boing-sdk 0.3.0

package/dist/referenceFungibleSecuredDeployBytecode.js

@@ -0,0 +1,274 @@
+/**
+ * Build **`0xFD` + init** deploy payloads for the secured reference fungible, matching
+ * `boing_execution::reference_fungible_secured_deploy_bytecode` / init layout.
+ *
+ * Runtime bytes are pinned from `defaultReferenceFungibleSecuredRuntimeBytecodeHex.ts`
+ * (regenerated with `embed-reference-fungible-secured-template-hex.mjs`).
+ */
+import { DEFAULT_REFERENCE_FUNGIBLE_SECURED_RUNTIME_BYTECODE_HEX } from './defaultReferenceFungibleSecuredRuntimeBytecodeHex.js';
+import { bytesToHex, hexToBytes } from './hex.js';
+import { normalizeNativeTokenSecurity, } from './nativeTokenSecurity.js';
+const CONTRACT_DEPLOY_INIT_CODE_MARKER = 0xfd;
+const Op = {
+    Stop: 0x00,
+    Add: 0x01,
+    Lt: 0x10,
+    Eq: 0x14,
+    IsZero: 0x15,
+    Caller: 0x33,
+    BlockHeight: 0x40,
+    MLoad: 0x51,
+    MStore: 0x52,
+    SLoad: 0x54,
+    SStore: 0x55,
+    JumpI: 0x57,
+    Push32: 0x7f,
+    Return: 0xf3,
+};
+/** Mirrors `reference_fungible_secured` flag words (u32). */
+export const FLAG_DENYLIST = 0x01;
+export const FLAG_MAX_TX = 0x02;
+export const FLAG_MAX_WALLET = 0x04;
+export const FLAG_ANTI_BOT = 0x08;
+export const FLAG_COOLDOWN = 0x10;
+export const FLAG_NO_MINT = 0x20;
+export const FLAG_TRANSFER_UNLOCK = 0x40;
+const U128_MAX = (1n << 128n) - 1n;
+const U64_MAX = (1n << 64n) - 1n;
+const DEFAULT_ANTI_BOT_EXTRA_BLOCKS = 100n;
+function keyLastByte(b) {
+    const k = new Uint8Array(32);
+    k[31] = b & 0xff;
+    return k;
+}
+function wordZero() {
+    return new Uint8Array(32);
+}
+function wordOne() {
+    const w = new Uint8Array(32);
+    w[31] = 1;
+    return w;
+}
+function wordU32(n) {
+    const w = new Uint8Array(32);
+    new DataView(w.buffer).setUint32(28, n >>> 0, false);
+    return w;
+}
+function wordU64(n) {
+    const w = new Uint8Array(32);
+    const v = n <= U64_MAX ? n : U64_MAX;
+    new DataView(w.buffer).setBigUint64(24, v, false);
+    return w;
+}
+function amountWord(amount) {
+    const w = new Uint8Array(32);
+    let v = amount <= U128_MAX ? amount : U128_MAX;
+    for (let i = 31; i >= 16; i--) {
+        w[i] = Number(v & 0xffn);
+        v >>= 8n;
+    }
+    return w;
+}
+function push32(w) {
+    const out = new Uint8Array(33);
+    out[0] = Op.Push32;
+    out.set(w, 1);
+    return out;
+}
+function u8(b) {
+    return new Uint8Array([b & 0xff]);
+}
+function concatBytes(...parts) {
+    const n = parts.reduce((a, p) => a + p.length, 0);
+    const out = new Uint8Array(n);
+    let o = 0;
+    for (const p of parts) {
+        out.set(p, o);
+        o += p.length;
+    }
+    return out;
+}
+function emitRuntimeToMemory(runtime) {
+    const padLen = (Math.ceil(runtime.length / 32) | 0) * 32;
+    const rt = new Uint8Array(padLen);
+    rt.set(runtime, 0);
+    const chunks = [];
+    for (let off = 0; off < padLen; off += 32) {
+        chunks.push(push32(rt.subarray(off, off + 32)));
+        chunks.push(push32(wordU64(BigInt(off))));
+        chunks.push(u8(Op.MStore));
+    }
+    return concatBytes(...chunks);
+}
+/**
+ * Init bytecode only (no `0xFD` prefix), matching `reference_fungible_secured_init_bytecode`.
+ */
+export function referenceFungibleSecuredInitBytecode(config, runtime) {
+    const refSecAdminKey = keyLastByte(0xc1);
+    const refSecAntiBotEndKey = keyLastByte(0xc7);
+    const refSecFlagsKey = keyLastByte(0xc3);
+    const refSecMaxTxKey = keyLastByte(0xc4);
+    const refSecMaxWalletKey = keyLastByte(0xc5);
+    const refSecAntiBotMaxKey = keyLastByte(0xc8);
+    const refSecCooldownSecsKey = keyLastByte(0xc9);
+    const refSecXferUnlockKey = keyLastByte(0xca);
+    const refSecPausedKey = keyLastByte(0xc6);
+    const parts = [
+        u8(Op.Caller),
+        push32(refSecAdminKey),
+        u8(Op.SStore),
+        u8(Op.BlockHeight),
+        push32(wordU64(config.antiBotExtraBlocks)),
+        u8(Op.Add),
+        push32(refSecAntiBotEndKey),
+        u8(Op.SStore),
+        push32(wordU32(config.flags >>> 0)),
+        push32(refSecFlagsKey),
+        u8(Op.SStore),
+        push32(amountWord(config.maxTx)),
+        push32(refSecMaxTxKey),
+        u8(Op.SStore),
+        push32(amountWord(config.maxWallet)),
+        push32(refSecMaxWalletKey),
+        u8(Op.SStore),
+        push32(amountWord(config.antiBotMaxAmount)),
+        push32(refSecAntiBotMaxKey),
+        u8(Op.SStore),
+        push32(wordU64(config.cooldownSecs)),
+        push32(refSecCooldownSecsKey),
+        u8(Op.SStore),
+        push32(wordU64(config.transferUnlockHeight)),
+        push32(refSecXferUnlockKey),
+        u8(Op.SStore),
+        push32(config.initialPaused ? wordOne() : wordZero()),
+        push32(refSecPausedKey),
+        u8(Op.SStore),
+        emitRuntimeToMemory(runtime),
+        push32(wordU64(BigInt(runtime.length))),
+        push32(wordZero()),
+        u8(Op.Return),
+        u8(Op.Stop),
+    ];
+    return concatBytes(...parts);
+}
+/** Full deploy: `0xFD || init` (init `RETURN`s runtime). */
+export function referenceFungibleSecuredDeployBytecode(config, runtime) {
+    const rt = runtime ??
+        hexToBytes(DEFAULT_REFERENCE_FUNGIBLE_SECURED_RUNTIME_BYTECODE_HEX);
+    const init = referenceFungibleSecuredInitBytecode(config, rt);
+    return concatBytes(u8(CONTRACT_DEPLOY_INIT_CODE_MARKER), init);
+}
+export function referenceFungibleSecuredDeployBytecodeHex(config, runtime) {
+    return bytesToHex(referenceFungibleSecuredDeployBytecode(config, runtime));
+}
+function parseDecimalU128(label, s) {
+    const t = s.trim();
+    if (!t)
+        return 0n;
+    if (!/^[0-9]+$/.test(t)) {
+        throw new Error(`${label}: expected non-negative decimal integer, got ${JSON.stringify(s)}`);
+    }
+    const v = BigInt(t);
+    if (v > U128_MAX) {
+        throw new Error(`${label}: value exceeds uint128`);
+    }
+    return v;
+}
+function parseDecimalU64(label, s) {
+    const t = s.trim();
+    if (!t)
+        return 0n;
+    if (!/^[0-9]+$/.test(t)) {
+        throw new Error(`${label}: expected non-negative decimal integer, got ${JSON.stringify(s)}`);
+    }
+    const v = BigInt(t);
+    if (v > U64_MAX) {
+        throw new Error(`${label}: value exceeds uint64`);
+    }
+    return v;
+}
+/**
+ * Map wizard / `boing.native_token_security.v1` fields to secured init storage (on-chain enforcement).
+ *
+ * - **renounceOwnership**: not applied at deploy (admin is deployer); use admin `0x05` after deploy.
+ * - **timelock**: maps to transfer-unlock **block height** = `chainHeight + timelockDelay` (both decimals).
+ */
+export function referenceFungibleSecuredConfigFromNativeTokenSecurity(input, ctx = {}) {
+    const n = normalizeNativeTokenSecurity(input);
+    let flags = 0;
+    let maxTx = 0n;
+    let maxWallet = 0n;
+    let antiBotExtraBlocks = 0n;
+    let antiBotMaxAmount = 0n;
+    let cooldownSecs = 0n;
+    let transferUnlockHeight = 0n;
+    let initialPaused = false;
+    if (n.enableBlacklist || n.enableFreezing) {
+        flags |= FLAG_DENYLIST;
+    }
+    if (n.renounceMint) {
+        flags |= FLAG_NO_MINT;
+    }
+    if (n.pauseFunction) {
+        initialPaused = true;
+    }
+    const maxTxV = parseDecimalU128('maxTxAmount', n.maxTxAmount);
+    if (maxTxV > 0n) {
+        flags |= FLAG_MAX_TX;
+        maxTx = maxTxV;
+    }
+    const wantWalletCap = n.maxWallet || n.antiWhale;
+    const pctRaw = n.maxWalletPercentage.trim();
+    const supply = ctx.mintFirstTotalSupplyWei;
+    if (wantWalletCap) {
+        flags |= FLAG_MAX_WALLET;
+        if (pctRaw && supply !== undefined && supply > 0n) {
+            const pct = parseDecimalU128('maxWalletPercentage', pctRaw);
+            if (pct > 100n) {
+                throw new Error('maxWalletPercentage: must be 0–100');
+            }
+            maxWallet = (supply * pct) / 100n;
+        }
+        else if (maxTxV > 0n) {
+            maxWallet = maxTxV;
+        }
+        else {
+            throw new Error('maxWallet / antiWhale: set maxWalletPercentage and mintFirstTotalSupplyWei on the deploy builder, or set maxTxAmount to use as the per-wallet cap');
+        }
+    }
+    if (n.antiBot) {
+        flags |= FLAG_ANTI_BOT;
+        antiBotExtraBlocks = DEFAULT_ANTI_BOT_EXTRA_BLOCKS;
+        antiBotMaxAmount = maxTxV > 0n ? maxTxV : U128_MAX;
+    }
+    const cd = parseDecimalU64('cooldownPeriod', n.cooldownPeriod);
+    if (cd > 0n) {
+        flags |= FLAG_COOLDOWN;
+        cooldownSecs = cd;
+    }
+    if (n.timelock) {
+        const delay = parseDecimalU64('timelockDelay', n.timelockDelay);
+        if (ctx.chainHeight === undefined) {
+            throw new Error('nativeTokenSecurity.timelock: pass chainContext.chainHeight (from boing_chainHeight) so transfer unlock height can be set on-chain');
+        }
+        flags |= FLAG_TRANSFER_UNLOCK;
+        transferUnlockHeight = ctx.chainHeight + delay;
+        if (transferUnlockHeight > U64_MAX) {
+            transferUnlockHeight = U64_MAX;
+        }
+    }
+    return {
+        flags,
+        maxTx,
+        maxWallet,
+        antiBotExtraBlocks,
+        antiBotMaxAmount,
+        cooldownSecs,
+        transferUnlockHeight,
+        initialPaused,
+    };
+}
+export function buildReferenceFungibleSecuredDeployBytecodeHexFromNativeTokenSecurity(input, ctx = {}) {
+    const cfg = referenceFungibleSecuredConfigFromNativeTokenSecurity(input, ctx);
+    return referenceFungibleSecuredDeployBytecodeHex(cfg);
+}

