Calculate a recommended $DIG buffer from node state, and expose the three funding states

[MichaelTaylor3d]

Parent epic: https://github.com/DIG-Network/dig_ecosystem/issues/3173
Consumer: DIG-Network/dig-app#306 (raises the notification from these states)
Contract: DIG-Network/dig-node-control-interface#32 (closed, published 0.23.0)

Body corrected 2026-08-28. This ticket was filed carrying dig-app#306's body verbatim — a
double-file. The title was always right; the body described the app-side notification. Rewritten
below to the node-side scope. Nothing about the work changed.

Task

Calculate a recommended $DIG buffer from the node's actual state, and expose the three funding
states over the control plane. The node computes; dig-app#306 displays and notifies.

User directive, 2026-08-28, verbatim:

"we also need a os notification when we are dangeriously out of DIG, there should be a calculated
recommended buffer of DIG based on the state of the node."

This extends DIG-Network/dig-app#300, which distinguishes only shortfall
from no shortfall. A binary signal cannot say how much to add, which is the only question a
person receiving it actually has.

The subtlety that decides whether the number is useful or alarmist

Collateral is RECLAIMED, not spent. Each epoch the node creates coins for (store, root, epoch n)
and reclaims epoch n-1 — and #377 specifies that
reclaims run first in every pass and are never gated on funds, precisely so returned collateral
funds the creates behind it.

So the steady-state requirement is roughly one epoch's lock, not one per epoch. A buffer computed
as "requirement x epochs of runway" overstates by the number of epochs and tells a user to acquire
many times what they need.

What the buffer must cover:

1. One epoch's lock — pairs x required_per_store x (1 + margin). The standing commitment.
2. The transition overlap — the window where epoch n coins exist before n-1 is reclaimed, or
   where a reclaim fails or is delayed. This is the real peak, and it is what an operator who has
   never seen a failed reclaim will not have budgeted for.
3. Escalation headroom — the requirement can rise, bounded at +12.5% per epoch
   (UP_STEP_DENOM = 8 in dig-mirror-collateral).

Escalation compounds, so headroom is a horizon choice, not a constant:

after	wall clock	factor	headroom
1 epoch	7 days	x1.12	12.5%
2 epochs	14 days	x1.27	26.6%
4 epochs	28 days	x1.60	60.2%
8 epochs	56 days	x2.57	156.6%
13 epochs	91 days	x4.62	362.4%

Pick a horizon and justify it in the output. A quarter of worst-case escalation demands 4.6x the
current lock, which is not advice anyone will follow; around a month reads as prudent. State the
horizon so the number is checkable rather than magic, and say plainly that the ceiling is a worst
case, not a forecast — in the dead band the multiplier does not move at all.

The three states

state	meaning	dig-app#306 surface
Short now	cannot cover the current epoch; stores are already going uncollateralised	notify
Dangerously low	covers now, but cannot cover the next epoch at the escalation ceiling	notify
Below recommended buffer	fine for several epochs, no cushion	readout only, never a notification

The third must not notify. A node in normal operation sits below a comfortable buffer much of the
time; notifying on it produces a recurring alert that is usually ignorable, which is how a user learns
to ignore the two that matter. That policy is stated here because this ticket owns the state
classification; the notification behaviour itself is dig-app#306.

Requirements

• Say the number. The output must support "Add ~N DIG", not "balance low". The whole point of
  a calculated buffer is that it converts an alarm into an action.
• Show the working — pairs served, current required_per_store, margin, and the horizon used. A
  figure a client cannot render a justification for is a figure a user will not act on.
• Never report a figure on unknown state. If the node cannot determine its requirement or its
  store set, the answer is unknown — not zero and not a guess. This is the money-lie rule;
  BalanceReading's pending/known/unknown split is the shape to reuse.
• Use dig-mirror-collateral's required_per_store. Do not restate the arithmetic:
  equilibrium x multiplier - handicap omits the floor clamp and is wrong as a formula.
• $DIG has 3 decimals; its base unit is 0.001 DIG. A mojo is XCH's base unit (1e-12 XCH). Nine
  orders of magnitude apart — do not let one name touch the other here.

Where it lives

