Categorygithub.com/algorand/go-algorandledger
package
4.0.2-stable+incompatible
Repository: https://github.com/algorand/go-algorand.git
Documentation: pkg.go.dev
Overview
Versions
3
Dependencies
49
Dependents
34
Files
12.1k SLOC

# 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.

# Packages

No description provided by the author
No description provided by the author
No description provided by the author
No description provided by the author
No description provided by the author
No description provided by the author
No description provided by the author

# Functions

MaxSize returns a maximum valid message size for this message type.
MaxSize returns a maximum valid message size for this message type.
MaxSize returns a maximum valid message size for this message type.
MaxSize returns a maximum valid message size for this message type.
MaxSize returns a maximum valid message size for this message type.
MakeCatchpointCatchupAccessor creates a CatchpointCatchupAccessor given a ledger.
MakeDebugBalances creates a ledger suitable for dryrun and debugger.
OpenLedger creates a Ledger object, using SQLite database filenames based on dbPathPrefix (in-memory if dbMem is true).

# Constants

BalancesPerCatchpointFileChunk defines the number of accounts that would be stored in each chunk in the catchpoint file.
CatchpointCatchupStateBlocksDownload indicates that we're downloading the blocks prior to the latest one ( total of CatchpointLookback blocks ).
CatchpointCatchupStateInactive is the common state for the catchpoint catchup - not active.
CatchpointCatchupStateLatestBlockDownload indicates that we're download the latest block.
CatchpointCatchupStateLedgerDownload indicates that we're downloading the ledger.
CatchpointCatchupStateSwitch indicates that we're switching to use the downloaded ledger/blocks content.
CatchpointContentFileName is a name of a file with catchpoint header info inside tar archive.
CatchpointFileVersionV5 is the catchpoint file version that was used when the database schema was V0-V5.
CatchpointFileVersionV6 is the catchpoint file version that is matching database schema since V6.
CatchpointFileVersionV7 is the catchpoint file version that is matching database schema V10.
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).
MaxEncodedBaseAccountDataSize is a rough estimate for the worst-case scenario we're going to have of the base account data serialized.
MaxEncodedBaseResourceDataSize is a rough estimate for the worst-case scenario we're going to have of the base resource data serialized.
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.
SPContextPerCatchpointFile defines the maximum number of state proof verification data stored in the catchpoint file.

# Variables

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

# Structs

CatchpointCatchupAccessorProgress is used by the caller of ProcessStagingBalances to obtain progress information.
CatchpointFileHeader is the content we would have in the "content.msgpack" file in the catchpoint tar archive.
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.
CatchpointSnapshotChunkV6 defines the current encoding of "balances.X.msgpack" files in the catchpoint snapshot.
DirsAndPrefix is a struct that holds the genesis directories and the database file prefix, so ledger can construct full paths to database files.
Ledger is a database storing the contents of the ledger.
MismatchingDatabaseRoundError is generated when we detect that the database round is different than the accountUpdates in-memory dbRound.
RoundOffsetError is an error for when requested round is behind earliest stored db entry.
StaleDatabaseRoundError is generated when we detect that the database round is behind the accountUpdates in-memory dbRound.

# Interfaces

CatchpointCatchupAccessor is an interface for the accessor wrapping the database storage for the catchpoint catchup functionality.
CatchupAccessorClientLedger represents ledger interface needed for catchpoint accessor clients.
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 aliases

CatchpointCatchupState is the state of the current catchpoint catchup process.
DebuggerLedger defines the minimal set of method required for creating a debug balances.