🚀 Octopus Release

.env-example

@@ -1,10 +1,7 @@
-MAINNET_RPC_URL=https://eth-mainnet.g.alchemy.com/v2/KEY
-OPTIMISM_RPC_URL=https://opt-mainnet.g.alchemy.com/v2/KEY
-BASE_RPC_URL=https://base-mainnet.g.alchemy.com/v2/KEY
-GOERLI_RPC_URL=https://eth-goerli.g.alchemy.com/v2/KEY
-OPTIMISM_GOERLI_RPC_URL=https://opt-goerli.g.alchemy.com/v2/KEY
-BASE_GOERLI_RPC_URL=https://base-goerli.g.alchemy.com/v2/KEY
-PRIVATE_KEY=KEY
-ETHERSCAN_API_KEY=KEY
-OPTIMISM_ETHERSCAN_API_KEY=KEY
-BASESCAN_API_KEY=KEY
+BASE_RPC=https://base-mainnet.g.alchemy.com/v2/<KEY>
+ARBITRUM_RPC=https://arb-mainnet.g.alchemy.com/v2/<KEY>
+ARBITRUM_SEPOLIA_RPC=https://arb-sepolia.g.alchemy.com/v2/<KEY>
+BASESCAN_API_KEY=<KEY>
+ARBISCAN_API_KEY=<KEY>
+ARBISCAN_SEPOLIA_API_KEY=<KEY>
+PRIVATE_KEY=<KEY>

.gas-snapshot

@@ -1,22 +1,35 @@
-Deployment:test_hashed_susdc_name() (gas: 5568)
-Deployment:test_sUSDCId_invalid() (gas: 51853)
-Deployment:test_sUSDC_address() (gas: 5455)
-Deployment:test_spotMarketProxy_zero_address() (gas: 41709)
-Deployment:test_susd_zero_address() (gas: 41696)
-Deployment:test_usdc_decimals_factor() (gas: 5420)
-Deployment:test_usdc_zero_address() (gas: 41637)
-Deployment:test_zap_address() (gas: 2356)
-ZapIn:test_zap_in() (gas: 463863)
-ZapIn:test_zap_in_event() (gas: 461040)
-ZapIn:test_zap_in_exceeds_cap() (gas: 457276)
-ZapIn:test_zap_in_susdc_approve_fails() (gas: 301777)
-ZapIn:test_zap_in_usdc_approve_fails() (gas: 62939)
-ZapIn:test_zap_in_usdc_transfer_fails() (gas: 14044)
-ZapIn:test_zap_in_zero() (gas: 246817)
-ZapOut:test_zap_out() (gas: 465470)
-ZapOut:test_zap_out_event() (gas: 463923)
-ZapOut:test_zap_out_insufficient_amount() (gas: 55830)
-ZapOut:test_zap_out_precision_loss(uint256) (runs: 256, μ: 465998, ~: 465998)
-ZapOut:test_zap_out_susd_approve_fails() (gas: 18892)
-ZapOut:test_zap_out_susdc_approve_fails() (gas: 312592)
-ZapOut:test_zap_out_zero() (gas: 9086)
+AaveTest:test_executeOperation_only_aave(address,address,uint256,uint256,bytes) (runs: 256, μ: 4072994, ~: 4072993)
+BurnTest:test_burn_arbitrum_sepolia(uint32) (runs: 256, μ: 4021378, ~: 4021378)
+BuyTest:test_buy_arbitrum(uint32) (runs: 256, μ: 4712117, ~: 4712117)
+BuyTest:test_buy_base(uint32) (runs: 256, μ: 4631652, ~: 4631652)
+FlushTest:test_flush(uint32) (runs: 256, μ: 4021401, ~: 4021401)
+ReentrancyTest:test_requireStage(uint8) (runs: 256, μ: 17762, ~: 8622)
+ReentrancyTest:test_requireStage_throws(uint8,uint256) (runs: 256, μ: 18839, ~: 11503)
+ReentrancyTest:test_stage_default() (gas: 3027)
+ReentrancyTest:test_stage_enum_level1() (gas: 660)
+ReentrancyTest:test_stage_enum_level2() (gas: 706)
+ReentrancyTest:test_stage_enum_unset() (gas: 844)
+SellTest:test_sell_arbitrum(uint32) (runs: 256, μ: 4884336, ~: 4884336)
+SellTest:test_sell_base(uint32) (runs: 256, μ: 4785869, ~: 4785869)
+SwapForTest:test_swap_for_multihop_arbitrum() (gas: 4611852)
+SwapForTest:test_swap_for_multihop_base() (gas: 4614101)
+SwapForTest:test_swap_for_single_arbitrum(uint8) (runs: 256, μ: 4461856, ~: 4461856)
+SwapForTest:test_swap_for_single_arbitrum_sepolia() (gas: 4021185)
+SwapForTest:test_swap_for_single_base() (gas: 4435614)
+SwapWithTest:test_swap_with_arbitrum(uint8) (runs: 256, μ: 4434036, ~: 4434036)
+SwapWithTest:test_swap_with_arbitrum_sepolia() (gas: 4021231)
+SwapWithTest:test_swap_with_base(uint8) (runs: 256, μ: 4328655, ~: 4328655)
+UnwindTest:test_unwind_arbitrum_sepolia() (gas: 4021254)
+UnwindTest:test_unwind_is_authorized() (gas: 4091114)
+UnwrapTest:test_unwrap_arbitrum(uint32) (runs: 256, μ: 4948844, ~: 4948844)
+UnwrapTest:test_unwrap_base(uint32) (runs: 256, μ: 4840687, ~: 4840687)
+WithdrawTest:test_withdraw_arbitrum() (gas: 4996101)
+WithdrawTest:test_withdraw_base() (gas: 4819562)
+WithdrawTest:test_withdraw_is_authorized_arbitrum() (gas: 4089866)
+WithdrawTest:test_withdraw_is_authorized_base() (gas: 4089981)
+WrapTest:test_wrap_arbitrum(uint32) (runs: 256, μ: 4766711, ~: 4766711)
+WrapTest:test_wrap_base(uint32) (runs: 256, μ: 4676382, ~: 4676382)
+ZapInTest:test_zap_in_arbitrum(uint32) (runs: 256, μ: 4898567, ~: 4898567)
+ZapInTest:test_zap_in_base(uint32) (runs: 256, μ: 4795630, ~: 4795630)
+ZapOutTest:test_zap_out_arbitum(uint64) (runs: 256, μ: 4853363, ~: 4853363)
+ZapOutTest:test_zap_out_base(uint64) (runs: 256, μ: 4755166, ~: 4755166)

