@toon-protocol/sdk 2.0.0 → 2.1.0

package/dist/swap-DF4ghKio.d.ts

@@ -1,484 +0,0 @@
-import { NostrEvent, UnsignedEvent } from 'nostr-tools/pure';
-import { IlpPreparePacket, SwapPair } from '@toon-protocol/core';
-
-/**
- * NIP-59 Gift Wrap Integration for ILP Packets (Story 12.2)
- *
- * Provides privacy-preserving encoding/decoding of swap packets using the
- * NIP-59 three-layer gift wrap construction (rumor -> seal -> gift wrap).
- * Intermediary peers routing ILP packets see only opaque TOON-encoded binary
- * in the data field -- they cannot determine the event kind, sender identity,
- * or swap intent. Only the destination Swap can unwrap and process.
- *
- * Also provides NIP-44 encryption/decryption for FULFILL claim return path
- * (D12-008), using ephemeral keys so intermediaries on the return path see
- * only opaque ciphertext.
- *
- * @module
- */
-
-/** Parameters for {@link wrapSwapPacket}. */
-interface WrapSwapPacketParams {
-    /** Unsigned inner event containing swap metadata. */
-    rumor: UnsignedEvent;
-    /** Sender's secp256k1 secret key. */
-    senderSecretKey: Uint8Array;
-    /** Swap's compressed hex pubkey (64 chars). */
-    recipientPubkey: string;
-}
-/** Result of {@link wrapSwapPacket}. */
-interface WrapSwapPacketResult {
-    /** Fully-formed kind:1059 gift wrap event signed by a fresh ephemeral key. */
-    giftWrap: NostrEvent;
-    /** The ephemeral pubkey used for the outer gift wrap layer. */
-    ephemeralPubkey: string;
-}
-/** Parameters for {@link unwrapSwapPacket}. */
-interface UnwrapSwapPacketParams {
-    /** A kind:1059 gift wrap event. */
-    giftWrap: NostrEvent;
-    /** Recipient's (Swap's) secret key. */
-    recipientSecretKey: Uint8Array;
-}
-/** Result of {@link unwrapSwapPacket}. */
-interface UnwrapSwapPacketResult {
-    /** The decrypted inner rumor (unsigned). */
-    rumor: UnsignedEvent;
-    /** The sender's real pubkey (extracted from the seal layer). */
-    senderPubkey: string;
-}
-/** Parameters for {@link wrapSwapPacketToToon}. */
-interface WrapSwapPacketToToonParams {
-    /** Unsigned inner event containing swap metadata. */
-    rumor: UnsignedEvent;
-    /** Sender's secp256k1 secret key. */
-    senderSecretKey: Uint8Array;
-    /** Swap's compressed hex pubkey (64 chars). */
-    recipientPubkey: string;
-    /** ILP destination address. */
-    destination: string;
-    /** Payment amount in ILP units (bigint). */
-    amount: bigint;
-    /** Packet expiry. Default: 30s from now (inside buildIlpPrepare). */
-    expiresAt?: Date;
-}
-/** Result of {@link wrapSwapPacketToToon}. */
-interface WrapSwapPacketToToonResult {
-    /** Ready-to-send ILP PREPARE packet with TOON-encoded gift wrap as data. */
-    ilpPrepare: IlpPreparePacket;
-    /** The ephemeral pubkey used for the outer gift wrap layer. */
-    ephemeralPubkey: string;
-}
-/** Parameters for {@link unwrapSwapPacketFromToon}. */
-interface UnwrapSwapPacketFromToonParams {
-    /** The data field from an incoming ILP PREPARE (TOON-encoded gift wrap). */
-    toonData: Uint8Array;
-    /** Recipient's (Swap's) secret key. */
-    recipientSecretKey: Uint8Array;
-}
-/** Parameters for {@link encryptFulfillClaim}. */
-interface EncryptFulfillClaimParams {
-    /** The signed claim bytes to encrypt. */
-    claimData: Uint8Array;
-    /** The original sender's pubkey (recovered from unwrap). */
-    senderPubkey: string;
-}
-/** Result of {@link encryptFulfillClaim}. */
-interface EncryptFulfillClaimResult {
-    /** NIP-44 encrypted claim bytes. */
-    ciphertext: Uint8Array;
-    /** The Swap's ephemeral pubkey (included in FULFILL so sender can decrypt). */
-    ephemeralPubkey: string;
-}
-/** Parameters for {@link decryptFulfillClaim}. */
-interface DecryptFulfillClaimParams {
-    /** The encrypted claim bytes from the FULFILL data field. */
-    ciphertext: Uint8Array;
-    /** The Swap's ephemeral pubkey from the FULFILL data field. */
-    ephemeralPubkey: string;
-    /** The sender's (recipient of FULFILL) secret key. */
-    recipientSecretKey: Uint8Array;
-}
-/**
- * NIP-59 three-layer gift wrap a swap packet.
- *
- * Constructs a kind:1059 gift wrap event using a fresh ephemeral keypair.
- * The rumor is sealed with the sender's real key, then wrapped with the
- * ephemeral key. Intermediaries see only the ephemeral pubkey.
- *
- * Each invocation generates a fresh ephemeral keypair for forward secrecy
- * and message unlinkability (risk R-006).
- *
- * @throws {GiftWrapError} If the wrap operation fails (invalid keys, crypto failure).
- */
-declare function wrapSwapPacket(params: WrapSwapPacketParams): WrapSwapPacketResult;
-/**
- * Unwrap a NIP-59 gift-wrapped swap packet, recovering the inner rumor
- * and the sender's real pubkey.
- *
- * Performs two-layer decryption: gift wrap -> seal -> rumor.
- * The sender pubkey is extracted from the seal's pubkey field.
- *
- * @throws {GiftWrapError} If kind is not 1059, decryption fails, or structure is malformed.
- */
-declare function unwrapSwapPacket(params: UnwrapSwapPacketParams): UnwrapSwapPacketResult;
-/**
- * Convenience: gift wrap a swap packet, encode to TOON binary, and build
- * an ILP PREPARE packet.
- *
- * This is the path that `streamSwap()` (Story 12.5) will use in its
- * per-packet loop.
- */
-declare function wrapSwapPacketToToon(params: WrapSwapPacketToToonParams): WrapSwapPacketToToonResult;
-/**
- * Convenience: decode TOON binary from an incoming ILP PREPARE data field
- * and unwrap the gift-wrapped swap packet.
- *
- * This is the path that the Swap handler (Story 12.3) will use to process
- * incoming swap packets.
- */
-declare function unwrapSwapPacketFromToon(params: UnwrapSwapPacketFromToonParams): UnwrapSwapPacketResult;
-/**
- * Encrypt a FULFILL claim for the return path (D12-008).
- *
- * Generates a fresh ephemeral keypair and NIP-44 encrypts the claim data.
- * The ephemeral pubkey is included alongside the ciphertext so the sender
- * can decrypt. The ephemeral privkey is discarded after encryption.
- *
- * @throws {GiftWrapError} If claimData is empty or encryption fails.
- */
-declare function encryptFulfillClaim(params: EncryptFulfillClaimParams): EncryptFulfillClaimResult;
-/**
- * Decrypt a FULFILL claim from the return path.
- *
- * Uses the sender's secret key and the Swap's ephemeral pubkey (from the
- * FULFILL data field) to NIP-44 decrypt the claim bytes.
- *
- * @throws {GiftWrapError} If decryption fails (wrong key, malformed ciphertext).
- */
-declare function decryptFulfillClaim(params: DecryptFulfillClaimParams): Uint8Array;
-
-/**
- * Sender-side `streamSwap()` API (Story 12.5).
- *
- * Drives the sender side of the Token Swap Primitive: chunks a total source
- * amount into N sender-chosen packets, wraps each with `wrapSwapPacketToToon()`
- * using a fresh ephemeral gift-wrap key per packet (D12-003 / risk R-006),
- * sends each via `ToonClient.sendSwapPacket(...)`, decrypts each FULFILL's
- * NIP-44-encrypted claim with `decryptFulfillClaim()`, accumulates the
- * decrypted claims into an ordered array, invokes a per-packet rate monitoring
- * callback, and supports pause / resume / stop / AbortSignal so the sender
- * can abort when rate drifts past tolerance.
- *
- * Composition story: consumes Stories 12.1 (SwapPair type), 12.2 (gift wrap
- * primitives), 12.3 (handler wire contract). Produces `AccumulatedClaim[]`
- * consumed by Story 12.6 (`buildSettlementTx()`).
- *
- * Design decisions:
- * - `streamSwap()` does NOT throw on mid-stream failure. Caller gets
- *   `StreamSwapResult` with `state` and `abortReason`. Only construction-time
- *   validation throws synchronously.
- * - `streamSwap()` does NOT retry individual packets. BTP-level connection
- *   retries are handled inside `BtpRuntimeClient`; application-layer retry
- *   (e.g., T04 insufficient inventory) is a future-story concern.
- * - Rate deviation math stays BigInt throughout. The `effectiveRate` on
- *   `PacketProgress` is a display-only `number` (Epic 11 retro MAX_SAFE_INTEGER
- *   guard).
- *
- * @module
- */
-
-/** Minimal `IlpSendResult` shape — mirrors `packages/client/src/types.ts`. */
-interface IlpSendResultLike {
-    accepted: boolean;
-    data?: string;
-    code?: string;
-    message?: string;
-}
-/**
- * Minimal `SignedBalanceProof` structural type.
- *
- * We avoid importing from `@toon-protocol/client` so the SDK package does not
- * gain a runtime dep on the client package. The sender layer only forwards
- * this opaquely to `ToonClient.sendSwapPacket`.
- */
-type SignedBalanceProofLike = any;
-/**
- * The subset of `ToonClient` that `streamSwap()` requires. This narrow shape
- * exists so that consumers can pass a real `ToonClient` OR a mock without
- * importing the whole class.
- */
-interface StreamSwapClient {
-    sendSwapPacket(params: {
-        destination: string;
-        amount: bigint;
-        toonData: Uint8Array;
-        timeout?: number;
-        claim?: SignedBalanceProofLike;
-    }): Promise<IlpSendResultLike>;
-    getPublicKey(): string;
-}
-/**
- * Parameters for {@link streamSwap} / {@link streamSwapControlled}.
- *
- * @stable — downstream Stories 12.6 and 12.8 depend on this shape.
- */
-interface StreamSwapParams {
-    /** SDK client with BTP wiring (see {@link StreamSwapClient}). */
-    client: StreamSwapClient;
-    /** Swap's 64-char lowercase hex pubkey (recipient of gift wrap). */
-    swapPubkey: string;
-    /** Swap's ILP destination address (e.g., 'g.toon.swap1'). */
-    swapIlpAddress: string;
-    /** The `SwapPair` being executed (from kind:10032 discovery, Story 12.1). */
-    pair: SwapPair;
-    /** Sender's 32-byte secp256k1 secret key. Used for seal signing AND FULFILL decryption. */
-    senderSecretKey: Uint8Array;
-    /**
-     * Sender's chain-specific payout address for `pair.to.chain` (Story 12.9 AC-4).
-     *
-     * REQUIRED. The Nostr `senderPubkey` (identity layer) cannot be used as the
-     * on-chain `recipient` in a balance-proof because they are cryptographically
-     * independent keys (D12-011). For `evm:*` chains this must be a 20-byte
-     * lowercased `0x`-prefixed hex address; for `solana:*` a base58 pubkey that
-     * decodes to 32 bytes; for `mina:*` a base58 public-key string. The value
-     * is validated at `streamSwapControlled()` entry via `validateChainAddress`
-     * and echoed on every rumor as the `chain-recipient` tag (AC-6).
-     */
-    chainRecipient: string;
-    /** Total source-asset amount to swap (source micro-units). */
-    totalAmount: bigint;
-    /** Even-split packet count. EXACTLY ONE of this or `packetAmounts` is required. */
-    packetCount?: number;
-    /** Explicit per-packet amounts. EXACTLY ONE of this or `packetCount` is required. */
-    packetAmounts?: readonly bigint[];
-    /** Source-asset balance proof claim. Required unless ChannelManager is wired. */
-    claim?: SignedBalanceProofLike;
-    /** Rate monitoring callback (fires after each accepted FULFILL). */
-    onPacket?: RateMonitorCallback;
-    /** Rate deviation threshold (decimal, e.g., 0.02 = 2%). */
-    rateDeviationThreshold?: number;
-    /** Per-packet timeout in ms. Default 30000. */
-    packetTimeoutMs?: number;
-    /** Optional AbortSignal. */
-    signal?: AbortSignal;
-    /**
-     * Optional pino-compatible logger. Defaults to a no-op.
-     *
-     * Note: `streamSwap` calls each method with a single structured-event object
-     * (e.g., `logger.warn({ event: 'stream_swap.packet_rejected', code, ... })`).
-     * Pino accepts this form (the object is logged as top-level fields and the
-     * message is left empty); other loggers that expect `(msg, meta)` should
-     * wrap accordingly.
-     */
-    logger?: {
-        debug: (...a: unknown[]) => void;
-        info: (...a: unknown[]) => void;
-        warn: (...a: unknown[]) => void;
-        error: (...a: unknown[]) => void;
-    };
-}
-/**
- * Rate monitoring callback. Fires after each successful FULFILL decryption,
- * before the next packet is sent. If the callback throws or rejects, the
- * stream is treated as stopped.
- */
-type RateMonitorCallback = (progress: PacketProgress) => void | Promise<void>;
-/**
- * Progress payload delivered to {@link RateMonitorCallback}. Frozen to
- * prevent callback mutation.
- */
-interface PacketProgress {
-    /** 0-indexed packet number within this streamSwap invocation. */
-    index: number;
-    /** Total number of packets scheduled. */
-    total: number;
-    /** Source-asset amount sent for this packet (micro-units). */
-    sourceAmount: bigint;
-    /** Target-asset claim amount derived for this packet (micro-units). */
-    targetAmount: bigint;
-    /** Rate advertised on the `SwapPair` at swap start (decimal string). */
-    advertisedRate: string;
-    /** Effective rate for this packet as JS Number (target / source in whole units). Display-only. */
-    effectiveRate: number;
-    /** Absolute deviation from advertisedRate as a decimal (e.g., 0.0125 = 1.25%). */
-    rateDeviation: number;
-    /** Cumulative source sent across accepted packets so far (including this one). */
-    cumulativeSource: bigint;
-    /** Cumulative target received so far (including this one). */
-    cumulativeTarget: bigint;
-    /** Controller state at callback time. */
-    state: 'running' | 'paused' | 'stopped';
-}
-/**
- * An accumulated claim successfully harvested from a single packet.
- *
- * @stable — Story 12.6 (`buildSettlementTx()`) depends on this shape.
- * Breaking changes require a coordinated migration.
- *
- * Story 12.6 ADDITIVE extension: the settlement-context fields
- * `channelId`, `nonce`, `cumulativeAmount`, `recipient`, and
- * `swapSignerAddress` are marked optional (`?:`) for one story-cycle of
- * backward compat but are REQUIRED in practice: Story 12.6's
- * `buildSettlementTx()` throws `MISSING_SETTLEMENT_METADATA` when any of
- * these are absent.
- */
-interface AccumulatedClaim {
-    /** 0-indexed position in the swap's packet stream. */
-    packetIndex: number;
-    /** Source-asset amount sent for this packet (micro-units). */
-    sourceAmount: bigint;
-    /**
-     * Target-asset amount claimed (micro-units).
-     *
-     * **Source of truth caveat:** This is the expected target amount computed
-     * by `applyRate(pair.rate)`. The actual signed-claim amount lives inside
-     * `claimBytes`; Story 12.6 is responsible for parsing `claimBytes` per
-     * chain and verifying the on-wire signed amount equals this expected amount.
-     */
-    targetAmount: bigint;
-    /** Decrypted signed claim bytes. Chain-specific encoding per Story 12.4. */
-    claimBytes: Uint8Array;
-    /** Swap's ephemeral pubkey from the FULFILL (64-char lowercase hex). */
-    swapEphemeralPubkey: string;
-    /** Optional Swap-side claim ID (passed through from handler metadata). */
-    claimId?: string;
-    /** Swap pair this claim was priced against (copy of `pair` for settlement-time routing). */
-    pair: SwapPair;
-    /** Unix ms timestamp when this claim was accepted. */
-    receivedAt: number;
-    /** Channel identifier on the target chain (lowercase hex with 0x prefix for EVM; base58 for Solana). */
-    channelId?: string;
-    /** Balance-proof nonce (decimal string). Monotonically increasing within a channel. */
-    nonce?: string;
-    /** Cumulative transferred amount on the channel (target micro-units, decimal string). */
-    cumulativeAmount?: string;
-    /** Recipient address (the sender's target-asset address). */
-    recipient?: string;
-    /** Swap's on-chain signer address. */
-    swapSignerAddress?: string;
-}
-/**
- * Aggregate result of a `streamSwap()` invocation.
- *
- * @stable — Stories 12.6 and 12.8 depend on this shape.
- */
-interface StreamSwapResult {
-    state: 'completed' | 'failed' | 'stopped';
-    claims: AccumulatedClaim[];
-    rejections: {
-        packetIndex: number;
-        sourceAmount: bigint;
-        code: string;
-        message: string;
-    }[];
-    errors: {
-        packetIndex: number;
-        cause: Error;
-    }[];
-    abortReason: 'complete' | 'aborted' | 'stopped' | 'callback-stop' | 'callback-throw' | 'rate-deviation' | 'all-rejected';
-    cumulativeSource: bigint;
-    cumulativeTarget: bigint;
-    packetsSent: number;
-    packetsScheduled: number;
-}
-/** External controller returned by {@link streamSwapControlled}. */
-interface StreamSwapController {
-    pause(): void;
-    resume(): void;
-    stop(): void;
-    readonly state: 'running' | 'paused' | 'stopped' | 'completed' | 'failed';
-}
-/** Length-split `total` into `count` bigints. Remainder absorbed on last element. */
-declare function chunkAmount(total: bigint, count: number): bigint[];
-/** Build the kind:20032 unsigned "swap rumor" event per AC-4.
- *
- * Story 12.9 AC-1/AC-6: the returned rumor MUST include a `chain-recipient`
- * tag carrying the sender-supplied chain-format payout address for
- * `pair.to.chain`. The value is echoed verbatim per packet — no case-folding
- * or transformation beyond what the sender-side `validateChainAddress`
- * accepts.
- */
-declare function buildSwapRumor(input: {
-    senderPubkey: string;
-    pair: SwapPair;
-    sourceAmount: bigint;
-    packetIndex: number;
-    totalPackets: number;
-    nonce: Uint8Array;
-    createdAt: number;
-    chainRecipient: string;
-}): UnsignedEvent;
-/**
- * Decode the FULFILL response `data` (base64-encoded JSON metadata) into
- * the `{ claim, ephemeralPubkey, claimId?, targetAmount?, ...settlement }`
- * shape.
- *
- * Story 12.6 extension: also parses the settlement-context fields
- * (`channelId`, `nonce`, `cumulativeAmount`, `recipient`, `swapSignerAddress`).
- * These are OPTIONAL and best-effort (#153): each is threaded through only
- * when it is a well-formed string for the target chain; an absent or malformed
- * settlement field is silently dropped rather than failing the whole decode,
- * so a fulfilled swap still surfaces its signed `claim` + `ephemeralPubkey`.
- * Only `claim` and `ephemeralPubkey` are strictly required.
- *
- * @param chain Optional `pair.to.chain` string for per-chain format validation
- *   of channelId / recipient / swapSignerAddress. When omitted, format checks
- *   fall back to a length-only sanity check.
- */
-declare function decodeFulfillMetadata(data: string | undefined, chain?: string): {
-    claim: string;
-    ephemeralPubkey: string;
-    claimId?: string;
-    /** Optional Swap-reported actual target amount (decimal string). Used for rate deviation when present. */
-    targetAmount?: string;
-    channelId?: string;
-    nonce?: string;
-    cumulativeAmount?: string;
-    recipient?: string;
-    swapSignerAddress?: string;
-};
-/**
- * Drive a multi-packet swap against a Swap and return a `StreamSwapResult`.
- *
- * `streamSwap()` does NOT throw on mid-stream failure — inspect the result's
- * `state`, `abortReason`, `rejections[]`, and `errors[]` to diagnose.
- *
- * @example
- * ```ts
- * // Discover the SwapPair from the Swap's kind:10032 peer-info event (Story 12.1).
- * const result = await streamSwap({
- *   client: toonClient,
- *   swapPubkey: swap.pubkey,
- *   swapIlpAddress: 'g.toon.swap1',
- *   pair,
- *   senderSecretKey,
- *   totalAmount: 1_000_000n,
- *   packetCount: 10,
- *   onPacket: (p) => console.log('packet', p.index, 'rate', p.effectiveRate),
- *   rateDeviationThreshold: 0.02,
- * });
- * // Feed result.claims into buildSettlementTx() from Story 12.6.
- * ```
- *
- * @throws {StreamSwapError} Only for construction-time validation failures
- *   (INVALID_AMOUNT, INVALID_CHUNKING, INVALID_PAIR, INVALID_STATE).
- */
-declare function streamSwap(params: StreamSwapParams): Promise<StreamSwapResult>;
-/**
- * Two-form variant of {@link streamSwap} that additionally returns a
- * {@link StreamSwapController} with `pause()` / `resume()` / `stop()`.
- *
- * @throws {StreamSwapError} Synchronously for construction-time validation.
- */
-declare function streamSwapControlled(params: StreamSwapParams): {
-    result: Promise<StreamSwapResult>;
-    controller: StreamSwapController;
-};
-declare const __testing: {
-    chunkAmount: typeof chunkAmount;
-    decodeFulfillMetadata: typeof decodeFulfillMetadata;
-    buildSwapRumor: typeof buildSwapRumor;
-};
-
-export { type AccumulatedClaim as A, type DecryptFulfillClaimParams as D, type EncryptFulfillClaimParams as E, type PacketProgress as P, type RateMonitorCallback as R, type StreamSwapController as S, type UnwrapSwapPacketFromToonParams as U, type WrapSwapPacketParams as W, __testing as _, type EncryptFulfillClaimResult as a, type StreamSwapParams as b, type StreamSwapResult as c, type UnwrapSwapPacketParams as d, type UnwrapSwapPacketResult as e, type WrapSwapPacketResult as f, type WrapSwapPacketToToonParams as g, type WrapSwapPacketToToonResult as h, decryptFulfillClaim as i, encryptFulfillClaim as j, streamSwapControlled as k, unwrapSwapPacketFromToon as l, wrapSwapPacketToToon as m, type StreamSwapClient as n, streamSwap as s, unwrapSwapPacket as u, wrapSwapPacket as w };