ledger

package
v0.0.0-...-c490c22 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Feb 10, 2025 License: AGPL-3.0 Imports: 49 Imported by: 1

README

Ledger

The ledger represents the state of an Algorand node. The core state of the ledger is a sequence of blocks (the blockchain). The ledger also maintains several trackers: state machines that consume the blockchain as input. One example of a tracker is the account state tracker, which keeps track of the state of individual accounts (balance, status, etc).

The external API for the ledger (for use by callers outside of this package) is defined in ledger.go.

Blocks

The ledger exposes the following functions for managing the blocks:

  • AddBlock(block, cert) adds a new block to the ledger, along with a certificate for that block. The ledger does not check the certificate's validity. If the block is not from the correct round (i.e., latest known plus one), an error is returned. The block is added to an in-memory queue of pending blocks, and is flushed to disk in the background for performance.

  • WaitForCommit(round) waits for the block for round to be written to persistent storage. After WaitForCommit(round) returns, the ledger guarantees that the block will be present even after a crash.

  • Latest() returns the last block added to the ledger.

  • LatestCommitted() returns the last block written to durable storage as well as the round of the latest block added to the ledger.

  • Block(round) returns the block for round, or ErrNoEntry if no such block has been added. Similarly, BlockCert(round) will return the block and the associated certificate.

  • Wait(round) allows the caller to wait for a block to be added to the ledger for round, by returning a channel that will be closed when a block for round is added.

Tracker API

The ledger comes with a set of trackers. Each tracker maintains a state machine based on the blockchain contents. Trackers are logically stateless: that is, they can reconstruct their state by consuming all blocks from the beginning of the blockchain. As an optimization, the ledger allows trackers to store persistent state, so that they can reconstruct their state quickly, without considering every block.

The interface between ledger and trackers is defined in tracker.go.

Trackers have access to the ledger through a restricted API defined by ledgerForTracker. This allows trackers to access the ledger's SQLite database, to query for blocks, etc.

Conversely, the ledger accesses trackers through the ledgerTracker interface:

  • loadFromDisk(ledgerForTracker) initializes the state of the tracker. The tracker can use the ledgerForTracker argument to load persistent state (e.g., for the accounts database). The tracker can also query for recent blocks, if the tracker's state depends only on recent blocks (e.g., for the tracker that keeps track of the recently committed transactions).

  • newBlock(rnd, delta) tells the tracker about a new block added to the ledger. delta describes the changes made by this block; this will be described in more details under block evaluation later.

  • committedUpTo(rnd) tells the tracker that all blocks up to and including rnd are written to persistent storage. This call is important for trackers that store persistent state themselves, since the tracker must be able to restore its state correctly after a crash, and may need to answer queries about older blocks after a crash if some recent non-committed blocks are lost.

  • close() frees up any resources held by this tracker.

The ledger serializes all updates to the trackers with a reader-writer lock.

Trackers

An individual tracker exposes tracker-specific APIs for accessing the state maintained by that tracker. These are currently passed through the Ledger object, so that the ledger can provide appropriate reader-writer locking.

Account tracker

  • Lookup(round, address) uses the account tracker to look up the state of an account as of round.

  • AllBalances(round) uses the account tracker to return the set of all account states as of round. This is likely to be large, so it's intended for debug purposes only.

  • Totals(round) returns the totals of accounts, using the account tracker.

Recent transactions tracker
  • Committed(txnid) returns whether txid has been recently committed, using the transaction tail tracker.
Participation tracker
  • ParticipationThresholds() returns the participation thresholds, from the participation tracker.
Delegator tracker
  • DumpDelegatorsTree() returns the tree of delegators for offline rewards, from the delegator tracker, for debug purposes.
Notification tracker
  • RegisterBlockListeners(listeners) registers listeners for new blocks, based on the pools.BlockListener API.

Block evaluation

Finally, the ledger implements logic to evaluate blocks. It supports three functions:

  • Construct a new block, based on a pool of potential transactions and rewards, that will be valid. This is done by using the Ledger.StartEvaluator(hdr, txcache) method. This returns a BlockEvaluator, which can then accept tentative transactions and rewards (using BlockEvaluator.Transaction() and BlockEvaluator.Reward()). The caller can finalize the block by calling BlockEvaluator.GenerateBlock(). txcache represents a cache of previously verified transactions, to avoid repeated checking of transaction signatures.

  • Validate a block. This is done by calling Ledger.Validate(block, txcache). Under the covers, it executes the same logic using a BlockEvaluator.

  • Evaluate a block to produce a delta describing the changes that this block implies for all of the trackers. This is the delta passed to the newBlock() method of trackers.

Block evaluation also produces auxiliary state, evalAux, which describes the state needed to evaluate a block. Currently, this consists of the set of offline rewards. Computing evalAux may require access to past blocks or the old state of various state trackers (in particular, for the offline rewards, it requires access to the past state of the delegator tracker). However, given an evalAux, it is possible to evaluate the block. The BlockEvaluator computes the evalAux when first evaluating a block, and the ledger saves the evalAux state to re-evaluate the block after a crash as needed.

