update desc for ez_transfers; update transactions (#866)

models/descriptions/__overview__.md

@@ -34,6 +34,7 @@ There is more information on how to use dbt docs in the last section of this doc
 **Core Convenience Tables:**
 - [ez_signers](#!/model/model.solana_models.core__ez_signers)
 - [ez_events_decoded](#!/model/model.solana_models.core__ez_events_decoded)
+- [ez_transfers](#!/model/model.solana_models.core__ez_transfers)
 
 ### DeFi Tables (`Solana`.`DEFI`.`<table_name>`)
 - [ez_dex_swaps](#!/model/model.solana_models.defi__ez_dex_swaps)

models/descriptions/tables/ez_signers.md

@@ -11,10 +11,10 @@ This table contains one row per unique Solana signer (address that signs transac
 - Support analytics on user growth, retention, and protocol usage
 
 ## Important Relationships
-- Closely related to `core.fact_transactions` (for transaction context), `core.fact_events` (for event context), and `core.fact_transfers` (for transfer events)
+- Closely related to `core.fact_transactions` (for transaction context), `core.fact_events` (for event context), and `core.ez_transfers` (for transfer events)
 - Use `core.fact_transactions` to analyze transaction-level activity
 - Use `core.fact_events` for event-level context and protocol interactions
-- Use `core.fact_transfers` for asset movement and transfer analytics
+- Use `core.ez_transfers` for asset movement and transfer analytics
 - Joins with `core.fact_blocks` for block context
 
 ## Commonly-used Fields

models/descriptions/tables/ez_transfers.md

@@ -0,0 +1,32 @@
+{% docs ez_transfers %}
+
+## Description
+This table contains transfer events for Solana and SPL tokens, including pre-parsed transfer amounts, USD value, token symbol, and verification status. Each row represents a single transfer event with enriched metadata that makes analytics easier compared to the raw `core.fact_transfers` table. The model includes both SOL and token transfers with complete pricing and token metadata, supporting comprehensive analytics on asset movement, wallet activity, payment flows, and large value transfers.
+
+**This is the preferred table for transfer analytics** - it includes USD pricing, token symbols, verification status, and other enriched fields that are essential for most analytical use cases.
+
+## Key Use Cases
+- Track SOL and SPL token movements with USD valuations
+- Analyze payment flows and wallet transaction histories
+- Monitor large value transfers and whale activity with price context
+- Build DeFi protocol volume analytics with accurate USD measurements
+- Analyze token adoption and usage patterns using verified token metadata
+- Create comprehensive asset movement dashboards with pricing data
+
+## Important Relationships
+- Enhanced version of `core.fact_transfers` with additional pricing and metadata fields
+- Closely related to `core.fact_events` (for event context), `core.fact_events_inner` (for inner/CPI events), and `core.ez_events_decoded` (for decoded instruction details)
+- Uses token price data from price tables to compute USD values
+- Joins with `core.fact_transactions` for transaction context
+- Essential for DeFi analytics when combined with protocol-specific tables like `defi.ez_dex_swaps` and `defi.ez_liquidity_pool_actions`
+
+## Commonly-used Fields
+- `block_timestamp`: For time-series and transfer sequencing analysis
+- `tx_id`, `block_id`: For transaction and block context joins
+- `tx_from`, `tx_to`: For sender and recipient analysis and wallet tracking
+- `amount`, `amount_usd`: For value analysis in both token units and USD
+- `mint`, `symbol`: For token-specific analytics and filtering
+- `token_is_verified`: For filtering to verified/trusted tokens
+- `signer`: For transaction initiator analysis
+
+{% enddocs %}

models/descriptions/tables/fact_decoded_instructions.md

@@ -11,11 +11,11 @@ This table contains one row per decoded instruction on the Solana blockchain, in
 - Enable detailed event and instruction-level analytics
 
 ## Important Relationships
-- Closely related to `core.ez_events_decoded` (preferred for most analytics), `core.fact_events` (for event context), `core.fact_events_inner` (for inner/CPI events), and `core.fact_transfers` (for transfer events)
+- Closely related to `core.ez_events_decoded` (preferred for most analytics), `core.fact_events` (for event context), `core.fact_events_inner` (for inner/CPI events), and `core.ez_transfers` (for transfer events)
 - Use `core.ez_events_decoded` for most analytics use cases
 - Use `core.fact_events` for event-level context and protocol interactions
 - Use `core.fact_events_inner` for nested program calls and composability analysis
-- Use `core.fact_transfers` for asset movement and transfer analytics
+- Use `core.ez_transfers` for asset movement and transfer analytics
 - Joins with `core.fact_blocks` for block context and `core.fact_transactions` for transaction context
 
 ## Commonly-used Fields

models/descriptions/tables/fact_events.md

@@ -11,10 +11,10 @@ This table records every event emitted by on-chain Solana programs during transa
 - Downstream analytics for protocol-specific event flows and decoded instructions
 
 ## Important Relationships
-- Closely related to `core.fact_events_inner` (for inner/CPI events), `core.ez_events_decoded` (preferred for decoded instruction details), and `core.fact_transfers` (for transfer events)
+- Closely related to `core.fact_events_inner` (for inner/CPI events), `core.ez_events_decoded` (preferred for decoded instruction details), and `core.ez_transfers` (for transfer events)
 - Use `core.fact_events_inner` to analyze Cross-Program Invocations (CPIs) and nested program calls
 - Use `core.ez_events_decoded` for detailed instruction and argument analysis (if program is being decoded)
-- Use `core.fact_transfers` for asset movement and transfer analytics
+- Use `core.ez_transfers` for asset movement and transfer analytics
 - Joins with `core.fact_blocks` for block context and `core.fact_transactions` for transaction context
 
 ## Commonly-used Fields

models/descriptions/tables/fact_events_inner.md

@@ -11,10 +11,10 @@ This table records every event that occurs within inner instructions (Cross-Prog
 - Downstream analytics for protocol-specific event flows and composable DeFi/NFT protocols
 
 ## Important Relationships
-- Closely related to `core.fact_events` (for top-level events), `core.ez_events_decoded` (preferred for decoded instruction details), and `core.fact_transfers` (for transfer events)
+- Closely related to `core.fact_events` (for top-level events), `core.ez_events_decoded` (preferred for decoded instruction details), and `core.ez_transfers` (for transfer events)
 - Use `core.fact_events` for top-level program events and instruction execution
 - Use `core.ez_events_decoded` for detailed instruction and argument analysis (if program is being decoded)
-- Use `core.fact_transfers` for asset movement and transfer analytics
+- Use `core.ez_transfers` for asset movement and transfer analytics
 - Joins with `core.fact_blocks` for block context and `core.fact_transactions` for transaction context
 
 ## Commonly-used Fields

models/descriptions/tables/fact_sol_balances.md

@@ -11,10 +11,10 @@ This table contains one row per account and transaction where a native SOL (Sola
 - Enable time-series and event-based analytics on SOL balances
 
 ## Important Relationships
-- Closely related to `core.fact_token_account_owners` (for historical ownership), `core.fact_events` (for event context), and `core.fact_transfers` (for transfer events)
+- Closely related to `core.fact_token_account_owners` (for historical ownership), `core.fact_events` (for event context), and `core.ez_transfers` (for transfer events)
 - Use `core.fact_token_account_owners` to attribute balances to the correct owner
 - Use `core.fact_events` for event-level context and protocol interactions
-- Use `core.fact_transfers` for asset movement and transfer analytics
+- Use `core.ez_transfers` for asset movement and transfer analytics
 - Joins with `core.fact_blocks` for block context and `core.fact_transactions` for transaction context
 
 ## Commonly-used Fields

models/descriptions/tables/fact_stake_pool_actions.md

@@ -11,10 +11,10 @@ This table contains deposit and withdrawal actions with stake pools on the Solan
 - Support analytics on DeFi staking ecosystem growth
 
 ## Important Relationships
-- Closely related to `defi.ez_liquidity_pool_actions` (for liquidity provision), `defi.ez_dex_swaps` (for DEX activity), and `core.fact_transfers` (for token movements)
+- Closely related to `defi.ez_liquidity_pool_actions` (for liquidity provision), `defi.ez_dex_swaps` (for DEX activity), and `core.ez_transfers` (for token movements)
 - Use `defi.ez_liquidity_pool_actions` to analyze liquidity provision in staking-related pools
 - Use `defi.ez_dex_swaps` to track trading of liquid staking tokens
-- Use `core.fact_transfers` to analyze token movements related to staking
+- Use `core.ez_transfers` to analyze token movements related to staking
 - Joins with `core.fact_blocks` for block context and `core.fact_transactions` for transaction context
 
 ## Commonly-used Fields

models/descriptions/tables/fact_token_account_owners.md

@@ -11,10 +11,10 @@ This table contains one row per token account address, recording the range of bl
 - Enable time-series and event-based analytics on token account ownership
 
 ## Important Relationships
-- Closely related to `core.fact_token_balances` (for balance changes), `core.fact_sol_balances` (for SOL balances), and `core.fact_transfers` (for transfer events)
+- Closely related to `core.fact_token_balances` (for balance changes), `core.fact_sol_balances` (for SOL balances), and `core.ez_transfers` (for transfer events)
 - Use `core.fact_token_balances` to analyze token balance changes and account activity
 - Use `core.fact_sol_balances` for SOL balance analytics
-- Use `core.fact_transfers` for asset movement and transfer analytics
+- Use `core.ez_transfers` for asset movement and transfer analytics
 - Joins with `core.fact_blocks` for block context and `core.fact_transactions` for transaction context
 
 ## Commonly-used Fields

models/descriptions/tables/fact_token_balances.md

@@ -11,10 +11,10 @@ This table contains one row per account and transaction where an SPL token balan
 - Enable time-series and event-based analytics on token balances
 
 ## Important Relationships
-- Closely related to `core.fact_token_account_owners` (for historical ownership), `core.fact_events` (for event context), and `core.fact_transfers` (for transfer events)
+- Closely related to `core.fact_token_account_owners` (for historical ownership), `core.fact_events` (for event context), and `core.ez_transfers` (for transfer events)
 - Use `core.fact_token_account_owners` to attribute balances to the correct owner
 - Use `core.fact_events` for event-level context and protocol interactions
-- Use `core.fact_transfers` for asset movement and transfer analytics
+- Use `core.ez_transfers` for asset movement and transfer analytics
 - Joins with `core.fact_blocks` for block context and `core.fact_transactions` for transaction context
 
 ## Commonly-used Fields

models/descriptions/tables/fact_token_burn_actions.md

@@ -11,9 +11,9 @@ This table contains information on all token burn events on the Solana blockchai
 - Support analytics on token economics and supply dynamics
 
 ## Important Relationships
-- Closely related to `defi.fact_token_mint_actions` (for mint events), `core.fact_transfers` (for token movements), and `core.fact_token_balances` (for balance changes)
+- Closely related to `defi.fact_token_mint_actions` (for mint events), `core.ez_transfers` (for token movements), and `core.fact_token_balances` (for balance changes)
 - Use `defi.fact_token_mint_actions` to analyze token creation and supply increase
-- Use `core.fact_transfers` to track token movements before burning
+- Use `core.ez_transfers` to track token movements before burning
 - Use `core.fact_token_balances` to analyze balance changes from burning
 - Joins with `core.fact_blocks` for block context and `core.fact_transactions` for transaction context
 

models/descriptions/tables/fact_token_mint_actions.md

@@ -11,9 +11,9 @@ This table contains information on all token mint events on the Solana blockchai
 - Support analytics on token economics and supply management
 
 ## Important Relationships
-- Closely related to `defi.fact_token_burn_actions` (for burn events), `core.fact_transfers` (for token movements), and `core.fact_token_balances` (for balance changes)
+- Closely related to `defi.fact_token_burn_actions` (for burn events), `core.ez_transfers` (for token movements), and `core.fact_token_balances` (for balance changes)
 - Use `defi.fact_token_burn_actions` to analyze token destruction and supply reduction
-- Use `core.fact_transfers` to track token movements after minting
+- Use `core.ez_transfers` to track token movements after minting
 - Use `core.fact_token_balances` to analyze balance changes from minting
 - Joins with `core.fact_blocks` for block context and `core.fact_transactions` for transaction context
 

models/descriptions/tables/fact_transactions.md

@@ -3,30 +3,63 @@
 ## Description
 This table contains one record per transaction on the Solana blockchain, capturing high-level transaction metadata as recorded on-chain. Each record includes block timestamp, transaction identifiers, account and token balance changes, program instructions, and execution metadata for every transaction processed on Solana mainnet. The table covers all finalized transactions, both successful and failed, and is updated as new blocks are processed. Data is sourced from on-chain transaction logs and normalized for analytics.
 
+**IMPORTANT: This is raw transaction data. For most analytics, use the specialized curated tables instead of querying this large table directly.** Transaction components are broken down and extracted into purpose-built tables that are optimized for specific analytical use cases and much easier to work with.
+
 ## Key Use Cases
-- Transaction-level analytics and protocol usage tracking
-- Fee analysis and cost monitoring for Solana transactions
-- Wallet and account activity analysis
-- Token and asset movement tracking
-- Program and instruction usage statistics
+**For most of these use cases, prefer the specialized curated tables listed in "Important Relationships" below:**
+
+- Transaction-level metadata and high-level transaction analytics
+- Fee analysis and cost monitoring for Solana transactions (use `fee` and `succeeded` fields)
 - Success/failure rate analysis for transactions
-- Building time-series dashboards for network activity
+- Basic wallet and signer analysis (for detailed analysis, use `core.ez_signers`)
+- Building time-series dashboards for network activity at the transaction level
+
+**Use curated tables for these common analyses instead:**
+- **Token and asset movement**: Use `core.ez_transfers` (includes USD values, token symbols)
+- **Program and instruction analysis**: Use `core.fact_events` and `core.fact_events_inner`
+- **Decoded instruction details**: Use `core.ez_events_decoded`
+- **Token balance changes**: Use `core.fact_token_balances`
 
 ## Important Relationships
-- Each transaction is linked to its corresponding block in `core.fact_blocks` via the `block_id` field
-- Used as a source for `core.fact_events`, `core.fact_transfers`, and other gold-level models for event, transfer, and program analytics
-- Joins with `core.fact_blocks` for block-level context and with `core.fact_token_balances` for token movement analysis
-- Downstream models may use `tx_id` to join with logs, events, and decoded instructions tables
-- Many curated and derived tables are built from this model for specialized analytics. For example, use `core.fact_events` and `core.fact_events_inner` for instruction/event-level analysis, or `core.fact_transfers` for transfer analytics. When possible, prefer these curated tables over querying the large `core.fact_transactions` table directly, as they are optimized for specific analytical use cases.
+**STRONGLY PREFER these curated tables over raw transaction data:**
+
+**For instruction and program analysis:**
+- `core.fact_events` - Parsed instruction events and program interactions
+- `core.fact_events_inner` - Inner/CPI instruction events for composability analysis
+- `core.ez_events_decoded` - Human-readable decoded instruction details with arguments
+
+**For transfer and asset movement analysis:**
+- `core.ez_transfers` - Token transfers with USD values, symbols, and verification status
+- `core.fact_token_balances` - Token balance changes over time
+
+**For wallet and signer analysis:**
+- `core.ez_signers` - Signer addresses extracted and enriched
+
+**Raw transaction relationships:**
+- Each transaction links to `core.fact_blocks` via `block_id` for block context
+- All curated tables use `tx_id` to link back to transaction context when needed
+- Raw fields like `instructions`, `inner_instructions`, and `program_ids` are parsed into the specialized tables above
+
+**Analysis Guidance:**
+- **DO NOT** parse `instructions` or `inner_instructions` arrays directly - use `core.fact_events` and `core.fact_events_inner`
+- **DO NOT** analyze program IDs from raw data - use the events tables for program interaction analysis  
+- **DO NOT** extract transfer data manually - use `core.ez_transfers` for all transfer analytics
+- **DO NOT** query this large table for routine analytics - it's optimized as a source table, not for direct analysis
 
 ## Commonly-used Fields
-- `tx_id`: Unique identifier for each transaction, used for joins and traceability
-- `block_id` and `block_timestamp`: For time-series and block-level analysis
-- `signers`: Key for wallet attribution and user activity analysis
-- `fee`: For cost and economic analysis
-- `succeeded`: Indicates transaction success/failure
-- `account_keys`, `pre_balances`, `post_balances`: For account-level balance change analysis
-- `instructions`, `inner_instructions`: For program and protocol usage analytics
-- `log_messages`: For debugging and advanced protocol analysis
+**When using this table directly (discouraged for most use cases):**
+
+- `tx_id`: Unique identifier for joins with curated tables and traceability
+- `block_id` and `block_timestamp`: For time-series and block-level context
+- `fee`: For transaction cost analysis
+- `succeeded`: For transaction success/failure rate analysis
+- `signers`: For basic signer analysis (prefer `core.ez_signers` for detailed analysis)
+
+**Fields to avoid parsing directly (use curated tables instead):**
+- `instructions`, `inner_instructions`: Use `core.fact_events` and `core.fact_events_inner` instead
+- `account_keys`, `pre_balances`, `post_balances`: Use `core.ez_transfers` or `core.fact_token_balances` instead
+- `log_messages`: Use `core.ez_events_decoded` for parsed program logs
+
+**Reminder: For most analytics, query the specialized curated tables that extract and enrich these raw fields rather than parsing them manually from this table.**
 
 {% enddocs %} 

models/descriptions/tables/fact_transfers.md

@@ -3,6 +3,8 @@
 ## Description
 This table contains one row per transfer event involving native SOL or SPL tokens on the Solana blockchain. Each row records the details of a single transfer, including block and transaction identifiers, sender and recipient addresses, transferred amount, and token mint. The model includes both SOL and token transfers, supporting analytics on asset movement, user activity, and protocol flows. Data is updated as new blocks are processed, and each row represents a unique transfer event within a transaction.
 
+**Note: For most transfer analytics, prefer using `core.ez_transfers` which includes additional enriched fields like USD values, token symbols, and verification status that make analytics easier.**
+
 ## Key Use Cases
 - Track SOL or SPL token movements between accounts
 - Analyze payment flows and wallet transaction histories
@@ -11,6 +13,7 @@ This table contains one row per transfer event involving native SOL or SPL token
 - Simplify asset movement analysis compared to parsing raw instructions
 
 ## Important Relationships
+- **Prefer `core.ez_transfers` for most transfer analytics** - enriched version with USD values, token symbols, and verification status
 - Closely related to `core.fact_events` (for event context), `core.fact_events_inner` (for inner/CPI events), and `core.ez_events_decoded` (preferred for decoded instruction details)
 - Use `core.fact_events` for event-level context and protocol interactions
 - Use `core.fact_events_inner` for nested program calls and composability analysis

models/gold/core/core__ez_transfers.yml

@@ -1,8 +1,7 @@
 version: 2
 models:
   - name: core__ez_transfers
-    description: |-
-      Contains transfer events for Solana and SPL tokens, including pre-parsed transfer amounts, USD value, token symbol, and verification status. This table is best for analytics on asset movement, wallet activity, payment flows, and large value transfers. 
+    description: "{{ doc('ez_transfers') }}" 
     columns:
       - name: BLOCK_TIMESTAMP
         description: "{{ doc('block_timestamp') }}"