@leofcoin/endpoints 0.4.11 → 0.5.0

package/README.md

@@ -1,3 +1,10 @@
+# Binary RPC migration
+
+Protocol 0.5.0 uses `application/octet-stream` HTTP and binary-only WebSocket
+frames. JSON bodies/query parameters and text socket frames are unsupported.
+Use the matching `@leofcoin/endpoint-clients@0.4` rather than `response.json()`.
+See [wire format, rollout and upstream release gates](../../docs/binary-wire-protocol.md).
+
 # endpoints
  
 ```js
@@ -6,4 +13,87 @@ http(chain, port, networkVersion)
 
 ```js
 wss(chain, port, networkVersion)
-```
+```
+
+## Generic contract reads
+
+POST /staticCall accepts a binary map containing `contract`, `method` and an
+array `params` (default `[]`). Native BigInts and byte arrays retain their types;
+there is no JSON boxing or revival. Use the matching HTTP/WebSocket clients.
+Malformed parameters return HTTP 400; rejected read-only queries return HTTP 422.
+All reads delegate to the chain's isolated `staticCall` path.
+
+## Public read-only explorer
+
+Deploy/restart the updated endpoints build before enabling anonymous browser
+exploration. These binary POST routes never access wallets, select accounts, sign,
+submit transactions or fetch missing content from peers. Responses carry
+`apiVersion: 1` and `chainId`. Except status, queries must include the expected
+`chainId`; a changed chain returns HTTP 409. Non-POST requests return HTTP 405.
+
+| Route | Binary fields | Result |
+| --- | --- | --- |
+| `/explorer/status` | none | Genesis identity, source tip, connected peer IDs, sync state |
+| `/explorer/blocks` | `from`, `count` (1–25), `chainId` | Applied block snapshot, zero-based indexes |
+| `/explorer/block` | `hash`, `chainId` | Hash-checked local content as Uint8Array, maximum 1 MiB |
+| `/explorer/transaction` | `hash`, `chainId` | Hash-checked local transaction/pool content as Uint8Array |
+| `/explorer/pool` | `chainId` | Up to 101 pool hashes; clients display at most 100 |
+| `/explorer/overview` | `chainId` | Public counters, registry, top-five holder balances and shares |
+
+Reads time out after 10 seconds. A local content miss returns HTTP 404 rather
+than a proxy fetch. Source sync/membership is not a proof of network finality.
+No explorer write action is exposed; all application API responses use binary encoding.
+
+## Chain Manager HTTP API
+
+`POST /manager/rpc` accepts `application/octet-stream` (maximum 1 MiB). Requests must
+include the full expected `chainId`; the node verifies its own genesis identity
+and returns HTTP 409 on a mismatch. All application API responses use binary encoding.
+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`, array `params` | `{ value }`, with native BigInt/byte fields |
+| `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/binary-http.d.ts

@@ -0,0 +1,4 @@
+export declare const RPC_LIMIT: number;
+export declare function readBinaryRequest(request: any, maxBytes?: number): Promise<any>;
+/** The Koa boundary owns serialization, including errors. Domain handlers see native values. */
+export declare const binaryHttp: (ctx: any, next: any) => Promise<any>;

package/exports/binary-http.js

