@toon-protocol/sdk 0.4.0 → 0.5.1

package/dist/index.d.ts

@@ -1,7 +1,11 @@
-import { ToonError, HandlePacketAcceptResponse, HandlePacketRejectResponse, ReputationScore, SkillDescriptor, EmbeddableConnectorLike, KnownPeer, SettlementConfig, ChainProviderConfigEntry, ConnectorChannelClient, BootstrapEventListener, BootstrapResult, DvmJobStatus, IlpSendResult, ParsedWorkflowDefinition } from '@toon-protocol/core';
-export { BootstrapEvent, BootstrapEventListener, HandlePacketAcceptResponse, HandlePacketRejectResponse, SkillDescriptor } from '@toon-protocol/core';
-import { NostrEvent } from 'nostr-tools/pure';
+import { ToonError, HandlePacketAcceptResponse, HandlePacketRejectResponse, ReputationScore, SkillDescriptor, EmbeddableConnectorLike, KnownPeer, SettlementConfig, ChainProviderConfigEntry, ConnectorChannelClient, BootstrapEventListener, BootstrapResult, DvmJobStatus, IlpSendResult, ParsedWorkflowDefinition, SwapPair } from '@toon-protocol/core';
+export { BootstrapEvent, BootstrapEventListener, HandlePacketAcceptResponse, HandlePacketRejectResponse, SkillDescriptor, balanceProofFieldsMina, balanceProofHashEvm, balanceProofHashSolana, bigintToBytes32BE, concatBytes, hexToBytes, minaHashToField } from '@toon-protocol/core';
+import { NostrEvent, UnsignedEvent } from 'nostr-tools/pure';
 import { ToonRoutingMeta } from '@toon-protocol/core/toon';
+import { TransportConfig } from '@toon-protocol/connector';
+export { TransportConfig } from '@toon-protocol/connector';
+import { A as AccumulatedClaim } from './swap-D4Ozr_BM.js';
+export { D as DecryptFulfillClaimParams, E as EncryptFulfillClaimParams, a as EncryptFulfillClaimResult, P as PacketProgress, R as RateMonitorCallback, S as StreamSwapController, b as StreamSwapParams, c as StreamSwapResult, U as UnwrapSwapPacketFromToonParams, d as UnwrapSwapPacketParams, e as UnwrapSwapPacketResult, W as WrapSwapPacketParams, f as WrapSwapPacketResult, g as WrapSwapPacketToToonParams, h as WrapSwapPacketToToonResult, _ as __streamSwapTesting, i as decryptFulfillClaim, j as encryptFulfillClaim, s as streamSwap, k as streamSwapControlled, u as unwrapSwapPacket, l as unwrapSwapPacketFromToon, w as wrapSwapPacket, m as wrapSwapPacketToToon } from './swap-D4Ozr_BM.js';
 
 /**
  * Unified identity module for @toon-protocol/sdk.
@@ -24,6 +28,34 @@ interface NodeIdentity {
     /** The EIP-55 checksummed EVM address (0x-prefixed, 42 characters). */
     evmAddress: string;
 }
+/**
+ * Solana Ed25519 identity derived via SLIP-0010 from a BIP-39 mnemonic.
+ */
+interface SolanaIdentity {
+    /** 64-byte Ed25519 keypair (32-byte private key + 32-byte public key). */
+    secretKey: Uint8Array;
+    /** Base58-encoded Ed25519 public key (Solana address). */
+    publicKey: string;
+}
+/**
+ * Mina Pallas identity derived from a BIP-39 mnemonic via mina-signer.
+ */
+interface MinaIdentity {
+    /** Hex-encoded Pallas private key. */
+    privateKey: string;
+    /** Base58 Mina public key (B62 prefix). */
+    publicKey: string;
+}
+/**
+ * Full multi-chain identity derived from a single BIP-39 mnemonic.
+ * Extends NodeIdentity (Nostr + EVM) with Solana and optionally Mina.
+ */
+interface ToonIdentity extends NodeIdentity {
+    /** Solana Ed25519 identity (always populated from mnemonic derivation). */
+    solana: SolanaIdentity;
+    /** Mina Pallas identity (undefined when mina-signer is not installed). */
+    mina?: MinaIdentity;
+}
 /**
  * Options for mnemonic-based key derivation.
  */
@@ -47,7 +79,7 @@ declare function generateMnemonic(): string;
  * @returns The derived NodeIdentity with secretKey, pubkey, and evmAddress.
  * @throws {IdentityError} If the mnemonic is invalid.
  */
-declare function fromMnemonic(mnemonic: string, options?: FromMnemonicOptions): NodeIdentity;
+declare function fromMnemonic(mnemonic: string, options?: FromMnemonicOptions): ToonIdentity;
 /**
  * Derives a complete NodeIdentity from an existing 32-byte secret key.
  *
@@ -56,6 +88,42 @@ declare function fromMnemonic(mnemonic: string, options?: FromMnemonicOptions):
  * @throws {IdentityError} If the secret key is not exactly 32 bytes.
  */
 declare function fromSecretKey(secretKey: Uint8Array): NodeIdentity;
