Mirror creates need an advertised URL this node can be fetched at

[MichaelTaylor3d]

Task

A mirror coin advertises where its store can be fetched from. dig_mirror_coin::create refuses
an advertisement with no URL — "a mirror must advertise at least one URL" — and a mirror coin is
the only thing that makes a held (store, root) discoverable. This node has no configured public
name, so NodeMirrorEffects::create refuses by name ahead of any chain read and
server::spawn_mirror_passes passes an empty URL set.

With dig-node#421 landed, this is the last thing between a funded operator wallet and a bond
actually being created.

Why it is not a one-liner

The URL is not a display string; it is published on chain in the coin's memos and is what a peer
uses to fetch. So the question is a real one and belongs to whoever answers it:

• What does this node advertise? Its dig.local name is useless to a stranger. rpc.dig.net is
  a shared gateway, not this node. A public DNS name or reachable address is operator knowledge, and
  config::is_self_upstream already documents that the node cannot decide it by resolver alone.
• Configured, or derived? An operator-set value is honest and needs a config surface. A derived
  one risks advertising an address nobody outside can reach — which stakes real $DIG on a claim the
  node cannot keep, and §25 penalises exactly that.
• More than one? MirrorAdvertisement.urls is a Vec, and IPv6-first (CLAUDE.md §5.2) suggests
  more than one entry is the normal case rather than the exception.
• Changing it later. A mirror coin's URLs are fixed at create. Moving a node means reclaiming and
  re-creating, which costs a round trip and a fee — worth knowing before the shape is locked.

Scope

A node that CAN advertise does; one that cannot says so and does not create. The refusal that exists
today is the correct default and must survive: publishing an unreachable URL is worse than not
publishing, because it locks collateral against a claim that will be penalised.

Context

• crates/dig-node-service/src/mirror/lifecycle.rs — NodeMirrorEffects::create, the named refusal.
• crates/dig-node-service/src/server.rs — spawn_mirror_passes, where the empty Vec is passed
  with the reason stated inline.
• crates/dig-node-service/src/config.rs — is_self_upstream, on why a public name is not derivable.
• SPEC.md §25.

Also still open on the same path (not this ticket): spawn_mirror_passes passes
broadcaster: None, and DIG_WALLET_ENABLE_LIVE_BROADCAST must be on for a signer to exist.

Parent

#412 ·
#377 ·
epic https://github.com/DIG-Network/dig_ecosystem/issues/3166

Sibling

#421 — the operator-scoped selector, which this
unblocks the other half of.

[MichaelTaylor3d]

Shape decision — advertised URLs are OPERATOR-CONFIGURED, never derived

Lane: loop/426-advertised-url · draft PR #430 · base 5df3e34.

Recorded before any behaviour lands, per CLAUDE.md §1.10. No loop-decider subagent tool is
reachable from this lane, so the decision was settled here at high rigor and is written down in
full so it can be refuted cheaply.

What the established contract already says (§2.0 already-shipped check, on the CONTRACT)

Read dig-mirror-coin 0.7.0 rather than assumed:

• MirrorAdvertisement.urls: Vec<String> — "Where the store can be fetched from. MUST be
  non-empty." (create.rs:38). Non-empty is the ONLY constraint the crate imposes.
• The memo layout is [hint(32), store(32), root(32), epoch, url, url, …] (crate SPEC §5) — every
  trailing entry is a URL, so many URLs is the designed case, not an exception.
• On READ the crate is deliberately tolerant: a non-UTF-8 memo entry is dropped because
  "URLs are advisory either way" (coin.rs:492). There is no scheme, host or format rule
  anywhere in the crate — none to contradict and none to inherit.
• dig-node's own SPEC §25 says nothing about URLs. Grepped: zero occurrences in the whole
  section. So this is genuinely unspecified on the node side, not a re-derivation of a shipped rule.

Reader-side tolerance and writer-side conservatism are not in conflict: the crate reads anybody's
coin and must not be brittle; this node writes a claim about itself and stakes $DIG on it.

The decision

1. Configured. Never derived. A new operator-set list; unset means this node advertises nothing.
   The one derivable candidate on the machine is the STUN reflexive address that
   seams/dig_peer/net.rs:469 already discovers, and it is exactly the wrong thing to publish: it is
   frequently unreachable from outside (symmetric NAT, no forward), and a mirror coin's URLs are
   fixed at create for the epoch, so a reflexive address that changes leaves collateral staked on
   a claim that is already false and §25 penalises. config::is_self_upstream documents the same
   limit for the upstream slot — a node cannot decide its own public name by resolver alone.
