Skip to content

Set up Polkadot staking with the API

You can only participate in staking on Polkadot ledgers as a validator from Ripple Custody.

You can perform the following staking tasks:

Bond tokens: Designate tokens for staking, a prerequisite before nomination of validators.
Unbond tokens: Remove bonded tokens from staking. After you unbond tokens, you can withdraw the unbonded tokens, or rebond the tokens.
Rebond: Rebond and stake unbonded tokens before the unbonding period finishes.
Bond extra: Add additional tokens to the already bonded amount.
Withdraw unbonded: Add unbonded tokens back to the account balance.
Chill: Clear the list of nominated validators without unbonding the tokens. To restart staking after this operation, you need to nominate new validators.
Nominate: Nominate up to sixteen validators to which to delegate your bonded tokens.
Set payee account: Set or change the account to receive the rewards from staking.
Set controller: Set the account to act as controller, as described in Account types.

Account types

Polkadot ledgers require the following two account types for staking:

A stash account: Holds the funds to use for staking.
A controller account: Controls the staking operations, such as nomination of validators.

If you want to maximize security, you can store the stash account in a separate, cold vault.

Ripple Custody doesn't impose the two account requirement: you can also choose to configure staking with a single account type if preferred.

The following table summarizes which account has the role to submit each of the staking operations listed below:

Operation	Controller	Stash
Bond		X
BondExtra		X
Unbond	X
WithdrawUnbonded	X
Rebond	X
Chill	X
Nominate	X
SetController		X
SetPayee	X

Prerequisites

To perform staking tasks on Polkadot, you need the following:

Prerequisite	Additional information
Accounts on a Polkadot ledger from which to initiate the transactions (two accounts are recommended, as described in Account types)	View account details
Enough funds in the account to cover the transaction fees and the amount	Check account balances
The following new IDs, in a standard UUID format: A transaction order ID An intent ID

Perform staking tasks

System change process

All new requests to change the system state follow the same process. To familiarize yourself with this process first, see Manage intents and approvals.

To perform Polkadot staking tasks, follow the steps in Manage intents and approvals, with a payload similar to one of the following examples.

Payload examples

Bond tokens

{
    "payload": {
        "id": "251c48e9-8a7d-4e1a-9c1e-224de1b55c0d",
        "accountId": "a4a87f1c-7577-4115-9b54-cc445ec08fb5",
        "parameters": {
            "pallet": {
                "method": {
                    "controller": {
                        "address": "5CwKL1nknaXcVfjJaXZ7rFtCJg8sc5tk4ppCzTbAURtBXwMQ",
                        "type": "Address"
                    },
                    "value": "500000000000",
                    "payee": {
                        "destination": {
                            "accountId": "f943d65c-58e3-4ba3-83eb-d66fdce0f32a",
                            "type": "Account"
                        },
                        "type": "Account"
                    },
                    "type": "Bond"
                },
                "type": "Staking"
            },
            "feeStrategy": {
                "priority": "Low",
                "type": "Priority"
            },
            "maximumFee": "20460002010",
            "type": "Substrate"
        },
        "customProperties": {},
        "type": "v0_CreateTransactionOrder"
    }
}

Fields of the payload block to note are as follows:

Field	Description
`accountId`	The stash account. For more information, see Account types.
`pallet.method.controller`	The controller account of the stash account. This account can be the either the stash account or another account. You can set this to an `Account`, `Endpoint` or `Address`.
`pallet.method.type`	`Bond`
`pallet.method.value`	The amount to bond, in Plancks.
`pallet.method.payee`	Destination of the staking rewards. The `type` can be `Controller`, `Stash`, `Staked` or `Account`. If you specify `Account`, then you can set the `destination.type` of `Account`, `Endpoint` or `Address`. You can change this later, with the Set payee account operation.
`pallet.type`	`Staking`
`parameters.feeStrategy`	The fee strategy to use for the transaction. For more information, see Fee strategy and maximum fee.
`parameters.maximumFee`	The maximum fee, in Plancks. For more information, see Fee strategy and maximum fee.
`parameters.type`	Ledger type, in this case `Substrate`.
`type`	`v0_CreateTransactionOrder`

Unbond tokens

{
    "payload": {
        "id": "251c48e9-8a7d-4e1a-9c1e-224de1b55c0d",
        "accountId": "4a15c769-fadb-40c2-adce-4c7733015bea",
        "parameters": {
            "pallet": {
                "method": {
                    "value": "1000000000000",
                    "type": "Unbond"
                },
                "type": "Staking"
            },
            "feeStrategy": {
                "priority": "Low",
                "type": "Priority"
            },
            "maximumFee": "20460002010",
            "type": "Substrate"
        },
        "customProperties": {},
        "type": "v0_CreateTransactionOrder"
    }
}

Fields of the payload block to note are as follows:

Field	Description
`accountId`	The controller account. For more information, see Account types.
`pallet.method.type`	`Unbond`
`pallet.method.value`	The amount to unbond from the bonded amount, in Plancks.

