From c5f2e6d2e0b281ef99c80f499968ee242328622f Mon Sep 17 00:00:00 2001 From: Derek Cofausper <256792747+decofe@users.noreply.github.com> Date: Fri, 1 May 2026 13:52:09 +0000 Subject: [PATCH 1/2] docs: add currency field guidance for non-vanilla stables and crypto-native assets MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add prominent warnings across three docs pages explaining how to set the currency field for yield-bearing stablecoins (sUSDe, BUIDL, USDs) and crypto-native assets (cbBTC, WETH). This is the most common deployment mistake — 5+ issuers have had to redeploy tokens due to incorrect values. Changes: - protocol/tip20/overview.mdx: new danger callout with examples table - protocol/tip20/spec.mdx: danger callout in Currencies and Quote Tokens - guide/issuance/create-a-stablecoin.mdx: upgraded warning to danger with explicit yield-bearing and crypto-native examples Amp-Thread-ID: https://ampcode.com/threads/T-019de3a3-77f7-7532-9e5a-da789d870d1c Co-authored-by: Amp --- .../guide/issuance/create-a-stablecoin.mdx | 14 +++++++++++-- src/pages/protocol/tip20/overview.mdx | 20 ++++++++++++++++++- src/pages/protocol/tip20/spec.mdx | 10 ++++++++++ 3 files changed, 41 insertions(+), 3 deletions(-) diff --git a/src/pages/guide/issuance/create-a-stablecoin.mdx b/src/pages/guide/issuance/create-a-stablecoin.mdx index adc9a71b..55cb0196 100644 --- a/src/pages/guide/issuance/create-a-stablecoin.mdx +++ b/src/pages/guide/issuance/create-a-stablecoin.mdx @@ -150,8 +150,18 @@ 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` field must be the [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) three-letter code for the token's **fiat denomination** (e.g., `"USD"`, `"EUR"`, `"GBP"`) — **not** the token symbol. This value **cannot be changed** after creation. A wrong value requires redeploying the token. + +**Only `USD` tokens can pay transaction fees on Tempo** — if your token is USD-denominated, `currency` must be `"USD"`. + +This applies to **all** USD-denominated tokens, including yield-bearing stablecoins and tokenized assets: +- sUSDe, BUIDL, USDs → `currency: "USD"` (not `"sUSDe"`, `"BUIDL"`, etc.) +- USDC, USDT, PYUSD → `currency: "USD"` (not the token symbol) + +For crypto-native assets like cbBTC or WETH, use the base asset code (e.g., `"BTC"`, `"ETH"`) — **not** `"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..6a3ec6fa 100644 --- a/src/pages/protocol/tip20/overview.mdx +++ b/src/pages/protocol/tip20/overview.mdx @@ -153,8 +153,26 @@ 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, not the token itself or its underlying collateral. This is the most common deployment error — **5+ issuers have had to redeploy their tokens** due to incorrect `currency` values. + +**Yield-bearing stablecoins** (e.g., sUSDe, BUIDL, USDs) that are denominated in USD must still set `currency` to `"USD"` — not to their token symbol. The yield mechanism does not change the denomination. + +**Crypto-native assets** (e.g., cbBTC, WETH, stETH) that are **not** pegged to a fiat currency should use a **non-ISO-4217 identifier** that describes the asset class (e.g., `"BTC"`, `"ETH"`). Do **not** set `currency` to `"USD"` for a non-USD-denominated asset — doing so will cause incorrect DEX routing and pricing. + +| Token | Backing / Peg | Correct `currency` | Incorrect `currency` | Why | +|---------|-------------------------|---------------------|----------------------|--------------------------------------------------------| +| sUSDe | Yield-bearing USD | `"USD"` | `"sUSDe"` | Denominated in USD despite yield mechanics | +| BUIDL | Tokenized T-bills (USD) | `"USD"` | `"BUIDL"` | Represents USD-denominated short-duration treasuries | +| USDs | USD savings token | `"USD"` | `"USDs"` | USD-denominated savings product | +| cbBTC | Wrapped Bitcoin | `"BTC"` | `"USD"` or `"cbBTC"` | Not a USD stablecoin — BTC-denominated | +| WETH | Wrapped Ether | `"ETH"` | `"USD"` or `"WETH"` | Not a USD stablecoin — ETH-denominated | + +**Rule of thumb:** ask "what fiat (or base crypto) currency is 1 unit of this token worth?" — that answer is your `currency` value. +::: + :::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..ec808255 100644 --- a/src/pages/protocol/tip20/spec.mdx +++ b/src/pages/protocol/tip20/spec.mdx @@ -455,6 +455,16 @@ 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] +The `currency` field represents the **denomination** of the token — the fiat or base currency that one unit of the token is worth — not the token's name, symbol, or collateral type. + +- **Yield-bearing USD tokens** (sUSDe, BUIDL, USDs, etc.): set `currency` to `"USD"`. The yield mechanism does not change the denomination. +- **Crypto-native assets** (cbBTC, WETH, stETH, etc.): use a non-ISO-4217 identifier for the base asset (e.g., `"BTC"`, `"ETH"`). Do **not** use `"USD"` — these tokens are not USD-denominated. +- **Never** use the token symbol (e.g., `"sUSDe"`, `"cbBTC"`) as the currency — it will not match any DEX routing rules and will prevent fee payment eligibility. + +The currency is **immutable**. An incorrect value requires redeploying the token. +::: + Updating the quote token occurs in two phases: 1. `setNextQuoteToken` stages a new quote token. 2. `completeQuoteTokenUpdate` finalizes the change. From 8cf303b0cf2404a8ccccce6632af81400d4cc092 Mon Sep 17 00:00:00 2001 From: Derek Cofausper <256792747+decofe@users.noreply.github.com> Date: Fri, 1 May 2026 15:10:39 +0000 Subject: [PATCH 2/2] fix: yield-bearing and crypto-native assets should use their own ticker as currency MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Per feedback — sUSDe, BUIDL, USDs, cbBTC, WETH etc. should all use their own ticker as the currency field, not ISO 4217 codes. Only vanilla 1:1 fiat-pegged stablecoins use ISO codes. Amp-Thread-ID: https://ampcode.com/threads/T-019de3a3-77f7-7532-9e5a-da789d870d1c Co-authored-by: Amp --- .../guide/issuance/create-a-stablecoin.mdx | 12 ++++------ src/pages/protocol/tip20/overview.mdx | 24 ++++++++++--------- src/pages/protocol/tip20/spec.mdx | 9 ++++--- 3 files changed, 21 insertions(+), 24 deletions(-) diff --git a/src/pages/guide/issuance/create-a-stablecoin.mdx b/src/pages/guide/issuance/create-a-stablecoin.mdx index 55cb0196..5cf500f8 100644 --- a/src/pages/guide/issuance/create-a-stablecoin.mdx +++ b/src/pages/guide/issuance/create-a-stablecoin.mdx @@ -151,15 +151,11 @@ 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! :::danger[Critical — `currency` field is immutable] -The `currency` field must be the [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) three-letter code for the token's **fiat denomination** (e.g., `"USD"`, `"EUR"`, `"GBP"`) — **not** the token symbol. This value **cannot be changed** after creation. A wrong value requires redeploying the token. +The `currency` value **cannot be changed** after token creation. A wrong value requires redeploying the token. -**Only `USD` tokens can pay transaction fees on Tempo** — if your token is USD-denominated, `currency` must be `"USD"`. - -This applies to **all** USD-denominated tokens, including yield-bearing stablecoins and tokenized assets: -- sUSDe, BUIDL, USDs → `currency: "USD"` (not `"sUSDe"`, `"BUIDL"`, etc.) -- USDC, USDT, PYUSD → `currency: "USD"` (not the token symbol) - -For crypto-native assets like cbBTC or WETH, use the base asset code (e.g., `"BTC"`, `"ETH"`) — **not** `"USD"`. +- **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 6a3ec6fa..8b6ba913 100644 --- a/src/pages/protocol/tip20/overview.mdx +++ b/src/pages/protocol/tip20/overview.mdx @@ -154,21 +154,23 @@ The `currency` field represents the **denomination**, not the token itself — m | EURC | `"EUR"` | `"EURC"` | :::danger[Common Mistake — Non-Vanilla Stablecoins and Crypto-Native Assets] -The `currency` field identifies the **fiat denomination** of the token, not the token itself or its underlying collateral. This is the most common deployment error — **5+ issuers have had to redeploy their tokens** due to incorrect `currency` values. +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** (e.g., sUSDe, BUIDL, USDs) that are denominated in USD must still set `currency` to `"USD"` — not to their token symbol. The yield mechanism does not change the denomination. +**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) that are **not** pegged to a fiat currency should use a **non-ISO-4217 identifier** that describes the asset class (e.g., `"BTC"`, `"ETH"`). Do **not** set `currency` to `"USD"` for a non-USD-denominated asset — doing so will cause incorrect DEX routing and pricing. +**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 | Backing / Peg | Correct `currency` | Incorrect `currency` | Why | +| Token | Type | Correct `currency` | Incorrect `currency` | Why | |---------|-------------------------|---------------------|----------------------|--------------------------------------------------------| -| sUSDe | Yield-bearing USD | `"USD"` | `"sUSDe"` | Denominated in USD despite yield mechanics | -| BUIDL | Tokenized T-bills (USD) | `"USD"` | `"BUIDL"` | Represents USD-denominated short-duration treasuries | -| USDs | USD savings token | `"USD"` | `"USDs"` | USD-denominated savings product | -| cbBTC | Wrapped Bitcoin | `"BTC"` | `"USD"` or `"cbBTC"` | Not a USD stablecoin — BTC-denominated | -| WETH | Wrapped Ether | `"ETH"` | `"USD"` or `"WETH"` | Not a USD stablecoin — ETH-denominated | - -**Rule of thumb:** ask "what fiat (or base crypto) currency is 1 unit of this token worth?" — that answer is your `currency` value. +| 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 diff --git a/src/pages/protocol/tip20/spec.mdx b/src/pages/protocol/tip20/spec.mdx index ec808255..9906d1e2 100644 --- a/src/pages/protocol/tip20/spec.mdx +++ b/src/pages/protocol/tip20/spec.mdx @@ -456,13 +456,12 @@ Virtual addresses are valid TIP-20 recipients on those paths but remain forwardi 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] -The `currency` field represents the **denomination** of the token — the fiat or base currency that one unit of the token is worth — not the token's name, symbol, or collateral type. +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 USD tokens** (sUSDe, BUIDL, USDs, etc.): set `currency` to `"USD"`. The yield mechanism does not change the denomination. -- **Crypto-native assets** (cbBTC, WETH, stETH, etc.): use a non-ISO-4217 identifier for the base asset (e.g., `"BTC"`, `"ETH"`). Do **not** use `"USD"` — these tokens are not USD-denominated. -- **Never** use the token symbol (e.g., `"sUSDe"`, `"cbBTC"`) as the currency — it will not match any DEX routing rules and will prevent fee payment eligibility. +- **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. +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: