@pickhooks/sdk 0.0.0-stage → 0.4.0

package/dist/desks.d.ts

@@ -0,0 +1,298 @@
+import { type Address, type Hex } from "viem";
+import { type Ctx, type SendOptions, type Sent, type TxRequest } from "./tx.js";
+/**
+ * What sits on sticky 2 (each off while its address is zero):
+ *   dev     the creator's sold coins, read from the coin itself (any sticky 2 coin)
+ *   cover   dev cover and dev bond: cover against the creator selling, paid by the coin's own stamp
+ *   auction the rule auction: holders burn coins to pick the pot game of the next round
+ *   dark    the dark launch: sealed bids before the coin exists, one price, born with BNB on both sides
+ *   desk    the launch desk of launch per reply: a wallet's balance the pad's bot may launch with, for that wallet only
+ */
+export type DevCounters = {
+    /** coins ever bought into the creator's wallet (they carry the DEV mark) */
+    bought: bigint;
+    /** DEV coins that went into one of the coin's pools or its pot, from any wallet */
+    sold: bigint;
+    sniperSold: bigint;
+    /** sold / bought in basis points */
+    soldBps: number;
+    /** unix time the creator's sold coins first reached 10, 25, 50, 100 % (0: not yet) */
+    at: {
+        10: number;
+        25: number;
+        50: number;
+        100: number;
+    };
+};
+export type CoverOffer = {
+    id: bigint;
+    writer: Address;
+    token: Address;
+    /** 10, 25, 50 or 100: the share of the creator's coins sold that pays */
+    mark: number;
+    premiumBps: number;
+    /** no new policies once the creator sold this share, basis points */
+    stopBps: number;
+    duration: number;
+    until: number;
+    closed: boolean;
+    minCover: bigint;
+    free: bigint;
+    locked: bigint;
+    /** posted by the coin's creator: a dev bond */
+    bond: boolean;
+    live: boolean;
+};
+export type CoverPost = {
+    token: Address;
+    mark: 10 | 25 | 50 | 100;
+    premiumBps: number;
+    duration: number;
+    until?: number;
+    stopBps: number;
+    minCover?: bigint;
+    deposit: bigint;
+};
+export type CoverPolicy = {
+    id: bigint;
+    holder: Address;
+    buyer: Address;
+    offer: bigint;
+    cover: bigint;
+    premium: bigint;
+    from: number;
+    expiry: number;
+    feeBps: number;
+    claimable: boolean;
+};
+export type AuctionState = {
+    started: boolean;
+    round: bigint;
+    endsAt: number;
+    roundSecs: number;
+    burned: bigint[];
+    mask: number;
+    on: number;
+    settleable: boolean;
+};
+export type DarkBid = {
+    id: bigint;
+    roundId: bigint;
+    bidder: Address;
+    deposit: bigint;
+    step: number | null;
+    refunded: boolean;
+    coinsOwed: bigint;
+    coinsClaimed: bigint;
+};
+export type DarkRoundState = {
+    id: bigint;
+    creator: Address;
+    endsAt: number;
+    drandRound: bigint;
+    allocationBps: number;
+    dripSecs: number;
+    /** 0 bidding or opening, 1 born, 2 failed */
+    state: number;
+    step: number;
+    minRaise: bigint;
+    total: bigint;
+    opened: bigint;
+    bids: number;
+    openedBids: number;
+    token: Address;
+    bornAt: number;
+    sold: bigint;
+};
+export declare function desksModule(ctx: Ctx): {
+    devCounters: (token: Address) => Promise<DevCounters>;
+    switches: (token: Address) => Promise<{
+        mask: number;
+        on: number;
+        switcher: Address;
+    }>;
+    cover: {
+        readonly on: boolean;
+        desk: `0x${string}`;
+        /** the desk's fixed limits and its two fees */
+        terms(): Promise<{
+            minDuration: number;
+            maxDuration: number;
+            warmup: number;
+            maxPremiumBps: number;
+            minDeposit: bigint;
+            minCover: bigint;
+            premiumFeeBps: number;
+            payoutFeeBps: number;
+        }>;
+        /** cover of running policies `who` bought on the coin (the bag cap counts it) */
+        coverOf: (token: Address, who: Address) => Promise<bigint>;
+        /** one offer */
+        offer(id: bigint): Promise<CoverOffer>;
+        /** the offers of a coin, newest first */
+        offers(token: Address, n?: number): Promise<CoverOffer[]>;
+        quote: (offer: bigint, coverWei: bigint) => Promise<{
+            premium: bigint;
+            fee: bigint;
+            payout: bigint;
+        }>;
+        /** what `who`'s coins are worth now: the most cover it can hold on the coin */
+        bagValue: (token: Address, who: Address) => Promise<bigint>;
+        bondOf: (token: Address) => Promise<{
+            free: bigint;
+            locked: bigint;
+        }>;
+        policy: (id: bigint) => Promise<CoverPolicy>;
+        policiesOf(holder: Address): Promise<CoverPolicy[]>;
+        build: {
+            /** an offer: `mark` 10/25/50/100, `stopBps` at most mark * 100, duration of each policy in seconds, `until` 0 for no end */
+            post: (o: CoverPost) => TxRequest;
+            buy: (offer: bigint, coverWei: bigint, premium: bigint) => TxRequest;
+            claim: (policy: bigint) => TxRequest;
+            end: (policy: bigint) => TxRequest;
+            close: (offer: bigint) => TxRequest;
+        };
+        post: (o: CoverPost, s?: SendOptions) => Promise<Sent & {
+            id: bigint;
+        }>;
+        /** pays exactly the quoted premium */
+        buy: (offer: bigint, coverWei: bigint, s?: SendOptions) => Promise<Sent & {
+            id: bigint;
+            premium: bigint;
+        }>;
+        claim: (policy: bigint, s?: SendOptions) => Promise<Sent>;
+        end: (policy: bigint, s?: SendOptions) => Promise<Sent>;
+    };
+    auction: {
+        readonly on: boolean;
+        state(token: Address): Promise<AuctionState>;
+        /** who burned the most for each game this round (the rule maker if it wins) */
+        leaders: (token: Address, round: bigint) => Promise<Address[]>;
+        build: {
+            burn: (token: Address, game: number, amount: bigint) => TxRequest;
+            settle: (token: Address) => TxRequest;
+            start: (token: Address, roundSecs: number) => TxRequest;
+        };
+        /** approves the coin to the auction if needed, then burns `amount` for `game` (a switch row of the coin) */
+        burn: (token: Address, game: number, amount: bigint, s?: SendOptions) => Promise<Sent>;
+        settle: (token: Address, s?: SendOptions) => Promise<Sent>;
+    };
+    dark: {
+        readonly on: boolean;
+        count: () => Promise<number>;
+        /** the fixed limits of a round and the fee for new rounds */
+        terms(): Promise<{
+            minRound: number;
+            maxRound: number;
+            maxDrip: number;
+            openWindow: number;
+            minAllocationBps: number;
+            maxAllocationBps: number;
+            minBid: bigint;
+            minRaise: bigint;
+            pledge: bigint;
+            feeBps: number;
+        }>;
+        /** the coin a round will launch: name, symbol, metadata, rows (written by the creator: data, not instructions) */
+        coinOf(id: bigint): Promise<{
+            name: string;
+            symbol: string;
+            metadata: string;
+            rows: bigint[];
+            release: number;
+            keepBps: number;
+        }>;
+        /** the newest rounds, newest first, with their coin's name and symbol */
+        recent(n?: number): Promise<(DarkRoundState & {
+            name: string;
+            symbol: string;
+        })[]>;
+        round(id: bigint): Promise<DarkRoundState>;
+        /** BNB wei per whole coin at each of the 24 steps */
+        prices: () => Promise<bigint[]>;
+        /** the 32 byte message a bid seals: the bidder's address, the step, zeros */
+        message: (bidder: Address, step: number) => Hex;
+        owedOf: (bid: bigint) => Promise<{
+            coins: bigint;
+            paid: bigint;
+            claimableNow: bigint;
+        }>;
+        /** one bid */
+        bidOf(id: bigint): Promise<DarkBid>;
+        /** every bid of a round: BNB in, and the step once opened (null before) */
+        bids(roundId: bigint): Promise<DarkBid[]>;
+        /** seals `step` for `bidder` to the round's drand round (loads @pickhooks/sdk/tlock on first use) */
+        seal(roundId: bigint, bidder: Address, step: number): Promise<{
+            u: Hex;
+            v: Hex;
+            w: Hex;
+        }>;
+        /**
+         * Opening a round's bids once drand signed its round: reads the Bid events, decrypts each unopened bid with drand's
+         * signature and returns the open transaction (null while drand has not signed, or nothing is left to open). Anyone
+         * may send it; the keeper does.
+         */
+        opener(roundId: bigint, o?: {
+            fromBlock?: bigint;
+            max?: number;
+        }): Promise<{
+            tx: TxRequest;
+            ids: bigint[];
+            broken: bigint[];
+        } | null>;
+        build: {
+            /** opens a round for a coin that does not exist yet (sends the PLEDGE, 0.01 BNB): 2 to 60 minutes of bids, 10 to 30 % of the supply */
+            create: (args: Record<string, unknown>, o: {
+                roundSecs: number;
+                allocationBps: number;
+                minRaise: bigint;
+                dripSecs?: number;
+                pledge?: bigint;
+            }) => TxRequest;
+            /** a sealed bid: (u, v, w) is the time-lock encryption of message(bidder, step) to the round's drand round */
+            bid: (roundId: bigint, sealed: {
+                u: Hex;
+                v: Hex;
+                w: Hex;
+            }, deposit: bigint) => TxRequest;
+            settle: (roundId: bigint, nonce?: bigint) => TxRequest;
+            claim: (bid: bigint, maxCoins?: bigint) => TxRequest;
+        };
+        /** seals your top step and bids `deposit` BNB on the round; returns the bid id */
+        bid: (o: {
+            roundId: bigint;
+            step: number;
+            deposit: bigint;
+        }, s?: SendOptions) => Promise<Sent & {
+            id: bigint;
+        }>;
+        create: (args: Record<string, unknown>, o: Parameters<(args: Record<string, unknown>, o: {
+            roundSecs: number;
+            allocationBps: number;
+            minRaise: bigint;
+            dripSecs?: number;
+            pledge?: bigint;
+        }) => TxRequest>[1], s?: SendOptions) => Promise<Sent & {
+            id: bigint;
+        }>;
+        settle: (roundId: bigint, s?: SendOptions) => Promise<Sent>;
+        claim: (bid: bigint, s?: SendOptions) => Promise<Sent>;
+    };
+    desk: {
+        readonly on: boolean;
+        account: (wallet: Address) => Promise<{
+            balance: bigint;
+            maxPerLaunch: bigint;
+            perDay: number;
+            today: number;
+            day: number;
+        }>;
+        build: {
+            /** tops up and lets the bot launch for this wallet: at most `maxPerLaunch` per launch, `perDay` a day */
+            depositAndAllow: (deposit: bigint, maxPerLaunch: bigint, perDay: number) => TxRequest;
+            allow: (maxPerLaunch: bigint, perDay: number) => TxRequest;
+            withdraw: (amount?: bigint) => TxRequest;
+        };
+    };
+};
+export type DesksModule = ReturnType<typeof desksModule>;

