hookr-sdk 0.2.1 → 1.1.0

package/dist/releases.js

@@ -0,0 +1,365 @@
+/**
+ * Hookr on Robinhood Chain: the production release `hookr-1`, its canary `canary-hookr-1-a`, each release's
+ * deployment, the Rules modules its root admits beside the release's own, and the deployment manifest the builders take.
+ *
+ * Every address is fixed by CREATE3 from the release deployer, the release id and the contract's name, so it is known
+ * before the contract is deployed and is the same on every machine. `test/releases.test.ts` derives each one again
+ * from those inputs. The canary runs the same code at its own addresses and exists to prove a release before
+ * production; build on `HOOKR_1`.
+ */
+import { defineChain, keccak256 } from "viem";
+import { deployment } from "./core/index.js";
+import { DEPLOYMENTS } from "./deployments.js";
+/** Robinhood Chain's id. */
+export const CHAIN_ID = 4663;
+/**
+ * The chain's public, keyless RPC endpoint. Fine for a few reads. Under load it rate limits, and a wide `eth_getLogs`
+ * can come back as an empty array instead of an error, so anything that must not miss data should use a provider
+ * endpoint of its own.
+ */
+export const RPC_URL = "https://rpc.mainnet.chain.robinhood.com";
+/** The block explorer people open: RobinScan. No trailing slash. */
+export const EXPLORER_URL = "https://robin.etherscan.io";
+/**
+ * Robinhood Chain for viem, on any viem 2, with RobinScan as its explorer. viem 2.55 and later also ship it as
+ * `robinhood` from `viem/chains`, with the same id and RPC endpoint and Blockscout as its explorer.
+ */
+export const ROBINHOOD_CHAIN = defineChain({
+    id: CHAIN_ID,
+    name: "Robinhood Chain",
+    nativeCurrency: { name: "Ether", symbol: "ETH", decimals: 18 },
+    rpcUrls: { default: { http: [RPC_URL] } },
+    blockExplorers: { default: { name: "RobinScan", url: EXPLORER_URL } },
+    contracts: { multicall3: { address: "0xca11bde05977b3631167028862be2a173976ca11" } },
+});
+/** An address's page on the explorer. */
+export function explorerAddressUrl(address) {
+    return `${EXPLORER_URL}/address/${address}`;
+}
+/** A transaction's page on the explorer. */
+export function explorerTxUrl(hash) {
+    return `${EXPLORER_URL}/tx/${hash}`;
+}
+/** Uniswap v4's dynamic-fee flag. Every Hookr pool's `PoolKey.fee` is this: the hook sets the LP fee on each swap. */
+export const DYNAMIC_FEE = 0x800000;
+/** The price limit for a `zeroForOne` swap that may fill in full: TickMath's MIN_SQRT_PRICE + 1. */
+export const MIN_SQRT_PRICE_LIMIT = 4295128740n;
+/** The price limit for a `oneForZero` swap that may fill in full: TickMath's MAX_SQRT_PRICE - 1. */
+export const MAX_SQRT_PRICE_LIMIT = 1461446703485210103287273052203988822378723970341n;
+/** Uniswap v4's PoolManager on Robinhood Chain. Every Hookr pool lives in it. */
+export const POOL_MANAGER = "0x8366a39CC670B4001A1121B8F6A443A643e40951";
+/** The account that deploys both releases. CREATE3 addresses depend on it, never on a nonce. */
+export const RELEASE_DEPLOYER = "0x0c0967485A25F18E70262a2Ee80c7595CC64a5fC";
+/** The CREATE3 factory both releases deploy through. */
+export const CREATE3_FACTORY = "0xc7c662Fc760FE1d5cB97fd8A68cb43A046da3F7d";
+/** The source commit both releases are built from. */
+export const RELEASE_SOURCE_COMMIT = "412960b37a631ce145d49fb4a1887f04a4d1fa74";
+/** The release digest: the hash of the build both releases deploy from. */
+export const RELEASE_PACKET_DIGEST = "83962c12ff55df431612ffae8bfc66a30041eb310035cfc30eab1bb9bdc0e031";
+/** A deployment, frozen, so no caller can change the facts a release carries. */
+function frozen(d) {
+    return d && Object.freeze({ ...d, runtimeHashes: Object.freeze({ ...d.runtimeHashes }) });
+}
+/** The production release. Build on this one. */
+export const HOOKR_1 = Object.freeze({
+    releaseId: "hookr-1",
+    canary: false,
+    chainId: CHAIN_ID,
+    deployment: frozen(DEPLOYMENTS["hookr-1"]),
+    rulesModules: Object.freeze({
+        standard: Object.freeze({
+            name: "standard",
+            rules: "0x4a71c270b1520F94064268102AebD744b0DE7942",
+            rulesRuntimeHash: "0x4b6d50b40981b8082f3ee5a7ebf57e48489f71c94c2a3b94032a1d1a382b515b",
+            recapture: "0xF83569E564d70daebc35950f66a73f2e2B915583",
+            recaptureRuntimeHash: "0xb78c68d64388c9c0c4d20faa3d429309a6a025024c3eefc579831bb10de145ed",
+        }),
+        /**
+         * Deployed 2026-10-07 beside the release (CREATE3 from the release deployer, release id `hookr-1-whole-pot`), with
+         * the release's constructor arguments. Its HookrRecapture pays a round's winner the whole pot and lets a pool put
+         * up to all of its arb recapture share in the pot. Same ABI as the release's Rules.
+         */
+        "whole-pot": Object.freeze({
+            name: "whole-pot",
+            rules: "0x10f684361b35C8411a2c07F68A6fB1F4B7e555F7",
+            rulesRuntimeHash: "0x3ffac05e248f81ad3843949052af1c0c6343179f0ec591bae3e271e249c7d879",
+            recapture: "0x60Efc4a41498e9433be2155b6cc1677AEC31D649",
+            recaptureRuntimeHash: "0xdc89f3eb02ff5bfbc07ac078e4f1d1de215ec253bc7ba843962e0b6cd11445c4",
+        }),
+        /**
+         * HookrRulesWalletCap v2, deployed 2026-10-12 beside the release (CREATE3 from the release deployer, release id
+         * `hookr-1-wallet-cap-v2`) with the release's constructor arguments, and admitted on HookrRoot with the release
+         * Rules' terms. The whole-pot Rules plus a per-wallet buy cap while a pool's launch guard lasts: it binds only a
+         * pool with a cap and a guard, and answers `extsload` (`wallet-cap.ts`). Its HookrRecapture is the whole-pot one's
+         * source, so its runtime, which keeps its own address, is its own. Same ABI as the release's Rules otherwise.
+         */
+        "wallet-cap": Object.freeze({
+            name: "wallet-cap",
+            rules: "0xb67b73E28C522a3AAC438bE970bf94976Deee52a",
+            rulesRuntimeHash: "0x0fed58ec91368b16ba4166acc65ddd9252529fb860834f81fdc5dab3179a6247",
+            recapture: "0xbbC43DC2f01F5E7882caCd78EF094A44eF0E4d23",
+            recaptureRuntimeHash: "0x04001c31836049074c926cf6519ecf999c18267229fe6a05df26685caadb0984",
+        }),
+        /**
+         * HookrRulesRoundTrip, deployed beside the release (CREATE3 from the release deployer, release id `hookr-1`) and
+         * admitted on HookrRoot with the release Rules' terms at block 82,372,631. Rules that keep a record of who traded
+         * in each block, which Buy/Sell Block's round-trip check reads. Same ABI as the release's Rules otherwise.
+         */
+        "round-trip": Object.freeze({
+            name: "round-trip",
+            rules: "0x3d7e31746127FD9a14d3C7fC12E73611D2e8cb34",
+            rulesRuntimeHash: "0x925797125cde5723bfa57ac04238e847ac0098a2821e6703fd4d5e20881a322b",
+            recapture: "0xddFF6326E5CB9AA98b88e9064d9A9570f777f8A3",
+            recaptureRuntimeHash: "0x7e8e752507e29441d26bec6646cd57598e63825ab888cf166da27cf9a5a31e5e",
+        }),
+    }),
+    contracts: Object.freeze({
+        HookrRegistryChecks: "0xB9F5c54E5Cc7ac6c7a96335E5A334Cf4eA496E98",
+        HookrRegistryAdmin: "0x675ac2102E8c69E2467F64656E3c235AF3901Ac1",
+        HookrRegistry: "0x463c82beA1a52F4Cc05ca0741a24F0AD24bA4602",
+        HookrTreasury: "0x2242F7FC75606500503075f29ea8cDA684EfB4a9",
+        HookrForwarder: "0xe7863CC0E2Fb783b44c279aB159bcD812c2ceA1c",
+        HookrRouter: "0xC2Bc9a3fe6c4Ce8C2F7EB4655b0869b01D8c93C9",
+        HookrQuoter: "0x445D7891381Aa7F91F5048EdBC6a611ccBDe7865",
+        HookrLaunchChecks: "0x8567369a70100828611BB6F44ec051B48F10fb59",
+        HookrTokenDeployer: "0x1B23D6d7beBcB61E39317E9F0Bc02AEB91aFCcAe",
+        HookrLauncher: "0x1cf2748A6670572425eAbf9Ab9e5BC4eb2eB8Ef4",
+        HookrReferralRegistry: "0xefD1DfBA80c06E72F793601706c3a1c71aab3057",
+        HookrProgramsAdmin: "0x40B40D65543E70a9C757eda1A2208517a8BC7292",
+        HookrPrograms: "0x9fA204AC99176782Fd20615b2b2A516D1F8C328F",
+        HookrMilestoneNFTFactory: "0xa340F964F1E685c681dC3ABB5B0405E608914d00",
+        HookrProgramValidator: "0x33e0249083Be7Cd8bD2fe175E0671AcfD0516850",
+        HookrReferralDistributor: "0x690539c53212899A9c6AEEE3b4B6737A5c4851d9",
+        HookrRoot: "0x89c9FB50d1f03192230FFB1c279BB6E7d3Fe6aCc",
+        HookrLane: "0x9A8a1006469BA196f8FEfc017a53505C83A060BB",
+        HookrRules: "0x4a71c270b1520F94064268102AebD744b0DE7942",
+        HookrRecapture: "0xF83569E564d70daebc35950f66a73f2e2B915583",
+        HookrFamilyRouter: "0x854f3Fa7AC342B244DF0d9A8c8F597b051aAE559",
+        HookrFamilyLock: "0xfAFEcE64099C1E791C4B46189c277f00c0c7e00b",
+        HookrCompliance: "0x9D205e8a68464761A9d84bdeCcEa0C3CB1e7B1EC",
+        HookrComplianceGuard: "0x6CD70db1ac99344416a6fD7184e23FA8f09f313A",
+        HookrAccountCalls: "0x0579a95A7760070E2d6D34e5beCe571e5F1c4818",
+        HookrPaymasterAdmin: "0x1d81F4B131832f741392edf7B91b4CF099FbB008",
+        HookrPaymaster: "0x1c4682915092E742231ea038C4fcA61e96a83c99",
+        HookrRootFactory: "0x21E438FaBE10770afb4407cF6b09d32369CBdCE4",
+        HookrSessionAdvisory: "0x78Bc6b7302Dda8632e661c8d74966bdBea1c66b1",
+        HookrFeeAdvisory: "0x3B6b3f00684987B831fcF9EB5f0d5B806afF7306",
+        HookrLiquidityVault: "0xA408923EF811945Ef119Bc700B1950Dab65467Fc",
+        HookrOwnedProfiles: "0xb46c318B6AEA2d6274f5566da414b09fDa6CC325",
+        HookrOwnedRootsLens: "0x6Bb5c9d21dD095F788cb8373d0143429ad277366",
+        HookrOwnedRootFactory: "0xA6c2a401597301dFf57A59bC8F70a9622499f3ec",
+        HookrLpBoost: "0x52536F5F4E5BC7cEA2197c8F1BB49bf2B133E7f1",
+    }),
+});
+/**
+ * The canary: the same contracts at their own addresses, deployed and proven before production. Not for users.
+ * @internal
+ */
+export const CANARY_HOOKR_1_A = Object.freeze({
+    releaseId: "canary-hookr-1-a",
+    canary: true,
+    chainId: CHAIN_ID,
+    deployment: frozen(DEPLOYMENTS["canary-hookr-1-a"]),
+    rulesModules: Object.freeze({
+        standard: Object.freeze({
+            name: "standard",
+            rules: "0x8Ef8869CD47d9928d563001F1d38D65c3c3e01Ab",
+            rulesRuntimeHash: "0x7e51ac228eafdaa7f2b3c45f2fec6ec9c872f81ce0258c1a2da95090883b30a5",
+            recapture: "0xe7035c0d8523a5eE9Fc5Ba5Ec97a4f1D771a6F87",
+            recaptureRuntimeHash: "0x54aa061f121e798029af86b9b700433fec566cdb570578e4e57a69865d6095a6",
+        }),
+    }),
+    contracts: Object.freeze({
+        HookrRegistryChecks: "0x4598d64B6c5730813a469e4B36cf379DbfB24118",
+        HookrRegistryAdmin: "0x57252DB7C9ed51213a324A2160934Ee2f840d6E8",
+        HookrRegistry: "0x91eDc45319B66dc4f168BcF7B957e8f753771834",
+        HookrTreasury: "0x3cA2926E5971Cda3E3667e9A6835b2cDfF8DD836",
+        HookrForwarder: "0xDd3407eB6DbFF4a3Cb6258923C35F3e306C86320",
+        HookrRouter: "0x3b6848A557F5Aedc18EbE5f3E5b6EafB4F46f6F9",
+        HookrQuoter: "0xc324D74339763E8b12709092a2c9d8f04CD02c88",
+        HookrLaunchChecks: "0xa22BF1F6a8709441Fc7af410891204454Ed24026",
+        HookrTokenDeployer: "0x85b6B07688Da8089F4191439dbFC315a4757DB0F",
+        HookrLauncher: "0x064a2b59f7c3d70ECdC0009be30Eb464110Ae787",
+        HookrReferralRegistry: "0x8EC0AE84b21BF2dD187ED390dbDA7A967ECfC5dD",
+        HookrProgramsAdmin: "0x2Bec6C3bEB51c062C0Ef59ddC67237354E86BeF1",
+        HookrPrograms: "0x3A11ea03e1B6c6750dEF8A5fBb41bd4c3d0C3d97",
+        HookrMilestoneNFTFactory: "0xFeE0AbA75f9C0A23bB5AB686314a5112dfe3f0b2",
+        HookrProgramValidator: "0xA6883F0424FA4Ec11E0591Aa14A26be957EE863A",
+        HookrReferralDistributor: "0x9ab480d01e89F9d9A1D1e3cd8433DCbC825BA4cC",
+        HookrRoot: "0x4C0904bfbdaEC6AA847C36BBf395E5f61325eacc",
+        HookrLane: "0x3ba186E41b83ABd4E91a2a72c2fF3BAF8f88003C",
+        HookrRules: "0x8Ef8869CD47d9928d563001F1d38D65c3c3e01Ab",
+        HookrRecapture: "0xe7035c0d8523a5eE9Fc5Ba5Ec97a4f1D771a6F87",
+        HookrFamilyRouter: "0xD6F31D46D06d4Aa91e937407369a369D1DB9C684",
+        HookrFamilyLock: "0xC39144589aC7336eFC9baB9d7608c7B014Fe757e",
+        HookrCompliance: "0xed326114d79b8bf64f00585fF3Ca1D5C01693649",
+        HookrComplianceGuard: "0xB6a3d34513020458fBC80D71F5753fC41a863CE5",
+        HookrAccountCalls: "0xdd706C93179730cFE73b8c1627bEc6103e51E3a3",
+        HookrPaymasterAdmin: "0x7a44B8E11097c4B801bcf195EF09295882538bF3",
+        HookrPaymaster: "0x1Bf7C2e0755b8776C04f21208Ea4CF29A0942866",
+        HookrRootFactory: "0x2B2fF011b4A3854b7796e86307736AEB558C80C7",
+        HookrSessionAdvisory: "0x6fE7e2244257664e4658FEcB308Cf374e6c83Af1",
+        HookrFeeAdvisory: "0x02B13627a634dfebBb864389cDb3E4D6945e80Ac",
+        HookrLiquidityVault: "0x67E93f59E3fD78e7976960aBce835E27c63Aa8c9",
+        HookrOwnedProfiles: "0xeCeD7a6D923Dc5C0c49B0a8c5089f372C6c40244",
+        HookrOwnedRootsLens: "0x76f0F2a48C154c8261110a4c13cdc5d4437A0631",
+        HookrOwnedRootFactory: "0xEFD7bE480bbA7e3b14dbA0878F34AB436bC08ff8",
+        HookrLpBoost: "0xe06dac9dea02424fAd01CEE10feA0ce5517765A9",
+    }),
+});
+/** Both releases by release id. */
+export const RELEASES = Object.freeze({
+    "hookr-1": HOOKR_1,
+    "canary-hookr-1-a": CANARY_HOOKR_1_A,
+});
+/** The contract each manifest role pins, in the order the manifest lists them. */
+export const MANIFEST_ROLES = Object.freeze({
+    poolManager: "PoolManager",
+    registry: "HookrRegistry",
+    root: "HookrRoot",
+    rules: "HookrRules",
+    router: "HookrRouter",
+    quoter: "HookrQuoter",
+    launcher: "HookrLauncher",
+    treasury: "HookrTreasury",
+    programs: "HookrPrograms",
+    referrals: "HookrReferralRegistry",
+    commissions: "HookrReferralDistributor",
+    forwarder: "HookrForwarder",
+    rootFactory: "HookrRootFactory",
+    feeAdvisory: "HookrFeeAdvisory",
+    sessionAdvisory: "HookrSessionAdvisory",
+    liquidityVault: "HookrLiquidityVault",
+});
+/** The address a manifest role pins in a release. */
+export function releaseAddress(release, role) {
+    const name = MANIFEST_ROLES[role];
+    if (!name)
+        throw new Error(`No ${role} in ${release.releaseId}`);
+    return name === "PoolManager" ? POOL_MANAGER : release.contracts[name];
+}
+/** What a version of this package made before the release was verified tells a caller. */
+function noDeployment(release) {
+    return new Error(`This version of hookr-sdk has no deployment for ${release.releaseId}: pass its startBlock and evidenceHash`);
+}
+/**
+ * The DeploymentManifest the builders take for a release: every role at its fixed address with its runtime hash, from
+ * the release's own deployment unless one is given, then each further Rules module (`otherRulesModules`) as one more
+ * `rules` pin with its own runtime hash, so the builders that name a Rules accept it. It makes no reads. Refuses a role
+ * without a runtime hash, and anything `deployment()` refuses.
+ *
+ * It is the builders' manifest. Its release id is the release's, `hookr-1`, so it is not the manifest a Hookr service
+ * publishes: `HookrClient` takes the release id and manifest hash the service names.
+ */
+export function releaseManifest(release, d = release.deployment) {
+    if (!d)
+        throw noDeployment(release);
+    const contracts = Object.keys(MANIFEST_ROLES).map((role) => {
+        const runtimeHash = d.runtimeHashes[role];
+        if (!runtimeHash)
+            throw new Error(`No runtime hash for ${role}`);
+        return {
+            role,
+            address: releaseAddress(release, role).toLowerCase(),
+            runtimeHash,
+            startBlock: d.startBlock,
+        };
+    });
+    for (const m of otherRulesModules(release))
+        contracts.push({ role: "rules", address: m.rules.toLowerCase(), runtimeHash: m.rulesRuntimeHash, startBlock: d.startBlock });
+    return deployment({
+        schema: "hookr.engagement.sources.v1",
+        releaseId: release.releaseId,
+        chainId: String(release.chainId),
+        startBlock: d.startBlock,
+        parentHash: d.parentHash,
+        contracts,
+        qualification: { status: "verified", evidenceHash: d.evidenceHash, sourceCommit: RELEASE_SOURCE_COMMIT },
+    });
+}
+/** The release's Rules modules other than its own HookrRules: on `hookr-1`, the whole-pot, Wallet Cap and round-trip Rules. */
+export function otherRulesModules(release) {
+    return Object.values(release.rulesModules).filter((m) => m !== undefined && m.rules.toLowerCase() !== release.contracts.HookrRules.toLowerCase());
+}
+/** The release's Rules module `name`, or an error for a release without it (the canary has only `standard`). */
+export function rulesModule(release, name) {
+    const m = release.rulesModules[name];
+    if (!m)
+        throw new Error(`${release.releaseId} has no ${name} Rules`);
+    return m;
+}
+/**
+ * `releaseManifest` with each role's runtime hash and the start block's hash read from chain. Refuses a role with no
+ * code: the release is not deployed, or not on this chain. Where the release carries its deployment, it also refuses
+ * a role whose code is not the release's, and a start block whose hash is not the release's. It always refuses a
+ * further Rules module whose code is not the one the release pins for it.
+ */
+export async function readReleaseManifest(client, release, options = {}) {
+    const pinned = release.deployment;
+    const startBlock = options.startBlock ?? (pinned ? BigInt(pinned.startBlock) : undefined);
+    const evidenceHash = options.evidenceHash ?? pinned?.evidenceHash;
+    if (startBlock === undefined || evidenceHash === undefined)
+        throw noDeployment(release);
+    const roles = Object.keys(MANIFEST_ROLES);
+    const modules = otherRulesModules(release);
+    const [block, codes, moduleCodes] = await Promise.all([
+        client.getBlock({ blockNumber: startBlock }),
+        Promise.all(roles.map((role) => client.getCode({ address: releaseAddress(release, role), blockNumber: options.blockNumber }))),
+        Promise.all(modules.map((m) => client.getCode({ address: m.rules, blockNumber: options.blockNumber }))),
+    ]);
+    if (!block.hash)
+        throw new Error(`Block ${startBlock} has no hash yet`);
+    const pinnedStart = pinned && startBlock === BigInt(pinned.startBlock);
+    if (pinnedStart && block.hash.toLowerCase() !== pinned.parentHash.toLowerCase())
+        throw new Error(`Block ${startBlock} is not ${release.releaseId}'s start block on this chain`);
+    const runtimeHashes = {};
+    roles.forEach((role, i) => {
+        const code = codes[i];
+        if (!code || code === "0x")
+            throw new Error(`No code at ${role} ${releaseAddress(release, role)}`);
+        const runtimeHash = keccak256(code);
+        const expected = pinned?.runtimeHashes[role];
+        if (expected && runtimeHash !== expected.toLowerCase())
+            throw new Error(`${role} ${releaseAddress(release, role)} does not run ${release.releaseId}'s code`);
+        runtimeHashes[role] = runtimeHash;
+    });
+    modules.forEach((m, i) => {
+        const code = moduleCodes[i];
+        if (!code || code === "0x")
+            throw new Error(`No code at the ${m.name} Rules ${m.rules}`);
+        if (keccak256(code) !== m.rulesRuntimeHash.toLowerCase())
+            throw new Error(`The ${m.name} Rules ${m.rules} do not run the code ${release.releaseId} pins for them`);
+    });
+    return releaseManifest(release, {
+        startBlock: startBlock.toString(),
+        parentHash: block.hash,
+        runtimeHashes,
+        evidenceHash,
+    });
+}
+/**
+ * The gas floor a swap on an arb recapture pool must carry while its lane is on: `2 × gasCap + gasCap / 63 + 755,000`
+ * (HookrLane), the `gasFloor` `laneOf(id)` returns. At the 3,000,000 cap the lane opens with it is 6,802,619. A swap
+ * sent with less reverts `InsufficientLaneGas`. The swap's own gas comes on top: a buy on a live lane pool estimates at
+ * about 7.5 million, so a fixed limit on such a pool should be at least 8,800,000, the estimate plus a sixth.
+ */
+export function laneGasFloor(gasCap) {
+    const cap = BigInt(gasCap);
+    if (cap <= 0n)
+        return 0n;
+    return 2n * cap + cap / 63n + 755000n;
+}
+/**
+ * The block number the contracts read as `block.number`: on Robinhood Chain, an Arbitrum Orbit chain, it is the parent
+ * chain's (Ethereum's), which each block carries as `l1BlockNumber`, about one every 12 seconds. Anti-Snipe's launch
+ * guard (`guardEndBlock`), and Wallet Cap with it, counts these blocks, so pass this as a launch's `blockNumber`.
+ * `getBlockNumber()` is the chain's own, far larger number: a guard counted from it is one the Rules refuse at bind.
+ */
+export async function readParentBlockNumber(client) {
+    const { l1BlockNumber } = ((await client.getBlock({ blockTag: "latest" })) ?? {});
+    if (typeof l1BlockNumber === "bigint" && l1BlockNumber > 0n)
+        return l1BlockNumber;
+    if (typeof l1BlockNumber === "string" && /^0x0*[1-9a-fA-F][0-9a-fA-F]*$/.test(l1BlockNumber))
+        return BigInt(l1BlockNumber);
+    throw new Error("The latest block carries no l1BlockNumber: read it from Robinhood Chain's own RPC");
+}

