stateproof

README

StateProof

Background

A State Proof is a cryptographic proof of state changes that occur in a given set of blocks. State Proofs are created and signed by the network. The same participants that reach consensus on new blocks sign a message attesting to a summary of recent Algorand transactions. These signatures are then compressed into a compact certificate of collective knowledge, also known as a State Proof. After a State Proof is created, a State Proof transaction, which includes the State Proof and the message it proves, is created and sent to the Algorand network for validation. The transaction goes through consensus like any other pending Algorand transaction: it gets validated by participation nodes, included in a block proposal, and written to the blockchain.

The crypto package implements the cryptography behind State Proofs. This package, stateproof, implements the orchestration logic for State Proofs. Specifically, it is responsible for the following:

• Producing signatures for State Proof messages for online accounts.
• Collecting signatures in order to create a State Proof.
• Gathering block information and online account balances from the ledger.
• Generating the State Proof transactions

State Proof Modules

• verify responsible for making a decision on whether or not to accept a State Proof for the round in which it is was proposed. The network aims to accept the most compact State Proof it can produce while also producing a State Proof every StateProofInterval rounds. For this reason, the network might not accept a valid State Proof when there is a chance a better (more compact) State Proof could be produced.

• Signer A go-routine that is triggered on every new block.

  • Generates the State Proof message when needed.
  • Signs the message using every online account's private State Proof key.
  • Persists signatures into the State Proof database.

• Builder A go-routine that is triggered on every new block.

  • Broadcasts participants' signatures over gossip. In order to prevent network congestion, every address has a designated round slot in which it can send its signature.
  • Creates a State Proof transaction and passes it to the transaction pool once enough SignedWeight is collected. It does this by keeping track of stateproof.Prover for every target State Proof round.
  • Responsible for removing stateproof.Prover data structure, signatures, and ephemeral keys once the relevant State Proof is committed.

  In addition, the Builder module implements the signature verification handling procedure. A relay invokes this procedure on every signature it receives to make sure that it collects only valid signatures for the State Proof.

State Proof Chain Liveness

The Algorand ledger only stores a limited number of historical blocks and online account balances (needed for the creation of State Proofs). If the State Proof chain were to lag behind regular consensus, this could theoretically make it impossible to create new State Proofs. For this reason, the Builder maintains its own database and backs-up necessary data from the ledger so that it can create State Proofs even if the ledger is far ahead.

On catchup scenarios, The Builder gets notified (OnPrepareVoterCommit) before the ledger removes data and stores it into the State Proof database.

Documentation

Index

• func FetchLightHeaders(l BlockHeaderFetcher, stateProofInterval uint64, latestRound basics.Round) ([]bookkeeping.LightBlockHeader, error)
• func GenerateProofOfLightBlockHeaders(stateProofInterval uint64, blkHdrArr lightBlockHeaders, blockIndex uint64) (*merklearray.SingleLeafProof, error)
• func GenerateStateProofMessage(l BlockHeaderFetcher, round basics.Round) (stateproofmsg.Message, error)
• func GetOldestExpectedStateProof(latestHeader *bookkeeping.BlockHeader) basics.Round
• func SigFromAddrMaxSize() (s int)
• func SpProverMaxSize() (s int)
• type Accounts
• type Address
• type BlockHeaderFetcher
• type Ledger
• type Network
• type SortAddress
• type TransactionSender
• type Worker
  • func NewWorker(genesisDir string, log logging.Logger, accts Accounts, ledger Ledger, ...) *Worker
  • func (spw *Worker) OnPrepareVoterCommit(oldBase basics.Round, newBase basics.Round, ...)
  • func (spw *Worker) Start()
  • func (spw *Worker) Stop()

Functions

func FetchLightHeaders

func FetchLightHeaders(l BlockHeaderFetcher, stateProofInterval uint64, latestRound basics.Round) ([]bookkeeping.LightBlockHeader, error)

