@toon-protocol/client 0.16.0 → 0.18.0

package/dist/index.d.ts

@@ -1,8 +1,11 @@
 import * as _toon_protocol_core from '@toon-protocol/core';
-import { IlpPeerInfo, IlpClient, IlpSendResult, NetworkFamilyStatus, ConnectorAdminClient, ConnectorChannelClient, OpenChannelParams, OpenChannelResult, ChannelState } from '@toon-protocol/core';
+import { IlpPeerInfo, IlpSendResult, IlpClient, SwapPair, NetworkFamilyStatus, ConnectorAdminClient, ConnectorChannelClient, OpenChannelParams, OpenChannelResult, ChannelState } from '@toon-protocol/core';
 export { UI_RENDERER_KIND, UI_TAG, UiCoordinate, buildUiCoordinate, getUiCoordinate, parseUiCoordinate, selectLatestAddressable } from '@toon-protocol/core';
 import { NostrEvent, EventTemplate } from 'nostr-tools/pure';
-import { PrivateKeyAccount } from 'viem/accounts';
+import { MinaSignerClientLike, SettlementBundle } from '@toon-protocol/sdk';
+import { AccumulatedClaim } from '@toon-protocol/sdk/swap';
+import { PrivateKeyAccount, Hex } from 'viem';
+import { PrivateKeyAccount as PrivateKeyAccount$1 } from 'viem/accounts';
 export { A2uiDecision, ConsentDecision, ConsentRequest, DispatchGuardInfo, DispatchInput, GenerateContext, GeneratedRenderer, GenerativeDecision, GenerativeFallbackOptions, GenerativeFallbackRenderer, GenerativeFallbackResult, GuardedDispatchInput, IntentClassification, KindRegistry, MIME_A2UI, MIME_MCP_APP, McpUiDecision, NativeDecision, PublishBackOptions, RenderBranch, RenderDecision, RenderTrust, RendererGenerator, RendererPin, RendererPinStore, RendererPublisher, RendererSigner, ResolvedCoordinate, SwapApproval, SwapDecision, SwapRejection, SwapRejectionReason, UiResource, VerifyRendererInput, WidgetIntent, buildConsentRequest, buildRendererEventTemplate, classifyIntent, deterministicGenerator, extractUiResource, guardedRenderDispatch, isTrustDowngrade, publishBackCoordinate, renderDeterministicHtml, renderDispatch, resolveRendererMime, resolveUiCoordinate, resolveUiRenderer, verifyRendererTrust } from './render/index.js';
 
 /** One on-chain wallet token balance. `amount` is base-unit integer, decimal. */
