Skip to content

Validators

Registration

Any Cosmos Hub validator in bonded (active) status can be registered on Atom Circuit. Registration is permissionless - anyone can register any bonded validator.

How to Register

  1. Navigate to the Register page
  2. Enter the validator's address (starts with cosmosvaloper1)
  3. The app looks up the validator on-chain and checks if it is already registered
  4. If not registered and in the active set, click "Register Validator"
  5. Sign the transaction with any Cosmos wallet (Keplr, Cosmostation, etc.)

The contract verifies the validator exists and is in the active set on-chain. Jailed, inactive, non-existent, or already-registered validators are rejected. A unique referral ID is generated automatically.

Each registered validator gets a referral link:

https://atomcircuit.net/swap?ref={referral_id}

The referral ID is derived from the valoper address, so it never changes even if the validator is deactivated and reactivated.

Vanity Slugs

Validators can have human-readable slugs instead of the default referral ID:

https://atomcircuit.net/swap?ref=cosmostation
  • Vanity slugs are auto-generated from on-chain validator names
  • Multiple slugs can point to the same validator (old slugs are preserved if the validator changes its name)
  • If no slug exists, the default referral ID works directly (e.g., ?ref=a1b2c3d4)

Referral Expiry

When a user clicks a referral link, the referral is saved in their browser for 30 days. All swaps during that period are attributed to the validator.

To switch to a different validator's referral, simply visit the swap page through a new referral link. The new referral replaces the previous one.

Referral Tracking

When a user swaps through a referral link:

  1. The system records which validator's referral the user came through
  2. The swap is verified and fees are distributed to the staking contract for that validator

Swaps without a referral go to the "general" pool, which is split equally among all active validators.

Tiers

Validators are ranked by total ATOM staked through the protocol:

Tier Threshold
Titan 100,000+ ATOM
Giant 10,000+ ATOM
Core 1,000+ ATOM
Node 100+ ATOM
Planetoid Under 100 ATOM

Tiers are purely cosmetic - they reflect community engagement driving swap volume through each validator's referral link. Higher tiers indicate more community support.

Validator Lifecycle

graph LR
    R[Register] --> A[Active]
    A -->|jailed| G[Grace Period]
    G -->|unjails| A
    G -->|expires| D[Deactivated]
    A -->|admin| D
    D -->|reactivate| A
    D -->|remove| X[Removed]

Active

  • Referral link works
  • Receives attributed fees
  • Appears on leaderboard
  • ATOM is delegated to this validator

Jailed (Grace Period)

When a validator gets jailed on-chain, the contract does not immediately deactivate it. Instead:

  1. The automated rebalance cycle detects the jailed status
  2. A 24-hour grace period begins
  3. The validator has time to unjail before action is taken
  4. If the validator unjails within the grace period, nothing happens - business as usual

Auto-Deactivated

If the grace period expires and the validator is still jailed (or becomes unbonded):

  1. Existing delegation is spread across the 3 smallest active validators (self-balancing)
  2. Pending fees are redistributed proportionally (by total staked weight) to other active validators
  3. The referral link is disabled
  4. The validator is marked as inactive

Reactivation

Once an auto-deactivated validator unjails and returns to bonded status on-chain:

  • Anyone can reactivate the validator - it is permissionless
  • The contract verifies the validator is bonded on-chain
  • The same referral ID and link are restored
  • The validator appears on the leaderboard again

Admin Deactivation

The admin can deactivate any validator for cause:

  • Same effects as auto-deactivation (pending fees redistributed, referral link disabled)
  • Only the admin can reactivate an admin-deactivated validator

Removal

The admin can permanently remove a deactivated validator from storage:

  • Frees a registration slot
  • Cannot remove active validators - must deactivate first
  • All data for that validator is deleted