@fairblock/stabletrust 2.0.6 → 2.0.10

package/README.md

@@ -2,12 +2,12 @@
 
 ## Overview
 
-The StableTrust SDK by Fairblock provides a robust interface for executing confidential and anonymous transfers using homomorphic encryption and zero-knowledge proofs. This package enables developers to integrate confidentiality features directly into their applications, allowing for secure token deposits, private transfers, and withdrawals while maintaining the integrity and auditability of the underlying blockchain transactions.
+The stabletrust SDK by Fairblock provides a robust interface for executing confidential and unlinkable transfers using homomorphic encryption and zero-knowledge proofs. This package enables developers to integrate confidentiality features directly into their applications, allowing for secure token deposits, private transfers, and withdrawals while maintaining the integrity and auditability of the underlying blockchain transactions.
 
 For a comprehensive technical understanding of the architecture and cryptographic primitives, please refer to the following documentation:
 
 - **Technical Overview**: [Fairblock Confidential Transfers](https://docs.fairblock.network/docs/confidential_transfers/technical_overview)
-- **Stabletrust Protocol**: [Stabletrust Documentation](https://docs.fairblock.network/docs/confidential_transfers/stabletrust)
+- **stabletrust Protocol**: [stabletrust Documentation](https://docs.fairblock.network/docs/confidential_transfers/stabletrust)
 - **Confidential Transactions**: [Transaction Mechanics](https://docs.fairblock.network/docs/confidential_transfers/confidential_transactions)
 
 ## Requirements
@@ -41,9 +41,9 @@ The SDK ships two clients that serve different privacy models:
 | Feature            | `ConfidentialTransferClient`                     | `AnonymousTransferClient`                                    |
 | :----------------- | :----------------------------------------------- | :----------------------------------------------------------- |
 | **Identity**       | On-chain wallet address is visible               | Account ID only — wallet address is hidden                   |
-| **Gas**            | User pays gas for all transactions               | Fairycloak relay pays gas (except deposit)                   |
+| **Gas**            | User pays gas for all transactions               | Relay pays gas (except user-funded raw-tx ops: deposit, fee top-up/withdraw, native-ETH create) |
 | **Setup**          | Direct RPC connection                            | Requires a running Fairycloak relay server                   |
-| **Recipient**      | Must have a confidential account                 | Can receive to another anonymous account or a public address |
+| **Recipient**      | Must have a confidential account                 | Can receive to another unlinkable account or a public address |
 | **Key management** | Keys auto-derived from wallet signature          | Keys derived per-account; store the private key yourself     |
 | **Best for**       | Privacy over balances/amounts with known senders | Full sender anonymity                                        |
 
@@ -51,9 +51,9 @@ The SDK ships two clients that serve different privacy models:
 
 Transactions are submitted on-chain directly from your wallet. The **amount and balance are encrypted** (hidden), but the **sender's address is visible** on-chain. Ideal when you want confidential balances without hiding your identity.
 
-### `AnonymousTransferClient` — Anonymous Transfers
+### `AnonymousTransferClient` — Unlinkable Transfers
 
-Transactions are routed through the **Fairycloak relay**, which submits them on-chain and pays gas. The sender's wallet address is **never revealed** on-chain — only a numeric account ID is associated with the transfer. Use this client when full sender anonymity is required.
+Transactions are routed through the **Fairycloak relay**, which submits them on-chain and pays gas (recouped from the account's prepaid fee reserve). The sender's wallet address is **never revealed** on-chain - only the caller-chosen account ID is associated with the transfer. Use this client when full sender anonymity is required.
 
 ---
 
@@ -63,12 +63,12 @@ The following contract addresses are available for confidential transfers on tes
 
 | Network(Testnet) | Chain ID | Contract Address                             |
 | :--------------- | :------- | :------------------------------------------- |
-| Stable           | 2201     | `0xB96aa42b246a956B170fE426A72fB610E4976f9E` |
-| Arc              | 5042002  | `0xb20aB54e1c6AE55B0DD11FEB7FFf3fF1E9631f19` |
-| Base             | 84532    | `0x962a8A7CD28BfFBb17C4F6Ec388782cca3ffd618` |
-| Ethereum         | 11155111 | `0x2E48F3D9b8F4aCA9E6AF0630eaB2ceB7A3f5eEd1` |
-| Arbitrum         | 421614   | `0x14Afd604971bee5b5fac52df2d56CaE421519Cc5` |
-| Tempo            | 42431    | `0x08B6563C95dfe3a4F5533CAA6F7D55a74FCb4F6c` |
+| Stable           | 2201     | `0xe1c1456CAb802312759a8cFc3976f88bf87082cf` |
+| Arc              | 5042002  | `0x1B4f05f67CC33788Da4C89a7cd0b2f8E0055E605` |
+| Base             | 84532    | `0x4a251C9D79faCa20b193630A4ee313af7cBCDD93` |
+| Ethereum         | 11155111 | `0x7507a13352AFAa79D33E994f86f2f62463ba8DE4` |
+| Arbitrum         | 421614   | `0x5acECCdeb5CbD3C727eCB49F8706Eb80EF2f977F` |
+| Tempo            | 42431    | `0xE559fB936C69c46E216bf61B07C16bF1a6d444aa` |
 
 ---
 
@@ -84,7 +84,7 @@ Import and initialize the client with your network configuration.
 import { ConfidentialTransferClient } from "@fairblock/stabletrust";
 import { ethers } from "ethers";
 
-// Use SDK default StableTrust contract for a known chainId
+// Use SDK default stabletrust contract for a known chainId
 const client = new ConfidentialTransferClient(
   "https://sepolia.base.org",
   84532,
@@ -96,7 +96,7 @@ If you are using a custom deployment, pass an explicit contract address:
 ```javascript
 const customClient = new ConfidentialTransferClient(
   "https://sepolia.base.org",
-  "0xYourCustomStabletrustContract",
+  "0xYourCustomstabletrustContract",
   84532,
 );
 ```
@@ -116,14 +116,38 @@ const arcClient = new ConfidentialTransferClient(
   5042002,
 );
 
-// Tempo (special fee handling via IPFS proof upload)
+// Tempo (defaults to offchainZKP/IPFS proof upload)
 const tempoClient = new ConfidentialTransferClient(
   "https://tempo-rpc.example.com",
   42431,
 );
 ```
 
-**Note on Tempo Chain**: The Tempo network (chainId 42431) uploads ZK proofs to IPFS instead of passing them as calldata. The SDK handles this automatically.
+**Note on off-chain ZKP/IPFS proofs**: The latest confidential-transfer contract exposes `transferConfidential(address,address,bytes,bool)` and `withdraw(address,uint256,bytes,bool)`. By default the SDK submits inline ABI-encoded proof bytes with `offchainZKP=false`. Set `offchainZKP: true` on `confidentialTransfer` or `withdraw` to upload the ABI-encoded proof bytes to StableTrust IPFS and put only the bare CID bytes on-chain. Tempo (chainId 42431) keeps the old SDK behaviour and defaults to `offchainZKP=true`; pass `{ offchainZKP: false }` to force inline proofs.
+
+```javascript
+const client = new ConfidentialTransferClient(rpcUrl, chainId, {
+  ipfsUploadUrl: process.env.STABLETRUST_IPFS_UPLOAD_URL,
+  ipfsApiKey: process.env.STABLETRUST_IPFS_API_KEY,
+});
+
+await client.confidentialTransfer(
+  signer,
+  recipientAddress,
+  tokenAddress,
+  amountToTransfer,
+  { offchainZKP: true },
+);
+
+await client.withdraw(
+  signer,
+  tokenAddress,
+  amountToWithdraw,
+  { offchainZKP: true },
+);
+```
+
+The deprecated option name `useOffchainVerify` is still accepted as an alias for `offchainZKP`.
 
 ### Token Denomination
 
@@ -186,7 +210,7 @@ Deposits ERC-20 tokens into the confidential contract. Handles ERC-20 approval a
 
 #### `confidentialTransfer(senderWallet, recipientAddress, tokenAddress, amount, options?)`
 
-Transfers a confidential amount to a recipient. The recipient must have an existing confidential account.
+Transfers a confidential amount to a recipient. The recipient must have an existing confidential account. Both inline and IPFS proof paths use the same live non-anonymous transfer fee. The SDK reads the active fee configuration automatically: native fees are attached as `msg.value`, while ERC-20 fees are approved for the diamond when necessary.
 
 - **Returns**: Transaction receipt.
 
@@ -196,9 +220,14 @@ Withdraws from the confidential available balance back to public ERC-20.
 
 - **Returns**: Transaction receipt.
 
-#### `getFeeAmount()`
+#### Fee configuration getters
+
+- `getFeeToken()` returns the active fee token; `ethers.ZeroAddress` means native currency.
+- `getNonAnonymousTransferFee()` returns the fixed fee used by both inline and IPFS non-anonymous transfers.
+- `getAnonymousIpfsTransferFee()` returns the fixed anonymous IPFS-path fee.
+- `getAnonymousInlineTransferFee()` returns the fixed anonymous inline-path fee.
 
-Returns the native fee (in wei) required for confidential transfers on the current chain.
+All amounts are returned as raw units of the active fee token.
 
 #### `getPublicBalance(address, tokenAddress)`
 
@@ -208,11 +237,11 @@ Returns the public ERC-20 balance for an address.
 
 ## AnonymousTransferClient
 
-The `AnonymousTransferClient` routes all operations through the **Fairycloak relay server**. The relay submits transactions on-chain and pays gas on your behalf (except for deposits, which require the user to pay). Your wallet address is never revealed — only a numeric anonymous account ID appears on-chain.
+The `AnonymousTransferClient` routes all operations through the **Fairycloak relay server**. The relay submits transactions on-chain and pays gas on your behalf, recovering the cost from the account's [prepaid fee reserve](#prepaid-fees). The exceptions are the **user-funded raw-tx operations** - `deposit`, `depositFees`, `withdrawFees`, `withdrawAllFees`, and native-ETH account creation - which you sign and pay gas for directly (and which are therefore not charged a prepaid fee). Your wallet address is never revealed - only your chosen unlinkable account ID appears on-chain.
 
-> **Access Required** — Anonymous transfers are available to teams building privacy-critical applications. To obtain a Fairycloak relay URL and API key, reach out to the Fairblock team at [hello@fairblock.network](mailto:hello@fairblock.network).
+> **Access Required** — Unlinkable transfers are available to teams building privacy-critical applications. To obtain a Fairycloak relay URL and API key, reach out to the Fairblock team at [hello@fairblock.network](mailto:hello@fairblock.network).
 
-### Anonymous Account ID Rules
+### Unlinkable Account ID Rules
 
 Every `accountId` (and `senderAccountId` / `recipientId`) you pass to `AnonymousTransferClient` must follow these rules, enforced both on-chain and by the Fairycloak relay:
 
@@ -235,9 +264,18 @@ const client = new AnonymousTransferClient({
 });
 ```
 
+**Config options** — `fairycloakUrl`, `chainId`, and `rpcUrl` are required. Optional:
+
+| option | default | purpose |
+|---|---|---|
+| `diamondAddress` | auto-resolved by `chainId` | override the ConfidentialMirror contract address |
+| `apiKey` | - | Fairycloak API key (sent as `X-API-Key`) |
+| `ipfsUploadUrl` / `ipfsApiKey` / `ipfsGatewayUrl` | env fallback | off-chain ZKP proof uploads (see [Off-chain ZKP proofs](#off-chain-zkp-proofs-ipfs)) |
+| `enableNativeFeeToken` | `false` | opt in to **native-ETH fee tokens**. Off by default - the SDK refuses account creation when the protocol fee token is native ETH unless this is `true`. See [Prepaid Fees](#prepaid-fees). |
+
 ### Key Derivation
 
-Anonymous accounts use a per-account ElGamal keypair derived from a wallet signature. **Store the returned `privateKey` securely** — it cannot be recovered without the original wallet and account ID.
+Unlinkable accounts use a per-account ElGamal keypair derived from a wallet signature. **Store the returned `privateKey` securely** — it cannot be recovered without the original wallet and account ID.
 
 ```javascript
 const keys = await client.deriveAnonymousKeys(authWallet, accountId);
@@ -249,13 +287,20 @@ const keys = await client.deriveAnonymousKeys(authWallet, accountId);
 
 #### `createAccount(authWallet, accountId, elgamalPublicKey, options?)`
 
-Creates a new anonymous account via the relay. The relay pays gas. `accountId` is a **caller-chosen string** — pick any unique identifier you like (e.g. a short UUID fragment or a human-readable name), as long as it follows the [Anonymous Account ID Rules](#anonymous-account-id-rules) above (non-empty, at most 20 characters, alphanumeric only, case-sensitive).
+Creates a new unlinkable account. `accountId` is a **caller-chosen string** — pick any unique identifier you like (e.g. a short UUID fragment or a human-readable name), as long as it follows the [Unlinkable Account ID Rules](#unlinkable-account-id-rules) above (non-empty, at most 20 characters, alphanumeric only, case-sensitive).
+
+Creation also seeds the account's **prepaid fee reserve** (see [Prepaid Fees](#prepaid-fees)). It pulls an `initialFeeDeposit` in the active fee token, immediately charges the one-time `anonymousCreateAccountFee`, and credits the remainder to the reserve once creation finalises. The deposit defaults to the contract's `anonymousMinimumInitialFeeDeposit`; override it with `options.initialFeeDeposit`. The submission model is chosen automatically by the active fee token:
+
+- **ERC-20 fee token** (default): the SDK checks/approves the deposit and the **relay submits + pays gas**.
+- **Native ETH fee token** (`feeToken == address(0)`): ETH can't be pulled with `transferFrom`, so the fee payer **signs and funds the payable tx itself** (`msg.value == initialFeeDeposit`, `authWallet` pays gas). This path is **disabled unless** the client is constructed with `enableNativeFeeToken: true` — otherwise `createAccount` throws.
+
+- **Options**: `deadlineOffset` (default `3600`), `initialFeeDeposit` (default = contract minimum), `gasLimit` (default `1000000n`, only used for the native raw tx)
 
 #### `ensureAnonymousAccount(authWallet, accountId, elgamalPublicKey, options?)`
 
-Idempotent helper that creates the anonymous account if it doesn't already exist, and (by default) waits until it has settled (no pending CW→EVM action) before returning. If an account with `accountId` already exists on-chain, account creation is skipped entirely — safe to call on every run with a stable `accountId`.
+Idempotent helper that creates the unlinkable account if it doesn't already exist, and (by default) waits until it has settled (no pending CW→EVM action) before returning. If an account with `accountId` already exists on-chain, account creation is skipped entirely — safe to call on every run with a stable `accountId`.
 
-> Note: an auth signer can only ever be bound to a single anonymous account, so reusing a wallet across different `accountId`s will fail at creation time even via `ensureAnonymousAccount`.
+> Note: an auth signer can only ever be bound to a single unlinkable account, so reusing a wallet across different `accountId`s will fail at creation time even via `ensureAnonymousAccount`.
 
 ```javascript
 const { accountId, accountInfo, created } = await client.ensureAnonymousAccount(
@@ -270,7 +315,7 @@ const { accountId, accountInfo, created } = await client.ensureAnonymousAccount(
 
 #### `updateAuthKeys(authWallet, accountId, { add, remove }, options?)`
 
-Adds or removes authorised signers for an anonymous account. Pass `ethers.Wallet` instances or raw uncompressed hex pubkey strings.
+Adds or removes authorised signers for an unlinkable account. Pass `ethers.Wallet` instances or raw uncompressed hex pubkey strings. The relay pays gas and charges the `anonymousUpdateKeysFee` from the account's [prepaid reserve](#prepaid-fees).
 
 #### `getAnonymousAccountInfo(accountId)`
 
@@ -294,7 +339,7 @@ Returns decrypted balances including raw ciphertexts — useful when you need th
 
 #### `deposit(authWallet, accountId, tokenAddress, amount, options?)`
 
-Deposits tokens into an anonymous account. The **user pays gas** for this operation. Handles ERC-20 approval automatically.
+Deposits tokens into an unlinkable account. The **user pays gas** for this operation. Handles ERC-20 approval automatically.
 
 ```javascript
 const result = await client.deposit(
@@ -308,7 +353,7 @@ await client.waitForRequest(result.request_id);
 
 #### `transferToPublic(authWallet, accountId, params, options?)`
 
-Transfers from an anonymous account to a public EVM address. The relay pays gas.
+Transfers from an unlinkable account to a public EVM address. The relay pays gas and charges the inline or IPFS transfer fee (depending on `offchainZKP`) from the sender's [prepaid reserve](#prepaid-fees).
 
 **Auto-proof mode** (recommended):
 
@@ -339,7 +384,7 @@ const result = await client.transferToPublic(wallet, accountId, {
 
 #### `transferToAnonymous(authWallet, senderAccountId, params, options?)`
 
-Transfers between two anonymous accounts. The relay pays gas.
+Transfers between two unlinkable accounts. The relay pays gas and charges the inline or IPFS transfer fee (depending on `offchainZKP`) from the sender's [prepaid reserve](#prepaid-fees).
 
 ```javascript
 const result = await client.transferToAnonymous(wallet, senderAccountId, {
@@ -352,11 +397,11 @@ const result = await client.transferToAnonymous(wallet, senderAccountId, {
 
 #### `applyPending(authWallet, accountId, options?)`
 
-Moves a pending incoming balance into available. Must be called after receiving an anonymous-to-anonymous transfer. The relay pays gas.
+Moves a pending incoming balance into available. Must be called after receiving an unlinkable-to-unlinkable transfer. The relay pays gas and charges the `anonymousApplyPendingFee` from the account's [prepaid reserve](#prepaid-fees).
 
 #### `withdraw(authWallet, accountId, params, options?)`
 
-Withdraws from an anonymous account to a public EVM address. The relay pays gas.
+Withdraws from an unlinkable account to a public EVM address. The relay pays gas and charges the inline or IPFS withdraw fee (depending on `offchainZKP`) from the account's [prepaid reserve](#prepaid-fees).
 
 ```javascript
 const result = await client.withdraw(wallet, accountId, {
@@ -367,32 +412,110 @@ const result = await client.withdraw(wallet, accountId, {
 });
 ```
 
+### Off-chain ZKP proofs (IPFS)
+
+By default an unlinkable proof is submitted **inline** through the Fairycloak relay. For `transferToPublic`, `transferToAnonymous`, and `withdraw` you can instead set **`offchainZKP: true`** to upload the proof to **StableTrust self-hosted IPFS** and put only the resulting **CID** on-chain. Fairycloak/Fairyport then fetches the full proof from IPFS and forwards the actual proof bytes to the CosmWasm contract. This keeps large (~2.5 KB) proofs out of calldata. The flag is optional and defaults to `false`, so the inline path is unchanged. These proof-carrying methods support it; `deposit` and `applyPending` do not (they carry no ZK proof).
+
+**Providing StableTrust IPFS upload config.** When `offchainZKP` is enabled the SDK uploads proof bytes to the configured StableTrust IPFS upload endpoint. Provide it either via the client config (recommended, and required in browsers where `process.env` is unavailable):
+
+```javascript
+const client = new AnonymousTransferClient({
+  fairycloakUrl: "http://127.0.0.1:8080",
+  chainId: 31337,
+  rpcUrl: "http://127.0.0.1:8545",
+  ipfsUploadUrl: process.env.STABLETRUST_IPFS_UPLOAD_URL,
+  ipfsApiKey: process.env.STABLETRUST_IPFS_API_KEY,
+});
+```
+
+…or, in Node.js, by setting `STABLETRUST_IPFS_UPLOAD_URL` and `STABLETRUST_IPFS_API_KEY` environment variables, used as fallback values when they are not passed in client config.
+
+**Usage** - add the flag to a normal transfer:
+
+```javascript
+// unlinkable -> unlinkable; proof stored on IPFS, CID on-chain
+await client.transferToAnonymous(wallet, "alice", {
+  recipientId: "bob",
+  token: tokenAddress,
+  amount: ethers.parseUnits("5", 18),
+  elGamalPrivateKey: keys.privateKey,
+  offchainZKP: true,
+});
+
+// unlinkable -> public EVM address
+await client.transferToPublic(wallet, "alice", {
+  recipient: "0xRecipientAddress",
+  token: tokenAddress,
+  amount: ethers.parseUnits("5", 18),
+  elGamalPrivateKey: keys.privateKey,
+  offchainZKP: true,
+});
+
+// withdraw to a public address; withdraw proof stored on IPFS, CID on-chain
+await client.withdraw(wallet, "alice", {
+  destination: "0xDestinationAddress",
+  token: tokenAddress,
+  plainAmount: ethers.parseUnits("5", 18),
+  elGamalPrivateKey: keys.privateKey,
+  offchainZKP: true,
+});
+```
+
+In manual-proof mode (when you pass a pre-computed `proof`) with `offchainZKP: true`, the SDK treats `proof` as an already-uploaded CID rather than re-uploading it.
+
 ### Prepaid Fees
 
-Every `transferToPublic` and `transferToAnonymous` call deducts a protocol fee from the sender account's **prepaid fee reserve**. The SDK checks this balance before submitting a transfer and throws a descriptive error if it's insufficient — top up the reserve with `depositFees` before transferring.
+The protocol uses a **prepaid-fee-for-all-operations** model. Each unlinkable account holds a **prepaid fee reserve** (a pot in the active fee token), and every relay-submitted operation debits a fixed fee from it:
+
+| operation | fee |
+|---|---|
+| create account | `anonymousCreateAccountFee` (charged once, at creation) |
+| update auth keys | `anonymousUpdateKeysFee` |
+| transfer (→ public / → anonymous) | `anonymousInlineTransferFee` or `anonymousIpfsTransferFee` |
+| apply pending | `anonymousApplyPendingFee` |
+| withdraw | `anonymousInlineWithdrawFee` or `anonymousIpfsWithdrawFee` |
+
+The relay fronts the gas for these operations and is reimbursed from the pot. **User-funded raw-tx operations do _not_ charge a prepaid fee** - `deposit`, `depositFees` (top-up), `withdrawFees`, and `withdrawAllFees` are signed and paid for by the user's own wallet, so there is nothing to reimburse.
+
+The reserve is seeded at [account creation](#createaccountauthwallet-accountid-elgamalpublickey-options) (`initialFeeDeposit − anonymousCreateAccountFee`) and topped up with `depositFees`. Transfers additionally pre-check the reserve before submitting and throw a descriptive error if it can't cover the fee.
+
+**Fee token.** There is one active fee token for the whole protocol, set by the admin and read via `getFeeToken()`. It can be an **ERC-20** (the default) or **native ETH** (`address(0)`) - fee amounts and the prepaid pot are denominated in whichever it is. Using a native-ETH fee token requires opting in with `enableNativeFeeToken: true` in the client config (see [createAccount](#createaccountauthwallet-accountid-elgamalpublickey-options)).
 
 #### `getFeeToken()`
 
-Returns the currently configured ERC-20 fee token address (checksummed). `depositFees` deposits must use this token. The fee token can be rotated by the protocol over time, but existing balances in old fee tokens remain withdrawable.
+Returns the currently configured fee token address (checksummed). `ethers.ZeroAddress` represents native currency. `depositFees` deposits must use this token. The fee token can be rotated by the protocol over time, but existing balances in old fee tokens remain withdrawable.
 
-#### `getFeeAmount()`
+#### Fee-config getters
 
-Returns the protocol fee amount (in raw ERC-20 units of the fee token) deducted from the prepaid reserve on each anonymous transfer. Returns `0n` if no fee is configured.
+All getters read live from the protocol and return **raw units of the active fee token** (`0n` when a pathway has no configured fee).
+
+Per-operation fees:
+
+- `getAnonymousCreateAccountFee()` - one-time account-creation fee.
+- `getAnonymousMinimumInitialFeeDeposit()` - minimum `initialFeeDeposit` accepted at creation.
+- `getAnonymousUpdateKeysFee()` - auth-key update.
+- `getAnonymousApplyPendingFee()` - apply-pending.
+- `getAnonymousInlineTransferFee()` / `getAnonymousIpfsTransferFee()` - inline / IPFS transfer.
+- `getAnonymousInlineWithdrawFee()` / `getAnonymousIpfsWithdrawFee()` - inline / IPFS withdraw.
+- `getNonAnonymousTransferFee()` - the shared non-anonymous transfer fee.
 
 #### `getPrepaidFeeBalance(accountId, token)`
 
-Returns the prepaid fee balance (in raw ERC-20 units) for an anonymous account and a given fee token.
+Returns the prepaid fee balance in raw units of the selected fee token. For native currency reserves, the amount is in wei.
 
 #### `depositFees(authWallet, accountId, amount, options?)`
 
-Deposits tokens into the prepaid fee reserve for an anonymous account. **The user pays gas** for this operation (mirrors `deposit()`). Handles ERC-20 approval against the active fee token automatically.
+Deposits tokens into the prepaid fee reserve for an unlinkable account. **The user pays gas** for this operation (mirrors `deposit()`). Handles ERC-20 approval against the active fee token automatically.
 
 ```javascript
+const offchainZKP = true;
 const feeToken = await client.getFeeToken();
-const feeAmount = await client.getFeeAmount();
+const inlineFee = await client.getAnonymousInlineTransferFee();
+const ipfsFee = await client.getAnonymousIpfsTransferFee();
+const requiredFee = offchainZKP ? ipfsFee : inlineFee;
 const feeBalance = await client.getPrepaidFeeBalance(accountId, feeToken);
 
-if (feeBalance < feeAmount) {
+if (feeBalance < requiredFee) {
   const result = await client.depositFees(
     wallet,
     accountId,
@@ -404,11 +527,11 @@ if (feeBalance < feeAmount) {
 
 #### `withdrawFees(authWallet, accountId, { token, destination, amount }, options?)`
 
-Withdraws a specific amount from the prepaid fee reserve for a given fee token. The relay pays gas. Use this to reclaim fees from a specific (possibly historical) fee token.
+Reclaims a specific amount from the prepaid fee reserve for a given fee token. **User-funded raw-tx** model (like `deposit`/`depositFees`): the anonymous signer authorises the withdrawal via EIP-712 and the same wallet signs and funds the outer transaction, so **the user pays gas and no prepaid fee is charged** — the full amount is returned. Use this to reclaim a specific (possibly historical) fee token.
 
 #### `withdrawAllFees(authWallet, accountId, { destination }, options?)`
 
-Withdraws all prepaid fee balances across all (including historical) fee tokens to `destination`. The relay pays gas.
+Drains all prepaid fee balances across all (including historical) fee tokens to `destination`. Same user-funded raw-tx model as `withdrawFees` — the user pays gas, no prepaid fee.
 
 #### Request Tracking
 
@@ -475,7 +598,7 @@ const withdrawAmount = ethers.parseUnits("2", tokenDecimals);
 await client.withdraw(wallet, tokenAddress, withdrawAmount);
 ```
 
-### Anonymous Flow (AnonymousTransferClient)
+### Unlinkable Flow (AnonymousTransferClient)
 
 ```javascript
 import { AnonymousTransferClient } from "@fairblock/stabletrust";
@@ -512,12 +635,13 @@ const balance = await client.getBalance(
 );
 console.log("Available:", balance.available, "Pending:", balance.pending);
 
-// 4. Top up the prepaid fee reserve if needed (user pays gas)
-// transferToPublic/transferToAnonymous deduct a protocol fee from this reserve.
+// 4. Top up the prepaid fee reserve if needed (user pays gas; no fee on the top-up itself)
+// The reserve was seeded at account creation; every relay op (update-keys/transfer/apply/withdraw)
+// draws a fixed fee from it. Here we make sure it can cover the next transfer.
 const feeToken = await client.getFeeToken();
-const feeAmount = await client.getFeeAmount();
+const inlineFee = await client.getAnonymousInlineTransferFee();
 const feeBalance = await client.getPrepaidFeeBalance(accountId, feeToken);
-if (feeBalance < feeAmount) {
+if (feeBalance < inlineFee) {
   const feeResult = await client.depositFees(
     wallet,
     accountId,
@@ -526,7 +650,7 @@ if (feeBalance < feeAmount) {
   await client.waitForRequest(feeResult.request_id);
 }
 
-// 5. Transfer to a public address (relay pays gas)
+// 5. Transfer to a public address (relay pays gas; a transfer fee is drawn from the prepaid reserve)
 const transferResult = await client.transferToPublic(wallet, accountId, {
   recipient: "0xRecipientAddress",
   token: tokenAddress,
@@ -535,7 +659,7 @@ const transferResult = await client.transferToPublic(wallet, accountId, {
 });
 await client.waitForRequest(transferResult.request_id);
 
-// 6. Withdraw (relay pays gas)
+// 6. Withdraw (relay pays gas; a withdraw fee is drawn from the prepaid reserve)
 const withdrawResult = await client.withdraw(wallet, accountId, {
   destination: wallet.address,
   token: tokenAddress,
@@ -572,39 +696,26 @@ try {
 
 ### Common Issues and Solutions
 
-| Issue                          | Cause                                                   | Solution                                                |
-| :----------------------------- | :------------------------------------------------------ | :------------------------------------------------------ |
-| "Account does not exist"       | Recipient hasn't initialized their confidential account | Recipient must call `ensureAccount()` first             |
-| "Insufficient balance"         | Transfer amount exceeds available confidential balance  | Deposit more tokens or reduce transfer amount           |
-| "Account finalization timeout" | Account creation is still processing                    | Wait a few minutes and retry                            |
-| "Proof generation failed"      | Invalid inputs or cryptographic operation error         | Verify all parameters and ensure sufficient balance     |
-| "Amount too small"             | Amount rounds to 0 in contract scale                    | Use a larger amount (minimum depends on token decimals) |
-| "Insufficient prepaid fee balance" | Anonymous account's prepaid fee reserve is below the per-transfer fee | Call `depositFees(wallet, accountId, amount)` to top up; use `getFeeToken()`/`getFeeAmount()` to check requirements |
-| Fairycloak HTTP error          | Relay unreachable or request rejected                   | Check the relay URL, API key, and account authorization |
-
----
-
-## Performance Metrics
-
-The following are estimated execution times for standard operations. Durations may vary based on network congestion and hardware.
-
-| Operation        | Avg Duration |
-| :--------------- | :----------- |
-| Account Creation | 45s          |
-| Deposit          | 63s          |
-| Transfer         | 58s          |
-| Withdraw         | 58s          |
+| Issue                              | Cause                                                                 | Solution                                                                                                            |
+| :--------------------------------- | :-------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------ |
+| "Account does not exist"           | Recipient hasn't initialized their confidential account               | Recipient must call `ensureAccount()` first                                                                         |
+| "Insufficient balance"             | Transfer amount exceeds available confidential balance                | Deposit more tokens or reduce transfer amount                                                                       |
+| "Account finalization timeout"     | Account creation is still processing                                  | Wait a few minutes and retry                                                                                        |
+| "Proof generation failed"          | Invalid inputs or cryptographic operation error                       | Verify all parameters and ensure sufficient balance                                                                 |
+| "Amount too small"                 | Amount rounds to 0 in contract scale                                  | Use a larger amount (minimum depends on token decimals)                                                             |
+| "Insufficient prepaid fee balance" | Unlinkable account's prepaid fee reserve is below the selected inline/IPFS transfer fee | Call `depositFees(wallet, accountId, amount)` to top up; use `getFeeToken()` and the matching anonymous fee getter |
+| Fairycloak HTTP error              | Relay unreachable or request rejected                                 | Check the relay URL, API key, and account authorization                                                             |
 
 ---
 
 ## Security Considerations
 
-When using the StableTrust SDK, follow these best practices to ensure the security of your confidential transactions:
+When using the stabletrust SDK, follow these best practices to ensure the security of your confidential transactions:
 
 1. **Private Key Management**
    - Never expose or log private keys or seed phrases
    - Store private keys securely (e.g., hardware wallets, encrypted vaults)
-   - Anonymous account `privateKey` values are sensitive — treat them the same as wallet private keys
+   - Unlinkable account `privateKey` values are sensitive — treat them the same as wallet private keys
 
 2. **Signer Security**
    - Use secure signer implementations (e.g., hardware wallets, encrypted key stores)
@@ -622,7 +733,7 @@ When using the StableTrust SDK, follow these best practices to ensure the securi
 
 5. **Balance Verification**
    - Check available balance before initiating transfers
-   - Anonymous transfers between anonymous accounts require `applyPending()` before the recipient can spend
+   - Unlinkable transfers between unlinkable accounts require `applyPending()` before the recipient can spend
 
 6. **Error Handling**
    - Implement comprehensive error handling for all SDK operations

package/examples/anonymous-flow.js

@@ -24,7 +24,7 @@ dotenv.config();
 
 const EVM_RPC = process.env.EVM_RPC ?? "http://127.0.0.1:8545";
 const FAIRYCLOAK_URL = process.env.FAIRYCLOAK_URL ?? "http://127.0.0.1:8080";
-const CHAIN_ID = Number(process.env.CHAIN_ID ?? "31337");
+const CHAIN_ID = Number(process.env.CHAIN_ID ?? "5042002");
 const TOKEN_ADDRESS =
   process.env.TOKEN_ADDRESS ?? "0xE915164570b027C2A0FfadcB1B672192E35BF008";
 const TOKEN_DECIMALS = Number(process.env.TOKEN_DECIMALS ?? "6");
@@ -232,38 +232,49 @@ async function main() {
   console.log("\n── [5] Top up prepaid fees for anon1 ───────────────────");
 
   const feeToken = await client.getFeeToken();
-  const feeAmount = await client.getFeeAmount();
+  const inlineFee = await client.getAnonymousInlineTransferFee();
   log("  fee token  :", feeToken);
-  log("  fee/xfer   :", fmt(feeAmount, TOKEN_DECIMALS), "tokens");
-
-  const feeBalance = await client.getPrepaidFeeBalance(anon1Id, feeToken);
-  log("  fee balance:", fmt(feeBalance, TOKEN_DECIMALS), "tokens");
-
-  if (feeBalance < MIN_FEE_BALANCE) {
-    log(
-      `  balance < ${fmt(MIN_FEE_BALANCE, TOKEN_DECIMALS)}, depositing ${fmt(FEE_DEPOSIT_AMOUNT, TOKEN_DECIMALS)} fee tokens (anon1 pays gas) …`,
-    );
-    const fd = await client.depositFees(
-      anon1Wallet,
-      anon1Id,
-      FEE_DEPOSIT_AMOUNT,
-    );
-    log("  request_id:", fd.request_id, "  status:", fd.status);
-    if (fd.error) log("    [!] Error:", fd.error);
-    if (fd.tx_hash) log("  tx_hash   :", fd.tx_hash);
-
-    const fdFinal = await client.waitForRequest(fd.request_id, {
-      timeoutMs: 180_000,
-    });
-    log("  status    :", fdFinal.status, "  tx_hash:", fdFinal.tx_hash ?? "—");
-    if (fdFinal.error) log("    [!] Error:", fdFinal.error);
-
-    const newFeeBalance = await client.getPrepaidFeeBalance(anon1Id, feeToken);
-    log("  new fee balance:", fmt(newFeeBalance, TOKEN_DECIMALS), "tokens");
+  log("  inline fee :", fmt(inlineFee, TOKEN_DECIMALS), "tokens");
+
+  if (inlineFee === 0n) {
+    log("  no fee configured — transactions are free, skipping top-up.");
   } else {
-    log(
-      `  fee balance sufficient (${fmt(feeBalance, TOKEN_DECIMALS)} ≥ ${fmt(MIN_FEE_BALANCE, TOKEN_DECIMALS)}), skipping deposit.`,
-    );
+    const feeBalance = await client.getPrepaidFeeBalance(anon1Id, feeToken);
+    log("  fee balance:", fmt(feeBalance, TOKEN_DECIMALS), "tokens");
+
+    const requiredFeeBalance =
+      inlineFee > MIN_FEE_BALANCE ? inlineFee : MIN_FEE_BALANCE;
+
+    if (feeBalance < requiredFeeBalance) {
+      const currency = feeToken === ethers.ZeroAddress ? "native" : "ERC-20";
+      const deficit = requiredFeeBalance - feeBalance;
+      const topUpAmount =
+        FEE_DEPOSIT_AMOUNT > deficit ? FEE_DEPOSIT_AMOUNT : deficit;
+      log(
+        `  balance < ${fmt(requiredFeeBalance, TOKEN_DECIMALS)}, depositing ${fmt(topUpAmount, TOKEN_DECIMALS)} ${currency} fee tokens (anon1 pays gas) …`,
+      );
+      const fd = await client.depositFees(
+        anon1Wallet,
+        anon1Id,
+        topUpAmount,
+      );
+      log("  request_id:", fd.request_id, "  status:", fd.status);
+      if (fd.error) log("    [!] Error:", fd.error);
+      if (fd.tx_hash) log("  tx_hash   :", fd.tx_hash);
+
+      const fdFinal = await client.waitForRequest(fd.request_id, {
+        timeoutMs: 180_000,
+      });
+      log("  status    :", fdFinal.status, "  tx_hash:", fdFinal.tx_hash ?? "—");
+      if (fdFinal.error) log("    [!] Error:", fdFinal.error);
+
+      const newFeeBalance = await client.getPrepaidFeeBalance(anon1Id, feeToken);
+      log("  new fee balance:", fmt(newFeeBalance, TOKEN_DECIMALS), "tokens");
+    } else {
+      log(
+        `  fee balance sufficient (${fmt(feeBalance, TOKEN_DECIMALS)} ≥ ${fmt(requiredFeeBalance, TOKEN_DECIMALS)}), skipping deposit.`,
+      );
+    }
   }
 
   // ── [6] Transfer anon1 → anon2 ───────────────────────────────────────────────

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fairblock/stabletrust",
-  "version": "2.0.6",
+  "version": "2.0.10",
   "description": "SDK for confidential transfers using homomorphic encryption and zero-knowledge proofs",
   "main": "src/index.js",
   "types": "src/index.d.ts",
@@ -28,7 +28,10 @@
     "url": "https://github.com/Fairblock/stabletrust-sdk"
   },
   "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
+    "test": "node --test test/*.test.mjs",
+    "test:live": "node --test test/ipfs-live.mjs",
+    "check:abi": "node scripts/check-contract-abi.mjs",
+    "check": "npm run check:abi && npm test"
   },
   "keywords": [
     "confidential",
@@ -41,10 +44,14 @@
   "author": "",
   "license": "Apache-2.0",
   "dependencies": {
+    "@noble/bls12-381": "^1.4.0",
+    "@noble/hashes": "^1.3.2",
+    "@stablelib/chacha20poly1305": "^1.0.1",
+    "axios": "^1.16.0",
     "dotenv": "^17.2.3",
     "ethers": "^6.16.0"
   },
   "engines": {
-    "node": ">=16.0.0"
+    "node": ">=18.0.0"
   }
 }