# Amount Math
Depositing and withdrawing assets from a
purse
and manipulating payment
amounts
all require adding and subtracting digital assets. ERTP
uses amountMath
methods for all these operations.
amountMath
methods also check their arguments' brand
,
throwing an error if the wrong brand
was used.
An amountMath
is one of three different kinds, each of which
implements the same methods. Which kind is used for a particular brand
depends
on what was specified when the brand
and its issuer
were
created. The kinds are:
MathKind.NAT
(nat
): Used with fungible assets.amount
values
are natural numbers (non-negative integers).MathKind.STRING_SET
(strSet
): Used with non-fungible assets.amount
values
are strings.MathKind.SET
(set
): Used with non-fungible assets.amount
values
are objects or records with multiple properties.
makeIssuerKit(allegedName, amountMathKind)
creates a new issuer
,
mint
, brand
, and amountMath
.
The second, optional, argument specifies which kind
of amountMath
is used for the brand
in a one-to-one
association with the new issuer
. It defaults to MathKind.NAT
.
For example:
makeIssuerKit('Quatloos'); // Defaults to MathKind.NAT
makeIssuerKit('Quatloos', MathKind.STRING_SET);
makeIssuerKit('Quatloos', MathKind.SET);
On the other hand, if you are not writing a Zoe contract and need to
use amountMath
, you probably want to
make and use a local amountMath
whose methods will work synchronously.
makeLocalAmountMath(issuer)
returns a promise for a local AmountMath
that works on the same brand
as the one associated with the issuer
argument.
const quatloosLocalAmountMath = await makeLocalAmountMath(quatloosIssuer);
# AmountMath Methods
The following is a brief description and example of each amountMath
method. For
more detail, click the method's name to go to its entry in the ERTP
API Reference.
Information Getting Methods
- amountMath.getBrand()
- For this
amountMath
, return thebrand
it can operate on.. const quatloosBrand = quatloosAmountMath.getBrand();
- For this
- amountMath.getValue(amount)
- Returns the
value
of theamount
argument. const { amountMath: quatloosAmountMath } = makeIssuerKit('quatloos'); const quatloos123 = quatloosAmountMath.make(123); // returns 123 const value = quatloosAmountMath.getValue(quatloos123);
- Returns the
- amountMath.getAmountMathKind()
- Returns a string of either
'nat'
,'str'
, or'strSet'
, indicating the kind of values thisamountMath
operates on. // amountMath kind defaults to `nat` const { amountMath: quatloosAmountMath } = makeIssuerKit('quatloos'); const kind = quatloosAmountMath.getAmountMathKind(); // returns 'nat'
- Returns a string of either
- amountMath.getEmpty()
- Returns an
amount
representing an emptyamount
(which is the identity element for theamountMath
add()
andsubtract()
operations. Note that this value varies depending on thebrand
and itsamountMath
kind (MathKind.NAT
,MathKind.STR
, orMathKind.STRING_SET
). const { amountMath: quatloosAmountMath } = makeIssuerKit('quatloos'); // Returns an empty amount for this issuer. // Since this is a fungible amount it returns 0 const empty = quatloosAmountMath.getEmpty();
- Returns an
- amountMath.getBrand()
Comparison Methods
- amountMath.isEmpty(amount)
- Returns
true
if itsamount
argument is empty, otherwisefalse
. const { amountMath: quatloosAmountMath } = makeIssuerKit('quatloos'); const empty = quatloosAmountMath.getEmpty(); const quatloos1 = quatloosAmountMath.make(1); // returns true quatloosAmountMath.isEmpty(empty); // returns false quatloosAmountMath.isEmpty(quatloos1);
- Returns
- amountMath.isGTE(leftAmount, rightAmount)
- Returns
true
if theleftAmount
argument is greater than or equal to therightAmount
argument, otherwisefalse
. const { amountMath: quatloosAmountMath } = makeIssuerKit('quatloos'); const empty = quatloosAmountMath.getEmpty(); const quatloos1 = quatloosAmountMath.make(1); // Returns true quatloosAmountMath.isGTE(quatloos1, empty); // Returns false quatloosAmountMath.isGTE(empty, quatloos1);
- Returns
- amountMath.isEqual(leftAmount, rightAmount)
- Returns
true
if theleftAmount
argument equals therightAmount
argument const { amountMath: quatloosAmountMath } = makeIssuerKit('quatloos'); const empty = quatloosAmountMath.getEmpty(); const quatloos1 = quatloosAmountMath.make(1); const anotherQuatloos1 = quatloosAmountMath.make(1); // Returns true quatloosAmountMath.isEqual(quatloos1, anotherQuatloos1); // Returns false quatloosAmountMath.isEqual(empty, quatloos1);
- Returns
- amountMath.coerce(allegedAmount)
- Takes an
amount
and returns it if it's a validamount
. If invalid, it throws an error. const { amountMath: quatloosAmountMath } = makeIssuerKit('quatloos'); const quatloos50 = quatloosAmountMath.make(50); quatloosAmountMath.coerce(quatloos50); // equal to quatloos50
- Takes an
- amountMath.isEmpty(amount)
Manipulator Methods
- amountMath.add(leftAmount, rightAmount)
- Returns an
amount
that is the union of theleftAmount
andrightAmount
amount
arguments. For a fungibleamount
, this means add their values. For a non-fungibleamount
, it usually means including all elements from bothleftAmount
andrightAmount
. const { amountMath: myItemsAmountMath } = makeIssuerKit('myItems', 'strSet'); const listAmountA = myItemsAmountMath.make(harden(['1', '2', '4'])); const listAmountB = myItemsAmountMath.make(harden(['3'])); // Returns an amount containing all of ['1', '2', '4', '3'] const combinedList = myItemsAmountMath.add(listAmountA, listAmountB);
- Returns an
- amountMath.subtract(leftAmount, rightAmount)
- Returns a new
amount
that is theleftAmount
argument minus therightAmount
argument (i.e. for strings or objects everything inleftAmount
not inrightAmount
). IfleftAmount
doesn't include the contents ofrightAmount
, it throws an error. const { amountMath: myItemsAmountMath } = makeIssuerKit('myItems', 'strSet'); const listAmountA = myItemsAmountMath.make(harden(['1', '2', '4'])); const listAmountB = myItemsAmountMath.make(harden(['3'])); const listAmountC = myItemsAmountMath.make(harden(['2'])); // Returns ['1', '4'] const subtractedList = myItemsAmountMath.subtract(listAmountA, listAmountC); // Throws error t.throws(() => myItemsAmountMath.subtract(listAmountA, listAmountB), { message: 'some of the elements in right ((an object)) were not present in left ((an object))', });
- Returns a new
- amountMath.add(leftAmount, rightAmount)
Amount Creation Methods
- amountMath.make(allegedValue)
- Takes a
value
argument and returns anamount
by making a record with thevalue
and thebrand
associated with theamountMath
. const { amountMath: quatloosAmountMath, brand: quatloosBrand, } = makeIssuerKit('quatloos'); /// An `amount` with `value` = 837 and `brand` = Quatloos const quatloos837 = quatloosAmountMath.make(837); const anotherQuatloos837 = harden({ brand: quatloosBrand, value: 837 }); t.deepEqual(quatloos837, anotherQuatloos837);
- Takes a
- amountMath.getEmpty()
- Returns an
amount
representing an emptyamount
(which is the identity element for theamountMath
add()
andsubtract()
operations. Note that this value varies depending onamountMath
's associatedbrand
and whetheramountMath
is of kindMathKind.NAT
,MathKind.STR
, orMathKind.STRING_SET
. const { amountMath: quatloosAmountMath } = makeIssuerKit('quatloos'); // Returns an empty amount for this issuer. // Since this is a fungible amount it returns 0 const empty = quatloosAmountMath.getEmpty();
- Returns an
- amountMath.make(allegedValue)
# Methods on other objects
These methods either use or return amountMath
objects:
- makeIssuerKit(allegedName, amountMathKind)
- Creates a new
amountMath
that uses theamountMath
kind designated by theamountMathKind
argument (MathKind.NAT
,MathKind.STR
,MathKind.STRING_SET
). Also creates a newmint
,issuer
, andbrand
. const { issuer, mint, brand, amountMath } = makeIssuerKit('quatloos');
- Creates a new
- issuer.getAmountMathKind()
- Returns the kind of
amountMath
(MathKind.NAT
,MathKind.STR
, orMathKind.STRING_SET
). const myAmountMathKind = quatloosIssuer.getAmountMathKind();
- Returns the kind of
- zcf.getAmountMath(brand)
- Returns the
amountMath
object associated with thebrand
argument. const quatloosAmountMath = zcf.getAmountMath(quatloosBrand);
- Returns the