@invisi-labs/sdk 1.1.6 → 1.2.0

package/dist/operation-bridge-CoECSxfi.d.ts

@@ -0,0 +1,472 @@
+import { ProofSidecar, ManifestIdentity, Scope } from '@invisi-labs/protocol/provenance';
+import { OfflineProver } from '@invisi-labs/prover/provenance-witness';
+import * as _invisi_labs_rpc_provenance from '@invisi-labs/rpc/provenance';
+import { ProvenanceClient } from '@invisi-labs/rpc/provenance';
+import { Note, CreditDeliveryState, ReceivingKeyLookup, Wallet, CreditUpdateChanges, AuthorizedStatement } from '@invisi-labs/primitives';
+import * as _invisi_labs_prover from '@invisi-labs/prover';
+import { Hex, Prover, NoteMembership, CreditMembership, ProverOptions, AggregateMember, ProofBundle } from '@invisi-labs/prover';
+import * as _invisi_labs_protocol from '@invisi-labs/protocol';
+import { FundingInput, ChainReader, ProtocolDataProvider, TransactionContext, CanonicalBlock, TransactRequestParams } from '@invisi-labs/protocol';
+import { SignedBroadcasterQuote, BroadcasterClient as BroadcasterClient$1, BroadcasterStatus, BroadcasterConfiguration } from '@invisi-labs/rpc/broadcaster';
+import { Hex as Hex$1, Delivery, Address, ShieldParams, ShieldOutput, CreateCreditParams, CreditDrawParams, UpdateCreditParams, RevokeCreditParams, TransactRequest } from '@invisi-labs/protocol/contracts';
+import { Provider } from 'ethers';
+import { Protocol, TokenProtocol } from '@invisi-labs/rpc';
+
+/** Public recovery packet; persist encrypted Note openings separately if reproof is needed. */
+interface ProvenanceProof {
+    format: "invisi-provenance-submission-v1";
+    data: string;
+    context: {
+        chainId: string;
+        protocolAddress: string;
+        tokenAddress: string;
+    };
+    mainCircuitCapacity: number;
+    publicInputs: string[];
+    operationDigest: string;
+    sidecars: ProofSidecar[];
+}
+
+interface WalletScope {
+    namespace: string;
+    chainId: bigint;
+    protocolAddress: Hex;
+    ownerAddress: Hex;
+}
+declare function creditReservationKey(commitment: string): string;
+interface Checkpoint {
+    number: bigint;
+    hash: Hex;
+}
+type SpentState = "unknown" | "unspent" | "spent";
+interface ReceiptPosition {
+    commitment: Hex;
+    treeId: bigint;
+    leafIndex: number;
+    blockNumber: bigint;
+    blockHash: Hex;
+    transactionHash?: Hex;
+}
+interface NoteRecord extends ReceiptPosition {
+    note: Note;
+    spent: SpentState;
+    checkedThrough?: Checkpoint;
+}
+interface CreditRecord extends ReceiptPosition {
+    receivingKeySource?: {
+        kind: "draw" | "update";
+        commitment: Hex;
+    };
+    revoked?: boolean;
+    state: CreditDeliveryState;
+    role: "owner" | "spender";
+    spent: SpentState;
+    checkedThrough?: Checkpoint;
+}
+type OperationStatus = "prepared" | "authorized" | "proved" | "ready" | "submitted" | "confirmed" | "failed" | "expired" | "uncertain" | "reorged";
+
+/** Minimal input count by descending amount, with deterministic tree/position/commitment ties. */
+type SelectableNote = Pick<NoteRecord, "note" | "commitment" | "treeId" | "leafIndex" | "spent">;
+
+type PreparationIntent = {
+    kind: "transfer";
+    options: TransferPreparation;
+} | {
+    kind: "shield";
+    options: ShieldPreparation;
+} | {
+    kind: "create-credit";
+    options: CreateCreditPreparation;
+} | {
+    kind: "draw-credit";
+    options: DrawCreditPreparation;
+} | {
+    kind: "update-credit";
+    options: UpdateCreditPreparation;
+} | {
+    kind: "revoke-credit";
+    options: RevokeCreditPreparation;
+};
+type BroadcasterFeeSource = "public-funding" | "private-inputs";
+interface BroadcasterQuoteOptions {
+    maxFeeAmount: bigint;
+    feeSource?: BroadcasterFeeSource;
+    maxAttempts?: number;
+    /** Optional app-owned permit signing, requested once for the final gross funding amount. */
+    fundingPermit?: (request: {
+        payer: `0x${string}`;
+        amount: bigint;
+        tokenAddress: `0x${string}`;
+        protocolAddress: `0x${string}`;
+    }) => Promise<NonNullable<TransferPreparation["funding"]>["permit"]>;
+}
+declare function prepareIntent(runtime: PreparationRuntime<OperationPlan>, intent: PreparationIntent): Promise<OperationPlan>;
+declare function prepareBroadcasterPlan(plan: OperationPlan, reprepare: (intent: PreparationIntent) => Promise<OperationPlan>, client: BroadcasterClient, options: BroadcasterQuoteOptions): Promise<{
+    plan: OperationPlan;
+    quote: SignedBroadcasterQuote;
+    broadcasterBinding: NonNullable<SavedOperation["broadcasterBinding"]>;
+}>;
+
+/** Application-level quote and submission conveniences over the public RPC client. */
+declare class BroadcasterClient extends BroadcasterClient$1 {
+    quote<T extends BroadcasterTransaction>(transaction: T, options: BroadcasterQuoteOptions): Promise<T>;
+    submit(transaction: BroadcasterTransaction): Promise<BroadcasterStatus>;
+}
+
+type AddressLookup = "chain" | "protocol-rpc";
+/** Capture deployment pins before a Protocol is bound to an operation's token. */
+declare function configureRecipientInfrastructure<T extends TransactionInfrastructure>(options: T): T;
+/** Internal lookup plumbing; public APIs never accept resolver functions. */
+declare function recipientLookup(options: object, source?: AddressLookup): ReceivingKeyLookup;
+
+interface NoteOutputContext {
+    chainId: bigint;
+    protocolAddress: Hex$1;
+    tokenAddress: Hex$1;
+}
+type NoteOutputRecipient = {
+    type: "evm";
+    address: string;
+    envelope?: boolean;
+    addressLookup?: AddressLookup;
+    nonce?: bigint | undefined;
+} | {
+    type: "invisi";
+    address: string;
+    nonce?: bigint | undefined;
+} | {
+    type: "identity";
+    identity: Hex$1;
+};
+type EncryptedRecipient = {
+    type: "evm";
+    address: string;
+    envelope?: true;
+    addressLookup?: AddressLookup;
+    nonce?: bigint | undefined;
+} | {
+    type: "invisi";
+    address: string;
+    nonce?: bigint | undefined;
+};
+type PaymentRequest = NoteOutputContext & {
+    amount: bigint;
+} & ({
+    recipient: EncryptedRecipient;
+    payload?: Uint8Array;
+} | {
+    recipient: {
+        type: "evm";
+        address: string;
+        envelope: false;
+        addressLookup?: AddressLookup;
+        nonce?: bigint | undefined;
+    } | {
+        type: "identity";
+        identity: Hex$1;
+    };
+    payload?: never;
+});
+/** Local payment choices; these never rewrite the encoded request. */
+interface NoteOutputExecutionOptions {
+    nonce?: bigint;
+    addressLookup?: AddressLookup;
+}
+
+/** Immutable output statement and optional recoverable opening. */
+declare class NoteOutput {
+    readonly to: string;
+    readonly ipp: string;
+    readonly amount: bigint;
+    readonly identity: Hex$1;
+    readonly commitment: Hex$1;
+    readonly deliveryFingerprint: Hex$1;
+    /** Encrypted EVM delivery is resolved by preparation; the original offline intent stays pending. */
+    readonly deliveryPending: boolean;
+    readonly context: NoteOutputContext;
+    readonly recipient: NoteOutputRecipient;
+    readonly nonce: bigint | undefined;
+    readonly payload: Uint8Array;
+    readonly preparedOutput: PreparedOutput;
+    private constructor();
+    /** Private offline delivery data; does not assert that the output has been mined. */
+    exportPaymentNote(): string;
+    static create(input: PaymentRequest | string, execution?: NoteOutputExecutionOptions): Promise<NoteOutput>;
+    assertCommitment(expectedHex: Hex$1): void;
+    get note(): Note | undefined;
+    get delivery(): Delivery;
+}
+
+interface CoinSelector {
+    select(candidates: readonly NoteRecord[], requiredAmount: bigint): readonly Hex$1[] | Promise<readonly Hex$1[]>;
+}
+interface FundingTypedData {
+    domain: Record<string, unknown>;
+    primaryType: string;
+    types: Record<string, readonly {
+        name: string;
+        type: string;
+    }[]>;
+    message: Record<string, unknown>;
+}
+interface FundingSigner {
+    readonly address: Address;
+    signTypedData(data: FundingTypedData): Promise<Hex$1>;
+}
+interface FundingAuthorizationVerifier {
+    verifyTypedData(data: FundingTypedData & {
+        address: Address;
+        signature: Hex$1;
+    }): Promise<boolean>;
+}
+interface FundingSource {
+    payer: Address;
+    amount: bigint;
+    authorization?: "signature" | "caller";
+    sigNonce?: bigint;
+    deadline?: bigint;
+    permit?: NonNullable<FundingInput["permit"]>;
+}
+/** Public submission mode; backend proof targets are selected internally. */
+type TransactionExecution = "single" | "aggregate";
+interface TransactionProveOptions extends ProverOptions {
+    /** Defaults to single. Aggregate produces a member for a separate aggregate submission. */
+    execution?: TransactionExecution;
+}
+interface TransferPreparation {
+    tokenAddress: Address;
+    /** Explicit subset for managed inventory; detached calls already supply inputs. */
+    commitments?: readonly Hex$1[];
+    /** Public ERC20 payout. Empty private outputs are allowed when a payout is present. */
+    withdrawal?: {
+        to: Address;
+        amount: bigint;
+    };
+    /** Immediate public fee paid from this operation's token. */
+    fee?: {
+        recipient: Address;
+        amount: bigint;
+    };
+    outputs: readonly NoteOutput[];
+    funding?: FundingSource;
+    deadline?: bigint;
+}
+interface ShieldPreparation {
+    fee?: {
+        recipient: Address;
+        amount: bigint;
+    };
+    tokenAddress: Address;
+    outputs: readonly NoteOutput[];
+    funding: FundingSource;
+    deadline?: bigint;
+}
+interface PreparedOutput {
+    context: NoteOutputContext;
+    recipient: NoteOutputRecipient;
+    amount: bigint;
+    note?: Note;
+    commitment: Hex$1;
+    identity: Hex$1;
+    delivery: Delivery;
+    /** Only offline encrypted EVM outputs may await registry-key resolution. */
+    deliveryPending?: true;
+    address: string;
+    change: boolean;
+}
+interface CreateCreditPreparation {
+    fee?: {
+        recipient: Address;
+        amount: bigint;
+    };
+    payload?: Uint8Array;
+    singleLimit?: bigint;
+    dailyLimit?: bigint;
+    monthlyLimit?: bigint;
+    availableCredit?: bigint;
+    unlimited?: boolean;
+    tokenAddress: Address;
+    spender: string;
+    expiry: bigint;
+    deadline?: bigint;
+}
+interface DrawCreditPreparation {
+    fee?: {
+        recipient: Address;
+        amount: bigint;
+    };
+    tokenAddress: Address;
+    credits: readonly {
+        credit: Hex$1;
+        amount: bigint;
+        payload?: Uint8Array;
+    }[];
+    recipient: string;
+    payload?: Uint8Array;
+    deadline?: bigint;
+}
+interface UpdateCreditPreparation {
+    fee?: {
+        recipient: Address;
+        amount: bigint;
+    };
+    payload?: Uint8Array;
+    singleLimit?: bigint;
+    dailyLimit?: bigint;
+    monthlyLimit?: bigint;
+    increaseAvailableCredit?: bigint;
+    decreaseAvailableCredit?: bigint;
+    unlimited?: boolean;
+    tokenAddress: Address;
+    credit: Hex$1;
+    expiry?: bigint;
+    deadline?: bigint;
+}
+interface RevokeCreditPreparation {
+    fee?: {
+        recipient: Address;
+        amount: bigint;
+    };
+    tokenAddress: Address;
+    owner?: Address;
+    shard: bigint;
+    slot: bigint;
+    caller?: Address;
+    deadline?: bigint;
+}
+interface PreparedCreditOutput {
+    state: CreditDeliveryState;
+    commitment: Hex$1;
+    deliveries: [Delivery, Delivery];
+}
+interface PreparedCreditInput extends CreditMembership {
+    commitment: Hex$1;
+    role: "owner" | "spender";
+}
+interface CreditPlan {
+    inputs: PreparedCreditInput[];
+    outputs: PreparedCreditOutput[];
+    deliveries: Delivery[];
+    creation?: CreateCreditParams;
+    draw?: CreditDrawParams;
+    update?: UpdateCreditParams;
+    updateChanges?: CreditUpdateChanges;
+    revocation?: RevokeCreditParams;
+    revocationSignature?: Hex$1;
+    revocationCaller?: Hex$1;
+    amounts?: bigint[];
+}
+interface OperationPlan {
+    intent?: PreparationIntent;
+    version: 1;
+    id: string;
+    kind: "transfer" | "shield" | "create-credit" | "draw-credit" | "update-credit" | "revoke-credit";
+    context: TransactionContext;
+    scope: WalletScope;
+    preparedAt: CanonicalBlock;
+    deadline: bigint;
+    outputs: PreparedOutput[];
+    inputs: Array<NoteMembership & {
+        commitment: Hex$1;
+    }>;
+    funding: FundingInput;
+    fundingMode: "none" | "signature" | "caller";
+    params?: TransactRequestParams;
+    shieldParams?: ShieldParams;
+    shieldOutputs?: ShieldOutput[];
+    capacity?: number;
+    credit?: CreditPlan;
+    statement?: _invisi_labs_prover.ProofStatement;
+}
+interface SavedOperation {
+    plan: OperationPlan;
+    provenance?: ProvenanceProof;
+    broadcasterBinding?: {
+        configuration: BroadcasterConfiguration;
+        intentHash: string;
+    };
+    broadcasterSubmissionId?: string;
+    broadcasterAttempted?: boolean;
+    broadcasterQuote?: SignedBroadcasterQuote;
+    proof?: ProofBundle;
+    call?: _invisi_labs_protocol.TransactionCall;
+    externalized?: boolean;
+    generation: number;
+    claim?: {
+        stage: string;
+        token: string;
+    };
+}
+interface TransactionInfrastructure {
+    provenanceClient?: _invisi_labs_rpc_provenance.ProvenanceClient;
+    provenance?: PreparedProvenanceCapability;
+    wallet: Wallet;
+    protocol: Protocol;
+    chainReader?: ChainReader;
+    protocolRpc?: ProtocolDataProvider;
+    prover?: Prover;
+    fundingVerifier?: FundingAuthorizationVerifier;
+    /** Optional ethers provider used by per-output direct-chain receiving-key lookup. */
+    provider?: Provider;
+    coinSelector?: CoinSelector;
+    transactionTTL?: bigint;
+}
+interface TransactionRuntime {
+    options: Omit<TransactionInfrastructure, "protocol"> & {
+        protocol: TokenProtocol;
+    };
+    scope: WalletScope;
+    reader: ChainReader;
+}
+interface LocalOperationSecrets {
+    authorization?: AuthorizedStatement;
+}
+interface OperationAggregateMember extends AggregateMember {
+    context: TransactionContext;
+    request: TransactRequest;
+}
+/** Data required while preparing an operation; it does not own persistence or reservations. */
+interface PreparationRuntime<Result> extends TransactionRuntime {
+    readInventory(): Promise<PreparationInventory>;
+    complete(plan: OperationPlan): Promise<Result>;
+    explicitInputs?: boolean;
+    inputSelection?: readonly Hex$1[];
+    changeAddress?: string;
+}
+interface PreparationInventory {
+    reservations: Record<string, string>;
+    invalidated?: string;
+    observedThrough?: Checkpoint;
+    notes: Record<string, SelectableNote>;
+    credits: Record<string, Pick<CreditRecord, "state" | "commitment" | "treeId" | "leafIndex" | "role" | "spent">>;
+}
+
+interface PreparedProvenanceCapability {
+    client: ProvenanceClient;
+    manifest: ManifestIdentity;
+    prover: OfflineProver;
+    maxRootPages?: number;
+    maxLeaves?: number;
+}
+declare function prepareProvenance(plan: OperationPlan, runtime: TransactionRuntime): Promise<{
+    operationDigest: string;
+    sidecars: ProofSidecar[];
+}>;
+declare function provePreparedProvenance(saved: SavedOperation, runtime: TransactionRuntime, capability?: PreparedProvenanceCapability, reprove?: boolean): Promise<ProvenanceProof>;
+declare function validateBroadcastEnvelope(saved: SavedOperation, client: BroadcasterClient): void;
+declare function validatePreparedBroadcast(saved: SavedOperation, client: BroadcasterClient, runtime: TransactionRuntime): Promise<void>;
+
+interface BroadcasterTransaction {
+    readonly id: string;
+    readonly status: string;
+}
+interface Hooks<T extends BroadcasterTransaction> {
+    quote(client: BroadcasterClient, options: BroadcasterQuoteOptions): Promise<T>;
+    submit(client: BroadcasterClient): Promise<BroadcasterStatus>;
+    provenanceContext(): Promise<Scope>;
+    readProvenance(): Promise<ProvenanceProof | undefined>;
+    proveProvenance(capability: PreparedProvenanceCapability, reprove?: boolean): Promise<ProvenanceProof>;
+}
+declare function bindBroadcasterOperation<T extends BroadcasterTransaction>(target: T, hooks: Hooks<T>): void;
+
+export { validateBroadcastEnvelope as $, type AddressLookup as A, type BroadcasterTransaction as B, type CreateCreditPreparation as C, type DrawCreditPreparation as D, type PreparedCreditInput as E, type FundingSigner as F, type PreparedCreditOutput as G, type PreparedOutput as H, type ReceiptPosition as I, type SpentState as J, bindBroadcasterOperation as K, type LocalOperationSecrets as L, configureRecipientInfrastructure as M, NoteOutput as N, type OperationStatus as O, type ProvenanceProof as P, creditReservationKey as Q, type RevokeCreditPreparation as R, type ShieldPreparation as S, type TransactionRuntime as T, type UpdateCreditPreparation as U, prepareBroadcasterPlan as V, type WalletScope as W, prepareIntent as X, prepareProvenance as Y, provePreparedProvenance as Z, recipientLookup as _, type PreparedProvenanceCapability as a, validatePreparedBroadcast as a0, type FundingTypedData as b, type FundingAuthorizationVerifier as c, type PreparationIntent as d, type OperationPlan as e, type TransactionProveOptions as f, type OperationAggregateMember as g, type TransactionInfrastructure as h, BroadcasterClient as i, type PaymentRequest as j, type BroadcasterFeeSource as k, type BroadcasterQuoteOptions as l, type FundingSource as m, type NoteOutputContext as n, type NoteOutputExecutionOptions as o, type NoteOutputRecipient as p, type TransactionExecution as q, type TransferPreparation as r, type SavedOperation as s, type PreparationRuntime as t, type Checkpoint as u, type CoinSelector as v, type CreditPlan as w, type CreditRecord as x, type NoteRecord as y, type PreparationInventory as z };