cred402/lib/keeperhub/executor.ts
caelum0x 24d073ee83 feat: KeeperHub execution layer + Flare interoperable/confidential credit
Two hackathon integrations spanning the whole credit stack, sim-first
(green with no keys) with real integrations behind env flags.

KeeperHub — the on-chain execution & reliability layer (lib/keeperhub/):
- OnchainExecutor: pay-per-execution (x402/MPP) -> simulate -> smart gas
  with exponential backoff -> MEV-protected private routing -> audit trail;
  real MCP client to app.keeperhub.com; deterministic sim fallback.
- Autonomous Credit Keeper: FTSO position health -> check->execute deleverage.
- Credit Automations: declarative price/health/schedule rules as workflows.
- Autonomous Scheduler: KeeperHub-cron loop running keeper + automations.

Flare — interoperable + confidential primitives (packages/.../flare, lib/flare):
- FXRP credit satellite: CAN-gated, FTSO-priced, FDC-attested; Coston2
  Solidity vault (contracts/flare/).
- Confidential Compute credit scoring (TEE-attested, private inputs).
- FTSO-priced multi-asset collateral; FAssets mint->collateralize lifecycle.

x402 Credit-Service Marketplace: sells cred402's intelligence pay-per-call
over x402 (402->pay->200); paid receipts feed the revenue->reputation loop.

Wiring: 78 MCP tools, /v1 + /api routes, console Flare + x402 tabs, 11 demo
CLIs, 8 feature docs + docs/SUBMISSIONS.md, recorded demo video (media/).
346 tests pass; 7 adversarial verification workflows caught + fixed ~37
correctness/security issues.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-08-11 23:34:23 +03:00

222 lines
8.5 KiB
TypeScript

