bank

package
v0.7.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: May 5, 2026 License: Apache-2.0 Imports: 11 Imported by: 13

README

Bank Precompile

Address

0x0000000000000000000000000000000000000804

Description

The Bank precompile provides read-only access to the Cosmos SDK x/bank module state through an EVM-compatible interface. This enables smart contracts to query native token balances and supply information for accounts and tokens registered with corresponding ERC-20 representations.

Interface

Methods
balances
function balances(address account) external view returns (Balance[] memory)

Retrieves all native token balances for the specified account. Each balance includes the ERC-20 contract address and amount in the token's original precision.

Parameters:

  • account: The account address to query

Returns:

  • Array of Balance structs containing:
    • contractAddress: ERC-20 contract address representing the native token
    • amount: Token balance in smallest denomination

Gas Cost: 2,851 + (2,851 × (n-1)) where n = number of tokens returned

totalSupply
function totalSupply() external view returns (Balance[] memory)

Retrieves the total supply of all native tokens in the system.

Parameters: None

Returns:

  • Array of Balance structs containing:
    • contractAddress: ERC-20 contract address representing the native token
    • amount: Total supply in smallest denomination

Gas Cost: 2,477 + (2,477 × (n-1)) where n = number of tokens returned

supplyOf
function supplyOf(address erc20Address) external view returns (uint256)

Retrieves the total supply of a specific token by its ERC-20 contract address.

Parameters:

  • erc20Address: The ERC-20 contract address of the token

Returns:

  • Total supply as uint256. Returns 0 if the token is not registered.

Gas Cost: 2,477

Data Structures
struct Balance {
    address contractAddress;  // ERC-20 contract address
    uint256 amount;          // Amount in smallest denomination
}

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

Documentation

Index

Constants

View Source 
const (
	// GasBalances defines the gas cost for a single ERC-20 balanceOf query
	GasBalances = 2_851

	// GasTotalSupply defines the gas cost for a single ERC-20 totalSupply query
	GasTotalSupply = 2_477

	// GasSupplyOf defines the gas cost for a single ERC-20 supplyOf query, taken from totalSupply of ERC20
	GasSupplyOf = 2_477
)
View Source 
const (
	// BalancesMethod defines the ABI method name for the bank Balances
	// query.
	BalancesMethod = "balances"
	// TotalSupplyMethod defines the ABI method name for the bank TotalSupply
	// query.
	TotalSupplyMethod = "totalSupply"
	// SupplyOfMethod defines the ABI method name for the bank SupplyOf
	// query.
	SupplyOfMethod = "supplyOf"
)

Variables

View Source 
var (
	ABI abi.ABI
)

Functions

func ParseBalancesArgs 

func ParseBalancesArgs(args []interface{}) (sdk.AccAddress, error)

ParseBalancesArgs parses the call arguments for the bank Balances query.

func ParseSupplyOfArgs 

func ParseSupplyOfArgs(args []interface{}) (common.Address, error)

ParseSupplyOfArgs parses the call arguments for the bank SupplyOf query.

Types

type Balance 

type Balance struct {
	ContractAddress common.Address
	Amount          *big.Int
}

Balance contains the amount for a corresponding ERC-20 contract address.

type Precompile 

type Precompile struct {
	cmn.Precompile

	abi.ABI
	// contains filtered or unexported fields
}

Precompile defines the bank precompile

func NewPrecompile 

func NewPrecompile(
	bankKeeper cmn.BankKeeper,
	erc20Keeper cmn.ERC20Keeper,
) *Precompile

NewPrecompile creates a new bank Precompile instance implementing the PrecompiledContract interface.

func (Precompile) Balances 

func (p Precompile) Balances(
	ctx sdk.Context,
	method *abi.Method,
	args []interface{},
) ([]byte, error)

Balances returns given account's balances of all tokens registered in the x/bank module and the corresponding ERC20 address (address, amount). The amount returned for each token has the original decimals precision stored in the x/bank. This method charges the account the corresponding value of an ERC-20 balanceOf call for each token returned.

func (Precompile) Execute added in v0.5.0 

func (p Precompile) Execute(ctx sdk.Context, contract *vm.Contract, readOnly bool) ([]byte, error)

Execute executes the precompiled contract bank query methods defined in the ABI.

func (Precompile) IsTransaction 

func (Precompile) IsTransaction(_ *abi.Method) bool

IsTransaction checks if the given method name corresponds to a transaction or query. It returns false since all bank methods are queries.

func (Precompile) Name added in v0.7.0 

func (p Precompile) Name() string

func (Precompile) RequiredGas 

func (p Precompile) RequiredGas(input []byte) uint64

RequiredGas calculates the precompiled contract's base gas rate.

func (Precompile) Run 

func (p Precompile) Run(evm *vm.EVM, contract *vm.Contract, readonly bool) ([]byte, error)

func (Precompile) SupplyOf 

func (p Precompile) SupplyOf(
	ctx sdk.Context,
	method *abi.Method,
	args []interface{},
) ([]byte, error)

SupplyOf returns the total supply of a given registered erc20 token from the x/bank module. If the ERC20 token doesn't have a registered TokenPair, the method returns a supply of zero. The amount returned with this query has the original decimals precision stored in the x/bank.

func (Precompile) TotalSupply 

func (p Precompile) TotalSupply(
	ctx sdk.Context,
	method *abi.Method,
	_ []interface{},
) ([]byte, error)

TotalSupply returns the total supply of all tokens registered in the x/bank module. The amount returned for each token has the original decimals precision stored in the x/bank. This method charges the account the corresponding value of a ERC-20 totalSupply call for each token returned.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.