@invisible-labs/sdk 0.6.0-devnet.1

package/dist/user.d.ts

@@ -0,0 +1,377 @@
+import { S as Session } from './session-DFuy54C-.js';
+import { a as CoordinatorPoolConfig, P as PayoutPolicy } from './types.generated-CHGSbmLp.js';
+import { C as CreateSessionOptions } from './createSession-D3ym-Ira.js';
+export { I as InvalidDepositAmountError } from './createSession-D3ym-Ira.js';
+import './types-ZhV7TIQY.js';
+
+/**
+ * Acceptance receipts (spec section 8.2).
+ *
+ * Every mutating command returns an asynchronous acceptance receipt - `accepted`
+ * plus a correlation `requestId` - never the resulting domain state. Outcomes
+ * arrive later through `sync` reads or `events` subscriptions.
+ */
+/** The receipt a mutating command resolves to once the coordinator accepts it. */
+interface AcceptanceReceipt {
+    readonly accepted: true;
+    /** Correlation id for this logical action; stable across transient retries. */
+    readonly requestId: string;
+    /** Optional coordinator-reported request state (e.g. `REQUESTED`). */
+    readonly state?: string;
+}
+
+type ClientSwapState = "new" | "awaiting_dkg" | "awaiting_deposit" | "awaiting_delegation" | "awaiting_delegate_ack" | "awaiting_delegate_ack_after_deposit" | "ready_for_settlement" | "settling" | "completed" | "refunded" | "failed";
+type PayoutSpec = {
+    readonly mode: "instant";
+    readonly destination_address: string;
+} | {
+    readonly mode: "scheduled";
+    readonly num_fragments: number;
+    readonly window_seconds: number;
+    readonly destination_addresses: readonly string[];
+};
+type SpendingPolicySnapshot = {
+    readonly asset: "SOL";
+    readonly entry_amount_lamports: number;
+    readonly total_committed_lamports: number;
+    readonly payout_deadline_ms: number;
+    readonly payout_window_ms?: number;
+    readonly payout_schedule: readonly {
+        readonly destination_address: string;
+    }[];
+    readonly fragment_count: number;
+    readonly payout_mode: "instant" | "scheduled";
+    readonly matching_mode: "exact_1_to_1";
+    readonly fragmentation_allowed: "payout_side_only";
+    readonly min_fee_bps: number;
+    readonly fee_bps: number;
+    readonly fee_lamports: number;
+    readonly net_payout_lamports: number;
+};
+type PayoutExecutedPayload = {
+    readonly index: number;
+    readonly amount_lamports: number;
+    readonly destination_address: string;
+    readonly tx_signature: string;
+    readonly executed_at_ms: number;
+    readonly final: boolean;
+};
+type WithdrawExecutedPayload = {
+    readonly tx_signature: string;
+    readonly amount_lamports: number;
+    readonly withdrawn_at_ms: number;
+    readonly trigger: "user_request" | "auto_deadline";
+    readonly destination_address: string;
+};
+type RefundExecutedPayload = WithdrawExecutedPayload;
+type SyncRetryInstruction = {
+    readonly should_retry: boolean;
+    readonly poll_after_ms: number | null;
+};
+type PayoutWindowSyncSnapshot = {
+    readonly starts_at_ms: number;
+    readonly deadline_ms: number | null;
+};
+type NormalUserContractStatus = "deposit" | "activating" | "active" | "settling" | "completed" | "refunded" | "expired";
+type NormalUserSettlementPhase = "awaiting_deposit" | "activating" | "waiting_for_liquidity" | "matched_scheduled" | "locked_pending_payout" | "submitted" | "confirming" | "completed" | "refund_pending" | "refunded" | "expired";
+type NormalUserRefundability = "available_now" | "request_pending" | "blocked_by_lock" | "stale" | "unavailable";
+type SourceLiquidityUse = "not_materialized" | "available" | "locked_for_payout" | "pending_finality" | "spent" | "released";
+type NormalUserContractSyncSnapshot = {
+    readonly contract_id: string;
+    readonly status: NormalUserContractStatus;
+    readonly settlement_phase: NormalUserSettlementPhase;
+    readonly refundability: NormalUserRefundability;
+    readonly source_liquidity_use: SourceLiquidityUse;
+    readonly destination_wallet: string | null;
+    readonly deposit_amount_lamports: number;
+    readonly deposit_expires_at_ms: number;
+    readonly payout_window: PayoutWindowSyncSnapshot;
+    readonly settlement_tx_hashes: readonly string[];
+    readonly settled_amount_lamports: number;
+    readonly protocol_fee_lamports: number;
+    readonly network_fee_lost_lamports: readonly number[];
+    readonly withdrawal_requested_lamports: number;
+    readonly withdrawal_landed_lamports: number;
+    readonly withdrawal_landed_fee_lamports: number;
+    readonly withdrawal_canceled_lamports: number;
+    readonly withdrawal_network_fee_loss_lamports: number;
+    readonly withdrawal_tx_hashes: readonly string[];
+    readonly retry: SyncRetryInstruction;
+    readonly state_version: number;
+    readonly updated_at_ms: number;
+};
+type NormalUserActorSyncSnapshot = {
+    readonly actor: "normal_user";
+    readonly snapshot: NormalUserContractSyncSnapshot;
+};
+type SyncUserResponsePayload = {
+    readonly state: ClientSwapState;
+    readonly fragments_executed: readonly PayoutExecutedPayload[];
+    readonly withdraw_execution?: RefundExecutedPayload;
+    readonly actor_sync?: NormalUserActorSyncSnapshot;
+};
+type WithdrawAcceptedPayload = {
+    readonly status: "accepted";
+    readonly amount_lamports: number;
+    readonly destination_address: string;
+    readonly accepted_at_ms: number;
+};
+type RunSwapParams = {
+    amountLamports: number;
+    payoutSpec: PayoutSpec;
+    payoutDeadlineMs?: number;
+    onPolicySnapshot?: (policy: SpendingPolicySnapshot) => void;
+    recoveryCommitment?: Uint8Array;
+    syncSecret?: Uint8Array;
+    onSyncSecretReady?: (info: {
+        secretHex: string;
+    }) => void | Promise<void>;
+    onRecoveryCodeReady?: (info: {
+        codeHex: string;
+    }) => void | Promise<void>;
+    delegateShare?: Uint8Array;
+    onDepositAddressReady?: (info: {
+        swapId: string;
+        jointPublicKey: Uint8Array;
+        amountLamports: number;
+        depositExpiresAtMs: number;
+        coordinatorTimestampMs: number;
+    }) => void | Promise<void>;
+    onDepositConfirmed?: (info: {
+        originAddress: string | undefined;
+    }) => void | Promise<void>;
+    payoutWindowMs?: number;
+};
+/** Parameters for the pre-deposit portion of a normal-user contract flow. */
+type ContractRequestParams = Omit<RunSwapParams, "onDepositConfirmed">;
+/**
+ * Details returned once the coordinator has accepted, initialized, and
+ * durably delegated a contract, but before the user's deposit is observed.
+ */
+type ContractRequestResult = {
+    readonly accepted: true;
+    /** V0 has no separate durable request id, so this aliases `swapId`. */
+    readonly requestId: string;
+    readonly state: "awaiting_deposit";
+    readonly swapId: string;
+    readonly depositAddress: string;
+    readonly jointPublicKey: Uint8Array;
+    readonly amountLamports: number;
+    readonly depositExpiresAtMs: number;
+    readonly coordinatorTimestampMs: number;
+    readonly delegatedAtMs: number;
+    /** The read-only status secret. The caller must persist it if it needs sync. */
+    readonly syncSecret: Uint8Array;
+    readonly syncSecretHex: string;
+    /** Present when the SDK generated the Recovery Code for this request. */
+    readonly recoveryCodeHex?: string;
+    readonly policySnapshot: SpendingPolicySnapshot;
+    readonly delegatePolicySnapshot: SpendingPolicySnapshot;
+};
+type SwapResult = {
+    swapId: string;
+    jointPublicKey: Uint8Array;
+    depositTxSignature: string;
+    depositObservedAtMs: number;
+    delegatedAtMs: number;
+    recoveryCodeHex?: string;
+    policySnapshot: SpendingPolicySnapshot;
+    delegatePolicySnapshot: SpendingPolicySnapshot;
+};
+type RefundIntentResult = {
+    readonly kind: "executed";
+    readonly refund: RefundExecutedPayload;
+} | {
+    readonly kind: "accepted";
+    readonly accepted: WithdrawAcceptedPayload;
+};
+type SessionStatus = "idle" | "connecting" | "running" | "done" | "failed";
+type CoordinatorSessionOptions = {
+    coordinator: CoordinatorPoolConfig;
+    createSession?: (options: CreateSessionOptions) => Promise<Session>;
+};
+type StateChangeListener = (swapState: ClientSwapState, sessionStatus: SessionStatus) => void;
+type LogListener = (msg: string, direction: "in" | "out" | "info") => void;
+type PayoutExecutedListener = (payload: PayoutExecutedPayload, swapId: string) => void;
+type RefundExecutedListener = (payload: RefundExecutedPayload, swapId: string) => void;
+type NormalUserActorSyncListener = (payload: NormalUserActorSyncSnapshot, coordinatorTimestampMs: number) => void;
+type CoordinatorProtocolError = Error & {
+    readonly code: string;
+    readonly failedReqId?: number;
+};
+type CoordinatorErrorListener = (err: CoordinatorProtocolError) => void;
+type CoordinatorSessionHandle = {
+    onStateChange(listener: StateChangeListener): () => void;
+    onLog(listener: LogListener): () => void;
+    onPayoutExecuted(listener: PayoutExecutedListener): () => void;
+    onRefundExecuted(listener: RefundExecutedListener): () => void;
+    onNormalUserActorSync(listener: NormalUserActorSyncListener): () => void;
+    onCoordinatorError(listener: CoordinatorErrorListener): () => void;
+    readonly currentSwapState: ClientSwapState;
+    readonly currentSessionStatus: SessionStatus;
+    runSwap(params: RunSwapParams): Promise<SwapResult>;
+    contractRequest(params: ContractRequestParams): Promise<ContractRequestResult>;
+    close(): void;
+    restoreSwapContext(params: {
+        swapId: string;
+        syncSecret?: Uint8Array;
+    }): void;
+    requestSwapStatus(timeoutMs?: number): Promise<SyncUserResponsePayload>;
+    startSwapStatusReconciliation(intervalMs?: number): () => void;
+    requestRefund(params: {
+        swapId?: string;
+        syncSecret?: Uint8Array;
+        recoveryCode: Uint8Array;
+        timeoutMs?: number;
+    }): Promise<RefundExecutedPayload>;
+    requestRefundIntent(params: {
+        swapId?: string;
+        syncSecret?: Uint8Array;
+        recoveryCode: Uint8Array;
+        timeoutMs?: number;
+    }): Promise<RefundIntentResult>;
+};
+declare function createCoordinatorSession(options: CoordinatorSessionOptions): CoordinatorSessionHandle;
+declare function isBenignTransportDrop(err: unknown): boolean;
+
+/**
+ * Payout policy validation (spec sections 4.3.1 and 10.1).
+ *
+ * A two-stage check: AJV enforces the structural shape, then the semantic rules
+ * that JSON Schema cannot express are applied. Any failure throws a
+ * `PolicyValidationError` and the policy never reaches the wire. Pure and
+ * synchronous; no transport, no I/O.
+ */
+
+/**
+ * Conversion factor used by the public payout-window selector.
+ */
+declare const PAYOUT_WINDOW_MILLISECONDS_PER_SECOND = 1000;
+/** `totalDeadlineMs` value that selects the coordinator's instant payout mode. */
+declare const INSTANT_PAYOUT_WINDOW_MS = 0;
+/**
+ * `totalDeadlineMs` values accepted by the current normal-user SDK surface.
+ * Zero selects instant payout; positive values select a scheduled window.
+ */
+declare const SUPPORTED_TOTAL_DEADLINE_MS: readonly number[];
+
+/** Byte length of the Recovery Code preimage used by normal-user withdrawals. */
+declare const RECOVERY_CODE_BYTE_LENGTH = 32;
+declare function generateRecoveryCode(): Promise<{
+    code: Uint8Array;
+    commitment: Uint8Array;
+}>;
+declare function commitmentFromCode(code: Uint8Array): Promise<Uint8Array>;
+declare function recoveryCodeToHex(code: Uint8Array): string;
+declare function recoveryCodeFromHex(hex: string): Uint8Array;
+declare function recoveryCodeFromUserInput(input: string): Uint8Array;
+
+/**
+ * `@invisible-labs/sdk/user` - normal-user (private transfer) commands (spec 4.3).
+ *
+ * The functional user API and the frontend `createCoordinatorSession` facade
+ * share the same coordinator lifecycle implementation. Importing this module
+ * must not pull in `/lp`, `/stats`, or `/events`.
+ */
+
+/** Inclusive minimum private-transfer entry amount in lamports. */
+declare const MIN_ENTRY_AMOUNT_LAMPORTS = 400000000;
+/** Inclusive maximum private-transfer entry amount in lamports. */
+declare const MAX_ENTRY_AMOUNT_LAMPORTS = 100000000000;
+/** Arguments to start a new private-transfer pool entry. */
+interface ContractRequestArgs {
+    /**
+     * Gross private-transfer amount in lamports.
+     *
+     * At the contract boundary, this is the exact amount the coordinator expects
+     * to observe at the fundable deposit address and hold in the joint wallet.
+     * It is the custody-side amount before protocol and network-fee accounting,
+     * not the net amount a payout destination receives.
+     */
+    readonly amountLamports: number;
+    /**
+     * Where and how the output is delivered. V0 normal-user requests support
+     * exactly one payout destination and validate the policy locally before
+     * submission. `batchExclusionId` is rejected in V0; its planned V1 meaning
+     * is campaign-scoped batch exclusion, never a stable actor identity.
+     * `destinations[*].minDelayMs` and `destinations[*].maxDelayMs` are also
+     * rejected in V0 because the current runtime does not honor them.
+     * `totalDeadlineMs` selects the payout window: use `0` for instant payout,
+     * or one of the coordinator-supported scheduled durations exposed by
+     * `SUPPORTED_TOTAL_DEADLINE_MS`.
+     */
+    readonly payoutPolicy: PayoutPolicy;
+    /**
+     * Retained for API compatibility. The current wire contract always commits a
+     * sync secret because status reads are keyed by that commitment.
+     */
+    readonly sync?: boolean;
+    /** Optional caller-owned status secret, copied before it reaches the wire. */
+    readonly syncSecret?: Uint8Array;
+    /** Called before ContractRequest so the caller can persist the status secret. */
+    readonly onSyncSecretReady?: (info: {
+        secretHex: string;
+    }) => void | Promise<void>;
+    /** Optional precomputed Recovery Code commitment for caller-managed recovery. */
+    readonly recoveryCommitment?: Uint8Array;
+    /** Called before DelegateShare so the caller can persist the generated code. */
+    readonly onRecoveryCodeReady?: (info: {
+        codeHex: string;
+    }) => void | Promise<void>;
+}
+/**
+ * Start a new pool entry through the current normal-user coordinator flow.
+ * Resolves after DKG and durable share delegation, before the user's deposit
+ * is observed. The returned `depositAddress` is the joint-wallet address.
+ * `payoutPolicy.totalDeadlineMs` selects the payout window: omitted or `0`
+ * selects instant payout; the supported positive millisecond values select
+ * the corresponding scheduled coordinator window.
+ *
+ * @throws PolicyValidationError if the payout policy is invalid (never hits the wire).
+ * @throws AttestationError if the session is not attested.
+ * @throws CommandError if the coordinator rejects the request or the local
+ *   session cannot complete the DKG/delegation boundary.
+ */
+declare function contractRequest(session: Session, args: ContractRequestArgs): Promise<ContractRequestResult>;
+/** Read the actor-scoped lifecycle projection for a normal-user contract. */
+declare function sync(session: Session, contractId: string, syncSecret: Uint8Array, timeoutMs?: number): Promise<SyncUserResponsePayload>;
+/** Arguments to refund a pool entry with the Recovery Code preimage. */
+interface RequestRefundArgs {
+    /** The 32-byte Recovery Code preimage. */
+    readonly recoveryCode: Uint8Array;
+}
+/**
+ * Submit a normal-user `withdraw_request` with only the Recovery Code preimage
+ * (`{ recovery_code }`). The coordinator queues a durable origin-bound
+ * withdrawal intent and terminal outcome is recovered through sync/status
+ * reads. No caller-supplied destination is accepted.
+ *
+ * @returns An acceptance receipt keyed by the resolved V0 `swapId`. The
+ *   coordinator's durable execution result is read later through `sync`.
+ * @throws AttestationError if the session is not attested.
+ * @throws PolicyValidationError if `recoveryCode` is not exactly 32 bytes.
+ * @throws CommandError if the coordinator rejects the withdrawal request.
+ */
+declare function requestRefund(session: Session, args: RequestRefundArgs): Promise<AcceptanceReceipt>;
+/**
+ * Read the fundable deposit address for a request once the sealed contract
+ * exposes it (`sync`).
+ *
+ * @throws NotImplementedError - read execution is deferred.
+ */
+declare function getDepositAddress(_session: Session, _requestId: string, _syncSecret: Uint8Array): Promise<string>;
+/**
+ * Subscribe to live sync messages for a request.
+ *
+ * @throws NotImplementedError - subscriptions are deferred.
+ */
+declare function subscribe(_session: Session, _requestId: string, _syncSecret: Uint8Array, _handler: (event: unknown) => void): never;
+/**
+ * Recover open requests after a tab close or restart by replaying the storage
+ * adapter and re-subscribing.
+ *
+ * @throws NotImplementedError - replay is deferred.
+ */
+declare function replayFromStorage(_session: Session, _storage: unknown): Promise<void>;
+
+export { type ClientSwapState, type ContractRequestArgs, type ContractRequestParams, type ContractRequestResult, type CoordinatorProtocolError, type CoordinatorSessionHandle, type CoordinatorSessionOptions, INSTANT_PAYOUT_WINDOW_MS, MAX_ENTRY_AMOUNT_LAMPORTS, MIN_ENTRY_AMOUNT_LAMPORTS, type NormalUserActorSyncSnapshot, type NormalUserRefundability, type NormalUserSettlementPhase, PAYOUT_WINDOW_MILLISECONDS_PER_SECOND, type PayoutExecutedPayload, type PayoutSpec, RECOVERY_CODE_BYTE_LENGTH, type RefundExecutedPayload, type RefundIntentResult, type RequestRefundArgs, type RunSwapParams, SUPPORTED_TOTAL_DEADLINE_MS, type SessionStatus, type SourceLiquidityUse, type SpendingPolicySnapshot, type SwapResult, type SyncUserResponsePayload, type WithdrawExecutedPayload, commitmentFromCode, contractRequest, createCoordinatorSession, generateRecoveryCode, getDepositAddress, isBenignTransportDrop, recoveryCodeFromHex, recoveryCodeFromUserInput, recoveryCodeToHex, replayFromStorage, requestRefund, subscribe, sync };