@fairblock/stabletrust 1.0.22 → 2.0.1

package/examples/anonymous-flow.js

@@ -0,0 +1,338 @@
+/**
+ * Anonymous Confidential Transfer — Basic Flow
+ *
+ *   [1] Generate two UUIDs as account IDs
+ *   [2] Derive ElGamal keypairs for both accounts
+ *   [3] Create both anonymous accounts via Fairycloak
+ *   [4] Deposit tokens into anon1
+ *   [5] Transfer anon1 → anon2
+ *   [6] Apply pending balance for anon2
+ *   [7] Withdraw anon2 → public address
+ *
+ * Run:
+ *   node examples/anonymous-flow.js
+ */
+
+import { ethers } from "ethers";
+import { randomUUID } from "crypto";
+import dotenv from "dotenv";
+import { AnonymousTransferClient } from "@fairblock/stabletrust";
+
+dotenv.config();
+
+// ── 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 TOKEN_ADDRESS =
+  process.env.TOKEN_ADDRESS ?? "0xE915164570b027C2A0FfadcB1B672192E35BF008";
+const TOKEN_DECIMALS = Number(process.env.TOKEN_DECIMALS ?? "6");
+
+// Amounts in raw ERC-20 units (6 decimals — matches complete-flow.js)
+const DEPOSIT_AMOUNT  =  100_000n; // 0.1  USDC
+const TRANSFER_AMOUNT =   50_000n; // 0.05 USDC
+const WITHDRAW_AMOUNT =   25_000n; // 0.025 USDC
+
+// Anvil test accounts — override via .env
+const ANON1_PK =
+  process.env.ANON1_PRIVATE_KEY ??
+  "0x7c852118294e51e653712a81e05800f419141751be58f605c371e15141b007a6";
+const ANON2_PK =
+  process.env.ANON2_PRIVATE_KEY ??
+  "0x8b3a350cf5c34c9194ca85829a2df0ec3153be0318b5e2d3348e872092edffba";
+const WITHDRAW_DEST_PK =
+  process.env.WITHDRAW_DEST_PK ??
+  "0x59c6995e998f97a5a0044966f0945389dc9e86dae88c7a8412f4603b6b78690d";
+
+// ── Helpers ───────────────────────────────────────────────────────────────────
+
+const log = console.log;
+const fmt = (n, decimals) => ethers.formatUnits(BigInt(n), decimals);
+
+async function logBalance(client, accountId, keys, token, _decimals, label) {
+  const bal = await client.getBalance(accountId, token, keys.privateKey);
+
+  // getBalance() returns amounts in contract scale (rawAmount * 100 / 10^tokenDecimals).
+  // Formatting with 2 decimal places gives the correct human-readable value: e.g.
+  //   contract scale 10  → formatUnits(10, 2)  = "0.10"  (= 0.1  USDC)
+  //   contract scale 5   → formatUnits(5, 2)   = "0.05"  (= 0.05 USDC)
+  console.log(
+    `[BALANCE][${label}] acc=${accountId} | ` +
+      `avail=${fmt(bal.available, 2)} | ` +
+      `pending=${fmt(bal.pending, 2)} | ` +
+      `total=${fmt(bal.amount, 2)}`,
+  );
+
+  return bal;
+}
+
+/**
+ * Poll until hasPendingAction flips to false (CW→EVM state settled).
+ */
+async function waitForAccountReady(
+  client,
+  accountId,
+  { timeoutMs = 180_000, label = "" } = {},
+) {
+  const tag = label ? `[${label}] ` : "";
+  process.stdout.write(
+    `  → ${tag}waiting for account ${accountId} to be ready`,
+  );
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    const info = await client.getAnonymousAccountInfo(accountId);
+    if (!info.hasPendingAction) {
+      console.log(" ✓");
+      return info;
+    }
+    process.stdout.write(".");
+    await new Promise((r) => setTimeout(r, 2000));
+  }
+  console.log(" ✗");
+  throw new Error(`Timeout waiting for account ${accountId} to be ready`);
+}
+
+// ── Main ──────────────────────────────────────────────────────────────────────
+
+async function main() {
+  console.log("\n═══════════════════════════════════════════════════════");
+  console.log("  Anonymous Confidential Transfer — Basic Flow");
+  console.log("═══════════════════════════════════════════════════════");
+  log("Fairycloak :", FAIRYCLOAK_URL);
+  log("Token      :", TOKEN_ADDRESS);
+
+  const provider = new ethers.JsonRpcProvider(EVM_RPC);
+  const anon1Wallet = new ethers.Wallet(ANON1_PK, provider);
+  const anon2Wallet = new ethers.Wallet(ANON2_PK, provider);
+  const withdrawDest = new ethers.Wallet(WITHDRAW_DEST_PK, provider).address;
+
+  log("Anon1     :", anon1Wallet.address);
+  log("Anon2     :", anon2Wallet.address);
+  log("Withdraw → :", withdrawDest);
+
+  const client = new AnonymousTransferClient({
+    fairycloakUrl: FAIRYCLOAK_URL,
+    chainId: CHAIN_ID,
+    rpcUrl: EVM_RPC,
+  });
+
+  // ── [1] Generate account IDs ─────────────────────────────────────────────────
+
+  console.log("\n── [1] Generate anonymous account IDs ──────────────────");
+
+  const anon1Id = randomUUID();
+  const anon2Id = randomUUID();
+  log("anon1 id:", anon1Id);
+  log("anon2 id:", anon2Id);
+
+  // ── [2] Derive ElGamal keypairs ──────────────────────────────────────────────
+
+  console.log("\n── [2] Derive ElGamal keypairs ─────────────────────────");
+  log("Deriving ElGamal keypairs from wallets + account IDs …");
+
+  const [anon1Keys, anon2Keys] = await Promise.all([
+    client.deriveAnonymousKeys(anon1Wallet, anon1Id),
+    client.deriveAnonymousKeys(anon2Wallet, anon2Id),
+  ]);
+  log("anon1 pubkey:", anon1Keys.publicKey);
+  log("anon2 pubkey:", anon2Keys.publicKey);
+
+  // ── [3] Create accounts ──────────────────────────────────────────────────────
+
+  console.log("\n── [3] Create anonymous accounts ───────────────────────");
+
+  log(`  creating anon1 (id=${anon1Id}) …`);
+  const cr1 = await client.createAccount(anon1Wallet, anon1Id, anon1Keys.publicKey);
+  log(`  request_id: ${cr1.request_id}  status: ${cr1.status}`);
+  if (cr1.error) log(`  [!] Error: ${cr1.error}`);
+
+  log(`  creating anon2 (id=${anon2Id}) …`);
+  const cr2 = await client.createAccount(anon2Wallet, anon2Id, anon2Keys.publicKey);
+  log(`  request_id: ${cr2.request_id}  status: ${cr2.status}`);
+  if (cr2.error) log(`  [!] Error: ${cr2.error}`);
+
+  log("Waiting for Fairycloak to confirm account creations …");
+  const [r1, r2] = await Promise.all([
+    client.waitForRequest(cr1.request_id, { timeoutMs: 180_000 }),
+    client.waitForRequest(cr2.request_id, { timeoutMs: 180_000 }),
+  ]);
+  if (r1.error) log("  [!] create anon1 failed:", r1.error);
+  if (r2.error) log("  [!] create anon2 failed:", r2.error);
+
+  await waitForAccountReady(client, anon1Id, { label: "anon1" });
+  await waitForAccountReady(client, anon2Id, { label: "anon2" });
+
+  const [i1, i2] = await Promise.all([
+    client.getAnonymousAccountInfo(anon1Id),
+    client.getAnonymousAccountInfo(anon2Id),
+  ]);
+  log(`anon1 exists=${i1.exists} finalized=${i1.finalized}`);
+  log(`anon2 exists=${i2.exists} finalized=${i2.finalized}`);
+
+  await logBalance(
+    client,
+    anon1Id,
+    anon1Keys,
+    TOKEN_ADDRESS,
+    TOKEN_DECIMALS,
+    "anon1:post-create",
+  );
+  await logBalance(
+    client,
+    anon2Id,
+    anon2Keys,
+    TOKEN_ADDRESS,
+    TOKEN_DECIMALS,
+    "anon2:post-create",
+  );
+
+  // ── [4] Deposit ──────────────────────────────────────────────────────────────
+
+  console.log("\n── [4] Deposit into anon1 ──────────────────────────────");
+  log(`Depositing ${fmt(DEPOSIT_AMOUNT, TOKEN_DECIMALS)} tokens into anon1 (anon1 pays gas) …`);
+
+  const dep = await client.deposit(
+    anon1Wallet,
+    anon1Id,
+    TOKEN_ADDRESS,
+    DEPOSIT_AMOUNT,
+  );
+  log("  request_id:", dep.request_id, "  status:", dep.status);
+  if (dep.error) log("    [!] Error:", dep.error);
+  if (dep.tx_hash) log("  tx_hash   :", dep.tx_hash);
+
+  const depFinal = await client.waitForRequest(dep.request_id, {
+    timeoutMs: 180_000,
+  });
+  log("  status    :", depFinal.status, "  tx_hash:", depFinal.tx_hash ?? "—");
+
+  await waitForAccountReady(client, anon1Id, { label: "deposit" });
+
+  await logBalance(
+    client,
+    anon1Id,
+    anon1Keys,
+    TOKEN_ADDRESS,
+    TOKEN_DECIMALS,
+    "anon1:post-deposit",
+  );
+
+  // ── [5] Transfer anon1 → anon2 ───────────────────────────────────────────────
+
+  console.log("\n── [5] Transfer anon1 → anon2 ──────────────────────────");
+  log(`Transferring ${fmt(TRANSFER_AMOUNT, TOKEN_DECIMALS)} tokens …`);
+
+  const txAnon = await client.transferToAnonymous(anon1Wallet, anon1Id, {
+    recipientId: anon2Id,
+    token: TOKEN_ADDRESS,
+    elGamalPrivateKey: anon1Keys.privateKey,
+    amount: TRANSFER_AMOUNT,
+  });
+  log("  request_id:", txAnon.request_id, "  status:", txAnon.status);
+  if (txAnon.error) log("    [!] Error:", txAnon.error);
+
+  const txAnonFinal = await client.waitForRequest(txAnon.request_id, {
+    timeoutMs: 180_000,
+  });
+  log(
+    "  status    :",
+    txAnonFinal.status,
+    "  tx_hash:",
+    txAnonFinal.tx_hash ?? "—",
+  );
+  if (txAnonFinal.error) log("    [!] Error:", txAnonFinal.error);
+
+  await waitForAccountReady(client, anon1Id, { label: "transfer sender" });
+  await waitForAccountReady(client, anon2Id, { label: "transfer recipient" });
+
+  await logBalance(
+    client,
+    anon1Id,
+    anon1Keys,
+    TOKEN_ADDRESS,
+    TOKEN_DECIMALS,
+    "anon1:post-transfer",
+  );
+  await logBalance(
+    client,
+    anon2Id,
+    anon2Keys,
+    TOKEN_ADDRESS,
+    TOKEN_DECIMALS,
+    "anon2:post-transfer",
+  );
+
+  // ── [6] Apply pending for anon2 ──────────────────────────────────────────────
+
+  console.log("\n── [6] Apply pending balance for anon2 ─────────────────");
+  log("Moving incoming credit from pending → available …");
+
+  const ap = await client.applyPending(anon2Wallet, anon2Id);
+  log("  request_id:", ap.request_id, "  status:", ap.status);
+  if (ap.error) log("    [!] Error:", ap.error);
+
+  const apFinal = await client.waitForRequest(ap.request_id, {
+    timeoutMs: 180_000,
+  });
+  log("  status    :", apFinal.status, "  tx_hash:", apFinal.tx_hash ?? "—");
+  if (apFinal.error) log("    [!] Error:", apFinal.error);
+
+  await waitForAccountReady(client, anon2Id, { label: "applyPending" });
+
+  await logBalance(
+    client,
+    anon2Id,
+    anon2Keys,
+    TOKEN_ADDRESS,
+    TOKEN_DECIMALS,
+    "anon2:post-apply",
+  );
+
+  // ── [7] Withdraw anon2 → public address ──────────────────────────────────────
+
+  console.log("\n── [7] Withdraw from anon2 ─────────────────────────────");
+  log(`Withdrawing ${fmt(WITHDRAW_AMOUNT, TOKEN_DECIMALS)} tokens → ${withdrawDest} …`);
+
+  const wd = await client.withdraw(anon2Wallet, anon2Id, {
+    destination: withdrawDest,
+    token: TOKEN_ADDRESS,
+    plainAmount: WITHDRAW_AMOUNT,
+    elGamalPrivateKey: anon2Keys.privateKey,
+  });
+  log("  request_id:", wd.request_id, "  status:", wd.status);
+  if (wd.error) log("    [!] Error:", wd.error);
+
+  const wdFinal = await client.waitForRequest(wd.request_id, {
+    timeoutMs: 180_000,
+  });
+  log("  status    :", wdFinal.status, "  tx_hash:", wdFinal.tx_hash ?? "—");
+  if (wdFinal.error) log("    [!] Error:", wdFinal.error);
+
+  await waitForAccountReady(client, anon2Id, { label: "withdraw" });
+
+  await logBalance(
+    client,
+    anon2Id,
+    anon2Keys,
+    TOKEN_ADDRESS,
+    TOKEN_DECIMALS,
+    "anon2:post-withdraw",
+  );
+
+  // ── Done ─────────────────────────────────────────────────────────────────────
+
+  console.log("\n═══════════════════════════════════════════════════════");
+  console.log("  ✅ Anonymous flow completed!");
+  console.log("═══════════════════════════════════════════════════════");
+  log("anon1 id   :", anon1Id);
+  log("anon2 id   :", anon2Id);
+  log("Deposited  :", ethers.formatUnits(DEPOSIT_AMOUNT, TOKEN_DECIMALS), "tokens → anon1");
+  log("Transferred:", ethers.formatUnits(TRANSFER_AMOUNT, TOKEN_DECIMALS), "tokens → anon2");
+  log("Withdrawn  :", ethers.formatUnits(WITHDRAW_AMOUNT, TOKEN_DECIMALS), "tokens →", withdrawDest);
+}
+
+main().catch((err) => {
+  console.error("\n[!]", err.message ?? err);
+  process.exit(1);
+});

