@attocash/cli 0.1.0

package/dist/labels/presentation.js

@@ -0,0 +1,90 @@
+import { AttoAlgorithm, AttoPublicKey } from '@attocash/commons-core';
+import { parseAddress } from '../network/reader.js';
+import { DIRECTORY_URL } from './directory.js';
+export function modelAddress(value, prefix = '') {
+    const publicKey = value[prefix ? `${prefix}PublicKey` : 'publicKey'];
+    const algorithm = value[prefix ? `${prefix}Algorithm` : 'algorithm'];
+    if (typeof publicKey !== 'string' || typeof algorithm !== 'string')
+        return;
+    try {
+        return AttoPublicKey.Companion.parse(publicKey).toAddress(AttoAlgorithm.valueOf(algorithm)).value;
+    }
+    catch {
+        return;
+    }
+}
+/** Read protocol keys without rewriting network objects or interpreting metadata. */
+export function resultAddresses(value) {
+    const addresses = new Set();
+    const visit = (value) => {
+        if (typeof value === 'string' && value.startsWith('atto://')) {
+            try {
+                addresses.add(parseAddress(value).value);
+            }
+            catch { /* Not an address. */ }
+        }
+        else if (Array.isArray(value))
+            value.forEach(visit);
+        else if (value && typeof value === 'object') {
+            const object = value;
+            for (const prefix of ['', 'receiver', 'representative', 'subject']) {
+                const address = modelAddress(object, prefix);
+                if (address)
+                    addresses.add(address);
+            }
+            for (const [key, child] of Object.entries(object)) {
+                if (!['metadata', 'blockJson', 'destinationBinding', 'addressLabels', 'globalDirectory'].includes(key))
+                    visit(child);
+            }
+        }
+    };
+    visit(value);
+    return [...addresses];
+}
+export class AddressLabels {
+    personal;
+    global;
+    constructor(personal, global) {
+        this.personal = personal;
+        this.global = global;
+    }
+    dictionary(network, addresses) {
+        const personal = new Map(this.personal.list(network).map(row => [row.address, row.label]));
+        const { snapshot, status } = this.global.cached();
+        const entries = network === 'LIVE' && snapshot ? [
+            ...snapshot.addresses.map(value => ({ ...value, kind: 'address' })),
+            ...snapshot.voters.map(value => ({ ...value, kind: 'voter' })),
+        ] : [];
+        const entities = new Map(snapshot?.entities.map(value => [value.entity, value]));
+        return Object.fromEntries([...new Set(addresses)].map(address => [address, {
+                ...(personal.has(address) ? { personal: { source: 'personal', label: personal.get(address) } } : {}),
+                global: entries.filter(entry => entry.address === address).map(entry => ({ ...entry, source: DIRECTORY_URL,
+                    entityInfo: entities.get(entry.entity), stale: status.stale })),
+                // A payout relationship says nothing about ownership of its destination.
+                payoutFor: entries.filter(entry => 'payToAddress' in entry && entry.payToAddress === address)
+                    .map(entry => ({ voterAddress: entry.address, label: entry.label, entity: entry.entity, source: DIRECTORY_URL, stale: status.stale })),
+            }]));
+    }
+    status(network) { return network === 'LIVE' ? this.global.cached().status : { network: 'LIVE', applicable: false }; }
+    list(network, all = false, search) {
+        const addresses = this.personal.list(network).map(row => row.address);
+        if (all && network === 'LIVE') {
+            const snapshot = this.global.cached().snapshot;
+            addresses.push(...(snapshot?.addresses.map(row => row.address) ?? []), ...(snapshot?.voters.map(row => row.address) ?? []));
+        }
+        const dictionary = this.dictionary(network, addresses);
+        const term = search?.trim().toLowerCase();
+        const items = Object.entries(dictionary).filter(([address, labels]) => !term || [address, labels.personal?.label,
+            ...labels.global.flatMap(row => [row.label, row.entity, row.entityInfo?.label, row.entityInfo?.organization])]
+            .some(value => value?.toLowerCase().includes(term))).map(([address]) => ({ address }));
+        return { network, items, addressLabels: Object.fromEntries(items.map(({ address }) => [address, dictionary[address]])), globalDirectory: this.status(network) };
+    }
+    decorate(result, network) {
+        if (Array.isArray(result))
+            return result.map(value => this.decorate(value, network));
+        const addresses = resultAddresses(result);
+        if (!addresses.length || !result || typeof result !== 'object' || Array.isArray(result))
+            return result;
+        return { ...result, addressLabels: this.dictionary(network, addresses), globalDirectory: this.status(network) };
+    }
+}

