@telaro/evaluator-evm 0.1.0

package/README.md

@@ -0,0 +1,57 @@
+# @telaro/evaluator-evm
+
+EVM-side primitives for the Telaro Bonded Evaluator (Stage 3 W6).
+
+Telaro acts as the `evaluator` slot on Virtuals' AgenticCommerceV3 contract
+on Base mainnet. When a Solana-side bonded panel reaches a verdict, the
+gateway needs to call `complete(jobId, ...)` or `reject(jobId, ...)` on Base,
+signed by the Telaro evaluator EOA. This package owns that signing path
+so anyone running a Telaro-compatible evaluator (Telaro itself, partner
+juries, custom verdict pipelines) can ship the same EVM settlement.
+
+## Install
+
+```bash
+pnpm add @telaro/evaluator-evm viem
+```
+
+`viem` is a peer dep. Lazy-loaded inside the package so importing the
+helpers does not drag in the EVM bundle until you actually settle.
+
+## Usage
+
+```ts
+import { signAndSendVerdict } from "@telaro/evaluator-evm";
+
+const txHash = await signAndSendVerdict({
+  verdict: "complete",
+  evmJobId: 42n,
+  evmChainId: 8453,
+  baseRpcUrl: process.env.BASE_RPC_URL!,
+  virtualsContractAddress: "0x238E541BfefD82238730D00a2208E5497F1832E0",
+  evmPrivateKeyHex: process.env.TELARO_EVALUATOR_EVM_PRIVKEY!,
+});
+console.log("settled:", txHash);
+```
+
+## API
+
+- `signAndSendVerdict(params)` — sign and submit a `complete` or `reject`
+  call. Returns the tx hash.
+- `makeWalletClient(params)` — get a viem WalletClient bound to the
+  Telaro EOA. Use when you want to attach more calls in the same flow.
+- `encodeVerdictCalldata(params)` — pure calldata builder. No tx submit.
+  Useful for Safe / Squads multisig flows or for dry-run logging.
+- `validateConfig(params)` — pre-flight check on chain id, key shape,
+  and contract address. Returns `null` on success, a short error
+  string on failure.
+- `VIRTUALS_BASE_MAINNET` — the canonical contract address constant.
+- `EVALUATOR_ABI_FRAGMENTS` — the two ABI signatures we use.
+
+## Why a separate package
+
+Before extracting this, the viem wiring lived inside
+`@telaro/sacp-mcp-server/src/evaluator-middleware.ts`. That meant any
+third party who wanted to run an evaluator had to fork the gateway or
+re-derive the calldata by hand. The split lets the gateway depend on
+this for the wire and gives external builders the same building block.

package/dist/index.d.ts

