@parity/product-deploy 0.10.0-rc.3 → 0.10.0

package/DEPLOYMENT.md

@@ -1,124 +1,102 @@
-# Deploying your first app
+# Setting up an environment
 
-This guide walks you from zero to a deployed, viewable web app on the [Polkadot Bulletin Chain](https://github.com/paritytech/polkadot-bulletin-chain) testnet, using `bulletin-deploy`.
+This guide is for the **operator / chain admin** standing up `bulletin-deploy` against a Polkadot environment. It covers what you configure and authorize so that deploys work against *your* chain.
 
-> [!NOTE]
-> This targets a **testnet** (`paseo-next-v2`) by default. It is reference/proof-of-concept tooling — see the security notice in the [README](README.md#security).
-
-## Prerequisites
+For **using** the tool once an environment is set up — building and shipping an app — see the [README](README.md). This document is the setup side.
 
-1. **Node.js ≥ 22.**
-   ```sh
-   node --version   # must print v22 or higher
-   ```
-2. **The CLI**, installed globally:
-   ```sh
-   npm install -g bulletin-deploy
-   ```
-3. **A built static site** — a directory of static files (HTML/CSS/JS), for example `./dist`. Build your app however you normally would (`npm run build`, etc.); `bulletin-deploy` uploads the resulting directory as-is.
-4. **An identity to own the name** — choose one:
-   - **Mobile Polkadot wallet (recommended).** No mnemonic on disk; you sign in once by scanning a QR code. See [Sign in](#1-sign-in-recommended) below.
-   - **A testnet mnemonic.** Pass `--mnemonic "..."` (or set the `MNEMONIC` env var) instead of signing in.
+> [!NOTE]
+> `bulletin-deploy` is reference / proof-of-concept tooling — see the security notice in the [README](README.md#security). The defaults target Polkadot testnets.
 
-That is all you need on testnet. You do **not** need testnet funds for the recommended path: a worker account registers the name and uploads the content, then transfers ownership to your account as the final step.
+**Documentation map — read in order:**
+1. **[DEPLOYMENT.md](DEPLOYMENT.md)** (this doc) — set up `bulletin-deploy` for your environment.
+2. **[docs/bootstrap.md](docs/bootstrap.md)** — the `bulletin-bootstrap` reference (Bulletin storage authorization).
+3. **[docs/e2e-bootstrap.md](docs/e2e-bootstrap.md)** — a fully worked setup, end to end, for the E2E test environment.
 
-### Optional: IPFS / Kubo
+(Using the tool to ship an app — not setting it up — is the [README](README.md).)
 
-By default the CLI uses the [IPFS Kubo](https://docs.ipfs.tech/install/) binary to merkleize your site if it is on your `PATH`, and otherwise falls back to a pure-JavaScript implementation. You can force the pure-JS path (no binary required) with `--js-merkle`. If you see `IPFS CLI not installed`, either install Kubo or add `--js-merkle`.
+## What an "environment" is
 
-## Choosing a name
+A `bulletin-deploy` environment is three things, which it expects to already exist for your network:
 
-Apps are addressed by a DotNS name like `myapp.dot`. A few rules:
+- an **Asset Hub** (PolkaVM / `pallet-revive`) with the **DotNS** contracts deployed — names live here;
+- a **Bulletin Chain** — content (your site, chunked + content-addressed) is stored here;
+- an **IPFS gateway** — serves the stored content over HTTP.
 
-- The base label must be **at least 6 characters** (shorter labels are reserved).
-- Pick something not already registered. The CLI tells you during a deploy whether the name is available or already owned by you.
+Setup is: tell `bulletin-deploy` where those are, authorize the accounts that will write to the Bulletin Chain, and (if your DotNS gates registration) grant the registering account personhood. The steps below.
 
-## Deploy
+## 1. Define the environment
 
-### 1. Sign in (recommended)
+`bulletin-deploy` resolves environments from `environments.json`. The built-in presets ship in `assets/environments.json`:
 
 ```sh
-bulletin-deploy login    # scan the QR code with your Polkadot wallet app
-bulletin-deploy whoami   # confirm the signed-in address
+bulletin-deploy --list-environments      # list the built-in environment IDs
 ```
 
-If you would rather sign with a mnemonic, skip this and pass `--mnemonic` on the deploy command instead.
-
-### 2. Deploy your build directory
+Add your network either by adding an entry to `assets/environments.json`, or by supplying one at runtime:
 
 ```sh
-bulletin-deploy ./dist myapp.dot
-# or, without an IPFS binary installed:
-bulletin-deploy ./dist myapp.dot --js-merkle
+bulletin-deploy ./dist myapp.dot --environment-file ./my-env.json
+bulletin-deploy ./dist myapp.dot --env <id> --contract DOTNS_REGISTRAR=0x...   # override single fields
 ```
 
-The CLI will:
+An environment entry provides:
 
-1. Merkleize your directory into content-addressed chunks.
-2. Upload the chunks to the Bulletin Chain and wait for finality.
-3. Register `myapp.dot` in DotNS and point it at your content.
-4. Transfer ownership of the name to your signed-in account.
+- **Chain endpoints** — the `wss://` RPCs for at least the **bulletin** and **asset-hub** chains.
+- **DotNS contract addresses** — the contract set deployed on your Asset Hub (`DOTNS_REGISTRAR`, `POP_RULES`, the resolvers, `STORE_FACTORY`, …).
+- **`nativeToEthRatio`** — `10^(18 − native_decimals)`; e.g. a 10-decimal native token → `100000000`.
+- **`registerStorageDeposit`** — the DotNS registration deposit on your chain.
+- **`autoAccountMapping`** — whether the chain maps accounts to H160 automatically on first tx.
+- **`ipfs`** — the gateway that serves deployed content.
 
-On success it prints a summary:
+Use the `paseo-next-v2` and `summit` entries in `assets/environments.json` as worked examples to copy.
 
-```
-============================================================
-DEPLOYMENT COMPLETE!
-============================================================
-   - Polkadot Desktop: myapp.dot
-   - Polkadot Browser: https://myapp.dot.li
-```
+## 2. Authorize Bulletin storage
 
-### 3. View it
+Writing content to the Bulletin Chain requires each **storage account** to hold a `TransactionStorage` **authorization** — a quota of transactions and bytes. Storage is gated by this quota, **not by balance** (Bulletin has no fee model), so the storage accounts need no funds. `bulletin-deploy` never grants the authorization itself; the chain's **authorizer** must.
 
-- Open **`https://myapp.dot.li`** in any browser.
-- Or open **`myapp.dot`** directly in a Polkadot-aware browser/extension.
+The storage accounts are an upload **pool**, derived as `//deploy/0…N` from `BULLETIN_POOL_MNEMONIC` (default: the well-known `DEV_PHRASE`). The deploy path derives the **same** pool from that env var — so if you use a custom pool, set `BULLETIN_POOL_MNEMONIC` identically for both bootstrap and deploy, or they won't line up.
 
-## If the transfer step fails
-
-If your content uploads but the final ownership transfer fails, the name is registered by the worker and you can claim it separately:
+`bulletin-bootstrap` reports each pool account's authorization status, and — given an authorizer key — grants authorization to the ones that lack it:
 
 ```sh
-bulletin-deploy transfer myapp.dot              # → your signed-in account
-bulletin-deploy transfer myapp.dot --to 0x...   # → an explicit recipient
+bulletin-bootstrap --env <id>                        # list pool accounts + their authorization status
+bulletin-bootstrap --env <id> --authorizer "<seed>"  # grant authorization with the authorizer key
+bulletin-bootstrap --env <id> --pool-size 20         # inspect/authorize a larger pool
 ```
 
-## Choosing a different network
+On a **testnet** the authorizer defaults to `//Alice` (it holds authorization authority there), so no `--authorizer` is needed. On a **production** chain, pass `--authorizer` with the key that actually holds authorization authority — if it can't grant, the tool reports that rather than pretending. See [`docs/bootstrap.md`](docs/bootstrap.md) for the full reference.
 
-```sh
-bulletin-deploy --list-environments      # show available environment IDs
-bulletin-deploy ./dist myapp.dot --env <id>
-```
+## 3. Personhood (if your DotNS gates registration)
 
-The default is `paseo-next-v2`. Override individual fields with `--environment-file <path>` or `--contract KEY=0x...`.
+If your `POP_RULES` contract requires Proof-of-Personhood to register a base name, the **registering account** needs a PoP status granted by the `POP_RULES` owner. (NoStatus-eligible label shapes skip this — see the rules in your DotNS deployment.)
 
-## Bootstrapping your own storage pool
+- On Parity's testnets, request a grant by opening an issue on [paritytech/dotns](https://github.com/paritytech/dotns/issues).
+- On your own chain, your `POP_RULES` owner grants it out of band — `bulletin-deploy` cannot upgrade a signer.
 
-On `paseo-next-v2` and the other shared Parity testnets the upload pool is **already authorized** — you don't need to bootstrap anything to deploy. You only need this if you run your own setup: a custom pool mnemonic, your own Bulletin chain, or a testnet that was just reset (a wipe clears all authorizations).
+## 4. Fund the signing accounts
 
-Uploading content to the Bulletin Chain requires the storage account to hold a `TransactionStorage` authorization — a quota of transactions and bytes. `bulletin-deploy` never grants this itself; the account must be authorized by the chain's authorizer first. The separate `bulletin-bootstrap` CLI does that for a pool:
+The accounts that register and transfer names need a balance on your Asset Hub for DotNS fees:
 
-```sh
-bulletin-bootstrap --env <id>                 # authorize the default pool on an environment
-bulletin-bootstrap --env <id> --pool-size 20  # authorize a larger pool
-bulletin-bootstrap --mnemonic "<phrase>"      # authorize a custom pool's accounts
-```
+- **Public testnets** — use the faucet (e.g. [faucet.polkadot.io](https://faucet.polkadot.io/)).
+- **Restricted networks** — fund the accounts out of band; there is no public faucet.
+
+(These are the DotNS signing accounts on the Asset Hub — distinct from the Bulletin storage pool in step 2, which needs authorization, not funds.)
+
+## 5. Content gateway
+
+Deployed content is content-addressed (a CID) on the Bulletin Chain and served over HTTP by the IPFS gateway you set as `ipfs` in step 1. The `.dot` name resolves to that CID via DotNS. Parity's public testnets resolve a deployed name at `https://<name>.dot.li`; your environment uses whatever gateway / resolver you point it at.
+
+## 6. Verify the setup
 
-It derives the pool accounts, authorizes each one for storage, and funds them. On a testnet the authorizer is the dev account (`//Alice`); on a production chain the network's own authorizer must grant authorization — `bulletin-bootstrap` cannot self-authorize there. It's a one-time setup step, not part of a routine deploy. See [`docs/bootstrap.md`](docs/bootstrap.md) for the full operator reference.
+A **test deploy** is the real check — run one (see the [README](README.md)) and confirm it completes and resolves. Two failures map straight back to the steps above:
 
-## Signing modes, in short
+- `not authorized to upload` → the storage account lacks authorization (step 2).
+- a personhood / registration gate → the registering account needs PoP (step 3).
 
-- **Signed in (default):** a worker registers and uploads, then hands the name to your account — zero wallet signatures on testnet.
-- **`--no-transfer-to-signedin-user`:** sign every DotNS transaction with your mobile session instead.
-- **`--mnemonic "..."` / `MNEMONIC`:** use a mnemonic instead of a session.
+If you're working from a **clone of the repository** (not just the npm package), `tools/` has read-only diagnostics that take `--env <id>`: `check-bulletin-auth.mjs` (storage quotas), `check-balances.mjs` (balances + quota), `check-pop-status.mjs` (personhood), `probe-env-health.mjs` (RPC reachability). These ship with the repo, not the published package.
 
-## Troubleshooting
+A concrete, fully worked instance of this setup — for the E2E test environment — lives in [`docs/e2e-bootstrap.md`](docs/e2e-bootstrap.md).
 
-| Symptom | Cause / fix |
-|---|---|
-| `IPFS CLI not installed` | Install [Kubo](https://docs.ipfs.tech/install/), or add `--js-merkle`. |
-| Name rejected as reserved / too short | Use a base label of **6+ characters**. |
-| `Login session unavailable or expired` | Re-run `bulletin-deploy login`. |
-| Not authorized to upload | The storage account lacks a Bulletin `TransactionStorage` authorization. On `paseo-next-v2` the shared pool is already authorized; on your own setup, see [Bootstrapping your own storage pool](#bootstrapping-your-own-storage-pool). On a production chain, request authorization from the network's authorizer. |
+---
 
-For the full option reference, run `bulletin-deploy --help`.
+Once the environment is set up, day-to-day use is in the [README](README.md): build your site, `bulletin-deploy ./dist myapp.dot`, done.

package/bin/bulletin-bootstrap

@@ -13,6 +13,7 @@ const flags = {};
 for (let i = 0; i < args.length; i++) {
   if (args[i] === "--pool-size") { flags.poolSize = parseInt(args[++i], 10); }
   else if (args[i] === "--mnemonic") { flags.mnemonic = args[++i]; }
+  else if (args[i] === "--authorizer") { flags.authorizer = args[++i]; }
   else if (args[i] === "--rpc") { flags.rpc = args[++i]; }
   else if (args[i] === "--env") { flags.env = args[++i]; }
   else if (args[i] === "--version" || args[i] === "-V") { flags.version = true; }
@@ -32,17 +33,27 @@ if (flags.help) {
   console.log(`bulletin-bootstrap v${VERSION}
 
 Usage:
-  bulletin-bootstrap
+  bulletin-bootstrap [options]
+
+Reports the authorization status of each pool account and, when an authorizer
+key is available, grants authorization to any account that needs it.
+
+The Bulletin chain has no fee model — storage access is gated by TransactionStorage
+authorization quota, not account balance. This tool manages that quota.
 
 Options:
-  --mnemonic "..."  Pool root mnemonic (or set BULLETIN_POOL_MNEMONIC / MNEMONIC env var)
-  --rpc wss://...   Bulletin RPC (or set BULLETIN_RPC env var)
-  --env <id>        Load environment by id from environments.json (sets default RPC and V2 flag)
-  --pool-size N     Number of pool accounts to initialize (default: 10)
-  --version         Show version
-  --help            Show this help
-
-Initialize pool accounts for Bulletin storage authorization.`);
+  --mnemonic "..."    Pool root mnemonic used to derive pool accounts
+                      (also readable from BULLETIN_POOL_MNEMONIC or MNEMONIC env var).
+                      Default: the well-known dev phrase (same key the deploy path uses).
+  --authorizer "..."  Seed/mnemonic of the key that holds authorization authority
+                      on this chain (e.g. "//Alice", a full mnemonic, or a hex seed).
+                      On testnets, defaults to //Alice if omitted.
+                      On non-testnets, required to grant — omit to get status only.
+  --rpc wss://...     Bulletin RPC endpoint (or set BULLETIN_RPC env var)
+  --env <id>          Load environment by id from environments.json
+  --pool-size N       Number of pool accounts to check/initialize (default: 10)
+  --version           Show version
+  --help              Show this help`);
   process.exit(0);
 }
 
@@ -52,6 +63,10 @@ const mnemonic = flags.mnemonic ?? process.env.BULLETIN_POOL_MNEMONIC ?? process
 
 const bootstrapOpts = {};
 
+if (flags.authorizer) {
+  bootstrapOpts.authorizerMnemonic = flags.authorizer;
+}
+
 if (flags.env) {
   const envJsonPath = fileURLToPath(new URL("../assets/environments.json", import.meta.url));
   let envDoc;

package/dist/auth/index.js

@@ -8,12 +8,13 @@ import {
   requestResourceAllocation,
   resolveSigner,
   summarizeOutcomes
-} from "../chunk-5OKB3TEB.js";
+} from "../chunk-5FLTDWWP.js";
 import {
   renderLoginStatus,
   renderLogoutStatus,
   renderQrCode
 } from "../chunk-RIRDBSBG.js";
+import "../chunk-TSPERKUS.js";
 import "../chunk-ZOC4GITL.js";
 export {
   BULLETIN_RESOURCE,

package/dist/auth/vendor/index.js

@@ -12,7 +12,8 @@ import {
   resolveSigner,
   sessionRootPublicKey,
   summarizeOutcomes
-} from "../../chunk-5OKB3TEB.js";
+} from "../../chunk-5FLTDWWP.js";
+import "../../chunk-TSPERKUS.js";
 import "../../chunk-ZOC4GITL.js";
 export {
   BULLETIN_RESOURCE,

package/dist/auth-config.js

@@ -9,9 +9,10 @@ import {
   getPeopleChainEndpoints,
   hasPersistedSession,
   resolveBulletinEndpoints
-} from "./chunk-7OOKA4BJ.js";
-import "./chunk-DFRIBV6O.js";
-import "./chunk-KY3CRS66.js";
+} from "./chunk-F2SDBU57.js";
+import "./chunk-TSPERKUS.js";
+import "./chunk-ORIB2S5P.js";
+import "./chunk-V4RTUMBT.js";
 import "./chunk-QRKI6MMK.js";
 import "./chunk-ZOC4GITL.js";
 export {

package/dist/bug-report.js

@@ -9,10 +9,10 @@ import {
   offerBugReport,
   scrubSecrets,
   setDeployContext
-} from "./chunk-D2WW2CIA.js";
-import "./chunk-ZG56UL3V.js";
-import "./chunk-DFRIBV6O.js";
-import "./chunk-KY3CRS66.js";
+} from "./chunk-OR7LUTET.js";
+import "./chunk-ZC43ORKF.js";
+import "./chunk-ORIB2S5P.js";
+import "./chunk-V4RTUMBT.js";
 export {
   buildCliFlagsSummary,
   buildLabels,

package/dist/{chunk-GKG2EQKM.js → chunk-32THWODT.js}

@@ -1,6 +1,6 @@
 import {
   preflightSssAllowance
-} from "./chunk-IF6BNIKT.js";
+} from "./chunk-SNDIOANW.js";
 import {
   statementSigningAccount
 } from "./chunk-GRPLHUYC.js";
@@ -34,16 +34,19 @@ import {
   STALE_SESSION_MESSAGE,
   getPeopleChainEndpoints,
   hasPersistedSession
-} from "./chunk-7OOKA4BJ.js";
+} from "./chunk-F2SDBU57.js";
 import {
   setDeployContext
-} from "./chunk-D2WW2CIA.js";
+} from "./chunk-OR7LUTET.js";
 import {
   probeChunks
-} from "./chunk-UBLIZRYW.js";
+} from "./chunk-7HQL3TPT.js";
 import {
   packSection
 } from "./chunk-C2TS5MER.js";
+import {
+  CLI_NAME
+} from "./chunk-TSPERKUS.js";
 import {
   DotNS,
   PUBLISHER_ABI,
@@ -53,7 +56,7 @@ import {
   parseDomainName,
   popStatusName,
   verifyNonceAdvanced
-} from "./chunk-FAB6BWDB.js";
+} from "./chunk-ARPBPQZQ.js";
 import {
   derivePoolAccounts,
   detectTestnet,
@@ -61,7 +64,7 @@ import {
   fetchPoolAuthorizations,
   isAuthorizationSufficient,
   selectAccount
-} from "./chunk-4PVJ2JBZ.js";
+} from "./chunk-4IUTMHVB.js";
 import {
   VERSION,
   captureWarning,
@@ -75,7 +78,7 @@ import {
   truncateAddress,
   withDeploySpan,
   withSpan
-} from "./chunk-DFRIBV6O.js";
+} from "./chunk-ORIB2S5P.js";
 import {
   DEFAULT_ENV_ID,
   getPopSelfServeConfig,
@@ -417,7 +420,9 @@ function isBenignTeardownError(error) {
   const s = error instanceof Error ? `${error.name ?? ""} ${error.message ?? ""}` : String(error);
   return /DestroyedError|Client destroyed/.test(s);
 }
-var CID_CONFIG = { version: 1, codec: 85, hashCode: 18, hashLength: 32 };
+var SHA256_MULTIHASH_CODE = 18;
+var BLAKE2B_256_MULTIHASH_CODE = 45600;
+var CID_CONFIG = { version: 1, codec: 85, hashCode: SHA256_MULTIHASH_CODE, hashLength: 32 };
 function deriveRootSigner(mnemonic, path3 = "") {
   const entropy = mnemonicToEntropy(mnemonic);
   const miniSecret = entropyToMiniSecret(entropy);
@@ -593,6 +598,9 @@ function chooseSignerInput(opts) {
 function isPhoneSignerActive(options) {
   return !!(options.signer && options.signerAddress && !options.transferTo);
 }
+function shouldHandoverName(opts) {
+  return !!opts.transferTo && opts.registeredFresh;
+}
 function formatStorageSignerLine(slotAddress, failReason) {
   if (slotAddress) return `   Storage signer: allowance slot ${slotAddress}`;
   return `   Storage signer: pool fallback (${failReason ?? "no session"})`;
@@ -616,7 +624,7 @@ function selectStorageReconnect(options) {
         console.warn(
           `\u26A0  Bulletin allowance slot not usable: ${reason}
    Falling back to the shared pool account for storage (fine on testnet).
-   To use your own allowance, run: bulletin-deploy logout && bulletin-deploy login`
+   To use your own allowance, run: ${CLI_NAME} logout && ${CLI_NAME} login`
         );
         return getProvider();
       }
@@ -690,9 +698,8 @@ function watchTransaction(tx, signer, txOpts, onSuccess, { label = "transaction"
   });
 }
 async function storeChunk(unsafeApi, signer, chunkBytes, nonce, ss58, opts = {}) {
-  const hashCode = 18;
-  const cid = createCID(chunkBytes, CID_CONFIG.codec, hashCode);
-  const tx = unsafeApi.tx.TransactionStorage.store_with_cid_config({ cid: { codec: BigInt(CID_CONFIG.codec), hashing: toHashingEnum(hashCode) }, data: chunkBytes });
+  const cid = createCID(chunkBytes, CID_CONFIG.codec, CID_CONFIG.hashCode);
+  const tx = unsafeApi.tx.TransactionStorage.store_with_cid_config({ cid: { codec: BigInt(CID_CONFIG.codec), hashing: toHashingEnum(CID_CONFIG.hashCode) }, data: chunkBytes });
   const txOpts = { mortality: { mortal: true, period: CHUNK_MORTALITY_PERIOD }, nonce };
   const { value, viaFallback, receipt } = await watchTransaction(tx, signer, txOpts, () => {
     console.log(`      CID: ${cid.toString()}`);
@@ -700,11 +707,15 @@ async function storeChunk(unsafeApi, signer, chunkBytes, nonce, ss58, opts = {})
   }, { label: `chunk(nonce:${nonce})`, rpc: BULLETIN_ENDPOINTS, senderSS58: ss58, expectedNonce: nonce, timeoutMs: CHUNK_TIMEOUT_MS, fetchNonce: opts.fetchNonce });
   return { ...value, viaFallback, receipt };
 }
-async function storeFile(contentBytes, { client: existingClient, unsafeApi: existingApi, signer: existingSigner } = {}) {
+async function storeFile(contentBytes, {
+  client: existingClient,
+  unsafeApi: existingApi,
+  signer: existingSigner,
+  hashCode = CID_CONFIG.hashCode
+} = {}) {
   console.log(`
    Size: ${(contentBytes.length / 1024).toFixed(2)} KB`);
   if (contentBytes.length > MAX_FILE_SIZE) throw new Error(`File exceeds 8MB limit. Use chunked deployment.`);
-  const hashCode = 18;
   const cid = createCID(contentBytes, CID_CONFIG.codec, hashCode);
   console.log(`   CID: ${cid.toString()}`);
   let client, unsafeApi, signer;
@@ -719,6 +730,13 @@ async function storeFile(contentBytes, { client: existingClient, unsafeApi: exis
     signer = provider.signer;
   }
   try {
+    const [probe] = await probeChunks([cid.toString()], { client });
+    if (probe.present === true) {
+      console.log(`   Already on chain (block ${probe.block}, index ${probe.index}) \u2014 skipping upload.
+`);
+      if (!existingClient) client.destroy();
+      return cid.toString();
+    }
     const tx = unsafeApi.tx.TransactionStorage.store_with_cid_config({ cid: { codec: BigInt(CID_CONFIG.codec), hashing: toHashingEnum(hashCode) }, data: contentBytes });
     const txOpts = { mortality: { mortal: true, period: 256 } };
     console.log(`   Submitting...`);
@@ -1996,7 +2014,7 @@ async function deploy(content, domainName = null, options = {}) {
       if (options.suri) throw e;
       if (e?.name === "SignerNotAvailableError") {
         if (hasSession) console.error(STALE_SESSION_MESSAGE);
-        else console.log("   Login session unavailable or expired \u2014 falling back to pool. Run `bulletin-deploy login` to use your identity.");
+        else console.log(`   Login session unavailable or expired \u2014 falling back to pool. Run \`${CLI_NAME} login\` to use your identity.`);
       } else {
         throw e;
       }
@@ -2012,7 +2030,7 @@ async function deploy(content, domainName = null, options = {}) {
       const allowed = await preflightSssAllowance(statementAccount, () => getPeopleChainEndpoints(envId));
       if (allowed === false) {
         throw new NonRetryableError(
-          "Session signing allowance has expired (~2-3 days after login). Run `bulletin-deploy logout`, then `bulletin-deploy login`, to renew (login alone won't refresh a stale session)."
+          `Session signing allowance has expired (~2-3 days after login). Run \`${CLI_NAME} logout\`, then \`${CLI_NAME} login\`, to renew (login alone won't refresh a stale session).`
         );
       }
     } catch (e) {
@@ -2394,6 +2412,7 @@ Have your phone ready \u2014 1 signature needed (link content)`);
             ...phoneSignerActive ? { onPhoneSigningRequired: (label) => console.log(`
    Check your phone \u2192 ${label}`) } : {}
           });
+          let registeredFresh = false;
           if (parsed?.isSubdomain) {
             const { owned, owner } = await dotns.checkSubdomainOwnership(parsed.sublabel, parsed.parentLabel);
             if (owned) {
@@ -2405,6 +2424,7 @@ Have your phone ready \u2014 1 signature needed (link content)`);
               if (!parentOwnership.owned) throw new Error(`You must own ${parsed.parentLabel}.dot to register subdomains under it`);
               console.log(`   Status: Registering subdomain...`);
               await dotns.registerSubdomain(parsed.sublabel, parsed.parentLabel);
+              registeredFresh = true;
             }
           } else {
             const { owned } = await dotns.checkOwnership(name);
@@ -2413,6 +2433,7 @@ Have your phone ready \u2014 1 signature needed (link content)`);
             } else {
               console.log(`   Status: Registering...`);
               await dotns.register(name);
+              registeredFresh = true;
             }
           }
           const contenthashHex = `0x${encodeContenthash(cid)}`;
@@ -2422,7 +2443,12 @@ Have your phone ready \u2014 1 signature needed (link content)`);
               await publish(dotns, parsed, options.failOnPublishError);
             }
           }
-          if (options.transferTo) {
+          if (options.transferTo && !registeredFresh) {
+            console.log(`   ${name}.dot already existed \u2014 updated content only; ownership unchanged (not transferred to ${options.transferTo}).`);
+            console.log(`   If you meant to claim it, run: ${CLI_NAME} transfer ${name} --env ${envId}${options.suri ? ` --mnemonic "<your worker key>"` : ""}`);
+            setDeployAttribute("deploy.transfer.status", "skipped-existing");
+          }
+          if (shouldHandoverName({ transferTo: options.transferTo, registeredFresh })) {
             const transferTo = options.transferTo;
             await withSpan("deploy.transfer", `3. transfer ${name}.dot`, { "deploy.transfer.to": transferTo }, async () => {
               setDeployAttribute("deploy.transfer.worker", truncateAddress(options.signerAddress ?? ""));
@@ -2434,7 +2460,7 @@ Have your phone ready \u2014 1 signature needed (link content)`);
                 console.log(`   Handed ${name}.dot to ${transferTo} (${transferRes.status}${transferRes.txHash ? `, tx ${transferRes.txHash}` : ""}).`);
               } catch (e) {
                 setDeployAttribute("deploy.transfer.status", "failed");
-                const recover = `bulletin-deploy transfer ${name} --env ${envId}` + (options.suri ? ` --mnemonic "<your worker key>"` : "");
+                const recover = `${CLI_NAME} transfer ${name} --env ${envId}` + (options.suri ? ` --mnemonic "<your worker key>"` : "");
                 try {
                   dotns.disconnect();
                 } catch {
@@ -2497,9 +2523,9 @@ Have your phone ready \u2014 1 signature needed (link content)`);
         console.log("\n" + "=".repeat(60));
         console.log("DEPLOYMENT COMPLETE!");
         console.log("=".repeat(60));
-        console.log("\nPolkadot Triangle");
-        console.log(`   - Polkadot Desktop: ${name}.dot`);
-        console.log(`   - Polkadot Browser: ${browserUrlFor(name, envId)}`);
+        console.log("\nCheck it out here:");
+        console.log(`   ${browserUrlFor(name, envId)}`);
+        console.log(`   ${name}.dot  (in a Polkadot-aware browser)`);
         console.log("\n" + "=".repeat(60) + "\n");
         return { domainName: name, fullDomain: `${name}.dot`, cid, ipfsCid };
       } finally {
@@ -2938,6 +2964,8 @@ export {
   retryBudgetExhausted,
   isConnectionError,
   isBenignTeardownError,
+  SHA256_MULTIHASH_CODE,
+  BLAKE2B_256_MULTIHASH_CODE,
   deriveRootSigner,
   createCID,
   encodeContenthash,
@@ -2951,6 +2979,7 @@ export {
   __selectStorageProviderModeForTest,
   chooseSignerInput,
   isPhoneSignerActive,
+  shouldHandoverName,
   formatStorageSignerLine,
   storeFile,
   __assignDenseNoncesForTest,