core

package
v0.0.0 Latest Latest
Warning

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

 Go to latest Published: Sep 23, 2026 License: Apache-2.0, UNKNOWN not legal advice Imports: 0 Imported by: 0

Documentation

Overview

Package core implements the JSON-RPC methods a Tendermint2 node exposes.

The route map in Environment.Routes is the authoritative list of methods and their parameters. For the user-facing reference — encoding rules and limits — see docs/resources/rpc-endpoints.md.

Transports

The same methods are served three ways, all mounted by rpc.RegisterRPCFuncs and github.com/gnolang/gno/tm2/pkg/bft/node:

  • URI over HTTP, as GET /<method>?<arg>=<value>
  • JSON-RPC over HTTP, as POST / with a request object
  • WebSocket, at /websocket, serving the same methods

Both JSON-RPC transports also accept an array of request objects as a batch.

A request to / with an empty body returns an HTML index of the methods available on that node.

Configuration

Parameters live under the rpc table of the node's config.toml, inside the data directory given by gnoland's --data-dir, and are edited there or with "gnoland config set rpc.<key> <value>". That command takes --config-path, not --data-dir, so a node on a custom data directory needs the path spelled out. The default listen address is tcp://127.0.0.1:26657.

The unsafe_* methods are registered only when rpc.unsafe is true. Two of them pass a caller-supplied filename straight to os.Create, so a node running with rpc.unsafe on a reachable address lets any caller overwrite files as the node user.

Arguments

Byte-array arguments may be passed as base64, or — on the URI transport only — as a 0x-prefixed hex string such as 0x616263. The 0x form is decoded in httpParamsToArgs; the JSON-RPC transport accepts base64 exclusively.

String arguments are safest quoted, as path="auth/accounts/g1...". An unquoted value is wrapped for the caller when strconv.Atoi accepts it, so a bare 123 reaches a string parameter intact, or when it is not valid JSON at all. A bare true, or a number too large for Go's int, then reaches amino as raw JSON and fails to unmarshal into a string; a bare null is worse, since it unmarshals silently to "". Two edges follow from the order of those tests: surrounding whitespace defeats Atoi but not json.Valid, so " 123" fails where 123 works, and the 0x branch runs before both and ignores the parameter's declared type, so path=0x616263 arrives as "YWJj".

The JSON-RPC envelope is ordinary JSON, but the result is marshalled with Amino JSON, which encodes byte arrays as base64 and 64-bit integers as quoted strings. Types with their own MarshalAmino, addresses among them, override that.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Consensus 

type Consensus interface {
	GetConfigDeepCopy() *cnscfg.ConsensusConfig
	GetState() sm.State
	GetValidators() (int64, []*types.Validator)
	GetLastHeight() int64
	GetRoundStateDeepCopy() *cstypes.RoundState
	GetRoundStateSimple() cstypes.RoundStateSimple
}

type Environment 

type Environment struct {
	// external, thread-safe interfaces
	ProxyAppQuery appconn.Query

	// interfaces defined in types and above
	StateDB      dbm.DB
	BlockStore   sm.BlockStore
	Consensus    Consensus
	P2PPeers     peers
	P2PTransport transport

	// objects
	PubKey      crypto.PubKey
	GenDoc      *types.GenesisDoc // cache the genesis structure
	EventSwitch events.EventSwitch
	Mempool     mempl.Mempool
	GetFastSync func() bool // avoids dependency on consensus pkg

	Logger *slog.Logger
	Config cfg.RPCConfig // value, not pointer — TimeoutBroadcastTxCommit must be stable
	// contains filtered or unexported fields
}

---------------------------------------------- Environment holds all per-node state that RPC handlers operate on. One Environment is created per Node instance, replacing the package-level globals this package used previously. All fields are expected to be populated before Start is called; individual handlers may only need a subset (tests construct partial Environments).

func (*Environment) ABCIInfo 

func (env *Environment) ABCIInfo(ctx *rpctypes.Context) (*ctypes.ResultABCIInfo, error)

