Contract Messages¶

Instantiate¶

{
  "fee_bps": 50,
  "min_stake_threshold": "500000",
  "min_claim_threshold": "100000",
  "treasury_address": "cosmos1...",
  "compound_bps": 8000,
  "treasury_bps": 1000,
  "operations_address": "cosmos1...",
  "operations_bps": 1000,
  "jail_grace_period": 604800,
  "max_validators": 250
}

Sets the initial configuration. The sender becomes the admin. operations_address and operations_bps are optional (default 0). jail_grace_period (default: 604800 (7 days), set to 86400 (24 hours) on mainnet) and max_validators (default: 250) are also optional. compound_bps + treasury_bps + operations_bps must equal 10000.

Execute Messages¶

Registration¶

RegisterValidator¶

{ "register_validator": { "valoper_address": "cosmosvaloper1..." } }

Permissionless. Registers a bonded Cosmos Hub validator. Generates a deterministic referral ID derived from the valoper address. Rejects jailed, unbonded, non-existent, or already-registered validators.

DeactivateValidator¶

{ "deactivate_validator": { "valoper_address": "cosmosvaloper1..." } }

Admin only. Deactivates a validator: sets active = false, removes referral from index, redistributes pending fees proportionally to active validators. Sets deactivated_by_admin = true.

ReactivateValidator¶

{ "reactivate_validator": { "valoper_address": "cosmosvaloper1..." } }

Permissionless for auto-deactivated validators. Admin only for admin-deactivated validators. Checks that the validator is bonded on-chain. Restores the same referral ID.

RemoveValidator¶

{ "remove_validator": { "valoper_address": "cosmosvaloper1..." } }

Admin only. Permanently removes a deactivated validator from storage, freeing a registration slot. Cannot remove active validators - deactivate first.

Fee Operations¶

ReceiveFees¶

{ "receive_fees": { "referral_id": "abc12345" } }

Must include only uatom in the transaction funds (rejects if any other denom is included). Adds the sent ATOM to the pending balance for the validator associated with the given referral ID. Rejects inactive validators (their referral ID is removed from the index on deactivation).

BatchReceiveFees¶

{ "batch_receive_fees": { "entries": [
  { "referral_id": "abc12345", "amount": "1000000" },
  { "referral_id": "def67890", "amount": "500000" }
] } }

Batch version of ReceiveFees. Distributes the attached uatom across multiple referrals in a single contract call. The sum of all entry amounts must exactly equal the attached funds. Each entry validates the referral exists and the validator is active, same as individual ReceiveFees. If any entry fails validation, the entire call reverts.

StakePending¶

{ "stake_pending": { "validator": null } }

Permissionless. Delegates pending ATOM to validators. Pass null to process all validators with pending fees above min_stake_threshold, or pass a specific valoper address to process just that one. Checks bonded status before each delegation - auto-deactivates jailed/unbonded validators and redistributes their pending fees.

Staking Maintenance¶

ClaimRewards¶

{ "claim_rewards": { "limit": 50 } }

Permissionless. Claims staking rewards from all delegations (up to limit). Rewards land in the contract's balance, ready for compounding.

CompoundRewards¶

{ "compound_rewards": { "limit": null } }

Permissionless. Calculates available balance (bank balance minus pending fees), sends treasury_bps share to treasury, sends operations_bps share to the operations address, and restakes the remaining compound_bps share proportionally to existing delegations.

The optional limit parameter enables paginated compounding for large validator sets. When limit is provided, the operation processes validators in batches (sorted by address) to stay within block gas limits. The first call takes the treasury and operations cuts and delegates to the first limit validators. Subsequent calls continue from the last processed validator address until all eligible validators are processed. When limit is null, all validators are processed in a single transaction.

Rebalance¶

{ "rebalance": { "limit": 50 } }

Permissionless. Checks delegation targets for jailed/unbonded status. Jailed validators get a grace period (jail_grace_period, default 7 days, set to 24 hours on mainnet). After grace period or if unbonded: spreads delegation across the 3 smallest active validators, auto-deactivates, redistributes pending fees.

