Feature/credentials (#625)

Add support for XLS-70d Credentials:

* Update existing transactions
* Add Credential ledger object
* add Credential integration tests
* Add unit and integration tests.
* Update testnet faucet url

Author: Patel-Raj11

V5_MIGRATION.md

@@ -0,0 +1,18 @@
+## Version 4 to Version 5 Migration Guide
+
+This guide explains a breaking change in v5.0.0 and how to upgrade from v4.1.0 to v5.0.0.
+
+With the [XLS-0070-credentials](https://github.com/XRPLF/XRPL-Standards/tree/master/XLS-0070-credentials) amendment, the
+`DepositPreAuth` transaction can now preauthorize **credentials**, not just an account like before.
+
+Because of this change, new `DepositPreAuthObject` ledger objects on the XRPL might have:
+
+- **No `Authorize` field**
+- A new field called **`AuthorizeCredentials`**
+
+So in v5.0.0, the `Authorize` field is now optional.
+
+When calling `ledger_entry` or `account_objects` in rippled (starting v5.0.0), the response for a `DepositPreAuthObject`
+will include **either** `Authorize` **or** `AuthorizeCredentials`, **not both**.
+
+Before using the response, check if the `Authorize` field is present.

xrpl4j-core/src/main/java/org/xrpl/xrpl4j/crypto/signing/SignatureUtils.java

@@ -44,6 +44,9 @@
 import org.xrpl.xrpl4j.model.transactions.CheckCash;
 import org.xrpl.xrpl4j.model.transactions.CheckCreate;
 import org.xrpl.xrpl4j.model.transactions.Clawback;
+import org.xrpl.xrpl4j.model.transactions.CredentialAccept;
+import org.xrpl.xrpl4j.model.transactions.CredentialCreate;
+import org.xrpl.xrpl4j.model.transactions.CredentialDelete;
 import org.xrpl.xrpl4j.model.transactions.DepositPreAuth;
 import org.xrpl.xrpl4j.model.transactions.DidDelete;
 import org.xrpl.xrpl4j.model.transactions.DidSet;
@@ -416,6 +419,18 @@ public <T extends Transaction> SingleSignedTransaction<T> addSignatureToTransact
       transactionWithSignature = MpTokenIssuanceSet.builder().from((MpTokenIssuanceSet) transaction)
         .transactionSignature(signature)
         .build();
+    } else if (CredentialCreate.class.isAssignableFrom(transaction.getClass())) {
+      transactionWithSignature = CredentialCreate.builder().from((CredentialCreate) transaction)
+        .transactionSignature(signature)
+        .build();
+    } else if (CredentialAccept.class.isAssignableFrom(transaction.getClass())) {
+      transactionWithSignature = CredentialAccept.builder().from((CredentialAccept) transaction)
+        .transactionSignature(signature)
+        .build();
+    } else if (CredentialDelete.class.isAssignableFrom(transaction.getClass())) {
+      transactionWithSignature = CredentialDelete.builder().from((CredentialDelete) transaction)
+        .transactionSignature(signature)
+        .build();
     } else {
       // Should never happen, but will in a unit test if we miss one.
       throw new IllegalArgumentException("Signing fields could not be added to the transaction.");
@@ -647,6 +662,18 @@ public <T extends Transaction> T addMultiSignaturesToTransaction(T transaction,
       transactionWithSignatures = MpTokenIssuanceSet.builder().from((MpTokenIssuanceSet) transaction)
         .signers(signers)
         .build();
+    } else if (CredentialCreate.class.isAssignableFrom(transaction.getClass())) {
+      transactionWithSignatures = CredentialCreate.builder().from((CredentialCreate) transaction)
+        .signers(signers)
+        .build();
+    } else if (CredentialAccept.class.isAssignableFrom(transaction.getClass())) {
+      transactionWithSignatures = CredentialAccept.builder().from((CredentialAccept) transaction)
+        .signers(signers)
+        .build();
+    } else if (CredentialDelete.class.isAssignableFrom(transaction.getClass())) {
+      transactionWithSignatures = CredentialDelete.builder().from((CredentialDelete) transaction)
+        .signers(signers)
+        .build();
     } else {
       // Should never happen, but will in a unit test if we miss one.
       throw new IllegalArgumentException("Signing fields could not be added to the transaction.");

xrpl4j-core/src/main/java/org/xrpl/xrpl4j/model/client/accounts/AccountObjectsRequestParams.java

@@ -9,9 +9,9 @@
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
  * You may obtain a copy of the License at
- * 
+ *
  *      http://www.apache.org/licenses/LICENSE-2.0
- * 
+ *
  * Unless required by applicable law or agreed to in writing, software
  * distributed under the License is distributed on an "AS IS" BASIS,
  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
@@ -93,8 +93,8 @@ default boolean deletionBlockersOnly() {
   }
 
   /**
-   * Specifies the ledger version to request. A ledger version can be specified by ledger hash,
-   * numerical ledger index, or a shortcut value.
+   * Specifies the ledger version to request. A ledger version can be specified by ledger hash, numerical ledger index,
+   * or a shortcut value.
    *
    * @return A {@link LedgerSpecifier} specifying the ledger version to request.
    */
@@ -125,6 +125,10 @@ enum AccountObjectType {
      * Check account object type.
      */
     CHECK("check"),
+    /**
+     * Credential account object type.
+     */
+    CREDENTIAL("credential"),
     /**
      * Desposit pre auth account object type.
      */

xrpl4j-core/src/main/java/org/xrpl/xrpl4j/model/client/ledger/CredentialLedgerEntryParams.java

@@ -0,0 +1,50 @@
+package org.xrpl.xrpl4j.model.client.ledger;
+
+import com.fasterxml.jackson.annotation.JsonProperty;
+import com.fasterxml.jackson.databind.annotation.JsonDeserialize;
+import com.fasterxml.jackson.databind.annotation.JsonSerialize;
+import org.immutables.value.Value.Immutable;
+import org.xrpl.xrpl4j.model.ledger.CredentialObject;
+import org.xrpl.xrpl4j.model.transactions.Address;
+import org.xrpl.xrpl4j.model.transactions.CredentialType;
+
+/**
+ * Parameters that uniquely identify an {@link CredentialObject} on ledger. Can be used in a
+ * {@link LedgerEntryRequestParams} to request an {@link CredentialObject}.
+ */
+@Immutable
+@JsonSerialize(as = ImmutableCredentialLedgerEntryParams.class)
+@JsonDeserialize(as = ImmutableCredentialLedgerEntryParams.class)
+public interface CredentialLedgerEntryParams {
+
+  /**
+   * Construct a {@code CredentialLedgerEntryParams} builder.
+   *
+   * @return An {@link ImmutableCredentialLedgerEntryParams.Builder}.
+   */
+  static ImmutableCredentialLedgerEntryParams.Builder builder() {
+    return ImmutableCredentialLedgerEntryParams.builder();
+  }
+
+  /**
+   * The subject of the credential.
+   *
+   * @return The unique {@link Address} of the subject of this credential.
+   */
+  Address subject();
+
+  /**
+   * The issuer of the credential.
+   *
+   * @return The unique {@link Address} of the issuer of this credential.
+   */
+  Address issuer();
+
+  /**
+   * A (hex-encoded) value to identify the type of credential from the issuer.
+   *
+   * @return A {@link CredentialType} defining the type of credential.
+   */
+  @JsonProperty("credential_type")
+  CredentialType credentialType();
+}

xrpl4j-core/src/main/java/org/xrpl/xrpl4j/model/client/ledger/DepositPreAuthCredential.java

@@ -0,0 +1,62 @@
+package org.xrpl.xrpl4j.model.client.ledger;
+
+/*-
+ * ========================LICENSE_START=================================
+ * xrpl4j :: model
+ * %%
+ * Copyright (C) 2020 - 2022 XRPL Foundation and its contributors
+ * %%
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ * =========================LICENSE_END==================================
+ */
+
+import com.fasterxml.jackson.annotation.JsonProperty;
+import com.fasterxml.jackson.databind.annotation.JsonDeserialize;
+import com.fasterxml.jackson.databind.annotation.JsonSerialize;
+import org.immutables.value.Value;
+import org.xrpl.xrpl4j.model.transactions.Address;
+import org.xrpl.xrpl4j.model.transactions.CredentialType;
+
+/**
+ * {@link DepositPreAuthCredential} inner object with Issuer and CredentialType details.
+ */
+@Value.Immutable
+@JsonSerialize(as = ImmutableDepositPreAuthCredential.class)
+@JsonDeserialize(as = ImmutableDepositPreAuthCredential.class)
+public interface DepositPreAuthCredential {
+
+  /**
+   * Construct a builder for this class.
+   *
+   * @return An {@link ImmutableDepositPreAuthCredential.Builder}.
+   */
+  static ImmutableDepositPreAuthCredential.Builder builder() {
+    return ImmutableDepositPreAuthCredential.builder();
+  }
+
+  /**
+   * The issuer of the credential.
+   *
+   * @return The unique {@link Address} of the issuer this credential.
+   */
+  @JsonProperty("issuer")
+  Address issuer();
+
+  /**
+   * A (hex-encoded) value to identify the type of credential from the issuer.
+   *
+   * @return A {@link CredentialType} defining the type of credential.
+   */
+  @JsonProperty("credential_type")
+  CredentialType credentialType();
+}

xrpl4j-core/src/main/java/org/xrpl/xrpl4j/model/client/ledger/DepositPreAuthLedgerEntryParams.java

@@ -1,10 +1,17 @@
 package org.xrpl.xrpl4j.model.client.ledger;
 
+import com.fasterxml.jackson.annotation.JsonProperty;
 import com.fasterxml.jackson.databind.annotation.JsonDeserialize;
 import com.fasterxml.jackson.databind.annotation.JsonSerialize;
+import com.google.common.base.Preconditions;
+import org.immutables.value.Value;
 import org.immutables.value.Value.Immutable;
 import org.xrpl.xrpl4j.model.transactions.Address;
 
+import java.util.HashSet;
+import java.util.List;
+import java.util.Optional;
+
 /**
  * Parameters that uniquely identify a {@link org.xrpl.xrpl4j.model.ledger.DepositPreAuthObject} on ledger that can be
  * used in a {@link LedgerEntryRequestParams} to request an {@link org.xrpl.xrpl4j.model.ledger.DepositPreAuthObject}.
@@ -35,6 +42,39 @@ static ImmutableDepositPreAuthLedgerEntryParams.Builder builder() {
    *
    * @return An {@link Address}.
    */
-  Address authorized();
+  Optional<Address> authorized();
+
+  /**
+   * A list of {@link DepositPreAuthCredential} that received the preauthorization.
+   *
+   * @return A list of type {@link DepositPreAuthCredential}.
+   */
+  @JsonProperty("authorized_credentials")
+  List<DepositPreAuthCredential> authorizedCredentials();
+
+  /**
+   * Validate {@link DepositPreAuthLedgerEntryParams#authorizedCredentials} has less than or equal to 8 credentials.
+   */
+  @Value.Check
+  default void validateCredentialsLength() {
+    if (!authorizedCredentials().isEmpty()) {
+      Preconditions.checkArgument(
+        authorizedCredentials().size() <= 8,
+        "authorizedCredentials should have less than or equal to 8 items."
+      );
+    }
+  }
 
+  /**
+   * Validate {@link DepositPreAuthLedgerEntryParams#authorizedCredentials} are unique.
+   */
+  @Value.Check
+  default void validateUniqueCredentials() {
+    if (!authorizedCredentials().isEmpty()) {
+      Preconditions.checkArgument(
+        new HashSet<>(authorizedCredentials()).size() == authorizedCredentials().size(),
+        "authorizedCredentials should have unique values."
+      );
+    }
+  }
 }

xrpl4j-core/src/main/java/org/xrpl/xrpl4j/model/client/ledger/LedgerEntryRequestParams.java

@@ -13,6 +13,7 @@
 import org.xrpl.xrpl4j.model.ledger.AmmObject;
 import org.xrpl.xrpl4j.model.ledger.BridgeObject;
 import org.xrpl.xrpl4j.model.ledger.CheckObject;
+import org.xrpl.xrpl4j.model.ledger.CredentialObject;
 import org.xrpl.xrpl4j.model.ledger.DepositPreAuthObject;
 import org.xrpl.xrpl4j.model.ledger.DidObject;
 import org.xrpl.xrpl4j.model.ledger.EscrowObject;
@@ -199,6 +200,31 @@ static LedgerEntryRequestParams<CheckObject> check(
       .build();
   }
 
+  /**
+   * Construct a {@link LedgerEntryRequestParams} that requests a {@link CredentialObject} ledger entry.
+   *
+   * <p>Note that although the rippled API allows you to specify either the Credential's ID
+   * or the [subject, issuer and credential_type] of the transaction that created the Credential, this class does not
+   * allow developers to request a {@link CredentialObject} by ID via this method. Instead, developers should use
+   * {@link LedgerEntryRequestParams#index()} and specify {@link CredentialObject} as the {@code ledgerObjectClass}
+   * parameter.</p>
+   *
+   * @param params          The {@link CredentialLedgerEntryParams} that uniquely identify the {@link CredentialObject}
+   *                        on ledger.
+   * @param ledgerSpecifier A {@link LedgerSpecifier} indicating the ledger to query data from.
+   *
+   * @return A {@link LedgerEntryRequestParams} for {@link CredentialObject}.
+   */
+  static LedgerEntryRequestParams<CredentialObject> credential(
+    CredentialLedgerEntryParams params,
+    LedgerSpecifier ledgerSpecifier
+  ) {
+    return ImmutableLedgerEntryRequestParams.<CredentialObject>builder()
+      .credential(params)
+      .ledgerSpecifier(ledgerSpecifier)
+      .build();
+  }
+
   /**
    * Construct a {@link LedgerEntryRequestParams} that requests a {@link EscrowObject} ledger entry.
    *
@@ -464,6 +490,13 @@ default boolean binary() {
    */
   Optional<Hash256> check();
 
+  /**
+   * Look up a {@link org.xrpl.xrpl4j.model.ledger.CredentialObject} by {@link CredentialLedgerEntryParams}.
+   *
+   * @return An optionally-present {@link CredentialLedgerEntryParams}.
+   */
+  Optional<CredentialLedgerEntryParams> credential();
+
   /**
    * Look up an {@link org.xrpl.xrpl4j.model.ledger.EscrowObject} by {@link EscrowLedgerEntryParams}.
    *
@@ -578,6 +611,10 @@ default Class<T> ledgerObjectClass() {
       return (Class<T>) CheckObject.class;
     }
 
+    if (credential().isPresent()) {
+      return (Class<T>) CredentialObject.class;
+    }
+
     if (escrow().isPresent()) {
       return (Class<T>) EscrowObject.class;
     }