docs: add currency field guidance for non-vanilla stablecoins and crypto-native assets

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.
 :::
 
 <Demo.Container name="Create Form">

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

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.