@cloakely/sdk 0.8.1 → 0.8.3

package/dist/drops.js

@@ -0,0 +1,428 @@
+/**
+ * Sealed NFT drops: one collection and its sealed sale (CloakDrop), made by CloakDropFactory.
+ *
+ *   GTD      listed wallets mint their guaranteed spots at the creator's GTD price, until the GTD window closes.
+ *   Auction  everyone else bids what they'd pay, sealed to a drand round. The creator's price is the floor. Bids rank
+ *            by score: their price, or for WL bids their price × (1 + boost). Public winners pay the clearing score;
+ *            WL winners pay it ÷ (1 + boost), never under the floor. Bids tied at the clearing score share what's left
+ *            by a lottery whose random start comes from every bid's sealed salt.
+ *
+ * The GTD and WL lists live on chain only as Merkle roots. The lists themselves are published once, in the factory's
+ * DropDetails event, so anyone can rebuild a proof; a list that doesn't match the root proves nothing.
+ */
+import { encodeAbiParameters, getAddress, isAddress, keccak256, toHex } from "viem";
+import { cloakDropAbi, cloakDropFactoryAbi } from "./abis.js";
+import { commitmentOf } from "./cloak.js";
+import { drandRoundAt, drandRoundTime, sealBid, unsealBid } from "./seal.js";
+export const DROP_BPS = 10000n;
+export const DROP_MAX_BOOST_BPS = 3_000;
+export const DROP_MAX_PER_BID = 20;
+export const DROP_MAX_SUPPLY = 10_000;
+/** Most entries one GTD or WL list can hold (the lists travel in one transaction). */
+export const DROP_LIST_MAX = 2_000;
+/** How long the keeper has to open the bids at most. Settlement doesn't wait for it once every bid is open. */
+export const DROP_DEFAULT_REVEAL_SECS = 1_800;
+// ───────────────────────────── Merkle lists ─────────────────────────────
+const enc = (types, values) => encodeAbiParameters(types, values);
+/** A WL list entry, as the drop hashes it. */
+export const wlLeaf = (wallet) => keccak256(keccak256(enc([{ type: "address" }], [wallet])));
+/** A GTD list entry: a wallet and its number of spots. */
+export const gtdLeaf = (wallet, spots) => keccak256(keccak256(enc([{ type: "address" }, { type: "uint32" }], [wallet, spots])));
+const hashPair = (a, b) => BigInt(a) < BigInt(b) ? keccak256(enc([{ type: "bytes32" }, { type: "bytes32" }], [a, b])) : keccak256(enc([{ type: "bytes32" }, { type: "bytes32" }], [b, a]));
+/** A Merkle tree over `leaves` (sorted-pair hashing, the layout CloakDrop checks). */
+export function merkleTree(leaves) {
+    const base = [...new Set(leaves.map((l) => l.toLowerCase()))].sort((a, b) => (BigInt(a) < BigInt(b) ? -1 : 1));
+    if (!base.length)
+        return { root: `0x${"0".repeat(64)}`, proof: () => [] };
+    const layers = [base];
+    while (layers.at(-1).length > 1) {
+        const prev = layers.at(-1);
+        const next = [];
+        for (let i = 0; i < prev.length; i += 2)
+            next.push(i + 1 < prev.length ? hashPair(prev[i], prev[i + 1]) : prev[i]);
+        layers.push(next);
+    }
+    return {
+        root: layers.at(-1)[0],
+        proof(leaf) {
+            let i = layers[0].indexOf(leaf.toLowerCase());
+            if (i < 0)
+                throw new Error("not on the list");
+            const out = [];
+            for (let k = 0; k < layers.length - 1; k++) {
+                const sib = i ^ 1;
+                if (sib < layers[k].length)
+                    out.push(layers[k][sib]);
+                i = Math.floor(i / 2);
+            }
+            return out;
+        },
+    };
+}
+const PHASES = ["gtd", "bidding", "reveal", "settle", "numbering", "settled"];
+// ───────────────────────────── client ─────────────────────────────
+export class CloakDrops {
+    publicClient;
+    walletClient;
+    factory;
+    fromBlock;
+    constructor(publicClient, walletClient, factory, 
+    /** First block to read the factory's and drops' events from. */
+    fromBlock = 0n) {
+        this.publicClient = publicClient;
+        this.walletClient = walletClient;
+        this.factory = factory;
+        this.fromBlock = fromBlock;
+    }
+    /** Many reads in one multicall where the chain has multicall3, else one by one (a local chain). */
+    async reads(contracts) {
+        if (!contracts.length)
+            return [];
+        if (this.publicClient.chain?.contracts?.multicall3)
+            return this.publicClient.multicall({ contracts: contracts, allowFailure: false });
+        return Promise.all(contracts.map((c) => this.publicClient.readContract(c)));
+    }
+    wallet() {
+        if (!this.walletClient)
+            throw new Error("CloakDrops: a walletClient is required for this call");
+        return this.walletClient;
+    }
+    async send(hash) {
+        const r = await this.publicClient.waitForTransactionReceipt({ hash });
+        if (r.status !== "success")
+            throw new Error(`transaction reverted: ${hash}`);
+        return r;
+    }
+    /** Every drop the factory made, newest last. */
+    async list() {
+        const n = Number(await this.publicClient.readContract({ address: this.factory, abi: cloakDropFactoryAbi, functionName: "dropsCount" }));
+        if (!n)
+            return [];
+        return (await this.reads(Array.from({ length: n }, (_, i) => ({ address: this.factory, abi: cloakDropFactoryAbi, functionName: "drops", args: [BigInt(i)] }))));
+    }
+    /** Create a drop. The caller is its creator. Returns the drop's address. */
+    async create(o) {
+        const w = this.wallet();
+        if (!o.name.trim() || o.name.length > 64 || !o.symbol.trim() || o.symbol.length > 16)
+            throw new Error("Give the collection a name (up to 64 characters) and a symbol (up to 16).");
+        if (!Number.isInteger(o.supply) || o.supply < 1 || o.supply > DROP_MAX_SUPPLY)
+            throw new Error(`Supply is 1 to ${DROP_MAX_SUPPLY}.`);
+        if (o.floor <= 0n)
+            throw new Error("Set a price above zero.");
+        const boost = o.wl?.boostBps ?? 0;
+        if (boost < 0 || boost > DROP_MAX_BOOST_BPS)
+            throw new Error("The WL boost is 0% to 30%.");
+        if ((o.gtd?.list.length ?? 0) > DROP_LIST_MAX || (o.wl?.list.length ?? 0) > DROP_LIST_MAX)
+            throw new Error(`A list holds up to ${DROP_LIST_MAX} wallets.`);
+        const gtdList = (o.gtd?.list ?? []).map((e) => ({ wallet: getAddress(e.wallet), spots: e.spots }));
+        const wlList = (o.wl?.list ?? []).map((a) => getAddress(a));
+        for (const e of gtdList)
+            if (!Number.isInteger(e.spots) || e.spots < 1)
+                throw new Error(`Give ${e.wallet} at least one GTD spot.`);
+        const gtdSpots = gtdList.reduce((a, e) => a + e.spots, 0);
+        if (gtdSpots > o.supply)
+            throw new Error("There are more GTD spots than NFTs.");
+        const now = Number((await this.publicClient.getBlock()).timestamp);
+        const gtdEnd = now + 90 + (gtdList.length ? o.gtd.durationSecs : 0);
+        const commitEnd = gtdEnd + o.biddingSecs;
+        const tlockRound = drandRoundAt(commitEnd);
+        const revealEnd = Math.max(commitEnd + (o.revealSecs ?? DROP_DEFAULT_REVEAL_SECS), drandRoundTime(tlockRound) + 60);
+        const params = {
+            creator: w.account.address,
+            supply: o.supply,
+            maxPerBid: o.maxPerBid ?? 2,
+            numTicks: o.numTicks ?? 200,
+            wlBoostBps: wlList.length ? boost : 0,
+            royaltyBps: o.royaltyBps ?? 500,
+            gtdEnd: BigInt(gtdEnd),
+            commitEnd: BigInt(commitEnd),
+            revealEnd: BigInt(revealEnd),
+            tlockRound: BigInt(tlockRound),
+            floor: o.floor,
+            tickSize: o.tickSize ?? (o.floor / 20n || 1n),
+            gtdPrice: o.gtd?.price ?? 0n,
+            gtdRoot: merkleTree(gtdList.map((e) => gtdLeaf(e.wallet, e.spots))).root,
+            wlRoot: merkleTree(wlList.map(wlLeaf)).root,
+        };
+        const details = { v: 1, ...(o.image ? { image: o.image } : {}), ...(o.description ? { description: o.description.slice(0, 1000) } : {}), ...(gtdList.length ? { gtd: gtdList } : {}), ...(wlList.length ? { wl: wlList } : {}), ...(o.spots ? { spots: { partner: o.spots.partner.slice(0, 200) } } : {}) };
+        const { result, request } = await this.publicClient.simulateContract({
+            address: this.factory,
+            abi: cloakDropFactoryAbi,
+            functionName: "createDrop",
+            args: [params, o.name.trim(), o.symbol.trim(), o.baseURI.trim(), JSON.stringify(details)],
+            account: w.account,
+        });
+        const txHash = await w.writeContract(request);
+        await this.send(txHash);
+        return { drop: result, txHash };
+    }
+    /** A drop's published details: its image, description and the lists behind its roots. */
+    async details(drop) {
+        const logs = await this.chunked((from, to) => this.publicClient.getContractEvents({ address: this.factory, abi: cloakDropFactoryAbi, eventName: "DropDetails", args: { drop }, fromBlock: from, toBlock: to, strict: true }), true);
+        try {
+            const d = JSON.parse(logs[0]?.args.details ?? "{}");
+            return {
+                image: typeof d.image === "string" ? d.image : undefined,
+                description: typeof d.description === "string" ? d.description : undefined,
+                gtd: Array.isArray(d.gtd) ? d.gtd.filter((e) => isAddress(e?.wallet) && Number.isInteger(e?.spots)) : undefined,
+                wl: Array.isArray(d.wl) ? d.wl.filter((a) => isAddress(a)) : undefined,
+                spots: typeof d.spots?.partner === "string" ? { partner: d.spots.partner } : undefined,
+            };
+        }
+        catch {
+            return {};
+        }
+    }
+    async get(drop) {
+        const c = { address: drop, abi: cloakDropAbi };
+        const fn = ["params", "name", "symbol", "baseURI", "phase", "bidsCount", "revealCount", "gtdMinted", "auctionSupply", "totalSupply", "settled", "failed", "sold", "clearingScore", "tieSupply", "tieDemand"];
+        const r = await this.reads(fn.map((f) => ({ ...c, functionName: f })));
+        const p = r[0];
+        const settled = r[10];
+        const clearing = r[13];
+        const zero = `0x${"0".repeat(64)}`;
+        const publicPrice = settled ? (clearing + DROP_BPS - 1n) / DROP_BPS : 0n;
+        let wlPrice = settled ? (clearing + DROP_BPS + BigInt(p.wlBoostBps) - 1n) / (DROP_BPS + BigInt(p.wlBoostBps)) : 0n;
+        if (settled && wlPrice < p.floor)
+            wlPrice = p.floor;
+        return {
+            address: drop,
+            name: r[1],
+            symbol: r[2],
+            baseURI: r[3],
+            creator: p.creator,
+            supply: p.supply,
+            maxPerBid: p.maxPerBid,
+            numTicks: p.numTicks,
+            wlBoostBps: p.wlBoostBps,
+            royaltyBps: p.royaltyBps,
+            gtdEnd: Number(p.gtdEnd),
+            commitEnd: Number(p.commitEnd),
+            revealEnd: Number(p.revealEnd),
+            tlockRound: Number(p.tlockRound),
+            floor: p.floor,
+            tickSize: p.tickSize,
+            gtdPrice: p.gtdPrice,
+            hasGtd: p.gtdRoot !== zero,
+            hasWl: p.wlRoot !== zero,
+            phase: PHASES[Number(r[4])],
+            bids: Number(r[5]),
+            reveals: Number(r[6]),
+            gtdMinted: Number(r[7]),
+            auctionSupply: Number(r[8]),
+            minted: Number(r[9]),
+            settled,
+            failed: r[11],
+            sold: Number(r[12]),
+            publicPrice,
+            wlPrice,
+            tieSupply: Number(r[14]),
+            tieDemand: Number(r[15]),
+        };
+    }
+    /** The bid level for a price: the highest level at or below it (bids snap down, never up). */
+    static tickFor(s, price) {
+        if (price < s.floor)
+            throw new Error("Bid at least the creator's price.");
+        const t = s.tickSize > 0n ? Number((price - s.floor) / s.tickSize) : 0;
+        return Math.min(t, s.numTicks - 1);
+    }
+    static priceAt(s, tick) {
+        return s.floor + BigInt(tick) * s.tickSize;
+    }
+    /** Whether a wallet is on a drop's WL or GTD list (and with how many GTD spots). */
+    async listed(drop, wallet) {
+        const d = await this.details(drop);
+        const me = wallet.toLowerCase();
+        const gtd = d.gtd?.find((e) => e.wallet.toLowerCase() === me);
+        const gtdMinted = gtd ? Number(await this.publicClient.readContract({ address: drop, abi: cloakDropAbi, functionName: "gtdMintedBy", args: [wallet] })) : 0;
+        return { wl: !!d.wl?.some((a) => a.toLowerCase() === me), gtdSpots: gtd?.spots ?? 0, gtdMinted };
+    }
+    /** Mint GTD spots from the listed wallet (the connected one). */
+    async gtdMint(drop, quantity) {
+        const w = this.wallet();
+        const [s, d] = await Promise.all([this.get(drop), this.details(drop)]);
+        const me = w.account.address;
+        const entry = d.gtd?.find((e) => e.wallet.toLowerCase() === me.toLowerCase());
+        if (!entry)
+            throw new Error("This wallet isn't on the GTD list.");
+        const tree = merkleTree((d.gtd ?? []).map((e) => gtdLeaf(getAddress(e.wallet), e.spots)));
+        const leaf = gtdLeaf(getAddress(entry.wallet), entry.spots);
+        const hash = await w.writeContract({ address: drop, abi: cloakDropAbi, functionName: "gtdMint", args: [entry.spots, tree.proof(leaf), quantity], value: s.gtdPrice * BigInt(quantity) });
+        await this.send(hash);
+        return hash;
+    }
+    /**
+     * Place a sealed bid: `quantity` NFTs at up to `price` wei each. The bid is encrypted to the drop's drand round, so
+     * nobody can read it before bidding closes; the keeper opens it then. A WL bid must come from the listed wallet.
+     * `deposit` may be more than the bid needs (the rest comes back), which hides the bid's size from the deposit.
+     */
+    async bid(drop, o) {
+        const w = this.wallet();
+        const s = await this.get(drop);
+        if (s.phase !== "bidding")
+            throw new Error(s.phase === "gtd" ? "Bidding opens when the GTD window closes." : "Bidding has closed.");
+        if (!Number.isInteger(o.quantity) || o.quantity < 1 || o.quantity > s.maxPerBid)
+            throw new Error(`Bid for 1 to ${s.maxPerBid} NFTs.`);
+        const tick = CloakDrops.tickFor(s, o.price);
+        const cost = CloakDrops.priceAt(s, tick) * BigInt(o.quantity);
+        const deposit = o.deposit ?? cost;
+        if (deposit < cost)
+            throw new Error("The deposit must cover the bid.");
+        let proof = [];
+        if (o.wl) {
+            const d = await this.details(drop);
+            const list = (d.wl ?? []).map((a) => getAddress(a));
+            if (!list.some((a) => a.toLowerCase() === w.account.address.toLowerCase()))
+                throw new Error("This wallet isn't on the WL.");
+            proof = merkleTree(list.map(wlLeaf)).proof(wlLeaf(w.account.address));
+        }
+        const salt = toHex(crypto.getRandomValues(new Uint8Array(32)));
+        const quantity = BigInt(o.quantity);
+        const commitment = commitmentOf(drop, w.account.address, tick, quantity, salt);
+        const sealed = await sealBid({ auction: drop, bidder: w.account.address, tick, quantity, salt }, s.tlockRound);
+        const { result, request } = await this.publicClient.simulateContract({ address: drop, abi: cloakDropAbi, functionName: "commit", args: [commitment, sealed, !!o.wl, proof], value: deposit, account: w.account });
+        const txHash = await w.writeContract(request);
+        await this.send(txHash);
+        return { id: result, txHash, tick, salt };
+    }
+    /** Read logs from `fromBlock` to now in one call, or in 100k-block pieces where the RPC limits ranges. */
+    async chunked(get, firstOnly = false) {
+        const latest = await this.publicClient.getBlockNumber({ cacheTime: 0 });
+        try {
+            return await get(this.fromBlock, latest);
+        }
+        catch {
+            const out = [];
+            for (let from = this.fromBlock; from <= latest; from += 100000n) {
+                out.push(...(await get(from, from + 99999n > latest ? latest : from + 99999n)));
+                if (firstOnly && out.length)
+                    break;
+            }
+            return out;
+        }
+    }
+    async committedLogs(drop) {
+        return this.chunked((from, to) => this.publicClient.getContractEvents({ address: drop, abi: cloakDropAbi, eventName: "Committed", strict: true, fromBlock: from, toBlock: to }));
+    }
+    /** Deliver one bid now: its NFTs to the bidder and the rest of its deposit back (anyone can, it's always the bidder's). */
+    async claim(drop, id) {
+        const { request } = await this.publicClient.simulateContract({ address: drop, abi: cloakDropAbi, functionName: "claim", args: [id], account: this.wallet().account });
+        const h = await this.wallet().writeContract(request);
+        await this.send(h);
+        return h;
+    }
+    /** A refund the drop couldn't send (a wallet that refuses HYPE) waits here for its bidder. */
+    async refundOwed(drop, bidder) {
+        return this.publicClient.readContract({ address: drop, abi: cloakDropAbi, functionName: "refundOwed", args: [bidder] });
+    }
+    async withdrawRefund(drop, to) {
+        const { request } = await this.publicClient.simulateContract({ address: drop, abi: cloakDropAbi, functionName: "withdrawRefund", args: [to], account: this.wallet().account });
+        const h = await this.wallet().writeContract(request);
+        await this.send(h);
+        return h;
+    }
+    /** Every bid on a drop (or one bidder's), with what it won once settled. */
+    async bids(drop, bidder) {
+        const [s, n] = await Promise.all([this.get(drop), this.publicClient.readContract({ address: drop, abi: cloakDropAbi, functionName: "bidsCount" })]);
+        if (!n)
+            return [];
+        const ids = Array.from({ length: Number(n) }, (_, i) => BigInt(i));
+        const raw = (await this.reads(ids.map((id) => ({ address: drop, abi: cloakDropAbi, functionName: "getBid", args: [id] }))));
+        const ready = s.settled && (s.tieSupply === 0 || s.phase === "settled");
+        const alloc = ready ? await this.reads(ids.map((id) => ({ address: drop, abi: cloakDropAbi, functionName: "allocationOf", args: [id] }))) : [];
+        return raw
+            .map((b, i) => {
+            const a = alloc[i];
+            return { id: ids[i], bidder: b.bidder, wl: b.wl, revealed: b.revealed, claimed: b.claimed, tick: b.tick, price: CloakDrops.priceAt(s, b.tick), quantity: b.quantity, deposit: b.deposit, nfts: a ? Number(a[0]) : 0, paid: a?.[1] ?? 0n, refund: a?.[2] ?? 0n };
+        })
+            .filter((b) => !bidder || b.bidder.toLowerCase() === bidder.toLowerCase());
+    }
+    // ── what the keeper (or anyone) runs ──
+    /** Open every sealed bid whose drand round has passed. Garbage ciphertexts are skipped (and penalised at claim). */
+    async revealAll(drop, opts = {}) {
+        const log = opts.log ?? (() => { });
+        const logs = await this.committedLogs(drop);
+        const reveals = [];
+        for (const l of logs) {
+            const b = await this.publicClient.readContract({ address: drop, abi: cloakDropAbi, functionName: "getBid", args: [l.args.id] });
+            if (b.revealed)
+                continue;
+            try {
+                const p = await unsealBid(l.args.sealedBid);
+                if (p.auction.toLowerCase() !== drop.toLowerCase())
+                    throw new Error("sealed for another drop");
+                if (commitmentOf(drop, b.bidder, p.tick, p.quantity, p.salt) !== b.commitment)
+                    throw new Error("ciphertext does not match commitment");
+                reveals.push({ id: l.args.id, tick: p.tick, quantity: p.quantity, salt: p.salt });
+            }
+            catch (e) {
+                log(`bid #${l.args.id}: cannot unseal (${e.message})`);
+            }
+        }
+        const size = opts.batchSize ?? 40;
+        for (let i = 0; i < reveals.length; i += size) {
+            await this.send(await this.wallet().writeContract({ address: drop, abi: cloakDropAbi, functionName: "revealBatch", args: [reveals.slice(i, i + size)] }));
+            log(`revealed ${Math.min(i + size, reveals.length)}/${reveals.length}`);
+        }
+        return { revealed: reveals.length };
+    }
+    /** Settle, then number the tied bids (if any) so claims can start. */
+    async settle(drop, opts = {}) {
+        const c = { address: drop, abi: cloakDropAbi };
+        const txs = [];
+        if (!(await this.publicClient.readContract({ ...c, functionName: "settled" }))) {
+            const h = await this.wallet().writeContract({ ...c, functionName: "settle" });
+            await this.send(h);
+            txs.push(h);
+        }
+        while ((await this.get(drop)).phase === "numbering") {
+            const h = await this.wallet().writeContract({ ...c, functionName: "numberTies", args: [BigInt(opts.tieBatch ?? 400)] });
+            await this.send(h);
+            txs.push(h);
+        }
+        return txs;
+    }
+    /** Deliver every unclaimed bid (NFTs and refunds always go to the bidder, never the caller). */
+    async claimAll(drop, opts = {}) {
+        const ids = (await this.bids(drop)).filter((b) => !b.claimed).map((b) => b.id);
+        const size = opts.batchSize ?? 25;
+        for (let i = 0; i < ids.length; i += size)
+            await this.send(await this.wallet().writeContract({ address: drop, abi: cloakDropAbi, functionName: "claimBatch", args: [ids.slice(i, i + size)] }));
+        return { claimed: ids.length };
+    }
+    /** The bidder takes its NFTs to another address (a fresh wallet, say); the refund still goes to the bidder. */
+    async claimTo(drop, id, to) {
+        const { request } = await this.publicClient.simulateContract({ address: drop, abi: cloakDropAbi, functionName: "claimTo", args: [id, to], account: this.wallet().account });
+        const h = await this.wallet().writeContract(request);
+        await this.send(h);
+        return h;
+    }
+    /** Pay out the creator's proceeds and the protocol fee (anyone can call; the destinations are fixed). */
+    async payOut(drop) {
+        const c = { address: drop, abi: cloakDropAbi };
+        const [owed, fees] = await Promise.all([this.publicClient.readContract({ ...c, functionName: "creatorOwed" }), this.publicClient.readContract({ ...c, functionName: "feesOwed" })]);
+        const txs = [];
+        if (owed > 0n) {
+            const h = await this.wallet().writeContract({ ...c, functionName: "withdrawProceeds" });
+            await this.send(h);
+            txs.push(h);
+        }
+        if (fees > 0n) {
+            try {
+                await this.publicClient.simulateContract({ ...c, functionName: "collectFees", account: this.wallet().account });
+                const h = await this.wallet().writeContract({ ...c, functionName: "collectFees" });
+                await this.send(h);
+                txs.push(h);
+            }
+            catch { }
+        }
+        return txs;
+    }
+    /** The creator mints what nobody bought (or all of it, if the drop failed). */
+    async mintUnsold(drop, to, quantity) {
+        const h = await this.wallet().writeContract({ address: drop, abi: cloakDropAbi, functionName: "mintUnsold", args: [to, quantity] });
+        await this.send(h);
+        return h;
+    }
+}

package/dist/index.d.ts

@@ -4,4 +4,6 @@ export * from "./deployments.js";
 export * from "./registry.js";
 export * from "./seal.js";
 export * from "./cloak.js";
+export * from "./drops.js";
 export * from "./private/index.js";
+export * from "./spots.js";

package/dist/index.js

@@ -4,4 +4,6 @@ export * from "./deployments.js";
 export * from "./registry.js";
 export * from "./seal.js";
 export * from "./cloak.js";
+export * from "./drops.js";
 export * from "./private/index.js";
+export * from "./spots.js";

package/dist/private/shared.d.ts

@@ -103,7 +103,10 @@ export declare class SharedVaultClient {
     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. */
+    /**
+     * Expected output of a swap through `token`'s market, before slippage. The market prices it at its own current fee:
+     * 0.3% on a Uniswap V2 pool, and on a v4 pool whatever the hook charges now (higher just after listing, then 0.3%).
+     */
     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>;

package/dist/private/shared.js

@@ -260,7 +260,10 @@ export class SharedVaultClient {
         }
         throw new Error("too many notes to combine");
     }
-    /** Expected output of a swap through `token`'s Uniswap market (0.3% fee), before slippage. */
+    /**
+     * Expected output of a swap through `token`'s market, before slippage. The market prices it at its own current fee:
+     * 0.3% on a Uniswap V2 pool, and on a v4 pool whatever the hook charges now (higher just after listing, then 0.3%).
+     */
     async quoteSwap(token, side, amountIn) {
         const m = this.info(token).market;
         const [rH, rT] = await Promise.all([
@@ -268,8 +271,7 @@ export class SharedVaultClient {
             this.pub.readContract({ address: m, abi: cloakPairAbi, functionName: "reserveToken" }),
         ]);
         const [rIn, rOut] = side === "buy" ? [rH, rT] : [rT, rH];
-        const a = amountIn * 997n;
-        return (a * rOut) / (rIn * 1000n + a);
+        return this.pub.readContract({ address: m, abi: cloakPairAbi, functionName: "getAmountOut", args: [amountIn, rIn, rOut] });
     }
     // ───────────── public → private ─────────────
     /** Wallet tokens → a private note on a one-time key. This step is public (the wallet deposits). */

package/dist/spots.d.ts

@@ -0,0 +1,65 @@
+/**
+ * WL spot sales: a partner collection gives out whitelist spots and they're sold as a Cloak drop.
+ *
+ * The drop's supply is the number of spots and its sealed auction picks the winners (the floor, ties and refunds work
+ * as in any drop). CloakSpotBook marks the drop as a spot sale. Once it settles, each winning bid names the wallets to
+ * whitelist, one per spot it won, and can change them until the deadline. The book holds the list the partner uses.
+ * Each winner also gets the drop's NFT as a receipt.
+ */
+import { type Address, type Hex } from "viem";
+import { CloakDrops, type CreateDropOptions, type DropBid } from "./drops.js";
+/** How long winners have to name their wallets, by default, once bids are opened. */
+export declare const SPOT_DEFAULT_WALLET_DAYS = 3;
+export declare const SPOT_MAX_WALLET_DAYS = 90;
+export interface SpotSale {
+    drop: Address;
+    partner: string;
+    /** Unix seconds: winners name or change wallets until then. */
+    deadline: number;
+}
+/** One winning bid and the wallets it named (none yet: `wallets` is empty). */
+export interface SpotWinner {
+    bidId: bigint;
+    bidder: Address;
+    spots: number;
+    wallets: Address[];
+}
+export type CreateSpotSaleOptions = Omit<CreateDropOptions, "gtd" | "baseURI" | "spots"> & {
+    /** The partner collection giving the spots. */
+    partner: string;
+    /** Days after the reveal window that winners have to name wallets (default 3). */
+    walletDays?: number;
+    baseURI?: string;
+};
+export declare class CloakSpots {
+    readonly drops: CloakDrops;
+    readonly book: Address;
+    constructor(drops: CloakDrops, book: Address);
+    private get pc();
+    private send;
+    /**
+     * Create a drop that sells `supply` WL spots for `partner`, then mark it as a spot sale. Two transactions; if the
+     * second fails, `open(drop, …)` finishes the job.
+     */
+    create(o: CreateSpotSaleOptions): Promise<{
+        drop: Address;
+        txHash: Hex;
+        openTx: Hex;
+        deadline: number;
+    }>;
+    /** Mark an existing drop (the caller's, not settled yet) as a WL spot sale. */
+    open(drop: Address, partner: string, deadline: number): Promise<Hex>;
+    /** The sale on a drop, or null if the drop isn't a WL spot sale. */
+    sale(drop: Address): Promise<SpotSale | null>;
+    /** Every drop marked as a spot sale, oldest first. */
+    sales(): Promise<Address[]>;
+    /** Every winning bid (once the drop is settled) with the wallets it has named so far. */
+    winners(drop: Address, bids?: DropBid[]): Promise<SpotWinner[]>;
+    /** Name the wallets to whitelist for a winning bid of the connected wallet: one per spot. Replaces earlier ones. */
+    setWallets(drop: Address, bidId: bigint, wallets: string[]): Promise<Hex>;
+    /**
+     * The whitelist as CSV, one row per spot: the wallet to whitelist (or blank if the winner hasn't named one), the
+     * bid and the bidder. A partner whitelists the `wallet` column.
+     */
+    static csv(winners: SpotWinner[]): string;
+}

package/dist/spots.js

@@ -0,0 +1,109 @@
+/**
+ * WL spot sales: a partner collection gives out whitelist spots and they're sold as a Cloak drop.
+ *
+ * The drop's supply is the number of spots and its sealed auction picks the winners (the floor, ties and refunds work
+ * as in any drop). CloakSpotBook marks the drop as a spot sale. Once it settles, each winning bid names the wallets to
+ * whitelist, one per spot it won, and can change them until the deadline. The book holds the list the partner uses.
+ * Each winner also gets the drop's NFT as a receipt.
+ */
+import { getAddress, isAddress } from "viem";
+import { cloakSpotBookAbi } from "./abis.js";
+/** How long winners have to name their wallets, by default, once bids are opened. */
+export const SPOT_DEFAULT_WALLET_DAYS = 3;
+export const SPOT_MAX_WALLET_DAYS = 90;
+export class CloakSpots {
+    drops;
+    book;
+    constructor(drops, book) {
+        this.drops = drops;
+        this.book = book;
+    }
+    get pc() {
+        return this.drops.publicClient;
+    }
+    async send(hash) {
+        const r = await this.pc.waitForTransactionReceipt({ hash });
+        if (r.status !== "success")
+            throw new Error(`transaction reverted: ${hash}`);
+        return r;
+    }
+    /**
+     * Create a drop that sells `supply` WL spots for `partner`, then mark it as a spot sale. Two transactions; if the
+     * second fails, `open(drop, …)` finishes the job.
+     */
+    async create(o) {
+        const partner = o.partner.trim();
+        if (!partner || partner.length > 200)
+            throw new Error("Name the partner collection (up to 200 characters).");
+        const days = o.walletDays ?? SPOT_DEFAULT_WALLET_DAYS;
+        if (!(days > 0 && days <= SPOT_MAX_WALLET_DAYS))
+            throw new Error(`Winners get 1 to ${SPOT_MAX_WALLET_DAYS} days to name wallets.`);
+        const { drop, txHash } = await this.drops.create({ ...o, baseURI: o.baseURI ?? "", maxPerBid: o.maxPerBid ?? 1, spots: { partner } });
+        const s = await this.drops.get(drop);
+        const deadline = s.revealEnd + Math.round(days * 86400);
+        const openTx = await this.open(drop, partner, deadline);
+        return { drop, txHash, openTx, deadline };
+    }
+    /** Mark an existing drop (the caller's, not settled yet) as a WL spot sale. */
+    async open(drop, partner, deadline) {
+        const w = this.drops.walletClient;
+        if (!w)
+            throw new Error("CloakSpots: a walletClient is required for this call");
+        const all = await this.drops.list();
+        const index = all.findIndex((a) => a.toLowerCase() === drop.toLowerCase());
+        if (index < 0)
+            throw new Error("That isn't a Cloak drop.");
+        const { request } = await this.pc.simulateContract({ address: this.book, abi: cloakSpotBookAbi, functionName: "open", args: [BigInt(index), partner.trim(), BigInt(deadline)], account: w.account });
+        const h = await w.writeContract(request);
+        await this.send(h);
+        return h;
+    }
+    /** The sale on a drop, or null if the drop isn't a WL spot sale. */
+    async sale(drop) {
+        const s = await this.pc.readContract({ address: this.book, abi: cloakSpotBookAbi, functionName: "sale", args: [drop] });
+        return s.open ? { drop, partner: s.partner, deadline: Number(s.deadline) } : null;
+    }
+    /** Every drop marked as a spot sale, oldest first. */
+    async sales() {
+        const n = Number(await this.pc.readContract({ address: this.book, abi: cloakSpotBookAbi, functionName: "salesCount" }));
+        const out = [];
+        for (let i = 0; i < n; i++)
+            out.push(await this.pc.readContract({ address: this.book, abi: cloakSpotBookAbi, functionName: "sales", args: [BigInt(i)] }));
+        return out;
+    }
+    /** Every winning bid (once the drop is settled) with the wallets it has named so far. */
+    async winners(drop, bids) {
+        const all = bids ?? (await this.drops.bids(drop));
+        const won = all.filter((b) => b.nfts > 0);
+        const [ids, wallets] = await this.pc.readContract({ address: this.book, abi: cloakSpotBookAbi, functionName: "list", args: [drop] });
+        return won.map((b) => ({ bidId: b.id, bidder: b.bidder, spots: b.nfts, wallets: wallets.filter((_, i) => ids[i] === b.id) }));
+    }
+    /** Name the wallets to whitelist for a winning bid of the connected wallet: one per spot. Replaces earlier ones. */
+    async setWallets(drop, bidId, wallets) {
+        const w = this.drops.walletClient;
+        if (!w)
+            throw new Error("CloakSpots: a walletClient is required for this call");
+        const list = wallets.map((a) => a.trim());
+        const bad = list.find((a) => !isAddress(a));
+        if (bad !== undefined)
+            throw new Error(`${bad || "An empty line"} isn't a wallet address.`);
+        const clean = list.map((a) => getAddress(a));
+        if (new Set(clean.map((a) => a.toLowerCase())).size !== clean.length)
+            throw new Error("Each spot needs a different wallet.");
+        const { request } = await this.pc.simulateContract({ address: this.book, abi: cloakSpotBookAbi, functionName: "setWallets", args: [drop, bidId, clean], account: w.account });
+        const h = await w.writeContract(request);
+        await this.send(h);
+        return h;
+    }
+    /**
+     * The whitelist as CSV, one row per spot: the wallet to whitelist (or blank if the winner hasn't named one), the
+     * bid and the bidder. A partner whitelists the `wallet` column.
+     */
+    static csv(winners) {
+        const rows = ["wallet,bid,bidder,status"];
+        for (const w of winners)
+            for (let i = 0; i < w.spots; i++)
+                rows.push(`${w.wallets[i] ?? ""},${w.bidId},${w.bidder},${w.wallets[i] ? "named" : "not named yet"}`);
+        return rows.join("\n") + "\n";
+    }
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@cloakely/sdk",
-  "version": "0.8.1",
-  "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.",
+  "version": "0.8.3",
+  "description": "Cloak on Elysium: sealed-bid token launches, sealed NFT drops and WL spot sales, and private trading (shielded balances, private swaps, batch auctions, private sends) with on-device zero-knowledge proofs.",
   "keywords": [
     "cloak",
     "elysium",