Documentation

Index

Constants

View Source 
const (
	// BalancesPerCatchpointFileChunk defines the number of accounts that would be stored in each chunk in the catchpoint file.
	// note that the last chunk would typically be less than this number.
	BalancesPerCatchpointFileChunk = 512

	// ResourcesPerCatchpointFileChunk defines the max number of resources that go in a singular chunk
	// 100,000 resources * 20KB/resource => roughly max 2GB per chunk if all of them are max'ed out apps.
	// In reality most entries are asset holdings, and they are very small.
	ResourcesPerCatchpointFileChunk = 100_000

	// SPContextPerCatchpointFile defines the maximum number of state proof verification data stored
	// in the catchpoint file.
	// (2 years * 31536000 seconds per year) / (256 rounds per state proof verification data * 3.6 seconds per round) ~= 70000
	SPContextPerCatchpointFile = 70000
)
View Source 
const (

	// CatchpointFileVersionV5 is the catchpoint file version that was used when the database schema was V0-V5.
	CatchpointFileVersionV5 = uint64(0200)
	// CatchpointFileVersionV6 is the catchpoint file version that is matching database schema since V6.
	// This version introduced accounts and resources separation. The first catchpoint
	// round of this version is >= `reenableCatchpointsRound`.
	CatchpointFileVersionV6 = uint64(0201)
	// CatchpointFileVersionV7 is the catchpoint file version that is matching database schema V10.
	// This version introduced state proof verification data and versioning for CatchpointLabel.
	CatchpointFileVersionV7 = uint64(0202)
	// CatchpointFileVersionV8 is the catchpoint file version that includes V6 and V7 data, as well
	// as historical onlineaccounts and onlineroundparamstail table data (added in DB version V7,
	// but until this version initialized with current round data, not 320 rounds of historical info).
	CatchpointFileVersionV8 = uint64(0203)

	// CatchpointContentFileName is a name of a file with catchpoint header info inside tar archive
	CatchpointContentFileName = "content.msgpack"
)
View Source 
const (
	// CatchpointCatchupStateInactive is the common state for the catchpoint catchup - not active.
	CatchpointCatchupStateInactive = iota
	// CatchpointCatchupStateLedgerDownload indicates that we're downloading the ledger
	CatchpointCatchupStateLedgerDownload
	// CatchpointCatchupStateLatestBlockDownload indicates that we're download the latest block
	CatchpointCatchupStateLatestBlockDownload
	// CatchpointCatchupStateBlocksDownload indicates that we're downloading the blocks prior to the latest one ( total of CatchpointLookback blocks )
	CatchpointCatchupStateBlocksDownload
	// CatchpointCatchupStateSwitch indicates that we're switching to use the downloaded ledger/blocks content
	CatchpointCatchupStateSwitch
)
View Source 
const MaxEncodedBaseAccountDataSize = 350

MaxEncodedBaseAccountDataSize is a rough estimate for the worst-case scenario we're going to have of the base account data serialized. this number is verified by the TestEncodedBaseAccountDataSize function.

View Source 
const MaxEncodedBaseResourceDataSize = 20000

MaxEncodedBaseResourceDataSize is a rough estimate for the worst-case scenario we're going to have of the base resource data serialized. this number is verified by the TestEncodedBaseResourceSize function.

Variables

View Source 
var ErrLookupLatestResources = errors.New("couldn't find latest resources")

ErrLookupLatestResources is returned if there is an error retrieving an account along with its resources.

Functions

func CatchpointCatchupStateMaxSize 

func CatchpointCatchupStateMaxSize() (s int)

MaxSize returns a maximum valid message size for this message type

func CatchpointFileHeaderMaxSize 

func CatchpointFileHeaderMaxSize() (s int)

MaxSize returns a maximum valid message size for this message type

func CatchpointSnapshotChunkV5MaxSize 

func CatchpointSnapshotChunkV5MaxSize() (s int)

MaxSize returns a maximum valid message size for this message type

func CatchpointSnapshotChunkV6MaxSize 

func CatchpointSnapshotChunkV6MaxSize() (s int)

MaxSize returns a maximum valid message size for this message type

func CatchpointStateProofVerificationContextMaxSize 

func CatchpointStateProofVerificationContextMaxSize() (s int)

MaxSize returns a maximum valid message size for this message type

func MakeDebugBalances 

func MakeDebugBalances(l DebuggerLedger, round basics.Round, proto protocol.ConsensusVersion, prevTimestamp int64) apply.Balances

MakeDebugBalances creates a ledger suitable for dryrun and debugger

Types

type CatchpointCatchupAccessor 

