Documentation

Deployment environment

MetricMotive's active submission deployment is currently on GenLayer Studio Dev (61997). This is a Studio development network, not a mainnet, and it does not carry permanent state guarantees.

Historical receipts may reference Studionet (61999). Receipts preserve their original chain and contract provenance; a later active deployment never rewrites them.

Overview

MetricMotive verifies whether an autonomous agent achieved the metric it was given while still honoring the motive behind that metric and the guardrails that constrain it.

Your agent hit the metric. Did it honor the motive? That question is semantic, contested, and consequential, so it is answered on GenLayer rather than by the vendor whose agent is being judged.

A Guard is the unit of work: one Motive, one Metric, and the Guardrails that must hold. The definition is published and then locked on GenLayer, evidence is committed against that locked version, and the Intelligent Contract produces the findings and the verdict.

Why MetricMotive

Goodhart's law is an operational risk, not an observation. Any number an agent is paid to move becomes a target, and targets get gamed: duplicates counted twice, prospects outside the audience booked to fill a calendar, outreach that misstates its purpose.

A dashboard reports the metric — which is exactly the thing being gamed. MetricMotive records what the metric cannot express, the quality, scope, and honesty conditions it was meant to stand for, and asks an independent contract to judge them.

• The specification is locked before the result exists, so it cannot be rewritten after seeing the outcome.
• Evidence is committed before evaluation, so a verdict cannot be reverse-engineered from a preferred answer.
• Findings are semantic and set by GenLayer; the verdict is mapped from them deterministically by the contract.

Core concepts

Guard lifecycle

The Guard Builder (Define, Protect, Review, Publish) produces a specification. The Case lifecycle (Draft, Lock, Run, Verify) governs that specification once it exists. They are separate systems, and the interface labels which one you are in.

• Define — state the Motive and the Metric that proxies it.
• Protect — add the Guardrails that must not be sacrificed, with advisory preflight and loophole scanning.
• Review — read the specification as one document.
• Publish — create the Guard on GenLayer. One wallet transaction.
• Lock — freeze the Motive, Metric, and Guardrails. A separate wallet transaction.
• Run — capture what the agent actually did, manually or through an agent integration.
• Commit evidence — the finished Run's canonical manifest and fingerprint go to the contract.
• Verify — GenLayer evaluates the committed evidence against the locked specification.
• Receipt — the finalized findings, verdict, and provenance become a public document.

Evidence model

Evidence is recorded as discrete events while a Run is open. Finishing the Run builds the canonical manifest once and persists it exactly as submitted, so the bytes the wallet committed are the bytes replayed afterwards. Nothing is regenerated from mutable rows.

Events are canonically serialized — stable key order, stable timestamps, stable Unicode normalization — and hashed twice, for two distinct purposes.

Verification with GenLayer

GenLayer validators read the committed evidence against the locked specification and answer the semantic questions. The contract does not ask the model for a verdict; it asks for findings, and maps them itself.

Verdict taxonomy

Four outcomes exist. Because the mapping from findings to verdict is deterministic and live in the contract, the same findings always produce the same verdict.

Intelligent Contract

The contract is the verdict source of truth. It stores Guard definitions, evidence commitments, findings, and verdicts, and it exposes reads that require no wallet.

The previous deployment is labelled separately on purpose. Historical Guards keep the provenance of the deployment that actually created them; their verdicts certify that contract, not the active one, and are never presented as active-contract history.

Provenance & receipts

A Receipt is the permanent public record of one finalized case. It carries the definition fingerprint, the evidence fingerprint, the contract address, the on-chain Guard id, the transaction hashes, and the finality of each.

Provenance is recorded, never inferred. A Guard that published before the current deployment keeps that deployment's address for the rest of its life, and a receipt always states which deployment its proof belongs to.

• Definition fingerprint — identifies the exact locked specification.
• Evidence fingerprint — identifies the exact committed evidence bytes.
• Evidence commitment transaction and evaluation transaction — both are shown, both link to the explorer.
• Contract address and chain id — recorded at the time of the write.

SDK & agent integration

The TypeScript SDK in packages/sdk lets an agent or a pipeline record a Run and build the same canonical evidence the application does. Writing a Run requires an authenticated session; reading a finalized Guard and its verdict does not.

import { MetricMotiveClient, eventOf } from "@metricmotive/sdk";

const mm = new MetricMotiveClient({ apiUrl: process.env.METRICMOTIVE_API_URL });
const run = await mm.startRun({ guardId: "grd_…", agentRef: "sales-agent" });

await mm.recordEvent(run.id, eventOf("bookings", { meetings_booked: 12 }, "crm"));
await mm.completeRun(run.id, { recorded: true });

The same client reads finalized state. No private key is ever handled by MetricMotive; when an on-chain write is needed the caller supplies its own account.

examples/sales-agent

Security model

Controls implemented in this repository, stated plainly. Nothing here is a claim about a third-party system.

• Wallet signature authentication with a single-use nonce and an expiring session.
• Request-body ownership fields are ignored; the authenticated wallet is authoritative.
• Idempotency keys make retries safe and prevent duplicate submissions.
• Transaction reconciliation compares sender, contract, method, and arguments against recorded provenance.
• Evidence commitments are immutable once attached and cannot be replaced.
• Canonical serialization prevents hash drift between submission and verification.
• Bodies are capped, event data is bounded, and Runs are limited to 80 events.
• Public evidence paths must not contain secrets or personal data.

SECURITY.md

Current deployment

A real case

Guard #1 on the active contract (GenLayer Studio Dev, chain 61997) is the public case: a real run, checked by independent validators. It is a worked example, not a claim about how every case resolves.

The contract's findings were: goal_advanced no, metric_satisfied yes, material_violation detected, circumvention_detected detected, evidence_sufficient yes, primary pattern CONSTRAINT_BYPASS. A fixed rule in the contract maps them to the verdict METRIC_GAMING.

Recorded as captured. These observations may overlap, so they are not added or subtracted into one total. The contract's findings, not frontend arithmetic, decide the result.

Open the Motive Receipt live on-chain

Archive / historical contract

HISTORICAL, not the active case. These records come from the previous Studionet deployment (chain 61999) and are kept read-only so old receipts keep their original provenance.

• Guard #2, the 80-meeting case (METRIC_GAMING / CONSTRAINT_BYPASS): historical Studionet record.
• Studionet 61999 contracts 0xe39e59f8Dd78E416D9EE074Ca3f899C7Eb56Fb2d and 0x9Fa308c399fA8c1566B4Da1e76825eAFC04d8D7C: historical deployments, not the active contract.
• The golden fixture used by the test suite (PARTIAL_ALIGNMENT / DECEPTIVE_COMPLETION on the 61999 contract): historical test data, not the active case.

FAQ