package/dist/network/reader.d.ts

@@ -0,0 +1,31 @@
+import { AttoAccount, AttoAccountEntry, AttoAddress, AttoInstant, AttoReceivable, AttoTransaction } from '@attocash/commons-core';
+import type { ListRequest, StreamFilter, WalletSettings } from '../wallet/types.js';
+type Model = AttoAccount | AttoAccountEntry | AttoReceivable | AttoTransaction;
+export declare function publicModel(model: unknown): unknown;
+export declare function parseAddress(value: string): AttoAddress;
+export declare function normalizeFilter(filter: StreamFilter): StreamFilter;
+export declare function isReplayable(filter: StreamFilter): boolean;
+export declare function eventPosition(model: unknown): {
+    address: string;
+    height: string;
+} | undefined;
+export declare class NodeReader {
+    readonly settings: WalletSettings;
+    private readonly headers;
+    constructor(settings: WalletSettings, headers?: Record<string, string>);
+    private request;
+    private get;
+    account(address: string, signal?: AbortSignal): Promise<AttoAccount | null>;
+    now(signal?: AbortSignal): Promise<AttoInstant>;
+    transaction(hash: string, signal?: AbortSignal): Promise<AttoTransaction | null>;
+    entry(hash: string, signal?: AbortSignal): Promise<AttoAccountEntry | null>;
+    voterWeight(address: string): Promise<unknown>;
+    stream(filter: StreamFilter, onEvent: (model: Model) => void, signal: AbortSignal): Promise<void>;
+    list(request: ListRequest, signal?: AbortSignal): Promise<{
+        items: unknown[];
+        nextCursor?: string;
+        timedOut: boolean;
+        limitReached?: boolean;
+    }>;
+}
+export {};

package/dist/network/reader.js

