@chipi-stack/chipi-react 14.7.0 → 14.9.0

package/dist/multisig.d.mts

@@ -0,0 +1,482 @@
+import * as _tanstack_react_query from '@tanstack/react-query';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import React from 'react';
+
+/**
+ * Framework-agnostic action-template engine for SHHH multisig governance.
+ *
+ * An {@link ActionTemplate} maps friendly, typed form fields → an
+ * OutsideExecution call list + a human-readable title. It's the seam that
+ * turns "call any contract" (powerful, scary) into "fill in this form"
+ * (founder-grade) — and the whitelabel seam: every integrator registers
+ * its own templates (Roca: create_pool / borrow / repay), while `Vote`
+ * ships built-in. The raw-call escape hatch lives in the UI layer, not
+ * here, because its arguments are open-ended.
+ *
+ * Pure: no React, no network — so the same template renders the proposer's
+ * form, every approver's inbox, and the notification, from one source of
+ * truth, and `toCalls` is deterministic (proposer and executor build the
+ * identical OE → the hash matches).
+ */
+type FeltLike = string | number | bigint;
+/** One call in an action — the shape the OE builder consumes. */
+interface CallSpec {
+    to: string;
+    entrypoint: string;
+    /** Flat 0x-hex felts. */
+    calldata: string[];
+}
+/** A typed input in an action template. */
+type FieldSpec = {
+    name: string;
+    label: string;
+    type: "amount";
+    decimals: number;
+    help?: string;
+} | {
+    name: string;
+    label: string;
+    type: "address";
+    help?: string;
+} | {
+    name: string;
+    label: string;
+    type: "number" | "bps" | "days" | "felt";
+    help?: string;
+} | {
+    name: string;
+    label: string;
+    type: "select";
+    options: {
+        label: string;
+        value: string;
+    }[];
+    help?: string;
+} | {
+    name: string;
+    label: string;
+    type: "text";
+    help?: string;
+};
+interface ActionTemplate<V = Record<string, unknown>> {
+    /** Stable id, persisted on the proposal. */
+    key: string;
+    /** Display label ("Create pool"). */
+    label: string;
+    description?: string;
+    /** Typed inputs rendered by `<ProposeAction>`. */
+    fields: FieldSpec[];
+    /** Pure: validated field values → the OE call list. */
+    toCalls: (v: V) => CallSpec[];
+    /** Pure: the plain-language title shown in the preview, inbox, and email. */
+    title: (v: V) => string;
+    /** Optional metadata persisted with the proposal so the approver's app
+     *  can render business context (e.g. `{ poolId }`). */
+    meta?: (v: V) => Record<string, string | number>;
+    /** App-level risk tier (decision §11.4). When the treasury configured the
+     *  matching quorum, the backend OVERRIDES requiredApprovals at propose
+     *  (ROUTINE → routineQuorum, SENSITIVE → sensitiveQuorum). App-enforced
+     *  for human treasuries — the on-chain wallet threshold stays the hard
+     *  floor at execute. Omit = no tier (the client's value is used). */
+    risk?: "ROUTINE" | "SENSITIVE";
+}
+/** Starknet felt252 field prime — args must be a non-negative felt below it. */
+declare const FELT_PRIME: bigint;
+/** Parse a decimal or 0x-hex value to a canonical `0x` felt. Throws on a
+ *  non-numeric or out-of-range value. */
+declare function toFelt(v: FeltLike): string;
+/** Split a u256 value into its `[low, high]` felts (Cairo calling convention). */
+declare function u256(v: FeltLike): [string, string];
+/** Convert a human amount ("10.5") to base units given a token's decimals. */
+declare function amountToBase(amount: string, decimals: number): bigint;
+/**
+ * Identity + light validation for a template registry: keys are present
+ * and unique. Returns the same array (typed) so call sites keep inference.
+ */
+declare function defineActions<T extends ActionTemplate<any>[]>(templates: [...T]): [...T];
+interface VoteValues {
+    contract: string;
+    proposalId: string;
+    choice: string;
+}
+/**
+ * Built-in `Vote` template — `vote(proposalId, choice)` on a governance
+ * contract. Pin the contract and/or entrypoint up front (then they drop
+ * out of the form), or leave them for the proposer to fill.
+ */
+declare function voteTemplate(opts?: {
+    governanceContract?: string;
+    entrypoint?: string;
+}): ActionTemplate<VoteValues>;
+
+/** shortString.encodeShortString("SN_MAIN") — Starknet mainnet. */
+declare const SN_MAIN_CHAIN_ID = "0x534e5f4d41494e";
+/**
+ * Max on-chain OE validity window (`executeBefore - executeAfter`), capped
+ * by the SHHH contract audit (M-2). This is the longest a proposal stays
+ * EXECUTABLE — distinct from how long its record lives in the coordination
+ * backend. NOTE: with `executeAfter` pinned to 0 the window would be the
+ * whole epoch and the contract rejects it, so `executeAfter` is set to ~now
+ * and persisted alongside the nonce + `executeBefore`.
+ */
+declare const OE_WINDOW_SECONDS: number;
+/**
+ * Signs an OE message hash for one owner → that owner's inner V2_SNIP12
+ * envelope (an array of felts). Implementations wrap a passkey / MetaMask /
+ * Phantom / STARK signer; the private key never leaves the implementation.
+ */
+type OeSigner = (params: {
+    messageHash: bigint;
+    ownerIndex: bigint;
+}) => Promise<bigint[]> | bigint[];
+/** Serialize an inner envelope (felt[]) to the comma-joined 0x-hex string
+ *  the coordination backend stores per signature. */
+declare function serializeEnvelope(env: bigint[]): string;
+declare function deserializeEnvelope(s: string): bigint[];
+/**
+ * OE replay nonce: ms timestamp shifted left 24 bits, ORed with a 24-bit
+ * random suffix. `nowMs`/`rand` are injectable for deterministic tests.
+ */
+declare function newOeNonce(nowMs: number, rand: number): bigint;
+interface ActionProposal {
+    oeMessageHash: string;
+    oeNonce: string;
+    oeExecuteBefore: string;
+    /** The proposer's inner V2_SNIP12 envelope, comma-joined 0x-hex. */
+    proposerSignature: string;
+}
+/** Derive the OE's executeAfter from its persisted executeBefore. The
+ *  window is a fixed constant (the contract cap), so the executor needs
+ *  only executeBefore to reconstruct the exact signed OE — no separate
+ *  executeAfter persistence (and no backend column). */
+declare function deriveExecuteAfter(oeExecuteBefore: string): bigint;
+/**
+ * Build an OE over `calls`, sign it as the proposer (owner 0 by default),
+ * and return everything a propose endpoint needs. The OE params (nonce +
+ * executeBefore) are returned; executeAfter is `executeBefore - OE_WINDOW`,
+ * so only executeBefore needs persisting. The window is the contract cap
+ * (the longest executable window M-2 allows).
+ */
+declare function buildActionProposal(params: {
+    walletAddress: string;
+    calls: CallSpec[];
+    sign: OeSigner;
+    ownerIndex?: bigint;
+    chainId?: string;
+    nowMs?: number;
+    rand?: number;
+}): Promise<ActionProposal>;
+/** Sign an existing proposal's OE hash as an approver → inner envelope string. */
+declare function signActionApproval(params: {
+    oeMessageHash: string;
+    ownerIndex: bigint;
+    sign: OeSigner;
+}): Promise<string>;
+/**
+ * Rebuild the exact OE from the persisted params + collected signatures and
+ * serialize the `execute` calldata. A 1-of-N wallet uses the single inner
+ * envelope; N≥2 wraps the inner envelopes in a V2_THRESHOLD envelope.
+ */
+declare function assembleActionExecuteCalldata(params: {
+    calls: CallSpec[];
+    oeNonce: string;
+    oeExecuteBefore: string;
+    signatures: string[];
+    requiredApprovals: number;
+}): string[];
+
+/**
+ * Injectable boundaries for the multisig governance hooks. The package owns
+ * the OE crypto + template engine + orchestration; the host supplies the
+ * transport (an authed coordination backend) and the signer (a per-owner
+ * OE signer + owner-index resolution). This keeps the package auth- and
+ * chain-agnostic: the dashboard wires Clerk today; the owner-signature SDK
+ * client wires it for integrators at P1.
+ */
+
+/** One owner's collected signature on a proposal. */
+interface ProposalSignature {
+    ownerId: number;
+    signerKind: string;
+    /** The owner's serialized inner V2_SNIP12 envelope (comma-joined felts). */
+    signature: string;
+}
+/** A treasury proposal as returned by the coordination backend. */
+interface TreasuryProposal {
+    id: string;
+    /** Set for generalized actions (vote / call any contract). */
+    calls?: {
+        to: string;
+        entrypoint: string;
+        calldata: string[];
+    }[] | null;
+    /** Human label for an action ("Vote YES on Proposal #5"). */
+    title?: string | null;
+    /** Arbitrary integrator context (e.g. `{ poolId }`). */
+    meta?: Record<string, string | number> | null;
+    /** App-level risk tier the proposal was filed under (null = none). */
+    risk?: "ROUTINE" | "SENSITIVE" | null;
+    oeMessageHash: string;
+    oeNonce: string | null;
+    oeExecuteBefore: string | null;
+    requiredApprovals: number;
+    status: "PROPOSED" | "APPROVED" | "EXECUTED" | "CANCELED" | "EXPIRED";
+    executedTxHash?: string | null;
+    signatures: ProposalSignature[];
+}
+/** The body the coordination backend's `propose` endpoint accepts. */
+interface ProposeBody {
+    proposerOwnerId: number;
+    recipient: string;
+    tokenAddress: string;
+    amount: string;
+    title: string;
+    calls: {
+        to: string;
+        entrypoint: string;
+        calldata: string[];
+    }[];
+    meta?: Record<string, string | number>;
+    /** Template risk tier — lets the backend apply the treasury's quorum policy. */
+    risk?: "ROUTINE" | "SENSITIVE";
+    oeMessageHash: string;
+    oeNonce: string;
+    oeExecuteBefore: string;
+    requiredApprovals: number;
+    proposerSignature: string;
+    proposerSignerKind: string;
+}
+/** The coordination backend (propose / list / sign / execute), host-wired. */
+interface MultisigTransport {
+    list(): Promise<{
+        items: TreasuryProposal[];
+    }>;
+    propose(body: ProposeBody): Promise<TreasuryProposal>;
+    sign(proposalId: string, body: {
+        ownerId: number;
+        signature: string;
+        signerKind: string;
+    }): Promise<unknown>;
+    execute(proposalId: string, calldata: string[]): Promise<{
+        executedTxHash?: string;
+        transactionHash?: string;
+    }>;
+}
+/**
+ * A per-owner OE signer. `sign` produces this device's inner envelope (key
+ * never leaves it). `resolveOwnerIndex` maps the device's credential to its
+ * position in the on-chain owner set (for approving as a non-proposer).
+ */
+interface MultisigSigner {
+    /** ShhhSignerKind, e.g. "WEBAUTHN_P256" / "STARK" / "EIP191_SECP256K1". */
+    signerKind: string;
+    /** Owner index this device proposes as (the bootstrap owner; default 0). */
+    proposerOwnerIndex?: number;
+    sign: OeSigner;
+    resolveOwnerIndex(walletAddress: string): Promise<number>;
+}
+
+/**
+ * Pure orchestration for the multisig governance flow — build a propose
+ * body, build an approval, assemble execute calldata. No React, no network:
+ * the hooks (`use-hooks.ts`) wrap these in mutations/queries, and they're
+ * directly unit-testable with a mock signer + injected `nowMs`/`rand`.
+ */
+
+/**
+ * Build a propose body for a template + its validated field values: derive
+ * the call(s) + title (+ meta), build & proposer-sign the OE, and shape the
+ * body the coordination backend expects. For an action the payment fields
+ * are placeholders (recipient/token = the first call's target, amount "0");
+ * the real intent rides in `calls` + `title`.
+ */
+declare function createProposal<V>(params: {
+    template: ActionTemplate<V>;
+    values: V;
+    walletAddress: string;
+    requiredApprovals: number;
+    signer: MultisigSigner;
+    chainId?: string;
+    nowMs?: number;
+    rand?: number;
+}): Promise<ProposeBody>;
+/**
+ * Build an approver's signature on an existing proposal: resolve this
+ * device's owner index from chain, then sign the SAME OE hash.
+ */
+declare function buildApproval(params: {
+    proposal: Pick<TreasuryProposal, "oeMessageHash">;
+    walletAddress: string;
+    signer: MultisigSigner;
+}): Promise<{
+    ownerId: number;
+    signature: string;
+    signerKind: string;
+}>;
+/**
+ * Assemble the execute calldata from a proposal's persisted call(s) + its
+ * collected signatures (sorted by owner index). Requires `calls` — this is
+ * the generalized-action flow; a host with payment-only proposals supplies
+ * the transfer calls.
+ */
+declare function buildExecuteCalldata(proposal: TreasuryProposal): string[];
+
+interface ProposeInput {
+    template: ActionTemplate<any>;
+    values: any;
+}
+/**
+ * Propose a templated action: build the call(s) + title from the template,
+ * passkey-/key-sign the OE as the proposer, and submit it. `getRequiredApprovals`
+ * supplies the wallet's threshold (the host reads it from chain — the package
+ * stays chain-agnostic).
+ */
+declare function useProposeAction(config: {
+    walletAddress: string;
+    transport: MultisigTransport;
+    signer: MultisigSigner;
+    getRequiredApprovals: () => Promise<number>;
+    chainId?: string;
+}): _tanstack_react_query.UseMutationResult<TreasuryProposal, Error, ProposeInput, unknown>;
+/**
+ * List a treasury's proposals and expose approve / execute mutations. An
+ * approver signs the same OE hash as their resolved owner index; once enough
+ * approvals are collected, execute rebuilds the OE from the persisted call(s)
+ * and relays it.
+ */
+declare function useTreasuryProposals(config: {
+    walletAddress: string;
+    transport: MultisigTransport;
+    signer: MultisigSigner;
+}): {
+    proposals: _tanstack_react_query.UseQueryResult<{
+        items: TreasuryProposal[];
+    }, Error>;
+    approve: _tanstack_react_query.UseMutationResult<unknown, Error, TreasuryProposal, unknown>;
+    execute: _tanstack_react_query.UseMutationResult<{
+        executedTxHash?: string;
+        transactionHash?: string;
+    }, Error, TreasuryProposal, unknown>;
+};
+
+/**
+ * Theming for the embeddable governance components (design brief §8).
+ *
+ * One mechanism: every component root carries inline CSS variables derived
+ * from a `theme` prop merged over the defaults, and a single namespaced
+ * stylesheet (injected once at runtime) styles everything off those vars.
+ * Integrators theme by passing tokens — `<Approvals theme={{ accent:
+ * "#0f766e", radius: "0.375rem" }} />` — and the components render native
+ * to the host app. No Tailwind/CSS-import requirement; SSR-safe (the
+ * stylesheet injects in an effect, and first paint is already var-driven).
+ *
+ * Default skin = the Chipi neobrutalism system: bold borders, hard offset
+ * shadow, high-contrast text.
+ */
+interface ChipiGovTheme {
+    /** Primary action color (buttons, focus, progress). */
+    accent?: string;
+    /** Text color on the accent. */
+    accentText?: string;
+    /** Card/dialog background. */
+    surface?: string;
+    /** Page-muted background (rows, inputs). */
+    surfaceMuted?: string;
+    /** Primary text. */
+    text?: string;
+    /** Secondary text. */
+    textMuted?: string;
+    /** Error/destructive color. */
+    danger?: string;
+    /** Success color (executed, looks-good). */
+    success?: string;
+    /** Border color. */
+    border?: string;
+    /** Corner radius (any CSS length). */
+    radius?: string;
+    /** Hard offset shadow (set to "none" for flat hosts). */
+    shadow?: string;
+    /** Font stack. */
+    font?: string;
+}
+declare const DEFAULT_THEME: Required<ChipiGovTheme>;
+/** Inline CSS-var style object for a component root. */
+declare function themeVars(theme?: ChipiGovTheme): Record<string, string>;
+/** Idempotently inject the component stylesheet into the document head. */
+declare function injectGovStyles(): void;
+
+/** Light per-type syntax check; returns a human error or null. */
+declare function fieldSyntaxError(field: FieldSpec, raw: string): string | null;
+declare function FieldInput(props: {
+    field: FieldSpec;
+    value: string;
+    onChange: (raw: string) => void;
+    /** Shown once the user has touched the field. */
+    error?: string | null;
+    disabled?: boolean;
+}): react_jsx_runtime.JSX.Element;
+
+interface ProposeActionProps {
+    /** The treasury's SHHH wallet address. */
+    walletAddress: string;
+    /** Action templates the proposer can pick from (`defineActions(...)`). */
+    actions: ActionTemplate<any>[];
+    transport: MultisigTransport;
+    signer: MultisigSigner;
+    /** Read the wallet's current threshold (host-supplied; chain read). */
+    getRequiredApprovals: () => Promise<number>;
+    /** Preselect a template by key (also hides the tabs when it's the only one). */
+    preselect?: string;
+    /** Custom trigger; receives the open callback. Defaults to a button. */
+    trigger?: (open: () => void) => React.ReactNode;
+    theme?: ChipiGovTheme;
+    onProposed?: (proposal: TreasuryProposal) => void;
+    chainId?: string;
+}
+declare function ProposeAction(props: ProposeActionProps): react_jsx_runtime.JSX.Element;
+
+type ApprovalsFilter = "actionable" | "pending" | "all";
+interface ApprovalsProps {
+    /** The treasury's SHHH wallet address. */
+    walletAddress: string;
+    transport: MultisigTransport;
+    signer: MultisigSigner;
+    /** Inject business context per row (reads `proposal.meta`). */
+    renderContext?: (proposal: TreasuryProposal) => React.ReactNode;
+    /** actionable = needs me or ready; pending = not terminal; all. Default actionable. */
+    filter?: ApprovalsFilter;
+    theme?: ChipiGovTheme;
+    onExecuted?: (proposal: TreasuryProposal, txHash?: string) => void;
+    /** Custom empty state. */
+    empty?: React.ReactNode;
+    /** Build an explorer URL for an executed tx hash (row link). */
+    explorerTxUrl?: (txHash: string) => string;
+    /**
+     * Mark a proposal as filed by an AI agent (governance §9). When this
+     * returns true, the row reads "{agentLabel} wants: {title}" with an
+     * Agent chip — the founder-facing "your agent wants…" copy. The host
+     * decides agent-ness (it knows which owner index is its agent); the
+     * package stays chain-read-free.
+     */
+    isAgentProposal?: (proposal: TreasuryProposal) => boolean;
+    /** Label for agent rows (default "Agent"). */
+    agentLabel?: string;
+}
+/** Human fallback title for legacy payment proposals without `title`. */
+declare function proposalTitle(p: TreasuryProposal): string;
+declare function Approvals(props: ApprovalsProps): react_jsx_runtime.JSX.Element;
+
+interface InboxTreasury extends Pick<ApprovalsProps, "walletAddress" | "transport" | "signer" | "renderContext" | "explorerTxUrl" | "isAgentProposal" | "agentLabel"> {
+    /** Group heading ("Ops treasury", "Acme · Pool fund"). */
+    label: string;
+}
+interface ApprovalInboxProps {
+    treasuries: InboxTreasury[];
+    theme?: ChipiGovTheme;
+    /** Shown when every treasury is caught up. */
+    onEmpty?: React.ReactNode;
+    onExecuted?: (treasury: InboxTreasury, proposal: TreasuryProposal, txHash?: string) => void;
+}
+declare function ApprovalInbox(props: ApprovalInboxProps): react_jsx_runtime.JSX.Element;
+
+export { type ActionProposal, type ActionTemplate, ApprovalInbox, type ApprovalInboxProps, Approvals, type ApprovalsFilter, type ApprovalsProps, type CallSpec, type ChipiGovTheme, DEFAULT_THEME, FELT_PRIME, type FeltLike, FieldInput, type FieldSpec, type InboxTreasury, type MultisigSigner, type MultisigTransport, OE_WINDOW_SECONDS, type OeSigner, type ProposalSignature, ProposeAction, type ProposeActionProps, type ProposeBody, type ProposeInput, SN_MAIN_CHAIN_ID, type TreasuryProposal, type VoteValues, amountToBase, assembleActionExecuteCalldata, buildActionProposal, buildApproval, buildExecuteCalldata, createProposal, defineActions, deriveExecuteAfter, deserializeEnvelope, fieldSyntaxError, injectGovStyles, newOeNonce, proposalTitle, serializeEnvelope, signActionApproval, themeVars, toFelt, u256, useProposeAction, useTreasuryProposals, voteTemplate };