Manage Deposits at Scale
Overview
One of the most important processes for a business is the ability to handle deposits made by clients. To facilitate this, each client needs their own wallet for the asset they want to deposit.
This requirement applies to both scenarios: deposits made by clients from external sources and on-ramp processes such as purchasing crypto and storing it in their address. Both flows result in the creation of a new wallet for the specific user.
Businesses serving hundreds of thousands or even millions of users need to create and manage these addresses and the deposited funds in the most operationally and cost-effective ways.
In this guide, we will outline the recommended workflows for Fireblocks clients to achieve an efficient setup for processing user deposits. The topics covered include:
- Setting up the correct wallet structure for your use case
- Receiving notifications on incoming transfers
- Processing UTXO and Tag/Memo-based asset deposits
- Processing account-based asset deposits
- Best practices for generating deposit addresses
- Validating wallet balances
- Maintaining an internal ledger
Setup the Wallet Structure
The wallet structure, or as we call it in Fireblocks, the vault structure, that you set up will directly impact the capabilities, efficiency, and operational load of your business. Fireblocks recommends one of the following two setups, depending on the type of your operation:
- Segregated Vault Structure: Ideal for customers running a B2B business. This setup is recommended for those who want full segregation of their clients' funds.
- Omnibus Vault Structure: Ideal for customers running a B2C business. This setup is recommended for those who want to create a dedicated wallet for each user and then sweep the funds into a single Treasury wallet.
Learn more about the Fireblocks Vault Structure types
Get Notifications for Incoming Transactions
To receive notifications about incoming transactions to your Fireblocks wallets, we recommend using the Webhook service.
Webhooks are push notifications sent by Fireblocks to a URL specified by the customer. This service sends notifications about various events in your Workspace, including incoming funds. Each incoming transaction triggers a series of events, starting with an alert that a new transaction has been identified, followed by subsequent notifications about the transaction's completion status.
Learn more about the Fireblocks Webhook service
Process UTXO and Tag/Memo Based Assets Deposits
Customers who find the Omnibus structure suitable for their business needs and work with UTXO-based assets will notice that all such assets (e.g., BTC, BCH, LTC, DOGE, ADA) are deposited into a single "Deposit" vault account. Each user has their own deposit address identified by the description parameter.
Processing these funds is straightforward in terms of address generation and management, but it introduces some potential challenges that should be considered during the integration phase. When running a retail-facing business and processing a large volume of UTXO-based asset deposits, customers may find that their deposit vault account accumulates a significant number of unspent transaction outputs (UTXOs) for a specific asset. Efficiently managing these UTXOs is crucial for the following reasons:
-
Creating Outgoing Transactions: Customers might want to move deposited funds (or part of them) to different venues such as exchange accounts, withdrawal vaults, or even a cold wallet. The number of UTXOs that can be selected for a transaction is limited to 250 UTXOs per transaction. This limitation could prevent customers from moving the desired amount if the selected 250 UTXOs do not add up to the intended amount. This depends on the UTXO selection mechanism in your Fireblocks wallet, which by default chooses the smallest confirmed UTXOs first. The selection mechanism can be adjusted to select the largest confirmed UTXOs first, based on customer preference.
-
Fee Efficiency: If a wallet has many small UTXOs, creating outgoing transactions will require selecting more UTXOs to reach the required amount. This results in larger transaction sizes and higher fees, making the transaction more attractive to miners/validators.
To overcome the mentioned in the above, customer should implement a UTXO consolidation logic as described in the following section.
UTXO Consolidation
UTXO-based transactions in Fireblocks have a limit of 250 inputs (UTXOs) per transaction. Additionally, there must be a logic to select the inputs for a transaction, which Fireblocks implements as follows:
- DEFAULT Selection Mechanism: By default, Fireblocks selects the first 250 smallest confirmed inputs available for a specified vault account. This helps customers use up small UTXOs and reduce the number of available UTXOs in their vault account.
- Configurable Selection Mechanism: Fireblocks can be configured to select the 250 largest confirmed inputs first. This configuration requires opening a request with our support team.
This consolidation transaction is typically made from the Deposits vault account to one of the Withdrawals vault accounts to maintain a sufficient asset balance for user withdrawals. However, the transaction can also be executed with multiple destinations, such as different vault accounts, exchange accounts, external addresses, or even a cold wallet.
The trigger for the consolidation process can be based on the number of deposits made into the Deposits vault account. For instance, customers can decide that after every 250 deposits (tracked by an internal counting logic), the system will automatically create the consolidation transaction. Others may choose to execute this transaction based on current network fees to save on transaction costs.
Fireblocks provides two important endpoints to help clients build their UTXO consolidation logic:
- Get Maximum Spendable Amount in a Single Transaction: This endpoint returns the maximum amount of a particular asset that can be spent in a single transaction from a specified vault account.
- Create Transaction: This endpoint creates a transaction with the specified amount returned from the endpoint above.
Additionally, clients who want to trigger the consolidation transaction based on the number of deposits made into their Deposits vault account can use the Fireblocks Webhook service to get notifications on completed incoming transfers.
Check out the UTXO Consolidation Developer Guide
Process Account Based Asset Deposits
Customers who want to generate a unique address for each of their end-users need to create a new intermediary vault account for each user and then the required vault wallet within this newly generated vault account. This is necessary because account-based assets do not support the generation of multiple addresses under the same wallet.
Once the generated address is shared with the end-user and the end-user makes a deposit into that vault account, most customers will want to perform a sweeping operation. This operation consolidates all deposited funds from the intermediary vault accounts into a single treasury management vault account for various business purposes.
Sweeping funds involves moving assets from address A to address B. It is important to note that this is an on-chain operation and includes transaction fee payments.
Learn more about the Sweeping Mechanism
While sweeping base assets like ETH is straightforward, sweeping deposited ERC20 tokens presents a challenge. This is because the transaction fee must be paid in the network's base asset, which end-users might not have in their wallets. To address this issue, Fireblocks recommends using the Fireblocks Gas Station feature.
Learn more about the Fireblocks Gas Station
Create Deposit Addresses Best Practices
Customers serving hundreds of thousands or even millions of users will eventually need to create a corresponding number of deposit addresses within a single vault account (for UTXO deposits) and/or intermediate vault accounts (for Account Based assets) in their workspace. A basic implementation is to create a new deposit address or vault account for the end-user whenever the user registers for the service or requests a deposit address for a specific coin.
In this setup, customers make a real-time API call to Fireblocks to generate a new deposit address or create a new vault account with a vault wallet for the requested asset, triggered by the end-user request.
While this approach is acceptable, the best practice we recommend is to create these deposit addresses or intermediate vault accounts proactively. Fireblocks customers should run a service that continuously creates addresses, vault accounts, and vault wallets, regardless of user requests.
This proactive approach means maintaining a pool of pre-generated vault accounts and addresses. When a user requests a new deposit address, customers can quickly assign a pre-generated address instead of making a real-time API call to Fireblocks. This reduces the risk of encountering API errors in real-time and significantly decreases the waiting time for users to receive a new address, thereby enhancing the user experience and providing a near real-time service.
To associate the pre-generated address with the end-user, during the assigning process on the customer's side, the following APIs should be called to synchronize both Fireblocks and the customer's internal system with the user reference:
-
UTXO and Tag/Memo Based Assets: When assigning a new UTXO-based asset deposit address within your Deposit vault account for a new user, call the Update Address Description API endpoint with the newly assigned user reference as the description.
-
Account-Based Assets: When assigning a new intermediate vault account for an end-user, call the Rename a Vault Account API endpoint with the newly assigned user reference as the vault account name. Ensure that the vault account name does not contain any PII data.
Validate Balances
Fireblocks allows you to receive notifications about incoming transactions to your Fireblocks vault accounts. A common setup for Fireblocks customers is to subscribe to the webhook service and get notified whenever a new deposit is made into a vault account. When an event for an incoming transaction is triggered, followed by an event confirming the deposit's completion, the typical setup on the customer's end will automatically update the internal ledger and adjust the balance of the user associated with the deposited vault account.
While this approach is generally correct, Fireblocks recommends implementing additional validation steps before crediting the end user with the deposited amount to avoid potential loss of funds.
Validating Incoming Balances is crucial!
Learn more about the best practices for validating balances and performing reconciliation processes in the following guide
Maintain an Internal Ledger
An internal ledger is a fundamental component to consider when building a retail-facing solution. Essentially, it records incoming transfers and balances for your users.
Maintaining this ledger is crucial because funds deposited by users into their accounts are often swept or moved to a different account, as described in the sweeping mechanism section. You need to accurately track how much each user has deposited and what balance should be displayed in your system.
Fireblocks does not provide a built-in component or feature for this specific need, so customers can implement it in any way they see fit. However, Fireblocks offers all the necessary utility tools and features to effectively maintain such a ledger. This includes APIs for validation and reconciliation processes and a webhook service that allows you to create an event-driven system triggered by various events in your Fireblocks workspace.
Updated 5 months ago