precompile

README

Sample Hardhat Project

This project demonstrates a basic Hardhat use case. It comes with a sample contract, a test for that contract, and a Hardhat Ignition module that deploys that contract.

Try running some of the following tasks:

npx hardhat help
npx hardhat test
REPORT_GAS=true npx hardhat test
npx hardhat node
npx hardhat ignition deploy ./ignition/modules/Lock.js

Documentation

Overview

Package precompile implements custom precompiles for the Nibiru EVM.

Precompiles are special, built-in contract interfaces that exist at predefined addresses and run custom logic outside of what is possible in standard Solidity contracts. This package extends the default Ethereum precompiles with Nibiru-specific functionality.

Key components:

• InitPrecompiles: Initializes and returns a map of precompiled contracts.
• PrecompileFunToken: Implements the FunToken precompile for ERC20-to-bank transfers.

The package also provides utility functions for working with precompiles, such as "ABIMethodByID" and "OnRunStart" for common precompile execution setup.

Index

• Constants
• Variables
• func AttrsToJSON(attrs []abci.EventAttribute) []byte
• func EmitEventAbciEvents(ctx sdk.Context, db *statedb.StateDB, abciEvents []sdk.Event, ...)
• func ErrArgTypeValidation(solidityHint string, arg any) error
• func ErrInvalidArgs(err error) error
• func ErrMethodCalled(method *gethabi.Method, wrapped error) error
• func ErrPrecompileRun(err error, p vm.PrecompiledContract) error
• func EventTopicFromBytes(bz []byte) (topic gethcommon.Hash)
• func EventTopicFromString(str string) (topic gethcommon.Hash)
• func HandleOutOfGasPanic(err *error) func()
• func InitPrecompiles(k keepers.PublicKeepers) (precompiles map[gethcommon.Address]vm.PrecompiledContract)
• func PrecompileFunToken(keepers keepers.PublicKeepers) vm.PrecompiledContract
• func PrecompileOracle(keepers keepers.PublicKeepers) vm.PrecompiledContract
• func PrecompileWasm(keepers keepers.PublicKeepers) vm.PrecompiledContract
• type OnRunStartResult
  • func OnRunStart(evm *vm.EVM, contractInput []byte, abi *gethabi.ABI, gasLimit uint64) (res OnRunStartResult, err error)
• type PrecompileMethod
• type Wasm
• type WasmBankCoin

Constants

const EvmEventAbciEvent = "AbciEvent"

EvmEventAbciEvent is the string key used to retrieve the "AbciEvent" Ethereum ABI event for a precompiled contract that implements the "INibiruEvm" interface from "Nibiru/x/evm/embeds/contracts/NibiruEvmUtils.sol".

Variables

var PrecompileAddr_FunToken = gethcommon.HexToAddress("0x0000000000000000000000000000000000000800")

Precompile address for "IFunToken.sol", the contract that enables transfers of ERC20 tokens to "nibi" addresses as bank coins using the ERC20's `FunToken` mapping.

var PrecompileAddr_Oracle = gethcommon.HexToAddress("0x0000000000000000000000000000000000000801")

Precompile address for "Oracle.sol", the contract that enables queries for exchange rates

var PrecompileAddr_Wasm = gethcommon.HexToAddress("0x0000000000000000000000000000000000000802")

Precompile address for "Wasm.sol",

Functions

func AttrsToJSON

func AttrsToJSON(attrs []abci.EventAttribute) []byte

AttrsToJSON creates a deterministic JSON encoding for the key-value tuples.

func EmitEventAbciEvents

func EmitEventAbciEvents(
	ctx sdk.Context,
	db *statedb.StateDB,
	abciEvents []sdk.Event,
	emittingAddr gethcommon.Address,
)

EmitEventAbciEvents adds a sequence of ABCI events to the EVM state DB so that they can be emitted at the end of the "EthereumTx". These events are indexed by their ABCI event type and help communicate non-EVM events in Ethereum-based block explorers and indexers by saving the event attributes in JSON form.

Instead of ABI packing the non-indexed argument, this function encodes the gethcore.Log.Data as a JSON string directly to optimize readbility in explorers without requiring the reader to decode using an ABI.

Simply use ["encoding/hex".DecodeString] with the "0x" prefix removed to read the ABCI event.

func ErrArgTypeValidation

func ErrArgTypeValidation(solidityHint string, arg any) error

Error short-hand for type validation

func ErrInvalidArgs

func ErrInvalidArgs(err error) error

Error when parsing method arguments

func ErrMethodCalled

func ErrMethodCalled(method *gethabi.Method, wrapped error) error

func ErrPrecompileRun

