cryptointerface 0.1.0__py3-none-any.whl

cryptointerface/flashloan.py

@@ -0,0 +1,307 @@
+"""
+Aave V3 flash loan integration.
+
+Usage
+-----
+1. Deploy a contract that implements `executeOperation` (see the Solidity
+   template in `AaveFlashLoan.EXECUTOR_TEMPLATE`).
+2. Call `AaveFlashLoan.flash_loan_tx(...)` to build the initiating transaction.
+3. Sign and broadcast with `Wallet.sign_and_send(tx)`.
+
+Flash-loan fee: 0.09 % (9 bps) on all Aave V3 deployments.
+"""
+
+from __future__ import annotations
+
+from web3 import Web3
+
+# ---------------------------------------------------------------------------
+# Aave V3 Pool addresses (PoolAddressesProvider-resolved Pool proxy)
+# Chain IDs match the Network enum in periphery/enums.py
+# ---------------------------------------------------------------------------
+AAVE_V3_POOL: dict[str, str] = {
+    "1":        "0x87870Bca3F3fD6335C3F4ce8392D69350B4fA4E2",  # Ethereum mainnet
+    "10":       "0x794a61358D6845594F94dc1DB02A252b5b4814aD",  # Optimism
+    "56":       "0x6807dc923806fE8Fd134338EABCA509979a7e0cB",  # BNB Chain
+    "137":      "0x794a61358D6845594F94dc1DB02A252b5b4814aD",  # Polygon
+    "8453":     "0xA238Dd80C259a72e81d7e4664a9801593F98d1c5",  # Base
+    "42161":    "0x794a61358D6845594F94dc1DB02A252b5b4814aD",  # Arbitrum One
+    "43114":    "0x794a61358D6845594F94dc1DB02A252b5b4814aD",  # Avalanche C-Chain
+    "11155111": "0x6Ae43d3271ff6888e7Fc43Fd7321a503ff738951",  # Sepolia testnet
+}
+
+FLASH_LOAN_FEE_BPS = 9  # 0.09 %
+
+# ---------------------------------------------------------------------------
+# Minimal Aave V3 Pool ABI — only the flashLoan selector is needed.
+# ---------------------------------------------------------------------------
+_AAVE_POOL_ABI = [
+    {
+        "inputs": [
+            {"internalType": "address",   "name": "receiverAddress", "type": "address"},
+            {"internalType": "address[]", "name": "assets",          "type": "address[]"},
+            {"internalType": "uint256[]", "name": "amounts",         "type": "uint256[]"},
+            {"internalType": "uint256[]", "name": "interestRateModes", "type": "uint256[]"},
+            {"internalType": "address",   "name": "onBehalfOf",      "type": "address"},
+            {"internalType": "bytes",     "name": "params",          "type": "bytes"},
+            {"internalType": "uint16",    "name": "referralCode",    "type": "uint16"},
+        ],
+        "name": "flashLoan",
+        "outputs": [],
+        "stateMutability": "nonpayable",
+        "type": "function",
+    },
+    {
+        "inputs": [
+            {"internalType": "address",  "name": "receiverAddress", "type": "address"},
+            {"internalType": "address",  "name": "asset",           "type": "address"},
+            {"internalType": "uint256",  "name": "amount",          "type": "uint256"},
+            {"internalType": "uint256",  "name": "interestRateMode","type": "uint256"},
+            {"internalType": "address",  "name": "onBehalfOf",      "type": "address"},
+            {"internalType": "bytes",    "name": "params",          "type": "bytes"},
+            {"internalType": "uint16",   "name": "referralCode",    "type": "uint16"},
+        ],
+        "name": "flashLoanSimple",
+        "outputs": [],
+        "stateMutability": "nonpayable",
+        "type": "function",
+    },
+]
+
+
+class AaveFlashLoan:
+    """Build Aave V3 flash-loan transactions (unsigned)."""
+
+    # ------------------------------------------------------------------
+    # Solidity executor template — deploy this contract, fill in your
+    # arbitrage logic inside executeOperation, then pass its address as
+    # `receiver_contract` to flash_loan_tx / flash_loan_simple_tx.
+    # ------------------------------------------------------------------
+    EXECUTOR_TEMPLATE = """\
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.20;
+
+import {IFlashLoanReceiver} from "@aave/core-v3/contracts/flashloan/interfaces/IFlashLoanReceiver.sol";
+import {IPoolAddressesProvider} from "@aave/core-v3/contracts/interfaces/IPoolAddressesProvider.sol";
+import {IPool} from "@aave/core-v3/contracts/interfaces/IPool.sol";
+import {IERC20} from "@openzeppelin/contracts/token/ERC20/IERC20.sol";
+
+/**
+ * @title  FlashLoanExecutor
+ * @notice Receives Aave V3 flash loans and executes atomic arbitrage.
+ *         Deploy once; call requestFlashLoan to trigger a loan.
+ */
+contract FlashLoanExecutor is IFlashLoanReceiver {
+    IPoolAddressesProvider public immutable override ADDRESSES_PROVIDER;
+    IPool                  public immutable override POOL;
+    address public owner;
+
+    modifier onlyOwner() {
+        require(msg.sender == owner, "Not owner");
+        _;
+    }
+
+    constructor(address addressesProvider) {
+        ADDRESSES_PROVIDER = IPoolAddressesProvider(addressesProvider);
+        POOL = IPool(IPoolAddressesProvider(addressesProvider).getPool());
+        owner = msg.sender;
+    }
+
+    /**
+     * @notice Called by Aave Pool after sending `amounts` of `assets` to this contract.
+     *         Must repay amounts[i] + premiums[i] for each asset before returning.
+     */
+    function executeOperation(
+        address[] calldata assets,
+        uint256[] calldata amounts,
+        uint256[] calldata premiums,
+        address  /*initiator*/,
+        bytes    calldata params
+    ) external override returns (bool) {
+        require(msg.sender == address(POOL), "Caller not Pool");
+
+        // ----------------------------------------------------------------
+        // INSERT YOUR ARBITRAGE LOGIC HERE
+        // params is ABI-encoded data passed from Python (e.g. swap routes).
+        // Example: decode buy/sell DEX router addresses and call swap().
+        // ----------------------------------------------------------------
+
+        // Approve repayment for each asset
+        for (uint256 i = 0; i < assets.length; i++) {
+            uint256 amountOwed = amounts[i] + premiums[i];
+            IERC20(assets[i]).approve(address(POOL), amountOwed);
+        }
+        return true;
+    }
+
+    /**
+     * @notice Initiate a multi-asset flash loan.
+     * @param assets   Token addresses to borrow.
+     * @param amounts  Amounts (in token's native decimals).
+     * @param params   Arbitrary bytes forwarded to executeOperation.
+     */
+    function requestFlashLoan(
+        address[] calldata assets,
+        uint256[] calldata amounts,
+        bytes     calldata params
+    ) external onlyOwner {
+        uint256[] memory modes = new uint256[](assets.length); // 0 = no debt
+        POOL.flashLoan(address(this), assets, amounts, modes, address(this), params, 0);
+    }
+
+    /**
+     * @notice Initiate a single-asset flash loan (cheaper gas).
+     */
+    function requestFlashLoanSimple(
+        address asset,
+        uint256 amount,
+        bytes   calldata params
+    ) external onlyOwner {
+        POOL.flashLoanSimple(address(this), asset, amount, params, 0);
+    }
+
+    /// Rescue any tokens accidentally sent to this contract.
+    function rescue(address token) external onlyOwner {
+        IERC20(token).transfer(owner, IERC20(token).balanceOf(address(this)));
+    }
+}
+"""
+
+    def __init__(self, chain_id: str | int, rpc_url: str):
+        self.chain_id = str(chain_id)
+        self.rpc_url = rpc_url
+        pool_address = AAVE_V3_POOL.get(self.chain_id)
+        if pool_address is None:
+            raise ValueError(
+                f"Aave V3 Pool not configured for chain_id={chain_id}. "
+                f"Supported chains: {list(AAVE_V3_POOL.keys())}"
+            )
+        self.pool_address = pool_address
+        self._w3 = Web3(Web3.HTTPProvider(rpc_url, request_kwargs={"timeout": 15}))
+        self._pool = self._w3.eth.contract(
+            address=Web3.to_checksum_address(pool_address),
+            abi=_AAVE_POOL_ABI,
+        )
+
+    # ------------------------------------------------------------------
+    # Transaction builders (return unsigned tx dicts)
+    # ------------------------------------------------------------------
+
+    def flash_loan_tx(
+        self,
+        receiver_contract: str,
+        assets: list[str],
+        amounts: list[int],
+        sender: str,
+        params: bytes = b"",
+        referral_code: int = 0,
+    ) -> dict:
+        """
+        Build an unsigned `flashLoan` transaction (multi-asset).
+
+        Parameters
+        ----------
+        receiver_contract : str
+            Address of the deployed FlashLoanExecutor contract.
+        assets : list[str]
+            Token addresses to borrow (checksummed).
+        amounts : list[int]
+            Amounts in raw token units (use `to_wei` to scale).
+        sender : str
+            EOA that will sign and send the transaction.
+        params : bytes
+            ABI-encoded data forwarded to `executeOperation`.
+        referral_code : int
+            Aave referral code (0 for none).
+
+        Returns
+        -------
+        dict
+            Unsigned transaction dict ready for `Wallet.sign_and_send`.
+        """
+        assets_cs  = [Web3.to_checksum_address(a) for a in assets]
+        modes      = [0] * len(assets)   # 0 = no debt (must repay in same tx)
+        receiver_cs = Web3.to_checksum_address(receiver_contract)
+        sender_cs   = Web3.to_checksum_address(sender)
+
+        return self._pool.functions.flashLoan(
+            receiver_cs,
+            assets_cs,
+            amounts,
+            modes,
+            receiver_cs,       # onBehalfOf = the executor itself
+            params,
+            referral_code,
+        ).build_transaction({"from": sender_cs})
+
+    def flash_loan_simple_tx(
+        self,
+        receiver_contract: str,
+        asset: str,
+        amount: int,
+        sender: str,
+        params: bytes = b"",
+        referral_code: int = 0,
+    ) -> dict:
+        """
+        Build an unsigned `flashLoanSimple` transaction (single asset, lower gas).
+
+        Parameters
+        ----------
+        receiver_contract : str
+            Address of the deployed FlashLoanExecutor contract.
+        asset : str
+            Token address to borrow.
+        amount : int
+            Amount in raw token units.
+        sender : str
+            EOA that will sign and send the transaction.
+        params : bytes
+            ABI-encoded data forwarded to `executeOperation`.
+        """
+        receiver_cs = Web3.to_checksum_address(receiver_contract)
+        asset_cs    = Web3.to_checksum_address(asset)
+        sender_cs   = Web3.to_checksum_address(sender)
+
+        return self._pool.functions.flashLoanSimple(
+            receiver_cs,
+            asset_cs,
+            amount,
+            params,
+            referral_code,
+        ).build_transaction({"from": sender_cs})
+
+    # ------------------------------------------------------------------
+    # Convenience: estimate profit after flash-loan fee
+    # ------------------------------------------------------------------
+
+    @staticmethod
+    def net_profit(
+        amount: int,
+        gross_profit_wei: int,
+        token_decimals: int = 18,
+    ) -> dict:
+        """
+        Estimate net profit after the 0.09 % Aave flash-loan fee.
+
+        Parameters
+        ----------
+        amount : int
+            Flash-loan amount in raw token units.
+        gross_profit_wei : int
+            Expected gross profit in raw token units.
+        token_decimals : int
+            Decimal places of the borrowed token.
+
+        Returns
+        -------
+        dict with keys: fee_wei, net_profit_wei, net_profit_human, is_profitable
+        """
+        fee_wei = (amount * FLASH_LOAN_FEE_BPS) // 10_000
+        net     = gross_profit_wei - fee_wei
+        return {
+            "fee_wei":         fee_wei,
+            "net_profit_wei":  net,
+            "net_profit_human": net / 10 ** token_decimals,
+            "is_profitable":   net > 0,
+        }

