hookr-sdk 0.2.1 → 1.1.0

package/dist/index.d.ts

@@ -1,18 +1,45 @@
 /**
- * `hookr-sdk` — build a market on Hookr's live root hooks with a custom rule configuration,
- * quote and swap through Hookr's router, read markets, and claim payouts.
+ * hookr-sdk: build on Hookr, the Uniswap v4 hook on Robinhood Chain.
  *
- * Two roots are live on Robinhood Chain (id 4663): the default root `HookrModularHookV6`
- * (`ADDRESSES.root`) and the arbitrage-recapture root `HookrModularHookV6WthV5`
- * (`ADDRESSES.recaptureRoot`); `ROOTS` in `chain.ts` pairs each with its kernel id. See the
- * README for a quickstart.
+ * `./core` is the release SDK of the release commit, copied byte for byte (`provenance.json` names the commit and
+ * every file's hash). `./releases` adds the addresses and deployment of the production release and its canary, the
+ * Rules modules its root admits beside the release's own, the chain for viem, and builds the DeploymentManifest the core
+ * builders take. `./wallet-cap` adds Wallet Cap: its pool terms, its storage reads and its refusal.
+ *
+ * Below, the core's quote-admission exports are exported again, marked deprecated: they name functions HookrRegistry
+ * does not have on chain.
+ */
+import * as registry from "./core/registry.js";
+import { kingOfTheHillPrizeBound as prizeBound } from "./core/rules.js";
+export * from "./core/index.js";
+export * from "./releases.js";
+export * from "./wallet-cap.js";
+/**
+ * The largest King of the Pool `maxPrizeBps` a recapture pool binds with: HookrRecapture's `prizeBoundFor(lpBps,
+ * burnBps, protocolShareBps, integratorBps)`, worked out offline.
  */
-export * from "./chain.js";
-export * from "./abi.js";
-export * from "./rules.js";
-export * from "./fees.js";
-export * from "./market.js";
-export * from "./swap.js";
-export * from "./reads.js";
-export * from "./claims.js";
-export * from "./links.js";
+export declare const kingOfThePoolPrizeBound: typeof prizeBound;
+/** @deprecated The same function as `kingOfThePoolPrizeBound`, under King of the Pool's earlier name. */
+export declare const kingOfTheHillPrizeBound: typeof prizeBound;
+/** @deprecated Describes calls HookrRegistry does not have on chain. Removed in 2.0. */
+export declare const QUOTE_ADMISSION_ABI: typeof registry.QUOTE_ADMISSION_ABI;
+/** @deprecated Names functions HookrRegistry does not have on chain. Removed in 2.0. */
+export declare const QUOTE_ADMISSION_OPERATIONS: typeof registry.QUOTE_ADMISSION_OPERATIONS;
+/** @deprecated Checks an ABI offline; against the deployed HookrRegistry's ABI it returns false. Removed in 2.0. */
+export declare const registryHasQuoteAdmission: typeof registry.registryHasQuoteAdmission;
+/** @deprecated Checks an ABI offline; against the deployed HookrRegistry's ABI it returns false. Removed in 2.0. */
+export declare const registryHasOperation: typeof registry.registryHasOperation;
+/** @deprecated Calls `excludeQuoteClassNow`, which HookrRegistry does not have on chain. Removed in 2.0. */
+export declare const buildExcludeQuoteClass: typeof registry.buildExcludeQuoteClass;
+/** @deprecated Calls `stopOpenQuotesNow`, which HookrRegistry does not have on chain. Removed in 2.0. */
+export declare const buildStopOpenQuotes: typeof registry.buildStopOpenQuotes;
+/** @deprecated Encodes `quoteState()`, which HookrRegistry does not have on chain. Removed in 2.0. */
+export declare const encodeQuoteStateCall: typeof registry.encodeQuoteStateCall;
+/** @deprecated Decodes `quoteState()`, which HookrRegistry does not have on chain. Removed in 2.0. */
+export declare const decodeQuoteState: typeof registry.decodeQuoteState;
+/** @deprecated The result of `quoteState()`, which HookrRegistry does not have on chain. Removed in 2.0. */
+export type QuoteState = registry.QuoteState;
+/** @deprecated Encodes `curatedQuote(asset)`, which HookrRegistry does not have on chain. Removed in 2.0. */
+export declare const encodeCuratedQuoteCall: typeof registry.encodeCuratedQuoteCall;
+/** @deprecated Decodes `curatedQuote(asset)`, which HookrRegistry does not have on chain. Removed in 2.0. */
+export declare const decodeCuratedQuote: typeof registry.decodeCuratedQuote;

