Architecture

System Overview

MultiHopper is built as a layered system. The protocol layer enforces all routing guarantees on-chain; the application layer provides the tooling to create and monitor routes.

User / Integrator
      ↓
  REST API / App
      ↓
 Keeper Network
      ↓
  Smart Contracts (Anchor / Rust)
      ↓
  Solana + Token2022

Smart Contracts

Two on-chain programs implement the protocol:

MultiHopper Core

3jLoS2wbNgtKzieUUxwg6Xhdv6gbZkHDtPWA9ZAgspFhHandles route creation, hop execution, wrap/unwrap operations, fee collection, provider registration, and fee schedule management. This is the primary program for all route interactions.

Orchestrator

4TPCmR2uN3hDM1FbTsf7ZtFXwXGSz4u1Kxv5YHj6eruXA permissionless execution engine that breaks route deployment into discrete keeper-executable steps. Manages the multi-transaction sequence needed to fund and initialize a route on behalf of the creator.

Transfer Hook Guard

2JEv3pD6nczEvn1xDXaEzehkJofPPjoQQpnW5nGY3r52Implements the Token2022 transfer hook extension for all wrapper mints. Enforces that only the protocol program can move wrapper tokens and that every transfer occurs within a valid, active route context.

Key On-Chain Accounts

MultiHopper Core

Account	Seed	Description
`RouteConfig`	`[b"route", route_id_le_bytes]`	Stores the full route definition: hop sequence, recipients, amounts, timing, prepaid hops, provider, and execution state
`RouteState`	`[b"state", route_id_le_bytes]`	Mutable execution state for the route — tracks hop progress and finalization
`PermanentDelegate`	`[b"delegate", route_id_le_bytes]`	PDA holding permanent delegate authority over the wrapper mint
`Vault` (SPL)	`[b"vault_authority", original_mint]`	Program-controlled token account holding original deposited SPL tokens
`SolVault`	`[b"sol_vault", token_config_creator]`	Program-controlled lamport vault for SOL routes
`WrapperMint`	`[b"mint_authority", route_id_le_bytes]`	Token2022 mint with permanent delegate, metadata pointer, and transfer hook extensions
`TokenConfig`	`[b"token_config_global_v2"]`	Global token configuration account
`Provider`	`[b"provider", provider_id]`	Integrator registration — stores provider wallet and ID
`FeeSchedule`	`[b"fee_schedule", provider_id]`	Tiered fee tiers for a registered provider

Orchestrator

Account	Seed	Description
`OrchestratorConfig`	`[b"orchestrator"]`	Stores the full step sequence, keeper share in basis points, step count, and creator
`OrchestratorStep`	`[b"step", orchestrator_id, step_index]`	Individual step with type, execute_at timestamp, and execution state

Application Layer

Component	Technology	Purpose
Web App	React 18/19, Vite, TailwindCSS	Route creation UI, wallet connection, transaction signing
API	Fastify, tRPC (internal), REST `/api/v1` (external)	Transaction building, route management
Scheduler	Node.js cron	Monitors pending steps and hops, submits keeper transactions
Indexer	Custom ETL	On-chain event indexing for real-time route status tracking
Database	PostgreSQL, Drizzle ORM	Route state, user data, execution history

Monorepo Structure

The codebase is organized as a Turborepo monorepo:

multihopper/
├── apps/
│   ├── web/          # React frontend
│   └── api/          # Fastify API server
├── libs/
│   ├── server/       # tRPC routers and server logic
│   └── shared/       # Shared types and utilities

The Anchor programs live in a separate multihopper-contracts repository.

Full Tech Stack

Layer	Technologies
Smart Contracts	Anchor, Rust, Token2022 (spl-token-2022)
Frontend	React 18/19, Vite, TanStack Router, Solana Wallet Adapter
Backend	Fastify, tRPC, Drizzle ORM, PostgreSQL
Infrastructure	Turborepo, TypeScript, Docker

Architectural Principles

Distribution and execution are intentionally separated. The abstraction layer handles asset routing and intermediate wallet coordination. The hop execution engine handles sequenced transfers. This separation allows each layer to evolve independently and makes the security boundary cleaner. Permissionless execution. No single entity controls whether a route executes. Any keeper can trigger orchestrator steps or hop executions — the program validates correctness, not identity. Off-chain indexing, on-chain authority. The indexer and API provide a convenient read layer, but they hold no authority over funds. All state that matters for settlement is on-chain. Provider extensibility. Integrators can register as providers via register_provider, attach a provider_id to routes, and configure per-provider fee tiers via initialize_fee_schedule / update_fee_schedule.

Getting started

Protocol

Concepts

Guides

System Overview

Smart Contracts

MultiHopper Core

Orchestrator

Transfer Hook Guard

Key On-Chain Accounts

MultiHopper Core

Orchestrator

Application Layer

Monorepo Structure

Full Tech Stack

Architectural Principles

​System Overview

​Smart Contracts

MultiHopper Core

Orchestrator

Transfer Hook Guard

​Key On-Chain Accounts

​MultiHopper Core

​Orchestrator

​Application Layer

​Monorepo Structure

​Full Tech Stack

​Architectural Principles

System Overview

Smart Contracts

Key On-Chain Accounts

MultiHopper Core

Orchestrator

Application Layer

Monorepo Structure

Full Tech Stack

Architectural Principles