@arcadiasystems/morse-cli 0.6.1 → 0.7.0

package/CHANGELOG.md

@@ -4,6 +4,24 @@ All notable changes to `@arcadiasystems/morse-cli` are documented here. The
 format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and this
 project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.7.0] - 2026-09-09
+
+### Added
+
+- **`--upload-relay <url|auto>`** routes Walrus uploads through a relay instead of the direct fanout, with `MORSE_WALRUS_UPLOAD_RELAY` and a per-profile `uploadRelay` following the usual `flags > env > config > defaults` precedence. `auto` resolves to the canonical Mysten relay for the selected network, and is refused on localnet, which has none.
+
+  A direct upload pushes slivers to every storage node in the committee at once, 95 on mainnet. Networks that cannot sustain that burst fail with `NotEnoughBlobConfirmationsError` even when the nodes are healthy and far above write quorum, and until now the CLI had no way around it while the SDK did: `DefaultWalrusWriteAdapter.fromConfig` already accepted `uploadRelay`, the CLI just never offered a way to set it.
+
+  Opt-in rather than default: the direct path is free and trustless, the relay costs a tip and sees your bytes.
+- **`--max-tip <mist>`** and `MORSE_WALRUS_MAX_TIP` cap the relay's per-upload tip, defaulting to 10000000 MIST (0.01 SUI). Mainnet prices the tip linearly in encoded blob size, so an uncapped relay upload has no upper bound on what it charges; over the cap `@mysten/walrus` refuses before spending. A non-integer or negative cap is rejected outright rather than falling back to the default, so a typo cannot silently authorise an unbounded tip.
+- `config add` takes `--upload-relay` to persist the choice on a profile. The value is validated at add time the way `--network` already is, so `auto` on a network with no canonical relay is refused immediately rather than producing a profile that only fails the first time someone uploads. `config list` shows it in both the human and `--json` renderings.
+
+### Notes
+
+- The relay setting and its tip cap are carried raw through `resolveSettings` and only resolved on the Walrus write path. `resolveSettings` runs for every command, so parsing them eagerly would let a typo'd `MORSE_WALRUS_MAX_TIP` in a shell profile or CI environment break reads that never upload anything. A malformed cap fails the upload, not `publication get`.
+
+  Verified live: uploads through the relay succeed on both networks and round-trip byte for byte, a too-low `--max-tip` refuses before spending, and a malformed one is rejected at parse time.
+
 ## [0.6.1] - 2026-09-09
 
 Picks up `@arcadiasystems/morse-sdk@0.6.0` and fixes a download regression it exposed. Upgrade if you use mainnet at all.

package/README.md

