Exchange Guide

Benefits of Using Liminal

Running a Web3 platform comes with its unique set of challenges. At Liminal, we've engineered our solutions to directly address these pain points, ensuring your operations are secure, efficient, and scalable.

Minimising Risks with Hot Wallets

Hot wallets, while necessary, can be a weak link in your security chain. Liminal's infrastructure minimises this risk by:

• Automated Sweeping: Constantly moving funds to cold storage to keep hot wallet balances low.
• Dynamic Liquidity Management: Ensuring withdrawal wallets maintain optimal liquidity for user transactions without excess holdings.

Effortless Wallet Operations via APIs:

• Seamless Integration: Liminal's APIs blend with your systems for streamlined wallet creation and transaction management.
• Programmable Interface: Execute complex wallet operations with simplicity through our smooth APIs.

Reducing Manual Operational Tasks

Liminal transforms manual, resource-intensive tasks into automated processes:

• Smart Refills: Automatically topping up withdrawal wallets when needed.
• Transaction Management: Swiftly addressing any stuck transactions with automated recovery mechanisms.

Streamlined Wallet Monitoring

Our platform alleviates the need for constant vigilance by:

• Real-Time Alerts: Keeping you informed of transaction statuses and transaction flows.
• Automated Checks: Monitoring deposit and withdrawal wallets to prevent asset accumulation and ensure transaction continuity.

Simplified Key and Wallet Management

• Unified Dashboard: Control all blockchain wallets from one central location for effortless management.
• Key Backup and Recovery: Quick recovery and access restoration to your assets with Liminal's robust backup processes.

Withdrawal Cost Efficiency with Liminal

• Fee Optimisation: Liminal's algorithm predicts and adjusts to Ethereum's fee fluctuations, ensuring lower transaction costs.
• Automated Efficiency: Set it and forget it—Liminal's system automatically manages fees, aiming for up to 15% savings on ETH withdrawals.

By choosing Liminal, you're not just selecting a service provider — you're partnering with a platform that understands the intricacies of running a Web3 exchange and is dedicated to mitigating those challenges through innovative technology like MPC and smart design.

Terminology for the Guide

• Deposit Hot Wallet: A digital wallet that operates online and is used to receive cryptocurrency deposits from users. It is designed for high-frequency transactions and is constantly monitored for security and balance management.
• Withdrawal Hot Wallet: This wallet is critical for processing user withdrawals on a cryptocurrency exchange. It is maintained online with automated signing to facilitate immediate transactions, ensuring a seamless user experience.
• Cold Wallet: A form of cryptocurrency wallet that is not connected to the internet, providing enhanced security for stored assets. It is typically used for holding funds that are not required for immediate daily transactions.
  • Hardware Wallet(Trezor/ Ledger)
  • Mobile MPC Wallet(iOS/ Android)
• Gas Station: A specialised wallet or service within Liminal that ensures that other operational wallets have sufficient gas to perform transactions efficiently and manages the allocation of gas fees for transactions on the EVM-based network.
• Consolidation: The process of transferring funds from multiple user deposit addresses to a single destination address(typically a cold wallet) for better security and management. This practice is often automated to reduce manual effort and operational risk.

Architecture and Overview: How Transactions Flow?

Liminal offers a sophisticated architecture that caters to the diverse needs of digital asset security through a blend of hot and cold storage solutions.

The architecture diagram illustrates the wallet infrastructure with Liminal for exchanges. The process is divided mainly into the aspects of user deposits, hot wallets (for temporary storage and transactions), and cold wallets (for secure, long-term storage). Here’s an explanation of the workflow depicted in the diagram:

1. User Deposits:

• Exchanges utilise an API to generate unique deposit addresses for users.
• Users deposit their funds into these unique addresses.

2. Consolidation:

• The funds deposited by users are consolidated or swept into a hot withdrawal wallet. This is done to manage and organise the funds better. The destination wallet could be a cold wallet or a hot withdrawal wallet depending on the exchange requirements.
• For consolidation to be successful, a gas fee (transaction fee) is needed. The gas fee must be in native coins of the cryptocurrency being transacted.

3. Gas Station and Auto Fuel:

• The Gas Station ensures that the wallet addresses eligible for consolidation have the necessary gas fees. It automatically sprays native coins to these addresses based on predefined rules set or default rule value.
• It operates periodically, running a job every two hours to identify eligible deposit addresses and spray gas fees in those addresses.

4. Smart Features & Automation:

• The system uses smart features like auto refills and consolidations to manage funds efficiently between hot wallets and cold wallets.
  • These features are rule-based and can be automated to ensure smooth and efficient fund management. Learn more about Consolidation Rules.

5. Refill Wallet and Cold Wallet:

• Smart refill automations can transfer funds from the hot withdrawal wallet to the Refill Wallet and further to the Cold Wallet for secure storage.
• The Refill Wallet acts as a buffer, storing a substantial amount of funds, while the Cold Wallet stores the majority of the funds securely and is not accessed frequently.

6. User Withdrawals:

• When a user wants to withdraw funds from the exchange, the withdrawal is processed from the hot withdrawal wallet.
• The exchange have to ensure that the hot wallet have adequate gas for transaction processing.
• Liminal employs a Gas Fee Saver algorithm to optimise and save on the gas fees, especially for EVM-based withdrawals.
  This architecture and process ensure that the funds are managed efficiently, securely, and economically, optimizing the necessary transaction fees and automating many of the operational aspects of fund management.

Prerequisite

Before diving into the setup, ensure you have:

• Access to Liminal's platform.
• Necessary API keys and access permissions set up. Refer to Liminal Express Setup guide.
• Refer to the Onboarding Guide.

👍

One-Time Express Setup:

Please ensure that you complete the Liminal Express Guide and execute the Setup API signer APIs as a one-time prerequisite. Once this step is accomplished, you will be able to create hot wallets as needed.

Setting up Deposit Infrastructure

Setting up a robust deposit infrastructure is essential for exchanges to facilitate the seamless inflow of funds from customers. Liminal's infrastructure allows for the generation of multiple user deposit addresses, which can then be assigned to customers for depositing funds. These funds can subsequently be consolidated into a destination wallet, typically a cold wallet, for enhanced security. Funds can also be consolidated into a hot withdrawal wallet as per exchange requirements.

Create a Hot Deposit Wallet

1. Go to the 'Wallets' section of the API collection and access the 'Create Wallet' API.
2. Adjust the coin as needed and wallet type as 'Deposit'.
3. Execute the API to create a new deposit wallet.

Wallet Visibility: Accessible via UI and Get List of Wallet API endpoint.

Setup Address Generation and Assignment

Effortlessly guide your clients to their deposit destinations with Liminal's intuitive address setup:

1. Choose Your Deposit Wallet
   Start by selecting the deposit wallet Id that will act as the hub for incoming funds.
2. Generate Addresses with Ease
   Liminal offers two flexible APIs for address generation:
   • Single Address API: Perfect for individual allocations.
   • Multiple Address API: Ideal for bulk assignments.

In the context of exchange operations, it is essential to establish a mapping between the addresses and indices with the internal user accounts. This mapping ensures that when a deposit is made, the exchange can accurately identify the user associated with the deposit and credit the value into his/her exchange account.

Address generation follows a deterministic pattern. Consequently, blockchain networks that are interoperable, such as Ethereum and Matic, will produce identical addresses if they are provided with the same index. This deterministic nature of address generation is crucial for maintaining consistency across compatible blockchain platforms.

Dive into our Address Generation Guide for a detailed, step-by-step process.

Now, your clients can effortlessly deposit funds into their uniquely assigned addresses, kickstarting their investment journey with your exchange.

📘

API Response Integration:

Once your hot wallet is established, utilize the API response to assign specific deposit addresses with a child derivation path to each user, ensuring a personalised and secure deposit experience for your customers.

Transaction Confirmation and Account Crediting

Exchanges receive notifications of incoming deposits through webhooks. This ensures that you are promptly informed of all transactions, allowing for immediate reconciliation and credit to customer accounts.

For more details on setting up and using webhooks, see our comprehensive webhook guide.

Once the transaction has been confirmed, the final step is to credit the user's account. Upon receiving and validating the transaction Id, the client can immediately proceed to credit the user's account.

📘

Note:

If webhooks fail or are not feasible, use the getTransfer API as a fallback to check or initiate data transfers. Refer to the API documentation for guidance.

Consolidation Reference: For details on transferring funds from deposit wallets to cold storage, please consult our Consolidation Guide.

Processing Customer Withdrawals

When a customer requests a withdrawal from an exchange, the transaction is processed through a withdrawal hot wallet. These wallets are specialized for quick, secure transactions, keeping their keys online for immediate action. The wallet checks for sufficient funds, confirms the customer's details, and prepares to send the required funds.

A critical point to note is that the hot withdrawal wallet must hold a balance of the native coin (like ETH for Ethereum transactions) to cover the transaction's gas fee. This is essential for the process as gas fees are required for blockchain network transactions.

Liminal’s smart Gas Fee Saver Algorithm then steps in to optimise these fees, reducing costs by timing transactions during lower fee periods and setting a strategically low but viable fee that ensures transaction completion.

Access to the hot wallets is restricted to API interactions, which, along with MPC security, ensures that transactions are not only swift but also secure. With these measures, the exchange can process withdrawals efficiently, keeping costs down and customers satisfied.

Important: Our system utilises a single withdrawal wallet to process all customer transfer requests efficiently.

