gold/core table desc 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/` 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 blockchain data:
+- Reference official protocol documentation for technical accuracy. Use web search to find official developer documentation for the subject blockchain.
+- Explain blockchain-specific concepts (gas, consensus, etc.)
+- Provide examples using the specific blockchain's conventions
+- 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.logs`
+- Utilizes token price data from `gold.prices` to compute USD columns
+
+## Commonly-used Fields
+- `tx_hash`: Essential for linking to transaction details and verification
+- `sender_id` and `receiver_id`: Core fields for flow analysis and network mapping
+- `amount_raw` 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. Utilize web search to find authentic and accurate developer documentation
+- Review technical specifications, whitepapers, and API documentation
+- Understand the blockchain's consensus mechanism, data structures, and conventions
+- Research common use cases and analytics patterns specific to the blockchain
+- Identify key technical concepts that need explanation (e.g., gas mechanics, consensus, token standards)
+
+**External Resources to Consult**
+- Official blockchain documentation
+- Developer guides and tutorials
+- Technical specifications and whitepapers
+- Community documentation and forums
+- Block explorers and API documentation
+
+### 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 (gas, consensus, 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/accumulator_root_hash.md

@@ -1,5 +1,14 @@
 {% docs accumulator_root_hash %}
 
-The root hash of a Merkle accumulator.
+The root hash of the Merkle accumulator, providing cryptographic proof of the blockchain's state at a given point.
+
+**Data type:** String
+**Example:**
+- 0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef
+
+**Business Context:**
+- Essential for blockchain state verification and integrity validation.
+- Critical for consensus mechanism analysis and state synchronization.
+- Enables verification of blockchain state consistency and security.
 
 {% enddocs %}

models/descriptions/address.md

@@ -1,5 +1,14 @@
 {% docs address %}
 
-Address unique to an individual wallet, validator, or token. 
+The unique address identifier for an individual wallet, validator, or token on the Aptos blockchain.
+
+**Data type:** String
+**Example:**
+- 0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef
+
+**Business Context:**
+- Primary identifier for tracking wallet activity and user behavior analysis.
+- Essential for DeFi protocol analysis and address labeling.
+- Enables correlation with address metadata for enhanced analytics and reporting.
 
 {% enddocs %}

models/descriptions/address_change.md

@@ -1,5 +1,14 @@
 {% docs address_change %}
 
-The top level address for this change.
+The top-level account address associated with this state change, representing the primary account affected by the change.
+
+**Data type:** String
+**Example:**
+- 0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef
+
+**Business Context:**
+- Essential for identifying the primary account affected by state changes.
+- Critical for account-based state change analysis and activity tracking.
+- Enables account-centric state change analytics and modification correlation.
 
 {% enddocs %}

models/descriptions/address_event.md

@@ -1,5 +1,14 @@
 {% docs address_event %}
 
-The top level address for this event.
+The top-level account address associated with this event, representing the primary account involved in the event.
+
+**Data type:** String
+**Example:**
+- 0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef
+
+**Business Context:**
+- Essential for identifying the primary account involved in events.
+- Critical for account-based event analysis and activity tracking.
+- Enables account-centric analytics and event correlation.
 
 {% enddocs %}

models/descriptions/amount.md

@@ -1,5 +1,15 @@
 {% docs amount %}
 
-The non-decimal adjusted amount of a token. For example, if a token has 18 decimals, then the amount of 1 token is 10^18.
+The non-decimal adjusted amount of a token, representing the raw on-chain value before decimal precision is applied.
+
+**Data type:** Decimal
+**Example:**
+- 1500000000000000000 (for 1.5 tokens with 18 decimals)
+- 1000000000000000000000 (for 1000 tokens with 18 decimals)
+
+**Business Context:**
+- Preserves the exact on-chain representation for precise calculations and verification.
+- Essential for blockchain-level accuracy and cross-reference with external data sources.
+- Used when decimal precision needs to be maintained for technical analysis.
 
 {% enddocs %}

models/descriptions/amount_unadj.md

@@ -1,5 +1,15 @@
 {% docs amount_unadj %}
 
-The non-decimal adjusted amount of a token. For example, if a token has 18 decimals, then the amount of 1 token is 10^18.
+The non-decimal adjusted amount of a token, representing the raw on-chain value before decimal precision is applied.
+
+**Data type:** Decimal
+**Example:**
+- 1500000000000000000 (for 1.5 tokens with 18 decimals)
+- 1000000000000000000000 (for 1000 tokens with 18 decimals)
+
+**Business Context:**
+- Preserves the exact on-chain representation for precise calculations and verification.
+- Essential for blockchain-level accuracy and cross-reference with external data sources.
+- Used when decimal precision needs to be maintained for technical analysis.
 
 {% enddocs %}

models/descriptions/amount_usd.md

@@ -1,5 +1,15 @@
 {% docs amount_usd %}
 
-The US dollar equivalent of the amount of a token.  
+The US dollar equivalent of the token amount, calculated by multiplying the decimal-adjusted amount by the token's USD price.
+
+**Data type:** Decimal
+**Example:**
+- 1500.00 (for 1.5 APT at $1000 per APT)
+- 1.00 (for 1 USDC at $1 per USDC)
+
+**Business Context:**
+- Enables financial analysis and value tracking in standardized USD terms.
+- Essential for portfolio valuation, revenue calculations, and financial reporting.
+- Supports cross-token comparisons and aggregate value analysis.
 
 {% enddocs %}

models/descriptions/block_hash.md

@@ -1,5 +1,14 @@
 {% docs block_hash %}
 
-The hash of the block header for a given block. 
+The cryptographic hash of the block header, providing a unique identifier for the block on the Aptos blockchain.
+
+**Data type:** String
+**Example:**
+- 0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef
+
+**Business Context:**
+- Essential for block verification and linking to external block explorers.
+- Critical for blockchain integrity verification and block identification.
+- Enables cross-reference with external blockchain data sources.
 
 {% enddocs %}

models/descriptions/block_number.md

@@ -1,5 +1,15 @@
 {% docs block_number %}
 
-Also known as block height. The block number, which indicates the length of the blockchain, increases after the addition of each new block.   
+Also known as block height. The block number indicates the position of a block in the blockchain, increasing sequentially after the addition of each new block.
+
+**Data type:** Integer
+**Example:**
+- 12345678
+- 98765432
+
+**Business Context:**
+- Primary identifier for ordering and filtering blockchain data chronologically.
+- Essential for block-level analysis and network growth tracking.
+- Enables correlation of transactions, transfers, and events to specific blocks.
 
 {% enddocs %}

models/descriptions/block_timestamp.md

@@ -1,5 +1,14 @@
 {% docs block_timestamp %}
 
-The date and time at which the block was produced.  
+The date and time at which the block was produced on the Aptos blockchain.
+
+**Data type:** Timestamp
+**Example:**
+- 2024-01-15 14:30:25.123456
+
+**Business Context:**
+- Primary field for time-series analysis and temporal filtering of blockchain activity.
+- Essential for trend analysis, volume calculations, and historical comparisons.
+- Enables time-based grouping and aggregation for analytics and reporting.
 
 {% enddocs %}

models/descriptions/blockchain.md

@@ -1,5 +1,16 @@
 {% docs blockchain %}
 
-The name of the blockchain
+The name of the blockchain where the address or entity is located.
+
+**Data type:** String
+**Example:**
+- aptos
+- ethereum
+- solana
+
+**Business Context:**
+- Essential for cross-chain analysis and blockchain identification.
+- Critical for multi-chain data correlation and blockchain-specific analytics.
+- Enables blockchain-based filtering and cross-chain reporting.
 
 {% enddocs %}

models/descriptions/change_address.md

@@ -1,5 +1,15 @@
 {% docs change_address %}
 
-The first segment of the inner change type
+The first segment of the inner change type, representing the account address where the change occurred.
+
+**Data type:** String
+**Example:**
+- 0x1
+- 0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef
+
+**Business Context:**
+- Essential for identifying the account where state changes occurred.
+- Critical for account-based state change analysis and modification tracking.
+- Enables account-specific state change analytics and modification correlation.
 
 {% enddocs %}

models/descriptions/change_data.md

@@ -1,5 +1,15 @@
 {% docs change_data %}
 
-The "data" object within this change.
+The data object within this state change, containing the specific information about what was modified.
+
+**Data type:** String (JSON)
+**Example:**
+- {"coin":{"value":"1000000"}}
+- {"balance":"500000"}
+
+**Business Context:**
+- Essential for understanding the specific data modifications in state changes.
+- Critical for state change analysis and data modification tracking.
+- Enables detailed state change analytics and modification reporting.
 
 {% enddocs %}

models/descriptions/change_index.md

@@ -1,5 +1,16 @@
 {% docs change_index %}
 
-Unique identifier for the change. This is a monotonically increasing integer that is incremented for each change. This is useful for determining the order of changes.
+Unique identifier for a state change within a transaction, representing the sequential order of state modifications during transaction execution.
+
+**Data type:** Integer
+**Example:**
+- 0 (first change in transaction)
+- 1 (second change in transaction)
+- 3 (fourth change in transaction)
+
+**Business Context:**
+- Essential for determining the chronological order of state changes within a transaction.
+- Critical for state transition analysis and transaction effect tracking.
+- Enables precise debugging and verification of transaction impact on blockchain state.
 
 {% enddocs %}

