@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. When a Solana bonded panel reaches a verdict, the gateway calls 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 can ship the same EVM settlement: Telaro itself, partner juries, or custom verdict pipelines.

Install

pnpm add @telaro/evaluator-evm viem

viem is a peer dependency. It is lazy-loaded inside the package, so importing a helper does not pull in the EVM bundle until you actually sign or encode.

Sign and broadcast in one call

The common path. The function signs with the EOA you pass in and broadcasts on the chain id you pass in.

import { signAndSendVerdict, VIRTUALS_BASE_MAINNET } from "@telaro/evaluator-evm";

const txHash = await signAndSendVerdict({
  verdict: "complete",
  evmJobId: 42n,
  evmChainId: 8453,
  baseRpcUrl: process.env.TELARO_BASE_RPC_URL!,
  virtualsContractAddress: VIRTUALS_BASE_MAINNET,
  evmPrivateKeyHex: process.env.TELARO_EVALUATOR_EVM_PRIVKEY!,
});

console.log("settled:", txHash);

Full runnable example: examples/01-sign-and-send.ts.

Build calldata without broadcasting

For Safe or Squads multisig flows, or for a dry-run log. No signing, no RPC call.

import { encodeVerdictCalldata } from "@telaro/evaluator-evm";

const calldata = await encodeVerdictCalldata({
  verdict: "complete",
  evmJobId: 42n,
});

console.log(calldata); // 0x...

Full runnable example: examples/02-dry-run-calldata.ts.

Pre-flight config check

Catch typos in the contract address, wrong chain id, and malformed key bytes before any tx goes out.

import { validateConfig } from "@telaro/evaluator-evm";

const err = validateConfig({
  evmChainId: 8453,
  virtualsContractAddress: process.env.TELARO_VIRTUALS_CONTRACT!,
  evmPrivateKeyHex: process.env.TELARO_EVALUATOR_EVM_PRIVKEY!,
});

if (err) throw new Error(err);

Full runnable example: examples/03-validate-config.ts.

API surface

| Export | Purpose | |---|---| | signAndSendVerdict(params) | Sign and broadcast a complete or reject call. Returns the tx hash. | | encodeVerdictCalldata(params) | Pure calldata builder. No signing, no broadcast. | | makeWalletClient(params) | Returns a viem WalletClient bound to the EOA. Use when chaining more calls in one flow. | | validateConfig(params) | Pre-flight check. Returns null on success, an error string on failure. | | VIRTUALS_BASE_MAINNET | Constant. 0x238E541BfefD82238730D00a2208E5497F1832E0. | | EVALUATOR_ABI_FRAGMENTS | The two ABI fragments used internally. |

Operating notes

The full runbook for provisioning the EOA, funding it, registering it with Virtuals, and rotating it lives in docs/EVALUATOR_EOA_MAINNET.md. Read it before any mainnet move.

Why a separate package

Before this extraction the viem wiring lived inside @telaro/sacp-mcp-server/src/evaluator-middleware.ts. Anyone who wanted to run a Telaro-compatible 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 lets external builders use the same building block.

License

MIT.