Transaction Lifecycle

Planbok provides a streamlined, uniform experience for managing transactions across multiple blockchains. This document outlines the process from the initial builder request to the final confirmation on the network.

Transaction Builders

To simplify the complexity of different blockchain protocols, Planbok uses a Builder Pattern. Instead of dealing with raw hex data, you interact with intuitive services that handle the heavy lifting:

1. Transfer Builder

Automates the creation of "Standard Transfers" for native assets, fungible tokens (ERC-20, SPL, etc.), and NFTs/Semi-NFTs [BETA]. It handles decimal normalization and validation for all supported chains.

[!WARNING] Support for NFTs (ERC-721) and Semi-NFTs (ERC-1155) is currently in Beta and coming soon. Usage will be managed by organizations for now, using Contract Execution

2. Contract Execution Builder

Designed for decentralized application (dApp) interactions. It allows you to specify function names and parameters (ABI-encoded for EVM, JSON-encoded for Cosmos/Near) which are then transformed into valid transaction data.

3. Signing Builder

A raw utility for signing arbitrary messages or pre-built transactions. This is used for advanced use cases like EIP-712 typed data signing or cross-chain bridge interactions.

Status Flow

Every transaction moves through a series of deterministic states. Understanding these statuses is key to building a responsive frontend for your application:

1. pending: The transaction has been "Built" and is stored in our database, awaiting the 2-of-2 MPC signing ceremony.
2. signed: The MPC nodes have successfully generated a signature. The full, signed transaction hex is now available.
3. broadcast: The signed transaction has been submitted to the blockchain network's mempool but is not yet included in a block.
4. confirmed: The transaction has been included in a block and has reached a sufficient level of finality on the network.
5. failed: The transaction encountered an error during signing, broadcasting, or was permanently rejected by the network (e.g., out of gas).
6. cancelled: A pending transaction was moved to the cancelled state before it could be signed or broadcast.

Advanced Actions: RBF (Replace-By-Fee)

For networks that support it (like EVM and Bitcoin), Planbok allows you to interact with transactions even after they've been broadcast:

Accelerate

If a transaction is stuck in the broadcast state due to low network fees, you can trigger an Accelerate action. Planbok will:

• Re-build the transaction with a higher gas price (EVM) or fee rate (Bitcoin).
• Maintain the same nonce to replace the original transaction in the mempool.
• Initiate a new 2-of-2 MPC ceremony for the updated signature.

Cancel

If you need to stop a transaction that is still in the mempool, you can trigger a Cancel action. Planbok will:

• Send a 0-value transaction to yourself with the same nonce but a significantly higher gas price.
• This effectively "wins" the race in the mempool, causing the original transaction to be discarded.

[!TIP] Use our Webhooks to listen for status changes (transaction.broadcast, transaction.confirmed). This is more efficient than polling the transaction status endpoint.