Account and wallet structure

The Fireblocks platform is organized around workspaces, vault accounts, asset wallets, and deposit addresses. This article explains that structure and how to apply it using omnibus or segregated account models.

At the top level, your various Fireblocks workspaces are contained within the logical group called the Customer Domain. These workspaces may be hot workspaces, which contain hot wallets, or cold workspaces, which contain cold wallets.

In your Fireblocks workspace, you can create and manage multiple vault accounts, which contain your asset wallets.

For each asset wallet, there are one or more deposit addresses. For UTXO-based assets, such as Bitcoin, a single asset wallet may generate one or more deposit addresses. For account-based assets, there are two options:

1. Account-based assets without tag/memo support, such as ETH, can only generate one deposit address.
2. Account-based assets with tag/memo support, such as XRP, can generate one or more deposit addresses. Each deposit address has the same on-chain address, but they differ by their tag/memo.

Types of workspaces

There are two types of Fireblocks workspaces: Mainnet and Testnet. Any additional workspaces used by Fireblocks for testing or other purposes are not referenced in this article or other design documents.

• Mainnet workspaces: These environments are used for staging and production purposes. Mainnet workspaces are only connected to Mainnet nodes of all supported blockchains.
• Testnet workspaces: These environments are used for sandbox and development purposes. Testnet workspaces are only connected to Testnet nodes of all supported blockchains.

Learn more about the differences between Mainnet and Testnet workspaces.

Types of structures

Fireblocks recommends structuring your vault accounts using one of two methods: omnibus or segregated. The diagram below describes the advantages and disadvantages of each structure.

Omnibus structure

The omnibus structure consists of a central vault account in addition to vault accounts for each end client. Funds are deposited into the individual vault accounts and then swept to the central vault account, where the funds can be invested.

The diagram below shows a high-level representation of the omnibus vault account structure in Fireblocks for all asset types that are not account-based assets without tag/memo support.

Address creation flows

For extended documentation, see Best Practices for Structuring Your Fireblocks Vault.

Two clarifications on the content in that article:

• Omnibus and segregated account structures are independent of whether you have a hot or cold workspace. Both can be implemented in either workspace type.
• Workspaces can contain both an omnibus and segregated account model. There is no limitation restricting a workspace to one specific account model.

Below are diagrams representing different flows for both omnibus and segregated account structures.

Omnibus address creation (UTXO)

1. The end user, Alice, asks to deposit a UTXO asset, such as Bitcoin (BTC).
2. The customer's front-end application creates a new deposit address in the omnibus vault account.
3. This deposit address is assigned to Alice and mapped accordingly within the customer's private ledger.
4. Alice receives a notification from the front-end application with her assigned deposit address, where she can start depositing funds.

Omnibus address creation (account-based with tag/memo support)

1. The end user, Alice, asks to deposit an account-based asset that supports tag/memo fields, such as Ripple (XRP).
2. The customer's front-end application creates a new deposit address in the omnibus vault account.
3. This deposit address is assigned to Alice and mapped accordingly within the customer's private ledger.
4. Alice receives a notification from the front-end application with her assigned deposit address, where she can start depositing funds.

Omnibus address creation (account-based)

1. The end user, Alice, asks to deposit an account-based asset, such as Ethereum (ETH).
2. The customer's front-end application creates a new intermediate vault account and an asset wallet with a deposit address within it.
3. This deposit address is assigned to Alice and mapped accordingly within the customer's private ledger.
4. Once mapped and credited, Alice receives a notification from the front-end application with her assigned deposit address, where she can start depositing funds.

Deposit flows

The diagrams below show the deposit flow for both asset types within the omnibus account structure.

Omnibus architecture for UTXO-based assets

Omnibus architecture for account-based assets

1. Alice deposits funds into her dedicated deposit address.
2. A new incoming transfer appears in Fireblocks and, once confirmed on-chain, the wallet's balance is updated.
3. A webhook event is triggered and sent to the customer's webhook listener component.
4. The webhook listener processes the deposit event and updates the internal ledger accordingly.
5. The customer's front end updates Alice's current balance and transaction history to reflect the newly credited deposit.

Withdrawal flows

Due to various protocol limitations, Fireblocks recommends having more than one withdrawal vault account and performing round-robin withdrawals between them.

• EVM-based networks: Having multiple withdrawal vault accounts helps prevent long queues caused by one stuck transaction. This is due to the protocol's nonce implementation, where every transaction must have an incremental value.
• Bitcoin (BTC): Having multiple withdrawal vault accounts helps prevent a situation where the same unconfirmed input is used in more than 25 subsequent transactions. This is due to Bitcoin Core's implementation of the default maximum limit of unconfirmed transaction chains.

Segregated structure

The segregated structure consists of individual vault accounts for each end client. Funds are stored in and invested from these individual accounts.

Address creation flows

There is no difference between UTXO and account-based assets in the segregated account structure. For both, the process is as follows:

1. The end user, Alice, asks to deposit some assets.
2. The customer's front-end application creates a new vault account if one does not exist, or reuses an existing vault account dedicated to Alice. The asset wallet is then created with a deposit address within the vault account.
3. Alice receives a notification from the front-end application with her assigned deposit address, where she can start depositing funds.

Deposit flows

1. Alice deposits funds into her dedicated deposit address.
2. A new incoming transfer appears in Fireblocks and, once confirmed on-chain, the wallet's balance is updated.
3. A webhook event is triggered and sent to the customer's webhook listener component.
4. The webhook listener processes the deposit event and updates the front-end application.
5. The customer's front end updates Alice's current balance and transaction history to reflect the newly credited deposit.

In this flow, there is no private ledger because the blockchain serves as the ledger and wallet balances are dedicated to a specific account.

Withdrawal flows

Assuming there are no restrictions or substantial withdrawal volumes (in terms of transaction count), withdrawal from the segregated account structure is straightforward.