Cosmos EVM

https://github.com/zeta-chain/evm
Admin
Cosmos EVM is a plug-and-play solution that adds EVM compatibility and customizability to your...
Tokens:15,678
Snippets:58
Trust Score:9.6
License:Apache-2.0
Update:1 year ago
Show doc for...
Tokens:
Raw
### Run Example Cosmos EVM Chain

Source: https://github.com/zeta-chain/evm/blob/main/evmd/README.md

Executes the local node script to run the example Cosmos EVM chain. Supports flags for database overwriting, binary installation, and remote debugging.

```bash
./local_node.sh [FLAGS]

Available flags:
- -y: Overwrite previous database
- -n: Do not overwrite previous database
- --no-install: Skip installation of the binary
- --remote-debugging: Build a binary suitable for remote debugging
```

--------------------------------

### Cosmos EVM Integration Guide

Source: https://github.com/zeta-chain/evm/blob/main/README.md

Information on how to integrate Cosmos EVM into an existing or new Cosmos SDK chain by importing it as a Go module library. The Interchain Labs team provides integration guides and core protocol support.

```go
import (
    // ... other imports
    "github.com/zeta-chain/evm"
)

// Initialize Cosmos EVM module
// ... configuration and setup ...
```

--------------------------------

### Bank Precompile Integration Test Suite Setup (Go)

Source: https://github.com/zeta-chain/evm/blob/main/tests/integration/README.md

Demonstrates how to set up and run integration tests for the Bank Precompile using the provided test harness. It shows how to create a custom application instance and pass it to the test suite.

```go
package integration

import (
    "testing"

    "github.com/stretchr/testify/suite"
    "github.com/cosmos/evm/tests/integration/precompiles/bank"
)

func TestBankPrecompileTestSuite(t *testing.T) {
    s := bank.NewPrecompileTestSuite(CreateEvmd)
    suite.Run(t, s)
}

func TestBankPrecompileIntegrationTestSuite(t *testing.T) {
    bank.TestIntegrationSuite(t, CreateEvmd)
}
```

--------------------------------

### EVMConfigurator Usage Example

Source: https://github.com/zeta-chain/evm/blob/main/evmd/eips/README.md

Demonstrates how to use the EVMConfigurator with the builder pattern to customize EVM settings, including extended EIPs and default extra EIPs.

```go
configurator := evmconfig.NewEVMConfigurator().
    WithExtendedEips(customActivators).
    WithExtendedDefaultExtraEIPs(defaultEnabledEIPs...). 
    Configure()

err := configurator.Configure()
```

--------------------------------

### Simulating IBC Functionality Example

Source: https://github.com/zeta-chain/evm/blob/main/testutil/ibc/README.md

Demonstrates a basic simulation of IBC functionality, including setting up a path, sending packets, receiving packets, acknowledging receipts, and relaying packets between chains.

```go
path := ibctesting.NewPath(suite.chainA, suite.chainB) // clientID, connectionID, channelID empty
suite.coordinator.Setup(path) // clientID, connectionID, channelID filled
suite.Require().Equal("07-tendermint-0", path.EndpointA.ClientID)
suite.Require().Equal("connection-0", path.EndpointA.ClientID)
suite.Require().Equal("channel-0", path.EndpointA.ClientID)

// send on endpointA
sequence, err := path.EndpointA.SendPacket(timeoutHeight1, timeoutTimestamp1, packet1Data)

// create packet 1 
packet1 := NewPacket() // NewPacket would construct your packet

// receive on endpointB
path.EndpointB.RecvPacket(packet1)

// acknowledge the receipt of the packet
path.EndpointA.AcknowledgePacket(packet1, ack)

// we can also relay
sequence, err := path.EndpointA.SendPacket(timeoutHeight2, timeoutTimestamp2, packet2Data)

packet2 := NewPacket()

path.RelayPacket(packet2)

// if needed we can update our clients
path.EndpointB.UpdateClient()
```

--------------------------------

### SimApp Implementation of TestingApp Interface

Source: https://github.com/zeta-chain/evm/blob/main/testutil/ibc/README.md

Provides an example implementation of the TestingApp interface for a SimApp. This demonstrates how to expose necessary components like BaseApp, StakingKeeper, IBCKeeper, and TxConfig to the testing framework.

```go
// TestingApp functions
// Example using SimApp to implement TestingApp

// GetBaseApp implements the TestingApp interface.
func (app *SimApp) GetBaseApp() *baseapp.BaseApp {
  return app.BaseApp
}

// GetStakingKeeper implements the TestingApp interface.
func (app *SimApp) GetStakingKeeper() ibctestingtypes.Keeper {
  return app.StakingKeeper
}

// GetIBCKeeper implements the TestingApp interface.
func (app *SimApp) GetIBCKeeper() *ibckeeper.Keeper {
  return app.IBCKeeper
}

// GetTxConfig implements the TestingApp interface.
func (app *SimApp) GetTxConfig() client.TxConfig {
  return app.txConfig
}
```

