Struct Amount

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

Number of millisatoshis.

This type represents a number of millisatoshis (thousands of satoshi) which is the base unit of the lightning network. It provides ordinary arithmetic and conversion methods.

Invariants

This type guarantees that the amount stays less than or equal to 21 million bitcoins. However unsafe code must not rely on this, at least for now. This implies that arithmetic operations always panic on overflow.

Display implementation

To avoid confusion, the amount is displayed with msat suffix - e.g. 42 msat. No other representations are supported yet, feel free to contribute!

Implementations

impl Amount

pub const ZERO: Amount

Zero bitcoins.

pub const ONE_MSAT: Amount

One millisatoshi

pub const MAX: Amount

21 million bitcoins.

pub const ONE_SAT: Amount

One satoshi

pub const ONE_BTC: Amount

One bitcoin

pub fn from_msat(msat: u64) -> Result<Self, OverflowError>

Constructs the amount from raw millisatosis.

The value is directly converted with an overflow check.

Errors

This method returns an error if the amount exceeds Bitcoin supply cap

Example

let msat = ln_types::Amount::from_msat(1000).unwrap();
assert_eq!(msat, ln_types::Amount::ONE_SAT);

pub fn from_sat(sat: u64) -> Result<Self, OverflowError>

Constructs the amount from raw satosis.

The value is converted with an overflow check.

Errors

This method returns an error if the amount exceeds Bitcoin supply cap

Example

let msat = ln_types::Amount::from_sat(100_000_000).unwrap();
assert_eq!(msat, ln_types::Amount::ONE_BTC);

pub fn to_msat(self) -> u64

Converts the value to raw millisatoshis.

Example

let msat = ln_types::Amount::ONE_SAT.to_msat();
assert_eq!(msat, 1000);

pub fn to_sat(self) -> Result<u64, FractionError>

Attempts to convert the value to raw satoshis.

Errors

This method returns an error if the number of millisatoshis isn’t rounded to thousands.

Example

let msat = ln_types::Amount::ONE_SAT.to_sat().unwrap();
assert_eq!(msat, 1);

pub fn to_sat_floor(self) -> u64

Converts to satoshis rounding down.

Example

let msat = ln_types::Amount::ONE_MSAT.to_sat_floor();
assert_eq!(msat, 0);

pub fn to_sat_ceiling(self) -> u64

Converts to satoshis rounding up.

Example

let msat = ln_types::Amount::ONE_MSAT.to_sat_ceiling();
assert_eq!(msat, 1);

pub fn to_sat_round(self) -> u64

Converts to satoshis rounding.

Example

let msat = ln_types::Amount::ONE_MSAT.to_sat_round();
assert_eq!(msat, 0);

Trait Implementations

impl Add for Amount

Panics on overflow

type Output = Amount

The resulting type after applying the + operator.

fn add(self, rhs: Amount) -> Self::Output

Performs the + operation.

impl AddAssign for Amount

Panics on overflow

fn add_assign(&mut self, rhs: Amount)

Performs the += operation.

impl Clone for Amount

fn clone(&self) -> Amount

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for Amount

Displays the amount followed by denomination msat.

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

Formats the value using the given formatter.

impl Default for Amount

fn default() -> Amount

Returns the “default value” for a type.

impl<'de> Deserialize<'de> for Amount

Available on crate feature serde only.

The value is deserialized as u64 msats.

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

where D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Display for Amount

Displays the amount followed by denomination msat.

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

Formats the value using the given formatter.

impl Div<u64> for Amount

type Output = Amount

The resulting type after applying the / operator.

fn div(self, rhs: u64) -> Self::Output

Performs the / operation.

impl DivAssign<u64> for Amount

fn div_assign(&mut self, rhs: u64)

Performs the /= operation.

impl<'a> FromSql<'a> for Amount

Available on crate feature postgres-types only.

Retrieved as i64 msats with range check