@@ -0,0 +1,370 @@
+import { createHash } from 'node:crypto';
+import { createRequire } from 'node:module';
+import { AttoAccount, AttoAccountEntry, AttoAddress, AttoAmount, AttoHash, AttoInstant, AttoTransaction, AttoUnit, toAttoHeight } from '@attocash/commons-core';
+import { AccountHeightSearch, HeightSearch } from '@attocash/commons-node';
+import { AttoNodeClientAsyncBuilder } from '@attocash/commons-node-remote';
+import { AttoError } from '../domain/errors.js';
+import { amountRaw } from '../domain/amount.js';
+// Ktor's Node engine uses require while Commons is imported as ESM.
+Object.assign(globalThis, { require: createRequire(import.meta.url) });
+const MAX_RESPONSE_BYTES = 1024 * 1024;
+const MAX_HEIGHT = 18446744073709551615n;
+const numericStrings = new Set(['amount', 'balance', 'previousBalance', 'height', 'fromHeight', 'toHeight', 'weight']);
+function jsonExact(text) {
+    return JSON.parse(text, (key, value, context) => {
+        if (typeof value === 'number' && (numericStrings.has(key) || !Number.isSafeInteger(value))) {
+            if (!context?.source)
+                throw new AttoError('UNSUPPORTED_RUNTIME', 'Exact JSON numbers require Node.js 24 or later.');
+            return context.source;
+        }
+        return value;
+    });
+}
+export function publicModel(model) {
+    if (model === null || model === undefined)
+        return null;
+    if (typeof model === 'object' && 'toJson' in model && typeof model.toJson === 'function') {
+        return jsonExact(model.toJson());
+    }
+    return jsonExact(JSON.stringify(model, (_key, value) => typeof value === 'bigint' ? value.toString() : value));
+}
+export function parseAddress(value) {
+    try {
+        return AttoAddress.parse(value);
+    }
+    catch {
+        throw new AttoError('INVALID_ADDRESS', 'Provide a valid Atto address.');
+    }
+}
+function parseHash(value) {
+    if (!/^[0-9a-fA-F]{64}$/.test(value))
+        throw new AttoError('INVALID_HASH', 'Provide a 64-character hexadecimal hash.');
+    return value.toUpperCase();
+}
+function height(value, allowZero = false) {
+    if (!/^\d+$/.test(value) || BigInt(value) > MAX_HEIGHT || (!allowZero && BigInt(value) === 0n)) {
+        throw new AttoError('INVALID_HEIGHT', 'Height must be a positive unsigned 64-bit integer string.');
+    }
+    return BigInt(value).toString();
+}
+export function normalizeFilter(filter) {
+    if (!['account', 'transaction', 'entry', 'receivable'].includes(filter.event)) {
+        throw new AttoError('INVALID_FILTER', 'Unknown network event type.');
+    }
+    const addresses = filter.addresses?.length ? [...new Set(filter.addresses.map(value => parseAddress(value).value))] : undefined;
+    if (addresses && addresses.length > 100)
+        throw new AttoError('INVALID_FILTER', 'Use at most 100 addresses per request.');
+    if (filter.hash && (addresses || !['transaction', 'entry'].includes(filter.event))) {
+        throw new AttoError('INVALID_FILTER', 'Hash filters support transactions or entries and cannot include addresses.');
+    }
+    if ((filter.fromHeight || filter.toHeight) && (!addresses || !['transaction', 'entry'].includes(filter.event))) {
+        throw new AttoError('INVALID_FILTER', 'Height ranges require address-specific transactions or entries.');
+    }
+    if (filter.event === 'receivable' && !addresses)
+        throw new AttoError('INVALID_FILTER', 'Receivable streams require at least one address.');
+    if (filter.minAmountRaw !== undefined && filter.event !== 'receivable') {
+        throw new AttoError('INVALID_FILTER', 'Minimum amounts apply only to receivables.');
+    }
+    const fromHeight = addresses && ['transaction', 'entry'].includes(filter.event) ? height(filter.fromHeight ?? '1') : undefined;
+    const toHeight = filter.toHeight !== undefined ? height(filter.toHeight) : undefined;
+    if (fromHeight && toHeight && BigInt(fromHeight) > BigInt(toHeight))
+        throw new AttoError('INVALID_HEIGHT', 'From height must not exceed to height.');
+    return {
+        event: filter.event,
+        ...(addresses ? { addresses } : {}),
+        ...(filter.hash ? { hash: parseHash(filter.hash) } : {}),
+        ...(fromHeight ? { fromHeight } : {}),
+        ...(toHeight ? { toHeight } : {}),
+        ...(filter.event === 'receivable' ? { minAmountRaw: amountRaw(filter.minAmountRaw ?? '0', 'RAW', true) } : {}),
+    };
+}
+export function isReplayable(filter) {
+    return Boolean(filter.addresses?.length && ['transaction', 'entry'].includes(filter.event));
+}
+export function eventPosition(model) {
+    if (typeof model !== 'object' || model === null || !('address' in model) || !('height' in model))
+        return;
+    const address = model.address;
+    return { address: address.value, height: String(model.height) };
+}
+export class NodeReader {
+    settings;
+    headers;
+    constructor(settings, headers = {}) {
+        this.settings = settings;
+        this.headers = headers;
+    }
+    async request(path, signal, firstEvent) {
+        try {
+            const response = await fetch(`${this.settings.nodeUrl.replace(/\/$/, '')}/${path}`, {
+                redirect: 'error', signal,
+                headers: { ...this.headers, accept: firstEvent ? 'application/x-ndjson' : 'application/json' },
+            });
+            if (!response.ok) {
+                await response.body?.cancel();
+                throw new AttoError(response.status === 404 ? 'NOT_FOUND' : 'NODE_HTTP_ERROR', `The node returned HTTP ${response.status}.`, { httpStatus: response.status });
+            }
+            return response;
+        }
+        catch (error) {
+            if (error instanceof AttoError)
+                throw error;
+            if (signal.aborted)
+                throw new AttoError('CANCELLED', 'The network request was cancelled.');
+            throw new AttoError('NODE_UNAVAILABLE', 'The node could not be reached.');
+        }
+    }
+    // Commons' Promise reads do not expose cancellation or HTTP status; finite
+    // lookups retain those caller contracts here.
+    async get(path, parse, signal, firstEvent = false) {
+        const timeout = AbortSignal.timeout(10_000);
+        const combined = signal ? AbortSignal.any([signal, timeout]) : timeout;
+        try {
+            const response = await this.request(path, combined, firstEvent);
+            let body = '';
+            const decoder = new TextDecoder();
+            let size = 0;
+            if (!response.body)
+                throw new AttoError('INVALID_NODE_RESPONSE', 'The node response has no body.');
+            const reader = response.body.getReader();
+            try {
+                while (true) {
+                    const { value, done } = await reader.read();
+                    if (done)
+                        break;
+                    size += value.length;
+                    if (size > MAX_RESPONSE_BYTES)
+                        throw new AttoError('INVALID_NODE_RESPONSE', 'The node response exceeded the size limit.');
+                    body += decoder.decode(value, { stream: true });
+                    if (firstEvent && body.includes('\n')) {
+                        body = body.slice(0, body.indexOf('\n'));
+                        break;
+                    }
+                }
+            }
+            finally {
+                await reader.cancel().catch(() => undefined);
+                reader.releaseLock();
+            }
+            body += decoder.decode();
+            if (firstEvent && !body.trim())
+                return null;
+            try {
+                return parse(body);
+            }
+            catch {
+                throw new AttoError('INVALID_NODE_RESPONSE', 'The node returned an invalid response.');
+            }
+        }
+        catch (error) {
+            if (error instanceof AttoError && error.code === 'NOT_FOUND')
+                return null;
+            if (signal?.aborted)
+                throw new AttoError('CANCELLED', 'The network request was cancelled.');
+            if (timeout.aborted)
+                throw new AttoError('NODE_TIMEOUT', 'The node request timed out.');
+            if (error instanceof AttoError)
+                throw error;
+            throw new AttoError('NODE_UNAVAILABLE', 'The node connection failed.');
+        }
+    }
+    account(address, signal) {
+        return this.get(`accounts/${parseAddress(address).publicKey}`, AttoAccount.fromJson, signal);
+    }
+    async now(signal) {
+        const requested = AttoInstant.Companion.now().toString();
+        const result = await this.get(`instants/${encodeURIComponent(requested)}`, text => {
+            const value = JSON.parse(text);
+            if (typeof value.clientInstant !== 'string' || typeof value.serverInstant !== 'string'
+                || AttoInstant.Companion.fromIso(value.clientInstant).toEpochMilliseconds() !== AttoInstant.Companion.fromIso(requested).toEpochMilliseconds())
+                throw new Error();
+            return AttoInstant.Companion.fromIso(value.serverInstant);
+        }, signal);
+        if (!result)
+            throw new AttoError('NODE_TIME_UNAVAILABLE', 'The node time API is unavailable. Check the configured node URL.');
+        return result;
+    }
+    transaction(hash, signal) {
+        return this.get(`transactions/${parseHash(hash)}`, AttoTransaction.fromJson, signal);
+    }
+    entry(hash, signal) {
+        return this.get(`accounts/entries/${parseHash(hash)}/stream`, AttoAccountEntry.fromJson, signal, true);
+    }
+    voterWeight(address) {
+        return this.get(`vote-weights/${parseAddress(address).path}`, jsonExact);
+    }
+    async stream(filter, onEvent, signal) {
+        const normalized = normalizeFilter(filter);
+        if (signal.aborted)
+            return;
+        const builder = new AttoNodeClientAsyncBuilder(this.settings.nodeUrl);
+        for (const [name, value] of Object.entries(this.headers))
+            builder.header(name, value);
+        const client = builder.build();
+        const addresses = normalized.addresses?.map(parseAddress);
+        const one = addresses?.length === 1 ? addresses[0] : undefined;
+        const hash = normalized.hash ? AttoHash.Companion.parse(normalized.hash) : undefined;
+        let job;
+        let callbackFailure;
+        let complete;
+        const cancel = () => {
+            // Cancellation before Commons starts its coroutine may omit onCancel.
+            // Joining the job also settles that case and waits for transport cleanup.
+            void job?.cancelAndJoin().then(() => complete(), complete);
+        };
+        const emit = (model) => {
+            if (signal.aborted || callbackFailure)
+                return;
+            // Commons catches Kotlin exceptions; a JS callback error must not escape
+            // into its coroutine and leave the subscription promise unresolved.
+            try {
+                onEvent(model);
+            }
+            catch (error) {
+                callbackFailure = { error };
+                cancel();
+            }
+        };
+        try {
+            await new Promise((resolve, reject) => {
+                complete = (error) => {
+                    if (callbackFailure)
+                        reject(callbackFailure.error);
+                    else if (error && !signal.aborted)
+                        reject(error);
+                    else
+                        resolve();
+                };
+                if (normalized.event === 'receivable') {
+                    const minimum = AttoAmount.from(AttoUnit.RAW, normalized.minAmountRaw);
+                    job = one
+                        ? client.onReceivableByPublicKey(one.publicKey, minimum, emit, complete)
+                        : client.onReceivableByAddresses(addresses, minimum, emit, complete);
+                }
+                else if (normalized.event === 'account') {
+                    job = one ? client.onAccountByPublicKey(one.publicKey, emit, complete)
+                        : addresses ? client.onAccountByAddresses(addresses, emit, complete)
+                            : client.onAccountAll(emit, complete);
+                }
+                else {
+                    const from = toAttoHeight(normalized.fromHeight ?? '1');
+                    const to = normalized.toHeight ? toAttoHeight(normalized.toHeight) : undefined;
+                    const search = addresses && !one ? HeightSearch.Companion.fromArray(addresses.map(address => new AccountHeightSearch(address, from, to))) : undefined;
+                    if (normalized.event === 'entry') {
+                        job = hash ? client.onAccountEntryByHash(hash, emit, complete)
+                            : one ? client.onAccountEntryByPublicKey(one.publicKey, from, to, emit, complete)
+                                : search ? client.onAccountEntryByHeightSearch(search, emit, complete)
+                                    : client.onAccountEntryAll(emit, complete);
+                    }
+                    else {
+                        job = hash ? client.onTransactionByHash(hash, emit, complete)
+                            : one ? client.onTransactionByPublicKey(one.publicKey, from, to, emit, complete)
+                                : search ? client.onTransactionByHeightSearch(search, emit, complete)
+                                    : client.onTransactionAll(emit, complete);
+                    }
+                }
+                signal.addEventListener('abort', cancel, { once: true });
+                if (signal.aborted)
+                    cancel();
+            });
+        }
+        catch (error) {
+            if (signal.aborted)
+                return;
+            if (error instanceof AttoError)
+                throw error;
+            // SDK errors may include URLs, headers, and response bodies. Keep them private.
+            throw new AttoError('NODE_STREAM_ERROR', 'The node stream failed. Check endpoint availability and node responses.');
+        }
+        finally {
+            signal.removeEventListener('abort', cancel);
+            await job?.cancelAndJoin();
+        }
+    }
+    async list(request, signal) {
+        const filter = normalizeFilter(request);
+        const limit = request.limit ?? 100;
+        const timeoutMs = request.timeoutMs ?? 3_000;
+        if (!Number.isInteger(limit) || limit < 1 || limit > 1000 || !Number.isInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 60_000) {
+            throw new AttoError('INVALID_LIST', 'Use a limit from 1 to 1000 and timeoutMs from 1 to 60000.');
+        }
+        const timeout = AbortSignal.timeout(timeoutMs);
+        const done = new AbortController();
+        const combined = AbortSignal.any([timeout, done.signal, ...(signal ? [signal] : [])]);
+        const items = [];
+        if (!isReplayable(filter)) {
+            if (request.cursor)
+                throw new AttoError('INVALID_CURSOR', 'Continuation cursors require address-specific transaction or entry history.');
+            await this.stream(filter, model => { items.push(publicModel(model)); if (items.length === limit)
+                done.abort(); }, combined);
+            if (signal?.aborted)
+                throw new AttoError('CANCELLED', 'The network request was cancelled.');
+            return { items, timedOut: timeout.aborted && !done.signal.aborted, ...(done.signal.aborted ? { limitReached: true } : {}) };
+        }
+        const scope = createHash('sha256').update(JSON.stringify([this.settings.nodeUrl, this.settings.network, filter])).digest('hex');
+        const addresses = filter.addresses;
+        let cursor = { version: 1, scope, addressIndex: 0, nextHeight: filter.fromHeight, upper: addresses.map(() => null) };
+        if (request.cursor) {
+            try {
+                if (request.cursor.length > 20_000)
+                    throw new Error();
+                const parsed = JSON.parse(Buffer.from(request.cursor, 'base64url').toString('utf8'));
+                if (parsed.version !== 1 || parsed.scope !== scope || !Number.isInteger(parsed.addressIndex) || parsed.addressIndex < 0 || parsed.addressIndex >= addresses.length || !Array.isArray(parsed.upper) || parsed.upper.length !== addresses.length)
+                    throw new Error();
+                height(parsed.nextHeight);
+                for (const upper of parsed.upper)
+                    if (upper !== null)
+                        height(upper, true);
+                cursor = parsed;
+            }
+            catch {
+                throw new AttoError('INVALID_CURSOR', 'The continuation cursor is invalid or belongs to a different query.');
+            }
+        }
+        try {
+            while (cursor.addressIndex < addresses.length && !combined.aborted) {
+                const index = cursor.addressIndex;
+                const address = addresses[index];
+                if (cursor.upper[index] === null) {
+                    const current = await this.account(address, combined);
+                    const currentHeight = current ? BigInt(String(current.height)) : 0n;
+                    cursor.upper[index] = (filter.toHeight && BigInt(filter.toHeight) < currentHeight ? BigInt(filter.toHeight) : currentHeight).toString();
+                }
+                const upper = cursor.upper[index];
+                if (BigInt(cursor.nextHeight) <= BigInt(upper)) {
+                    await this.stream({ ...filter, addresses: [address], fromHeight: cursor.nextHeight, toHeight: upper }, model => {
+                        const position = eventPosition(model);
+                        if (!position || position.address !== address || BigInt(position.height) > BigInt(upper))
+                            throw new AttoError('INVALID_NODE_RESPONSE', 'The node returned an event outside the requested account range.');
+                        if (BigInt(position.height) < BigInt(cursor.nextHeight))
+                            return;
+                        // Each account stream is height ordered. Never advance over a missing block.
+                        if (position.height !== cursor.nextHeight)
+                            throw new AttoError('HISTORY_GAP', 'The node returned a gap in account history. Retry with a fully synchronized node.');
+                        items.push(publicModel(model));
+                        cursor.nextHeight = (BigInt(position.height) + 1n).toString();
+                        if (items.length === limit)
+                            done.abort();
+                    }, combined);
+                }
+                if (BigInt(cursor.nextHeight) > BigInt(upper)) {
+                    cursor.addressIndex++;
+                    cursor.nextHeight = filter.fromHeight;
+                }
+                else if (!combined.aborted) {
+                    throw new AttoError('HISTORY_GAP', 'The node closed the stream before the requested history was complete.');
+                }
+            }
+        }
+        catch (error) {
+            if (!combined.aborted)
+                throw error;
+        }
+        if (signal?.aborted)
+            throw new AttoError('CANCELLED', 'The network request was cancelled.');
+        return {
+            items, timedOut: timeout.aborted && !done.signal.aborted,
+            ...(cursor.addressIndex < addresses.length ? { nextCursor: Buffer.from(JSON.stringify(cursor)).toString('base64url') } : {}),
+        };
+    }
+}