package/package.json

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

package/pkg/README.md

@@ -0,0 +1,310 @@
+# Confidential Tokens - Privacy-First Digital Assets
+
+A complete implementation of confidential token operations using ElGamal encryption and zero-knowledge proofs. This project includes both a Solidity smart contract (GatewayContract) and a professional web frontend for confidential token management.
+
+## 🚀 Features
+
+### Smart Contract (GatewayContract.sol)
+- **Account Management**: Create and manage confidential accounts with ElGamal keypairs
+- **Token Conversion**: Convert ERC20 tokens to confidential tokens
+- **Private Transfers**: Transfer confidential tokens with zero-knowledge proofs
+- **Secure Withdrawals**: Convert confidential tokens back to ERC20 tokens
+- **Access Control**: Role-based permissions for admin and relayer operations
+- **Event Logging**: Comprehensive event system for tracking operations
+
+### Frontend Application
+- **Professional UI**: Modern, responsive design optimized for real-world usage
+- **Wallet Integration**: MetaMask connection for Ethereum blockchain access
+- **Account Dashboard**: View encrypted balances and account status
+- **Token Operations**: Convert, transfer, and withdraw confidential tokens
+- **Client-Side Security**: All cryptographic operations performed in WebAssembly
+- **Real-Time Updates**: Live status updates and transaction tracking
+
+## 🏗️ Architecture
+
+```
+┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
+│   Frontend      │    │  GatewayContract │    │   Relayer       │
+│   (Web App)     │◄──►│   (Solidity)     │◄──►│   (Off-chain)   │
+│                 │    │                  │    │                 │
+│ • MetaMask      │    │ • Account Mgmt   │    │ • Proof Verify  │
+│ • WebAssembly   │    │ • Token Escrow   │    │ • State Update  │
+│ • Proof Gen     │    │ • Event Logging  │    │ • Balance Mgmt  │
+└─────────────────┘    └──────────────────┘    └─────────────────┘
+```
+
+## 📁 Project Structure
+
+```
+elgamal-demo/
+├── GatewayContract.sol          # Main smart contract
+├── src/                         # Rust cryptographic library
+│   ├── components/              # Core cryptographic components
+│   │   ├── elgamal.rs          # ElGamal encryption implementation
+│   │   ├── proofs.rs           # Zero-knowledge proofs
+│   │   └── ...
+│   ├── transfer.rs             # Transfer proof generation
+│   ├── withdraw.rs             # Withdraw proof generation
+│   └── lib.rs                  # Library exports
+├── frontend/                    # Web application
+│   ├── index.html              # Main application page
+│   ├── styles.css              # Professional styling
+│   ├── app.js                  # Main application logic
+│   ├── deployment-config.js    # Configuration file
+│   ├── src/lib.rs              # WebAssembly bindings
+│   └── pkg/                    # Built WebAssembly files
+└── scripts/                     # Deployment scripts
+```
+
+## 🛠️ Installation & Setup
+
+### Prerequisites
+- **Rust**: Latest stable version
+- **Node.js**: 16+ with npm
+- **Solidity**: For smart contract development
+- **MetaMask**: Browser extension for wallet connection
+
+### 1. Clone and Setup
+
+```bash
+git clone <repository-url>
+cd elgamal-demo
+
+# Install Rust dependencies
+cargo build
+
+# Setup frontend
+cd frontend
+npm install
+npm run build:wasm
+```
+
+### 2. Smart Contract Deployment
+
+```bash
+# Deploy GatewayContract (example using Hardhat)
+npx hardhat compile
+npx hardhat run scripts/deploy.js --network <network>
+```
+
+### 3. Configuration
+
+Update `frontend/deployment-config.js` with your deployed contract address and network settings:
+
+```javascript
+export const CONFIG = {
+    GATEWAY_CONTRACT_ADDRESS: '0xYourDeployedContractAddress',
+    NETWORK: {
+        chainId: 1, // Mainnet or testnet
+        name: 'Ethereum Mainnet',
+        // ... other settings
+    }
+};
+```
+
+### 4. Start Development Server
+
+```bash
+cd frontend
+npm run dev
+# Open http://localhost:8080
+```
+
+## 🔧 Usage
+
+### 1. Connect Wallet
+- Click "Connect Wallet" in the header
+- Approve MetaMask connection
+- Verify your address is displayed
+
+### 2. Create Confidential Account
+- Click "Create Account" card
+- Generate ElGamal keypair (stored locally)
+- Submit account creation to contract
+
+### 3. Convert Tokens
+- Select token (USDC, USDT, DAI)
+- Enter amount to convert
+- Approve token transfer and confirm conversion
+
+### 4. Private Transfers
+- Enter recipient address
+- Select token and amount
+- Generate zero-knowledge proof
+- Submit confidential transfer
+
+### 5. Withdraw Tokens
+- Select token and amount
+- Generate withdrawal proof
+- Convert back to ERC20 tokens
+
+## 🔐 Security Features
+
+### Cryptographic Security
+- **ElGamal Encryption**: All balances encrypted with user-specific keys
+- **Zero-Knowledge Proofs**: Transfer amounts and balances remain private
+- **Client-Side Generation**: All proofs generated locally in WebAssembly
+- **No Server Dependency**: Cryptographic operations don't require server trust
+
+### Smart Contract Security
+- **Access Control**: Role-based permissions for sensitive operations
+- **Reentrancy Protection**: Guards against reentrancy attacks
+- **Pausable Operations**: Admin can pause contract in emergencies
+- **Event Logging**: Comprehensive audit trail for all operations
+
+### Frontend Security
+- **Local Key Storage**: Private keys stored in browser (use secure storage in production)
+- **Input Validation**: All user inputs validated before processing
+- **Error Handling**: Comprehensive error handling and user feedback
+- **HTTPS Required**: All operations require secure connections
+
+## 🌐 Network Support
+
+### Mainnet
+- Ethereum Mainnet
+- Token addresses for USDC, USDT, DAI
+
+### Testnet
+- Sepolia Testnet
+- Test token addresses
+- Faucet integration for testing
+
+## 📊 API Reference
+
+### WebAssembly Functions
+
+```javascript
+// Generate ElGamal keypair
+const keypair = await generate_keypair();
+
+// Encrypt amount with public key
+const encrypted = await encrypt_amount(amount, pubkey);
+
+// Generate transfer proof
+const proof = await generate_transfer_proof({
+    current_balance_ciphertext,
+    current_balance,
+    transfer_amount,
+    source_keypair,
+    destination_pubkey
+});
+
+// Generate withdraw proof
+const proof = await generate_withdraw_proof({
+    current_balance_ciphertext,
+    current_balance,
+    withdraw_amount,
+    keypair
+});
+```
+
+### Smart Contract Functions
+
+```solidity
+// Create confidential account
+function createConfidentialAccount(bytes calldata elgamalPubkey) 
+    external returns (bytes32);
+
+// Convert tokens to confidential
+function deposit(DepositItem[] calldata items) 
+    external returns (bytes32);
+
+// Private transfer
+function transferConfidential(address recipient, string calldata denom, bytes calldata transferProofData) 
+    external returns (bytes32);
+
+// Withdraw tokens
+function withdraw(string calldata denom, uint256 amount, bytes calldata withdrawProofData) 
+    external returns (bytes32);
+```
+
+## 🚀 Deployment
+
+### Frontend Deployment (Vercel)
+
+```bash
+# Install Vercel CLI
+npm i -g vercel
+
+# Deploy
+cd frontend
+vercel --prod
+```
+
+### Smart Contract Deployment
+
+```bash
+# Using Hardhat
+npx hardhat run scripts/deploy.js --network mainnet
+
+# Using Foundry
+forge create --rpc-url <RPC_URL> --private-key <PRIVATE_KEY> GatewayContract
+```
+
+## 🔍 Testing
+
+### Frontend Testing
+
+```bash
+cd frontend
+npm test
+```
+
+### Smart Contract Testing
+
+```bash
+npx hardhat test
+```
+
+### WebAssembly Testing
+
+```bash
+cd frontend
+npm run test:wasm
+```
+
+## 📝 Development
+
+### Adding New Features
+
+1. **Smart Contract**: Add functions to `GatewayContract.sol`
+2. **Cryptography**: Implement in Rust library (`src/`)
+3. **WebAssembly**: Expose functions in `frontend/src/lib.rs`
+4. **Frontend**: Add UI components in `app.js`
+
+### Code Style
+
+- **Rust**: Follow standard Rust conventions
+- **JavaScript**: Use ES6+ features, async/await
+- **Solidity**: Follow OpenZeppelin patterns
+- **CSS**: Use CSS custom properties for theming
+
+## 🤝 Contributing
+
+1. Fork the repository
+2. Create feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit changes (`git commit -m 'Add amazing feature'`)
+4. Push to branch (`git push origin feature/amazing-feature`)
+5. Open Pull Request
+
+## 📄 License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## 🆘 Support
+
+- **Issues**: Report bugs and feature requests on GitHub Issues
+- **Discussions**: Join community discussions on GitHub Discussions
+- **Documentation**: Check the [USAGE.md](frontend/USAGE.md) for detailed usage guide
+
+## 🔮 Roadmap
+
+- [ ] Multi-asset support
+- [ ] Batch operations
+- [ ] Mobile app
+- [ ] Advanced privacy features
+- [ ] Integration with other DeFi protocols
+
+---
+
+**Built with ❤️ for privacy and decentralization**