@black-market/sdk 0.5.2 → 0.6.0

package/docs/launch-lifecycle.md

@@ -7,6 +7,16 @@ The canonical authorities are the registry/certification/adapter/config contract
 in the protocol repository. Plan identity is `LaunchPlanV1`. Pool-bound V4 uses **config 5**,
 canonical Abyss uses **config 1**, and generic current shared-V4 support uses **config 4**.
 
+## 0.6.0 admission changes
+
+Optional caller policy no longer substitutes for, or gates, actual sequential execution proof.
+Results distinguish `executionProof`, `protocolFit`, and `transportPreflight`. Robinhood
+admission reads pinned Nitro compute limits and poster budgets, then requires native exact
+validated replay. `buildNextTransaction` optionally preflights the immediate next envelope
+through `submissionClient`. Deployment addresses, lifecycle plan/schema domains, profile
+capabilities and explicit atomic/staged behavior are unchanged.
+
+
 ## Deployed infrastructure
 
 Robinhood mainnet (`4663`) selects the mined `pool-launch-v1` deployment captured at block
@@ -72,7 +82,7 @@ Validation uses `validateV4LifecycleMarket`; the collector factory getter is
 | `planLaunch({client, account, plan, mode, limits?, fork?, receipts?, confirmations?})` | Validates domain/funding/admission and canonical progress, records the exact atomic attempt, and reviews only the explicitly selected mode. |
 | `simulateLaunchPlan({client, planned, limits?, fork?, receipts?, confirmations?})` | Rereads canonical state and proves remaining work. Preserves receipt evidence, economics and selected mode. |
 | `readLaunchProgress({client, planned, receipts?, confirmations?})` | Confirmation-bound canonical state, latest head, receipt/replacement/reorg status, account-nonce safety and actual prepared market/live state. |
-| `buildNextTransaction({client, planned, limits?, fork?, receipts?, confirmations?, action?})` | Rereads progress, constraints and stateful proof before returning one admitted transaction. `action: "cancel"` uses the stored commitment without requiring fresh adapter/profile admission. Terminal launches return `undefined`. |
+| `buildNextTransaction({client, planned, submissionClient?, limits?, fork?, receipts?, confirmations?, action?})` | Rereads progress, constraints and stateful proof before returning one admitted transaction. Optional `submissionClient` adds read-only exact immediate envelope preflight. `action: "cancel"` uses the stored commitment without requiring fresh adapter/profile admission. Terminal launches return `undefined`. |
 
 Clients may be viem public clients or raw `request({method,params})` RPC clients. Transport, wallet, signing and durable storage are application-owned. `PlannedLaunch` contains bigint values and live limit callbacks: persist `serializeLaunchPlan(plan)`, explicit execution mode, confirmation policy and receipt references, not the entire object.
 
@@ -186,15 +196,80 @@ No automatic atomic-to-staged fallback exists. Obtain separate consent to review
 
 ## Execution constraints and stateful simulation
 
-Admission requires current `chainGasLimit`, `rpcGasLimit`, `accountGasLimit` and `maxCalldataBytes`; block gas limit alone cannot fill missing transaction/RPC/account policy. Use a `LifecycleLimitSource` callback whose returned chain/account/core/observed block/hash match the requested pinned context and actual provider-owned policy. Static supplied facts are only current at that exact context; relabeling stale limits is not proof.
-
-The ceiling is the minimum of block and explicit transaction caps. Headroom defaults to 1,500 bps, bounded 0–10,000. The measurement pass is followed by execution at exact returned gas/fee limits. Fork execution uses gross sequential estimates rather than refund-reduced receipt gas as an executable minimum. Transactions expose `estimate.executionFee`, optional `dataFee/totalFee` and `feeConfidence: "execution-and-data" | "execution-only"`; missing rollup/data fee is not an invented all-in estimate. Limits are refreshed before every next transaction.
+Optional `chainGasLimit`, `rpcGasLimit`, `accountGasLimit`, `maxCalldataBytes` and
+`maxSimulationGas` tighten admission when supplied. Missing policy remains explicit in
+`limits.unknownExecutionConstraints`/`unknownConstraints`; it does not reject an otherwise
+proved exact sequence or invent a provider/account cap. No policy service is required.
+A `LifecycleLimitSource` callback receives the canonical chain/account/core/block context.
+Any supplied provenance must match it; stale/mismatched/malformed facts or a failed supplied
+resolver reject rather than disappearing into optional uncertainty. Gas caps are positive
+exact uint64 `bigint`; calldata is a positive safe integer byte count.
+Reviewed gas envelopes are positive uint64 too; zero-metering observations cannot admit
+a zero-gas transaction. Headroom calculations retain wide exact bigint intermediates.
+
+Headroom defaults to 1,500 bps, bounded 0–10,000. Generic EVM admission uses the pinned
+bounded header and supplied total-envelope restrictions plus actual validated RPC proof.
+It reports an absent independent per-transaction cutoff honestly, without importing a
+universal Ethereum cutoff. `executionGasCeiling` and `transactionGasCeiling` are equal on
+generic EVM. The permissive measurement pass never admits a launch: replay must execute
+the exact returned gas/fee envelope, every postcondition and all ordered buy bounds.
+Fork discovery uses gross sequential estimates, not refund-reduced receipt gas as an
+executable minimum. Explicit ceiling recovery preserves gasleft/EIP-150 validation and
+carries that successfully replayed ceiling, never a smaller unproved envelope.
 
 Sequential backends:
 
-1. `eth_simulateV1`: actual ordered transactions, state carried between synthetic blocks, exact gas-envelope verification, core returns/events and ordered buy bounds.
-2. Explicit separate disposable loopback fork: snapshot-isolated real transactions, exact pinned chain/header identity, canonical poststate/allowances and cleanup. Source RPC stays read-only.
-3. Neither: unavailable/provisional/unadmitted; no executable next transaction.
+1. `eth_simulateV1`: ordered transactions with state carried between synthetic blocks, followed by exact validated replay.
+2. Generic EVM only: explicitly separate disposable loopback fork, with snapshot-isolated real transactions, pinned chain/header identity, canonical poststate/allowances and mandatory cleanup. Source RPC stays read-only.
+3. Neither: unavailable/provisional/unadmitted; disconnected dependent `eth_call` estimates cannot create an executable next transaction.
+
+Every proof completion rechecks the planned source chain ID and pinned block hash. A
+changed source transport cannot retain admission merely by returning the same fork hash.
+
+### Nitro compute and poster accounting
+
+For Robinhood `4663`, each pinned context reads ArbSys (`0x64`).`arbOSVersion` and ArbGasInfo
+(`0x6c`).`getMaxTxGasLimit`/`getMaxBlockGasLimit`. ArbSys returns **55 + logical ArbOS version**;
+the raw value must be at least 105, and `limits.arbOSVersion` reports logical version 50+.
+The positive validated getter values establish `maxTxComputeGas`, `maxBlockComputeGas`
+and their minimum `executionGasCeiling`. Failed reads never fall back to the huge Nitro
+header or a hard-coded 32M. `limits.protocol` identifies `"nitro"` or `"evm"`.
+
+Nitro `transactionGasCeiling`, when present, is the minimum of supplied **complete**
+chain/RPC/account gas-envelope restrictions. It is independent of the compute ceiling:
+an admitted transaction's `gas` may exceed `executionGasCeiling` because poster gas is
+not compute. NodeInterface (`0xc8`).`gasEstimateL1Component` is read at the same pinned
+block with the exact sender, destination, calldata and value, including future dependent
+steps whose execution cannot yet be independently estimated. It budgets poster gas only.
+The buffered compute-discovery envelope plus buffered poster budget is carried into
+exact validated replay; an approximate poster quote is never subtracted from total
+gas use to certify exact compute fit.
+
+A separate pinned validated simulation probes all three ArbOS/version/getter values
+against the canonical observations. Only that isolated capability probe temporarily
+overrides the probe account's balance, so probe-only fees cannot reject an exactly-funded
+launch. Probe funding/nonce changes, steps and fees never enter real plan measurement,
+replay, postconditions or affordability, which use actual payer state. The native Nitro
+`eth_simulateV1` commit-mode ArbOS charging hook removes the **actual** poster charge and
+holds excess compute gas before execution. Successful exact replay and postconditions,
+not the quote or permissive pass, prove fit. Missing native metering or a mismatched
+probe fails closed. Generic Anvil/Hardhat forks cannot certify Nitro execution.
+
+Transactions expose `estimate.executionFee`, optional external `dataFee`/`totalFee` and
+`feeConfidence: "execution-and-data" | "execution-only"`. On Nitro, `posterGas`/`posterFee`
+are the estimated buffered allocation **inside** `gasLimit`, `dataFeeIncludedInGas` is
+true, `dataFee` is zero and `totalFee` equals `gasLimit * gasPrice`. Affordability counts
+this complete envelope once; adding `posterFee` again would double-charge. A caller
+`estimateDataFee` is therefore rejected on Nitro. On generic EVM it retains its original
+semantics as a validated external fee added outside execution gas. Missing external fee
+does not manufacture an all-in estimate. All observations and limits refresh for build-next.
+
+Source references: [ArbSys version encoding](https://github.com/OffchainLabs/nitro-precompile-interfaces/blob/main/ArbSys.sol),
+[ArbGasInfo compute getters](https://github.com/OffchainLabs/nitro-precompile-interfaces/blob/main/ArbGasInfo.sol),
+[native simulate commit mode](https://github.com/OffchainLabs/go-ethereum/blob/51d716ccf8293072077feb9764d63d73f5e4ff20/internal/ethapi/simulate.go),
+[ArbOS actual poster/compute charging](https://github.com/OffchainLabs/nitro/blob/ccc5c828d9ea22f161efc784bac4d4a6559b7e59/arbos/tx_processor.go),
+and [NodeInterface poster estimate](https://github.com/OffchainLabs/nitro-contracts/blob/main/src/node-interface/NodeInterface.sol).
+These describe backend semantics, not evidence of a live launch executed by this SDK release.
 
 Atomic/activation simulation `steps[].returnData` encodes the actual `LaunchReceiptV1` tuple. Controlled-fork output is reconstructed from matching real activation/buy receipt logs and canonical state, never geometric estimates or echoed request minima. `tokenOut` and `quoteSpent` are parallel arrays indexed by ordered buys.
 
@@ -206,12 +281,48 @@ const fork = createControlledLifecycleFork({
 const planned = await planLaunch({client, account: plan.creator, plan, mode: "staged", limits, fork});
 ```
 
-The fork endpoint must be distinct/loopback, including localhost/IP aliases and effective port. Anvil reset/impersonation is default; disposable Hardhat may explicitly use its reset method/impersonation. Never pass the source client as a fork or use a live unlocked wallet as a disposable backend. Operators own exclusive fork access during proof. Controlled-local policy does not prove live provider/account admission or imply bound topology is a gas optimization.
+The fork endpoint must be distinct/loopback, including localhost/IP aliases and effective port. Anvil reset/impersonation is default; disposable Hardhat may explicitly use its reset method/impersonation. Never pass the source client as a fork or use a live unlocked wallet as a disposable backend. Operators own exclusive fork access during generic EVM proof. Controlled-local execution does not prove wallet submission acceptance and cannot certify Nitro metering or imply bound topology is a gas optimization.
 
 ## Wallet submission and canonical recovery
 
 The SDK never signs. Before **every** approval/reset/core/predeploy/cancel signature, compare the wallet's configured chain (if any) and fresh connected `getChainId()` with the returned `next.chainId`. Failure/invalid identity is a refusal. Supply a matching explicit viem Chain descriptor; do not pass `chain: null` or disable wallet chain checks. Send exact `from/to/data/value/gas/gasPrice`, not a cached estimate or wallet batch.
 
+Simulation and `next.admission` carry flat, independent proof outcomes:
+
+| Field | Values | Scope |
+| --- | --- | --- |
+| `executionProof` | `"proved"`, `"failed"`, `"unavailable"` | Complete stateful exact-envelope execution and postconditions, never permissive measurement alone. |
+| `protocolFit` | `"proved"`, `"failed"`, `"unknown"` | Applicable proven protocol and known tightening restrictions. Missing optional policy remains separately disclosed. |
+| `transportPreflight` | `"not-requested"`, `"passed"`, `"failed"` | Immediate exact next-transaction acceptance estimate on the supplied submission RPC. |
+
+`admitted` means the current exact sequence is proved to fit and affordable; it is
+not guaranteed wallet submission or future execution. Admission reuses simulation
+`blockNumber`, `blockHash`, `account`, `chainId` and `limits`. Plans never preflight
+future dependent transactions against state that does not exist.
+
+```ts
+const planned = await planLaunch({ client, account: plan.creator, plan, mode: "atomic" });
+const submissionClient = {
+  request: ({ method, params }) => activeProvider.request({ method, params }),
+};
+const next = await buildNextTransaction({ client, planned, receipts, submissionClient });
+// Freshly verify the active wallet account/connector/chain again, then review/sign next.
+```
+
+When supplied, `submissionClient` receives only read-only `eth_chainId` and
+`eth_estimateGas` for the immediate next `from/to/data/value/gas/gasPrice` at `latest`.
+Its positive estimate must fit the reviewed gas exactly; gas is never silently enlarged.
+Chain identity is checked before and after estimation, and the source pinned hash/chain
+is rechecked before returning. Success sets `next.admission.transportPreflight` to
+`"passed"`. Refusal, unsupported RPC, malformed estimate, over-envelope estimate or
+chain drift raises `SUBMISSION_PREFLIGHT_FAILED` without returning a transaction.
+The error's `simulation` retains execution admission and its canonical context, changing
+only transport outcome/reason to `"failed"`. Cancellation uses the same preflight.
+Without a submission client, `"not-requested"` remains honest and no wallet RPC is implied.
+Applications still own fresh active account/provider guards around asynchronous work;
+a read-only preflight does not authenticate an active wallet or authorize a signature.
+
+
 Persist transaction hashes immediately. After receipt, retain `observedBlockNumber`, `observedBlockHash`, confirmation policy and, for replacements, original `transactionHash` plus effective `replacementHash`. A same-nonce self-transfer is replacement-cancelled, not launch completion. Removed observed blocks are reorged; status zero is reverted; a missing receipt at the unchanged observed block remains pending. Unknown hashes do not invent reorgs.
 
 `confirmations` is positive and defaults to 1. Progress anchors confirmed canonical and latest head hashes, compares confirmed/head/pending account nonces, and prevents ref-free reloads from advancing unconfirmed work. Pending receipts/state return no executable envelope (`RECEIPT_PENDING`/`UNCONFIRMED_STATE`). Reload the exact plan/mode/policy/receipt references; never trust a cached step counter. Market read failures are surfaced without removing adapter-independent cancellation.
@@ -310,13 +421,13 @@ never changes mode, drops positions/buys or overrides failed admission.
 Optional `NFT_BASE_URI` provides an ERC404 base URI you actually host; its default is
 empty, with real NFT units/mirror behavior but no claim of hosted NFT metadata.
 
-Optional `SIMULATION_RPC_URL` uses the canonical SDK controlled fork on a separate
-owned disposable loopback Anvil. Otherwise real native sequential `eth_simulateV1` is
-required. Only the simulation fork is reset/impersonated/reverted. Source RPC requests
-have a 120-second bound and are not retried. Default gas `16000000`, calldata `131072`
-and headroom `1000` bps are explicitly **EXAMPLE ceilings, not verified provider/account
-limits**; the chain cap is bounded by observed block gas limits. Environment overrides
-are documented in the example guide and remain subject to full SDK admission.
+The chain-4663 examples require native sequential Nitro `eth_simulateV1`; generic
+Anvil/Hardhat simulation is not an ArbOS compute/poster proof. Source RPC requests
+have a 120-second bound and are not retried. There are no invented default gas or
+calldata caps. Explicit environment restrictions only tighten the complete envelope;
+headroom defaults to 1,500 bps. SDK native pinned compute/poster reads and exact replay
+remain mandatory, and build-next uses the same source RPC as the read-only submission
+preflight before each local signature. Environment options are documented in the example guide.
 
 Execution rechecks chain/creator/destination and exact finalized calldata before each
 send. Exact admitted envelopes are signed locally; computed hashes and unsigned

package/examples/.env.example

@@ -5,16 +5,13 @@ LAUNCH_API_URL=
 
 # Optional: blank uses the SDK official Robinhood chain-4663 mainnet RPC.
 RPC_URL=
-# Optional: separate owned loopback Anvil used only for SDK controlled simulation.
-# Blank selects the actual RPC native eth_simulateV1 backend.
-SIMULATION_RPC_URL=
 # Optional ERC404 NFT metadata base URI that you actually host; blank means empty URI.
 NFT_BASE_URI=
 
-# Optional EXAMPLE ceilings, NOT verified provider/account limits.
-# Chain cap is also bounded by every observed block gas limit.
-# EXAMPLE_CHAIN_GAS_CAP=16000000
-# EXAMPLE_RPC_GAS_CAP=16000000
-# EXAMPLE_ACCOUNT_GAS_CAP=16000000
-# EXAMPLE_MAX_CALLDATA_BYTES=131072
-# EXAMPLE_HEADROOM_BPS=1000
+# Optional local tightening restrictions. Blank/unset means unknown, not refused.
+# Nitro protocol compute caps and poster budgeting are read natively at the pinned block.
+# EXAMPLE_CHAIN_GAS_CAP=
+# EXAMPLE_RPC_GAS_CAP=
+# EXAMPLE_ACCOUNT_GAS_CAP=
+# EXAMPLE_MAX_CALLDATA_BYTES=
+# EXAMPLE_HEADROOM_BPS=1500

package/examples/README.md

@@ -42,12 +42,15 @@ commitment before begin. `--receipts receipts.json` and `--confirmations N` rest
 canonical recovery context. The CLI never signs, submits source-chain transactions,
 uploads metadata, or publishes a launch. Modes never fall back silently.
 
-Executable admission additionally requires current matching execution-limit evidence
-(`--limits current-limits.json`) and sequential `eth_simulateV1`, or an explicitly
-supplied **separate disposable loopback fork** (`--fork-rpc URL`). Limits must include
-chain/account/core/observed-block/hash provenance and actual chain/RPC/account/calldata
-caps; encode bigint values as decimal strings. Missing facts produce provisional/refused
-admission, not invented provider/account policy. See the
+Executable admission requires actual stateful measurement and exact validated replay.
+`--limits current-limits.json` is optional tightening policy, not a required backend:
+missing caps stay explicit uncertainty, while supplied malformed/stale/mismatched
+provenance rejects. Encode bigint values as decimal strings. Robinhood `4663` reads
+pinned native Nitro compute/poster evidence and requires native `eth_simulateV1`.
+A **separate disposable loopback fork** (`--fork-rpc URL`) remains available for
+generic EVM, not as a Nitro metering substitute. Unsigned review reports
+`transportPreflight: "not-requested"` unless a consumer supplies its active submission
+RPC to build-next. See the
 [lifecycle guide](../docs/launch-lifecycle.md#execution-constraints-and-stateful-simulation).
 
 ## Real HTTP metadata sessions
@@ -91,7 +94,6 @@ Edit `.env` once:
 PRIVATE_KEY=
 LAUNCH_API_URL=
 RPC_URL=
-SIMULATION_RPC_URL=
 ```
 
 Set `PRIVATE_KEY` to **your funded EOA's** 32-byte hex key and `LAUNCH_API_URL` to
@@ -111,11 +113,13 @@ Optional `NFT_BASE_URI` supplies your actually hosted ERC404 NFT metadata base U
 Blank uses an empty base URI: NFT units/mirror behavior remain real, but the example
 does not claim hosted NFT metadata exists.
 
-Blank `SIMULATION_RPC_URL` selects the actual SDK native sequential `eth_simulateV1`
-backend. Set it only to a **separate owned disposable loopback Anvil** for the canonical
-SDK controlled fork; only this simulation environment is reset/impersonated/reverted.
+The fixed Robinhood examples require native sequential Nitro `eth_simulateV1`, including
+an isolated pinned ArbOS capability probe and exact fee-bearing replay. Generic
+Anvil/Hardhat forks cannot certify Nitro compute/poster metering and are not a fallback.
 Unsupported native simulation, insufficient funds or failed admission stop before API
-staging/broadcast. There is no mode fallback, admission override or reduced case.
+staging/broadcast. Each immediate next envelope is additionally preflighted read-only
+through the same execution RPC before signing. There is no mode fallback, admission
+override, automatic submission replay or reduced case.
 
 ### Commands and fixed cases
 
@@ -148,14 +152,16 @@ selected; token-only burn is 3000 bps in the burn case. V4 uses frozen registere
 treasury/author terms with developer rate `0`; executor fee is 275 bps.
 Hook salts/random identities are finalized and saved before execution.
 
-### Example execution ceilings
+### Optional execution restrictions
 
-Defaults are **EXAMPLE ceilings, not verified provider or account limits**:
-chain/RPC/account gas `16000000`, calldata `131072` bytes, headroom `1000` bps.
-The chain cap is additionally bounded by every observed block gas limit. If your
-provider/account policy differs, configure decimal environment values:
-`EXAMPLE_CHAIN_GAS_CAP`, `EXAMPLE_RPC_GAS_CAP`, `EXAMPLE_ACCOUNT_GAS_CAP`,
-`EXAMPLE_MAX_CALLDATA_BYTES`, `EXAMPLE_HEADROOM_BPS`. These do not bypass SDK admission.
+There are no default chain/RPC/account gas or calldata caps. The SDK reads current
+Nitro protocol compute ceilings and exact-calldata poster budgets itself. Default
+headroom is **1500 bps (15%)**. Set explicit decimal restrictions only when you intend
+to tighten the complete transaction envelope: `EXAMPLE_CHAIN_GAS_CAP`,
+`EXAMPLE_RPC_GAS_CAP`, `EXAMPLE_ACCOUNT_GAS_CAP`, `EXAMPLE_MAX_CALLDATA_BYTES`.
+`EXAMPLE_HEADROOM_BPS` preserves your explicit 0–10000 policy. These are local
+restrictions, not invented provider/account assurances or admission bypasses.
+Poster allocation is already inside Nitro gas/affordability and is not charged twice.
 
 ### Evidence and failure recovery
 

package/examples/launch-example-support.mjs

@@ -70,7 +70,7 @@ export function loadExampleEnvironment() {
 export function readExampleConfiguration(sdk, redactor, env = process.env) {
   redactor.addSecret(env.PRIVATE_KEY);
   if (typeof env.PRIVATE_KEY === "string") redactor.addSecret(env.PRIVATE_KEY.slice(2));
-  for (const value of [env.RPC_URL, env.LAUNCH_API_URL, env.SIMULATION_RPC_URL, env.NFT_BASE_URI]) registerEndpointSecrets(redactor, value);
+  for (const value of [env.RPC_URL, env.LAUNCH_API_URL, env.NFT_BASE_URI]) registerEndpointSecrets(redactor, value);
   if (!env.PRIVATE_KEY?.trim()) throw exampleError("MISSING_CONFIGURATION", "PRIVATE_KEY is required in the environment or working-directory .env");
   if (!env.LAUNCH_API_URL?.trim()) throw exampleError("MISSING_CONFIGURATION", "LAUNCH_API_URL is required in the environment or working-directory .env");
   if (!/^0x[\da-f]{64}$/i.test(env.PRIVATE_KEY)) throw exampleError("INVALID_PRIVATE_KEY", "PRIVATE_KEY must be a 32-byte hex private key");
@@ -79,24 +79,20 @@ export function readExampleConfiguration(sdk, redactor, env = process.env) {
   catch { throw exampleError("INVALID_PRIVATE_KEY", "PRIVATE_KEY must be a valid 32-byte secp256k1 hex private key"); }
   const addresses = sdk.getAddresses(4663);
   const rpcUrl = executionRpcUrl(env.RPC_URL || sdk.robinhoodMainnet.rpcUrls.default.http[0]);
-  const forkRpcUrl = env.SIMULATION_RPC_URL ? loopbackUrl(env.SIMULATION_RPC_URL, "Simulation RPC") : undefined;
-  if (forkRpcUrl) {
-    const source = new URL(rpcUrl); const fork = new URL(forkRpcUrl);
-    const port = (url) => url.port || (url.protocol === "https:" ? "443" : "80");
-    if (["127.0.0.1", "localhost", "[::1]"].includes(source.hostname) && port(source) === port(fork)) throw exampleError("UNSAFE_ENDPOINT", "Execution and disposable simulation RPCs must use distinct loopback ports");
-  }
   const gasCap = (key) => {
-    const value = env[key] || "16000000";
+    const value = env[key];
+    if (value === undefined || value === "") return undefined;
     if (!/^[1-9]\d*$/.test(value)) throw exampleError("INVALID_CONFIGURATION", `${key} must be a positive decimal integer`);
     return value;
   };
   const integer = (key, fallback, minimum, maximum) => {
+    if (fallback === undefined && (env[key] === undefined || env[key] === "")) return undefined;
     const value = env[key] || String(fallback);
     if (!/^(?:0|[1-9]\d*)$/.test(value) || !Number.isSafeInteger(Number(value)) || Number(value) < minimum || Number(value) > maximum) throw exampleError("INVALID_CONFIGURATION", `${key} is outside its allowed integer range`);
     return Number(value);
   };
   return {
-    chainId: "4663", rpcUrl, forkRpcUrl, apiUrl: launchApiUrl(env.LAUNCH_API_URL),
+    chainId: "4663", rpcUrl, apiUrl: launchApiUrl(env.LAUNCH_API_URL),
     orchestrator: addresses.launchOrchestrator, creator: account.address,
     quoteAsset: addresses.weth, quoteDecimals: 18, oracleFactory: addresses.abyssFactory,
     nftBaseUri: env.NFT_BASE_URI || "",
@@ -104,9 +100,9 @@ export function readExampleConfiguration(sdk, redactor, env = process.env) {
       chainTransactionGasLimit: gasCap("EXAMPLE_CHAIN_GAS_CAP"),
       rpcTransactionGasLimit: gasCap("EXAMPLE_RPC_GAS_CAP"),
       accountTransactionGasLimit: gasCap("EXAMPLE_ACCOUNT_GAS_CAP"),
-      maxCalldataBytes: integer("EXAMPLE_MAX_CALLDATA_BYTES", 131072, 1, Number.MAX_SAFE_INTEGER),
-      headroomBps: integer("EXAMPLE_HEADROOM_BPS", 1000, 0, 10000),
-      provenance: { scope: "example-ceilings", note: "EXAMPLE ceilings, not verified provider or account limits; bounded by each observed block gas limit" },
+      maxCalldataBytes: integer("EXAMPLE_MAX_CALLDATA_BYTES", undefined, 1, Number.MAX_SAFE_INTEGER),
+      headroomBps: integer("EXAMPLE_HEADROOM_BPS", 1500, 0, 10000),
+      provenance: { scope: "user-ceilings", note: "Optional local tightening restrictions, not verified provider or account limits" },
     },
   };
 }

package/examples/launch-example.mjs

@@ -60,7 +60,7 @@ function rpcClient(url, artifacts, signal, label) {
       const body = await response.json();
       if (body.error) throw exampleError(body.error.code ?? "RPC_ERROR", `${label} ${method}: ${body.error.message}`, { data: body.error.data, cause: body.error });
       if (!("result" in body)) throw exampleError("INVALID_RPC_RESPONSE", `${label} ${method}: result was omitted`, { data: body });
-      if (method === "eth_simulateV1" || label === "simulation" && ["eth_sendTransaction", "anvil_reset", "evm_snapshot", "evm_revert"].includes(method)) artifacts.event("rpc-observation", { backend: label, method, params, result: body.result, elapsedMs: Date.now() - started });
+      if (method === "eth_simulateV1") artifacts.event("rpc-observation", { backend: label, method, params, result: body.result, elapsedMs: Date.now() - started });
       return body.result;
     } catch (error) {
       artifacts.event("rpc-error", { backend: label, method, params, elapsedMs: Date.now() - started, error: errorEvidence(error) });
@@ -256,20 +256,22 @@ function limitSource(fixture, artifacts) {
   return async ({ block, chainId, account, orchestrator }) => {
     const limits = {
       chainId, account, orchestrator, observedBlockNumber: block.number, observedBlockHash: block.hash,
-      chainGasLimit: BigInt(policy.chainTransactionGasLimit) < block.gasLimit ? BigInt(policy.chainTransactionGasLimit) : block.gasLimit, rpcGasLimit: BigInt(policy.rpcTransactionGasLimit),
-      accountGasLimit: BigInt(policy.accountTransactionGasLimit), maxCalldataBytes: policy.maxCalldataBytes, headroomBps: policy.headroomBps,
+      chainGasLimit: policy.chainTransactionGasLimit === undefined ? undefined : BigInt(policy.chainTransactionGasLimit),
+      rpcGasLimit: policy.rpcTransactionGasLimit === undefined ? undefined : BigInt(policy.rpcTransactionGasLimit),
+      accountGasLimit: policy.accountTransactionGasLimit === undefined ? undefined : BigInt(policy.accountTransactionGasLimit),
+      maxCalldataBytes: policy.maxCalldataBytes, headroomBps: policy.headroomBps,
     };
     artifacts.event("execution-limits", { limits, provenance: policy.provenance });
     return limits;
   };
 }
 
-async function executePlan({ client, fixture, planned, sdk, artifacts, signal, limits, fork, wallet }) {
+async function executePlan({ client, fixture, planned, sdk, artifacts, signal, limits, wallet }) {
   const references = [];
   let activation;
   for (let step = 0; step < 64; step += 1) {
     artifacts.stage("build-next", { step });
-    const next = await sdk.buildNextTransaction({ client, planned, receipts: references, limits, fork });
+    const next = await sdk.buildNextTransaction({ client, planned, receipts: references, limits, submissionClient: client });
     if (!next) return { references, activation };
     artifacts.event("next-admitted", { transaction: next });
     assert.equal(next.chainId, Number(planned.chainId));
@@ -282,10 +284,12 @@ async function executePlan({ client, fixture, planned, sdk, artifacts, signal, l
     const args = next.kind === "begin" ? [planned.plan, sdk.LifecycleMode.Staged] : next.kind === "prepare" ? [planned.plan, next.marketStart, next.marketCount] : [planned.plan];
     assert.equal(next.data.toLowerCase(), encodeFunctionData({ abi: sdk.launchLifecycleAbi, functionName, args }).toLowerCase(), "Exact finalized-plan calldata");
     assert.ok(next.gas !== undefined && (next.gasPrice !== undefined || next.maxFeePerGas !== undefined && next.maxPriorityFeePerGas !== undefined) && next.admission?.admitted === true, "Actual next transaction needs stateful gas/envelope admission");
-    const head = await client.request({ method: "eth_getBlockByNumber", params: ["latest", false] });
-    const ceiling = [BigInt(head.gasLimit), ...["chainTransactionGasLimit", "rpcTransactionGasLimit", "accountTransactionGasLimit"].map((key) => BigInt(fixture.executionLimits[key]))].reduce((left, right) => left < right ? left : right);
-    assert.ok(next.gas > 0n && next.gas <= ceiling, "Admitted gas must fit all explicit caps");
-    assert.ok((next.data.length - 2) / 2 <= fixture.executionLimits.maxCalldataBytes, "Exact calldata cap");
+    assert.equal(next.admission.executionProof, "proved"); assert.equal(next.admission.protocolFit, "proved");
+    assert.equal(next.admission.transportPreflight, "passed", "Exact immediate-next submission RPC preflight is required before signing");
+    const ceiling = next.admission.limits.transactionGasCeiling;
+    assert.ok(next.gas > 0n && (ceiling === undefined || next.gas <= ceiling), "Complete gas envelope must fit supplied restrictions; Nitro compute is separately proved");
+    const calldataCap = next.admission.limits.maxCalldataBytes;
+    assert.ok(calldataCap === undefined || (next.data.length - 2) / 2 <= calldataCap, "Exact calldata must fit any supplied cap");
     const envelope = transactionEnvelope(next);
     const wire = { ...envelope };
     for (const key of ["chainId", "value", "gas", "gasPrice", "maxFeePerGas", "maxPriorityFeePerGas", "nonce"]) if (wire[key] !== undefined) wire[key] = toHex(BigInt(wire[key]));
@@ -529,21 +533,14 @@ async function executeExample({ fixture, scenario, sdk, artifacts, signal }) {
   const { plan, predictedToken } = await constructPlan({ client, fixture, scenario, sdk, artifacts, signal });
   artifacts.stage("execution-planning");
   const limits = limitSource(fixture, artifacts);
-  let fork;
-  if (fixture.forkRpcUrl !== undefined) {
-    const baseFork = sdk.createControlledLifecycleFork({ sourceRpcUrl: fixture.rpcUrl, forkRpcUrl: fixture.forkRpcUrl, allowTransactions: true, impersonation: "anvil", receiptTimeoutMs: 30_000 });
-    // Only the SDK's separate owned simulation fork is reset/impersonated/reverted.
-    fork = { ...baseFork, client: rpcClient(fixture.forkRpcUrl, artifacts, signal, "simulation") };
-    assert.match(await fork.client.request({ method: "web3_clientVersion" }), /anvil/i);
-  }
-  const planned = await sdk.planLaunch({ client, account: fixture.creator, plan, mode: scenario.mode, limits, fork, confirmations: 1 });
+  const planned = await sdk.planLaunch({ client, account: fixture.creator, plan, mode: scenario.mode, limits, confirmations: 1 });
   artifacts.save("planning.json", planned);
   artifacts.event("execution-plan", { mode: planned.mode, simulation: planned.simulation, atomicAttempt: planned.atomicAttempt, prerequisites: planned.prerequisites, transactions: planned.transactions });
   assert.equal(planned.mode, scenario.mode, "Never silently change requested mode"); addressEqual(planned.predictedToken, predictedToken, "Planner token prediction");
   if (!planned.simulation.admitted) throw exampleError("PLAN_NOT_ADMITTED", planned.simulation.reason ?? "The actual SDK did not admit this exact launch", { simulation: planned.simulation });
   const transport = apiTransport({ artifacts, signal, apiUrl: fixture.apiUrl });
   const session = await stageMetadata({ fixture, plan, sdk, artifacts, transport, wallet });
-  const executed = await executePlan({ client, fixture, planned, sdk, artifacts, signal, limits, fork, wallet });
+  const executed = await executePlan({ client, fixture, planned, sdk, artifacts, signal, limits, wallet });
   await verifyChain({ client, planned, ...executed, fixture, scenario, sdk, artifacts });
   await publishAndVerify({ fixture, planned, activation: executed.activation, session, sdk, artifacts, transport, signal, timeoutSeconds: 90 });
   artifacts.stage("completed");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@black-market/sdk",
-  "version": "0.5.2",
+  "version": "0.6.0",
   "description": "TypeScript SDK for Abyss token launches, swaps, and lending.",
   "license": "MIT",
   "repository": {

package/src/lifecycle/planner.ts

@@ -209,7 +209,7 @@ function orderedTransactions(plan: LaunchPlanV1, mode: "atomic" | "staged", prog
 function attachEstimates(transactions: readonly LifecycleTransaction[], simulation: LifecycleSimulation): LifecycleTransaction[] {
   return transactions.map((transaction) => {
     const estimate = simulation.steps.find((step) => step.transactionId === transaction.id)?.estimate;
-    return { ...transaction, gas: estimate?.gasLimit, gasPrice: estimate?.gasPrice, estimate, admission: { admitted: simulation.admitted, confidence: simulation.confidence, reason: simulation.reason, limits: simulation.limits } };
+    return { ...transaction, gas: estimate?.gasLimit, gasPrice: estimate?.gasPrice, estimate, admission: { admitted: simulation.admitted, confidence: simulation.confidence, executionProof: simulation.executionProof, protocolFit: simulation.protocolFit, transportPreflight: simulation.transportPreflight, blockNumber: simulation.blockNumber, blockHash: simulation.blockHash, account: simulation.account, chainId: simulation.chainId, reason: simulation.reason, limits: simulation.limits } };
   });
 }
 
@@ -301,7 +301,7 @@ export async function planLaunch(options: PlanLaunchOptions): Promise<PlannedLau
   const predictedToken = await readLifecycleContract<Address>(client, plan.orchestrator, launchLifecycleAbi, "predictToken", [plan], block);
   const { tokenFactory, tokenFactoryCodeHash } = await readTokenFactoryBinding(client, plan.orchestrator, block);
   const { limits } = await resolveLifecycleLimits({ client, account, orchestrator: plan.orchestrator, block, chainId: plan.chainId }, options.limits);
-  const placeholder: LifecycleSimulation = { backend: "unavailable", confidence: "provisional", admitted: false, blockNumber: block.number, blockHash: block.hash, account, chainId: plan.chainId, limits, steps: [] };
+  const placeholder: LifecycleSimulation = { backend: "unavailable", confidence: "provisional", admitted: false, executionProof: "unavailable", protocolFit: "unknown", transportPreflight: "not-requested", blockNumber: block.number, blockHash: block.hash, account, chainId: plan.chainId, limits, steps: [] };
   const identity = { plan, planHash, launchId, predictedToken, account, mode, confirmations: options.confirmations ?? 1 };
   const progress = await readLaunchProgress({ client, planned: identity, receipts: options.receipts }, block);
   let planned: PlannedLaunch = { ...identity, tokenFactory, tokenFactoryCodeHash, chainId: plan.chainId, transactions: [], prerequisites: [], profiles: [], hookDeployments: [], progress, simulation: placeholder, atomicAttempt: placeholder, preparationBatchSize: plan.markets.length, limits: options.limits };
@@ -318,7 +318,7 @@ export async function planLaunch(options: PlanLaunchOptions): Promise<PlannedLau
   }
   if (progress.canonical.phase === LifecyclePhase.Active || progress.canonical.phase === LifecyclePhase.Cancelled) {
     await assertLifecycleBlock(client, block);
-    return { ...planned, simulation: { ...placeholder, confidence: "stateful", admitted: true, reason: "Canonical launch is terminal; no transaction remains" } };
+    return { ...planned, simulation: { ...placeholder, confidence: "stateful", executionProof: "proved", protocolFit: "proved", admitted: true, reason: "Canonical launch is terminal; no transaction remains" } };
   }
   const prerequisites = progress.canonical.phase === LifecyclePhase.None ? await readFunding(client, plan, block) : { prerequisites: [], approvals: [], nativeValue: 0n, reasons: [] };
   const validation = await validatePendingInputs(client, planned, progress, block);
@@ -351,6 +351,33 @@ export async function planLaunch(options: PlanLaunchOptions): Promise<PlannedLau
   return { ...planned, atomicAttempt, simulation, preparationBatchSize, transactions: attachEstimates(transactions, simulation) };
 }
 
+async function preflightNextTransaction(options: BuildNextTransactionOptions, next: LifecycleTransaction, simulation: LifecycleSimulation): Promise<LifecycleTransaction> {
+  if (next.gas === undefined || next.gas <= 0n || next.gas >= 1n << 64n || next.gasPrice === undefined || next.gasPrice < 0n ||
+    simulation.executionProof !== "proved" || simulation.protocolFit !== "proved" || !simulation.admitted ||
+    next.estimate === undefined || next.estimate.gasLimit !== next.gas || next.estimate.gasPrice !== next.gasPrice ||
+    simulation.limits.transactionGasCeiling !== undefined && next.gas > simulation.limits.transactionGasCeiling) {
+    throw new LifecyclePlanningError("MISSING_GAS_PROOF", "Next transaction has no current-state exact gas/headroom/fee-envelope proof", simulation);
+  }
+  const submissionClient = options.submissionClient;
+  if (submissionClient === undefined) return { ...next, dependencies: [] };
+  try {
+    if (rpcQuantity(await lifecycleRpc(submissionClient, "eth_chainId"), "submission chain ID") !== simulation.chainId) throw new Error("Active submission RPC chain differs from the reviewed transaction");
+    const estimated = rpcQuantity(await lifecycleRpc(submissionClient, "eth_estimateGas", [{
+      from: next.from, to: next.to, data: next.data, value: toHex(next.value), gas: toHex(next.gas), gasPrice: toHex(next.gasPrice),
+    }, "latest"]), "submission gas estimate");
+    if (estimated <= 0n || estimated > next.gas) throw new Error("Submission RPC gas estimate exceeds the exact reviewed envelope or is zero");
+    if (rpcQuantity(await lifecycleRpc(submissionClient, "eth_chainId"), "submission chain ID") !== simulation.chainId) throw new Error("Active submission RPC chain changed during preflight");
+  } catch (failure) {
+    const reason = `Exact next-transaction submission preflight failed: ${failure instanceof Error ? failure.message : String(failure)}`;
+    throw new LifecyclePlanningError("SUBMISSION_PREFLIGHT_FAILED", reason, { ...simulation, transportPreflight: "failed", reason });
+  }
+  const canonical = await readLifecycleBlock(options.client, toHex(simulation.blockNumber));
+  if (canonical.hash.toLowerCase() !== simulation.blockHash.toLowerCase()) throw new LifecyclePlanningError("STATE_REORGED", "Pinned launch proof changed during submission preflight; rebuild from canonical progress");
+  if (rpcQuantity(await lifecycleRpc(options.client, "eth_chainId"), "chain ID") !== simulation.chainId) throw new LifecyclePlanningError("CHAIN_MISMATCH", "Source RPC chain changed during submission preflight");
+  if (next.admission === undefined) throw new LifecyclePlanningError("MISSING_GAS_PROOF", "Next transaction omitted its exact simulation admission", simulation);
+  return { ...next, dependencies: [], admission: { ...next.admission, transportPreflight: "passed" } };
+}
+
 /** Re-reads canonical state, revalidates all prerequisites, and proves the remaining sequence afresh. */
 export async function buildNextTransaction(options: BuildNextTransactionOptions): Promise<LifecycleTransaction | undefined> {
   const block = await readLifecycleBlock(options.client);
@@ -368,17 +395,18 @@ export async function buildNextTransaction(options: BuildNextTransactionOptions)
     if (progress.canonical.phase === LifecyclePhase.None) throw new LifecyclePlanningError("NOT_STARTED", "An unstarted plan has no launch escrow to cancel");
     const { planned } = options;
     const transaction: LifecycleTransaction = { id: "cancel", kind: "cancel", chainId: Number(planned.chainId), from: planned.account, to: planned.plan.orchestrator, data: encodeFunctionData({ abi: launchLifecycleAbi, functionName: "cancelLaunch", args: [planned.plan] }), value: 0n, dependencies: [], postconditions: [{ kind: "launch", phase: "Cancelled", preparedMarkets: progress.canonical.preparedMarkets }] };
-    const simulation = await simulateLaunchTransactions({ client: options.client, planned, limits: options.limits ?? planned.limits, fork: options.fork }, [transaction], block);
+    const simulation = await simulateLaunchTransactions({ client: options.client, planned, limits: options.limits === undefined ? planned.limits : options.limits, fork: options.fork }, [transaction], block);
     if (!simulation.admitted) throw new LifecyclePlanningError("CANCEL_NOT_ADMITTED", simulation.reason ?? "Cancellation could not be proved against current canonical state", simulation);
-    return attachEstimates([transaction], simulation)[0];
+    const next = attachEstimates([transaction], simulation)[0];
+    if (next === undefined) throw new LifecyclePlanningError("MISSING_GAS_PROOF", "Cancellation omitted its exact simulation admission", simulation);
+    return preflightNextTransaction(options, next, simulation);
   }
-  const refreshed = await planLaunch({ client: options.client, plan: options.planned.plan, account: options.planned.account, mode: options.planned.mode, limits: options.limits ?? options.planned.limits, fork: options.fork, receipts: options.receipts, confirmations: options.confirmations ?? options.planned.confirmations });
+  const refreshed = await planLaunch({ client: options.client, plan: options.planned.plan, account: options.planned.account, mode: options.planned.mode, limits: options.limits === undefined ? options.planned.limits : options.limits, fork: options.fork, receipts: options.receipts, confirmations: options.confirmations ?? options.planned.confirmations });
   if (!refreshed.simulation.admitted) throw new LifecyclePlanningError("PLAN_NOT_ADMITTED", refreshed.simulation.reason ?? "Remaining exact launch sequence is not admitted", refreshed.simulation);
   assertPlannedDeploymentBindings(options.planned, refreshed);
   const next = refreshed.transactions[0];
   if (next === undefined) return undefined;
-  if (next.gas === undefined || next.gasPrice === undefined || next.gas > refreshed.simulation.limits.executionGasCeiling) throw new LifecyclePlanningError("MISSING_GAS_PROOF", "Next transaction has no current-state exact gas/headroom/fee-envelope proof");
-  return { ...next, dependencies: [] };
+  return preflightNextTransaction(options, next, refreshed.simulation);
 }
 
 /** Re-simulates only canonical unfinished work with the same submitted receipt
@@ -388,7 +416,7 @@ export async function simulateLaunchPlan(options: SimulateLaunchPlanOptions): Pr
   if (hashLaunchPlan(planned.plan).toLowerCase() !== planned.planHash.toLowerCase() || hashLaunchIdentity(planned.plan).toLowerCase() !== planned.launchId.toLowerCase()) throw new LifecyclePlanningError("PLAN_MUTATED", "Stored economic plan no longer matches its commitment");
   const current = await planLaunch({
     client, plan: planned.plan, account: planned.account, mode: planned.mode,
-    limits: options.limits ?? planned.limits, fork: options.fork,
+    limits: options.limits === undefined ? planned.limits : options.limits, fork: options.fork,
     receipts: options.receipts, confirmations: options.confirmations ?? planned.confirmations,
   });
   assertPlannedDeploymentBindings(planned, current);