db

Documentation

Overview

Package db provides a database interface for the executor.

Index

• type DBAttestation
• type DBMessage
• type DBState
• type ExecutorDB
• type ExecutorDBReader
• type ExecutorDBWriter

Types

type DBAttestation

type DBAttestation struct {
	// Destination is the destination of the attestation.
	Destination *uint32
	// SnapshotRoot is the snapshot root.
	SnapshotRoot *string
	// DataHash is the agent root and SnapGasHash combined into a single hash.
	DataHash *string
	// AttestationNonce is the nonce of the attestation.
	AttestationNonce *uint32
	// SummitBlockNumber is the block number when the attestation was created in Summit.
	SummitBlockNumber *uint64
	// SummitTimestamp is the timestamp of the block when the attestation was created in Summit.
	SummitTimestamp *uint64
	// DestinationBlockNumber is the block number that the attestation was submitted on the destination.
	DestinationBlockNumber *uint64
	// DestinationTimestamp is the timestamp of the block that the attestation was submitted on the destination.
	DestinationTimestamp *uint64
}

DBAttestation is the executor type for interacting with the database representation of an attestation.

type DBMessage

type DBMessage struct {
	// ChainID is the chain ID of the chain that the message is for.
	ChainID *uint32
	// Destination is the destination chain id of the message.
	Destination *uint32
	// Nonce is the nonce of the message.
	Nonce *uint32
	// Message is the message.
	Message *[]byte
	// BlockNumber is the block number of the message.
	BlockNumber *uint64
	// Executed is if the message has been executed.
	Executed *bool
	// MinimumTimeSet is if the MinimumTime field has been set from an Attestation.
	MinimumTimeSet *bool
	// MinimumTime is the minimum time that the message can be executed.
	MinimumTime *uint64
}

DBMessage is the executor type for interacting with the database representation of a message.

type DBState

type DBState struct {
	// SnapshotRoot is the snapshot root.
	SnapshotRoot *string
	// Root is the origin Merkle tree's root.
	Root *string
	// ChainID is the origin chain id.
	ChainID *uint32
	// Nonce is the origin Merkle tree's nonce.
	Nonce *uint32
	// OriginBlockNumber is the block number that the state was taken from on the origin.
	OriginBlockNumber *uint64
	// OriginTimestamp is the timestamp of the block that the state was taken from on the origin.
	OriginTimestamp *uint64
	// Proof is the Snapshot Merkle Tree proof for the state.
	Proof *json.RawMessage
	// StateIndex is the index of the state in the Snapshot.
	StateIndex *uint32
	// BlockNumber is the block number the state was received at on Summit.
	BlockNumber *uint64
	// GDGasPrice is the gas price from the gas data.
	GDGasPrice *uint16
	// GDDataPrice is the data price from the gas data.
	GDDataPrice *uint16
	// GDExecBuffer is the exec buffer from the gas data.
	GDExecBuffer *uint16
	// GDAmortAttCost is the amortAttCost from the gas data.
	GDAmortAttCost *uint16
	// GDEtherPrice is the etherPrice from the gas data.
	GDEtherPrice *uint16
	// GDMarkup is the markup from the gas data.
	GDMarkup *uint16
}

DBState is the executor type for interacting with the database representation of a state.

type ExecutorDB

type ExecutorDB interface {
	ExecutorDBWriter
	ExecutorDBReader
}

ExecutorDB is the interface for the executor database.

type ExecutorDBReader