cryptointerface/periphery/config.py

@@ -0,0 +1,46 @@
+import os
+import json
+import platform
+from pathlib import Path
+
+ENV_VAR = "CRYPTOINTERFACE_DB"
+CONFIG_DIR = "cryptointerface"
+CONFIG_FILE = "config.json"
+DEFAULT_DB = "cryptointerface.db"
+
+
+def _get_config_dir() -> Path:
+    system = platform.system()
+    if system == "Windows":
+        base = os.environ.get("APPDATA", Path.home() / "AppData" / "Roaming")
+    elif system == "Darwin":
+        base = Path.home() / "Library" / "Application Support"
+    else:
+        base = os.environ.get("XDG_CONFIG_HOME", Path.home() / ".config")
+
+    return Path(base) / CONFIG_DIR
+
+
+def get_db_path() -> Path:
+    # 1. Environment variable
+    env_path = os.environ.get(ENV_VAR, "")
+    if env_path:
+        return Path(env_path)
+
+    # 2. Config file
+    config_dir = _get_config_dir()
+    config_path = config_dir / CONFIG_FILE
+
+    if config_path.exists():
+        try:
+            with open(config_path) as f:
+                config = json.load(f)
+            db_path = config.get("database", "")
+            if db_path:
+                return Path(db_path)
+        except (json.JSONDecodeError, OSError):
+            pass
+
+    # 3. Default: inside the config directory
+    config_dir.mkdir(parents=True, exist_ok=True)
+    return config_dir / DEFAULT_DB

