boing-sdk 0.3.0

package/dist/canonicalDeployArtifacts.js

@@ -0,0 +1,271 @@
+/**
+ * Versioning + tx-object helpers for **pinned** native Boing deploys (form-parity with EVM apps).
+ *
+ * See `docs/BOING-CANONICAL-DEPLOY-ARTIFACTS.md`. **Fungible** and **NFT collection** templates ship a
+ * pinned default in this package (`DEFAULT_REFERENCE_*`); env vars still override when set.
+ */
+import { DEFAULT_REFERENCE_FUNGIBLE_TEMPLATE_BYTECODE_HEX } from './defaultReferenceFungibleTemplateBytecodeHex.js';
+import { DEFAULT_REFERENCE_FUNGIBLE_SECURED_TEMPLATE_BYTECODE_HEX } from './defaultReferenceFungibleSecuredTemplateBytecodeHex.js';
+import { DEFAULT_REFERENCE_NFT_COLLECTION_TEMPLATE_BYTECODE_HEX } from './defaultReferenceNftCollectionTemplateBytecodeHex.js';
+import { descriptionHashHexFromNativeTokenSecurity, } from './nativeTokenSecurity.js';
+import { buildReferenceFungibleSecuredDeployBytecodeHexFromNativeTokenSecurity } from './referenceFungibleSecuredDeployBytecode.js';
+/** Logical id for the fungible template line item (docs + telemetry). */
+export const REFERENCE_FUNGIBLE_TEMPLATE_ARTIFACT_ID = 'boing.reference_fungible.v0';
+/** Bump when default pinned hex in this package changes. */
+export const REFERENCE_FUNGIBLE_TEMPLATE_VERSION = '1';
+/** Logical id for the secured fungible template (`0xFD` init + runtime toggles). */
+export const REFERENCE_FUNGIBLE_SECURED_TEMPLATE_ARTIFACT_ID = 'boing.reference_fungible_secured.v0';
+/** Bump when default pinned secured hex in this package changes. */
+export const REFERENCE_FUNGIBLE_SECURED_TEMPLATE_VERSION = '1';
+/** Logical id for the NFT collection template. */
+export const REFERENCE_NFT_COLLECTION_TEMPLATE_ARTIFACT_ID = 'boing.reference_nft_collection.v0';
+/** Matches `reference_nft_collection_template_bytecode()` in `boing-execution` (regenerate via `dump_reference_token_artifacts`). */
+export const REFERENCE_NFT_COLLECTION_TEMPLATE_VERSION = '1';
+const DEFAULT_NFT_COLLECTION_ENV_KEYS = [
+    'BOING_REFERENCE_NFT_COLLECTION_TEMPLATE_BYTECODE_HEX',
+    'VITE_BOING_REFERENCE_NFT_COLLECTION_TEMPLATE_BYTECODE_HEX',
+    'REACT_APP_BOING_REFERENCE_NFT_COLLECTION_TEMPLATE_BYTECODE_HEX',
+];
+const DEFAULT_FUNGIBLE_ENV_KEYS = [
+    'BOING_REFERENCE_FUNGIBLE_TEMPLATE_BYTECODE_HEX',
+    'VITE_BOING_REFERENCE_FUNGIBLE_TEMPLATE_BYTECODE_HEX',
+    'REACT_APP_BOING_REFERENCE_FUNGIBLE_TEMPLATE_BYTECODE_HEX',
+];
+const DEFAULT_FUNGIBLE_SECURED_ENV_KEYS = [
+    'BOING_REFERENCE_FUNGIBLE_SECURED_TEMPLATE_BYTECODE_HEX',
+    'VITE_BOING_REFERENCE_FUNGIBLE_SECURED_TEMPLATE_BYTECODE_HEX',
+    'REACT_APP_BOING_REFERENCE_FUNGIBLE_SECURED_TEMPLATE_BYTECODE_HEX',
+];
+function readProcessEnv(name) {
+    try {
+        const proc = globalThis.process;
+        if (proc?.env && typeof proc.env[name] === 'string') {
+            const v = proc.env[name]?.trim();
+            return v || undefined;
+        }
+    }
+    catch {
+        /* ignore */
+    }
+    return undefined;
+}
+/**
+ * Normalize hex for wallet RPC payloads (`0x` prefix). Use for deploy bytecode or `description_hash`.
+ */
+export function ensure0xHex(hex) {
+    const t = hex.trim();
+    if (!t) {
+        throw new Error('ensure0xHex: empty hex');
+    }
+    const prefixed = t.startsWith('0x') || t.startsWith('0X') ? t : `0x${t}`;
+    return prefixed;
+}
+/**
+ * Resolve pinned fungible template bytecode: explicit override → known env keys → embedded default
+ * (`DEFAULT_REFERENCE_FUNGIBLE_TEMPLATE_BYTECODE_HEX`).
+ */
+export function resolveReferenceFungibleTemplateBytecodeHex(opts) {
+    if (opts?.explicitHex?.trim()) {
+        return ensure0xHex(opts.explicitHex);
+    }
+    for (const k of DEFAULT_FUNGIBLE_ENV_KEYS) {
+        const v = readProcessEnv(k);
+        if (v)
+            return ensure0xHex(v);
+    }
+    if (opts?.extraEnvKeys) {
+        for (const k of opts.extraEnvKeys) {
+            const v = readProcessEnv(k);
+            if (v)
+                return ensure0xHex(v);
+        }
+    }
+    return ensure0xHex(DEFAULT_REFERENCE_FUNGIBLE_TEMPLATE_BYTECODE_HEX);
+}
+/**
+ * Resolve pinned **secured** fungible deploy bytecode (`0xFD` init + runtime): explicit → env → embedded default.
+ */
+export function resolveReferenceFungibleSecuredTemplateBytecodeHex(opts) {
+    if (opts?.explicitHex?.trim()) {
+        return ensure0xHex(opts.explicitHex);
+    }
+    for (const k of DEFAULT_FUNGIBLE_SECURED_ENV_KEYS) {
+        const v = readProcessEnv(k);
+        if (v)
+            return ensure0xHex(v);
+    }
+    if (opts?.extraEnvKeys) {
+        for (const k of opts.extraEnvKeys) {
+            const v = readProcessEnv(k);
+            if (v)
+                return ensure0xHex(v);
+        }
+    }
+    return ensure0xHex(DEFAULT_REFERENCE_FUNGIBLE_SECURED_TEMPLATE_BYTECODE_HEX);
+}
+/**
+ * Resolve pinned **reference NFT collection** template bytecode (explicit → env → embedded default,
+ * same pattern as {@link resolveReferenceFungibleTemplateBytecodeHex}).
+ */
+export function resolveReferenceNftCollectionTemplateBytecodeHex(opts) {
+    if (opts?.explicitHex?.trim()) {
+        return ensure0xHex(opts.explicitHex);
+    }
+    for (const k of DEFAULT_NFT_COLLECTION_ENV_KEYS) {
+        const v = readProcessEnv(k);
+        if (v)
+            return ensure0xHex(v);
+    }
+    if (opts?.extraEnvKeys) {
+        for (const k of opts.extraEnvKeys) {
+            const v = readProcessEnv(k);
+            if (v)
+                return ensure0xHex(v);
+        }
+    }
+    return ensure0xHex(DEFAULT_REFERENCE_NFT_COLLECTION_TEMPLATE_BYTECODE_HEX);
+}
+/**
+ * Build a **`contract_deploy_meta`** object for `boing_sendTransaction` / `boing_signTransaction`.
+ */
+export function buildContractDeployMetaTx(input) {
+    const name = input.assetName.trim();
+    const sym = input.assetSymbol.trim().toUpperCase();
+    if (!name) {
+        throw new Error('buildContractDeployMetaTx: assetName required');
+    }
+    if (!sym) {
+        throw new Error('buildContractDeployMetaTx: assetSymbol required');
+    }
+    const bytecode = ensure0xHex(input.bytecodeHex);
+    const purpose_category = (input.purposeCategory ?? 'token').trim();
+    const out = {
+        type: 'contract_deploy_meta',
+        bytecode,
+        purpose_category,
+        asset_name: name,
+        asset_symbol: sym,
+    };
+    const dh = input.descriptionHashHex?.trim();
+    if (dh) {
+        out.description_hash = ensure0xHex(dh);
+    }
+    return out;
+}
+/**
+ * **One call** for wizard-style **Deploy token** on Boing: resolve pinned fungible bytecode + build **`contract_deploy_meta`**.
+ * Pass the result to **`boing_sendTransaction`** / **`boing_signTransaction`** (Boing Express).
+ */
+export function buildReferenceFungibleDeployMetaTx(input) {
+    const bytecodeHex = input.bytecodeHexOverride?.trim()
+        ? ensure0xHex(input.bytecodeHexOverride)
+        : resolveReferenceFungibleTemplateBytecodeHex({ extraEnvKeys: input.extraEnvKeys });
+    const explicitDh = input.descriptionHashHex?.trim();
+    const securityDh = !explicitDh && input.nativeTokenSecurity
+        ? descriptionHashHexFromNativeTokenSecurity(input.nativeTokenSecurity)
+        : undefined;
+    return buildContractDeployMetaTx({
+        bytecodeHex,
+        assetName: input.assetName,
+        assetSymbol: input.assetSymbol,
+        purposeCategory: input.purposeCategory,
+        descriptionHashHex: explicitDh || securityDh,
+    });
+}
+/**
+ * Same as {@link buildReferenceFungibleDeployMetaTx} but uses the secured fungible template.
+ * When **`nativeTokenSecurity`** is passed, bytecode is built so wizard toggles map to on-chain
+ * `reference_fungible_secured` init storage (not only `description_hash`). When omitted, uses the
+ * pinned default secured template (flags off).
+ */
+export function buildReferenceFungibleSecuredDeployMetaTx(input) {
+    const bytecodeHex = input.bytecodeHexOverride?.trim()
+        ? ensure0xHex(input.bytecodeHexOverride)
+        : input.nativeTokenSecurity !== undefined
+            ? buildReferenceFungibleSecuredDeployBytecodeHexFromNativeTokenSecurity(input.nativeTokenSecurity, {
+                chainHeight: input.chainContext?.chainHeight,
+                mintFirstTotalSupplyWei: input.mintFirstTotalSupplyWei,
+            })
+            : resolveReferenceFungibleSecuredTemplateBytecodeHex({ extraEnvKeys: input.extraEnvKeys });
+    const explicitDh = input.descriptionHashHex?.trim();
+    const securityDh = !explicitDh && input.nativeTokenSecurity
+        ? descriptionHashHexFromNativeTokenSecurity(input.nativeTokenSecurity)
+        : undefined;
+    return buildContractDeployMetaTx({
+        bytecodeHex,
+        assetName: input.assetName,
+        assetSymbol: input.assetSymbol,
+        purposeCategory: input.purposeCategory,
+        descriptionHashHex: explicitDh || securityDh,
+    });
+}
+/**
+ * **One call** for **native NFT collection** deploy meta tx. Bytecode: **`bytecodeHexOverride`** if set,
+ * else env keys (see {@link resolveReferenceNftCollectionTemplateBytecodeHex}), else the SDK embedded default.
+ */
+export function buildReferenceNftCollectionDeployMetaTx(input) {
+    const bytecodeHex = input.bytecodeHexOverride?.trim()
+        ? ensure0xHex(input.bytecodeHexOverride)
+        : resolveReferenceNftCollectionTemplateBytecodeHex({ extraEnvKeys: input.extraEnvKeys });
+    return buildContractDeployMetaTx({
+        bytecodeHex,
+        assetName: input.collectionName,
+        assetSymbol: input.collectionSymbol,
+        purposeCategory: input.purposeCategory ?? 'nft',
+        descriptionHashHex: input.descriptionHashHex,
+    });
+}
+const DEFAULT_NATIVE_AMM_POOL_ENV_KEYS = [
+    'BOING_NATIVE_AMM_BYTECODE_HEX',
+    'VITE_BOING_NATIVE_AMM_BYTECODE_HEX',
+    'REACT_APP_BOING_NATIVE_AMM_BYTECODE_HEX',
+];
+/**
+ * Resolve **native constant-product pool** bytecode from override or env (same keys as
+ * [examples/native-boing-tutorial](../examples/native-boing-tutorial/) **`BOING_NATIVE_AMM_BYTECODE_HEX`**).
+ */
+export function resolveNativeConstantProductPoolBytecodeHex(opts) {
+    if (opts?.explicitHex?.trim()) {
+        return ensure0xHex(opts.explicitHex);
+    }
+    for (const k of DEFAULT_NATIVE_AMM_POOL_ENV_KEYS) {
+        const v = readProcessEnv(k);
+        if (v)
+            return ensure0xHex(v);
+    }
+    if (opts?.extraEnvKeys) {
+        for (const k of opts.extraEnvKeys) {
+            const v = readProcessEnv(k);
+            if (v)
+                return ensure0xHex(v);
+        }
+    }
+    return undefined;
+}
+/**
+ * **One call** for **native CP pool** **`contract_deploy_meta`**: pinned bytecode from env or override,
+ * **`purpose_category`** default **`dapp`**, then the same Express shape as token/NFT deploys.
+ */
+export function buildNativeConstantProductPoolDeployMetaTx(input) {
+    const bytecodeHex = input.bytecodeHexOverride?.trim()
+        ? ensure0xHex(input.bytecodeHexOverride)
+        : resolveNativeConstantProductPoolBytecodeHex({ extraEnvKeys: input.extraEnvKeys });
+    if (!bytecodeHex) {
+        throw new Error('buildNativeConstantProductPoolDeployMetaTx: no pool bytecode — set BOING_NATIVE_AMM_BYTECODE_HEX (or VITE_/REACT_APP_ variant), or pass bytecodeHexOverride');
+    }
+    const name = (input.poolLabel ?? 'Native CP Pool').trim();
+    const sym = (input.poolSymbol ?? 'POOL').trim().toUpperCase();
+    if (!name) {
+        throw new Error('buildNativeConstantProductPoolDeployMetaTx: poolLabel required when set to empty');
+    }
+    if (!sym) {
+        throw new Error('buildNativeConstantProductPoolDeployMetaTx: poolSymbol required when set to empty');
+    }
+    return buildContractDeployMetaTx({
+        bytecodeHex,
+        assetName: name,
+        assetSymbol: sym,
+        purposeCategory: input.purposeCategory ?? 'dapp',
+        descriptionHashHex: input.descriptionHashHex,
+    });
+}