func ErrPrecompileRun(err error, p vm.PrecompiledContract) error

ErrPrecompileRun is error function intended for use in a `defer` pattern, which modifies the input error in the event that its value becomes non-nil. This creates a concise way to prepend extra information to the original error.

func EventTopicFromBytes

func EventTopicFromBytes(bz []byte) (topic gethcommon.Hash)

EventTopicFromBytes creates a "Topic" hash for an EVM event log. An event topic is a 32-byte field used to index specific fields in a smart contract event. Topics make it possible to efficiently filter for and search events in transaction logs.

func EventTopicFromString

func EventTopicFromString(str string) (topic gethcommon.Hash)

EventTopicFromString creates a "Topic" hash for an EVM event log. An event topic is a 32-byte field used to index specific fields in a smart contract event. Topics make it possible to efficiently filter for and search events in transaction logs.

func HandleOutOfGasPanic

func HandleOutOfGasPanic(err *error) func()

func InitPrecompiles

func InitPrecompiles(
	k keepers.PublicKeepers,
) (precompiles map[gethcommon.Address]vm.PrecompiledContract)

InitPrecompiles initializes and returns a map of precompiled contracts for the EVM. It combines default Ethereum precompiles with custom Nibiru precompiles.

Parameters:

• k: A keepers.PublicKeepers instance providing access to various blockchain state.

Returns:

• A map of Ethereum addresses to PrecompiledContract implementations.

func PrecompileFunToken

func PrecompileFunToken(keepers keepers.PublicKeepers) vm.PrecompiledContract

func PrecompileOracle

func PrecompileOracle(keepers keepers.PublicKeepers) vm.PrecompiledContract

func PrecompileWasm

func PrecompileWasm(keepers keepers.PublicKeepers) vm.PrecompiledContract

Types

type OnRunStartResult

type OnRunStartResult struct {
	// Args contains the decoded (ABI unpacked) arguments passed to the contract
	// as input.
	Args []any

	// CacheCtx is a cached SDK context that allows isolated state
	// operations to occur that can be reverted by the EVM's [statedb.StateDB].
	CacheCtx sdk.Context

	// Method is the ABI method for the precompiled contract call.
	Method *gethabi.Method

	StateDB *statedb.StateDB

	PrecompileJournalEntry statedb.PrecompileCalled
}

func OnRunStart

func OnRunStart(
	evm *vm.EVM, contractInput []byte, abi *gethabi.ABI, gasLimit uint64,
) (res OnRunStartResult, err error)

OnRunStart prepares the execution environment for a precompiled contract call. It handles decoding the input data according the to contract ABI, creates an isolated cache context for state changes, and sets up a snapshot for potential EVM "reverts".

Args:

• evm: Instance of the EVM executing the contract
• contract: Precompiled contract being called
• abi: gethabi.ABI defining the contract's invokable methods.

Example Usage:

```go
func (p newPrecompile) Run(
  evm *vm.EVM, contract *vm.Contract, readonly bool
) (bz []byte, err error) {
	res, err := OnRunStart(evm, contract, p.ABI())
	if err != nil {
	    return nil, err
	}
	// ...
	// Use res.Ctx for state changes
	// Use res.StateDB.Commit() before any non-EVM state changes
	// to guarantee the context and [statedb.StateDB] are in sync.
}
```

type PrecompileMethod

type PrecompileMethod string

const (
	FunTokenMethod_sendToBank  PrecompileMethod = "sendToBank"
	FunTokenMethod_balance     PrecompileMethod = "balance"
	FunTokenMethod_bankBalance PrecompileMethod = "bankBalance"
	FunTokenMethod_whoAmI      PrecompileMethod = "whoAmI"
)

const (
	WasmMethod_execute      PrecompileMethod = "execute"
	WasmMethod_query        PrecompileMethod = "query"
	WasmMethod_instantiate  PrecompileMethod = "instantiate"
	WasmMethod_executeMulti PrecompileMethod = "executeMulti"
	WasmMethod_queryRaw     PrecompileMethod = "queryRaw"
)

Contract methods from Wasm.sol

const (
	OracleMethod_queryExchangeRate PrecompileMethod = "queryExchangeRate"
)

type Wasm

type Wasm struct {
	*wasmkeeper.PermissionedKeeper
	wasmkeeper.Keeper
}

Wasm: A struct embedding keepers for read and write operations in Wasm, such as execute, query, and instantiate.

type WasmBankCoin

type WasmBankCoin struct {
	Denom  string   `json:"denom"`
	Amount *big.Int `json:"amount"`
}

WasmBankCoin is a naked struct for the "BankCoin" type from Wasm.sol. The ABI parser requires an unnamed strict, so this type is only used in tests.