2. A list, order preserved. Vec<String>, matching the memo layout. IPv6-first (§5.2) is
   documented as the recommendation; the node does not reorder the operator's list, because these
   are advisory hints and silently reordering them misstates the operator's own preference.
3. The refusal survives, and is what an empty list produces. No configured URL → no advertisement
   → create refuses by name and no spend is attempted. Publishing an unreachable URL is worse than
   not publishing: it locks collateral against a claim that will be penalised.
4. Validation is narrow and fails in the survivable direction. An entry must parse as an absolute
   URL with a scheme and a non-empty host. Any scheme is accepted — refusing non-http(s) would
   be a stricter rule than anything shipped and would pre-emptively break a future dig:// form.
   Rejected outright are only the self-evidently this-machine-only hosts — loopback, unspecified,
   link-local, localhost, dig.local — which is precisely the mistake the ticket warns about
   (copying the node's own local address in). A private/LAN range is warned about and accepted:
   an operator running a LAN-only deployment has made an explicit choice, and rejecting it would stop
   a legitimate operator bonding forever, whereas accepting it costs only that operator's own stake.
   An entry that fails is dropped with a warning; if nothing survives, the node advertises nothing
   and falls back to (3).

Which direction a wrong version fails in

• Wrong toward refusal: the node does not bond. Recoverable by setting one config value.
• Wrong toward publication: real $DIG is locked against a URL nobody can reach, and §25 penalises it.
  Unrecoverable within the epoch.

Every fork above is resolved toward the first.

Changing the value later — worth knowing before it is locked

A mirror coin's URLs are fixed at create. Moving a node, or correcting a typo in this list, means
reclaiming every affected coin and re-creating it — a round trip and a fee. The node therefore
does not auto-reclaim when this config changes; that would spend money on a config edit. The
change takes effect for coins created after it, and the cost is documented at the config surface.

Not in this lane

broadcaster: None (#424) and the operator CAT selector (#421 / PR #423). This lane does not touch
mirror/lifecycle.rs or src/server.rs until #423 has merged.

[MichaelTaylor3d]

Progress — shape decided, config surface landed on the branch, wiring BLOCKED on #423

Branch loop/426-advertised-url · HEAD f6fca07 · draft PR #430.

DONE

• Shape decided and recorded above (operator-configured, never derived; list; narrow validation;
  the existing refusal survives as the unset case).
• crates/dig-node-service/src/mirror/advertise.rs — ADVERTISE_URLS_ENV,
  parse_advertised_urls, advertised_urls_from_env, Advertised { accepted, rejected },
  Rejection { NotAbsolute, ThisMachineOnly }. Pure; no I/O beyond one env read.
• url = "2" declared directly on dig-node-service (already resolved transitively at 2.5.8, so no
  new line enters the tree).
• SPEC.md §25.10 written, with the same PARTIALLY-SATISFIED marker style §25 already uses: the
  surface exists, nothing reads it, no coin is created. It does not claim the wiring.
• 7 unit tests green (cargo test -p dig-node-service --lib mirror::advertise).
• Both guards proven load-bearing by mutation, on the committed tree — disabling the
  this-machine rejection failed exactly
  a_this_machine_host_is_dropped_and_its_public_sibling_survives and nothing else; sorting the
  accepted list failed exactly the_operators_order_is_preserved_in_both_directions and nothing
  else.

NOT DONE, and deliberately so

The wiring lives in mirror/lifecycle.rs (NodeMirrorEffects::create) and src/server.rs
(spawn_mirror_passes), which PR #423 (#421, the operator CAT selector) is rewriting right now.
Editing them from this lane would be two writers on one region. This lane has touched neither file.

NEXT ACTION when #423 merges

1. git fetch origin and rebase with git rebase --onto origin/main f6fca07~3 — not a plain
   git rebase origin/main; dig-node squash-merges, so a plain rebase replays these commits against
   their own squashed form.
2. Read the advertisement at pass construction in spawn_mirror_passes, pass it into
   NodeMirrorEffects, and have create refuse by name when it is empty — the same shape as the
   existing named refusals, so a node that cannot advertise says so and attempts no spend.
3. Log the accepted count and each rejected entry with its reason once at bring-up.
4. Update the §25 status block's CREATES bullet to match what then runs.
5. Version bump last, Cargo.toml + Cargo.lock together (CI runs --locked), 0.173.0 → 0.174.0.

Found and left (§2.6, not chased): dig_mirror_coin's reader drops a non-UTF-8 memo entry as
advisory, so a coin can decode with fewer URLs than were published. It affects readers, not this
node's writing, and is the crate's stated behaviour rather than a defect here.