--------------------------------

### Setup Transfer Testing App in Go

Source: https://github.com/zeta-chain/evm/blob/main/testutil/ibc/README.md

Configures a testing application for IBC transfer module, including setting up the database, encoding configuration, and default genesis state. This function is intended to be used within a testing framework.

```go
package transfertesting

import (
  "encoding/json"

  "github.com/cometbft/cometbft/libs/log"
  dbm "github.com/cometbft/cometbft-db"

  "github.com/cosmos/ibc-go/v10/modules/apps/transfer/simapp"
  ibctesting "github.com/cosmos/ibc-go/v10/testing"
)

func SetupTransferTestingApp() (ibctesting.TestingApp, map[string]json.RawMessage) {
  db := dbm.NewMemDB()
  encCdc := simapp.MakeTestEncodingConfig()
  app := simapp.NewSimApp(
    log.NewNopLogger(),
    db,
    nil,
    true,
    map[int64]bool{},
    simapp.DefaultNodeHome,
    5,
    encCdc,
    simapp.EmptyAppOptions{},
  )
  return app, simapp.NewDefaultGenesisState(encCdc.Marshaler)
}

func init() {
  ibctesting.DefaultTestingAppInit = SetupTransferTestingApp
}

func NewTransferPath(chainA, chainB *ibctesting.TestChain) *ibctesting.Path {
  path := ibctesting.NewPath(chainA, chainB)
  path.EndpointA.ChannelConfig.PortID = ibctesting.TransferPort
  path.EndpointB.ChannelConfig.PortID = ibctesting.TransferPort

  return path
}

func GetTransferSimApp(chain *ibctesting.TestChain) *simapp.SimApp {
  app, ok := chain.App.(*simapp.SimApp)
  if !ok {
  panic("not transfer app")
  }

  return app
}
```

--------------------------------

### Clean Smart Contract Artifacts

Source: https://github.com/zeta-chain/evm/blob/main/scripts/compile_smart_contracts/README.md

Cleans up generated artifacts, installed dependencies, and cached files related to smart contract compilation.

```bash
make contracts-clean
```

--------------------------------

### Compile Smart Contracts

Source: https://github.com/zeta-chain/evm/blob/main/scripts/compile_smart_contracts/README.md

Compiles all smart contracts found in the repository using a Hardhat setup. It collects contracts, copies them for compilation, and then copies the resulting JSON data back to the source locations. Only overwrites existing JSON files.

```bash
make contracts-compile
```

--------------------------------

### Modifying Operation Constant Gas

Source: https://github.com/zeta-chain/evm/blob/main/evmd/eips/README.md

Example of a custom EIP that modifies the constant gas cost for the CREATE opcode. It uses the SetConstantGas method to update the operation's gas cost.

```go
// Enable a custom EIP-0000
func Enable0000(jt *vm.JumpTable) {
	jt[vm.CREATE].SetConstantGas(1)
}
```

--------------------------------

### SetupTest for KeeperTestSuite

Source: https://github.com/zeta-chain/evm/blob/main/testutil/ibc/README.md

Initializes the testing environment for KeeperTestSuite by creating a coordinator with two test chains.

```go
// SetupTest creates a coordinator with 2 test chains.
func (suite *KeeperTestSuite) SetupTest() {
  suite.coordinator = ibctesting.NewCoordinator(suite.T(), 2) // initializes 2 test chains
  suite.chainA = suite.coordinator.GetChain(ibctesting.GetChainID(1)) // convenience and readability
  suite.chainB = suite.coordinator.GetChain(ibctesting.GetChainID(2)) // convenience and readability
}
```

--------------------------------

### Error Handling for EVMConfigurator

Source: https://github.com/zeta-chain/evm/blob/main/evmd/eips/README.md

Shows how to handle errors during EVM configuration, suggesting to panic if an error occurs as the configuration happens before node startup.

```go
if err != nil {
    panic(err)
}
```

--------------------------------

### Initialize TestingApp with SimApp

Source: https://github.com/zeta-chain/evm/blob/main/testutil/ibc/README.md

Provides a function to initialize the TestingApp using ibc-go's SimApp. It returns the TestingApp instance and its default genesis state.

```go
func SetupTestingApp() (TestingApp, map[string]json.RawMessage) {
	db := dbm.NewMemDB()
	app := simapp.NewSimApp(log.NewNopLogger(), db, nil, true, simtestutil.EmptyAppOptions{})
	return app, app.DefaultGenesis()
}
```

--------------------------------

### EVM Creation with Configuration

Source: https://github.com/zeta-chain/evm/blob/main/evmd/eips/README.md

Illustrates how the EVM configuration is retrieved and used when creating a new EVM instance within the ApplyTransaction method.

```go
cfg, err := k.EVMConfig(ctx, sdk.ConsAddress(ctx.BlockHeader().ProposerAddress), k.eip155ChainID)
						
	ev.evm = k.NewEVM(ctx, msg, cfg, tracer, stateDB)
```

