@toon-protocol/rig 4.7.0 → 5.0.0

package/dist/standalone/index.d.ts

@@ -2,13 +2,14 @@ import { P as Publisher, F as FeeRates, G as GitObjectUpload, U as UploadReceipt
 import '@toon-protocol/core/nip34';
 
 /**
- * The paid write path on `@toon-protocol/client` 2.x — a {@link Publisher}
+ * The paid write path on `@toon-protocol/client` 4.x: a {@link Publisher}
  * that pays a TOON connector per request.
  *
  * Everything a paid command needs comes from one connector URL: the client
- * reads the node's own `GET /ilp` (addresses, prices, settlement chains,
- * sealing key — connector ADR 0050), opens or adopts a payment channel, and
- * pays each request with a signed claim. There is no relay to discover peers
+ * reads the node's own `GET /ilp` (addresses, prices, x402 batch-settlement
+ * terms, sealing key: connector ADR 0050), opens or resumes an x402 channel,
+ * and pays each request with a signed voucher for the running total
+ * (connector ADR 0075). There is no relay to discover peers
  * on (kind:10032 was removed by ADR 0046) and no topology to negotiate: a
  * destination is a route the node prices, and `send()` pays what the route
  * costs — including the per-kibibyte part of an ADR 0065 schedule, which the
@@ -65,7 +66,7 @@ interface RouteTerms {
     price: bigint;
     pricePerKib?: bigint;
 }
-/** The slice of `ToonClient` (2.x) this publisher needs. */
+/** The slice of `ToonClient` (4.x) this publisher needs. */
 interface PaidClientLike {
     send(destination: string, request: PaidRequest, options?: PaidSendOptions): Promise<PaidSendResult>;
     /** The node's terms for a destination, or `null` when it prices no such route. */
@@ -127,7 +128,7 @@ declare class ConnectorPublisher implements Publisher {
     getFeeRates(): Promise<FeeRates>;
     private readFeeRates;
     private sign;
-    /** One paid kind:5094 write; returns the tx id and what the claim spent. */
+    /** One paid kind:5094 write; returns the tx id and what the voucher spent. */
     private storeWrite;
     uploadGitObject(upload: GitObjectUpload): Promise<UploadReceipt>;
     uploadBlob(upload: BlobUpload): Promise<UploadReceipt>;
@@ -148,7 +149,7 @@ declare class ConnectorPublisher implements Publisher {
 /**
  * The Nostr signing key rig derives from a BIP-39 phrase.
  *
- * `@toon-protocol/client` 2.x is a pure payer and carries no Nostr identity
+ * `@toon-protocol/client` 2.x and later is a pure payer and carries no Nostr identity
  * (its own words), so the derivation that lived in the 0.x client moves here,
  * unchanged: `m/44'/1237'/0'/0/<accountIndex>`. Unchanged matters — this is
  * the key every existing rig repo is owned by (`toon.owner`, the kind:30617
@@ -176,40 +177,45 @@ declare function deriveNostrKeyFromMnemonic(mnemonic: string, accountIndex?: num
 /**
  * Peer→channel map for the STANDALONE embedded publisher (#262).
  *
- * Why this exists: `@toon-protocol/client`'s `ChannelManager` persists the
- * off-chain nonce/cumulative-claim watermark (its `ChannelStore`,
- * `channels.json`, keyed by channelId) but keeps the peer→channelId mapping
- * ONLY in memory. So every standalone CLI invocation used to open (and fund)
- * a FRESH on-chain channel — the #260 fresh-outsider e2e stranded five
- * deposits across five commands. This store remembers WHICH channel the
- * identity holds with each peer, keyed by
- * `identity pubkey | ILP anchor (peer/apex destination) | chain | tokenNetwork`,
- * so the next invocation resumes it via `ChannelManager.trackChannel` (which
- * rehydrates the nonce watermark from `channels.json`) with zero on-chain
- * writes.
+ * Why this exists: rig used to open (and fund) a FRESH on-chain channel per
+ * invocation, because the client of the day kept the peer→channelId mapping
+ * only in memory (the #260 fresh-outsider e2e stranded five deposits across
+ * five commands). Since client 4.x the client persists its own channel config
+ * beside the watermark (`JsonFileChannelStore`: `channels-x402.json` plus its
+ * `.peers.json` sibling) and resumes from it by itself. This map remains the
+ * record `rig channel list/close/settle`, `rig balance` and `rig ci serve`
+ * read: WHICH channel the identity holds with each peer, keyed by
+ * `identity pubkey | ILP anchor (peer/apex destination) | chain | tokenNetwork`.
+ *
+ * VOUCHERS (client 4.x, connector ADR 0075): every paid packet carries an x402
+ * `batch-settlement` voucher naming the running total. There is no nonce; the
+ * watermark is the cumulative amount alone. The toon-channel claims client
+ * 3.x signed are refused by a current connector, so a 3.x rig's files
+ * (`rig-channels.json`, `channels.json`) are never read by this module and
+ * never written: they are only named, so their deposits can still be taken
+ * back with the rig that opened them ({@link legacyChannelFiles}).
  *
  * It is the standalone twin of the daemon's
  * `packages/client-mcp/src/daemon/apex-channel-store.ts` — same record shape
- * (channelId + the chain context `trackChannel` needs), extended with the
- * identity pubkey (rig identities come from an env/`.env` precedence chain,
- * so one state dir can serve several identities) and the tokenNetwork.
+ * (channelId + the chain context), extended with the identity pubkey (rig
+ * identities come from an env/`.env` precedence chain, so one state dir can
+ * serve several identities) and the tokenNetwork.
  * `@toon-protocol/rig` must not import `@toon-protocol/client-mcp` (that
  * package depends on this one — circular), hence the twin; keep the
  * semantics in sync.
  *
  * CONCURRENCY: writes happen only from paid commands, which already hold the
  * per-identity advisory lockfile (./nonce-guard.ts `NonceLock`) for their
- * whole lifetime — the same guard that serializes the claim watermark also
+ * whole lifetime: the same guard that serializes the voucher watermark also
  * serializes this file for one identity. `rig channel list` reads only.
  *
  * COUNTERPARTY: the key names a ROUTE, not a node — an ILP name can change
  * hands (the devnet apex `g.toon` was retired and another node took over
  * `g.toon.relay`). A record therefore also carries the counterparty
- * settlement address it was opened against (`context.recipient`), which is
- * re-checked against the destination's announced address before every resume
- * ({@link counterpartyMatch}); a rotated counterparty
- * {@link ChannelMapStore.supersede}s the record instead of signing claims a
- * connector with no record of that channel refuses (`F01`).
+ * settlement address it was opened against (`context.recipient`), which can be
+ * re-checked against the destination's announced address ({@link
+ * counterpartyMatch}); a rotated counterparty {@link ChannelMapStore.supersede}s
+ * the record rather than paying a connector with no record of that channel.
  *
  * CORRUPTION: an unreadable/invalid map file is a hard
  * {@link ChannelMapCorruptError} — surfaced BEFORE any on-chain open — never
@@ -220,22 +226,46 @@ declare function deriveNostrKeyFromMnemonic(mnemonic: string, accountIndex?: num
  * `rig channel list` command reads it without the optional
  * `@toon-protocol/client` peer dependency installed.
  */
-/** Map filename under the shared client state dir. */
-declare const RIG_CHANNEL_MAP_FILENAME = "rig-channels.json";
+/** Map filename under the shared client state dir (x402 voucher channels). */
+declare const RIG_CHANNEL_MAP_FILENAME = "rig-channels-x402.json";
+/**
+ * The client's x402 channel store under the shared client state dir: the
+ * voucher watermark, with every channel's config in the `.peers.json` sibling.
+ * A new name for client 4.x so a 3.x store is never read as one.
+ */
+declare const CHANNEL_STORE_FILENAME = "channels-x402.json";
+/** What a client 3.x rig kept its toon-channel map in. Never read or written. */
+declare const LEGACY_RIG_CHANNEL_MAP_FILENAME = "rig-channels.json";
+/** What a client 3.x rig kept its toon-channel watermark in. Never read or written. */
+declare const LEGACY_CHANNEL_STORE_FILENAME = "channels.json";
 /**
  * Resolve the two channel-state files under `TOON_CLIENT_HOME` (default
- * `~/.toon-client`): the rig peer→channel map, and the client's nonce
- * watermark store (`config.json`'s `channelStorePath`, default
- * `<dir>/channels.json` — the same resolution `cli/standalone-mode.ts` feeds
- * the embedded ToonClient).
+ * `~/.toon-client`): the rig peer→channel map, and the client's x402 voucher
+ * store (`config.json`'s `channelStorePath`, default
+ * `<dir>/channels-x402.json`: the same resolution `cli/standalone-mode.ts`
+ * feeds the embedded ToonClient).
  */
 declare function resolveChannelPaths(env: NodeJS.ProcessEnv): {
     mapPath: string;
     watermarkPath: string;
 };
 /**
- * Chain context `ChannelManager.trackChannel` needs to resume a channel
- * (same shape the daemon's apex-channel-store persists).
+ * The client 3.x channel files present in a state dir: a toon-channel map and
+ * watermark a current connector no longer honours. Named so a caller can say
+ * they were skipped; the deposits they record are left for the 3.x rig that
+ * opened them (`npm i -g @toon-protocol/rig@4.7.0`, then `rig channel close`).
+ */
+declare function legacyChannelFiles(dir: string): string[];
+/**
+ * Does `path` hold a client 3.x toon-channel store? Its watermark entries
+ * carry a nonce that moved (a 4.x entry keeps `nonce: 0` for the file's
+ * sake), and its `.peers.json` bindings carry no `batchSettlement` config.
+ * An unreadable file answers false: the client reports it on its own read.
+ */
+declare function isToonChannelStore(path: string): boolean;
+/**
+ * A channel's chain context (same shape the daemon's apex-channel-store
+ * persists, and the client's own binding carries).
  */
 interface PersistedChannelContext {
     chainType: string;
@@ -249,17 +279,17 @@ interface PersistedChannelContext {
 interface ChannelMapRecord {
     /** On-chain payment channel id. */
     channelId: string;
-    /** Registered peer id the negotiation was keyed by (`peerNegotiations`). */
+    /** The node's sealing key id (`GET /ilp` `edgeIdentity.keyId`), else its URL. */
     peerId: string;
     /** Hex Nostr pubkey of the identity that opened the channel. */
     identity: string;
     /** ILP anchor destination the channel was opened against (peer/apex). */
     destination: string;
-    /** Negotiated settlement chain, e.g. `evm:31337`. */
+    /** The x402 network the channel lives on, e.g. `eip155:8453`, `solana:5eykt…`. */
     chain: string;
-    /** TokenNetwork contract address ('' when the peer announced none). */
+    /** The batch-settlement contract (EVM) or program (Solana) holding it. */
     tokenNetwork: string;
-    /** Context for `trackChannel` on resume. */
+    /** Chain context: chain type, token, counterparty. */
     context: PersistedChannelContext;
     /** On-chain deposit total (base units, string), when known. */
     depositTotal?: string;
@@ -284,15 +314,16 @@ interface ChannelMapKey {
     tokenNetwork: string;
 }
 /**
- * One entry of the client's nonce-watermark store (`channels.json`) —
+ * One entry of the client's voucher watermark store (`channels-x402.json`):
  * format DUPLICATED from `@toon-protocol/client`'s `JsonFileChannelStore`
  * (`packages/client/src/channel/ChannelStore.ts`); keep in sync.
  */
 interface WatermarkEntry {
-    nonce: number;
-    /** Cumulative claimed amount, base units (string-encoded bigint). */
+    /** Always 0 for an x402 channel: vouchers carry no nonce. Kept for the file's shape. */
+    nonce?: number;
+    /** Cumulative amount signed so far, base units (string-encoded bigint). */
     cumulativeAmount: string;
-    /** Withdraw-flow timers, string-encoded unix SECONDS. */
+    /** Exit timers, string-encoded unix SECONDS. */
     closedAt?: string;
     settleableAt?: string;
     settledAt?: string;
@@ -336,11 +367,11 @@ declare function recordKey(record: ChannelMapRecord): ChannelMapKey;
 interface ChannelMapStoreOptions {
     /** The rig peer→channel map file (`rig-channels.json`). */
     mapPath: string;
-    /** The client's nonce-watermark store (`channels.json`). */
+    /** The client's voucher watermark store (`channels-x402.json`). */
     watermarkPath: string;
 }
 /**
- * File-backed peer→channel map + read/seed access to the client's nonce
+ * File-backed peer→channel map + read/seed access to the client's voucher
  * watermark store. Synchronous I/O (matches the client's `ChannelStore`
  * surface); see the module doc for the locking and corruption contracts.
  */
@@ -359,9 +390,9 @@ declare class ChannelMapStore {
     listFor(identity: string, destination: string): ChannelMapRecord[];
     /**
      * Record a (freshly opened) channel. Overwrites any previous record under
-     * the same (identity, destination, chain, tokenNetwork) key — the old
-     * channel is closed/stale by then; its claim watermark stays in the
-     * watermark store.
+     * the same (identity, destination, chain, tokenNetwork) key; a caller that
+     * replaces a channel still holding a deposit {@link supersede}s the old
+     * record first. Its watermark stays in the watermark store.
      */
     record(record: Omit<ChannelMapRecord, 'openedAt' | 'lastUsedAt'> & Partial<Pick<ChannelMapRecord, 'openedAt' | 'lastUsedAt'>>): void;
     /**
@@ -387,13 +418,13 @@ declare class ChannelMapStore {
      */
     supersede(record: ChannelMapRecord): void;
     /**
-     * Read one channel's nonce-watermark entry from the client's
-     * `channels.json` (undefined when the file or entry is missing).
+     * Read one channel's watermark entry from the client's voucher store
+     * (undefined when the file or entry is missing).
      * @throws {ChannelMapCorruptError} when the watermark file is unreadable.
      */
     readWatermark(channelId: string): WatermarkEntry | undefined;
     /**
-     * Seed a fresh channel's watermark entry (`nonce 0, cumulative 0`) so a
+     * Seed a fresh channel's watermark entry (cumulative 0) so a
      * later resume can tell "never claimed against" apart from "watermark
      * lost". Never overwrites an existing entry.
      */
@@ -403,8 +434,8 @@ declare class ChannelMapStore {
     private readWatermarkFile;
 }
 /**
- * Where a channel sits in the withdraw journey, from its watermark timers —
- * mirrors `ChannelManager.getChannelCloseState`. A missing entry reads as
+ * Where a channel sits in the exit journey, from its watermark timers:
+ * mirrors what the client's `channel.channels()` reports. A missing entry reads as
  * `open` (recorded channels are seeded at open time; a lost watermark file
  * surfaces separately as unknown claim state).
  */
@@ -460,26 +491,26 @@ interface WalletChainBalanceInfo {
 /** Receipt of an explicit `rig channel open` (fresh open OR resume). */
 interface ChannelOpenOutcome {
     channelId: string;
-    /** True when the recorded channel was resumed (no on-chain open). */
+    /** True when the recorded channel was resumed (no open). */
     resumed: boolean;
     /** ILP anchor destination the channel is keyed by in the map. */
     destination: string;
-    /** Negotiated settlement chain, when recorded (e.g. `evm:31337`). */
+    /** The x402 network the channel lives on (e.g. `eip155:8453`). */
     chain?: string;
-    /** Registered peer id, when recorded. */
+    /** The node's sealing key id, when it publishes one. */
     peerId?: string;
     /** On-chain deposit total (base units), when known. */
     depositTotal?: string;
-    /** Extra collateral added by `--deposit` (base units), when any. */
+    /** Extra collateral added by `--deposit` (base units, Base only), when any. */
     depositAdded?: string;
     /** Tx hash of the `--deposit` top-up, when any. */
     depositTxHash?: string;
 }
-/** Receipt of a channel close (start of the settlement challenge window). */
+/** Receipt of a channel close (start of the exit window). */
 interface ChannelCloseOutcome {
     channelId: string;
     txHash?: string;
-    /** Unix SECONDS (string-encoded bigint) the close landed on-chain. */
+    /** Unix SECONDS (string-encoded bigint) the close was started. */
     closedAt: string;
     /** Unix SECONDS (string-encoded bigint) settle becomes possible. */
     settleableAt: string;
@@ -496,17 +527,20 @@ interface ChannelSettleOutcome {
  */
 interface StandaloneMoneyOps {
     /**
-     * Explicitly open (or resume) the payment channel for the context's
-     * channel anchor — the SAME resume-or-open path lazy paid writes use, so
-     * the result lands in the #262 peer→channel map. `deposit` adds that much
-     * extra collateral (base units) after the open/resume.
+     * Explicitly open (or resume) the x402 channel with the context's node:
+     * the channel lazy paid writes draw on, so the result lands in the #262
+     * peer→channel map. `deposit` adds that much extra collateral (base units)
+     * after the open/resume; only a Base channel can be topped up.
      */
     openChannel(opts?: {
         deposit?: bigint;
     }): Promise<ChannelOpenOutcome>;
-    /** Close a recorded channel — starts the on-chain challenge window. */
+    /**
+     * Close a recorded channel: starts its exit window. The client leaves
+     * every channel still open with the node in the same call.
+     */
     closeChannel(record: ChannelMapRecord): Promise<ChannelCloseOutcome>;
-    /** Settle a closed channel after its challenge window — releases funds. */
+    /** Settle a closed channel after its exit window: releases funds. */
     settleChannel(record: ChannelMapRecord): Promise<ChannelSettleOutcome>;
     /**
      * The full multi-chain wallet view (#299) for the identity's configured
@@ -520,14 +554,15 @@ interface StandaloneMoneyOps {
 /**
  * Nonce-ownership guard for the STANDALONE embedded Publisher (#228).
  *
- * Why this exists: a payment channel's balance proof is a CUMULATIVE
- * watermark — the ChannelManager auto-increments the nonce and cumulative
- * amount on every `signBalanceProof`. Two writers signing claims on the same
- * channel from separate processes (a running `toon-clientd` daemon plus a
- * standalone embedded client, or two standalone processes) each keep their
- * own cumulative counter, so their claims race: the connector sees
- * non-monotonic watermarks and a re-signed claim can double-charge (the
- * hazard documented in packages/rig-web/tests/e2e/seed/lib/publish.ts).
+ * Why this exists: every x402 voucher names the channel's CUMULATIVE total
+ * (client 4.x, connector ADR 0075; the nonce of the 3.x toon-channel claims
+ * is gone), and the connector accepts one only if it exceeds the last by at
+ * least the charge. Two writers signing vouchers on the same channel from
+ * separate processes (a running `toon-clientd` daemon plus a standalone
+ * embedded client, or two standalone processes) each keep their own running
+ * total, so their vouchers race: the connector refuses the one that does not
+ * advance, and a re-signed total can double-charge (the hazard documented in
+ * packages/rig-web/tests/e2e/seed/lib/publish.ts).
  *
  * Two independent defenses, both keyed by the Nostr pubkey (one identity =
  * one channel set):
@@ -628,4 +663,4 @@ declare class NonceLock {
     release(): void;
 }
 
-export { type AcquireLockOptions, type ChannelCloseOutcome, ChannelMapCorruptError, type ChannelMapKey, type ChannelMapRecord, ChannelMapStore, type ChannelMapStoreOptions, type ChannelOpenOutcome, type ChannelSettleOutcome, type CheckDaemonOptions, ConnectorPublishError, ConnectorPublisher, type ConnectorPublisherOptions, DEFAULT_DAEMON_PORT, DaemonIdentityConflictError, MAX_ACCOUNT_INDEX, NonceLock, type NostrKey, type PaidClientLike, type PaidFulfilled, type PaidLeg, type PaidRefused, type PaidRequest, type PaidSendOptions, type PaidSendResult, type PersistedChannelContext, RIG_CHANNEL_MAP_FILENAME, type RouteTerms, StandaloneLockError, type StandaloneMoneyOps, type WalletChainBalanceInfo, type WalletTokenAmountInfo, type WatermarkEntry, channelStatus, checkDaemonIdentity, counterpartyMatch, defaultDaemonPort, defaultLockDir, deriveNostrKeyFromMnemonic, extractArweaveTxId, nostrDerivationPath, recordKey, resolveChannelPaths, sameSettlementAddress };
+export { type AcquireLockOptions, CHANNEL_STORE_FILENAME, type ChannelCloseOutcome, ChannelMapCorruptError, type ChannelMapKey, type ChannelMapRecord, ChannelMapStore, type ChannelMapStoreOptions, type ChannelOpenOutcome, type ChannelSettleOutcome, type CheckDaemonOptions, ConnectorPublishError, ConnectorPublisher, type ConnectorPublisherOptions, DEFAULT_DAEMON_PORT, DaemonIdentityConflictError, LEGACY_CHANNEL_STORE_FILENAME, LEGACY_RIG_CHANNEL_MAP_FILENAME, MAX_ACCOUNT_INDEX, NonceLock, type NostrKey, type PaidClientLike, type PaidFulfilled, type PaidLeg, type PaidRefused, type PaidRequest, type PaidSendOptions, type PaidSendResult, type PersistedChannelContext, RIG_CHANNEL_MAP_FILENAME, type RouteTerms, StandaloneLockError, type StandaloneMoneyOps, type WalletChainBalanceInfo, type WalletTokenAmountInfo, type WatermarkEntry, channelStatus, checkDaemonIdentity, counterpartyMatch, defaultDaemonPort, defaultLockDir, deriveNostrKeyFromMnemonic, extractArweaveTxId, isToonChannelStore, legacyChannelFiles, nostrDerivationPath, recordKey, resolveChannelPaths, sameSettlementAddress };

package/dist/standalone/index.js

@@ -2,17 +2,22 @@ import {
   ConnectorPublishError,
   ConnectorPublisher,
   extractArweaveTxId
-} from "../chunk-UE5TAFEU.js";
+} from "../chunk-ZQGXFFBP.js";
 import {
+  CHANNEL_STORE_FILENAME,
   ChannelMapCorruptError,
   ChannelMapStore,
+  LEGACY_CHANNEL_STORE_FILENAME,
+  LEGACY_RIG_CHANNEL_MAP_FILENAME,
   RIG_CHANNEL_MAP_FILENAME,
   channelStatus,
   counterpartyMatch,
+  isToonChannelStore,
+  legacyChannelFiles,
   recordKey,
   resolveChannelPaths,
   sameSettlementAddress
-} from "../chunk-XCLUB2CY.js";
+} from "../chunk-LMZSAFAB.js";
 import {
   DEFAULT_DAEMON_PORT,
   DaemonIdentityConflictError,
@@ -24,14 +29,17 @@ import {
   defaultLockDir,
   deriveNostrKeyFromMnemonic,
   nostrDerivationPath
-} from "../chunk-U5A7MHBP.js";
+} from "../chunk-7VIVQHRG.js";
 export {
+  CHANNEL_STORE_FILENAME,
   ChannelMapCorruptError,
   ChannelMapStore,
   ConnectorPublishError,
   ConnectorPublisher,
   DEFAULT_DAEMON_PORT,
   DaemonIdentityConflictError,
+  LEGACY_CHANNEL_STORE_FILENAME,
+  LEGACY_RIG_CHANNEL_MAP_FILENAME,
   MAX_ACCOUNT_INDEX,
   NonceLock,
   RIG_CHANNEL_MAP_FILENAME,
@@ -43,6 +51,8 @@ export {
   defaultLockDir,
   deriveNostrKeyFromMnemonic,
   extractArweaveTxId,
+  isToonChannelStore,
+  legacyChannelFiles,
   nostrDerivationPath,
   recordKey,
   resolveChannelPaths,