types

Documentation

Index

• type Accounts
• type Blocks
• type Client
• type Events
• type Hashable
• type Head
• type HeadBroadcaster
• type HeadBroadcasterRegistry
• type HeadListener
• type HeadSaver
• type HeadTrackable
• type HeadTracker
• type ID
• type NewHeadHandler
• type Sequence
• type Subscription
• type Transactions

Types

type Accounts

type Accounts[ADDR Hashable, SEQ Sequence] interface {
	BalanceAt(ctx context.Context, accountAddress ADDR, blockNumber *big.Int) (*big.Int, error)
	TokenBalance(ctx context.Context, accountAddress ADDR, tokenAddress ADDR) (*big.Int, error)
	SequenceAt(ctx context.Context, accountAddress ADDR, blockNumber *big.Int) (SEQ, error)
}

type Blocks

type Blocks[BLOCK any, BLOCKHASH Hashable] interface {
	BlockByNumber(ctx context.Context, number *big.Int) (*BLOCK, error)
	BlockByHash(ctx context.Context, hash BLOCKHASH) (*BLOCK, error)
	LatestBlockHeight(context.Context) (*big.Int, error)
}

type Client

type Client[
	CHAINID ID,
	SEQ Sequence,
	ADDR Hashable,
	BLOCK any,
	BLOCKHASH Hashable,
	TX any,
	TXHASH Hashable,
	TXRECEIPT any,
	EVENT any,
	EVENTOPS any,
] interface {
	// ChainID stored for quick access
	ConfiguredChainID() CHAINID
	// ChainID RPC call
	ChainID() (CHAINID, error)

	Accounts[ADDR, SEQ]
	Transactions[TX, TXHASH, TXRECEIPT]
	Events[EVENT, EVENTOPS]
	Blocks[BLOCK, BLOCKHASH]

	CallContext(ctx context.Context, result interface{}, method string, args ...interface{}) error
}

A generic client interface for communication with the RPC node Every native chain must implement independently

type Events

type Events[EVENT any, EVENTOPS any] interface {
	FilterEvents(ctx context.Context, query EVENTOPS) ([]EVENT, error)
}

type Hashable

type Hashable interface {
	fmt.Stringer
	comparable

	Bytes() []byte
}

A chain-agnostic generic interface to represent the following native types on various chains: PublicKey, Address, Account, BlockHash, TxHash

type Head

type Head[BLOCK_HASH Hashable] interface {
	// BlockNumber is the head's block number
	BlockNumber() int64

	// ChainLength returns the length of the chain followed by recursively looking up parents
	ChainLength() uint32

	// EarliestHeadInChain traverses through parents until it finds the earliest one
	EarliestHeadInChain() Head[BLOCK_HASH]

	// Parent is the head's parent block
	GetParent() Head[BLOCK_HASH]

	// Hash is the head's block hash
	BlockHash() BLOCK_HASH
	GetParentHash() BLOCK_HASH

	// HashAtHeight returns the hash of the block at the given height, if it is in the chain.
	// If not in chain, returns the zero hash
	HashAtHeight(blockNum int64) BLOCK_HASH
}

Head provides access to a chain's head, as needed by the TxManager. This is a generic interface which ALL chains will implement.

type HeadBroadcaster

type HeadBroadcaster[H Head[BLOCK_HASH], BLOCK_HASH Hashable] interface {
	services.ServiceCtx
	BroadcastNewLongestChain(H)
	HeadBroadcasterRegistry[H, BLOCK_HASH]
}

HeadBroadcaster relays new Heads to all subscribers.

type HeadBroadcasterRegistry

type HeadBroadcasterRegistry[H Head[BLOCK_HASH], BLOCK_HASH Hashable] interface {
	Subscribe(callback HeadTrackable[H, BLOCK_HASH]) (currentLongestChain H, unsubscribe func())
}

type HeadListener

