node

package
v0.0.0-...-97165cf Latest Latest
Warning

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

 Go to latest Published: Apr 26, 2026 License: MIT Imports: 7 Imported by: 0

Documentation

Overview

Package node provides a JSON-RPC 2.0 client for the Mintlayer node daemon (default mainnet port 3030, testnet port 13030).

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Amount 

type Amount struct {
	Atoms string `json:"atoms"`
}

Amount represents a Mintlayer token/coin amount expressed in atoms. The atoms field is a decimal string to avoid JavaScript integer overflow.

type BannedPeer 

type BannedPeer struct {
	// Address is the banned IP address.
	Address string
	// BanTime is [seconds, nanoseconds] Unix epoch of ban expiry.
	BanTime [2]int64
}

BannedPeer is one entry from ListBanned.

func (*BannedPeer) UnmarshalJSON 

func (b *BannedPeer) UnmarshalJSON(data []byte) error

UnmarshalJSON implements json.Unmarshaler. Wire format: ["address", {"time": [secs, nanos]}].

type BlockSourceContent 

type BlockSourceContent struct {
	BlockID string `json:"block_id"`
}

BlockSourceContent is a helper for constructing BlockReward-type OutpointSourceIDs.

type ChainstateInfo 

type ChainstateInfo struct {
	BestBlockHeight        uint64    `json:"best_block_height"`
	BestBlockID            string    `json:"best_block_id"`
	BestBlockTimestamp     Timestamp `json:"best_block_timestamp"`
	MedianTime             Timestamp `json:"median_time"`
	IsInitialBlockDownload bool      `json:"is_initial_block_download"`
}

ChainstateInfo is returned by ChainstateInfo.

type Client 

type Client struct {
	// contains filtered or unexported fields
}

Client is a JSON-RPC 2.0 client for the Mintlayer node daemon.

func New 

func New(endpoint string, opts ...Option) *Client

New creates a Client targeting endpoint (e.g. "http://127.0.0.1:3030").

func (*Client) AddReservedNode 

func (c *Client) AddReservedNode(ctx context.Context, addr string) error

AddReservedNode adds an address to the reserved-node list. The node maintains a persistent outbound connection to reserved peers.

func (*Client) Ban 

func (c *Client) Ban(ctx context.Context, address string, duration time.Duration) error

Ban bans the peer at address for the given duration. The wire format sends duration as [seconds, nanoseconds].

func (*Client) BestBlockHeight 

func (c *Client) BestBlockHeight(ctx context.Context) (uint64, error)

BestBlockHeight returns the current tip block height.

func (*Client) BestBlockID 

func (c *Client) BestBlockID(ctx context.Context) (string, error)

BestBlockID returns the current tip block ID as a hex string.

func (*Client) BlockHeightInMainChain 

func (c *Client) BlockHeightInMainChain(ctx context.Context, blockID string) (*uint64, error)

BlockHeightInMainChain returns the mainchain height for a block ID. Returns nil if the block is not in the mainchain.

func (*Client) BlockIDAtHeight 

func (c *Client) BlockIDAtHeight(ctx context.Context, height uint64) (*string, error)

BlockIDAtHeight returns the block ID at the given mainchain height. Returns nil if no block exists at that height.

func (*Client) ChainstateInfo 

func (c *Client) ChainstateInfo(ctx context.Context) (*ChainstateInfo, error)

ChainstateInfo returns a summary of chain state: best block, height, timestamp, median time, and IBD flag.

func (*Client) Connect 

func (c *Client) Connect(ctx context.Context, addr string) error

Connect attempts a one-time outbound connection to addr. Unlike AddReservedNode the connection is not persistent.

func (*Client) ContainsOrphanTx 

func (c *Client) ContainsOrphanTx(ctx context.Context, txID string) (bool, error)

ContainsOrphanTx reports whether a transaction is in the orphan pool (its inputs are not yet present in the UTXO set).

func (*Client) ContainsTx 

