@toon-protocol/core 1.4.1 → 1.5.0

package/dist/index.d.ts

@@ -127,6 +127,7 @@ declare const PREFIX_GRANT_KIND = 10037;
  * The genesis node uses this directly -- it does not derive its address from a pubkey.
  * All other nodes derive addresses as children of their upstream peer's prefix.
  */
+declare const ILP_ROOT_PREFIX = "g.toon";
 /**
  * Blob Storage DVM kind (kind 5094).
  * Used for permanent blob storage requests (e.g., Arweave uploads).
@@ -163,7 +164,6 @@ declare const PET_INTERACTION_RESULT_KIND = 6900;
  * pipeline after ZK proof generation.
  */
 declare const PET_INTERACTION_EVENT_KIND = 14919;
-declare const ILP_ROOT_PREFIX = "g.toon";
 
 /**
  * Shared ILP address validation utilities.
@@ -430,8 +430,29 @@ interface IlpPeerInfo {
     ilpAddress: string;
     /** All ILP addresses of this peer (one per upstream peering). When absent (pre-Epic-7 events), consumers should default to [ilpAddress]. */
     ilpAddresses?: string[];
-    /** BTP WebSocket endpoint URL for packet exchange */
+    /** BTP WebSocket endpoint URL for packet exchange (pay-per-event writes) */
     btpEndpoint: string;
+    /**
+     * ILP-over-HTTP endpoint URL (RFC-0035) for stateless, one-shot writes:
+     * `POST` an ILP PREPARE here and receive a FULFILL/REJECT body. Suited to
+     * pure consumers, browsers, and NAT'd agents that don't need a duplex BTP
+     * session. Absent when the node only exposes BTP. The same host typically
+     * also accepts an HTTP `Upgrade` to BTP — see {@link supportsUpgrade}.
+     */
+    httpEndpoint?: string;
+    /**
+     * Whether `httpEndpoint`'s host accepts an HTTP `Upgrade` to a BTP/WebSocket
+     * session (`Sec-WebSocket-Protocol: btp`). Lets a client start on
+     * ILP-over-HTTP and upgrade to duplex BTP when it becomes a peer or needs
+     * server-initiated packets, carrying its HTTP-proven identity across.
+     */
+    supportsUpgrade?: boolean;
+    /**
+     * Public Nostr relay WebSocket URL for FREE reads (e.g. `wss://<addr>.anyone/`
+     * or `ws://host:7100`). Lets a client discover where to subscribe/read without
+     * out-of-band config. Absent when the relay isn't publicly exposed.
+     */
+    relayUrl?: string;
     /** Optional BLS HTTP endpoint for direct packet delivery (bootstrap only) */
     blsHttpEndpoint?: string;
     /** @deprecated Use supportedChains instead. Kept for backward compatibility. */
@@ -454,6 +475,36 @@ interface IlpPeerInfo {
     prefixPricing?: {
         basePrice: string;
     };
+    /** Token pairs this peer can swap, with current rates. Absent = no swap support. */
+    swapPairs?: SwapPair[];
+}
+/**
+ * Declarative advertisement of a token swap pair supported by a swap-capable peer (Mill).
+ *
+ * Source and target assets use the same `{blockchain}:{network}[:{chainId}]` chain format
+ * as `IlpPeerInfo.supportedChains`. Rate is serialized as a decimal string (not a float) to
+ * preserve arbitrary precision — D12-006. Min/max amounts are source-asset micro-unit integer
+ * strings that may exceed `Number.MAX_SAFE_INTEGER`; compare via `BigInt`.
+ */
+interface SwapPair {
+    /** Source asset */
+    from: {
+        assetCode: string;
+        assetScale: number;
+        chain: string;
+    };
+    /** Target asset */
+    to: {
+        assetCode: string;
+        assetScale: number;
+        chain: string;
+    };
+    /** Exchange rate as decimal string (target units per source unit) */
+    rate: string;
+    /** Minimum swap amount per packet in source asset micro-units (optional) */
+    minAmount?: string;
+    /** Maximum swap amount per packet in source asset micro-units (optional) */
+    maxAmount?: string;
 }
 /**
  * Subscription handle for real-time event updates.
@@ -490,6 +541,14 @@ interface OpenChannelResult {
     channelId: string;
     /** Channel status after open request */
     status: string;
+    /**
+     * On-chain channel `depositTotal` (base units), read at open time. Only
+     * surfaced by the Mina opener: the Mina balance-proof signer must bind
+     * `balanceB = depositTotal − balanceA` so the on-chain `claimFromChannel`
+     * signatureA check passes (toon-protocol/connector#133). Left undefined by the
+     * EVM and Solana openers, which do not need it.
+     */
+    depositTotal?: bigint;
 }
 /**
  * State of a payment channel from the connector.
@@ -532,9 +591,12 @@ interface ConnectorChannelClient {
 }
 
 /**
- * Parsers for ILP-related Nostr events.
+ * Chain identifier validation.
+ *
+ * Shared helper used by `parseIlpPeerInfo` and `swap-pair-validation` to avoid
+ * a circular import between `events/parsers.ts` and `events/swap-pair-validation.ts`
+ * (Story 12.1 Task 2.2 fallback).
  */
-
 /**
  * Validates a chain identifier string.
  * Valid format: {blockchain}:{network} or {blockchain}:{network}:{chainId}
@@ -544,12 +606,20 @@ interface ConnectorChannelClient {
  * @returns true if the chain identifier is valid
  */
 declare function validateChainId(chainId: string): boolean;