--------------------------------

### ZetaChain EVM Testing Commands

Source: https://github.com/zeta-chain/evm/blob/main/README.md

Provides commands for executing various types of tests for the ZetaChain EVM, including unit tests, coverage tests, fuzz tests, Solidity tests, and benchmark tests. These commands are managed via the Makefile.

```bash
make test-unit
make test-unit-cover
make test-fuzz
make test-solidity
make benchmark
```

--------------------------------

### NewEVMInterpreter Logic for EIP Activation

Source: https://github.com/zeta-chain/evm/blob/main/evmd/eips/README.md

Details the logic within NewEVMInterpreter for initializing the JumpTable and enabling extra EIPs, including error handling for activation failures.

```go
func NewEVMInterpreter(evm *EVM, cfg Config) *EVMInterpreter {
	// If jump table was not initialised we set the default one.
	if cfg.JumpTable == nil {
	cfg.JumpTable = DefaultJumpTable(evm.chainRules)
		for i, eip := range cfg.ExtraEips {
			// Deep-copy jumptable to prevent modification of opcodes in other tables
			copy := CopyJumpTable(cfg.JumpTable)
			if err := EnableEIP(eip, copy); err != nil {
				// Disable it, so caller can check if it's activated or not
				cfg.ExtraEips = append(cfg.ExtraEips[:i], cfg.ExtraEips[i+1:]...)
				log.Error("EIP activation failed", "eip", eip, "error", err)
			}
		cfg.JumpTable = copy
		}
	}

	return &EVMInterpreter{
		ev: evm,
		cfg: cfg,
	}
}
```

--------------------------------

### gRPC Client Queries for Precisebank

Source: https://github.com/zeta-chain/evm/blob/main/x/precisebank/README.md

Provides documentation for gRPC endpoints to query the Precisebank module, including TotalFractionalBalances, Remainder, and FractionalBalance.

```APIDOC
Query Service: cosmos.evm.precisebank.v1.Query

Methods:

1. TotalFractionalBalances
   - Description: Queries the aggregate sum of all fractional balances.
   - Endpoint: cosmos.evm.precisebank.v1.Query/TotalFractionalBalances
   - Example Usage:
     ```shell
     grpcurl -plaintext \
       localhost:9090 \
       cosmos.evm.precisebank.v1.Query/TotalFractionalBalances
     ```
   - Example Output:
     ```json
     {
       "total": "2000000000000aatom"
     }
     ```

2. Remainder
   - Description: Queries the current remainder amount.
   - Endpoint: cosmos.evm.precisebank.v1.Query/Remainder
   - Example Usage:
     ```shell
     grpcurl -plaintext \
       localhost:9090 \
       cosmos.evm.precisebank.v1.Query/Remainder
     ```
   - Example Output:
     ```json
     {
       "remainder": "100aatom"
     }
     ```

3. FractionalBalance
   - Description: Queries the fractional balance of a specific account.
   - Endpoint: cosmos.evm.precisebank.v1.Query/FractionalBalance
   - Parameters:
     - address: The account address (string).
   - Example Usage:
     ```shell
     grpcurl -plaintext \
       -d '{"address": "cosmos1..."}' \
       localhost:9090 \
       cosmos.evm.precisebank.v1.Query/FractionalBalance
     ```
   - Example Output:
     ```json
     {
       "fractional_balance": "10000aatom"
     }
     ```
```

--------------------------------

### Mocking IBC App Callbacks in Go

Source: https://github.com/zeta-chain/evm/blob/main/testutil/ibc/README.md

Demonstrates how to use the `MockIBCApp` from the IBC mock module to intercept and control the behavior of base application callbacks during middleware testing. This allows for isolated testing of middleware logic.

```go
mockModule.IBCApp.OnChanOpenTry = func(ctx sdk.Context, portID, channelID, version string) error {
  return fmt.Errorf("mock base app must not be called for OnChanOpenTry")
}
```

```go
suite.chainA.GetSimApp().ICAAuthModule.IBCApp.OnChanOpenInit = func(
ctx sdk.Context, order channeltypes.Order, connectionHops []string,
portID, channelID string, counterparty channeltypes.Counterparty, version string,
) error {
return fmt.Errorf("mock ica auth fails")
}
```

--------------------------------

### Regenerate BankKeeper Mock

Source: https://github.com/zeta-chain/evm/blob/main/x/erc20/types/mocks/README.md

Generates a mock for the BankKeeper interface from a specified Cosmos SDK version. It clones the SDK, navigates to the bank module, generates the mock using mockery, renames the mock to BankKeeper, and places it in the correct directory.

