@idos-network/kwil-infra 1.1.0

package/src/xrpl-credentials/accept.ts

@@ -0,0 +1,143 @@
+import { hexEncode, utf8Encode } from "@idos-network/utils/codecs";
+
+/**
+ * Payload structure for XRPL CredentialAccept transaction
+ *
+ * This type defines the required fields for creating a credential acceptance
+ * transaction on the XRP Ledger. The CredentialType field is automatically
+ * encoded as a hex string from the UTF-8 representation of the credential type.
+ */
+export type CredentialAcceptPayload = {
+  /** Transaction type identifier - must be "CredentialAccept" */
+  TransactionType: "CredentialAccept";
+  /** The issuer's XRPL address who created the Credential object */
+  Issuer: string;
+  /** The account's XRPL address who is receiving the credential */
+  Account: string;
+  /** The type of credential being accepted (encoded as hex string) */
+  CredentialType: string;
+};
+
+/**
+ * Creates a credential acceptance payload for XRPL transactions
+ *
+ * This function constructs a properly formatted payload for credential acceptance
+ * transactions. The credential type is automatically encoded from UTF-8 to hex
+ * format as required by XRPL specifications.
+ *
+ * @param issuerAddress - The XRPL address of the credential issuer
+ * @param accountAddress - The XRPL address of the account accepting the credential
+ * @param credentialType - The human-readable idOS credential type (e.g., "KYC")
+ * @returns A properly formatted CredentialAcceptPayload object
+ *
+ * @example
+ * ```typescript
+ * const payload = OriginalCredentialAcceptPayload(
+ *   "rIssuerAddress123...",
+ *   "rAccountAddress456...",
+ *   "KYC"
+ * );
+ * // Result: {
+ * //   TransactionType: "CredentialAccept",
+ * //   Issuer: "rIssuerAddress123...",
+ * //   Account: "rAccountAddress456...",
+ * //   CredentialType: "4B5943" // Hex encoded "KYC"
+ * // }
+ * ```
+ */
+export function OriginalCredentialAcceptPayload(
+  issuerAddress: string,
+  accountAddress: string,
+  credentialType: string,
+): CredentialAcceptPayload {
+  // Encode the credential type from UTF-8 to hex format
+  // This is required by XRPL for proper transaction processing
+  const encodedCredentialType = hexEncode(utf8Encode(credentialType));
+
+  return {
+    TransactionType: "CredentialAccept",
+    Issuer: issuerAddress,
+    Account: accountAddress,
+    CredentialType: encodedCredentialType,
+  };
+}
+
+/**
+ * Creates a copy credential acceptance payload for XRPL transactions
+ *
+ * This function constructs a payload for accepting a copy of an existing credential
+ * with additional metadata including the original issuer and a timelock period.
+ * The CredentialType field is encoded as a composite string containing:
+ * - "AG-" prefix (indicating copy credential)
+ * - Original credential type
+ * - Original issuer address
+ * - Timelock period in years
+ *
+ * @param copyCredentialIssuerAddress - The XRPL address of the issuer created a XRPL Credential object related to idOS credential copy
+ * @param accountAddress - The XRPL address of the account accepting the credential copy
+ * @param originalCredentialIssuerAddress - The XRPL address of the issuer created a XRPL Credential object related to idOS original credential
+ * @param credentialType - The human-readable idOScredential type (e.g., "KYC")
+ * @param timelockYears - The number of years for the timelock period (must be non-negative integer)
+ * @returns A properly formatted CredentialAcceptPayload object for copy credentials
+ * @throws {Error} When timelockYears is not a non-negative integer
+ *
+ * @example
+ * ```typescript
+ * const payload = await CopyCredentialAcceptPayload(
+ *   "rCopyIssuerAddress123...",
+ *   "rAccountAddress456...",
+ *   "rOriginalIssuerAddress789...",
+ *   "KYC",
+ *   2
+ * );
+ * // Result: {
+ * //   TransactionType: "CredentialAccept",
+ * //   Issuer: "rCopyIssuerAddress123...",
+ * //   Account: "rAccountAddress456...",
+ * //   CredentialType: "41472D4B59432D..." // Hex encoded "AG-KYC-{originalIssuer}-2Y"
+ * // }
+ * ```
+ */
+export async function CopyCredentialAcceptPayload(
+  copyCredentialIssuerAddress: string,
+  accountAddress: string,
+  originalCredentialIssuerAddress: string,
+  credentialType: string,
+  timelockYears: number,
+): Promise<CredentialAcceptPayload> {
+  // Validate that timelockYears is a non-negative integer
+  if (!Number.isInteger(timelockYears) || timelockYears < 0) {
+    throw new Error("timelockYears must be a non-negative integer");
+  }
+
+  let decodeAccountID: typeof import("xrpl").decodeAccountID;
+  try {
+    ({ decodeAccountID } = await import("xrpl"));
+  } catch {
+    throw new Error(
+      'Missing optional peer dependency "xrpl". Install it to use CopyCredentialAcceptPayload.',
+    );
+  }
+
+  // Create a composite credential type string that includes:
+  // - "AG-" prefix (indicating this is a copy credential)
+  // - Original credential type
+  // - Original issuer Account ID (decoded from XRPL address format)
+  // - Timelock period in years
+  const type = Buffer.concat([
+    utf8Encode("AG"),
+    utf8Encode("-"),
+    utf8Encode(credentialType),
+    utf8Encode("-"),
+    decodeAccountID(originalCredentialIssuerAddress),
+    utf8Encode("-"),
+    utf8Encode(`${timelockYears}Y`),
+  ]);
+
+  return {
+    TransactionType: "CredentialAccept",
+    Issuer: copyCredentialIssuerAddress,
+    Account: accountAddress,
+    CredentialType: hexEncode(type),
+  };
+}