models/descriptions/change_module.md

@@ -1,5 +1,16 @@
 {% docs change_module %}
 
-The second segment of the inner change type
+The second segment of the inner change type, representing the module where the change occurred.
+
+**Data type:** String
+**Example:**
+- coin
+- staking
+- governance
+
+**Business Context:**
+- Essential for identifying the module where state changes occurred.
+- Critical for module-based state change analysis and protocol tracking.
+- Enables module-specific state change analytics and protocol correlation.
 
 {% enddocs %}

models/descriptions/change_resource.md

@@ -1,5 +1,16 @@
 {% docs change_resource %}
 
-The third segment of the inner change type
+The third segment of the inner change type, representing the specific resource that was modified.
+
+**Data type:** String
+**Example:**
+- CoinStore
+- StakePool
+- ValidatorSet
+
+**Business Context:**
+- Essential for identifying the specific resource that was modified in state changes.
+- Critical for resource-based state change analysis and modification tracking.
+- Enables resource-specific analytics and modification correlation.
 
 {% enddocs %}

models/descriptions/change_type.md

@@ -1,5 +1,18 @@
 {% docs change_type %}
 
-The "type" object from within this change. Values are: delete_resource, delete_table_item, write_module, write_resource, write_table_item.
+The type of state change that occurred during transaction execution, categorizing how the blockchain state was modified.
+
+**Data type:** String
+**Example:**
+- write_resource (created or updated a resource)
+- delete_resource (deleted a resource)
+- write_module (deployed or updated a module)
+- write_table_item (created or updated a table item)
+- delete_table_item (deleted a table item)
+
+**Business Context:**
+- Essential for understanding the nature and impact of state modifications.
+- Critical for resource lifecycle analysis and state transition tracking.
+- Enables debugging and verification of transaction effects on blockchain state.
 
 {% enddocs %}

models/descriptions/changes.md

@@ -1,5 +1,14 @@
 {% docs changes %}
 
-The changes that the transaction executed.
+The state changes that were executed by the transaction, representing modifications to the blockchain's global state.
+
+**Data type:** String (JSON)
+**Example:**
+- [{"type":"write_resource","address":"0x123...","data":{"coin":{"value":"1000000"}}}]
+
+**Business Context:**
+- Essential for understanding the impact and effects of transactions on blockchain state.
+- Critical for state transition analysis and transaction effect tracking.
+- Enables comprehensive transaction analysis and state modification monitoring.
 
 {% enddocs %}

models/descriptions/coin_type_hash.md

@@ -0,0 +1,14 @@
+{% docs coin_type_hash %}
+
+The cryptographic hash of the coin type, providing a unique identifier for the token's type definition.
+
+**Data type:** String
+**Example:**
+- 0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef
+
+**Business Context:**
+- Essential for token type identification and uniqueness verification.
+- Critical for token categorization and type-based analysis.
+- Enables type-based analytics and token classification.
+
+{% enddocs %} 

models/descriptions/creation_number.md

@@ -1,5 +1,16 @@
 {% docs creation_number %}
 
-Ceation number corresponding to the event stream originating from the given account.
+Creation number corresponding to the event stream originating from the given account, representing the order of events emitted by that account.
+
+**Data type:** Integer
+**Example:**
+- 0 (first event from account)
+- 5 (6th event from account)
+- 25 (26th event from account)
+
+**Business Context:**
+- Essential for event ordering and account event stream analysis.
+- Critical for event correlation and account activity tracking.
+- Enables event-based analytics and account behavior analysis.
 
 {% enddocs %}

models/descriptions/creator.md

@@ -1,5 +1,16 @@
 {% docs creator %}
 
-Name of the label creator - for now, this will always be "Flipside." 
+The name of the entity that created the label, typically representing the data provider or labeling source.
+
+**Data type:** String
+**Example:**
+- Flipside
+- Community
+- Protocol
+
+**Business Context:**
+- Essential for label attribution and data source tracking.
+- Critical for understanding label reliability and source credibility.
+- Enables source-based analytics and label quality assessment.
 
 {% enddocs %}

models/descriptions/creator_address.md

@@ -0,0 +1,14 @@
+{% docs creator_address %}
+
+The account address that created the token, representing the original issuer of the asset.
+
+**Data type:** String
+**Example:**
+- 0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef
+
+**Business Context:**
+- Essential for token origin tracking and creator analysis.
+- Critical for token issuer identification and creation verification.
+- Enables creator-based analytics and token origin analysis.
+
+{% enddocs %} 

models/descriptions/decimals.md

@@ -0,0 +1,16 @@
+{% docs decimals %}
+
+The number of decimal places used for the token's precision, determining the smallest unit of the token.
+
+**Data type:** Integer
+**Example:**
+- 8 (Bitcoin-style precision)
+- 18 (Ethereum-style precision)
+- 6 (USDC-style precision)
+
+**Business Context:**
+- Essential for accurate token amount calculations and decimal adjustment.
+- Critical for price calculations and financial reporting accuracy.
+- Enables precise token analytics and amount conversion operations.
+
+{% enddocs %} 

models/descriptions/domain.md

@@ -0,0 +1,16 @@
+{% docs domain %}
+
+The primary domain name component of an Aptos Name, representing the main identifier without subdomains or suffixes.
+
+**Data type:** String
+**Example:**
+- alice
+- bob
+- mydomain
+
+**Business Context:**
+- Essential for domain categorization and primary name analysis.
+- Critical for domain ownership tracking and registration analysis.
+- Enables domain-level analytics and trend analysis.
+
+{% enddocs %} 

models/descriptions/domain_with_suffix.md

@@ -0,0 +1,16 @@
+{% docs domain_with_suffix %}
+
+The domain name including the blockchain suffix, representing the complete domain identifier with the .apt extension.
+
+**Data type:** String
+**Example:**
+- alice.apt
+- bob.apt
+- mydomain.apt
+
+**Business Context:**
+- Essential for complete domain identification and suffix analysis.
+- Critical for domain registration tracking and ownership verification.
+- Enables suffix-based analytics and domain categorization.
+
+{% enddocs %} 

models/descriptions/epoch.md

@@ -1,5 +1,15 @@
 {% docs epoch %}
 
-An epoch in the Aptos blockchain is defined as a duration of time, in seconds, during which a number of blocks are voted on by the validators, the validator set is updated, and the rewards are distributed to the validators. The Aptos mainnet epoch is set as 7200 seconds (two hours).
+An epoch in the Aptos blockchain represents a duration of time during which blocks are voted on by validators, the validator set is updated, and rewards are distributed. The Aptos mainnet epoch is set to 7200 seconds (two hours).
+
+**Data type:** Integer
+**Example:**
+- 1234
+- 5678
+
+**Business Context:**
+- Essential for epoch-based analysis and validator performance tracking.
+- Critical for reward distribution analysis and consensus mechanism monitoring.
+- Enables epoch-level analytics and validator set change tracking.
 
 {% enddocs %}

models/descriptions/event_address.md

@@ -1,5 +1,15 @@
 {% docs event_address %}
 
-The first segment of the event type
+The first segment of the event type, representing the account address that emitted the event.
+
+**Data type:** String
+**Example:**
+- 0x1
+- 0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef
+
+**Business Context:**
+- Essential for identifying the source account that emitted the event.
+- Critical for event source analysis and account event tracking.
+- Enables event source analytics and account-based event correlation.
 
 {% enddocs %}

models/descriptions/event_data.md

@@ -1,5 +1,15 @@
 {% docs event_data %}
 
-The "data" object within this event.
+The data object within this event, containing the specific information and parameters of the event.
+
+**Data type:** String (JSON)
+**Example:**
+- {"amount":"1000000","account":"0x123..."}
+- {"token_id":"123","owner":"0x456..."}
+
+**Business Context:**
+- Essential for understanding the specific data and parameters in events.
+- Critical for event analysis and event parameter tracking.
+- Enables detailed event analytics and parameter-based reporting.
 
 {% enddocs %}

models/descriptions/event_index.md

@@ -1,5 +1,16 @@
 {% docs event_index %}
 
-Unique identifier for the event. This is a monotonically increasing integer that is incremented for each event. This is useful for determining the order of changes.
+Unique identifier for an event within a transaction, representing the sequential order of events emitted during transaction execution.
+
+**Data type:** Integer
+**Example:**
+- 0 (first event in transaction)
+- 1 (second event in transaction)
+- 5 (sixth event in transaction)
+
+**Business Context:**
+- Essential for determining the chronological order of events within a transaction.
+- Critical for event correlation and transaction flow analysis.
+- Enables precise event sequencing and debugging of complex transactions.
 
 {% enddocs %}

models/descriptions/event_module.md

@@ -1,5 +1,16 @@
 {% docs event_module %}
 