package/dist/referenceNft.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Reference NFT calldata layout (Boing-defined). See `docs/BOING-REFERENCE-NFT.md`.
+ */
+export declare const SELECTOR_OWNER_OF = 3;
+export declare const SELECTOR_TRANSFER_NFT = 4;
+export declare const SELECTOR_SET_METADATA_HASH = 5;
+/** 96-byte `owner_of(token_id)` reference calldata. */
+export declare function encodeReferenceOwnerOfCalldata(tokenIdHex32: string): Uint8Array;
+/** 96-byte `transfer_nft(to, token_id)` reference calldata. */
+export declare function encodeReferenceTransferNftCalldata(toHexAccount32: string, tokenIdHex32: string): Uint8Array;
+/** 96-byte `set_metadata_hash(token_id, hash)` reference calldata. */
+export declare function encodeReferenceSetMetadataHashCalldata(tokenIdHex32: string, metadataHashHex32: string): Uint8Array;
+export declare function encodeReferenceOwnerOfCalldataHex(tokenIdHex32: string): string;
+//# sourceMappingURL=referenceNft.d.ts.map

package/dist/referenceNft.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"referenceNft.d.ts","sourceRoot":"","sources":["../src/referenceNft.ts"],"names":[],"mappings":"AAAA;;GAEG;AASH,eAAO,MAAM,iBAAiB,IAAO,CAAC;AACtC,eAAO,MAAM,qBAAqB,IAAO,CAAC;AAC1C,eAAO,MAAM,0BAA0B,IAAO,CAAC;AAE/C,uDAAuD;AACvD,wBAAgB,8BAA8B,CAAC,YAAY,EAAE,MAAM,GAAG,UAAU,CAK/E;AAED,+DAA+D;AAC/D,wBAAgB,kCAAkC,CAChD,cAAc,EAAE,MAAM,EACtB,YAAY,EAAE,MAAM,GACnB,UAAU,CAMZ;AAED,sEAAsE;AACtE,wBAAgB,sCAAsC,CACpD,YAAY,EAAE,MAAM,EACpB,iBAAiB,EAAE,MAAM,GACxB,UAAU,CAMZ;AAED,wBAAgB,iCAAiC,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAE9E"}

