Struct WalletSyncStatusResult 

pub struct WalletSyncStatusResult {
    pub phase: WalletSyncPhase,
    pub peak_height: Option<u32>,
    pub chia_peer_count: Option<u32>,
    pub watched_addresses: Option<u32>,
    pub subscription_peer_count: Option<u32>,
    pub chia_peer_peak_height: Option<u32>,
}

control.wallet.syncStatus — is the wallet’s chain replica being kept current, how far has it got, and how many Chia peers is it using?

Synced means CAUGHT UP AND CONNECTED, not ONCE CAUGHT UP

phase is WalletSyncPhase::Synced only when the initial catch-up completed AND at least one Chia peer connection is live right now. A wallet that caught up yesterday and has been offline since MUST report Syncing. This makes phase == Synced STRICTLY STRONGER than WalletPeakResult::synced, which reflects only the completed-catch-up flag: Synced implies that flag, the flag does not imply Synced. Both types say so, because the two notions share a word and nothing but the docs would keep them aligned.

This is the whole reason the method exists. A surface asking does my wallet stay synced? cannot be answered by a flag that a disconnected wallet still sets.

Synced is nevertheless not a freshness guarantee. Being connected is not being up to date: a live connection to a stalled or lagging peer satisfies the predicate while the replica goes stale. The phase reports that catch-up finished and a peer is attached — that nothing KNOWN is preventing the replica from being kept current — and a consumer needing actual freshness must compare peak_height against something, not read this phase. Stating the limit is the point: this family exists because a surface asserted more than it knew.

The height NEVER comes from a third-party oracle

peak_height is the node’s OWN replica’s height or null. It MUST NOT fall back to the coinset oracle. control.wallet.peak deliberately does fall back, because it answers a different question — what height is the chain at? — whereas this field answers how far has this replica got? An oracle’s height here would report a caller’s own sync progress using a number the replica never reached, which is precisely the reading a progress display makes.

chia_peer_count: 0 is a disambiguator, not a phase

A sync that is running while connected to nothing reports Syncing with a count of 0, and a consumer SHOULD render the count alongside the phase for exactly that reason: “syncing — no peers” is honest where a bare “syncing” implies progress that is not happening. null means the node cannot observe the count at all and licenses no claim about connectivity either way.

watched_addresses is what makes an idle sync readable

A sync following nothing is idle, and the phase alone does not say whether that is correct. The count is the second fact that settles it: 0 beside WalletSyncPhase::NoWalletEnrolled is a complete and honest picture, while 0 beside WalletSyncPhase::WalletNotUnlocked is a wallet whose coins nobody is following. A consumer SHOULD render the two together for the same reason it renders the peer count beside Syncing.

Some(0) is an OBSERVED zero — the node looked and is following no addresses. None means the node did not report the number, which is not the same claim and MUST NOT be rendered as zero: a node that cannot say how many addresses it follows has not told you that it follows none.

A Synced phase with watched_addresses: Some(0) is a contradiction a conforming node MUST NOT emit — a sync following no addresses has not caught anything up. A consumer meeting it SHOULD trust the count over the phase, because the count is the narrower claim.

An older node’s payload still parses

A node that predates watched_addresses omits the key, and it deserializes to None — the node did not report it. That tolerance is required, not incidental: a mandatory new field would make every older node unreadable to a client that has it, which is dig_ecosystem#2609 in mirror image — the same fail-closed break with the old and new sides swapped. A contract that tolerates a token from the future must equally tolerate a payload from the past.

Every Option field here behaves this way, because serde decodes a missing Option to None. So peak_height and chia_peer_count are absent-tolerant too, and have been since this type shipped. Only phase is structurally mandatory. A conforming node MUST still emit all four keys — absence is a compatibility allowance for older builds, never a licence to omit an observation — and a consumer MUST read an absent count as unreported rather than zero.

These are CHIA peers, not DIG peers

chia_peer_count counts CHIA FULL-NODE peers the wallet’s chain sync is connected to. It is NOT the DIG gossip/content peer count from control.peerStatus (connected_peers / relay_peer_count); the two are unrelated numbers that move independently. A surface that placed one of them beside a wallet sync status under a bare label of “peers” would assert something false — a node with many DIG peers and no Chia peer is a wallet that is not syncing at all. A caller that wants BOTH networks’ counts reads PeerCountsResult, which is the one call that answers for each network by name.

