Amounts, Values, and Brands
Amounts
An amount
describes digital assets. There are no amount
API methods, but AmountMath methods take amounts
as arguments to get information about and manipulate them.
AmountMath.make()
is generally how you make new amounts
. However, you can also make an amount
as an object literal by making a record of a brand
and a value
. While AmountMath.make()
is recommended for proper object-oriented programming, this produces the same result:
const newAmount = { brand: quatloosBrand, value: 5n };
Each amount
has two properties:
- brand: The type of digital asset, such as our imaginary
Quatloos
currency or, in a game, a powerful magic sword with a brand ofPlus3Sword-ABCGames
or similar. - value: How much/many of the asset. Fungible values are natural numbers represented as BigInts. Non-fungible values may be represented as strings naming a particular right, or an arbitrary object representing the rights at issue (e.g., a theater ticket's date, time, row, and seat positions).
amounts
and their values
and brands
can be manipulated by the AmountMath
library. It executes the logic of how amounts
change when digital assets are merged, separated, or otherwise manipulated. For example, you make an offer for something, which is declined. You want to change your offer, represented as an amount
, to be of a greater value
by adding to it.
Brands
A brand
object is an amount
object's type of digital asset, such as our imaginary Quatloos currency or, in a game, a powerful magic sword.
In ERTP, mint
objects create new asset payment
objects. Each mint
has a one-to-one relationship with an issuer
object. And each issuer
object has a one-to-one relationship with a brand
object. This means:
- A
mint
can only create apayment
for one specificbrand
, which must be the samebrand
as their associatedissuer
. - An
issuer
can only create a new emptypurse
for one specificbrand
. - An
amount
is either fungible or non-fungible, as determined by which itsissuer
, and thus itsbrand
, was created to be.
A brand
has three associated methods. The following is a brief description and example of each brand
method. For more detail, click the method's name to go to its entry in the ERTP API Reference.
- aBrand.isMyIssuer()
- Returns
true
if theissuer
argument matches theissuer
associated with thebrand
. We have this method because theissuer
is authoritative and thebrand
is not. You can create apayment
,purse
, oramount
with abrand
that claims a particularissuer
, without thatissuer
having been involved. But if you use thatpayment
orpurse
, it won't be accepted by genuine ones. So to know, you have to verify with theissuer
to see if it agrees. - js
const isIssuer = brand.isMyIssuer(issuer);
- Returns
- aBrand.getAllegedName()
- Returns the
brand
's alleged name, but should not be trusted as accurate. - js
const name = brand.getAllegedName();
- Returns the
- aBrand.getDisplayInfo()
- Returns the
DisplayInfo
associated with thebrand
. TheDisplayInfo
tells the UI how to correctly displayvalues
associated with thebrand
. - js
const myDisplayInfo = brand.getDisplayInfo();
- Returns the
The following methods on other ERTP components also either operate on or return a brand
.
- anIssuer.getBrand()
- Returns the
brand
for theissuer
. Thebrand
is not closely held, so this should not be trusted to identify anissuer
alone. Fake digital assets andamount
s can use thebrand
of anotherissuer
. - js
const myBrand = quatloosIssuer.getBrand(); // myBrand === quatloosBrand
- Returns the
- aPayment.getAllegedBrand()
- Return the
payment
's allegedbrand
. Because apayment
is not trusted, this should be treated with suspicion and verified elsewhere. This example code determines if apayment
we got from untrusted sources is valid. It uses thebrand
to find apurse
we want to deposit it in, then verifies that it's genuine. - js
const allegedBrand = payment.getAllegedBrand(); const probablyAppropriatePurse = brandToPurse.get(allegedBrand); const depositAmount = probablyAppropriatePurse.deposit(payment);
- Return the
AmountValues
AmountValues are the "how many" part of an amount
.
Note that number values (for fungible assets) are represented as BigInt
s and not Number
s. Write 10n
rather than 10
.
There are no value
methods, but two AmountMath
methods use or return them.
- AmountMath.getValue(brand, amount)
- Return the
amount
argument'svalue
- js
const quatloos123 = AmountMath.make(quatloosBrand, 123n); // returns 123 const value = AmountMath.getValue(quatloosBrand, quatloos123);
- Return the
- AmountMath.make(brand, allegedValue)
- Make an
amount
from abrand
and avalue
. - js
const quatloos837 = AmountMath.make(quatloosBrand, 837n);
- Make an