#51 Add payment functionality

src/main/java/org/unicitylabs/sdk/StateTransitionClient.java

@@ -37,6 +37,12 @@ public CompletableFuture<InclusionProofResponse> getInclusionProof(StateId state
     return this.client.getInclusionProof(stateId);
   }
 
+  /**
+   * Submits a certification request to the aggregator.
+   *
+   * @param certificationData The certification data to submit.
+   * @return certification response from the aggregator.
+   */
   public CompletableFuture<CertificationResponse> submitCertificationRequest(CertificationData certificationData) {
     return this.client.submitCertificationRequest(certificationData);
   }

src/main/java/org/unicitylabs/sdk/api/CertificationData.java

@@ -10,6 +10,7 @@
 import org.unicitylabs.sdk.crypto.secp256k1.SigningService;
 import org.unicitylabs.sdk.predicate.EncodedPredicate;
 import org.unicitylabs.sdk.predicate.Predicate;
+import org.unicitylabs.sdk.predicate.UnlockScript;
 import org.unicitylabs.sdk.predicate.builtin.PayToPublicKeyPredicateUnlockScript;
 import org.unicitylabs.sdk.serializer.cbor.CborDeserializer;
 import org.unicitylabs.sdk.serializer.cbor.CborSerializer;
@@ -39,6 +40,11 @@ public class CertificationData {
     this.unlockScript = Arrays.copyOf(unlockScript, unlockScript.length);
   }
 
+  /**
+   * Get lock script of certified transaction output.
+   *
+   * @return lock script
+   */
   public Predicate getLockScript() {
     return this.lockScript;
   }
@@ -61,12 +67,17 @@ public DataHash getTransactionHash() {
     return this.transactionHash;
   }
 
+  /**
+   * Get unlock script used for certification.
+   *
+   * @return unlock script bytes
+   */
   public byte[] getUnlockScript() {
     return Arrays.copyOf(this.unlockScript, this.unlockScript.length);
   }
 
   /**
-   * Create CertificationData from CBOR bytes.
+   * Deserialize CertificationData from CBOR bytes.
    *
    * @param bytes CBOR bytes
    * @return CertificationData
@@ -82,6 +93,13 @@ public static CertificationData fromCbor(byte[] bytes) {
     );
   }
 
+  /**
+   * Build certification data for a mint transaction using the deterministic mint signing service.
+   *
+   * @param transaction mint transaction
+   *
+   * @return certification data
+   */
   public static CertificationData fromMintTransaction(MintTransaction transaction) {
     SigningService signingService = MintSigningService.create(transaction.getTokenId());
 
@@ -92,6 +110,26 @@ public static CertificationData fromMintTransaction(MintTransaction transaction)
     );
   }
 
+  /**
+   * Build certification data from a transaction and unlock script object.
+   *
+   * @param transaction transaction to certify
+   * @param unlockScript unlock script
+   *
+   * @return certification data
+   */
+  public static CertificationData fromTransaction(Transaction transaction, UnlockScript unlockScript) {
+    return CertificationData.fromTransaction(transaction, unlockScript.encode());
+  }
+
+  /**
+   * Build certification data from a transaction and encoded unlock script bytes.
+   *
+   * @param transaction transaction to certify
+   * @param unlockScript encoded unlock script bytes
+   *
+   * @return certification data
+   */
   public static CertificationData fromTransaction(Transaction transaction, byte[] unlockScript) {
     return new CertificationData(
         transaction.getLockScript(),
@@ -113,7 +151,7 @@ public DataHash calculateLeafValue() {
   }
 
   /**
-   * Convert the certification data to CBOR bytes.
+   * Serialize certification data to CBOR bytes.
    *
    * @return CBOR bytes
    */

src/main/java/org/unicitylabs/sdk/api/CertificationRequest.java

@@ -54,11 +54,11 @@ public static CertificationRequest create(CertificationData certificationData) {
   }
 
   /**
-   * Convert the request to a CBOR bytes.
+   * Serialize request to a CBOR bytes.
    *
    * @return CBOR bytes
    */
-  public byte[] toCBOR() {
+  public byte[] toCbor() {
     return CborSerializer.encodeArray(
         this.stateId.toCbor(),
         this.certificationData.toCbor(),

src/main/java/org/unicitylabs/sdk/api/InclusionProof.java

@@ -22,12 +22,9 @@ public class InclusionProof {
       CertificationData certificationData,
       UnicityCertificate unicityCertificate
   ) {
-    Objects.requireNonNull(merkleTreePath, "Merkle tree path cannot be null.");
-    Objects.requireNonNull(unicityCertificate, "Unicity certificate cannot be null.");
-
-    this.merkleTreePath = merkleTreePath;
+    this.merkleTreePath = Objects.requireNonNull(merkleTreePath, "Merkle tree path cannot be null.");;
     this.certificationData = certificationData;
-    this.unicityCertificate = unicityCertificate;
+    this.unicityCertificate = Objects.requireNonNull(unicityCertificate, "Unicity certificate cannot be null.");;
   }
 
   /**
@@ -58,7 +55,7 @@ public Optional<CertificationData> getCertificationData() {
   }
 
   /**
-   * Create inclusion proof from CBOR bytes.
+   * Deserialize inclusion proof from CBOR bytes.
    *
    * @param bytes CBOR bytes
    * @return inclusion proof
@@ -74,7 +71,7 @@ public static InclusionProof fromCbor(byte[] bytes) {
   }
 
   /**
-   * Convert inclusion proof to CBOR bytes.
+   * Serialize inclusion proof to CBOR bytes.
    *
    * @return CBOR bytes
    */

src/main/java/org/unicitylabs/sdk/api/InclusionProofRequest.java

@@ -26,6 +26,11 @@ public InclusionProofRequest(
     this.stateId = stateId.getData();
   }
 
+  /**
+   * Get state id.
+   *
+   * @return state id
+   */
   public byte[] getStateId() {
     return Arrays.copyOf(this.stateId, this.stateId.length);
   }

src/main/java/org/unicitylabs/sdk/api/InclusionProofResponse.java

@@ -35,7 +35,7 @@ public InclusionProof getInclusionProof() {
   }
 
   /**
-   * Create response from CBOR bytes.
+   * Deserialize response from CBOR bytes.
    *
    * @param bytes CBOR bytes
    * @return inclusion proof response
@@ -48,6 +48,11 @@ public static InclusionProofResponse fromCbor(byte[] bytes) {
     );
   }
 
+  /**
+   * Serialize inclusion proof response to CBOR bytes.
+   *
+   * @return CBOR bytes
+   */
   public byte[] toCbor() {
     return CborSerializer.encodeArray(
         CborSerializer.encodeUnsignedInteger(this.blockNumber),

src/main/java/org/unicitylabs/sdk/api/JsonRpcAggregatorClient.java

@@ -35,26 +35,31 @@ public JsonRpcAggregatorClient(String url) {
    *
    */
   public JsonRpcAggregatorClient(String url, String apiKey) {
-    Objects.requireNonNull(url, "url cannot be null");
-
-    this.transport = new JsonRpcHttpTransport(url);
+    this.transport = new JsonRpcHttpTransport(Objects.requireNonNull(url, "url cannot be null"));
     this.apiKey = apiKey;
   }
 
+  /**
+   * Submit a certification request for a transaction state transition.
+   *
+   * @param certificationData certification payload
+   *
+   * @return asynchronous certification response
+   */
+  @Override
   public CompletableFuture<CertificationResponse> submitCertificationRequest(
       CertificationData certificationData
   ) {
-    Objects.requireNonNull(certificationData, "certificationData cannot be null");
-
-    CertificationRequest request = CertificationRequest.create(certificationData);
+    CertificationRequest request = CertificationRequest.create(
+        Objects.requireNonNull(certificationData, "certificationData cannot be null"));
 
     Map<String, List<String>> headers = this.apiKey == null
         ? Map.of()
         : Map.of(AUTHORIZATION, List.of(String.format("Bearer %s", this.apiKey)));
 
     return this.transport.request(
         "certification_request",
-        HexConverter.encode(request.toCBOR()),
+        HexConverter.encode(request.toCbor()),
         CertificationResponse.class,
         headers
     );
@@ -66,10 +71,10 @@ public CompletableFuture<CertificationResponse> submitCertificationRequest(
    * @param stateId state id
    * @return inclusion / non inclusion proof
    */
+  @Override
   public CompletableFuture<InclusionProofResponse> getInclusionProof(StateId stateId) {
-    Objects.requireNonNull(stateId, "stateId cannot be null");
-
-    InclusionProofRequest request = new InclusionProofRequest(stateId);
+    InclusionProofRequest request = new InclusionProofRequest(
+        Objects.requireNonNull(stateId, "stateId cannot be null"));
 
     return this.transport
         .request("get_inclusion_proof.v2", request, String.class)
@@ -81,8 +86,9 @@ public CompletableFuture<InclusionProofResponse> getInclusionProof(StateId state
    *
    * @return block height
    */
+  @Override
   public CompletableFuture<Long> getBlockHeight() {
     return this.transport.request("get_block_height", Map.of(), BlockHeightResponse.class)
         .thenApply(BlockHeightResponse::getBlockNumber);
   }
-}
+}

src/main/java/org/unicitylabs/sdk/api/StateId.java

@@ -12,34 +12,67 @@
 import org.unicitylabs.sdk.util.BitString;
 import org.unicitylabs.sdk.util.HexConverter;
 
-public class StateId {
+/**
+ * Represents a state identifier for requests.
+ */
+public final class StateId {
 
   private final DataHash hash;
 
   private StateId(DataHash hash) {
     this.hash = hash;
   }
 
+  /**
+   * Returns the raw hash bytes of this state id.
+   *
+   * @return state id hash bytes
+   */
   public byte[] getData() {
     return this.hash.getData();
   }
 
+  /**
+   * Returns the hash imprint bytes.
+   *
+   * @return state id imprint bytes
+   */
   public byte[] getImprint() {
     return this.hash.getImprint();
   }
 
+  /**
+   * Deserializes a state id from CBOR.
+   *
+   * @param bytes CBOR byte string containing SHA-256 hash bytes
+   * @return decoded state id
+   */
   public static StateId fromCbor(byte[] bytes) {
     return new StateId(
         new DataHash(HashAlgorithm.SHA256, CborDeserializer.decodeByteString(bytes)));
   }
 
+  /**
+   * Creates a state id from certification data.
+   *
+   * @param certificationData certification data carrying lock script and source state hash
+   * @return created state id
+   * @throws NullPointerException if {@code certificationData} is {@code null}
+   */
   public static StateId fromCertificationData(CertificationData certificationData) {
     Objects.requireNonNull(certificationData, "Certification data cannot be null");
 
     return StateId.create(certificationData.getLockScript(),
         certificationData.getSourceStateHash());
   }
 
+  /**
+   * Creates a state id from transaction data.
+   *
+   * @param transaction transaction carrying lock script and source state hash
+   * @return created state id
+   * @throws NullPointerException if {@code transaction} is {@code null}
+   */
   public static StateId fromTransaction(Transaction transaction) {
     Objects.requireNonNull(transaction, "Transaction cannot be null");
 
@@ -59,17 +92,22 @@ private static StateId create(Predicate predicate, DataHash stateHash) {
     return new StateId(hash);
   }
 
+  /**
+   * Serializes this state id as a CBOR bytes.
+   *
+   * @return CBOR-encoded state id
+   */
   public byte[] toCbor() {
     return CborSerializer.encodeByteString(this.getData());
   }
 
   /**
-   * Converts the StateId to a BitString.
+   * Converts this state id to a {@link BitString}.
    *
-   * @return The BitString representation of the StateId.
+   * @return bit string representation of this state id
    */
   public BitString toBitString() {
-    return BitString.fromStateId(this);
+    return new BitString(this.getImprint());
   }
 
   @Override
@@ -86,13 +124,8 @@ public int hashCode() {
     return Objects.hashCode(this.hash);
   }
 
-  /**
-   * Returns a string representation of the StateId.
-   *
-   * @return The string representation.
-   */
   @Override
   public String toString() {
     return String.format("StateId[%s]", HexConverter.encode(this.getImprint()));
   }
-}
+}

src/main/java/org/unicitylabs/sdk/api/bft/InputRecord.java

@@ -144,7 +144,7 @@ public byte[] getExecutedTransactionsHash() {
   }
 
   /**
-   * Create InputRecord from CBOR bytes.
+   * Deserialize InputRecord from CBOR bytes.
    *
    * @param bytes CBOR bytes
    * @return input record
@@ -168,7 +168,7 @@ public static InputRecord fromCbor(byte[] bytes) {
   }
 
   /**
-   * Convert InputRecord to CBOR bytes.
+   * Serialize InputRecord to CBOR bytes.
    *
    * @return CBOR bytes
    */

src/main/java/org/unicitylabs/sdk/api/bft/ShardTreeCertificate.java

@@ -47,7 +47,7 @@ public List<byte[]> getSiblingHashList() {
   }
 
   /**
-   * Create shard tree certificate from CBOR bytes.
+   * Deserialize shard tree certificate from CBOR bytes.
    *
    * @param bytes CBOR bytes
    * @return shard tree certificate
@@ -64,7 +64,7 @@ public static ShardTreeCertificate fromCbor(byte[] bytes) {
   }
 
   /**
-   * Convert shard tree certificate to CBOR bytes.
+   * Serialize shard tree certificate to CBOR bytes.
    *
    * @return CBOR bytes
    */