Boxes: Add support for Boxes

.test-env

@@ -1,6 +1,6 @@
 # Configs for testing repo download:
 SDK_TESTING_URL="https://github.com/algorand/algorand-sdk-testing"
-SDK_TESTING_BRANCH="master"
+SDK_TESTING_BRANCH="feature/box-storage"
 SDK_TESTING_HARNESS="test-harness"
 
 VERBOSE_HARNESS=0

src/main/java/com/algorand/algosdk/builder/transaction/ApplicationBaseTransactionBuilder.java

@@ -1,6 +1,7 @@
 package com.algorand.algosdk.builder.transaction;
 
 import com.algorand.algosdk.crypto.Address;
+import com.algorand.algosdk.transaction.AppBoxReference;
 import com.algorand.algosdk.transaction.Transaction;
 import com.algorand.algosdk.util.Encoder;
 
@@ -15,6 +16,7 @@ public abstract class ApplicationBaseTransactionBuilder<T extends ApplicationBas
     private List<Address> accounts;
     private List<Long> foreignApps;
     private List<Long> foreignAssets;
+    private List<AppBoxReference> appBoxReferences;
     private Long applicationId;
 
     /**
@@ -36,6 +38,7 @@ protected void applyTo(Transaction txn) {
         if (accounts != null) txn.accounts = accounts;
         if (foreignApps != null) txn.foreignApps = foreignApps;
         if (foreignAssets != null) txn.foreignAssets = foreignAssets;
+        if (appBoxReferences != null) txn.boxReferences = convertBoxes(appBoxReferences, foreignApps, applicationId);
     }
 
     @Override
@@ -63,6 +66,7 @@ public T args(List<byte[]> args) {
 
     /**
      * ApplicationArgs lists some transaction-specific arguments accessible from application logic.
+     *
      * @param args List of Base64 encoded strings.
      */
     public T argsBase64Encoded(List<String> args) {
@@ -90,4 +94,17 @@ public T foreignAssets(List<Long> foreignAssets) {
         this.foreignAssets = foreignAssets;
         return (T) this;
     }
+
+    private List<Transaction.BoxReference> convertBoxes(List<AppBoxReference> abrs, List<Long> foreignApps, Long curApp) {
+        ArrayList<Transaction.BoxReference> xs = new ArrayList<>();
+        for (AppBoxReference abr : abrs) {
+            xs.add(Transaction.BoxReference.fromAppBoxReference(abr, foreignApps, curApp));
+        }
+        return xs;
+    }
+
+    public T boxReferences(List<AppBoxReference> boxReferences) {
+        this.appBoxReferences = boxReferences;
+        return (T) this;
+    }
 }

src/main/java/com/algorand/algosdk/builder/transaction/ApplicationCallReferencesSetter.java

@@ -3,9 +3,10 @@
 import java.util.List;
 
 import com.algorand.algosdk.crypto.Address;
+import com.algorand.algosdk.transaction.AppBoxReference;
 
 public interface ApplicationCallReferencesSetter<T extends ApplicationCallReferencesSetter<T>> {
-    
+
     /**
      * ApplicationID is the application being interacted with, or 0 if creating a new application.
      */
@@ -27,4 +28,10 @@ public interface ApplicationCallReferencesSetter<T extends ApplicationCallRefere
      * application. The access is read-only.
      */
     public T foreignAssets(List<Long> foreignAssets);
+
+    /**
+     * BoxReferences lists the boxes whose state may be accessed during evaluation of this application call. The apps
+     * the boxes belong to must be present in ForeignApps.
+     */
+    public T boxReferences(List<AppBoxReference> boxReferences);
 }

src/main/java/com/algorand/algosdk/builder/transaction/MethodCallTransactionBuilder.java

@@ -2,12 +2,15 @@
 
 import com.algorand.algosdk.abi.Method;
 import com.algorand.algosdk.crypto.Address;
+import com.algorand.algosdk.crypto.Digest;
 import com.algorand.algosdk.crypto.TEALProgram;
 import com.algorand.algosdk.logic.StateSchema;
+import com.algorand.algosdk.transaction.AppBoxReference;
 import com.algorand.algosdk.transaction.MethodCallParams;
 import com.algorand.algosdk.transaction.Transaction;
 import com.algorand.algosdk.transaction.TxnSigner;
 
+import java.math.BigInteger;
 import java.util.ArrayList;
 import java.util.HashSet;
 import java.util.List;
@@ -22,6 +25,7 @@ public class MethodCallTransactionBuilder<T extends MethodCallTransactionBuilder
     protected List<Address> foreignAccounts = new ArrayList<>();
     protected List<Long> foreignAssets = new ArrayList<>();
     protected List<Long> foreignApps = new ArrayList<>();
+    protected List<AppBoxReference> boxReferences = new ArrayList<>();
 
     protected TEALProgram approvalProgram, clearStateProgram;
     protected StateSchema localStateSchema;