cryptointerface/periphery/db.py

@@ -0,0 +1,136 @@
+import threading
+import duckdb
+from .config import get_db_path
+
+_db_path: str | None = None
+_lock = threading.Lock()
+_thread_local = threading.local()
+
+_CREATE_TABLES_SQL = """
+CREATE TABLE IF NOT EXISTS tokens (
+    symbol      VARCHAR NOT NULL,
+    chain_id    VARCHAR NOT NULL,
+    address     VARCHAR NOT NULL,
+    decimals    INTEGER,
+    PRIMARY KEY (chain_id, address)
+);
+CREATE TABLE IF NOT EXISTS pools_v2 (
+    dex         VARCHAR NOT NULL,
+    chain_id    INTEGER NOT NULL,
+    token_0     VARCHAR NOT NULL,
+    token_1     VARCHAR NOT NULL,
+    address     VARCHAR NOT NULL,
+    PRIMARY KEY (dex, chain_id, token_0, token_1)
+);
+CREATE TABLE IF NOT EXISTS pools_v3 (
+    dex         VARCHAR NOT NULL,
+    chain_id    INTEGER NOT NULL,
+    token_0     VARCHAR NOT NULL,
+    token_1     VARCHAR NOT NULL,
+    fee         INTEGER NOT NULL,
+    address     VARCHAR NOT NULL,
+    PRIMARY KEY (dex, chain_id, token_0, token_1, fee)
+);
+"""
+
+
+def _init_tables(db_path: str = None) -> duckdb.DuckDBPyConnection:
+    global _db_path
+    if db_path is not None:
+        _db_path = db_path
+    if _db_path is None:
+        _db_path = str(get_db_path())
+
+    if not hasattr(_thread_local, "conn"):
+        _thread_local.conn = duckdb.connect(_db_path)
+        for stmt in _CREATE_TABLES_SQL.strip().split(";"):
+            stmt = stmt.strip()
+            if stmt:
+                _thread_local.conn.execute(stmt)
+
+    return _thread_local.conn
+
+
+def insert_data(df, db_cols: list, table_name: str, conn, pk_cols: list = None):
+    if df.is_empty():
+        return
+    final_cols = [c for c in db_cols if c in df.columns]
+    df = df.select(final_cols)
+    col_names = ", ".join(final_cols)
+
+    with _lock:
+        if pk_cols:
+            pk_where = " AND ".join([f"existing.{c} = df.{c}" for c in pk_cols])
+            conn.execute(
+                f"""
+                INSERT INTO {table_name} ({col_names})
+                SELECT {col_names} FROM df
+                WHERE NOT EXISTS (
+                    SELECT 1 FROM {table_name} existing
+                    WHERE {pk_where}
+                )
+            """
+            )
+        else:
+            conn.execute(
+                f"INSERT INTO {table_name} ({col_names}) SELECT {col_names} FROM df"
+            )
+
+
+def drop_tables(table_name: str):
+    conn = _init_tables()
+    conn.execute(f"DROP TABLE {table_name}")
+    conn.commit()
+    conn.close()
+
+
+def export_tokens_to_csv(csv_path: str = "tokens.csv"):
+    conn = _init_tables()
+    conn.execute(f"COPY tokens TO '{csv_path}' (HEADER, DELIMITER ',')")
+
+
+def export_pools_to_csv(v2_path: str = "pools_v2.csv", v3_path: str = "pools_v3.csv"):
+    conn = _init_tables()
+    conn.execute(f"COPY pools_v2 TO '{v2_path}' (HEADER, DELIMITER ',')")
+    conn.execute(f"COPY pools_v3 TO '{v3_path}' (HEADER, DELIMITER ',')")
+
+
+def insert_tokens_csv_to_db(csv_path: str = "tokens.csv"):
+    conn = _init_tables()
+    conn.execute(
+        f"""
+        INSERT INTO tokens (symbol, chain_id, address, decimals)
+        SELECT symbol, chain_id, address, decimals FROM read_csv_auto('{csv_path}')
+        WHERE NOT EXISTS (
+            SELECT 1 FROM tokens existing
+            WHERE existing.chain_id = chain_id AND existing.address = address
+        )
+        """
+    )
+
+
+def insert_pools_csv_to_db(v2_path: str = "pools_v2.csv", v3_path: str = "pools_v3.csv"):
+    conn = _init_tables()
+    conn.execute(
+        f"""
+        INSERT INTO pools_v2 (dex, chain_id, token_0, token_1, address)
+        SELECT dex, chain_id, token_0, token_1, address FROM read_csv_auto('{v2_path}')
+        WHERE NOT EXISTS (
+            SELECT 1 FROM pools_v2 existing
+            WHERE existing.dex = dex AND existing.chain_id = chain_id
+              AND existing.token_0 = token_0 AND existing.token_1 = token_1
+        )
+        """
+    )
+    conn.execute(
+        f"""
+        INSERT INTO pools_v3 (dex, chain_id, token_0, token_1, fee, address)
+        SELECT dex, chain_id, token_0, token_1, fee, address FROM read_csv_auto('{v3_path}')
+        WHERE NOT EXISTS (
+            SELECT 1 FROM pools_v3 existing
+            WHERE existing.dex = dex AND existing.chain_id = chain_id
+              AND existing.token_0 = token_0 AND existing.token_1 = token_1
+              AND existing.fee = fee
+        )
+        """
+    )

