hookr-sdk 0.2.1 → 1.0.0

package/dist/core/advisories.d.ts

@@ -0,0 +1,184 @@
+import { type Hex } from "viem";
+import { type Address, type Call, type ContractRole, type DeploymentManifest, type Hash } from "./schema.js";
+/**
+ * HookrFeeAdvisory.Config, the bind data of a fee-advisory pool. Pips of the pool input.
+ * cap: largest surcharge either way; surcharge: default while no keeper target is live; premium0/premium1: default
+ * per-direction premiums; maxStep: largest change per update; minInterval/maxTtl: seconds (minInterval at most
+ * MAX_MIN_INTERVAL, one day).
+ */
+export interface FeeAdvisoryConfig {
+    cap: number;
+    surcharge: number;
+    premium0: number;
+    premium1: number;
+    maxStep: number;
+    minInterval: number;
+    maxTtl: number;
+}
+/**
+ * HookrSessionAdvisory.Schedule, the bind data of a session-advisory pool: the surcharge per US equity session.
+ * Ramps are seconds after the open (pre-market to regular) and before the close (regular to after-hours); flags is
+ * `SESSION_UNCOVERED_AS_CLOSED` or zero.
+ */
+export interface SessionSchedule {
+    regularPips: number;
+    preMarketPips: number;
+    afterHoursPips: number;
+    overnightPips: number;
+    closedPips: number;
+    openRampSeconds: number;
+    closeRampSeconds: number;
+    flags: number;
+}
+/**
+ * HookrSessionTiers.Tiers: a higher LP fee outside US regular hours that a fee-advisory pool may bind next to its
+ * Config. The surcharge is the keeper's (or the default) plus the tier in force, clamped to the Config cap. Same
+ * fields and units as SessionSchedule; the tiers read the session advisory's shared market calendar.
+ */
+export type SessionTiers = SessionSchedule;
+/** Flag: a weekday outside the calendar is charged the closed surcharge. */
+export declare const SESSION_UNCOVERED_AS_CLOSED: 1;
+/** HookrFeeAdvisory.MIN_TIERED_GAS: the advisory refuses session tiers on a pool with less advisory gas. */
+export declare const FEE_ADVISORY_MIN_TIERED_GAS: 60000;
+/**
+ * Advisory gas a HookrRoot fee-advisory pool needs for the advisory's own bind. HookrRoot requires the pool's
+ * advisory gas to equal the admission's and runs `bind` within it; the bind reads the admission and the Rules
+ * configuration and writes the pool's state, bounds and, when tiered, its session tiers, measured at 71,974 and
+ * 99,306 gas on this release. These floors carry about 10% margin and sit above the advisory's own MIN_ADVISORY_GAS
+ * (30,000) and MIN_TIERED_GAS (60,000). A pair root calls `bindPair` with its full gas, so no bind floor applies there.
+ */
+export declare const FEE_ADVISORY_ROOT_BIND_GAS: {
+    readonly plain: 80000;
+    readonly tiered: 110000;
+};
+/** The root a fee-advisory pool binds through: a HookrRoot launch member (`bind`) or a HookrPairRoot (`bindPair`). */
+export type FeeAdvisoryRoot = "root" | "pair";
+/**
+ * Smallest advisory gas a fee-advisory pool binds with. HookrRoot: the bind floor `FEE_ADVISORY_ROOT_BIND_GAS`,
+ * which clears `bind`'s MIN_ADVISORY_GAS and, tiered, MIN_TIERED_GAS. Pair root: `bindPair`'s MIN_PAIR_GAS
+ * (10,000), or MIN_TIERED_GAS (60,000) with session tiers.
+ */
+export declare function feeAdvisoryMinGas(root: FeeAdvisoryRoot, tiered: boolean): number;
+/** ABI-encodes a fee-advisory Config: the bind data for `launchAdvised` and for a pair root's `bindPair`. */
+export declare function encodeFeeAdvisoryConfig(c: FeeAdvisoryConfig): Hex;
+/** Decodes `PoolBound.config` / `PairBound.config`, refusing any non-canonical encoding as the advisory does. */
+export declare function decodeFeeAdvisoryConfig(data: Hex): FeeAdvisoryConfig;
+/**
+ * Refuses a Config HookrFeeAdvisory would refuse under the largest cap `limit`: the pair root's advisory cap, or
+ * on a HookrRoot pool min(admission cap, pool room above the Rules' native ceiling).
+ */
+export declare function checkFeeAdvisoryConfig(c: FeeAdvisoryConfig, limit: number): void;
+/**
+ * Refuses session tiers HookrFeeAdvisory would refuse under the pool's Config cap `cap`: known flags, ramps within
+ * the shortest regular session, every tier at most the cap, and at least one tier above zero (all-zero tiers bind as
+ * a plain Config instead).
+ */
+export declare function checkSessionTiers(t: SessionTiers, cap: number): void;
+/**
+ * ABI-encodes a fee Config with session tiers (480 bytes): the bind data of a fee-advisory pool that charges more
+ * outside US regular hours, for `launchAdvised` and a pair root's `bindPair`. Checks no gas: the pool needs
+ * `feeAdvisoryMinGas(root, true)` of advisory gas, which `encodeFeeAdvisoryBind` checks.
+ */
+export declare function encodeTieredFeeAdvisoryConfig(c: FeeAdvisoryConfig, t: SessionTiers): Hex;
+/**
+ * Decodes fee-advisory bind data (`PoolBound.config` / `PairBound.config`): a Config, or a Config and session
+ * tiers. Refuses any other size and any non-canonical encoding, as the advisory does.
+ */
+export declare function decodeFeeAdvisoryBindData(data: Hex): {
+    config: FeeAdvisoryConfig;
+    tiers?: SessionTiers;
+};
+/**
+ * Fee-advisory bind data: the Config, with session tiers when given, checked against the largest cap `limit` and
+ * the pool's advisory gas `gasLimit` against `feeAdvisoryMinGas(root, tiered)`. On a HookrRoot pool (`launchAdvised`,
+ * the default) `gasLimit` is the advisory admission's, which HookrRoot requires exactly and runs the bind within:
+ * at least 80,000 plain and 110,000 tiered. On a pair root (`"pair"`, `bindPair`) it is the root's advisoryGasLimit:
+ * at least 10,000 plain and 60,000 tiered.
+ */
+export declare function encodeFeeAdvisoryBind(c: FeeAdvisoryConfig, limit: number, gasLimit: number, tiers?: SessionTiers, root?: FeeAdvisoryRoot): Hex;
+/** HookrFeeAdvisory.State: the swap-path state of a pool; `tiered` when it bound session tiers. */
+export interface FeePoolState {
+    target0: number;
+    target1: number;
+    expiry: number;
+    default0: number;
+    default1: number;
+    guardCeiling: number;
+    guardEnd: number;
+    updatedAt: number;
+    bound: boolean;
+    tiered: boolean;
+}
+/** `poolState(id)` calldata for HookrFeeAdvisory. */
+export declare function encodeFeePoolStateCall(id: Hash): Hex;
+/** Decodes a `poolState(id)` result. */
+export declare function decodeFeePoolState(data: Hex): FeePoolState;
+/** ABI-encodes a session Schedule (always 256 bytes): the bind data for `launchAdvised` and a pair root's `bindPair`. */
+export declare function encodeSessionSchedule(s: SessionSchedule): Hex;
+/** Decodes session bind data; the advisory accepts exactly 256 bytes. */
+export declare function decodeSessionSchedule(data: Hex): SessionSchedule;
+/**
+ * Refuses a Schedule HookrSessionAdvisory would refuse with tier cap `cap`: the pair root's advisory cap, or on a
+ * HookrRoot pool the advisory's admitted LP cap.
+ */
+export declare function checkSessionSchedule(s: SessionSchedule, cap: number): void;
+/** A pair root's advisory terms and the parameters its advisory binds the pool with. */
+export type PairAdvisoryBinding = 
+/** `tiers`: optional session tiers, a higher fee outside US regular hours next to the keeper surcharge. */
+{
+    advisory: "fee";
+    config: FeeAdvisoryConfig;
+    tiers?: SessionTiers;
+} | {
+    advisory: "session";
+    schedule: SessionSchedule;
+};
+/**
+ * `advisoryData` for HookrRootFactory.deploy: the bytes the pair root passes to its advisory's `bindPair`, checked
+ * against the root's immutable advisory cap and gas limit the way the advisory checks them (fee: MIN_PAIR_GAS, or
+ * MIN_TIERED_GAS with tiers; session: MIN_PAIR_GAS).
+ */
+export declare function encodeBindPairData(binding: PairAdvisoryBinding, capPips: number, gasLimit: number): Hex;
+/**
+ * Full `bindPair(id, capPips, gasLimit, data)` calldata, the call a pair root makes when it opens. Useful for
+ * reviewing a trace; the advisory only accepts it from the root itself.
+ */
+export declare function encodeBindPairCall(id: Hash, capPips: number, gasLimit: number, data: Hex): Hex;
+/**
+ * Keeper call: sets the keeper target and per-direction premiums of a fee-advisory pool for `ttl` seconds. Each
+ * directional surcharge stays within the pool cap and moves at most maxStep from the surcharge in force.
+ */
+export declare function buildFeeReprice(m: DeploymentManifest, id: Hash, target: number, premium0: number, premium1: number, ttl: number): Call;
+/** A timelocked HookrGoverned operation on a later-stage contract. */
+export type GovernedOperation = {
+    kind: "ADD_KEEPER";
+    keeper: Address;
+}
+/** Dates are month * 100 + day, strictly ascending weekdays; `early` lists 13:00 closes that are not closures. */
+ | {
+    kind: "APPEND_YEAR";
+    year: number;
+    closed: readonly number[];
+    early: readonly number[];
+} | {
+    kind: "SET_SKIM";
+    bps: number;
+} | {
+    kind: "TRANSFER_OWNER";
+    nextOwner: Address;
+};
+/** `queue(kind, arguments)` inputs of a governed operation, with its canonical ABI arguments. */
+export declare function encodeGovernedOperation(op: GovernedOperation): {
+    kind: Hash;
+    arguments: Hex;
+};
+/**
+ * HookrGoverned.operationHash: keccak256(abi.encode(chainId, contract, kind, epoch, arguments)). Read `epoch` from
+ * the contract's `epoch(key)`; a restrictive action (removing a keeper, lowering the skim) raises it and voids what
+ * was queued before.
+ */
+export declare function governedOperationHash(chainId: bigint, target: Address, kind: Hash, epoch: bigint, args: Hex): Hash;
+/** Owner call queuing a governed operation on its pinned contract. */
+export declare function buildGovernedQueue(m: DeploymentManifest, op: GovernedOperation, role?: ContractRole): Call;
+/** Owner call executing a matured governed operation with the arguments it was queued with. */
+export declare function buildGovernedExecute(m: DeploymentManifest, op: GovernedOperation, role?: ContractRole): Call;

