Loopbox

Loopbox is a wallet-owned DeFi loop-strategy simulator and executor. Pick a preset (or configure a custom one), a risk level, and a loop depth — Loopbox scans the same strategy across Ethereum, Base, and Arbitrum, prices it with a venue-exact quant analysis on live on-chain data, and compiles it into a single batch your own wallet executes. Cross-chain funding is handled by a Particle Universal Account in EIP-7702 mode, so you never manually bridge or switch chains.

Note

This is a hackathon build for the Particle Universal Accounts / EIP-7702 track. Every script and the hosted app run against live mainnet data but never broadcast a real transaction — see Zero real funds below.

The guiding idea is "cross-chain intelligence, single-chain execution": the engine reasons across chains to pick the best destination, capital is routed there before any leverage exists, and once debt is open, everything — opening, re-looping, guarding, unwinding — stays on that one chain.

For the full technical breakdown (formulas, call sequences, the guard contract, every diagram), see docs/ARCHITECTURE.md, docs/simulation-and-quant.md, and docs/strategy-engine.md. This README stays brief on purpose.

How it works

flowchart LR
    A[Preset or custom strategy] --> B[Live quant analysis]
    B --> C[Compile to calls]
    C --> D[Sanitize + guard]
    D --> E[Particle UA preview\nEIP-7702 batch]
    E -.zero funds.-> F[Your wallet signs]

Loading

1. Analyze — a venue-exact simulation prices the loop using each protocol's own rate model at your size (post-trade, not spot), producing seven headline numbers: net APY, leverage, liquidation buffer, worst-stress health factor, borrow-rate headroom, round-trip cost, and debt as a share of market liquidity.
2. Compile — the report becomes an ordered list of calls (supply, borrow, swap, repeat) for the exact venue (Morpho Blue or Aave v3). Every call is immediately re-decoded and re-checked by its own protocol adapter — a mismatch is treated as a bug, not a warning.
3. Preview & execute — the compiled batch is quoted through a Particle Universal Account. In EIP-7702 mode, your existing address temporarily gains smart-account behavior, so the whole multi-step position opens (or unwinds) as one atomic transaction your own EOA signs — no vault, no proxy, no new address owning your funds.

Particle Universal Accounts & EIP-7702

EIP-7702 lets an EOA delegate execution to smart-account code for a single transaction, without changing its address. Particle Universal Accounts build on that: one account with a unified balance across chains, chain-agnostic funding, gas abstraction, and transaction previews. In 7702 mode the Universal Account address is the owner EOA — the position always belongs to you, never to an application contract.

This is what makes "cross-chain intelligence, single-chain execution" possible: Particle sources capital from wherever it sits and routes it to the destination chain before the loop opens; after that, the invariant is no bridge after debt is opened — the remaining risk is routing/rate risk, never cross-chain liquidation risk.

LoopboxGuard

A stateless, fund-free Solidity contract (contracts/) appended as the final call in the atomic batch. It re-reads live venue health (Aave healthFactor, or Morpho's reconstructed LTV) inside the transaction and reverts the whole open if the post-state is unsafe — proven by unit tests and a Base fork test, though not yet deployed on mainnet (see docs/ARCHITECTURE.md for the current status).

Zero real funds

Every script and the hosted app run against live mainnet data, but nothing is ever broadcast. Execution is proven two ways instead:

• Particle previews — real, signature-less quotes against the live UA backend.
• Anvil forks — the compiled batch actually executes against forked mainnet state, including the guard and the full unwind.

Sending is gated behind LOOPBOX_ENABLE_SEND, which nothing in this repo ever sets.

Project layout

Path	What's there
src/	Config registries, protocol adapters (Morpho, Aave, Uniswap, Lido, Pendle, ERC20), the strategy engine (analyze/compile), and the Particle/Privy account layer
contracts/	LoopboxGuard.sol and its Foundry test suite
scripts/	Four CONFIG-driven demo scripts (below) — no CLI args, edit the constants at the top of each file
ui/	The hosted Next.js app — wallet connect, strategy builder, scanner, and an architecture showcase
docs/	The technical deep dives referenced throughout this file
test/	Unit tests, including golden-value checks against independently computed figures

Scripts

Every layer is exercised by a runnable script before touching the UI. Each opens with an editable CONFIG (or SPEC) constant — no CLI arguments, the CONFIG block is the runbook.

pnpm preset   # preset strategies end to end — catalog, analysis, compiled calls,
              # Particle preview, Anvil fork execution, live position, unwind
pnpm custom   # the same journey driven by a typed custom spec instead of a preset id
pnpm scan     # ranks every preset live across chains, recommends a destination,
              # can hand the winner straight to fork execution
pnpm proof    # generates the structured fork-execution receipt the hosted UI renders

pnpm preset — catalog + live analysis

Ten verified presets, then a full pre-execution analysis: post-trade rates, loop-by-loop detail, stress scenarios, and costs — all from live mainnet reads.

pnpm custom — resolve, analyze, compile

A custom strategy resolves through the same allowlists as a preset, gets analyzed and constraint-checked, then compiles into the identical ordered, sanitizer-checked call list — entry and unwind.

pnpm scan — cross-chain ranking

Scans every preset live, ranks by net APY net of round-trip cost, and recommends a destination chain per collateral/debt pair — typed rejections (like an SY mint-capacity cap) are shown honestly, not hidden.

pnpm proof — Anvil fork execution

The compiled batch actually executes against forked mainnet state: funding lands, the position opens, the guard passes on a healthy state and reverts on an unsafe one, and the full de-loop unwind recovers ~99.96% of equity.

Getting started

pnpm install
cp .env.example .env   # fill in RPC URLs + Particle/Privy credentials
pnpm typecheck && pnpm test
pnpm preset             # edit CONFIG in scripts/preset.ts first

For the hosted app:

cd ui
pnpm install
cp .env.example .env.local
pnpm dev

Important

The ui/ app needs its own env file — Next.js only reads .env* from its own project directory, never the repo root.