package/dist/network/retry.d.ts

@@ -0,0 +1,7 @@
+import { AttoError } from '../domain/errors.js';
+export interface SendRetry {
+    signal: AbortSignal;
+    onRetry: (error: AttoError, delayMs: number) => void;
+}
+/** Retry only a network operation, never rebuild a signed payment. Opt-in for CLI sends. */
+export declare function retryNetwork<T>(operation: () => Promise<T>, retry?: SendRetry): Promise<T>;

package/dist/network/retry.js

@@ -0,0 +1,53 @@
+import { setTimeout as delay } from 'node:timers/promises';
+import { AttoError } from '../domain/errors.js';
+function networkError(error) {
+    if (error instanceof AttoError)
+        return error;
+    if (!(error instanceof Error))
+        return;
+    // Commons exposes standard Error names, but not a public JS HTTP status
+    // accessor. Never inspect Kotlin internals or print dependency messages.
+    if (error.name === 'ClientRequestException')
+        return new AttoError('NODE_CLIENT_ERROR', 'The node returned an HTTP 4xx error.');
+    if (error.name === 'ServerResponseException')
+        return new AttoError('NODE_SERVER_ERROR', 'The node returned an HTTP 5xx error.');
+    if (['HttpRequestTimeoutException', 'ConnectTimeoutException', 'SocketTimeoutException'].includes(error.name)) {
+        return new AttoError('NODE_TIMEOUT', 'The node request timed out.');
+    }
+    if ((error.name === 'TypeError' && error.message === 'fetch failed')
+        || (error.cause instanceof Error && error.cause.name === 'TypeError' && error.cause.message === 'fetch failed')
+        || error.name === 'EOFException') {
+        return new AttoError('NODE_UNAVAILABLE', 'The node connection failed.');
+    }
+}
+function retryable(error) {
+    const status = error.details?.httpStatus;
+    if (status !== undefined)
+        return status >= 500 && status <= 599;
+    return ['NODE_SERVER_ERROR', 'NODE_TIMEOUT', 'NODE_UNAVAILABLE', 'WORK_TIMEOUT', 'WORK_FAILED', 'MARKET_DATA_UNAVAILABLE'].includes(error.code);
+}
+/** Retry only a network operation, never rebuild a signed payment. Opt-in for CLI sends. */
+export async function retryNetwork(operation, retry) {
+    let delayMs = 1000;
+    for (;;) {
+        if (retry?.signal.aborted)
+            throw new AttoError('CANCELLED', 'Send cancelled.');
+        try {
+            return await operation();
+        }
+        catch (error) {
+            if (!retry)
+                throw error;
+            if (retry.signal.aborted)
+                throw new AttoError('CANCELLED', 'Send cancelled.');
+            const failure = networkError(error);
+            if (!failure || !retryable(failure))
+                throw failure ?? error;
+            retry.onRetry(failure, delayMs);
+            await delay(delayMs, undefined, { signal: retry.signal }).catch(() => {
+                throw new AttoError('CANCELLED', 'Send cancelled.');
+            });
+            delayMs = Math.min(delayMs * 2, 30_000);
+        }
+    }
+}

