@fairblock/stabletrust 2.0.13 → 2.0.15

package/README.md

@@ -63,11 +63,11 @@ The following contract addresses are available for confidential transfers on tes
 
 | Network(Testnet) | Chain ID | Contract Address                             |
 | :--------------- | :------- | :------------------------------------------- |
-| Stable           | 2201     | `0xe1c1456CAb802312759a8cFc3976f88bf87082cf` |
-| Arc              | 5042002  | `0x1B4f05f67CC33788Da4C89a7cd0b2f8E0055E605` |
-| Base             | 84532    | `0x4a251C9D79faCa20b193630A4ee313af7cBCDD93` |
-| Ethereum         | 11155111 | `0x7507a13352AFAa79D33E994f86f2f62463ba8DE4` |
-| Arbitrum         | 421614   | `0x5acECCdeb5CbD3C727eCB49F8706Eb80EF2f977F` |
+| Stable           | 2201     | `0x0b6791C168ffBF52e82F5E862929Dbf505c3A46E` |
+| Arc              | 5042002  | `0xA90621B79d49c8E3A5eeEBcaaa839E2f886240C5` |
+| Base             | 84532    | `0xb6cdAE7ccfEE03e351694c63436D5c5c073aEF84` |
+| Ethereum         | 11155111 | `0x5A061604A1d94f4fa9939544707f6B200d6bB5cf` |
+| Arbitrum         | 421614   | `0x147C6D8cA1a4784Ed76d98b0E3CcA41C38a49A5f` |
 | Tempo            | 42431    | `0xE559fB936C69c46E216bf61B07C16bF1a6d444aa` |
 
 ---

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fairblock/stabletrust",
-  "version": "2.0.13",
+  "version": "2.0.15",
   "description": "SDK for confidential transfers using homomorphic encryption and zero-knowledge proofs",
   "main": "src/index.js",
   "types": "src/withdrawal-fees.d.ts",
@@ -49,7 +49,7 @@
     "@stablelib/chacha20poly1305": "^1.0.1",
     "axios": "^1.16.0",
     "dotenv": "^17.2.3",
