boing-sdk 0.3.0

package/dist/dexIntegration.js

@@ -0,0 +1,193 @@
+/**
+ * One-call defaults for native Boing DEX wiring: merge **`boing_getNetworkInfo.end_user`**
+ * hints with embedded testnet fallbacks and app overrides.
+ *
+ * See [BOING-DAPP-INTEGRATION.md](../../docs/BOING-DAPP-INTEGRATION.md) § **Seamless native DEX defaults**.
+ */
+import { CANONICAL_BOING_TESTNET_NATIVE_CP_POOL_HEX } from './canonicalTestnet.js';
+import { CANONICAL_BOING_TESTNET_NATIVE_AMM_LP_VAULT_HEX, CANONICAL_BOING_TESTNET_NATIVE_DEX_FACTORY_HEX, CANONICAL_BOING_TESTNET_NATIVE_DEX_LEDGER_ROUTER_V2_HEX, CANONICAL_BOING_TESTNET_NATIVE_DEX_LEDGER_ROUTER_V3_HEX, CANONICAL_BOING_TESTNET_NATIVE_DEX_MULTIHOP_SWAP_ROUTER_HEX, CANONICAL_BOING_TESTNET_NATIVE_LP_SHARE_TOKEN_HEX, } from './canonicalTestnetDex.js';
+import { isBoingTestnetChainId } from './chainIds.js';
+import { validateHex32 } from './hex.js';
+import { getLogsChunked } from './indexerBatch.js';
+import { NATIVE_DEX_FACTORY_TOPIC_REGISTER_HEX } from './nativeDexFactory.js';
+import { tryParseNativeDexFactoryRegisterRpcLogEntry, } from './nativeDexFactoryLogs.js';
+function parseOptionalHex32(v) {
+    if (v == null || typeof v !== 'string')
+        return null;
+    const t = v.trim();
+    if (!t)
+        return null;
+    try {
+        return validateHex32(t);
+    }
+    catch {
+        return null;
+    }
+}
+function mergeOptionalAccountHex(chainId, override, rpcField, embeddedWhenTestnet) {
+    const o = override;
+    if (o?.trim()) {
+        try {
+            return { hex: validateHex32(o), source: 'override' };
+        }
+        catch {
+            return { hex: null, source: 'none' };
+        }
+    }
+    const rpc = parseOptionalHex32(rpcField ?? null);
+    if (rpc)
+        return { hex: rpc, source: 'rpc_end_user' };
+    if (chainId != null && isBoingTestnetChainId(chainId) && embeddedWhenTestnet != null) {
+        return { hex: embeddedWhenTestnet, source: 'sdk_testnet_embedded' };
+    }
+    return { hex: null, source: 'none' };
+}
+function getProcessEnvRecord() {
+    if (typeof globalThis === 'undefined')
+        return undefined;
+    const proc = globalThis.process;
+    return proc?.env;
+}
+function readFirstProcessEnv(keys) {
+    const env = getProcessEnvRecord();
+    if (env == null)
+        return undefined;
+    for (const k of keys) {
+        const v = env[k];
+        if (v != null && String(v).trim())
+            return String(v).trim();
+    }
+    return undefined;
+}
+/**
+ * Build {@link NativeDexIntegrationOverrides} from **`process.env`** (Node / Vite / CRA).
+ * First non-empty value wins per key group. Safe to call from browser bundles if env is injected at build time.
+ */
+export function buildNativeDexIntegrationOverridesFromProcessEnv() {
+    const o = {};
+    const pool = readFirstProcessEnv([
+        'REACT_APP_BOING_NATIVE_AMM_POOL',
+        'VITE_BOING_NATIVE_AMM_POOL',
+        'BOING_NATIVE_AMM_POOL',
+    ]);
+    const fac = readFirstProcessEnv([
+        'REACT_APP_BOING_NATIVE_VM_DEX_FACTORY',
+        'VITE_BOING_NATIVE_VM_DEX_FACTORY',
+        'BOING_NATIVE_VM_DEX_FACTORY',
+        'BOING_DEX_FACTORY_HEX',
+    ]);
+    const hop = readFirstProcessEnv([
+        'REACT_APP_BOING_NATIVE_VM_SWAP_ROUTER',
+        'VITE_BOING_NATIVE_VM_SWAP_ROUTER',
+        'BOING_NATIVE_VM_SWAP_ROUTER',
+        'BOING_NATIVE_DEX_MULTIHOP_SWAP_ROUTER',
+    ]);
+    const l2 = readFirstProcessEnv([
+        'REACT_APP_BOING_NATIVE_DEX_LEDGER_ROUTER_V2',
+        'VITE_BOING_NATIVE_DEX_LEDGER_ROUTER_V2',
+        'BOING_NATIVE_DEX_LEDGER_ROUTER_V2',
+    ]);
+    const l3 = readFirstProcessEnv([
+        'REACT_APP_BOING_NATIVE_DEX_LEDGER_ROUTER_V3',
+        'VITE_BOING_NATIVE_DEX_LEDGER_ROUTER_V3',
+        'BOING_NATIVE_DEX_LEDGER_ROUTER_V3',
+    ]);
+    const vault = readFirstProcessEnv([
+        'REACT_APP_BOING_NATIVE_AMM_LP_VAULT',
+        'VITE_BOING_NATIVE_AMM_LP_VAULT',
+        'BOING_NATIVE_AMM_LP_VAULT',
+    ]);
+    const share = readFirstProcessEnv([
+        'REACT_APP_BOING_NATIVE_AMM_LP_SHARE_TOKEN',
+        'VITE_BOING_NATIVE_AMM_LP_SHARE_TOKEN',
+        'BOING_NATIVE_AMM_LP_SHARE_TOKEN',
+    ]);
+    if (pool)
+        o.nativeCpPoolAccountHex = pool;
+    if (fac)
+        o.nativeDexFactoryAccountHex = fac;
+    if (hop)
+        o.nativeDexMultihopSwapRouterAccountHex = hop;
+    if (l2)
+        o.nativeDexLedgerRouterV2AccountHex = l2;
+    if (l3)
+        o.nativeDexLedgerRouterV3AccountHex = l3;
+    if (vault)
+        o.nativeAmmLpVaultAccountHex = vault;
+    if (share)
+        o.nativeLpShareTokenAccountHex = share;
+    return o;
+}
+/**
+ * Merge RPC **`end_user`** canonical addresses, optional app overrides, and embedded **6913** fallbacks
+ * (see [`canonicalTestnetDex.ts`](./canonicalTestnetDex.ts)).
+ * Order per field: overrides → node hints → testnet embedded constants.
+ */
+export function mergeNativeDexIntegrationDefaults(info, overrides) {
+    const chainId = info?.chain_id ?? null;
+    const eu = info?.end_user;
+    const poolEmb = CANONICAL_BOING_TESTNET_NATIVE_CP_POOL_HEX;
+    const facEmb = CANONICAL_BOING_TESTNET_NATIVE_DEX_FACTORY_HEX;
+    const hopEmb = CANONICAL_BOING_TESTNET_NATIVE_DEX_MULTIHOP_SWAP_ROUTER_HEX;
+    const l2Emb = CANONICAL_BOING_TESTNET_NATIVE_DEX_LEDGER_ROUTER_V2_HEX;
+    const l3Emb = CANONICAL_BOING_TESTNET_NATIVE_DEX_LEDGER_ROUTER_V3_HEX;
+    const vaultEmb = CANONICAL_BOING_TESTNET_NATIVE_AMM_LP_VAULT_HEX;
+    const shareEmb = CANONICAL_BOING_TESTNET_NATIVE_LP_SHARE_TOKEN_HEX;
+    const pool = mergeOptionalAccountHex(chainId, overrides?.nativeCpPoolAccountHex, eu?.canonical_native_cp_pool ?? null, poolEmb);
+    const factory = mergeOptionalAccountHex(chainId, overrides?.nativeDexFactoryAccountHex, eu?.canonical_native_dex_factory ?? null, facEmb);
+    const multihop = mergeOptionalAccountHex(chainId, overrides?.nativeDexMultihopSwapRouterAccountHex, eu?.canonical_native_dex_multihop_swap_router ?? null, hopEmb);
+    const ledgerV2 = mergeOptionalAccountHex(chainId, overrides?.nativeDexLedgerRouterV2AccountHex, eu?.canonical_native_dex_ledger_router_v2 ?? null, l2Emb);
+    const ledgerV3 = mergeOptionalAccountHex(chainId, overrides?.nativeDexLedgerRouterV3AccountHex, eu?.canonical_native_dex_ledger_router_v3 ?? null, l3Emb);
+    const vault = mergeOptionalAccountHex(chainId, overrides?.nativeAmmLpVaultAccountHex, eu?.canonical_native_amm_lp_vault ?? null, vaultEmb);
+    const share = mergeOptionalAccountHex(chainId, overrides?.nativeLpShareTokenAccountHex, eu?.canonical_native_lp_share_token ?? null, shareEmb);
+    let endUserExplorerUrl = null;
+    const ex = eu?.explorer_url;
+    if (typeof ex === 'string') {
+        const t = ex.trim();
+        if (t && /^https?:\/\//i.test(t)) {
+            endUserExplorerUrl = t.replace(/\/+$/, '');
+        }
+    }
+    return {
+        nativeCpPoolAccountHex: pool.hex,
+        nativeDexFactoryAccountHex: factory.hex,
+        poolSource: pool.source,
+        factorySource: factory.source,
+        nativeDexMultihopSwapRouterAccountHex: multihop.hex,
+        nativeDexMultihopSwapRouterSource: multihop.source,
+        nativeDexLedgerRouterV2AccountHex: ledgerV2.hex,
+        nativeDexLedgerRouterV2Source: ledgerV2.source,
+        nativeDexLedgerRouterV3AccountHex: ledgerV3.hex,
+        nativeDexLedgerRouterV3Source: ledgerV3.source,
+        nativeAmmLpVaultAccountHex: vault.hex,
+        nativeAmmLpVaultSource: vault.source,
+        nativeLpShareTokenAccountHex: share.hex,
+        nativeLpShareTokenSource: share.source,
+        endUserExplorerUrl,
+    };
+}
+/** Fetch **`boing_getNetworkInfo`** and {@link mergeNativeDexIntegrationDefaults}. */
+export async function fetchNativeDexIntegrationDefaults(client, overrides) {
+    const info = await client.getNetworkInfo();
+    return mergeNativeDexIntegrationDefaults(info, overrides);
+}
+/**
+ * Stream **`register_pair`** **`Log3`** rows for a factory (chunked **`boing_getLogs`**).
+ * Requires a known factory **`AccountId`** (from {@link NativeDexIntegrationDefaults} or CREATE2 prediction).
+ */
+export async function fetchNativeDexFactoryRegisterLogs(client, opts) {
+    const factoryAccountHex = validateHex32(opts.factoryAccountHex);
+    const raw = await getLogsChunked(client, {
+        fromBlock: opts.fromBlock,
+        toBlock: opts.toBlock,
+        address: factoryAccountHex,
+        topics: [NATIVE_DEX_FACTORY_TOPIC_REGISTER_HEX, null, null],
+    }, {});
+    const out = [];
+    for (const row of raw) {
+        const p = tryParseNativeDexFactoryRegisterRpcLogEntry(row);
+        if (p)
+            out.push(p);
+    }
+    return out;
+}