In the node. It needs the store set, the epoch requirement, the margin and the reclaim state, all
of which are node-side. It is a natural fit for the control.collateral.* methods declared in
dig-node-control-interface 0.23.0, so one answer serves the readout, the notification and the margin
cost figure together — and dign can answer the same question on a headless host where no
notification will ever fire.

Acceptance

On a real funded node: the recommended buffer is a specific number the operator can check against
their own arithmetic; the three states are distinguishable over the control plane and from dign; and
a node with unknown state reports unknown rather than a figure.

[MichaelTaylor3d]

Parent epic: https://github.com/DIG-Network/dig_ecosystem/issues/3166 · extends DIG-Network/dig-app#300 (binary shortfall today) · siblings: #389 (calculate) and DIG-Network/dig-app#306 (notify)

The one thing most likely to be got wrong: collateral is reclaimed, not spent, and dig-node#377 runs reclaims first precisely so returned collateral funds the creates. So the steady-state need is one epoch's lock, not one per epoch — a buffer computed as requirement x epochs overstates by the number of epochs and would tell an operator to acquire many times what they need.

[MichaelTaylor3d]

Landed on loop/385-collateral-control, draft PR #395.
Awaiting the gate.

The recommendation is NOT "requirement x epochs of runway". Collateral is RECLAIMED, not spent,
and reclaims run first in every pass and are never gated on funds, so returned collateral funds the
creates behind it — steady state is roughly ONE epoch's lock. A runway-shaped figure would overstate
by the epoch count and tell an operator to buy several times what they need.

The real peak is the transition overlap, so:

recommended = lock + lock x (9/8)^4

which is one epoch's lock, the overlap, and four epochs of escalation headroom in a single
expression rather than three that could double-count each other. Escalation compounds (1 epoch
1.12x, 2 1.27x, 4 1.60x, 8 2.57x, 13 4.62x), so the horizon is a choice: four epochs is about a
month and reads as prudent, where a quarter would demand 4.6x the current lock and nobody would act
on it. The horizon is printed with the figure, and the ceiling is labelled a worst case rather than
a forecast — in the dead band the multiplier does not move at all.

The three states, walked live against a node with two pinned stores:

$ dign collateral buffer --balance 6.06
serving 2 store advertisement(s) at 3.000 DIG each (100 bp margin) — one epoch locks 6.060 DIG
  next epoch could rise to 6.817 DIG at the +12.5%/epoch ceiling
  recommended holding 15.766 DIG (covers the reclaim overlap plus 4 epochs of escalation; a worst case, not a forecast)
  DANGEROUSLY LOW — this epoch is covered, but a rise at the ceiling would not be. Add 9.706 DIG to reach the recommendation.

--balance 5      -> SHORT NOW — ... Add at least 1.060 DIG now, 10.766 DIG to reach the recommendation.
--balance 7      -> below the recommended buffer — fine for now, no cushion. Add 8.766 DIG to reach it.
--balance 15.8   -> funded — at or above the recommended buffer.
(no --balance)   -> holding UNKNOWN — pass --balance <DIG> to see where you stand

below_recommended_buffer is a readout and never a notification, as specified — a normal node
sits there much of the time. Every threshold is pinned from both sides in the tests (one under must
move the state, at-bound must not).

It says the number: "Add 9.706 DIG", with the working shown so it can be sanity-checked.

Two defects the live run caught that the suite could not

Both the same class — an unknown rendered as a reassuring answer:

1. An unreadable hosted-store list defaulted to zero advertisements. Zero obligations and an
   unreadable list produce identical arithmetic — a 0.000 DIG recommendation every balance clears
   — so a node that could not tell how much it owes answered "funded". Now unknown.
2. A node serving nothing said "funded — at or above the recommended buffer", implying its
   stores were covered when it has none.

They surfaced because the live fixture had pairs = 0 while every unit fixture varied it. Also, a
malformed --balance is refused rather than parsed as zero, which would have reported SHORT NOW
over a typo.

Limitation, stated rather than hidden

On a real node today the requirement answers unknown: not_censused, because the census that names
the epoch is #387. That is the honest answer, not a
stub — and this PR lands the record store and the census-epoch marker #387 will write. The known
path above was driven with the record and marker a census produces.

[MichaelTaylor3d]

Correction to my earlier comment, worth recording because I got it wrong first and the wrong version
carried a real hazard.

