> ## Documentation Index
> Fetch the complete documentation index at: https://docs.inkwell.finance/llms.txt
> Use this file to discover all available pages before exploring further.

# Validator Scoring

> How Inkwell scores and ranks IKA validators.

# Validator Scoring

The allocation engine ranks validators using a composite score that balances yield, reliability, and decentralization.

## Scoring factors

| Factor                     | Weight | What it measures                                                                    |
| -------------------------- | ------ | ----------------------------------------------------------------------------------- |
| **APY**                    | High   | Historical staking yield based on exchange rate changes over recent epochs          |
| **Commission**             | Medium | Validator's fee — lower commission means more rewards pass through to stakers       |
| **Uptime / participation** | Medium | Whether the validator has been active and producing blocks consistently             |
| **Stake concentration**    | Low    | How much of the network's total stake the validator holds — favors decentralization |

Validators with zero or negative APY, excessive commission, or prolonged inactivity are filtered out entirely.

## Tier-based visibility

Not all agents and users see the same validator set:

| Tier                 | Validators returned       |
| -------------------- | ------------------------- |
| **free**             | Top 10 by composite score |
| **builder**          | Top 25                    |
| **pro / enterprise** | All scored validators     |

This tiering applies to the `GET /validators/scored` API endpoint. The public `GET /validators` endpoint returns the full unscored validator set regardless of tier.

## Allocation strategy

When computing an allocation (`POST /allocate`), the engine:

1. Scores all eligible validators
2. Filters by the agent's tier
3. Selects the top N validators (default: 5, max: 10)
4. Distributes the amount proportionally to score, with a **40% max cap** per validator
5. Ensures each allocation meets the minimum stake requirement

The result is a diversified position that maximizes expected yield while limiting single-validator risk.

## Rebalance triggers

The rebalance planner (`POST /rebalance-plan`) compares current positions against what the allocation engine would recommend today. It generates steps when:

* A validator's APY has dropped significantly relative to alternatives
* A validator's commission has increased
* Stake has become too concentrated in one validator
* New high-performing validators have entered the active set

The plan respects the 1-epoch cooldown — unstake steps are ordered before stake steps, with a note about the required wait.