boing-sdk 0.3.0

package/CHANGELOG.md

@@ -0,0 +1,26 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html) as applied before **1.0.0** (minor releases may include breaking TypeScript surface changes).
+
+## [0.3.0] - 2026-04-12
+
+### Added
+
+- **DEX discovery JSON-RPC helpers** on `BoingClient`: `listDexPoolsPage`, `listDexTokensPage`, `getDexToken` (`boing_listDexPools`, `boing_listDexTokens`, `boing_getDexToken`), including optional `factory`, `light` / `enrich`, and `includeDiagnostics`.
+- **Types** `DexPoolListRow`, `DexPoolListPage`, `DexTokenListRow`, `DexTokenListPage`, `DexDiscoveryPoolDiagnostics`, `DexDiscoveryTokenDiagnostics` (exported from package root).
+- **`buildNativeDexIndexerStatsForClient`**: merges `createdAtHeight`, `tokenADecimals`, and `tokenBDecimals` from `boing_listDexPools` into `NativeDexIndexerPoolRow` when the node supports discovery RPC.
+
+### Changed
+
+- **`DexPoolListRow`** now includes required **`tokenADecimals`** and **`tokenBDecimals`** (aligned with node; default **18** when the node has no decimals map).
+
+### Breaking (TypeScript)
+
+- Code that **constructs** `DexPoolListRow` literals must supply **`tokenADecimals`** and **`tokenBDecimals`**. Consumers that only **parse** RPC JSON from a current node are unchanged.
+
+### Packaging
+
+- **`package.json` `files`**: the published tarball includes **`dist/`**, **`README.md`**, and **`CHANGELOG.md`** only (smaller install; `prepublishOnly` still runs **`npm run build`**).

package/README.md