@@ -0,0 +1,87 @@
+/**
+ * @telaro/evaluator-evm — Stage 3 W6 EVM side.
+ *
+ * Sign and submit Virtuals AgenticCommerceV3 complete / reject calls
+ * from the Telaro evaluator EOA. Extracted from the gateway so anyone
+ * building an evaluator (Telaro's bonded panel, an external partner,
+ * a custom verdict pipeline) can ship the same on-chain settlement
+ * path without reimplementing the viem plumbing.
+ *
+ * Usage:
+ *
+ *   import { signAndSendVerdict } from "@telaro/evaluator-evm";
+ *   const txHash = await signAndSendVerdict({
+ *     verdict: "complete",
+ *     evmJobId: 42n,
+ *     baseRpcUrl: process.env.TELARO_BASE_RPC_URL!,
+ *     evmChainId: 8453,
+ *     virtualsContractAddress: "0x238E541BfefD82238730D00a2208E5497F1832E0",
+ *     evmPrivateKeyHex: process.env.TELARO_EVALUATOR_EVM_PRIVKEY!,
+ *     reasonHex: "0x" + "00".repeat(32),
+ *   });
+ */
+export type EvaluatorVerdict = "complete" | "reject";
+/** Virtuals AgenticCommerceV3 proxy on Base mainnet. */
+export declare const VIRTUALS_BASE_MAINNET = "0x238E541BfefD82238730D00a2208E5497F1832E0";
+/** ERC-8183 + Virtuals lifecycle terminal call signatures used by an evaluator. */
+export declare const EVALUATOR_ABI_FRAGMENTS: readonly ["function complete(uint256 jobId, bytes32 reason, bytes optParams)", "function reject(uint256 jobId, bytes32 reason, bytes optParams)"];
+export interface SignAndSendVerdictParams {
+    verdict: EvaluatorVerdict;
+    /** u256 EVM jobId from the JobCreated event. */
+    evmJobId: bigint;
+    /** Base mainnet (8453) or Base Sepolia (84532). */
+    evmChainId: number;
+    /** EVM JSON-RPC URL. */
+    baseRpcUrl: string;
+    /** Virtuals AgenticCommerceV3 proxy on Base. */
+    virtualsContractAddress: string;
+    /** 32-byte hex EVM private key, with or without 0x prefix. */
+    evmPrivateKeyHex: string;
+    /** Optional 32-byte hex attestation pointer. Defaults to all zeros. */
+    reasonHex?: string;
+    /** Optional bytes-hex extra params. Defaults to 0x. */
+    optParamsHex?: string;
+}
+/**
+ * Sign and submit a complete/reject transaction on Base. viem is loaded
+ * lazily so importing this module doesn't drag in a 200KB ESM bundle on
+ * platforms that only need the planning helpers.
+ */
+export declare function signAndSendVerdict(params: SignAndSendVerdictParams): Promise<`0x${string}`>;
+export interface WalletClientParams {
+    baseRpcUrl: string;
+    evmChainId: number;
+    evmPrivateKeyHex: string;
+}
+/**
+ * Lazy-loaded viem wallet client tied to the Telaro EOA. The return
+ * type is intentionally erased to `unknown` shaped as a wallet client;
+ * downstream callers typically just need `.sendTransaction`. Cast to
+ * viem's `WalletClient` if you need the full typed surface.
+ */
+export interface LooseWalletClient {
+    sendTransaction: (tx: {
+        to: `0x${string}`;
+        data: `0x${string}`;
+        value: bigint;
+    }) => Promise<`0x${string}`>;
+}
+export declare function makeWalletClient(params: WalletClientParams): Promise<LooseWalletClient>;
+export interface EncodeVerdictParams {
+    verdict: EvaluatorVerdict;
+    evmJobId: bigint;
+    reasonHex?: string;
+    optParamsHex?: string;
+}
+/** Encode the complete/reject calldata. Pure function — no viem required for callers that just want bytes. */
+export declare function encodeVerdictCalldata(params: EncodeVerdictParams): Promise<`0x${string}`>;
+/**
+ * Sanity check on common config errors before paying the viem import.
+ * Returns null on success, a short error string on failure.
+ */
+export declare function validateConfig(params: {
+    evmChainId: number;
+    evmPrivateKeyHex: string;
+    virtualsContractAddress: string;
+}): string | null;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,MAAM,MAAM,gBAAgB,GAAG,UAAU,GAAG,QAAQ,CAAC;AAErD,wDAAwD;AACxD,eAAO,MAAM,qBAAqB,+CAA+C,CAAC;AAElF,mFAAmF;AACnF,eAAO,MAAM,uBAAuB,mJAG1B,CAAC;AAEX,MAAM,WAAW,wBAAwB;IACvC,OAAO,EAAE,gBAAgB,CAAC;IAC1B,gDAAgD;IAChD,QAAQ,EAAE,MAAM,CAAC;IACjB,mDAAmD;IACnD,UAAU,EAAE,MAAM,CAAC;IACnB,wBAAwB;IACxB,UAAU,EAAE,MAAM,CAAC;IACnB,gDAAgD;IAChD,uBAAuB,EAAE,MAAM,CAAC;IAChC,8DAA8D;IAC9D,gBAAgB,EAAE,MAAM,CAAC;IACzB,uEAAuE;IACvE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,uDAAuD;IACvD,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;;;GAIG;AACH,wBAAsB,kBAAkB,CACtC,MAAM,EAAE,wBAAwB,GAC/B,OAAO,CAAC,KAAK,MAAM,EAAE,CAAC,CAiBxB;AAED,MAAM,WAAW,kBAAkB;IACjC,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,gBAAgB,EAAE,MAAM,CAAC;CAC1B;AAED;;;;;GAKG;AACH,MAAM,WAAW,iBAAiB;IAChC,eAAe,EAAE,CAAC,EAAE,EAAE;QACpB,EAAE,EAAE,KAAK,MAAM,EAAE,CAAC;QAClB,IAAI,EAAE,KAAK,MAAM,EAAE,CAAC;QACpB,KAAK,EAAE,MAAM,CAAC;KACf,KAAK,OAAO,CAAC,KAAK,MAAM,EAAE,CAAC,CAAC;CAC9B;AAED,wBAAsB,gBAAgB,CACpC,MAAM,EAAE,kBAAkB,GACzB,OAAO,CAAC,iBAAiB,CAAC,CAa5B;AAED,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,gBAAgB,CAAC;IAC1B,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,8GAA8G;AAC9G,wBAAsB,qBAAqB,CACzC,MAAM,EAAE,mBAAmB,GAC1B,OAAO,CAAC,KAAK,MAAM,EAAE,CAAC,CAYxB;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE;IACrC,UAAU,EAAE,MAAM,CAAC;IACnB,gBAAgB,EAAE,MAAM,CAAC;IACzB,uBAAuB,EAAE,MAAM,CAAC;CACjC,GAAG,MAAM,GAAG,IAAI,CAYhB"}

package/dist/index.js

