Bank Precompile - Sei Docs

Address: 0x0000000000000000000000000000000000001001 The Sei bank precompile allows EVM applications to interact directly with Sei’s native banking system through standard smart contract calls. This enables querying balances, transferring tokens, and accessing token metadata for both native SEI tokens and Cosmos SDK-based assets, providing seamless integration between EVM and Cosmos ecosystems.

What is a precompile? A precompile is a special smart contract deployed at a fixed address by the Sei protocol itself, that exposes custom native chain logic to EVM-based applications. It acts like a regular contract from the EVM’s perspective, but executes privileged, low-level logic efficiently.

How Does the Bank Precompile Work?

The bank precompile at address 0x0000000000000000000000000000000000001001 exposes functions like send(), sendNative(), balance(), all_balances(), and token metadata queries.

Direct Integration: EVM contracts and dApps can call banking functions like any other smart contract method.
Native Execution: Operations are executed at the Cosmos SDK level for maximum efficiency and security.
Cross-Chain Assets: Manage both native SEI tokens and IBC assets seamlessly from EVM contracts.

When to use send vs sendNative: send moves an arbitrary denom (any IBC or factory token) between two EVM addresses (0x...) by reading the balance directly from the bank module — no msg.value is attached. It is gated to the registered ERC20 native pointer for that denom, so it is typically invoked from the auto-deployed pointer contract rather than from arbitrary user code. sendNative is for sending native SEI (the attached msg.value) from the EVM caller to a Cosmos bech32 (sei1...) destination, which is useful for crossing the EVM→Cosmos boundary when the recipient has no associated EVM address (for example, paying a Cosmos-only contract or account).

Use Cases

DeFi Applications: Build decentralized finance protocols that can handle native SEI and Cosmos assets.
Portfolio Management: Build tools to track and manage multi-asset portfolios across Cosmos and EVM.
Token Information Services: Query comprehensive token metadata for UI display and analytics.

What You’ll Learn in This Guide

By the end of this guide, you’ll be able to:

Execute Token Transfers - Send both native SEI and custom tokens between addresses
Query Account Balances - Check single and multi-asset balances for any address
Access Token Metadata - Retrieve names, symbols, decimals, and supply information

Functions

The bank precompile exposes the following functions:

Transaction Functions

/// Sends non-native tokens from one address to another. Callable only by the
/// registered ERC20 native pointer contract for the given denom.
/// @param fromAddress The EVM address (0x...) to send funds from.
/// @param toAddress The EVM address (0x...) to send funds to.
/// @param denom The denomination of funds to send.
/// @param amount The amount of the above denom to send.
/// @return success Whether the send was successfully executed.
function send(
    address fromAddress,
    address toAddress,
    string memory denom,
    uint256 amount
) external returns (bool success);

/// Sends native SEI (the attached msg.value) from the EVM caller to a Cosmos
/// bech32 recipient. Requires a non-zero msg.value.
/// @param toNativeAddress The bech32 (sei1...) address of the recipient.
/// @return success Whether the tokens were successfully sent.
function sendNative(
    string memory toNativeAddress
) payable external returns (bool success);

Query Functions

/// Queries the balance of the given account for the specified denom.
/// @param acc The EVM address (0x...) of the account to query.
/// @param denom The denomination to query for.
/// @return amount The amount of denom held by acc.
function balance(
    address acc,
    string memory denom
) external view returns (uint256 amount);

/// Queries the balance of the given account for all balances.
/// @param acc The EVM address (0x...) of the account to query.
/// @return response Balances for all coins/denoms.
function all_balances(
    address acc
) external view returns (Coin[] memory response);

/// Queries the name of the specified denom.
/// @param denom The denomination to query about.
/// @return response The name of the specified denom.
function name(
    string memory denom
) external view returns (string memory response);

/// Queries the symbol of the specified denom.
/// @param denom The denomination to query about.
/// @return response The symbol of the specified denom.
function symbol(
    string memory denom
) external view returns (string memory response);

/// Queries the number of decimal places for the specified denom.
/// @param denom The denomination to query about.
/// @return response The number of decimals for the specified denom.
function decimals(
    string memory denom
) external view returns (uint8 response);

/// Queries the total supply of the specified denom.
/// @param denom The denomination to query about.
/// @return response The total supply of the specified denom.
function supply(
    string memory denom
) external view returns (uint256 response);