package/dist/index.js

@@ -1,18 +1,43 @@
 /**
- * `hookr-sdk` — build a market on Hookr's live root hooks with a custom rule configuration,
- * quote and swap through Hookr's router, read markets, and claim payouts.
+ * hookr-sdk: build on Hookr, the Uniswap v4 hook on Robinhood Chain.
  *
- * Two roots are live on Robinhood Chain (id 4663): the default root `HookrModularHookV6`
- * (`ADDRESSES.root`) and the arbitrage-recapture root `HookrModularHookV6WthV5`
- * (`ADDRESSES.recaptureRoot`); `ROOTS` in `chain.ts` pairs each with its kernel id. See the
- * README for a quickstart.
+ * `./core` is the release SDK of the release commit, copied byte for byte (`provenance.json` names the commit and
+ * every file's hash). `./releases` adds the addresses and deployment of the production release and its canary, the
+ * Rules modules its root admits beside the release's own, the chain for viem, and builds the DeploymentManifest the core
+ * builders take. `./wallet-cap` adds Wallet Cap: its pool terms, its storage reads and its refusal.
+ *
+ * Below, the core's quote-admission exports are exported again, marked deprecated: they name functions HookrRegistry
+ * does not have on chain.
+ */
+import * as registry from "./core/registry.js";
+import { kingOfTheHillPrizeBound as prizeBound } from "./core/rules.js";
+export * from "./core/index.js";
+export * from "./releases.js";
+export * from "./wallet-cap.js";
+/**
+ * The largest King of the Pool `maxPrizeBps` a recapture pool binds with: HookrRecapture's `prizeBoundFor(lpBps,
+ * burnBps, protocolShareBps, integratorBps)`, worked out offline.
  */
-export * from "./chain.js";
-export * from "./abi.js";
-export * from "./rules.js";
-export * from "./fees.js";
-export * from "./market.js";
-export * from "./swap.js";
-export * from "./reads.js";
-export * from "./claims.js";
-export * from "./links.js";
+export const kingOfThePoolPrizeBound = prizeBound;
+/** @deprecated The same function as `kingOfThePoolPrizeBound`, under King of the Pool's earlier name. */
+export const kingOfTheHillPrizeBound = prizeBound;
+/** @deprecated Describes calls HookrRegistry does not have on chain. Removed in 2.0. */
+export const QUOTE_ADMISSION_ABI = registry.QUOTE_ADMISSION_ABI;
+/** @deprecated Names functions HookrRegistry does not have on chain. Removed in 2.0. */
+export const QUOTE_ADMISSION_OPERATIONS = registry.QUOTE_ADMISSION_OPERATIONS;
+/** @deprecated Checks an ABI offline; against the deployed HookrRegistry's ABI it returns false. Removed in 2.0. */
+export const registryHasQuoteAdmission = registry.registryHasQuoteAdmission;
+/** @deprecated Checks an ABI offline; against the deployed HookrRegistry's ABI it returns false. Removed in 2.0. */
+export const registryHasOperation = registry.registryHasOperation;
+/** @deprecated Calls `excludeQuoteClassNow`, which HookrRegistry does not have on chain. Removed in 2.0. */
+export const buildExcludeQuoteClass = registry.buildExcludeQuoteClass;
+/** @deprecated Calls `stopOpenQuotesNow`, which HookrRegistry does not have on chain. Removed in 2.0. */
+export const buildStopOpenQuotes = registry.buildStopOpenQuotes;
+/** @deprecated Encodes `quoteState()`, which HookrRegistry does not have on chain. Removed in 2.0. */
+export const encodeQuoteStateCall = registry.encodeQuoteStateCall;
+/** @deprecated Decodes `quoteState()`, which HookrRegistry does not have on chain. Removed in 2.0. */
+export const decodeQuoteState = registry.decodeQuoteState;
+/** @deprecated Encodes `curatedQuote(asset)`, which HookrRegistry does not have on chain. Removed in 2.0. */
+export const encodeCuratedQuoteCall = registry.encodeCuratedQuoteCall;
+/** @deprecated Decodes `curatedQuote(asset)`, which HookrRegistry does not have on chain. Removed in 2.0. */
+export const decodeCuratedQuote = registry.decodeCuratedQuote;

package/dist/releases.d.ts

