StateProof: State proof support

client/v2/algod/algod.go

@@ -80,8 +80,8 @@ func (c *Client) Block(round uint64) *Block {
 	return &Block{c: c, round: round}
 }
 
-func (c *Client) GetProof(round uint64, txid string) *GetProof {
-	return &GetProof{c: c, round: round, txid: txid}
+func (c *Client) GetTransactionProof(round uint64, txid string) *GetTransactionProof {
+	return &GetTransactionProof{c: c, round: round, txid: txid}
 }
 
 func (c *Client) Supply() *Supply {
@@ -112,6 +112,14 @@ func (c *Client) PendingTransactionInformation(txid string) *PendingTransactionI
 	return &PendingTransactionInformation{c: c, txid: txid}
 }
 
+func (c *Client) GetStateProof(round uint64) *GetStateProof {
+	return &GetStateProof{c: c, round: round}
+}
+
+func (c *Client) GetLightBlockHeaderProof(round uint64) *GetLightBlockHeaderProof {
+	return &GetLightBlockHeaderProof{c: c, round: round}
+}
+
 func (c *Client) GetApplicationByID(applicationId uint64) *GetApplicationByID {
 	return &GetApplicationByID{c: c, applicationId: applicationId}
 }

client/v2/algod/getLightBlockHeaderProof.go

@@ -0,0 +1,23 @@
+package algod
+
+import (
+	"context"
+	"fmt"
+
+	"github.com/algorand/go-algorand-sdk/client/v2/common"
+	"github.com/algorand/go-algorand-sdk/client/v2/common/models"
+)
+
+// GetLightBlockHeaderProof gets a proof for a given light block header inside a
+// state proof commitment
+type GetLightBlockHeaderProof struct {
+	c *Client
+
+	round uint64
+}
+
+// Do performs the HTTP request
+func (s *GetLightBlockHeaderProof) Do(ctx context.Context, headers ...*common.Header) (response models.LightBlockHeaderProof, err error) {
+	err = s.c.get(ctx, &response, fmt.Sprintf("/v2/blocks/%s/lightheader/proof", common.EscapeParams(s.round)...), nil, headers)
+	return
+}

client/v2/algod/getStateProof.go

@@ -0,0 +1,22 @@
+package algod
+
+import (
+	"context"
+	"fmt"
+
+	"github.com/algorand/go-algorand-sdk/client/v2/common"
+	"github.com/algorand/go-algorand-sdk/client/v2/common/models"
+)
+
+// GetStateProof get a state proof that covers a given round
+type GetStateProof struct {
+	c *Client
+
+	round uint64
+}
+
+// Do performs the HTTP request
+func (s *GetStateProof) Do(ctx context.Context, headers ...*common.Header) (response models.StateProof, err error) {
+	err = s.c.get(ctx, &response, fmt.Sprintf("/v2/stateproofs/%s", common.EscapeParams(s.round)...), nil, headers)
+	return
+}

client/v2/algod/getProof.go → client/v2/algod/getTransactionProof.go

@@ -8,8 +8,8 @@ import (
 	"github.com/algorand/go-algorand-sdk/client/v2/common/models"
 )
 
-// GetProofParams contains all of the query parameters for url serialization.
-type GetProofParams struct {
+// GetTransactionProofParams contains all of the query parameters for url serialization.
+type GetTransactionProofParams struct {
 
 	// Format configures whether the response object is JSON or MessagePack encoded.
 	Format string `url:"format,omitempty"`
@@ -20,26 +20,26 @@ type GetProofParams struct {
 	Hashtype string `url:"hashtype,omitempty"`
 }
 
-// GetProof get a Merkle proof for a transaction in a block.
-type GetProof struct {
+// GetTransactionProof get a proof for a transaction in a block.
+type GetTransactionProof struct {
 	c *Client
 
 	round uint64
 	txid  string
 
-	p GetProofParams
+	p GetTransactionProofParams
 }
 
 // Hashtype the type of hash function used to create the proof, must be one of:
 // * sha512_256
 // * sha256
-func (s *GetProof) Hashtype(Hashtype string) *GetProof {
+func (s *GetTransactionProof) Hashtype(Hashtype string) *GetTransactionProof {
 	s.p.Hashtype = Hashtype
 	return s
 }
 
 // Do performs the HTTP request
-func (s *GetProof) Do(ctx context.Context, headers ...*common.Header) (response models.ProofResponse, err error) {
+func (s *GetTransactionProof) Do(ctx context.Context, headers ...*common.Header) (response models.TransactionProofResponse, err error) {
 	err = s.c.get(ctx, &response, fmt.Sprintf("/v2/blocks/%s/transactions/%s/proof", common.EscapeParams(s.round, s.txid)...), s.p, headers)
 	return
 }

client/v2/common/models/block.go

@@ -22,6 +22,9 @@ type Block struct {
 	// Seed (seed) Sortition seed.
 	Seed []byte `json:"seed"`
 
+	// StateProofTracking tracks the status of state proofs.
+	StateProofTracking []StateProofTracking `json:"state-proof-tracking,omitempty"`
+
 	// Timestamp (ts) Block creation timestamp in seconds since eposh
 	Timestamp uint64 `json:"timestamp"`
 
@@ -37,6 +40,12 @@ type Block struct {
 	// the same TxnRoot.
 	TransactionsRoot []byte `json:"transactions-root"`
 
+	// TransactionsRootSha256 (txn256) TransactionsRootSHA256 is an auxiliary
+	// TransactionRoot, built using a vector commitment instead of a merkle tree, and
+	// SHA256 hash function instead of the default SHA512_256. This commitment can be
+	// used on environments where only the SHA256 function exists.
+	TransactionsRootSha256 []byte `json:"transactions-root-sha256"`
+
 	// TxnCounter (tc) TxnCounter counts the number of transactions committed in the
 	// ledger, from the time at which support for this feature was introduced.
 	// Specifically, TxnCounter is the number of the next transaction that will be

client/v2/common/models/hash_factory.go

@@ -0,0 +1,7 @@
+package models
+
+// HashFactory defines a model for HashFactory.
+type HashFactory struct {
+	// HashType (t)
+	HashType uint64 `json:"hash-type,omitempty"`
+}

client/v2/common/models/indexer_state_proof_message.go

@@ -0,0 +1,19 @@
+package models
+
+// IndexerStateProofMessage defines a model for IndexerStateProofMessage.
+type IndexerStateProofMessage struct {
+	// BlockHeadersCommitment (b)
+	BlockHeadersCommitment []byte `json:"block-headers-commitment,omitempty"`
+
+	// FirstAttestedRound (f)
+	FirstAttestedRound uint64 `json:"first-attested-round,omitempty"`
+
+	// LatestAttestedRound (l)
+	LatestAttestedRound uint64 `json:"latest-attested-round,omitempty"`
+
+	// LnProvenWeight (P)
+	LnProvenWeight uint64 `json:"ln-proven-weight,omitempty"`
+
+	// VotersCommitment (v)
+	VotersCommitment []byte `json:"voters-commitment,omitempty"`
+}

client/v2/common/models/light_block_header_proof.go

@@ -0,0 +1,14 @@
+package models
+
+// LightBlockHeaderProof proof of membership and position of a light block header.
+type LightBlockHeaderProof struct {
+	// Index the index of the light block header in the vector commitment tree
+	Index uint64 `json:"index"`
+
+	// Proof the encoded proof.
+	Proof []byte `json:"proof"`
+
+	// Treedepth represents the depth of the tree that is being proven, i.e. the number
+	// of edges from a leaf to the root.
+	Treedepth uint64 `json:"treedepth"`
+}

client/v2/common/models/merkle_array_proof.go

@@ -0,0 +1,13 @@
+package models
+
+// MerkleArrayProof defines a model for MerkleArrayProof.
+type MerkleArrayProof struct {
+	// HashFactory
+	HashFactory HashFactory `json:"hash-factory,omitempty"`
+
+	// Path (pth)
+	Path [][]byte `json:"path,omitempty"`
+
+	// TreeDepth (td)
+	TreeDepth uint64 `json:"tree-depth,omitempty"`
+}

client/v2/common/models/state_proof.go

@@ -0,0 +1,10 @@
+package models
+
+// StateProof represents a state proof and its corresponding message
+type StateProof struct {
+	// Message represents the message that the state proofs are attesting to.
+	Message StateProofMessage `json:"Message"`
+
+	// Stateproof the encoded StateProof for the message.
+	Stateproof []byte `json:"StateProof"`
+}

client/v2/common/models/state_proof_fields.go

@@ -0,0 +1,28 @@
+package models
+
+// StateProofFields (sp) represents a state proof.
+// Definition:
+// crypto/stateproof/structs.go : StateProof
+type StateProofFields struct {
+	// PartProofs (P)
+	PartProofs MerkleArrayProof `json:"part-proofs,omitempty"`
+
+	// PositionsToReveal (pr) Sequence of reveal positions.
+	PositionsToReveal []uint64 `json:"positions-to-reveal,omitempty"`
+
+	// Reveals (r) Note that this is actually stored as a map[uint64] - Reveal in the
+	// actual msgp
+	Reveals []StateProofReveal `json:"reveals,omitempty"`
+
+	// SaltVersion (v) Salt version of the merkle signature.
+	SaltVersion uint64 `json:"salt-version,omitempty"`
+
+	// SigCommit (c)
+	SigCommit []byte `json:"sig-commit,omitempty"`
+
+	// SigProofs (S)
+	SigProofs MerkleArrayProof `json:"sig-proofs,omitempty"`
+
+	// SignedWeight (w)
+	SignedWeight uint64 `json:"signed-weight,omitempty"`
+}

client/v2/common/models/state_proof_message.go

@@ -0,0 +1,23 @@
+package models
+
+// StateProofMessage represents the message that the state proofs are attesting to.
+type StateProofMessage struct {
+	// Blockheaderscommitment the vector commitment root on all light block headers
+	// within a state proof interval.
+	Blockheaderscommitment []byte `json:"BlockHeadersCommitment"`
+
+	// Firstattestedround the first round the message attests to.
+	Firstattestedround uint64 `json:"FirstAttestedRound"`
+
+	// Lastattestedround the last round the message attests to.
+	Lastattestedround uint64 `json:"LastAttestedRound"`
+
+	// Lnprovenweight an integer value representing the natural log of the proven
+	// weight with 16 bits of precision. This value would be used to verify the next
+	// state proof.
+	Lnprovenweight uint64 `json:"LnProvenWeight"`
+
+	// Voterscommitment the vector commitment root of the top N accounts to sign the
+	// next StateProof.
+	Voterscommitment []byte `json:"VotersCommitment"`
+}

client/v2/common/models/state_proof_participant.go

@@ -0,0 +1,10 @@
+package models
+
+// StateProofParticipant defines a model for StateProofParticipant.
+type StateProofParticipant struct {
+	// Verifier (p)
+	Verifier StateProofVerifier `json:"verifier,omitempty"`
+
+	// Weight (w)
+	Weight uint64 `json:"weight,omitempty"`
+}

client/v2/common/models/state_proof_reveal.go

@@ -0,0 +1,14 @@
+package models
+
+// StateProofReveal defines a model for StateProofReveal.
+type StateProofReveal struct {
+	// Participant (p)
+	Participant StateProofParticipant `json:"participant,omitempty"`
+
+	// Position the position in the signature and participants arrays corresponding to
+	// this entry.
+	Position uint64 `json:"position,omitempty"`
+
+	// SigSlot (s)
+	SigSlot StateProofSigSlot `json:"sig-slot,omitempty"`
+}

client/v2/common/models/state_proof_sig_slot.go

@@ -0,0 +1,10 @@
+package models
+
+// StateProofSigSlot defines a model for StateProofSigSlot.
+type StateProofSigSlot struct {
+	// LowerSigWeight (l) The total weight of signatures in the lower-numbered slots.
+	LowerSigWeight uint64 `json:"lower-sig-weight,omitempty"`
+
+	// Signature
+	Signature StateProofSignature `json:"signature,omitempty"`
+}

client/v2/common/models/state_proof_signature.go

@@ -0,0 +1,16 @@
+package models
+
+// StateProofSignature defines a model for StateProofSignature.
+type StateProofSignature struct {
+	// FalconSignature
+	FalconSignature []byte `json:"falcon-signature,omitempty"`
+
+	// MerkleArrayIndex
+	MerkleArrayIndex uint64 `json:"merkle-array-index,omitempty"`
+
+	// Proof
+	Proof MerkleArrayProof `json:"proof,omitempty"`
+
+	// VerifyingKey (vkey)
+	VerifyingKey []byte `json:"verifying-key,omitempty"`
+}

client/v2/common/models/state_proof_tracking.go

@@ -0,0 +1,18 @@
+package models
+
+// StateProofTracking defines a model for StateProofTracking.
+type StateProofTracking struct {
+	// NextRound (n) Next round for which we will accept a state proof transaction.
+	NextRound uint64 `json:"next-round,omitempty"`
+
+	// OnlineTotalWeight (t) The total number of microalgos held by the online accounts
+	// during the StateProof round.
+	OnlineTotalWeight uint64 `json:"online-total-weight,omitempty"`
+
+	// Type state Proof Type. Note the raw object uses map with this as key.
+	Type uint64 `json:"type,omitempty"`
+
+	// VotersCommitment (v) Root of a vector commitment containing online accounts that
+	// will help sign the proof.
+	VotersCommitment []byte `json:"voters-commitment,omitempty"`
+}

client/v2/common/models/state_proof_verifier.go

@@ -0,0 +1,10 @@
+package models
+
+// StateProofVerifier defines a model for StateProofVerifier.
+type StateProofVerifier struct {
+	// Commitment (cmt) Represents the root of the vector commitment tree.
+	Commitment []byte `json:"commitment,omitempty"`
+
+	// KeyLifetime (lf) Key lifetime.
+	KeyLifetime uint64 `json:"key-lifetime,omitempty"`
+}

client/v2/common/models/transaction.go

@@ -133,6 +133,11 @@ type Transaction struct {
 	// signatures should be provided.
 	Signature TransactionSignature `json:"signature,omitempty"`
 
+	// StateProofTransaction fields for a state proof transaction.
+	// Definition:
+	// data/transactions/stateproof.go : StateProofTxnFields
+	StateProofTransaction TransactionStateProof `json:"state-proof-transaction,omitempty"`
+
 	// Type (type) Indicates what type of transaction this is. Different types have
 	// different fields.
 	// Valid types, and where their fields are stored:
@@ -142,5 +147,6 @@ type Transaction struct {
 	// * (axfer) asset-transfer-transaction
 	// * (afrz) asset-freeze-transaction
 	// * (appl) application-transaction
+	// * (stpf) state-proof-transaction
 	Type string `json:"tx-type,omitempty"`
 }

client/v2/common/models/proof_response.go → client/v2/common/models/transaction_proof_response.go

@@ -1,7 +1,7 @@
 package models
 
-// ProofResponse proof of transaction in a block.
-type ProofResponse struct {
+// TransactionProofResponse proof of transaction in a block.
+type TransactionProofResponse struct {
 	// Hashtype the type of hash function used to create the proof, must be one of:
 	// * sha512_256
 	// * sha256
@@ -10,7 +10,7 @@ type ProofResponse struct {
 	// Idx index of the transaction in the block's payset.
 	Idx uint64 `json:"idx"`
 
-	// Proof merkle proof of transaction membership.
+	// Proof proof of transaction membership.
 	Proof []byte `json:"proof"`
 
 	// Stibhash hash of SignedTxnInBlock for verifying proof.