common

Documentation

Index

• type App
• type BlockContext
• type ChainContext
• type Engine
• type ExecutionData
  • func (e *ExecutionData) Clean() error
• type MigrationContext
• type NetworkParameters
• type SchemaGetter
• type Service
  • func (s *Service) NamedLogger(name string) *Service
• type TxContext

Types

type App

type App struct {
	// Service is the base application
	Service *Service
	// DB is a connection to the underlying Postgres database
	DB sql.DB
	// Engine is the underlying KwilDB engine, capable of storing and
	// executing against
	// Kuneiform schemas
	Engine Engine
}

App is an application that can modify and query the local database instance.

type BlockContext

type BlockContext struct {
	// ChainContext contains information about the chain.
	ChainContext *ChainContext
	// Height gets the height of the current block.
	Height int64
	// Timestamp is a timestamp of the current block.
	// It is set by the block proposer, and therefore may not be accurate.
	// It should not be used for time-sensitive operations where incorrect
	// timestamps could result in security vulnerabilities.
	Timestamp int64
	// Proposer gets the proposer public key of the current block.
	Proposer []byte
}

BlockContext provides context for all block operations.

type ChainContext

type ChainContext struct {
	// ChainID is the unique identifier for the chain.
	ChainID string

	// NetworkParams holds network level parameters that can be evolved
	// over the lifetime of a network.
	NetworkParameters *NetworkParameters

	// MigrationParams holds the context for all migration operations such as
	// block info to poll for the changesets from the old chain during migration.
	MigrationParams *MigrationContext
}

ChainContext provides context for all chain operations. Fields in ChainContext should never be mutated, except NetworkParameters can be deterministically mutated as part of block execution.

type Engine

type Engine interface {
	SchemaGetter
	// CreateDataset deploys a new dataset from a schema.
	// The dataset will be owned by the caller.
	CreateDataset(ctx *TxContext, tx sql.DB, schema *types.Schema) error
	// DeleteDataset deletes a dataset.
	// The caller must be the owner of the dataset.
	DeleteDataset(ctx *TxContext, tx sql.DB, dbid string) error
	// Procedure executes a procedure in a dataset. It can be given
	// either a readwrite or readonly database transaction. If it is
	// given a read-only transaction, it will not be able to execute
	// any procedures that are not `view`.
	Procedure(ctx *TxContext, tx sql.DB, options *ExecutionData) (*sql.ResultSet, error)
	// ListDatasets returns a list of all datasets on the network.
	ListDatasets(caller []byte) ([]*types.DatasetIdentifier, error)
	// Execute executes a SQL statement on a dataset.
	// It uses Kwil's SQL dialect.
	Execute(ctx *TxContext, tx sql.DB, dbid, query string, values map[string]any) (*sql.ResultSet, error)
	// Reload reloads the engine with the latest db state
	Reload(ctx context.Context, tx sql.Executor) error
}

Engine is an interface for the main database engine that is responsible for deploying and executing Kuneiform datasets.

type ExecutionData

type ExecutionData struct {
	//TxCtx *TxContext
	// Dataset is the DBID of the dataset that was called.
	// Even if a procedure in another dataset is called, this will
	// always be the original dataset.
	Dataset string

	// Procedure is the original procedure that was called.
	// Even if a nested procedure is called, this will always be the
	// original procedure.
	Procedure string

	// Args are the arguments that were passed to the procedure.
	// Currently these are all string or untyped nil values.
	Args []any
}

ExecutionOptions is contextual data that is passed to a procedure during call / execution. It is scoped to the lifetime of a single execution.

func (*ExecutionData) Clean

func (e *ExecutionData) Clean() error

type MigrationContext

type MigrationContext struct {
	// StartHeight is the height of the first block to start migration.
	StartHeight int64
	// EndHeight is the height of the last block to end migration.
	EndHeight int64
}

MigrationContext provides context for all migration operations. Fields in MigrationContext should never be mutated till the migration is completed.

type NetworkParameters

type NetworkParameters struct {
	// MaxBlockSize is the maximum size of a block in bytes.
	MaxBlockSize int64
	// JoinExpiry is the number of blocks after which the validators
	// join request expires if not approved.
	JoinExpiry int64
	// VoteExpiry is the default number of blocks after which the validators
	// vote expires if not approved.
	VoteExpiry int64
	// DisabledGasCosts dictates whether gas costs are disabled.
	DisabledGasCosts bool

	// MigrationStatus determines the status of the migration.
	MigrationStatus types.MigrationStatus

	// MaxVotesPerTx is the maximum number of votes that can be included in a
	// single transaction.
	MaxVotesPerTx int64
}

NetworkParameters are network level configurations that can be evolved over the lifetime of a network.

type SchemaGetter

type SchemaGetter interface {
	// GetSchema returns the schema of a dataset.
	// It will return an error if the dataset does not exist.
	GetSchema(dbid string) (*types.Schema, error)
}

SchemaGetter is an interface for getting the schema of a dataset.

type Service

type Service struct {
	// Logger is a logger for the application
	Logger log.SugaredLogger
	// ExtensionConfigs is a map of the nodes extensions and local
	// configurations.
	// It maps: extension_name -> config_key -> config_value
	//
	// DEPRECATED: Use LocalConfig.AppCfg.Extensions instead.
	ExtensionConfigs map[string]map[string]string
	// GenesisConfig is the genesis configuration of the network.
	GenesisConfig *chain.GenesisConfig
	// LocalConfig is the local configuration of the node.
	LocalConfig *config.KwildConfig
	// Identity is the node/validator identity (pubkey).
	Identity []byte
}

Service provides access to general application information to extensions.

func (*Service) NamedLogger

func (s *Service) NamedLogger(name string) *Service

NameLogger returns a new Service with the logger named. Every other field is the same pointer as the original.

type TxContext

type TxContext struct {
	Ctx context.Context
	// BlockContext is the context of the current block.
	BlockContext *BlockContext
	// TxID is the ID of the current transaction.
	TxID string
	// Signer is the public key of the transaction signer.
	Signer []byte
	// Caller is the string identifier of the transaction signer.
	// It is derived from the signer's registered authenticator.
	Caller string
	// Authenticator is the authenticator used to sign the transaction.
	Authenticator string
}

TxContext is contextual information provided to a transaction execution Route handler. This is defined in common as it is used by both the internal txapp router and extension implementations in extensions/consensus.