@attocash/cli 0.1.1 → 0.2.0

package/dist/wallet/receive-daemon.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/wallet/receive-daemon.js

@@ -0,0 +1,63 @@
+process.env.KOTLIN_LOGGING_STARTUP_MESSAGE = 'false';
+const [directory, token] = process.argv.slice(2);
+if (directory && token) {
+    const { setTimeout: delay } = await import('node:timers/promises');
+    const { StateStore } = await import('../storage/state.js');
+    const { AttoApplication } = await import('../application/app.js');
+    const { BackgroundReceiver, requireReceivingProfile } = await import('./background-receive.js');
+    const { errorResult } = await import('../domain/errors.js');
+    let store;
+    let application;
+    let receiver;
+    let release;
+    const stop = () => receiver?.update(token, { desired: false, state: 'stopping' });
+    try {
+        store = new StateStore(directory);
+        receiver = new BackgroundReceiver(store);
+        release = receiver.claim(token);
+        if (release) {
+            requireReceivingProfile(store);
+            const owner = receiver;
+            application = new AttoApplication({
+                directory, receivingAllowed: () => !owner.stopping(token),
+                onReceiveProgress: event => owner.progress(token, event),
+            });
+            process.once('SIGINT', stop);
+            process.once('SIGTERM', stop);
+            receiver.update(token, { state: 'running' });
+            // Acknowledge local construction/ownership before starting any network or
+            // password-store operation. IPC is detached immediately after the reply.
+            if (process.connected)
+                await new Promise((resolve, reject) => {
+                    process.send({ ready: token }, error => error ? reject(error) : resolve());
+                });
+            if (process.connected)
+                process.disconnect();
+            if (!receiver.stopping(token)) {
+                void application.start().catch(error => owner.update(token, { lastError: errorResult(error) }));
+                while (!receiver.stopping(token))
+                    await delay(100);
+            }
+        }
+    }
+    catch (error) {
+        if (release)
+            receiver?.update(token, { desired: false, state: 'stopping', lastError: errorResult(error) });
+    }
+    finally {
+        // Keep ownership and stopping visible until the current receive, startup
+        // lookups, and work requests have all finished or been canceled.
+        if (release)
+            receiver?.update(token, { desired: false, state: 'stopping' });
+        await application?.close();
+        if (release)
+            receiver?.update(token, { desired: false, state: 'stopped' });
+        release?.();
+        store?.close();
+        process.removeListener('SIGINT', stop);
+        process.removeListener('SIGTERM', stop);
+        if (process.connected)
+            process.disconnect();
+    }
+}
+export {};

package/dist/wallet/work-daemon.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/wallet/work-daemon.js

@@ -0,0 +1,20 @@
+process.env.KOTLIN_LOGGING_STARTUP_MESSAGE = 'false';
+const [directory, epoch] = process.argv.slice(2);
+if (directory && epoch) {
+    const { StateStore } = await import('../storage/state.js');
+    const { WalletWork } = await import('./work.js');
+    let store;
+    let work;
+    try {
+        store = new StateStore(directory);
+        const state = store;
+        work = new WalletWork(state, () => state.get('settings'));
+        await work.runDetached(epoch);
+    }
+    catch { /* Public jobs remain eligible after startup or storage failures. */ }
+    finally {
+        await work?.close();
+        store?.close();
+    }
+}
+export {};

package/dist/wallet/work.d.ts

@@ -5,25 +5,47 @@ export interface BlockWorker {
     workBlock(block: AttoBlock, signal?: AbortSignal): Promise<AttoWork>;
     close(): void;
 }
-/** Public work only: no signer, mnemonic, or seed enters this owner. */
+export type WorkExecution = 'in-process' | 'detached';
+/** Public preparation, validation and caching. No credential or signer enters
+ * this owner. Speculative failures never escape into completed transactions. */
 export declare class WalletWork {
     private readonly store;
     private readonly settings;
-    private readonly queued;
-    private readonly pending;
-    private readonly requests;
-    private backgroundCount;
+    private readonly execution;
     private closed;
-    constructor(store: StateStore, settings: () => WalletSettings);
+    private drainTask?;
+    private resumeRequested;
+    private readonly active;
+    private readonly computations;
+    private readonly requests;
+    constructor(store: StateStore, settings: () => WalletSettings, execution?: WorkExecution);
+    private scope;
+    private nextBlock;
+    private key;
+    private head;
+    private same;
     isReady(account: AttoAccount): boolean;
     prepare(accounts: readonly AttoAccount[]): void;
+    /** A confirmed block is sufficient to prepare its successor, including after
+     * publication recovery. This unsigned change template is never published;
+     * work depends on the head, height, network and time, not its representative. */
+    prepareConfirmed(block: AttoBlock): void;
+    private enqueue;
+    /** Resume only after successful CLI input validation/operation, never in the constructor. */
+    resume(): void;
     worker(): BlockWorker;
-    close(): Promise<void>;
-    private nextBlock;
-    private key;
+    private queue;
+    /** Caller owns the short state transaction. Lower observations cannot undo
+     * newer heads; an equal-height replacement invalidates the previous fork. */
+    private observe;
     private read;
     private save;
     private obtain;
     private compute;
+    /** Release the singleton inside the final queue transaction. An enqueue is
+     * either seen by this owner or its launch candidate can become the next owner. */
+    runDetached(epoch: string): Promise<void>;
     private drain;
+    cancel(): Promise<void>;
+    close(): Promise<void>;
 }

package/dist/wallet/work.js

@@ -1,62 +1,153 @@
-import { AttoInstant, AttoWork, attoAccountChange, attoBlockWorkTarget, } from '@attocash/commons-core';
+import { spawn } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
+import { setTimeout as delay } from 'node:timers/promises';
+import { fileURLToPath } from 'node:url';
+import { performance } from 'node:perf_hooks';
+import { AttoBlock, AttoChangeBlock, AttoInstant, AttoWork, attoAccountChange, attoBlockWorkTarget, toAttoHeight } from '@attocash/commons-core';
 import { requestWork } from '../network/work.js';
 import { AttoError } from '../domain/errors.js';
-const BACKGROUND_LIMIT = 2;
+const QUEUE_KEY = 'work.queue';
+const EPOCH_KEY = 'work.epoch';
 const QUEUE_LIMIT = 100;
-/** Public work only: no signer, mnemonic, or seed enters this owner. */
+const CONCURRENCY = 2;
+const SPECULATIVE_MS = 10_000;
+const WORKER_MS = 60_000;
+/** Public preparation, validation and caching. No credential or signer enters
+ * this owner. Speculative failures never escape into completed transactions. */
 export class WalletWork {
     store;
     settings;
-    queued = new Map();
-    pending = new Map();
-    requests = new Set();
-    backgroundCount = 0;
+    execution;
     closed = false;
-    constructor(store, settings) {
+    drainTask;
+    resumeRequested = false;
+    active = new Set();
+    computations = new Map();
+    requests = new Set();
+    constructor(store, settings, execution = 'in-process') {
         this.store = store;
         this.settings = settings;
+        this.execution = execution;
+    }
+    scope() {
+        const { network, nodeUrl, workerUrl } = this.settings();
+        return JSON.stringify([this.store.get(EPOCH_KEY) ?? null, this.store.get('identity') ?? null, network, nodeUrl, workerUrl]);
+    }
+    nextBlock(account) {
+        return attoAccountChange(account, account.representativeAddress, AttoInstant.Companion.now().toString()).block;
     }
+    key(block) { return `work.${block.network.name}.${block.publicKey}`; }
+    head(block) { return { scope: this.scope(), target: attoBlockWorkTarget(block), height: block.height.toString() }; }
+    same(left, right) { return left.scope === right.scope && left.target === right.target && left.height === right.height; }
     isReady(account) {
-        if (this.closed || account.network.name !== this.settings().network)
+        try {
+            return !this.closed && account.network.name === this.settings().network && Boolean(this.read(this.nextBlock(account)));
+        }
+        catch {
             return false;
-        return this.read(this.nextBlock(account)) !== undefined;
+        }
     }
     prepare(accounts) {
+        try {
+            this.enqueue(accounts.map(account => this.nextBlock(account)));
+        }
+        catch { /* Public preparation must not change a completed payment's result. */ }
+    }
+    /** A confirmed block is sufficient to prepare its successor, including after
+     * publication recovery. This unsigned change template is never published;
+     * work depends on the head, height, network and time, not its representative. */
+    prepareConfirmed(block) {
+        try {
+            this.enqueue([new AttoChangeBlock(block.network, block.version, block.algorithm, block.publicKey, toAttoHeight((BigInt(block.height.toString()) + 1n).toString()), block.balance, AttoInstant.Companion.now(), block.hash, block.algorithm, block.publicKey)]);
+        }
+        catch { /* Even template/storage failures are optional after confirmation. */ }
+    }
+    enqueue(blocks) {
         if (this.closed)
             return;
-        for (const account of accounts) {
-            if (account.network.name !== this.settings().network)
-                continue;
-            const block = this.nextBlock(account);
-            if (this.read(block))
-                continue;
-            const key = this.key(block);
-            if (this.queued.size < QUEUE_LIMIT || this.queued.has(key))
-                this.queued.set(key, block);
-        }
-        this.drain();
+        try {
+            this.store.transaction(() => {
+                if (!this.store.get(EPOCH_KEY))
+                    this.store.set(EPOCH_KEY, randomUUID());
+                let queue = this.queue();
+                for (const block of blocks) {
+                    if (block.network.name !== this.settings().network)
+                        continue;
+                    const key = this.key(block);
+                    const head = this.head(block);
+                    if (!this.observe(key, head))
+                        continue;
+                    queue = queue.filter(job => job.scope === head.scope);
+                    const position = queue.findIndex(job => job.key === key);
+                    if (this.read(block)) {
+                        queue = queue.filter(job => job.key !== key || !this.same(job, head));
+                    }
+                    else if (position !== -1) {
+                        if (!this.same(queue[position], head))
+                            queue[position] = { ...head, key, id: randomUUID(), block: block.toJson() };
+                    }
+                    else if (queue.length < QUEUE_LIMIT)
+                        queue.push({ ...head, key, id: randomUUID(), block: block.toJson() });
+                }
+                this.store.set(QUEUE_KEY, queue);
+            });
+            this.resume();
+        }
+        catch { /* A completed transaction survives speculative storage/launch failures. */ }
+    }
+    /** Resume only after successful CLI input validation/operation, never in the constructor. */
+    resume() {
+        if (this.closed)
+            return;
+        try {
+            if (!this.queue().length)
+                return;
+            if (this.execution === 'detached') {
+                // Always launch a candidate after enqueueing. The child checks ownership
+                // in the same state transaction used by the draining owner's exit.
+                const child = spawn(process.execPath, [fileURLToPath(new URL('./work-daemon.js', import.meta.url)), this.store.directory, this.store.get(EPOCH_KEY) ?? ''], {
+                    detached: true, stdio: 'ignore', windowsHide: true,
+                });
+                child.on('error', () => { });
+                child.unref();
+            }
+            else if (this.drainTask)
+                this.resumeRequested = true;
+            else {
+                this.resumeRequested = false;
+                this.drainTask = this.drain().catch(() => { }).finally(() => {
+                    this.drainTask = undefined;
+                    if (this.resumeRequested)
+                        this.resume();
+                });
+            }
+        }
+        catch { /* Pending jobs remain eligible on a later invocation. */ }
     }
     worker() {
-        // A signing operation borrows this cache; only the application closes it.
         return { workBlock: (block, signal) => this.obtain(block, false, signal), close() { } };
     }
-    async close() {
-        this.closed = true;
-        this.queued.clear();
-        for (const request of this.requests)
-            request.abort();
-        await Promise.allSettled([...this.pending.values()].map(job => job.promise));
+    queue() {
+        const value = this.store.get(QUEUE_KEY);
+        if (!Array.isArray(value))
+            return [];
+        return value.filter((job) => job !== null && typeof job === 'object'
+            && ['id', 'key', 'scope', 'target', 'block'].every(key => typeof job[key] === 'string')
+            && typeof job.height === 'string' && /^\d+$/.test(job.height)).slice(0, QUEUE_LIMIT);
     }
-    nextBlock(account) {
-        // Commons constructs the next-head target and validates its own work. This
-        // unsigned block is only a work request; it is never signed or published.
-        return attoAccountChange(account, account.representativeAddress, AttoInstant.Companion.now().toString()).block;
+    /** Caller owns the short state transaction. Lower observations cannot undo
+     * newer heads; an equal-height replacement invalidates the previous fork. */
+    observe(key, head) {
+        const prior = this.store.get('head.' + key);
+        if (prior?.scope === head.scope && /^\d+$/.test(prior.height) && BigInt(prior.height) > BigInt(head.height))
+            return false;
+        this.store.set('head.' + key, head);
+        return true;
     }
-    key(block) { return `work.${block.network.name}.${block.publicKey.toString()}`; }
     read(block) {
         try {
             const record = this.store.get(this.key(block));
-            if (!record || record.target !== attoBlockWorkTarget(block) || !/^[0-9a-f]{16}$/i.test(record.work))
+            if (!record || !this.same(record, this.head(block)) || !/^[0-9a-f]{16}$/i.test(record.work))
                 return;
             const work = AttoWork.Companion.parse(record.work);
             return work.isValid(block) ? work : undefined;
@@ -65,63 +156,126 @@ export class WalletWork {
             return undefined;
         }
     }
-    save(block, work) {
-        if (this.closed || block.network.name !== this.settings().network)
+    save(block, head, work) {
+        if (this.closed || this.scope() !== head.scope)
             return;
-        const key = this.key(block);
         this.store.transaction(() => {
-            const prior = this.store.get(key);
-            // An older in-flight job must not displace work for a newer account head,
-            // including work another CLI/MCP process has already persisted.
-            if (prior && /^\d+$/.test(prior.height) && BigInt(prior.height) > BigInt(block.height.toString()))
+            const observed = this.store.get('head.' + this.key(block));
+            if (observed && !this.same(observed, head))
                 return;
-            this.store.set(key, { target: attoBlockWorkTarget(block), height: block.height.toString(), work: work.toString() });
+            this.store.set(this.key(block), { scope: head.scope, target: head.target, height: head.height, work: work.toString() });
+            this.store.set(QUEUE_KEY, this.queue().filter(job => job.key !== this.key(block) || !this.same(job, head)));
         });
     }
-    async obtain(block, speculative = false, signal) {
-        if (this.closed)
-            throw new AttoError('WORK_CLOSED', 'The wallet work cache is closed.');
-        const settings = this.settings();
-        if (block.network.name !== settings.network)
-            throw new AttoError('NETWORK_MISMATCH', 'Work must use the configured wallet network.');
-        const ready = this.read(block);
-        if (ready)
-            return ready;
-        const key = `${this.key(block)}.${attoBlockWorkTarget(block)}`;
-        const existing = this.pending.get(key);
+    async obtain(block, speculative, signal) {
+        // Establish the shared generation before any computation takes its lock.
+        // Otherwise a first enqueue could change its scope while foreground work
+        // was already running under an uninitialized generation.
+        if (!this.store.get(EPOCH_KEY)) {
+            try {
+                this.store.transaction(() => { if (!this.store.get(EPOCH_KEY))
+                    this.store.set(EPOCH_KEY, randomUUID()); });
+            }
+            catch { /* Foreground work can still use its ordinary uncached fallback. */ }
+        }
+        const key = this.scope() + ':' + this.key(block) + ':' + attoBlockWorkTarget(block);
+        const existing = this.computations.get(key);
         if (existing) {
+            let cancel;
             try {
-                const work = await existing.promise;
-                // A job begun before a threshold change may no longer satisfy this block.
+                const cancelled = new Promise((_, reject) => {
+                    cancel = () => reject(new AttoError('CANCELLED', 'Send cancelled.'));
+                    if (signal?.aborted)
+                        cancel();
+                    else
+                        signal?.addEventListener('abort', cancel, { once: true });
+                });
+                const work = await Promise.race([existing.promise, cancelled]);
                 if (work.isValid(block))
                     return work;
             }
             catch (error) {
-                // Speculation has a shorter deadline. A real transaction retains the
-                // normal worker budget if that earlier background attempt failed.
-                if (speculative || !existing.speculative)
+                if (signal?.aborted || speculative || !existing.speculative)
                     throw error;
             }
+            finally {
+                if (cancel)
+                    signal?.removeEventListener('abort', cancel);
+            }
         }
-        if (this.closed)
-            throw new AttoError('WORK_CLOSED', 'The wallet work cache is closed.');
-        const job = { promise: this.compute(block, settings.workerUrl, speculative ? 10 : 60, signal), speculative };
-        this.pending.set(key, job);
+        const operation = this.compute(block, speculative, signal);
+        this.active.add(operation);
+        const computation = { promise: operation, speculative };
+        this.computations.set(key, computation);
         try {
-            return await job.promise;
+            return await operation;
         }
         finally {
-            if (this.pending.get(key) === job)
-                this.pending.delete(key);
+            this.active.delete(operation);
+            if (this.computations.get(key) === computation)
+                this.computations.delete(key);
         }
     }
-    async compute(block, url, timeoutSeconds, signal) {
+    async compute(block, speculative, signal) {
+        if (this.closed)
+            throw new AttoError('WORK_CLOSED', 'The wallet work cache is closed.');
+        const settings = this.settings();
+        if (block.network.name !== settings.network)
+            throw new AttoError('NETWORK_MISMATCH', 'Work must use the configured wallet network.');
+        const head = this.head(block);
         const controller = new AbortController();
         this.requests.add(controller);
-        const timer = setTimeout(() => controller.abort(), timeoutSeconds * 1000);
+        const combined = AbortSignal.any([controller.signal, ...(signal ? [signal] : [])]);
+        let timer = setTimeout(() => controller.abort(), speculative ? SPECULATIVE_MS : WORKER_MS);
+        let release;
+        let slot;
         try {
-            const work = await requestWork(block, url, AbortSignal.any([controller.signal, ...(signal ? [signal] : [])]));
-            this.save(block, work);
+            if (!speculative) {
+                try {
+                    this.store.transaction(() => this.observe(this.key(block), head));
+                }
+                catch { /* Coordination/cache failure falls back to foreground generation. */ }
+            }
+            for (;;) {
+                combined.throwIfAborted();
+                if (this.scope() !== head.scope)
+                    throw new AttoError('WORK_OBSOLETE', 'Wallet configuration changed during work preparation.');
+                const ready = this.read(block);
+                if (ready)
+                    return ready;
+                try {
+                    release = this.store.tryWorkLock(head.scope + ':' + this.key(block) + ':' + head.target);
+                }
+                catch (error) {
+                    if (speculative)
+                        throw error;
+                    break;
+                }
+                if (release)
+                    break;
+                await delay(25, undefined, { signal: combined });
+            }
+            if (speculative) {
+                while (!slot) {
+                    for (let index = 0; index < CONCURRENCY && !slot; index++)
+                        slot = this.store.tryWorkLock('speculative-slot-' + index);
+                    if (!slot)
+                        await delay(25, undefined, { signal: combined });
+                }
+            }
+            else {
+                // Waiting for speculation does not consume the normal generation budget.
+                clearTimeout(timer);
+                timer = setTimeout(() => controller.abort(), WORKER_MS);
+            }
+            const ready = this.read(block);
+            if (ready)
+                return ready;
+            const work = await requestWork(block, settings.workerUrl, combined);
+            try {
+                this.save(block, head, work);
+            }
+            catch { /* The validated nonce remains usable. */ }
             return work;
         }
         catch (error) {
@@ -138,17 +292,92 @@ export class WalletWork {
         finally {
             clearTimeout(timer);
             this.requests.delete(controller);
+            slot?.();
+            release?.();
         }
     }
-    drain() {
-        while (!this.closed && this.backgroundCount < BACKGROUND_LIMIT && this.queued.size > 0) {
-            const [key, block] = this.queued.entries().next().value;
-            this.queued.delete(key);
-            this.backgroundCount++;
-            void this.obtain(block, true).catch(() => { }).finally(() => {
-                this.backgroundCount--;
-                this.drain();
-            });
+    /** Release the singleton inside the final queue transaction. An enqueue is
+     * either seen by this owner or its launch candidate can become the next owner. */
+    async runDetached(epoch) {
+        let release;
+        this.store.transaction(() => {
+            if (this.store.get(EPOCH_KEY) === epoch)
+                release = this.store.tryProcessLock('work-daemon');
+        });
+        if (!release)
+            return;
+        const unlock = () => { release?.(); release = undefined; };
+        try {
+            await this.drain(epoch, unlock);
+        }
+        finally {
+            await this.close();
+            unlock();
+        }
+    }
+    async drain(epoch = this.store.get(EPOCH_KEY), unlock) {
+        const attempted = new Set();
+        const pending = new Map();
+        const started = performance.now();
+        try {
+            for (;;) {
+                if (this.closed || this.store.get(EPOCH_KEY) !== epoch || (unlock && performance.now() - started >= WORKER_MS))
+                    break;
+                const jobs = this.store.transaction(() => {
+                    const queue = this.queue().filter(job => job.scope === this.scope());
+                    this.store.set(QUEUE_KEY, queue);
+                    const next = queue.filter(job => !attempted.has(job.id)).slice(0, CONCURRENCY - pending.size);
+                    if (!next.length && !pending.size)
+                        unlock?.();
+                    return next;
+                });
+                if (!jobs.length && !pending.size)
+                    return;
+                for (const job of jobs) {
+                    attempted.add(job.id);
+                    const task = (async () => {
+                        const template = AttoBlock.fromJson(job.block);
+                        if (!(template instanceof AttoChangeBlock))
+                            return;
+                        const block = new AttoChangeBlock(template.network, template.version, template.algorithm, template.publicKey, template.height, template.balance, AttoInstant.Companion.now(), template.previous, template.representativeAlgorithm, template.representativePublicKey);
+                        const observed = this.store.get('head.' + job.key);
+                        if (this.key(block) !== job.key || !this.same(this.head(block), job) || (observed && !this.same(observed, job)))
+                            return;
+                        const work = await this.obtain(block, true);
+                        // Cache hits also remove jobs left by interrupted owners.
+                        this.save(block, job, work);
+                    })().catch(() => { }).finally(() => pending.delete(job.id));
+                    pending.set(job.id, task);
+                }
+                await Promise.race([...pending.values(), delay(25)]);
+            }
         }
+        finally {
+            if (unlock)
+                for (const controller of this.requests)
+                    controller.abort();
+            await Promise.allSettled([...pending.values()]);
+        }
+    }
+    async cancel() {
+        this.store.transaction(() => { this.store.set(EPOCH_KEY, randomUUID()); this.store.set(QUEUE_KEY, []); });
+        await this.close();
+        const deadline = performance.now() + 5000;
+        for (;;) {
+            const release = this.store.tryProcessLock('work-daemon');
+            if (release) {
+                release();
+                return;
+            }
+            if (performance.now() >= deadline)
+                throw new AttoError('WALLET_BUSY', 'Public work preparation is still stopping. Retry wallet reset.');
+            await delay(25);
+        }
+    }
+    async close() {
+        this.closed = true;
+        for (const controller of this.requests)
+            controller.abort();
+        await Promise.allSettled([...this.active, ...(this.drainTask ? [this.drainTask] : [])]);
     }
 }

package/dist/watches/manager.d.ts

@@ -28,7 +28,7 @@ export declare class WatchManager {
         } | undefined;
         id: string;
         filter: StreamFilter;
-        status: "running" | "reconnecting" | "stopped" | "completed";
+        status: "reconnecting" | "running" | "stopped" | "completed";
         createdAt: string;
         reconnects: number;
         replayable: boolean;
@@ -40,7 +40,7 @@ export declare class WatchManager {
         } | undefined;
         id: string;
         filter: StreamFilter;
-        status: "running" | "reconnecting" | "stopped" | "completed";
+        status: "reconnecting" | "running" | "stopped" | "completed";
         createdAt: string;
         reconnects: number;
         replayable: boolean;
@@ -60,7 +60,7 @@ export declare class WatchManager {
         } | undefined;
         id: string;
         filter: StreamFilter;
-        status: "running" | "reconnecting" | "stopped" | "completed";
+        status: "reconnecting" | "running" | "stopped" | "completed";
         createdAt: string;
         reconnects: number;
         replayable: boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@attocash/cli",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "Atto wallet CLI and reusable wallet engine with local key custody and shared spending limits",
   "license": "BSD-3-Clause",
   "type": "module",