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
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 |
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 |
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:
- Scores all eligible validators
- Filters by the agent’s tier
- Selects the top N validators (default: 5, max: 10)
- Distributes the amount proportionally to score, with a 40% max cap per validator
- Ensures each allocation meets the minimum stake requirement
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