Blackhole Diamond — Onchain Executor

Blackhole Diamond is the on-chain component that guarantees deterministic execution. It receives a signed execution packet containing a primary route plus one or more fallback routes.

If the primary route fails — due to slippage, bridge downtime, or contract reverts — Blackhole Diamond automatically activates a fallback route, without requiring new signatures or user intervention.

Runtime Execution Flow

1. Signature Verification

• Verifies the integrity of the execution packet with ECDSA.recover.

2. Primary Route Execution

• Executes the primary calldata through internal call or delegate pattern.

• Enforces runtime constraints: slippage, minOut, deadlines, gas limits.

3. Failure Detection

• If constraints are violated or execution reverts, the system does not halt.

• SafeSwitch logic moves execution to the first fallback route.

4. Fallback Activation

• Validates the next route’s constraints.

• Executes fallback calldata.

• Iterates until success or exhaustion of options.

5. Graceful Exit

• If no route succeeds, Diamond reverts the transaction.

• Assets are never retained — full non-custodial guarantee.

Security Properties

• One signature, multiple routes Users sign a deterministic bundle of primary + fallback paths. No external resigning required.

• Strict scope enforcement Only pre-signed routes can be executed. No injected logic is possible.

• Non-custodial by design The contract never holds user funds beyond the scope of the transaction.

• Fallback isolation Each fallback executes independently, preventing state contamination.

Benefits

• Resilience to bridge/pool failures and volatile conditions.

• Safer UX: one signature covers multiple recovery paths.

• Eliminates the “stuck funds” problem common in aggregators and bridges.

• Enables confidence in cross-chain execution, even under unstable liquidity.