package/dist/core/advisories.js

@@ -0,0 +1,291 @@
+import { decodeAbiParameters, decodeFunctionResult, encodeAbiParameters, encodeFunctionData, keccak256, } from "viem";
+import { ARTIFACT_ABIS, RELEASE_CONSTANTS, STRUCT_COMPONENTS } from "./generated.js";
+import { address, assert, hash, uint, } from "./schema.js";
+import { buildCall } from "./wallet.js";
+/** Flag: a weekday outside the calendar is charged the closed surcharge. */
+export const SESSION_UNCOVERED_AS_CLOSED = RELEASE_CONSTANTS.SESSION_UNCOVERED_AS_CLOSED;
+/** HookrFeeAdvisory.MIN_TIERED_GAS: the advisory refuses session tiers on a pool with less advisory gas. */
+export const FEE_ADVISORY_MIN_TIERED_GAS = RELEASE_CONSTANTS.FEE_ADVISORY_MIN_TIERED_GAS;
+/**
+ * Advisory gas a HookrRoot fee-advisory pool needs for the advisory's own bind. HookrRoot requires the pool's
+ * advisory gas to equal the admission's and runs `bind` within it; the bind reads the admission and the Rules
+ * configuration and writes the pool's state, bounds and, when tiered, its session tiers, measured at 71,974 and
+ * 99,306 gas on this release. These floors carry about 10% margin and sit above the advisory's own MIN_ADVISORY_GAS
+ * (30,000) and MIN_TIERED_GAS (60,000). A pair root calls `bindPair` with its full gas, so no bind floor applies there.
+ */
+export const FEE_ADVISORY_ROOT_BIND_GAS = { plain: 80_000, tiered: 110_000 };
+/**
+ * Smallest advisory gas a fee-advisory pool binds with. HookrRoot: the bind floor `FEE_ADVISORY_ROOT_BIND_GAS`,
+ * which clears `bind`'s MIN_ADVISORY_GAS and, tiered, MIN_TIERED_GAS. Pair root: `bindPair`'s MIN_PAIR_GAS
+ * (10,000), or MIN_TIERED_GAS (60,000) with session tiers.
+ */
+export function feeAdvisoryMinGas(root, tiered) {
+    if (root === "pair")
+        return tiered ? RELEASE_CONSTANTS.FEE_ADVISORY_MIN_TIERED_GAS : RELEASE_CONSTANTS.FEE_ADVISORY_MIN_PAIR_GAS;
+    return tiered
+        ? Math.max(FEE_ADVISORY_ROOT_BIND_GAS.tiered, RELEASE_CONSTANTS.FEE_ADVISORY_MIN_TIERED_GAS)
+        : Math.max(FEE_ADVISORY_ROOT_BIND_GAS.plain, RELEASE_CONSTANTS.FEE_ADVISORY_MIN_ADVISORY_GAS);
+}
+const FEE_TUPLE = [{ type: "tuple", components: STRUCT_COMPONENTS.FeeAdvisoryConfig }];
+const SESSION_TUPLE = [{ type: "tuple", components: STRUCT_COMPONENTS.SessionSchedule }];
+const TIERED_FEE_TUPLE = [
+    { type: "tuple", components: STRUCT_COMPONENTS.FeeAdvisoryConfig },
+    { type: "tuple", components: STRUCT_COMPONENTS.SessionTiers },
+];
+/** ABI size of a fee Config alone; tiered bind data appends the 256-byte Tiers. */
+const FEE_CONFIG_BYTES = 32 * STRUCT_COMPONENTS.FeeAdvisoryConfig.length;
+function int(value, bits, label) {
+    assert(Number.isSafeInteger(value) && value >= 0 && value < 2 ** bits, `Invalid ${label}`);
+}
+function fields(components, value) {
+    for (const c of components) {
+        const bits = Number(/^uint(\d+)$/.exec(c.type)?.[1]);
+        assert(bits > 0 && bits <= 48, `Unsupported ${c.type} field ${c.name}`);
+        int(value[c.name], bits, c.name);
+    }
+}
+/** ABI-encodes a fee-advisory Config: the bind data for `launchAdvised` and for a pair root's `bindPair`. */
+export function encodeFeeAdvisoryConfig(c) {
+    fields(STRUCT_COMPONENTS.FeeAdvisoryConfig, c);
+    return encodeAbiParameters(FEE_TUPLE, [c]);
+}
+/** Decodes `PoolBound.config` / `PairBound.config`, refusing any non-canonical encoding as the advisory does. */
+export function decodeFeeAdvisoryConfig(data) {
+    const [c] = decodeAbiParameters(FEE_TUPLE, data);
+    assert(encodeAbiParameters(FEE_TUPLE, [c]).toLowerCase() === data.toLowerCase(), "Non-canonical fee config");
+    return { ...c };
+}
+/**
+ * Refuses a Config HookrFeeAdvisory would refuse under the largest cap `limit`: the pair root's advisory cap, or
+ * on a HookrRoot pool min(admission cap, pool room above the Rules' native ceiling).
+ */
+export function checkFeeAdvisoryConfig(c, limit) {
+    fields(STRUCT_COMPONENTS.FeeAdvisoryConfig, c);
+    assert(c.cap > 0 && c.cap <= limit, "Fee cap outside (0, limit]");
+    assert(c.surcharge + c.premium0 <= c.cap && c.surcharge + c.premium1 <= c.cap, "Default surcharge above the cap");
+    assert(c.maxStep > 0 && c.minInterval > 0, "Fee updates need a step and an interval");
+    assert(c.minInterval <= RELEASE_CONSTANTS.FEE_ADVISORY_MAX_MIN_INTERVAL, "Fee update interval above 1 day");
+    assert(c.maxTtl > 0 && c.maxTtl <= RELEASE_CONSTANTS.FEE_ADVISORY_MAX_TTL, "Fee TTL outside (0, 72 hours]");
+}
+/**
+ * Refuses session tiers HookrFeeAdvisory would refuse under the pool's Config cap `cap`: known flags, ramps within
+ * the shortest regular session, every tier at most the cap, and at least one tier above zero (all-zero tiers bind as
+ * a plain Config instead).
+ */
+export function checkSessionTiers(t, cap) {
+    fields(STRUCT_COMPONENTS.SessionTiers, t);
+    const tiers = [t.regularPips, t.preMarketPips, t.afterHoursPips, t.overnightPips, t.closedPips];
+    assert(tiers.some((x) => x > 0), "Session tiers are all zero; bind the Config alone");
+    assert((t.flags & ~RELEASE_CONSTANTS.SESSION_TIERS_UNCOVERED_AS_CLOSED) === 0, "Unknown tier flags");
+    assert(t.openRampSeconds + t.closeRampSeconds <= RELEASE_CONSTANTS.SESSION_TIERS_MAX_RAMP_SECONDS, "Ramps longer than the shortest regular session");
+    assert(tiers.every((x) => x <= cap), "Session tier above the fee cap");
+}
+/**
+ * ABI-encodes a fee Config with session tiers (480 bytes): the bind data of a fee-advisory pool that charges more
+ * outside US regular hours, for `launchAdvised` and a pair root's `bindPair`. Checks no gas: the pool needs
+ * `feeAdvisoryMinGas(root, true)` of advisory gas, which `encodeFeeAdvisoryBind` checks.
+ */
+export function encodeTieredFeeAdvisoryConfig(c, t) {
+    fields(STRUCT_COMPONENTS.FeeAdvisoryConfig, c);
+    checkSessionTiers(t, c.cap);
+    return encodeAbiParameters(TIERED_FEE_TUPLE, [c, t]);
+}
+/**
+ * Decodes fee-advisory bind data (`PoolBound.config` / `PairBound.config`): a Config, or a Config and session
+ * tiers. Refuses any other size and any non-canonical encoding, as the advisory does.
+ */
+export function decodeFeeAdvisoryBindData(data) {
+    const size = (data.length - 2) / 2;
+    if (size === FEE_CONFIG_BYTES)
+        return { config: decodeFeeAdvisoryConfig(data) };
+    assert(size === FEE_CONFIG_BYTES + RELEASE_CONSTANTS.SESSION_TIERS_ENCODED_SIZE, "Fee bind data is neither a Config nor a Config with tiers");
+    const [config, tiers] = decodeAbiParameters(TIERED_FEE_TUPLE, data);
+    assert(encodeAbiParameters(TIERED_FEE_TUPLE, [config, tiers]).toLowerCase() === data.toLowerCase(), "Non-canonical fee config");
+    return { config: { ...config }, tiers: { ...tiers } };
+}
+/**
+ * Fee-advisory bind data: the Config, with session tiers when given, checked against the largest cap `limit` and
+ * the pool's advisory gas `gasLimit` against `feeAdvisoryMinGas(root, tiered)`. On a HookrRoot pool (`launchAdvised`,
+ * the default) `gasLimit` is the advisory admission's, which HookrRoot requires exactly and runs the bind within:
+ * at least 80,000 plain and 110,000 tiered. On a pair root (`"pair"`, `bindPair`) it is the root's advisoryGasLimit:
+ * at least 10,000 plain and 60,000 tiered.
+ */
+export function encodeFeeAdvisoryBind(c, limit, gasLimit, tiers, root = "root") {
+    checkFeeAdvisoryConfig(c, limit);
+    if (tiers)
+        checkSessionTiers(tiers, c.cap);
+    int(gasLimit, 32, "advisory gas");
+    const floor = feeAdvisoryMinGas(root, tiers !== undefined);
+    assert(gasLimit >= floor, `Advisory gas ${gasLimit} below the fee advisory's ${root === "pair" ? "pair root" : "HookrRoot"} ${tiers ? "tiered " : ""}floor ${floor}`);
+    return tiers ? encodeTieredFeeAdvisoryConfig(c, tiers) : encodeFeeAdvisoryConfig(c);
+}
+/** `poolState(id)` calldata for HookrFeeAdvisory. */
+export function encodeFeePoolStateCall(id) {
+    return encodeFunctionData({ abi: ARTIFACT_ABIS.HookrFeeAdvisory, functionName: "poolState", args: [hash(id)] });
+}
+/** Decodes a `poolState(id)` result. */
+export function decodeFeePoolState(data) {
+    const s = decodeFunctionResult({ abi: ARTIFACT_ABIS.HookrFeeAdvisory, functionName: "poolState", data });
+    return {
+        target0: s.target0,
+        target1: s.target1,
+        expiry: Number(s.expiry),
+        default0: s.default0,
+        default1: s.default1,
+        guardCeiling: s.guardCeiling,
+        guardEnd: Number(s.guardEnd),
+        updatedAt: Number(s.updatedAt),
+        bound: s.bound,
+        tiered: s.tiered,
+    };
+}
+/** ABI-encodes a session Schedule (always 256 bytes): the bind data for `launchAdvised` and a pair root's `bindPair`. */
+export function encodeSessionSchedule(s) {
+    fields(STRUCT_COMPONENTS.SessionSchedule, s);
+    return encodeAbiParameters(SESSION_TUPLE, [s]);
+}
+/** Decodes session bind data; the advisory accepts exactly 256 bytes. */
+export function decodeSessionSchedule(data) {
+    assert(data.length === 2 + 2 * 256, "Session schedule must be 256 bytes");
+    const [s] = decodeAbiParameters(SESSION_TUPLE, data);
+    assert(encodeAbiParameters(SESSION_TUPLE, [s]).toLowerCase() === data.toLowerCase(), "Non-canonical schedule");
+    return { ...s };
+}
+/**
+ * Refuses a Schedule HookrSessionAdvisory would refuse with tier cap `cap`: the pair root's advisory cap, or on a
+ * HookrRoot pool the advisory's admitted LP cap.
+ */
+export function checkSessionSchedule(s, cap) {
+    fields(STRUCT_COMPONENTS.SessionSchedule, s);
+    assert((s.flags & ~SESSION_UNCOVERED_AS_CLOSED) === 0, "Unknown schedule flags");
+    assert(s.openRampSeconds + s.closeRampSeconds <= RELEASE_CONSTANTS.SESSION_ADVISORY_MAX_RAMP_SECONDS, "Ramps longer than the shortest regular session");
+    assert([s.regularPips, s.preMarketPips, s.afterHoursPips, s.overnightPips, s.closedPips].every((t) => t <= cap), "Session tier above the cap");
+}
+/**
+ * `advisoryData` for HookrRootFactory.deploy: the bytes the pair root passes to its advisory's `bindPair`, checked
+ * against the root's immutable advisory cap and gas limit the way the advisory checks them (fee: MIN_PAIR_GAS, or
+ * MIN_TIERED_GAS with tiers; session: MIN_PAIR_GAS).
+ */
+export function encodeBindPairData(binding, capPips, gasLimit) {
+    if (binding.advisory === "fee")
+        return encodeFeeAdvisoryBind(binding.config, capPips, gasLimit, binding.tiers, "pair");
+    assert(gasLimit >= RELEASE_CONSTANTS.SESSION_ADVISORY_MIN_PAIR_GAS, "Pair gas below the session advisory minimum");
+    checkSessionSchedule(binding.schedule, capPips);
+    return encodeSessionSchedule(binding.schedule);
+}
+/**
+ * Full `bindPair(id, capPips, gasLimit, data)` calldata, the call a pair root makes when it opens. Useful for
+ * reviewing a trace; the advisory only accepts it from the root itself.
+ */
+export function encodeBindPairCall(id, capPips, gasLimit, data) {
+    int(capPips, 24, "cap");
+    int(gasLimit, 32, "gas limit");
+    return encodeFunctionData({
+        abi: ARTIFACT_ABIS.HookrFeeAdvisory,
+        functionName: "bindPair",
+        args: [hash(id), capPips, gasLimit, data],
+    });
+}
+/**
+ * Keeper call: sets the keeper target and per-direction premiums of a fee-advisory pool for `ttl` seconds. Each
+ * directional surcharge stays within the pool cap and moves at most maxStep from the surcharge in force.
+ */
+export function buildFeeReprice(m, id, target, premium0, premium1, ttl) {
+    int(target, 24, "target");
+    int(premium0, 24, "premium0");
+    int(premium1, 24, "premium1");
+    assert(Number.isInteger(ttl) && ttl > 0 && ttl <= RELEASE_CONSTANTS.FEE_ADVISORY_MAX_TTL, "TTL outside (0, 72 hours]");
+    return buildCall(m, "feeAdvisory", ARTIFACT_ABIS.HookrFeeAdvisory, "reprice", [
+        hash(id),
+        target,
+        premium0,
+        premium1,
+        ttl,
+    ]);
+}
+/** Which pinned contract runs each governed kind. TRANSFER_OWNER runs on the role passed to the builders. */
+const GOVERNED = {
+    ADD_KEEPER: "feeAdvisory",
+    APPEND_YEAR: "sessionAdvisory",
+    SET_SKIM: "liquidityVault",
+};
+function governedAbi(role) {
+    if (role === "feeAdvisory")
+        return ARTIFACT_ABIS.HookrFeeAdvisory;
+    if (role === "sessionAdvisory")
+        return ARTIFACT_ABIS.HookrSessionAdvisory;
+    assert(role === "liquidityVault", `No governed ABI for ${role}`);
+    return ARTIFACT_ABIS.HookrLiquidityVault;
+}
+function dates(values) {
+    values.forEach((d, i) => {
+        int(d, 16, "date");
+        assert(d >= 101 && d <= 1231 && d % 100 >= 1 && d % 100 <= 31, "Date outside month * 100 + day");
+        assert(i === 0 || d > values[i - 1], "Dates must be strictly ascending");
+    });
+    return [...values];
+}
+function governed(op) {
+    switch (op.kind) {
+        case "ADD_KEEPER":
+            return {
+                kind: RELEASE_CONSTANTS.ADD_KEEPER,
+                types: [{ type: "address" }],
+                values: [address(op.keeper)],
+                call: "addKeeper",
+            };
+        case "APPEND_YEAR":
+            int(op.year, 16, "year");
+            assert(dates(op.early).every((d) => !op.closed.includes(d)), "An early close cannot also be a closure");
+            return {
+                kind: RELEASE_CONSTANTS.APPEND_YEAR,
+                types: [{ type: "uint16" }, { type: "uint16[]" }, { type: "uint16[]" }],
+                values: [op.year, dates(op.closed), [...op.early]],
+                call: "appendYear",
+            };
+        case "SET_SKIM":
+            int(op.bps, 16, "skim");
+            assert(op.bps <= RELEASE_CONSTANTS.VAULT_SKIM_CEILING_BPS, "Skim above the ceiling");
+            return { kind: RELEASE_CONSTANTS.SET_SKIM, types: [{ type: "uint16" }], values: [op.bps], call: "setSkim" };
+        case "TRANSFER_OWNER":
+            return {
+                kind: RELEASE_CONSTANTS.TRANSFER_OWNER,
+                types: [{ type: "address" }],
+                values: [address(op.nextOwner)],
+                call: "transferOwnership",
+            };
+    }
+}
+function roleOf(op, role) {
+    if (op.kind === "TRANSFER_OWNER") {
+        assert(role !== undefined, "TRANSFER_OWNER needs the governed contract role");
+        return role;
+    }
+    assert(role === undefined || role === GOVERNED[op.kind], `${op.kind} runs on ${GOVERNED[op.kind]}`);
+    return GOVERNED[op.kind];
+}
+/** `queue(kind, arguments)` inputs of a governed operation, with its canonical ABI arguments. */
+export function encodeGovernedOperation(op) {
+    const g = governed(op);
+    return { kind: g.kind, arguments: encodeAbiParameters(g.types, g.values) };
+}
+/**
+ * HookrGoverned.operationHash: keccak256(abi.encode(chainId, contract, kind, epoch, arguments)). Read `epoch` from
+ * the contract's `epoch(key)`; a restrictive action (removing a keeper, lowering the skim) raises it and voids what
+ * was queued before.
+ */
+export function governedOperationHash(chainId, target, kind, epoch, args) {
+    return keccak256(encodeAbiParameters([{ type: "uint256" }, { type: "address" }, { type: "bytes32" }, { type: "uint256" }, { type: "bytes" }], [uint(chainId), address(target), hash(kind), uint(epoch), args]));
+}
+/** Owner call queuing a governed operation on its pinned contract. */
+export function buildGovernedQueue(m, op, role) {
+    const r = roleOf(op, role);
+    const { kind, arguments: args } = encodeGovernedOperation(op);
+    return buildCall(m, r, governedAbi(r), "queue", [kind, args]);
+}
+/** Owner call executing a matured governed operation with the arguments it was queued with. */
+export function buildGovernedExecute(m, op, role) {
+    const r = roleOf(op, role);
+    const g = governed(op);
+    return buildCall(m, r, governedAbi(r), g.call, g.values);
+}

