@cloakely/sdk 0.4.0 → 0.6.0

package/dist/cloak.d.ts

@@ -1,4 +1,6 @@
 import { type Account, type Address, type Chain, type Hex, type PublicClient, type Transport, type WalletClient } from "viem";
+/** `lpLockUntil` for "locked forever, the creator earns the pool's trading fees". */
+export declare const LOCK_FOREVER_FEES: bigint;
 import { type BidPreimage } from "./seal.js";
 export type Wallet = WalletClient<Transport, Chain, Account>;
 export interface LaunchParams {
@@ -21,8 +23,11 @@ export interface LaunchParams {
     revealEnd: number;
     /** Share of the raise that seeds the pool, in bps (default 5000). */
     lpBps?: number;
-    /** Unix seconds until LP shares can be released to the creator; 0 / "burn" burns them (default). */
-    lpLockUntil?: number | "burn";
+    /**
+     * What happens to the pool's LP: "burn" (default) burns it; "fees" locks it forever and pays the creator the pool's
+     * 0.3% trading fees (CloakFeeLocker); a unix time locks it until then, when the creator can take it.
+     */
+    lpLockUntil?: number | "burn" | "fees";
     noRevealPenaltyBps?: number;
     creator?: Address;
     metadataURI?: string;
@@ -53,7 +58,12 @@ export interface AuctionState {
     clearingPrice: bigint;
     sold: bigint;
     raised: bigint;
+    /** The market Cloak trades: a CloakV2Market in front of a Uniswap V2 pool, or (earlier launches) a CloakPair. */
     pair: Address;
+    /** The launch's Uniswap V2 pool (token / WHYPE), tradable and tracked everywhere. Zero for a CloakPair market. */
+    uniPair: Address;
+    /** The LP is locked forever and the creator earns its trading fees (see `creatorFees`). */
+    creatorFees: boolean;
     tokenName: string;
     tokenSymbol: string;
     /** Launch fee on a successful raise, fixed when the auction was created. */
@@ -123,6 +133,20 @@ export declare class Cloak {
     private listLegacy;
     private listCurrent;
     getAuction(auction: Address): Promise<AuctionState>;
+    /**
+     * The creator's trading fees for a launch whose LP is locked forever: what can be claimed now (in tokens and WHYPE),
+     * who receives it, and the locker position. `null` for launches without creator fees.
+     */
+    creatorFees(auction: Address): Promise<{
+        locker: Address;
+        position: bigint;
+        beneficiary: Address;
+        claimableLp: bigint;
+        tokens: bigint;
+        whype: bigint;
+    } | null>;
+    /** Pay a launch's earned trading fees to its creator (anyone can send this; the fees always go to the creator). */
+    claimCreatorFees(auction: Address): Promise<Hex>;
     /** Revealed demand per tick (empty until the reveal phase — that is the point). */
     demandCurve(auction: Address): Promise<{
         tick: number;
@@ -218,8 +242,19 @@ export declare class Cloak {
             readonly name: "config_";
             readonly type: "address";
             readonly internalType: "contract CloakConfig";
+        }, {
+            readonly name: "seeder_";
+            readonly type: "address";
+            readonly internalType: "contract IMarketSeeder";
+        }, {
+            readonly name: "feeLocker_";
+            readonly type: "address";
+            readonly internalType: "contract IFeeLocker";
         }];
         readonly stateMutability: "nonpayable";
+    }, {
+        readonly type: "receive";
+        readonly stateMutability: "payable";
     }, {
         readonly type: "function";
         readonly name: "DEAD";
@@ -250,6 +285,16 @@ export declare class Cloak {
             readonly internalType: "uint256";
         }];
         readonly stateMutability: "view";
+    }, {
+        readonly type: "function";
+        readonly name: "LOCK_FOREVER_FEES";
+        readonly inputs: readonly [];
+        readonly outputs: readonly [{
+            readonly name: "";
+            readonly type: "uint64";
+            readonly internalType: "uint64";
+        }];
+        readonly stateMutability: "view";
     }, {
         readonly type: "function";
         readonly name: "MAX_TICKS";
@@ -472,6 +517,16 @@ export declare class Cloak {
             readonly internalType: "uint256";
         }];
         readonly stateMutability: "view";
+    }, {
+        readonly type: "function";
+        readonly name: "creatorFees";
+        readonly inputs: readonly [];
+        readonly outputs: readonly [{
+            readonly name: "";
+            readonly type: "bool";
+            readonly internalType: "bool";
+        }];
+        readonly stateMutability: "view";
     }, {
         readonly type: "function";
         readonly name: "creatorOwed";
@@ -536,6 +591,26 @@ export declare class Cloak {
             readonly internalType: "bool";
         }];
         readonly stateMutability: "view";
+    }, {
+        readonly type: "function";
+        readonly name: "feeLocker";
+        readonly inputs: readonly [];
+        readonly outputs: readonly [{
+            readonly name: "";
+            readonly type: "address";
+            readonly internalType: "contract IFeeLocker";
+        }];
+        readonly stateMutability: "view";
+    }, {
+        readonly type: "function";
+        readonly name: "feePosition";
+        readonly inputs: readonly [];
+        readonly outputs: readonly [{
+            readonly name: "";
+            readonly type: "uint256";
+            readonly internalType: "uint256";
+        }];
+        readonly stateMutability: "view";
     }, {
         readonly type: "function";
         readonly name: "feesOwed";
@@ -830,6 +905,16 @@ export declare class Cloak {
             readonly internalType: "uint256";
         }];
         readonly stateMutability: "view";