.github/workflows/lint.yml

@@ -1,25 +1,35 @@
 name: lint
 
-on: [push]
+on:
+  push:
+  pull_request:
+  workflow_dispatch:
 
 env:
-    FOUNDRY_PROFILE: ci
+  FOUNDRY_PROFILE: ci
 
 jobs:
-    check:
-        strategy:
-            fail-fast: true
+  check:
+    strategy:
+      fail-fast: true
 
-        runs-on: ubuntu-latest
-        steps:
-            - uses: actions/checkout@v3
-              with:
-                  submodules: recursive
+    name: Foundry project
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          submodules: recursive
 
-            - name: Install Foundry
-              uses: foundry-rs/foundry-toolchain@v1
-              with:
-                  version: nightly
+      - name: Install Foundry
+        uses: foundry-rs/foundry-toolchain@v1
+        with:
+          version: nightly
 
-            - name: Lint Check
-              run: forge fmt --check
+      - name: Show Forge version
+        run: |
+          forge --version
+
+      - name: Run Forge fmt
+        run: |
+          forge fmt --check
+        id: fmt

.gitignore

@@ -13,3 +13,4 @@ out/
 # Other
 .vscode
 .idea
+.DS-store

.gitmodules

@@ -1,3 +1,6 @@
 [submodule "lib/forge-std"]
 	path = lib/forge-std
 	url = https://github.com/foundry-rs/forge-std
+[submodule "lib/surl"]
+	path = lib/surl
+	url = https://github.com/memester-xyz/surl

README.md

@@ -1,7 +1,7 @@
-# Zap
+# Zap Flashloan Utility
 
-[![Github Actions][gha-badge]][gha] 
-[![Foundry][foundry-badge]][foundry] 
+[![Github Actions][gha-badge]][gha]
+[![Foundry][foundry-badge]][foundry]
 [![License: GPL-3.0][license-badge]][license]
 
 [gha]: https://github.com/JaredBorders/Zap/actions
@@ -11,54 +11,82 @@
 [license]: https://opensource.org/license/GPL-3.0/
 [license-badge]: https://img.shields.io/badge/GitHub-GPL--3.0-informational
 
-## Contracts
+## Overview
 
-> `tree src/`
+Zap is a smart contract that facilitates stablecoin "zapping" and Synthetix native collateral unwinding by integrating flash loans from Aave and Odos swaps.
 
