Fungible Token Fixed Supply

[shawnxie999]

Fungible Token Fixed Supply

Requirements:

Ensure that an issuer can only issue a fixed number of tokens by implementing a fixed supply policy.

1. Prevent any further issuance beyond that limit.
2. Specify the maximum number of tokens that can be issued
3. A way to signal a fixed supply of tokens

Goal:

Create trust and predictability in the cryptocurrency market, as users can be assured that the supply of their chosen currency is fixed and the value of their holdings will not be diluted by unexpected inflation.

Problem statements:

Account needs to be blackholed to ensure a fixed supply

1. Disrupts continued management of token operations:
   1. Updating the issuing address's domain/contact information
   2. Adjusting other issuer settings like tick size or managing freezes, or just correcting any settings that weren't "just right" before blackholing
   3. Authorizing trust lines (as it stands, you can't use the "[only] Authorized Trust Lines" feature with a fixed-supply token)
   4. Using the issuing account for anything else (e.g., issuing a different token from the same address)
2. Unable to issue previously burnt tokens
   5. Fees burnt today
   6. Re-issue tokens that were "burned" by being sent (returned) directly to the issuer
3. Public trust: the issuer may or may not blackhole the account sufficiently for the community to follow accurately.
   7. The current mechanism is to use a recommended address that is publically recognized
4. Custody requirements: In some jurisdictions, cryptocurrency exchanges and other financial institutions holding customer assets must adhere to specific custody requirements. These requirements may include protecting customer assets from theft, loss, or unauthorized access. So in some situations, blackholing might not be considered enough, and other measures to ensure a fixed supply might be required.

Workflow Example

If a fixed supply limit has been set for a token, then the issuer cannot issue more than the specified limit. There are two main transactions that involve tokens: Payment and OfferCreate.

Here is a sample workflow of how supply limit interact with these transactions:

1. Bob sets up a TrustLine to Alice for USD token
2. Alice issues 100 USD to Bob through a Payment transaction
3. Alice wants to set a fixed supply limit of 50 USD
   • She fails to do so because she has already issued 100 USD
4. Alice re-try to set a fixed supply limit of 200 USD, and is successful
5. Alice submits an OfferCreate transaction of params:
   • TakerGets is 150 USD and TakerPays is 100 XRP
   • Transaction FAILS! Even though the Offer has not been consumed immediately, but we know if Alice sets her offering to 150 USD, then there is a possibility that in the future, her total amount of issued USD will reach 250 (considering she has already issued 100 USD to Bob), which goes over the supply limit (200 USD)
6. Alice retries to submit an OfferCreate transaction of params:
   • TakerGets is 80 USD and TakerPays is 100 XRP
   • Transaction is SUCCESSFUL. When this Offer becomes fully consumed in the future, the total amount of USD Alice issues will total up to 180, which is less than the limit (200 USD)

Hence, whenever a token is issued through new OfferCreate or Payment transactions, the resulting balance(or potential balance in the case of Offers) of the token needs to be compared with the fixed supply limit.

Design/Implementation

To find the current balance of a token, we must iterate through the owner directory of the account to find the total amount of an issued currency. Below is a pseudo code to find the total amount of USD that an account has issued:

`Total` = 0

For each object in owner directory:
    If it is a `RippleState/TrustLine` object has USD currency:
	   `Total` = `Total` + balance of USD in this trustline
    If it is an `Offer` object with USD currency for TakerGets:
    	   `Total` = `Total` + balance of TakerGets
    (Notes: although TakerGets has not been paid out yet, but the offer will eventually be consumed, hence we need to factor in the potential increase in the number of the token when computing its total)

When the issuer creates a new Payment transaction with USD, we must make sure

Total + USD balance in the Payment tx  <=  fixed supply limit

When the issuer creates a new OfferCreate transaction with USD as the currency for TakerGets, we must make sure

Total + USD balance in TakerGets  <=  fixed supply limit

Approaches

Approach 1: New FungibleToken ledger object

Since there isn’t anywhere on the ledger that keeps track of a fungible token in one place, we will introduce a new object type called FungibleToken to keep track of the information for a token. It would have a schema similar to the following:

{
	"Currency": "USD",`
	"Issuer": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
	"FixedSupplyLimit": 1000,
	"TotalTokenAmount": 500
}

With this approach, each fungible token has its own object on the ledger and does not need to populate other objects. It will be easier and cleaner to fetch the information for a token as it will now be stored in one single place. Each new object would require an additional reserve.

This object would only be created when the user sets a FixedSupplyLimit, this would likely need a new transaction as well.

Evaluation

Pros:

• Flexibility of setting a different fixed supply limit for each token
• One place one the ledger to keep track of the supply limit and the total amount of tokens.
• No need to bloat existing ledger objects, and no need to use AccountRoot object for bookkeeping
• Prevents spamming attacks since there is a reserve for each object, so the user can’t create an arbitrary number of supply limits in attempt to overwhelm the ledger
• No need to compute the total amount of token in each transaction, which can save a lot of time, since we store the total amount of token, TotalTokenAmount in the FungibleToken object.

This may be wrong, as we are creating a divergence in fungible token bookkeeping on the ledger, and we may still need to traverse the owner directory for correctness verification(eg. InvariantCheck) to make sure the numbers sum up to the same one? If this is the case, we will still have very expensive Payment and OfferCreate transactions.

Cons:

• High implementation complexity for a simple feature, as we are introducing a new type of object.
• New object requires more space, leading to a somewhat slower performance
• TotalTokenAmount may still need recomputation during a transaction, as there is a risk of incorrect data. Again, this requires iterating the owner directory to recompute the total, which is expensive. We need some level of confidence that the TotalTokenAmount is the right number and does not diverge from the actual sum. This is an implementation detail that is open to further discussion.
• No way to find out the total token amount because of limitation on STAmount, such that finite precision is not guarenteed.

Approach 2: New FungibleToken object with modifiers

The FungibleToken object

The FungibleToken object represents a single fungible token. The object is created by a TokenSet transaction. However, this object does not exist for each fungible token unless explicity set by a TokenSet.

Fields

An FungibleToken object can have the following required and optional fields.

---

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

Indicates the fungible token currency.

---

Field Name	Required?	JSON Type	Internal Type
Issuer	✔️	string	ACCOUNT ID

The issuer of the currency

---

Field Name	Required?	JSON Type	Internal Type
FixedSupplyLimit		object	AMOUNT

Indicates the total issued amount allowed.

---

Field Name	Required?	JSON Type	Internal Type
Receiver		string	ACCOUNT ID

The receiver of the token amount specified in FixedSupplyLimit .

---

Field Name	Required?	JSON Type	Internal Type
Locked		bool	bool

Indicates if the currency has locked. If true, no more tokens of this currency can be issued.

This is set to true after a sucessful TokenSet transaction with tfSetLimit flag

---

Field Name	Required?	JSON Type	Internal Type
Flags	✔️	number	UINT32

Flag Name	Flag Value	Description
tfSetLimit	0x00000001	If set, issuer of the currency has already been blackholed and no more token of this currency has be issued.

---

The TokenSet transaction

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

Indicates the new transaction type TokenSet. The recommended name is ttTOKENSET.

---

Field Name	Required?	JSON Type	Internal Type
Flags	✔️	number	UINT32

Specifies the flags for this transaction.

Flag Name	Flag Value	Description
tfSetLimit	0x00000001	If set, issue the specified token limit to the Receiver address and then blackhole this account. Also sets Locked to true

---

Field Name	Required?	JSON Type	Internal Type
Account	✔️	string	ACCOUNT ID

Indicates the account which is executing this transaction. The account MUST be the issuer of the asset.

---

Field Name	Required?	JSON Type	Internal Type
FixSupplyLimit		object	AMOUNT

Only valid if tfSetLimit flag is on. Indicates the amount specified for fixed supply limit.

If the token already exists, MUST leave this field out, because AMOUNT doesn't support finite precision, so unable to find out the total.

---

Field Name	Required?	JSON Type	Internal Type
Receiver		string	ACCOUNT ID

Only valid if tfSetLimit flag is on. Indicates the account which receives FixSupplyLimit amount of token.

If the token already exists, MUST leave this field out.

---

How to use TokenSet

Scenario 1: Limit a token that already exists

Set tfSetLimit to true(even though we don't set a limit, but we need this flag to indicate that we want to discontinue from issuing and blackhole the issuer). If the issuer has already issued the token, leave the Receiver and FixSupplyLimit parameters out for the TrustSet request. This is because we have no good way of finding out the precise total of the already issued token.

Scenario 2: Set limit for a new token

Set tfSetLimit to true. Set the FixSupplyLimit to the amount of token that you want to limit. Set the Receiver to the account that you want to receive the tokens. Receiver address will receive exactly what is specified in the FixSupplyLimit field.

A successful TokenSet

When the result of a TokenSet with tfSetLimit flag is successful, it will:

• the Issuer account will be blackholed, such that there is a limit to the total amount of token.
• will also disable the No Ripple flag for Issuer, if enabled.
• if it's a new token, Receiver address will receive the amount specified by FixSupplyLimit

Advantages

• No longer need to worry about STAmount precision as we are no longer dealing with total, we simply send to specified amount to another address, and issuer account immediately becomes blackholed right after
• New FungibleToken object could be utilized in the future for other features like Memo

Disadvantages

• Big feature, complexity could not be worth it, as the the feature is simply condensing existing XRP transactions into one. What the TokenSet does could be replicated by doing multiple transactions on the ledger already

Approach 3: Compact Fungible Token

Compact Fungible Token is discussed in proposal. It is a type of token that allows finite precision and set maximum limit on the total amount, which addresses exactly what the requirements tries to solve.

Advantages

• Finite precision, see more details in the proposal

Disadvantages

• Massive change required, as it introduces multiple new objects and transactions. The effort required would simply be too big for the scope of the fixed supply limit

[JoelKatz]

You can't iterate through the owner directory because that is potentially unbounded work for a transactor. You can't really keep the total because there is no guarantee the math will work out due to finite precision.

You can already accomplish this by creating an issuing account, allowing rippling by default, and extending trust to other accounts that totals the desired maximum issued amount (or just issuing the desired amount), and then blackholing the issuing account.

[shawnxie999]

Deleted unfeasible approaches.

See Approach 2 for the new method.

[sappenin]

I think you've seen it already @shawnxie999, but if we think we're going to introduce a new concept, we should consider the CFT proposal -- there's a lot of overlap between the two ideas, plus a variety of other benefits to a CFT in the general case.

Note that CFTs (at present) don't support rippling or some other features (see Advantages and Disadvantages and Assumption in that discussion) so CFTs might not satisfy all the requirements here (though for regulated issuances, I think they do).

All that said, I've thought CFTs would make most sense on a sidechain at first (maybe a CBDC sidechain) in order to prove out the idea.

But at any rate, the path of least resistance here (and easiest solution) is to simply make an issuer blackhole their account (as @JoelKatz suggests).