package/src/xrpl-credentials/create.ts

@@ -0,0 +1,199 @@
+import type { Client, TxResponse, Wallet } from "xrpl";
+
+import { hexEncode, utf8Encode } from "@idos-network/utils/codecs";
+
+/**
+ * Parameters for creating an original credential on XRPL
+ */
+export type CreateCredentialForOriginalParams = {
+  /** Unique identifier for the idOS credential, like `741a9caf-ec53-42c7-aed6-519950dcded5` */
+  credId: string;
+  /** Type/category of the credential, like `KYC` */
+  credType: string;
+  /** XRPL address of the user receiving the credential, like `rPT1Sjq2YGrBMTttX4GZHjKu9dyf6bpAYe` */
+  userAddress: string;
+};
+
+/**
+ * Parameters for creating a time-locked copy credential on XRPL
+ */
+export type CreateCredentialForCopyParams = {
+  /** Unique identifier for the idOS credential */
+  credId: string;
+  /** Type/category of the credential */
+  credType: string;
+  /** XRPL address of the user receiving the credential */
+  userAddress: string;
+  /** Number of years to lock the credential (must be non-negative integer) */
+  timelockYears: number;
+  /** XRPL address of the original credential issuer */
+  origCredIssuerAddress: string;
+};
+
+/**
+ * Service class for creating credentials on the XRPL blockchain
+ *
+ * This service provides methods to create both original and copy credentials
+ * on the XRPL. It handles connection management, transaction submission,
+ * and proper encoding of credential data according to XRPL specifications.
+ *
+ * @example
+ * ```typescript
+ * const wallet = Wallet.fromSeed("s...");
+ * const xrplService = await XrplCredentialsCreate.init("wss://s.devnet.rippletest.net:51233", wallet);
+ *
+ * // Create original credential
+ * await xrplService.createCredentialForOriginal({
+ *   credId: "741a9caf-ec53-42c7-aed6-519950dcded5",
+ *   credType: "KYC",
+ *   userAddress: "rPT1Sjq2YGrBMTttX4GZHjKu9dyf6bpAYe"
+ * });
+ * ```
+ */
+export class XrplCredentialsCreate {
+  readonly #client: Client;
+  readonly #wallet: Wallet;
+  readonly #xrpl: typeof import("xrpl");
+
+  constructor(nodeUrl: string, wallet: Wallet, xrpl: typeof import("xrpl")) {
+    this.#xrpl = xrpl;
+    this.#wallet = wallet;
+    this.#client = new this.#xrpl.Client(nodeUrl);
+  }
+
+  /**
+   * Creates a new XRPL credentials service instance.
+   *
+   * @param nodeUrl - The WebSocket URL of the XRPL node to connect to
+   * @param wallet  - The XRPL wallet to use for signing transactions
+   */
+  static async init(nodeUrl: string, wallet: Wallet): Promise<XrplCredentialsCreate> {
+    let xrpl: typeof import("xrpl");
+
+    try {
+      xrpl = await import("xrpl");
+    } catch {
+      throw new Error(
+        "Missing optional peer dependency 'xrpl'. Install it to use XrplCredentialsCreate.",
+      );
+    }
+
+    return new XrplCredentialsCreate(nodeUrl, wallet, xrpl);
+  }
+
+  /**
+   * Creates a credential on the XRPL that reflects an idOS original credential.
+   *
+   * This method creates a new credential with the specified type and assigns it to the given user.
+   * The credential type is encoded as a hex string, and the credential ID is encoded as a hex URI.
+   *
+   * @param params - Parameters for creating the original credential
+   * @returns Promise resolving to the XRPL transaction result
+   *
+   * @example
+   * ```typescript
+   * await xrplService.createCredentialForOriginal({
+   *   credId: "741a9caf-ec53-42c7-aed6-519950dcded5",
+   *   credType: "KYC",
+   *   userAddress: "rPT1Sjq2YGrBMTttX4GZHjKu9dyf6bpAYe"
+   * });
+   * ```
+   */
+  async createCredentialForOriginal(
+    params: CreateCredentialForOriginalParams,
+  ): Promise<TxResponse> {
+    const { credId, credType, userAddress } = params;
+
+    // Connect to the XRPL node
+    await this.#client.connect();
+
+    // Submit the credential creation transaction and wait for confirmation
+    const res = await this.#client.submitAndWait(
+      {
+        TransactionType: "CredentialCreate",
+        Account: this.#wallet.address,
+        Subject: userAddress,
+        // Encode credential type as hex string (required by XRPL)
+        CredentialType: hexEncode(utf8Encode(credType)),
+        // Encode credential ID as hex URI (required by XRPL)
+        URI: hexEncode(utf8Encode(credId)),
+      },
+      {
+        wallet: this.#wallet,
+      },
+    );
+
+    // Disconnect from the XRPL node
+    await this.#client.disconnect();
+
+    return res;
+  }
+
+  /**
+   * Creates a time-locked credential copy on the XRPL.
+   *
+   * This method creates a Credential object in XRPL that reflects an idOS credential copy.
+   * The credential type includes metadata about the original issuer and time-lock duration.
+   * The composite credential type follows the format: "AG-{type}-{originalIssuer}-{timelock}Y"
+   *
+   * @param params - Parameters for creating the time-locked credential copy
+   * @returns Promise resolving to the XRPL transaction result
+   *
+   * @throws {Error} When timelockYears is not a non-negative integer
+   *
+   * @example
+   * ```typescript
+   * const result = await xrplService.createCredentialForCopy({
+   *   credId: "741a9caf-ec53-42c7-aed6-519950dcded5",
+   *   credType: "KYC",
+   *   userAddress: "rPT1Sjq2YGrBMTttX4GZHjKu9dyf6bpAYe",
+   *   timelockYears: 5,
+   *   origCredIssuerAddress: "rU9C67bZ3ZvjXaJYwYqMqjMq1o4ZbwK3YN"
+   * });
+   * ```
+   */
+  async createCredentialForCopy(params: CreateCredentialForCopyParams): Promise<TxResponse> {
+    const { credId, credType, userAddress, timelockYears, origCredIssuerAddress } = params;
+
+    // Validate timelockYears is a non-negative integer
+    if (!Number.isInteger(timelockYears) || timelockYears < 0) {
+      throw new Error("timelockYears must be a non-negative integer");
+    }
+
+    // Connect to the XRPL node
+    await this.#client.connect();
+
+    // Create composite credential type with metadata:
+    // Format: "AG-{credType}-{originalIssuer}-{timelock}Y"
+    const type = Buffer.concat([
+      utf8Encode("AG"), // "AG" prefix for copy credentials
+      utf8Encode("-"), // Separator
+      utf8Encode(credType), // Original credential type
+      utf8Encode("-"), // Separator
+      this.#xrpl.decodeAccountID(origCredIssuerAddress), // Original issuer address (decoded)
+      utf8Encode("-"), // Separator
+      utf8Encode(`${timelockYears}Y`), // Timelock period in years
+    ]);
+
+    // Submit the credential copy creation transaction and wait for confirmation
+    const res = await this.#client.submitAndWait(
+      {
+        TransactionType: "CredentialCreate",
+        Account: this.#wallet.address,
+        Subject: userAddress,
+        // Use the composite credential type with metadata
+        CredentialType: hexEncode(type),
+        // Encode credential ID as hex URI (required by XRPL)
+        URI: hexEncode(utf8Encode(credId)),
+      },
+      {
+        wallet: this.#wallet,
+      },
+    );
+
+    // Disconnect from the XRPL node
+    await this.#client.disconnect();
+
+    return res;
+  }
+}

package/src/xrpl-credentials/index.ts

@@ -0,0 +1,12 @@
+/**
+ * XRPL Credentials Module
+ *
+ * This module provides utilities for creating and managing XRPL credential transactions.
+ * It includes functionality for:
+ * - Creating credentials on the XRPL blockchain
+ * - Generating credential acceptance payloads
+ * - Managing both original and copy credentials
+ */
+
+export * from "./accept";
+export * from "./create";

package/tsconfig.json

@@ -0,0 +1,33 @@
+{
+  "compilerOptions": {
+    "target": "ESNext",
+    "lib": ["DOM", "ESNext"],
+    "module": "ESNext",
+    "skipLibCheck": true,
+
+    // Bundler mode
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "noEmit": false,
+    "emitDeclarationOnly": true,
+
+    // Output configuration
+    "declaration": true,
+    "declarationMap": true,
+    "declarationDir": "./dist/types",
+    "isolatedDeclarations": true,
+    "sourceMap": true,
+    "inlineSources": true,
+
+    // Linting
+    "strict": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noFallthroughCasesInSwitch": true,
+    "forceConsistentCasingInFileNames": true,
+    "esModuleInterop": true
+  },
+  "include": ["./src/**/*"]
+}

package/tsdown.config.ts

@@ -0,0 +1,13 @@
+import { defineConfig } from "tsdown";
+
+export default defineConfig({
+  dts: true,
+  entry: [
+    "./src/index.ts",
+    "./src/actions/index.ts",
+    "./src/signature-verification/index.ts",
+    "./src/xrp/utils.ts",
+    "./src/facesign/index.ts",
+    "./src/xrpl-credentials/index.ts",
+  ],
+});

package/vitest.config.ts

@@ -0,0 +1,6 @@
+import { defineConfig } from "vitest/config";
+export default defineConfig({
+  test: {
+    environment: "jsdom",
+  },
+});