Boxes: Add support for Boxes (#345)

Author: michaeldiamant

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);
+    }
+}

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

@@ -22,6 +22,7 @@
  * MethodCallParams is an object that holds all parameters necessary to invoke {@link AtomicTransactionComposer#addMethodCall(MethodCallParams)}
  */
 public class MethodCallParams {
+
     // if the abi type argument number > 15, then the abi types after 14th should be wrapped in a tuple
     private static final int MAX_ABI_ARG_TYPE_LEN = 15;
 
@@ -35,7 +36,8 @@ public class MethodCallParams {
     public final List<Address> foreignAccounts;
     public final List<Long> foreignAssets;
     public final List<Long> foreignApps;
-    
+    public final List<AppBoxReference> boxReferences;
+
     public final TEALProgram approvalProgram, clearProgram;
     public final StateSchema globalStateSchema, localStateSchema;
     public final Long extraPages;
@@ -54,17 +56,13 @@ public class MethodCallParams {
     public final String genesisID;
     public final Digest genesisHash;
 
-    /**
-     * NOTE: it's strongly suggested to use {@link com.algorand.algosdk.builder.transaction.MethodCallTransactionBuilder}
-     * instead of this constructor to create a new MethodCallParams object.
-     */
-    public MethodCallParams(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,
-                            TEALProgram approvalProgram, TEALProgram clearProgram,
-                            StateSchema globalStateSchema, StateSchema localStateSchema, Long extraPages) {
+    protected MethodCallParams(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) {
         if (appID == null || method == null || sender == null || onCompletion == null || signer == null || genesisID == null || genesisHash == null || firstValid == null || lastValid == null || (fee == null && flatFee == null))
             throw new IllegalArgumentException("Method call builder error: some required field not added");
         if (fee != null && flatFee != null)
@@ -113,16 +111,38 @@ public MethodCallParams(Long appID, Method method, List<Object> methodArgs, Addr
         this.foreignAccounts = new ArrayList<>(fAccounts);
         this.foreignAssets = new ArrayList<>(fAssets);
         this.foreignApps = new ArrayList<>(fApps);
+        this.boxReferences = new ArrayList<>(boxes);
         this.approvalProgram = approvalProgram;
         this.clearProgram = clearProgram;
         this.globalStateSchema = globalStateSchema;
         this.localStateSchema = localStateSchema;
         this.extraPages = extraPages;
     }
 
+    /**
+     * Deprecated - Use {@link com.algorand.algosdk.builder.transaction.MethodCallTransactionBuilder}
+     * to create a new MethodCallParams object instead.
+     */
+    @Deprecated
+    public MethodCallParams(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,
+                            TEALProgram approvalProgram, TEALProgram clearProgram,
+                            StateSchema globalStateSchema, StateSchema localStateSchema, Long extraPages) {
+        this(appID, method, methodArgs, sender,
+                onCompletion, note, lease, genesisID, genesisHash,
+                firstValid, lastValid, fee, flatFee,
+                rekeyTo, signer,
+                fAccounts, fAssets, fApps, new ArrayList(),
+                approvalProgram, clearProgram,
+                globalStateSchema, localStateSchema, extraPages);
+    }
+
     /**
      * Create the transactions which will carry out the specified method call.
-     * 
+     * <p>
      * The list of transactions returned by this function will have the same length as method.getTxnCallCount().
      */
     public List<TransactionWithSigner> createTransactions() {
@@ -136,6 +156,7 @@ public List<TransactionWithSigner> createTransactions() {
         List<Address> foreignAccounts = new ArrayList<>(this.foreignAccounts);
         List<Long> foreignAssets = new ArrayList<>(this.foreignAssets);
         List<Long> foreignApps = new ArrayList<>(this.foreignApps);
+        List<AppBoxReference> boxReferences = new ArrayList<>(this.boxReferences);
 
         for (int i = 0; i < this.method.args.size(); i++) {
             Method.Arg argT = this.method.args.get(i);
@@ -199,21 +220,22 @@ public List<TransactionWithSigner> createTransactions() {
         ApplicationCallTransactionBuilder<?> txBuilder = ApplicationCallTransactionBuilder.Builder();
 
         txBuilder
-            .firstValid(this.firstValid)
-            .lastValid(this.lastValid)
-            .genesisHash(this.genesisHash)
-            .genesisID(this.genesisID)
-            .fee(this.fee)
-            .flatFee(this.flatFee)
-            .note(this.note)
-            .lease(this.lease)
-            .rekey(this.rekeyTo)
-            .sender(this.sender)
-            .applicationId(this.appID)
-            .args(encodedABIArgs)
-            .accounts(foreignAccounts)
-            .foreignApps(foreignApps)
-            .foreignAssets(foreignAssets);
+                .firstValid(this.firstValid)
+                .lastValid(this.lastValid)
+                .genesisHash(this.genesisHash)
+                .genesisID(this.genesisID)
+                .fee(this.fee)
+                .flatFee(this.flatFee)
+                .note(this.note)
+                .lease(this.lease)
+                .rekey(this.rekeyTo)
+                .sender(this.sender)
+                .applicationId(this.appID)
+                .args(encodedABIArgs)
+                .accounts(foreignAccounts)
+                .foreignApps(foreignApps)
+                .foreignAssets(foreignAssets)
+                .boxReferences(boxReferences);
 
         Transaction tx = txBuilder.build();
 
@@ -228,7 +250,7 @@ public List<TransactionWithSigner> createTransactions() {
             tx.localStateSchema = this.localStateSchema;
         if (this.extraPages != null)
             tx.extraPages = this.extraPages;
-        
+
         TransactionWithSigner methodCall = new TransactionWithSigner(tx, this.signer);
         transactionArgs.add(methodCall);
 
@@ -245,12 +267,12 @@ private static boolean checkTransactionType(TransactionWithSigner tws, String tx
      * and this function will return an index that can be used to reference `objectToBeAdded` in `objectArray`.
      *
      * @param objectToBeAdded - The value to add to the array. If this value is already present in the array,
-     *   it will not be added again. Instead, the existing index will be returned.
-     * @param objectArray - The existing foreign array. This input may be modified to append `valueToAdd`.
-     * @param zerothObject - If provided, this value indicated two things: the 0 value is special for this
-     *   array, so all indexes into `objectArray` must start at 1; additionally, if `objectToBeAdded` equals
-     *   `zerothValue`, then `objectToBeAdded` will not be added to the array, and instead the 0 indexes will
-     *   be returned.
+     *                        it will not be added again. Instead, the existing index will be returned.
+     * @param objectArray     - The existing foreign array. This input may be modified to append `valueToAdd`.
+     * @param zerothObject    - If provided, this value indicated two things: the 0 value is special for this
+     *                        array, so all indexes into `objectArray` must start at 1; additionally, if `objectToBeAdded` equals
+     *                        `zerothValue`, then `objectToBeAdded` will not be added to the array, and instead the 0 indexes will
+     *                        be returned.
      * @return An index that can be used to reference `valueToAdd` in `array`.
      */
     private static <T> int populateForeignArrayIndex(T objectToBeAdded, List<T> objectArray, T zerothObject) {