hookr-sdk 0.2.1 → 1.0.0

package/dist/core/registry.js

@@ -0,0 +1,378 @@
+import { decodeAbiParameters, decodeFunctionResult, encodeAbiParameters, encodeFunctionData, keccak256, parseAbi, toBytes, } from "viem";
+import { ARTIFACT_ABIS, RELEASE_CONSTANTS } from "./generated.js";
+import { address, assert, hash, uint, ZERO_HASH, } from "./schema.js";
+import { MAX_LP_FEE_PIPS, RULES_GAS_LIMIT } from "./rules.js";
+import { buildCall } from "./wallet.js";
+const registryAbi = ARTIFACT_ABIS.HookrRegistry;
+/** IHookrRegistry.Kind. */
+export const ADMISSION_KIND = { RULES: 0, ADVISORY: 1 };
+/** HookrTypes phase bits an advisory may run in. */
+export const PHASE = { BEFORE_SWAP: 1, AFTER_SWAP: 2 };
+/**
+ * The quote-admission surface of HookrRegistry: the two timelocked operations (a quote class by
+ * runtime codehash, open quotes), their two immediate brakes (owner or guardian), the reads and the events. Written
+ * from its compiled ABI; `test/quote-admission.test.ts` pins every item to it (`test/fixtures`) and to the
+ * generated ABI once the packet carries them. Their kind constants are private in the registry: keccak256 of the name.
+ */
+export const QUOTE_ADMISSION_ABI = parseAbi([
+    "function enableQuoteClassOf(address witness, bytes32 codeHash)",
+    "function excludeQuoteClassNow(bytes32 codeHash)",
+    "function allowOpenQuotes()",
+    "function stopOpenQuotesNow()",
+    "function curatedQuote(address asset) view returns (bool)",
+    "function quoteState() view returns (bool openQuotes, uint48 openQuotesStoppedAt, bytes32[] classes)",
+    "event QuoteClassSet(bytes32 indexed codeHash, address indexed witness, bool active)",
+    "event QuoteClassExcluded(bytes32 indexed codeHash, address indexed by)",
+    "event OpenQuotesSet(bool open, address indexed by)",
+    "error QuoteClassActive(bytes32 codeHash)",
+    "error OpenQuotesActive()",
+    "error QueuedBeforeBrake(bytes32 operation)",
+]);
+/** The two quote-admission operations by kind name, and the function each executes with. */
+export const QUOTE_ADMISSION_OPERATIONS = {
+    SET_QUOTE_CLASS: "enableQuoteClassOf",
+    OPEN_QUOTES: "allowOpenQuotes",
+};
+const params = (ps = []) => ps
+    .map((p) => (p.type.startsWith("tuple") ? `(${params(p.components)})${p.type.slice(5)}` : p.type) +
+    (p.indexed ? " indexed" : ""))
+    .join(",");
+/** An ABI item's full signature, names aside: kind, name, parameter types, indexed flags, mutability and outputs. */
+function signature(item) {
+    const e = item;
+    const head = `${e.type} ${e.name ?? ""}(${params(e.inputs)})`;
+    return e.type === "function" ? `${head} ${e.stateMutability} returns (${params(e.outputs)})` : head;
+}
+/**
+ * Whether `abi` (by default the packet's generated HookrRegistry ABI) carries every quote-admission item with the exact
+ * signature. The operations, brakes and reads below refuse an ABI without them, so nothing can build a call the
+ * release does not have; a caller that targets another registry build passes that build's ABI.
+ */
+export function registryHasQuoteAdmission(abi = registryAbi) {
+    const have = new Set(abi.map(signature));
+    return QUOTE_ADMISSION_ABI.every((item) => have.has(signature(item)));
+}
+/** Whether `abi` carries the function a quote-admission operation executes with. */
+export function registryHasOperation(kind, abi = registryAbi) {
+    const item = QUOTE_ADMISSION_ABI.find((e) => e.type === "function" && e.name === QUOTE_ADMISSION_OPERATIONS[kind]);
+    return abi.some((e) => signature(e) === signature(item));
+}
+const kindHash = (name) => keccak256(toBytes(name));
+/** keccak256 of empty code: an account without code has it, so no class may be admitted by it. */
+const EMPTY_CODE_HASH = "0xc5d2460186f7233c927e7db2dcc703c0e500b653ca82273b7bfad8045d85a470";
+/** A quote class's runtime codehash: nonzero and never the empty-code hash. */
+export function quoteClassHash(value) {
+    const h = hash(value);
+    assert(h !== ZERO_HASH && h !== EMPTY_CODE_HASH, "A quote class needs a real runtime codehash");
+    return h;
+}
+/** keccak256 of each kind name, as the registry's public constants. */
+export const REGISTRY_KINDS = {
+    SET_LAUNCHER: RELEASE_CONSTANTS.SET_LAUNCHER,
+    SET_QUOTE: RELEASE_CONSTANTS.SET_QUOTE,
+    SET_QUOTE_CLASS: kindHash("SET_QUOTE_CLASS"),
+    OPEN_QUOTES: kindHash("OPEN_QUOTES"),
+    REGISTER_ROOT: RELEASE_CONSTANTS.REGISTER_ROOT,
+    RETIRE_ROOT: RELEASE_CONSTANTS.RETIRE_ROOT,
+    REOPEN_ROOT: RELEASE_CONSTANTS.REOPEN_ROOT,
+    SET_ROOT_FACTORY: RELEASE_CONSTANTS.SET_ROOT_FACTORY,
+    ADMIT: RELEASE_CONSTANTS.ADMIT,
+    TRANSFER_OWNER: RELEASE_CONSTANTS.TRANSFER_OWNER,
+    SET_GUARDIAN: RELEASE_CONSTANTS.SET_GUARDIAN,
+    RESUME_NEW_MARKETS: RELEASE_CONSTANTS.RESUME_NEW_MARKETS,
+};
+function inputs(name, abi = registryAbi) {
+    const entry = abi.find((e) => e.type === "function" && e.name === name);
+    assert(entry && entry.type === "function", `HookrRegistry ABI lacks ${name}`);
+    const pinned = QUOTE_ADMISSION_ABI.find((e) => e.type === "function" && e.name === name);
+    assert(!pinned || signature(pinned) === signature(entry), `HookrRegistry ABI differs for ${name}`);
+    return entry.inputs;
+}
+/** Each kind's executing function and the ABI arguments it re-derives, taken from the artifact. */
+const EXECUTE = {
+    SET_LAUNCHER: "setLauncher",
+    SET_QUOTE: "setQuote",
+    SET_QUOTE_CLASS: QUOTE_ADMISSION_OPERATIONS.SET_QUOTE_CLASS,
+    OPEN_QUOTES: QUOTE_ADMISSION_OPERATIONS.OPEN_QUOTES,
+    REGISTER_ROOT: "registerRoot",
+    RETIRE_ROOT: "retireRoot",
+    REOPEN_ROOT: "reopenRoot",
+    SET_ROOT_FACTORY: "setRootFactory",
+    ADMIT: "admit",
+    TRANSFER_OWNER: "transferOwnership",
+    SET_GUARDIAN: "setGuardian",
+    RESUME_NEW_MARKETS: "resumeNewMarkets",
+};
+function values(op) {
+    switch (op.kind) {
+        case "SET_LAUNCHER":
+            return [address(op.launcher), op.active];
+        case "SET_QUOTE":
+            return [address(op.asset), op.active];
+        case "SET_QUOTE_CLASS":
+            return [address(op.witness), quoteClassHash(op.codeHash)];
+        case "OPEN_QUOTES":
+            return [];
+        case "REGISTER_ROOT":
+            assert(hash(op.codeHash) !== ZERO_HASH, "Missing root codehash");
+            return [address(op.root), op.codeHash];
+        case "RETIRE_ROOT":
+        case "REOPEN_ROOT":
+            return [address(op.root)];
+        case "SET_ROOT_FACTORY":
+            assert(!op.active || hash(op.codeHash) !== ZERO_HASH, "Missing factory codehash");
+            return [address(op.factory), hash(op.codeHash), op.active];
+        case "ADMIT":
+            checkAdmission(op.admission);
+            return [address(op.root), op.admission];
+        case "TRANSFER_OWNER":
+            return [address(op.nextOwner)];
+        case "SET_GUARDIAN":
+            return [address(op.guardian, true)];
+        case "RESUME_NEW_MARKETS":
+            return [];
+    }
+}
+/**
+ * `queue(kind, arguments)` inputs for an operation, with the canonical ABI arguments. `abi` is the registry build's ABI
+ * (default: the packet's); a kind whose executing function it lacks is refused.
+ */
+export function encodeRegistryOperation(op, abi = registryAbi) {
+    const args = values(op);
+    const params = inputs(EXECUTE[op.kind], abi);
+    return {
+        kind: REGISTRY_KINDS[op.kind],
+        arguments: args.length ? encodeAbiParameters(params, args) : "0x",
+    };
+}
+/**
+ * Decodes an `OperationQueued(kind, arguments)` into the operation it will execute. Refuses an unknown kind and any
+ * non-canonical argument encoding, as HookrRegistry.queue does.
+ */
+export function decodeRegistryOperation(kind, args, abi = registryAbi) {
+    const entry = Object.entries(REGISTRY_KINDS).find(([, k]) => k === kind.toLowerCase());
+    assert(entry, "Unknown registry operation kind");
+    const name = entry[0];
+    const params = inputs(EXECUTE[name], abi);
+    const v = params.length ? decodeAbiParameters(params, args) : [];
+    const lower = (a) => a.toLowerCase();
+    let op;
+    switch (name) {
+        case "SET_LAUNCHER":
+            op = { kind: name, launcher: lower(v[0]), active: v[1] };
+            break;
+        case "SET_QUOTE":
+            op = { kind: name, asset: lower(v[0]), active: v[1] };
+            break;
+        case "SET_QUOTE_CLASS":
+            op = { kind: name, witness: lower(v[0]), codeHash: v[1].toLowerCase() };
+            break;
+        case "OPEN_QUOTES":
+            op = { kind: name };
+            break;
+        case "REGISTER_ROOT":
+            op = { kind: name, root: lower(v[0]), codeHash: v[1] };
+            break;
+        case "RETIRE_ROOT":
+        case "REOPEN_ROOT":
+            op = { kind: name, root: lower(v[0]) };
+            break;
+        case "SET_ROOT_FACTORY":
+            op = { kind: name, factory: lower(v[0]), codeHash: v[1], active: v[2] };
+            break;
+        case "ADMIT":
+            op = { kind: name, root: lower(v[0]), admission: { ...v[1], implementation: lower(v[1].implementation) } };
+            break;
+        case "TRANSFER_OWNER":
+            op = { kind: name, nextOwner: lower(v[0]) };
+            break;
+        case "SET_GUARDIAN":
+            op = { kind: name, guardian: lower(v[0]) };
+            break;
+        case "RESUME_NEW_MARKETS":
+            op = { kind: name };
+            break;
+    }
+    assert(encodeAbiParameters(params, params.length ? values(op) : []).toLowerCase() === args.toLowerCase(), "Non-canonical registry operation arguments");
+    return op;
+}
+/** HookrRegistry.operationHash: keccak256(abi.encode(chainId, registry, kind, arguments)). */
+export function registryOperationHash(chainId, registry, kind, args) {
+    return keccak256(encodeAbiParameters([{ type: "uint256" }, { type: "address" }, { type: "bytes32" }, { type: "bytes" }], [uint(chainId), address(registry), hash(kind), args]));
+}
+/** Owner call that queues `op`; it executes after the registry delay with `buildRegistryExecute`. */
+export function buildRegistryQueue(m, op, abi = registryAbi) {
+    const { kind, arguments: args } = encodeRegistryOperation(op, abi);
+    return buildCall(m, "registry", abi, "queue", [kind, args]);
+}
+/** Owner call that executes a matured `op`: the same arguments the queue committed to. */
+export function buildRegistryExecute(m, op, abi = registryAbi) {
+    inputs(EXECUTE[op.kind], abi);
+    return buildCall(m, "registry", abi, EXECUTE[op.kind], values(op));
+}
+function quoteAdmissionAbi(abi) {
+    assert(registryHasQuoteAdmission(abi), "HookrRegistry ABI lacks the quote-admission calls");
+    return abi;
+}
+/**
+ * Brake (owner or guardian, immediate): withdraws quote class `codeHash` from new pools and refuses every admission of
+ * it queued until now. Existing pools keep the quote they bound; a catalog entry for the same asset still qualifies it.
+ */
+export function buildExcludeQuoteClass(m, codeHash, abi = registryAbi) {
+    return buildCall(m, "registry", quoteAdmissionAbi(abi), "excludeQuoteClassNow", [quoteClassHash(codeHash)]);
+}
+/**
+ * Brake (owner or guardian, immediate): turns open quotes off for new pools and refuses every opening queued until
+ * now. The catalog, the admitted classes and native ETH still qualify; existing pools keep their quote.
+ */
+export function buildStopOpenQuotes(m, abi = registryAbi) {
+    return buildCall(m, "registry", quoteAdmissionAbi(abi), "stopOpenQuotesNow", []);
+}
+/** `quoteState()` calldata. */
+export function encodeQuoteStateCall() {
+    return encodeFunctionData({ abi: QUOTE_ADMISSION_ABI, functionName: "quoteState" });
+}
+/** Decodes a `quoteState()` result. */
+export function decodeQuoteState(data) {
+    const [openQuotes, stoppedAt, classes] = decodeFunctionResult({
+        abi: QUOTE_ADMISSION_ABI,
+        functionName: "quoteState",
+        data,
+    });
+    return {
+        openQuotes,
+        openQuotesStoppedAt: Number(stoppedAt),
+        classes: classes.map((c) => c.toLowerCase()),
+    };
+}
+/** `curatedQuote(asset)` calldata: native ETH, a catalog asset or a class member, never an open quote. */
+export function encodeCuratedQuoteCall(asset) {
+    return encodeFunctionData({ abi: QUOTE_ADMISSION_ABI, functionName: "curatedQuote", args: [address(asset, true)] });
+}
+/** Decodes a `curatedQuote(asset)` result. */
+export function decodeCuratedQuote(data) {
+    return decodeFunctionResult({ abi: QUOTE_ADMISSION_ABI, functionName: "curatedQuote", data });
+}
+/**
+ * Refuses an admission HookrRegistry would refuse on its own terms (the checks that do not read chain state).
+ * A Rules admission runs both phases, never fails open and carries exactly `RULES_GAS_LIMIT` gas.
+ */
+export function checkAdmission(a) {
+    assert(a.kind === 0 || a.kind === 1, "Invalid admission kind");
+    address(a.implementation);
+    assert(hash(a.codeHash) !== ZERO_HASH, "Missing module codehash");
+    assert(hash(a.schemaHash) !== ZERO_HASH, "Missing schema hash");
+    assert(Number.isInteger(a.gasLimit) && a.gasLimit >= 25_000 && a.gasLimit <= RULES_GAS_LIMIT, "Admission gas out of range");
+    assert(Number.isInteger(a.caps.maxLpFeePips) && a.caps.maxLpFeePips >= 0 && a.caps.maxLpFeePips <= MAX_LP_FEE_PIPS, "Admission LP cap above 600000 pips");
+    assert(Number.isInteger(a.caps.maxQuoteTakePips) && a.caps.maxQuoteTakePips >= 0 && a.caps.maxQuoteTakePips < 1_000_000, "Admission quote take cap at or above 1000000 pips");
+    assert(Number.isInteger(a.caps.maxSubjectTakeBps) && a.caps.maxSubjectTakeBps >= 0 && a.caps.maxSubjectTakeBps <= 1_000, "Admission subject cap above 1000 bps");
+    assert(Number.isInteger(a.phaseMask) && (a.phaseMask & ~3) === 0, "Invalid phase mask");
+    if (a.kind === ADMISSION_KIND.RULES)
+        assert(a.phaseMask === 3 && !a.failOpen && a.gasLimit === RULES_GAS_LIMIT, "Rules admission must run both phases, fail closed and carry exactly 2000000 gas");
+    else
+        assert(a.phaseMask !== 0 && a.caps.maxSubjectTakeBps === 0, "Advisory admission needs a phase and no subject take");
+    if (a.failOpen)
+        assert(a.feeOnly && a.caps.maxQuoteTakePips === 0, "Fail-open admission must be fee-only");
+}
+/**
+ * A HookrRules admission: both phases, fail-closed, exactly RULES_GAS_LIMIT gas, and the Rules' schema id
+ * (`schemaHash`, RULES_CONFIG_SCHEMA_HASH, the keccak256 of RulesConfig's type string since r26; omitted, it is that
+ * id). Any other id is refused: HookrLane checks each admission's schemaHash against the Rules' own
+ * configSchemaHash(), so a Rules admitted under another id could never serve a lane pool.
+ */
+export function rulesAdmission(p) {
+    const schemaHash = hash(p.schemaHash ?? RELEASE_CONSTANTS.RULES_CONFIG_SCHEMA_HASH);
+    assert(schemaHash === RELEASE_CONSTANTS.RULES_CONFIG_SCHEMA_HASH.toLowerCase(), "A Rules admission carries the Rules' schema id RULES_CONFIG_SCHEMA_HASH (keccak256 of RulesConfig's type string); " +
+        'keccak256("hookr.rules.config") is the retired 15-word layout\'s');
+    const a = { kind: 0, ...p, schemaHash, gasLimit: RULES_GAS_LIMIT, phaseMask: 3, failOpen: false };
+    checkAdmission(a);
+    return a;
+}
+/**
+ * An advisory admission. `caps` is the advisory's admitted maximum; every pool that binds it reserves that maximum
+ * out of its caps (`poolCapsFor`).
+ */
+export function advisoryAdmission(p) {
+    const a = { kind: 1, ...p };
+    checkAdmission(a);
+    return a;
+}
+/**
+ * A pair-advisory admission for a root factory: kind ADVISORY, surcharge cap `maxLpFeePips`, BEFORE_SWAP, fee-only,
+ * no quote take, fail closed unless `failOpen`. HookrRootFactory deploys a root naming the advisory only when the
+ * root's advisory cap and gas are at most these and the advisory's runtime codehash is `codeHash`; a fail-open root
+ * additionally needs a fail-open admission (the rule HookrRoot applies when it binds a fail-open advisory).
+ */
+export function pairAdvisoryAdmission(p) {
+    assert(Number.isInteger(p.maxLpFeePips) &&
+        p.maxLpFeePips > 0 &&
+        p.maxLpFeePips <= RELEASE_CONSTANTS.PAIR_ROOT_MAX_LP_FEE_PIPS, "Pair advisory cap outside (0, HookrPairRoot.MAX_LP_FEE_PIPS]");
+    assert(Number.isInteger(p.gasLimit) && p.gasLimit <= RELEASE_CONSTANTS.PAIR_ROOT_MAX_ADVISORY_GAS, "Pair advisory gas above HookrPairRoot.MAX_ADVISORY_GAS");
+    const { maxLpFeePips, failOpen = false, ...rest } = p;
+    return advisoryAdmission({
+        ...rest,
+        caps: { maxLpFeePips, maxQuoteTakePips: 0, maxSubjectTakeBps: 0 },
+        phaseMask: PHASE.BEFORE_SWAP,
+        feeOnly: true,
+        failOpen,
+    });
+}
+/** The timelocked ADMIT of a pair advisory scoped to root factory `factory`. */
+export function factoryAdmission(factory, admission) {
+    assert(admission.kind === ADMISSION_KIND.ADVISORY, "A root factory admits only advisories");
+    checkAdmission(admission);
+    return { kind: "ADMIT", root: address(factory), admission };
+}
+/**
+ * The checks HookrRootFactory.deploy runs on a pair root's advisory against its factory admission (read with
+ * `admission(factory, advisory)`) and the advisory's current runtime codehash. A fail-open root charges its full cap
+ * whenever the advisory fails, so it needs an admission that is fail-open, fee-only and without a quote take.
+ */
+export function checkPairRootAdmission(params, admitted, advisoryCodeHash) {
+    const advisory = address(params.advisory);
+    assert(admitted.implementation.toLowerCase() === advisory && admitted.kind === ADMISSION_KIND.ADVISORY, "Advisory not admitted for the root factory");
+    assert(params.advisoryCapPips <= admitted.caps.maxLpFeePips, "Advisory cap above the factory admission");
+    assert(params.advisoryGasLimit <= admitted.gasLimit, "Advisory gas above the factory admission");
+    if (params.advisoryFailOpen)
+        assert(admitted.failOpen && admitted.feeOnly && admitted.caps.maxQuoteTakePips === 0, "Fail-open root needs a fail-open, fee-only factory admission without a quote take");
+    assert(hash(advisoryCodeHash) === admitted.codeHash.toLowerCase(), "Advisory runtime differs from its admission");
+}
+/**
+ * Brake (owner or guardian, immediate): permanently withdraws root factory `factory`'s admissions of the given pair
+ * advisories. Deployed pair roots keep their advisory; `rootStatus` then reads them as unverified.
+ */
+export function buildRevokeFactoryAdmissions(m, factory, implementations) {
+    assert(implementations.length > 0, "Name at least one admission to revoke");
+    return buildCall(m, "registry", registryAbi, "revokeFactoryAdmissions", [
+        address(factory),
+        implementations.map((a) => address(a)),
+    ]);
+}
+/** `rootStatus(root)` calldata. */
+export function encodeRootStatusCall(root) {
+    return encodeFunctionData({ abi: registryAbi, functionName: "rootStatus", args: [address(root)] });
+}
+/**
+ * Decodes a `rootStatus(root)` result. `verified` is true for a registered root whose advisory, if any, is still
+ * admitted for its factory with an unchanged runtime codehash; gate pair roots on it.
+ */
+export function decodeRootStatus(data) {
+    const [advisory, verified] = decodeFunctionResult({
+        abi: registryAbi,
+        functionName: "rootStatus",
+        data,
+    });
+    return { advisory: advisory.toLowerCase(), verified };
+}
+/**
+ * Whether `code` is an EIP-7702 delegation designator (0xef0100 || target). The registry, the treasury and every
+ * HookrGoverned contract refuse such an account as owner, nominee or guardian.
+ */
+export function isDelegatedCode(code) {
+    return code !== undefined && /^0xef0100[\da-fA-F]{40}$/.test(code);
+}
+/** Refuses an owner, nominee or guardian account whose code (from eth_getCode) is an EIP-7702 delegation. */
+export function checkUndelegated(account, code) {
+    assert(!isDelegatedCode(code), "EIP-7702 delegated account");
+    return address(account, true);
+}