Skip to main content

Documentation Index

Fetch the complete documentation index at: https://dev-docs.multihopper.com/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

MultiHopper enables scheduled, sequenced token transfers on Solana. The key insight is separating custody from routing: original tokens stay locked in a program-controlled vault while wrapper tokens flow through the route. Two on-chain programs implement the protocol:
  • MultiHopper Core (7ukX5xXys5nekSfvWxqfCJpjJxF9ymvJz9v9wSCR6fke) — handles route creation, hop execution, wrap/unwrap operations, provider registration, and fee management.
  • Orchestrator (4TPCmR2uN3hDM1FbTsf7ZtFXwXGSz4u1Kxv5YHj6eruX) — a permissionless execution engine that coordinates the deployment transaction sequence for a route through discrete, keeper-executable steps.

​
Core Mechanism: Wrapper Tokens

MultiHopper uses Solana’s Token2022 extensions to create route-specific wrapper tokens.
1

Deposit into vault

A user deposits original tokens (SOL or SPL) into an on-chain vault controlled by the protocol program.
2

Mint wrapper tokens

The protocol mints an equivalent amount of wrapper tokens using a Token2022 mint with the permanent delegate extension enabled. Wrapper tokens are backed 1:1 by the vault.
3

Execute hops

The permanent delegate allows the protocol to programmatically transfer wrapper tokens between hop recipients at scheduled times — without requiring recipient signatures at each step.
4

Redeem

After the route completes, the final recipient burns their wrapper tokens to redeem the original tokens from the vault.
Original tokens never leave the vault until final redemption. The wrapper token mechanism ensures 1:1 backing throughout the entire route lifecycle.

​
Token2022 Extensions Used

MultiHopper relies on three Token2022 extensions to implement its routing logic:
ExtensionRole
Permanent DelegateEnables programmatic token transfers without holder signatures — the protocol can move wrapper tokens on behalf of recipients
Metadata PointerAttaches route metadata (hop sequence, timing, recipients) directly to the wrapper mint on-chain
Transfer HookEnforces custom transfer compliance rules at the protocol level on every wrapper token movement

​
Orchestrator: Step-Based Deployment

The Orchestrator program coordinates the multi-transaction sequence required to deploy a route. Instead of requiring the user to sign every setup transaction themselves, the orchestrator breaks deployment into discrete steps that permissionless keepers can execute. Each step has a type:
Step TypeDescription
transferTransfer SOL or lamports between accounts (e.g. fund a hop wallet)
wrap_solWrap SOL into the route’s vault via wrap_sol on the Core program
wrap_tokenWrap an SPL token into the route’s vault
When a route is deployed through the orchestrator:
  1. An OrchestratorConfig account is created with the full step sequence and a keeper_share_bps incentive.
  2. Individual OrchestratorStep accounts are initialized, each with an execute_at timestamp.
  3. Any keeper can execute each step once its scheduled time arrives — earning a share of the deposited funds.
  4. After all steps complete, the orchestrator is closed and rent reclaimed.

​
On-Chain Enforcement

Every constraint in a route is enforced by the smart contract — there is no trusted off-chain component with authority over funds.
Each hop and orchestrator step has an execute_at timestamp validated against the Solana clock. A hop or step cannot execute before its scheduled time — the transaction will fail at the contract level.
Hops execute in strict order. Hop N must complete before hop N+1 can be triggered. This is enforced by on-chain state tracking within the route account.
The prepaid_hops field on each route enforces how many hops have been fee-paid. The program rejects execution beyond the prepaid limit.
Protocol fees are collected upfront at route creation. Provider integrators can attach a provider_id and optional reference_id to routes, with per-provider fee schedules managed via the FeeSchedule account.

​
Token Support

The wrapper mechanism normalizes all Solana token types into a consistent routing interface:
  • Native SOL (via dedicated initialize_route_sol / wrap_sol / unwrap_sol instructions)
  • Standard SPL tokens
  • Token2022 tokens
SOL routes use a dedicated sol_vault PDA rather than a token account, with mint_wsol_tickets used to issue wrapper tokens representing locked SOL.

​
What Happens If a Keeper Fails?

If a keeper fails to execute a step or hop at the scheduled time, the step stays pending and any other executor can trigger it. The protocol does not rely on a single keeper — execution is permissionless. If a step fails on-chain, the refund_failed_step instruction on the Orchestrator returns deposited funds to the creator. The rescue_step instruction provides an admin escape hatch for stuck steps.

Learn about Keepers

Understand how the keeper network provides permissionless, decentralized execution.