type HeadListener[H Head[BLOCK_HASH], BLOCK_HASH Hashable] interface {
	// ListenForNewHeads kicks off the listen loop (not thread safe)
	// done() must be executed upon leaving ListenForNewHeads()
	ListenForNewHeads(handleNewHead NewHeadHandler[H, BLOCK_HASH], done func())

	// ReceivingHeads returns true if the listener is receiving heads (thread safe)
	ReceivingHeads() bool

	// Connected returns true if the listener is connected (thread safe)
	Connected() bool

	// HealthReport returns report of errors within HeadListener
	HealthReport() map[string]error
}

HeadListener is a chain agnostic interface that manages connection of Client that receives heads from the blockchain node

type HeadSaver

type HeadSaver[H Head[BLOCK_HASH], BLOCK_HASH Hashable] interface {
	// Save updates the latest block number, if indeed the latest, and persists
	// this number in case of reboot.
	Save(ctx context.Context, head H) error
	// Load loads latest EvmHeadTrackerHistoryDepth heads, returns the latest chain.
	Load(ctx context.Context) (H, error)
	// LatestChain returns the block header with the highest number that has been seen, or nil.
	LatestChain() H
	// Chain returns a head for the specified hash, or nil.
	Chain(hash BLOCK_HASH) H
}

HeadSaver is an chain agnostic interface for saving and loading heads Different chains will instantiate generic HeadSaver type with their native Head and BlockHash types.

type HeadTrackable

type HeadTrackable[H Head[BLOCK_HASH], BLOCK_HASH Hashable] interface {
	// OnNewLongestChain sends a new head when it becomes available. Subscribers can recursively trace the parent
	// of the head to the finality depth back. If this is not possible (e.g. due to recent boot, backfill not complete
	// etc), users may get a shorter linked list. If there is a re-org, older blocks won't be sent to this function again.
	// But the new blocks from the re-org will be available in later blocks' parent linked list.
	OnNewLongestChain(ctx context.Context, head H)
}

HeadTrackable is implemented by the core txm, to be able to receive head events from any chain. Chain implementations should notify head events to the core txm via this interface.

type HeadTracker

type HeadTracker[H Head[BLOCK_HASH], BLOCK_HASH Hashable] interface {
	services.ServiceCtx
	// Backfill given a head will fill in any missing heads up to the given depth
	// (used for testing)
	Backfill(ctx context.Context, headWithChain H, depth uint) (err error)
	LatestChain() H
}

HeadTracker holds and stores the block experienced by a particular node in a thread safe manner. Reconstitutes the last block number on reboot.

type ID

type ID fmt.Stringer

ID represents the base type, for any chain's ID. It should be convertible to a string, that can uniquely identify this chain

type NewHeadHandler

type NewHeadHandler[H Head[BLOCK_HASH], BLOCK_HASH Hashable] func(ctx context.Context, header H) error

NewHeadHandler is a callback that handles incoming heads

type Sequence

type Sequence interface {
	fmt.Stringer
	Int64() int64 // needed for numeric sequence confirmation - to be removed with confirmation logic generalization: https://smartcontract-it.atlassian.net/browse/BCI-860
}

Sequence represents the base type, for any chain's sequence object. It should be convertible to a string

type Subscription

type Subscription interface {
	// Unsubscribe cancels the sending of events to the data channel
	// and closes the error channel.
	Unsubscribe()
	// Err returns the subscription error channel. The error channel receives
	// a value if there is an issue with the subscription (e.g. the network connection
	// delivering the events has been closed). Only one value will ever be sent.
	// The error channel is closed by Unsubscribe.
	Err() <-chan error
}

type Transactions

type Transactions[TX any, TXHASH Hashable, TXRECEIPT any] interface {
	SendTransaction(ctx context.Context, tx *TX) error
	SimulateTransaction(ctx context.Context, tx *TX) error
	TransactionByHash(ctx context.Context, txHash TXHASH) (*TX, error)
	TransactionReceipt(ctx context.Context, txHash TXHASH) (*TXRECEIPT, error)
}