type CatchpointCatchupAccessor interface {
	// GetState returns the current state of the catchpoint catchup
	GetState(ctx context.Context) (state CatchpointCatchupState, err error)

	// SetState set the state of the catchpoint catchup
	SetState(ctx context.Context, state CatchpointCatchupState) (err error)

	// GetLabel returns the current catchpoint catchup label
	GetLabel(ctx context.Context) (label string, err error)

	// SetLabel set the catchpoint catchup label
	SetLabel(ctx context.Context, label string) (err error)

	// ResetStagingBalances resets the current staging balances, preparing for a new set of balances to be added
	ResetStagingBalances(ctx context.Context, newCatchup bool) (err error)

	// ProcessStagingBalances deserialize the given bytes as a temporary staging balances
	ProcessStagingBalances(ctx context.Context, sectionName string, bytes []byte, progress *CatchpointCatchupAccessorProgress) (err error)

	// BuildMerkleTrie inserts the account hashes into the merkle trie
	BuildMerkleTrie(ctx context.Context, progressUpdates func(uint64, uint64)) (err error)

	// GetCatchupBlockRound returns the latest block round matching the current catchpoint
	GetCatchupBlockRound(ctx context.Context) (round basics.Round, err error)

	// GetVerifyData returns the balances hash, spver hash and totals used by VerifyCatchpoint
	GetVerifyData(ctx context.Context) (balancesHash, spverHash, onlineAccountsHash, onlineRoundParamsHash crypto.Digest, totals ledgercore.AccountTotals, err error)

	// VerifyCatchpoint verifies that the catchpoint is valid by reconstructing the label.
	VerifyCatchpoint(ctx context.Context, blk *bookkeeping.Block) (err error)

	// StoreBalancesRound calculates the balances round based on the first block and the associated consensus parameters, and
	// store that to the database
	StoreBalancesRound(ctx context.Context, blk *bookkeeping.Block) (err error)

	// StoreFirstBlock stores a single block to the blocks database.
	StoreFirstBlock(ctx context.Context, blk *bookkeeping.Block, cert *agreement.Certificate) (err error)

	// StoreBlock stores a single block to the blocks database.
	StoreBlock(ctx context.Context, blk *bookkeeping.Block, cert *agreement.Certificate) (err error)

	// FinishBlocks concludes the catchup of the blocks database.
	FinishBlocks(ctx context.Context, applyChanges bool) (err error)

	// EnsureFirstBlock ensure that we have a single block in the staging block table, and returns that block
	EnsureFirstBlock(ctx context.Context) (blk bookkeeping.Block, err error)

	// CompleteCatchup completes the catchpoint catchup process by switching the databases tables around
	// and reloading the ledger.
	CompleteCatchup(ctx context.Context) (err error)

	// Ledger returns a narrow subset of Ledger methods needed by CatchpointCatchupAccessor clients
	Ledger() (l CatchupAccessorClientLedger)
}

CatchpointCatchupAccessor is an interface for the accessor wrapping the database storage for the catchpoint catchup functionality.

func MakeCatchpointCatchupAccessor 

func MakeCatchpointCatchupAccessor(ledger *Ledger, log logging.Logger) CatchpointCatchupAccessor

MakeCatchpointCatchupAccessor creates a CatchpointCatchupAccessor given a ledger

type CatchpointCatchupAccessorProgress 

type CatchpointCatchupAccessorProgress struct {
	TotalAccounts              uint64
	ProcessedAccounts          uint64
	ProcessedBytes             uint64
	TotalKVs                   uint64
	ProcessedKVs               uint64
	TotalOnlineAccounts        uint64
	ProcessedOnlineAccounts    uint64
	TotalOnlineRoundParams     uint64
	ProcessedOnlineRoundParams uint64
	TotalChunks                uint64
	SeenHeader                 bool
	Version                    uint64
	TotalAccountHashes         uint64

	BalancesWriteDuration          time.Duration
	CreatablesWriteDuration        time.Duration
	HashesWriteDuration            time.Duration
	KVWriteDuration                time.Duration
	OnlineAccountsWriteDuration    time.Duration
	OnlineRoundParamsWriteDuration time.Duration
	// contains filtered or unexported fields
}

CatchpointCatchupAccessorProgress is used by the caller of ProcessStagingBalances to obtain progress information

type CatchpointCatchupState 

type CatchpointCatchupState int32

CatchpointCatchupState is the state of the current catchpoint catchup process

func (CatchpointCatchupState) CanMarshalMsg 

func (_ CatchpointCatchupState) CanMarshalMsg(z interface{}) bool

func (*CatchpointCatchupState) CanUnmarshalMsg 

func (_ *CatchpointCatchupState) CanUnmarshalMsg(z interface{}) bool

func (CatchpointCatchupState) MarshalMsg 

func (z CatchpointCatchupState) MarshalMsg(b []byte) (o []byte)

MarshalMsg implements msgp.Marshaler

func (CatchpointCatchupState) MsgIsZero 

