Enum MirrorBondState 

pub enum MirrorBondState {
    Bonded {
        coin_id: String,
        epoch: u64,
        amount_dig_base_units: u64,
    },
    Pending,
    Unfunded {
        short_dig_base_units: u64,
    },
    Deferred {
        reason: CollateralUnknownReason,
    },
    Withheld,
    Disabled,
    Reclaiming {
        coin_id: String,
        epoch: u64,
        amount_dig_base_units: u64,
    },
}

What this node can say about ONE (store, root) bond right now.

The whole point is that “no coin yet” is never one answer

Six of these seven variants mean “there is no current-epoch coin”, and every one of them calls for a different response from a person: add funds, wait, do nothing, turn a switch back on, or nothing at all because the capsule was never this node’s to advertise. Collapsing any two of them is what produces an hourly out-of-funds alarm about a perfectly healthy node (dig-app#300), which is the defect this method exists to remove.

Vocabulary: withheld, disabled and reclaiming are three different things

dig-node’s internal BondState (mirror/pass.rs) used the single word Withheld for the node-wide collateralisation switch being OFF, while dig-node SPEC.md §25.8 used the same word for a capsule of Relayed provenance — one this node holds but deliberately never advertises. They are not the same state. They differ in SCOPE (one switch for the node, versus one capsule’s provenance) and, more importantly, in REMEDY: an operator told “withheld” about a disabled node goes looking at content, and one told “withheld” about a relayed capsule goes looking for a switch. This contract keeps them apart, and neither existing use survives unchanged:

• Withheld carries §25.8’s meaning — Relayed provenance, per capsule.
• Disabled is the node-wide switch, which §25.8 could not express at all.
• Reclaiming is §25.8’s seventh state, which BondState had no variant for even though the money is still locked while it lasts.

So dig-node MUST rename BondState::Withheld to Disabled and add Withheld + Reclaiming, and §25.8 MUST gain disabled. Serving the old enum under §25.8’s words would publish a contract whose terms mean something else — the drift class this crate exists to prevent.

Withheld is VACUOUS until dig-node’s surface enumerates its SERVED set rather than its Held set. A relayed capsule is by construction absent from the desired-bond set, so a derivation keyed on Held bonds can never emit this variant — it would silently answer “no such row” where §25.8 promises “withheld on purpose”. Declaring it here is correct; a producer that cannot reach it MUST say so rather than report the state as satisfied.

Variants

Bonded

A coin bonding this (store, root) for the CURRENT epoch is on chain.

Fields

coin_id: String

The coin a person can look up, hex, no 0x.

epoch: u64

The epoch it bonds, one-based.

amount_dig_base_units: u64

What the coin actually LOCKS, in DIG base units, read from the coin — never from this epoch’s requirement. A coin created under a previous requirement locks the previous amount, and rendering today’s price against yesterday’s coin is a figure nobody holds.

Pending

A create for this bond has been submitted and has not confirmed.

Nothing is wrong and no money is missing. A client MUST NOT render this as a shortfall.

Unfunded

The wallet cannot cover the create for this bond.

The genuine out-of-funds state, and the ONLY one a client may raise a funding alarm on.

Fields

short_dig_base_units: u64

How many more DIG base units THIS BOND alone needs.

DIG base units — $DIG has 3 decimals, so one unit is 0.001 DIG. It is NOT a mojo, which is XCH’s 1e-12 unit, nine orders of magnitude away. A mirror amount is never quoted in mojos.

Per bond, never a total. “How short is this node overall” is control.collateral.buffer’s question, and it answers it authoritatively.

Deferred

The epoch’s collateral requirement is not known, so no create can be PRICED.

NOT an out-of-funds state. The wallet may be full. A client that renders this as a shortfall tells an operator to send money that would change nothing.

Fields

reason: CollateralUnknownReason

Why the requirement is unknown, in the SAME taxonomy CollateralRequirementResult::Unknown uses.

Reused rather than restated: a second copy of that taxonomy here would drift from the original, and a client already renders these tokens for control.collateral.requirement.

Withheld

This node holds the capsule with Relayed provenance: it does not claim to serve it, and deliberately never advertises it.

§25.8’s withheld. Nothing is wrong, nothing is owed, and there is no remedy — which is exactly why conflating it with Unfunded is the dig-app#300 defect.

Disabled

Collateralisation is switched OFF for this node, so no bond is advertised regardless of funds, provenance or price.

Node-wide, not per capsule: every row reads disabled together. The remedy is a switch, and it is the operator’s own earlier decision — a client MUST NOT present it as a fault.

Reclaiming

A live coin is being reclaimed: the bond is going away and the money is not back yet.

Carries the coin because the funds are STILL LOCKED for the duration. A surface that showed this as unbonded-and-unlocked would report money as available that cannot be spent, and a reclaim that fails leaves the coin exactly where this says it is.

Fields

coin_id: String

The coin being reclaimed, hex, no 0x.

epoch: u64

The epoch that coin bonds — frequently a PREVIOUS epoch, which is usually why it is being reclaimed.

amount_dig_base_units: u64

What it still locks, in DIG base units, read from the coin.

Trait Implementations

impl Clone for MirrorBondState

fn clone(&self) -> MirrorBondState

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for MirrorBondState

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for MirrorBondState

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Eq for MirrorBondState

impl PartialEq for MirrorBondState

fn eq(&self, other: &MirrorBondState) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl Serialize for MirrorBondState

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl StructuralPartialEq for MirrorBondState