Node-Level Architecture

This document provides a detailed view of the internal architecture of Movement L1 nodes, covering the various components, their interactions, and the data flows within a single node instance. For the high-level system architecture and network design, see L1 Architecture.

Core Layers

The Movement L1 node architecture is organized into five core layers, each handling specific aspects of node functionality while working together to provide a complete, high-performance blockchain node. These layers correspond directly to the L1 architecture but focus on the internal implementation details of individual nodes rather than the overall system design.

┌─────────────────────────────────────────────────────────────────────┐
│                        Movement L1 Node                             │
├─────────────────────────────────────────────────────────────────────┤
│  1. API Layer                                                       │
│  ┌─────────────┐ ┌─────────────┐ ┌─────────────┐                    │
│  │   RPC/API   │ │  WebSocket  │ │   Metrics   │                    │
│  │   Server    │ │   Server    │ │   Exporter  │                    │
│  └─────────────┘ └─────────────┘ └─────────────┘                    │
├─────────────────────────────────────────────────────────────────────┤
│  2. Storage Layer                                                   │
│  ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐    │
│  │   State     │ │ Transaction │ │   Event     │ │   Config    │    │
│  │   Store     │ │    Store    │ │   Store     │ │   Store     │    │
│  └─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘    │
├─────────────────────────────────────────────────────────────────────┤
│  3. Execution Layer                                                 │
│  ┌─────────────┐ ┌─────────────┐ ┌─────────────┐                    │
│  │ Transaction │ │   Executor  │ │ State Cache │                    │
│  │  Validator  │ │   Engine    │ │   Manager   │                    │
│  └─────────────┘ └─────────────┘ └─────────────┘                    │
├─────────────────────────────────────────────────────────────────────┤
│  4. Consensus Layer                                                 │
│  ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐    │
│  │  Consensus  │ │   Voting    │ │   Leader    │ │   Safety    │    │
│  │   Engine    │ │   Module    │ │  Election   │ │   Module    │    │
│  └─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘    │
├─────────────────────────────────────────────────────────────────────┤
│  5. Network Layer                                                   │
│  ┌─────────────┐ ┌─────────────┐                                    │
│  │   P2P Net   │ │   Mempool   │                                    │
│  │   Handler   │ │   Manager   │                                    │
│  └─────────────┘ └─────────────┘                                    │
└─────────────────────────────────────────────────────────────────────┘

1. API Layer

RPC/API Server

The RPC/API Server provides external API access to node functionality. The RPC/API Server provides transaction submission endpoints for submitting signed transactions to the network, state queries for querying account states and resource data, block information retrieval for block and transaction data, and network status endpoints for getting node and network health information.

WebSocket Server

The WebSocket Server provides real-time event streaming to subscribers. The WebSocket Server streams new block notifications in real-time, transaction confirmation status updates, account change notifications for state changes, and network events including validator set changes and other network events.

Metrics Exporter

The Metrics Exporter exports node performance and health metrics. It tracks performance metrics including transaction throughput, latency, and CPU usage, network metrics such as peer count, message rates, and bandwidth usage, storage metrics covering database size, disk I/O, and cache hit rates, and consensus metrics including participation rates and voting statistics.

2. Storage Layer

State Store

The State Store provides persistent storage of global blockchain state. It supports efficient read operations with Merkle proofs for state queries, atomic write operations with versioning for state updates, proof generation for cryptographic proofs of state, and state synchronization to sync state with other nodes.

Transaction Store

The Transaction Store stores the complete transaction history and metadata

Event Store and Indexing

The Event Store provides indexing by event key for fast queries of specific event streams, by type to query events by Move type, by transaction to find all events from a specific transaction, and by block to retrieve all events from a block.

Configuration Store

The Configuration Store stores node configuration and network parameters. The Configuration Store manages network configuration for peer discovery and connection limits, consensus configuration for voting timeouts and block limits, execution configuration for gas prices and resource limits, and API configuration for rate limits and authentication settings.

3. Execution Layer

Transaction Validator

The Transaction Validator validates transaction signatures, format, and basic checks in the following steps:

1. Signature Verification: Cryptographic signature validation
2. Format Checking: Transaction structure and field validation
3. Sequence Validation: Account sequence number verification
4. Gas Validation: Gas price and limit verification
5. Balance Checking: Sufficient balance for transaction fees

Executor Engine

The Executor Engine executes validated transactions using the MoveVM and through the following pipeline:

1. Transaction Preparation: Load account states and dependencies
2. MoveVM Execution: Execute Move bytecode in sandboxed environment
3. State Updates: Apply changes to global state
4. Event Generation: Generate events for state changes
5. Gas Accounting: Calculate and charge gas fees

State Cache Manager

The State Cache Manager manages in-memory caching of frequently accessed state. The State Cache Manager maintains an account cache for recently accessed account states, a resource cache for frequently queried Move resources, a module cache for compiled Move module bytecode, and a Merkle cache for recently computed Merkle tree nodes.

4. Consensus Layer

Consensus Engine

The Consensus Engine coordinates the Byzantine Fault Tolerant consensus protocol through the following flow:

1. Block Proposal: Leader proposes a block containing transactions and a Quorum Certificate (QC) for its parent.
2. Voting Phase: Validators verify the proposal and cast vote messages.
3. QC Formation: Votes are aggregated into a Quorum Certificate attesting to the block's validity.
4. Block Commit: Once a 3-chain of consecutive certified blocks is formed, the earliest block in the chain is finalized and added to the ledger.

Voting Module

The Voting Module handles vote creation, validation, aggregation, and timeout votes for liveness. It has the following vote types:

• block vote: validator’s signature attesting to a proposed block.
• timeout vote: issued if no valid proposal is received in time, can aggregate into a Timeout Certificate (TC) to trigger a new leader view.

Leader Election

The Leader Election determines which validator proposes the next block. The Leader Election uses weighted selection with probability proportional to validator stake, ensuring deterministic selection where the same leader is chosen by all honest validators. The algorithm implements regular rotation to prevent centralization and guarantees liveness with progress even when some validators are offline.

Safety Module

The Safety Module ensures consensus safety properties are maintained. The Safety Module performs conflicting vote detection to prevent double voting, fork detection to identify potential blockchain forks, slashing evidence collection for malicious behavior, and implements recovery mechanisms to handle network partitions and attacks.

5. Network Layer

P2P Network Handler

The P2P Network Handler manages peer-to-peer communication with other nodes. The P2P Network Handler consists of a connection manager that establishes and maintains connections to peers, a message router that routes incoming messages to appropriate handlers, a gossip protocol that implements efficient information dissemination, and peer discovery mechanisms that discover and connect to new network peers.

Mempool Manager

The Mempool Manager manages pending transactions before consensus. The Mempool Manager includes a transaction pool for in-memory storage of pending transactions, a priority queue that orders transactions by gas price and priority, a spam filter that prevents spam and invalid transactions, and an expiration manager that removes expired transactions.

Node Types and Specialization

Validator Nodes

Validator nodes provide active consensus participation in block production, performing state validation by verifying all state transitions and contributing to network security through staking mechanisms. These nodes participate in protocol governance decisions and include full consensus participation with complete consensus engine activation, block production capabilities for proposing and creating blocks, validator key management for secure storage of validator keys, and slashing protection against slashing conditions.

Full Nodes

Full nodes maintain complete state synchronization of the blockchain state, providing transaction relay services that forward transactions to the validator network and offering API services with endpoints for applications. These nodes ensure data availability for network participants and are configured with complete state synchronization for state replication, full API services with complete endpoint availability, real-time event streaming for notifications, and mempool participation for transaction relay and validation.

Light Nodes

Light nodes implement selective synchronization by syncing only relevant account data, performing proof verification without maintaining full state and achieving resource efficiency with minimal storage and bandwidth requirements. These nodes provide mobile support optimized for mobile and embedded devices, with reduced storage requirements and bandwidth optimization through efficient data transfer protocols.

Performance Optimization

Caching Strategies

Performance optimization employs LRU cache with Least Recently Used eviction for hot data, write-through cache for consistent caching with persistent storage, bloom filters for fast negative lookups of non-existent data, and data compression for storage and network transfer efficiency.

Parallel Processing

The system implements transaction parallelization for concurrent execution of independent transactions, I/O parallelization through asynchronous disk and network operations, multi-threading for CPU-intensive operations on multiple cores, and pipeline processing to overlap computation and I/O operations.

Resource Management

Resource management includes memory pools with pre-allocated memory for frequent operations, connection pooling to reuse database and network connections, efficient garbage collection for cleanup of temporary data, and rate limiting to prevent resource exhaustion from excessive load.

Monitoring and Diagnostics

Health Checks

Health checks monitor network connectivity for peer connection status, consensus participation including voting and block production rates, storage health for database integrity and performance, and resource utilization covering CPU, memory, and disk usage.

Logging and Tracing

The system implements structured logging with machine-readable log formats, distributed tracing for request tracing across components, performance metrics with detailed timing and throughput data, and comprehensive error tracking for error collection and analysis.

Debugging Tools

Debugging tools provide state inspection capabilities for examining blockchain state, transaction simulation for testing transaction execution, network analysis to analyze peer connections and message flow, and performance profiling to identify performance bottlenecks.