Struct SingletonAmount 

pub struct SingletonAmount(/* private fields */);

A coin amount that has been proven ODD, and is therefore usable as a singleton’s amount.

Construct with SingletonAmount::new or SingletonAmount::from_funding_coin; there is no other way to obtain one, and the inner value is only readable through SingletonAmount::get.

Why this is public when no public function takes one

It is a PRE-FLIGHT VALIDATOR for callers, not a parameter type: a wallet splitting a funding coin checks the amount it is about to split to — SingletonAmount::new(amount)? — BEFORE building the spend, and gets the same answer, from the same code, that create_did would give it afterwards. The create entry points take a Coin and validate internally, so the type appears in no signature today. (dig_ecosystem#2479 proposes promoting it so dig-account and dig-merkle share this one validated type instead of each restating the odd-amount rule; until then, keep it public — a consumer restating the rule is exactly the drift it exists to prevent.)

Money note

This type proves the amount is launchable, not that it is the amount you meant to lock up. The whole amount becomes the singleton’s amount — see SingletonAmount::from_funding_coin.

Implementations

impl SingletonAmount

pub const MINIMAL: Self

The amount dig-account splits a funding coin down to before minting, and the smallest amount a singleton can carry. Callers with no reason to prefer another value should use it.

This const is built in-module, so it bypasses SingletonAmount::new’s check — the same is true of any const added beside it. Every such const MUST therefore carry an ODD value, and MUST be covered by a test that re-validates it through new (consts_are_odd… below) rather than asserting its literal number, so that an even one turns a test red.

pub const fn new(amount: u64) -> DidResult<Self>

Proves amount is odd, and therefore usable as a singleton’s amount.

Errors

DidError::EvenSingletonAmount if amount is even (which includes zero). A singleton is identified on chain by being the odd-amount output of its launcher, so an even amount can never produce one.

pub const fn from_funding_coin(coin: &Coin) -> DidResult<Self>

Proves the funding coin’s amount is usable as the singleton’s amount.

The whole coin becomes the singleton

A launch built from coin gives the singleton coin.amount — the ENTIRE amount, because this crate is a pure spend builder and emits no change output. Deciding where change goes is the caller’s policy, not this crate’s: dig-account splits an exact 1-mojo coin off its source coin first (CREATE_COIN(puzzle_hash, 1, memos)) and calls in with that, keeping the remainder under its own control. A caller that instead passes a whole 1,000,001-mojo wallet coin mints a 1,000,001-mojo DID and locks the excess in the identity coin.

So: pass a coin pre-split to EXACTLY the amount the singleton should carry.

Errors

DidError::EvenSingletonAmount if the coin’s amount is even — see SingletonAmount::new.

pub const fn get(self) -> u64

The proven-odd amount.

Trait Implementations

impl Clone for SingletonAmount

fn clone(&self) -> SingletonAmount

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Copy for SingletonAmount

impl Debug for SingletonAmount

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

Formats the value using the given formatter.

impl Eq for SingletonAmount

impl Hash for SingletonAmount

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl Ord for SingletonAmount

fn cmp(&self, other: &SingletonAmount) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

where Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized,

Restrict a value to a certain interval.

fn clamp_to<R>(self, range: R) -> Self

where Self: Sized, R: ClampBounds<Self>,

🔬This is a nightly-only experimental API. (clamp_to)

Restrict a value to a certain range.

impl PartialEq for SingletonAmount

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

Equality operator ==.

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

Inequality operator !=.

impl PartialOrd for SingletonAmount

fn partial_cmp(&self, other: &SingletonAmount) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

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

Tests less than (for self and other) and is used by the < operator.

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

Tests less than or equal to (for self and other) and is used by the <= operator.

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

Tests greater than (for self and other) and is used by the > operator.

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

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl StructuralPartialEq for SingletonAmount