package/dist/erc721Logs.d.ts

@@ -0,0 +1,21 @@
+/**
+ * ERC-721 **`Transfer(address,address,uint256)`** log parsing for indexer-style **`boing_getLogs`** rows.
+ * Topic0 matches Ethereum’s canonical event signature (same as widely used EVM tooling).
+ */
+import type { RpcLogEntry } from './types.js';
+/** `keccak256("Transfer(address,address,uint256)")` topic0 (lowercase `0x` + 64 hex). */
+export declare const ERC721_TRANSFER_TOPIC0_HEX: "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef";
+export type Erc721TransferParsed = {
+    fromHex: `0x${string}`;
+    toHex: `0x${string}`;
+    tokenId: bigint;
+    blockHeight: number;
+    txId: string;
+    logIndex: number;
+};
+/**
+ * Parse one **`Transfer`** log (`4` topics: signature + indexed from + to + tokenId).
+ */
+export declare function tryParseErc721TransferRpcLog(entry: RpcLogEntry): Erc721TransferParsed | null;
+export declare function filterMapErc721TransferRpcLogs(entries: readonly RpcLogEntry[]): Erc721TransferParsed[];
+//# sourceMappingURL=erc721Logs.d.ts.map

package/dist/erc721Logs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"erc721Logs.d.ts","sourceRoot":"","sources":["../src/erc721Logs.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE9C,yFAAyF;AACzF,eAAO,MAAM,0BAA0B,EACrC,oEAA6E,CAAC;AAwBhF,MAAM,MAAM,oBAAoB,GAAG;IACjC,OAAO,EAAE,KAAK,MAAM,EAAE,CAAC;IACvB,KAAK,EAAE,KAAK,MAAM,EAAE,CAAC;IACrB,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;CAClB,CAAC;AAEF;;GAEG;AACH,wBAAgB,4BAA4B,CAAC,KAAK,EAAE,WAAW,GAAG,oBAAoB,GAAG,IAAI,CAoB5F;AAED,wBAAgB,8BAA8B,CAAC,OAAO,EAAE,SAAS,WAAW,EAAE,GAAG,oBAAoB,EAAE,CAOtG"}

