From 7d054397ae4bdb824950904d0eedca358c1f63fd Mon Sep 17 00:00:00 2001
From: ian <ian@cryptape.com>
Date: Sat, 2 Sep 2023 10:50:18 +0800
Subject: [PATCH] docs: add docs for tx builder and ScriptHandler

---
 build.gradle                                  |  2 +
 .../AbstractTransactionBuilder.java           | 21 ++++++++
 .../transaction/handler/ScriptHandler.java    | 51 +++++++++++++++++++
 3 files changed, 74 insertions(+)

diff --git a/build.gradle b/build.gradle
index 13ed3a577..b1398abc8 100644
--- a/build.gradle
+++ b/build.gradle
@@ -13,6 +13,7 @@ buildscript {
     ext.mockkVersion = "1.13.5"
 
     repositories {
+        maven { url 'https://maven.aliyun.com/repository/public/' }
         mavenCentral()
     }
 
@@ -46,6 +47,7 @@ allprojects {
     apply plugin: 'java'
 
     repositories {
+        maven { url 'https://maven.aliyun.com/repository/public/' }
         mavenCentral()
     }
 
diff --git a/ckb/src/main/java/org/nervos/ckb/transaction/AbstractTransactionBuilder.java b/ckb/src/main/java/org/nervos/ckb/transaction/AbstractTransactionBuilder.java
index a21c65e2c..c5b0d4ba1 100644
--- a/ckb/src/main/java/org/nervos/ckb/transaction/AbstractTransactionBuilder.java
+++ b/ckb/src/main/java/org/nervos/ckb/transaction/AbstractTransactionBuilder.java
@@ -19,6 +19,12 @@ public abstract class AbstractTransactionBuilder {
   protected List<TransactionInput> inputsDetail = new ArrayList<>();
   protected Transaction tx = new Transaction();
 
+  /**
+   * Initialites the transaction builder.
+   *
+   * @param configuration This is the bundle of configuration for builder,
+   *                      such as fee rate and registerred {@link org.nervos.ckb.transaction.handler.ScriptHandler}.
+   */
   public AbstractTransactionBuilder(TransactionBuilderConfiguration configuration, Iterator<TransactionInput> availableInputs) {
     this.configuration = configuration;
     this.availableInputs = availableInputs;
@@ -94,9 +100,24 @@ protected static long calculateTxFee(Transaction transaction, long feeRate) {
     return Calculator.calculateTransactionFee(transaction, feeRate);
   }
 
+  /**
+   * Builds the transaction with a default context for script handlers.
+   *
+   * This function will call script handlers in {@code TransactionConfiguration} with a
+   * default context null. Use {@link #build(Object...)} to pass custom contexts.
+   *
+   * @see org.nervos.ckb.transaction.handler.ScriptHandler#buildTransaction(AbstractTransactionBuilder, ScriptGroup, Object)
+   */
   public TransactionWithScriptGroups build() {
     return build((Object) null);
   }
 
+  /**
+   * Builds the transaction with custom contexts for script handlers.
+   *
+   * The contexts will be passed to the registered script handlers in the same order.
+   *
+   * @see org.nervos.ckb.transaction.handler.ScriptHandler#buildTransaction(AbstractTransactionBuilder, ScriptGroup, Object)
+   */
   abstract TransactionWithScriptGroups build(Object... contexts);
 }
diff --git a/ckb/src/main/java/org/nervos/ckb/transaction/handler/ScriptHandler.java b/ckb/src/main/java/org/nervos/ckb/transaction/handler/ScriptHandler.java
index 994e26c8d..255d185d6 100644
--- a/ckb/src/main/java/org/nervos/ckb/transaction/handler/ScriptHandler.java
+++ b/ckb/src/main/java/org/nervos/ckb/transaction/handler/ScriptHandler.java
@@ -4,7 +4,58 @@
 import org.nervos.ckb.sign.ScriptGroup;
 import org.nervos.ckb.transaction.AbstractTransactionBuilder;
 
+/**
+ * ScriptHandler implements the building logic for various scripts.
+ *
+ * These handlers should be registered in the transaction builder via {@link
+ * org.nervos.ckb.transaction.TransactionBuilderConfiguration}.
+ */
 public interface ScriptHandler {
+  /**
+   * Build the transaction for the script.
+   *
+   * This function is called by transaction builder for each script group and each context.
+   *
+   * Generally this function should:
+   *
+   * <ol>
+   * <li>Check the scriptGroup to determine whether to proceed with the next steps or skip them.</li>
+   * <li>Add cell deps for the script.</li>
+   * <li>
+   *   Prefill the witness for the script so the transaction size will not
+   *   increase after signing, which may invalidate the fee calculation.
+   * </li>
+   * </ol>
+   *
+   * <p>For example:</p>
+   *
+   * <pre>{@code
+   * @Override
+   * boolean buildTransaction(AbstractTransactionBuilder txBuilder, ScriptGroup scriptGroup, Object context) {
+   *    // Only change the transaction when the script is used.
+   *    if (scriptGroup == null || !isMatched(scriptGroup.getScript())) {
+   *      return false;
+   *    }
+   *    // Add celldeps
+   *    txBuilder.addCellDeps(cellDeps);
+   *
+   *    // Prefill witness placeholder
+   *    int witnessIndex = scriptGroup.getInputIndices().get(0);
+   *    byte[] dummyWitness = new byte[8];
+   *    txBuilder.setWitness(witnessIndex, WitnessArgs.Type.LOCK, dummyWitness);
+   *
+   *    return true;
+   * }
+   * }</pre>
+   *
+   * @param txBuilder The transaction in building.
+   * @param scriptGroup Transaction builder calls this callback for each script group found in the transaction.
+   *     The script handler is responsoble for determining whether it should handle the given script group.
+   * @param context This is null passed from {@link org.nervos.ckb.transaction.AbstractTransactionBuilder#build()},
+   *     or provided contexts in {@link org.nervos.ckb.transaction.AbstractTransactionBuilder#build(Object...)}.
+   * @return {@code true} when the script handler has modified the transaction.
+   *
+   */
   boolean buildTransaction(AbstractTransactionBuilder txBuilder, ScriptGroup scriptGroup, Object context);
 
   void init(Network network);