flip/fsc-evm
1
0
Fork 0
mirror of https://github.com/FlipsideCrypto/fsc-evm.git synced 2026-02-06 17:36:56 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

gold docs

Browse Source
This commit is contained in:
drethereum 2025-07-14 13:43:23 -06:00
parent db0d237adc
commit 015bbcf28b
4 changed files with 580 additions and 2 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

28
models/balances_package/gold/balances__ez_balances_erc20.yml
View File

@ -1,30 +1,56 @@
version: 2
models:
- name: balances__ez_balances_erc20
description: '{{ doc("ez_balances_erc20_table_doc") }}'
columns:
- name: BLOCK_NUMBER
description: '{{ doc("general_block_number") }}'
- name: BLOCK_TIMESTAMP
description: '{{ doc("general_block_timestamp") }}'
- name: TX_POSITION
description: '{{ doc("general_tx_position") }}'
- name: TX_HASH
description: '{{ doc("general_tx_hash") }}'
- name: TX_SUCCEEDED
description: '{{ doc("ez_balances_erc20_tx_succeeded") }}'
- name: CONTRACT_ADDRESS
description: '{{ doc("ez_balances_erc20_contract_address") }}'
- name: DECIMALS
description: '{{ doc("ez_balances_erc20_decimals") }}'
- name: SYMBOL
description: '{{ doc("ez_balances_erc20_symbol") }}'
- name: SLOT_NUMBER
description: '{{ doc("ez_balances_erc20_slot_number") }}'
- name: ADDRESS
description: '{{ doc("ez_balances_erc20_address") }}'
- name: PRE_BALANCE_HEX
description: '{{ doc("ez_balances_erc20_pre_balance_hex") }}'
- name: PRE_BALANCE_RAW
description: '{{ doc("ez_balances_erc20_pre_balance_raw") }}'
- name: PRE_BALANCE_PRECISE
description: '{{ doc("ez_balances_erc20_pre_balance_precise") }}'
- name: PRE_BALANCE
description: '{{ doc("ez_balances_erc20_pre_balance") }}'
- name: PRE_BALANCE_USD
description: '{{ doc("ez_balances_erc20_pre_balance_usd") }}'
- name: POST_BALANCE_HEX
description: '{{ doc("ez_balances_erc20_post_balance_hex") }}'
- name: POST_BALANCE_RAW
description: '{{ doc("ez_balances_erc20_post_balance_raw") }}'
- name: POST_BALANCE_PRECISE
description: '{{ doc("ez_balances_erc20_post_balance_precise") }}'
- name: POST_BALANCE
description: '{{ doc("ez_balances_erc20_post_balance") }}'
- name: POST_BALANCE_USD
description: '{{ doc("ez_balances_erc20_post_balance_usd") }}'
- name: NET_BALANCE_RAW
description: '{{ doc("ez_balances_erc20_net_balance_raw") }}'
- name: NET_BALANCE
description: '{{ doc("ez_balances_erc20_net_balance") }}'
- name: EZ_BALANCES_ERC20_ID
description: '{{ doc("general_pk") }}'
- name: INSERTED_TIMESTAMP
- name: MODIFIED_TIMESTAMP
description: '{{ doc("general_inserted_timestamp") }}'
- name: MODIFIED_TIMESTAMP
description: '{{ doc("general_modified_timestamp") }}'

26
models/balances_package/gold/balances__ez_balances_native.yml
View File