package/dist/referenceNft.js

@@ -0,0 +1,34 @@
+/**
+ * Reference NFT calldata layout (Boing-defined). See `docs/BOING-REFERENCE-NFT.md`.
+ */
+import { bytesToHex } from './hex.js';
+import { calldataAccountIdWord, calldataFixedWord32, calldataSelectorLastByte, } from './calldata.js';
+export const SELECTOR_OWNER_OF = 0x03;
+export const SELECTOR_TRANSFER_NFT = 0x04;
+export const SELECTOR_SET_METADATA_HASH = 0x05;
+/** 96-byte `owner_of(token_id)` reference calldata. */
+export function encodeReferenceOwnerOfCalldata(tokenIdHex32) {
+    const out = new Uint8Array(96);
+    out.set(calldataSelectorLastByte(SELECTOR_OWNER_OF), 0);
+    out.set(calldataFixedWord32(tokenIdHex32), 32);
+    return out;
+}
+/** 96-byte `transfer_nft(to, token_id)` reference calldata. */
+export function encodeReferenceTransferNftCalldata(toHexAccount32, tokenIdHex32) {
+    const out = new Uint8Array(96);
+    out.set(calldataSelectorLastByte(SELECTOR_TRANSFER_NFT), 0);
+    out.set(calldataAccountIdWord(toHexAccount32), 32);
+    out.set(calldataFixedWord32(tokenIdHex32), 64);
+    return out;
+}
+/** 96-byte `set_metadata_hash(token_id, hash)` reference calldata. */
+export function encodeReferenceSetMetadataHashCalldata(tokenIdHex32, metadataHashHex32) {
+    const out = new Uint8Array(96);
+    out.set(calldataSelectorLastByte(SELECTOR_SET_METADATA_HASH), 0);
+    out.set(calldataFixedWord32(tokenIdHex32), 32);
+    out.set(calldataFixedWord32(metadataHashHex32), 64);
+    return out;
+}
+export function encodeReferenceOwnerOfCalldataHex(tokenIdHex32) {
+    return bytesToHex(encodeReferenceOwnerOfCalldata(tokenIdHex32));
+}

