@attocash/cli 0.1.0

package/dist/pricing/market.js

@@ -0,0 +1,150 @@
+import { amountOutput, amountRaw } from '../domain/amount.js';
+import { AttoError } from '../domain/errors.js';
+export const DEFAULT_METRICS_URL = 'https://gatekeeper.live.application.atto.cash/projections/metrics';
+const MAX_RESPONSE_BYTES = 1_048_576;
+// Projections are dated daily, so accept a UTC metric date at most 72 hours old.
+const MAX_PRICE_AGE_MS = 72 * 60 * 60 * 1000;
+const RAW_PER_ATTO = 1000000000n;
+function decimal(value) {
+    // Bound parsing work while preserving substantially more precision than RAW.
+    if (typeof value !== 'string' || !/^\d{1,40}(?:\.\d{1,40})?$/.test(value))
+        throw new Error('Invalid decimal');
+    const [whole, fraction = ''] = value.split('.');
+    return { coefficient: BigInt(`${whole}${fraction}`), scale: 10n ** BigInt(fraction.length) };
+}
+export class MarketData {
+    fetchImpl;
+    source;
+    constructor(url = DEFAULT_METRICS_URL, fetchImpl = fetch) {
+        this.fetchImpl = fetchImpl;
+        let parsed;
+        try {
+            parsed = new URL(url);
+        }
+        catch {
+            throw new AttoError('INVALID_MARKET_URL', 'Market data requires an HTTPS URL without credentials.');
+        }
+        if (parsed.protocol !== 'https:' || parsed.username || parsed.password)
+            throw new AttoError('INVALID_MARKET_URL', 'Market data requires an HTTPS URL without credentials.');
+        this.source = parsed.href;
+    }
+    async metrics(signal) {
+        let payload;
+        try {
+            const response = await this.fetchImpl(this.source, {
+                signal: AbortSignal.any([AbortSignal.timeout(10_000), ...(signal ? [signal] : [])]),
+                headers: { Accept: 'application/json' },
+                credentials: 'omit',
+                redirect: 'error',
+            });
+            if (!response.ok || !response.body) {
+                await response.body?.cancel();
+                throw new AttoError('MARKET_DATA_UNAVAILABLE', 'Market data is currently unavailable.', { httpStatus: response.status });
+            }
+            if (Number(response.headers.get('content-length') ?? 0) > MAX_RESPONSE_BYTES) {
+                await response.body.cancel();
+                throw new AttoError('MARKET_DATA_INVALID', 'The market-data response exceeds the supported size.');
+            }
+            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 > MAX_RESPONSE_BYTES) {
+                        await reader.cancel();
+                        throw new AttoError('MARKET_DATA_INVALID', 'The market-data response exceeds the supported size.');
+                    }
+                    chunks.push(value);
+                }
+            }
+            finally {
+                reader.releaseLock();
+            }
+            const bytes = new Uint8Array(size);
+            let offset = 0;
+            for (const chunk of chunks) {
+                bytes.set(chunk, offset);
+                offset += chunk.byteLength;
+            }
+            try {
+                payload = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(bytes));
+            }
+            catch {
+                throw new AttoError('MARKET_DATA_INVALID', 'The market-data response is not valid JSON.');
+            }
+        }
+        catch (error) {
+            if (error instanceof AttoError)
+                throw error;
+            throw new AttoError('MARKET_DATA_UNAVAILABLE', 'Market data could not be retrieved within ten seconds.');
+        }
+        if (!payload || typeof payload !== 'object' || !('metrics' in payload) || !Array.isArray(payload.metrics)) {
+            throw new AttoError('MARKET_DATA_INVALID', 'The market-data response must contain a metrics array.');
+        }
+        const metrics = payload.metrics.map((metric) => {
+            if (!metric || typeof metric !== 'object' || !('name' in metric) || typeof metric.name !== 'string'
+                || !('date' in metric) || typeof metric.date !== 'string' || !('value' in metric) || typeof metric.value !== 'string') {
+                throw new AttoError('MARKET_DATA_INVALID', 'Each market metric requires a name, date, and string value.');
+            }
+            return { name: metric.name, date: metric.date, value: metric.value };
+        });
+        return { metrics, source: this.source, fetchedAt: new Date().toISOString() };
+    }
+    async quoteUsd(amount, signal) {
+        let usd;
+        try {
+            usd = decimal(amount);
+            if (usd.coefficient <= 0n)
+                throw new Error();
+        }
+        catch {
+            throw new AttoError('INVALID_USD_AMOUNT', 'USD amount must be a positive decimal string with at most 40 digits on either side of the decimal point.');
+        }
+        const snapshot = await this.metrics(signal);
+        const prices = snapshot.metrics.filter((metric) => metric.name === 'price.usd');
+        const price = prices[0];
+        if (prices.length !== 1 || !price)
+            throw new AttoError('INVALID_PRICE', 'Market data must contain exactly one USD price.');
+        let ratio;
+        try {
+            ratio = decimal(price.value);
+            if (ratio.coefficient <= 0n)
+                throw new Error();
+        }
+        catch {
+            throw new AttoError('INVALID_PRICE', 'The USD price must be a positive decimal string.');
+        }
+        const priceTime = Date.parse(`${price.date}T00:00:00.000Z`);
+        if (!/^\d{4}-\d{2}-\d{2}$/.test(price.date) || !Number.isFinite(priceTime) || new Date(priceTime).toISOString().slice(0, 10) !== price.date) {
+            throw new AttoError('INVALID_PRICE', 'The USD price requires a valid UTC calendar date.');
+        }
+        const age = Date.parse(snapshot.fetchedAt) - priceTime;
+        if (age < 0)
+            throw new AttoError('PRICE_FUTURE', 'The USD price has a future date.');
+        if (age > MAX_PRICE_AGE_MS)
+            throw new AttoError('PRICE_STALE', 'The daily USD price is more than 72 hours old.');
+        const raw = usd.coefficient * ratio.scale * RAW_PER_ATTO / (usd.scale * ratio.coefficient);
+        if (raw === 0n)
+            throw new AttoError('INVALID_USD_AMOUNT', 'The USD amount converts to less than 1 RAW.');
+        let converted;
+        try {
+            converted = amountRaw(raw.toString(), 'RAW');
+        }
+        catch {
+            throw new AttoError('INVALID_USD_AMOUNT', 'The USD amount converts to more than the Atto amount range allows.');
+        }
+        return {
+            usd: amount,
+            priceUsd: price.value,
+            priceDate: price.date,
+            source: snapshot.source,
+            fetchedAt: snapshot.fetchedAt,
+            amount: amountOutput(converted),
+            informational: true,
+        };
+    }
+}

package/dist/pricing/terms.d.ts

@@ -0,0 +1,6 @@
+/** Informational acknowledgement, adapted from the desktop wallet's market-data notice. */
+export declare const marketTerms: {
+    readonly version: "2026-09-05";
+    readonly title: "USD conversion and wallet responsibility";
+    readonly text: string;
+};

package/dist/pricing/terms.js

@@ -0,0 +1,12 @@
+/** Informational acknowledgement, adapted from the desktop wallet's market-data notice. */
+export const marketTerms = {
+    version: '2026-09-05',
+    title: 'USD conversion and wallet responsibility',
+    text: 'USD conversions use an indicative daily Atto market-data price, not an executable market quote. '
+        + 'Prices may be incorrect, delayed, unavailable, or outdated, and the displayed source and price date should be checked. '
+        + 'Conversions round down to whole RAW and transactions send ATTO, not USD. No USD proceeds, exchange rate, or realizable value are promised. '
+        + 'This information is not financial, investment, trading, legal, or tax advice and should not be your only basis for a decision. '
+        + 'This wallet uses self-custody: you are responsible for securing your device and recovery phrase and checking destination addresses and amounts. '
+        + 'Anyone with the recovery phrase may control your funds; confirmed network transactions may be irreversible. '
+        + 'Acknowledgement records that you have read this information.',
+};

package/dist/spending/destination.d.ts

@@ -0,0 +1,16 @@
+import type { StateStore } from '../storage/state.js';
+import type { NetworkName } from '../wallet/types.js';
+import type { SpendLedger } from './ledger.js';
+export interface DestinationBinding {
+    address: string;
+    network: NetworkName;
+    label?: string;
+}
+export declare function validateDestinationBinding(binding: DestinationBinding): void;
+/** Pins destinations even when selection/pricing fails before a reservation.
+ * The label lookup and first binding share one SQLite write transaction. */
+export declare function bindDestination(store: StateStore, ledger: SpendLedger, network: NetworkName, request: {
+    requestId: string;
+    destination?: string;
+    destinationLabel?: string;
+}): DestinationBinding;

package/dist/spending/destination.js

@@ -0,0 +1,42 @@
+import { AttoError } from '../domain/errors.js';
+import { PersonalLabels, nameKey, personalNameSchema } from '../labels/personal.js';
+import { parseAddress } from '../network/reader.js';
+export function validateDestinationBinding(binding) {
+    if (!binding || !['LIVE', 'BETA', 'DEV', 'LOCAL'].includes(binding.network) || parseAddress(binding.address).value !== binding.address
+        || (binding.label !== undefined && personalNameSchema.parse(binding.label) !== binding.label))
+        throw new Error('Invalid payment destination binding.');
+}
+/** Pins destinations even when selection/pricing fails before a reservation.
+ * The label lookup and first binding share one SQLite write transaction. */
+export function bindDestination(store, ledger, network, request) {
+    return store.transaction(() => {
+        const key = `send.destination.${request.requestId}`;
+        const saved = store.get(key);
+        const record = ledger.get(request.requestId);
+        const prior = saved ?? record?.destinationBinding;
+        if (prior) {
+            try {
+                validateDestinationBinding(prior);
+            }
+            catch {
+                throw new AttoError('INVALID_STATE', 'The saved payment destination is invalid. Restore verified profile state.');
+            }
+            if (prior.network !== network)
+                throw new AttoError('NETWORK_MISMATCH', 'This request ID belongs to another network.');
+            if (request.destinationLabel !== undefined
+                ? prior.label === undefined || nameKey(prior.label) !== nameKey(request.destinationLabel)
+                : parseAddress(request.destination).value !== prior.address) {
+                throw new AttoError('REQUEST_CONFLICT', 'This request ID belongs to a different destination. Use its original personal name or full address.');
+            }
+            return prior;
+        }
+        const local = request.destinationLabel === undefined ? undefined : new PersonalLabels(store).resolve(network, request.destinationLabel);
+        const binding = { network, address: local?.address ?? parseAddress(request.destination).value,
+            ...(local ? { label: local.label } : {}) };
+        if (record && (record.destination !== binding.address || (record.network && record.network !== network))) {
+            throw new AttoError('REQUEST_CONFLICT', 'This request ID belongs to a different payment destination or network.');
+        }
+        store.set(key, binding);
+        return binding;
+    });
+}

package/dist/spending/journal.d.ts

@@ -0,0 +1,28 @@
+import { z } from 'zod';
+export declare const paymentMetadataSchema: z.ZodRecord<z.ZodString, z.ZodJSONSchema>;
+export type PaymentMetadata = z.infer<typeof paymentMetadataSchema>;
+export type PaymentStepStatus = 'planned' | 'signed' | 'published' | 'unknown' | 'failed';
+export interface ConsolidationStep {
+    id: string;
+    kind: 'send' | 'receive';
+    index: number;
+    sourceAddress: string;
+    destination: string;
+    raw: string;
+    sourceStepId?: string;
+    status: PaymentStepStatus;
+    hash?: string;
+    blockJson?: string;
+    result?: unknown;
+    publishedAt?: number;
+}
+export interface PaymentPlan {
+    indexes: number[];
+    steps: ConsolidationStep[];
+}
+/** Check durable structure here; the payment engine verifies derived addresses
+ * and the exact transaction content again before each signature. */
+export declare function validatePaymentPlan(plan: PaymentPlan, parent: {
+    index: number;
+    sourceAddress?: string;
+}): void;

package/dist/spending/journal.js

