Skip to main content

Architecture Overview

The Xplore Nodes system follows a modular architecture where each node implements a standardized interface. This page explains the system architecture and how nodes fit into the overall system.

System Components​

The Xplore Nodes system consists of several key components:

Node Interface​

Defines the contract that all nodes must implement. Every node must provide:

  • Request Processing: Handle swap requests and return standardized responses
  • State Management: Sync and maintain node state (tokens, chains, etc.)
  • Token Management: Provide lists of supported and reserve tokens
  • Validation: Check if swaps are enabled for token pairs
  • Transaction Tracking: Retrieve transaction status and records

Router​

Routes requests to appropriate nodes based on node ID. The router:

  • Dispatches requests to the correct node instance
  • Handles node registration and discovery
  • Manages node lifecycle and state
  • Provides fallback mechanisms for unavailable nodes

State Management​

Handles node registration and synchronization:

  • Node Registration: Registers nodes on startup
  • State Sync: Coordinates periodic state synchronization
  • Node Discovery: Provides information about available nodes
  • Health Monitoring: Tracks node availability and status

Error Handling​

Standardized error reporting across all nodes:

  • Error Codes: Predefined error codes for common scenarios
  • Error Types: Structured error objects with codes and messages
  • Error Propagation: Consistent error handling throughout the system

Type System​

Shared types for requests, responses, and data structures:

  • ChainToken: Standardized token representation
  • SwapRequest: Input format for swap requests
  • SwapResponse: Output format for swap responses
  • TransactionRecord: Transaction status and details

Node Lifecycle​

  1. Initialization: Node is instantiated with configuration
  2. Registration: Node registers itself with the state manager
  3. State Sync: Node syncs its state (tokens, chains, etc.)
  4. Ready: Node is ready to process requests
  5. Request Processing: Node handles swap requests
  6. Periodic Sync: Node periodically refreshes its state

Node Types​

Nodes can be categorized by their capabilities:

  • Bridge Nodes: Handle cross-chain swaps
  • DEX Nodes: Handle same-chain swaps
  • Hybrid Nodes: Support both same-chain and cross-chain

Integration Points​

When integrating a new node, you'll interact with:

  1. Node Trait: Implement the Node interface
  2. Type System: Use standardized types for data structures
  3. Error System: Use NodeError for error handling
  4. State Manager: Register your node with registerNode()
  5. Router: Your node will be automatically routed by the router

Next Steps​