package/dist/referenceToken.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Reference fungible calldata layout (Boing-defined). See `docs/BOING-REFERENCE-TOKEN.md`.
+ */
+/** Selector low byte for reference `transfer`. */
+export declare const SELECTOR_TRANSFER = 1;
+/** Selector low byte for reference first-mint style hook. */
+export declare const SELECTOR_MINT_FIRST = 2;
+/** Build 96-byte reference `transfer(to, amount)` calldata. */
+export declare function encodeReferenceTransferCalldata(toHexAccount32: string, amount: bigint): Uint8Array;
+/** Build 96-byte reference `mint_first` calldata. */
+export declare function encodeReferenceMintFirstCalldata(toHexAccount32: string, amount: bigint): Uint8Array;
+/** Hex `0x` + 96-byte reference transfer calldata. */
+export declare function encodeReferenceTransferCalldataHex(toHexAccount32: string, amount: bigint): string;
+//# sourceMappingURL=referenceToken.d.ts.map

package/dist/referenceToken.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"referenceToken.d.ts","sourceRoot":"","sources":["../src/referenceToken.ts"],"names":[],"mappings":"AAAA;;GAEG;AASH,kDAAkD;AAClD,eAAO,MAAM,iBAAiB,IAAO,CAAC;AACtC,6DAA6D;AAC7D,eAAO,MAAM,mBAAmB,IAAO,CAAC;AAExC,+DAA+D;AAC/D,wBAAgB,+BAA+B,CAAC,cAAc,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,UAAU,CAMlG;AAED,qDAAqD;AACrD,wBAAgB,gCAAgC,CAAC,cAAc,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,UAAU,CAMnG;AAED,sDAAsD;AACtD,wBAAgB,kCAAkC,CAAC,cAAc,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAEjG"}

