agentwallet-sdk 3.1.0 → 3.1.1

package/README.md

@@ -12,16 +12,19 @@ Agent spent $490 today → 🛑 Next tx queued ($500/day limit hit)
 
 ## How We Compare
 
-| | **agentwallet-sdk** | **Coinbase Agentic Wallet** | **MoonPay Agents** |
-|---|---|---|---|
-| **Custody** | Non-custodial (keys on device) | Semi-custodial (TEE) | Non-custodial (claimed) |
-| **Spend Limits** | On-chain (smart contract) | API-enforced | Not documented |
-| **Chains** | **17** (Base, ETH, Arb, Polygon + 12 EVM + **Solana**) | Base only | Unclear |
-| **Agent Identity** | ERC-8004 + ERC-6551 | None | None |
-| **Open Source** | MIT | Partial | Closed |
-| **x402 Payments** | Native | Supported | "Compatible" |
-
-> On-chain spend limits can't be bypassed even if the API layer is compromised. That's the difference between policy and math.
+| | **agentwallet-sdk** | **Coinbase Agentic** | **OKX OnchainOS** | **Binance Agent** | **MoonPay Agents** |
+|---|---|---|---|---|---|
+| **Custody** | Non-custodial (agent holds keys) | Semi-custodial (TEE) | Custodial (exchange) | Custodial (exchange) | Non-custodial (claimed) |
+| **Spend Limits** | On-chain (smart contract) | API-enforced | Not documented | Not documented | Not documented |
+| **Chains** | **17** (16 EVM + Solana) | Base only | 60+ (custodial) | Binance chain | Unclear |
+| **Agent Identity** | ERC-8004 + ERC-6551 | None | None | None | None |
+| **Open Source** | MIT | Partial | Closed | Closed | Closed |
+| **x402 Payments** | Native | Supported | Supported | No | "Compatible" |
+| **Jupiter Swaps** | Yes (Solana) | No | No | No | No |
+| **CCTP Bridging** | 17-chain V2 | No | Partial | No | No |
+| **If exchange goes down** | Agent keeps working | Degraded | Agent stops | Agent stops | Unknown |
+
+> On-chain spend limits can't be bypassed even if the API layer is compromised. Exchanges can freeze your agent's account. A non-custodial smart contract can't. That's the difference between policy and math.
 
 ## Why Agent Wallet?
 

package/dist/flash/executor.d.ts

