τέλος — the intended end. You declare the outcome; the protocol resolves the path.
Telos is an intent-based atomic aggregator connecting Tempo (settlement-specialized Reth chain) and Hyperliquid (CLOB-native L1). A merchant or user submits a single intent — "settle this payment in USD-equivalent value" — and Telos routes the execution across both venues, hedging price risk in the settlement window.
This is a research project, not yet a product. It is also the practical companion to psyto/rethlab: RethLab teaches the Rust EVM stack from source; Telos puts it into production.
A running list of concepts internalized while building Telos lives in LEARNING.md, organized by topic with pointers back to the commits that introduced them.
Existing aggregators (1inch, Jupiter, CowSwap, Paraswap) route swaps between liquidity sources. None of them protect a merchant from price drift between user pays and merchant settles.
Telos does. The settlement gateway:
- Receives a
PaymentIntenton Tempo (via the MPP standard — Multi-Party Payments). - Hits the Hyperliquid CLOB for spot execution at the best available price.
- Opens a perp hedge on Hyperliquid sized to the settlement window.
- Closes the hedge atomically on outbound settlement to the merchant.
The perp leg is the same delta-neutral logic Fabrknt's Kodiak vault uses for yield, repurposed here as merchant FX protection.
┌─────────────┐ PaymentIntent ┌──────────────┐
│ Payer │ ────────────────────▶ │ Tempo (L1) │
└─────────────┘ │ Reth-based │
└──────┬───────┘
│ event
▼
┌────────────────────────┐
│ Telos Solver (Rust) │
│ ─ Alloy listener │
│ ─ REVM simulator │
│ ─ Reth precompile │
└────────┬───────────────┘
│ spot + perp
▼
┌────────────────────────┐
│ Hyperliquid CLOB + │
│ Perp Order Book │
└────────┬───────────────┘
│ settle
▼
┌────────────────────────┐
│ Merchant │
└────────────────────────┘
| Layer | Responsibility | Tech |
|---|---|---|
| Listener | Sub-100ms event capture from Tempo & Hyperliquid | Alloy (typed providers, sol! bindings) |
| Settler | Pre-flight simulation — does this route fill within slippage budget? | REVM (forked-state execution) |
| Precompile | On-chain custom opcode for atomic settle+hedge accounting | Reth (execution extension API) |
Telos is structured to exercise the modern Rust+Ethereum stack one layer at a time. RethLab provides the source-level theory; Telos is where it ships.
| Phase | Tech focus | Deliverable |
|---|---|---|
| Week 1–2 | Alloy — typed providers, sol! macro, event subscriptions |
telos-listener connects to Tempo & HL, prints incoming events |
| Week 3–4 | REVM — forking, inspectors, gas accounting | telos-settler simulates swap+hedge against forked Tempo state |
| Week 5–8 | Reth — execution extensions, custom precompiles | On-chain precompile for atomic settle accounting |
| Week 9+ | Adversarial work — MEV resistance, oracle deviation circuit breakers, ZK private intents | Audit-ready spec |
Only after the off-chain pain is felt do we move logic on-chain. This is deliberate.
telos/
├── crates/
│ ├── telos-types/ # shared types: Intent, RouteQuote, etc.
│ ├── telos-listener/ # Alloy-based event listener (Week 1–2)
│ ├── telos-settler/ # REVM simulation + decision gating (Weeks 3–6, 12)
│ ├── telos-submitter/ # signed broadcast + confirmation (Weeks 7–8)
│ ├── telos-store/ # sqlx + sqlite event log per intent (Week 9)
│ ├── telos-precompile/ # custom EVM precompile: intent_digest (Weeks 10–11)
│ ├── telos-node/ # jsonrpsee server exposing the custom EVM (Week 13)
│ └── telos-cli/ # binary entry point
└── Cargo.toml # workspace
Concept stage. As of 2026-05-03:
Listener handles four modes — headers (default), typed PaymentIntent on a Tempo contract, typed Fill on a Hyperliquid HyperEVM contract, or both multiplexed via tokio::select!. Configure via env vars: TELOS_TEMPO_WS_URL + TELOS_TEMPO_CONTRACT, TELOS_HL_WS_URL + TELOS_HL_CONTRACT.
Settler runs each decoded intent through REVM in two sequential legs against the same EVM context — REVM's transact accumulates state, so the hedge tx sees the post-state of the spot tx.
- Spot leg:
IERC20.transfer(merchant, amount)against the settlement asset. - Hedge leg (only when
TELOS_HL_GATEWAYis set):IHyperliquidGateway.placeShort(asset, size, maxSlippageBps)against the configured HL builder/bridge address.
Both modes — empty in-memory state (simulate_settlement) and forked from a live RPC (simulate_settlement_forked, async, dispatched via spawn_blocking to bridge async Alloy ↔ sync REVM) — walk the same two-leg path. Outcomes carry per-leg success, gas, decoded revert reason, plus an atomic_success flag that is the AND of both legs.
Feedback loop: a shared PriceBook is updated by every HL Fill and read by every decoded intent. quote_route(intent, &prices, hedge_venue) returns a RouteQuote with spot amount and a 1:1 hedge size at the current mark — the placeholder that funding-tilt logic will replace.
Decision gate: should_submit(outcome, route, intent, cfg) returns Submit(SubmissionPlan) or Reject(reason) — rejecting on no quote, spot or hedge revert, or stale price (max_price_age_secs defaults to 30).
Submitter (Weeks 7–8): when approved, the hedge tx is handed to a Submitter backed by an Alloy wallet-aware provider. Dry-run by default: estimates gas and logs the intended broadcast. Set TELOS_BROADCAST=1 and provide TELOS_SIGNER_KEY + TELOS_SUBMIT_RPC_URL to actually broadcast. Telos signs only the hedge — the spot leg is the merchant's settlement, observed for gating but not broadcast by us.
After broadcast, submit_and_confirm awaits the receipt under a ConfirmConfig { confirmations, timeout } budget and decodes any emitted OrderPlaced event from the receipt logs. Returns a typed SettlementResult: DryRun, Confirmed { tx_hash, block_number, gas_used, hedge_acked }, Failed { ... } (mined but reverted), or Timeout { waited_secs }.
Persistence (Week 9): set TELOS_DB_URL=sqlite://./telos.db to enable the telos-store event log. Every intent's lifecycle — observed → quoted → simulated → decided → settled — is appended as JSON-payload rows in a single intent_events table. On startup the CLI reports how many intents were observed but never settled in a previous run (the reconciliation set). Store writes are best-effort; a sqlite hiccup is logged but never poisons the in-memory pipeline.
Custom precompile (Weeks 10–12): telos-precompile exposes intent_digest, an Eth-style precompile at 0x…0901 that hashes the canonical intent fields and returns a 32-byte digest. TelosPrecompiles wraps the standard EthPrecompiles and intercepts that one address — implementing PrecompileProvider. The settler now uses Evm::new(...) + TelosPrecompiles in both empty-state and forked simulations, so any tx in any simulation can call the precompile. The leg-walking inner loop is generic over impl ExecuteEvm, so swapping the precompile provider doesn't ripple through the call sites.
Node façade (Week 13): telos-node is a small jsonrpsee server that exposes eth_call against a fresh REVM with TelosPrecompiles. Anyone can hit it from cast, alloy, or any standard JSON-RPC client and call into address 0x…0901 to get the canonical digest back. Stateless on purpose — each call builds an ephemeral EVM over EmptyDB. A real Reth integration would plug TelosPrecompiles into reth_evm::ConfigureEvm so the same precompile rides the node's normal pipeline; the pattern is the same, the plumbing is much heavier and is the deliberate next step.
TELOS_NODE_BIND=127.0.0.1:8545 cargo run -p telos-nodeThis repository is private during the learning phase. It will open if and when the architecture stabilizes.
τέλος is the Greek for purpose, end, completion — the word Aristotle used for the goal toward which a thing tends. Every other word in the aggregator vocabulary describes mechanism: route, swap, settle, hedge. Telos describes the user's relationship to the system. They state the end. The protocol owns the means.
MIT — see LICENSE.