Skip to main content

Required Interfaces

This page documents the Node interface and all required data types.

Node Interface​

All nodes must implement the Node interface:

interface Node {
  processRequest(input: SwapRequest): Promise<NodeResult<SwapResponse>>;
  getSupportedTokens(): ChainToken[];
  getReserveTokens(): ChainToken[];
  getId(): string;
  syncState(): Promise<NodeResult<void>>;
  isSwapEnabled(inputToken: ChainToken, outputToken: ChainToken): boolean;
  getSupportedChainIds(): string[];
  getTransactionRecord(transactionHash: string): Promise<NodeResult<TransactionRecord>>;
}

Method Descriptions​

getId(): string​

Returns the node identifier used in routing and responses. This ID must be unique across all nodes and match the registration in ts/src/nodes/index.ts.

getSupportedTokens(): ChainToken[]​

Returns all tokens this node supports, normalized as ChainToken objects. This list is populated during syncState() by fetching from your provider's API.

getReserveTokens(): ChainToken[]​

Returns tokens this node keeps as reserves or requires for operations. These are typically native gas tokens, bridge tokens, or tokens the node holds inventory of.

getSupportedChainIds(): string[]​

Returns the set of supported chain IDs. These should be canonical chain identifiers used across the project.

syncState(): Promise<NodeResult<void>>​

Bootstraps and refreshes all runtime data the node needs to operate. Called on startup and periodically to keep data fresh. Should be idempotent and resilient to partial failures.

isSwapEnabled(inputToken: ChainToken, outputToken: ChainToken): boolean​

Fast, synchronous eligibility check to determine if a token pair can be swapped. Must be fast and synchronous - no network calls or heavy computation.

processRequest(input: SwapRequest): Promise<NodeResult<SwapResponse>>​

Main entrypoint for processing swap requests. Validates input, checks eligibility, calls your provider's API to get quotes/rates, and returns a standardized SwapResponse.

getTransactionRecord(transactionHash: string): Promise<NodeResult<TransactionRecord>>​

Retrieve and normalize a transaction's status and details into a TransactionRecord. Used to track swap progress and provide status updates to clients.

Data Types​

ChainToken​

Standardized token representation:

type ChainToken = {
  chain_id: string;    // Chain identifier (e.g., "1", "polygon", "solana")
  address: string;     // Token contract address or symbol
  decimals: number;    // Token decimal places
};

SwapRequest​

Input format for swap requests:

type SwapRequest = {
  input_token: ChainToken | null;
  output_token: ChainToken | null;
  amount_in: string;                    // Amount in smallest unit
  amount_out_min: string;              // Minimum output amount
  slippage_tolerance: number;          // Slippage in basis points
  recipient_address: string;           // Destination address
  sender_address: string;              // Source address
  exact_out: boolean;                  // Whether this is exact output swap
  generate_deposit_address: boolean;   // Whether to generate deposit address
  timeout_ms: number;                  // Request timeout in milliseconds
};

SwapResponse​

Output format for swap responses:

type SwapResponse = {
  uuid: string;                        // Unique identifier
  amount_out: string;                  // Output amount
  output_token: ChainToken | null;
  amount_in: string;                   // Input amount
  amount_in_with_fee: string;          // Input amount including fees
  input_token: ChainToken | null;
  refund_address: string;              // Address for refunds
  recipient_address: string;           // Destination address
  chain_id: string;                    // Source chain ID
  partner_id: number;                  // Partner identifier
  deposit_address: string;             // Deposit address (if applicable)
  quote_expiry: number;                 // Quote expiration timestamp
  execution_time: number;               // Estimated execution time in ms
  slippage_tolerance: number;          // Applied slippage tolerance
  node_id: string;                     // Node identifier
  node_type: NodeType;                 // Type of node
  transaction_data: TransactionData | null; // Transaction data for execution
};

TransactionRecord​

Transaction status and details:

type TransactionRecord = {
  source_transaction_hash: string;
  destination_transaction_hash: string | null;
  source_timestamp: number;
  destination_timestamp: number | null;
  node: string;
  sender: string;
  amount_in: string;
  input_token: ChainToken;
  output_token: ChainToken;
  amount_out: string;
  recipient_address: string;
  status: TransactionStatus;
};

NodeCapabilities​

Defines what a node can do:

type NodeCapabilities = {
  supportsSwaps: boolean;           // Does this node support swaps?
  supportsCrossChain: boolean;      // Does this node support cross-chain swaps?
  supportsNativeWrapping: boolean;  // Does this node support native token wrapping?
  maxSupportedChains: number;       // Maximum number of supported chains
  supportedTxTypes: TransactionType[]; // Supported transaction types
};

NodeSpecificConfig​

Node-specific configuration:

type NodeSpecificConfig = {
  apiEndpoint: string;
  apiKey: string | null;
  headers: Record<string, string>;
  timeout: number;
  retryConfig?: {
    maxRetries: number;
    retryDelay: number;
    backoffFactor: number;
  };
};

Next Steps​