Using the Precompile

Setup

Prerequisites

Before getting started, ensure you have:

Node.js (v18 or higher)
npm or yarn package manager
EVM-compatible wallet
SEI tokens for gas and testing transfers
Hardhat for development and testing

Install Dependencies

Install the required packages for interacting with Sei precompiles:

# Instantiate a new Hardhat 3 project (choose "Hardhat 3" and the Mocha + Ethers.js TypeScript setup)
npx hardhat --init

# Install ethers.js for smart contract interactions
npm install ethers

# Install Sei EVM bindings for precompile addresses and ABIs
npm install @sei-js/precompiles@2.1.2

Setup Hardhat Environment

Create a hardhat.config.ts file with the following content:

import { defineConfig, configVariable } from 'hardhat/config';
import hardhatToolboxMochaEthers from '@nomicfoundation/hardhat-toolbox-mocha-ethers';

export default defineConfig({
  solidity: '0.8.28',
  networks: {
    sei: {
      type: 'http',
      chainId: 1329,
      url: 'https://evm-rpc.sei-apis.com',
      accounts: [configVariable('PRIVATE_KEY')]
    }
  },
  plugins: [hardhatToolboxMochaEthers]
});

Store your private key in Hardhat’s encrypted keystore (no plaintext .env file needed):

npx hardhat keystore set PRIVATE_KEY

Import Precompile Components

JavaScript
Solidity

// Import Bank precompile address and ABI
// View the entire ABI here: https://github.com/sei-protocol/sei-chain/tree/main/precompiles/bank
import { BANK_PRECOMPILE_ABI, BANK_PRECOMPILE_ADDRESS } from '@sei-js/precompiles';
import { ethers } from 'ethers';

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.0;

struct Coin {
uint256 amount;
string denom;
}

interface IBankPrecompile {
function send(
address fromAddress,
address toAddress,
string memory denom,
uint256 amount
) external returns (bool success);

    function sendNative(
        string memory toNativeAddress
    ) payable external returns (bool success);

    function balance(
        address acc,
        string memory denom
    ) external view returns (uint256 amount);

    function all_balances(
        address acc
    ) external view returns (Coin[] memory response);

    function name(
        string memory denom
    ) external view returns (string memory response);

    function symbol(
        string memory denom
    ) external view returns (string memory response);

    function decimals(
        string memory denom
    ) external view returns (uint8 response);

    function supply(
        string memory denom
    ) external view returns (uint256 response);

}

Precompile Address: The bank precompile is deployed at 0x0000000000000000000000000000000000001001

Contract Initialization

JavaScript
Solidity

Set up your provider, signer, and contract instance:

// Using EVM-compatible wallet as the signer and provider
const provider = new ethers.BrowserProvider(window.ethereum);
await provider.send('eth_requestAccounts', []);
const signer = await provider.getSigner();

// Create a contract instance for the bank precompile
const bank = new ethers.Contract(BANK_PRECOMPILE_ADDRESS, BANK_PRECOMPILE_ABI, signer);

// Initialize the contract instance in your Solidity code
contract TokenManager {
    IBankPrecompile constant BANK = IBankPrecompile(0x0000000000000000000000000000000000001001);
}

Native SEI vs Custom Tokens

Native SEI Transfers:

Use sendNative() with payable value
Denomination is always usei (micro-SEI)
Parse to 18 digits when calling sendNative()

Custom Token Transfers:

Use send() with specific denomination
Requires prior token approval or ownership
Support various decimal configurations

Step-by-Step Guide: Using the Bank Precompile

Send Native SEI Tokens

JavaScript
Solidity

// Send native SEI tokens to another address
const recipientAddress = 'sei1qqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqq6s8dpw';
const amountInSei = '0.1'; // 0.1 SEI

try {
  // msg.value is in wei (18 decimals), like any other EVM transaction
  const amountInWei = ethers.parseUnits(amountInSei, 18); // equivalent to ethers.parseEther(amountInSei)

  // Send native SEI
  const tx = await bank.sendNative(recipientAddress, {
    value: amountInWei,
    gasLimit: 300000n
  });

  const receipt = await tx.wait();
  console.log('Native SEI transfer successful:', receipt.hash);
  console.log(`Sent ${amountInSei} SEI to ${recipientAddress}`);
} catch (error) {
  console.error('Native SEI transfer failed:', error);
}

