From d2bcc93f0e5b300538d6618fe61e4002029f6303 Mon Sep 17 00:00:00 2001 From: max-digi Date: Thu, 7 May 2026 18:11:54 +0100 Subject: [PATCH 1/6] docs: add Querying Tempo page Adds a new page under Integrate Tempo covering data-layer differences analysts and indexers need to know when querying Tempo: USD-denominated fees, TIP-20 6 decimals, Transfer events vs tx.value, fee_payer attribution, system transactions, and supply derivation. Also includes key precompile addresses and network details. Amp-Thread-ID: https://ampcode.com/threads/T-019e0366-1385-70ac-8cf3-1738206b7d0e Co-authored-by: Amp --- src/pages/quickstart/querying-tempo.mdx | 113 ++++++++++++++++++++++++ vocs.config.ts | 4 + 2 files changed, 117 insertions(+) create mode 100644 src/pages/quickstart/querying-tempo.mdx diff --git a/src/pages/quickstart/querying-tempo.mdx b/src/pages/quickstart/querying-tempo.mdx new file mode 100644 index 00000000..38982c3a --- /dev/null +++ b/src/pages/quickstart/querying-tempo.mdx @@ -0,0 +1,113 @@ +--- +title: Querying Tempo +description: Write correct analytics queries for Tempo. Covers fee units, TIP-20 decimals, Transfer events, fee_payer attribution, system transactions, and supply. +showOutline: 1 +--- + +# Querying Tempo + +Tempo is EVM-compatible, so most query patterns you already know work here. There are a handful of differences that will silently produce wrong numbers if you carry over Ethereum assumptions. This page covers them. + +The examples use generic SQL — column and table names will vary by platform. + +## 1. Fees are in USD, not ETH + +On Ethereum, gas price is in wei (10⁻¹⁸ ETH). On Tempo, gas price is in **attodollars** (10⁻¹⁸ USD). The result of the fee calculation is USD. There is no native token. + +The correct formula rounds to the nearest microdollar, which is how fees are actually settled: + +```sql +CEIL(effective_gas_price * gas_used / 1e12) / 1e6 +``` + +```sql +SELECT date_trunc('day', block_time) AS day, + SUM(CEIL(effective_gas_price * gas_used / 1e12) / 1e6) AS usd_fees +FROM transactions +GROUP BY 1 +ORDER BY 1; +``` + +## 2. TIP-20 tokens use 6 decimals, not 18 + +Divide token amounts by `1e6`. Using `1e18` gives a result 10¹² times too small. + +## 3. Use Transfer events for volume, not tx.value + +`tx.value` is always zero on Tempo. All token movement is captured in `Transfer` events. + +```sql +SELECT date_trunc('day', block_time) AS day, + token_address, + SUM(amount) / 1e6 AS volume_usd +FROM tip20_transfers +GROUP BY 1, 2 +ORDER BY 1; +``` + +`TransferWithMemo` (used by MPP and others) also emits a standard `Transfer` event. If your platform exposes both, query only `Transfer` — including both double-counts every memo transfer. + +## 4. Use COALESCE(fee_payer, from) for attribution + +Sponsored transactions populate a separate `fee_payer` field. If you group by `from` to measure who paid fees or sent transactions, sponsored activity gets attributed to the wrong address. + +```sql +SELECT COALESCE(fee_payer, "from") AS payer, + COUNT(*) AS tx_count, + SUM(CEIL(effective_gas_price * gas_used / 1e12) / 1e6) AS usd_paid +FROM transactions +GROUP BY 1 +ORDER BY 3 DESC; +``` + +## 5. Exclude system transactions when measuring user activity + +Transactions where `from = 0x0000000000000000000000000000000000000000` are system-level. Include them in raw chain metrics but exclude them when computing things like active addresses, unique senders, or user-initiated volume. + +## 6. Compute token supply from Transfer events, not Mint events + +Genesis mints on Tempo may not emit a `Mint` event. To get accurate supply, derive it from `Transfer` events: mints have `from = 0x0000…0000`, burns have `to = 0x0000…0000`. + +```sql +SELECT + SUM(CASE WHEN "from" = 0x0000000000000000000000000000000000000000 + THEN amount / 1e6 ELSE 0 END) AS total_minted, + SUM(CASE WHEN "to" = 0x0000000000000000000000000000000000000000 + THEN amount / 1e6 ELSE 0 END) AS total_burned, + SUM(CASE WHEN "from" = 0x0000000000000000000000000000000000000000 + THEN amount / 1e6 + WHEN "to" = 0x0000000000000000000000000000000000000000 + THEN -amount / 1e6 + ELSE 0 END) AS supply +FROM tip20_transfers +WHERE token_address = ; +``` + +## Key addresses + +| Contract | Address | +| --- | --- | +| FeeManager | `0xfeec000000000000000000000000000000000000` | +| Stablecoin DEX | `0xdec0000000000000000000000000000000000000` | +| TIP-20 Factory | `0x20fc000000000000000000000000000000000000` | +| PathUSD | `0x20c0000000000000000000000000000000000000` | + +## Networks + +### Mainnet + +| | | +| --- | --- | +| Chain ID | `4217` | +| RPC | `https://rpc.tempo.xyz` | +| Explorer | `https://explore.tempo.xyz` | +| Tokenlist | `https://tokenlist.tempo.xyz/list/4217` | + +### Testnet (Moderato) + +| | | +| --- | --- | +| Chain ID | `42431` | +| RPC | `https://rpc.moderato.tempo.xyz` | +| Explorer | `https://explore.testnet.tempo.xyz` | +| Tokenlist | `https://tokenlist.tempo.xyz/list/42431` | diff --git a/vocs.config.ts b/vocs.config.ts index 89c8e12b..385ff22b 100644 --- a/vocs.config.ts +++ b/vocs.config.ts @@ -444,6 +444,10 @@ export default defineConfig({ text: 'Wallet Developers', link: '/quickstart/wallet-developers', }, + { + text: 'Querying Tempo', + link: '/quickstart/querying-tempo', + }, { text: 'Contract Verification', link: '/quickstart/verify-contracts', From ad728b984f5eb1b3dbca757c1b899ece9b9d9ec3 Mon Sep 17 00:00:00 2001 From: max-digi Date: Thu, 7 May 2026 19:00:01 +0100 Subject: [PATCH 2/6] docs(querying-tempo): make Transfer queries interactive via IndexSupplyQuery Address PR feedback: replace static SQL examples for the Transfer-based sections (volume, supply) with the existing component so readers can edit and run them against Tempo mainnet via Index Supply. Gas-fee, fee_payer attribution, and system-tx examples remain static blocks because they reference Tempo-specific columns (effective_gas_price, fee_payer) not exposed in IndexSupply's standard schema. Amp-Thread-ID: https://ampcode.com/threads/T-019e0366-1385-70ac-8cf3-1738206b7d0e Co-authored-by: Amp --- src/pages/quickstart/querying-tempo.mdx | 63 ++++++++++++++++--------- 1 file changed, 40 insertions(+), 23 deletions(-) diff --git a/src/pages/quickstart/querying-tempo.mdx b/src/pages/quickstart/querying-tempo.mdx index 38982c3a..bce1ccaf 100644 --- a/src/pages/quickstart/querying-tempo.mdx +++ b/src/pages/quickstart/querying-tempo.mdx @@ -4,11 +4,13 @@ description: Write correct analytics queries for Tempo. Covers fee units, TIP-20 showOutline: 1 --- +import { IndexSupplyQuery } from '../../components/IndexSupplyQuery' + # Querying Tempo Tempo is EVM-compatible, so most query patterns you already know work here. There are a handful of differences that will silently produce wrong numbers if you carry over Ethereum assumptions. This page covers them. -The examples use generic SQL — column and table names will vary by platform. +The interactive examples below run against [Index Supply](https://www.indexsupply.net) on Tempo mainnet — edit the SQL and hit **Run Query** to try variations. The static examples use generic SQL — column and table names will vary by platform. ## 1. Fees are in USD, not ETH @@ -36,14 +38,22 @@ Divide token amounts by `1e6`. Using `1e18` gives a result 10¹² times too smal `tx.value` is always zero on Tempo. All token movement is captured in `Transfer` events. -```sql -SELECT date_trunc('day', block_time) AS day, - token_address, - SUM(amount) / 1e6 AS volume_usd -FROM tip20_transfers -GROUP BY 1, 2 -ORDER BY 1; -``` +The query below sums `Transfer` event amounts for `pathUSD` (the network's reference stablecoin). Adjust the `address` filter or grouping to inspect any TIP-20 token. + + `TransferWithMemo` (used by MPP and others) also emits a standard `Transfer` event. If your platform exposes both, query only `Transfer` — including both double-counts every memo transfer. @@ -68,20 +78,27 @@ Transactions where `from = 0x0000000000000000000000000000000000000000` are syste Genesis mints on Tempo may not emit a `Mint` event. To get accurate supply, derive it from `Transfer` events: mints have `from = 0x0000…0000`, burns have `to = 0x0000…0000`. -```sql -SELECT - SUM(CASE WHEN "from" = 0x0000000000000000000000000000000000000000 - THEN amount / 1e6 ELSE 0 END) AS total_minted, - SUM(CASE WHEN "to" = 0x0000000000000000000000000000000000000000 - THEN amount / 1e6 ELSE 0 END) AS total_burned, - SUM(CASE WHEN "from" = 0x0000000000000000000000000000000000000000 - THEN amount / 1e6 - WHEN "to" = 0x0000000000000000000000000000000000000000 - THEN -amount / 1e6 - ELSE 0 END) AS supply -FROM tip20_transfers -WHERE token_address = ; -``` +The query below derives `pathUSD` total minted, total burned, and live supply directly from `Transfer` events. + + + +Divide each value by `1e6` to convert raw amounts to whole tokens. ## Key addresses From a0f30247a2349a5ce99f2c7d3ec1c1be2e0c5f51 Mon Sep 17 00:00:00 2001 From: max-digi Date: Thu, 7 May 2026 18:30:07 +0100 Subject: [PATCH 3/6] fix(sync): quote authors with @ to prevent YAML parse error Upstream TIPs occasionally include GitHub handles like @0xrusowsky in the authors field. The leading @ is a YAML reserved character and breaks the build. Quote the value defensively when it begins with any YAML reserved char. Amp-Thread-ID: https://ampcode.com/threads/T-019e0366-1385-70ac-8cf3-1738206b7d0e Co-authored-by: Amp --- vite.config.ts | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/vite.config.ts b/vite.config.ts index aea1b131..27ce7716 100644 --- a/vite.config.ts +++ b/vite.config.ts @@ -124,6 +124,13 @@ function syncTips(): Plugin { // Escape angle brackets outside of code blocks/inline code so MDX doesn't // treat them as JSX (e.g. `Mapping` in prose). content = escapeAngleBrackets(content) + // Quote frontmatter `authors:` values that start with a YAML reserved + // character (e.g. `@handle`). Upstream TIPs occasionally include GitHub + // handles like `@0xrusowsky`, which break YAML parsing unless quoted. + content = content.replace( + /^(authors:\s*)([@&*!|>%#`].*)$/m, + (_m, prefix, value) => `${prefix}"${value.replace(/"/g, '\\"')}"`, + ) const outputPath = path.join(outputDir, file.name.replace('.md', '.mdx')) await fs.writeFile(outputPath, content) }), From f3829980102cf07d05d41701991735fdcf122e55 Mon Sep 17 00:00:00 2001 From: max-digi Date: Thu, 7 May 2026 19:01:08 +0100 Subject: [PATCH 4/6] docs(querying-tempo): simplify, single interactive example Amp-Thread-ID: https://ampcode.com/threads/T-019e0366-1385-70ac-8cf3-1738206b7d0e Co-authored-by: Amp --- src/pages/quickstart/querying-tempo.mdx | 97 ++++++++----------------- 1 file changed, 32 insertions(+), 65 deletions(-) diff --git a/src/pages/quickstart/querying-tempo.mdx b/src/pages/quickstart/querying-tempo.mdx index bce1ccaf..83af641c 100644 --- a/src/pages/quickstart/querying-tempo.mdx +++ b/src/pages/quickstart/querying-tempo.mdx @@ -8,19 +8,15 @@ import { IndexSupplyQuery } from '../../components/IndexSupplyQuery' # Querying Tempo -Tempo is EVM-compatible, so most query patterns you already know work here. There are a handful of differences that will silently produce wrong numbers if you carry over Ethereum assumptions. This page covers them. +Tempo is EVM-compatible, so most query patterns you already know work here. There are a handful of differences that will silently produce wrong numbers if you carry over Ethereum assumptions. -The interactive examples below run against [Index Supply](https://www.indexsupply.net) on Tempo mainnet — edit the SQL and hit **Run Query** to try variations. The static examples use generic SQL — column and table names will vary by platform. +The interactive examples run live against [Index Supply](https://www.indexsupply.net) on Tempo mainnet — edit the SQL and hit **Run Query**. Static examples use generic SQL — table and column names will vary by platform. ## 1. Fees are in USD, not ETH -On Ethereum, gas price is in wei (10⁻¹⁸ ETH). On Tempo, gas price is in **attodollars** (10⁻¹⁸ USD). The result of the fee calculation is USD. There is no native token. +On Ethereum, gas price is in wei (10⁻¹⁸ ETH). On Tempo, it's in **attodollars** (10⁻¹⁸ USD). The fee calculation result is USD. There is no native token. -The correct formula rounds to the nearest microdollar, which is how fees are actually settled: - -```sql -CEIL(effective_gas_price * gas_used / 1e12) / 1e6 -``` +Round to the nearest microdollar (how fees actually settle): ```sql SELECT date_trunc('day', block_time) AS day, @@ -36,69 +32,51 @@ Divide token amounts by `1e6`. Using `1e18` gives a result 10¹² times too smal ## 3. Use Transfer events for volume, not tx.value -`tx.value` is always zero on Tempo. All token movement is captured in `Transfer` events. - -The query below sums `Transfer` event amounts for `pathUSD` (the network's reference stablecoin). Adjust the `address` filter or grouping to inspect any TIP-20 token. +`tx.value` is always zero on Tempo. All token movement is in `Transfer` events. -`TransferWithMemo` (used by MPP and others) also emits a standard `Transfer` event. If your platform exposes both, query only `Transfer` — including both double-counts every memo transfer. +`TransferWithMemo` (used by MPP) also emits a standard `Transfer`. Query only `Transfer` to avoid double-counting. ## 4. Use COALESCE(fee_payer, from) for attribution -Sponsored transactions populate a separate `fee_payer` field. If you group by `from` to measure who paid fees or sent transactions, sponsored activity gets attributed to the wrong address. +Sponsored transactions populate a separate `fee_payer` field. Grouping by `from` attributes sponsored activity to the wrong address. ```sql SELECT COALESCE(fee_payer, "from") AS payer, - COUNT(*) AS tx_count, - SUM(CEIL(effective_gas_price * gas_used / 1e12) / 1e6) AS usd_paid + COUNT(*) AS tx_count FROM transactions GROUP BY 1 -ORDER BY 3 DESC; +ORDER BY 2 DESC; ``` -## 5. Exclude system transactions when measuring user activity - -Transactions where `from = 0x0000000000000000000000000000000000000000` are system-level. Include them in raw chain metrics but exclude them when computing things like active addresses, unique senders, or user-initiated volume. +## 5. Exclude system transactions from user metrics -## 6. Compute token supply from Transfer events, not Mint events +`from = 0x0000…0000` is system-level. Include in raw chain metrics, exclude when measuring users. -Genesis mints on Tempo may not emit a `Mint` event. To get accurate supply, derive it from `Transfer` events: mints have `from = 0x0000…0000`, burns have `to = 0x0000…0000`. +## 6. Compute supply from Transfer events, not Mint events -The query below derives `pathUSD` total minted, total burned, and live supply directly from `Transfer` events. - - +Genesis mints may not emit `Mint`. Derive supply from `Transfer`: mints have `from = 0x0…0`, burns have `to = 0x0…0`. Divide by `1e6` for whole tokens. -Divide each value by `1e6` to convert raw amounts to whole tokens. +```sql +SELECT + SUM(CASE WHEN "from" = '0x0000000000000000000000000000000000000000' + THEN value + WHEN "to" = '0x0000000000000000000000000000000000000000' + THEN -value + ELSE 0 END) AS supply +FROM transfer +WHERE address = '0x20c0000000000000000000000000000000000000'; +``` ## Key addresses @@ -107,24 +85,13 @@ Divide each value by `1e6` to convert raw amounts to whole tokens. | FeeManager | `0xfeec000000000000000000000000000000000000` | | Stablecoin DEX | `0xdec0000000000000000000000000000000000000` | | TIP-20 Factory | `0x20fc000000000000000000000000000000000000` | -| PathUSD | `0x20c0000000000000000000000000000000000000` | +| pathUSD | `0x20c0000000000000000000000000000000000000` | ## Networks -### Mainnet - -| | | -| --- | --- | -| Chain ID | `4217` | -| RPC | `https://rpc.tempo.xyz` | -| Explorer | `https://explore.tempo.xyz` | -| Tokenlist | `https://tokenlist.tempo.xyz/list/4217` | - -### Testnet (Moderato) - -| | | -| --- | --- | -| Chain ID | `42431` | -| RPC | `https://rpc.moderato.tempo.xyz` | -| Explorer | `https://explore.testnet.tempo.xyz` | -| Tokenlist | `https://tokenlist.tempo.xyz/list/42431` | +| | Mainnet | Testnet (Moderato) | +| --- | --- | --- | +| Chain ID | `4217` | `42431` | +| RPC | `https://rpc.tempo.xyz` | `https://rpc.moderato.tempo.xyz` | +| Explorer | `https://explore.tempo.xyz` | `https://explore.testnet.tempo.xyz` | +| Tokenlist | `https://tokenlist.tempo.xyz/list/4217` | `https://tokenlist.tempo.xyz/list/42431` | From 0f98913e8539b85bf25a8bd9b9f66e7e88dd47cc Mon Sep 17 00:00:00 2001 From: max-digi Date: Thu, 7 May 2026 19:07:37 +0100 Subject: [PATCH 5/6] docs(querying-tempo): fix column name (value -> amount), make supply interactive Amp-Thread-ID: https://ampcode.com/threads/T-019e0366-1385-70ac-8cf3-1738206b7d0e Co-authored-by: Amp --- src/pages/quickstart/querying-tempo.mdx | 29 +++++++++++++++---------- 1 file changed, 18 insertions(+), 11 deletions(-) diff --git a/src/pages/quickstart/querying-tempo.mdx b/src/pages/quickstart/querying-tempo.mdx index 83af641c..25f148c5 100644 --- a/src/pages/quickstart/querying-tempo.mdx +++ b/src/pages/quickstart/querying-tempo.mdx @@ -38,7 +38,7 @@ Divide token amounts by `1e6`. Using `1e18` gives a result 10¹² times too smal chainId={4217} title={'Recent pathUSD transfers'} signatures={["Transfer"]} - query={`SELECT block_num, "from", "to", value + query={`SELECT block_num, "from", "to", amount FROM transfer WHERE address = '0x20c0000000000000000000000000000000000000' ORDER BY block_num DESC @@ -67,16 +67,23 @@ ORDER BY 2 DESC; Genesis mints may not emit `Mint`. Derive supply from `Transfer`: mints have `from = 0x0…0`, burns have `to = 0x0…0`. Divide by `1e6` for whole tokens. -```sql -SELECT - SUM(CASE WHEN "from" = '0x0000000000000000000000000000000000000000' - THEN value - WHEN "to" = '0x0000000000000000000000000000000000000000' - THEN -value - ELSE 0 END) AS supply -FROM transfer -WHERE address = '0x20c0000000000000000000000000000000000000'; -``` + ## Key addresses From f8a1212c2840bc9c2985e76389fd5209e315a808 Mon Sep 17 00:00:00 2001 From: max-digi Date: Thu, 7 May 2026 19:11:15 +0100 Subject: [PATCH 6/6] docs(querying-tempo): revert interactive blocks to static SQL Amp-Thread-ID: https://ampcode.com/threads/T-019e0366-1385-70ac-8cf3-1738206b7d0e Co-authored-by: Amp --- src/pages/quickstart/querying-tempo.mdx | 57 +++++++++++-------------- 1 file changed, 25 insertions(+), 32 deletions(-) diff --git a/src/pages/quickstart/querying-tempo.mdx b/src/pages/quickstart/querying-tempo.mdx index 25f148c5..046efcbf 100644 --- a/src/pages/quickstart/querying-tempo.mdx +++ b/src/pages/quickstart/querying-tempo.mdx @@ -4,13 +4,11 @@ description: Write correct analytics queries for Tempo. Covers fee units, TIP-20 showOutline: 1 --- -import { IndexSupplyQuery } from '../../components/IndexSupplyQuery' - # Querying Tempo Tempo is EVM-compatible, so most query patterns you already know work here. There are a handful of differences that will silently produce wrong numbers if you carry over Ethereum assumptions. -The interactive examples run live against [Index Supply](https://www.indexsupply.net) on Tempo mainnet — edit the SQL and hit **Run Query**. Static examples use generic SQL — table and column names will vary by platform. +Examples use generic SQL — table and column names will vary by platform. ## 1. Fees are in USD, not ETH @@ -34,16 +32,14 @@ Divide token amounts by `1e6`. Using `1e18` gives a result 10¹² times too smal `tx.value` is always zero on Tempo. All token movement is in `Transfer` events. - +```sql +SELECT date_trunc('day', block_time) AS day, + token_address, + SUM(amount) / 1e6 AS volume_usd +FROM tip20_transfers +GROUP BY 1, 2 +ORDER BY 1; +``` `TransferWithMemo` (used by MPP) also emits a standard `Transfer`. Query only `Transfer` to avoid double-counting. @@ -65,25 +61,22 @@ ORDER BY 2 DESC; ## 6. Compute supply from Transfer events, not Mint events -Genesis mints may not emit `Mint`. Derive supply from `Transfer`: mints have `from = 0x0…0`, burns have `to = 0x0…0`. Divide by `1e6` for whole tokens. - - +Genesis mints may not emit `Mint`. Derive supply from `Transfer`: mints have `from = 0x0…0`, burns have `to = 0x0…0`. + +```sql +SELECT + SUM(CASE WHEN "from" = '0x0000000000000000000000000000000000000000' + THEN amount / 1e6 ELSE 0 END) AS total_minted, + SUM(CASE WHEN "to" = '0x0000000000000000000000000000000000000000' + THEN amount / 1e6 ELSE 0 END) AS total_burned, + SUM(CASE WHEN "from" = '0x0000000000000000000000000000000000000000' + THEN amount / 1e6 + WHEN "to" = '0x0000000000000000000000000000000000000000' + THEN -amount / 1e6 + ELSE 0 END) AS supply +FROM tip20_transfers +WHERE token_address = ; +``` ## Key addresses