diff --git a/src/pages/guide/issuance/create-a-stablecoin.mdx b/src/pages/guide/issuance/create-a-stablecoin.mdx index adc9a71b..5cf500f8 100644 --- a/src/pages/guide/issuance/create-a-stablecoin.mdx +++ b/src/pages/guide/issuance/create-a-stablecoin.mdx @@ -150,8 +150,14 @@ Now that we have some input fields, we need to add some logic to handle the subm After this step, your users will be able to create a stablecoin by clicking the "Create" button! -:::warning -We **strongly** recommend that for stablecoins, the `currency` field be set to the [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) three-letter code for the underlying fiat currency (e.g., `"USD"`, `"EUR"`, `"GBP"`) — **not** the token symbol. This value is **immutable** after token creation and affects fee payment eligibility, DEX routing, and quote token pairing. **Only `USD` stablecoins can be used to pay transaction fees on Tempo** — if your stablecoin is USD-denominated, the currency must be set to `"USD"` to be eligible for fee payment. +:::danger[Critical — `currency` field is immutable] +The `currency` value **cannot be changed** after token creation. A wrong value requires redeploying the token. + +- **Vanilla 1:1 fiat stablecoins** (USDC, USDT, PYUSD, EURC): use the [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) fiat code → `"USD"`, `"EUR"`, etc. **Only `USD` tokens can pay transaction fees on Tempo.** +- **Yield-bearing stablecoins & tokenized assets** (sUSDe, BUIDL, USDs): use the **token's own ticker** → `"sUSDe"`, `"BUIDL"`, `"USDs"`. Do **not** use `"USD"`. +- **Crypto-native assets** (cbBTC, WETH): use the **token's own ticker** → `"cbBTC"`, `"WETH"`. Do **not** use `"USD"`. + +See the full [currency field reference](/protocol/tip20/overview#currency-declaration) for detailed examples. ::: diff --git a/src/pages/protocol/tip20/overview.mdx b/src/pages/protocol/tip20/overview.mdx index 769235b0..8b6ba913 100644 --- a/src/pages/protocol/tip20/overview.mdx +++ b/src/pages/protocol/tip20/overview.mdx @@ -153,8 +153,28 @@ The `currency` field represents the **denomination**, not the token itself — m | PYUSD | `"USD"` | `"PYUSD"` | | EURC | `"EUR"` | `"EURC"` | +:::danger[Common Mistake — Non-Vanilla Stablecoins and Crypto-Native Assets] +The `currency` field identifies the **fiat denomination** of the token for vanilla stablecoins. For yield-bearing or crypto-native assets, use the **token's own ticker** as the currency. This is the most common deployment error — **5+ issuers have had to redeploy their tokens** due to incorrect `currency` values. + +**Yield-bearing stablecoins and tokenized assets** (e.g., sUSDe, BUIDL, USDs) should set `currency` to their **own ticker** — not `"USD"`. These tokens are not vanilla stablecoins and should not be treated as interchangeable with USD in DEX routing. + +**Crypto-native assets** (e.g., cbBTC, WETH, stETH) should also set `currency` to their **own ticker**. Do **not** set `currency` to `"USD"` for a non-USD-pegged asset. + +| Token | Type | Correct `currency` | Incorrect `currency` | Why | +|---------|-------------------------|---------------------|----------------------|--------------------------------------------------------| +| USDC | Vanilla USD stablecoin | `"USD"` | `"USDC"` | 1:1 USD peg — use ISO 4217 fiat code | +| EURC | Vanilla EUR stablecoin | `"EUR"` | `"EURC"` | 1:1 EUR peg — use ISO 4217 fiat code | +| sUSDe | Yield-bearing USD | `"sUSDe"` | `"USD"` | Yield-bearing — not a vanilla stablecoin | +| BUIDL | Tokenized T-bills | `"BUIDL"` | `"USD"` | Tokenized treasury product, not a vanilla stablecoin | +| USDs | USD savings token | `"USDs"` | `"USD"` | Yield-bearing savings product | +| cbBTC | Wrapped Bitcoin | `"cbBTC"` | `"USD"` or `"BTC"` | Crypto-native asset — use token ticker | +| WETH | Wrapped Ether | `"WETH"` | `"USD"` or `"ETH"` | Crypto-native asset — use token ticker | + +**Rule of thumb:** only vanilla 1:1 fiat-pegged stablecoins use ISO 4217 codes (e.g., `"USD"`, `"EUR"`). Everything else — yield-bearing, tokenized assets, crypto-native — uses its **own ticker** as the `currency`. +::: + :::warning -The currency code is **immutable** — it cannot be changed after token creation. An incorrect currency code will affect fee payment eligibility, DEX routing, and quote token pairing. +The currency code is **immutable** — it cannot be changed after token creation. An incorrect currency code will affect fee payment eligibility, DEX routing, and quote token pairing. **A wrong value requires redeploying the token.** ::: ### DEX Quote Tokens diff --git a/src/pages/protocol/tip20/spec.mdx b/src/pages/protocol/tip20/spec.mdx index 327724e4..9906d1e2 100644 --- a/src/pages/protocol/tip20/spec.mdx +++ b/src/pages/protocol/tip20/spec.mdx @@ -455,6 +455,15 @@ Virtual addresses are valid TIP-20 recipients on those paths but remain forwardi ## Currencies and Quote Tokens Each TIP-20 token declares a currency identifier and a corresponding `quoteToken` used for pricing and routing in the Stablecoin DEX. Stablecoin currency identifiers should be [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) three-letter codes representing the underlying fiat currency (e.g., `"USD"`, `"EUR"`, `"GBP"`) — not the token's own symbol. The currency is set at token creation and **cannot be changed afterward**. **Only tokens with `currency == "USD"` are eligible for paying transaction fees.** Tokens with `currency == "USD"` must pair with a USD-denominated TIP-20 token. +:::danger[Setting `currency` for non-vanilla stablecoins and crypto-native assets] +Only vanilla 1:1 fiat-pegged stablecoins should use ISO 4217 codes (`"USD"`, `"EUR"`, etc.). All other token types must use their **own ticker** as the `currency`. + +- **Yield-bearing stablecoins & tokenized assets** (sUSDe, BUIDL, USDs, etc.): set `currency` to the token's ticker (e.g., `"sUSDe"`, `"BUIDL"`). Do **not** use `"USD"` — these are not vanilla stablecoins. +- **Crypto-native assets** (cbBTC, WETH, stETH, etc.): set `currency` to the token's ticker (e.g., `"cbBTC"`, `"WETH"`). Do **not** use `"USD"`. + +The currency is **immutable**. An incorrect value requires redeploying the token. See the [currency field reference](/protocol/tip20/overview#currency-declaration) for a full examples table. +::: + Updating the quote token occurs in two phases: 1. `setNextQuoteToken` stages a new quote token. 2. `completeQuoteTokenUpdate` finalizes the change.