@fairblock/stabletrust 1.0.7 → 1.0.8

package/README.md

@@ -38,7 +38,7 @@ The following contract addresses are available for confidential transfers on tes
 
 | Network  | Chain ID | Contract Address                             |
 | :------- | :------- | :------------------------------------------- |
-| Stable   | 2201     | `0x4735ab83c87Dea00A5B6377f477fe60C848D29d6` |
+| Stable   | 2201     | `0x29E4fd434758b1677c10854Fa81C2fc496D76E62` |
 | Arc      | 1244     | `0x1Bf79BF5A32D6f3cdce3fe1A93c3fB222Bc93bb3` |
 | Base     | 84532    | `0x73D2bc5B5c7aF5C3726E7bEf0BD8b4931923fdA9` |
 | Ethereum | 11155111 | `0xD765Dff7D734ABE09f88991A46BAb73ACa8910EF` |
@@ -94,17 +94,50 @@ 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)
+
+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.
+
+- To deposit 0.1 tokens, send 10 units (0.1 \* 100).
+- To display a balance, use $display = raw / 100$.
+
+**Recommended helpers (consistent with examples):**
+
+```javascript
+// Use 2 decimals to match x100 scaling
+const amountToDeposit = ethers.parseUnits("0.1", 2); // 10
+await client.confidentialDeposit(signer, tokenAddress, amountToDeposit);
+
+const amountToTransfer = ethers.parseUnits("0.05", 2); // 5
+await client.confidentialTransfer(
+  signer,
+  recipientAddress,
+  tokenAddress,
+  amountToTransfer,
+);
+
+const amountToWithdraw = ethers.parseUnits("0.02", 2); // 2
+await client.withdraw(signer, tokenAddress, amountToWithdraw);
+
+const balance = await client.getConfidentialBalance(
+  signer.address,
+  privateKey,
+  tokenAddress,
+);
+console.log("Balance:", ethers.formatUnits(balance.amount, 2));
+```
+
 ### Key Functions
 
 The following methods are the primary entry points for interacting with the confidential system.
 
-#### `deriveKeys(signer)`
+#### `getAccountInfo(address)`
 
-Derives the encryption keypair for a wallet. These keys are used for all confidential operations.
+Fetches account core information from the contract.
 
 - **Parameters**:
-  - `signer` (ethers.Signer): The ethers.js signer instance for the user.
-- **Returns**: An object containing `publicKey` and `privateKey` (base64-encoded).
+  - `address` (string): The account address.
+- **Returns**: Contract account data (exists, finalized, pubkey, etc.).
 
 #### `ensureAccount(signer, options)`
 
@@ -117,31 +150,32 @@ Initializes or retrieves the cryptographic keys associated with an account. This
     - `maxAttempts` (number): Maximum attempts to check finalization. Default: `30`
 - **Returns**: An object containing the user's private and public keys for the confidential system.
 
-#### `getBalance(address, privateKey, tokenAddress, options)`
+#### `getConfidentialBalance(address, privateKey, tokenAddress)`
 
-Retrieves the decrypted balance for a specific token in the confidential account.
+Retrieves the decrypted available and pending balances for a specific token, plus the total.
 
 - **Parameters**:
   - `address` (string): The account address.
   - `privateKey` (string): The private key for decryption.
   - `tokenAddress` (string): The token contract address.
-  - `options` (object, optional):
-    - `type` (string): Balance type—`'available'` or `'pending'`. Default: `'available'`
-- **Returns**: An object containing `amount` (number) and `ciphertext` (string).
+- **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
 
-#### `deposit(signer, tokenAddress, amount, options)`
+#### `confidentialDeposit(signer, tokenAddress, amount, options)`
 
 Deposits a specified amount of ERC20 tokens into the confidential contract, converting them into a "pending" confidential balance.
 
 - **Parameters**:
   - `signer` (ethers.Signer): The transaction signer.
   - `tokenAddress` (string): The contract address of the ERC20 token.
-  - `amount` (bigint | string | number): The amount to deposit (ensure proper unit scaling).
+  - `amount` (bigint | string | number): The amount to deposit in x100 units.
   - `options` (object, optional):
     - `waitForFinalization` (boolean): Wait for deposit finalization. Default: `true`
 - **Returns**: A transaction receipt.
 
