# Transaction status

Executive summary
**After initiation, transactions progress through governance approval, signing, broadcast, and blockchain confirmation, each with distinct statuses.**

- Internal statuses: Pending → Preparing → Reserved → Prepared → Broadcasting → Completed.
- Ledger statuses: Detected → Confirmed (or Replaced/Expired).
- Hot vaults sign automatically. Cold vaults require manual intervention.
- Finality is blockchain-specific. Some chains confirm in seconds, others take minutes.


Why this matters
Understanding transaction statuses is essential for operations and support. Each status indicates where a transaction is in the pipeline and what might be blocking it. "Preparing" often means fee conditions aren't met; "Pending" means awaiting approvals; "Broadcasting" means it's on the network awaiting confirmation. Cold vault transactions require additional operational procedures.

**For architects and operators**: Set up monitoring and alerting on transaction status distributions. Define SLAs for each phase. For cold vault deployments, establish clear procedures for the air-gapped signing process and ensure operators understand the workflow.

Prerequisites
Before reading this page, you should understand:

- [Transactions](/products/custody/v1.36/transactions/overview) - The overall transaction lifecycle and flow
- [Transaction initiation](/products/custody/v1.36/transactions/initiation) - How to start a transaction


## Blockchain concepts

To understand transaction processing, you need to be familiar with a few blockchain concepts:

| Concept | Description | Non-technical explanation |
|  --- | --- | --- |
| **UTXO** | Unspent transaction output - 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. | Think of UTXOs as individual coins in your wallet. When you spend, you use whole coins and receive change back. |
| **Nonce** | A transaction counter, starting at 0, that represents the number of operations sent to an Ethereum Virtual Machine (EVM) blockchain from an account. | A sequence number that ensures your transactions are processed in order, and prevents duplicates. |
| **Gas** | A measure of how much a transaction costs on an Ethereum Virtual Machine blockchain. | The "fuel" required to run your transaction—more complex operations need more gas. |


## Transaction statuses

A blockchain transaction moves through the following statuses:

![Transaction statuses](/assets/transaction-flow.4e35830e7eec539a1421f98cae754303bbca92d5978029330f8d007f7064accc.7e88c1bd.png)

The flow is the same for all ledgers, apart from Bitcoin-type ledgers, which go through an additional step.



### Ripple Custody statuses

While still in Ripple Custody, the transaction can have the following statuses:

| Status | Description | What this means |
|  --- | --- | --- |
| `Pending` | Transaction order is approved by policy evaluation. | Your transaction passed governance checks and is queued for processing. |
| `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. | The system is gathering blockchain data needed to build your transaction. If fees are too high, it waits here. |
| `Reserved` | The necessary resources were allocated for the transaction (for example, nonce or UTXO), which impacts the `Reserved` balance of the account. | Funds are set aside for this transaction and won't be used for other transactions. |
| `Prepared` | The notary has produced an attestation for the vault, which will verify, construct, and sign the transaction. | The operation is authorized and ready for vault verification and signing. |
| `Broadcasting` | The ledger accounting service broadcasts the transaction and tracks its status. | Your transaction has been sent to the blockchain network. |
| `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](/products/custody/v1.36/transactions/reference#transaction-finality). | Ripple Custody has done its job — now we're waiting for the blockchain to confirm it. |
| `Failed` | A transaction can fail for multiple reasons, such as:Expiration dateBlockchain embedded limitationLow fees (the vault rejects the transaction).Deterministic failure to broadcastInvalid endpointNotary rejection due to invalid signature or unexpected payload version (could be recovered by updating the corresponding component) | Something went wrong. Check the error details to understand what happened. |


In addition, Ripple Custody includes status `Interrupted` for internal use only.

### Ledger statuses

Once on chain, the transaction can have a number of blockchain-specific statuses:

| Status | Description | What this means |
|  --- | --- | --- |
| `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. | The blockchain has received your transaction and included it in a block. |
| `Replaced` | Following a user request to replace a transaction with a new one, the transaction is being replaced on-chain. | You requested a replacement transaction (e.g., with higher fees), and it's being processed. |
| `Confirmed` | The transaction is validated in the required number of blocks to reach finality. For more information, see [Transaction finality](/products/custody/v1.36/transactions/reference#transaction-finality). | **Your transaction is complete and irreversible.** The blockchain has permanently recorded it. |
| `Expired` | Confirmation was not reached within the set time. | The transaction wasn't confirmed in time. You may need to resubmit. |


When is my transaction truly complete?
A transaction is fully complete when it reaches **Confirmed** status. At this point, the transaction has been validated by the blockchain and is irreversible. The number of confirmations required varies by blockchain—see [Transaction finality](/products/custody/v1.36/transactions/reference#transaction-finality) for details.

For a complete status summary table, see [Transactions reference](/products/custody/v1.36/transactions/reference#transaction-status-reference).

### Transaction failure

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.


## Vault transaction flows

Ripple Custody supports two vault architectures for transaction signing: *hot vaults* (network-connected) and *cold vaults* (air-gapped). Both follow the same governance and approval process, but differ in how the signed transaction reaches the blockchain.

For more information about the system components described in these flows, see [System architecture](/products/custody/v1.36/overview/architecture).

### Transaction flow overview

The following table describes the complete transaction flow. The initial workflow is identical for hot and cold vaults. The flow diverges when the vault receives the notary-attested operation query.

![Hot vault flow ](/assets/custody-hot-vault-flow.679997ad4a66588a7a8a74fe027f202e11d6e5812a509471dac800067ca4813d.7e88c1bd.png)

#### Common steps (hot and cold vaults)

| Step | Component | Description | What's happening |
|  --- | --- | --- | --- |
| 1 | Operator → API | `Operator 1` submits a signed intent containing transaction data via HTTPS POST to the API gateway. | A user requests a transaction. |
| 2 | API → Operator | The API gateway returns `202 Accepted` with a `requestId` when the request is accepted for processing. | The request is scheduled; execution has not completed yet. |
| 3 | API → AMQP | The API gateway queues the workflow task. | The transaction enters the asynchronous workflow. |
| 4 | Workflow → Notary Bridge | The workflow makes the signed request available to the notary boundary. | The system starts policy evaluation. |
| 5 | Notary | The notary retrieves the signed request, verifies the user signature, evaluates policy, and checks trusted state. | The system checks whether this user can make this request. |
| 6 | Operator → API | If the policy requires another approval, `Operator 2` approves the transaction via HTTPS POST to the API gateway. | Another user approves the transaction. |
| 7 | API → AMQP | The API gateway accepts the approval for asynchronous processing and queues it. | The approval enters the same workflow. |
| 8 | Notary | The notary retrieves and verifies the signed approval. | The approval is checked against policy requirements. |
| 9 | Notary → Notary KMS | When policy conditions are satisfied, the notary updates trusted state and signs the attestation. | All approvals are received and the operation is attested. |
| 10 | Ledger Accounting → PostgreSQL | Ledger Accounting persists the resulting operational state and prepares ledger resources such as fees, nonce, or UTXO selection. | The transaction is prepared for signing. |
| 11 | API | The notary-attested operation query becomes available for the vault. | The transaction is ready for vault verification and signing. |


#### Hot vault: steps 12-18

| Step | Component | Description | What's happening |
|  --- | --- | --- | --- |
| 12 | Vault → API | The vault polls the API gateway for new operation queries via HTTPS GET. | The vault checks for transactions to sign. |
| 13 | API → Vault | The API gateway returns the notary-attested operation query. | The vault receives the transaction work. |
| 14 | Vault | The vault verifies the notary attestation, Merkle proof, and request data, then builds the ledger-specific transaction. | The vault confirms the operation is authorized. |
| 15 | Vault → KMS | The vault requests the protected blockchain transaction signature from its KMS, HSM, or MPC backend. | The protected key signs without leaving the backend. |
| 16 | Vault → API | The vault submits the signed transaction via HTTPS POST. | The signed transaction is returned. |
| 17 | API → Ledger Accounting | The API gateway requests broadcast and tracking. | The system prepares to send the transaction to the blockchain. |
| 18 | Ledger Accounting → Blockchain | Ledger Accounting broadcasts the signed transaction and tracks it through ledger status updates. | Your transaction is sent to the blockchain network. |


Cold vault difference
In a cold vault deployment, the online vault polling and upload steps are replaced by a manual process involving an operator who physically transfers data between the online system and the air-gapped vault.

#### Cold vault: steps 12-23

![Cold vault flow ](/assets/custody-cold-vault-flow.7915dd698183d930143c7441b9736c9b3000f5ebccac9da3a1e73e17ba44511f.7e88c1bd.png)

| Step | Component | Description | What's happening |
|  --- | --- | --- | --- |
| 12 | Operator → API | The cold vault operator requests pending operations from the API gateway. | An operator downloads the transaction request. |
| 13 | API → Operator | The API gateway returns the notary-attested operation query. | The operator receives the transaction data. |
| 14 | Operator → Cold Bridge | The operator **physically moves** to the air-gapped system and submits the operation query to the cold bridge. | The operator walks to the secure room with the cold vault. |
| 15 | Vault → Cold Bridge | The vault polls the cold bridge for new operation queries. | The cold vault checks for transactions to sign. |
| 16 | Cold Bridge → Vault | The cold bridge returns the notary-attested operation query. | The cold vault receives the transaction work. |
| 17 | Vault | The vault verifies the notary attestation, Merkle proof, and request data, then builds and signs the ledger-specific transaction through its protected backend. | The cold vault signs only after verification. |
| 18 | Vault → Cold Bridge | The vault submits the signed transaction to the cold bridge. | The signed transaction is ready for pickup. |
| 19-20 | Operator → Cold Bridge | The operator retrieves the signed transaction from the cold bridge. | The operator downloads the signed transaction. |
| 21 | Operator → API | The operator **physically moves** back and submits the signed transaction to the API gateway. | The operator returns and uploads the signed transaction. |
| 22 | API → Ledger Accounting | The API gateway requests broadcast and tracking. | The system prepares to send the transaction to the blockchain. |
| 23 | Ledger Accounting → Blockchain | Ledger Accounting broadcasts the signed transaction and tracks it through ledger status updates. | Your transaction is sent to the blockchain network. |


### Choosing between hot and cold vaults

| Factor | Hot vault | Cold vault |
|  --- | --- | --- |
| **Security** | Network-connected (higher attack surface) | Air-gapped (maximum isolation) |
| **Transaction speed** | Seconds to minutes | Hours to days (manual process) |
| **Automation** | Fully automated | Requires operator intervention |
| **Use case** | Frequent transactions, trading, payments | Large treasury reserves, cold storage |
| **Operational cost** | Lower (no manual steps) | Higher (dedicated operators, physical security) |


Recommendation
Use a **hybrid approach**: maintain a hot vault for operational liquidity (daily transactions) and a cold vault for long-term reserves. Set governance policies that require cold vault signing for transactions above a threshold amount.

## Transaction fees

When you transact on a ledger, the fees you pay are a combination of the fees set by the ledger itself and a strategy you specify in Ripple Custody to trade off priority against cost.

At transaction execution, Ripple Custody calculates the fee by calling the dry run operation, then adjusts based on your fee strategy and ledger requirements. For an API workflow that includes dry run before submission, see [Send assets with the API](/products/custody/v1.36/transactions/send-and-receive/send-assets-api#dry-run-the-intent).

Ripple Custody supports several fee strategy types:

| Type | Description |
|  --- | --- |
| **Priority** | Fee calculated based on priority level (Low, Medium, High). Required for transfer orders. |
| **Specified rate** | You specify the exact fee rate. EIP 1559 variant available for Ethereum. |
| **Specified additional fee** | Your specified amount added on top of the ledger base fee. |
| **Predefined** | The ledger calculates fees using its own criteria (e.g., Hedera). |
| **Beneficiary pays** | The recipient pays the transaction fees. |


Set a **maximum fee** as a safeguard to cap transaction costs. If network fees exceed your maximum, Ripple Custody holds the transaction in `Preparing` status until conditions improve.

For detailed fee strategies by ledger, see [Transactions reference](/products/custody/v1.36/transactions/reference#fee-strategies-by-ledger).

## Transaction finality

Transaction finality is the point at which a blockchain transaction becomes irreversible. Ripple Custody implements probabilistic finality, treating transactions as confirmed after a sufficient number of blocks.

Different blockchains require different confirmation thresholds:

| Category | Examples | Confirmation Blocks |
|  --- | --- | --- |
| **Fast finality** | XRP Ledger, Stellar, Algorand, Hedera, Avalanche, Polkadot | 1 |
| **Medium finality** | Bitcoin, Dash, Cardano, Tezos, Solana | 2-31 |
| **High confirmation** | Ethereum, BSC, Polygon | 96-200 |


For complete finality settings by network, see [Transactions reference](/products/custody/v1.36/transactions/reference#transaction-finality).

## Next steps

- [Transactions reference](/products/custody/v1.36/transactions/reference) - Detailed fee and finality tables, troubleshooting
- [System architecture](/products/custody/v1.36/overview/architecture) - Learn about notary, vault, and other components
- Send assets: [UI](/products/custody/v1.36/transactions/send-and-receive/send-assets-ui) | [API](/products/custody/v1.36/transactions/send-and-receive/send-assets-api) - Guide for creating transactions