-The second segment of the event type
+The second segment of the event type, representing the module that emitted the event.
+
+**Data type:** String
+**Example:**
+- coin
+- staking
+- governance
+
+**Business Context:**
+- Essential for identifying the module that emitted the event.
+- Critical for module-based event analysis and protocol tracking.
+- Enables module-specific analytics and protocol event correlation.
 
 {% enddocs %}

models/descriptions/event_resource.md

@@ -1,5 +1,16 @@
 {% docs event_resource %}
 
-The third segment of the event type
+The third segment of the event type, representing the specific resource or event name.
+
+**Data type:** String
+**Example:**
+- DepositEvent
+- WithdrawEvent
+- TransferEvent
+
+**Business Context:**
+- Essential for identifying the specific event type and resource.
+- Critical for event categorization and specific event analysis.
+- Enables resource-specific analytics and event type correlation.
 
 {% enddocs %}

models/descriptions/event_root_hash.md

@@ -1,5 +1,14 @@
 {% docs event_root_hash %}
 
-The root hash for the event.
+The root hash of the event tree, providing cryptographic proof of all events emitted in the transaction.
+
+**Data type:** String
+**Example:**
+- 0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef
+
+**Business Context:**
+- Essential for event verification and integrity validation.
+- Critical for event-driven analytics and event correlation analysis.
+- Enables verification of event consistency and security.
 
 {% enddocs %}

models/descriptions/event_type.md

@@ -1,5 +1,16 @@
 {% docs event_type %}
 
-The full three-part descriptive type from event. The event type consists of the event_address :: event_module :: event_resource.
+The full three-part descriptive type of an event, consisting of the event_address, event_module, and event_resource identifiers.
+
+**Data type:** String
+**Example:**
+- 0x1::coin::DepositEvent
+- 0x1::coin::WithdrawEvent
+- 0xf22bede237a07e121b56d91a491eb7bcdfd1f5907926a9e58338f964a01b17fa::coin::DepositEvent
+
+**Business Context:**
+- Essential for categorizing and filtering events by their type and source.
+- Critical for DeFi protocol analysis and event-driven analytics.
+- Enables pattern recognition and event correlation across different contracts.
 
 {% enddocs %}

models/descriptions/events.md

@@ -1,5 +1,14 @@
 {% docs events %}
 
-The events that the transaction executed.
+The events that were emitted during transaction execution, representing notifications and state change announcements.
+
+**Data type:** String (JSON)
+**Example:**
+- [{"type":"0x1::coin::DepositEvent","data":{"amount":"1000000","account":"0x123..."}}]
+
+**Business Context:**
+- Essential for event-driven analytics and smart contract interaction monitoring.
+- Critical for DeFi protocol analysis and event pattern recognition.
+- Enables comprehensive transaction effect analysis and event correlation.
 
 {% enddocs %}

models/descriptions/expiration_timestamp.md

@@ -0,0 +1,14 @@
+{% docs expiration_timestamp %}
+
+The timestamp when the Aptos Name registration expires, indicating when the name will become inactive.
+
+**Data type:** Timestamp
+**Example:**
+- 2024-12-31 23:59:59.000000
+
+**Business Context:**
+- Essential for expiration monitoring and renewal analysis.
+- Critical for name lifecycle management and expiration tracking.
+- Enables expiration-based analytics and renewal prediction.
+
+{% enddocs %} 

models/descriptions/expiration_timestamp_secs.md

@@ -1,5 +1,15 @@
 {% docs expiration_timestamp_secs %}
 
-The time at which the transaction ceases to valid.
+The timestamp in seconds when the transaction ceases to be valid and can no longer be executed on the Aptos blockchain.
+
+**Data type:** Integer
+**Example:**
+- 1705344000 (January 15, 2024 00:00:00 UTC)
+- 1705430400 (January 16, 2024 00:00:00 UTC)
+
+**Business Context:**
+- Essential for transaction validity analysis and expiration monitoring.
+- Critical for understanding transaction lifecycle and time-based constraints.
+- Enables analysis of transaction timing and network congestion patterns.
 
 {% enddocs %}

models/descriptions/failed_proposer_indices.md

@@ -0,0 +1,15 @@
+{% docs failed_proposer_indices %}
+
+Array of indices representing validators that failed to propose blocks in the consensus round.
+
+**Data type:** Array
+**Example:**
+- [1, 3, 5]
+- []
+
+**Business Context:**
+- Essential for consensus mechanism analysis and validator performance tracking.
+- Critical for understanding block proposal failures and network health.
+- Enables validator performance analytics and consensus reliability reporting.
+
+{% enddocs %} 

models/descriptions/first_version.md

@@ -1,5 +1,15 @@
 {% docs first_version %}
 
-The version number of the first transaction in the block.
+The version number of the first transaction included in the block, representing the starting transaction version for that block.
+
+**Data type:** Integer
+**Example:**
+- 12345678
+- 98765432
+
+**Business Context:**
+- Essential for understanding the transaction range contained within each block.
+- Critical for block-level analysis and transaction sequencing verification.
+- Enables correlation between blocks and their contained transactions.
 
 {% enddocs %}

models/descriptions/from_address_transfer.md

@@ -1,5 +1,14 @@
 {% docs from_address_transfer %}
 
-The account address that sent the transfer.
+The account address that initiated the transfer, representing the sender of the tokens.
+
+**Data type:** String
+**Example:**
+- 0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef
+
+**Business Context:**
+- Essential for transfer flow analysis and sender identification.
+- Critical for account activity tracking and transfer origin analysis.
+- Enables sender-based analytics and transfer flow reporting.
 
 {% enddocs %}

models/descriptions/gas_unit_price.md

@@ -1,5 +1,15 @@
 {% docs gas_unit_price %}
 
-The cost per unit of gas, determining the transaction fee paid by the sender for each unit of computational resource consumed
+The cost per unit of gas, determining the transaction fee paid by the sender for each unit of computational resource consumed on the Aptos blockchain.
+
+**Data type:** Integer
+**Example:**
+- 100 (100 octa per gas unit)
+- 1000 (1000 octa per gas unit)
+
+**Business Context:**
+- Essential for calculating total transaction fees and network economics analysis.
+- Critical for understanding gas market dynamics and fee optimization.
+- Enables cost analysis and user experience optimization.
 
 {% enddocs %}

models/descriptions/gas_used.md

@@ -1,5 +1,16 @@
 {% docs gas_used %}
 
-The amount of gas used for the transaction
+The amount of gas units consumed during the execution of a transaction on the Aptos blockchain.
+
+**Data type:** Integer
+**Example:**
+- 1000
+- 5000
+- 15000
+
+**Business Context:**
+- Essential for gas fee calculations and network economics analysis.
+- Critical for understanding transaction complexity and resource consumption.
+- Enables optimization analysis and cost efficiency tracking.
 
 {% enddocs %}

models/descriptions/handle_change.md

@@ -1,5 +1,14 @@
 {% docs handle_change %}
 
-The top level handle for this change.
+The top-level handle for this state change, representing the resource handle that was modified.
+
+**Data type:** String
+**Example:**
+- 0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef
+
+**Business Context:**
+- Essential for identifying the resource handle affected by state changes.
+- Critical for resource-based state change analysis and handle tracking.
+- Enables handle-specific analytics and resource change correlation.
 
 {% enddocs %}

models/descriptions/id.md

@@ -0,0 +1,14 @@
+{% docs id %}
+
+Unique identifier for the block metadata record, providing a distinct reference for each block's metadata.
+
+**Data type:** String
+**Example:**
+- 0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef
+
+**Business Context:**
+- Essential for unique record identification and data integrity.
+- Critical for join operations and metadata record management.
+- Enables precise metadata retrieval and referential integrity maintenance.
+
+{% enddocs %} 

models/descriptions/inner_change_type.md

@@ -1,5 +1,15 @@
 {% docs inner_change_type %}
 
-The full three-part descriptive change type from change. The inner change type consists of the change_address :: change_module :: change_resource.
+The full three-part descriptive change type, consisting of change_address::change_module::change_resource.
+
+**Data type:** String
+**Example:**
+- 0x1::coin::CoinStore
+- 0x123::staking::StakePool
+
+**Business Context:**
+- Essential for comprehensive change type identification and categorization.
+- Critical for detailed state change analysis and type-based filtering.
+- Enables complete change type analytics and resource categorization.
 
 {% enddocs %}

models/descriptions/inserted_timestamp.md

@@ -1,5 +1,14 @@
 {% docs inserted_timestamp %}
 
-The utc timestamp at which the row was inserted into the table.
+The UTC timestamp when the row was inserted into the table, representing when the data was first recorded.
+
+**Data type:** Timestamp
+**Example:**
+- 2024-01-15 14:30:25.123456
+
+**Business Context:**
+- Essential for data lineage tracking and insertion timing analysis.
+- Critical for understanding data freshness and processing delays.
+- Enables data quality analysis and processing performance monitoring.
 
 {% enddocs %}

models/descriptions/is_active.md