+    }, {
+        readonly type: "function";
+        readonly name: "seeder";
+        readonly inputs: readonly [];
+        readonly outputs: readonly [{
+            readonly name: "";
+            readonly type: "address";
+            readonly internalType: "contract IMarketSeeder";
+        }];
+        readonly stateMutability: "view";
     }, {
         readonly type: "function";
         readonly name: "settle";
@@ -892,6 +977,16 @@ export declare class Cloak {
             readonly internalType: "uint256";
         }];
         readonly stateMutability: "view";
+    }, {
+        readonly type: "function";
+        readonly name: "uniPair";
+        readonly inputs: readonly [];
+        readonly outputs: readonly [{
+            readonly name: "";
+            readonly type: "address";
+            readonly internalType: "address";
+        }];
+        readonly stateMutability: "view";
     }, {
         readonly type: "function";
         readonly name: "withdrawProceeds";
@@ -978,6 +1073,21 @@ export declare class Cloak {
             readonly internalType: "bytes";
         }];
         readonly anonymous: false;
+    }, {
+        readonly type: "event";
+        readonly name: "CreatorFeesOn";
+        readonly inputs: readonly [{
+            readonly name: "locker";
+            readonly type: "address";
+            readonly indexed: false;
+            readonly internalType: "address";
+        }, {
+            readonly name: "position";
+            readonly type: "uint256";
+            readonly indexed: false;
+            readonly internalType: "uint256";
+        }];
+        readonly anonymous: false;
     }, {
         readonly type: "event";
         readonly name: "DustSwept";
@@ -1183,6 +1293,26 @@ export declare class Cloak {
             readonly internalType: "uint256";
         }];
         readonly anonymous: false;
+    }, {
+        readonly type: "event";
+        readonly name: "UniswapMarket";
+        readonly inputs: readonly [{
+            readonly name: "uniPair";
+            readonly type: "address";
+            readonly indexed: true;
+            readonly internalType: "address";
+        }, {
+            readonly name: "market";
+            readonly type: "address";
+            readonly indexed: false;
+            readonly internalType: "address";
+        }, {
+            readonly name: "lpShares";
+            readonly type: "uint256";
+            readonly indexed: false;
+            readonly internalType: "uint256";
+        }];
+        readonly anonymous: false;
     }], "Committed", true, bigint, bigint>>;
     /**
      * Decrypt every sealed bid whose drand round has passed and reveal them in batches. Anyone can run this — it needs no

package/dist/cloak.js

@@ -1,5 +1,7 @@
 import { zeroAddress, encodeAbiParameters, keccak256, parseEventLogs, toHex, } from "viem";
-import { cloakAuctionAbi, cloakFactoryAbi, cloakPairAbi, cloakTokenAbi } from "./abis.js";
+import { cloakAuctionAbi, cloakFactoryAbi, cloakFeeLockerAbi, cloakPairAbi, cloakTokenAbi } from "./abis.js";
+/** `lpLockUntil` for "locked forever, the creator earns the pool's trading fees". */
+export const LOCK_FOREVER_FEES = 2n ** 64n - 1n;
 import { drandRoundAt, sealBid, unsealBid } from "./seal.js";
 const WAD = 10n ** 18n;
 const PHASES = ["commit", "reveal", "settle", "settled"];
