Boxes: Add support for Boxes (#341)

.circleci/config.yml

@@ -1,7 +1,7 @@
 version: 2.1
 
 orbs:
-  go: circleci/[email protected].0
+  go: circleci/[email protected].1
 
 workflows:
   circleci_build_and_test:
@@ -10,7 +10,7 @@ workflows:
           name: 'test_go_<< matrix.go_version >>'
           matrix:
             parameters:
-              go_version: ['1.16', '1.17']
+              go_version: ['1.17']
 
 jobs:
   test:

.gitignore

@@ -28,3 +28,6 @@ coverage.html
 # Testing files
 *.feature
 temp
+
+# asdf
+.tool-versions

client/v2/algod/algod.go

@@ -128,6 +128,14 @@ func (c *Client) GetApplicationByID(applicationId uint64) *GetApplicationByID {
 	return &GetApplicationByID{c: c, applicationId: applicationId}
 }
 
+func (c *Client) GetApplicationBoxes(applicationId uint64) *GetApplicationBoxes {
+	return &GetApplicationBoxes{c: c, applicationId: applicationId}
+}
+
+func (c *Client) GetApplicationBoxByName(applicationId uint64, name []byte) *GetApplicationBoxByName {
+	return (&GetApplicationBoxByName{c: c, applicationId: applicationId}).name(name)
+}
+
 func (c *Client) GetAssetByID(assetId uint64) *GetAssetByID {
 	return &GetAssetByID{c: c, assetId: assetId}
 }

client/v2/algod/getApplicationBoxByName.go

@@ -0,0 +1,47 @@
+package algod
+
+import (
+	"context"
+	"encoding/base64"
+	"fmt"
+
+	"github.com/algorand/go-algorand-sdk/client/v2/common"
+	"github.com/algorand/go-algorand-sdk/client/v2/common/models"
+)
+
+// GetApplicationBoxByNameParams contains all of the query parameters for url serialization.
+type GetApplicationBoxByNameParams struct {
+
+	// Name a box name, in the goal app call arg form 'encoding:value'. For ints, use
+	// the form 'int:1234'. For raw bytes, use the form 'b64:A=='. For printable
+	// strings, use the form 'str:hello'. For addresses, use the form 'addr:XYZ...'.
+	Name string `url:"name,omitempty"`
+}
+
+// GetApplicationBoxByName given an application ID and box name, it returns the box
+// name and value (each base64 encoded). Box names must be in the goal app call arg
+// encoding form 'encoding:value'. For ints, use the form 'int:1234'. For raw
+// bytes, use the form 'b64:A=='. For printable strings, use the form 'str:hello'.
+// For addresses, use the form 'addr:XYZ...'.
+type GetApplicationBoxByName struct {
+	c *Client
+
+	applicationId uint64
+
+	p GetApplicationBoxByNameParams
+}
+
+// name a box name, in the goal app call arg form 'encoding:value'. For ints, use
+// the form 'int:1234'. For raw bytes, use the form 'b64:A=='. For printable
+// strings, use the form 'str:hello'. For addresses, use the form 'addr:XYZ...'.
+func (s *GetApplicationBoxByName) name(name []byte) *GetApplicationBoxByName {
+	s.p.Name = "b64:" + base64.StdEncoding.EncodeToString(name)
+
+	return s
+}
+
+// Do performs the HTTP request
+func (s *GetApplicationBoxByName) Do(ctx context.Context, headers ...*common.Header) (response models.Box, err error) {
+	err = s.c.get(ctx, &response, fmt.Sprintf("/v2/applications/%s/box", common.EscapeParams(s.applicationId)...), s.p, headers)
+	return
+}

client/v2/algod/getApplicationBoxes.go

@@ -0,0 +1,42 @@
+package algod
+
+import (
+	"context"
+	"fmt"
+
+	"github.com/algorand/go-algorand-sdk/client/v2/common"
+	"github.com/algorand/go-algorand-sdk/client/v2/common/models"
+)
+
+// GetApplicationBoxesParams contains all of the query parameters for url serialization.
+type GetApplicationBoxesParams struct {
+
+	// Max max number of box names to return. If max is not set, or max == 0, returns
+	// all box-names.
+	Max uint64 `url:"max,omitempty"`
+}
+
+// GetApplicationBoxes given an application ID, return all Box names. No particular
+// ordering is guaranteed. Request fails when client or server-side configured
+// limits prevent returning all Box names.
+type GetApplicationBoxes struct {
+	c *Client
+
+	applicationId uint64
+
+	p GetApplicationBoxesParams
+}
+
+// Max max number of box names to return. If max is not set, or max == 0, returns
+// all box-names.
+func (s *GetApplicationBoxes) Max(Max uint64) *GetApplicationBoxes {
+	s.p.Max = Max
+
+	return s
+}
+
+// Do performs the HTTP request
+func (s *GetApplicationBoxes) Do(ctx context.Context, headers ...*common.Header) (response models.BoxesResponse, err error) {
+	err = s.c.get(ctx, &response, fmt.Sprintf("/v2/applications/%s/boxes", common.EscapeParams(s.applicationId)...), s.p, headers)
+	return
+}

client/v2/common/models/account.go

@@ -97,6 +97,14 @@ type Account struct {
 	// to the count of AssetHolding objects held by this account.
 	TotalAssetsOptedIn uint64 `json:"total-assets-opted-in"`
 
+	// TotalBoxBytes for app-accounts only. The total number of bytes allocated for the
+	// keys and values of boxes which belong to the associated application.
+	TotalBoxBytes uint64 `json:"total-box-bytes"`
+
+	// TotalBoxes for app-accounts only. The total number of boxes which belong to the
+	// associated application.
+	TotalBoxes uint64 `json:"total-boxes"`
+
 	// TotalCreatedApps the count of all apps (AppParams objects) created by this
 	// account.
 	TotalCreatedApps uint64 `json:"total-created-apps"`

client/v2/common/models/box.go

@@ -0,0 +1,10 @@
+package models
+
+// Box box name and its content.
+type Box struct {
+	// Name (name) box name, base64 encoded
+	Name []byte `json:"name"`
+
+	// Value (value) box value, base64 encoded.
+	Value []byte `json:"value"`
+}

client/v2/common/models/box_descriptor.go

@@ -0,0 +1,7 @@
+package models
+
+// BoxDescriptor box descriptor describes an app box without a value.
+type BoxDescriptor struct {
+	// Name base64 encoded box name
+	Name []byte `json:"name"`
+}

client/v2/common/models/boxes_response.go

@@ -0,0 +1,14 @@
+package models
+
+// BoxesResponse box names of an application
+type BoxesResponse struct {
+	// ApplicationId (appidx) application index.
+	ApplicationId uint64 `json:"application-id"`
+
+	// Boxes
+	Boxes []BoxDescriptor `json:"boxes"`
+
+	// NextToken used for pagination, when making another request provide this token
+	// with the next parameter.
+	NextToken string `json:"next-token,omitempty"`
+}

client/v2/indexer/indexer.go

@@ -87,6 +87,14 @@ func (c *Client) LookupApplicationByID(applicationId uint64) *LookupApplicationB
 	return &LookupApplicationByID{c: c, applicationId: applicationId}
 }
 
+func (c *Client) SearchForApplicationBoxes(applicationId uint64) *SearchForApplicationBoxes {
+	return &SearchForApplicationBoxes{c: c, applicationId: applicationId}
+}
+
+func (c *Client) LookupApplicationBoxByIDAndName(applicationId uint64, name []byte) *LookupApplicationBoxByIDAndName {
+	return (&LookupApplicationBoxByIDAndName{c: c, applicationId: applicationId}).name(name)
+}
+
 func (c *Client) LookupApplicationLogsByID(applicationId uint64) *LookupApplicationLogsByID {
 	return &LookupApplicationLogsByID{c: c, applicationId: applicationId}
 }

client/v2/indexer/lookupApplicationBoxByIDandName.go

@@ -0,0 +1,47 @@
+package indexer
+
+import (
+	"context"
+	"encoding/base64"
+	"fmt"
+
+	"github.com/algorand/go-algorand-sdk/client/v2/common"
+	"github.com/algorand/go-algorand-sdk/client/v2/common/models"
+)
+
+// LookupApplicationBoxByIDAndNameParams contains all of the query parameters for url serialization.
+type LookupApplicationBoxByIDAndNameParams struct {
+
+	// Name a box name in goal-arg form 'encoding:value'. For ints, use the form
+	// 'int:1234'. For raw bytes, use the form 'b64:A=='. For printable strings, use
+	// the form 'str:hello'. For addresses, use the form 'addr:XYZ...'.
+	Name string `url:"name,omitempty"`
+}
+
+// LookupApplicationBoxByIDAndName given an application ID and box name, returns
+// base64 encoded box name and value. Box names must be in the goal app call arg
+// form 'encoding:value'. For ints, use the form 'int:1234'. For raw bytes, encode
+// base 64 and use 'b64' prefix as in 'b64:A=='. For printable strings, use the
+// form 'str:hello'. For addresses, use the form 'addr:XYZ...'.
+type LookupApplicationBoxByIDAndName struct {
+	c *Client
+
+	applicationId uint64
+
+	p LookupApplicationBoxByIDAndNameParams
+}
+
+// name a box name in goal-arg form 'encoding:value'. For ints, use the form
+// 'int:1234'. For raw bytes, use the form 'b64:A=='. For printable strings, use
+// the form 'str:hello'. For addresses, use the form 'addr:XYZ...'.
+func (s *LookupApplicationBoxByIDAndName) name(name []byte) *LookupApplicationBoxByIDAndName {
+	s.p.Name = "b64:" + base64.StdEncoding.EncodeToString(name)
+
+	return s
+}
+
+// Do performs the HTTP request
+func (s *LookupApplicationBoxByIDAndName) Do(ctx context.Context, headers ...*common.Header) (response models.Box, err error) {
+	err = s.c.get(ctx, &response, fmt.Sprintf("/v2/applications/%s/box", common.EscapeParams(s.applicationId)...), s.p, headers)
+	return
+}

client/v2/indexer/searchForApplicationBoxes.go

@@ -0,0 +1,53 @@
+package indexer
+
+import (
+	"context"
+	"fmt"
+
+	"github.com/algorand/go-algorand-sdk/client/v2/common"
+	"github.com/algorand/go-algorand-sdk/client/v2/common/models"
+)
+
+// SearchForApplicationBoxesParams contains all of the query parameters for url serialization.
+type SearchForApplicationBoxesParams struct {
+
+	// Limit maximum number of results to return. There could be additional pages even
+	// if the limit is not reached.
+	Limit uint64 `url:"limit,omitempty"`
+
+	// Next the next page of results. Use the next token provided by the previous
+	// results.
+	Next string `url:"next,omitempty"`
+}
+
+// SearchForApplicationBoxes given an application ID, returns the box names of that
+// application sorted lexicographically.
+type SearchForApplicationBoxes struct {
+	c *Client
+
+	applicationId uint64
+
+	p SearchForApplicationBoxesParams
+}
+
+// Limit maximum number of results to return. There could be additional pages even
+// if the limit is not reached.
+func (s *SearchForApplicationBoxes) Limit(Limit uint64) *SearchForApplicationBoxes {
+	s.p.Limit = Limit
+
+	return s
+}
+
+// Next the next page of results. Use the next token provided by the previous
+// results.
+func (s *SearchForApplicationBoxes) Next(Next string) *SearchForApplicationBoxes {
+	s.p.Next = Next
+
+	return s
+}
+
+// Do performs the HTTP request
+func (s *SearchForApplicationBoxes) Do(ctx context.Context, headers ...*common.Header) (response models.BoxesResponse, err error) {
+	err = s.c.get(ctx, &response, fmt.Sprintf("/v2/applications/%s/boxes", common.EscapeParams(s.applicationId)...), s.p, headers)
+	return
+}

future/atomicTransactionComposer.go

@@ -97,6 +97,9 @@ type AddMethodCallParams struct {
 	// Any foreign accounts to be passed that aren't part of the method signature
 	// If accounts are provided here, the accounts specified in the method args will appear after these
 	ForeignAccounts []string
+
+	// References of the boxes to be accessed by this method call.
+	BoxReferences []types.AppBoxReference
 }
 
 // ExecuteResult contains the results of successfully calling the Execute method on an
@@ -167,8 +170,8 @@ type AtomicTransactionComposer struct {
 	// The current status of the composer. The status increases monotonically.
 	status AtomicTransactionComposerStatus
 
-	// The transaction contexts in the group with their respective signers. If status is greater then
-	// BUILDING then this slice cannot change.
+	// The transaction contexts in the group with their respective signers.
+	// If status is greater than BUILDING, then this slice cannot change.
 	txContexts []transactionContext
 }
 
@@ -373,17 +376,19 @@ func (atc *AtomicTransactionComposer) AddMethodCall(params AddMethodCallParams)
 		encodedAbiArgs = append(encodedAbiArgs, encodedArg)
 	}
 
-	tx, err := MakeApplicationCallTx(
+	tx, err := MakeApplicationCallTxWithBoxes(
 		params.AppID,
 		encodedAbiArgs,
 		foreignAccounts,
 		foreignApps,
 		foreignAssets,
+		params.BoxReferences,
 		params.OnComplete,
 		params.ApprovalProgram,
 		params.ClearProgram,
 		params.GlobalSchema,
 		params.LocalSchema,
+		params.ExtraPages,
 		params.SuggestedParams,
 		params.Sender,
 		params.Note,
@@ -394,13 +399,6 @@ func (atc *AtomicTransactionComposer) AddMethodCall(params AddMethodCallParams)
 		return err
 	}
 
-	if params.ExtraPages != 0 {
-		tx, err = MakeApplicationCallTxWithExtraPages(tx, params.ExtraPages)
-		if err != nil {
-			return err
-		}
-	}
-
 	txAndSigner := TransactionWithSigner{
 		Txn:    tx,
 		Signer: params.Signer,