Parachain Staking

Contents

• Staking Architecture
• Common Operations
• Staking Parameters
• Reward Distribution
• Testing Staking
• Debugging Staking Issues

Staking Architecture

Core Components

Key Concepts

• Collators: Block producers that stake tokens
• Delegators: Token holders who delegate to collators
• Rounds: Fixed-length periods for reward distribution
• Commission: Percentage collators take from block rewards

Storage Layout

// Key storage items in pallet-parachain-staking
pub type CollatorCommission<T> = StorageValue<_, Perbill>;
pub type TotalSelected<T> = StorageValue<_, u32>;
pub type Round<T> = StorageValue<_, RoundInfo>;

pub type CandidateInfo<T> = StorageMap<_, Twox64Concat, AccountId, CandidateMetadata>;
pub type DelegatorState<T> = StorageMap<_, Twox64Concat, AccountId, Delegator>;
pub type TopDelegations<T> = StorageMap<_, Twox64Concat, AccountId, Delegations>;
pub type BottomDelegations<T> = StorageMap<_, Twox64Concat, AccountId, Delegations>;

pub type AtStake<T> = StorageDoubleMap<_, Twox64Concat, RoundIndex, Twox64Concat, AccountId, CollatorSnapshot>;
pub type DelayedPayouts<T> = StorageMap<_, Twox64Concat, RoundIndex, DelayedPayout>;

Common Operations

Query Staking State

// Get collator info
const candidateInfo = await api.query.parachainStaking.candidateInfo(collatorAddress);

// Get delegator state
const delegatorState = await api.query.parachainStaking.delegatorState(delegatorAddress);

// Get current round
const round = await api.query.parachainStaking.round();

// Get selected candidates for current round
const selectedCandidates = await api.query.parachainStaking.selectedCandidates();

Delegate via Precompile

// IParachainStaking interface
interface IParachainStaking {
    function delegate(
        address candidate,
        uint256 amount,
        uint256 candidateDelegationCount,
        uint256 delegatorDelegationCount
    ) external;

    function delegatorBondMore(address candidate, uint256 more) external;

    function scheduleDelegatorBondLess(address candidate, uint256 less) external;

    function executeDelegationRequest(address delegator, address candidate) external;

    function cancelDelegationRequest(address candidate) external;
}

Delegate via Substrate

// Join as delegator
pallet_parachain_staking::Call::delegate {
    candidate: collator_account,
    amount: 1_000_000_000_000_000_000, // 1 GLMR
    candidate_delegation_count: 100,
    delegation_count: 10,
}

// Bond more to existing delegation
pallet_parachain_staking::Call::delegator_bond_more {
    candidate: collator_account,
    more: 500_000_000_000_000_000, // 0.5 GLMR
}

Staking Parameters

Network-Specific Configuration

Runtime Configuration

// runtime/moonbase/lib.rs
parameter_types! {
    pub const MinCollatorStk: u128 = 1_000 * UNIT;
    pub const MinDelegation: u128 = 1 * UNIT;
    pub const MaxTopDelegationsPerCandidate: u32 = 300;
    pub const MaxBottomDelegationsPerCandidate: u32 = 50;
    pub const MaxDelegationsPerDelegator: u32 = 100;
    pub const DefaultBlocksPerRound: u32 = 300;
    pub const RewardPaymentDelay: u32 = 2;
}

impl pallet_parachain_staking::Config for Runtime {
    type RuntimeEvent = RuntimeEvent;
    type Currency = Balances;
    type MonetaryGovernanceOrigin = EnsureRoot<AccountId>;
    type MinBlocksPerRound = ConstU32<10>;
    type DefaultBlocksPerRound = DefaultBlocksPerRound;
    type RewardPaymentDelay = RewardPaymentDelay;
    type MinSelectedCandidates = ConstU32<8>;
    type MaxTopDelegationsPerCandidate = MaxTopDelegationsPerCandidate;
    type MaxBottomDelegationsPerCandidate = MaxBottomDelegationsPerCandidate;
    type MaxDelegationsPerDelegator = MaxDelegationsPerDelegator;
    type MinCollatorStk = MinCollatorStk;
    type MinCandidateStk = MinCollatorStk;
    type MinDelegation = MinDelegation;
    type WeightInfo = pallet_parachain_staking::weights::SubstrateWeight<Runtime>;
    // ...
}

Reward Distribution

Round Lifecycle

Round N Start
    │
    ▼
Block Production (collators earn points)
    │
    ▼
Round N End
    │
    ▼
Round N+1 Start
    │
    ▼
Round N-1 Rewards Distributed (after delay)

Reward Calculation

// Simplified reward calculation
fn calculate_rewards(
    total_reward: Balance,
    collator: &CollatorSnapshot,
) -> (Balance, Vec<(AccountId, Balance)>) {
    // Collator gets commission
    let commission = total_reward * collator.commission;
    let delegator_pool = total_reward - commission;

    // Self-bond portion
    let collator_self_reward = delegator_pool * collator.bond / collator.total;

    // Delegator portions
    let delegator_rewards: Vec<_> = collator.delegations.iter()
        .map(|d| {
            let share = delegator_pool * d.amount / collator.total;
            (d.owner.clone(), share)
        })
        .collect();

    (commission + collator_self_reward, delegator_rewards)
}

Testing Staking

Unit Tests

// pallets/parachain-staking/src/tests.rs
#[test]
fn delegate_works() {
    ExtBuilder::default()
        .with_balances(vec![(1, 1000), (2, 1000)])
        .with_candidates(vec![(1, 500)])
        .build()
        .execute_with(|| {
            assert_ok!(ParachainStaking::delegate(
                RuntimeOrigin::signed(2),
                1,    // candidate
                100,  // amount
                1,    // candidate delegation count
                0,    // delegator delegation count
            ));

            assert_eq!(
                ParachainStaking::delegator_state(2).unwrap().total(),
                100
            );
        });
}

Integration Tests

// test/suites/dev/moonbase/test-staking/test-staking-delegate.ts
describeSuite({
  id: "D010501",
  title: "Staking - Delegation",
  foundationMethods: "dev",
  testCases: ({ context, it }) => {
    it({
      id: "T01",
      title: "Should delegate to collator via precompile",
      test: async () => {
        const { result } = await context.createBlock(
          context.createTxn!({
            to: PRECOMPILE_STAKING_ADDRESS,
            data: encodeFunctionData({
              abi: stakingAbi,
              functionName: "delegate",
              args: [collator, amount, candidateCount, delegatorCount],
            }),
          })
        );

        expect(result?.successful).toBe(true);
      },
    });
  },
});

Debugging Staking Issues

Common Issues

Inspect Staking State

// Check if delegator is in top delegations
const topDelegations = await api.query.parachainStaking.topDelegations(collator);
const isInTop = topDelegations.unwrap().delegations.some(
  d => d.owner.toString() === delegator
);

// Check pending requests
const requests = await api.query.parachainStaking.delegationScheduledRequests(collator);
const pendingRequest = requests.find(
  r => r.delegator.toString() === delegator
);

Debug Logging

// Add to pallet for debugging
log::debug!(
    target: "parachain-staking",
    "Delegation: delegator={:?}, candidate={:?}, amount={:?}",
    delegator, candidate, amount
);

Key Files

• Pallet: pallets/parachain-staking/src/lib.rs
• Types: pallets/parachain-staking/src/types.rs
• Delegation: pallets/parachain-staking/src/delegation_requests.rs
• Rewards: pallets/parachain-staking/src/inflation.rs
• Precompile: precompiles/parachain-staking/src/lib.rs
• Tests: test/suites/dev/moonbase/test-staking/