upd descriptions and rules

.cursor/rules/cursor-rules-location.mdc

@@ -0,0 +1,83 @@
+---
+description: Cursor Rules Location
+globs: 
+alwaysApply: false
+---
+---
+description: Cursor Rules Location
+globs: *.mdc
+---
+# Cursor Rules Location
+
+Rules for placing and organizing Cursor rule files in the repository.
+
+<rule>
+name: cursor_rules_location
+description: Standards for placing Cursor rule files in the correct directory
+filters:
+  # Match any .mdc files
+  - type: file_extension
+    pattern: "\\.mdc$"
+  # Match files that look like Cursor rules
+  - type: content
+    pattern: "(?s)<rule>.*?</rule>"
+  # Match file creation events
+  - type: event
+    pattern: "file_create"
+
+actions:
+  - type: reject
+    conditions:
+      - pattern: "^(?!\\.\\/\\.cursor\\/rules\\/.*\\.mdc$)"
+        message: "Cursor rule files (.mdc) must be placed in the .cursor/rules directory"
+
+  - type: suggest
+    message: |
+      When creating Cursor rules:
+
+      1. Always place rule files in PROJECT_ROOT/.cursor/rules/:
+         ```
+         .cursor/rules/
+         ├── general-coding-standards.mdc
+         ├── dbt-model-standards.mdc
+         ├── project-context.mdc
+         └── cursor-rules-location.mdc
+         ```
+
+      2. Follow the naming convention:
+         - Use kebab-case for filenames
+         - Always use .mdc extension
+         - Make names descriptive of the rule's purpose
+
+      3. Directory structure:
+         ```
+         PROJECT_ROOT/
+         ├── .cursor/
+         │   └── rules/
+         │       ├── general-coding-standards.mdc
+         │       ├── dbt-model-standards.mdc
+         │       ├── project-context.mdc
+         │       └── cursor-rules-location.mdc
+         └── ...
+         ```
+
+      4. Never place rule files:
+         - In the project root
+         - In subdirectories outside .cursor/rules
+         - In any other location
+
+examples:
+  - input: |
+      # Bad: Rule file in wrong location
+      rules/my-rule.mdc
+      my-rule.mdc
+      .rules/my-rule.mdc
+
+      # Good: Rule file in correct location
+      .cursor/rules/my-rule.mdc
+    output: "Correctly placed Cursor rule file"
+
+metadata:
+  priority: high
+  version: 1.0
+</rule>

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

@@ -0,0 +1,130 @@
+---
+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: |-
+      [Clear description of what the model contains and its purpose]
+    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:** - Clear explanation of the model's purpose and contents
+- **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
+Must clearly explain:
+- What the model is mapping from the blockchain
+- What data it contains and its scope
+- How it relates to other models in the lineage
+- Any important transformations or business logic applied
+
+### 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
+
+## 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
+- 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
+
+## Documentation Review Process
+
+### Research Phase
+- Search official protocol documentation for technical concepts
+- Review developer guides and API documentation
+- Understand the blockchain's data structures and conventions
+- Research common use cases and analytics patterns
+
+### Analysis Phase
+- Read the dbt model SQL to understand transformations
+- Follow model lineage to understand data dependencies
+- Identify business logic and data quality considerations
+- Map columns to their blockchain equivalents
+
+### Writing Phase
+- Write clear, complete descriptions that stand alone
+- Use consistent terminology and formatting
+- Include examples for complex concepts
+- Ensure descriptions support LLM understanding
+
+### Quality Check
+- Verify technical accuracy against protocol documentation
+- Ensure descriptions are complete and self-contained
+- Check for consistency across related models
+- Validate that descriptions support common analytics use cases
+
+## File Organization
+- Store all documentation in `models/descriptions/` directory
+- Use consistent naming: `column_name.md` for individual columns with descriptions wrapped in the appropriate tags: `{% docs column_name %} DESCRIPTION {% enddocs %}`
+- Create table-level documentation in `table_name.md` files
+- Maintain `__overview__.md` for project-level context
+
+## Examples of Good Documentation
+```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 NEAR token, the amount_raw would be 1000000000000000000000000 (1e24) since NEAR has 24 decimal places. This field preserves the exact on-chain representation of the token amount for precise calculations and verification.
+{% enddocs %}
+```
+
+## 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

.cursor/rules/dbt-overview-standard.mdc

