@toon-protocol/client 0.15.0 → 0.17.0

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import * as _toon_protocol_core from '@toon-protocol/core';
-import { IlpPeerInfo, IlpClient, IlpSendResult, NetworkFamilyStatus, ConnectorAdminClient, ConnectorChannelClient, OpenChannelParams, OpenChannelResult, ChannelState } from '@toon-protocol/core';
+import { IlpPeerInfo, IlpSendResult, IlpClient, NetworkFamilyStatus, ConnectorAdminClient, ConnectorChannelClient, OpenChannelParams, OpenChannelResult, ChannelState } from '@toon-protocol/core';
 export { UI_RENDERER_KIND, UI_TAG, UiCoordinate, buildUiCoordinate, getUiCoordinate, parseUiCoordinate, selectLatestAddressable } from '@toon-protocol/core';
 import { NostrEvent, EventTemplate } from 'nostr-tools/pure';
 import { PrivateKeyAccount } from 'viem/accounts';
@@ -15,6 +15,108 @@ interface WalletBalance {
     /** Token decimals, when resolved. */
     assetScale?: number;
 }
+/**
+ * One asset amount within a chain's wallet view — the native coin or one token.
+ * `amount` is a base-unit integer, decimal string.
+ */
+interface WalletTokenAmount {
+    /** Asset symbol (e.g. `'ETH'`, `'SOL'`, `'MINA'`, `'USDC'`), when known. */
+    symbol?: string;
+    /** Base-unit integer, decimal string. */
+    amount: string;
+    /** Decimals for formatting (ETH 18, SOL 9, MINA 9, USDC 6). */
+    decimals?: number;
+    /** Token contract / SPL mint address. Absent for the native coin. */
+    address?: string;
+}
+/**
+ * The full wallet view for ONE chain the identity is configured for: the native
+ * coin plus every configured token, keyed by the chain's full key (e.g.
+ * `'evm:31337'`). `unreadable` marks a chain whose RPC could not be reached at
+ * all — the caller renders a per-chain notice rather than crashing.
+ */
+interface WalletChainBalances {
+    chain: 'evm' | 'solana' | 'mina';
+    /** Full chain key, e.g. `'evm:31337'`, `'solana'`, `'mina'`. */
+    chainKey: string;
+    address: string;
+    /** Native-coin balance, when readable. */
+    native?: WalletTokenAmount;
+    /** Configured token balances (e.g. USDC), each best-effort. */
+    tokens: WalletTokenAmount[];
+    /** True when nothing on this chain could be read (RPC unreachable). */
+    unreadable?: boolean;
+    /** First read error, when any read failed (for diagnostics). */
+    error?: string;
+}
+/** Read an ERC-20 token balance (balance + decimals + symbol) for `owner`. */
+declare function readEvmTokenBalance(opts: {
+    rpcUrl: string;
+    chainKey: string;
+    tokenAddress: string;
+    owner: string;
+}): Promise<WalletBalance>;
+/** Read the native ETH balance (wei) for `owner` via `eth_getBalance`. */
+declare function readEvmNativeBalance(opts: {
+    rpcUrl: string;
+    chainKey: string;
+    owner: string;
+}): Promise<WalletTokenAmount>;
+/** Read the native SOL balance (lamports) for `owner` via the `getBalance` RPC. */
+declare function readSolanaNativeBalance(opts: {
+    rpcUrl: string;
+    owner: string;
+    fetchImpl?: typeof fetch;
+}): Promise<WalletTokenAmount>;
+/** Read the SPL-token balance for `owner`'s token account(s) of `mint`. */
+declare function readSolanaTokenBalance(opts: {
+    rpcUrl: string;
+    mint: string;
+    owner: string;
+    fetchImpl?: typeof fetch;
+}): Promise<WalletBalance>;
+/** Read the native MINA balance (nanomina) for `owner` via the Mina GraphQL API. */
+declare function readMinaBalance(opts: {
+    graphqlUrl: string;
+    owner: string;
+    fetchImpl?: typeof fetch;
+}): Promise<WalletBalance>;
+/**
+ * Per-chain inputs for {@link readWalletBalances}: the resolved RPC URL, the
+ * identity's address on that chain, and the configured token (USDC) — sourced by
+ * the caller from the network topology / presets, never hardcoded here. A chain
+ * key absent from the object is simply not read.
+ */
+interface WalletBalanceSources {
+    evm?: {
+        chainKey: string;
+        rpcUrl: string;
+        owner: string;
+        tokenAddress?: string;
+    };
+    solana?: {
+        chainKey?: string;
+        rpcUrl: string;
+        owner: string;
+        tokenMint?: string;
+    };
+    mina?: {
+        chainKey?: string;
+        graphqlUrl: string;
+        owner: string;
+    };
+    /** Injectable fetch (Solana/Mina JSON-RPC & GraphQL) for tests. */
+    fetchImpl?: typeof fetch;
+}
+/**
+ * Read the full wallet view — native coin + configured tokens — for every chain
+ * in `sources`, keyed per chain. FREE: read-only RPC, no signing. Each chain is
+ * read independently and in parallel; a chain whose RPC is unreachable degrades
+ * to `{ unreadable: true, error }` instead of failing the others. Within a chain
+ * the native and token reads are independent, so a native read can succeed even
+ * if the token read fails (and vice versa).
+ */
+declare function readWalletBalances(sources: WalletBalanceSources): Promise<WalletChainBalances[]>;
 
 /**
  * Solana payment-channel parameters supplied via `ToonClientConfig.solanaChannel`.
@@ -538,6 +640,62 @@ declare function requestBlobStorage(client: ToonClient, secretKey: Uint8Array, p
  */
 declare function extractArweaveTxId(base64Data: string): string;
 
