models.go

Overview

The `models.go` file defines the core data structures (models) used to represent Cosmos SDK blockchain entities within the application. These models encapsulate detailed information about accounts, transactions, staking, validators, and related blockchain events and states in a structured format. Each model corresponds closely to Cosmos SDK concepts and is annotated for automatic API documentation generation (Swagger).

This file primarily provides type definitions, with no functions or methods, serving as a foundational layer for serialization, deserialization, and manipulation of Cosmos blockchain data throughout the system.

Detailed Explanation of Models

Account

Represents a Cosmos SDK account with detailed blockchain state.

type Account struct {
	api.BaseAccount
	AccountNumber int     `json:"accountNumber"` // Unique account number on chain
	Sequence      int     `json:"sequence"`      // Sequence number for replay protection
	Assets        []Value `json:"assets"`        // List of assets owned by the account
}

Parameters:
- AccountNumber: Integer identifier assigned by the blockchain.
- Sequence: Integer incremented with each transaction to prevent replay.
- Assets: Slice of Value representing tokens held by the account.
Usage: Used to represent and query account details such as balances and transaction sequence.

Attribute

Represents a key-value pair inside a transaction log event.

type Attribute struct {
	Key   string `json:"key"`   // Attribute key, e.g., "action"
	Value string `json:"value"` // Attribute value, e.g., "/cosmos.bank.v1beta1.MsgSend"
}

Usage: Captures event details emitted during transactions for indexing and filtering.

ValueByAttribute

A map of attribute keys to their string values.

type ValueByAttribute map[string]string

Usage: Facilitates grouping of event attributes by their keys.

Delegation

Represents a staking delegation from an account to a validator.

type Delegation struct {
	Validator *Validator `json:"validator"` // Validator being delegated to
	Shares    string     `json:"shares"`    // Amount of shares delegated (string decimal)
	Balance   Value      `json:"balance"`   // Token balance delegated
}

Usage: Used when querying staking delegations and their balances.

EventsByMsgIndex

Maps message index (as a string) to event attributes.

type EventsByMsgIndex map[string]AttributesByEvent

Usage: Organizes transaction events by the index of the message within that transaction.

Event

Represents a transaction event with type and attributes.

type Event struct {
	Type       string      `json:"type"`       // Event type, e.g., "message"
	Attributes []Attribute `json:"attributes"` // List of key-value attributes
}

Usage: Represents individual events emitted during transaction execution.

AttributesByEvent

Maps event types to their attributes grouped by attribute key.

type AttributesByEvent map[string]ValueByAttribute

Usage: Used for grouping event attributes by event type in transaction logs.

Info

Represents general information about the Cosmos SDK blockchain.

type Info struct {
	api.BaseInfo
}

Usage: Contains metadata about the running blockchain node or chain.

Message

Represents a message inside a transaction, encapsulating the actual blockchain action.

type Message struct {
	Addresses []string `json:"-"`       // Addresses involved (not serialized)
	Index     string   `json:"index"`   // Message index within the transaction
	Origin    string   `json:"origin"`  // Origin address or source
	From      string   `json:"from"`    // Sender address
	To        string   `json:"to"`      // Recipient address
	Type      string   `json:"type"`    // Message type, e.g., "/cosmos.bank.v1beta1.MsgSend"
	Value     Value    `json:"value"`   // Value transferred in the message
}

Usage: Used to parse and represent individual transaction messages.

Redelegation

Represents a redelegation of stake from one validator to another.

type Redelegation struct {
	SourceValidator      *Validator          `json:"sourceValidator"`      // Validator where stake is moved from
	DestinationValidator *Validator          `json:"destinationValidator"` // Validator where stake is moved to
	Entries              []RedelegationEntry `json:"entries"`              // List of redelegation entries
}

Usage: Represents redelegation actions in staking.

RedelegationEntry

Represents a single redelegation action entry.

type RedelegationEntry struct {
	CompletionTime string `json:"completionTime"` // Timestamp when redelegation completes
	Shares         string `json:"shares"`         // Amount of shares redelegated
	Balance        string `json:"balance"`        // Associated balance
}

Usage: Represents detailed redelegation steps with timing and amounts.

Reward

Represents staking rewards for a validator.

type Reward struct {
	Validator *Validator `json:"validator"` // Validator rewarded
	Rewards   []Value    `json:"rewards"`   // List of reward values
}

Usage: Used to represent rewards accrued from staking.

Staking

Represents the current staking state for an account.

type Staking struct {
	Delegations   []Delegation   `json:"delegations"`   // List of active delegations
	Redelegations []Redelegation `json:"redelegations"` // List of redelegations
	Unbondings    []Unbonding    `json:"unbondings"`    // List of unbondings
	Rewards       []Reward       `json:"rewards"`       // List of rewards
}

Usage: Aggregates staking-related information in one structure.

Tx (Transaction)

Represents a blockchain transaction.

type Tx struct {
	api.BaseTx
	Confirmations int              `json:"confirmations"` // Number of confirmations
	Fee           Value            `json:"fee"`           // Transaction fee
	GasUsed       string           `json:"gasUsed"`       // Gas actually used
	GasWanted     string           `json:"gasWanted"`     // Gas requested
	Index         int              `json:"index"`         // Transaction index
	Memo          string           `json:"memo,omitempty"`// Optional memo
	Value         string           `json:"value"`         // Total value transferred
	Messages      []Message        `json:"messages"`      // List of messages in tx
	Events        EventsByMsgIndex `json:"events"`        // Events grouped by message index
}

Usage: Central structure to represent transactions including messages and events.

TxHistory

Represents transaction history for an address or extended public key.

type TxHistory struct {
	api.BaseTxHistory
	Txs []Tx `json:"txs"` // List of transactions
}

Usage: Used when querying the transaction history for an account.

TxParam

Parameter object for querying a transaction by hash.

type TxParam struct {
	TxID string `json:"txid"` // Transaction hash (required)
}

Usage: Used in API endpoints to specify transaction IDs.

Unbonding

Represents an unbonding delegation.

type Unbonding struct {
	Validator *Validator       `json:"validator"` // Validator from which unbonding occurs
	Entries   []UnbondingEntry `json:"entries"`   // Unbonding entries
}

Usage: Used to represent the unbonding process in staking.

UnbondingEntry

Represents a single unbonding action.

type UnbondingEntry struct {
	CompletionTime string `json:"completionTime"` // When unbonding completes
	Balance        Value  `json:"balance"`        // Balance being unbonded
}

Usage: Details each unbonding step with timing and amount.

ValidatorUnbonding

Represents validator-specific unbonding info.

type ValidatorUnbonding struct {
	Height    int `json:"height"`    // Block height of unbonding
	Timestamp int `json:"timestamp"` // Unix timestamp of unbonding
}

Usage: Metadata on unbonding state for validators.

ValidatorCommission

Represents commission parameters for a validator.

type ValidatorCommission struct {
	Rate          string `json:"rate"`          // Current commission rate
	MaxRate       string `json:"maxRate"`       // Maximum allowed commission
	MaxChangeRate string `json:"maxChangeRate"` // Max change allowed for commission
}

Usage: Used for validator commission configurations.

Validators

Represents a paginated list of validators.

type Validators struct {
	api.Pagination
	Validators []Validator `json:"validators"` // List of validators
}

Usage: Used when fetching or listing validators with pagination.

Validator

Represents details about a single validator.

type Validator struct {
	Address     string              `json:"address"`     // Validator operator address
	Moniker     string              `json:"moniker"`     // Validator display name
	Jailed      bool                `json:"jailed"`      // Jail status
	Status      string              `json:"status"`      // Bonding status (e.g., BOND_STATUS_BONDED)
	Tokens      string              `json:"tokens"`      // Number of tokens delegated
	Shares      string              `json:"shares"`      // Total shares
	Website     string              `json:"website"`     // Validator website URL
	Description string              `json:"description"` // Validator description
	APR         string              `json:"apr"`         // Annual percentage rate
	Unbonding   ValidatorUnbonding  `json:"unbonding"`   // Unbonding info
	Commission  ValidatorCommission `json:"commission"`  // Commission info
}

Usage: Used to represent and query validator information.

Value

Represents an asset value with amount and denomination.

type Value struct {
	Amount string `json:"amount"` // Amount as a string (to preserve precision)
	Denom  string `json:"denom"`  // Denomination (token symbol)
}

Usage: Used throughout models to represent token amounts and types.

Important Implementation Details

All amount/values are stored as strings to avoid floating-point precision issues typical in blockchain token amounts.
Models use embedded structures from api package (BaseAccount, BaseInfo, BaseTx, BaseTxHistory, Pagination) to inherit common fields and metadata.
Swagger annotations (swagger:model, swagger:allOf) are used extensively for automatic API documentation generation.
Some fields are omitted from JSON serialization with json:"-" to keep internal data private from API consumers (e.g., Addresses in Message).
Maps such as EventsByMsgIndex and AttributesByEvent are used to group related event data efficiently by message index and event type.

Interaction with Other Parts of the System