@@ -0,0 +1,219 @@
+/**
+ * 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 { type Chain } from "viem";
+import { type Address, type ContractRole, type DeploymentManifest, type Hash } from "./core/index.js";
+/** Robinhood Chain's id. */
+export declare 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 declare const RPC_URL = "https://rpc.mainnet.chain.robinhood.com";
+/** The block explorer people open: RobinScan. No trailing slash. */
+export declare 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 declare const ROBINHOOD_CHAIN: Chain;
+/** An address's page on the explorer. */
+export declare function explorerAddressUrl(address: Address): string;
+/** A transaction's page on the explorer. */
+export declare function explorerTxUrl(hash: Hash): string;
+/** Uniswap v4's dynamic-fee flag. Every Hookr pool's `PoolKey.fee` is this: the hook sets the LP fee on each swap. */
+export declare const DYNAMIC_FEE = 8388608;
+/** The price limit for a `zeroForOne` swap that may fill in full: TickMath's MIN_SQRT_PRICE + 1. */
+export declare 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 declare const MAX_SQRT_PRICE_LIMIT = 1461446703485210103287273052203988822378723970341n;
+/** Uniswap v4's PoolManager on Robinhood Chain. Every Hookr pool lives in it. */
+export declare const POOL_MANAGER: Address;
+/** The account that deploys both releases. CREATE3 addresses depend on it, never on a nonce. */
+export declare const RELEASE_DEPLOYER: Address;
+/** The CREATE3 factory both releases deploy through. */
+export declare const CREATE3_FACTORY: Address;
+/** The source commit both releases are built from. */
+export declare const RELEASE_SOURCE_COMMIT = "412960b37a631ce145d49fb4a1887f04a4d1fa74";
+/** The release digest: the hash of the build both releases deploy from. */
+export declare const RELEASE_PACKET_DIGEST = "83962c12ff55df431612ffae8bfc66a30041eb310035cfc30eab1bb9bdc0e031";
+/** Every contract of a release, by contract name. */
+export interface ReleaseContracts {
+    HookrRegistryChecks: Address;
+    HookrRegistryAdmin: Address;
+    HookrRegistry: Address;
+    HookrTreasury: Address;
+    HookrForwarder: Address;
+    HookrRouter: Address;
+    HookrQuoter: Address;
+    HookrLaunchChecks: Address;
+    HookrTokenDeployer: Address;
+    HookrLauncher: Address;
+    HookrReferralRegistry: Address;
+    HookrProgramsAdmin: Address;
+    HookrPrograms: Address;
+    /** Created by HookrPrograms. */
+    HookrMilestoneNFTFactory: Address;
+    /** Created by HookrPrograms. */
+    HookrProgramValidator: Address;
+    HookrReferralDistributor: Address;
+    /** The hook every pool of the release names in `PoolKey.hooks`. */
+    HookrRoot: Address;
+    /** Created by HookrRoot: the arb recapture lane. */
+    HookrLane: Address;
+    HookrRules: Address;
+    /** Created by HookrRules: the arb recapture split. */
+    HookrRecapture: Address;
+    HookrFamilyRouter: Address;
+    HookrFamilyLock: Address;
+    HookrCompliance: Address;
+    HookrComplianceGuard: Address;
+    HookrAccountCalls: Address;
+    HookrPaymasterAdmin: Address;
+    HookrPaymaster: Address;
+    HookrRootFactory: Address;
+    HookrSessionAdvisory: Address;
+    HookrFeeAdvisory: Address;
+    HookrLiquidityVault: Address;
+    HookrOwnedProfiles: Address;
+    HookrOwnedRootsLens: Address;
+    HookrOwnedRootFactory: Address;
+    HookrLpBoost: Address;
+}
+export type ReleaseContractName = keyof ReleaseContracts;
+/** The id each contract's salt is derived from. */
+export type HookrReleaseId = "hookr-1" | "canary-hookr-1-a";
+export interface HookrRelease {
+    /** The release id each contract's salt is derived from. */
+    releaseId: HookrReleaseId;
+    /** True for the canary: the same code at its own addresses, run before production. */
+    canary: boolean;
+    chainId: typeof CHAIN_ID;
+    contracts: Readonly<ReleaseContracts>;
+    /**
+     * The deployment as the release's verified app manifest records it, or null in a version of this package made
+     * before the release was deployed and verified. `releaseManifest` and `readReleaseManifest` use it by default.
+     */
+    deployment: Readonly<ReleaseDeployment> | null;
+    /**
+     * The Rules modules a pool on this release's root can bind, by name: `standard`, the release's own HookrRules, and
+     * on `hookr-1` also `whole-pot`, where King of the Pool pays the round's winner the whole pot, `wallet-cap`, the
+     * whole-pot Rules with a per-wallet buy cap while the launch guard lasts (`wallet-cap.ts`), and `round-trip`, the
+     * Rules that record who traded in each block for Buy/Sell Block's round-trip check. The registry admits each on the
+     * root with the release Rules' own terms. `rulesModule` names one.
+     */
+    rulesModules: Readonly<Partial<Record<RulesModuleName, Readonly<RulesModule>>>>;
+}
+/**
+ * The name of a Rules module: the release's own Rules, or beside them the whole-pot King of the Pool Rules, the Wallet
+ * Cap Rules or the round-trip Rules.
+ */
+export type RulesModuleName = "standard" | "whole-pot" | "wallet-cap" | "round-trip";
+/**
+ * A HookrRules a pool can bind on the release's root (its `PoolConfig.rules`), and the HookrRecapture it created in its
+ * constructor. The Rules reach that module for every King of the Pool call, so a pool's round, pot, prize and claims
+ * live at the Rules address. Both runtime hashes are the code read back from chain.
+ */
+export interface RulesModule {
+    name: RulesModuleName;
+    rules: Address;
+    rulesRuntimeHash: Hash;
+    recapture: Address;
+    recaptureRuntimeHash: Hash;
+}
+/** The production release. Build on this one. */
+export declare const HOOKR_1: HookrRelease;
+/**
+ * The canary: the same contracts at their own addresses, deployed and proven before production. Not for users.
+ * @internal
+ */
+export declare const CANARY_HOOKR_1_A: HookrRelease;
+/** Both releases by release id. */
+export declare const RELEASES: Readonly<Record<HookrReleaseId, HookrRelease>>;
+/** The contract each manifest role pins, in the order the manifest lists them. */
+export declare const MANIFEST_ROLES: Readonly<Partial<Record<ContractRole, ReleaseContractName | "PoolManager">>>;
+/** The address a manifest role pins in a release. */
+export declare function releaseAddress(release: HookrRelease, role: keyof typeof MANIFEST_ROLES): Address;
+/** What a manifest needs beyond the addresses: the deployment as the chain has it and its source verification. */
+export interface ReleaseDeployment {
+    /** The block the manifest starts from, as a decimal string: the block the release's app manifest was read at. */
+    startBlock: string;
+    /** That block's hash. The manifest calls it `parentHash`. */
+    parentHash: Hash;
+    /** keccak256 of each role's runtime code. Every role of `MANIFEST_ROLES` needs one. */
+    runtimeHashes: Readonly<Partial<Record<ContractRole, Hash>>>;
+    /**
+     * The hash of the release's source verification records on Blockscout. The manifest carries it to say the release
+     * is verified; the builders check its form, not its content.
+     */
+    evidenceHash: Hash;
+}
+/**
+ * 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 declare function releaseManifest(release: HookrRelease, d?: Readonly<ReleaseDeployment> | null): DeploymentManifest;
+/** The release's Rules modules other than its own HookrRules: on `hookr-1`, the whole-pot, Wallet Cap and round-trip Rules. */
+export declare function otherRulesModules(release: HookrRelease): Readonly<RulesModule>[];
+/** The release's Rules module `name`, or an error for a release without it (the canary has only `standard`). */
+export declare function rulesModule(release: HookrRelease, name: RulesModuleName): Readonly<RulesModule>;
+/** The two reads `readReleaseManifest` makes. A viem PublicClient has both. */
+export interface ReleaseReader {
+    getCode(args: {
+        address: Address;
+        blockNumber?: bigint;
+    }): Promise<`0x${string}` | undefined>;
+    getBlock(args: {
+        blockNumber: bigint;
+    }): Promise<{
+        hash: Hash | null;
+    }>;
+}
+/** Overrides for `readReleaseManifest`. With none, it reads the release's own deployment. */
+export interface ReadReleaseOptions {
+    /** The block the manifest starts from. Defaults to the release's. */
+    startBlock?: bigint;
+    /** The release's source verification hash. Defaults to the release's. */
+    evidenceHash?: Hash;
+    /** The block the code is read at. Defaults to the latest. */
+    blockNumber?: bigint;
+}
+/**
+ * `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 declare function readReleaseManifest(client: ReleaseReader, release: HookrRelease, options?: ReadReleaseOptions): Promise<DeploymentManifest>;
+/**
+ * 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 declare function laneGasFloor(gasCap: number | bigint): bigint;
+/** The read `readParentBlockNumber` makes. A viem PublicClient has it. */
+export interface ParentBlockReader {
+    getBlock(args: {
+        blockTag: "latest";
+    }): Promise<unknown>;
+}
+/**
+ * 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 declare function readParentBlockNumber(client: ParentBlockReader): Promise<bigint>;