type ExecutorDBReader interface {
	// GetMessage gets a message from the database.
	GetMessage(ctx context.Context, messageMask DBMessage) (*agentsTypes.Message, error)
	// GetMessages gets messages from the database, paginated and ordered in ascending order by nonce.
	GetMessages(ctx context.Context, messageMask DBMessage, page int) ([]agentsTypes.Message, error)
	// GetBlockNumber gets the block number of a message from the database.
	GetBlockNumber(ctx context.Context, messageMask DBMessage) (uint64, error)
	// GetLastBlockNumber gets the last block number that had a message in the database.
	GetLastBlockNumber(ctx context.Context, chainID uint32, contractType types.ContractType) (uint64, error)
	// GetExecutableMessages gets executable messages from the database.
	GetExecutableMessages(ctx context.Context, messageMask DBMessage, currentTime uint64, page int) ([]agentsTypes.Message, error)
	// GetUnsetMinimumTimeMessages gets messages from the database that have not had their minimum time set.
	GetUnsetMinimumTimeMessages(ctx context.Context, messageMask DBMessage, page int) ([]agentsTypes.Message, error)
	// GetMessageMinimumTime gets the minimum time for a message to be executed.
	GetMessageMinimumTime(ctx context.Context, messageMask DBMessage) (*uint64, error)

	// GetAttestation gets an attestation that has fields matching the attestation mask.
	GetAttestation(ctx context.Context, attestationMask DBAttestation) (*agentsTypes.Attestation, error)
	// GetAttestationBlockNumber gets the block number of an attestation.
	GetAttestationBlockNumber(ctx context.Context, attestationMask DBAttestation) (*uint64, error)
	// GetAttestationTimestamp gets the timestamp of an attestation.
	GetAttestationTimestamp(ctx context.Context, attestationMask DBAttestation) (*uint64, error)
	// GetEarliestSnapshotFromAttestation takes a list of snapshot roots, checks which one has the lowest block number, and returns that snapshot root back.
	GetEarliestSnapshotFromAttestation(ctx context.Context, attestationMask DBAttestation, snapshotRoots []string) (*[32]byte, error)

	// GetState gets a state from the database.
	GetState(ctx context.Context, stateMask DBState) (*agentsTypes.State, error)
	// GetStateMetadata gets the snapshot root, proof, and tree height of a state from the database.
	GetStateMetadata(ctx context.Context, stateMask DBState) (snapshotRoot *[32]byte, proof *json.RawMessage, stateIndex *uint32, err error)
	// GetPotentialSnapshotRoots gets all snapshot roots that are greater than or equal to a specified nonce and matches
	// a specified chain ID.
	GetPotentialSnapshotRoots(ctx context.Context, chainID uint32, nonce uint32) ([]string, error)
	// GetSnapshotRootsInNonceRange gets all snapshot roots for all states in a specified nonce range.
	GetSnapshotRootsInNonceRange(ctx context.Context, chainID uint32, startNonce uint32, endNonce uint32) ([]string, error)

	// GetTimestampForMessage gets the timestamp for a message. This is done in multiple logical steps:
	// 1. Get all potential snapshot roots for the message (all snapshot roots that are associated to states with
	// the same chain ID and a nonce greater than or equal to the message nonce).
	// 2. Get the minimum destination block number for all attestations that are associated to the potential snapshot roots.
	// 3. Return the timestamp of the attestation with the minimum destination block number.
	GetTimestampForMessage(ctx context.Context, chainID, destination, nonce uint32) (*uint64, error)
	// GetEarliestStateInRange gets the earliest state with the same snapshot root as an attestation within a nonce range.
	// 1. Get all states that are within a nonce range.
	// 2. Get the state with the earliest attestation associated to it.
	GetEarliestStateInRange(ctx context.Context, chainID, destination, startNonce, endNonce uint32) (*agentsTypes.State, error)
}

ExecutorDBReader is the interface for reading from the executor database.

type ExecutorDBWriter

type ExecutorDBWriter interface {
	// StoreMessage stores a message in the database.
	StoreMessage(ctx context.Context, message agentsTypes.Message, blockNumber uint64, minimumTimeSet bool, minimumTime uint64) error
	// ExecuteMessage marks a message as executed in the database.
	ExecuteMessage(ctx context.Context, messageMask DBMessage) error
	// SetMinimumTime sets the minimum time of a message.
	SetMinimumTime(ctx context.Context, messageMask DBMessage, minimumTime uint64) error

	// StoreAttestation stores an attestation.
	StoreAttestation(ctx context.Context, attestation agentsTypes.Attestation, destination uint32, destinationBlockNumber, destinationTimestamp uint64) error

	// StoreState stores a state.
	StoreState(ctx context.Context, state agentsTypes.State, snapshotRoot [32]byte, proof [][]byte, stateIndex uint32, blockNumber uint64) error
	// StoreStates stores multiple states with the same snapshot root.
	StoreStates(ctx context.Context, states []agentsTypes.State, snapshotRoot [32]byte, proofs [][][]byte, blockNumber uint64) error
}

ExecutorDBWriter is the interface for writing to the executor database.