+
+/**
+ * Parsers for ILP-related Nostr events.
+ */
+
 /**
  * Parses a kind:10032 Nostr event into an IlpPeerInfo object.
  *
  * @param event - The Nostr event to parse
  * @returns The parsed IlpPeerInfo object
- * @throws InvalidEventError if the event is malformed or missing required fields
+ * @throws {InvalidEventError} if the event is malformed or missing required fields.
+ *   This includes: malformed JSON, invalid required fields, invalid `feePerByte`,
+ *   invalid `prefixPricing`, invalid `ilpAddresses`, `swapPairs` not being an array,
+ *   or any `SwapPair` element failing structural validation (Story 12.1 AC-5).
  */
 declare function parseIlpPeerInfo(event: NostrEvent): IlpPeerInfo;
 
@@ -557,6 +627,16 @@ declare function parseIlpPeerInfo(event: NostrEvent): IlpPeerInfo;
  * Builders for ILP-related Nostr events.
  */
 
+/** Options controlling how a kind:10032 announcement event is built. */
+interface BuildIlpPeerInfoOptions {
+    /**
+     * NIP-40 time-to-live, in seconds. When set to a positive value, the event
+     * carries an `["expiration", created_at + ttlSeconds]` tag so a stale
+     * announcement from an offline apex expires instead of lingering forever
+     * (issue #261). Omit (or pass a non-positive value) for a non-expiring event.
+     */
+    ttlSeconds?: number;
+}
 /**
  * Builds and signs a kind:10032 Nostr event from IlpPeerInfo data.
  *
@@ -566,13 +646,49 @@ declare function parseIlpPeerInfo(event: NostrEvent): IlpPeerInfo;
  *
  * @param info - The ILP peer info to serialize into the event
  * @param secretKey - The secret key to sign the event with
+ * @param options - Optional build options (e.g. a NIP-40 `ttlSeconds`)
  * @returns A signed Nostr event
  *
  * @throws {ToonError} With code `INVALID_FEE` if `feePerByte` is not a non-negative integer string
  * @throws {ToonError} With code `ADDRESS_EMPTY_ADDRESSES` if `ilpAddresses` is an empty array
  * @throws {ToonError} With code `ADDRESS_INVALID_PREFIX` if any element of `ilpAddresses` is invalid
+ * @throws {ToonError} With code `INVALID_SWAP_PAIR` if any element of `swapPairs` is structurally invalid
+ */
+declare function buildIlpPeerInfoEvent(info: IlpPeerInfo, secretKey: Uint8Array, options?: BuildIlpPeerInfoOptions): NostrEvent;
+
+/**
+ * NIP-40 expiration-timestamp helpers.
+ *
+ * A kind:10032 announcement (`ILP_PEER_INFO_KIND`) is a replaceable event: a
+ * relay keeps only the latest per author, so a stale announcement from an apex
+ * that has since gone offline lingers forever and clients faithfully dial its
+ * dead BTP endpoint (issue #261). Stamping the announcement with a NIP-40
+ * `["expiration", <unix-seconds>]` tag turns it into a liveness signal: a live
+ * apex re-publishes before the tag elapses, and once it stops, NIP-40-aware
+ * relays drop the event and discovery skips it.
+ */
+
+/** Tag name carrying the NIP-40 expiration timestamp (unix seconds). */
+declare const EXPIRATION_TAG = "expiration";
+/**
+ * Read the NIP-40 expiration timestamp (unix seconds) from an event's tags.
+ *
+ * @returns The timestamp, or `undefined` when the event carries no valid
+ *   `expiration` tag (no tag, non-numeric, or negative value).
+ */
+declare function getEventExpiration(event: NostrEvent): number | undefined;
+/**
+ * Whether an event has expired per its NIP-40 `expiration` tag.
+ *
+ * Events with no (or malformed) expiration tag never expire — they return
+ * `false`, preserving backward compatibility with announcements published
+ * before TTLs existed.
+ *
+ * @param event - The event to test.
+ * @param nowSeconds - Reference time in unix seconds (defaults to now).
+ *   Injectable for deterministic tests.
  */
-declare function buildIlpPeerInfoEvent(info: IlpPeerInfo, secretKey: Uint8Array): NostrEvent;
+declare function isEventExpired(event: NostrEvent, nowSeconds?: number): boolean;
 
 /**
  * Event builder and parser for kind:10036 Seed Relay List events.
@@ -2353,6 +2469,162 @@ declare function negotiateSettlementChain(requesterChains: string[], responderCh
  */
 declare function resolveTokenForChain(chain: string, requesterPreferredTokens?: Record<string, string>, responderPreferredTokens?: Record<string, string>): string | undefined;
 