@@ -6,7 +6,7 @@ content entries from your terminal, signing with a locally encrypted key.
 Content is stored on [Walrus](https://walrus.xyz); private entries are encrypted
 with [Seal](https://github.com/MystenLabs/seal).
 
-> Status: v0.6.1. Mainnet and testnet are both supported for public content;
+> Status: v0.7.0. Mainnet and testnet are both supported for public content;
 > the command surface is stable.
 >
 > **Encrypted commands are testnet-only.** `entry add-encrypted`, `entry
@@ -112,6 +112,8 @@ Environment variables (override the config file, overridden by flags):
 | --- | --- | --- |
 | `MORSE_PROFILE` | `--profile` | Profile to use. |
 | `MORSE_NETWORK` | `--network` | `mainnet`, `testnet`, or `localnet`. |
+| `MORSE_WALRUS_UPLOAD_RELAY` | `--upload-relay` | Upload through a Walrus relay instead of the direct fanout. `auto` picks the canonical relay for the network. |
+| `MORSE_WALRUS_MAX_TIP` | `--max-tip` | Cap the relay's per-upload tip, in MIST. Defaults to 10000000 (0.01 SUI). |
 | `MORSE_RPC_URL` | `--rpc` | Sui RPC URL override. |
 | `MORSE_ADDRESS` | (no flag) | Active account address, selecting which keystore to use. |
 | `MORSE_PUBLICATION` | `-P, --publication` | Active publication id. |
@@ -146,6 +148,8 @@ Global options apply to every command and must appear before the subcommand
 | `--network <mainnet\|testnet\|localnet>` | Network to target (default: testnet). `localnet` needs a custom deployment. |
 | `-p, --profile <name>` | Config profile to use. |
 | `--rpc <url>` | Override the Sui RPC URL. |
+| `--upload-relay <url\|auto>` | Upload Walrus blobs through a relay instead of the direct fanout. `auto` picks the canonical relay for the network. Costs a tip per upload. |
+| `--max-tip <mist>` | Cap the relay's per-upload tip, in MIST (default: 10000000). |
 | `--json` | Machine-readable JSON on stdout. |
 | `-q, --quiet` | Suppress progress and informational output. |
 | `-y, --yes` | Assume yes for confirmation prompts. |
@@ -168,7 +172,7 @@ and `-C, --collection <name>`, both defaulting to the active context.
 
 | Command | Purpose |
 | --- | --- |
-| `config add <name> --network <net> [--rpc <url>]` | Create or update a profile. |
+| `config add <name> --network <net> [--rpc <url>] [--upload-relay <url\|auto>]` | Create or update a profile. |
 | `config list` | List profiles; `*` marks the default. |
 | `config use <name>` | Set the default profile. |
 | `config remove <name>` | Delete a profile. |
@@ -348,6 +352,40 @@ to fetch the full record per file (one read each) when you need them.
   retired, so it needs `--indexer-url` pointing at a source that serves the same
   query. This affects testnet as well as mainnet.
 
+## When uploads fail: the upload relay
+
+A Walrus upload pushes slivers to every storage node in the committee at once,
+95 of them on mainnet. Networks that cannot sustain that burst fail with
+`NotEnoughBlobConfirmationsError` or "Unable to connect", **even when the nodes
+are healthy and far above write quorum**. If uploads fail while reads work, this
+is almost certainly why, and it is not a fault in your config.
+
+Route the upload through a relay and one connection replaces ~95:
+
+```sh
+morse --upload-relay auto file upload ./photo.jpg --public -n photo
+```
+
+`auto` resolves to Mysten's canonical relay for the selected network. Pass a URL
+instead to use a different operator, or persist it on a profile:
+
+```sh
+morse config add mainnet --network mainnet --upload-relay auto
+```
+
+Three things to know before reaching for it:
+
+- **It costs a tip per upload**, on top of WAL and gas. Mainnet prices it
+  linearly in encoded blob size; a small blob runs about 0.0026 SUI.
+- **The tip is capped** at `--max-tip` (default 10000000 MIST, 0.01 SUI). Over
+  the cap the upload is refused before anything is spent, rather than quietly
+  charging more than you expected.
+- **The relay sees your bytes.** Same trade as any hosted service; encrypt first
+  if that matters.
+
+It is opt-in on purpose. The direct path is free and trustless, and most
+networks handle it fine.
+
 ## Publishing
 
 Published to the public npm registry as the scoped package

package/dist/index.js

@@ -148,7 +148,7 @@ import { Command } from "commander";
 // package.json
 var package_default = {
   name: "@arcadiasystems/morse-cli",
-  version: "0.6.1",
+  version: "0.7.0",
   description: "Command-line interface for the Morse decentralized CMS on Sui.",
   license: "MIT",
   type: "module",
@@ -217,9 +217,10 @@ var package_default = {
 };
 
 // src/cli/program.ts
+var DEFAULT_MAX_TIP_MIST = 1e7;
 function buildProgram() {
   const program = new Command;
-  program.name("morse").description("Command-line interface for the Morse decentralized CMS on Sui.").version(package_default.version, "-V, --version", "Print the version and exit").option("--network <network>", "Sui network: mainnet, testnet, or localnet [env: MORSE_NETWORK]").option("-p, --profile <name>", "Config profile to use [env: MORSE_PROFILE]").option("--rpc <url>", "Override the Sui RPC URL [env: MORSE_RPC_URL]").option("--json", "Output machine-readable JSON on stdout").option("-q, --quiet", "Suppress progress and informational output").option("-y, --yes", "Assume yes for confirmation prompts").option("--debug", "Print stack traces on error").enablePositionalOptions().showHelpAfterError().exitOverride();
+  program.name("morse").description("Command-line interface for the Morse decentralized CMS on Sui.").version(package_default.version, "-V, --version", "Print the version and exit").option("--network <network>", "Sui network: mainnet, testnet, or localnet [env: MORSE_NETWORK]").option("-p, --profile <name>", "Config profile to use [env: MORSE_PROFILE]").option("--rpc <url>", "Override the Sui RPC URL [env: MORSE_RPC_URL]").option("--upload-relay <url|auto>", "Upload Walrus blobs through a relay instead of fanning out to every storage node; 'auto' picks the canonical relay for the network. Costs a tip per upload [env: MORSE_WALRUS_UPLOAD_RELAY]").option("--max-tip <mist>", `Cap the per-upload relay tip, in MIST (default: ${DEFAULT_MAX_TIP_MIST}) [env: MORSE_WALRUS_MAX_TIP]`).option("--json", "Output machine-readable JSON on stdout").option("-q, --quiet", "Suppress progress and informational output").option("-y, --yes", "Assume yes for confirmation prompts").option("--debug", "Print stack traces on error").enablePositionalOptions().showHelpAfterError().exitOverride();
   return program;
 }
 
@@ -462,6 +463,9 @@ function parseProfile(name, value, source) {
   if (typeof value.rpc === "string") {
     profile.rpc = value.rpc;
   }
+  if (typeof value.uploadRelay === "string") {
+    profile.uploadRelay = value.uploadRelay;
+  }
   if (typeof value.account === "string") {
     profile.account = value.account;
   }
@@ -564,6 +568,35 @@ async function updateActiveProfile(opts, patch, env = process.env) {
 }
 
 // src/config/profile.ts
+function canonicalUploadRelay(network) {
+  if (network === "mainnet" || network === "testnet") {
+    return `https://upload-relay.${network}.walrus.space`;
+  }
+  return;
+}
+function resolveUploadRelay(value, network) {
+  if (value === undefined || value === "") {
+    return;
+  }
+  if (value !== "auto") {
+    return value;
+  }
+  const canonical = canonicalUploadRelay(network);
+  if (canonical === undefined) {
+    throw new UsageError(`--upload-relay auto has no canonical relay for ${network}. Pass an explicit relay URL.`);
+  }
+  return canonical;
+}
+function parseMaxTip(value) {
+  if (value === undefined || value === "") {
+    return DEFAULT_MAX_TIP_MIST;
+  }
+  const parsed = /^\d+$/.test(value) ? Number(value) : Number.NaN;
+  if (!Number.isSafeInteger(parsed)) {
+    throw new UsageError(`--max-tip must be a non-negative integer in MIST; got "${value}".`);
+  }
+  return parsed;
+}
 function resolveSettings(opts, config, env = process.env) {
   const explicitProfile = opts.profile ?? env.MORSE_PROFILE;
   const profileName = explicitProfile ?? config.defaultProfile;
@@ -574,10 +607,21 @@ function resolveSettings(opts, config, env = process.env) {
   const networkValue = opts.network ?? env.MORSE_NETWORK ?? profile?.network ?? "testnet";
   const network = coerceNetwork(networkValue);
   const rpcUrl = opts.rpc ?? env.MORSE_RPC_URL ?? profile?.rpc;
+  const uploadRelay = opts.uploadRelay ?? env.MORSE_WALRUS_UPLOAD_RELAY ?? profile?.uploadRelay;
+  const maxTip = opts.maxTip ?? env.MORSE_WALRUS_MAX_TIP;
   const account = env.MORSE_ADDRESS ?? profile?.account;
   const publication = env.MORSE_PUBLICATION ?? profile?.publication;
   const collection = env.MORSE_COLLECTION ?? profile?.collection;
-  return { profileName, network, rpcUrl, account, publication, collection };
+  return {
+    profileName,
+    network,
+    rpcUrl,
+    uploadRelay,
+    maxTip,
+    account,
+    publication,
+    collection
+  };
 }
 
 // src/keystore/keystore.ts
@@ -991,7 +1035,7 @@ async function buildContentContext(command) {
     throw new CliError("Walrus content uploads are not available on localnet. Use testnet or mainnet.", ExitCode.Usage);
   }
   const adapter = new KeypairAdapter(keypair, base.client);
-  const walrus = DefaultWalrusWriteAdapter.fromConfig({ network, suiClient: base.client }, keypair);
+  const walrus = DefaultWalrusWriteAdapter.fromConfig(walrusWriteConfig(base, network), keypair);
   return {
     ...base,
     output: base.output.withNetwork(network),
@@ -1006,6 +1050,17 @@ function assertSealAvailable(config) {
   }
   throw new CliError(`Encrypted commands are not available on ${config.network}. Seal key servers there are operated commercially and the CLI cannot yet be pointed at one. Use --network testnet, or drive @arcadiasystems/morse-sdk directly with your own seal.serverConfigs.`, ExitCode.Usage);
 }
+function walrusWriteConfig(base, network) {
+  const host = resolveUploadRelay(base.settings.uploadRelay, network);
+  if (host === undefined) {
+    return { network, suiClient: base.client };
+  }
+  return {
+    network,
+    suiClient: base.client,
+    uploadRelay: { host, sendTip: { max: parseMaxTip(base.settings.maxTip) } }
+  };
+}
 async function buildEncryptContext(command) {
   const ctx = await buildContentContext(command);
   return { ...ctx, seal: lazySeal(ctx) };
@@ -1539,12 +1594,14 @@ async function runConfigList(output) {
 }
 async function runConfigAdd(output, name, options) {
   const network = coerceNetwork(options.network);
+  resolveUploadRelay(options.uploadRelay, network);
   const cfg = await loadConfig();
   const profiles = {
     ...cfg.profiles,
     [name]: {
       network,
-      ...options.rpc === undefined ? {} : { rpc: options.rpc }
+      ...options.rpc === undefined ? {} : { rpc: options.rpc },
+      ...options.uploadRelay === undefined ? {} : { uploadRelay: options.uploadRelay }
     }
   };
   const defaultProfile = Object.keys(cfg.profiles).length === 0 ? name : cfg.defaultProfile;
@@ -1553,6 +1610,7 @@ async function runConfigAdd(output, name, options) {
     profile: name,
     network,
     rpc: options.rpc,
+    uploadRelay: options.uploadRelay,
     default: defaultProfile === name
   });
 }
@@ -1582,7 +1640,7 @@ function registerConfigCommands(program) {
   config.command("list").description("List profiles and show the default").action(async (_options, command) => {
     await runConfigList(outputFor(command));
   });
-  config.command("add <name>").description("Create or update a profile").requiredOption("--network <network>", "Sui network: mainnet, testnet, or localnet").option("--rpc <url>", "RPC URL override for this profile").action(async (name, options, command) => {
+  config.command("add <name>").description("Create or update a profile").requiredOption("--network <network>", "Sui network: mainnet, testnet, or localnet").option("--rpc <url>", "RPC URL override for this profile").option("--upload-relay <url|auto>", "Walrus upload relay for this profile; 'auto' picks the canonical relay for the network").action(async (name, options, command) => {
     await runConfigAdd(outputFor(command), name, options);
   });
   config.command("use <name>").description("Set the default profile").action(async (name, _options, command) => {
@@ -1612,6 +1670,9 @@ function renderProfiles(config) {
     if (profile.rpc !== undefined) {
       parts.push(profile.rpc);
     }
+    if (profile.uploadRelay !== undefined) {
+      parts.push(`relay=${profile.uploadRelay}`);
+    }
     if (profile.account !== undefined) {
       parts.push(profile.account);
     }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@arcadiasystems/morse-cli",
-	"version": "0.6.1",
+	"version": "0.7.0",
 	"description": "Command-line interface for the Morse decentralized CMS on Sui.",
 	"license": "MIT",
 	"type": "module",