func (z CatchpointCatchupState) MsgIsZero() bool

MsgIsZero returns whether this is a zero value

func (CatchpointCatchupState) Msgsize 

func (z CatchpointCatchupState) Msgsize() (s int)

Msgsize returns an upper bound estimate of the number of bytes occupied by the serialized message

func (*CatchpointCatchupState) UnmarshalMsg 

func (z *CatchpointCatchupState) UnmarshalMsg(bts []byte) (o []byte, err error)

func (*CatchpointCatchupState) UnmarshalMsgWithState 

func (z *CatchpointCatchupState) UnmarshalMsgWithState(bts []byte, st msgp.UnmarshalState) (o []byte, err error)

UnmarshalMsg implements msgp.Unmarshaler

type CatchpointFileHeader 

type CatchpointFileHeader struct {
	Version                uint64                   `codec:"version"`
	BalancesRound          basics.Round             `codec:"balancesRound"`
	BlocksRound            basics.Round             `codec:"blocksRound"`
	Totals                 ledgercore.AccountTotals `codec:"accountTotals"`
	TotalAccounts          uint64                   `codec:"accountsCount"`
	TotalChunks            uint64                   `codec:"chunksCount"`
	TotalKVs               uint64                   `codec:"kvsCount"`
	TotalOnlineAccounts    uint64                   `codec:"onlineAccountsCount"`
	TotalOnlineRoundParams uint64                   `codec:"onlineRoundParamsCount"`
	Catchpoint             string                   `codec:"catchpoint"`
	BlockHeaderDigest      crypto.Digest            `codec:"blockHeaderDigest"`
	// contains filtered or unexported fields
}

CatchpointFileHeader is the content we would have in the "content.msgpack" file in the catchpoint tar archive. we need it to be public, as it's being decoded externally by the catchpointdump utility.

func (*CatchpointFileHeader) CanMarshalMsg 

func (_ *CatchpointFileHeader) CanMarshalMsg(z interface{}) bool

func (*CatchpointFileHeader) CanUnmarshalMsg 

func (_ *CatchpointFileHeader) CanUnmarshalMsg(z interface{}) bool

func (*CatchpointFileHeader) MarshalMsg 

func (z *CatchpointFileHeader) MarshalMsg(b []byte) (o []byte)

MarshalMsg implements msgp.Marshaler

func (*CatchpointFileHeader) MsgIsZero 

func (z *CatchpointFileHeader) MsgIsZero() bool

MsgIsZero returns whether this is a zero value

func (*CatchpointFileHeader) Msgsize 

func (z *CatchpointFileHeader) Msgsize() (s int)

Msgsize returns an upper bound estimate of the number of bytes occupied by the serialized message

func (*CatchpointFileHeader) UnmarshalMsg 

func (z *CatchpointFileHeader) UnmarshalMsg(bts []byte) (o []byte, err error)

func (*CatchpointFileHeader) UnmarshalMsgWithState 

func (z *CatchpointFileHeader) UnmarshalMsgWithState(bts []byte, st msgp.UnmarshalState) (o []byte, err error)

UnmarshalMsg implements msgp.Unmarshaler

type CatchpointSnapshotChunkV5 

type CatchpointSnapshotChunkV5 struct {
	Balances []encoded.BalanceRecordV5 `codec:"bl,allocbound=BalancesPerCatchpointFileChunk"`
	// contains filtered or unexported fields
}

CatchpointSnapshotChunkV5 defines the encoding of "balances.X.msgpack" files in the catchpoint snapshot used before database schema v6, which split accounts from asset/app resource data.

func (*CatchpointSnapshotChunkV5) CanMarshalMsg 

func (_ *CatchpointSnapshotChunkV5) CanMarshalMsg(z interface{}) bool

func (*CatchpointSnapshotChunkV5) CanUnmarshalMsg 

func (_ *CatchpointSnapshotChunkV5) CanUnmarshalMsg(z interface{}) bool

func (*CatchpointSnapshotChunkV5) MarshalMsg 

func (z *CatchpointSnapshotChunkV5) MarshalMsg(b []byte) (o []byte)

MarshalMsg implements msgp.Marshaler

func (*CatchpointSnapshotChunkV5) MsgIsZero 

func (z *CatchpointSnapshotChunkV5) MsgIsZero() bool

MsgIsZero returns whether this is a zero value

func (*CatchpointSnapshotChunkV5) Msgsize 

func (z *CatchpointSnapshotChunkV5) Msgsize() (s int)

Msgsize returns an upper bound estimate of the number of bytes occupied by the serialized message

func (*CatchpointSnapshotChunkV5) UnmarshalMsg 

func (z *CatchpointSnapshotChunkV5) UnmarshalMsg(bts []byte) (o []byte, err error)

func (*CatchpointSnapshotChunkV5) UnmarshalMsgWithState 

func (z *CatchpointSnapshotChunkV5) UnmarshalMsgWithState(bts []byte, st msgp.UnmarshalState) (o []byte, err error)

