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 fraction 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 helps to determine the specific type of asset you are dealing with inside the category provided by the unit type. For example, if you are dealing with a world currency, the unit token would be the ISO 4217 currency code. The combination of the unit type and unit token should provide all the information you’ll need to be able to exchange that asset to 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 hundredth’s precision as cents are commonly used when dealing with US dollars.
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 are some examples of how you would use amount data to exchange amounts.
Exchanging USD to EUR
Section titled “Exchanging USD to EUR”- Check that unit types are exchangeable
- Look up conversion rate between unit tokens
- Find 0.91 USD → EUR
- Produce a new amount, with the target unit token and converted unit count
Exchanging USD micros to display amount
Section titled “Exchanging USD micros to display amount”- Check that unit types are exchangeable
- Find they can be converted, if the unit tokens match
- Ensure unit tokens match
- Find rate of 0.0000001
- Produce a new amount, with the target unit token and converted unit count
Note: this would be only for display, fractional amounts cannot be stored in the system.
Selling a house
Section titled “Selling a house”- Check that unit types are exchangeable
- Find that they are, if there is a valid sale price
- Lookup sale price for holding_e1f29e8fd139963
- Produce a new amount, with the sale currency and sale price
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 unitCount is whole numbers only. 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 not exact when dealing with fractions. Unfortunately, these small approximations can add up to a big of discrepancy over millions of transactions. String Theory avoids this problem by having the precision declared in advance and then storing only whole numbers.
It sounds small, and adds weirdness to using the system, but we promise that if you store fractions in any monetary system this will eventually become a problem.