types

Documentation

Index

• type GenerateNextSequenceFunc
• type Hashable
• type Head
• type HeadBroadcaster
• type HeadBroadcasterRegistry
• type HeadListener
• type HeadSaver
• type HeadTrackable
• type HeadTracker
• type ID
  • func NewIDFromInt(id int64) ID
  • func RandomID() ID
• type NewHeadHandler
• type Receipt
• type Sequence
• type Subscription

Types

type GenerateNextSequenceFunc

type GenerateNextSequenceFunc[SEQ Sequence] func(prev SEQ) SEQ

Generate the next usable sequence for a transaction

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

	// Timestamp the time of mining of the block
	GetTimestamp() time.Time

	// 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

	// Returns the total difficulty of the block. For chains who do not have a concept of block
	// difficulty, return 0.
	BlockDifficulty() *big.Int
	// IsValid returns true if the head is valid.
	IsValid() bool
}

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.Service
	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 heads up to latestFinalized - historyDepth, returns the latest chain.
	Load(ctx context.Context, latestFinalized int64) (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
	// MarkFinalized - marks matching block and all it's direct ancestors as finalized
	MarkFinalized(ctx context.Context, latestFinalized H) error
}

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.Service
	// Backfill given a head will fill in any missing heads up to latestFinalized
	Backfill(ctx context.Context, headWithChain, latestFinalized H) (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

func NewIDFromInt

func NewIDFromInt(id int64) ID

func RandomID

func RandomID() ID

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 Receipt

type Receipt[TX_HASH Hashable, BLOCK_HASH Hashable] interface {
	GetStatus() uint64
	GetTxHash() TX_HASH
	GetBlockNumber() *big.Int
	IsZero() bool
	IsUnmined() bool
	GetFeeUsed() uint64
	GetTransactionIndex() uint
	GetBlockHash() BLOCK_HASH
}

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
}