@@ -88,7 +90,7 @@ export class Cloak {
         if (!this.factory)
             throw new Error("Cloak: factory address required");
         const w = this.wallet();
-        const lock = p.lpLockUntil === undefined || p.lpLockUntil === "burn" ? 0 : p.lpLockUntil;
+        const lock = p.lpLockUntil === undefined || p.lpLockUntil === "burn" ? 0n : p.lpLockUntil === "fees" ? LOCK_FOREVER_FEES : BigInt(p.lpLockUntil);
         const params = {
             creator: p.creator ?? w.account.address,
             saleSupply: p.saleSupply,
@@ -100,7 +102,7 @@ export class Cloak {
             revealEnd: BigInt(p.revealEnd),
             lpBps: p.lpBps ?? 5000,
             noRevealPenaltyBps: p.noRevealPenaltyBps ?? 1000,
-            lpLockUntil: BigInt(lock),
+            lpLockUntil: lock,
             tlockRound: BigInt(drandRoundAt(p.commitEnd)),
         };
         const txHash = await w.writeContract({
@@ -120,47 +122,34 @@ export class Cloak {
     async listLaunches() {
         if (!this.factory)
             throw new Error("Cloak: factory address required");
-        const legacy = [];
-        for (const f of this.legacyFactories)
-            legacy.push(...(await this.listLegacy(f)));
-        return [...(await this.listCurrent()), ...legacy];
+        // every factory, and every launch in it, read at once (a multicall client folds them into a few requests)
+        const [current, ...legacy] = await Promise.all([this.listCurrent(), ...this.legacyFactories.map((f) => this.listLegacy(f))]);
+        return [...current, ...legacy.flat()];
     }
     async listLegacy(factory) {
         const n = await this.publicClient.readContract({ address: factory, abi: cloakFactoryAbi, functionName: "launchesCount" });
-        const out = [];
-        for (let i = 0n; i < n; i++) {
+        return Promise.all(Array.from({ length: Number(n) }, async (_, k) => {
+            const i = BigInt(k);
             // a factory from v2 on returns a vesting contract too; the first one returns five fields
             const six = await this.publicClient.readContract({ address: factory, abi: cloakFactoryAbi, functionName: "launches", args: [i] }).catch(() => null);
             const [auction, token, creator, launchpad, creatorAlloc] = six ?? (await this.publicClient.readContract({ address: factory, abi: LEGACY_LAUNCHES_ABI, functionName: "launches", args: [i] }));
-            out.push({ auction, token, creator, launchpad, creatorAlloc, vesting: (six?.[5] ?? zeroAddress), factory, index: i, legacy: true });
-        }
-        return out;
+            return { auction, token, creator, launchpad, creatorAlloc, vesting: (six?.[5] ?? zeroAddress), factory, index: i, legacy: true };
+        }));
     }
     async listCurrent() {
-        if (!this.factory)
-            throw new Error("Cloak: factory address required");
-        const n = await this.publicClient.readContract({
-            address: this.factory,
-            abi: cloakFactoryAbi,
-            functionName: "launchesCount",
-        });
-        const out = [];
-        for (let i = 0n; i < n; i++) {
-            const [auction, token, creator, launchpad, creatorAlloc, vesting] = await this.publicClient.readContract({
-                address: this.factory,
-                abi: cloakFactoryAbi,
-                functionName: "launches",
-                args: [i],
-            });
-            out.push({ auction, token, creator, launchpad, creatorAlloc, vesting, factory: this.factory, index: i });
-        }
-        return out;
+        const factory = this.factory;
+        const n = await this.publicClient.readContract({ address: factory, abi: cloakFactoryAbi, functionName: "launchesCount" });
+        return Promise.all(Array.from({ length: Number(n) }, async (_, k) => {
+            const index = BigInt(k);
+            const [auction, token, creator, launchpad, creatorAlloc, vesting] = await this.publicClient.readContract({ address: factory, abi: cloakFactoryAbi, functionName: "launches", args: [index] });
+            return { auction, token, creator, launchpad, creatorAlloc, vesting, factory, index };
+        }));
     }
     // ───────────── reads ─────────────
     async getAuction(auction) {
         const c = { address: auction, abi: cloakAuctionAbi };
         const r = this.publicClient;
-        const [params, token, phase, commits, reveals, totalDeposits, totalDemand, settled, failed, clearingTick, clearingPrice, sold, raised, pair, launchFeeBps, bidCap, depositCap, creatorOwed, feesOwed] = await Promise.all([
+        const [params, token, phase, commits, reveals, totalDeposits, totalDemand, settled, failed, clearingTick, clearingPrice, sold, raised, pair, launchFeeBps, bidCap, depositCap, creatorOwed, feesOwed, uniPair, creatorFees] = await Promise.all([
             r.readContract({ ...c, functionName: "params" }),
             r.readContract({ ...c, functionName: "token" }),
             r.readContract({ ...c, functionName: "phase" }),
@@ -181,6 +170,9 @@ export class Cloak {
             r.readContract({ ...c, functionName: "depositCap" }).catch(() => 0n),
             r.readContract({ ...c, functionName: "creatorOwed" }).catch(() => 0n),
             r.readContract({ ...c, functionName: "feesOwed" }).catch(() => 0n),
+            // launches from the Uniswap factory on
+            r.readContract({ ...c, functionName: "uniPair" }).catch(() => zeroAddress),
+            r.readContract({ ...c, functionName: "creatorFees" }).catch(() => false),
         ]);
         const [creator, saleSupply, lpReserve, minPrice, tickSize, numTicks, commitEnd, revealEnd, lpBps, noRevealPenaltyBps, lpLockUntil, tlockRound] = params;
         const [tokenName, tokenSymbol] = await Promise.all([
@@ -214,6 +206,8 @@ export class Cloak {
             sold,
             raised,
             pair,
+            uniPair,
+            creatorFees,
             tokenName,
             tokenSymbol,
             launchFeeBps,
@@ -223,6 +217,40 @@ export class Cloak {
             feesOwed,
         };
     }
+    /**
+     * The creator's trading fees for a launch whose LP is locked forever: what can be claimed now (in tokens and WHYPE),
+     * who receives it, and the locker position. `null` for launches without creator fees.
+     */
+    async creatorFees(auction) {
+        const c = { address: auction, abi: cloakAuctionAbi };
+        const on = await this.publicClient.readContract({ ...c, functionName: "creatorFees" }).catch(() => false);
+        if (!on)
+            return null;
+        const [locker, position, token, uniPair] = await Promise.all([
+            this.publicClient.readContract({ ...c, functionName: "feeLocker" }),
+            this.publicClient.readContract({ ...c, functionName: "feePosition" }),
+            this.publicClient.readContract({ ...c, functionName: "token" }),
+            this.publicClient.readContract({ ...c, functionName: "uniPair" }),
+        ]);
+        const l = { address: locker, abi: cloakFeeLockerAbi };
+        const [pos, claimableLp, [a0, a1], token0] = await Promise.all([
+            this.publicClient.readContract({ ...l, functionName: "positions", args: [position] }),
+            this.publicClient.readContract({ ...l, functionName: "claimable", args: [position] }),
+            this.publicClient.readContract({ ...l, functionName: "claimableAmounts", args: [position] }),
+            this.publicClient.readContract({ address: uniPair, abi: [{ type: "function", name: "token0", stateMutability: "view", inputs: [], outputs: [{ type: "address" }] }], functionName: "token0" }),
+        ]);
+        const tokenIs0 = token0.toLowerCase() === token.toLowerCase();
+        return { locker, position, beneficiary: pos.beneficiary, claimableLp, tokens: tokenIs0 ? a0 : a1, whype: tokenIs0 ? a1 : a0 };
+    }
+    /** Pay a launch's earned trading fees to its creator (anyone can send this; the fees always go to the creator). */
+    async claimCreatorFees(auction) {
+        const f = await this.creatorFees(auction);
+        if (!f)
+            throw new Error("this launch has no creator fees");
+        if (f.claimableLp === 0n)
+            throw new Error("no fees earned yet");
+        return this.send(await this.wallet().writeContract({ address: f.locker, abi: cloakFeeLockerAbi, functionName: "claim", args: [f.position] })).then((r) => r.transactionHash);
+    }
     /** Revealed demand per tick (empty until the reveal phase — that is the point). */
     async demandCurve(auction) {
         const s = await this.getAuction(auction);

package/dist/deployments.d.ts

@@ -28,6 +28,14 @@ export interface CloakDeployment {
     factory: Address;
     /** Block the factory was deployed in: scan launch events from here. */
     factoryBlock: bigint;
+    /** Earlier factories of this same deployment (newest first): their launches still list, settle and trade. */
+    earlierFactories?: Address[];
+    /** Block of this deployment's first factory: scan its launches' bids from here (defaults to `factoryBlock`). */
+    firstFactoryBlock?: bigint;
+    /** CloakSeeder: opens each settled launch's market (a Uniswap V2 pool where the chain has one). */
+    seeder?: Address;
+    /** CloakFeeLocker: holds "locked forever" LP and pays its trading fees to the creator. */
+    feeLocker?: Address;
     router: Address;
     /** Block the router was deployed in: scan private-pool events from here. */
     routerBlock: bigint;
@@ -52,6 +60,8 @@ export interface CloakDeployment {
     previous?: PreviousDeployment[];
 }
 export declare const deployments: Record<number, CloakDeployment>;
+/** Every factory before `d.factory` whose launches should still list, newest first: this deployment's, then earlier ones'. */
+export declare function legacyFactories(d: CloakDeployment): Address[];
 /** The Cloak deployment on `chainId`, or an error naming the chains Cloak is on. */
 export declare function deploymentFor(chainId: number): CloakDeployment;
 /**

package/dist/deployments.js

@@ -1,7 +1,7 @@
 import { privateRouterAbi } from "./abis.js";
 import { readRegistry } from "./registry.js";
 export const deployments = {
-    // Cloak v4 (Oct 31), the permanent vaults: deployments/elysium-testnet-v4.json. CloakConfig's registry lists all of it;
+    // Cloak v4 (Oct 31), the permanent vaults, plus the Uniswap launch factory (Nov 2): deployments/elysium-testnet-v4.json. CloakConfig's registry lists all of it;
     // liveDeployment() reads the current contracts from there.
     99801: {
         chainId: 99801,
@@ -9,8 +9,14 @@ export const deployments = {
         config: "0x9fdf166f0671166148ea98cdd3ef0118d256167f",
         vaults: "0x24bc1d369aab3a2d741a48f8cac1af5dfd9f3d43",
         vaultsBlock: 19485039n,
-        factory: "0xa88df63d7d44acc66052e5cbe5ba9503bf940993",
-        factoryBlock: 19484794n,
+        // the creator-fee launch factory (Nov 2): every launch opens a Uniswap V2 pool at its clearing price, and its LP can
+        // be locked forever with the trading fees going to the creator
+        factory: "0xd179bad69715f4bd4796dd7a4103be143fba02ad",
+        factoryBlock: 21312271n,
+        earlierFactories: ["0xeac84944f5a8343edf49cde8ef74d71f4908a656", "0xa88df63d7d44acc66052e5cbe5ba9503bf940993"],
+        firstFactoryBlock: 19484794n,
+        seeder: "0x633aa82b806dafc0ae4c84418d23f3726139a88d",
+        feeLocker: "0x3b74062a72b16f9a221d63515518a635414501d8",
         router: "0x343ab9a7aac93cee28321410510ea24417cc6386",
         routerBlock: 19485063n,
         batcher: "0xc69e4bca18020ae93bc9f17093985bfb139a3203",
@@ -54,6 +60,10 @@ export const deployments = {
         ],
     },
 };
+/** Every factory before `d.factory` whose launches should still list, newest first: this deployment's, then earlier ones'. */
+export function legacyFactories(d) {
+    return [...(d.earlierFactories ?? []), ...(d.previous ?? []).map((p) => p.factory)].filter((f) => f && !/^0x0{40}$/i.test(f));
+}
 /** The Cloak deployment on `chainId`, or an error naming the chains Cloak is on. */
 export function deploymentFor(chainId) {
     const d = deployments[chainId];
@@ -81,6 +91,7 @@ export async function liveDeployment(publicClient, base) {
         vaultsBlock: reg.vaultsBlock ?? base.vaultsBlock,
         factory: reg.factory,
         factoryBlock: reg.factoryBlock,
+        earlierFactories: reg.earlierFactories.length ? reg.earlierFactories : base.earlierFactories,
         router: reg.router,
         routerBlock: reg.routerBlock,
         batcher: reg.batcher ?? base.batcher,

package/dist/private/client.d.ts

@@ -1,5 +1,5 @@
 import { type Address, type Hex, type PublicClient } from "viem";
-import type { Wallet } from "../cloak.js";
+import { type Wallet } from "../cloak.js";
 import { CloakKeys } from "./crypto.js";
 import { MerkleTree } from "./tree.js";
 import type { ProofArgs, Prover } from "./prover.js";
@@ -140,6 +140,49 @@ export declare class CloakPrivate {
         txHash: Hex;
         tokens: bigint;
     }>;
+    /**
+     * One-time bid wallet `n` for `auction`. The private balance pays its deposit and a little gas through a relayed
+     * withdrawal, so on-chain the bid comes from a fresh address nobody can tie to this account's wallet.
+     */
+    bidWallet(auction: Address, n: number): {
+        n: number;
+        address: Address;
+        wallet: Wallet;
+    };
+    /** Gas a bid wallet keeps for its own transactions: the bid, a private claim, and moving what's left back in. */
+    bidGasReserve(): Promise<bigint>;
+    /** This account's bid wallets for `auction` that have been used (newest last), found from the seed alone. */
+    bidWallets(auction: Address): Promise<{
+        n: number;
+        address: Address;
+        wallet: Wallet;
+    }[]>;
+    /**
+     * Place a sealed bid paid from the private HYPE balance: a relayed private withdrawal funds a fresh one-time wallet
+     * with the deposit plus gas, and that wallet seals the bid. Keep the returned secret like any bid's (auto-reveal makes
+     * losing it harmless). After settlement, `finishPrivateBids` claims the tokens privately and moves the refund back.
+     */
+    bidPrivately(auction: Address, opts: {
+        maxPrice: bigint;
+        quantity: bigint;
+        deposit?: bigint;
+    }, onStatus?: Status): Promise<{
+        secret: import("../cloak.js").BidSecret;
+        bidWallet: `0x${string}`;
+        n: number;
+        fundTx: `0x${string}`;
+    }>;
+    /**
+     * After a launch settles: for every bid this account placed from its private balance, claim won tokens straight into
+     * the private vault (or, if a cap blocks that, to the bid wallet and then in), collect refunds, and move the bid
+     * 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<{
+        claimed: number;
+        movedHype: bigint;
+        movedTokens: bigint;
+    }>;
     roundInfo(): Promise<{
         round: bigint;
         endsAt: number;

package/dist/private/client.js

@@ -1,5 +1,7 @@
-import { encodeAbiParameters, parseEventLogs, zeroAddress } from "viem";
-import { cloakAuctionAbi, cloakMigratorAbi, cloakPairAbi, privateBatcherAbi, privateRouterAbi, shieldedPoolAbi } from "../abis.js";
+import { createWalletClient, custom, encodeAbiParameters, parseEventLogs, zeroAddress } from "viem";
+import { privateKeyToAccount } from "viem/accounts";
+import { cloakAuctionAbi, cloakConfigAbi, cloakMigratorAbi, cloakPairAbi, privateBatcherAbi, privateRouterAbi, shieldedPoolAbi } from "../abis.js";
+import { Cloak } from "../cloak.js";
 import { ACCOUNT_MESSAGE, ACCOUNT_TYPED_DATA, ROUTER_ACCOUNT_TYPED_DATA, CloakKeys, MAIN_KEY, noteCommitment, encryptFullMemo, encryptRouterMemo, formatCloakAddress, nullifierOf, parseCloakAddress, randomField, randomKeyIndex, readMemo, } from "./crypto.js";
 import { MerkleTree } from "./tree.js";
 import { MOVE_DATA_ABI, ORDER_DATA_ABI, SWAP_DATA_ABI, buildTransaction, selectNotes, splitStandard } from "./tx.js";
@@ -406,6 +408,131 @@ export class CloakPrivate {
             throw new Error("private claim reverted");
         return { txHash: hash, tokens };
     }
+    // ───────────── sealed bids paid from the private balance ─────────────
+    /**
+     * One-time bid wallet `n` for `auction`. The private balance pays its deposit and a little gas through a relayed
+     * withdrawal, so on-chain the bid comes from a fresh address nobody can tie to this account's wallet.
+     */
+    bidWallet(auction, n) {
+        const account = privateKeyToAccount(this.keys.bidWalletKey(auction, n));
+        const chain = this.publicClient.chain;
+        if (!chain)
+            throw new Error("the public client needs a chain");
+        const wallet = createWalletClient({ account, chain, transport: custom({ request: (a) => this.publicClient.request(a) }) });
+        return { n, address: account.address, wallet };
+    }
+    /** Gas a bid wallet keeps for its own transactions: the bid, a private claim, and moving what's left back in. */
+    async bidGasReserve() {
+        const gp = await this.publicClient.getGasPrice();
+        return (gp < 100000000n ? 100000000n : gp) * 6000000n;
+    }
+    /** This account's bid wallets for `auction` that have been used (newest last), found from the seed alone. */
+    async bidWallets(auction) {
+        const out = [];
+        for (let n = 0; n < 64; n++) {
+            const w = this.bidWallet(auction, n);
+            const [nonce, bal] = await Promise.all([this.publicClient.getTransactionCount({ address: w.address }), this.publicClient.getBalance({ address: w.address })]);
+            if (nonce === 0 && bal === 0n)
+                break;
+            out.push(w);
+        }
+        return out;
+    }
+    /**
+     * Place a sealed bid paid from the private HYPE balance: a relayed private withdrawal funds a fresh one-time wallet
+     * with the deposit plus gas, and that wallet seals the bid. Keep the returned secret like any bid's (auto-reveal makes
+     * losing it harmless). After settlement, `finishPrivateBids` claims the tokens privately and moves the refund back.
+     */
+    async bidPrivately(auction, opts, onStatus = () => { }) {
+        const reader = new Cloak(this.publicClient);
+        const s = await reader.getAuction(auction);
+        if (s.phase !== "commit")
+            throw new Error("commit phase is over");
+        const q = reader.quoteBid(s, opts.maxPrice, opts.quantity);
+        const deposit = opts.deposit ?? q.deposit;
+        if (deposit < q.cost)
+            throw new Error("deposit is below the bid's cost");
+        const used = await this.bidWallets(auction);
+        const bw = this.bidWallet(auction, used.length);
+        const gas = await this.bidGasReserve();
+        // the vault keeps its withdrawal fee from what arrives, so send enough that deposit + gas land in full
+        const config = await this.publicClient.readContract({ address: this.router, abi: privateRouterAbi, functionName: "config" });
+        const feeBps = BigInt(await this.publicClient.readContract({ address: config, abi: cloakConfigAbi, functionName: "withdrawFeeBps" }));
+        const want = deposit + gas;
+        const send = (want * 10000n + (10000n - feeBps) - 1n) / (10000n - feeBps);
+        onStatus("Paying the deposit from your private balance…");
+        const fund = await this.unshieldHype(bw.address, send, onStatus);
+        const r = await this.publicClient.waitForTransactionReceipt({ hash: fund });
+        if (r.status !== "success")
+            throw new Error("funding the bid wallet reverted");
+        for (let i = 0; i < 30 && (await this.publicClient.getBalance({ address: bw.address })) < want; i++)
+            await new Promise((x) => setTimeout(x, 1000));
+        if ((await this.publicClient.getBalance({ address: bw.address })) < deposit)
+            throw new Error("the bid wallet wasn't funded; nothing was bid, and the HYPE is in the one-time wallet (finishPrivateBids moves it back)");
+        onStatus("Sealing the bid from a one-time wallet…");
+        const secret = await new Cloak(this.publicClient, bw.wallet).bid(auction, { maxPrice: opts.maxPrice, quantity: opts.quantity, deposit });
+        return { secret, bidWallet: bw.address, n: bw.n, fundTx: fund };
+    }
+    /**
+     * After a launch settles: for every bid this account placed from its private balance, claim won tokens straight into
+     * the private vault (or, if a cap blocks that, to the bid wallet and then in), collect refunds, and move the bid
+     * 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 = () => { }) {
+        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());
+        for (const bw of await this.bidWallets(auction)) {
+            const c = new Cloak(this.publicClient, bw.wallet);
+            const bids = await reader.bidsOf(auction, bw.address);
+            // before settlement only a wallet whose bid never went through has anything to move back
+            if (!s.settled && bids.length > 0)
+                continue;
+            for (const b of bids) {
+                if (b.claimed)
+                    continue;
+                onStatus(`Claiming bid #${b.id}…`);
+                if (b.tokens > 0n && vaultOpen) {
+                    try {
+                        await this.claimPrivately(bw.wallet, auction, b.id);
+                        claimed++;
+                        continue;
+                    }
+                    catch { } // over the vault's deposit cap: claim to the bid wallet instead
+                }
+                await c.claim(auction, [b.id]);
+                claimed++;
+            }
+            const owed = await this.publicClient.readContract({ address: auction, abi: cloakAuctionAbi, functionName: "refundOwed", args: [bw.address] }).catch(() => 0n);
+            if (owed > 0n) {
+                const h = await bw.wallet.writeContract({ address: auction, abi: cloakAuctionAbi, functionName: "withdrawRefund", args: [bw.address] });
+                await this.publicClient.waitForTransactionReceipt({ hash: h });
+            }
+            if (vaultOpen) {
+                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);
+                        movedTokens += t;
+                    }
+                    catch { } // a cap may block it; the tokens stay in the one-time wallet, which nobody can tie to you
+                }
+            }
+            const bal = await this.publicClient.getBalance({ address: bw.address });
+            const keep = (await this.bidGasReserve()) / 3n; // gas for this last shield
+            if (bal > keep * 2n) {
+                onStatus("Moving the refund back into your private balance…");
+                await this.shieldHype(bw.wallet, bal - keep);
+                movedHype += bal - keep;
+            }
+        }
+        return { claimed, movedHype, movedTokens };
+    }
     // ───────────── batch auctions (hide trade size) ─────────────
     async roundInfo() {
         if (!this.batcher)

package/dist/private/crypto.d.ts

@@ -70,6 +70,12 @@ export declare class CloakKeys {
     static fromSignature(sig: Hex): CloakKeys;
     key(index: number): Promise<SpendKey>;
     main(): Promise<SpendKey>;
+    /**
+     * The private key of one-time bid wallet `n` for `auction`: a fresh address that bids from the private balance, so the
+     * bid can't be linked to the account's wallet. Derived from this account's seed, so the same signature always finds
+     * it again (on any device).
+     */
+    bidWalletKey(auction: Hex, n: number): Hex;
 }
 export interface Note {
     amount: bigint;

package/dist/private/crypto.js

@@ -77,6 +77,14 @@ export class CloakKeys {
     main() {
         return this.key(MAIN_KEY);
     }
+    /**
+     * The private key of one-time bid wallet `n` for `auction`: a fresh address that bids from the private balance, so the
+     * bid can't be linked to the account's wallet. Derived from this account's seed, so the same signature always finds
+     * it again (on any device).
+     */
+    bidWalletKey(auction, n) {
+        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 async function nullifierOf(n, leafIndex, privKey) {