@@ -640,6 +643,63 @@ declare function requestBlobStorage(client: ToonClient, secretKey: Uint8Array, p
  */
 declare function extractArweaveTxId(base64Data: string): string;
 
+/**
+ * Shared sender-side plumbing for sender-chosen execution conditions
+ * (toon-client#350; contract: connector `docs/local-delivery-fulfillment-contract.md`,
+ * connector#309; spec: toon-meta `docs/rolling-swap.md` §3).
+ *
+ * Both ILP transports (HTTP `POST /ilp` and BTP) take the SAME extended send
+ * params and map FULFILL/REJECT responses through the SAME verifier so the
+ * two paths cannot drift:
+ *
+ *   - absent/all-zero `executionCondition` → legacy class: today's behavior,
+ *     byte-for-byte (zero condition on the wire, no FULFILL verification);
+ *   - non-zero `executionCondition` → sender-chosen: the condition goes on
+ *     the PREPARE verbatim and the FULFILL's 32-byte fulfillment MUST hash
+ *     back to it — a missing/malformed/mismatching preimage is surfaced as a
+ *     FAILED result (never a silent accept, never retried).
+ */
+
+/**
+ * Send parameters accepted by both ILP transports. Extends the
+ * `@toon-protocol/core` `IlpClient` param shape with the sender-chosen
+ * condition and an explicit expiry — plain `IlpClient` callers keep working
+ * unchanged (both extras are optional; omitting them is the legacy path).
+ */
+interface IlpSendParams {
+    destination: string;
+    amount: string;
+    /** Base64 ILP `data` payload. */
+    data: string;
+    /** Transport timeout in ms; also the default expiry window. */
+    timeout?: number;
+    /**
+     * Sender-chosen 32-byte execution condition `C = sha256(P)` (spec R2).
+     * Absent or all-zero = legacy unverified packet (default — ordinary
+     * publish/upload writes MUST keep this default).
+     */
+    executionCondition?: Uint8Array;
+    /**
+     * Explicit PREPARE `expiresAt` (spec R7). Defaults to `now + timeout`,
+     * preserving pre-#350 behavior. Accepts a `Date` or an ISO 8601 string —
+     * `@toon-protocol/core` ≥2.1.0's `IlpClient` passes the string form.
+     */
+    expiresAt?: Date | string;
+}
+/**
+ * `IlpSendResult` plus the FULFILL preimage when a sender-chosen condition
+ * was verified. Only populated on the sender-chosen path so legacy result
+ * objects stay byte-identical.
+ */
+interface IlpSendResultWithFulfillment extends IlpSendResult {
+    /** Base64 32-byte fulfillment preimage (verified: sha256 == condition). */
+    fulfillment?: string;
+}
+/** ILP code used for a client-side fulfillment-verification failure. */
+declare const FULFILLMENT_MISMATCH_CODE = "F99";
+/** Message for a client-side fulfillment-verification failure. */
+declare const FULFILLMENT_MISMATCH_MESSAGE: string;
+
 interface BtpRuntimeClientConfig {
     btpUrl: string;
     peerId: string;
@@ -676,23 +736,22 @@ declare class BtpRuntimeClient implements IlpClient {
     /**
      * Sends an ILP packet via BTP with auto-reconnect on connection errors.
      * Satisfies IlpClient interface.
+     *
+     * `params` may carry a sender-chosen `executionCondition` and an explicit
+     * `expiresAt` (toon-client#350); omitting both is the legacy zero-condition
+     * path, unchanged. With a non-zero condition the FULFILL preimage is
+     * verified (`sha256(fulfillment) == condition`) and a mismatch is surfaced
+     * as a failed result — see `mapIlpResponse`.
      */
-    sendIlpPacket(params: {
-        destination: string;
-        amount: string;
-        data: string;
-        timeout?: number;
-    }): Promise<IlpSendResult>;
+    sendIlpPacket(params: IlpSendParams): Promise<IlpSendResult>;
     /**
      * Sends a balance proof claim via BTP protocol data, then sends an ILP packet.
      * Auto-reconnects on connection errors.
+     *
+     * Sender-chosen `executionCondition` / explicit `expiresAt` semantics are
+     * identical to {@link sendIlpPacket}.
      */
-    sendIlpPacketWithClaim(params: {
-        destination: string;
-        amount: string;
-        data: string;
-        timeout?: number;
-    }, claim: Record<string, unknown>): Promise<IlpSendResult>;
+    sendIlpPacketWithClaim(params: IlpSendParams, claim: Record<string, unknown>): Promise<IlpSendResult>;
     /**
      * Send a standalone `payment-channel-claim` BTP MESSAGE (no ILP packet
      * attached). The connector's ClaimReceiver consumes this fire-and-forget
@@ -701,6 +760,14 @@ declare class BtpRuntimeClient implements IlpClient {
      */
     sendClaimMessage(claim: Record<string, unknown>): Promise<void>;
     private _sendClaimMessageOnce;
+    /**
+     * Build the ILP PREPARE for a send, applying the sender-chosen condition /
+     * explicit expiry when provided (toon-client#350) and validating that a
+     * non-zero condition is exactly 32 bytes (the OER serializer would
+     * otherwise silently zero-fill it, downgrading the packet to the legacy
+     * unverified class).
+     */
+    private buildPrepare;
     /**
      * Single-attempt ILP packet send. Reconnects if not connected.
      */
@@ -792,25 +859,24 @@ declare class HttpIlpClient implements IlpClient {
      * Send an ILP PREPARE via `POST /ilp` WITHOUT a claim. The connector accepts
      * this only on free/zero-amount routes; paid writes must use
      * {@link sendIlpPacketWithClaim}. Satisfies the IlpClient interface.
+     *
+     * `params` may carry a sender-chosen `executionCondition` and an explicit
+     * `expiresAt` (toon-client#350); omitting both is the legacy zero-condition
+     * path, unchanged. With a non-zero condition the FULFILL preimage is
+     * verified (`sha256(fulfillment) == condition`) and a mismatch is surfaced
+     * as a failed result — see {@link mapIlpResponse}.
      */
-    sendIlpPacket(params: {
-        destination: string;
-        amount: string;
-        data: string;
-        timeout?: number;
-    }): Promise<IlpSendResult>;
+    sendIlpPacket(params: IlpSendParams): Promise<IlpSendResult>;
     /**
      * Send an ILP PREPARE via `POST /ilp` with the payment-channel claim attached
      * as the `ILP-Payment-Channel-Claim` header. `claim` is the SAME JSON object
      * the BTP path attaches as the `payment-channel-claim` protocolData entry —
      * we base64(JSON.stringify(claim)) it, byte-for-byte identical to BTP.
+     *
+     * Sender-chosen `executionCondition` / explicit `expiresAt` semantics are
+     * identical to {@link sendIlpPacket}.
      */
-    sendIlpPacketWithClaim(params: {
-        destination: string;
-        amount: string;
-        data: string;
-        timeout?: number;
-    }, claim: unknown): Promise<IlpSendResult>;
+    sendIlpPacketWithClaim(params: IlpSendParams, claim: unknown): Promise<IlpSendResult>;
     /**
      * Upgrade to a duplex BTP session over the SAME endpoint.
      *
@@ -838,6 +904,10 @@ declare class HttpIlpClient implements IlpClient {
      * Map a `200 OK` body (OER FULFILL/REJECT) to an IlpSendResult; map a non-2xx
      * to a transport error. Per the wire contract, ILP-level rejects arrive as a
      * 200 + REJECT body — only HTTP non-2xx means a transport-layer failure.
+     *
+     * When `sentCondition` is non-zero the FULFILL preimage is verified against
+     * it; a mismatch yields `accepted: false` (shared `mapIlpResponse` logic,
+     * identical to the BTP path).
      */
     private mapResponse;
     private mapTransportError;
@@ -1051,6 +1121,173 @@ declare function serializeHttpRequest(req: {
  */
 declare function parseHttpResponse(bytes: Uint8Array): Response;
 
+/**
+ * The persisted receive-side watermark for one swap target channel: the
+ * HIGHEST-NONCE verified chain-B claim per `(chain, channelId)` (toon-client
+ * issue #352, rolling-swap spec toon-meta docs/rolling-swap.md §3.2/§9).
+ *
+ * Claims are cumulative balance proofs — a higher-nonce claim supersedes every
+ * earlier one — so persisting only the winner per channel is lossless for
+ * settlement: `buildSettlementTx` redeems exactly this claim. Superseded claims
+ * are informational and dropped.
+ */
+interface ReceivedClaimEntry {
+    /** Target chain the claim settles on (`pair.to.chain`, e.g. `evm:base:8453`). */
+    chain: string;
+    /** Payment-channel id on the target chain (0x-hex for EVM, base58 otherwise). */
+    channelId: string;
+    /** Balance-proof nonce (strictly increasing per channel). */
+    nonce: bigint;
+    /** Cumulative transferred amount, target micro-units. */
+    cumulativeAmount: bigint;
+    /** Recipient address the claim pays (the sender's `chainRecipient`). */
+    recipient: string;
+    /** Swap peer's on-chain signer address the signature verified against. */
+    swapSignerAddress: string;
+    /** The verified signed claim bytes (chain-specific encoding). */
+    claimBytes: Uint8Array;
+    /** Optional swap-side claim id. */
+    claimId?: string;
+    /** The SwapPair the claim was priced against (settlement-time routing). */
+    pair: SwapPair;
+    /** Unix ms the winning claim was accepted off the wire. */
+    receivedAt: number;
+    /** Unix ms this entry was last advanced. */
+    updatedAt: number;
+    /** Unix ms of the last successful on-chain settlement submission. */
+    settledAt?: number;
+    /** Watermark nonce redeemed by that settlement (claims ≤ this are settled). */
+    settledNonce?: bigint;
+    /** Tx hash of the last settlement submission. */
+    settleTxHash?: string;
+}
+/**
+ * Persistence interface for received (chain-B) swap claims. Mirrors
+ * {@link ChannelStore}'s sync surface; keyed by `(chain, channelId)`.
+ */
+interface ReceivedClaimStore {
+    save(entry: ReceivedClaimEntry): void;
+    load(chain: string, channelId: string): ReceivedClaimEntry | undefined;
+    list(): ReceivedClaimEntry[];
+    delete(chain: string, channelId: string): void;
+}
+/**
+ * JSON file-backed {@link ReceivedClaimStore}. Synchronous I/O to match the
+ * `JsonFileChannelStore` pattern (`ChannelStore.ts`); the parent directory is
+ * created on first save so a fresh daemon home works out of the box.
+ */
+declare class JsonFileReceivedClaimStore implements ReceivedClaimStore {
+    private readonly filePath;
+    constructor(filePath: string);
+    save(entry: ReceivedClaimEntry): void;
+    load(chain: string, channelId: string): ReceivedClaimEntry | undefined;
+    list(): ReceivedClaimEntry[];
+    delete(chain: string, channelId: string): void;
+    private readFile;
+    private writeFile;
+}
+/**
+ * In-memory {@link ReceivedClaimStore} for tests and path-less configs. NOT
+ * restart-safe — a daemon should always be given a `JsonFileReceivedClaimStore`.
+ */
+declare class InMemoryReceivedClaimStore implements ReceivedClaimStore {
+    private readonly entries;
+    save(entry: ReceivedClaimEntry): void;
+    load(chain: string, channelId: string): ReceivedClaimEntry | undefined;
+    list(): ReceivedClaimEntry[];
+    delete(chain: string, channelId: string): void;
+}
+
+/**
+ * Receive-side swap settlement (toon-client#352): turn persisted
+ * {@link ReceivedClaimEntry} watermarks into on-chain settlement submissions.
+ *
+ * Building is pure and chain-agnostic — `buildSettlementTx` (sdk) re-verifies
+ * the stored claim's signature and produces one {@link SettlementBundle} per
+ * `(chain, channelId)` with the FINAL watermark, so N received advances net to
+ * one on-chain close per channel (spec §9). Submission is chain-gated:
+ *
+ * - **EVM** — implemented here ({@link submitEvmSettlement}): the bundle's
+ *   unsigned RLP is decoded for `to`/calldata, gas is estimated against the
+ *   configured RPC, and the tx is signed by the client's EVM account (the
+ *   claim recipient) and broadcast. Real submission is therefore env-gated on
+ *   `chainRpcUrls[chain]` — absent RPC config yields a built-not-submitted
+ *   result, never a throw.
+ * - **Solana** — the bundle carries a serialized Message; a submission path is
+ *   not wired yet (follow-up under toon-meta#145).
+ * - **Mina** — receive-side redemption needs a co-sign (`claimFromChannel`
+ *   takes `signatureA` AND `signatureB`) plus o1js proof generation; the
+ *   client has no receive-side co-sign path. Explicitly out of scope for #352
+ *   (documented gap; follow-up: toon-client#357).
+ */
+
+/** One per-channel settlement build outcome (result-shaped, never thrown). */
+interface SwapSettlementBuild {
+    chain: string;
+    channelId: string;
+    /** The bundle, when the claim verified and the chain config sufficed. */
+    bundle?: SettlementBundle;
+    /** Why no bundle was produced (missing config, failed re-verification, …). */
+    error?: {
+        code: string;
+        message: string;
+    };
+}
+interface BuildSwapSettlementsParams {
+    /** Persisted watermarks to settle (typically `store.list()`, filtered). */
+    entries: readonly ReceivedClaimEntry[];
+    /**
+     * Per-chain settlement contract: EVM TokenNetwork address / Solana
+     * programId, keyed by the FULL chain key (e.g. `evm:base:8453`). Matches the
+     * daemon config's `tokenNetworks` map.
+     */
+    tokenNetworks?: Record<string, string>;
+    /** Pre-loaded `mina-signer` client for `mina:*` re-verification. */
+    minaSignerClient?: MinaSignerClientLike;
+}
+/** Rebuild the sdk `AccumulatedClaim` shape from a persisted entry. */
+declare function entryToAccumulatedClaim(entry: ReceivedClaimEntry): AccumulatedClaim;
+/**
+ * Parse the numeric chain id off an `evm:{network}:{chainId}` / `evm:{chainId}`
+ * chain key. Returns undefined for malformed keys (reported result-shaped).
+ */
+declare function parseEvmChainId(chain: string): number | undefined;
+/**
+ * Build one settlement bundle per persisted entry via the sdk's
+ * `buildSettlementTx` (signature re-verified at settle time — a tampered
+ * store never reaches a submission). Per-entry isolation: one bad channel
+ * cannot block the others.
+ */
+declare function buildSwapSettlements(params: BuildSwapSettlementsParams): SwapSettlementBuild[];
+interface SubmitEvmSettlementParams {
+    /** JSON-RPC endpoint of the bundle's chain (`chainRpcUrls[bundle.chain]`). */
+    rpcUrl: string;
+    /** The claim recipient's EVM account (signs + pays gas for the redeem). */
+    account: PrivateKeyAccount;
+    /** Receipt wait bound, ms (default 60_000). */
+    timeoutMs?: number;
+}
+interface SubmitEvmSettlementResult {
+    txHash: string;
+    /** Receipt status when the wait succeeded within the bound. */
+    status?: 'success' | 'reverted';
+}
+/**
+ * Decode the unsigned legacy-RLP tx a settlement bundle carries.
+ * Layout (EIP-155 unsigned): [nonce, gasPrice, gasLimit, to, value, data, chainId, 0, 0].
+ */
+declare function decodeEvmSettlementTx(bundle: SettlementBundle): {
+    to: Hex;
+    data: Hex;
+    chainId: number;
+};
+/**
+ * Sign + broadcast an EVM settlement bundle from the recipient's account.
+ * Gas/nonce are read from the RPC; the tx is signed locally (non-custodial)
+ * and sent as a raw transaction, then awaited to a receipt (bounded).
+ */
+declare function submitEvmSettlement(bundle: SettlementBundle, params: SubmitEvmSettlementParams): Promise<SubmitEvmSettlementResult>;
+
 /**
  * ToonClient - High-level client for interacting with TOON network.
  *
@@ -1254,6 +1491,14 @@ declare class ToonClient {
      *       matching `destination`,
      *   (c) neither -> throw MISSING_CLAIM.
      *
+     * A caller may supply a sender-chosen 32-byte `executionCondition`
+     * (`C = sha256(P)`, one fresh preimage per packet — toon-client#350,
+     * rolling-swap spec §3 R1/R2) and an explicit `expiresAt` (R7). Both are
+     * set on the wire by either transport (HTTP `POST /ilp` and BTP), and on
+     * FULFILL the transport verifies `sha256(fulfillment) == condition` —
+     * a mismatch comes back as `accepted: false` (code F99), never a silent
+     * accept. Omitting them keeps today's zero-condition legacy packet.
+     *
      * @throws {ToonClientError} INVALID_STATE / NO_ILP_TRANSPORT / MISSING_CLAIM
      */
     sendSwapPacket(params: {
@@ -1262,6 +1507,10 @@ declare class ToonClient {
         toonData: Uint8Array;
         timeout?: number;
         claim?: SignedBalanceProof;
+        /** Sender-chosen 32-byte execution condition; absent/zero = legacy. */
+        executionCondition?: Uint8Array;
+        /** Explicit ILP expiry; defaults to `now + timeout` in the transport. */
+        expiresAt?: Date;
     }): Promise<IlpSendResult>;
     /**
      * Build a BTP claim message from a pre-signed balance proof using the
@@ -1393,6 +1642,19 @@ declare class ToonClient {
         channelId: string;
         txHash?: string;
     }>;
+    /**
+     * Submit a receive-side swap settlement bundle on-chain (toon-client#352).
+     * The bundle comes from the sdk's `buildSettlementTx` over persisted,
+     * verified chain-B claims (`buildSwapSettlements`); this signs it with the
+     * client's EVM account (the claim recipient) and broadcasts it.
+     *
+     * Env-gated seam: EVM only, and only when `chainRpcUrls[bundle.chain]` is
+     * configured — otherwise this throws a clear config error and callers
+     * surface a built-not-submitted result. Solana submission and the Mina
+     * receive-side co-sign path are explicit follow-ups (see
+     * swap/settle-received-claims.ts module doc).
+     */
+    settleSwapBundle(bundle: SettlementBundle): Promise<SubmitEvmSettlementResult>;
     /** Where a tracked channel sits in the withdraw journey. */
     getChannelCloseState(channelId: string): 'open' | 'closing' | 'settleable' | 'settled';
     getSettleableAt(channelId: string): bigint | undefined;
@@ -2075,7 +2337,7 @@ declare class EvmSigner {
     /** ChainSigner identifier — EVM address */
     get signerIdentifier(): string;
     /** Viem PrivateKeyAccount — usable with walletClient for on-chain transactions */
-    get account(): PrivateKeyAccount;
+    get account(): PrivateKeyAccount$1;
     /**
      * Signs a balance proof using EIP-712 typed data.
      *
@@ -2674,6 +2936,105 @@ declare class ChannelManager {
  */
 declare function readMinaDepositTotal(graphqlUrl: string, zkAppAddress: string, fetchImpl?: typeof fetch): Promise<bigint>;
 
+/**
+ * Receive-side swap-claim ingestion + verification (toon-client#352, part of
+ * the rolling-swap epic toon-meta#145; spec: toon-meta docs/rolling-swap.md
+ * §3.2/§9 dependency 1).
+ *
+ * The deployed client used to accept swapped-in chain-B claims blind: no
+ * signature check, no watermark, no persistence — `buildSettlementTx` /
+ * `verifyAccumulatedClaim` had zero call sites in this repo. This module is
+ * the missing pipeline: every accumulated claim harvested from a swap stream
+ * is VERIFIED at receipt time and, only if it passes, persisted as the
+ * highest-nonce watermark for its `(chain, channelId)` in a
+ * {@link ReceivedClaimStore}. A claim that fails verification is NEVER counted
+ * as value received — failures are loud and result-shaped, not thrown.
+ *
+ * Verification order per claim (cheapest first, every check fail-closed):
+ *   1. settlement metadata completeness — a claim missing any of channelId /
+ *      nonce / cumulativeAmount / recipient / swapSignerAddress cannot be
+ *      settled (`MISSING_SETTLEMENT_METADATA` later) and is bucketed `legacy`
+ *      (the pre-rename-peer path, #349) rather than rejected: the existing
+ *      loud swap-time warning stays the surface for those.
+ *   2. chain consistency — the claim must settle on the session's target chain.
+ *   3. recipient — must equal the session `chainRecipient` (EVM
+ *      case-insensitive), the anti-substitution check.
+ *   4. advertised signer — when the caller supplies the maker's advertised
+ *      `swapSignerAddress` (kind:10032 discovery / operator config), the
+ *      claim's self-reported signer must match (`SWAP_SIGNER_MISMATCH`,
+ *      sdk 2.x vocabulary).
+ *   5. signature — `verifyAccumulatedClaim` (sdk) against the expected signer:
+ *      the advertised address when given, else the claim's self-reported one
+ *      (which then still proves the claim is internally consistent and pins
+ *      the address the settlement tx will verify against on-chain).
+ *   6. signer pinning — a claim may not silently rotate the signer of an
+ *      already-persisted watermark for the same channel.
+ *   7. nonce/cumulative monotonicity vs the locally persisted watermark —
+ *      strictly increasing nonce AND cumulative; the cumulative advance must
+ *      cover this packet's `targetAmount` (an under-delivering advance means
+ *      the maker short-paid the packet).
+ */
+
+/** Why a claim was rejected at receipt time. Codes are stable API. */
+type ReceivedClaimRejectionCode = 'CHAIN_MISMATCH' | 'RECIPIENT_MISMATCH' | 'SWAP_SIGNER_MISMATCH' | 'SIGNER_MISMATCH' | 'SIGNATURE_INVALID' | 'MINA_VERIFICATION_UNSUPPORTED' | 'UNSUPPORTED_CHAIN' | 'NON_MONOTONIC_NONCE' | 'NON_MONOTONIC_CUMULATIVE' | 'CUMULATIVE_SHORTFALL' | 'MALFORMED_METADATA';
+interface ReceivedClaimRejection {
+    claim: AccumulatedClaim;
+    code: ReceivedClaimRejectionCode;
+    message: string;
+}
+interface VerifiedReceivedClaim {
+    claim: AccumulatedClaim;
+    /** How far this claim advanced the persisted cumulative watermark. */
+    watermarkAdvance: bigint;
+}
+interface IngestReceivedClaimsParams {
+    /** Accumulated claims off a swap stream (`streamSwap().claims`), in order. */
+    claims: readonly AccumulatedClaim[];
+    /** The session's target chain (`pair.to.chain` of the requested swap). */
+    expectedChain: string;
+    /** The session's payout address on `expectedChain`. */
+    chainRecipient: string;
+    /**
+     * The maker's ADVERTISED on-chain signer address for `expectedChain`
+     * (kind:10032 discovery or operator-supplied). When set, a claim whose
+     * self-reported `swapSignerAddress` differs is rejected with
+     * `SWAP_SIGNER_MISMATCH` and the signature is verified against THIS address,
+     * never the claim's own.
+     */
+    expectedSignerAddress?: string;
+    /** Durable watermark store; verified claims are persisted here. */
+    store: ReceivedClaimStore;
+    /** Pre-loaded `mina-signer` client — required to verify `mina:*` claims. */
+    minaSignerClient?: MinaSignerClientLike;
+    /** Clock seam for tests. */
+    now?: () => number;
+}
+interface IngestReceivedClaimsResult {
+    /** Claims that passed every check and advanced a persisted watermark. */
+    verified: VerifiedReceivedClaim[];
+    /** Claims that failed verification. NEVER counted as value received. */
+    rejected: ReceivedClaimRejection[];
+    /**
+     * Claims missing settlement metadata (pre-rename / legacy swap peer, #349).
+     * Not verified, not persisted, surfaced through the existing swap-time
+     * warning — behavior for legacy no-metadata swaps is unchanged.
+     */
+    legacy: AccumulatedClaim[];
+    /** Total watermark advance across verified claims (target micro-units). */
+    valueReceived: bigint;
+}
+/** True when the claim carries every settlement-context field. */
+declare function hasSettlementMetadata(claim: AccumulatedClaim): claim is AccumulatedClaim & Required<Pick<AccumulatedClaim, 'channelId' | 'nonce' | 'cumulativeAmount' | 'recipient' | 'swapSignerAddress'>>;
+/**
+ * Verify a batch of received chain-B claims and persist the winning watermark
+ * per `(chain, channelId)`. See the module doc for the check ladder.
+ *
+ * Result-shaped: never throws on a bad claim — it lands in `rejected` with a
+ * stable code, and later claims are still processed (a channel's watermark
+ * only advances through claims that verified).
+ */
+declare function ingestReceivedClaims(params: IngestReceivedClaimsParams): IngestReceivedClaimsResult;
+
 /**
  * Configuration options for retry behavior with exponential backoff.
  */
@@ -2809,6 +3170,56 @@ declare function parseFulfillHttpBytes(bytes: Uint8Array): ParsedFulfillHttp;
  */
 declare function parseFulfillHttp(base64Data: string): ParsedFulfillHttp;
 
+/**
+ * Sender-chosen ILP execution conditions (toon-client#350, rolling-swap
+ * prerequisite — toon-meta#145 §3 R1/R2).
+ *
+ * Contract (normative: connector `docs/local-delivery-fulfillment-contract.md`,
+ * connector#309):
+ *   - An ABSENT or ALL-ZERO (32×0x00) `executionCondition` is the LEGACY
+ *     class: no hashlock, no verification — today's publish/upload writes.
+ *   - Any NON-ZERO condition is SENDER-CHOSEN: the sender mints a fresh
+ *     random 32-byte preimage `P` per packet, sets `C = sha256(P)` on the
+ *     PREPARE, and on FULFILL MUST verify that the returned fulfillment
+ *     hashes back to `C` — a missing/malformed/mismatching fulfillment is a
+ *     hard failure (the packet is counted failed, never silently accepted).
+ *
+ * Isomorphic: @noble/hashes only (no Buffer, no node:crypto).
+ */
+/** Exact byte length of an ILP execution condition / fulfillment preimage. */
+declare const CONDITION_LENGTH = 32;
+/** A freshly minted per-packet hashlock: `condition = sha256(preimage)`. */
+interface ExecutionConditionPair {
+    /** Random 32-byte preimage `P` — reveal is the commit act; never reuse. */
+    preimage: Uint8Array;
+    /** `C = sha256(P)` — goes on the PREPARE's `executionCondition`. */
+    condition: Uint8Array;
+}
+/**
+ * Mint a fresh random 32-byte preimage and its sha256 condition (spec R1).
+ * Mint one PER PACKET: a reused preimage lets any observer of packet *i*
+ * fulfill packet *i+1* without the sender's consent.
+ */
+declare function mintExecutionCondition(): ExecutionConditionPair;
+/**
+ * True when `condition` selects the LEGACY (unverified) class: absent or
+ * all-zero. The OER wire treats absent and 32×0x00 identically.
+ */
+declare function isZeroCondition(condition: Uint8Array | undefined): boolean;
+/**
+ * Validate a caller-supplied execution condition before it goes on the wire.
+ * @throws {Error} When the condition is not exactly 32 bytes — the OER
+ *   serializer would otherwise silently zero-fill it, downgrading a
+ *   sender-chosen packet to the legacy unverified class.
+ */
+declare function assertValidCondition(condition: Uint8Array): void;
+/**
+ * True iff `fulfillment` is exactly 32 bytes and `sha256(fulfillment)`
+ * equals `condition` — the sender-side FULFILL check (spec R6's mirror).
+ * Fail-closed: an undefined/short/long fulfillment never matches.
+ */
+declare function fulfillmentMatchesCondition(fulfillment: Uint8Array | undefined, condition: Uint8Array): boolean;
+
 /**
  * Settlement info produced by buildSettlementInfo().
  * Extends the core SettlementConfig shape with ilpAddress for client use.
@@ -3326,4 +3737,4 @@ declare function loadKeystore(path: string, password: string): string;
  */
 declare function writeKeystoreFile(path: string, keystore: EncryptedKeystore): void;
 
-export { type BackupPayload, type BalanceProofParams, BtpRuntimeClient, type BtpRuntimeClientConfig, type ChainMetadata, type ChainSigner, ChannelFundingError, ChannelManager, type ClaimMessage, type ClaimResolver, ConnectorError, type DiscoveredIlpPeer, type EVMClaimMessage, type EncryptedKeystore, EvmSigner, type FaucetChain, type FundWalletOptions, type FundWalletResult, type H402FetchOptions, Http402Client, type Http402ClientConfig, HttpConnectorAdmin, type HttpConnectorAdminConfig, HttpIlpClient, type HttpIlpClientConfig, type HttpIlpClientFactory, HttpRuntimeClient, type HttpRuntimeClientConfig, ILP_CLAIM_HEADER, ILP_CLAIM_WRAPPED_HEADER, ILP_PEER_ID_HEADER, type IlpTransportChoice, KeyManager, type KeyManagerConfig, type MinaClaimMessage, type MinaDepositReader, MinaSigner, type MinaSignerOptions, NetworkError, OnChainChannelClient, type OnChainChannelClientConfig, type ParsedFulfillHttp, type ParsedX402Challenge, type PasskeyInfo, type PublishEventResult, type RequestBlobStorageParams, type RequestBlobStorageResult, type RetryOptions, type SelectIlpTransportOptions, type SignedBalanceProof, type SolanaChannelClientOptions, type SolanaClaimMessage, SolanaSigner, type ToonChannelAccept, ToonClient, type ToonClientConfig, ToonClientError, type ToonIdentity, type ToonSigners, type ToonStartResult, ValidationError, type VaultData, type WalletBalance, type WalletBalanceSources, type WalletChainBalances, type WalletTokenAmount, applyDefaults, applyNetworkPresets, buildBackupEvent, buildBackupFilter, buildSettlementInfo, buildStoreWriteEnvelope, decryptMnemonic, defaultFaucetTimeout, deriveFromNsec, deriveFullIdentity, deriveNostrKeyFromMnemonic, encryptMnemonic, extractArweaveTxId, fundWallet, generateKeystore, generateMnemonic, generateRandomIdentity, getNetworkStatus, httpEndpointToBtpUrl, importKeystore, isInsufficientGasError, isPrfSupported, loadKeystore, parseBackupPayload, parseFulfillHttp, parseFulfillHttpBytes, parseHttpResponse, parseX402Body, parseX402Challenge, proxyIlpEndpoint, readDiscoveredIlpPeer, readEvmNativeBalance, readEvmTokenBalance, readMinaBalance, readMinaDepositTotal, readSolanaNativeBalance, readSolanaTokenBalance, readWalletBalances, requestBlobStorage, selectIlpTransport, serializeHttpRequest, validateConfig, validateMnemonic, withRetry, writeKeystoreFile };
+export { type BackupPayload, type BalanceProofParams, BtpRuntimeClient, type BtpRuntimeClientConfig, type BuildSwapSettlementsParams, CONDITION_LENGTH, type ChainMetadata, type ChainSigner, ChannelFundingError, ChannelManager, type ClaimMessage, type ClaimResolver, ConnectorError, type DiscoveredIlpPeer, type EVMClaimMessage, type EncryptedKeystore, EvmSigner, type ExecutionConditionPair, FULFILLMENT_MISMATCH_CODE, FULFILLMENT_MISMATCH_MESSAGE, type FaucetChain, type FundWalletOptions, type FundWalletResult, type H402FetchOptions, Http402Client, type Http402ClientConfig, HttpConnectorAdmin, type HttpConnectorAdminConfig, HttpIlpClient, type HttpIlpClientConfig, type HttpIlpClientFactory, HttpRuntimeClient, type HttpRuntimeClientConfig, ILP_CLAIM_HEADER, ILP_CLAIM_WRAPPED_HEADER, ILP_PEER_ID_HEADER, type IlpSendParams, type IlpSendResultWithFulfillment, type IlpTransportChoice, InMemoryReceivedClaimStore, type IngestReceivedClaimsParams, type IngestReceivedClaimsResult, JsonFileReceivedClaimStore, KeyManager, type KeyManagerConfig, type MinaClaimMessage, type MinaDepositReader, MinaSigner, type MinaSignerOptions, NetworkError, OnChainChannelClient, type OnChainChannelClientConfig, type ParsedFulfillHttp, type ParsedX402Challenge, type PasskeyInfo, type PublishEventResult, type ReceivedClaimEntry, type ReceivedClaimRejection, type ReceivedClaimRejectionCode, type ReceivedClaimStore, type RequestBlobStorageParams, type RequestBlobStorageResult, type RetryOptions, type SelectIlpTransportOptions, type SignedBalanceProof, type SolanaChannelClientOptions, type SolanaClaimMessage, SolanaSigner, type SubmitEvmSettlementParams, type SubmitEvmSettlementResult, type SwapSettlementBuild, type ToonChannelAccept, ToonClient, type ToonClientConfig, ToonClientError, type ToonIdentity, type ToonSigners, type ToonStartResult, ValidationError, type VaultData, type VerifiedReceivedClaim, type WalletBalance, type WalletBalanceSources, type WalletChainBalances, type WalletTokenAmount, applyDefaults, applyNetworkPresets, assertValidCondition, buildBackupEvent, buildBackupFilter, buildSettlementInfo, buildStoreWriteEnvelope, buildSwapSettlements, decodeEvmSettlementTx, decryptMnemonic, defaultFaucetTimeout, deriveFromNsec, deriveFullIdentity, deriveNostrKeyFromMnemonic, encryptMnemonic, entryToAccumulatedClaim, extractArweaveTxId, fulfillmentMatchesCondition, fundWallet, generateKeystore, generateMnemonic, generateRandomIdentity, getNetworkStatus, hasSettlementMetadata, httpEndpointToBtpUrl, importKeystore, ingestReceivedClaims, isInsufficientGasError, isPrfSupported, isZeroCondition, loadKeystore, mintExecutionCondition, parseBackupPayload, parseEvmChainId, parseFulfillHttp, parseFulfillHttpBytes, parseHttpResponse, parseX402Body, parseX402Challenge, proxyIlpEndpoint, readDiscoveredIlpPeer, readEvmNativeBalance, readEvmTokenBalance, readMinaBalance, readMinaDepositTotal, readSolanaNativeBalance, readSolanaTokenBalance, readWalletBalances, requestBlobStorage, selectIlpTransport, serializeHttpRequest, submitEvmSettlement, validateConfig, validateMnemonic, withRetry, writeKeystoreFile };