@absol-labs/agent 0.9.1 → 0.11.0

package/dist/x402/verified-delivery-facilitator.js

@@ -0,0 +1,423 @@
+import { getAddress } from "viem";
+import { PaymentPayloadSchema, PaymentRequirementsSchema, } from "x402/types";
+import { X402_NETWORK_BY_CHAIN_ID, X402_USDC_BY_CHAIN_ID, X402_VERSION, } from "./payment-requirements.js";
+export const SETTLEMENT_REFUSAL_DETAIL = Object.freeze({
+    "asset-not-allowed": "the settlement asset is not on this facilitator's allowlist. The relayer signs a call to " +
+        "`asset`, so an unrestricted asset would let a caller choose which contract the operator's " +
+        "key calls and pays gas for.",
+    "network-mismatch": "the payload or the requirements name a chain this facilitator does not settle on",
+    "zero-amount": "a zero-value settlement moves nothing and would only burn the relayer's gas",
+    "resource-not-tracked": "this relayer only pays gas for resources Metrik tracks, and this resource did not resolve " +
+        "to exactly one signed Metrik listing. The payment is not refused — any other facilitator " +
+        "can settle it; Metrik is declining to spend its own gas on it.",
+});
+export const DEFAULT_SETTLEMENT_SCOPE = "tracked-resources";
+/**
+ * The `invalidReason` used when the delivery gate refuses.
+ *
+ * The enum has no member for "the resource is not delivering", so the choice is
+ * between members that are all imperfect. Every payer-side member
+ * (`invalid_payload`, `invalid_exact_evm_payload_signature`,
+ * `insufficient_funds`) would be an active lie: it sends the developer to debug
+ * a wallet that is working correctly. `unexpected_verify_error` is also false —
+ * this refusal is deliberate and expected, not an error.
+ *
+ * `invalid_payment_requirements` is the only member that points at the
+ * REQUIREMENTS side of the exchange, which is exactly where the problem is:
+ * Metrik will not settle a payment quoted for THIS resource to THIS payee right
+ * now. It is the honest member, and the `metrik.detail` string carries the rest.
+ */
+export const DELIVERY_REFUSAL_REASON = "invalid_payment_requirements";
+/**
+ * Default: `allow`.
+ *
+ * The standing Metrik rule is buyer-favouring, and it still is — but it applies
+ * where Metrik HOLDS the buyer's money and must decide whether to release it.
+ * Here Metrik holds nothing, so refusing does not protect a buyer's funds; it
+ * only denies them a service they asked to buy, on a rail that works fine
+ * without Metrik. Four things make `allow` the right default:
+ *
+ * 1. **Absent evidence is the normal case, not the exception.** The oracle's
+ *    `/services` projection is built from ACTIVE STREAMS. A service with no live
+ *    Metrik stream has no row at all — on the live oracle today that is every
+ *    service. Failing closed would refuse 100% of payments, which is a broken
+ *    facilitator rather than a careful one.
+ * 2. **Fail-closed is a censorship lever.** If "oracle down" meant "no payments",
+ *    anyone who could degrade Metrik's oracle could block payments to a
+ *    competitor listed on it. `allow` removes that lever entirely.
+ * 3. **The harms are asymmetric.** A wrong refusal denies a service outright. A
+ *    wrong allowance passes one `exact` payment, at a price the buyer already
+ *    agreed to, which by construction is one call's worth.
+ * 4. **A pass never claims anything.** `isValid: true` with
+ *    `gate: "indeterminate"` says "no fresh evidence", and the annotation says
+ *    so in the response. Nobody has to infer an endorsement that was not made.
+ *
+ * Set `indeterminatePolicy: "deny"` for a deployment that would rather refuse
+ * than proceed without positive fresh evidence. That is a real, supported
+ * choice — it is just not a safe default.
+ */
+export const DEFAULT_INDETERMINATE_POLICY = "allow";
+export class RelayerNotConfiguredError extends Error {
+    constructor() {
+        super("this facilitator has no settlement relayer configured, so /settle cannot broadcast. " +
+            "Set METRIK_X402_RELAYER_PRIVATE_KEY (and METRIK_X402_RPC_URL) to enable settlement. " +
+            "Refusing rather than silently returning a fake success.");
+        this.name = "RelayerNotConfiguredError";
+    }
+}
+export class MetrikVerifiedDeliveryFacilitator {
+    paymentVerifier;
+    paymentSettler;
+    resourceIndex;
+    deliveryOracle;
+    indeterminatePolicy;
+    network;
+    settlementAssets;
+    settlementScope;
+    constructor(options) {
+        const chainId = options.chainId ?? 84532;
+        const network = X402_NETWORK_BY_CHAIN_ID[chainId];
+        if (network === undefined) {
+            throw new Error(`x402 v1 has no network name for chain ${chainId} (Metrik settles on Base: 8453, 84532)`);
+        }
+        this.paymentVerifier = options.paymentVerifier;
+        this.paymentSettler = options.paymentSettler;
+        this.resourceIndex = options.resourceIndex;
+        this.deliveryOracle = options.deliveryOracle;
+        this.indeterminatePolicy =
+            options.indeterminatePolicy ?? DEFAULT_INDETERMINATE_POLICY;
+        this.network = network;
+        const defaultAsset = X402_USDC_BY_CHAIN_ID[chainId]?.address;
+        const allowlist = options.settlementAssetAllowlist ??
+            (defaultAsset === undefined ? [] : [defaultAsset]);
+        if (allowlist.length === 0) {
+            throw new Error(`no settlement asset allowlist for chain ${chainId} and none supplied. ` +
+                "Refusing to construct a facilitator that would either settle nothing or, " +
+                "worse, broadcast to a caller-chosen contract.");
+        }
+        const normalized = new Set();
+        for (const candidate of allowlist) {
+            let checksummed;
+            try {
+                checksummed = getAddress(candidate);
+            }
+            catch {
+                throw new Error(`settlementAssetAllowlist entry is not an EVM address: ${candidate}`);
+            }
+            normalized.add(checksummed);
+        }
+        this.settlementAssets = normalized;
+        this.settlementScope = options.settlementScope ?? DEFAULT_SETTLEMENT_SCOPE;
+    }
+    /** The assets this relayer may be asked to call, for logging at startup. */
+    get allowedSettlementAssets() {
+        return [...this.settlementAssets];
+    }
+    supported() {
+        return {
+            x402Version: X402_VERSION,
+            kind: [{ scheme: "exact", networkId: this.network, extra: {} }],
+        };
+    }
+    /** `POST /verify`. Takes an unvalidated body; never throws on bad input. */
+    async verify(body) {
+        const parsed = parseFacilitatorRequest(body);
+        if (parsed === undefined) {
+            return {
+                isValid: false,
+                invalidReason: "invalid_payload",
+                metrik: {
+                    gate: "not-applicable",
+                    settleable: false,
+                    detail: "request body is not a valid x402 {paymentPayload, paymentRequirements} pair",
+                },
+            };
+        }
+        return this.evaluate(parsed.paymentPayload, parsed.paymentRequirements);
+    }
+    /**
+     * `POST /settle`. Re-runs the full gate before broadcasting: a facilitator
+     * must never settle something it would not verify, and `/settle` is reachable
+     * without `/verify` ever having been called.
+     */
+    async settle(body) {
+        const parsed = parseFacilitatorRequest(body);
+        if (parsed === undefined) {
+            return {
+                success: false,
+                errorReason: "invalid_payload",
+                transaction: "",
+                network: this.network,
+                metrik: {
+                    gate: "not-applicable",
+                    settleable: false,
+                    detail: "request body is not a valid x402 {paymentPayload, paymentRequirements} pair",
+                },
+            };
+        }
+        // Settlement constraints that need no network round trip run FIRST, so a
+        // hostile body never reaches the RPC, the registry or the oracle — let
+        // alone the relayer.
+        const preflight = this.settlementPreflight(parsed.paymentPayload, parsed.paymentRequirements);
+        if (preflight !== undefined) {
+            return this.refuseSettlement(parsed.paymentPayload, preflight, undefined);
+        }
+        const gate = await this.evaluate(parsed.paymentPayload, parsed.paymentRequirements);
+        if (!gate.isValid) {
+            return {
+                success: false,
+                ...(gate.invalidReason === undefined
+                    ? {}
+                    : { errorReason: gate.invalidReason }),
+                transaction: "",
+                network: parsed.paymentPayload.network,
+                ...(gate.payer === undefined ? {} : { payer: gate.payer }),
+                metrik: gate.metrik,
+            };
+        }
+        if (!gate.metrik.settleable) {
+            return this.refuseSettlement(parsed.paymentPayload, gate.metrik.settlementRefusal ?? "resource-not-tracked", gate.metrik);
+        }
+        if (this.paymentSettler === undefined) {
+            throw new RelayerNotConfiguredError();
+        }
+        const settled = await this.paymentSettler.settle(parsed.paymentPayload, parsed.paymentRequirements);
+        return { ...settled, metrik: gate.metrik };
+    }
+    /**
+     * Settlement constraints checkable from the request alone — no RPC, no
+     * registry, no oracle. Returns the refusal, or `undefined` if the request
+     * clears them.
+     */
+    settlementPreflight(payload, requirements) {
+        if (payload.network !== this.network ||
+            requirements.network !== this.network) {
+            return "network-mismatch";
+        }
+        // THE control. Without it the relayer signs a call to whatever contract
+        // address the caller puts here. See `SettlementRefusalReason`.
+        let asset;
+        try {
+            asset = getAddress(requirements.asset);
+        }
+        catch {
+            return "asset-not-allowed";
+        }
+        if (!this.settlementAssets.has(asset)) {
+            return "asset-not-allowed";
+        }
+        let amount;
+        try {
+            amount = BigInt(requirements.maxAmountRequired);
+        }
+        catch {
+            return "zero-amount";
+        }
+        if (amount <= 0n) {
+            return "zero-amount";
+        }
+        return undefined;
+    }
+    /** Builds the standard-shaped refusal for a settlement the relayer declines. */
+    refuseSettlement(payload, reason, gate) {
+        return {
+            success: false,
+            errorReason: reason === "network-mismatch"
+                ? "invalid_network"
+                : "invalid_payment_requirements",
+            transaction: "",
+            network: this.network,
+            metrik: {
+                ...(gate ?? { gate: "not-applicable", detail: "" }),
+                settleable: false,
+                settlementRefusal: reason,
+                detail: SETTLEMENT_REFUSAL_DETAIL[reason],
+            },
+        };
+    }
+    async evaluate(payload, requirements) {
+        const evaluated = await this.evaluateGate(payload, requirements);
+        // `settleable` is computed once, here, from the same facts `/settle`
+        // enforces — so a resource server reading `/verify` learns BEFORE it does
+        // any work whether this relayer will actually broadcast.
+        const refusal = this.settlementPreflight(payload, requirements) ??
+            (evaluated.isValid
+                ? this.scopeRefusal(evaluated.metrik.gate)
+                : "resource-not-tracked");
+        return {
+            ...evaluated,
+            metrik: {
+                ...evaluated.metrik,
+                settleable: refusal === undefined,
+                ...(refusal === undefined ? {} : { settlementRefusal: refusal }),
+            },
+        };
+    }
+    /** Does this gate outcome name a resource the relayer will pay gas for? */
+    scopeRefusal(gate) {
+        if (this.settlementScope === "any-resource") {
+            return undefined;
+        }
+        // Only an origin that resolved to exactly one signed listing counts.
+        // "not-applicable" (not ours), "ambiguous" (two claimants) and
+        // "registry-unavailable" (cannot tell) are all "we do not know this is
+        // ours", and the relayer does not spend gas on that.
+        return gate === "passed" ||
+            gate === "indeterminate" ||
+            gate === "refused" ||
+            gate === "payee-mismatch"
+            ? undefined
+            : "resource-not-tracked";
+    }
+    async evaluateGate(payload, requirements) {
+        // 1. Ordinary payment validity first. A malformed or unfunded payment is
+        //    rejected on its own merits, and never reaches — or leaks — the
+        //    delivery record of a service.
+        const payment = await this.paymentVerifier.verify(payload, requirements);
+        if (!payment.isValid) {
+            return {
+                ...payment,
+                metrik: {
+                    gate: "not-applicable",
+                    detail: "payment rejected on ordinary x402 grounds; the Metrik delivery gate did not run",
+                },
+            };
+        }
+        // 2. Is this resource one of ours? Resolved from Metrik's own verified
+        //    registry view, keyed on the resource URL's origin.
+        const lookup = await this.resourceIndex.lookup(requirements.resource);
+        if (lookup.status === "registry-unavailable") {
+            return this.applyIndeterminate(payment, {
+                gate: "registry-unavailable",
+                detail: "Metrik could not read its service registry, so it cannot tell whether this resource is one it tracks",
+            });
+        }
+        if (lookup.status !== "resolved" || lookup.resource === undefined) {
+            // Not a Metrik listing. Behave exactly like any other facilitator.
+            return {
+                ...payment,
+                metrik: {
+                    gate: "not-applicable",
+                    detail: "resource is not a Metrik-listed service; Metrik has no delivery opinion and applied no gate",
+                },
+            };
+        }
+        const resolved = lookup.resource;
+        // 3. The payee must be the operator who SIGNED the listing. This is the one
+        //    check that protects the payer rather than the seller: without it,
+        //    anyone could quote a Metrik-listed resource and redirect its payment to
+        //    their own address.
+        if (!addressesEqual(requirements.payTo, resolved.operator)) {
+            return {
+                isValid: false,
+                invalidReason: "invalid_exact_evm_payload_recipient_mismatch",
+                ...(payment.payer === undefined ? {} : { payer: payment.payer }),
+                metrik: {
+                    gate: "payee-mismatch",
+                    serviceRef: resolved.serviceRef,
+                    detail: `payTo ${requirements.payTo} is not the operator ${resolved.operator} who signed the listing ` +
+                        `for ${resolved.matchedOrigin}; refusing to settle a payment for a Metrik-listed resource to a different address`,
+                },
+            };
+        }
+        // 4. The differentiator.
+        const assessment = await this.deliveryOracle.verdictFor(resolved.serviceRef);
+        if (assessment.verdict === "failing") {
+            return {
+                isValid: false,
+                invalidReason: DELIVERY_REFUSAL_REASON,
+                ...(payment.payer === undefined ? {} : { payer: payment.payer }),
+                metrik: {
+                    gate: "refused",
+                    detail: `Metrik's oracle reports this service as FAILING its delivery checks ` +
+                        `(verdict recorded ${assessment.ageSeconds ?? "?"}s ago, within the ` +
+                        `${assessment.freshnessWindowSeconds}s freshness window). The payment itself is valid; ` +
+                        `Metrik is refusing to settle it. This prevents a payment — it does not recover one.`,
+                    ...assessmentFields(assessment, resolved.serviceRef),
+                },
+            };
+        }
+        if (assessment.verdict === "indeterminate") {
+            return this.applyIndeterminate(payment, {
+                gate: "indeterminate",
+                detail: `Metrik has no fresh delivery evidence for this service (${assessment.reason}; ` +
+                    `freshness window ${assessment.freshnessWindowSeconds}s). ` +
+                    `Policy is "${this.indeterminatePolicy}".`,
+                ...assessmentFields(assessment, resolved.serviceRef),
+            });
+        }
+        return {
+            ...payment,
+            metrik: {
+                gate: "passed",
+                detail: `Metrik's oracle recorded a passing delivery check for this service ` +
+                    `${assessment.ageSeconds ?? "?"}s ago. This is not an endorsement of output correctness — ` +
+                    `Metrik verifies delivery, not correctness.`,
+                ...assessmentFields(assessment, resolved.serviceRef),
+            },
+        };
+    }
+    applyIndeterminate(payment, annotation) {
+        if (this.indeterminatePolicy === "deny") {
+            return {
+                isValid: false,
+                invalidReason: DELIVERY_REFUSAL_REASON,
+                ...(payment.payer === undefined ? {} : { payer: payment.payer }),
+                metrik: {
+                    ...annotation,
+                    detail: `${annotation.detail} Refusing because this facilitator is configured to require positive fresh evidence.`,
+                },
+            };
+        }
+        return {
+            ...payment,
+            metrik: {
+                ...annotation,
+                detail: `${annotation.detail} Allowing: Metrik holds none of this money, so refusing would deny the ` +
+                    `service without protecting anyone. "isValid: true" here asserts only that the payment is ` +
+                    `well-formed — it is NOT a statement that the service is delivering.`,
+            },
+        };
+    }
+}
+function assessmentFields(assessment, serviceRef) {
+    return {
+        serviceRef,
+        deliveryVerdict: assessment.verdict,
+        deliveryReason: assessment.reason,
+        lastCheckedAt: assessment.lastCheckedAt,
+        verdictAgeSeconds: assessment.ageSeconds,
+        freshnessWindowSeconds: assessment.freshnessWindowSeconds,
+    };
+}
+function addressesEqual(a, b) {
+    try {
+        return getAddress(a) === getAddress(b);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Parses the facilitator wire body with the REAL x402 schemas. Both `/verify`
+ * and `/settle` take the same `{paymentPayload, paymentRequirements}` pair.
+ */
+export function parseFacilitatorRequest(body) {
+    if (typeof body !== "object" || body === null) {
+        return undefined;
+    }
+    const candidate = body;
+    const payload = PaymentPayloadSchema.safeParse(candidate.paymentPayload);
+    if (!payload.success) {
+        return undefined;
+    }
+    const requirements = PaymentRequirementsSchema.safeParse(candidate.paymentRequirements);
+    if (!requirements.success) {
+        return undefined;
+    }
+    return {
+        paymentPayload: payload.data,
+        paymentRequirements: requirements.data,
+    };
+}
+//# sourceMappingURL=verified-delivery-facilitator.js.map

package/dist/x402/verified-delivery-facilitator.js.map

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

package/dist/zktls/t2-delivery-proof.d.ts

@@ -161,17 +161,17 @@ export declare const deliveryProofRequestBodySchema: z.ZodObject<{
             identifier: z.ZodString;
         }, "strict", z.ZodTypeAny, {
             owner: string;
-            parameters: string;
             context: string;
             provider: string;
+            parameters: string;
             timestampS: number;
             epoch: number;
             identifier: string;
         }, {
             owner: string;
-            parameters: string;
             context: string;
             provider: string;
+            parameters: string;
             timestampS: number;
             epoch: number;
             identifier: string;
@@ -181,9 +181,9 @@ export declare const deliveryProofRequestBodySchema: z.ZodObject<{
         identifier: string;
         claimData: {
             owner: string;
-            parameters: string;
             context: string;
             provider: string;
+            parameters: string;
             timestampS: number;
             epoch: number;
             identifier: string;
@@ -193,9 +193,9 @@ export declare const deliveryProofRequestBodySchema: z.ZodObject<{
         identifier: string;
         claimData: {
             owner: string;
-            parameters: string;
             context: string;
             provider: string;
+            parameters: string;
             timestampS: number;
             epoch: number;
             identifier: string;
@@ -208,9 +208,9 @@ export declare const deliveryProofRequestBodySchema: z.ZodObject<{
         identifier: string;
         claimData: {
             owner: string;
-            parameters: string;
             context: string;
             provider: string;
+            parameters: string;
             timestampS: number;
             epoch: number;
             identifier: string;
@@ -236,9 +236,9 @@ export declare const deliveryProofRequestBodySchema: z.ZodObject<{
         identifier: string;
         claimData: {
             owner: string;
-            parameters: string;
             context: string;
             provider: string;
+            parameters: string;
             timestampS: number;
             epoch: number;
             identifier: string;

package/docs/agent-layer.md

@@ -15,14 +15,18 @@ fills exactly that gap, and the agent layer is where an agent experiences it.
 
 ## The four components
 
-### 1. x402 verified-streaming scheme
+### 1. Metrik verified-streaming `402` flow
 
-A StreamProof-flavored x402 scheme/facilitator: an agent hits an HTTP `402`, receives
-a _verified-streaming_ requirement (operator, serviceRef, rate, budget, settlement
+A Metrik-native HTTP `402` challenge flow: an agent hits a `402`, receives a
+_verified-streaming_ requirement (operator, serviceRef, rate, budget, settlement
 chain/escrow), responds with a signed-mandate payload, and a stream opens through the
-SDK — paying only for oracle-verified delivery, pausing on failure. The integration
-reuses the `402` challenge/response shape and the protocol's existing settlement path.
-(`src/x402/`)
+SDK — paying only for oracle-verified delivery. It borrows the _shape_ of an x402
+challenge/response and reuses the protocol's existing settlement path. (`src/x402/`)
+
+It is **not the x402 protocol**: its scheme string, challenge body, payload and
+`X-METRIK-PAYMENT` header are all Metrik's own, and it does not interoperate with
+`x402-fetch`, `x402-axios`, or `x402-express`. See [docs/x402.md](./x402.md) for the
+evidence and for what real x402 support would require.
 
 ### 2. MCP server
 
@@ -32,7 +36,8 @@ Every fund-moving tool is gated by a spend mandate, with JSON-serializable manda
 payloads and env-driven settlement config. The server also keeps a local stream
 registry so agents can list and reclaim the streams they opened. (`src/mcp/`)
 
-The server runs locally over stdio (`pnpm mcp:stdio`) or as a hosted,
+The server runs locally over stdio (the published `metrik-mcp` executable, or
+`pnpm mcp:stdio` in-repo) or as a hosted,
 multi-tenant, per-caller-authenticated endpoint over Streamable HTTP
 (`pnpm mcp:http`) — see [docs/mcp-hosted.md](./mcp-hosted.md).
 
@@ -124,7 +129,7 @@ proven live. Tracked separately if/when a paymaster is provisioned.
 
 ```mermaid
 flowchart LR
-    AGENT[AI agent] -->|MCP tool / x402 402| AL[Agent layer]
+    AGENT[AI agent] -->|MCP tool / Metrik 402| AL[Agent layer]
     AL -->|checkMandate| MND[Spend mandate]
     MND -->|allowed| SDK[@absol-labs/sdk]
     SDK --> ESC[Escrow on settlement chain]
@@ -146,5 +151,5 @@ flowchart LR
 
 ## Roadmap (see issues)
 
-x402 scheme → MCP server → framework adapters → example agents
+Metrik `402` flow → MCP server → framework adapters → example agents
 (hire + monitor + close on verification gaps) → wallet/provider integration.