@@ -62,7 +66,7 @@ public T method(Method method) {
 
     /**
      * Specify arguments for the ABI method invocation.
-     * 
+     * <p>
      * This will reset the arguments list to what is passed in by the caller.
      */
     public T methodArguments(List<Object> arguments) {
@@ -72,7 +76,7 @@ public T methodArguments(List<Object> arguments) {
 
     /**
      * Specify arguments for the ABI method invocation.
-     * 
+     * <p>
      * This will add the arguments passed in by the caller to the existing list of arguments.
      */
     public T addMethodArguments(List<Object> arguments) {
@@ -82,7 +86,7 @@ public T addMethodArguments(List<Object> arguments) {
 
     /**
      * Specify arguments for the ABI method invocation.
-     * 
+     * <p>
      * This will add the argument passed in by the caller to the existing list of arguments.
      */
     public T addMethodArgument(Object argument) {
@@ -125,6 +129,16 @@ public T foreignAssets(List<Long> foreignAssets) {
         return (T) this;
     }
 
+    @Override
+    public T boxReferences(List<AppBoxReference> boxReferences) {
+        if (boxReferences != null)
+            // duplicate box references can be meaningful, don't get rid of them
+            this.boxReferences = new ArrayList<>(boxReferences);
+        else
+            this.boxReferences.clear();
+        return (T) this;
+    }
+
     @Override
     public T approvalProgram(TEALProgram approvalProgram) {
         this.approvalProgram = approvalProgram;
@@ -162,10 +176,34 @@ public T extraPages(Long extraPages) {
      * Build a MethodCallParams object.
      */
     public MethodCallParams build() {
-        return new MethodCallParams(
-                appID, method, methodArgs, sender, onCompletion, note, lease, genesisID, genesisHash,
+        return new MethodCallParamsFactory(appID, method, methodArgs, sender, onCompletion, note, lease, genesisID, genesisHash,
                 firstValid, lastValid, fee, flatFee, rekeyTo, signer, foreignAccounts, foreignAssets, foreignApps,
-                approvalProgram, clearStateProgram, globalStateSchema, localStateSchema, extraPages
-        );
+                boxReferences, approvalProgram, clearStateProgram, globalStateSchema, localStateSchema, extraPages);
+    }
+
+    /**
+     * MethodCallParamsFactory exists only as a way to facilitate construction of
+     * `MethodCallParams` instances via a protected constructor.
+     * <p>
+     * No extension or other modification is intended.
+     */
+    private static class MethodCallParamsFactory extends MethodCallParams {
+
+        MethodCallParamsFactory(Long appID, Method method, List<Object> methodArgs, Address sender,
+                                Transaction.OnCompletion onCompletion, byte[] note, byte[] lease, String genesisID, Digest genesisHash,
+                                BigInteger firstValid, BigInteger lastValid, BigInteger fee, BigInteger flatFee,
+                                Address rekeyTo, TxnSigner signer,
+                                List<Address> fAccounts, List<Long> fAssets, List<Long> fApps, List<AppBoxReference> boxes,
+                                TEALProgram approvalProgram, TEALProgram clearProgram,
+                                StateSchema globalStateSchema, StateSchema localStateSchema, Long extraPages) {
+            super(appID, method, methodArgs, sender,
+                    onCompletion, note, lease, genesisID, genesisHash,
+                    firstValid, lastValid, fee, flatFee,
+                    rekeyTo, signer,
+                    fAccounts, fAssets, fApps, boxes,
+                    approvalProgram, clearProgram,
+                    globalStateSchema, localStateSchema, extraPages);
+        }
+
     }
 }

src/main/java/com/algorand/algosdk/transaction/AppBoxReference.java

@@ -0,0 +1,55 @@
+package com.algorand.algosdk.transaction;
+
+import com.algorand.algosdk.util.BoxQueryEncoding;
+
+import java.util.Arrays;
+import java.util.Objects;
+
+public class AppBoxReference {
+    // the app ID of the app this box belongs to. Instead of serializing this value,
+    // it's used to calculate the appIdx for AppBoxReference.
+    private final long appId;
+
+    // the name of the box unique to the app it belongs to
+    private final byte[] name;
+
+    public AppBoxReference(long appId, byte[] name) {
+        this.appId = appId;
+        this.name = Arrays.copyOf(name, name.length);
+    }
+
+    @Override
+    public boolean equals(Object o) {
+        if (this == o) return true;
+        if (o == null || getClass() != o.getClass()) return false;
+        AppBoxReference that = (AppBoxReference) o;
+        return appId == that.appId && Arrays.equals(name, that.name);
+    }
+
+    @Override
+    public int hashCode() {
+        int result = Objects.hash(appId);
+        result = 31 * result + Arrays.hashCode(name);
+        return result;
+    }
+
+    public long getAppId() {
+        return appId;
+    }
+
+    public byte[] getName() {
+        return Arrays.copyOf(name, name.length);
+    }
+
+    @Override
+    public String toString() {
+        return "AppBoxReference{" +
+                "appID=" + appId +
+                ", name=" + Arrays.toString(name) +
+                '}';
+    }
+
+    public String nameQueryEncoded() {
+        return BoxQueryEncoding.encodeBytes(name);
+    }
+}