@@ -0,0 +1,159 @@
+---
+description: 
+globs: __overview__.md,models/descriptions/*,models/gold/**/*.sql
+alwaysApply: false
+---
+# dbt Overview Standards
+When working with dbt projects, ensure comprehensive documentation exists about the project and a base reference to the gold models exists in the `__overview__.md` file for both human and LLM consumption.
+
+## Project __overview__
+The file `models/descriptions/__overview__.md` is the entry point to the model description and documentation and must contain a rich description of what the project is.  
+The file MUST START AND END WITH DBT JINJA DOCS TAGS `{% docs __overview__ %}` and `{% ENDDOCS %}`
+
+## Quick Links Section Requirements
+The `__overview__.md` file MUST contain a "Quick Links to Table Documentation" section that provides direct navigation to all gold model documentation. This section must include a simple list, organized by gold schema, with the models and a hyperlink to the model documentation.
+
+### Required Elements:
+**Hyperlinks to Gold Model Documentation** - A comprehensive list of all gold models organized by schema. The schema can be inferred from the model name as the slug before the double underscore. For example, `core__fact_blocks` is a model named `fact_blocks` in the schema `core`.  
+
+### Gold Model Links Structure:
+The quicklinks section must be organized by schema and use the relative link to load the page generated by dbt documentation. The relative link structure is `#!/model/dbt_uniqueId` where dbt's `uniqueId` format is `node_type.project_name.model_name`. All of these `node_types` are `model`. `project_name` is the name of the dbt models project established in `dbt_project.yml` by the `name` variable. `model_name` is finally the name of the model as determed by the name of the sql file OR the value of `name` in the model's associated `.yml` file. For example, a uniqueId for Near's `fact_blocks` model would be `model.near_models.core__fact_blocks` making the relative URL `#!/model/model.near_models.core__fact_blocks`.  
+
+```markdown
+## **Quick Links to Table Documentation**
+
+**Click on the links below to jump to the documentation for each schema.**
+
+### [Schema Name] Tables (`[DATABASE]`.`[SCHEMA]`.`<table_name>`)
+
+**[Model Type Tables:]**
+
+- model_1
+- model_2
+```
+
+### Schema Organization Rules:
+1. **Group by Schema**: Organize models by their schema (core, defi, nft, price, social, governance, etc.)
+2. **Use Exact Schema Names**: Use the exact schema names as they appear in the database (e.g., `NEAR.CORE`, `NEAR.DEFI`, `NEAR.NFT`)
+3. **Model Type Subgrouping**: Within each schema, subgroup by model type:
+   - **Dimension Tables:** (dim_* models)
+   - **Fact Tables:** (fact_* models) 
+   - **Easy Views:** (ez_* models)
+4. **Link Format**: Use the exact dbt docs link format: `#!/model/model.[project_name].[schema]__[model]`
+5. **Model Naming**: Use the exact model name as it appears in the file system (without .sql extension)
+
+### Implementation Guidelines for Coding Agents:
+1. **Scan Directory Structure**: Read `models/gold/` directory to identify all schema subdirectories
+2. **Extract Model Names**: For each schema directory, list all `.sql` files and remove the `.sql` extension
+3. **Determine Schema Mapping**: Map directory names to database schema names:
+   - `gold/core/` → `NEAR.CORE`
+   - `gold/defi/` → `NEAR.DEFI` 
+   - `gold/nft/` → `NEAR.NFT`
+   - `gold/price/` → `NEAR.PRICE`
+   - `gold/social/` → `NEAR.SOCIAL`
+   - `gold/governance/` → `NEAR.GOV`
+   - `gold/stats/` → `NEAR.STATS`
+   - `gold/atlas/` → `NEAR.ATLAS`
+4. **Categorize Models**: Group models by prefix:
+   - `dim_*` → Dimension Tables
+   - `fact_*` → Fact Tables  
+   - `ez_*` → Easy Views
+   - `udf_*`, `udtf_*` → Custom Functions
+5. **Generate Links**: Create markdown links using the proper format
+6. **Maintain Order**: Keep models in alphabetical order within each category
+
+### Validation Requirements:
+- Every gold model must have a corresponding link
+- Links must use the correct dbt docs format
+- Schema names must match the actual database schema
+- Model names must match the actual file names (without .sql extension)
+- Links must be organized by schema and model type
+- All links must be functional and point to valid dbt documentation
+
+## XML Tag Requirements
+Every `__overview__.md` file MUST include structured `<llm>` XML tags for easy interpretation by an LLM.
+```xml
+<llm>
+<blockchain>[Protocol Name]</blockchain>
+<aliases>[Common Aliases]</aliases>
+<ecosystem>[Execution Environment or Layer Type, for example EVM, SVM, IBC, Layer 1, Layer 2]</ecosystem>
+<description>[Rich 3-5 sentence description of the blockchain, its consensus mechanism, key features, and developer/user benefits including if the blockchain was built for a specific usecase.]</description>
+<external_resources>
+    <block_scanner>[Link to the primary block scanner for the blockchain]</block_scanner>
+    <developer_documenation>[Link to the primary developer documentation, maintained by the blockchain devs]</developer_documentation>
+</external_resources>
+</llm>
+```
+Place these XML tags at the end of the documentation (BUT STILL BEFORE THE JINJA ENDDOCS TAG),
+
+## Automatic __overview__.md Updates
+The `__overview__.md` file MUST be automatically updated whenever any gold model is created, modified, or deleted to maintain documentation consistency.
+
+
+### Trigger Conditions:
+The following actions MUST trigger an automatic update to `__overview__.md`:
+1. **New Gold Model Created**: When a new `.sql` file is added to any `models/gold/*/` directory
+2. **Gold Model Modified**: When any existing `.sql` file in `models/gold/*/` directories is changed
+3. **Gold Model Deleted**: When any `.sql` file is removed from `models/gold/*/` directories
+4. **Gold Model Renamed**: When any `.sql` file in `models/gold/*/` directories is renamed
+5. **Schema Directory Changes**: When new schema directories are added to or removed from `models/gold/`
+
+### Update Process for Coding Agents:
+When any of the above trigger conditions occur, the coding agent MUST:
+
+1. **Scan Current Gold Models**: 
+   - Read the entire `models/gold/` directory structure
+   - Identify all `.sql` files across all schema subdirectories
+   - Extract model names (remove `.sql` extension)
+
+2. **Generate Updated Quicklinks Section**:
+   - Follow the Implementation Guidelines for Coding Agents (section above)
+   - Create a complete new quicklinks section with all current gold models
+   - Maintain proper schema organization and model type grouping
+
+3. **Update __overview__.md**:
+   - Preserve the XML tag section at the top
+   - Replace the entire "Quick Links to Table Documentation" section with the newly generated content
+   - Maintain all other existing content in the file
+   - Ensure proper markdown formatting and link structure
+
+4. **Validation Check**:
+   - Verify all gold models have corresponding links
+   - Confirm links use correct dbt docs format
+   - Check that schema names and model names are accurate
+   - Ensure alphabetical ordering within categories
+
+### Implementation Commands:
+When a gold model change is detected, the coding agent should execute these steps:
+
+```bash
+# 1. Scan for all gold models
+find models/gold/ -name "*.sql" -type f
+
+# 2. Generate updated quicklinks content
+# (Follow the Implementation Guidelines for Coding Agents)
+
+# 3. Update __overview__.md file
+# (Replace the Quick Links section while preserving other content)
+```
+
+### File Preservation Rules:
+When updating `__overview__.md`, the coding agent MUST:
+- **Preserve XML Tags**: Keep the `<llm>` XML section exactly as is
+- **Preserve Introduction**: Maintain the project description and usage instructions
+- **Preserve Other Sections**: Keep all sections after the Quick Links (Data Model Overview, Using dbt docs, etc.)
+- **Update Only Quick Links**: Replace only the "Quick Links to Table Documentation" section
+- **Maintain Formatting**: Preserve markdown formatting and structure
+
+### Error Handling:
+If the update process encounters issues:
+1. **Backup Original**: Create a backup of the original `__overview__.md` before making changes
+2. **Partial Updates**: If full regeneration fails, attempt to add/remove only the specific model that changed
+3. **Validation**: After any update, verify the file is still valid markdown and all links are functional
+4. **Rollback**: If validation fails, restore from backup and report the issue
+
+### Integration with dbt Workflow:
+This automatic update process should integrate with standard dbt workflows:
+- **Pre-commit**: Update `__overview__.md` before committing gold model changes
+- **Post-run**: Verify `__overview__.md` is current after dbt model runs
+- **CI/CD**: Include `__overview__.md` validation in continuous integration checks

.cursor/rules/general-coding-standards.mdc

@@ -0,0 +1,76 @@
+---
+description: 
+globs: 
+alwaysApply: true
+---
+# dbt Model Standards for Flipside Crypto
+
+## General Rules
+- Follow the existing code style and patterns in the codebase
+- Write clear, concise, and well-documented code
+- Use meaningful variable, function, column and model names
+- Handle errors gracefully and provide helpful error messages
+- Test your code thoroughly before submitting
+- Follow the existing project structure and conventions
+
+## Code Quality
+- Write self-documenting code with clear and consistent names
+- Use consistent formatting and indentation
+- Implement proper error handling and logging
+- Follow DRY (Don't Repeat Yourself) principles
+- Use meaningful commit messages
+- Use snake_case for all objects (tables, columns, models)
+- Maintain column naming consistency through the pipeline
+
+## dbt Model Structure
+- Models are connected through ref() and source() functions
+- Data flows from source -> bronze -> silver -> gold layers
+- Each model has upstream dependencies and downstream consumers
+- Column-level lineage is maintained through transformations
+- Parse ref() and source() calls to identify direct dependencies
+- Track column transformations from upstream models
+- Consider impact on downstream consumers
+- Preserve business logic across transformations
+
+## Model Naming and Organization
+- Follow naming patterns: bronze__, silver__, core__, fact_, dim__, ez__, where a double underscore indicates a break between a model schema and object name. I.e. core__fact_blocks equates to <database>.core.fact_blocks.
+- Organize by directory structure: bronze/, silver/, gold/, etc.
+- Upstream models appear on the LEFT side of the DAG
+- Current model is the focal point
+- Downstream models appear on the RIGHT side of the DAG
+
+## Modeling Standards
+- Use snake_case for all objects
+- Prioritize incremental processing always
+- Follow source/bronze/silver/gold layering
+- Document chain-specific assumptions
+- Include incremental predicates to improve performance
+- For gold layer models, include search optimization following Snowflake's recommended best practices
+- Cluster models on appropriate fields
+
+## Testing Requirements
+- Ensure proper token decimal handling
+- Implement unique tests for primary keys
+- Implement recency tests for tables that are expected to have frequent data updates
+- Add not_null tests for required columns
+- Use relationships tests for foreign keys
+
+## Performance Guidelines
+- Optimize for high TPS (blockchain data)
+- Handle large state change volumes efficiently
+- Index frequently queried dimensions
+- Consider partition pruning strategies
+- Implement appropriate clustering keys
+- Optimize database queries for large datasets
+- Use appropriate indexing strategies
+- Monitor resource usage and optimize accordingly
+- Consider the impact of changes on existing systems
+
+## Documentation
+- Document data sources
+- Map entity relationships
+- Include model descriptions in yml files per expanded rule [dbt-documentation-standards.mdc](mdc:.cursor/rules/dbt-documentation-standards.mdc)
+- Document column descriptions and business logic
+- Explain incremental logic and predicates
+- Note any data quality considerations
+

.cursor/rules/project-context.mdc

@@ -0,0 +1,69 @@
+---
+description: 
+globs: 
+alwaysApply: true
+---
+# Project Context
+
+This is a dbt project for analyzing NEAR Protocol blockchain data using Snowflake as the data warehouse.
+The models follow dimensional modeling principles with a focus on blockchain-specific patterns.
+
+## Domain Knowledge
+
+### NEAR Protocol
+- Account structure: implicit accounts vs named accounts
+- Transaction anatomy: signatures, actions, receipts, outcomes
+- Smart contract interactions: function calls, cross-contract calls
+- Gas mechanics: attached deposits, gas pricing, refunds
+- RPC methods: tx_status, block, receipt, access_key_changes
+- Sharding architecture: chunks, receipts across shards
+- Token standards: FT (NEP-141), NFT (NEP-171)
+
+### Data Structures
+- Blocks: height, timestamp, hash, author, chunks
+- Transactions: hash, signer_id, receiver_id, actions
+- Receipts: predecessor_id, receiver_id, action_kind
+- Execution Outcomes: status, gas_burnt, tokens_burnt
+- State Changes: account updates, code deployments, token transfers
+
+## Modeling Standards
+- Use snake_case for all objects
+- Implement incremental processing for core tables
+- Follow source/staging/core/mart layering
+- Handle chain reorganizations properly
+- Document chain-specific assumptions
+
+## Testing Requirements
+- Validate transaction integrity across receipt chains
+- Ensure proper token decimal handling
+- Test cross-shard transaction completeness
+- Verify action parsing accuracy
+- Monitor for chain reorganizations
+
+## Performance Guidelines
+- Optimize for NEAR's high TPS
+- Handle large state change volumes efficiently
+- Index frequently queried dimensions
+- Consider partition pruning strategies
+- Implement appropriate clustering keys
+
+## Documentation
+- Document RPC data sources
+- Explain transaction flow assumptions
+- Note sharding implications
+- Map entity relationships
+- Track known data anomalies
+
+## Metrics Focus
+- Transaction volumes and success rates
+- Active accounts and contract usage
+- Token transfers and balances
+- Gas consumption patterns
+- Protocol economics indicators
+
+## Error Handling
+- Handle invalid UTF-8 in contract data
+- Manage receipt execution failures
+- Track missing block segments
+- Monitor for RPC inconsistencies
+- Log unexpected action types

.gitignore

@@ -23,4 +23,4 @@ local*
 .user.yml
 .cursorignore
 .cursorrules
-.cursor/*
+.cursor/mcp.json

models/descriptions/__overview__.md

@@ -1,202 +1,100 @@
 {% docs __overview__ %}
 
-# Welcome to the Flipside Crypto NEAR Models Documentation
+# NEAR Protocol Blockchain Analytics
 
-## **What does this documentation cover?**
-
-The documentation included here details the design of the NEAR
-tables and views available via [Flipside Crypto.](https://flipsidecrypto.xyz/) For more information on how these models are built, please see [the github repository.](https://github.com/flipsideCrypto/near-models/)
-
-## **How do I use these docs?**
-
-The easiest way to navigate this documentation is to use the Quick Links below. These links will take you to the documentation for each table, which contains a description, a list of the columns, and other helpful information.
-
-If you are experienced with dbt docs, feel free to use the sidebar to navigate the documentation, as well as explore the relationships between tables and the logic building them.
-
-There is more information on how to use dbt docs in the last section of this document.
+This dbt project provides comprehensive analytics and data models for the NEAR Protocol blockchain. NEAR is a layer-1 blockchain designed for usability and scalability, featuring a unique sharding architecture and developer-friendly environment. The project transforms raw blockchain data into structured, queryable tables that support analytics, reporting, and business intelligence workflows.
 
 ## **Quick Links to Table Documentation**
 
 **Click on the links below to jump to the documentation for each schema.**
 
-### Core Tables (`NEAR`.`CORE`.`<table_name>`)
+### [Core Tables](`NEAR`.`CORE`)
 
 **Dimension Tables:**
-
-- [dim_address_labels](#!/model/model.near.core__dim_address_labels)
-- [dim_token_labels](#!/model/model.near.core__dim_token_labels)
+- [core__dim_address_labels](#!/model/model.near_models.core__dim_address_labels)
+- [core__dim_ft_contract_metadata](#!/model/model.near_models.core__dim_ft_contract_metadata)
 
 **Fact Tables:**
+- [core__fact_blocks](#!/model/model.near_models.core__fact_blocks)
+- [core__fact_developer_activity](#!/model/model.near_models.core__fact_developer_activity)
+- [core__fact_logs](#!/model/model.near_models.core__fact_logs)
+- [core__fact_receipts](#!/model/model.near_models.core__fact_receipts)
+- [core__fact_token_transfers](#!/model/model.near_models.core__fact_token_transfers)
+- [core__fact_transactions](#!/model/model.near_models.core__fact_transactions)
 
-- [fact_actions_events_function_call](#!/model/model.near.core__fact_actions_events_function_call)
-- [fact_actions_events](#!/model/model.near.core__fact_actions_events)
-- [fact_blocks](#!/model/model.near.core__fact_blocks)
-- [fact_logs](#!/model/model.near.core__fact_logs)
-- [fact_receipts](#!/model/model.near.core__fact_receipts)
-- [fact_token_metadata](#!/model/model.near.core__fact_token_metadata)
-- [fact_transactions](#!/model/model.near.core__fact_transactions)
-- [fact_transfers](#!/model/model.near.core__fact_transfers)
+**Easy Views:**
+- [core__ez_actions](#!/model/model.near_models.core__ez_actions)
+- [core__ez_native_daily_balances](#!/model/model.near_models.core__ez_native_daily_balances)
+- [core__ez_token_transfers](#!/model/model.near_models.core__ez_token_transfers)
 
-### DeFi Tables (`NEAR`.`DEFI`.`<table_name>`)
+### [DeFi Tables](`NEAR`.`DEFI`)
 
-- [fact_dex_swaps](#!/model/model.near.defi__fact_dex_swaps)
+**Fact Tables:**
+- [defi__fact_bridge_activity](#!/model/model.near_models.defi__fact_bridge_activity)
+- [defi__fact_dex_swaps](#!/model/model.near_models.defi__fact_dex_swaps)
+- [defi__fact_intents](#!/model/model.near_models.defi__fact_intents)
+- [defi__fact_lending](#!/model/model.near_models.defi__fact_lending)
 
-### Governance Tables (`NEAR`.`GOV`.`<table_name>`)
+**Easy Views:**
+- [defi__ez_bridge_activity](#!/model/model.near_models.defi__ez_bridge_activity)
+- [defi__ez_dex_swaps](#!/model/model.near_models.defi__ez_dex_swaps)
+- [defi__ez_intents](#!/model/model.near_models.defi__ez_intents)
+- [defi__ez_lending](#!/model/model.near_models.defi__ez_lending)
 
-- [dim_staking_pools](#!/model/model.near.gov__dim_staking_pools)
-- [fact_lockup_actions](#!/model/model.near.gov__fact_lockup_actions)
-- [fact_staking_actions](#!/model/model.near.gov__fact_staking_actions)
-- [fact_staking_pool_balances](#!/model/model.near.gov__fact_staking_pool_balances)
-- [fact_staking_pool_daily_balances](#!/model/model.near.gov__fact_staking_pool_daily_balances)
+### [NFT Tables](`NEAR`.`NFT`)
 
-### NFT Tables (`NEAR`.`NFT`.`<table_name>`)
+**Dimension Tables:**
+- [nft__dim_nft_contract_metadata](#!/model/model.near_models.nft__dim_nft_contract_metadata)
 
-- [fact_nft_mints](#!/model/model.near.nft__fact_nft_mints)
-- [fact_nft_transfers](#!/model/model.near.nft__fact_nft_transfers)
-- [ez_nft_sales](#!/model/model.near.nft__ez_nft_sales)
+**Fact Tables:**
+- [nft__fact_nft_mints](#!/model/model.near_models.nft__fact_nft_mints)
+- [nft__fact_nft_transfers](#!/model/model.near_models.nft__fact_nft_transfers)
 
-### Price Tables (`NEAR`.`PRICE`.`<table_name>`)
+**Easy Views:**
+- [nft__ez_nft_sales](#!/model/model.near_models.nft__ez_nft_sales)
 
-- [fact_prices](#!/model/model.near.price__fact_prices)
+### [Price Tables](`NEAR`.`PRICE`)
 
-### Social Tables (`NEAR`.`SOCIAL`.`<table_name>`)
+**Dimension Tables:**
+- [price__dim_asset_metadata](#!/model/model.near_models.price__dim_asset_metadata)
 
-- [fact_addkey_events](#!/model/model.near.social__fact_addkey_events)
-- [fact_decoded_actions](#!/model/model.near.social__fact_decoded_actions)
-- [fact_profile_changes](#!/model/model.near.social__fact_profile_changes)
-- [fact_posts](#!/model/model.near.social__fact_posts)
-- [fact_widget_deployments](#!/model/model.near.social__fact_widget_deployments)
+**Fact Tables:**
+- [price__fact_prices_ohlc_hourly](#!/model/model.near_models.price__fact_prices_ohlc_hourly)
 
-### Beta Tables (`NEAR`.`BETA`.`<table_name>`)
+**Easy Views:**
+- [price__ez_asset_metadata](#!/model/model.near_models.price__ez_asset_metadata)
+- [price__ez_prices_hourly](#!/model/model.near_models.price__ez_prices_hourly)
 
-- [github_activity](https://github.com/forgxyz/developer_report_near)
+### [Governance Tables](`NEAR`.`GOV`)
 
-### Custom Functions
+**Dimension Tables:**
+- [gov__dim_staking_pools](#!/model/model.near_models.gov__dim_staking_pools)
 
-- [udtf_call_contract_function](#!/macro/macro.near.create_UDTF_CALL_CONTRACT_FUNCTION_BY_HEIGHT)
+**Fact Tables:**
+- [gov__fact_lockup_actions](#!/model/model.near_models.gov__fact_lockup_actions)
+- [gov__fact_staking_actions](#!/model/model.near_models.gov__fact_staking_actions)
+- [gov__fact_staking_pool_balances](#!/model/model.near_models.gov__fact_staking_pool_balances)
+- [gov__fact_staking_pool_daily_balances](#!/model/model.near_models.gov__fact_staking_pool_daily_balances)
 
-Call a contract method via the [public NEAR RPC endpoint](https://docs.near.org/api/rpc/setup), modeled after the official documentation, [here](https://docs.near.org/api/rpc/contracts#call-a-contract-function).
+### [Stats Tables](`NEAR`.`STATS`)
 
-This function accepts 3 or 4 parameters:
+**Easy Views:**
+- [stats__ez_core_metrics_hourly](#!/model/model.near_models.stats__ez_core_metrics_hourly)
 
-- `account_id` STR (required)
-- This is the deployed contract_address you want to call.
+### [Atlas Tables](`NEAR`.`ATLAS`)
 
-- `method_name` STR (required)
-- This is the method on the contract to call.
+**Easy Views:**
+- [atlas__ez_supply](#!/model/model.near_models.atlas__ez_supply)
 
-- `args` OBJ (required)
-- Any requred or optional input parameters that the contract method accepts.
-- For best results, this should be formed by using the Snowflake function [`OBJECT_CONSTRUCT()`](https://docs.snowflake.com/en/sql-reference/functions/object_construct)
-
-- `block_id` INT (optional)
-- Pass a block height (note - hash not accepted) to call the method at a certain block in time.
-- If nothing is passed, the default behavior is `final` per the explanation [here](https://docs.near.org/api/rpc/setup#using-finality-param).
-- Note - when passing in a block id parameter, the archive node is called which may be considerably slower than the primary access node.
-
-**Important Note** - this is the public access endpoint, use responsibly.
-
-#### Examples
-
-Return 25 accounts that have authorized the contract `social.near`.
-
-```sql
-SELECT
-    *
-FROM
-    TABLE(
-        near.streamline.udtf_call_contract_function(
-            'social.near',
-            'get_accounts',
-            OBJECT_CONSTRUCT(
-                'from_index',
-                0,
-                'limit',
-                25
-            )
-        )
-    );
-
-```
-
-Get the staked balance of 100 addresses on the pool `staked.poolv1.near` at block `85,000,000`.
-
-```sql
-SELECT
-    DATA :result :block_height :: NUMBER AS block_height,
-    VALUE :account_id :: STRING AS account_id,
-    VALUE :can_withdraw :: BOOLEAN AS can_withdraw,
-    VALUE :staked_balance :: NUMBER / pow(
-        10,
-        24
-    ) AS staked_balance,
-    VALUE :unstaked_balance :: NUMBER / pow(
-        10,
-        24
-    ) AS unstaked_balance
-FROM
-    TABLE(
-        near.streamline.udtf_call_contract_function(
-            'staked.poolv1.near',
-            'get_accounts',
-            {
-                'from_index': 0,
-                'limit': 100
-            },
-            85000000
-        )
-    ),
-    LATERAL FLATTEN(decoded_result)
-```
-
-- [udf_get_chainhead](#!/macro/macro.near.create_UDF_GET_CHAINHEAD)
-
-Calls the `status` method on Near RPC and returns the block height of chainhead.
-
-```sql
-SELECT
-    NEAR.STREAMLINE.UDF_GET_CHAINHEAD()
-```
-
-## **Data Model Overview**
-
-The NEAR
-models are built a few different ways, but the core fact tables are built using three layers of sql models: **bronze, silver, and gold (or core).**
-
-- Bronze: Data is loaded in from the source as a view
-- Silver: All necessary parsing, filtering, de-duping, and other transformations are done here
-- Gold (or core): Final views and tables that are available publicly
-
-The dimension tables are sourced from a variety of on-chain and off-chain sources.
-
-Convenience views (denoted ez\_) are a combination of different fact and dimension tables. These views are built to make it easier to query the data.
-
-## **Using dbt docs**
-
-### Navigation
-
-You can use the `Project` and `Database` navigation tabs on the left side of the window to explore the models in the project.
-
-### Database Tab
-
-This view shows relations (tables and views) grouped into database schemas. Note that ephemeral models are _not_ shown in this interface, as they do not exist in the database.
-
-### Graph Exploration
-
-You can click the blue icon on the bottom-right corner of the page to view the lineage graph of your models.
-
-On model pages, you'll see the immediate parents and children of the model you're exploring. By clicking the Expand button at the top-right of this lineage pane, you'll be able to see all of the models that are used to build, or are built from, the model you're exploring.
-
-Once expanded, you'll be able to use the `--models` and `--exclude` model selection syntax to filter the models in the graph. For more information on model selection, check out the [dbt docs](https://docs.getdbt.com/docs/model-selection-syntax).
-
-Note that you can also right-click on models to interactively filter and explore the graph.
-
-### **More information**
-
-- [Flipside](https://flipsidecrypto.xyz/)
-- [Velocity](https://app.flipsidecrypto.com/velocity?nav=Discover)
-- [Tutorials](https://docs.flipsidecrypto.com/our-data/tutorials)
-- [Github](https://github.com/FlipsideCrypto/near-models)
-- [What is dbt?](https://docs.getdbt.com/docs/introduction)
+<llm>
+<blockchain>NEAR Protocol</blockchain>
+<aliases>NEAR, NEAR Protocol</aliases>
+<ecosystem>Layer 1, Sharded Blockchain</ecosystem>
+<description>NEAR Protocol is a layer-1 blockchain designed for usability and scalability, featuring a unique sharding architecture called Nightshade that enables high throughput and low latency. Built with a focus on developer experience, NEAR uses a proof-of-stake consensus mechanism and supports both Rust and AssemblyScript for smart contract development. The protocol features human-readable account names, low transaction fees, and fast finality, making it ideal for decentralized applications, DeFi protocols, and NFT marketplaces. NEAR's sharding technology allows the network to scale horizontally by processing transactions across multiple shards simultaneously, while maintaining security and decentralization.</description>
+<external_resources>
+    <block_scanner>https://explorer.near.org/</block_scanner>
+    <developer_documentation>https://docs.near.org/</developer_documentation>
+</external_resources>
+</llm>
 
 {% enddocs %} 

models/descriptions/action_data.md

@@ -1,5 +1,5 @@
 {% docs action_data %}
 
-A JSON object containing the argument data that was called by the `action_event`, if any.
+JSON object containing argument data for the receipt action. This field stores the parameters and arguments passed to the action, particularly for FunctionCall actions. The data structure varies by action type - for FunctionCall actions, it may include method names, arguments, and attached deposits. For Transfer actions, it contains the amount being transferred. This field enables detailed analysis of what specific operations were performed within each action.
 
 {% enddocs %}

models/descriptions/action_index.md

@@ -1,5 +1,5 @@
 {% docs action_index %}
 
-The index of the current `action_name` and `action_data` in the order in which it appeared in the transaction.
+Index of the action within the transaction. This field indicates the position of the action in the sequence of actions within the transaction. Actions are processed in order, and this index helps maintain the chronological sequence and relationship between multiple actions in a single transaction. The first action has index 0, the second has index 1, and so on.
 
 {% enddocs %}

models/descriptions/action_name.md

@@ -1,5 +1,5 @@
 {% docs action_name %}
 
-The name of the action performed.
+Name of the action performed. Most often one of: Transfer, FunctionCall, Delegate, AddKey, CreateAccount. Rarely: DeleteKey, DeleteAccount, Stake, DeployContract. This field identifies the specific type of action that was executed within the transaction. FunctionCall actions are the most common for smart contract interactions, while Transfer actions handle token movements, and other actions manage account permissions and creation.
 
 {% enddocs %}

models/descriptions/address_name.md

@@ -1,5 +1,5 @@
 {% docs address_name %}
 
-The name attributed to the address.
+The name attributed to the address. This is a human-readable identifier that provides context about what the address represents, such as "Binance Hot Wallet", "Uniswap V3 Router", or "NEAR Foundation Treasury". Address names help users understand the purpose and ownership of blockchain addresses without needing to memorize cryptographic addresses.
 
 {% enddocs %}

models/descriptions/amount_adj.md

@@ -1,5 +1,5 @@
 {% docs amount_adj %}
 
-A decimal adjusted amount (of tokens, price, etc.). 
+Decimal adjusted amount of tokens (as float, rounded - use this generally). This field provides the token amount after applying the appropriate decimal precision adjustments based on the token's decimal places. For example, if transferring 1 NEAR token, the amount_adj would be 1.0 after dividing the raw amount (1e24) by 10^24. This field is the most commonly used representation for token amounts in analytics and reporting as it provides human-readable values.
 
 {% enddocs %}

models/descriptions/amount_precise.md

@@ -0,0 +1,5 @@
+{% docs amount_precise %}
+
+Decimal adjusted amount of tokens (as text, for highest precision). This field provides the token amount after applying decimal precision adjustments, stored as a text string to maintain the highest possible precision without any floating-point rounding errors. This format is particularly useful for tokens with very high decimal precision or when exact precision is critical for financial calculations.
+
+{% enddocs %} 

models/descriptions/amount_raw.md

@@ -1,6 +1,6 @@
 {% docs amount_raw %}
 
-An unadjusted amount (of tokens, price, etc.) for the relevant record. This is the number as it appears on chain and is not decimal adjusted.
+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 NEAR token, the amount_raw would be 1000000000000000000000000 (1e24) since NEAR has 24 decimal places. This field preserves the exact on-chain representation of the token amount for precise calculations and verification.
 
 {% enddocs %}
 

models/descriptions/amount_raw_precise.md

@@ -0,0 +1,5 @@
+{% docs amount_raw_precise %}
+
+Decimal adjusted amount of tokens (high precision float). This field provides the token amount after applying decimal precision adjustments, stored as a high-precision floating-point number. Unlike amount_adj which may have some rounding, this field maintains maximum precision for calculations requiring exact decimal representation of token amounts.
+
+{% enddocs %} 

models/descriptions/amount_usd.md

@@ -1,5 +1,5 @@
 {% docs amount_usd %}
 
-Token amount for the record decimal adjusted and multiplied by a price in USD, if available.
+USD value of the token transfer (null if hourly price not available). This field provides the dollar equivalent value of the token transfer by multiplying the decimal-adjusted token amount by the token's USD price at the time of the transfer. This field is null when price data is unavailable, which can occur for new tokens, tokens with low liquidity, or during periods when price feeds are unavailable.
 
 {% enddocs %}

models/descriptions/creator.md

@@ -0,0 +1,5 @@
+{% docs creator %}
+
+The source or entity that created this label. This field indicates who or what system generated the address label. Almost always "flipside" for automatically generated labels, but can also be "user_submitted" for community-contributed labels. This helps track the provenance and reliability of the labeling information, distinguishing between automated system labels and manually curated community contributions.
+
+{% enddocs %} 

models/descriptions/decimals.md

@@ -1,5 +1,5 @@
 {% docs decimals %}
 
-The number of decimals a raw number should be divided by to decimal adjust. For example, bridged tokens from Ethereum typically use 18 decimals so a raw (unadjusted chain number) of 1000000000000000000 represents 1.
+Number of decimal places for the token. This field specifies the precision of the token, indicating how many decimal places should be used when converting from raw on-chain amounts to human-readable values. For example, NEAR has 24 decimals, so 1 NEAR = 1e24 raw units. Most ERC-20 tokens use 18 decimals, while some tokens may use different precision based on their design requirements.
 
 {% enddocs %}

models/descriptions/gas_burnt.md

@@ -1,7 +1,5 @@
 {% docs gas_burnt %}
 
-The gas used in the object, whether it be the transaction, action or receipt. In the case of a curated model where this column is included alongside a transaction fee, this is the gas burnt during the individual action or receipt.
-
-In raw number format with 16 decimal places, to adjust divide by POW(10,16) or multiply by 1e-16.
+Gas burned for the receipt action. This field represents the amount of computational resources consumed specifically for the receipt being processed. Gas burning is the mechanism by which NEAR charges for computational work, and this field tracks the exact amount burned for this particular receipt action. In raw number format with 16 decimal places, to adjust divide by POW(10,16) or multiply by 1e-16.
 
 {% enddocs %}

models/descriptions/gas_used.md

@@ -1,5 +1,5 @@
 {% docs gas_used %}
 
-Units of gas required to execute this transaction. In raw number format, to adjust divide by POW(10,12)
+Gas used for the transaction. This field represents the amount of computational resources consumed to execute the transaction. Gas is measured in units, and the actual cost is calculated by multiplying gas used by the gas price. In raw number format, to adjust divide by POW(10,12). Higher gas usage indicates more complex operations or larger computational requirements.
 
 {% enddocs %}

models/descriptions/is_delegated.md

@@ -1,5 +1,5 @@
 {% docs is_delegated %}
 
-This column is a boolean value that indicates whether the executed action is a delegated action. Note: Actions with action_name = 'Delegate' themselves are marked as FALSE, while the actions within them are marked as TRUE.
+Whether the action was delegated, typically a FunctionCall acting on another account on its behalf, often where receipt predecessor_id is not the receipt signer or receiver. This field indicates when an action is being executed by one account on behalf of another, which is common in relay transactions, cross-contract calls, or when using access keys with limited permissions. Note: Actions with action_name = 'Delegate' themselves are marked as FALSE, while the actions within them are marked as TRUE.
 
 {% enddocs %}

models/descriptions/label_subtype.md

@@ -1,5 +1,5 @@
 {% docs label_subtype %}
 
-A sub-category nested within label type providing further detail.
+A sub-category nested within label_type providing further detail. This field offers more specific classification within the broader label_type category. Examples include "contract_deployer", "hot_wallet", "token_contract", "liquidity_pool", "governance_contract", "bridge_contract", or "validator". Label subtypes provide granular detail about the specific role or function of an address within its broader category.
 
 {% enddocs %}

models/descriptions/label_type.md

@@ -1,5 +1,5 @@
 {% docs label_type %}
 
-A high-level category describing the addresses main function or ownership.
+A high-level category describing the address's main function or ownership. This field provides broad classification of addresses into major categories such as "cex" (centralized exchange), "dex" (decentralized exchange), "dapp" (decentralized application), "games", "defi" (decentralized finance), "infrastructure", or "governance". Label types help users quickly understand the primary purpose or category of an address within the blockchain ecosystem.
 
 {% enddocs %}

models/descriptions/memo.md

@@ -1,5 +1,5 @@
 {% docs memo %}
 
-Memo: The log message within Near now includes an optional dictionary.
+Optional log message within the transaction (often null). This field contains additional information or context about the transfer, such as transaction notes, reference numbers, or descriptive text. Memos are commonly used in cross-chain bridges, exchange deposits, or other scenarios where additional context is needed to identify or process the transfer. The memo field is optional and frequently null for standard transfers.
 
 {% enddocs %}

models/descriptions/predecessor_id.md

@@ -1,7 +1,5 @@
 {% docs predecessor_id %}
 
-This is the account that was the immediate caller to the smart contract. If this is a simple transaction (no cross-contract calls) from alice.near to banana.near, the smart contract at banana.near considers Alice the predecessor. In this case, Alice would also be the signer.  
-  
-Source: https://docs.near.org/tutorials/crosswords/beginner/actions#predecessor-signer-and-current-account
+Account that called the relevant receipt (often the same as tx_signer, but can be system as well). This field identifies the account that directly invoked the receipt being processed. In simple transactions, this is typically the same as the transaction signer. However, in cross-contract calls or system operations, this may be a different account or the system account. This is crucial for understanding the call chain and access control in NEAR's execution model.
 
 {% enddocs %}

models/descriptions/project_name.md

@@ -1,5 +1,5 @@
 {% docs project_name %}
 
-The associated project, if applicable.
+The associated project name, if applicable. This field identifies the specific protocol, application, or organization that the address is associated with. For example, addresses might be labeled with project names like "Ref Finance", "Aurora", "NEAR Foundation", or "Binance". This helps categorize addresses within the broader ecosystem and provides context about which protocol or organization they belong to.
 
 {% enddocs %}

models/descriptions/receipt_succeeded.md

@@ -1,5 +1,5 @@
 {% docs receipt_succeeded %}
 
-A boolean indicating whether the receipt was successfully processed, based on the presence of a Failure message.
+Boolean indicating whether the receipt was successfully processed. This field tracks the execution status of the receipt, which is crucial for understanding transaction outcomes. While most transactions succeed, individual receipts within a transaction can fail due to various reasons such as insufficient gas, contract errors, or invalid parameters. This field is essential for filtering successful operations and analyzing failure patterns.
 
 {% enddocs %}

models/descriptions/receiver_id.md

@@ -1,7 +1,5 @@
 {% docs receiver_id %}
 
-The address of the NEAR account that the receipt was executed on.
-Note, this differs from `tx_receiver` and is associated with the receipt within a transaction. It is often a contract on which a method is executed by the `signer_id`.
-
+Account reacting to the receipt from predecessor_id, can be relay, a contract, or a user of a relay, etc. This field identifies the account that is processing the receipt and executing the associated action. In most cases, this is a smart contract that is being called, but it can also be a user account in relay transactions or the system account for certain operations. This differs from tx_receiver and is specific to the receipt being processed.
 
 {% enddocs %}

models/descriptions/signer_id.md

@@ -1,5 +1,5 @@
 {% docs signer_id %}
 
-The signer is the account that originally signed the transaction that began the blockchain activity, which may or may not include cross-contract calls. If a function calls results in several cross-contract calls, think of the signer as the account that pushed over the first domino in that chain reaction.
+Signer of the receipt, often same as tx_signer, sometimes system in the case of systemic gas refunds. This field identifies the account that has the authority to execute the receipt. In most cases, this is the same as the transaction signer, but in system operations like gas refunds, this may be the system account. The signer is the account that originally signed the transaction that began the blockchain activity, which may or may not include cross-contract calls.
 
 {% enddocs %}

models/descriptions/symbol.md

@@ -1,5 +1,5 @@
 {% docs symbol %}
 
-The shorthand symbol for the token, as used by common price feeds and exchanges.
+Token symbol (e.g., 'wNEAR', 'SWEAT'). This field contains the abbreviated identifier for the token as commonly used in trading pairs, price feeds, and user interfaces. Token symbols are typically 2-6 characters long and provide a quick way to identify tokens without using their full contract addresses. Examples include 'NEAR' for the native token, 'wNEAR' for wrapped NEAR, and 'USDC' for USD Coin.
 
 {% enddocs %}

models/descriptions/token_price.md

@@ -0,0 +1,5 @@
+{% docs token_price %}
+
+Price of the token at the time of transfer (used for amount_usd column). This field contains the USD price per token unit at the time the transfer occurred. This price is used to calculate the amount_usd field by multiplying it with the decimal-adjusted token amount. Price data is sourced from various price feeds and may be null for tokens without available pricing information.
+
+{% enddocs %} 

models/descriptions/transfer_type.md

@@ -1,5 +1,5 @@
 {% docs transfer_type %}
 
-Nature of the transfer
+Nature of the transfer. This field categorizes the type of token transfer being performed. Common values include "native" for raw NEAR token transfers, "nep141" for fungible token transfers following the NEAR token standard, and other protocol-specific transfer types. This helps distinguish between different token standards and transfer mechanisms used on the NEAR blockchain.
 
 {% enddocs %}

models/descriptions/tx_fee.md

@@ -0,0 +1,5 @@
+{% docs tx_fee %}
+
+RAW Fee for the transaction in smallest NEAR unit. This field contains the total transaction fee paid in the smallest unit of NEAR (yoctoNEAR, 1e-24 NEAR). To convert to NEAR tokens, divide by 1e24. The fee is calculated by multiplying the gas used by the gas price and represents the cost of executing the transaction on the NEAR blockchain.
+
+{% enddocs %} 

models/descriptions/tx_receiver.md

@@ -1,5 +1,5 @@
 {% docs tx_receiver %}
 
-The transaction receiver.
+The transaction receiver, similar to an origin_to in EVM, but can be a contract OR if a relayer is used, the receiver is the user. This field identifies the account that is the intended recipient of the transaction. In direct transactions, this is typically the contract or account being called. In relay transactions, this represents the end user account that the relayer is acting on behalf of.
 
 {% enddocs %}

models/descriptions/tx_signer.md

@@ -1,5 +1,5 @@
 {% docs tx_signer %}
 
-The transaction signer.
+Account that originally signed the transaction, can be a relayer. This field identifies the account that cryptographically signed the transaction, authorizing it to be executed on the blockchain. In relay transactions, this may be a relayer account rather than the end user, while in direct transactions, it represents the actual user or contract initiating the transaction.
 
 {% enddocs %}

models/descriptions/tx_succeeded.md

@@ -1,5 +1,5 @@
 {% docs tx_succeeded %}
 
-Indicates whether the transaction failed or succeeded.
+Boolean indicating if the transaction was successful (rarely used, most tx succeed, it is receipts that can fail). This field tracks the overall success status of the transaction. While most transactions succeed at the transaction level, individual receipts within the transaction can still fail. This field is less commonly used for filtering since receipt-level success tracking provides more granular information about specific operations within the transaction.
 
 {% enddocs %}