package/dist/network/work.d.ts

@@ -0,0 +1,3 @@
+import { AttoBlock, AttoWork } from '@attocash/commons-core';
+/** Request and validate public work without caching, signing, or wallet state. */
+export declare function requestWork(block: AttoBlock, url: string, signal: AbortSignal): Promise<AttoWork>;

package/dist/network/work.js

@@ -0,0 +1,66 @@
+import { AttoWork, attoBlockWorkTarget } from '@attocash/commons-core';
+import { AttoError } from '../domain/errors.js';
+const RESPONSE_LIMIT = 2048;
+/** Request and validate public work without caching, signing, or wallet state. */
+export async function requestWork(block, url, signal) {
+    try {
+        const timestamp = Number(block.timestamp.toEpochMilliseconds());
+        if (!Number.isSafeInteger(timestamp))
+            throw new AttoError('INVALID_WORK', 'The work timestamp cannot be represented exactly.');
+        // Commons WorkerOperations.Request serializes this public network/time/
+        // target tuple. Fetch supplies cancellation absent from its JS worker API.
+        const response = await fetch(`${url.replace(/\/+$/, '')}/works`, {
+            method: 'POST', redirect: 'error', signal,
+            headers: { 'content-type': 'application/json', accept: 'application/json' },
+            body: JSON.stringify({ network: block.network.name, timestamp, target: attoBlockWorkTarget(block) }),
+        });
+        if (!response.ok) {
+            await response.body?.cancel();
+            throw new AttoError('WORK_FAILED', `The worker returned HTTP ${response.status}.`, { httpStatus: response.status });
+        }
+        const value = await readResponse(response);
+        if (typeof value !== 'object' || value === null || !('work' in value)
+            || typeof value.work !== 'string' || !/^[0-9a-f]{16}$/i.test(value.work)) {
+            throw new AttoError('INVALID_WORK', 'The worker returned malformed proof of work.');
+        }
+        const work = AttoWork.Companion.parse(value.work);
+        if (!work.isValid(block))
+            throw new AttoError('INVALID_WORK', 'The worker returned invalid proof of work.');
+        return work;
+    }
+    catch (error) {
+        if (signal.aborted)
+            throw new AttoError('WORK_TIMEOUT', 'The work request was cancelled or timed out.');
+        if (error instanceof AttoError)
+            throw error;
+        throw new AttoError('WORK_FAILED', 'Proof-of-work generation failed. Check the worker endpoint. Run doctor for diagnostics.');
+    }
+}
+async function readResponse(response) {
+    if (!response.body)
+        throw new AttoError('INVALID_WORK', 'The worker returned an empty response.');
+    const reader = response.body.getReader();
+    const chunks = [];
+    let size = 0;
+    try {
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            size += value.byteLength;
+            if (size > RESPONSE_LIMIT)
+                throw new AttoError('INVALID_WORK', 'The worker response exceeds the allowed size.');
+            chunks.push(value);
+        }
+        try {
+            return JSON.parse(Buffer.concat(chunks).toString('utf8'));
+        }
+        catch {
+            throw new AttoError('INVALID_WORK', 'The worker returned malformed JSON.');
+        }
+    }
+    finally {
+        await reader.cancel().catch(() => undefined);
+        reader.releaseLock();
+    }
+}

package/dist/pricing/market.d.ts

@@ -0,0 +1,29 @@
+export declare const DEFAULT_METRICS_URL = "https://gatekeeper.live.application.atto.cash/projections/metrics";
+export interface MarketMetric {
+    name: string;
+    date: string;
+    value: string;
+}
+export interface MarketMetrics {
+    metrics: MarketMetric[];
+    source: string;
+    fetchedAt: string;
+}
+export declare class MarketData {
+    private readonly fetchImpl;
+    private readonly source;
+    constructor(url?: string, fetchImpl?: typeof fetch);
+    metrics(signal?: AbortSignal): Promise<MarketMetrics>;
+    quoteUsd(amount: string, signal?: AbortSignal): Promise<{
+        usd: string;
+        priceUsd: string;
+        priceDate: string;
+        source: string;
+        fetchedAt: string;
+        amount: {
+            raw: string;
+            atto: string;
+        };
+        informational: true;
+    }>;
+}