@cloakely/sdk 0.2.4 → 0.2.6

package/README.md

@@ -72,6 +72,15 @@ await priv.unshieldHype(freshAddress, parseEther("0.5")); // back to any wallet
 console.log(await priv.balance(priv.hypeMarket.pool));    // only this account can see it
 ```
 
+Private USDC lives in its own vault. Register it from the deployment, then shield, send and withdraw like any token:
+
+```ts
+const usdc = priv.addAsset(d.assets![0]);                                // { symbol: "USDC", decimals: 6, … }
+await priv.shieldToken(walletClient, usdc.token, parseUnits("50", 6));   // approve + deposit (public, once)
+await priv.send(usdc.token, "cloak:…", parseUnits("20", 6));             // amount hidden
+await priv.unshieldToken(usdc.token, freshAddress, parseUnits("10", 6)); // 0.25% fee kept
+```
+
 The private account comes from one EIP-712 signature bound to the chain and the router. The same wallet always restores it, and nothing is stored on a server. In Node, read the circuit files yourself and pass them to `createProver(wasm, zkey)`.
 
 ## Fees (testnet beta)
@@ -90,7 +99,7 @@ Rules live in the on-chain `CloakConfig`. Raising a fee or a cap waits a public
 | Export | What it is |
 |---|---|
 | `Cloak` | Launches: `createLaunch`, `bid`, `revealAll`, `settle`, `claimAll`, `payOut`, `getAuction`, `listLaunches` |
-| `CloakPrivate` | Private balances: `shieldHype`, `buy`, `sell`, `batch`, `send`, `unshieldHype`, `unshieldToken`, `balance`, `maxSpendable`, `migrateFrom` |
+| `CloakPrivate` | Private balances: `shieldHype`, `shieldToken`, `buy`, `sell`, `batch`, `send`, `unshieldHype`, `unshieldToken`, `addAsset`, `balance`, `maxSpendable`, `migrateFrom` |
 | `relayerSubmitter`, `walletSubmitter` | How private calls are submitted: through a relayer (private), or from a wallet (for tests) |
 | `loadProver`, `createProver` | The Groth16 prover, running on the device |
 | `deployments`, `deploymentFor` | Addresses, start blocks, relayer and circuit URLs per chain |

package/dist/deployments.d.ts

@@ -15,6 +15,14 @@ export interface CloakDeployment {
     relayerUrl: string;
     /** Hosted circuit artifacts (transaction2x2.wasm and transaction2x2_final.zkey). */
     circuitsUrl: string;
+    /** Shielded pools for existing tokens (USDC): register them with `CloakPrivate.addAsset`. */
+    assets?: {
+        symbol: string;
+        token: Address;
+        pool: Address;
+        decimals: number;
+        fromBlock: bigint;
+    }[];
     /** The first deployment: its launches still list, and its private balances move here through `migrator`. */
     legacy?: {
         factory: Address;

package/dist/deployments.js

@@ -11,6 +11,10 @@ export const deployments = {
         whype: "0xe44b27113D4b947c0B1bDf4a93878D0e115f4bdD",
         relayerUrl: "https://cloak-keeper.onrender.com",
         circuitsUrl: "https://cloak.boblabs.tech/circuits",
+        assets: [
+            // Elysium testnet USDC (bridged from Circle's USDC on HyperEVM): private sends and withdrawals
+            { symbol: "USDC", token: "0x7D29d8047B905000459c0E80c34a26CeedcB47b2", pool: "0x61de30970e3c53665ce5a89323284e7ab379fa08", decimals: 6, fromBlock: 18329466n },
+        ],
         legacy: {
             factory: "0x1dc1ea9837ecbd31ec74f0d558e1db1c303a7e1c",
             router: "0xfa2574cfc3afb8f7d3a0651fa2111ff4e3d2fc41",

package/dist/private/client.d.ts

@@ -26,6 +26,17 @@ export interface PrivateMarket {
     pool: Address;
     pair: Address | null;
     symbol?: string;
+    /** Token decimals (18 for HYPE and launch tokens; 6 for USDC). */
+    decimals?: number;
+}
+/** A shielded pool for an existing token (such as USDC) that lives next to the router, not in its launch registry. */
+export interface PrivateAsset {
+    symbol: string;
+    token: Address;
+    pool: Address;
+    decimals: number;
+    /** Block the pool was deployed in: its events are scanned from here. */
+    fromBlock: bigint;
 }
 /** POST shielded calls to a Cloak relayer (`services/keeper` serves `/relay` and `/quote`). */
 export declare function relayerSubmitter(url: string): Submitter;
@@ -51,6 +62,10 @@ export declare class CloakPrivate {
     readonly migrator?: Address | undefined;
     private pools;
     markets: PrivateMarket[];
+    /** Shielded pools outside the launch registry (USDC). Send, unshieldToken and shieldToken work on these too. */
+    assets: (PrivateMarket & {
+        fromBlock: bigint;
+    })[];
     constructor(publicClient: PublicClient, router: Address, keys: CloakKeys, prover: () => Promise<Prover>, submit: Submitter, fromBlock?: bigint, batcher?: Address | undefined, migrator?: Address | undefined);
     /**
      * Derive the private keys from one EIP-712 signature bound to this chain and router, so a signature asked for by any
@@ -67,6 +82,8 @@ export declare class CloakPrivate {
     loadMarkets(): Promise<PrivateMarket[]>;
     get hypeMarket(): PrivateMarket;
     market(token: Address): PrivateMarket;
+    /** Register a shielded pool that isn't a launch market, such as USDC (`deploymentFor(chainId).assets`). */
+    addAsset(a: PrivateAsset): PrivateMarket;
     private state;
     /** Pull new leaves from the pool's events, trial-decrypt them, and refresh spent flags. */
     sync(pool: Address): Promise<OwnedNote[]>;
@@ -92,6 +109,11 @@ export declare class CloakPrivate {
     private inputsFor;
     /** Public HYPE → private balance. This one step is public (your wallet deposits); everything after is not. */
     shieldHype(wallet: Wallet, amount: bigint): Promise<Hex>;
+    /**
+     * Public tokens → private balance, for any pool this client knows (USDC, or a launch token). Like shieldHype, this
+     * one step is public and lands on a one-time key. Asks the wallet to approve the pool first if needed.
+     */
+    shieldToken(wallet: Wallet, token: Address, amount: bigint, onStatus?: Status): Promise<Hex>;
     roundInfo(): Promise<{
         round: bigint;
         endsAt: number;
@@ -143,10 +165,10 @@ export declare class CloakPrivate {
     address(): Promise<string>;
     /**
      * Private transfer inside a pool: sender, recipient and amount all stay hidden.
-     * `token` = a launch token, or the WHYPE address / hypeMarket.token for HYPE.
+     * `token` = a launch token, an asset such as USDC, or the WHYPE address / hypeMarket.token for HYPE.
      */
     send(token: Address, to: string, amount: bigint, onStatus?: Status): Promise<Hex>;
-    /** Private launch tokens → any address. */
+    /** Private tokens (a launch token, or an asset such as USDC) → any address. */
     unshieldToken(token: Address, to: Address, amount: bigint, onStatus?: Status): Promise<Hex>;
     /**
      * Move every private balance `legacy` (a client on the earlier router, with the earlier keys) can see into this

package/dist/private/client.js

@@ -7,6 +7,11 @@ import { MOVE_DATA_ABI, ORDER_DATA_ABI, SWAP_DATA_ABI, buildTransaction, selectN
 const EPOCH_BITS = 20;
 const epochOf = (globalIndex) => Math.floor(globalIndex / 2 ** EPOCH_BITS);
 const positionOf = (globalIndex) => globalIndex % 2 ** EPOCH_BITS;
+const ERC20_ABI = [
+    { type: "function", name: "allowance", stateMutability: "view", inputs: [{ type: "address" }, { type: "address" }], outputs: [{ type: "uint256" }] },
+    { type: "function", name: "approve", stateMutability: "nonpayable", inputs: [{ type: "address" }, { type: "uint256" }], outputs: [{ type: "bool" }] },
+    { type: "function", name: "balanceOf", stateMutability: "view", inputs: [{ type: "address" }], outputs: [{ type: "uint256" }] },
+];
 const json = (v) => JSON.stringify(v, (_, x) => (typeof x === "bigint" ? x.toString() : x));
 /** POST shielded calls to a Cloak relayer (`services/keeper` serves `/relay` and `/quote`). */
 export function relayerSubmitter(url) {
@@ -75,6 +80,8 @@ export class CloakPrivate {
     migrator;
     pools = new Map();
     markets = [];
+    /** Shielded pools outside the launch registry (USDC). Send, unshieldToken and shieldToken work on these too. */
+    assets = [];
     constructor(publicClient, router, keys, prover, submit, fromBlock = 0n, batcher, migrator) {
         this.publicClient = publicClient;
         this.router = router;
@@ -128,15 +135,26 @@ export class CloakPrivate {
         return m;
     }
     market(token) {
-        const m = this.markets.find((x) => x.token.toLowerCase() === token.toLowerCase());
+        const t = token.toLowerCase();
+        const m = this.markets.find((x) => x.token.toLowerCase() === t) ?? this.assets.find((x) => x.token.toLowerCase() === t);
         if (!m)
             throw new Error("no private market for this token (createPool after settlement)");
         return m;
     }
+    /** Register a shielded pool that isn't a launch market, such as USDC (`deploymentFor(chainId).assets`). */
+    addAsset(a) {
+        const existing = this.assets.find((x) => x.pool.toLowerCase() === a.pool.toLowerCase());
+        if (existing)
+            return existing;
+        const m = { token: a.token, pool: a.pool, pair: null, symbol: a.symbol, decimals: a.decimals, fromBlock: a.fromBlock };
+        this.assets.push(m);
+        return m;
+    }
     state(pool) {
         let s = this.pools.get(pool.toLowerCase());
         if (!s) {
-            s = { leaves: [], scannedUpTo: 0, fromBlock: this.fromBlock, notes: [] };
+            const asset = this.assets.find((x) => x.pool.toLowerCase() === pool.toLowerCase());
+            s = { leaves: [], scannedUpTo: 0, fromBlock: asset?.fromBlock ?? this.fromBlock, notes: [] };
             this.pools.set(pool.toLowerCase(), s);
         }
         return s;
@@ -286,6 +304,42 @@ export class CloakPrivate {
             throw new Error("shield reverted");
         return hash;
     }
+    /**
+     * Public tokens → private balance, for any pool this client knows (USDC, or a launch token). Like shieldHype, this
+     * one step is public and lands on a one-time key. Asks the wallet to approve the pool first if needed.
+     */
+    async shieldToken(wallet, token, amount, onStatus = () => { }) {
+        if (amount <= 0n)
+            throw new Error("amount must be positive");
+        const pool = this.market(token).pool;
+        const owner = wallet.account.address;
+        // check first, so a wallet without the tokens doesn't pay gas for an approval that leads nowhere
+        const held = await this.publicClient.readContract({ address: token, abi: ERC20_ABI, functionName: "balanceOf", args: [owner] });
+        if (held < amount)
+            throw new Error(`insufficient token balance in wallet: has ${held}, needs ${amount}`);
+        const allowance = await this.publicClient.readContract({ address: token, abi: ERC20_ABI, functionName: "allowance", args: [owner, pool] });
+        if (allowance < amount) {
+            onStatus("Approve the deposit in your wallet…");
+            const a = await wallet.writeContract({ address: token, abi: ERC20_ABI, functionName: "approve", args: [pool, amount] });
+            const ar = await this.publicClient.waitForTransactionReceipt({ hash: a });
+            if (ar.status !== "success")
+                throw new Error("approve reverted");
+        }
+        const keyIndex = randomKeyIndex();
+        const k = await this.keys.key(keyIndex);
+        const blinding = randomField();
+        onStatus("Confirm the deposit in your wallet…");
+        const hash = await wallet.writeContract({
+            address: pool,
+            abi: shieldedPoolAbi,
+            functionName: "depositTo",
+            args: [k.pubKey, amount, blinding, encryptFullMemo(this.keys.encPub, amount, blinding, keyIndex)],
+        });
+        const r = await this.publicClient.waitForTransactionReceipt({ hash });
+        if (r.status !== "success")
+            throw new Error("shield reverted");
+        return hash;
+    }
     // ───────────── batch auctions (hide trade size) ─────────────
     async roundInfo() {
         if (!this.batcher)
@@ -460,7 +514,7 @@ export class CloakPrivate {
     }
     /**
      * Private transfer inside a pool: sender, recipient and amount all stay hidden.
-     * `token` = a launch token, or the WHYPE address / hypeMarket.token for HYPE.
+     * `token` = a launch token, an asset such as USDC, or the WHYPE address / hypeMarket.token for HYPE.
      */
     async send(token, to, amount, onStatus = () => { }) {
         const rcpt = parseCloakAddress(to);
@@ -484,7 +538,7 @@ export class CloakPrivate {
         onStatus("Relaying private transfer…");
         return this.submit({ kind: "transact", pool, proof, extData });
     }
-    /** Private launch tokens → any address. */
+    /** Private tokens (a launch token, or an asset such as USDC) → any address. */
     async unshieldToken(token, to, amount, onStatus = () => { }) {
         const pool = this.market(token).pool;
         const q = await this.relayFee("transact", pool);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cloakely/sdk",
-  "version": "0.2.4",
+  "version": "0.2.6",
   "description": "Cloak on Elysium: sealed-bid token launches and private trading (shielded balances, private swaps, batch auctions, private sends) with on-device zero-knowledge proofs.",
   "keywords": [
     "cloak",