I said the collateral epoch was a chain-anchored consensus fact the node could not compute, and built
a marker file for the census to write. That was wrong. dig-constants 0.13.0 publishes the
mirror-coin epoch schedule as a wall-clock one — 7-day epochs from a fixed genesis — with
mirror_epoch_at_unix_ms as its canonical implementation. This ticket's own status table said as
much (dig-constants#17 — DONE, 0.12.0 live); I did not follow it before designing around its
absence.

The marker is gone and the epoch is derived. It was not merely unnecessary — it was the hazard it
was supposed to avoid: a marker left behind by a census that has stopped running names an epoch
that is no longer current, and nothing local can detect that. Deriving the epoch makes a stale answer
structurally unrepresentable, because the lookup is always for the epoch current now.

Verified on a real node built from loop/385-collateral-control:

# the node derives the epoch itself — no marker, no hint
$ dign collateral requirement
epoch 104 (protocol v1) — 3.780 DIG per store, before any safety margin
  from 17 advertisement(s) across 820 collateralised owner(s) · multiplier 0.900000x · handicap 0.720 DIG

# the same record edited to name epoch 103 (last week) instead
$ dign collateral requirement
collateral requirement UNKNOWN — this node has not censused the epoch · run the census for this epoch

The arithmetic is delegated to dig-constants, never re-derived: the epoch number is an input to
coin identity (dig_mirror_coin::mirror_hint takes it), so a second implementation would derive
different coins, not a different label. One-based and div_euclid are both pinned in the test at
the only input that distinguishes them — the millisecond before genesis, which a truncating /
collides with epoch 1.

Consequence for this epic: the control.collateral.* surface is live now rather than pending.
The remaining gap is the census that POPULATES the per-epoch record, which is
#387 — a second PR in the same lane.

PR: #395

[MichaelTaylor3d]

Update: dig-node-control-interface 0.24.0 published mid-branch and declares
control.collateral.buffer as its own method. This lane adopted it, deleted its own parallel types
in favour of the contract's, and now serves the method. Conformance 5/5.

Two corrections to what I posted earlier, both of which the published shape forced:

• There are FOUR unknown reasons, not three. I had folded a missing requirement into
  served_set_unknown, which reports a network gap as a local one and sends the operator to
  run a census when the real problem is elsewhere. requirement_unknown is now distinct, and a test
  asserts no buffer reason collides with a census reason.
• funded, not adequate, and the per-epoch lock and the shortfall are derived rather than
  carried. The contract publishes the inputs to both, so a carried field would be a fourth number
  that could disagree with the three it comes from.

The node's own answer is honestly unknown today, and that is the deliverable rather than a stub.
It passes nothing for the served set or the balance instead of approximating them: the served
(owner, store, root) set is enumerated by the census
(#387), and this node cannot know which address holds
an operator's $DIG. A set that merely resembles the served roots — the hosted-store list, which
SPEC §4.2e used to direct clients to — or a balance for the wrong address is a plausible wrong
number on a money surface, which is worse than no number.

dign collateral buffer with no operands asks the node; --roots/--balance are an override so a
person gets a figure today. Real output from a node built on this branch:

$ dign collateral buffer
collateral buffer UNKNOWN — this node cannot list the store roots it serves.

$ dign collateral buffer --roots 17
collateral buffer UNKNOWN — this node does not know your spendable $DIG.

$ dign collateral buffer --roots 17 --balance 80
serving 17 store root(s) at 3.780 DIG each (100 bp margin)
  this epoch locks 64.906 DIG · reclaim overlap 64.906 DIG · escalation headroom 39.060 DIG over 4 epochs (x1.601804 ceiling — a worst case, not a forecast)
  recommended holding 168.872 DIG
  below the recommended buffer — every epoch is covered, but there is no cushion. Add 88.872 DIG to reach it.

--balance 60      -> SHORT NOW — ... Add at least 4.906 DIG now, 108.872 DIG to reach the recommendation.
--balance 64.906  -> DANGEROUSLY LOW — this epoch is covered, but a rise at the ceiling would not be.
--balance 168.9   -> funded — at or above the recommended buffer.

The three requirements from this ticket all hold: the number is an amount to add, not an
adjective; the working is shown so it can be checked; and below_recommended_buffer is excluded from
is_shortfall() so it can never raise a notification.

PR: #395