bulletin-deploy 0.7.4 → 0.7.6

package/dist/{chunk-JHNW2EKY.js → chunk-WIBZPZSY.js}

@@ -12,6 +12,7 @@ var TOPUP_TRANSACTIONS = 1e3;
 var TOPUP_BYTES = 100000000n;
 var TOPUP_THRESHOLD_TXS = 50n;
 var TOPUP_THRESHOLD_BYTES = 50000000n;
+var WS_HEARTBEAT_TIMEOUT_MS = 3e5;
 function derivePoolAccounts(poolSize = 10, mnemonic = DEV_PHRASE) {
   const entropy = mnemonicToEntropy(mnemonic);
   const miniSecret = entropyToMiniSecret(entropy);
@@ -126,23 +127,13 @@ function aliceKeyring() {
   const signer = getPolkadotSigner(alice.publicKey, "Sr25519", (data) => alice.sign(data));
   return { alice, signer };
 }
-async function withAliceApi(bulletinRpc, fn) {
-  const aliceClient = createClient(withPolkadotSdkCompat(getWsProvider(bulletinRpc)));
-  const aliceApi = aliceClient.getUnsafeApi();
-  try {
-    const { signer } = aliceKeyring();
-    return await fn(aliceApi, signer);
-  } finally {
-    aliceClient.destroy();
-  }
-}
 var U32_MAX = 0xFFFFFFFFn;
 function clampU32(n, name) {
   if (n < 0n) throw new Error(`${name} must be non-negative`);
   if (n > U32_MAX) throw new Error(`${name} (${n}) exceeds u32 max \u2014 split the deploy into smaller batches`);
   return Number(n);
 }
-async function ensureAuthorized(api, address, bulletinRpc, label, minimum = { txs: TOPUP_THRESHOLD_TXS, bytes: TOPUP_THRESHOLD_BYTES }) {
+async function ensureAuthorized(api, address, label, minimum = { txs: TOPUP_THRESHOLD_TXS, bytes: TOPUP_THRESHOLD_BYTES }) {
   const auth = await api.query.TransactionStorage.Authorizations.getValue(
     Enum("Account", address)
   );
@@ -152,54 +143,55 @@ async function ensureAuthorized(api, address, bulletinRpc, label, minimum = { tx
     return;
   }
   console.log(`   Auto-authorizing ${label ?? "account"} (${address.slice(0, 8)}...)...`);
-  await withAliceApi(bulletinRpc, async (aliceApi, signer) => {
-    await submitAliceTxWithRetry(
-      () => aliceApi.tx.TransactionStorage.authorize_account({
-        who: address,
-        transactions: TOPUP_TRANSACTIONS,
-        bytes: TOPUP_BYTES
-      }),
-      signer,
-      `authorize_account(${label ?? "account"})`
-    );
-    console.log(`   Authorized: ${TOPUP_TRANSACTIONS} txs, ${TOPUP_BYTES / 1000000n}MB`);
-  });
+  const { signer } = aliceKeyring();
+  await submitAliceTxWithRetry(
+    () => api.tx.TransactionStorage.authorize_account({
+      who: address,
+      transactions: TOPUP_TRANSACTIONS,
+      bytes: TOPUP_BYTES
+    }),
+    signer,
+    `authorize_account(${label ?? "account"})`
+  );
+  console.log(`   Authorized: ${TOPUP_TRANSACTIONS} txs, ${TOPUP_BYTES / 1000000n}MB`);
 }
-async function topUpBy(address, bulletinRpc, needs, label) {
-  await withAliceApi(bulletinRpc, async (aliceApi, signer) => {
-    const currentAuth = await aliceApi.query.TransactionStorage.Authorizations.getValue(
-      Enum("Account", address)
-    );
-    const current = {
-      transactions: currentAuth ? BigInt(currentAuth.extent.transactions) : 0n,
-      bytes: currentAuth ? currentAuth.extent.bytes : 0n
-    };
-    const fmtMB = (b) => (Number(b) / 1e6).toFixed(1);
-    const target = computeTopUpTarget(current, needs);
-    if (!target) {
-      console.log(`   Pre-auth skipped for ${label ?? "account"} (${address.slice(0, 8)}...): current ${current.transactions} txs / ${fmtMB(current.bytes)}MB covers needs + floor.`);
-      return;
-    }
-    const transactions = clampU32(target.transactions, "topUpBy.txs");
-    console.log(`   Pre-authorizing ${label ?? "account"} (${address.slice(0, 8)}...): current ${current.transactions} txs / ${fmtMB(current.bytes)}MB \u2192 target ${target.transactions} txs / ${fmtMB(target.bytes)}MB...`);
-    await submitAliceTxWithRetry(
-      () => aliceApi.tx.TransactionStorage.authorize_account({
-        who: address,
-        transactions,
-        bytes: target.bytes
-      }),
-      signer,
-      `topUpBy(${label ?? "account"})`
-    );
-    console.log(`   Pre-authorized: target ${transactions} txs / ${fmtMB(target.bytes)}MB`);
-  });
+async function topUpBy(api, address, needs, label) {
+  const currentAuth = await api.query.TransactionStorage.Authorizations.getValue(
+    Enum("Account", address)
+  );
+  const current = {
+    transactions: currentAuth ? BigInt(currentAuth.extent.transactions) : 0n,
+    bytes: currentAuth ? currentAuth.extent.bytes : 0n
+  };
+  const fmtMB = (b) => (Number(b) / 1e6).toFixed(1);
+  const target = computeTopUpTarget(current, needs);
+  if (!target) {
+    console.log(`   Pre-auth skipped for ${label ?? "account"} (${address.slice(0, 8)}...): current ${current.transactions} txs / ${fmtMB(current.bytes)}MB covers needs + floor.`);
+    return;
+  }
+  const transactions = clampU32(target.transactions, "topUpBy.txs");
+  const { signer } = aliceKeyring();
+  console.log(`   Pre-authorizing ${label ?? "account"} (${address.slice(0, 8)}...): current ${current.transactions} txs / ${fmtMB(current.bytes)}MB \u2192 target ${target.transactions} txs / ${fmtMB(target.bytes)}MB...`);
+  await submitAliceTxWithRetry(
+    () => api.tx.TransactionStorage.authorize_account({
+      who: address,
+      transactions,
+      bytes: target.bytes
+    }),
+    signer,
+    `topUpBy(${label ?? "account"})`
+  );
+  console.log(`   Pre-authorized: target ${transactions} txs / ${fmtMB(target.bytes)}MB`);
 }
 async function bootstrapPool(bulletinRpc, poolSize = 10, mnemonic) {
   console.log(`Bootstrapping ${poolSize} pool accounts on ${bulletinRpc}...
 `);
   await cryptoWaitReady();
   const accounts = derivePoolAccounts(poolSize, mnemonic);
-  const client = createClient(withPolkadotSdkCompat(getWsProvider(bulletinRpc)));
+  const client = createClient(withPolkadotSdkCompat(getWsProvider(
+    bulletinRpc,
+    { heartbeatTimeout: WS_HEARTBEAT_TIMEOUT_MS }
+  )));
   const api = client.getUnsafeApi();
   const keyring = new Keyring({ type: "sr25519" });
   const alice = keyring.addFromUri("//Alice");

package/dist/{chunk-DHQ3JGF4.js → chunk-Y6CTPQS2.js}

@@ -1,7 +1,7 @@
 import {
   package_default,
   writeRunState
-} from "./chunk-UJP2PZGU.js";
+} from "./chunk-HHY32NGJ.js";
 
 // src/memory-report.ts
 import * as fs2 from "fs";

package/dist/{chunk-YYULF2JX.js → chunk-YX62STIA.js}

@@ -2,11 +2,11 @@ import {
   classifyErrorArea,
   isInteractive,
   promptYesNo
-} from "./chunk-CQ753LDA.js";
+} from "./chunk-EECNTEAE.js";
 import {
   VERSION,
   getCurrentSentryTraceId
-} from "./chunk-DHQ3JGF4.js";
+} from "./chunk-Y6CTPQS2.js";
 
 // src/bug-report.ts
 import { execSync, execFileSync } from "child_process";
@@ -74,7 +74,6 @@ function scrubSecrets(text) {
 }
 function buildCliFlagsSummary(flags) {
   const parts = [];
-  if (flags.bootstrap) parts.push("--bootstrap");
   if (flags.jsMerkle) parts.push("--js-merkle");
   if (flags.ghPagesMirror) parts.push("--gh-pages-mirror");
   if (flags.poolSize != null) parts.push(`--pool-size ${String(flags.poolSize)}`);

package/dist/deploy.js

@@ -25,15 +25,15 @@ import {
   storeChunkedContent,
   storeDirectory,
   storeFile
-} from "./chunk-SVKCVNXD.js";
-import "./chunk-YYULF2JX.js";
-import "./chunk-CQ753LDA.js";
-import "./chunk-YREZFNCC.js";
+} from "./chunk-A2J6R5PD.js";
+import "./chunk-YX62STIA.js";
+import "./chunk-EECNTEAE.js";
+import "./chunk-G6CVI6U2.js";
 import "./chunk-2Q2WSKFD.js";
-import "./chunk-DHQ3JGF4.js";
-import "./chunk-UJP2PZGU.js";
+import "./chunk-Y6CTPQS2.js";
+import "./chunk-HHY32NGJ.js";
 import "./chunk-B7GUYYAN.js";
-import "./chunk-JHNW2EKY.js";
+import "./chunk-WIBZPZSY.js";
 import "./chunk-QGM4M3NI.js";
 export {
   CHUNK_MORTALITY_PERIOD,

package/dist/dotns.d.ts

@@ -88,6 +88,7 @@ declare function stripTrailingDigits(label: string): string;
 declare function sanitizeDomainLabel(label: string): string;
 declare function validateDomainLabel(label: string): string;
 declare function isCommitmentMature(chainNowSeconds: number, commitTimestampSeconds: number, minimumAgeSeconds: number): boolean;
+declare function isExplicitCommitmentBuffer(envValue: string | undefined): boolean;
 declare function classifyDotnsLabel(label: string): {
     status: number;
     message: string;
@@ -155,4 +156,4 @@ declare class DotNS {
 }
 declare const dotns: DotNS;
 
-export { CONNECTION_TIMEOUT_MS, CONTRACTS, DECIMALS, DEFAULT_MNEMONIC, DOTNS_TX_MAX_ATTEMPTS, DOT_NODE, DotNS, type DotNSConnectOptions, type DotnsPreflightResult, NATIVE_TO_ETH_RATIO, OPERATION_TIMEOUT_MS, type OwnershipResult, type ParsedDomainName, type PriceValidationResult, ProofOfPersonhoodStatus, RPC_ENDPOINTS, TX_CHAIN_TIME_BUDGET_MS, TX_TIMEOUT_MS, TX_WALL_CLOCK_CEILING_MS, WS_HEARTBEAT_TIMEOUT_MS, canRegister, classifyDotnsLabel, classifyTxRetryDecision, computeDomainTokenId, convertWeiToNative, countTrailingDigits, dotns, fetchNonce, isCommitmentMature, parseDomainName, parseProofOfPersonhoodStatus, popStatusName, runDotnsCli, sanitizeDomainLabel, simulateUserStatus, stripTrailingDigits, validateDomainLabel, verifyNonceAdvanced };
+export { CONNECTION_TIMEOUT_MS, CONTRACTS, DECIMALS, DEFAULT_MNEMONIC, DOTNS_TX_MAX_ATTEMPTS, DOT_NODE, DotNS, type DotNSConnectOptions, type DotnsPreflightResult, NATIVE_TO_ETH_RATIO, OPERATION_TIMEOUT_MS, type OwnershipResult, type ParsedDomainName, type PriceValidationResult, ProofOfPersonhoodStatus, RPC_ENDPOINTS, TX_CHAIN_TIME_BUDGET_MS, TX_TIMEOUT_MS, TX_WALL_CLOCK_CEILING_MS, WS_HEARTBEAT_TIMEOUT_MS, canRegister, classifyDotnsLabel, classifyTxRetryDecision, computeDomainTokenId, convertWeiToNative, countTrailingDigits, dotns, fetchNonce, isCommitmentMature, isExplicitCommitmentBuffer, parseDomainName, parseProofOfPersonhoodStatus, popStatusName, runDotnsCli, sanitizeDomainLabel, simulateUserStatus, stripTrailingDigits, validateDomainLabel, verifyNonceAdvanced };

package/dist/dotns.js

@@ -23,6 +23,7 @@ import {
   dotns,
   fetchNonce,
   isCommitmentMature,
+  isExplicitCommitmentBuffer,
   parseDomainName,
   parseProofOfPersonhoodStatus,
   popStatusName,
@@ -32,10 +33,10 @@ import {
   stripTrailingDigits,
   validateDomainLabel,
   verifyNonceAdvanced
-} from "./chunk-YREZFNCC.js";
-import "./chunk-DHQ3JGF4.js";
-import "./chunk-UJP2PZGU.js";
-import "./chunk-JHNW2EKY.js";
+} from "./chunk-G6CVI6U2.js";
+import "./chunk-Y6CTPQS2.js";
+import "./chunk-HHY32NGJ.js";
+import "./chunk-WIBZPZSY.js";
 import "./chunk-QGM4M3NI.js";
 export {
   CONNECTION_TIMEOUT_MS,
@@ -62,6 +63,7 @@ export {
   dotns,
   fetchNonce,
   isCommitmentMature,
+  isExplicitCommitmentBuffer,
   parseDomainName,
   parseProofOfPersonhoodStatus,
   popStatusName,

package/dist/index.js

@@ -1,14 +1,14 @@
 import {
   deploy
-} from "./chunk-SVKCVNXD.js";
-import "./chunk-YYULF2JX.js";
-import "./chunk-CQ753LDA.js";
+} from "./chunk-A2J6R5PD.js";
+import "./chunk-YX62STIA.js";
+import "./chunk-EECNTEAE.js";
 import {
   DotNS,
   parseDomainName
-} from "./chunk-YREZFNCC.js";
+} from "./chunk-G6CVI6U2.js";
 import "./chunk-2Q2WSKFD.js";
-import "./chunk-DHQ3JGF4.js";
+import "./chunk-Y6CTPQS2.js";
 import {
   VERSION,
   loadRunState,
@@ -18,7 +18,7 @@ import {
   shouldSkipStaleWarning,
   stateFilePath,
   writeRunState
-} from "./chunk-UJP2PZGU.js";
+} from "./chunk-HHY32NGJ.js";
 import {
   merkleizeJS
 } from "./chunk-B7GUYYAN.js";
@@ -28,7 +28,7 @@ import {
   ensureAuthorized,
   fetchPoolAuthorizations,
   selectAccount
-} from "./chunk-JHNW2EKY.js";
+} from "./chunk-WIBZPZSY.js";
 import "./chunk-QGM4M3NI.js";
 export {
   DotNS,

package/dist/memory-report.js

@@ -5,8 +5,8 @@ import {
   maybeWriteMemoryReport,
   safeHeap,
   sampleFromBytes
-} from "./chunk-DHQ3JGF4.js";
-import "./chunk-UJP2PZGU.js";
+} from "./chunk-Y6CTPQS2.js";
+import "./chunk-HHY32NGJ.js";
 import "./chunk-QGM4M3NI.js";
 export {
   DEFAULT_THRESHOLD_MB,

package/dist/pool.d.ts

@@ -30,8 +30,8 @@ declare function classifyAliceTxError(err: unknown): TxRetryDecision;
 declare function isTestnetSpecName(specName: string | undefined | null): boolean;
 declare function detectTestnet(api: any): Promise<boolean>;
 declare function _resetTestnetCacheForTests(): void;
-declare function ensureAuthorized(api: any, address: string, bulletinRpc: string, label?: string, minimum?: AuthorizationNeeds): Promise<void>;
-declare function topUpBy(address: string, bulletinRpc: string, needs: AuthorizationNeeds, label?: string): Promise<void>;
+declare function ensureAuthorized(api: any, address: string, label?: string, minimum?: AuthorizationNeeds): Promise<void>;
+declare function topUpBy(api: any, address: string, needs: AuthorizationNeeds, label?: string): Promise<void>;
 declare function bootstrapPool(bulletinRpc: string, poolSize?: number, mnemonic?: string): Promise<void>;
 
 export { type AuthorizationNeeds, type PoolAccount, type PoolAuthorization, type TxRetryDecision, _resetTestnetCacheForTests, bootstrapPool, classifyAliceTxError, computeTopUpTarget, derivePoolAccounts, detectTestnet, ensureAuthorized, fetchPoolAuthorizations, isTestnetSpecName, selectAccount, topUpBy };

package/dist/pool.js

@@ -10,7 +10,7 @@ import {
   isTestnetSpecName,
   selectAccount,
   topUpBy
-} from "./chunk-JHNW2EKY.js";
+} from "./chunk-WIBZPZSY.js";
 import "./chunk-QGM4M3NI.js";
 export {
   _resetTestnetCacheForTests,

package/dist/run-state.js

@@ -7,7 +7,7 @@ import {
   shouldSkipStaleWarning,
   stateFilePath,
   writeRunState
-} from "./chunk-UJP2PZGU.js";
+} from "./chunk-HHY32NGJ.js";
 import "./chunk-QGM4M3NI.js";
 export {
   VERSION,

package/dist/telemetry.js

@@ -24,8 +24,8 @@ import {
   truncateAddress,
   withDeploySpan,
   withSpan
-} from "./chunk-DHQ3JGF4.js";
-import "./chunk-UJP2PZGU.js";
+} from "./chunk-Y6CTPQS2.js";
+import "./chunk-HHY32NGJ.js";
 import "./chunk-QGM4M3NI.js";
 export {
   VERSION,

package/dist/version-check.js

@@ -8,9 +8,9 @@ import {
   isPreReleaseVersion,
   preReleaseWarning,
   promptYesNo
-} from "./chunk-CQ753LDA.js";
-import "./chunk-DHQ3JGF4.js";
-import "./chunk-UJP2PZGU.js";
+} from "./chunk-EECNTEAE.js";
+import "./chunk-Y6CTPQS2.js";
+import "./chunk-HHY32NGJ.js";
 import "./chunk-QGM4M3NI.js";
 export {
   assessVersion,

package/docs/bootstrap.md

@@ -0,0 +1,49 @@
+# bulletin-bootstrap
+
+`bulletin-bootstrap` is the operator CLI for initializing Bulletin pool accounts. It is separate from `bulletin-deploy` on purpose: deploys are the normal user path, bootstrap is an admin/setup operation.
+
+## Usage
+
+```bash
+bulletin-bootstrap
+```
+
+Options:
+
+| Flag | What it does |
+|---|---|
+| `--rpc wss://...` | Override the Bulletin RPC endpoint. Also readable from `BULLETIN_RPC`. |
+| `--pool-size N` | Number of derived pool accounts to initialize. Default: `10`. |
+| `--mnemonic "..."` | Root mnemonic used to derive the pool accounts. Also readable from `BULLETIN_POOL_MNEMONIC`, then `MNEMONIC`. |
+| `--version` | Print the CLI version. |
+| `--help` | Show help. |
+
+## What it does
+
+The command derives the pool account set and initializes the on-chain authorization state needed for Bulletin uploads.
+
+Use it when:
+
+- you are bringing up a fresh pool on a testnet
+- the shared uploader pool has not been authorized yet
+- you want to pre-initialize a non-default pool mnemonic
+
+Do not use it as part of routine deploys. Normal deploys go through `bulletin-deploy`.
+
+## Examples
+
+```bash
+# Default testnet pool against the default RPC
+bulletin-bootstrap
+
+# Different RPC and larger pool
+bulletin-bootstrap --rpc wss://custom-bulletin.example.com --pool-size 20
+
+# Explicit pool mnemonic
+bulletin-bootstrap --mnemonic "..."
+```
+
+## Related Docs
+
+- [Main README](../README.md)
+- [E2E test setup](./e2e-bootstrap.md)

package/docs/e2e-bootstrap.md

@@ -0,0 +1,64 @@
+# E2E test setup
+
+The E2E suite (`test/e2e.test.js`, driven by `.github/workflows/e2e.yml`) deploys real content to Paseo Bulletin testnet via `bulletin-deploy` and verifies the on-chain round-trip. It consumes the **shared default pool** (derived from `DEV_PHRASE` — the same pool real users hit in production) for Bulletin chunk upload, so no pool bootstrapping is required.
+
+Three one-time setup items are needed before the workflow can pass. Do them once per testnet lifetime (redo if testnet is wiped).
+
+## Prerequisites
+
+- `bulletin-deploy` built locally (`npm run build`).
+- `@parity/dotns-cli` on `$PATH` (for the Bob registration in item 3). Install with `npm i -g @parity/dotns-cli`.
+- Network access to Paseo Bulletin RPC (`wss://paseo-bulletin-rpc.polkadot.io`) and Asset Hub Paseo (DotNS).
+- Alice's dev mnemonic: `bottom drive obey lake curtain smoke basket hold race lonely fit walk`.
+
+## Setup
+
+### 1. Grant Alice PoP Full
+
+Both happy-path scenarios (S1, S2) deploy as Alice via DotNS. Registering a new un-reserved base name requires PoP Full:
+
+```bash
+node tools/check-pop-status.mjs --grant full
+```
+
+Idempotent. Re-run if the check shows Alice below Full.
+
+### 2. Fund and map Bob on Asset Hub Paseo
+
+Bob (`//Bob` from the dev phrase) is the owner of `e2eowned.dot` (see item 3). He needs:
+
+- **Balance** on Asset Hub Paseo for his on-chain fees. Request ~1 PAS from the Paseo faucet at [https://faucet.polkadot.io/](https://faucet.polkadot.io/) sending to Bob's SS58 address `5FHneW46xGXgs5mUiveU4sbTyGBzmstUspZC92UhjJM694ty`.
+- **Revive mapping** so he can sign EVM transactions. Running `check-pop-status` against Bob's key URI submits `map_account` automatically on connect if the mapping is absent:
+
+```bash
+node tools/check-pop-status.mjs "bottom drive obey lake curtain smoke basket hold race lonely fit walk//Bob"
+```
+
+Expected output: Bob's SS58, his H160 (`0x41dccbd49b26c50d34355ed86ff0fa9e489d1e01`), and PoP status (`NoStatus (0)` initially). Idempotent.
+
+### 3. Register `e2eowned.dot` directly as Bob
+
+The S3 negative scenario asserts that `bulletin-deploy` refuses to deploy to a domain owned by a different account (exit 78 with transfer guidance). Have Bob register the label via `dotns-cli` — no Alice intermediary, no Bulletin content needed (S3 never reads content):
+
+```bash
+dotns register domain -n e2eowned -s full --cb 30 \
+  -k "bottom drive obey lake curtain smoke basket hold race lonely fit walk//Bob"
+```
+
+Expected: exit 0, stdout ends with "Operation Complete" and `Domain: e2eowned.dot`. After this, `e2eowned.dot` is owned by Bob's H160 `0x41dccbd49b26c50d34355ed86ff0fa9e489d1e01`. PoP Full is auto-granted on testnet as part of the registration (an 8-char base name requires Full per `classifyDotnsLabel`). The `--cb 30` sets a 30s commitment buffer — the default 6s sometimes misses the 12s `minCommitmentAge` on Asset Hub Paseo.
+
+If S3 ever fails because `e2eowned.dot` was transferred back to Alice by mistake, re-run this step to restore Bob's ownership.
+
+## No pre-registration needed for `e2epool.dot` / `e2edirect.dot`
+
+The stable happy-path labels auto-register to Alice on first deploy (pool mode and direct mode both resolve to Alice at the DotNS layer — `--mnemonic` only overrides the DotNS signer, not the Bulletin signer; Bulletin always uses the pool). Subsequent runs exercise the update path (new contenthash under existing ownership).
+
+## Verifying locally
+
+```bash
+E2E=1 E2E_SIGNER=pool E2E_MERKLE=js E2E_SCENARIO=s1 \
+  BULLETIN_RPC=wss://paseo-bulletin-rpc.polkadot.io \
+  npm run test:e2e
+```
+
+Vary `E2E_SCENARIO` (`s1`, `s2`, `s3`), `E2E_SIGNER` (`pool`, `direct`), and `E2E_MERKLE` (`js`, `kubo`) to cover the full CI matrix.

package/docs/telemetry.md

@@ -0,0 +1,59 @@
+# Telemetry
+
+Telemetry is **off by default for external users**. It is enabled automatically for known internal Parity contexts and can also be controlled explicitly.
+
+## Opt in / opt out
+
+- `BULLETIN_DEPLOY_TELEMETRY=1`: explicit opt-in
+- `BULLETIN_DEPLOY_TELEMETRY=0`: force off
+
+Internal detection signals are OR'd together:
+
+1. `GITHUB_REPOSITORY` matches a known internal org
+2. `RUNNER_NAME` starts with `parity-`
+3. `git remote get-url origin` points at a known internal org
+
+## What is tracked
+
+- deploy duration and success/failure
+- storage phase timing
+- DotNS phase timing
+- pool account selection
+- source metadata such as repo, branch, and CI vs local
+- tool version
+
+## Ambient Sentry mode
+
+If another app embeds `bulletin-deploy` and already owns Sentry initialization, set these before importing or invoking the library:
+
+```sh
+BULLETIN_DEPLOY_USE_AMBIENT_SENTRY=1
+BULLETIN_DEPLOY_HOST_APP=<your-app-name>
+```
+
+That makes `bulletin-deploy` reuse the existing Sentry client instead of calling its own `Sentry.init()`.
+
+Requirements:
+
+- the host app must initialize Sentry first
+- Sentry SDK compatibility still matters
+- quotas and issue grouping remain owned by the host project
+
+## Tagging test traffic
+
+Use `--tag` or `DEPLOY_TAG` to separate test and benchmark traffic from real deploys.
+
+Examples:
+
+```bash
+bulletin-deploy --tag e2e-ci-pr ./build my-app.dot
+DEPLOY_TAG=load-test bulletin-deploy ./build my-app.dot
+```
+
+Common tags in this repo:
+
+- `e2e-ci-pr`
+- `e2e-ci-nightly`
+- `e2e-local-smoke`
+- `e2e-local-pr`
+- `e2e-local-nightly`

package/docs/testing.md

@@ -0,0 +1,44 @@
+# Testing
+
+The repo has three practical test layers: offline unit tests, live-testnet E2E coverage, and GitHub Actions matrices that exercise the shipped reusable workflow.
+
+## Offline tests
+
+```bash
+npm test
+```
+
+This runs the local Node test suite without network access.
+
+## Live-testnet E2E
+
+The E2E suite deploys real content to Paseo Bulletin and verifies the on-chain round-trip.
+
+Local launchers:
+
+```bash
+npm run test:e2e:smoke
+npm run test:e2e:pr
+npm run test:e2e:nightly
+```
+
+Quiet mode:
+
+```bash
+E2E_QUIET=1 npm run test:e2e:smoke
+E2E_QUIET=1 npm run test:e2e:pr
+E2E_QUIET=1 npm run test:e2e:nightly
+```
+
+Each scenario writes a JUnit XML report under `e2e-reports/`.
+
+For one-time chain setup, see [E2E test setup](./e2e-bootstrap.md).
+
+## CI matrices
+
+`.github/workflows/e2e.yml` calls the shipped reusable `.github/workflows/deploy.yml` so the E2E jobs exercise the same path consumers use.
+
+- per-PR: stable happy-path coverage plus negative ownership coverage
+- nightly: broader signer, merkleization, and mirror-path coverage
+
+E2E deploys are tagged so telemetry can distinguish them from real-user traffic. See [Telemetry](./telemetry.md).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bulletin-deploy",
-  "version": "0.7.4",
+  "version": "0.7.6",
   "private": false,
   "repository": {
     "type": "git",
@@ -14,7 +14,8 @@
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "bin": {
-    "bulletin-deploy": "./bin/bulletin-deploy"
+    "bulletin-deploy": "./bin/bulletin-deploy",
+    "bulletin-bootstrap": "./bin/bulletin-bootstrap"
   },
   "exports": {
     ".": {
@@ -24,12 +25,13 @@
   },
   "files": [
     "dist",
-    "bin"
+    "bin",
+    "docs"
   ],
   "scripts": {
     "build": "tsup src/index.ts src/deploy.ts src/dotns.ts src/pool.ts src/telemetry.ts src/memory-report.ts src/merkle.ts src/gh-pages-mirror.ts src/version-check.ts src/bug-report.ts src/run-state.ts --format esm --dts --clean --target node22",
     "prepare": "npm run build",
-    "test": "npm run build && node --test test/test.js test/pool.test.js test/helpers/e2e-helpers.test.js",
+    "test": "npm run build && node --test test/test.js test/cli-help.test.js test/helpers/e2e-helpers.test.js",
     "test:e2e": "npm run build && node --test test/e2e.test.js",
     "test:e2e:smoke": "bash scripts/e2e-pass.sh smoke",
     "test:e2e:pr": "bash scripts/e2e-pass.sh pr",