@@ -0,0 +1,15 @@
+{% docs is_active %}
+
+Boolean value indicating whether the Aptos Name is currently active and valid for use.
+
+**Data type:** Boolean
+**Example:**
+- true (name is active)
+- false (name is inactive)
+
+**Business Context:**
+- Essential for filtering active names and status analysis.
+- Critical for name lifecycle analysis and expiration tracking.
+- Enables active name analytics and status-based reporting.
+
+{% enddocs %} 

models/descriptions/is_fungible.md

@@ -0,0 +1,15 @@
+{% docs is_fungible %}
+
+Boolean indicating whether the transfer was conducted using the legacy coin transfer mechanism (simpler, original method) or the fungible_asset module (newer, more flexible system for managing fungible assets).
+
+**Data type:** Boolean
+**Example:**
+- true (uses fungible_asset module)
+- false (uses legacy coin transfer mechanism)
+
+**Business Context:**
+- Essential for understanding transfer mechanism evolution and compatibility.
+- Critical for protocol analysis and transfer method categorization.
+- Enables mechanism-based analytics and transfer type reporting.
+
+{% enddocs %} 

models/descriptions/is_primary.md

@@ -0,0 +1,15 @@
+{% docs is_primary %}
+
+Boolean value indicating whether the Aptos Name is the primary name for the owner, representing their main identifier.
+
+**Data type:** Boolean
+**Example:**
+- true (primary name for owner)
+- false (secondary name for owner)
+
+**Business Context:**
+- Essential for identifying primary names and user profile analysis.
+- Critical for understanding name hierarchy and user preferences.
+- Enables primary name analytics and user identity analysis.
+
+{% enddocs %} 

models/descriptions/key_change.md

@@ -1,5 +1,15 @@
 {% docs key_change %}
 
-The key value for the write_table_item change
+The key value for the write_table_item change, representing the table key that was modified.
+
+**Data type:** String
+**Example:**
+- 0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef
+- "token_id_123"
+
+**Business Context:**
+- Essential for identifying the specific table key that was modified in state changes.
+- Critical for table-based state change analysis and key modification tracking.
+- Enables key-specific analytics and table modification correlation.
 
 {% enddocs %}

models/descriptions/label.md

@@ -1,5 +1,16 @@
 {% docs label %}
 
-The label or name of the address. 
+The human-readable label or name assigned to the address, providing a meaningful identifier for the entity.
+
+**Data type:** String
+**Example:**
+- Uniswap V3
+- Binance Hot Wallet
+- Aave Protocol
+
+**Business Context:**
+- Essential for human-readable entity identification and address mapping.
+- Critical for user-friendly analytics and address recognition.
+- Enables labeled entity analysis and address categorization reporting.
 
 {% enddocs %}

models/descriptions/label_subtype.md

@@ -1,5 +1,17 @@
 {% docs label_subtype %}
 
-Adds more detail to the label type. 
+A more detailed classification that adds specificity to the label type, providing granular categorization of the labeled entity.
+
+**Data type:** String
+**Example:**
+- dex
+- cex
+- lending
+- staking
+
+**Business Context:**
+- Essential for detailed entity classification and subtype analysis.
+- Critical for precise filtering and granular entity categorization.
+- Enables subtype-based analytics and detailed entity reporting.
 
 {% enddocs %}

models/descriptions/label_type.md

@@ -1,5 +1,17 @@
 {% docs label_type %}
 
-A broad category that describes what a label is representing. 
+A broad category that describes what a label is representing, providing high-level classification of the labeled entity.
+
+**Data type:** String
+**Example:**
+- protocol
+- exchange
+- wallet
+- contract
+
+**Business Context:**
+- Essential for label categorization and entity type analysis.
+- Critical for filtering and grouping labeled entities by type.
+- Enables type-based analytics and entity classification reporting.
 
 {% enddocs %}

models/descriptions/last_transaction_version.md

@@ -0,0 +1,15 @@
+{% docs last_transaction_version %}
+
+The version number of the last transaction that modified the Aptos Name, representing the most recent update.
+
+**Data type:** Integer
+**Example:**
+- 12345678
+- 98765432
+
+**Business Context:**
+- Essential for tracking name modification history and update analysis.
+- Critical for understanding name lifecycle and change tracking.
+- Enables version-based analytics and modification pattern recognition.
+
+{% enddocs %} 

models/descriptions/last_version.md

@@ -1,5 +1,15 @@
 {% docs last_version %}
 
-The version number of the last transaction in the block.
+The version number of the last transaction included in the block, representing the ending transaction version for that block.
+
+**Data type:** Integer
+**Example:**
+- 12345688
+- 98765442
+
+**Business Context:**
+- Essential for understanding the transaction range contained within each block.
+- Critical for block-level analysis and transaction sequencing verification.
+- Enables correlation between blocks and their contained transactions.
 
 {% enddocs %}

models/descriptions/max_gas_amount.md

@@ -1,5 +1,16 @@
 {% docs max_gas_amount %}
 
-The maximum amount of gas allocated for the execution of a transaction
+The maximum amount of gas units allocated for the execution of a transaction on the Aptos blockchain.
+
+**Data type:** Integer
+**Example:**
+- 10000
+- 50000
+- 100000
+
+**Business Context:**
+- Essential for gas fee analysis and transaction cost optimization.
+- Critical for understanding transaction complexity and resource requirements.
+- Enables gas efficiency analysis and user experience optimization.
 
 {% enddocs %}

models/descriptions/modified_timestamp.md

@@ -1,5 +1,14 @@
 {% docs modified_timestamp %}
 
-The utc timestamp at which the row was last modified.
+The UTC timestamp when the row was last modified, representing when the data was most recently updated.
+
+**Data type:** Timestamp
+**Example:**
+- 2024-01-15 14:30:25.123456
+
+**Business Context:**
+- Essential for data freshness analysis and update tracking.
+- Critical for understanding data modification patterns and change frequency.
+- Enables data quality monitoring and update performance analysis.
 
 {% enddocs %}

models/descriptions/name.md

@@ -0,0 +1,16 @@
+{% docs name %}
+
+The full name of the token, providing a human-readable identifier for the asset.
+
+**Data type:** String
+**Example:**
+- Aptos Coin
+- USD Coin
+- Tether USD
+
+**Business Context:**
+- Essential for token identification and human-readable reporting.
+- Critical for token categorization and name-based filtering.
+- Enables user-friendly analytics and token name analysis.
+
+{% enddocs %} 

models/descriptions/owner_address.md

@@ -0,0 +1,14 @@
+{% docs owner_address %}
+
+The account address that owns the Aptos Name, representing the entity with control over the name registration.
+
+**Data type:** String
+**Example:**
+- 0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef
+
+**Business Context:**
+- Essential for ownership analysis and name control tracking.
+- Critical for ownership transfer analysis and registration management.
+- Enables owner-based analytics and name portfolio analysis.
+
+{% enddocs %} 

models/descriptions/payload.md

@@ -1,5 +1,14 @@
 {% docs payload %}
 
-The data that is being carried by a transaction.
+The data payload carried by a transaction, containing the specific instructions and parameters for the transaction execution.
+
+**Data type:** String (JSON)
+**Example:**
+- {"function":"0x1::coin::transfer","type_arguments":["0x1::aptos_coin::AptosCoin"],"arguments":["0x123...","1000000"]}
+
+**Business Context:**
+- Essential for understanding the specific actions and parameters of transactions.
+- Critical for transaction analysis and smart contract interaction tracking.
+- Enables detailed transaction parsing and function call analysis.
 
 {% enddocs %}

models/descriptions/payload_function.md

@@ -1,5 +1,16 @@
 {% docs payload_function %}
 
-The function that is being called in the transaction payload.
+The specific function being called within the transaction payload, identifying the smart contract method to be executed.
+
+**Data type:** String
+**Example:**
+- 0x1::coin::transfer
+- 0x1::coin::register
+- 0xf22bede237a07e121b56d91a491eb7bcdfd1f5907926a9e58338f964a01b17fa::coin::mint
+
+**Business Context:**
+- Essential for categorizing transactions by function type and smart contract interaction.
+- Critical for DeFi protocol analysis and function call pattern recognition.
+- Enables transaction filtering and specific function usage analytics.
 
 {% enddocs %}

models/descriptions/pk.md

@@ -1,5 +1,14 @@
 {% docs pk %}
 
-The unique identifier for each row in the table.
+The unique primary key identifier for each row in the table, ensuring data integrity and uniqueness.
+
+**Data type:** String
+**Example:**
+- 0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef
+
+**Business Context:**
+- Essential for data integrity and unique row identification.
+- Critical for join operations and data relationship management.
+- Enables precise data retrieval and referential integrity maintenance.
 
 {% enddocs %}

models/descriptions/previous_block_votes_bitvec.md

@@ -0,0 +1,14 @@
+{% docs previous_block_votes_bitvec %}
+
+Bit vector representing the votes from validators on the previous block in the consensus mechanism.
+
+**Data type:** String
+**Example:**
+- 0x1234567890abcdef
+
+**Business Context:**
+- Essential for consensus mechanism analysis and validator voting tracking.
+- Critical for understanding consensus participation and voting patterns.
+- Enables voting analytics and consensus participation reporting.
+
+{% enddocs %} 

models/descriptions/prices_is_verified.md

@@ -0,0 +1,15 @@
+{% docs prices_is_verified %}
+
+Boolean value indicating whether the token has been verified by the price provider, ensuring data quality and reliability.
+
+**Data type:** Boolean
+**Example:**
+- true (token is verified)
+- false (token is not verified)
+
+**Business Context:**
+- Essential for data quality filtering and reliable price analysis.
+- Critical for risk assessment and verified token prioritization.
+- Enables quality-based analytics and verified token reporting.
+
+{% enddocs %} 

models/descriptions/proposer.md

@@ -1,5 +1,14 @@
 {% docs proposer %}
 
-The block proposer.
+The address of the validator that proposed the block in the Aptos consensus mechanism.
+
+**Data type:** String
+**Example:**
+- 0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef
+
+**Business Context:**
+- Essential for validator performance analysis and block proposer tracking.
+- Critical for consensus mechanism analysis and validator rotation monitoring.
+- Enables proposer-based analytics and validator participation analysis.
 
 {% enddocs %}

models/descriptions/registered_address.md

@@ -0,0 +1,14 @@
+{% docs registered_address %}
+
+The account address that the Aptos Name resolves to, representing the target address for name resolution.
+
+**Data type:** String
+**Example:**
+- 0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef
+
+**Business Context:**
+- Essential for name resolution analysis and address mapping.
+- Critical for understanding the relationship between names and addresses.
+- Enables resolution-based analytics and address correlation.
+
+{% enddocs %} 

models/descriptions/round.md

@@ -1,5 +1,15 @@
 {% docs round %}
 
-A round number is a shared counter used to select leaders during an epoch of the consensus protocol.
+A round number representing a shared counter used to select leaders during an epoch of the Aptos consensus protocol.
+
+**Data type:** Integer
+**Example:**
+- 12345
+- 67890
+
+**Business Context:**
+- Essential for consensus mechanism analysis and leader selection tracking.
+- Critical for block production analysis and consensus round monitoring.
+- Enables round-based analytics and consensus performance evaluation.
 
 {% enddocs %}

models/descriptions/sender.md

@@ -1,5 +1,14 @@
 {% docs sender %}
 
-Sender is the address of the originator account for a transaction. A transaction must be signed by the originator.
+The address of the originator account that initiated and signed the transaction on the Aptos blockchain.
+
+**Data type:** String
+**Example:**
+- 0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef
+
+**Business Context:**
+- Essential for user behavior analysis and wallet activity tracking.
+- Critical for transaction attribution and sender-based analytics.
+- Enables correlation with address labels for enhanced user profiling.
 
 {% enddocs %}

models/descriptions/sequence_number.md

@@ -1,5 +1,16 @@
 {% docs sequence_number %}
 
-The sequence number for an account indicates the number of transactions that have been submitted and committed on chain from that account. It is incremented every time a transaction sent from that account is executed or aborted and stored in the blockchain.
+The sequence number for an account indicates the number of transactions that have been submitted and committed on-chain from that account, incremented with each executed or aborted transaction.
+
+**Data type:** Integer
+**Example:**
+- 0 (first transaction from account)
+- 10 (11th transaction from account)
+- 100 (101st transaction from account)
+
+**Business Context:**
+- Essential for transaction ordering and account activity tracking.
+- Critical for preventing replay attacks and ensuring transaction uniqueness.
+- Enables account-based analytics and transaction sequence analysis.
 
 {% enddocs %}

models/descriptions/signature.md

@@ -1,5 +1,14 @@
 {% docs signature %}
 
-A signature is the result of hashing the signing message with the client's private key. By default Aptos uses the Ed25519 scheme to generate the signature of the raw transaction.
+A cryptographic signature generated by hashing the signing message with the client's private key using the Ed25519 scheme on the Aptos blockchain.
+
+**Data type:** String
+**Example:**
+- 0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef
+
+**Business Context:**
+- Essential for transaction verification and cryptographic security validation.
+- Critical for authenticating transaction origin and preventing unauthorized transactions.
+- Enables signature analysis and security auditing of blockchain transactions.
 
 {% enddocs %}

models/descriptions/state_change_hash.md

@@ -0,0 +1,14 @@
+{% docs state_change_hash %}
+
+The cryptographic hash of the state changes, providing verification of the blockchain state modifications.
+
+**Data type:** String
+**Example:**
+- 0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef
+
+**Business Context:**
+- Essential for state change verification and integrity validation.
+- Critical for blockchain state consistency and change tracking.
+- Enables state change analytics and integrity reporting.
+
+{% enddocs %} 

models/descriptions/state_checkpoint_hash.md

@@ -0,0 +1,14 @@
+{% docs state_checkpoint_hash %}
+
+The cryptographic hash of the state checkpoint, providing verification of the blockchain state at a specific point in time.
+
+**Data type:** String
+**Example:**
+- 0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef
+
+**Business Context:**
+- Essential for state checkpoint verification and integrity validation.
+- Critical for blockchain state consistency and checkpoint tracking.
+- Enables checkpoint analytics and state integrity reporting.
+
+{% enddocs %} 

models/descriptions/state_key_hash.md

@@ -0,0 +1,14 @@
+{% docs state_key_hash %}
+
+The cryptographic hash of the state key, providing a unique identifier for the specific state entry that was modified.
+
+**Data type:** String
+**Example:**
+- 0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef
+
+**Business Context:**
+- Essential for state key identification and change tracking.
+- Critical for state modification analysis and key-based correlation.
+- Enables state key analytics and modification pattern recognition.
+
+{% enddocs %} 

models/descriptions/subdomain.md

@@ -0,0 +1,16 @@
+{% docs subdomain %}
+
+The subdomain component of an Aptos Name, representing the hierarchical identifier below the primary domain.
+
+**Data type:** String
+**Example:**
+- test
+- dev
+- staging
+
+**Business Context:**
+- Essential for subdomain management and hierarchical name analysis.
+- Critical for organizational structure analysis and subdomain tracking.
+- Enables subdomain-level analytics and usage pattern recognition.
+
+{% enddocs %} 

models/descriptions/success.md

@@ -1,5 +1,15 @@
 {% docs success %}
 
-The boolean value indicating whether the transaction was successful or not.
+The boolean value indicating whether the transaction was successfully executed on the Aptos blockchain.
+
+**Data type:** Boolean
+**Example:**
+- true (transaction succeeded)
+- false (transaction failed)
+
+**Business Context:**
+- Essential for filtering successful transactions and analyzing failure rates.
+- Critical for accurate volume calculations and user experience analysis.
+- Enables debugging and error pattern recognition in transaction analysis.
 
 {% enddocs %}

models/descriptions/symbol.md

@@ -1,5 +1,16 @@
 {% docs symbol %}
 
-The symbol of asset.
+The symbol of the token involved in the action (e.g., APT, USDC, USDT). Used to identify the asset type in analytics and reporting.
+
+**Data type:** String
+**Example:**
+- APT
+- USDC
+- USDT
+
+**Business Context:**
+- Enables grouping and filtering of transfers by token.
+- Supports analytics on asset flows, protocol usage, and user preferences.
+- Provides human-readable identification for tokens in reports and dashboards.
 
 {% enddocs %}

models/descriptions/tables/core__dim_aptos_names.md

@@ -1,5 +1,30 @@
 {% docs core__dim_aptos_names %}
 
-This table contains information related to aptos names.
+## Description
+This table contains comprehensive information about Aptos Names, the blockchain's naming service that allows users to register human-readable domain names linked to their wallet addresses. The table tracks all registered names including domains, subdomains, ownership details, registration status, and expiration information. Aptos Names function similarly to ENS on Ethereum, providing a user-friendly way to identify and interact with addresses on the Aptos network through memorable names rather than long hexadecimal addresses.
+
+## Key Use Cases
+- Aptos Name registration and ownership analysis
+- Domain name tracking and expiration monitoring
+- User identity mapping and address resolution
+- Subdomain management and hierarchical name analysis
+- Primary name identification for user profile analysis
+- Name service adoption and usage pattern analysis
+
+## Important Relationships
+- Enriches address information across core models by providing human-readable names
+- Links to transaction data in `core.fact_transactions` through owner and registered addresses
+- Supports transfer analysis in `core.fact_transfers` and `core.ez_transfers` with named addresses
+- Enables user-friendly analytics by resolving addresses to readable names
+- Provides context for user behavior analysis through named entity identification
+
+## Commonly-used Fields
+- `token_name`: Full Aptos Name identifier for display and filtering
+- `domain`: Primary domain name for categorization and analysis
+- `owner_address`: Address that owns the name for ownership analysis
+- `registered_address`: Address the name resolves to for address mapping
+- `is_active`: Status indicator for valid and active names
+- `is_primary`: Flag for identifying primary names for users
+- `expiration_timestamp`: Critical for name renewal and expiration analysis
 
 {% enddocs %}

models/descriptions/tables/core__dim_labels.md

@@ -1,5 +1,29 @@
 {% docs core__dim_labels %}
 
-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.
+## Description
+This table provides comprehensive address labeling and classification for the Aptos blockchain, serving as a centralized repository of address identifiers and names. Labels are organized into hierarchical categories with "type" (e.g., cex, dex, dapp, games) and "subtype" (e.g., contract_deployer, hot_wallet, token_contract) to enable systematic address classification. The labeling system combines automatic algorithmic detection with manual curation, including community contributions through tools like the add-a-label platform. Labels can be dynamically updated and removed based on accuracy assessments and relevance changes.
+
+## Key Use Cases
+- Address identification and classification for analytics and reporting
+- DeFi protocol analysis by identifying protocol-related addresses
+- Exchange and institutional wallet tracking and monitoring
+- Contract deployment analysis and developer activity tracking
+- Security analysis and suspicious address identification
+- Network mapping and relationship analysis between labeled entities
+
+## Important Relationships
+- Enriches address information across all core models including `core.fact_transfers`, `core.ez_transfers`, and `core.fact_transactions`
+- Provides context for transaction analysis by identifying participant types
+- Supports DeFi analytics by classifying protocol-related addresses
+- Enables cross-chain analysis through consistent labeling standards
+- Links to community-contributed labels and external labeling systems
+
+## Commonly-used Fields
+- `address`: Primary identifier for linking to transaction and transfer data
+- `label_type`: High-level categorization for broad address classification
+- `label_subtype`: Detailed classification for specific address roles and functions
+- `label`: Human-readable name or identifier for the address
+- `creator`: Source of the label for attribution and quality assessment
+- `blockchain`: Chain identifier for cross-chain analysis
 
 {% enddocs %}

models/descriptions/tables/core__dim_tokens.md

@@ -1,5 +1,29 @@
 {% docs core__dim_tokens %}
 
-This table contains decimals, symbols, and names for on chain tokens.
+## Description
+This table serves as the comprehensive token metadata dimension for the Aptos blockchain, combining information from both legacy coin tokens and newer fungible assets. It provides essential token characteristics including names, symbols, decimal precision, creator addresses, and creation timestamps. The table unifies metadata from two different token standards on Aptos: the original coin module and the newer fungible asset module, ensuring complete coverage of all tokens on the network for analytics and display purposes.
+
+## Key Use Cases
+- Token identification and display with human-readable names and symbols
+- Decimal conversion for accurate financial calculations in transfer analysis
+- Token creation analysis and creator address tracking
+- Token verification and metadata validation for data quality
+- Token discovery and categorization for DeFi and NFT analytics
+- Historical token creation timeline analysis
+
+## Important Relationships
+- Enriches transfer data in `core.fact_transfers` and `core.ez_transfers` with token metadata
+- Provides decimal information for proper amount calculations in transfer analytics
+- Supports token verification processes and quality assessment
+- Links to creator addresses for token origin analysis
+- Enables token categorization and filtering across all core models
+
+## Commonly-used Fields
+- `token_address`: Primary identifier for linking to transfer and transaction data
+- `symbol`: Human-readable token symbol for easy identification and filtering
+- `decimals`: Critical for proper decimal conversion in financial calculations
+- `name`: Full token name for display and identification purposes
+- `creator_address`: Important for token origin analysis and creator tracking
+- `transaction_created_timestamp`: Essential for token creation timeline analysis
 
 {% enddocs %}

models/descriptions/tables/core__ez_native_transfers.md

@@ -1,5 +1,28 @@
 {% docs core__ez_native_transfers %}
 
-This table contains a flattened easy version of the native transfers. This table uses the fact_transfers table as a base and filters down to only aptos tokens. The logic used to derive this table requires the withdrawal event to occur in the previous event to the deposit event and also requires the withdrawal event to be the same amount as the deposit event. The only exception to that rule is when a "CoinRegisterEvent" occurs in between the withdraw and deposit events. Any transfers that do not meet this criteria are not included in this table.
+## Description
+This table provides a simplified, flattened view of native token transfers on the Aptos blockchain, specifically focusing on APT token movements between accounts. The table applies specific business logic to identify genuine transfer pairs by requiring withdrawal events to occur immediately before deposit events with matching amounts, with exceptions for intermediate "CoinRegisterEvent" occurrences. This filtering ensures that only actual token transfers are captured, excluding other blockchain events that might appear as transfers but represent different operations.
+
+## Key Use Cases
+- Native APT token flow analysis and tracking across the network
+- Wallet-to-wallet transfer monitoring and pattern recognition
+- Network fee analysis and gas cost tracking for APT transfers
+- User behavior analysis for native token movements
+- Transfer volume analysis and network activity monitoring
+- Simplified transfer analysis without complex event parsing
+
+## Important Relationships
+- Complements the broader transfer analysis available in `core.fact_transfers` and `core.ez_transfers`
+- Provides simplified transfer data for analytics that don't require complex event parsing
+- Supports native token-specific analysis separate from other token types
+- Enables straightforward sender-to-receiver transfer tracking
+
+## Commonly-used Fields
+- `from_address`: Essential for identifying transfer senders and outflow analysis
+- `to_address`: Critical for identifying transfer recipients and inflow analysis
+- `amount`: Transfer amount for value calculations and volume analysis
+- `tx_hash`: Important for linking to transaction details and verification
+- `block_timestamp`: Primary field for time-series analysis and trend detection
+- `success`: Transaction success status for filtering valid transfers
 
 {% enddocs %}

models/descriptions/tables/core__ez_transfers.md

@@ -1,6 +1,31 @@
 {% docs core__ez_transfers %}
 
-This table contains Deposit and Withdraw events from the coin module as well as  Deposit, Withdraw, DepositEvent, and WithdrawEvent from the fungible_asset module on the aptos blockchain. Note: transfers with a 0 amount are excluded. This EZ table also does decimal conversion, adds the token symbol, adds USD pricing, and adds the token_is_verified flag.
+## Description
+This table provides an enhanced, user-friendly version of token transfers on the Aptos blockchain with business logic applied for analytics. It builds upon `core.fact_transfers` by adding decimal conversion for proper token amounts, USD pricing for financial analysis, token symbols for readability, and verification status for data quality assessment. The table automatically handles both legacy coin transfers and newer fungible asset transfers, providing a unified view of all token movements with standardized formatting and pricing information.
+
+## Key Use Cases
+- Financial analysis with USD-denominated transfer values and proper decimal handling
+- Token flow analysis with human-readable symbols and verified token identification
+- DeFi protocol analytics requiring accurate token amounts and pricing data
+- Cross-chain bridge monitoring with standardized transfer information
+- Whale movement tracking with USD value context for large transfers
+- Token distribution studies with proper decimal-adjusted amounts and pricing
+
+## Important Relationships
+- Sources data from `core.fact_transfers` and applies business logic transformations
+- Enriches token information by joining with `core.dim_tokens` for decimals and symbols
+- Adds pricing data through `price.ez_prices_hourly` for USD value calculations
+- Supports native transfer analysis in `core.ez_native_transfers` with enhanced data
+- Provides foundation for DeFi and NFT analytics that require decimal-adjusted amounts
+
+## Commonly-used Fields
+- `amount`: Decimal-adjusted token amount for accurate financial calculations
+- `amount_usd`: USD value of transfers for financial analysis and value tracking
+- `symbol`: Human-readable token symbol for easy identification and filtering
+- `token_is_verified`: Quality indicator for data reliability and token authenticity
+- `tx_hash`: Essential for linking to transaction details and verification
+- `account_address`: Core field for identifying transfer participants and flow analysis
+- `block_timestamp`: Primary field for time-series analysis and trend detection
 
 {% enddocs %}
 

models/descriptions/tables/core__fact_blocks.md

@@ -1,8 +1,26 @@
 {% docs core__fact_blocks %}
 
-This table contains "block" level data for the Aptos blockchain. This table can be used to analyze trends at a block level, for example total transactions over time.
-"The Aptos blockchain doesn't have an explicit notion of a block — it only uses blocks for batching and executing transactions.
-A transaction at height 0 is the first transaction (genesis transaction), and a transaction at height 100 is the 101st transaction in the transaction store."
-from [aptos.dev docs] https://aptos.dev/reference/glossary/#version
+## Description
+This table contains block-level data for the Aptos blockchain, mapping the fundamental block structure that groups transactions for execution. The Aptos blockchain uses blocks for batching and executing transactions, where each block contains a range of transaction versions. A transaction at height 0 is the first transaction (genesis transaction), and a transaction at height 100 is the 101st transaction in the transaction store. This table provides the essential metadata for each block including timestamps, hash values, and transaction counts.
+
+## Key Use Cases
+- Block-level trend analysis and transaction volume monitoring over time
+- Network performance analysis and block production rate calculations
+- Transaction throughput analysis and network capacity planning
+- Block time analysis and network efficiency metrics
+- Historical block data for network health monitoring and anomaly detection
+
+## Important Relationships
+- Serves as the foundation for transaction-level analysis in `core.fact_transactions`
+- Provides block context for transfer events in `core.fact_transfers` and `core.ez_transfers`
+- Links to block metadata in `core.fact_transactions_block_metadata` for enhanced block analysis
+- Supports event analysis in `core.fact_events` by providing block-level context
+
+## Commonly-used Fields
+- `block_number`: Primary identifier for ordering and filtering blocks chronologically
+- `block_timestamp`: Essential for time-series analysis and temporal filtering of blockchain activity
+- `tx_count`: Critical for measuring transaction throughput and network activity levels
+- `block_hash`: Important for block verification and linking to external block explorers
+- `first_version` and `last_version`: Key for understanding the transaction range contained within each block
 
 {% enddocs %}

models/descriptions/tables/core__fact_changes.md

@@ -1,5 +1,30 @@
 {% docs core__fact_changes %}
 
-This table contains the flattened changes from the transaction. Each change will have a unique change index within a transaction.
+## Description
+This table contains flattened state changes from Aptos blockchain transactions, providing a comprehensive view of all modifications to the blockchain state. Each change represents a discrete modification to the global state, including resource modifications, account balance changes, module deployments, and other state transitions. The table captures the granular details of how transactions affect the blockchain state, with each change having a unique index within its parent transaction. This enables detailed analysis of state transitions and their impact on the network.
+
+## Key Use Cases
+- State change analysis and transaction impact assessment
+- Resource modification tracking and state transition monitoring
+- Account balance change analysis and financial state tracking
+- Module deployment and upgrade monitoring
+- State key analysis and storage pattern identification
+- Transaction effect analysis and state mutation tracking
+
+## Important Relationships
+- Provides detailed state change context for transaction analysis in `core.fact_transactions`
+- Links to transaction metadata for complete transaction effect analysis
+- Supports resource analysis and state modification tracking
+- Enables granular state transition analysis across all core models
+- Provides foundation for advanced state analysis and debugging
+
+## Commonly-used Fields
+- `tx_hash`: Essential for linking changes to their parent transactions
+- `change_index`: Unique identifier for ordering changes within a transaction
+- `change_type`: Critical for categorizing and filtering different types of state changes
+- `address`: Primary field for identifying which account's state was modified
+- `change_module` and `change_resource`: Important for understanding what was modified
+- `key` and `value`: Essential for analyzing the specific data that was changed
+- `block_timestamp`: Primary field for time-series analysis of state changes
 
 {% enddocs %}

models/descriptions/tables/core__fact_events.md

@@ -1,5 +1,31 @@
 {% docs core__fact_events %}
 
-This table contains the flattened events from the transaction. Each event will have a unique event index within a transaction.
+## Description
+This table contains flattened events from Aptos blockchain transactions, providing a comprehensive view of all events emitted during transaction execution. Events are the primary mechanism for smart contracts to communicate state changes and important occurrences to external observers. Each event represents a discrete occurrence within a transaction, such as token transfers, contract interactions, or state modifications, with a unique index within its parent transaction. This table enables detailed analysis of blockchain activity and smart contract behavior.
+
+## Key Use Cases
+- Event-driven analytics and smart contract interaction monitoring
+- Token transfer event analysis and flow tracking
+- DeFi protocol event monitoring and activity analysis
+- Contract interaction pattern recognition and behavior analysis
+- Event-based alerting and real-time monitoring
+- Smart contract debugging and event emission analysis
+
+## Important Relationships
+- Provides event context for transaction analysis in `core.fact_transactions`
+- Links to transfer data in `core.fact_transfers` and `core.ez_transfers` for comprehensive flow analysis
+- Supports state change analysis in `core.fact_changes` with event correlation
+- Enables event-driven analytics across all core models
+- Provides foundation for DeFi and NFT event analysis
+
+## Commonly-used Fields
+- `tx_hash`: Essential for linking events to their parent transactions
+- `event_index`: Unique identifier for ordering events within a transaction
+- `event_type`: Critical for categorizing and filtering different types of events
+- `event_address`: Primary field for identifying the contract that emitted the event
+- `event_module` and `event_resource`: Important for understanding the event source
+- `event_data`: Essential for analyzing the specific event payload and parameters
+- `account_address`: Key for identifying the account associated with the event
+- `block_timestamp`: Primary field for time-series analysis of events
 
 {% enddocs %}

models/descriptions/tables/core__fact_transactions.md

@@ -1,6 +1,30 @@
 {% docs core__fact_transactions %}
 
-This table contains transaction level data for the Aptos blockchain. Each transaction will have a unique transaction hash and version.
-For more information see [aptos.dev docs] Each transaction will have a unique transaction hash
+## Description
+This table contains comprehensive transaction-level data for the Aptos blockchain, serving as the primary fact table for all transaction analysis. Each transaction represents a discrete operation on the blockchain, including user transactions, system transactions, and consensus-related operations. The table captures complete transaction metadata including sender information, gas details, execution status, and cryptographic signatures. This table provides the foundation for understanding blockchain activity, user behavior, and network performance across all transaction types.
+
+## Key Use Cases
+- Transaction volume analysis and network activity monitoring
+- User behavior analysis and transaction pattern recognition
+- Gas fee analysis and network economics monitoring
+- Transaction success rate analysis and failure investigation
+- Sender activity tracking and wallet behavior analysis
+- Network performance analysis and transaction throughput monitoring
+
+## Important Relationships
+- Serves as the foundation for all transaction-related analysis across core models
+- Links to transfer data in `core.fact_transfers` and `core.ez_transfers` via `tx_hash`
+- Provides context for event analysis in `core.fact_events` and state changes in `core.fact_changes`
+- Supports block-level analysis in `core.fact_blocks` with transaction aggregation
+- Enables comprehensive transaction effect analysis across the entire data model
+
+## Commonly-used Fields
+- `tx_hash`: Primary identifier for linking to all related transaction data
+- `sender`: Essential for user behavior analysis and wallet tracking
+- `success`: Critical for transaction success rate analysis and failure investigation
+- `gas_used` and `gas_unit_price`: Important for gas fee analysis and network economics
+- `block_timestamp`: Primary field for time-series analysis and trend detection
+- `tx_type`: Key for categorizing and filtering different transaction types
+- `version`: Unique transaction identifier for ordering and version tracking
 
 {% enddocs %}

models/descriptions/tables/core__fact_transactions_block_metadata.md

@@ -1,5 +1,29 @@
 {% docs core__fact_transactions_block_metadata %}
 
-These transactions are inserted at the beginning of the block. A BlockMetadata transaction can also mark the end of an epoch and trigger reward distribution to validators.
+## Description
+This table contains BlockMetadata transactions from the Aptos blockchain, which are special system transactions inserted at the beginning of each block to provide essential block-level information. These transactions include consensus metadata such as proposer information, epoch details, round numbers, and validator voting data. BlockMetadata transactions also serve as epoch boundary markers, triggering reward distribution to validators when an epoch ends. The table provides critical infrastructure data for understanding Aptos's consensus mechanism and block production process.
+
+## Key Use Cases
+- Consensus mechanism analysis and validator performance tracking
+- Epoch boundary detection and reward distribution monitoring
+- Block proposer analysis and validator rotation tracking
+- Network governance and consensus participation analysis
+- Block production rate and network efficiency monitoring
+- Validator voting pattern analysis and consensus health assessment
+
+## Important Relationships
+- Provides block-level context for transaction analysis in `core.fact_transactions`
+- Links to block data in `core.fact_blocks` for comprehensive block analysis
+- Supports consensus analysis and validator performance tracking
+- Enables epoch-based analysis across all core models
+- Provides infrastructure context for network health monitoring
+
+## Commonly-used Fields
+- `block_number`: Primary identifier for linking to block-level analysis
+- `proposer`: Essential for validator performance and rotation analysis
+- `epoch`: Critical for epoch-based analysis and reward distribution tracking
+- `round`: Important for consensus round analysis and block production timing
+- `vm_status`: Transaction execution status for consensus health monitoring
+- `block_timestamp`: Primary field for time-series analysis of consensus activity
 
 {% enddocs %}

models/descriptions/tables/core__fact_transactions_state_checkpoint.md

@@ -1,5 +1,29 @@
 {% docs core__fact_transactions_state_checkpoint %}
 
-These transactions are appended at the end of the block and is used as a checkpoint milestone.
+## Description
+This table contains StateCheckpoint transactions from the Aptos blockchain, which are special system transactions appended at the end of each block to serve as checkpoint milestones. These transactions provide critical state verification data including state checkpoint hashes, accumulator root hashes, and event root hashes that enable the blockchain to maintain data integrity and support efficient state synchronization. StateCheckpoint transactions are essential for the blockchain's consensus mechanism and enable nodes to verify the integrity of the blockchain state at regular intervals.
+
+## Key Use Cases
+- Blockchain state integrity verification and checkpoint analysis
+- State synchronization monitoring and node health assessment
+- Consensus mechanism analysis and state verification tracking
+- Block finality analysis and state checkpoint milestone monitoring
+- Network security analysis and state tampering detection
+- State recovery and synchronization efficiency analysis
+
+## Important Relationships
+- Provides state verification context for transaction analysis in `core.fact_transactions`
+- Links to block data in `core.fact_blocks` for comprehensive block analysis
+- Supports consensus analysis and state integrity verification
+- Enables checkpoint-based analysis across all core models
+- Provides infrastructure context for network security monitoring
+
+## Commonly-used Fields
+- `block_number`: Primary identifier for linking to block-level analysis
+- `state_checkpoint_hash`: Essential for state integrity verification and checkpoint analysis
+- `accumulator_root_hash`: Critical for state accumulator verification and data integrity
+- `event_root_hash`: Important for event tree verification and event integrity
+- `vm_status`: Transaction execution status for checkpoint health monitoring
+- `block_timestamp`: Primary field for time-series analysis of checkpoint activity
 
 {% enddocs %}