@@ -0,0 +1,119 @@
+/**
+ * Flash Loan Executor
+ *
+ * Builds signed transactions for Aave V3 flash loan execution.
+ *
+ * ⚠️ PRODUCTION NOTICE — REQUIRED BEFORE USE:
+ * Flash loans use Aave's callback pattern. Aave calls `executeOperation()` on a
+ * receiver contract mid-transaction. This SDK generates the transaction calldata,
+ * but you MUST deploy `FlashLoanExecutor.sol` first.
+ *
+ * Deployment steps:
+ * 1. Deploy `src/flash/contracts/FlashLoanExecutor.sol` with the Aave Pool address
+ * 2. Fund it with enough gas token for operations
+ * 3. Pass the deployed address as `executorContractAddress` in FlashLoanConfig
+ *
+ * Architecture (approach C — agent-signed transactions):
+ * - Agent calls this executor's `buildArbitrageTx()` or `buildLiquidationTx()`
+ * - Executor returns a transaction object (to, data, value, gasEstimate)
+ * - Agent signs and broadcasts the transaction using their wallet
+ * - The deployed FlashLoanExecutor.sol contract handles the Aave callback atomically
+ *
+ * No private keys are held by this SDK. All signing is performed by the agent's wallet.
+ */
+import { ethers } from 'ethers';
+import type { FlashLoanConfig, FlashLoanProvider, ArbitrageOpportunity, LiquidationOpportunity } from './types.js';
+/**
+ * Aave V3 Pool — methods needed by the executor.
+ * Full ABI: https://github.com/aave/aave-v3-core/blob/master/contracts/interfaces/IPool.sol
+ */
+declare const AAVE_POOL_ABI: readonly ["function flashLoanSimple(address receiverAddress, address asset, uint256 amount, bytes calldata params, uint16 referralCode) external", "function liquidationCall(address collateralAsset, address debtAsset, address user, uint256 debtToCover, bool receiveAToken) external"];
+/**
+ * FlashLoanExecutor contract ABI (our deployed contract).
+ * The contract implements IFlashLoanReceiver and handles the Aave callback.
+ * See: src/flash/contracts/FlashLoanExecutor.sol
+ */
+declare const FLASH_EXECUTOR_ABI: readonly ["function executeArbitrage(address asset, uint256 amount, address buyDex, address sellDex, bytes calldata buyCalldata, bytes calldata sellCalldata) external", "function executeLiquidation(address collateralAsset, address debtAsset, address user, uint256 debtAmount, address aavePool) external"];
+/**
+ * Canonical Aave V3 Pool addresses by chain.
+ * Source: https://docs.aave.com/developers/deployed-contracts/v3-mainnet
+ */
+declare const AAVE_POOL_ADDRESSES: Record<string, string>;
+/** A built transaction ready for agent signing */
+export interface BuiltTransaction {
+    /** Target contract address (Aave Pool or FlashLoanExecutor) */
+    to: string;
+    /** ABI-encoded calldata */
+    data: string;
+    /** ETH value to send (0n for token flash loans) */
+    value: bigint;
+    /** Estimated gas units required */
+    gasEstimate: bigint;
+}
+/**
+ * Builds flash loan transactions for agent signing.
+ *
+ * Usage:
+ * ```typescript
+ * const executor = new FlashLoanExecutor({ chain: 'base', rpcUrl: '...' });
+ * const tx = executor.buildArbitrageTx(opportunity, wallet);
+ * const receipt = await wallet.sendTransaction(tx);
+ * ```
+ *
+ * ⚠️ Requires a deployed `FlashLoanExecutor.sol` contract (see config).
+ */
+export declare class FlashLoanExecutor {
+    private readonly config;
+    constructor(config: FlashLoanConfig);
+    /**
+     * Build a flash loan arbitrage transaction.
+     *
+     * Flow:
+     * 1. Encodes arbitrage params (buy/sell DEX calldata) into bytes
+     * 2. Wraps in `flashLoanSimple()` call to Aave Pool
+     * 3. Aave calls back `FlashLoanExecutor.executeOperation()` on our contract
+     * 4. Contract buys on DEX A, sells on DEX B, repays loan + fee
+     *
+     * @param opportunity - Arbitrage opportunity from the scanner
+     * @param wallet - Agent's ethers.Wallet (used only for address; does not sign here)
+     * @returns Transaction object ready for wallet.sendTransaction()
+     */
+    buildArbitrageTx(opportunity: ArbitrageOpportunity, wallet: ethers.Wallet): BuiltTransaction;
+    /**
+     * Build a flash loan liquidation transaction.
+     *
+     * Flow:
+     * 1. Flash-borrows the borrower's debt token from Aave
+     * 2. Calls `liquidationCall()` on Aave with the borrowed funds
+     * 3. Receives discounted collateral (5–10% bonus)
+     * 4. Swaps collateral back to debt token to repay flash loan
+     * 5. Profit = collateral bonus - flash loan fee - gas
+     *
+     * @param opportunity - Liquidation opportunity from the scanner
+     * @param wallet - Agent's ethers.Wallet
+     * @returns Transaction object ready for wallet.sendTransaction()
+     */
+    buildLiquidationTx(opportunity: LiquidationOpportunity, wallet: ethers.Wallet): BuiltTransaction;
+    /**
+     * Get the canonical Aave V3 Pool address for a chain.
+     *
+     * @param chain - Chain name (case-insensitive)
+     * @returns Pool address, or empty string if chain is not supported
+     */
+    getAavePoolAddress(chain: string): string;
+    /**
+     * Estimate the flash loan fee for a given borrow amount.
+     *
+     * Fee schedule:
+     * - Aave V3:    0.09% (9 bps) — configurable by Aave governance
+     * - Balancer:   0.00% (0 bps) — free flash loans (gas only)
+     * - Uniswap V3: 0.30% (30 bps) — same as the pool's swap fee tier
+     *
+     * @param amount - Borrow amount in token's native decimals
+     * @param provider - Flash loan provider (default: 'aave-v3')
+     * @returns Fee amount in the same units as `amount`
+     */
+    estimateFee(amount: bigint, provider?: FlashLoanProvider): bigint;
+}
+export { AAVE_POOL_ABI, FLASH_EXECUTOR_ABI, AAVE_POOL_ADDRESSES };
+//# sourceMappingURL=executor.d.ts.map

package/dist/flash/executor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"executor.d.ts","sourceRoot":"","sources":["../../src/flash/executor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAChC,OAAO,KAAK,EAAE,eAAe,EAAE,iBAAiB,EAAE,oBAAoB,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAC;AAInH;;;GAGG;AACH,QAAA,MAAM,aAAa,4RAGT,CAAC;AAEX;;;;GAIG;AACH,QAAA,MAAM,kBAAkB,kTAGd,CAAC;AAIX;;;GAGG;AACH,QAAA,MAAM,mBAAmB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAK/C,CAAC;AAaF,kDAAkD;AAClD,MAAM,WAAW,gBAAgB;IAC/B,+DAA+D;IAC/D,EAAE,EAAE,MAAM,CAAC;IACX,2BAA2B;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,mDAAmD;IACnD,KAAK,EAAE,MAAM,CAAC;IACd,mCAAmC;IACnC,WAAW,EAAE,MAAM,CAAC;CACrB;AAID;;;;;;;;;;;GAWG;AACH,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAkB;gBAE7B,MAAM,EAAE,eAAe;IAInC;;;;;;;;;;;;OAYG;IACH,gBAAgB,CACd,WAAW,EAAE,oBAAoB,EACjC,MAAM,EAAE,MAAM,CAAC,MAAM,GACpB,gBAAgB;IAoCnB;;;;;;;;;;;;;OAaG;IACH,kBAAkB,CAChB,WAAW,EAAE,sBAAsB,EACnC,MAAM,EAAE,MAAM,CAAC,MAAM,GACpB,gBAAgB;IAmCnB;;;;;OAKG;IACH,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM;IAIzC;;;;;;;;;;;OAWG;IACH,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,GAAE,iBAA6B,GAAG,MAAM;CAY7E;AAGD,OAAO,EAAE,aAAa,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,CAAC"}

package/dist/flash/executor.js

