@fairblock/stabletrust 2.0.6 → 2.0.10

package/src/constants.js

@@ -2,16 +2,42 @@
  * Contract ABIs and Constants
  */
 
+const CREATE_CONFIDENTIAL_ACCOUNT_SIGNATURE = "createConfidentialAccount(bytes)";
+const DEPOSIT_SIGNATURE = "deposit(address,uint256)";
+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 TRANSFER_CONFIDENTIAL_SIGNATURE = "transferConfidential(address,address,bytes,bool)";
+export const WITHDRAW_CONFIDENTIAL_SIGNATURE = "withdraw(address,uint256,bytes,bool)";
+export const FEE_TOKEN_SIGNATURE = "feeToken()";
+export const NON_ANONYMOUS_TRANSFER_FEE_SIGNATURE = "nonAnonymousTransferFee()";
+export const ANONYMOUS_IPFS_TRANSFER_FEE_SIGNATURE = "anonymousIpfsTransferFee()";
+export const ANONYMOUS_INLINE_TRANSFER_FEE_SIGNATURE = "anonymousInlineTransferFee()";
+
 export const CONTRACT_ABI = [
-  "function createConfidentialAccount(bytes elgamalPubkey) external",
-  "function deposit(address token, uint256 plainAmount) external",
-  "function getAccountCore(address ownerAddr) external view returns ((bool exists, bool finalized, bool pendingAction, uint256 txId, bytes elgamalPubkey, uint64 pendingCreditCounter))",
-  "function getAvailable(address ownerAddr, address token) external view returns (bytes c1, bytes c2)",
-  "function getPending(address ownerAddr, address token) external view returns (bytes c1, bytes c2)",
-  "function transferConfidential(address recipient, address token, bytes proof) external payable",
-  "function withdraw(address token, uint256 plainAmount, bytes proof) external",
-  "function applyPending() external",
-  "function feeAmount() external view returns (uint256)",
+  `function ${CREATE_CONFIDENTIAL_ACCOUNT_SIGNATURE} external`,
+  `function ${DEPOSIT_SIGNATURE} 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`,
+  `function ${APPLY_PENDING_SIGNATURE} external`,
+  `function ${FEE_TOKEN_SIGNATURE} external view returns (address)`,
+  `function ${NON_ANONYMOUS_TRANSFER_FEE_SIGNATURE} external view returns (uint256)`,
+  `function ${ANONYMOUS_IPFS_TRANSFER_FEE_SIGNATURE} external view returns (uint256)`,
+  `function ${ANONYMOUS_INLINE_TRANSFER_FEE_SIGNATURE} external view returns (uint256)`,
+  // Events used to extract request/tx IDs from receipts for backend persistence
+  "event DepositRequested(address indexed ownerAddr, uint256 indexed txId, address indexed token, uint256 plainAmount, bytes availableShare, bytes pendingShare)",
+  "event DepositProcessed(address indexed ownerAddr, uint256 indexed txId, bool ok, string errorMsg, address token, bytes newAvailC1, bytes newAvailC2, uint64 pendingCreditCounter, uint64 minimumPendingCreditCounter, bytes availableShare, bytes pendingShare)",
+  "event TransferRequested(address indexed sender, address indexed recipient, uint256 indexed txId, address token, bytes proof, uint256 feePaid, bool useOffchainVerify, bytes senderPubkey, bytes recipientPubkey, bytes senderCurrC1, bytes senderCurrC2)",
+  "event TransferProcessed(address indexed sender, address indexed recipient, uint256 indexed txId, bool ok, string errorMsg, address token, bytes senderNewAvailC1, bytes senderNewAvailC2, bytes recipientNewPendingC1, bytes recipientNewPendingC2, uint64 senderPendingCreditCounter, bytes senderAvailableShare, uint64 recipientPendingCreditCounter, uint64 recipientMinimumPendingCreditCounter, bytes recipientPendingShare)",
+  "event ApplyPendingRequested(address indexed ownerAddr, uint256 indexed txId)",
+  "event ApplyPendingProcessed(address indexed ownerAddr, uint256 indexed txId, bool ok, string errorMsg, address[] tokens, bytes[] newAvailC1, bytes[] newAvailC2, uint64 pendingCreditCounter, uint64 minimumPendingCreditCounter, bytes availableShare)",
+  "event WithdrawRequested(address indexed ownerAddr, uint256 indexed txId, address token, uint256 plainAmount, bytes proof, bool useOffchainVerify, bytes userPubkey, bytes userCurrC1, bytes userCurrC2)",
+  "event WithdrawProcessed(address indexed ownerAddr, uint256 indexed txId, bool ok, string errorMsg, address token, uint256 plainAmount, bytes newAvailC1, bytes newAvailC2, uint64 pendingCreditCounter, uint64 minimumPendingCreditCounter, bytes availableShare)",
 ];
 
 export const ERC20_ABI = [
@@ -19,6 +45,7 @@ export const ERC20_ABI = [
   "function allowance(address owner, address spender) external view returns (uint256)",
   "function balanceOf(address account) external view returns (uint256)",
   "function decimals() external view returns (uint8)",
+  "function symbol() external view returns (string)",
 ];
 
 export const TEMPO_FEE_TOKEN_ADDRESS =

package/src/ibe.js

@@ -0,0 +1,59 @@
+import { timelockEncrypt } from "./vendor/ts-ibe/index.js";
+
+const IBE_PUBKEY_URL =
+  "https://anon-testnet-api.fairblock.network/fairyring/keyshare/pubkey";
+
+/** @type {{ active: string, queued: string | null } | null} */
+let cachedIbePublicKeys = null;
+
+function extractPublicKey(pubkeyObj) {
+  return pubkeyObj?.public_key || pubkeyObj?.pubkey || null;
+}
+
+async function getIbePublicKeys() {
+  if (cachedIbePublicKeys) return cachedIbePublicKeys;
+
+  const response = await fetch(IBE_PUBKEY_URL, {
+    headers: { Accept: "application/json" },
+  });
+
+  if (!response.ok) {
+    throw new Error(
+      `Failed to fetch IBE public key: ${response.status} ${response.statusText}`,
+    );
+  }
+
+  const data = await response.json();
+  const active = extractPublicKey(data?.active_pubkey);
+  const queued = extractPublicKey(data?.queued_pubkey);
+
+  if (!active) {
+    throw new Error("Active IBE public key not found in chain API response");
+  }
+
+  cachedIbePublicKeys = { active, queued: queued || null };
+  return cachedIbePublicKeys;
+}
+
+/**
+ * Encrypts a base64-encoded randomness (PedersenOpening) using IBE.
+ * Always encrypts under the active pubkey; also encrypts under the queued
+ * pubkey when the chain reports one (backup for key rotation).
+ *
+ * @param {string} userAddress - Wallet address used as the IBE identity
+ * @param {string} randomnessBase64 - Base64-encoded randomness
+ * @returns {Promise<{ encrypted: string, queuedEncrypted: string | null }>}
+ *   Hex-encoded IBE ciphertexts
+ */
+export async function encryptRandomness(userAddress, randomnessBase64) {
+  const { active, queued } = await getIbePublicKeys();
+  const id = userAddress.toLowerCase();
+  const randomnessBuffer = Buffer.from(randomnessBase64, "base64");
+
+  const [encrypted, queuedEncrypted] = await Promise.all([
+    timelockEncrypt(id, active, randomnessBuffer),
+    queued ? timelockEncrypt(id, queued, randomnessBuffer) : Promise.resolve(null),
+  ]);
+
+  return { encrypted, queuedEncrypted };
+}

package/src/index.d.ts

@@ -14,6 +14,16 @@ declare module "@fairblock/stabletrust" {
     diamondAddress?: string;
     /** Optional API key for Fairycloak */
     apiKey?: string;
+    /** StableTrust IPFS upload endpoint, used when a transfer sets `offchainZKP: true`.
+     * Falls back to `STABLETRUST_IPFS_UPLOAD_URL` in Node.js when omitted.
+     */
+    ipfsUploadUrl?: string;
+    /** Optional bearer token for the StableTrust IPFS upload endpoint.
+     * Falls back to `STABLETRUST_IPFS_API_KEY` in Node.js when omitted.
+     */
+    ipfsApiKey?: string;
+    /** Optional read gateway base URL, e.g. `https://ipfs.example.com`. */
+    ipfsGatewayUrl?: string;
   }
 
   export interface AnonymousAccountInfo {
@@ -81,6 +91,11 @@ declare module "@fairblock/stabletrust" {
     amount?: bigint | string | number;
     /** Recipient ElGamal public key (base64). Auto-resolved from the chain if omitted. */
     destinationPublicKey?: string;
+    /**
+     * When true, the ZK proof is uploaded to StableTrust IPFS and only its CID is put on-chain,
+     * instead of sending the full proof inline. Requires `ipfsUploadUrl`/`ipfsApiKey` config or the StableTrust IPFS environment variables.
+     */
+    offchainZKP?: boolean;
   }
 
   export interface TransferToAnonymousParams {
@@ -94,6 +109,11 @@ declare module "@fairblock/stabletrust" {
     amount?: bigint | string | number;
     /** Recipient ElGamal public key (base64). Auto-resolved from the chain if omitted. */
     destinationPublicKey?: string;
+    /**
+     * When true, the ZK proof is uploaded to StableTrust IPFS and only its CID is put on-chain,
+     * instead of sending the full proof inline. Requires `ipfsUploadUrl`/`ipfsApiKey` config or the StableTrust IPFS environment variables.
+     */
+    offchainZKP?: boolean;
   }
 
   export interface WithdrawParams {
@@ -105,6 +125,11 @@ declare module "@fairblock/stabletrust" {
     proof?: string;
     /** ElGamal private key (base64) for auto-proof generation. Contract scale is derived automatically. */
     elGamalPrivateKey?: string;
+    /**
+     * When true, the ZK proof is uploaded to StableTrust IPFS and only its CID is put on-chain,
+     * instead of sending the full proof inline. Requires `ipfsUploadUrl`/`ipfsApiKey` config or `STABLETRUST_IPFS_UPLOAD_URL` / `STABLETRUST_IPFS_API_KEY`. Defaults to false.
+     */
+    offchainZKP?: boolean;
   }
 
   export interface AnonymousAccountBalance {
@@ -263,14 +288,17 @@ declare module "@fairblock/stabletrust" {
      */
     getFeeToken(): Promise<string>;
 
-    /**
-     * Get the protocol fee amount in raw ERC-20 units of the fee token.
-     * This is the amount deducted per anonymous transfer. Returns 0n if no fee is set.
-     */
-    getFeeAmount(): Promise<bigint>;
+    /** Get the fixed fee used by all non-anonymous confidential transfers. */
+    getNonAnonymousTransferFee(): Promise<bigint>;
+
+    /** Get the fixed fee used by anonymous transfers whose proof is stored on IPFS. */
+    getAnonymousIpfsTransferFee(): Promise<bigint>;
+
+    /** Get the fixed fee used by anonymous transfers whose proof is submitted inline. */
+    getAnonymousInlineTransferFee(): Promise<bigint>;
 
     /**
-     * Get the prepaid fee balance for an anonymous account and token (raw ERC-20 units).
+     * Get the prepaid fee balance for an anonymous account and token (raw fee-token units).
      * Use `getFeeToken()` to get the active fee token address.
      */
     getPrepaidFeeBalance(accountId: string, token: string): Promise<bigint>;
@@ -283,9 +311,10 @@ declare module "@fairblock/stabletrust" {
      * Handles ERC-20 approval automatically.
      *
      * The fee token is read from the contract — use `getFeeToken()` to see it.
-     * Use `getFeeAmount()` to see how much is deducted per transfer.
+     * Use `getAnonymousInlineTransferFee()` or `getAnonymousIpfsTransferFee()`
+     * to see how much is deducted for the selected proof path.
      *
-     * @param amount Amount in raw ERC-20 units of the active fee token
+     * @param amount Amount in raw units of the active fee token (wei for native currency)
      */
     depositFees(
       authWallet: ethers.Wallet,
@@ -458,7 +487,7 @@ declare module "@fairblock/stabletrust" {
    * Balance information
    */
   export interface Balance {
-    amount: number;
+    amount: bigint;
     ciphertext: string | null;
   }
 
@@ -466,7 +495,7 @@ declare module "@fairblock/stabletrust" {
    * Confidential balance summary
    */
   export interface ConfidentialBalance {
-    amount: number;
+    amount: bigint;
     available: Balance;
     pending: Balance;
   }
@@ -490,6 +519,14 @@ declare module "@fairblock/stabletrust" {
    * Transfer options
    */
   export interface TransferOptions {
+    /**
+     * When true, upload the ABI-encoded transfer proof to StableTrust IPFS and
+     * submit only the bare CID bytes on-chain with offchainZKP=true.
+     * Defaults to true on Tempo (chainId 42431) for backwards compatibility,
+     * and false on other chains.
+     */
+    offchainZKP?: boolean;
+    /** @deprecated Use offchainZKP instead. */
     useOffchainVerify?: boolean;
     waitForFinalization?: boolean;
   }
@@ -498,10 +535,27 @@ declare module "@fairblock/stabletrust" {
    * Withdraw options
    */
   export interface WithdrawOptions {
+    /**
+     * When true, upload the ABI-encoded withdraw proof to StableTrust IPFS and
+     * submit only the bare CID bytes on-chain with offchainZKP=true.
+     * Defaults to true on Tempo (chainId 42431) for backwards compatibility,
+     * and false on other chains.
+     */
+    offchainZKP?: boolean;
+    /** @deprecated Use offchainZKP instead. */
     useOffchainVerify?: boolean;
     waitForFinalization?: boolean;
   }
 
+  export interface StableTrustIpfsOptions {
+    /** StableTrust IPFS upload endpoint. Falls back to STABLETRUST_IPFS_UPLOAD_URL in Node.js. */
+    ipfsUploadUrl?: string;
+    /** Optional bearer token for the StableTrust IPFS upload endpoint. Falls back to STABLETRUST_IPFS_API_KEY in Node.js. */
+    ipfsApiKey?: string;
+    /** StableTrust backend API base URL for persisting request rows. Defaults to the production API. */
+    apiBaseUrl?: string;
+  }
+
   /**
    * Main SDK client class
    * WASM auto-initializes on first use - no manual initialization required!
@@ -512,7 +566,7 @@ declare module "@fairblock/stabletrust" {
      * @param rpcUrl RPC endpoint URL
      * @param chainId Chain ID (uses default Stabletrust contract for known networks)
      */
-    constructor(rpcUrl: string, chainId: number);
+    constructor(rpcUrl: string, chainId: number, options?: StableTrustIpfsOptions);
 
     /**
      * Create a new ConfidentialTransferClient
@@ -520,7 +574,7 @@ declare module "@fairblock/stabletrust" {
      * @param contractAddress Confidential transfer contract address
      * @param chainId Chain ID
      */
-    constructor(rpcUrl: string, contractAddress: string, chainId: number);
+    constructor(rpcUrl: string, contractAddress: string, chainId: number, options?: StableTrustIpfsOptions);
 
     /**
      * Get account information from the contract
@@ -574,7 +628,7 @@ declare module "@fairblock/stabletrust" {
       senderWallet: ethers.Wallet | ethers.Signer,
       recipientAddress: string,
       tokenAddress: string,
-      amount: number,
+      amount: bigint | string | number,
       options?: TransferOptions,
     ): Promise<ethers.ContractTransactionReceipt>;
 
@@ -588,14 +642,21 @@ declare module "@fairblock/stabletrust" {
     withdraw(
       wallet: ethers.Wallet | ethers.Signer,
       tokenAddress: string,
-      amount: number,
+      amount: bigint | string | number,
       options?: WithdrawOptions,
     ): Promise<ethers.ContractTransactionReceipt>;
 
-    /**
-     * Get the current fee amount for confidential transfers
-     */
-    getFeeAmount(): Promise<bigint>;
+    /** Get the currently configured fee token. address(0) means native currency. */
+    getFeeToken(): Promise<string>;
+
+    /** Get the fixed fee used by all non-anonymous confidential transfers. */
+    getNonAnonymousTransferFee(): Promise<bigint>;
+
+    /** Get the fixed fee used by anonymous transfers whose proof is stored on IPFS. */
+    getAnonymousIpfsTransferFee(): Promise<bigint>;
+
+    /** Get the fixed fee used by anonymous transfers whose proof is submitted inline. */
+    getAnonymousInlineTransferFee(): Promise<bigint>;
 
     /**
      * Get the public ERC20 balance for an address (for comparison with confidential balance)
@@ -674,6 +735,12 @@ declare module "@fairblock/stabletrust" {
   /**
    * Contract ABI
    */
+  export const TRANSFER_CONFIDENTIAL_SIGNATURE: string;
+  export const WITHDRAW_CONFIDENTIAL_SIGNATURE: string;
+  export const FEE_TOKEN_SIGNATURE: string;
+  export const NON_ANONYMOUS_TRANSFER_FEE_SIGNATURE: string;
+  export const ANONYMOUS_IPFS_TRANSFER_FEE_SIGNATURE: string;
+  export const ANONYMOUS_INLINE_TRANSFER_FEE_SIGNATURE: string;
   export const CONTRACT_ABI: any[];
 
   /**

package/src/index.js

@@ -10,6 +10,12 @@ export {
 export {
   CONTRACT_ABI,
   ERC20_ABI,
+  TRANSFER_CONFIDENTIAL_SIGNATURE,
+  WITHDRAW_CONFIDENTIAL_SIGNATURE,
+  FEE_TOKEN_SIGNATURE,
+  NON_ANONYMOUS_TRANSFER_FEE_SIGNATURE,
+  ANONYMOUS_IPFS_TRANSFER_FEE_SIGNATURE,
+  ANONYMOUS_INLINE_TRANSFER_FEE_SIGNATURE,
   STABLETRUST_CONTRACTS_BY_CHAIN_ID,
   getStabletrustContractAddress,
 } from "./constants.js";

package/src/utils.js

@@ -1,8 +1,4 @@
 import { ethers } from "ethers";
-// Pinata uploads API endpoint
-// Docs: https://docs.pinata.cloud
-const PINATA_UPLOAD_URL = "https://uploads.pinata.cloud/v3/files";
-const PINATA_JWT = process.env.PINATA_JWT;
 
 // Anonymous account ID constraints (must match the Fairycloak relay and on-chain contract rules)
 export const MAX_ANONYMOUS_ACCOUNT_ID_LENGTH = 20;
@@ -38,37 +34,96 @@ export function validateAnonymousAccountId(accountId, fieldName = "accountId") {
   }
 }
 /**
- * Encodes the ZK-Proof data for a transfer into a format the Solidity contract expects.
+ * Convert a proof component returned by the WASM/proof generator into the exact
+ * bytes carried inside the contract/Fairyport ABI proof tuple. The current proof
+ * generator returns base64 text for each proof component; these ASCII bytes are
+ * what the Go relayer and CosmWasm contract expect to receive.
+ *
+ * Hex strings are also accepted for callers that provide raw proof component
+ * bytes manually.
+ *
+ * @param {string|Uint8Array|ArrayBuffer|Array<number>} value
+ * @returns {Uint8Array}
+ * @private
+ */
+function _proofPartToBytes(value) {
+  if (value instanceof Uint8Array) return value;
+  if (value instanceof ArrayBuffer) return new Uint8Array(value);
+  if (Array.isArray(value)) return new Uint8Array(value);
+  if (typeof value !== "string" || value.length === 0) {
+    throw new Error("invalid proof component: expected non-empty string or bytes");
+  }
+  if (value.startsWith("0x")) return ethers.getBytes(value);
+  return new TextEncoder().encode(value);
+}
+
+/**
+ * Encodes the ZK-Proof data for a transfer into the format expected by the
+ * latest EVM/Fairyport/CosmWasm flow: abi.encode(bytes equalityProof,
+ * bytes ciphertextValidityProof, bytes rangeProof).
  *
  * @param {Object} proofData - The proof data object
- * @returns {string} Encoded proof bytes
+ * @returns {string} ABI-encoded proof bytes
  */
 export function encodeTransferProof(proofData) {
   const abiCoder = ethers.AbiCoder.defaultAbiCoder();
   return abiCoder.encode(
-    ["string", "string", "string"],
+    ["bytes", "bytes", "bytes"],
     [
-      proofData.equality_proof,
-      proofData.ciphertext_validity_proof,
-      proofData.range_proof,
+      _proofPartToBytes(proofData.equality_proof),
+      _proofPartToBytes(proofData.ciphertext_validity_proof),
+      _proofPartToBytes(proofData.range_proof),
     ],
   );
 }
 
 /**
- * Encodes the ZK-Proof data for a withdrawal.
+ * Encodes the ZK-Proof data for a withdrawal into the format expected by the
+ * latest EVM/Fairyport/CosmWasm flow: abi.encode(bytes equalityProof,
+ * bytes rangeProof).
  *
  * @param {Object} proofData - The proof data object
- * @returns {string} Encoded proof bytes
+ * @returns {string} ABI-encoded proof bytes
  */
 export function encodeWithdrawProof(proofData) {
   const abiCoder = ethers.AbiCoder.defaultAbiCoder();
   return abiCoder.encode(
-    ["string", "string"],
-    [proofData.equality_proof, proofData.range_proof],
+    ["bytes", "bytes"],
+    [_proofPartToBytes(proofData.equality_proof), _proofPartToBytes(proofData.range_proof)],
   );
 }
 
+/**
+ * Convert a raw ERC-20 token amount to the contract's 2-decimal scale
+ * (`rawAmount * 100 / 10^decimals`).
+ *
+ * Throws when the amount rounds to zero and warns when a sub-cent remainder
+ * is dropped, so callers never silently no-op or lose precision.
+ *
+ * @param {bigint|string|number} rawAmount - Amount in raw ERC-20 units
+ * @param {bigint|number} tokenDecimals - Token decimals
+ * @returns {bigint} Amount in contract scale
+ * @throws {Error} If the amount rounds to 0 in contract scale
+ */
+export function toContractScale(rawAmount, tokenDecimals) {
+  const raw = BigInt(rawAmount);
+  const divisor = 10n ** BigInt(tokenDecimals);
+  const scaled = (raw * 100n) / divisor;
+
+  if (scaled <= 0n) {
+    throw new Error(
+      `Amount too small: ${raw} raw units rounds to 0 in contract scale`,
+    );
+  }
+  if ((raw * 100n) % divisor !== 0n) {
+    console.warn(
+      `Amount ${raw} is not fully representable in contract scale (2 decimals); the sub-cent remainder will be dropped.`,
+    );
+  }
+
+  return scaled;
+}
+
 /**
  * Delays execution for a specified time
  *
@@ -121,76 +176,128 @@ export async function waitForCondition(
 }
 
 /**
- * Upload a JSON-serializable object to IPFS and return its CID (as a string).
- * The object will be stored as a UTF-8 JSON blob.
+ * Browser-safe environment lookup.
  *
- * @param {any} data - JSON-serializable data to store.
- * @returns {Promise<string>} The CID string.
+ * @param {string} name - Environment variable name.
+ * @returns {string|undefined}
+ * @private
  */
-export async function uploadJsonToIpfs(data) {
-  if (!PINATA_JWT) {
-    throw new Error("PINATA_JWT is not set");
+function _env(name) {
+  if (typeof process !== "undefined" && process?.env?.[name]) {
+    return process.env[name];
   }
+  return undefined;
+}
 
-  const json = JSON.stringify(data);
-  const blob = new Blob([json], { type: "application/json" });
-
-  const form = new FormData();
-  form.append("file", blob, "proof.json");
-  form.append("network", "public");
-  form.append("name", "zk-proof");
-
-  const res = await fetch(PINATA_UPLOAD_URL, {
-    method: "POST",
-    headers: {
-      Authorization: `Bearer ${PINATA_JWT}`,
-    },
-    body: form,
-  });
+/**
+ * Resolve StableTrust IPFS upload options from explicit options or environment variables.
+ *
+ * @param {Object} [options]
+ * @param {string} [options.uploadUrl] - StableTrust IPFS upload endpoint.
+ * @param {string} [options.ipfsUploadUrl] - Alias for uploadUrl.
+ * @param {string} [options.apiKey] - Bearer token for upload endpoint.
+ * @param {string} [options.ipfsApiKey] - Alias for apiKey.
+ * @returns {{uploadUrl:string, apiKey:string|null}}
+ * @private
+ */
+function _resolveIpfsUploadOptions(options = {}) {
+  const uploadUrl =
+    options.uploadUrl ||
+    options.ipfsUploadUrl ||
+    _env("STABLETRUST_IPFS_UPLOAD_URL") ||
+    _env("IPFS_UPLOAD_URL");
 
-  if (!res.ok) {
-    const text = await res.text();
-    throw new Error(`Pinata upload failed: ${text}`);
+  if (!uploadUrl) {
+    throw new Error(
+      "StableTrust IPFS upload URL is not set - pass `ipfsUploadUrl` in the client config or set STABLETRUST_IPFS_UPLOAD_URL",
+    );
   }
 
-  const jsonRes = await res.json();
-  return jsonRes?.data?.cid?.toString();
+  return {
+    uploadUrl: String(uploadUrl).trim(),
+    apiKey:
+      options.apiKey ||
+      options.ipfsApiKey ||
+      _env("STABLETRUST_IPFS_API_KEY") ||
+      _env("IPFS_UPLOAD_API_KEY") ||
+      null,
+  };
 }
 
 /**
- * Upload raw bytes to IPFS (Pinata) and return the CID.
+ * Upload a JSON-serializable object to the configured StableTrust IPFS upload endpoint
+ * and return its CID. The object is stored as UTF-8 JSON bytes.
  *
- * @param {Uint8Array|ArrayBuffer} bytes - Raw proof bytes.
- * @param {string} [name='proof.bin'] - Optional file name metadata.
- * @returns {Promise<string>} The CID string.
+ * @param {any} data - JSON-serializable data to store.
+ * @param {Object} [options]
+ * @param {string} [options.uploadUrl] - StableTrust IPFS upload endpoint.
+ * @param {string} [options.apiKey] - Bearer token for upload endpoint.
+ * @returns {Promise<string>} Bare CID string.
  */
-export async function uploadBytesToIpfs(bytes, name = "proof.bin") {
-  if (!PINATA_JWT) {
-    throw new Error("PINATA_JWT is not set");
-  }
+export async function uploadJsonToIpfs(data, options = {}) {
+  const json = JSON.stringify(data);
+  return uploadBytesToIpfs(new TextEncoder().encode(json), "proof.json", options);
+}
 
+/**
+ * Upload raw proof bytes to the configured StableTrust IPFS upload endpoint and return the bare CID.
+ *
+ * Expected upload endpoint contract:
+ * - POST raw bytes to `uploadUrl`
+ * - `Content-Type: application/octet-stream`
+ * - optional `Authorization: Bearer <apiKey>`
+ * - response JSON contains `{ "cid": "..." }` (also accepts `Hash`/`Cid` for compatibility)
+ *
+ * @param {Uint8Array|ArrayBuffer|Array<number>} bytes - Raw proof bytes.
+ * @param {string} [name='proof.bin'] - Optional proof name, sent as `X-StableTrust-Filename` metadata.
+ * @param {Object} [options]
+ * @param {string} [options.uploadUrl] - StableTrust IPFS upload endpoint.
+ * @param {string} [options.apiKey] - Bearer token for upload endpoint.
+ * @returns {Promise<string>} Bare CID string.
+ */
+export async function uploadBytesToIpfs(bytes, name = "proof.bin", options = {}) {
+  const { uploadUrl, apiKey } = _resolveIpfsUploadOptions(options);
   const uint8 = bytes instanceof Uint8Array ? bytes : new Uint8Array(bytes);
 
-  const blob = new Blob([uint8], { type: "application/octet-stream" });
+  if (uint8.length === 0) {
+    throw new Error("cannot upload an empty proof to IPFS");
+  }
 
-  const form = new FormData();
-  form.append("file", blob, name);
-  form.append("network", "public");
-  form.append("name", name);
+  const headers = {
+    "Content-Type": "application/octet-stream",
+  };
+  if (name) {
+    headers["X-StableTrust-Filename"] = String(name);
+  }
+  if (apiKey) {
+    headers.Authorization = `Bearer ${apiKey}`;
+  }
 
-  const res = await fetch(PINATA_UPLOAD_URL, {
+  const res = await fetch(uploadUrl, {
     method: "POST",
-    headers: {
-      Authorization: `Bearer ${PINATA_JWT}`,
-    },
-    body: form,
+    headers,
+    body: uint8,
   });
 
   if (!res.ok) {
     const text = await res.text();
-    throw new Error(`Pinata upload failed: ${text}`);
+    throw new Error(`StableTrust IPFS upload failed: ${text}`);
+  }
+
+  const contentType = res.headers.get("content-type") || "";
+  let cid;
+  if (contentType.includes("application/json")) {
+    const jsonRes = await res.json();
+    cid = jsonRes?.cid ?? jsonRes?.CID ?? jsonRes?.Cid ?? jsonRes?.Hash ?? jsonRes?.hash;
+  } else {
+    cid = await res.text();
   }
 
-  const jsonRes = await res.json();
-  return jsonRes?.data?.cid?.toString();
+  cid = String(cid || "").trim().replace(/^ipfs:\/\//i, "");
+  if (!cid) {
+    throw new Error("StableTrust IPFS upload returned no CID");
+  }
+
+  return cid;
 }
+