UnmarshalMsg implements msgp.Unmarshaler

type CatchpointSnapshotChunkV6 

type CatchpointSnapshotChunkV6 struct {
	Balances []encoded.BalanceRecordV6 `codec:"bl,allocbound=BalancesPerCatchpointFileChunk"`

	KVs               []encoded.KVRecordV6                `codec:"kv,allocbound=BalancesPerCatchpointFileChunk"`
	OnlineAccounts    []encoded.OnlineAccountRecordV6     `codec:"oa,allocbound=BalancesPerCatchpointFileChunk"`
	OnlineRoundParams []encoded.OnlineRoundParamsRecordV6 `codec:"orp,allocbound=BalancesPerCatchpointFileChunk"`
	// contains filtered or unexported fields
}

CatchpointSnapshotChunkV6 defines the current encoding of "balances.X.msgpack" files in the catchpoint snapshot.

func (*CatchpointSnapshotChunkV6) CanMarshalMsg 

func (_ *CatchpointSnapshotChunkV6) CanMarshalMsg(z interface{}) bool

func (*CatchpointSnapshotChunkV6) CanUnmarshalMsg 

func (_ *CatchpointSnapshotChunkV6) CanUnmarshalMsg(z interface{}) bool

func (*CatchpointSnapshotChunkV6) MarshalMsg 

func (z *CatchpointSnapshotChunkV6) MarshalMsg(b []byte) (o []byte)

MarshalMsg implements msgp.Marshaler

func (*CatchpointSnapshotChunkV6) MsgIsZero 

func (z *CatchpointSnapshotChunkV6) MsgIsZero() bool

MsgIsZero returns whether this is a zero value

func (*CatchpointSnapshotChunkV6) Msgsize 

func (z *CatchpointSnapshotChunkV6) Msgsize() (s int)

Msgsize returns an upper bound estimate of the number of bytes occupied by the serialized message

func (*CatchpointSnapshotChunkV6) UnmarshalMsg 

func (z *CatchpointSnapshotChunkV6) UnmarshalMsg(bts []byte) (o []byte, err error)

func (*CatchpointSnapshotChunkV6) UnmarshalMsgWithState 

func (z *CatchpointSnapshotChunkV6) UnmarshalMsgWithState(bts []byte, st msgp.UnmarshalState) (o []byte, err error)

UnmarshalMsg implements msgp.Unmarshaler

type CatchupAccessorClientLedger 

type CatchupAccessorClientLedger interface {
	BlockCert(rnd basics.Round) (blk bookkeeping.Block, cert agreement.Certificate, err error)
	GenesisHash() crypto.Digest
	BlockHdr(rnd basics.Round) (blk bookkeeping.BlockHeader, err error)
	Latest() (rnd basics.Round)
}

CatchupAccessorClientLedger represents ledger interface needed for catchpoint accessor clients

type DebuggerLedger 

type DebuggerLedger = eval.LedgerForCowBase

DebuggerLedger defines the minimal set of method required for creating a debug balances.

type DirsAndPrefix 

type DirsAndPrefix struct {
	config.ResolvedGenesisDirs
	DBFilePrefix string // the prefix of the database files, appended to genesis directories
}

DirsAndPrefix is a struct that holds the genesis directories and the database file prefix, so ledger can construct full paths to database files

type Ledger 

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

Ledger is a database storing the contents of the ledger.

func OpenLedger 

func OpenLedger[T string | DirsAndPrefix](

	log logging.Logger, dbPathPrefix T, dbMem bool, genesisInitState ledgercore.InitState, cfg config.Local,
) (*Ledger, error)

OpenLedger creates a Ledger object, using SQLite database filenames based on dbPathPrefix (in-memory if dbMem is true). genesisInitState.Blocks and genesisInitState.Accounts specify the initial blocks and accounts to use if the

func (*Ledger) AddBlock 

func (l *Ledger) AddBlock(blk bookkeeping.Block, cert agreement.Certificate) error

AddBlock adds a new block to the ledger. The block is stored in an in-memory queue and is written to the disk in the background. An error is returned if this is not the expected next block number.

func (*Ledger) AddValidatedBlock 

func (l *Ledger) AddValidatedBlock(vb ledgercore.ValidatedBlock, cert agreement.Certificate) error

AddValidatedBlock adds a new block to the ledger, after the block has been validated by calling Ledger.Validate(). This saves the cost of having to re-compute the effect of the block on the ledger state, if the block has previously been validated. Otherwise, AddValidatedBlock behaves like AddBlock.

func (*Ledger) Block 

func (l *Ledger) Block(rnd basics.Round) (blk bookkeeping.Block, err error)

Block returns the block for round rnd.

func (*Ledger) BlockCert 

func (l *Ledger) BlockCert(rnd basics.Round) (blk bookkeeping.Block, cert agreement.Certificate, err error)

