@fairblock/stabletrust 1.0.14 → 1.0.16

package/README.md

@@ -38,12 +38,12 @@ The following contract addresses are available for confidential transfers on tes
 
 | Network(Testnet) | Chain ID | Contract Address                             |
 | :--------------- | :------- | :------------------------------------------- |
-| Stable           | 2201     | `0xb0b461aFA69b715d842c7fAb602f50D4cef83fe5` |
-| Arc              | 1244     | `0xEa837218c7Ccd9eA1BCfB640e5c6aFE59952b4FA` |
-| Base             | 84532    | `0x1a06530765e942a1D26B74d9558e9a1EdA615867` |
-| Ethereum         | 11155111 | `0xABEa3399873b80f528Ee76286087b45ed38Fbf97` |
-| Arbitrum         | 421614   | `0x2131De660C6be8b535E6f17E171bFf7143E9E9F4` |
-| Tempo            | 42431    | `0xF3525FF8F592883f8fA2d89EfBe85637955Df487` |
+| Stable           | 2201     | `0xB96aa42b246a956B170fE426A72fB610E4976f9E` |
+| Arc              | 1244     | `0xb20aB54e1c6AE55B0DD11FEB7FFf3fF1E9631f19` |
+| Base             | 84532    | `0x962a8A7CD28BfFBb17C4F6Ec388782cca3ffd618` |
+| Ethereum         | 11155111 | `0x2E48F3D9b8F4aCA9E6AF0630eaB2ceB7A3f5eEd1` |
+| Arbitrum         | 421614   | `0x14Afd604971bee5b5fac52df2d56CaE421519Cc5` |
+| Tempo            | 42431    | `0x08B6563C95dfe3a4F5533CAA6F7D55a74FCb4F6c` |
 
 ## Usage
 