ABCIInfo gets some info about the application.

func (*Environment) ABCIQuery 

func (env *Environment) ABCIQuery(ctx *rpctypes.Context, path string, data []byte, height int64, prove bool) (*ctypes.ResultABCIQuery, error)

ABCIQuery queries the application for some information.

func (*Environment) Block 

func (env *Environment) Block(ctx *rpctypes.Context, heightPtr *int64) (*ctypes.ResultBlock, error)

Block returns the block at the given height. If no height is provided, it fetches the latest block.

func (*Environment) BlockResults 

func (env *Environment) BlockResults(ctx *rpctypes.Context, heightPtr *int64) (*ctypes.ResultBlockResults, error)

BlockResults gets ABCIResults at a given height. If no height is provided, it fetches results for the latest block. Results are for the height of the block containing the txs.

func (*Environment) BlockchainInfo 

func (env *Environment) BlockchainInfo(ctx *rpctypes.Context, minHeight, maxHeight int64) (*ctypes.ResultBlockchainInfo, error)

BlockchainInfo gets block headers for minHeight <= height <= maxHeight. Block headers are returned in descending order (highest first).

Returns at most 20 items.

func (*Environment) BroadcastTxAsync 

func (env *Environment) BroadcastTxAsync(ctx *rpctypes.Context, tx types.Tx) (*ctypes.ResultBroadcastTx, error)

BroadcastTxAsync returns right away, with no response. Does not wait for CheckTx nor DeliverTx results.

The returned error covers what the mempool itself can decide: capacity and size limits, a duplicate already in the cache, and a proxy connection failure. The application's CheckTx does run — gno.land hosts the application in-process, so the local client executes it before this method returns, and the mempool acts on the outcome by admitting or dropping the transaction. The caller is the one left out: the callback passed here is nil, so the result never reaches it, and a transaction the application rejects — an undecodable one, for instance — is reported as a success.

Callers that need to know whether a transaction was accepted into the mempool use BroadcastTxSync. Acceptance is not execution: CheckTx does not run the messages, so the outcome of a transaction is only available from Tx once it has been included in a block.

func (*Environment) BroadcastTxCommit 

func (env *Environment) BroadcastTxCommit(ctx *rpctypes.Context, tx types.Tx) (*ctypes.ResultBroadcastTxCommit, error)

BroadcastTxCommit returns with the responses from CheckTx and DeliverTx.

IMPORTANT: use only for testing and development. In production, use BroadcastTxSync or BroadcastTxAsync.

CONTRACT: only returns error if mempool.CheckTx() errs, we timeout waiting for tx to commit, or the Environment was not started.

func (*Environment) BroadcastTxSync 

func (env *Environment) BroadcastTxSync(ctx *rpctypes.Context, tx types.Tx) (*ctypes.ResultBroadcastTx, error)

BroadcastTxSync returns with the response from CheckTx. Does not wait for DeliverTx result.

func (*Environment) Commit 

func (env *Environment) Commit(ctx *rpctypes.Context, heightPtr *int64) (*ctypes.ResultCommit, error)

Commit returns the block commit at the given height. If no height is provided, it fetches the commit for the latest block.

func (*Environment) ConsensusParams 

func (env *Environment) ConsensusParams(ctx *rpctypes.Context, heightPtr *int64) (*ctypes.ResultConsensusParams, error)

ConsensusParams returns the consensus parameters at the given block height. If no height is provided, it fetches the current consensus params.

func (*Environment) ConsensusState 

func (env *Environment) ConsensusState(ctx *rpctypes.Context) (*ctypes.ResultConsensusState, error)

ConsensusState returns a concise summary of the consensus state. UNSTABLE.

func (*Environment) DumpConsensusState 

func (env *Environment) DumpConsensusState(ctx *rpctypes.Context) (*ctypes.ResultDumpConsensusState, error)

DumpConsensusState dumps consensus state. UNSTABLE.

func (*Environment) Genesis 

