@parity/product-deploy 0.8.1 → 0.8.2-rc.1

package/README.md

@@ -1,233 +1,5 @@
 # bulletin-deploy
 
-`bulletin-deploy` publishes a static web app to Bulletin and binds it to a human-readable `.dot` domain.
+Early alpha code, stay tuned.
 
-The main CLI is deploy-only. Pool bootstrap and other operator setup live in [`bulletin-bootstrap`](docs/bootstrap.md).
-
-## Quick Start
-
-```bash
-npm install -g bulletin-deploy
-
-# Build your app first, then deploy it.
-bulletin-deploy ./dist my-app00.dot
-```
-
-On success, the CLI prints the CID and the `.dot` domain that now serves your app.
-
-## Installation
-
-- **Node.js 22+**
-- **IPFS Kubo** if you want the default merkleization path
-
-```bash
-# macOS
-brew install ipfs
-ipfs init
-
-# Linux
-wget https://dist.ipfs.tech/kubo/v0.33.0/kubo_v0.33.0_linux-amd64.tar.gz
-tar -xvzf kubo_v0.33.0_linux-amd64.tar.gz
-sudo bash kubo/install.sh
-ipfs init
-```
-
-If you do not want a Kubo dependency, pass `--js-merkle`.
-
-Stable installs:
-
-- `npm install -g bulletin-deploy`
-- `npm install -g bulletin-deploy@latest`
-
-Release candidates:
-
-- `npm install -g bulletin-deploy@rc`
-- `npm install -g bulletin-deploy@<exact-version>`
-
-## CLI Usage
-
-```bash
-bulletin-deploy <build-dir> <domain.dot>
-```
-
-Examples:
-
-```bash
-# Basic deploy (defaults to --env paseo-next-v2)
-bulletin-deploy ./dist my-app00.dot
-
-# Pick a different environment
-bulletin-deploy ./dist my-app00.dot --env paseo-review
-
-# List supported environments
-bulletin-deploy --list-environments
-
-# Refresh the environments cache before deploying
-bulletin-deploy ./dist my-app00.dot --refresh-environments --env paseo-next-v2
-
-# Direct signer deploy
-bulletin-deploy ./dist my-app00.dot --mnemonic "..."
-
-# Custom Bulletin RPC override (asset-hub still comes from --env)
-bulletin-deploy ./dist my-app00.dot --rpc wss://custom-bulletin.example.com
-```
-
-### Selecting an environment
-
-`--env <id>` selects a target environment by id. The list of environments and their RPC endpoints is sourced dynamically from [`paritytech/bulletin-deploy/assets/environments.json`](./assets/environments.json), which mirrors [`paritytech/triangle-status/environments.json`](https://github.com/paritytech/triangle-status/blob/main/environments.json) (the latter is private; bulletin-deploy serves as the public mirror).
-
-| Env id | Network | Bulletin available? |
-|---|---|---|
-| `paseo-next-v2` (default) | testnet | yes |
-| `paseo-next` | testnet | yes |
-| `paseo-review` | testnet | yes |
-| `previewnet` | testnet | yes |
-| `polkadot` | mainnet | not yet |
-| `kusama` | mainnet | not yet |
-
-A single env id drives both the bulletin RPC and the asset-hub RPC used internally for DotNS, so they cannot drift. When you pass `--rpc`, it overrides only the bulletin endpoint within the chosen env; the asset-hub endpoint still comes from `--env`.
-
-The runtime uses a 24-hour cache at `${XDG_CACHE_HOME:-~/.cache}/bulletin-deploy/environments.json`; `--refresh-environments` busts it and re-fetches. The npm tarball ships a bundled snapshot that is used when the live URL is unreachable.
-
-### Options
-
-| Flag | What it does |
-|---|---|
-| `--env <id>` | Target environment. Default: `paseo-next-v2`. See `--list-environments` for valid ids. |
-| `--list-environments` | Print the environments table and exit. |
-| `--refresh-environments` | Bust the cache and re-fetch environments.json. Composes with `--env` (refresh-then-deploy) or runs solo. |
-| `--rpc wss://...` | Override the Bulletin RPC endpoint within the chosen `--env`. Also readable from `BULLETIN_RPC`. |
-| `--mnemonic "..."` | Use a specific mnemonic as the direct signer for Bulletin uploads and DotNS updates. Also readable from `MNEMONIC`. |
-| `--derivation-path "..."` | Apply a Substrate derivation path to `--mnemonic`, for example `//deploy/3`. |
-| `--pool-size N` | Change the number of derived pool accounts available for pool-mode Bulletin uploads. Default: `10`. |
-| `--password "..."` | Encrypt SPA content before upload. Consumers must provide the password to decrypt it. |
-| `--js-merkle` | Use pure-JS merkleization instead of the Kubo binary. |
-| `--tag "..."` | Attach a free-form telemetry label. Also readable from `DEPLOY_TAG`. |
-| `--gh-pages-mirror` | After a successful deploy, push the generated CAR to the current repo's `gh-pages` branch as an HTTP mirror. |
-| `--input-car <path>` | Deploy from a pre-built CAR file instead of a build directory. Skips merkleization; reads the root CID from the CAR header. Usage: `bulletin-deploy --input-car site.car my-app.dot` |
-| `--version` | Print the CLI version. |
-| `--help` | Show help. |
-
-## Concepts
-
-- `Bulletin`: the chain that stores the app payload in chunked transaction storage.
-- `.dot domain`: the DotNS name that points at the deployed content.
-- `CAR`: the content-addressed archive produced from your build output before upload.
-- `merkleization`: turning a directory into a content-addressed DAG and CAR file.
-- `pool accounts`: derived Bulletin uploader accounts used to spread nonce and authorization load.
-- `PoP`: Proof of Personhood, which some `.dot` names require before registration.
-
-## Incremental Upload
-
-After the first deploy of a `.dot` domain, every subsequent deploy automatically reuses chunks already stored on Bulletin instead of re-uploading them. There is no flag to enable; it just runs.
-
-How it works:
-
-1. The previous deploy embeds a manifest at `.bulletin-deploy/manifest.json` inside the deployed content (file classification, block ordering, chunk metadata).
-2. The new deploy fetches the previous contenthash from DotNS, then fetches that manifest via the Bulletin IPFS gateway.
-3. The new build's CAR is sliced into chunks; each chunk's CID is HEAD-probed against the gateway. Chunks already present are skipped.
-4. Only the chunks that actually changed (typically: the manifest itself and any modified content) are uploaded.
-
-The summary line at the end of a deploy shows the savings:
-
-```
-Cache:
-  Manifest:    embedded (1 attempt)
-  Probed:      18 chunks  →  15 cached, 2 to upload, 1 probe-failed
-  Recycled:    3 CIDs found on-chain that weren't in the previous manifest
-  Saved:       ~52s and 14.3 MB upload
-```
-
-CI runners benefit identically — no `actions/cache` wiring required, because the manifest travels with the deployed content rather than living on the runner's disk.
-
-**Encrypted deploys** (`--password`) bypass the incremental path. Encryption produces non-deterministic CAR bytes per run, so chunk-level dedup can't apply.
-
-**Force a full re-upload** by deleting `.bulletin-deploy/` from your build output (or changing one byte in any non-volatile file) before deploying. The classifier treats `.bulletin-deploy/` paths as volatile, so removing the manifest forces the next deploy to fall back to the heuristic classifier.
-
-## Domain Rules
-
-DotNS classifies labels on-chain and may require a specific Proof of Personhood level before registration.
-
-Typical cases:
-
-| Domain pattern | Typical classification |
-|---|---|
-| Base name, for example `my-app.dot` | `ProofOfPersonhoodFull` |
-| Name with trailing digits, for example `my-app00.dot` | often `NoStatus`, but not guaranteed |
-
-Do not rely on the string shape alone. The on-chain classifier is authoritative.
-
-On testnets, `bulletin-deploy` self-grants PoP only when the classifier says it is needed. On mainnet, PoP cannot be self-granted.
-
-## GitHub Pages Mirror
-
-`--gh-pages-mirror` is an opt-in cache path for hosts that want an HTTP fetch path in addition to Bulletin.
-
-```bash
-bulletin-deploy ./dist my-app.dot --gh-pages-mirror
-```
-
-After a successful deploy, the CLI pushes:
-
-- `bulletin/<domain>.dot.car`
-- `bulletin/<domain>.dot.json`
-
-to the current repo's `gh-pages` branch and prints the Pages URL.
-
-Use it when you want to validate or consume the mirror feature. The source of truth remains Bulletin plus DotNS.
-
-## Programmatic API
-
-```js
-import { deploy } from "bulletin-deploy";
-
-const result = await deploy("./dist", "my-app00.dot");
-console.log(result.cid, result.domainName);
-```
-
-For environments without Kubo:
-
-```js
-await deploy("./dist", "my-app00.dot", { jsMerkle: true });
-```
-
-## Environment Variables
-
-| Variable | Default | Description |
-|---|---|---|
-| `BULLETIN_RPC` | `wss://paseo-bulletin-rpc.polkadot.io` | Override the Bulletin chain WebSocket RPC for the chosen `--env`. |
-| `BULLETIN_ENVIRONMENTS_URL` | bulletin-deploy public mirror | Override the runtime URL for environments.json. Internal teams point this at a fork or local proxy. |
-| `BULLETIN_DEPLOY_TELEMETRY` | off for external users, on for internal users | `1` to opt in, `0` to force off |
-| `BULLETIN_DEPLOY_UPDATE_CHECK` | `1` | Set to `0` to disable version checks on failure |
-| `IPFS_CID` | unset | Skip storage and reuse an existing CID |
-| `DEPLOY_TAG` | unset | Telemetry label equivalent to `--tag` |
-| `BULLETIN_DEPLOY_HOST_APP` | unset | Name of the host app embedding bulletin-deploy (e.g. `playground-cli`). Sets `deploy.host_app` on telemetry spans. |
-| `BULLETIN_DEPLOY_HOST_APP_VERSION` | unset | Version of the host app. Sets `deploy.host_app_version` on telemetry spans when `BULLETIN_DEPLOY_HOST_APP` is also set. |
-
-## Troubleshooting
-
-| Error | What to check |
-|---|---|
-| `Requires Full Personhood verification` | The chosen label needs a higher PoP level. |
-| `Domain ... is owned by a different account` | The `.dot` name is already owned by the account indicated. Use that account as parameter or transfer the domain from that account to the new account you want to use |
-| `Account ... is not authorized for Bulletin storage` | The uploader account is not authorized on Bulletin yet. For operator-managed pools, see [`bulletin-bootstrap`](docs/bootstrap.md). |
-| `fetchNonce timed out` or connection errors | The Bulletin RPC may be unhealthy. Try another endpoint. |
-| `IPFS CLI not installed` | Install Kubo or switch to `--js-merkle`. |
-| Previous deploy did not exit cleanly / OOM hint | Retry with a larger Node heap, for example `NODE_OPTIONS='--max-old-space-size=8192'`. |
-
-## Contributing
-
-New to the codebase? Start with **[ONBOARDING.md](ONBOARDING.md)** — it covers install, the mental model, the first task, and the working conventions for this repo (worktree-per-branch, squash-merge policy, never-delete-tests, where the per-directory rules live).
-
-The team uses Claude Code as a primary tool. The repo ships team-shared Claude configuration: `.claude/skills/` (project-specific commands like `/e2e-local`, `/dotns-diagnose`, `/sentry-query`), `.claude/settings.json` (Bash allowlist), and per-directory `CLAUDE.md` files in `src/`, `sentry/`, `test/`, `tools/` that load on demand. Running `claude` inside this repo picks all of that up automatically.
-
-Already have Claude Code installed? Clone, `npm install`, open `ONBOARDING.md`. New to Claude Code itself? The same doc covers install.
-
-For maintainers and engineers familiar with the release flow, the canonical procedures live in the root [`CLAUDE.md`](CLAUDE.md): change workflow, dual-stage RC → stable release, post-release Sentry monitoring, and the squash-merge convention that satisfies branch protection without per-commit GPG signing.
-
-## More Docs
-
-- [Bootstrap and operator setup](docs/bootstrap.md)
-- [Testing](docs/testing.md)
-- [Telemetry](docs/telemetry.md)
-- [E2E one-time setup](docs/e2e-bootstrap.md)
+Full documentation and contributing guide: [docs-internal/README.dev.md](docs-internal/README.dev.md)

package/assets/environments.json

@@ -11,6 +11,12 @@
       "autoAccountMapping": true,
       "nativeToEthRatio": 100000000,
       "registerStorageDeposit": 2000000000000,
+      "popSelfServe": {
+        "sudoEnvLabel": "Preview",
+        "personhoodFaucetUrl": "https://sudo.personhood.dev/personhood-faucet",
+        "dotnsBootstrapUrl": "https://sudo.personhood.dev/dotns-bootstrap",
+        "stateAwareGuidance": true
+      },
       "contracts": {
         "DOTNS_PROTOCOL_REGISTRY": "0x984F17a9077808F4B7e127F76806A1D59546B5B6",
         "DOTNS_REGISTRAR": "0x061273AeF34e8ab9Ca08E199d7440E2639Fc2088",

package/bin/bulletin-deploy

@@ -42,6 +42,7 @@ for (let i = 0; i < args.length; i++) {
     }
     (flags.contracts ??= {})[kv.slice(0, eq)] = kv.slice(eq + 1);
   }
+  else if (args[i] === "--environment-file") { flags.environmentFile = args[++i]; }
   else if (args[i] === "--list-environments") { flags.listEnvironments = true; }
   else if (args[i] === "--password") { flags.password = args[++i]; }
   else if (args[i] === "--js-merkle") { flags.jsMerkle = true; }
@@ -67,6 +68,12 @@ if (flags.publish && flags.unpublish) {
   process.exit(1);
 }
 
+// --environment-file: propagate to the env var so all internal loadEnvironments()
+// call sites (deploy.ts, manifest/publish.ts, personhood) honor the override.
+if (flags.environmentFile) {
+  process.env.BULLETIN_DEPLOY_ENV_FILE = flags.environmentFile;
+}
+
 if (flags.version) {
   console.log(`bulletin-deploy v${VERSION}`);
   process.exit(0);
@@ -81,7 +88,7 @@ if (flags.removedBootstrap) {
 // nothing else (deploy positional args are ignored).
 if (flags.listEnvironments) {
   try {
-    const { doc } = await loadEnvironments();
+    const { doc } = await loadEnvironments({ userFilePath: flags.environmentFile ?? process.env.BULLETIN_DEPLOY_ENV_FILE });
     console.log(formatEnvironmentTable(listEnvironments(doc)));
     process.exit(0);
   } catch (e) {
@@ -169,6 +176,13 @@ Options:
   --env <id>               Target environment from environments.json (default: paseo-next-v2).
                            Drives both the bulletin RPC and the asset-hub RPC used
                            by DotNS. See --list-environments for valid ids.
+  --environment-file <path>
+                           Path to a JSON file deep-merged over the bundled
+                           environments.json. Override only the fields you need
+                           (e.g. contract addresses after a chain reset); unspecified
+                           fields fall through to the bundled values. Also honored
+                           via BULLETIN_DEPLOY_ENV_FILE env var.
+                           Warning: values are not validated against chain.
   --list-environments      Print the environments table and exit.
   --contract <KEY>=<addr>  Supply/override a DotNS contract address (repeatable).
                            Merged over the chosen --env's contracts map; required

package/dist/bug-report.js

@@ -9,10 +9,10 @@ import {
   offerBugReport,
   scrubSecrets,
   setDeployContext
-} from "./chunk-MXMVZU2Q.js";
-import "./chunk-O2BFXY3Y.js";
-import "./chunk-INVA3XGG.js";
-import "./chunk-V5N5EYNV.js";
+} from "./chunk-H64ZLWW2.js";
+import "./chunk-EJWZGSHD.js";
+import "./chunk-RIAMPAL2.js";
+import "./chunk-NJPBXF5Z.js";
 export {
   buildCliFlagsSummary,
   buildLabels,

package/dist/{chunk-IRT4A7OO.js → chunk-2GBSYVK2.js}

@@ -1,6 +1,6 @@
 import {
   isTestnetSpecName
-} from "./chunk-RW3GWDGI.js";
+} from "./chunk-JQ5X3VMP.js";
 import {
   captureWarning,
   markCodePath,
@@ -8,10 +8,10 @@ import {
   setDeploySentryTag,
   truncateAddress,
   withSpan
-} from "./chunk-INVA3XGG.js";
+} from "./chunk-RIAMPAL2.js";
 import {
   validateContractAddresses
-} from "./chunk-CNPB4VAM.js";
+} from "./chunk-5K3RI5C2.js";
 import {
   NonRetryableError
 } from "./chunk-ZOC4GITL.js";
@@ -60,6 +60,10 @@ var FEE_FLOOR_REGISTER = ONE_PAS / 10n;
 var TOP_UP_TARGET = ONE_PAS / 2n;
 var SOURCE_BUFFER = ONE_PAS;
 var MINIMUM_REGISTER_STORAGE_DEPOSIT = 2000000000000n;
+var REGISTER_RENT_PRICE_WEI = 10n * 10n ** 18n;
+function bufferedRentNative(nativeToEthRatio) {
+  return REGISTER_RENT_PRICE_WEI * 110n / (100n * nativeToEthRatio);
+}
 var REPROVE_FEE_ESTIMATE = ONE_PAS / 100n;
 var REPROVE_FEE_SAFETY_MARGIN_PCT = 110n;
 var TOP_UP_TRANSFER_TIMEOUT_MS = 6e4;
@@ -74,13 +78,13 @@ function resolveNativeTokenSymbol(envId) {
   if (envId.includes("rococo")) return "ROC";
   return "PAS";
 }
-function feeFloorFor(plannedAction, storageDeposit = MINIMUM_REGISTER_STORAGE_DEPOSIT) {
+function feeFloorFor(plannedAction, storageDeposit = MINIMUM_REGISTER_STORAGE_DEPOSIT, rentPriceNative = 0n) {
   if (plannedAction === "already-owned-by-us") return FEE_FLOOR_OWNED;
-  return FEE_FLOOR_REGISTER + storageDeposit;
+  return FEE_FLOOR_REGISTER + storageDeposit + rentPriceNative;
 }
-function topUpTargetFor(plannedAction, storageDeposit = MINIMUM_REGISTER_STORAGE_DEPOSIT) {
+function topUpTargetFor(plannedAction, storageDeposit = MINIMUM_REGISTER_STORAGE_DEPOSIT, rentPriceNative = 0n) {
   if (plannedAction === "already-owned-by-us") return TOP_UP_TARGET;
-  return TOP_UP_TARGET + storageDeposit;
+  return TOP_UP_TARGET + storageDeposit + rentPriceNative;
 }
 var RPC_ENDPOINTS = [
   "wss://asset-hub-paseo.dotters.network",
@@ -120,6 +124,30 @@ function classifyTxRetryDecision(err) {
   if (lower.includes("transaction watcher silent")) return "retry";
   return "abort";
 }
+var DOTNS_RETRY_BASE_MS = 400;
+var DOTNS_RETRY_MAX_MS = 6e3;
+function dotnsRetryBackoffMs(attempt, rand = Math.random) {
+  const ceil = Math.min(DOTNS_RETRY_BASE_MS * 2 ** (attempt - 1), DOTNS_RETRY_MAX_MS);
+  return Math.round(ceil * (0.5 + rand() * 0.5));
+}
+function makeRetryStatusFilter(sink) {
+  let buffered = false;
+  return {
+    callback: (status) => {
+      if (status === "failed") {
+        buffered = true;
+        return;
+      }
+      sink(status);
+    },
+    flush: () => {
+      if (buffered) sink("failed");
+    },
+    reset: () => {
+      buffered = false;
+    }
+  };
+}
 var DEFAULT_MNEMONIC = "bottom drive obey lake curtain smoke basket hold race lonely fit walk";
 var _rpcIdCounter = 0;
 async function fetchNonceFromEndpoint(rpc, ss58Address) {
@@ -533,7 +561,13 @@ var ReviveClientWrapper = class _ReviveClientWrapper {
   async getEvmAddress(substrateAddress) {
     if (isAddress(substrateAddress)) return substrateAddress;
     const address = await this.client.apis.ReviveApi.address(substrateAddress);
-    return convertToHexString(address);
+    const hex = convertToHexString(address);
+    if (!hex || hex === "0x") {
+      throw new Error(
+        "ReviveApi.address returned empty result \u2014 RPC node may not support pallet-revive; try a different endpoint via DOTNS_RPC"
+      );
+    }
+    return hex;
   }
   async performDryRunCall(originSubstrateAddress, contractAddress, value, encodedData) {
     if (isAddress(originSubstrateAddress)) throw new Error("performDryRunCall requires SS58 Substrate address, not EVM H160 address");
@@ -554,6 +588,21 @@ var ReviveClientWrapper = class _ReviveClientWrapper {
     if (!result.result.isOk) return { success: false, gasConsumed: result.gasConsumed, storageDeposit: result.storageDeposit.value, gasRequired: result.gasRequired, revertData: result.result.value.data, revertFlags: result.result.value.flags };
     return { success: true, gasConsumed: result.gasConsumed, storageDeposit: result.storageDeposit.value, gasRequired: result.gasRequired };
   }
+  // Returns true if the address holds contract code, false if it provably does
+  // not, and null if this runtime doesn't expose the storage map (caller must
+  // not treat null as "no code"). Used to disambiguate an empty-success (`0x`)
+  // contract read: on pallet-revive, calling an address with no code succeeds
+  // with empty return data, so empty `0x` from a read almost always means the
+  // configured contract address is wrong/undeployed rather than a real "unset".
+  async hasContractCode(address) {
+    try {
+      const info = await this.client.query.Revive.AccountInfoOf.getValue(address);
+      if (info === void 0 || info === null) return false;
+      return info.account_type?.type === "Contract";
+    } catch {
+      return null;
+    }
+  }
   async checkIfAccountMapped(substrateAddress) {
     try {
       const evmAddress = await this.getEvmAddress(substrateAddress);
@@ -699,18 +748,23 @@ var ReviveClientWrapper = class _ReviveClientWrapper {
     });
   }
   async signAndSubmitWithRetry(buildExtrinsic, signer, statusCallback, label, opts = {}) {
+    const filter = makeRetryStatusFilter(statusCallback);
     let lastError;
     for (let attempt = 1; attempt <= DOTNS_TX_MAX_ATTEMPTS; attempt++) {
+      filter.reset();
       try {
-        return await this.signAndSubmitExtrinsic(buildExtrinsic(), signer, statusCallback, opts);
+        return await this.signAndSubmitExtrinsic(buildExtrinsic(), signer, filter.callback, opts);
       } catch (e) {
         lastError = e;
         const decision = classifyTxRetryDecision(e);
         if (decision === "abort" || attempt === DOTNS_TX_MAX_ATTEMPTS) break;
+        const ms = dotnsRetryBackoffMs(attempt);
         const short = (e?.message ?? String(e)).slice(0, 80);
-        console.log(`   ${label}: attempt ${attempt}/${DOTNS_TX_MAX_ATTEMPTS} failed (${short}), retrying...`);
+        console.log(`   ${label}: attempt ${attempt}/${DOTNS_TX_MAX_ATTEMPTS} failed (${short}), retrying in ${ms}ms\u2026`);
+        await new Promise((r) => setTimeout(r, ms));
       }
     }
+    filter.flush();
     throw lastError instanceof Error ? lastError : new Error(String(lastError));
   }
   // Dry-runs one Revive.call and returns the chain-side limits the live
@@ -841,6 +895,15 @@ function classifyAliasAccountRow(row) {
   }
   return { state: "wrong-context", storedContextHex: contextHex, revision };
 }
+function formatSelfServeSteps(popSelfServe) {
+  const steps = [];
+  if (popSelfServe.faucetUrl) {
+    steps.push(`Fund the service account mnemonic via ${popSelfServe.faucetUrl}`);
+  }
+  steps.push(`Go to ${popSelfServe.personhoodFaucetUrl}, pick your env (e.g. ${popSelfServe.sudoEnvLabel}), and paste the mnemonic`);
+  steps.push(`Go to ${popSelfServe.dotnsBootstrapUrl} and follow each step (first and last can probably be skipped)`);
+  return steps.map((s, i) => `  ${i + 1}. ${s}`).join("\n");
+}
 function formatPersonhoodRemediation(state, popSelfServe, environmentId) {
   if (!popSelfServe?.stateAwareGuidance) {
     return "Self-attestation is no longer available. Contact the DotNS team for whitelisting / Personhood status help.";
@@ -848,9 +911,7 @@ function formatPersonhoodRemediation(state, popSelfServe, environmentId) {
   switch (state.state) {
     case "not-bound":
       return `Your account has no DotNS alias binding on ${environmentId ?? "this environment"}. On testnets you can self-serve:
-  1. Fund the service account mnemonic via ${popSelfServe.faucetUrl}
-  2. Go to ${popSelfServe.personhoodFaucetUrl}, pick your env (e.g. ${popSelfServe.sudoEnvLabel}), and paste the mnemonic
-  3. Go to ${popSelfServe.dotnsBootstrapUrl} and follow each step (first and last can probably be skipped)`;
+` + formatSelfServeSteps(popSelfServe);
     case "bound-likely-stale":
       return `Your alias binding exists but may have a stale ring revision. Run \`node tools/reprove-alias.mjs --mnemonic <your-mnemonic> --env ${environmentId ?? "this environment"}\` to refresh the proof, then retry the registration.`;
     case "wrong-context":
@@ -868,12 +929,7 @@ function formatPopShortfallReason(opts) {
       const state = aliasState ?? { state: "not-bound" };
       testnetBlock = "\n\n" + formatPersonhoodRemediation(state, popSelfServe, environmentId);
     } else {
-      testnetBlock = `
-
-On testnets you can self-serve:
-  1. Fund the service account mnemonic via ${popSelfServe.faucetUrl}
-  2. Go to ${popSelfServe.personhoodFaucetUrl}, pick your env (e.g. ${popSelfServe.sudoEnvLabel}), and paste the mnemonic
-  3. Go to ${popSelfServe.dotnsBootstrapUrl} and follow each step (first and last can probably be skipped)`;
+      testnetBlock = "\n\nOn testnets you can self-serve:\n" + formatSelfServeSteps(popSelfServe);
     }
   }
   const alternativesBlock = `
@@ -987,12 +1043,16 @@ var DotNS = class {
         );
         console.log(`   H160 Address: ${this.evmAddress}`);
       } catch (e) {
-        throw new Error(`DotNS connect: failed to resolve EVM address from ${this.substrateAddress} via ReviveApi.address (${e.message?.slice(0, 200)})`);
+        const inner = e.message?.slice(0, 200) ?? String(e).slice(0, 200);
+        const rpcHint = inner.includes("timed out") ? `; RPC: ${rpc} \u2014 retry or set DOTNS_RPC to another endpoint` : "";
+        throw new Error(
+          `DotNS connect: failed to resolve EVM address from ${this.substrateAddress} via ReviveApi.address (${inner})${rpcHint}`
+        );
       }
       setDeployAttribute("deploy.dotns.rpc_used", rpc);
       setDeployAttribute("deploy.dotns.evm_address", this.evmAddress);
       this.connected = true;
-      if (options.nativeToEthRatio) this._nativeToEthRatio = options.nativeToEthRatio;
+      await this.resolveNativeToEthRatio(options);
       try {
         await this.ensureMappedAccountReady(options.autoAccountMapping ?? false);
       } catch (e) {
@@ -1092,6 +1152,35 @@ var DotNS = class {
   ensureConnected() {
     if (!this.connected) throw new Error("Not connected. Call connect() first.");
   }
+  /**
+   * Resolve the authoritative nativeToEthRatio for this session.
+   *
+   * Priority: chain constant (Revive.NativeToEthRatio) > options.nativeToEthRatio > default.
+   * On mismatch between the env-configured value and the chain value, logs a WARNING naming
+   * both values and proceeds with the chain value (it is the source of truth).
+   * On query failure, falls back to the configured/default value without throwing.
+   *
+   * Must be called after clientWrapper is established (i.e. inside connect()).
+   */
+  async resolveNativeToEthRatio(options) {
+    const configuredRatio = options.nativeToEthRatio ?? NATIVE_TO_ETH_RATIO;
+    this._nativeToEthRatio = configuredRatio;
+    if (!this.clientWrapper) return;
+    try {
+      const chainValue = await this.clientWrapper.client.constants.Revive.NativeToEthRatio();
+      const chainRatio = BigInt(chainValue);
+      if (chainRatio !== configuredRatio) {
+        const msg = `DotNS: Revive.NativeToEthRatio from chain (${chainRatio}) differs from configured value (${configuredRatio}); using chain value`;
+        console.warn(msg);
+        captureWarning("nativeToEthRatio mismatch: chain value overrides env config", {
+          chain_value: String(chainRatio),
+          configured_value: String(configuredRatio)
+        });
+      }
+      this._nativeToEthRatio = chainRatio;
+    } catch {
+    }
+  }
   // Returns true when the DotNS chain (Asset Hub) reports a testnet spec_name.
   // Used to gate test-only behaviors like self-granting Full PoP on a Lite
   // signer for a NoStatus label.
@@ -1280,7 +1369,25 @@ var DotNS = class {
         contracts: this._contracts
       }));
     }
-    return decodeFunctionResult({ abi: contractAbi, functionName, data: callResult.result.value.data });
+    const rawData = callResult.result.value.data ?? "0x";
+    if (rawData.length <= 2) {
+      const hasCode = await this.clientWrapper.hasContractCode(contractAddress);
+      const name = dotnsContractName(contractAddress, this._contracts);
+      if (hasCode === false) {
+        throw new Error(
+          `No contract deployed at ${contractAddress} (${name}) \u2014 the dry-run call to ${functionName} returned empty success data, which on pallet-revive means the target address has no contract code. Check environments.json / --contract config for this network.`
+        );
+      }
+      if (hasCode === null) {
+        throw new Error(
+          `Contract call returned empty data \u2014 contract=${name} (${contractAddress}) functionName=${functionName}. Could not verify whether contract code exists at this address (runtime code-presence query failed); investigate the contract/ABI or the configured address.`
+        );
+      }
+      throw new Error(
+        `Contract call returned empty data \u2014 contract=${name} (${contractAddress}) functionName=${functionName}. The address has contract code but the call returned no bytes, which is unexpected for this read. Investigate the contract/ABI rather than masking it with a default.`
+      );
+    }
+    return decodeFunctionResult({ abi: contractAbi, functionName, data: rawData });
   }
   /**
    * Like contractCall, but returns null when the chain replies with empty data
@@ -1314,7 +1421,7 @@ var DotNS = class {
       }));
     }
     const rawData = callResult.result.value.data ?? "0x";
-    if (rawData === "0x" || rawData === "" || rawData.length <= 2) return null;
+    if (rawData.length <= 2) return null;
     return decodeFunctionResult({ abi: contractAbi, functionName, data: rawData });
   }
   async contractTransaction(contractAddress, value, contractAbi, functionName, args = [], statusCallback = () => {
@@ -1422,7 +1529,7 @@ var DotNS = class {
       if (txResolution.kind === TX_KIND_HASH) {
         setDeployAttribute("deploy.subnode.tx", txResolution.hash);
         if (txResolution.block) {
-          setDeployAttribute("deploy.subnode.block", txResolution.block.number);
+          setDeployAttribute("deploy.subnode.block", String(txResolution.block.number));
           setDeployAttribute("deploy.subnode.block_hash", txResolution.block.hash);
           console.log(`      finalised @ block ${txResolution.block.number} (tx ${txResolution.hash})`);
         } else {
@@ -1561,7 +1668,7 @@ var DotNS = class {
       if (txRes.kind === TX_KIND_HASH) {
         setDeployAttribute("deploy.contenthash.tx", txRes.hash);
         if (txRes.block) {
-          setDeployAttribute("deploy.contenthash.block", txRes.block.number);
+          setDeployAttribute("deploy.contenthash.block", String(txRes.block.number));
           setDeployAttribute("deploy.contenthash.block_hash", txRes.block.hash);
           console.log(`      finalised @ block ${txRes.block.number} (tx ${txRes.hash})`);
         } else {
@@ -1979,9 +2086,7 @@ var DotNS = class {
     const reservationInfo = await withTimeout(this.contractCall(this._contracts.POP_RULES, POP_RULES_ABI, "isBaseNameReserved", [baseName]), 3e4, "isBaseNameReserved");
     const [isReserved, reservationOwner] = reservationInfo;
     if (isReserved && reservationOwner.toLowerCase() !== this.evmAddress.toLowerCase()) throw new Error("Base name reserved for original Lite registrant");
-    const classificationResult = await withTimeout(this.contractCall(this._contracts.POP_RULES, POP_RULES_ABI, "classifyName", [label]), 3e4, "classifyName");
-    const requiredStatus = typeof classificationResult[0] === "bigint" ? Number(classificationResult[0]) : classificationResult[0];
-    const message = classificationResult[1];
+    const { requiredStatus, message } = await this.classifyName(label);
     const userStatus = await this.getUserPopStatus();
     if (requiredStatus === ProofOfPersonhoodStatus.Reserved) throw new Error(message);
     if (!canRegister(requiredStatus, userStatus)) {
@@ -2021,7 +2126,7 @@ var DotNS = class {
     if (registerTxRes.kind === TX_KIND_HASH) {
       setDeployAttribute("deploy.register.tx", registerTxRes.hash);
       if (registerTxRes.block) {
-        setDeployAttribute("deploy.register.block", registerTxRes.block.number);
+        setDeployAttribute("deploy.register.block", String(registerTxRes.block.number));
         setDeployAttribute("deploy.register.block_hash", registerTxRes.block.hash);
         console.log(`      finalised @ block ${registerTxRes.block.number} (tx ${registerTxRes.hash})`);
       } else {
@@ -2271,13 +2376,14 @@ var DotNS = class {
   // canProceed:true result with an actionable canProceed:false when even the
   // top-up can't get the signer above the threshold.
   async gateOnFeeBalance(candidate, signerFreeBalance, isTestnet) {
-    const feeFloor = feeFloorFor(candidate.plannedAction, this._registerStorageDeposit);
+    const rentPriceNative = candidate.plannedAction === "register" ? bufferedRentNative(this._nativeToEthRatio) : 0n;
+    const feeFloor = feeFloorFor(candidate.plannedAction, this._registerStorageDeposit, rentPriceNative);
     let effectiveBalance = signerFreeBalance;
     let toppedUp;
     if (effectiveBalance < feeFloor && isTestnet) {
       setDeployAttribute("deploy.dotns.signer_below_floor", "true");
       console.log(`   DotNS signer ${this.substrateAddress?.slice(0, 8)}... balance ${fmtPas(effectiveBalance)} PAS < ${fmtPas(feeFloor)} PAS floor \u2014 attempting testnet auto top-up...`);
-      const result = await this.attemptTestnetTopUp(this.substrateAddress, topUpTargetFor(candidate.plannedAction, this._registerStorageDeposit));
+      const result = await this.attemptTestnetTopUp(this.substrateAddress, topUpTargetFor(candidate.plannedAction, this._registerStorageDeposit, rentPriceNative));
       if (result) {
         console.log(`   Topped up ${fmtPas(result.transferred)} PAS from ${result.source}`);
         effectiveBalance += result.transferred;
@@ -2462,6 +2568,8 @@ export {
   WS_HEARTBEAT_TIMEOUT_MS,
   DOTNS_TX_MAX_ATTEMPTS,
   classifyTxRetryDecision,
+  dotnsRetryBackoffMs,
+  makeRetryStatusFilter,
   DEFAULT_MNEMONIC,
   fetchNonce,
   verifyNonceAdvanced,