An 6390/llm context descriptions (#855)

* description rules and fact_txs update

* blocks update

* idls and labels

* wip

* wip

* update desc

* update

* update doc rules

* update table desc per new rules

* updates

.cursor/rules/dbt-documentation-standards.mdc

@@ -0,0 +1,158 @@
+---
+description: 
+globs: models/descriptions/*,*.yml,models/gold/**/*.sql
+alwaysApply: false
+---
+# dbt Documentation Standards
+When working with dbt projects, ensure comprehensive documentation that supports LLM-driven analytics workflows. This includes rich table and column descriptions that provide complete context for understanding blockchain data.
+
+## Table Documentation Standards
+Every dbt Model must have an accompanying yml file that provides model documentation.
+
+### Basic YML File Format
+Every dbt model yml file must follow this basic structure:
+
+```yaml
+version: 2
+
+models:
+  - name: [model_name]
+    description: "{{ doc('table_name') }}"
+    tests:
+      - [appropriate_tests_for_the_model]
+
+    columns:
+      - name: [COLUMN_NAME]
+        description: "{{ doc('column_name')}}"
+        tests:
+          - [appropriate_tests_for_the_column]
+```
+
+#### Required Elements:
+- **version: 2** - Must be the first line
+- **models:** - Top-level key containing the model definitions
+- **name:** - The exact name of the dbt model (without .sql extension)
+- **description:** - Reference to markdown documentation using `{{ doc('table_name') }}`
+- **columns:** - List of all columns in the model with their documentation
+
+#### Column Documentation Format:
+```yaml
+- name: [COLUMN_NAME_IN_UPPERCASE]
+  description: "{{ doc('column_name')}}"
+  tests:
+    - [test_name]:
+        [test_parameters]
+```
+
+### Table Descriptions
+Table documentation must include 4 standard elements, formatted in markdown. As the base documentation file is YML, the table description must be written in a dbt documentation markdown file in the `models/descriptions/tables` directory. The Table YML can then use the jinja doc block to reference it.
+
+The 4 standard categories (designed for LLM client consumption to aid in data model discovery and selection):
+
+1. **Description** (the "what"): What the model is mapping from the blockchain, data scope and coverage, transformations and business logic applied. DO NOT EXPLAIN THE DBT MODEL LINEAGE. This is not important for the use case of LLM-driven blockchain analytics.
+2. **Key Use Cases**: Examples of when this table might be used and for what analysis, specific analytical scenarios and applications
+3. **Important Relationships**: How this table might be used alongside OTHER GOLD LEVEL models, dependencies and connections to other key gold models. For example, a table like logs, events, or receipts may contain information from a larget transactions. To build this description, you SHOULD review the dbt model lineage to understand genuine model relationships. You must convert the model name to a database object, for example `core__fact_blocks.sql` = `core.fact_blocks` = `<schema>__<table_name>.sql`
+4. **Commonly-used Fields**: Fields most important to condicting analytics. Determining these requires an understanding of the data model, what the columns are (via their descriptions) and how those fields aid in analytics. One way an understanding can be inferred is by analyzing curated models (anything that is not a core model in the gold/core/ directory is curated. Core models clean and map basic data objects of the blockchain like blocks, transactions, events, logs, etc. Curated models map specialized areas of activity like defi, nfts, governance, etc.). Blockchain data is often logged to a data table as a json object with a rich mapping of event-based details.
+
+### Lineage Analysis
+Before writing table descriptions:
+- Read the dbt model SQL to understand the logic
+- Follow upstream dependencies to understand data flow
+- Review source models and transformations
+- Understand the business context and use cases
+- Review the column descriptions to estabish an understanding of the model, as a whole.
+- At the gold level, an ez_ table typically sources data from a fact_ table and this relationship should be documented. Ez_ tables add business logic such as (but not limited to) labels and USD price information
+
+## Column Documentation Standards
+
+### Rich Descriptions
+Each column description must include:
+- Clear definition of what the field represents
+- Data type and format expectations
+- Business context and use cases
+- Examples where helpful (especially for blockchain-specific concepts)
+- Relationships to other fields when relevant
+- Any important caveats or limitations
+
+### Blockchain-Specific Context
+For Solana blockchain data:
+- Reference official Solana protocol documentation for technical accuracy
+- Explain Solana-specific concepts (lamports, rent, program accounts, etc.)
+- Provide examples using Solana's conventions (e.g., base58 addresses, slot numbers)
+- Clarify differences from other blockchains when relevant
+
+### YAML Requirements
+- Column names MUST BE CAPITALIZED in YAML files
+- Use `{{ doc('column_name') }}` references for consistent desciption across models. The doc block must refer to a valid description in `models/descriptions`
+- Include appropriate tests for data quality
+
+## Examples of Good Documentation
+
+### Table Documentation Example
+```markdown
+{% docs table_transfers %}
+## Description
+This table tracks all token transfers on the <name> blockchain, capturing movements of native tokens and fungible tokens between accounts. The data includes both successful and failed transfers, with complete transaction context and token metadata.
+
+## Key Use Cases
+- Token flow analysis and wallet tracking
+- DeFi protocol volume measurements
+- Cross-chain bridge monitoring
+- Whale movement detection and alerts
+- Token distribution and holder analysis
+
+## Important Relationships
+- Subset of `gold.transactions`
+- Maps events emitted in `gold.events` or `gold.decoded_instructions`
+- Utilizes token price data from `gold.prices` to compute USD columns
+
+## Commonly-used Fields
+- `tx_id`: Essential for linking to transaction details and verification
+- `signers`: Core fields for solana user analysis and network mapping
+- `amount` and `amount_usd`: Critical for value calculations and financial analysis
+- `token_address`: Key for filtering by specific tokens and DeFi analysis
+- `block_timestamp`: Primary field for time-series analysis and trend detection
+{% enddocs %}
+```
+
+### Column Documentation Example
+```markdown
+{% docs amount_raw %}
+Unadjusted amount of tokens as it appears on-chain (not decimal adjusted). This is the raw token amount before any decimal precision adjustments are applied. For example, if transferring 1 native token, the amount_raw would be 1000000000000000000000000 (1e24) since <this blockchain's native token> has 24 decimal places. This field preserves the exact on-chain representation of the token amount for precise calculations and verification.
+{% enddocs %}
+```
+Important consideration: be sure to research and confirm figures such as decimal places. If unknown DO NOT MAKE UP A NUMBER.
+
+## Common Patterns to Follow
+- Start with a clear definition
+- Provide context about why the field exists
+- Include examples for complex concepts
+- Explain relationships to other fields
+- Mention any important limitations or considerations
+- Use consistent terminology throughout the project
+
+## Quality Standards
+
+### Completeness
+- Every column must have a clear, detailed description
+- Table descriptions must explain the model's purpose and scope
+- Documentation must be self-contained without requiring external context
+- All business logic and transformations must be explained
+
+### Accuracy
+- Technical details must match official blockchain documentation
+- Data types and formats must be correctly described
+- Examples must use appropriate blockchain conventions
+- Relationships between fields must be accurately described
+
+### Clarity
+- Descriptions must be clear and easy to understand
+- Complex concepts must be explained with examples
+- Terminology must be consistent throughout the project
+- Language must support LLM understanding
+
+### Consistency
+- Use consistent terminology across all models
+- Follow established documentation patterns
+- Maintain consistent formatting and structure
+- Ensure similar fields have similar descriptions

.cursor/rules/review-dbt-documentation.mdc

@@ -0,0 +1,220 @@
+---
+description: 
+globs: 
+alwaysApply: false
+---
+# Review dbt Documentation Process
+
+## Overview
+This document outlines the comprehensive process for reviewing and improving column and table descriptions for gold models in dbt projects. The goal is to provide robust, rich details that improve context for LLM-driven analytics workflows, ensuring that documentation is complete, accurate, and self-contained without requiring external expert files.
+
+## Objectives
+- Create clear, detailed documentation that supports LLM understanding of blockchain data
+- Ensure technical accuracy by referencing official protocol documentation
+- Provide rich context for each table and column to enable effective analytics
+- Maintain consistency across all models and schemas
+- Support automated analytics workflows without requiring expert context files
+
+## Pre-Review Requirements
+
+### 1. Research Phase
+**Blockchain Protocol Documentation**
+- Search and read official developer documentation for the target blockchain ie for Solana: (https://solana.com/docs). Utilize web search to find authentic and accurate developer documentation
+- Review technical specifications, whitepapers, and API documentation
+- Understand Solana's consensus mechanism, data structures (accounts, slots, instructions), and conventions
+- Research common use cases and analytics patterns specific to the blockchain
+- Identify key technical concepts that need explanation (e.g., lamports, rent, program accounts, token standards)
+
+**External Resources to Consult**
+- Official Solana documentation (https://docs.solana.com/)
+- Developer guides and tutorials
+- Technical specifications and whitepapers
+- Community documentation and forums
+- Block explorers and API documentation (e.g., https://explorer.solana.com/ and https://solscan.io/)
+
+### 2. Project Context Analysis
+- Review the `__overview__.md` file and rewrite it per the @dbt-overview-standard rule to create a summary of what this particular blockchain is, unique characteristics, and any other general information about the chain itself
+- Review existing documentation patterns and terminology
+- Understand the data flow and model lineage structure
+
+## Review Process
+
+### Step 1: Model Analysis
+**SQL Logic Review**
+- Read the dbt model SQL file to understand the transformations and business logic
+- Follow upstream dependencies to understand data flow from source to gold layer
+- Review bronze source models, silver staging models, and intermediate transformations
+- Identify any complex joins, aggregations, or business logic that needs explanation
+- Understand the incremental logic and any filtering conditions
+
+**Lineage Analysis**
+- Map the complete data lineage from source to gold model
+- Identify key transformations and their purposes
+- Understand relationships between related models for the sole purpose of generating a robust description
+- Do not include data lineage analysis in the table description
+
+### Step 2: Column Description Review
+**Individual Column Analysis**
+For each column in the model:
+
+1. **Technical Understanding**
+   - Read the SQL to understand how the column is derived
+   - Check upstream models if the column comes from a transformation
+   - Understand the data type and format expectations
+   - Identify any business logic applied to the column
+
+2. **Blockchain Context**
+   - Research the blockchain-specific meaning of the column
+   - Reference official documentation for technical accuracy
+   - Understand how this field relates to blockchain concepts
+   - Identify any blockchain-specific conventions or requirements
+
+3. **Documentation Assessment**
+   - Review existing column description
+   - Evaluate completeness and clarity
+   - Check for missing context or examples
+   - Ensure the description supports LLM understanding
+
+**Required Elements for Column Descriptions**
+- Clear definition of what the field represents
+- Data type and format expectations
+- Business context and use cases
+- Examples where helpful (especially for blockchain-specific concepts)
+- Relationships to other fields when relevant
+- Any important caveats or limitations
+- Blockchain-specific context and conventions
+
+### Step 3: Table Description Review
+**Current State Assessment**
+- Review the updated column descriptions
+- Review existing table description in the YAML file
+- Evaluate completeness and clarity
+- Identify missing context or unclear explanations
+
+**Required Elements for Table Descriptions**
+Table documentation must include 4 standard elements, formatted in markdown. As the base documentation file is YML, the table description must be written in a dbt documentation markdown file in the `models/descriptions/` directory. The Table YML can then use the jinja doc block to reference it.
+
+The 4 standard categories are fully defined in the @dbt-documentation-standards rule. They are:
+
+1. **Description**
+2. **Key Use Cases**
+3. **Important Relationships**
+4. **Commonly-used Fields**
+
+### Step 4: Documentation File Review
+**Individual Documentation Files**
+- Check if each column has a corresponding `.md` file in `models/descriptions/`
+- Review existing documentation for completeness and accuracy
+- Update or create documentation files as needed
+
+**Documentation File Format**
+```markdown
+{% docs column_name %}
+[Rich, detailed description including:
+- Clear definition
+- Data format and examples
+- Business context
+- Blockchain-specific details
+- Relationships to other fields
+- Important considerations]
+{% enddocs %}
+```
+
+### Step 5: YAML File Review
+**YAML Structure Validation**
+- Ensure column names are CAPITALIZED in YAML files
+- Verify all columns reference documentation using `{{ doc('column_name') }}`
+- Check that appropriate tests are included
+- Validate the overall YAML structure
+
+**YAML File Format**
+```yaml
+version: 2
+
+models:
+  - name: [model_name]
+    description: |-
+      [Clear, direct table description]
+    
+    columns:
+      - name: [COLUMN_NAME_IN_UPPERCASE]
+        description: "{{ doc('column_name') }}"
+        tests:
+          - [appropriate_tests]
+```
+
+## Review Checklist
+
+### Table Level
+- [ ] Table documentation is in markdown file in `models/descriptions/` directory
+- [ ] Table YAML references documentation using jinja doc block
+- [ ] **Description** section explains what blockchain data is being modeled
+- [ ] **Key Use Cases** section provides specific analytical scenarios
+- [ ] **Important Relationships** section explains connections to other GOLD models
+- [ ] **Commonly-used Fields** section identifies critical columns and their importance
+- [ ] Documentation is optimized for LLM client consumption
+
+### Column Level
+- [ ] Each column has a comprehensive description
+- [ ] Data types and formats are clearly specified
+- [ ] Business context and use cases are explained
+- [ ] Examples are provided for complex concepts
+- [ ] Relationships to other fields are documented
+- [ ] Important limitations or caveats are noted
+- [ ] Blockchain-specific context is included
+
+### Documentation Files
+- [ ] All columns have corresponding `.md` files
+- [ ] Documentation files contain rich, detailed descriptions
+- [ ] Examples use appropriate blockchain conventions
+- [ ] Technical accuracy is verified against official documentation
+
+### YAML Files
+- [ ] Column names are CAPITALIZED
+- [ ] All columns reference documentation using `{{ doc('column_name') }}`
+- [ ] Appropriate tests are included
+- [ ] YAML structure is valid
+
+## Implementation Guidelines
+
+### Documentation Writing Tips
+- Start with a clear definition of what the field represents
+- Provide context about why the field exists and its importance
+- Include examples for complex concepts, especially blockchain-specific ones
+- Explain relationships to other fields when relevant
+- Mention any important limitations or considerations
+- Use consistent terminology throughout the project
+
+### Blockchain-Specific Considerations
+- Reference official protocol documentation for technical concepts
+- Explain blockchain-specific concepts (lamports, rent, program accounts, etc.)
+- Provide examples using the specific blockchain's conventions
+- Clarify differences from other blockchains when relevant
+- Include information about data freshness and update mechanisms
+
+### LLM Optimization
+- Write descriptions that are complete and self-contained
+- Use clear, structured language that supports automated understanding
+- Include context that helps LLMs understand the data's purpose
+- Provide examples that illustrate common use cases
+- Ensure descriptions support common analytics workflows
+
+## Post-Review Actions
+
+### Validation
+- Verify all documentation is technically accurate
+- Check that descriptions are complete and self-contained
+- Ensure consistency across related models
+- Validate that documentation supports common analytics use cases
+
+### Testing
+- Test documentation by having an LLM attempt to understand the data
+- Verify that descriptions enable effective query generation
+- Check that examples are clear and helpful
+- Ensure documentation supports the intended analytics workflows
+
+### Maintenance
+- Update documentation when models change
+- Review and refresh documentation periodically
+- Maintain consistency as new models are added
+- Keep documentation aligned with blockchain protocol updates

models/descriptions/account_address.md

@@ -0,0 +1,13 @@
+{% docs account_address %}
+
+The base58-encoded address of the token account. Used to uniquely identify SPL token accounts on the Solana blockchain. Each token account holds a balance of a specific SPL token and is controlled by an owner address.
+
+**Data type:** String (base58 address)
+**Example:**
+- `9xQeWv...`
+
+**Business Context:**
+- Enables attribution of token balances and transfers to specific accounts.
+- Used in analytics for tracking token holdings, transfers, and ownership changes.
+
+{% enddocs %} 

models/descriptions/account_keys.md

@@ -0,0 +1,3 @@
+{% docs account_keys %}
+An array of all account addresses referenced by this transaction, including signers, writable, and read-only accounts. Each entry is a base58-encoded Solana address. This list is used to resolve account balances and permissions for transaction execution. See: https://docs.solana.com/developing/programming-model/accounts
+{% enddocs %} 

models/descriptions/address.md

@@ -0,0 +1,10 @@
+{% docs address %}
+The base58-encoded Solana address (public key) being labeled. Used to join with transaction, account, and program tables for entity resolution and analytics.
+
+**Example:**
+- "4Nd1mY..."
+
+**Business Context:**
+- Enables address-level analytics, entity resolution, and attribution.
+- Used as a join key for linking labels to on-chain activity.
+{% enddocs %} 

models/descriptions/address_name.md

@@ -0,0 +1,10 @@
+{% docs address_name %}
+A human-readable name or alias for the address, if available. Used for display, search, and analytics on labeled addresses.
+
+**Example:**
+- "Orca Treasury"
+- "ME Marketplace"
+
+**Business Context:**
+- Enables user-friendly display, search, and analytics on addresses.
+{% enddocs %} 

models/descriptions/amount.md

@@ -1,5 +1,13 @@
 {% docs amount %}
 
-The number of tokens sent during an event
+The amount of the asset transferred in the event. For native SOL, this is decimal adjusted and is not in Lamports. For SPL tokens, this is decimal adjusted according to the token's mint. Represents the value moved from sender to recipient in a single transfer event.
+
+**Data type:** Numeric (integer for lamports, decimal for tokens)
+**Example:**
+- USDC: `50.00` (represents 50 USDC tokens)
+
+**Business Context:**
+- Used to analyze transaction volumes, user activity, and protocol flows.
+- Supports aggregation of asset movement for analytics and reporting.
 
 {% enddocs %}

models/descriptions/backfill_status.md

@@ -1,5 +1,11 @@
-{% docs backfill_status%}
+{% docs backfill_status %}
+A status indicator describing whether historical data for this program or IDL has been fully backfilled. Common values: 'complete', 'in_progress', 'not_started'.
 
-Status for the decoding of historical events - complete/in progress/not started
+**Example:**
+- "complete"
+- "in_progress"
+- "not_started"
 
+**Business Context:**
+- Supports data completeness checks, ETL monitoring, and analytics on historical coverage.
 {% enddocs %}

models/descriptions/balances/balances.md

@@ -1,66 +1,105 @@
 {% docs sol_balance_table_doc %}
 
-A fact table containing the beginning and ending balances of native SOL accounts in a transaction. This contains both successful and unsuccessful transactions as native SOL is still deducted in failures. The 'owner' is the same as the 'account_address' because native SOL is not held within a separate token account.
+Contains one row per account and transaction where a native SOL (Solana) balance changes on the Solana blockchain. Tracks pre- and post-transaction balances for each account, including block, transaction, and mint information. Balances are adjusted for SOL's 9 decimal places. Enables analysis of SOL balance changes, account activity, and ownership attribution at the transaction level. Includes both successful and unsuccessful transactions, as native SOL is deducted even in failures. The 'owner' is the same as the 'account_address' because native SOL is not held within a separate token account. Data is updated incrementally as new blocks are processed, and each row represents a unique account-transaction balance change event.
 
 {% enddocs %}
 
 {% docs token_balance_table_doc %}
 
-A fact table containing the beginning and ending token balances of token accounts in a transaction. This only contain successful transactions as there are no token balance changes in failed transactions.
+Contains one row per account and transaction where an SPL token balance changes on the Solana blockchain. Tracks pre- and post-transaction balances for each token account, including block, transaction, mint, and owner information. Balances are decimal adjusted according to the token's mint. Enables analysis of token balance changes, account activity, and ownership attribution at the transaction level. Only includes successful transactions, as there are no token balance changes in failed transactions. Data is updated incrementally as new blocks are processed, and each row represents a unique token account-transaction balance change event.
 
 {% enddocs %}
 
 {% docs balances_account %}
 
-The account address which holds a specific token.
+The base58-encoded address of the account holding the asset. For native SOL, this is the wallet address. For SPL tokens, this is the token account address. Used to attribute balances and transfers to specific accounts.
+
+**Example:**
+- Native SOL: `7GgkQ2...` (wallet address)
+- SPL Token: `9xQeWv...` (token account address)
 
 {% enddocs %}
 
 {% docs balances_pre_amount %}
 
-The initial decimal-adjusted amount in an account.
+The account's balance before the transaction, decimal-adjusted. For SOL, this is in units of SOL (not lamports); for tokens, this is in the token's native units (adjusted for mint decimals).
+
+**Data type:** Numeric (decimal)
+**Example:**
+- SOL: `1.23456789` (represents 1.23456789 SOL)
+- USDC: `100.00` (represents 100 USDC tokens)
 
 {% enddocs %}
 
 {% docs balances_post_amount %}
 
-The final decimal-adjusted amount in an account.
+The account's balance after the transaction, decimal-adjusted. For SOL, this is in units of SOL (not lamports); for tokens, this is in the token's native units (adjusted for mint decimals).
+
+**Data type:** Numeric (decimal)
+**Example:**
+- SOL: `0.23456789` (represents 0.23456789 SOL after a transfer)
+- USDC: `50.00` (represents 50 USDC tokens after a transfer)
 
 {% enddocs %}
 
 {% docs balances_index %}
 
-Location of the account entry within the balances array for a transaction.
+The position of the account entry within the balances array for a transaction. Used to correlate balances with other transaction-level arrays (e.g., account_keys).
+
+**Data type:** Integer
+**Example:**
+- `0` (first account in the array)
+- `2` (third account in the array)
 
 {% enddocs %}
 
 {% docs balances_account_index %}
 
-Location corresponding to the index field in the account_keys array.
+The index of the account in the account_keys array for the transaction. Useful for mapping balances to specific accounts referenced in the transaction.
+
+**Data type:** Integer
+**Example:**
+- `1` (second account in account_keys)
 
 {% enddocs %}
 
 {% docs token_balances_pre_owner %}
 
-Owner of the token account at the start of the transaction.
+The owner of the token account at the start of the transaction. This is a base58-encoded address. Ownership may change during a transaction (e.g., via token transfers or account reassignment).
+
+**Data type:** String (base58 address)
+**Example:**
+- `7GgkQ2...`
 
 {% enddocs %}
 
 {% docs token_balances_post_owner %}
 
-The final owner of the token account in the transaction.
+The owner of the token account at the end of the transaction. This is a base58-encoded address. If ownership changes during the transaction, this field reflects the new owner.
+
+**Data type:** String (base58 address)
+**Example:**
+- `9xQeWv...`
 
 {% enddocs %}
 
 {% docs token_balances_block_owner %}
 
-The final owner of the token account within the block.
+The owner of the token account at the end of the block. Used for block-level attribution of balances and transfers. This is a base58-encoded address.
+
+**Data type:** String (base58 address)
+**Example:**
+- `7GgkQ2...`
 
 {% enddocs %}
 
 {% docs sol_balances_owner %}
 
-The wallet holding the native SOL. This is represented as the same value as the 'account_address'.
+The wallet address holding the native SOL. For native SOL, the owner is always the same as the account address, since SOL is not held in a separate token account.
+
+**Data type:** String (base58 address)
+**Example:**
+- `7GgkQ2...`
 
 {% enddocs %}
 

models/descriptions/block_hash.md

@@ -0,0 +1,10 @@
+{% docs block_hash %}
+The cryptographic hash of this block, as recorded on the Solana blockchain. Used to verify block integrity and support block explorer lookups. This value is a base58-encoded string.
+
+**Example:**
+- "5h3k...9zQ"
+
+**Business Context:**
+- Used for block verification, deduplication, and explorer integrations.
+- Supports chain integrity and auditability.
+{% enddocs %} 

models/descriptions/block_height.md

@@ -0,0 +1,10 @@
+{% docs block_height %}
+The height (slot number) of this block in the Solana blockchain. Block height is a sequential integer that increases with each new block and is used to order blocks chronologically.
+
+**Example:**
+- 12345678
+
+**Business Context:**
+- Used for block ordering, chain growth analysis, and fork resolution.
+- Important for time-series and historical analytics.
+{% enddocs %} 

models/descriptions/block_id.md

@@ -1,5 +1,13 @@
 {% docs block_id %}
+A unique identifier for the block in which this transaction was included on the Solana blockchain. Typically a sequential integer or hash, depending on the data source. Used to group transactions by block and analyze block-level activity.
 
-Slot for which a block can be created.
+**Example:**
+- 123456789
 
+**Business Context:**
+- Supports block-level analytics, such as block production rate and transaction throughput.
+- Useful for tracing transaction inclusion and block explorer integrations.
+
+**Relationships:**
+- All transactions with the same 'block_id' share the same 'block_timestamp'.
 {% enddocs %}

models/descriptions/block_timestamp.md

@@ -1,5 +1,5 @@
 {% docs block_timestamp %}
 
-The date and time at which the block began.
+The timestamp (UTC) at which the block was produced on the Solana blockchain. This field is recorded as a TIMESTAMP data type and represents the precise moment the block was finalized and added to the chain. It is essential for time-series analysis, block production monitoring, and aligning transaction and event data to specific points in time. Used extensively for analytics involving block intervals, network activity trends, and historical lookups. Format: `YYYY-MM-DD HH:MI:SS` (UTC).
 
 {% enddocs %}

models/descriptions/blockchain.md

@@ -1,5 +1,10 @@
 {% docs blockchain %}
+The name of the blockchain network to which the labeled address or entity belongs. For this model, the value is always 'solana'.
 
-In this table, always Solana. Used to join to cross-chain tables. 
+**Example:**
+- "solana"
 
+**Business Context:**
+- Enables multi-chain analytics and filtering.
+- Used as a join key in cross-chain models.
 {% enddocs %}

models/descriptions/chain_id.md

@@ -0,0 +1,10 @@
+{% docs chain_id %}
+A static identifier for the Solana blockchain. This value is always 'solana' for Solana-native tables and is used to support joins with cross-chain analytics tables.
+
+**Example:**
+- "solana"
+
+**Business Context:**
+- Supports cross-chain analytics and integrations.
+- Used as a join key in multi-chain models.
+{% enddocs %} 

models/descriptions/creator.md

@@ -0,0 +1,10 @@
+{% docs creator %}
+The identifier (e.g., address or username) of the entity or user who created the label for this address. Used for attribution, auditing, and analytics on label provenance.
+
+**Example:**
+- "7G8h..."
+- "labeler_001"
+
+**Business Context:**
+- Supports label attribution, auditability, and analytics on label creation activity.
+{% enddocs %} 

models/descriptions/date_submitted.md

@@ -1,5 +1,9 @@
 {% docs date_submitted %}
+The UTC date and time when the IDL was submitted for this program. Used for tracking submission recency, program upgrades, and developer activity.
 
-Date at which the IDL was submitted.
+**Example:**
+- "2024-05-01 12:34:56"
 
+**Business Context:**
+- Enables submission recency analysis, upgrade tracking, and developer engagement monitoring.
 {% enddocs %}

models/descriptions/decoded_accounts.md

@@ -0,0 +1,3 @@
+{% docs decoded_accounts %}
+An array of Solana account addresses (base58-encoded) involved in the decoded instruction. Each account may represent a user, program, token account, or system account. Useful for attribution, protocol analysis, and understanding instruction context.
+{% enddocs %} 

models/descriptions/decoded_args.md

@@ -0,0 +1,3 @@
+{% docs decoded_args %}
+A JSON object containing the arguments or parameters passed to the Solana program in the decoded instruction. The structure varies by program and instruction type. Enables granular analysis of protocol usage and on-chain activity.
+{% enddocs %} 

models/descriptions/decoded_instruction.md

@@ -0,0 +1,3 @@
+{% docs decoded_instruction %}
+A JSON object representing the decoded Solana instruction, including the program being called, the accounts involved, and any arguments or data passed to the program. Enables detailed analysis of protocol interactions and instruction-level behavior. Example: {"programId": "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA", "accounts": [...], "args": {...}}.
+{% enddocs %} 

models/descriptions/decoding_error.md

@@ -0,0 +1,3 @@
+{% docs decoding_error %}
+A string describing any error encountered while decoding the instruction. If decoding was successful, this field is null. Useful for monitoring data quality and identifying unsupported or malformed instructions.
+{% enddocs %} 

models/descriptions/earliest_decoded_block.md

@@ -1,5 +1,9 @@
 {% docs earliest_decoded_block %}
+The block ID (slot number) of the earliest block for which decoded instructions are available for this program. Used to track the start of program activity and analytics coverage.
 
-The oldest block where events has been decoded
+**Example:**
+- 12345679
 
+**Business Context:**
+- Enables analytics on program activity start, coverage, and completeness.
 {% enddocs %}

models/descriptions/end_block_id.md

@@ -0,0 +1,14 @@
+{% docs end_block_id %}
+
+The block ID (slot number) where the ownership period for the token account ends (exclusive). A null value indicates the current owner. Used to determine the time range during which a specific owner controlled the account.
+
+**Data type:** Integer (slot number) or null
+**Example:**
+- `123456999` (ownership ended at this block)
+- `null` (current owner)
+
+**Business Context:**
+- Enables historical attribution of token balances and transfers to the correct owner.
+- Supports analytics on ownership changes, user activity, and protocol events.
+
+{% enddocs %} 

models/descriptions/event_index.md

@@ -1,5 +1,13 @@
 {% docs event_index %}
+The position of the event (instruction) within the list of instructions for a given Solana transaction. Used to order and reference events within a transaction. Indexing starts at 0 for the first event.
+
+**Example:**
+- 0
+- 3
+
+**Business Context:**
+- Enables precise identification and ordering of events within a transaction, which is critical for reconstructing transaction flows and analyzing protocol behavior.
+- Used to join or filter event-level data, especially when multiple events occur in a single transaction.
 
-Location of the instruction (event) within a transaction
 
 {% enddocs %}

models/descriptions/event_type.md

@@ -1,5 +1,15 @@
 {% docs event_type %}
+A string categorizing the type of event or instruction, such as 'transfer', 'mint', 'burn', or protocol-specific actions.
 
-The type of event (i.e. "delegate", "withdraw") that is occurring
+**Example:**
+- 'transfer'
+- 'mint'
+- 'burn'
 
+**Business Context:**
+- Enables segmentation and filtering of on-chain activity for analytics and dashboards.
+- Used to group and analyze protocol-specific actions and user behaviors.
+
+**Relationships:**
+- May be derived from decoded instruction data or protocol-specific logic.
 {% enddocs %}

models/descriptions/fee.md

@@ -0,0 +1,3 @@
+{% docs fee %}
+The transaction fee paid for processing this transaction, denominated in lamports (the smallest unit of SOL). This fee is deducted from the payer's account and is determined by the compute resources consumed and the current network fee rate. For more information, see: https://docs.solana.com/implemented-proposals/transaction-fees
+{% enddocs %} 

models/descriptions/first_block_id.md

@@ -1,5 +1,9 @@
 {% docs first_block_id %}
+The block ID (slot number) of the first block in which this program or IDL was observed. Used to track program deployment and interface introduction on-chain.
 
-The block where the program was first called in a transaction
+**Example:**
+- 12345678
 
+**Business Context:**
+- Supports deployment analysis, program lifecycle tracking, and historical analytics.
 {% enddocs %}

models/descriptions/first_program_id.md

@@ -0,0 +1,3 @@
+{% docs first_program_id %}
+The program ID (base58-encoded address) of the first Solana program this signer interacted with, excluding chain admin programs. Indicates the initial protocol or application used by the signer. Example: 'TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA'.
+{% enddocs %} 

models/descriptions/first_tx_date.md

@@ -0,0 +1,3 @@
+{% docs first_tx_date %}
+The date (UTC) of the first transaction signed by this address, formatted as YYYY-MM-DD. Useful for cohort analysis, user onboarding studies, and measuring protocol adoption over time.
+{% enddocs %} 

models/descriptions/idl.md

@@ -0,0 +1,7 @@
+{% docs idl %}
+The Interface Definition Language (IDL) document for the Solana program, typically in JSON format. Defines the program's instructions, accounts, and types, enabling clients and analytics tools to interact with the program in a standardized way.
+
+**Example:**
+- JSON object describing program instructions and accounts
+
+{% enddocs %} 

models/descriptions/idl_hash.md

@@ -0,0 +1,9 @@
+{% docs idl_hash %}
+A cryptographic hash (e.g., SHA-256) of the IDL document, used to verify the integrity and version of the program interface. Changes when the IDL is updated or modified.
+
+**Example:**
+- "a3f5...9b2c"
+
+**Business Context:**
+- Enables version tracking, upgrade detection, and integrity verification for program interfaces.
+{% enddocs %} 

models/descriptions/index.md

@@ -1,5 +1,15 @@
 {% docs index %}
 
-A unique key that identifies the event's position within a transaction
+The position of the transfer event within the list of events for a given Solana transaction. Used to order and reference transfers within a transaction. Indexing starts at 0 for the first event.
+
+**Data type:** Integer
+**Example:**
+- 0 (first transfer in the transaction)
+- 2 (third transfer in the transaction)
+
+**Business Context:**
+- Enables reconstruction of transfer order and analysis of intra-transaction asset movement.
+- Used to join, filter, or segment data for protocol analytics, error tracing, and event sequencing.
+
 
 {% enddocs %}

models/descriptions/inner_index.md

@@ -1,5 +1,13 @@
 {% docs inner_index %}
+The position of the inner instruction or event within the list of inner instructions for a given Solana transaction. Used to order and reference nested (CPI) instructions. Indexing starts at 0 for the first inner instruction.
+
+**Example:**
+- 0
+- 2
+
+**Business Context:**
+- Enables precise identification and ordering of nested program calls (Cross-Program Invocations) within a transaction.
+- Critical for analyzing composability, protocol integrations, and the full execution path of complex transactions.
 
-Location of the instruction within an instruction's (event) inner instruction
 
 {% enddocs %}

models/descriptions/inner_instructions.md

@@ -0,0 +1,3 @@
+{% docs inner_instructions %}
+An array of instructions invoked by programs during the execution of the main transaction instructions. Inner instructions are generated by CPI (cross-program invocation) and provide details on program-to-program calls. See: https://docs.solana.com/developing/programming-model/calling-between-programs
+{% enddocs %} 

models/descriptions/inserted_timestamp.md

@@ -1,5 +1,3 @@
 {% docs inserted_timestamp %}
-
-The timestamp at which the record was initially created and inserted into this table.
-
+The timestamp when this transaction record was first inserted into the analytics database. Used for data freshness tracking and incremental model logic. Format: YYYY-MM-DD HH:MI:SS. Not derived from the blockchain, but from the ETL process.
 {% enddocs %}

models/descriptions/instruction_program_id.md

@@ -0,0 +1,15 @@
+{% docs instruction_program_id %}
+The unique public key (base58-encoded address) of the Solana program that invoked this inner instruction (Cross-Program Invocation, CPI). This field identifies the calling program.
+
+**Example:**
+- "4Nd1mY..." (caller)
+- "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA" (callee)
+
+**Business Context:**
+- Enables tracing of program-to-program calls and composability patterns in Solana transactions.
+- Used to analyze protocol integrations, nested execution flows, and the origin of on-chain actions.
+
+**Relationships:**
+- Used with 'program_id', 'tx_id', and instruction indices to reconstruct full CPI call stacks.
+- 'instruction_program_id' is the caller; 'program_id' is the callee for the inner instruction.
+{% enddocs %} 

models/descriptions/instructions.md

@@ -0,0 +1,3 @@
+{% docs instructions %}
+An array of program instructions executed as part of this transaction. Each instruction includes the program ID, accounts involved, and input data. Instructions define the actions performed by the transaction. See: https://docs.solana.com/developing/programming-model/transactions#instructions
+{% enddocs %} 

models/descriptions/is_active.md

@@ -0,0 +1,8 @@
+{% docs is_active %}
+Boolean flag indicating whether the program has had decoded instructions or activity within a recent time window (e.g., last 14 days). TRUE means the program is active; FALSE means it is dormant or inactive.
+
+**Example:**
+- true
+- false
+
+{% enddocs %} 

models/descriptions/is_valid.md

@@ -1,5 +1,8 @@
 {% docs is_valid %}
+Boolean flag indicating whether the IDL is valid and conforms to expected structure and standards. TRUE means the IDL is valid and usable; FALSE indicates errors or incompatibility.
 
-Whether events are properly decoding with the IDL
+**Example:**
+- true
+- false
 
 {% enddocs %}

models/descriptions/label.md

@@ -0,0 +1,10 @@
+{% docs label %}
+The human-readable label or project name associated with the address. Used for entity attribution, analytics, and display in dashboards or explorers.
+
+**Example:**
+- "Orca"
+- "Magic Eden"
+
+**Business Context:**
+- Supports attribution, search, and analytics on labeled entities.
+{% enddocs %} 

models/descriptions/label_subtype.md

@@ -0,0 +1,11 @@
+{% docs label_subtype %}
+A sub-category nested within label_type, providing further detail about the labeled address (e.g., 'amm', 'marketplace', 'bridge'). Used for more granular segmentation and analytics.
+
+**Example:**
+- "amm"
+- "marketplace"
+- "bridge"
+
+**Business Context:**
+- Enables fine-grained analytics and filtering by address subtype.
+{% enddocs %} 

models/descriptions/label_type.md

@@ -0,0 +1,11 @@
+{% docs label_type %}
+A high-level category describing the main function or ownership of the labeled address (e.g., 'defi', 'nft', 'cex', 'dapp'). Used for grouping, filtering, and analytics on address types.
+
+**Example:**
+- "defi"
+- "nft"
+- "cex"
+
+**Business Context:**
+- Supports segmentation, filtering, and analytics by address type.
+{% enddocs %} 

models/descriptions/last_activity_timestamp.md

@@ -0,0 +1,7 @@
+{% docs last_activity_timestamp %}
+The UTC timestamp of the most recent decoded instruction or activity for this program. Used to track program usage, recency, and engagement.
+
+**Example:**
+- "2024-05-01 12:34:56"
+
+{% enddocs %} 

models/descriptions/last_program_id.md

@@ -0,0 +1,3 @@
+{% docs last_program_id %}
+The program ID (base58-encoded address) of the last Solana program this signer interacted with, excluding chain admin programs. Indicates the most recent protocol or application used by the signer. Example: 'Vote111111111111111111111111111111111111111'.
+{% enddocs %} 

models/descriptions/last_tx_date.md

@@ -0,0 +1,3 @@
+{% docs last_tx_date %}
+The date (UTC) of the most recent transaction signed by this address, formatted as YYYY-MM-DD. Useful for measuring user retention, reactivation, and protocol engagement over time.
+{% enddocs %} 

models/descriptions/log_messages.md

@@ -0,0 +1,3 @@
+{% docs log_messages %}
+An array of log messages emitted by programs during transaction execution. Useful for debugging, tracing program logic, and analyzing transaction outcomes. Each entry is a string message as output by the Solana runtime. See: https://docs.solana.com/developing/programming-model/runtime#logging
+{% enddocs %} 

models/descriptions/modified_timestamp.md

@@ -1,5 +1,3 @@
 {% docs modified_timestamp %}
-
-The timestamp at which this record was last modified by an internal process.
-
+The timestamp when this transaction record was last updated in the analytics database. Used for tracking updates and supporting incremental model logic. Format: YYYY-MM-DD HH:MI:SS. Not derived from the blockchain, but from the ETL process.
 {% enddocs %}

models/descriptions/network.md

@@ -0,0 +1,11 @@
+{% docs network %}
+The name of the Solana network from which this block was sourced. Common values include 'mainnet-beta', 'testnet', or 'devnet'. Used to distinguish between different Solana environments and support multi-network analytics.
+
+**Example:**
+- "mainnet-beta"
+- "testnet"
+
+**Business Context:**
+- Enables filtering and analysis by network environment.
+- Important for cross-network comparisons and testnet/mainnet separation.
+{% enddocs %} 

models/descriptions/num_days_active.md

@@ -0,0 +1,3 @@
+{% docs num_days_active %}
+The total number of unique days (UTC) on which this signer performed at least one transaction. Useful for measuring user activity, engagement, and protocol stickiness.
+{% enddocs %} 

models/descriptions/num_txs.md

@@ -0,0 +1,3 @@
+{% docs num_txs %}
+The total number of distinct transactions signed by this address. Useful for analyzing user activity, protocol adoption, and transaction frequency.
+{% enddocs %} 

models/descriptions/owner.md

@@ -0,0 +1,13 @@
+{% docs owner %}
+
+The base58-encoded address of the owner controlling the token account during the specified block range. Ownership may change over time due to transfers or account reassignment. Used to attribute token balances and transfers to the correct user or program at any point in time.
+
+**Data type:** String (base58 address)
+**Example:**
+- `7GgkQ2...`
+
+**Business Context:**
+- Enables historical tracking of token account ownership.
+- Supports analytics on user activity, protocol attribution, and token flows.
+
+{% enddocs %} 

models/descriptions/pk.md

@@ -1,5 +1,4 @@
 {% docs pk %}
-
-The unique identifier for each row in the table.
+A unique, stable identifier for each record in this table. The primary key (PK) ensures that every row is uniquely identifiable and supports efficient joins, lookups, and data integrity across models. The PK may be a natural key (such as a blockchain transaction hash) or a surrogate key generated from one or more fields, depending on the table's structure and requirements.
 
 {% enddocs %}

models/descriptions/post_balances.md

@@ -0,0 +1,3 @@
+{% docs post_balances %}
+An array of lamport balances for each account in 'account_keys' after the transaction is executed. The order matches the 'account_keys' array. Used to track balance changes and verify transaction effects. Value is in lamports (1 SOL = 1,000,000,000 lamports).
+{% enddocs %} 

models/descriptions/post_token_balances.md

@@ -0,0 +1,3 @@
+{% docs post_token_balances %}
+An array of SPL token balances for each token account involved in the transaction, after execution. Each entry includes the token account address, mint, and raw amount. Used to track token transfers and verify effects. See: https://spl.solana.com/token
+{% enddocs %} 

models/descriptions/pre_balances.md

@@ -0,0 +1,3 @@
+{% docs pre_balances %}
+An array of lamport balances for each account in 'account_keys' before the transaction is executed. The order matches the 'account_keys' array. Used to track balance changes and verify transaction effects. Value is in lamports (1 SOL = 1,000,000,000 lamports).
+{% enddocs %} 

models/descriptions/pre_token_balances.md

@@ -0,0 +1,3 @@
+{% docs pre_token_balances %}
+An array of SPL token balances for each token account involved in the transaction, before execution. Each entry includes the token account address, mint, and raw amount. Used to track token transfers and verify effects. See: https://spl.solana.com/token
+{% enddocs %} 

models/descriptions/previous_block_hash.md

@@ -0,0 +1,10 @@
+{% docs previous_block_hash %}
+The cryptographic hash of the previous block in the Solana blockchain. Used to verify chain continuity and support block explorer lookups. This value is a base58-encoded string.
+
+**Example:**
+- "4g2j...8yP"
+
+**Business Context:**
+- Supports chain integrity, fork resolution, and auditability.
+- Used for block explorer navigation and verification.
+{% enddocs %} 

models/descriptions/previous_block_id.md

@@ -0,0 +1,10 @@
+{% docs previous_block_id %}
+The block ID (slot number) of the previous block in the Solana blockchain. Used to establish block lineage and support chain traversal.
+
+**Example:**
+- 12345677
+
+**Business Context:**
+- Enables block-to-block navigation and fork analysis.
+- Important for reconstructing chain history.
+{% enddocs %} 

models/descriptions/program_id.md

@@ -1,5 +1,12 @@
 {% docs program_id %}
+The unique public key (base58-encoded address) of a Solana program. This field identifies the on-chain program (smart contract) responsible for processing instructions, emitting events, or managing accounts. Used throughout Solana analytics models—including events, transactions, IDLs, and program activity tables—to join, filter, and analyze program-level data.
 
-An address that identifies the program that is being interacted with. I.E. which DEX for a swap or marketplace for an NFT sale.
+**Example:**
+- "4Nd1mY..."
+- "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA"
+
+**Business Context:**
+- Used as a join key for program activity, deployments, events, and interface changes.
+- Supports segmentation of activity by protocol, DEX, NFT marketplace, or other on-chain application.
 
 {% enddocs %}

models/descriptions/programs_used.md

@@ -0,0 +1,3 @@
+{% docs programs_used %}
+An array of program IDs (base58-encoded addresses) that this signer interacted with on a given day. Useful for protocol segmentation, user journey analysis, and ecosystem mapping. Example: ['TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA', 'Vote111111111111111111111111111111111111111'].
+{% enddocs %} 

models/descriptions/recent_block_hash.md

@@ -0,0 +1,3 @@
+{% docs recent_block_hash %}
+The hash of the most recent block prior to this transaction, as recorded on the Solana blockchain. Used to prevent transaction replay and ensure transaction freshness. This value is a base58-encoded string representing the block hash at the time the transaction was submitted. For more details, see the Solana documentation on transaction structure: https://docs.solana.com/developing/clients/jsonrpc-api#sendtransaction
+{% enddocs %} 

models/descriptions/signer.md

@@ -0,0 +1,3 @@
+{% docs signer %}
+The Solana address (public key, base58-encoded) that signed the transaction. Signers are responsible for authorizing transactions and may represent users, programs, or system accounts. In most cases, the first signer is the fee payer. This field enables analysis of user activity, protocol adoption, and transaction attribution. Example: '7Ggk7Q2...'.
+{% enddocs %} 

models/descriptions/signers.md

@@ -1,5 +1,14 @@
 {% docs signers %}
+An array of account addresses that have signed the transaction, authorizing its execution on the Solana blockchain. Each signer is a base58-encoded public key. Signers are required for transaction validity and may include the fee payer and other accounts with write permissions. The order of signers matches their appearance in the transaction's account_keys array. For more details, see: https://docs.solana.com/developing/programming-model/accounts#signers
 
-List of accounts that signed the transaction
+**Example:**
+- ["3N5k...", "7G8h..."]
 
+**Business Context:**
+- Used to verify transaction authorization and trace which accounts initiated or approved actions.
+- Important for analytics on user activity, multisig wallets, and program interactions.
+
+**Relationships:**
+- Subset of the 'account_keys' array.
+- The first signer is typically the fee payer.
 {% enddocs %}

models/descriptions/start_block_id.md

@@ -0,0 +1,13 @@
+{% docs start_block_id %}
+
+The block ID (slot number) where the ownership period for the token account begins (inclusive). Used to determine the time range during which a specific owner controlled the account.
+
+**Data type:** Integer (slot number)
+**Example:**
+- `123456789`
+
+**Business Context:**
+- Enables historical attribution of token balances and transfers to the correct owner.
+- Supports analytics on ownership changes, user activity, and protocol events.
+
+{% enddocs %} 

models/descriptions/submitted_by.md

@@ -1,5 +1,8 @@
-{% docs submitted_by%}
+{% docs submitted_by %}
+The identifier (e.g., address or username) of the entity or user who submitted the IDL for this program. Used for attribution, auditing, and developer analytics.
 
-The discord username for the individual that submitted the IDL, or 'flipside' if submitted by internal team
+**Example:**
+- "7G8h..."
+- "dev_user_123"
 
 {% enddocs %}

models/descriptions/table_dim_labels.md

@@ -1,5 +1,5 @@
 {% docs table_dim_labels %}
+Contains one row per labeled address or entity on the Solana blockchain. This table maps Solana addresses to human-readable labels, label types, subtypes, creators, and project names, supporting entity resolution, attribution, and analytics. Labels are classified by type (e.g., cex, dex, dapp, games) and subtype (e.g., contract_deployer, hot_wallet, token_contract) to enable granular segmentation and analysis. Data is sourced from a combination of automated algorithms, manual curation, protocol APIs, and community submissions. Automatic labels are generated based on on-chain behavior, contract deployments, and protocol integrations, while manual and community labels capture new protocols, exchange wallets, and trending addresses. All labels are reviewed for accuracy and can be updated or removed as needed. This model supports analytics on protocol adoption, ecosystem mapping, and address attribution for Solana.
 
-The labels table is a store of one-to-one address identifiers, or an address name. Labels are broken out into a "type" (such as cex, dex, dapp, games, etc.) and a "subtype" (ex: contract_deployer, hot_wallet, token_contract, etc.) in order to help classify each address name into similar groups. Our labels are sourced from many different places, but can primarily be grouped into two categories: automatic and manual. Automatic labels are continuously labeled based on certain criteria, such as a known contract deploying another contract, behavior based algorithms for finding deposit wallets, and consistent data pulls of custom protocol APIs. Manual labels are done periodically to find addresses that cannot be found programmatically such as finding new protocol addresses, centralized exchange hot wallets, or trending addresses. Labels can also be added by our community by using our add-a-label tool (https://science.flipsidecrypto.xyz/add-a-label/) or on-chain with near (https://near.social/lord1.near/widget/Form) and are reviewed by our labels team. A label can be removed by our labels team if it is found to be incorrect or no longer relevant; this generally will only happen for mislabeled deposit wallets.
 
 {% enddocs %}

models/descriptions/tables/dim_idls.md

@@ -0,0 +1,23 @@
+{% docs dim_idls %}
+
+## Description
+This table contains one row per program interface definition (IDL) on the Solana blockchain, but only includes programs for which we have the IDL and are actively decoding instructions. Programs listed here are the only ones for which decoded data is available in downstream models. It maps program IDs to their Interface Definition Language (IDL) documents, hashes, validity, activity status, and submission metadata. Each row represents a unique program interface definition, supporting analytics on program interfaces, upgrades, and developer activity.
+
+## Key Use Cases
+- Analyze program interface definitions and upgrades
+- Track program activity, validity, and deployment status
+- Support analytics on developer activity and protocol upgrades
+- Study program adoption, composability, and ecosystem growth
+- Enable time-series and event-based analytics on program interfaces
+
+## Important Relationships
+- Closely related to `core.fact_decoded_instructions` and `core.ez_events_decoded` (for decoded program calls)
+- Use `core.ez_events_decoded` to analyze program calls and usage
+
+## Commonly-used Fields
+- `program_id`: For program identification and joins
+- `idl`, `idl_hash`: For interface definition and verification
+- `is_valid`, `is_active`: For program status analytics
+- `last_activity_timestamp`, `date_submitted`: For activity and submission analysis
+
+{% enddocs %} 

models/descriptions/tables/ez_events_decoded.md

@@ -0,0 +1,26 @@
+{% docs ez_events_decoded %}
+
+## Description
+This table contains one row per decoded Solana record, mapping detailed program activity, event types, and instruction arguments as recorded on-chain. It only includes decoded data for programs for which we have the IDL (as listed in `core.dim_idls`). This table contains all the information in `core.fact_decoded_instructions`, but with additional extracted fields such as `decoded_accounts`, `decoded_args`, and `decoding_error`. For most analytics use cases, this table is preferred over `core.fact_decoded_instructions` due to its richer, more accessible structure. Each row represents a decoded event, supporting protocol usage analysis, event tracking, error monitoring, and attribution of accounts and signers.
+
+## Key Use Cases
+- Analyze decoded program activity and event types
+- Attribute events to accounts, signers, and protocols
+- Monitor protocol usage, event flows, and error rates
+- Support analytics on composable DeFi, NFT, and governance protocols
+- Enable flexible analytics on Solana program interactions and protocol activity
+
+## Important Relationships
+- Closely related to `core.fact_decoded_instructions` (for raw decoded instruction details), `core.fact_events` (for event context), and `core.fact_events_inner` (for inner/CPI events)
+- Use `core.fact_decoded_instructions` for raw instruction data if needed, but prefer this table for most analytics
+- Use `core.fact_events` and `core.fact_events_inner` for event-level context and protocol interactions
+- Joins with `core.fact_blocks` for block context and `core.fact_transactions` for transaction context
+
+## Commonly-used Fields
+- `block_timestamp`: For time-series and event sequencing analysis
+- `block_id`, `tx_id`, `index`, `inner_index`: For unique event identification and joins
+- `program_id`, `event_type`: For filtering by program or event type
+- `decoded_instruction`, `decoded_accounts`, `decoded_args`, `decoding_error`: For detailed event and error analytics
+- `signers`, `succeeded`: For user attribution and transaction outcome analysis
+
+{% enddocs %} 

models/descriptions/tables/ez_signers.md

@@ -0,0 +1,27 @@
+{% docs ez_signers %}
+
+## Description
+This table contains one row per unique Solana signer (address that signs transactions), with activity metrics, first/last transaction dates, programs used, and fee totals. Each row represents a unique signer and their activity profile, supporting analytics on user and protocol adoption, signer activity, and fee contributions across the Solana blockchain.
+
+## Key Use Cases
+- Analyze signer activity and protocol adoption
+- Track user and protocol engagement over time
+- Study fee contributions and transaction patterns
+- Segment signers by activity, protocol, and time
+- 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)
+- 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
+- Joins with `core.fact_blocks` for block context
+
+## Commonly-used Fields
+- `signer`: For user and protocol identification
+- `first_tx_date`, `last_tx_date`: For activity period analysis
+- `num_days_active`, `num_txs`: For engagement and usage analytics
+- `total_fees`: For fee contribution analysis
+- `programs_used`: For protocol usage segmentation
+
+{% enddocs %} 

models/descriptions/tables/fact_blocks.md

@@ -0,0 +1,21 @@
+{% docs fact_blocks %}
+
+## Description
+This table contains one record per block produced on the Solana blockchain, capturing block-level metadata including block identifiers, timestamps, hashes, network and chain information, and references to previous blocks. The table covers all finalized blocks on Solana mainnet and is updated as new blocks are processed. Data is sourced from on-chain block logs and normalized for analytics, supporting chain continuity and block production analysis.
+
+## Key Use Cases
+- Block-level analytics and network monitoring
+- Chain continuity and fork analysis
+- Time-series analysis of block production and network activity
+- Joining with transaction and event tables for multi-level analytics
+- Block explorer and dashboard backends
+
+## Important Relationships
+- Each block is linked to its predecessor via `previous_block_id` and `previous_block_hash` fields, supporting chain continuity analysis
+- Joins with `core.fact_transactions` for transaction-level context 
+
+## Commonly-used Fields
+- `block_id`: Unique identifier for each block, used for joins and traceability
+- `block_timestamp`: For time-series and block production analysis
+
+{% enddocs %} 

models/descriptions/tables/fact_decoded_instructions.md

@@ -0,0 +1,28 @@
+{% docs fact_decoded_instructions %}
+
+## Description
+This table contains one row per decoded instruction on the Solana blockchain, including program ID, event type, and detailed instruction metadata as recorded on-chain. It only includes decoded data for programs for which we have the IDL (as listed in `core.dim_idls`). For most analytics use cases, `core.ez_events_decoded` is preferred, as it contains all the information in this table plus additional extracted fields (such as decoded_accounts, decoded_args, decoding_error) for easier analysis. Each row represents a decoded instruction, supporting detailed analysis of protocol interactions, program calls, and event flows.
+
+## Key Use Cases
+- Analyze decoded instructions and program calls
+- Segment and classify protocol interactions by event type
+- Study program usage and protocol adoption
+- Support analytics on composable DeFi, NFT, and governance protocols
+- 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)
+- 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
+- Joins with `core.fact_blocks` for block context and `core.fact_transactions` for transaction context
+
+## Commonly-used Fields
+- `block_timestamp`: For time-series and instruction sequencing analysis
+- `block_id`, `tx_id`, `index`, `inner_index`: For unique instruction identification and joins
+- `program_id`, `event_type`: For filtering by program or event type
+- `decoded_instruction`: For detailed instruction analytics
+- `signers`: For user attribution and protocol usage analysis
+
+{% enddocs %} 

models/descriptions/tables/fact_events.md

@@ -0,0 +1,27 @@
+{% docs fact_events %}
+
+## Description
+This table records every event emitted by on-chain Solana programs during transaction execution. Each row represents a single event, including its type, the program that emitted it, and its position within the transaction. The table covers all events observed on Solana mainnet, including protocol-level and application-level activity. Events are uniquely identified by block, transaction, and event index. This model enables detailed analysis of program behavior, user actions, and protocol interactions at the event level, and is central to understanding the full scope of on-chain activity.
+
+## Key Use Cases
+- Analyze program interactions and instruction execution flow
+- Track specific program events, methods, or user actions
+- Protocol usage analytics and event-level activity monitoring
+- Avoid complex JSON array parsing from `core.fact_transactions` by using pre-parsed event fields
+- 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)
+- 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
+- Joins with `core.fact_blocks` for block context and `core.fact_transactions` for transaction context
+
+## Commonly-used Fields
+- `block_timestamp`: For time-series and event sequencing analysis
+- `block_id`, `tx_id`, `index`: For unique event identification and joins
+- `program_id`, `event_type`: For filtering by program or event type
+- `instruction`, `inner_instruction`: For instruction-level analytics
+- `signers`, `succeeded`: For user attribution and transaction outcome analysis
+
+{% enddocs %} 

models/descriptions/tables/fact_events_inner.md

@@ -0,0 +1,27 @@
+{% docs fact_events_inner %}
+
+## Description
+This table records every event that occurs within inner instructions (Cross-Program Invocations, or CPIs) on the Solana blockchain. Each row represents an event triggered by a program calling another program during transaction execution, capturing the full context of nested program interactions. The table covers all inner events observed on Solana mainnet, with detailed indexing to support analysis of deeply nested program flows. Events are uniquely identified by block, transaction, instruction, and inner instruction indices. This model enables granular tracing of protocol and application logic, supporting advanced analytics on composability, protocol integrations, and on-chain automation.
+
+## Key Use Cases
+- Analyze Cross-Program Invocations (CPIs) and nested program calls
+- Trace the full execution flow of complex Solana transactions
+- Study composability and protocol integrations
+- Support advanced analytics on on-chain automation and program-to-program interactions
+- 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)
+- 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
+- Joins with `core.fact_blocks` for block context and `core.fact_transactions` for transaction context
+
+## Commonly-used Fields
+- `block_timestamp`: For time-series and event sequencing analysis
+- `block_id`, `tx_id`, `instruction_index`, `inner_index`: For unique event identification and joins
+- `program_id`, `instruction_program_id`, `event_type`: For filtering by program or event type
+- `instruction`: For instruction-level analytics
+- `signers`, `succeeded`: For user attribution and transaction outcome analysis
+
+{% enddocs %} 

models/descriptions/tables/fact_sol_balances.md

@@ -0,0 +1,26 @@
+{% docs fact_sol_balances %}
+
+## Description
+This table contains one row per account and transaction where a native SOL (Solana) balance changes on the Solana blockchain. It tracks pre- and post-transaction balances for each account, including block, transaction, mint, and owner information. Balances are adjusted for SOL's 9 decimal places. Each row represents a unique account-transaction balance change event, enabling analysis of SOL balance changes, account activity, and ownership attribution at the transaction level.
+
+## Key Use Cases
+- Analyze SOL balance changes and account activity
+- Attribute SOL balances and transfers to the correct owner at any point in time
+- Support analytics on SOL flows, DeFi protocol activity, and wallet histories
+- Study SOL distribution, holder analysis, and whale tracking
+- 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)
+- 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
+- Joins with `core.fact_blocks` for block context and `core.fact_transactions` for transaction context
+
+## Commonly-used Fields
+- `block_timestamp`: For time-series and balance change analysis
+- `block_id`, `tx_id`, `tx_index`: For unique identification and joins
+- `account_address`, `mint`, `owner`: For account, token, and ownership analytics
+- `pre_balance`, `balance`: For before/after balance analysis
+
+{% enddocs %} 