BlockCert returns the block and the certificate of the block for round rnd.

func (*Ledger) BlockHdr 

func (l *Ledger) BlockHdr(rnd basics.Round) (blk bookkeeping.BlockHeader, err error)

BlockHdr returns the BlockHeader of the block for round rnd.

func (*Ledger) CheckConfirmedTail 

func (l *Ledger) CheckConfirmedTail(txid transactions.Txid) (basics.Round, bool)

CheckConfirmedTail checks if a transaction txid happens to have LastValid greater than the current round at the time of calling and has been already committed to the ledger. If both conditions are met it returns true. This function could be used as filter to check if a transaction is committed to the ledger, and no extra checks needed if it says true.

Note, this cannot be used to check if transaction happened or not in past MaxTxnLife rounds.

func (*Ledger) CheckDup 

func (l *Ledger) CheckDup(currentProto config.ConsensusParams, current basics.Round, firstValid basics.Round, lastValid basics.Round, txid transactions.Txid, txl ledgercore.Txlease) error

CheckDup return whether a transaction is a duplicate one.

func (*Ledger) Close 

func (l *Ledger) Close()

Close reclaims resources used by the ledger (namely, the database connection and goroutines used by trackers).

func (*Ledger) EncodedBlockCert 

func (l *Ledger) EncodedBlockCert(rnd basics.Round) (blk []byte, cert []byte, err error)

EncodedBlockCert returns the encoded block and the corresponding encoded certificate of the block for round rnd.

func (*Ledger) FlushCaches 

func (l *Ledger) FlushCaches()

FlushCaches flushes any pending data in caches so that it is fully available during future lookups.

func (*Ledger) GenesisAccounts 

func (l *Ledger) GenesisAccounts() map[basics.Address]basics.AccountData

GenesisAccounts returns initial accounts for this ledger.

func (*Ledger) GenesisHash 

func (l *Ledger) GenesisHash() crypto.Digest

GenesisHash returns the genesis hash for this ledger.

func (*Ledger) GenesisProto 

func (l *Ledger) GenesisProto() config.ConsensusParams

GenesisProto returns the initial protocol for this ledger.

func (*Ledger) GenesisProtoVersion 

func (l *Ledger) GenesisProtoVersion() protocol.ConsensusVersion

GenesisProtoVersion returns the initial protocol version for this ledger.

func (*Ledger) GetCatchpointCatchupState 

func (l *Ledger) GetCatchpointCatchupState(ctx context.Context) (state CatchpointCatchupState, err error)

GetCatchpointCatchupState returns the current state of the catchpoint catchup.

func (*Ledger) GetCatchpointStream 

func (l *Ledger) GetCatchpointStream(round basics.Round) (ReadCloseSizer, error)

GetCatchpointStream returns a ReadCloseSizer file stream from which the catchpoint file for the provided round could be retrieved. If no such stream can be generated, a non-nil error is returned. The io.ReadCloser and the error are mutually exclusive - if error is returned, the file stream is guaranteed to be nil, and vice versa, if the file stream is not nil, the error is guaranteed to be nil.

func (*Ledger) GetCreator 

func (l *Ledger) GetCreator(cidx basics.CreatableIndex, ctype basics.CreatableType) (basics.Address, bool, error)

GetCreator is like GetCreatorForRound, but for the latest round and race-free with respect to ledger.Latest()

func (*Ledger) GetCreatorForRound 

func (l *Ledger) GetCreatorForRound(rnd basics.Round, cidx basics.CreatableIndex, ctype basics.CreatableType) (creator basics.Address, ok bool, err error)

GetCreatorForRound takes a CreatableIndex and a CreatableType and tries to look up a creator address, setting ok to false if the query succeeded but no creator was found.

func (*Ledger) GetKnockOfflineCandidates 

func (l *Ledger) GetKnockOfflineCandidates(rnd basics.Round, proto config.ConsensusParams) (map[basics.Address]basics.OnlineAccountData, error)

GetKnockOfflineCandidates retrieves a list of online accounts who will be checked to a recent proposal or heartbeat. Large accounts are the ones worth checking.

func (*Ledger) GetLastCatchpointLabel 

func (l *Ledger) GetLastCatchpointLabel() string

GetLastCatchpointLabel returns the latest catchpoint label that was written to the database.

func (*Ledger) GetStateDeltaForRound 

func (l *Ledger) GetStateDeltaForRound(rnd basics.Round) (ledgercore.StateDelta, error)

GetStateDeltaForRound retrieves a ledgercore.StateDelta from the accountUpdates cache for the requested rnd

func (*Ledger) GetStateProofVerificationContext 

func (l *Ledger) GetStateProofVerificationContext(stateProofLastAttestedRound basics.Round) (*ledgercore.StateProofVerificationContext, error)

GetStateProofVerificationContext returns the data required to verify the state proof whose last attested round is stateProofLastAttestedRound.

