Delegating with the Casper Client
This document details a workflow where an account holder on a Casper network can delegate tokens to a validator.
Prerequisites
- You meet all prerequisites listed here, including having a valid
node-address
and the Casper command-line client - You have previously deployed a smart contract to a Casper network
The workflow will take you through two additional prerequisites before sending the delegation request:
- Building the delegation Wasm to execute on the network
- Getting the public key of a validator on the network
Building The Delegation Wasm
Obtain the delegate.wasm
by cloning the casper-node repository.
git clone https://github.com/casper-network/casper-node
Prepare the Rust environment and then build the contracts using the Makefile provided in the repository.
cd casper-node
make setup-rs
make build-contracts-rs
Once you build the contracts, you can use the delegate.wasm
to create a deploy that will initiate the delegation process. The Wasm can be found in this directory: target/wasm32-unknown-unknown/release/
.
ls target/wasm32-unknown-unknown/release/delegate.wasm
Acquiring a Validator's Public Key
The official Casper Testnet and Mainnet provide a browser-based block explorer to look up the list of validators:
You will see a list of validators present on the network and their total stake (including tokens from other delegators).
You can click on any validator listed to see more information about the validator, including the validator's personal stake.
As a prospective delegator, selecting a trustworthy validator with a favorable rate is essential. Each validator shows the delegation rate, which is a percentage of your reward share that the validator will retain. Thus, a 10% rate implies that the validator will retain 10% of your reward share. Please do your due diligence before staking your tokens with a validator.
Note the PublicKey
of the validator you have selected to delegate your tokens.
Suppose you observe your delegation request in the bid structure but do not see the associated validator key in the era_validators
structure. In that case, the validator you selected is not part of the current validator set. In this event, your tokens will only be earning rewards if you un-delegate, wait through the unbonding period, and re-delegate to another validator.
Additionally, any rewards earned are re-delegated by default to the validator from the initial delegation request. Therefore at the time of un-delegation, you should consider un-delegating the initial amount plus any additional rewards earned through the delegation process.
The active validator set constantly rotates; therefore, when delegating to a validator, remember that the validator you selected may have been rotated out of the set.
Sending the Delegation Request
We recommend testing the following steps on the official Testnet before performing them in a live environment like the Casper Mainnet.
In this example, we use the Casper client to send a deploy containing the delegate.wasm
to the network to initiate the delegation process.
casper-client put-deploy \
--node-address http://<peer-ip-address>:7777 \
--chain-name casper-test \
--session-path <path-to-wasm>/delegate.wasm \
--payment-amount 5000000000 \
--session-arg "validator:public_key='<hex-encoded-validator-public-key>'" \
--session-arg "amount:u512='<amount-to-delegate>'" \
--session-arg "delegator:public_key='<hex-encoded-public-key>'" \
--secret-key <delegator-secret-key>.pem
Note The delegator's public key and the secret key that signs the deploy must be part of the same account key pair.
Request fields:
node-address
- An IP address of a node on the networksecret-key
- Path to the secret key filechain-name
- Name of the chain, to avoid the deploy from being accidentally or maliciously included in a different chain- The chain-name for Testnet is casper-test
- The chain-name for Mainnet is casper
session-path
- The path to where thedelegate.wasm
is locatedsession-arg
- The arguments to thedelegate
request- The argument
validator
is the public key of the validator to whom the tokens will be delegated - The argument
amount
is the number of tokens to be delegated - The argument
delegator
is the public key of the account delegating tokens to a validator
- The argument
Important response fields:
"result"."deploy_hash"
- the address of the executed delegation request.
Save the returned deploy_hash from the output to query information about the delegation deploy later.
Refer to the Deploy Status section to learn how to confirm that your deploy was executed successfully.
Confirming the Delegation
A Casper network maintains an auction where validators bid on slots to become part of the active validator set. Delegation rewards are only earned for a validator who has won the auction and is part of the active set. Thus to ensure the delegated tokens can earn rewards, we must first check that:
- Our delegation is part of the bid to the auction
- The validator is part of the active validator set
Once the deploy has been processed, we can query the auction for information to confirm our delegation. We can use the Casper command-line client to create an RPC request with the following query:
casper-client get-auction-info \
--node-address http://<peer-ip-address>:7777
Request fields:
node-address
- An IP address of a node on the network
The get-auction-info
call will return all the bids currently in the auction contract and the list of active validators for 4
future eras from the present era.
Below is a sample output:
"bids": [
{
"bid": {
"bonding_purse": "uref-a5ce7dbc5f7e02ef52048e64b2ff4693a472a1a56fe71e83b180cd33271b2ed9-007",
"delegation_rate": 1,
"delegators": [
{
"bonding_purse": "uref-ca9247ad56a4d5be70484303133e2d6db97f7d7385772155763749af98ace0b0-007",
"delegatee": "0102db4e11bccb3f9d823c82b9389625d383867d00d09b343043cdbe5ca56dd1fd",
"public_key": "010c7fef89bf1fc38363bd2ec20bbfb5e1152d6a9579c8847615c59c7e461ece89",
"staked_amount": "1"
},
{
"bonding_purse": "uref-38a2e9cad51b380e478c9a325578f4bbdaa0337b99b9ab9bf1dc2a114eb948b9-007",
"delegatee": "0102db4e11bccb3f9d823c82b9389625d383867d00d09b343043cdbe5ca56dd1fd",
"public_key": "016ebb38d613f2550e7c21ff9d99f6249b4ae5fb9e30938f6ece2d84a22a36b035",
"staked_amount": "478473232415318176495746923"
}
],
"inactive": false,
"staked_amount": "493754513995516852173468935"
},
"public_key": "0102db4e11bccb3f9d823c82b9389625d383867d00d09b343043cdbe5ca56dd1fd"
},
The delegation request has been processed successfully if your public key and associated amount appear in the bid
data structure. However, this does not mean the associated validator is part of the validator set, so you must check the validator status.
Checking Validator Status
The auction maintains a field called era_validators
, which contains the validator information for 4 future eras from the current era. An entry for a specific era lists the PublicKeys
of the active validators for that era, along with their stake in the network.
If a validator is part of the set, its public key will be in the era_validators
field as part of the Auction
data structure. We can use the Casper command-line client to create an RPC request to obtain auction information and assert that the selected validator is part of the active validator set.
casper-client get-auction-info \
--node-address http://<peer-ip-address>:7777
Request fields:
node-address
- An IP address of a node on the network
Important Response fields:
In the response, check the "auction_state"."era_validators"
structure, which should contain the public key of the selected validator for the era in which the validator will be active.
Below is an example of the era_validators
structure:
"block_height":105,
"era_validators":[
{
"era_id":9,
"validator_weights":[
{
"public_key":"0102db4e11bccb3f9d823c82b9389625d383867d00d09b343043cdbe5ca56dd1fd",
"weight":"648151805935226166098427654"
},
{
"public_key":"01aa67009b37a23c7ad0ca632da5da239d5db46067d4b34125f61b04611f610baf",
"weight":"648151805938466925128109996"
},
{
"public_key":"01b7afa2beeddffd13458b763d7a00259f7dc0fa45498dfed05b4d7df4b7d65e2c",
"weight":"648151805935226166098427656"
},
{
"public_key":"01ca5463dac047cbd750d97ee42dd810cf1e081ece7d83ae4fc03b25a9ecad3b6a",
"weight":"648151805938466925128109998"
},
{
"public_key":"01f4a7644695aa129eba09fb3f11d0277b2bea1a3d5bc1933bcda93fdb4ad17e55",
"weight":"648151805938466925128110000"
}
]
},
In the above example, we see the public keys of the active validators in Era 9
.
Note: Validators earn delegation rewards only when they are part of the active set. This information is time-sensitive; therefore, a validator selected today may not be part of the set tomorrow. Keep this in mind when creating a delegation request.