Initial commit: add .gitignore and README

docs/GUARD_DEVELOPMENT_GUIDE.md

@@ -0,0 +1,146 @@
+# Guard Development Guide
+
+## Overview
+
+Guards are safety checks that prevent unsafe strategy execution. This guide explains how to create custom guards.
+
+## Guard Structure
+
+A guard consists of:
+1. Schema definition (in `strategy.schema.ts`)
+2. Evaluation function (in `src/guards/`)
+3. Integration (in `src/planner/guards.ts`)
+
+## Creating a Guard
+
+### 1. Define Guard Schema
+
+Add to `src/strategy.schema.ts`:
+
+```typescript
+// Add to GuardSchema type enum
+"customGuard",
+
+// Guard params are defined in the guard evaluation function
+```
+
+### 2. Create Guard File
+
+Create `src/guards/customGuard.ts`:
+
+```typescript
+import { Guard } from "../strategy.schema.js";
+
+export interface CustomGuardParams {
+  threshold: string;
+  // Add guard-specific parameters
+}
+
+/**
+ * Evaluate custom guard
+ * 
+ * @param guard - Guard definition
+ * @param context - Execution context
+ * @returns Guard evaluation result
+ */
+export function evaluateCustomGuard(
+  guard: Guard,
+  context: {
+    // Add context properties needed for evaluation
+    [key: string]: any;
+  }
+): { passed: boolean; reason?: string; [key: string]: any } {
+  const params = guard.params as CustomGuardParams;
+  const threshold = BigInt(params.threshold);
+
+  // Perform check
+  const value = context.value || 0n;
+  const passed = value <= threshold;
+
+  return {
+    passed,
+    reason: passed ? undefined : `Value ${value} exceeds threshold ${threshold}`,
+    value,
+    threshold,
+  };
+}
+```
+
+### 3. Integrate Guard
+
+Add to `src/planner/guards.ts`:
+
+```typescript
+import { evaluateCustomGuard } from "../guards/customGuard.js";
+
+// Add case in evaluateGuard function
+case "customGuard":
+  result = evaluateCustomGuard(guard, context);
+  break;
+```
+
+## Guard Context
+
+The context object provides access to:
+- `oracle`: PriceOracle instance
+- `aave`: AaveV3Adapter instance
+- `uniswap`: UniswapV3Adapter instance
+- `gasEstimate`: GasEstimate
+- `chainName`: Chain name
+- Custom properties from execution context
+
+## Guard Failure Actions
+
+Guards support three failure actions:
+
+- `revert`: Stop execution (default)
+- `warn`: Log warning but continue
+- `skip`: Skip the step
+
+## Examples
+
+### Existing Guards
+
+- `oracleSanity.ts`: Price validation
+- `twapSanity.ts`: TWAP price checks
+- `maxGas.ts`: Gas limits
+- `minHealthFactor.ts`: Health factor checks
+- `slippage.ts`: Slippage protection
+- `positionDeltaLimit.ts`: Position size limits
+
+## Best Practices
+
+1. **Clear Error Messages**: Provide actionable error messages
+2. **Context Validation**: Check required context properties
+3. **Thresholds**: Use configurable thresholds
+4. **Documentation**: Document all parameters
+5. **Testing**: Write comprehensive tests
+
+## Testing
+
+Create test file `tests/unit/guards/customGuard.test.ts`:
+
+```typescript
+import { describe, it, expect } from "vitest";
+import { evaluateCustomGuard } from "../../../src/guards/customGuard.js";
+import { Guard } from "../../../src/strategy.schema.js";
+
+describe("Custom Guard", () => {
+  it("should pass when value is within threshold", () => {
+    const guard: Guard = {
+      type: "customGuard",
+      params: {
+        threshold: "1000000",
+      },
+    };
+
+    const context = {
+      value: 500000n,
+    };
+
+    const result = evaluateCustomGuard(guard, context);
+    expect(result.passed).toBe(true);
+  });
+});
+```
+