Merge pull request #666 from doitian/custom-script-doc

docs: document script handler and signer

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

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

core/src/main/java/org/nervos/ckb/sign/ScriptSigner.java

@@ -2,6 +2,27 @@
 
 import org.nervos.ckb.type.Transaction;
 
+/**
+ * ScriptSigner implements the signing logic for various scripts.
+ *
+ * These signers should be registered in {@link TransactionSigner}.
+ */
 public interface ScriptSigner {
+  /**
+   * Sign the transaction for the script.
+   *
+   * This function is called by {@link TransactionSigner}
+   * for each context and each matched script group.
+   *
+   * @param transaction The transaction to be signed.
+   * @param scriptGroup TransactionSigner selects the corresponding ScriptSigner for each script group.
+   *     This selection is based on the registered ScriptSigner's provided script type and hash.
+   * @param context This is passed from {@code TransactionSigner.signTransaction}
+   * @return {@code true} when the script handler has modified the transaction.
+   *
+   * @see TransactionSigner#signTransaction(TransactionWithScriptGroups, Context...)
+   * @see TransactionSigner#signTransaction(TransactionWithScriptGroups, Set<Context>)
+   * @see TransactionSigner#signTransaction(TransactionWithScriptGroups, String...)
+   */
   boolean signTransaction(Transaction transaction, ScriptGroup scriptGroup, Context context);
 }

core/src/main/java/org/nervos/ckb/sign/TransactionSigner.java

@@ -87,12 +87,25 @@ public TransactionSigner registerLockScriptSigner(String codeHash, ScriptSigner
     return registerLockScriptSigner(Numeric.hexStringToByteArray(codeHash), scriptSigner);
   }
 
-
+  /**
+   * signTransaction signs the transaction using registered ScriptSigners.
+   *
+   * @param transaction Transaction to be signed.
+   * @param contexts Contexts for {@link org.nervos.ckb.sign.ScriptSigner}.
+   * @return signed groups indices.
+   */
   public Set<Integer> signTransaction(
       TransactionWithScriptGroups transaction, Context... contexts) {
     return signTransaction(transaction, new HashSet<>(Arrays.asList(contexts)));
   }
 
+  /**
+   * signTransaction signs the transaction using registered ScriptSigners.
+   *
+   * @param transaction Transaction to be signed.
+   * @param contexts Contexts for {@link org.nervos.ckb.sign.ScriptSigner}.
+   * @return signed groups indices.
+   */
   public Set<Integer> signTransaction(
       TransactionWithScriptGroups transaction, Set<Context> contexts) {
     Set<Integer> signedGroupsIndices = new HashSet<>();
@@ -122,6 +135,13 @@ public Set<Integer> signTransaction(
     return signedGroupsIndices;
   }
 
+  /**
+   * signTransaction signs the transaction using registered ScriptSigners.
+   *
+   * @param transaction Transaction to be signed.
+   * @param privateKeys Each private key is wrapped in one {@link Context}. These contexts will be passed to ScriptSigners.
+   * @return signed groups indices.
+   */
   public Set<Integer> signTransaction(
       TransactionWithScriptGroups transaction, String... privateKeys) {
     Contexts contexts = new Contexts();