@@ -97,21 +97,23 @@ const tempoClient = new ConfidentialTransferClient(
 
 **Note on Tempo Chain**: The Tempo network (chainId 42431) uses token-based fees instead of native currency. The SDK automatically handles fee payment using PathUSD when detected.
 
-### Token Denomination (x100)
+### Token Denomination
 
-All confidential token amounts in this SDK use a fixed scale of 100. That means the SDK expects amounts in "token \* 100" units for deposit, transfer, and withdraw. When displaying balances, divide by 100.
+When interacting with the SDK for deposit, transfer, and withdraw operations, you should parse the token amount using the underlying token's decimals. When displaying the fetched balance, format it using the token's decimals.
 
-- To deposit 0.1 tokens, send 10 units (0.1 \* 100).
-- To display a balance, use $display = raw / 100$.
+- To deposit, transfer, or withdraw tokens, parse the amount using `ethers.parseUnits(amount, tokenDecimals)`.
+- To display a balance, format the raw amount using `ethers.formatUnits(balance.amount, tokenDecimals)`.
 
 **Recommended helpers (consistent with examples):**
 
 ```javascript
-// Use 2 decimals to match x100 scaling
-const amountToDeposit = ethers.parseUnits("0.1", 2); // 10
+// Fetch or define your token's decimals (e.g., 6 for USDC)
+const tokenDecimals = 6;
+
+const amountToDeposit = ethers.parseUnits("0.1", tokenDecimals);
 await client.confidentialDeposit(signer, tokenAddress, amountToDeposit);
 
-const amountToTransfer = ethers.parseUnits("0.05", 2); // 5
+const amountToTransfer = ethers.parseUnits("0.05", tokenDecimals);
 await client.confidentialTransfer(
   signer,
   recipientAddress,
@@ -119,7 +121,7 @@ await client.confidentialTransfer(
   amountToTransfer,
 );
 
-const amountToWithdraw = ethers.parseUnits("0.02", 2); // 2
+const amountToWithdraw = ethers.parseUnits("0.02", tokenDecimals);
 await client.withdraw(signer, tokenAddress, amountToWithdraw);
 
 const balance = await client.getConfidentialBalance(
@@ -127,7 +129,7 @@ const balance = await client.getConfidentialBalance(
   privateKey,
   tokenAddress,
 );
-console.log("Balance:", ethers.formatUnits(balance.amount, 2));
+console.log("Balance:", ethers.formatUnits(balance.amount, tokenDecimals));
 ```
 
 ### Key Functions
@@ -162,9 +164,9 @@ Retrieves the decrypted available and pending balances for a specific token, plu
   - `privateKey` (string): The private key for decryption.
   - `tokenAddress` (string): The token contract address.
 - **Returns**: An object containing:
-  - `amount` (number): The total (available + pending) in x100 units
-  - `available` (object): `{ amount, ciphertext }` in x100 units
-  - `pending` (object): `{ amount, ciphertext }` in x100 units
+  - `amount` (bigint): The total (available + pending)
+  - `available` (object): `{ amount, ciphertext }`
+  - `pending` (object): `{ amount, ciphertext }`
 
 #### `confidentialDeposit(signer, tokenAddress, amount, options)`
 
@@ -173,7 +175,7 @@ Deposits a specified amount of ERC20 tokens into the confidential contract, conv
 - **Parameters**:
   - `signer` (ethers.Signer): The transaction signer.
   - `tokenAddress` (string): The contract address of the ERC20 token.
-  - `amount` (bigint | string | number): The amount to deposit in x100 units.
+  - `amount` (bigint | string | number): The amount to deposit, parsed with token decimals.
   - `options` (object, optional):
     - `waitForFinalization` (boolean): Wait for deposit finalization. Default: `true`
 - **Returns**: A transaction receipt.
@@ -186,7 +188,7 @@ Executes a confidential transfer of tokens from the sender to a recipient. The a
   - `signer` (ethers.Signer): The sender's signer.
   - `recipientAddress` (string): The public address of the recipient.
   - `tokenAddress` (string): The token contract address.
-  - `amount` (number): The amount to transfer in x100 units.
+  - `amount` (bigint | string | number): The amount to transfer, parsed with token decimals.
   - `options` (object, optional):
     - `useOffchainVerify` (boolean): Use offchain verification. Default: `false`
     - `waitForFinalization` (boolean): Wait for transfer finalization. Default: `true`
@@ -199,7 +201,7 @@ Withdraws funds from the confidential "available" balance back to the public lay
 - **Parameters**:
   - `signer` (ethers.Signer): The user's signer.
   - `tokenAddress` (string): The token contract address.
-  - `amount` (number): The amount to withdraw in x100 units.
+  - `amount` (bigint | string | number): The amount to withdraw, parsed with token decimals.
   - `options` (object, optional):
     - `useOffchainVerify` (boolean): Use offchain verification. Default: `false`
     - `waitForFinalization` (boolean): Wait for withdrawal finalization. Default: `true`
@@ -288,7 +290,7 @@ When using the StableTrust SDK, follow these best practices to ensure the securi
 
 5. **Balance Verification**
 
-- Check available balance before initiating transfers (values are in x100 units)
+- Check available balance before initiating transfers
 - Be aware of transaction fees that may vary by network
 - On Tempo chain, ensure sufficient PathUSD balance for fee payment
 

package/examples/complete-flow.js

@@ -1,7 +1,7 @@
 import { ethers } from "ethers";
 import dotenv from "dotenv";
 import { ConfidentialTransferClient } from "@fairblock/stabletrust";
-
+import { ERC20_ABI } from "./constants.js";
 dotenv.config();
 
 /**
@@ -11,9 +11,6 @@ dotenv.config();
  * https://docs.fairblock.network/docs/confidential_transfers/technical_overview
  */
 
-// Optional override for custom confidential contract deployments.
-const CONTRACT_ADDRESS =
-  process.env.CONTRACT_ADDRESS || "0xb0b461aFA69b715d842c7fAb602f50D4cef83fe5";
 // Standard ERC20 token contract. Any ERC20 on this chain ID can be used.
 const TOKEN_ADDRESS =
   process.env.TOKEN_ADDRESS || "0x78Cf24370174180738C5B8E352B6D14c83a6c9A9";
@@ -42,11 +39,7 @@ async function trackPerformance(actionName, action) {
 async function main() {
   console.log("=== Starting Confidential Flow Performance Test ===\n");
 
-  const client = new ConfidentialTransferClient(
-    RPC_URL,
-    CONTRACT_ADDRESS,
-    Number(CHAIN_ID),
-  );
+  const client = new ConfidentialTransferClient(RPC_URL, Number(CHAIN_ID));
 
   const provider = new ethers.JsonRpcProvider(RPC_URL);
   const sender = new ethers.Wallet(process.env.SENDER_PRIVATE_KEY, provider);
@@ -55,6 +48,9 @@ async function main() {
     provider,
   );
 
+  const tokenContract = new ethers.Contract(TOKEN_ADDRESS, ERC20_ABI, provider);
+  const tokenDecimals = await tokenContract.decimals();
+
   console.log("Sender Address:", sender.address);
   console.log("Recipient Address:", recipient.address);
 
@@ -62,7 +58,7 @@ async function main() {
   const recipientKeys = await client.ensureAccount(recipient);
 
   // 1. DEPOSIT PHASE
-  const depositAmount = ethers.parseUnits("0.1", 2);
+  const depositAmount = ethers.parseUnits("0.1", tokenDecimals);
   const senderConfidentialBalanceBefore = await client.getConfidentialBalance(
     sender.address,
     senderKeys.privateKey,
@@ -71,7 +67,7 @@ async function main() {
 
   console.log(
     "Sender Confidential Balance (Pre-Deposit):",
-    ethers.formatUnits(senderConfidentialBalanceBefore.amount, 2),
+    ethers.formatUnits(senderConfidentialBalanceBefore.amount, tokenDecimals),
   );
 
   console.log("Depositing 0.1 tokens into confidential contract...");
@@ -91,11 +87,11 @@ async function main() {
   );
   console.log(
     "Sender Confidential Balance (Post-Deposit):",
-    ethers.formatUnits(senderConfidentialBalanceAfterDep.amount, 2),
+    ethers.formatUnits(senderConfidentialBalanceAfterDep.amount, tokenDecimals),
   );
 
   // 2. TRANSFER PHASE
-  const transferAmount = ethers.parseUnits("0.05", 2);
+  const transferAmount = ethers.parseUnits("0.05", tokenDecimals);
   const senderConfidentialBalanceBeforeTx = await client.getConfidentialBalance(
     sender.address,
     senderKeys.privateKey,
@@ -111,11 +107,14 @@ async function main() {
 
   console.log(
     "Sender Confidential Balance (Pre-Transfer):",
-    ethers.formatUnits(senderConfidentialBalanceBeforeTx.amount, 2),
+    ethers.formatUnits(senderConfidentialBalanceBeforeTx.amount, tokenDecimals),
   );
   console.log(
     "Recipient Confidential Balance (Pre-Transfer):",
-    ethers.formatUnits(recipientConfidentialBalanceBeforeTx.amount, 2),
+    ethers.formatUnits(
+      recipientConfidentialBalanceBeforeTx.amount,
+      tokenDecimals,
+    ),
   );
 
   console.log("Transferring 0.05 tokens confidentially to recipient...");
@@ -152,22 +151,22 @@ async function main() {
 
   console.log(
     "Sender Confidential Balance (Post-Transfer):",
-    ethers.formatUnits(senderConfidentialBalanceAfterTx.amount, 2),
+    ethers.formatUnits(senderConfidentialBalanceAfterTx.amount, tokenDecimals),
   );
   console.log(
     "Recipient Confidential Balance (Post-Transfer):",
-    ethers.formatUnits(recipientConfidentialBalanceAfterTx.amount, 2),
+    ethers.formatUnits(
+      recipientConfidentialBalanceAfterTx.amount,
+      tokenDecimals,
+    ),
     "\n",
   );
 
   // 3. WITHDRAW PHASE
-  const withdrawAmount = ethers.parseUnits("0.05", 2);
+  const withdrawAmount = ethers.parseUnits("0.05", tokenDecimals);
   console.log(
     "Withdrawing 0.05 tokens from confidential contract to recipient's public balance...",
   );
-  const withdrawRes = await trackPerformance("WITHDRAW_TOKENS", () =>
-    client.withdraw(recipient, TOKEN_ADDRESS, withdrawAmount),
-  );
   let recipientConfidentialBalanceBeforeWithdraw =
     await client.getConfidentialBalance(
       recipient.address,
@@ -177,8 +176,15 @@ async function main() {
 
   console.log(
     "Recipient Confidential Balance (Pre-Withdraw):",
-    ethers.formatUnits(recipientConfidentialBalanceBeforeWithdraw.amount, 2),
+    ethers.formatUnits(
+      recipientConfidentialBalanceBeforeWithdraw.amount,
+      tokenDecimals,
+    ),
   );
+  const withdrawRes = await trackPerformance("WITHDRAW_TOKENS", () =>
+    client.withdraw(recipient, TOKEN_ADDRESS, withdrawAmount),
+  );
+
   const withdrawHash = withdrawRes.result.hash;
   console.log(`Transaction Hash: ${withdrawHash}`);
   console.log(`View Transaction: ${EXPLORER_URL}${withdrawHash}`);
@@ -192,7 +198,10 @@ async function main() {
 
   console.log(
     "Recipient Confidential Balance (Final):",
-    ethers.formatUnits(recipientConfidentialBalanceAfterWithdraw.amount, 2),
+    ethers.formatUnits(
+      recipientConfidentialBalanceAfterWithdraw.amount,
+      tokenDecimals,
+    ),
   );
 
   console.log("\n=== Complete Flow Execution Finished ===");

package/examples/constants.js

@@ -0,0 +1,6 @@
+export const ERC20_ABI = [
+  "function approve(address spender, uint256 amount) external returns (bool)",
+  "function allowance(address owner, address spender) external view returns (uint256)",
+  "function balanceOf(address account) external view returns (uint256)",
+  "function decimals() external view returns (uint8)",
+];

package/examples/simple-snippets.js

@@ -19,9 +19,10 @@ async function minimalFlow() {
   // 2. Initialize Confidential Accounts (View Keys)
   await client.ensureAccount(sender);
   await client.ensureAccount(recipient);
-
+  const tokenContract = new ethers.Contract(TOKEN_ADDRESS, ERC20_ABI, provider);
+  const tokenDecimals = await tokenContract.decimals();
   const TOKEN = "0x78Cf24370174180738C5B8E352B6D14c83a6c9A9";
-  const amount = ethers.parseUnits("0.1", 2);
+  const amount = ethers.parseUnits("0.1", tokenDecimals);
   let res;
   // 3. DEPOSIT: Move public ERC20 into the confidential contract
   res = await client.confidentialDeposit(sender, TOKEN, amount);
@@ -32,11 +33,15 @@ async function minimalFlow() {
     sender,
     recipient.address,
     TOKEN,
-    ethers.parseUnits("0.05", 2),
+    ethers.parseUnits("0.05", tokenDecimals),
   );
   console.log("Transfer TX Hash:", EXPLORER_URL + res.hash);
   // 5. WITHDRAW: Convert confidential balance back to public ERC20
-  res = await client.withdraw(recipient, TOKEN, ethers.parseUnits("0.05", 2));
+  res = await client.withdraw(
+    recipient,
+    TOKEN,
+    ethers.parseUnits("0.05", tokenDecimals),
+  );
   console.log("Withdraw TX Hash:", EXPLORER_URL + res.hash);
   console.log("Confidential flow complete.");
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fairblock/stabletrust",
-  "version": "1.0.14",
+  "version": "1.0.16",
   "description": "SDK for confidential transfers using homomorphic encryption and zero-knowledge proofs",
   "main": "src/index.js",
   "types": "src/index.d.ts",

package/src/client.js

@@ -288,18 +288,24 @@ export class ConfidentialTransferClient {
       }
 
       if ((!c1 || c1 === "0x") && (!c2 || c2 === "0x")) {
-        return { amount: 0, ciphertext: null };
+        return { amount: 0n, ciphertext: null };
       }
 
       const wasm = await this._getWasm();
       const ciphertext = combineCiphertext(c1, c2);
-      const amount = decryptCiphertext(
+      const contractAmount = decryptCiphertext(
         ciphertext,
         privateKey,
         wasm.decrypt_ciphertext,
       );
+      const tokenAmount = ethers.formatUnits(contractAmount, 2);
+      const tokenContract = this._getTokenContract(tokenAddress);
+      const tokenUnits = await tokenContract.decimals();
 
-      return { amount, ciphertext };
+      return {
+        amount: ethers.parseUnits(tokenAmount, Number(tokenUnits)),
+        ciphertext,
+      };
     } catch (error) {
       throw new Error(`Failed to get balance: ${error.message}`);
     }
@@ -360,8 +366,11 @@ export class ConfidentialTransferClient {
         tokenAddress,
         "deposit",
       );
-      const depositAmount = BigInt(amount);
+
       const tokenContract = this._getTokenContract(tokenAddress);
+      const tokenDecimals = await tokenContract.decimals();
+      const depositAmount =
+        (BigInt(amount) * 100n) / 10n ** BigInt(tokenDecimals);
 
       // Check token balance and allowance in parallel
       const [tokenBalance, allowance] = await Promise.all([
@@ -370,11 +379,11 @@ export class ConfidentialTransferClient {
       ]);
       if (tokenBalance < depositAmount) {
         throw new Error(
-          `Insufficient token balance. Required: ${depositAmount}, Available: ${tokenBalance}`,
+          `Insufficient token balance. Required: ${amount}, Available: ${tokenBalance}`,
         );
       }
 
-      if (allowance < depositAmount) {
+      if (allowance < amount) {
         const approveTx = await tokenContract
           .connect(wallet)
           .approve(this.config.contractAddress, ethers.MaxUint256);
@@ -442,6 +451,10 @@ export class ConfidentialTransferClient {
       if (!amount || amount <= 0) {
         throw new Error("Transfer amount must be greater than 0");
       }
+      const tokenContract = this._getTokenContract(tokenAddress);
+      const tokenDecimals = await tokenContract.decimals();
+      const transferAmount =
+        (BigInt(amount) * 100n) / 10n ** BigInt(tokenDecimals);
 
       const senderAddress = await senderWallet.getAddress();
 
@@ -498,28 +511,28 @@ export class ConfidentialTransferClient {
           "Current balance ciphertext is required. Did you call getConfidentialBalance()?",
         );
       }
-      if (balanceSummary.amount < amount) {
+      if (balanceSummary.amount < BigInt(amount)) {
         throw new Error(
           `Insufficient balance. Required: ${amount}, Total: ${balanceSummary.amount}`,
         );
       }
       if (
         derivedCurrentBalance === undefined ||
-        derivedCurrentBalance < amount
+        derivedCurrentBalance < BigInt(amount)
       ) {
         throw new Error(
           `Insufficient balance. Required: ${amount}, Available: ${derivedCurrentBalance}`,
         );
       }
 
+      const currentBalanceContractScale =
+        (BigInt(derivedCurrentBalance) * 100n) / 10n ** BigInt(tokenDecimals);
+
       // Generate proof
       const proofInput = {
         current_balance_ciphertext: derivedCurrentBalanceCiphertext,
-        current_balance:
-          typeof derivedCurrentBalance === "bigint"
-            ? derivedCurrentBalance.toString()
-            : derivedCurrentBalance,
-        transfer_amount: typeof amount === "bigint" ? Number(amount) : amount,
+        current_balance: Number(currentBalanceContractScale),
+        transfer_amount: Number(transferAmount),
         source_keypair: derivedSenderKeys.privateKey,
         destination_pubkey: derivedRecipientPublicKey,
       };
@@ -753,6 +766,11 @@ export class ConfidentialTransferClient {
         throw new Error("Withdrawal amount must be greater than 0");
       }
 
+      const tokenContract = this._getTokenContract(tokenAddress);
+      const tokenDecimals = await tokenContract.decimals();
+      const withdrawAmount =
+        (BigInt(amount) * 100n) / 10n ** BigInt(tokenDecimals);
+
       // Auto-derive keys
       const derivedKeys = await this._deriveKeys(wallet);
       if (!derivedKeys?.privateKey) {
@@ -780,25 +798,25 @@ export class ConfidentialTransferClient {
           "Current balance ciphertext is required. Did you call getConfidentialBalance()?",
         );
       }
-      if (balanceSummary.amount < amount) {
+      if (balanceSummary.amount < BigInt(amount)) {
         throw new Error(
           `Insufficient balance. Required: ${amount}, Total: ${balanceSummary.amount}`,
         );
       }
-      if (currentBalance === undefined || currentBalance < amount) {
+      if (currentBalance === undefined || currentBalance < BigInt(amount)) {
         throw new Error(
           `Insufficient balance. Required: ${amount}, Available: ${currentBalance}`,
         );
       }
 
+      const currentBalanceContractScale =
+        (BigInt(currentBalance) * 100n) / 10n ** BigInt(tokenDecimals);
+
       // Generate withdrawal proof
       const withdrawInput = {
         current_balance_ciphertext: currentBalanceCiphertext,
-        current_balance:
-          typeof currentBalance === "bigint"
-            ? Number(currentBalance)
-            : currentBalance,
-        withdraw_amount: typeof amount === "bigint" ? Number(amount) : amount,
+        current_balance: Number(currentBalanceContractScale),
+        withdraw_amount: Number(withdrawAmount),
         keypair: derivedKeys.privateKey,
       };
 
@@ -819,7 +837,7 @@ export class ConfidentialTransferClient {
         .connect(wallet)
         .withdraw(
           tokenAddress,
-          BigInt(amount),
+          BigInt(withdrawAmount),
           ethers.getBytes(encodeWithdrawProof(proof.data)),
           useOffchainVerify,
         );

package/src/constants.js

@@ -18,18 +18,19 @@ export const ERC20_ABI = [
   "function approve(address spender, uint256 amount) external returns (bool)",
   "function allowance(address owner, address spender) external view returns (uint256)",
   "function balanceOf(address account) external view returns (uint256)",
+  "function decimals() external view returns (uint8)",
 ];
 
 export const TEMPO_FEE_TOKEN_ADDRESS =
   "0x20c0000000000000000000000000000000000000";
 
 export const STABLETRUST_CONTRACTS_BY_CHAIN_ID = Object.freeze({
-  2201: "0xb0b461aFA69b715d842c7fAb602f50D4cef83fe5", //Stable
-  1244: "0xEa837218c7Ccd9eA1BCfB640e5c6aFE59952b4FA", //Arc
-  84532: "0x1a06530765e942a1D26B74d9558e9a1EdA615867", //Base
-  11155111: "0xABEa3399873b80f528Ee76286087b45ed38Fbf97", //Ethereum
-  421614: "0x2131De660C6be8b535E6f17E171bFf7143E9E9F4", //Arbitrum
-  42431: "0xF3525FF8F592883f8fA2d89EfBe85637955Df487", //Tempo
+  2201: "0xB96aa42b246a956B170fE426A72fB610E4976f9E", //Stable
+  1244: "0xb20aB54e1c6AE55B0DD11FEB7FFf3fF1E9631f19", //Arc
+  84532: "0x962a8A7CD28BfFBb17C4F6Ec388782cca3ffd618", //Base
+  11155111: "0x2E48F3D9b8F4aCA9E6AF0630eaB2ceB7A3f5eEd1", //Ethereum
+  421614: "0x14Afd604971bee5b5fac52df2d56CaE421519Cc5", //Arbitrum
+  42431: "0x08B6563C95dfe3a4F5533CAA6F7D55a74FCb4F6c", //Tempo
 });
 
 export function getStableTrustContractAddress(chainId) {

package/src/crypto.js

@@ -11,7 +11,7 @@ import { ethers } from "ethers";
  */
 export async function deriveKeys(wallet, config, generateKeypair) {
   const domain = {
-    name: "Fairblock",
+    name: "ConfidentialTokens",
     version: "1",
     chainId: config.chainId,
     verifyingContract: config.contractAddress,
@@ -26,15 +26,15 @@ export async function deriveKeys(wallet, config, generateKeypair) {
   };
 
   const contextHash = ethers.keccak256(
-    ethers.solidityPacked(
+    ethers.AbiCoder.defaultAbiCoder().encode(
       ["uint256", "address", "address", "string"],
       [config.chainId, config.contractAddress, ethers.ZeroAddress, "main"],
     ),
   );
-
+  const userAddress = wallet.address.toLowerCase();
   const message = {
     purpose: "homomorphic-key-derive-v1",
-    user: wallet.address,
+    user: userAddress,
     context: contextHash,
   };
 
@@ -42,7 +42,7 @@ export async function deriveKeys(wallet, config, generateKeypair) {
   const domainContext = JSON.stringify({
     chainId: config.chainId.toString(),
     verifyingContract: config.contractAddress,
-    user: wallet.address,
+    user: userAddress,
     purpose: "homomorphic-key-derive-v1",
     version: "1",
   });