FOR REVIEW ONLY - go-algorand-sdk v1.20.0

.circleci/config.yml

@@ -10,7 +10,7 @@ workflows:
           name: 'test_go_<< matrix.go_version >>'
           matrix:
             parameters:
-              go_version: ['1.15', '1.16', '1.17']
+              go_version: ['1.16', '1.17']
 
 jobs:
   test:

.test-env

@@ -0,0 +1,14 @@
+# Configs for testing repo download:
+SDK_TESTING_URL="https://github.com/algorand/algorand-sdk-testing"
+SDK_TESTING_BRANCH="master"
+SDK_TESTING_HARNESS="test-harness"
+
+VERBOSE_HARNESS=0
+
+# WARNING: If set to 1, new features will be LOST when downloading the test harness.
+# REGARDLESS: modified features are ALWAYS overwritten.
+REMOVE_LOCAL_FEATURES=0
+
+# WARNING: Be careful when turning on the next variable.
+# In that case you'll need to provide all variables expected by `algorand-sdk-testing`'s `.env`
+OVERWRITE_TESTING_ENVIRONMENT=0

CHANGELOG.md

@@ -1,3 +1,26 @@
+# 1.20.0
+## What's Changed
+### Bugfixes
+* Bug-Fix: passthru verbosity by @tzaffi in https://github.com/algorand/go-algorand-sdk/pull/371
+* BugFix: Src map type assert fix by @barnjamin in https://github.com/algorand/go-algorand-sdk/pull/370
+### New Features
+* StateProof: State proof support by @Eric-Warehime in https://github.com/algorand/go-algorand-sdk/pull/374
+* StateProof: State Proof Verification additions by @almog-t in https://github.com/algorand/go-algorand-sdk/pull/377
+* State Proofs: added compute leaf function for light block header to sdk by @almog-t in https://github.com/algorand/go-algorand-sdk/pull/382
+* State Proofs: renamed light block header hash func by @almog-t in https://github.com/algorand/go-algorand-sdk/pull/383
+### Enhancements
+* Enhancement: Use Sandbox for Testing by @tzaffi in https://github.com/algorand/go-algorand-sdk/pull/360
+* Enhancement: Deprecating use of langspec by @ahangsu in https://github.com/algorand/go-algorand-sdk/pull/366
+* State Proofs: Use generic type for StateProof txn field. by @winder in https://github.com/algorand/go-algorand-sdk/pull/378
+* Improvement: Better SourceMap decoding by @barnjamin in https://github.com/algorand/go-algorand-sdk/pull/380
+* tests: Enable stpf cucumber unit tests by @Eric-Warehime in https://github.com/algorand/go-algorand-sdk/pull/386
+
+## New Contributors
+* @tzaffi made their first contribution in https://github.com/algorand/go-algorand-sdk/pull/360
+* @almog-t made their first contribution in https://github.com/algorand/go-algorand-sdk/pull/377
+
+**Full Changelog**: https://github.com/algorand/go-algorand-sdk/compare/v1.19.0...v1.20.0
+
 # 1.19.0
 ## Enhancements
 * AVM: Consolidate TEAL and AVM versions ([#345](https://github.com/algorand/go-algorand-sdk/pull/345))

Makefile

@@ -1,6 +1,9 @@
 SRCPATH     := $(shell pwd)
 TEST_SOURCES := $(shell cd $(SRCPATH) && go list ./...)
 TEST_SOURCES_NO_CUCUMBER := $(shell cd $(SRCPATH) && go list ./... | grep -v test)
+UNIT_TAGS :=  "$(shell awk '{print $2}' test/unit.tags | paste -s -d, -)"
+INTEGRATIONS_TAGS := "$(shell awk '{print $2}' test/integration.tags | paste -s -d, -)"
+GO_IMAGE := golang:$(subst go,,$(shell go version | cut -d' ' -f 3 | cut -d'.' -f 1,2))-stretch
 
 lint:
 	golint `go list ./... | grep -v /vendor/`
@@ -19,13 +22,27 @@ test:
 
 unit:
 	go test $(TEST_SOURCES_NO_CUCUMBER)
-	cd test && go test -timeout 0s --godog.strict=true --godog.format=pretty --godog.tags="@unit.sourcemap,@unit.offline,@unit.algod,@unit.indexer,@unit.transactions.keyreg,@unit.rekey,@unit.tealsign,@unit.dryrun,@unit.responses,@unit.applications,@unit.transactions,@unit.indexer.rekey,@unit.responses.messagepack,@unit.responses.231,@unit.responses.messagepack.231,@unit.responses.genesis,@unit.feetest,@unit.indexer.logs,@unit.abijson,@unit.abijson.byname,@unit.transactions.payment,@unit.atomic_transaction_composer,@unit.responses.unlimited_assets,@unit.indexer.ledger_refactoring,@unit.algod.ledger_refactoring,@unit.dryrun.trace.application" --test.v .
+	cd test && go test -timeout 0s --godog.strict=true --godog.format=pretty --godog.tags=$(UNIT_TAGS) --test.v .
 
 integration:
 	go test $(TEST_SOURCES_NO_CUCUMBER)
-	cd test && go test -timeout 0s --godog.strict=true --godog.format=pretty --godog.tags="@algod,@assets,@auction,@kmd,@send,@indexer,@rekey_v1,@send.keyregtxn,@dryrun,@compile,@applications.verified,@indexer.applications,@indexer.231,@abi,@c2c,@compile.sourcemap" --test.v .
+	cd test && go test -timeout 0s --godog.strict=true --godog.format=pretty --godog.tags=$(INTEGRATIONS_TAGS) --test.v .
+
+display-all-go-steps:
+	find test -name "*.go" | xargs grep "github.com/cucumber/godog" 2>/dev/null | cut -d: -f1 | sort | uniq | xargs grep -Eo "Step[(].[^\`]+" | awk '{sub(/:Step\(./,":")} 1' | sed -E 's/", [a-zA-Z0-9]+\)//g'
+
+harness:
+	./test-harness.sh
+
+docker-gosdk-build:
+	echo "Building docker image from base $(GO_IMAGE)"
+	docker build -t go-sdk-testing --build-arg GO_IMAGE="$(GO_IMAGE)" -f test/docker/Dockerfile $(shell pwd)
+
+docker-gosdk-run:
+	docker ps -a
+	docker run -it --network host go-sdk-testing:latest
+
+docker-test: harness docker-gosdk-build docker-gosdk-run
 
-docker-test:
-	./test/docker/run_docker.sh
 
 .PHONY: test fmt

README.md

@@ -31,7 +31,7 @@ In `client/v2` the `indexer` package contains a client for the Algorand Indexer
 
 # SDK Development
 
-Run tests with `make docker-test`
+Run tests with `make docker-test`. To set up the sandbox-based test harness without standing up the go-algorand docker image use `make harness`.
 
 # Quick Start
 

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"`
+}