FetchLightHeaders returns the headers of the blocks in the interval

func GenerateProofOfLightBlockHeaders

func GenerateProofOfLightBlockHeaders(stateProofInterval uint64, blkHdrArr lightBlockHeaders, blockIndex uint64) (*merklearray.SingleLeafProof, error)

GenerateProofOfLightBlockHeaders sets up a tree over the blkHdrArr and returns merkle proof over one of the blocks.

func GenerateStateProofMessage

func GenerateStateProofMessage(l BlockHeaderFetcher, round basics.Round) (stateproofmsg.Message, error)

GenerateStateProofMessage returns a stateproof message that contains all the necessary data for proving on Algorand's state. In addition, it also includes the trusted data for the next stateproof verification

func GetOldestExpectedStateProof

func GetOldestExpectedStateProof(latestHeader *bookkeeping.BlockHeader) basics.Round

GetOldestExpectedStateProof returns the lowest round for which the node should create a state proof.

func SigFromAddrMaxSize

func SigFromAddrMaxSize() (s int)

MaxSize returns a maximum valid message size for this message type

func SpProverMaxSize

func SpProverMaxSize() (s int)

MaxSize returns a maximum valid message size for this message type

Types

type Accounts

type Accounts interface {
	StateProofKeys(basics.Round) []account.StateProofSecretsForRound
	DeleteStateProofKey(id account.ParticipationID, round basics.Round) error
}

Accounts captures the aspects of the AccountManager that are used by this package.

type Address

type Address = basics.Address

Address is required for the msgpack sort binding, since it looks for Address and not basics.Address

type BlockHeaderFetcher

type BlockHeaderFetcher interface {
	BlockHdr(round basics.Round) (bookkeeping.BlockHeader, error)
}

BlockHeaderFetcher captures the aspects of the Ledger that is used to fetch block headers

type Ledger

type Ledger interface {
	Latest() basics.Round
	Wait(basics.Round) chan struct{}
	GenesisHash() crypto.Digest
	BlockHdr(basics.Round) (bookkeeping.BlockHeader, error)
	VotersForStateProof(basics.Round) (*ledgercore.VotersForRound, error)
	RegisterVotersCommitListener(listener ledgercore.VotersCommitListener)
	UnregisterVotersCommitListener()
}

Ledger captures the aspects of the ledger that are used by this package.

type Network

type Network interface {
	Broadcast(ctx context.Context, tag protocol.Tag, data []byte, wait bool, except network.Peer) error
	RegisterHandlers([]network.TaggedMessageHandler)
}

Network captures the aspects of the gossip network protocol that are used by this package.

type SortAddress

type SortAddress = basics.SortAddress

SortAddress implements sorting by Address keys for canonical encoding of maps in msgpack format.

type TransactionSender

type TransactionSender interface {
	BroadcastInternalSignedTxGroup([]transactions.SignedTxn) error
}

TransactionSender is an interface that captures the node's ability to broadcast a new transaction.

type Worker

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

Worker builds state proofs, by broadcasting signatures using this node's participation keys, by collecting signatures sent by others, and by sending out the resulting state proof in a transaction.

func NewWorker

func NewWorker(genesisDir string, log logging.Logger, accts Accounts, ledger Ledger, net Network, txnSender TransactionSender) *Worker

NewWorker constructs a new Worker, as used by the node.

func (*Worker) OnPrepareVoterCommit

func (spw *Worker) OnPrepareVoterCommit(oldBase basics.Round, newBase basics.Round, votersFetcher ledgercore.LedgerForSPBuilder)

OnPrepareVoterCommit is a function called by the voters tracker when it's preparing to commit rnd. It gives the builder the chance to persist the data it needs.

func (*Worker) Start

func (spw *Worker) Start()

Start starts the goroutines for the worker.

func (*Worker) Stop

func (spw *Worker) Stop()

Stop stops any goroutines associated with this worker. It is the caller responsibility to remove the register network handlers