package/dist/referenceToken.js

@@ -0,0 +1,29 @@
+/**
+ * Reference fungible calldata layout (Boing-defined). See `docs/BOING-REFERENCE-TOKEN.md`.
+ */
+import { bytesToHex } from './hex.js';
+import { calldataAccountIdWord, calldataSelectorLastByte, calldataU128BeWord, } from './calldata.js';
+/** Selector low byte for reference `transfer`. */
+export const SELECTOR_TRANSFER = 0x01;
+/** Selector low byte for reference first-mint style hook. */
+export const SELECTOR_MINT_FIRST = 0x02;
+/** Build 96-byte reference `transfer(to, amount)` calldata. */
+export function encodeReferenceTransferCalldata(toHexAccount32, amount) {
+    const out = new Uint8Array(96);
+    out.set(calldataSelectorLastByte(SELECTOR_TRANSFER), 0);
+    out.set(calldataAccountIdWord(toHexAccount32), 32);
+    out.set(calldataU128BeWord(amount), 64);
+    return out;
+}
+/** Build 96-byte reference `mint_first` calldata. */
+export function encodeReferenceMintFirstCalldata(toHexAccount32, amount) {
+    const out = new Uint8Array(96);
+    out.set(calldataSelectorLastByte(SELECTOR_MINT_FIRST), 0);
+    out.set(calldataAccountIdWord(toHexAccount32), 32);
+    out.set(calldataU128BeWord(amount), 64);
+    return out;
+}
+/** Hex `0x` + 96-byte reference transfer calldata. */
+export function encodeReferenceTransferCalldataHex(toHexAccount32, amount) {
+    return bytesToHex(encodeReferenceTransferCalldata(toHexAccount32, amount));
+}

package/dist/retryAfter.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Parse HTTP **`Retry-After`** (RFC 7231): delay in seconds as integer, or an HTTP-date.
+ * Returns milliseconds to wait, or **`undefined`** if missing / unparseable.
+ */
+export declare function parseRetryAfterMs(value: string | null): number | undefined;
+//# sourceMappingURL=retryAfter.d.ts.map

package/dist/retryAfter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"retryAfter.d.ts","sourceRoot":"","sources":["../src/retryAfter.ts"],"names":[],"mappings":"AAGA;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,GAAG,SAAS,CAgB1E"}

package/dist/retryAfter.js

@@ -0,0 +1,24 @@
+/** Cap parsed delay so a bad header cannot stall the client for hours. */
+const MAX_RETRY_AFTER_MS = 86400000; // 24h
+/**
+ * Parse HTTP **`Retry-After`** (RFC 7231): delay in seconds as integer, or an HTTP-date.
+ * Returns milliseconds to wait, or **`undefined`** if missing / unparseable.
+ */
+export function parseRetryAfterMs(value) {
+    if (value == null)
+        return undefined;
+    const trimmed = value.trim();
+    if (trimmed === '')
+        return undefined;
+    const asInt = Number.parseInt(trimmed, 10);
+    if (!Number.isNaN(asInt) && asInt >= 0 && String(asInt) === trimmed) {
+        return Math.min(asInt * 1000, MAX_RETRY_AFTER_MS);
+    }
+    const when = Date.parse(trimmed);
+    if (!Number.isNaN(when)) {
+        const delta = when - Date.now();
+        if (delta > 0)
+            return Math.min(delta, MAX_RETRY_AFTER_MS);
+    }
+    return undefined;
+}

