Initial commit: add .gitignore and README

docs/PROTOCOL_INTEGRATION_GUIDE.md

@@ -0,0 +1,132 @@
+# Protocol Integration Guide
+
+## Overview
+
+This guide explains how to add support for new DeFi protocols to the Strategic executor.
+
+## Integration Steps
+
+### 1. Create Adapter
+
+Create a new adapter file in `src/adapters/`:
+
+```typescript
+// src/adapters/newProtocol.ts
+import { Contract, JsonRpcProvider, Wallet } from "ethers";
+import { getChainConfig } from "../config/chains.js";
+
+const PROTOCOL_ABI = [
+  "function deposit(uint256 amount) external",
+  // Add required ABI functions
+];
+
+export class NewProtocolAdapter {
+  private contract: Contract;
+  private provider: JsonRpcProvider;
+  private signer?: Wallet;
+
+  constructor(chainName: string, signer?: Wallet) {
+    const config = getChainConfig(chainName);
+    this.provider = new JsonRpcProvider(config.rpcUrl);
+    this.signer = signer;
+
+    this.contract = new Contract(
+      config.protocols.newProtocol?.address,
+      PROTOCOL_ABI,
+      signer || this.provider
+    );
+  }
+
+  async deposit(amount: bigint): Promise<string> {
+    if (!this.signer) {
+      throw new Error("Signer required");
+    }
+    const tx = await this.contract.deposit(amount);
+    return tx.hash;
+  }
+}
+```
+
+### 2. Add to Chain Config
+
+Update `src/config/chains.ts`:
+
+```typescript
+protocols: {
+  // ... existing protocols
+  newProtocol: {
+    address: "0x...",
+  },
+}
+```
+
+### 3. Add to Schema
+
+Update `src/strategy.schema.ts`:
+
+```typescript
+z.object({
+  type: z.literal("newProtocol.deposit"),
+  amount: z.union([z.string(), z.object({ blind: z.string() })]),
+}),
+```
+
+### 4. Add to Compiler
+
+Update `src/planner/compiler.ts`:
+
+```typescript
+// Import adapter
+import { NewProtocolAdapter } from "../adapters/newProtocol.js";
+
+// Add to class
+private newProtocol?: NewProtocolAdapter;
+
+// Initialize in constructor
+if (config.protocols.newProtocol) {
+  this.newProtocol = new NewProtocolAdapter(chainName);
+}
+
+// Add case in compileStep
+case "newProtocol.deposit": {
+  if (!this.newProtocol) throw new Error("NewProtocol adapter not available");
+  const action = step.action as Extract<StepAction, { type: "newProtocol.deposit" }>;
+  const amount = BigInt(action.amount);
+  const iface = this.newProtocol["contract"].interface;
+  const data = iface.encodeFunctionData("deposit", [amount]);
+  calls.push({
+    to: getChainConfig(this.chainName).protocols.newProtocol!.address,
+    data,
+    description: `NewProtocol deposit ${amount}`,
+  });
+  break;
+}
+```
+
+### 5. Add Tests
+
+Create test file `tests/unit/adapters/newProtocol.test.ts`:
+
+```typescript
+import { describe, it, expect } from "vitest";
+import { NewProtocolAdapter } from "../../../src/adapters/newProtocol.js";
+
+describe("NewProtocol Adapter", () => {
+  it("should deposit", async () => {
+    // Test implementation
+  });
+});
+```
+
+## Best Practices
+
+1. **Error Handling**: Always validate inputs and handle errors gracefully
+2. **Event Parsing**: Parse events for return values when possible
+3. **Gas Estimation**: Provide accurate gas estimates
+4. **Documentation**: Document all methods and parameters
+5. **Testing**: Write comprehensive tests
+
+## Example: Complete Integration
+
+See existing adapters like `src/adapters/aaveV3.ts` for complete examples.
+