@toon-protocol/sdk 2.0.1 → 2.2.0

package/dist/swap-PFQTJZA7.d.ts

@@ -0,0 +1,1244 @@
+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;
+
+/**
+ * rfc-0039-style stream receipts (issue #84, rolling-swap spec §7.2).
+ *
+ * Per fulfilled packet the maker attaches a compact SIGNED receipt to the
+ * FULFILL accept-metadata: a monotone cumulative proof of asset-B delivered
+ * in the session. The receipt chain is the sender's portable audit/dispute
+ * artifact today (it makes the maker-debt bound provable to a third party)
+ * and the natural input to a future escrow layer. Receipts are
+ * session-scoped via `streamNonce`; the latest receipt supersedes all
+ * earlier ones, mirroring the highest-nonce rule for claims.
+ *
+ * ## Deviations from Interledger rfc-0039 (documented per spec §7.2 — the
+ * TOON-native equivalent deliberately does not import the STREAM framing):
+ *
+ * - **Signature, not HMAC.** rfc-0039 authenticates receipts with
+ *   HMAC-SHA256 over a pre-shared 32-byte Receipt Secret, so only a party
+ *   holding the secret can verify. TOON receipts are BIP-340 Schnorr
+ *   signatures by the maker's receipt key (default: the maker's Nostr
+ *   identity key — the same `swapPubkey` the sender already discovered via
+ *   kind:10032), making every receipt verifiable by ANY third party with
+ *   the maker's pubkey. No Receipt Secret exists or is provisioned.
+ * - **Nonce provisioning.** rfc-0039's Verifier generates the Receipt Nonce
+ *   and communicates it out-of-band (SPSP headers). Here the sender (who is
+ *   its own verifier today) generates a 16-byte `streamNonce` per
+ *   `streamSwap()` invocation and communicates it in-band as the rumor's
+ *   `stream-nonce` tag. Legacy makers ignore the unknown tag.
+ * - **Encoding.** JSON object inside the accept-metadata dict rather than a
+ *   CANONICAL-OER STREAM frame. A deterministic length-prefixed binary
+ *   encoding ({@link encodeReceiptSigningPayload}) is used ONLY as the
+ *   signing preimage.
+ * - **Fields.** `seq` (maker's per-session fulfill counter — enables hole
+ *   detection, absent from rfc-0039), `rate` + `rateTimestamp` (the quote
+ *   tape entry, attested under the maker signature) are added; the STREAM
+ *   `Stream ID` is dropped (one logical stream per session — the
+ *   `streamNonce` IS the stream identity); `Total Received` is a decimal
+ *   string (bigint range) rather than UInt64.
+ *
+ * rfc-0039 semantics preserved: one receipt per fulfilled packet, each
+ * carrying a progressively higher cumulative total; latest supersedes;
+ * verification = authenticity check + monotonicity against previously seen
+ * receipts for the same nonce.
+ *
+ * @module
+ */
+/** Wire version of the TOON stream receipt. */
+declare const STREAM_RECEIPT_VERSION: 1;
+/** Domain-separation tag prefixed to the receipt signing payload. */
+declare const STREAM_RECEIPT_SIGNING_TAG = "toon.stream-receipt.v1";
+/** The signed fields of a {@link StreamReceipt} (everything except `sig`). */
+interface StreamReceiptFields {
+    /** Receipt wire version — always {@link STREAM_RECEIPT_VERSION}. */
+    v: typeof STREAM_RECEIPT_VERSION;
+    /**
+     * Session identifier: 32-char lowercase hex (16 bytes), generated by the
+     * sender per stream and echoed by the maker on every receipt.
+     */
+    streamNonce: string;
+    /**
+     * Maker's per-session fulfill counter, 1-based, strictly increasing by 1
+     * per fulfilled packet. Gaps observed by the sender indicate receipts it
+     * never received (hole detection).
+     */
+    seq: number;
+    /**
+     * Running total of asset B delivered in this session (target micro-units,
+     * decimal string). Monotone non-decreasing in `seq`; the latest receipt
+     * supersedes all earlier ones.
+     */
+    cumulativeDelivered: string;
+    /** The maker's quote `R_i` applied to the packet this receipt rode on (decimal string). */
+    rate: string;
+    /** Unix ms timestamp when the maker's rate source produced {@link rate}. */
+    rateTimestamp: number;
+}
+/**
+ * A signed stream receipt as carried on the FULFILL accept-metadata under
+ * the `receipt` key (rolling-swap spec §7.2).
+ */
+interface StreamReceipt extends StreamReceiptFields {
+    /**
+     * 128-char lowercase hex BIP-340 Schnorr signature by the maker's receipt
+     * key over `sha256(encodeReceiptSigningPayload(fields))`.
+     */
+    sig: string;
+}
+/**
+ * Aggregate view of the receipts harvested from one stream — the serialized
+ * audit/dispute artifact's in-memory shape. Returned on
+ * `StreamSwapResult.receipts` (present on abort too, covering what filled).
+ */
+interface StreamReceiptChain {
+    /** The sender-generated session nonce receipts were verified against. */
+    streamNonce: string;
+    /** All verified receipts, sorted by ascending `seq`. */
+    receipts: StreamReceipt[];
+    /** Highest-`seq` receipt — supersedes all others (rfc-0039 latest-wins). */
+    latest?: StreamReceipt;
+    /**
+     * `latest.cumulativeDelivered`, or `'0'` when no receipt was received —
+     * the signed total of asset B the maker attests to having delivered.
+     */
+    totalDelivered: string;
+    /**
+     * Missing `seq` values in `[1, latest.seq]`: fulfilled packets whose
+     * receipts the sender never received (lost FULFILLs, or maker skips).
+     */
+    holes: number[];
+}
+/** True iff `value` is a well-formed 32-char lowercase hex stream nonce. */
+declare function isValidStreamNonce(value: unknown): value is string;
+/**
+ * Structurally validate an untrusted metadata `receipt` value into a
+ * {@link StreamReceipt}. Checks shape ONLY — no signature or monotonicity
+ * verification (that is {@link verifyStreamReceipt} / {@link ReceiptChainTracker}).
+ *
+ * @throws {Error} with a human-readable reason when malformed. Callers
+ *   (e.g. `decodeFulfillMetadata`) wrap into their own error taxonomy.
+ */
+declare function parseStreamReceipt(value: unknown): StreamReceipt;
+/**
+ * Deterministic binary encoding of the signed receipt fields — the signing
+ * preimage. Layout (all integers big-endian):
+ *
+ * ```
+ * len(tag):u32 || tag(utf8) || v:u8 || streamNonce(16 raw bytes)
+ *   || seq:u64 || len:u32 || cumulativeDelivered(utf8)
+ *   || len:u32 || rate(utf8) || rateTimestamp:u64
+ * ```
+ *
+ * Length prefixes remove concatenation ambiguity between the variable-width
+ * decimal strings (same rationale as the swap-handler replay packet-id hash).
+ */
+declare function encodeReceiptSigningPayload(fields: StreamReceiptFields): Uint8Array;
+/**
+ * Sign the receipt fields with the maker's receipt secret key (32-byte
+ * secp256k1 scalar — by default the maker's Nostr identity key). Returns
+ * the complete {@link StreamReceipt} with the BIP-340 Schnorr `sig` over
+ * `sha256(encodeReceiptSigningPayload(fields))`.
+ */
+declare function signStreamReceipt(fields: StreamReceiptFields, secretKey: Uint8Array): StreamReceipt;
+/**
+ * Verify a receipt's Schnorr signature against the maker's receipt pubkey
+ * (64-char lowercase hex x-only key — by default the maker's `swapPubkey`).
+ * Authenticity only; monotonicity/session checks live in
+ * {@link ReceiptChainTracker}.
+ */
+declare function verifyStreamReceipt(receipt: StreamReceipt, makerPubkey: string): boolean;
+/** Outcome of {@link ReceiptChainTracker.add}. */
+type ReceiptAddResult = {
+    ok: true;
+} | {
+    ok: false;
+    /** Machine-readable rejection reason. */
+    code: 'BAD_SIGNATURE' | 'WRONG_STREAM_NONCE' | 'DUPLICATE_SEQ' | 'NON_MONOTONIC';
+    message: string;
+};
+/**
+ * Accumulates and verifies the receipt chain for ONE stream session.
+ *
+ * Per added receipt it checks, in order:
+ * 1. `streamNonce` matches the session (a receipt for another session is
+ *    worthless as proof for this one),
+ * 2. the Schnorr signature verifies against the maker's receipt pubkey,
+ * 3. `seq` is not a duplicate,
+ * 4. `cumulativeDelivered` is monotone in `seq` against every receipt seen
+ *    so far: non-decreasing with ascending `seq` (rfc-0039 "progressively
+ *    higher amount"; non-strict so a zero-target packet — possible under
+ *    `applyRate` truncation — does not read as maker equivocation).
+ *
+ * Receipts may be added OUT OF ORDER (adaptive W>1 streams complete in
+ * arbitrary order); monotonicity is enforced against both the nearest lower
+ * and nearest higher `seq` neighbors.
+ */
+declare class ReceiptChainTracker {
+    #private;
+    constructor(input: {
+        streamNonce: string;
+        makerPubkey: string;
+    });
+    get streamNonce(): string;
+    /** Number of verified receipts accumulated so far. */
+    get size(): number;
+    /**
+     * Verify + accumulate one receipt. On `{ok: false}` the receipt is NOT
+     * added and the chain is unchanged.
+     */
+    add(receipt: StreamReceipt): ReceiptAddResult;
+    /**
+     * Snapshot the accumulated chain: sorted receipts, the superseding latest,
+     * the signed total delivered, and any `seq` holes in `[1, latest.seq]`.
+     */
+    chain(): StreamReceiptChain;
+}
+/**
+ * Serialize a receipt chain into the portable audit/dispute artifact: a
+ * stable, versioned JSON document. Any third party holding the maker's
+ * receipt pubkey can re-verify every receipt in it offline (the enclosed
+ * receipts are self-contained signed statements).
+ */
+declare function serializeReceiptChain(chain: StreamReceiptChain): string;
+/** Per-session receipt issuance state kept by the maker. */
+interface ReceiptSessionState {
+    /** Last issued seq (0 = none issued yet). */
+    seq: number;
+    /** Cumulative asset-B delivered in the session so far (target micro-units). */
+    cumulativeDelivered: bigint;
+}
+/**
+ * Minimal synchronous store contract for maker-side receipt session state,
+ * keyed by `streamNonce`.
+ *
+ * SYNCHRONOUS by design: the swap handler performs the read-increment-write
+ * inside one microtask so concurrent packets in the same session get
+ * distinct, gapless `seq` values and consistent cumulative totals. An
+ * operator-supplied store that persists (e.g. alongside the claim/channel
+ * store, so receipt state survives restarts like claims do) should
+ * write-through asynchronously in the background while serving reads from
+ * memory. The default is {@link BoundedReceiptSessions} (in-memory LRU).
+ */
+interface ReceiptSessionStoreLike {
+    get(streamNonce: string): ReceiptSessionState | undefined;
+    set(streamNonce: string, state: ReceiptSessionState): unknown;
+    delete(streamNonce: string): boolean;
+}
+/**
+ * Default ceiling for the maker's receipt-session LRU. Same DoS rationale
+ * as `DEFAULT_SEEN_PACKET_IDS_CAP`: bounds memory against an attacker
+ * minting unlimited distinct stream nonces. An evicted (or maker-restarted)
+ * session restarts at seq 1 — the sender's tracker then rejects the
+ * duplicate seq loudly rather than accepting a forked chain.
+ */
+declare const DEFAULT_RECEIPT_SESSIONS_CAP = 10000;
+/**
+ * Bounded in-memory LRU {@link ReceiptSessionStoreLike}. Access-order
+ * eviction: active sessions stay pinned while stale ones age out.
+ */
+declare class BoundedReceiptSessions implements ReceiptSessionStoreLike {
+    #private;
+    constructor(cap?: number);
+    get size(): number;
+    get cap(): number;
+    get(streamNonce: string): ReceiptSessionState | undefined;
+    set(streamNonce: string, state: ReceiptSessionState): this;
+    delete(streamNonce: string): boolean;
+}
+/**
+ * Maker-side: advance the session state for one fulfilled packet and issue
+ * the corresponding signed receipt. The read-increment-write against the
+ * store happens synchronously (no awaits) so concurrent handler invocations
+ * interleave safely.
+ *
+ * MUST only be called for a packet that is being ACCEPTED — a rejected
+ * packet gets no receipt and MUST NOT advance the session.
+ */
+declare function issueSessionReceipt(input: {
+    sessions: ReceiptSessionStoreLike;
+    streamNonce: string;
+    /** Asset-B amount delivered by THIS packet (target micro-units). */
+    deliveredAmount: bigint;
+    /** The quote-tape rate applied to this packet. */
+    rate: string;
+    /** The quote-tape timestamp for {@link rate}. */
+    rateTimestamp: number;
+    /** Maker receipt secret key (32-byte secp256k1). */
+    secretKey: Uint8Array;
+}): StreamReceipt;
+
+/**
+ * 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;
+    /**
+     * Maker receipt verification key (issue #84, rfc-0039 stream receipts;
+     * rolling-swap spec §7.2): 64-char lowercase hex x-only pubkey each
+     * per-fulfill receipt's BIP-340 signature is verified against. Defaults
+     * to `swapPubkey` (the maker identity key — the swap handler's default
+     * receipt signer). Set when the maker provisioned a dedicated receipt key
+     * (`CreateSwapHandlerConfig.receiptSecretKey`, e.g. the swap#47 coupled
+     * engine's chain-B claim signer key).
+     */
+    receiptPubkey?: string;
+    /**
+     * When true, every fulfilled packet MUST carry a verifiable receipt: a
+     * receipt-less FULFILL is recorded as a `RECEIPT_MISSING` rejection and
+     * the stream halts with `abortReason: 'receipt-invalid'` (a maker that
+     * doesn't attest deliveries cannot be audited, so keep the exposure at
+     * zero). When omitted/false, receipt-less fulfills from legacy makers
+     * degrade gracefully: the claim still accumulates, `result.receipts`
+     * is simply empty. A receipt that is PRESENT but fails verification
+     * (tampered, wrong key, wrong session, non-monotone, duplicate seq) is
+     * ALWAYS a loud `RECEIPT_INVALID` rejection + halt, regardless of this
+     * flag — the packet's claim is never accumulated.
+     */
+    requireReceipts?: boolean;
+    /** 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;
+    /**
+     * Verified per-fulfill stream receipt (issue #84, rolling-swap spec §7.2).
+     * Present iff the maker emitted a receipt AND it verified (signature,
+     * session nonce, monotonicity) — an invalid receipt halts the stream
+     * before the callback ever fires for that packet.
+     */
+    receipt?: StreamReceipt;
+    /** 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;
+    /**
+     * The VERIFIED signed receipt that rode on this packet's FULFILL
+     * (issue #84, rolling-swap spec §7.2) — receipts persist wherever the
+     * claim does. Present iff the maker emitted receipts for this session.
+     */
+    receipt?: StreamReceipt;
+}
+/**
+ * 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' | 'receipt-invalid' | 'all-rejected';
+    cumulativeSource: bigint;
+    cumulativeTarget: bigint;
+    packetsSent: number;
+    packetsScheduled: number;
+    /**
+     * The verified receipt chain for this stream (issue #84, rolling-swap
+     * spec §7.2): every receipt that verified against the maker receipt key,
+     * sorted by `seq`, plus the superseding `latest`, the signed
+     * `totalDelivered`, and any `seq` holes. ALWAYS present — on abort it
+     * covers exactly what filled before the halt; against a legacy maker
+     * (no receipt support) it is simply empty. Feed to
+     * `serializeReceiptChain()` for the portable audit/dispute artifact.
+     */
+    receipts: StreamReceiptChain;
+}
+/** 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.
+ *
+ * Issue #84 (rfc-0039 stream receipts): when `streamNonce` is provided, the
+ * rumor also carries a `stream-nonce` tag — the sender-generated session
+ * identifier a receipt-capable maker echoes on every per-fulfill receipt.
+ * This is the TOON analogue of rfc-0039's Verifier→Receiver Receipt-Nonce
+ * provisioning (in-band, per stream). Legacy makers ignore the unknown tag.
+ */
+declare function buildSwapRumor(input: {
+    senderPubkey: string;
+    pair: SwapPair;
+    sourceAmount: bigint;
+    packetIndex: number;
+    totalPackets: number;
+    nonce: Uint8Array;
+    createdAt: number;
+    chainRecipient: string;
+    /** 32-char lowercase hex session nonce (issue #84 stream receipts). */
+    streamNonce?: 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).
+ *
+ * Issue #84 extension (rfc-0039 stream receipts, spec §7.2): parses the
+ * optional `receipt` object into a structurally-validated {@link StreamReceipt}.
+ * Like the tape, a PRESENT-but-malformed receipt is a loud
+ * `FULFILL_DECODE_FAILED` (a garbled proof must never be silently dropped —
+ * the sender would keep streaming while its audit artifact rots); a wholly
+ * absent receipt is legacy-maker territory and tolerated here (the
+ * `requireReceipts` policy is enforced by the caller, which has the halt
+ * machinery). Signature/monotonicity verification is NOT done here — that is
+ * `processAcceptedPacket`'s ReceiptChainTracker.
+ *
+ * @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;
+    /** Per-fulfill stream receipt (issue #84) — structurally validated, NOT yet signature-verified. */
+    receipt?: StreamReceipt;
+    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 { wrapSwapPacket as $, type AccumulatedClaim as A, BoundedReceiptSessions as B, decryptFulfillClaim as C, DEFAULT_RECEIPT_SESSIONS_CAP as D, type EncryptFulfillClaimParams as E, encodeReceiptSigningPayload as F, encryptFulfillClaim as G, isSwapControllerState as H, InMemorySwapControllerStateStore as I, JsonFileSwapControllerStateStore as J, isValidStreamNonce as K, issueSessionReceipt as L, parseStreamReceipt as M, serializeReceiptChain as N, signStreamReceipt as O, type PacketObservation as P, streamSwap as Q, type ReceiptSessionStoreLike as R, STREAM_RECEIPT_SIGNING_TAG as S, streamSwapControlled as T, type UnwrapSwapPacketFromToonParams as U, swapControllerStateKey as V, type WrapSwapPacketParams as W, unwrapSwapPacket as X, unwrapSwapPacketFromToon as Y, verifyStreamReceipt as Z, __testing as _, AdaptiveDeltaController as a, wrapSwapPacketToToon as a0, type StreamSwapClient as a1, type AdaptiveDeltaControllerConfig as b, type DecryptFulfillClaimParams as c, type EncryptFulfillClaimResult as d, type PacketProgress as e, type PacketResolution as f, type RateMonitorCallback as g, type ReceiptAddResult as h, ReceiptChainTracker as i, type ReceiptSessionState as j, STREAM_RECEIPT_VERSION as k, type StreamReceipt as l, type StreamReceiptChain as m, type StreamReceiptFields as n, type StreamSwapAdaptiveController as o, type StreamSwapController as p, type StreamSwapParams as q, type StreamSwapResult as r, SwapControllerError as s, type SwapControllerState as t, type SwapControllerStateStore as u, type UnwrapSwapPacketParams as v, type UnwrapSwapPacketResult as w, type WrapSwapPacketResult as x, type WrapSwapPacketToToonParams as y, type WrapSwapPacketToToonResult as z };