@toon-protocol/client 0.18.0 → 0.19.0

package/README.md

@@ -51,14 +51,11 @@ pnpm add mina-signer
 These coordinates go straight into the [`ToonClient` config](#quick-start) below.
 
 > **Local development (from a clone of this repo, not the npm package).** To try the client
-> end-to-end against a throwaway local network, start the monorepo's SDK E2E stack — Anvil + two peer
-> nodes + relays. This script ships with the repo, **not** the published package:
->
-> ```bash
-> ./scripts/sdk-e2e-infra.sh up     # start (Ctrl-C-safe; `down` to stop)
-> curl http://localhost:19100/health   # peer 1 health
-> ./scripts/sdk-e2e-infra.sh down   # stop
-> ```
+> end-to-end against a throwaway local network — Anvil + two peer nodes + relays — see
+> [`packages/client/tests/e2e/README.md`](tests/e2e/README.md) for the service topology and manual
+> testing snippet. Its automated setup steps assume the monorepo's `scripts/sdk-e2e-infra.sh`
+> wrapper and a `docker-compose-sdk-e2e.yml`, neither of which ships in this extracted repo; treat
+> those steps as a reference for provisioning the equivalent infrastructure yourself.
 >
 > | Service          | Port  | Purpose                                             |
 > | ---------------- | ----- | --------------------------------------------------- |
@@ -275,38 +272,36 @@ pnpm test:coverage        # Run with coverage report
 
 ### E2E Tests
 
-E2E tests require the SDK E2E infrastructure:
+E2E tests require Docker Compose infrastructure. See
+[tests/e2e/README.md](tests/e2e/README.md) for the service topology — note its automated setup
+script isn't included in this extracted repo either (see the Prerequisites section above), so
+provision the equivalent infrastructure manually, then run:
 
 ```bash
-# Start infrastructure
-./scripts/sdk-e2e-infra.sh up
-
-# Run E2E tests
 cd packages/client
 pnpm test:e2e
 ```
 
-See [tests/e2e/README.md](tests/e2e/README.md) for detailed E2E setup.
-
 ---
 
 ## Examples
 
-See [examples/client-example/](../../examples/client-example/) for standalone client examples:
+See [examples/](examples/) for standalone client examples:
 
-- **01 - Publish Event** (`01-publish-event.ts`): Full client lifecycle with self-describing claims
-- **02 - Payment Channel Lifecycle** (`02-payment-channel.ts`): Multiple events with incrementing balance proofs
-- **03 - Multi-Chain Publish** (`03-multi-chain-publish.ts`): Publishing with multiple settlement chains configured
-- **04 - Subscribe to Events** (`04-subscribe-events.ts`): Reading events back from the relay (free)
+- **Basic Publish** (`basic-publish.ts`): Publish a Nostr event to the TOON network
+- **Publish and Verify** (`publish-and-verify.ts`): Publish an event and verify via connector logs
+- **Publish to Peer1** (`publish-to-peer1.ts`): Multi-hop ILP routing via a peer connector
+- **Multi-Hop Routing** (`multi-hop-routing.ts`): Route an event through peer1 to the genesis relay
+- **With Payment Channels** (`with-payment-channels.ts`): Configure EVM payment channels and publish with a signed balance proof
 
 ---
 
 ## Related Packages
 
-- **[@toon-protocol/core](../core/)** — Core protocol (peer discovery, bootstrap, `buildBlobStorageRequest`)
-- **[@toon-protocol/relay](../relay/)** — Operator product running the apex connector plus relay/swap/store nodes; also exports `encodeEventToToon` / `decodeEventFromToon` for event encoding
-- **[@toon-protocol/sdk](../sdk/)** — Higher-level helpers including `streamSwap()` for multi-chain swaps via a **swap**
-- **[@toon-protocol/bls](../bls/)** — Business Logic Server (pricing, validation, storage)
+- **[@toon-protocol/core](https://www.npmjs.com/package/@toon-protocol/core)** — Core protocol (peer discovery, bootstrap, `buildBlobStorageRequest`)
+- **[@toon-protocol/relay](https://www.npmjs.com/package/@toon-protocol/relay)** — Operator product running the apex connector plus relay/swap/store nodes; also exports `encodeEventToToon` / `decodeEventFromToon` for event encoding
+- **[@toon-protocol/sdk](https://www.npmjs.com/package/@toon-protocol/sdk)** — Higher-level helpers including `streamSwap()` for multi-chain swaps via a **swap**
+- **[@toon-protocol/bls](https://www.npmjs.com/package/@toon-protocol/bls)** — Business Logic Server (pricing, validation, storage)
 
 ---
 

package/dist/index.d.ts

@@ -407,6 +407,24 @@ interface ToonClientConfig {
      * gated (distinct from the connector #88 on-chain-settle gate).
      */
     minaChannel?: MinaChannelClientOptions;
+    /**
+     * Receive-side Mina swap-claim redemption (#357): maker on-chain co-signatures
+     * keyed by dest-channel zkApp address (B62).
+     *
+     * On-chain `claimFromChannel` is dual-party — it verifies BOTH participants
+     * signed `[commitment, nonce, channelHash]`. The recipient (this client)
+     * produces its own co-signature from the derived Mina key, but the swap-wire
+     * claim only carries the maker's `balanceProofFieldsMina` signature (a
+     * DIFFERENT message), so the maker must additionally deliver a
+     * payment-channel-commitment-form co-signature. Until that flows over the swap
+     * wire, an operator can inject the maker's `{ r, s }` here to complete a
+     * receive-side redemption. Absent one, settlement fails closed with
+     * `MINA_MAKER_COSIGN_REQUIRED` (never a silent pass).
+     */
+    swapMinaMakerSignatures?: Record<string, {
+        r: string;
+        s: string;
+    }>;
     /** File path for persisting payment channel nonce/amount state across restarts */
     channelStorePath?: string;
     /** Nostr relay URL for peer discovery. Default: 'ws://localhost:7100' */
@@ -1561,8 +1579,6 @@ declare class ToonClient {
     private getClaimTransport;
     /**
      * Shared claim-resolution logic used by `publishEvent` and `sendSwapPacket`.
-     * TODO(12.5 followup): also factor `publishEvent`'s inline claim resolution
-     * to call this helper. Kept duplicated for now to minimize regression risk.
      */
     private resolveClaimForDestination;
     /**
@@ -2935,6 +2951,44 @@ declare class ChannelManager {
  * @param fetchImpl - injectable for tests; defaults to global `fetch`.
  */
 declare function readMinaDepositTotal(graphqlUrl: string, zkAppAddress: string, fetchImpl?: typeof fetch): Promise<bigint>;
+/** Channel-lifecycle enum written to `channelState` (matches the zkApp). */
+declare const MINA_CHANNEL_STATE: {
+    readonly UNINITIALIZED: 0;
+    readonly OPEN: 1;
+    readonly CLOSING: 2;
+    readonly SETTLED: 3;
+};
+/**
+ * On-chain `PaymentChannel` state the receive-side settler needs to assemble a
+ * co-signed `claimFromChannel` — all read via plain GraphQL (NO o1js / WASM), so
+ * the read path stays lightweight and unit-testable. Field semantics match
+ * {@link MinaChannelState} in the connector's Mina SDK.
+ */
+interface MinaOnChainChannelState {
+    /** `Poseidon([participantA.x, participantB.x, channelNonce])`, decimal Field. */
+    channelHash: string;
+    /** Current `Poseidon([balanceA, balanceB, salt])`, decimal Field. */
+    balanceCommitment: string;
+    /** Highest claimed nonce recorded on-chain. */
+    nonceField: bigint;
+    /** {@link MINA_CHANNEL_STATE} enum value. */
+    channelState: number;
+    /** Total escrowed deposit (base units). */
+    depositTotal: bigint;
+}
+/**
+ * Read the channel's on-chain `PaymentChannel` state via GraphQL.
+ *
+ * Reuses the same `account(publicKey).zkappState` query as
+ * {@link readMinaDepositTotal} and decodes the fields the co-signed
+ * `claimFromChannel` assembly binds: `channelHash` (participant identity),
+ * `depositTotal` (balance conservation), `nonceField` (monotonicity gate), and
+ * `channelState` (must be OPEN). No o1js is loaded — the values are raw Field
+ * decimal strings straight off the node.
+ *
+ * @param fetchImpl - injectable for tests; defaults to global `fetch`.
+ */
+declare function readMinaChannelState(graphqlUrl: string, zkAppAddress: string, fetchImpl?: typeof fetch): Promise<MinaOnChainChannelState>;
 
 /**
  * Receive-side swap-claim ingestion + verification (toon-client#352, part of
@@ -3035,6 +3089,389 @@ declare function hasSettlementMetadata(claim: AccumulatedClaim): claim is Accumu
  */
 declare function ingestReceivedClaims(params: IngestReceivedClaimsParams): IngestReceivedClaimsResult;
 
+/**
+ * Per-packet preimage retention (toon-client#360, rolling-swap epic
+ * toon-meta#145 — spec `docs/rolling-swap.md` §3 R1 / §3.2 leg-B reveal).
+ *
+ * `withSenderConditions` (toon-client#354) mints a fresh 32-byte preimage
+ * `P_i` per fill packet, sets `C_i = sha256(P_i)` on the leg-A PREPARE, and —
+ * before this module — DISCARDED `P_i`. Leg-B reveal (spec §3.2) is the commit
+ * act: the sender reveals `P_i` only AFTER verifying the leg-B claim, so the
+ * daemon must retain each `P_i` from mint time until the reveal step consumes
+ * it. This is that retention seam.
+ *
+ * Keyed by `packetIndex` — the 0-indexed position in the swap's packet stream.
+ * `packetIndex` is the one identifier shared between the send side (the wrapper
+ * mints one condition per `sendSwapPacket` call, which `streamSwap` issues in
+ * strictly increasing `packetIndex` order) and the receive side
+ * (`AccumulatedClaim.packetIndex`), so it correlates a retained preimage to the
+ * claim whose reveal will consume it.
+ *
+ * Reveal is single-use: {@link PreimageRetentionStore.take} removes the entry
+ * so a preimage is never revealed twice (spec R1 — a reused preimage lets an
+ * observer of packet *i* fulfill packet *i+1* without the sender's consent).
+ *
+ * Session-scoped and in-memory by design: a preimage is only meaningful within
+ * the swap stream that minted it (a fresh stream mints fresh preimages), and a
+ * preimage revealed after a crash would commit leg A for a leg-B claim the
+ * restarted daemon can no longer verify. Durability lives on the *watermark*
+ * (`ReceivedClaimStore`), not here.
+ */
+/** A retained per-packet hashlock secret awaiting (or past) its leg-B reveal. */
+interface RetainedPreimage {
+    /** 0-indexed position in the swap's packet stream; the correlation key. */
+    packetIndex: number;
+    /** The 32-byte preimage `P_i` — revealed to commit leg A (spec R6). */
+    preimage: Uint8Array;
+    /** `C_i = sha256(P_i)` — what went on the leg-A PREPARE (kept for auditing). */
+    condition: Uint8Array;
+    /** Unix ms the preimage was minted/retained. */
+    retainedAt: number;
+}
+/**
+ * Retention interface for per-packet preimages, keyed by `packetIndex`. Mirrors
+ * the sync surface of the daemon's other stores ({@link ReceivedClaimStore}).
+ */
+interface PreimageRetentionStore {
+    /** Retain `entry`, replacing any prior entry for the same `packetIndex`. */
+    retain(entry: RetainedPreimage): void;
+    /** Peek the retained preimage for `packetIndex` without consuming it. */
+    get(packetIndex: number): RetainedPreimage | undefined;
+    /** Consume (return AND remove) the preimage — single-use reveal (spec R1). */
+    take(packetIndex: number): RetainedPreimage | undefined;
+    /** Number of preimages still retained (awaiting reveal). */
+    size(): number;
+    /** Drop every retained preimage — call when the session ends. */
+    clear(): void;
+}
+/**
+ * In-memory {@link PreimageRetentionStore}. The only implementation: preimages
+ * are session-scoped secrets that MUST NOT outlive their stream (see the module
+ * doc), so there is deliberately no file-backed variant.
+ */
+declare class InMemoryPreimageRetentionStore implements PreimageRetentionStore {
+    private readonly entries;
+    retain(entry: RetainedPreimage): void;
+    get(packetIndex: number): RetainedPreimage | undefined;
+    take(packetIndex: number): RetainedPreimage | undefined;
+    size(): number;
+    clear(): void;
+}
+
+/**
+ * Atomic verify -> persist -> reveal composition (toon-client#360, rolling-swap
+ * epic toon-meta#145 — spec `docs/rolling-swap.md` §3 R5/R8, §3.2 leg-B reveal).
+ *
+ * {@link ingestReceivedClaims} (toon-client#358) verifies a received chain-B
+ * claim and persists its watermark AT VERIFY TIME. But verification is not the
+ * commit: leg-B reveal is (spec R5 — the sender reveals `P_i` only after the
+ * claim verifies). A daemon that verifies a claim, advances the watermark, and
+ * then WITHHOLDS or FAILS the reveal has advanced a watermark for value it never
+ * committed to. Left there, engine rule R8 bites: after the maker rolls its own
+ * side back it REUSES the rolled-back nonce for the next fill, and the client's
+ * monotonicity check (`nonce <= watermark.nonce -> NON_MONOTONIC_NONCE`) would
+ * falsely reject that legitimate re-fill.
+ *
+ * So verify/persist/reveal must compose as ONE unit whose durable effect is
+ * "watermark advanced iff the reveal committed":
+ *
+ *   1. snapshot the prior watermark for the claim's `(chain, channelId)`;
+ *   2. verify + persist via {@link ingestReceivedClaims} (single claim);
+ *   3. reveal the retained preimage `P_i` for `claim.packetIndex`;
+ *   4. on `withheld` / thrown / preimage-missing -> COMPENSATING ROLLBACK:
+ *      restore the snapshot (or delete when there was none), so the watermark
+ *      tracks only ACCEPTED/REVEALED packets and R8's reused nonce is accepted.
+ *
+ * Claims are processed strictly in order and each claim's fate is decided
+ * before the next is verified, so cross-claim monotonicity flows through the
+ * durable store: a rolled-back claim leaves no trace for the next to trip over.
+ * Legacy no-metadata claims (spec §349 path) and hard verification rejects
+ * never reach a reveal and never touch a watermark — behavior unchanged.
+ */
+
+/** The sender's leg-B decision for a verified claim (spec R5). */
+type RevealDecision = 'revealed' | 'withheld';
+interface RevealResult {
+    decision: RevealDecision;
+    /** Human-readable detail, surfaced on a rolled-back record when withheld. */
+    reason?: string;
+}
+/**
+ * Reveal a verified claim's preimage to commit leg A, OR withhold it. Receives
+ * the claim and the retained preimage for its `packetIndex` (`undefined` when
+ * none was retained — e.g. a legacy zero-condition packet reaching this path).
+ * Returning `withheld`, resolving to no decision, or THROWING all trigger the
+ * compensating rollback; only `revealed` keeps the watermark advance.
+ */
+type RevealFn = (claim: AccumulatedClaim, preimage: RetainedPreimage | undefined) => RevealResult | Promise<RevealResult>;
+interface IngestAndRevealParams extends IngestReceivedClaimsParams {
+    /** Leg-B reveal decision, invoked once per VERIFIED claim (spec R5/R6). */
+    reveal: RevealFn;
+    /**
+     * Retained per-packet preimages ({@link PreimageRetentionStore}). The reveal
+     * for a verified claim CONSUMES (`take`) the preimage for its `packetIndex`,
+     * so a preimage is never revealed twice (spec R1). Optional: without it the
+     * reveal fn receives `undefined` and decides on its own.
+     */
+    preimages?: PreimageRetentionStore;
+}
+interface RevealedClaim {
+    claim: AccumulatedClaim;
+    /** How far the (now committed) watermark advanced. */
+    watermarkAdvance: bigint;
+}
+interface RolledBackClaim {
+    claim: AccumulatedClaim;
+    /** The advance that was persisted then rolled back (never counted). */
+    watermarkAdvance: bigint;
+    /** Why the reveal did not commit (withheld reason, or the thrown error). */
+    reason: string;
+}
+interface IngestAndRevealResult {
+    /** Claims that verified AND revealed — the only ones whose value counts. */
+    revealed: RevealedClaim[];
+    /**
+     * Claims that verified but whose reveal was withheld/failed: the watermark
+     * advance was persisted then ROLLED BACK, so a subsequent re-fill reusing
+     * the same nonce (engine R8) is accepted, not falsely rejected.
+     */
+    rolledBack: RolledBackClaim[];
+    /** Claims that failed verification. NEVER revealed, NEVER persisted. */
+    rejected: ReceivedClaimRejection[];
+    /** Legacy no-metadata claims (spec §349). Unchanged: not verified/revealed. */
+    legacy: AccumulatedClaim[];
+    /** Total watermark advance across REVEALED claims only. */
+    valueRevealed: bigint;
+}
+/**
+ * Verify, persist, and reveal a batch of received chain-B claims atomically:
+ * a verified claim's watermark advance survives iff its reveal commits, and is
+ * rolled back otherwise (see the module doc for why R8 needs this).
+ *
+ * Never throws on a bad claim or a throwing reveal — both land in the result
+ * (`rejected` / `rolledBack`) with the durable watermark left consistent.
+ */
+declare function ingestAndReveal(params: IngestAndRevealParams): Promise<IngestAndRevealResult>;
+
+/**
+ * Mina receive-side swap settlement (toon-client#357, part of the rolling-swap
+ * epic toon-meta#145; follow-up to the #352 receive-side ingestion PR).
+ *
+ * #352 shipped VERIFICATION of swapped-in Mina claims but explicitly left
+ * REDEMPTION out: `POST /swap/settle` returned `SUBMISSION_UNSUPPORTED` for
+ * `mina:*` bundles. This module is the missing redemption seam — it turns a
+ * verified accumulated Mina claim into an on-chain co-signed `claimFromChannel`
+ * transaction against the payment-channel zkApp.
+ *
+ * ## Why Mina needs a co-sign (and EVM/Solana do not)
+ *
+ * The zkApp's `claimFromChannel(newBalanceA, newBalanceB, newSalt, signatureA,
+ * signatureB, participantA, participantB, channelNonce, newBalanceCommitment,
+ * newNonce)` is DUAL-PARTY (connector#84): it verifies BOTH participants signed
+ * the SAME message `[newBalanceCommitment, newNonce, storedChannelHash]`
+ * (`packages/mina-zkapp/src/PaymentChannel.ts`). The client's existing
+ * {@link MinaSigner} is payer-side only. On the swap RECEIVE side the client is
+ * the RECIPIENT of the channel, so it must contribute the recipient's
+ * co-signature (`signatureB` for its participant slot).
+ *
+ * ## Signature-message mismatch — the maker-side dependency
+ *
+ * The swap-wire claim (`AccumulatedClaim.claimBytes`) carries the maker's
+ * Schnorr signature over `balanceProofFieldsMina(channelId, cumulativeAmount,
+ * nonce, recipient)` (verified by the sdk's `verifyMinaSignature`). That is a
+ * DIFFERENT message than the on-chain `[commitment, nonce, channelHash]`, so it
+ * CANNOT be reused as an on-chain participant signature. On-chain redemption
+ * therefore needs the maker to ALSO contribute a payment-channel-commitment-form
+ * signature over `[commitment, nonce, channelHash]` (the same form the connector
+ * payment-channel provider produces from a client claim). Until a maker delivers
+ * that, {@link submitMinaSettlement} fails closed with
+ * `MINA_MAKER_COSIGN_REQUIRED` (never a silent pass). See the PR body for the
+ * cross-repo maker/wire follow-up.
+ *
+ * ## globalSlot preconditions
+ *
+ * Unlike `initiateClose`/`settle` (which pin `network.globalSlotSinceGenesis`
+ * and were the subject of the #202 exact-slot-precondition bug), the zkApp's
+ * `claimFromChannel` binds NO slot precondition — only `channelState == OPEN`,
+ * `channelHash`, `depositTotal`, and a strictly-increasing `nonceField`. The
+ * redeem path is therefore immune to the #202 slot-drift failure. The eventual
+ * close+settle that pays escrow out to the recipient DOES touch the slot window
+ * and remains the connector's `settleChannel` responsibility (a separate step).
+ *
+ * ## What runs where
+ *
+ * - On-chain STATE READ + co-sign assembly ({@link buildMinaCoSignedClaim}):
+ *   plain GraphQL + `mina-signer` (Pallas Schnorr / Poseidon) — NO o1js, fully
+ *   unit-testable in-process.
+ * - Proof generation + broadcast ({@link submitMinaSettlement}): drives an
+ *   injectable {@link MinaClaimSubmitter}; the default is an o1js-backed settler
+ *   ({@link createO1jsMinaClaimSubmitter}) that dynamically imports `o1js` +
+ *   `@toon-protocol/mina-zkapp` only when invoked (never loaded by the non-Mina
+ *   suite). o1js circuit compilation + proving is slow (30-120s) and is exercised
+ *   only against live devnet Mina behind an env gate.
+ */
+
+/** Bare Pallas Schnorr signature in the o1js JSON (decimal `r`/`s`) form. */
+interface MinaSignaturePair {
+    r: string;
+    s: string;
+}
+/** Stable failure codes for Mina receive-side settlement. */
+type MinaSettlementErrorCode = 'NOT_MINA_BUNDLE' | 'NO_GRAPHQL_CONFIGURED' | 'CHANNEL_NOT_OPEN' | 'NONCE_NOT_ADVANCING' | 'CHANNEL_HASH_MISMATCH' | 'CUMULATIVE_EXCEEDS_DEPOSIT' | 'MINA_MAKER_COSIGN_REQUIRED' | 'PROVING_FAILED';
+/** Result-shaped-by-throw settlement error carrying a stable {@link code}. */
+declare class MinaSettlementError extends Error {
+    readonly code: MinaSettlementErrorCode;
+    constructor(code: MinaSettlementErrorCode, message: string);
+}
+/** Inputs to {@link buildMinaCoSignedClaim} (pure assembly, no o1js). */
+interface MinaCoSignInputs {
+    /** Deployed payment-channel zkApp address (B62) — the on-chain channel id. */
+    channelId: string;
+    /** Claim nonce being redeemed (must exceed the on-chain `nonceField`). */
+    nonce: bigint;
+    /** Cumulative amount credited to the recipient (base units). */
+    cumulativeAmount: bigint;
+    /** Recipient's Mina B62 pubkey — one channel participant (the co-signer). */
+    recipient: string;
+    /** Swap maker's Mina B62 pubkey — the other channel participant. */
+    swapSignerAddress: string;
+    /** On-chain `depositTotal` (base units) for balance conservation. */
+    depositTotal: bigint;
+    /** On-chain `channelHash` (decimal Field) used to resolve A/B ordering. */
+    onChainChannelHash: string;
+    /** Recipient's Mina private key (big-endian hex scalar OR `EK…` base58). */
+    recipientPrivateKey: string;
+    /** Channel nonce baked into the on-chain `channelHash` (default 0). */
+    channelNonce?: bigint;
+    /** Override the deterministic salt (else {@link deriveMinaSalt}). */
+    saltOverride?: bigint;
+    /**
+     * Maker's payment-channel-commitment-form signature over
+     * `[commitment, nonce, channelHash]`. REQUIRED for a fully-redeemable claim;
+     * when absent the returned claim reports {@link makerSignatureMissing}.
+     */
+    makerSignature?: MinaSignaturePair;
+}
+/** A dual-party claim assembled for the zkApp's `claimFromChannel`. */
+interface MinaCoSignedClaim {
+    channelId: string;
+    /** Balance credited to `participantA` (base units). */
+    balanceA: bigint;
+    /** Balance credited to `participantB` (`depositTotal - balanceA`). */
+    balanceB: bigint;
+    salt: bigint;
+    nonce: bigint;
+    channelNonce: bigint;
+    /** `Poseidon([balanceA, balanceB, salt])`, decimal Field. */
+    balanceCommitment: string;
+    /** Participant A B62 (ordered to reproduce the on-chain `channelHash`). */
+    participantA: string;
+    /** Participant B B62. */
+    participantB: string;
+    /** Which participant slot the recipient/co-signer occupies. */
+    recipientRole: 'A' | 'B';
+    /** The recipient's co-signature over `[commitment, nonce, channelHash]`. */
+    recipientSignature: MinaSignaturePair;
+    /** Signature for participant A (recipient's or maker's per {@link recipientRole}). */
+    signatureA?: MinaSignaturePair;
+    /** Signature for participant B. */
+    signatureB?: MinaSignaturePair;
+    /** True when no maker co-signature was supplied (claim not yet redeemable). */
+    makerSignatureMissing: boolean;
+}
+/**
+ * Assemble a dual-party `claimFromChannel` claim from a verified swap claim.
+ *
+ * Pure crypto (GraphQL-read state is passed in): resolves the on-chain A/B
+ * participant ordering by reproducing `channelHash`, conserves balances against
+ * `depositTotal`, computes the Poseidon commitment, and produces the recipient's
+ * co-signature over `[commitment, nonce, channelHash]` with `mina-signer`. No
+ * o1js is loaded.
+ *
+ * @throws {MinaSettlementError} `CHANNEL_HASH_MISMATCH` when neither ordering of
+ *   `{recipient, swapSignerAddress}` reproduces `onChainChannelHash`;
+ *   `CUMULATIVE_EXCEEDS_DEPOSIT` when the credit exceeds the escrow.
+ */
+declare function buildMinaCoSignedClaim(inputs: MinaCoSignInputs): Promise<MinaCoSignedClaim>;
+/** Arguments handed to a {@link MinaClaimSubmitter} (o1js proving boundary). */
+interface MinaClaimSubmitArgs {
+    /** Mina GraphQL endpoint bound as the active o1js network. */
+    graphqlUrl: string;
+    /** Channel zkApp address (B62). */
+    channelId: string;
+    balanceA: bigint;
+    balanceB: bigint;
+    salt: bigint;
+    nonce: bigint;
+    /** Participant pubkeys (B62), ordered to match the on-chain `channelHash`. */
+    participantA: string;
+    participantB: string;
+    channelNonce: bigint;
+    signatureA: MinaSignaturePair;
+    signatureB: MinaSignaturePair;
+    /** Fee-payer / submitter Mina private key (hex scalar or `EK…` base58). */
+    feePayerPrivateKey: string;
+    /** zkApp tx fee (nanomina); the default settler applies 0.1 MINA when unset. */
+    txFeeNanomina?: bigint;
+}
+/**
+ * Generates the o1js proof and broadcasts the `claimFromChannel` tx. Injected so
+ * the assembly logic can be unit-tested without loading the WASM circuit runtime.
+ */
+interface MinaClaimSubmitter {
+    claimFromChannel(args: MinaClaimSubmitArgs): Promise<{
+        txHash: string;
+    }>;
+}
+/** Read seam for the on-chain channel state (default: plain GraphQL). */
+type MinaChannelStateReader = (graphqlUrl: string, zkAppAddress: string) => Promise<MinaOnChainChannelState>;
+/** Context for {@link submitMinaSettlement}. */
+interface MinaSettlementContext {
+    /** Mina GraphQL URL (reads state + binds the o1js network). */
+    graphqlUrl?: string;
+    /** Recipient's Mina private key (co-signs; also the default fee payer). */
+    recipientPrivateKey: string;
+    /** Maker's on-chain-form co-signature over `[commitment, nonce, channelHash]`. */
+    makerSignature?: MinaSignaturePair;
+    /** Fee-payer key override (defaults to `recipientPrivateKey`). */
+    feePayerPrivateKey?: string;
+    /** zkApp tx fee (nanomina). */
+    txFeeNanomina?: bigint;
+    /** Channel nonce for the on-chain `channelHash` (default 0). */
+    channelNonce?: bigint;
+    /** Inject a state reader (tests). Defaults to {@link readMinaChannelState}. */
+    reader?: MinaChannelStateReader;
+    /** Inject a proof submitter (tests). Defaults to an o1js-backed settler. */
+    submitter?: MinaClaimSubmitter;
+}
+interface MinaSettlementResult {
+    txHash: string;
+}
+/**
+ * Redeem a verified Mina swap claim via a co-signed on-chain `claimFromChannel`.
+ *
+ * Env/config-gated like the EVM path: with no `graphqlUrl` the caller gets
+ * `NO_GRAPHQL_CONFIGURED` (built-not-submitted). Reads the live channel state,
+ * asserts it is OPEN and the claim nonce advances the on-chain watermark,
+ * assembles the dual-party claim ({@link buildMinaCoSignedClaim}), and — only
+ * with a maker co-signature present — drives the o1js proof + broadcast.
+ *
+ * @throws {MinaSettlementError} with a stable {@link MinaSettlementErrorCode}.
+ */
+declare function submitMinaSettlement(bundle: SettlementBundle, context: MinaSettlementContext): Promise<MinaSettlementResult>;
+/**
+ * Build the default o1js-backed {@link MinaClaimSubmitter}.
+ *
+ * Mirrors the connector's `MinaPaymentChannelSDK.claimFromChannel`: binds the
+ * active Mina network, fetches the channel + fee-payer accounts, deserializes the
+ * `{r,s}` signatures, and builds + proves + broadcasts the zkApp
+ * `claimFromChannel` method. o1js and `@toon-protocol/mina-zkapp` are imported
+ * dynamically INSIDE `claimFromChannel` so the non-Mina test suite never loads
+ * the multi-hundred-MB WASM circuit runtime. Compilation + proving are slow
+ * (30-120s) and only run against live devnet Mina.
+ */
+declare function createO1jsMinaClaimSubmitter(): MinaClaimSubmitter;
+
 /**
  * Configuration options for retry behavior with exponential backoff.
  */
@@ -3274,7 +3711,7 @@ declare function validateConfig(config: ToonClientConfig): void;
  * The resolved config type after defaults are applied.
  * secretKey is guaranteed to be present (auto-generated if omitted).
  */
-type ResolvedConfig = Required<Omit<ToonClientConfig, 'connector' | 'mnemonic' | 'mnemonicAccountIndex' | 'evmPrivateKey' | 'network' | 'supportedChains' | 'settlementAddresses' | 'preferredTokens' | 'tokenNetworks' | 'btpUrl' | 'btpAuthToken' | 'btpPeerId' | 'connectorHttpEndpoint' | 'proxyUrl' | 'faucetUrl' | 'connectorSupportsUpgrade' | 'chainRpcUrls' | 'initialDeposit' | 'settlementTimeout' | 'solanaChannel' | 'minaChannel' | 'channelStorePath' | 'knownPeers' | 'destinationAddress'>> & {
+type ResolvedConfig = Required<Omit<ToonClientConfig, 'connector' | 'mnemonic' | 'mnemonicAccountIndex' | 'evmPrivateKey' | 'network' | 'supportedChains' | 'settlementAddresses' | 'preferredTokens' | 'tokenNetworks' | 'btpUrl' | 'btpAuthToken' | 'btpPeerId' | 'connectorHttpEndpoint' | 'proxyUrl' | 'faucetUrl' | 'connectorSupportsUpgrade' | 'chainRpcUrls' | 'initialDeposit' | 'settlementTimeout' | 'solanaChannel' | 'minaChannel' | 'swapMinaMakerSignatures' | 'channelStorePath' | 'knownPeers' | 'destinationAddress'>> & {
     connector?: unknown;
     /** Always present after applyDefaults() — derived from secretKey if not explicitly provided */
     evmPrivateKey: string | Uint8Array;
@@ -3308,6 +3745,7 @@ type ResolvedConfig = Required<Omit<ToonClientConfig, 'connector' | 'mnemonic' |
     settlementTimeout?: number;
     solanaChannel?: ToonClientConfig['solanaChannel'];
     minaChannel?: ToonClientConfig['minaChannel'];
+    swapMinaMakerSignatures?: ToonClientConfig['swapMinaMakerSignatures'];
     channelStorePath?: string;
     knownPeers?: {
         pubkey: string;
@@ -3737,4 +4175,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 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 };
+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, InMemoryPreimageRetentionStore, InMemoryReceivedClaimStore, type IngestAndRevealParams, type IngestAndRevealResult, type IngestReceivedClaimsParams, type IngestReceivedClaimsResult, JsonFileReceivedClaimStore, KeyManager, type KeyManagerConfig, MINA_CHANNEL_STATE, type MinaChannelStateReader, type MinaClaimMessage, type MinaClaimSubmitArgs, type MinaClaimSubmitter, type MinaCoSignInputs, type MinaCoSignedClaim, type MinaDepositReader, type MinaOnChainChannelState, type MinaSettlementContext, MinaSettlementError, type MinaSettlementErrorCode, type MinaSettlementResult, type MinaSignaturePair, MinaSigner, type MinaSignerOptions, NetworkError, OnChainChannelClient, type OnChainChannelClientConfig, type ParsedFulfillHttp, type ParsedX402Challenge, type PasskeyInfo, type PreimageRetentionStore, type PublishEventResult, type ReceivedClaimEntry, type ReceivedClaimRejection, type ReceivedClaimRejectionCode, type ReceivedClaimStore, type RequestBlobStorageParams, type RequestBlobStorageResult, type RetainedPreimage, type RetryOptions, type RevealDecision, type RevealFn, type RevealResult, type RevealedClaim, type RolledBackClaim, 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, buildMinaCoSignedClaim, buildSettlementInfo, buildStoreWriteEnvelope, buildSwapSettlements, createO1jsMinaClaimSubmitter, decodeEvmSettlementTx, decryptMnemonic, defaultFaucetTimeout, deriveFromNsec, deriveFullIdentity, deriveNostrKeyFromMnemonic, encryptMnemonic, entryToAccumulatedClaim, extractArweaveTxId, fulfillmentMatchesCondition, fundWallet, generateKeystore, generateMnemonic, generateRandomIdentity, getNetworkStatus, hasSettlementMetadata, httpEndpointToBtpUrl, importKeystore, ingestAndReveal, ingestReceivedClaims, isInsufficientGasError, isPrfSupported, isZeroCondition, loadKeystore, mintExecutionCondition, parseBackupPayload, parseEvmChainId, parseFulfillHttp, parseFulfillHttpBytes, parseHttpResponse, parseX402Body, parseX402Challenge, proxyIlpEndpoint, readDiscoveredIlpPeer, readEvmNativeBalance, readEvmTokenBalance, readMinaBalance, readMinaChannelState, readMinaDepositTotal, readSolanaNativeBalance, readSolanaTokenBalance, readWalletBalances, requestBlobStorage, selectIlpTransport, serializeHttpRequest, submitEvmSettlement, submitMinaSettlement, validateConfig, validateMnemonic, withRetry, writeKeystoreFile };