sovereign-flash-sdk

The cheapest multi-hop flash loan routing layer on Arbitrum. Period.

What This Does

Aave V3 charges 0.05% on every flash loan. Balancer charges 0% but has limited liquidity depth.

This SDK routes your flash loans through the Sovereign Omni-Aggregator, which automatically splits your token basket across both protocols to minimize your total cost. You pay a 0.01% gateway fee instead of Aave's 0.05%.

Deployed on Arbitrum Mainnet: 0x64dFe266E88c5c44883711F424Ed374b3D677F5D

Installation

npm install sovereign-flash-sdk ethers

Quick Start

import { ethers } from "ethers";
import { SovereignFlashClient } from "sovereign-flash-sdk";

const provider = new ethers.JsonRpcProvider("https://arb1.arbitrum.io/rpc");
const wallet = new ethers.Wallet(YOUR_PRIVATE_KEY, provider);

const client = new SovereignFlashClient(wallet);

// Borrow 1M USDC + 10 WETH in a single atomic transaction
const tx = await client.requestFlashBasket(
  [
    "0xaf88d065e77c8cC2239327C5EDb3A432268e5831", // USDC
    "0x82aF49447D8a07e3bd95BD0d56f35241523fBab1"  // WETH
  ],
  [
    ethers.parseUnits("1000000", 6), // 1M USDC
    ethers.parseEther("10")          // 10 WETH
  ],
  "0x" // Your encoded execution data
);

await tx.wait();

Failure Surface & Callback Engineering

To intercept the payload, your MEV bot must explicitly implement ISovereignReceiver. The aggregator dynamically arrays the final premiums locally.

Exact Callback Interface:

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.20;

interface ISovereignReceiver {
    // Expected return: MUST return `true`
    // Expected execution: Must grant Approval / Transfer of (amounts + premiums) to the Gateway address.
    function executeOperation(
        address[] calldata tokens,
        uint256[] calldata amounts,
        uint256[] calldata premiums,
        bytes calldata data
    ) external returns (bool);
}

Advanced Error Handling (EVM Custom Errors)

Sovereign avoids string reverts completely to save gas. You will need to trace these exact custom errors if your execution fails:

• SovereignUnderfill(): Balancer lacked enough liquidity and the Aave V3 fallback failed to procure the deficit.
• CallbackFailed(): Your receiver contract did not return boolean true.
• Shortfall(uint256 deficit): Your arbitrage sequence failed to approve/transfer the exact amounts + premiums back to the Gateway before the callback resolved.

Break-Even Gas Analysis (Cost-Benefit)

Sovereign uses nested flash calls (Balancer ➔ Aave). This costs approximately 185,000 gas. At standard Arbitrum congestion, this adds roughly ~$0.15 of fixed overhead to your EVM transaction compared to calling Aave directly.

| Flash Loan Size | Direct Aave (0.05%) | Sovereign (0.01% + $0.15 Gas) | Result | |-----------------|---------------------|-------------------------------|--------| | $100 | $0.05 | ~$0.16 | You Lose | | $350 | $0.17 | ~$0.18 | Break-Even Line | | $10,000 | $5.00 | $1.15 | Sovereign Saves 77% | | $1,000,000 | $500.00 | $100.15 | Sovereign Saves 80% |

Note: If traversing routes purely through Balancer (bypassing Aave entirely), gas overhead drops significantly.

Architecture

1. Checks Balancer Vault state getPoolTokens() capacity bounds.
2. Routes available tokens through Balancer (0% limit execution).
3. Remaining tokens route through Aave V3 (0.05% fee).
4. Merges both fractional payloads into a strict executeOperation to your bot.
5. Collects 0.01% overall gateway footprint.

All of this happens in a single atomic transaction within one block.

License

MIT — Island Dreamers Inc.