func (c *Client) ContainsTx(ctx context.Context, txID string) (bool, error)

ContainsTx reports whether a transaction is in the mempool (not the orphan pool).

func (*Client) DelegationShare 

func (c *Client) DelegationShare(ctx context.Context, poolAddress, delegationAddress string) (*Amount, error)

DelegationShare returns the amount owned by a delegation in a pool. Returns nil if not found.

func (*Client) Disconnect 

func (c *Client) Disconnect(ctx context.Context, peerID uint64) error

Disconnect closes the connection to a peer identified by peerID. If it was an outbound connection, the address is removed from the peer database.

func (*Client) GetBindAddresses 

func (c *Client) GetBindAddresses(ctx context.Context) ([]string, error)

GetBindAddresses returns the p2p listen addresses (host:port) of this node.

func (*Client) GetBlock 

func (c *Client) GetBlock(ctx context.Context, id string) (*string, error)

GetBlock returns the hex-encoded serialized bytes of a block. Returns nil if the block is not found. Genesis cannot be retrieved here.

func (*Client) GetBlockJSON 

func (c *Client) GetBlockJSON(ctx context.Context, id string) (json.RawMessage, error)

GetBlockJSON returns the block parsed as a JSON object. Returns nil if the block is not found.

func (*Client) GetConnectedPeers 

func (c *Client) GetConnectedPeers(ctx context.Context) ([]PeerInfo, error)

GetConnectedPeers returns details about all currently connected peers.

func (*Client) GetFeeRate 

func (c *Client) GetFeeRate(ctx context.Context, inTopXMb uint32) (*FeeRate, error)

GetFeeRate returns the fee rate that places a transaction in the top inTopXMb megabytes of the mempool.

func (*Client) GetFeeRatePoints 

func (c *Client) GetFeeRatePoints(ctx context.Context) ([]FeeRatePoint, error)

GetFeeRatePoints returns all data points of the mempool fee-rate curve.

func (*Client) GetMainchainBlocks 

func (c *Client) GetMainchainBlocks(ctx context.Context, from uint64, maxCount uint32) ([]string, error)

GetMainchainBlocks returns up to maxCount consecutive mainchain blocks starting at height from, each as a hex-encoded byte string.

func (*Client) GetPeerCount 

func (c *Client) GetPeerCount(ctx context.Context) (uint64, error)

GetPeerCount returns the number of currently connected peers.

func (*Client) GetTransaction 

func (c *Client) GetTransaction(ctx context.Context, txID string) (*MempoolTx, error)

GetTransaction returns the mempool entry for a transaction. Returns nil if the transaction is not found in the mempool or orphan pool.

func (*Client) GetUTXO 

func (c *Client) GetUTXO(ctx context.Context, outpoint Outpoint) (json.RawMessage, error)

GetUTXO returns the TxOutput at a UTXO outpoint as raw JSON. Returns nil if the outpoint is not found or already spent.

func (*Client) ListBanned 

func (c *Client) ListBanned(ctx context.Context) ([]BannedPeer, error)

ListBanned returns all banned peer addresses together with their ban expiry time.

func (*Client) MemoryUsage 

func (c *Client) MemoryUsage(ctx context.Context) (uint64, error)

MemoryUsage returns the estimated memory used by the mempool in bytes.

func (*Client) MempoolSubmitTransaction 

func (c *Client) MempoolSubmitTransaction(ctx context.Context, txHex string, trustPolicy TrustPolicy) error

MempoolSubmitTransaction submits a signed transaction to the local mempool only. It does NOT broadcast to the P2P network; use P2PSubmitTransaction for that.

func (*Client) NodeShutdown 

func (c *Client) NodeShutdown(ctx context.Context) error

NodeShutdown orders the node daemon to shut down gracefully.

func (*Client) NodeVersion 

func (c *Client) NodeVersion(ctx context.Context) (string, error)

NodeVersion returns the node software version string (e.g. "1.3.0").

func (*Client) OrderInfo 