func (env *Environment) Genesis(ctx *rpctypes.Context) (*ctypes.ResultGenesis, error)

Genesis returns the genesis file.

func (*Environment) Health 

func (env *Environment) Health(ctx *rpctypes.Context) (*ctypes.ResultHealth, error)

Health returns node health. Returns empty result (200 OK) on success, no response in case of an error.

func (*Environment) NetInfo 

func (env *Environment) NetInfo(ctx *rpctypes.Context) (*ctypes.ResultNetInfo, error)

NetInfo returns network info.

func (*Environment) NumUnconfirmedTxs 

func (env *Environment) NumUnconfirmedTxs(ctx *rpctypes.Context) (*ctypes.ResultUnconfirmedTxs, error)

NumUnconfirmedTxs returns the number of unconfirmed transactions.

func (*Environment) Routes 

func (env *Environment) Routes(unsafe bool) map[string]*rpc.RPCFunc

Routes builds the RPC route map for this Environment. Each route binds a method value on env, so requests dispatch to this specific Environment's state without going through package globals.

If unsafe is true, the "unsafe_*" routes (mempool flush, CPU/heap profiler) are included.

func (*Environment) Start 

func (env *Environment) Start() error

Start initializes any per-Environment background services. Currently this only creates and starts the txDispatcher if EventSwitch is non-nil. Start is idempotent but panics if called after Stop.

func (*Environment) Status 

func (env *Environment) Status(ctx *rpctypes.Context, heightGtePtr *int64) (*ctypes.ResultStatus, error)

Status returns Tendermint status including node info, pubkey, latest block hash, app hash, block height and time.

`heightGte` optionally returns 409 if the latest chain height is less than it, which is useful for readyness probes.

func (*Environment) Stop 

func (env *Environment) Stop() error

Stop tears down the services started by Start. It should be called before the associated EventSwitch is stopped so the txDispatcher goroutine exits via its own Quit channel rather than racing evsw.Quit(). Stop is idempotent.

func (*Environment) Tx 

func (env *Environment) Tx(ctx *rpctypes.Context, hash []byte) (*ctypes.ResultTx, error)

Tx allows you to query the transaction results. `nil` could mean the transaction is in the mempool, invalidated, or was not sent in the first place.

func (*Environment) UnconfirmedTxs 

func (env *Environment) UnconfirmedTxs(ctx *rpctypes.Context, limit int) (*ctypes.ResultUnconfirmedTxs, error)

UnconfirmedTxs gets unconfirmed transactions (maximum ?limit entries) including their number.

func (*Environment) UnsafeFlushMempool 

func (env *Environment) UnsafeFlushMempool(ctx *rpctypes.Context) (*ctypes.ResultUnsafeFlushMempool, error)

UnsafeFlushMempool removes all transactions from the mempool.

func (*Environment) UnsafeStartCPUProfiler 

func (env *Environment) UnsafeStartCPUProfiler(ctx *rpctypes.Context, filename string) (*ctypes.ResultUnsafeProfile, error)

UnsafeStartCPUProfiler starts a pprof profiler using the given filename.

func (*Environment) UnsafeStopCPUProfiler 

func (env *Environment) UnsafeStopCPUProfiler(ctx *rpctypes.Context) (*ctypes.ResultUnsafeProfile, error)

UnsafeStopCPUProfiler stops the running pprof profiler.

func (*Environment) UnsafeWriteHeapProfile 

func (env *Environment) UnsafeWriteHeapProfile(ctx *rpctypes.Context, filename string) (*ctypes.ResultUnsafeProfile, error)

UnsafeWriteHeapProfile dumps a heap profile to the given filename.

func (*Environment) Validators 

func (env *Environment) Validators(ctx *rpctypes.Context, heightPtr *int64) (*ctypes.ResultValidators, error)

Validators returns the validator set at the given block height. If no height is provided, it fetches the current validator set. Note the validators are sorted by their address — this is the canonical order for the validators in the set as used in computing their Merkle root.

Source Files

View all Source files

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL