@leofcoin/endpoints 0.4.11 → 0.4.12

package/README.md

@@ -6,4 +6,58 @@ http(chain, port, networkVersion)
 
 ```js
 wss(chain, port, networkVersion)
-```
+```
+
+## Chain Manager HTTP API
+
+`POST /manager/rpc` accepts `application/json` (maximum 1 MiB). Requests must
+include the full expected `chainId`; the node verifies its own genesis identity
+and returns HTTP 409 on a mismatch. Existing endpoints remain unchanged.
+This API never unlocks a node wallet, selects remote accounts or signs messages.
+Deploy/restart an updated endpoints package before connecting Chain Manager.
+
+Actions:
+
+| Action | Additional fields | Result |
+| --- | --- | --- |
+| `status` | optional public `account` | API version, chain identity, sync, peer count, height, contract hashes, account balance in integer units and latest nonce |
+| `read` | `contract`, `method`, JSON array `params` | `{ value }`, using the existing bigint JSON codec |
+| `submit` | signed `transaction`, optional encoded `contract` | transaction hash and explicit status |
+| `receipt` | transaction `hash` | durable status, canonical inclusion (`blockHeight`, `blockHash`) and scan progress (`scannedHeight`) when observed, or `unknown` |
+
+Submissions require a synced node with connected peers. A contract upload must
+match the signed factory registration, creator and content hash. The node
+validates signatures before storing uploaded code. Duplicate transaction hashes
+are admitted once, including concurrent duplicates.
+
+`pending` means admitted, not confirmed. The chain's canonical completion
+promise or verified canonical block membership produces `confirmed`; execution
+rejection produces `failed`. Unverifiable admission
+produces `unknown`, never a success-shaped response or an automatic resend.
+
+Before any contract upload/admission, a reservation is durably saved in the
+node's existing isolated `chainStore`, under `manager:receipts:v1:<full-chain-id>`.
+Storage unavailability/corruption/write failure blocks admission explicitly.
+Updates and duplicate checks are serialized. Restarting the HTTP server/node
+restores admission history and does not resubmit a reserved transaction.
+
+After restart, `receipt` scans at most 128 canonical blocks per request from the
+submission height, persists its cursor and checks recorded inclusion/scan anchors.
+It uses canonical worker blocks, not the mempool or raw transaction store; absent
+inclusion is `unknown`, never inferred failure. Refresh again to continue a long
+scan. A changing tip or unavailable canonical block returns an explicit error
+without advancing durable progress. Canonical tip lookup avoids cached fallback
+state when the machine exposes its strict getter.
+
+Receipts are bounded to 512 entries per chain. Only completed entries may be
+evicted; a full unresolved journal blocks new admission. Reservations written
+before a crash can remain unknown if delivery never happened. Evicted entries,
+pre-upgrade transactions and receipts from another node are also unknown; these
+require operator reconciliation and are not proof of rejection. The journal is
+local to a node, not shared across distinct node instances.
+
+Use HTTPS and an operator-controlled endpoint. CORS permits the web and Electron
+clients to connect but is not authentication. The API only accepts transactions
+already signed by the client; it provides no privileged server-side keys.
+Chain-ID checks protect this connection from accidental chain switching; they do
+not add cryptographic cross-chain replay protection to the existing wire format.

package/exports/http.js

@@ -7,6 +7,7 @@ import Showdown from 'showdown';
 import shared from './shared.js';
 import { dirname, join } from 'path';
 import { fileURLToPath } from 'url';
+import { managerMiddleware } from './manager.js';
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 const converter = new Showdown.Converter();
@@ -155,6 +156,7 @@ export default (chain, port, networkVersion, remote = false) => {
             ctx.type = 'application/json';
         }
     });
+    api.use(managerMiddleware(chain));
     api.use(router.routes());
     return api.listen(port);
 };

package/exports/manager-receipts.d.ts

@@ -0,0 +1,43 @@
+type Store = {
+    has(key: string): Promise<boolean>;
+    get(key: string): Promise<Uint8Array | string>;
+    put(key: string, value: Uint8Array): Promise<unknown>;
+};
+type Block = {
+    index: number | bigint | string;
+    hash: string;
+    transactions: string[];
+};
+type Chain = {
+    lastBlock: Block | Promise<Block>;
+    machine?: {
+        getCanonicalTip(): Promise<Block>;
+    };
+    getBlocks(from: number, to: number): Promise<Block[]>;
+};
+export type Receipt = {
+    hash: string;
+    status: string;
+    createdAt: number;
+    error?: string;
+    startHeight: number;
+    scannedHeight?: number;
+    scannedHash?: string;
+    blockHeight?: number;
+    blockHash?: string;
+};
+/** Uses the node's already isolated durable chain store, never a shared filesystem path. */
+export declare class ManagerReceipts {
+    #private;
+    private store;
+    private chain;
+    constructor(store: () => Store, chain: Chain);
+    tip(): Promise<Block>;
+    serialized<T>(work: () => Promise<T>): Promise<T>;
+    load(chainId: string): Promise<Map<string, Receipt>>;
+    save(chainId: string, receipts: Map<string, Receipt>): Promise<void>;
+    reserve(receipts: Map<string, Receipt>, receipt: Receipt): void;
+    complete(chainId: string, hash: string, status: 'confirmed' | 'failed', error?: string): Promise<void>;
+    reconcile(receipt: Receipt): Promise<Receipt>;
+}
+export {};

package/exports/manager-receipts.js

@@ -0,0 +1,117 @@
+const statuses = ['submitting', 'pending', 'confirmed', 'failed', 'unknown'];
+const LIMIT = 512;
+/** Uses the node's already isolated durable chain store, never a shared filesystem path. */
+export class ManagerReceipts {
+    store;
+    chain;
+    #tail = Promise.resolve();
+    constructor(store, chain) {
+        this.store = store;
+        this.chain = chain;
+    }
+    async tip() {
+        return this.chain.machine ? this.chain.machine.getCanonicalTip() : await this.chain.lastBlock;
+    }
+    async #block(index) {
+        const blocks = await this.chain.getBlocks(index, index + 1);
+        const block = blocks[0];
+        if (!block || Number(block.index) !== index || !Array.isArray(block.transactions) || typeof block.hash !== 'string')
+            throw new Error(`Canonical block ${index} is unavailable; retry reconciliation later`);
+        return block;
+    }
+    serialized(work) {
+        const next = this.#tail.then(work);
+        this.#tail = next.catch(error => { console.error('Management receipt operation failed:', error); });
+        return next;
+    }
+    async load(chainId) {
+        const store = this.store();
+        if (!store)
+            throw new Error('Durable chain store is unavailable; management writes are disabled');
+        const key = `manager:receipts:v1:${chainId}`;
+        if (!await store.has(key))
+            return new Map();
+        const raw = await store.get(key);
+        const parsed = JSON.parse(typeof raw === 'string' ? raw : new TextDecoder().decode(raw));
+        if (!Array.isArray(parsed) || parsed.length > LIMIT || parsed.some(value => !value || typeof value.hash !== 'string' || !/^[A-Z2-7]{32,128}$/.test(value.hash) ||
+            !statuses.includes(value.status) || !Number.isSafeInteger(value.createdAt) ||
+            !Number.isSafeInteger(value.startHeight) || value.startHeight < 0 ||
+            (value.scannedHeight !== undefined && (!Number.isSafeInteger(value.scannedHeight) || value.scannedHeight < 0)) ||
+            (value.blockHeight !== undefined && (!Number.isSafeInteger(value.blockHeight) || value.blockHeight < 1)) ||
+            (value.blockHash !== undefined && typeof value.blockHash !== 'string') ||
+            (value.scannedHash !== undefined && typeof value.scannedHash !== 'string') ||
+            (value.error !== undefined && typeof value.error !== 'string')))
+            throw new Error('Stored management receipts are invalid; refusing to overwrite them');
+        return new Map(parsed.map(receipt => [receipt.hash, receipt]));
+    }
+    async save(chainId, receipts) {
+        await this.store().put(`manager:receipts:v1:${chainId}`, new TextEncoder().encode(JSON.stringify([...receipts.values()])));
+    }
+    reserve(receipts, receipt) {
+        if (receipts.size >= LIMIT) {
+            const completed = [...receipts].find(([, value]) => ['confirmed', 'failed'].includes(value.status));
+            if (!completed)
+                throw new Error('Receipt capacity reached; reconcile pending transactions first');
+            receipts.delete(completed[0]);
+        }
+        receipts.set(receipt.hash, receipt);
+    }
+    async complete(chainId, hash, status, error) {
+        return this.serialized(async () => {
+            const receipts = await this.load(chainId);
+            const receipt = receipts.get(hash);
+            if (!receipt)
+                throw new Error('Receipt disappeared before canonical completion');
+            receipt.status = status;
+            receipt.error = error;
+            await this.save(chainId, receipts);
+        });
+    }
+    async reconcile(receipt) {
+        if (typeof this.chain.getBlocks !== 'function')
+            throw new Error('Node does not support canonical receipt reconciliation');
+        const tip = await this.tip();
+        const height = Number(tip?.index ?? 0);
+        if (!Number.isSafeInteger(height) || height < 0)
+            throw new Error('Invalid canonical height');
+        const assertStable = async () => {
+            const current = await this.tip();
+            if (String(current?.index ?? 0) !== String(tip?.index ?? 0) || current?.hash !== tip?.hash)
+                throw new Error('Canonical tip changed during reconciliation; refresh again');
+        };
+        // Recheck recorded inclusion instead of trusting a previous process's observation.
+        if (receipt.blockHeight !== undefined) {
+            const block = receipt.blockHeight <= height ? await this.#block(receipt.blockHeight) : undefined;
+            if (block?.transactions?.includes(receipt.hash)) {
+                await assertStable();
+                return { ...receipt, status: 'confirmed', error: undefined, blockHash: block.hash };
+            }
+            receipt = { ...receipt, status: 'unknown', blockHeight: undefined, blockHash: undefined, scannedHeight: undefined, scannedHash: undefined, startHeight: 0 };
+        }
+        if (receipt.scannedHeight && receipt.scannedHash) {
+            const anchor = receipt.scannedHeight <= height ? await this.#block(receipt.scannedHeight) : undefined;
+            if (anchor?.hash !== receipt.scannedHash)
+                receipt = { ...receipt, scannedHeight: undefined, scannedHash: undefined, startHeight: 0 };
+        }
+        // Scan a bounded range per refresh; no pool membership or nonce heuristic proves confirmation.
+        const start = Math.max(1, Math.min(receipt.scannedHeight ?? (receipt.startHeight - 1), height) + 1);
+        const end = Math.min(height, start + 127);
+        let scannedHash = receipt.scannedHash;
+        for (let index = start; index <= end; index++) {
+            const block = await this.#block(index);
+            if (block.transactions.includes(receipt.hash)) {
+                await assertStable();
+                return { ...receipt, status: 'confirmed', error: undefined, blockHeight: index, blockHash: block.hash, scannedHeight: index, scannedHash: block.hash };
+            }
+            scannedHash = block.hash;
+        }
+        await assertStable();
+        // Even fully scanned absence is not failure: delivery or execution may still be pending.
+        return {
+            ...receipt, scannedHeight: Math.max(receipt.scannedHeight ?? 0, end),
+            scannedHash,
+            status: receipt.status === 'failed' ? 'failed' : 'unknown',
+            error: receipt.status === 'failed' ? receipt.error : 'No canonical inclusion observed yet. Refresh to continue reconciliation; do not resend.'
+        };
+    }
+}

package/exports/manager.d.ts

@@ -0,0 +1,2 @@
+/** No remote wallet access: only public queries and client-signed transactions. */
+export declare function managerMiddleware(chain: any): (ctx: any, next: any) => Promise<any>;

package/exports/manager.js

@@ -0,0 +1,156 @@
+import { ContractMessage, TransactionMessage } from '@leofcoin/messages';
+import { verifyChainIdentity } from '@leofcoin/lib/chain-identity';
+import { ManagerReceipts } from './manager-receipts.js';
+const MAX_BODY = 1_048_576;
+const errorMessage = (error) => error?.error?.message || error?.message || String(error?.error || error);
+class RequestError extends Error {
+    status;
+    constructor(status, message) {
+        super(message);
+        this.status = status;
+    }
+}
+async function readBody(request) {
+    let size = 0;
+    const chunks = [];
+    for await (const chunk of request) {
+        size += chunk.length;
+        if (size > MAX_BODY)
+            throw new RequestError(413, 'Management request exceeds 1 MiB');
+        chunks.push(chunk);
+    }
+    try {
+        return JSON.parse(Buffer.concat(chunks).toString('utf8'));
+    }
+    catch {
+        throw new RequestError(400, 'Management request must contain JSON');
+    }
+}
+/** No remote wallet access: only public queries and client-signed transactions. */
+export function managerMiddleware(chain) {
+    const store = globalThis.chainStore;
+    const contractStore = globalThis.contractStore;
+    const journal = new ManagerReceipts(() => store, chain);
+    const live = new Set();
+    const peerCount = () => Object.values(globalThis.peernet?.connections || {})
+        .filter((peer) => peer.connected).length;
+    return async (ctx, next) => {
+        if (ctx.path !== '/manager/rpc')
+            return next();
+        ctx.set('Cache-Control', 'no-store');
+        if (ctx.method !== 'POST') {
+            ctx.status = 405;
+            ctx.body = { error: 'Use POST with application/json' };
+            return;
+        }
+        try {
+            if (!ctx.is('application/json'))
+                throw new RequestError(415, 'Content-Type must be application/json');
+            const body = await readBody(ctx.req);
+            if (!body || typeof body !== 'object' || Array.isArray(body))
+                throw new RequestError(400, 'Invalid request');
+            const identity = await verifyChainIdentity(await chain.getChainIdentity());
+            if (body.chainId !== identity.chainId)
+                throw new RequestError(409, 'Endpoint chain identity changed; reconnect and review');
+            const { action } = body;
+            if (action === 'status') {
+                const account = body.account;
+                if (account !== undefined && (typeof account !== 'string' || account.length > 128))
+                    throw new RequestError(400, 'Invalid account');
+                ctx.body = {
+                    apiVersion: 1, chainId: identity.chainId, network: identity.network,
+                    nativeToken: identity.genesisContracts.nativeToken, contractFactory: identity.genesisContracts.contractFactory,
+                    height: String((await journal.tip())?.index ?? 0), peers: peerCount(), synced: chain.state?.sync === 'synced',
+                    balance: account ? String(await chain.balanceOf(account) ?? 0) : '0',
+                    nonce: account ? await chain.getNonce(account) : 0
+                };
+            }
+            else if (action === 'read') {
+                if (typeof body.contract !== 'string' || !/^[A-Z2-7]{32,128}$/.test(body.contract) ||
+                    typeof body.method !== 'string' || !/^[A-Za-z][A-Za-z0-9_]{0,79}$/.test(body.method) ||
+                    !Array.isArray(body.params) || body.params.length > 100)
+                    throw new RequestError(400, 'Invalid contract, method or parameter array');
+                ctx.body = { value: await chain.staticCall(body.contract, body.method, body.params) ?? null };
+            }
+            else if (action === 'receipt') {
+                if (typeof body.hash !== 'string' || !/^[A-Z2-7]{32,128}$/.test(body.hash))
+                    throw new RequestError(400, 'Invalid transaction hash');
+                ctx.body = await journal.serialized(async () => {
+                    const receipts = await journal.load(identity.chainId);
+                    const receipt = receipts.get(body.hash);
+                    if (!receipt)
+                        return { hash: body.hash, status: 'unknown' };
+                    if (live.has(`${identity.chainId}:${body.hash}`))
+                        return receipt;
+                    const reconciled = await journal.reconcile(receipt);
+                    receipts.set(body.hash, reconciled);
+                    await journal.save(identity.chainId, receipts);
+                    return reconciled;
+                });
+            }
+            else if (action === 'submit') {
+                if (!chain.state || chain.state.sync !== 'synced' || peerCount() === 0)
+                    throw new RequestError(503, 'Node must be synced and connected before submission');
+                const transaction = body.transaction;
+                if (!transaction || typeof transaction !== 'object' || !transaction.signature)
+                    throw new RequestError(400, 'A client-signed transaction is required');
+                const message = new TransactionMessage(transaction);
+                if (message.encoded.length > 32768)
+                    throw new RequestError(413, 'Transaction exceeds 32 KiB');
+                const hash = await message.hash();
+                // Validate before persisting uploaded code, including its binding to this signed registration.
+                await chain.validateTransactionSignature(message);
+                let contract;
+                if (body.contract !== undefined) {
+                    if (typeof body.contract !== 'string')
+                        throw new RequestError(400, 'Contract must be an encoded message');
+                    contract = new ContractMessage(body.contract);
+                    if (contract.encoded.length > 262144 || contract.decoded.creator !== transaction.from ||
+                        transaction.to !== identity.genesisContracts.contractFactory ||
+                        transaction.method !== 'registerContract' || transaction.params?.length !== 1 ||
+                        transaction.params[0] !== await contract.hash())
+                        throw new RequestError(400, 'Contract does not match the signed factory registration');
+                }
+                ctx.body = await journal.serialized(async () => {
+                    const receipts = await journal.load(identity.chainId);
+                    const known = receipts.get(hash);
+                    if (known)
+                        return known;
+                    const height = Number((await journal.tip())?.index ?? 0);
+                    if (!Number.isSafeInteger(height) || height < 0)
+                        throw new Error('Invalid submission height');
+                    const receipt = { hash, status: 'submitting', createdAt: Date.now(), startHeight: height };
+                    journal.reserve(receipts, receipt);
+                    await journal.save(identity.chainId, receipts);
+                    try {
+                        if (contract)
+                            await contractStore.put(await contract.hash(), contract.encoded);
+                        const pending = await chain.sendTransaction(transaction);
+                        if (pending?.hash !== hash || !pending.wait || typeof pending.wait.then !== 'function')
+                            throw new Error('Node did not return a canonical completion handle');
+                        receipt.status = 'pending';
+                        live.add(`${identity.chainId}:${hash}`);
+                        Promise.resolve(pending.wait).then(() => journal.complete(identity.chainId, hash, 'confirmed'), error => journal.complete(identity.chainId, hash, 'failed', errorMessage(error))).catch(error => console.error('Could not persist canonical management completion:', hash, error))
+                            .finally(() => live.delete(`${identity.chainId}:${hash}`));
+                    }
+                    catch (error) {
+                        // The node may already have admitted the transaction. Never silently auto-resend.
+                        receipt.status = 'unknown';
+                        receipt.error = errorMessage(error);
+                        console.error('Management submission could not be verified:', hash, error);
+                    }
+                    await journal.save(identity.chainId, receipts);
+                    return receipt;
+                });
+            }
+            else
+                throw new RequestError(400, 'Unsupported management action');
+        }
+        catch (error) {
+            ctx.status = error instanceof RequestError ? error.status : 400;
+            ctx.body = { error: errorMessage(error) };
+            if (!(error instanceof RequestError))
+                console.error('Management request failed:', error);
+        }
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@leofcoin/endpoints",
-  "version": "0.4.11",
+  "version": "0.4.12",
   "description": "",
   "type": "module",
   "exports": {
@@ -34,6 +34,8 @@
   },
   "homepage": "https://github.com/leofcoin/monorepo/tree/main/packages/endpoints#readme",
   "dependencies": {
+    "@leofcoin/lib": "^1.3.15",
+    "@leofcoin/messages": "^1.6.5",
     "@koa/cors": "^5.0.0",
     "@koa/router": "^13.1.1",
     "@leofcoin/utils": "^1.1.45",