Struct WalletCoinsParams 

pub struct WalletCoinsParams {
    pub address: String,
    pub asset: Asset,
    pub after_coin_id: Option<String>,
    pub limit: Option<u32>,
}

control.wallet.coins params: which address + asset to read spendable coins for, and which PAGE of them.

The address + asset pair is byte-identical to dig-app’s frozen CoinsRequest and to WalletBalanceParams — a balance is this read reduced to a sum — so the paging fields are purely additive and a caller that names neither asks exactly what it asked before.

Bounded, because an address’s coin count is not (dig-node#381)

A funded address accumulates coins without limit, and every change coin a spend produces adds one. An unpaged read therefore has unbounded cardinality on the same loopback control plane that has NO request rate limiting of any kind (dig_ecosystem#2577) — the identical exposure WalletCoinsByParentParams documents at length, for the identical reason, and on the fallback tier the work lands on a third-party coinset oracle rather than on this node.

Paged rather than capped, for the reason its sibling records: a bare cap is a dead end, because an address holding more coins than the cap could never be fully enumerated, and this read exists so a caller can BUILD A SPEND from the coins it names. A spend built from a silently truncated coin set refuses with a shortfall that is not true.

The paging rules are the sibling’s rules, deliberately

ASCENDING coin_id, a cursor the caller was HANDED rather than an offset, and an out-of-range limit REFUSED rather than clamped. See WalletCoinsByParentParams for why each of those is the money-safe choice; a second set of paging semantics on the same plane would be a place for the two to disagree.

Fields

address: String

The xch1… address to read coins for.

asset: Asset

The asset to read coins for.

after_coin_id: Option<String>

Resume STRICTLY AFTER this coin, in ascending coin_id order. None starts at the first.

This is the value the previous page handed back as cursor — never a value the caller invented, and never a marker for where the chain got to.

limit: Option<u32>

The page size. None asks for COINS_DEFAULT_LIMIT.

A value above COINS_MAX_LIMIT, or a zero, is REFUSED as INVALID_PARAMS rather than clamped — see Self::validated.

Implementations

impl WalletCoinsParams

pub fn first_page(address: impl Into<String>, asset: Asset) -> Self

A first page of coins at one address for one asset: the node’s default size, from the start.

The common case, and the one a caller should not have to spell out — naming a page size means asserting a number this caller invented over the one the contract chose.

pub fn effective_limit(&self) -> u32

The page size this request asks for, resolving None to COINS_DEFAULT_LIMIT.

Stated once here so a node and a client cannot resolve the same omitted field to two different numbers — a disagreement that shows up as a page boundary in the wrong place, which is exactly where a paged walk loses rows. On a coin read a lost row is a coin the caller cannot spend.

pub fn validated(self) -> Result<Self, ControlError>

Normalize the cursor and check the page bound, or reject as -32602 INVALID_PARAMS.

The address is NOT validated here: it is decoded by the node’s own bech32m reader, which is the only thing that can tell a well-formed address from a well-formed string, and this crate has never claimed otherwise for WalletBalanceParams either.

An out-of-range limit is REFUSED, never clamped, for the reason WalletCoinsByParentParams::validated states: a silently shrunk page hands back a cursor for a position the caller did not ask about.

Trait Implementations

impl Clone for WalletCoinsParams

fn clone(&self) -> WalletCoinsParams

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl ControlCall for WalletCoinsParams

const METHOD: ControlMethod = ControlMethod::WalletCoins

The wire method this call invokes.

type Output = WalletCoinsResult

The typed result this call returns on success.

impl Debug for WalletCoinsParams

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

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for WalletCoinsParams

fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>

where D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Eq for WalletCoinsParams

impl PartialEq for WalletCoinsParams

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

Equality operator ==.

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

Inequality operator !=.

impl Serialize for WalletCoinsParams

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 WalletCoinsParams