@@ -0,0 +1,195 @@
+/**
+ * Flash Loan Executor
+ *
+ * Builds signed transactions for Aave V3 flash loan execution.
+ *
+ * ⚠️ PRODUCTION NOTICE — REQUIRED BEFORE USE:
+ * Flash loans use Aave's callback pattern. Aave calls `executeOperation()` on a
+ * receiver contract mid-transaction. This SDK generates the transaction calldata,
+ * but you MUST deploy `FlashLoanExecutor.sol` first.
+ *
+ * Deployment steps:
+ * 1. Deploy `src/flash/contracts/FlashLoanExecutor.sol` with the Aave Pool address
+ * 2. Fund it with enough gas token for operations
+ * 3. Pass the deployed address as `executorContractAddress` in FlashLoanConfig
+ *
+ * Architecture (approach C — agent-signed transactions):
+ * - Agent calls this executor's `buildArbitrageTx()` or `buildLiquidationTx()`
+ * - Executor returns a transaction object (to, data, value, gasEstimate)
+ * - Agent signs and broadcasts the transaction using their wallet
+ * - The deployed FlashLoanExecutor.sol contract handles the Aave callback atomically
+ *
+ * No private keys are held by this SDK. All signing is performed by the agent's wallet.
+ */
+import { ethers } from 'ethers';
+// ─── ABIs ─────────────────────────────────────────────────────────────────────
+/**
+ * Aave V3 Pool — methods needed by the executor.
+ * Full ABI: https://github.com/aave/aave-v3-core/blob/master/contracts/interfaces/IPool.sol
+ */
+const AAVE_POOL_ABI = [
+    'function flashLoanSimple(address receiverAddress, address asset, uint256 amount, bytes calldata params, uint16 referralCode) external',
+    'function liquidationCall(address collateralAsset, address debtAsset, address user, uint256 debtToCover, bool receiveAToken) external',
+];
+/**
+ * FlashLoanExecutor contract ABI (our deployed contract).
+ * The contract implements IFlashLoanReceiver and handles the Aave callback.
+ * See: src/flash/contracts/FlashLoanExecutor.sol
+ */
+const FLASH_EXECUTOR_ABI = [
+    'function executeArbitrage(address asset, uint256 amount, address buyDex, address sellDex, bytes calldata buyCalldata, bytes calldata sellCalldata) external',
+    'function executeLiquidation(address collateralAsset, address debtAsset, address user, uint256 debtAmount, address aavePool) external',
+];
+// ─── Canonical Aave V3 Pool Addresses ─────────────────────────────────────────
+/**
+ * Canonical Aave V3 Pool addresses by chain.
+ * Source: https://docs.aave.com/developers/deployed-contracts/v3-mainnet
+ */
+const AAVE_POOL_ADDRESSES = {
+    ethereum: '0x87870Bca3F3fD6335C3F4ce8392D69350B4fA4E2',
+    base: '0xA238Dd80C259a72e81d7e4664a9801593F98d1c5',
+    arbitrum: '0x794a61358D6845594F94dc1DB02A252b5b4814aD',
+    optimism: '0x794a61358D6845594F94dc1DB02A252b5b4814aD',
+};
+/** Default gas limit for flash loan arbitrage transactions */
+const DEFAULT_ARB_GAS_ESTIMATE = 500000n;
+/** Default gas limit for flash loan liquidation transactions */
+const DEFAULT_LIQ_GAS_ESTIMATE = 400000n;
+/** Aave V3 referral code (0 = no referral) */
+const AAVE_REFERRAL_CODE = 0;
+// ─── FlashLoanExecutor Class ──────────────────────────────────────────────────
+/**
+ * Builds flash loan transactions for agent signing.
+ *
+ * Usage:
+ * ```typescript
+ * const executor = new FlashLoanExecutor({ chain: 'base', rpcUrl: '...' });
+ * const tx = executor.buildArbitrageTx(opportunity, wallet);
+ * const receipt = await wallet.sendTransaction(tx);
+ * ```
+ *
+ * ⚠️ Requires a deployed `FlashLoanExecutor.sol` contract (see config).
+ */
+export class FlashLoanExecutor {
+    constructor(config) {
+        this.config = config;
+    }
+    /**
+     * Build a flash loan arbitrage transaction.
+     *
+     * Flow:
+     * 1. Encodes arbitrage params (buy/sell DEX calldata) into bytes
+     * 2. Wraps in `flashLoanSimple()` call to Aave Pool
+     * 3. Aave calls back `FlashLoanExecutor.executeOperation()` on our contract
+     * 4. Contract buys on DEX A, sells on DEX B, repays loan + fee
+     *
+     * @param opportunity - Arbitrage opportunity from the scanner
+     * @param wallet - Agent's ethers.Wallet (used only for address; does not sign here)
+     * @returns Transaction object ready for wallet.sendTransaction()
+     */
+    buildArbitrageTx(opportunity, wallet) {
+        const aavePoolAddress = this.getAavePoolAddress(this.config.chain);
+        if (!aavePoolAddress) {
+            throw new Error(`No Aave V3 Pool address for chain: ${this.config.chain}`);
+        }
+        const pool = new ethers.Interface(AAVE_POOL_ABI);
+        // Encode the arbitrage strategy params that will be passed through Aave's callback.
+        // The FlashLoanExecutor.sol contract decodes these in executeOperation().
+        const innerParams = ethers.AbiCoder.defaultAbiCoder().encode(['address', 'address', 'bytes', 'bytes'], [
+            opportunity.buyDex, // DEX router to buy from
+            opportunity.sellDex, // DEX router to sell to
+            '0x', // buy calldata (filled by router in production)
+            '0x', // sell calldata (filled by router in production)
+        ]);
+        const data = pool.encodeFunctionData('flashLoanSimple', [
+            this.config.aavePoolAddress ?? wallet.address, // receiverAddress (FlashLoanExecutor.sol)
+            opportunity.tokenAddress, // asset to borrow
+            opportunity.amount, // amount
+            innerParams, // params passed to executeOperation
+            AAVE_REFERRAL_CODE,
+        ]);
+        return {
+            to: aavePoolAddress,
+            data,
+            value: 0n, // Token flash loans never require ETH value
+            gasEstimate: DEFAULT_ARB_GAS_ESTIMATE,
+        };
+    }
+    /**
+     * Build a flash loan liquidation transaction.
+     *
+     * Flow:
+     * 1. Flash-borrows the borrower's debt token from Aave
+     * 2. Calls `liquidationCall()` on Aave with the borrowed funds
+     * 3. Receives discounted collateral (5–10% bonus)
+     * 4. Swaps collateral back to debt token to repay flash loan
+     * 5. Profit = collateral bonus - flash loan fee - gas
+     *
+     * @param opportunity - Liquidation opportunity from the scanner
+     * @param wallet - Agent's ethers.Wallet
+     * @returns Transaction object ready for wallet.sendTransaction()
+     */
+    buildLiquidationTx(opportunity, wallet) {
+        const aavePoolAddress = this.getAavePoolAddress(this.config.chain);
+        if (!aavePoolAddress) {
+            throw new Error(`No Aave V3 Pool address for chain: ${this.config.chain}`);
+        }
+        const pool = new ethers.Interface(AAVE_POOL_ABI);
+        // Encode liquidation params for the callback
+        const innerParams = ethers.AbiCoder.defaultAbiCoder().encode(['address', 'address', 'address', 'address'], [
+            opportunity.collateralAddress, // collateral to seize
+            opportunity.debtAddress, // debt token to repay
+            opportunity.borrower, // target borrower
+            aavePoolAddress, // Aave Pool for repayment
+        ]);
+        const data = pool.encodeFunctionData('flashLoanSimple', [
+            this.config.aavePoolAddress ?? wallet.address, // receiverAddress (FlashLoanExecutor.sol)
+            opportunity.debtAddress, // asset = debt token
+            opportunity.debtAmount, // amount = debt to repay
+            innerParams,
+            AAVE_REFERRAL_CODE,
+        ]);
+        return {
+            to: aavePoolAddress,
+            data,
+            value: 0n,
+            gasEstimate: DEFAULT_LIQ_GAS_ESTIMATE,
+        };
+    }
+    /**
+     * Get the canonical Aave V3 Pool address for a chain.
+     *
+     * @param chain - Chain name (case-insensitive)
+     * @returns Pool address, or empty string if chain is not supported
+     */
+    getAavePoolAddress(chain) {
+        return AAVE_POOL_ADDRESSES[chain.toLowerCase()] ?? '';
+    }
+    /**
+     * Estimate the flash loan fee for a given borrow amount.
+     *
+     * Fee schedule:
+     * - Aave V3:    0.09% (9 bps) — configurable by Aave governance
+     * - Balancer:   0.00% (0 bps) — free flash loans (gas only)
+     * - Uniswap V3: 0.30% (30 bps) — same as the pool's swap fee tier
+     *
+     * @param amount - Borrow amount in token's native decimals
+     * @param provider - Flash loan provider (default: 'aave-v3')
+     * @returns Fee amount in the same units as `amount`
+     */
+    estimateFee(amount, provider = 'aave-v3') {
+        switch (provider) {
+            case 'aave-v3':
+                return (amount * 9n) / 10000n; // 0.09%
+            case 'balancer':
+                return 0n; // Balancer V2: 0% fee
+            case 'uniswap-v3':
+                return (amount * 30n) / 10000n; // 0.30% (same as default pool fee)
+            default:
+                return (amount * 9n) / 10000n;
+        }
+    }
+}
+// Re-export ABIs for users who want to interact with contracts directly
+export { AAVE_POOL_ABI, FLASH_EXECUTOR_ABI, AAVE_POOL_ADDRESSES };
+//# sourceMappingURL=executor.js.map

package/dist/flash/executor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"executor.js","sourceRoot":"","sources":["../../src/flash/executor.ts"],"names":[],"mappings":"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"}

package/dist/flash/index.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Flash Loan Module — Public API
+ *
+ * Exports the scanner (opportunity detection) and executor (transaction building)
+ * for Aave V3 flash loans.
+ *
+ * ⚠️ PRODUCTION NOTICE:
+ * Executing flash loans requires a deployed `FlashLoanExecutor.sol` contract.
+ * See `src/flash/contracts/FlashLoanExecutor.sol` for the Solidity scaffold.
+ *
+ * Quick start:
+ * ```typescript
+ * import { FlashOpportunityScanner, FlashLoanExecutor } from '@agentwallet/sdk/flash';
+ *
+ * const scanner = new FlashOpportunityScanner();
+ * const opportunities = await scanner.scanArbitrage({ tokens: ['WETH'], chain: 'base' });
+ *
+ * const executor = new FlashLoanExecutor({ chain: 'base', rpcUrl: '...' });
+ * const tx = executor.buildArbitrageTx(opportunities[0], wallet);
+ * await wallet.sendTransaction(tx);
+ * ```
+ */
+export { FlashOpportunityScanner } from './scanner.js';
+export type { ScanArbitrageParams, ScanLiquidationsParams } from './scanner.js';
+export { FlashLoanExecutor, AAVE_POOL_ABI, FLASH_EXECUTOR_ABI, AAVE_POOL_ADDRESSES } from './executor.js';
+export type { BuiltTransaction } from './executor.js';
+export type { FlashLoanConfig, FlashLoanResult, FlashOpportunity, ArbitrageOpportunity, LiquidationOpportunity, FlashScanResult, FlashOpportunityType, FlashLoanProvider, } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/flash/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/flash/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,EAAE,uBAAuB,EAAE,MAAM,cAAc,CAAC;AACvD,YAAY,EAAE,mBAAmB,EAAE,sBAAsB,EAAE,MAAM,cAAc,CAAC;AAEhF,OAAO,EAAE,iBAAiB,EAAE,aAAa,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AAC1G,YAAY,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAEtD,YAAY,EACV,eAAe,EACf,eAAe,EACf,gBAAgB,EAChB,oBAAoB,EACpB,sBAAsB,EACtB,eAAe,EACf,oBAAoB,EACpB,iBAAiB,GAClB,MAAM,YAAY,CAAC"}

