Struct WalletCoinByIdResult 

pub struct WalletCoinByIdResult {
    pub coin: Option<WalletCoinRecord>,
    pub source: Option<WalletReadSource>,
    pub synced: bool,
    pub peak_height: Option<u32>,
}

control.wallet.coinById — ONE coin, named by its own id, spent or unspent.

An absent coin is an ANSWER; an unreachable chain is an ERROR

coin: null means a chain WAS consulted and holds no such coin. It is NEVER what a caller gets when the chain could not be reached: those are the catalogued errors (crate::error::ControlErrorCode::WalletNoChainSource / WalletReadFailed / WalletRateLimited). Collapsing the two turns “your wifi dropped” into “your mint never happened”, and the remedies are opposite: retry the read, versus stop waiting.

Why this method exists — observing a mint

control.wallet.broadcast’s accepted: true reports mempool admission only; only a buried confirmation of the CREATED COIN is evidence that a mint happened. control.wallet.coins cannot supply it — it answers by ADDRESS and lists UNSPENT coins only, so it can see neither the created DID coin nor the funding coin the mint spent. This method is how that evidence is obtained: read the created coin’s id for a created_height, and the funding coin’s id for a spent_height. Without it a mint can be pushed, real XCH can leave the wallet, and the outcome stays permanently “pending”.

The freshness fields are honest, not decorative

source discloses which tier answered, and every freshness field describes THAT tier — the same rule the by-address reads carry. The bound MUST come from the party that PRODUCED the answer: a fallback answer MUST report the ORACLE’s own peak as peak_height, and a db answer the replica’s peak. A node MUST NOT bound an answer by its own replica’s peak, nor by the high-water mark of its held peers, when neither produced the answer — that stamps a freshness claim onto figures whose freshness it does not bound.

synced is a CONCLUSION, and it is defined exactly: it is true if and only if the reported peak_height is the height the tier that ANSWERED reported in the SAME read that produced these figures, and that tier reports the figures complete as of it. A peak carried over from an earlier read, or obtained from any other exchange, party or tier, does NOT satisfy this.

synced true on a fallback answer therefore asserts only that ONE disclosed oracle answered self-consistently. It is not corroboration by the network and MUST NOT be presented as confirmation by it; a consumer that badges money as current from it MUST also surface the tier.

false and null are the honest answer in three cases, and a node MUST emit them there: an answering tier that tracks no peak of its own; a CACHED row, which no live tier bounds; and a peak the node cannot bind to the same read as the figures.

A negative answer requires a view that could have held the coin

coin: null is a VERDICT — it says stop waiting — so it MUST NOT be served from a view that could not have seen the coin in the first place. A node whose replica is still catching up, or whose local index is address-scoped rather than a full chain view, has NOT established that the coin is absent; it has only established that IT cannot see it. Such a node MUST return WalletNoChainSource or WalletReadFailed and MUST NOT answer coin: null.

This matters precisely for the two coins this method exists to observe. A created coin sits at no wallet address and a spent funding coin is gone from every unspent list, so an address-scoped replica is guaranteed to miss both — and a coin: null from it would report a mint that DID happen as never-having-happened, with the funds already gone. control.wallet.peak is no escape hatch here: it reports that same replica’s height, which can bound a positive confirmation but can never license a negative one.

Fields

coin: Option<WalletCoinRecord>

The coin, or null when the consulted chain holds no coin with that id (see the type docs).

The key MUST be present. null is a verdict here, so an ABSENT key must not decode into one: serde’s default treatment of Option makes a missing field indistinguishable from an explicit null, which would let an unrelated or truncated payload — anything at all carrying a synced field — decode into a confident “the chain holds no such coin”. deserialize_with suppresses that default so the field is genuinely required.

source: Option<WalletReadSource>

Which tier answered, or None from a node too old to disclose it. See WalletReadSource.

synced: bool

Whether this answer reflects a caught-up view of the tier that ANSWERED, measured against that tier’s own peak — never against the node’s replica or its held peers.

true only when that peak came from the SAME read that produced these figures; a carried-over peak means false.

peak_height: Option<u32>

The peak height of the tier that ANSWERED, or null when that tier tracks no peak.

It MUST be the height that tier reported in the SAME read that produced the figures, or null.

Trait Implementations

impl Clone for WalletCoinByIdResult

fn clone(&self) -> WalletCoinByIdResult

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for WalletCoinByIdResult

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

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for WalletCoinByIdResult

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

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Eq for WalletCoinByIdResult

impl PartialEq for WalletCoinByIdResult

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

Equality operator ==.

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

Inequality operator !=.

impl Serialize for WalletCoinByIdResult

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 WalletCoinByIdResult