bank.go

Overview

The `bank.go` file is part of the `cosmos` package and provides a set of utility methods to query blockchain-related financial data from a Cosmos SDK-based blockchain via HTTP REST API calls. It primarily interacts with the LCD (Light Client Daemon) REST endpoints to retrieve information about token supply, staking, distribution parameters, and minting provisions.

Each method in this file belongs to an `HTTPClient` receiver and performs a specific query by sending an HTTP GET request to the corresponding Cosmos SDK REST endpoint. The responses are unmarshaled into internal Go structs, and key values are extracted and returned as strings.

This file abstracts the complexity of direct REST API calls and JSON parsing, offering a clean, simple interface to obtain financial metrics from the Cosmos blockchain.

Details of Types and Methods

Type: HTTPClient

• Description:
  The HTTPClient type is assumed (from context) to be a struct that wraps a REST client instance (LCD) used for making HTTP requests to the Cosmos SDK REST API. The exact definition of HTTPClient is not included in this file but is essential for all methods herein.

Method: GetTotalSupply

func (c *HTTPClient) GetTotalSupply(denom string) (string, error)

• Purpose:
  Retrieves the total supply amount of a specific token denomination (denom) from the blockchain.

• Parameters:

  • denom (string): The token denomination identifier, e.g., "atom" or "uatom".

• Returns:

  • string: The total supply amount as a string (usually a large integer represented as a string).

  • error: An error if the HTTP request or JSON unmarshalling fails.

• Usage Example:

  supply, err := client.GetTotalSupply("uatom")
  if err != nil {
      log.Fatal(err)
  }
  fmt.Println("Total supply of uatom:", supply)
  

• Implementation Details:

  • Sends a GET request to /cosmos/bank/v1beta1/supply/by_denom with query parameter denom.

  • The JSON response is expected to have the structure:

    {
      "amount": {
        "amount": "<string>",
        "denom": "<string>"
      }
    }
    

  • Returns the "amount.amount" field value.

Method: GetAnnualProvisions

func (c *HTTPClient) GetAnnualProvisions() (string, error)

• Purpose:
  Fetches the annual provisions value, which typically represents the yearly minted token amount used by the inflation/minting module of the blockchain.

• Parameters:
  None.

• Returns:

  • string: Annual provisions amount as a string.

  • error: If the request or unmarshalling fails.

• Usage Example:

  provisions, err := client.GetAnnualProvisions()
  if err != nil {
      log.Fatal(err)
  }
  fmt.Println("Annual provisions:", provisions)
  

• Implementation Details:

  • Sends a GET request to /cosmos/mint/v1beta1/annual_provisions.

  • Expects a JSON response with "annual_provisions" field.

Method: GetCommunityTax

func (c *HTTPClient) GetCommunityTax() (string, error)

• Purpose:
  Retrieves the community tax parameter, which is a fraction of rewards allocated to the community pool in the Cosmos SDK distribution module.

• Parameters:
  None.

• Returns:

  • string: Community tax as a string representing a decimal fraction (e.g., "0.02" for 2%).

  • error: On failure.

• Usage Example:

  tax, err := client.GetCommunityTax()
  if err != nil {
      log.Fatal(err)
  }
  fmt.Println("Community tax:", tax)
  

• Implementation Details:

  • Calls /cosmos/distribution/v1beta1/params endpoint.

  • Expects response JSON with nested "params" object containing "community_tax".

Method: GetBondedTokens

func (c *HTTPClient) GetBondedTokens() (string, error)

• Purpose:
  Obtains the total number of bonded tokens, i.e., tokens staked by validators and delegators in the staking pool.

• Parameters:
  None.

• Returns:

  • string: Amount of bonded tokens as a string.

  • error: If request fails.

• Usage Example:

  bondedTokens, err := client.GetBondedTokens()
  if err != nil {
      log.Fatal(err)
  }
  fmt.Println("Bonded tokens:", bondedTokens)
  

• Implementation Details:

  • Sends GET request to /cosmos/staking/v1beta1/pool.

  • Expects JSON with "pool" object containing "bonded_tokens".

Important Implementation Notes

• Each method uses the c.LCD.R() pattern, likely a REST client builder pattern (e.g., from the resty HTTP client), chained with .SetResult() for automatic JSON unmarshalling.

• Error handling wraps low-level errors with context messages using github.com/pkg/errors.

• All returned token amounts and parameters are strings. This design avoids issues with numeric overflow and preserves precision, as blockchain token amounts often use high-precision decimals or large integers.

• The file only contains read-only query functions; there are no write or transaction-related methods.

• The REST endpoints used correspond exactly to standard Cosmos SDK REST endpoints for bank, mint, distribution, and staking modules.

Interaction with Other System Components

• The HTTPClient struct must be properly initialized with a configured LCD REST client (c.LCD), which handles HTTP transport, base URL, authentication (if any), and other settings.

• This file acts as a data access layer for blockchain economic state information in Cosmos-based applications.

• Higher-level business logic or user interface components can invoke these methods to display blockchain metrics or perform calculations.

• The error-wrapping approach helps propagate detailed errors up the call stack for debugging or user notification.

Visual Diagram

classDiagram
    class HTTPClient {
        +GetTotalSupply(denom string) string, error
        +GetAnnualProvisions() string, error
        +GetCommunityTax() string, error
        +GetBondedTokens() string, error
    }

    %% Indicate that HTTPClient depends on LCD REST client internally (not shown in file)
    class LCDClient {
        +R() *Request
    }

    HTTPClient --> LCDClient : uses

Summary

The `bank.go` file provides a concise and robust interface to retrieve key blockchain economic parameters from a Cosmos SDK blockchain via REST API calls. It encapsulates various domain-specific queries related to token supply, inflation, community tax, and staking pool statistics, returning results as strings with consistent error handling. It depends on an HTTP REST client abstraction (`LCD`) and serves as a foundational component for applications interacting with Cosmos blockchain financial data.