package/dist/flash/index.js

@@ -0,0 +1,25 @@
+/**
+ * Flash Loan Module — Public API
+ *
+ * Exports the scanner (opportunity detection) and executor (transaction building)
+ * for Aave V3 flash loans.
+ *
+ * ⚠️ PRODUCTION NOTICE:
+ * Executing flash loans requires a deployed `FlashLoanExecutor.sol` contract.
+ * See `src/flash/contracts/FlashLoanExecutor.sol` for the Solidity scaffold.
+ *
+ * Quick start:
+ * ```typescript
+ * import { FlashOpportunityScanner, FlashLoanExecutor } from '@agentwallet/sdk/flash';
+ *
+ * const scanner = new FlashOpportunityScanner();
+ * const opportunities = await scanner.scanArbitrage({ tokens: ['WETH'], chain: 'base' });
+ *
+ * const executor = new FlashLoanExecutor({ chain: 'base', rpcUrl: '...' });
+ * const tx = executor.buildArbitrageTx(opportunities[0], wallet);
+ * await wallet.sendTransaction(tx);
+ * ```
+ */
+export { FlashOpportunityScanner } from './scanner.js';
+export { FlashLoanExecutor, AAVE_POOL_ABI, FLASH_EXECUTOR_ABI, AAVE_POOL_ADDRESSES } from './executor.js';
+//# sourceMappingURL=index.js.map

package/dist/flash/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/flash/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,EAAE,uBAAuB,EAAE,MAAM,cAAc,CAAC;AAGvD,OAAO,EAAE,iBAAiB,EAAE,aAAa,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC"}

package/dist/flash/scanner.d.ts