+/**
+ * Shared sender-side plumbing for sender-chosen execution conditions
+ * (toon-client#350; contract: connector `docs/local-delivery-fulfillment-contract.md`,
+ * connector#309; spec: toon-meta `docs/rolling-swap.md` §3).
+ *
+ * Both ILP transports (HTTP `POST /ilp` and BTP) take the SAME extended send
+ * params and map FULFILL/REJECT responses through the SAME verifier so the
+ * two paths cannot drift:
+ *
+ *   - absent/all-zero `executionCondition` → legacy class: today's behavior,
+ *     byte-for-byte (zero condition on the wire, no FULFILL verification);
+ *   - non-zero `executionCondition` → sender-chosen: the condition goes on
+ *     the PREPARE verbatim and the FULFILL's 32-byte fulfillment MUST hash
+ *     back to it — a missing/malformed/mismatching preimage is surfaced as a
+ *     FAILED result (never a silent accept, never retried).
+ */
+
+/**
+ * Send parameters accepted by both ILP transports. Extends the
+ * `@toon-protocol/core` `IlpClient` param shape with the sender-chosen
+ * condition and an explicit expiry — plain `IlpClient` callers keep working
+ * unchanged (both extras are optional; omitting them is the legacy path).
+ */
+interface IlpSendParams {
+    destination: string;
+    amount: string;
+    /** Base64 ILP `data` payload. */
+    data: string;
+    /** Transport timeout in ms; also the default expiry window. */
+    timeout?: number;
+    /**
+     * Sender-chosen 32-byte execution condition `C = sha256(P)` (spec R2).
+     * Absent or all-zero = legacy unverified packet (default — ordinary
+     * publish/upload writes MUST keep this default).
+     */
+    executionCondition?: Uint8Array;
+    /**
+     * Explicit PREPARE `expiresAt` (spec R7). Defaults to `now + timeout`,
+     * preserving pre-#350 behavior.
+     */
+    expiresAt?: Date;
+}
+/**
+ * `IlpSendResult` plus the FULFILL preimage when a sender-chosen condition
+ * was verified. Only populated on the sender-chosen path so legacy result
+ * objects stay byte-identical.
+ */
+interface IlpSendResultWithFulfillment extends IlpSendResult {
+    /** Base64 32-byte fulfillment preimage (verified: sha256 == condition). */
+    fulfillment?: string;
+}
+/** ILP code used for a client-side fulfillment-verification failure. */
+declare const FULFILLMENT_MISMATCH_CODE = "F99";
+/** Message for a client-side fulfillment-verification failure. */
+declare const FULFILLMENT_MISMATCH_MESSAGE: string;
+
 interface BtpRuntimeClientConfig {
     btpUrl: string;
     peerId: string;
@@ -574,23 +732,22 @@ declare class BtpRuntimeClient implements IlpClient {
     /**
      * Sends an ILP packet via BTP with auto-reconnect on connection errors.
      * Satisfies IlpClient interface.
+     *
+     * `params` may carry a sender-chosen `executionCondition` and an explicit
+     * `expiresAt` (toon-client#350); omitting both is the legacy zero-condition
+     * path, unchanged. With a non-zero condition the FULFILL preimage is
+     * verified (`sha256(fulfillment) == condition`) and a mismatch is surfaced
+     * as a failed result — see `mapIlpResponse`.
      */
-    sendIlpPacket(params: {
-        destination: string;
-        amount: string;
-        data: string;
-        timeout?: number;
-    }): Promise<IlpSendResult>;
+    sendIlpPacket(params: IlpSendParams): Promise<IlpSendResult>;
     /**
      * Sends a balance proof claim via BTP protocol data, then sends an ILP packet.
      * Auto-reconnects on connection errors.
+     *
+     * Sender-chosen `executionCondition` / explicit `expiresAt` semantics are
+     * identical to {@link sendIlpPacket}.
      */
-    sendIlpPacketWithClaim(params: {
-        destination: string;
-        amount: string;
-        data: string;
-        timeout?: number;
-    }, claim: Record<string, unknown>): Promise<IlpSendResult>;
+    sendIlpPacketWithClaim(params: IlpSendParams, claim: Record<string, unknown>): Promise<IlpSendResult>;
     /**
      * Send a standalone `payment-channel-claim` BTP MESSAGE (no ILP packet
      * attached). The connector's ClaimReceiver consumes this fire-and-forget
@@ -599,6 +756,14 @@ declare class BtpRuntimeClient implements IlpClient {
      */
     sendClaimMessage(claim: Record<string, unknown>): Promise<void>;
     private _sendClaimMessageOnce;
+    /**
+     * Build the ILP PREPARE for a send, applying the sender-chosen condition /
+     * explicit expiry when provided (toon-client#350) and validating that a
+     * non-zero condition is exactly 32 bytes (the OER serializer would
+     * otherwise silently zero-fill it, downgrading the packet to the legacy
+     * unverified class).
+     */
+    private buildPrepare;
     /**
      * Single-attempt ILP packet send. Reconnects if not connected.
      */
@@ -690,25 +855,24 @@ declare class HttpIlpClient implements IlpClient {
      * Send an ILP PREPARE via `POST /ilp` WITHOUT a claim. The connector accepts
      * this only on free/zero-amount routes; paid writes must use
      * {@link sendIlpPacketWithClaim}. Satisfies the IlpClient interface.
+     *
+     * `params` may carry a sender-chosen `executionCondition` and an explicit
+     * `expiresAt` (toon-client#350); omitting both is the legacy zero-condition
+     * path, unchanged. With a non-zero condition the FULFILL preimage is
+     * verified (`sha256(fulfillment) == condition`) and a mismatch is surfaced
+     * as a failed result — see {@link mapIlpResponse}.
      */
-    sendIlpPacket(params: {
-        destination: string;
-        amount: string;
-        data: string;
-        timeout?: number;
-    }): Promise<IlpSendResult>;
+    sendIlpPacket(params: IlpSendParams): Promise<IlpSendResult>;
     /**
      * Send an ILP PREPARE via `POST /ilp` with the payment-channel claim attached
      * as the `ILP-Payment-Channel-Claim` header. `claim` is the SAME JSON object
      * the BTP path attaches as the `payment-channel-claim` protocolData entry —
      * we base64(JSON.stringify(claim)) it, byte-for-byte identical to BTP.
+     *
+     * Sender-chosen `executionCondition` / explicit `expiresAt` semantics are
+     * identical to {@link sendIlpPacket}.
      */
-    sendIlpPacketWithClaim(params: {
-        destination: string;
-        amount: string;
-        data: string;
-        timeout?: number;
-    }, claim: unknown): Promise<IlpSendResult>;
+    sendIlpPacketWithClaim(params: IlpSendParams, claim: unknown): Promise<IlpSendResult>;
     /**
      * Upgrade to a duplex BTP session over the SAME endpoint.
      *
@@ -736,6 +900,10 @@ declare class HttpIlpClient implements IlpClient {
      * Map a `200 OK` body (OER FULFILL/REJECT) to an IlpSendResult; map a non-2xx
      * to a transport error. Per the wire contract, ILP-level rejects arrive as a
      * 200 + REJECT body — only HTTP non-2xx means a transport-layer failure.
+     *
+     * When `sentCondition` is non-zero the FULFILL preimage is verified against
+     * it; a mismatch yields `accepted: false` (shared `mapIlpResponse` logic,
+     * identical to the BTP path).
      */
     private mapResponse;
     private mapTransportError;
@@ -1152,6 +1320,14 @@ declare class ToonClient {
      *       matching `destination`,
      *   (c) neither -> throw MISSING_CLAIM.
      *
+     * A caller may supply a sender-chosen 32-byte `executionCondition`
+     * (`C = sha256(P)`, one fresh preimage per packet — toon-client#350,
+     * rolling-swap spec §3 R1/R2) and an explicit `expiresAt` (R7). Both are
+     * set on the wire by either transport (HTTP `POST /ilp` and BTP), and on
+     * FULFILL the transport verifies `sha256(fulfillment) == condition` —
+     * a mismatch comes back as `accepted: false` (code F99), never a silent
+     * accept. Omitting them keeps today's zero-condition legacy packet.
+     *
      * @throws {ToonClientError} INVALID_STATE / NO_ILP_TRANSPORT / MISSING_CLAIM
      */
     sendSwapPacket(params: {
@@ -1160,6 +1336,10 @@ declare class ToonClient {
         toonData: Uint8Array;
         timeout?: number;
         claim?: SignedBalanceProof;
+        /** Sender-chosen 32-byte execution condition; absent/zero = legacy. */
+        executionCondition?: Uint8Array;
+        /** Explicit ILP expiry; defaults to `now + timeout` in the transport. */
+        expiresAt?: Date;
     }): Promise<IlpSendResult>;
     /**
      * Build a BTP claim message from a pre-signed balance proof using the
@@ -1317,6 +1497,22 @@ declare class ToonClient {
      * are derived there).
      */
     getBalances(): Promise<WalletBalance[]>;
+    /**
+     * The FULL multi-chain wallet view (#299): for every chain the identity is
+     * configured for, the native coin (ETH / SOL / MINA) AND every configured
+     * token (USDC), grouped per chain with the identity's address on that chain.
+     * A superset of {@link getBalances} — which stays scoped to the channel's
+     * settlement token — kept as a separate reader so channel-settlement callers
+     * are unaffected.
+     *
+     * FREE: read-only RPC, no signing, no payment. Works on an UNSTARTED client:
+     * the Solana/Mina addresses (which the signers only register during
+     * `start()`) are derived on demand from the retained mnemonic — the SAME keys
+     * `start()` would register and that `rig fund` prints — so all configured
+     * chains appear even before a start. Best-effort per chain: an unreachable
+     * RPC yields `{ unreadable: true }` for that chain, never failing the others.
+     */
+    getWalletBalances(): Promise<WalletChainBalances[]>;
     /**
      * Resolves an ILP destination address to a peer ID.
      * Convention: destination "g.toon.peer1" → peerId "peer1" (last segment).
@@ -2691,6 +2887,56 @@ declare function parseFulfillHttpBytes(bytes: Uint8Array): ParsedFulfillHttp;
  */
 declare function parseFulfillHttp(base64Data: string): ParsedFulfillHttp;
 
+/**
+ * Sender-chosen ILP execution conditions (toon-client#350, rolling-swap
+ * prerequisite — toon-meta#145 §3 R1/R2).
+ *
+ * Contract (normative: connector `docs/local-delivery-fulfillment-contract.md`,
+ * connector#309):
+ *   - An ABSENT or ALL-ZERO (32×0x00) `executionCondition` is the LEGACY
+ *     class: no hashlock, no verification — today's publish/upload writes.
+ *   - Any NON-ZERO condition is SENDER-CHOSEN: the sender mints a fresh
+ *     random 32-byte preimage `P` per packet, sets `C = sha256(P)` on the
+ *     PREPARE, and on FULFILL MUST verify that the returned fulfillment
+ *     hashes back to `C` — a missing/malformed/mismatching fulfillment is a
+ *     hard failure (the packet is counted failed, never silently accepted).
+ *
+ * Isomorphic: @noble/hashes only (no Buffer, no node:crypto).
+ */
+/** Exact byte length of an ILP execution condition / fulfillment preimage. */
+declare const CONDITION_LENGTH = 32;
+/** A freshly minted per-packet hashlock: `condition = sha256(preimage)`. */
+interface ExecutionConditionPair {
+    /** Random 32-byte preimage `P` — reveal is the commit act; never reuse. */
+    preimage: Uint8Array;
+    /** `C = sha256(P)` — goes on the PREPARE's `executionCondition`. */
+    condition: Uint8Array;
+}
+/**
+ * Mint a fresh random 32-byte preimage and its sha256 condition (spec R1).
+ * Mint one PER PACKET: a reused preimage lets any observer of packet *i*
+ * fulfill packet *i+1* without the sender's consent.
+ */
+declare function mintExecutionCondition(): ExecutionConditionPair;
+/**
+ * True when `condition` selects the LEGACY (unverified) class: absent or
+ * all-zero. The OER wire treats absent and 32×0x00 identically.
+ */
+declare function isZeroCondition(condition: Uint8Array | undefined): boolean;
+/**
+ * Validate a caller-supplied execution condition before it goes on the wire.
+ * @throws {Error} When the condition is not exactly 32 bytes — the OER
+ *   serializer would otherwise silently zero-fill it, downgrading a
+ *   sender-chosen packet to the legacy unverified class.
+ */
+declare function assertValidCondition(condition: Uint8Array): void;
+/**
+ * True iff `fulfillment` is exactly 32 bytes and `sha256(fulfillment)`
+ * equals `condition` — the sender-side FULFILL check (spec R6's mirror).
+ * Fail-closed: an undefined/short/long fulfillment never matches.
+ */
+declare function fulfillmentMatchesCondition(fulfillment: Uint8Array | undefined, condition: Uint8Array): boolean;
+
 /**
  * Settlement info produced by buildSettlementInfo().
  * Extends the core SettlementConfig shape with ilpAddress for client use.
@@ -3208,4 +3454,4 @@ declare function loadKeystore(path: string, password: string): string;
  */
 declare function writeKeystoreFile(path: string, keystore: EncryptedKeystore): void;
 
-export { type BackupPayload, type BalanceProofParams, BtpRuntimeClient, type BtpRuntimeClientConfig, type ChainMetadata, type ChainSigner, ChannelFundingError, ChannelManager, type ClaimMessage, type ClaimResolver, ConnectorError, type DiscoveredIlpPeer, type EVMClaimMessage, type EncryptedKeystore, EvmSigner, type FaucetChain, type FundWalletOptions, type FundWalletResult, type H402FetchOptions, Http402Client, type Http402ClientConfig, HttpConnectorAdmin, type HttpConnectorAdminConfig, HttpIlpClient, type HttpIlpClientConfig, type HttpIlpClientFactory, HttpRuntimeClient, type HttpRuntimeClientConfig, ILP_CLAIM_HEADER, ILP_CLAIM_WRAPPED_HEADER, ILP_PEER_ID_HEADER, type IlpTransportChoice, KeyManager, type KeyManagerConfig, type MinaClaimMessage, type MinaDepositReader, MinaSigner, type MinaSignerOptions, NetworkError, OnChainChannelClient, type OnChainChannelClientConfig, type ParsedFulfillHttp, type ParsedX402Challenge, type PasskeyInfo, type PublishEventResult, type RequestBlobStorageParams, type RequestBlobStorageResult, type RetryOptions, type SelectIlpTransportOptions, type SignedBalanceProof, type SolanaChannelClientOptions, type SolanaClaimMessage, SolanaSigner, type ToonChannelAccept, ToonClient, type ToonClientConfig, ToonClientError, type ToonIdentity, type ToonSigners, type ToonStartResult, ValidationError, type VaultData, applyDefaults, applyNetworkPresets, buildBackupEvent, buildBackupFilter, buildSettlementInfo, buildStoreWriteEnvelope, decryptMnemonic, defaultFaucetTimeout, deriveFromNsec, deriveFullIdentity, deriveNostrKeyFromMnemonic, encryptMnemonic, extractArweaveTxId, fundWallet, generateKeystore, generateMnemonic, generateRandomIdentity, getNetworkStatus, httpEndpointToBtpUrl, importKeystore, isInsufficientGasError, isPrfSupported, loadKeystore, parseBackupPayload, parseFulfillHttp, parseFulfillHttpBytes, parseHttpResponse, parseX402Body, parseX402Challenge, proxyIlpEndpoint, readDiscoveredIlpPeer, readMinaDepositTotal, requestBlobStorage, selectIlpTransport, serializeHttpRequest, validateConfig, validateMnemonic, withRetry, writeKeystoreFile };
+export { type BackupPayload, type BalanceProofParams, BtpRuntimeClient, type BtpRuntimeClientConfig, CONDITION_LENGTH, type ChainMetadata, type ChainSigner, ChannelFundingError, ChannelManager, type ClaimMessage, type ClaimResolver, ConnectorError, type DiscoveredIlpPeer, type EVMClaimMessage, type EncryptedKeystore, EvmSigner, type ExecutionConditionPair, FULFILLMENT_MISMATCH_CODE, FULFILLMENT_MISMATCH_MESSAGE, type FaucetChain, type FundWalletOptions, type FundWalletResult, type H402FetchOptions, Http402Client, type Http402ClientConfig, HttpConnectorAdmin, type HttpConnectorAdminConfig, HttpIlpClient, type HttpIlpClientConfig, type HttpIlpClientFactory, HttpRuntimeClient, type HttpRuntimeClientConfig, ILP_CLAIM_HEADER, ILP_CLAIM_WRAPPED_HEADER, ILP_PEER_ID_HEADER, type IlpSendParams, type IlpSendResultWithFulfillment, type IlpTransportChoice, KeyManager, type KeyManagerConfig, type MinaClaimMessage, type MinaDepositReader, MinaSigner, type MinaSignerOptions, NetworkError, OnChainChannelClient, type OnChainChannelClientConfig, type ParsedFulfillHttp, type ParsedX402Challenge, type PasskeyInfo, type PublishEventResult, type RequestBlobStorageParams, type RequestBlobStorageResult, type RetryOptions, type SelectIlpTransportOptions, type SignedBalanceProof, type SolanaChannelClientOptions, type SolanaClaimMessage, SolanaSigner, type ToonChannelAccept, ToonClient, type ToonClientConfig, ToonClientError, type ToonIdentity, type ToonSigners, type ToonStartResult, ValidationError, type VaultData, type WalletBalance, type WalletBalanceSources, type WalletChainBalances, type WalletTokenAmount, applyDefaults, applyNetworkPresets, assertValidCondition, buildBackupEvent, buildBackupFilter, buildSettlementInfo, buildStoreWriteEnvelope, decryptMnemonic, defaultFaucetTimeout, deriveFromNsec, deriveFullIdentity, deriveNostrKeyFromMnemonic, encryptMnemonic, extractArweaveTxId, fulfillmentMatchesCondition, fundWallet, generateKeystore, generateMnemonic, generateRandomIdentity, getNetworkStatus, httpEndpointToBtpUrl, importKeystore, isInsufficientGasError, isPrfSupported, isZeroCondition, loadKeystore, mintExecutionCondition, parseBackupPayload, parseFulfillHttp, parseFulfillHttpBytes, parseHttpResponse, parseX402Body, parseX402Challenge, proxyIlpEndpoint, readDiscoveredIlpPeer, readEvmNativeBalance, readEvmTokenBalance, readMinaBalance, readMinaDepositTotal, readSolanaNativeBalance, readSolanaTokenBalance, readWalletBalances, requestBlobStorage, selectIlpTransport, serializeHttpRequest, validateConfig, validateMnemonic, withRetry, writeKeystoreFile };