@chipi-stack/chipi-react 14.6.0 → 14.8.0

package/README.md

@@ -58,9 +58,50 @@ function Wallet() {
 - **In-app token transfer UIs** — send and receive USDC with a few lines of React
 - **Connect-with-passkey flows** — biometric wallet login without seed phrases
 - **DeFi dashboards and loyalty/rewards redemption interfaces** — display balances, history, and reward claims
+- **Multisig treasury governance** — propose/approve/execute any contract action with N-of-M approvals (see `/multisig` below)
 
 Have an idea? [Tell us what you want to build](https://github.com/chipi-pay/build-with-chipi/issues/new)
 
+## Multisig governance (`@chipi-stack/chipi-react/multisig`)
+
+> Tree-shakeable subpath for SHHH multisig: propose any contract action (or a vote), collect N-of-M approvals, execute. Experimental — the API may change.
+
+Describe your actions once as typed templates, then drive them with hooks. The hooks are auth- and chain-agnostic: you pass a `MultisigTransport` (your coordination backend) and a `MultisigSigner` (per-owner OE signer), and own the UI.
+
+```tsx
+import {
+  defineActions, voteTemplate, u256, toFelt,
+  useProposeAction, useTreasuryProposals,
+  type MultisigTransport, type MultisigSigner,
+} from "@chipi-stack/chipi-react/multisig";
+
+// 1. Register your action templates (vote ships built-in).
+const ACTIONS = defineActions([
+  voteTemplate({ governanceContract: "0x…" }),
+  {
+    key: "stake",
+    label: "Stake",
+    fields: [{ name: "amount", label: "Amount", type: "amount", decimals: 18 }],
+    toCalls: (v) => [{ to: "0x…", entrypoint: "stake", calldata: u256(v.amount) }],
+    title: (v) => `Stake ${v.amount}`,
+  },
+]);
+
+// 2. Propose → approve → execute (you supply transport + signer).
+function Governance({ walletAddress, transport, signer }: {
+  walletAddress: string; transport: MultisigTransport; signer: MultisigSigner;
+}) {
+  const propose = useProposeAction({
+    walletAddress, transport, signer,
+    getRequiredApprovals: async () => 2, // read your wallet's threshold
+  });
+  const { proposals, approve, execute } = useTreasuryProposals({ walletAddress, transport, signer });
+  // render your own UI on top of these
+}
+```
+
+The pure pieces — `defineActions`, `voteTemplate`, the `toFelt`/`u256`/`amountToBase` encoders, and the OE core (`buildActionProposal`/`signActionApproval`/`assembleActionExecuteCalldata`) — have no React or network dependency, so templates and calldata are unit-testable in isolation.
+
 ## Documentation
 
 Full docs at [docs.chipipay.com](https://docs.chipipay.com)

package/dist/multisig.d.mts

@@ -0,0 +1,350 @@
+import * as _tanstack_react_query from '@tanstack/react-query';
+
+/**
+ * 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>;
+}
+/** 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;
+    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>;
+    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>;
+};
+
+export { type ActionProposal, type ActionTemplate, type CallSpec, FELT_PRIME, type FeltLike, type FieldSpec, type MultisigSigner, type MultisigTransport, OE_WINDOW_SECONDS, type OeSigner, type ProposalSignature, type ProposeBody, type ProposeInput, SN_MAIN_CHAIN_ID, type TreasuryProposal, type VoteValues, amountToBase, assembleActionExecuteCalldata, buildActionProposal, buildApproval, buildExecuteCalldata, createProposal, defineActions, deriveExecuteAfter, deserializeEnvelope, newOeNonce, serializeEnvelope, signActionApproval, toFelt, u256, useProposeAction, useTreasuryProposals, voteTemplate };