models/descriptions/tables/core__fact_transfers.md

@@ -1,5 +1,30 @@
 {% docs core__fact_transfers %}
 
-This table contains Deposit and Withdraw events from the coin module as well as  Deposit, Withdraw, DepositEvent, and WithdrawEvent from the fungible_asset module on the aptos blockchain. Note: transfers with a 0 amount are excluded.
+## Description
+This table tracks all token transfers on the Aptos blockchain, capturing movements of both native tokens and fungible assets between accounts. The data combines two transfer mechanisms: the legacy coin transfer system (coin module) and the newer fungible asset module. The table includes Deposit and Withdraw events from both modules, with transfers having zero amounts excluded. Each transfer record contains complete transaction context, event metadata, and token information for comprehensive transfer analysis.
+
+## Key Use Cases
+- Token flow analysis and wallet tracking across the Aptos network
+- DeFi protocol volume measurements and liquidity flow monitoring
+- Cross-chain bridge activity tracking and asset movement analysis
+- Whale movement detection and large transfer alerts
+- Token distribution analysis and holder behavior studies
+- Network activity monitoring and transfer pattern recognition
+
+## Important Relationships
+- Serves as the foundation for enhanced transfer analysis in `core.ez_transfers` which adds decimal conversion, USD pricing, and token symbols
+- Links to transaction details in `core.fact_transactions` via `tx_hash` for complete transaction context
+- Connects to token metadata in `core.dim_tokens` via `token_address` for token information
+- Supports native transfer analysis in `core.ez_native_transfers` which applies specific filtering logic
+- Provides event context for `core.fact_events` analysis
+
+## Commonly-used Fields
+- `tx_hash`: Essential for linking to transaction details and verification
+- `account_address`: Core field for identifying transfer participants and flow analysis
+- `amount`: Critical for value calculations and financial analysis (raw amount before decimal adjustment)
+- `token_address`: Key for filtering by specific tokens and DeFi analysis
+- `block_timestamp`: Primary field for time-series analysis and trend detection
+- `transfer_event`: Important for understanding the type of transfer (Deposit/Withdraw)
+- `is_fungible`: Distinguishes between legacy coin transfers and newer fungible asset transfers
 
 {% enddocs %}

models/descriptions/to_address_transfer.md

@@ -1,5 +1,14 @@
 {% docs to_address_transfer %}
 
-The account address that received the transfer.
+The account address that received the transfer, representing the recipient of the tokens.
+
+**Data type:** String
+**Example:**
+- 0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef
+
+**Business Context:**
+- Essential for transfer flow analysis and recipient identification.
+- Critical for account activity tracking and transfer destination analysis.
+- Enables recipient-based analytics and transfer flow reporting.
 
 {% enddocs %}

models/descriptions/token_address.md

@@ -1,5 +1,15 @@
 {% docs token_address %}
 
-The full address of the token. This string contains the account,module, and resource.
+The full address of the token on the Aptos blockchain, containing the account, module, and resource identifiers.
+
+**Data type:** String
+**Example:**
+- 0x1::coin::AptosCoin (native APT token)
+- 0xf22bede237a07e121b56d91a491eb7bcdfd1f5907926a9e58338f964a01b17fa::coin::USDC
+
+**Business Context:**
+- Primary identifier for filtering and grouping transactions by specific tokens.
+- Essential for DeFi analysis, token flow tracking, and protocol-specific analytics.
+- Enables correlation with token metadata for symbol and decimal information.
 
 {% enddocs %}

models/descriptions/token_name.md

@@ -0,0 +1,16 @@
+{% docs token_name %}
+
+The full Aptos Name identifier, representing the complete human-readable name registered on the Aptos blockchain.
+
+**Data type:** String
+**Example:**
+- alice.apt
+- bob.test.apt
+- mydomain.apt
+
+**Business Context:**
+- Primary identifier for Aptos Name registration and ownership analysis.
+- Essential for user identity mapping and address resolution.
+- Enables human-readable analytics and user-friendly reporting.
+
+{% enddocs %} 

models/descriptions/token_standard.md

@@ -0,0 +1,15 @@
+{% docs token_standard %}
+
+The token standard used for the Aptos Name, indicating the technical specification and implementation details.
+
+**Data type:** String
+**Example:**
+- v1
+- v2
+
+**Business Context:**
+- Essential for technical analysis and standard compliance tracking.
+- Critical for understanding name implementation and feature availability.
+- Enables standard-based analytics and technical categorization.
+
+{% enddocs %} 

models/descriptions/transaction_created_timestamp.md

@@ -0,0 +1,14 @@
+{% docs transaction_created_timestamp %}
+
+The timestamp when the token was created, representing when the token was first deployed on the blockchain.
+
+**Data type:** Timestamp
+**Example:**
+- 2024-01-15 14:30:25.123456
+
+**Business Context:**
+- Essential for token age analysis and creation timing tracking.
+- Critical for token lifecycle analysis and creation event correlation.
+- Enables creation-based analytics and token age reporting.
+
+{% enddocs %} 

models/descriptions/transaction_version_created.md

@@ -0,0 +1,15 @@
+{% docs transaction_version_created %}
+
+The transaction version when the token was created, representing the specific transaction that deployed the token.
+
+**Data type:** Integer
+**Example:**
+- 12345678
+- 98765432
+
+**Business Context:**
+- Essential for token creation transaction identification and version tracking.
+- Critical for token deployment analysis and creation transaction correlation.
+- Enables version-based analytics and creation transaction reporting.
+
+{% enddocs %} 

models/descriptions/transfer_event.md

@@ -1,5 +1,15 @@
 {% docs transfer_event %}
 
-The type of transfer event. Value will either be  'WithdrawEvent' or 'DepositEvent'
+The type of transfer event, indicating whether tokens were withdrawn from or deposited to an account.
+
+**Data type:** String
+**Example:**
+- WithdrawEvent
+- DepositEvent
+
+**Business Context:**
+- Essential for categorizing transfer direction and flow analysis.
+- Critical for understanding token movement patterns and account behavior.
+- Enables transfer type analytics and flow direction reporting.
 
 {% enddocs %}

models/descriptions/tx_count.md

@@ -1,5 +1,16 @@
 {% docs tx_count %}
 
-The count of transactions in this block.
+The total count of transactions included in this block, representing the number of transactions processed in that block.
+
+**Data type:** Integer
+**Example:**
+- 10
+- 50
+- 100
+
+**Business Context:**
+- Essential for measuring transaction throughput and network capacity analysis.
+- Critical for block-level performance monitoring and network efficiency metrics.
+- Enables trend analysis of transaction volume over time.
 
 {% enddocs %}

models/descriptions/tx_hash.md

@@ -1,5 +1,14 @@
 {% docs tx_hash %}
 
-Transaction hash is a unique 66-character identifier that is generated when a transaction is executed. 
+Transaction hash is a unique 66-character identifier that is generated when a transaction is executed on the Aptos blockchain.
+
+**Data type:** String
+**Example:**
+- 0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef
+
+**Business Context:**
+- Primary identifier for linking transaction data across all related tables.
+- Essential for transaction verification and blockchain explorer lookups.
+- Enables correlation of transfers, events, and state changes to specific transactions.
 
 {% enddocs %}

models/descriptions/tx_type.md

@@ -1,5 +1,16 @@
 {% docs tx_type %}
 
-The type of the transaction. Values will be one of "block_metadata_transaction","state_checkpoint_transaction","user_transaction".
+The type of transaction executed on the Aptos blockchain, categorizing transactions by their purpose and origin.
+
+**Data type:** String
+**Example:**
+- user_transaction (regular user-initiated transactions)
+- block_metadata_transaction (system transactions for block metadata)
+- state_checkpoint_transaction (system transactions for state checkpoints)
+
+**Business Context:**
+- Essential for filtering and categorizing different types of blockchain activity.
+- Critical for separating user activity from system operations in analytics.
+- Enables focused analysis on specific transaction categories and use cases.
 
 {% enddocs %}

models/descriptions/value_change.md

@@ -1,5 +1,15 @@
 {% docs value_change %}
 
-The value for the write_table_item change
+The value for the write_table_item change, representing the new value that was written to the table.
+
+**Data type:** String (JSON)
+**Example:**
+- {"amount":"1000000"}
+- {"owner":"0x123..."}
+
+**Business Context:**
+- Essential for understanding the new value written in table modifications.
+- Critical for value-based state change analysis and modification tracking.
+- Enables value-specific analytics and table modification correlation.
 
 {% enddocs %}