package/dist/core/client.d.ts

@@ -0,0 +1,55 @@
+import { type Address, type Coverage, type AccountView, type FamilyView, type ProofView, type Hash, type ApiEnvelope, type ApiPage, type ProgramListing } from "./schema.js";
+/** Pages a list client-side before `programs()`/`families()`/`campaigns()` refuse to guess the rest. */
+export declare const MAX_CLIENT_PAGES = 40;
+export interface PageQuery {
+    cursor?: string | null;
+    limit?: number;
+    includeUnqualified?: boolean;
+}
+export declare class HookrClient {
+    readonly base: string;
+    readonly expected: {
+        releaseId: string;
+        chainId: string;
+        manifestHash: Hash;
+    };
+    readonly fetcher: typeof fetch;
+    constructor(base: string, expected: {
+        releaseId: string;
+        chainId: string;
+        manifestHash: Hash;
+    }, fetcher?: typeof fetch);
+    envelope<T>(path: string, query?: Record<string, string>): Promise<ApiEnvelope<T>>;
+    get<T>(path: string): Promise<T>;
+    coverage(): Promise<Coverage>;
+    page<T>(path: string, { cursor, limit, includeUnqualified }?: PageQuery, extra?: Record<string, string>): Promise<{
+        items: T[];
+        page: ApiPage;
+    }>;
+    /** Follows `page.next` to the end; refuses rather than returning a silently partial list. */
+    all<T>(path: string, query?: PageQuery, extra?: Record<string, string>): Promise<T[]>;
+    /** Qualified programs by default; `includeUnqualified` adds the rest with their reasons. */
+    programPage(query?: PageQuery): Promise<{
+        items: ProgramListing[];
+        page: ApiPage;
+    }>;
+    programs(query?: PageQuery): Promise<ProgramListing[]>;
+    program(id: string): Promise<ProgramListing>;
+    campaignPage(query?: PageQuery): Promise<{
+        items: Record<string, unknown>[];
+        page: ApiPage;
+    }>;
+    campaigns(query?: PageQuery): Promise<Record<string, unknown>[]>;
+    familyPage(query?: PageQuery & {
+        owner?: Address;
+    }): Promise<{
+        items: FamilyView[];
+        page: ApiPage;
+    }>;
+    families(query?: PageQuery & {
+        owner?: Address;
+    }): Promise<FamilyView[]>;
+    account(user: Address): Promise<AccountView>;
+    proof(programId: string, day: string, user: Address): Promise<ProofView>;
+    commissionProof(id: string, day: string, user: Address): Promise<ProofView>;
+}

