0033 XLS-33d: Compact Fungible Tokens (CFT)

[sappenin]

See the updated version of XLS-33d

A previous version of the spec follows:

Title:       Compact Fungible Tokens (CFTs)
Revision:    1 (2022-08-05)

Author:  
             David Fuelling
             Nikolaos Bougalis 
Affiliation: Ripple

1. Compact Fungible Tokens (CFTs)

1.1. Abstract

Trustlines are a fundamental building block for a variety of XRP Ledger tokenization features, including CBDCs and fiat-collateralized stablecoins. However, as more and more token issuers embrace the XRP Ledger, the current size of each trustline will become an impediment to ledger stability and accessibility.

This proposal introduces extensions to the XRP Ledger to support a more compact fungible token (i.e., CFT) type, along with operations to enumerate, purchase, sell and hold such tokens.

Unlike Trustlines, CFTs do not represent bidirectional debt relationships. Instead, CFTs function more like a unidirectional trustline with only one balance, making it simpler to support common tokenization requirements, including even non-monetery use-cases such as tracking reputation points in an online game.

Perhaps as important, however, CFTs require significantly less space than trustlines: ~52 bytes for each CFT held by a token holder, as compared to at least 234 bytes for every new trustline (see Appendix 1 for a more detailed comparison).

1.1.1. Advantages and Disadvantages

Advantages

• Uses a fixed-point balance representation instead of a floating-point representation, yielding the following benefits:
  • CFT balance amounts can easily be added to other ledger objects like escrows, checks, payment channels, and AMMs.
  • The implemenatation can more reliably and easily enforce invariant checks and explicitly track fees.
  • Eliminates edge case floating-point math involving very small amounts violating expected equality conditions (e.g., CFTs will never have to deal with cases where A+B=A for non-zero B or (A+B)+C != A+(B+C)).
• Simpler conceptual model (truslines and rippling make it harder for developers to reason about the system, which increases the risk of errors or value loss).
• Reduces trustline storage requirements which allows more accounts to hold more tokens, for less cost.
• Reduces long-term infrastructure and storage burdens on node operators, increasing network resiliency.
• Improves node performance when processing large volumes of CFT transactions.

Disadvantages

• CFTs would introduce a third asset type on the ledger after XRP and IOUs, which complicates the Payment Engine implementation (if we consider NFTs, then CFTs would be a fourth asset type).
• New transaction and data types require new implementation code from client libraries and wallets to read, display, and transact.
• CFTs will represent a smaller overall balance amount as compared to trustlines (Trustlines can represent and enormous range, roughly between 10^-96 to 10^80).

1.1.2. Assumptions

This proposal makes a variety of assumptions, based upon observations of existing trustline usage in order to produce the most compact representations of data. These assumptions include:

1. Only Unidirectional. This proposal does not support bidirectional trustline constructions, on the assumption that most token issuers leave their trustline limit set to the default value of 0 (i.e., issuers don't allow debt relationships with token holders, by default). Thus, CFTs do not have the same "balance netting" functionality found in trustlines because CFTs have only a single balance as opposed to the two balances used by trustlines.
2. Few Issuances per Issuer. The most common examples of fungible token issuance involve regulatory overhead, which makes it less common for issuers to issue many fungible tokens, in the general case. In addition, existing guidance on xrpl.org advises token issuers to use different addresses for each token issuance in order to better accomodate global freeze activities. Because of this, we assume that any individual issuer will not issue many different fungible tokens using the same address. In particular, this specification limits the number of unique CFT issuances to 32 per issuing account. If an issuer wishes to support more than this number of CFTs, additional addresses can still be used.
3. No Trust Limits. Unlike current Trustline functionality where trust amount limits can be set by either party, this proposal eliminates this feature under the assumption that token holders will not acquire a CFT without first making an off-ledger trust decision. For example, a common use-case for a CFT is a fiat-backed stablecoin, where a token holder wouldn't purchase more stablecoin than they would feel comfortable holding.
4. No TrustSet Transactions. CFTs may be held by any account, and therefore do not require any sort of TrustSet transaction in order to enable holding a CFT. However, in order to disallow an arbitrary CFT sender from consuming recipient account reserves, payment senders have to commit 1 incremental reserve (i.e., currently 2 XRP) when sending a token to any recipient who doesn't currently hold any CFTs (or to any recipient where sending the token would incur a new CFTokenPage).
5. No Rippling. Unlike some existing capabilities of the ledger, CFTs are not eligible for rippling, and thus do not have any configurability settings related to that functionality.

1.2. Creating Compact Fungible Tokens

1.2.1. On-Ledger Data Structures

We propose two new objects and one new ledger structure:

1. A CFTokenIssuance is a new object that describes a fungible token issuance created by an issuer.
2. A CFToken is a new object that describes a single account's holdings of an issued token.
3. A CFTokenPage is a ledger structure that contains a set of CFToken objects owned by the same token holder.

1.2.1.1. The CFTokenIssuance object

The CFTokenIssuance object represents a single CFT issuance and holds data associated with the issuance itself. Token issuances are created using the CFTokenIssuanceCreate transaction and can, optionally, be destroyed by the CFTokenIssuanceDestroy transaction.

1.2.1.1.1. CFTokenIssuance Ledger Identifier

The ID of an CFTokenIssuance object, a.k.a CFTokenIssuanceID is the result of SHA512-Half of the following values, concatenated in order:

• The CFTokenIssuance space key (0x007E).
• The AccountID of the issuer.
• The AssetCode of the issuance.

1.2.1.1.2. Fields

CFTokenIssuance objects are stored in the ledger and tracked in an Owner Directory owned by the issuer. Issuances have the following required and optional fields:

Field Name	Required?	JSON Type	Internal Type
LedgerEntryType	✔️	number	UINT16
Flags	✔️	number	UINT32
Issuer	✔️	string	ACCOUNTID
AssetCode	✔️	string	UINT160
AssetScale	(default)	number	UINT8
MaximumAmount	✔️	string	UINT64
OutstandingAmount	✔️	string	UINT64
LockedAmount	️(default)	string	UINT64
TransferFee	️(default)	number	UINT16
Metadata		string	BLOB
OwnerNode	(default)	number	UINT64

1.2.1.1.2.1. LedgerEntryType

The value 0x007E, mapped to the string CFTokenIssuance, indicates that this object describes a Compact Fungible Token (CFT).

1.2.1.1.2.2. Flags

A set of flags indicating properties or other options associated with this CFTokenIssuance object. The type specific flags proposed are:

Flag Name	Flag Value	Description
lsfFrozen	️0x0001	If set, indicates that all balances should be frozen.
lsfCannotFreezeBalances	️0x0002	If set, indicates that individual balances cannot be frozen. This has no effect on the issuers ability to globally freeze, yet provides token holders with more assurance that individual token holders will not be frozen on an ad-hoc basis, but instead all tokens will only ever be frozen or unfrozen together.
lsfRequiresAuthorization	️0x0004	If set, indicates that individual holders must be authorized. This enables issuers to limit who can hold their assets.
lsfCanEscrow	0x0008	If set, indicates that individual holders can place their balances into an escrow.
lsfCanTrade	0x0010	If set, indicates that individual holders can trade their balances using the XRP Ledger DEX or AMM.
lsfTransferable	️0x0020	If set, indicates that tokens held by non-issuers may not be transferred to any other account except back to the issuer. This enables use-cases like store credit, which often cannot be transferred to any entity except the issuer.

With the exception of the lsfFrozen flag, which can be mutated via the **CFTokenIssuanceSet** transactions, these flags are immutable: they can only be set during the CFTokenIssuanceCreate transaction and cannot be changed later.

1.2.1.1.2.3. Issuer

The address of the account that controls both the issuance amounts and characteristics of a particular fungible token.

1.2.1.1.2.4. AssetCode

A 160-bit blob of data. It is reccommended to use only upper-case ASCII letters in addition to the ASCII digits 0 through 9, the dot (.) character and the dash (-) chracter (dots and dashes should never be the first character of an asset code, and should not be repeated in sequence in any asset code).

While it's possible to store any arbitrary data in this field, implementations that detect the above reccommended character conformance should display them as ASCII for human readability, allowing issuers to support well-known ISO-4207 currency codes in addition to custom codes. This also helps prevents spoofing attacks where a homoglyph might be used to trick a person into using the wrong asset code.

1.2.1.1.2.5. AssetScale

An asset scale is the difference, in orders of magnitude, between a standard unit and a corresponding fractional unit. More formally, the asset scale is a non-negative integer (0, 1, 2, …) such that one standard unit equals 10^(-scale) of a corresponding fractional unit. If the fractional unit equals the standard unit, then the asset scale is 0.

1.2.1.1.2.6. MaximumAmount

This value is an unsigned number that specifies the maximum number of CFTs that can be distributed to non-issuing accounts (i.e., minted). For issuances that do not have a maximum limit, this value should be set to 0xFFFFFFFFFFFFFFFF.

1.2.1.1.2.7. OutstandingAmount

Specifies the sum of all token amounts that have been minted to all token holders. This value can be stored on ledger as a default type so that when it's value is 0, it takes up less space on ledger. This value is increased whenever an issuer pays CFTs to a non-issuer account, and decreased whenever a non-issuer pays CFTs into the issuing account.

1.2.1.1.2.8. TransferFee

This value specifies the fee, in tenths of a basis point, charged by the issuer for secondary sales of the token, if such sales are allowed at all. Valid values for this field are between 0 and 50,000 inclusive. A value of 1 is equivalent to 1/10 of a basis point or 0.001%, allowing transfer rates between 0% and 50%. A TransferFee of 50,000 corresponds to 50%. The default value for this field is 0.

1.2.1.1.2.9. OwnerNode

Identifies the page in the owner's directory where this item is referenced.

1.2.1.1.2. Example CFTokenIssuance JSON

{
    "LedgerEntryType": "CFTokenIssuance",
    "Flags" : 131072,
    "Issuer" : "rsA2LpzuawewSBQXkiju3YQTMzW13pAAdW",
    "AssetCode": "5553440000000000000000000000000000000000",
    "AssetScale": "2"
    "MaximumAmount", "100000000",
    "OutstandingAmount", "5",
    "TransferFee": 50000,     
    "Metadata" : "",
    "OwnerNode": "74"
}

1.2.1.1.3. How do CFTokenIssuance objects work?

Any account may issue up to 32 Compact Fungible Tokens, but each issuance must have a different AssetCode.

1.2.1.1.3.1. Searching for a CFTokenIssuance object

CFT Issuances are uniquely identified by a combination of a type-specific prefix, the isser address and an asset code. To locate a specific CFTokenIssuance, the first step is to locate the owner directory for the issuer. Then, find the directory that holds CFTokenIssuance ledger objects and iterate through each entry to find the instance with the desired AssetCode. If that entry does not exist then the CFTokenIssuance does not exist for the given account.

1.2.1.1.3.2. Adding a CFTokenIssuance object

A CFTokenIssuance object can be added by using the same approach to find the CFTokenIssuance, and adding it to that directory. If, after addition, the number of CFTs in the directory would exceed 32, then the operation must fail.

1.2.1.1.3.3. Removing a CFTokenIssuance object

A CFTokenIssuance can be removed using the same approach, but only if the CurMintedAmount is equal to 0.

1.2.1.1.3.4. Reserve for CFTokenIssuance object

Each CFTokenIssuance costs an incremental reserve to the owner account. This specification allows up to 32 CFTokenIssuance entries per account.

1.2.1.2. The CFToken object

The CFToken object represents an amount of a token held by an account that is not the token issuer. CFTs are acquired via ordinary Payment or DEX transactions, and can optionally be redeemed or exchanged using these same types of transactions.

1.2.1.2.1 Fields

A CFToken object can have the following required and optional fields. Notice that, unlike other objects, no field is needed to identify the object type or current owner of the object, because CFT holdings are grouped into pages that implicitly define the object type and identify the holder.

Field Name	Required?	JSON Type	Internal Type
CFTIssuanceID	✔️	string	UINT256
Amount	✔️	string	UINT64
LockedAmount	default	string	UINT64
Flags	default	number	UINT32

1.2.1.2.1.1. CFTIssuanceID

The CFTokenIssuance identifier.

1.2.1.2.1.2. Amount

This value specifies a positive amount of tokens currently held by the owner. Valid values for this field are between 0x0 and 0xFFFFFFFFFFFFFFFF.

1.2.1.2.1.3. LockedAmount

This value specifies a positive amount of tokens that are currently held in a token holder's account but that are unavailable to be used by the token holder. Locked tokens might, for example, represent value currently being held in escrow, or value that is otherwise inaccessible to the token holder for some other reason, such as an account freeze.

This value is stored as a default value such that it's initial value is 0, in order to save space on the ledger for a an empty CFT holding.

1.2.1.2.1.4. Flags

A set of flags indicating properties or other options associated with this CFTokenIssuance object. The type specific flags proposed are:

Flag Name	Flag Value	Description
lsfFrozen	0x0001	If set, indicates that the CFT owned by this account is currently frozen and cannot be used in any XRP transactions other than sending value back to the issuer. When this flag is set, the LockedAmount must equal the Amount value.

1.2.1.2.2. Example CFToken JSON

{
    "TokenID": "00070C4495F14B0E44F78A264E41713C64B5F89242540EE255534400000000000000",
     "Flags" : 0,
    "Amount" : "100000000",
    "LockedAmount : "0"
}

1.2.1.3. The CFTokenPage ledger entry

This object represents a collection of CFToken objects owned by the same account. It is important to note that the CFToken objects themselves reside within this page, instead of in a dedicated object entry in the SHAMap. An account can have multiple CFTokenPage ledger objects, which form a doubly-linked list (DLL).

In the interest of minimizing the size of a page and optimizing storage, the Owner field is not present since it is encoded as part of the object's ledger identifier (more details in the CFTokenPageID discussion below).

1.2.1.3.1 Fields

A CFTokenPage object may have the following required and optional fields:

Field Name	Required?	JSON Type	Internal Type
LedgerEntryType	✔️	string	UINT16
PreviousPageMin	️	string	UINT256
NextPageMin	️	string	UINT256
PreviousTxnID	️	string	HASH256
PreviousTxnLgrSeq	️	number	UINT32
CFTokens	️ ✔	object	TOKEN

1.2.1.3.1.1. **LedgerEntryType**

Identifies the type of ledger object. This proposal recommends the value 0x007F as the reserved ledger entry type.

1.2.1.3.1.2. **PreviousPageMin**

The locator of the previous page, if any. Details about this field and how it should be used are outlined below, after the construction of the CFTokenPageID is explained.

1.2.1.3.1.3. **NextPageMin**

The locator of the next page, if any. Details about this field and how it should be used are outlined below, after the construction of the CFTokenPageID is explained.

1.2.1.3.1.4. **PreviousTxnID**

Identifies the transaction ID of the transaction that most recently modified this CFTokenPage object.

1.2.1.3.1.5. **PreviousTxnLgrSeq**

The sequence of the ledger that contains the transaction that most recently modified this CFTokenPage object.

1.2.1.3.1.6. **CFTokens**

The collection of CFToken objects contained in this CFTokenPage object. This specification places an upper bound of 32 CFToken objects per page. Objects should be stored in sorted order, from low to high with the low order 96 bits of the TokenID used as the sorting parameter.

1.2.1.3.2. CFTokenPage ID Format

Unlike other object identifiers on the XRP Ledger, which are derived by hashing a collection of data using SHA512-Half, CFTokenPage identifiers are constructed so as to specfically allow for the adoption of a more efficient paging structure, designed to enable user accounts to efficiently hold many CFTs at the same time.

To that end, a unique CFTokenPage ID (a.k.a., CFTokenPageID) is derived by concatenating a 196-bit value that uniquely identifies a particular account's holdings of CFT, followed by a 64-bit value that uniquely identifies a particular CFT issuance. Using this construction enables efficient lookups of individual CFTokenPage objects without requiring iteration of the doubly-linked list of all CFTokenPages.

More formally, we assume:

• The function high196(x) returns the "high" 196 bits of a 256-bit value.
• The function low64(x) returns the "low" 64-bits of a 256-bit value.
• A CFTokenIssuanceID uniqely identifies a CFT Issuance as defined above in ["CFTokenIssuance Ledger Identifier"].
• A CFTokenHolderID uniquely identifies a holder of some amount of CFT (as opposed to other token types such as an NFT) and is defined as the result of SHA512-Half of the following values, concatenated in order:
  • The CFTokenIssuance ledger identifier key (0x007E).
  • The AccountID of the CFT holder.

Therefore:

• Let CFTokenPageID equal high196(CFTokenHolderId) concatenated with low64(CFTokenIssuanceId).
• Let CFTokenIssuanceID A only be included in a page with CFTokenPageId B if and only if low64(A) >= low64(B).

1.2.1.3.3. Example CFTokenPage JSON

{
    "LedgerEntryType": "CFTokenPage",
    "PreviousTokenPage": "598EDFD7CF73460FB8C695d6a9397E907378C8A841F7204C793DCBEF5406",
    "PreviousTokenNext": "598EDFD7CF73460FB8C695d6a9397E9073781BA3B78198904F659AAA252A",
    "PreviousTxnID": "95C8761B22894E328646F7A70035E9DFBECC90EDD83E43B7B973F626D21A0822",
    "PreviousTxnLgrSeq": 42891441,
    "Tokens":
        {
            {
                "CFTokenID": "00070C4495F14B0E44F78A264E41713C64B5F89242540EE255534400000000000000",
                "Amount": 50000
            },
            /* potentially more objects */
       }
}

1.2.1.3.4. How do CFTokenPage objects work?

The page within which a CFToken entry is stored will be formed as described above. This is needed to find the correct starting point in the doubly-linked list of CFTokenPage objects if that list is large. This is because it is inefficient to have to traverse the list from the beginning if an account holds thousands of CFToken objects in hundreds of CFTokenPage objects.

1.2.1.3.4.1. Searching a CFToken object

To search for a specific CFToken, the first step is to locate the CFTokenPage, if any, that should contain that CFToken. For that do the following:

Compute the CFTokenPageID using the account of the owner and the CFTIssuanceID of the token, as described above. Then search for the ledger entry whose identifier is less than or equal to that value. If that entry does not exist or is not a CFTokenPage, the CFToken is not held by the given account.

1.2.1.3.4.2. Adding a CFToken object

A CFToken object can be added by using the same approach to find the CFTokenPage it should be in and adding it to that page. If after addition the page overflows, find the next and previous pages (if any) and balance those three pages, inserting a new page as/if needed.

1.2.1.3.4.2. Removing a CFToken object

A CFToken can be removed by using the same approach. If the number of CFToken in the page goes below a certain threshhold, an attempt will be made to consolidate the page with a previous or subsequent page and recover the reserve.

1.2.1.3.4.3. Reserve for CFTokenPage object

Each CFTokenPage costs an incremental reserve to the owner account. This specification allows up to 32 CFToken entries per page, which means that for accounts that hold multiple CFTs the effective reserve cost per Fungible Token can be as low as R/32 where R is the incremental reserve.

1.3 Transactions

This proposal introduces several new transactions to allow for the creation and deletion of CFT issuances. Likewise, this proposal introduce several new transactions for minting and redeeming discrete instances of CFTs. All transactions introduced by this proposal incorporate the common transaction fields that are shared by all transactions. Common fields are not documented in this proposal unless needed because this proposal introduces new possible values for such fields.

1.3.1 Transactions for Creating and Destroying Compact Fungible Token Issuances on XRPL

We define three transactions related to CFT Issuances: CFTokenIssuanceCreate and CFTokenIssuanceDestroy and CFTokenIssuanceSet for minting, destroying, and updating CFT Issuances respectively on XRPL.

1.3.1.1 The CFTokenIssuanceCreate transaction

The CFTokenIssuanceCreate transaction creates an CFTokenIssuance object and adds it to the relevant directory node of the creator. This transaction is the only opportunity an issuer has to specify any token fields that are defined as immutable (e.g., CFT Flags).

If the transaction is successful, the newly created token will be owned by the account (the creator account) which executed the transaction.

1.3.1.1.1 Transaction-specific Fields

Field Name	Required?	JSON Type	Internal Type
TransactionType	️ ✔	object	UINT16

Indicates the new transaction type CFTokenIssuanceCreate. The integer value is 25 (TODO).

Field Name	Required?	JSON Type	Internal Type
AssetCode	️ ✔	string	BLOB

A 160-bit blob of data. It is reccommended to use only upper-case ASCII letters in addition to the ASCII digits 0 through 9. While it's possible to store any arbitrary data in this field, implementations that detect the above reccommended characters should display them as ASCII for human readability. This also helps prevents spoofing attacks where a homoglyph might be used to trick a person into using the wrong asset code.

Field Name	Required?	JSON Type	Internal Type
AssetScale	️ ✔	number	UINT8

An asset scale is the difference, in orders of magnitude, between a standard unit and a corresponding fractional unit. More formally, the asset scale is a non-negative integer (0, 1, 2, …) such that one standard unit equals 10^(-scale) of a corresponding fractional unit. If the fractional unit equals the standard unit, then the asset scale is 0.

Field Name	Required?	JSON Type	Internal Type
Flags	️	number	UINT16

Specifies the flags for this transaction. In addition to the universal transaction flags that are applicable to all transactions (e.g., tfFullyCanonicalSig), the following transaction-specific flags are defined and used to set the appropriate fields in the Fungible Token:

Flag Name	Flag Value	Description
lsfFrozen	️0x0001	If set, indicates that all balances should be frozen.
lsfCannotFreezeBalances	️0x0002	If set, indicates that individual balances cannot be frozen. This has no effect on the issuers ability to globally freeze.
lsfRequiresAuthorization	️0x0004	If set, indicates that individual holders must be authorized. This enables issuers to limit who can hold their assets.
lsfCanEscrow	0x0008	If set, indicates that individual holders can place their balances into an escrow.
lsfCanTrade	0x0010	If set, indicates that individual holders can trade their balances using the XRP Ledger DEX.
lsfTransferable	️0x0020	If set, indicates that the tokens may not be transferred to any other account except the issuer.

Field Name	Required?	JSON Type	Internal Type
TransferFee		number	UINT16

The value specifies the fee to charged by the issuer for secondary sales of the Token, if such sales are allowed. Valid values for this field are between 0 and 50,000 inclusive, allowing transfer rates of between 0.000% and 50.000% in increments of 0.001.

The field MUST NOT be present if the tfTransferable flag is not set. If it is, the transaction should fail and a fee should be claimed.

Field Name	Required?	JSON Type	Internal Type
MaximumAmount	✔️	string	UINT64

The maximum asset amount of this token that should ever be issued.

Field Name	Required?	JSON Type	Internal Type
Metadata	✔️	string	BLOB

Arbitrary metadata about this issuance, in hex format.

1.3.1.1.2 Example CFTokenIssuanceCreate transaction

{
  "TransactionType": "CFTokenIssuanceCreate",
  "AssetCode": "5553440000000000000000000000000000000000",
  "AssetScale": "2",
  "TransferFee": 314,
  "MaxAmount": "50000000",
  "Flags": 83659,
  "Metadata": "FOO",
  "Fee": 10,
}

This transaction assumes that the issuer of the token is the signer of the transaction.

1.3.2 The CFTokenIssuanceDestroy transaction

The CFTokenIssuanceDestroy transaction is used to remove an CFTokenIssuance object from the directory node in which it is being held, effectively removing the token from the ledger ("destroying" it).

If this operation succeeds, the corresponding CFTokenIssuance is removed and the owner’s reserve requirement is reduced by one.

1.3.2.1 Transaction-specific Fields

Field Name	Required?	JSON Type	Internal Type
TransactionType	✔️	string	UINT16

Indicates the new transaction type CFTokenIssuanceDestroy. The integer value is 26 (TODO).

Field Name	Required?	JSON Type	Internal Type
CFTokenIssuance	✔️	string	UINT256

Identifies the CFTokenIssuance object to be removed by the transaction.

1.3.2.2 Example CFTokenIssuanceDestroy JSON

{
      "TransactionType": "CFTokenIssuanceDestroy",
      "Fee": 10,
      "CFTokenIssuance": "00070C4495F14B0E44F78A264E41713C64B5F89242540EE255534400000000000000"
}

1.3.3 The CFTokenIssuanceSet Transaction

1.3.3.1 CFTokenIssuanceSet

Field Name	Required?	JSON Type	Internal Type
TransactionType	️ ✔	object	UINT16

Indicates the new transaction type CFTokenIssuanceSet. The integer value is 28 (TODO).

Field Name	Required?	JSON Type	Internal Type
CFTokenIssuance	✔️	string	UINT256

The CFTokenIssuance identifier.

Field Name	Required?	JSON Type	Internal Type
Account	✔️	string	ACCOUNTID

An optional XRPL Address of an individual token holder balance to freeze/unfreeze. If omitted, this transaction will apply to all any accounts holding CFTs.

Field Name	Required?	JSON Type	Internal Type
Flag	✔️	string	UINT64

1.3.3.2 Example CFTokenIssuanceSet JSON

{
      "TransactionType": "CFTokenIssuanceSet",
      "Fee": 10,
      "CFTokenIssuance": "00070C4495F14B0E44F78A264E41713C64B5F89242540EE255534400000000000000",
      "Flags": 1
}

1.3.3.1.1 CFTokenSet Flags

Transactions of the CFTokenFreeze type support additional values in the Flags field, as follows:

Flag Name	Flag Value	Description
tfSetFreeze	️0x0001	If set, indicates that all CFT balances for this asset should be frozen.
tfSetUnFreeze	️0x0002	If set, indicates that all CFT balances for this asset should be unfrozen.

Appendix 1: Current Trustline Storage Requirements

As described in issue #3866, the size of a RippleState object is anywhere from 234 to 250 bytes plus a minimum of 32 bytes for object owner tracking, described in more detail here:

FIELD NAME          SIZE IN BITS
================================
LedgerEntryType               16
Flags                         32 ("optional" but present in > 99.99% of cases)
Balance                      384 (160–224 wasted)
LowLimit                     384 (160–224 wasted)
HighLimit                    384 (160–224 wasted)
PreviousTxnID                256
PreviousTxnLgrSeq             32
LowNode                       64 (often has value 0)
HighNode                      64 (often has value 0)
--------------------------------
REQUIRED SUBTOTAL:          1872 (234 bytes)

OPTIONAL FIELDS
--------------------------------
LowQualityIn                  32
LowQualityOut                 32
HighQualityIn                 32
HighQualityOut                32
--------------------------------
MAXIMUM TOTAL SIZE:         2000 (250 bytes)

TODO: Validate these numbers as they may be slightly low for truslintes. For example, in addition to the above data, trustlines require two directory entries for low/high nodes that get created for each trustline (i.e., for each RippleState object). This creates two root objects, each 98 bytes, adding 196 bytes in total per unique issuer/holder. Conversely, for CFTs, the page structure allows for up to 32 issuances to be held by a single token holder while only incurring around 102 bytes for a CFTokenPage. Thus, every time an account wants to hold a new token, the current Trustline implementation would require at least 430 bytes every time. If we imagine a single account holding 20 tokens, CFTs would require ~1040 bytes, whereas trustlines would require ~8,600 bytes!

Potential Future Directions

This specification does not currently enable nor address how CFTs would interact with the DEX, or be addded to any other ledger objects like escrows, payment channels, checks, or any forthcoming AMM specification. However, support for CFTs with these objects should be considered (e.g., perhaps by adapting this proposal to CFTs).

Implementation Notes

1. At present, there is no CFTRedeem transaction because holders of a CFT can use a normal payment transaction to send CFT back to the issuer, thus "redeeming" CFT and removing it from circulation. Note that in order for this to work, issuer accounts may not hold CFT.

2. For CFTokenIssuances that have the lsfRequiresAuthorization flag set, it is envisioned that a DepositPreauth transaction could be used with minor adaptations to distinguish between pre-authorized trustlines and pre-authorized CFTs. Alternatively, we might consider deposit_preauth objects might apply to both, under the assumption that a single issuer restricting trustlines will want to make the same restrictions around CFTs emanating from the same issuer account.

[WietseWind]

Thanks @sappenin and @nbougalis!

Before reading all details I skimmed through & have a first remark/item I'd like more people to comment on. It's about the name. If we want to make it clear(er) for people outside of the XRPL ecosystem that the XRPL is a network that can handle issued tokens, I think it's best not to add specific XRPL token type references to the transaction names.

(Referring to the C, compact)

To us (existing XRPL devs, techies) it's compact, because we know the XRPL and current Trust Lines and IOU's

New people don't, or don't even know the XRPL could even deal with tokens (that's a problem throughout the XRPL's history, people don't know what it can do for a long time)

So instead of CFTokenPage, CFTokenIssuanceCreate, wouldn't it be much easier to understand for new XRPL users if it was just "IssueToken" and "TokenPage"?

As there's already a distinction between the two as one is called token and the other TrustLine+IOU?

[sappenin]

Good suggestion, and no objections from my side. If there aren't other strong opinions, I can update the language.

On a related note, I actually don't love the name CFT but was mostly trying to (1) not stomp on the entire "token" namespace in XRPL and (2) have something that aligned with, yet stayed distinct from, NFT.

The name FT was an obvious candidate, but just felt weird to me...

Naming is hard. :)

[Mwni]

There is an issue with this, and that is the fact that until now the entire community has gotten used to calling trustline IOUs "tokens". Somestimes "coins". But "issued currencies" or "IOUs" is a very rare term. This could introduce a great deal of confusion.

[wojake]

I agree with Wietse, most XRPL devs understand the "compactness" to CFT but newcomers won't at a first glance.

I think CFT is an okay name for the proposal, different systems have different concepts/token implementation and devs need to adapt to the changes/differences if they're newcomers.

[dangell7]

So we would have issued currencies, fungible tokens, and non fungible tokens... ok

I would cast a vote for FT nomenclature and then if it were me I would restructure the documentation to highlight FT over IC's and show the specific use case where IC would be used over FT. Then sort of phase it out.

In what use case would it be better to use an IC over an FT?

[mDuo13]

@dangell7 The biggest use case for "issued currency" / IOU tech on the XRPL that CFT don't cover is community credit, or any similar system that involves bidirectional balances where either side can be net positive or net negative. There are probably others; theoretically speaking at least I've seen descriptions of a hypothetical "credit issuing gateway" where the trust lines and balances are reversed from token issuers we have today.

As for the opening question, I am not a fan of redefining "token" definition yet again and undoing some or all of the work we did to migrate away from terms like "issued currency" and "IOU" up to now. I am OK with "CFT" but another, descriptive name for this type of asset could be unidirectional fungible token? The nice thing about that name is that it reflects the assumptions and innate definition of the asset class rather than defining it in terms of how its implementation's efficiency compares to the other implementation. (This way, "UFT" holds as a distinction even if the trust line implementation gets updated.)

[tequdev]

It appears that CFTokenIssuanceFreeze is also represented as a CFTokenIssuanceSet.

[sappenin]

Great catch, and thanks for pointing that out -- I've updated the description above (better late than never on my part)

;)

[mDuo13]

One thing with the NFT-related transactions that we should consider before implementing this feature is the size of metadata. With NFToken-related transactions, any change to an NFTokenPage object results in pretty much the entire (large) page being listed in both the "PreviousFields" and the "FinalFields" sections of the metadata (see XRPLF/rippled#4333 for details & examples).

CFTs have the potential to change even more often, so we should make sure to do some optimization there so that it doesn't cause a massive increase in the size of transaction metadata and the amount of space a given amount of transaction history occupies (both in RAM and on disk).

[shawnxie999]

In a CFTokenIssuance object, the MaximumAmount is the cap on the total amount of a single CFT issued to non-issuer accounts right? In other words, OutstandingAmount <= MaximumAmount is always true?

[sappenin]

Yes, that's correct.

[kennyzlei]

Have we considered what a clawback capability might look like with CFTs? I suspect some ideas on clawback of IOU might translate over to CFT as well

[sappenin]

We didn't discuss clawback when we drafted this specification, but I think the idea is useful and should be added to the specification as an option. I'll update the spec shortly to reflect something like that and ping the group once I have something.

Note that things like "clawback" (and most CFT knobs/features) should only be specified at CFT creation, and then not allowed to mutate after that point. This is so that anyone interacting with a token has confidence that the characteristics of the token won't change from underneath them. Despite this (seeming) constraint, if an issuer wanted to transition from "clawback-disabled" to "clawback-enabled", the issuer could easily do this by creating a new CFT issuance (with clawback enabled) and then deprecate the original CFT.)

[kennyzlei]

Yeah I agree with that, specifying upon CFT creation will provide transparency on what could happen and not result in surprises after the fact. Thanks for taking an iteration to add clawback as an option here 🙏

[shawnxie999]

I think it might be a good idea to add clawback as an extension of the freeze flag of each CFT, so the fund can only be clawback if the CFTokenIssuance object is not frozen. By doing this, we can use the same flaglsfCannotFreezeBalances to disclaim clawback, since both freeze and clawback serve regulatory compliance.

[sappenin]

I think it might be a good idea to add clawback as an extension of the freeze flag of each CFT...

@shawnxie999 - I agree. Once XLS-39d solidifies this, I can update this spec since it will likely make sense to replicate the same relationship between freeze and clawback.

[shawnxie999]

Implementation wise, if we are going to incorporating CFT into Payment transaction. Then I think we also need to introduce a new field in Payment called CFT_Amount to encompass the CFTIssuanceID and the Value. We can't reuse the Amount field because it is strictly for STAmount objects.

[sappenin]

Introducing something new (like CFTAmount) is one option, with some nice upsides (e.g., we could guarantee that CFT doesn't break anything in existing logic that handles XRPAmount or IOUAmount). But if we decided we wanted to re-use STAmount, I wrote up an idea around this a few days ago that I think could work -- but very open to hearing problems or concerns (I wrote it kind of quickly):

https://gist.github.com/sappenin/2c923bb249d4e9dd153e2e5f32f96d92

[shawnxie999]

thanks for the write-up!

[shawnxie999]

have we thought about disabling freeze by default? so instead of lsfCannotFreezeBalances, we could have lsfAllowFreezeBalances, which could be set if and only if OutstandingAmount = 0.

David S. said that there were lots of criticisms around how freeze is enabled by default for IOUs.

I don't have an opinion, just a thought.

[sappenin]

I think this makes sense, and seems like a reasonable default. Let me try to revise the spec to make sure we're not missing anything, and I'll post back here once I've seen what this impacts (if anything).

One thing that comes to mind immediately though is the interplay between this change and "Global Freeze" (and then possibly clawback). At the moment, the spec defines global freeze independent of individual freeze.

[sappenin]

Hello group: per the new XLS Contributing process, it is my opinion that we have reach a "well-refined standard."

As such, I propose that we move this discussion to a file (via this PR) and work on final changes using additional PRs, for better change-tracking. For example -- there are some Clawback changes that either I or @ledhed2222 will propose to the spec once it's in file-form (so we can better track proposals and changes).

Please comment here if you would like to object to moving this spec/discussion forward in the process into a DRAFT spec.

(Note that per the Contributing guidelines, moving a spec into the DRAFT state does not mean any kind of endorsement, nor does it mean that this specification will become adopted. It is solely meant as a mechanism to enable better change tracking using PRs.)

[intelliot]

As noted by @sappenin , this has been moved here: XLS-33d: Compact Fungible Tokens (CFTs).

Closing this discussion in order to focus future comments on that PR.