Create a Withdrawal Wallet

1. Navigate to the 'Wallets' folder and select 'Create Wallet' API.
2. Adjust the coin as needed and wallet type as 'Withdrawal'.
3. Execute the API to create a new withdrawal wallet.

Send Transaction

1. Before initiating a withdrawal request, verify the balance of the withdrawal wallet using the GetBalance API. For more information on how to use this, refer to the accompanying guide.
2. Once the balance is confirmed, initiate the withdrawal request via the SendMany API.
3. To monitor the status of the withdrawal request, consult the Get Pending Transaction API.
4. Process the transaction in the blockchain network and update the user's balance.

Move funds from Deposit Wallets (Consolidation)

Why is it needed?

Once your customer deposits funds and you have credited his/her account, the funds can be moved out of deposit wallets. This is done to secure the funds into more secure cold wallets and also to seamlessly process customer withdrawals. Liminal provides options for standard and smart consolidation to seamlessly facilitate this process.

Consolidation is a critical process for exchanges, involving the automatic transfer of assets from numerous deposit wallet addresses into a single, more secure wallet (cold wallet). This practice is not just about organisation—it's a strategic move to enhance security and operational efficiency.

The Advantages of Smart Consolidation

Liminal takes consolidation to the next level with smart features, allowing for:

• Multiple Destinations: Distribute assets across various wallets based on predefined rules.
• Spillover Control: Manage overflow by setting thresholds, beyond which funds move to alternate destinations.
• Threshold Configuration: Decide the minimum amount of funds to keep in deposit wallets, reducing risk.
• Gas Fee Management: Exercise control over the gas fees for consolidation transactions, optimizing costs.

Smart Consolidation: A Game-Changer for EVM Chains

While standard consolidation is available across all chains with a deposit wallet, smart consolidation shines on EVM-based chains like Ethereum and Polygon. It's designed to:

• Secure Assets: Automatically transfer excess funds into the fortress of cold storage.
• Balance Risk and Convenience: Keep the minimum required funds in the deposit wallet, with the bulk safeguarded in cold storage.

Key Points to Remember

• Currently, only EVM chains are equipped with smart consolidation capabilities.
• Non-EVM chains utilise standard consolidation to a single destination based on preset rules.

Smart Consolidation in Action for Exchanges

For exchanges, each user's funds are received at a unique deposit address. Post-deposit, the exchange's priority is the security of these funds. Smart consolidation steps in to elevate this security by:

1. Scanning User Deposits: It starts with a review of user deposit addresses holding funds.
2. Identifying Threshold Exceed: Addresses with funds above a certain value are flagged.
3. Automating Transfers: Funds are then automatically routed from deposit wallets to destination wallets—and predominantly to the more secure cold wallets.

This intelligent approach minimises the vulnerabilities of deposit wallets, ensures swift transfers, and significantly boosts overall security, making it an indispensable tool for exchanges in managing their internal fund movements.

Understanding Gas Stations for Exchanges

For any exchange, the flow of transactions is the lifeblood of operations. Gas fees on the blockchain are akin to fuel for these transactions, ensuring they are processed and confirmed. Liminal's Gas Station is an essential component that automates the management of these fees, ensuring your exchange's transactions are never stalled due to lack of gas.

Why Exchanges Need a Gas Station

Problem Statement:
Exchanges often face the challenge of efficiently transferring funds from user deposit addresses for operational use. These funds, scattered across various user addresses, need to be consolidated into a main wallet for exchange operations. This consolidation, or sweeping of funds, requires payment of a gas fee for each transaction on the blockchain. This is the point where a Gas Station becomes vital.

• Continuous Operations: The Gas Station ensures that there's always a reserve of native coins (e.g., ETH for Ethereum blockchain) available to pay for these gas fees. This is key to uninterrupted service, allowing transactions to be processed without delay due to insufficient gas.
• Fund Consolidation: For tasks like consolidating funds from multiple addresses, a Gas Station is indispensable. Although Gas Stations are not used for withdrawal wallets—which is managed by Liminal—it's a crucial component for deposit wallets, ensuring that every consolidation transaction has the necessary gas.
• Operational Efficiency: Automating the gas funding process, the Gas Station removes the need for manual top-ups of gas balances, thus freeing up resources and reducing the risk of human error. Your team can dedicate more time to other areas of the business instead of constantly monitoring gas levels.
• Sprayer Wallet Support: A further role of the Gas Station is to replenish the sprayer wallet automatically. The sprayer wallet is responsible for distributing gas to the user deposit addresses to enable the movement of funds. This step is automated, ensuring that consolidation actions are always ready to proceed without manual intervention.

📘

Note:

When dealing with token transactions, it is necessary to have the native coins available for gas fees to ensure a smooth transaction flow.