@@ -0,0 +1,54 @@
+import { encodeWire, decodeWire, BINARY_CONTENT_TYPE } from '@leofcoin/binary';
+export const RPC_LIMIT = 4 * 1024 * 1024;
+export async function readBinaryRequest(request, maxBytes = 1048576) {
+    const chunks = [];
+    let size = 0;
+    for await (const chunk of request) {
+        size += chunk.length;
+        if (size > maxBytes)
+            throw Object.assign(new Error('Binary request too large'), { status: 413 });
+        chunks.push(chunk);
+    }
+    return decodeWire('rpc', Buffer.concat(chunks), { maxBytes });
+}
+/** The Koa boundary owns serialization, including errors. Domain handlers see native values. */
+export const binaryHttp = async (ctx, next) => {
+    if (ctx.path === '/' && ctx.method === 'GET')
+        return next();
+    try {
+        if (ctx.method === 'POST') {
+            if (ctx.get('content-type').split(';')[0] !== BINARY_CONTENT_TYPE)
+                throw Object.assign(new Error('Use application/octet-stream binary RPC'), { status: 415 });
+            try {
+                ctx.state.rpcParams = await readBinaryRequest(ctx.req);
+            }
+            catch (error) {
+                throw Object.assign(error, { status: error.status || 400 });
+            }
+            if (!ctx.state.rpcParams || typeof ctx.state.rpcParams !== 'object' || Array.isArray(ctx.state.rpcParams) || ctx.state.rpcParams instanceof Uint8Array)
+                throw Object.assign(new Error('RPC parameters must be a binary map'), { status: 400 });
+        }
+        else if (ctx.method === 'GET' && !ctx.querystring)
+            ctx.state.rpcParams = {};
+        else
+            throw Object.assign(new Error('Use binary POST parameters; JSON/query-string payloads are unsupported'), { status: 405 });
+        await next();
+        // Koa turns a legitimate null result into HTTP 204; binary RPC must still carry its null tag.
+        if (ctx.status === 204 && ctx.body == null)
+            ctx.status = 200;
+        else if (ctx.body == null)
+            ctx.body = { error: ctx.message || 'RPC returned no value' };
+    }
+    catch (error) {
+        ctx.status = Number.isInteger(error.status) && error.status >= 400 && error.status <= 599 ? error.status : 500;
+        ctx.body = { error: ctx.status === 500 ? 'RPC operation failed' : error.message };
+    }
+    try {
+        ctx.body = Buffer.from(encodeWire('rpc', ctx.body, { maxBytes: RPC_LIMIT }));
+    }
+    catch {
+        ctx.status = 500;
+        ctx.body = Buffer.from(encodeWire('rpc', { error: 'RPC response cannot be encoded' }));
+    }
+    ctx.type = BINARY_CONTENT_TYPE;
+};

package/exports/binary-socket.d.ts

@@ -0,0 +1,4 @@
+export default function binarySocketServer({ port, protocol }: {
+    port: any;
+    protocol: any;
+}, routes: any): any;

package/exports/binary-socket.js

@@ -0,0 +1,57 @@
+import { WebSocketServer } from 'ws';
+import { encodeWire, decodeWire } from '@leofcoin/binary';
+export default function binarySocketServer({ port, protocol }, routes) {
+    const required = `${protocol}.lfc-binary-v1`;
+    const server = new WebSocketServer({ port, maxPayload: 4 * 1024 * 1024,
+        handleProtocols: protocols => protocols.has(required) ? required : false });
+    server.on('connection', socket => {
+        if (socket.protocol !== required) {
+            socket.close(1002, 'Binary protocol required');
+            return;
+        }
+        let active = 0;
+        socket.on('error', () => { });
+        socket.on('message', async (bytes, binary) => {
+            if (!binary || !(bytes instanceof Uint8Array)) {
+                socket.close(1003, 'Binary frames required');
+                return;
+            }
+            let request;
+            try {
+                request = decodeWire('rpc-request', bytes, { maxBytes: 1048576 });
+                if (!request || typeof request.id !== 'string' || request.id.length > 80 || !request.id ||
+                    typeof request.url !== 'string' || !Object.hasOwn(routes, request.url))
+                    throw new Error('Invalid RPC request');
+            }
+            catch {
+                socket.close(1002, 'Invalid binary RPC');
+                return;
+            }
+            const send = (value, status = 200) => {
+                if (socket.readyState === 1)
+                    socket.send(encodeWire('rpc-response', { id: request.id, status, value }, { maxBytes: 4 * 1024 * 1024 }));
+            };
+            if (active >= 32) {
+                send({ error: 'Too many pending requests' }, 429);
+                return;
+            }
+            active++;
+            try {
+                const context = { send };
+                await routes[request.url](...(request.params === undefined ? [context] : [request.params, context]));
+            }
+            catch {
+                try {
+                    send({ error: 'RPC operation failed' }, 500);
+                }
+                catch {
+                    socket.close(1011);
+                }
+            }
+            finally {
+                active--;
+            }
+        });
+    });
+    return server;
+}

package/exports/explorer.d.ts

@@ -0,0 +1,2 @@
+/** Public data only. No wallet, account selection, signing, submission or peer fetches. */
+export declare function explorerMiddleware(chain: any): (ctx: any, next: any) => Promise<any>;

