@toon-protocol/client 0.16.0 → 0.17.0

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 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, 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';
@@ -640,6 +640,62 @@ 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.
+     */
+    expiresAt?: Date;
+}
+/**
+ * `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 +732,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 +756,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 +855,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 +900,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;
@@ -1254,6 +1320,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 +1336,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
@@ -2809,6 +2887,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 +3454,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, 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, 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, assertValidCondition, buildBackupEvent, buildBackupFilter, buildSettlementInfo, buildStoreWriteEnvelope, decryptMnemonic, defaultFaucetTimeout, deriveFromNsec, deriveFullIdentity, deriveNostrKeyFromMnemonic, encryptMnemonic, extractArweaveTxId, fulfillmentMatchesCondition, fundWallet, generateKeystore, generateMnemonic, generateRandomIdentity, getNetworkStatus, httpEndpointToBtpUrl, importKeystore, isInsufficientGasError, isPrfSupported, isZeroCondition, loadKeystore, mintExecutionCondition, parseBackupPayload, parseFulfillHttp, parseFulfillHttpBytes, parseHttpResponse, parseX402Body, parseX402Challenge, proxyIlpEndpoint, readDiscoveredIlpPeer, readEvmNativeBalance, readEvmTokenBalance, readMinaBalance, readMinaDepositTotal, readSolanaNativeBalance, readSolanaTokenBalance, readWalletBalances, requestBlobStorage, selectIlpTransport, serializeHttpRequest, validateConfig, validateMnemonic, withRetry, writeKeystoreFile };

package/dist/index.js

@@ -894,9 +894,13 @@ function deserializeIlpPacket(buf) {
 }
 function deserializeIlpFulfill(buf) {
   let offset = 1;
+  if (buf.length < offset + 32) {
+    throw new Error("Buffer underflow reading FULFILL fulfillment");
+  }
+  const fulfillment = buf.slice(offset, offset + 32);
   offset += 32;
   const { value: data } = decodeVarOctetString(buf, offset);
-  return { type: ILPPacketType.FULFILL, data };
+  return { type: ILPPacketType.FULFILL, fulfillment, data };
 }
 function deserializeIlpReject(buf) {
   let offset = 1;
@@ -1207,8 +1211,10 @@ var IsomorphicBtpClient = class {
             this.pendingRequests.delete(id);
             if (json["type"] === "FULFILL") {
               const responseData = json["data"] ? this.base64ToUint8Array(json["data"]) : new Uint8Array(0);
+              const fulfillment = json["fulfillment"] ? this.base64ToUint8Array(json["fulfillment"]) : new Uint8Array(32);
               pending.resolve({
                 type: ILPPacketType.FULFILL,
+                fulfillment,
                 data: responseData
               });
             } else {
@@ -1269,6 +1275,70 @@ var IsomorphicBtpClient = class {
   }
 };
 
+// src/utils/condition.ts
+import { sha256 } from "@noble/hashes/sha2.js";
+import { randomBytes } from "@noble/hashes/utils.js";
+var CONDITION_LENGTH = 32;
+function mintExecutionCondition() {
+  const preimage = randomBytes(CONDITION_LENGTH);
+  return { preimage, condition: sha256(preimage) };
+}
+function isZeroCondition(condition) {
+  if (condition === void 0) return true;
+  for (const byte of condition) {
+    if (byte !== 0) return false;
+  }
+  return true;
+}
+function assertValidCondition(condition) {
+  if (condition.length !== CONDITION_LENGTH) {
+    throw new Error(
+      `executionCondition must be exactly ${CONDITION_LENGTH} bytes, got ${condition.length}`
+    );
+  }
+}
+function fulfillmentMatchesCondition(fulfillment, condition) {
+  if (fulfillment === void 0 || fulfillment.length !== CONDITION_LENGTH) {
+    return false;
+  }
+  const digest = sha256(fulfillment);
+  for (let i = 0; i < CONDITION_LENGTH; i++) {
+    if (digest[i] !== condition[i]) return false;
+  }
+  return true;
+}
+
+// src/adapters/ilp-send.ts
+var FULFILLMENT_MISMATCH_CODE = "F99";
+var FULFILLMENT_MISMATCH_MESSAGE = "FULFILL fulfillment does not match execution condition (sha256(fulfillment) != executionCondition) \u2014 packet counted failed";
+function mapIlpResponse(packet, sentCondition) {
+  if (packet.type === ILPPacketType.FULFILL) {
+    const dataField = packet.data.length > 0 ? { data: toBase64(packet.data) } : {};
+    if (sentCondition === void 0 || isZeroCondition(sentCondition)) {
+      return { accepted: true, ...dataField };
+    }
+    if (!fulfillmentMatchesCondition(packet.fulfillment, sentCondition)) {
+      return {
+        accepted: false,
+        code: FULFILLMENT_MISMATCH_CODE,
+        message: FULFILLMENT_MISMATCH_MESSAGE,
+        ...dataField
+      };
+    }
+    return {
+      accepted: true,
+      fulfillment: toBase64(packet.fulfillment),
+      ...dataField
+    };
+  }
+  return {
+    accepted: false,
+    code: packet.code,
+    message: packet.message,
+    ...packet.data.length > 0 ? { data: toBase64(packet.data) } : {}
+  };
+}
+
 // src/adapters/BtpRuntimeClient.ts
 function isConnectionError(error) {
   const msg = error.message.toLowerCase();
@@ -1324,6 +1394,12 @@ var BtpRuntimeClient = class {
   /**
    * 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`.
    */
   async sendIlpPacket(params) {
     return withRetry(() => this._sendIlpPacketOnce(params), {
@@ -1339,6 +1415,9 @@ var BtpRuntimeClient = class {
   /**
    * 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}.
    */
   async sendIlpPacketWithClaim(params, claim) {
     return withRetry(() => this._sendIlpPacketWithClaimOnce(params, claim), {
@@ -1381,6 +1460,30 @@ var BtpRuntimeClient = class {
       encodeUtf8(JSON.stringify(claim))
     );
   }
+  /**
+   * 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).
+   */
+  buildPrepare(params) {
+    const condition = params.executionCondition;
+    if (condition !== void 0 && !isZeroCondition(condition)) {
+      assertValidCondition(condition);
+    }
+    return {
+      prepare: {
+        type: 12,
+        amount: BigInt(params.amount),
+        destination: params.destination,
+        executionCondition: condition ?? new Uint8Array(32),
+        expiresAt: params.expiresAt ?? new Date(Date.now() + (params.timeout ?? 3e4)),
+        data: fromBase64(params.data)
+      },
+      condition
+    };
+  }
   /**
    * Single-attempt ILP packet send. Reconnects if not connected.
    */
@@ -1388,26 +1491,9 @@ var BtpRuntimeClient = class {
     if (!this._isConnected) {
       await this.reconnect();
     }
-    const response = await this.btpClient.sendPacket({
-      type: 12,
-      amount: BigInt(params.amount),
-      destination: params.destination,
-      executionCondition: new Uint8Array(32),
-      expiresAt: new Date(Date.now() + (params.timeout ?? 3e4)),
-      data: fromBase64(params.data)
-    });
-    if (response.type === ILPPacketType.FULFILL) {
-      return {
-        accepted: true,
-        data: response.data.length > 0 ? toBase64(response.data) : void 0
-      };
-    }
-    return {
-      accepted: false,
-      code: response.code,
-      message: response.message,
-      data: response.data.length > 0 ? toBase64(response.data) : void 0
-    };
+    const { prepare, condition } = this.buildPrepare(params);
+    const response = await this.btpClient.sendPacket(prepare);
+    return mapIlpResponse(response, condition);
   }
   /**
    * Single-attempt claim + ILP packet send. Reconnects if not connected.
@@ -1426,29 +1512,9 @@ var BtpRuntimeClient = class {
         data: encodeUtf8(JSON.stringify(claim))
       }
     ];
-    const response = await this.btpClient.sendPacket(
-      {
-        type: 12,
-        amount: BigInt(params.amount),
-        destination: params.destination,
-        executionCondition: new Uint8Array(32),
-        expiresAt: new Date(Date.now() + (params.timeout ?? 3e4)),
-        data: fromBase64(params.data)
-      },
-      protocolData
-    );
-    if (response.type === ILPPacketType.FULFILL) {
-      return {
-        accepted: true,
-        data: response.data.length > 0 ? toBase64(response.data) : void 0
-      };
-    }
-    return {
-      accepted: false,
-      code: response.code,
-      message: response.message,
-      data: response.data.length > 0 ? toBase64(response.data) : void 0
-    };
+    const { prepare, condition } = this.buildPrepare(params);
+    const response = await this.btpClient.sendPacket(prepare, protocolData);
+    return mapIlpResponse(response, condition);
   }
 };
 
@@ -1480,6 +1546,12 @@ var HttpIlpClient = class {
    * 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}.
    */
   async sendIlpPacket(params) {
     return withRetry(() => this.postPrepare(params), {
@@ -1494,6 +1566,9 @@ var HttpIlpClient = class {
    * 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}.
    */
   async sendIlpPacketWithClaim(params, claim) {
     return withRetry(() => this.postPrepare(params, claim), {
@@ -1546,12 +1621,16 @@ var HttpIlpClient = class {
    */
   async postPrepare(params, claim) {
     const requestTimeout = params.timeout ?? this.timeout;
+    const condition = params.executionCondition;
+    if (condition !== void 0 && !isZeroCondition(condition)) {
+      assertValidCondition(condition);
+    }
     const prepare = serializeIlpPrepare({
       type: ILPPacketType.PREPARE,
       amount: BigInt(params.amount),
       destination: params.destination,
-      executionCondition: new Uint8Array(32),
-      expiresAt: new Date(Date.now() + requestTimeout),
+      executionCondition: condition ?? new Uint8Array(32),
+      expiresAt: params.expiresAt ?? new Date(Date.now() + requestTimeout),
       data: fromBase64(params.data)
     });
     const headers = {
@@ -1574,7 +1653,7 @@ var HttpIlpClient = class {
         signal: controller.signal
       });
       clearTimeout(timeoutId);
-      return await this.mapResponse(response);
+      return await this.mapResponse(response, condition);
     } catch (error) {
       clearTimeout(timeoutId);
       throw this.mapTransportError(error, requestTimeout);
@@ -1584,26 +1663,18 @@ var HttpIlpClient = class {
    * 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).
    */
-  async mapResponse(response) {
+  async mapResponse(response, sentCondition) {
     if (response.ok) {
       const buf = new Uint8Array(await response.arrayBuffer());
       if (buf.length === 0) {
         throw new ConnectorError("Empty 200 body from /ilp (expected OER ILP response)");
       }
-      const ilp = deserializeIlpPacket(buf);
-      if (ilp.type === ILPPacketType.FULFILL) {
-        return {
-          accepted: true,
-          data: ilp.data.length > 0 ? toBase64(ilp.data) : void 0
-        };
-      }
-      return {
-        accepted: false,
-        code: ilp.code,
-        message: ilp.message,
-        data: ilp.data.length > 0 ? toBase64(ilp.data) : void 0
-      };
+      return mapIlpResponse(deserializeIlpPacket(buf), sentCondition);
     }
     const body = await response.text().catch(() => "");
     const detail = body ? `: ${body}` : "";
@@ -1692,7 +1763,7 @@ import { base58Encode as base58Encode2 } from "@toon-protocol/core";
 
 // src/channel/solana-payment-channel.ts
 import { ed25519 } from "@noble/curves/ed25519.js";
-import { sha256 } from "@noble/hashes/sha2.js";
+import { sha256 as sha2562 } from "@noble/hashes/sha2.js";
 import { base58Encode, base58Decode } from "@toon-protocol/core";
 var TOKEN_PROGRAM_ID = "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA";
 var SYSTEM_PROGRAM_ID = "11111111111111111111111111111111";
@@ -1781,7 +1852,7 @@ function findProgramAddress(seeds, programId) {
     input.set(programId, offset);
     offset += programId.length;
     input.set(PDA_MARKER, offset);
-    const hash = sha256(input);
+    const hash = sha2562(input);
     if (!isOnCurve(hash)) return { pda: hash, bump };
   }
   throw new Error("Could not find a viable PDA bump seed");
@@ -3234,7 +3305,7 @@ var SolanaSigner = class {
 
 // src/signing/mina-signer.ts
 import { hexToMinaBase58PrivateKey as hexToMinaBase58PrivateKey3 } from "@toon-protocol/core";
-import { sha256 as sha2562 } from "@noble/hashes/sha2.js";
+import { sha256 as sha2563 } from "@noble/hashes/sha2.js";
 import { bytesToHex } from "@noble/hashes/utils.js";
 
 // src/channel/mina-payment-channel.ts
@@ -3365,7 +3436,7 @@ var DEFAULT_MINA_TOKEN_ID = "MINA";
 var MINA_CLAIM_NETWORK = "devnet";
 function deriveMinaSalt(zkAppAddress, nonce) {
   const digestHex = bytesToHex(
-    sha2562(new TextEncoder().encode(`mina-pc-salt:${zkAppAddress}:${nonce}`))
+    sha2563(new TextEncoder().encode(`mina-pc-salt:${zkAppAddress}:${nonce}`))
   );
   const salt = BigInt("0x" + digestHex.slice(0, 60));
   return salt === 0n ? 1n : salt;
@@ -4897,6 +4968,14 @@ var ToonClient = class {
    *       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
    */
   async sendSwapPacket(params) {
@@ -4917,7 +4996,9 @@ var ToonClient = class {
         destination: params.destination,
         amount: String(params.amount),
         data: toBase64(params.toonData),
-        timeout: params.timeout ?? 3e4
+        timeout: params.timeout ?? 3e4,
+        ...params.executionCondition ? { executionCondition: params.executionCondition } : {},
+        ...params.expiresAt ? { expiresAt: params.expiresAt } : {}
       },
       claimMessage
     );
@@ -6771,7 +6852,7 @@ import {
   scryptSync,
   createCipheriv,
   createDecipheriv,
-  randomBytes
+  randomBytes as randomBytes2
 } from "crypto";
 import { writeFileSync as writeFileSync2, readFileSync as readFileSync2 } from "fs";
 var SCRYPT_N = 2 ** 17;
@@ -6798,8 +6879,8 @@ function encryptMnemonic2(mnemonic, password) {
   if (typeof password !== "string" || password.length === 0) {
     throw new Error("encryptMnemonic: password must be a non-empty string");
   }
-  const salt = randomBytes(SALT_LEN);
-  const iv = randomBytes(IV_LEN);
+  const salt = randomBytes2(SALT_LEN);
+  const iv = randomBytes2(IV_LEN);
   const key = scryptSync(password, salt, SCRYPT_KEY_LEN, {
     N: SCRYPT_N,
     r: SCRYPT_R,
@@ -6902,10 +6983,13 @@ function writeKeystoreFile(path, keystore) {
 }
 export {
   BtpRuntimeClient,
+  CONDITION_LENGTH,
   ChannelFundingError,
   ChannelManager,
   ConnectorError,
   EvmSigner,
+  FULFILLMENT_MISMATCH_CODE,
+  FULFILLMENT_MISMATCH_MESSAGE,
   GenerativeFallbackRenderer,
   Http402Client,
   HttpConnectorAdmin,
@@ -6930,6 +7014,7 @@ export {
   ValidationError,
   applyDefaults,
   applyNetworkPresets,
+  assertValidCondition,
   buildBackupEvent,
   buildBackupFilter,
   buildConsentRequest,
@@ -6947,6 +7032,7 @@ export {
   encryptMnemonic2 as encryptMnemonic,
   extractArweaveTxId,
   extractUiResource,
+  fulfillmentMatchesCondition,
   fundWallet,
   generateKeystore,
   generateMnemonic,
@@ -6959,7 +7045,9 @@ export {
   isInsufficientGasError,
   isPrfSupported,
   isTrustDowngrade,
+  isZeroCondition,
   loadKeystore,
+  mintExecutionCondition,
   parseBackupPayload,
   parseFulfillHttp,
   parseFulfillHttpBytes,