-```
-src/
-├── Zap.sol
-├── ZapErrors.sol
-├── ZapEvents.sol
-└── interfaces
-    ├── IERC20.sol
-    └── ISpotMarketProxy.sol
-```
+### What is a **Zap**?
 
-## Tests
+> ONLY USDC is supported
 
-1. Follow the [Foundry guide to working on an existing project](https://book.getfoundry.sh/projects/working-on-an-existing-project.html)
+USDC <--(spot market)--> sUSDC <--(spot market)--> USDx
 
-2. Build project
+### What is **Collateral Unwinding**?
 
-```
-npm run compile
-```
+#### Flashloan Utility Flow
 
-3. Execute tests (requires rpc url(s) to be set in `.env`)
+1. **Request Flash Loans (Aave):** Borrow USDC to access liquidity without posting collateral.
+2. **Zap into USDx (Synthetix Spot Market):** Use the borrowed funds to zap into USDx.
+3. **Burn USDx & Repay Debt (Synthetix Core):** Repay Synthetix debt by burning USDx.
+4. **Withdraw and Unwrap Collateral (Synthetix Spot Market):** Withdraw margin (e.g., sETH) and convert it back to underlying assets (e.g., WETH).
+5. **Swap (Odos):** Exchange collateral assets (like WETH) for USDC to repay the flash loan.
+6. **Flash Loan Repayment (Aave):** The USDC loan, including the premium, is repaid to Aave.
+7. **Send Remaining Collateral (Synthetix):** Any surplus collateral is returned to the user.
 
-```
-npm run test
-```
+## Key Features
 
-4. Run specific test
+- Zap via Synthetix
+- Wrap & Unwrap Collateral via Synthetix
+- Buy & Sell via Synthetix
+- Unwind Collateral via Synthetix, Aave, and Odos
+- Burn Debt via Synthetix
+- Withdraw Perp Collateral via Synthetix
+- Swap via Odos
 
-```
-forge test --fork-url $(grep BASE_RPC_URL .env | cut -d '=' -f2) --match-test TEST_NAME -vvv
-```
+## Development
 
-## Deployment Addresses
+### Build, Test, Report
 
-> See `deployments/` folder
+1. **Build the project**
 
-1. Optimism deployments found in `deployments/Optimism.json`
-2. Optimism Goerli deployments found in `deployments/OptimismGoerli.json`
-3. Base deployments found in `deployments/Base.json`
-4. Base Goerli deployments found in `deployments/BaseGoerli.json`
+   ```
+   forge build
+   ```
 
-## Audits
+2. **Run tests**
+
+   ```
+   forge test
+   ```
+
+3. **Report Test Coverage**
+
+   ```
+   make coverage
+   ```
+
+4. **Report Gas Snapshot**
+   ```
+   make snapshot
+   ```
+
+## How to Deploy
 
-> See `audits/` folder
+- See the `deployments/` folder for Arbitrum and Base deployments.
+
+How to Deploy:
+
+1. Create a `.env` file using `.env-example` as a reference
+
+2. Deploy to Base
+   ```
+   make deploy_base
+   ```
+3. Deploy to Arbitrum
+   ```
+   make deploy_arbitrum
+   ```
+
+## Audits
 
-1. Internal audits found in `audits/internal/`
-2. External audits found in `audits/external/`
+- See the `audits/` folder for Audit reports.

deployments/Arbitrum.json

@@ -0,0 +1,3 @@
+{
+    "Zap": "0xD1F129e0cDd3Cc5c65ea00041623841C3d709F83"
+}

deployments/Base.json

@@ -0,0 +1,3 @@
+{
+    "Zap": "0xC9aF789Ae606F69cF8Ed073A04eC92f2354b027d"
+}

docs/.gitignore

@@ -0,0 +1 @@
+book/

docs/book.css

@@ -0,0 +1,13 @@
+table {
+    margin: 0 auto;
+    border-collapse: collapse;
+    width: 100%;
+}
+
+table td:first-child {
+    width: 15%;
+}
+
+table td:nth-child(2) {
+    width: 25%;
+}

docs/book.toml

@@ -0,0 +1,12 @@
+[book]
+src = "src"
+title = ""
+
+[output.html]
+no-section-label = true
+additional-js = ["solidity.min.js"]
+additional-css = ["book.css"]
+git-repository-url = "https://github.com/moss-eth/zap"
+
+[output.html.fold]
+enable = true