Refactor API for Consistency and Usability

appkit/src/test/scala/org/ergoplatform/appkit/AnonymousAccessSpec.scala

@@ -116,7 +116,7 @@ object DhtUtils {
        |  proveDHTuple(groupGenerator, g_y, g_x, g_xy)    // for alice
        |}""".stripMargin);
 
-    val dhtBoxCreationTx = BoxOperations.createForProver(sender, ctx).withAmountToSpend(amountToSend).putToContractTx(contract)
+    val dhtBoxCreationTx = BoxOperations.createForProver(sender, ctx).value(amountToSend).putToContractTx(contract)
     dhtBoxCreationTx
   }
 

appkit/src/test/scala/org/ergoplatform/appkit/AppkitProvingInterpreterSpec.scala

@@ -34,7 +34,7 @@ class AppkitProvingInterpreterSpec extends AnyPropSpec
         is
       }
     }
-    ops.withAmountToSpend(oneErg * 2)
+    ops.value(oneErg * 2)
   }
 
   /** This method creates an UnsignedTransaction instance directly bypassing builders and
@@ -92,7 +92,7 @@ class AppkitProvingInterpreterSpec extends AnyPropSpec
         tokens.add(ergoToken1)
         tokens.add(ergoToken2)
         val unsigned = ops
-          .withTokensToSpend(tokens)
+          .tokens(tokens)
           .putToContractTxUnsigned(address.toErgoContract)
         val reduced = prover.reduce(unsigned, 0)
         reduced.getInputBoxesIds.size() shouldBe 2

appkit/src/test/scala/org/ergoplatform/appkit/BabelFeeSpec.scala

@@ -29,8 +29,8 @@ class BabelFeeSpec extends AnyPropSpec with Matchers with ScalaCheckDrivenProper
 
       val txCreate = BabelFeeOperations.createNewBabelContractTx(
         BoxOperations.createForSender(creator, ctx)
-          .withAmountToSpend(amountToSend)
-          .withInputBoxesLoader(new MockedBoxesLoader(Arrays.asList(input1))),
+          .value(amountToSend)
+          .inputBoxesLoader(new MockedBoxesLoader(Arrays.asList(input1))),
         ErgoId.create(mockTokenId),
         Parameters.OneErg
       )
@@ -42,7 +42,7 @@ class BabelFeeSpec extends AnyPropSpec with Matchers with ScalaCheckDrivenProper
       // now we cancel the babel box
       val txCancel = BabelFeeOperations.cancelBabelFeeContract(
         BoxOperations.createForSender(creator, ctx)
-          .withInputBoxesLoader(new MockedBoxesLoader(Arrays.asList(input1))),
+          .inputBoxesLoader(new MockedBoxesLoader(Arrays.asList(input1))),
         babelFeeErgoBox)
 
       ctx.newProverBuilder()

appkit/src/test/scala/org/ergoplatform/appkit/TxBuilderSpec.scala

@@ -273,7 +273,7 @@ class TxBuilderSpec extends AnyPropSpec with Matchers
 
       val recipient = senderProver.getEip3Addresses.get(1)
       val amountToSend = 1000000
-      val signed = BoxOperations.createForProver(senderProver, ctx).withAmountToSpend(amountToSend)
+      val signed = BoxOperations.createForProver(senderProver, ctx).value(amountToSend)
         .send(recipient)
       assert(signed != null)
     }
@@ -290,8 +290,8 @@ class TxBuilderSpec extends AnyPropSpec with Matchers
       val amountToSend = 1000000
 
       val unsigned = BoxOperations.createForSenders(senders, ctx)
-        .withAmountToSpend(amountToSend)
-        .withMessage("Test message")
+        .value(amountToSend)
+        .message("Test message")
         .putToContractTxUnsigned(pkContract)
       unsigned.getOutputs.get(0).getRegisters.size() shouldBe 6
       unsigned.getOutputs.get(0).getAttachment.getType shouldBe BoxAttachment.Type.PLAIN_TEXT
@@ -358,8 +358,8 @@ class TxBuilderSpec extends AnyPropSpec with Matchers
 
         val amountToSend = 1000000
         val unsigned = BoxOperations.createForSenders(senders, ctx)
-          .withAmountToSpend(amountToSend)
-          .withInputBoxesLoader(new ExplorerAndPoolUnspentBoxesLoader())
+          .value(amountToSend)
+          .inputBoxesLoader(new ExplorerAndPoolUnspentBoxesLoader())
           .putToContractTxUnsigned(recipientContract)
 
         val prover = ctx.newProverBuilder.build // prover without secrets
@@ -395,24 +395,24 @@ class TxBuilderSpec extends AnyPropSpec with Matchers
         .build().convertToInputWith(mockTxId, 1)
 
       val operations = BoxOperations.createForSenders(senders, ctx)
-        .withAmountToSpend(amountToSend)
-        .withTokensToSpend(Arrays.asList(new ErgoToken(mockTxId, 1)))
-        .withInputBoxesLoader(new MockedBoxesLoader(Arrays.asList(input1, input2)))
+        .value(amountToSend)
+        .tokens(Arrays.asList(new ErgoToken(mockTxId, 1)))
+        .inputBoxesLoader(new MockedBoxesLoader(Arrays.asList(input1, input2)))
       val inputsSelected = operations.loadTop()
 
       // both boxes should be selected
       inputsSelected.size() shouldBe 2
 
       // if we restrict to a single box, we face InputBoxLimitExceededException
       assertExceptionThrown(
-        operations.withMaxInputBoxesToSelect(1).loadTop(),
+        operations.maxInputBoxes(1).loadTop(),
         exceptionLike[InputBoxLimitExceededException]("could not cover 1000000 nanoERG")
       )
 
       // if there is only a single input box, we face NotEnoughCoinsForChangeException
       val operations2 = BoxOperations.createForSenders(senders, ctx)
-        .withAmountToSpend(amountToSend)
-        .withInputBoxesLoader(new MockedBoxesLoader(util.Arrays.asList(input1)))
+        .value(amountToSend)
+        .inputBoxesLoader(new MockedBoxesLoader(util.Arrays.asList(input1)))
 
       assertExceptionThrown(
         operations2.loadTop(),
@@ -499,8 +499,8 @@ class TxBuilderSpec extends AnyPropSpec with Matchers
         .build().convertToInputWith(mockTxId, 1)
 
       val operations = BoxOperations.createForSenders(senders, ctx)
-        .withAmountToSpend(amountToSend)
-        .withInputBoxesLoader(new MockedBoxesLoader(Arrays.asList(input1, input2)))
+        .value(amountToSend)
+        .inputBoxesLoader(new MockedBoxesLoader(Arrays.asList(input1, input2)))
       val unsigned = operations.putToContractTxUnsigned(pkContract)
 
       // all outputs should have 100 tokens at max, and it should contain all input tokens
@@ -545,8 +545,8 @@ class TxBuilderSpec extends AnyPropSpec with Matchers
         .build().convertToInputWith(mockTxId, 0)
 
       val unsigned = BoxOperations.createForSenders(senders, ctx)
-        .withAmountToSpend(amountToSend)
-        .withInputBoxesLoader(new MockedBoxesLoader(Arrays.asList(input1)))
+        .value(amountToSend)
+        .inputBoxesLoader(new MockedBoxesLoader(Arrays.asList(input1)))
         .putToContractTxUnsigned(pkContract)
 
       // check if this succeeds without token burning, but with tokens in change box
@@ -563,9 +563,9 @@ class TxBuilderSpec extends AnyPropSpec with Matchers
 
       // check if this suceeds finding all tokens and not raising any exception
       val spendAllTokens = BoxOperations.createForSenders(senders, ctx)
-        .withAmountToSpend(amountToSend)
-        .withTokensToSpend(Arrays.asList(new ErgoToken(mockTxId, 2)))
-        .withInputBoxesLoader(new MockedBoxesLoader(Arrays.asList(input1)))
+        .value(amountToSend)
+        .tokens(Arrays.asList(new ErgoToken(mockTxId, 2)))
+        .inputBoxesLoader(new MockedBoxesLoader(Arrays.asList(input1)))
         .putToContractTxUnsigned(pkContract)
 
       val reduced2 = prover.reduce(spendAllTokens, 0)
@@ -618,7 +618,7 @@ class TxBuilderSpec extends AnyPropSpec with Matchers
   property("Mint a token and rebuild it from BoxCandidate") {
     val ergoClient = createMockedErgoClient(data)
     ergoClient.execute { ctx: BlockchainContext =>
-      val unsigned = BoxOperations.createForSender(address, ctx).withAmountToSpend(15000000)
+      val unsigned = BoxOperations.createForSender(address, ctx).value(15000000)
         .mintTokenToContractTxUnsigned(new ErgoTreeContract(address.getErgoAddress.script, address.getNetworkType), { tokenId: String =>
           new Eip4Token(tokenId, 1, "Test name", "Test desc", 0)
         })

common/src/main/java/org/ergoplatform/appkit/Address.java

@@ -84,11 +84,25 @@ public NetworkType getNetworkType() {
      * @return underlying {@link P2PKAddress}.
      * @throws IllegalArgumentException if this instance is not P2PK address
      */
-    public P2PKAddress asP2PK() {
+    /**
+     * @return underlying {@link P2PKAddress}.
+     * @throws IllegalArgumentException if this instance is not P2PK address
+     */
+    public P2PKAddress toP2PK() {
         InternalUtil.checkArgument(isP2PK(), "This instance %s is not P2PKAddress", this);
         return (P2PKAddress) _address;
     }
 
+    /**
+     * @return underlying {@link P2PKAddress}.
+     * @throws IllegalArgumentException if this instance is not P2PK address
+     * @deprecated use {@link #toP2PK()}
+     */
+    @Deprecated
+    public P2PKAddress asP2PK() {
+        return toP2PK();
+    }
+
     /**
      * @return true if this address has Pay-To-Script type.
      */
@@ -98,11 +112,21 @@ public P2PKAddress asP2PK() {
      * @return underlying {@link Pay2SAddress}.
      * @throws IllegalArgumentException if this instance is not P2S address
      */
-    public Pay2SAddress asP2S() {
+    public Pay2SAddress toP2S() {
         InternalUtil.checkArgument(isP2S(), "This instance %s is not Pay2SAddress", this);
         return (Pay2SAddress) _address;
     }
 
+    /**
+     * @return underlying {@link Pay2SAddress}.
+     * @throws IllegalArgumentException if this instance is not P2S address
+     * @deprecated use {@link #toP2S()}
+     */
+    @Deprecated
+    public Pay2SAddress asP2S() {
+        return toP2S();
+    }
+
     /**
      * Obtain an instance of {@link ErgoAddress} related to this Address instance.
      *
@@ -115,7 +139,7 @@ public ErgoAddress getErgoAddress() {
     /**
      * Extract public key from P2PKAddress.
      */
-    public DLogProtocol.ProveDlog getPublicKey() { return asP2PK().pubkey(); }
+    public DLogProtocol.ProveDlog getPublicKey() { return toP2PK().pubkey(); }
 
     /**
      * Extract public key from P2PKAddress and return its group element

lib-api/src/main/java/org/ergoplatform/appkit/BoxOperations.java

@@ -77,7 +77,7 @@ public static BoxOperations createForProver(ErgoProver senderProver, BlockchainC
     /**
      * @param amountToSpend nanoerg value to be collected in inboxes
      */
-    public BoxOperations withAmountToSpend(long amountToSpend) {
+    public BoxOperations value(long amountToSpend) {
         if (amountToSpend < 0) {
             throw new IllegalArgumentException("Amount to send must be >= 0");
         }
@@ -89,15 +89,15 @@ public BoxOperations withAmountToSpend(long amountToSpend) {
     /**
      * @param tokensToSpend tokens to be collected in inboxes
      */
-    public BoxOperations withTokensToSpend(@Nonnull List<ErgoToken> tokensToSpend) {
+    public BoxOperations tokens(@Nonnull List<ErgoToken> tokensToSpend) {
         this.tokensToSpend = tokensToSpend;
         return this;
     }
 
     /**
      * @param feeAmount fee amount in nanoerg to be used for generated transactions
      */
-    public BoxOperations withFeeAmount(long feeAmount) {
+    public BoxOperations fee(long feeAmount) {
         if (feeAmount < MinFee) {
             throw new IllegalArgumentException("Amount to send must be >= " + MinFee);
         }
@@ -109,7 +109,7 @@ public BoxOperations withFeeAmount(long feeAmount) {
     /**
      * @param attachment attachment to be set for outboxes
      */
-    public BoxOperations withAttachment(@Nullable BoxAttachment attachment) {
+    public BoxOperations attachment(@Nullable BoxAttachment attachment) {
         this.attachment = attachment;
         return this;
     }
@@ -126,19 +126,19 @@ public int getMaxInputBoxesToSelect() {
      *                              if set to <= 0 (or not set), there is no input box restriction
      *                              checked by loadTop.
      */
-    public BoxOperations withMaxInputBoxesToSelect(int maxInputBoxesToSelect) {
+    public BoxOperations maxInputBoxes(int maxInputBoxesToSelect) {
         this.maxInputBoxesToSelect = maxInputBoxesToSelect;
         return this;
     }
 
     /**
      * @param message message to be set for outboxes as {@link BoxAttachmentPlainText}
      */
-    public BoxOperations withMessage(@Nullable String message) {
+    public BoxOperations message(@Nullable String message) {
         if (message != null) {
-            withAttachment(BoxAttachmentPlainText.buildForText(message));
+            attachment(BoxAttachmentPlainText.buildForText(message));
         } else {
-            withAttachment(null);
+            attachment(null);
         }
         return this;
     }
@@ -148,7 +148,7 @@ public BoxOperations withMessage(@Nullable String message) {
      *                         See {@link IUnspentBoxesLoader for more information}
      *                         Default is {@link ExplorerApiUnspentLoader}
      */
-    public BoxOperations withInputBoxesLoader(@Nonnull IUnspentBoxesLoader inputBoxesSource) {
+    public BoxOperations inputBoxesLoader(@Nonnull IUnspentBoxesLoader inputBoxesSource) {
         this.inputBoxesLoader = inputBoxesSource;
         return this;
     }
@@ -231,7 +231,7 @@ public String send(Address recipient) {
      * list.
      * The list is then used to select covering boxes.
      *
-     * The method respects a max amount of boxes to be selected set by {@link #withMaxInputBoxesToSelect(int)}.
+     * The method respects a max amount of boxes to be selected set by {@link #maxInputBoxes(int)}.
      * If this limit is exceeded, a {@link org.ergoplatform.appkit.InputBoxesSelectionException.InputBoxLimitExceededException}
      * is thrown and no further boxes are loaded.
      *

lib-api/src/main/java/org/ergoplatform/appkit/UnsignedTransactionBuilder.java

@@ -35,6 +35,15 @@ public interface UnsignedTransactionBuilder {
      */
     UnsignedTransactionBuilder addInputs(InputBox... boxes);
 
+    /**
+     * Adds input boxes to an already specified list of inputs or, if no input boxes defined yet,
+     * as the boxes to spend. The order is preserved.
+     * The boxes that will be spent by the transaction when it will be included in a block.
+     *
+     * @param boxes list of boxes to be spent by the transaction.
+     */
+    UnsignedTransactionBuilder addInputs(List<InputBox> boxes);
+
     /**
      * @deprecated use {@link #addInputs(InputBox...)}
      */
@@ -53,6 +62,14 @@ public interface UnsignedTransactionBuilder {
      */
     UnsignedTransactionBuilder addDataInputs(InputBox... boxes);
 
+    /**
+     * Adds input boxes to an already specified list of data inputs or, if no data input boxes
+     * defined yet, set the boxes as the data input boxes to be used. The order is preserved.
+     *
+     * @param boxes list of boxes to be used as data-inputs by the transaction.
+     */
+    UnsignedTransactionBuilder addDataInputs(List<InputBox> boxes);
+
     /**
      * @deprecated use {@link #addDataInputs(InputBox...)}
      */
@@ -77,6 +94,14 @@ public interface UnsignedTransactionBuilder {
      */
     UnsignedTransactionBuilder addOutputs(OutBox... outBoxes);
 
+    /**
+     * Adds output boxes to an already specified list of outputs or, if no output boxes defined yet,
+     * as the boxes to be output. The order is preserved.
+     *
+     * @param outBoxes output boxes created by the transaction
+     */
+    UnsignedTransactionBuilder addOutputs(List<OutBox> outBoxes);
+
     /**
      * Adds transaction fee output.
      *
@@ -98,6 +123,13 @@ public interface UnsignedTransactionBuilder {
      */
     UnsignedTransactionBuilder tokensToBurn(ErgoToken... tokens);
 
+    /**
+     * Configures amounts for tokens to be burnt.
+     *
+     * @param tokens one or more tokens to be burnt as part of the transaction.
+     */
+    UnsignedTransactionBuilder tokensToBurn(List<ErgoToken> tokens);
+
     /**
      * Adds change output to the specified address if needed.
      *

lib-impl/src/main/java/org/ergoplatform/appkit/impl/OutBoxBuilderImpl.scala

@@ -25,7 +25,6 @@ class OutBoxBuilderImpl(_txB: UnsignedTransactionBuilderImpl) extends OutBoxBuil
   }
 
   override def tokens(tokens: ErgoToken*): OutBoxBuilderImpl = {
-    require(tokens.nonEmpty, "At least one token should be specified")
     val maxTokens = SigmaConstants.MaxTokens.value
     require(tokens.size <= maxTokens, SigmaConstants.MaxTokens.description + s": $maxTokens")
     _tokens ++= tokens