blockdb

Documentation

Overview

Package blockdb saves chain and block data for inspection later to aid in debugging interchaintest failures.

Index

• func ConnectDB(ctx context.Context, databasePath string) (*sql.DB, error)
• func Migrate(db *sql.DB, gitSha string) error
• type BlockSaver
• type Chain
  • func (chain *Chain) SaveBlock(ctx context.Context, height uint64, txs []Tx) error
• type Collector
  • func NewCollector(log *zap.Logger, finder TxFinder, saver BlockSaver, rate time.Duration) *Collector
  • func (p *Collector) Collect(ctx context.Context)
  • func (p *Collector) Stop()
• type CosmosMessageResult
• type Event
• type EventAttribute
• type Query
  • func NewQuery(db *sql.DB) *Query
  • func (q *Query) CosmosMessages(ctx context.Context, chainPkey int64) ([]CosmosMessageResult, error)
  • func (q *Query) CurrentSchemaVersion(ctx context.Context) (SchemaVersionResult, error)
  • func (q *Query) RecentTestCases(ctx context.Context, limit int) ([]TestCaseResult, error)
  • func (q *Query) Transactions(ctx context.Context, chainPkey int64) ([]TxResult, error)
• type SchemaVersionResult
• type TestCase
  • func CreateTestCase(ctx context.Context, db *sql.DB, testName, gitSha string) (*TestCase, error)
  • func (tc *TestCase) AddChain(ctx context.Context, chainID, chainType string) (*Chain, error)
• type TestCaseResult
• type Tx
• type TxFinder
• type TxResult

Functions

func ConnectDB

func ConnectDB(ctx context.Context, databasePath string) (*sql.DB, error)

ConnectDB connects to the sqlite database at databasePath. Auto-creates directory path via MkdirAll. Pings database once to ensure connection. Pass :memory: as databasePath for in-memory database.

func Migrate

func Migrate(db *sql.DB, gitSha string) error

Migrate migrates db in an idempotent manner. If an error is returned, it's acceptable to delete the database and start over. The basic ERD is as follows:

┌────────────────────┐          ┌────────────────────┐         ┌────────────────────┐          ┌────────────────────┐
│                    │          │                    │         │                    │          │                    │
│                    │         ╱│                    │        ╱│                    │         ╱│                    │
│     Test Case      │───────┼──│       Chain        │───────○─│       Block        │────────○─│         Tx         │
│                    │         ╲│                    │        ╲│                    │         ╲│                    │
│                    │          │                    │         │                    │          │                    │
└────────────────────┘          └────────────────────┘         └────────────────────┘          └────────────────────┘

The gitSha ensures we can trace back to the version of the codebase that produced the schema. Warning: Typical best practice wraps each migration step into its own transaction. For simplicity given this is an embedded database, we omit transactions.

Types

type BlockSaver

type BlockSaver interface {
	SaveBlock(ctx context.Context, height uint64, txs []Tx) error
}

BlockSaver saves transactions for block at height.

type Chain

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

Chain tracks its blocks and a block's transactions.

func (*Chain) SaveBlock

func (chain *Chain) SaveBlock(ctx context.Context, height uint64, txs []Tx) error

SaveBlock tracks a block at height with its transactions. This method is idempotent and can be safely called multiple times with the same arguments. The txs should be human-readable.

type Collector

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

Collector saves block transactions at regular intervals.

func NewCollector

func NewCollector(log *zap.Logger, finder TxFinder, saver BlockSaver, rate time.Duration) *Collector

NewCollector creates a valid Collector that polls every duration at rate. The rate should be less than the time it takes to produce a block. Typically, a rate that will collect a few times a second is sufficient such as 100-200ms.

func (*Collector) Collect

func (p *Collector) Collect(ctx context.Context)

Collect saves block transactions starting at height 1 and advancing by 1 height as long as there are no errors with finding or saving the transactions.