@@ -0,0 +1,191 @@
+# Boing SDK
+
+TypeScript/JavaScript client for [Boing Network](https://github.com/Boing-Network/boing.network): typed RPC client, hex utilities, and structured errors (including QA rejection feedback).
+
+## Install
+
+```bash
+npm install
+npm run build
+```
+
+Or from a parent repo (when published): `npm install boing-sdk`.
+
+### Consuming via `file:` (e.g. [boing.finance](https://github.com/Boing-Network/boing.finance))
+
+The compiled output lives in **`dist/`**, which is **committed** in `Boing-Network/boing.network` (repo root `.gitignore` ignores generic `dist/` but not `boing-sdk/dist/`). Clones and CI siblings therefore get a usable `dist/index.js` without a separate SDK build step.
+
+When you change SDK **source** (`src/`), run `npm run build` in `boing-sdk` and commit the updated **`dist/`**. The **`boing-sdk`** workflow fails if `dist/` drifts from the TypeScript build output.
+
+**boing.finance** checks out `boing.network` only so the `file:` path resolves; it does not build the SDK first. **boing.finance**’s `frontend/scripts/postinstall-boing-sdk.mjs` only runs `npm run build` in the linked package when `dist/index.js` is missing (e.g. local SDK development or a broken checkout) and **fails the install** if that build does not succeed.
+
+## Tests
+
+- **Unit / offline:** `npm test` — Vitest; does not require a running Boing node.
+- **Optional RPC integration:** `tests/rpcIntegration.test.ts` runs only when **`BOING_INTEGRATION_RPC_URL`** is set (e.g. `http://127.0.0.1:8545`). If it is unset, Vitest **skips** that whole suite so default runs stay offline-friendly. Core cases: sync state (or **`getBlockByHeight`** fallback), blocks + receipts, **`getLogsChunked`**, **`fetchBlocksWithReceiptsForHeightRange`**, **`getTransactionReceipt`** (unknown tx → **`null`**). Endpoints that return **-32601** for **`boing_getSyncState`** or **`boing_getLogs`** still pass where noted. With **`BOING_EXPECT_FULL_RPC=1`** (see **`.github/workflows/boing-sdk-rpc-integration.yml`**), an extra test asserts **`boing_clientVersion`**, **`boing_rpcSupportedMethods`**, and **`probeBoingRpcCapabilities`** (6/6 core methods, including **`boing_getNetworkInfo`** / **`boing_getBlockByHeight`** / **`boing_getTransactionReceipt`**).
+- **Operator / tutorial smoke (separate from Vitest):** in **`examples/native-boing-tutorial`**, **`npm run preflight-rpc`** (or **`check-testnet-rpc`** only) with **`BOING_RPC_URL`** — same scripts CI runs after starting a local node; see [PRE-VIBEMINER-NODE-COMMANDS.md](../docs/PRE-VIBEMINER-NODE-COMMANDS.md). From the **monorepo root**, the same **`npm run <script>`** names delegate to the tutorial package (see root **`package.json`**).
+- **`npm run verify`** — same as `npm test`, then prints a short note explaining the skip when the env var is missing.
+
+## Quick start
+
+```ts
+import { createClient, BoingRpcError } from 'boing-sdk';
+
+const client = createClient('http://localhost:8545');
+
+// Read chain and account state
+const height = await client.chainHeight();
+const account = await client.getAccount('0x' + '00'.repeat(32)); // 32-byte hex
+console.log(account.balance, account.nonce, account.stake);
+
+// Pre-flight QA check before deploying a contract
+const qa = await client.qaCheck('0x600160005260206000f3'); // hex bytecode
+if (qa.result === 'reject') {
+  console.error('QA rejected:', qa.rule_id, qa.message);
+} else if (qa.result === 'allow') {
+  // Submit signed tx (hex from Rust CLI or future signer)
+  await client.submitTransaction(hexSignedTx);
+}
+
+// Handle structured QA errors on submit
+try {
+  await client.submitTransaction(hexSignedTx);
+} catch (e) {
+  if (e instanceof BoingRpcError && e.isQaRejected) {
+    const { rule_id, message } = e.qaData ?? {};
+    console.error('Deployment rejected:', rule_id, message);
+  }
+  throw e;
+}
+```
+
+## API
+
+- **createClient(config)** — `config` can be a URL string or `{ baseUrl, fetch?, timeoutMs? }`. Default timeout 30s; set `timeoutMs: 0` to disable.
+- **BoingClient** — typed methods for all RPCs (32-byte account/hash params are validated locally before sending):
+  - **RPC probe** — **`probeBoingRpcCapabilities`** returns **`{ clientVersion, supportedMethods, methods }`** plus **`countAvailableBoingRpcMethods`**, **`explainBoingRpcProbeGaps`** (`rpcCapabilities.ts`): detect **-32601** missing methods; CLI: **`npm run build`** then **`npm run probe-rpc`** (or **`npm run probe-rpc`** from repo root); **`diagnosis`** in JSON explains stale node vs current repo; node discovery: **`boing_clientVersion`**, **`boing_rpcSupportedMethods`**
+  - `chainHeight()`, `getBalance(hexAccountId)`, `getAccount(hexAccountId)`
+  - `getBlockByHeight(height, includeReceipts?)`, `getBlockByHash(hexHash, includeReceipts?)`
+  - `getTransactionReceipt(hexTxId)`, `getLogs(filter)` — bounded log query ([RPC-API-SPEC.md](../docs/RPC-API-SPEC.md))
+  - Receipt/log helpers: `normalizeTopicWord`, `iterBlockReceiptLogs`, `filterReceiptLogsByTopic0`, … (`receiptLogs.ts`; see [INDEXER-RECEIPT-AND-LOG-INGESTION.md](../docs/INDEXER-RECEIPT-AND-LOG-INGESTION.md))
+  - `getAccountProof(hexAccountId)`, `verifyAccountProof(hexProof, hexStateRoot)`
+  - `simulateTransaction(hexSignedTx)`, `submitTransaction(hexSignedTx)`
+  - High-level flows: `submitTransferWithSimulationRetry`, `submitContractCallWithSimulationRetry`, `submitDeployWithPurposeFlow` (see **Simulate → access list → submit** below)
+  - **Pinned native deploy (Boing Express tx objects)** — `buildContractDeployMetaTx`, **`buildReferenceFungibleDeployMetaTx`** / **`buildReferenceFungibleSecuredDeployMetaTx`** / **`buildReferenceNftCollectionDeployMetaTx`** (wizard-friendly one-call builders), `resolveReferenceFungibleTemplateBytecodeHex`, **`resolveReferenceFungibleSecuredTemplateBytecodeHex`**, `resolveReferenceNftCollectionTemplateBytecodeHex`, `ensure0xHex`, `DEFAULT_REFERENCE_FUNGIBLE_SECURED_TEMPLATE_BYTECODE_HEX`, `REFERENCE_FUNGIBLE_TEMPLATE_VERSION`, **`REFERENCE_FUNGIBLE_SECURED_TEMPLATE_VERSION`**, `REFERENCE_NFT_COLLECTION_TEMPLATE_VERSION` (`canonicalDeployArtifacts.ts`; [BOING-CANONICAL-DEPLOY-ARTIFACTS.md](../docs/BOING-CANONICAL-DEPLOY-ARTIFACTS.md)); multi-network wizards: **`isBoingTestnetChainId`**, **`normalizeBoingChainIdHex`**, **`BOING_TESTNET_CHAIN_ID_*`** (`chainIds.ts`); review-step QA (`dappDeploy.ts`; [BOING-DAPP-INTEGRATION.md](../docs/BOING-DAPP-INTEGRATION.md) § **One wizard, two backends**): **`buildAndPreflightReferenceFungibleDeploy`**, **`buildAndPreflightReferenceNftCollectionDeployMeta`**, **`preflightContractDeployMetaWithUi`**, **`describeContractDeployMetaQaResponse`**, **`preflightContractDeployMetaQa`**, **`BOING_QA_PLACEHOLDER_DESCRIPTION_HASH_HEX`**
+  - **Generic calldata words** — `calldataSelectorLastByte`, `calldataU128BeWord`, `calldataAccountIdWord`, `calldataFixedWord32`, `concatCalldata` (same layout as reference token/NFT encoders; use for custom contracts)
+  - **Typed call builder** — `BoingCalldataWord`, `assertBoingCalldataWord`, `boingWordU128` / `boingWordAccount` / `boingWordFixed` / `boingWordSelector` (32-byte argument words), **`encodeBoingCall(selectorLowByte, args)`** (reference-style first word + argument words)
+  - **Minimal call ABI (Boing-native)** — `encodeBoingCallTyped(selector, ['u128','account',…], values)`, `encodeBoingCallFromAbiArgs`, **`BoingReferenceCallDescriptors`** (reference token / NFT / native AMM layouts) + **`encodeBoingCallFromDescriptor`** — not Solidity ABI / keccak4; matches `docs/BOING-REFERENCE-TOKEN.md`, `BOING-REFERENCE-NFT.md`, `NATIVE-AMM-CALLDATA.md`
+  - **Native CP pool (MVP)** — `buildNativeConstantProductPoolAccessList`, `buildNativeConstantProductContractCallTx`, `mergeNativePoolAccessListWithSimulation`; **`fetchNativeConstantProductReserves`**, **`fetchNativeConstantProductPoolSnapshot`** (batched reserves + total LP ± signer LP), **`fetchNativeConstantProductTotalLpSupply`**, **`fetchNativeConstantProductSwapFeeBps`** (v3/v4), **`fetchNativeAmmSignerLpBalance`**, **`decodeBoingStorageWordU128`**, **`decodeNativeAmmAddLiquidityReturnLpMinted`**, **`decodeNativeAmmLogDataU128Triple`**, reserve / total-LP / token / **swap-fee-bps** key helpers (`nativeAmmPool.ts`); **`tryParseNativeAmmLog2`**, **`filterMapNativeAmmRpcLogs`** (`nativeAmmLogs.ts`); **`constantProductAmountOut`** / **`constantProductAmountOutWithFeeBps`** / **`constantProductAmountOutNoFee`** / **`encodeNativeAmmSetTokensCalldata`** / **`encodeNativeAmmSetSwapFeeBpsCalldata`** / **`NATIVE_CP_SWAP_FEE_BPS`** / **`NATIVE_AMM_TOPIC_*_HEX`** / **`nativeAmmLogTopic0Utf8`** (`nativeAmm.ts`; [NATIVE-AMM-CALLDATA.md](../docs/NATIVE-AMM-CALLDATA.md)); **LP vault** — `encodeNativeAmmLpVaultConfigureCalldata`, `buildNativeAmmLpVaultDepositAddAccessList`, `buildNativeAmmLpVaultDepositAddContractCallTx`, merge helpers (`nativeAmmLpVault.ts`; [NATIVE-AMM-LP-VAULT.md](../docs/NATIVE-AMM-LP-VAULT.md)); **LP share token** — encoders + `buildLpShareTokenAccessList`, `buildLpShareTokenContractCallTx`, `mergeLpShareTokenAccessListWithSimulation` (`nativeLpShareToken.ts`; [NATIVE-LP-SHARE-TOKEN.md](../docs/NATIVE-LP-SHARE-TOKEN.md)); **`CANONICAL_BOING_TESTNET_NATIVE_CP_POOL_HEX`** (`canonicalTestnet.ts`) — convenience mirror of [RPC-API-SPEC.md](../docs/RPC-API-SPEC.md) § Native constant-product AMM (bump when the on-chain canonical pool changes)
+  - **Native DEX (pair directory + routers)** — [BOING-NATIVE-DEX-CAPABILITY.md](../docs/BOING-NATIVE-DEX-CAPABILITY.md): factory calldata + access lists (`nativeDexFactory.ts`), **`fetchNativeDexFactoryPairsCount`**, **`findNativeDexFactoryPoolByTokens`**, **`Log3`** parsers (`nativeDexFactoryPool.ts`, `nativeDexFactoryLogs.ts`; [NATIVE-DEX-FACTORY.md](../docs/NATIVE-DEX-FACTORY.md)); ledger-router forward calldata + tx builders **v1–v3** (`nativeDexLedgerRouter.ts`; [NATIVE-DEX-LEDGER-ROUTER.md](../docs/NATIVE-DEX-LEDGER-ROUTER.md)); **swap2** + **multihop** encoders (`nativeDexSwap2Router.ts`; [NATIVE-DEX-SWAP2-ROUTER.md](../docs/NATIVE-DEX-SWAP2-ROUTER.md), [NATIVE-DEX-MULTIHOP-SWAP-ROUTER.md](../docs/NATIVE-DEX-MULTIHOP-SWAP-ROUTER.md)); CREATE2 predictors + salts (`create2.ts`); tutorial **`deploy-native-dex-directory`** ([examples/native-boing-tutorial](../examples/native-boing-tutorial/) README §7c2)
+  - **Seamless defaults + wallet glue** — **`fetchNativeDexIntegrationDefaults`** / **`mergeNativeDexIntegrationDefaults`** (`dexIntegration.ts`): merge **`boing_getNetworkInfo`**.**`end_user`** (**`BOING_CANONICAL_NATIVE_CP_POOL`** / **`BOING_CANONICAL_NATIVE_DEX_FACTORY`**) with overrides and **6913** embedded pool fallback; **`fetchNativeDexFactoryRegisterLogs`** for chunked **`register_pair`** scans; **`getInjectedEip1193Provider`**, **`boingSendTransaction`**, **`requestAccounts`**, **`readChainIdHex`**, **`providerSupportsBoingNativeRpc`** (`walletProvider.ts`; [BOING-DAPP-INTEGRATION.md](../docs/BOING-DAPP-INTEGRATION.md))
+  - **Directory snapshot (Boing-only)** — **`fetchNativeDexDirectorySnapshot`** (defaults + **`pairs_count`** + optional log backfill), **`pickNativeDexPoolFromRegisterLogs`**, **`resolveNativeDexPoolForTokens`** (`logs` | `simulate` | `auto`), **`nativeDexPairKey`**, **`suggestNativeDexRegisterLogCatchUpRange`** (`nativeDexDirectory.ts`; no external chain RPC)
+  - **DEX onboarding + preflight** — **`formatBoingNativeDexNotEvmDisclaimer`**, **`describeNativeDexDefaultGaps`**, **`assertBoingNativeDexToolkitRpc`**, **`formatNativeDexToolkitPreflightForUi`**, **`buildNativeCpPoolSwapExpressTx`**, **`buildNativeDexMultihopSwapExpressTxFromRoute128`** / **`160`**, **`applyNativeDexMultihopSimulationToContractCallTx`** (`nativeDexSeamless.ts`); wallet copy **`BOING_WALLET_RPC_METHODS_NATIVE_DAPP`**, **`explainEthSendTransactionInsufficientForBoingNativeCall`**, **`connectInjectedBoingWallet`**, **`mapInjectedProviderErrorToUiMessage`** (`walletProvider.ts`)
+  - **CP routing + aggregation (off-chain)** — **`quoteCpPoolSwap`**, **`rankDirectCpPools`**, **`findBestCpRoutes`**, **`pickFirstMultihopCpRoute`**, **`uniqueSortedTokenHex32FromCpRoute`**, **`minOutFloorAfterSlippageBps`**, **`encodeNativeDexMultihopRouterCalldata*FromRoute`**, **`quoteCpEvenSplitAcrossDirectPools`**, **`hydrateCpPoolVenuesFromRpc`**, **`fetchCpRoutingFromDirectoryLogs`** (`nativeDexRouting.ts`); **`buildNativeDexMultihopRouterAccessList`**, **`mergeNativeDexMultihopRouterAccessListWithSimulation`** (`nativeAmmPool.ts`)
+  - **CREATE2 address prediction** — **`predictCreate2ContractAddress`**, **`predictNativeCpPoolCreate2Address`** … **`predictNativeCpPoolV5Create2Address`**, **`nativeCpPoolCreate2SaltV1Hex`** … **`nativeCpPoolCreate2SaltV5Hex`**, **`NATIVE_CP_POOL_CREATE2_SALT_V1`** … **`V5`** (`create2.ts`; matches `boing_primitives::create2_contract_address` / `native_amm.rs`; see [NATIVE-AMM-CALLDATA.md](../docs/NATIVE-AMM-CALLDATA.md) § CREATE2)
+  - **Indexer-scale reads** — **`getIndexerChainTips`** / **`clampIndexerHeightRange`** / **`planIndexerChainTipsWithFallback`** / **`planIndexerCatchUp`** (`indexerSync.ts`; fallback when **`boing_getSyncState`** is **-32601**); **`fetchBlocksWithReceiptsForHeightRange`** (replay path: full blocks + receipts; demos: [fetch-blocks-range.mjs](../examples/native-boing-tutorial/scripts/fetch-blocks-range.mjs), [indexer-ingest-tick.mjs](../examples/native-boing-tutorial/scripts/indexer-ingest-tick.mjs)); **`summarizeIndexerFetchGaps`**, **`mergeInclusiveHeightRanges`**, **`unionInclusiveHeightRanges`**, **`subtractInclusiveRangeFromRanges`**, **`blockHeightGapRowsForInsert`**, **`nextContiguousIndexedHeightAfterOmittedFetch`** (`indexerBatch.ts`, `indexerGaps.ts`; pruned gaps, D1 row shapes, archive backfill subtraction); `getLogsChunked` / `planLogBlockChunks` (≤128-block spans per [RPC-API-SPEC.md](../docs/RPC-API-SPEC.md)); optional **`maxConcurrent`** on chunked logs and height-range fetches; **`mapWithConcurrencyLimit`**; **`flattenReceiptsFromBundles`**; `fetchReceiptsForBlockHeight`; **`fetchReceiptsForHeightRange`** (optional `onMissingBlock: 'omit'`) — ingestion pseudo-flow: [INDEXER-RECEIPT-AND-LOG-INGESTION.md](../docs/INDEXER-RECEIPT-AND-LOG-INGESTION.md); example DDL: [tools/observer-indexer-schema.sql](../tools/observer-indexer-schema.sql); JSON + SQLite ingest: [examples/observer-ingest-reference](../examples/observer-ingest-reference/) (`ingest-tick`, **`ingest-sqlite-tick`** + **`BOING_SQLITE_PATH`**); D1 cron sample: [examples/observer-d1-worker](../examples/observer-d1-worker/); backlog: [NEXT-STEPS-FUTURE-WORK.md](../docs/NEXT-STEPS-FUTURE-WORK.md)
+  - **Fixed contract submitter** — `createNativeContractSubmitter({ client, secretKey32, senderHex, contractHex, accessList? })` → `.submitCalldata(bytes)`
+  - `registerDappMetrics(hexContract, hexOwner)`, `submitIntent(hexSignedIntent)`
+  - `qaCheck(hexBytecode, purposeCategory?, descriptionHash?, assetName?, assetSymbol?)` — pre-flight QA without submitting (same param order as node `boing_qaCheck`)
+  - `qaPoolList()`, `qaPoolConfig()`, `qaPoolVote(txHashHex, voterHex, vote)` — governance QA pool for Unsure deploys
+  - `faucetRequest(hexAccountId)` — testnet only
+- **BoingRpcError** — `code`, `message`, `data`, `method`; `isQaRejected`, `isQaPendingPool`, `pendingPoolTxHash`, `isQaPoolDisabled`, `isQaPoolFull`, `isQaPoolDeployerCap`, `qaData`; `toString()` for logging.
+- **Hex helpers** — `ensureHex`, `bytesToHex`, `hexToBytes`, `accountIdToHex`, `hexToAccountId`, `validateHex32`, **`isBoingNativeAccountIdHex`** (32-byte account id check for multi-wallet wizards).
+
+All 32-byte IDs (account, hash) are hex strings with or without `0x` prefix. Invalid hex or wrong length throws before the request.
+
+## Submitting transactions
+
+The node expects **hex-encoded bincode-serialized `SignedTransaction`**. Encoding matches Rust `boing-primitives` (bincode 1.3); see [BOING-SIGNED-TRANSACTION-ENCODING.md](../docs/BOING-SIGNED-TRANSACTION-ENCODING.md).
+
+**Options:**
+
+1. **TypeScript (Node or bundler)** — build + sign with a 32-byte Ed25519 secret key:
+
+```ts
+import {
+  createClient,
+  fetchNextNonce,
+  buildTransferTransaction,
+  signTransactionInput,
+} from 'boing-sdk';
+
+const client = createClient('http://localhost:8545');
+const senderHex = '0x' + '<64-hex of public key>';
+const secret32 = new Uint8Array(32); // your signing seed / secret key bytes
+const nonce = await fetchNextNonce(client, senderHex);
+const tx = buildTransferTransaction({
+  nonce,
+  senderHex,
+  toHex: '0x' + '<64-hex recipient>',
+  amount: 1n,
+});
+const signedHex = await signTransactionInput(tx, secret32);
+await client.simulateTransaction(signedHex);
+await client.submitTransaction(signedHex);
+```
+
+2. **Injected wallet** — `boing_sendTransaction` / `boing_signTransaction` in **Boing Express** ([BOING-EXPRESS-WALLET.md](../docs/BOING-EXPRESS-WALLET.md)).
+
+3. **Rust CLI** — `cargo run -p boing-cli -- …` for local dev.
+
+4. **Custom signer** — `signTransactionInputWithSigner(tx, async (hash) => …)` (must return 64-byte Ed25519 signature over `hash`).
+
+**Protocol QA:** Contract deploys are checked in the mempool (`boing_qa`). Use `qaCheck` before submit and purpose-bearing deploy types from the wallet. See [QUALITY-ASSURANCE-NETWORK.md](../docs/QUALITY-ASSURANCE-NETWORK.md).
+
+**dApp checklist:** [BOING-DAPP-INTEGRATION.md](../docs/BOING-DAPP-INTEGRATION.md).
+
+See [RPC-API-SPEC.md](../docs/RPC-API-SPEC.md), [BUILD-ROADMAP.md](../docs/BUILD-ROADMAP.md), and [BOING-VM-CAPABILITY-PARITY-ROADMAP.md](../docs/BOING-VM-CAPABILITY-PARITY-ROADMAP.md).
+
+## Simulate → access list → submit (P4)
+
+Use **`submitTransferWithSimulationRetry`**, **`submitContractCallWithSimulationRetry`**, or **`submitDeployWithPurposeFlow`** so the node can widen `access_list` when `boing_simulateTransaction` returns `access_list_covers_suggestion: false` (merges `suggested_access_list` via `mergeAccessListWithSimulation`).
+
+```ts
+import {
+  createClient,
+  submitTransferWithSimulationRetry,
+  explainBoingRpcError,
+  senderHexFromSecretKey,
+  hexToBytes,
+} from 'boing-sdk';
+
+const client = createClient(process.env.BOING_RPC_URL ?? 'http://127.0.0.1:8545');
+const secret = hexToBytes(process.env.BOING_SECRET_HEX!); // 0x + 64 hex
+const senderHex = await senderHexFromSecretKey(secret);
+
+try {
+  const { tx_hash, lastSimulation, attempts } = await submitTransferWithSimulationRetry({
+    client,
+    secretKey32: secret,
+    senderHex,
+    toHex: process.env.BOING_TO_HEX!,
+    amount: 10n,
+  });
+  console.log({ tx_hash, gas: lastSimulation.gas_used, attempts });
+} catch (e) {
+  console.error(explainBoingRpcError(e));
+}
+```
+
+Deploy path runs **`boing_qaCheck`** first; **`reject`** throws `BoingRpcError` with `isQaRejected`. On **`submitTransaction`**, catch **`BoingRpcError`** for mempool QA (**-32050**), pool (**-32051**), and pool caps (**-32054..-32056**). Code reference: [BOING-RPC-ERROR-CODES-FOR-DAPPS.md](../docs/BOING-RPC-ERROR-CODES-FOR-DAPPS.md).
+
+**Canonical scripts:** [examples/native-boing-tutorial](../examples/native-boing-tutorial/) (`transfer`, `contract-call`, `deploy-minimal`).
+
+## API additions (transaction flows)
+
+- `senderHexFromSecretKey(secret32)` — derive `AccountId` hex from signing seed.
+- `submitTransferWithSimulationRetry`, `submitContractCallWithSimulationRetry`, `submitDeployWithPurposeFlow` — see `submitFlow.ts`.
+- `SimulationFailedError` — simulation failed without an access-list retry path.
+- `explainBoingRpcError(e)` — human-readable string for `BoingRpcError` and QA pool codes.
+
+## Tests
+
+```bash
+cd boing-sdk && npm install && npm test
+```
+
+Golden vectors are tied to `cargo run -p boing-primitives --example dump_bincode`.
+
+## Planned
+
+- CLI auto-completion, contract templates. See [DEVELOPMENT-AND-ENHANCEMENTS.md](../docs/DEVELOPMENT-AND-ENHANCEMENTS.md).

package/dist/accessList.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Access list helpers — pair with `boing_simulateTransaction` hints (Track A).
+ */
+import type { AccessListJson, SimulateResult } from './types.js';
+/** Deduped sorted union of hex account ids (read ∪ write from suggestion). */
+export declare function accountsFromSuggestedAccessList(s: AccessListJson): string[];
+/**
+ * Merge explicit read/write lists with simulation `suggested_access_list` (union per side).
+ * Use after a successful or failed simulate to widen lists toward the heuristic minimum.
+ */
+export declare function mergeAccessListWithSimulation(read: string[], write: string[], sim: SimulateResult): {
+    read: string[];
+    write: string[];
+};
+/** Build `AccessList`-shaped object from simulation only (both sides = union of suggested read+write). */
+export declare function accessListFromSimulation(sim: SimulateResult): {
+    read: string[];
+    write: string[];
+} | null;
+/** True if simulation reports the signed tx’s access list covers the heuristic minimum. */
+export declare function simulationCoversSuggestedAccessList(sim: SimulateResult): boolean;
+//# sourceMappingURL=accessList.d.ts.map

package/dist/accessList.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"accessList.d.ts","sourceRoot":"","sources":["../src/accessList.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAOjE,8EAA8E;AAC9E,wBAAgB,+BAA+B,CAAC,CAAC,EAAE,cAAc,GAAG,MAAM,EAAE,CAK3E;AAED;;;GAGG;AACH,wBAAgB,6BAA6B,CAC3C,IAAI,EAAE,MAAM,EAAE,EACd,KAAK,EAAE,MAAM,EAAE,EACf,GAAG,EAAE,cAAc,GAClB;IAAE,IAAI,EAAE,MAAM,EAAE,CAAC;IAAC,KAAK,EAAE,MAAM,EAAE,CAAA;CAAE,CAUrC;AAED,0GAA0G;AAC1G,wBAAgB,wBAAwB,CAAC,GAAG,EAAE,cAAc,GAAG;IAAE,IAAI,EAAE,MAAM,EAAE,CAAC;IAAC,KAAK,EAAE,MAAM,EAAE,CAAA;CAAE,GAAG,IAAI,CAKxG;AAED,2FAA2F;AAC3F,wBAAgB,mCAAmC,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAEhF"}

package/dist/accessList.js

@@ -0,0 +1,45 @@
+/**
+ * Access list helpers — pair with `boing_simulateTransaction` hints (Track A).
+ */
+import { validateHex32 } from './hex.js';
+function normHex32(s) {
+    return validateHex32(s);
+}
+/** Deduped sorted union of hex account ids (read ∪ write from suggestion). */
+export function accountsFromSuggestedAccessList(s) {
+    const set = new Set();
+    for (const x of s.read)
+        set.add(normHex32(x));
+    for (const x of s.write)
+        set.add(normHex32(x));
+    return [...set].sort();
+}
+/**
+ * Merge explicit read/write lists with simulation `suggested_access_list` (union per side).
+ * Use after a successful or failed simulate to widen lists toward the heuristic minimum.
+ */
+export function mergeAccessListWithSimulation(read, write, sim) {
+    const sug = sim.suggested_access_list;
+    if (!sug) {
+        return { read: [...read], write: [...write] };
+    }
+    const r = new Set(read.map(normHex32));
+    const w = new Set(write.map(normHex32));
+    for (const x of sug.read)
+        r.add(normHex32(x));
+    for (const x of sug.write)
+        w.add(normHex32(x));
+    return { read: [...r], write: [...w] };
+}
+/** Build `AccessList`-shaped object from simulation only (both sides = union of suggested read+write). */
+export function accessListFromSimulation(sim) {
+    const sug = sim.suggested_access_list;
+    if (!sug)
+        return null;
+    const ids = accountsFromSuggestedAccessList(sug);
+    return { read: ids, write: ids };
+}
+/** True if simulation reports the signed tx’s access list covers the heuristic minimum. */
+export function simulationCoversSuggestedAccessList(sim) {
+    return sim.access_list_covers_suggestion === true;
+}

package/dist/bincode.d.ts

@@ -0,0 +1,92 @@
+/**
+ * bincode 1.3 layout matching `crates/boing-primitives` (serde derive).
+ * Used for `Transaction`, `SignedTransaction`, and signable hash preimage.
+ * @see docs/BOING-SIGNED-TRANSACTION-ENCODING.md
+ */
+/** Payload variants — discriminant u32 LE must match Rust enum declaration order. */
+export declare const PayloadVariant: {
+    readonly Transfer: 0;
+    readonly ContractCall: 1;
+    readonly ContractDeploy: 2;
+    readonly ContractDeployWithPurpose: 3;
+    readonly ContractDeployWithPurposeAndMetadata: 4;
+    readonly Bond: 5;
+    readonly Unbond: 6;
+};
+export declare function concatBytes(...parts: Uint8Array[]): Uint8Array;
+export declare function writeU32Le(n: number): Uint8Array;
+export declare function writeU64Le(n: bigint): Uint8Array;
+export declare function writeU128Le(n: bigint): Uint8Array;
+/** `AccessList` — two length-prefixed vectors of 32-byte accounts. */
+export declare function encodeAccessList(read: Uint8Array[], write: Uint8Array[]): Uint8Array;
+/** `Vec<u8>` — u64 LE length + raw bytes. */
+export declare function encodeByteVec(data: Uint8Array): Uint8Array;
+/** UTF-8 string: u64 LE byte length + UTF-8 payload. */
+export declare function encodeBincodeString(s: string): Uint8Array;
+/** `Option<[u8;32]>` — tag u8 + optional fixed 32 bytes. */
+export declare function encodeOptionFixed32(salt: Uint8Array | null | undefined): Uint8Array;
+/** `Option<Vec<u8>>` — tag u8 + optional vec. */
+export declare function encodeOptionByteVec(opt: Uint8Array | null | undefined): Uint8Array;
+/** `Option<String>` — tag u8 + optional string. */
+export declare function encodeOptionString(opt: string | null | undefined): Uint8Array;
+export type TransactionPayloadInput = {
+    kind: 'transfer';
+    to: Uint8Array;
+    amount: bigint;
+} | {
+    kind: 'contractCall';
+    contract: Uint8Array;
+    calldata: Uint8Array;
+} | {
+    kind: 'contractDeploy';
+    bytecode: Uint8Array;
+    create2Salt?: Uint8Array | null;
+} | {
+    kind: 'contractDeployWithPurpose';
+    bytecode: Uint8Array;
+    purposeCategory: string;
+    descriptionHash?: Uint8Array | null;
+    create2Salt?: Uint8Array | null;
+} | {
+    kind: 'contractDeployWithPurposeAndMetadata';
+    bytecode: Uint8Array;
+    purposeCategory: string;
+    descriptionHash?: Uint8Array | null;
+    assetName?: string | null;
+    assetSymbol?: string | null;
+    create2Salt?: Uint8Array | null;
+} | {
+    kind: 'bond';
+    amount: bigint;
+} | {
+    kind: 'unbond';
+    amount: bigint;
+};
+export declare function encodeTransactionPayload(payload: TransactionPayloadInput): Uint8Array;
+export interface TransactionInput {
+    nonce: bigint;
+    sender: Uint8Array;
+    payload: TransactionPayloadInput;
+    accessList: {
+        read: Uint8Array[];
+        write: Uint8Array[];
+    };
+}
+export declare function encodeTransaction(tx: TransactionInput): Uint8Array;
+/** `Signature` — serde `serialize_bytes` → u64 LE length + 64 raw bytes. */
+export declare function encodeSignature(signature64: Uint8Array): Uint8Array;
+export declare function encodeSignedTransaction(tx: TransactionInput, signature64: Uint8Array): Uint8Array;
+/**
+ * BLAKE3 hash signed by the node for `SignedTransaction` verification.
+ * preimage = nonce_le || sender(32) || bincode(payload) || bincode(access_list)
+ */
+export declare function signableTransactionHash(tx: TransactionInput): Uint8Array;
+/**
+ * Derives the mempool / receipt **`tx_id`** (32-byte BLAKE3) from **`0x` + bincode(`SignedTransaction`)** hex
+ * returned by Boing Express after `boing_signTransaction`. Matches **`Transaction::id()`** / **`boing_getTransactionReceipt`** param
+ * per [RPC-API-SPEC.md](https://github.com/Boing-Network/boing.network/blob/main/docs/RPC-API-SPEC.md) (signable body excludes the trailing serde `Signature` block).
+ *
+ * @throws if hex is invalid or the trailing signature length field is not 64
+ */
+export declare function transactionIdFromSignedTransactionHex(signedTxHex: string): string;
+//# sourceMappingURL=bincode.d.ts.map

package/dist/bincode.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bincode.d.ts","sourceRoot":"","sources":["../src/bincode.ts"],"names":[],"mappings":"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"}

package/dist/bincode.js

@@ -0,0 +1,154 @@
+/**
+ * bincode 1.3 layout matching `crates/boing-primitives` (serde derive).
+ * Used for `Transaction`, `SignedTransaction`, and signable hash preimage.
+ * @see docs/BOING-SIGNED-TRANSACTION-ENCODING.md
+ */
+import { blake3 } from '@noble/hashes/blake3';
+import { bytesToHex, ensureHex, hexToBytes } from './hex.js';
+/** Payload variants — discriminant u32 LE must match Rust enum declaration order. */
+export const PayloadVariant = {
+    Transfer: 0,
+    ContractCall: 1,
+    ContractDeploy: 2,
+    ContractDeployWithPurpose: 3,
+    ContractDeployWithPurposeAndMetadata: 4,
+    Bond: 5,
+    Unbond: 6,
+};
+export 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;
+}
+export function writeU32Le(n) {
+    const b = new Uint8Array(4);
+    new DataView(b.buffer).setUint32(0, n >>> 0, true);
+    return b;
+}
+export function writeU64Le(n) {
+    const b = new Uint8Array(8);
+    new DataView(b.buffer).setBigUint64(0, n, true);
+    return b;
+}
+export function writeU128Le(n) {
+    const b = new Uint8Array(16);
+    let x = n;
+    for (let i = 0; i < 16; i++) {
+        b[i] = Number(x & 0xffn);
+        x >>= 8n;
+    }
+    return b;
+}
+function encodeVecAccountIds(ids) {
+    const parts = [writeU64Le(BigInt(ids.length))];
+    for (const id of ids) {
+        if (id.length !== 32)
+            throw new Error('Each AccountId must be exactly 32 bytes');
+        parts.push(id);
+    }
+    return concatBytes(...parts);
+}
+/** `AccessList` — two length-prefixed vectors of 32-byte accounts. */
+export function encodeAccessList(read, write) {
+    return concatBytes(encodeVecAccountIds(read), encodeVecAccountIds(write));
+}
+/** `Vec<u8>` — u64 LE length + raw bytes. */
+export function encodeByteVec(data) {
+    return concatBytes(writeU64Le(BigInt(data.length)), data);
+}
+/** UTF-8 string: u64 LE byte length + UTF-8 payload. */
+export function encodeBincodeString(s) {
+    const utf8 = new TextEncoder().encode(s);
+    return concatBytes(writeU64Le(BigInt(utf8.length)), utf8);
+}
+/** `Option<[u8;32]>` — tag u8 + optional fixed 32 bytes. */
+export function encodeOptionFixed32(salt) {
+    if (salt == null)
+        return new Uint8Array([0]);
+    if (salt.length !== 32)
+        throw new Error('create2_salt must be 32 bytes');
+    return concatBytes(new Uint8Array([1]), salt);
+}
+/** `Option<Vec<u8>>` — tag u8 + optional vec. */
+export function encodeOptionByteVec(opt) {
+    if (opt == null)
+        return new Uint8Array([0]);
+    return concatBytes(new Uint8Array([1]), encodeByteVec(opt));
+}
+/** `Option<String>` — tag u8 + optional string. */
+export function encodeOptionString(opt) {
+    if (opt == null)
+        return new Uint8Array([0]);
+    return concatBytes(new Uint8Array([1]), encodeBincodeString(opt));
+}
+export function encodeTransactionPayload(payload) {
+    switch (payload.kind) {
+        case 'transfer':
+            return concatBytes(writeU32Le(PayloadVariant.Transfer), payload.to, writeU128Le(payload.amount));
+        case 'contractCall':
+            return concatBytes(writeU32Le(PayloadVariant.ContractCall), payload.contract, encodeByteVec(payload.calldata));
+        case 'contractDeploy':
+            return concatBytes(writeU32Le(PayloadVariant.ContractDeploy), encodeByteVec(payload.bytecode), encodeOptionFixed32(payload.create2Salt ?? null));
+        case 'contractDeployWithPurpose':
+            return concatBytes(writeU32Le(PayloadVariant.ContractDeployWithPurpose), encodeByteVec(payload.bytecode), encodeBincodeString(payload.purposeCategory), encodeOptionByteVec(payload.descriptionHash ?? null), encodeOptionFixed32(payload.create2Salt ?? null));
+        case 'contractDeployWithPurposeAndMetadata':
+            return concatBytes(writeU32Le(PayloadVariant.ContractDeployWithPurposeAndMetadata), encodeByteVec(payload.bytecode), encodeBincodeString(payload.purposeCategory), encodeOptionByteVec(payload.descriptionHash ?? null), encodeOptionString(payload.assetName ?? null), encodeOptionString(payload.assetSymbol ?? null), encodeOptionFixed32(payload.create2Salt ?? null));
+        case 'bond':
+            return concatBytes(writeU32Le(PayloadVariant.Bond), writeU128Le(payload.amount));
+        case 'unbond':
+            return concatBytes(writeU32Le(PayloadVariant.Unbond), writeU128Le(payload.amount));
+        default: {
+            const _x = payload;
+            return _x;
+        }
+    }
+}
+export function encodeTransaction(tx) {
+    if (tx.sender.length !== 32)
+        throw new Error('sender must be 32 bytes');
+    return concatBytes(writeU64Le(tx.nonce), tx.sender, encodeTransactionPayload(tx.payload), encodeAccessList(tx.accessList.read, tx.accessList.write));
+}
+/** `Signature` — serde `serialize_bytes` → u64 LE length + 64 raw bytes. */
+export function encodeSignature(signature64) {
+    if (signature64.length !== 64)
+        throw new Error('Ed25519 signature must be 64 bytes');
+    return concatBytes(writeU64Le(64n), signature64);
+}
+export function encodeSignedTransaction(tx, signature64) {
+    return concatBytes(encodeTransaction(tx), encodeSignature(signature64));
+}
+/**
+ * BLAKE3 hash signed by the node for `SignedTransaction` verification.
+ * preimage = nonce_le || sender(32) || bincode(payload) || bincode(access_list)
+ */
+export function signableTransactionHash(tx) {
+    const preimage = concatBytes(writeU64Le(tx.nonce), tx.sender, encodeTransactionPayload(tx.payload), encodeAccessList(tx.accessList.read, tx.accessList.write));
+    return blake3(preimage);
+}
+const SIGNED_TX_SIGNATURE_TRAIL_BYTES = 8 + 64;
+/**
+ * Derives the mempool / receipt **`tx_id`** (32-byte BLAKE3) from **`0x` + bincode(`SignedTransaction`)** hex
+ * returned by Boing Express after `boing_signTransaction`. Matches **`Transaction::id()`** / **`boing_getTransactionReceipt`** param
+ * per [RPC-API-SPEC.md](https://github.com/Boing-Network/boing.network/blob/main/docs/RPC-API-SPEC.md) (signable body excludes the trailing serde `Signature` block).
+ *
+ * @throws if hex is invalid or the trailing signature length field is not 64
+ */
+export function transactionIdFromSignedTransactionHex(signedTxHex) {
+    const bytes = hexToBytes(ensureHex(signedTxHex));
+    if (bytes.length < SIGNED_TX_SIGNATURE_TRAIL_BYTES + 1) {
+        throw new Error('Signed transaction bytes too short to derive tx_id');
+    }
+    const sigLenOffset = bytes.length - SIGNED_TX_SIGNATURE_TRAIL_BYTES;
+    const dv = new DataView(bytes.buffer, bytes.byteOffset + sigLenOffset, 8);
+    const sigLen = dv.getBigUint64(0, true);
+    if (sigLen !== 64n) {
+        throw new Error(`Unexpected serde signature length field: ${sigLen} (expected 64)`);
+    }
+    const txBody = bytes.subarray(0, sigLenOffset);
+    return bytesToHex(blake3(txBody));
+}