```bash
# update the currently used version
COSMOS_VERSION="v0.50.9-evmos"
CUR_DIR="$(pwd)"
TMP_DIR="/tmp/tmp-sdk-mocks-$(date +%s)"

echo "Cloning Cosmos SDK $COSMOS_VERSION into $TMP_DIR..." &&
git clone --depth 1 --branch "$COSMOS_VERSION" https://github.com/evmos/cosmos-sdk.git "$TMP_DIR" &&
cd "$TMP_DIR" &&

# Go into bank module and generate mock
echo "Generating mocks for bank keeper..." &&
cd x/bank/keeper &&
mockery --name Keeper &&
sed -i '' 's/([^a-zA-Z])Keeper/\1BankKeeper/g' mocks/Keeper.go &&
mv mocks/Keeper.go "$CUR_DIR/x/erc20/types/mocks/BankKeeper.go" && 

# Clean up
echo "Cleaning up $TMP_DIR..." &&
cd "$CUR_DIR" &&
rm -rf "$TMP_DIR"

echo "Done."
```

--------------------------------

### Set DefaultTestingAppInit

Source: https://github.com/zeta-chain/evm/blob/main/testutil/ibc/README.md

Sets the global DefaultTestingAppInit variable to use the custom SetupTestingApp function.

```go
func init() {
  ibctesting.DefaultTestingAppInit = SetupTestingApp
}
```

--------------------------------

### Add New Smart Contract

Source: https://github.com/zeta-chain/evm/blob/main/scripts/compile_smart_contracts/README.md

Adds a new smart contract to the project and generates its corresponding JSON file. Specify the path to the new contract using the CONTRACT variable.

```bash
make contracts-add CONTRACT=path/to/contract.sol
```

--------------------------------

### Cosmos EVM Precisebank Module Overview

Source: https://github.com/zeta-chain/evm/blob/main/x/precisebank/README.md

Explains the relationship between 'uatom' (Cosmos native) and 'aatom' (EVM native) units, detailing the precision extension from 6 to 18 decimal places. It covers the quotient-remainder theorem for managing integer and fractional balances and the role of the reserve account in maintaining supply consistency.

```go
package precisebank

// uatom represents the Cosmos-native atomic unit (10^-6 ATOM).
// aatom represents the EVM-native sub-atomic unit (10^-18 ATOM).
// C is the conversion factor: C = 10^12 (1 uatom = C aatom).

// Account balance representation:
// a(n) = b(n) * C + f(n)
// where a(n) is the aatom balance, b(n) is the uatom balance (integer unit),
// and f(n) is the fractional balance (fractional unit).
// 0 <= f(n) < C

// Total supply relationship:
// T_a = Total aatom supply
// T_b = Total uatom supply
// T_a = T_b * C - r
// where r is the remainder in the reserve account.

```

--------------------------------

### SimApp AppCodec Implementation

Source: https://github.com/zeta-chain/evm/blob/main/testutil/ibc/README.md

Demonstrates the implementation of the AppCodec() method for SimApp, which is required by the TestingApp interface. This method returns the application's codec, crucial for testing purposes.

```go
// AppCodec returns SimApp's app codec.
//
// NOTE: This is solely to be used for testing purposes as it may be desirable
// for modules to register their own custom testing types.
func (app *SimApp) AppCodec() codec.Codec {
  return app.appCodec
}
```

--------------------------------

### JSON-RPC Server Configuration

Source: https://github.com/zeta-chain/evm/blob/main/README.md

Details the configuration options available for the JSON-RPC server within the ZetaChain EVM. This includes controlling exposed namespaces, setting custom timeouts for EVM calls and HTTP requests, defining maximum block gas, and managing the number of open connections.

```APIDOC
JSON-RPC Server Configuration:
  - Control over exposed namespaces.
  - Fine-grained control over HTTP requests.
  - Custom timeouts for EVM calls.
  - Custom timeouts for HTTP requests.
  - Maximum block gas configuration.
  - Maximum number of open connections.
```

--------------------------------

### Cosmos EVM Smart Contract Extensions

Source: https://github.com/zeta-chain/evm/blob/main/README.md

Enables access to chain-native functionality through Solidity smart contracts. This allows developers to leverage Cosmos EVM's extensions within their smart contract logic.

```Solidity
pragma solidity ^0.8.26;

contract MyContract {
    // Access chain-native functionality through Cosmos EVM extensions
    // ... contract logic ...
}
```

--------------------------------

### TestKeeperTestSuite Execution

Source: https://github.com/zeta-chain/evm/blob/main/testutil/ibc/README.md

A function to run all tests within the KeeperTestSuite using testify's Run method.

```go
// TestKeeperTestSuite runs all the tests within this package.
func TestKeeperTestSuite(t *testing.T) {
  testifysuite.Run(t, new(KeeperTestSuite))
}
```

--------------------------------

### KeeperTestSuite Structure

Source: https://github.com/zeta-chain/evm/blob/main/testutil/ibc/README.md

Defines the KeeperTestSuite struct, which embeds testify's suite and holds a coordinator and test chains for testing keeper functions.

```go
// KeeperTestSuite is a testing suite to test keeper functions.
type KeeperTestSuite struct {
  testifysuite.Suite

  coordinator *ibctesting.Coordinator

  // testing chains used for convenience and readability
  chainA *ibctesting.TestChain
  chainB *ibctesting.TestChain
}
```