cryptointerface/periphery/dex_architecture.json

@@ -0,0 +1,119 @@
+{
+    "uniswap_v2": {
+        "version": 2,
+        "protocol": "uniswap_v2",
+        "factory_fn": "getPair",
+        "router_fn": "swapExactTokensForTokens",
+        "fee_tiers": null,
+        "swap_fee_bps": 30,
+        "notes": "Original Uniswap V2. Fixed 0.3% fee baked into the pair contract."
+    },
+    "uniswap_v3": {
+        "version": 3,
+        "protocol": "uniswap_v3",
+        "factory_fn": "getPool",
+        "router_fn": "exactInputSingle",
+        "fee_tiers": [100, 500, 3000, 10000],
+        "swap_fee_bps": null,
+        "notes": "Original Uniswap V3. Fee is per pool — use the matched fee tier."
+    },
+    "sushiswap_v2": {
+        "version": 2,
+        "protocol": "uniswap_v2",
+        "factory_fn": "getPair",
+        "router_fn": "swapExactTokensForTokens",
+        "fee_tiers": null,
+        "swap_fee_bps": 30,
+        "notes": "Uniswap V2 fork. ABI-compatible with uniswap_v2."
+    },
+    "sushiswap_v3": {
+        "version": 3,
+        "protocol": "uniswap_v3",
+        "factory_fn": "getPool",
+        "router_fn": "exactInputSingle",
+        "fee_tiers": [100, 500, 3000, 10000],
+        "swap_fee_bps": null,
+        "notes": "Uniswap V3 fork. Fee is per pool — use the matched fee tier."
+    },
+    "pancakeswap_v2": {
+        "version": 2,
+        "protocol": "uniswap_v2",
+        "factory_fn": "getPair",
+        "router_fn": "swapExactTokensForTokens",
+        "fee_tiers": null,
+        "swap_fee_bps": 25,
+        "notes": "Uniswap V2 fork. 0.25% swap fee."
+    },
+    "pancakeswap_v3": {
+        "version": 3,
+        "protocol": "uniswap_v3",
+        "factory_fn": "getPool",
+        "router_fn": "exactInputSingle",
+        "fee_tiers": [100, 500, 2500, 10000],
+        "swap_fee_bps": null,
+        "notes": "Uniswap V3 fork. Fee is per pool — use the matched fee tier."
+    },
+    "quickswap_v2": {
+        "version": 2,
+        "protocol": "uniswap_v2",
+        "factory_fn": "getPair",
+        "router_fn": "swapExactTokensForTokens",
+        "fee_tiers": null,
+        "swap_fee_bps": 30,
+        "notes": "Uniswap V2 fork on Polygon."
+    },
+    "quickswap_v3": {
+        "version": 3,
+        "protocol": "algebra_v3",
+        "factory_fn": "poolByPair",
+        "router_fn": "exactInputSingle",
+        "fee_tiers": null,
+        "swap_fee_bps": null,
+        "notes": "Algebra V3 fork. Fee is dynamic per pool."
+    },
+    "camelot_v2": {
+        "version": 2,
+        "protocol": "uniswap_v2",
+        "factory_fn": "getPair",
+        "router_fn": "swapExactTokensForTokens",
+        "fee_tiers": null,
+        "swap_fee_bps": 30,
+        "notes": "Uniswap V2 fork on Arbitrum."
+    },
+    "camelot_v3": {
+        "version": 3,
+        "protocol": "algebra_v3",
+        "factory_fn": "poolByPair",
+        "router_fn": "exactInputSingle",
+        "fee_tiers": null,
+        "swap_fee_bps": null,
+        "notes": "Algebra V3 fork on Arbitrum. Fee is dynamic per pool."
+    },
+    "traderjoe_v1": {
+        "version": 2,
+        "protocol": "uniswap_v2",
+        "factory_fn": "getPair",
+        "router_fn": "swapExactTokensForTokens",
+        "fee_tiers": null,
+        "swap_fee_bps": 30,
+        "notes": "Uniswap V2 fork on Avalanche/Arbitrum."
+    },
+    "aerodrome": {
+        "version": 2,
+        "protocol": "solidly_v2",
+        "factory_fn": "getPool",
+        "router_fn": "swapExactTokensForTokens",
+        "fee_tiers": null,
+        "swap_fee_bps": 2,
+        "notes": "Solidly/Velodrome fork on Base. 0.02% volatile pool fee (stable pools vary)."
+    },
+    "velodrome": {
+        "version": 2,
+        "protocol": "solidly_v2",
+        "factory_fn": "getPool",
+        "router_fn": "swapExactTokensForTokens",
+        "fee_tiers": null,
+        "swap_fee_bps": 2,
+        "notes": "Solidly fork on Optimism. 0.02% volatile pool fee (stable pools vary)."
+    }
+}