hookr-sdk 0.2.1 → 1.0.0

package/dist/core/schema.d.ts

@@ -0,0 +1,358 @@
+export type Address = `0x${string}`;
+export type Hash = `0x${string}`;
+export type Raw = string;
+export declare const ZERO: Address;
+export declare const ZERO_HASH: Hash;
+export declare function assert(ok: unknown, message: string): asserts ok;
+export declare function address(value: unknown, zero?: boolean): Address;
+export declare function hash(value: unknown): Hash;
+export declare function uint(value: unknown, bits?: number): bigint;
+export declare function canonical(value: unknown): string;
+/** Every manifest source role. `root` and `rules` may repeat; every other role is a singleton. */
+export declare const CONTRACT_ROLES: readonly ["poolManager", "registry", "root", "rules", "router", "quoter", "launcher", "treasury", "programs", "referrals", "commissions", "forwarder", "positionManager", "rootFactory", "feeAdvisory", "sessionAdvisory", "liquidityVault"];
+export type ContractRole = (typeof CONTRACT_ROLES)[number];
+export interface ContractPin {
+    role: ContractRole;
+    address: Address;
+    runtimeHash: Hash;
+    startBlock: Raw;
+}
+export interface DeploymentManifest {
+    schema: "hookr.engagement.sources.v1";
+    releaseId: string;
+    chainId: Raw;
+    startBlock: Raw;
+    parentHash: Hash;
+    contracts: ContractPin[];
+    tokens?: {
+        address: Address;
+        symbol: string;
+        decimals: number;
+    }[];
+    commissionAuthorities?: {
+        rules: Address;
+        feeSource: 0 | 1;
+        creators: Address[];
+    }[];
+    /**
+     * Reviewed smart-wallet runtime keccak hashes whose accounts may earn referral commission and cashback as payers.
+     * Any other contract payer, or EIP-7702 delegate, is excluded because a third party may be able to bind it.
+     */
+    payerCodeHashes?: Hash[];
+    qualification: {
+        status: "verified";
+        evidenceHash: Hash;
+        sourceCommit: string;
+    };
+}
+export declare function deployment(value: unknown): DeploymentManifest;
+export interface Coverage {
+    schema: "hookr.coverage.v1";
+    chainId: Raw;
+    manifestHash: Hash;
+    fromBlock: Raw;
+    throughBlock: Raw | null;
+    throughHash: Hash | null;
+    throughTimestamp: Raw | null;
+    observedFinalizedBlock: Raw | null;
+    contiguous: boolean;
+    generation: number;
+    status: "empty" | "indexed" | "stale" | "error";
+    error: string | null;
+    sourceTrust: "configured-rpc-and-reviewed-code";
+}
+export interface Scope {
+    root: Address;
+    poolId: Hash;
+    configHash: Hash;
+    quoteAsset: Address;
+    numerator: Raw;
+    denominator: Raw;
+    subjectNumerator: Raw;
+    subjectDenominator: Raw;
+}
+export interface Terms {
+    mode: number;
+    globalBux: boolean;
+    start: Raw;
+    end: Raw;
+    pointBudget: Raw;
+    walletPointCap: Raw;
+    pointNumerator: Raw;
+    pointDenominator: Raw;
+    dailyPointBudget: Raw;
+    rewardToken: Address;
+    cashBudget: Raw;
+    walletCashCap: Raw;
+    cashNumerator: Raw;
+    cashDenominator: Raw;
+    dailyCashBudget: Raw;
+    attestor: Address;
+    reviewer: Address;
+    reviewDelay: Raw;
+    sourcePolicyHash: Hash;
+    name: string;
+    metadataURI: string;
+    pointDecimals: number;
+    referralRegistry: Address;
+    baseProgramId: Raw;
+}
+export interface Program {
+    id: Raw;
+    address: Address;
+    creator: Address;
+    termsHash: Hash;
+    terms: Terms;
+    scopes: Scope[];
+}
+export interface Award {
+    beneficiary: Address;
+    weight: Raw;
+    points: Raw;
+    cash: Raw;
+    proof: Hash[];
+}
+export interface DayAllocation {
+    schema: "hookr.day-allocation.v1";
+    status: "draft" | "reviewed";
+    chainId: Raw;
+    distributor: Address;
+    programId: Raw;
+    termsHash: Hash;
+    day: Raw;
+    epochStart: Raw;
+    epochEnd: Raw;
+    sourcePolicyHash: Hash;
+    coverageHash: Hash;
+    evidenceHash: Hash;
+    root: Hash;
+    totalWeight: Raw;
+    generation: number;
+    awards: Award[];
+    rounding: {
+        pointUnallocated: Raw;
+        cashUnallocated: Raw;
+    };
+    review?: {
+        reviewer: Address;
+        reviewedAt: string;
+        artifactHash: Hash;
+        signature: Hash;
+    };
+}
+export interface Call {
+    chainId: number;
+    to: Address;
+    data: Hash;
+    value: bigint;
+}
+/** Cursor for list routes. `next` is null only when the list is complete. */
+export interface ApiPage {
+    limit: number;
+    next: string | null;
+    scanned: number;
+}
+export interface ApiEnvelope<T> {
+    schema: "hookr.api.v1";
+    releaseId: string;
+    coverage: Coverage;
+    data: T;
+    page?: ApiPage;
+}
+/** A listed program or campaign carries the service's qualification verdict and its reasons. */
+export interface Qualification {
+    qualified: boolean;
+    unqualifiedReasons: string[];
+}
+export type ProgramListing = (Program & {
+    buxApproved: boolean;
+} & Qualification) | ({
+    id: Raw;
+} & Qualification);
+/**
+ * A buy of a family member pool that its creator made at launch. `devBuy` is the launchWithBuy dev buy
+ * (DevBuyExecuted), the only buy the Launcher's 5% cap binds. `sameTransaction` is any other buy of a member pool
+ * inside the FamilyLaunched transaction that a family owner paid (`payer`, the HookrRouter SwapExecuted paired with
+ * the Swap), sent (`sender`, the PoolManager Swap sender) or originated (`origin`, the transaction sender). Values
+ * the logs do not carry are null: a direct PoolManager buy has no `quoteIn` or `subjectOut`, only its Swap's raw
+ * pool-side amounts.
+ */
+export interface CreatorBuyView {
+    kind: "devBuy" | "sameTransaction";
+    member: number;
+    poolId: Hash;
+    tx: Hash;
+    block: Raw;
+    logIndex: number;
+    matchedBy: ("devBuy" | "payer" | "sender" | "origin")[];
+    buyer: Address;
+    payer: Address | null;
+    recipient: Address | null;
+    sender: Address | null;
+    origin: Address | null;
+    quoteIn: Raw | null;
+    subjectOut: Raw | null;
+    swap: {
+        amount0: Raw;
+        amount1: Raw;
+    } | null;
+    sqrtPriceX96: Raw | null;
+    sqrtPriceAfterX96: Raw | null;
+    lockedUntil: Raw | null;
+    /** The buy's member quote, as the family's `members[].quoteAsset`. */
+    quoteAsset: QuoteAssetView | null;
+    /**
+     * The USD value of `quoteIn` at the buy's block, an 18-place decimal string, when the index proves the rate (USDG is
+     * one dollar; any other quote through tracked Hookr pools against USDG, or against ETH and then ETH/USDG); else null.
+     */
+    quoteInUsd: string | null;
+}
+/**
+ * A family member's quote as the service reports it: symbol, decimals and class from reviewed sources only (native
+ * ETH, the manifest's tokens, the SDK catalog, the stock scan). `decimals` is null when none names it: raw amounts
+ * in that quote cannot be formatted.
+ */
+export interface QuoteAssetView {
+    address: Address;
+    symbol: string | null;
+    decimals: number | null;
+    class: "native" | "weth" | "stable" | "hookr" | "listed" | "rwa" | "erc20";
+    source: "native" | "manifest" | "catalog" | "stock-scan" | "unknown";
+}
+export interface FamilyView {
+    id: Hash;
+    launcher: Address;
+    owner: Address;
+    creator: Address;
+    subject: Address;
+    root: Address;
+    launchedAt: Raw;
+    launchBlock: Raw;
+    launchTx: Hash;
+    members: {
+        member: number;
+        poolId: Hash;
+        quote: Address;
+        liquidity: Raw;
+        quoteAsset: QuoteAssetView;
+    }[];
+    /** Null when the index holds no PoolManager logs for the family's pools; `creatorBuysUnavailable` says why. */
+    creatorBuys: CreatorBuyView[] | null;
+    /**
+     * Why `creatorBuys` is null, else null. `root-not-pinned`: the family's root is not a manifest root pin covering its
+     * launch block (a root the registry admitted after the manifest was reviewed). `pool-not-tracked`: a member pool's
+     * Initialize was not indexed. Either way the launch transaction's Swaps were never stored.
+     */
+    creatorBuysUnavailable: "root-not-pinned" | "pool-not-tracked" | null;
+}
+export interface AccountProgramView {
+    id: Raw;
+    issuer: Address;
+    globalBux: boolean;
+    name: string;
+    pointDecimals: number;
+    points: Raw;
+    cashAllocated: Raw;
+    cashClaimable: Raw;
+    rewardToken: Address;
+    /** False when a scope names an unpinned root, display text exceeds service bounds or the policy is unknown. */
+    qualified?: boolean;
+    days: {
+        day: Raw;
+        status: string;
+        reviewStatus: "draft" | "reviewed";
+        weight: Raw;
+        nominalPoints: Raw;
+        nominalCash: Raw;
+        payer: Address;
+        proof: Hash[];
+        coverageHash: Hash;
+        root: Hash;
+        award: Record<string, unknown>;
+    }[];
+    nfts: {
+        milestone: Raw;
+        tokenId: Raw;
+        delivered: boolean;
+    }[];
+}
+export interface CommissionDayView {
+    day: Raw;
+    status: string;
+    reviewStatus: "draft" | "reviewed";
+    eligibleFees: Raw;
+    commission: Raw;
+    cashback: Raw;
+    payer: Address;
+    referrer: Address;
+    firstActivityBlock: Raw;
+    proof: Hash[];
+    coverageHash: Hash;
+    collectionsHash: Hash;
+    root: Hash;
+}
+export interface AccountView {
+    address: Address;
+    coverage: Coverage;
+    /** Only programs this account has indexed activity or an allocation award in. */
+    programs: AccountProgramView[];
+    /** Programs this account took part in whose definition the service does not serve, with the reason. */
+    unavailablePrograms?: {
+        id: Raw;
+        reason: string;
+    }[];
+    /** Lists cut to the most recent entries ("programs", "campaigns", "bindings"); totals stay complete. */
+    truncated?: string[];
+    referrals: {
+        bindings: Record<string, unknown>[];
+        bindingCount?: number;
+        campaigns: {
+            id: Raw;
+            distributor: Address;
+            programKey: Hash;
+            currency: Address;
+            qualified?: boolean;
+            commissionEarned: Raw;
+            cashbackEarned: Raw;
+            days: CommissionDayView[];
+        }[];
+        unavailableCampaigns?: {
+            id: Raw;
+            reason: string;
+        }[];
+        claimables: {
+            distributor: Address;
+            currency: Address;
+            allocated: Raw;
+            paid: Raw;
+            claimable: Raw;
+        }[];
+    };
+}
+export type ClaimAction = {
+    type: "claimDay" | "claimReferralDay";
+    programId: Raw;
+    day: Raw;
+    beneficiary: Address | null;
+    payer: Address | null;
+    referrer: Address | null;
+    firstActivityBlock: Raw | null;
+    weight: Raw;
+    proof: Hash[];
+} | {
+    type: "creditDay";
+    campaignId: Raw;
+    day: Raw;
+    payer: Address;
+    referrer: Address;
+    firstActivityBlock: Raw;
+    eligibleFees: Raw;
+    proof: Hash[];
+};
+export interface ProofView {
+    allocation: Record<string, unknown>;
+    award: Record<string, unknown>;
+    onchainStatus: string;
+    localReview: boolean;
+    action: ClaimAction | null;
+}

