From 8e59435183c501e26084af718beb584894b1acb9 Mon Sep 17 00:00:00 2001 From: tarikceric Date: Fri, 18 Jul 2025 14:06:01 -0700 Subject: [PATCH 1/2] gold/core table desc updates --- .cursor/rules/dbt-documentation-standards.mdc | 158 +++++++++++++ .cursor/rules/review-dbt-documentation.mdc | 220 ++++++++++++++++++ models/descriptions/accumulator_root_hash.md | 11 +- models/descriptions/address.md | 11 +- models/descriptions/address_change.md | 11 +- models/descriptions/address_event.md | 11 +- models/descriptions/amount.md | 12 +- models/descriptions/amount_unadj.md | 12 +- models/descriptions/amount_usd.md | 12 +- models/descriptions/block_hash.md | 11 +- models/descriptions/block_number.md | 12 +- models/descriptions/block_timestamp.md | 11 +- models/descriptions/blockchain.md | 13 +- models/descriptions/change_address.md | 12 +- models/descriptions/change_data.md | 12 +- models/descriptions/change_index.md | 13 +- models/descriptions/change_module.md | 13 +- models/descriptions/change_resource.md | 13 +- models/descriptions/change_type.md | 15 +- models/descriptions/changes.md | 11 +- models/descriptions/coin_type_hash.md | 14 ++ models/descriptions/creation_number.md | 13 +- models/descriptions/creator.md | 13 +- models/descriptions/creator_address.md | 14 ++ models/descriptions/decimals.md | 16 ++ models/descriptions/domain.md | 16 ++ models/descriptions/domain_with_suffix.md | 16 ++ models/descriptions/epoch.md | 12 +- models/descriptions/event_address.md | 12 +- models/descriptions/event_data.md | 12 +- models/descriptions/event_index.md | 13 +- models/descriptions/event_module.md | 13 +- models/descriptions/event_resource.md | 13 +- models/descriptions/event_root_hash.md | 11 +- models/descriptions/event_type.md | 13 +- models/descriptions/events.md | 11 +- models/descriptions/expiration_timestamp.md | 14 ++ .../descriptions/expiration_timestamp_secs.md | 12 +- .../descriptions/failed_proposer_indices.md | 15 ++ models/descriptions/first_version.md | 12 +- models/descriptions/from_address_transfer.md | 11 +- models/descriptions/gas_unit_price.md | 12 +- models/descriptions/gas_used.md | 13 +- models/descriptions/handle_change.md | 11 +- models/descriptions/id.md | 14 ++ models/descriptions/inner_change_type.md | 12 +- models/descriptions/inserted_timestamp.md | 11 +- models/descriptions/is_active.md | 15 ++ models/descriptions/is_fungible.md | 15 ++ models/descriptions/is_primary.md | 15 ++ models/descriptions/key_change.md | 12 +- models/descriptions/label.md | 13 +- models/descriptions/label_subtype.md | 14 +- models/descriptions/label_type.md | 14 +- .../descriptions/last_transaction_version.md | 15 ++ models/descriptions/last_version.md | 12 +- models/descriptions/max_gas_amount.md | 13 +- models/descriptions/modified_timestamp.md | 11 +- models/descriptions/name.md | 16 ++ models/descriptions/owner_address.md | 14 ++ models/descriptions/payload.md | 11 +- models/descriptions/payload_function.md | 13 +- models/descriptions/pk.md | 11 +- .../previous_block_votes_bitvec.md | 14 ++ models/descriptions/prices_is_verified.md | 15 ++ models/descriptions/proposer.md | 11 +- models/descriptions/registered_address.md | 14 ++ models/descriptions/round.md | 12 +- models/descriptions/sender.md | 11 +- models/descriptions/sequence_number.md | 13 +- models/descriptions/signature.md | 11 +- models/descriptions/state_change_hash.md | 14 ++ models/descriptions/state_checkpoint_hash.md | 14 ++ models/descriptions/state_key_hash.md | 14 ++ models/descriptions/subdomain.md | 16 ++ models/descriptions/success.md | 12 +- models/descriptions/symbol.md | 13 +- .../tables/core__dim_aptos_names.md | 27 ++- .../descriptions/tables/core__dim_labels.md | 26 ++- .../descriptions/tables/core__dim_tokens.md | 26 ++- .../tables/core__ez_native_transfers.md | 25 +- .../descriptions/tables/core__ez_transfers.md | 27 ++- .../descriptions/tables/core__fact_blocks.md | 26 ++- .../descriptions/tables/core__fact_changes.md | 27 ++- .../descriptions/tables/core__fact_events.md | 28 ++- .../tables/core__fact_transactions.md | 28 ++- .../core__fact_transactions_block_metadata.md | 26 ++- ...ore__fact_transactions_state_checkpoint.md | 26 ++- .../tables/core__fact_transfers.md | 27 ++- models/descriptions/to_address_transfer.md | 11 +- models/descriptions/token_address.md | 12 +- models/descriptions/token_name.md | 16 ++ models/descriptions/token_standard.md | 15 ++ .../transaction_created_timestamp.md | 14 ++ .../transaction_version_created.md | 15 ++ models/descriptions/transfer_event.md | 12 +- models/descriptions/tx_count.md | 13 +- models/descriptions/tx_hash.md | 11 +- models/descriptions/tx_type.md | 13 +- models/descriptions/value_change.md | 12 +- models/descriptions/version.md | 13 +- models/descriptions/vm_status.md | 14 +- models/gold/core/core__dim_aptos_names.yml | 44 ++-- models/gold/core/core__dim_tokens.yml | 14 +- models/gold/core/core__fact_changes.yml | 1 + models/gold/core/core__fact_transactions.yml | 1 + ...core__fact_transactions_block_metadata.yml | 4 + ...re__fact_transactions_state_checkpoint.yml | 3 +- models/gold/core/core__fact_transfers.yml | 2 +- 109 files changed, 1790 insertions(+), 110 deletions(-) create mode 100644 .cursor/rules/dbt-documentation-standards.mdc create mode 100644 .cursor/rules/review-dbt-documentation.mdc create mode 100644 models/descriptions/coin_type_hash.md create mode 100644 models/descriptions/creator_address.md create mode 100644 models/descriptions/decimals.md create mode 100644 models/descriptions/domain.md create mode 100644 models/descriptions/domain_with_suffix.md create mode 100644 models/descriptions/expiration_timestamp.md create mode 100644 models/descriptions/failed_proposer_indices.md create mode 100644 models/descriptions/id.md create mode 100644 models/descriptions/is_active.md create mode 100644 models/descriptions/is_fungible.md create mode 100644 models/descriptions/is_primary.md create mode 100644 models/descriptions/last_transaction_version.md create mode 100644 models/descriptions/name.md create mode 100644 models/descriptions/owner_address.md create mode 100644 models/descriptions/previous_block_votes_bitvec.md create mode 100644 models/descriptions/prices_is_verified.md create mode 100644 models/descriptions/registered_address.md create mode 100644 models/descriptions/state_change_hash.md create mode 100644 models/descriptions/state_checkpoint_hash.md create mode 100644 models/descriptions/state_key_hash.md create mode 100644 models/descriptions/subdomain.md create mode 100644 models/descriptions/token_name.md create mode 100644 models/descriptions/token_standard.md create mode 100644 models/descriptions/transaction_created_timestamp.md create mode 100644 models/descriptions/transaction_version_created.md diff --git a/.cursor/rules/dbt-documentation-standards.mdc b/.cursor/rules/dbt-documentation-standards.mdc new file mode 100644 index 0000000..aab41e5 --- /dev/null +++ b/.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` = `__.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 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 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 \ No newline at end of file diff --git a/.cursor/rules/review-dbt-documentation.mdc b/.cursor/rules/review-dbt-documentation.mdc new file mode 100644 index 0000000..81adf31 --- /dev/null +++ b/.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 \ No newline at end of file diff --git a/models/descriptions/accumulator_root_hash.md b/models/descriptions/accumulator_root_hash.md index 912fbd5..fe70a55 100644 --- a/models/descriptions/accumulator_root_hash.md +++ b/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 %} \ No newline at end of file diff --git a/models/descriptions/address.md b/models/descriptions/address.md index 36215fe..6940bc1 100644 --- a/models/descriptions/address.md +++ b/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 %} \ No newline at end of file diff --git a/models/descriptions/address_change.md b/models/descriptions/address_change.md index 74e0e44..b425bb2 100644 --- a/models/descriptions/address_change.md +++ b/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 %} \ No newline at end of file diff --git a/models/descriptions/address_event.md b/models/descriptions/address_event.md index e97de9f..b6a6885 100644 --- a/models/descriptions/address_event.md +++ b/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 %} \ No newline at end of file diff --git a/models/descriptions/amount.md b/models/descriptions/amount.md index a01c8e4..4d9446a 100644 --- a/models/descriptions/amount.md +++ b/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 %} diff --git a/models/descriptions/amount_unadj.md b/models/descriptions/amount_unadj.md index 40eb2ab..8052fed 100644 --- a/models/descriptions/amount_unadj.md +++ b/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 %} diff --git a/models/descriptions/amount_usd.md b/models/descriptions/amount_usd.md index 6f32555..4d49e88 100644 --- a/models/descriptions/amount_usd.md +++ b/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 %} diff --git a/models/descriptions/block_hash.md b/models/descriptions/block_hash.md index 1658154..293da1e 100644 --- a/models/descriptions/block_hash.md +++ b/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 %} \ No newline at end of file diff --git a/models/descriptions/block_number.md b/models/descriptions/block_number.md index ba7fa4f..6179f6c 100644 --- a/models/descriptions/block_number.md +++ b/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 %} diff --git a/models/descriptions/block_timestamp.md b/models/descriptions/block_timestamp.md index 0c1a1b8..7bdb13e 100644 --- a/models/descriptions/block_timestamp.md +++ b/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 %} \ No newline at end of file diff --git a/models/descriptions/blockchain.md b/models/descriptions/blockchain.md index b5098dc..44e83e0 100644 --- a/models/descriptions/blockchain.md +++ b/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 %} \ No newline at end of file diff --git a/models/descriptions/change_address.md b/models/descriptions/change_address.md index c1f0173..a9e3bb9 100644 --- a/models/descriptions/change_address.md +++ b/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 %} \ No newline at end of file diff --git a/models/descriptions/change_data.md b/models/descriptions/change_data.md index 0f669dc..ab33b8f 100644 --- a/models/descriptions/change_data.md +++ b/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 %} \ No newline at end of file diff --git a/models/descriptions/change_index.md b/models/descriptions/change_index.md index f5b008e..095c0c0 100644 --- a/models/descriptions/change_index.md +++ b/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 %} \ No newline at end of file diff --git a/models/descriptions/change_module.md b/models/descriptions/change_module.md index 0aecd3c..acaa874 100644 --- a/models/descriptions/change_module.md +++ b/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 %} \ No newline at end of file diff --git a/models/descriptions/change_resource.md b/models/descriptions/change_resource.md index 54e227a..0399f17 100644 --- a/models/descriptions/change_resource.md +++ b/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 %} \ No newline at end of file diff --git a/models/descriptions/change_type.md b/models/descriptions/change_type.md index aeef1e9..8fcdb8d 100644 --- a/models/descriptions/change_type.md +++ b/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 %} \ No newline at end of file diff --git a/models/descriptions/changes.md b/models/descriptions/changes.md index 8b718ad..ab9a7e7 100644 --- a/models/descriptions/changes.md +++ b/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 %} \ No newline at end of file diff --git a/models/descriptions/coin_type_hash.md b/models/descriptions/coin_type_hash.md new file mode 100644 index 0000000..8e79180 --- /dev/null +++ b/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 %} \ No newline at end of file diff --git a/models/descriptions/creation_number.md b/models/descriptions/creation_number.md index 31e5dac..a3ca343 100644 --- a/models/descriptions/creation_number.md +++ b/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 %} \ No newline at end of file diff --git a/models/descriptions/creator.md b/models/descriptions/creator.md index ff72c36..4769ba5 100644 --- a/models/descriptions/creator.md +++ b/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 %} \ No newline at end of file diff --git a/models/descriptions/creator_address.md b/models/descriptions/creator_address.md new file mode 100644 index 0000000..33f05fb --- /dev/null +++ b/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 %} \ No newline at end of file diff --git a/models/descriptions/decimals.md b/models/descriptions/decimals.md new file mode 100644 index 0000000..8263afd --- /dev/null +++ b/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 %} \ No newline at end of file diff --git a/models/descriptions/domain.md b/models/descriptions/domain.md new file mode 100644 index 0000000..8ae67a8 --- /dev/null +++ b/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 %} \ No newline at end of file diff --git a/models/descriptions/domain_with_suffix.md b/models/descriptions/domain_with_suffix.md new file mode 100644 index 0000000..12daf69 --- /dev/null +++ b/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 %} \ No newline at end of file diff --git a/models/descriptions/epoch.md b/models/descriptions/epoch.md index 1befe29..373c257 100644 --- a/models/descriptions/epoch.md +++ b/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 %} \ No newline at end of file diff --git a/models/descriptions/event_address.md b/models/descriptions/event_address.md index 27c91b9..9f06556 100644 --- a/models/descriptions/event_address.md +++ b/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 %} \ No newline at end of file diff --git a/models/descriptions/event_data.md b/models/descriptions/event_data.md index 20f0f1b..fe83fa3 100644 --- a/models/descriptions/event_data.md +++ b/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 %} \ No newline at end of file diff --git a/models/descriptions/event_index.md b/models/descriptions/event_index.md index b11e8ab..a720b7c 100644 --- a/models/descriptions/event_index.md +++ b/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 %} \ No newline at end of file diff --git a/models/descriptions/event_module.md b/models/descriptions/event_module.md index 0cd680f..0884da7 100644 --- a/models/descriptions/event_module.md +++ b/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 %} \ No newline at end of file diff --git a/models/descriptions/event_resource.md b/models/descriptions/event_resource.md index 171c2e1..ef1bd13 100644 --- a/models/descriptions/event_resource.md +++ b/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 %} \ No newline at end of file diff --git a/models/descriptions/event_root_hash.md b/models/descriptions/event_root_hash.md index 496edae..4fbc93f 100644 --- a/models/descriptions/event_root_hash.md +++ b/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 %} \ No newline at end of file diff --git a/models/descriptions/event_type.md b/models/descriptions/event_type.md index 59986ef..a4195aa 100644 --- a/models/descriptions/event_type.md +++ b/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 %} \ No newline at end of file diff --git a/models/descriptions/events.md b/models/descriptions/events.md index c96082b..ef7bcac 100644 --- a/models/descriptions/events.md +++ b/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 %} \ No newline at end of file diff --git a/models/descriptions/expiration_timestamp.md b/models/descriptions/expiration_timestamp.md new file mode 100644 index 0000000..d75ecc5 --- /dev/null +++ b/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 %} \ No newline at end of file diff --git a/models/descriptions/expiration_timestamp_secs.md b/models/descriptions/expiration_timestamp_secs.md index 0386f71..85aa61e 100644 --- a/models/descriptions/expiration_timestamp_secs.md +++ b/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 %} \ No newline at end of file diff --git a/models/descriptions/failed_proposer_indices.md b/models/descriptions/failed_proposer_indices.md new file mode 100644 index 0000000..ee1e06c --- /dev/null +++ b/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 %} \ No newline at end of file diff --git a/models/descriptions/first_version.md b/models/descriptions/first_version.md index 1a5825b..4dd9718 100644 --- a/models/descriptions/first_version.md +++ b/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 %} \ No newline at end of file diff --git a/models/descriptions/from_address_transfer.md b/models/descriptions/from_address_transfer.md index fc8b5a1..6dc15b6 100644 --- a/models/descriptions/from_address_transfer.md +++ b/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 %} \ No newline at end of file diff --git a/models/descriptions/gas_unit_price.md b/models/descriptions/gas_unit_price.md index 0a53fd5..ae211e4 100644 --- a/models/descriptions/gas_unit_price.md +++ b/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 %} \ No newline at end of file diff --git a/models/descriptions/gas_used.md b/models/descriptions/gas_used.md index 785880e..3dda203 100644 --- a/models/descriptions/gas_used.md +++ b/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 %} \ No newline at end of file diff --git a/models/descriptions/handle_change.md b/models/descriptions/handle_change.md index 29db8eb..cad7cd4 100644 --- a/models/descriptions/handle_change.md +++ b/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 %} \ No newline at end of file diff --git a/models/descriptions/id.md b/models/descriptions/id.md new file mode 100644 index 0000000..2716664 --- /dev/null +++ b/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 %} \ No newline at end of file diff --git a/models/descriptions/inner_change_type.md b/models/descriptions/inner_change_type.md index 1ae3156..52b4478 100644 --- a/models/descriptions/inner_change_type.md +++ b/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 %} \ No newline at end of file diff --git a/models/descriptions/inserted_timestamp.md b/models/descriptions/inserted_timestamp.md index 14703c3..7d20d9e 100644 --- a/models/descriptions/inserted_timestamp.md +++ b/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 %} \ No newline at end of file diff --git a/models/descriptions/is_active.md b/models/descriptions/is_active.md new file mode 100644 index 0000000..a06dfb5 --- /dev/null +++ b/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 %} \ No newline at end of file diff --git a/models/descriptions/is_fungible.md b/models/descriptions/is_fungible.md new file mode 100644 index 0000000..39815b8 --- /dev/null +++ b/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 %} \ No newline at end of file diff --git a/models/descriptions/is_primary.md b/models/descriptions/is_primary.md new file mode 100644 index 0000000..87ebccc --- /dev/null +++ b/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 %} \ No newline at end of file diff --git a/models/descriptions/key_change.md b/models/descriptions/key_change.md index a277e5f..3e9849e 100644 --- a/models/descriptions/key_change.md +++ b/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 %} \ No newline at end of file diff --git a/models/descriptions/label.md b/models/descriptions/label.md index 51af3dc..5a80dcc 100644 --- a/models/descriptions/label.md +++ b/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 %} \ No newline at end of file diff --git a/models/descriptions/label_subtype.md b/models/descriptions/label_subtype.md index 113de57..cd49127 100644 --- a/models/descriptions/label_subtype.md +++ b/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 %} \ No newline at end of file diff --git a/models/descriptions/label_type.md b/models/descriptions/label_type.md index c81472b..d13dbf8 100644 --- a/models/descriptions/label_type.md +++ b/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 %} \ No newline at end of file diff --git a/models/descriptions/last_transaction_version.md b/models/descriptions/last_transaction_version.md new file mode 100644 index 0000000..4e9d985 --- /dev/null +++ b/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 %} \ No newline at end of file diff --git a/models/descriptions/last_version.md b/models/descriptions/last_version.md index a56d7b6..ecbc14e 100644 --- a/models/descriptions/last_version.md +++ b/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 %} \ No newline at end of file diff --git a/models/descriptions/max_gas_amount.md b/models/descriptions/max_gas_amount.md index 45da165..647c0c5 100644 --- a/models/descriptions/max_gas_amount.md +++ b/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 %} \ No newline at end of file diff --git a/models/descriptions/modified_timestamp.md b/models/descriptions/modified_timestamp.md index c4d18ee..104ec39 100644 --- a/models/descriptions/modified_timestamp.md +++ b/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 %} \ No newline at end of file diff --git a/models/descriptions/name.md b/models/descriptions/name.md new file mode 100644 index 0000000..a9f431f --- /dev/null +++ b/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 %} \ No newline at end of file diff --git a/models/descriptions/owner_address.md b/models/descriptions/owner_address.md new file mode 100644 index 0000000..7784ad5 --- /dev/null +++ b/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 %} \ No newline at end of file diff --git a/models/descriptions/payload.md b/models/descriptions/payload.md index bc8f12b..f1d0206 100644 --- a/models/descriptions/payload.md +++ b/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 %} \ No newline at end of file diff --git a/models/descriptions/payload_function.md b/models/descriptions/payload_function.md index 912a1a1..dbd9805 100644 --- a/models/descriptions/payload_function.md +++ b/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 %} \ No newline at end of file diff --git a/models/descriptions/pk.md b/models/descriptions/pk.md index 8dfdfb5..6153067 100644 --- a/models/descriptions/pk.md +++ b/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 %} \ No newline at end of file diff --git a/models/descriptions/previous_block_votes_bitvec.md b/models/descriptions/previous_block_votes_bitvec.md new file mode 100644 index 0000000..962c1ec --- /dev/null +++ b/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 %} \ No newline at end of file diff --git a/models/descriptions/prices_is_verified.md b/models/descriptions/prices_is_verified.md new file mode 100644 index 0000000..f2cb0ba --- /dev/null +++ b/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 %} \ No newline at end of file diff --git a/models/descriptions/proposer.md b/models/descriptions/proposer.md index d66b281..b2d467d 100644 --- a/models/descriptions/proposer.md +++ b/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 %} \ No newline at end of file diff --git a/models/descriptions/registered_address.md b/models/descriptions/registered_address.md new file mode 100644 index 0000000..391fae5 --- /dev/null +++ b/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 %} \ No newline at end of file diff --git a/models/descriptions/round.md b/models/descriptions/round.md index f24284a..943b0cc 100644 --- a/models/descriptions/round.md +++ b/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 %} \ No newline at end of file diff --git a/models/descriptions/sender.md b/models/descriptions/sender.md index b86343b..6fccf5f 100644 --- a/models/descriptions/sender.md +++ b/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 %} \ No newline at end of file diff --git a/models/descriptions/sequence_number.md b/models/descriptions/sequence_number.md index 7738bf6..5724e74 100644 --- a/models/descriptions/sequence_number.md +++ b/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 %} \ No newline at end of file diff --git a/models/descriptions/signature.md b/models/descriptions/signature.md index 121914a..b4bdad9 100644 --- a/models/descriptions/signature.md +++ b/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 %} \ No newline at end of file diff --git a/models/descriptions/state_change_hash.md b/models/descriptions/state_change_hash.md new file mode 100644 index 0000000..fca03d3 --- /dev/null +++ b/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 %} \ No newline at end of file diff --git a/models/descriptions/state_checkpoint_hash.md b/models/descriptions/state_checkpoint_hash.md new file mode 100644 index 0000000..1ac725c --- /dev/null +++ b/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 %} \ No newline at end of file diff --git a/models/descriptions/state_key_hash.md b/models/descriptions/state_key_hash.md new file mode 100644 index 0000000..5f364ac --- /dev/null +++ b/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 %} \ No newline at end of file diff --git a/models/descriptions/subdomain.md b/models/descriptions/subdomain.md new file mode 100644 index 0000000..ed4eaed --- /dev/null +++ b/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 %} \ No newline at end of file diff --git a/models/descriptions/success.md b/models/descriptions/success.md index 6b20598..6084bcd 100644 --- a/models/descriptions/success.md +++ b/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 %} \ No newline at end of file diff --git a/models/descriptions/symbol.md b/models/descriptions/symbol.md index 0c16f42..af07481 100644 --- a/models/descriptions/symbol.md +++ b/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 %} \ No newline at end of file diff --git a/models/descriptions/tables/core__dim_aptos_names.md b/models/descriptions/tables/core__dim_aptos_names.md index 34e63de..43697b0 100644 --- a/models/descriptions/tables/core__dim_aptos_names.md +++ b/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 %} diff --git a/models/descriptions/tables/core__dim_labels.md b/models/descriptions/tables/core__dim_labels.md index 8060a3b..e805ab5 100644 --- a/models/descriptions/tables/core__dim_labels.md +++ b/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 %} diff --git a/models/descriptions/tables/core__dim_tokens.md b/models/descriptions/tables/core__dim_tokens.md index 31b6922..04ca98e 100644 --- a/models/descriptions/tables/core__dim_tokens.md +++ b/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 %} diff --git a/models/descriptions/tables/core__ez_native_transfers.md b/models/descriptions/tables/core__ez_native_transfers.md index 02cff32..efbd1d9 100644 --- a/models/descriptions/tables/core__ez_native_transfers.md +++ b/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 %} diff --git a/models/descriptions/tables/core__ez_transfers.md b/models/descriptions/tables/core__ez_transfers.md index 3037199..fbac109 100644 --- a/models/descriptions/tables/core__ez_transfers.md +++ b/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 %} diff --git a/models/descriptions/tables/core__fact_blocks.md b/models/descriptions/tables/core__fact_blocks.md index b98a007..bbd4cf3 100644 --- a/models/descriptions/tables/core__fact_blocks.md +++ b/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 %} diff --git a/models/descriptions/tables/core__fact_changes.md b/models/descriptions/tables/core__fact_changes.md index 3b66c3e..84ad119 100644 --- a/models/descriptions/tables/core__fact_changes.md +++ b/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 %} diff --git a/models/descriptions/tables/core__fact_events.md b/models/descriptions/tables/core__fact_events.md index ad7a9d0..485a771 100644 --- a/models/descriptions/tables/core__fact_events.md +++ b/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 %} diff --git a/models/descriptions/tables/core__fact_transactions.md b/models/descriptions/tables/core__fact_transactions.md index c691119..1c2ee5c 100644 --- a/models/descriptions/tables/core__fact_transactions.md +++ b/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 %} diff --git a/models/descriptions/tables/core__fact_transactions_block_metadata.md b/models/descriptions/tables/core__fact_transactions_block_metadata.md index 819eeac..50d8f09 100644 --- a/models/descriptions/tables/core__fact_transactions_block_metadata.md +++ b/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 %} diff --git a/models/descriptions/tables/core__fact_transactions_state_checkpoint.md b/models/descriptions/tables/core__fact_transactions_state_checkpoint.md index 3b4b995..3682738 100644 --- a/models/descriptions/tables/core__fact_transactions_state_checkpoint.md +++ b/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 %} diff --git a/models/descriptions/tables/core__fact_transfers.md b/models/descriptions/tables/core__fact_transfers.md index 307130b..e48770f 100644 --- a/models/descriptions/tables/core__fact_transfers.md +++ b/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 %} diff --git a/models/descriptions/to_address_transfer.md b/models/descriptions/to_address_transfer.md index 6144397..39ce5e9 100644 --- a/models/descriptions/to_address_transfer.md +++ b/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 %} \ No newline at end of file diff --git a/models/descriptions/token_address.md b/models/descriptions/token_address.md index 766881f..1b79d62 100644 --- a/models/descriptions/token_address.md +++ b/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 %} \ No newline at end of file diff --git a/models/descriptions/token_name.md b/models/descriptions/token_name.md new file mode 100644 index 0000000..a65cbeb --- /dev/null +++ b/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 %} \ No newline at end of file diff --git a/models/descriptions/token_standard.md b/models/descriptions/token_standard.md new file mode 100644 index 0000000..24202e1 --- /dev/null +++ b/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 %} \ No newline at end of file diff --git a/models/descriptions/transaction_created_timestamp.md b/models/descriptions/transaction_created_timestamp.md new file mode 100644 index 0000000..32f6f34 --- /dev/null +++ b/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 %} \ No newline at end of file diff --git a/models/descriptions/transaction_version_created.md b/models/descriptions/transaction_version_created.md new file mode 100644 index 0000000..45d9939 --- /dev/null +++ b/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 %} \ No newline at end of file diff --git a/models/descriptions/transfer_event.md b/models/descriptions/transfer_event.md index 3862b6f..90ff759 100644 --- a/models/descriptions/transfer_event.md +++ b/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 %} \ No newline at end of file diff --git a/models/descriptions/tx_count.md b/models/descriptions/tx_count.md index 74978b9..1d332c2 100644 --- a/models/descriptions/tx_count.md +++ b/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 %} \ No newline at end of file diff --git a/models/descriptions/tx_hash.md b/models/descriptions/tx_hash.md index a848c23..e9f02f0 100644 --- a/models/descriptions/tx_hash.md +++ b/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 %} \ No newline at end of file diff --git a/models/descriptions/tx_type.md b/models/descriptions/tx_type.md index 528e1bd..ccc2e9e 100644 --- a/models/descriptions/tx_type.md +++ b/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 %} \ No newline at end of file diff --git a/models/descriptions/value_change.md b/models/descriptions/value_change.md index 87d41a8..071e93b 100644 --- a/models/descriptions/value_change.md +++ b/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 %} \ No newline at end of file diff --git a/models/descriptions/version.md b/models/descriptions/version.md index ac9836e..04b35a0 100644 --- a/models/descriptions/version.md +++ b/models/descriptions/version.md @@ -1,5 +1,16 @@ {% docs version %} -The version also know as the height of the transactions that have been executed on the Aptos blockchain. The first transaction in the blockchain has a version of 0. The version number is incremented by 1 for each transaction that is executed on the blockchain. +The version number, also known as the height, represents the sequential position of a transaction in the Aptos blockchain. The first transaction has a version of 0, and each subsequent transaction increments by 1. + +**Data type:** Integer +**Example:** +- 0 (genesis transaction) +- 12345678 +- 98765432 + +**Business Context:** +- Unique identifier for ordering transactions chronologically across the entire blockchain. +- Essential for transaction sequencing and version-based analysis. +- Enables precise transaction tracking and blockchain state verification. {% enddocs %} \ No newline at end of file diff --git a/models/descriptions/vm_status.md b/models/descriptions/vm_status.md index 1942480..ad3eac5 100644 --- a/models/descriptions/vm_status.md +++ b/models/descriptions/vm_status.md @@ -1,5 +1,17 @@ {% docs vm_status %} -For failed transactions, this fields provides context to why the transaction failed. For successful transactions, this field will be set to `Executed successfully`. +The execution status of a transaction as reported by the Aptos Virtual Machine (VM), providing success confirmation or failure details. + +**Data type:** String +**Example:** +- Executed successfully +- OUT_OF_GAS +- INSUFFICIENT_BALANCE +- INVALID_ARGUMENT + +**Business Context:** +- Essential for transaction success rate analysis and failure investigation. +- Critical for debugging transaction issues and understanding failure patterns. +- Enables user experience analysis and error pattern recognition. {% enddocs %} \ No newline at end of file diff --git a/models/gold/core/core__dim_aptos_names.yml b/models/gold/core/core__dim_aptos_names.yml index f5ff208..388466d 100644 --- a/models/gold/core/core__dim_aptos_names.yml +++ b/models/gold/core/core__dim_aptos_names.yml @@ -4,28 +4,28 @@ models: description: '{{ doc("core__dim_aptos_names") }}' columns: - - name: token_name - description: 'The full aptos name' - - name: domain - description: 'The domain of the aptos name' - - name: domain_with_suffix - description: 'The domain plus the suffix' - - name: subdomain - description: 'The subdomain of the aptos name' - - name: owner_address - description: 'The account address that owns the aptos name' - - name: registered_address - description: 'The account address that the aptos name is registered to' - - name: is_active - description: 'Boolean value identifying if the aptos name is active' - - name: is_primary - description: 'Boolean value identifying if the aptos name is primary' - - name: token_standard - description: 'The token standard of the aptos name' - - name: expiration_timestamp - description: 'The timestamp of when the aptos name expires' - - name: last_transaction_version - description: 'The last transaction version of the aptos name' + - name: TOKEN_NAME + description: '{{ doc("token_name") }}' + - name: DOMAIN + description: '{{ doc("domain") }}' + - name: DOMAIN_WITH_SUFFIX + description: '{{ doc("domain_with_suffix") }}' + - name: SUBDOMAIN + description: '{{ doc("subdomain") }}' + - name: OWNER_ADDRESS + description: '{{ doc("owner_address") }}' + - name: REGISTERED_ADDRESS + description: '{{ doc("registered_address") }}' + - name: IS_ACTIVE + description: '{{ doc("is_active") }}' + - name: IS_PRIMARY + description: '{{ doc("is_primary") }}' + - name: TOKEN_STANDARD + description: '{{ doc("token_standard") }}' + - name: EXPIRATION_TIMESTAMP + description: '{{ doc("expiration_timestamp") }}' + - name: LAST_TRANSACTION_VERSION + description: '{{ doc("last_transaction_version") }}' - name: DIM_APTOS_NAMES_ID description: '{{ doc("pk") }}' - name: INSERTED_TIMESTAMP diff --git a/models/gold/core/core__dim_tokens.yml b/models/gold/core/core__dim_tokens.yml index a2b8b40..d4ef840 100644 --- a/models/gold/core/core__dim_tokens.yml +++ b/models/gold/core/core__dim_tokens.yml @@ -10,19 +10,19 @@ models: - not_null - unique - name: NAME - description: 'The full token name' + description: '{{ doc("name") }}' - name: SYMBOL - description: 'The token symbol' + description: '{{ doc("symbol") }}' - name: DECIMALS - description: 'The number of decimals for the token' + description: '{{ doc("decimals") }}' - name: COIN_TYPE_HASH - description: 'Hash of the coin type' + description: '{{ doc("coin_type_hash") }}' - name: CREATOR_ADDRESS - description: 'The account address that created the token' + description: '{{ doc("creator_address") }}' - name: TRANSACTION_CREATED_TIMESTAMP - description: 'The timestamp of when the token was created' + description: '{{ doc("transaction_created_timestamp") }}' - name: TRANSACTION_VERSION_CREATED - description: 'The transaction version of when the token was created' + description: '{{ doc("transaction_version_created") }}' - name: DIM_TOKENS_ID description: '{{ doc("pk") }}' - name: INSERTED_TIMESTAMP diff --git a/models/gold/core/core__fact_changes.yml b/models/gold/core/core__fact_changes.yml index 3e37015..36ad606 100644 --- a/models/gold/core/core__fact_changes.yml +++ b/models/gold/core/core__fact_changes.yml @@ -41,6 +41,7 @@ models: - name: VALUE description: '{{ doc("value_change") }}' - name: STATE_KEY_HASH + description: '{{ doc("state_key_hash") }}' - name: FACT_CHANGES_ID description: '{{ doc("pk") }}' - name: INSERTED_TIMESTAMP diff --git a/models/gold/core/core__fact_transactions.yml b/models/gold/core/core__fact_transactions.yml index 0b0807d..6f4c58e 100644 --- a/models/gold/core/core__fact_transactions.yml +++ b/models/gold/core/core__fact_transactions.yml @@ -39,6 +39,7 @@ models: - name: VM_STATUS description: '{{ doc("vm_status") }}' - name: STATE_CHANGE_HASH + description: '{{ doc("state_change_hash") }}' - name: ACCUMULATOR_ROOT_HASH description: '{{ doc("accumulator_root_hash") }}' - name: EVENT_ROOT_HASH diff --git a/models/gold/core/core__fact_transactions_block_metadata.yml b/models/gold/core/core__fact_transactions_block_metadata.yml index 94180bc..53ae6e5 100644 --- a/models/gold/core/core__fact_transactions_block_metadata.yml +++ b/models/gold/core/core__fact_transactions_block_metadata.yml @@ -23,8 +23,11 @@ models: - name: CHANGES description: '{{ doc("changes") }}' - name: FAILED_PROPOSER_INDICES + description: '{{ doc("failed_proposer_indices") }}' - name: ID + description: '{{ doc("id") }}' - name: PREVIOUS_BLOCK_VOTES_BITVEC + description: '{{ doc("previous_block_votes_bitvec") }}' - name: PROPOSER description: '{{ doc("proposer") }}' - name: ROUND @@ -32,6 +35,7 @@ models: - name: VM_STATUS description: '{{ doc("vm_status") }}' - name: STATE_CHANGE_HASH + description: '{{ doc("state_change_hash") }}' - name: ACCUMULATOR_ROOT_HASH description: '{{ doc("accumulator_root_hash") }}' - name: EVENT_ROOT_HASH diff --git a/models/gold/core/core__fact_transactions_state_checkpoint.yml b/models/gold/core/core__fact_transactions_state_checkpoint.yml index a087b39..5b54528 100644 --- a/models/gold/core/core__fact_transactions_state_checkpoint.yml +++ b/models/gold/core/core__fact_transactions_state_checkpoint.yml @@ -19,6 +19,7 @@ models: - name: VM_STATUS description: '{{ doc("vm_status") }}' - name: STATE_CHECKPOINT_HASH + description: '{{ doc("state_checkpoint_hash") }}' - name: ACCUMULATOR_ROOT_HASH description: '{{ doc("accumulator_root_hash") }}' - name: EVENT_ROOT_HASH @@ -28,4 +29,4 @@ models: - name: INSERTED_TIMESTAMP description: '{{ doc("inserted_timestamp") }}' - name: MODIFIED_TIMESTAMP - description: '{{ doc("modified_timestamp") }}' + description: '{{ doc("modified_timestamp") }}' diff --git a/models/gold/core/core__fact_transfers.yml b/models/gold/core/core__fact_transfers.yml index cfa44c0..f3d2729 100644 --- a/models/gold/core/core__fact_transfers.yml +++ b/models/gold/core/core__fact_transfers.yml @@ -27,7 +27,7 @@ models: - name: TOKEN_ADDRESS description: '{{ doc("token_address") }}' - name: IS_FUNGIBLE - description: 'Boolean indicating whether the transfer was conducted using the legacy coin transfer mechanism (a simpler, original method for transferring coins) or the fungible_asset module (a newer, more flexible system for managing fungible assets).' + description: '{{ doc("is_fungible") }}' - name: FACT_TRANSFERS_ID description: '{{ doc("pk") }}' tests: From ba62d731a61a413698de59fe9e98eba556ba25cb Mon Sep 17 00:00:00 2001 From: tarikceric Date: Fri, 18 Jul 2025 14:21:14 -0700 Subject: [PATCH 2/2] delete dupes --- models/descriptions/prices_is_verified.md | 15 --------------- 1 file changed, 15 deletions(-) delete mode 100644 models/descriptions/prices_is_verified.md diff --git a/models/descriptions/prices_is_verified.md b/models/descriptions/prices_is_verified.md deleted file mode 100644 index f2cb0ba..0000000 --- a/models/descriptions/prices_is_verified.md +++ /dev/null @@ -1,15 +0,0 @@ -{% 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 %} \ No newline at end of file