Documentation

# ERTP Data Types

ERTP introduces and uses several data types.

# Amount

An Amount is a description of digital assets, answering the questions "how much?" and "of what kind?". It is an AmountValue ("how much?") labeled with a Brand ("of what kind?"). The AmountMath object introduces a library of methods that can be used to manipulate and analyze Amounts.

Note that Amounts can describe either fungible or non-fungible assets.

someAmount: {
  brand: someBrand,
  value: someValue
}

# AmountShape

An AmountShape is a description of non-fungible digital assets. Similar to Amount, AmountShape has 2 properties: a Brand, which states what kind of asset this is, and a ValueShape, which is an object containing however many properties are required to describe this non-fungible asset. Note that an asset's ValueShape is defined by the elementShape parameter when the asset's Issuer is created via the makeIssuerKit() function.

someAmountShape: {
  brand: someBrand,
  valueShape: someValueShape
}

# AmountValue

An AmountValue is the part of an Amount that describes the value of something that can be owned or shared: how much, how many, or a description of a unique asset, such as $3, Pixel(3,2), or “Seat J12 for the show September 27th at 9:00pm”. For a fungible Amount, the AmountValue is usually a non-negative BigInt such as 10n or 137n. For a non-fungible Amount, the AmountValue might be a CopySet containing strings naming particular rights or objects representing the rights directly. AmountValues must be Keys.

# AssetKind

There are several kinds of Assets.

  • AssetKind.NAT : Used with fungible assets. AmountValues are natural numbers using the JavaScript BigInt (opens new window) type to avoid overflow risks from using the usual JavaScript Number type.
  • AssetKind.SET : Deprecated.
  • AssetKind.COPY_SET : Used with non-fungible assets where there can't be duplicates (e.g., assigned seats in a stadium). AmountValues are arrays of objects.
  • AssetKind.COPY_BAG : Used with non-fungible assets where there can be duplicates. (e.g., weapons in a computer game). AmountValues are arrays of objects.

Even though very different mathematical processes are performed, AmountMath methods work for all kinds of assets.

Use makeIssuerKit() to specify which AssetKind your contract uses. See the Issuer documentation for details on how to use this method.

import { AssetKind, makeIssuerKit } from '@agoric/ertp';
makeIssuerKit('quatloos'); // Defaults to AssetKind.NAT and undefined DisplayInfo
makeIssuerKit('kitties', AssetKind.COPY_SET); // Defaults to undefined DisplayInfo

# DisplayInfo

A DisplayInfo data type is associated with a Brand and gives information about how to display that Brand's Amounts. DisplayInfo has one optional property, decimalPlaces, which takes a non-negative integer value.

The decimalPlaces property tells the display software (opens new window) how many places to move the decimal point over to the left so as to display the value in the commonly used denomination (e.g., display "10.00 dollars" rather than "1000 cents").

Fungible digital assets are represented in integers, in their smallest unit. For example, the smallest unit for a US dollar might be either dollar or cent. If it's dollar, decimalPlaces would be 0. If it's cent, decimalPlaces would be 2. Similarly, if you want the smallest unit of ether (the cryptocurrency coin used on the Ethereum network) to be wei (one ether = 1018 wei), then decimalPlaces would be 18.

Non-fungible assets have values that are arrays, so you shouldn't specify a decimalPlaces value for them.

decimalPlaces should be used for display purposes only. Any other use is an anti-pattern.

DisplayInfo also has an AssetKind property. Its value specifies the kind of the associated asset.

← Agoric REPL →