Amounts
String Theory uses a highly flexible amount system to represent assets. It’s capable of representing any world currency, proprietary currencies (like loyalty points), and even non-fungible assets like real estate. It does this by storing three pieces of data with each amount: unit type, unit token, and unit count . We’ll dive into what each of these mean, with examples.
Unit Type
Section titled “Unit Type”The unit type is a string that represents the category of asset, and often the maximum precision of that category. For example, String Theory supports six digit precision for world currencies out of the box using the unit type currency_micros . If the asset category doesn’t have fractional units then don’t worry about specifying it in the unit type. Something like loyalty_points would work just fine for non-fractional units.
Below we’ll provide some sample types, but remember: you can create your own for whatever asset categories you have. There is no need to be limited to the ones explained here.
Unit type examples
Section titled “Unit type examples”- currency_micros : an ISO 4217 world currency with micro (6 digit) maximum precision
- currency_centis : an ISO 4217 world currency with centi (2 digit) maximum precision
- loyalty_points : a proprietary loyalty point currency with no fractional units
- real_estate : an asset representing a real estate holding
- nft : an asset representing an NFT in a blockchain
Unit Token
Section titled “Unit Token”The unit token is a string that clarifies the specific sub-type of an asset. For example, if you are dealing with a world currency, the unit token would be the ISO 4217 currency code. A unit token can only be fully understood in the context of the category defined by unit type. In fact, the combination of the unit type and unit token is such an important concept in String Theory that we have a name for it: Asset Class . An asset class should provide all the information you’ll need to exchange one asset for another. We’ll get more into this later in the practical examples section.
Unit token examples
Section titled “Unit token examples”- ISO 4217 codes (e.g. USD, EUR, JPY)
- referral_credit
- loyalty_points
- 373 Blue Spring St., East Meadow, NY 11554
- property_8c56ef6b-bf92-4362-8815-322c44362334
Unit Count
Section titled “Unit Count”The unit count is the numeric count of the asset that is represented by this amount. Unit counts are always whole numbers so it’s important to know the maximum precision you want to support for the unit type. This is because computers cannot accurately represent decimal numbers without losing precision. For example, if you are dealing with USD you’ll want to at least support hundredths precision as cents are commonly used when dealing with US dollars. See the fractional units section for more details.
If you are using the String Theory UI you’ll see currencies, in particular, formatted as decimals in the international format appropriate for that currency for your convenience, but all APIs will always return only whole numbers for unit counts.
Unit count examples
Section titled “Unit count examples”(In currency_micros USD)
- 1000000 (1 USD)
- 350000 (35 cents)
- 25 (25/1,000,000 of a dollar)
- 2.38
- 150281.0000001
Practical Examples
Section titled “Practical Examples”Example amounts
Section titled “Example amounts”Some practical examples of amounts:
Exchanging amounts
Section titled “Exchanging amounts”String Theory’s amounts are designed to provide enough information to be able to exchange between two amounts (or tell if they are incompatible) without having to look at additional metadata. Here is an example of how you would use amount data to exchange amounts:
Exchanging USD to EUR
Section titled “Exchanging USD to EUR”- Check that the asset classes are exchangeable
- Look up conversion rate between asset classes
- Find 0.91 USD → EUR
- Produce a new amount, with the target asset class and converted unit count
String Theory has first class support for exchanging amounts and recording exchanges. This can be complex, particularly if you manage non-traditional assets, but we provide lots of tools and flexibility. See the exchanges documentation for detailed information.
Side note: fractional units
Section titled “Side note: fractional units”You might have noticed some strangeness with how String Theory handles fractional numbers. We have a maximum precision as part of the unit type, and the unit count is always a whole number. Why is this?
The answer is a bit complex if you don’t understand how fractions are stored in a computer (binary fractions wikipedia), but the simple summary is this:
Computer systems are not capable of precisely storing fractional values, only approximations
It can get really close, but may not be exact when dealing with fractions. Unfortunately, these small approximations can add up to a big discrepancy over millions of transactions. String Theory avoids this problem by having the precision declared in advance and then storing only whole numbers.
If you are currently working with fractional units, then working with only whole numbers will be a change, but we promise it is worth the cost. If you store fractions in any monetary system this will eventually become a problem.