+/**
+ * Shared balance-proof hash helpers — the single source of truth for the
+ * byte/field layout that ALL signers and verifiers across the monorepo depend
+ * on:
+ *  - the Mill-side signer (`packages/mill/src/payment-channel-signer.ts`)
+ *  - the sender-side settlement verifier (`packages/sdk/src/settlement/{evm,solana,mina}.ts`)
+ *  - the client-side balance-proof signers (`packages/client/src/signing/{solana,mina}-signer.ts`)
+ *
+ * Originally extracted from the Mill signer (Story 12.4) into `@toon-protocol/sdk`
+ * (Story 12.6 AC-6). Relocated here to `@toon-protocol/core` so the client can
+ * consume the canonical hashes WITHOUT taking a dependency on `@toon-protocol/sdk`
+ * (the client only depends on core). `@toon-protocol/sdk` re-exports these names
+ * unchanged, so Mill and existing SDK consumers are unaffected.
+ *
+ * Any change to a hash layout here automatically applies to every signer AND
+ * verifier — they cannot drift.
+ *
+ * @module
+ */
+/**
+ * Convert a hex string (with or without `0x` prefix) to bytes. Rejects
+ * odd-length and non-hex input.
+ */
+declare function hexToBytes(hex: string): Uint8Array;
+/**
+ * Encode a non-negative bigint as 32-byte big-endian. Throws if negative or
+ * exceeds 256 bits.
+ */
+declare function bigintToBytes32BE(x: bigint): Uint8Array;
+/**
+ * Concat N Uint8Arrays into one new Uint8Array.
+ */
+declare function concatBytes(...parts: Uint8Array[]): Uint8Array;
+/**
+ * Compute the EVM balance-proof message hash:
+ *   keccak256(channelId || cumulativeAmount(32BE) || nonce(32BE) || recipient)
+ *
+ * `channelIdBytes` MUST be 32 bytes. `recipientBytes` MUST be 20 bytes.
+ * This hash is what `EvmPaymentChannelSigner.signBalanceProof` signs and
+ * what `recoverEvmSignerAddress` recovers against.
+ *
+ * @stable — signer and verifier depend on the exact byte layout.
+ */
+declare function balanceProofHashEvm(channelIdBytes: Uint8Array, cumulativeAmount: bigint, nonce: bigint, recipientBytes: Uint8Array): Uint8Array;
+/**
+ * Compute the Solana balance-proof message hash:
+ *   sha256(utf8(channelId) || cumulativeAmount(32BE) || nonce(32BE) || utf8(recipient))
+ *
+ * `channelId` and `recipient` are base58-encoded strings (ASCII-subset of
+ * UTF-8). This hash is what `SolanaPaymentChannelSigner.signBalanceProof`
+ * signs and what `verifyEd25519Signature` verifies against.
+ *
+ * @stable — signer and verifier depend on the exact byte layout.
+ */
+declare function balanceProofHashSolana(channelId: string, cumulativeAmount: bigint, nonce: bigint, recipient: string): Uint8Array;
+/**
+ * Hash an arbitrary string to a Pallas-field-safe bigint.
+ *
+ * The Pallas base field order is slightly below 2^254, so we take the first
+ * 240 bits (60 hex chars / 30 bytes) of `sha256(utf8(s))` as a conservative,
+ * guaranteed-in-field representation. Used to fold the variable-length
+ * `channelId` / `recipient` strings into the fixed field-element array a Mina
+ * Schnorr signature is computed over.
+ *
+ * @stable — Mill signer and SDK verifier depend on the exact derivation.
+ */
+declare function minaHashToField(s: string): bigint;
+/**
+ * Compute the Mina balance-proof field-element message:
+ *   [ minaHashToField(channelId),
+ *     cumulativeAmount,
+ *     nonce,
+ *     minaHashToField(recipient) ]
+ *
+ * This is the EXACT `fields` array that the Mill's `MinaPaymentChannelSigner`
+ * passes to `mina-signer`'s `signFields(...)`, and that the sender-side
+ * `verifyMinaSignature` re-derives and passes to `verifyFields(...)`. Keeping
+ * the derivation here (shared across `@toon-protocol/mill`, `@toon-protocol/sdk`,
+ * and `@toon-protocol/client`) prevents signer/verifier drift — mirroring the
+ * EVM/Solana hash helpers above.
+ *
+ * NOTE: this is the Mill↔sender wire contract (a Schnorr signature over four
+ * field elements), NOT the connector's on-chain `MinaPaymentChannelSDK`
+ * Poseidon-commitment proof shape. The two are distinct; see
+ * `packages/sdk/src/settlement/mina.ts` for the relationship + the
+ * remaining on-chain-settlement gap.
+ *
+ * @stable — Mill signer and SDK verifier depend on the exact byte layout.
+ */
+declare function balanceProofFieldsMina(channelId: string, cumulativeAmount: bigint, nonce: bigint, recipient: string): bigint[];
+
+/**
+ * Base58 (Bitcoin/Solana alphabet) encode/decode.
+ *
+ * Identical implementation to `@toon-protocol/sdk`'s `identity.ts` helpers —
+ * relocated/duplicated here so `@toon-protocol/core` (and its `client`
+ * consumer) can base58-encode Solana addresses and the Mina base58check
+ * private-key format without depending on the SDK.
+ *
+ * @module
+ */
+/**
+ * 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;
+
+/**
+ * Mina private-key format conversion.
+ *
+ * `deriveFullIdentity()` / `deriveMillKeys()` emit a Mina Pallas scalar as a
+ * big-endian hex string, but `mina-signer`'s `signFields`/`derivePublicKey`
+ * require the Mina base58check (`EK…`) private-key format. This helper bridges
+ * the two so a hex-derived Mina key produces signatures verifiable by the
+ * sender-side `verifyMinaSignature`.
+ *
+ * Mirrors `hexToMinaBase58PrivateKey` in `packages/mill/src/payment-channel-signer.ts`
+ * (same fixed Mina base58check wire standard — version byte `0x5a`, non-zero
+ * tag `0x01`, little-endian scalar, double-sha256 checksum).
+ *
+ * @module
+ */
+/**
+ * Convert a big-endian 32-byte hex scalar (the form `deriveFullIdentity()`
+ * emits for Mina) into the Mina base58check private-key string mina-signer's
+ * `signFields`/`derivePublicKey` require. If the input already looks like a
+ * base58 `EK…` key it is returned unchanged.
+ *
+ * Layout (pre-checksum): `[0x5a, 0x01, <scalar bytes little-endian>]`, then
+ * append the first 4 bytes of `sha256(sha256(payload))` and base58-encode.
+ */
+declare function hexToMinaBase58PrivateKey(privateKey: string): string;
+/**
+ * Derive the Mina base58 (`B62…`) public key for a private-key scalar, using
+ * the optional `mina-signer` peer dep.
+ *
+ * `deriveFullIdentity()` / `deriveMillKeys()` emit only a keccak **hex
+ * placeholder** for the Mina public key — they deliberately avoid pulling
+ * Pallas curve math into derivation. That placeholder is unfundable and is
+ * rejected by Mina GraphQL balance queries, so wallet views that display it
+ * (e.g. the townhouse `/wallet/balances` mill Mina leg) show an unusable hex
+ * string. This resolves the real, fundable `B62…` address when `mina-signer`
+ * is installed.
+ *
+ * Returns `null` (not a throw) when `mina-signer` is absent — a missing
+ * optional peer dep is not an error; callers fall back to the hex placeholder.
+ * The B62 encoding is network-agnostic, so the chosen `network` is irrelevant.
+ *
+ * @param privateKey big-endian hex scalar (as derivation emits) or an
+ *   already-base58 `EK…` Mina private key.
+ */
+declare function deriveMinaPublicKeyBase58(privateKey: string): Promise<string | null>;
+
 /**
  * Bootstrap service for peer discovery and network initialization.
  *
@@ -3270,6 +3542,47 @@ interface ToonNode {
  */
 declare function createToonNode(config: ToonNodeConfig): ToonNode;
 