The duplicated field is ONE observation

chia_peer_count also appears on PeerCountsResult, and the two are the SAME observation: a conforming node MUST serve them from one source, and they MUST agree within a single node’s view. The field is duplicated rather than moved because it is load-bearing HERE — chia_peer_count: 0 beside Syncing is the honest “syncing — no peers” state, and a phase separated from its count reads as a contradiction. A DIG content-network count, by contrast, is not a wallet fact and does not vary with wallet state, which is why it is absent from this type rather than added for symmetry.

Which field combinations are meaningful

{phase: Synced, peak_height: null} MUST NOT be emitted. A node records its peak BEFORE it marks the initial catch-up complete, so a completed catch-up always has a height behind it; a Synced with no height describes a state a conforming node cannot be in, and a consumer has no honest reading for it.

{phase: NotStarted, peak_height: <some height>} is the opposite case, and is EXPLICITLY LEGITIMATE — it is not a contradiction and MUST NOT be “fixed”. The height is persisted in the wallet database, while the phase describes whether a sync is running IN THIS PROCESS. A node that synced yesterday and has just restarted reports exactly this, and reports it truthfully: here is the height I reached, and no sync is running right now. Forbidding the pair would force a conforming node to either fabricate a phase it is not in or discard a height it genuinely has — which is the dishonesty this method was created to prevent. peak_height: null alongside NotStarted is equally legitimate and means a wallet that has never synced at all.

No confirmation-depth arithmetic happens here

The height recorded is the height of the LAST EXISTING block the peer view reported (NewPeakWallet.height / RespondPuzzleState.height from a real full node). This surface performs no depth arithmetic. dig_ecosystem#2483 records that peak_height’s meaning differs between a simulator (the NEXT height) and a full node (the last existing one), so a consumer computing depth must floor its own input rather than assume a convention.

Fields

phase: WalletSyncPhase

Which state the wallet’s chain sync is in. See WalletSyncPhase.

peak_height: Option<u32>

The replica’s own peak height, or null when it has none — never height 0 as a stand-in for unknown, and never an oracle’s height. See the type docs.

chia_peer_count: Option<u32>

How many CHIA full-node peers the sync is connected to. 0 is an observed zero; null means the node cannot observe the count. Not the DIG peer count — see the type docs.

watched_addresses: Option<u32>

How many addresses the wallet sync is actually following. Some(0) is an observed zero; None means the node did not report the number at all — including because it predates the field. See the type docs for why that distinction is load-bearing.

subscription_peer_count: Option<u32>

How many peers the REPLICA’s own subscription supervisor is writing through. The supervisor holds AT MOST ONE subscription peer by design, so this is a 0-or-1 fact about whether the replica is currently being kept fed — never a measure of network reach. None means no supervisor is attached at all, not that it counted zero.

This is deliberately NOT chia_peer_count and MUST NOT be summed with it. Before dig_ecosystem#2806 this crate’s chia_peer_count carried this narrower number instead of the wallet’s true peer count, so a node with five peers serving every read reported chia_peer_count: 1 — the subscription supervisor’s single writer standing in for the whole peer set. The two fields exist side by side so that confusion cannot recur: one counts what the replica is fed BY, the other counts what the wallet’s sync is actually CONNECTED to.

chia_peer_peak_height: Option<u32>

The peak height this node’s OWN Chia peers have ANNOUNCED — not the replica’s own progress (see peak_height) and not any oracle’s reading. None until at least one peer has said something; never 0, which every real block height is trivially above and so can never be an honest “unobserved” stand-in.

A value here is evidence those peers are live and talking, independent of whether the replica itself has caught up to it.

Trait Implementations

impl Clone for WalletSyncStatusResult

fn clone(&self) -> WalletSyncStatusResult

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for WalletSyncStatusResult

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

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for WalletSyncStatusResult

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

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Eq for WalletSyncStatusResult

impl PartialEq for WalletSyncStatusResult

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

Equality operator ==.

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

Inequality operator !=.

impl Serialize for WalletSyncStatusResult

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 WalletSyncStatusResult