Value
A Value element represents an amount of fungible tokens on a universe chain. Values standardize fungible tokens within the protocol, making them programmable both on universe chains and on the Previous chain.
Before a value can be used in objects, it must be registered in the Element Registry, providing the token standard, contract address, and related materials during registration.
For example, if you're creating an NFT representing a gift card, you can conceptualize it as an object composed of two elements: a value element representing the face value, say 20 $USDC, and a material element representing the card’s background image.
On the universe chain, the set contract holds the token for the object (meaning whoever owns the object can withdraw or use the $USDC). On the Previous chain, the kind contract can read the current balance from the Value element, load the token image, resize it, and overlay it on the background image.
Representation
A Value is represented by the following structure:
struct Value {
uint64 token;
uint192 amount;
}
Fields
| Type | Field | Desc |
|---|---|---|
uint64 | token | The ID of the fungible token contract. |
uint192 | amount | The amount of the fungible token. |
The higher 8 bits of the token field are used to indicate the token standard. The lower 56 bits of the token field are an index to identify a specific token among all tokens registered under the same standard.
Token Standards
Currently supported standards for fungible tokens include:
| Standard Type | Standard Value | Description |
|---|---|---|
TOKEN_STD_NATIVE | 1 | Native token (e.g., ETH). |
TOKEN_STD_20 | 2 | ERC-20-like tokens(e.g., USDC). |
Additional token standards can be registered by users, allowing for future token types to be supported.
Encoding
Value can be encoded as a uint256 or a bytes32::
uint256 encoded1 = (uint256(token) << 192) | uint256(amount);
bytes32 encoded2 = bytes32((uint256(token) << 192) | uint256(amount));
Limitation
The amount field is allocated 192 bits, which allows for a maximum value of 2^192 - 1. While this is large enough for most scenarios, tokens with very high decimal places might approach this upper limit, potentially leading to an overflow or other boundary-related issues in cases of extremely high precision.