package/dist/wallet-cap.d.ts

@@ -0,0 +1,159 @@
+/**
+ * Wallet Cap: HookrRulesWalletCap (`rulesModule(HOOKR_1, "wallet-cap")`), the whole-pot Rules with a per-wallet buy
+ * cap on each launch while its pools' launch guards last.
+ *
+ * - The cap rides in `RulesConfig.potMinBuyQuote`, in the token's raw units: the most of it one wallet may buy while the
+ *   pool's guard lasts. These Rules bind only a pool with a cap and a launch guard (`guardEndBlock` within the next
+ *   100,000 parent blocks), and `potEveryNBuys` stays zero. Every other Rules refuses a nonzero `potMinBuyQuote`, as the
+ *   core's `checkRulesConfig` does.
+ * - Each guarded buy counts what it delivers (the pool's output less Auto Burn) against its wallet: the payer
+ *   HookrRouter, the forwarder, the family router or the curated Uniswap router names, or for a swap through a router
+ *   that names none, the transaction's signer. Counts are per token and per launch: the pools of one launch share
+ *   `Bound.launchedAt`, the second they bound, and a later launch of the token counts from zero, so every pool of a
+ *   launch takes the same cap, and arb recapture on every pool or none (`checkWalletCapLaunch`). A sell frees no room.
+ *   The creator's dev buy and the pool's own arb recapture executor are not counted. A buy past the cap reverts
+ *   `GuardWalletLimit(wallet, actual, limit)`. After the guard nothing is counted or capped.
+ * - The Rules answer `extsload(bytes32)`, one word of their storage, and `readWalletCap` reads through it.
+ */
+import { type Hex } from "viem";
+import { type Address, type Admission, type Caps, type Hash, type ParamContext, type PoolTerms, type RootAdvisoryKind, type RulesConfig, type RulesContext, type RulesLaunch } from "./core/index.js";
+import { type HookrRelease } from "./releases.js";
+/**
+ * What HookrRulesWalletCap adds to the release Rules' ABI (`rulesAbi`): `extsload`, one word of its storage as Uniswap
+ * v4's Extsload reads it, and the refusal of a buy that would take a wallet past its pool's cap.
+ */
+export declare const WALLET_CAP_ABI: readonly [{
+    readonly type: "function";
+    readonly name: "extsload";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [{
+        readonly name: "slot";
+        readonly type: "bytes32";
+        readonly internalType: "bytes32";
+    }];
+    readonly outputs: readonly [{
+        readonly name: "value";
+        readonly type: "bytes32";
+        readonly internalType: "bytes32";
+    }];
+}, {
+    readonly type: "error";
+    readonly name: "GuardWalletLimit";
+    readonly inputs: readonly [{
+        readonly name: "wallet";
+        readonly type: "address";
+        readonly internalType: "address";
+    }, {
+        readonly name: "actual";
+        readonly type: "uint256";
+        readonly internalType: "uint256";
+    }, {
+        readonly name: "limit";
+        readonly type: "uint256";
+        readonly internalType: "uint256";
+    }];
+}];
+/** erc7201:hookr.rules, every HookrRules' State: keccak256(abi.encode(uint256(keccak256("hookr.rules")) - 1)) & ~0xff. */
+export declare const RULES_SLOT = 53445494162334802764660739626191472437579742535980357254313114366502610401536n;
+/**
+ * The slot of a pool's first Bound word, `State.pools[poolId]`: keccak256(abi.encode(poolId, RULES_SLOT)). Its launch
+ * guard's end is in the next slot (`uint40` of the word) and its cap two slots on (the top 128 bits).
+ */
+export declare function walletCapPoolSlot(poolId: Hash): Hash;
+/** The slot of `wallet`'s count of `subject` on launch `launch`, `State.bought[subject][launch][wallet]`. */
+export declare function walletCapBoughtSlot(subject: Address, launch: number | bigint, wallet: Address): Hash;
+/**
+ * The launch in a pool's first Bound word: its top 32 bits, `Bound.launchedAt`. The word packs, low to high,
+ * baseFeePips (24 bits), tickSpacing (16), bound (8), quoteIsCurrency0 (8), terms (8), liquidityOwner (160) and
+ * launchedAt (32). Null for anything but 32 bytes of hex with the bound flag set: a pool these Rules never bound.
+ */
+export declare function walletCapLaunch(value: Hex): number | null;
+/**
+ * A pool's cap, in the token's raw units, for a share of `supply` (raw units) in basis points: the floor of
+ * supply × bps / 10,000, so 200 bps of a supply of 10^27 is 2 × 10^25. It goes in the pool's `rules.potMinBuyQuote`.
+ * Refuses a share outside 1 to 10,000 bps and a cap that rounds to zero. hookr.fun offers 0.1% to 10%, 2% by default.
+ */
+export declare function walletCapAmount(supply: bigint, bps: number | bigint): bigint;
+/** What a wallet may still buy while the guard lasts: the cap less what it bought, never below zero. */
+export declare function walletCapRoom(cap: bigint, bought: bigint): bigint;
+/**
+ * Refuses a RulesConfig HookrRulesWalletCap's bind would refuse and returns its fee ceilings: `checkRulesConfig` with
+ * the cap set aside, plus the Wallet Cap Rules' own terms: a cap above zero in `potMinBuyQuote` (below 2^128), and a
+ * launch guard, with its liquidity owner, ending within 100,000 parent blocks after `ctx.blockNumber`, which is required
+ * here. `potEveryNBuys` stays zero. Every other Rules refuses a cap: check those with `checkRulesConfig`.
+ */
+export declare function checkWalletCapRulesConfig(c: RulesConfig, ctx: RulesContext): Caps;
+/**
+ * `rulesPoolTerms` for a launch member on the Wallet Cap Rules: every check `checkWalletCapRulesConfig` makes, the
+ * pool's caps and gas limits from the Rules' admission (`admission(HookrRoot, rulesModule(HOOKR_1, "wallet-cap").rules)`
+ * on the registry), and its `rulesData` with the cap. Refuses the admission of any other Rules. The member binds these
+ * Rules as `config.rules` and `l.rules`, cap included, as `rules`; every pool of the launch takes the same cap.
+ */
+export declare function walletCapPoolTerms(l: RulesLaunch, ctx: ParamContext & {
+    liquidityOwner?: Address;
+}, rulesAdmission: Admission, advisory?: {
+    admission: Admission;
+    kind: RootAdvisoryKind;
+    phases?: number;
+}, release?: HookrRelease): PoolTerms;
+/**
+ * Refuses a launch whose members (`buildLaunch`'s) Wallet Cap would leave a way round, or turn against traders, though
+ * the Rules bind each pool alone: some pools on the Wallet Cap Rules and some not, capped pools with different caps (a
+ * wallet could then buy the largest), or capped pools some with arb recapture and some without (on a capped pool
+ * without the lane, the executor's legs count against the trader whose swap set them off). Passes a launch without it.
+ */
+export declare function checkWalletCapLaunch(members: readonly Record<string, unknown>[], release?: HookrRelease): void;
+/** The read `readWalletCap` makes: an `eth_call`. A viem PublicClient has it. */
+export interface WalletCapReader {
+    call(args: {
+        to: Address;
+        data: Hex;
+        blockNumber?: bigint;
+    }): Promise<{
+        data?: Hex;
+    }>;
+}
+/** Which pool, and optionally which wallet, `readWalletCap` reads. */
+export interface WalletCapQuery {
+    /** The pool's PoolId (`poolId(key)`). */
+    poolId: Hash;
+    /** The wallet whose count and room to read. */
+    wallet?: Address;
+    /** The pool's token, with `wallet`: counts are per token. */
+    subject?: Address;
+    /** The block to read at. Defaults to the latest. */
+    blockNumber?: bigint;
+}
+/** A pool's wallet cap as its Rules hold it, and a wallet's count against it. */
+export interface WalletCap {
+    /** The pool's launch: `Bound.launchedAt`, the second its launch bound it, which the launch's pools share. */
+    launch: number;
+    /** The parent block the pool's launch guard, and the cap with it, ends at (`readParentBlockNumber` reads the clock). */
+    guardEndBlock: bigint;
+    /** The most of the token, in raw units, one wallet may buy across the launch's pools while the guard lasts. */
+    cap: bigint;
+    /** What the wallet bought across the launch's pools while their guards lasted, or null without a wallet. */
+    bought: bigint | null;
+    /** What the wallet may still buy before the guard ends (`walletCapRoom`), or null without a wallet. */
+    room: bigint | null;
+}
+/**
+ * Reads a pool on the Wallet Cap Rules through their `extsload`: its launch, guard end and cap from its Bound
+ * (`walletCapPoolSlot` and the two slots after it), then, with a wallet, that wallet's count on the launch
+ * (`walletCapBoughtSlot`) and its room. Null for a pool these Rules have not bound: a pool on any other Rules has no
+ * wallet cap. A count and its room hold while the guard lasts; after it nothing is counted or capped.
+ */
+export declare function readWalletCap(client: WalletCapReader, query: WalletCapQuery, release?: HookrRelease): Promise<WalletCap | null>;
+/** A buy Wallet Cap refused: the wallet it counted, the total the buy would have brought it to, and the cap. */
+export interface WalletCapRefusal {
+    wallet: Address;
+    actual: bigint;
+    limit: bigint;
+}
+/**
+ * The GuardWalletLimit inside a failed quote, swap or launch, however the root, the lane, the PoolManager and the quoter
+ * wrapped it, or null. Takes the revert data, or the viem error that carries it.
+ */
+export declare function walletCapRefusal(error: unknown): WalletCapRefusal | null;
+/** Names Wallet Cap's refusal in `error` (revert data, or the viem error that carries it), or null. */
+export declare function walletCapRevert(error: unknown): string | null;