From 49107094acb8a0b8807bc96295340bca0dcccf86 Mon Sep 17 00:00:00 2001 From: Georgios Konstantopoulos Date: Mon, 9 Feb 2026 16:11:56 +0000 Subject: [PATCH 1/6] docs: add ISO 4217 currency code guidance for TIP-20 issuers - overview: add ISO 4217 reference, common codes table, do/don't table, immutability warning - spec: clarify currency identifiers are ISO 4217 codes, note immutability - issuance guide: add warning callout before createToken code example Amp-Thread-ID: https://ampcode.com/threads/T-019c4322-fc93-713a-bd40-93b07bb39a92 Co-authored-by: Amp --- .../guide/issuance/create-a-stablecoin.mdx | 4 +++ src/pages/protocol/tip20/overview.mdx | 25 +++++++++++++++++++ src/pages/protocol/tip20/spec.mdx | 4 +-- 3 files changed, 31 insertions(+), 2 deletions(-) diff --git a/src/pages/guide/issuance/create-a-stablecoin.mdx b/src/pages/guide/issuance/create-a-stablecoin.mdx index a595e319..081fca4c 100644 --- a/src/pages/guide/issuance/create-a-stablecoin.mdx +++ b/src/pages/guide/issuance/create-a-stablecoin.mdx @@ -151,6 +151,10 @@ 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 +The `currency` field must be an [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. +::: + diff --git a/src/pages/protocol/tip20/overview.mdx b/src/pages/protocol/tip20/overview.mdx index b3d25a9f..0d3727c3 100644 --- a/src/pages/protocol/tip20/overview.mdx +++ b/src/pages/protocol/tip20/overview.mdx @@ -132,6 +132,31 @@ TIP-20 supports an opt-in [reward distribution system](/protocol/tip20-rewards/o A TIP-20 token can declare a currency identifier (e.g., `"USD"`, `"EUR"`) that identifies the real-world asset backing the token. This enables proper routing and pricing in Tempo's [Stablecoin DEX](/protocol/exchange). USD-denominated TIP-20 tokens can be used to pay transaction fees and serve as quote tokens in the DEX. +Currency identifiers should be [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) three-letter currency codes. Common examples include: + +| Code | Currency | +|-------|------------------------| +| `USD` | United States Dollar | +| `EUR` | Euro | +| `GBP` | British Pound Sterling | +| `JPY` | Japanese Yen | +| `SGD` | Singapore Dollar | +| `BRL` | Brazilian Real | +| `AED` | UAE Dirham | + +The `currency` field represents the **denomination**, not the token itself — multiple tokens can share the same currency code: + +| Token | Correct `currency` | Incorrect `currency` | +|---------------|---------------------|----------------------| +| USDC | `"USD"` ✅ | `"USDC"` ❌ | +| USDT | `"USD"` ✅ | `"USDT"` ❌ | +| PYUSD | `"USD"` ✅ | `"PYUSD"` ❌ | +| EURC | `"EUR"` ✅ | `"EURC"` ❌ | + +:::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. +::: + ### DEX Quote Tokens TIP-20 tokens can serve as quote tokens in Tempo's decentralized exchange (DEX). When creating trading pairs on the [Stablecoin DEX](/protocol/exchange), TIP-20 tokens function as the quote currency against which other tokens are priced and traded. diff --git a/src/pages/protocol/tip20/spec.mdx b/src/pages/protocol/tip20/spec.mdx index c81ddb9d..0a58339c 100644 --- a/src/pages/protocol/tip20/spec.mdx +++ b/src/pages/protocol/tip20/spec.mdx @@ -411,7 +411,7 @@ TIP-20 tokens cannot be sent to other TIP-20 token contract addresses. The imple Any attempt to transfer to a TIP-20 token address must revert with `InvalidRecipient`. This prevents accidental token loss by sending funds to token contracts instead of user accounts. ## 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. Tokens with `currency == "USD"` must pair with a USD-denominated TIP-20 token. +Each TIP-20 token declares a currency identifier and a corresponding `quoteToken` used for pricing and routing in the Stablecoin DEX. 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**. Tokens with `currency == "USD"` must pair with a USD-denominated TIP-20 token. Updating the quote token occurs in two phases: 1. `setNextQuoteToken` stages a new quote token. @@ -470,7 +470,7 @@ interface ITIP20Factory { /// @notice Creates and deploys a new TIP-20 token /// @param name The token's ERC-20 name /// @param symbol The token's ERC-20 symbol - /// @param currency The token's currency identifier (e.g. "USD") + /// @param currency The token's ISO 4217 currency code (e.g. "USD", "EUR"). Immutable after creation. /// @param quoteToken The TIP-20 quote token used for exchange pricing /// @param admin The address to receive DEFAULT_ADMIN_ROLE on the new token /// @param salt A unique salt for deterministic address derivation From 9799b134573dfbe19bce4aa320264dcc57a7a610 Mon Sep 17 00:00:00 2001 From: malleshpai Date: Mon, 9 Feb 2026 11:25:32 -0500 Subject: [PATCH 2/6] minor edit --- src/pages/guide/issuance/create-a-stablecoin.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/pages/guide/issuance/create-a-stablecoin.mdx b/src/pages/guide/issuance/create-a-stablecoin.mdx index 081fca4c..ec40848c 100644 --- a/src/pages/guide/issuance/create-a-stablecoin.mdx +++ b/src/pages/guide/issuance/create-a-stablecoin.mdx @@ -152,7 +152,7 @@ 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 -The `currency` field must be an [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. +We **strongly** recommend that the `currency` field be 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. ::: From 2851a0689d933436aa1d2651c4718d2679b38cb5 Mon Sep 17 00:00:00 2001 From: malleshpai Date: Mon, 9 Feb 2026 12:04:59 -0500 Subject: [PATCH 3/6] Clarify recommendation for currency field in stablecoin guide --- src/pages/guide/issuance/create-a-stablecoin.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/pages/guide/issuance/create-a-stablecoin.mdx b/src/pages/guide/issuance/create-a-stablecoin.mdx index ec40848c..48e90fa8 100644 --- a/src/pages/guide/issuance/create-a-stablecoin.mdx +++ b/src/pages/guide/issuance/create-a-stablecoin.mdx @@ -152,7 +152,7 @@ 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 the `currency` field be 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. +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. ::: From 97cea5c92e26f8db6519b0ac8301c69fcc27547b Mon Sep 17 00:00:00 2001 From: malleshpai Date: Mon, 9 Feb 2026 12:06:32 -0500 Subject: [PATCH 4/6] Clarify currency identifier usage in TIP-20 tokens --- src/pages/protocol/tip20/overview.mdx | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/src/pages/protocol/tip20/overview.mdx b/src/pages/protocol/tip20/overview.mdx index 0d3727c3..f5e1e874 100644 --- a/src/pages/protocol/tip20/overview.mdx +++ b/src/pages/protocol/tip20/overview.mdx @@ -132,7 +132,7 @@ TIP-20 supports an opt-in [reward distribution system](/protocol/tip20-rewards/o A TIP-20 token can declare a currency identifier (e.g., `"USD"`, `"EUR"`) that identifies the real-world asset backing the token. This enables proper routing and pricing in Tempo's [Stablecoin DEX](/protocol/exchange). USD-denominated TIP-20 tokens can be used to pay transaction fees and serve as quote tokens in the DEX. -Currency identifiers should be [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) three-letter currency codes. Common examples include: +Stablecoin currency identifiers should be [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) three-letter currency codes. Common examples include: | Code | Currency | |-------|------------------------| @@ -148,10 +148,10 @@ The `currency` field represents the **denomination**, not the token itself — m | Token | Correct `currency` | Incorrect `currency` | |---------------|---------------------|----------------------| -| USDC | `"USD"` ✅ | `"USDC"` ❌ | -| USDT | `"USD"` ✅ | `"USDT"` ❌ | -| PYUSD | `"USD"` ✅ | `"PYUSD"` ❌ | -| EURC | `"EUR"` ✅ | `"EURC"` ❌ | +| USDC | `"USD"` | `"USDC"` | +| USDT | `"USD"` | `"USDT"` | +| PYUSD | `"USD"` | `"PYUSD"` | +| EURC | `"EUR"` | `"EURC"` | :::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. From d467a3b1662cd4c19db99002f34c033b28f4ed1e Mon Sep 17 00:00:00 2001 From: malleshpai Date: Mon, 9 Feb 2026 12:07:43 -0500 Subject: [PATCH 5/6] Clarify currency identifiers for TIP-20 tokens --- src/pages/protocol/tip20/spec.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/pages/protocol/tip20/spec.mdx b/src/pages/protocol/tip20/spec.mdx index 0a58339c..cef2bd88 100644 --- a/src/pages/protocol/tip20/spec.mdx +++ b/src/pages/protocol/tip20/spec.mdx @@ -411,7 +411,7 @@ TIP-20 tokens cannot be sent to other TIP-20 token contract addresses. The imple Any attempt to transfer to a TIP-20 token address must revert with `InvalidRecipient`. This prevents accidental token loss by sending funds to token contracts instead of user accounts. ## 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. 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**. Tokens with `currency == "USD"` must pair with a USD-denominated TIP-20 token. +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**. Tokens with `currency == "USD"` must pair with a USD-denominated TIP-20 token. Updating the quote token occurs in two phases: 1. `setNextQuoteToken` stages a new quote token. From 9c5123482c4eef45e665384abcb7b8b7318057a9 Mon Sep 17 00:00:00 2001 From: Georgios Konstantopoulos Date: Mon, 9 Feb 2026 18:01:18 +0000 Subject: [PATCH 6/6] docs: explicitly state that only USD stablecoins can pay fees Amp-Thread-ID: https://ampcode.com/threads/T-019c4390-0ad5-75ce-8c97-0cfa95a8dfef Co-authored-by: Amp --- src/pages/guide/issuance/create-a-stablecoin.mdx | 2 +- src/pages/protocol/tip20/overview.mdx | 2 +- src/pages/protocol/tip20/spec.mdx | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/src/pages/guide/issuance/create-a-stablecoin.mdx b/src/pages/guide/issuance/create-a-stablecoin.mdx index 48e90fa8..c3f2c7fa 100644 --- a/src/pages/guide/issuance/create-a-stablecoin.mdx +++ b/src/pages/guide/issuance/create-a-stablecoin.mdx @@ -152,7 +152,7 @@ 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. +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. ::: diff --git a/src/pages/protocol/tip20/overview.mdx b/src/pages/protocol/tip20/overview.mdx index f5e1e874..247bd663 100644 --- a/src/pages/protocol/tip20/overview.mdx +++ b/src/pages/protocol/tip20/overview.mdx @@ -130,7 +130,7 @@ TIP-20 supports an opt-in [reward distribution system](/protocol/tip20-rewards/o ### Currency Declaration -A TIP-20 token can declare a currency identifier (e.g., `"USD"`, `"EUR"`) that identifies the real-world asset backing the token. This enables proper routing and pricing in Tempo's [Stablecoin DEX](/protocol/exchange). USD-denominated TIP-20 tokens can be used to pay transaction fees and serve as quote tokens in the DEX. +A TIP-20 token can declare a currency identifier (e.g., `"USD"`, `"EUR"`) that identifies the real-world asset backing the token. This enables proper routing and pricing in Tempo's [Stablecoin DEX](/protocol/exchange). **Only `USD`-denominated stablecoins can be used to pay transaction fees on Tempo.** USD-denominated TIP-20 tokens also serve as quote tokens in the DEX. Stablecoin currency identifiers should be [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) three-letter currency codes. Common examples include: diff --git a/src/pages/protocol/tip20/spec.mdx b/src/pages/protocol/tip20/spec.mdx index cef2bd88..026414e1 100644 --- a/src/pages/protocol/tip20/spec.mdx +++ b/src/pages/protocol/tip20/spec.mdx @@ -411,7 +411,7 @@ TIP-20 tokens cannot be sent to other TIP-20 token contract addresses. The imple Any attempt to transfer to a TIP-20 token address must revert with `InvalidRecipient`. This prevents accidental token loss by sending funds to token contracts instead of user accounts. ## 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**. Tokens with `currency == "USD"` must pair with a USD-denominated TIP-20 token. +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. Updating the quote token occurs in two phases: 1. `setNextQuoteToken` stages a new quote token.