fn from_sql( ty: &Type, raw: &'a [u8], ) -> Result<Self, Box<dyn Error + Send + Sync + 'static>>

Creates a new value of this type from a buffer of data of the specified Postgres Type in its binary format.

fn accepts(ty: &Type) -> bool

Determines if a value of this type can be created from the specified Postgres Type.

fn from_sql_null(ty: &Type) -> Result<Self, Box<dyn Error + Send + Sync>>

Creates a new value of this type from a NULL SQL value.

fn from_sql_nullable( ty: &Type, raw: Option<&'a [u8]>, ) -> Result<Self, Box<dyn Error + Send + Sync>>

A convenience function that delegates to from_sql and from_sql_null depending on the value of raw.

impl FromStr for Amount

Accepts an unsigned integer up to 21 000 000 BTC The amount may optionally be followed by denomination msat.

type Err = ParseError

The associated error which can be returned from parsing.

fn from_str(s: &str) -> Result<Self, Self::Err>

Parses a string s to return a value of this type.

impl Hash for Amount

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 Mul<Amount> for u64

Panics on overflow

type Output = Amount

The resulting type after applying the * operator.

fn mul(self, rhs: Amount) -> Self::Output

Performs the * operation.

impl Mul<u64> for Amount

Panics on overflow

type Output = Amount

The resulting type after applying the * operator.

fn mul(self, rhs: u64) -> Self::Output

Performs the * operation.

impl MulAssign<u64> for Amount

Panics on overflow

fn mul_assign(&mut self, rhs: u64)

Performs the *= operation.

impl Ord for Amount

fn cmp(&self, other: &Amount) -> 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.

impl ParseArgFromStr for Amount

Available on crate feature parse_arg only.

fn describe_type<W: Write>(writer: W) -> Result

Writes human-readable description of the type to the writer.

impl PartialEq for Amount

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

Tests for self and other values to be equal, and is used by ==.

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

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialOrd for Amount

fn partial_cmp(&self, other: &Amount) -> 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 Rem<u64> for Amount

type Output = Amount

The resulting type after applying the % operator.

fn rem(self, rhs: u64) -> Self::Output

Performs the % operation.

impl RemAssign<u64> for Amount

fn rem_assign(&mut self, rhs: u64)

Performs the %= operation.

impl Serialize for Amount

Available on crate feature serde only.

The value is serialized as u64 msats.

fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>

where S: Serializer,

Serialize this value into the given Serde serializer.

impl Sub for Amount

Panics on overflow

type Output = Amount

The resulting type after applying the - operator.

fn sub(self, rhs: Amount) -> Self::Output

Performs the - operation.

impl SubAssign for Amount

Panics on overflow

fn sub_assign(&mut self, rhs: Amount)

Performs the -= operation.

impl ToSql for Amount

Available on crate feature postgres-types only.

Stored as i64 msats

fn to_sql( &self, ty: &Type, out: &mut BytesMut, ) -> Result<IsNull, Box<dyn Error + Send + Sync + 'static>>

Converts the value of self into the binary format of the specified Postgres Type, appending it to out.

fn accepts(ty: &Type) -> bool

Determines if a value of this type can be converted to the specified Postgres Type.

fn to_sql_checked( &self, ty: &Type, out: &mut BytesMut, ) -> Result<IsNull, Box<dyn Error + Sync + Send>>

An adaptor method used internally by Rust-Postgres.

fn encode_format(&self, _ty: &Type) -> Format

Specify the encode format

impl<'a> TryFrom<&'a str> for Amount

Accepts an unsigned integer up to 21 000 000 BTC The amount may optionally be followed by denomination msat.

type Error = ParseError

The type returned in the event of a conversion error.

fn try_from(s: &'a str) -> Result<Self, Self::Error>

Performs the conversion.

impl TryFrom<Amount> for Amount

Available on crate feature bitcoin-units only.

type Error = OverflowError

The type returned in the event of a conversion error.

fn try_from(value: Amount) -> Result<Self, Self::Error>

Performs the conversion.

impl TryFrom<Amount> for Amount

Available on crate feature bitcoin-units only.

type Error = FractionError

The type returned in the event of a conversion error.

fn try_from(value: Amount) -> Result<Self, Self::Error>

Performs the conversion.

impl TryFrom<Box<str>> for Amount

Available on crate feature alloc only.

Accepts an unsigned integer up to 21 000 000 BTC The amount may optionally be followed by denomination msat.

type Error = ParseError

The type returned in the event of a conversion error.

fn try_from(s: Box<str>) -> Result<Self, Self::Error>

Performs the conversion.

impl TryFrom<String> for Amount

Available on crate feature alloc only.

Accepts an unsigned integer up to 21 000 000 BTC The amount may optionally be followed by denomination msat.

type Error = ParseError

The type returned in the event of a conversion error.

fn try_from(s: String) -> Result<Self, Self::Error>

Performs the conversion.

impl Value for Amount

Available on crate feature slog only.

Logs msats using emit_u64

fn serialize( &self, _rec: &Record<'_>, key: Key, serializer: &mut dyn Serializer, ) -> Result

Serialize self into Serializer

impl Copy for Amount

impl Eq for Amount

impl StructuralPartialEq for Amount