+/**
+ * ILP wire-code → connector semantic-reason translation.
+ *
+ * Connector v3.3.2 introduced the contract: its payment-handler adapter
+ * (`payment-handler.js`'s `mapRejectCode()`) takes a SEMANTIC reason key
+ * (e.g. `'internal_error'`) and looks it up in `REJECT_CODE_MAP` to produce
+ * the wire code (`'T00'`). If a caller passes a raw wire code (`'T00'`) it
+ * is not a key in the map, so the connector falls back to the generic
+ * `'F99'` code — collapsing every reject reason regardless of its true
+ * cause.
+ *
+ * The TOON SDK / handlers express rejections via `ctx.reject(ilpCode, msg)`
+ * using ILP wire codes (T00, F00, F02, F03, F04, F06, T04, R00, ...). This
+ * helper inverts the connector's `REJECT_CODE_MAP` so callers can translate
+ * back to the semantic key the connector now expects.
+ *
+ * Source of truth for the connector's accepted keys:
+ *   `@toon-protocol/connector` v3.3.3 — `core/payment-handler.ts`'s
+ *   `REJECT_CODE_MAP` and the `AcceptedSemanticCode` literal-union it
+ *   `satisfies`. v3.3.3 added `unreachable` (F02) and
+ *   `insufficient_destination_amount` (F04). The `satisfies` constraint
+ *   structurally prevents drift between the published vocabulary and the
+ *   wire-code mapping.
+ */
+/**
+ * Inverse of the connector's `REJECT_CODE_MAP`.
+ *
+ * Maps every ILP wire code the SDK currently emits to a semantic reason
+ * the connector recognises. Codes outside this set fall back to
+ * `'invalid_request'` (`'F00'`) so we still produce a meaningful,
+ * non-`F99` wire code at the far side.
+ */
+declare const ILP_TO_SEMANTIC: Readonly<Record<string, string>>;
+/**
+ * Translate an ILP wire code (T00, F00, ...) to the semantic reason the
+ * connector's `mapRejectCode()` expects. Falls back to `'invalid_request'`
+ * for unknown codes — yields `'F00'` at the wire instead of the generic
+ * `'F99'`.
+ */
+declare function ilpCodeToSemantic(ilpCode: string): string;
+
 /**
  * Mock USDC token configuration for local development (Anvil).
  *
@@ -3360,8 +3673,13 @@ declare const MOCK_USDC_CONFIG: MockUsdcConfig;
 type ChainType = 'evm' | 'solana' | 'mina';
 /**
  * Supported EVM chain preset names (backward-compatible).
+ *
+ * `anvil` is the local-dev chain. `arbitrum-*` and `base-*` are the public
+ * Arbitrum and Base networks used by the network-mode resolver
+ * (see network-profile.ts). Base is the primary EVM chain for single-EVM
+ * nodes; the apex connector and Mill can hold providers for both families.
  */
-type ChainName = 'anvil' | 'arbitrum-sepolia' | 'arbitrum-one';
+type ChainName = 'anvil' | 'arbitrum-sepolia' | 'arbitrum-one' | 'base-sepolia' | 'base-mainnet';
 /**
  * Supported Solana chain preset names.
  */
@@ -3434,6 +3752,21 @@ interface EVMProviderConfigEntry {
     rpcUrl: string;
     registryAddress: string;
     keyId: string;
+    tokenAddress: string;
+    privateKey?: string;
+    /**
+     * Settlement tuning knobs. The connector reads its GLOBAL settlement
+     * threshold from the first EVM provider carrying `settlementOptions` and
+     * applies that single `threshold` across all chains (EVM/Solana/Mina).
+     * Mirrors the connector's `EVMProviderConfig.settlementOptions` so a custom
+     * provider entry can pass it straight through.
+     */
+    settlementOptions?: {
+        threshold?: string;
+        settlementTimeoutSecs?: number;
+        initialDepositMultiplier?: number;
+        pollingIntervalMs?: number;
+    };
 }
 /**
  * Solana-specific provider configuration entry.
@@ -3576,6 +3909,173 @@ declare function buildSolanaProviderEntry(config: SolanaChainPreset, keyId: stri
  */
 declare function buildMinaProviderEntry(config: MinaChainPreset, keyId?: string): MinaProviderConfigEntry;
 