models/descriptions/tables/fact_token_account_owners.md

@@ -0,0 +1,25 @@
+{% docs fact_token_account_owners %}
+
+## Description
+This table contains one row per token account address, recording the range of blocks during which a given owner controlled the account. It enables historical tracking of token account ownership on the Solana blockchain, supporting attribution of token balances and transfers to the correct owner at any point in time. Each row represents a unique ownership period for a token account, with start and end block identifiers. Null end_block_id indicates current ownership.
+
+## Key Use Cases
+- Attribute token balances and transfers to the correct owner at any point in time
+- Analyze historical changes in token account ownership
+- Support analytics on token flows, DeFi protocol activity, and wallet histories
+- Study token distribution, holder analysis, and whale tracking
+- 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)
+- 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
+- Joins with `core.fact_blocks` for block context and `core.fact_transactions` for transaction context
+
+## Commonly-used Fields
+- `account_address`, `owner`: For account and ownership analytics
+- `start_block_id`, `end_block_id`: For historical ownership period analysis
+- `fact_token_account_owners_id`: For unique identification and joins
+
+{% enddocs %} 

models/descriptions/tables/fact_token_balances.md

@@ -0,0 +1,26 @@
+{% docs fact_token_balances %}
+
+## Description
+This table contains one row per account and transaction where an SPL token balance changes on the Solana blockchain. It tracks pre- and post-transaction balances for each token account, including block, transaction, mint, and owner information. Balances are decimal adjusted according to the token's mint. Each row represents a unique token account-transaction balance change event, enabling analysis of token balance changes, account activity, and ownership attribution at the transaction level.
+
+## Key Use Cases
+- Analyze token balance changes and account activity
+- Attribute token balances and transfers to the correct owner at any point in time
+- Support analytics on token flows, DeFi protocol activity, and wallet histories
+- Study token distribution, holder analysis, and whale tracking
+- 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)
+- 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
+- Joins with `core.fact_blocks` for block context and `core.fact_transactions` for transaction context
+
+## Commonly-used Fields
+- `block_timestamp`: For time-series and balance change analysis
+- `block_id`, `tx_id`, `tx_index`: For unique identification and joins
+- `account_address`, `mint`, `owner`: For account, token, and ownership analytics
+- `pre_balance`, `balance`: For before/after balance analysis
+
+{% enddocs %} 

