bulletin-deploy 0.7.5 → 0.7.6

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.5",
+  "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",