From b5d9a1186e7f49bfb366bd1c0cd5860bd4f9935a Mon Sep 17 00:00:00 2001 From: malleshpai <5857042+malleshpai@users.noreply.github.com> Date: Thu, 20 Aug 2026 17:56:54 +0000 Subject: [PATCH 1/3] docs: document non-gas-eligible currency codes Co-authored-by: Derek Cofausper <256792747+decofe@users.noreply.github.com> --- src/pages/docs/guide/issuance/create-a-stablecoin.mdx | 2 +- src/pages/docs/protocol/fees/spec-fee.mdx | 2 ++ src/pages/docs/protocol/tip20/overview.mdx | 10 ++++++---- src/pages/docs/protocol/tip20/spec.mdx | 2 +- 4 files changed, 10 insertions(+), 6 deletions(-) diff --git a/src/pages/docs/guide/issuance/create-a-stablecoin.mdx b/src/pages/docs/guide/issuance/create-a-stablecoin.mdx index d13fd7ce..1c650b4e 100644 --- a/src/pages/docs/guide/issuance/create-a-stablecoin.mdx +++ b/src/pages/docs/guide/issuance/create-a-stablecoin.mdx @@ -156,7 +156,7 @@ After this step, your users will be able to create a stablecoin by clicking the Tokens can also carry an optional on-chain [`logoURI`](/docs/protocol/tip20/spec#logo-uri) that wallets and explorers read directly from the token contract. It's set on the token contract and is independent of this creation flow; for the recommended format, use a square, rasterized PNG or WebP (max 256 bytes; `https`, `http`, `ipfs`, or `data` scheme). :::warning -The `currency` field is **immutable** after token creation and affects fee payment eligibility, DEX routing, and quote token pairing. See [Currency Declaration](/docs/protocol/tip20/overview#currency-declaration) for guidelines on choosing the right value. **Only `USD` stablecoins can be used to pay transaction fees on Tempo.** +The `currency` field is **immutable** after token creation and affects fee payment eligibility, DEX routing, and quote token pairing. See [Currency Declaration](/docs/protocol/tip20/overview#currency-declaration) for guidelines on choosing the right value. **Only `USD` stablecoins can be used to pay transaction fees on Tempo.** If a token tracks USD but must not be gas eligible, such as a permissioned token that cannot support Fee Manager transfers, use `USD-NGE`. This also makes the token ineligible for the Stablecoin DEX and prevents it from using a `USD` quote token. ::: diff --git a/src/pages/docs/protocol/fees/spec-fee.mdx b/src/pages/docs/protocol/fees/spec-fee.mdx index b17b929c..6346f047 100644 --- a/src/pages/docs/protocol/fees/spec-fee.mdx +++ b/src/pages/docs/protocol/fees/spec-fee.mdx @@ -16,6 +16,8 @@ Tempo has no native token. Transaction fees are paid directly in USD-denominated Users can pay gas fees in any [TIP-20](/docs/protocol/tip20/spec) token whose currency is USD, as long as that stablecoin has sufficient liquidity on the enshrined [fee AMM](/docs/protocol/fees/spec-fee-amm) against the token that the current validator wants to receive. +Fee eligibility requires an exact `USD` currency value. Tokens that track USD but must not be gas eligible use the `USD-NGE` [currency convention](/docs/protocol/tip20/overview#currency-declaration). For example, a permissioned token can use `USD-NGE` when its transfer restrictions are incompatible with the Fee Manager or Fee AMM. + In determining *which* token a user pays fees in, we want to maximize customizability (so that wallets or users can implement more sophisticated UX than is possible at the protocol layer), minimize surprise (particularly surprises in which a user pays fees in a stablecoin they did not expect to), and have sane default behavior so that users can begin using basic functions like payments even using wallets that are not customized for Tempo support. ## Fee units diff --git a/src/pages/docs/protocol/tip20/overview.mdx b/src/pages/docs/protocol/tip20/overview.mdx index b1b60fc1..7d860625 100644 --- a/src/pages/docs/protocol/tip20/overview.mdx +++ b/src/pages/docs/protocol/tip20/overview.mdx @@ -132,14 +132,15 @@ A TIP-20 token can declare a currency identifier that identifies the reference a #### General principle -**The `currency` field identifies the reference asset that 1 unit of the token is designed to be worth** — not what the token is called or what it is denominated in. Two tokens that track the same asset should have the same `currency`. When in doubt, consider that the purpose of this field is to determine what assets a token would trade against on a DEX designed for assets that trade within 2% of a 1:1 price. +**The `currency` field identifies the reference asset that 1 unit of the token is designed to be worth** — not what the token is called or what it is denominated in. Two tokens that track the same asset should have the same `currency`, unless one intentionally opts out of gas eligibility with the `-NGE` suffix described below. When in doubt, consider that the purpose of this field is to determine what assets a token would trade against on a DEX designed for assets that trade within 2% of a 1:1 price. #### Guidelines 1. **Tokens that track an asset with an [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) code** — use that code. This includes fiat currencies (`"USD"`, `"EUR"`) as well as commodities (`"XAU"` for gold, `"XAG"` for silver). 2. **Tokens tracking a non-ISO asset at 1:1** — use the symbol of the reference asset. For example, a bridged WBTC that tracks BTC should use `"BTC"`; a bridged WETH that tracks ETH should use `"ETH"`. Prefer `"BTC"` over `"XBT"`. Use the symbol from the asset's origin chain when there is ambiguity across platforms. -3. **Tokens denominated in but not pegged to a currency** — do **not** use that currency's code. A tokenized gold product priced in USD should not use `"USD"`, because 1 unit is not designed to be worth 1 USD. -4. **Tokens with no reference asset** — if a token does not track any external asset (e.g. a governance or utility token), use its own symbol as the currency. +3. **Tokens that track a currency but must not be gas eligible** — append `-NGE` (not gas eligible) to the reference currency code. For example, use `"USD-NGE"` for a permissioned token that tracks USD but cannot support the Fee Manager or Fee AMM transfer flows. Apply the same convention to other currencies, such as `"EUR-NGE"`. This is a naming convention: the protocol excludes these tokens because gas and Stablecoin DEX eligibility currently require an exact `"USD"` currency value. +4. **Tokens denominated in but not pegged to a currency** — do **not** use that currency's code. A tokenized gold product priced in USD should not use `"USD"`, because 1 unit is not designed to be worth 1 USD. +5. **Tokens with no reference asset** — if a token does not track any external asset (e.g. a governance or utility token), use its own symbol as the currency. #### Currency declaration examples @@ -147,6 +148,7 @@ A TIP-20 token can declare a currency identifier that identifies the reference a |-------|--------|------------| | USDC | US Dollar | `"USD"` | | USDT | US Dollar | `"USD"` | +| WTGXX | US Dollar, permissioned and not gas eligible | `"USD-NGE"` | | EURC | Euro | `"EUR"` | | Bridged WBTC | Bitcoin | `"BTC"` | | Bridged stETH | Ether | `"ETH"` | @@ -155,7 +157,7 @@ A TIP-20 token can declare a currency identifier that identifies the reference a | Governance token (e.g. UNI) | Itself | `"UNI"` | :::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 token that uses `"USD-NGE"` cannot use a `"USD"` quote token because their currency values differ. ::: ### DEX Quote Tokens diff --git a/src/pages/docs/protocol/tip20/spec.mdx b/src/pages/docs/protocol/tip20/spec.mdx index d1fe342b..b2242b17 100644 --- a/src/pages/docs/protocol/tip20/spec.mdx +++ b/src/pages/docs/protocol/tip20/spec.mdx @@ -461,7 +461,7 @@ Recipient-bearing TIP-20 paths — `transfer`, `transferFrom`, `transferWithMemo Virtual addresses are valid TIP-20 recipients on those paths but remain forwarding aliases rather than canonical TIP-20 holders. Non-TIP-20 tokens sent to a virtual address do not forward. Forwarded deposits appear as two-hop standard `Transfer` events in the same transaction; indexers and explorers should collapse that pair into one logical deposit to the resolved master wallet. ## Currencies and Quote Tokens -Each TIP-20 token declares a [currency identifier](/docs/protocol/tip20/overview#currency-declaration) and a corresponding `quoteToken` used for pricing and routing in the Stablecoin DEX. 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. +Each TIP-20 token declares a [currency identifier](/docs/protocol/tip20/overview#currency-declaration) and a corresponding `quoteToken` used for pricing and routing in the Stablecoin DEX. The currency is set at token creation and **cannot be changed afterward**. **Only tokens with `currency == "USD"` are eligible for paying transaction fees.** A token that tracks USD but must not be gas eligible can declare `currency == "USD-NGE"`. This also makes it ineligible for the Stablecoin DEX and prevents it from using a `"USD"` quote token. 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 cc9c120eba720c23f89ee2527888621a84833bd0 Mon Sep 17 00:00:00 2001 From: malleshpai <5857042+malleshpai@users.noreply.github.com> Date: Thu, 20 Aug 2026 18:00:05 +0000 Subject: [PATCH 2/3] docs: remove WTGXX example Co-authored-by: Derek Cofausper <256792747+decofe@users.noreply.github.com> --- src/pages/docs/protocol/tip20/overview.mdx | 1 - 1 file changed, 1 deletion(-) diff --git a/src/pages/docs/protocol/tip20/overview.mdx b/src/pages/docs/protocol/tip20/overview.mdx index 7d860625..7b77ba6d 100644 --- a/src/pages/docs/protocol/tip20/overview.mdx +++ b/src/pages/docs/protocol/tip20/overview.mdx @@ -148,7 +148,6 @@ A TIP-20 token can declare a currency identifier that identifies the reference a |-------|--------|------------| | USDC | US Dollar | `"USD"` | | USDT | US Dollar | `"USD"` | -| WTGXX | US Dollar, permissioned and not gas eligible | `"USD-NGE"` | | EURC | Euro | `"EUR"` | | Bridged WBTC | Bitcoin | `"BTC"` | | Bridged stETH | Ether | `"ETH"` | From dbfdc2da24273307e1265ab812b01e3814621776 Mon Sep 17 00:00:00 2001 From: malleshpai <5857042+malleshpai@users.noreply.github.com> Date: Thu, 20 Aug 2026 18:08:11 +0000 Subject: [PATCH 3/3] docs: correct USD-NGE quote-token guidance Co-authored-by: Derek Cofausper <256792747+decofe@users.noreply.github.com> --- src/pages/docs/guide/issuance/create-a-stablecoin.mdx | 2 +- src/pages/docs/protocol/tip20/overview.mdx | 2 +- src/pages/docs/protocol/tip20/spec.mdx | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/src/pages/docs/guide/issuance/create-a-stablecoin.mdx b/src/pages/docs/guide/issuance/create-a-stablecoin.mdx index 1c650b4e..06296f49 100644 --- a/src/pages/docs/guide/issuance/create-a-stablecoin.mdx +++ b/src/pages/docs/guide/issuance/create-a-stablecoin.mdx @@ -156,7 +156,7 @@ After this step, your users will be able to create a stablecoin by clicking the Tokens can also carry an optional on-chain [`logoURI`](/docs/protocol/tip20/spec#logo-uri) that wallets and explorers read directly from the token contract. It's set on the token contract and is independent of this creation flow; for the recommended format, use a square, rasterized PNG or WebP (max 256 bytes; `https`, `http`, `ipfs`, or `data` scheme). :::warning -The `currency` field is **immutable** after token creation and affects fee payment eligibility, DEX routing, and quote token pairing. See [Currency Declaration](/docs/protocol/tip20/overview#currency-declaration) for guidelines on choosing the right value. **Only `USD` stablecoins can be used to pay transaction fees on Tempo.** If a token tracks USD but must not be gas eligible, such as a permissioned token that cannot support Fee Manager transfers, use `USD-NGE`. This also makes the token ineligible for the Stablecoin DEX and prevents it from using a `USD` quote token. +The `currency` field is **immutable** after token creation and affects fee payment eligibility, DEX routing, and quote token pairing. See [Currency Declaration](/docs/protocol/tip20/overview#currency-declaration) for guidelines on choosing the right value. **Only `USD` stablecoins can be used to pay transaction fees on Tempo.** If a token tracks USD but must not be gas eligible, such as a permissioned token that cannot support Fee Manager transfers, use `USD-NGE`. This also makes the token ineligible for the Stablecoin DEX. ::: diff --git a/src/pages/docs/protocol/tip20/overview.mdx b/src/pages/docs/protocol/tip20/overview.mdx index 7b77ba6d..c1160a42 100644 --- a/src/pages/docs/protocol/tip20/overview.mdx +++ b/src/pages/docs/protocol/tip20/overview.mdx @@ -156,7 +156,7 @@ A TIP-20 token can declare a currency identifier that identifies the reference a | Governance token (e.g. UNI) | Itself | `"UNI"` | :::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. A token that uses `"USD-NGE"` cannot use a `"USD"` quote token because their currency values differ. +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 diff --git a/src/pages/docs/protocol/tip20/spec.mdx b/src/pages/docs/protocol/tip20/spec.mdx index b2242b17..12d9b336 100644 --- a/src/pages/docs/protocol/tip20/spec.mdx +++ b/src/pages/docs/protocol/tip20/spec.mdx @@ -461,7 +461,7 @@ Recipient-bearing TIP-20 paths — `transfer`, `transferFrom`, `transferWithMemo Virtual addresses are valid TIP-20 recipients on those paths but remain forwarding aliases rather than canonical TIP-20 holders. Non-TIP-20 tokens sent to a virtual address do not forward. Forwarded deposits appear as two-hop standard `Transfer` events in the same transaction; indexers and explorers should collapse that pair into one logical deposit to the resolved master wallet. ## Currencies and Quote Tokens -Each TIP-20 token declares a [currency identifier](/docs/protocol/tip20/overview#currency-declaration) and a corresponding `quoteToken` used for pricing and routing in the Stablecoin DEX. The currency is set at token creation and **cannot be changed afterward**. **Only tokens with `currency == "USD"` are eligible for paying transaction fees.** A token that tracks USD but must not be gas eligible can declare `currency == "USD-NGE"`. This also makes it ineligible for the Stablecoin DEX and prevents it from using a `"USD"` quote token. Tokens with `currency == "USD"` must pair with a USD-denominated TIP-20 token. +Each TIP-20 token declares a [currency identifier](/docs/protocol/tip20/overview#currency-declaration) and a corresponding `quoteToken` used for pricing and routing in the Stablecoin DEX. The currency is set at token creation and **cannot be changed afterward**. **Only tokens with `currency == "USD"` are eligible for paying transaction fees.** A token that tracks USD but must not be gas eligible can declare `currency == "USD-NGE"`. This also makes it ineligible for the Stablecoin DEX. 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.