These models serve as the data contracts between the Cosmos blockchain API layer and the internal application logic.
The models are used for parsing responses from Cosmos SDK RPC endpoints or REST APIs.
They are integral in the transaction processing pipeline to interpret transaction contents, events, and staking states.
The api package types embedded here provide common blockchain fields ensuring consistency across different coin implementations.
These models are consumed by service layers to provide user-facing features such as account balances, transaction histories, staking management, and validator information.

Example Usage

// Example: Creating an Account with assets
acc := cosmos.Account{
    AccountNumber: 420,
    Sequence:      69,
    Assets: []cosmos.Value{
        {Amount: "1000000", Denom: "uatom"},
    },
}

// Example: Representing a transaction with messages and events
tx := cosmos.Tx{
    Confirmations: 5,
    Fee:           cosmos.Value{Amount: "5000", Denom: "uatom"},
    GasUsed:       "20000",
    GasWanted:     "25000",
    Index:         1,
    Value:         "1000000",
    Messages: []cosmos.Message{
        {
            Index:  "0",
            Origin: "cosmos1senderaddress",
            From:   "cosmos1senderaddress",
            To:     "cosmos1recipientaddress",
            Type:   "/cosmos.bank.v1beta1.MsgSend",
            Value:  cosmos.Value{Amount: "1000000", Denom: "uatom"},
        },
    },
    Events: cosmos.EventsByMsgIndex{
        "0": cosmos.AttributesByEvent{
            "message": cosmos.ValueByAttribute{
                "action": "/cosmos.bank.v1beta1.MsgSend",
            },
        },
    },
}

Diagram: Class Structure of models.go

classDiagram
    class Account {
        +int AccountNumber
        +int Sequence
        +[]Value Assets
    }
    class Attribute {
        +string Key
        +string Value
    }
    class Delegation {
        +Validator Validator
        +string Shares
        +Value Balance
    }
    class Event {
        +string Type
        +[]Attribute Attributes
    }
    class Message {
        +string Index
        +string Origin
        +string From
        +string To
        +string Type
        +Value Value
    }
    class Redelegation {
        +Validator SourceValidator
        +Validator DestinationValidator
        +[]RedelegationEntry Entries
    }
    class RedelegationEntry {
        +string CompletionTime
        +string Shares
        +string Balance
    }
    class Reward {
        +Validator Validator
        +[]Value Rewards
    }
    class Staking {
        +[]Delegation Delegations
        +[]Redelegation Redelegations
        +[]Unbonding Unbondings
        +[]Reward Rewards
    }
    class Tx {
        +int Confirmations
        +Value Fee
        +string GasUsed
        +string GasWanted
        +int Index
        +string Memo
        +string Value
        +[]Message Messages
        +EventsByMsgIndex Events
    }
    class TxHistory {
        +[]Tx Txs
    }
    class Unbonding {
        +Validator Validator
        +[]UnbondingEntry Entries
    }
    class UnbondingEntry {
        +string CompletionTime
        +Value Balance
    }
    class ValidatorUnbonding {
        +int Height
        +int Timestamp
    }
    class ValidatorCommission {
        +string Rate
        +string MaxRate
        +string MaxChangeRate
    }
    class Validators {
        +[]Validator Validators
    }
    class Validator {
        +string Address
        +string Moniker
        +bool Jailed
        +string Status
        +string Tokens
        +string Shares
        +string Website
        +string Description
        +string APR
        +ValidatorUnbonding Unbonding
        +ValidatorCommission Commission
    }
    class Value {
        +string Amount
        +string Denom
    }

    Account --|> api.BaseAccount
    Info --|> api.BaseInfo
    Tx --|> api.BaseTx
    TxHistory --|> api.BaseTxHistory
    Validators --|> api.Pagination

    Delegation --> Validator
    Redelegation --> Validator
    Redelegation --> RedelegationEntry
    Reward --> Validator
    Staking --> Delegation
    Staking --> Redelegation
    Staking --> Unbonding
    Staking --> Reward
    Tx --> Message
    Tx --> EventsByMsgIndex
    Unbonding --> Validator
    Unbonding --> UnbondingEntry
    Validator --> ValidatorUnbonding
    Validator --> ValidatorCommission

Summary

The `models.go` file is a comprehensive collection of Cosmos SDK blockchain data models designed to facilitate the representation, transmission, and processing of blockchain entities such as accounts, transactions, staking information, and validators. It forms a critical foundation for the application's interaction with Cosmos blockchain data and supports rich querying and analytics features by structuring complex blockchain concepts into manageable Go types.