package/dist/core/schema.js

@@ -0,0 +1,105 @@
+export const ZERO = "0x0000000000000000000000000000000000000000";
+export const ZERO_HASH = `0x${"0".repeat(64)}`;
+export function assert(ok, message) {
+    if (!ok)
+        throw new Error(message);
+}
+export function address(value, zero = false) {
+    assert(typeof value === "string" && /^0x[\da-fA-F]{40}$/.test(value), "Invalid address");
+    assert(zero || value.toLowerCase() !== ZERO, "Zero address");
+    return value.toLowerCase();
+}
+export function hash(value) {
+    assert(typeof value === "string" && /^0x[\da-fA-F]{64}$/.test(value), "Invalid hash");
+    return value.toLowerCase();
+}
+export function uint(value, bits = 256) {
+    assert((typeof value === "string" && /^(0|[1-9]\d*)$/.test(value)) || typeof value === "bigint", "Expected raw integer string");
+    const n = BigInt(value);
+    assert(n >= 0n && n < 1n << BigInt(bits), "Integer overflow");
+    return n;
+}
+export function canonical(value) {
+    if (typeof value === "bigint")
+        return JSON.stringify(value.toString());
+    if (value === null || typeof value !== "object") {
+        const result = JSON.stringify(value);
+        assert(result !== undefined, "Undefined is not canonical");
+        return result;
+    }
+    if (Array.isArray(value))
+        return `[${value.map(canonical).join(",")}]`;
+    return `{${Object.keys(value)
+        .sort()
+        .map((k) => `${JSON.stringify(k)}:${canonical(value[k])}`)
+        .join(",")}}`;
+}
+/** Every manifest source role. `root` and `rules` may repeat; every other role is a singleton. */
+export const CONTRACT_ROLES = [
+    "poolManager",
+    "registry",
+    "root",
+    "rules",
+    "router",
+    "quoter",
+    "launcher",
+    "treasury",
+    "programs",
+    "referrals",
+    "commissions",
+    "forwarder",
+    "positionManager",
+    "rootFactory",
+    "feeAdvisory",
+    "sessionAdvisory",
+    "liquidityVault",
+];
+export function deployment(value) {
+    const m = value;
+    assert(m?.schema === "hookr.engagement.sources.v1", "Unknown manifest schema");
+    uint(m.chainId);
+    assert(uint(m.chainId) > 0n && uint(m.startBlock) > 0n, "Invalid chain/start block");
+    hash(m.parentHash);
+    assert(uint(m.startBlock) <= BigInt(Number.MAX_SAFE_INTEGER), "Block height overflow");
+    assert(typeof m.releaseId === "string" && /^[a-z0-9-]{1,80}$/.test(m.releaseId), "Invalid releaseId");
+    assert(m.qualification?.status === "verified" && /^[\da-f]{40}$/.test(m.qualification.sourceCommit), "Unqualified release");
+    hash(m.qualification.evidenceHash);
+    assert(Array.isArray(m.contracts) && m.contracts.length > 0 && m.contracts.length <= 64, "Invalid sources");
+    const seen = new Set();
+    for (const role of CONTRACT_ROLES.filter((r) => r !== "root" && r !== "rules"))
+        assert(m.contracts.filter((c) => c.role === role).length <= 1, `Duplicate singleton ${role}`);
+    for (const token of m.tokens ?? []) {
+        address(token.address, true);
+        assert(typeof token.symbol === "string" &&
+            token.symbol.length <= 32 &&
+            Number.isInteger(token.decimals) &&
+            token.decimals >= 0 &&
+            token.decimals <= 255, "Invalid token metadata");
+    }
+    for (const c of m.contracts) {
+        assert(CONTRACT_ROLES.includes(c.role), "Unknown source role");
+        assert(c.address === address(c.address), "Manifest source addresses must be lowercase");
+        hash(c.runtimeHash);
+        assert(c.runtimeHash !== ZERO_HASH, "Missing runtime hash");
+        assert(uint(c.startBlock) >= uint(m.startBlock) && uint(c.startBlock) <= BigInt(Number.MAX_SAFE_INTEGER), "Source coverage height invalid");
+        assert(!seen.has(c.address), "Duplicate source");
+        seen.add(c.address);
+    }
+    for (const rule of m.commissionAuthorities ?? []) {
+        address(rule.rules);
+        assert(rule.feeSource === 0 || rule.feeSource === 1, "Invalid fee authority source");
+        assert(m.contracts.some((c) => c.role === "rules" && c.address === rule.rules.toLowerCase()), "Unpinned fee authority");
+        assert(Array.isArray(rule.creators) && rule.creators.length > 0 && rule.creators.length <= 32, "Invalid fee authority creators");
+        rule.creators.forEach((c) => address(c));
+    }
+    if (m.payerCodeHashes !== undefined) {
+        assert(Array.isArray(m.payerCodeHashes) && m.payerCodeHashes.length <= 32, "Invalid payer code allow-list");
+        for (const h of m.payerCodeHashes) {
+            hash(h);
+            assert(h === h.toLowerCase() && h !== ZERO_HASH, "Invalid payer code hash");
+        }
+    }
+    for (const role of ["poolManager", "root", "router", "launcher", "programs"])
+        assert(m.contracts.some((c) => c.role === role), `Missing ${role}`);
+    return m;
+}

package/dist/core/stocks.generated.d.ts

@@ -0,0 +1,11 @@
+import type { Address } from "./schema.js";
+/** One Robinhood stock token: its address, onchain symbol and name, and the block its proxy was created in. */
+export interface StockToken {
+    address: Address;
+    symbol: string;
+    name: string;
+    createdBlock: number;
+}
+/** The last block the stock scan read. A proxy created after it is still classified by its beacon slot. */
+export declare const ROBINHOOD_STOCK_SCAN_BLOCK = 73819564;
+export declare const ROBINHOOD_STOCK_TOKENS: readonly StockToken[];