@cloakely/sdk 0.6.0 → 0.7.0

package/dist/deployments.d.ts

@@ -42,6 +42,12 @@ export interface CloakDeployment {
     batcher: Address;
     /** Moves balances from every earlier deployment into the permanent vaults. */
     migrator?: Address;
+    /** SharedVault: one private vault for every new Uniswap launch token (testnet experiment). */
+    shared?: Address;
+    /** Block the shared vault was deployed in: scan its notes from here. */
+    sharedBlock?: bigint;
+    /** SharedRouter: private buys, sells and hidden sends for the shared vault. */
+    sharedRouter?: Address;
     hypePool: Address;
     whype: Address;
     /** Hosted relayer (POST /relay, GET /quote). */

package/dist/deployments.js

@@ -17,6 +17,10 @@ export const deployments = {
         firstFactoryBlock: 19484794n,
         seeder: "0x633aa82b806dafc0ae4c84418d23f3726139a88d",
         feeLocker: "0x3b74062a72b16f9a221d63515518a635414501d8",
+        // the shared launch-token vault (Nov 2, testnet experiment): new Uniswap launches keep their private balances here
+        shared: "0x0ce2ecb0195e07899377e3d7b01e927ab3f87610",
+        sharedBlock: 21426599n,
+        sharedRouter: "0xe2a0769a5acbd987c1b6725247c56187a112dc7e",
         router: "0x343ab9a7aac93cee28321410510ea24417cc6386",
         routerBlock: 19485063n,
         batcher: "0xc69e4bca18020ae93bc9f17093985bfb139a3203",
@@ -96,6 +100,9 @@ export async function liveDeployment(publicClient, base) {
         routerBlock: reg.routerBlock,
         batcher: reg.batcher ?? base.batcher,
         migrator: reg.migrator ?? base.migrator,
+        shared: reg.shared ?? base.shared,
+        sharedBlock: reg.sharedBlock ?? base.sharedBlock,
+        sharedRouter: reg.sharedRouter ?? base.sharedRouter,
         hypePool,
         whype,
         previous: reg.previous.length

package/dist/private/client.d.ts

@@ -114,7 +114,11 @@ export declare class CloakPrivate {
     relayFee(kind: RelayKind, pool: Address): Promise<RelayQuote>;
     /** What a withdrawal of `amount` from `pool` delivers after the protocol's withdrawal fee. */
     afterFee(pool: Address, amount: bigint): Promise<bigint>;
-    private changeOutput;
+    changeOutput(amount: bigint): Promise<{
+        amount: bigint;
+        pubKey: bigint;
+        memo: (b: bigint) => `0x${string}`;
+    }>;
     dummy(): Promise<{
         dummyPubKey: bigint;
         dummyMemo: (b: bigint) => `0x${string}`;
@@ -123,7 +127,7 @@ export declare class CloakPrivate {
      * Get 1–2 notes (from one tree epoch) covering `target`, merging notes privately first when the balance is spread
      * across many. Each merge is a relayed transaction and pays the relayer's fee from the merged notes.
      */
-    private inputsFor;
+    inputsFor(pool: Address, target: bigint, onStatus: Status): Promise<OwnedNote[]>;
     /** Public HYPE → private balance. This one step is public (your wallet deposits); everything after is not. */
     shieldHype(wallet: Wallet, amount: bigint): Promise<Hex>;
     /**
@@ -178,7 +182,12 @@ export declare class CloakPrivate {
      * wallet's HYPE back into the private balance. Before settlement it only moves back HYPE from a one-time wallet whose
      * bid never went through. Safe to call again; it only does what's left.
      */
-    finishPrivateBids(auction: Address, onStatus?: Status): Promise<{
+    finishPrivateBids(auction: Address, onStatus?: Status, 
+    /** The shared launch-token vault, for launches whose token lives there (claimed to the bid wallet, then moved in). */
+    shared?: {
+        isAdmitted(token: Address): Promise<boolean>;
+        shield(wallet: Wallet, token: Address, amount: bigint): Promise<Hex>;
+    }): Promise<{
         claimed: number;
         movedHype: bigint;
         movedTokens: bigint;

package/dist/private/client.js

@@ -479,13 +479,16 @@ export class CloakPrivate {
      * wallet's HYPE back into the private balance. Before settlement it only moves back HYPE from a one-time wallet whose
      * bid never went through. Safe to call again; it only does what's left.
      */
-    async finishPrivateBids(auction, onStatus = () => { }) {
+    async finishPrivateBids(auction, onStatus = () => { }, 
+    /** The shared launch-token vault, for launches whose token lives there (claimed to the bid wallet, then moved in). */
+    shared) {
         const reader = new Cloak(this.publicClient);
         const s = await reader.getAuction(auction);
         let claimed = 0;
         let movedHype = 0n;
         let movedTokens = 0n;
         const vaultOpen = !s.failed && this.markets.some((m) => m.token.toLowerCase() === s.token.toLowerCase());
+        const inShared = !s.failed && !vaultOpen && !!shared && (await shared.isAdmitted(s.token));
         for (const bw of await this.bidWallets(auction)) {
             const c = new Cloak(this.publicClient, bw.wallet);
             const bids = await reader.bidsOf(auction, bw.address);
@@ -512,12 +515,12 @@ export class CloakPrivate {
                 const h = await bw.wallet.writeContract({ address: auction, abi: cloakAuctionAbi, functionName: "withdrawRefund", args: [bw.address] });
                 await this.publicClient.waitForTransactionReceipt({ hash: h });
             }
-            if (vaultOpen) {
+            if (vaultOpen || inShared) {
                 const t = await this.publicClient.readContract({ address: s.token, abi: ERC20_ABI, functionName: "balanceOf", args: [bw.address] });
                 if (t > 0n) {
                     onStatus("Moving tokens into your private balance…");
                     try {
-                        await this.shieldToken(bw.wallet, s.token, t);
+                        await (inShared ? shared.shield(bw.wallet, s.token, t) : this.shieldToken(bw.wallet, s.token, t));
                         movedTokens += t;
                     }
                     catch { } // a cap may block it; the tokens stay in the one-time wallet, which nobody can tie to you

package/dist/private/crypto.d.ts

@@ -81,6 +81,8 @@ export interface Note {
     amount: bigint;
     pubKey: bigint;
     blinding: bigint;
+    /** Shared vault only: the token's address as a number. Notes of single-token vaults have none. */
+    asset?: bigint;
 }
 export declare const noteCommitment: (n: Note) => Promise<bigint>;
 export declare function nullifierOf(n: Note, leafIndex: number, privKey: bigint): Promise<bigint>;

package/dist/private/crypto.js

@@ -86,7 +86,7 @@ export class CloakKeys {
         return keccak256(concat([toBytes("cloak-bidwallet-v1"), this.seed, toBytes(auction.toLowerCase()), toBytes(toHex(n, { size: 4 }))]));
     }
 }
-export const noteCommitment = (n) => poseidon([n.amount, n.pubKey, n.blinding]);
+export const noteCommitment = (n) => n.asset === undefined ? poseidon([n.amount, n.pubKey, n.blinding]) : poseidon([n.amount, n.pubKey, n.blinding, n.asset]);
 export async function nullifierOf(n, leafIndex, privKey) {
     const c = await noteCommitment(n);
     const sig = await poseidon([privKey, c, BigInt(leafIndex)]);

package/dist/private/index.d.ts

@@ -3,3 +3,4 @@ export * from "./tree.js";
 export * from "./prover.js";
 export * from "./tx.js";
 export * from "./client.js";
+export * from "./shared.js";

package/dist/private/index.js

@@ -3,3 +3,4 @@ export * from "./tree.js";
 export * from "./prover.js";
 export * from "./tx.js";
 export * from "./client.js";
+export * from "./shared.js";

package/dist/private/prover.d.ts

@@ -7,10 +7,14 @@ export interface ProofArgs {
     extDataHash: bigint;
     inputNullifiers: [bigint, bigint];
     outputCommitments: [bigint, bigint];
+    /** Shared-vault proofs only: the token named publicly, or 0 for a send that hides it. */
+    publicAsset?: bigint;
 }
 export type Prover = (input: Record<string, unknown>) => Promise<ProofArgs>;
 /** Groth16 prover for the 2-in/2-out circuit (`transaction2x2`). Runs on the user's device. */
 export declare function createProver(wasm: Uint8Array, zkey: Uint8Array): Prover;
+/** Groth16 prover for the shared launch-token vault (`transactionMA2x2`, 8 public signals). */
+export declare function createSharedProver(wasm: Uint8Array, zkey: Uint8Array): Prover;
 /** Hosted circuit artifacts. */
 export declare const CIRCUITS_URL = "https://cloak.boblabs.tech/circuits";
 /** SHA-256 of the artifacts this SDK version was built and tested against. */
@@ -29,3 +33,18 @@ export declare function loadProver(baseUrl?: string, opts?: {
         zkey: string;
     } | null;
 }): Promise<Prover>;
+/** SHA-256 of the shared-vault circuit artifacts this SDK version was built and tested against. */
+export declare const SHARED_CIRCUIT_HASHES: {
+    readonly wasm: "55712f66e67fd9345daac5c881c2e73c546864dbd1e23481463b603b47aa53ed";
+    readonly zkey: "86ecee336f022ac1d2dbcc4db7e85ef838aee34c4d75fe8bc7446db86f3b97b3";
+};
+/**
+ * Fetch the shared launch-token vault's circuit (`transactionMA2x2`, 15 MB, once) and build its prover. Checked against
+ * `SHARED_CIRCUIT_HASHES` like `loadProver`; pass `hashes: null` to skip that when serving your own build.
+ */
+export declare function loadSharedProver(baseUrl?: string, opts?: {
+    hashes?: {
+        wasm: string;
+        zkey: string;
+    } | null;
+}): Promise<Prover>;

package/dist/private/prover.js

@@ -20,6 +20,28 @@ export function createProver(wasm, zkey) {
         };
     };
 }
+/** Groth16 prover for the shared launch-token vault (`transactionMA2x2`, 8 public signals). */
+export function createSharedProver(wasm, zkey) {
+    return async (input) => {
+        const snarkjs = await import("snarkjs");
+        const { proof, publicSignals } = await snarkjs.groth16.fullProve(Object.fromEntries(Object.entries(input).map(([k, v]) => [k, str(v)])), wasm, zkey);
+        const s = publicSignals.map(BigInt);
+        return {
+            a: [BigInt(proof.pi_a[0]), BigInt(proof.pi_a[1])],
+            b: [
+                [BigInt(proof.pi_b[0][1]), BigInt(proof.pi_b[0][0])],
+                [BigInt(proof.pi_b[1][1]), BigInt(proof.pi_b[1][0])],
+            ],
+            c: [BigInt(proof.pi_c[0]), BigInt(proof.pi_c[1])],
+            root: s[0],
+            publicAmount: s[1],
+            extDataHash: s[2],
+            publicAsset: s[3],
+            inputNullifiers: [s[4], s[5]],
+            outputCommitments: [s[6], s[7]],
+        };
+    };
+}
 /** Hosted circuit artifacts. */
 export const CIRCUITS_URL = "https://cloak.boblabs.tech/circuits";
 /** SHA-256 of the artifacts this SDK version was built and tested against. */
@@ -53,3 +75,29 @@ export async function loadProver(baseUrl = CIRCUITS_URL, opts = {}) {
     }
     return createProver(wasm, zkey);
 }
+/** SHA-256 of the shared-vault circuit artifacts this SDK version was built and tested against. */
+export const SHARED_CIRCUIT_HASHES = {
+    wasm: "55712f66e67fd9345daac5c881c2e73c546864dbd1e23481463b603b47aa53ed",
+    zkey: "86ecee336f022ac1d2dbcc4db7e85ef838aee34c4d75fe8bc7446db86f3b97b3",
+};
+/**
+ * Fetch the shared launch-token vault's circuit (`transactionMA2x2`, 15 MB, once) and build its prover. Checked against
+ * `SHARED_CIRCUIT_HASHES` like `loadProver`; pass `hashes: null` to skip that when serving your own build.
+ */
+export async function loadSharedProver(baseUrl = CIRCUITS_URL, opts = {}) {
+    const base = baseUrl.replace(/\/$/, "");
+    const get = async (name) => {
+        const res = await fetch(`${base}/${name}`);
+        if (!res.ok)
+            throw new Error(`could not download ${name} from ${base} (${res.status})`);
+        return new Uint8Array(await res.arrayBuffer());
+    };
+    const [wasm, zkey] = await Promise.all([get("transactionMA2x2.wasm"), get("transactionMA2x2_final.zkey")]);
+    const want = opts.hashes === undefined ? SHARED_CIRCUIT_HASHES : opts.hashes;
+    if (want) {
+        const [hw, hz] = await Promise.all([sha256(wasm), sha256(zkey)]);
+        if (hw !== want.wasm || hz !== want.zkey)
+            throw new Error("shared-vault circuit files don't match this SDK version's hashes; refusing to prove with them");
+    }
+    return createSharedProver(wasm, zkey);
+}

package/dist/private/shared.d.ts

@@ -0,0 +1,127 @@
+import { type Address, type Hex } from "viem";
+import { type Wallet } from "../cloak.js";
+import type { ProofArgs, Prover } from "./prover.js";
+import { type ExtData, type OwnedNote } from "./tx.js";
+import type { CloakPrivate, RelayQuote, Status } from "./client.js";
+/**
+ * The shared launch-token vault (testnet experiment): one private vault for every Cloak launch token that opens on
+ * Uniswap from now on, next to the single-token vaults of HYPE and USDC.
+ *
+ *   shield    wallet tokens → private note (one-time key)
+ *   buy       private HYPE → private token, through the launch's Uniswap pool
+ *   sell      private token → private HYPE
+ *   send      private token → any cloak: address, and nobody can tell WHICH token moved: the vault sees a send with no
+ *             fee, and the relayer is paid from the sender's private HYPE in the same transaction
+ *   unshield  private token → any address
+ *
+ * Each note holds one token (Poseidon(amount, pubKey, blinding, token)), and every proof spends and creates notes of a
+ * single token only. Uses the account's keys, HYPE vault and relayer from `CloakPrivate`.
+ */
+export declare const SHARED_SWAP_DATA_ABI: readonly [{
+    readonly type: "tuple";
+    readonly components: readonly [{
+        readonly name: "token";
+        readonly type: "address";
+    }, {
+        readonly name: "minOut";
+        readonly type: "uint256";
+    }, {
+        readonly name: "outPubKey";
+        readonly type: "uint256";
+    }, {
+        readonly name: "outBlinding";
+        readonly type: "uint256";
+    }, {
+        readonly name: "outMemo";
+        readonly type: "bytes";
+    }, {
+        readonly name: "deadline";
+        readonly type: "uint64";
+    }];
+}];
+export type SharedRelayKind = "sharedTransact" | "sharedBuy" | "sharedSell" | "sharedSend";
+export interface SharedRelayCall {
+    kind: SharedRelayKind;
+    /** The shared-vault proof (or, for sharedBuy, the HYPE vault proof). */
+    proof: ProofArgs;
+    extData: ExtData;
+    /** sharedSend only: the HYPE vault proof that pays the relayer. */
+    feeProof?: ProofArgs;
+    feeExtData?: ExtData;
+}
+export type SharedSubmitter = ((call: SharedRelayCall) => Promise<Hex>) & {
+    /** The relayer's fee: in HYPE for sharedBuy and sharedSend, in the token for sharedTransact and sharedSell. */
+    quote?: (kind: SharedRelayKind, token: Address) => Promise<RelayQuote>;
+};
+/** POST shared-vault calls to a Cloak relayer (`services/keeper` serves `/relay-shared` and `/quote-shared`). */
+export declare function sharedRelayerSubmitter(url: string): SharedSubmitter;
+/** Submit shared-vault calls from a wallet (that wallet pays gas and appears as the sender). For tests and relayers. */
+export declare function sharedWalletSubmitter(priv: CloakPrivate, wallet: Wallet, vault: Address, router: Address): SharedSubmitter;
+export interface SharedToken {
+    token: Address;
+    market: Address;
+    symbol: string;
+}
+export declare class SharedVaultClient {
+    readonly priv: CloakPrivate;
+    readonly vault: Address;
+    readonly router: Address;
+    readonly prover: () => Promise<Prover>;
+    readonly submit: SharedSubmitter;
+    readonly fromBlock: bigint;
+    tokens: SharedToken[];
+    private leaves;
+    private scannedUpTo;
+    private notes;
+    private nextBlock;
+    constructor(priv: CloakPrivate, vault: Address, router: Address, prover: () => Promise<Prover>, submit: SharedSubmitter, fromBlock?: bigint);
+    private get pub();
+    /** Every token admitted to the vault, with its Uniswap market. */
+    loadTokens(): Promise<SharedToken[]>;
+    /** Whether `token` is in the shared vault (reads the vault's list if it isn't known yet). */
+    isAdmitted(token: Address): Promise<boolean>;
+    private info;
+    /** Let a settled Uniswap launch's token into the vault (anyone can; costs gas). */
+    admit(wallet: Wallet, factory: Address, launchIndex: bigint): Promise<Hex>;
+    /** Pull new notes, find which are ours and which token each holds, refresh spent flags. */
+    sync(): Promise<OwnedNote[]>;
+    /** Private balance of `token` in the shared vault. */
+    balance(token: Address): Promise<bigint>;
+    /** Every token this account holds privately in the shared vault. */
+    balances(): Promise<{
+        token: Address;
+        symbol: string;
+        amount: bigint;
+    }[]>;
+    /** The most one withdrawal (or sell) of `token` can take: the balance minus the relayer's fee (with a 25% cushion). */
+    maxWithdraw(token: Address, kind?: "sharedTransact" | "sharedSell"): Promise<bigint>;
+    private tree;
+    private quote;
+    /** 1–2 notes of `token` covering `target`, combining notes first (a relayed send to yourself) when needed. */
+    private inputsFor;
+    /** Expected output of a swap through `token`'s Uniswap market (0.3% fee), before slippage. */
+    quoteSwap(token: Address, side: "buy" | "sell", amountIn: bigint): Promise<bigint>;
+    /** Wallet tokens → a private note on a one-time key. This step is public (the wallet deposits). */
+    shield(wallet: Wallet, token: Address, amount: bigint, onStatus?: Status): Promise<Hex>;
+    /** Claim won bids of a shared-vault launch and move the tokens in. Two public steps from the bidder's wallet. */
+    claimInto(wallet: Wallet, auction: Address, bidIds: bigint[], onStatus?: Status): Promise<{
+        tokens: bigint;
+    }>;
+    /** Private HYPE → private `token`. The HYPE side, the swap and the output note are proven here, relayed elsewhere. */
+    buy(token: Address, hypeIn: bigint, opts?: {
+        slippageBps?: number;
+        onStatus?: Status;
+    }): Promise<Hex>;
+    /** Private `token` → private HYPE. */
+    sell(token: Address, amount: bigint, opts?: {
+        slippageBps?: number;
+        onStatus?: Status;
+    }): Promise<Hex>;
+    /**
+     * Send `amount` of `token` to a cloak: address without revealing which token: the shared-vault proof names no token
+     * and pays no fee, and a second proof pays the relayer from this account's private HYPE. Needs some private HYPE.
+     */
+    send(token: Address, amount: bigint, to: string, onStatus?: Status): Promise<Hex>;
+    /** Private `token` → `to` (any address). Names the token, as any withdrawal must. */
+    unshield(token: Address, amount: bigint, to: Address, onStatus?: Status): Promise<Hex>;
+}