Mirror-coin lifecycle: presence tracks the .dig file on disk, created/reclaimed automatically per epoch

[MichaelTaylor3d]

Task

Implement the mirror-coin lifecycle in dig-node: create one per (store, root) it serves per epoch,
reclaim the previous epoch's, and reclaim when it stops serving — signing automatically, under a
scoped key.

Per (store, root), not per store. The legacy had one coin per store; roots are now broadcast
individually, so a publisher can fund the latest root and not the legacy one if they choose.

The naming chain, so the legacy source is readable

server coin (legacy code) → collateral coin (interim) → mirror coin (canonical). grep -rniE "mirror" across all three legacy src/ trees returns zero hits — the type is ServerCoin; "mirror" is the puzzle name one layer down in DataLayer-Driver.

§908 carve-out — the node signs this automatically

User directive: "the node MUST sign this on the users behalf, managing these mirror coins behind the scenes, and creating the spends automatically is a hard requirement. Its impossible for the user to approve all the transactions."

Scoped to mirror coins. §908 stands for everything else. The shape to lock first (§1.10): which key signs (a dedicated, separately-derived key with a bounded working balance — not the master seed, or the carve-out is total), what bounds the authority (per-epoch cap, the epoch's required amount per (store, root), destination restricted to the mirror puzzle), what the user accepts and when, and how revocation reclaims what is locked.

The legacy state machine, measured — replicate the shape, not the bugs

ensureServerCoinExists (dig-chia-sdk/src/blockchain/ServerCoin.ts:285-363), driven by a 60-second job (sync_stores.ts:326-333), not a weekly timer — the weekly cadence is emergent from comparing the computed epoch to the cached one:

• coin exists, synced, root matches → no-op (:306)
• coin exists, synced, root moved → update the local record only, no chain write (:311)
• coin exists, not synced → melt it (:323), stated reason: "helps prevent penalties for not having a valid peer registered"
• no coin, synced → create (:334)
• not synced → return without creating (:327) — never advertise a store you cannot serve

It is a re-create per epoch, not a renew. Nothing tops up or extends.

The epoch clock

calculateEpochAndRound (ServerCoin.ts:500-529): 7-day wall-clock windows, hard-coded 7*24*60*60*1000, 1-based, genesis 2024-09-03T00:00Z. Rounds are 10 minutes, 1008 per epoch. No chain input.

dig-epoch is NOT this. It is L2 epoch geometry anchored to L1 block heights with BlockProduction/Checkpoint/Finalization phases — a different notion. Using it here would silently change the cadence. If it is adopted anyway, it leaves the parked L2 island and needs the same release-first treatment as dig-mirror-coin.

Bugs NOT to inherit — this is the highest-value part of the brief

1. meltOutdatedEpochs had no in-repo callers, but it WORKED — it was an operational step.
   Corrected by the user directly: "no meltOutdatedEpochs worked when that legacy ran. We just had to
   locate the old coins and spend them in that version." An earlier version of this ticket called it
   dead code; that was wrong, and the error is worth keeping visible — "no callers" was turned into
   "never happened" without asking what ran outside the repo.

   The requirement survives, and it binds harder here than it did there: dig-node has no operator.
   Nobody will locate and spend the old coins by hand. So reclaiming epoch n-1 when creating epoch
   n is an acceptance criterion, not an optimisation — stranded collateral is real user money that
   never comes back.

2. Unbounded retry under the sync mutex (:71-78 + sync_stores.ts:253) — recursion on a substring match, no cap, no backoff. One underfunded store stalls synchronisation of every other store, forever.

3. IP-keyed records (:116) with a 7-day IP refresh (ip_refresh.ts:41-48) — a dynamic IP strands collateral at every address ever held. Key on launcher id + owner puzzle hash.

4. The local .json was authoritative and unrecoverable if lost. Use query::list (keyed on owner puzzle hash, ownership from the lineage proof) as the source of truth.

5. waitForConfirmation waited on the wrong coin (:347) — it waits for the funding coin to be spent, which a competing spend satisfies identically. It never confirmed the mirror coin was created.

6. Reclaim requires XCH for its own fee (:136), and meltUntrackedStoreCoins (:424-438) has no per-coin try/catch — the first failure aborts the whole sweep. A wallet at zero can be unable to advertise and unable to recover what it already locked.

7. Melt/create churn on sync flap (:321-323) — two fees and two confirmation waits per round trip.

Amount

The amount is derived per epoch, not fixed. equilibrium x multiplier - handicap, computed from
chain data and independently reproducible by every node — specified in
https://github.com/DIG-Network/dig_ecosystem/issues/3173 and implemented in dig-mirror-collateral.
Call that crate; never re-derive the formula — its clamps are structural in the code and absent from
the formula as written, so re-deriving reintroduces holes.

$DIG has 3 decimals, so whole $DIG x 1,000 = CAT mojos. At genesis the schedule starts at 1.000 $DIG
per (store, root) and rises toward 5.000 as the handicap decays. Legacy locked 0.0003 XCH — a
different asset entirely; do not let it drift back.

Hard constraints

• Never hand-roll a spend bundle (§4.1) — dig-mirror-coin builds them.
• Every automated spend writes to the audit record (dig-node#376). A spend reaching chain with no entry is invisible money movement.
• BLOCKED on dig-mirror-coin reaching the ceiling and publishing (dig-mirror-coin#3). Adopting it at chia 0.26/0.30 would re-split dig-node, which just reached 0.36.1.

Evidence (§2.6)

A person watching a (store, root) get collateralised on a real machine: the epoch's required amount
locked, the coin resolvable on chain, and the previous epoch's coin reclaimed at rollover. Not a green
suite.

Parent

https://github.com/DIG-Network/dig_ecosystem/issues/3166

[MichaelTaylor3d]

The process STOPS on insufficient funds — it does not retry (user directive, 2026-08-27)

"when we are out of DIG or XCH to run this collateral coin process, the dig-app must display a modal to the user to add more funds. Or else the process will stop."

This is a deliberate departure from the legacy behaviour, and the legacy behaviour is why: ServerCoin.ts:71-78 recursed on a substring match with no cap and no backoff, while holding the sync mutex (sync_stores.ts:253) — so one underfunded store stalled synchronisation of every other store, indefinitely.

Requirements for this lane:

• Stop cleanly: no partial spend, no half-written audit entry, resumable state so adding funds picks up rather than restarting the epoch's work.
• Both assets matter. $DIG is the collateral; XCH pays the fees. melt needs XCH for its own fee (ServerCoin.ts:136), so a zero-XCH wallet is unable to advertise and unable to reclaim what is already locked. Detect and report them separately — the consequences differ.
• Do not block other work. An underfunded store must not stall the maintenance pass for every other store. That is the specific legacy bug this replaces.
• Emit an audit entry for the stop (dig-node#376). A spend that did not happen because funds were short is a first-class record, not an omission — it is the same state the app's modal reports, and the CLI must show it too.

[MichaelTaylor3d]

CORRECTION: meltOutdatedEpochs was not a bug — it was operated manually

User, 2026-08-27:

"no meltOutdatedEpochs worked when that legacy ran. We just had to locate the old coins and spend them in that version"

The research finding was factually right and my reading of it was wrong. meltOutdatedEpochs (ServerCoin.ts:366-394) genuinely has zero callers in the source — that part holds. What I inferred from it does not: I wrote that prior-epoch collateral was "stranded forever" and called it "the single most important thing not to replicate".

It was not stranded. Reclaiming old epochs was an OPERATIONAL step, not an automatic one — the coins were located and spent deliberately, using that function, by whoever ran the servers. The code was correct and it was used; it simply was not on the 60-second automatic path.

That is a different thing from a bug, and the distinction changes the requirement rather than removing it.

What this does and does not change for us

Still required, and now for the right reason: the new implementation must reclaim epoch n-1 automatically. Not because the legacy leaked funds, but because the legacy had an operator and dig-node does not. A node running on an end user's machine has nobody to locate old coins and spend them, and at 20 DIG per store per epoch the accumulation is not something a user should be expected to notice, let alone clean up by hand.

So the acceptance criterion stands — automatic reclaim of the prior epoch — but the justification is "there is no operator here", not "the legacy was broken".

Worth carrying: that the legacy could locate and spend those coins at all is evidence the capability was sound. Our reclaim plus query::list (chain-side, keyed on owner puzzle hash) is a strictly better version of the same operation — it does not depend on a local .json surviving, which is what would actually have stranded funds.

On my error specifically

I turned "no callers" into "never happened" without asking what ran outside the repo. A function with no in-repo callers can still be the thing an operator invokes, and a legacy system's behaviour is not fully described by its automatic paths. Recorded because the same inference is available on every dead-looking function in these two repos, and the next reader should not repeat it.

[MichaelTaylor3d]

SETTLED: the epoch is the 7-day wall clock. Do NOT use dig-epoch.

User, 2026-08-27:

"yes the epoch is the 7 day wall clock, that detail is correct"

This closes the design fork flagged earlier (§1.10 — lock the shape before building). The authority is the legacy function the user pointed at, calculateEpochAndRound (dig-chia-sdk/src/blockchain/ServerCoin.ts:500-529):

const firstEpochStart      = new Date(Date.UTC(2024, 8, 3, 0, 0)); // 2024-09-03T00:00Z
const millisecondsInEpoch  = 7 * 24 * 60 * 60 * 1000;              // 7 days, hard-coded
const epochNumber          = Math.floor(differenceMillis / millisecondsInEpoch) + 1;  // 1-BASED
const millisecondsInRound  = 10 * 60 * 1000;                       // 1008 rounds/epoch

Properties that matter and must be preserved exactly, because the epoch is an input to coin identity — get it wrong and every mirror coin lands under a hint nobody looks up:

• 7 days, wall-clock UTC, hard-coded — not derived from block interval or height
• Genesis 2024-09-03T00:00Z
• 1-based (note the + 1) — an off-by-one here silently orphans a whole epoch's coins
• No chain input. The epoch is computable offline, by the node, the CLI and the app independently — which is what lets all three agree without coordination.

dig-epoch is explicitly NOT this

dig-epoch defines L2 epoch geometry anchored to L1 block heights, with BlockProduction / Checkpoint / Finalization phases. A genuinely different notion that happens to share the word. Adopting it here would silently change the cadence and the boundaries.

Consequence: no second crate leaves the parked L2 island. dig-epoch stays parked with dig-block, dig-slashing and the rest. Only dig-mirror-coin is being brought to the ceiling.

Where the epoch definition lives

Canonical, in dig-constants — alongside the 20 DIG amount (DIG-Network/dig-constants#17). Three independent consumers must compute the same epoch number: the node (to morph the hint), the CLI (to audit by epoch), and the app (to display "collateralised for epoch N"). Three copies of a genesis timestamp and a window length is exactly how they drift, and a drifted epoch is not a display bug — it is coins created under the wrong hint.

dig-mirror-coin deliberately takes epoch as a caller-supplied BigInt and defines no clock, so the clock is ours to own and to place correctly.

[MichaelTaylor3d]

BINDING CONSTRAINT: replicate the original EXACTLY, except the asset (user directive, 2026-08-27)

Verbatim:

"i think the main thing when you ask 'if i know something i dont' is to be extra careful you know the ins and outs of the the original implementation because this needs to work exactly the same way with the exception we are locking DIG instead of XCH"

This raises the bar on every lane in this epic. The default is now match the legacy behaviour, and any departure must be a decision the user has actually made — not an improvement a lane thought was obviously right.

The line between what must match and what the user has already changed

Must match — the on-chain and lifecycle behaviour:

• the epoch cycle and its arithmetic (7-day wall clock, genesis 2024-09-03T00:00Z, 1-based)
• the create / reclaim / re-create-per-epoch semantics
• the advertisement's on-chain shape and what a reader can learn from it
• the sync gating: never advertise a store you cannot serve; retract when you fall out of sync
• discovery semantics — what counts as a peer for a store in an epoch

Already changed by explicit directive, and those stand:

• $DIG instead of XCH, 20 DIG instead of 0.0003 XCH
• the node signs automatically (§908 carve-out)
• the process STOPS when out of funds rather than retrying forever
• an hourly OS notification, which legacy had no equivalent of at all
• an Activity tab and dign CLI audit, likewise new
• automatic reclaim of the prior epoch — because dig-node has no operator, where the legacy had one

Everything else defaults to replicate.

The concrete thing this changes RIGHT NOW: the memo layout

Research found a divergence that is exactly the "ins and outs" the user is warning about, and it is not a detail:

Legacy memos (ServerCoin.ts:52-59) are [hint, peerIp, publicSyntheticKey_hex] — slot 1 is a public key, not a URL. The legacy reader knows it (:223-226):

const peerUrl = serverCoin.memoUrls[0];
// The second memo URL is the public key
// We will utilize this for future features
const publicKey = serverCoin.memoUrls[1];

dig-mirror-coin has no counterpart for that slot. create.rs:86-88 treats every entry after the hint as a URL, and parse_memos (coin.rs:305-309) keeps any UTF-8 entry as a URL. So a legacy-shaped advertisement surfaces the pubkey hex as a bogus second URL, and a coin we create carries no pubkey at all.

That is a structural difference in what the coin says, not a cosmetic one. Under "work exactly the same way" it needs a deliberate answer:

1. Carry the pubkey, matching legacy — which means dig-mirror-coin needs a memo slot it does not currently model, and that is a crate change.
2. Do not carry it, accepting that our advertisement says less than the legacy one did — defensible only if nothing reads it, and the legacy comment says "we will utilize this for future features", i.e. it was reserved rather than used.

This is a question for the user, because it is about what the coin means, not about how to build it. Flagged rather than decided.

And the standing instruction for every lane

When the legacy did something that looks wrong, say so and ask — do not silently fix it. Several legacy behaviours were flagged in the research as defects. At least one of those calls has already been wrong: meltOutdatedEpochs looked like dead code stranding funds, and was in fact an operational step the user ran deliberately. A lane that "fixes" a behaviour the user relies on has broken the requirement while passing its own tests.

[MichaelTaylor3d]

REQUIREMENT: the $DIG must be PROVABLY locked (user directive, 2026-08-27)

"make sure you are provably locking the DIG CAT token"

This is a real requirement and not a given, because the legacy system did not meet it.

The legacy collateral was not provably bonded

Discovery filtered on amount alone (ServerCoin.ts:214-216):

const filteredCoinStates = hintedCoinStates.filter(
  (coinState) => coinState.coin.amount >= serverCoinCollateral
);

fetch_server_coin then ran the parent's puzzle to extract memos, but never asserted the coin sits at MirrorArgs::curry_tree_hash(). So any coin of sufficient amount, hinted to the morph value, with two memos, was accepted as a peer — including an ordinary coin the announcer still fully controlled and could spend the next block.

From a reader's point of view the legacy "collateral" was a claim, not a bond. Under "replicate exactly", this is the one place the answer must be no — the user has now asked explicitly for the opposite.

What "provably locked" has to mean here

1. The coin is at the mirror puzzle, verified — not inferred from a hint or an amount. dig-mirror-coin already does this: list/discover authenticate against mirror_coin_puzzle_hash() and return NotDigCollateral otherwise (coin.rs:167-171). Do not bypass it.
2. It is genuinely a $DIG CAT, with the asset id re-derived from the creating spend, not taken from the coin's own claim about itself. Canonical DIG_ASSET_ID is a406d3a9de984d03c9591c10d917593b434d5263cabe2b42f6b367df16832f81.
3. The amount is the full 20 DIG (20,000 CAT mojos), and the fee is paid from separate XCH coins so it can never shave the collateral. reclaim already has this property; the create path must too.
4. A reader other than the creator can verify all of the above from chain data alone. That is what makes it a bond rather than an assertion — and it is what the legacy lacked.

Evidence this ticket owes

A test that a coin which is not at the mirror puzzle, or not the $DIG asset, or short of the full amount, is rejected — and it must go RED if the check is removed. The legacy failure mode is precisely a test that only ever supplies well-formed coins and therefore proves nothing about what a hostile one does.

Also worth pinning: the hint alone must not be trusted. The morph is launcher_id + epoch under a namespace hash, and adjacent stores at adjacent epochs collide by construction — the crate documents this deliberately (namespace.rs:83-93) and defends by recomputing the morph from a candidate store id (coin.rs:85-87, used at query.rs:325). The legacy did not, and could not, because its hint was a bare number. Keep that defence.

[MichaelTaylor3d]

THE TRIGGER: mirror-coin presence tracks the .dig FILE on disk (user directive, 2026-08-27)

Verbatim:

"the idea between the mirror coins, if the dig-node is making available a .dig file to the network, a mirror coin with collateral needs to be created. If we stop hosting the .dig file to the network, the mirror coin needs to be spent and we need to retreive back the collateral. So this needs to watch the .dig files in the directory and add/remove collateral needs to follow whether the .dig file for that store and root exists or not. We want to avoid having a mirror coin live on chain for the current epoch without the .dig file because that gets penalized at a later date"

This is the requirement the rest of the lifecycle hangs off, and it is sharper than "one coin per subscribed store".

The invariant

A live mirror coin for the current epoch ⟺ the .dig file for that store AND root is on disk and being served.

Both directions matter, and the second is the one with teeth:

• .dig present → coin must exist. Otherwise the node is serving content it earns nothing for and is undiscoverable.
• .dig gone → coin must be spent and the collateral retrieved. Leaving it live is not merely wasteful — it gets penalised later. The coin is an advertisement that this node serves that content; if the content is not there, the advertisement is false, and the network is entitled to treat it as such.

The trigger is the FILESYSTEM, not a subscription list

Watch the .dig directory. The authority on "are we serving this" is whether the file is on disk, not whether a store id appears in a config. Those two can disagree — a store can be subscribed with the file missing, or the file can be removed out from under a running node — and the on-chain claim must follow the file, because the file is what a peer will actually be asked for.

This is the legacy behaviour restated in the terms that actually matter. Legacy gated on sync state and melted the coin the moment a store fell out of sync, with the reason stated in its own source (ServerCoin.ts:321-322): "If not synced, melt the coin, a new one will be created when synced up / this helps prevent penalties for not having a valid peer registered." Same invariant, expressed against a different signal.

Keyed on store AND root — and this needs a decision

The user says presence follows "the .dig file for that store and root". The legacy did NOT do this, and the divergence is worth settling deliberately rather than inheriting:

Legacy, on a root change while still synced (ServerCoin.ts:311-318), updated its local record's rootHash and made no chain write. So the coin kept advertising the OLD root while the node served the new one — the recorded root and the advertised root diverged silently, invisibly to every other node.

Under the invariant above that is wrong: the coin advertises a root whose .dig may no longer be on disk. The question for the user:

1. Root change ⇒ replace the coin (spend the old, create one advertising the new root). Correct by the invariant, costs a spend and a fee per root change.
2. Root change ⇒ leave the coin, matching legacy exactly, accepting that the advertisement goes stale between epochs.

Option 1 is what the directive implies and option 2 is what "replicate exactly" implies. They conflict, so it is a decision rather than a detail. Flagged, not decided.

Consequences for this lane

• Removal must be as reliable as creation. A missed create costs discoverability; a missed removal incurs a penalty. The failure directions are not symmetric, so the reconciliation must be able to find and spend a coin whose local record is missing — which is exactly what dig-mirror-coin's query::list (chain-side, keyed on owner puzzle hash) provides, and what the legacy .json could not.
• Deletion is not always an event you receive. A file can vanish while the process is down, on a volume that was unmounted, or via a path the watcher does not cover. The watcher is an optimisation; the periodic reconciliation between on-disk .dig files and on-chain coins is the correctness mechanism. Do not build only the watcher.
• Churn control. A file that disappears and returns — a re-download, a volume remount, an atomic replace during an update — must not produce a spend per flap. Each round trip costs two fees. Legacy hit this on sync flap (:321-323); a debounce or a confirm-before-acting delay is needed, and its length is a real parameter, not a magic number.
• An atomic replace looks like a delete. Writing store.dig.tmp then renaming over store.dig presents as a removal followed by a creation to most watchers. Reclaiming and re-collateralising on every content update would be expensive and wrong.

[MichaelTaylor3d]

THE BIGGEST DIVERGENCE FROM LEGACY: one coin per (store, ROOT, epoch) (user directive, 2026-08-27)

Verbatim:

"the biggest difference between the new implementation and the legacy implementation is that the legacy had a collateral coin for each store, now, we need a collateral coin for each store + root. We are broadcasting we are serving roots individually. This allows publishers to fund the latest root but not the legacy if they choose."

Legacy: one coin per (store, epoch). New: one coin per (store, root, epoch).

The reason is economic, not cosmetic: a publisher must be able to fund the latest root and decline to fund older ones. That is only expressible if the advertisement names a root, and only enforceable if a reader can tell which root a given coin is bonding.

dig-mirror-coin CANNOT express this today — measured

pub struct MirrorAdvertisement {
    pub store_launcher_id: Bytes32,
    pub epoch: BigInt,
    pub urls: Vec<String>,
    pub collateral: u64,
}                                   // <- no root

pub fn morph_store_launcher_id(store_launcher_id: Bytes32, epoch: &BigInt) -> Bytes32 {
    let launcher_id_int = BigInt::from_signed_bytes_be(store_launcher_id.as_ref());
    let offset_launcher_id = launcher_id_int + epoch;
    (offset_launcher_id, MIRROR_NAMESPACE).tree_hash().into()
}                                   // <- store + epoch only

Neither the advertisement nor the hint carries a root. This is a crate change, and it is a larger one than the ceiling move — it touches coin identity.

The shape question that must be locked BEFORE it is built (§1.10)

Does the root go in the HINT, or in the MEMOS? They are not equivalent, and the choice is wire-permanent:

	root in the hint	root in the memos
"who serves store X at root Y?"	one direct lookup	fetch every coin for store X, then filter
"which roots does anyone serve for store X?"	not enumerable — you must already know Y	one lookup, read them off
cost to a publisher funding one root	targeted	must scan
collision surface	a third input to the morph	unchanged

"We are broadcasting we are serving roots individually" leans toward the hint — a per-root broadcast that cannot be looked up per root is not really individual. But enumerating the roots served for a store is the query the app and the CLI will want, and the hint form makes that impossible without an external index.

A third option exists and should be considered rather than assumed away: root in the hint AND in the memos, paying one extra memo slot to keep both queries cheap.

This is a user/architecture decision, not a lane's. It determines what every mirror coin looks like on chain, permanently — namespace.rs:17-18 already records that changing the namespace "moves every mirror coin to a different hint and orphans every coin already on chain", and a new input to the morph has the same property.

Consequences to weigh

• Coin count scales with roots, not stores. A store with 5 historical roots the node still serves is 5 coins × 20 DIG = 100 DIG locked for one store. The economics of "20 per store" and "20 per store-root" are materially different, and the user's own trigger requirement — the coin exists iff the .dig for that store and root is on disk — means a node holding old roots pays for each.
• This makes the .dig-file trigger exact rather than approximate. Earlier I flagged a conflict between "presence follows store+root" and legacy's behaviour of updating the recorded root locally with no chain write. This directive resolves it: a root change is not a metadata update to an existing coin, it is a different coin. Old root's .dig removed → spend that root's coin. New root's .dig present → create a coin for it.
• The legacy memo layout question resurfaces. Legacy memos were [hint, peerIp, publicSyntheticKey]. If the root goes in the memos, the layout is being extended anyway and the pubkey slot should be settled in the same change rather than twice.

Sequencing — does this block the current publish?

No, and it should not. PR#4 is the ceiling move, needed regardless and orthogonal to this. Publish it as 0.4.0, then add root support as the next crate change.

But it does become the new blocker for the lifecycle lane (#377), which cannot be built against a crate that has no root in the advertisement. That lane was already blocked on the ceiling; it is now blocked on root support too, and root support needs the shape decision above first.

[MichaelTaylor3d]

HINT SHAPE: the morph takes the root (user directive, 2026-08-27)

Verbatim:

"the root should be a morphed version of the hint is its morph(store + root)"

Settled: the root goes in the HINT, not the memos. So "who serves store X at root Y?" is one direct lookup, which is what makes per-root broadcasting real rather than nominal.

The one thing that must be confirmed before this is built

Where does EPOCH go? The directive names morph(store + root) and does not mention it. Taken literally that would replace epoch with root — but the epoch cannot simply drop out, because the weekly cycle depends on it: coins are re-created each epoch ("it maintains these weekly because of epics"), and a hint with no epoch term yields one permanent hint per (store, root) with nothing distinguishing this week's coin from last week's.

Two readings, both consistent with what has been said:

(A) Flat, three-term — morph(store + root + epoch)

tree_hash((store_int + root_int + epoch, MIRROR_NAMESPACE))

Closest to the legacy shape (store + epoch), one term added.

(B) Nested — morph(morph(store + root) + epoch)

inner = tree_hash((store_int + root_int, MIRROR_NAMESPACE))
hint  = tree_hash((inner_int + epoch,   MIRROR_NAMESPACE))

The phrase "the root should be a morphed version" reads naturally as a nested morph, and this composes with the existing structure rather than widening it.

Proceeding on (B) unless corrected, because it matches the wording most closely and because the inner morph(store + root) is independently useful — it names the store-root pair epoch-independently, which is the thing a publisher funds.

Why the choice is not cosmetic

Plain addition aliases, and adding a third term makes it worse. The existing morph is store_int + epoch, and the crate already documents the collision deliberately (namespace.rs:83-93): a store one unit ahead at epoch n and one behind at epoch n+1 produce the same value. With a third additive term, (store, root, epoch) triples that sum identically collide far more readily — roots are 32-byte hashes, so store + root spans the full range and near-collisions between unrelated pairs become ordinary rather than exotic.

The crate defends against this today by recomputing the morph from a candidate store id and comparing (coin.rs:85-87, used at query.rs:325), which the legacy could not do. That defence must be extended to the root: a candidate coin is only for (store, root) if recomputing from both reproduces the hint. Without it, per-root funding could be misdirected to a colliding pair — which is a money consequence, not a lookup nuisance.

Nesting (B) reduces the exposure: the inner hash is uniformly distributed before the epoch is added, so the outer sum is not adding two structured 32-byte values.

Consequences already settled by this

• Enumerating "which roots does anyone serve for store X" is NOT possible from the hint alone. That was the trade-off flagged earlier and it is accepted by this directive. If the app or CLI needs that query, it needs the root list from somewhere else — the node's own .dig directory for its own stores, or an external index for other people's. Worth confirming that no planned surface depends on enumerating other nodes' roots, because this shape forecloses it.
• The .dig trigger becomes exactly expressible: the .dig file is (store, root), and so is the coin's identity. One file, one coin, per epoch.
• morph_store_launcher_id's signature changes, which is breaking for the crate — but at zero consumers, and it ships alongside root support in the same release.

Sequencing

PR#4 (the ceiling move) still publishes as 0.4.0, unchanged and orthogonal. Root support is the next crate change and is the new blocker for #377.

[MichaelTaylor3d]

SETTLED: the hint is morph(store + root + epoch) — flat, three terms (user, 2026-08-27)

"oh your right it should be morph(store + root + epoch)"

Supersedes my previous comment, which proceeded on the nested reading (B). Option (A) is the decision. Do not build the nested form.

pub fn morph_store_root_launcher_id(
    store_launcher_id: Bytes32,
    root: Bytes32,
    epoch: &BigInt,
) -> Bytes32 {
    let store_int = BigInt::from_signed_bytes_be(store_launcher_id.as_ref());
    let root_int  = BigInt::from_signed_bytes_be(root.as_ref());
    (store_int + root_int + epoch, MIRROR_NAMESPACE).tree_hash().into()
}

Closest to the legacy shape (store + epoch), one term added. Signature is illustrative — name and argument order are the implementer's call; the arithmetic is not.

The collision defence is now LOAD-BEARING, not defence-in-depth

This shape carries the collision property I flagged, and choosing it makes the existing mitigation mandatory rather than nice-to-have. Stating it plainly so it is not treated as a caveat:

The morph is plain addition, so distinct triples collide by construction. (store, root, epoch) and (store+1, root−1, epoch) produce the identical hint. The crate already documents the two-term version of this deliberately (namespace.rs:83-93) — a store one unit ahead at epoch n and one behind at epoch n+1 hash the same. Adding a third full-width term does not create the problem, but it widens it: roots are 32-byte hashes spanning the whole range, so colliding pairs stop being exotic.

Therefore: a candidate coin counts as advertising (store, root, epoch) ONLY if recomputing the morph from all three reproduces its hint. Never trust the hint to tell you what it is for.

The crate already does exactly this for the two-term case — MirrorCoin::advertises recomputes and compares (coin.rs:85-87, used by discover at query.rs:325), which is precisely what the legacy could not do because its hint was a bare integer. That check must be extended to take the root, and it must be extended in the same change that adds the root — not after.

Why this matters more here than in legacy: the point of per-root coins is that a publisher funds a specific root. A collision that misdirects discovery is a lookup nuisance; a collision that misdirects funding moves money to the wrong claim. That is the difference between this shape and the legacy one, and it is why the recompute is not optional.

Evidence this owes

• A test that a deliberately constructed colliding triple — same hint, different (store, root, epoch) — is rejected by the advertises-check. It must go RED if the recompute is removed. The existing aliasing test at namespace.rs:83-93 is the pattern; extend it to three terms rather than replacing it.
• A golden vector over the new morph, computed and committed before any consumer adopts it, per the puzzle-hash lesson from PR#4: a vector written after the fact proves nothing.

Unchanged by this

Root in the hint (not memos) stands, with its accepted trade-off: enumerating "which roots does anyone serve for store X" is not possible from the hint alone. Your own stores are answerable from the .dig directory; other nodes' are not.

PR#4 still publishes as 0.4.0 — ceiling only, orthogonal. Root support is the next crate change and the blocker for #377.

[MichaelTaylor3d]

DISCOVERY vs VERIFICATION are separate mechanisms — and the DHT should carry the coin id (user directive, 2026-08-27)

Verbatim:

"the dht is the primary discover mechanism for the stores and roots. The dht does not prove if a coin was colllateralized. So when incentives are calculated, we fine the nodes with this root using the dht and then we query the chain if it was collateralized. So morph(store + root + epoch) is the most direct way to find that. I would even argue its more direct to do morph(store + root + pubkey + epoch) so we can find the exact collateral coin. Even better the dht should include the coinid of the collateral coin and we look it up to verify."

This reframes what the chain is for, and it is a better design than the one recorded above. Stating the split plainly because it changes several earlier conclusions:

	mechanism	answers
Discovery	the DHT	who is serving store X at root Y?
Verification	the chain	is that node's claim actually bonded?

The chain is not the discovery path. It never needed to be — that was an assumption carried over from the legacy design, where getAllEpochPeers was a chain scan because there was no DHT to ask.

This removes the trade-off I recorded earlier, and it removes the collision risk

Two things I wrote above are now obsolete:

1. "Enumerating which roots are served for store X is not possible from the hint" — accepted earlier as a real cost. It is not a cost, because that query belongs to the DHT, which can answer it directly.
2. The collision defence — I made recompute-and-compare load-bearing because plain addition means (store, root, epoch) and (store+1, root−1, epoch) collide. With the coin id carried in the DHT record, verification is a direct coin lookup and the morph is not on the trust path at all. A collision cannot misdirect funding if funding never resolves through the morph.

The recompute-and-compare check should still exist — it costs little and it guards the fallback path — but it stops being the thing standing between a collision and misdirected money.

The three candidate shapes, and what each is for

(A) morph(store + root + epoch) — one hint shared by every node serving that root in that epoch. Good for "who serves this?", which is the question the DHT now owns.

(B) morph(store + root + pubkey + epoch) — one hint per node per root per epoch. Good for "did THIS node bond it?", which is the question the incentive calculation actually asks, since the DHT has already told it which nodes to check.

(C) coin id in the DHT record — a direct lookup. No search, no morph, no collision surface, one round trip.

These are not alternatives; (C) is the fast path and one of (A)/(B) is the fallback. A DHT record can be stale, absent, or lying, so the chain must remain independently queryable — but the everyday path should be (C).

(B) fits the stated flow better than (A). The incentive calculation already knows the node; what it needs is that node's specific coin. Under (A) it gets every coin at that hint and must sift; under (B) it computes one hint and looks. The cost is that (B) makes the chain unusable for open-ended "who serves this?" queries — which is fine precisely because the DHT owns that question.

Recommendation: (B) + (C). Coin id in the DHT for the fast path; morph(store + root + pubkey + epoch) as the fallback that needs no DHT record to work.

Consequences that need deciding

• Which pubkey? The node's identity key, its synthetic key, or the owner puzzle hash. The legacy advertisement carried publicSyntheticKey in memo slot 1 and never used it ("we will utilize this for future features") — this may be that future feature, and if so the slot's original intent should be honoured rather than re-invented.
• A DHT record claiming a coin id is untrusted input. Verification means fetching that coin and checking it is at the mirror puzzle, is $DIG, carries the full collateral, and advertises the claimed (store, root, epoch) — not merely that a coin with that id exists. NC-12 applies: the DHT peer is untrusted.
• The fallback must be reachable when the DHT record is absent, or a node that fails to publish its coin id becomes unverifiable and therefore unpaid — a silent penalty for a DHT problem rather than a collateral problem.
• This crosses into dig-dht, which is a separate crate and a separate consumer. The DHT record shape is a cross-repo contract (§4.1) and needs its own child ticket.

Sequencing unchanged

PR#4 still publishes as 0.4.0 — the ceiling move, orthogonal to all of this. Root support is the next crate change; this directive changes what that change should contain, so it must be settled before that work starts rather than after.

[MichaelTaylor3d]

SETTLED: the hint is morph(store + root + owner_puzzle_hash + epoch), plus two decisions I was asked to make

User, 2026-08-27: "which pubkey - owner puzzle hash" / "the other questions you decide"

The identity term: owner puzzle hash

Confirmed by the user, and it is the right one for a reason worth recording: the crate already uses the owner puzzle hash as the identity axis everywhere else. query::list is keyed on it, and reclaim authorises against it via the lineage proof (reclaim.rs:49-53, NotOwner). Choosing a synthetic key or an identity key would have introduced a second notion of "whose coin is this" alongside the one the crate already enforces on chain.

It also has a property the alternatives lack: it is recoverable from the coin itself. MirrorCoin::owner_puzzle_hash() reads it out of the lineage proof, so a verifier can recompute the full morph from the coin in hand and check it against the hint the coin was found under — closing the loop without trusting anything the announcer said.

DECISION 1 — a DHT-supplied coin id is a POINTER, never evidence

The coin id tells you WHERE to look. It never tells you WHAT the coin is for. Both halves matter, and conflating them is the whole risk: a hostile or stale DHT peer can hand you a real, well-formed, fully-collateralised coin id that bonds something else entirely — a different root, a different store, a different node's claim. Every property would check out except the one that matters.

So verification fetches the coin and proves four things independently of anything the DHT said:

1. It sits at mirror_coin_puzzle_hash() — verified, not inferred from the hint or the amount. This is precisely what the legacy failed to do, which is why its collateral was a claim rather than a bond.
2. It is genuinely $DIG, with the asset id re-derived from the creating spend, not read off the coin's own assertion about itself.
3. It carries the full collateral (20 DIG / 20,000 CAT mojos).
4. Recomputing morph(store + root + owner_puzzle_hash + epoch) from the four terms reproduces the hint the coin actually carries. This is the step that binds the coin to the claim. Without it, items 1-3 prove only that a valid mirror coin exists somewhere.

NC-12 applies unchanged: the DHT peer is untrusted. The record is an optimisation that saves a lookup, and its worst case must be a wasted round trip — never a wrong verdict.

DECISION 2 — the morph is the fallback, and no node is penalised for a missing coin id

Earlier I worried that a node failing to publish its coin id becomes unverifiable and therefore unpaid — a silent penalty for a DHT problem rather than a collateral problem. On reflection that concern dissolves, because we know all four morph terms without the record.

By the time verification runs, the DHT has already told us the node exists and which (store, root) it serves. The epoch comes from the clock. The owner puzzle hash comes from the node's DHT entry. So:

coin id present in the DHT record  ->  direct lookup, then verify (1)-(4)
coin id absent                     ->  compute the morph, query by hint, then verify (1)-(4)

Both paths end at the same four checks. The coin id only skips the hint query. A node that omits it is slower to verify, not unverifiable.

Consequence for the DHT record shape: the coin id is OPTIONAL. Do not make it required, and do not treat its absence as a fault — that would convert a transport-layer omission into a payment penalty, which is exactly the failure this decision avoids. A node with no DHT entry at all is simply not discovered, which is correct: the DHT owns discovery.

What this changes for the crate

morph_store_launcher_id gains two terms and becomes morph(store + root + owner_puzzle_hash + epoch). That is breaking, and it lands in the same release as root support.

The collision defence extends to all four terms. Plain addition still means distinct 4-tuples can collide; MirrorCoin::advertises must recompute from all four and compare (today it does two — coin.rs:85-87, used by discover at query.rs:325). With the coin id as the fast path the morph is off the trust path in the common case, but the fallback is a real path and must be sound on its own.

Still owed by whoever builds this

• A test that a deliberately constructed colliding 4-tuple is rejected by the advertises-check — RED if the recompute is removed.
• A test that a coin id pointing at a valid mirror coin for a different (store, root) is rejected. That is the specific attack this decision exists to stop, and it is the one a well-formed-fixtures-only test suite will miss.
• A golden vector over the new four-term morph, committed before any consumer adopts it — per the PR#4 lesson, a vector written afterwards proves nothing.