@toon-protocol/sdk 0.5.0 → 0.5.1

package/dist/index.d.ts

@@ -0,0 +1,1951 @@
+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.
+ *
+ * Derives both a Nostr pubkey (x-only Schnorr, BIP-340) and an EVM address
+ * (Keccak-256) from a single secp256k1 private key, following the NIP-06
+ * derivation standard.
+ *
+ * Both Nostr and EVM use the secp256k1 elliptic curve, so a single 12-word
+ * seed phrase can recover the complete identity across both layers.
+ */
+/**
+ * Represents a node's complete identity: secret key, Nostr pubkey, and EVM address.
+ */
+interface NodeIdentity {
+    /** The 32-byte secp256k1 secret key. */
+    secretKey: Uint8Array;
+    /** The x-only Schnorr public key (32 bytes, 64 lowercase hex characters). */
+    pubkey: string;
+    /** 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.
+ */
+interface FromMnemonicOptions {
+    /** Key index in the NIP-06 derivation path. Defaults to 0. */
+    accountIndex?: number;
+}
+/**
+ * Generates a valid 12-word BIP-39 mnemonic using 128-bit entropy.
+ *
+ * @returns A space-separated string of 12 BIP-39 English words.
+ */
+declare function generateMnemonic(): string;
+/**
+ * Derives a complete NodeIdentity from a BIP-39 mnemonic phrase.
+ *
+ * Uses the NIP-06 derivation path: m/44'/1237'/0'/0/{accountIndex}
+ *
+ * @param mnemonic - A valid BIP-39 mnemonic (12 or 24 words).
+ * @param options - Optional derivation options (accountIndex defaults to 0).
+ * @returns The derived NodeIdentity with secretKey, pubkey, and evmAddress.
+ * @throws {IdentityError} If the mnemonic is invalid.
+ */
+declare function fromMnemonic(mnemonic: string, options?: FromMnemonicOptions): ToonIdentity;
+/**
+ * Derives a complete NodeIdentity from an existing 32-byte secret key.
+ *
+ * @param secretKey - A 32-byte secp256k1 secret key.
+ * @returns The derived NodeIdentity with secretKey, pubkey, and evmAddress.
+ * @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.
+ * All errors extend ToonError from @toon-protocol/core for a consistent error hierarchy.
+ */
+
+/**
+ * Error thrown when identity operations fail.
+ * Used for invalid mnemonics, invalid secret keys, and key derivation failures.
+ */
+declare class IdentityError extends ToonError {
+    constructor(message: string, cause?: Error);
+}
+/**
+ * Error thrown when node lifecycle operations fail.
+ * Used for start/stop failures, configuration errors, etc.
+ */
+declare class NodeError extends ToonError {
+    constructor(message: string, cause?: Error);
+}
+/**
+ * Error thrown when handler dispatch operations fail.
+ * Used for handler registration conflicts, missing handlers, and dispatch errors.
+ */
+declare class HandlerError extends ToonError {
+    constructor(message: string, cause?: Error);
+}
+/**
+ * Error thrown when Schnorr signature verification fails.
+ * Used for invalid signatures, malformed events, and verification pipeline errors.
+ */
+declare class VerificationError extends ToonError {
+    constructor(message: string, cause?: Error);
+}
+/**
+ * Error thrown when payment validation fails.
+ * Used for pricing calculation errors, insufficient payment, and pricing policy violations.
+ */
+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.
+ *
+ * Provides a context object passed to kind-based handlers with methods
+ * for accessing TOON data, shallow-parsed metadata, and accept/reject actions.
+ */
+
+/**
+ * The handler context passed to each kind-based handler.
+ */
+interface HandlerContext {
+    /** Raw TOON string (base64-encoded). */
+    readonly toon: string;
+    /** Event kind from shallow parse. */
+    readonly kind: number;
+    /** Event pubkey from shallow parse. */
+    readonly pubkey: string;
+    /** Payment amount in the ILP packet. */
+    readonly amount: bigint;
+    /** ILP destination address. */
+    readonly destination: string;
+    /** Lazy-decode the TOON payload into a full NostrEvent. */
+    decode(): NostrEvent;
+    /** Accept the packet with optional metadata. */
+    accept(metadata?: Record<string, unknown>): HandlePacketAcceptResponse;
+    /** Reject the packet with an ILP error code and message. */
+    reject(code: string, message: string): HandlePacketRejectResponse;
+}
+interface CreateHandlerContextOptions {
+    toon: string;
+    meta: ToonRoutingMeta;
+    amount: bigint;
+    destination: string;
+    toonDecoder: (toon: string) => NostrEvent;
+}
+/**
+ * Creates a HandlerContext from the given options.
+ */
+declare function createHandlerContext(options: CreateHandlerContextOptions): HandlerContext;
+
+/**
+ * Handler registry for @toon-protocol/sdk.
+ *
+ * Maps event kinds to handler functions for dispatching incoming ILP packets.
+ */
+
+type HandlerResponse = HandlePacketAcceptResponse | HandlePacketRejectResponse;
+type Handler = (ctx: HandlerContext) => Promise<HandlerResponse>;
+/**
+ * Registry that maps Nostr event kinds to handler functions.
+ */
+declare class HandlerRegistry {
+    private handlers;
+    private defaultHandler;
+    /**
+     * Register a handler for a specific event kind.
+     * Replaces any existing handler for that kind.
+     */
+    on(kind: number, handler: Handler): this;
+    /**
+     * Register a default handler for unrecognized kinds.
+     */
+    onDefault(handler: Handler): this;
+    /**
+     * 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.
+     */
+    getDvmKinds(): number[];
+    /**
+     * Dispatch a context to the appropriate handler based on kind.
+     */
+    dispatch(ctx: HandlerContext): Promise<HandlerResponse>;
+}
+
+/**
+ * Pricing validator for @toon-protocol/sdk.
+ *
+ * Validates that incoming ILP payments meet the required price based on
+ * TOON payload size and configured price per byte.
+ */
+
+interface PricingValidatorConfig {
+    basePricePerByte?: bigint;
+    ownPubkey: string;
+    kindPricing?: Record<number, bigint>;
+}
+interface PricingValidationResult {
+    accepted: boolean;
+    rejection?: {
+        accept: false;
+        code: string;
+        message: string;
+        metadata?: Record<string, string>;
+    };
+}
+/**
+ * Creates a pricing validator that checks payment amounts against TOON size.
+ */
+declare function createPricingValidator(config: PricingValidatorConfig): {
+    validate(meta: ToonRoutingMeta, amount: bigint): PricingValidationResult;
+};
+
+/**
+ * Verification pipeline for @toon-protocol/sdk.
+ *
+ * Verifies Schnorr signatures on incoming TOON payloads before dispatching
+ * to handlers. In dev mode, verification is skipped.
+ */
+
+interface VerificationResult {
+    verified: boolean;
+    rejection?: {
+        accept: false;
+        code: string;
+        message: string;
+    };
+}
+interface VerificationPipelineConfig {
+    devMode: boolean;
+}
+/**
+ * Creates a verification pipeline that checks Schnorr signatures.
+ */
+declare function createVerificationPipeline(config: VerificationPipelineConfig): {
+    verify(meta: ToonRoutingMeta, _toonData: string): Promise<VerificationResult>;
+};
+
+/**
+ * Payment handler bridge for @toon-protocol/sdk.
+ *
+ * Bridges between ILP packet handling and the handler registry,
+ * using isTransit to distinguish fire-and-forget from await semantics.
+ */
+
+interface PaymentHandlerBridgeConfig {
+    registry: HandlerRegistry;
+    devMode: boolean;
+    ownPubkey: string;
+    basePricePerByte: bigint;
+}
+interface PaymentRequest {
+    paymentId: string;
+    destination: string;
+    amount: string;
+    data: string;
+    isTransit: boolean;
+}
+interface PaymentResponse {
+    accept: boolean;
+    code?: string;
+    message?: string;
+    data?: string;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Creates a payment handler bridge that connects ILP packets to the handler registry.
+ */
+declare function createPaymentHandlerBridge(config: PaymentHandlerBridgeConfig): {
+    handlePayment(request: PaymentRequest): Promise<PaymentResponse>;
+};
+
+/**
+ * Event storage handler stub for @toon-protocol/sdk.
+ *
+ * This is a stub that throws. The real implementation lives in
+ * `@toon-protocol/town` -- see `createEventStorageHandler` from that package.
+ *
+ * The SDK is the framework; Town is the relay implementation. SDK consumers
+ * building relay functionality should use `@toon-protocol/town` directly.
+ */
+/**
+ * Creates an event storage handler.
+ *
+ * **Stub** -- throws "not yet implemented". See `@toon-protocol/town` for the
+ * real relay implementation of this handler.
+ *
+ * @see {@link https://github.com/ALLiDoizCode/toon/tree/main/packages/town | @toon-protocol/town}
+ */
+declare function createEventStorageHandler(_config: unknown): unknown;
+
+/**
+ * Skill descriptor builder for DVM service discovery.
+ *
+ * Computes a SkillDescriptor from the handler registry and node configuration.
+ * The descriptor is embedded in kind:10035 events to advertise DVM capabilities.
+ *
+ * Returns `undefined` when no DVM handlers are registered (backward compatible
+ * with pre-DVM kind:10035 events).
+ */
+
+/** Configuration for building a skill descriptor. */
+interface BuildSkillDescriptorConfig {
+    /** Base price per byte in USDC micro-units (default: 10n). */
+    basePricePerByte?: bigint;
+    /** Per-kind pricing overrides (kind number -> price in USDC micro-units). */
+    kindPricing?: Record<number, bigint>;
+    /** Service name override (default: 'toon-dvm'). */
+    name?: string;
+    /** Schema version override (default: '1.0'). */
+    version?: string;
+    /** Feature list override. */
+    features?: string[];
+    /** JSON Schema draft-07 object for job request parameters. */
+    inputSchema?: Record<string, unknown>;
+    /** Available AI models. */
+    models?: string[];
+    /** Pre-computed reputation score for the skill descriptor. */
+    reputation?: ReputationScore;
+    /** TEE attestation metadata for the skill descriptor. */
+    attestation?: {
+        /** 64-char hex event ID of the provider's latest kind:10033 attestation event. */
+        eventId: string;
+        /** Enclave image hash for the TEE environment. */
+        enclaveImageHash: string;
+    };
+}
+/**
+ * Builds a SkillDescriptor from the handler registry and configuration.
+ *
+ * Returns `undefined` when the registry has no DVM handlers (kinds 5000-5999).
+ * When DVM kinds exist, auto-populates the descriptor:
+ * - `kinds` from `registry.getDvmKinds()`
+ * - `pricing` from `config.kindPricing` overrides or `config.basePricePerByte` fallback
+ * - `name`, `version`, `features`, `inputSchema`, `models` from config or defaults
+ *
+ * @param registry - The handler registry to read DVM kinds from.
+ * @param config - Node configuration for pricing and optional overrides.
+ * @returns A SkillDescriptor, or undefined if no DVM handlers are registered.
+ */
+declare function buildSkillDescriptor(registry: HandlerRegistry, config?: BuildSkillDescriptorConfig): SkillDescriptor | undefined;
+
+/**
+ * createNode() composition for @toon-protocol/sdk.
+ *
+ * Wires the full ILP packet processing pipeline:
+ *   shallow TOON parse -> Schnorr signature verification -> pricing validation -> handler dispatch
+ *
+ * Provides start() / stop() lifecycle management by delegating to
+ * the core ToonNode composition (embedded mode) or manual HTTP
+ * composition (standalone mode).
+ *
+ * ## Deployment Modes
+ *
+ * - **Embedded** (`connector`): Pass an EmbeddableConnectorLike directly.
+ *   Zero-latency packet delivery via direct function calls.
+ * - **Standalone** (`connectorUrl` + `handlerPort`): Connect to an external
+ *   connector via HTTP. The SDK starts an HTTP server to receive packets.
+ */
+
+/**
+ * Configuration for creating a ServiceNode via createNode().
+ *
+ * Supports three deployment modes:
+ * - **Default** (no connector args): Auto-creates an embedded ConnectorNode via
+ *   dynamic import. Requires `@toon-protocol/connector` as peer dependency.
+ * - **Embedded** (`connector`): Pass a pre-configured EmbeddableConnectorLike.
+ * - **Standalone** (`connectorUrl` + `handlerPort`): Connect to an external
+ *   connector via HTTP. The SDK starts an HTTP server to receive packets.
+ *
+ * Provide `connector` OR (`connectorUrl` + `handlerPort`), or neither (auto-create).
+ */
+interface NodeConfig {
+    /** 32-byte secp256k1 secret key */
+    secretKey: Uint8Array;
+    /** Chain preset name (default: 'anvil'). See resolveChainConfig(). */
+    chain?: string;
+    /**
+     * Embedded connector instance for zero-latency mode.
+     * If neither `connector` nor `connectorUrl` is provided, an embedded
+     * ConnectorNode is auto-created (requires @toon-protocol/connector peer dep).
+     */
+    connector?: EmbeddableConnectorLike;
+    /**
+     * External connector admin URL for standalone mode (e.g., "http://localhost:8081").
+     * Must be provided with `handlerPort`.
+     */
+    connectorUrl?: string;
+    /**
+     * Port for the HTTP server that receives ILP packets from the external connector.
+     * Must be provided with `connectorUrl`.
+     */
+    handlerPort?: number;
+    /**
+     * BTP server port for the auto-created embedded connector (default: 3000).
+     * Only used when neither `connector` nor `connectorUrl` is provided.
+     */
+    btpServerPort?: number;
+    /**
+     * EVM private key for settlement infrastructure.
+     * Only used when auto-creating an embedded connector.
+     * If not set, the identity's secp256k1 key is used.
+     */
+    settlementPrivateKey?: string;
+    /**
+     * Upstream peer's ILP address prefix for address derivation.
+     * When set, the node derives its ILP address as
+     * `deriveChildAddress(upstreamPrefix, pubkey)` and ignores `ilpAddress`.
+     */
+    upstreamPrefix?: string;
+    /**
+     * Multiple upstream peer prefixes for multi-peered nodes (Story 7.3).
+     * When set, derives one ILP address per upstream prefix. Takes priority
+     * over `upstreamPrefix` (singular) when both are set.
+     */
+    upstreamPrefixes?: string[];
+    /** ILP address (default: derived from pubkey under ILP_ROOT_PREFIX) */
+    ilpAddress?: string;
+    /** BTP endpoint URL advertised in kind:10032 announcements */
+    btpEndpoint?: string;
+    /** Asset code (default: 'USD') */
+    assetCode?: string;
+    /** Asset scale (default: 6) */
+    assetScale?: number;
+    /**
+     * Base price per byte for pricing validation (default: 10n).
+     *
+     * Amounts are in USDC micro-units (6 decimals) for production.
+     * Default 10n = 10 micro-USDC per byte = $0.00001/byte.
+     * A 1KB event costs 10,240 micro-USDC = ~$0.01.
+     */
+    basePricePerByte?: bigint;
+    /**
+     * Routing fee per byte charged by this node as an intermediary (default: 0n = free routing).
+     * Advertised in kind:10032 peer info events as a non-negative integer string.
+     */
+    feePerByte?: bigint;
+    /** Dev mode skips signature verification (default: false) */
+    devMode?: boolean;
+    /** TOON encoder function */
+    toonEncoder?: (event: NostrEvent) => Uint8Array;
+    /** TOON decoder function */
+    toonDecoder?: (bytes: Uint8Array) => NostrEvent;
+    /** Initial known peers for bootstrap */
+    knownPeers?: KnownPeer[];
+    /** Relay WebSocket URL */
+    relayUrl?: string;
+    /** Settlement info for peer registration */
+    settlementInfo?: SettlementConfig;
+    /** Enable ArDrive peer lookup */
+    ardriveEnabled?: boolean;
+    /** Per-kind pricing overrides */
+    kindPricing?: Record<number, bigint>;
+    /**
+     * Multi-chain provider configuration for the embedded connector.
+     * When provided, passed directly to ConnectorNode as `chainProviders`.
+     * Takes priority over the legacy `settlementInfra` auto-configuration.
+     * 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.
+     * Only used when auto-creating an embedded connector.
+     */
+    nip59?: {
+        enabled: boolean;
+    };
+    /**
+     * Per-peer NIP-59 public keys for claim encryption.
+     * Map of peer ID to compressed secp256k1 public key (hex, 66 chars).
+     * Applied to peer configs when registering peers with the connector.
+     * Only used when auto-creating an embedded connector.
+     */
+    peerNip59PublicKeys?: Record<string, string>;
+    /** Config-based handler registration (alternative to post-creation .on()) */
+    handlers?: Record<number, Handler>;
+    /** Config-based default handler (alternative to post-creation .onDefault()) */
+    defaultHandler?: Handler;
+    /**
+     * Optional skill descriptor configuration overrides.
+     * When DVM handlers are registered, these values override the auto-derived
+     * defaults in the skill descriptor. See buildSkillDescriptor().
+     */
+    skillConfig?: Omit<BuildSkillDescriptorConfig, 'basePricePerByte' | 'kindPricing'>;
+}
+/**
+ * Result returned by ServiceNode.start().
+ */
+interface StartResult {
+    /** Number of peers successfully bootstrapped */
+    peerCount: number;
+    /** Number of payment channels opened */
+    channelCount: number;
+    /** Detailed results from the bootstrap phase */
+    bootstrapResults: BootstrapResult[];
+}
+/**
+ * Result returned by ServiceNode.publishEvent().
+ */
+interface PublishEventResult {
+    success: boolean;
+    eventId: string;
+    /** Response data from the ILP FULFILL packet (e.g., Arweave tx ID for kind:5094). */
+    data?: string;
+    code?: string;
+    message?: string;
+}
+/**
+ * A fully wired TOON node with lifecycle management.
+ */
+interface ServiceNode {
+    /** Nostr x-only public key (32 bytes, 64 hex chars) */
+    readonly pubkey: string;
+    /** EVM address derived from the same secp256k1 key */
+    readonly evmAddress: string;
+    /** Pass-through to the underlying connector (null in standalone mode) */
+    readonly connector: EmbeddableConnectorLike | null;
+    /** Channel client (null if connector lacks channel support or in standalone mode) */
+    readonly channelClient: ConnectorChannelClient | null;
+    /** Register a handler for a specific event kind (builder pattern) */
+    on(kind: number, handler: Handler): ServiceNode;
+    /** Register a lifecycle event listener */
+    on(event: 'bootstrap', listener: BootstrapEventListener): ServiceNode;
+    /** Register a default handler for unrecognized kinds (builder pattern) */
+    onDefault(handler: Handler): ServiceNode;
+    /** Start the node: wire packet handler, run bootstrap, start discovery */
+    start(): Promise<StartResult>;
+    /** Stop the node: clean up lifecycle state */
+    stop(): Promise<void>;
+    /** Initiate peering with a discovered peer (register + settlement) */
+    peerWith(pubkey: string): Promise<void>;
+    /**
+     * Publish a Nostr event to a remote peer via the embedded connector.
+     *
+     * TOON-encodes the event, computes payment amount, and sends as an
+     * ILP PREPARE packet via the runtime client.
+     *
+     * @param event - The Nostr event to publish
+     * @param options - Must include destination ILP address. Optional `amount`
+     *   overrides the default basePricePerByte * toonData.length calculation
+     *   (prepaid model: send exact destination amount). Optional `bid` is a
+     *   client-side safety cap: if the destination amount exceeds `bid`, the
+     *   SDK throws before sending any ILP packet.
+     * @returns Result with success/failure info and event ID
+     */
+    publishEvent(event: NostrEvent, options?: {
+        destination: string;
+        amount?: bigint;
+        bid?: bigint;
+    }): Promise<PublishEventResult>;
+    /**
+     * Publish a Kind 7000 DVM job feedback event via ILP PREPARE.
+     *
+     * Builds a signed Kind 7000 feedback event with NIP-90 tags (e, p, status)
+     * and delegates to publishEvent() for TOON encoding and ILP delivery.
+     * Standard relay write fee applies: basePricePerByte * toonData.length.
+     *
+     * @param requestEventId - 64-char hex event ID of the original Kind 5xxx request
+     * @param customerPubkey - 64-char hex pubkey of the customer who posted the request
+     * @param status - Job status value ('processing', 'error', 'success', 'partial')
+     * @param content - Optional status details or error message
+     * @param options - Must include destination ILP address
+     * @returns Result with success/failure info and event ID
+     */
+    publishFeedback(requestEventId: string, customerPubkey: string, status: DvmJobStatus, content?: string, options?: {
+        destination: string;
+    }): Promise<PublishEventResult>;
+    /**
+     * Publish a Kind 6xxx DVM job result event via ILP PREPARE.
+     *
+     * Builds a signed Kind 6xxx result event with NIP-90 tags (e, p, amount)
+     * and delegates to publishEvent() for TOON encoding and ILP delivery.
+     * Standard relay write fee applies: basePricePerByte * toonData.length.
+     *
+     * @param requestEventId - 64-char hex event ID of the original Kind 5xxx request
+     * @param customerPubkey - 64-char hex pubkey of the customer who posted the request
+     * @param amount - Compute cost in USDC micro-units as string
+     * @param content - Result data (text, URL, etc.)
+     * @param options - Must include destination; optional kind (default: 6100)
+     * @returns Result with success/failure info and event ID
+     */
+    publishResult(requestEventId: string, customerPubkey: string, amount: string, content: string, options?: {
+        destination: string;
+        kind?: number;
+    }): Promise<PublishEventResult>;
+    /**
+     * Returns the computed skill descriptor for this node's DVM capabilities.
+     * Returns `undefined` if no DVM handlers (kinds 5000-5999) are registered.
+     * The descriptor is computed from the handler registry and node config.
+     */
+    getSkillDescriptor(): SkillDescriptor | undefined;
+    /**
+     * Send an ILP payment to a provider for compute settlement.
+     *
+     * Extracts the compute cost from the result event's `amount` tag via
+     * parseJobResult(), optionally validates against the original bid amount
+     * (E5-R005 bid validation), and sends a pure ILP value transfer
+     * (empty data field) to the provider's ILP address.
+     *
+     * This is a payment-only operation -- no TOON encoding, no relay write.
+     * The payment routes through the ILP mesh using the same infrastructure
+     * as relay write fees.
+     *
+     * @deprecated Use publishEvent() with amount option instead. Prepaid model:
+     * send job request + payment in one packet via
+     * `publishEvent(event, { destination, amount: computePrice })`.
+     *
+     * @param resultEvent - Kind 6xxx result event with amount tag
+     * @param providerIlpAddress - Provider's ILP address from kind:10035
+     * @param options - Optional originalBid for bid validation (E5-R005)
+     * @returns ILP send result with accepted/rejected status
+     */
+    settleCompute(resultEvent: NostrEvent, providerIlpAddress: string, options?: {
+        originalBid?: string;
+    }): Promise<IlpSendResult>;
+    /**
+     * Add a new upstream peer, deriving and registering its ILP address.
+     *
+     * Updates the AddressRegistry, registers a self-route in the embedded
+     * connector, and triggers kind:10032 republication via BootstrapService.
+     *
+     * @param upstreamPrefix - The upstream peer's ILP address prefix
+     */
+    addUpstreamPeer(upstreamPrefix: string): void;
+    /**
+     * Remove an upstream peer, unregistering its derived ILP address.
+     *
+     * Updates the AddressRegistry, removes the self-route from the embedded
+     * connector, and triggers kind:10032 republication via BootstrapService.
+     *
+     * @param upstreamPrefix - The upstream prefix to remove
+     */
+    removeUpstreamPeer(upstreamPrefix: string): void;
+    /**
+     * Claim a prefix from an upstream peer by sending a prefix claim event
+     * with payment via ILP.
+     *
+     * Builds a Kind 10034 prefix claim event, reads the upstream's prefix
+     * pricing from its kind:10032 advertisement, and calls publishEvent()
+     * with the appropriate amount.
+     *
+     * @param prefix - The prefix string to claim (e.g., 'useast')
+     * @param upstreamDestination - ILP address of the upstream node
+     * @param options - Optional prefixPrice override (defaults to upstream's prefixPricing.basePrice from discovery)
+     * @returns Result with success/failure info and event ID
+     */
+    claimPrefix(prefix: string, upstreamDestination: string, options?: {
+        prefixPrice?: bigint;
+    }): Promise<PublishEventResult>;
+}
+/**
+ * Creates a fully wired ServiceNode from configuration.
+ *
+ * The returned node has the full ILP packet processing pipeline wired in the
+ * correct order:
+ *   1. Shallow TOON parse (extract routing metadata)
+ *   2. Schnorr signature verification (reject with F06 if invalid)
+ *   3. Pricing validation (reject with F04 if underpaid)
+ *   4. Handler dispatch (route to kind-specific or default handler)
+ *
+ * Supports two deployment modes:
+ * - **Embedded** (`connector`): Uses createToonNode for zero-latency
+ *   packet delivery via direct function calls.
+ * - **Standalone** (`connectorUrl` + `handlerPort`): Starts an HTTP server
+ *   to receive packets and uses HTTP clients for the connector API.
+ *
+ * Handlers can be registered via config or post-creation .on()/.onDefault().
+ */
+declare function createNode(config: NodeConfig): ServiceNode;
+
+/**
+ * Workflow Orchestrator for multi-step DVM pipelines (Story 6.1).
+ *
+ * Manages the lifecycle of a workflow chain: creates step job requests,
+ * detects step completion/failure, advances to the next step, handles
+ * timeouts, and settles compute payments per step.
+ *
+ * The orchestrator uses the TOON relay as the orchestration layer --
+ * there is no separate workflow engine. Step completion is detected
+ * via relay event subscriptions (Kind 6xxx results, Kind 7000 feedback).
+ *
+ * State machine states:
+ *   - `pending`: Workflow created but not yet started
+ *   - `step_N_running`: Step N's job request published, waiting for result
+ *   - `step_N_failed`: Step N failed (error or timeout), workflow aborted
+ *   - `completed`: All steps finished successfully
+ *
+ * Settlement: Each step settles individually via settleCompute().
+ * The orchestrator validates sum(step_amounts) <= total_bid before settlement.
+ *
+ * Forward-compatible with Epic 7 prepaid protocol: settlement logic is
+ * isolated in handleStepResult() so swapping to prepaid per-step payment
+ * requires changes only in that method.
+ */
+
+/**
+ * Workflow state type. Uses template literal types for step-indexed states.
+ * Note: Timeout is represented as `step_N_failed` (timeout is a failure mode,
+ * not a separate terminal state). The timeout cause is communicated in the
+ * customer notification content.
+ */
+type WorkflowState = 'pending' | `step_${number}_running` | `step_${number}_failed` | 'completed';
+/**
+ * Event store interface for workflow state persistence.
+ * Minimal interface -- only store() and query() are needed.
+ */
+interface WorkflowEventStore {
+    store(event: NostrEvent): Promise<void>;
+    query(filter: {
+        kinds?: number[];
+        '#e'?: string[];
+    }): Promise<NostrEvent[]>;
+}
+/**
+ * Configuration options for the WorkflowOrchestrator.
+ */
+interface WorkflowOrchestratorOptions {
+    /** Secret key for signing step job request events (32-byte Uint8Array). */
+    secretKey?: Uint8Array;
+    /** Per-step timeout in milliseconds (default: 300000 = 5 minutes). */
+    stepTimeoutMs?: number;
+    /** Injectable time source for deterministic testing. */
+    now?: () => number;
+    /**
+     * Injectable timer factory for deterministic testing.
+     * Defaults to global setTimeout. Inject a custom implementation
+     * to control timer advancement in tests without vi.useFakeTimers().
+     */
+    setTimer?: (callback: () => void, ms: number) => ReturnType<typeof setTimeout>;
+    /**
+     * Injectable timer cancellation for deterministic testing.
+     * Defaults to global clearTimeout. Must pair with setTimer.
+     */
+    clearTimer?: (handle: ReturnType<typeof setTimeout>) => void;
+    /** Optional event store for workflow state persistence. */
+    eventStore?: WorkflowEventStore;
+    /** Default destination ILP address for publishing events. */
+    destination?: string;
+    /** Workflow definition event ID (for referencing in notifications). */
+    workflowEventId?: string;
+    /** Customer pubkey (for directing notifications). */
+    customerPubkey?: string;
+}
+/**
+ * Per-step state tracking.
+ */
+interface StepState {
+    /** Index of this step (0-based). */
+    index: number;
+    /** The job request event ID published for this step. */
+    requestEventId?: string;
+    /** The result event received for this step. */
+    resultEvent?: NostrEvent;
+    /** Whether this step has been settled. */
+    settled: boolean;
+}
+/**
+ * Orchestrates a multi-step DVM workflow chain.
+ *
+ * Each instance manages a single workflow. For concurrent workflows,
+ * create multiple WorkflowOrchestrator instances sharing the same
+ * ServiceNode.
+ */
+declare class WorkflowOrchestrator {
+    private readonly node;
+    private readonly options;
+    private state;
+    private definition;
+    private workflowEventId;
+    private customerPubkey;
+    private currentStepIndex;
+    private stepStates;
+    private timeoutHandle;
+    private processedResultIds;
+    constructor(node: ServiceNode, options?: WorkflowOrchestratorOptions);
+    /**
+     * Returns the current workflow state.
+     */
+    getState(): WorkflowState;
+    /**
+     * Returns per-step state tracking data (for testing/debugging).
+     */
+    getStepStates(): readonly Readonly<StepState>[];
+    /**
+     * Starts a workflow: parses the definition, creates and publishes
+     * the Kind 5xxx job request for step 1, sets state to step_1_running.
+     */
+    startWorkflow(definition: ParsedWorkflowDefinition): Promise<void>;
+    /**
+     * Handles a Kind 6xxx result event for the current step.
+     *
+     * If the current step matches, extracts the result content and either:
+     * - Advances to the next step (publishes Kind 5xxx for step N+1)
+     * - Marks workflow as completed (if this was the final step)
+     *
+     * Idempotent: re-processing a result for an already-advanced step is a no-op.
+     */
+    handleStepResult(resultEvent: NostrEvent): Promise<void>;
+    /**
+     * Handles a Kind 7000 feedback event for the current step.
+     *
+     * If the feedback status is 'error', marks the workflow as failed
+     * and notifies the customer.
+     */
+    handleStepFeedback(feedbackEvent: NostrEvent): Promise<void>;
+    /**
+     * Cleans up resources (timeout handles).
+     */
+    destroy(): void;
+    /**
+     * Publishes a Kind 5xxx job request for the given step.
+     */
+    private publishStepRequest;
+    /**
+     * Settles compute payment for a completed step.
+     */
+    private settleStep;
+    /**
+     * Returns the bid allocation for a specific step.
+     * Uses explicit bidAllocation if set, otherwise proportional split.
+     */
+    private getStepBid;
+    /**
+     * Publishes a Kind 7000 workflow notification to the customer.
+     */
+    private publishWorkflowNotification;
+    /**
+     * Starts a timeout timer for the current step.
+     */
+    private startStepTimeout;
+    /**
+     * Returns the secret key for signing step events.
+     * Falls back to a deterministic key derived from the node pubkey
+     * (for testing -- production should always pass secretKey in options).
+     */
+    private getSecretKey;
+    /**
+     * Clears the current step timeout.
+     */
+    private clearStepTimeout;
+}
+
+/**
+ * Swarm Coordinator for competitive DVM bidding (Story 6.2).
+ *
+ * Manages the lifecycle of a competitive swarm: collects provider
+ * submissions, handles timeout-based judging deadlines, validates
+ * winner selection, and settles compute payment to the winner only.
+ *
+ * The coordinator uses the TOON relay as the orchestration layer --
+ * there is no separate swarm engine. Submission arrival is detected
+ * via relay event subscriptions (Kind 6xxx results).
+ *
+ * State machine states:
+ *   - `collecting`: Waiting for provider submissions (Kind 6xxx results)
+ *   - `judging`: Timeout or max submissions reached; customer selects winner
+ *   - `settled`: Winner paid via settleCompute(); swarm complete
+ *   - `failed`: No submissions within timeout or error
+ *
+ * Settlement: Only the winning provider receives compute payment.
+ * Losing providers paid relay write fees (sunk cost) but receive
+ * no compute payment -- this is by design to incentivize quality.
+ *
+ * Forward-compatible with Epic 7 prepaid protocol: settlement logic
+ * is isolated in selectWinner() so swapping to prepaid per-winner
+ * payment requires changes only in that method.
+ */
+
+/**
+ * Swarm state type.
+ * - `collecting`: Waiting for provider submissions.
+ * - `judging`: Timeout or max submissions reached; awaiting winner selection.
+ * - `settled`: Winner paid; swarm complete.
+ * - `failed`: No submissions within timeout or error.
+ */
+type SwarmState = 'collecting' | 'judging' | 'settled' | 'failed';
+/**
+ * Configuration options for the SwarmCoordinator.
+ */
+interface SwarmCoordinatorOptions {
+    /** Secret key for signing events (32-byte Uint8Array). */
+    secretKey?: Uint8Array;
+    /** Swarm collection timeout in milliseconds (default: 600000 = 10 minutes). */
+    timeoutMs?: number;
+    /** Injectable time source for deterministic testing. */
+    now?: () => number;
+    /**
+     * Injectable timer factory for deterministic testing.
+     * Defaults to global setTimeout. Inject a custom implementation
+     * to control timer advancement in tests without vi.useFakeTimers().
+     */
+    setTimer?: (callback: () => void, ms: number) => ReturnType<typeof setTimeout>;
+    /**
+     * Injectable timer cancellation for deterministic testing.
+     * Defaults to global clearTimeout. Must pair with setTimer.
+     */
+    clearTimer?: (handle: ReturnType<typeof setTimeout>) => void;
+    /** Optional event store for swarm state persistence. */
+    eventStore?: WorkflowEventStore;
+    /** Default destination ILP address for publishing events. */
+    destination?: string;
+}
+/**
+ * Coordinates a competitive DVM swarm.
+ *
+ * Each instance manages a single swarm. For concurrent swarms,
+ * create multiple SwarmCoordinator instances sharing the same
+ * ServiceNode.
+ */
+declare class SwarmCoordinator {
+    private readonly node;
+    private readonly options;
+    private state;
+    private swarmRequestId;
+    private customerPubkey;
+    private maxProviders;
+    private submissions;
+    private timeoutHandle;
+    private started;
+    private settlementSucceeded;
+    private submissionIds;
+    constructor(node: ServiceNode, options?: SwarmCoordinatorOptions);
+    /**
+     * Returns the current swarm state.
+     */
+    getState(): SwarmState;
+    /**
+     * Returns whether settlement was successfully completed.
+     * Only meaningful when state is 'settled' (returns true).
+     * If settlement fails, the state remains 'judging' and this returns false.
+     */
+    isSettlementSucceeded(): boolean;
+    /**
+     * Returns the collected eligible submissions.
+     */
+    getSubmissions(): readonly NostrEvent[];
+    /**
+     * Starts a swarm: parses the swarm request, initializes collection,
+     * and starts the timeout timer.
+     */
+    startSwarm(swarmRequest: NostrEvent): Promise<void>;
+    /**
+     * Handles a Kind 6xxx result event (provider submission).
+     *
+     * Validates the `e` tag references the swarm request, adds to the
+     * submissions list, and checks if max providers is reached.
+     *
+     * Late submissions (after timeout or max reached) are ignored.
+     * Submissions before startSwarm() are silently ignored.
+     */
+    handleSubmission(resultEvent: NostrEvent): Promise<void>;
+    /**
+     * Selects the winner and settles compute payment.
+     *
+     * Validates:
+     * - Swarm is in `judging` state (not `collecting`, `settled`, or `failed`)
+     * - Selection references a submission in the collected set
+     * - Swarm has not already been settled (idempotency guard)
+     *
+     * @throws ToonError with code DVM_SWARM_ALREADY_SETTLED if already settled
+     * @throws ToonError with code DVM_SWARM_INVALID_SELECTION if winner not in submissions
+     */
+    selectWinner(selectionEvent: NostrEvent): Promise<void>;
+    /**
+     * Cleans up resources (timeout handles).
+     */
+    destroy(): void;
+    /**
+     * Starts the collection timeout timer.
+     */
+    private startTimeout;
+    /**
+     * Publishes a Kind 7000 feedback event indicating no submissions were received.
+     */
+    private publishNoSubmissionsFeedback;
+    /**
+     * Clears the current timeout timer.
+     */
+    private clearTimeout;
+}
+
+/**
+ * Prefix claim handler for the TOON prefix marketplace.
+ *
+ * Creates a handler that processes kind 10034 prefix claim events,
+ * validates payment and prefix availability, and publishes grant
+ * confirmations. Lives in SDK (not core) because it depends on
+ * the SDK's Handler type and HandlerContext interface.
+ */
+
+/**
+ * Options for creating a prefix claim handler.
+ */
+interface PrefixClaimHandlerOptions {
+    /** Pricing configuration for prefix claims. */
+    prefixPricing: {
+        basePrice: bigint;
+    };
+    /** Secret key for signing grant events. */
+    secretKey: Uint8Array;
+    /** Returns the current map of claimed prefixes (prefix -> claimer pubkey). */
+    getClaimedPrefixes: () => Map<string, string>;
+    /**
+     * Atomically claim a prefix for a pubkey. Returns true if the claim
+     * succeeded, false if the prefix was already taken. This is the
+     * serialization point for race condition defense.
+     */
+    claimPrefix: (prefix: string, claimerPubkey: string) => boolean;
+    /** Publish the grant event (e.g., to the local relay). */
+    publishGrant: (grantEvent: NostrEvent) => Promise<void>;
+    /** ILP address prefix to include in the grant event (default: 'g.toon'). */
+    ilpAddressPrefix?: string;
+}
+/**
+ * Creates a handler for kind 10034 prefix claim events.
+ *
+ * The handler validates payment, prefix availability, and prefix format,
+ * then atomically claims the prefix and publishes a grant confirmation.
+ *
+ * @param options - Handler configuration
+ * @returns A Handler function for kind 10034 events
+ */
+declare function createPrefixClaimHandler(options: PrefixClaimHandlerOptions): Handler;
+
+/**
+ * Arweave upload adapter wrapping @ardrive/turbo-sdk.
+ *
+ * This is the ONLY file that imports @ardrive/turbo-sdk, isolating the
+ * external dependency behind an interface (risk E8-R002).
+ */
+/**
+ * Interface for uploading data to Arweave.
+ * Implementations wrap a specific Arweave upload SDK.
+ */
+interface ArweaveUploadAdapter {
+    upload(data: Buffer, tags?: Record<string, string>): Promise<{
+        txId: string;
+    }>;
+}
+/**
+ * Turbo SDK upload adapter using @ardrive/turbo-sdk.
+ *
+ * - 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 is duck-typed at runtime.
+ */
+declare class TurboUploadAdapter implements ArweaveUploadAdapter {
+    private turboClient;
+    private initialized;
+    constructor(turboClient?: unknown);
+    private getClient;
+    upload(data: Buffer, tags?: Record<string, string>): Promise<{
+        txId: string;
+    }>;
+}
+
+/**
+ * Chunk state manager for multi-packet blob uploads.
+ *
+ * Accumulates chunks for a given uploadId, assembles them in order
+ * when all chunks have arrived, and enforces timeout and memory caps.
+ */
+interface ChunkManagerConfig {
+    /** Timeout in milliseconds before partial uploads are discarded (default: 300_000 = 5 min). */
+    timeoutMs?: number;
+    /** Maximum number of concurrent active uploads (default: 100). */
+    maxActiveUploads?: number;
+    /** Maximum total bytes accumulated per upload before rejection (default: 50MB). */
+    maxBytesPerUpload?: number;
+}
+interface AddChunkResult {
+    /** Whether all chunks have been received and the blob is fully assembled. */
+    complete: boolean;
+    /** The assembled blob (only present when complete is true). */
+    assembled?: Buffer;
+    /** Error message if the chunk was rejected. */
+    error?: string;
+}
+/**
+ * Manages chunked upload state for the Arweave DVM handler.
+ */
+declare class ChunkManager {
+    private uploads;
+    private readonly timeoutMs;
+    private readonly maxActiveUploads;
+    private readonly maxBytesPerUpload;
+    constructor(config?: ChunkManagerConfig);
+    /**
+     * Add a chunk for a given uploadId.
+     *
+     * @param uploadId - Unique identifier for the upload session.
+     * @param chunkIndex - Zero-based index of this chunk.
+     * @param totalChunks - Total number of chunks expected.
+     * @param data - The chunk data.
+     * @returns Result indicating completion status or error.
+     * @throws Error if memory cap reached or duplicate chunk.
+     */
+    addChunk(uploadId: string, chunkIndex: number, totalChunks: number, data: Buffer): AddChunkResult;
+    /**
+     * Check if an upload is complete (all chunks received).
+     * Returns false if the uploadId is unknown (cleaned up or never started).
+     */
+    isComplete(uploadId: string): boolean;
+    /**
+     * Clean up state for a given uploadId, clearing the timeout timer.
+     */
+    cleanup(uploadId: string): void;
+    /**
+     * Clean up all active uploads and their timers.
+     * Call this on node shutdown to prevent timer leaks.
+     */
+    destroyAll(): void;
+}
+
+/**
+ * Arweave DVM handler for kind:5094 blob storage requests.
+ *
+ * Creates a handler function that:
+ * 1. Parses the kind:5094 event from the HandlerContext
+ * 2. For single-packet uploads: uploads directly to Arweave via the adapter
+ * 3. For chunked uploads: accumulates via ChunkManager, uploads on completion
+ *
+ * The handler does NOT validate pricing -- the SDK pricing validator
+ * (packages/sdk/src/pricing-validator.ts) runs BEFORE the handler is invoked.
+ *
+ * Returns HandlePacketAcceptResponse with `data` field containing the Arweave
+ * tx ID -- NOT via ctx.accept() which only supports metadata.
+ */
+
+interface ArweaveDvmConfig {
+    /** Arweave upload adapter (wraps @ardrive/turbo-sdk). */
+    turboAdapter: ArweaveUploadAdapter;
+    /** Chunk state manager for multi-packet uploads. */
+    chunkManager: ChunkManager;
+    /** Optional default Arweave data item tags (e.g., Content-Type). */
+    arweaveTags?: Record<string, string>;
+}
+/**
+ * Creates an Arweave DVM handler for kind:5094 blob storage requests.
+ *
+ * @param config - Handler configuration with adapter and chunk manager.
+ * @returns A handler function compatible with HandlerRegistry.on().
+ */
+declare function createArweaveDvmHandler(config: ArweaveDvmConfig): (ctx: HandlerContext) => Promise<HandlerResponse>;
+
+/**
+ * Client-side helpers for uploading blobs to an Arweave DVM provider.
+ *
+ * - uploadBlob(): single-packet upload for blobs under the chunk threshold
+ * - uploadBlobChunked(): multi-packet upload that splits large blobs into chunks
+ *
+ * Both use publishEvent() with the amount override (Story 7.6, D7-007).
+ */
+
+/**
+ * Minimal interface for publishing events. Matches ServiceNode.publishEvent().
+ */
+interface PublishableNode {
+    publishEvent(event: NostrEvent, options?: {
+        destination: string;
+        amount?: bigint;
+    }): Promise<Pick<PublishEventResult, 'success' | 'eventId' | 'data' | 'message'>>;
+}
+/**
+ * Options for single-packet blob upload.
+ */
+interface UploadBlobOptions {
+    /** MIME type of the blob (default: 'application/octet-stream'). */
+    contentType?: string;
+    /** Secret key for signing the event. */
+    secretKey: Uint8Array;
+    /** Price per byte in USDC micro-units for amount calculation. */
+    pricePerByte?: bigint;
+}
+/**
+ * Options for chunked blob upload.
+ */
+interface UploadBlobChunkedOptions {
+    /** Chunk size in bytes (default: 500_000, under 512KB threshold). */
+    chunkSize?: number;
+    /** MIME type of the blob (default: 'application/octet-stream'). */
+    contentType?: string;
+    /** Secret key for signing events. */
+    secretKey: Uint8Array;
+    /** Price per byte in USDC micro-units for amount calculation. */
+    pricePerByte?: bigint;
+}
+/**
+ * Upload a blob to an Arweave DVM provider in a single ILP packet.
+ *
+ * Uses publishEvent() with amount override (D7-007) to send the blob
+ * and payment in one ILP PREPARE.
+ *
+ * @param node - The ServiceNode (or compatible) to publish through.
+ * @param blob - The raw blob data to upload.
+ * @param destination - The provider's ILP address.
+ * @param options - Upload options including secretKey for signing.
+ * @returns The Arweave transaction ID from the FULFILL data field.
+ */
+declare function uploadBlob(node: PublishableNode, blob: Buffer, destination: string, options: UploadBlobOptions): Promise<string>;
+/**
+ * Upload a large blob to an Arweave DVM provider using chunked uploads.
+ *
+ * Splits the blob into chunks, each sent as a separate kind:5094 ILP PREPARE
+ * with uploadId, chunkIndex, and totalChunks params. Each chunk carries its
+ * own payment. The final chunk's FULFILL data contains the Arweave tx ID.
+ *
+ * @param node - The ServiceNode (or compatible) to publish through.
+ * @param blob - The raw blob data to upload.
+ * @param destination - The provider's ILP address.
+ * @param options - Chunked upload options including secretKey for signing.
+ * @returns The Arweave transaction ID from the final chunk's FULFILL data.
+ */
+declare function uploadBlobChunked(node: PublishableNode, blob: Buffer, destination: string, options: UploadBlobChunkedOptions): Promise<string>;
+
+/**
+ * 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 };