import { keccak256 } from "../x402/evm.js";
import { KeeperHubClient } from "./client.js";
import { SmartGasEstimator } from "./gas.js";
import { PaymentRouter } from "./payments.js";
import { AuditTrail } from "./audit.js";
import type {
AuditRecord,
ExecutionIntent,
ExecutionResult,
GasEstimate,
OnchainExecutor,
SimulationResult,
} from "./types.js";
/**
* KeeperHubExecutor — the last mile. An agent decides; this pushes the decided
* transaction on-chain through KeeperHub with the full reliability envelope:
*
* pay-per-execution (x402 / MPP) → simulate (preflight) → smart gas w/ backoff
* → private / MEV-protected submit → poll to a tx hash → audit trail
*
* Live path (KEEPERHUB_API_KEY set): drives KeeperHub's `execute_contract_call`
* (`simulate:true` then broadcast) and `get_direct_execution_status`, honoring the
* `upstream_cold_start` retry hint with a reused idempotency key. Sim path:
* deterministic, so the loop runs with no key and no chain — same ExecutionResult
* shape either way.
*/
export interface KeeperHubExecutorOptions {
client?: KeeperHubClient;
gas?: SmartGasEstimator;
payments?: PaymentRouter;
audit?: AuditTrail;
/** MEV-protected private submission. Default true (KEEPERHUB_PRIVATE_ROUTING=0 disables). */
privateRouting?: boolean;
/** Base fee (wei) seed for the sim/record gas math. Default 1 gwei. */
baseFeeWei?: bigint;
priorityFeeWei?: bigint;
now?: () => number;
sleep?: (ms: number) => Promise<void>;
}
const DEFAULT_GAS_LIMIT = 120_000;
export class KeeperHubExecutor implements OnchainExecutor {
private readonly client: KeeperHubClient;
private readonly gas: SmartGasEstimator;
private readonly payments: PaymentRouter;
private readonly audit: AuditTrail;
private readonly privateRouting: boolean;
private readonly baseFeeWei: bigint;
private readonly priorityFeeWei: bigint;
private readonly now: () => number;
private readonly sleep: (ms: number) => Promise<void>;
private seq = 0;
constructor(opts: KeeperHubExecutorOptions = {}) {
this.client = opts.client ?? new KeeperHubClient();
this.gas = opts.gas ?? new SmartGasEstimator();
this.payments = opts.payments ?? new PaymentRouter();
this.audit = opts.audit ?? new AuditTrail();
this.privateRouting = opts.privateRouting ?? (process.env.KEEPERHUB_PRIVATE_ROUTING !== "0");
this.baseFeeWei = opts.baseFeeWei ?? 1_000_000_000n;
this.priorityFeeWei = opts.priorityFeeWei ?? 1_000_000n;
this.now = opts.now ?? (() => Date.now());
this.sleep = opts.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
}
isLive(): boolean {
return this.client.isLive();
}
auditTrail(): AuditRecord[] {
return this.audit.list();
}
auditFor(agentId: string): AuditRecord[] {
return this.audit.list(agentId);
}
reliability() {
return this.audit.summary();
}
async execute(intent: ExecutionIntent): Promise<ExecutionResult> {
this.seq += 1;
const idempotencyKey = keccak256(`kh:${intent.label}:${intent.chain_id}:${this.seq}:${this.now()}`);
const execution_id = idempotencyKey.slice(0, 34);
const payment = this.payments.settle(intent);
// 1) Preflight simulation.
const simulation = await this.simulate(intent);
const gas = this.gas.estimate(
{ base_fee_wei: this.baseFeeWei, priority_fee_wei: this.priorityFeeWei, gas_limit: simulation.gas_estimate ?? DEFAULT_GAS_LIMIT },
0,
);
const baseRecord: AuditRecord = {
audit_id: keccak256(`audit:${execution_id}`).slice(0, 34),
execution_id,
agent_id: intent.agent_id,
chain_id: intent.chain_id,
intent_kind: intent.kind,
label: intent.label,
trigger: { kind: intent.kind, to: intent.to, function: intent.function, ...intent.metadata },
simulation,
gas,
payment,
private_routed: this.privateRouting,
sponsored: payment.protocol === "sponsored",
tx_hash: "",
status: "simulated",
submitted_at: this.now(),
};
if (!simulation.ok) {
const rec = this.audit.append({ ...baseRecord, status: "failed", detail: simulation.revert_reason });
return this.toResult(rec, false, simulation.source, simulation.revert_reason);
}
// 2) Submit (private routing) — live via KeeperHub, else deterministic sim.
if (this.isLive()) {
return this.submitLive(intent, baseRecord, idempotencyKey);
}
const tx_hash = keccak256(`khtx:${execution_id}:${intent.to}`);
const rec = this.audit.append({
...baseRecord,
tx_hash,
status: "confirmed",
gas_used: Math.round((gas.gas_limit * 82) / 100),
confirmed_at: this.now(),
});
return this.toResult(rec, true, "sim");
}
// -- internals -----------------------------------------------------------
private async simulate(intent: ExecutionIntent): Promise<SimulationResult> {
if (!this.isLive()) {
return { ok: true, gas_estimate: DEFAULT_GAS_LIMIT, source: "sim" };
}
try {
const out = (await this.client.callTool("execute_contract_call", {
chain_id: intent.chain_id,
contract_address: intent.to,
function: intent.function,
args: intent.args ?? [],
simulate: true,
})) as { gas_estimate?: number; gasEstimate?: number; revert_reason?: string; error?: string };
const gas_estimate = out.gas_estimate ?? out.gasEstimate;
const revert = out.revert_reason ?? out.error;
return { ok: !revert, gas_estimate, revert_reason: revert, source: "keeperhub" };
} catch (err) {
return { ok: false, revert_reason: (err as Error).message, source: "keeperhub" };
}
}
/** Broadcast + poll to a tx hash, honoring KeeperHub's cold-start retry hint. */
private async submitLive(intent: ExecutionIntent, base: AuditRecord, idempotencyKey: string): Promise<ExecutionResult> {
try {
const submit = (await this.client.callTool("execute_contract_call", {
chain_id: intent.chain_id,
contract_address: intent.to,
function: intent.function,
args: intent.args ?? [],
private: this.privateRouting,
idempotency_key: idempotencyKey,
})) as { execution_id?: string; executionId?: string };
const executionId = submit.execution_id ?? submit.executionId ?? base.execution_id;
const rec = this.audit.append({ ...base, execution_id: executionId, status: "submitted" });
for (let attempt = 0; attempt < this.gas.maxAttempts; attempt++) {
const status = (await this.client.callTool("get_direct_execution_status", {
execution_id: executionId,
})) as { status?: string; tx_hash?: string; txHash?: string; gas_used?: number; error_code?: string; retryAfterSeconds?: number };
if (status.error_code === "upstream_cold_start") {
await this.sleep((status.retryAfterSeconds ?? 2) * 1000);
continue;
}
const txHash = status.tx_hash ?? status.txHash;
if ((status.status === "confirmed" || status.status === "success") && txHash) {
const confirmed = this.audit.confirm(rec.audit_id, {
gas_used: status.gas_used,
confirmed_at: this.now(),
tx_hash: txHash,
})!;
return this.toResult(confirmed, true, "keeperhub");
}
if (status.status === "failed" || status.status === "reverted") {
const failed = this.audit.fail(rec.audit_id, { confirmed_at: this.now(), detail: "execution reverted" })!;
return this.toResult(failed, false, "keeperhub", "execution reverted");
}
await this.sleep(this.gas.retryDelayMs(attempt));
}
const timedOut = this.audit.fail(rec.audit_id, { confirmed_at: this.now(), detail: "timed out polling execution status" })!;
return this.toResult(timedOut, false, "keeperhub", "timed out polling execution status");
} catch (err) {
const failed = this.audit.append({ ...base, status: "failed", detail: (err as Error).message });
return this.toResult(failed, false, "keeperhub", (err as Error).message);
}
}
private toResult(rec: AuditRecord, ok: boolean, source: "keeperhub" | "sim", detail?: string): ExecutionResult {
return {
ok,
execution_id: rec.execution_id,
tx_hash: rec.tx_hash,
audit_id: rec.audit_id,
simulation: rec.simulation,
gas: rec.gas,
payment: rec.payment,
private_routed: rec.private_routed,
sponsored: rec.sponsored,
gas_used: rec.gas_used,
source,
detail: detail ?? rec.detail,
};
}
}
export type { GasEstimate };