Routing & Execution Architecture

Introduction

Blackhole is a modular execution layer that securely connects dApps to global on-chain liquidity through a single API/SDK.

It unifies bridges, DEXes, and aggregators across EVM chains, Solana, Sui, and L2 networks, while providing pre-signature validation and deterministic on-chain execution with built-in fallback and safe unwind.

---

1. Intent from dApp

The dApp (wallet, protocol, or aggregator) creates an intent describing the desired action — for example, swapping a token and bridging the result to another network.

This intent is sent to the Blackhole API/SDK using validateRoute(intent).

---

2. Route Construction — Blackhole Router (off-chain)

The Blackhole Router:

1. Collects quotes and builds possible routes from all supported DEXes, bridges, and other liquidity sources,

2. Combines same-chain and cross-chain steps when needed,

3. Prepares a set of candidate routes (primary and fallback).

---

3. Pre-Signature Validation — Umbra + Echo (off-chain)

The candidate routes are then fully validated:

1. Full-path simulation: every step is tested off-chain to detect failures in advance.

2. Static analysis: checks function selectors, proxy/upgrade patterns, fee limits, and potential vulnerabilities.

3. Reputation filtering: evaluates bridges and protocols based on audit history, exploits, and live operational data.

4. Guardrails: applies strict per-leg constraints such as minOut, deadlines, fee caps, and allowlists.

The output is a ready-to-execute Execution Packet that contains the approved primary route, fallback paths, and all required safety conditions.

---

4. Packet Return & User Signature

This validated Execution Packet is returned to the dApp. The dApp presents it to the user and requests a single final signature. By the time of signing, all routes and safety checks are already fixed and verified.

---

5. Deterministic On-Chain Execution — Blackhole Diamond

After signing, the Execution Packet is sent to Blackhole Diamond, the on-chain state-machine executor.

1. Executes each step strictly according to the packet’s constraints.

2. If a condition fails (e.g., bridge paused, minOut breach, missed deadline), it automatically switches to the defined fallback route or performs a safe unwind, ensuring no asset loss.

3. Emits detailed execution events for monitoring and analytics.

---

6. Telemetry & Feedback

All execution data and runtime events are streamed back to the off-chain system to update models, improve routing, and refine future validation.

---

End-to-End Flow

1. dApp → SDK: submits intent.

2. Router: aggregates quotes and constructs primary and fallback routes.

3. Umbra + Echo: fully validate routes and produce a ready Execution Packet.

4. User: signs the validated packet.

5. Diamond: executes deterministically with automatic fallback or safe unwind if needed.

6. Telemetry: sends execution logs back for continuous learning and analytics.

---

Key Takeaway

Blackhole turns complex cross-chain engineering into one predictable cycle: intent → validated execution packet → guaranteed on-chain execution.

The dApp receives a route that will either be completed exactly as defined or safely rolled back, removing the need for custom routing and error-handling code.