package/dist/rpcCapabilities.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Optional `boing_*` JSON-RPC methods: probe availability without assuming a full node build.
+ * Uses JSON-RPC **-32601** (method not found) to detect missing handlers — same as integration fallbacks.
+ */
+import type { BoingClient } from './client.js';
+/** Result of probing a single RPC method. */
+export interface BoingRpcMethodProbe {
+    /** `true` if the call completed without throwing. */
+    available: boolean;
+    /** Present when `available` is false. */
+    code?: number;
+    message?: string;
+}
+/** Named probes useful for indexers, wallets, and debugging version skew. */
+export interface BoingRpcCapabilities {
+    boing_chainHeight: BoingRpcMethodProbe;
+    boing_getSyncState: BoingRpcMethodProbe;
+    boing_getBlockByHeight: BoingRpcMethodProbe;
+    boing_getLogs: BoingRpcMethodProbe;
+    boing_getTransactionReceipt: BoingRpcMethodProbe;
+    boing_getNetworkInfo: BoingRpcMethodProbe;
+}
+/** Result of {@link probeBoingRpcCapabilities}: core probes plus optional discovery fields. */
+export interface BoingRpcProbeBundle {
+    /** From `boing_clientVersion` when implemented; **`null`** if **-32601** or unset. */
+    clientVersion: string | null;
+    /** From `boing_rpcSupportedMethods` when implemented; **`null`** if **-32601** or unset. */
+    supportedMethods: string[] | null;
+    methods: BoingRpcCapabilities;
+}
+/**
+ * Call discovery plus a small set of read-only RPCs with minimal parameters.
+ * A method is **available** if it returns (including JSON-RPC `result: null` for unknown tx/block).
+ */
+export declare function probeBoingRpcCapabilities(client: BoingClient): Promise<BoingRpcProbeBundle>;
+/** Count of core probed methods with `available: true`. */
+export declare function countAvailableBoingRpcMethods(bundleOrMethods: BoingRpcProbeBundle | BoingRpcCapabilities): number;
+/**
+ * Human-readable diagnosis when **`probeBoingRpcCapabilities`** shows gaps.
+ * **`undefined`** when all probed methods are available, or when there is nothing actionable to say.
+ */
+export declare function explainBoingRpcProbeGaps(bundleOrMethods: BoingRpcProbeBundle | BoingRpcCapabilities): string | undefined;
+//# sourceMappingURL=rpcCapabilities.d.ts.map

package/dist/rpcCapabilities.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rpcCapabilities.d.ts","sourceRoot":"","sources":["../src/rpcCapabilities.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAG/C,6CAA6C;AAC7C,MAAM,WAAW,mBAAmB;IAClC,qDAAqD;IACrD,SAAS,EAAE,OAAO,CAAC;IACnB,yCAAyC;IACzC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,6EAA6E;AAC7E,MAAM,WAAW,oBAAoB;IACnC,iBAAiB,EAAE,mBAAmB,CAAC;IACvC,kBAAkB,EAAE,mBAAmB,CAAC;IACxC,sBAAsB,EAAE,mBAAmB,CAAC;IAC5C,aAAa,EAAE,mBAAmB,CAAC;IACnC,2BAA2B,EAAE,mBAAmB,CAAC;IACjD,oBAAoB,EAAE,mBAAmB,CAAC;CAC3C;AAED,+FAA+F;AAC/F,MAAM,WAAW,mBAAmB;IAClC,sFAAsF;IACtF,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,4FAA4F;IAC5F,gBAAgB,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC;IAClC,OAAO,EAAE,oBAAoB,CAAC;CAC/B;AA8BD;;;GAGG;AACH,wBAAsB,yBAAyB,CAAC,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAuEjG;AAED,2DAA2D;AAC3D,wBAAgB,6BAA6B,CAC3C,eAAe,EAAE,mBAAmB,GAAG,oBAAoB,GAC1D,MAAM,CAGR;AAED;;;GAGG;AACH,wBAAgB,wBAAwB,CACtC,eAAe,EAAE,mBAAmB,GAAG,oBAAoB,GAC1D,MAAM,GAAG,SAAS,CAgDpB"}

package/dist/rpcCapabilities.js