package/dist/canonicalTestnet.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Well-known **public Boing testnet** (chain id **6913**) identifiers.
+ *
+ * **Normative source of truth** for the canonical native CP pool address is
+ * [RPC-API-SPEC.md](https://github.com/Boing-Network/boing.network/blob/main/docs/RPC-API-SPEC.md) § Native constant-product AMM
+ * and [TESTNET.md](https://github.com/Boing-Network/boing.network/blob/main/docs/TESTNET.md) §5.3.
+ * This constant is a **convenience mirror** for TypeScript apps and tutorials; it may lag a doc-only update — verify on docs if unsure.
+ */
+/**
+ * Canonical **v1** native constant-product pool `AccountId` on public Boing testnet (**6913**).
+ * Rotations: [OPS-FRESH-TESTNET-BOOTSTRAP.md](../../docs/OPS-FRESH-TESTNET-BOOTSTRAP.md).
+ */
+/** Live stack on `https://testnet-rpc.boing.network` — see `docs/NATIVE-DEX-OPERATOR-DEPLOYMENT-RECORD.md` Appendix B. */
+export declare const CANONICAL_BOING_TESTNET_NATIVE_CP_POOL_HEX: string;
+//# sourceMappingURL=canonicalTestnet.d.ts.map

package/dist/canonicalTestnet.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"canonicalTestnet.d.ts","sourceRoot":"","sources":["../src/canonicalTestnet.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH;;;GAGG;AACH,0HAA0H;AAC1H,eAAO,MAAM,0CAA0C,QAEtD,CAAC"}

package/dist/canonicalTestnet.js

@@ -0,0 +1,15 @@
+/**
+ * Well-known **public Boing testnet** (chain id **6913**) identifiers.
+ *
+ * **Normative source of truth** for the canonical native CP pool address is
+ * [RPC-API-SPEC.md](https://github.com/Boing-Network/boing.network/blob/main/docs/RPC-API-SPEC.md) § Native constant-product AMM
+ * and [TESTNET.md](https://github.com/Boing-Network/boing.network/blob/main/docs/TESTNET.md) §5.3.
+ * This constant is a **convenience mirror** for TypeScript apps and tutorials; it may lag a doc-only update — verify on docs if unsure.
+ */
+import { validateHex32 } from './hex.js';
+/**
+ * Canonical **v1** native constant-product pool `AccountId` on public Boing testnet (**6913**).
+ * Rotations: [OPS-FRESH-TESTNET-BOOTSTRAP.md](../../docs/OPS-FRESH-TESTNET-BOOTSTRAP.md).
+ */
+/** Live stack on `https://testnet-rpc.boing.network` — see `docs/NATIVE-DEX-OPERATOR-DEPLOYMENT-RECORD.md` Appendix B. */
+export const CANONICAL_BOING_TESTNET_NATIVE_CP_POOL_HEX = validateHex32('0x7247ddc3180fdc4d3fd1e716229bfa16bad334a07d28aa9fda9ad1bfa7bdacc3');

package/dist/canonicalTestnetDex.d.ts

@@ -0,0 +1,17 @@
+/**
+ * **Live native DEX aux** on public Boing testnet RPC (`https://testnet-rpc.boing.network`, chain **6913**).
+ * Deployed via `npm run deploy-native-dex-full-stack` (operator record: `docs/NATIVE-DEX-OPERATOR-DEPLOYMENT-RECORD.md` Appendix B).
+ *
+ * **V1 ledger router** is optional (`BOING_AUX_INCLUDE_LEDGER_V1`); this stack ships swap2 + v2 + v3 forwarders only.
+ * `CANONICAL_BOING_TESTNET_NATIVE_DEX_LEDGER_ROUTER_V1_HEX` remains a legacy CREATE2 prediction id — do not assume it is deployed.
+ */
+export declare const CANONICAL_BOING_TESTNET_NATIVE_DEX_DEPLOYER_HEX: string;
+export declare const CANONICAL_BOING_TESTNET_NATIVE_DEX_FACTORY_HEX: string;
+/** Legacy predicted v1 — not deployed on the current testnet-rpc full-stack bundle unless aux includes v1. */
+export declare const CANONICAL_BOING_TESTNET_NATIVE_DEX_LEDGER_ROUTER_V1_HEX: string;
+export declare const CANONICAL_BOING_TESTNET_NATIVE_DEX_LEDGER_ROUTER_V2_HEX: string;
+export declare const CANONICAL_BOING_TESTNET_NATIVE_DEX_LEDGER_ROUTER_V3_HEX: string;
+export declare const CANONICAL_BOING_TESTNET_NATIVE_DEX_MULTIHOP_SWAP_ROUTER_HEX: string;
+export declare const CANONICAL_BOING_TESTNET_NATIVE_AMM_LP_VAULT_HEX: string;
+export declare const CANONICAL_BOING_TESTNET_NATIVE_LP_SHARE_TOKEN_HEX: string;
+//# sourceMappingURL=canonicalTestnetDex.d.ts.map

package/dist/canonicalTestnetDex.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"canonicalTestnetDex.d.ts","sourceRoot":"","sources":["../src/canonicalTestnetDex.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,eAAO,MAAM,+CAA+C,QAE3D,CAAC;AAEF,eAAO,MAAM,8CAA8C,QAE1D,CAAC;AAEF,8GAA8G;AAC9G,eAAO,MAAM,uDAAuD,QAEnE,CAAC;AAEF,eAAO,MAAM,uDAAuD,QAEnE,CAAC;AAEF,eAAO,MAAM,uDAAuD,QAEnE,CAAC;AAEF,eAAO,MAAM,2DAA2D,QAEvE,CAAC;AAEF,eAAO,MAAM,+CAA+C,QAE3D,CAAC;AAEF,eAAO,MAAM,iDAAiD,QAE7D,CAAC"}

package/dist/canonicalTestnetDex.js

@@ -0,0 +1,17 @@
+/**
+ * **Live native DEX aux** on public Boing testnet RPC (`https://testnet-rpc.boing.network`, chain **6913**).
+ * Deployed via `npm run deploy-native-dex-full-stack` (operator record: `docs/NATIVE-DEX-OPERATOR-DEPLOYMENT-RECORD.md` Appendix B).
+ *
+ * **V1 ledger router** is optional (`BOING_AUX_INCLUDE_LEDGER_V1`); this stack ships swap2 + v2 + v3 forwarders only.
+ * `CANONICAL_BOING_TESTNET_NATIVE_DEX_LEDGER_ROUTER_V1_HEX` remains a legacy CREATE2 prediction id — do not assume it is deployed.
+ */
+import { validateHex32 } from './hex.js';
+export const CANONICAL_BOING_TESTNET_NATIVE_DEX_DEPLOYER_HEX = validateHex32('0x3b6a27bcceb6a42d62a3a8d02a6f0d73653215771de243a63ac048a18b59da29');
+export const CANONICAL_BOING_TESTNET_NATIVE_DEX_FACTORY_HEX = validateHex32('0x58112627fc84618a27b82e9af82bc9a51761c6d3cca1260c93d56d22b6c481a1');
+/** Legacy predicted v1 — not deployed on the current testnet-rpc full-stack bundle unless aux includes v1. */
+export const CANONICAL_BOING_TESTNET_NATIVE_DEX_LEDGER_ROUTER_V1_HEX = validateHex32('0x371b4cd7e3b88e06e6b89bdc86214918a7e7ec73b62deb7f9975e4166736d54d');
+export const CANONICAL_BOING_TESTNET_NATIVE_DEX_LEDGER_ROUTER_V2_HEX = validateHex32('0x33334ff73c44c93335ac5e69938a52ea65fa77b062d1961ed22c131adaa31e0f');
+export const CANONICAL_BOING_TESTNET_NATIVE_DEX_LEDGER_ROUTER_V3_HEX = validateHex32('0x2c90ffcddeb2683219b4b8143a91d7b93f249bcb0d9523c8b4f2111de668b79a');
+export const CANONICAL_BOING_TESTNET_NATIVE_DEX_MULTIHOP_SWAP_ROUTER_HEX = validateHex32('0xf801cd1aa5ec402f89a2f394b49e6b0c136264d8945b16a4a6a81a188b18acc1');
+export const CANONICAL_BOING_TESTNET_NATIVE_AMM_LP_VAULT_HEX = validateHex32('0x937d09ee8e4dcc521c812566ad4930792e74ad004ecb3ae2cc73dc015813aa8d');
+export const CANONICAL_BOING_TESTNET_NATIVE_LP_SHARE_TOKEN_HEX = validateHex32('0x101201403f573e5b1d6d5c6b93d52d12c68957f4a228d5dad76e78c747044421');

package/dist/chainIds.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Chain identifiers for **native Boing** L1 — use in multi-network dApps (deploy wizards, network pickers).
+ *
+ * Prefer **`boing_getNetworkInfo`**.`chain_id` when connected to a live RPC; use these constants when
+ * branching on **`eth_chainId`** / **`boing_chainId`** from the wallet.
+ */
+/** Public testnet chain id (decimal), per docs ([TESTNET.md](../../docs/TESTNET.md)). */
+export declare const BOING_TESTNET_CHAIN_ID_DECIMAL = 6913;
+/** Same id as EIP-155-style `0x`-prefixed hex (lowercase). */
+export declare const BOING_TESTNET_CHAIN_ID_HEX: "0x1b01";
+/**
+ * Normalize wallet/RPC chain id to lowercase `0x` hex (e.g. **`0x1b01`**).
+ * Accepts decimal string, `0x` hex, or bigint / number.
+ */
+export declare function normalizeBoingChainIdHex(chainId: string | number | bigint): `0x${string}`;
+/** True when **`chainId`** is **Boing testnet** (6913 / `0x1b01`), after normalization. */
+export declare function isBoingTestnetChainId(chainId: string | number | bigint): boolean;
+//# sourceMappingURL=chainIds.d.ts.map

package/dist/chainIds.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chainIds.d.ts","sourceRoot":"","sources":["../src/chainIds.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,yFAAyF;AACzF,eAAO,MAAM,8BAA8B,OAAO,CAAC;AAEnD,8DAA8D;AAC9D,eAAO,MAAM,0BAA0B,EAAG,QAAiB,CAAC;AAO5D;;;GAGG;AACH,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,GAAG,KAAK,MAAM,EAAE,CA2BzF;AAED,2FAA2F;AAC3F,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAOhF"}

package/dist/chainIds.js

@@ -0,0 +1,56 @@
+/**
+ * Chain identifiers for **native Boing** L1 — use in multi-network dApps (deploy wizards, network pickers).
+ *
+ * Prefer **`boing_getNetworkInfo`**.`chain_id` when connected to a live RPC; use these constants when
+ * branching on **`eth_chainId`** / **`boing_chainId`** from the wallet.
+ */
+/** Public testnet chain id (decimal), per docs ([TESTNET.md](../../docs/TESTNET.md)). */
+export const BOING_TESTNET_CHAIN_ID_DECIMAL = 6913;
+/** Same id as EIP-155-style `0x`-prefixed hex (lowercase). */
+export const BOING_TESTNET_CHAIN_ID_HEX = '0x1b01';
+function strip0x(h) {
+    const t = h.trim().toLowerCase();
+    return t.startsWith('0x') ? t.slice(2) : t;
+}
+/**
+ * Normalize wallet/RPC chain id to lowercase `0x` hex (e.g. **`0x1b01`**).
+ * Accepts decimal string, `0x` hex, or bigint / number.
+ */
+export function normalizeBoingChainIdHex(chainId) {
+    if (typeof chainId === 'bigint') {
+        if (chainId < 0n) {
+            throw new Error('normalizeBoingChainIdHex: negative chain id');
+        }
+        return `0x${chainId.toString(16)}`;
+    }
+    if (typeof chainId === 'number') {
+        if (!Number.isInteger(chainId) || chainId < 0) {
+            throw new Error(`normalizeBoingChainIdHex: invalid number ${chainId}`);
+        }
+        return `0x${BigInt(chainId).toString(16)}`;
+    }
+    const s = chainId.trim();
+    if (/^\d+$/.test(s)) {
+        const n = BigInt(s);
+        if (n < 0n) {
+            throw new Error('normalizeBoingChainIdHex: negative chain id');
+        }
+        return `0x${n.toString(16)}`;
+    }
+    const bare = strip0x(s);
+    if (!/^[0-9a-f]+$/i.test(bare)) {
+        throw new Error('normalizeBoingChainIdHex: expected decimal or hex chain id');
+    }
+    const n = BigInt(`0x${bare}`);
+    return `0x${n.toString(16)}`;
+}
+/** True when **`chainId`** is **Boing testnet** (6913 / `0x1b01`), after normalization. */
+export function isBoingTestnetChainId(chainId) {
+    try {
+        const h = normalizeBoingChainIdHex(chainId).toLowerCase();
+        return h === BOING_TESTNET_CHAIN_ID_HEX;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/client.d.ts

@@ -0,0 +1,223 @@
+/**
+ * Boing JSON-RPC client — typed methods for all node RPCs.
+ */
+import type { AccountBalance, AccountProof, AccountState, Block, ExecutionReceipt, GetLogsFilter, RpcLogEntry, FaucetResult, QaCheckResponse, QaPoolConfigResult, QaPoolListResult, QaPoolVoteResult, RegisterDappResult, SimulateResult, SubmitIntentResult, SubmitTransactionResult, SyncState, NetworkInfo, BoingHealth, RpcMethodCatalog, RpcOpenApiDocument, BoingRpcPreflightResult, ContractStorageWord, DexPoolListPage, DexTokenListPage, DexTokenListRow, VerifyProofResult, OperatorApplyQaPolicyResult, QaRegistryResult, JsonRpcBatchResponseItem } from './types.js';
+export interface BoingClientConfig {
+    baseUrl: string;
+    /** Optional fetch implementation (e.g. for Node or custom headers). */
+    fetch?: typeof fetch;
+    /** Request timeout in ms. Default 30000. Set 0 to disable. */
+    timeoutMs?: number;
+    /** Merged into every JSON-RPC request (e.g. `{ 'X-Boing-Operator': token }`). */
+    extraHeaders?: Record<string, string>;
+    /**
+     * Extra attempts after the first failure for transient errors (HTTP 429/502/503/504, RPC -32016,
+     * timeouts, network). Default **0** (no retries).
+     */
+    maxRetries?: number;
+    /** Backoff base in ms before each retry: wait `retryBaseDelayMs * 2^attempt`. Default 250. */
+    retryBaseDelayMs?: number;
+    /**
+     * When true, sends **`X-Request-Id`** on each HTTP call (fresh UUID per request). Nodes echo it for log correlation.
+     */
+    generateRequestId?: boolean;
+}
+/**
+ * HTTP JSON-RPC client for a Boing node.
+ * All methods return typed results; on RPC error they throw BoingRpcError (with code, message, method, and optional data).
+ */
+export declare class BoingClient {
+    private readonly baseUrl;
+    private readonly fetchImpl;
+    private readonly timeoutMs;
+    private readonly extraHeaders;
+    private readonly maxRetries;
+    private readonly retryBaseDelayMs;
+    private readonly generateRequestId;
+    private id;
+    /** From the last JSON-RPC **`POST /`** response header **`x-request-id`** (when present). */
+    private lastXRequestId;
+    constructor(config: string | BoingClientConfig);
+    /** Normalized RPC origin (no trailing slash). */
+    getBaseUrl(): string;
+    /**
+     * Correlation id from the most recent JSON-RPC **`POST /`** response (**`x-request-id`**).
+     * Useful for support UI when CORS exposes this header on the response.
+     */
+    getLastXRequestId(): string | undefined;
+    private recordRequestIdFromResponse;
+    private rpcExtraHeaders;
+    private requestOnce;
+    private request;
+    private requestBatchOnce;
+    /**
+     * POST a JSON-RPC **batch** (JSON array of requests). Assigns monotonic numeric `id`s; returns the response array in order.
+     */
+    requestBatch(calls: ReadonlyArray<{
+        method: string;
+        params?: unknown[];
+    }>): Promise<JsonRpcBatchResponseItem[]>;
+    /**
+     * `GET {baseUrl}/live` — process is up (no chain read; for orchestrator liveness).
+     * Uses the same `extraHeaders` as JSON-RPC (e.g. auth in front of the node).
+     */
+    checkHttpLive(): Promise<boolean>;
+    /**
+     * `GET {baseUrl}/ready` — node can serve RPC (read lock on state). Returns false on **503** when
+     * the node enforces **`BOING_RPC_READY_MIN_PEERS`** and peer count is too low.
+     */
+    checkHttpReady(): Promise<boolean>;
+    /**
+     * One round-trip sanity check for dashboards and CI: `health`, supported method count,
+     * optional catalog size, whether OpenAPI JSON is exposed, plain HTTP `/live` + `/ready`,
+     * and a small JSON-RPC **batch** probe (`jsonrpcBatchOk`).
+     */
+    preflightRpc(): Promise<BoingRpcPreflightResult>;
+    /** `GET {baseUrl}/openapi.json` — same document as `boing_getRpcOpenApi` when the node exposes it. */
+    checkHttpOpenApiJson(): Promise<boolean>;
+    /** `GET {baseUrl}/.well-known/boing-rpc` — path hints for HTTP discovery. */
+    checkWellKnownBoingRpc(): Promise<boolean>;
+    /** `GET {baseUrl}/live.json` — JSON liveness probe. */
+    checkHttpLiveJson(): Promise<boolean>;
+    /**
+     * **`GET {baseUrl}/openapi.json`** — same OpenAPI document as **`boing_getRpcOpenApi`**, without a JSON-RPC round-trip.
+     * Prefer this in browser devtools panels; throws **`BoingRpcError`** when the response is not OK or not JSON.
+     */
+    fetchOpenApiViaHttp(): Promise<RpcOpenApiDocument>;
+    /** Current chain height (tip block number). */
+    chainHeight(): Promise<number>;
+    /** Build identity string for this node (e.g. `boing-node/0.1.0`). Params: `[]`. */
+    clientVersion(): Promise<string>;
+    /**
+     * Alphabetically sorted `boing_*` method names implemented by this binary (discovery). Params: `[]`.
+     */
+    rpcSupportedMethods(): Promise<string[]>;
+    /** Embedded JSON Schema-style catalog for codegen (params `[]`). See `boing_getNetworkInfo.developer`. */
+    getRpcMethodCatalog(): Promise<RpcMethodCatalog>;
+    /** Minimal OpenAPI 3.1 document for `POST /` JSON-RPC and `GET /ws` (params `[]`). */
+    getRpcOpenApi(): Promise<RpcOpenApiDocument>;
+    /**
+     * Liveness and build identity (params `[]`). Prefer this over `boing_chainHeight` for load balancers:
+     * includes `client_version`, optional `chain_id` / `chain_name` from node env, and `head_height`.
+     */
+    health(): Promise<BoingHealth>;
+    /**
+     * Committed chain tip: `head_height`, `finalized_height` (same as head today), and tip `latest_block_hash`.
+     * See RPC-API-SPEC.md — finality semantics.
+     */
+    getSyncState(): Promise<SyncState>;
+    /**
+     * Network + tip snapshot for dApps (params `[]`). Includes `chain_native` (sums over committed accounts) and
+     * `rpc.not_available` for capabilities this surface does not expose (e.g. staking APY).
+     * See RPC-API-SPEC.md — `chain_id` / `chain_name` require node env `BOING_CHAIN_ID` / `BOING_CHAIN_NAME`.
+     */
+    getNetworkInfo(): Promise<NetworkInfo>;
+    /** Get spendable balance for an account. Params: 32-byte account ID (hex). */
+    getBalance(hexAccountId: string): Promise<AccountBalance>;
+    /** Get full account state (balance, nonce, stake). Params: 32-byte account ID (hex). */
+    getAccount(hexAccountId: string): Promise<AccountState>;
+    /** Get block by height. Returns null if not found. */
+    getBlockByHeight(height: number, includeReceipts?: boolean): Promise<Block | null>;
+    /** Receipt for an included tx (`Transaction.id` hex), or `null` if unknown. */
+    getTransactionReceipt(hexTxId: string): Promise<ExecutionReceipt | null>;
+    /**
+     * Bounded log query over committed blocks (see RPC-API-SPEC — max block span and result cap on the node).
+     * Optional `address` is normalized to 32-byte hex when provided.
+     */
+    getLogs(filter: GetLogsFilter): Promise<RpcLogEntry[]>;
+    /** Get block by hash. Params: 32-byte block hash (hex). */
+    getBlockByHash(hexBlockHash: string, includeReceipts?: boolean): Promise<Block | null>;
+    /** Get Merkle proof for an account. Params: 32-byte account ID (hex). */
+    getAccountProof(hexAccountId: string): Promise<AccountProof>;
+    /** Verify an account Merkle proof. Params: hex proof, hex state root. */
+    verifyAccountProof(hexProof: string, hexStateRoot: string): Promise<VerifyProofResult>;
+    /** Read one 32-byte VM storage slot for a contract (`SLOAD` semantics; missing → zero word). */
+    getContractStorage(hexContractId: string, hexKey32: string): Promise<ContractStorageWord>;
+    /**
+     * Cursor-paginated native DEX pools (`boing_listDexPools`).
+     * Factory: **`params.factory`** (32-byte hex) overrides **`BOING_CANONICAL_NATIVE_DEX_FACTORY`**.
+     * Set **`light`** / **`enrich: false`** to skip receipt scan (**`createdAtHeight`** stays null).
+     * Each pool row includes **`tokenADecimals`** / **`tokenBDecimals`** (**`BOING_DEX_TOKEN_DECIMALS_JSON`**, default **18**).
+     */
+    listDexPoolsPage(params?: {
+        cursor?: string | null;
+        limit?: number;
+        factory?: string;
+        /** Fast path: skip receipt scan (no **`createdAtHeight`**). */
+        light?: boolean;
+        /** When false, same as **`light: true`**. */
+        enrich?: boolean;
+        /** When true, response may include **`diagnostics`** (receipt scan counters). */
+        includeDiagnostics?: boolean;
+    }): Promise<DexPoolListPage>;
+    /**
+     * Cursor-paginated DEX-derived token universe (`boing_listDexTokens`).
+     * Optional **`minReserveProduct`** / **`minLiquidityWei`** are decimal digit strings (same as node).
+     * **`light`** skips receipt + deploy metadata scans (**`firstSeenHeight`** null, **`metadataSource`** abbrev-only).
+     */
+    listDexTokensPage(params?: {
+        cursor?: string | null;
+        limit?: number;
+        factory?: string;
+        light?: boolean;
+        enrich?: boolean;
+        minReserveProduct?: string;
+        minLiquidityWei?: string;
+        includeDiagnostics?: boolean;
+    }): Promise<DexTokenListPage>;
+    /** Single-token lookup in the DEX-derived universe (`boing_getDexToken`). */
+    getDexToken(idHex32: string, options?: {
+        factory?: string;
+        light?: boolean;
+        enrich?: boolean;
+        includeDiagnostics?: boolean;
+    }): Promise<DexTokenListRow | null>;
+    /** Simulate a transaction without applying it. Params: hex-encoded signed transaction. */
+    simulateTransaction(hexSignedTx: string): Promise<SimulateResult>;
+    /**
+     * Dry-run a `contract_call` without a signed transaction (`boing_simulateContractCall`).
+     * Params: `[contract_hex, calldata_hex, sender_hex?, at_block?]` — see `docs/RPC-API-SPEC.md`.
+     */
+    simulateContractCall(contractHex: string, calldataHex: string, options?: {
+        /** Omit for two-arg RPC; `null` or omit with `atBlock` → JSON `null` (zero sender). */
+        senderHex?: string | null;
+        /** `"latest"` or current tip height integer. */
+        atBlock?: number | 'latest';
+    }): Promise<SimulateResult>;
+    /**
+     * Submit a signed transaction to the mempool.
+     * The hex_signed_tx must be hex-encoded bincode-serialized SignedTransaction (from Rust/CLI or future signer).
+     */
+    submitTransaction(hexSignedTx: string): Promise<SubmitTransactionResult>;
+    /** Register a dApp for incentive tracking. Params: 32-byte hex contract id, 32-byte hex owner id. */
+    registerDappMetrics(hexContract: string, hexOwner: string): Promise<RegisterDappResult>;
+    /** Submit a signed intent. Params: hex-encoded signed intent. */
+    submitIntent(hexSignedIntent: string): Promise<SubmitIntentResult>;
+    /**
+     * Pre-flight QA check for a deployment (no submit). Matches node param order:
+     * [hex_bytecode, purpose_category?, description_hash?, asset_name?, asset_symbol?].
+     * When passing asset_name, include description_hash (or use a 32-byte placeholder) per RPC-API-SPEC.
+     * Returns allow | reject | unsure; when reject, rule_id and message are set.
+     */
+    /** List pending governance QA pool items. */
+    qaPoolList(): Promise<QaPoolListResult>;
+    /** Read effective QA pool governance config and `pending_count`. */
+    qaPoolConfig(): Promise<QaPoolConfigResult>;
+    /** Read-only: effective QA rule registry JSON (same shape as `qa_registry.json`). No auth. */
+    getQaRegistry(): Promise<QaRegistryResult>;
+    /**
+     * Vote on a pooled Unsure deploy. `voter` must be a governance administrator unless the node uses dev_open_voting.
+     * Params: tx_hash hex, voter account hex, `allow` | `reject` | `abstain`.
+     */
+    qaPoolVote(txHashHex: string, voterHex: string, vote: 'allow' | 'reject' | 'abstain'): Promise<QaPoolVoteResult>;
+    /**
+     * Apply QA registry and pool governance config on the node (operator RPC).
+     * Params are full JSON documents as strings (same format as `qa_registry.json` / `qa_pool_config.json`).
+     * Requires `X-Boing-Operator` when the node has `BOING_OPERATOR_RPC_TOKEN` set.
+     */
+    operatorApplyQaPolicy(registryJson: string, qaPoolConfigJson: string): Promise<OperatorApplyQaPolicyResult>;
+    qaCheck(hexBytecode: string, purposeCategory?: string, descriptionHash?: string, assetName?: string, assetSymbol?: string): Promise<QaCheckResponse>;
+    /** Request testnet BOING (only when node is started with --faucet-enable). Params: 32-byte account ID (hex). Rate limited per account. */
+    faucetRequest(hexAccountId: string): Promise<FaucetResult>;
+}
+//# sourceMappingURL=client.d.ts.map