[java] fix javadoc warnings in shared library

java/shared/src/main/java/com/squareup/subzero/shared/Base45.java

@@ -21,12 +21,20 @@
  * to manually type the code (for dev/debugging purpose or as a fallback).
  */
 public final class Base45 {
+  /** The ordered set of valid Base45 characters as a String. */
   protected static final String CHARSET = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ $%*+-./:";
   private final static Object lock = new Object();
+  /** The reverse-lookup map from Base45 character to Integer value. */
   protected static ImmutableMap<Character, Integer> REVERSE_CHARSET = null;
 
+  /** Everything in this class is static, so don't allow construction. */
+  private Base45() {}
+
   /**
    * Fast reverse lookup using ImmutableMap.
+   * @param c the Base45 character to look up
+   * @return the Integer value of the character, in the range [0, 44], or null if the character is
+   *         not a member of the Base45 charset.
    */
   protected static Integer indexOf(char c) {
     // The map needs to be initialized in a thread-safe way.
@@ -44,6 +52,8 @@ protected static Integer indexOf(char c) {
 
   /**
    * Encodes a byte array to a Base45-encoded String.
+   * @param input the bytes to encode
+   * @return the input encoded as a Base45 string
    */
   public static String toBase45(byte[] input) {
     // input expands by approximately a factor of 1.5 (1.5 comes from log(256) / log(45))
@@ -92,8 +102,9 @@ public static String toBase45(byte[] input) {
 
   /**
    * Decodes a Base45-encoded String back to a byte array.
-   *
-   * Throws IllegalArgumentException if the input contains invalid characters.
+   * @param input the Base45-encoded string
+   * @return the decoded byte array
+   * @throws IllegalArgumentException if the input contains invalid characters.
    */
   public static byte[] fromBase45(String input) {
     // input shrinks by a factor 1.5

java/shared/src/main/java/com/squareup/subzero/shared/ColdWallet.java

@@ -31,6 +31,10 @@
 import static java.lang.String.format;
 import static org.bitcoinj.crypto.DeterministicKey.deserializeB58;
 
+/**
+ * This class represents a subzero cold wallet and provides methods for transferring funds out of
+ * the cold wallet into the gateway.
+ */
 public class ColdWallet {
   private NetworkParameters params;
   private int walletId;
@@ -42,7 +46,8 @@ public class ColdWallet {
    *
    * @param params org.bitcoinj.params.TestNet3Params or org.bitcoinj.params.MainNetParams
    * @param walletId A walletId used by Subzero to identify which wallet to use
-   * @param publicRootKeys The public keys from wallet initialization
+   * @param publicRootKeys The Base58-encoded public keys from wallet initialization
+   * @param gateway The Base58-encoded gateway xpub(?) address.
    */
   public ColdWallet(NetworkParameters params, int walletId, List<String> publicRootKeys,
       String gateway) {
@@ -54,6 +59,13 @@ public ColdWallet(NetworkParameters params, int walletId, List<String> publicRoo
     this.gateway = deserializeB58(gateway, params);
   }
 
+  /**
+   * Constructor for ColdWallet object, used to interact with a cold wallet.
+   * @param params org.bitcoinj.params.TestNet3Params or org.bitcoinj.params.MainNetParams
+   * @param walletId A walletId used by Subzero to identify which wallet to use
+   * @param publicRootKeys The public keys from wallet initialization
+   * @param gateway The gateway public key.
+   */
   public ColdWallet(NetworkParameters params, int walletId, List<DeterministicKey> publicRootKeys,
       DeterministicKey gateway) {
     this.params = params;
@@ -112,6 +124,7 @@ public CommandRequest startTransaction(List<TxInput> inputs, List<TxOutput> outp
    * @param inputs This needs to match the inputs passed to startTransaction
    * @param outputs This needs to match the inputs passed to startTransaction
    * @param signatures The signatures from the Subzero responses to the startTransaction CommandRequests
+   * @return the transaction serialized to a byte array
    */
   public byte[] createTransaction(List<TxInput> inputs, List<TxOutput> outputs,
       List<List<Signature>> signatures) {
@@ -157,6 +170,15 @@ public R getRight() {
    * corresponding public keys were placed in the scriptPubKey or redeemScript. If all signatures
    * are valid, 1 is returned, 0 otherwise. Due to a bug, one extra unused value is removed from
    * the stack."
+   * @param publicRootKeys The public keys from wallet initialization.
+   * @param inputs List of transaction inputs.
+   * @param outputs List of transaction outputs.
+   * @param gateway The gateway address to send the funds to.
+   * @param signatures The list of signatures authorizing the transaction.
+   * @param lock_time The bitcoin lock time.
+   * @param sequence The sequence number.
+   * @return The serialized transaction.
+   * @throws RuntimeException on invalid input.
    */
   public byte[] createWrappedSegwitMultisigTransaction(
       List<DeterministicKey> publicRootKeys,

java/shared/src/main/java/com/squareup/subzero/shared/ColdWalletCreator.java

@@ -11,6 +11,10 @@
  * handled by three static functions here.
  */
 public class ColdWalletCreator {
+
+  /** Everything in this class is static, so don't allow construction. */
+  private ColdWalletCreator() {}
+
   /**
    * Create a new wallet.  Call this multiple times, if you want to use multiple tokens.
    *

java/shared/src/main/java/com/squareup/subzero/shared/Constants.java

@@ -1,25 +1,57 @@
 package com.squareup.subzero.shared;
 
+/**
+ * This class holds a bunch of constants, many of which must be kept in sync with subzero core.
+ */
 public class Constants {
-  public static final int MAGIC = 0x20de; // must be kept in sync with core/include/config.h
-  public static final int VERSION = 210; // must be kept in sync with core/include/config.h
+  /** Everything in this class is static, so don't allow construction. */
+  private Constants() {}
+
+  /** Magic number, must be kept in sync with core/include/config.h. */
+  public static final int MAGIC = 0x20de;
+
+  /** Current version, must be kept in sync with core/include/config.h. */
+  public static final int VERSION = 210;
+
+  /** Probably used for testing, or may be unused. */
   public static final int TEMP_DEFAULT_WALLET_ID = 9999;
 
+  /** Total number of participants in multisig transactions. */
   public static final int MULTISIG_PARTICIPANTS = 4;
+
+  /** Number of required signatures from participants in a multisig transaction. */
   public static final int MULTISIG_THRESHOLD = 2;
 
   // These constants need to be kept in sync with the following two files. The Java constants can be
   // more restrictive than the C ones.
   // https://github.com/square/subzero/blob/master/core/proto/squareup/subzero/common.options
   // https://github.com/square/subzero/blob/master/core/proto/squareup/subzero/internal.options
+
+  /** Max size of an encrypted master seed, in bytes. */
   public static final int ENCRYPTED_MASTER_SEED_MAX_SIZE = 92;
+
+  /** Max size of a master seed encryption key ticket, in bytes. */
   public static final int MASTER_SEED_ENCRYPTION_KEY_TICKET_MAX_SIZE = 256;
+
+  /** Max size of a pub key encryption key ticket, in bytes. */
   public static final int PUB_KEY_ENCRYPTION_KEY_TICKET_MAX_SIZE = 256;
+
+  /** Max number of encrypted pub keys. */
   public static final int ENCRYPTED_PUB_KEYS_MAX_COUNT = 4;
+
+  /** Max size of an encrypted pub key, in bytes. */
   public static final int ENCRYPTED_PUB_KEY_MAX_SIZE = 156;
+
+  /** Max number of transaction inputs. */
   public static final int INPUTS_COUNT_MAX = 128;
+
+  /** Max number of transaction outputs. */
   public static final int OUTPUTS_COUNT_MAX = 128;
+
+  /** Max size of a TxInput prev_hash, in bytes. */
   public static final int TXINPUT_PREV_HASH_MAX_SIZE = 32;
+
+  /** Max size of an InitializeWallet.random_bytes field, in bytes. */
   public static final int RANDOM_BYTES_MAX_SIZE = 64;
 
   /**

java/shared/src/main/java/com/squareup/subzero/shared/QrSigner.java

@@ -38,20 +38,25 @@ public class QrSigner implements Destroyable {
     // equivalent of NISTP256 in the trezor crypto library on the HSM.
     //https://tools.ietf.org/search/rfc4492#appendix-A
     private String curve_name = "secp256r1";
+    /** The path to the private key secret file. */
     public static String secret_path = "/tmp/secret";
 
     /**
      * Zeroize what can be done.
      * TODO: BigInteger is still there somewhere and it needs to be handled.
      *
-     * @throws DestroyFailedException
+     * @throws DestroyFailedException never actually thrown, forced by parent interface.
      */
     @Override
     public void destroy() throws DestroyFailedException {
         Arrays.fill(this.key, (byte) 0);
         this.is_destroyed = true;
     }
 
+    /**
+     * Getter for the private is_destroyed field.
+     * @return true if and only if destroy() has been called.
+     */
     @Override
     public boolean isDestroyed() {
         return is_destroyed;
@@ -77,18 +82,25 @@ private static byte[] readSecret() {
     }
 
     /**
+     * Sets the private static secret_path field.
      * @param path a String representing the absolute path.
      */
     public static void setSecretPath(String path) {
         QrSigner.secret_path = path;
     }
 
+    /**
+     * Creates a QrSigner which loads the key from the file referenced by the private static
+     * secret_path field.
+     */
     public QrSigner() {
         this(QrSigner.readSecret());
     }
 
     /**
+     * Constructs a new QrSigner which signs with the given secret key.
      * @param key bytes for the secret scalar. Big Endian.
+     * @throws RuntimeException if key.length != 32
      */
     public QrSigner(byte[] key) {
         if (key.length != 32) {
@@ -136,7 +148,11 @@ public byte[] sign(byte[] data) {
         return ret.toByteArray();
     }
 
-    // Only added to demonstrate error
+    /**
+     * Only added to demonstrate error.
+     * @param data the bytes to sign incorrectly.
+     * @return the incorrect signature.
+     */
     public byte[] incorrectSignTest(byte[] data) {
         ECDSASigner signer = new ECDSASigner(new HMacDSAKCalculator(new SHA256Digest()));
         // BigInteger is signed. This is wrong. Just for Test.
@@ -151,9 +167,12 @@ public byte[] incorrectSignTest(byte[] data) {
     }
 
     /**
+     * Verifies the given signature over the given byte array, using the key this QrSigner was
+     * constructed with.
      * @param signature raw signature bytes as obtained from `sign`.
      * @param data      bytes to verify the signature against.
-     * @return
+     * @return true if and only if the signature is valid.
+     * @throws RuntimeException if signature.length != 64.
      */
     public boolean verify(byte[] signature, byte[] data) {
         if (signature.length != 64) {
@@ -167,14 +186,22 @@ public boolean verify(byte[] signature, byte[] data) {
         return signer.verifySignature(hashed_data, BigIntegers.fromUnsignedByteArray(signature, 0, 32), BigIntegers.fromUnsignedByteArray(signature, 32, 32));
     }
 
+    /**
+     * Gets the public key as a raw byte array.
+     * @return the raw public key bytes.
+     */
     public byte[] dumpPublicKey() {
         ECPoint base = this.domain.getG();
         //BigIntegers.fromUnsignedByteArray is the way to do it.
         ECPoint pub = base.multiply(BigIntegers.fromUnsignedByteArray(this.key, 0, 32));
         return pub.getEncoded(false);
 
     }
-    // Only added to demonstrate and test for a prior Bug.
+
+    /**
+     * Only added to demonstrate and test for a prior Bug.
+     * @return the public key, encoded incorrectly.
+     */
     public byte[] dumpIncorrectPublicKeyTest() {
         ECPoint base = this.domain.getG();
         // BigInteger is signed. This is wrong. Just for Test.