common

Documentation

Index

• type Accounts
• type App
• type BlockContext
• type CallResult
• type ChainContext
• type Engine
• type EngineContext
  • func (e *EngineContext) Valid() error
• type MigrationContext
• type NetworkParameters
• type Row
• type Service
  • func (s *Service) NamedLogger(name string) *Service
• type TxContext
• type Validators

Types

type Accounts

type Accounts interface {
	// Credit credits an account with the given amount. If the account
	// does not exist, it will be created. A negative amount will be
	// treated as a debit. Accounts cannot have negative balances, and
	// will return an error if the amount would cause the balance to go
	// negative.
	Credit(ctx context.Context, tx sql.Executor, account *types.AccountID, balance *big.Int) error
	// Transfer transfers an amount from one account to another. If the
	// from account does not have enough funds to transfer the amount,
	// it will fail. If the to account does not exist, it will be
	// created. The amount must be greater than 0.
	Transfer(ctx context.Context, tx sql.TxMaker, from, to *types.AccountID, amt *big.Int) error
	// GetAccount retrieves the account with the given identifier. If the
	// account does not exist, it will return an account with a balance
	// of 0 and a nonce of 0.
	GetAccount(ctx context.Context, tx sql.Executor, account *types.AccountID) (*types.Account, error)
	// ApplySpend applies a spend to the account. If the account does not
	// exist, it will be created. If the account does not have enough
	// funds to spend the amount, the entire balance will be spent and
	// the spend will fail.
	ApplySpend(ctx context.Context, tx sql.Executor, account *types.AccountID, amount *big.Int, nonce int64) error
}

Accounts is an interface for managing accounts on the Kwil network. It should be used to credit, debit, and transfer funds between Kwil accounts.

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
	// Accounts is the account manager for the application
	Accounts Accounts
	// Validators is the validator manager for the application
	Validators Validators
}

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
	// Hash is the hash of the current block.
	// It can be empty if the block is the genesis block and
	// no initial state hash was specified in the genesis configuration.
	Hash types.Hash
	// Timestamp is a timestamp of the current block, in seconds (UNIX epoch).
	// 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 crypto.PublicKey
}

BlockContext provides context for all block operations.

type CallResult

type CallResult struct {
	// Logs are the logs generated by the action.
	Logs []string
}

CallResult is the result of a call to an action. It does not include the records, as they should be consumed via the resultFn callback.

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

	NetworkUpdates types.ParamUpdates

	// 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. TODO: review these contexts and see if all the fields are necessary

type Engine

type Engine interface {
	// Call calls an action in the database. The resultFn callback is
	// called for each row in the result set. If the resultFn returns
	// an error, the call will be aborted and the error will be returned.
	Call(ctx *EngineContext, db sql.DB, namespace, action string, args []any, resultFn func(*Row) error) (*CallResult, error)
	// Execute executes a statement in the database. The fn callback is
	// called for each row in the result set. If the fn returns an error,
	// the call will be aborted and the error will be returned.
	Execute(ctx *EngineContext, db sql.DB, statement string, params map[string]any, fn func(*Row) error) error
	// ExecuteWithoutEngineCtx executes a statement in the database without
	// needing an engine context. This is useful for extensions that need to
	// interact with the engine outside of a transaction. If possible, use
	// Execute instead.
	ExecuteWithoutEngineCtx(ctx context.Context, db sql.DB, statement string, params map[string]any, fn func(*Row) error) error
}

type EngineContext

type EngineContext struct {
	// TxContext is the transaction context of the current transaction.
	TxContext *TxContext
	// OverrideAuthz is a flag that indicates whether the authorization
	// should be overridden. This is used to allow extensions to perform
	// owner-level operations on the database, even if the caller is not
	// the owner.
	OverrideAuthz bool
	// InvalidTxCtx is a flag that indicates whether the transaction context
	// is valid / can be used. There are times when the engine is called
	// while not within a transaction (e.g. by extensions to read in metadata)
	// on startup. In these cases, the transaction context is not valid.
	// This will disable all system variables (e.g. @caller). If users are
	// not in a transaction but still want to use system variables (e.g. in an
	// RPC making read-only calls to the engine), they should set this to false,
	// and make sure to create a fake transaction context.
	// If InvalidTxCtx is set to true, OverrideAuthz should also be set to true.
	InvalidTxCtx bool
}

EngineContext is a context that is passed to the engine when executing an action or statement.

func (*EngineContext) Valid

func (e *EngineContext) Valid() 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 = types.NetworkParameters

type Row

type Row struct {
	// ColumnNames are the names of the columns in the row.
	ColumnNames []string
	// ColumnTypes are the types of the columns in the row.
	ColumnTypes []*types.DataType
	// Values are the values of the columns in the row.
	Values []any
}

Row contains information about a row in a table.

type Service

type Service struct {
	// Logger is a logger for the application
	Logger log.Logger

	// GenesisConfig is the genesis configuration of the network.
	GenesisConfig *config.GenesisConfig

	// LocalConfig is the local configuration of the node.
	LocalConfig *config.Config

	// Identity is the node/validator identity (pubkey).
	Identity []byte // maybe this actuall needs to be crypto.PubKey???
}

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.

type Validators

type Validators interface {
	// GetValidatorPower retrieves the power of the given validator. If
	// the validator does not exist, it will return 0.
	GetValidatorPower(ctx context.Context, pubKey []byte, pubKeyType crypto.KeyType) (int64, error)
	// GetValidators retrieves all validators.
	GetValidators() []*types.Validator
	// SetValidatorPower sets the power of a validator. If the target
	// validator does not exist, it will be created with the given power.
	// If set to 0, the target validator will be deleted, and will no
	// longer be considered a validator. It will return an error if a
	// negative power is given.
	SetValidatorPower(ctx context.Context, tx sql.Executor, pubKey []byte, pubKeyType crypto.KeyType, power int64) error
}

Validators is an interface for managing validators on the Kwil network.