+/**
+ * Network-mode resolution for the Townhouse `network` flag.
+ *
+ * A single operator-facing selector — `mainnet | testnet | devnet | custom` —
+ * resolves a coherent multi-chain configuration that is consumed by BOTH:
+ * (`custom` additionally accepts operator RPC URLs via `--evm-url`/`--sol-url`
+ * to point at the project's dev chains — e.g. the Akash-hosted anvil + solana.)
+ *
+ * - the **apex** standalone connector (its `chainProviders` settlement array), and
+ * - the **children** node containers (town/mill), via a small set of env vars the
+ *   HS compose template interpolates (`EVM_CHAIN`, `EVM_RPC_URL`, `EVM_CHAIN_ID`,
+ *   `EVM_USDC_ADDRESS`, `SOLANA_RPC_URL`, `SOLANA_USDC_MINT`).
+ *
+ * Design notes:
+ * - **All tiers are public.** No tier resolves to a local chain (anvil/lightnet),
+ *   so a node never points at an unreachable `localhost` RPC. This is what fixes
+ *   the "JsonRpcProvider failed to detect network" boot-loop that left town nodes
+ *   permanently disconnected (an empty RPC fell back to the `anvil` preset whose
+ *   `localhost:8545` does not exist in the HS network).
+ * - **EVM = Base (primary) + Arbitrum.** The single-EVM town node uses Base; the
+ *   apex connector and Mill can hold providers for both families.
+ * - **Settlement status.** TOON's settlement contracts are deployed for the
+ *   public **testnet/devnet** tiers (EVM Base Sepolia registry + TokenNetwork,
+ *   Solana devnet program, Mina devnet zkApp — source of truth: e2e/testnets.json),
+ *   so those families resolve `configured` and the apex builds real
+ *   `chainProviders` for them. **Mainnet remains unconfigured** (contracts not
+ *   deployed there yet) → relay-only. The resolver only builds a connector
+ *   `chainProviders` entry for a family once its on-chain addresses are present.
+ *   No addresses are invented; filling the remaining (mainnet) presets later
+ *   requires no change here. The deployed testnet/devnet addresses are
+ *   maintained in sync with e2e/testnets.json (the one-time public deploy).
+ *
+ * The low-level local `solana-devnet` / `mina-devnet` presets in chain-config.ts
+ * (used by the dev/e2e stack) are intentionally NOT reused — this module defines
+ * the public Solana/Mina endpoints itself.
+ *
+ * @module
+ */
+
+/** Operator-facing network selector. */
+type NetworkMode = 'mainnet' | 'testnet' | 'devnet' | 'custom';
+/** The three preset-derivable public tiers (everything except custom). */
+type DerivableTier = Exclude<NetworkMode, 'custom'>;
+/**
+ * Operator-supplied RPC URLs for `network: 'custom'`
+ * (`--evm-url` / `--sol-url`). Use this to point the apex + nodes at the
+ * project's dev chains hosted anywhere — e.g. the anvil + solana that
+ * scripts/akash-deploy.sh deploys to Akash (whose ingress hostnames rotate per
+ * redeploy, so the operator passes the current URLs). The EVM chain is assumed
+ * to be the chain-id 31338 `akash-anvil` deploy (deterministic TOON settlement
+ * contracts → settlement-complete); Solana is RPC + Mock-USDC (relay-only, no
+ * program). For arbitrary real chains with their own contracts, use the full
+ * `customProviders` (chains editor) path instead.
+ */
+interface CustomEndpoints {
+    /** EVM JSON-RPC URL (the project's anvil deploy). */
+    evmUrl?: string;
+    /** Solana JSON-RPC URL. */
+    solUrl?: string;
+}
+/** Per-family settlement readiness, for honest UX. */
+interface NetworkFamilyStatus {
+    /** `configured` once the family has on-chain settlement addresses for this tier. */
+    evm: 'configured' | 'unconfigured';
+    solana: 'configured' | 'unconfigured';
+    mina: 'configured' | 'unconfigured';
+}
+/**
+ * Env vars the HS compose template interpolates into the node containers.
+ * Only keys with real values are present (absent ⇒ compose `${VAR:-}` default).
+ */
+interface NetworkNodeEnv {
+    /** Primary EVM chain preset name → town `TOON_CHAIN` (`'none'` ⇒ relay-only). */
+    EVM_CHAIN?: string;
+    EVM_RPC_URL?: string;
+    EVM_CHAIN_ID?: string;
+    EVM_USDC_ADDRESS?: string;
+    SOLANA_RPC_URL?: string;
+    SOLANA_USDC_MINT?: string;
+    /** Solana payment-channel program id (filled per-deploy; empty in presets). */
+    SOLANA_PROGRAM_ID?: string;
+    /** Mina payment-channel zkApp address (filled per-deploy; empty in presets). */
+    MINA_ZKAPP_ADDRESS?: string;
+}
+/** Resolved network configuration for apex + children. */
+interface NetworkProfile {
+    network: NetworkMode;
+    /**
+     * Connector `chainProviders` for the apex. Contains only settlement-complete
+     * families (omitted when on-chain addresses are absent — the caller falls back
+     * to its own default in that case).
+     */
+    chainProviders: ChainProviderConfigEntry[];
+    /** Env overlay for the node containers. */
+    nodeEnv: NetworkNodeEnv;
+    /** Per-family settlement readiness. */
+    status: NetworkFamilyStatus;
+}
+/** Sentinel for the town node meaning "no EVM settlement chain — run relay-only". */
+declare const RELAY_ONLY_CHAIN = "none";
+/**
+ * Resolve a {@link NetworkProfile} from a network mode.
+ *
+ * @param network - The operator-selected network mode.
+ * @param opts.keyId - Settlement signing key for connector `chainProviders`
+ *   entries. Required to emit settlement-complete providers; omit for the common
+ *   relay-only case (no providers are built without it).
+ * @param opts.customProviders - For `network: 'custom'`, the operator-supplied
+ *   `chainProviders` to pass through verbatim (and to derive node env from).
+ * @param opts.endpoints - For `network: 'custom'`, operator-supplied RPC URLs
+ *   (`--evm-url` / `--sol-url`) pointing at the project's dev chains. Used when
+ *   `customProviders` is empty (the lightweight URL-only path).
+ */
+declare function resolveNetworkProfile(network: NetworkMode, opts?: {
+    keyId?: string;
+    customProviders?: ChainProviderConfigEntry[];
+    endpoints?: CustomEndpoints;
+}): NetworkProfile;
+/**
+ * Client-facing per-chain settlement presets resolved from a network mode.
+ *
+ * Where {@link NetworkProfile} targets the apex connector + node containers
+ * (env overlay + `chainProviders`), this targets the @toon-protocol/client
+ * `ToonClientConfig` shape: identifier-keyed maps (`evm:<name>:<chainId>`,
+ * `solana:<cluster>`, `mina:<network>`) plus the Solana/Mina channel params.
+ * It draws from the SAME presets (`CHAIN_PRESETS`, `SOLANA_TIER`, `MINA_TIER`),
+ * so node and client default to the identical live contracts — no duplicated
+ * address tables in the client package.
+ *
+ * Only `mainnet | testnet | devnet` are resolvable here; `custom` is the
+ * client's fully-manual path and is intentionally not handled.
+ */
+interface ClientNetworkPresets {
+    /** Chain identifiers (`evm:base:84532`, `solana:devnet`, `mina:devnet`). */
+    supportedChains: string[];
+    /** identifier → JSON-RPC / GraphQL URL. */
+    chainRpcUrls: Record<string, string>;
+    /** identifier → preferred token (USDC / SPL mint) address. */
+    preferredTokens: Record<string, string>;
+    /** identifier → EVM TokenNetwork contract address (EVM only). */
+    tokenNetworks: Record<string, string>;
+    /** Solana channel params (rpcUrl + programId + tokenMint), if deployed. */
+    solanaChannel?: {
+        rpcUrl: string;
+        programId: string;
+        tokenMint?: string;
+    };
+    /** Mina channel params (graphqlUrl + zkAppAddress + networkId), if deployed. */
+    minaChannel?: {
+        graphqlUrl: string;
+        zkAppAddress: string;
+        networkId: 'devnet' | 'mainnet';
+    };
+    /** Per-family settlement readiness (mirrors the node). */
+    status: NetworkFamilyStatus;
+}
+/**
+ * Resolve {@link ClientNetworkPresets} for a derivable network tier.
+ *
+ * Mirrors {@link resolveNetworkProfile}'s address sourcing but emits the
+ * client config shape. The EVM family is the tier's primary chain (Base);
+ * Solana/Mina are the public tier endpoints. Only families with deployed TOON
+ * contracts contribute settlement maps + channel params (others stay relay-only
+ * and are reported `unconfigured`).
+ */
+declare function resolveClientNetwork(network: DerivableTier): ClientNetworkPresets;
+
 /**
  * Shared ILP PREPARE packet construction for the TOON protocol.
  *
@@ -4024,4 +4524,4 @@ declare function createLogger(config: LoggerConfig): Logger;
  */
 declare const VERSION = "0.1.0";
 