@@ -0,0 +1,133 @@
+/**
+ * Flash Loan Opportunity Scanner
+ *
+ * Scans for profitable flash loan opportunities across DEXs and lending protocols.
+ *
+ * ⚠️ PRODUCTION NOTICE:
+ * Real arbitrage scanning requires live DEX price quotes (SmartSwapRouter integration)
+ * and Aave borrower tracking (subgraph or event indexing). The methods below implement
+ * the full interface and calculation logic — wire in the SmartSwapRouter for live quotes.
+ */
+import type { ArbitrageOpportunity, LiquidationOpportunity, FlashScanResult } from './types.js';
+/** Parameters for DEX arbitrage scanning */
+export interface ScanArbitrageParams {
+    /** Token addresses or symbols to scan for price discrepancies */
+    tokens: string[];
+    /** Chain to scan on */
+    chain: string;
+    /**
+     * Notional trade size in USD used to measure price impact.
+     * Default: $10,000 — large enough to show real price differences.
+     */
+    amountUsd?: number;
+    /**
+     * Minimum net profit in basis points to report an opportunity.
+     * Default: 5 bps (0.05%). Filters noise from tiny spreads.
+     */
+    minNetProfitBps?: number;
+}
+/** Parameters for liquidation scanning */
+export interface ScanLiquidationsParams {
+    /** Chain to scan on */
+    chain: string;
+    /**
+     * Known borrower addresses to check for underwater positions.
+     * In production, populate this from Aave subgraph or event logs.
+     * If empty, returns an empty array.
+     */
+    borrowers?: string[];
+    /**
+     * Ethers provider for on-chain calls.
+     * If not provided, on-chain health factor checks are skipped.
+     */
+    provider?: import('ethers').JsonRpcProvider;
+    /**
+     * Minimum estimated profit (USD) to report a liquidation opportunity.
+     * Default: $50
+     */
+    minProfitUsd?: number;
+}
+/**
+ * Scans for flash loan opportunities: DEX arbitrage and protocol liquidations.
+ *
+ * **DEX Arbitrage**: Compares buy/sell prices across DEX aggregators.
+ * A spread exceeding the Aave flash loan fee (0.09%) + gas becomes a
+ * profitable arbitrage opportunity.
+ *
+ * **Liquidations**: Checks known borrowers' health factors on Aave V3.
+ * Positions with healthFactor < 1.0 are liquidatable; the liquidator
+ * receives a bonus (typically 5–10%) on the seized collateral.
+ *
+ * ⚠️ PRODUCTION NOTICE:
+ * Requires a deployed `FlashLoanExecutor.sol` to actually execute opportunities.
+ * See `src/flash/contracts/FlashLoanExecutor.sol`.
+ */
+export declare class FlashOpportunityScanner {
+    /**
+     * Scan for DEX arbitrage opportunities across a token list.
+     *
+     * Algorithm:
+     * 1. For each token, simulate buying $amountUsd on each available DEX aggregator
+     * 2. Simulate selling the same amount on each DEX aggregator
+     * 3. Compute the spread: (bestSell - bestBuy) / bestBuy * 10000 (bps)
+     * 4. Subtract Aave flash loan fee (9 bps) and estimated gas cost
+     * 5. Return opportunities where netProfitBps > minNetProfitBps, sorted desc
+     *
+     * In production, wire `SmartSwapRouter.getQuote()` to fetch real DEX prices.
+     * Without live quotes, returns an empty array (no false positives).
+     *
+     * @param params - Scan configuration
+     * @returns Viable arbitrage opportunities sorted by netProfitBps descending
+     */
+    scanArbitrage(params: ScanArbitrageParams): Promise<ArbitrageOpportunity[]>;
+    /**
+     * Check for liquidation opportunities on Aave V3.
+     *
+     * Algorithm:
+     * 1. For each known borrower address, call getUserAccountData() on Aave Pool
+     * 2. If healthFactor < 1e18 (i.e., < 1.0 in 18-decimal representation) → liquidatable
+     * 3. Estimate profit: debtToRepay × liquidationBonus%
+     * 4. Return opportunities where estimatedProfitUsd > minProfitUsd
+     *
+     * ⚠️ PRODUCTION NOTICE:
+     * This requires tracking active Aave borrowers via:
+     *   - Aave subgraph (https://thegraph.com/explorer/subgraphs/...)
+     *   - Indexing Borrow events from the Aave Pool contract
+     * Without a borrower list, returns empty array.
+     *
+     * @param params - Scan configuration
+     * @returns Liquidatable positions sorted by estimatedProfitUsd descending
+     */
+    scanLiquidations(params: ScanLiquidationsParams): Promise<LiquidationOpportunity[]>;
+    /**
+     * Run a full scan: both DEX arbitrage and liquidations.
+     * Returns a FlashScanResult with the best opportunity highlighted.
+     */
+    scan(arbitrageParams: ScanArbitrageParams, liquidationParams?: ScanLiquidationsParams): Promise<FlashScanResult>;
+    /**
+     * Calculate net profit in basis points for an arbitrage opportunity.
+     * Public helper used by tests and external callers.
+     *
+     * @param grossProfitBps - Raw spread between buy and sell price
+     * @param flashLoanFeeBps - Flash loan fee (default: 9 for Aave V3)
+     * @param gasBps - Estimated gas as % of trade size (default: 10 bps)
+     */
+    static calcNetProfitBps(grossProfitBps: number, flashLoanFeeBps?: number, gasBps?: number): number;
+    /**
+     * Build an ArbitrageOpportunity object from raw price data.
+     * Useful for testing the scanner logic without live DEX quotes.
+     */
+    static buildArbitrageOpportunity(params: {
+        token: string;
+        tokenAddress: string;
+        amount: bigint;
+        buyDex: string;
+        buyPrice: bigint;
+        sellDex: string;
+        sellPrice: bigint;
+        chain: string;
+        amountUsd?: number;
+        gasBps?: number;
+    }): ArbitrageOpportunity;
+}
+//# sourceMappingURL=scanner.d.ts.map

