hookr-sdk 0.2.1 → 1.1.0

package/dist/wallet-cap.js

@@ -0,0 +1,234 @@
+/**
+ * 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 { BaseError, decodeErrorResult, encodeAbiParameters, encodeFunctionData, getAddress, keccak256, numberToHex, parseAbi, } from "viem";
+import { address, assert, checkRulesConfig, encodeRulesData, hash, rulesKnobsOf, rulesPoolTerms, uint, } from "./core/index.js";
+import { HOOKR_1, rulesModule } 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 const WALLET_CAP_ABI = [
+    {
+        type: "function",
+        name: "extsload",
+        stateMutability: "view",
+        inputs: [{ name: "slot", type: "bytes32", internalType: "bytes32" }],
+        outputs: [{ name: "value", type: "bytes32", internalType: "bytes32" }],
+    },
+    {
+        type: "error",
+        name: "GuardWalletLimit",
+        inputs: [
+            { name: "wallet", type: "address", internalType: "address" },
+            { name: "actual", type: "uint256", internalType: "uint256" },
+            { name: "limit", type: "uint256", internalType: "uint256" },
+        ],
+    },
+];
+/** erc7201:hookr.rules, every HookrRules' State: keccak256(abi.encode(uint256(keccak256("hookr.rules")) - 1)) & ~0xff. */
+export const RULES_SLOT = 0x762913e4bc0f59f7b08c82f07586fa48932548ab5fab99e6db0b09765b4ff900n;
+/** `State.bought`, the State's fourteenth field: what each wallet bought, per subject and launch. */
+const BOUGHT = RULES_SLOT + 13n;
+/** A slot as `extsload` takes it: 32 bytes, wrapping as the EVM's slot arithmetic does. */
+const word = (n) => numberToHex(n & ((1n << 256n) - 1n), { size: 32 });
+/** The slot of `key` in the mapping at `slot`: keccak256(abi.encode(key, slot)). */
+const mapping = (keyType, key, slot) => BigInt(keccak256(encodeAbiParameters([{ type: keyType }, { type: "uint256" }], [key, slot])));
+/**
+ * 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 function walletCapPoolSlot(poolId) {
+    return word(mapping("bytes32", hash(poolId), RULES_SLOT));
+}
+/** The slot of `wallet`'s count of `subject` on launch `launch`, `State.bought[subject][launch][wallet]`. */
+export function walletCapBoughtSlot(subject, launch, wallet) {
+    const bySubject = mapping("address", address(subject), BOUGHT);
+    return word(mapping("address", address(wallet), mapping("uint256", uint(BigInt(launch), 32), bySubject)));
+}
+/**
+ * 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 function walletCapLaunch(value) {
+    if (typeof value !== "string" || !/^0x[0-9a-fA-F]{64}$/.test(value))
+        return null;
+    const w = BigInt(value);
+    return ((w >> 40n) & 0xffn) === 1n ? Number(w >> 224n) : 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 function walletCapAmount(supply, bps) {
+    assert(typeof supply === "bigint" && supply > 0n, "Wallet Cap needs the token's supply in raw units");
+    const share = BigInt(bps);
+    assert(share >= 1n && share <= 10000n, `Wallet Cap share ${share} bps outside 1 to 10,000`);
+    const cap = (supply * share) / 10000n;
+    assert(cap > 0n, "Wallet Cap's share of this supply rounds to zero tokens");
+    return uint(cap, 128);
+}
+/** What a wallet may still buy while the guard lasts: the cap less what it bought, never below zero. */
+export function walletCapRoom(cap, bought) {
+    return bought >= cap ? 0n : cap - bought;
+}
+/** The terms only the Wallet Cap Rules hold a pool to, and the parent block to check its guard against. */
+function walletCapTerms(c, blockNumber) {
+    assert(typeof c.potMinBuyQuote === "bigint" && c.potMinBuyQuote > 0n, "Wallet Cap needs its cap in potMinBuyQuote: the most of the token, in raw units, one wallet may buy during the guard");
+    uint(c.potMinBuyQuote, 128);
+    assert(c.guardEndBlock !== 0, "Wallet Cap lasts as long as the launch guard: set guardEndBlock");
+    assert(blockNumber !== undefined, "Wallet Cap needs blockNumber, the parent block the launch lands in (readParentBlockNumber), to check its guard");
+}
+/**
+ * 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 function checkWalletCapRulesConfig(c, ctx) {
+    walletCapTerms(c, ctx.blockNumber);
+    return checkRulesConfig({ ...c, potMinBuyQuote: 0n }, ctx);
+}
+/**
+ * `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 function walletCapPoolTerms(l, ctx, rulesAdmission, advisory, release = HOOKR_1) {
+    const m = rulesModule(release, "wallet-cap");
+    assert(address(rulesAdmission.implementation, true) === address(m.rules) && hash(rulesAdmission.codeHash) === hash(m.rulesRuntimeHash), `Not the admission of ${release.releaseId}'s Wallet Cap Rules ${m.rules}`);
+    walletCapTerms(l.rules, ctx.blockNumber);
+    const terms = rulesPoolTerms({ ...l, rules: { ...l.rules, potMinBuyQuote: 0n } }, ctx, rulesAdmission, advisory);
+    return { ...terms, rulesData: encodeRulesData(l.rules, rulesKnobsOf(l)) };
+}
+/**
+ * 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 function checkWalletCapLaunch(members, release = HOOKR_1) {
+    const pin = release.rulesModules["wallet-cap"];
+    const field = (member, part, key) => member[part]?.[key];
+    const capped = (member) => {
+        const rules = field(member, "config", "rules");
+        return pin !== undefined && typeof rules === "string" && rules.toLowerCase() === pin.rules.toLowerCase();
+    };
+    if (!members.some(capped))
+        return;
+    assert(members.every(capped), "Wallet Cap counts a wallet's buys across the launch's pools: every pool binds its Rules, or none does");
+    const caps = new Set(members.map((m) => field(m, "rules", "potMinBuyQuote")));
+    const [cap] = caps;
+    assert(caps.size === 1 && typeof cap === "bigint" && cap > 0n, "Every pool of a Wallet Cap launch takes the same cap, above zero");
+    assert(new Set(members.map((m) => field(m, "recapture", "on") === true)).size === 1, "In a Wallet Cap launch every pool takes arb recapture, or none does");
+}
+/**
+ * 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 async function readWalletCap(client, query, release = HOOKR_1) {
+    assert((query.wallet === undefined) === (query.subject === undefined), "A wallet's count needs the pool's subject");
+    const rules = rulesModule(release, "wallet-cap").rules;
+    const at = query.blockNumber === undefined ? {} : { blockNumber: query.blockNumber };
+    const read = async (slot) => {
+        const data = encodeFunctionData({ abi: WALLET_CAP_ABI, functionName: "extsload", args: [word(slot)] });
+        const answer = (await client.call({ to: rules, data, ...at })).data;
+        assert(typeof answer === "string" && /^0x[0-9a-fA-F]{64}$/.test(answer), `The Wallet Cap Rules ${rules} answered extsload with ${answer}`);
+        return answer;
+    };
+    const pool = BigInt(walletCapPoolSlot(query.poolId));
+    const [first, second, third] = await Promise.all([read(pool), read(pool + 1n), read(pool + 2n)]);
+    const launch = walletCapLaunch(first);
+    if (launch === null)
+        return null;
+    const cap = BigInt(third) >> 128n;
+    assert(cap > 0n, `The Wallet Cap Rules ${rules} hold no cap for pool ${query.poolId}`);
+    const guardEndBlock = BigInt(second) & ((1n << 40n) - 1n);
+    if (query.wallet === undefined)
+        return { launch, guardEndBlock, cap, bought: null, room: null };
+    const bought = BigInt(await read(BigInt(walletCapBoughtSlot(query.subject, launch, query.wallet))));
+    return { launch, guardEndBlock, cap, bought, room: walletCapRoom(cap, bought) };
+}
+/**
+ * The errors a refusal can reach a caller inside: the root's and the lane's (a module's own revert), the PoolManager's
+ * (a hook's revert in a swap) and the quoter's (a quoted swap's revert).
+ */
+const REFUSAL_ABI = [
+    ...WALLET_CAP_ABI,
+    ...parseAbi([
+        "error ModuleCallReverted(address module, bytes4 callSelector, bytes reason)",
+        "error WrappedError(address target, bytes4 selector, bytes reason, bytes details)",
+        "error SimulationFailed(bytes reason)",
+    ]),
+];
+/** The most wrappers stripped from one revert, so a malformed one cannot recurse without end. */
+const MAX_WRAPS = 4;
+const hex = (value) => typeof value === "string" && /^0x([0-9a-fA-F]{2})+$/.test(value) ? value : null;
+/** Revert data: a hex string as given, or the data a viem error carries anywhere in its cause chain. */
+function revertData(error) {
+    if (typeof error === "string")
+        return hex(error);
+    for (let e = error, depth = 0; e !== null && typeof e === "object" && depth < 16; depth++) {
+        const { raw, data, cause } = e;
+        const found = hex(raw) ?? hex(data) ?? hex(data?.data);
+        if (found)
+            return found;
+        e = cause;
+    }
+    return null;
+}
+/**
+ * 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 function walletCapRefusal(error) {
+    let data = revertData(error);
+    for (let wraps = 0; data !== null && wraps <= MAX_WRAPS; wraps++) {
+        let e;
+        try {
+            e = decodeErrorResult({ abi: REFUSAL_ABI, data });
+        }
+        catch (caught) {
+            if (!(caught instanceof BaseError))
+                throw caught;
+            return null;
+        }
+        if (e.errorName === "GuardWalletLimit") {
+            const [wallet, actual, limit] = e.args;
+            return { wallet: getAddress(wallet), actual, limit };
+        }
+        if (e.errorName === "ModuleCallReverted" || e.errorName === "WrappedError")
+            data = hex(e.args[2]);
+        else if (e.errorName === "SimulationFailed")
+            data = hex(e.args[0]);
+        else
+            return null;
+    }
+    return null;
+}
+/** Names Wallet Cap's refusal in `error` (revert data, or the viem error that carries it), or null. */
+export function walletCapRevert(error) {
+    const r = walletCapRefusal(error);
+    return r
+        ? `The buy would bring ${r.wallet}'s buys of the subject during the launch guard to ${r.actual}, above the pool's wallet cap ${r.limit}`
+        : null;
+}

