@cloakely/sdk 0.8.0 → 0.8.2

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/client.d.ts

@@ -104,6 +104,8 @@ export declare class CloakPrivate {
     private state;
     /** Pull new leaves from the pool's events, trial-decrypt them, and refresh spent flags. */
     sync(pool: Address): Promise<OwnedNote[]>;
+    /** Every note this account has received in `pool`, spent ones included (each with `spent` and its nullifier). */
+    history(pool: Address): Promise<OwnedNote[]>;
     balance(pool: Address): Promise<bigint>;
     /** The most a single relayed call of this kind can move from `pool`: the balance minus the relayer's fee. */
     maxSpendable(pool: Address, kind?: RelayKind): Promise<bigint>;

package/dist/private/client.js

@@ -249,6 +249,11 @@ export class CloakPrivate {
         s.notes.forEach((x, i) => (x.spent = Boolean(flags[i])));
         return s.notes.filter((x) => !x.spent);
     }
+    /** Every note this account has received in `pool`, spent ones included (each with `spent` and its nullifier). */
+    async history(pool) {
+        await this.sync(pool);
+        return [...this.state(pool).notes];
+    }
     async balance(pool) {
         return (await this.sync(pool)).reduce((a, x) => a + x.amount, 0n);
     }

package/dist/private/links.d.ts

@@ -22,6 +22,18 @@ export declare const newLinkSecret: () => Uint8Array;
 export declare function linkKeys(secret: Uint8Array, passcode?: string): Promise<CloakKeys>;
 /** The cloak: address a link's money is sent to. */
 export declare function linkAddress(keys: CloakKeys): Promise<string>;
+/** The 8-hex-digit check a locked link carries: the first 4 bytes of a hash of the account the passcode opens. */
+export declare function linkCheck(keys: CloakKeys): Promise<string>;
+/** Thrown when a link's check says the passcode is wrong. */
+export declare class WrongPasscodeError extends Error {
+    constructor(riddle: boolean);
+}
+/**
+ * Opens a link's account. A locked link with a check tries the code (and the ways a phone may have mangled it) and
+ * throws WrongPasscodeError if none matches, without touching the network. A link without a check (made before
+ * checks existed) opens with the code as typed; an empty account is then all a wrong code looks like.
+ */
+export declare function openLinkKeys(l: ClaimLink, passcode?: string): Promise<CloakKeys>;
 export interface ClaimLink {
     secret: Uint8Array;
     /** Block the link was funded in. Shown to the claimer; scanning still starts at the vaults' first block, because
@@ -40,7 +52,15 @@ export interface ClaimLink {
     hint?: string;
     /** Split into this many equal shares: each person who opens the link claims one (a red envelope). */
     shares?: number;
+    /** A short check of the account a passcode opens, so a wrong passcode is caught on the device, before any
+     *  network call. It tells a guesser nothing a copy of the link didn't already: each guess still costs a full scrypt. */
+    check?: string;
 }
+/**
+ * A claim link: https://cloak.boblabs.tech/claim#c<letters and digits>. Everything after the # is one run of letters
+ * and digits (base 62), because chat apps end a link at characters like "-", "_", "." or "%" (WhatsApp and Telegram
+ * both cut links that way) and a cut link loses the money's key.
+ */
 export declare function buildClaimLink(l: ClaimLink, origin?: string): string;
 /** Reads a claim link (the whole URL or just its fragment). Throws on anything that isn't one. */
 export declare function parseClaimLink(link: string): ClaimLink;

package/dist/private/links.js

@@ -21,7 +21,7 @@
  */
 import { scryptAsync } from "@noble/hashes/scrypt";
 import { randomBytes } from "@noble/hashes/utils";
-import { concat, isAddress, keccak256, toBytes } from "viem";
+import { concat, isAddress, keccak256, toBytes, toHex } from "viem";
 import { CloakKeys, formatCloakAddress, parseCloakAddress } from "./crypto.js";
 export const LINK_ORIGIN = "https://cloak.boblabs.tech";
 export const LINK_MESSAGE_MAX = 140;
@@ -64,9 +64,46 @@ export async function linkKeys(secret, passcode) {
 export async function linkAddress(keys) {
     return formatCloakAddress((await keys.main()).pubKey, keys.encPub);
 }
-export function buildClaimLink(l, origin = LINK_ORIGIN) {
+/** The 8-hex-digit check a locked link carries: the first 4 bytes of a hash of the account the passcode opens. */
+export async function linkCheck(keys) {
+    return keccak256(concat([toBytes("cloak-link-check-v1"), toBytes(await linkAddress(keys))])).slice(2, 10);
+}
+/** Thrown when a link's check says the passcode is wrong. */
+export class WrongPasscodeError extends Error {
+    constructor(riddle) {
+        super(riddle ? "That's not the answer. Check the spelling and try again." : "That's not the passcode. Check it with the sender and try again.");
+        this.name = "WrongPasscodeError";
+    }
+}
+/** Ways a phone may have typed the same code: curly quotes and long dashes from autocorrect, a trailing full stop. */
+function passcodeVariants(code) {
+    const base = normalizePasscode(code);
+    const straight = base.replace(/[\u2018\u2019\u201b\u2032]/g, "'").replace(/[\u201c\u201d\u2033]/g, '"').replace(/[\u2013\u2014\u2212]/g, "-");
+    return [...new Set([base, straight, straight.replace(/[.!?]+$/, "")])].filter(Boolean);
+}
+/**
+ * Opens a link's account. A locked link with a check tries the code (and the ways a phone may have mangled it) and
+ * throws WrongPasscodeError if none matches, without touching the network. A link without a check (made before
+ * checks existed) opens with the code as typed; an empty account is then all a wrong code looks like.
+ */
+export async function openLinkKeys(l, passcode) {
+    if (!l.locked)
+        return linkKeys(l.secret);
+    if (!passcode || !normalizePasscode(passcode))
+        throw new Error(l.hint ? "Type the answer." : "Enter the passcode.");
+    if (!l.check)
+        return linkKeys(l.secret, passcode);
+    for (const v of passcodeVariants(passcode)) {
+        const k = await linkKeys(l.secret, v);
+        if ((await linkCheck(k)) === l.check)
+            return k;
+    }
+    throw new WrongPasscodeError(!!l.hint);
+}
+/** The fields of a claim link as query parameters (the secret in hex). */
+function claimParams(l) {
     const p = new URLSearchParams();
-    p.set("k", b64url(l.secret));
+    p.set("k", toHex(l.secret).slice(2));
     p.set("b", l.block.toString());
     if (l.token)
         p.set("t", l.token);
@@ -85,24 +122,69 @@ export function buildClaimLink(l, origin = LINK_ORIGIN) {
         p.set("q", q);
     if (l.shares && l.shares > 1)
         p.set("n", String(Math.min(Math.floor(l.shares), LINK_SHARES_MAX)));
-    return `${origin.replace(/\/+$/, "")}/claim#${p.toString()}`;
+    if (l.check && /^[0-9a-f]{8}$/.test(l.check))
+        p.set("c", l.check);
+    return p;
+}
+/**
+ * A claim link: https://cloak.boblabs.tech/claim#c<letters and digits>. Everything after the # is one run of letters
+ * and digits (base 62), because chat apps end a link at characters like "-", "_", "." or "%" (WhatsApp and Telegram
+ * both cut links that way) and a cut link loses the money's key.
+ */
+export function buildClaimLink(l, origin = LINK_ORIGIN) {
+    return `${origin.replace(/\/+$/, "")}/claim#c${toBase62(new TextEncoder().encode(claimParams(l).toString()))}`;
+}
+const B62 = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz";
+function toBase62(bytes) {
+    // a leading 1 byte keeps leading zero bytes; the payload is a few hundred bytes, so plain bigint math is fine
+    let n = BigInt(toHex(concat([new Uint8Array([1]), bytes])));
+    let out = "";
+    while (n > 0n) {
+        out = B62[Number(n % 62n)] + out;
+        n /= 62n;
+    }
+    return out;
+}
+function fromBase62(s) {
+    let n = 0n;
+    for (const ch of s) {
+        const v = B62.indexOf(ch);
+        if (v < 0)
+            throw new Error("bad link");
+        n = n * 62n + BigInt(v);
+    }
+    let hex = n.toString(16);
+    if (hex.length % 2)
+        hex = "0" + hex;
+    const b = toBytes(`0x${hex}`);
+    if (b[0] !== 1)
+        throw new Error("bad link");
+    return b.slice(1);
 }
 /** Reads a claim link (the whole URL or just its fragment). Throws on anything that isn't one. */
 export function parseClaimLink(link) {
-    const frag = link.includes("#") ? link.slice(link.indexOf("#") + 1) : link;
+    let frag = (link.includes("#") ? link.slice(link.indexOf("#") + 1) : link).trim();
+    if (/^c[0-9A-Za-z]+$/.test(frag)) {
+        try {
+            frag = new TextDecoder("utf-8", { fatal: true }).decode(fromBase62(frag.slice(1)));
+        }
+        catch {
+            throw new Error("This claim link is cut short or damaged. Ask the sender to copy the whole link again.");
+        }
+    }
     const p = new URLSearchParams(frag);
     const k = p.get("k");
     if (!k)
         throw new Error("This isn't a Cloak claim link.");
     let secret;
     try {
-        secret = unb64url(k);
+        secret = /^[0-9a-fA-F]{64}$/.test(k) ? toBytes(`0x${k}`) : unb64url(k);
     }
     catch {
         throw new Error("This claim link is damaged. Ask the sender to copy it again.");
     }
     if (secret.length !== 32)
-        throw new Error("This claim link is cut short. Ask the sender to copy it again.");
+        throw new Error("This claim link is cut short. Ask the sender to copy the whole link again.");
     const b = p.get("b") ?? "0";
     const t = p.get("t");
     const a = p.get("a");
@@ -116,6 +198,7 @@ export function parseClaimLink(link) {
         locked: p.get("p") === "1",
         hint: cleanLinkText(p.get("q"), LINK_HINT_MAX) || undefined,
         shares: /^\d{1,2}$/.test(p.get("n") ?? "") && Number(p.get("n")) > 1 ? Math.min(Number(p.get("n")), LINK_SHARES_MAX) : undefined,
+        check: /^[0-9a-f]{8}$/.test(p.get("c") ?? "") ? p.get("c") : undefined,
     };
 }
 /** Checks an amount and returns it as a plain decimal, or throws a plain-language error. Empty means "payer chooses". */