𓆰 flashgod 𓆪

$22B in crypto across 7 transactions as-a-service
(as of crypto prices on 6:30 am UTC, 29th Nov 2024).

Wait wut?! 🤯

flashgod is a 🪶 weight flash-loan aggregator on all EVM compatible chains (with size), that provides unbridled access to all available assets of all flash-loan providers on 7 different chains, in 1 transaction per chain, on a clean and easy-to-use interface,

featuring flash-loan providers: Aave V3, Uniswap V3, Balancer V2,

on chains: Ethereum, Arbitrum, Optimism, Polygon, Base, Avalanche, BSC.

Table of Contents 📑

1. The Power in thy Hands
2. How?
3. Purpose
4. Scoop for Devs
5. Project Structure
6. Usage
7. Future Work / Improvements
8. Credits
9. Legal

The Power in thy Hands ⚜️

Amounts fetched for all major assets.
1 row => 1 txn.
(as of 29th Nov 2024)

How? 💡

• Nothing new, but connecting existing dots. Simply a chain of callbacks initiating flashloans from one provider to the next.

• Things get particularly interesting for Uniswap V3, where flashloans have to be borrowed from multiple pools in a single transaction, in a gas-efficient manner.

• flashgod does so by recursively calling its uniV3 flashloan initiator function from its callback, with clever use of transient storage for persistent pool data through these calls, to keep things light:
  
  

  

Purpose 🎯

Provide a simpler, light-weight, easy-to-use interface to access much larger flashloans, for

• developers: to test their protocols with real size of attacks that can hit their contracts
• security-researchers: identify, assess, measure and write POCs for real damage that flashloan-focused attack vectors can cause
• market-makers: to perform arbitrages, liquidations, loan-refinancing, etc.

Important: This software is intended for legitimate business and research purposes only. Any use for malicious activities including but not limited to attacks on live protocols or theft of assets is strictly prohibited. Users must comply with all applicable laws, regulations, and ethical standards. See LICENSE.md for more details.

Scoop for Devs 🍨

Cool tricks were possible when transient storage's 1-transaction persistence yin, met flashgod's 1-transaction flashloan yang:

• statelessness: extensive use of transient storage allowed
  • 0 state variables (except the ones inherited which can be removed too)
  • upto 200x cheaper reads and writes across the transaction (max SSTORE = 20k gas against max TSTORE = 100 gas)
  • persistent metadata of providers and flashloaned assets, necessary for the recursive flashloan calls
• yulism: using yul wherever sensibly possible to reduce gas significantly, most notably for decoding bytes array of pool data of all UniV3 pools and storing them in transient storage, in a way that allows for simple and quick access
• iterable-set: the key-value nature of transient storage allows for implementing an Iterable-Set data structure using two mappings, 1 to allow adding unique assets in O(1) time, and the other to iterate over these assets through insertion order in O(n) time. This came handy in storing overlapping assets from multiple flashloan providers, uniquely.

Project Structure { }

src/

• Tremor.sol - Core contract implementing aggregated flash loans across Aave, Balancer, and Uniswap V3
• config/Addresses.sol - Configuration file containing protocol addresses for supported chains

test/

• Tremor.t.sol - Integration tests for flash loan functionality across different chains
• invariants/
  • Tremor.invariants.t.sol - Invariant tests ensuring core safety properties
  • handlers/Handler.sol - Test handlers for fuzzing flash loan interactions

foundry.toml

• Foundry configuration file with EVM settings and test parameters

Usage 💻

1. Run locally:
   • git clone [email protected]:smitrajput/flashgod.git && cd flashgod
   • cp .env.example .env, then add your RPC URLs in the .env file
   • install foundry (follow this section)
   • forge install
   • forge test --via-ir, should show:
2. Update this list of addresses with ones you want to flashloan
3. Time to test. Update corresponding assets and amounts in the test functions of the chains you want to flashloan from. For instance, to flashloan from Ethereum, update the test_dominoeFlashLoans_ethereum() function:
   • here to update aave assets
   • here to specify amounts for aave
   • here to update balancer assets
   • here to specify amounts for balancer
   • here to update uniV3 pools
   • here to specify amounts for uniV3
4. Finally, add the logic you want to execute using the aggregated flashloans to _letsPutASmileOnThatFace()
5. Run forge test -vv --via-ir --match-test "test_dominoeFlashLoans_ethereum()", for some fireworks:

Future Work / Improvements 🔮

• the 7 txns becoming 1 should be a richter scale 9.0, beginning the era of cross-chain flashloans. Interesting experiments might be possible using Polymer today, until we figure out atomic interop.
• support for other EVM and altEVM chains could be added
• support for more flashloan providers (dYdX?) if any, could be added
• the 2 inherited immutable variables in Tremor.sol from PeripheryPayments and PeripheryImmutableState can be removed and a minimal WETH deposit/withdraw, token transfer logic can be added to further reduce gas
• Tremor.sol can be converted to an abstract contract, making _letsPutASmileOnThatFace() a virtual function, which can be overriden by developers' derived contracts to add their fund-usage logic
• Tremor.sol could be deployed on all 7 chains as a diamond proxy contract, with 1 facet open for developers to upgrade, write their fund-usage logic, use it, and destroy it in the same txn. Call them ephemeral contracts. Do bear in mind the legal risks of deploying such a contract.

Credits 📚

Opening GIF: A.L.Crego

Legal 📄

LICENSE.md