package/dist/erc721Logs.js

@@ -0,0 +1,69 @@
+/**
+ * ERC-721 **`Transfer(address,address,uint256)`** log parsing for indexer-style **`boing_getLogs`** rows.
+ * Topic0 matches Ethereum’s canonical event signature (same as widely used EVM tooling).
+ */
+import { normalizeTopicWord } from './receiptLogs.js';
+/** `keccak256("Transfer(address,address,uint256)")` topic0 (lowercase `0x` + 64 hex). */
+export const ERC721_TRANSFER_TOPIC0_HEX = '0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef';
+function topicAddressToAccountHex32(topic) {
+    try {
+        const t = normalizeTopicWord(topic);
+        if (t.length !== 66)
+            return null;
+        const addr20 = t.slice(-40).toLowerCase();
+        if (!/^[0-9a-f]{40}$/.test(addr20))
+            return null;
+        return (`0x${'00'.repeat(12)}${addr20}`);
+    }
+    catch {
+        return null;
+    }
+}
+function topicUint256ToBigInt(topic) {
+    try {
+        const t = normalizeTopicWord(topic);
+        if (t.length !== 66)
+            return null;
+        return BigInt(t);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Parse one **`Transfer`** log (`4` topics: signature + indexed from + to + tokenId).
+ */
+export function tryParseErc721TransferRpcLog(entry) {
+    try {
+        const t0 = normalizeTopicWord(entry.topics[0] ?? '');
+        if (t0 !== ERC721_TRANSFER_TOPIC0_HEX)
+            return null;
+        if (entry.topics.length !== 4)
+            return null;
+        const from32 = topicAddressToAccountHex32(entry.topics[1]);
+        const to32 = topicAddressToAccountHex32(entry.topics[2]);
+        const tid = topicUint256ToBigInt(entry.topics[3]);
+        if (from32 == null || to32 == null || tid == null)
+            return null;
+        return {
+            fromHex: from32.toLowerCase(),
+            toHex: to32.toLowerCase(),
+            tokenId: tid,
+            blockHeight: entry.block_height,
+            txId: entry.tx_id,
+            logIndex: entry.log_index,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+export function filterMapErc721TransferRpcLogs(entries) {
+    const out = [];
+    for (const e of entries) {
+        const p = tryParseErc721TransferRpcLog(e);
+        if (p)
+            out.push(p);
+    }
+    return out;
+}

package/dist/errors.d.ts

@@ -0,0 +1,60 @@
+/**
+ * RPC error with optional structured data (e.g. QA rejection rule_id and message).
+ * When thrown from BoingClient, `method` is set to the RPC method that failed.
+ */
+export declare class BoingRpcError extends Error {
+    readonly code: number;
+    readonly data?: unknown | undefined;
+    /** RPC method that failed (e.g. "boing_getBalance"). */
+    readonly method?: string | undefined;
+    /**
+     * From HTTP **`Retry-After`** when the server returned a retriable status (e.g. 429).
+     * Used by `BoingClient` to wait at least this long before the next retry.
+     */
+    readonly retryAfterMs?: number | undefined;
+    constructor(code: number, message: string, data?: unknown | undefined, 
+    /** RPC method that failed (e.g. "boing_getBalance"). */
+    method?: string | undefined, 
+    /**
+     * From HTTP **`Retry-After`** when the server returned a retriable status (e.g. 429).
+     * Used by `BoingClient` to wait at least this long before the next retry.
+     */
+    retryAfterMs?: number | undefined);
+    /** Short string for logging: "BoingRpcError(code, method): message". */
+    toString(): string;
+    /** True if this is a QA deployment rejection (-32050). */
+    get isQaRejected(): boolean;
+    /** True if deployment was referred to governance QA pool (-32051). */
+    get isQaPendingPool(): boolean;
+    /** True if QA pool is disabled by governance (-32054). */
+    get isQaPoolDisabled(): boolean;
+    /** True if QA pool hit global max pending (-32055). */
+    get isQaPoolFull(): boolean;
+    /** True if deployer exceeded per-address pool cap (-32056). */
+    get isQaPoolDeployerCap(): boolean;
+    /** True if the node rejected the call due to HTTP JSON-RPC rate limiting (-32016). */
+    get isRateLimited(): boolean;
+    /** For -32051, `data.tx_hash` when present. */
+    get pendingPoolTxHash(): string | undefined;
+    /** QA rejection details when code is -32050. */
+    get qaData(): {
+        rule_id: string;
+        message: string;
+    } | undefined;
+}
+/**
+ * JSON-RPC 2.0 **method not found** (-32601). Common when the endpoint is an older Boing node or a
+ * proxy that does not implement a newer `boing_*` method (e.g. `boing_getSyncState`, `boing_getLogs`).
+ */
+export declare function isBoingRpcMethodNotFound(e: unknown): boolean;
+/**
+ * Whether a failed call is worth retrying (transient HTTP, rate limits, network).
+ * Application errors (e.g. invalid nonce, QA rejection) return false.
+ */
+export declare function isRetriableBoingRpcError(e: unknown): boolean;
+/**
+ * User-facing explanation for logging and UI (maps Boing JSON-RPC codes to short text).
+ * See `docs/BOING-RPC-ERROR-CODES-FOR-DAPPS.md` in the boing-network repo.
+ */
+export declare function explainBoingRpcError(e: unknown): string;
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,qBAAa,aAAc,SAAQ,KAAK;aAEpB,IAAI,EAAE,MAAM;aAEZ,IAAI,CAAC,EAAE,OAAO;IAC9B,wDAAwD;aACxC,MAAM,CAAC,EAAE,MAAM;IAC/B;;;OAGG;aACa,YAAY,CAAC,EAAE,MAAM;gBATrB,IAAI,EAAE,MAAM,EAC5B,OAAO,EAAE,MAAM,EACC,IAAI,CAAC,EAAE,OAAO,YAAA;IAC9B,wDAAwD;IACxC,MAAM,CAAC,EAAE,MAAM,YAAA;IAC/B;;;OAGG;IACa,YAAY,CAAC,EAAE,MAAM,YAAA;IAOvC,wEAAwE;IAC/D,QAAQ,IAAI,MAAM;IAK3B,0DAA0D;IAC1D,IAAI,YAAY,IAAI,OAAO,CAE1B;IAED,sEAAsE;IACtE,IAAI,eAAe,IAAI,OAAO,CAE7B;IAED,0DAA0D;IAC1D,IAAI,gBAAgB,IAAI,OAAO,CAE9B;IAED,uDAAuD;IACvD,IAAI,YAAY,IAAI,OAAO,CAE1B;IAED,+DAA+D;IAC/D,IAAI,mBAAmB,IAAI,OAAO,CAEjC;IAED,sFAAsF;IACtF,IAAI,aAAa,IAAI,OAAO,CAE3B;IAED,+CAA+C;IAC/C,IAAI,iBAAiB,IAAI,MAAM,GAAG,SAAS,CAI1C;IAED,gDAAgD;IAChD,IAAI,MAAM,IAAI;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,GAAG,SAAS,CAO7D;CACF;AAED;;;GAGG;AACH,wBAAgB,wBAAwB,CAAC,CAAC,EAAE,OAAO,GAAG,OAAO,CAE5D;AAED;;;GAGG;AACH,wBAAgB,wBAAwB,CAAC,CAAC,EAAE,OAAO,GAAG,OAAO,CAc5D;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,CAAC,EAAE,OAAO,GAAG,MAAM,CAwCvD"}

package/dist/errors.js

@@ -0,0 +1,153 @@
+/**
+ * RPC error with optional structured data (e.g. QA rejection rule_id and message).
+ * When thrown from BoingClient, `method` is set to the RPC method that failed.
+ */
+export class BoingRpcError extends Error {
+    constructor(code, message, data, 
+    /** RPC method that failed (e.g. "boing_getBalance"). */
+    method, 
+    /**
+     * From HTTP **`Retry-After`** when the server returned a retriable status (e.g. 429).
+     * Used by `BoingClient` to wait at least this long before the next retry.
+     */
+    retryAfterMs) {
+        super(message);
+        this.code = code;
+        this.data = data;
+        this.method = method;
+        this.retryAfterMs = retryAfterMs;
+        this.name = 'BoingRpcError';
+        Object.setPrototypeOf(this, BoingRpcError.prototype);
+    }
+    /** Short string for logging: "BoingRpcError(code, method): message". */
+    toString() {
+        const method = this.method ? ` ${this.method}` : '';
+        return `BoingRpcError(${this.code}${method}): ${this.message}`;
+    }
+    /** True if this is a QA deployment rejection (-32050). */
+    get isQaRejected() {
+        return this.code === -32050;
+    }
+    /** True if deployment was referred to governance QA pool (-32051). */
+    get isQaPendingPool() {
+        return this.code === -32051;
+    }
+    /** True if QA pool is disabled by governance (-32054). */
+    get isQaPoolDisabled() {
+        return this.code === -32054;
+    }
+    /** True if QA pool hit global max pending (-32055). */
+    get isQaPoolFull() {
+        return this.code === -32055;
+    }
+    /** True if deployer exceeded per-address pool cap (-32056). */
+    get isQaPoolDeployerCap() {
+        return this.code === -32056;
+    }
+    /** True if the node rejected the call due to HTTP JSON-RPC rate limiting (-32016). */
+    get isRateLimited() {
+        return this.code === -32016;
+    }
+    /** For -32051, `data.tx_hash` when present. */
+    get pendingPoolTxHash() {
+        if (this.code !== -32051 || !this.data || typeof this.data !== 'object')
+            return undefined;
+        const d = this.data;
+        return typeof d.tx_hash === 'string' ? d.tx_hash : undefined;
+    }
+    /** QA rejection details when code is -32050. */
+    get qaData() {
+        if (this.code !== -32050 || !this.data || typeof this.data !== 'object')
+            return undefined;
+        const d = this.data;
+        if (typeof d.rule_id === 'string' && typeof d.message === 'string') {
+            return { rule_id: d.rule_id, message: d.message };
+        }
+        return undefined;
+    }
+}
+/**
+ * JSON-RPC 2.0 **method not found** (-32601). Common when the endpoint is an older Boing node or a
+ * proxy that does not implement a newer `boing_*` method (e.g. `boing_getSyncState`, `boing_getLogs`).
+ */
+export function isBoingRpcMethodNotFound(e) {
+    return e instanceof BoingRpcError && e.code === -32601;
+}
+/**
+ * Whether a failed call is worth retrying (transient HTTP, rate limits, network).
+ * Application errors (e.g. invalid nonce, QA rejection) return false.
+ */
+export function isRetriableBoingRpcError(e) {
+    if (!(e instanceof BoingRpcError))
+        return true;
+    if (e.isRateLimited)
+        return true;
+    if (e.code === -32000) {
+        const m = e.message;
+        if (/\bHTTP 429\b/.test(m))
+            return true;
+        if (/\bHTTP 502\b/.test(m))
+            return true;
+        if (/\bHTTP 503\b/.test(m))
+            return true;
+        if (/\bHTTP 504\b/.test(m))
+            return true;
+        if (/Request timed out after \d+ms/.test(m))
+            return true;
+        if (/ECONNRESET|ETIMEDOUT|ENOTFOUND|EAI_AGAIN/i.test(m))
+            return true;
+        if (/fetch failed|Failed to fetch|Load failed|network/i.test(m))
+            return true;
+    }
+    return false;
+}
+/**
+ * User-facing explanation for logging and UI (maps Boing JSON-RPC codes to short text).
+ * See `docs/BOING-RPC-ERROR-CODES-FOR-DAPPS.md` in the boing-network repo.
+ */
+export function explainBoingRpcError(e) {
+    if (e instanceof BoingRpcError) {
+        if (e.isQaRejected) {
+            const q = e.qaData;
+            return q ? `QA rejected (${q.rule_id}): ${q.message}` : `QA rejected: ${e.message}`;
+        }
+        if (e.isQaPendingPool) {
+            const h = e.pendingPoolTxHash;
+            return h
+                ? `Deployment queued for QA pool (tx_hash ${h}). Vote via boing_qaPoolVote.`
+                : `Deployment queued for QA pool: ${e.message}`;
+        }
+        if (e.isQaPoolDisabled)
+            return `QA pool is disabled by governance: ${e.message}`;
+        if (e.isQaPoolFull)
+            return `QA pool is full (global cap): ${e.message}`;
+        if (e.isQaPoolDeployerCap)
+            return `QA pool deployer cap reached: ${e.message}`;
+        if (e.code === -32057)
+            return `Operator RPC authentication required: ${e.message}`;
+        if (e.isRateLimited) {
+            const hint = e.retryAfterMs != null && e.retryAfterMs > 0
+                ? ` Wait at least ${Math.ceil(e.retryAfterMs / 1000)}s (Retry-After header).`
+                : '';
+            return `Rate limited: ${e.message}.${hint}`;
+        }
+        if (e.code === -32000 && e.message.includes('413')) {
+            return `Request body too large for this RPC endpoint: ${e.message}`;
+        }
+        if (e.code === -32700)
+            return `Invalid JSON in RPC body (parse error): ${e.message}`;
+        if (e.code === -32600)
+            return `Invalid JSON-RPC request (e.g. batch too large or malformed): ${e.message}`;
+        if (e.code === -32601)
+            return `RPC method not implemented on this endpoint (old node or filtered proxy): ${e.message}`;
+        if (e.code === -32602)
+            return `Invalid RPC params: ${e.message}`;
+        if (e.code === -32000 && e.retryAfterMs != null && e.retryAfterMs > 0) {
+            return `Transient RPC error (wait ~${Math.ceil(e.retryAfterMs / 1000)}s per Retry-After): ${e.message}`;
+        }
+        return e.toString();
+    }
+    if (e instanceof Error)
+        return e.message;
+    return String(e);
+}

package/dist/hex.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Hex encoding/decoding for 32-byte IDs, hashes, and RPC params.
+ */
+/** Ensure string has 0x prefix. */
+export declare function ensureHex(s: string): string;
+/** Encode bytes to hex with 0x prefix. */
+export declare function bytesToHex(bytes: Uint8Array): string;
+/** Decode hex string to bytes (with or without 0x). */
+export declare function hexToBytes(hex: string): Uint8Array;
+/**
+ * Normalize hex and require exactly 32 bytes (64 hex chars). Use for account IDs and hashes.
+ * @returns Hex string with 0x prefix
+ * @throws if not valid hex or length is not 64
+ */
+export declare function validateHex32(hex: string): string;
+/**
+ * Decode a **32-byte** `boing_getContractStorage` **value** word as a Boing **`AccountId`**, or **`null`**
+ * if the word is all zero. Truncates/pads to 64 hex chars like other storage decoders.
+ */
+export declare function decodeBoingStorageWordAccountId(valueHex: string): `0x${string}` | null;
+/** True if **`hex`** is a valid **32-byte** Boing **`AccountId`** (`0x` + 64 hex). Use to branch wizards away from 20-byte EVM addresses. */
+export declare function isBoingNativeAccountIdHex(hex: string): boolean;
+/** Assert 32-byte buffer; return as hex. */
+export declare function accountIdToHex(bytes: Uint8Array): string;
+/** Parse 32-byte AccountId from hex. */
+export declare function hexToAccountId(hex: string): Uint8Array;
+//# sourceMappingURL=hex.d.ts.map

package/dist/hex.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hex.d.ts","sourceRoot":"","sources":["../src/hex.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,mCAAmC;AACnC,wBAAgB,SAAS,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAG3C;AAED,0CAA0C;AAC1C,wBAAgB,UAAU,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,CAIpD;AAID,uDAAuD;AACvD,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU,CASlD;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAMjD;AAED;;;GAGG;AACH,wBAAgB,+BAA+B,CAAC,QAAQ,EAAE,MAAM,GAAG,KAAK,MAAM,EAAE,GAAG,IAAI,CAWtF;AAED,6IAA6I;AAC7I,wBAAgB,yBAAyB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAO9D;AAED,4CAA4C;AAC5C,wBAAgB,cAAc,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,CAGxD;AAED,wCAAwC;AACxC,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU,CAItD"}

package/dist/hex.js

@@ -0,0 +1,82 @@
+/**
+ * Hex encoding/decoding for 32-byte IDs, hashes, and RPC params.
+ */
+/** Ensure string has 0x prefix. */
+export function ensureHex(s) {
+    const t = s.trim();
+    return t.startsWith('0x') ? t : '0x' + t;
+}
+/** Encode bytes to hex with 0x prefix. */
+export function bytesToHex(bytes) {
+    return '0x' + Array.from(bytes)
+        .map((b) => b.toString(16).padStart(2, '0'))
+        .join('');
+}
+const HEX_RE = /^[0-9a-fA-F]+$/;
+/** Decode hex string to bytes (with or without 0x). */
+export function hexToBytes(hex) {
+    const raw = hex.trimStart().replace(/^0x/i, '');
+    if (raw.length % 2 !== 0)
+        throw new Error('Invalid hex: length must be even');
+    if (!HEX_RE.test(raw))
+        throw new Error('Invalid hex: expected 0-9, a-f, A-F');
+    const bytes = new Uint8Array(raw.length / 2);
+    for (let i = 0; i < bytes.length; i++) {
+        bytes[i] = parseInt(raw.slice(i * 2, i * 2 + 2), 16);
+    }
+    return bytes;
+}
+/**
+ * Normalize hex and require exactly 32 bytes (64 hex chars). Use for account IDs and hashes.
+ * @returns Hex string with 0x prefix
+ * @throws if not valid hex or length is not 64
+ */
+export function validateHex32(hex) {
+    const normalized = ensureHex(hex);
+    const raw = normalized.slice(2);
+    if (raw.length !== 64)
+        throw new Error(`Expected 32 bytes (64 hex chars), got ${raw.length} hex chars`);
+    if (!HEX_RE.test(raw))
+        throw new Error('Invalid hex: expected 0-9, a-f, A-F');
+    return normalized;
+}
+/**
+ * Decode a **32-byte** `boing_getContractStorage` **value** word as a Boing **`AccountId`**, or **`null`**
+ * if the word is all zero. Truncates/pads to 64 hex chars like other storage decoders.
+ */
+export function decodeBoingStorageWordAccountId(valueHex) {
+    const raw = ensureHex(valueHex).slice(2).toLowerCase();
+    if (raw.length % 2 !== 0) {
+        throw new Error('storage word AccountId: hex length must be even');
+    }
+    if (!HEX_RE.test(raw)) {
+        throw new Error('storage word AccountId: invalid hex');
+    }
+    const word64 = raw.length > 64 ? raw.slice(-64) : raw.padStart(64, '0');
+    if (word64 === '0'.repeat(64))
+        return null;
+    return validateHex32(`0x${word64}`);
+}
+/** True if **`hex`** is a valid **32-byte** Boing **`AccountId`** (`0x` + 64 hex). Use to branch wizards away from 20-byte EVM addresses. */
+export function isBoingNativeAccountIdHex(hex) {
+    try {
+        validateHex32(hex);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Assert 32-byte buffer; return as hex. */
+export function accountIdToHex(bytes) {
+    if (bytes.length !== 32)
+        throw new Error('AccountId must be 32 bytes');
+    return bytesToHex(bytes);
+}
+/** Parse 32-byte AccountId from hex. */
+export function hexToAccountId(hex) {
+    const bytes = hexToBytes(hex);
+    if (bytes.length !== 32)
+        throw new Error('AccountId must be 32 bytes hex');
+    return bytes;
+}