When you send a transaction to a blockchain, once the Ripple Custody governance process is complete, Ripple Custody generates the corresponding transaction to broadcast on chain.
The transaction then progresses through different statuses of a flow, as described below.
Key concepts required for an understanding of transaction processing are:
- UTXO
- Nonce
- Gas
These concepts are generic blockchain concepts and are included for guidance. You can find more information about UTXO, nonce, and gas in external sources.
UTXO (unspent transaction output) is a digital currency resource used for transactions on Bitcoin-type ledgers. It represents a certain amount of cryptocurrency that was authorized by a sender and is available to be spent by a beneficiary.
Nonce is a transaction counter, starting at 0, that represents the number of operations sent to an Ethereum Virtual Machine blockchain from an account.
Gas is a measure of how much a transaction costs on an Ethereum Virtual Machine blockchain.
A blockchain transaction moves through the following statuses:
The flow is the same for all ledgers, apart from Bitcoin-type ledgers, which go through an additional step.
While still in Ripple Custody, the transaction can have the following statuses:
| Status | Description |
|---|---|
Pending | Transaction order is approved by the policy engine. |
Preparing | The ledger accounting service fetches the executable transaction order and retrieves data from the ledger nodes (for example, nonce, UTXO, or fees). The information is stored in the database. Note that the transaction remains on hold (Preparing status) until the network conditions make it possible to broadcast it within the acceptable fee levels. |
Reserved | The necessary resources were allocated for the transaction (for example, nonce or UTXO), which impacts the Reserved balance of the account. |
Prepared | The governance engine has produced a signature of executability for the vault, which will verify, construct, and sign the transaction. |
Broadcasting | The ledger accounting service broadcasts the transaction and tracks its status. |
Completed | All processing is complete and the transaction was successfully broadcast. The transaction is no longer within the control of Ripple Custody. The amount of time for the transaction to be processed depends on the number of blocks the ledger needs to reach finality. For more details, see Transaction finality. |
Failed | A transaction can fail for multiple reasons, such as:
|
In addition, Ripple Custody includes status Interrupted for internal use only.
Once on chain, the transaction can have a number of blockchain-specific statuses:
| Status | Description |
|---|---|
Detected | The transaction is visible in the first block of the ledger. For Bitcoin ledgers, this status applies if the transaction is either visible in the mempool or the first block. |
Replaced | Following a user request to replace a transaction with a new one, the transaction is being replaced on-chain. |
Confirmed | The transaction is validated in the required number of blocks to reach finality. For more information, see Transaction finality. |
Expired | Confirmation was not reached within the set time. |
When a transaction reaches the Confirmed status on the ledger, the transaction sent by the user is included in a block of the chain, however, this does not automatically mean that the action described in the transaction was executed. The action is not executed if the transaction breaks a rule on the ledger or the transaction contains a mistake, for example:
- The data string sent to a smart contract is malformed.
- The operation is reverted for lack of gas.
- A non-authorized staking operation is submitted.
- The address of the recipient is faulty.
- A token was sent that was not previously associated with the recipient address.
The following examples illustrate how transactions from Ripple Custody to an external system are processed using a combination of Ripple Custody components and external components. The examples show a complete transaction flow through the components of the Ripple Custody system, using both a hot and cold vault.
For more information about the system components described in the flows, see Components.
| Step | Description |
|---|---|
| 1 | Operator 1 submits a new signed intent Int1 to Ripple Custody through an HTTPS POST request to the API gateway. The intent contains data for a new transaction Trn1. |
| 2 | The governance engine regularly polls the notary bridge for new messages, through a dedicated gRPC stream. |
| 3 | The notary bridge replies to the gRPC request with the signed intent Int1. |
| 4 | The governance engine checks the user signature of Int1 and applies the related policy. |
| 5 | The governance engine submits the validated intent Int1 to the notary bridge, through a dedicated gRPC request. |
| 6 | Operator 2 approves Trn1 by submitting an HTTPS POST request to the API gateway. |
| 7 | The governance engine regularly polls the notary bridge for new messages, through a dedicated gRPC stream. |
| 8 | The notary bridge replies to the gRPC request with the signed intent approving Trn1. |
| 9 | The governance engine verifies the user signature of the transaction approval and applies the related policy. As all required approvals were submitted and verified, the governance engine generates and signs an operation query for the vault, and sends a request to the vault to build and sign the blockchain transaction Tx1. |
| 10 | The governance engine submits the signed message to the notary bridge, through a dedicated gRPC request. |
| 11 | The vault regularly polls the API gateway for new operation queries, through an HTTPS GET request. |
| 12 | The API gateway replies to the HTTPS request with the operation query signed by the governance engine. |
| 13 | The vault verifies the governance engine signature, builds blockchain transaction Tx1, and signs the transaction. |
| 14 | The vault submits the signed transaction Tx1 to the API gateway through an HTTPS POST. |
| 15 | The API gateway sends a request to the ledger accounting service to broadcast the signed blockchain transaction Tx1. |
| 16 | The ledger accounting service broadcasts the signed blockchain transaction Tx1 to the blockchain through the DLT. |
| Step | Description |
|---|---|
| 1 | Operator 1 submits a new signed intent Int1 to Ripple Custody through an HTTPS POST request to the API gateway. The intent contains data for a new transaction Trn1. |
| 2 | The governance engine regularly polls the notary bridge for new messages, through a dedicated gRPC stream. |
| 3 | The notary bridge replies to the gRPC request with the signed intent Int1. |
| 4 | The governance engine verifies the user signature of Int1 and applies the related policy. |
| 5 | The governance engine submits the validated intent Int1 to the notary bridge, through a dedicated gRPC request. |
| 6 | Operator 2 approves Trn1 by submitting an HTTPS POST request to the API gateway. |
| 7 | The governance engine regularly polls the notary bridge for new messages, through a dedicated gRPC stream. |
| 8 | The notary bridge replies to the gRPC request with the signed intent approving Trn1. |
| 9 | The governance engine verifies the user signature of the transaction approval and applies the related policy. As all required approvals were submitted and verified, the governance engine generates and signs an operation query for the vault, and sends a request to build and sign blockchain transaction Tx1. |
| 10 | The governance engine submits a signed message to the notary bridge, through a dedicated gRPC request. |
| 11 | The operator in charge of operating the air-gapped system sends an HTTPS GET request to the API gateway, asking for new operations intended for the air-gapped vault. |
| 12 | The API gateway replies to the HTTPS request with the operation query signed by the governance engine. |
| 13 | The operator physically moves to the air-gapped system and submits the operation query through an HTTPS POST request to the cold bridge, a dedicated component for the air-gapped system. |
| 14 | The vault regularly polls the cold bridge for new operation queries, through an HTTPS GET request. |
| 15 | The cold bridge replies to the HTTPS request with the operation query signed by the governance engine. |
| 16 | The vault verifies the governance engine signature, builds blockchain transaction Tx1, and signs the transaction. |
| 17 | The vault submits signed transaction Tx1 to the cold bridge through an HTTPS POST request. |
| 18 | The operator retrieves signed transaction Tx1 from the cold bridge through a dedicated HTTPS GET request. |
| 19 | The cold bridge replies to the HTTPS request with the signed transaction Tx1. |
| 20 | The operator submits the signed transaction to be broadcast to the API Gateway through an HTTPS POST request. |
| 21 | The API gateway requests the ledger accounting service to broadcast the signed blockchain transaction Tx1. |
| 22 | The ledger accounting service broadcasts the signed blockchain transaction Tx1 to the blockchain through the DLT. |