@toon-protocol/rig 2.0.1 → 2.2.0

package/dist/standalone/index.d.ts

@@ -1,7 +1,266 @@
 import { ToonClientConfig, SignedBalanceProof, PublishEventResult } from '@toon-protocol/client';
-import { U as UnsignedEvent, P as Publisher, F as FeeRates, G as GitObjectUpload, a as UploadReceipt, b as PublishReceipt } from '../publisher-CClD9OIZ.js';
+import { U as UnsignedEvent, P as Publisher, F as FeeRates, G as GitObjectUpload, a as UploadReceipt, b as PublishReceipt } from '../publisher-CrwaNQrK.js';
 import '@toon-protocol/core/nip34';
 
+/**
+ * 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.
+ *
+ * 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.
+ * `@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
+ * serializes this file for one identity. `rig channel list` reads only.
+ *
+ * CORRUPTION: an unreadable/invalid map file is a hard
+ * {@link ChannelMapCorruptError} — surfaced BEFORE any on-chain open — never
+ * an empty fallback. Falling back to "no channels" would silently open (and
+ * fund) a duplicate channel, which is exactly the #262 bug.
+ *
+ * This module is dependency-light on purpose (node:fs only): the free
+ * `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";
+/**
+ * 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).
+ */
+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).
+ */
+interface PersistedChannelContext {
+    chainType: string;
+    chainId: number;
+    tokenNetworkAddress: string;
+    tokenAddress?: string;
+    /** Counterparty settlement address (required for Solana/Mina proofs). */
+    recipient?: string;
+}
+/** One persisted peer→channel binding. */
+interface ChannelMapRecord {
+    /** On-chain payment channel id. */
+    channelId: string;
+    /** Registered peer id the negotiation was keyed by (`peerNegotiations`). */
+    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`. */
+    chain: string;
+    /** TokenNetwork contract address ('' when the peer announced none). */
+    tokenNetwork: string;
+    /** Context for `trackChannel` on resume. */
+    context: PersistedChannelContext;
+    /** On-chain deposit total (base units, string), when known. */
+    depositTotal?: string;
+    /** ISO timestamps. */
+    openedAt: string;
+    lastUsedAt: string;
+}
+/** The composite key a record is stored under. */
+interface ChannelMapKey {
+    identity: string;
+    destination: string;
+    chain: string;
+    tokenNetwork: string;
+}
+/**
+ * One entry of the client's nonce-watermark store (`channels.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). */
+    cumulativeAmount: string;
+    /** Withdraw-flow timers, string-encoded unix SECONDS. */
+    closedAt?: string;
+    settleableAt?: string;
+    settledAt?: string;
+}
+/** The peer→channel map file is unreadable or malformed. */
+declare class ChannelMapCorruptError extends Error {
+    readonly path: string;
+    constructor(path: string, detail: string);
+}
+/** The key fields of a full record. */
+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`). */
+    watermarkPath: string;
+}
+/**
+ * File-backed peer→channel map + read/seed access to the client's nonce
+ * watermark store. Synchronous I/O (matches the client's `ChannelStore`
+ * surface); see the module doc for the locking and corruption contracts.
+ */
+declare class ChannelMapStore {
+    readonly mapPath: string;
+    readonly watermarkPath: string;
+    constructor(options: ChannelMapStoreOptions);
+    /** All recorded channels. @throws {ChannelMapCorruptError} */
+    list(): ChannelMapRecord[];
+    /**
+     * Recorded channels for one (identity, destination) pair — the resume
+     * candidates for a paid command. @throws {ChannelMapCorruptError}
+     */
+    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.
+     */
+    record(record: Omit<ChannelMapRecord, 'openedAt' | 'lastUsedAt'> & Partial<Pick<ChannelMapRecord, 'openedAt' | 'lastUsedAt'>>): void;
+    /**
+     * Bump a record's `lastUsedAt` (and optionally its known on-chain deposit)
+     * after resuming it. Unknown keys are a no-op.
+     */
+    touch(key: ChannelMapKey, update?: {
+        depositTotal?: string;
+    }): void;
+    /**
+     * Read one channel's nonce-watermark entry from the client's
+     * `channels.json` (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
+     * later resume can tell "never claimed against" apart from "watermark
+     * lost". Never overwrites an existing entry.
+     */
+    seedWatermark(channelId: string): void;
+    private readMap;
+    private writeMap;
+    private readWatermarkFile;
+}
+/**
+ * Where a channel sits in the withdraw journey, from its watermark timers —
+ * mirrors `ChannelManager.getChannelCloseState`. A missing entry reads as
+ * `open` (recorded channels are seeded at open time; a lost watermark file
+ * surfaces separately as unknown claim state).
+ */
+declare function channelStatus(entry: WatermarkEntry | undefined, nowSec?: number): 'open' | 'closing' | 'settleable' | 'settled';
+
+/**
+ * Dependency-light types for the client money lifecycle (#263): the seam
+ * between the money CLI commands (`rig fund` / `rig balance` /
+ * `rig channel open|close|settle`) and the standalone publisher's money
+ * operations.
+ *
+ * Lives beside channel-map.ts (not in standalone-publisher.ts) so
+ * `cli/standalone-context.ts` — which command modules `import type` without
+ * dragging in `@toon-protocol/client` — can reference these shapes: the
+ * publisher module statically imports the heavy client package, this module
+ * imports nothing but the (node:fs-only) channel map types.
+ */
+
+/**
+ * One on-chain wallet token balance — structural twin of
+ * `@toon-protocol/client`'s `WalletBalance` (`balance/WalletBalanceReader.ts`,
+ * not exported from the package root); keep in sync.
+ */
+interface WalletBalanceInfo {
+    chain: 'evm' | 'solana' | 'mina';
+    address: string;
+    /** Base-unit integer, decimal string. */
+    amount: string;
+    /** Token symbol, when resolved (e.g. `'USDC'`, `'MINA'`). */
+    asset?: string;
+    /** Token decimals, when resolved. */
+    assetScale?: number;
+}
+/** 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). */
+    resumed: boolean;
+    /** ILP anchor destination the channel is keyed by in the map. */
+    destination: string;
+    /** Negotiated settlement chain, when recorded (e.g. `evm:31337`). */
+    chain?: string;
+    /** Registered peer id, when recorded. */
+    peerId?: string;
+    /** On-chain deposit total (base units), when known. */
+    depositTotal?: string;
+    /** Extra collateral added by `--deposit` (base units), 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). */
+interface ChannelCloseOutcome {
+    channelId: string;
+    txHash?: string;
+    /** Unix SECONDS (string-encoded bigint) the close landed on-chain. */
+    closedAt: string;
+    /** Unix SECONDS (string-encoded bigint) settle becomes possible. */
+    settleableAt: string;
+}
+/** Receipt of a channel settle (collateral released). */
+interface ChannelSettleOutcome {
+    channelId: string;
+    txHash?: string;
+}
+/**
+ * The money operations a standalone context exposes to the CLI commands.
+ * Implemented by `StandalonePublisher` (guard + client start shared with the
+ * paid-write path); tests inject fakes.
+ */
+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.
+     */
+    openChannel(opts?: {
+        deposit?: bigint;
+    }): Promise<ChannelOpenOutcome>;
+    /** Close a recorded channel — starts the on-chain challenge window. */
+    closeChannel(record: ChannelMapRecord): Promise<ChannelCloseOutcome>;
+    /** Settle a closed channel after its challenge window — releases funds. */
+    settleChannel(record: ChannelMapRecord): Promise<ChannelSettleOutcome>;
+    /**
+     * On-chain wallet balances for the identity's configured chains — a FREE
+     * read (no client start, no nonce guard, no uplink). Best-effort per chain.
+     */
+    walletBalances(): Promise<WalletBalanceInfo[]>;
+}
+
 /**
  * StandalonePublisher — impl 2 of the {@link Publisher} seam (#228): an
  * EMBEDDED ToonClient constructed from the caller's config (mnemonic +
@@ -27,6 +286,12 @@ import '@toon-protocol/core/nip34';
  * guard (./nonce-guard.ts): refuse if a toon-clientd holds this identity,
  * and hold an exclusive per-pubkey lockfile against other standalone
  * processes for the lifetime of this publisher.
+ *
+ * Channel REUSE (#262): with a `channelMap` configured, start() resumes the
+ * channel recorded for (identity, channel anchor) — `trackChannel` rehydrates
+ * the cumulative-claim watermark from the client's channels.json — and
+ * records any fresh lazy open, so sequential CLI invocations share ONE
+ * on-chain channel instead of stranding a deposit per run (./channel-map.ts).
  */
 
 /** A fully-signed Nostr event (structural subset of nostr-tools' NostrEvent). */
@@ -53,6 +318,34 @@ interface ToonClientLike {
         ilpAmount?: bigint;
         proxyPath?: string;
     }): Promise<PublishEventResult>;
+    /** On-chain deposit total for a tracked channel (channel-map bookkeeping). */
+    getChannelDepositTotal?(channelId: string): bigint;
+    /** Re-read a RESUMED channel's on-chain deposit (persisted state omits it). */
+    rehydrateChannelDeposit?(channelId: string, opts: {
+        chain: string;
+        tokenNetworkAddress: string;
+    }): Promise<bigint | undefined>;
+    /** Deposit extra collateral (base-unit delta) into an open channel. */
+    depositToChannel?(channelId: string, amount: string | bigint): Promise<{
+        channelId: string;
+        txHash?: string;
+        depositTotal: string;
+    }>;
+    /** Close a channel — starts the settlement challenge window (on-chain). */
+    closeChannel?(channelId: string): Promise<{
+        channelId: string;
+        txHash?: string;
+        /** Unix SECONDS, string-encoded. */
+        closedAt: string;
+        settleableAt: string;
+    }>;
+    /** Settle a closed channel after its window — releases funds (on-chain). */
+    settleChannel?(channelId: string): Promise<{
+        channelId: string;
+        txHash?: string;
+    }>;
+    /** Free on-chain wallet-balance read (works on an UNSTARTED client). */
+    getBalances?(): Promise<WalletBalanceInfo[]>;
 }
 interface StandalonePublisherOptions {
     /**
@@ -89,6 +382,28 @@ interface StandalonePublisherOptions {
     lockDir?: string;
     /** Fetch impl for the daemon probe (tests). */
     fetchImpl?: typeof fetch;
+    /**
+     * Peer→channel map store (#262): start() resumes the channel recorded for
+     * (identity, channel anchor) instead of opening a fresh one, and records
+     * any fresh lazy open for the next invocation. Absent (embedded callers
+     * managing their own channel lifecycle): the historical behaviour — open
+     * lazily every run, record nothing.
+     */
+    channelMap?: ChannelMapStore;
+    /**
+     * Per-chain settlement parameters to BACK-FILL into the client's peer
+     * negotiations after start (#264/#260): peers whose kind:10032 announce
+     * carries no `tokenNetworks`/`preferredTokens` negotiate with those fields
+     * empty, and the on-chain channel open then fails ("tokenNetwork address
+     * is required"). Values here never override what a peer DID announce —
+     * they only fill gaps, keyed by the negotiated chain id.
+     */
+    negotiationFallbacks?: {
+        tokenNetworks?: Record<string, string>;
+        preferredTokens?: Record<string, string>;
+    };
+    /** Sink for non-fatal channel-persistence warnings (default: stderr). */
+    warn?: (line: string) => void;
 }
 /** A relay/store rejected a paid write (fee NOT spent iff the claim failed too). */
 declare class StandalonePublishError extends Error {
@@ -124,9 +439,18 @@ declare class StandalonePublisher implements Publisher {
     private readonly daemonPort;
     private readonly lockDir;
     private readonly fetchImpl;
+    private readonly channelMap;
+    /** ILP anchor the channel is keyed by in the map (peer/apex destination). */
+    private readonly channelAnchor;
+    private readonly negotiationFallbacks;
+    private readonly warn;
     private lock;
     private channelId;
     private readyPromise;
+    /** Guard + client start only (no channel) — see {@link startClientOnly}. */
+    private clientReadyPromise;
+    /** True when the last start() RESUMED the recorded channel (#263). */
+    private lastOpenResumed;
     constructor(options: StandalonePublisherOptions);
     /** Hex Nostr pubkey of the embedded identity (available before start). */
     getPublicKey(): string;
@@ -136,9 +460,86 @@ declare class StandalonePublisher implements Publisher {
      * eagerly to fail fast. Idempotent.
      */
     start(): Promise<void>;
-    private doStart;
+    /**
+     * Run the nonce guard and start the embedded client WITHOUT touching the
+     * payment channel (#263): `channel close`/`settle` operate on a RECORDED
+     * channel and must never open a fresh one as a side effect of starting.
+     * Idempotent; `start()` layers the channel open/resume on top of this.
+     */
+    startClientOnly(): Promise<void>;
+    private doStartClient;
+    /**
+     * Back-fill negotiated peer metadata the announce did not carry
+     * (#264/#260 root cause 3): after the client's bootstrap negotiation, any
+     * peer negotiation missing `tokenNetwork`/`tokenAddress` gets the derived
+     * per-chain fallback for its negotiated chain, BEFORE the lazy channel
+     * open reads them. Announced values are never overridden.
+     */
+    private applyNegotiationFallbacks;
+    /**
+     * Open the payment channel — or, when the channel map has a record for
+     * (identity, anchor), RESUME the recorded on-chain channel (#262).
+     *
+     * Resume seeds the client's ChannelManager (`trackChannel` rehydrates the
+     * cumulative-claim watermark from channels.json; `peerChannels` makes the
+     * subsequent `openChannel` return the same id instead of opening on-chain).
+     * A fresh open is RECORDED so the next invocation resumes it. A corrupt map
+     * file throws BEFORE anything is opened — never a silent duplicate open.
+     */
+    private openOrResumeChannel;
+    /**
+     * Try to resume one recorded channel: the first candidate whose peer is
+     * still negotiated on the SAME chain + tokenNetwork and whose watermark
+     * does not show it closed/settled. Returns the resumed record, if any.
+     */
+    private resumeRecordedChannel;
+    /** Record a freshly opened channel (+ seed its claim watermark at 0/0). */
+    private recordOpenedChannel;
     /** Release the identity lock and stop the embedded client (if we own it). */
     stop(): Promise<void>;
+    /**
+     * Explicit `rig channel open`: the SAME resume-or-open path the lazy paid
+     * writes use (guard → start → resume the recorded channel or open + record
+     * a fresh one), surfaced with a receipt — plus an optional extra collateral
+     * deposit on top of the open/resume.
+     */
+    openChannelExplicit(opts?: {
+        /** Extra collateral to deposit AFTER the open/resume (base units). */
+        deposit?: bigint;
+    }): Promise<ChannelOpenOutcome>;
+    /**
+     * Adopt a RECORDED channel into the running client so on-chain close/
+     * settle/deposit can act on it: `trackChannel` rehydrates the claim
+     * watermark + withdraw timers from channels.json, `peerChannels` binds the
+     * peer, and the on-chain client's context cache is re-seeded (it only
+     * learns context at open time — a resumed channel would otherwise throw
+     * "No on-chain context").
+     */
+    private adoptRecordedChannel;
+    /**
+     * Close a recorded channel: starts the on-chain settlement challenge
+     * window. The client persists `closedAt`/`settleableAt` into the claim
+     * watermark store, which is exactly where `rig channel list`/`balance`
+     * derive the closing/settleable/settled status from. Guard + client start,
+     * but NEVER a channel open ({@link startClientOnly}).
+     */
+    closeRecordedChannel(record: ChannelMapRecord): Promise<ChannelCloseOutcome>;
+    /**
+     * Settle a recorded channel after its challenge window — releases the
+     * remaining collateral. The client enforces the `now >= settleableAt` time
+     * guard BEFORE spending gas (a too-early call throws its retryable
+     * SettleTooEarlyError) and persists `settledAt` into the watermark store.
+     */
+    settleRecordedChannel(record: ChannelMapRecord): Promise<ChannelSettleOutcome>;
+    /**
+     * On-chain wallet balances for the embedded identity — a FREE read on the
+     * UNSTARTED client (no nonce guard, no uplink, no channel): the client
+     * reads the settlement chain its channels actually use (its EVM key is
+     * derived at construction; Solana/Mina keys only exist after a start, so
+     * those chains appear once a start-requiring command ran — same
+     * best-effort contract as the client's own getBalances).
+     */
+    readWalletBalances(): Promise<WalletBalanceInfo[]>;
     /**
      * Fee rates for `planPush` estimation: the flat per-event fee and the
      * per-byte upload rate this publisher pays (daemon `feePerEvent` and seed
@@ -182,6 +583,12 @@ declare class StandalonePublisher implements Publisher {
  *  1. Daemon detection — probe the toon-clientd loopback control API
  *     (`GET /status`) and REFUSE when it reports the SAME identity. A daemon
  *     on a different identity holds different channels and is harmless.
+ *     Since #279 the CLI's paid WRITE commands never get here with a
+ *     same-identity daemon up — they delegate to its `/git/*` routes first
+ *     (`cli/daemon-session.ts`), which achieves the same one-writer goal by
+ *     handing the watermark to the daemon. This guard remains the backstop
+ *     for the probe→publish race window and for operations with no daemon
+ *     route (channel close/settle, explicit open).
  *  2. Advisory lockfile — an exclusive per-pubkey lockfile under the shared
  *     `~/.toon-client` state dir so two STANDALONE processes can't race each
  *     other (the daemon check only covers the daemon). Stale locks (dead pid)
@@ -269,4 +676,4 @@ declare class NonceLock {
     release(): void;
 }
 
-export { type AcquireLockOptions, type CheckDaemonOptions, DEFAULT_DAEMON_PORT, DaemonIdentityConflictError, NonceLock, type SignedNostrEvent, StandaloneLockError, StandalonePublishError, StandalonePublisher, type StandalonePublisherOptions, type ToonClientLike, checkDaemonIdentity, defaultDaemonPort, defaultLockDir, deriveRouteDestinations, extractArweaveTxId };
+export { type AcquireLockOptions, type ChannelCloseOutcome, ChannelMapCorruptError, type ChannelMapKey, type ChannelMapRecord, ChannelMapStore, type ChannelMapStoreOptions, type ChannelOpenOutcome, type ChannelSettleOutcome, type CheckDaemonOptions, DEFAULT_DAEMON_PORT, DaemonIdentityConflictError, NonceLock, type PersistedChannelContext, RIG_CHANNEL_MAP_FILENAME, type SignedNostrEvent, StandaloneLockError, type StandaloneMoneyOps, StandalonePublishError, StandalonePublisher, type StandalonePublisherOptions, type ToonClientLike, type WalletBalanceInfo, type WatermarkEntry, channelStatus, checkDaemonIdentity, defaultDaemonPort, defaultLockDir, deriveRouteDestinations, extractArweaveTxId, recordKey, resolveChannelPaths };

package/dist/standalone/index.js

@@ -1,28 +1,42 @@
 import {
+  StandalonePublishError,
+  StandalonePublisher,
+  deriveRouteDestinations,
+  extractArweaveTxId
+} from "../chunk-OIJNRACA.js";
+import {
+  ChannelMapCorruptError,
+  ChannelMapStore,
   DEFAULT_DAEMON_PORT,
   DaemonIdentityConflictError,
   NonceLock,
+  RIG_CHANNEL_MAP_FILENAME,
   StandaloneLockError,
-  StandalonePublishError,
-  StandalonePublisher,
+  channelStatus,
   checkDaemonIdentity,
   defaultDaemonPort,
   defaultLockDir,
-  deriveRouteDestinations,
-  extractArweaveTxId
-} from "../chunk-XRRU6YBQ.js";
+  recordKey,
+  resolveChannelPaths
+} from "../chunk-SW7ZHMGS.js";
 import "../chunk-X2CZPPDM.js";
 export {
+  ChannelMapCorruptError,
+  ChannelMapStore,
   DEFAULT_DAEMON_PORT,
   DaemonIdentityConflictError,
   NonceLock,
+  RIG_CHANNEL_MAP_FILENAME,
   StandaloneLockError,
   StandalonePublishError,
   StandalonePublisher,
+  channelStatus,
   checkDaemonIdentity,
   defaultDaemonPort,
   defaultLockDir,
   deriveRouteDestinations,
-  extractArweaveTxId
+  extractArweaveTxId,
+  recordKey,
+  resolveChannelPaths
 };
 //# sourceMappingURL=index.js.map