Skip to main content

Advance Flows using a Transaction Hash

Motivation​

The Staking API provides the option for clients to use an existing solution to sign and broadcast transactions themselves, and to use a transaction hash from a completed transaction to advance the state of a flow and confirm the transaction on-chain — in lieu of providing a signed transaction payload.

The following example uses a Polkadot bonding flow on the Westend testnet to illustrate the process.

Action​

Polkadot delegation flows use the create_bonding_tx action to generate a transaction payload. It is still possible to bond from a Stash account, outside the scope of the Staking API. In this case, we want to perform the bond transaction (including the signature) from the Polkadot.js Apps UI, then complete the bonding flow with the Staking API by providing the transaction hash of the completed transaction.

The general form of this action is confirm_<action>_tx_by_hash. Since we are performing a bonding transaction, the action name to use is confirm_bonding_tx_by_hash.

Using this action in a flow lets you supply a transaction hash to the Staking API while the flow is in the <action>_tx_signature state. In the case of Polkadot, the block number of the block which includes the transaction hash must also be specified.

This action is also available for other networks and flows.

Click to view Staking API response for Polkadot
Partial response for create_bonding_tx (... indicates where response was trimmed)
{
  "id": "3ace9f6b-7298-4fc7-b780-f2c3ea521784",
  "state": "bonding_tx_signature",
  "actions": [
    ...
    {
      "name": "confirm_bonding_tx_by_hash",
      "inputs": [
        {
          "name": "hash",
          "display": "Hash",
          "description": "",
          "type": "string",
          "validations": [
            {
              "type": "presence",
              "options": {}
            }
          ],
          "array": false,
          "default_value": null
        },
        {
          "name": "block_number",
          "display": "Block Number",
          "description": "",
          "type": "integer",
          "validations": [],
          "array": false,
          "default_value": null
        }
      ]
    }
  ],
  ...
  "network_code": "polkadot",
  "chain_code": "westend",
  "created_at": "2023-01-20T22:10:26.800Z",
  "updated_at": "2023-01-20T22:28:19.348Z"
}

Usage​

On Polkadot, the input for hash should be the Extrinsic Hash of the transaction, and the input for block should be the block number in which that extrinsic occurred. For other networks, supply the hash of a confirmed transaction.

Check out an example bonding transaction on the Subscan block explorer for an example of where to find this information.

Code Examples​

important

Code examples provided as samples only and should not be used in production out of the box. Use at your own risk.

Example PUT /api/v1/flows/<flow_id>/next
curl -X PUT 'https://polkadot-slate.figment.io/api/v1/flows/<flow_id>/next' \
-H 'Authorization: API-KEY' \
-H 'Content-Type: application/json' \
-d '{
    "name": "confirm_bonding_tx_by_hash",
    "inputs": {
        "hash": "0x53b66da426dca5386408f0a3cdc5300477dd7151c7459701e9dcbbf0fa0b07c8",
        "block_number": "14295923"
    }
}'
note

The parameter block_number only applies to Polkadot.

Flow State​

The action confirm_<action>_tx_by_hash updates the flow state, depending on whether the confirmed transaction hash can be found by the Staking API.

  • When confirm_<action>_tx_by_hash succeeds, the flow state will reflect the successful action, the same as if a transaction payload had been signed and sent to the Staking API. Check the network tabs below for a summary of flow states after confirm_<action>_tx_by_hash.

  • In case confirm_<action>_tx_by_hash fails, the flow state will remain <action>_tx_signature, allowing for retries — the flow state does not become <action>_tx_broadcasting.

In the case of the example Polkadot bonding transaction, the state would be bonding_complete after a successful confirm_bonding_tx_by_hash action.

For comparison, an Ethereum staking flow state would be deposited after a successful confirm_deposit_tx_by_hash action.

  • Polkadot staking flow state is bonding_complete after a successful bonding transaction and delegated after a successful nomination transaction
  • Polkadot unstaking flow final state is done or ready_to_withdraw, moving to done after a successful withdrawal transaction
  • Polkadot add staking proxy flow final state is registered
  • Polkadot remove staking proxy flow final state is removed
  • Polkadot transfer flow final state is transferred