contract PaymentProcessor {
    IBankPrecompile constant BANK = IBankPrecompile(0x0000000000000000000000000000000000001001);

    event PaymentSent(address indexed from, string to, uint256 amount);

    function sendSeiPayment(string memory recipient) external payable {
        require(msg.value > 0, "Payment amount must be greater than 0");

        bool success = BANK.sendNative{value: msg.value}(recipient);
        require(success, "Payment failed");

        emit PaymentSent(msg.sender, recipient, msg.value);
    }
}

Send Custom Tokens

JavaScript
Solidity

send() can only be called by the registered ERC20 native pointer contract for the given denom — calling it from a regular wallet will revert. The snippet below only illustrates the arguments a pointer contract passes. As a user, transfer native denoms through the denom’s ERC20 pointer contract (transfer()), or use sendNative() for SEI.

// Illustration: how a registered ERC20 pointer contract calls send()
const fromAddress = '0x1234567890123456789012345678901234567890';
const toAddress = '0x9876543210987654321098765432109876543210';
const tokenDenom = 'usei';
const amount = '1';

// Amounts are in the denom's base units — check decimals() for each denom.
// usei has 6 decimals (1 SEI = 1,000,000 usei)
const tx = await bank.send(
  fromAddress,
  toAddress,
  tokenDenom,
  ethers.parseUnits(amount, 6),
  {
    gasLimit: 300000n
  }
);

const receipt = await tx.wait();
console.log('Custom token transfer successful:', receipt.hash);
console.log(`Sent ${amount} ${tokenDenom} from ${fromAddress} to ${toAddress}`);

contract TokenTransferManager {
    IBankPrecompile constant BANK = IBankPrecompile(0x0000000000000000000000000000000000001001);

    event TokenTransfer(
        address indexed from,
        address indexed to,
        string denom,
        uint256 amount
    );

    function transferTokens(
        address to,
        string memory denom,
        uint256 amount
    ) external {
        // Transfer tokens from sender to recipient
        bool success = BANK.send(msg.sender, to, denom, amount);
        require(success, "Token transfer failed");

        emit TokenTransfer(msg.sender, to, denom, amount);
    }

    function batchTransfer(
        address[] memory recipients,
        string memory denom,
        uint256[] memory amounts
    ) external {
        require(recipients.length == amounts.length, "Array length mismatch");

        for (uint256 i = 0; i < recipients.length; i++) {
            bool success = BANK.send(msg.sender, recipients[i], denom, amounts[i]);
            require(success, "Batch transfer failed");

            emit TokenTransfer(msg.sender, recipients[i], denom, amounts[i]);
        }
    }
}

Query Account Balance

JavaScript
Solidity

// Query specific token balance
const accountAddress = '0x1234567890123456789012345678901234567890';
const tokenDenom = 'usei';

try {
  const balance = await bank.balance(accountAddress, tokenDenom);

  // Convert usei to SEI for display
  if (tokenDenom === 'usei') {
    const seiBalance = ethers.formatUnits(balance, 6);
    console.log(`SEI Balance: ${seiBalance} SEI`);
  } else {
    console.log(`${tokenDenom} Balance: ${balance.toString()}`);
  }
} catch (error) {
  console.error('Balance query failed:', error);
}

contract BalanceChecker {
    IBankPrecompile constant BANK = IBankPrecompile(0x0000000000000000000000000000000000001001);

    function getUserSeiBalance(address user) external view returns (uint256) {
        return BANK.balance(user, "usei");
    }

    function getUserTokenBalance(
        address user,
        string memory denom
    ) external view returns (uint256) {
        return BANK.balance(user, denom);
    }

    function hasMinimumBalance(
        address user,
        string memory denom,
        uint256 minAmount
    ) external view returns (bool) {
        uint256 balance = BANK.balance(user, denom);
        return balance >= minAmount;
    }
}

Query All Balances

JavaScript
Solidity

// Query all token balances for an account
const accountAddress = '0x1234567890123456789012345678901234567890';