func (c *Client) OrderInfo(ctx context.Context, orderID string) (*OrderInfo, error)

OrderInfo returns the current state of an on-chain order. Returns nil if the order is not found.

func (*Client) OrdersInfoByCurrencies 

func (c *Client) OrdersInfoByCurrencies(ctx context.Context, ask, give *Currency) (map[string]OrderInfo, error)

OrdersInfoByCurrencies returns all orders matching the given ask/give currencies. Pass nil for either currency to match any. The returned map key is the order id (hex).

func (*Client) P2PSubmitTransaction 

func (c *Client) P2PSubmitTransaction(ctx context.Context, txHex string, trustPolicy TrustPolicy) error

P2PSubmitTransaction submits a signed transaction to the mempool AND broadcasts it to the P2P network. This is the correct call for propagating a transaction to the Mintlayer network.

func (*Client) PoolDecommissionDestination 

func (c *Client) PoolDecommissionDestination(ctx context.Context, poolAddress string) (*string, error)

PoolDecommissionDestination returns the decommission address (bech32) for a pool. Returns nil if the pool is not found.

func (*Client) RemoveReservedNode 

func (c *Client) RemoveReservedNode(ctx context.Context, addr string) error

RemoveReservedNode removes an address from the reserved-node list. The existing connection (if any) is not closed immediately.

func (*Client) StakePoolBalance 

func (c *Client) StakePoolBalance(ctx context.Context, poolAddress string) (*Amount, error)

StakePoolBalance returns the total balance of a pool (staker + all delegations). Returns nil if the pool is not found.

func (*Client) StakerBalance 

func (c *Client) StakerBalance(ctx context.Context, poolAddress string) (*Amount, error)

StakerBalance returns only the staker (pool owner) portion of a pool's balance, excluding delegations. Returns nil if the pool is not found.

func (*Client) SubmitBlock 

func (c *Client) SubmitBlock(ctx context.Context, blockHex string) error

SubmitBlock submits a fully serialized block (hex) to the node. Validation is still enforced; used by stakers after producing a block.

func (*Client) TokenInfo 

func (c *Client) TokenInfo(ctx context.Context, tokenID string) (*TokenInfo, error)

TokenInfo returns token info by token id (bech32). Returns nil if not found.

func (*Client) TokensInfo 

func (c *Client) TokensInfo(ctx context.Context, tokenIDs []string) ([]TokenInfo, error)

TokensInfo is the batch version of TokenInfo. Returns one entry per requested token id in the same order.

func (*Client) Unban 

func (c *Client) Unban(ctx context.Context, address string) error

Unban removes the ban on a previously banned peer address.

type Currency 

type Currency struct {
	Type    string  `json:"type"`
	Content *string `json:"content,omitempty"`
}

Currency is used as a query parameter for OrdersInfoByCurrencies. Set Type to "Coin" (Content omitted) or "Token" (Content = token-id bech32 string).

type FeeRate 

type FeeRate struct {
	AmountPerKB Amount `json:"amount_per_kb"`
}

FeeRate represents a fee rate as atoms per kilobyte.

type FeeRatePoint 

type FeeRatePoint struct {
	Size uint64
	Rate FeeRate
}

FeeRatePoint is one point on the mempool fee-rate curve. Size is the cumulative transaction size in bytes; Rate is the fee rate at that point.

func (*FeeRatePoint) UnmarshalJSON 

func (f *FeeRatePoint) UnmarshalJSON(data []byte) error

UnmarshalJSON implements json.Unmarshaler. The wire format is a 2-element array: [size, {"amount_per_kb": {...}}].

type MempoolTx 

type MempoolTx struct {
	// ID is the transaction id as a hex string.
	ID string `json:"id"`
	// Status is one of: "InMempool", "InMempoolDuplicate", "InOrphanPool", "InOrphanPoolDuplicate".
	Status      string `json:"status"`
	Transaction string `json:"transaction"` // hex-encoded raw bytes
}