Withdraw unbonded tokens

{
    "payload": {
        "id": "251c48e9-8a7d-4e1a-9c1e-224de1b55c0d",
        "accountId": "4a15c769-fadb-40c2-adce-4c7733015bea",
        "parameters": {
            "pallet": {
                "method": {
                    "numSlashingSpans": 0,
                    "type": "WithdrawUnbonded"
                },
                "type": "Staking"
            },
            "feeStrategy": {
                "priority": "Low",
                "type": "Priority"
            },
            "maximumFee": "20460002010",
            "type": "Substrate"
        },
        "customProperties": {},
        "type": "v0_CreateTransactionOrder"
    }
}

Fields of the payload block to note are as follows:

Field	Description
`accountId`	The controller account. For more information, see Account types.
`pallet.method.type`	`WithdrawUnbonded`
`pallet.method.numSlashingSpans`	The slashing mechanism of Polkadot splits the eras of each nominator into slashing spans to detect the events on which a nominator gets slashed. If acting as nominator, no slashing occurred during the era, the value of `method.numSlashingSpans` should be 0.
`pallet.type`	`Staking`
`parameters.feeStrategy`	The fee strategy to use for the transaction. For more information, see Fee strategy and maximum fee.
`parameters.maximumFee`	The maximum fee, in Plancks. For more information, see Fee strategy and maximum fee.
`parameters.type`	Ledger type, in this case `Substrate`.
`type`	`v0_CreateTransactionOrder`

Rebond tokens

{
    "payload": {
        "id": "251c48e9-8a7d-4e1a-9c1e-224de1b55c0d",
        "accountId": "4a15c769-fadb-40c2-adce-4c7733015bea",
        "parameters": {
            "pallet": {
                "method": {
                    "value": "1000000000000",
                    "type": "Rebond"
                },
                "type": "Staking"
            },
            "feeStrategy": {
               "priority": "Low",
               "type": "Priority"
            },
            "maximumFee": "20460002010",
            "type": "Substrate"
        },
        "customProperties": {},
        "type": "v0_CreateTransactionOrder"
    }
}

Fields of the payload block to note are as follows:

Field	Description
`accountId`	The controller account. For more information, see Account types.
`pallet.method.type`	`Rebond`
`pallet.method.value`	The amount to rebond, in Plancks.
`pallet.type`	`Staking`
`parameters.feeStrategy`	The fee strategy to use for the transaction. For more information, see Fee strategy and maximum fee.
`parameters.maximumFee`	The maximum fee, in Plancks. For more information, see Fee strategy and maximum fee.
`parameters.type`	Ledger type, in this case `Substrate`.
`type`	`v0_CreateTransactionOrder`

Bond extra

{
    "payload": {
        "id": "251c48e9-8a7d-4e1a-9c1e-224de1b55c0d",
        "accountId": "a4a87f1c-7577-4115-9b54-cc445ec08fb5",
        "parameters": {
            "pallet": {
                "method": {
                    "maxAdditional": "1000000000000",
                    "type": "BondExtra"
                },
                "type": "Staking"
            },
            "feeStrategy": {
                "priority": "Low",
                "type": "Priority"
            },
            "maximumFee": "20460002010",
            "type": "Substrate"
        },
        "customProperties": {},
        "type": "v0_CreateTransactionOrder"
    }
}

Fields of the payload block to note are as follows:

Field	Description
`accountId`	The stash account. For more information, see Account types.
`pallet.method.type`	`BondExtra`
`pallet.method.maxAdditional`	The funds to add to the already bonded amount, in Plancks.
`pallet.type`	`Staking`
`parameters.feeStrategy`	The fee strategy to use for the transaction. For more information, see Fee strategy and maximum fee.
`parameters.maximumFee`	The maximum fee, in Plancks. For more information, see Fee strategy and maximum fee.
`parameters.type`	Ledger type, in this case `Substrate`.
`type`	`v0_CreateTransactionOrder`

Nominate staking validators

{
    "payload": {
        "id": "251c48e9-8a7d-4e1a-9c1e-224de1b55c0d",
        "accountId": "4a15c769-fadb-40c2-adce-4c7733015bea",
        "parameters": {
            "pallet": {
                "method": {
                    "targets": [
                        {
                           "accountId": "f943d65c-58e3-4ba3-83eb-d66fdce0f32a",
                           "type": "Account"
                        },
                        {
                           "accountId": "953d75b2-e384-46e9-8a72-a1ce753a50e2",
                           "type": "Account"
                        }
                    ],
                    "type": "Nominate"
                },
                "type": "Staking"
            },
            "feeStrategy": {
                "priority": "Low",
                "type": "Priority"
            },
            "maximumFee": "20460002010",
            "type": "Substrate"
        },
        "customProperties": {},
        "type": "v0_CreateTransactionOrder"
    }
}