--------------------------------

### NewTransferPath Helper Function

Source: https://github.com/zeta-chain/evm/blob/main/testutil/ibc/README.md

Creates a new IBC path specifically for the transfer module, setting the PortID for both endpoints.

```go
func NewTransferPath(chainA, chainB *ibctesting.TestChain) *ibctesting.Path {
  path := ibctesting.NewPath(chainA, chainB)
  path.EndpointA.ChannelConfig.PortID = ibctesting.TransferPort
  path.EndpointB.ChannelConfig.PortID = ibctesting.TransferPort

  return path
}
```

--------------------------------

### Precisebank gRPC API

Source: https://github.com/zeta-chain/evm/blob/main/x/precisebank/README.md

Defines the gRPC endpoints for querying balance information within the precisebank module. These include total fractional balances, remainder balances, and individual fractional balances.

```APIDOC
service Query {
  // TotalFractionalBalances returns the total fractional balances across all accounts.
  rpc TotalFractionalBalances(QueryTotalFractionalBalancesRequest) returns (QueryTotalFractionalBalancesResponse);

  // Remainder returns the remainder balance of the reserve account.
  rpc Remainder(QueryRemainderRequest) returns (QueryRemainderResponse);

  // FractionalBalance returns the fractional balance of a specific account.
  rpc FractionalBalance(QueryFractionalBalanceRequest) returns (QueryFractionalBalanceResponse);
}

message QueryTotalFractionalBalancesRequest {}

message QueryTotalFractionalBalancesResponse {
  // Total fractional balance across all accounts.
  string total_fractional_balances = 1;
}

message QueryRemainderRequest {}

message QueryRemainderResponse {
  // Remainder balance of the reserve account.
  string remainder = 1;
}

message QueryFractionalBalanceRequest {
  // Bech32 address of the account.
  string address = 1;
}

message QueryFractionalBalanceResponse {
  // Fractional balance of the specified account.
  string fractional_balance = 1;
}

```

--------------------------------

### Custom Improvement Proposals (Opcodes)

Source: https://github.com/zeta-chain/evm/blob/main/README.md

Details the ability for Cosmos EVM users to customize EVM opcodes and add new ones. Further information can be found in the provided documentation link.

```APIDOC
Custom Improvement Proposals (Opcodes):
  - Customize EVM opcodes.
  - Add new custom opcodes.
  - Refer to documentation for details: https://docs.evmos.org/develop/smart-contracts/custom-improvement-proposals
```

--------------------------------

### EIP-1559 Fee Market Mechanism

Source: https://github.com/zeta-chain/evm/blob/main/README.md

Describes the implementation of the EIP-1559 fee market mechanism, allowing users to control transaction costs by tailoring fee structures. The mechanism can be customized to balance user affordability and network sustainability, or disabled entirely.

```APIDOC
EIP-1559 Fee Market Mechanism:
  - Ready-to-use EIP-1559 solution.
  - Tailor fee structures for network needs.
  - Balance user affordability and network sustainability.
  - Option to disable the mechanism.
```

--------------------------------

### BankWrapper Conversion Logic

Source: https://github.com/zeta-chain/evm/blob/main/x/vm/wrappers/README.md

Illustrates the helper functions used by the BankWrapper to convert coin amounts between the Cosmos SDK's bank module decimal representation and EVM's 18-decimal standard. These functions are crucial for maintaining consistency in coin values within the EVM context.

```go
func mustConvertEvmCoinTo18Decimals(coin sdk.Coin) sdk.Coin {
    // Implementation details for converting coin to 18 decimals
    return convertedCoin
}

func convertCoinsFrom18Decimals(coins sdk.Coins) sdk.Coins {
    // Implementation details for converting coins from 18 decimals
    return convertedCoins
}
```

--------------------------------

### Cosmos EVM JSON-RPC Endpoints

Source: https://github.com/zeta-chain/evm/blob/main/README.md

Cosmos EVM exposes JSON-RPC endpoints for connectivity with standard EVM tooling such as wallets (MetaMask, Rabby) and block explorers (Blockscout).

```APIDOC
JSON-RPC Endpoints:

- eth_blockNumber: Returns the number of the most recent block.
- eth_getBalance: Returns the balance of the specified account.
- eth_sendRawTransaction: Sends a pre-signed transaction.
- eth_call: Executes a message call immediately without creating a transaction.
- txpool_content: Returns the content of the transaction pool.

These endpoints are compatible with standard EVM tooling.
```

--------------------------------

### Regenerate EVMKeeper Mock

Source: https://github.com/zeta-chain/evm/blob/main/x/erc20/types/mocks/README.md

Generates a mock for the EVMKeeper interface, which is a reduced interface defined in the ERC20 types. This command should be run from the x/erc20/types directory.

```bash
cd x/erc20/types
mockery --name EVMKeeper
```

--------------------------------

### TestingApp Interface Definition

Source: https://github.com/zeta-chain/evm/blob/main/testutil/ibc/README.md

Defines the TestingApp interface required for integrating custom testing applications with the IBC testing package. It extends the standard abci.Application interface with methods to access BaseApp, StakingKeeper, IBCKeeper, and TxConfig.

```go
type TestingApp interface {
  abci.Application

  // ibc-go additions
  GetBaseApp() *baseapp.BaseApp
  GetStakingKeeper() ibctestingtypes.StakingKeeper
  GetIBCKeeper() *keeper.Keeper
  GetTxConfig() client.TxConfig

  // Implemented by SimApp
  AppCodec() codec.Codec

  // Implemented by BaseApp
  LastCommitID() sdk.CommitID
  LastBlockHeight() int64
}
```

--------------------------------

### Endpoint Struct Definition

Source: https://github.com/zeta-chain/evm/blob/main/testutil/ibc/README.md

Defines the Endpoint struct, which represents an IBC channel endpoint, including its associated client, connection, and channel configurations.

```go
// Endpoint is a which represents a channel endpoint and its associated
// client and connections. It contains client, connection, and channel
// configuration parameters. Endpoint functions will utilize the parameters
// set in the configuration structs when executing IBC messages.
type Endpoint struct {
  Chain        *TestChain
  Counterparty *Endpoint
  ClientID     string
  ConnectionID string
  ChannelID    string

  ClientConfig     ClientConfig
  ConnectionConfig *ConnectionConfig
  ChannelConfig    *ChannelConfig
}
```

--------------------------------

### BankKeeper Interface Definition

Source: https://github.com/zeta-chain/evm/blob/main/x/precisebank/README.md

Defines the BankKeeper interface for the x/precisebank module, extending the authtypes.BankKeeper with additional methods for managing spendable coins and performing mint/burn operations.

```Go
type BankKeeper interface {
	authtypes.BankKeeper
	SpendableCoin(ctx sdk.Context, addr sdk.AccAddress, denom string) sdk.Coin
	SendCoinsFromModuleToAccount(ctx sdk.Context, senderModule string, recipientAddr sdk.AccAddress, amt sdk.Coins) error
	MintCoins(ctx sdk.Context, moduleName string, amt sdk.Coins) error
	BurnCoins(ctx sdk.Context, moduleName string, amt sdk.Coins) error
}
```

--------------------------------

### EVMConfigurator Type Definition

Source: https://github.com/zeta-chain/evm/blob/main/evmd/eips/README.md

Defines the structure of the EVMConfigurator, which holds configurations for extended EIPs and default extra EIPs.

```go
type EVMConfigurator struct {
	extendedEIPs             map[int]func(*vm.JumpTable)
	extendedDefaultExtraEIPs []int64
	sealed                   bool
}
```

--------------------------------

### EVM Contract Execution Function

Source: https://github.com/zeta-chain/evm/blob/main/x/ibc/callbacks/README.md

The `CallEVMWithData` function is central to executing EVM contract calls within the EVM Callbacks module. It takes context, sender address, contract address, data payload, commit flag, and gas cap as parameters.

```go
func (k Keeper) CallEVMWithData(
	ctx sdk.Context,
	from common.Address,
	contract *common.Address,
	data []byte,
	commit bool,
    gasCap *big.Int,
) (*types.MsgEthereumTxResponse, error)
```

--------------------------------

### Zeta Chain EVM Reserve Update Logic

Source: https://github.com/zeta-chain/evm/blob/main/x/precisebank/README.md

Details the mathematical logic for updating the reserve account based on fractional unit changes in two accounts. It covers different scenarios and their resulting reserve adjustments.

```mathematics
b'(R) - b(R) = 
  case f'(1) > f(1) and f'(2) < f(2):
    0
  case f'(1) <= f(1) and f'(2) < f(2):
    -1
  case f'(1) > f(1) and f'(2) >= f(2):
    1
  case f'(1) <= f(1) and f'(2) >= f(2):
    0

```

--------------------------------

### Cosmos EVM Fee Market Mechanism

Source: https://github.com/zeta-chain/evm/blob/main/README.md

Implements a self-regulating fee market mechanism based on EIP-1559 to handle transaction surges efficiently.

```APIDOC
EIP-1559 Fee Market:

- Base Fee: The minimum fee per gas required for a block.
- Priority Fee: An optional fee per gas to incentivize miners.
- Gas Limit: The maximum amount of gas a transaction can consume.
- Gas Used: The actual amount of gas consumed by a transaction.

This mechanism ensures predictable transaction fees and efficient network usage.
```

--------------------------------

### ICallbacks Interface for IBC Acknowledgements and Timeouts (Solidity)

Source: https://github.com/zeta-chain/evm/blob/main/x/ibc/callbacks/README.md

Defines the Solidity interface for contracts that need to handle IBC packet acknowledgements and timeouts on the source chain. It includes functions for processing packet data and acknowledgements or timeouts.