package/exports/explorer.js

@@ -0,0 +1,117 @@
+import { BlockMessage, TransactionMessage } from '@leofcoin/messages';
+import { verifyChainIdentity } from '@leofcoin/lib/chain-identity';
+const fail = (status, message) => { throw Object.assign(new Error(message), { status }); };
+const integer = (value, maximum) => {
+    if (!/^(0|[1-9]\d*)$/.test(String(value)) || !Number.isSafeInteger(Number(value)) || Number(value) > maximum)
+        fail(400, 'Invalid explorer range');
+    return Number(value);
+};
+const hashInput = value => {
+    if (typeof value !== 'string' || !/^[A-Z2-7]{32,128}$/.test(value))
+        fail(400, 'Invalid content hash');
+    return value;
+};
+/** Public data only. No wallet, account selection, signing, submission or peer fetches. */
+export function explorerMiddleware(chain) {
+    return async (ctx, next) => {
+        if (!ctx.path.startsWith('/explorer/'))
+            return next();
+        ctx.set('Cache-Control', 'no-store');
+        if (ctx.method !== 'POST') {
+            ctx.status = 405;
+            ctx.body = { error: 'Explorer supports read-only binary POST requests' };
+            return;
+        }
+        let timer;
+        try {
+            const body = await Promise.race([
+                (async () => {
+                    const identity = await verifyChainIdentity(await chain.getChainIdentity());
+                    if (ctx.path !== '/explorer/status' && ctx.state.rpcParams.chainId !== identity.chainId)
+                        fail(409, 'Explorer chain identity changed; reconnect');
+                    const response = { apiVersion: 1, chainId: identity.chainId };
+                    if (ctx.path === '/explorer/status') {
+                        const tip = await chain.lastBlock;
+                        return { ...response, identity, tip: { index: tip.index, hash: tip.hash },
+                            synced: chain.state?.sync === 'synced', nativeToken: identity.genesisContracts.nativeToken,
+                            peers: Object.entries(globalThis.peernet?.connections || {})
+                                .filter(([, peer]) => peer?.connected).map(([id]) => id).slice(0, 100) };
+                    }
+                    if (ctx.path === '/explorer/blocks') {
+                        const from = integer(ctx.state.rpcParams.from, Number.MAX_SAFE_INTEGER);
+                        const count = integer(ctx.state.rpcParams.count, 25);
+                        if (count < 1 || from > Number.MAX_SAFE_INTEGER - count)
+                            fail(400, 'Invalid explorer range');
+                        const blocks = await chain.getBlocks(from, from + count);
+                        if (!Array.isArray(blocks))
+                            fail(503, 'Canonical block data unavailable');
+                        return { ...response, blocks: blocks.filter(block => block && block.loaded !== false) };
+                    }
+                    if (ctx.path === '/explorer/block' || ctx.path === '/explorer/transaction') {
+                        const hash = hashInput(ctx.state.rpcParams.hash);
+                        const stores = ctx.path === '/explorer/block' ? [globalThis.blockStore]
+                            : [globalThis.transactionStore, globalThis.transactionPoolStore];
+                        let bytes;
+                        for (const store of stores) {
+                            if (store && await store.has(hash)) {
+                                bytes = await store.get(hash);
+                                break;
+                            }
+                        }
+                        if (!(bytes instanceof Uint8Array) || bytes.length === 0)
+                            fail(404, 'Content not available on this node');
+                        if (bytes.length > 1_048_576)
+                            fail(413, 'Explorer content exceeds 1 MiB');
+                        const message = ctx.path === '/explorer/block' ? new BlockMessage(bytes) : new TransactionMessage(bytes);
+                        if (await message.hash() !== hash)
+                            fail(503, 'Stored content hash mismatch');
+                        return { ...response, encoded: bytes };
+                    }
+                    if (ctx.path === '/explorer/pool') {
+                        if (!globalThis.transactionPoolStore)
+                            fail(503, 'Transaction pool unavailable');
+                        return { ...response, hashes: (await globalThis.transactionPoolStore.keys(101)).slice(0, 101).map(String) };
+                    }
+                    if (ctx.path === '/explorer/overview') {
+                        const [validators, registeredContracts, nativeCalls, nativeMints, nativeBurns, nativeTransfers, totalContracts, totalTransactions, totalSize, poolCount, poolSize, balances] = await Promise.all([
+                            chain.staticCall(identity.genesisContracts.validators, 'validators', []),
+                            chain.staticCall(identity.genesisContracts.contractFactory, 'totalContracts', []),
+                            chain.nativeCalls, chain.nativeMints, chain.nativeBurns, chain.nativeTransfers,
+                            chain.totalContracts, chain.totalTransactions, chain.totalSize,
+                            globalThis.transactionPoolStore?.length(), globalThis.transactionPoolStore?.size(), chain.balances
+                        ]);
+                        let supply = 0n;
+                        let funded = 0;
+                        const top = [];
+                        if (!balances || typeof balances !== 'object')
+                            fail(503, 'Balances unavailable');
+                        for (const [address, raw] of Object.entries(balances)) {
+                            const balance = BigInt(raw);
+                            if (balance <= 0n)
+                                continue;
+                            supply += balance;
+                            funded++;
+                            top.push({ address, balance });
+                            top.sort((a, b) => a.balance === b.balance ? a.address.localeCompare(b.address) : a.balance > b.balance ? -1 : 1);
+                            if (top.length > 5)
+                                top.pop();
+                        }
+                        return { ...response, validators, registeredContracts, nativeCalls, nativeMints, nativeBurns,
+                            nativeTransfers, totalContracts, totalTransactions, totalSize, poolCount, poolSize,
+                            holders: { total: funded, holders: top.map(holder => ({ ...holder, share: Number(holder.balance * 10000n / (supply || 1n)) / 100 })) } };
+                    }
+                    fail(404, 'Unknown read-only explorer resource');
+                })(),
+                new Promise((_, reject) => { timer = setTimeout(() => reject(Object.assign(new Error('Explorer read timed out'), { status: 503 })), 10000); })
+            ]);
+            ctx.body = body;
+        }
+        catch (error) {
+            ctx.status = [400, 404, 405, 409, 413, 503].includes(error.status) ? error.status : 503;
+            ctx.body = { error: ctx.status === 503 ? 'Public explorer data unavailable; retry after node sync' : error.message };
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    };
+}

package/exports/http.js

@@ -1,12 +1,15 @@
+import { binaryHttp } from './binary-http.js';
 import koa from 'koa';
 import cors from '@koa/cors';
 import Router from '@koa/router';
-import { formatUnits, jsonStringifyBigInt } from '@leofcoin/utils';
+import { formatUnits } from '@leofcoin/utils';
 import { readFile } from 'fs/promises';
 import Showdown from 'showdown';
 import shared from './shared.js';
 import { dirname, join } from 'path';
 import { fileURLToPath } from 'url';
+import { managerMiddleware } from './manager.js';
+import { explorerMiddleware } from './explorer.js';
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 const converter = new Showdown.Converter();
@@ -22,39 +25,39 @@ export default (chain, port, networkVersion, remote = false) => {
     router.get('/', (ctx) => {
         ctx.body = converter.makeHtml(apiFile.toString());
     });
-    router.get('/network', (ctx) => {
+    router.all('/network', (ctx) => {
         ctx.body = {
             version: networkVersion
         };
     });
-    router.get('/chainIdentity', async (ctx) => {
+    router.all('/chainIdentity', async (ctx) => {
         ctx.body = await chain.getChainIdentity();
     });
-    router.get('/networkStats', async (ctx) => {
+    router.all('/networkStats', async (ctx) => {
         ctx.body = await shared.networkStats(chain, networkVersion);
     });
-    router.get('/balances', async (ctx) => {
+    router.all('/balances', async (ctx) => {
         ctx.body = await chain.balances;
     });
-    router.get('/balanceOf', async (ctx) => {
+    router.all('/balanceOf', async (ctx) => {
         // @ts-ignore
-        const balance = (await chain.balances)[ctx.query.address];
+        const balance = (await chain.balances)[ctx.state.rpcParams.address];
         if (balance)
-            ctx.body = ctx.query.format ? formatUnits(balance).toString() : balance.toString();
+            ctx.body = ctx.state.rpcParams.format ? formatUnits(balance).toString() : balance.toString();
         else
             ctx.body = '0n';
     });
-    router.get('/selectedAccount', (ctx) => {
+    router.all('/selectedAccount', (ctx) => {
         if (remote)
             ctx.body = globalThis.peernet.selectedAccount;
         else
             ctx.status = 405;
     });
-    router.get('/selectAccount', async (ctx) => {
+    router.all('/selectAccount', async (ctx) => {
         if (remote) {
-            globalThis.peernet.selectedAccount = ctx.query.address;
+            globalThis.peernet.selectedAccount = ctx.state.rpcParams.address;
             try {
-                await globalThis.walletStore.put('selected-account', ctx.query.address);
+                await globalThis.walletStore.put('selected-account', ctx.state.rpcParams.address);
             }
             catch (error) {
                 ctx.body = error.message;
@@ -64,97 +67,115 @@ export default (chain, port, networkVersion, remote = false) => {
             ctx.status = 405;
         }
     });
-    router.get('/accounts', async (ctx) => {
+    router.all('/accounts', async (ctx) => {
         if (remote)
             ctx.body = JSON.parse(new TextDecoder().decode(await globalThis.walletStore.get('accounts')));
         else
             ctx.status = 405;
     });
-    router.get('/hasTransactionToHandle', async (ctx) => {
+    router.all('/hasTransactionToHandle', async (ctx) => {
         ctx.body = await chain.hasTransactionToHandle();
     });
-    router.get('/getNonce', async (ctx) => {
-        ctx.body = await chain.getNonce(ctx.query.address);
+    router.all('/getNonce', async (ctx) => {
+        ctx.body = await chain.getNonce(ctx.state.rpcParams.address);
     });
-    router.get('/getBlock', async (ctx) => (ctx.body = await chain.getBlock(ctx.query.index)));
-    router.get('/blocks', async (ctx) => {
-        const limit = ctx.query.amount;
+    router.all('/getBlock', async (ctx) => (ctx.body = await chain.getBlock(ctx.state.rpcParams.index)));
+    router.all('/blocks', async (ctx) => {
+        const limit = ctx.state.rpcParams.amount;
         ctx.body = await globalThis.blockStore.values(limit);
     });
-    router.get('/sendTransaction', async (ctx) => {
+    router.all('/sendTransaction', async (ctx) => {
         try {
-            const tx = await chain.sendTransaction(ctx.query.transaction);
-            await tx.wait();
+            const tx = await chain.sendTransaction((ctx.state.rpcParams.transaction ?? ctx.state.rpcParams));
+            await (typeof tx.wait === 'function' ? tx.wait() : tx.wait);
             delete tx.wait;
-            ctx.body = JSON.stringify(tx, jsonStringifyBigInt);
+            ctx.body = tx;
         }
         catch (error) {
-            // ctx(202)
+            ctx.status = 422;
+            ctx.body = { error: error instanceof Error ? error.message : 'Transaction failed' };
         }
     });
-    router.get('/peerId', (ctx) => (ctx.body = globalThis.peernet.peerId));
-    router.get('/validators', (ctx) => (ctx.body = chain.validators));
-    router.get('/peers', (ctx) => (ctx.body = globalThis.peernet.peers.map(([id, peer]) => id)));
-    router.get('/lookup', async (ctx) => {
-        ctx.body = await chain.lookup(ctx.query.name);
-    });
-    router.get('/staticCall', async (ctx) => (ctx.body = await chain.staticCall(ctx.query.contract, ctx.query.method, ctx.query.params)));
-    router.get('/contracts', async (ctx) => (ctx.body = await chain.contracts));
-    router.get('/totalContracts', async (ctx) => (ctx.body = await chain.totalContracts));
-    router.get('/nativeToken', async (ctx) => (ctx.body = await chain.nativeToken));
-    router.get('/nativeCalls', async (ctx) => (ctx.body = await chain.nativeCalls));
-    router.get('/nativeMints', async (ctx) => (ctx.body = await chain.nativeMints));
-    router.get('/nativeBurns', async (ctx) => (ctx.body = await chain.nativeBurns));
-    router.get('/nativeTransfers', async (ctx) => (ctx.body = await chain.nativeTransfers));
-    router.get('/totalBurnAmount', async (ctx) => (ctx.body = await chain.totalBurnAmount));
-    router.get('/totalMintAmount', async (ctx) => (ctx.body = await chain.totalMintAmount));
-    router.get('/totalTransferAmount', async (ctx) => (ctx.body = await chain.totalTransferAmount));
-    router.get('/totalTransactions', async (ctx) => (ctx.body = await chain.totalTransactions));
-    router.get('/totalSize', async (ctx) => (ctx.body = await chain.totalSize));
-    router.get('/totalBlocks', async (ctx) => (ctx.body = await chain.totalBlocks));
-    router.get('/lastBlock', async (ctx) => (ctx.body = await chain.lastBlock));
-    router.get('/lastBlockHeight', async (ctx) => (ctx.body = await chain.lastBlockHeight));
-    router.get('/poolTransactions', async (ctx) => (ctx.body = await globalThis.transactionPoolStore.get()));
-    router.get('/transactionsInPool', async (ctx) => (ctx.body = await globalThis.transactionPoolStore.length()));
-    router.get('/transactionPoolSize', async (ctx) => (ctx.body = await globalThis.transactionPoolStore.size()));
-    router.get('/participating', (ctx) => (ctx.body = chain.participating));
-    router.get('/participate', async (ctx) => {
+    router.all('/peerId', (ctx) => (ctx.body = globalThis.peernet.peerId));
+    router.all('/validators', (ctx) => (ctx.body = chain.validators));
+    router.all('/peers', (ctx) => (ctx.body = globalThis.peernet.peers.map(([id, peer]) => id)));
+    router.all('/lookup', async (ctx) => {
+        ctx.body = await chain.lookup(ctx.state.rpcParams.name);
+    });
+    router.all('/staticCall', async (ctx) => {
+        let params;
+        try {
+            params = ctx.state.rpcParams.params ?? [];
+            if (!Array.isArray(params) || typeof ctx.state.rpcParams.contract !== 'string' || typeof ctx.state.rpcParams.method !== 'string')
+                throw new Error('Invalid read parameters');
+        }
+        catch {
+            ctx.status = 400;
+            ctx.body = { error: 'staticCall params must be a binary array' };
+            return;
+        }
+        try {
+            const value = await chain.staticCall(ctx.state.rpcParams.contract, ctx.state.rpcParams.method, params);
+            ctx.body = value ?? null;
+        }
+        catch (error) {
+            ctx.status = 422;
+            ctx.body = { error: error instanceof Error ? error.message : 'Read-only contract query failed' };
+        }
+    });
+    router.all('/contracts', async (ctx) => (ctx.body = await chain.contracts));
+    router.all('/totalContracts', async (ctx) => (ctx.body = await chain.totalContracts));
+    router.all('/nativeToken', async (ctx) => (ctx.body = await chain.nativeToken));
+    router.all('/nativeCalls', async (ctx) => (ctx.body = await chain.nativeCalls));
+    router.all('/nativeMints', async (ctx) => (ctx.body = await chain.nativeMints));
+    router.all('/nativeBurns', async (ctx) => (ctx.body = await chain.nativeBurns));
+    router.all('/nativeTransfers', async (ctx) => (ctx.body = await chain.nativeTransfers));
+    router.all('/totalBurnAmount', async (ctx) => (ctx.body = await chain.totalBurnAmount));
+    router.all('/totalMintAmount', async (ctx) => (ctx.body = await chain.totalMintAmount));
+    router.all('/totalTransferAmount', async (ctx) => (ctx.body = await chain.totalTransferAmount));
+    router.all('/totalTransactions', async (ctx) => (ctx.body = await chain.totalTransactions));
+    router.all('/totalSize', async (ctx) => (ctx.body = await chain.totalSize));
+    router.all('/totalBlocks', async (ctx) => (ctx.body = await chain.totalBlocks));
+    router.all('/lastBlock', async (ctx) => (ctx.body = await chain.lastBlock));
+    router.all('/lastBlockHeight', async (ctx) => (ctx.body = await chain.lastBlockHeight));
+    router.all('/poolTransactions', async (ctx) => (ctx.body = await globalThis.transactionPoolStore.get()));
+    router.all('/transactionsInPool', async (ctx) => (ctx.body = await globalThis.transactionPoolStore.length()));
+    router.all('/transactionPoolSize', async (ctx) => (ctx.body = await globalThis.transactionPoolStore.size()));
+    router.all('/participating', (ctx) => (ctx.body = chain.participating));
+    router.all('/participate', async (ctx) => {
         if (remote)
-            ctx.body = await chain.participate(ctx.query.address);
+            ctx.body = await chain.participate(ctx.state.rpcParams.address);
         else
             ctx.status = 405;
     });
-    router.get('/deployContract', async (ctx) => {
+    router.all('/deployContract', async (ctx) => {
         try {
-            const tx = await chain.deployContract(ctx.query.contract, ctx.query.transaction);
-            await tx.wait();
+            const tx = await chain.deployContract(ctx.state.rpcParams.contract, ctx.state.rpcParams.transaction);
+            await (typeof tx.wait === 'function' ? tx.wait() : tx.wait);
             delete tx.wait;
-            ctx.body = JSON.stringify(tx, jsonStringifyBigInt);
+            ctx.body = tx;
         }
         catch (error) {
-            ctx.body = error.mesage;
+            ctx.status = 422;
+            ctx.body = { error: error instanceof Error ? error.message : 'Deployment failed' };
         }
     });
-    router.get('/createContractAddress', async (ctx) => {
+    router.all('/createContractAddress', async (ctx) => {
         try {
-            const address = await chain.createContractAddress(ctx.query.owner, ctx.query.code, ctx.query.params);
+            const address = await chain.createContractAddress(ctx.state.rpcParams.owner, ctx.state.rpcParams.code, ctx.state.rpcParams.params);
             ctx.body = address;
         }
         catch (error) { }
     });
-    router.get('/blockHashMap', async (ctx) => (ctx.body = chain.blockHashMap));
-    router.get('/bootstrap', async (ctx) => {
-        ctx.body = (await shared.bootstrap()).map((value) => Array.from(value.toString()));
+    router.all('/blockHashMap', async (ctx) => (ctx.body = chain.blockHashMap));
+    router.all('/bootstrap', async (ctx) => {
+        ctx.body = await shared.bootstrap();
     });
     // todo finish ...
     api.use(cors({ origin: '*' }));
-    api.use(async (ctx, next) => {
-        await next();
-        if (ctx.body !== null && typeof ctx.body === 'object') {
-            ctx.body = JSON.stringify(ctx.body, jsonStringifyBigInt);
-            ctx.type = 'application/json';
-        }
-    });
+    api.use(binaryHttp);
+    api.use(explorerMiddleware(chain));
+    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,137 @@
+import { ContractMessage, TransactionMessage } from '@leofcoin/messages';
+import { verifyChainIdentity } from '@leofcoin/lib/chain-identity';
+import { ManagerReceipts } from './manager-receipts.js';
+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;
+    }
+}
+/** 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/octet-stream' };
+            return;
+        }
+        try {
+            const body = ctx.state.rpcParams;
+            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 (!(body.contract instanceof Uint8Array))
+                        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/exports/rpc-handler.d.ts

@@ -0,0 +1,2 @@
+/** Socket route dispatch does not await rejected promises; contain failures here. */
+export declare const guardRpcHandler: (handler: any) => (...args: any[]) => Promise<any>;

package/exports/rpc-handler.js

@@ -0,0 +1,18 @@
+/** Socket route dispatch does not await rejected promises; contain failures here. */
+export const guardRpcHandler = handler => async (...args) => {
+    const index = args.findIndex(value => value && typeof value.send === 'function');
+    if (index < 0)
+        return;
+    const response = args[index];
+    const send = (value, status = 200) => response.send(value ?? null, status);
+    args[index] = { ...response, send };
+    try {
+        return await handler(...args);
+    }
+    catch (error) {
+        try {
+            send({ error: error instanceof Error ? error.message : 'RPC operation failed' }, 422);
+        }
+        catch { /* The socket may already be closed; never reject the detached route. */ }
+    }
+};

package/exports/ws.d.ts

@@ -1,5 +1,2 @@
-declare const _default: (chain: any, port: any, networkVersion: any, remote?: boolean) => Promise<{
-    close: () => void;
-    connections: import("socket-request-server/connection").SocketRequestConnection[];
-}>;
+declare const _default: (chain: any, port: any, networkVersion: any, remote?: boolean) => any;
 export default _default;

package/exports/ws.js

@@ -1,8 +1,9 @@
-import Server from 'socket-request-server';
+import Server from './binary-socket.js';
 import { formatUnits } from '@leofcoin/utils';
 import shared from './shared.js';
+import { guardRpcHandler } from './rpc-handler.js';
 export default (chain, port, networkVersion, remote = false) => {
-    return Server({ port, protocol: networkVersion }, {
+    const routes = {
         network: async ({ send }) => {
             send({ version: networkVersion });
         },
@@ -50,19 +51,19 @@ export default (chain, port, networkVersion, remote = false) => {
         sendTransaction: async (transaction, { send }) => {
             try {
                 const tx = await chain.sendTransaction(transaction);
-                await tx.wait();
+                await (typeof tx.wait === 'function' ? tx.wait() : tx.wait);
                 delete tx.wait;
                 send(tx);
             }
             catch (error) {
-                send(202);
+                send({ error: error instanceof Error ? error.message : 'Transaction failed' }, 422);
             }
         },
         peerId: ({ send }) => send(globalThis.peernet.peerId),
         peers: ({ send }) => send(globalThis.peernet.peers.map(([id, peer]) => id)),
         validators: ({ send }) => send(chain.validators),
         lookup: async ({ name }, { send }) => send(await chain.lookup(name)),
-        staticCall: async ({ contract, method, params }, { send }) => send(await chain.staticCall(contract, method, params)),
+        staticCall: async ({ contract, method, params }, { send }) => send(await chain.staticCall(contract, method, params ?? [])),
         contracts: async ({ send }) => send(await chain.contracts),
         totalContracts: async ({ send }) => send(await chain.totalContracts),
         nativeToken: async ({ send }) => send(await chain.nativeToken),
@@ -93,12 +94,12 @@ export default (chain, port, networkVersion, remote = false) => {
         deployContract: async ({ transaction, contract }, { send }) => {
             try {
                 const tx = await chain.deployContract(contract, transaction);
-                await tx.wait();
+                await (typeof tx.wait === 'function' ? tx.wait() : tx.wait);
                 delete tx.wait;
                 send(tx);
             }
             catch (error) {
-                send(error.message);
+                send({ error: error instanceof Error ? error.message : 'Deployment failed' }, 422);
             }
         },
         createContractAddress: async ({ owner, code, params }, { send }) => {
@@ -107,12 +108,13 @@ export default (chain, port, networkVersion, remote = false) => {
                 send(address);
             }
             catch (error) {
-                send(error);
+                send({ error: error instanceof Error ? error.message : 'Contract address failed' }, 422);
             }
         },
         blockHashMap: async ({ send }) => send(await chain.blockHashMap),
         bootstrap: async ({ send }) => {
             send(await shared.bootstrap());
         }
-    });
+    };
+    return Server({ port, protocol: networkVersion }, Object.fromEntries(Object.entries(routes).map(([name, handler]) => [name, guardRpcHandler(handler)])));
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@leofcoin/endpoints",
-  "version": "0.4.11",
+  "version": "0.5.0",
   "description": "",
   "type": "module",
   "exports": {
@@ -34,12 +34,15 @@
   },
   "homepage": "https://github.com/leofcoin/monorepo/tree/main/packages/endpoints#readme",
   "dependencies": {
+    "@leofcoin/binary": "^1.1.0",
+    "ws": "^8.22.0",
+    "@leofcoin/lib": "^1.4.0",
+    "@leofcoin/messages": "^2.0.0",
     "@koa/cors": "^5.0.0",
     "@koa/router": "^13.1.1",
     "@leofcoin/utils": "^1.1.45",
     "koa": "^3.0.1",
-    "showdown": "^2.1.0",
-    "socket-request-server": "^1.6.17"
+    "showdown": "^2.1.0"
   },
   "devDependencies": {
     "@leofcoin/types": "^1.0.22",