package/dist/core/client.js

@@ -0,0 +1,107 @@
+import { assert, address, uint, hash, } from "./schema.js";
+/** Pages a list client-side before `programs()`/`families()`/`campaigns()` refuse to guess the rest. */
+export const MAX_CLIENT_PAGES = 40;
+export class HookrClient {
+    base;
+    expected;
+    fetcher;
+    constructor(base, expected, fetcher = fetch) {
+        const u = new URL(base);
+        assert(u.protocol === "https:" || (u.protocol === "http:" && ["localhost", "127.0.0.1", "[::1]"].includes(u.hostname)), "HTTPS required");
+        assert(!u.username && !u.password && !u.search && !u.hash, "Invalid API origin");
+        uint(expected.chainId);
+        hash(expected.manifestHash);
+        this.base = u.href.replace(/\/$/, "");
+        this.expected = expected;
+        this.fetcher = fetcher;
+    }
+    async envelope(path, query = {}) {
+        assert(/^\/v1\/[a-z0-9/-]+$/i.test(path), "Invalid API path");
+        const q = new URLSearchParams();
+        for (const [k, v] of Object.entries(query)) {
+            assert((k === "cursor" && /^\d{1,15}-\d{1,9}$/.test(v)) ||
+                (k === "limit" && /^\d{1,3}$/.test(v)) ||
+                (k === "include" && v === "unqualified") ||
+                (k === "owner" && address(v) === v), "Invalid API query");
+            q.set(k, v);
+        }
+        const r = await this.fetcher(this.base + path + (q.size ? `?${q}` : ""), {
+            signal: AbortSignal.timeout(15000),
+        });
+        assert(r.ok, `Service unavailable (${r.status})`);
+        const b = await r.json();
+        assert(b &&
+            b.schema === "hookr.api.v1" &&
+            b.releaseId === this.expected.releaseId &&
+            b.coverage?.chainId === this.expected.chainId &&
+            b.coverage?.manifestHash === this.expected.manifestHash, "Service deployment identity mismatch");
+        return b;
+    }
+    async get(path) {
+        return (await this.envelope(path)).data;
+    }
+    coverage() {
+        return this.get("/v1/coverage");
+    }
+    async page(path, { cursor, limit, includeUnqualified } = {}, extra = {}) {
+        const b = await this.envelope(path, {
+            ...extra,
+            ...(cursor ? { cursor } : {}),
+            ...(limit !== undefined ? { limit: String(limit) } : {}),
+            ...(includeUnqualified ? { include: "unqualified" } : {}),
+        });
+        assert(Array.isArray(b.data) && b.page, "Service list response lacks a page");
+        return { items: b.data, page: b.page };
+    }
+    /** Follows `page.next` to the end; refuses rather than returning a silently partial list. */
+    async all(path, query = {}, extra = {}) {
+        const out = [];
+        let cursor = query.cursor;
+        for (let i = 0; i < MAX_CLIENT_PAGES; i++) {
+            const r = await this.page(path, { ...query, cursor }, extra);
+            out.push(...r.items);
+            if (!r.page.next)
+                return out;
+            cursor = r.page.next;
+        }
+        throw new Error("List exceeds the client page bound; page it with a cursor");
+    }
+    /** Qualified programs by default; `includeUnqualified` adds the rest with their reasons. */
+    programPage(query = {}) {
+        return this.page("/v1/programs", query);
+    }
+    programs(query = {}) {
+        return this.all("/v1/programs", query);
+    }
+    program(id) {
+        uint(id);
+        return this.get(`/v1/programs/${id}`);
+    }
+    campaignPage(query = {}) {
+        return this.page("/v1/referral-campaigns", query);
+    }
+    campaigns(query = {}) {
+        return this.all("/v1/referral-campaigns", query);
+    }
+    familyPage(query = {}) {
+        const { owner, ...rest } = query;
+        return this.page("/v1/families", rest, owner ? { owner: address(owner) } : {});
+    }
+    families(query = {}) {
+        const { owner, ...rest } = query;
+        return this.all("/v1/families", rest, owner ? { owner: address(owner) } : {});
+    }
+    account(user) {
+        return this.get(`/v1/accounts/${address(user)}`);
+    }
+    proof(programId, day, user) {
+        uint(programId);
+        uint(day);
+        return this.get(`/v1/proofs/${programId}/${day}/${address(user)}`);
+    }
+    commissionProof(id, day, user) {
+        uint(id);
+        uint(day);
+        return this.get(`/v1/commission-proofs/${id}/${day}/${address(user)}`);
+    }
+}