models/descriptions/tables/fact_transactions.md

@@ -0,0 +1,32 @@
+{% docs fact_transactions %}
+
+## 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.
+
+## 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
+- Success/failure rate analysis for transactions
+- Building time-series dashboards for network activity
+
+## 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.
+
+## 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
+
+{% enddocs %} 

models/descriptions/tables/fact_transfers.md

@@ -0,0 +1,26 @@
+{% docs fact_transfers %}
+
+## 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.
+
+## Key Use Cases
+- Track SOL or SPL token movements between accounts
+- Analyze payment flows and wallet transaction histories
+- Monitor large value transfers and whale activity
+- Build DeFi protocol volume and token flow analytics
+- Simplify asset movement analysis compared to parsing raw instructions
+
+## Important Relationships
+- 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
+- Use `core.ez_events_decoded` for detailed instruction and argument analysis (if program is being decoded)
+- Joins with `core.fact_transactions` for transaction context
+
+## Commonly-used Fields
+- `block_timestamp`: For time-series and transfer sequencing analysis
+- `block_id`, `tx_id`, `index`: For unique transfer identification and joins
+- `tx_from`, `tx_to`: For sender and recipient analysis
+- `amount`, `mint`: For value and token-specific analytics
+
+{% enddocs %} 

models/descriptions/total_fees.md

