@leofcoin/endpoints 0.4.12 → 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
@@ -8,11 +15,40 @@ http(chain, port, networkVersion)
 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/json` (maximum 1 MiB). Requests must
+`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. Existing endpoints remain unchanged.
+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.
 
@@ -21,7 +57,7 @@ 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 |
+| `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` |
 
@@ -60,4 +96,4 @@ 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.
+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,13 +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();
@@ -23,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;
@@ -65,97 +67,114 @@ 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.js

@@ -1,7 +1,6 @@
 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;
@@ -10,22 +9,6 @@ class RequestError extends Error {
         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;
@@ -40,13 +23,11 @@ export function managerMiddleware(chain) {
         ctx.set('Cache-Control', 'no-store');
         if (ctx.method !== 'POST') {
             ctx.status = 405;
-            ctx.body = { error: 'Use POST with application/json' };
+            ctx.body = { error: 'Use POST with application/octet-stream' };
             return;
         }
         try {
-            if (!ctx.is('application/json'))
-                throw new RequestError(415, 'Content-Type must be application/json');
-            const body = await readBody(ctx.req);
+            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());
@@ -102,7 +83,7 @@ export function managerMiddleware(chain) {
                 await chain.validateTransactionSignature(message);
                 let contract;
                 if (body.contract !== undefined) {
-                    if (typeof body.contract !== 'string')
+                    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 ||

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.12",
+  "version": "0.5.0",
   "description": "",
   "type": "module",
   "exports": {
@@ -34,14 +34,15 @@
   },
   "homepage": "https://github.com/leofcoin/monorepo/tree/main/packages/endpoints#readme",
   "dependencies": {
-    "@leofcoin/lib": "^1.3.15",
-    "@leofcoin/messages": "^1.6.5",
+    "@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",