package/dist/flash/scanner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scanner.d.ts","sourceRoot":"","sources":["../../src/flash/scanner.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EACV,oBAAoB,EACpB,sBAAsB,EACtB,eAAe,EAEhB,MAAM,YAAY,CAAC;AAqCpB,4CAA4C;AAC5C,MAAM,WAAW,mBAAmB;IAClC,iEAAiE;IACjE,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,uBAAuB;IACvB,KAAK,EAAE,MAAM,CAAC;IACd;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;OAGG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,0CAA0C;AAC1C,MAAM,WAAW,sBAAsB;IACrC,uBAAuB;IACvB,KAAK,EAAE,MAAM,CAAC;IACd;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB;;;OAGG;IACH,QAAQ,CAAC,EAAE,OAAO,QAAQ,EAAE,eAAe,CAAC;IAC5C;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;;;;;;;;;;;;;GAcG;AACH,qBAAa,uBAAuB;IAClC;;;;;;;;;;;;;;;OAeG;IACG,aAAa,CAAC,MAAM,EAAE,mBAAmB,GAAG,OAAO,CAAC,oBAAoB,EAAE,CAAC;IAsCjF;;;;;;;;;;;;;;;;;OAiBG;IACG,gBAAgB,CAAC,MAAM,EAAE,sBAAsB,GAAG,OAAO,CAAC,sBAAsB,EAAE,CAAC;IA4BzF;;;OAGG;IACG,IAAI,CACR,eAAe,EAAE,mBAAmB,EACpC,iBAAiB,CAAC,EAAE,sBAAsB,GACzC,OAAO,CAAC,eAAe,CAAC;IAoC3B;;;;;;;OAOG;IACH,MAAM,CAAC,gBAAgB,CACrB,cAAc,EAAE,MAAM,EACtB,eAAe,GAAE,MAA2B,EAC5C,MAAM,GAAE,MAAiC,GACxC,MAAM;IAIT;;;OAGG;IACH,MAAM,CAAC,yBAAyB,CAAC,MAAM,EAAE;QACvC,KAAK,EAAE,MAAM,CAAC;QACd,YAAY,EAAE,MAAM,CAAC;QACrB,MAAM,EAAE,MAAM,CAAC;QACf,MAAM,EAAE,MAAM,CAAC;QACf,QAAQ,EAAE,MAAM,CAAC;QACjB,OAAO,EAAE,MAAM,CAAC;QAChB,SAAS,EAAE,MAAM,CAAC;QAClB,KAAK,EAAE,MAAM,CAAC;QACd,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,MAAM,CAAC,EAAE,MAAM,CAAC;KACjB,GAAG,oBAAoB;CAkCzB"}