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. A fallback answer MUST report synced false and peak_height null however caught-up the node’s own replica is, because the oracle produced the figures and the replica neither produced them nor bounds their freshness. A db answer means the node’s OWN replica answered, so it MUST report synced: true and the replica’s peak.

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 local view; false for every fallback answer.

peak_height: Option<u32>

The peak height this answer reflects, or null when none applies (every fallback answer).

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