```solidity
interface ICallbacks {
    /// @dev Callback function to be called on the source chain
    /// after the packet life cycle is completed and acknowledgement is processed
    /// by source chain. The contract address is passed the packet information and acknowledgmeent
    /// to execute the callback logic.
    /// @param channelId the channnel identifier of the packet
    /// @param portId the port identifier of the packet
    /// @param sequence the sequence number of the packet
    /// @param data the data of the packet
    /// @param acknowledgement the acknowledgement of the packet
    function onPacketAcknowledgement(
        string memory channelId,
        string memory portId,
        uint64 sequence,
        bytes memory data,
        bytes memory acknowledgement
    ) external;

    /// @dev Callback function to be called on the source chain
    /// after the packet life cycle is completed and the packet is timed out
    /// by source chain. The contract address is passed the packet information
    /// to execute the callback logic.
    /// @param channelId the channnel identifier of the packet
    /// @param portId the port identifier of the packet
    /// @param sequence the sequence number of the packet
    /// @param data the data of the packet
    function onPacketTimeout(
        string memory channelId,
        string memory portId,
        uint64 sequence,
        bytes memory data
    ) external;
}
```

--------------------------------

### Adding Amount Arithmetic

Source: https://github.com/zeta-chain/evm/blob/main/x/precisebank/README.md

