Bank - Cosmos Docs

概览

Bank 预编译提供了对原生 Cosmos SDK 代币的 ERC20 风格访问能力，使智能合约能够通过标准化接口查询余额和代币总供应量。它充当 Cosmos SDK x/bank 模块的 Solidity 封装。地址：0x0000000000000000000000000000000000000804 相关模块：x/bank

Gas 成本

balances：2,851 + (2,851 × (n-1))，其中 n = 返回的代币数量
totalSupply：2,477 + (2,477 × (n-1))，其中 n = 返回的代币数量
supplyOf：2,477

主要方法

balances

签名：balances(address account) → Balance[] memory 说明：查询指定账户地址的所有原生代币余额，并返回由 Balance（ERC-20 合约地址和数量）结构组成的数组。

// 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);
    }
}

参数：

account (address)：要查询余额的账户地址

返回值：包含 contractAddress 和 amount 字段的 Balance 结构体数组

totalSupply

签名：totalSupply() → Balance[] memory 说明：查询系统中所有原生代币的总供应量。返回系统中每个已注册代币的完整供应信息。

// 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;
    }
}

参数：无 返回值：显示每种代币总供应量的 Balance 结构体数组

supplyOf

签名：supplyOf(address erc20Address) → uint256 说明：通过提供特定代币的 ERC20 合约地址来查询其总供应量。当你只需要单个代币的供应信息时，这种方式效率更高。

// 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;
    }
}

参数：

erc20Address (address)：该代币的 ERC20 合约地址

返回值：指定代币的总供应量，类型为 uint256

数据结构 ->

Balance

Balance 结构体表示一个代币余额及其关联的 ERC20 合约地址：

contractAddress (address)：表示该原生代币的 ERC20 合约地址
amount (uint256)：以最小计量单位表示的代币数量

完整接口与 ABI

Bank Solidity 接口

// 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": {}
}

实现细节

代币解析

预编译会通过 x/erc20 模块的代币对注册表，将原生 Cosmos SDK denom 解析为对应的 ERC-20 合约地址。只有已注册代币对的代币才会在查询结果中返回。

小数精度

所有返回的数量都会保留 x/bank 模块中存储的原始小数精度。预编译不会执行任何小数转换。

Gas 计量

该预编译通过以下方式实现高效的 Gas 计量：

对首个结果收取基础 Gas
在批量查询中，对每个额外结果逐步增加收费
在返回结果前消耗 Gas，以防止 DoS 攻击向量

错误处理

supplyOf 中的无效代币地址会返回 0，而不是回退
对没有余额的账户进行查询时，会返回空数组
所有方法都是只读的，无法修改状态

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.

// 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.

// 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.

// 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

​概览

​Gas 成本

​主要方法

​balances

​totalSupply

​supplyOf

​数据结构 ->

​Balance

​完整接口与 ABI

​实现细节

​代币解析

​小数精度

​Gas 计量

​错误处理

​Overview

​Gas Costs

​Primary Methods

​balances

​totalSupply

​supplyOf

​Data Structures ->

​Balance

​Full Interface & ABI

​Implementation Details

​Token Resolution

​Decimal Precision

​Gas Metering

​Error Handling

概览

Gas 成本

主要方法

balances

totalSupply

supplyOf

数据结构 ->

Balance

完整接口与 ABI

实现细节

代币解析

小数精度

Gas 计量

错误处理

Overview

Gas Costs

Primary Methods

balances

totalSupply

supplyOf

Data Structures ->

Balance

Full Interface & ABI

Implementation Details

Token Resolution

Decimal Precision

Gas Metering

Error Handling