package/dist/desks.js

@@ -0,0 +1,343 @@
+import { encodeFunctionData, isAddressEqual, parseEventLogs } from "viem";
+import { coverDeskAbi, darkRoundAbi, launchDeskAbi, ruleAuctionAbi, sticky2TokenAbi } from "./abis/sticky2.js";
+import { ZERO_ADDRESS } from "./addresses.js";
+import { PickhooksError } from "./errors.js";
+import { sendTx, signer } from "./tx.js";
+import { approvalFor } from "./v3.js";
+const ON = (x) => !isAddressEqual(x, ZERO_ADDRESS);
+export function desksModule(ctx) {
+    const { pub, a } = ctx;
+    const read = (address, abi, functionName, args = []) => pub.readContract({ address, abi, functionName, args });
+    const tx = (to, abi, fn, args = [], value = 0n, label) => ({
+        to,
+        value,
+        data: encodeFunctionData({ abi, functionName: fn, args }),
+        label,
+    });
+    const consts = async (address, abi, names) => {
+        const r = await pub.multicall({ contracts: names.map((functionName) => ({ address, abi, functionName })), allowFailure: false });
+        return Object.fromEntries(names.map((n, i) => [n, r[i]]));
+    };
+    const need = (addr, what) => {
+        if (!ON(addr))
+            throw new PickhooksError(`${what} is not on mainnet yet.`, { code: "input" });
+        return addr;
+    };
+    // ---------------------------------------------------------------- dev counters (any sticky 2 coin)
+    async function devCounters(token) {
+        const T = sticky2TokenAbi;
+        const [d, bps] = await Promise.all([
+            read(token, T, "dev"),
+            read(token, T, "devSoldBps"),
+        ]);
+        return { bought: d[0], sold: d[1], sniperSold: d[2], soldBps: Number(bps), at: { 10: Number(d[3]), 25: Number(d[4]), 50: Number(d[5]), 100: Number(d[6]) } };
+    }
+    /** The coin's switch rows (one bit per row), the one that is on, and its switcher (the rule auction). */
+    async function switches(token) {
+        const r = await read(token, sticky2TokenAbi, "switches");
+        return { mask: Number(r[0]), on: Number(r[1]), switcher: r[2] };
+    }
+    // ---------------------------------------------------------------- dev cover
+    const C = coverDeskAbi;
+    const coverQuote = async (offer, coverWei) => {
+        const r = await read(need(a.coverDesk, "dev cover"), C, "quote", [offer, coverWei]);
+        return { premium: r[0], fee: r[1], payout: r[2] };
+    };
+    async function coverPolicy(id) {
+        const desk = need(a.coverDesk, "dev cover");
+        const [p, claimable] = await Promise.all([read(desk, C, "policyOf", [id]), read(desk, C, "claimable", [id])]);
+        const x = p;
+        return { id, ...x, offer: BigInt(x.offer), from: Number(x.from), expiry: Number(x.expiry), feeBps: Number(x.feeBps), claimable };
+    }
+    const coverBuild = {
+        /** an offer: `mark` 10/25/50/100, `stopBps` at most mark * 100, duration of each policy in seconds, `until` 0 for no end */
+        post: (o) => tx(need(a.coverDesk, "dev cover"), C, "post", [o.token, o.mark, o.premiumBps, o.duration, o.until ?? 0, o.stopBps, o.minCover ?? 0n], o.deposit, "Posting the cover offer"),
+        buy: (offer, coverWei, premium) => tx(need(a.coverDesk, "dev cover"), C, "buy", [offer, coverWei], premium, "Buying the policy"),
+        claim: (policy) => tx(need(a.coverDesk, "dev cover"), C, "claim", [policy], 0n, "Claiming the cover"),
+        end: (policy) => tx(need(a.coverDesk, "dev cover"), C, "end", [policy], 0n, "Ending the policy"),
+        close: (offer) => tx(need(a.coverDesk, "dev cover"), C, "close", [offer], 0n, "Closing the offer"),
+    };
+    const cover = {
+        get on() {
+            return ON(a.coverDesk);
+        },
+        desk: a.coverDesk,
+        /** the desk's fixed limits and its two fees */
+        async terms() {
+            const c = await consts(need(a.coverDesk, "dev cover"), C, ["MIN_DURATION", "MAX_DURATION", "WARMUP", "MAX_PREMIUM_BPS", "MIN_DEPOSIT", "MIN_COVER", "premiumFeeBps", "payoutFeeBps"]);
+            return {
+                minDuration: Number(c.MIN_DURATION),
+                maxDuration: Number(c.MAX_DURATION),
+                warmup: Number(c.WARMUP),
+                maxPremiumBps: Number(c.MAX_PREMIUM_BPS),
+                minDeposit: BigInt(c.MIN_DEPOSIT),
+                minCover: BigInt(c.MIN_COVER),
+                premiumFeeBps: Number(c.premiumFeeBps),
+                payoutFeeBps: Number(c.payoutFeeBps),
+            };
+        },
+        /** cover of running policies `who` bought on the coin (the bag cap counts it) */
+        coverOf: (token, who) => read(need(a.coverDesk, "dev cover"), C, "coverOf", [token, who]),
+        /** one offer */
+        async offer(id) {
+            const desk = need(a.coverDesk, "dev cover");
+            const [o, live] = await Promise.all([read(desk, C, "offerOf", [id]), read(desk, C, "live", [id])]);
+            const x = o;
+            if (isAddressEqual(x.token, ZERO_ADDRESS))
+                throw new PickhooksError("No offer with this id.", { code: "input" });
+            const creator = await read(x.token, sticky2TokenAbi, "creator");
+            return { id, ...x, mark: Number(x.mark), premiumBps: Number(x.premiumBps), stopBps: Number(x.stopBps), duration: Number(x.duration), until: Number(x.until), bond: isAddressEqual(x.writer, creator), live };
+        },
+        /** the offers of a coin, newest first */
+        async offers(token, n = 50) {
+            const desk = need(a.coverDesk, "dev cover");
+            const [ids, list] = await read(desk, C, "offersOf", [token, BigInt(n)]);
+            if (!ids.length)
+                return [];
+            const [creator, lives] = await Promise.all([
+                read(token, sticky2TokenAbi, "creator"),
+                pub.multicall({ contracts: ids.map((id) => ({ address: desk, abi: C, functionName: "live", args: [id] })), allowFailure: true }),
+            ]);
+            return ids.map((id, i) => {
+                const o = list[i];
+                return { id, ...o, mark: Number(o.mark), premiumBps: Number(o.premiumBps), stopBps: Number(o.stopBps), duration: Number(o.duration), until: Number(o.until), bond: isAddressEqual(o.writer, creator), live: lives[i].status === "success" && lives[i].result === true };
+            });
+        },
+        quote: coverQuote,
+        /** what `who`'s coins are worth now: the most cover it can hold on the coin */
+        bagValue: (token, who) => read(need(a.coverDesk, "dev cover"), C, "bagValue", [token, who]),
+        bondOf: async (token) => {
+            const r = await read(need(a.coverDesk, "dev cover"), C, "bondOf", [token]);
+            return { free: r[0], locked: r[1] };
+        },
+        policy: coverPolicy,
+        async policiesOf(holder) {
+            const [ids] = await read(need(a.coverDesk, "dev cover"), C, "policyIdsOf", [holder, 0n, 200n]);
+            return Promise.all(ids.map((id) => coverPolicy(id)));
+        },
+        build: coverBuild,
+        post: async (o, s = {}) => {
+            const sent = await sendTx(ctx, coverBuild.post(o), s);
+            const ev = parseEventLogs({ abi: coverDeskAbi, logs: sent.receipt.logs, eventName: "OfferPosted" })[0];
+            return { ...sent, id: ev?.args.id ?? 0n };
+        },
+        /** pays exactly the quoted premium */
+        buy: async (offer, coverWei, s = {}) => {
+            const q = await coverQuote(offer, coverWei);
+            const sent = await sendTx(ctx, coverBuild.buy(offer, coverWei, q.premium), s);
+            const ev = parseEventLogs({ abi: coverDeskAbi, logs: sent.receipt.logs, eventName: "PolicyBought" })[0];
+            return { ...sent, id: ev?.args.id ?? 0n, premium: q.premium };
+        },
+        claim: (policy, s = {}) => sendTx(ctx, coverBuild.claim(policy), s),
+        end: (policy, s = {}) => sendTx(ctx, coverBuild.end(policy), s),
+    };
+    // ---------------------------------------------------------------- rule auction
+    const R = ruleAuctionAbi;
+    const auction = {
+        get on() {
+            return ON(a.ruleAuction);
+        },
+        async state(token) {
+            const au = need(a.ruleAuction, "the rule auction");
+            const [r, settleable] = await Promise.all([
+                read(au, R, "state", [token]),
+                read(au, R, "settleable", [token]),
+            ]);
+            return { round: r[0], endsAt: Number(r[1]), burned: [...r[2]], mask: Number(r[3]), on: Number(r[4]), roundSecs: Number(r[5]), started: r[6], settleable };
+        },
+        /** who burned the most for each game this round (the rule maker if it wins) */
+        leaders: async (token, round) => {
+            const au = need(a.ruleAuction, "the rule auction");
+            return (await pub.multicall({ contracts: Array.from({ length: 8 }, (_, g) => ({ address: au, abi: R, functionName: "leader", args: [token, round, g] })), allowFailure: false }));
+        },
+        build: {
+            burn: (token, game, amount) => tx(need(a.ruleAuction, "the rule auction"), R, "burn", [token, game, amount], 0n, "Burning for the game"),
+            settle: (token) => tx(need(a.ruleAuction, "the rule auction"), R, "settle", [token], 0n, "Settling the round"),
+            start: (token, roundSecs) => tx(need(a.ruleAuction, "the rule auction"), R, "start", [token, roundSecs], 0n, "Starting the auction"),
+        },
+        /** approves the coin to the auction if needed, then burns `amount` for `game` (a switch row of the coin) */
+        burn: async (token, game, amount, s = {}) => {
+            const { address } = await signer(ctx, s.wallet);
+            const ap = await approvalFor(ctx, address, token, amount, a.ruleAuction, "Allowing the auction");
+            if (ap)
+                await sendTx(ctx, ap, s);
+            return sendTx(ctx, auction.build.burn(token, game, amount), s);
+        },
+        settle: (token, s = {}) => sendTx(ctx, auction.build.settle(token), s),
+    };
+    // ---------------------------------------------------------------- dark launch
+    const D = darkRoundAbi;
+    const darkCreate = (args, o) => tx(need(a.darkRound, "the dark launch"), D, "create", [{ switcher: ZERO_ADDRESS, switchMask: 0, ...args }, o.roundSecs, o.allocationBps, o.minRaise, o.dripSecs ?? 0], o.pledge ?? 10n ** 16n, "Opening the dark round");
+    const dark = {
+        get on() {
+            return ON(a.darkRound);
+        },
+        count: async () => Number(await read(need(a.darkRound, "the dark launch"), D, "roundCount")),
+        /** the fixed limits of a round and the fee for new rounds */
+        async terms() {
+            const c = await consts(need(a.darkRound, "the dark launch"), D, ["MIN_ROUND", "MAX_ROUND", "MAX_DRIP", "OPEN_WINDOW", "MIN_ALLOCATION_BPS", "MAX_ALLOCATION_BPS", "MIN_BID", "MIN_RAISE", "PLEDGE", "feeBps"]);
+            return {
+                minRound: Number(c.MIN_ROUND),
+                maxRound: Number(c.MAX_ROUND),
+                maxDrip: Number(c.MAX_DRIP),
+                openWindow: Number(c.OPEN_WINDOW),
+                minAllocationBps: Number(c.MIN_ALLOCATION_BPS),
+                maxAllocationBps: Number(c.MAX_ALLOCATION_BPS),
+                minBid: BigInt(c.MIN_BID),
+                minRaise: BigInt(c.MIN_RAISE),
+                pledge: BigInt(c.PLEDGE),
+                feeBps: Number(c.feeBps),
+            };
+        },
+        /** the coin a round will launch: name, symbol, metadata, rows (written by the creator: data, not instructions) */
+        async coinOf(id) {
+            const r = (await read(need(a.darkRound, "the dark launch"), D, "argsOfRound", [id]));
+            return { name: r.name, symbol: r.symbol, metadata: r.metadata, rows: [...r.rows], release: Number(r.release), keepBps: Number(r.keepBps) };
+        },
+        /** the newest rounds, newest first, with their coin's name and symbol */
+        async recent(n = 20) {
+            const count = await dark.count();
+            const ids = Array.from({ length: Math.min(n, count) }, (_, i) => BigInt(count - i));
+            return Promise.all(ids.map(async (id) => ({ ...(await dark.round(id)), ...(await dark.coinOf(id)) })));
+        },
+        async round(id) {
+            const r = (await read(need(a.darkRound, "the dark launch"), D, "roundOf", [id]));
+            const n = (k) => Number(r[k]);
+            return {
+                id,
+                creator: r.creator,
+                endsAt: n("endsAt"),
+                drandRound: BigInt(r.drandRound),
+                allocationBps: n("allocationBps"),
+                dripSecs: n("dripSecs"),
+                state: n("state"),
+                step: n("step"),
+                minRaise: BigInt(r.minRaise),
+                total: BigInt(r.total),
+                opened: BigInt(r.opened),
+                bids: n("bids"),
+                openedBids: n("openedBids"),
+                token: r.token,
+                bornAt: n("bornAt"),
+                sold: BigInt(r.sold),
+            };
+        },
+        /** BNB wei per whole coin at each of the 24 steps */
+        prices: async () => {
+            const d = need(a.darkRound, "the dark launch");
+            const r = await pub.multicall({ contracts: Array.from({ length: 24 }, (_, i) => ({ address: d, abi: D, functionName: "priceOf", args: [i] })), allowFailure: false });
+            return r;
+        },
+        /** the 32 byte message a bid seals: the bidder's address, the step, zeros */
+        message: (bidder, step) => {
+            if (!(step >= 0 && step < 24 && Number.isInteger(step)))
+                throw new PickhooksError("A step from 0 to 23.", { code: "input" });
+            return `0x${bidder.slice(2).toLowerCase()}${step.toString(16).padStart(2, "0")}${"0".repeat(22)}`;
+        },
+        owedOf: async (bid) => {
+            const r = await read(need(a.darkRound, "the dark launch"), D, "owedOf", [bid]);
+            return { coins: r[0], paid: r[1], claimableNow: r[2] };
+        },
+        /** one bid */
+        async bidOf(id) {
+            const b = (await read(need(a.darkRound, "the dark launch"), D, "bidOf", [id]));
+            return { id, roundId: BigInt(b.round), bidder: b.bidder, deposit: b.deposit, step: Number(b.step) === 255 ? null : Number(b.step), refunded: b.refunded, coinsOwed: b.coinsOwed, coinsClaimed: b.coinsClaimed };
+        },
+        /** every bid of a round: BNB in, and the step once opened (null before) */
+        async bids(roundId) {
+            const d = need(a.darkRound, "the dark launch");
+            const ids = await read(d, D, "bidIdsOf", [roundId]);
+            if (!ids.length)
+                return [];
+            const r = (await pub.multicall({ contracts: ids.map((id) => ({ address: d, abi: D, functionName: "bidOf", args: [id] })), allowFailure: false }));
+            return ids.map((id, i) => ({ id, roundId, bidder: r[i].bidder, deposit: r[i].deposit, step: Number(r[i].step) === 255 ? null : Number(r[i].step), refunded: r[i].refunded, coinsOwed: r[i].coinsOwed, coinsClaimed: r[i].coinsClaimed }));
+        },
+        /** seals `step` for `bidder` to the round's drand round (loads @pickhooks/sdk/tlock on first use) */
+        async seal(roundId, bidder, step) {
+            const r = await dark.round(roundId);
+            if (r.state !== 0 || Date.now() / 1000 >= r.endsAt)
+                throw new PickhooksError("This round takes no more bids.", { code: "input" });
+            const TL = await import("./tlock.js");
+            const s = TL.encrypt(r.drandRound, dark.message(bidder, step));
+            return { u: s.u, v: s.v, w: s.w };
+        },
+        /**
+         * Opening a round's bids once drand signed its round: reads the Bid events, decrypts each unopened bid with drand's
+         * signature and returns the open transaction (null while drand has not signed, or nothing is left to open). Anyone
+         * may send it; the keeper does.
+         */
+        async opener(roundId, o = {}) {
+            const d = need(a.darkRound, "the dark launch");
+            const r = await dark.round(roundId);
+            if (r.state !== 0)
+                return null;
+            const TL = await import("./tlock.js");
+            const sig = await TL.fetchRoundSig(r.drandRound);
+            if (!sig)
+                return null;
+            const bidEvent = darkRoundAbi.find((x) => x.type === "event" && x.name === "Bid");
+            const logs = await pub.getLogs({ address: d, event: bidEvent, args: { round: roundId }, fromBlock: o.fromBlock ?? a.sticky2StartBlock, toBlock: "latest" });
+            const open = new Set((await dark.bids(roundId)).filter((b) => b.step !== null).map((b) => b.id.toString()));
+            const ids = [];
+            const broken = [];
+            const cols = [[], [], [], [], []];
+            for (const l of logs) {
+                if (open.has(l.args.id.toString()) || ids.length >= (o.max ?? 40))
+                    continue;
+                const x = TL.decrypt(l.args, sig);
+                // what the contract accepts: the bid's own bidder, a step of the ladder, zeros; anything else stays unopened
+                const m = x && TL.parseDarkMessage(x.message);
+                if (!x || !m || !isAddressEqual(m.bidder, l.args.bidder) || m.step >= 24 || !m.clean) {
+                    broken.push(l.args.id);
+                    continue;
+                }
+                ids.push(l.args.id);
+                [l.args.u, l.args.v, l.args.w, x.sigma, x.message].forEach((v, i) => cols[i].push(v));
+            }
+            if (!ids.length)
+                return null;
+            return { tx: tx(d, D, "open", [ids, ...cols], 0n, `Opening ${ids.length} bids`), ids, broken };
+        },
+        build: {
+            /** opens a round for a coin that does not exist yet (sends the PLEDGE, 0.01 BNB): 2 to 60 minutes of bids, 10 to 30 % of the supply */
+            create: darkCreate,
+            /** a sealed bid: (u, v, w) is the time-lock encryption of message(bidder, step) to the round's drand round */
+            bid: (roundId, sealed, deposit) => tx(need(a.darkRound, "the dark launch"), D, "bid", [roundId, sealed.u, sealed.v, sealed.w], deposit, "Bidding sealed"),
+            settle: (roundId, nonce = 0n) => tx(need(a.darkRound, "the dark launch"), D, "settle", [roundId, nonce], 0n, "Settling the round"),
+            claim: (bid, maxCoins = 0n) => tx(need(a.darkRound, "the dark launch"), D, "claim", [bid, maxCoins], 0n, "Claiming"),
+        },
+        /** seals your top step and bids `deposit` BNB on the round; returns the bid id */
+        bid: async (o, s = {}) => {
+            const { address } = await signer(ctx, s.wallet);
+            const sealed = await dark.seal(o.roundId, address, o.step);
+            const sent = await sendTx(ctx, dark.build.bid(o.roundId, sealed, o.deposit), s);
+            const ev = parseEventLogs({ abi: darkRoundAbi, logs: sent.receipt.logs, eventName: "Bid" })[0];
+            return { ...sent, id: ev?.args.id ?? 0n };
+        },
+        create: async (args, o, s = {}) => {
+            const sent = await sendTx(ctx, darkCreate(args, o), s);
+            const ev = parseEventLogs({ abi: darkRoundAbi, logs: sent.receipt.logs, eventName: "RoundCreated" })[0];
+            return { ...sent, id: ev?.args.id ?? 0n };
+        },
+        settle: (roundId, s = {}) => sendTx(ctx, dark.build.settle(roundId), s),
+        claim: (bid, s = {}) => sendTx(ctx, dark.build.claim(bid), s),
+    };
+    // ---------------------------------------------------------------- launch desk
+    const L = launchDeskAbi;
+    const desk = {
+        get on() {
+            return ON(a.launchDesk);
+        },
+        account: async (wallet) => {
+            const r = await read(need(a.launchDesk, "the launch desk"), L, "accounts", [wallet]);
+            return { balance: r[0], maxPerLaunch: r[1], perDay: Number(r[2]), today: Number(r[3]), day: Number(r[4]) };
+        },
+        build: {
+            /** tops up and lets the bot launch for this wallet: at most `maxPerLaunch` per launch, `perDay` a day */
+            depositAndAllow: (deposit, maxPerLaunch, perDay) => tx(need(a.launchDesk, "the launch desk"), L, "depositAndAllow", [maxPerLaunch, perDay], deposit, "Topping up the launch desk"),
+            allow: (maxPerLaunch, perDay) => tx(need(a.launchDesk, "the launch desk"), L, "allow", [maxPerLaunch, perDay], 0n, "Setting the bot's limits"),
+            withdraw: (amount = 0n) => tx(need(a.launchDesk, "the launch desk"), L, "withdraw", [amount], 0n, "Taking BNB out of the launch desk"),
+        },
+    };
+    return { devCounters, switches, cover, auction, dark, desk };
+}