@@ -0,0 +1,3 @@
+{% docs total_fees %}
+The total amount of transaction fees (in lamports) paid by this signer. Only the first signer in a transaction pays the fee. This field may be null for non-fee-payer signers. Useful for analyzing fee contributions, protocol costs, and user economics. 1 SOL = 1,000,000,000 lamports.
+{% enddocs %} 

models/descriptions/tx_from.md

@@ -1,5 +1,12 @@
 {% docs tx_from %}
 
-The wallet address that initiated an event
+The base58-encoded wallet address that initiates the transfer event. For native SOL and SPL token transfers, this is the sender's address. Used to attribute outgoing asset movement to specific users or programs.
+
+**Data type:** String (base58 address)
+**Example:**
+- `7GgkQ2...`
+
+**Business Context:**
+- Enables analysis of asset outflows, user activity, and protocol interactions.
 
 {% enddocs %}

models/descriptions/tx_id.md

@@ -1,5 +1,13 @@
 {% docs tx_id %}
 
-A unique key that identifies a transaction
+The unique transaction signature (hash) for each transaction on the Solana blockchain. This field is a base58-encoded string, typically 88 characters in length, and serves as the primary identifier for transactions across all Solana data models. Used to join transaction data with related tables (blocks, events, transfers, logs, decoded instructions) and to trace the full lifecycle and effects of a transaction. Essential for transaction-level analytics, debugging, and cross-referencing with block explorers or Solana APIs.
+
+**Example:**
+- `5Nf6Q2k6v1Qw2k3v4Qw5Nf6Q2k6v1Qw2k3v4Qw5Nf6Q2k6v1Qw2k3v4Qw5Nf6Q2k6v1Qw2k3v4Qw`
+
+**Business Context:**
+- Enables precise tracking, auditing, and attribution of on-chain activity
+- Used for linking transactions to events, logs, and protocol actions
+- Critical for compliance, monitoring, and analytics workflows
 
 {% enddocs %}