try {
  const allBalances = await bank.all_balances(accountAddress);

  console.log(`Account: ${accountAddress}`);
  console.log('All Balances:');

  allBalances.forEach((coin, index) => {
    if (coin.denom === 'usei') {
      const seiAmount = ethers.formatUnits(coin.amount, 6);
      console.log(`  ${index + 1}. ${seiAmount} SEI (${coin.denom})`);
    } else {
      console.log(`  ${index + 1}. ${coin.amount.toString()} ${coin.denom}`);
    }
  });
} catch (error) {
  console.error('All balances query failed:', error);
}

contract PortfolioManager {
    IBankPrecompile constant BANK = IBankPrecompile(0x0000000000000000000000000000000000001001);

    struct Portfolio {
        address owner;
        Coin[] balances;
        uint256 totalValue; // In usei equivalent
    }

    function getPortfolio(address user) external view returns (Coin[] memory) {
        return BANK.all_balances(user);
    }

    function hasAnyBalance(address user) external view returns (bool) {
        Coin[] memory balances = BANK.all_balances(user);
        return balances.length > 0;
    }

    function countTokenTypes(address user) external view returns (uint256) {
        Coin[] memory balances = BANK.all_balances(user);
        return balances.length;
    }

    function findTokenBalance(
        address user,
        string memory targetDenom
    ) external view returns (uint256) {
        Coin[] memory balances = BANK.all_balances(user);

        for (uint256 i = 0; i < balances.length; i++) {
            if (keccak256(bytes(balances[i].denom)) == keccak256(bytes(targetDenom))) {
                return balances[i].amount;
            }
        }

        return 0; // Token not found
    }
}

Query Token Metadata

JavaScript
Solidity

// Query comprehensive token metadata
const tokenDenom = 'usei';

try {
  // Get all metadata in parallel
  const [name, symbol, decimals, totalSupply] = await Promise.all([bank.name(tokenDenom), bank.symbol(tokenDenom), bank.decimals(tokenDenom), bank.supply(tokenDenom)]);

  console.log('Token Metadata:');
  console.log(`  Denomination: ${tokenDenom}`);
  console.log(`  Name: ${name}`);
  console.log(`  Symbol: ${symbol}`);
  console.log(`  Decimals: ${decimals}`);
  console.log(`  Total Supply: ${ethers.formatUnits(totalSupply, decimals)}`);
} catch (error) {
  console.error('Metadata query failed:', error);
}

// Function to get formatted token info
async function getTokenInfo(denom) {
  try {
    const metadata = {
      denom: denom,
      name: await bank.name(denom),
      symbol: await bank.symbol(denom),
      decimals: await bank.decimals(denom),
      supply: await bank.supply(denom)
    };

    return {
      ...metadata,
      formattedSupply: ethers.formatUnits(metadata.supply, metadata.decimals)
    };
  } catch (error) {
    console.error(`Failed to get info for ${denom}:`, error);
    return null;
  }
}

contract TokenRegistry {
    IBankPrecompile constant BANK = IBankPrecompile(0x0000000000000000000000000000000000001001);

    struct TokenInfo {
        string denom;
        string name;
        string symbol;
        uint8 decimals;
        uint256 totalSupply;
        bool isValid;
    }

    mapping(string => TokenInfo) public tokenRegistry;

    function getTokenInfo(
        string memory denom
    ) external view returns (TokenInfo memory) {
        TokenInfo memory info;

        info.denom = denom;
        info.name = BANK.name(denom);
        info.symbol = BANK.symbol(denom);
        info.decimals = BANK.decimals(denom);
        info.totalSupply = BANK.supply(denom);
        info.isValid = true;

        return info;
    }
}

Complete Integration Example

JavaScript
Solidity

import { BANK_PRECOMPILE_ABI, BANK_PRECOMPILE_ADDRESS } from '@sei-js/precompiles';
import { ethers } from 'ethers';

class SeiTokenManager {
  private bank: ethers.Contract;
  private signer: ethers.Signer;

  constructor(signer: ethers.Signer) {
    this.signer = signer;
    this.bank = new ethers.Contract(BANK_PRECOMPILE_ADDRESS, BANK_PRECOMPILE_ABI, signer);
  }

  // Send native SEI tokens
  async sendSei(recipientAddress: string, amountInSei: string) {
    try {
      const amountInWei = ethers.parseUnits(amountInSei, 18);
      const tx = await this.bank.sendNative(recipientAddress, {
        value: amountInWei,
        gasLimit: 100000
      });

      const receipt = await tx.wait();
      return {
        success: true,
        transactionHash: receipt.hash,
        amount: amountInSei,
        recipient: recipientAddress
      };
    } catch (error) {
      return { success: false, error: error.message };
    }
  }

  // Get user's portfolio
  async getPortfolio(address: string) {
    try {
      const balances = await this.bank.all_balances(address);
      const portfolio = [];

      for (const coin of balances) {
        try {
          const metadata = await this.getTokenMetadata(coin.denom);
          portfolio.push({
            denom: coin.denom,
            amount: coin.amount.toString(),
            formattedAmount: ethers.formatUnits(coin.amount, metadata.decimals),
            ...metadata
          });
        } catch (metadataError) {
          // If metadata fails, still include the balance
          portfolio.push({
            denom: coin.denom,
            amount: coin.amount.toString(),
            formattedAmount: coin.amount.toString(),
            name: 'Unknown',
            symbol: 'Unknown',
            decimals: 0
          });
        }
      }

      return { success: true, portfolio };
    } catch (error) {
      return { success: false, error: error.message };
    }
  }

  // Get token metadata
  async getTokenMetadata(denom: string) {
    const [name, symbol, decimals, supply] = await Promise.all([this.bank.name(denom).catch(() => 'Unknown'), this.bank.symbol(denom).catch(() => 'Unknown'), this.bank.decimals(denom).catch(() => 0), this.bank.supply(denom).catch(() => 0n)]);

    return { name, symbol, decimals, supply: supply.toString() };
  }

  // Transfer custom tokens
  async transferToken(toAddress: string, denom: string, amount: string, decimals: number = 18) {
    try {
      const fromAddress = await this.signer.getAddress();
      const parsedAmount = ethers.parseUnits(amount, decimals);

      const tx = await this.bank.send(fromAddress, toAddress, denom, parsedAmount, {
        gasLimit: 150000
      });

      const receipt = await tx.wait();
      return {
        success: true,
        transactionHash: receipt.hash,
        from: fromAddress,
        to: toAddress,
        denom,
        amount
      };
    } catch (error) {
      return { success: false, error: error.message };
    }
  }

  // Batch operations
  async batchBalanceCheck(addresses: string[], denom: string) {
    try {
      const balances = await Promise.allSettled(addresses.map((addr) => this.bank.balance(addr, denom)));

      return balances.map((result, index) => ({
        address: addresses[index],
        balance: result.status === 'fulfilled' ? result.value.toString() : '0',
        success: result.status === 'fulfilled'
      }));
    } catch (error) {
      throw new Error(`Batch balance check failed: ${error.message}`);
    }
  }
}

// Usage example
async function bankExample() {
  const provider = new ethers.BrowserProvider(window.ethereum);
  await provider.send('eth_requestAccounts', []);
  const signer = await provider.getSigner();
  const tokenManager = new SeiTokenManager(signer);

  console.log('=== Sei Token Manager Demo ===');

  // 1. Get current user's portfolio
  const userAddress = await signer.getAddress();
  const portfolio = await tokenManager.getPortfolio(userAddress);

  if (portfolio.success) {
    console.log('User Portfolio:');
    portfolio.portfolio.forEach((token, index) => {
      console.log(`  ${index + 1}. ${token.formattedAmount} ${token.symbol} (${token.name})`);
    });
  }

  // 2. Send native SEI
  const sendResult = await tokenManager.sendSei('sei1qqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqq6s8dpw', '0.01');

  if (sendResult.success) {
    console.log('SEI transfer successful:', sendResult.transactionHash);
  }

  // 3. Check balances for multiple addresses
  const addresses = ['0x1234567890123456789012345678901234567890', '0x9876543210987654321098765432109876543210'];

  const batchBalances = await tokenManager.batchBalanceCheck(addresses, 'usei');
  console.log('Batch balance results:', batchBalances);
}

Complete Contract Example

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.0;

interface IBankPrecompile {
    function send(address fromAddress, address toAddress, string memory denom, uint256 amount) external returns (bool success);
    function sendNative(string memory toNativeAddress) payable external returns (bool success);
    function balance(address acc, string memory denom) external view returns (uint256 amount);
    function all_balances(address acc) external view returns (Coin[] memory response);
    function name(string memory denom) external view returns (string memory response);
    function symbol(string memory denom) external view returns (string memory response);
    function decimals(string memory denom) external view returns (uint8 response);
    function supply(string memory denom) external view returns (uint256 response);
}

struct Coin {
    uint256 amount;
    string denom;
}

contract ComprehensiveTokenManager {
    IBankPrecompile constant BANK = IBankPrecompile(0x0000000000000000000000000000000000001001);

    // Events
    event PaymentProcessed(address indexed from, string to, uint256 amount, string denom);
    event TokenTransfer(address indexed from, address indexed to, string denom, uint256 amount);
    event BatchTransferCompleted(address indexed sender, uint256 totalRecipients);

    // State variables
    mapping(address => bool) public authorizedOperators;
    mapping(string => bool) public supportedTokens;
    address public owner;

    modifier onlyOwner() {
        require(msg.sender == owner, "Only owner can execute");
        _;
    }

    modifier onlyAuthorized() {
        require(authorizedOperators[msg.sender] || msg.sender == owner, "Not authorized");
        _;
    }

    constructor() {
        owner = msg.sender;
        authorizedOperators[msg.sender] = true;
        supportedTokens["usei"] = true;
    }

    // =============
    // Payment Functions
    // =============

    function processPayment(
        string memory recipient,
        uint256 amount
    ) external payable {
        require(msg.value >= amount, "Insufficient payment");

        bool success = BANK.sendNative{value: amount}(recipient);
        require(success, "Payment failed");

        // Refund excess
        if (msg.value > amount) {
            payable(msg.sender).transfer(msg.value - amount);
        }

        emit PaymentProcessed(msg.sender, recipient, amount, "usei");
    }

    function processTokenPayment(
        address recipient,
        string memory denom,
        uint256 amount
    ) external onlyAuthorized {
        require(supportedTokens[denom], "Token not supported");

        bool success = BANK.send(msg.sender, recipient, denom, amount);
        require(success, "Token payment failed");

        emit TokenTransfer(msg.sender, recipient, denom, amount);
    }

    // =============
    // Batch Operations
    // =============

    function batchSeiTransfer(
        string[] memory recipients,
        uint256[] memory amounts
    ) external payable {
        require(recipients.length == amounts.length, "Array length mismatch");
        require(recipients.length <= 50, "Too many recipients");

        uint256 totalAmount = 0;
        for (uint256 i = 0; i < amounts.length; i++) {
            totalAmount += amounts[i];
        }
        require(msg.value >= totalAmount, "Insufficient total payment");

        for (uint256 i = 0; i < recipients.length; i++) {
            bool success = BANK.sendNative{value: amounts[i]}(recipients[i]);
            require(success, "Batch transfer failed");

            emit PaymentProcessed(msg.sender, recipients[i], amounts[i], "usei");
        }

        // Refund excess
        if (msg.value > totalAmount) {
            payable(msg.sender).transfer(msg.value - totalAmount);
        }

        emit BatchTransferCompleted(msg.sender, recipients.length);
    }

    function batchTokenTransfer(
        address[] memory recipients,
        string memory denom,
        uint256[] memory amounts
    ) external onlyAuthorized {
        require(recipients.length == amounts.length, "Array length mismatch");
        require(recipients.length <= 20, "Too many recipients");
        require(supportedTokens[denom], "Token not supported");

        for (uint256 i = 0; i < recipients.length; i++) {
            bool success = BANK.send(msg.sender, recipients[i], denom, amounts[i]);
            require(success, "Batch token transfer failed");

            emit TokenTransfer(msg.sender, recipients[i], denom, amounts[i]);
        }

        emit BatchTransferCompleted(msg.sender, recipients.length);
    }

    // =============
    // Query Functions
    // =============

    function getUserPortfolio(address user) external view returns (Coin[] memory) {
        return BANK.all_balances(user);
    }

    function getUserBalance(address user, string memory denom) external view returns (uint256) {
        return BANK.balance(user, denom);
    }

    function getTokenInfo(string memory denom) external view returns (
        string memory name,
        string memory symbol,
        uint8 decimals,
        uint256 totalSupply
    ) {
        name = BANK.name(denom);
        symbol = BANK.symbol(denom);
        decimals = BANK.decimals(denom);
        totalSupply = BANK.supply(denom);
    }

    function checkSufficientBalance(
        address user,
        string memory denom,
        uint256 requiredAmount
    ) external view returns (bool) {
        uint256 balance = BANK.balance(user, denom);
        return balance >= requiredAmount;
    }

    function batchBalanceCheck(
        address[] memory users,
        string memory denom
    ) external view returns (uint256[] memory balances) {
        balances = new uint256[](users.length);
        for (uint256 i = 0; i < users.length; i++) {
            balances[i] = BANK.balance(users[i], denom);
        }
    }

    // =============
    // Admin Functions
    // =============

    function addSupportedToken(string memory denom) external onlyOwner {
        supportedTokens[denom] = true;
    }

    function removeSupportedToken(string memory denom) external onlyOwner {
        supportedTokens[denom] = false;
    }

    function addOperator(address operator) external onlyOwner {
        authorizedOperators[operator] = true;
    }

    function removeOperator(address operator) external onlyOwner {
        require(operator != owner, "Cannot remove owner");
        authorizedOperators[operator] = false;
    }

    // Emergency withdraw function
    function emergencyWithdraw() external onlyOwner {
        payable(owner).transfer(address(this).balance);
    }

    // =============
    // Utility Functions
    // =============

    function convertSeiToUsei(uint256 seiAmount) pure external returns (uint256) {
        return seiAmount * 1e6;
    }

    function convertUseiToSei(uint256 useiAmount) pure external returns (uint256) {
        return useiAmount / 1e6;
    }

    receive() external payable {}
}

Compile the contract:

npx hardhat compile

Deployment ScriptFirst, deploy the contract using Hardhat:

import { network } from 'hardhat';

// Hardhat 3 exposes ethers through a network connection rather than a global import
const { ethers } = await network.create();

async function main() {
  // The signer comes from the network config (encrypted keystore)
  const [deployer] = await ethers.getSigners();
  console.log('Deploying contracts with the account:', deployer.address);

  const balance = await deployer.provider.getBalance(deployer.address);
  console.log('Account balance:', ethers.formatEther(balance));

  const ComprehensiveTokenManager = await ethers.getContractFactory('ComprehensiveTokenManager');
  console.log('Deploying ComprehensiveTokenManager...', ComprehensiveTokenManager);
  const comprehensiveTokenManager = await ComprehensiveTokenManager.deploy({
    gasLimit: 5000000n // Set a reasonable gas limit
  });
  await comprehensiveTokenManager.waitForDeployment();

  console.log('ComprehensiveTokenManager deployed to:', await comprehensiveTokenManager.getAddress());
}

main().catch((error) => {
  console.error(error);
  process.exitCode = 1;
});

To deploy, run:

npx hardhat run scripts/deploy.js --network sei

Next look through the integration example:

import { network } from 'hardhat';
import TokenManager from './artifacts/contracts/ComprehensiveTokenManager.sol/ComprehensiveTokenManager.json' with { type: 'json' };

// Hardhat 3 exposes ethers through a network connection rather than a global import
const { ethers } = await network.create();

async function main() {
  // The signer comes from the network config (encrypted keystore)
  const [deployer] = await ethers.getSigners();
  console.log('Interacting with the account:', deployer.address);

  const address = '0xYourDeployedContractAddress'; // Replace with your contract address
  const tokenManager = new ethers.Contract(address, TokenManager.abi, deployer);
  console.log('TokenManager deployed to:', address);

  // Add some supported tokens
  const tokens = ['usei', 'uatom', 'ubtc'];

  for (const token of tokens) {
    try {
      const tx = await tokenManager.addSupportedToken(token);
      await tx.wait();
      console.log('Added supported token:', token);
    } catch (error) {
      console.error('Failed to add token:', token, error.message);
    }
  }

  try {
    const allBalances = await tokenManager.getUserPortfolio(deployer.address);
    console.log('All balances:', allBalances);
  } catch (error) {
    console.error('Failed to get user portfolio:', error.message);
  }
}

main()
  .then(() => process.exit(0))
  .catch((error) => {
    console.error(error);
    process.exit(1);
  });

Then run the integration example:

npx hardhat run scripts/integrationExample.js --network sei

Security Considerations & Risks

Transaction Security

