storage

Documentation

Overview

Package storage defines storage interfaces.

Index

• func IsValidText(text string) bool
• type BatchItem
• type BeaconData
• type ConsensusAllData
• type ConsensusBlockData
• type ConsensusSourceStorage
• type GovernanceData
• type QueryBatch
  • func (b *QueryBatch) AsPgxBatch() pgx.Batch
  • func (b *QueryBatch) Extend(qb *QueryBatch)
  • func (b *QueryBatch) Len() int
  • func (b *QueryBatch) Queries() []*BatchItem
  • func (b *QueryBatch) Queue(cmd string, args ...interface{})
• type QueryResult
• type QueryResults
• type RegistryData
• type RootHashData
• type SchedulerData
• type StakingData
• type TargetStorage
• type Tx
• type TxOptions

Functions

func IsValidText

func IsValidText(text string) bool

IsValidText returns true iff the given string is valid UTF-8 and does not contain any NUL bytes. Postgresql TEXT field requires valid UTF8 strings and does not allow NUL bytes.

Types

type BatchItem

type BatchItem struct {
	Cmd  string
	Args []interface{}
}

type BeaconData

type BeaconData struct {
	Height int64

	Epoch  beacon.EpochTime
	Beacon []byte
}

BeaconData represents data for the random beacon at a given height.

type ConsensusAllData

type ConsensusAllData struct {
	BlockData      *ConsensusBlockData
	BeaconData     *BeaconData
	RegistryData   *RegistryData
	RootHashData   *RootHashData
	StakingData    *StakingData
	SchedulerData  *SchedulerData
	GovernanceData *GovernanceData
}

type ConsensusBlockData

type ConsensusBlockData struct {
	Height int64

	BlockHeader             *consensus.Block
	Epoch                   beacon.EpochTime
	TransactionsWithResults []nodeapi.TransactionWithResults
}

ConsensusBlockData represents data for a consensus block at a given height.

type ConsensusSourceStorage

type ConsensusSourceStorage interface {
	// GenesisDocument returns the genesis document for the chain.
	GenesisDocument(ctx context.Context, chainContext string) (*genesisAPI.Document, error)

	// AllData returns all data tied to a specific height.
	AllData(ctx context.Context, height int64) (*ConsensusAllData, error)

	// LatestBlockHeight returns the latest height for which a block is available.
	LatestBlockHeight(ctx context.Context) (int64, error)

	// BlockData gets block data at the specified height. This includes all
	// block header information, as well as transactions and events included
	// within that block.
	BlockData(ctx context.Context, height int64) (*ConsensusBlockData, error)

	// BeaconData gets beacon data at the specified height. This includes
	// the epoch number at that height, as well as the beacon state.
	BeaconData(ctx context.Context, height int64) (*BeaconData, error)

	// RegistryData gets registry data at the specified height. This includes
	// all registered entities and their controlled nodes and statuses.
	RegistryData(ctx context.Context, height int64) (*RegistryData, error)

	// StakingData gets staking data at the specified height. This includes
	// staking backend events to be applied to indexed state.
	StakingData(ctx context.Context, height int64) (*StakingData, error)

	// SchedulerData gets scheduler data at the specified height. This
	// includes all validators and runtime committees.
	SchedulerData(ctx context.Context, height int64) (*SchedulerData, error)

	// GovernanceData gets governance data at the specified height. This
	// includes all proposals, their respective statuses and voting responses.
	GovernanceData(ctx context.Context, height int64) (*GovernanceData, error)

	// RootHashData gets root hash data at the specified height. This includes
	// root hash events.
	RootHashData(ctx context.Context, height int64) (*RootHashData, error)

	// Name returns the name of the source storage.
	Name() string

	// Close instructs the source storage to clean up resources. Calling other
	// methods after this one results in undefined behavior.
	Close() error
}

ConsensusSourceStorage defines an interface for retrieving raw block data from the consensus layer.

type GovernanceData

type GovernanceData struct {
	Height int64

	Events                []nodeapi.Event
	ProposalSubmissions   []nodeapi.Proposal
	ProposalExecutions    []nodeapi.ProposalExecutedEvent
	ProposalFinalizations []nodeapi.Proposal
	Votes                 []nodeapi.VoteEvent
}

GovernanceData represents governance data for proposals at a given height.

Note: The governance backend supports getting events directly. We support retrieving events as updates to apply when getting data at a specific height.

type QueryBatch

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

QueryBatch represents a batch of queries to be executed atomically. We use a custom type that mirrors `pgx.Batch`, but is thread-safe to use and allows introspection for debugging.

func (*QueryBatch) AsPgxBatch