MempoolTx is returned by GetTransaction (mempool).

type Option 

type Option func(*Client)

Option configures a Client.

func WithBasicAuth 

func WithBasicAuth(user, pass string) Option

WithBasicAuth configures HTTP Basic Authentication credentials.

func WithHTTPClient 

func WithHTTPClient(hc *http.Client) Option

WithHTTPClient replaces the default HTTP client.

func WithTimeout 

func WithTimeout(d time.Duration) Option

WithTimeout sets a per-request timeout on the default HTTP client. Cannot be combined with WithHTTPClient — the last option applied wins.

type OrderInfo 

type OrderInfo struct {
	ConcludeKey    string          `json:"conclude_key"`
	InitiallyAsked json.RawMessage `json:"initially_asked"`
	InitiallyGiven json.RawMessage `json:"initially_given"`
	AskBalance     Amount          `json:"ask_balance"`
	GiveBalance    Amount          `json:"give_balance"`
	Nonce          uint64          `json:"nonce"`
	IsFrozen       bool            `json:"is_frozen"`
}

OrderInfo is returned by OrderInfo and OrdersInfoByCurrencies.

type Outpoint 

type Outpoint struct {
	SourceID OutpointSourceID `json:"source_id"`
	Index    uint32           `json:"index"`
}

Outpoint identifies a specific output within a transaction or block reward.

type OutpointSourceID 

type OutpointSourceID struct {
	Type    string          `json:"type"`
	Content json.RawMessage `json:"content"`
}

OutpointSourceID identifies the transaction or block reward that produced a UTXO. Set Type to "Transaction" and Content to a JSON object {"tx_id": "hex…"}, or Type to "BlockReward" and Content to {"block_id": "hex…"}.

type PeerInfo 

type PeerInfo struct {
	PeerID uint64 `json:"peer_id"`
	// Address is the remote address in "host:port" form.
	Address string `json:"address"`
	// PeerRole is one of: "Inbound", "OutboundFullRelay", "OutboundBlockRelay",
	// "OutboundReserved", "OutboundManual", "Feeler".
	PeerRole        string `json:"peer_role"`
	BanScore        uint32 `json:"ban_score"`
	UserAgent       string `json:"user_agent"`
	SoftwareVersion string `json:"software_version"`
	// PingWait, PingLast, PingMin are milliseconds; nil when not yet measured.
	PingWait         *int64 `json:"ping_wait"`
	PingLast         *int64 `json:"ping_last"`
	PingMin          *int64 `json:"ping_min"`
	LastTipBlockTime *int64 `json:"last_tip_block_time"`
}

PeerInfo describes a connected peer.

type RPCError 

type RPCError struct {
	Code    int    `json:"code"`
	Message string `json:"message"`
}

RPCError is returned when the node daemon replies with a JSON-RPC error object.

func (*RPCError) Error 

func (e *RPCError) Error() string

type Timestamp 

type Timestamp struct {
	Timestamp int64 `json:"timestamp"`
}

Timestamp wraps a Unix seconds timestamp returned by the node.

type TokenInfo 

type TokenInfo struct {
	Type    string          `json:"type"`
	Content json.RawMessage `json:"content"`
}

TokenInfo is returned by TokenInfo and TokensInfo. The Type field is "FungibleToken" or "NonFungibleToken". Content holds the raw JSON payload specific to each token type.

type TrustPolicy 

type TrustPolicy string

TrustPolicy controls fee-check strictness when submitting transactions. 

const (
	// TrustPolicyTrusted skips some fee checks. Use only when you control the transaction.
	TrustPolicyTrusted TrustPolicy = "Trusted"
	// TrustPolicyUntrusted applies full validation. Recommended for all external transactions.
	TrustPolicyUntrusted TrustPolicy = "Untrusted"
)

type TxSourceContent 

type TxSourceContent struct {
	TxID string `json:"tx_id"`
}

TxSourceContent is a helper for constructing Transaction-type OutpointSourceIDs.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.