Amount Validation: Always validate transfer amounts and ensure sufficient balances
Address Verification: Verify recipient addresses are valid before sending tokens
Reentrancy Protection: Be aware of potential reentrancy when combining with other contracts

Permission Management

// Example of secure permission patterns
modifier onlyTokenHolder(string memory denom, uint256 minAmount) {
    require(BANK.balance(msg.sender, denom) >= minAmount, "Insufficient token balance");
    _;
}

modifier validRecipient(address recipient) {
    require(recipient != address(0), "Invalid recipient");
    require(recipient != address(this), "Cannot send to contract");
    _;
}

Troubleshooting

Common Issues and Solutions

Transaction Failures

// Handle common transfer errors
try {
  const tx = await bank.sendNative(recipient, { value: amount });
  await tx.wait();
} catch (error) {
  if (error.message.includes('insufficient funds')) {
    console.error('Insufficient balance for transfer');
  } else if (error.message.includes('invalid address')) {
    console.error('Invalid recipient address format');
  } else {
    console.error('Transfer failed:', error.message);
  }
}

Balance Query Issues

// Safe balance checking with error handling
async function safeGetBalance(address: string, denom: string) {
  try {
    const balance = await bank.balance(address, denom);
    return { success: true, balance: balance.toString() };
  } catch (error) {
    if (error.message.includes('not found')) {
      return { success: true, balance: '0' }; // No balance = 0
    }
    return { success: false, error: error.message };
  }
}

Error Code Reference

Error	Cause	Solution
`insufficient funds`	Not enough balance for transfer	Check balance before transfer
`invalid address`	Malformed address format	Use proper EVM (0x…) or Sei (sei1…) format
`unknown denomination`	Token denom doesn’t exist	Verify token denomination format
`amount overflow`	Amount exceeds uint256 limits	Use appropriate amount ranges
`metadata not found`	Token metadata not available	Handle missing metadata gracefully

Important Notes

Remember: Always verify token denominations and handle errors gracefully in production applications!

SEI Native: While reading from chain it is formatted to 6 decimal places (1 SEI = 1,000,000 usei) and while writing to chain it is parsed to 18 decimal places.
Custom Tokens: Check decimals using decimals() function
Display Formatting: Always format amounts with proper decimal places for user display

Gas Optimization

Batch Operations: Use batch functions for multiple operations to save gas
Query Efficiency: Cache frequently accessed token metadata
Error Handling: Implement proper error handling to avoid failed transaction costs

Integration Best Practices

Balance Checks: Always verify sufficient balance before transfers
Error Recovery: Implement retry logic for failed transactions
User Experience: Provide clear feedback on transaction status
Decimal Handling: Use proper decimal formatting for different token types

View the Bank precompile source code and the contract ABI here.

​How Does the Bank Precompile Work?

​Use Cases

​What You’ll Learn in This Guide

​Functions

​Transaction Functions

​Query Functions

​Using the Precompile

​Setup

​Prerequisites

​Install Dependencies

​Setup Hardhat Environment

​Import Precompile Components

​Contract Initialization

​Native SEI vs Custom Tokens

​Step-by-Step Guide: Using the Bank Precompile

​Send Native SEI Tokens

​Send Custom Tokens

​Query Account Balance

​Query All Balances

​Query Token Metadata

​Complete Integration Example

​Security Considerations & Risks

​Transaction Security

​Permission Management

​Troubleshooting

​Common Issues and Solutions

​Transaction Failures

​Balance Query Issues

​Error Code Reference

​Important Notes

​Gas Optimization

​Integration Best Practices

How Does the Bank Precompile Work?

Use Cases

What You’ll Learn in This Guide

Functions

Transaction Functions

Query Functions

Using the Precompile

Setup

Prerequisites

Install Dependencies

Setup Hardhat Environment

Import Precompile Components

Contract Initialization

Native SEI vs Custom Tokens

Step-by-Step Guide: Using the Bank Precompile

Send Native SEI Tokens

Send Custom Tokens

Query Account Balance

Query All Balances

Query Token Metadata

Complete Integration Example

Security Considerations & Risks

Transaction Security

Permission Management

Troubleshooting

Common Issues and Solutions

Transaction Failures

Balance Query Issues

Error Code Reference

Important Notes

Gas Optimization

Integration Best Practices