@invisible-labs/sdk 0.6.0-devnet.3 → 0.6.0-devnet.5

package/dist/user.d.ts

@@ -1,6 +1,6 @@
 import { S as Session } from './session-DFuy54C-.js';
-import { P as PayoutPolicy } from './types.generated-BSEBz4jR.js';
-export { I as InvalidDepositAmountError } from './errors-N2touVm4.js';
+import { P as PayoutPolicy } from './types.generated-YhFu9ZBR.js';
+export { I as InvalidDepositAmountError } from './types.generated-YhFu9ZBR.js';
 
 /**
  * Acceptance receipts (spec section 8.2).
@@ -18,7 +18,17 @@ interface AcceptanceReceipt {
     readonly state?: string;
 }
 
+/** Shared normal-user transfer types used without importing an actor entrypoint. */
 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;
@@ -37,6 +47,7 @@ type SpendingPolicySnapshot = {
     readonly fee_lamports: number;
     readonly net_payout_lamports: number;
 };
+
 type PayoutExecutedPayload = {
     readonly index: number;
     readonly amount_lamports: number;
@@ -62,14 +73,16 @@ type PayoutWindowSyncSnapshot = {
     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 NormalUserSettlementPhase = "awaiting_deposit" | "activating" | "waiting_for_liquidity" | "retry_delayed" | "recovery_required" | "matched_scheduled" | "locked_pending_payout" | "submitted" | "confirming" | "completed" | "refund_pending" | "refunded" | "expired";
 type NormalUserRefundability = "available_now" | "request_pending" | "blocked_by_lock" | "stale" | "unavailable";
+type NormalUserRefundStatus = "queued" | "reserved" | "submitted" | "confirming" | "retrying" | "finalized" | "failed" | "partial" | "canceled";
 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 refund_status: NormalUserRefundStatus | null;
     readonly source_liquidity_use: SourceLiquidityUse;
     readonly destination_wallet: string | null;
     readonly deposit_amount_lamports: number;
@@ -79,6 +92,7 @@ type NormalUserContractSyncSnapshot = {
     readonly settled_amount_lamports: number;
     readonly protocol_fee_lamports: number;
     readonly network_fee_lost_lamports: readonly number[];
+    readonly recovery_refund_remaining_lamports: number;
     readonly withdrawal_requested_lamports: number;
     readonly withdrawal_landed_lamports: number;
     readonly withdrawal_landed_fee_lamports: number;
@@ -115,6 +129,45 @@ type RefundAcceptanceReceipt = AcceptanceReceipt & {
     readonly amountLamports: number;
     readonly acceptedAtMs?: number;
 };
+type RunSwapParams = {
+    amountLamports: number;
+    payoutSpec: PayoutSpec;
+    payoutDeadlineMs?: number;
+    onPolicySnapshot?: (policy: SpendingPolicySnapshot) => void;
+    recoveryCommitment?: Uint8Array;
+    syncSecret?: Uint8Array;
+    onSyncSecretReady?: (info: {
+        secretHex: string;
+    }) => void | Promise<void>;
+    resumeSecret?: Uint8Array;
+    onResumeSecretReady?: (info: {
+        secretHex: string;
+    }) => void | Promise<void>;
+    onSwapAllocated?: (info: {
+        swapId: string;
+        syncSecretHex: string;
+        resumeSecretHex: string;
+    }) => void | Promise<void>;
+    onRecoveryCodeReady?: (info: {
+        codeHex: string;
+    }) => void | Promise<void>;
+    onDelegateShareReady?: (info: {
+        swapId: string;
+        delegateShare: Uint8Array;
+    }) => 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;
+};
 /**
  * Details returned once the coordinator has accepted, initialized, and
  * durably delegated a contract, but before the user's deposit is observed.
@@ -134,11 +187,59 @@ type ContractRequestResult = {
     /** The read-only status secret. The caller must persist it if it needs sync. */
     readonly syncSecret: Uint8Array;
     readonly syncSecretHex: string;
+    /** The pre-delegation mutation secret. Persist it only for resume/recovery workflows. */
+    readonly resumeSecret: Uint8Array;
+    readonly resumeSecretHex: string;
     /** Present when the SDK generated the Recovery Code for this request. */
     readonly recoveryCodeHex?: string;
     readonly policySnapshot: SpendingPolicySnapshot;
     readonly delegatePolicySnapshot: SpendingPolicySnapshot;
 };
+/** Inputs for resuming an already allocated pre-delegation contract. */
+type ResumePreDelegationParams = {
+    readonly swapId: string;
+    readonly resumeSecret: Uint8Array;
+    readonly syncSecret?: Uint8Array;
+    readonly recoveryCommitment: Uint8Array;
+    /** The policy snapshot returned when the contract was first allocated. */
+    readonly policySnapshot: SpendingPolicySnapshot;
+    /** Called before DkgRound2 so recovery can persist the generated Alice share. */
+    readonly onDelegateShareReady?: RunSwapParams["onDelegateShareReady"];
+    /** Supply the previously generated Alice share when DKG was already sealed. */
+    readonly delegateShare?: Uint8Array;
+};
+type ResumePreDelegationResult = {
+    readonly swapId: string;
+    readonly jointPublicKey?: Uint8Array;
+    readonly depositExpiresAtMs?: number;
+    readonly coordinatorTimestampMs?: number;
+    readonly delegatedAtMs: number;
+};
+
+declare const CLIENT_PERSISTENCE_SCHEMA_VERSION = 1;
+type PersistedTransferStage = "allocation" | "ready" | "terminal-cleaned";
+/** Public, local-only projection of an SDK-owned normal-user transfer record. */
+interface PersistedTransfer {
+    readonly schemaVersion: typeof CLIENT_PERSISTENCE_SCHEMA_VERSION;
+    readonly stage: PersistedTransferStage;
+    readonly swapId: string;
+    readonly amountLamports: number;
+    readonly destinationAddress: string;
+    readonly policySnapshot: SpendingPolicySnapshot;
+    readonly status: ClientSwapState;
+    readonly stateVersion?: number;
+    readonly updatedAtMs: number;
+    readonly coordinatorTimestampMs?: number;
+    readonly depositAddress?: string;
+    readonly depositExpiresAtMs?: number;
+    readonly delegatedAtMs?: number;
+    readonly syncSecret?: Uint8Array;
+    readonly recoveryCode?: Uint8Array;
+}
+declare function listPersistedTransfers(session: Session): Promise<readonly PersistedTransfer[]>;
+declare function getPersistedTransfer(session: Session, swapId: string): Promise<PersistedTransfer | null>;
+declare function removePersistedTransfer(session: Session, swapId: string): Promise<void>;
+declare function purgePersistedTransfers(session: Session): Promise<void>;
 
 /**
  * Payout policy validation (spec sections 4.3.1 and 10.1).
@@ -214,12 +315,29 @@ interface ContractRequestArgs {
     readonly onSyncSecretReady?: (info: {
         secretHex: string;
     }) => void | Promise<void>;
+    /** Optional precomputed pre-delegation mutation secret, copied before it reaches the wire. */
+    readonly resumeSecret?: Uint8Array;
+    /** Called before ContractRequest so the caller can persist the resume secret. */
+    readonly onResumeSecretReady?: (info: {
+        secretHex: string;
+    }) => void | Promise<void>;
+    /** Called after allocation so the caller can persist both secrets with the swap id. */
+    readonly onSwapAllocated?: (info: {
+        swapId: string;
+        syncSecretHex: string;
+        resumeSecretHex: 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>;
+    /** Called before DkgRound2 so the caller can persist the generated Alice share. */
+    readonly onDelegateShareReady?: (info: {
+        swapId: string;
+        delegateShare: Uint8Array;
+    }) => void | Promise<void>;
 }
 /**
  * Start a new pool entry through the current normal-user coordinator flow.
@@ -235,18 +353,26 @@ interface ContractRequestArgs {
  *   session cannot complete the DKG/delegation boundary.
  */
 declare function contractRequest(session: Session, args: ContractRequestArgs): Promise<ContractRequestResult>;
+/** Resume pre-delegation DKG or delegation on a caller-owned Session. */
+declare function resumePreDelegation(session: Session, args: ResumePreDelegationParams): Promise<ResumePreDelegationResult>;
 /** Read the actor-scoped lifecycle projection for a normal-user contract. */
 declare function sync(session: Session, contractId: string, syncSecret: Uint8Array, timeoutMs?: number): Promise<SyncUserResponse>;
 /** Arguments to refund a pool entry with the Recovery Code preimage. */
 interface RequestRefundArgs {
+    /** Optional contract correlation required when multiple contracts share one Session. */
+    readonly swapId?: string;
+    /** Optional status secret used to restore the correlated contract context. */
+    readonly syncSecret?: Uint8Array;
     /** 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.
+ * Submit a normal-user `withdraw_request` with the Recovery Code preimage
+ * (`{ recovery_code }`). Pass `swapId` and `syncSecret` when multiple contracts
+ * share one Session so the request is correlated to the intended contract.
+ * 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`, including
  *   the coordinator-authoritative amount accepted for withdrawal. The
@@ -257,4 +383,4 @@ interface RequestRefundArgs {
  */
 declare function requestRefund(session: Session, args: RequestRefundArgs): Promise<RefundAcceptanceReceipt>;
 
-export { type ContractRequestArgs, type ContractRequestResult, 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, RECOVERY_CODE_BYTE_LENGTH, type RefundAcceptanceReceipt, type RefundExecutedPayload, type RequestRefundArgs, SUPPORTED_TOTAL_DEADLINE_MS, type SourceLiquidityUse, type SpendingPolicySnapshot, type SyncUserResponse, type SyncUserResponsePayload, type WithdrawExecutedPayload, commitmentFromCode, contractRequest, generateRecoveryCode, recoveryCodeFromHex, recoveryCodeFromUserInput, recoveryCodeToHex, requestRefund, sync };
+export { type ContractRequestArgs, type ContractRequestResult, 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 PersistedTransfer, type PersistedTransferStage, RECOVERY_CODE_BYTE_LENGTH, type RefundAcceptanceReceipt, type RefundExecutedPayload, type RequestRefundArgs, type ResumePreDelegationParams, type ResumePreDelegationResult, SUPPORTED_TOTAL_DEADLINE_MS, type SourceLiquidityUse, type SpendingPolicySnapshot, type SyncUserResponse, type SyncUserResponsePayload, type WithdrawExecutedPayload, commitmentFromCode, contractRequest, generateRecoveryCode, getPersistedTransfer, listPersistedTransfers, purgePersistedTransfers, recoveryCodeFromHex, recoveryCodeFromUserInput, recoveryCodeToHex, removePersistedTransfer, requestRefund, resumePreDelegation, sync };