@cfxdevkit/executor 0.1.0 → 1.0.5

package/README.md

@@ -0,0 +1,132 @@
+# @cfxdevkit/executor
+
+On-chain strategy execution engine for Conflux DevKit — the runtime primitives for building keepers, bots, or AI agents that execute limit orders, DCA, TWAP, and spot swaps on Conflux eSpace.
+
+## Features
+
+- **`Executor`** — Orchestrator that evaluates jobs on a tick interval, checks price conditions, enforces safety limits, and submits on-chain transactions.
+- **`KeeperClientImpl`** — viem-based client that wraps the `AutomationManager` contract for job creation, cancellation, and forceful execution.
+- **`SafetyGuard`** — Circuit-breaker with configurable per-tick swap caps, per-job retry caps, and a global circuit-breaker on consecutive failures.
+- **`RetryQueue`** — Exponential backoff with jitter for failed job retries.
+- **`PriceChecker`** — Pluggable price source interface + condition evaluator (`gte`/`lte` against a target price).
+- **Full type system** — `Job` union type with per-strategy params (`LimitOrderJob`, `DCAJob`, `TWAPJob`, `SwapJob`) and lifecycle statuses.
+- **Zero framework coupling** — Injectable `AutomationLogger` interface; no React, no HTTP framework required.
+
+## Supported strategies
+
+| Strategy | Status |
+|---|---|
+| Limit order | ✅ Implemented |
+| DCA (Dollar-Cost Averaging) | ✅ Implemented |
+| TWAP | 🔜 Types only (contract support pending) |
+| Spot swap | 🔜 Types only (contract support pending) |
+
+## Installation
+
+```bash
+pnpm add @cfxdevkit/executor
+# or
+npm install @cfxdevkit/executor
+```
+
+## Peer dependencies
+
+```json
+{
+  "viem": ">=2.0.0"
+}
+```
+
+## Usage
+
+### Basic keeper setup
+
+```ts
+import { Executor, KeeperClientImpl, SafetyGuard, PriceChecker, noopLogger } from '@cfxdevkit/executor';
+import { createWalletClient, http } from 'viem';
+import { confluxESpace } from 'viem/chains';
+import { privateKeyToAccount } from 'viem/accounts';
+
+const account = privateKeyToAccount('0x...');
+const walletClient = createWalletClient({ account, chain: confluxESpace, transport: http() });
+
+const keeperClient = new KeeperClientImpl({
+  walletClient,
+  automationManagerAddress: '0x...',
+});
+
+const safetyGuard = new SafetyGuard({
+  maxSwapsPerTick: 3,
+  maxConsecutiveFailures: 5,
+  maxRetriesPerJob: 4,
+});
+
+const priceChecker = new PriceChecker({
+  priceSource: myPriceSource,   // implement PriceSource interface
+  decimalsResolver: myResolver, // implement DecimalsResolver interface
+});
+
+const executor = new Executor({
+  keeperClient,
+  safetyGuard,
+  priceChecker,
+  jobStore: myJobStore,         // implement JobStore interface
+  logger: noopLogger,           // or inject your own AutomationLogger
+  tickIntervalMs: 15_000,       // evaluate jobs every 15 s
+});
+
+executor.start();
+```
+
+### Creating a limit order job
+
+```ts
+import type { LimitOrderStrategy } from '@cfxdevkit/executor';
+
+const strategy: LimitOrderStrategy = {
+  kind: 'limit_order',
+  tokenIn: '0xCFX...',
+  tokenOut: '0xUSDT...',
+  amountIn: '100.0',       // human-readable
+  targetPrice: '0.38',     // trigger when price >= target
+  direction: 'gte',
+  slippageBps: 50,         // 0.5%
+  expiresInDays: 7,
+};
+
+await executor.createJob(strategy, ownerAddress);
+```
+
+### Creating a DCA job
+
+```ts
+import type { DCAStrategy } from '@cfxdevkit/executor';
+
+const strategy: DCAStrategy = {
+  kind: 'dca',
+  tokenIn: '0xUSDT...',
+  tokenOut: '0xCFX...',
+  amountPerSwap: '50.0',   // human-readable, per interval
+  intervalHours: 24,
+  totalSwaps: 30,
+  slippageBps: 100,        // 1%
+};
+
+await executor.createJob(strategy, ownerAddress);
+```
+
+## Job lifecycle
+
+```
+pending → active → executed
+                 ↘ failed (exhausted retries)
+       → cancelled (user-cancelled)
+       → paused    (SafetyGuard circuit-breaker)
+```
+
+## Conflux Compatibility
+
+| Network | Chain ID | Support |
+|---|---|---|
+| Conflux eSpace Mainnet | 1030 | ✅ |
+| Conflux eSpace Testnet | 71 | ✅ |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cfxdevkit/executor",
-  "version": "0.1.0",
+  "version": "1.0.5",
   "description": "Conflux DevKit – on-chain strategy execution engine (limit orders, DCA, and more)",
   "type": "module",
   "main": "dist/index.js",
@@ -22,10 +22,26 @@
     },
     "./package.json": "./package.json"
   },
+  "scripts": {
+    "build": "tsup",
+    "build:watch": "tsup --watch",
+    "type-check": "tsc --noEmit",
+    "dev": "tsup --watch",
+    "test": "vitest run --pass-with-no-tests",
+    "test:run": "vitest --run",
+    "test:coverage": "vitest --run --coverage --pass-with-no-tests",
+    "clean": "rm -rf dist",
+    "lint": "biome lint src/",
+    "lint:fix": "biome lint --write src/",
+    "format": "biome format src/",
+    "format:fix": "biome format --write src/",
+    "check": "biome check src/",
+    "check:fix": "biome check --write src/"
+  },
   "dependencies": {
-    "viem": ">=2.0.0",
-    "@cfxdevkit/core": "0.1.0",
-    "@cfxdevkit/protocol": "0.1.0"
+    "@cfxdevkit/core": "workspace:*",
+    "@cfxdevkit/protocol": "workspace:*",
+    "viem": ">=2.0.0"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.3.10",
@@ -48,29 +64,14 @@
   ],
   "author": "Conflux DevKit Team",
   "license": "Apache-2.0",
+  "packageManager": "pnpm@10.11.0",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/cfxdevkit/conflux-devkit.git",
+    "url": "git+https://github.com/cfxdevkit/devkit.git",
     "directory": "packages/executor"
   },
   "homepage": "https://github.com/cfxdevkit/conflux-devkit#readme",
   "bugs": {
-    "url": "https://github.com/cfxdevkit/conflux-devkit/issues"
-  },
-  "scripts": {
-    "build": "tsup",
-    "build:watch": "tsup --watch",
-    "type-check": "tsc --noEmit",
-    "dev": "tsup --watch",
-    "test": "vitest run --pass-with-no-tests",
-    "test:run": "vitest --run",
-    "test:coverage": "vitest --run --coverage",
-    "clean": "rm -rf dist",
-    "lint": "biome lint src/",
-    "lint:fix": "biome lint --write src/",
-    "format": "biome format src/",
-    "format:fix": "biome format --write src/",
-    "check": "biome check src/",
-    "check:fix": "biome check --write src/"
+    "url": "https://github.com/cfxdevkit/devkit/issues"
   }
-}
+}