@@ -0,0 +1,159 @@
+/**
+ * Optional `boing_*` JSON-RPC methods: probe availability without assuming a full node build.
+ * Uses JSON-RPC **-32601** (method not found) to detect missing handlers — same as integration fallbacks.
+ */
+import { BoingRpcError, isBoingRpcMethodNotFound } from './errors.js';
+function mapProbeError(e) {
+    if (isBoingRpcMethodNotFound(e)) {
+        const msg = e instanceof Error ? e.message : String(e);
+        return { available: false, code: -32601, message: msg };
+    }
+    if (e instanceof BoingRpcError) {
+        return { available: false, code: e.code, message: e.message };
+    }
+    return { available: false, message: e instanceof Error ? e.message : String(e) };
+}
+const ZERO_TX_HEX = `0x${'00'.repeat(32)}`;
+const CAP_KEYS = [
+    'boing_chainHeight',
+    'boing_getSyncState',
+    'boing_getBlockByHeight',
+    'boing_getLogs',
+    'boing_getTransactionReceipt',
+    'boing_getNetworkInfo',
+];
+function unwrapMethods(bundleOrMethods) {
+    return 'methods' in bundleOrMethods ? bundleOrMethods.methods : bundleOrMethods;
+}
+/**
+ * Call discovery plus a small set of read-only RPCs with minimal parameters.
+ * A method is **available** if it returns (including JSON-RPC `result: null` for unknown tx/block).
+ */
+export async function probeBoingRpcCapabilities(client) {
+    const methods = {};
+    let clientVersion = null;
+    let supportedMethods = null;
+    await Promise.all([
+        (async () => {
+            try {
+                clientVersion = await client.clientVersion();
+            }
+            catch (e) {
+                if (!isBoingRpcMethodNotFound(e))
+                    throw e;
+            }
+        })(),
+        (async () => {
+            try {
+                supportedMethods = await client.rpcSupportedMethods();
+            }
+            catch (e) {
+                if (!isBoingRpcMethodNotFound(e))
+                    throw e;
+            }
+        })(),
+        (async () => {
+            try {
+                await client.chainHeight();
+                methods.boing_chainHeight = { available: true };
+            }
+            catch (e) {
+                methods.boing_chainHeight = mapProbeError(e);
+            }
+        })(),
+        (async () => {
+            try {
+                await client.getSyncState();
+                methods.boing_getSyncState = { available: true };
+            }
+            catch (e) {
+                methods.boing_getSyncState = mapProbeError(e);
+            }
+        })(),
+        (async () => {
+            try {
+                await client.getBlockByHeight(0, false);
+                methods.boing_getBlockByHeight = { available: true };
+            }
+            catch (e) {
+                methods.boing_getBlockByHeight = mapProbeError(e);
+            }
+        })(),
+        (async () => {
+            try {
+                await client.getLogs({ fromBlock: 0, toBlock: 0 });
+                methods.boing_getLogs = { available: true };
+            }
+            catch (e) {
+                methods.boing_getLogs = mapProbeError(e);
+            }
+        })(),
+        (async () => {
+            try {
+                await client.getTransactionReceipt(ZERO_TX_HEX);
+                methods.boing_getTransactionReceipt = { available: true };
+            }
+            catch (e) {
+                methods.boing_getTransactionReceipt = mapProbeError(e);
+            }
+        })(),
+        (async () => {
+            try {
+                await client.getNetworkInfo();
+                methods.boing_getNetworkInfo = { available: true };
+            }
+            catch (e) {
+                methods.boing_getNetworkInfo = mapProbeError(e);
+            }
+        })(),
+    ]);
+    return { clientVersion, supportedMethods, methods };
+}
+/** Count of core probed methods with `available: true`. */
+export function countAvailableBoingRpcMethods(bundleOrMethods) {
+    const m = unwrapMethods(bundleOrMethods);
+    return CAP_KEYS.filter((k) => m[k].available).length;
+}
+/**
+ * Human-readable diagnosis when **`probeBoingRpcCapabilities`** shows gaps.
+ * **`undefined`** when all probed methods are available, or when there is nothing actionable to say.
+ */
+export function explainBoingRpcProbeGaps(bundleOrMethods) {
+    const methods = unwrapMethods(bundleOrMethods);
+    const supportedListing = 'supportedMethods' in bundleOrMethods ? bundleOrMethods.supportedMethods : undefined;
+    const reportedVersion = 'clientVersion' in bundleOrMethods ? bundleOrMethods.clientVersion : undefined;
+    if (!methods.boing_chainHeight.available) {
+        return ('boing_chainHeight failed — this URL may not be a Boing JSON-RPC server (POST /, JSON-RPC 2.0), or the node is unreachable.');
+    }
+    const methodNotFound = CAP_KEYS.filter((k) => !methods[k].available && methods[k].code === -32601);
+    if (methodNotFound.length > 0) {
+        let s = `The server returned -32601 (method not found) for: ${methodNotFound.join(', ')}. ` +
+            'The current **boing-node** in the boing.network repo registers these methods on the same HTTP POST / handler as boing_chainHeight. ' +
+            'Typical causes: (1) an **older boing-node binary** — rebuild with `cargo build -p boing-node --release` and restart (see docs/RUNBOOK.md); ' +
+            '(2) a **reverse proxy** that only forwards a subset of JSON-RPC method names. ' +
+            'Full list: docs/RPC-API-SPEC.md.';
+        if (supportedListing != null) {
+            const sm = new Set(supportedListing);
+            const ghost = methodNotFound.filter((k) => sm.has(k));
+            if (ghost.length > 0) {
+                s += ` Contradiction: boing_rpcSupportedMethods lists ${ghost.join(', ')} but calls failed — likely a filtering proxy.`;
+            }
+        }
+        if (reportedVersion != null && reportedVersion !== '') {
+            s += ` Reported client: ${reportedVersion}.`;
+        }
+        else if ('clientVersion' in bundleOrMethods &&
+            bundleOrMethods.clientVersion === null) {
+            s +=
+                ' **`boing_clientVersion` is also missing (-32601)** — this process does not match a current `boing-node` from this repository (that method is registered alongside `boing_chainHeight`). ';
+        }
+        s +=
+            ' Confirm what is listening: from the repo root run **`npm run rpc-endpoint-check`** (no SDK build). On Windows: **`netstat -ano | findstr :8545`** then **`tasklist /FI "PID eq <pid>" /V`**; start the node with **`cargo run -p boing-node -- --validator --rpc-port 8545`** or **`target/release/boing-node`** after **`cargo build -p boing-node --release`.**';
+        return s;
+    }
+    const otherFailed = CAP_KEYS.filter((k) => !methods[k].available && methods[k].code !== -32601);
+    if (otherFailed.length > 0) {
+        return `Some probed methods failed with errors other than -32601: ${otherFailed.join(', ')}. Inspect methods.*.message in this output.`;
+    }
+    return undefined;
+}