Workflow Note:
The Gas Station operates autonomously, transferring funds from the Customer-funded Cold Gas Station Wallet to the sprayer wallet based on predefined thresholds. This process is checked bi-hourly, ensuring continuous operation without manual intervention. Set up is straightforward, allowing for easy customization of thresholds and rules.

For detailed guidance on setting up and funding your Gas Station, as well as configuring custom rules, refer to the Gas Station Guide.

Exchange Fund Consolidation Workflow

1. Generate Deposit Addresses: Use the Generate Many Address API to create deposit addresses for users.
   Example: This code is for generating 100 Ethereum-compatible addresses for wallet Id 1.

{  
  "wallet": {  
    "coin": "eth",  
    "allToken": true,  
    "walletId": 1  
  },  
  "path": {  
    "startIndex": 1,  
    "endIndex": 100  
  }

For a detailed walkthrough, refer to our Address Generation Guide.

2. Monitor Customer Deposits: When customers deposit funds, you will receive webhook notifications. Ensure you have your webhook listener set up to capture and process these events for further processes.
   For more information on setting up webhooks, see our Webhook Setup Guide.
3. Set Consolidation Rules: Before consolidation, configure your rules in the Liminal dashboard. These rules determine how and when funds from deposit addresses are moved. If you do not set custom rules, default settings will apply.
   For a step-by-step on configuring rules, check out our Consolidation Rules Configuration Guide.

   📘

   Note:

   UTXO Consolidation Guide
   For UTXO-based chains, see our guide on consolidating Unspent Transaction Outputs (UTXOs) here.

   Non-UTXO Consolidation Guide
   For non-UTXO chains, find our guide on consolidating non-UTXO transactions here.

3. Understanding Gas Fees for Transactions:
   For native coin transactions, fees are taken from the transaction amount.
   For token transactions, if the deposit address does not have native coins for the transaction fee, the Gas Station Wallet will supply it.
   Learn how to manage gas fees by reading our Gas Fee Management Guide.
4. Implementing Consolidation: To automate the consolidation, you will need to set up a CRON job. Below is an example of a CRON job snippet in a Unix-like system for running a consolidation script for DAI token in deposit wallet with wallet Id 1 every 15 mins:

const cron = require('node-cron');  
const axios = require('axios');

// Define the API endpoint and request body  
const API_ENDPOINT = '<https://api-sdk.lmnl.dev/api/wallet/consolidate-transaction'>;  
const REQUEST_BODY = {  
    wallet: {  
        coin: "eth",  
        walletId: 1,  
        allToken: true,  
        tokenOptions: {  
            tokenName: "dai",  
            tokenAddress: "0xdc31Ee1784292379Fbb2964b3B9C4124D8F89C60"  
        }  
    },  
    transactions: {  
        consolidateOptions: {  
            targetAddress: "0x7f17be241f88530da74f035e8b74125ffedea98d"  
        }  
    }  
};

// Set up the CRON job to run every 15 minutes  
cron.schedule('_/15 _ \* \* \*', async () => {  
    try {  
        const response = await axios.post(API_ENDPOINT, REQUEST_BODY);  
        console.log('API called successfully:', response.data);  
    } catch (error) {  
        console.error('Error calling the API:', error);  
    }  
});

console.log('CRON job started. API will be called every 15 minutes.');

Important Information for Consolidation Process:

• When consolidating native coins, you may omit the tokenOptions object from the request body.
• For token consolidation, the tokenOptions object must be included, specifying tokenName and tokenAddress.

📘

Single-Operation Token Consolidation:

• To consolidate all tokens in one go, incorporate the allAssets parameter within the transactions object in the request body.
• This eliminates the need for setting up multiple cron jobs for different tokens; a single cron job will suffice to consolidate all tokens in the wallet.
  For further details and to learn how to set this up correctly, please refer to this link.

6. Check the Status of Transactions: To get the status of the consolidation transaction, you can call the Get Transaction Status API. Here's an example request:

{  
  "wallet": {  
    "coin": "eth",  
    "allToken": true,  
    "walletId": 1  
  },  
  "sequenceId": "08d5893b-0066-4619-b7af-a5bae54205d5"  
}

Note - You will also receive a webhook event when consolidation is completed.

FAQs: Addressing Your Concerns

Q: How does Liminal simplify onboarding?
A: With our plug-and-play APIs and dedicated support engineer, you can integrate Liminal's services rapidly, minimising downtime and technical challenges.

Q: Can Liminal help with the high costs of gas fees?
A: Absolutely. Our Gas Station feature automates the funding of wallets to manage gas fees efficiently, saving you from unexpected costs.

Q: What makes Liminal's consolidation feature stand out?
A: Liminal's smart consolidation allows for multiple destinations, threshold configurations, and gas fee control, providing a tailored and automated approach to fund management. Learn more about this here.