From fb4389b43ec3497ec22a3f6a8c240a4a6a1f1587 Mon Sep 17 00:00:00 2001 From: joshitzko <82132285+joshitzko@users.noreply.github.com> Date: Fri, 26 Jun 2026 17:21:59 -0400 Subject: [PATCH 1/2] Clarify non-USD TIP-20 issuance docs --- .../guide/issuance/create-a-stablecoin.mdx | 26 +++++++++++++++++++ .../docs/protocol/exchange/quote-tokens.mdx | 16 +++++++++--- src/pages/docs/protocol/tip20/overview.mdx | 8 +++++- 3 files changed, 46 insertions(+), 4 deletions(-) diff --git a/src/pages/docs/guide/issuance/create-a-stablecoin.mdx b/src/pages/docs/guide/issuance/create-a-stablecoin.mdx index d3ca4d8d..430fa210 100644 --- a/src/pages/docs/guide/issuance/create-a-stablecoin.mdx +++ b/src/pages/docs/guide/issuance/create-a-stablecoin.mdx @@ -157,6 +157,32 @@ Tokens can also carry an optional on-chain `logoURI` ([TIP-1026](https://tips.sh 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.** ::: +#### Choose currency and quote token + +Set `currency` to the reference asset the token tracks, not to the token symbol. For fiat-backed stablecoins, use the ISO 4217 code such as `USD`, `EUR`, `BRL`, or `MXN`. Do not set `currency: 'USD'` unless 1 token is intended to track 1 US dollar. + +The SDK defaults `quoteToken` to [`pathUSD`](/docs/protocol/exchange/quote-tokens#pathusd) (`0x20c0000000000000000000000000000000000000`) when omitted. If you override `quoteToken`, it must be an already deployed TIP-20. + +| Token you are issuing | Quote token | Factory behavior | Tempo behavior today | +| --- | --- | --- | --- | +| `USD` stablecoin | Deployed `USD` TIP-20, such as `pathUSD` | Deploys | Eligible for fee payment; native DEX routing is supported when liquidity exists | +| `USD` stablecoin | Deployed non-`USD` TIP-20 | Reverts with `InvalidQuoteToken` | Not applicable | +| Non-`USD` stablecoin | Any deployed TIP-20 | Deploys | Minting, transfers, roles, policies, and memos work; not eligible for fee payment; native DEX trading is not supported today | +| Any token | Undeployed or non-TIP-20 address | Reverts with `InvalidQuoteToken` | Not applicable | + +If you override the SDK default, verify the quote token before deploying: + +```bash +export RPC_URL=https://rpc.moderato.tempo.xyz +export TIP20_FACTORY=0x20fc000000000000000000000000000000000000 +export QUOTE_TOKEN=0x20c0000000000000000000000000000000000000 + +cast call $TIP20_FACTORY "isTIP20(address)(bool)" $QUOTE_TOKEN --rpc-url $RPC_URL +cast call $QUOTE_TOKEN "currency()(string)" --rpc-url $RPC_URL +``` + +For a `USD` token, the quote token's `currency()` must return `USD`. For a local-currency token, the quote token selection records your intended pricing/routing metadata, but it does not enable native DEX FX trading today. + diff --git a/src/pages/docs/protocol/exchange/quote-tokens.mdx b/src/pages/docs/protocol/exchange/quote-tokens.mdx index b93c2f05..56a8bbe2 100644 --- a/src/pages/docs/protocol/exchange/quote-tokens.mdx +++ b/src/pages/docs/protocol/exchange/quote-tokens.mdx @@ -1,5 +1,5 @@ --- -description: Quote tokens determine trading pairs on Tempo's DEX. Each TIP-20 specifies a quote token, with pathUSD available as an optional neutral choice. +description: Quote tokens determine trading pairs on Tempo's DEX. Each TIP-20 specifies a quote token, with pathUSD available as an optional neutral USD choice. --- # Quote Tokens @@ -16,9 +16,9 @@ pathUSD is issued by Bridge and is backed 1:1 by high-quality USD-denominated re ### Why pathUSD? -Tempo is designed to be neutral across stablecoin issuers. Rather than defaulting to any single issuer's stablecoin as the quote token, pathUSD provides a neutral option that any token can pair against on Tempo's DEX. This ensures that no single stablecoin issuer has a privileged position in Tempo's liquidity graph and guarantees stablecoin interoperability. +Tempo is designed to be neutral across stablecoin issuers. Rather than defaulting to any single issuer's stablecoin as the quote token, pathUSD provides a neutral option that any USD token can pair against on Tempo's DEX. This ensures that no single stablecoin issuer has a privileged position in Tempo's liquidity graph and guarantees stablecoin interoperability. -pathUSD is not meant to compete as a consumer-facing stablecoin. Use of pathUSD is optional, and tokens are able to list any other token as their quote token if they choose. pathUSD can also be accepted as a fee token by validators. +pathUSD is not meant to compete as a consumer-facing stablecoin. Use of pathUSD is optional, and USD tokens are able to list any other USD token as their quote token if they choose. pathUSD can also be accepted as a fee token by validators. ### Contract @@ -52,6 +52,16 @@ This means: - Your token trades against pathUSD on the exchange. - Users can swap between your token and other USD stablecoins that also use pathUSD, or ones connected by a multi-hop path. +### Non-USD Stablecoins + +Non-USD TIP-20 tokens also specify `quoteToken()` metadata at issuance. The quote token must be a deployed TIP-20, but current native DEX support is USD-only: + +- A `USD` token must choose a `USD` quote token. +- A non-`USD` token can choose any deployed TIP-20 quote token. +- Setting a quote token for a non-`USD` token does not create a native DEX FX market or enable same-currency non-USD trading today. + +Local-currency issuers can still deploy TIP-20 tokens, mint and burn supply, transfer with memos, and use roles and transfer policies. Choose a deployed TIP-20 that represents your current pricing or routing plan; changing it later requires the TIP-20 quote-token update flow. + ### Tree Structure Quote token relationships form a tree structure where all USD stablecoins are connected via multi-hop paths: diff --git a/src/pages/docs/protocol/tip20/overview.mdx b/src/pages/docs/protocol/tip20/overview.mdx index fb4e98f7..447532ed 100644 --- a/src/pages/docs/protocol/tip20/overview.mdx +++ b/src/pages/docs/protocol/tip20/overview.mdx @@ -93,6 +93,8 @@ Below are some of the key benefits and features of TIP-20 tokens: Any USD-denominated TIP-20 token can be used to pay transaction fees on Tempo. +Non-USD TIP-20 tokens can still be issued and used for token transfers, role-based operations, transfer policies, memos, and other TIP-20 functionality. They are not transaction fee tokens today. + The [Fee AMM](/docs/protocol/fees/spec-fee-amm) automatically converts your token to the validator's preferred fee token, eliminating the need for users to hold a separate gas token. This feature works natively: no additional infrastructure or integration required. Full specification of this feature can be found in the [Payment Lanes Specification](/docs/protocol/blockspace/payment-lane-specification). @@ -142,6 +144,8 @@ A TIP-20 token can declare a currency identifier that identifies the reference a **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. +Do not set `currency` to `"USD"` to gain fee eligibility or DEX support unless the token actually tracks the US dollar. A token that tracks another fiat currency should use that currency's ISO 4217 code even though non-USD tokens are not fee tokens or tradable on the native DEX today. + #### 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). @@ -170,7 +174,9 @@ The currency code is **immutable** — it cannot be changed after token creation TIP-20 tokens can serve as quote tokens in Tempo's decentralized exchange (DEX). When creating trading pairs on the [Stablecoin DEX](/docs/protocol/exchange), TIP-20 tokens function as the quote currency against which other tokens are priced and traded. -This enables efficient stablecoin-to-stablecoin trading and provides optimized routing for liquidity. For example, a USDG TIP-20 token can be paired with other stablecoins, allowing traders to swap between different USD-denominated tokens with minimal slippage through concentrated liquidity pools. +This currently enables efficient USD stablecoin-to-stablecoin trading and provides optimized routing for liquidity. For example, a USDG TIP-20 token can be paired with other stablecoins, allowing traders to swap between different USD-denominated tokens with minimal slippage through concentrated liquidity pools. + +Non-USD TIP-20 tokens also have `quoteToken` metadata, but current native DEX pair creation and swaps only support USD-denominated tokens. See [Quote Tokens](/docs/protocol/exchange/quote-tokens) for the current quote-token rules. By using TIP-20 tokens as quote tokens, the DEX benefits from the same payment-optimized features like deterministic addresses, currency identifiers, and compliance policies, ensuring secure and efficient exchange operations. From d498d36fa81858304990738308f8ad0145675e5d Mon Sep 17 00:00:00 2001 From: joshitzko <82132285+joshitzko@users.noreply.github.com> Date: Fri, 26 Jun 2026 17:27:09 -0400 Subject: [PATCH 2/2] Trim non-USD TIP-20 docs guidance --- .../guide/issuance/create-a-stablecoin.mdx | 26 +++---------------- .../docs/protocol/exchange/quote-tokens.mdx | 16 +++--------- src/pages/docs/protocol/tip20/overview.mdx | 8 +----- 3 files changed, 7 insertions(+), 43 deletions(-) diff --git a/src/pages/docs/guide/issuance/create-a-stablecoin.mdx b/src/pages/docs/guide/issuance/create-a-stablecoin.mdx index 430fa210..2ec98fd3 100644 --- a/src/pages/docs/guide/issuance/create-a-stablecoin.mdx +++ b/src/pages/docs/guide/issuance/create-a-stablecoin.mdx @@ -157,31 +157,11 @@ Tokens can also carry an optional on-chain `logoURI` ([TIP-1026](https://tips.sh 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.** ::: -#### Choose currency and quote token +#### Issuing non-USD stablecoins -Set `currency` to the reference asset the token tracks, not to the token symbol. For fiat-backed stablecoins, use the ISO 4217 code such as `USD`, `EUR`, `BRL`, or `MXN`. Do not set `currency: 'USD'` unless 1 token is intended to track 1 US dollar. +Set `currency` to the reference asset the token tracks, not to the token symbol. For fiat-backed stablecoins, use the ISO 4217 code such as `USD`, `EUR`, `BRL`, or `MXN`; do not use `USD` unless 1 token is intended to track 1 US dollar. -The SDK defaults `quoteToken` to [`pathUSD`](/docs/protocol/exchange/quote-tokens#pathusd) (`0x20c0000000000000000000000000000000000000`) when omitted. If you override `quoteToken`, it must be an already deployed TIP-20. - -| Token you are issuing | Quote token | Factory behavior | Tempo behavior today | -| --- | --- | --- | --- | -| `USD` stablecoin | Deployed `USD` TIP-20, such as `pathUSD` | Deploys | Eligible for fee payment; native DEX routing is supported when liquidity exists | -| `USD` stablecoin | Deployed non-`USD` TIP-20 | Reverts with `InvalidQuoteToken` | Not applicable | -| Non-`USD` stablecoin | Any deployed TIP-20 | Deploys | Minting, transfers, roles, policies, and memos work; not eligible for fee payment; native DEX trading is not supported today | -| Any token | Undeployed or non-TIP-20 address | Reverts with `InvalidQuoteToken` | Not applicable | - -If you override the SDK default, verify the quote token before deploying: - -```bash -export RPC_URL=https://rpc.moderato.tempo.xyz -export TIP20_FACTORY=0x20fc000000000000000000000000000000000000 -export QUOTE_TOKEN=0x20c0000000000000000000000000000000000000 - -cast call $TIP20_FACTORY "isTIP20(address)(bool)" $QUOTE_TOKEN --rpc-url $RPC_URL -cast call $QUOTE_TOKEN "currency()(string)" --rpc-url $RPC_URL -``` - -For a `USD` token, the quote token's `currency()` must return `USD`. For a local-currency token, the quote token selection records your intended pricing/routing metadata, but it does not enable native DEX FX trading today. +The SDK defaults `quoteToken` to [`pathUSD`](/docs/protocol/exchange/quote-tokens#pathusd). If you override it, use an already deployed TIP-20. `USD` tokens must use a `USD` quote token; non-`USD` TIP-20s can be issued with any deployed TIP-20 quote token, but they are not fee tokens and are not supported by native DEX trading today. diff --git a/src/pages/docs/protocol/exchange/quote-tokens.mdx b/src/pages/docs/protocol/exchange/quote-tokens.mdx index 56a8bbe2..b93c2f05 100644 --- a/src/pages/docs/protocol/exchange/quote-tokens.mdx +++ b/src/pages/docs/protocol/exchange/quote-tokens.mdx @@ -1,5 +1,5 @@ --- -description: Quote tokens determine trading pairs on Tempo's DEX. Each TIP-20 specifies a quote token, with pathUSD available as an optional neutral USD choice. +description: Quote tokens determine trading pairs on Tempo's DEX. Each TIP-20 specifies a quote token, with pathUSD available as an optional neutral choice. --- # Quote Tokens @@ -16,9 +16,9 @@ pathUSD is issued by Bridge and is backed 1:1 by high-quality USD-denominated re ### Why pathUSD? -Tempo is designed to be neutral across stablecoin issuers. Rather than defaulting to any single issuer's stablecoin as the quote token, pathUSD provides a neutral option that any USD token can pair against on Tempo's DEX. This ensures that no single stablecoin issuer has a privileged position in Tempo's liquidity graph and guarantees stablecoin interoperability. +Tempo is designed to be neutral across stablecoin issuers. Rather than defaulting to any single issuer's stablecoin as the quote token, pathUSD provides a neutral option that any token can pair against on Tempo's DEX. This ensures that no single stablecoin issuer has a privileged position in Tempo's liquidity graph and guarantees stablecoin interoperability. -pathUSD is not meant to compete as a consumer-facing stablecoin. Use of pathUSD is optional, and USD tokens are able to list any other USD token as their quote token if they choose. pathUSD can also be accepted as a fee token by validators. +pathUSD is not meant to compete as a consumer-facing stablecoin. Use of pathUSD is optional, and tokens are able to list any other token as their quote token if they choose. pathUSD can also be accepted as a fee token by validators. ### Contract @@ -52,16 +52,6 @@ This means: - Your token trades against pathUSD on the exchange. - Users can swap between your token and other USD stablecoins that also use pathUSD, or ones connected by a multi-hop path. -### Non-USD Stablecoins - -Non-USD TIP-20 tokens also specify `quoteToken()` metadata at issuance. The quote token must be a deployed TIP-20, but current native DEX support is USD-only: - -- A `USD` token must choose a `USD` quote token. -- A non-`USD` token can choose any deployed TIP-20 quote token. -- Setting a quote token for a non-`USD` token does not create a native DEX FX market or enable same-currency non-USD trading today. - -Local-currency issuers can still deploy TIP-20 tokens, mint and burn supply, transfer with memos, and use roles and transfer policies. Choose a deployed TIP-20 that represents your current pricing or routing plan; changing it later requires the TIP-20 quote-token update flow. - ### Tree Structure Quote token relationships form a tree structure where all USD stablecoins are connected via multi-hop paths: diff --git a/src/pages/docs/protocol/tip20/overview.mdx b/src/pages/docs/protocol/tip20/overview.mdx index 447532ed..fb4e98f7 100644 --- a/src/pages/docs/protocol/tip20/overview.mdx +++ b/src/pages/docs/protocol/tip20/overview.mdx @@ -93,8 +93,6 @@ Below are some of the key benefits and features of TIP-20 tokens: Any USD-denominated TIP-20 token can be used to pay transaction fees on Tempo. -Non-USD TIP-20 tokens can still be issued and used for token transfers, role-based operations, transfer policies, memos, and other TIP-20 functionality. They are not transaction fee tokens today. - The [Fee AMM](/docs/protocol/fees/spec-fee-amm) automatically converts your token to the validator's preferred fee token, eliminating the need for users to hold a separate gas token. This feature works natively: no additional infrastructure or integration required. Full specification of this feature can be found in the [Payment Lanes Specification](/docs/protocol/blockspace/payment-lane-specification). @@ -144,8 +142,6 @@ A TIP-20 token can declare a currency identifier that identifies the reference a **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. -Do not set `currency` to `"USD"` to gain fee eligibility or DEX support unless the token actually tracks the US dollar. A token that tracks another fiat currency should use that currency's ISO 4217 code even though non-USD tokens are not fee tokens or tradable on the native DEX today. - #### 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). @@ -174,9 +170,7 @@ The currency code is **immutable** — it cannot be changed after token creation TIP-20 tokens can serve as quote tokens in Tempo's decentralized exchange (DEX). When creating trading pairs on the [Stablecoin DEX](/docs/protocol/exchange), TIP-20 tokens function as the quote currency against which other tokens are priced and traded. -This currently enables efficient USD stablecoin-to-stablecoin trading and provides optimized routing for liquidity. For example, a USDG TIP-20 token can be paired with other stablecoins, allowing traders to swap between different USD-denominated tokens with minimal slippage through concentrated liquidity pools. - -Non-USD TIP-20 tokens also have `quoteToken` metadata, but current native DEX pair creation and swaps only support USD-denominated tokens. See [Quote Tokens](/docs/protocol/exchange/quote-tokens) for the current quote-token rules. +This enables efficient stablecoin-to-stablecoin trading and provides optimized routing for liquidity. For example, a USDG TIP-20 token can be paired with other stablecoins, allowing traders to swap between different USD-denominated tokens with minimal slippage through concentrated liquidity pools. By using TIP-20 tokens as quote tokens, the DEX benefits from the same payment-optimized features like deterministic addresses, currency identifiers, and compliance policies, ensuring secure and efficient exchange operations.