func (*Collector) Stop

func (p *Collector) Stop()

Stop terminates the Collect loop. Stop is safe to be called concurrently and is safe to be called multiple times.

If Collect has not been called, Stop panics.

type CosmosMessageResult

type CosmosMessageResult struct {
	Height int64
	Index  int
	Type   string // URI for proto definition, e.g. /ibc.core.client.v1.MsgCreateClient

	ClientChainID sql.NullString

	ClientID             sql.NullString
	CounterpartyClientID sql.NullString

	ConnID             sql.NullString
	CounterpartyConnID sql.NullString

	PortID             sql.NullString
	CounterpartyPortID sql.NullString

	ChannelID             sql.NullString
	CounterpartyChannelID sql.NullString
}

type Event

type Event struct {
	Type       string
	Attributes []EventAttribute
}

Event is an alternative representation of tendermint/abci/types.Event, so that the blockdb package does not depend directly on tendermint.

type EventAttribute

type EventAttribute struct {
	Key, Value string
}

type Query

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

Query is a service that queries the database.

func NewQuery

func NewQuery(db *sql.DB) *Query

func (*Query) CosmosMessages

func (q *Query) CosmosMessages(ctx context.Context, chainPkey int64) ([]CosmosMessageResult, error)

CosmosMessages returns a summary of Cosmos messages for the chainID. In Cosmos, a transaction may have 1 or more associated messages. chainPkey is the chain primary key "chain.id", not to be confused with the column "chain_id".

func (*Query) CurrentSchemaVersion

func (q *Query) CurrentSchemaVersion(ctx context.Context) (SchemaVersionResult, error)

CurrentSchemaVersion returns the latest git sha and time that produced the sqlite schema.

func (*Query) RecentTestCases

func (q *Query) RecentTestCases(ctx context.Context, limit int) ([]TestCaseResult, error)

RecentTestCases returns aggregated data for each test case and chain combination.

func (*Query) Transactions

func (q *Query) Transactions(ctx context.Context, chainPkey int64) ([]TxResult, error)

Transactions returns TxResults only for blocks with transactions present. chainPkey is the chain primary key "chain.id", not to be confused with the column "chain_id".

type SchemaVersionResult

type SchemaVersionResult struct {
	GitSha string
	// Always set to user's local time zone.
	CreatedAt time.Time
}

type TestCase

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

TestCase is a single test invocation.

func CreateTestCase

func CreateTestCase(ctx context.Context, db *sql.DB, testName, gitSha string) (*TestCase, error)

CreateTestCase starts tracking new test case with testName.

func (*TestCase) AddChain

func (tc *TestCase) AddChain(ctx context.Context, chainID, chainType string) (*Chain, error)

AddChain tracks and attaches a chain to the test case. The chainID must be unique per test case. E.g. osmosis-1001, cosmos-1004 The chainType denotes which ecosystem the chain belongs to. E.g. cosmos, penumbra, composable, etc.

type TestCaseResult

type TestCaseResult struct {
	ID          int64
	Name        string
	GitSha      string // Git commit that ran the test.
	CreatedAt   time.Time
	ChainPKey   int64  // chain primary key
	ChainID     string // E.g. osmosis-1001
	ChainType   string // E.g. cosmos, penumbra
	ChainHeight sql.NullInt64
	TxTotal     sql.NullInt64
}

TestCaseResult is a combination of a single test case and single chain associated with the test case.

type Tx

type Tx struct {
	// For Tendermint transactions, this should be encoded as JSON.
	// Otherwise, this should be a human-readable format if possible.
	Data []byte

	// Events associated with the transaction, if applicable.
	Events []Event
}

type TxFinder

type TxFinder interface {
	FindTxs(ctx context.Context, height uint64) ([]Tx, error)
}

TxFinder finds transactions given block at height.

type TxResult

type TxResult struct {
	Height int64
	Tx     []byte
}