Formulas for updating atom balance (a'(n)) and integer/fractional units (b'(n), f'(n)) when adding an amount 'a'. It details the conditions for incrementing the integer unit based on the fractional part.

```math
a'(n) = a(n) + a

b'(n) * C + f'(n) = b(n) * C + f(n) + a

f'(n) = f(n) + a mod C

b'(n) = 
  b(n) + floor(a/C) if f'(n) >= f(n)
  b(n) + floor(a/C) + 1 if f'(n) < f(n)
```

--------------------------------

### Callback Information in Memo (JSON)

Source: https://github.com/zeta-chain/evm/blob/main/x/ibc/callbacks/README.md

Specifies the JSON structure required within the IBC transfer packet's memo field to configure source callbacks, including the target EVM contract address and gas limit.

```json
{
    "memo": {
        "src_callback": {
            "address": "evm_contract_addr",
            "gas_limit": "1000000"
        }
    }
}
```

--------------------------------

### Cosmos EVM EIP-712 Structured Data Signing

Source: https://github.com/zeta-chain/evm/blob/main/README.md

Utilizes EIP-712 for structured data signing, allowing for arbitrary messages to be signed in a human-readable and secure format.

```APIDOC
EIP-712 Structured Data Signing:

- Domain Separator: Defines the context of the signed data.
- Message Structure: Defines the schema of the data to be signed.
- Signing Process: Generates a signature for the structured message.

This enables secure and user-friendly signing of complex messages.
```

--------------------------------

### Coin Minting Events

Source: https://github.com/zeta-chain/evm/blob/main/x/precisebank/README.md

Defines the JSON structure for 'coinbase' and 'coin_received' events, indicating the minter/receiver and the amount of coins minted or received.

```json
{
  "type": "coinbase",
  "attributes": [
    {
      "key": "minter",
      "value": "{{sdk.AccAddress of the module minting coins}}",
      "index": true
    },
    {
      "key": "amount",
      "value": "{{sdk.Coins being minted}}",
      "index": true
    }
  ]
}
```

```json
{
  "type": "coin_received",
  "attributes": [
    {
      "key": "receiver",
      "value": "{{sdk.AccAddress of the module minting coins}}",
      "index": true
    },
    {
      "key": "amount",
      "value": "{{sdk.Coins being received}}",
      "index": true
    }
  ]
}
```

--------------------------------

### Zeta Chain EVM Burn Mechanics Logic

Source: https://github.com/zeta-chain/evm/blob/main/x/precisebank/README.md

Explains the mathematical logic for updating the reserve account during a burn operation, considering changes in one account's fractional units and the remainder. It outlines the conditions for reserve adjustments.

```mathematics
b'(R) - b(R) = 
  case f'(1) > f(1) and r' < r:
    0
  case f'(1) <= f(1) and r' < r:
    -1
  case f'(1) > f(1) and r' >= r:
    1
  case f'(1) <= f(1) and r' >= r:
    0

```

--------------------------------

### Operation Structure Definition

Source: https://github.com/zeta-chain/evm/blob/main/evmd/eips/README.md

Defines the structure of an EVM operation, including its execution logic, gas costs, and stack requirements. This structure can be modified by custom EIPs.

```go
type operation struct {
	// execute is the operation function
	execute     executionFunc
	constantGas uint64
	dynamicGas  gasFunc
	// minStack tells how many stack items are required
	minStack int
	// maxStack specifies the max length the stack can have for this operation
	// to not overflow the stack.
	maxStack int

	// memorySize returns the memory size required for the operation
	memorySize memorySizeFunc
}
```

--------------------------------

### Specifying Enabled Custom EIPs

Source: https://github.com/zeta-chain/evm/blob/main/evmd/eips/README.md

Defines a slice of custom EIP numbers to be activated in the Cosmos EVM chain. This list is used to configure the DefaultExtraEIPs parameter.

```go
cosmosEVMEnabledEIPs = []int64{
    0o000,
}
```

--------------------------------

### ICS20 Memo Format for EVM Callbacks

Source: https://github.com/zeta-chain/evm/blob/main/x/ibc/callbacks/README.md

This JSON structure defines the `memo` field format for ICS-20 transfer packets intended for EVM callbacks. It includes the destination contract address, gas limit, and packed contract calldata.

```json
{
    //... other ibc fields that we don't care about
    "data":{
    	"denom": "denom on counterparty chain (e.g. uatom)",  // will be transformed to the local denom (ibc/...)
        "amount": "1000",
        "sender": "addr on counterparty chain", // will be transformed
        "receiver": "isolated receiver address for sender",
    	"memo": {
           "dest_callback": {
              "address": "evmContractAddress",
              "gas_limit": "1000000",
              "calldata": "{abipacked_contract_calldata}"
            }
        }
    }
}
```

--------------------------------

### Custom Activators Map Definition

Source: https://github.com/zeta-chain/evm/blob/main/evmd/eips/README.md

Defines a map of custom EIP activators in Cosmos EVM. The keys are EIP numbers (octal representation), and the values are functions that modify the JumpTable.

```go
cosmosEVMActivators = map[int]func(*vm.JumpTable){
	0o000: eips.Enable0000,
	0o001: eips.Enable0001,
	0o002: eips.Enable0002,
}
```

--------------------------------

### Subtracting Amount Arithmetic

Source: https://github.com/zeta-chain/evm/blob/main/x/precisebank/README.md

Formulas for updating atom balance (a'(n)) and integer/fractional units (b'(n), f'(n)) when subtracting an amount 'a'. It explains the conditions for decrementing the integer unit when the fractional part is insufficient.

```math
a'(n) = a(n) - a

b'(n) * C + f'(n) = b(n) * C + f(n) - a

f'(n) = f(n) - a mod C

b'(n) = 
  b(n) - floor(a/C) if f'(n) <= f(n)
  b(n) - floor(a/C) - 1 if f'(n) > f(n)
```

--------------------------------

### Transfer Arithmetic and Remainder Invariance

Source: https://github.com/zeta-chain/evm/blob/main/x/precisebank/README.md

Details the arithmetic for transfers between accounts, including how balances are updated and demonstrating that the remainder (r) remains constant throughout the transfer process. This is derived from the conservation of the total supply.

```math
Account 1: a'(1) = a(1) - a
Account 2: a'(2) = a(2) + a

Reserve update: (b'(R) - b(R)) * C = sum(f'(n)) - sum(f(n)) + r' - r

For a two-account transfer:
(b'(R) - b(R)) * C = (f'(1) - f(1)) + (f'(2) - f(2)) + r' - r

Substituting definitions of f'(n):
0 = r' - r mod C

Given 0 <= r', r < C, this implies r' - r = 0, so r' = r.
```

--------------------------------

### Coin Burning Events

Source: https://github.com/zeta-chain/evm/blob/main/x/precisebank/README.md

Defines the JSON structure for 'burn' and 'coin_spent' events, indicating the burner/spender and the amount of coins burned or spent.

```json
{
  "type": "burn",
  "attributes": [
    {
      "key": "burner",
      "value": "{{sdk.AccAddress of the module burning coins}}",
      "index": true
    },
    {
      "key": "amount",
      "value": "{{sdk.Coins being burned}}",
      "index": true
    }
  ]
}
```

```json
{
  "type": "coin_spent",
  "attributes": [
    {
      "key": "spender",
      "value": "{{sdk.AccAddress of the module burning coins}}",
      "index": true
    },
    {
      "key": "amount",
      "value": "{{sdk.Coins being burned}}",
      "index": true
    }
  ]
}
```

--------------------------------

### Keeper Events: SendCoins Transfer Event

Source: https://github.com/zeta-chain/evm/blob/main/x/precisebank/README.md

Represents the event emitted when coins are transferred via the SendCoins function in the x/precisebank module. It includes details about the sender, recipient, and the amount transferred.

```JSON
{
  "type": "transfer",
  "attributes": [
    {
      "key": "recipient",
      "value": "{{sdk.AccAddress of the recipient}}",
      "index": true
    },
    {
      "key": "sender",
      "value": "{{sdk.AccAddress of the sender}}",
      "index": true
    },
    {
      "key": "amount",
      "value": "{{sdk.Coins being transferred}}",
      "index": true
    }
  ]
}
```

--------------------------------

### Custom EIP Modifier Signature

Source: https://github.com/zeta-chain/evm/blob/main/evmd/eips/README.md

Defines the signature for custom EIP modifiers in Cosmos EVM. This function takes a JumpTable pointer and modifies opcode behavior.

```go
func(jt *vm.JumpTable) {}
```
Tokens:
Raw