Fields of the payload block to note are as follows:

Field	Description
`accountId`	The controller account. For more information, see Account types.
`pallet.method.targets`	Account addresses to nominate as validators.
`pallet.method.type`	`Nominate`
`pallet.type`	`Staking`
`parameters.feeStrategy`	The fee strategy to use for the transaction. For more information, see Fee strategy and maximum fee.
`parameters.maximumFee`	The maximum fee, in Plancks. For more information, see Fee strategy and maximum fee.
`parameters.type`	Ledger type, in this case `Substrate`.
`type`	`v0_CreateTransactionOrder`

Set payee account

{
    "payload": {
        "id": "251c48e9-8a7d-4e1a-9c1e-224de1b55c0d",
        "accountId": "4a15c769-fadb-40c2-adce-4c7733015bea",
        "parameters": {
            "pallet": {
                "method": {
                    "payee": {
                        "destination": {
                            "accountId": "f943d65c-58e3-4ba3-83eb-d66fdce0f32a",
                            "type": "Account"
                        },
                        "type": "Account"
                    },
                    "type": "SetPayee"
                },
                "type": "Staking"
            },
            "feeStrategy": {
                "priority": "Low",
                "type": "Priority"
            },
            "maximumFee": "20460002010",
            "type": "Substrate"
        },
        "customProperties": {},
        "type": "v0_CreateTransactionOrder"
    }
}

Fields of the payload block to note are as follows:

Field	Description
`accountId`	The controller account. For more information, see Account types.
`pallet.method.type`	`SetPayee`
`pallet.method.payee`	Destination of the staking rewards. The `type` can be `Controller`, `Stash`, `Staked` or `Account`. If you specify `Account`, then you can set the `destination.type` of `Account`, `Endpoint` or `Address`. This overrides the payee set with the Bond operation.
`pallet.type`	`Staking`
`parameters.feeStrategy`	The fee strategy to use for the transaction. For more information, see Fee strategy and maximum fee.
`parameters.maximumFee`	The maximum fee, in Plancks. For more information, see Fee strategy and maximum fee.
`parameters.type`	Ledger type, in this case `Substrate`.
`type`	`v0_CreateTransactionOrder`

Chill

{
    "payload": {
        "id": "251c48e9-8a7d-4e1a-9c1e-224de1b55c0d",
        "accountId": "4a15c769-fadb-40c2-adce-4c7733015bea",
        "parameters": {
            "pallet": {
                "method": {
                    "type": "Chill"
                },
                "type": "Staking"
            },
            "feeStrategy": {
                "priority": "Low",
                "type": "Priority"
            },
            "maximumFee": "20460002010",
            "type": "Substrate"
        },
        "customProperties": {},
        "type": "v0_CreateTransactionOrder"
    }
}

Fields of the payload block to note are as follows:

Field	Description
`accountId`	The controller account. For more information, see Account types.
`pallet.method.type`	`Chill`
`pallet.type`	`Staking`
`parameters.feeStrategy`	The fee strategy to use for the transaction. For more information, see Fee strategy and maximum fee.
`parameters.maximumFee`	The maximum fee, in Plancks. For more information, see Fee strategy and maximum fee.
`parameters.type`	Ledger type, in this case `Substrate`.
`type`	`v0_CreateTransactionOrder`

Update controller account

{
    "payload": {
        "id": "251c48e9-8a7d-4e1a-9c1e-224de1b55c0d",
        "accountId": "a4a87f1c-7577-4115-9b54-cc445ec08fb5",
        "parameters": {
            "pallet": {
                "method": {
                    "controller": {
                        "accountId": "f943d65c-58e3-4ba3-83eb-d66fdce0f32a",
                        "type": "Account"
                    },
                    "type": "SetController"
                },
                "type": "Staking"
            },
            "feeStrategy": {
                "priority": "Low",
                "type": "Priority"
            },
            "maximumFee": "20460002010",
            "type": "Substrate"
        },
        "customProperties": {},
        "type": "v0_CreateTransactionOrder"
    }
}

Fields of the payload block to note are as follows:

Field	Description
`accountId`	The stash account. For more information, see Account types.
`pallet.method.type`	`SetController`
`pallet.method.controller`	The controller wallet, either an internal `Account`, an `Endpoint`, or an external `Address`.
`pallet.type`	`Staking`
`parameters.feeStrategy`	The fee strategy to use for the transaction. For more information, see Fee strategy and maximum fee.
`parameters.maximumFee`	The maximum fee, in Plancks. For more information, see Fee strategy and maximum fee.
`parameters.type`	Ledger type, in this case `Substrate`.
`type`	`v0_CreateTransactionOrder`

When the transaction order is successfully approved, Ripple Custody does the following:

Creates a transaction, to broadcast the details on the blockchain.
Creates one or more transfers, to represent the separate amounts associated with the transaction, such as the cryptocurrency amount and the fees.

Delegate Tezos staking validation rights with the API

Gas station