@uuaid/pillar 0.2.0-alpha.9 → 2.0.1

package/src/vda/shims.mjs

@@ -0,0 +1,77 @@
+/**
+ * VDA-1 adoption shims (plan Phase 5) — wrap other protocols' settlement
+ * artifacts into VDA envelopes and emit VDA ids in their native shapes.
+ * The shims TRANSLATE; they never upgrade trust: an x402 settlement wraps
+ * into a `transfer` claim verified against the CHAIN (same instrument as
+ * any transfer), and an A2A artifact / MCP tool result carries the
+ * attestation, not a re-statement of it.
+ */
+import { normalizeClaim } from "./core.mjs";
+
+/**
+ * Map an x402 payment-settlement (HTTP 402 flow) onto a VDA transfer claim.
+ * x402 settles on-chain; its receipt fields name network, tx hash, payer,
+ * payee, asset, amount.  The output is a CLAIM — verification still runs
+ * through TransferVerifier against the chain, so the shim adds zero trust.
+ *
+ * settlement: { network: "eip155:<chainId>"|<chainId>, txHash, payer?,
+ *               payee, amount, asset? ("native" | erc20 address) }
+ */
+export function claimFromX402(settlement) {
+  const s = settlement ?? {};
+  let chainId = null;
+  if (typeof s.network === "string" && s.network.startsWith("eip155:")) chainId = Number(s.network.slice(7));
+  else if (s.network != null && !Number.isNaN(Number(s.network))) chainId = Number(s.network);
+  const asset = s.asset == null || s.asset === "native" ? "native"
+    : String(s.asset).startsWith("erc20:") ? String(s.asset) : `erc20:${String(s.asset)}`;
+  const n = normalizeClaim({
+    kind: "transfer", rail: "evm", chainId,
+    txId: s.txHash ?? s.txId ?? null,
+    from: s.payer ?? null, to: s.payee ?? null,
+    amount: s.amount != null ? String(s.amount) : null,
+    asset,
+  });
+  if (!n.ok) return { ok: false, reason: `x402-unmappable:${n.reason}` };
+  return { ok: true, claim: n.claim };
+}
+
+/**
+ * Emit an attestation as an A2A task artifact (A2A artifacts are named parts
+ * with data payloads).  The artifact carries the FULL envelope so any A2A
+ * client can verify offline; the name carries the content-addressed id.
+ */
+export function a2aArtifactOfAttestation(att) {
+  if (att?.kind !== "vda-attestation") throw new Error("a2a shim: not a vda-attestation");
+  return {
+    artifactId: `vda-${att.attestationId}`,
+    name: `vda-attestation:${att.attestationId}`,
+    description: `VDA-1 ${att.claim?.kind} attestation, verdict=${att.verdict}, verifier=${att.verifier ?? "unsigned"}`,
+    parts: [{ kind: "data", data: att }],
+  };
+}
+
+/**
+ * MCP tool descriptor for a server exposing VDA verification.  The handler
+ * wiring is host-specific; this is the portable contract (name, schema,
+ * annotations) so any MCP host can demand receipts the same way.
+ */
+export const MCP_VERIFY_TOOL = {
+  name: "vda_verify_transfer",
+  description:
+    "Verify that a transfer (native or ERC-20) actually settled on-chain, from the chain's own record. " +
+    "Returns a signed, content-addressed VDA-1 attestation verifiable offline. " +
+    "Verdicts: verified | failed | pending | instrument-blind | unsupported (fail-closed).",
+  inputSchema: {
+    type: "object",
+    required: ["chainId", "txId", "to", "amount"],
+    properties: {
+      chainId: { type: "integer", description: "EVM chain id (e.g. 137)" },
+      txId: { type: "string", description: "transaction hash" },
+      from: { type: "string", description: "expected sender (optional)" },
+      to: { type: "string", description: "expected recipient" },
+      amount: { type: "string", description: "decimal base units (wei) — string, never a number" },
+      asset: { type: "string", description: '"native" or "erc20:<tokenAddress>"' },
+    },
+  },
+  annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: true },
+};