Currency
Overview
This currency pallet provides an interface for the other pallets to manage balances of different currencies.
Accounts have three balances per currency: they have a free
, reserved
, and frozen
amount.
Users are able to freely transfer free  frozen
balances, but only the parachain pallets are able to operate on reserved
amounts.
Frozen
is used to implement temptorary locks of free balances like vesting schedules.
The external API for dispatchable and RPC functions use ‘thin’ amount types, meaning that the used currency depends on the context. For example, the currency used in deposit_collateral depends on the vault’s currencyId
.
Sometimes, as is for example the case for register_vault, the function takes an additional currencyId
argument to specify the currency to use. In contrast, internally in the parachain amounts are often represented by the Amount
type defined in this pallet, which in addition to the amount, also contains the used currency. The benefit of this type is twofold. First, we can guarantee that operations only work on compatible amounts. For example, it prevents adding DOT amounts to KSM amounts. Second, it allows for a more convenient api.
Data Model
Structs
Amount
Stores an amount and the used currency.
Parameter 
Type 
Description 


Balance 
The amount. 

CurrencyId 
The used currency. 
Functions
from_signed_fixed_point
Constructs an Amount
from a signed fixed point number and a currencyId
. The fixed point number is truncated. E.g., a value of 2.5 would return 2.
Specification
Function Signature
from_signed_fixed_point(amount, currencyId)
Parameters
amount
: The amount as fixed point.currencyId
: The currency.
Preconditions
amount
MUST be representable as a 128 bit unsigned number.
Postconditions
An
Amount
MUST be returned whereAmount.amount
is the truncatedamount
argument, andAmount.currencyId
is thecurrencyId
argument.
to_signed_fixed_point
Converts an Amount
struct into a fixedpoint number.
Specification
Function Signature
to_signed_fixed_point(amount)
Parameters
amount
: The amount struct.
Preconditions
amount
MUST be representable by the signed fixed point type.
Postconditions
amount.amount
MUST be returned as a fixed point number.
convert_to
Converts the given amount
into the given currency.
Specification
Function Signature
convert_to(amount, currencyId)
Parameters
amount
: The amount struct.currencyId
: The currency to convert to.
Preconditions
convert when called with
amount
andcurrencyId
MUST return successfully.
Postconditions
convert MUST be called with
amount
andcurrencyId
as arguments.
checked_add
Adds two amounts.
Specification
Function Signature
checked_add(amount1, amount2)
Parameters
amount1
: the first amount.amount2
: the second amount.
Preconditions
amount1.currencyId
MUST be equal toamount2.currencyId
Postconditions
MUST return the sum of both amounts.
checked_sub
Subtracts two amounts.
Specification
Function Signature
checked_sub(amount1, amount2)
Parameters
amount1
: the first amount.amount2
: the second amount.
Preconditions
amount1.currencyId
MUST be equal toamount2.currencyId
Postconditions
MUST return
amount1  amount2
.
saturating_sub
Subtracts two amounts, or zero if the result would be negative.
Specification
Function Signature
saturating_sub(amount1, amount2)
Parameters
amount1
: the first amount.amount2
: the second amount.
Preconditions
amount1.currencyId
MUST be equal toamount2.currencyId
Postconditions
if
amount2 <= amount1
, then this function MUST returnamount1  amount2
.if
amount2 > amount1
, then this function MUST return zero.
checked_fixed_point_mul
Multiplies an amount by a fixed point scalar. The result is rounded down.
Specification
Function Signature
checked_fixed_point_mul(amount, scalar)
Parameters
amount
: the Amount struct.scalar
: the fixed point scalar.
Preconditions
The multiplied amount MUST be representable by a 128 bit unsigned integer.
Postconditions
MUST return a copy of
amount
that is multiplied by the scalar. The result MUST be rounded down.
checked_fixed_point_mul_rounded_up
Like checked_fixed_point_mul, but with a roundedup result.
Specification
Function Signature
checked_fixed_point_mul_rounded_up(amount, scalar)
Parameters
amount
: the Amount struct.scalar
: the fixed point scalar.
Preconditions
The multiplied amount MUST be representable by a 128 bit unsigned integer.
Postconditions
MUST return a copy of
amount
that is multiplied by the scalar. The result MUST be rounded up.
rounded_mul
Like checked_fixed_point_mul, but with a rounded result.
Specification
Function Signature
rounded_mul(amount, scalar)
Parameters
amount
: the Amount struct.scalar
: the fixed point scalar.
Preconditions
The multiplied amount MUST be representable by a 128 bit unsigned integer.
Postconditions
MUST return a copy of
amount
that is multiplied by the scalar. The result MUST be rounded to the nearest integer.
checked_div
Divides an amount by a fixed point scalar. The result is rounded down.
Specification
Function Signature
checked_div(amount, scalar)
Parameters
amount
: the Amount struct.scalar
: the fixed point scalar.
Preconditions
The multiplied amount MUST be representable by a 128 bit unsigned integer.
Postconditions
MUST return a copy of
amount
that is divided by the scalar.
ratio
Returns the fixed point ratio between two amounts.
Specification
Function Signature
ratio(amount1, amount2)
Parameters
amount1
: the first Amount struct.amount2
: the second Amount struct.
Preconditions
amount1.currencyId
MUST be equal toamount2.currencyId
The ratio MUST be representable by the fixed point type.
Postconditions
MUST return the ratio between the two amounts.
Comparisons: lt, le, eq, ge, gt
Compares two amounts
Specification
Function Signature
[ltleeqgegt](amount1, amount2)
Parameters
amount1
: the first Amount struct.amount2
: the second Amount struct.
Preconditions
amount1.currencyId
MUST be equal toamount2.currencyId
Postconditions
MUST return true when the comparison holds.
transfer
Transfers the amount between the given accounts.
Specification
Function Signature
transfer(amount, source, destination)
Parameters
amount
: the Amount struct.source
: the account to transfer from.destination
: the account to transfer to.
Preconditions
source
MUST have sufficient unlocked funds in the given currency
Postconditions
The free balance of
source
MUST decrease byamount.amount
(in the currency determined byamount.currencyId)
The free balance of
destination
MUST increase byamount.amount
(in the currency determined byamount.currencyId)
lock_on
Locks the amount on the given account.
Specification
Function Signature
lock_on(amount, accountId)
Parameters
amount
: the Amount struct.accountId
: the account to lock the amount on.
Preconditions
The given account MUST have sufficient unlocked funds in the given currency.
Postconditions
The free balance of
accountId
MUST decrease byamount.amount
(in the currency determined byamount.currencyId)
The locked balance of
accountId
MUST increase byamount.amount
(in the currency determined byamount.currencyId)
unlock_on
Unlocks the amount on the given account.
Specification
Function Signature
unlock_on(amount, accountId)
Parameters
amount
: the Amount struct.accountId
: the account to unlock the amount on.
Preconditions
The given account MUST have sufficient locked funds in the given currency.
Postconditions
The locked balance of
accountId
MUST decrease byamount.amount
(in the currency determined byamount.currencyId)
The free balance of
accountId
MUST increase byamount.amount
(in the currency determined byamount.currencyId)
burn_from
Burns the amount on the given account.
Specification
Function Signature
burn_from(amount, accountId)
Parameters
amount
: the Amount struct.accountId
: the account to lock the amount on.
Preconditions
The given account MUST have sufficient locked funds in the given currency.
Postconditions
The locked balance of
accountId
MUST decrease byamount.amount
(in the currency determined byamount.currencyId)
mint_to
Mints the amount on the given account.
Specification
Function Signature
mint_to(amount, accountId)
Parameters
amount
: the Amount struct.accountId
: the account to mint the amount on.
Postconditions
The
free
balance ofaccountId
MUST increase byamount.amount
(in the currency determined byamount.currencyId)