-#### `transfer(signer, recipientAddress, tokenAddress, amount, options)`
+#### `confidentialTransfer(signer, recipientAddress, tokenAddress, amount, options)`
 
 Executes a confidential transfer of tokens from the sender to a recipient. The amount and nature of the transfer are encrypted.
 
@@ -149,22 +183,12 @@ 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.
+  - `amount` (number): The amount to transfer in x100 units.
   - `options` (object, optional):
     - `useOffchainVerify` (boolean): Use offchain verification. Default: `false`
     - `waitForFinalization` (boolean): Wait for transfer finalization. Default: `true`
 - **Returns**: A transaction receipt.
 
-#### `applyPending(signer, options)`
-
-Moves funds from the "pending" balance to the "available" balance. This is often necessary for the recipient to utilize received funds.
-
-- **Parameters**:
-  - `signer` (ethers.Signer): The user's signer.
-  - `options` (object, optional):
-    - `waitForFinalization` (boolean): Wait for operation finalization. Default: `true`
-- **Returns**: A transaction receipt.
-
 #### `withdraw(signer, tokenAddress, amount, options)`
 
 Withdraws funds from the confidential "available" balance back to the public layer (ERC20 tokens).
@@ -172,40 +196,12 @@ 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.
+  - `amount` (number): The amount to withdraw in x100 units.
   - `options` (object, optional):
     - `useOffchainVerify` (boolean): Use offchain verification. Default: `false`
     - `waitForFinalization` (boolean): Wait for withdrawal finalization. Default: `true`
 - **Returns**: A transaction receipt.
 
-#### `waitForPendingBalance(address, privateKey, tokenAddress, options)`
-
-Polls for pending balance to appear after a transfer (typically after another user calls `applyPending`).
-
-- **Parameters**:
-  - `address` (string): The account address.
-  - `privateKey` (string): The private key for decryption.
-  - `tokenAddress` (string): The token contract address.
-  - `options` (object, optional):
-    - `maxAttempts` (number): Maximum polling attempts. Default: `60`
-    - `intervalMs` (number): Polling interval in milliseconds. Default: `3000`
-- **Returns**: An object containing `amount` and `ciphertext`.
-
-#### `getFeeAmount()`
-
-Retrieves the current fee amount required for confidential transfers on the network.
-
-- **Returns**: The fee amount in wei (bigint).
-
-#### `getTokenBalance(address, tokenAddress)`
-
-Retrieves the public ERC20 token balance for an address (non-confidential).
-
-- **Parameters**:
-  - `address` (string): The account address.
-  - `tokenAddress` (string): The token contract address.
-- **Returns**: The token balance (bigint).
-
 ### Examples
 
 For a complete implementation demonstrating the full lifecycle of a confidential transaction—from deposit to withdrawal—please refer to the `examples/complete-flow.js` file included in this repository.