-    "ethers": "^6.16.0"
+    "ethers": "^6.17.0"
   },
   "engines": {
     "node": ">=18.0.0"

package/src/backend.js

@@ -2,6 +2,12 @@ import axios from "axios";
 
 const DEFAULT_API_BASE_URL = "https://stabletrust-backend-api.fairblock.network";
 
+// Bound each request-row POST. Callers await these,
+// so without a timeout a slow/hung backend would stall the caller's transfer()
+// even though the on-chain transfer already completed. On timeout axios rejects
+// with ECONNABORTED, which _postRequest turns into a warning.
+const REQUEST_TIMEOUT_MS = 5000;
+
 export const CHAIN_KEY_BY_ID = {
   2201: "stable",
   5042002: "arc",
@@ -16,5 +22,7 @@ export const CHAIN_KEY_BY_ID = {
  * POST /api/requests — create a request row
  */
 export async function createRequest(requestData, apiBaseUrl = DEFAULT_API_BASE_URL) {
-  await axios.post(`${apiBaseUrl}/api/requests`, requestData);
+  await axios.post(`${apiBaseUrl}/api/requests`, requestData, {
+    timeout: REQUEST_TIMEOUT_MS,
+  });
 }

package/src/confidential-client.js

@@ -121,7 +121,10 @@ export class ConfidentialTransferClient {
   }
 
   /**
-   * Fire-and-forget request row creation
+   * Post a request row. Returns the createRequest promise (which resolves even
+   * on failure - errors are logged and swallowed) so callers that need the row
+   * to exist before returning (e.g. confidentialTransfer) can `await` it.
+   * Callers that don't await keep the old fire-and-forget behavior.
    * @private
    */
   _postRequest(data) {
@@ -132,7 +135,7 @@ export class ConfidentialTransferClient {
       applicationName: this.config.applicationName,
       ...data,
     };
-    createRequest(payload, apiBaseUrl).catch((err) => {
+    return createRequest(payload, apiBaseUrl).catch((err) => {
       const status = err?.response?.status;
       const body = err?.response?.data;
       console.warn("[StableTrust] Failed to post request:", err.message);
@@ -882,67 +885,72 @@ export class ConfidentialTransferClient {
       ]);
       const tokenSymbol = await tokenContract.symbol();
 
-      Promise.all([
-        encryptRandomness(senderAddress, proof.data.sender_randomness),
-        encryptRandomness(recipientAddress, proof.data.receiver_randomness),
-      ])
-        .then(([senderEnc, receiverEnc]) => {
-          const transferDetails = {
-            sender: senderAddress.toLowerCase(),
-            recipient: recipientAddress.toLowerCase(),
-            token: tokenSymbol,
-            tokenAddress,
-          };
-
-          const queuedFields =
-            senderEnc.queuedEncrypted && receiverEnc.queuedEncrypted
-              ? {
-                  queuedEncryptedSenderRandomness: senderEnc.queuedEncrypted,
-                  queuedEncryptedSenderRandomnessId:
-                    senderEnc.queuedEncryptedId,
-                  queuedEncryptedReceiverRandomness:
-                    receiverEnc.queuedEncrypted,
-                  queuedEncryptedReceiverRandomnessId:
-                    receiverEnc.queuedEncryptedId,
-                }
-              : {};
-
-          this._postRequest({
-            requestId,
-            userAddress: senderAddress.toLowerCase(),
-            operationKind: 2,
-            type: "transfer",
-            transactionHash: txHash,
-            status: "pending",
-            details: transferDetails,
-            encryptedSenderRandomness: senderEnc.encrypted,
-            encryptedSenderRandomnessId: senderEnc.encryptedId,
-            encryptedReceiverRandomness: receiverEnc.encrypted,
-            encryptedReceiverRandomnessId: receiverEnc.encryptedId,
-            ...queuedFields,
-          });
-
-          this._postRequest({
-            requestId: `received-${requestId}-${recipientAddress.toLowerCase()}`,
-            userAddress: recipientAddress.toLowerCase(),
-            operationKind: 2,
-            type: "received",
-            transactionHash: txHash,
-            status: "pending",
-            details: transferDetails,
-            encryptedReceiverRandomness: receiverEnc.encrypted,
-            encryptedReceiverRandomnessId: receiverEnc.encryptedId,
-            ...(receiverEnc.queuedEncrypted
-              ? {
-                  queuedEncryptedReceiverRandomness:
-                    receiverEnc.queuedEncrypted,
-                  queuedEncryptedReceiverRandomnessId:
-                    receiverEnc.queuedEncryptedId,
-                }
-              : {}),
-          });
-        })
-        .catch(() => {});
+      let senderEnc = null;
+      let receiverEnc = null;
+      try {
+        [senderEnc, receiverEnc] = await Promise.all([
+          encryptRandomness(senderAddress, proof.data.sender_randomness),
+          encryptRandomness(recipientAddress, proof.data.receiver_randomness),
+        ]);
+      } catch (encErr) {
+        console.warn(
+          `[StableTrust] Transfer ${txHash} Failed to get IBE Randomness (${encErr?.message ?? encErr}). `,
+        );
+      }
+
+      if (senderEnc && receiverEnc) {
+        const transferDetails = {
+          sender: senderAddress.toLowerCase(),
+          recipient: recipientAddress.toLowerCase(),
+          token: tokenSymbol,
+          tokenAddress,
+        };
+
+        const queuedFields =
+          senderEnc.queuedEncrypted && receiverEnc.queuedEncrypted
+            ? {
+                queuedEncryptedSenderRandomness: senderEnc.queuedEncrypted,
+                queuedEncryptedSenderRandomnessId: senderEnc.queuedEncryptedId,
+                queuedEncryptedReceiverRandomness: receiverEnc.queuedEncrypted,
+                queuedEncryptedReceiverRandomnessId:
+                  receiverEnc.queuedEncryptedId,
+              }
+            : {};
+
+        await this._postRequest({
+          requestId,
+          userAddress: senderAddress.toLowerCase(),
+          operationKind: 2,
+          type: "transfer",
+          transactionHash: txHash,
+          status: "pending",
+          details: transferDetails,
+          encryptedSenderRandomness: senderEnc.encrypted,
+          encryptedSenderRandomnessId: senderEnc.encryptedId,
+          encryptedReceiverRandomness: receiverEnc.encrypted,
+          encryptedReceiverRandomnessId: receiverEnc.encryptedId,
+          ...queuedFields,
+        });
+
+        await this._postRequest({
+          requestId: `received-${requestId}-${recipientAddress.toLowerCase()}`,
+          userAddress: recipientAddress.toLowerCase(),
+          operationKind: 2,
+          type: "received",
+          transactionHash: txHash,
+          status: "pending",
+          details: transferDetails,
+          encryptedReceiverRandomness: receiverEnc.encrypted,
+          encryptedReceiverRandomnessId: receiverEnc.encryptedId,
+          ...(receiverEnc.queuedEncrypted
+            ? {
+                queuedEncryptedReceiverRandomness: receiverEnc.queuedEncrypted,
+                queuedEncryptedReceiverRandomnessId:
+                  receiverEnc.queuedEncryptedId,
+              }
+            : {}),
+        });
+      }
 
       if (waitForFinalization) {
         await this._waitForGlobalState(senderAddress, "transfer");

package/src/constants.js

@@ -2,15 +2,25 @@
  * Contract ABIs and Constants
  */
 
-const CREATE_CONFIDENTIAL_ACCOUNT_SIGNATURE = "createConfidentialAccount(bytes)";
-const DEPOSIT_SIGNATURE = "deposit(address,uint256)";
+export const PREDICATE_ATTESTATION_SIGNATURE =
+  "(string,uint256,address,bytes)";
+const PREDICATE_ATTESTATION_ABI =
+  "(string uuid,uint256 expiration,address attester,bytes signature) attestation";
+
+export const CREATE_CONFIDENTIAL_ACCOUNT_SIGNATURE =
+  `createConfidentialAccount(bytes,${PREDICATE_ATTESTATION_SIGNATURE})`;
+export const DEPOSIT_SIGNATURE =
+  `deposit(address,uint256,${PREDICATE_ATTESTATION_SIGNATURE})`;
 const GET_ACCOUNT_CORE_SIGNATURE = "getAccountCore(address)";
 const GET_AVAILABLE_SIGNATURE = "getAvailable(address,address)";
 const GET_PENDING_SIGNATURE = "getPending(address,address)";
-const APPLY_PENDING_SIGNATURE = "applyPending()";
+export const APPLY_PENDING_SIGNATURE =
+  `applyPending(${PREDICATE_ATTESTATION_SIGNATURE})`;
 
-export const TRANSFER_CONFIDENTIAL_SIGNATURE = "transferConfidential(address,address,bytes,bool)";
-export const WITHDRAW_CONFIDENTIAL_SIGNATURE = "withdraw(address,uint256,bytes,bool)";
+export const TRANSFER_CONFIDENTIAL_SIGNATURE =
+  `transferConfidential(address,address,bytes,bool,${PREDICATE_ATTESTATION_SIGNATURE})`;
+export const WITHDRAW_CONFIDENTIAL_SIGNATURE =
+  `withdraw(address,uint256,bytes,bool,${PREDICATE_ATTESTATION_SIGNATURE})`;
 export const FEE_TOKEN_SIGNATURE = "feeToken()";
 export const FEE_ACCOUNT_SIGNATURE = "feeAccount()";
 export const NON_ANONYMOUS_TRANSFER_FEE_SIGNATURE = "nonAnonymousTransferFee()";
@@ -21,14 +31,14 @@ export const ANONYMOUS_INLINE_TRANSFER_FEE_SIGNATURE = "anonymousInlineTransferF
 export const ANONYMOUS_WITHDRAW_FEE_PPM_SIGNATURE = "anonymousWithdrawFeePpm()";
 
 export const CONTRACT_ABI = [
-  `function ${CREATE_CONFIDENTIAL_ACCOUNT_SIGNATURE} external`,
-  `function ${DEPOSIT_SIGNATURE} external`,
+  `function createConfidentialAccount(bytes elgamalPubkey,${PREDICATE_ATTESTATION_ABI}) external`,
+  `function deposit(address token,uint256 plainAmount,${PREDICATE_ATTESTATION_ABI}) external`,
   `function ${GET_ACCOUNT_CORE_SIGNATURE} external view returns ((bool exists, bool finalized, bool pendingAction, uint256 txId, bytes elgamalPubkey, uint64 pendingCreditCounter))`,
   `function ${GET_AVAILABLE_SIGNATURE} external view returns (bytes c1, bytes c2)`,
   `function ${GET_PENDING_SIGNATURE} external view returns (bytes c1, bytes c2)`,
-  `function ${TRANSFER_CONFIDENTIAL_SIGNATURE} external payable`,
-  `function ${WITHDRAW_CONFIDENTIAL_SIGNATURE} external payable`,
-  `function ${APPLY_PENDING_SIGNATURE} external`,
+  `function transferConfidential(address recipient,address token,bytes proof,bool offchainZKP,${PREDICATE_ATTESTATION_ABI}) external payable`,
+  `function withdraw(address token,uint256 plainAmount,bytes proof,bool offchainZKP,${PREDICATE_ATTESTATION_ABI}) external payable`,
+  `function applyPending(${PREDICATE_ATTESTATION_ABI}) external`,
   `function ${FEE_TOKEN_SIGNATURE} external view returns (address)`,
   `function ${FEE_ACCOUNT_SIGNATURE} external view returns (address)`,
   `function ${NON_ANONYMOUS_TRANSFER_FEE_SIGNATURE} external view returns (uint256)`,
@@ -63,11 +73,11 @@ export const ERC20_ABI = [
 export const TEMPO_FEE_TOKEN_ADDRESS =
   "0x20c0000000000000000000000000000000000000";
 export const STABLETRUST_CONTRACTS_BY_CHAIN_ID = Object.freeze({
-  2201: "0xe1c1456CAb802312759a8cFc3976f88bf87082cf", //Stable
-  5042002: "0x1B4f05f67CC33788Da4C89a7cd0b2f8E0055E605", //Arc
-  84532: "0x4a251C9D79faCa20b193630A4ee313af7cBCDD93", //Base
-  11155111: "0x7507a13352AFAa79D33E994f86f2f62463ba8DE4", //Ethereum
-  421614: "0x5acECCdeb5CbD3C727eCB49F8706Eb80EF2f977F", //Arbitrum
+  2201: "0x0b6791C168ffBF52e82F5E862929Dbf505c3A46E", //Stable
+  5042002: "0xA90621B79d49c8E3A5eeEBcaaa839E2f886240C5", //Arc
+  84532: "0xb6cdAE7ccfEE03e351694c63436D5c5c073aEF84", //Base
+  11155111: "0x5A061604A1d94f4fa9939544707f6B200d6bB5cf", //Ethereum
+  421614: "0x147C6D8cA1a4784Ed76d98b0E3CcA41C38a49A5f", //Arbitrum Sepolia
   42431: "0xE559fB936C69c46E216bf61B07C16bF1a6d444aa", //Tempo
   42161: "0xCAA6384D5Ac8b9111D482dd676BB890f2b6e9513", //Arbitrum One (mainnet)
 });

package/src/ibe.js

@@ -3,6 +3,14 @@ import { timelockEncrypt } from "./vendor/ts-ibe/index.js";
 const IBE_PUBKEY_URL =
   "https://anon-testnet-api.fairblock.network/fairyring/keyshare/pubkey";
 
+// Bound the IBE public-key fetch. Without this, a slow or hung endpoint (a
+// socket that accepts the connection but never responds) would block the fetch
+// indefinitely, and because confidentialTransfer awaits encryptRandomness that
+// stall propagates to the caller's transfer() call even though the on-chain
+// transfer already happened. On timeout the fetch aborts and encryptRandomness
+// rejects, which the caller handles as "dashboard record skipped".
+const IBE_FETCH_TIMEOUT_MS = 5000;
+
 /** @type {{ active: string, queued: string | null } | null} */
 let cachedIbePublicKeys = null;
 
@@ -23,9 +31,22 @@ function buildIbeId(userAddress, publicKey) {
 async function getIbePublicKeys() {
   if (cachedIbePublicKeys) return cachedIbePublicKeys;
 
-  const response = await fetch(IBE_PUBKEY_URL, {
-    headers: { Accept: "application/json" },
-  });
+  let response;
+  try {
+    response = await fetch(IBE_PUBKEY_URL, {
+      headers: { Accept: "application/json" },
+      signal: AbortSignal.timeout(IBE_FETCH_TIMEOUT_MS),
+    });
+  } catch (err) {
+    if (err?.name === "TimeoutError" || err?.name === "AbortError") {
+      throw new Error(
+        `IBE public key fetch timed out after ${IBE_FETCH_TIMEOUT_MS}ms`,
+      );
+    }
+    throw new Error(
+      `IBE public key fetch failed: ${err?.message ?? err}`,
+    );
+  }
 
   if (!response.ok) {
     throw new Error(

package/src/index.js

@@ -3,7 +3,7 @@ export {
   ControlledConfidentialTransferClient,
   AnonymousTransferClient,
   WITHDRAW_FEE_PPM_DENOMINATOR,
-} from "./fee-aware-clients.js";
+} from "./predicate-fee-aware-clients.js";
 export { deriveKeys, decryptCiphertext, combineCiphertext } from "./crypto.js";
 export {
   encodeTransferProof,
@@ -14,7 +14,11 @@ export {
 export {
   CONTRACT_ABI,
   ERC20_ABI,
+  PREDICATE_ATTESTATION_SIGNATURE,
+  CREATE_CONFIDENTIAL_ACCOUNT_SIGNATURE,
+  DEPOSIT_SIGNATURE,
   TRANSFER_CONFIDENTIAL_SIGNATURE,
+  APPLY_PENDING_SIGNATURE,
   WITHDRAW_CONFIDENTIAL_SIGNATURE,
   FEE_TOKEN_SIGNATURE,
   FEE_ACCOUNT_SIGNATURE,
@@ -27,4 +31,9 @@ export {
   STABLETRUST_CONTRACTS_BY_CHAIN_ID,
   getStabletrustContractAddress,
 } from "./constants.js";
+export {
+  emptyPredicateAttestation,
+  injectPredicateAttestation,
+  isPredicateAttestation,
+} from "./predicate-contract.js";
 // Note: initializeWasm is now internal - WASM auto-initializes on first client use

package/src/predicate-contract.js

@@ -0,0 +1,126 @@
+import { ethers } from "ethers";
+
+const PREDICATE_BUSINESS_ARG_COUNTS = Object.freeze({
+  createConfidentialAccount: 1,
+  deposit: 2,
+  transferConfidential: 4,
+  applyPending: 0,
+  withdraw: 4,
+});
+
+const METHOD_HELPERS = [
+  "estimateGas",
+  "populateTransaction",
+  "send",
+  "staticCall",
+  "staticCallResult",
+];
+
+const PREDICATE_WRAPPED = Symbol("stabletrust.predicateWrappedContract");
+
+/**
+ * Empty Predicate attestation used while on-chain Predicate enforcement is off.
+ * A fresh array is returned for each call so callers/ethers never share mutable
+ * tuple state between transactions.
+ */
+export function emptyPredicateAttestation() {
+  return ["", 0n, ethers.ZeroAddress, "0x"];
+}
+
+export function isPredicateAttestation(value) {
+  if (Array.isArray(value)) return value.length === 4;
+  if (!value || typeof value !== "object") return false;
+  return (
+    "uuid" in value &&
+    "expiration" in value &&
+    "attester" in value &&
+    "signature" in value
+  );
+}
+
+/**
+ * Convert the pre-Predicate SDK call shape into the upgraded Diamond call shape.
+ * Existing SDK methods may optionally append an ethers transaction-overrides
+ * object, so the attestation must be inserted immediately before overrides.
+ *
+ * Calls that already contain an explicit attestation are left unchanged. This
+ * makes the wrapped contract usable directly by applications that obtain a real
+ * Predicate attestation later.
+ */
+export function injectPredicateAttestation(methodName, args) {
+  const businessArgCount = PREDICATE_BUSINESS_ARG_COUNTS[methodName];
+  if (businessArgCount === undefined) return args;
+
+  if (args.length === businessArgCount) {
+    return [...args, emptyPredicateAttestation()];
+  }
+
+  if (args.length === businessArgCount + 1) {
+    if (isPredicateAttestation(args[businessArgCount])) {
+      return args;
+    }
+    return [
+      ...args.slice(0, businessArgCount),
+      emptyPredicateAttestation(),
+      args[businessArgCount],
+    ];
+  }
+
+  if (
+    args.length === businessArgCount + 2 &&
+    isPredicateAttestation(args[businessArgCount])
+  ) {
+    return args;
+  }
+
+  // Let ethers surface its normal argument-count/type error for malformed calls.
+  return args;
+}
+
+function wrapPredicateMethod(methodName, method) {
+  const wrapped = (...args) =>
+    method(...injectPredicateAttestation(methodName, args));
+
+  for (const helperName of METHOD_HELPERS) {
+    const helper = method?.[helperName];
+    if (typeof helper === "function") {
+      wrapped[helperName] = (...args) =>
+        helper(...injectPredicateAttestation(methodName, args));
+    }
+  }
+
+  return wrapped;
+}
+
+/**
+ * Wrap an ethers Contract so the SDK's existing high-level methods keep their
+ * public API while targeting the upgraded Attestation-bearing selectors.
+ *
+ * `connect()` is wrapped recursively because every state-changing SDK path uses
+ * `this.contract.connect(wallet)` before invoking the contract.
+ */
+export function wrapPredicateContract(contract) {
+  if (!contract || contract[PREDICATE_WRAPPED]) return contract;
+
+  return new Proxy(contract, {
+    get(target, prop) {
+      if (prop === PREDICATE_WRAPPED) return true;
+
+      if (prop === "connect") {
+        return (runner) => wrapPredicateContract(target.connect(runner));
+      }
+
+      if (
+        typeof prop === "string" &&
+        Object.prototype.hasOwnProperty.call(PREDICATE_BUSINESS_ARG_COUNTS, prop)
+      ) {
+        const method = target[prop];
+        if (typeof method === "function") {
+          return wrapPredicateMethod(prop, method);
+        }
+      }
+
+      return Reflect.get(target, prop, target);
+    },
+  });
+}

package/src/predicate-fee-aware-clients.js

@@ -0,0 +1,31 @@
+import {
+  ConfidentialTransferClient as FeeAwareConfidentialTransferClient,
+  ControlledConfidentialTransferClient as FeeAwareControlledConfidentialTransferClient,
+  AnonymousTransferClient,
+  WITHDRAW_FEE_PPM_DENOMINATOR,
+} from "./fee-aware-clients.js";
+import { wrapPredicateContract } from "./predicate-contract.js";
+
+/**
+ * Public non-anonymous clients target the upgraded ConfidentialMirror ABI.
+ * Existing SDK methods still call the pre-Predicate argument shape internally;
+ * the wrapped ethers Contract inserts an empty attestation while enforcement is
+ * disabled, without changing the high-level SDK API.
+ */
+export class ConfidentialTransferClient extends FeeAwareConfidentialTransferClient {
+  constructor(...args) {
+    super(...args);
+    this.contract = wrapPredicateContract(this.contract);
+  }
+}
+
+export class ControlledConfidentialTransferClient extends FeeAwareControlledConfidentialTransferClient {
+  constructor(...args) {
+    super(...args);
+    this.contract = wrapPredicateContract(this.contract);
+  }
+}
+
+// Anonymous flows are intentionally not Predicate-gated and must remain
+// byte-for-byte/API compatible with the existing anonymous client behavior.
+export { AnonymousTransferClient, WITHDRAW_FEE_PPM_DENOMINATOR };