@@ -0,0 +1,69 @@
+import { z } from 'zod';
+import { amountRaw } from '../domain/amount.js';
+export const paymentMetadataSchema = z.record(z.string().min(1).max(128), z.json()).superRefine((metadata, context) => {
+    let nodes = 0;
+    const bounded = (value, depth) => {
+        if (++nodes > 256 || depth > 5)
+            return false;
+        if (value !== null && typeof value === 'object')
+            return Object.values(value).every(child => bounded(child, depth + 1));
+        return true;
+    };
+    if (!bounded(metadata, 0) || Buffer.byteLength(JSON.stringify(metadata), 'utf8') > 4096) {
+        context.addIssue({ code: 'custom', message: 'Payment metadata must fit 4096 bytes, 256 values, and five nesting levels.' });
+    }
+});
+/** Check durable structure here; the payment engine verifies derived addresses
+ * and the exact transaction content again before each signature. */
+export function validatePaymentPlan(plan, parent) {
+    if (!plan || !Array.isArray(plan.indexes) || plan.indexes.length < 1 || plan.indexes.length > 100
+        || plan.indexes.some(index => !Number.isSafeInteger(index) || index < 0 || index > 0x7fff_ffff)
+        || new Set(plan.indexes).size !== plan.indexes.length || !plan.indexes.includes(parent.index)
+        || !Array.isArray(plan.steps) || plan.steps.length > 200 || !parent.sourceAddress)
+        throw new Error('Invalid payment plan.');
+    const steps = new Map();
+    const received = new Set();
+    const accountAddresses = new Map([[parent.index, parent.sourceAddress]]);
+    let sentRaw = 0n;
+    let receivedRaw = 0n;
+    let unfinished = false;
+    for (const step of plan.steps) {
+        if (!step || typeof step.id !== 'string' || !step.id || step.id.length > 200 || steps.has(step.id)
+            || !['send', 'receive'].includes(step.kind) || !plan.indexes.includes(step.index)
+            || typeof step.sourceAddress !== 'string' || !step.sourceAddress || step.sourceAddress.length > 128
+            || step.destination !== parent.sourceAddress || amountRaw(step.raw, 'RAW') !== step.raw
+            || !['planned', 'signed', 'published', 'unknown', 'failed'].includes(step.status))
+            throw new Error('Invalid consolidation step.');
+        if (accountAddresses.has(step.index) && accountAddresses.get(step.index) !== step.sourceAddress)
+            throw new Error('Inconsistent step account.');
+        accountAddresses.set(step.index, step.sourceAddress);
+        if (step.hash !== undefined && (typeof step.hash !== 'string' || !step.hash || typeof step.blockJson !== 'string' || !step.blockJson))
+            throw new Error('Invalid recorded step.');
+        if (['signed', 'published', 'unknown'].includes(step.status) && !step.hash)
+            throw new Error('Missing step block.');
+        if (step.status === 'planned' && step.hash !== undefined)
+            throw new Error('Planned step already has a block.');
+        if (unfinished && step.status !== 'planned')
+            throw new Error('Consolidation steps advanced out of order.');
+        if (step.status !== 'published')
+            unfinished = true;
+        if (step.status === 'published' && (!Number.isSafeInteger(step.publishedAt) || (step.publishedAt ?? -1) < 0))
+            throw new Error('Invalid publication timestamp.');
+        if (step.kind === 'send') {
+            if (step.index === parent.index || step.sourceAddress === parent.sourceAddress || step.sourceStepId !== undefined)
+                throw new Error('Invalid consolidation source.');
+            sentRaw += BigInt(step.raw);
+        }
+        else {
+            const source = step.sourceStepId === undefined ? undefined : steps.get(step.sourceStepId);
+            if (!source || source.kind !== 'send' || received.has(source.id) || source.raw !== step.raw
+                || source.destination !== step.destination || step.index !== parent.index || step.sourceAddress !== parent.sourceAddress)
+                throw new Error('Invalid consolidation receipt.');
+            received.add(source.id);
+            receivedRaw += BigInt(step.raw);
+        }
+        steps.set(step.id, step);
+    }
+    if (sentRaw !== receivedRaw || [...steps.values()].some(step => step.kind === 'send' && !received.has(step.id)))
+        throw new Error('Incomplete consolidation plan.');
+}

package/dist/spending/ledger.d.ts