-export { AddressRegistry, type AgentRuntimeClient, ArDrivePeerRegistry, AttestationBootstrap, type AttestationBootstrapConfig, type AttestationBootstrapEvent, type AttestationBootstrapEventListener, type AttestationBootstrapResult, type AttestationEventOptions, AttestationState, AttestationVerifier, type AttestationVerifierConfig, type AttestedResultVerificationOptions, type AttestedResultVerificationResult, AttestedResultVerifier, BLOB_STORAGE_REQUEST_KIND, BLOB_STORAGE_RESULT_KIND, type BlobStorageRequestParams, type BootstrapConfig, BootstrapError, type BootstrapEvent, type BootstrapEventListener, type BootstrapPhase, type BootstrapResult, BootstrapService, type BootstrapServiceConfig, type BtpHandshakeExtension, type BuildIlpPrepareParams, CHAIN_PRESETS, type CalculateRouteAmountParams, type ChainName, type ChainPreset, type ChainProviderConfigEntry, type ChainType, type ChannelState, type ConnectorAdminClient, type ConnectorAdminLike, type ConnectorChannelClient, type ConnectorChannelLike, type ConnectorNodeLike, type DeriveFromKmsSeedOptions, type DeterminismReport, type DirectRuntimeClientConfig, type DiscoveredPeer, type DiscoveryTracker, type DiscoveryTrackerConfig, type DvmJobStatus, type EVMProviderConfigEntry, type EmbeddableConnectorLike, type ForbiddenPattern, type GenesisPeer, GenesisPeerLoader, type HandlePacketAcceptResponse, type HandlePacketRejectResponse, type HandlePacketRequest, type HandlePacketResponse, ILP_PEER_INFO_KIND, ILP_ROOT_PREFIX, IMAGE_GENERATION_KIND, type IlpClient, type IlpPeerInfo, type IlpPreparePacket, type IlpSendResult, JOB_FEEDBACK_KIND, JOB_REQUEST_KIND_BASE, JOB_RESULT_KIND_BASE, JOB_REVIEW_KIND, type JobFeedbackParams, type JobRequestParams, type JobResultParams, type JobReviewParams, KmsIdentityError, type KmsKeypair, type KnownPeer, type LogEntry, type LogLevel, type Logger, type LoggerConfig, MINA_CHAIN_PRESETS, MOCK_USDC_ADDRESS, MOCK_USDC_CONFIG, type MinaChainName, type MinaChainPreset, type MinaProviderConfigEntry, type MockUsdcConfig, type MultiChainName, type NixBuildResult, NixBuilder, type NixBuilderConfig, NostrPeerDiscovery, type OpenChannelParams, type OpenChannelResult, PET_INTERACTION_EVENT_KIND, PET_INTERACTION_REQUEST_KIND, PET_INTERACTION_RESULT_KIND, PREFIX_CLAIM_KIND, PREFIX_GRANT_KIND, type PacketHandler, type ParsedAttestation, type ParsedBlobStorageRequest, type ParsedJobFeedback, type ParsedJobRequest, type ParsedJobResult, type ParsedJobReview, type ParsedSwarmRequest, type ParsedSwarmSelection, type ParsedWorkflowDefinition, type ParsedWotDeclaration, PcrReproducibilityError, type PcrReproducibilityResult, type PeerDescriptor, type PrefixClaimContent, type PrefixGrantContent, type PrefixValidationResult, type PublishSeedRelayConfig, type RegisterPeerParams, type ReputationScore, ReputationScoreCalculator, type ReputationSignals, type ResolveRouteFeesParams, type ResolveRouteFeesResult, SEED_RELAY_LIST_KIND, SERVICE_DISCOVERY_KIND, SOLANA_CHAIN_PRESETS, SeedRelayDiscovery, type SeedRelayDiscoveryConfig, type SeedRelayDiscoveryResult, type SeedRelayEntry, type SendPacketParams, type SendPacketResult, type ServiceDiscoveryContent, type SettlementConfig, type SkillDescriptor, type SocialDiscoveryEvent, type SocialDiscoveryEventListener, SocialPeerDiscovery, type SocialPeerDiscoveryConfig, type SolanaChainName, type SolanaChainPreset, type SolanaProviderConfigEntry, type Subscription, type SwarmRequestParams, type SwarmSelectionParams, TEE_ATTESTATION_KIND, TEXT_GENERATION_KIND, TEXT_TO_SPEECH_KIND, TRANSLATION_KIND, type TeeAttestation, ToonError, type ToonNode, type ToonNodeConfig, type ToonNodeStartResult, USDC_DECIMALS, USDC_NAME, USDC_SYMBOL, VERSION, type VerificationResult, type VerifyOptions, type Violation, WEB_OF_TRUST_KIND, WORKFLOW_CHAIN_KIND, type WorkflowDefinitionParams, type WorkflowStep, type WotDeclarationParams, analyzeDockerfileForNonDeterminism, assignAddressFromHandshake, buildAttestationEvent, buildBlobStorageRequest, buildEip712Domain, buildEvmProviderEntry, buildIlpPeerInfoEvent, buildIlpPrepare, buildJobFeedbackEvent, buildJobRequestEvent, buildJobResultEvent, buildJobReviewEvent, buildMinaProviderEntry, buildPrefixClaimEvent, buildPrefixGrantEvent, buildPrefixHandshakeData, buildSeedRelayListEvent, buildServiceDiscoveryEvent, buildSolanaProviderEntry, buildSwarmRequestEvent, buildSwarmSelectionEvent, buildWorkflowDefinitionEvent, buildWotDeclarationEvent, calculateRouteAmount, checkAddressCollision, createAgentRuntimeClient, createDirectChannelClient, createDirectConnectorAdmin, createDirectIlpClient, createDirectRuntimeClient, createDiscoveryTracker, createHttpChannelClient, createHttpConnectorAdmin, createHttpIlpClient$1 as createHttpIlpClient, createHttpRuntimeClient, createHttpIlpClient as createHttpRuntimeClientV2, createLogger, createToonNode, deriveChildAddress, deriveFromKmsSeed, extractPrefixFromHandshake, hasMinReputation, hasRequireAttestation, isGenesisNode, isValidIlpAddressStructure, negotiateSettlementChain, parseAttestation, parseBlobStorageRequest, parseIlpPeerInfo, parseJobFeedback, parseJobRequest, parseJobResult, parseJobReview, parsePrefixClaimEvent, parsePrefixGrantEvent, parseSeedRelayList, parseServiceDiscovery, parseSwarmRequest, parseSwarmSelection, parseWorkflowDefinition, parseWotDeclaration, publishSeedRelayEntry, readDockerfileNix, resolveChainConfig, resolveMinaChainConfig, resolveRouteFees, resolveSolanaChainConfig, resolveTokenForChain, validateChainId, validateIlpAddress, validatePrefix, validatePrefixConsistency, verifyPcrReproducibility };
+export { AddressRegistry, type AgentRuntimeClient, ArDrivePeerRegistry, AttestationBootstrap, type AttestationBootstrapConfig, type AttestationBootstrapEvent, type AttestationBootstrapEventListener, type AttestationBootstrapResult, type AttestationEventOptions, AttestationState, AttestationVerifier, type AttestationVerifierConfig, type AttestedResultVerificationOptions, type AttestedResultVerificationResult, AttestedResultVerifier, BLOB_STORAGE_REQUEST_KIND, BLOB_STORAGE_RESULT_KIND, type BlobStorageRequestParams, type BootstrapConfig, BootstrapError, type BootstrapEvent, type BootstrapEventListener, type BootstrapPhase, type BootstrapResult, BootstrapService, type BootstrapServiceConfig, type BtpHandshakeExtension, type BuildIlpPeerInfoOptions, type BuildIlpPrepareParams, CHAIN_PRESETS, type CalculateRouteAmountParams, type ChainName, type ChainPreset, type ChainProviderConfigEntry, type ChainType, type ChannelState, type ClientNetworkPresets, type ConnectorAdminClient, type ConnectorAdminLike, type ConnectorChannelClient, type ConnectorChannelLike, type ConnectorNodeLike, type CustomEndpoints, type DeriveFromKmsSeedOptions, type DeterminismReport, type DirectRuntimeClientConfig, type DiscoveredPeer, type DiscoveryTracker, type DiscoveryTrackerConfig, type DvmJobStatus, type EVMProviderConfigEntry, EXPIRATION_TAG, type EmbeddableConnectorLike, type ForbiddenPattern, type GenesisPeer, GenesisPeerLoader, type HandlePacketAcceptResponse, type HandlePacketRejectResponse, type HandlePacketRequest, type HandlePacketResponse, ILP_PEER_INFO_KIND, ILP_ROOT_PREFIX, ILP_TO_SEMANTIC, IMAGE_GENERATION_KIND, type IlpClient, type IlpPeerInfo, type IlpPreparePacket, type IlpSendResult, JOB_FEEDBACK_KIND, JOB_REQUEST_KIND_BASE, JOB_RESULT_KIND_BASE, JOB_REVIEW_KIND, type JobFeedbackParams, type JobRequestParams, type JobResultParams, type JobReviewParams, KmsIdentityError, type KmsKeypair, type KnownPeer, type LogEntry, type LogLevel, type Logger, type LoggerConfig, MINA_CHAIN_PRESETS, MOCK_USDC_ADDRESS, MOCK_USDC_CONFIG, type MinaChainName, type MinaChainPreset, type MinaProviderConfigEntry, type MockUsdcConfig, type MultiChainName, type NetworkFamilyStatus, type NetworkMode, type NetworkNodeEnv, type NetworkProfile, type NixBuildResult, NixBuilder, type NixBuilderConfig, NostrPeerDiscovery, type OpenChannelParams, type OpenChannelResult, PET_INTERACTION_EVENT_KIND, PET_INTERACTION_REQUEST_KIND, PET_INTERACTION_RESULT_KIND, PREFIX_CLAIM_KIND, PREFIX_GRANT_KIND, type PacketHandler, type ParsedAttestation, type ParsedBlobStorageRequest, type ParsedJobFeedback, type ParsedJobRequest, type ParsedJobResult, type ParsedJobReview, type ParsedSwarmRequest, type ParsedSwarmSelection, type ParsedWorkflowDefinition, type ParsedWotDeclaration, PcrReproducibilityError, type PcrReproducibilityResult, type PeerDescriptor, type PrefixClaimContent, type PrefixGrantContent, type PrefixValidationResult, type PublishSeedRelayConfig, RELAY_ONLY_CHAIN, type RegisterPeerParams, type ReputationScore, ReputationScoreCalculator, type ReputationSignals, type ResolveRouteFeesParams, type ResolveRouteFeesResult, SEED_RELAY_LIST_KIND, SERVICE_DISCOVERY_KIND, SOLANA_CHAIN_PRESETS, SeedRelayDiscovery, type SeedRelayDiscoveryConfig, type SeedRelayDiscoveryResult, type SeedRelayEntry, type SendPacketParams, type SendPacketResult, type ServiceDiscoveryContent, type SettlementConfig, type SkillDescriptor, type SocialDiscoveryEvent, type SocialDiscoveryEventListener, SocialPeerDiscovery, type SocialPeerDiscoveryConfig, type SolanaChainName, type SolanaChainPreset, type SolanaProviderConfigEntry, type Subscription, type SwapPair, type SwarmRequestParams, type SwarmSelectionParams, TEE_ATTESTATION_KIND, TEXT_GENERATION_KIND, TEXT_TO_SPEECH_KIND, TRANSLATION_KIND, type TeeAttestation, ToonError, type ToonNode, type ToonNodeConfig, type ToonNodeStartResult, USDC_DECIMALS, USDC_NAME, USDC_SYMBOL, VERSION, type VerificationResult, type VerifyOptions, type Violation, WEB_OF_TRUST_KIND, WORKFLOW_CHAIN_KIND, type WorkflowDefinitionParams, type WorkflowStep, type WotDeclarationParams, analyzeDockerfileForNonDeterminism, assignAddressFromHandshake, balanceProofFieldsMina, balanceProofHashEvm, balanceProofHashSolana, base58Decode, base58Encode, bigintToBytes32BE, buildAttestationEvent, buildBlobStorageRequest, buildEip712Domain, buildEvmProviderEntry, buildIlpPeerInfoEvent, buildIlpPrepare, buildJobFeedbackEvent, buildJobRequestEvent, buildJobResultEvent, buildJobReviewEvent, buildMinaProviderEntry, buildPrefixClaimEvent, buildPrefixGrantEvent, buildPrefixHandshakeData, buildSeedRelayListEvent, buildServiceDiscoveryEvent, buildSolanaProviderEntry, buildSwarmRequestEvent, buildSwarmSelectionEvent, buildWorkflowDefinitionEvent, buildWotDeclarationEvent, calculateRouteAmount, checkAddressCollision, concatBytes, createAgentRuntimeClient, createDirectChannelClient, createDirectConnectorAdmin, createDirectIlpClient, createDirectRuntimeClient, createDiscoveryTracker, createHttpChannelClient, createHttpConnectorAdmin, createHttpIlpClient$1 as createHttpIlpClient, createHttpRuntimeClient, createHttpIlpClient as createHttpRuntimeClientV2, createLogger, createToonNode, deriveChildAddress, deriveFromKmsSeed, deriveMinaPublicKeyBase58, extractPrefixFromHandshake, getEventExpiration, hasMinReputation, hasRequireAttestation, hexToBytes, hexToMinaBase58PrivateKey, ilpCodeToSemantic, isEventExpired, isGenesisNode, isValidIlpAddressStructure, minaHashToField, negotiateSettlementChain, parseAttestation, parseBlobStorageRequest, parseIlpPeerInfo, parseJobFeedback, parseJobRequest, parseJobResult, parseJobReview, parsePrefixClaimEvent, parsePrefixGrantEvent, parseSeedRelayList, parseServiceDiscovery, parseSwarmRequest, parseSwarmSelection, parseWorkflowDefinition, parseWotDeclaration, publishSeedRelayEntry, readDockerfileNix, resolveChainConfig, resolveClientNetwork, resolveMinaChainConfig, resolveNetworkProfile, resolveRouteFees, resolveSolanaChainConfig, resolveTokenForChain, validateChainId, validateIlpAddress, validatePrefix, validatePrefixConsistency, verifyPcrReproducibility };