Struct Currency

Represents a currency type. Every single value of Currency defines a distinct currency type. To draw a parallel with real world monetary, each Currency value represents such currencies as USD (US Dollar) or EUR (Euro), not values like $100 or €100.

Implements
IEquatable<Currency>
ISerializable
Namespace: Libplanet.Assets
Assembly: Libplanet.dll
Syntax
public readonly struct Currency : IEquatable<Currency>, ISerializable
Remarks

There are two types of Currency: capped and uncapped. Capped currencies have a hard limit on the maximum minted amount, and uncapped currencies do not have the said limit. To define a Currency you may call either of the following.

Examples

Here is how US Dollar can be represented using Currency:

var USMint = new PrivateKey();
var USD = Currency.Uncapped(ticker: "USD", decimalPlaces: 2, minter: USMint.ToAddress());
var twentyThreeBucks = 23 * USD;
// Or alternatively: USD * 23;
// Or explicitly: new FungibleAssetValue(USD, 23, 0)

Constructors

| Improve this Doc View Source

Currency(IValue)

Deserializes a Currency type from a Bencodex value.

Declaration
public Currency(IValue serialized)
Parameters
Type Name Description
IValue serialized

The Bencodex value serialized by Serialize() method.
See Also

Fields

| Improve this Doc View Source

DecimalPlaces

The number of digits to treat as minor units (i.e., exponent).

Declaration
public readonly byte DecimalPlaces
Field Value
Type Description
Byte
| Improve this Doc View Source

Hash

The deterministic hash derived from other fields.

Declaration
public readonly HashDigest<SHA1> Hash
Field Value
Type Description
HashDigest<SHA1>
| Improve this Doc View Source

Minters

The Addresses who can mint the currency. If this is null anyone can mint the currency.

Declaration
public readonly IImmutableSet<Address>? Minters
Field Value
Type Description
Nullable<IImmutableSet<Address>>
Remarks

Unlike null, an empty set means no one can mint the currency.

See Also
| Improve this Doc View Source

Ticker

The ticker symbol, e.g., "USD".

Declaration
public readonly string Ticker
Field Value
Type Description
String
| Improve this Doc View Source

TotalSupplyTrackable

Whether the total supply of this instance of Currency is trackable.

Declaration
public readonly bool TotalSupplyTrackable
Field Value
Type Description
Boolean

Properties

| Improve this Doc View Source

MaximumSupply

The uppermost quantity of currency allowed to exist. null means unlimited supply.

Declaration
public readonly FungibleAssetValue? MaximumSupply { get; }
Property Value
Type Description
Nullable<FungibleAssetValue>

Methods

| Improve this Doc View Source

AllowsToMint(Address)

Returns true if and only if the given address is allowed to mint or burn assets of this currency.

Declaration
public readonly bool AllowsToMint(Address address)
Parameters
Type Name Description
Address address

The account address to test.
Returns
Type Description
Boolean

true if and only if the given address is allowed to mint or burn assets of this currency.
| Improve this Doc View Source

Capped(String, Byte, (BigInteger Major, BigInteger Minor), Address)

Define a Currency with a maximum supply limit.

Declaration
public static Currency Capped(string ticker, byte decimalPlaces, (BigInteger Major, BigInteger Minor) maximumSupply, Address minter)
Parameters
Type Name Description
String ticker

The ticker symbol, e.g., "USD".
Byte decimalPlaces

The number of digits to treat as minor units (i.e., exponent).
(, )<BigInteger, BigInteger> maximumSupply

The uppermost quantity of currency allowed to exist. For example, the maximumSupply parameter in Currency.Capped("ABC", 2, (123, 45), ...) means that the token ABC can be minted up to 123.45 ABC. See also MaximumSupply field which corresponds to this.
Address minter

The address who can mint the currency. To specify multiple minters, use the See also Minters field which corresponds to this.
Returns
Type Description
Currency

An instance of Currency with a maximum supply limit.
| Improve this Doc View Source

Capped(String, Byte, (BigInteger Major, BigInteger Minor), Nullable<IImmutableSet<Address>>)

Define a Currency with a maximum supply limit.

Declaration
public static Currency Capped(string ticker, byte decimalPlaces, (BigInteger Major, BigInteger Minor) maximumSupply, IImmutableSet<Address>? minters)
Parameters
Type Name Description
String ticker

The ticker symbol, e.g., "USD".
Byte decimalPlaces

The number of digits to treat as minor units (i.e., exponent).
(, )<BigInteger, BigInteger> maximumSupply

The uppermost quantity of currency allowed to exist. For example, the maximumSupply parameter in Currency.Capped("ABC", 2, (123, 45), ...) means that the token ABC can be minted up to 123.45 ABC. See also MaximumSupply field which corresponds to this.
Nullable<IImmutableSet<Address>> minters

The Addresses who can mint the currency. See also Minters field which corresponds to this.
Returns
Type Description
Currency

An instance of Currency with a maximum supply limit.
| Improve this Doc View Source

Equals(Currency)

