@ael-protocol/sdk 0.1.0

package/README.md

@@ -0,0 +1,252 @@
+# @ael-protocol/sdk
+
+**AEL SDK** - Intent-based trading execution for AI Agents on Base.
+
+AEL (Agent Execution Layer) enables AI agents to execute on-chain trades through a simple intent-based API. Submit your trading intent, and Solvers compete to execute it at the best price.
+
+## Installation
+
+```bash
+npm install @ael-protocol/sdk viem
+```
+
+## Quick Start (6 Lines)
+
+```typescript
+import { AEL, BASE_MAINNET, ETH_ADDRESS } from '@ael-protocol/sdk';
+import { base } from 'viem/chains';
+import { parseEther, parseUnits } from 'viem';
+
+// Recommend using Alchemy or Infura RPC for production
+const ael = new AEL({ privateKey: '0x...', routerAddress: BASE_MAINNET.AEL_ROUTER, chain: base, rpcUrl: process.env.BASE_RPC_URL || 'https://mainnet.base.org' });
+const result = await ael.swap({ tokenIn: ETH_ADDRESS, tokenOut: BASE_MAINNET.USDC, amountIn: parseEther('0.1'), minAmountOut: parseUnits('200', 6) });
+const status = await ael.waitForSettlement(result.intentHash);
+```
+
+## Contract Addresses
+
+### Base Mainnet (Chain ID: 8453)
+
+| Contract | Address |
+|----------|---------|
+| Router | `0x85977BD37d8100F81566A1c6815047f5557bCDCB` |
+| SolverRegistry | `0xd14D394631C32Ea35fFF8407157C6867bCc8E946` |
+| FeeVault | `0xF8E3646b03a83465D6DAE65edbF380C77feb5DE0` |
+
+### Base Sepolia (Chain ID: 84532)
+
+| Contract | Address |
+|----------|---------|
+| Router | `0x83A260939cF1326E9aa94eF6c814F2Fd876535e8` |
+| SolverRegistry | `0xC69A90904B44297af5fC7C554d7ca37612Ef01B3` |
+| FeeVault | `0xAec32AbD0233a124B7D0A17055fB40a50442E088` |
+
+## API Reference
+
+### `new AEL(config)`
+
+Create a new AEL instance.
+
+```typescript
+interface AELConfig {
+  privateKey: `0x${string}`;    // Agent's private key
+  routerAddress: `0x${string}`; // AEL Router address
+  chain: Chain;                 // viem chain object (base or baseSepolia)
+  rpcUrl: string;               // RPC endpoint URL
+}
+
+// Recommend using Alchemy or Infura RPC for production
+const ael = new AEL({
+  privateKey: process.env.PRIVATE_KEY as `0x${string}`,
+  routerAddress: BASE_MAINNET.AEL_ROUTER,
+  chain: base,
+  rpcUrl: process.env.BASE_RPC_URL || 'https://mainnet.base.org',
+});
+```
+
+### `ael.swap(params): Promise<SwapResult>`
+
+Submit a swap intent. Handles EIP-712 signing and ERC20 approval automatically.
+
+```typescript
+interface SwapParams {
+  tokenIn: `0x${string}`;      // Input token (use ETH_ADDRESS for ETH)
+  tokenOut: `0x${string}`;     // Output token address
+  amountIn: bigint;            // Amount to swap (in wei)
+  minAmountOut: bigint;        // Minimum output (slippage protection)
+  deadline?: bigint;           // Optional deadline (default: 1 hour)
+}
+
+interface SwapResult {
+  intentHash: `0x${string}`;   // Unique intent identifier
+  txHash: `0x${string}`;       // Transaction hash
+  status: IntentStatus;        // 'Pending'
+}
+
+// Example
+const result = await ael.swap({
+  tokenIn: ETH_ADDRESS,
+  tokenOut: BASE_MAINNET.USDC,
+  amountIn: parseEther('0.1'),
+  minAmountOut: parseUnits('200', 6),
+});
+```
+
+### `ael.quote(tokenIn, tokenOut, amountIn): Promise<QuoteResult | null>`
+
+Get a price quote from Uniswap V3. Tries all fee tiers (0.05%, 0.3%, 1%) and returns the best.
+
+```typescript
+interface QuoteResult {
+  amountOut: bigint;    // Expected output amount
+  priceImpact: number;  // Price impact percentage
+  fee: number;          // Pool fee tier (500, 3000, or 10000)
+}
+
+const quote = await ael.quote(ETH_ADDRESS, BASE_MAINNET.USDC, parseEther('1'));
+if (quote) {
+  console.log('Expected:', quote.amountOut, 'Fee tier:', quote.fee);
+}
+```
+
+### `ael.cancel(intentHash): Promise<Hash>`
+
+Cancel a pending intent and get refunded. Only works after 30-second lock period.
+
+```typescript
+const txHash = await ael.cancel(intentHash);
+```
+
+### `ael.getStatus(intentHash): Promise<IntentStatus>`
+
+Check the current status of an intent.
+
+```typescript
+enum IntentStatus {
+  None = 0,      // Intent doesn't exist
+  Pending = 1,   // Waiting for Solver
+  Settled = 2,   // Successfully executed
+  Refunded = 3,  // Cancelled or failed
+  Expired = 4,   // Deadline passed
+}
+
+const status = await ael.getStatus(intentHash);
+```
+
+### `ael.waitForSettlement(intentHash, timeoutMs?): Promise<IntentStatus>`
+
+Poll until intent is settled, refunded, or expired. Default timeout: 60 seconds.
+
+```typescript
+const finalStatus = await ael.waitForSettlement(intentHash, 120000);
+if (finalStatus === IntentStatus.Settled) {
+  console.log('Trade executed!');
+}
+```
+
+### `ael.address`
+
+Get the agent's wallet address.
+
+```typescript
+console.log('Agent:', ael.address);
+```
+
+## Constants
+
+```typescript
+import { BASE_MAINNET, BASE_SEPOLIA, ETH_ADDRESS } from '@ael-protocol/sdk';
+
+// Mainnet
+BASE_MAINNET.AEL_ROUTER  // Router contract
+BASE_MAINNET.USDC        // 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913
+BASE_MAINNET.WETH        // 0x4200000000000000000000000000000000000006
+
+// Testnet
+BASE_SEPOLIA.AEL_ROUTER  // Router contract
+BASE_SEPOLIA.USDC        // 0x036CbD53842c5426634e7929541eC2318f3dCF7e
+
+// Native ETH
+ETH_ADDRESS              // 0x0000000000000000000000000000000000000000
+```
+
+## Intent Lifecycle
+
+```
+[Agent] submitIntent() --> [Pending] --> [Solver] settle() --> [Settled]
+                              |
+                              +--> [Agent] cancel() --> [Refunded]
+                              |
+                              +--> deadline passed --> [Expired]
+```
+
+## Fee Structure
+
+- Protocol fee: **2 basis points (0.02%)** on input token
+- Fee distribution:
+  - **70%** to Solver (execution reward)
+  - **20%** to Protocol Treasury
+  - **10%** to Governance Fund
+
+## Complete Example
+
+```typescript
+import { AEL, BASE_MAINNET, ETH_ADDRESS, IntentStatus } from '@ael-protocol/sdk';
+import { base } from 'viem/chains';
+import { parseEther, parseUnits, formatUnits } from 'viem';
+
+async function main() {
+  // Recommend using Alchemy or Infura RPC for production
+  const ael = new AEL({
+    privateKey: process.env.PRIVATE_KEY as `0x${string}`,
+    routerAddress: BASE_MAINNET.AEL_ROUTER,
+    chain: base,
+    rpcUrl: process.env.BASE_RPC_URL || 'https://mainnet.base.org',
+  });
+
+  console.log('Agent:', ael.address);
+
+  // Get quote
+  const quote = await ael.quote(ETH_ADDRESS, BASE_MAINNET.USDC, parseEther('0.1'));
+  if (!quote) throw new Error('No liquidity');
+
+  console.log('Quote:', formatUnits(quote.amountOut, 6), 'USDC');
+
+  // Swap with 2% slippage
+  const minOut = quote.amountOut * 98n / 100n;
+  const result = await ael.swap({
+    tokenIn: ETH_ADDRESS,
+    tokenOut: BASE_MAINNET.USDC,
+    amountIn: parseEther('0.1'),
+    minAmountOut: minOut,
+  });
+
+  console.log('Intent:', result.intentHash);
+
+  // Wait for settlement
+  const status = await ael.waitForSettlement(result.intentHash, 60000);
+  console.log('Status:', IntentStatus[status]);
+}
+
+main().catch(console.error);
+```
+
+## Error Handling
+
+```typescript
+try {
+  await ael.swap({...});
+} catch (error) {
+  if (error.message.includes('DepositCapExceeded')) {
+    // Protocol deposit limit reached
+  } else if (error.message.includes('InsufficientOutput')) {
+    // Slippage protection triggered
+  } else if (error.message.includes('InvalidDeadline')) {
+    // Deadline too short or too long
+  }
+}
+```
+
+## License
+
+MIT