package/dist/rpcDoctor.d.ts

@@ -0,0 +1,27 @@
+/**
+ * One-shot environment check: preflight HTTP discovery + capability probes + optional required methods.
+ */
+import type { BoingClient } from './client.js';
+import type { BoingRpcPreflightResult } from './types.js';
+import { type BoingRpcProbeBundle } from './rpcCapabilities.js';
+export interface BoingRpcDoctorOptions {
+    /** If set, `ok` is false when any of these are missing from `boing_rpcSupportedMethods`. */
+    requiredMethods?: string[];
+}
+export interface BoingRpcDoctorResult {
+    ok: boolean;
+    preflight: BoingRpcPreflightResult;
+    capabilityProbe: BoingRpcProbeBundle;
+    missingRequiredMethods: string[];
+    messages: string[];
+}
+/**
+ * Run {@link BoingClient.preflightRpc}, {@link probeBoingRpcCapabilities}, and optional required-method checks.
+ * `messages` collects short strings suitable for logs or UI (includes `explainBoingRpcProbeGaps` when probes fail).
+ */
+export declare function doctorBoingRpcEnvironment(client: BoingClient, options?: BoingRpcDoctorOptions): Promise<BoingRpcDoctorResult>;
+/** Format {@link BoingRpcDoctorResult} as a multi-line string for stdout. */
+export declare function formatBoingRpcDoctorReport(result: BoingRpcDoctorResult): string;
+/** Map arbitrary errors to a short doctor message (uses {@link explainBoingRpcError} for `BoingRpcError`). */
+export declare function doctorErrorMessage(e: unknown): string;
+//# sourceMappingURL=rpcDoctor.d.ts.map

package/dist/rpcDoctor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rpcDoctor.d.ts","sourceRoot":"","sources":["../src/rpcDoctor.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE/C,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,YAAY,CAAC;AAC1D,OAAO,EAAuD,KAAK,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAErH,MAAM,WAAW,qBAAqB;IACpC,4FAA4F;IAC5F,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;CAC5B;AAED,MAAM,WAAW,oBAAoB;IACnC,EAAE,EAAE,OAAO,CAAC;IACZ,SAAS,EAAE,uBAAuB,CAAC;IACnC,eAAe,EAAE,mBAAmB,CAAC;IACrC,sBAAsB,EAAE,MAAM,EAAE,CAAC;IACjC,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED;;;GAGG;AACH,wBAAsB,yBAAyB,CAC7C,MAAM,EAAE,WAAW,EACnB,OAAO,CAAC,EAAE,qBAAqB,GAC9B,OAAO,CAAC,oBAAoB,CAAC,CAoC/B;AAED,6EAA6E;AAC7E,wBAAgB,0BAA0B,CAAC,MAAM,EAAE,oBAAoB,GAAG,MAAM,CAa/E;AAED,8GAA8G;AAC9G,wBAAgB,kBAAkB,CAAC,CAAC,EAAE,OAAO,GAAG,MAAM,CAErD"}