models/descriptions/tx_index.md

@@ -1,5 +1,14 @@
 {% docs tx_index %}
+The position of this transaction within its containing block, starting from zero. Used to order transactions within a block and analyze intra-block activity.
 
-The index of the transaction in the block. Index of 0 is the first transaction executed in the block.
+**Example:**
+- 0
+- 15
 
+**Business Context:**
+- Useful for reconstructing block order and analyzing transaction sequencing.
+- Can be used to identify priority transactions or block congestion.
+
+**Relationships:**
+- Used with 'block_id' and 'block_timestamp' for full ordering.
 {% enddocs %}

models/descriptions/tx_size.md

@@ -0,0 +1,3 @@
+{% docs tx_size %}
+The size of the transaction in bytes, including all instructions, signatures, and account references. Used to analyze transaction complexity and network resource usage. See: https://docs.solana.com/developing/clients/jsonrpc-api#sendtransaction
+{% enddocs %} 

models/descriptions/tx_succeeded.md

@@ -1,5 +1,12 @@
 {% docs tx_succeeded %}
+Boolean flag indicating whether the transaction was successfully executed and confirmed on the Solana blockchain. A value of TRUE means the transaction was processed without errors; FALSE indicates failure due to program errors, insufficient funds, or other issues.
 
-True when a transaction is successful, otherwise false.
+**Example:**
+- true
+- false
+
+**Business Context:**
+- Used to filter for successful transactions in analytics and reporting.
+- Important for error analysis, user experience, and program debugging.
 
 {% enddocs %}