func (*Ledger) GetTracer 

func (l *Ledger) GetTracer() logic.EvalTracer

GetTracer returns the logic.EvalTracer attached to the ledger--can be nil.

func (*Ledger) IsBehindCommittingDeltas 

func (l *Ledger) IsBehindCommittingDeltas() bool

IsBehindCommittingDeltas indicates if the ledger is behind expected number of in-memory deltas. It intended to slow down the catchup service when deltas overgrow some limit.

func (*Ledger) IsWritingCatchpointDataFile 

func (l *Ledger) IsWritingCatchpointDataFile() bool

IsWritingCatchpointDataFile returns true when a catchpoint file is being generated. The function is used by the catchup service to avoid memory pressure until the catchpoint data file writing is complete.

func (*Ledger) Latest 

func (l *Ledger) Latest() basics.Round

Latest returns the latest known block round added to the ledger.

func (*Ledger) LatestCommitted 

func (l *Ledger) LatestCommitted() (basics.Round, basics.Round)

LatestCommitted returns the last block round number written to persistent storage. This block, and all previous blocks, are guaranteed to be available after a crash. In addition, it returns the latest block round number added to the ledger ( which will be flushed to persistent storage later on )

func (*Ledger) LatestTotals 

func (l *Ledger) LatestTotals() (basics.Round, ledgercore.AccountTotals, error)

LatestTotals returns the totals of all accounts for the most recent round, as well as the round number.

func (*Ledger) LatestTrackerCommitted 

func (l *Ledger) LatestTrackerCommitted() basics.Round

LatestTrackerCommitted returns the trackers' dbRound which "is always exactly accountsRound()"

func (*Ledger) LookupAccount 

func (l *Ledger) LookupAccount(round basics.Round, addr basics.Address) (data ledgercore.AccountData, validThrough basics.Round, withoutRewards basics.MicroAlgos, err error)

LookupAccount uses the accounts tracker to return the account state (without resources) for a given address, for a given round. The returned account values reflect the changes of all blocks up to and including the returned round number. The returned AccountData contains the rewards applied up to that round number, and the additional withoutRewards return value contains the value before rewards were applied.

func (*Ledger) LookupAgreement 

func (l *Ledger) LookupAgreement(rnd basics.Round, addr basics.Address) (basics.OnlineAccountData, error)

LookupAgreement returns account data used by agreement.

func (*Ledger) LookupApplication 

func (l *Ledger) LookupApplication(rnd basics.Round, addr basics.Address, aidx basics.AppIndex) (ledgercore.AppResource, error)

LookupApplication loads an application resource that matches the request parameters from the ledger.

func (*Ledger) LookupAsset 

func (l *Ledger) LookupAsset(rnd basics.Round, addr basics.Address, aidx basics.AssetIndex) (ledgercore.AssetResource, error)

LookupAsset loads an asset resource that matches the request parameters from the ledger.

func (*Ledger) LookupAssets 

func (l *Ledger) LookupAssets(addr basics.Address, assetIDGT basics.AssetIndex, limit uint64) ([]ledgercore.AssetResourceWithIDs, basics.Round, error)

LookupAssets loads asset resources that match the request parameters from the ledger.

func (*Ledger) LookupKeysByPrefix 

func (l *Ledger) LookupKeysByPrefix(round basics.Round, keyPrefix string, maxKeyNum uint64) ([]string, error)

LookupKeysByPrefix searches keys with specific prefix, up to `maxKeyNum` if `maxKeyNum` == 0, then it loads all keys with such prefix

func (*Ledger) LookupKv 

func (l *Ledger) LookupKv(rnd basics.Round, key string) ([]byte, error)

LookupKv loads a KV pair from the accounts update

func (*Ledger) LookupLatest 

func (l *Ledger) LookupLatest(addr basics.Address) (basics.AccountData, basics.Round, basics.MicroAlgos, error)

LookupLatest uses the accounts tracker to return the account state (including resources) for a given address, for the latest round. The returned account values reflect the changes of all blocks up to and including the returned round number.

func (*Ledger) LookupWithoutRewards 

func (l *Ledger) LookupWithoutRewards(rnd basics.Round, addr basics.Address) (ledgercore.AccountData, basics.Round, error)

LookupWithoutRewards is like Lookup but does not apply pending rewards up to the requested round rnd.

func (*Ledger) OnlineCirculation 

func (l *Ledger) OnlineCirculation(rnd basics.Round, voteRnd basics.Round) (basics.MicroAlgos, error)

OnlineCirculation returns the online totals of all accounts at the end of round rnd. It implements agreement's calls for Circulation(rnd)

func (*Ledger) RegisterBlockListeners 

func (l *Ledger) RegisterBlockListeners(listeners []ledgercore.BlockListener)

RegisterBlockListeners registers listeners that will be called when a new block is added to the ledger.

func (*Ledger) RegisterVotersCommitListener 