+/**
+ * Derives a full multi-chain ToonIdentity from a BIP-39 mnemonic,
+ * including async Mina derivation (requires mina-signer).
+ *
+ * Chains derived:
+ * - Nostr (secp256k1): m/44'/1237'/0'/0/{accountIndex}
+ * - EVM (secp256k1): same key as Nostr, Keccak-256 for address
+ * - Solana (Ed25519): m/44'/501'/{accountIndex}'/0' (SLIP-0010)
+ * - Mina (Pallas): m/44'/12586'/{accountIndex}'/0/0 (optional, requires mina-signer)
+ *
+ * All four chains vary by `accountIndex`, so distinct indices yield fully
+ * distinct multi-chain identities from one seed. Index 0 is unchanged from the
+ * historical fixed paths.
+ *
+ * @param mnemonic - A valid BIP-39 mnemonic (12 or 24 words).
+ * @param options - Optional derivation options (accountIndex defaults to 0).
+ * @returns The derived ToonIdentity with all chain identities populated.
+ * @throws {IdentityError} If the mnemonic is invalid.
+ */
+declare function fromMnemonicFull(mnemonic: string, options?: FromMnemonicOptions): Promise<ToonIdentity>;
+/**
+ * Generates a random Solana Ed25519 keypair (non-deterministic).
+ *
+ * For deterministic derivation from a mnemonic, use fromMnemonic() instead.
+ *
+ * @returns A SolanaIdentity with random keypair.
+ */
+declare function generateSolanaKeypair(): SolanaIdentity;
+/**
+ * Encodes a byte array to a Base58 string (Bitcoin/Solana alphabet).
+ */
+declare function base58Encode(bytes: Uint8Array): string;
+/**
+ * Decodes a Base58 string to a byte array (Bitcoin/Solana alphabet).
+ */
+declare function base58Decode(str: string): Uint8Array;
 
 /**
  * SDK-specific error classes for @toon-protocol/sdk.
@@ -97,6 +165,61 @@ declare class VerificationError extends ToonError {
 declare class PricingError extends ToonError {
     constructor(message: string, cause?: Error);
 }
+/**
+ * Error thrown when NIP-59 gift wrap or NIP-44 FULFILL encryption operations fail.
+ * Used for wrap/unwrap failures, decryption errors, and malformed gift wrap events.
+ */
+declare class GiftWrapError extends ToonError {
+    constructor(message: string, cause?: Error);
+}
+/**
+ * Error thrown when Mill swap handler orchestration fails.
+ * Used for rate-conversion errors (invalid format, zero, overflow guards),
+ * unsupported pair lookups, and issuer-boundary failures that are NOT
+ * gift-wrap-specific. Gift-wrap failures continue to surface as `GiftWrapError`.
+ */
+declare class SwapHandlerError extends ToonError {
+    constructor(message: string, cause?: Error);
+}
+/**
+ * Error thrown by the sender-side `streamSwap()` API (Story 12.5).
+ *
+ * All failures are categorized by a narrow `code` so callers can branch on
+ * cause. `INVALID_*` codes are construction-time validation failures (thrown
+ * synchronously before any packet fires). `FULFILL_DECODE_FAILED` surfaces
+ * when the Mill returns `accepted: true` but the FULFILL data cannot be
+ * decoded — this is a non-fatal per-packet error and is captured in
+ * `StreamSwapResult.errors[]`.
+ */
+declare class StreamSwapError extends Error {
+    readonly code: 'INVALID_AMOUNT' | 'INVALID_CHUNKING' | 'INVALID_PAIR' | 'INVALID_STATE' | 'INVALID_CHAIN_RECIPIENT' | 'FULFILL_DECODE_FAILED';
+    readonly cause?: unknown;
+    constructor(code: StreamSwapError['code'], message: string, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * Error thrown by the sender-side `buildSettlementTx()` helper (Story 12.6).
+ *
+ * Settlement is a post-swap one-shot computation, so this error class is
+ * THROWN synchronously (unlike `streamSwap` which routes per-packet failures
+ * through `StreamSwapResult`). Callers are expected to wrap the call in
+ * `try/catch`.
+ *
+ * Narrow `code` union lets callers branch on cause — see
+ * `_bmad-output/implementation-artifacts/12-6-build-settlement-tx.md` AC-11
+ * for the per-code semantics.
+ *
+ * @since 12.6
+ * @stable — Epic 13 Chain Bridge DVM depends on this error shape.
+ */
+declare class SettlementTxError extends Error {
+    readonly code: 'INVALID_INPUT' | 'MISSING_SETTLEMENT_METADATA' | 'UNSUPPORTED_CHAIN' | 'MISSING_RECIPIENT' | 'RECIPIENT_MISMATCH' | 'MILL_SIGNER_MISMATCH' | 'DUPLICATE_NONCE' | 'NON_MONOTONIC_CUMULATIVE' | 'INVALID_SIGNATURE_LENGTH' | 'INVALID_SIGNATURE_V' | 'ENCODING_FAILED';
+    readonly cause?: unknown;
+    constructor(code: SettlementTxError['code'], message: string, options?: {
+        cause?: unknown;
+    });
+}
 
 /**
  * Handler context for @toon-protocol/sdk.
@@ -165,6 +288,11 @@ declare class HandlerRegistry {
      * Returns all registered kind numbers, sorted ascending.
      */
     getRegisteredKinds(): number[];
+    /**
+     * Returns the handler registered for `kind`, or `undefined` if none.
+     * Added for Story 12.7 AC-10 (handler-registration verification).
+     */
+    get(kind: number): Handler | undefined;
     /**
      * Returns registered kinds in the DVM request range (5000-5999), sorted ascending.
      * Uses JOB_REQUEST_KIND_BASE (5000) as the range start.
@@ -451,6 +579,12 @@ interface NodeConfig {
      * Only used when auto-creating an embedded connector.
      */
     chainProviders?: ChainProviderConfigEntry[];
+    /**
+     * Transport configuration for the embedded connector (ator/SOCKS5 privacy overlay).
+     * When provided, passed directly to ConnectorNode as `transport`.
+     * Only used when auto-creating an embedded connector.
+     */
+    transport?: TransportConfig;
     /**
      * NIP-59 transport privacy configuration for the embedded connector.
      * When enabled, per-packet claims are wrapped in three-layer encryption.
@@ -1034,12 +1168,16 @@ interface ArweaveUploadAdapter {
 /**
  * Turbo SDK upload adapter using @ardrive/turbo-sdk.
  *
- * - Dev/free tier (<=100KB): pass no turboClient, uses TurboFactory.unauthenticated()
- * - Prod (paid, uncapped): pass a TurboAuthenticatedClient from TurboFactory.authenticated()
+ * - Dev/free tier (<=100KB): pass no turboClient. getClient() lazily generates an
+ *   ephemeral RSA JWK and builds a TurboFactory.authenticated() client. The upload
+ *   service grants free small-data-item uploads to any valid signer regardless of
+ *   balance, so no deposit is required. NOTE: TurboFactory.unauthenticated() is NOT
+ *   usable here — in @ardrive/turbo-sdk >=1.40 uploadFile() exists only on the
+ *   authenticated client; the unauthenticated client exposes only uploadSignedDataItem().
+ * - Prod (paid, uncapped): pass a TurboAuthenticatedClient from a funded wallet.
  *
  * The turboClient is typed as `unknown` to avoid importing @ardrive/turbo-sdk types
- * in this interface. The actual TurboAuthenticatedClient or TurboUnauthenticatedClient
- * is duck-typed at runtime.
+ * in this interface. The actual TurboAuthenticatedClient is duck-typed at runtime.
  */
 declare class TurboUploadAdapter implements ArweaveUploadAdapter {
     private turboClient;
@@ -1210,4 +1348,604 @@ declare function uploadBlob(node: PublishableNode, blob: Buffer, destination: st
  */
 declare function uploadBlobChunked(node: PublishableNode, blob: Buffer, destination: string, options: UploadBlobChunkedOptions): Promise<string>;
 
-export { type AddChunkResult, type ArweaveDvmConfig, type ArweaveUploadAdapter, type BuildSkillDescriptorConfig, ChunkManager, type ChunkManagerConfig, type CreateHandlerContextOptions, type FromMnemonicOptions, type Handler, type HandlerContext, HandlerError, HandlerRegistry, type HandlerResponse, IdentityError, type NodeConfig, NodeError, type NodeIdentity, type PaymentHandlerBridgeConfig, type PaymentRequest, type PaymentResponse, type PrefixClaimHandlerOptions, PricingError, type PricingValidationResult, type PricingValidatorConfig, type PublishEventResult, type PublishableNode, type ServiceNode, type StartResult, SwarmCoordinator, type SwarmCoordinatorOptions, type SwarmState, TurboUploadAdapter, type UploadBlobChunkedOptions, type UploadBlobOptions, VerificationError, type VerificationPipelineConfig, type VerificationResult, type WorkflowEventStore, WorkflowOrchestrator, type WorkflowOrchestratorOptions, type WorkflowState, buildSkillDescriptor, createArweaveDvmHandler, createEventStorageHandler, createHandlerContext, createNode, createPaymentHandlerBridge, createPrefixClaimHandler, createPricingValidator, createVerificationPipeline, fromMnemonic, fromSecretKey, generateMnemonic, uploadBlob, uploadBlobChunked };
+/**
+ * Mill Swap Handler (Story 12.3)
+ *
+ * `createSwapHandler()` factory produces a kind:1059 `Handler` that:
+ *   1. Unwraps an incoming NIP-59 gift-wrapped ILP swap packet (via Story 12.2).
+ *   2. Identifies the requested `SwapPair` from inner-rumor `swap-from` / `swap-to` tags.
+ *   3. Applies a per-packet exchange rate (pair.rate or live rateProvider hook).
+ *   4. Delegates signed claim issuance to a pluggable `ClaimIssuer` (Story 12.4).
+ *   5. NIP-44 encrypts the claim with an ephemeral key (Story 12.2) for return.
+ *
+ * The handler is a pure application-layer composition — no connector, routing,
+ * or wallet code lives here. See `_bmad-output/epics/epic-12-token-swap-primitive.md`
+ * for D12-001/D12-008/D12-009/D12-010 and the scope fence.
+ *
+ * Transport encoding: the `accept()` metadata emits `claim` as a base64-encoded
+ * NIP-44 ciphertext, `ephemeralPubkey` as 64-char lowercase hex, and optional
+ * `claimId`. The sender-side `streamSwap()` (Story 12.5) base64-decodes `claim`
+ * before calling `decryptFulfillClaim`.
+ *
+ * @module
+ */
+
+/** Parameters passed to a {@link ClaimIssuer.issueClaim} call. */
+interface IssueClaimParams {
+    /** Source-asset amount received by the Mill (ILP packet amount, source micro-units). */
+    sourceAmount: bigint;
+    /** Target-asset amount owed to the sender (post-rate-conversion, target micro-units). */
+    targetAmount: bigint;
+    /** The `SwapPair` this packet is being priced against. */
+    pair: SwapPair;
+    /**
+     * The sender's real Nostr pubkey (extracted from the unwrapped seal).
+     *
+     * Identity-layer key only: used by the Mill for inventory ledger keying and
+     * the sender→channel sticky binding (`channelState.reserve()` /
+     * `channelState.release()`). The Mill MUST NOT pass this to chain-layer
+     * signers as the balance-proof `recipient` — use {@link chainRecipient}
+     * for that (Story 12.9 D12-011).
+     */
+    senderPubkey: string;
+    /**
+     * The sender's chain-specific payout address for `pair.to.chain`
+     * (Story 12.9 AC-10). Extracted and format-validated from the rumor's
+     * `chain-recipient` tag by the swap handler. REQUIRED. This is the
+     * address the Mill's `PaymentChannelSigner` MUST use as the balance-proof
+     * `recipient` (e.g., 20-byte EVM address, 32-byte Solana Ed25519 pubkey).
+     */
+    chainRecipient: string;
+    /** The inner rumor (for optional Mill-side context; may be ignored by the issuer). */
+    rumor: UnsignedEvent;
+}
+/**
+ * Result returned from {@link ClaimIssuer.issueClaim}.
+ *
+ * Story 12.6 extension: additive settlement-context fields let the sender
+ * reconstruct the balance-proof message hash for signature verification and
+ * on-chain settlement (see `buildSettlementTx()`).
+ */
+interface IssueClaimResult {
+    /** Signed claim bytes ready for NIP-44 encryption (chain-specific format). */
+    claim: Uint8Array;
+    /** Optional Mill-side claim ID for logging/tracing. */
+    claimId?: string;
+    /** Channel identifier on the target chain. */
+    channelId?: string;
+    /** Balance-proof nonce (monotonically increasing per channel). */
+    nonce?: bigint;
+    /** Cumulative transferred amount on the channel (target micro-units). */
+    cumulativeAmount?: bigint;
+    /** Recipient address (the sender's target-asset address). */
+    recipient?: string;
+    /** Mill's on-chain signer address. */
+    millSignerAddress?: string;
+}
+/**
+ * Pluggable signed-claim issuer. Story 12.3 defines only the contract — the
+ * concrete multi-chain implementation ships in Story 12.4.
+ *
+ * The issuer owns inventory accounting and signing-key material. The handler
+ * relies on `issueClaim()` being atomic with inventory debit: if the call
+ * resolves, the target-asset amount MUST be considered committed from the
+ * Mill's reserves. If the call throws, no inventory change SHOULD have occurred.
+ */
+interface ClaimIssuer {
+    /**
+     * Produce a signed off-chain payment-channel claim in the target asset.
+     *
+     * @throws Error (or subclass) on insufficient reserves, unsupported pair,
+     * or signing failure. Errors with `code === 'INSUFFICIENT_INVENTORY'` or
+     * messages matching `/insufficient/i` are surfaced as ILP T04; all other
+     * errors as T00.
+     */
+    issueClaim(params: IssueClaimParams): Promise<IssueClaimResult>;
+}
+/** Parameters for {@link applyRate}. */
+interface ApplyRateParams {
+    /** Source amount in source micro-units. */
+    sourceAmount: bigint;
+    /** `SwapPair.from.assetScale` (number of decimals on source side). */
+    fromScale: number;
+    /** `SwapPair.to.assetScale` (number of decimals on target side). */
+    toScale: number;
+    /** Decimal-string rate (target whole-units per source whole-unit). */
+    rate: string;
+}
+/** Minimal pino-compatible logger interface. */
+interface SwapHandlerLogger {
+    debug: (...args: unknown[]) => void;
+    info: (...args: unknown[]) => void;
+    warn: (...args: unknown[]) => void;
+    error: (...args: unknown[]) => void;
+}
+/**
+ * Minimal `Set`-like contract the handler requires from
+ * `seenPacketIds`. Both the native `Set<string>` and
+ * {@link BoundedSeenPacketIds} satisfy this; operators can swap in a
+ * persistent/remote-backed replacement too.
+ */
+interface SeenPacketIdsLike {
+    has(value: string): boolean;
+    add(value: string): unknown;
+    delete(value: string): boolean;
+}
+/** Configuration for {@link createSwapHandler}. */
+interface CreateSwapHandlerConfig {
+    /** Mill's secp256k1 secret key for unwrapping gift-wrapped packets (32 bytes). */
+    recipientSecretKey: Uint8Array;
+    /** Swap pairs this Mill currently supports. */
+    swapPairs: SwapPair[];
+    /** Claim issuer delegate (Story 12.4 plugs in the multi-chain implementation). */
+    claimIssuer: ClaimIssuer;
+    /**
+     * Optional live-rate override hook. When provided, the handler calls this per
+     * packet instead of reading `pair.rate`. MUST return a decimal string matching
+     * `SwapPair.rate` format: /^(0|[1-9]\d*)(\.\d+)?$/.
+     */
+    rateProvider?: (pair: SwapPair) => string | Promise<string>;
+    /**
+     * Optional replay-protection set. When provided, the handler uses it
+     * VERBATIM (operator-owned — bounding/persistence is the operator's
+     * responsibility). When OMITTED (Story 12.8 AC-14), the handler
+     * defaults to a {@link BoundedSeenPacketIds} with cap
+     * {@link DEFAULT_SEEN_PACKET_IDS_CAP}. Any `Set`-shaped object with
+     * `has`/`add`/`delete` (and a `size` getter for test introspection)
+     * satisfies the contract.
+     */
+    seenPacketIds?: SeenPacketIdsLike;
+    /** Optional pino-compatible logger. Defaults to a no-op logger. */
+    logger?: SwapHandlerLogger;
+}
+/**
+ * ILP REJECT codes emitted by `createSwapHandler()`.
+ *
+ * Exported as named constants so tests (Story 12.8 AC-3 forbids hardcoded
+ * error-code strings) and downstream integrators can assert against the
+ * same symbolic source the handler uses. Values follow RFC 27 / ILPv4
+ * reject-code conventions (F01 = malformed, F02 = unreachable, F04 =
+ * duplicate, F06 = unsupported pair, T00 = transient internal, T04 =
+ * insufficient liquidity).
+ */
+declare const SWAP_HANDLER_REJECT_CODES: {
+    /** Malformed / invalid PREPARE content — gift-wrap shape or amount invalid. */
+    readonly INVALID_GIFT_WRAP: "F01";
+    /** No route — the handler did not match a registered destination. */
+    readonly UNREACHABLE: "F02";
+    /** Duplicate packet — `seenPacketIds` replay hit. */
+    readonly DUPLICATE_PACKET: "F04";
+    /** Requested swap pair is not advertised by this Mill. */
+    readonly UNSUPPORTED_PAIR: "F06";
+    /** Transient internal failure — signing, rate provider, or unexpected. */
+    readonly INTERNAL: "T00";
+    /** Insufficient Mill inventory for the requested amount. */
+    readonly INSUFFICIENT_LIQUIDITY: "T04";
+};
+/**
+ * Human-readable reject messages emitted by `createSwapHandler()`.
+ *
+ * Tests may assert against these verbatim rather than matching regexes
+ * (Story 12.8 AC-3 guidance).
+ */
+declare const SWAP_HANDLER_REJECT_MESSAGES: {
+    readonly INVALID_GIFT_WRAP: "Invalid gift wrap";
+    readonly INVALID_AMOUNT: "Invalid amount";
+    readonly UNREACHABLE: "Unreachable";
+    readonly DUPLICATE_PACKET: "Duplicate packet";
+    readonly UNSUPPORTED_PAIR: "Unsupported swap pair";
+    readonly INTERNAL: "Internal error";
+    readonly INSUFFICIENT_LIQUIDITY: "Insufficient liquidity";
+    readonly RATE_PROVIDER: "Rate provider error";
+    readonly RATE_CONVERSION: "Rate conversion error";
+};
+/**
+ * Apply a decimal-string exchange rate to a source amount across asset scales.
+ * Uses BigInt arithmetic throughout — never coerces to `Number` — to preserve
+ * 18-decimal EVM precision (Epic 11 retro MAX_SAFE_INTEGER guard).
+ *
+ * Rounds toward zero (integer division), which economically favors the Mill
+ * (standard market-maker convention).
+ *
+ * @throws {SwapHandlerError} If rate format is invalid, rate is zero, or
+ *   sourceAmount is not positive.
+ */
+declare function applyRate(params: ApplyRateParams): bigint;
+/**
+ * Find the `SwapPair` identified by the rumor's `swap-from` / `swap-to` tags.
+ *
+ * Each tag value is parsed as `<assetCode>:<chain>`, split on the FIRST `:`
+ * so multi-segment chain IDs like `evm:base:8453` remain intact as the chain
+ * portion. Returns `null` for any malformed/missing tag — the handler
+ * interprets `null` as "unsupported pair" and rejects via ILP F06.
+ */
+declare function findSwapPair(rumor: UnsignedEvent, pairs: SwapPair[]): SwapPair | null;
+/**
+ * Construct a kind:1059 Mill inbound-swap handler.
+ *
+ * The returned `Handler` is a pure closure over `config`; two calls with the
+ * same config yield two independent-but-equivalent handlers. Register via
+ * `node.handlers.on(1059, handler)` (Story 12.7).
+ *
+ * @throws {SwapHandlerError} At construction time if config is malformed.
+ */
+declare function createSwapHandler(config: CreateSwapHandlerConfig): Handler;
+
+/**
+ * Mina-specific settlement: balance-proof signature verification +
+ * settlement-bundle construction (Story 12.8 follow-up to 12.6 AC-9).
+ *
+ * ## What is implemented (and unit-tested)
+ *
+ * - {@link verifyMinaSignature}: verifies the Mill's off-chain balance-proof
+ *   signature using `mina-signer` (`verifyFields`). This is the EXACT inverse
+ *   of the Mill's {@link MinaPaymentChannelSigner} (`packages/mill/src/payment-channel-signer.ts`),
+ *   which signs `balanceProofFieldsMina(channelId, cumulativeAmount, nonce, recipient)`
+ *   via `mina-signer`'s `signFields` and emits the base58 signature string as
+ *   the claim's `claimBytes` (UTF-8). The field-element derivation lives in
+ *   `hashes.ts` so signer and verifier cannot drift (same single-source-of-
+ *   truth pattern as EVM/Solana).
+ * - {@link buildMinaSettlementTx}: constructs a {@link SettlementBundle}
+ *   envelope (chain metadata + the verified balance proof bytes) so a Chain
+ *   Bridge DVM / direct sender has everything needed to drive the on-chain
+ *   claim. The signature is re-emitted verbatim in `unsignedTxBytes`.
+ *
+ * ## What remains (documented gap — NOT silently stubbed)
+ *
+ * The final on-chain step — submitting a Mina zkApp `claimFromChannel`
+ * transaction that settles the channel — requires **o1js circuit compilation
+ * + zk-SNARK proof generation** (Poseidon balance-commitment, zkApp method
+ * proving). The connector already implements this in
+ * `MinaPaymentChannelSDK.claimFromChannel()` (o1js, heavyweight). That proof
+ * generation is intentionally NOT done here: o1js circuit compilation is far
+ * too heavy for a unit-testable SDK helper and would pull a multi-hundred-MB
+ * WASM dependency into every SDK consumer. Instead, the bundle carries the
+ * verified balance proof so a Mina-capable settler (the connector's
+ * `MinaPaymentChannelProvider`, or a future o1js-backed Chain Bridge DVM) can
+ * generate the proof + broadcast. See the on-chain settlement note below
+ * (connector 3.8.1 wires the dual-party claim path — connector#84).
+ *
+ * Note also: the Mill↔sender wire proof here (a Schnorr signature over four
+ * field elements) is a DIFFERENT object than the connector's on-chain
+ * `MinaPaymentChannelSDK` Poseidon-commitment proof shape
+ * (`{ commitment, signature, nonce }`). The verifier matches the Mill's
+ * actual emitted format (`MinaPaymentChannelSigner`), which is what a sender
+ * receives on-wire.
+ *
+ * @module
+ * @since 12.8
+ */
+
+/**
+ * Minimal structural type for the slice of the `mina-signer` `Client` we use.
+ * Declared locally so the SDK does not hard-depend on the optional peer dep's
+ * full type surface (the ambient `mina-signer.d.ts` only declares
+ * `derivePublicKey`). `verifyFields` is synchronous.
+ */
+interface MinaSignerClientLike {
+    verifyFields(input: {
+        data: bigint[];
+        signature: string;
+        publicKey: string;
+    }): boolean;
+}
+/**
+ * Lazily load `mina-signer` (optional peer dep) and instantiate a `Client`
+ * bound to {@link MINA_NETWORK}. Returns `undefined` when the peer dep is not
+ * installed — callers MUST treat that as "cannot verify Mina claims" rather
+ * than "claim is valid".
+ *
+ * Mirrors the dynamic-import pattern in `identity.ts` (`deriveMinaIdentity`).
+ *
+ * @since 12.8
+ */
+declare function loadMinaSignerClient(): Promise<MinaSignerClientLike | undefined>;
+/**
+ * Verify a Mina balance-proof Schnorr signature carried in an
+ * `AccumulatedClaim`.
+ *
+ * Re-derives the signed field-element message via {@link balanceProofFieldsMina}
+ * (identical to the Mill signer), decodes the claim's `claimBytes` to the
+ * base58 signature string the Mill emitted, and verifies it against
+ * `expectedSignerAddress` using a `mina-signer` `Client`.
+ *
+ * `client` MUST be a pre-loaded `mina-signer` `Client` (see
+ * {@link loadMinaSignerClient}). It is injected (rather than imported inline)
+ * so the synchronous `buildSettlementTx()` pipeline can verify Mina claims
+ * without becoming async.
+ *
+ * @returns `true` iff the signature is valid for the given signer address.
+ * @throws {SettlementTxError} on missing settlement metadata or a malformed
+ *   (non-UTF-8 / empty) signature payload.
+ * @since 12.8
+ */
+declare function verifyMinaSignature(claim: AccumulatedClaim, expectedSignerAddress: string, client: MinaSignerClientLike): boolean;
+
+/**
+ * Public types for `buildSettlementTx()` (Story 12.6).
+ *
+ * @module
+ * @since 12.6
+ * @see _bmad-output/implementation-artifacts/12-6-build-settlement-tx.md
+ */
+
+/**
+ * Chain-specific raw settlement transaction bundle, produced by
+ * `buildSettlementTx()`. Contains everything a Chain Bridge DVM
+ * (Epic 13, kind:5260) or a direct sender needs to submit the settlement
+ * on-chain.
+ *
+ * @stable — Epic 13 Chain Bridge DVM depends on this shape.
+ * @since 12.6
+ */
+interface SettlementBundle {
+    /** Target chain identifier (e.g., `'evm:8453'`, `'evm:42161'`, `'solana:mainnet'`, `'mina:mainnet'`). */
+    chain: string;
+    /** Chain family — drives per-chain parsing. */
+    chainKind: 'evm' | 'solana' | 'mina';
+    /** Channel identifier on the target chain (lowercase hex with 0x prefix for EVM; base58 for Solana). */
+    channelId: string;
+    /** Cumulative transferred amount settled by this tx (target micro-units, decimal string). */
+    cumulativeAmount: string;
+    /** Balance-proof nonce settled by this tx (decimal string). */
+    nonce: string;
+    /** Recipient address (the sender's target-asset address — the one that will receive funds). */
+    recipient: string;
+    /** Mill's on-chain signer address (expected signer of the balance-proof signature). */
+    millSignerAddress: string;
+    /**
+     * Raw UNSIGNED transaction bytes ready for the caller to sign (or for a
+     * Chain Bridge DVM to gas-sponsor + sign). EVM: RLP-encoded tx with
+     * placeholder gas fields (tx nonce / gasPrice / gasLimit = 0) per EIP-155.
+     * Solana: serialized Message (not Transaction — Transaction requires signatures).
+     * Mina: the verified balance-proof signature bytes (envelope). The final
+     * on-chain `claimFromChannel` zkApp tx requires o1js proof generation and is
+     * produced by a Mina-capable settler — see the on-chain settlement note in
+     * `packages/sdk/src/settlement/mina.ts` (connector 3.8.1 wires the dual-party
+     * claim path — connector#84).
+     */
+    unsignedTxBytes: Uint8Array;
+    /**
+     * Expected on-chain event signature (hex, 0x-prefixed keccak256 for EVM)
+     * so a Chain Bridge DVM can watch for confirmation. Optional for
+     * non-EVM chains that lack topic-based event signatures.
+     */
+    expectedEventSignature?: string;
+    /**
+     * Number of `AccumulatedClaim` inputs in THIS bundle's `(chain, channelId)`
+     * group that survived signature verification.
+     */
+    claimsMerged: number;
+    /** Index of the winning claim in the ORIGINAL input array (`BuildSettlementTxParams.claims`). */
+    selectedClaimIndex: number;
+    /** Source-asset chain of the SwapPair (for Chain Bridge bill-back). */
+    sourceChain: string;
+    /** Source-asset code of the SwapPair (for Chain Bridge bill-back). */
+    sourceAssetCode: string;
+}
+/**
+ * Per-chain Mill signer configuration.
+ *
+ * @since 12.6
+ */
+interface MillSignerConfig {
+    /**
+     * Expected on-chain signer address for the Mill. EVM: 0x + 40 lowercase
+     * hex chars. Solana: base58-encoded 32-byte Ed25519 pubkey. Mina: base58 pubkey.
+     */
+    address: string;
+    /**
+     * On-chain payment-channel contract address (EVM-only).
+     */
+    contractAddress?: string;
+    /**
+     * Solana on-chain program ID. Required for Solana claims.
+     */
+    programId?: string;
+    /**
+     * EVM chain-id (decimal). Required for EVM claims — baked into RLP per EIP-155.
+     */
+    chainId?: number;
+}
+/**
+ * Parameters for `buildSettlementTx()`.
+ *
+ * @stable — Epic 13 Chain Bridge DVM depends on this shape.
+ * @since 12.6
+ */
+interface BuildSettlementTxParams {
+    /** Claims to settle. Typically `streamSwapResult.claims`. MUST be non-empty. */
+    claims: readonly AccumulatedClaim[];
+    /** Per-chain Mill signer configuration. Keyed by `claim.pair.to.chain`. */
+    signers: Record<string, MillSignerConfig>;
+    /** Sender's target-asset address per chain. Keyed by `claim.pair.to.chain`. */
+    recipients: Record<string, string>;
+    /** When `true` (default), verify every claim's signature against `signers[chain].address`. */
+    verifySignatures?: boolean;
+    /**
+     * Pre-loaded `mina-signer` `Client` (optional peer dep). REQUIRED to verify
+     * `mina:*` claims when `verifySignatures` is on: `buildSettlementTx()` is
+     * synchronous and `mina-signer` only loads via async `import()`, so the
+     * caller must load it up front (see `loadMinaSignerClient()`) and inject it
+     * here. When a `mina:*` claim is present and this is absent, that claim is
+     * rejected with `MINA_VERIFICATION_UNSUPPORTED` rather than passed through
+     * unverified. Ignored for EVM/Solana claims.
+     */
+    minaSignerClient?: MinaSignerClientLike;
+    /** When `true`, include superseded claims in `result.superseded[]`. Default false. */
+    includeSuperseded?: boolean;
+    /** Optional pino-compatible logger. */
+    logger?: {
+        debug: (...a: unknown[]) => void;
+        info: (...a: unknown[]) => void;
+        warn: (...a: unknown[]) => void;
+        error: (...a: unknown[]) => void;
+    };
+}
+/**
+ * Result of `buildSettlementTx()`.
+ *
+ * @stable — Epic 13 Chain Bridge DVM depends on this shape.
+ * @since 12.6
+ */
+interface BuildSettlementTxResult {
+    /** One bundle per unique (chain, channelId) group that had at least one surviving claim. */
+    bundles: SettlementBundle[];
+    /** Claims rejected during signature verification. */
+    rejected: {
+        claim: AccumulatedClaim;
+        reason: 'SIGNATURE_INVALID' | 'SIGNER_MISMATCH' | 'MINA_VERIFICATION_UNSUPPORTED';
+        details?: string;
+    }[];
+    /** Claims superseded by a higher-nonce claim in the same group (only populated if params.includeSuperseded). */
+    superseded: AccumulatedClaim[];
+}
+
+/**
+ * EVM-specific settlement tx construction + signature verification
+ * (Story 12.6 AC-7).
+ *
+ * @module
+ * @since 12.6
+ * @see _bmad-output/implementation-artifacts/12-6-build-settlement-tx.md
+ */
+
+/**
+ * Re-encode an EVM settlement bundle's RLP with real tx-nonce / gasPrice /
+ * gasLimit values. The `to`, `value`, `data`, `chainId` fields are preserved
+ * from the original bundle.
+ *
+ * @stable
+ * @since 12.6
+ */
+declare function fillEvmSettlementTxGas(bundle: SettlementBundle, gas: {
+    nonce: bigint;
+    gasPrice: bigint;
+    gasLimit: bigint;
+}, signer: MillSignerConfig): Uint8Array;
+
+/**
+ * `buildSettlementTx()` — public entrypoint for Story 12.6.
+ *
+ * Takes the output `claims` array from `streamSwap()` + per-chain signer
+ * config + per-chain recipient addresses, and produces one
+ * {@link SettlementBundle} per unique `(chain, channelId)` group.
+ *
+ * @module
+ * @since 12.6
+ * @see _bmad-output/implementation-artifacts/12-6-build-settlement-tx.md
+ */
+
+/**
+ * Build raw unsigned settlement transactions from a bag of accumulated
+ * swap claims.
+ *
+ * Algorithm:
+ *   1. Validate params (synchronous throws on malformed input).
+ *   2. Optionally verify each claim's signature. Rejected claims land in
+ *      `result.rejected[]` and are dropped from further processing.
+ *   3. Group surviving claims by `(chain, channelId)`. Within each group,
+ *      assert recipient + millSignerAddress consensus, unique nonces, and
+ *      non-decreasing cumulativeAmount with nonce.
+ *   4. Pick the winning claim per group (highest nonce).
+ *   5. Dispatch each winner to its chain-specific tx builder.
+ *
+ * @stable
+ * @since 12.6
+ * @throws {SettlementTxError} Synchronously on malformed input, group-level
+ *   inconsistency, or chain dispatch failures.
+ *
+ * @example
+ * ```ts
+ * const result = await streamSwap({ ... });
+ * const { bundles } = buildSettlementTx({
+ *   claims: result.claims,
+ *   signers: {
+ *     'evm:base:8453': {
+ *       address: '0xmill...',
+ *       contractAddress: '0xtokennetwork...',
+ *       chainId: 8453,
+ *     },
+ *   },
+ *   recipients: { 'evm:base:8453': '0xsender...' },
+ * });
+ * // Feed bundles[0].unsignedTxBytes into fillEvmSettlementTxGas → sign → eth_sendRawTransaction.
+ * ```
+ */
+declare function buildSettlementTx(params: BuildSettlementTxParams): BuildSettlementTxResult;
+/**
+ * Standalone utility: verify a single `AccumulatedClaim`'s signature against
+ * a `MillSignerConfig` without running the full grouping/winner pipeline.
+ *
+ * Useful inside a `streamSwap()` `onPacket` callback for mid-stream claim
+ * validation.
+ *
+ * For `mina:*` claims, pass a pre-loaded `mina-signer` `Client` as
+ * `minaSignerClient` (see `loadMinaSignerClient()`); without it, Mina claims
+ * return `MINA_VERIFICATION_UNSUPPORTED` (same contract as
+ * `buildSettlementTx`).
+ *
+ * @stable
+ * @since 12.6
+ */
+declare function verifyAccumulatedClaim(claim: AccumulatedClaim, signer: MillSignerConfig, minaSignerClient?: MinaSignerClientLike): {
+    valid: true;
+} | {
+    valid: false;
+    reason: string;
+};
+
+/**
+ * Solana-specific settlement tx construction + signature verification
+ * (Story 12.6 AC-9).
+ *
+ * @module
+ * @since 12.6
+ * @see _bmad-output/implementation-artifacts/12-6-build-settlement-tx.md
+ */
+
+/**
+ * Verify a Solana Ed25519 balance-proof signature.
+ *
+ * @since 12.6
+ */
+declare function verifyEd25519Signature(claim: AccumulatedClaim, expectedSignerAddress: string): boolean;
+
+/**
+ * DvmHealthResponse — canonical type for the DVM BLS health endpoint.
+ * Exported from @toon-protocol/sdk so Townhouse and the entrypoint share
+ * the same definition (mirrors MillHealthResponse from @toon-protocol/mill).
+ */
+/** Per-kind job count for jobsRecent.byKind */
+interface DvmJobsByKindEntry {
+    kind: number;
+    count: number;
+}
+/** Per-status job counts for the sliding window */
+interface DvmJobsByStatus {
+    processing: number;
+    success: number;
+    error: number;
+    partial: number;
+}
+/** Windowed recent-jobs telemetry (default window: 5 min) */
+interface DvmJobsRecent {
+    total: number;
+    byKind: DvmJobsByKindEntry[];
+    byStatus: DvmJobsByStatus;
+}
+/** Response shape for GET /health on the DVM BLS server (port 3400). */
+interface DvmHealthResponse {
+    status: 'starting' | 'ok' | 'stopping' | 'stopped' | 'error';
+    version: string;
+    nodePubkey: string;
+    uptimeSec: number;
+    /** Registered handler event kinds (e.g. [5094, 5250]). */
+    handlerKinds: number[];
+    /** Per-kind pricing in string-encoded bigint (e.g. { "5094": "10", "5250": "10000" }). */
+    kindPricing: Record<string, string>;
+    basePricePerByte: string;
+    jobsRecent: DvmJobsRecent;
+}
+
+export { AccumulatedClaim, type AddChunkResult, type ApplyRateParams, type ArweaveDvmConfig, type ArweaveUploadAdapter, type BuildSettlementTxParams, type BuildSettlementTxResult, type BuildSkillDescriptorConfig, ChunkManager, type ChunkManagerConfig, type ClaimIssuer, type CreateHandlerContextOptions, type CreateSwapHandlerConfig, type DvmHealthResponse, type DvmJobsByKindEntry, type DvmJobsByStatus, type DvmJobsRecent, type FromMnemonicOptions, GiftWrapError, type Handler, type HandlerContext, HandlerError, HandlerRegistry, type HandlerResponse, IdentityError, type IssueClaimParams, type IssueClaimResult, type MillSignerConfig, type MinaIdentity, type MinaSignerClientLike, type NodeConfig, NodeError, type NodeIdentity, type PaymentHandlerBridgeConfig, type PaymentRequest, type PaymentResponse, type PrefixClaimHandlerOptions, PricingError, type PricingValidationResult, type PricingValidatorConfig, type PublishEventResult, type PublishableNode, SWAP_HANDLER_REJECT_CODES, SWAP_HANDLER_REJECT_MESSAGES, type ServiceNode, type SettlementBundle, SettlementTxError, type SolanaIdentity, type StartResult, StreamSwapError, SwapHandlerError, type SwapHandlerLogger, SwarmCoordinator, type SwarmCoordinatorOptions, type SwarmState, type ToonIdentity, TurboUploadAdapter, type UploadBlobChunkedOptions, type UploadBlobOptions, VerificationError, type VerificationPipelineConfig, type VerificationResult, type WorkflowEventStore, WorkflowOrchestrator, type WorkflowOrchestratorOptions, type WorkflowState, applyRate, base58Decode, base58Encode, buildSettlementTx, buildSkillDescriptor, createArweaveDvmHandler, createEventStorageHandler, createHandlerContext, createNode, createPaymentHandlerBridge, createPrefixClaimHandler, createPricingValidator, createSwapHandler, createVerificationPipeline, fillEvmSettlementTxGas, findSwapPair, fromMnemonic, fromMnemonicFull, fromSecretKey, generateMnemonic, generateSolanaKeypair, loadMinaSignerClient, uploadBlob, uploadBlobChunked, verifyAccumulatedClaim, verifyEd25519Signature, verifyMinaSignature };