Interacting with the Staking Precompile¶
Introduction¶
Moonbeam uses a Delegated Proof of Stake system through the parachain staking pallet, allowing token holders (delegators) to express exactly which collator candidates they would like to support and with what quantity of stake. The design of the parachain staking pallet is such that it enforces shared risk/reward on chain between delegators and candidates.
The staking module is coded in Rust and it is part of a pallet that is normally not accessible from the Ethereum side of Moonbeam. However, a staking precompile allows developers to access the staking features using the Ethereum API in a precompiled contract located at address:
0x0000000000000000000000000000000000000800
0x0000000000000000000000000000000000000800
0x0000000000000000000000000000000000000800
This guide will cover the available methods in the staking precompile interface. In addition, it will show you how to interact with the staking pallet through the staking precompile and the Ethereum API. The examples in this guide are done on Moonbase Alpha, but they can be adapted for Moonbeam or Moonriver.
Exit Delays¶
Some of the staking pallet extrinsics include exit delays that you must wait before the request can be executed. The exit delays to note are as follows:
Variable | Value |
---|---|
Decrease candidate bond | 28 rounds (168 hours) |
Decrease delegator bond | 28 rounds (168 hours) |
Revoke delegation | 28 rounds (168 hours) |
Leave candidates | 28 rounds (168 hours) |
Leave delegators | 28 rounds (168 hours) |
Variable | Value |
---|---|
Decrease candidate bond | 24 rounds (48 hours) |
Decrease delegator bond | 24 rounds (48 hours) |
Revoke delegation | 24 rounds (48 hours) |
Leave candidates | 24 rounds (48 hours) |
Leave delegators | 24 rounds (48 hours) |
Variable | Value |
---|---|
Decrease candidate bond | 2 rounds (4 hours) |
Decrease delegator bond | 2 rounds (4 hours) |
Revoke delegation | 2 rounds (4 hours) |
Leave candidates | 2 rounds (4 hours) |
Leave delegators | 2 rounds (4 hours) |
Parachain Staking Solidity Interface¶
StakingInterface.sol is an interface through which Solidity contracts can interact with parachain-staking. The beauty is that Solidity developers don’t have to learn the Substrate API. Instead, they can interact with staking functions using the Ethereum interface they are familiar with.
The Solidity interface includes the following functions:
- is_delegator(address delegator) — read-only function that checks whether the specified address is currently a staking delegator. Uses the
delegatorState
method of the staking pallet - is_candidate(address candidate) — read-only function that checks whether the specified address is currently a collator candidate. Uses the
candidateState
method of the staking pallet - is_selected_candidate(address candidate) - read-only function that checks whether the specified address is currently part of the active collator set. Uses the
selectedCandidates
method of the staking pallet - points(uint256 round) - read-only function that gets the total points awarded to all collators in a given round. Uses the
points
method of the staking pallet - min_delegation() — read-only function that gets the minimum delegation amount. Uses the
minDelegation
method of the staking pallet - candidate_count() - read-only function that gets the current amount of collator candidates. Uses the
candidatePool
method of the staking pallet - round() - read-only function that returns the current round number. Uses the
round
method of the staking pallet - candidate_delegation_count(address candidate) - read-only function that returns the number of delegations for the specified collator candidate address. Uses the
candidateInfo
method of the staking pallet - delegator_delegation_count(address delegator) - read-only function that returns the number of delegations for the specified delegator address. Uses the
delegatorState
method of the staking pallet - selected_candidates() - read-only function that gets the selected candidates for the current round. Uses the
selectedCandidates
method of the staking pallet - delegation_request_is_pending(address delegator, address candidate) - returns a boolean to indicate whether there is a pending delegation request made by a given delegator for a given candidate
- candidate_exit_is_pending(address candidate) - returns a boolean to indicate whether a pending exit exists for a specific candidate. Uses the
candidateInfo
method of the staking pallet - candidate_request_is_pending(address candidate) - returns a boolean to indicate whether there is a pending bond less request made by a given candidate. Uses the
candidateInfo
method of the staking pallet - join_candidates(uint256 amount, uint256 candidateCount) — allows the account to join the set of collator candidates with a specified bond amount and the current candidate count. Uses the
joinCandidates
method of the staking pallet - schedule_leave_candidates(uint256 candidateCount) - schedules a request for a candidate to remove themselves from the candidate pool. Scheduling the request does not automatically execute it. There is an exit delay that must be waited before you can execute the request via the
execute_leave_candidates
extrinsic. Uses thescheduleLeaveCandidates
method of the staking pallet - execute_leave_candidates(address candidate, uint256 candidateDelegationCount) - executes the due request to leave the set of collator candidates. Uses the
executeLeaveCandidates
method of the staking pallet - cancel_leave_candidates(uint256 candidateCount) - allows a candidate to cancel a pending scheduled request to leave the candidate pool. Given the current number of candidates in the pool. Uses the
cancelLeaveCandidates
method of the staking pallet - go_offline() — temporarily leave the set of collator candidates without unbonding. Uses the
goOffline
method of the staking pallet - go_online() — rejoin the set of collator candidates after previously calling
go_offline()
. Uses thegoOnline
method of the staking pallet - candidate_bond_more(uint256 more) — collator candidate increases bond by specified amount. Uses the
candidateBondMore
method of the staking pallet - schedule_candidate_bond_less(uint256 less) - schedules a request to decrease a candidates bond by a specified amount. Scheduling the request does not automatically execute it. There is an exit delay that must be waited before you can execute the request via the
execute_candidate_bond_request
extrinsic. Uses thescheduleCandidateBondLess
method of the staking pallet - execute_candidate_bond_less(address candidate) - executes any due requests to decrease a specified candidates bond amount. Uses the
executeCandidateBondLess
method of the staking pallet - cancel_candidate_bond_less() - allows a candidate to cancel a pending scheduled request to decrease a candidates bond. Uses the
cancelCandidateBondLess
method of the staking pallet - delegate(address candidate, uint256 amount, uint256 candidateDelegationCount, uint256 delegatorDelegationCount) — if the caller is not a delegator, this function adds them to the set of delegators. If the caller is already a delegator, then it adjusts their delegation amount. Uses the
delegate
method of the staking pallet - schedule_leave_delegators() — schedules a request to leave the set of delegators and revoke all ongoing delegations. Scheduling the request does not automatically execute it. There is an exit delay that must be waited before you can execute the request via the
execute_leave_delegators
extrinsic. Uses thescheduleLeaveDelegators
method of the staking pallet - execute_leave_delegators(address delegator, uint256 delegatorDelegationCount) - executes the due request to leave the set of delegators and revoke all delegations. Uses the
executeLeaveDelegators
method of the staking pallet - cancel_leave_delegators() - cancels a pending scheduled request to leave the set of delegators. Uses the
cancelLeaveDelegators
method of the staking pallet - schedule_revoke_delegation(address candidate) — schedules a request to revoke a delegation given the address of a candidate. Scheduling the request does not automatically execute it. There is an exit delay that must be waited before you can execute the request via the
execute_delegation_request
extrinsic. Uses thescheduleRevokeDelegation
method of the staking pallet - delegator_bond_more(address candidate, uint256 more) — delegator increases bond to a collator by specified amount. Uses the
delegatorBondMore
method of the staking pallet - schedule_delegator_bond_less(address candidate, uint256 less) — schedules a request for a delegator to bond less with respect to a specific candidate. Scheduling the request does not automatically execute it. There is an exit delay that must be waited before you can execute the request via the
execute_delegation_request
extrinsic. Uses thescheduleDelegatorBondLess
method of the staking pallet - execute_delegation_request(address delegator, address candidate) - executes any due delegation requests provided the address of a delegator and a candidate. Uses the
executeDelegationRequest
method of the staking pallet - cancel_delegation_request(address candidate) - cancels any pending delegation requests provided the address of a candidate. Uses the
cancelDelegationRequest
method of the staking pallet
The following methods are deprecated and will be removed in the future:
- is_nominator(address nominator) — read-only function that checks whether the specified address is currently a staking delegator. Use
is_delegator
instead - min_nomination() — read-only function that gets the minimum delegation amount. Use
min_delegation
instead - collator_nomination_count(address collator) - read-only function that returns the number of delegations for the specified collator address. Use
candidate_delegation_count
instead - nominator_nomination_count(address nominator) - read-only function that returns the number of delegations for the specified delegator address. Use
delegator_delegation_count
instead - leave_candidates(uint256 amount, uint256 candidateCount) — immediately removes the account from the candidate pool to prevent others from selecting it as a collator and triggers unbonding. Use
schedule_leave_candidates
andexecute_leave_candidates
instead - candidate_bond_less(uint256 less) — collator candidate decreases bond by specified amount. Use
schedule_candidate_bond_less
andexecute_candidate_bond_less
instead - nominate(address collator, uint256 amount, uint256 collatorNominationCount, uint256 nominatorNominationCount) — if the caller is not a delegator, this function adds them to the set of delegators. If the caller is already a delegator, then it adjusts their delegation amount. Use
delegate
instead - leave_nominators(uint256 nominatorNominationCount) — leave the set of delegators and revoke all ongoing delegations. Use
schedule_leave_delegators
andexecute_leave_delegators
instead - revoke_nominations(address collator) — revoke a specific delegation. Use
schedule_revoke_delegation
andexecute_delegation_request
instead - nominator_bond_more(address collator, uint256 more) — delegator increases bond to a collator by specified amount. Use
delegator_bond_more
instead - nominator_bond_less(address collator, uint256 less) — delegator decreases bond to a collator by specified amount. Use
schedule_delegator_bond_less
andexecute_delegation_request
instead
Interact with the Solidity Interface¶
Checking Prerequisites¶
The below example is demonstrated on Moonbase Alpha, however, similar steps can be taken for Moonbeam and Moonriver.
- Have MetaMask installed and connected to Moonbase Alpha
- Have an account with at least
1
token. You can get DEV tokens for testing on Moonbase Alpha once every 24 hours from the Moonbase Alpha Faucet
Note
The example below requires more than 1
token due to the minimum delegation amount plus gas fees. If you need more than the faucet dispenses, please contact us on Discord and we will be happy to help you.
Remix Set Up¶
- Get a copy of StakingInterface.sol
- Copy and paste the file contents into a Remix file named
StakingInterface.sol
Compile the Contract¶
- Click on the Compile tab, second from top
- Then to compile the interface, click on Compile StakingInterface.sol
Access the Contract¶
- Click on the Deploy and Run tab, directly below the Compile tab in Remix. Note: you are not deploying a contract here, instead you are accessing a precompiled contract that is already deployed
- Make sure Injected Web3 is selected in the ENVIRONMENT drop down
- Ensure ParachainStaking - StakingInterface.sol is selected in the CONTRACT dropdown. Since this is a precompiled contract there is no need to deploy, instead you are going to provide the address of the precompile in the At Address Field
- Provide the address of the staking precompile for Moonbase Alpha:
0x0000000000000000000000000000000000000800
and click At Address - The Parachain Staking precompile will appear in the list of Deployed Contracts
Delegate a Collator¶
For this example, you are going to be delegating a collator on Moonbase Alpha. Delegators are token holders who stake tokens, vouching for specific candidates. Any user that holds a minimum amount of 1 token in their free balance can become a delegator.
You can do your own research and select the candidate you desire. For this guide, the following candidate address will be used: 0x4c5A56ed5A4FF7B09aA86560AfD7d383F4831Cce
.
In order to delegate a candidate, you'll need to determine the current candidate delegation count and delegator delegation count. The candidate delegation count is the number of delegations backing a specific candidate. The delegator delegation account is the number of delegations made by the delegator.
To obtain the candidate delegator count, you can call a function that the staking precompile provides. Expand the PARACHAINSTAKING contract found under the Deployed Contracts list, then:
- Find and expand the candidate_delegation_count function
- Enter the candidate address (
0x4c5A56ed5A4FF7B09aA86560AfD7d383F4831Cce
) - Click call
- After the call is complete, the results will be displayed
If you don't know your existing number of delegations, you can easily get them by following these steps:
- Find and expand the delegator_delegation_count function
- Enter your address
- Click call
- After the call is complete, the results will be displayed
Now that you have obtained the candidate delegator count and your number of existing delegations, you have all of the information you need to delegate a candidate. To get started:
- Find and expand the delegate function
- Enter the candidate address you would like to delegate (
0x4c5A56ed5A4FF7B09aA86560AfD7d383F4831Cce
) - Provide the amount to delegate in Wei. There is a minimum of
1
token to delegate, so the lowest amount in Wei is5000000000000000000
- Enter the delegation count for the candidate
- Enter your delegation count
- Press transact
- MetaMask will pop-up, you can review the details and confirm the transaction
Verify Delegation¶
To verify your delegation was successful, you can check the chain state in Polkadot.js Apps. First, add your MetaMask address to the address book in Polkadot.js Apps.
- Navigate to Accounts and then Address Book
- Click on Add contact
- Add your MetaMask address
- Provide a nickname for the account
- Click Save
To verify your delegation was successful, head to Polkadot.js Apps and navigate to Developer and then Chain State
- Select the parachainStaking pallet
- Select the delegatorState query
- Enter your address
- Optionally, you can enable the include option slider if you want to provide a specific blockhash to query
- Click the + button to return the results and verify your delegation
Note
You do not have to enter anything in the blockhash to query at field if you are looking for an overview of your delegations.
Revoke a Delegation¶
As of runtime version 1001, there have been significant changes to the way users can interact with various staking features. Including the way staking exits are handled.
Exits now require you to schedule a request to exit or revoke a delegation, wait a delay period, and then execute the request.
To revoke a delegation for a specific candidate and receive your tokens back, you can use the scheduleRevokeDelegation
extrinsic. Scheduling a request does not automatically revoke your delegation, you must wait an exit delay, and then execute the request by using the executeDelegationRequest
method.
To revoke a delegation and receive your tokens back, head back over to Remix, then:
- From the list of Deployed Contracts, find and expand the schedule_revoke_delegation function
- Enter the candidate address you would like to revoke the delegation for
- Click transact
- MetaMask will pop, you can review the transaction details, and click Confirm
Once the transaction is confirmed, you must wait the duration of the exit delay before you can execute and revoke the delegation request. If you try to revoke it before the exit delay is up, your extrinsic will fail.
After the exit delay has passed, you can go back to Remix and follow these steps to execute the due request:
- From the list of Deployed Contracts, find and expand the execute_delegation_request function
- Enter the address of the delegator you would like to revoke the delegation for
- Enter the candidate address you would like to revoke the delegation from
- Click transact
- MetaMask will pop, you can review the transaction details, and click Confirm
After the call is complete, the results will be displayed and the delegation will be revoked for the given delegator and from the specified candidate. You can also check your delegator state again on Polkadot.js Apps to confirm.
If for any reason you need to cancel a pending scheduled request to revoke a delegation, you can do so by following these steps in Remix:
- From the list of Deployed Contracts, find and expand the cancel_delegation_request function
- Enter the candidate address you would like to cancel the pending request for
- Click transact
- MetaMask will pop, you can review the transaction details, and click Confirm
You can check your delegator state again on Polkadot.js Apps to confirm that your delegation is still in tact.