Declaration
public readonly bool Equals(Currency other)
Parameters
Type Name Description
Currency other
Returns
Type Description
Boolean
| Improve this Doc View Source

Equals(Nullable<Object>)

Declaration
public override readonly bool Equals(object? obj)
Parameters
Type Name Description
Nullable<Object> obj
Returns
Type Description
Boolean
| Improve this Doc View Source

GetHashCode()

Declaration
public override readonly int GetHashCode()
Returns
Type Description
Int32
| Improve this Doc View Source

Legacy(String, Byte, Address)

OBSOLETE! DO NOT USE.

(unless you are upgrading your project from an old version of Libplanet that did not support total supply tracking for Currency and had a legacy Currency defined.)

Define a legacy Currency without total supply tracking, which is internally compatible with the legacy version.

Declaration
public static Currency Legacy(string ticker, byte decimalPlaces, Address minter)
Parameters
Type Name Description
String ticker

The ticker symbol, e.g., "USD".
Byte decimalPlaces

The number of digits to treat as minor units (i.e., exponent).
Address minter

The address who can mint the currency. To specify multiple minters, use the Legacy(String, Byte, Nullable<IImmutableSet<Address>>) See also Minters field which corresponds to this.
Returns
Type Description
Currency

An instance of legacy Currency without total supply tracking.
See Also
| Improve this Doc View Source

Legacy(String, Byte, Nullable<IImmutableSet<Address>>)

OBSOLETE! DO NOT USE.

(unless you are upgrading your project from an old version of Libplanet that did not support total supply tracking for Currency and had a legacy Currency defined.)

Define a legacy Currency without total supply tracking, which is internally compatible with the legacy version.

Declaration
public static Currency Legacy(string ticker, byte decimalPlaces, IImmutableSet<Address>? minters)
Parameters
Type Name Description
String ticker

The ticker symbol, e.g., "USD".
Byte decimalPlaces

The number of digits to treat as minor units (i.e., exponent).
Nullable<IImmutableSet<Address>> minters

The Addresses who can mint the currency. See also Minters field which corresponds to this.
Returns
Type Description
Currency

An instance of legacy Currency without total supply tracking.
| Improve this Doc View Source

Serialize()

Serializes the currency into a Bencodex value.

Declaration
public readonly IValue Serialize()
Returns
Type Description
IValue

The serialized Bencodex value.
| Improve this Doc View Source

ToString()

Declaration
public override readonly string ToString()
Returns
Type Description
String
| Improve this Doc View Source

Uncapped(String, Byte, Address)

Define a Currency without a maximum supply limit.

Declaration
public static Currency Uncapped(string ticker, byte decimalPlaces, Address minter)
Parameters
Type Name Description
String ticker

The ticker symbol, e.g., "USD".
Byte decimalPlaces

The number of digits to treat as minor units (i.e., exponent).
Address minter

The address who can mint the currency. To specify multiple minters, use the Uncapped(String, Byte, Nullable<IImmutableSet<Address>>) See also Minters field which corresponds to this.
Returns
Type Description
Currency

An instance of Currency without a maximum supply limit.
See Also
| Improve this Doc View Source

Uncapped(String, Byte, Nullable<IImmutableSet<Address>>)

Define a Currency without a maximum supply limit.

Declaration
public static Currency Uncapped(string ticker, byte decimalPlaces, IImmutableSet<Address>? minters)
Parameters
Type Name Description
String ticker

The ticker symbol, e.g., "USD".
Byte decimalPlaces

The number of digits to treat as minor units (i.e., exponent).
Nullable<IImmutableSet<Address>> minters

The Addresses who can mint the currency. See also Minters field which corresponds to this.
Returns
Type Description
Currency

An instance of Currency without a maximum supply limit.

Operators

| Improve this Doc View Source

Multiply(BigInteger, Currency)

Gets a fungible asset value with the given quantity of the specified currency.

Declaration
public static FungibleAssetValue operator *(BigInteger quantity, Currency currency)
Parameters
Type Name Description
BigInteger quantity

The major unit of the fungible asset value, i.e., digits before the decimal separator.
Currency currency

The currency to get a value.
Returns
Type Description
FungibleAssetValue

A fungible asset value with the given quantity of the specified currency.
Remarks

This cannot specify MinorUnit but only MajorUnit. For more precision, directly use FungibleAssetValue's constructors instead.

| Improve this Doc View Source

Multiply(Currency, BigInteger)

Gets a fungible asset value with the given quantity of the specified currency.

Declaration
public static FungibleAssetValue operator *(Currency currency, BigInteger quantity)
Parameters
Type Name Description
Currency currency

The currency to get a value.
BigInteger quantity

The major unit of the fungible asset value, i.e., digits before the decimal separator.
Returns
Type Description
FungibleAssetValue

A fungible asset value with the given quantity of the specified currency.
Remarks

This cannot specify MinorUnit but only MajorUnit. For more precision, directly use FungibleAssetValue's constructors instead.

Implements

IEquatable<>
ISerializable

See Also