Bank

An ERC20 interface to native Cosmos SDK tokens for balance queries and supply information

Overview

The Bank precompile provides ERC20-style access to native Cosmos SDK tokens, enabling smart contracts to query balances and token supplies through standardized interfaces. It serves as a Solidity wrapper around the Cosmos SDK x/bank module.

Address: 0x0000000000000000000000000000000000000804

Related Module: x/bank

Gas Costs

• balances: 2,851 + (2,851 × (n-1)) where n = number of tokens returned
• totalSupply: 2,477 + (2,477 × (n-1)) where n = number of tokens returned
• supplyOf: 2,477

Primary Methods

balances

Signature: balances(address account) → Balance[] memory

Description: Queries all native token balances for a specific account address and returns an array of Balance (ERC-20 contract address & amount) structures.

Solidity

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

contract BankExample {
    address constant BANK_PRECOMPILE = 0x0000000000000000000000000000000000000804;
    
    struct Balance {
        address contractAddress;
        uint256 amount;
    }
    
    function getAccountBalances(address account) external view returns (Balance[] memory balances) {
        (bool success, bytes memory result) = BANK_PRECOMPILE.staticcall(
            abi.encodeWithSignature("balances(address)", account)
        );
        
        require(success, "Balance query failed");
        balances = abi.decode(result, (Balance[]));
        return balances;
    }
    
    // Convenience function to get caller's balances
    function getMyBalances() external view returns (Balance[] memory balances) {
        return this.getAccountBalances(msg.sender);
    }
}

Parameters:

• account (address): The account address to query balances for

Returns: Array of Balance structures with contractAddress and amount fields

totalSupply

Signature: totalSupply() → Balance[] memory

Description: Queries the total supply of all native tokens in the system. Returns comprehensive supply information for every token registered in the system.

Solidity

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

contract BankExample {
    address constant BANK_PRECOMPILE = 0x0000000000000000000000000000000000000804;
    
    struct Balance {
        address contractAddress;
        uint256 amount;
    }
    
    function getTotalSupply() external view returns (Balance[] memory totalSupply) {
        (bool success, bytes memory result) = BANK_PRECOMPILE.staticcall(
            abi.encodeWithSignature("totalSupply()")
        );
        
        require(success, "Total supply query failed");
        totalSupply = abi.decode(result, (Balance[]));
        return totalSupply;
    }
}

Parameters: None

Returns: Array of Balance structures showing total supply for each token

supplyOf

Signature: supplyOf(address erc20Address) → uint256

Description: Queries the total supply of a specific token by providing its ERC20 contract address. More efficient when you need supply information for a single token.

Solidity

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

contract BankExample {
    address constant BANK_PRECOMPILE = 0x0000000000000000000000000000000000000804;
    
    function getTokenSupply(address erc20Address) external view returns (uint256 supply) {
        (bool success, bytes memory result) = BANK_PRECOMPILE.staticcall(
            abi.encodeWithSignature("supplyOf(address)", erc20Address)
        );
        
        require(success, "Token supply query failed");
        supply = abi.decode(result, (uint256));
        return supply;
    }
    
    // Helper function to check if token exists (has supply > 0)
    function tokenExists(address erc20Address) external view returns (bool) {
        uint256 supply = this.getTokenSupply(erc20Address);
        return supply > 0;
    }
}

Parameters:

• erc20Address (address): The ERC20 contract address of the token

Returns: Total supply of the specified token as uint256

Data Structures ->

Balance

The Balance struct represents a token balance with its associated ERC20 contract address:

• contractAddress (address): The ERC20 contract address representing the native token
• amount (uint256): Token amount in the smallest denomination

Full Interface & ABI

Bank Solidity Interface

// SPDX-License-Identifier: LGPL-3.0-only
pragma solidity >=0.8.18;

/// @dev The IBank contract's address.
address constant IBANK_PRECOMPILE_ADDRESS = 0x0000000000000000000000000000000000000804;

/// @dev The IBank contract's instance.
IBank constant IBANK_CONTRACT = IBank(IBANK_PRECOMPILE_ADDRESS);

/// @dev Balance specifies the ERC20 contract address and the amount of tokens.
struct Balance {
    /// contractAddress defines the ERC20 contract address.
    address contractAddress;
    /// amount of tokens
    uint256 amount;
}

/**
 * @author Evmos Team
 * @title Bank Interface
 * @dev Interface for querying balances and supply from the Bank module.
 */
interface IBank {
    /// @dev balances defines a method for retrieving all the native token balances
    /// for a given account.
    /// @param account the address of the account to query balances for.
    /// @return balances the array of native token balances.
    function balances(
        address account
    ) external view returns (Balance[] memory balances);

    /// @dev totalSupply defines a method for retrieving the total supply of all
    /// native tokens.
    /// @return totalSupply the supply as an array of native token balances
    function totalSupply() external view returns (Balance[] memory totalSupply);

    /// @dev supplyOf defines a method for retrieving the total supply of a particular native coin.
    /// @return totalSupply the supply as a uint256
    function supplyOf(
        address erc20Address
    ) external view returns (uint256 totalSupply);
}

Bank ABI

{
  "_format": "hh-sol-artifact-1",
  "contractName": "IBank",
  "sourceName": "solidity/precompiles/bank/IBank.sol",
  "abi": [
    {
      "inputs": [
        {
          "internalType": "address",
          "name": "account",
          "type": "address"
        }
      ],
      "name": "balances",
      "outputs": [
        {
          "components": [
            {
              "internalType": "address",
              "name": "contractAddress",
              "type": "address"
            },
            {
              "internalType": "uint256",
              "name": "amount",
              "type": "uint256"
            }
          ],
          "internalType": "struct Balance[]",
          "name": "balances",
          "type": "tuple[]"
        }
      ],
      "stateMutability": "view",
      "type": "function"
    },
    {
      "inputs": [
        {
          "internalType": "address",
          "name": "erc20Address",
          "type": "address"
        }
      ],
      "name": "supplyOf",
      "outputs": [
        {
          "internalType": "uint256",
          "name": "totalSupply",
          "type": "uint256"
        }
      ],
      "stateMutability": "view",
      "type": "function"
    },
    {
      "inputs": [],
      "name": "totalSupply",
      "outputs": [
        {
          "components": [
            {
              "internalType": "address",
              "name": "contractAddress",
              "type": "address"
            },
            {
              "internalType": "uint256",
              "name": "amount",
              "type": "uint256"
            }
          ],
          "internalType": "struct Balance[]",
          "name": "totalSupply",
          "type": "tuple[]"
        }
      ],
      "stateMutability": "view",
      "type": "function"
    }
  ],
  "bytecode": "0x",
  "deployedBytecode": "0x",
  "linkReferences": {},
  "deployedLinkReferences": {}
}

Implementation Details

Token Resolution

The precompile resolves native Cosmos SDK denominations to their corresponding ERC-20 contract addresses through the x/erc20 module’s token pair registry. Only tokens with registered token pairs are returned in query results.

Decimal Precision

All amounts returned preserve the original decimal precision stored in the x/bank module. No decimal conversion is performed by the precompile.

Gas Metering

The precompile implements efficient gas metering by:

• Charging base gas for the first result
• Incrementally charging for each additional result in batch queries
• Consuming gas before returning results to prevent DoS vectors

Error Handling

• Invalid token addresses in supplyOf return 0 rather than reverting
• Queries for accounts with no balances return empty arrays
• All methods are read-only and cannot modify state