package/dist/abi.d.ts

@@ -0,0 +1,287 @@
+/**
+ * AEL Router ABI
+ */
+export declare const ROUTER_ABI: readonly [{
+    readonly type: "event";
+    readonly name: "IntentSubmitted";
+    readonly inputs: readonly [{
+        readonly name: "intentHash";
+        readonly type: "bytes32";
+        readonly indexed: true;
+    }, {
+        readonly name: "agent";
+        readonly type: "address";
+        readonly indexed: true;
+    }, {
+        readonly name: "tokenIn";
+        readonly type: "address";
+        readonly indexed: false;
+    }, {
+        readonly name: "tokenOut";
+        readonly type: "address";
+        readonly indexed: false;
+    }, {
+        readonly name: "amountIn";
+        readonly type: "uint256";
+        readonly indexed: false;
+    }, {
+        readonly name: "minAmountOut";
+        readonly type: "uint256";
+        readonly indexed: false;
+    }, {
+        readonly name: "deadline";
+        readonly type: "uint256";
+        readonly indexed: false;
+    }];
+}, {
+    readonly type: "event";
+    readonly name: "IntentSettled";
+    readonly inputs: readonly [{
+        readonly name: "intentHash";
+        readonly type: "bytes32";
+        readonly indexed: true;
+    }, {
+        readonly name: "solver";
+        readonly type: "address";
+        readonly indexed: true;
+    }, {
+        readonly name: "amountOut";
+        readonly type: "uint256";
+        readonly indexed: false;
+    }, {
+        readonly name: "fee";
+        readonly type: "uint256";
+        readonly indexed: false;
+    }];
+}, {
+    readonly type: "event";
+    readonly name: "IntentCancelled";
+    readonly inputs: readonly [{
+        readonly name: "intentHash";
+        readonly type: "bytes32";
+        readonly indexed: true;
+    }];
+}, {
+    readonly type: "event";
+    readonly name: "IntentExpired";
+    readonly inputs: readonly [{
+        readonly name: "intentHash";
+        readonly type: "bytes32";
+        readonly indexed: true;
+    }];
+}, {
+    readonly type: "function";
+    readonly name: "submitIntent";
+    readonly inputs: readonly [{
+        readonly name: "intent";
+        readonly type: "tuple";
+        readonly components: readonly [{
+            readonly name: "agent";
+            readonly type: "address";
+        }, {
+            readonly name: "tokenIn";
+            readonly type: "address";
+        }, {
+            readonly name: "tokenOut";
+            readonly type: "address";
+        }, {
+            readonly name: "amountIn";
+            readonly type: "uint256";
+        }, {
+            readonly name: "minAmountOut";
+            readonly type: "uint256";
+        }, {
+            readonly name: "deadline";
+            readonly type: "uint256";
+        }, {
+            readonly name: "nonce";
+            readonly type: "uint256";
+        }, {
+            readonly name: "signature";
+            readonly type: "bytes";
+        }];
+    }];
+    readonly outputs: readonly [{
+        readonly name: "intentHash";
+        readonly type: "bytes32";
+    }];
+    readonly stateMutability: "payable";
+}, {
+    readonly type: "function";
+    readonly name: "cancelIntent";
+    readonly inputs: readonly [{
+        readonly name: "intentHash";
+        readonly type: "bytes32";
+    }];
+    readonly outputs: readonly [];
+    readonly stateMutability: "nonpayable";
+}, {
+    readonly type: "function";
+    readonly name: "getIntentStatus";
+    readonly inputs: readonly [{
+        readonly name: "intentHash";
+        readonly type: "bytes32";
+    }];
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "uint8";
+    }];
+    readonly stateMutability: "view";
+}, {
+    readonly type: "function";
+    readonly name: "getNonce";
+    readonly inputs: readonly [{
+        readonly name: "agent";
+        readonly type: "address";
+    }];
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "uint256";
+    }];
+    readonly stateMutability: "view";
+}, {
+    readonly type: "function";
+    readonly name: "domainSeparator";
+    readonly inputs: readonly [];
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "bytes32";
+    }];
+    readonly stateMutability: "view";
+}, {
+    readonly type: "function";
+    readonly name: "intents";
+    readonly inputs: readonly [{
+        readonly name: "intentHash";
+        readonly type: "bytes32";
+    }];
+    readonly outputs: readonly [{
+        readonly name: "agent";
+        readonly type: "address";
+    }, {
+        readonly name: "tokenIn";
+        readonly type: "address";
+    }, {
+        readonly name: "tokenOut";
+        readonly type: "address";
+    }, {
+        readonly name: "amountIn";
+        readonly type: "uint256";
+    }, {
+        readonly name: "minAmountOut";
+        readonly type: "uint256";
+    }, {
+        readonly name: "deadline";
+        readonly type: "uint256";
+    }, {
+        readonly name: "status";
+        readonly type: "uint8";
+    }];
+    readonly stateMutability: "view";
+}];
+/**
+ * ERC20 ABI
+ */
+export declare const ERC20_ABI: readonly [{
+    readonly type: "function";
+    readonly name: "approve";
+    readonly inputs: readonly [{
+        readonly name: "spender";
+        readonly type: "address";
+    }, {
+        readonly name: "amount";
+        readonly type: "uint256";
+    }];
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "bool";
+    }];
+    readonly stateMutability: "nonpayable";
+}, {
+    readonly type: "function";
+    readonly name: "allowance";
+    readonly inputs: readonly [{
+        readonly name: "owner";
+        readonly type: "address";
+    }, {
+        readonly name: "spender";
+        readonly type: "address";
+    }];
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "uint256";
+    }];
+    readonly stateMutability: "view";
+}, {
+    readonly type: "function";
+    readonly name: "balanceOf";
+    readonly inputs: readonly [{
+        readonly name: "account";
+        readonly type: "address";
+    }];
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "uint256";
+    }];
+    readonly stateMutability: "view";
+}, {
+    readonly type: "function";
+    readonly name: "decimals";
+    readonly inputs: readonly [];
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "uint8";
+    }];
+    readonly stateMutability: "view";
+}, {
+    readonly type: "function";
+    readonly name: "symbol";
+    readonly inputs: readonly [];
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "string";
+    }];
+    readonly stateMutability: "view";
+}];
+/**
+ * Uniswap V3 Quoter ABI
+ */
+export declare const QUOTER_ABI: readonly [{
+    readonly type: "function";
+    readonly name: "quoteExactInputSingle";
+    readonly inputs: readonly [{
+        readonly name: "params";
+        readonly type: "tuple";
+        readonly components: readonly [{
+            readonly name: "tokenIn";
+            readonly type: "address";
+        }, {
+            readonly name: "tokenOut";
+            readonly type: "address";
+        }, {
+            readonly name: "amountIn";
+            readonly type: "uint256";
+        }, {
+            readonly name: "fee";
+            readonly type: "uint24";
+        }, {
+            readonly name: "sqrtPriceLimitX96";
+            readonly type: "uint160";
+        }];
+    }];
+    readonly outputs: readonly [{
+        readonly name: "amountOut";
+        readonly type: "uint256";
+    }, {
+        readonly name: "sqrtPriceX96After";
+        readonly type: "uint160";
+    }, {
+        readonly name: "initializedTicksCrossed";
+        readonly type: "uint32";
+    }, {
+        readonly name: "gasEstimate";
+        readonly type: "uint256";
+    }];
+    readonly stateMutability: "nonpayable";
+}];
+//# sourceMappingURL=abi.d.ts.map

package/dist/abi.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"abi.d.ts","sourceRoot":"","sources":["../src/abi.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,eAAO,MAAM,UAAU;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAyGb,CAAC;AAEX;;GAEG;AACH,eAAO,MAAM,SAAS;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA0CZ,CAAC;AAEX;;GAEG;AACH,eAAO,MAAM,UAAU;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAyBb,CAAC"}