Reconcile¶

{ "reconcile": {} }

Permissionless. Syncs the contract's total_staked records for all validators with actual on-chain delegation amounts. Corrects drift from slashing or failed transactions. The limit parameter is accepted for compatibility but ignored - all delegations are always reconciled.

Admin Operations¶

Undelegate¶

{ "undelegate": { "validator": "cosmosvaloper1...", "amount": "1000000" } }

Admin only. Initiates undelegation from a specific validator. Subject to the 21-day unbonding period.

ClearCompoundState¶

{ "clear_compound_state": {} }

Admin only. Clears stuck compound pagination state. Used if a paginated compound sequence is interrupted and needs to be reset so a fresh compound can begin.

UpdateConfig¶

{
  "update_config": {
    "fee_bps": 50,
    "min_stake_threshold": "1000000",
    "min_claim_threshold": "100000",
    "paused": false,
    "treasury_address": "cosmos1...",
    "compound_bps": 8000,
    "treasury_bps": 1000,
    "operations_address": "cosmos1...",
    "operations_bps": 1000,
    "jail_grace_period": 604800,
    "max_validators": 250
  }
}

Admin only. Updates any subset of configuration parameters. All fields are optional - only provided fields are updated. Validates compound_bps + treasury_bps + operations_bps == 10000 and fee_bps <= 10000. If operations_bps is greater than zero, operations_address must be set.

ProposeAdmin¶

{ "propose_admin": { "new_admin": "cosmos1..." } }

Admin only. First step of two-step admin transfer. Sets pending_admin.

AcceptAdmin¶

{ "accept_admin": {} }

Pending admin only. Second step of admin transfer. Caller must be the pending_admin. Transfers admin role.

Query Messages¶

Config¶

{ "config": {} }

Returns the full contract configuration:

ConfigResponse {
    admin: String,
    pending_admin: Option<String>,
    fee_bps: u16,
    min_stake_threshold: Uint128,
    min_claim_threshold: Uint128,
    paused: bool,
    treasury_address: String,
    compound_bps: u16,
    treasury_bps: u16,
    operations_address: Option<String>,
    operations_bps: u16,
    jail_grace_period: u64,
    max_validators: u32,
}

Validator¶

{ "validator": { "valoper": "cosmosvaloper1..." } }

Returns info for a single validator by valoper address:

ValidatorInfo {
    valoper: String,
    referral_id: String,
    registered_at: u64,
    total_staked: Uint128,
    active: bool,
    deactivated_by_admin: bool,
}

ValidatorByReferral¶

{ "validator_by_referral": { "referral_id": "abc12345" } }

Returns info for a validator by referral ID. Same response as Validator.

Leaderboard¶

{ "leaderboard": { "start_after": null, "limit": 100 } }

Returns active validators sorted by total_staked (descending). Supports pagination via start_after (valoper address).

AllValidators¶

{ "all_validators": { "start_after": null, "limit": 100 } }

Returns all registered validators (active and inactive). Supports pagination.

GlobalStats¶

{ "global_stats": {} }

Returns protocol-wide statistics:

GlobalStats {
    total_atom_staked: Uint128,
    total_validators: u32,
}

PendingFees¶

{ "pending_fees": { "validator": null } }

Returns pending (not yet staked) fee balances. Pass null for all validators, or a specific valoper address for one.

PendingFee {
    validator: String,
    amount: Uint128,
}

CompoundState¶

{ "compound_state": {} }

Returns the current compound pagination state, or null if no paginated compound is in progress:

CompoundState {
    remaining: Uint128,      // ATOM left to delegate in remaining pages
    cursor: Option<String>,  // Last processed validator address
    eligible_count: u32,     // Total eligible validators at start of compound
    processed_count: u32,    // Validators processed so far
}

Used to check whether a paginated compound sequence is in progress and how much work remains.

RecentStakeEvents¶

{ "recent_stake_events": { "limit": 10 } }

Returns the most recent stake events (max 100 stored):

StakeEvent {
    validator: String,
    amount: Uint128,
    timestamp: u64,
}