@@ -0,0 +1,98 @@
+/**
+ * @telaro/evaluator-evm — Stage 3 W6 EVM side.
+ *
+ * Sign and submit Virtuals AgenticCommerceV3 complete / reject calls
+ * from the Telaro evaluator EOA. Extracted from the gateway so anyone
+ * building an evaluator (Telaro's bonded panel, an external partner,
+ * a custom verdict pipeline) can ship the same on-chain settlement
+ * path without reimplementing the viem plumbing.
+ *
+ * Usage:
+ *
+ *   import { signAndSendVerdict } from "@telaro/evaluator-evm";
+ *   const txHash = await signAndSendVerdict({
+ *     verdict: "complete",
+ *     evmJobId: 42n,
+ *     baseRpcUrl: process.env.TELARO_BASE_RPC_URL!,
+ *     evmChainId: 8453,
+ *     virtualsContractAddress: "0x238E541BfefD82238730D00a2208E5497F1832E0",
+ *     evmPrivateKeyHex: process.env.TELARO_EVALUATOR_EVM_PRIVKEY!,
+ *     reasonHex: "0x" + "00".repeat(32),
+ *   });
+ */
+/** Virtuals AgenticCommerceV3 proxy on Base mainnet. */
+export const VIRTUALS_BASE_MAINNET = "0x238E541BfefD82238730D00a2208E5497F1832E0";
+/** ERC-8183 + Virtuals lifecycle terminal call signatures used by an evaluator. */
+export const EVALUATOR_ABI_FRAGMENTS = [
+    "function complete(uint256 jobId, bytes32 reason, bytes optParams)",
+    "function reject(uint256 jobId, bytes32 reason, bytes optParams)",
+];
+/**
+ * Sign and submit a complete/reject transaction on Base. viem is loaded
+ * lazily so importing this module doesn't drag in a 200KB ESM bundle on
+ * platforms that only need the planning helpers.
+ */
+export async function signAndSendVerdict(params) {
+    const wallet = await makeWalletClient({
+        baseRpcUrl: params.baseRpcUrl,
+        evmChainId: params.evmChainId,
+        evmPrivateKeyHex: params.evmPrivateKeyHex,
+    });
+    const data = await encodeVerdictCalldata({
+        verdict: params.verdict,
+        evmJobId: params.evmJobId,
+        reasonHex: params.reasonHex,
+        optParamsHex: params.optParamsHex,
+    });
+    return wallet.sendTransaction({
+        to: params.virtualsContractAddress,
+        data,
+        value: 0n,
+    });
+}
+export async function makeWalletClient(params) {
+    const { createWalletClient, http } = await import("viem");
+    const { privateKeyToAccount } = await import("viem/accounts");
+    const { base, baseSepolia } = await import("viem/chains");
+    const chain = params.evmChainId === 8453 ? base : baseSepolia;
+    const pkHex = params.evmPrivateKeyHex.startsWith("0x")
+        ? params.evmPrivateKeyHex
+        : "0x" + params.evmPrivateKeyHex;
+    return createWalletClient({
+        account: privateKeyToAccount(pkHex),
+        chain,
+        transport: http(params.baseRpcUrl),
+    });
+}
+/** Encode the complete/reject calldata. Pure function — no viem required for callers that just want bytes. */
+export async function encodeVerdictCalldata(params) {
+    const { encodeFunctionData, parseAbi } = await import("viem");
+    const abi = parseAbi(EVALUATOR_ABI_FRAGMENTS);
+    return encodeFunctionData({
+        abi,
+        functionName: params.verdict,
+        args: [
+            params.evmJobId,
+            (params.reasonHex ?? "0x" + "00".repeat(32)),
+            (params.optParamsHex ?? "0x"),
+        ],
+    });
+}
+/**
+ * Sanity check on common config errors before paying the viem import.
+ * Returns null on success, a short error string on failure.
+ */
+export function validateConfig(params) {
+    if (params.evmChainId !== 8453 && params.evmChainId !== 84532) {
+        return `unsupported evmChainId ${params.evmChainId}; expected 8453 (Base mainnet) or 84532 (Base Sepolia)`;
+    }
+    const pk = params.evmPrivateKeyHex.replace(/^0x/, "");
+    if (!/^[0-9a-fA-F]{64}$/.test(pk)) {
+        return "evmPrivateKeyHex must be 32 bytes hex";
+    }
+    if (!/^0x[0-9a-fA-F]{40}$/.test(params.virtualsContractAddress)) {
+        return "virtualsContractAddress must be a 20-byte 0x-prefixed EVM address";
+    }
+    return null;
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@telaro/evaluator-evm",
+  "version": "0.1.0",
+  "description": "EVM-side primitives for the Telaro Bonded Evaluator. Sign and submit Virtuals AgenticCommerceV3 complete/reject transactions from any wallet that holds the Telaro evaluator EOA private key.",
+  "license": "MIT",
+  "homepage": "https://telaro.xyz",
+  "repository": "https://github.com/Telaro-Protocol/telaro-protocol",
+  "main": "dist/index.js",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "node --import tsx/esm --test tests/*.test.ts"
+  },
+  "peerDependencies": {
+    "viem": "^2.0.0"
+  },
+  "peerDependenciesMeta": {
+    "viem": {
+      "optional": false
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsx": "^4.16.0",
+    "typescript": "^5.5.0",
+    "viem": "^2.52.0"
+  },
+  "keywords": [
+    "erc-8183",
+    "evaluator",
+    "virtuals",
+    "base",
+    "viem",
+    "evm",
+    "telaro"
+  ]
+}