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/:

// 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:

protocols: {
  // ... existing protocols
  newProtocol: {
    address: "0x...",
  },
}

3. Add to Schema

Update src/strategy.schema.ts:

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:

// 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:

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.