docs

✿ how you make money

❀ where the "extra" comes from

A passive cross-chain LP has to pick allocations upfront — say 50/50 — and live with it. If Base has 80% of the trading volume that week, a passive LP loses ~30% of potential fees because too much capital sits idle on the wrong chain.

mirv's agent swarm rebalances every 45 seconds. If Base's pool is paying more fees per dollar of liquidity, USDC shifts from Ethereum to Base via Circle CCTP. Your LP is always concentrated where the volume is.

✦ what happens when you deposit

1. 1. You approve USDC to the vault, then call deposit on Base.
2. 2. The vault mints you mirvUSDC shares. Initially 1 share = 1 USDC.
3. 3. The vault splits your USDC by the chain registry. Today: 60% stays on Base, 40% gets bridged to Ethereum via Circle's CCTP burn-and-mint.
4. 4. Within ~20 minutes, the bridged USDC arrives on Ethereum and lands at the Relayer contract.
5. 5. The agent reports the cross-chain balance, so the vault's totalAssets reflects the full amount.
6. 6. The agent (or a triggered hook callback) adds the USDC as LP into each chain's V4 pool, paired with WETH.

Between steps 3 and 5 your share price will briefly look lower than $1 because the cross-chain portion isn't yet accounted for. This settles within one agent cycle (~45s) once the agent reports.

✿ how you withdraw

✦ the agent swarm

Four agents, all powered by Claude, cooperate to decide when and how to rebalance. They run on a 45-second cycle.

❀ what bounds the swarm

The agents are LLMs and could be wrong. The protocol assumes they will be wrong sometimes and bounds the damage in code:

• No move can shift more than 25% of total assets in a single cycle. Even a compromised agent can't drain the vault.
• Two independent price feeds (Pyth + Chainlink) must agree within 5% before anything moves.
• Depth updates from the other chain are capped at 10× any prior reading. Stops impossible-looking spikes from triggering bad moves.
• There's a 60-second cooldown between rebalances. The agents can't fire-hose dispatches.
• Treasury changes are delayed 24 hours. If the owner changes where fees go, you have a full day to leave first.
• Cross-chain reports older than 1 hour are rejected. If the agent goes silent, the vault won't act on stale data.
• You can always start a withdrawal. No admin override on the user exit path.

Internal test suite is at 135 passing tests. Slither, Mythril and Foundry fork-tests have been run against the rc6 bytecode. Not yet externally audited — mainnet is gated on that.

❀ what has to be true for this to actually be useful

We're being honest here, because Uniswap and other smart people will ask. mirv's pools are permissionless — anyone with USDC + WETH can add LP to them. But on day one, nobody will, because there's no incentive to use our pool over the canonical Uniswap one if they're shallower.

That means today the swarm is mostly managing the vault's own positions across two chains. It's a real protocol with real cross-chain mechanics — but to earn fees for depositors, our pools need external swap volume, and that requires:

• Seed depth at mainnet launch — treasury seeds $500k–$1M per chain so routers consider us competitive.
• Router + aggregator integration — Uniswap Universal Router, 1inch, Matcha need to know our pool exists and route through it. We're working toward this.
• The hook's cross-chain primitive being adopted — our actual edge is that routers can read cross-chain depth from a single contract call. That's what makes mirv ≠ "just another LP."
• Smarter agents — the swarm needs to also monitor canonical pools (not just our own) to detect when our pool is non-competitive and adjust.

The contracts are validated end-to-end. The mechanism works. The go-to-market — getting volume to flow through — is the next phase. See the README's "Pre-mainnet must-haves" section for the work plan.

✿ the V4 hook (for technical readers)

mirv's interesting trick is that depth isn't a per-chain phenomenon anymore. The MirrorHook exposes a cross-chain depth primitive that any contract on either chain can read, packaged behind a single quoter interface:

// IMirrorHookQuoter — the "menu" routers + aggregators call
function quoteCrossChainPool(bytes32 poolId)
  external view returns (CrossChainQuote memory);

struct CrossChainQuote {
  uint256  localDepthUsd;
  uint256  sisterChainsCount;
  uint256[] sisterDepthsUsd;
  uint32[]  sisterDomainIds;
  uint256  totalCrossChainDepthUsd;
  uint256  crossChainAdvantageBps;  // local vs best sister
  bool     reliable;
}

One call, one struct, the entire cross-chain depth picture. No off-chain indexer required. ~10k gas at 0 sisters, ~12k with one. Suitable for inclusion in a V4 quoter's hot path.

A reference router-side caller ships at examples/ExampleRouterIntegration.sol in the repo with two patterns: shouldRouteThroughMirv() (yes/no for a given swap size) andfindDeepestChain() (best sister to route through).

V4 pool identity is (currency0, currency1, fee, tickSpacing, hooks) — attaching a different hook means it's a different pool. So mirv runs its own USDC/WETH pool on each chain, separate from the canonical Uniswap pool. We don't compete with that pool; we add a hook-coordinated lane next to it.

✦ contract addresses

rc6 candidate, live on testnet. all verified on the explorers.

❀ frequent questions