@@ -221,7 +217,12 @@ The SDK provides descriptive error messages for common issues. Here are some typ
 
 ```javascript
 try {
-  await client.transfer(signer, recipientAddress, tokenAddress, amount);
+  await client.confidentialTransfer(
+    signer,
+    recipientAddress,
+    tokenAddress,
+    amount,
+  );
 } catch (error) {
   if (error.message.includes("Insufficient balance")) {
     console.error("Transfer amount exceeds available balance");
@@ -251,12 +252,12 @@ The following are estimated execution times for standard operations within the c
 
 The following are estimated execution times for standard operations within the confidential flow. Please note that these durations may vary based on network congestion and client hardware performance.
 
-| Operation     | Avg Duration |
-| :------------ | :----------- |
-| Deposit       | 63s          |
-| Transfer      | 58s          |
-| Apply Pending | 61s          |
-| Withdraw      | 58s          |
+| Operation | Avg Duration |
+| :-------- | :----------- |
+| Creation  | 45s          |
+| Deposit   | 63s          |
+| Transfer  | 58s          |
+| Withdraw  | 58s          |
 
 ## Security Considerations
 
@@ -283,9 +284,10 @@ When using the StableTrust SDK, follow these best practices to ensure the securi
    - Allow sufficient time for account finalization before proceeding with operations
 
 5. **Balance Verification**
-   - 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
+
+- Check available balance before initiating transfers (values are in x100 units)
+- Be aware of transaction fees that may vary by network
+- On Tempo chain, ensure sufficient PathUSD balance for fee payment
 
 6. **Error Handling**
    - Implement comprehensive error handling for all SDK operations

package/examples/complete-flow.js

@@ -11,18 +11,18 @@ dotenv.config();
  * https://docs.fairblock.network/docs/confidential_transfers/technical_overview
  */
 
-// Currently configured for Ethereum Sepolia confidential mirror contract.
+// Currently configured for Stable Testnet confidential mirror contract.
 // You can deploy your own confidential contract on any EVM network and use that.
 const CONTRACT_ADDRESS =
-  process.env.CONTRACT_ADDRESS || "0xD765Dff7D734ABE09f88991A46BAb73ACa8910EF";
+  process.env.CONTRACT_ADDRESS || "0x29E4fd434758b1677c10854Fa81C2fc496D76E62";
 // Standard ERC20 token contract. Any ERC20 on this chain ID can be used.
 const TOKEN_ADDRESS =
-  process.env.TOKEN_ADDRESS || "0x1c7D4B196Cb0C7B01d743Fbc6116a902379C7238";
+  process.env.TOKEN_ADDRESS || "0x78Cf24370174180738C5B8E352B6D14c83a6c9A9";
 const RPC_URL =
-  process.env.ETHEREUM_RPC_URL || "https://ethereum-sepolia-rpc.publicnode.com";
+  process.env.ETHEREUM_RPC_URL || "https://rpc.testnet.stable.xyz";
 const EXPLORER_URL =
-  process.env.EXPLORER_URL || "https://sepolia.etherscan.io/tx/";
-const CHAIN_ID = process.env.CHAIN_ID || 11155111;
+  process.env.EXPLORER_URL || "https://testnet.stablescan.xyz/tx/";
+const CHAIN_ID = process.env.CHAIN_ID || 2201;
 1;
 
 /**
@@ -64,141 +64,109 @@ async function main() {
   const recipientKeys = await client.ensureAccount(recipient);
 
   // 1. DEPOSIT PHASE
-  const depositAmount = ethers.parseUnits("0.1", 6);
-  const senderAvailBeforeDep = await client.getBalance(
+  const depositAmount = ethers.parseUnits("0.1", 2);
+  const senderConfidentialBalanceBefore = await client.getConfidentialBalance(
     sender.address,
     senderKeys.privateKey,
     TOKEN_ADDRESS,
-    { type: "available" },
   );
+
   console.log(
-    "Sender Available (Pre-Deposit):",
-    ethers.formatUnits(senderAvailBeforeDep.amount, 6),
+    "Sender Confidential Balance (Pre-Deposit):",
+    ethers.formatUnits(senderConfidentialBalanceBefore.amount, 2),
   );
 
+  console.log("Depositing 0.1 tokens into confidential contract...");
+
   const depRes = await trackPerformance("DEPOSIT_TOKENS", () =>
-    client.deposit(sender, TOKEN_ADDRESS, depositAmount),
+    client.confidentialDeposit(sender, TOKEN_ADDRESS, depositAmount),
   );
   // Fixed hash reference: checking for result.transactionHash or result.hash
   const depHash = depRes.result.hash;
   console.log(`Transaction Hash: ${depHash}`);
   console.log(`View Transaction: ${EXPLORER_URL}${depHash}`);
 
-  const senderAvailAfterDep = await client.getBalance(
+  const senderConfidentialBalanceAfterDep = await client.getConfidentialBalance(
     sender.address,
     senderKeys.privateKey,
     TOKEN_ADDRESS,
-    { type: "available" },
   );
   console.log(
-    "Sender Available (Post-Deposit):",
-    ethers.formatUnits(senderAvailAfterDep.amount, 6),
-    "\n",
+    "Sender Confidential Balance (Post-Deposit):",
+    ethers.formatUnits(senderConfidentialBalanceAfterDep.amount, 2),
   );
 
   // 2. TRANSFER PHASE
-  const transferAmount = ethers.parseUnits("0.05", 6);
-  const senderAvailBeforeTx = await client.getBalance(
+  const transferAmount = ethers.parseUnits("0.05", 2);
+  const senderConfidentialBalanceBeforeTx = await client.getConfidentialBalance(
     sender.address,
     senderKeys.privateKey,
     TOKEN_ADDRESS,
-    { type: "available" },
-  );
-  const recipientPendBeforeTx = await client.getBalance(
-    recipient.address,
-    recipientKeys.privateKey,
-    TOKEN_ADDRESS,
-    { type: "pending" },
   );
 
+  const recipientConfidentialBalanceBeforeTx =
+    await client.getConfidentialBalance(
+      recipient.address,
+      recipientKeys.privateKey,
+      TOKEN_ADDRESS,
+    );
+
   console.log(
-    "Sender Available (Pre-Transfer):",
-    ethers.formatUnits(senderAvailBeforeTx.amount, 6),
+    "Sender Confidential Balance (Pre-Transfer):",
+    ethers.formatUnits(senderConfidentialBalanceBeforeTx.amount, 2),
   );
   console.log(
-    "Recipient Pending (Pre-Transfer):",
-    ethers.formatUnits(recipientPendBeforeTx.amount, 6),
+    "Recipient Confidential Balance (Pre-Transfer):",
+    ethers.formatUnits(recipientConfidentialBalanceBeforeTx.amount, 2),
   );
 
+  console.log("Transferring 0.05 tokens confidentially to recipient...");
+
   // FIXED: Ensured all arguments are explicitly passed in the arrow function
   const txRes = await trackPerformance("CONFIDENTIAL_TRANSFER", () =>
-    client.transfer(sender, recipient.address, TOKEN_ADDRESS, transferAmount),
+    client.confidentialTransfer(
+      sender,
+      recipient.address,
+      TOKEN_ADDRESS,
+      transferAmount,
+    ),
   );
 
   const txHash = txRes.result.hash;
   console.log(
-    "Status: Privacy shielding active. Transfer amount is hidden on-chain.",
+    "Status:Confidential Transfer is completed. Transfer amount is hidden on-chain.",
   );
   console.log(`Transaction Hash: ${txHash}`);
   console.log(`View Transaction: ${EXPLORER_URL}${txHash}`);
 
-  const senderAvailAfterTx = await client.getBalance(
+  const senderConfidentialBalanceAfterTx = await client.getConfidentialBalance(
     sender.address,
     senderKeys.privateKey,
     TOKEN_ADDRESS,
-    { type: "available" },
-  );
-  const recipientPendAfterTx = await client.getBalance(
-    recipient.address,
-    recipientKeys.privateKey,
-    TOKEN_ADDRESS,
-    { type: "pending" },
   );
 
+  const recipientConfidentialBalanceAfterTx =
+    await client.getConfidentialBalance(
+      recipient.address,
+      recipientKeys.privateKey,
+      TOKEN_ADDRESS,
+    );
+
   console.log(
-    "Sender Available (Post-Transfer):",
-    ethers.formatUnits(senderAvailAfterTx.amount, 6),
+    "Sender Confidential Balance (Post-Transfer):",
+    ethers.formatUnits(senderConfidentialBalanceAfterTx.amount, 2),
   );
   console.log(
-    "Recipient Pending (Post-Transfer):",
-    ethers.formatUnits(recipientPendAfterTx.amount, 6),
+    "Recipient Confidential Balance (Post-Transfer):",
+    ethers.formatUnits(recipientConfidentialBalanceAfterTx.amount, 2),
     "\n",
   );
 
-  // 3. APPLY PENDING PHASE
-  const recipientAvailBeforeApply = await client.getBalance(
-    recipient.address,
-    recipientKeys.privateKey,
-    TOKEN_ADDRESS,
-    { type: "available" },
-  );
+  // 3. WITHDRAW PHASE
+  const withdrawAmount = ethers.parseUnits("0.05", 2);
   console.log(
-    "Recipient Available (Pre-Apply):",
-    ethers.formatUnits(recipientAvailBeforeApply.amount, 6),
+    "Withdrawing 0.05 tokens from confidential contract to recipient's public balance...",
   );
-
-  const applyRes = await trackPerformance("APPLY_PENDING", () =>
-    client.applyPending(recipient),
-  );
-  const applyHash = applyRes.result.hash;
-  console.log(`Transaction Hash: ${applyHash}`);
-  console.log(`View Transaction: ${EXPLORER_URL}${applyHash}`);
-
-  const recipientPendAfterApply = await client.getBalance(
-    recipient.address,
-    recipientKeys.privateKey,
-    TOKEN_ADDRESS,
-    { type: "pending" },
-  );
-  const recipientAvailAfterApply = await client.getBalance(
-    recipient.address,
-    recipientKeys.privateKey,
-    TOKEN_ADDRESS,
-    { type: "available" },
-  );
-
-  console.log(
-    "Recipient Pending (Post-Apply):",
-    ethers.formatUnits(recipientPendAfterApply.amount, 6),
-  );
-  console.log(
-    "Recipient Available (Post-Apply):",
-    ethers.formatUnits(recipientAvailAfterApply.amount, 6),
-    "\n",
-  );
-
-  // 4. WITHDRAW PHASE
-  const withdrawAmount = ethers.parseUnits("0.05", 6);
   const withdrawRes = await trackPerformance("WITHDRAW_TOKENS", () =>
     client.withdraw(recipient, TOKEN_ADDRESS, withdrawAmount),
   );
@@ -206,15 +174,16 @@ async function main() {
   console.log(`Transaction Hash: ${withdrawHash}`);
   console.log(`View Transaction: ${EXPLORER_URL}${withdrawHash}`);
 
-  const recipientAvailAfterWithdraw = await client.getBalance(
-    recipient.address,
-    recipientKeys.privateKey,
-    TOKEN_ADDRESS,
-    { type: "available" },
-  );
+  const recipientConfidentialBalanceAfterWithdraw =
+    await client.getConfidentialBalance(
+      recipient.address,
+      recipientKeys.privateKey,
+      TOKEN_ADDRESS,
+    );
+
   console.log(
-    "Recipient Available (Final):",
-    ethers.formatUnits(recipientAvailAfterWithdraw.amount, 6),
+    "Recipient Confidential Balance (Final):",
+    ethers.formatUnits(recipientConfidentialBalanceAfterWithdraw.amount, 2),
   );
 
   console.log("\n=== Complete Flow Execution Finished ===");

package/examples/simple-snippets.js

@@ -3,15 +3,15 @@ import dotenv from "dotenv";
 import { ConfidentialTransferClient } from "@fairblock/stabletrust";
 dotenv.config();
 const RPC_URL =
-  process.env.RPC_URL || "https://ethereum-sepolia-rpc.publicnode.com";
+  process.env.ETHEREUM_RPC_URL || "https://rpc.testnet.stable.xyz";
 const EXPLORER_URL =
-  process.env.EXPLORER_URL || "https://sepolia.etherscan.io/tx/";
+  process.env.EXPLORER_URL || "https://testnet.stablescan.xyz/tx/";
 async function minimalFlow() {
   // 1. Setup Client & Wallets
   const client = new ConfidentialTransferClient(
     RPC_URL,
-    "0xD765Dff7D734ABE09f88991A46BAb73ACa8910EF",
-    421614,
+    "0x29E4fd434758b1677c10854Fa81C2fc496D76E62",
+    2201,
   );
 
   const provider = new ethers.JsonRpcProvider(RPC_URL);
@@ -25,20 +25,22 @@ async function minimalFlow() {
   await client.ensureAccount(sender);
   await client.ensureAccount(recipient);
 
-  const TOKEN = "0xD765Dff7D734ABE09f88991A46BAb73ACa8910EF";
+  const TOKEN = "0x78Cf24370174180738C5B8E352B6D14c83a6c9A9";
   const amount = ethers.parseUnits("0.001", 6);
   let res;
   // 3. DEPOSIT: Move public ERC20 into the confidential contract
-  res = await client.deposit(sender, TOKEN, amount);
+  res = await client.confidentialDeposit(sender, TOKEN, amount);
   console.log("Deposit TX Hash:", EXPLORER_URL + res.hash);
   // 4. TRANSFER: Privacy-preserving transfer (On-chain amount is hidden)
   // This moves funds from Sender's 'Available' to Recipient's 'Pending' balance
-  res = await client.transfer(sender, recipient.address, TOKEN, amount / 2n);
+  res = await client.confidentialTransfer(
+    sender,
+    recipient.address,
+    TOKEN,
+    amount / 2n,
+  );
   console.log("Transfer TX Hash:", EXPLORER_URL + res.hash);
-  // 5. SETTLE: Recipient claims pending transfers into their available balance
-  res = await client.applyPending(recipient);
-  console.log("Settle TX Hash:", EXPLORER_URL + res.hash);
-  // 6. WITHDRAW: Convert confidential balance back to public ERC20
+  // 5. WITHDRAW: Convert confidential balance back to public ERC20
   res = await client.withdraw(recipient, TOKEN, amount / 4n);
   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.7",
+  "version": "1.0.8",
   "description": "SDK for confidential transfers using homomorphic encryption and zero-knowledge proofs",
   "main": "src/index.js",
   "types": "src/index.d.ts",