func (b *QueryBatch) AsPgxBatch() pgx.Batch

AsPgxBatch converts a QueryBatch to a pgx.Batch.

func (*QueryBatch) Extend

func (b *QueryBatch) Extend(qb *QueryBatch)

Extend merges another batch into the current batch.

func (*QueryBatch) Len

func (b *QueryBatch) Len() int

Len returns the number of queries in the batch.

func (*QueryBatch) Queries

func (b *QueryBatch) Queries() []*BatchItem

Queries returns the queries in the batch. Each item of the returned slice is composed of the SQL command and its arguments.

func (*QueryBatch) Queue

func (b *QueryBatch) Queue(cmd string, args ...interface{})

Queue adds query to a batch.

type QueryResult

type QueryResult = pgx.Row

QueryResult represents the result from a read query.

type QueryResults

type QueryResults = pgx.Rows

QueryResults represents the results from a read query.

type RegistryData

type RegistryData struct {
	Height int64

	Events                  []nodeapi.Event
	RuntimeRegisteredEvents []nodeapi.RuntimeRegisteredEvent
	EntityEvents            []nodeapi.EntityEvent
	NodeEvents              []nodeapi.NodeEvent
	NodeUnfrozenEvents      []nodeapi.NodeUnfrozenEvent
}

RegistryData represents data for the node registry at a given height.

Note: The registry backend supports getting events directly. We support retrieving events as updates to apply when getting data at specific height.

type RootHashData

type RootHashData struct {
	Height int64

	Events []nodeapi.Event
}

RootHashData represents data for runtime processing at a given height.

type SchedulerData

type SchedulerData struct {
	Height int64

	Validators []nodeapi.Validator
	Committees map[coreCommon.Namespace][]nodeapi.Committee
}

SchedulerData represents data for elected committees and validators at a given height.

type StakingData

type StakingData struct {
	Height int64
	Epoch  beacon.EpochTime

	Events                []nodeapi.Event
	Transfers             []nodeapi.TransferEvent
	Burns                 []nodeapi.BurnEvent
	AddEscrows            []nodeapi.AddEscrowEvent
	TakeEscrows           []nodeapi.TakeEscrowEvent
	ReclaimEscrows        []nodeapi.ReclaimEscrowEvent
	DebondingStartEscrows []nodeapi.DebondingStartEscrowEvent
	AllowanceChanges      []nodeapi.AllowanceChangeEvent
}

StakingData represents data for accounts at a given height.

Note: The staking backend supports getting events directly. We support retrieving events as updates to apply when getting data at specific height.

type TargetStorage

type TargetStorage interface {
	// SendBatch sends a batch of queries to be applied to target storage.
	SendBatch(ctx context.Context, batch *QueryBatch) error

	// SendBatchWithOptions is like SendBatch, with custom DB options (e.g. level of tx isolation).
	SendBatchWithOptions(ctx context.Context, batch *QueryBatch, opts TxOptions) error

	// Query submits a query to fetch data from target storage.
	Query(ctx context.Context, sql string, args ...interface{}) (QueryResults, error)

	// QueryRow submits a query to fetch a single row of data from target storage.
	QueryRow(ctx context.Context, sql string, args ...interface{}) QueryResult

	// Begin starts a new transaction.
	// XXX: Not the nicest that this exposes the underlying pgx.Tx interface. Could instead
	// return a `TargetStorage`-like interface wrapper, that only exposes Query/QueryRow/SendBatch/SendBatchWithOptions
	// and Commit/Rollback.
	Begin(ctx context.Context) (Tx, error)

	// Close shuts down the target storage client.
	Close()

	// Name returns the name of the target storage.
	Name() string

	// Wipe removes all contents of the target storage.
	Wipe(ctx context.Context) error

	// DisableTriggersAndFKConstraints disables all triggers and foreign key constraints
	// in nexus tables. This is useful when inserting blockchain data out of order,
	// so that later blocks can refer to (yet unindexed) earlier blocks without violating constraints.
	DisableTriggersAndFKConstraints(ctx context.Context) error

	// EnableTriggersAndFKConstraints enables all triggers and foreign key constraints
	// in the given schema.
	// WARNING: This might enable triggers not explicitly disabled by DisableTriggersAndFKConstraints.
	// WARNING: This does not enforce/check contraints on rows that were inserted while triggers were disabled.
	EnableTriggersAndFKConstraints(ctx context.Context) error
}

TargetStorage defines an interface for reading and writing processed block data.

type Tx

type Tx = pgx.Tx

Tx represents a database transaction.

type TxOptions

type TxOptions = pgx.TxOptions

TxOptions encodes the way DB transactions are executed.