strategic/docs/PROTOCOL_INTEGRATION_GUIDE.md

# 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.