func (l *Ledger) RegisterVotersCommitListener(listener ledgercore.VotersCommitListener)

RegisterVotersCommitListener registers a listener that will be called when a commit is about to cover a round.

func (*Ledger) StartEvaluator 

func (l *Ledger) StartEvaluator(hdr bookkeeping.BlockHeader, paysetHint, maxTxnBytesPerBlock int, tracer logic.EvalTracer) (*eval.BlockEvaluator, error)

StartEvaluator creates a BlockEvaluator, given a ledger and a block header of the block that the caller is planning to evaluate. If the length of the payset being evaluated is known in advance, a paysetHint >= 0 can be passed, avoiding unnecessary payset slice growth. The optional maxTxnBytesPerBlock parameter provides a cap on the size of a single generated block size, when a non-zero value is passed. If a value of zero or less is passed to maxTxnBytesPerBlock, the consensus MaxTxnBytesPerBlock would be used instead. The tracer argument is a logic.EvalTracer which will be attached to the evaluator and have its hooked invoked during the eval process for each block. A nil tracer will default to the tracer attached to the ledger.

func (*Ledger) Totals 

func (l *Ledger) Totals(rnd basics.Round) (ledgercore.AccountTotals, error)

Totals returns the totals of all accounts for the given round.

func (*Ledger) UnregisterVotersCommitListener 

func (l *Ledger) UnregisterVotersCommitListener()

UnregisterVotersCommitListener unregisters the commit listener.

func (*Ledger) Validate 

func (l *Ledger) Validate(ctx context.Context, blk bookkeeping.Block, executionPool execpool.BacklogPool) (*ledgercore.ValidatedBlock, error)

Validate uses the ledger to validate block blk as a candidate next block. It returns an error if blk is not the expected next block, or if blk is not a valid block (e.g., it has duplicate transactions, overspends some account, etc.).

func (*Ledger) VerifiedTransactionCache 

func (l *Ledger) VerifiedTransactionCache() verify.VerifiedTransactionCache

VerifiedTransactionCache returns the verify.VerifiedTransactionCache

func (*Ledger) VotersForStateProof 

func (l *Ledger) VotersForStateProof(rnd basics.Round) (*ledgercore.VotersForRound, error)

VotersForStateProof returns the top online accounts at round rnd. The result might be nil, even with err=nil, if there are no voters for that round because state proofs were not enabled.

func (*Ledger) Wait 

func (l *Ledger) Wait(r basics.Round) chan struct{}

Wait returns a channel that closes once a given round is stored durably in the ledger. When <-l.Wait(r) finishes, ledger is guaranteed to have round r, and will not lose round r after a crash. This makes it easy to use in a select{} statement.

func (*Ledger) WaitForCommit 

func (l *Ledger) WaitForCommit(r basics.Round)

WaitForCommit waits until block r (and block before r) are durably written to disk.

func (*Ledger) WaitMem 

func (l *Ledger) WaitMem(r basics.Round) chan struct{}

WaitMem returns a channel that closes once a given round is available in memory in the ledger, but might not be stored durably on disk yet.

func (*Ledger) WaitWithCancel 

func (l *Ledger) WaitWithCancel(r basics.Round) (chan struct{}, func())

WaitWithCancel returns a channel that closes once a given round is stored durably in the ledger. The returned function can be used to cancel the wait, which cleans up resources if no other Wait call is active for the same round.

type MismatchingDatabaseRoundError 

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

MismatchingDatabaseRoundError is generated when we detect that the database round is different than the accountUpdates in-memory dbRound. This could happen normally when the database and the in-memory dbRound aren't synchronized. However, when we work in non-sync mode, we expect the database to be always synchronized with the in-memory data. When that condition is violated, this error is generated.

func (*MismatchingDatabaseRoundError) Error 

func (e *MismatchingDatabaseRoundError) Error() string

type ReadCloseSizer 

type ReadCloseSizer interface {
	io.ReadCloser
	Size() (int64, error)
}

ReadCloseSizer interface implements the standard io.Reader and io.Closer as well as supporting the Size() function that let the caller know what the size of the stream would be (in bytes).

type RoundOffsetError 

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

RoundOffsetError is an error for when requested round is behind earliest stored db entry

func (*RoundOffsetError) Error 

func (e *RoundOffsetError) Error() string

type StaleDatabaseRoundError 

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

StaleDatabaseRoundError is generated when we detect that the database round is behind the accountUpdates in-memory dbRound. This should never happen, since we update the database first, and only upon a successful update we update the in-memory dbRound.

func (*StaleDatabaseRoundError) Error 

func (e *StaleDatabaseRoundError) Error() string

Source Files

View all Source files

Directories

Path Synopsis
prefetcher
testing
store
blockdb
testing
trackerdb
trackerdb/dualdriver
trackerdb/generickv
trackerdb/pebbledbdriver
trackerdb/sqlitedriver
trackerdb/testdb

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.