package/package.json

@@ -1,29 +1,65 @@
 {
   "name": "hookr-sdk",
-  "version": "0.2.1",
-  "description": "Build a market on Hookr's live root hooks, quote and swap through its router, read markets, and claim payouts.",
+  "version": "1.1.0",
+  "description": "Build on Hookr, the Uniswap v4 hook on Robinhood Chain: launch tokens with Hook Blocks, open pools, quote and swap.",
   "type": "module",
   "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/Hookr-fun/hookr"
-  },
+  "homepage": "https://hookr.fun/docs",
+  "keywords": [
+    "hookr",
+    "uniswap",
+    "uniswap-v4",
+    "v4-hooks",
+    "hooks",
+    "hook-blocks",
+    "token-launch",
+    "robinhood-chain",
+    "viem",
+    "sdk"
+  ],
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
-    }
+    },
+    "./package.json": "./package.json"
   },
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "files": [
     "dist",
-    "README.md"
+    "provenance.json",
+    "README.md",
+    "CHANGELOG.md",
+    "MIGRATING.md",
+    "LICENSE"
   ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=18.16"
+  },
+  "devEngines": {
+    "runtime": {
+      "name": "node",
+      "version": ">=22.18",
+      "onFail": "error"
+    }
+  },
   "peerDependencies": {
-    "viem": "^2"
+    "viem": "^2.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "24.3.0",
+    "typescript": "5.9.3",
+    "viem": "2.55.10"
   },
   "scripts": {
-    "build": "tsc -p tsconfig.json"
+    "build": "rm -rf dist && tsc -p tsconfig.build.json && node scripts/declarations.mjs",
+    "typecheck": "tsc -p tsconfig.json",
+    "test": "node --test test/*.test.ts",
+    "sync": "node scripts/sync-core.mjs",
+    "deployment": "node scripts/release-deployment.mjs",
+    "prepack": "npm run build",
+    "prepublishOnly": "node scripts/release-deployment.mjs --require hookr-1"
   }
 }

package/provenance.json

@@ -0,0 +1,31 @@
+{
+  "schema": "hookr-sdk.provenance.v1",
+  "algorithm": "sha256",
+  "source": {
+    "commit": "412960b37a631ce145d49fb4a1887f04a4d1fa74",
+    "path": "labs/hooks/hookr-phase-one/sdk/src",
+    "package": "@hookr/phase-one-sdk@0.1.0"
+  },
+  "packetDigest": "83962c12ff55df431612ffae8bfc66a30041eb310035cfc30eab1bb9bdc0e031",
+  "contractSources": "Verified on RobinScan at each contract's address: https://robin.etherscan.io",
+  "files": {
+    "abi.ts": "615359c9865eaa8b12ddde68f3e115bcf4cc922c2ba9578cd4c4ba9c0836d416",
+    "advisories.ts": "2fd12057ddb8c8527c19438574366ca9b15a48183b841d56d44e38506b823ded",
+    "client.ts": "78c386458e747e9c520926e3c22c33292a4ef0ae26dfcf4b671ccd7302e19328",
+    "generated.ts": "2fa220f53b64b85cb8fd7b34e06dd3a346027b6d8aa4e93835f69f92697a0fe7",
+    "index.ts": "5789edae589547442a6529111dd8c2e02d6a8791784f6da45c96e189567b3059",
+    "launch.ts": "dffb0d1321a30f68d4510dc30523599ae28b9a30f6df9880366e149974555268",
+    "pair.ts": "1b3f3f2d3dbf6a3e69655c9d35324e5f656ab64b2d7b846c7621dd6a4ca4e43d",
+    "params.ts": "5fa75b9ede3bbb20d4b48f2b907220f9b832b05977c3aeefa5b69d0169f85521",
+    "policies.ts": "07411d29d46f7175ff77624242cabcf4d3a235a287507f3d83a0df4a06985410",
+    "proofs.ts": "81f1f4a0f2c267b8a2b7897ecd4847fb8791f512f8babc51f1c8976d9d047bb8",
+    "quotes.ts": "c3483a97ca247533cc5ef9d5648b43df591d47db3c434e8f8ff6b634b44359c3",
+    "referrals.ts": "9426b5a128ddff1c9f7b54e483a81a30458dea04c7d40adff8d1e4084f048987",
+    "registry.ts": "fec429bc5b7bd91a83124d46055171269ded20678c185ad3e40d7d5e1153cee8",
+    "rules.ts": "d34b23187424756293b06815c6ee31dc772c87f2ae1cbba63f966148ece64543",
+    "schema.ts": "caa6caa9f15ae9a597bf8b2a2d098ef40780b8b6410a3a72a4f2be62b84c98e5",
+    "stocks.generated.ts": "8809cd3b82612bbc6e96bca23b756ee0bb7b99d391d991415f6ffb9d2aa705fd",
+    "vault.ts": "e01d26ed5517547bfc29dc89ca58836c762d665e88a5db58523475248f5de387",
+    "wallet.ts": "25fd97be3dde9755414f0eeacae2a9cfc14358951f98d6573af1025403895dba"
+  }
+}