hookr-sdk 0.2.1 → 1.1.0

package/dist/core/quotes.js

@@ -0,0 +1,550 @@
+import { decodeFunctionResult, encodeFunctionData, formatUnits, parseAbi, parseUnits } from "viem";
+import { registryAbi } from "./abi.js";
+import { decodeCuratedQuote, encodeCuratedQuoteCall } from "./registry.js";
+import { address, assert, uint, ZERO } from "./schema.js";
+import { ROBINHOOD_STOCK_TOKENS } from "./stocks.generated.js";
+import { contract } from "./wallet.js";
+/**
+ * Quote assets: every asset a Hookr 1 market may quote in, the classes the app and the release tooling name them by,
+ * their decimals, and the ERC-20 funding a launch or trade needs.
+ *
+ * On chain the registry decides. HookrRoot.initializePool refuses a quote `isQuote` does not admit (UnqualifiedQuote);
+ * native ETH is always admitted, an ERC-20 through the reviewed catalog (SET_QUOTE), a whole class by runtime code hash
+ * (SET_QUOTE_CLASS, every Robinhood stock token) or, while open quotes are on (OPEN_QUOTES), any contract that is not an
+ * EIP-7702 delegated account, as the live launchpads accept. `curatedQuote` tells the first three from an open quote.
+ * Nothing here can admit a quote: `quoteAdmission` reads the registry at a block, and a class below is a label for
+ * guidance, never an admission.
+ *
+ * The classification follows the live app's v2-asset-class.ts: the curated catalog first (the only source that can
+ * name a stablecoin), then the ERC-1967 beacon slot (every Robinhood stock token is a BeaconProxy of one beacon), then
+ * fail closed to an unconfident "erc20".
+ */
+/** ERC-1967 beacon slot: bytes32(uint256(keccak256("eip1967.proxy.beacon")) - 1). */
+export const ERC1967_BEACON_SLOT = "0xa3f0ad74e5423aebfd80d3ef4346578335a9a72aeaee59ff6cb3582b35133d50";
+/** ERC-1967 implementation slot: bytes32(uint256(keccak256("eip1967.proxy.implementation")) - 1). */
+export const ERC1967_IMPLEMENTATION_SLOT = "0x360894a13ba1a3210667c828492db98dca3e2076cc3735a920a3ca505d382bbc";
+/** The one beacon every Robinhood tokenized stock and ETF on chain 4663 proxies to (also its pause registry). */
+export const ROBINHOOD_STOCK_BEACON = "0xe10b6f6b275de231345c20d14ab812db62151b00";
+/** The runtime keccak256 every one of those proxies shares: OpenZeppelin BeaconProxy with that beacon immutable. */
+export const ROBINHOOD_STOCK_PROXY_RUNTIME_KECCAK256 = "0x6c1fdd40002dcb440c7fff6a84171404d279ccb057803b65826f7546acd65630";
+/** Canonical Permit2: HookrForwarder pulls a gasless swap's ERC-20 input through it. */
+export const PERMIT2 = "0x000000000022d473030f116ddee9f6b43ac78ba3";
+/** The block the catalog below was read at (chain 4663, through Alchemy, 2026-10-06 00:54 UTC). */
+export const ROBINHOOD_QUOTE_CATALOG_BLOCK = 81_225_166;
+/**
+ * The genesis catalog the owner set on 2026-10-05: the 20 largest tokens on Robinhood Chain by market cap at
+ * ROBINHOOD_QUOTE_CATALOG_BLOCK that pass review (WETH and USDG among them) plus HOOKR and What The Hook's WTH, in the
+ * registry's queue order (the release template's `quoteAssets`).
+ * Every field was read from chain 4663 at ROBINHOOD_QUOTE_CATALOG_BLOCK, not copied from a document (USDG and
+ * syrupUSDG are 6 decimals). WETH, USDG and U are ERC-1967 proxies: a runtime hash alone does not review their upgrade
+ * authority.
+ */
+export const ROBINHOOD_QUOTE_CATALOG = Object.freeze([
+    {
+        address: "0x0bd7d308f8e1639fab988df18a8011f41eacad73",
+        symbol: "WETH",
+        name: "WETH",
+        decimals: 18,
+        class: "weth",
+        runtimeKeccak256: "0x5706be52f64875fee65a2cec0d80e47a23d8793cbe85d214b48445e2d05f5353",
+        implementation: "0xc6b81b429797e0f555440b70cd99e032d7ae947e",
+    },
+    {
+        address: "0x5fc5360d0400a0fd4f2af552add042d716f1d168",
+        symbol: "USDG",
+        name: "Global Dollar",
+        decimals: 6,
+        class: "stable",
+        runtimeKeccak256: "0x864cc9ad53b338b82da1f7cab85ab0b3d5c8861acb422b6fec63cf36234f36a6",
+        implementation: "0x68184c449e1a8f34fa18d289737129fd27b66f8f",
+    },
+    {
+        address: "0x18e674231a58c239dc7daedcffe15ec3a24cff5c",
+        symbol: "HOOKR",
+        name: "Hookr.fun",
+        decimals: 18,
+        class: "hookr",
+        runtimeKeccak256: "0xd9346eaf1a9878650549765e1d4ce8b3d0516d93d3203e1c8b99e382428ebc8d",
+        implementation: null,
+    },
+    {
+        address: "0xb8fa8010833463aac5595b55b9045479239eff79",
+        symbol: "WTH",
+        name: "what the hook?",
+        decimals: 18,
+        class: "listed",
+        runtimeKeccak256: "0x21d9e3d68d1f15f3cb3080c8f9321e5a2dc3fe4d05f135ab203e9d0e966a8275",
+        implementation: null,
+    },
+    {
+        address: "0x51250b135174ca09450ec01c4aff73cf69dbb590",
+        symbol: "NOVAAI",
+        name: "NovaAI",
+        decimals: 18,
+        class: "listed",
+        runtimeKeccak256: "0x53fb452d8017996465eebb6bcd7c2dcd7ee1ad4997289cabd7141099fc716a49",
+        implementation: null,
+    },
+    {
+        address: "0x39dbed3a2bd333467115de45665cc57f813c4571",
+        symbol: "PONS",
+        name: "Pons",
+        decimals: 18,
+        class: "listed",
+        runtimeKeccak256: "0x16c3d3ede897688ddff79262606f13bead398332e65001f192460fbac4e1fb85",
+        implementation: null,
+    },
+    {
+        address: "0x5d3a1ff2b6bab83b63cd9ad0787074081a52ef34",
+        symbol: "USDe",
+        name: "USDe",
+        decimals: 18,
+        class: "listed",
+        runtimeKeccak256: "0x43d4a9c80fe87d7d878b8c8bdcb419261a1cb037e6833918c67c9b74e8519ca4",
+        implementation: null,
+    },
+    {
+        address: "0x020bfc650a365f8bb26819deaabf3e21291018b4",
+        symbol: "CASHCAT",
+        name: "Cash Cat",
+        decimals: 18,
+        class: "listed",
+        runtimeKeccak256: "0x725781ccca82a0bf9b1f8920b2fe58ea1e4facf46d0db9f50226d6409de890fe",
+        implementation: null,
+    },
+    {
+        address: "0x57c0e45cb534413d1c20a4240955d6bb250bb4f1",
+        symbol: "UP",
+        name: "up",
+        decimals: 18,
+        class: "listed",
+        runtimeKeccak256: "0xb4d0e29f0aa13a275c7615fbe5946d2b05df8a01811b068203aa73f55b069d8c",
+        implementation: null,
+    },
+    {
+        address: "0x40858070814a57fdf33a613ae84fe0a8b4a874f7",
+        symbol: "syrupUSDG",
+        name: "syrupUSDG",
+        decimals: 6,
+        class: "listed",
+        runtimeKeccak256: "0xc91c79f8c922a0c3a31f130aa8199c2f9ae03027ac49f2ad759dde9cb8b1dd61",
+        implementation: null,
+    },
+    {
+        address: "0x2e8c31162b855a2ffa90f6f8634643ad6f111e18",
+        symbol: "AI",
+        name: "Artificial Inu",
+        decimals: 18,
+        class: "listed",
+        runtimeKeccak256: "0xf10f86b05965a827a332e6c73086f18026fbe3917f4bffbec3f938b3b5397b56",
+        implementation: null,
+    },
+    {
+        address: "0x07ebb29a38fbcb41563817e5e19f2cec619c90d2",
+        symbol: "BUN",
+        name: "Bundle Cat",
+        decimals: 18,
+        class: "listed",
+        runtimeKeccak256: "0x7c16047fae9f8fee5effb88675360c56f8fbfa4f4d430181205f299eac934ff9",
+        implementation: null,
+    },
+    {
+        address: "0xaa07a0e9209e16ac99708c3ec70159c6ef3128a3",
+        symbol: "ORBIO",
+        name: "Orbio.so",
+        decimals: 18,
+        class: "listed",
+        runtimeKeccak256: "0x67d7a9d1677c238d9dae8679f500586f7d189e7bcda59964f3ce634dcf7363cf",
+        implementation: null,
+    },
+    {
+        address: "0x98096d17e191b3da1d5f99a6d7b3584351b11e18",
+        symbol: "BONER",
+        name: "Boner Coin",
+        decimals: 18,
+        class: "listed",
+        runtimeKeccak256: "0xf10f86b05965a827a332e6c73086f18026fbe3917f4bffbec3f938b3b5397b56",
+        implementation: null,
+    },
+    {
+        address: "0x0e0d2c89a5a019fe1cf762e5e33187631dacc21b",
+        symbol: "CHUMP",
+        name: "Chump Coin",
+        decimals: 18,
+        class: "listed",
+        runtimeKeccak256: "0x45d441a5e2161cd6e1c85796510b7629bf4729788efa88db59c07164aa9a524a",
+        implementation: null,
+    },
+    {
+        address: "0x8e41fd25e85e624560fa50ff9f117a02cd30b8b3",
+        symbol: "SIF",
+        name: "Super Inu Force",
+        decimals: 18,
+        class: "listed",
+        runtimeKeccak256: "0xd6b9feb551dea0e2dd7fe152cf14408773760f153134d29a33a0686af976e5db",
+        implementation: null,
+    },
+    {
+        address: "0xce24439f2d9c6a2289f741120fe202248b666666",
+        symbol: "U",
+        name: "United Stables",
+        decimals: 18,
+        class: "listed",
+        runtimeKeccak256: "0xae12b1d61f7ed4febf649ccf319cb49a0e921cca3739dcb01b47d316049d46ff",
+        implementation: "0x261c4ee7e337852f919b90372e2518d6bff7ea4c",
+    },
+    {
+        address: "0xc38c332012a9116dcade0c7f43b5d3c71799a9f8",
+        symbol: "HOODCHAN",
+        name: "HOODCHAN",
+        decimals: 18,
+        class: "listed",
+        runtimeKeccak256: "0xc59b76e554d38563071118131d593fa1ff92dcac9df1d6ce19b6349d96f05c7f",
+        implementation: null,
+    },
+    {
+        address: "0x385f4f8ae47651ce5f58f5265395a669f8281e18",
+        symbol: "MEME",
+        name: "A Meme Coin",
+        decimals: 18,
+        class: "listed",
+        runtimeKeccak256: "0xf10f86b05965a827a332e6c73086f18026fbe3917f4bffbec3f938b3b5397b56",
+        implementation: null,
+    },
+    {
+        address: "0x56910d4409f3a0c78c64dd8d0545ff0705389870",
+        symbol: "Index",
+        name: "The Index",
+        decimals: 18,
+        class: "listed",
+        runtimeKeccak256: "0x4ee19c3a5cda0991509f65faa494c490942df5f19fc79659306a125c15b41d84",
+        implementation: null,
+    },
+    {
+        address: "0x5cb6f181081301b44905f3ae15419112ecabd8a6",
+        symbol: "PIPEDOG",
+        name: "pipedog",
+        decimals: 18,
+        class: "listed",
+        runtimeKeccak256: "0xc0d0d825734a0b6d070991217c8c0fb8530b574e839d2ff7685341fd9d707912",
+        implementation: null,
+    },
+    {
+        address: "0x2d8d6f4a93acd7a916a5a654ec8b690ba3b3eadd",
+        symbol: "STATICS",
+        name: "Statics",
+        decimals: 18,
+        class: "listed",
+        runtimeKeccak256: "0xf10f86b05965a827a332e6c73086f18026fbe3917f4bffbec3f938b3b5397b56",
+        implementation: null,
+    },
+]);
+/** Native ETH: the zero address in every pool key, 18 decimals, always admitted by the registry. */
+export const NATIVE_QUOTE = Object.freeze({
+    address: ZERO,
+    symbol: "ETH",
+    decimals: 18,
+    class: "native",
+    source: "native",
+    confident: true,
+});
+/** Display labels for each class. */
+export const QUOTE_CLASS_LABELS = Object.freeze({
+    native: "ETH",
+    weth: "WETH",
+    stable: "USDG / stablecoin",
+    hookr: "HOOKR",
+    listed: "Listed token",
+    rwa: "Robinhood stock token",
+    erc20: "Other ERC-20",
+});
+/** What a stock quote means for the pool, in the live classifier's words. */
+export const STOCK_QUOTE_NOTE = "This token is a Robinhood tokenized stock: its proxy points at the shared beacon, so a pause there halts every pool holding it.";
+/** Why an unclassified quote still warns. */
+export const UNCLASSIFIED_QUOTE_NOTE = "This address is not on the verified list and does not point at the shared Robinhood stock beacon. It is treated as an ERC-20 you do not control: verify what it does on transfer before you use it.";
+/** An upgradeable catalog quote. */
+export const PROXY_QUOTE_NOTE = "This token is an upgradeable proxy: its issuer can change what it does, and every pool quoting it follows.";
+/** A quote whose transfers move less or more than asked is refused by every Hookr transfer (exact settlement). */
+export const EXACT_TRANSFER_NOTE = "Hookr settles exact amounts: a token that takes a fee on transfer, rebases or blocks addresses can make launches, trades and fee claims revert.";
+const lower = (a) => a.toLowerCase();
+/** The reviewed catalog entry for an address, or null. */
+export function catalogQuote(target) {
+    return ROBINHOOD_QUOTE_CATALOG.find((q) => q.address === lower(target)) ?? null;
+}
+const STOCKS = new Map(ROBINHOOD_STOCK_TOKENS.map((t) => [t.address, t]));
+/** The scanned stock token at an address (its label), or null. A token absent here can still be a stock token. */
+export function stockToken(target) {
+    return STOCKS.get(lower(target)) ?? null;
+}
+/** A token's decimals as the contracts can use them: an integer from 0 to 36. Anything else throws. */
+export function quoteDecimals(value) {
+    const n = typeof value === "bigint" ? Number(value) : value;
+    assert(typeof n === "number" && Number.isInteger(n) && n >= 0 && n <= 36, "Quote decimals must be an integer from 0 to 36");
+    return n;
+}
+/** Parses a decimal amount typed in quote units ("1.5") into raw units, refusing more places than the token has. */
+export function parseQuoteAmount(text, decimals) {
+    const places = quoteDecimals(decimals);
+    const t = typeof text === "string" ? text.trim() : "";
+    assert(/^(0|[1-9]\d*)(\.\d+)?$|^0?\.\d+$/.test(t), "Enter a plain decimal amount");
+    const fraction = t.includes(".") ? t.split(".")[1] : "";
+    assert(fraction.length <= places, `This quote has ${places} decimal places`);
+    return parseUnits(t.startsWith(".") ? "0" + t : t, places);
+}
+/** Formats a raw quote amount in its token's units. */
+export function formatQuoteAmount(raw, decimals) {
+    return formatUnits(uint(raw), quoteDecimals(decimals));
+}
+/** The address a 32-byte storage word holds, or null for an empty or malformed word. */
+export function addressFromWord(word) {
+    if (typeof word !== "string" || !/^0x[\da-fA-F]{1,64}$/.test(word))
+        return null;
+    const tail = word.slice(2).padStart(64, "0").slice(-40);
+    return /^0+$/.test(tail) ? null : `0x${tail.toLowerCase()}`;
+}
+/** The classification that needs no network: native ETH, the catalog and the scanned stock list. Null otherwise. */
+export function classifyQuoteOffline(target) {
+    const a = address(target, true);
+    if (a === ZERO)
+        return NATIVE_QUOTE;
+    const listed = catalogQuote(a);
+    if (listed)
+        return {
+            address: a,
+            symbol: listed.symbol,
+            decimals: listed.decimals,
+            class: listed.class,
+            source: "catalog",
+            confident: true,
+        };
+    const stock = stockToken(a);
+    // The scan read each listed proxy's beacon slot; the list is still only a label source, so the answer says beacon.
+    if (stock)
+        return {
+            address: a,
+            symbol: stock.symbol,
+            decimals: 18,
+            class: "rwa",
+            source: "beacon",
+            confident: true,
+            name: stock.name,
+        };
+    return null;
+}
+const METADATA = parseAbi([
+    "function decimals() view returns (uint8)",
+    "function symbol() view returns (string)",
+    "function name() view returns (string)",
+]);
+async function readMetadata(reader, target, fn) {
+    try {
+        const data = await reader.call(target, encodeFunctionData({ abi: METADATA, functionName: fn }));
+        return decodeFunctionResult({ abi: METADATA, functionName: fn, data });
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * The full classification: native, the catalog, then the ERC-1967 beacon slot, then an unconfident "erc20". Decimals
+ * and symbol are read from the token and are null when it does not answer (a quote without decimals cannot be priced
+ * or funded, so callers refuse it). A read that throws degrades to "erc20", never to a safer class.
+ */
+export async function classifyQuote(reader, target) {
+    const a = address(target, true);
+    const offline = classifyQuoteOffline(a);
+    if (offline && offline.source !== "beacon")
+        return offline;
+    let beacon = null;
+    try {
+        beacon = addressFromWord(await reader.getStorageAt(a, ERC1967_BEACON_SLOT));
+    }
+    catch {
+        beacon = null;
+    }
+    const [decimals, symbol, name] = await Promise.all([
+        readMetadata(reader, a, "decimals"),
+        readMetadata(reader, a, "symbol"),
+        readMetadata(reader, a, "name"),
+    ]);
+    let d = null;
+    try {
+        d = quoteDecimals(decimals);
+    }
+    catch {
+        d = null;
+    }
+    const s = typeof symbol === "string" && symbol.trim() !== "" ? symbol : null;
+    if (beacon === ROBINHOOD_STOCK_BEACON) {
+        const n = typeof name === "string" && name.trim() !== "" ? name : offline?.name;
+        return {
+            address: a,
+            symbol: s,
+            decimals: d,
+            class: "rwa",
+            source: "beacon",
+            confident: true,
+            ...(n ? { name: n } : {}),
+        };
+    }
+    return { address: a, symbol: s, decimals: d, class: "erc20", source: "unclassified", confident: false };
+}
+/**
+ * The warnings a quote carries before anyone launches or trades against it, in display order. `curated` is the
+ * registry's `curatedQuote` answer (`quoteAdmission`): false adds the open-quote note.
+ */
+export function quoteWarnings(q, curated) {
+    const out = [];
+    if (q.class === "rwa")
+        out.push(STOCK_QUOTE_NOTE);
+    if (curated === false && q.class !== "native")
+        out.push(OPEN_QUOTE_NOTE);
+    if (!q.confident)
+        out.push(UNCLASSIFIED_QUOTE_NOTE);
+    if (q.source === "catalog" && catalogQuote(q.address)?.implementation)
+        out.push(PROXY_QUOTE_NOTE);
+    if (q.class === "rwa" || q.class === "erc20")
+        out.push(EXACT_TRANSFER_NOTE);
+    if (q.decimals === null && q.class !== "native")
+        out.push("This token did not report its decimals, so no amount in it can be read.");
+    return out;
+}
+/** A read-only registry isQuote call for `asset` at the manifest's registry. */
+export function buildIsQuote(m, asset) {
+    return {
+        to: contract(m, "registry"),
+        data: encodeFunctionData({ abi: registryAbi, functionName: "isQuote", args: [address(asset, true)] }),
+    };
+}
+/** Whether the registry admits `asset` as a new market's quote, by an eth_call the caller pins to a block. */
+export async function quoteAdmitted(ethCall, m, asset) {
+    const { to, data } = buildIsQuote(m, asset);
+    return decodeFunctionResult({ abi: registryAbi, functionName: "isQuote", data: await ethCall(to, data) });
+}
+/**
+ * What the registry says of a quote at the caller's block: `admitted`, whether a new pool may bind it (`isQuote`), and
+ * `curated`, whether it is native ETH, a catalog asset or a class member rather than admitted only by open quotes.
+ * `curated` is null when the registry does not answer `curatedQuote` (a release without quote classes, where every
+ * admitted quote is a catalog asset) or the read fails; a caller then labels the quote by its classification alone.
+ */
+export async function quoteAdmission(ethCall, m, asset) {
+    const admitted = await quoteAdmitted(ethCall, m, asset);
+    let curated = null;
+    try {
+        curated = decodeCuratedQuote(await ethCall(contract(m, "registry"), encodeCuratedQuoteCall(asset)));
+    }
+    catch {
+        curated = null;
+    }
+    return { admitted, curated: curated === null ? null : admitted && curated };
+}
+/** The note an open quote carries: the registry admits it without any review. */
+export const OPEN_QUOTE_NOTE = "The registry admits this token only because open quotes are on: nobody reviewed it. Check its address before you use it.";
+/**
+ * Refuses a member quote the Launcher or the root would refuse before any pool opens, and one no amount could be read
+ * in: the subject itself, a quote repeated in one family, or an ERC-20 without known decimals. Registry admission is
+ * checked on chain (`quoteAdmitted`).
+ */
+export function checkLaunchQuotes(subject, quotes) {
+    assert(quotes.length > 0 && quotes.length <= 8, "A family has one to eight quote markets");
+    const seen = new Set();
+    for (const q of quotes) {
+        const a = address(q.address, true);
+        assert(subject === null || a !== address(subject), "A market cannot quote its own token");
+        assert(!seen.has(a), "Each family member needs a different quote");
+        seen.add(a);
+        assert(a === ZERO || q.decimals !== null, "This quote did not report its decimals");
+        if (q.decimals !== null)
+            quoteDecimals(q.decimals);
+    }
+}
+/**
+ * The funding HookrLauncher.launch / launchAdvised / launchWithBuy / launchFamily collects from the caller: for every
+ * member, its quote side's maximum (amount1Max when the subject sorts first, else amount0Max) plus the dev buy's quoteIn
+ * on each buy's member (launchFamily takes up to one per member); for an existing subject, the subject side's maxima too
+ * (a new token is minted to the Launcher); and the launch fee in native value (r31, `launchFee`, read at the launch
+ * block). Native ETH is the call's value; each ERC-20 needs an allowance to the Launcher of the listed amount.
+ */
+export function launchFunding(m, subject, existingSubject, members, launchFee, buys = []) {
+    const s = address(subject);
+    const launcher = contract(m, "launcher");
+    assert(typeof launchFee === "bigint" && launchFee >= 0n, "Invalid launch fee");
+    let native = launchFee;
+    const erc20 = new Map();
+    const add = (token, amount) => {
+        if (amount === 0n)
+            return;
+        if (token === ZERO)
+            native += amount;
+        else
+            erc20.set(token, (erc20.get(token) ?? 0n) + amount);
+    };
+    const seen = new Set();
+    for (const buy of buys) {
+        assert(Number.isSafeInteger(buy.member) && buy.member >= 0 && buy.member < members.length, "The dev buy names no family member");
+        assert(!seen.has(buy.member), "At most one dev buy per member");
+        seen.add(buy.member);
+    }
+    members.forEach((member, i) => {
+        const q = address(member.quote, true);
+        assert(q !== s, "A market cannot quote its own token");
+        const subjectFirst = BigInt(s) < BigInt(q);
+        const quoteMax = uint(subjectFirst ? member.amount1Max : member.amount0Max, 128);
+        const subjectMax = uint(subjectFirst ? member.amount0Max : member.amount1Max, 128);
+        const buy = buys.find((b) => b.member === i);
+        add(q, quoteMax + (buy ? uint(buy.quoteIn, 128) : 0n));
+        if (existingSubject)
+            add(s, subjectMax);
+    });
+    return {
+        native,
+        allowances: [...erc20].map(([token, amount]) => ({ token: token, spender: launcher, amount })),
+    };
+}
+/**
+ * The ERC-20 allowance HookrRouter.swap needs: the input currency's exact amount for exact input, the bound for exact
+ * output, to the router. Null when the input is native ETH (sent as value). Through HookrForwarder (gasless) the
+ * allowance goes to Permit2 instead: `permit2Allowance`.
+ */
+export function swapAllowance(m, s) {
+    const input = address(s.zeroForOne ? s.key.currency0 : s.key.currency1, true);
+    if (input === ZERO)
+        return null;
+    const amount = s.amountSpecified < 0n ? -s.amountSpecified : uint(s.amountBound, 128);
+    return { token: input, spender: contract(m, "router"), amount };
+}
+/** A gasless swap's ERC-20 input needs a Permit2 allowance; the intent's signature then authorizes each pull. */
+export function permit2Allowance(token, amount) {
+    const t = address(token);
+    return { token: t, spender: PERMIT2, amount: uint(amount) };
+}
+const ERC20_APPROVE = parseAbi(["function approve(address spender, uint256 amount) returns (bool)"]);
+/**
+ * The ERC-20 approve for an allowance. `current` is the signer's allowance now: a token that refuses to move a
+ * nonzero allowance to another nonzero value (USDT-style) is reset to zero first, so pass it and send the calls in
+ * order. Returns no call when the allowance already covers the amount.
+ */
+export function buildApprovals(m, a, current = 0n) {
+    const chainId = Number(uint(m.chainId));
+    const token = address(a.token), spender = address(a.spender);
+    uint(a.amount);
+    if (uint(current) >= a.amount)
+        return [];
+    const call = (amount) => ({
+        chainId,
+        to: token,
+        data: encodeFunctionData({ abi: ERC20_APPROVE, functionName: "approve", args: [spender, amount] }),
+        value: 0n,
+    });
+    return current > 0n ? [call(0n), call(a.amount)] : [call(a.amount)];
+}
+/**
+ * The Robinhood stock tokens as one reviewed quote class (SET_QUOTE_CLASS): the runtime keccak256 every proxy of the
+ * stock beacon shares, the beacon it embeds, and AAPL as the witness the registry checks the hash against.
+ */
+export const ROBINHOOD_STOCK_QUOTE_CLASS = Object.freeze({
+    label: "Robinhood stock tokens",
+    runtimeKeccak256: ROBINHOOD_STOCK_PROXY_RUNTIME_KECCAK256,
+    beacon: ROBINHOOD_STOCK_BEACON,
+    witness: "0xaf3d76f1834a1d425780943c99ea8a608f8a93f9",
+});

package/dist/core/referrals.d.ts

@@ -0,0 +1,32 @@
+import type { Address, Hash, DeploymentManifest, Call } from "./schema.js";
+export declare function referralAuthorization(m: DeploymentManifest, message: {
+    payer: Address;
+    referrer: Address;
+    programKey: Hash;
+    codeHash: Hash;
+    nonce: bigint;
+    deadline: bigint;
+}): {
+    domain: {
+        name: string;
+        version: string;
+        chainId: number;
+        verifyingContract: `0x${string}`;
+    };
+    primaryType: "ReferralAuthorization";
+    types: {
+        ReferralAuthorization: {
+            name: string;
+            type: string;
+        }[];
+    };
+    message: {
+        payer: Address;
+        referrer: Address;
+        programKey: Hash;
+        codeHash: Hash;
+        nonce: bigint;
+        deadline: bigint;
+    };
+};
+export declare function buildReferralBinding(m: DeploymentManifest, key: Hash, referrer: Address, code: Hash): Call;

package/dist/core/referrals.js

@@ -0,0 +1,36 @@
+import { uint, address, deployment, hash, assert } from "./schema.js";
+import { referralsAbi } from "./abi.js";
+import { contract, buildCall } from "./wallet.js";
+export function referralAuthorization(m, message) {
+    deployment(m);
+    hash(message.programKey);
+    hash(message.codeHash);
+    assert(message.payer.toLowerCase() !== message.referrer.toLowerCase(), "Self referral");
+    address(message.payer);
+    address(message.referrer);
+    uint(message.nonce);
+    uint(message.deadline);
+    return {
+        domain: {
+            name: "HookrReferralRegistry",
+            version: "1",
+            chainId: Number(m.chainId),
+            verifyingContract: contract(m, "referrals"),
+        },
+        primaryType: "ReferralAuthorization",
+        types: {
+            ReferralAuthorization: [
+                { name: "payer", type: "address" },
+                { name: "referrer", type: "address" },
+                { name: "programKey", type: "bytes32" },
+                { name: "codeHash", type: "bytes32" },
+                { name: "nonce", type: "uint256" },
+                { name: "deadline", type: "uint256" },
+            ],
+        },
+        message,
+    };
+}
+export function buildReferralBinding(m, key, referrer, code) {
+    return buildCall(m, "referrals", referralsAbi, "register", [key, address(referrer), code]);
+}