@bananapus/nana-sdk-core 2.23.0 → 2.24.1

package/dist/cjs/review/safeRelayr.d.ts

@@ -0,0 +1,144 @@
+import { type Address, type Hex, type PublicClient } from "viem";
+import { type SafeTransactionMessage } from "../safeService.js";
+import { type RelayrEntry, type RelayrPayment, type RelayrQuote, type RelayrReleaseClient, type RelayrSentPayment, type RelayrTransactionRecord, type RelayrTransactionBinding, type RelayrProofClient, type RelayrVerifiedDestination } from "./relayr.js";
+/** Exact frozen calldata plus the Safe intent it executes. Context belongs to the app. */
+export type SafeRelayrExecution = {
+    entry: RelayrEntry;
+    safe: Address;
+    safeTxHash: Hex;
+    nonce: number;
+    context?: unknown;
+};
+/** Normalized durable state. Adapters retain their existing storage schema and metadata. */
+export type SafeRelayrSession = {
+    id: string;
+    account: Address;
+    executions: SafeRelayrExecution[];
+    quote?: RelayrQuote;
+    bundleUuid?: string;
+    paymentStatus: "unfunded" | "sending" | "submitted" | "confirmed" | "reverted" | "expired";
+    payments: RelayrSentPayment[];
+    state: "publishing" | "active" | "complete" | "released";
+    /** Obsolete Safe nonces do not prove execution success, quote expiry, or a refund. */
+    releaseReason?: "quote-expired" | "safe-nonces-consumed";
+    createdAt: number;
+    records?: RelayrTransactionRecord[];
+    /** Conservative legacy reservations when exact execution proof is unavailable. */
+    reservationKeys?: string[];
+    context?: unknown;
+};
+export type SafeRelayrStore = {
+    /** Include unresolved legacy reservations, including those made by other accounts. */
+    list(account: Address): Promise<SafeRelayrSession[]>;
+    /** Must finish durable persistence before resolving; never silently swallow failure. */
+    save(session: SafeRelayrSession): Promise<void>;
+    /** Serialize overlapping Safe scopes across tabs AND accounts. An account-only lock is insufficient; retain legacy locks too. */
+    withLock<T>(account: Address, run: () => Promise<T>): Promise<T>;
+};
+export type SafeRelayrResult = {
+    state: "ready" | "pending" | "complete" | "released";
+    session: SafeRelayrSession;
+    payments: RelayrPayment[];
+    recovery?: SafeRelayrRecovery;
+};
+/** Read-only evidence when the saved publication cannot identify an exact quote. */
+export type SafeRelayrRecovery = {
+    reason: "missing-execution-proof" | "safe-nonces-live" | "safe-nonces-mixed" | "safe-nonces-unavailable" | "safe-nonces-consumed" | "funding-unresolved";
+    message: string;
+    checks?: {
+        chainId: number;
+        safe: Address;
+        nonce: number;
+        currentNonce?: string;
+        state: "consumed" | "live" | "unavailable";
+    }[];
+};
+export type SafeRelayrReady = SafeRelayrResult & {
+    state: "ready";
+    resumed: boolean;
+};
+export type SafeRelayrStatus = (index: number, state: "checking" | "ready" | "rechecking" | "failed", execution: SafeRelayrExecution) => void;
+export type SafeRelayrOptions = {
+    store: SafeRelayrStore;
+    clientFor: (chainId: number) => (RelayrReleaseClient & Partial<Pick<PublicClient, "request">>) | undefined;
+    fetch?: typeof globalThis.fetch;
+    currentAccount: () => Address | undefined;
+    /** Check live Safe nonce/policy, app permissions, and simulate this ORIGINAL calldata. */
+    revalidate: (execution: SafeRelayrExecution, account: Address) => Promise<void>;
+    /** Explicit user review of precisely these frozen calls. No wallet submission. */
+    review: (executions: readonly SafeRelayrExecution[], options: {
+        resumed: boolean;
+    }) => Promise<unknown>;
+    /**
+     * Guarded wallet adapter. Await beforeSend after wallet review, then onSending
+     * immediately before wallet invocation. Await onSent whenever a hash (including
+     * a replacement) becomes known. Retain the application's payment review,
+     * runtime authentication, simulation, and account checks.
+     */
+    sendPayment: (options: {
+        session: SafeRelayrSession;
+        payment: RelayrPayment;
+        beforeSend: () => Promise<void>;
+        onSending: () => Promise<void>;
+        onSent: (payments: RelayrSentPayment[]) => Promise<void>;
+    }) => Promise<{
+        hash: Hex;
+        payments: RelayrSentPayment[];
+    }>;
+    /** App receipt guards run only after every exact destination and Safe event is proven. */
+    afterVerified?: (execution: SafeRelayrExecution, verified: RelayrVerifiedDestination) => Promise<void>;
+    createId?: () => string;
+};
+export declare class SafeRelayrRecoveryError extends Error {
+    readonly session: SafeRelayrSession;
+    readonly recovery?: SafeRelayrRecovery | undefined;
+    readonly name = "SafeRelayrRecoveryError";
+    constructor(session: SafeRelayrSession, message?: string, recovery?: SafeRelayrRecovery | undefined);
+}
+/** A nonce reserves its Safe on its chain even when signature bytes or the proposed intent change. */
+export declare function safeRelayrReservationKey(execution: Pick<SafeRelayrExecution, "entry" | "safe" | "nonce">): string;
+/** Reuse requires the complete one-to-one intent set. Subsets and supersets conflict. */
+export declare function sameSafeRelayrIntents(left: readonly SafeRelayrExecution[], right: readonly SafeRelayrExecution[]): boolean;
+/** Authenticate execTransaction's signed fields against the expected Safe EIP-712 hash. */
+export declare function requireSafeRelayrExecution(execution: SafeRelayrExecution): SafeTransactionMessage;
+/** Exact live nonce/hash guards for adapters that perform eth_call preconditions. */
+export declare function safeRelayrPreconditions(execution: SafeRelayrExecution): {
+    address: Address;
+    data: Hex;
+    expected: Hex;
+}[];
+/** Canonical exact destination receipts plus matching, refund-free Safe success events. */
+export declare function verifySafeRelayrLanding(clientFor: (chainId: number) => RelayrProofClient | undefined, { executions, bindings, records, }: {
+    executions: readonly SafeRelayrExecution[];
+    bindings: readonly RelayrTransactionBinding[];
+    records: readonly RelayrTransactionRecord[];
+}): Promise<RelayrVerifiedDestination[]>;
+/** Shared Safe Relayr state machine. It never signs Safe proposals or submits on prepare/check. */
+export declare function createSafeRelayrController(options: SafeRelayrOptions): {
+    prepare: ({ account, executions: input, signal, onStatus, }: {
+        account: Address;
+        executions: readonly SafeRelayrExecution[];
+        signal?: AbortSignal;
+        onStatus?: SafeRelayrStatus;
+    }) => Promise<SafeRelayrReady>;
+    check: ({ account, sessionId, }: {
+        account: Address;
+        sessionId: string;
+    }) => Promise<SafeRelayrResult>;
+    fund: ({ account, sessionId, paymentChainId, signal, onStatus, }: {
+        account: Address;
+        sessionId: string;
+        paymentChainId: number;
+        signal?: AbortSignal;
+        onStatus?: SafeRelayrStatus;
+    }) => Promise<SafeRelayrResult>;
+    watch: ({ account, sessionId, signal, onUpdate, intervalMs, timeoutMs, }: {
+        account: Address;
+        sessionId: string;
+        signal?: AbortSignal;
+        onUpdate?: (result: SafeRelayrResult) => void | Promise<void>;
+        intervalMs?: number;
+        timeoutMs?: number;
+    }) => Promise<SafeRelayrResult>;
+};
+//# sourceMappingURL=safeRelayr.d.ts.map

package/dist/cjs/review/safeRelayr.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"safeRelayr.d.ts","sourceRoot":"","sources":["../../../src/review/safeRelayr.ts"],"names":[],"mappings":"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"}