@toon-protocol/sdk 2.0.1 → 2.1.0

package/dist/swap-Oub-0vqU.d.ts

@@ -0,0 +1,911 @@
+import { NostrEvent, UnsignedEvent } from 'nostr-tools/pure';
+import { IlpPreparePacket, SwapPair, ToonError } 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;
+    /**
+     * Per-packet expiry. Propagated onto the produced PREPARE as an ISO 8601
+     * `expiresAt` string (rolling-swap R7 leg ordering). When omitted, the
+     * transport applies its default (timeout-derived, ~30s).
+     */
+    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;
+
+/**
+ * Adaptive δ/W controller for rolling swaps (issue #83, rolling-swap spec §6).
+ *
+ * Two knobs, managed separately:
+ * - `δ` (delta) — packet size in source micro-units — bounds *per-packet
+ *   pick-off risk*.
+ * - `W` (window) — max unfulfilled packets in flight — bounds *timing /
+ *   liveness risk* and the worst-case unrecovered exposure `δ·W`.
+ *
+ * Normative behavior implemented here (spec §6):
+ * - **The cap.** `delta_cap = ε / (v·τ)`, recomputed per packet from measured
+ *   state, and `δ ≤ delta_cap` always. δ and `delta_cap` are fractions of the
+ *   session's remaining notional; `v·τ` is the expected fractional rate drift
+ *   while one packet is in flight; ε is the per-packet slippage budget as a
+ *   fraction of the maker's advertised half-spread (default `ε = 0.5 ×
+ *   halfSpread`). ε is spread-denominated, never an absolute rate.
+ * - **Inputs are measured, not trusted.** `v` is an EWMA of
+ *   `abs(R_i − R_{i−1})/R_{i−1}` per second read off the quote tape
+ *   (`PacketProgress.rate` / `rateTimestamp`, issue #82); `τ` is an EWMA of
+ *   observed round-trip times. Both update on every observed packet.
+ * - **Asymmetric adjustment, one knob per step.** On a shrink signal (a
+ *   `stale_rate` reject, any other reject/verification failure, or realized
+ *   per-packet slip `> ε`): multiplicative — `δ ← max(δ_min, δ/2)`; if the
+ *   signal was a timeout/expiry, `W ← max(1, ⌈W/2⌉)` instead. On a clean
+ *   streak of `K = 16` consecutive fulfills: additive — `δ ← min(caps, δ +
+ *   δ_0)` or `W ← min(W_max, W + 1)`, alternating, never both in one step.
+ * - **Cold start ramps.** With no persisted state for the tuple:
+ *   `δ_0 = min(delta_cap, notional/256, maker maxAmount)`, `W_0 = 1`. Until
+ *   the first shrink signal ever observed for the tuple, the δ widen step is
+ *   multiplicative (`δ ← min(caps, 2δ)` per clean streak) — slow-start —
+ *   dropping to additive permanently after the first loss event.
+ * - **State is per-(chain, maker, pair) and persisted** via a pluggable
+ *   {@link SwapControllerStateStore} (the SDK is isomorphic; the JSON-file
+ *   implementation is Node-only and lazily imports `node:fs`).
+ *
+ * INVARIANT (spec §5): the controller is an *efficiency* mechanism only. It
+ * never sees, computes, or relaxes the `minExchangeRate` floor — the floor
+ * check in `stream-swap.ts` runs before the controller observes anything and
+ * consults nothing but the floor itself. A calm (or adversarially painted)
+ * tape can widen δ up to the caps, but can never worsen the sender's declared
+ * worst case. NOTE: the adversarial-quote-tape question (toon-meta#146 — a
+ * maker quoting calm to coax δ wide, then gapping one large packet) is open;
+ * its resolution may tighten the cap logic here. The floor plus the absolute
+ * `maxPacketAmount` cap are the uncompromising backstops in the meantime.
+ *
+ * @module
+ */
+
+/**
+ * Error thrown for invalid adaptive-controller configuration or a
+ * persistence-layer failure surfaced through {@link SwapControllerStateStore}.
+ */
+declare class SwapControllerError extends ToonError {
+    constructor(message: string, cause?: Error);
+}
+/**
+ * Persisted per-(chain, maker, pair) controller state (spec §6 value shape
+ * `{delta, W, vEwma, tauEwma, cleanStreak, everShrunk, updatedAt}` plus the
+ * additive `lastWidened` alternation marker).
+ *
+ * JSON-serializable by construction: `delta` is a decimal string because
+ * `bigint` does not survive `JSON.stringify`.
+ */
+interface SwapControllerState {
+    /** Schema version for forward migration. Currently `1`. */
+    v: 1;
+    /**
+     * Current ramp value of δ in source micro-units (decimal string).
+     * `'0'` means "not yet initialized" — the first `nextDelta()` call seeds it
+     * with the cold-start `δ_0`.
+     */
+    delta: string;
+    /** In-flight window W: max unfulfilled packets outstanding. Always ≥ 1. */
+    W: number;
+    /** EWMA of `abs(ΔR)/R` per second, measured from the quote tape. */
+    vEwma: number;
+    /** EWMA of observed packet round-trip time, in seconds. */
+    tauEwma: number;
+    /** Consecutive clean fulfills since the last knob adjustment. */
+    cleanStreak: number;
+    /**
+     * True once ANY shrink signal has ever been observed for this tuple.
+     * Ends the multiplicative slow-start widen ramp permanently (spec §6).
+     */
+    everShrunk: boolean;
+    /** Which knob the most recent widen step adjusted (alternation marker). */
+    lastWidened: 'delta' | 'window';
+    /** Unix ms of the last state mutation. */
+    updatedAt: number;
+}
+/** Runtime shape check for a (possibly foreign) persisted state blob. */
+declare function isSwapControllerState(value: unknown): value is SwapControllerState;
+/**
+ * Canonical persistence key for a controller tuple (spec §6):
+ * `${chain}:${makerPubkey}:${from}:${to}` with `from`/`to` as
+ * `assetCode@chain` so cross-chain pairs sharing an asset code stay distinct.
+ *
+ * The leading `chain` segment is the SOURCE chain — per-tuple state is how
+ * the same code runs fast on Base and cautious on Mina.
+ */
+declare function swapControllerStateKey(params: {
+    makerPubkey: string;
+    pair: SwapPair;
+}): string;
+/**
+ * Pluggable persistence seam for controller state, keyed by
+ * {@link swapControllerStateKey}. The SDK is isomorphic, so the interface is
+ * environment-neutral (same pattern as `WorkflowEventStore`); pick
+ * {@link JsonFileSwapControllerStateStore} on Node or supply your own
+ * (e.g. IndexedDB / daemon-side store in toon-client).
+ */
+interface SwapControllerStateStore {
+    load(key: string): Promise<SwapControllerState | undefined>;
+    save(key: string, state: SwapControllerState): Promise<void>;
+}
+/** Volatile in-memory store — the default when no store is configured. */
+declare class InMemorySwapControllerStateStore implements SwapControllerStateStore {
+    private readonly states;
+    load(key: string): Promise<SwapControllerState | undefined>;
+    save(key: string, state: SwapControllerState): Promise<void>;
+}
+/**
+ * Node-only JSON-file store (the toon-client `JsonFileChannelStore` pattern —
+ * controller state persists beside the channel store). One JSON file holds a
+ * `{ [key]: SwapControllerState }` map; writes are atomic
+ * (temp-file + rename). `node:fs` / `node:path` are imported lazily so
+ * bundling this module for the browser stays safe as long as the class is
+ * not instantiated there.
+ */
+declare class JsonFileSwapControllerStateStore implements SwapControllerStateStore {
+    private readonly filePath;
+    constructor(filePath: string);
+    private readAll;
+    load(key: string): Promise<SwapControllerState | undefined>;
+    save(key: string, state: SwapControllerState): Promise<void>;
+}
+/**
+ * Resolution class of one packet, as measured by the sender (spec §6):
+ *
+ * - `'fulfill'` — packet fulfilled and its claim accepted. Clean unless the
+ *   realized slip exceeds ε (computed internally from `rate` +
+ *   `sourceAmount` + `targetAmount`), in which case it is a shrink signal.
+ * - `'reject-stale'` — maker staleness reject (`T99 stale_rate`, spec §4).
+ *   Shrink signal → δ halves.
+ * - `'reject'` — any other reject or verification failure (R5-class: floor
+ *   breach, recipient substitution, bad claim). Shrink signal → δ halves.
+ * - `'timeout'` — packet expiry / transport timeout. Shrink signal → W
+ *   halves (timing risk, not pricing risk).
+ * - `'error'` — transport or decode error. Shrink signal → δ halves.
+ */
+type PacketResolution = 'fulfill' | 'reject-stale' | 'reject' | 'timeout' | 'error';
+/** One per-packet observation fed to {@link AdaptiveDeltaController.observe}. */
+interface PacketObservation {
+    /** Resolution class for this packet (see {@link PacketResolution}). */
+    resolution: PacketResolution;
+    /** Measured round-trip time for this packet in ms (send → resolve). */
+    rttMs?: number;
+    /** Quote-tape rate `R_i` for this packet (decimal string, issue #82). */
+    rate?: string;
+    /** Unix ms when the maker's rate source produced {@link rate}. */
+    rateTimestamp?: number;
+    /** Source amount sent for this packet (micro-units). Used for slip. */
+    sourceAmount?: bigint;
+    /** Delivered target amount (micro-units). Used for slip. */
+    targetAmount?: bigint;
+    /**
+     * Remaining session notional AFTER this packet (source micro-units).
+     * When provided, widen steps are additionally clamped to the current
+     * `delta_cap` fraction of it (spec §6 `δ ← min(delta_cap, δ + δ_0)`).
+     * `nextDelta()` re-enforces the cap at issuance regardless.
+     */
+    remaining?: bigint;
+}
+/**
+ * The seam `streamSwap` consumes (kept structural so alternative controller
+ * implementations — or a test double — can be plugged in).
+ */
+interface StreamSwapAdaptiveController {
+    /**
+     * Decide the size of the next packet, in source micro-units, given the
+     * session's remaining notional. MUST return a value in `[1, remaining]`
+     * (callers clamp defensively). Enforces `δ ≤ delta_cap` at issuance.
+     */
+    nextDelta(remaining: bigint): bigint;
+    /** Current in-flight window W (max unfulfilled packets outstanding, ≥ 1). */
+    readonly window: number;
+    /** Feed one packet observation. May persist state (hence async). */
+    observe(observation: PacketObservation): void | Promise<void>;
+}
+/** Configuration for {@link AdaptiveDeltaController.create}. */
+interface AdaptiveDeltaControllerConfig {
+    /** Maker's 64-char hex pubkey — part of the persistence key. */
+    makerPubkey: string;
+    /** The pair being executed — chain + asset parts of the persistence key. */
+    pair: SwapPair;
+    /**
+     * Maker's advertised two-sided spread as a fraction (e.g. `0.004` = 40 bps).
+     * ε is denominated off this — NEVER an absolute rate (spec §6): the
+     * half-spread self-calibrates ε per chain and per maker. Today the spread
+     * is caller-supplied (from the maker's board / RFQ response once toon#145's
+     * RFQ lands); there is deliberately no default — an invented spread would
+     * rot and silently mis-size ε.
+     */
+    advertisedSpread: number;
+    /**
+     * ε as a fraction of the advertised HALF-spread. Default `0.5`
+     * (spec §6 default `ε = 0.5 × halfSpread`).
+     */
+    epsilonHalfSpreadFraction?: number;
+    /**
+     * Absolute per-packet ceiling in source micro-units (the maker's advertised
+     * `maxAmount`). Applied to δ at issuance AND to every widen step — the
+     * uncompromising absolute cap alongside the measured `v·τ` bound.
+     */
+    maxPacketAmount?: bigint;
+    /** Floor on δ in source micro-units (`δ_min`). Default `1n`. */
+    minPacketAmount?: bigint;
+    /** Ceiling on W (`W_max`). Default `8`. */
+    maxWindow?: number;
+    /** Clean-fulfill streak length K per widen step. Default `16` (spec §6). */
+    cleanStreakLength?: number;
+    /**
+     * Cold-start divisor: `δ_0 = notional / coldStartDivisor` (further clamped
+     * by `delta_cap` and `maxPacketAmount`). Default `256` (spec §6).
+     */
+    coldStartDivisor?: number;
+    /** EWMA smoothing factor α for both `v` and `τ`, in (0, 1]. Default `0.2`. */
+    ewmaAlpha?: number;
+    /**
+     * Pluggable persistence. Default: a fresh volatile
+     * {@link InMemorySwapControllerStateStore} (state survives the session
+     * only). Pass {@link JsonFileSwapControllerStateStore} (Node) or a custom
+     * store to persist ramp/trust across swaps.
+     */
+    store?: SwapControllerStateStore;
+    /** Injectable clock for deterministic tests. Default `Date.now`. */
+    now?: () => number;
+}
+/**
+ * Per-(chain, maker, pair) adaptive δ/W controller (spec §6). Construct via
+ * {@link AdaptiveDeltaController.create} (async: loads persisted state).
+ *
+ * Concurrency note: one instance drives one swap session. Running two
+ * concurrent sessions against the same tuple is last-write-wins on the
+ * persisted state (same as concurrent channel use).
+ */
+declare class AdaptiveDeltaController implements StreamSwapAdaptiveController {
+    /** Persistence key for this tuple (see {@link swapControllerStateKey}). */
+    readonly key: string;
+    private readonly store;
+    private readonly pair;
+    private readonly epsilon;
+    private readonly maxPacketAmount;
+    private readonly minPacketAmount;
+    private readonly maxWindow;
+    private readonly cleanStreakLength;
+    private readonly coldStartDivisor;
+    private readonly alpha;
+    private readonly now;
+    private readonly stateInternal;
+    /** δ in-memory as bigint (mirrors `stateInternal.delta`). */
+    private delta;
+    /** Cold-start δ_0 — also the additive widen increment. Set on first nextDelta(). */
+    private delta0;
+    /** Previous tape entry for the per-second volatility measurement. */
+    private lastRate;
+    private lastRateTimestamp;
+    private constructor();
+    /**
+     * Create a controller for one swap session: loads the persisted state for
+     * the tuple from the store, or starts cold (`δ` unset until the first
+     * `nextDelta()`, `W = 1`).
+     */
+    static create(config: AdaptiveDeltaControllerConfig): Promise<AdaptiveDeltaController>;
+    /** Defensive snapshot of the current controller state. */
+    get state(): SwapControllerState;
+    /** Current in-flight window W. */
+    get window(): number;
+    /**
+     * Current `delta_cap = ε/(v·τ)` as a fraction of remaining notional.
+     * `Infinity` while `v·τ` has no measurement yet (cold tape) — the
+     * cold-start `δ_0` and absolute caps bound δ in that regime.
+     */
+    get deltaCapFraction(): number;
+    /** `delta_cap` in absolute source micro-units for a given remaining notional. */
+    private deltaCapAbsolute;
+    /**
+     * Decide the next packet size (source micro-units) for a session with
+     * `remaining` notional left. Enforces, in order: the measured
+     * `delta_cap = ε/(v·τ)` bound, the absolute `maxPacketAmount` cap, the
+     * remaining notional, and the `minPacketAmount` floor. Seeds the
+     * cold-start `δ_0 = min(delta_cap, notional/256, maxPacketAmount)` on
+     * first call.
+     */
+    nextDelta(remaining: bigint): bigint;
+    /**
+     * Feed one packet observation: updates the measured EWMAs (`v`, `τ`),
+     * applies at most ONE knob adjustment (asymmetric: multiplicative shrink /
+     * additive widen), and persists the state.
+     */
+    observe(observation: PacketObservation): Promise<void>;
+    /**
+     * Realized per-packet slip as a fraction: shortfall of the delivered
+     * target amount vs the amount implied by the packet's own tape rate `R_i`
+     * (spec §7.1 `Δcumulative` vs `⌊δ · R_i⌋` cross-check). `0` when the
+     * inputs are unavailable or delivery met the tape.
+     */
+    private realizedSlip;
+}
+
+/**
+ * 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;
+        /**
+         * Explicit per-packet PREPARE expiry. When set, the transport MUST use
+         * exactly this expiry on the wire instead of deriving one from the
+         * request timeout. Optional so existing `ToonClient` implementations
+         * remain structurally compatible (they ignore the extra field until
+         * the client-transport work lands).
+         */
+        expiresAt?: Date;
+    }): 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, `packetAmounts`, or `controller` is required. */
+    packetCount?: number;
+    /** Explicit per-packet amounts. EXACTLY ONE of this, `packetCount`, or `controller` is required. */
+    packetAmounts?: readonly bigint[];
+    /**
+     * Adaptive δ/W controller (issue #83, rolling-swap spec §6). EXACTLY ONE
+     * of this, `packetCount`, or `packetAmounts` is required.
+     *
+     * When set, packetization is DYNAMIC: the static even split is replaced by
+     * per-packet sizing from `controller.nextDelta(remaining)` (δ, capped by
+     * the measured `ε/(v·τ)` bound), and up to `controller.window` (W) packets
+     * are kept in flight concurrently. After every packet resolves, the
+     * controller receives a {@link PacketObservation} (realized rate, tape
+     * entry, RTT, resolution class) so δ and W adapt across the stream —
+     * multiplicative shrink on stale/slip/reject, additive widen on clean
+     * streaks.
+     *
+     * Adaptive-mode contract differences (each N/A to the legacy paths):
+     * - `PacketProgress.total` is the number of packets scheduled SO FAR (the
+     *   final count is unknown upfront).
+     * - With `W > 1`, `onPacket` fires in packet COMPLETION order, not strict
+     *   index order.
+     * - On a mid-stream halt (floor breach, stop, abort), already-sent
+     *   in-flight packets are drained and their claims harvested before the
+     *   result resolves.
+     *
+     * INVARIANT: the controller only tightens/loosens δ and W. It is consulted
+     * strictly AFTER the `minExchangeRate` floor check and can never relax it.
+     */
+    controller?: StreamSwapAdaptiveController;
+    /** 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;
+    /**
+     * Hard floor on the per-packet exchange rate (issue #82, rfc-0029
+     * `minExchangeRate` semantics; rolling-swap spec §5). Decimal string in
+     * `SwapPair.rate` format (target whole-units per source whole-unit),
+     * strictly positive.
+     *
+     * When set:
+     * - The quote tape (`rate` + `rateTimestamp` on each FULFILL's metadata)
+     *   becomes REQUIRED: a fulfilled packet whose metadata is missing the
+     *   tape is a loud per-packet `FULFILL_DECODE_FAILED` error, never a
+     *   silent drop.
+     * - Each fulfilled packet is checked BEFORE its claim is decrypted or
+     *   accumulated: if the maker's tape rate `R_i` is below the floor, OR
+     *   the delivered `targetAmount` is below `applyRate(sourceAmount,
+     *   minExchangeRate)`, the packet is recorded as a rejection with code
+     *   `BELOW_FLOOR` and the stream halts with `abortReason: 'below-floor'`.
+     *   A violating packet NEVER accumulates into `claims[]`.
+     *
+     * This is the safety mechanism, deliberately independent of (and never
+     * relaxed by) the soft `rateDeviationThreshold` monitor, the `onPacket`
+     * callback, or any future adaptive-controller signal: a calm tape must
+     * not be able to talk the sender into a worse worst case.
+     *
+     * When omitted, behavior is unchanged (legacy back-compat): the tape is
+     * optional and only the soft deviation monitor applies.
+     */
+    minExchangeRate?: string;
+    /** Per-packet timeout in ms. Default 30000. */
+    packetTimeoutMs?: number;
+    /**
+     * Per-packet PREPARE expiry window in ms. When set, each packet is sent
+     * with `expiresAt = now + packetExpiryMs` (computed at send time) so a
+     * stalled packet expires deterministically and releases its in-flight
+     * slot (rolling-swap R7). When omitted, behavior is unchanged: the
+     * transport derives the expiry from its timeout (back-compat default).
+     */
+    packetExpiryMs?: 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. In adaptive mode (`controller` set)
+     * packet sizing is dynamic, so this is the number scheduled SO FAR.
+     */
+    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;
+    /**
+     * Quote-tape entry (issue #82, rolling-swap spec §7.1): the maker's fresh
+     * rate `R_i` actually applied to THIS packet, as reported on the FULFILL
+     * metadata. Present iff the maker emitted the tape. The sequence of these
+     * values across packets, in `index` order, IS the price tape the adaptive
+     * controller (toon#83) consumes.
+     */
+    rate?: string;
+    /** Unix ms timestamp when the maker's rate source produced {@link rate}. Present iff `rate` is. */
+    rateTimestamp?: number;
+    /** 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;
+    /** Maker's fresh rate `R_i` applied to this packet (decimal string), from the FULFILL quote tape. */
+    rate?: string;
+    /** Unix ms timestamp when the maker's rate source produced `rate`. Present iff `rate` is. */
+    rateTimestamp?: number;
+}
+/**
+ * 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' | 'below-floor' | '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.
+ *
+ * Issue #82 extension (quote tape, rolling-swap spec §7.1): parses the
+ * per-packet quote-tape fields `rate` (decimal string, the maker's fresh
+ * `R_i`) and `rateTimestamp` (unix ms). Unlike the best-effort settlement
+ * fields, a MALFORMED tape is always a loud `FULFILL_DECODE_FAILED` — a
+ * present-but-garbled `rate`/`rateTimestamp`, or one field without the
+ * other, fails the decode rather than silently dropping, so a rolling
+ * sender can never run blind on a corrupt tape. A wholly ABSENT tape is
+ * permitted for legacy makers unless `opts.requireQuoteTape` is set (which
+ * `runLoop` does whenever `minExchangeRate` is armed).
+ *
+ * @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.
+ * @param opts.requireQuoteTape When true, a missing `rate`/`rateTimestamp`
+ *   pair is a `FULFILL_DECODE_FAILED` error instead of being tolerated.
+ */
+declare function decodeFulfillMetadata(data: string | undefined, chain?: string, opts?: {
+    requireQuoteTape?: boolean;
+}): {
+    claim: string;
+    ephemeralPubkey: string;
+    claimId?: string;
+    /** Optional Swap-reported actual target amount (decimal string). Used for rate deviation when present. */
+    targetAmount?: string;
+    /** Quote-tape rate `R_i` (decimal string). Present iff the maker emitted the tape. */
+    rate?: string;
+    /** Quote-tape timestamp (unix ms). Present iff `rate` is. */
+    rateTimestamp?: number;
+    channelId?: string;
+    nonce?: string;
+    cumulativeAmount?: string;
+    recipient?: string;
+    swapSignerAddress?: string;
+};
+/**
+ * Compare two decimal-string rates (RATE_REGEX format) exactly, in BigInt —
+ * no float coercion. Returns -1 if `a < b`, 0 if equal, 1 if `a > b`.
+ *
+ * Used by the issue #82 `minExchangeRate` floor to compare the maker's tape
+ * rate `R_i` against the floor without precision loss on long fractions.
+ */
+declare function compareDecimalRates(a: string, b: string): -1 | 0 | 1;
+/**
+ * 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;
+    compareDecimalRates: typeof compareDecimalRates;
+};
+
+export { type AccumulatedClaim as A, type StreamSwapClient as B, type DecryptFulfillClaimParams as D, type EncryptFulfillClaimParams as E, InMemorySwapControllerStateStore as I, JsonFileSwapControllerStateStore as J, type PacketObservation as P, type RateMonitorCallback as R, type StreamSwapAdaptiveController as S, type UnwrapSwapPacketFromToonParams as U, type WrapSwapPacketParams as W, __testing as _, AdaptiveDeltaController as a, type AdaptiveDeltaControllerConfig as b, type EncryptFulfillClaimResult as c, type PacketProgress as d, type PacketResolution as e, type StreamSwapController as f, type StreamSwapParams as g, type StreamSwapResult as h, SwapControllerError as i, type SwapControllerState as j, type SwapControllerStateStore as k, type UnwrapSwapPacketParams as l, type UnwrapSwapPacketResult as m, type WrapSwapPacketResult as n, type WrapSwapPacketToToonParams as o, type WrapSwapPacketToToonResult as p, decryptFulfillClaim as q, encryptFulfillClaim as r, isSwapControllerState as s, streamSwap as t, streamSwapControlled as u, swapControllerStateKey as v, unwrapSwapPacket as w, unwrapSwapPacketFromToon as x, wrapSwapPacket as y, wrapSwapPacketToToon as z };