@ -1,28 +1,52 @@
version: 2
models:
- name: balances__ez_balances_native
description: '{{ doc("ez_balances_native_table_doc") }}'
columns:
- name: BLOCK_NUMBER
description: '{{ doc("general_block_number") }}'
- name: BLOCK_TIMESTAMP
description: '{{ doc("general_block_timestamp") }}'
- name: TX_POSITION
description: '{{ doc("general_tx_position") }}'
- name: TX_HASH
description: '{{ doc("general_tx_hash") }}'
- name: ADDRESS
description: '{{ doc("ez_balances_native_address") }}'
- name: PRE_NONCE
description: '{{ doc("ez_balances_native_pre_nonce") }}'
- name: PRE_BALANCE_HEX
description: '{{ doc("ez_balances_native_pre_balance_hex") }}'
- name: PRE_BALANCE_RAW
description: '{{ doc("ez_balances_native_pre_balance_raw") }}'
- name: PRE_BALANCE_PRECISE
description: '{{ doc("ez_balances_native_pre_balance_precise") }}'
- name: PRE_BALANCE
description: '{{ doc("ez_balances_native_pre_balance") }}'
- name: PRE_BALANCE_USD
description: '{{ doc("ez_balances_native_pre_balance_usd") }}'
- name: POST_NONCE
description: '{{ doc("ez_balances_native_post_nonce") }}'
- name: POST_BALANCE_HEX
description: '{{ doc("ez_balances_native_post_balance_hex") }}'
- name: POST_BALANCE_RAW
description: '{{ doc("ez_balances_native_post_balance_raw") }}'
- name: POST_BALANCE_PRECISE
description: '{{ doc("ez_balances_native_post_balance_precise") }}'
- name: POST_BALANCE
description: '{{ doc("ez_balances_native_post_balance") }}'
- name: POST_BALANCE_USD
description: '{{ doc("ez_balances_native_post_balance_usd") }}'
- name: NET_BALANCE_RAW
description: '{{ doc("ez_balances_native_net_balance_raw") }}'
- name: NET_BALANCE
description: '{{ doc("ez_balances_native_net_balance") }}'
- name: DECIMALS
description: '{{ doc("ez_balances_native_decimals") }}'
- name: EZ_BALANCES_NATIVE_ID
description: '{{ doc("general_pk") }}'
- name: INSERTED_TIMESTAMP
- name: MODIFIED_TIMESTAMP
description: '{{ doc("general_inserted_timestamp") }}'
- name: MODIFIED_TIMESTAMP
description: '{{ doc("general_modified_timestamp") }}'

263
models/doc_descriptions/balances/ez_balances_erc20.md Normal file
View File

@ -0,0 +1,263 @@
{% docs ez_balances_erc20_table_doc %}
## What
This table tracks ERC20 token balance changes at the transaction level by capturing pre- and post-transaction states from contract storage slots. It uses state tracer data to show exactly how each address's token balance changed during transaction execution for verified ERC20 tokens, including decimal adjustments and USD valuations, where available, for comprehensive token balance analysis. This data set includes both successful and failed transactions, as state may change regardless.
## Key Use Cases
- Tracking ERC20 token balance changes at transaction granularity
- Analyzing token balance impacts of DeFi interactions and trades
- Monitoring large token balance changes and whale activity
- Calculating precise token balance evolution over time
- Identifying addresses with significant token holdings
- Debugging smart contract effects on token balances
- Analyzing token distribution and concentration metrics
## Important Relationships
- **Join with fact_transactions**: Use `tx_hash` for transaction context
- **Join with fact_blocks**: Use `block_number` for block metadata
- **Join with dim_labels**: Use `address` for entity identification
- **Join with dim_contracts**: Use `contract_address` for token contract details
- **Join with ez_token_transfers**: Compare balance changes to transfer events
- **Join with ez_prices_hourly**: USD valuations already included but can be refreshed
- **Join with ez_balances_native**: Compare with native token balance changes
## Commonly-used Fields
- `address`: The account whose token balance changed
- `contract_address`: The ERC20 token contract address
- `symbol`: Token symbol (USDC, WETH, etc.)
- `pre_balance`: Token balance before the transaction
- `post_balance`: Token balance after the transaction
- `net_balance`: The change in token balance (post - pre)
- `pre_balance_usd` / `post_balance_usd`: USD values at time of transaction
- `decimals`: Number of decimal places for the token
- `tx_hash`: Transaction that caused the balance change
## Sample queries
**Daily ERC20 Token Balance Changes**
```sql
SELECT
DATE_TRUNC('day', block_timestamp) AS day,
symbol,
COUNT(*) AS balance_changes,
COUNT(DISTINCT address) AS unique_holders,
SUM(ABS(net_balance)) AS total_balance_moved,
SUM(net_balance) AS net_balance_change
FROM <blockchain_name>.balances.ez_balances_erc20
WHERE block_timestamp >= CURRENT_DATE - 30
AND net_balance != 0
AND symbol IS NOT NULL
GROUP BY 1, 2
ORDER BY 1 DESC, total_balance_moved DESC;
```
**Token Holder Balance Evolution**
```sql
-- Track how a specific address's token balances changed over time
SELECT
block_timestamp,
tx_hash,
contract_address,
symbol,
pre_balance,
post_balance,
net_balance,
pre_balance_usd,
post_balance_usd
FROM <blockchain_name>.balances.ez_balances_erc20
WHERE address = LOWER('0x1234567890123456789012345678901234567890')
AND block_timestamp >= CURRENT_DATE - 30
AND net_balance != 0
ORDER BY block_timestamp DESC;
```
**DeFi Protocol Token Impact Analysis**
```sql
-- Analyze how DeFi interactions affect token balances
SELECT
t.to_address AS protocol_address,
b.symbol,
COUNT(*) AS balance_changes,
COUNT(DISTINCT b.address) AS unique_users,
SUM(CASE WHEN b.net_balance > 0 THEN b.net_balance ELSE 0 END) AS total_gains,
SUM(CASE WHEN b.net_balance < 0 THEN ABS(b.net_balance) ELSE 0 END) AS total_losses
FROM <blockchain_name>.balances.ez_balances_erc20 b
JOIN <blockchain_name>.core.fact_transactions t USING (tx_hash)
WHERE b.net_balance != 0
AND t.to_address IN (SELECT address FROM dim_contracts)
AND b.block_timestamp >= CURRENT_DATE - 7
AND b.symbol IS NOT NULL
GROUP BY 1, 2
HAVING COUNT(*) > 10
ORDER BY total_gains + total_losses DESC
LIMIT 50;
```
**Token Balance Distribution by Token**
```sql
-- Analyze current token holders and their balances
SELECT
contract_address,
symbol,
COUNT(DISTINCT address) AS holder_count,
SUM(post_balance) AS total_supply_tracked,
AVG(post_balance) AS avg_balance,
MAX(post_balance) AS max_balance
FROM <blockchain_name>.balances.ez_balances_erc20
WHERE block_timestamp >= CURRENT_DATE - 1
AND post_balance > 0
AND symbol IS NOT NULL
GROUP BY 1, 2
ORDER BY holder_count DESC
LIMIT 50;
```
{% enddocs %}
{% docs ez_balances_erc20_contract_address %}
The ERC20 token contract address whose balance changed in this transaction.
Example: '0xa0b86a33e6eb88b4d81b15e4e60c8a5b776e3b7a'
{% enddocs %}
{% docs ez_balances_erc20_symbol %}
The token symbol for the ERC20 token.
Example: 'USDC'
{% enddocs %}
{% docs ez_balances_erc20_address %}
The account address whose token balance changed in this transaction.
Example: '0x1234567890123456789012345678901234567890'
{% enddocs %}
{% docs ez_balances_erc20_slot_number %}
The storage slot number used to track balances for this ERC20 token contract.
Example: 0
{% enddocs %}
{% docs ez_balances_erc20_decimals %}
Number of decimal places for the token, used for proper decimal adjustment.
Example: 6
{% enddocs %}
{% docs ez_balances_erc20_tx_succeeded %}
Boolean indicator of whether the transaction that caused this balance change was successful.
Example: true
{% enddocs %}
{% docs ez_balances_erc20_pre_balance %}
Token balance before the transaction execution, decimal adjusted to standard units.
Example: 1000.50
{% enddocs %}
{% docs ez_balances_erc20_post_balance %}
Token balance after the transaction execution, decimal adjusted to standard units.
Example: 750.25
{% enddocs %}
{% docs ez_balances_erc20_net_balance %}
The change in token balance (post_balance - pre_balance).
Example: -250.25
{% enddocs %}
{% docs ez_balances_erc20_pre_balance_usd %}
USD value of the pre-transaction token balance at the time of the transaction.
Example: 1000.50
{% enddocs %}
{% docs ez_balances_erc20_post_balance_usd %}
USD value of the post-transaction token balance at the time of the transaction.
Example: 750.25
{% enddocs %}
{% docs ez_balances_erc20_pre_balance_precise %}
Token balance before transaction, decimal adjusted, returned as a string to preserve precision.
Example: '1000.500000'
{% enddocs %}
{% docs ez_balances_erc20_post_balance_precise %}
Token balance after transaction, decimal adjusted, returned as a string to preserve precision.
Example: '750.250000'
{% enddocs %}
{% docs ez_balances_erc20_pre_balance_raw %}
Token balance before transaction in smallest unit, no decimal adjustment.
Example: 1000500000
{% enddocs %}
{% docs ez_balances_erc20_post_balance_raw %}
Token balance after transaction in smallest unit, no decimal adjustment.
Example: 750250000
{% enddocs %}
{% docs ez_balances_erc20_net_balance_raw %}
The change in token balance in smallest unit.
Example: -250250000
{% enddocs %}
{% docs ez_balances_erc20_pre_balance_hex %}
Hexadecimal representation of the pre-transaction balance as stored in the contract's storage slot.
Example: '0x3b9aca00'
{% enddocs %}
{% docs ez_balances_erc20_post_balance_hex %}
Hexadecimal representation of the post-transaction balance as stored in the contract's storage slot.
Example: '0x2cb417800'
{% enddocs %}

