Skip to main content

Code Structure

This page explains the directory layout and organization of the Xplore Nodes codebase.

Directory Layout​

ts/src/
├── nodes/
│   ├── your-node/
│   │   ├── common.ts          # Main implementation
│   │   ├── index.ts           # Exports
│   │   ├── flows/
│   │   │   ├── index.ts
│   │   │   └── native.ts      # Node registration
│   │   └── tests/
│   │       └── your-node.test.ts
│   ├── common/                # Shared utilities
│   │   ├── chains.ts          # Chain definitions
│   │   └── index.ts
│   └── index.ts               # Main nodes export
├── node_trait.ts              # Node interface
├── types.ts                   # Type definitions
├── error.ts                   # Error handling
├── state.ts                   # Node registration
├── router.ts                  # Request routing
└── index.ts                   # Main server

Key Files​

Core System Files​

node_trait.ts​

Defines the Node interface that all nodes must implement. This is the contract that ensures consistency across all node implementations.

types.ts​

Contains shared type definitions for:

  • NodeCapabilities: What a node can do (swaps, cross-chain, etc.)
  • NodeSpecificConfig: Node-specific configuration (API endpoints, timeouts, etc.)
  • TransactionType: Supported transaction types (EVM, Solana, etc.)

error.ts​

Standardized error handling with:

  • NodeError class: Structured error objects
  • NodeResult<T>: Result type that can be a value or error
  • Error codes: Predefined error codes for common scenarios

state.ts​

Node registration and management system:

  • registerNode(): Register a node with the system
  • NodeDescriptor: Interface for node registration
  • Node discovery and state management

router.ts​

Routes requests to appropriate nodes:

  • Node lookup by ID
  • Request dispatching
  • Fallback mechanisms

xplore-types/​

Shared data structures for requests and responses:

  • ChainToken: Token representation
  • SwapRequest: Input format
  • SwapResponse: Output format
  • TransactionRecord: Transaction status

Node Implementation Files​

common.ts​

Main node implementation containing:

  • Node class definition
  • All required method implementations
  • Helper methods and utilities
  • Configuration and state management

flows/​

Different modes or flows for the node:

  • Each flow represents a different node instance
  • Flows register nodes with different configurations
  • Example: native.ts, advanced.ts, api.ts

tests/​

Test files for the node:

  • Unit tests for individual methods
  • Integration tests with real APIs
  • End-to-end tests

File Organization Best Practices​

  1. Keep implementations in common.ts: Main logic should be in the common file
  2. Separate flows by mode: Use flows directory for different node modes
  3. Test alongside code: Keep tests close to implementation
  4. Export cleanly: Use index files for clean exports

Next Steps​