@@ -0,0 +1,118 @@
+import { type DestinationBinding } from './destination.js';
+import type { StateStore } from '../storage/state.js';
+import type { AccountPool, SpendingPolicy } from '../wallet/types.js';
+import { type PaymentMetadata, type PaymentPlan } from './journal.js';
+export type { ConsolidationStep, PaymentMetadata, PaymentPlan } from './journal.js';
+export interface SendRecord {
+    id: string;
+    index: number;
+    destination: string;
+    destinationBinding?: DestinationBinding;
+    raw: string;
+    createdAt: number;
+    status: 'reserved' | 'signed' | 'published' | 'unknown' | 'failed';
+    hash?: string;
+    blockJson?: string;
+    result?: unknown;
+    publishedAt?: number;
+    sourceAddress?: string;
+    network?: string;
+    metadata?: PaymentMetadata;
+    quote?: unknown;
+    selection?: 'automatic' | 'explicit';
+    plan?: PaymentPlan;
+}
+export type SendReservation = Pick<SendRecord, 'id' | 'index' | 'destination' | 'raw' | 'createdAt'> & Partial<Pick<SendRecord, 'sourceAddress' | 'network' | 'metadata' | 'quote' | 'selection' | 'plan' | 'destinationBinding'>>;
+export type McpAccess = 'read-only' | 'spend';
+export interface ProposalWallet {
+    directory: string;
+    walletFingerprint: string | null;
+    network: string;
+}
+export interface LimitsProposal extends ProposalWallet {
+    id: string;
+    policy: SpendingPolicy;
+    access: McpAccess;
+    createdAt: number;
+    expiresAt: number;
+    baseRevision: number;
+    status: 'pending' | 'approved' | 'rejected';
+    decidedAt?: number;
+    pool?: AccountPool;
+}
+export declare class SpendLedger {
+    private readonly store;
+    constructor(store: StateStore);
+    policy(): SpendingPolicy;
+    setPolicy(policy: SpendingPolicy): void;
+    mcpAccess(): McpAccess;
+    pool(): AccountPool;
+    proposePolicy(policy: SpendingPolicy, access: McpAccess, wallet: ProposalWallet, pool?: AccountPool): LimitsProposal;
+    proposal(): LimitsProposal | null;
+    reviewProposal(id: string, wallet: ProposalWallet): LimitsProposal;
+    approveProposal(id: string, wallet: ProposalWallet): void;
+    rejectProposal(id: string, wallet: ProposalWallet): void;
+    private revision;
+    private replacePolicy;
+    assertCanReserve(raw: string, now?: number): void;
+    /** Recheck the current policy before signing without charging this reservation twice. */
+    assertReservationAllowed(id: string, now?: number): void;
+    private assertAllowance;
+    reserve(request: SendReservation): SendRecord;
+    get(id: string): SendRecord | undefined;
+    journalGet(requestId: string): SendRecord | undefined;
+    journalList(options?: {
+        limit?: number;
+        cursor?: string;
+        status?: SendRecord['status'];
+    }): {
+        items: SendRecord[];
+        nextCursor?: string;
+    };
+    signed(id: string, hash: string, blockJson: string): void;
+    complete(id: string, result: unknown, publishedAt: number): void;
+    uncertain(id: string): void;
+    fail(id: string): void;
+    /** Caller must first prove a different canonical block at this block's height. */
+    reject(id: string): void;
+    stepSigned(id: string, stepId: string, hash: string, blockJson: string): void;
+    stepComplete(id: string, stepId: string, result: unknown, publishedAt: number): void;
+    stepUncertain(id: string, stepId: string): void;
+    /** Caller must prove this internal block conflicts with the canonical chain.
+     * The pinned plan cannot complete; retain all step evidence in the failed parent. */
+    stepReject(id: string, stepId: string): void;
+    private updateStep;
+    pending(): SendRecord[];
+    usage(now?: number): {
+        policy: SpendingPolicy;
+        mcpAccess: McpAccess;
+        pool: AccountPool;
+        proposal: LimitsProposal | null;
+        pendingRaw: string;
+        perRequest: {
+            limitRaw: string;
+            amount: string;
+            unit: import("../wallet/types.js").AmountUnit;
+        } | null;
+        rolling: {
+            from: number;
+            until: number;
+            limitRaw: string;
+            publishedRaw: string;
+            reservedRaw: string;
+            usedRaw: string;
+            remainingRaw: string;
+            days: number;
+            amount: string;
+            unit: import("../wallet/types.js").AmountUnit;
+        }[];
+    };
+    private records;
+    private update;
+    private pendingTotal;
+    private ruleUsage;
+    private validatePolicy;
+    private validatePool;
+    private validateDetails;
+    private planDefinition;
+}