models/descriptions/tx_to.md

@@ -1,5 +1,12 @@
 {% docs tx_to %}
 
-The wallet address that receives tokens in an event
+The base58-encoded wallet address that receives the asset in a transfer event. For native SOL and SPL token transfers, this is the recipient's address. Used to attribute incoming asset movement to specific users or programs.
+
+**Data type:** String (base58 address)
+**Example:**
+- `9xQeWv...`
+
+**Business Context:**
+- Enables analysis of asset inflows, user activity, and protocol interactions.
 
 {% enddocs %}

models/descriptions/units_consumed.md

@@ -0,0 +1,3 @@
+{% docs units_consumed %}
+The number of compute units consumed by this transaction. Compute units measure the computational resources used and are used to calculate transaction fees. For more information, see: https://docs.solana.com/developing/runtime-facilities/programs#compute-budget
+{% enddocs %} 

models/descriptions/units_limit.md

@@ -0,0 +1,3 @@
+{% docs units_limit %}
+The maximum number of compute units allowed for this transaction, as set by the compute budget instruction. Transactions exceeding this limit will fail. For more information, see: https://docs.solana.com/developing/runtime-facilities/programs#compute-budget
+{% enddocs %} 

models/gold/core/core__dim_idls.yml

@@ -1,14 +1,14 @@
 version: 2
 models:
   - name: core__dim_idls
-    description: The status of Program IDL's submitted for decoding events 
+    description: "{{ doc('dim_idls') }}"
     columns:
       - name: PROGRAM_ID
         description: "{{ doc('program_id') }}"
         tests:
           - dbt_expectations.expect_column_to_exist
       - name: IDL
-        description: "The complete submitted IDL that defines the program"
+        description: "{{ doc('idl') }}"
         tests:
           - dbt_expectations.expect_column_to_exist
       - name: IDL_HASH
@@ -24,11 +24,11 @@ models:
         tests:
           - dbt_expectations.expect_column_to_exist
       - name: IS_ACTIVE
-        description: "If the program has decoded instructions in the last 14 days"
+        description: "{{ doc('is_active') }}"
         tests:
           - dbt_expectations.expect_column_to_exist
       - name: LAST_ACTIVITY_TIMESTAMP
-        description: "Most recent date that the program has decoded instructions"
+        description: "{{ doc('last_activity_timestamp') }}"
         tests:
           - dbt_expectations.expect_column_to_exist
       - name: SUBMITTED_BY
@@ -48,14 +48,14 @@ models:
         tests:
           - dbt_expectations.expect_column_to_exist
       - name: DIM_IDLS_ID
-        description: "{{ doc('id') }}"
-        tests:
-          - dbt_expectations.expect_column_to_exist
-      - name: MODIFIED_TIMESTAMP
-        description: "{{ doc('modified_timestamp') }}"
+        description: "{{ doc('pk') }}"
         tests:
           - dbt_expectations.expect_column_to_exist
       - name: INSERTED_TIMESTAMP
         description: "{{ doc('inserted_timestamp') }}"
         tests:
           - dbt_expectations.expect_column_to_exist
+      - name: MODIFIED_TIMESTAMP
+        description: "{{ doc('modified_timestamp') }}"
+        tests:
+          - dbt_expectations.expect_column_to_exist

models/gold/core/core__dim_labels.yml

@@ -1,41 +1,45 @@
 version: 2
 models:
   - name: core__dim_labels
-    description: '{{ doc("table_dim_labels") }}'   
-    tests:
-      - dbt_utils.unique_combination_of_columns:
-          combination_of_columns:
-            - ADDRESS
+    description: "{{ doc('table_dim_labels') }}"
     columns:
       - name: BLOCKCHAIN
-        description: The name of the blockchain
+        description: "{{ doc('blockchain') }}"
         tests:
-          - not_null
+          - dbt_expectations.expect_column_to_exist
       - name: CREATOR
-        description: The name of the creator of the label
+        description: "{{ doc('creator') }}"
         tests:
-          - not_null
-      - name: LABEL_TYPE
-        description: A high-level category describing the addresses main function or ownership
-        tests:
-          - not_null
-          - dbt_expectations.expect_column_values_to_be_in_set:
-              value_set: ['flotsam', 'nft', 'defi', 'dex', 'cex', 'dapp', 'token', 'operator', 'layer2', 'chadmin', 'bridge', 'games']
-      - name: LABEL_SUBTYPE
-        description: A sub-category nested within label type providing further detail
-        tests:
-          - not_null
-      - name: LABEL
-        description: Name of the controlling entity of the address
-        tests:
-          - not_null
+          - dbt_expectations.expect_column_to_exist
       - name: ADDRESS
-        description: Address that the label is for. This is the field that should be used to join other tables with labels. 
+        description: "{{ doc('address') }}"
         tests:
-          - not_null
+          - dbt_expectations.expect_column_to_exist
+      - name: LABEL_TYPE
+        description: "{{ doc('label_type') }}"
+        tests:
+          - dbt_expectations.expect_column_to_exist
+      - name: LABEL_SUBTYPE
+        description: "{{ doc('label_subtype') }}"
+        tests:
+          - dbt_expectations.expect_column_to_exist
+      - name: LABEL
+        description: "{{ doc('label') }}"
+        tests:
+          - dbt_expectations.expect_column_to_exist
+      - name: ADDRESS_NAME
+        description: "{{ doc('address_name') }}"
+        tests:
+          - dbt_expectations.expect_column_to_exist
       - name: DIM_LABELS_ID
-        description: '{{ doc("pk") }}'   
+        description: "{{ doc('pk') }}"
+        tests:
+          - dbt_expectations.expect_column_to_exist
       - name: INSERTED_TIMESTAMP
-        description: '{{ doc("inserted_timestamp") }}'   
+        description: "{{ doc('inserted_timestamp') }}"
+        tests:
+          - dbt_expectations.expect_column_to_exist
       - name: MODIFIED_TIMESTAMP
-        description: '{{ doc("modified_timestamp") }}' 
+        description: "{{ doc('modified_timestamp') }}"
+        tests:
+          - dbt_expectations.expect_column_to_exist 

models/gold/core/core__ez_events_decoded.yml

@@ -1,7 +1,7 @@
 version: 2
 models:
   - name: core__ez_events_decoded
-    description: Contains each event that occurs on Solana where the instruction has been decoded. A transaction can consist of more than one event and not all events within a transaction will be decoded.
+    description: "{{ doc('ez_events_decoded') }}"
     columns:
       - name: BLOCK_TIMESTAMP
         description: "{{ doc('block_timestamp') }}"
@@ -16,7 +16,7 @@ models:
         tests:
           - dbt_expectations.expect_column_to_exist
       - name: SIGNERS
-        description: List of accounts that signed the transaction
+        description: "{{ doc('signers') }}"
         tests: 
           - dbt_expectations.expect_column_to_exist
       - name: SUCCEEDED
@@ -24,7 +24,7 @@ models:
         tests: 
           - dbt_expectations.expect_column_to_exist
       - name: INDEX
-        description: Location of the event within the instructions of a transaction
+        description: "{{ doc('index') }}"
         tests:
           - dbt_expectations.expect_column_to_exist
       - name: INNER_INDEX
@@ -38,19 +38,19 @@ models:
       - name: EVENT_TYPE
         description: "{{ doc('event_type') }}"
       - name: DECODED_INSTRUCTION
-        description: An instruction specifies which program it is calling, which accounts it wants to read or modify, and additional data that serves as auxiliary input to the program
+        description: "{{ doc('decoded_instruction') }}"
         tests:
           - dbt_expectations.expect_column_to_exist
       - name: DECODED_ACCOUNTS
-        description: The accounts object within the decoded instruction
+        description: "{{ doc('decoded_accounts') }}"
         tests:
           - dbt_expectations.expect_column_to_exist
       - name: DECODED_ARGS
-        description: The args object within the decoded instruction
+        description: "{{ doc('decoded_args') }}"
         tests:
           - dbt_expectations.expect_column_to_exist
       - name: DECODING_ERROR
-        description: The error if the decoding failed
+        description: "{{ doc('decoding_error') }}"
         tests:
           - dbt_expectations.expect_column_to_exist
       - name: EZ_EVENTS_DECODED_ID

models/gold/core/core__ez_signers.yml

@@ -1,42 +1,42 @@
 version: 2
 models:
   - name: core__ez_signers
-    description: A table that contains aggregate information about addresses that have signed transactions.
+    description: "{{ doc('ez_signers') }}"
     columns:
       - name: SIGNER
-        description: The address of the user that initiated the transaction
+        description: "{{ doc('signer') }}"
         tests:
           - dbt_expectations.expect_column_to_exist
       - name: FIRST_TX_DATE
-        description: The first date that the wallet performed a transaction on.
+        description: "{{ doc('first_tx_date') }}"
         tests: 
           - dbt_expectations.expect_column_to_exist
       - name: FIRST_PROGRAM_ID
-        description: The ID of the first program this signer interacted with, excluding chain admin programs.
+        description: "{{ doc('first_program_id') }}"
         tests: 
           - dbt_expectations.expect_column_to_exist
       - name: LAST_TX_DATE
-        description: The date of the most recent transaction the signer has performed.
+        description: "{{ doc('last_tx_date') }}"
         tests: 
           - dbt_expectations.expect_column_to_exist
       - name: LAST_PROGRAM_ID
-        description: The ID of the last program this signer interacted with, excluding chain admin programs.
+        description: "{{ doc('last_program_id') }}"
         tests: 
           - dbt_expectations.expect_column_to_exist
       - name: NUM_DAYS_ACTIVE
-        description: A count of the total number of unique days that this signer has performed a transaction.
+        description: "{{ doc('num_days_active') }}"
         tests: 
           - dbt_expectations.expect_column_to_exist
       - name: NUM_TXS
-        description: The total number of distinct transactions initiated by this signer. 
+        description: "{{ doc('num_txs') }}"
         tests: 
           - dbt_expectations.expect_column_to_exist
       - name: TOTAL_FEES
-        description: The total amount of fees (in lamports) that the signer has paid on a given day. This field can be null, as only the first signer pays fees in a transaction.
+        description: "{{ doc('total_fees') }}"
         tests: 
           - dbt_expectations.expect_column_to_exist
       - name: PROGRAMS_USED
-        description: An array containing all program IDs a user interacted with on a given day.
+        description: "{{ doc('programs_used') }}"
         tests: 
           - dbt_expectations.expect_column_to_exist
       - name: EZ_SIGNERS_ID

models/gold/core/core__fact_blocks.yml

@@ -1,7 +1,7 @@
 version: 2
 models:
   - name: core__fact_blocks
-    description: Contains general information about each block produced on Solana. 
+    description: "{{ doc('fact_blocks') }}"
     columns:
       - name: BLOCK_ID
         description: "{{ doc('block_id') }}"
@@ -12,32 +12,38 @@ models:
         tests:
           - dbt_expectations.expect_column_to_exist
       - name: NETWORK
-        description: solana network name
+        description: "{{ doc('network') }}"
         tests:
           - dbt_expectations.expect_column_to_exist
       - name: CHAIN_ID
-        description: chain identifier, this will always be solana.  Field is used in joins with crosschain tables
+        description: "{{ doc('chain_id') }}"
         tests:
           - dbt_expectations.expect_column_to_exist
       - name: BLOCK_HEIGHT
-        description: heigh of the block
+        description: "{{ doc('block_height') }}"
         tests:
           - dbt_expectations.expect_column_to_exist
       - name: BLOCK_HASH
-        description: hash of the block
+        description: "{{ doc('block_hash') }}"
         tests:
           - dbt_expectations.expect_column_to_exist
       - name: PREVIOUS_BLOCK_ID
-        description: previous slot value
+        description: "{{ doc('previous_block_id') }}"
         tests:
           - dbt_expectations.expect_column_to_exist
       - name: PREVIOUS_BLOCK_HASH
-        description: previous block's hash value
+        description: "{{ doc('previous_block_hash') }}"
         tests:
           - dbt_expectations.expect_column_to_exist
       - name: FACT_BLOCKS_ID
-        description: '{{ doc("pk") }}'   
+        description: "{{ doc('pk') }}"
+        tests:
+          - dbt_expectations.expect_column_to_exist
       - name: INSERTED_TIMESTAMP
-        description: '{{ doc("inserted_timestamp") }}'   
+        description: "{{ doc('inserted_timestamp') }}"
+        tests:
+          - dbt_expectations.expect_column_to_exist
       - name: MODIFIED_TIMESTAMP
-        description: '{{ doc("modified_timestamp") }}' 
+        description: "{{ doc('modified_timestamp') }}"
+        tests:
+          - dbt_expectations.expect_column_to_exist 

models/gold/core/core__fact_decoded_instructions.yml

@@ -1,7 +1,7 @@
 version: 2
 models:
   - name: core__fact_decoded_instructions
-    description: Contains the decoded instructions for events. This table only contains instructions for the programs that we have idls for. More idls will continually be added.
+    description: "{{ doc('fact_decoded_instructions') }}"
     columns:
       - name: BLOCK_TIMESTAMP
         description: "{{ doc('block_timestamp') }}"
@@ -20,7 +20,7 @@ models:
         tests: 
           - dbt_expectations.expect_column_to_exist
       - name: INDEX
-        description: Location of the event within the instructions of a transaction
+        description: "{{ doc('index') }}"
         tests:
           - dbt_expectations.expect_column_to_exist
       - name: INNER_INDEX
@@ -34,9 +34,7 @@ models:
       - name: EVENT_TYPE
         description: "{{ doc('event_type') }}"
       - name: DECODED_INSTRUCTION
-        description: An instruction specifies which program it is calling, which accounts it wants to read or modify, and additional data that serves as auxiliary input to the program
-        tests:
-          - dbt_expectations.expect_column_to_exist
+        description: "{{ doc('decoded_instruction') }}"
       - name: FACT_DECODED_INSTRUCTIONS_ID
         description: '{{ doc("pk") }}'   
       - name: INSERTED_TIMESTAMP

models/gold/core/core__fact_events.yml

@@ -1,7 +1,7 @@
 version: 2
 models:
   - name: core__fact_events
-    description: Contains each event that occurs on Solana. A transaction can consist of more than one event. 
+    description: "{{ doc('fact_events') }}"
     columns:
       - name: BLOCK_TIMESTAMP
         description: "{{ doc('block_timestamp') }}"

models/gold/core/core__fact_events_inner.yml

@@ -1,7 +1,7 @@
 version: 2
 models:
   - name: core__fact_events_inner
-    description: Contains each event that occurs within the inner instructions of an instruction. These are also known as CPI (Cross-Program Invocations), where a program makes a call to another.
+    description: "{{ doc('fact_events_inner') }}"
     recent_date_filter: &recent_date_filter
       config:
         where: modified_timestamp >= current_date - 7
@@ -48,7 +48,7 @@ models:
           - dbt_expectations.expect_column_to_exist
           - not_null: *recent_date_filter
       - name: INSTRUCTION_PROGRAM_ID
-        description: "{{ doc('program_id') }}. For the instruction calling this inner instruction."
+        description: "{{ doc('instruction_program_id') }}"
         tests:
           - dbt_expectations.expect_column_to_exist  
           - not_null: *recent_date_filter

models/gold/core/core__fact_sol_balances.yml

@@ -1,7 +1,7 @@
 version: 2
 models:
   - name: core__fact_sol_balances
-    description: "{{ doc('sol_balance_table_doc') }}"
+    description: "{{ doc('fact_sol_balances') }}"
     recent_date_filter: &recent_date_filter
       config:
         where: modified_timestamp >= current_date - 7

models/gold/core/core__fact_token_account_owners.yml

@@ -1,22 +1,22 @@
 version: 2
 models:
   - name: core__fact_token_account_owners
-    description: Contains token account addresses and the range of blocks from which an address had ownership. Table updated daily.
+    description: "{{ doc('fact_token_account_owners') }}"
     columns:
       - name: ACCOUNT_ADDRESS
-        description: Address of token account
+        description: "{{ doc('account_address') }}"
         tests:
           - dbt_expectations.expect_column_to_exist
       - name: OWNER
-        description: Address of owner
+        description: "{{ doc('owner') }}"
         tests:
           - dbt_expectations.expect_column_to_exist
       - name: START_BLOCK_ID
-        description: Block where this ownership begins 
+        description: "{{ doc('start_block_id') }}"
         tests:
           - dbt_expectations.expect_column_to_exist
       - name: END_BLOCK_ID
-        description: Block where this ownership ends, null value represents current ownership 
+        description: "{{ doc('end_block_id') }}"
         tests:
           - dbt_expectations.expect_column_to_exist
       - name: FACT_TOKEN_ACCOUNT_OWNERS_ID

models/gold/core/core__fact_token_balances.yml

@@ -1,7 +1,7 @@
 version: 2
 models:
   - name: core__fact_token_balances
-    description: "{{ doc('token_balance_table_doc') }}"
+    description: "{{ doc('fact_token_balances') }}"
     recent_date_filter: &recent_date_filter
       config:
         where: modified_timestamp >= current_date - 7

models/gold/core/core__fact_transactions.yml

@@ -1,7 +1,7 @@
 version: 2
 models:
   - name: core__fact_transactions
-    description: A table that contains high level information about every transaction on the Solana blockchain. 
+    description: "{{ doc('fact_transactions') }}"
     columns:
       - name: BLOCK_TIMESTAMP
         description: "{{ doc('block_timestamp') }}"
@@ -12,7 +12,7 @@ models:
         tests:
           - dbt_expectations.expect_column_to_exist
       - name: RECENT_BLOCK_HASH
-        description: Previous block's hash value
+        description: "{{ doc('recent_block_hash') }}"
         tests:
           - dbt_expectations.expect_column_to_exist
       - name: TX_ID
@@ -20,7 +20,7 @@ models:
         tests:
           - dbt_expectations.expect_column_to_exist
       - name: FEE
-        description: Transaction fee (in lamports)
+        description: "{{ doc('fee') }}"
         tests:
           - dbt_expectations.expect_column_to_exist
       - name: SUCCEEDED
@@ -28,43 +28,51 @@ models:
         tests:
           - dbt_expectations.expect_column_to_exist
       - name: SIGNERS
-        description: List of accounts that signed the transaction
+        description: "{{ doc('signers') }}"
         tests:
           - dbt_expectations.expect_column_to_exist
       - name: ACCOUNT_KEYS
-        description: List of accounts that are referenced by pre/post sol/token balances objects
+        description: "{{ doc('account_keys') }}"
         tests:
           - dbt_expectations.expect_column_to_exist
       - name: PRE_BALANCES
-        description: List of pre-transaction balances for different accounts
+        description: "{{ doc('pre_balances') }}"
         tests:
           - dbt_expectations.expect_column_to_exist
       - name: POST_BALANCES
-        description: List of post-transaction balances for different accounts
+        description: "{{ doc('post_balances') }}"
         tests:
           - dbt_expectations.expect_column_to_exist
       - name: PRE_TOKEN_BALANCES
-        description: List of pre-transaction token balances for different token accounts
+        description: "{{ doc('pre_token_balances') }}"
         tests:
           - dbt_expectations.expect_column_to_exist
       - name: POST_TOKEN_BALANCES
-        description: List of post-transaction token balances for different token accounts
+        description: "{{ doc('post_token_balances') }}"
+        tests:
+          - dbt_expectations.expect_column_to_exist
+      - name: INSTRUCTIONS
+        description: "{{ doc('instructions') }}"
+        tests:
+          - dbt_expectations.expect_column_to_exist
+      - name: INNER_INSTRUCTIONS
+        description: "{{ doc('inner_instructions') }}"
         tests:
           - dbt_expectations.expect_column_to_exist
       - name: LOG_MESSAGES
-        description: Array of log messages written by the program for this transaction
+        description: "{{ doc('log_messages') }}"
         tests:
           - dbt_expectations.expect_column_to_exist
       - name: UNITS_CONSUMED
-        description: The number of compute units consumed by the program. 
+        description: "{{ doc('units_consumed') }}"
         tests:
           - dbt_expectations.expect_column_to_exist
       - name: UNITS_LIMIT
-        description: The max number of compute units that can be consumed by the program.
+        description: "{{ doc('units_limit') }}"
         tests:
           - dbt_expectations.expect_column_to_exist
       - name: TX_SIZE
-        description: The size of the transaction in bytes.
+        description: "{{ doc('tx_size') }}"
         tests:
           - dbt_expectations.expect_column_to_exist
       - name: TX_INDEX
@@ -74,6 +82,10 @@ models:
       - name: FACT_TRANSACTIONS_ID
         description: '{{ doc("pk") }}'   
       - name: INSERTED_TIMESTAMP
-        description: '{{ doc("inserted_timestamp") }}'   
+        description: "{{ doc('inserted_timestamp') }}"
+        tests:
+          - dbt_expectations.expect_column_to_exist
       - name: MODIFIED_TIMESTAMP
-        description: '{{ doc("modified_timestamp") }}' 
+        description: "{{ doc('modified_timestamp') }}"
+        tests:
+          - dbt_expectations.expect_column_to_exist 

models/gold/core/core__fact_transfers.yml

@@ -1,7 +1,7 @@
 version: 2
 models:
   - name: core__fact_transfers
-    description: Contains transfer events for Solana and spl-tokens. 
+    description: "{{ doc('fact_transfers') }}"
     columns:
       - name: BLOCK_TIMESTAMP
         description: "{{ doc('block_timestamp') }}"
@@ -21,16 +21,10 @@ models:
           - dbt_expectations.expect_column_to_exist
       - name: TX_FROM
         description: "{{ doc('tx_from') }}"
-        tests:
-          - dbt_expectations.expect_column_to_exist
       - name: TX_TO 
         description: "{{ doc('tx_to') }}"
-        tests:
-          - dbt_expectations.expect_column_to_exist
       - name: AMOUNT 
         description: "{{ doc('amount') }}"
-        tests:
-          - dbt_expectations.expect_column_to_exist
       - name: MINT
         description: "{{ doc('mint') }}"
         tests: