An 6390/llm context descriptions 2 (#859)

* update defi table desc

* complete defi table update

* move col desc to folder; add nft docs

* cleanup

models/descriptions/bridge/bridge_activity.md

@@ -1,6 +1,31 @@
 {% docs bridge_ez_table_doc %}
 
-A comprehensive convenience table holding blockchain and platform specific bridge activity on Wormhole, DeBridge and Mayan Finance. This table also includes prices and token symbols, where available. 
+## Description
+This table provides a comprehensive view of cross-chain bridge activity on Solana, capturing token transfers via major protocols including Wormhole, DeBridge, and Mayan Finance. It standardizes inbound and outbound bridge transactions, includes protocol/platform identification, and enriches each event with USD pricing and token metadata where available. Each row represents a single bridge transaction, supporting analytics on cross-chain liquidity flows, protocol usage, and multi-chain DeFi activity.
+
+## Key Use Cases
+- Analyze cross-chain liquidity flows and bridge protocol adoption
+- Track token movements between Solana and other blockchains
+- Study user behavior and protocol usage patterns for bridging
+- Monitor USD-denominated bridge flows and capital movement
+- Support analytics on multi-chain DeFi ecosystem growth and integration
+
+## Important Relationships
+- Closely related to `defi.fact_bridge_activity` (raw bridge events), `defi.ez_liquidity_pool_actions` (for liquidity flows after bridging), and `defi.ez_dex_swaps` (for DEX activity of bridged tokens)
+- Use `defi.fact_bridge_activity` for protocol-level bridge event details
+- Use `defi.ez_liquidity_pool_actions` to analyze liquidity provision/removal after bridging
+- Use `defi.ez_dex_swaps` to track trading activity of tokens post-bridge
+- `core.fact_transactions` for transaction context
+
+## Commonly-used Fields
+- `block_timestamp`: For time-series and bridge flow analysis
+- `platform`: For protocol identification (Wormhole, DeBridge, Mayan, etc.)
+- `direction`: For filtering inbound vs outbound transfers
+- `source_chain`, `destination_chain`: For cross-chain analytics
+- `source_address`, `destination_address`: For user and address-level analysis
+- `amount`, `amount_usd`: For value and USD-denominated analytics
+- `mint`, `symbol`, `token_is_verified`: For token and asset analytics
+- `succeeded`: For transaction success analysis
 
 {% enddocs %}
 

models/descriptions/burn_amount.md

@@ -1,5 +0,0 @@
-{% docs burn_amount %}
-
-The number of tokens burned during an event
-
-{% enddocs %}

models/descriptions/columns/aggregator_program_id.md

@@ -0,0 +1,10 @@
+{% docs aggregator_program_id %}
+
+The program ID of the aggregator (e.g., Jupiter) that orchestrated the multi-hop swap route. This field identifies the aggregator responsible for routing the swap across multiple DEXes.
+
+- **Data type:** STRING (base58 Solana program address)
+- **Business context:** Used to identify the aggregator protocol that coordinated the swap route.
+- **Analytics use cases:** Aggregator usage analysis, route optimization studies, and protocol adoption tracking.
+- **Example:** 'JUP4Fb2cqiRUcaTHdrPC8h2gNsA2ETXiPDD33WcGuJB'
+
+{% enddocs %} 

models/descriptions/columns/authority.md

@@ -0,0 +1,10 @@
+{% docs authority %}
+
+The address of the account that has authority over the NFT mint. This field identifies who can perform administrative actions on the NFT, such as minting additional editions or updating metadata.
+
+- **Data type:** STRING (Solana address, e.g., '9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM')
+- **Business context:** Used to track NFT governance, edition minting, and authority changes.
+- **Analytics use cases:** Authority change tracking, edition minting analysis, and NFT governance studies.
+- **Example:** '9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM'
+
+{% enddocs %} 

models/descriptions/columns/bridge_user_address.md

@@ -0,0 +1,10 @@
+{% docs bridge_user_address %}
+
+The Solana address that is receiving or sending bridged tokens. This field identifies the user involved in the cross-chain transfer.
+
+- **Data type:** STRING (base58 Solana address)
+- **Business context:** Used to track user bridge activity, analyze bridge user behavior, and identify bridge power users.
+- **Analytics use cases:** User bridge activity analysis, whale tracking, and bridge adoption studies.
+- **Example:** '4Nd1mYw4r...'
+
+{% enddocs %} 

models/descriptions/columns/burn_amount.md

@@ -0,0 +1,10 @@
+{% docs burn_amount %}
+
+The amount of tokens being burned in the transaction, denominated in the token's smallest unit (e.g., lamports for SOL, or the base unit for SPL tokens). This field enables token supply analysis and burn tracking.
+
+- **Data type:** NUMBER (integer, token's smallest unit)
+- **Business context:** Used to track token burns, analyze token supply changes, and measure deflationary pressure.
+- **Analytics use cases:** Token supply analysis, burn rate tracking, and deflationary token studies.
+- **Example:** For SOL, 1 SOL = 1,000,000,000 lamports; a value of `1000000000` means 1 SOL burned.
+
+{% enddocs %}

models/descriptions/columns/burn_authority.md

@@ -0,0 +1,10 @@
+{% docs burn_authority %}
+
+The account address that has authority to confirm the burn event. This field identifies the entity responsible for authorizing the token burn.
+
+- **Data type:** STRING (base58 Solana address)
+- **Business context:** Used to track burn authorities, analyze burn patterns, and identify centralized burn controls.
+- **Analytics use cases:** Burn authority analysis, centralized vs decentralized burn studies, and token governance tracking.
+- **Example:** '4Nd1mYw4r...'
+
+{% enddocs %} 

models/descriptions/columns/collection_id.md

@@ -0,0 +1,10 @@
+{% docs collection_id %}
+
+The unique address identifier for the NFT collection. This field provides a blockchain-level identifier for grouping NFTs into collections and enables collection-level analytics and tracking.
+
+- **Data type:** STRING (Solana address, e.g., 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v')
+- **Business context:** Used for precise collection grouping, analytics, and to join with other collection-level data.
+- **Analytics use cases:** Collection-level aggregation, cross-collection comparisons, and collection membership queries.
+- **Example:** 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v'
+
+{% enddocs %}

models/descriptions/columns/creators.md

@@ -0,0 +1,10 @@
+{% docs creators %}
+
+A JSON array containing the creator addresses and their associated royalty percentages for the NFT. This field tracks who created the NFT and what percentage of sales they receive as royalties.
+
+- **Data type:** ARRAY of STRUCTS (e.g., [{"address": "...", "share": 50}])
+- **Business context:** Used for royalty attribution, creator analytics, and revenue distribution.
+- **Analytics use cases:** Creator earnings analysis, royalty flow tracking, and multi-creator attribution studies.
+- **Example:** [{"address": "9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM", "share": 50}]
+
+{% enddocs %} 

models/descriptions/columns/currency_address.md

@@ -0,0 +1,10 @@
+{% docs currency_address %}
+
+The address of the token used to pay for the NFT transaction. This field identifies which cryptocurrency or token was used as payment, enabling analysis of payment preferences and market dynamics.
+
+- **Data type:** STRING (Solana address, e.g., 'So11111111111111111111111111111111111111112' for SOL, 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v' for USDC)
+- **Business context:** Used to identify the payment asset for NFT sales and mints, analyze payment trends, and support cross-token analytics.
+- **Analytics use cases:** Payment token flow analysis, market share by token, cross-currency price comparisons, and filtering NFT sales by payment asset.
+- **Example:** 'So11111111111111111111111111111111111111112' (SOL)
+
+{% enddocs %} 

models/descriptions/columns/currency_symbol.md

@@ -0,0 +1,10 @@
+{% docs currency_symbol %}
+
+The symbol of the token used to pay for the NFT transaction. This field provides a human-readable identifier for the payment currency, making it easier to understand and analyze payment patterns.
+
+- **Data type:** STRING (e.g., 'SOL', 'USDC', 'USDT')
+- **Business context:** Used for user-friendly display, filtering, and grouping of NFT sales and mints by payment token.
+- **Analytics use cases:** Market share by token symbol, user preference analysis, and reporting on payment trends.
+- **Example:** 'SOL'
+
+{% enddocs %} 

models/descriptions/columns/dca_requester.md

@@ -0,0 +1,10 @@
+{% docs dca_requester %}
+
+The original address that requested the DCA (Dollar Cost Averaging) swap. This field identifies the user who initiated the DCA order, enabling user-level DCA analytics.
+
+- **Data type:** STRING (base58 Solana address, NULL if not a DCA swap)
+- **Business context:** Used to track DCA users, analyze DCA user behavior, and measure DCA feature adoption at the user level.
+- **Analytics use cases:** DCA user segmentation, user behavior analysis, and Jupiter product adoption studies.
+- **Example:** '4Nd1mYw4r...'
+
+{% enddocs %} 

models/descriptions/columns/is_compressed_nft.md

@@ -0,0 +1,10 @@
+{% docs is_compressed_nft %}
+
+A boolean flag indicating whether the NFT is a compressed NFT (cNFT). Compressed NFTs use Merkle trees to reduce storage costs and enable more efficient NFT creation and management.
+
+- **Data type:** BOOLEAN (TRUE for compressed NFTs, FALSE for standard NFTs)
+- **Business context:** Used to distinguish between standard and compressed NFTs for analytics, cost analysis, and protocol adoption tracking.
+- **Analytics use cases:** cNFT adoption analysis, storage cost studies, and segmentation of NFT activity by type.
+- **Example:** TRUE
+
+{% enddocs %} 

models/descriptions/columns/is_dca_swap.md

@@ -0,0 +1,10 @@
+{% docs is_dca_swap %}
+
+A boolean flag indicating whether the swap was initiated by a Jupiter DCA (Dollar Cost Averaging) order. This field enables analysis of DCA feature usage and user behavior patterns.
+
+- **Data type:** BOOLEAN (TRUE/FALSE, NULL if not a DCA swap)
+- **Business context:** Used to identify DCA swaps and analyze Jupiter's DCA feature adoption and usage patterns.
+- **Analytics use cases:** DCA feature adoption analysis, user behavior studies, and Jupiter product analytics.
+- **Example:** TRUE
+
+{% enddocs %} 

models/descriptions/columns/is_limit_swap.md

@@ -0,0 +1,10 @@
+{% docs is_limit_swap %}
+
+A boolean flag indicating whether the swap was initiated by a Jupiter limit order. This field enables analysis of limit order feature usage and user behavior patterns.
+
+- **Data type:** BOOLEAN (TRUE/FALSE, NULL if not a limit order swap)
+- **Business context:** Used to identify limit order swaps and analyze Jupiter's limit order feature adoption and usage patterns.
+- **Analytics use cases:** Limit order feature adoption analysis, user behavior studies, and Jupiter product analytics.
+- **Example:** TRUE
+
+{% enddocs %} 

models/descriptions/columns/limit_requester.md

@@ -0,0 +1,10 @@
+{% docs limit_requester %}
+
+The original address that requested the limit order swap. This field identifies the user who initiated the limit order, enabling user-level limit order analytics.
+
+- **Data type:** STRING (base58 Solana address, NULL if not a limit order swap)
+- **Business context:** Used to track limit order users, analyze limit order user behavior, and measure limit order feature adoption at the user level.
+- **Analytics use cases:** Limit order user segmentation, user behavior analysis, and Jupiter product adoption studies.
+- **Example:** '4Nd1mYw4r...'
+
+{% enddocs %} 

models/descriptions/columns/liquidity_pool_address.md

@@ -0,0 +1,10 @@
+{% docs liquidity_pool_address %}
+
+The address of the liquidity pool where the action is being performed. This field identifies the specific pool involved in the liquidity action.
+
+- **Data type:** STRING (base58 Solana address)
+- **Business context:** Used to identify specific liquidity pools, analyze pool activity, and track pool-specific liquidity flows.
+- **Analytics use cases:** Pool-level analysis, liquidity flow tracking, and pool performance studies.
+- **Example:** '4Nd1mYw4r...'
+
+{% enddocs %}

models/descriptions/columns/liquidity_pool_name.md

@@ -0,0 +1,10 @@
+{% docs liquidity_pool_name %}
+
+The name of the liquidity pool where the action is being performed. This field provides a human-readable identifier for the specific pool.
+
+- **Data type:** STRING (pool name or identifier)
+- **Business context:** Used to identify specific liquidity pools, analyze pool activity, and track pool-specific liquidity flows.
+- **Analytics use cases:** Pool-level analysis, liquidity flow tracking, and pool performance studies.
+- **Example:** 'SOL-USDC Pool'
+
+{% enddocs %} 

models/descriptions/columns/liquidity_pool_platform.md

@@ -0,0 +1,10 @@
+{% docs liquidity_pool_platform %}
+
+The name of the liquidity pool protocol or platform (e.g., Raydium, Orca, Meteora) that manages the pool. This field enables protocol-level analytics.
+
+- **Data type:** STRING (e.g., 'Raydium', 'Orca', 'Meteora')
+- **Business context:** Used to identify the liquidity pool protocol, analyze protocol adoption, and compare protocol performance.
+- **Analytics use cases:** Protocol market share analysis, protocol adoption tracking, and cross-protocol liquidity studies.
+- **Example:** 'Raydium'
+
+{% enddocs %} 

models/descriptions/columns/liquidity_provider.md

@@ -0,0 +1,10 @@
+{% docs liquidity_provider %}
+
+The address of the liquidity provider who is performing the deposit or withdrawal action. This field identifies the user providing or removing liquidity from the pool.
+
+- **Data type:** STRING (base58 Solana address)
+- **Business context:** Used to track liquidity providers, analyze provider behavior, and identify active liquidity participants.
+- **Analytics use cases:** Liquidity provider analysis, provider behavior studies, and liquidity provision tracking.
+- **Example:** '4Nd1mYw4r...'
+
+{% enddocs %}

models/descriptions/columns/log_id.md

@@ -0,0 +1,10 @@
+{% docs log_id %}
+
+A unique identifier for the swap event, typically a combination of the transaction ID (TX_ID) and the event index within the transaction. This field enables precise event-level analytics and deduplication.
+
+- **Data type:** STRING (composite key, e.g., '5G7...:3')
+- **Business context:** Used to uniquely identify swap events, prevent double-counting, and join with event-level logs.
+- **Analytics use cases:** Event-level deduplication, log/event joins, and transaction traceability.
+- **Example:** '5G7...:3'
+
+{% enddocs %} 

models/descriptions/columns/marketplace_version.md

@@ -0,0 +1,10 @@
+{% docs marketplace_version %}
+
+The version of the NFT marketplace protocol used for the transaction. This field identifies the specific version of the marketplace program that facilitated the NFT sale.
+
+- **Data type:** STRING (e.g., 'v1', 'v2', 'v3')
+- **Business context:** Used to track protocol evolution, feature adoption, and user migration between marketplace versions.
+- **Analytics use cases:** Marketplace upgrade impact analysis, version adoption trends, and protocol migration studies.
+- **Example:** 'v2'
+
+{% enddocs %} 

models/descriptions/columns/mint_amount.md

@@ -0,0 +1,10 @@
+{% docs mint_amount %}
+
+The amount of tokens being minted in the transaction, denominated in the token's smallest unit (e.g., lamports for SOL, or the base unit for SPL tokens). This field enables token supply analysis and mint tracking.
+
+- **Data type:** NUMBER (integer, token's smallest unit)
+- **Business context:** Used to track token mints, analyze token supply changes, and measure inflationary pressure.
+- **Analytics use cases:** Token supply analysis, mint rate tracking, and inflationary token studies.
+- **Example:** For SOL, 1 SOL = 1,000,000,000 lamports; a value of `1000000000` means 1 SOL minted.
+
+{% enddocs %}

models/descriptions/columns/mint_authority.md

@@ -0,0 +1,10 @@
+{% docs mint_authority %}
+
+The address of the account that has authority to authorize the mint operation. This field identifies the entity responsible for authorizing the token mint.
+
+- **Data type:** STRING (base58 Solana address)
+- **Business context:** Used to track mint authorities, analyze mint patterns, and identify centralized mint controls.
+- **Analytics use cases:** Mint authority analysis, centralized vs decentralized mint studies, and token governance tracking.
+- **Example:** '4Nd1mYw4r...'
+
+{% enddocs %}