Collector User Guide
The Collector only works with Ethereum, EVM tokens, and ERC-20 tokens.
To consolidate Bitcoin and other similar UTXO cryptocurrencies, see the /mergeUtxos function in the API.
Introduction
In Omnibus accounts, funds cannot be sent directly from deposit wallets to arbitrary receivers. You must transfer the assets from the deposit wallets to your main omnibus account before they become spendable. The Collector gathers crypto asset funds (strictly limited to Ethereum, native tokens, and ERC-20 tokens) from multiple deposit addresses across many EVM networks (such as Ethereum, Polygon, Avalanche, and others). These funds are then transferred to the main MPC or cold address associated with their respective omnibus account.
The Collector takes what would otherwise be a tedious process of collecting from multiple wallets and condenses it, once properly configured, to a single click. Remember, each wallet collected from entails a transfer, a transaction, from the deposit wallet to the main account. Like all transactions on the blockchain, fees are assessed. Running the collector more frequently has a direct impact on the liquidity of the assets. When the collector operates at shorter intervals, it facilitates quicker transactions and enhances the overall account liquidity. However, this increased frequency also results in more frequent fee assessments.
The user can create multiple Collectors for the system, however, they can link each account to only one Collector.
Configuring a Collector for Your Needs
Custody Infrastructure supports setting multiple Collector configurations, each configuration collecting from several omnibus accounts. Multiple configurations allow you to easily support multiple business models. As an example:
- When setting up a Collector for ‘Retail omnibus accounts’ the fee tolerance for collecting might be set to a very low number to reflect that the organization doesn’t charge retail clients much for covering blockchain fees and therefore is unwilling to tolerate or cover high fees. The Collector is likely to collect less frequently, only running a collection when the blockchain network charged lower fees. The Retail Omnibus Account customers' assets would be less liquid, but the customers would have lower overhead.
- When setting up a Collector for "VIP client collection" the organization can set a higher tolerance for blockchain fees to supply faster service when needed, have funds pooled faster into one blockchain address, and be ready to be served for any need or purpose of these VIP clients. The Collector is likely to collect more frequently, as the blockchain fees will cross the "this is too high for me" threshold far less often, running a collection when the blockchain network charged lower fees. The VIP Client Account customers' assets would be more liquid, but the customers would have higher operational overhead.
The above examples illustrate some basic use cases, but the Collector is quite flexible - you can configure the Collector according to your unique business needs.
Each account can appear only in one collector configuration.
Adding Collector access
Setting up user access to the Collector occurs in the System Preferences, where a user can be added to the Collector allowlist.
Open the Admin Panel, select Settings, and then the System Preferences tab.
In the Collector & Exchange user allowlist set the Collections fee limit.
To add a user to the allowlist, select Edit.
Add the user(s) by selecting the 
button.
Select Save.
The Collectors icon is added to the Side menu bar.
Collector creation process
Creating a Collector is a three-phase process. First, the Collector is configured. Next, the tokens are selected. Finally, the fee tolerances are tuned. You'll need to work through the following three screens to complete the process:
- Name
- Token
Create a New Collector
Open the Collector page from the Side bar menu.
To create a new collector, select the New collector button
The New Collector pane starts with the Name section.
Type a name for the Collector.
Make the name descriptive enough that an auditor can understand the Collector's purpose when working through an audit of your system.
Open the Accounts dropdown menu and select the check box(es) to include. Each account can only be connected to one Collector.
Select MPC or Cold to decide where to direct the collected funds:
- MPC: Choose this option to send funds to the main account's MPC wallet for all collected currencies. This is the most liquid option.
- Cold: Choose this option to send funds to the Main Accounts Cold wallet for all collected currencies. This is the most secure option.
Collection is done on a per-account basis, meaning that account funds are not commingled with other accounts in the collection process. For example, when selecting MPC, Account 1 deposit addresses will be collected to the Account 1 main MPC address, and Account 2 deposit addresses will be collected to the Account 2 main MPC address.
Select Next.
The Token section opens.
Select one or multiple tokens from the drop down list.
Any number of tokens can be set for a Collector, but the more tokens selected, the more time the collection operation takes to run. Only active currencies can be selected and collected.
Select Next.
The Network Fees section opens.
Set the Priority and Max total fees.
Select Create.
Setting Network fees
Each network requires general fee settings. Specific, per-token settings can be set later. For more information, see Explaining Collector MetricsExplaining Collector Metrics.
- Priority fee - The fee that goes to the validator in EVM networks. For some networks, such as Ethereum, the Custody Infrastructure system automatically receives a priority fee suggestion; there’s no need to set it any differently than what’s being shown by the system.
- Max total fee - The total amount of fee you're willing to pay over one collection run for all deposit addresses together across all chosen network tokens.
- The ‘Max total fee’ exists so you can protect yourself from overspending in fees due to ERC-20 token collections. Overspending can happen when the value of the token experiences a sudden spike, causing transactions to require a higher fiat cost than you are willing to pay.
For example, paying for USDT token transfers on the Ethereum blockchain are paid in ETH fees. If that fiat value were to change fast and drastically upwards due to a smart contract hack or breach, then collections would be skewed into a decision to collect from many deposit addresses even in cases where the deposit address token value doesn’t justify it.
Suppose a breach causes WBTC, an ERC-20 token that tracks Bitcoin’s price, to spike to $150,000. This makes collecting it more profitable, even with high ETH fees. But if the token price drops quickly after the breach, the organization still loses ETH for the transfers.
To avoid this, the organization can cap the total Ethereum fees for each collection. This can be based on previous collections and the expected value of the tokens.
Capping the total allowed fee per network for each collection run protects against smart contract hacks or other malicious actors and enables an organization to cap a possible loss of funds to a reasonable amount.
Collection Metrics
There are two collection metrics to manage fee tolerance: Fee ratio & Fee cap
Fee Ratio
The formula for the fee ratio is simple:
Formula (calculated for a specific deposit address and token combination):
\frac{\text { Blockchain Fee }}{\text { Deposit Address Balance }} = \text { Fee Ratio }The challenge in dealing with ratio has to do with the nature of cryptocurrencies. Native currencies, like Ethereum, are charged transaction fees in the currency itself. Moving ETH entails paying fees in ETH. Changes in ETH's fiat price doesn't impact the ratio between the fee amount, as both go up or down in fiat value together.
With tokens built on the Ethereum blockchain, the token value is independent of the value of Ethereum, but the fee for moving the tokens is charged in Ethereum. A change in the fiat value of ETH (or the token) can wildly swing the fee ratio.
For token transactions, the Collector calculates the fee ratio the moment it is activated. The first step in calculating the ratio is to convert both the token and the Ethereum needed to pay the fee into their current fiat values.
Only after the Collector knows the current fiat values of both the token and the fees can the fee ratio be determined. The resulting ratio is then checked against the settings you configured to determine whether or not to collect the assets at this time.
Example:
The following table shows the collector's decision-making for a USDT token on the Ethereum blockchain, for a specific account:
The numbers:
- 1 USDT token = 1$
- ETH network fee for transferring ERC-20 token at the time the collector starts is 0.0091ETH ~ 15$
- Fee ratio set to = 3%
Omnibus Account wallets | Balance | Fee Ratio | Collection Decision |
|---|---|---|---|
Wallet 1 | 10 USDT = 10$ | 15/10= 1.5 Fee ratio: 150% | Do not collect [150% > 3%] |
Wallet 2 | 245,624 USDT = 245,624$ | 15/245,624 = 0.6% | COLLECT! [0.6% < 3%] |
Wallet 3 | 45 USDT = 45$ | 15/45= 33% | Do not collect [33% > 3%] |
Wallet 4 | 20,000 USDT = 20,000$ | 15 / 20,000 = 0.075% | COLLECT! [0.075% < 3%] |
Wallet 5 | 1 USDT = 1$ | 15/1 = 1500% | Do not collect [1500% > 3%] |
The table above only looks at Fee Ratio. In real life, both Fee Ratio and Fee Caps are considered for each wallet.
In the above example, the collector would gather funds from Wallets 2 and 4.
Fee Cap
The Fee Cap is set in ETH. It's a raw number, not converted into Fiat. Why? Because no new fiat currency is introduced. The transaction fees come from ETH you already own, so no new fiat currency enters the picture.
Fee cap is a metric set for the following purposes:
- A Fee cap is required so that fee costs don't exceed a certain amount even for deposit addresses that contain large sums.
- Network fees are dynamic and change block by block.
- Changing network fees mean that if you are not in a hurry to collect the fees, you can wait for a time when blockchain fees will go down due to decreasing demand.
- Usually when North-American crypto markets are less active, blockchain fees go down significantly.
- Using our API, a collector can be set through a script to run every 12 hours and attempt to collect according to blockchain fees present at the time of collection.
Example:
Looking at the prior table, there are two wallets the collector would choose to collect from if the fee cap were not set, Wallets 2 and 4.
Omnibus Account wallets | Balance | Fee Ratio | Collection decision |
|---|---|---|---|
Wallet 2 | 245,624 USDT = 245,624$ | 15/245,624 = 0.6% | COLLECT! [0.6% < 3%] |
Wallet 4 | 20,000 USDT = 20,000$ | 15 / 20,000 = 0.075% | COLLECT! [0.075% < 3%] |
The Fee Cap is set to 0.0049 ETH, and is factored into the table below:
Omnibus Account wallets | Balance | Fee Ratio | Fee (LIMIT) | Collection decision |
|---|---|---|---|---|
Wallet 2 | 245,624 USDT = 245,624$ | 15/245,624 = 0.6% COLLECT | 0.0091 (0.0049) | Do not collect. [0.0091 > 0.0049] |
Wallet 4 | 20,000 USDT = 20,000$ | 15 / 20,000 = 0.075% COLLECT | 0.0091 (0.0049) | Do not collect. [0.0091 > 0.0049] |
With the Fee Limits in place, the collector decides the cost of collect is too high even though the ratio is acceptable.
Gas Limits
The Collector is nothing special from the standpoint of the blockchain. The transfers it performs are nothing special, just ordinary transactions. The gas limit for Ethereum should thus be standard: 21000. As for ERC20 tokens, please use Etherscan to see what the market rate is for the token in question.
Running a Collector
Once the collection starts, you’ll see the time elapsed from the initial start time as well as what time the collector started working.
A collector cannot start if another collector is currently running.
A collector cannot be started on a schedule. Starting a Collector unattended requires that you write a script.
Collection History Log
Click at the bottom of the collector page to expand the collection history log view.
For each collection instance, the table will show:
- The Initiator by name & email - the initiator is the user who started the collection
- Start time - when the collection started
- End time - when the collection ended
- Collected value in fiat - total collected crypto assets translated into fiat value
- Total fees as fiat value and as a percentage from total collected value
- Percentage is calculated as:
\frac{\text { Total fees }}{\text { Collected fiat value }} * \text { 100 }For example: Collected 20$ worth of ETH, paid 4$ worth of ETH as blockchain fees, so:
\frac{\text {4}}{\text {20}} * \text { 100 } = {20}{\%}The GUI will not show you why a transaction failed in the history. If you run the collection via API and it fails, the API output will contain more detail about why it failed. The API output is only shown ONCE though, so make sure to copy-paste it and retain it for your records.
Collection Instance Logs
Clicking the arrow to the far right of a collection instance drills down into that Collector run's logs. This provides detailed data of collection attempts whether successful or failed:
Activity Page
Collector transactions are filtered out from the desktop activity page.
Collector Cold Vault Settings
Collector allowed user list is the list of Users permitted to use the collector. This is set from the cold vault interface on the preferences screen. Just scroll down to see this part of the screen and select the relevant users to allow them to set, edit, and run collectors.
This feature is only available in Cold-driven set ups.
Collections Fee Limit per Week
You can also set a collections fee limit per week for all collection instances (meaning the number of times each of the set collectors ran in a given week timeframe). This limit is in fiat value and is aimed at protecting the organization both from unintentional mistakes and malicious employees.
