Bonding

A bonding request (or bidding in the validator auction) can only be sent once the node has completed the synchronization process. Bonding in Casper takes place through the auction contract via the add_bid.wasm contract. The auction runs for a future era, every era. There are 100 slots available, and the auction will take the top 100 bids and create the validator set for the future era.

Eras are approximately 2 hours long. The auction runs every era and selects the validator set for the era after the next, and runs at the end of each era. Therefore, the time for bid submission to inclusion in the validator set is a minimum of 2 hours. Bonding requests (bids) are transactions like any other. Because they are generic transactions, they are more resistant to censorship.

Security and Bonding

The most secure way to send a bonding transaction is to compile the contract and send the request to the network. Because the transaction authorizes the token to be locked into the auction contract, it's really important to compile the contract yourself. Here are the steps to do this:

• Visit Github and fork and clone the repository.
• Make sure that all dependencies are installed (documented on GitHub).
• Follow the instructions to build the contracts.
• Ensure that the keys you will use for bonding are available & have been funded.
• Create the bonding transaction & deploy it using the casper-client.
• Query the system to verify that your bid was accepted.
• Check the status of the auction to see if you have won a slot.

Build Add_Bid Contract

Because bonding transactions are generic transactions, it's necessary to build the contract that submits a bid. Clone the casper-node repository and build the contracts. To build contracts, set up Rust & install all dependencies.

Build the contracts in release mode.

$ make setup-rs
$ make build-client-contracts

Obtain the Casper Client

In this document, we will use the Rust Casper client to send the bonding request. You can find the client on crates.io. or you can obtain it by following these steps..

Run the commands below to install the Casper client on most flavors of Linux and macOS. You will need the nightly version of the compiler.

rustup toolchain install nightly
cargo +nightly install casper-client

If you receive an error on openSSL (macOS) - use brew to install it.

brew install openssl

Example Bonding Transaction

Note the path to files and keys. Note: the session arguments need to be encased in double-quotes, with the parameter values in single quotes. Note the required payment amount. The bonding transaction costs 3 CSPR. The payment amount is specified in motes.

casper-client put-deploy --chain-name casper --node-address http://localhost:7777 --secret-key /etc/casper/<VALIDATOR_SECRET_KEY>.pem --session-path  $HOME/casper-node/target/wasm32-unknown-unknown/release/add_bid.wasm  --payment-amount 8000000000  --session-arg="public_key:public_key='<VALIDATOR_PUBLIC_KEY_HEX>'" --session-arg="amount:u512='<BID-AMOUNT>'" --session-arg="delegation_rate:u8='<PERCENT_TO_KEEP_FROM_DELEGATORS>'"

Contract Arguments

The add_bid contract accepts 3 arguments:

• public key: The public key in hex of the account to bond. Note: This has to be the matching key to the validator's secret key that signs the deployment.
• amount: This is the amount that is being bid. If the bid wins, this will be the validator's initial bond amount.
• delegation_rate: The percentage of rewards that the validator retains from delegators that delegate their tokens to the node.

Check the Status of the Transaction

Since this is a deployment like any other, it's possible to perform get-deploy using the client, which will return the execution status.

casper-client get-deploy --node-address http://localhost:7777 <DEPLOY_HASH>

Check the Status of the bid in the Auction

If the bid wins a slot in the auction, the public key and associated bond amount (formerly bid amount) will appear in the auction contract as part of the validator set for a future era. To determine if the bid was accepted, query the auction contract via the rust casper-client

casper-client get-auction-info --node-address http://localhost:7777

The request returns a response that looks like this:

 {
"jsonrpc": "2.0",
"result": {
  "bids": [
    {
      "bid": {
        "bonding_purse": "",
        "delegation_rate": 0,
        "delegators": [],
        "release_era": null,
        "reward": "93328432442428418861229954179737",
        "staked_amount": ""
      },
      "public_key": ""
    },
    {
      "bid": {
        "bonding_purse": "",
        "delegation_rate": 10,
        "delegators": [],
        "release_era": null,
        "reward": "0",
        "staked_amount": ""
      },
      "public_key": ""
    },
    {
      "bid": {
        "bonding_purse": "",
        "delegation_rate": 10,
        "delegators": [],
        "release_era": null,
        "reward": "",
        "staked_amount": ""
      },
      "public_key": ""
    },
    {
      "bid": {
        "bonding_purse": "",
        "delegation_rate": 10,
        "delegators": [],
        "release_era": null,
        "reward": "0",
        "staked_amount": ""
      },
      "public_key": ""
    },
    {
      "bid": {
        "bonding_purse": "",
        "delegation_rate": 0,
        "delegators": [],
        "release_era": null,
        "reward": "",
        "staked_amount": ""
      },
      "public_key": ""
    }
  ],
  "block_height": xxx,
  "era_validators": [
    {
      "era_id": xx,
      "validator_weights": [...]
    },
    {
      "era_id": xx,
      "validator_weights": [...]
    },
    {
      "era_id": xx,
      "validator_weights": [...]
    },
    {
      "era_id": xx,
      "validator_weights": [...]
    }
  ],
  "state_root_hash": "..."
},
"id": xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
 }

Note the era_id and the validator_weights sections of the response. For a given era_id a set of validators is defined. To determine the current era, ping the /status endpoint of a validating node in the network. This will return the current era_id. The current era_id will be listed in the auction info response. If the public key associated with a bid appears in the validator_weights structure for an era, then the account is bonded in that era.

If the Bid doesn't win

If your bid doesn't win a slot in the auction, it is because your bid is too low. The resolution for this problem is to increase your bid amount. The minimum bid amount is represented by the bid held by the lowest ranking validator in the auction. It is possible to submit additional bids, to increase the odds of winning a slot. It is also possible to encourage token holders to delegate stake to you for bonding.

If you have any concerns, questions, or issues, please submit a request to our support team here:

https://support.casperlabs.io/hc/en-gb/requests/new