@cfxdevkit/executor 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,425 @@
+import { Address, createWalletClient } from 'viem';
+
+/**
+ * Minimal injectable logger interface for the automation module.
+ *
+ * The SDK ships with NO logging dependency. Consumers can pass any compatible
+ * logger (pino, winston, console wrapper …) or omit it to get silent behaviour.
+ */
+interface AutomationLogger {
+    info(msg: string | object, ...args: unknown[]): void;
+    warn(msg: string | object, ...args: unknown[]): void;
+    debug(msg: string | object, ...args: unknown[]): void;
+    error(msg: string | object, ...args: unknown[]): void;
+}
+/** Default no-op logger — used when no logger is supplied. */
+declare const noopLogger: AutomationLogger;
+
+type JobStatus = 'pending' | 'active' | 'executed' | 'cancelled' | 'failed' | 'paused';
+type JobType = 'limit_order' | 'dca' | 'twap' | 'swap';
+interface BaseJob {
+    id: string;
+    owner: string;
+    type: JobType;
+    status: JobStatus;
+    /** bytes32 hex jobId from the on-chain JobCreated event (0x-prefixed) */
+    onChainJobId: string | null;
+    createdAt: number;
+    updatedAt: number;
+    expiresAt: number | null;
+    retries: number;
+    maxRetries: number;
+    lastError: string | null;
+}
+interface LimitOrderJob extends BaseJob {
+    type: 'limit_order';
+    params: LimitOrderParams;
+}
+interface DCAJob extends BaseJob {
+    type: 'dca';
+    params: DCAParams;
+}
+interface TWAPJob extends BaseJob {
+    type: 'twap';
+    params: TWAPParams;
+}
+interface SwapJob extends BaseJob {
+    type: 'swap';
+    params: SwapParams;
+}
+type Job = LimitOrderJob | DCAJob | TWAPJob | SwapJob;
+interface LimitOrderParams {
+    tokenIn: string;
+    tokenOut: string;
+    amountIn: string;
+    minAmountOut: string;
+    targetPrice: string;
+    direction: 'gte' | 'lte';
+    /** User-configured slippage in basis points (e.g. 50 = 0.5%) — stored for display */
+    slippageBps?: number;
+}
+interface DCAParams {
+    tokenIn: string;
+    tokenOut: string;
+    amountPerSwap: string;
+    intervalSeconds: number;
+    totalSwaps: number;
+    swapsCompleted: number;
+    nextExecution: number;
+}
+interface TWAPParams {
+    tokenIn: string;
+    tokenOut: string;
+    totalAmountIn: string;
+    numberOfTranches: number;
+    intervalSeconds: number;
+    slippageBps?: number;
+}
+interface SwapParams {
+    tokenIn: string;
+    tokenOut: string;
+    amountIn: string;
+    minAmountOut: string;
+    slippageBps?: number;
+}
+interface SafetyConfig {
+    /** Maximum USD value per single swap */
+    maxSwapUsd: number;
+    /** Maximum slippage in basis points (e.g. 200 = 2%) */
+    maxSlippageBps: number;
+    /** Maximum retries before a job is marked failed */
+    maxRetries: number;
+    /** Minimum seconds between consecutive executions for the same job */
+    minExecutionIntervalSeconds: number;
+    /** If true, all job execution is halted (circuit-breaker) */
+    globalPause: boolean;
+}
+interface SafetyViolation {
+    jobId: string;
+    rule: keyof SafetyConfig;
+    detail: string;
+    timestamp: number;
+}
+type SafetyCheckResult = {
+    ok: true;
+} | {
+    ok: false;
+    violation: SafetyViolation;
+};
+
+/**
+ * Price source adapter interface.
+ *
+ * Returns the spot price of `tokenIn` denominated in `tokenOut`, scaled by
+ * 1e18.  Implementations may call a DEX (Swappi, etc.), an oracle, or a mock.
+ */
+interface PriceSource {
+    /**
+     * Returns 0n if the pair is unknown or price cannot be fetched.
+     */
+    getPrice(tokenIn: string, tokenOut: string): Promise<bigint>;
+}
+interface PriceCheckResult {
+    conditionMet: boolean;
+    currentPrice: bigint;
+    targetPrice: bigint;
+    swapUsd: number;
+}
+/**
+ * Callback that resolves a token address to its ERC-20 decimal count.
+ * Implementations should cache the result for performance.
+ */
+type DecimalsResolver = (token: string) => Promise<number>;
+/**
+ * PriceChecker – queries a price source and evaluates whether a job's
+ * trigger condition is currently met.
+ */
+declare class PriceChecker {
+    private source;
+    private tokenPricesUsd;
+    /**
+     * Resolves a token's decimal count.  Called lazily when _estimateUsd needs
+     * to convert raw wei amounts into human-readable values.  The resolver may
+     * query the chain, a static map, or simply return 18.
+     */
+    private getDecimals;
+    private readonly log;
+    constructor(source: PriceSource, tokenPricesUsd?: Map<string, number>, logger?: AutomationLogger, getDecimals?: DecimalsResolver);
+    checkLimitOrder(job: Job & {
+        type: 'limit_order';
+    }): Promise<PriceCheckResult>;
+    checkDCA(job: Job & {
+        type: 'dca';
+    }): Promise<PriceCheckResult>;
+    updateTokenPrice(token: string, usdPrice: number): void;
+    private _estimateUsd;
+}
+
+/**
+ * RetryQueue – wraps jobs for retry-with-exponential-backoff scheduling.
+ *
+ * Backoff formula:
+ *   delay = min(base × 2^attempt, maxDelay) × (1 + jitter × rand)
+ */
+declare class RetryQueue {
+    private readonly baseDelayMs;
+    private readonly maxDelayMs;
+    private readonly jitter;
+    private readonly log;
+    private queue;
+    constructor(options?: {
+        baseDelayMs?: number;
+        maxDelayMs?: number;
+        jitter?: number;
+    }, logger?: AutomationLogger);
+    /** Enqueue a job for retry after a calculated backoff delay. */
+    enqueue(job: Job): void;
+    /** Remove a job from the queue (e.g. after success or manual cancel). */
+    remove(jobId: string): void;
+    /** Return all jobs whose retry time has arrived; removes them from the queue. */
+    drainDue(now?: number): Job[];
+    size(): number;
+    private _backoffDelay;
+}
+
+/** Default on-chain safety limits. */
+declare const DEFAULT_SAFETY_CONFIG: SafetyConfig;
+/**
+ * SafetyGuard – off-chain complement to AutomationManager's on-chain checks.
+ *
+ * Responsibilities:
+ *  1. Validate a job satisfies configured safety bounds before the keeper
+ *     submits a transaction.
+ *  2. Provide a global pause switch (circuit-breaker).
+ *  3. Log every violation for audit purposes.
+ *
+ * The logger is injected rather than imported — the SDK ships with no logging
+ * dependency.  Pass your pino/winston/console instance, or omit for silence.
+ */
+declare class SafetyGuard {
+    private config;
+    private violations;
+    private readonly log;
+    constructor(config?: Partial<SafetyConfig>, logger?: AutomationLogger);
+    /**
+     * Run all configured safety checks against a job.
+     * Returns `{ ok: true }` if all pass, or `{ ok: false, violation }` on first failure.
+     */
+    check(job: Job, context: {
+        swapUsd: number;
+        currentTime?: number;
+    }): SafetyCheckResult;
+    updateConfig(patch: Partial<SafetyConfig>): void;
+    getConfig(): Readonly<SafetyConfig>;
+    pauseAll(): void;
+    resumeAll(): void;
+    isPaused(): boolean;
+    getViolations(): readonly SafetyViolation[];
+    clearViolations(): void;
+    private _fail;
+}
+
+interface KeeperClient$1 {
+    executeLimitOrder(jobId: string, owner: string, params: LimitOrderJob['params']): Promise<{
+        txHash: string;
+        amountOut?: string | null;
+    }>;
+    executeDCATick(jobId: string, owner: string, params: DCAJob['params']): Promise<{
+        txHash: string;
+        amountOut?: string | null;
+        nextExecutionSec: number;
+    }>;
+    /** Read the terminal status of a job from the contract. */
+    getOnChainStatus(jobId: `0x${string}`): Promise<'active' | 'executed' | 'cancelled' | 'expired'>;
+}
+interface JobStore {
+    getActiveJobs(): Promise<Job[]>;
+    markActive(jobId: string): Promise<void>;
+    markExecuted(jobId: string, txHash: string, amountOut?: string | null): Promise<void>;
+    /**
+     * Record one completed DCA tick.
+     * Updates swapsCompleted + nextExecution in params_json and inserts an
+     * execution record.  Sets status → 'executed' when all swaps are done,
+     * otherwise keeps the job 'active' so subsequent ticks can run.
+     */
+    markDCATick(jobId: string, txHash: string, newSwapsCompleted: number, nextExecution: number, amountOut?: string | null): Promise<void>;
+    markFailed(jobId: string, error: string): Promise<void>;
+    incrementRetry(jobId: string): Promise<void>;
+    markExpired(jobId: string): Promise<void>;
+    /** Mark a job cancelled — use when on-chain status is CANCELLED. */
+    markCancelled(jobId: string): Promise<void>;
+    /** Record the latest error message without changing status or incrementing retries. */
+    updateLastError(jobId: string, error: string): Promise<void>;
+}
+interface ExecutorOptions {
+    dryRun?: boolean;
+}
+/**
+ * Executor – evaluates active jobs and submits on-chain transactions when
+ * conditions are met and the SafetyGuard approves.
+ */
+declare class Executor {
+    private priceChecker;
+    private safetyGuard;
+    private retryQueue;
+    private keeperClient;
+    private jobStore;
+    private dryRun;
+    constructor(priceChecker: PriceChecker, safetyGuard: SafetyGuard, retryQueue: RetryQueue, keeperClient: KeeperClient$1, jobStore: JobStore, options?: ExecutorOptions);
+    /**
+     * Process a single job tick.
+     */
+    processTick(job: Job): Promise<void>;
+    /**
+     * Process all active jobs + due retries in one tick.
+     */
+    runAllTicks(): Promise<void>;
+    private _processLimitOrder;
+    private _processDCA;
+}
+
+/**
+ * KeeperClient — viem implementation of the KeeperClient interface.
+ *
+ * Wraps AutomationManager contract calls for executeLimitOrder and executeDCATick.
+ * The executor wallet is a keeper (not a custodian) — it cannot move user funds
+ * unless the user has set an on-chain allowance for that specific swap.
+ */
+
+interface KeeperClientConfig {
+    /** RPC endpoint for Conflux eSpace */
+    rpcUrl: string;
+    /** Hex private key (0x-prefixed) of the keeper wallet */
+    privateKey: `0x${string}`;
+    /** Deployed AutomationManager contract address */
+    contractAddress: Address;
+    /**
+     * Swappi router address.
+     * Testnet:  0x873789aaf553fd0b4252d0d2b72c6331c47aff2e
+     * Mainnet:  0xE37B52296b0bAA91412cD0Cd97975B0805037B84  (Swappi v2 — only address with deployed code;
+     * old 0x62B0873... has no bytecode)
+     */
+    swappiRouter: Address;
+    /**
+     * Maximum gas price in gwei before aborting execution (circuit breaker).
+     * Defaults to 1000 gwei.
+     */
+    maxGasPriceGwei?: bigint;
+    /** Chain definition — pass the viem chain object (espaceTestnet / espaceMainnet) */
+    chain: Parameters<typeof createWalletClient>[0]['chain'];
+    /** RPC request timeout in milliseconds (applies to read/simulate/write calls). */
+    rpcTimeoutMs?: number;
+}
+declare class KeeperClientImpl implements KeeperClient$1 {
+    private readonly walletClient;
+    private readonly publicClient;
+    private readonly contractAddress;
+    private readonly swappiRouter;
+    private readonly maxGasPriceGwei;
+    private readonly rpcTimeoutMs;
+    private readonly account;
+    constructor(config: KeeperClientConfig);
+    private withTimeout;
+    /**
+     * Query the on-chain status of a job.
+     * Returns one of: 'active' | 'executed' | 'cancelled' | 'expired'.
+     * Throws if the contract call fails (e.g. job not found).
+     */
+    getOnChainStatus(onChainJobId: `0x${string}`): Promise<'active' | 'executed' | 'cancelled' | 'expired'>;
+    /** Guard: abort if chain is paused or gas price is too high */
+    private preflightCheck;
+    /**
+     * Build minimal swap calldata for a token-in/token-out pair via Swappi.
+     *
+     * In a production keeper the calldata would be built via a DEX aggregator
+     * (e.g. OKX DEX API) to get optimal routing.  For the MVP we encode the
+     * simplest Swappi path: `swapExactTokensForTokens(amountIn, minOut, path, to, deadline)`.
+     *
+     * NOTE: The AutomationManager does NOT use this calldata for custody;
+     * it only uses it to call the router on behalf of the user's pre-approved allowance.
+     */
+    private buildSwapCalldata;
+    executeLimitOrder(jobId: string, owner: string, params: LimitOrderJob['params']): Promise<{
+        txHash: string;
+        amountOut: string | null;
+    }>;
+    executeDCATick(jobId: string, owner: string, params: DCAJob['params']): Promise<{
+        txHash: string;
+        amountOut: string | null;
+        nextExecutionSec: number;
+    }>;
+}
+
+/**
+ * Minimal interface that any concrete keeper/executor must satisfy.
+ *
+ * The SDK defines the contract here; implementations live in the CAS worker
+ * (KeeperClient) or in custom keeper deployments.
+ */
+interface KeeperClient {
+    /**
+     * Submit an `executeLimitOrder` transaction to the AutomationManager
+     * contract and wait for it to be mined.
+     */
+    executeLimitOrder(jobId: `0x${string}`, owner: `0x${string}`, params: LimitOrderParams): Promise<{
+        txHash: `0x${string}`;
+        amountOut?: string;
+    }>;
+    /**
+     * Submit an `executeDCATick` transaction and wait for confirmation.
+     */
+    executeDCATick(jobId: `0x${string}`, owner: `0x${string}`, params: DCAParams): Promise<{
+        txHash: `0x${string}`;
+        amountOut?: string;
+    }>;
+    /**
+     * Read the current on-chain status of a job.
+     *
+     * Maps the contract `JobStatus` enum:
+     *  `0 = ACTIVE → 'active'`
+     *  `1 = EXECUTED → 'executed'`
+     *  `2 = CANCELLED → 'cancelled'`
+     *  `3 = EXPIRED → 'expired'`
+     */
+    getOnChainStatus(jobId: `0x${string}`): Promise<'active' | 'executed' | 'cancelled' | 'expired'>;
+}
+
+interface LimitOrderStrategy {
+    kind: 'limit_order';
+    tokenIn: string;
+    tokenOut: string;
+    amountIn: string;
+    targetPrice: string;
+    direction: 'gte' | 'lte';
+    slippageBps: number;
+    expiresInDays: number | null;
+}
+interface DCAStrategy {
+    kind: 'dca';
+    tokenIn: string;
+    tokenOut: string;
+    amountPerSwap: string;
+    intervalHours: number;
+    totalSwaps: number;
+    slippageBps: number;
+}
+interface TWAPStrategy {
+    kind: 'twap';
+    tokenIn: string;
+    tokenOut: string;
+    totalAmountIn: string;
+    numberOfTranches: number;
+    intervalHours: number;
+    slippageBps: number;
+    expiresInDays: number | null;
+}
+interface SwapStrategy {
+    kind: 'swap';
+    tokenIn: string;
+    tokenOut: string;
+    amountIn: string;
+    slippageBps: number;
+}
+type Strategy = LimitOrderStrategy | DCAStrategy | TWAPStrategy | SwapStrategy;
+
+export { type AutomationLogger, type BaseJob, type DCAJob, type DCAParams, type DCAStrategy, DEFAULT_SAFETY_CONFIG, type DecimalsResolver, Executor, type ExecutorOptions, type KeeperClient as IKeeperClient, type Job, type JobStatus, type JobStore, type JobType, type KeeperClient$1 as KeeperClient, type KeeperClientConfig, KeeperClientImpl, type LimitOrderJob, type LimitOrderParams, type LimitOrderStrategy, type PriceCheckResult, PriceChecker, type PriceSource, RetryQueue, type SafetyCheckResult, type SafetyConfig, SafetyGuard, type SafetyViolation, type Strategy, type SwapJob, type SwapParams, type SwapStrategy, type TWAPJob, type TWAPParams, type TWAPStrategy, noopLogger };