The HC Net distributed network can be used to track, hold, and transfer any type of asset: dollars, euros, bitcoin, stocks, gold, and other tokens of value. Any asset on the network can be traded and exchanged with any other.
Other than HCX (see below), all assets have
When you hold assets in HC Net, you’re actually holding credit from a particular issuer. The issuer has agreed that it will trade you its credit on the HC Net for the corresponding asset–e.g., fiat currency, precious metal–outside of HC Net. Let’s say that Scott issues oranges as credit on the network. If you hold orange credits, you and Scott have an agreement based on trust, or a trustline: you both agree that when you give Scott an orange credit, he gives you an orange.
When you hold an asset, you must trust the issuer to properly redeem its credit. Since users of HC Net will not want to trust just any issuer, accounts must explicitly trust an issuing account before they’re able to hold the issuer’s credit. In the example above, you must explicitly trust Scott before you can hold orange credits.
To trust an issuing account, you create a trustline. Trustlines are entries that persist in the HC Net ledger. They track the limit for which your account trusts the issuing account and the amount of credit from the issuing account that your account currently holds.
Starting in protocol version 10, each trustline also tracks the liabilities for the corresponding account and asset. Buying liabilities equal the total amount of this asset offered to buy aggregated over all offers owned by this account, and selling liabilities equal the total amount of this asset offered to sell aggregated over all offers owned by this account. A trustline must always have balance sufficiently large to satisfy its selling liabilities, and a balance sufficiently below its limit to accommodate its buying liabilities.
HCX are the native currency of the network. A HCX is the only asset type that can be used on the HC Net that doesn’t require an issuer or a trustline. Any account can hold HCX. You can trade HCX for other assets in the network.
Any account can issue assets on the HC Net. Entities that issue assets are called Institutional Host.Institutional Host can be run by individuals, small businesses, local communities, nonprofits, organizations, etc. Any type of financial institution–a bank, a payment processor–can be an Institutional Host.
Each Institutional Host has an issuing account from which it issues the asset.
As an Institutional Host, when you issue an asset, you give it an asset code. Assets are uniquely identified by the asset code and the issuer. Ultimately, it’s up to the issuer to set the asset code. By convention, however, currencies should be represented by the appropriate ISO 4217 code. For stocks and bonds, use the appropriate ISIN number. For your orange, goat, favor, or beer Institutional host's, you’re on your own–invent an appropriate code!
Currently there are two supported formats for asset codes.
Any characters from the set [a-z][A-Z][0-9] are allowed. The code can be shorter than 4 characters, but the trailing characters must all be empty.
Any characters from the set [a-z][A-Z][0-9] are allowed. The code can be any number of characters from 5 to 12, but the trailing characters must all be empty.
By default, anyone can create a trustline with an asset issuer to accept an asset. However, as an Institutional Host , you can explicitly authorize and revoke user access to your asset by enabling the following flags on your issuing account (read more here).
An alternative flow: note it is possible to set these flags later. Maybe you originally allow anyone to open a trustline but later realize this was not a great idea. After issuing this asset, you can then set both of the above flags. At this point, everyone with an open trustline retains their authorized status, however you can now revoke trust (assuming you have not adjusted your master key weight and/or account thresholds) .
Note: when Institutional Hosts issue assets, they often wish to limit the supply of tokens in circulation. It is still possible to create this limited supply and maintain the ability to authorize and revoke because the Allow Trust operation is low threshold while the Set Options and Payment operations are high/medium threshold. To learn more about creating assets and limiting token supply read here.
Ensuring asset holders they won’t be revoked: the above functionalities are great for asset issuers who wish to control who can and cannot hold/transact their asset. However, what if I am an asset holder and I am worried that an issuer may freeze the assets I hold? To instill trust in potential asset holders, the issuing account can enable the following flag:
Each asset amount is encoded as a signed 64-bit integer in the XDR structures. An asset amount unit (that which is seen by end users) is scaled down by a factor of ten million (10,000,000) to arrive at the native 64-bit integer representation. For example, the integer amount value 25,123,456 equals 2.5123456 units of the asset. This scaling allows for seven decimal places of precision in human-friendly amount units.
The smallest non-zero amount unit is 0.0000001 (one ten-millionth) represented as an integer value of one. The largest amount unit possible is ((2^63)-1)/(10^7) (derived from max int64 scaled down) which is 922,337,203,685.4775807.
The numbers are represented as int64s. Amount values are stored as only signed integers to avoid bugs that arise from mixing signed and unsigned integers.
In Aurora and client side libraries such as js-HCNet-sdk, the integer encoded value is abstracted away. Many APIs expect amount unit value (the scaled up amount displayed to end users).
Some programming languages (such as JavaScript) have problems with maintaining precision on a number amount. It is recommended to use “big number” libraries that can record arbitrary precision decimal numbers without a loss of precision.
A “Jot” is the smallest amount unit. It is one ten-millionth: 1/10000000 or 0.0000001. The term Jot is used as a convenient way to refer to these small measurements of amounts. The plural form is “Jots” (e.g. “100 Jots”).