265
models/doc_descriptions/balances/ez_balances_native.md Normal file
View File

@ -0,0 +1,265 @@
{% docs ez_balances_native_table_doc %}
## What
This table tracks native asset balance changes (ETH, AVAX, BNB, etc.) at the transaction level by capturing pre- and post-transaction states. It uses state tracer data to show exactly how each address's native asset balance changed during transaction execution, including decimal adjustments and USD valuations, where available, for comprehensive balance analysis. This data set includes both successful and failed transactions, as state may change regardless.
## Key Use Cases
- Tracking native asset balance changes at transaction granularity
- Analyzing balance impacts of smart contract interactions
- Monitoring large balance changes and whale activity
- Calculating precise balance evolution over time
- Identifying addresses with significant native asset holdings
- Debugging transaction effects on account balances
## Important Relationships
- **Join with fact_transactions**: Use `tx_hash` for transaction context
- **Join with fact_blocks**: Use `block_number` for block metadata
- **Join with dim_labels**: Use `address` for entity identification
- **Join with ez_native_transfers**: Compare balance changes to transfer amounts
- **Join with ez_prices_hourly**: USD valuations already included but can be refreshed
## Commonly-used Fields
- `address`: The account whose balance changed
- `pre_balance`: Native asset balance before the transaction
- `post_balance`: Native asset balance after the transaction
- `net_balance`: The change in balance (post - pre)
- `pre_balance_usd` / `post_balance_usd`: USD values at time of transaction
- `tx_hash`: Transaction that caused the balance change
- `block_timestamp`: When the balance change occurred
## Sample queries
**Daily Native Asset Balance Changes**
```sql
SELECT
DATE_TRUNC('day', block_timestamp) AS day,
COUNT(*) AS balance_changes,
COUNT(DISTINCT address) AS unique_addresses,
SUM(ABS(net_balance)) AS total_balance_moved,
SUM(CASE WHEN net_balance > 0 THEN net_balance ELSE 0 END) AS total_increases,
SUM(CASE WHEN net_balance < 0 THEN ABS(net_balance) ELSE 0 END) AS total_decreases
FROM <blockchain_name>.balances.ez_balances_native
WHERE block_timestamp >= CURRENT_DATE - 30
AND net_balance != 0
GROUP BY 1
ORDER BY 1 DESC;
```
**Address Balance Evolution**
```sql
-- Track how a specific address's balance changed over time
SELECT
block_timestamp,
tx_hash,
pre_balance,
post_balance,
net_balance,
pre_balance_usd,
post_balance_usd,
SUM(net_balance) OVER (
PARTITION BY address
ORDER BY block_number, tx_position
ROWS UNBOUNDED PRECEDING
) AS running_balance_change
FROM <blockchain_name>.balances.ez_balances_native
WHERE address = LOWER('0x1234567890123456789012345678901234567890')
AND block_timestamp >= CURRENT_DATE - 30
ORDER BY block_timestamp DESC;
```
**Smart Contract Balance Impact Analysis**
```sql
-- Analyze how smart contract interactions affect user balances
WITH contract_interactions AS (
SELECT
b.address,
b.tx_hash,
b.net_balance,
b.block_timestamp,
t.to_address AS contract_interacted
FROM <blockchain_name>.balances.ez_balances_native b
JOIN <blockchain_name>.core.fact_transactions t USING (tx_hash)
WHERE b.net_balance != 0
AND t.to_address IN (SELECT address FROM dim_contracts)
AND b.block_timestamp >= CURRENT_DATE - 7
)
SELECT
contract_interacted,
dc.name AS contract_name,
COUNT(*) AS balance_changes,
COUNT(DISTINCT address) AS unique_users,
SUM(CASE WHEN net_balance > 0 THEN net_balance ELSE 0 END) AS total_gains,
SUM(CASE WHEN net_balance < 0 THEN ABS(net_balance) ELSE 0 END) AS total_losses,
AVG(ABS(net_balance)) AS avg_balance_change
FROM contract_interactions c
LEFT JOIN <blockchain_name>.core.dim_contracts dc ON c.contract_interacted = dc.address
GROUP BY 1, 2
HAVING COUNT(*) > 10
ORDER BY total_gains + total_losses DESC
LIMIT 50;
```
**Balance Change Distribution**
```sql
-- Analyze the distribution of balance changes by magnitude
SELECT
CASE
WHEN ABS(net_balance) < 0.01 THEN 'Dust (<0.01)'
WHEN ABS(net_balance) < 0.1 THEN 'Small (0.01-0.1)'
WHEN ABS(net_balance) < 1 THEN 'Medium (0.1-1)'
WHEN ABS(net_balance) < 10 THEN 'Large (1-10)'
WHEN ABS(net_balance) < 100 THEN 'Very Large (10-100)'
ELSE 'Whale (100+)'
END AS balance_change_category,
COUNT(*) AS change_count,
COUNT(DISTINCT address) AS unique_addresses,
SUM(ABS(net_balance)) AS total_volume,
AVG(ABS(net_balance)) AS avg_magnitude
FROM <blockchain_name>.balances.ez_balances_native
WHERE block_timestamp >= CURRENT_DATE - 1
AND net_balance != 0
GROUP BY 1
ORDER BY
CASE balance_change_category
WHEN 'Dust (<0.01)' THEN 1
WHEN 'Small (0.01-0.1)' THEN 2
WHEN 'Medium (0.1-1)' THEN 3
WHEN 'Large (1-10)' THEN 4
WHEN 'Very Large (10-100)' THEN 5
WHEN 'Whale (100+)' THEN 6
END;
```
{% enddocs %}
{% docs ez_balances_native_address %}
The address whose native asset balance changed in this transaction.
Example: '0x1234567890123456789012345678901234567890'
{% enddocs %}
{% docs ez_balances_native_pre_balance %}
Native asset balance before the transaction execution, decimal adjusted to standard units.
Example: 15.75
{% enddocs %}
{% docs ez_balances_native_post_balance %}
Native asset balance after the transaction execution, decimal adjusted to standard units.
Example: 12.25
{% enddocs %}
{% docs ez_balances_native_net_balance %}
The change in native asset balance (post_balance - pre_balance).
Example: -3.5
{% enddocs %}
{% docs ez_balances_native_pre_balance_usd %}
USD value of the pre-transaction balance at the time of the transaction.
Example: 39375.00
{% enddocs %}
{% docs ez_balances_native_post_balance_usd %}
USD value of the post-transaction balance at the time of the transaction.
Example: 30625.00
{% enddocs %}
{% docs ez_balances_native_pre_balance_precise %}
Native asset balance before transaction, decimal adjusted, returned as a string to preserve precision.
Example: '15.750000000000000000'
{% enddocs %}
{% docs ez_balances_native_post_balance_precise %}
Native asset balance after transaction, decimal adjusted, returned as a string to preserve precision.
Example: '12.250000000000000000'
{% enddocs %}
{% docs ez_balances_native_pre_balance_raw %}
Native asset balance before transaction in smallest unit (Wei), no decimal adjustment.
Example: 15750000000000000000
{% enddocs %}
{% docs ez_balances_native_post_balance_raw %}
Native asset balance after transaction in smallest unit (Wei), no decimal adjustment.
Example: 12250000000000000000
{% enddocs %}
{% docs ez_balances_native_net_balance_raw %}
The change in native asset balance in smallest unit (Wei).
Example: -3500000000000000000
{% enddocs %}
{% docs ez_balances_native_pre_balance_hex %}
Hexadecimal representation of the pre-transaction balance as returned by the blockchain RPC.
Example: '0xda475abf0000000'
{% enddocs %}
{% docs ez_balances_native_post_balance_hex %}
Hexadecimal representation of the post-transaction balance as returned by the blockchain RPC.
Example: '0xaa87bee5380000'
{% enddocs %}
{% docs ez_balances_native_pre_nonce %}
Account nonce value before the transaction execution.
Example: 42
{% enddocs %}
{% docs ez_balances_native_post_nonce %}
Account nonce value after the transaction execution. May be null.
Example: 43
{% enddocs %}
{% docs ez_balances_native_decimals %}
Number of decimal places for the native asset. Typically 18 for native assets.
Example: 18
{% enddocs %}