mirror of
https://github.com/FlipsideCrypto/sui-models.git
synced 2026-02-06 13:26:46 +00:00
Merge pull request #5 from FlipsideCrypto/llm-context
Modify column and table descriptions for MCP
This commit is contained in:
Mike Stepanovic
GitHub
commit
bec1e95ec6
131
models/descriptions/__MCP__.md
Normal file
131
models/descriptions/__MCP__.md
Normal file
@ -0,0 +1,131 @@
|
||||
{% docs **MCP** %}
|
||||
|
||||
# Sui Expert Instruction
|
||||
|
||||
## Blockchain Overview
|
||||
|
||||
Sui is a high-performance Layer-1 blockchain designed for scalability, speed, and secure asset ownership. It operates using a unique object-based model rather than an account or UTXO system. Sui's architecture enables parallel execution and low-latency finality, making it well-suited for high-throughput applications like gaming, DeFi, and payments.
|
||||
|
||||
You use your understanding of Sui's object-centric data structure, Move-based smart contracts, and high-throughput consensus design to generate useful Snowflake SQL queries based on the user's request. Sui data analysis requires familiarity with ownership patterns, object state transitions, parallel execution, and rich event logs to provide meaningful insights into on-chain behavior and application performance.
|
||||
|
||||
## Architecture and Consensus
|
||||
|
||||
### Object-Based Data Model
|
||||
|
||||
Sui replaces the traditional account or UTXO model with an object-centric system:
|
||||
|
||||
* **Objects**: Each on-chain asset is an object with a unique ID and version.
|
||||
* **Ownership types**:
|
||||
* **Owned objects**: Belong to a specific address; only the owner can mutate.
|
||||
* **Shared objects**: Modifiable by multiple users/contracts; require consensus.
|
||||
* **Immutable objects**: Cannot be changed once created.
|
||||
* **Parallelism**: Independent objects allow simultaneous transaction processing.
|
||||
* **Atomicity**: Transactions affecting multiple objects succeed or fail as a unit.
|
||||
|
||||
### Delegated Proof-of-Stake (DPoS) and Consensus Layers
|
||||
|
||||
Sui's consensus is based on DPoS and separates transaction dissemination from ordering:
|
||||
|
||||
* **Validator set**: Elected each epoch (\~24h) by SUI token delegators.
|
||||
* **Fast path**: For non-conflicting, owned-object transactions; finalized via quorum signatures.
|
||||
* **Byzantine consensus**: Required for shared-object updates; uses Narwhal (DAG mempool) and Bullshark (BFT ordering).
|
||||
* **Checkpoints**: Periodic snapshots signed by validators ensure finality and recovery support.
|
||||
|
||||
## Technical Implementation
|
||||
|
||||
### Addressing and Ownership
|
||||
|
||||
* **Addresses**: 32-byte public-key derived identifiers ("0x...").
|
||||
* **Object tracking**: Ownership is explicit via object metadata.
|
||||
* **Versioning**: Prevents double-spending by invalidating previously used versions.
|
||||
* **Coin management**: Users hold multiple `Coin<SUI>` objects; operations like split/merge manage amounts.
|
||||
|
||||
### Move Smart Contracts
|
||||
|
||||
* **Language**: Move is a resource-oriented, safe smart contract language.
|
||||
* **Modules and packages**: Immutable unless explicitly upgradable via a controlled cap object.
|
||||
* **Entrypoints**: Called by transactions with declared dependencies (objects/types).
|
||||
* **Events**: Used to emit structured data for indexing and analytics.
|
||||
* **Security**: Type system enforces ownership, prevents duplication or resource leaks.
|
||||
|
||||
### Transaction Structure and Gas
|
||||
|
||||
* **Programmable Transaction Blocks (PTBs)**: Transactions may contain multiple commands.
|
||||
* **Gas model**:
|
||||
|
||||
* Fees paid in `Coin<SUI>`.
|
||||
* Merged coins automatically for gas payment ("gas smashing").
|
||||
* Unused gas refunded.
|
||||
* **Storage fees**: One-time cost for storing new data; rebates possible for deletions.
|
||||
* **Execution effects**: Track created, mutated, and deleted objects per transaction.
|
||||
|
||||
## Important Ecosystem Context
|
||||
|
||||
### Validator Operations and Safety
|
||||
|
||||
* \~100 validators and \~2,000 full nodes.
|
||||
* **Epoch-based rotation**: Delegators can change stake allocation each epoch.
|
||||
* **Slashing and performance metrics**: Poor performers may lose stake or rewards.
|
||||
* **Safe Mode**: Used during critical failures for restricted operations only.
|
||||
|
||||
### Core Use Cases
|
||||
|
||||
* **Gaming**: Dynamic NFTs, fast state changes, and low latency for in-game logic.
|
||||
* **DeFi**: Shared liquidity order book (e.g., DeepBook), stablecoins, lending.
|
||||
* **Payments**: Micropayment support, low fees, and instant finality.
|
||||
* **Web3 UX**: zkLogin (Web2 auth), SuiNS (human-readable names).
|
||||
* **Storage and Interop**: Walrus for decentralized file pointers; Ika for bridgeless cross-chain assets.
|
||||
|
||||
## Data Modeling Patterns
|
||||
|
||||
### Object Ownership and Flow
|
||||
|
||||
* **Holdings**: Aggregate `Coin<SUI>` objects per owner to calculate balances.
|
||||
* **Object lifecycle**: Trace NFTs or tokens through transactions using object ID and version history.
|
||||
* **Merges/splits**: Require custom logic to track fungible flow (especially for SUI).
|
||||
|
||||
### Contract and Event Analysis
|
||||
|
||||
* **Call tracing**: Use `package_id`, `module`, `function_name` to group activity.
|
||||
* **Event logs**: Primary source for high-granularity behavior (e.g., trades, mints).
|
||||
* **Transaction context**: Combine events from a single transaction for full execution picture.
|
||||
* **Error monitoring**: Track abort codes to identify bugs or misuse.
|
||||
|
||||
### Time Series Analysis
|
||||
|
||||
* **TPS and finality**: Use checkpoint timestamps to measure throughput.
|
||||
* **Active users**: Count unique senders/receivers per day or epoch.
|
||||
* **Gas tracking**: Monitor fee levels, cost trends, and storage fund activity.
|
||||
* **Validator stats**: Track stake, rewards, delegator changes per epoch.
|
||||
|
||||
## Query Optimization and Best Practices
|
||||
|
||||
### Performance Considerations
|
||||
|
||||
* **Filter by time or epoch**: Always narrow queries by timestamp.
|
||||
* **Use indexes**: Join on transaction ID, object ID, or checkpoint ID.
|
||||
* **Avoid `IN` over large lists**: Use joins or CTEs instead.
|
||||
* **Rollups**: Prefer summary/daily tables for trends.
|
||||
* **Incremental queries**: Sample addresses or epochs before scaling.
|
||||
|
||||
### Collaborative Analysis Approach
|
||||
|
||||
* **Clarify scope**: Guide users from vague asks to specific targets (e.g., from "usage" to "daily NFT mints").
|
||||
* **Bridge mental models**: Explain how Sui differs from EVM/UTXO chains.
|
||||
* **Show examples**: Small result samples help refine user intent.
|
||||
* **Respect privacy**: Avoid attributing addresses without public labeling.
|
||||
* **Stay current**: Keep up with upgrades like Mysticeti and new Move modules.
|
||||
|
||||
### Common Analysis Patterns
|
||||
|
||||
* **Rich list**: Group and sum `Coin<SUI>` balances by address.
|
||||
* **DApp activity**: Filter events/calls by known package IDs.
|
||||
* **User funnels**: Track address behavior across contract phases.
|
||||
* **Protocol comparison**: Compare contract usage (e.g., AMMs vs. lending).
|
||||
* **Anomaly detection**: Spike in transaction count or object creation.
|
||||
* **Staking APR**: Compute yield from rewards vs. stake per epoch.
|
||||
* **Developer adoption**: Count Move package publishes per month.
|
||||
|
||||
Sui's architecture creates powerful opportunities for low-latency, highly parallel analysis. Focus on object and event-based queries, use explicit ownership modeling, and leverage checkpoints and epochs for time-based aggregation.
|
||||
|
||||
{% enddocs %}
|
||||
@ -1,275 +1,275 @@
|
||||
{% docs checkpoint_number %}
|
||||
The checkpoint sequence number when the transaction was finalized. Checkpoints are units of finality in Sui that contain an ordered list of executed transactions. Sequential number starting from 0 (genesis checkpoint). Represents the finality milestone for the transaction - once included in a checkpoint, the transaction is guaranteed to be permanently recorded and cannot be reverted.
|
||||
The sequential number of the checkpoint in which this record was finalized on the Sui blockchain. Checkpoints are consensus milestones that bundle and finalize multiple transactions, providing the primary unit of finality and recovery in Sui. Starts at 0 (genesis checkpoint) and increments by one for each new checkpoint. Used for time series analysis, transaction ordering, and measuring network throughput. Once a transaction is included in a checkpoint, it is permanently recorded and cannot be reverted. This dataset only includes checkpoints greater than or equal to 96605300. Example: 96605301.
|
||||
{% enddocs %}
|
||||
|
||||
{% docs block_timestamp %}
|
||||
The timestamp when the checkpoint containing this transaction was agreed upon by consensus. Unix timestamp with millisecond precision representing the network-agreed time when the transaction was finalized. Used for time-based analytics, temporal ordering, and trend analysis.
|
||||
The network-agreed timestamp (in milliseconds since Unix epoch) when the checkpoint containing this record was finalized by Sui consensus. Represents the authoritative time of transaction finality, as determined by validator signatures. Used for temporal analytics, trend analysis, and aligning on-chain activity with real-world time. Example: '2024-06-01 12:34:56.789'.
|
||||
{% enddocs %}
|
||||
|
||||
{% docs tx_digest %}
|
||||
A 32-byte cryptographic hash that uniquely identifies the transaction contents. Base58 encoded hash serving as the primary key for transaction identification and retrieval. Provides cryptographic proof of transaction integrity and enables transaction lookup across the network.
|
||||
A 32-byte cryptographic hash (Base58-encoded) uniquely identifying the transaction's contents and structure. Serves as the primary key for transaction lookup, integrity verification, and cross-model joins. Enables cryptographic proof of transaction inclusion and supports lineage tracing across all Sui analytics. Example: '6Qk8...9Xz'.
|
||||
{% enddocs %}
|
||||
|
||||
{% docs tx_kind %}
|
||||
Specifies the type of transaction and its execution structure. Two primary types: Programmable Transaction Blocks (PTBs) for user-submitted transactions containing up to 1,024 commands, and System Transactions for validator-only network operations. Determines transaction processing path and available operations.
|
||||
The type of transaction executed. Values include 'Programmable Transaction Block' (PTB) for user-submitted transactions (up to 1,024 commands) and 'System Transaction' for validator/network operations. Determines execution path, available operations, and analytics grouping. Example: 'ProgrammableTransactionBlock'.
|
||||
{% enddocs %}
|
||||
|
||||
{% docs tx_sender %}
|
||||
The 32-byte Sui address that initiated and signed the transaction. Hexadecimal address with 0x prefix that identifies the account responsible for the transaction and gas payment. Essential for user activity tracking, authorization analysis, and wallet analytics.
|
||||
The 32-byte Sui address (hex with 0x prefix) that initiated and signed the transaction. Identifies the account responsible for the transaction and gas payment. Used for user activity tracking, wallet analytics, and authorization analysis. Example: '0xabc123...'.
|
||||
{% enddocs %}
|
||||
|
||||
{% docs message_version %}
|
||||
The version of the transaction data structure format, enabling protocol evolution. Currently uses TransactionDataV1 structure. Ensures backward compatibility and enables protocol upgrades without breaking existing transaction formats.
|
||||
The version of the transaction data structure, supporting protocol evolution and backward compatibility. Currently uses 'TransactionDataV1'. Ensures analytics remain robust across protocol upgrades. Example: '1'.
|
||||
{% enddocs %}
|
||||
|
||||
{% docs tx_succeeded %}
|
||||
Boolean indicator of transaction execution success. Values: Success (transaction completed successfully) or Error (transaction failed with error details). Primary indicator for transaction outcome analysis, success rate tracking, and error monitoring.
|
||||
Boolean flag indicating transaction execution outcome. true = success, false = error. Used for outcome analysis, error monitoring, and success rate tracking. Example: true.
|
||||
{% enddocs %}
|
||||
|
||||
{% docs tx_fee %}
|
||||
Complete gas cost for transaction execution in SUI tokens. Calculated as (computation_cost + storage_cost - storage_rebate) / 10^9. Represents the economic cost of transaction execution, essential for cost analysis, fee optimization, and economic modeling.
|
||||
Total gas fee paid for transaction execution, denominated in SUI tokens. Calculated as (computation_cost + storage_cost - storage_rebate) / 1e9. Used for economic modeling, fee optimization, and cost analysis. Example: 0.00123 (SUI).
|
||||
{% enddocs %}
|
||||
|
||||
{% docs tx_error %}
|
||||
Detailed error information when transaction execution fails. Human-readable error messages with error codes providing diagnostic information for failed transactions. Enables debugging, error pattern analysis, and application improvement.
|
||||
Error message and code if the transaction failed. Human-readable string with error details for diagnostics, debugging, and error pattern analysis. Example: 'MoveAbort: InsufficientBalance'.
|
||||
{% enddocs %}
|
||||
|
||||
{% docs tx_dependencies %}
|
||||
Set of transaction digests that this transaction depends upon for object versions. Array of Base58-encoded transaction digests establishing transaction ordering and causality. Important for understanding transaction flow and dependency chains.
|
||||
Array of transaction digests that this transaction depends on for object versions. Establishes transaction ordering and causality, supporting dependency analysis and complex flow tracing. Example: ['6Qk8...9Xz', '7Yl2...3Ab'].
|
||||
{% enddocs %}
|
||||
|
||||
{% docs gas_used_computation_cost %}
|
||||
The total cost in MIST units for computational resources consumed during transaction execution. Calculated as computation_units * gas_price. Represents the validator's computational work cost, used for analyzing transaction complexity and computational efficiency.
|
||||
Total computation cost in MIST units (1 SUI = 1e9 MIST) for executing the transaction. Calculated as computation_units * gas_price. Used for analyzing transaction complexity and validator workload. Example: 1000000.
|
||||
{% enddocs %}
|
||||
|
||||
{% docs gas_used_non_refundable_storage_fee %}
|
||||
The portion of storage fees that cannot be reclaimed when data is deleted. Calculated as storage_units * storage_price * 0.01 (1% of total storage fees). Ensures storage fund sustainability by maintaining baseline capitalization.
|
||||
Portion of storage fees (in MIST) that cannot be reclaimed, ensuring storage fund sustainability. Calculated as storage_units * storage_price * 0.01. Used for economic modeling and storage fund analysis. Example: 10000.
|
||||
{% enddocs %}
|
||||
|
||||
{% docs gas_used_storage_cost %}
|
||||
The total cost in MIST units for storing data on-chain in perpetuity. Calculated as storage_units * storage_price where storage_units = bytes_stored * 100. Users pay upfront for perpetual storage costs.
|
||||
Total cost (in MIST) for storing data on-chain. Calculated as storage_units * storage_price. Users pay this upfront for perpetual storage. Used for storage analytics and cost modeling. Example: 500000.
|
||||
{% enddocs %}
|
||||
|
||||
{% docs gas_used_storage_rebate %}
|
||||
The refund amount in MIST units when previously stored data is deleted. Calculated as original_storage_fee * 0.99 (99% refund). Incentivizes data cleanup and efficient storage usage.
|
||||
Refund amount (in MIST) when previously stored data is deleted. Calculated as original_storage_fee * 0.99. Incentivizes data cleanup and efficient storage usage. Example: 495000.
|
||||
{% enddocs %}
|
||||
|
||||
{% docs gas_price %}
|
||||
The user-submitted price per computation unit in MIST units. Structure: reference_gas_price + tip (optional). Determines transaction priority and total cost, essential for fee market analysis and cost optimization.
|
||||
User-submitted price per computation unit (in MIST). Structure: reference_gas_price + optional tip. Determines transaction priority and total cost. Used for fee market analysis and optimization. Example: 1000.
|
||||
{% enddocs %}
|
||||
|
||||
{% docs gas_budget %}
|
||||
The maximum amount in MIST units that a user is willing to pay for transaction execution. Limits: Minimum 2,000 MIST, Maximum 50,000,000,000 MIST. Provides cost protection for users and is critical for transaction planning.
|
||||
Maximum amount (in MIST) user is willing to pay for transaction execution. Protects users from excessive fees. Minimum: 2,000 MIST, Maximum: 50,000,000,000 MIST. Used for transaction planning and cost control. Example: 1000000.
|
||||
{% enddocs %}
|
||||
|
||||
{% docs gas_owner %}
|
||||
The Sui address responsible for paying gas fees. Enables sponsored transactions where a third party pays gas fees. Important for tracking payment models and gasless user experiences.
|
||||
Sui address responsible for paying gas fees. Enables sponsored transactions (third-party gas payment). Used for payment model analytics and gasless UX studies. Example: '0xabc123...'.
|
||||
{% enddocs %}
|
||||
|
||||
{% docs balance_change_index %}
|
||||
Index ordering balance changes within a transaction. Sequential integer starting from 0 tracking balance modification sequence. Important for accurate financial analysis and reconciliation.
|
||||
Zero-based index ordering balance changes within a transaction. Tracks the sequence of balance modifications for accurate financial analysis and reconciliation. Example: 0.
|
||||
{% enddocs %}
|
||||
|
||||
{% docs coin_type %}
|
||||
Type identifier for coins/tokens using Move's type system. Format: {package}::{module}::{struct}. Example: 0x2::sui::SUI for native SUI token. Identifies token types in multi-asset ecosystem, essential for DeFi analytics.
|
||||
Fully qualified Move type identifier for coins/tokens. Format: {package}::{module}::{struct}. Example: '0x2::sui::SUI' for native SUI token. Essential for DeFi analytics, token classification, and cross-asset analysis.
|
||||
{% enddocs %}
|
||||
|
||||
{% docs amount %}
|
||||
Token quantity in smallest unit (MIST for SUI). Integer format where 1 SUI = 1,000,000,000 MIST. Represents precise token amounts, critical for financial calculations and balance tracking.
|
||||
Token quantity in the smallest unit (MIST for SUI). Integer value; 1 SUI = 1,000,000,000 MIST. Used for precise financial calculations, balance tracking, and token flow analysis. Example: 1000000000.
|
||||
{% enddocs %}
|
||||
|
||||
{% docs owner %}
|
||||
Ownership information for objects/balances. Enum with variants: Address, Shared, or Immutable. Determines object/coin accessibility, important for wallet analytics and ownership distribution studies.
|
||||
Ownership information for objects or balances. Enum: Address (user), Shared (requires consensus), Immutable (cannot change). Determines accessibility and is critical for wallet analytics, ownership distribution, and access control studies. Example: 'Address'.
|
||||
{% enddocs %}
|
||||
|
||||
{% docs change_index %}
|
||||
Sequential index ordering state changes within a transaction. Zero-based sequential numbering ordering object modifications within transactions. Critical for maintaining transaction atomicity in analytics.
|
||||
Zero-based sequential index ordering object state changes within a transaction. Ensures atomicity and correct ordering for analytics and lineage tracing. Example: 2.
|
||||
{% enddocs %}
|
||||
|
||||
{% docs type %}
|
||||
Categorization of object state modifications or event types. Enum values: created, modified, deleted, wrapped, unwrapped for changes. Tracks object lifecycle events, essential for understanding state transitions.
|
||||
Type/category of object state modification or event. Enum: created, modified, deleted, wrapped, unwrapped (for changes); event type string (for events). Used for lifecycle analysis and state transition tracking. Example: 'created'.
|
||||
{% enddocs %}
|
||||
|
||||
{% docs sender %}
|
||||
Transaction sender address in the context of events and changes. 32-byte Sui address representing transaction signing authority. Important for authorization tracking and security analysis.
|
||||
Sui address (32-byte hex) representing the transaction or event sender. Used for authorization, security analysis, and user activity tracking. Example: '0xabc123...'.
|
||||
{% enddocs %}
|
||||
|
||||
{% docs digest %}
|
||||
A 32-byte cryptographic hash of object contents using SHA-256. Hexadecimal string representation enabling content verification and integrity checking. Important for detecting unauthorized modifications.
|
||||
32-byte cryptographic hash (hex) of object contents, using SHA-256. Used for content verification, integrity checking, and unauthorized modification detection. Example: 'a1b2c3...'.
|
||||
{% enddocs %}
|
||||
|
||||
{% docs object_id %}
|
||||
A 32-byte globally unique identifier for objects in Sui's storage system. Hexadecimal string serving as primary key for object identification and tracking. Essential for asset provenance and ownership history.
|
||||
Globally unique 32-byte identifier for Sui objects. Hex string, primary key for object tracking, provenance, and asset history. Example: '0x1234abcd...'.
|
||||
{% enddocs %}
|
||||
|
||||
{% docs object_type %}
|
||||
The Move type that governs the object's structure and behavior. Format: package_address::module_name::struct_name<type_parameters>. Enables type-based object classification and filtering.
|
||||
Move type signature governing the object's structure and behavior. Format: {package}::{module}::{struct}<type_parameters>. Enables type-based classification and filtering. Example: '0x2::coin::Coin<0x2::sui::SUI>'.
|
||||
{% enddocs %}
|
||||
|
||||
{% docs version %}
|
||||
An 8-byte unsigned integer that increments with every transaction modifying the object. Tracks object mutation frequency and enables version-based conflict resolution. Starting value: 1 for newly created objects.
|
||||
8-byte unsigned integer incremented with every object modification. Tracks mutation frequency and supports version-based conflict resolution. Initial value: 1. Example: 5.
|
||||
{% enddocs %}
|
||||
|
||||
{% docs previous_version %}
|
||||
References the immediately preceding version of the object. Value: current_version - 1 (0 for initial creation). Creates immutable audit trail and enables historical state reconstruction.
|
||||
Version number immediately preceding the current object version. Enables historical state reconstruction and audit trails. Value: current_version - 1 (0 for initial creation). Example: 4.
|
||||
{% enddocs %}
|
||||
|
||||
{% docs object_owner %}
|
||||
Indicates how the object can be accessed and who has control. Types: Address-owned, Shared (requires consensus), Immutable (publicly accessible), Object-owned. Determines access patterns and transaction requirements.
|
||||
Indicates how the object is owned and accessed. Types: Address-owned, Shared (consensus), Immutable (public), Object-owned. Determines access patterns and transaction requirements. Example: 'Shared'.
|
||||
{% enddocs %}
|
||||
|
||||
{% docs epoch %}
|
||||
Temporal partition lasting ~24 hours with fixed validator set and protocol configuration. Sequence number starting at 0 defining network operational periods. Critical for tracking validator changes and protocol upgrades.
|
||||
Epoch number (integer) representing a fixed period (~24h) with a stable validator set and protocol configuration. Used for tracking validator changes, protocol upgrades, and time-based partitioning. Example: 42.
|
||||
{% enddocs %}
|
||||
|
||||
{% docs checkpoint_digest %}
|
||||
32-byte cryptographic hash uniquely identifying checkpoint contents. Base58-encoded hash enabling checkpoint verification and integrity checking. Essential for network security and state synchronization.
|
||||
32-byte cryptographic hash (Base58) uniquely identifying checkpoint contents. Used for checkpoint verification, integrity checking, and chain continuity. Example: '6Qk8...9Xz'.
|
||||
{% enddocs %}
|
||||
|
||||
{% docs previous_digest %}
|
||||
Hash of the previous checkpoint, creating blockchain continuity. Base58-encoded hash maintaining blockchain integrity through cryptographic chaining. Critical for history verification and chain analysis.
|
||||
Hash of the previous checkpoint, maintaining blockchain continuity. Used for history verification and chain analysis. Example: '5Jk7...8Yz'.
|
||||
{% enddocs %}
|
||||
|
||||
{% docs network_total_transactions %}
|
||||
Cumulative count of all transactions processed by the network. Monotonically increasing integer serving as key metric for network growth and adoption. Essential for throughput analysis and scaling assessments.
|
||||
Cumulative count of all transactions processed by the network up to this checkpoint. Monotonically increasing integer, key metric for network growth, adoption, and throughput analysis. Example: 10000000.
|
||||
{% enddocs %}
|
||||
|
||||
{% docs validator_signature %}
|
||||
Aggregated BLS signatures from validator quorum (>2/3). Base64-encoded BLS aggregated signature with bitmap providing Byzantine fault-tolerant consensus proof. Critical for security analysis and validator participation tracking.
|
||||
Aggregated BLS signature (Base64) from validator quorum (>2/3) for checkpoint finality. Provides Byzantine fault-tolerant consensus proof. Used for security analysis and validator participation tracking. Example: 'MEUCIQ...'.
|
||||
{% enddocs %}
|
||||
|
||||
{% docs tx_count %}
|
||||
Total number of transactions included in the checkpoint. Integer count defining checkpoint size and transaction throughput. Important for network performance analysis and capacity planning.
|
||||
Total number of transactions included in the checkpoint. Used for measuring checkpoint size, throughput, and network performance. Example: 250.
|
||||
{% enddocs %}
|
||||
|
||||
{% docs transactions_array %}
|
||||
Array of transaction digests included in the checkpoint. Array of Base58-encoded transaction hashes defining checkpoint composition. Essential for transaction finality tracking and checkpoint analysis.
|
||||
Array of transaction digests included in the checkpoint. Used for transaction finality tracking, checkpoint analysis, and reconstructing checkpoint composition. Example: ['6Qk8...9Xz', '7Yl2...3Ab'].
|
||||
{% enddocs %}
|
||||
|
||||
{% docs event_index %}
|
||||
Zero-based sequential index ordering events within a transaction. Sequential numbering starting from 0 providing deterministic event ordering. Essential for event sequence reconstruction and analytics.
|
||||
Zero-based index ordering events within a transaction. Ensures deterministic event ordering for sequence reconstruction and analytics. Example: 1.
|
||||
{% enddocs %}
|
||||
|
||||
{% docs event_address %}
|
||||
The Sui address that triggered the event emission. 32-byte Sui address identifying event origin for filtering and access control. Important for user activity tracking and security auditing.
|
||||
Sui address (32-byte hex) that triggered the event emission. Used for filtering, access control, and user activity analytics. Example: '0xabc123...'.
|
||||
{% enddocs %}
|
||||
|
||||
{% docs event_module %}
|
||||
The name of the Move module that emitted the event. String identifier categorizing events by functional module. Enables module-specific event filtering and analysis.
|
||||
Name of the Move module that emitted the event. Used for module-specific event filtering and analytics. Example: 'coin'.
|
||||
{% enddocs %}
|
||||
|
||||
{% docs event_resource %}
|
||||
The fully qualified type signature of the event struct. Format: <package_id>::<module>::<struct_name><type_parameters>. Enables type-safe event deserialization and schema tracking.
|
||||
Fully qualified type signature of the event struct. Format: {package_id}::{module}::{struct_name}<type_parameters>. Enables type-safe event deserialization and schema tracking. Example: '0x2::coin::TransferEvent<0x2::sui::SUI>'.
|
||||
{% enddocs %}
|
||||
|
||||
{% docs package_id %}
|
||||
The unique identifier of the Move package containing the event module. 32-byte object ID linking events to deployed smart contracts. Essential for package-level analytics and deployment tracking.
|
||||
Unique identifier (object ID) of the Move package containing the event module. Used for package-level analytics, deployment tracking, and contract lineage. Example: '0x2'.
|
||||
{% enddocs %}
|
||||
|
||||
{% docs transaction_module %}
|
||||
The module executed in the transaction that emitted the event. String identifier linking events to transaction context. Important for understanding transaction flow and module interactions.
|
||||
Name of the module executed in the transaction that emitted the event. Links events to transaction context for flow analysis. Example: 'pay_sui'.
|
||||
{% enddocs %}
|
||||
|
||||
{% docs parsed_json %}
|
||||
JSON representation of the event data. JSON object with structure varying by event type. Provides structured event data for analytics, essential for event-driven applications and real-time monitoring.
|
||||
JSON object representing the event data, with structure varying by event type. Provides structured, machine-readable event data for analytics, dApp monitoring, and real-time applications. Example: {"amount": "1000000", "recipient": "0xabc..."}.
|
||||
{% enddocs %}
|
||||
|
||||
{% docs input_index %}
|
||||
References inputs within programmable transaction block. Sequential integer for input array access linking commands to their inputs. Important for understanding transaction dependencies and resource usage patterns.
|
||||
Zero-based index referencing inputs within a programmable transaction block. Links commands to their inputs for dependency and resource usage analysis. Example: 0.
|
||||
{% enddocs %}
|
||||
|
||||
{% docs value %}
|
||||
The actual data content of the object or input value. Variable-sized byte array encoded using Binary Canonical Serialization (BCS). Contains the actual object/input data for content analysis.
|
||||
Actual data content of the object or input value, encoded using Binary Canonical Serialization (BCS). Used for content analysis, debugging, and advanced analytics. Example: '0x010203...'.
|
||||
{% enddocs %}
|
||||
|
||||
{% docs value_type %}
|
||||
Specifies the Move type of the object's value content or input value type. Fully qualified type name with generics enabling type-safe deserialization and schema evolution tracking.
|
||||
Move type of the object's value content or input value type. Fully qualified type name with generics, supporting type-safe deserialization and schema evolution. Example: '0x2::coin::Coin<0x2::sui::SUI>'.
|
||||
{% enddocs %}
|
||||
|
||||
{% docs initial_shared_version %}
|
||||
Records the version at which an object was first shared. Nullable u64 (None for non-shared objects). Determines consensus requirements and helps analyze shared object contention patterns.
|
||||
Version number at which an object was first shared. Nullable u64 (None for non-shared objects). Determines consensus requirements and helps analyze shared object contention. Example: 3.
|
||||
{% enddocs %}
|
||||
|
||||
{% docs mutable %}
|
||||
Boolean flag indicating whether the object can be modified. Values: true (mutable) or false (immutable). Affects performance characteristics and access patterns - immutable objects enable caching and parallel access.
|
||||
Boolean flag indicating if the object can be modified. true = mutable, false = immutable. Affects performance, access patterns, and caching. Example: true.
|
||||
{% enddocs %}
|
||||
|
||||
{% docs payload_index %}
|
||||
Position of payload within programmable transaction block. Sequential integer starting from 0 ordering transaction commands. Essential for understanding complex transaction flows.
|
||||
Zero-based index of the payload within a programmable transaction block. Orders transaction commands for flow analysis. Example: 0.
|
||||
{% enddocs %}
|
||||
|
||||
{% docs payload_type %}
|
||||
Type of command in programmable transaction block. Values: MoveCall, TransferObjects, SplitCoins, etc. Categorizes transaction operations, critical for analyzing dApp interaction patterns.
|
||||
Type of command in a programmable transaction block. Values: MoveCall, TransferObjects, SplitCoins, etc. Used for dApp interaction and protocol analytics. Example: 'MoveCall'.
|
||||
{% enddocs %}
|
||||
|
||||
{% docs payload_details %}
|
||||
Detailed information about specific payload command. Structured data varying by payload type containing complete command specification. Essential for deep transaction analysis and smart contract interaction tracking.
|
||||
Structured details about the specific payload command. Varies by payload type; includes all arguments and context. Used for deep transaction and smart contract analytics. Example: {"function": "transfer", "args": ["0xabc...", 1000]}.
|
||||
{% enddocs %}
|
||||
|
||||
{% docs inserted_timestamp %}
|
||||
Timestamp when the record was inserted into the database. System-generated timestamp for data lineage and ETL tracking. Used for monitoring data freshness and processing delays.
|
||||
Timestamp when the record was inserted into the analytics database. System-generated by the ETL pipeline, typically in TIMESTAMP_NTZ format. Used for data lineage, ETL monitoring, and freshness checks. In Sui analytics, this field is essential for tracking data ingestion latency, validating pipeline health, and supporting incremental model builds. Example: '2024-06-01 12:34:56.789'.
|
||||
{% enddocs %}
|
||||
|
||||
{% docs modified_timestamp %}
|
||||
Timestamp when the record was last modified. System-generated timestamp for change tracking and data versioning. Important for incremental processing and data consistency verification.
|
||||
Timestamp when the record was last modified in the analytics database. System-generated for change tracking, data versioning, and consistency verification. In Sui, this supports incremental processing, late-arriving data correction, and auditability of analytics workflows. Used to monitor data staleness and trigger downstream updates. Example: '2024-06-01 12:34:56.789'.
|
||||
{% enddocs %}
|
||||
|
||||
{% docs fact_checkpoints_id %}
|
||||
Surrogate key for the checkpoint fact table. Generated unique identifier for database relationships and indexing. Primary key enabling efficient queries and joins across checkpoint data.
|
||||
Surrogate key for the checkpoint fact table. Generated unique identifier for each checkpoint record, typically constructed from the checkpoint number or digest. Ensures row-level uniqueness and supports efficient joins, indexing, and lineage tracing across all checkpoint-related analytics. In Sui, this enables fast correlation of checkpoint metadata with transactions, validator signatures, and epoch transitions. Essential for time series analysis, network health monitoring, and data integrity verification.
|
||||
{% enddocs %}
|
||||
|
||||
{% docs fact_events_id %}
|
||||
Surrogate key for the events fact table. Generated unique identifier combining transaction digest and event index. Primary key for event tracking and analytics workflows.
|
||||
Surrogate key for the events fact table. Generated unique identifier combining transaction digest and event index, ensuring each event emission is uniquely addressable. Used as the primary key for event tracking, analytics workflows, and cross-model joins. In Sui, this supports granular dApp analytics, protocol monitoring, and event-driven application logic by enabling precise event referencing and lineage analysis.
|
||||
{% enddocs %}
|
||||
|
||||
{% docs fact_transaction_balance_changes_id %}
|
||||
Surrogate key for the balance changes fact table. Generated unique identifier combining transaction digest and balance change index. Primary key for financial analysis and balance tracking.
|
||||
Surrogate key for the balance changes fact table. Generated unique identifier by combining transaction digest and balance change index, guaranteeing uniqueness for each balance change event. Critical for financial analysis, reconciliation, and tracking token flows at the most granular level. In Sui, this enables accurate wallet balance reconstruction, detection of large transfers, and portfolio analytics across all addresses and token types.
|
||||
{% enddocs %}
|
||||
|
||||
{% docs fact_changes_id %}
|
||||
Surrogate key for the object changes fact table. Generated unique identifier combining transaction digest and change index. Primary key for object lifecycle analysis and state tracking.
|
||||
Surrogate key for the object changes fact table. Generated unique identifier by combining transaction digest and change index, ensuring each object state transition is uniquely tracked. Supports object lifecycle analysis, state tracking, and forensic investigations. In Sui, this is essential for tracing the full history of NFTs, coins, and other on-chain objects, supporting compliance, provenance, and application behavior analytics.
|
||||
{% enddocs %}
|
||||
|
||||
{% docs fact_transaction_blocks_id %}
|
||||
Surrogate key for the transaction blocks fact table. Generated unique identifier based on transaction digest. Primary key for transaction-level analysis and performance monitoring.
|
||||
Surrogate key for the transaction blocks fact table. Generated unique identifier based on transaction digest, providing a one-to-one mapping to each transaction block. Enables efficient transaction-level analysis, performance monitoring, and lineage tracing from transaction inputs to execution outcomes. In Sui, this is critical for understanding transaction dependencies, gas usage, and execution results at scale.
|
||||
{% enddocs %}
|
||||
|
||||
{% docs fact_transaction_inputs_id %}
|
||||
Surrogate key for the transaction inputs fact table. Generated unique identifier combining transaction digest and input index. Primary key for transaction dependency analysis and input tracking.
|
||||
Surrogate key for the transaction inputs fact table. Generated unique identifier by combining transaction digest and input index, ensuring each input to a transaction is uniquely addressable. Supports dependency analysis, resource utilization tracking, and validation of transaction atomicity. In Sui, this enables detailed tracing of input objects, shared object usage, and parallel execution patterns.
|
||||
{% enddocs %}
|
||||
|
||||
{% docs fact_transactions_id %}
|
||||
Surrogate key for the transactions fact table. Generated unique identifier combining transaction digest and payload index. Primary key for transaction payload analysis and command tracking.
|
||||
Surrogate key for the transactions fact table. Generated unique identifier by combining transaction digest and payload index, uniquely identifying each command or payload within a programmable transaction block. Essential for command-level analytics, smart contract interaction tracking, and composability analysis in Sui's multi-command transaction model.
|
||||
{% enddocs %}
|
||||
|
||||
{% docs dim_tokens_id %}
|
||||
Surrogate key for the tokens dimension table. Generated unique identifier for token metadata. Primary key enabling efficient token lookups and joins across fact tables.
|
||||
Surrogate key for the tokens dimension table. Generated unique identifier for each token metadata record, typically derived from the coin type or on-chain metadata. Enables efficient token lookups, joins across fact tables, and lineage tracing from raw on-chain data to analytics-ready attributes. In Sui, this is critical for accurate token identification, decimal normalization, and cross-model analytics involving token flows and balances.
|
||||
{% enddocs %}
|
||||
|
||||
{% docs coin_types_id %}
|
||||
Surrogate key for coin types. Generated unique identifier for coin type classification. Used for indexing and joining coin type information across analytics queries.
|
||||
Surrogate key for coin types. Generated unique identifier for each coin type, supporting classification, indexing, and efficient joins across analytics queries. In Sui, this enables fast aggregation and filtering by token type, supporting DeFi analytics, token velocity studies, and ecosystem-wide token usage analysis.
|
||||
{% enddocs %}
|
||||
|
||||
{% docs decimals %}
|
||||
Number of decimal places for the token. Integer value defining token precision (e.g., 9 for SUI meaning 1 SUI = 1,000,000,000 MIST). Essential for accurate token amount calculations and display formatting.
|
||||
Number of decimal places for the token. Integer value defining token precision (e.g., 9 for SUI means 1 SUI = 1,000,000,000 MIST). Essential for accurate token amount calculations, display formatting, and cross-token analytics. Example: 9.
|
||||
{% enddocs %}
|
||||
|
||||
{% docs symbol %}
|
||||
Token symbol identifier. Short string representation of the token (e.g., "SUI", "USDC"). Used for user-friendly token identification and display in applications.
|
||||
Short string symbol for the token (e.g., 'SUI', 'USDC'). Used for user-friendly token identification, UI display, and analytics grouping. Example: 'SUI'.
|
||||
{% enddocs %}
|
||||
|
||||
{% docs name %}
|
||||
Full descriptive name of the token. Human-readable string providing complete token identification. Used for detailed token information and user interfaces.
|
||||
Full descriptive name of the token. Human-readable string for complete token identification, used in interfaces and analytics. Example: 'Sui Token'.
|
||||
{% enddocs %}
|
||||
|
||||
{% docs description %}
|
||||
Detailed description of the token's purpose and functionality. Text field providing comprehensive token information including use cases, features, and technical details.
|
||||
Detailed description of the token's purpose, features, and technical details. Used for documentation, analytics, and user interfaces. Example: 'Native token of the Sui blockchain, used for gas and staking.'
|
||||
{% enddocs %}
|
||||
|
||||
{% docs icon_url %}
|
||||
URL pointing to the token's icon image. Web URL for token visual representation used in wallets and applications. Enables consistent token branding across the ecosystem.
|
||||
Web URL pointing to the token's icon image. Used for visual representation in wallets, dApps, and analytics dashboards. Example: 'https://assets.sui.io/icons/sui.svg'.
|
||||
{% enddocs %}
|
||||
|
||||
{% docs id %}
|
||||
Unique identifier for the token metadata. System-generated identifier linking token metadata to on-chain token types. Used for metadata management and token registry operations.
|
||||
Unique identifier for the token metadata record, linking metadata to on-chain token types. Used for metadata management, registry operations, and analytics joins. Example: 'tokenmeta_123'.
|
||||
{% enddocs %}
|
||||
@ -1,31 +1,31 @@
|
||||
{% docs core__dim_tokens %}
|
||||
Dimension table containing comprehensive token metadata for all coins and tokens on the Sui blockchain. This model provides enriched token information including decimals, symbols, names, descriptions, and icon URLs sourced from on-chain metadata. The table serves as the primary reference for token details used across all analytics workflows and fact tables. Data is sourced from the bronze_api__coin_metadata model and includes both native SUI tokens and custom tokens deployed on the network. Essential for token identification, decimal adjustment calculations, and user interface display formatting.
|
||||
Dimension table providing authoritative metadata for all fungible and non-fungible tokens on the Sui blockchain. Includes decimals, symbols, names, descriptions, and icon URLs sourced from on-chain metadata and Move package definitions. Serves as the canonical reference for token identification, decimal normalization, and UI display across analytics workflows. Data is sourced from bronze_api__coin_metadata and cross-referenced with on-chain Move modules, covering both native SUI and custom tokens. Essential for accurate balance calculations, token flow analysis, and user-facing applications. Supports lineage tracing from raw on-chain metadata to analytics-ready token attributes.
|
||||
{% enddocs %}
|
||||
|
||||
{% docs core__fact_balance_changes %}
|
||||
Fact table capturing all balance changes for tokens and coins on the Sui blockchain. Each record represents a balance change event within a transaction, including the amount changed, coin type, and owner information. This table is essential for tracking token movements, wallet balances, and transaction impacts across the network. Data includes both positive and negative balance changes, enabling comprehensive financial analysis and reconciliation. The table supports portfolio tracking, treasury management, and token flow analysis across all addresses and token types in the Sui ecosystem.
|
||||
Fact table recording every token and coin balance change event on the Sui blockchain at the finest granularity. Each row represents a single balance delta (positive or negative) for a specific owner, coin type, and transaction, capturing the full flow of assets across wallets and contracts. Includes object IDs, transaction context, and ownership metadata, supporting precise tracking of token movements, portfolio changes, and treasury operations. Enables reconstruction of wallet balances, detection of large transfers, and analysis of token velocity. Data is derived from transaction execution effects and object state transitions, following Sui's explicit ownership and versioning model.
|
||||
{% enddocs %}
|
||||
|
||||
{% docs core__fact_changes %}
|
||||
Fact table documenting all object changes that occur within transactions on the Sui blockchain. This includes created, modified, deleted, wrapped, and unwrapped objects, providing a complete audit trail of object state changes. Essential for tracking object lifecycle, ownership transfers, and state mutations across the network. The table captures the full spectrum of object modifications including version changes, ownership transfers, and type transformations. Critical for compliance reporting, forensic analysis, and understanding application behavior patterns in the Sui object model.
|
||||
Fact table capturing all object state transitions on the Sui blockchain, including creation, mutation, deletion, wrapping, and unwrapping of objects. Each record documents the full lifecycle of Sui objects (NFTs, coins, packages, etc.) as they are manipulated by transactions. Includes object IDs, versions, types, and ownership changes, enabling forensic analysis, compliance reporting, and application behavior tracing. Supports lineage analysis by linking object changes to specific transactions, epochs, and owners. Critical for understanding Sui's object-centric data model and for tracking resource flows, upgrades, and state mutations across the network.
|
||||
{% enddocs %}
|
||||
|
||||
{% docs core__fact_checkpoints %}
|
||||
Fact table containing information about checkpoints in the Sui blockchain. Each checkpoint represents a consensus point that bundles multiple transactions together, serving as the primary unit of finality in Sui. This table includes checkpoint metadata, transaction counts, validator signatures, and epoch information essential for network analysis and data integrity verification. Checkpoints are formed approximately every 250ms through the Mysticeti consensus mechanism. The table is fundamental for understanding network throughput, validator participation, and transaction finality across the Sui blockchain.
|
||||
Fact table representing all finalized checkpoints on the Sui blockchain, which serve as consensus points bundling multiple transactions for finality and recovery. Each checkpoint aggregates metadata such as checkpoint sequence number, timestamp, transaction count, validator signatures, and epoch information. Checkpoints are produced via the Mysticeti consensus mechanism approximately every 250ms, providing the backbone for time series analysis (TPS, latency, validator participation). This table is essential for measuring network throughput, tracking validator performance, and ensuring data integrity. Supports analytics on epoch transitions, validator set changes, and network health.
|
||||
{% enddocs %}
|
||||
|
||||
{% docs core__fact_events %}
|
||||
Fact table capturing all events emitted by transactions on the Sui blockchain. Events represent structured data emissions from smart contracts and system operations, providing detailed insights into application-specific activities. This table includes event metadata, parsed JSON data, and categorization essential for dApp analytics and protocol monitoring. Events are emitted by Move modules during transaction execution and contain rich contextual information about contract interactions. The table supports real-time monitoring, business intelligence, and protocol analytics across the entire Sui ecosystem.
|
||||
Fact table logging all events emitted by Move smart contracts and system operations during transaction execution on Sui. Each event is a structured data emission containing contract-specific or protocol-level information, including event type, JSON payload, emitting module, and transaction context. Enables deep dApp analytics, protocol monitoring, and behavioral analysis by exposing granular details of on-chain activity. Events are indexed by transaction and checkpoint, supporting real-time monitoring, anomaly detection, and business intelligence use cases. Essential for understanding contract interactions, user engagement, and protocol-level trends in the Sui ecosystem.
|
||||
{% enddocs %}
|
||||
|
||||
{% docs core__fact_transaction_blocks %}
|
||||
Fact table providing comprehensive transaction-level information for all transactions on the Sui blockchain. This table serves as the primary source for transaction metadata, including success status, gas usage, fees, and error information. Essential for transaction analysis, fee optimization, and network performance monitoring. The table includes detailed gas breakdowns, dependency tracking, and execution outcomes. Critical for understanding network economics, user behavior patterns, and application performance across the Sui blockchain infrastructure.
|
||||
Fact table providing detailed metadata for every transaction block executed on the Sui blockchain. Includes transaction hash, sender, success status, gas usage, fee breakdowns, error codes, and dependency tracking. Serves as the primary source for transaction-level analytics, fee optimization, and network performance monitoring. Supports lineage tracing from transaction inputs to execution outcomes, including gas smashing, storage fee rebates, and error diagnostics. Critical for understanding Sui's transaction model, user behavior, and application performance at scale.
|
||||
{% enddocs %}
|
||||
|
||||
{% docs core__fact_transaction_inputs %}
|
||||
Fact table documenting all inputs used by transactions on the Sui blockchain. This includes objects, pure values, and shared objects that transactions reference or consume during execution. Essential for understanding transaction dependencies, object usage patterns, and input validation across the network. The table captures input types, versions, mutability flags, and ownership information. Important for analyzing transaction complexity, resource utilization, and dependency chains in complex multi-step transactions and smart contract interactions.
|
||||
Fact table enumerating all inputs consumed by transactions on the Sui blockchain, including owned objects, shared objects, pure values, and input types. Each record details the object ID, version, mutability, and ownership at the time of transaction execution. Enables dependency analysis, resource utilization tracking, and validation of transaction atomicity. Supports analytics on input complexity, shared object usage, and transaction parallelism. Essential for understanding how Sui's object-centric model enables parallel execution and for tracing the full dependency graph of complex transactions.
|
||||
{% enddocs %}
|
||||
|
||||
{% docs core__fact_transactions %}
|
||||
Fact table capturing the detailed payload structure of all transactions on the Sui blockchain. This table breaks down transaction commands into individual components, providing granular visibility into Move function calls, transfers, and other transaction operations. Essential for understanding transaction composition and smart contract interactions. The table includes payload types, command details, and execution order information. Critical for analyzing dApp usage patterns, protocol interactions, and transaction complexity across the Sui ecosystem.
|
||||
Fact table decomposing every transaction on the Sui blockchain into its constituent commands and payloads. Each row represents a single command (e.g., Move call, transfer, split, merge) within a programmable transaction block, capturing execution order, command type, and argument details. Enables granular analysis of smart contract interactions, dApp usage patterns, and transaction complexity. Supports lineage tracing from high-level user actions to low-level on-chain effects, including Move function calls and resource transfers. Critical for protocol analytics, developer adoption tracking, and understanding composability in the Sui ecosystem.
|
||||
{% enddocs %}
|
||||
Loading…
Reference in New Issue
Block a user