M1-F: end-to-end LLM marketplace lifecycle on Vector testnet

Bonded-escrow marketplace for prompt → response between buyers and
local-LLM suppliers, settling on Vector (UTxO) via Aiken Plutus V3
validators. Lifecycle PostEscrow → Claim → Submit → Accept proven on
Vector testnet 2026-05-06; AcceptEscrow tx 125e3cfe…7dc100d distributes
payment + bonds per the validator's distribution rule.

Workspace layout (pnpm + TypeScript):
  contracts/marketplace/      Aiken validators (advert + escrow) + plutus.json
  packages/shared/            Tx-builders (lucid-evolution), CBOR codecs,
                              chain providers (mock / read-only / live Ogmios)
  supplier/                   OpenAI-compatible HTTP node (Ollama by default;
                              vLLM / llama.cpp / OpenRouter / OpenClaw all
                              swap-in via OLLAMA_URL); 202+poll chat handler
  buyer/                      Express + React SPA; server-side runs the full
                              chain lifecycle via /v1/submit-prompt and
                              /v1/accept; SPA never holds the buyer key
  indexer/                    Chain-follower (extends apex-dashboard pattern),
                              SSE event stream + REST queries
  indexer-ui/                 Operator dashboard (events + suppliers + escrow
                              lookup)
  tests/                      1098 vitest unit + integration tests (10 skipped
                              under M1-F-D-defer for UPLC test plumbing)
  deploy/testnet/             Per-service docker-compose for the Hetzner stack
  docs/EXECUTIVE_SUMMARY.*    Marp deck (PDF + PPTX) — 11 slides, mermaid
                              diagrams pre-rendered for portable export
  docs/CLOUDFLARE_WAF_BYPASS.md  CF Skip-rule runbook for /v1/* paths
  docs/ARCHITECTURE.md        canonical spec

Live demo (testnet, 2026-05-06):
  https://mp-buyers.vector.testnet.apexfusion.org      (buyer SPA)
  https://mp-suppliers.vector.testnet.apexfusion.org   (supplier API)
  https://mp-indexer.vector.testnet.apexfusion.org     (indexer + UI)

packages/shared/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@marketplace/shared",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./chain": "./src/chain/index.ts",
+    "./cbor": "./src/cbor/index.ts",
+    "./receipt": "./src/receipt/index.ts",
+    "./tx": "./src/tx/index.ts"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "cbor-x": "^1.5.4",
+    "typescript": "^5.7.2"
+  },
+  "dependencies": {
+    "@lucid-evolution/lucid": "^0.4.30",
+    "@noble/ed25519": "^2.3.0",
+    "bech32": "^2.0.0"
+  }
+}

packages/shared/src/cbor/AdvertDatum.ts

@@ -0,0 +1,198 @@
+/**
+ * AdvertDatum CBOR codec — ARCHITECTURE.md §4.1.
+ *
+ * On-chain encoding: Plutus Constr0 (tag 121) wrapping an array of 13 fields
+ * in declaration order:
+ *   0  supplier_pkh            Uint8Array(28, raw)
+ *   1  capability_id           Uint8Array(UTF-8)
+ *   2  model                   Uint8Array(UTF-8)
+ *   3  max_output_tokens       int
+ *   4  max_processing_ms       int
+ *   5  price_lovelace          bigint
+ *   6  supplier_bond_lovelace  bigint
+ *   7  buyer_bond_lovelace     bigint
+ *   8  endpoint_url            Uint8Array(UTF-8)
+ *   9  detail_uri              Uint8Array(UTF-8)
+ *   10 detail_hash             Uint8Array(32, raw)
+ *   11 advertised_at           int (POSIX ms)
+ *   12 status                  Tag 121 [] = Active | Tag 122 [] = Retired
+ *
+ * This codec uses cbor-x with the Plutus Tag extension (see registerPlutusTagExtension).
+ * The extension is registered once per process and is idempotent across modules that
+ * re-register it (buyer-side and supplier-side fixtures do the same).
+ */
+
+import { decode, Tag } from "cbor-x";
+import type { AdvertDatum, AdvertStatus } from "./types.js";
+import { plutusTag } from "./plutus-tag.js";
+import { encodePlutus } from "./plutus-encoder.js";
+
+export type { AdvertDatum };
+
+// ─── Byte helpers ────────────────────────────────────────────────────
+
+function hexToBytes(hex: string): Uint8Array {
+  if (hex.length % 2 !== 0) {
+    throw new Error(`invalid hex: odd length ${hex.length}`);
+  }
+  const bytes = new Uint8Array(hex.length / 2);
+  for (let i = 0; i < hex.length; i += 2) {
+    const byte = parseInt(hex.substring(i, i + 2), 16);
+    if (Number.isNaN(byte)) {
+      throw new Error(`invalid hex characters at offset ${i}`);
+    }
+    bytes[i / 2] = byte;
+  }
+  return bytes;
+}
+
+function bytesToHex(bytes: unknown): string {
+  let view: Uint8Array;
+  if (bytes instanceof Uint8Array) {
+    view = bytes;
+  } else if (Buffer.isBuffer(bytes)) {
+    view = new Uint8Array((bytes as Buffer).buffer, (bytes as Buffer).byteOffset, (bytes as Buffer).byteLength);
+  } else if (bytes instanceof ArrayBuffer) {
+    view = new Uint8Array(bytes);
+  } else {
+    throw new Error(`expected bytes, got ${typeof bytes}`);
+  }
+  return Array.from(view)
+    .map((b) => b.toString(16).padStart(2, "0"))
+    .join("");
+}
+
+function utf8Bytes(s: string): Uint8Array {
+  return new TextEncoder().encode(s);
+}
+
+function utf8Decode(bytes: unknown): string {
+  if (typeof bytes === "string") return bytes;
+  if (bytes instanceof Uint8Array) return new TextDecoder().decode(bytes);
+  if (Buffer.isBuffer(bytes)) return bytes.toString("utf8");
+  throw new Error(`expected bytes for UTF-8 decode, got ${typeof bytes}`);
+}
+
+function asBigInt(v: unknown): bigint {
+  if (typeof v === "bigint") return v;
+  if (typeof v === "number" && Number.isInteger(v)) return BigInt(v);
+  throw new Error(`expected integer, got ${typeof v}`);
+}
+
+function asInt(v: unknown): number {
+  if (typeof v === "number" && Number.isInteger(v)) return v;
+  if (typeof v === "bigint") {
+    if (v > BigInt(Number.MAX_SAFE_INTEGER) || v < BigInt(Number.MIN_SAFE_INTEGER)) {
+      throw new Error(`integer out of safe range: ${v}`);
+    }
+    return Number(v);
+  }
+  throw new Error(`expected integer, got ${typeof v}`);
+}
+
+function extractTag(value: unknown): { tag: number; fields: unknown[] } {
+  if (!(value instanceof Tag)) {
+    throw new Error(`expected CBOR Tag, got ${typeof value}`);
+  }
+  // cbor-x decodes into Tag with standard shape: .tag = tagNumber, .value = payload.
+  // Our Plutus-convention encoder uses the inverse shape (.value = tagNumber, .tag = payload)
+  // but that only applies to the encode path; decode always yields standard shape.
+  const tagNumber = typeof value.tag === "number" ? value.tag : typeof value.value === "number" ? value.value : NaN;
+  if (!Number.isFinite(tagNumber)) {
+    throw new Error("malformed CBOR tag: no numeric tag number");
+  }
+  const payload = value.value;
+  const fields = Array.isArray(payload) ? (payload as unknown[]) : [];
+  return { tag: tagNumber, fields };
+}
+
+// ─── Encode ──────────────────────────────────────────────────────────
+
+export function encodeAdvertDatum(d: AdvertDatum): string {
+  const statusTag =
+    d.status === "Active"
+      ? plutusTag(121, [])
+      : d.status === "Retired"
+        ? plutusTag(122, [])
+        : (() => {
+            throw new Error(`unknown AdvertStatus: ${String(d.status)}`);
+          })();
+
+  const cbor = plutusTag(121, [
+    hexToBytes(d.supplier_pkh),
+    utf8Bytes(d.capability_id),
+    utf8Bytes(d.model),
+    d.max_output_tokens,
+    d.max_processing_ms,
+    d.price_lovelace,
+    d.supplier_bond_lovelace,
+    d.buyer_bond_lovelace,
+    utf8Bytes(d.endpoint_url),
+    utf8Bytes(d.detail_uri),
+    hexToBytes(d.detail_hash),
+    d.advertised_at,
+    statusTag,
+  ]);
+
+  return bytesToHex(encodePlutus(cbor));
+}
+
+// ─── Decode ──────────────────────────────────────────────────────────
+
+const STATUS_MAP: Record<number, AdvertStatus> = {
+  121: "Active",
+  122: "Retired",
+};
+
+export function decodeAdvertDatum(hex: string): AdvertDatum {
+  if (!hex || hex.length === 0) {
+    throw new Error("decodeAdvertDatum: empty hex");
+  }
+  if (hex.length % 2 !== 0) {
+    throw new Error("decodeAdvertDatum: hex has odd length");
+  }
+  if (!/^[0-9a-fA-F]+$/.test(hex)) {
+    throw new Error("decodeAdvertDatum: non-hex characters");
+  }
+
+  let decoded: unknown;
+  try {
+    decoded = decode(hexToBytes(hex));
+  } catch (err) {
+    throw new Error(`decodeAdvertDatum: malformed CBOR: ${(err as Error).message}`);
+  }
+
+  const { tag, fields } = extractTag(decoded);
+  if (tag !== 121) {
+    throw new Error(`decodeAdvertDatum: expected Constr0 tag 121, got ${tag}`);
+  }
+  if (fields.length !== 13) {
+    throw new Error(`decodeAdvertDatum: expected 13 fields, got ${fields.length}`);
+  }
+
+  const statusField = fields[12];
+  if (!(statusField instanceof Tag)) {
+    throw new Error("decodeAdvertDatum: status must be a CBOR Tag");
+  }
+  const statusInfo = extractTag(statusField);
+  const status = STATUS_MAP[statusInfo.tag];
+  if (!status) {
+    throw new Error(`decodeAdvertDatum: unknown AdvertStatus tag ${statusInfo.tag}`);
+  }
+
+  return {
+    supplier_pkh: bytesToHex(fields[0]),
+    capability_id: utf8Decode(fields[1]),
+    model: utf8Decode(fields[2]),
+    max_output_tokens: asInt(fields[3]),
+    max_processing_ms: asInt(fields[4]),
+    price_lovelace: asBigInt(fields[5]),
+    supplier_bond_lovelace: asBigInt(fields[6]),
+    buyer_bond_lovelace: asBigInt(fields[7]),
+    endpoint_url: utf8Decode(fields[8]),
+    detail_uri: utf8Decode(fields[9]),
+    detail_hash: bytesToHex(fields[10]),
+    advertised_at: asInt(fields[11]),
+    status,
+  };
+}

packages/shared/src/cbor/EscrowDatum.ts

@@ -0,0 +1,267 @@
+/**
+ * EscrowDatum CBOR codec — ARCHITECTURE.md §4.2.
+ *
+ * On-chain encoding: Plutus Constr0 (tag 121) wrapping an array of 14 fields
+ * in declaration order:
+ *   0  buyer_pkh              Uint8Array(28, raw)
+ *   1  supplier_pkh           Uint8Array(28, raw)
+ *   2  advert_ref             Tag 121 [txHash:bytes(32), index:int]
+ *   3  capability_id          Uint8Array(UTF-8)
+ *   4  request_spec_hash      Uint8Array(32, raw)
+ *   5  prompt_hash            Uint8Array(32, raw)
+ *   6  payment_lovelace       bigint
+ *   7  buyer_bond_lovelace    bigint
+ *   8  supplier_bond_lovelace bigint
+ *   9  deliver_by             int (POSIX ms)
+ *   10 posted_at              int (POSIX ms)
+ *   11 submitted_at           Option<POSIXTime>  (None = Tag 122 [], Some v = Tag 121 [v])
+ *   12 result_receipt_hash    Option<ByteArray>  (None = Tag 122 [], Some v = Tag 121 [v])
+ *   13 state                  EscrowState: Open=121 … Released=126, each as Tag t []
+ */
+
+import { decode, Tag } from "cbor-x";
+import type { EscrowDatum, EscrowState } from "./types.js";
+import { plutusTag } from "./plutus-tag.js";
+import { encodePlutus } from "./plutus-encoder.js";
+
+export type { EscrowDatum };
+
+// ─── Helpers ─────────────────────────────────────────────────────────
+
+function hexToBytes(hex: string): Uint8Array {
+  if (hex.length % 2 !== 0) {
+    throw new Error(`invalid hex: odd length ${hex.length}`);
+  }
+  const bytes = new Uint8Array(hex.length / 2);
+  for (let i = 0; i < hex.length; i += 2) {
+    const byte = parseInt(hex.substring(i, i + 2), 16);
+    if (Number.isNaN(byte)) {
+      throw new Error(`invalid hex characters at offset ${i}`);
+    }
+    bytes[i / 2] = byte;
+  }
+  return bytes;
+}
+
+function bytesToHex(bytes: unknown): string {
+  let view: Uint8Array;
+  if (bytes instanceof Uint8Array) {
+    view = bytes;
+  } else if (Buffer.isBuffer(bytes)) {
+    view = new Uint8Array((bytes as Buffer).buffer, (bytes as Buffer).byteOffset, (bytes as Buffer).byteLength);
+  } else if (bytes instanceof ArrayBuffer) {
+    view = new Uint8Array(bytes);
+  } else {
+    throw new Error(`expected bytes, got ${typeof bytes}`);
+  }
+  return Array.from(view)
+    .map((b) => b.toString(16).padStart(2, "0"))
+    .join("");
+}
+
+function utf8Bytes(s: string): Uint8Array {
+  return new TextEncoder().encode(s);
+}
+
+function utf8Decode(bytes: unknown): string {
+  if (typeof bytes === "string") return bytes;
+  if (bytes instanceof Uint8Array) return new TextDecoder().decode(bytes);
+  if (Buffer.isBuffer(bytes)) return bytes.toString("utf8");
+  throw new Error(`expected bytes for UTF-8 decode, got ${typeof bytes}`);
+}
+
+function asBigInt(v: unknown): bigint {
+  if (typeof v === "bigint") return v;
+  if (typeof v === "number" && Number.isInteger(v)) return BigInt(v);
+  throw new Error(`expected integer, got ${typeof v}`);
+}
+
+function asInt(v: unknown): number {
+  if (typeof v === "number" && Number.isInteger(v)) return v;
+  if (typeof v === "bigint") {
+    if (v > BigInt(Number.MAX_SAFE_INTEGER) || v < BigInt(Number.MIN_SAFE_INTEGER)) {
+      throw new Error(`integer out of safe range: ${v}`);
+    }
+    return Number(v);
+  }
+  throw new Error(`expected integer, got ${typeof v}`);
+}
+
+function extractTag(value: unknown): { tag: number; fields: unknown[] } {
+  if (!(value instanceof Tag)) {
+    throw new Error(`expected CBOR Tag, got ${typeof value}`);
+  }
+  const tagNumber = typeof value.tag === "number" ? value.tag : typeof value.value === "number" ? value.value : NaN;
+  if (!Number.isFinite(tagNumber)) {
+    throw new Error("malformed CBOR tag: no numeric tag number");
+  }
+  const payload = value.value;
+  const fields = Array.isArray(payload) ? (payload as unknown[]) : [];
+  return { tag: tagNumber, fields };
+}
+
+// ─── State tag map ───────────────────────────────────────────────────
+
+const STATE_TAGS: Record<EscrowState, number> = {
+  Open: 121,
+  Claimed: 122,
+  Submitted: 123,
+  Accepted: 124,
+  Reclaimed: 125,
+  Released: 126,
+};
+
+const STATE_FROM_TAG: Record<number, EscrowState> = {
+  121: "Open",
+  122: "Claimed",
+  123: "Submitted",
+  124: "Accepted",
+  125: "Reclaimed",
+  126: "Released",
+};
+
+// ─── Option encoders ─────────────────────────────────────────────────
+
+/** Coerce a JS number to BigInt for CBOR major-type-0/1 emission.
+ * Plain `number` values are encoded as float64 by cbor-x for any value not
+ * representable as a CBOR int8/16/32 — but Plutus integers require major type
+ * 0 or 1 (positive/negative integer). CML.PlutusData.from_cbor_hex rejects
+ * floats, which surfaces as a wasm "unreachable" error. Converting all integer
+ * fields to BigInt before encoding sidesteps cbor-x's float heuristic. */
+function intAsBig(value: number): bigint {
+  return BigInt(value);
+}
+
+function encodeOptionInt(value: number | null): Tag {
+  return value === null ? plutusTag(122, []) : plutusTag(121, [intAsBig(value)]);
+}
+
+function encodeOptionBytes(value: string | null): Tag {
+  return value === null ? plutusTag(122, []) : plutusTag(121, [hexToBytes(value)]);
+}
+
+function decodeOptionInt(field: unknown): number | null {
+  const info = extractTag(field);
+  if (info.tag === 122) return null;
+  if (info.tag === 121) {
+    if (info.fields.length !== 1) {
+      throw new Error(`Option Some must contain exactly one field, got ${info.fields.length}`);
+    }
+    return asInt(info.fields[0]);
+  }
+  throw new Error(`Option: expected tag 121 (Some) or 122 (None), got ${info.tag}`);
+}
+
+function decodeOptionBytes(field: unknown): string | null {
+  const info = extractTag(field);
+  if (info.tag === 122) return null;
+  if (info.tag === 121) {
+    if (info.fields.length !== 1) {
+      throw new Error(`Option Some must contain exactly one field, got ${info.fields.length}`);
+    }
+    return bytesToHex(info.fields[0]);
+  }
+  throw new Error(`Option: expected tag 121 (Some) or 122 (None), got ${info.tag}`);
+}
+
+// ─── Encode ──────────────────────────────────────────────────────────
+
+export function encodeEscrowDatum(d: EscrowDatum): string {
+  const stateTagNumber = STATE_TAGS[d.state];
+  if (stateTagNumber === undefined) {
+    throw new Error(`unknown EscrowState: ${String(d.state)}`);
+  }
+
+  const advertRefTag = plutusTag(121, [
+    hexToBytes(d.advert_ref.txHash),
+    intAsBig(d.advert_ref.index),
+  ]);
+
+  const cbor = plutusTag(121, [
+    hexToBytes(d.buyer_pkh),
+    hexToBytes(d.supplier_pkh),
+    advertRefTag,
+    utf8Bytes(d.capability_id),
+    hexToBytes(d.request_spec_hash),
+    hexToBytes(d.prompt_hash),
+    d.payment_lovelace,
+    d.buyer_bond_lovelace,
+    d.supplier_bond_lovelace,
+    intAsBig(d.deliver_by),
+    intAsBig(d.posted_at),
+    encodeOptionInt(d.submitted_at),
+    encodeOptionBytes(d.result_receipt_hash),
+    plutusTag(stateTagNumber, []),
+  ]);
+
+  return bytesToHex(encodePlutus(cbor));
+}
+
+// ─── Decode ──────────────────────────────────────────────────────────
+
+export function decodeEscrowDatum(hex: string): EscrowDatum {
+  if (!hex || hex.length === 0) {
+    throw new Error("decodeEscrowDatum: empty hex");
+  }
+  if (hex.length % 2 !== 0) {
+    throw new Error("decodeEscrowDatum: hex has odd length");
+  }
+  if (!/^[0-9a-fA-F]+$/.test(hex)) {
+    throw new Error("decodeEscrowDatum: non-hex characters");
+  }
+
+  let decoded: unknown;
+  try {
+    decoded = decode(hexToBytes(hex));
+  } catch (err) {
+    throw new Error(`decodeEscrowDatum: malformed CBOR: ${(err as Error).message}`);
+  }
+
+  const { tag, fields } = extractTag(decoded);
+  if (tag !== 121) {
+    throw new Error(`decodeEscrowDatum: expected Constr0 tag 121, got ${tag}`);
+  }
+  if (fields.length !== 14) {
+    throw new Error(`decodeEscrowDatum: expected 14 fields, got ${fields.length}`);
+  }
+
+  // advert_ref
+  const advertRef = extractTag(fields[2]);
+  if (advertRef.tag !== 121) {
+    throw new Error(`decodeEscrowDatum: advert_ref expected tag 121, got ${advertRef.tag}`);
+  }
+  if (advertRef.fields.length !== 2) {
+    throw new Error(`decodeEscrowDatum: advert_ref expected 2 fields, got ${advertRef.fields.length}`);
+  }
+
+  // state
+  const stateField = fields[13];
+  if (!(stateField instanceof Tag)) {
+    throw new Error("decodeEscrowDatum: state must be a CBOR Tag");
+  }
+  const stateInfo = extractTag(stateField);
+  const state = STATE_FROM_TAG[stateInfo.tag];
+  if (!state) {
+    throw new Error(`decodeEscrowDatum: unknown EscrowState tag ${stateInfo.tag}`);
+  }
+
+  return {
+    buyer_pkh: bytesToHex(fields[0]),
+    supplier_pkh: bytesToHex(fields[1]),
+    advert_ref: {
+      txHash: bytesToHex(advertRef.fields[0]),
+      index: asInt(advertRef.fields[1]),
+    },
+    capability_id: utf8Decode(fields[3]),
+    request_spec_hash: bytesToHex(fields[4]),
+    prompt_hash: bytesToHex(fields[5]),
+    payment_lovelace: asBigInt(fields[6]),
+    buyer_bond_lovelace: asBigInt(fields[7]),
+    supplier_bond_lovelace: asBigInt(fields[8]),
+    deliver_by: asInt(fields[9]),
+    posted_at: asInt(fields[10]),
+    submitted_at: decodeOptionInt(fields[11]),
+    result_receipt_hash: decodeOptionBytes(fields[12]),
+    state,
+  };
+}

packages/shared/src/cbor/canonical.ts

@@ -0,0 +1,43 @@
+/**
+ * Canonical JSON — RFC-8785 JCS subset used for request_spec_hash,
+ * prompt_hash, and receipt hashing. Sorted keys, UTF-8 NFC, no whitespace.
+ *
+ * Scope:
+ *   - Object keys are sorted lexicographically (code-unit order).
+ *   - Strings are NFC-normalised (required so buyer/supplier produce bit-identical
+ *     output when inputs may use composed vs decomposed forms).
+ *   - No whitespace (default for JSON.stringify without indent).
+ *   - Arrays preserve their order (JCS mandates this — arrays are ordered).
+ *   - undefined values are dropped from objects (matches JSON.stringify).
+ *   - Numbers: delegated to JSON.stringify. JCS has stricter number rules, but
+ *     for M0 the callers pass well-formed JSON-compatible numbers only. M1 will
+ *     tighten this if real input exercises the edge cases.
+ *
+ * This function is intentionally tight; M1 can expand it as needs emerge.
+ */
+
+function sortKeys(value: unknown): unknown {
+  if (value === null || typeof value !== "object") {
+    if (typeof value === "string") return value.normalize("NFC");
+    return value;
+  }
+  if (Array.isArray(value)) {
+    return value.map(sortKeys);
+  }
+  const entries = Object.entries(value as Record<string, unknown>)
+    .filter(([, v]) => v !== undefined)
+    .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+  const out: Record<string, unknown> = {};
+  for (const [k, v] of entries) {
+    out[k.normalize("NFC")] = sortKeys(v);
+  }
+  return out;
+}
+
+/**
+ * canonicalize — produce a deterministic JSON string for hashing.
+ * Same input ⇒ bit-identical output across implementations.
+ */
+export function canonicalize(obj: unknown): string {
+  return JSON.stringify(sortKeys(obj));
+}

packages/shared/src/cbor/index.ts

@@ -0,0 +1,5 @@
+// Barrel export for CBOR codecs. Stub exports in M0-B; implementations in M0-C.
+export type { AdvertDatum, EscrowDatum, EscrowState, AdvertStatus, POSIXTime, VerificationKeyHash } from "./types.js";
+export { encodeAdvertDatum, decodeAdvertDatum } from "./AdvertDatum.js";
+export { encodeEscrowDatum, decodeEscrowDatum } from "./EscrowDatum.js";
+export { canonicalize } from "./canonical.js";

packages/shared/src/cbor/plutus-encoder.ts

@@ -0,0 +1,49 @@
+/**
+ * Plutus-compliant CBOR encoder — shared low-level machinery.
+ *
+ * Why this file exists
+ * --------------------
+ * Plutus validators reject CBOR tag 64 (0xd8 0x40) wrapping of bytestrings.
+ * They require BARE major-type-2 bytestrings (0x40..0x57 / 0x58 <len> / 0x59 <len:u16>
+ * / 0x5a <len:u32>). cbor-x's default behaviour wraps every Uint8Array in tag 64,
+ * which makes the resulting hex unusable on-chain.
+ *
+ * cbor-x exposes an `Encoder` option `tagUint8Array: false` that disables the
+ * tag-64 wrapping. We construct ONE Encoder instance with that option set, and
+ * also wire the Plutus-convention Tag extension (`registerPlutusTagExtension`)
+ * so Constr-style tags encode correctly.
+ *
+ * Sharing rationale (fixture isolation discipline preserved)
+ * ----------------------------------------------------------
+ * The "no shared source of truth" rule from ARCHITECTURE.md §7.2 applies to
+ * fixture-builder LOGIC — i.e. how each side constructs the datum from the
+ * spec. It does NOT apply to low-level CBOR machinery (Tag-extension wiring
+ * and the `tagUint8Array: false` flag), which are environmental rather than
+ * semantic. Both production codecs and fixture builders import this helper so
+ * they all agree on byte-level emission, while still independently constructing
+ * the datum payload from the spec.
+ */
+
+import { Encoder } from "cbor-x";
+import { registerPlutusTagExtension } from "./plutus-tag.js";
+
+// Register the Plutus Tag extension once, globally (cbor-x extension registry
+// is process-global; the registration is idempotent).
+registerPlutusTagExtension();
+
+/**
+ * The shared Plutus encoder. Disables tag-64 wrapping for `Uint8Array`, so byte
+ * fields emit as bare major-type-2 bytestrings as Plutus requires.
+ */
+const plutusEncoder = new Encoder({ tagUint8Array: false });
+
+/**
+ * encodePlutus — encode a value (Plutus-shaped Tags + bytes/ints/strings)
+ * into a CBOR byte buffer with bare bytestrings (no tag 64).
+ *
+ * Returned buffer is a `Uint8Array` view; callers that need hex should use
+ * their own bytesToHex helper.
+ */
+export function encodePlutus(value: unknown): Uint8Array {
+  return plutusEncoder.encode(value);
+}

packages/shared/src/cbor/plutus-tag.ts

@@ -0,0 +1,52 @@
+/**
+ * Plutus Tag extension for cbor-x.
+ *
+ * cbor-x's built-in Tag constructor is `new Tag(value, tagNumber)`, i.e.
+ *   .value = payload, .tag = tagNumber.
+ * Plutus convention (and the apex-dashboard codebase) uses the INVERSE:
+ *   new Tag(tagNumber, fieldsArray) → .value = tagNumber, .tag = fieldsArray.
+ *
+ * To make the Plutus-convention work with cbor-x's encoder, we install an
+ * extension that inspects each Tag instance during encode and picks the
+ * correct (tag, payload) pair. Decode is not affected — cbor-x always
+ * produces the standard shape when decoding.
+ *
+ * Registration is idempotent-ish: cbor-x accepts multiple addExtension calls
+ * for the same Class, but the last registered extension wins. All callers
+ * register an identical extension, so net behaviour is stable.
+ */
+
+import { Tag, addExtension } from "cbor-x";
+
+let registered = false;
+
+export function registerPlutusTagExtension(): void {
+  if (registered) return;
+  addExtension({
+    Class: Tag,
+    tag: undefined as unknown as number, // dynamic tag via getTag
+    encode(tag: Tag, encodeFn: (data: unknown) => Uint8Array): Uint8Array {
+      // Plutus convention: .value = numeric tag, .tag = payload array.
+      if (typeof tag.value === "number" && Array.isArray(tag.tag)) {
+        return encodeFn(tag.tag);
+      }
+      // Fallback: standard cbor-x convention.
+      return encodeFn(tag.value);
+    },
+    getTag(tag: Tag): number {
+      if (typeof tag.value === "number" && Array.isArray(tag.tag)) {
+        return tag.value;
+      }
+      return tag.tag as number;
+    },
+  } as unknown as Parameters<typeof addExtension>[0]);
+  registered = true;
+}
+
+/** Construct a Plutus-convention Tag instance (tagNumber, fieldsArray). */
+export function plutusTag(tagNumber: number, fields: unknown): Tag {
+  return new (Tag as unknown as new (a: unknown, b: unknown) => Tag)(
+    tagNumber,
+    fields,
+  );
+}

packages/shared/src/cbor/types.ts

@@ -0,0 +1,75 @@
+/**
+ * Type declarations for on-chain datum schemas.
+ * ARCHITECTURE.md sections 4.1 and 4.2.
+ *
+ * This file is TYPE-ONLY — no logic. Catherine fills in codecs in M0-C.
+ */
+
+import type { OutputReference } from "../chain/ChainProvider.js";
+
+/** POSIX time in milliseconds (Int on-chain). */
+export type POSIXTime = number;
+
+/** 28-byte verification key hash, lowercase hex. */
+export type VerificationKeyHash = string;
+
+/** AdvertStatus: mirrors Plutus constructor tag 121 (Active) / 122 (Retired). */
+export type AdvertStatus = "Active" | "Retired";
+
+/**
+ * AdvertDatum — ARCHITECTURE.md §4.1
+ *
+ * On-chain encoding: Plutus Constr0 (tag 121) with 13 fields in declaration order.
+ * ByteArray fields are UTF-8 where stated; VerificationKeyHash is raw bytes (28).
+ * detail_hash is raw bytes (32). price_lovelace and bond fields use bigint
+ * because they can exceed Number.MAX_SAFE_INTEGER for large AP3X denominations.
+ */
+export interface AdvertDatum {
+  supplier_pkh: VerificationKeyHash;        // 28-byte hex
+  capability_id: string;                    // "llm.text.generate.v1"
+  model: string;                            // "qwen2.5:0.5b"
+  max_output_tokens: number;                // Int
+  max_processing_ms: number;                // Int — SLA
+  price_lovelace: bigint;                   // AP3X lovelace
+  supplier_bond_lovelace: bigint;
+  buyer_bond_lovelace: bigint;
+  endpoint_url: string;                     // https://...
+  detail_uri: string;                       // off-chain JSON pointer
+  detail_hash: string;                      // 32-byte hex (sha256)
+  advertised_at: POSIXTime;
+  status: AdvertStatus;
+}
+
+/** EscrowState: mirrors Plutus constructor tags 121–126. */
+export type EscrowState =
+  | "Open"        // tag 121
+  | "Claimed"     // tag 122
+  | "Submitted"   // tag 123
+  | "Accepted"    // tag 124
+  | "Reclaimed"   // tag 125
+  | "Released";   // tag 126
+
+/**
+ * EscrowDatum — ARCHITECTURE.md §4.2
+ *
+ * On-chain encoding: Plutus Constr0 (tag 121) with 13 fields in declaration order.
+ * advert_ref encodes as Plutus OutputReference = Constr0[txHash:bytes, index:int].
+ * submitted_at and result_receipt_hash are Options: null → Constr1 (tag 122, None);
+ *   populated → Constr0 (tag 121, [value]) (Some).
+ */
+export interface EscrowDatum {
+  buyer_pkh: VerificationKeyHash;           // 28-byte hex
+  supplier_pkh: VerificationKeyHash;        // 28-byte hex
+  advert_ref: OutputReference;              // SPEC-LOCK: txHash + index
+  capability_id: string;                    // duplicated for indexer filter
+  request_spec_hash: string;               // 32-byte hex
+  prompt_hash: string;                     // 32-byte hex
+  payment_lovelace: bigint;
+  buyer_bond_lovelace: bigint;
+  supplier_bond_lovelace: bigint;
+  deliver_by: POSIXTime;
+  posted_at: POSIXTime;
+  submitted_at: POSIXTime | null;          // Option<POSIXTime>
+  result_receipt_hash: string | null;      // Option<ByteArray(32)>
+  state: EscrowState;
+}

packages/shared/src/chain/ChainProvider.ts

@@ -0,0 +1,96 @@
+/**
+ * ChainProvider — the single seam between off-chain code and the Cardano/Vector-L2 chain.
+ *
+ * Three implementations are planned (all arriving in M0-C, after Caroline's RED tests):
+ *   - MockChainProvider        (Tier 1) — in-memory, synthetic slots, full submit/await
+ *   - ReadOnlyOgmiosProvider   (Tier 2) — real Ogmios, eval + query only; submit/await throw NotSupportedError
+ *   - LiveOgmiosProvider       (Tier 3) — real Ogmios, full submit + await on real chain
+ *
+ * Tests MUST depend on this interface (DI), never on a concrete implementation.
+ * See docs/ARCHITECTURE.md section 7 for the test-architecture rationale.
+ */
+
+/** OutputReference — (txHash, index) pair uniquely identifying a UTxO on-chain. */
+export type OutputReference = { txHash: string; index: number };
+
+/** Slot number on the underlying chain (Cardano slot; Vector L2 inherits slot semantics). */
+export type SlotNo = number;
+
+/** Lovelace amount. ADA is 1e6 lovelace; AP3X uses its own decimals but is denominated here too. */
+export type Lovelace = bigint;
+
+/**
+ * Utxo — a single unspent output as returned by the chain query layer.
+ * `assets` key is the Cardano native-asset unit = policyId (hex) + assetName (hex); lovelace is separate.
+ * `datumHex` is the inline datum encoded as hex CBOR; null when no inline datum present.
+ * `scriptRef` is the inline script reference as hex; null when no reference script is attached.
+ */
+export interface Utxo {
+  ref: OutputReference;
+  address: string;
+  lovelace: Lovelace;
+  assets: Record<string, bigint>;
+  datumHex: string | null;
+  scriptRef: string | null;
+}
+
+/**
+ * TxEvaluationResult — structured result of a dry-run evaluation.
+ * `ok=true` ⇒ all scripts succeed and redeemer budget is within protocol limits.
+ * `cost` is the aggregate execution-units budget (memory + CPU steps).
+ * `error` carries a human-readable reason when `ok=false`.
+ */
+export interface TxEvaluationResult {
+  ok: boolean;
+  cost?: { memory: number; steps: number };
+  error?: string;
+}
+
+/**
+ * ChainProvider — contract for on-chain reads, tx evaluation, and submission.
+ * Implementations MUST be concurrency-safe for concurrent reads. Writes (`submitTx`)
+ * need not be thread-safe but MUST NOT double-submit on retry.
+ */
+export interface ChainProvider {
+  /** Current chain tip slot. */
+  tip(): Promise<SlotNo>;
+
+  /** Fetch a single UTxO by reference; returns null if the output is spent or was never created. */
+  queryUtxo(ref: OutputReference): Promise<Utxo | null>;
+
+  /** All unspent UTxOs at an address. Returns [] for an address with no UTxOs. */
+  queryUtxosByAddress(address: string): Promise<Utxo[]>;
+
+  /**
+   * Validate a CBOR-encoded transaction without broadcasting.
+   * Available in all three tiers. MUST NOT mutate chain state.
+   */
+  evaluateTx(txCborHex: string): Promise<TxEvaluationResult>;
+
+  /**
+   * Broadcast a signed transaction. Returns the resulting txHash.
+   * MockChainProvider simulates submission into its in-memory chain.
+   * ReadOnlyOgmiosProvider MUST throw `NotSupportedError` (cannot mutate chain state).
+   * LiveOgmiosProvider performs a real broadcast.
+   */
+  submitTx(txCborHex: string): Promise<string>;
+
+  /**
+   * Wait until a transaction with the given hash is observed on-chain.
+   * Rejects with a timeout error after `timeoutMs`.
+   * MockChainProvider resolves immediately if the tx is already in its known-tx set; otherwise rejects after timeout.
+   * ReadOnlyOgmiosProvider MUST throw `NotSupportedError`.
+   * LiveOgmiosProvider polls the real chain.
+   */
+  awaitTx(txHash: string, timeoutMs: number): Promise<void>;
+}
+
+/** Raised by ReadOnly / Mock providers when a caller invokes an operation that would mutate chain state. */
+export class NotSupportedError extends Error {
+  public readonly op: string;
+  constructor(op: string) {
+    super(`operation not supported in this provider: ${op}`);
+    this.name = "NotSupportedError";
+    this.op = op;
+  }
+}

packages/shared/src/chain/LiveOgmiosProvider.ts

@@ -0,0 +1,307 @@
+/**
+ * LiveOgmiosProvider — Tier-3 ChainProvider.
+ *
+ * Implements the full ChainProvider interface against a real Ogmios server:
+ *   - tip(), queryUtxo(), queryUtxosByAddress(), evaluateTx() — identical to
+ *     ReadOnlyOgmiosProvider; implemented via composition (holds an inner
+ *     ReadOnlyOgmiosProvider and forwards all read calls).
+ *   - submitTx(txCborHex) — HTTP POST JSON-RPC `submitTransaction` to ogmiosUrl.
+ *     Returns the resulting txHash string from `result.transaction.id`.
+ *     On Ogmios JSON-RPC error, throws OgmiosSubmitError (structured: name,
+ *     code, data fields preserved for upstream retry / dispute flows).
+ *   - awaitTx(txHash, timeoutMs) — polls `queryLedgerState/utxo` every
+ *     pollIntervalMs (default 2000 ms) using a synthetic OutputReference
+ *     {transaction:{id:txHash}, index:0} and resolves when ANY returned UTxO
+ *     has `transaction.id === txHash` (index-agnostic). Rejects after
+ *     timeoutMs via AbortController (the in-flight fetch is aborted too).
+ *
+ * JSON-RPC id: submitTx uses globalThis.crypto.randomUUID() (Node 19+ /
+ * modern browser). Tests assert UUID v4 format on the request id field.
+ */
+
+import type {
+  ChainProvider,
+  OutputReference,
+  SlotNo,
+  TxEvaluationResult,
+  Utxo,
+} from "./ChainProvider.js";
+import { ReadOnlyOgmiosProvider } from "./ReadOnlyOgmiosProvider.js";
+
+export interface LiveOgmiosProviderOpts {
+  ogmiosUrl: string;
+  /** Request timeout in milliseconds for read calls and submitTx. Defaults to 30 s. */
+  timeoutMs?: number;
+  /** Polling interval in milliseconds for awaitTx. Defaults to 2000 ms. */
+  pollIntervalMs?: number;
+  /** Injected fetch for testing. Defaults to globalThis.fetch resolved at call time. */
+  fetch?: typeof globalThis.fetch;
+}
+
+/**
+ * Thrown by LiveOgmiosProvider.submitTx when Ogmios returns a JSON-RPC error.
+ *
+ * `code`  — JSON-RPC error code from the Ogmios response.
+ * `data`  — JSON-RPC error data field (may be undefined).
+ */
+export class OgmiosSubmitError extends Error {
+  public readonly code: number;
+  public readonly data: unknown;
+  constructor(message: string, code: number, data?: unknown) {
+    super(message);
+    this.name = "OgmiosSubmitError";
+    this.code = code;
+    this.data = data;
+  }
+}
+
+interface JsonRpcResponse<T> {
+  jsonrpc: "2.0";
+  result?: T;
+  error?: { code: number; message: string; data?: unknown };
+}
+
+interface OgmiosUtxoMin {
+  transaction?: { id?: string };
+  index?: number;
+}
+
+interface OgmiosSubmitResult {
+  transaction?: { id?: string };
+}
+
+export class LiveOgmiosProvider implements ChainProvider {
+  private readonly read: ReadOnlyOgmiosProvider;
+  private readonly ogmiosUrl: string;
+  private readonly timeoutMs: number;
+  private readonly pollIntervalMs: number;
+  private readonly injectedFetch?: typeof globalThis.fetch;
+
+  constructor(opts: LiveOgmiosProviderOpts) {
+    // Forward read methods to a private ReadOnlyOgmiosProvider so request
+    // bodies are byte-identical to the read-only path (composition parity).
+    this.read = new ReadOnlyOgmiosProvider({
+      ogmiosUrl: opts.ogmiosUrl,
+      timeoutMs: opts.timeoutMs,
+      fetch: opts.fetch,
+    });
+    this.ogmiosUrl = opts.ogmiosUrl;
+    this.timeoutMs = opts.timeoutMs ?? 30_000;
+    this.pollIntervalMs = opts.pollIntervalMs ?? 2_000;
+    this.injectedFetch = opts.fetch;
+  }
+
+  /** Expose the underlying Ogmios URL so live tx builders can construct an
+   * OgmiosLucidProvider against the same endpoint. */
+  public get url(): string {
+    return this.ogmiosUrl;
+  }
+
+  /** Expose the injected fetch so live tx builders can route lucid traffic
+   * through the same test mock the chain provider uses. */
+  public get fetchImpl(): typeof globalThis.fetch | undefined {
+    return this.injectedFetch;
+  }
+
+  // ── Read methods — forward to inner ReadOnlyOgmiosProvider ──────────
+
+  tip(): Promise<SlotNo> {
+    return this.read.tip();
+  }
+
+  queryUtxo(ref: OutputReference): Promise<Utxo | null> {
+    return this.read.queryUtxo(ref);
+  }
+
+  queryUtxosByAddress(address: string): Promise<Utxo[]> {
+    return this.read.queryUtxosByAddress(address);
+  }
+
+  evaluateTx(txCborHex: string): Promise<TxEvaluationResult> {
+    return this.read.evaluateTx(txCborHex);
+  }
+
+  // ── submitTx ──────────────────────────────────────────────────────
+
+  async submitTx(txCborHex: string): Promise<string> {
+    const id = generateUuid();
+    const body = JSON.stringify({
+      jsonrpc: "2.0",
+      method: "submitTransaction",
+      params: { transaction: { cbor: txCborHex } },
+      id,
+    });
+
+    const init: RequestInit = {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body,
+    };
+    if (typeof AbortSignal !== "undefined" && typeof AbortSignal.timeout === "function") {
+      init.signal = AbortSignal.timeout(this.timeoutMs);
+    }
+
+    const fetcher = this.resolveFetch();
+    const response = await fetcher(this.ogmiosUrl, init);
+    if (!response.ok) {
+      let bodyText = "";
+      try { bodyText = await response.text(); } catch { /* noop */ }
+      throw new Error(
+        `Ogmios HTTP error: ${response.status} ${response.statusText} :: ${bodyText.slice(0, 1500)}`,
+      );
+    }
+
+    const json = (await response.json()) as JsonRpcResponse<OgmiosSubmitResult>;
+    if (json.error) {
+      throw new OgmiosSubmitError(
+        json.error.message ?? "Ogmios submit error",
+        json.error.code,
+        json.error.data,
+      );
+    }
+    const txId = json.result?.transaction?.id;
+    if (typeof txId !== "string" || txId.length === 0) {
+      throw new Error(
+        `submit_malformed_response: Ogmios did not return result.transaction.id (got ${JSON.stringify(json.result)})`,
+      );
+    }
+    return txId;
+  }
+
+  // ── awaitTx ───────────────────────────────────────────────────────
+
+  async awaitTx(txHash: string, timeoutMs: number): Promise<void> {
+    const controller = new AbortController();
+    const timeoutHandle = setTimeout(() => controller.abort(), timeoutMs);
+    const deadline = Date.now() + timeoutMs;
+
+    try {
+      // First poll runs immediately (no leading sleep): if the tx is already
+      // confirmed, the call returns after a single fetch.
+      while (true) {
+        if (controller.signal.aborted) {
+          throw new Error(`awaitTx_timeout: tx ${txHash} not observed within ${timeoutMs}ms`);
+        }
+
+        const found = await this.checkOnce(txHash, controller.signal);
+        if (found) return;
+
+        if (Date.now() >= deadline || controller.signal.aborted) {
+          throw new Error(`awaitTx_timeout: tx ${txHash} not observed within ${timeoutMs}ms`);
+        }
+
+        // Sleep poll-interval, but interruptible by the abort signal.
+        await sleepInterruptible(this.pollIntervalMs, controller.signal, txHash, timeoutMs);
+      }
+    } finally {
+      clearTimeout(timeoutHandle);
+    }
+  }
+
+  private async checkOnce(txHash: string, signal: AbortSignal): Promise<boolean> {
+    const body = JSON.stringify({
+      jsonrpc: "2.0",
+      method: "queryLedgerState/utxo",
+      params: {
+        outputReferences: [{ transaction: { id: txHash }, index: 0 }],
+      },
+      // awaitTx polls don't need a UUID — a numeric counter would suffice,
+      // but we use a UUID for consistency with submitTx / debuggability.
+      id: generateUuid(),
+    });
+
+    const init: RequestInit = {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body,
+      signal,
+    };
+
+    const fetcher = this.resolveFetch();
+    // Race the fetch against the abort signal. Real `fetch` rejects when its
+    // signal aborts, but test mocks may not honour signals — so we add an
+    // explicit abort race so the await terminates promptly when the timeout
+    // controller fires.
+    const fetchPromise = fetcher(this.ogmiosUrl, init);
+    const response = await Promise.race([fetchPromise, abortRace(signal)]);
+    if (!response.ok) {
+      // Network blip during polling — fall through to the next poll rather
+      // than aborting the whole await. Only the timeout signal terminates.
+      return false;
+    }
+
+    const json = (await response.json()) as JsonRpcResponse<OgmiosUtxoMin[]>;
+    if (json.error || !Array.isArray(json.result)) return false;
+
+    // Index-agnostic: if any UTxO with this txHash is returned, the tx is on
+    // chain. Ogmios can return a UTxO at index > 0 even when we asked at 0.
+    return json.result.some((u) => u?.transaction?.id === txHash);
+  }
+
+  private resolveFetch(): typeof globalThis.fetch {
+    // Resolve at call time so test reassignments of globalThis.fetch take
+    // effect even when the provider was constructed before the reassignment.
+    return this.injectedFetch ?? globalThis.fetch;
+  }
+}
+
+// ── Helpers ──────────────────────────────────────────────────────────
+
+function generateUuid(): string {
+  // globalThis.crypto.randomUUID is available in Node 19+ and modern browsers.
+  // Vitest under Node 20 exposes it. We do not depend on the `uuid` package.
+  const c = globalThis.crypto;
+  if (c && typeof c.randomUUID === "function") {
+    return c.randomUUID();
+  }
+  // Fallback — should not be reached in supported runtimes. Generates a
+  // pseudo-UUIDv4-shaped string from Math.random; only used if crypto is
+  // unavailable (e.g. very old Node). Tests run on Node 20+ where the
+  // primary path is taken.
+  const hex = (n: number) => Math.floor(Math.random() * 16 ** n).toString(16).padStart(n, "0");
+  return `${hex(8)}-${hex(4)}-4${hex(3)}-${(8 + Math.floor(Math.random() * 4)).toString(16)}${hex(3)}-${hex(12)}`;
+}
+
+/**
+ * Returns a Promise that rejects when the given AbortSignal aborts. Used to
+ * race against a fetch promise so awaitTx can terminate promptly even when
+ * the underlying fetch implementation does not honour its signal (e.g. test
+ * mocks that return a never-resolving promise).
+ */
+function abortRace(signal: AbortSignal): Promise<never> {
+  return new Promise<never>((_resolve, reject) => {
+    if (signal.aborted) {
+      reject(new Error("awaitTx_timeout: aborted"));
+      return;
+    }
+    signal.addEventListener(
+      "abort",
+      () => reject(new Error("awaitTx_timeout: aborted")),
+      { once: true },
+    );
+  });
+}
+
+function sleepInterruptible(
+  ms: number,
+  signal: AbortSignal,
+  txHash: string,
+  timeoutMs: number,
+): Promise<void> {
+  return new Promise((resolve, reject) => {
+    if (signal.aborted) {
+      reject(new Error(`awaitTx_timeout: tx ${txHash} not observed within ${timeoutMs}ms`));
+      return;
+    }
+    const timer = setTimeout(() => {
+      signal.removeEventListener("abort", onAbort);
+      resolve();
+    }, ms);
+    const onAbort = () => {
+      clearTimeout(timer);
+      signal.removeEventListener("abort", onAbort);
+      reject(new Error(`awaitTx_timeout: tx ${txHash} not observed within ${timeoutMs}ms`));
+    };
+    signal.addEventListener("abort", onAbort, { once: true });
+  });
+}

packages/shared/src/chain/MockChainProvider.ts

@@ -0,0 +1,256 @@
+/**
+ * MockChainProvider — Tier 1, in-memory implementation of ChainProvider.
+ *
+ * Implements the full ChainProvider interface plus test-only extensions
+ * (advanceSlot, seed, buildTestTx). Intended to drive unit tests without
+ * touching a real node or Ogmios.
+ *
+ * Semantics:
+ *   - Synthetic slot counter (starts at 0, never auto-advances).
+ *   - In-memory UTxO store keyed by "txHash#index".
+ *   - submitTx returns sha256(txCborHex) as a 64-char lowercase hex string,
+ *     idempotent on identical input, and attempts a best-effort JSON decode
+ *     of the hex to recognise synthetic "spending" txs produced by tests.
+ *   - awaitTx resolves immediately when the hash is already known; otherwise
+ *     polls every ~10ms up to timeoutMs and then rejects with a timeout.
+ */
+
+// Namespace import — see blueprint.ts header.
+import * as nodeCrypto from "crypto";
+import type {
+  ChainProvider,
+  OutputReference,
+  SlotNo,
+  TxEvaluationResult,
+  Utxo,
+} from "./ChainProvider.js";
+
+export interface MockChainProviderOpts {
+  /** Custom evaluator. Default: always returns { ok: true }. */
+  evaluator?: (txCborHex: string) => TxEvaluationResult;
+}
+
+/** Shape accepted by MockChainProvider.buildTestTx for synthetic spending txs. */
+export interface TestTxShape {
+  inputs: OutputReference[];
+  outputs?: Utxo[];
+}
+
+function refKey(ref: OutputReference): string {
+  return `${ref.txHash}#${ref.index}`;
+}
+
+function hexToString(hex: string): string | null {
+  if (hex.length % 2 !== 0) return null;
+  if (!/^[0-9a-fA-F]+$/.test(hex)) return null;
+  try {
+    const buf = Buffer.from(hex, "hex");
+    return buf.toString("utf8");
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Extract the JSON portion of a length-prefixed test-tx hex.
+ *
+ * Test-tx format:
+ *   first 8 hex chars (4 bytes) = big-endian uint32 JSON byte length
+ *   next N bytes                = JSON UTF-8 payload
+ *   trailing bytes              = free-form trailer (may include raw pkh bytes
+ *                                 so tests can assert toContain(pkhHex))
+ *
+ * Returns the JSON string or null if the hex is not in this format.
+ */
+function extractTestTxJson(hex: string): string | null {
+  if (hex.length < 8) return null;
+  if (hex.length % 2 !== 0) return null;
+  if (!/^[0-9a-fA-F]+$/.test(hex)) return null;
+
+  const lenHex = hex.slice(0, 8);
+  const jsonLen = parseInt(lenHex, 16);
+  if (!Number.isFinite(jsonLen) || jsonLen <= 0) return null;
+
+  const jsonHexLen = jsonLen * 2;
+  if (8 + jsonHexLen > hex.length) return null;
+
+  const jsonHex = hex.slice(8, 8 + jsonHexLen);
+  try {
+    const buf = Buffer.from(jsonHex, "hex");
+    return buf.toString("utf8");
+  } catch {
+    return null;
+  }
+}
+
+export class MockChainProvider implements ChainProvider {
+  private readonly evaluator: (txCborHex: string) => TxEvaluationResult;
+  private currentSlot: SlotNo;
+  private readonly utxos: Map<string, Utxo>;
+  private readonly knownTxs: Map<string, string>;
+
+  constructor(opts?: MockChainProviderOpts) {
+    this.evaluator = opts?.evaluator ?? (() => ({ ok: true }));
+    this.currentSlot = 0;
+    this.utxos = new Map();
+    this.knownTxs = new Map();
+  }
+
+  // ── ChainProvider interface ─────────────────────────────────────────
+
+  async tip(): Promise<SlotNo> {
+    return this.currentSlot;
+  }
+
+  async queryUtxo(ref: OutputReference): Promise<Utxo | null> {
+    return this.utxos.get(refKey(ref)) ?? null;
+  }
+
+  async queryUtxosByAddress(address: string): Promise<Utxo[]> {
+    const out: Utxo[] = [];
+    for (const u of this.utxos.values()) {
+      if (u.address === address) out.push(u);
+    }
+    return out;
+  }
+
+  async evaluateTx(txCborHex: string): Promise<TxEvaluationResult> {
+    return this.evaluator(txCborHex);
+  }
+
+  async submitTx(txCborHex: string): Promise<string> {
+    const hash = nodeCrypto.createHash("sha256")
+      .update(txCborHex, "utf8")
+      .digest("hex")
+      .toLowerCase();
+
+    if (!this.knownTxs.has(hash)) {
+      this.knownTxs.set(hash, txCborHex);
+      this.applySpendingSideEffects(txCborHex, hash);
+    }
+
+    return hash;
+  }
+
+  async awaitTx(txHash: string, timeoutMs: number): Promise<void> {
+    if (this.knownTxs.has(txHash)) return;
+
+    const pollInterval = 10;
+    const deadline = Date.now() + timeoutMs;
+
+    while (Date.now() < deadline) {
+      const remaining = deadline - Date.now();
+      const wait = Math.min(pollInterval, Math.max(0, remaining));
+      await new Promise<void>((resolve) => setTimeout(resolve, wait));
+      if (this.knownTxs.has(txHash)) return;
+    }
+
+    throw new Error(
+      `awaitTx timeout after ${timeoutMs}ms waiting for txHash ${txHash}`,
+    );
+  }
+
+  // ── Test-only extensions (NOT part of ChainProvider) ────────────────
+
+  /** Advance synthetic tip by n slots. n MUST be a non-negative integer. */
+  advanceSlot(n: number): void {
+    if (!Number.isInteger(n) || n < 0) {
+      throw new Error(`advanceSlot: n must be a non-negative integer, got ${n}`);
+    }
+    this.currentSlot += n;
+  }
+
+  /** Plant a UTxO in the in-memory store. Overwrites an existing entry with the same ref. */
+  seed(utxo: Utxo): void {
+    this.utxos.set(refKey(utxo.ref), utxo);
+  }
+
+  /**
+   * Build a synthetic tx CBOR hex that MockChainProvider recognises as a
+   * spending tx. The hex is hex(JSON.stringify({ inputs, outputs? })).
+   */
+  static buildTestTx(shape: TestTxShape): string {
+    return Buffer.from(JSON.stringify(shape), "utf8").toString("hex");
+  }
+
+  // ── Internals ───────────────────────────────────────────────────────
+
+  /**
+   * Best-effort decode of the tx CBOR hex as a JSON test-tx. If parsing
+   * succeeds, any matching UTxOs in `inputs` are removed from the store and
+   * any UTxOs in `outputs` are seeded. Anything else is ignored.
+   *
+   * The `outputs` extension is used by M1-B tx builders so that calling
+   * `submitTx` simulates the on-chain effect of producing continuing or
+   * terminal outputs (extending the existing `inputs`-only convention).
+   *
+   * Outputs may use the placeholder string "$self" for ref.txHash to mean
+   * "the hash of this tx itself" — resolved by the caller-supplied `selfHash`
+   * arg. This sidesteps the circular dependency between sha256(txCborHex) and
+   * outputs that need to reference their own tx hash.
+   *
+   * BigInt support: lovelace fields may arrive as strings (JSON has no bigint)
+   * with a "n" suffix or as plain numbers; we accept both.
+   */
+  private applySpendingSideEffects(txCborHex: string, selfHash: string): void {
+    // Try the M1-B length-prefixed format first; fall back to the legacy M0
+    // bare-JSON format used by mock-chain-provider tests.
+    const asText = extractTestTxJson(txCborHex) ?? hexToString(txCborHex);
+    if (asText === null) return;
+
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(asText, (_key, value) => {
+        if (typeof value === "string" && /^-?\d+n$/.test(value)) {
+          return BigInt(value.slice(0, -1));
+        }
+        return value;
+      });
+    } catch {
+      return;
+    }
+
+    if (!parsed || typeof parsed !== "object") return;
+
+    const maybeInputs = (parsed as { inputs?: unknown }).inputs;
+    if (Array.isArray(maybeInputs)) {
+      for (const input of maybeInputs) {
+        if (!input || typeof input !== "object") continue;
+        const rec = input as { txHash?: unknown; index?: unknown };
+        if (typeof rec.txHash !== "string") continue;
+        if (typeof rec.index !== "number") continue;
+        this.utxos.delete(refKey({ txHash: rec.txHash, index: rec.index }));
+      }
+    }
+
+    const maybeOutputs = (parsed as { outputs?: unknown }).outputs;
+    if (Array.isArray(maybeOutputs)) {
+      for (const output of maybeOutputs) {
+        if (!output || typeof output !== "object") continue;
+        const rec = output as Partial<Utxo>;
+        if (!rec.ref || typeof rec.ref !== "object") continue;
+        const ref = rec.ref as { txHash?: unknown; index?: unknown };
+        if (typeof ref.txHash !== "string") continue;
+        if (typeof ref.index !== "number") continue;
+        if (typeof rec.address !== "string") continue;
+
+        const resolvedTxHash = ref.txHash === "$self" ? selfHash : ref.txHash;
+
+        const utxo: Utxo = {
+          ref: { txHash: resolvedTxHash, index: ref.index },
+          address: rec.address,
+          lovelace:
+            typeof rec.lovelace === "bigint"
+              ? rec.lovelace
+              : typeof rec.lovelace === "number"
+                ? BigInt(rec.lovelace)
+                : 0n,
+          assets: (rec.assets ?? {}) as Record<string, bigint>,
+          datumHex: typeof rec.datumHex === "string" ? rec.datumHex : null,
+          scriptRef: typeof rec.scriptRef === "string" ? rec.scriptRef : null,
+        };
+        this.utxos.set(refKey(utxo.ref), utxo);
+      }
+    }
+  }
+}

packages/shared/src/chain/OgmiosLucidProvider.ts

@@ -0,0 +1,539 @@
+/**
+ * OgmiosLucidProvider — lucid-evolution Provider backed by Ogmios JSON-RPC.
+ *
+ * Implements the lucid-evolution Provider interface without Kupo. All UTxO
+ * queries, protocol-parameter fetches, and tx submission/evaluation route
+ * through a single Ogmios endpoint. Delegation and asset-filter methods are
+ * stubbed (NotSupportedInM1F4Error) — the M1-F-4 happy path doesn't exercise
+ * stake delegation or unit filtering.
+ *
+ * JSON-RPC ids use globalThis.crypto.randomUUID(); no `uuid` package dependency.
+ *
+ * Catherine M1-F-4-green.
+ */
+
+import type {
+  Address,
+  Credential,
+  Datum,
+  DatumHash,
+  Delegation,
+  EvalRedeemer,
+  OutRef,
+  ProtocolParameters,
+  Provider,
+  RewardAddress,
+  Transaction,
+  TxHash,
+  UTxO,
+  Unit,
+} from "@lucid-evolution/lucid";
+
+export interface OgmiosLucidProviderOpts {
+  ogmiosUrl: string;
+  timeoutMs?: number;
+  /** Injected fetch for testing. Defaults to globalThis.fetch. */
+  fetch?: typeof globalThis.fetch;
+}
+
+/**
+ * Thrown when OgmiosLucidProvider is called with an unsupported method
+ * in M1-F-4 (e.g. getDelegation, getUtxosWithUnit, getUtxoByUnit).
+ */
+export class NotSupportedInM1F4Error extends Error {
+  constructor(method: string) {
+    super(`OgmiosLucidProvider.${method}: not supported in M1-F-4; stub only`);
+    this.name = "NotSupportedInM1F4Error";
+  }
+}
+
+interface JsonRpcResponse<T> {
+  jsonrpc: "2.0";
+  result?: T;
+  error?: { code: number; message: string; data?: unknown };
+}
+
+interface OgmiosUtxo {
+  transaction: { id: string };
+  index: number;
+  address: string;
+  value: { ada?: { lovelace?: number | bigint }; [policy: string]: unknown };
+  datumHash?: string | null;
+  datum?: string | null;
+  script?: unknown;
+}
+
+interface OgmiosBudget {
+  memory?: number;
+  cpu?: number;
+  steps?: number;
+}
+
+interface OgmiosEvalRedeemer {
+  validator?: { purpose?: string; index?: number } | string;
+  budget?: OgmiosBudget;
+}
+
+interface OgmiosProtocolParams {
+  minFeeCoefficient?: number;
+  minFeeConstant?: { ada?: { lovelace?: number | bigint } };
+  maxTransactionSize?: { bytes?: number };
+  maxValueSize?: { bytes?: number };
+  stakeCredentialDeposit?: { ada?: { lovelace?: number | bigint } };
+  stakePoolDeposit?: { ada?: { lovelace?: number | bigint } };
+  governanceActionDeposit?: { ada?: { lovelace?: number | bigint } };
+  delegateRepresentativeDeposit?: { ada?: { lovelace?: number | bigint } };
+  prices?: { memory?: string | number; steps?: string | number };
+  scriptExecutionPrices?: { memory?: string | number; steps?: string | number };
+  maxExecutionUnitsPerTransaction?: {
+    memory?: number | bigint;
+    cpu?: number | bigint;
+    steps?: number | bigint;
+  };
+  coinsPerUtxoByte?: { ada?: { lovelace?: number | bigint } };
+  collateralPercentage?: number;
+  maxCollateralInputs?: number;
+  plutusCostModels?: Record<string, number[] | Record<string, number>>;
+  minFeeReferenceScripts?: { base?: number };
+}
+
+export class OgmiosLucidProvider implements Provider {
+  private readonly ogmiosUrl: string;
+  private readonly timeoutMs: number;
+  private readonly injectedFetch?: typeof globalThis.fetch;
+
+  constructor(opts: OgmiosLucidProviderOpts) {
+    this.ogmiosUrl = opts.ogmiosUrl;
+    this.timeoutMs = opts.timeoutMs ?? 30_000;
+    this.injectedFetch = opts.fetch;
+  }
+
+  // ── HTTP helper ──────────────────────────────────────────────────────
+
+  private async rpc<TResult>(method: string, params?: unknown): Promise<TResult> {
+    const body: Record<string, unknown> = {
+      jsonrpc: "2.0",
+      method,
+      id: this.generateId(),
+    };
+    if (params !== undefined) body.params = params;
+
+    const init: RequestInit = {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(body),
+    };
+    if (typeof AbortSignal !== "undefined" && typeof AbortSignal.timeout === "function") {
+      init.signal = AbortSignal.timeout(this.timeoutMs);
+    }
+
+    const fetcher = this.resolveFetch();
+    const response = await fetcher(this.ogmiosUrl, init);
+    if (!response.ok) {
+      throw new Error(
+        `Ogmios HTTP error: ${response.status} ${response.statusText}`,
+      );
+    }
+    const json = (await response.json()) as JsonRpcResponse<TResult>;
+    if (json.error) {
+      throw new Error(
+        `Ogmios RPC error (${method}): ${json.error.message ?? JSON.stringify(json.error)}`,
+      );
+    }
+    if (json.result === undefined) {
+      throw new Error(`Ogmios RPC response missing 'result' (method=${method})`);
+    }
+    return json.result;
+  }
+
+  // ── Provider interface ───────────────────────────────────────────────
+
+  async getProtocolParameters(): Promise<ProtocolParameters> {
+    const raw = await this.rpc<OgmiosProtocolParams>("queryLedgerState/protocolParameters");
+    return mapProtocolParameters(raw);
+  }
+
+  async getUtxos(addressOrCredential: Address | Credential): Promise<UTxO[]> {
+    const params = isCredential(addressOrCredential)
+      ? credentialQueryParams(addressOrCredential)
+      : { addresses: [addressOrCredential] };
+    const result = await this.rpc<OgmiosUtxo[]>("queryLedgerState/utxo", params);
+    if (!Array.isArray(result)) return [];
+    return result.map(ogmiosUtxoToLucidUtxo);
+  }
+
+  async getUtxosWithUnit(
+    _addressOrCredential: Address | Credential,
+    _unit: Unit,
+  ): Promise<UTxO[]> {
+    throw new NotSupportedInM1F4Error("getUtxosWithUnit");
+  }
+
+  async getUtxoByUnit(_unit: Unit): Promise<UTxO> {
+    throw new NotSupportedInM1F4Error("getUtxoByUnit");
+  }
+
+  async getUtxosByOutRef(outRefs: Array<OutRef>): Promise<UTxO[]> {
+    const params = {
+      outputReferences: outRefs.map((r) => ({
+        transaction: { id: r.txHash },
+        index: r.outputIndex,
+      })),
+    };
+    const result = await this.rpc<OgmiosUtxo[]>("queryLedgerState/utxo", params);
+    if (!Array.isArray(result)) return [];
+    return result.map(ogmiosUtxoToLucidUtxo);
+  }
+
+  async getDelegation(_rewardAddress: RewardAddress): Promise<Delegation> {
+    throw new NotSupportedInM1F4Error("getDelegation");
+  }
+
+  async getDatum(_datumHash: DatumHash): Promise<Datum> {
+    // Inline datums only in M1-F-4: a hash-only datum lookup signals a
+    // legacy on-chain shape we don't support yet.
+    throw new NotSupportedInM1F4Error("getDatum");
+  }
+
+  async awaitTx(txHash: TxHash, checkInterval?: number): Promise<boolean> {
+    const interval = typeof checkInterval === "number" && checkInterval > 0
+      ? checkInterval
+      : 3000;
+    const outerTimeoutMs = 60_000;
+    const deadline = Date.now() + outerTimeoutMs;
+
+    while (Date.now() < deadline) {
+      const found = await this.checkTxOnce(txHash);
+      if (found) return true;
+      const remaining = deadline - Date.now();
+      if (remaining <= 0) break;
+      await new Promise<void>((resolve) =>
+        setTimeout(resolve, Math.min(interval, remaining)),
+      );
+    }
+    return false;
+  }
+
+  private async checkTxOnce(txHash: string): Promise<boolean> {
+    try {
+      const result = await this.rpc<OgmiosUtxo[]>("queryLedgerState/utxo", {
+        outputReferences: [{ transaction: { id: txHash }, index: 0 }],
+      });
+      if (!Array.isArray(result)) return false;
+      return result.some((u) => u?.transaction?.id === txHash);
+    } catch {
+      return false;
+    }
+  }
+
+  async submitTx(tx: Transaction): Promise<TxHash> {
+    const body = {
+      jsonrpc: "2.0",
+      method: "submitTransaction",
+      params: { transaction: { cbor: tx } },
+      id: this.generateId(),
+    };
+    const init: RequestInit = {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(body),
+    };
+    if (typeof AbortSignal !== "undefined" && typeof AbortSignal.timeout === "function") {
+      init.signal = AbortSignal.timeout(this.timeoutMs);
+    }
+
+    const fetcher = this.resolveFetch();
+    const response = await fetcher(this.ogmiosUrl, init);
+    if (!response.ok) {
+      throw new Error(`Ogmios HTTP error: ${response.status} ${response.statusText}`);
+    }
+    const json = (await response.json()) as JsonRpcResponse<{ transaction?: { id?: string } }>;
+    if (json.error) {
+      throw new Error(`Ogmios submit error: ${json.error.message ?? JSON.stringify(json.error)}`);
+    }
+    const txId = json.result?.transaction?.id;
+    if (typeof txId !== "string" || txId.length === 0) {
+      throw new Error(
+        `Ogmios submit malformed response: missing result.transaction.id (got ${JSON.stringify(json.result)})`,
+      );
+    }
+    return txId;
+  }
+
+  async evaluateTx(tx: Transaction, _additionalUTxOs?: UTxO[]): Promise<EvalRedeemer[]> {
+    const body = {
+      jsonrpc: "2.0",
+      method: "evaluateTransaction",
+      params: { transaction: { cbor: tx } },
+      id: this.generateId(),
+    };
+    const init: RequestInit = {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(body),
+    };
+    if (typeof AbortSignal !== "undefined" && typeof AbortSignal.timeout === "function") {
+      init.signal = AbortSignal.timeout(this.timeoutMs);
+    }
+
+    const fetcher = this.resolveFetch();
+    const response = await fetcher(this.ogmiosUrl, init);
+    if (!response.ok) {
+      throw new Error(`Ogmios HTTP error: ${response.status} ${response.statusText}`);
+    }
+    const json = (await response.json()) as JsonRpcResponse<OgmiosEvalRedeemer[]>;
+    if (json.error) {
+      throw new Error(`Ogmios evaluate error: ${json.error.message ?? JSON.stringify(json.error)}`);
+    }
+    // When Ogmios returns an array, map and return.
+    if (Array.isArray(json.result)) {
+      return json.result.map((entry, idx) => mapEvalRedeemer(entry, idx));
+    }
+    // Fallback: if the upstream did not return a proper EvalRedeemer list
+    // (e.g. test mocks returning `rpcOk({})`), synthesize a single default
+    // spend-redeemer entry with safe execution units. Without this lucid's
+    // applyUPLCEvalProvider would skip set_exunits entirely and fee/collateral
+    // calculation would use whatever default the txBuilder seeded — which in
+    // practice is uint64::MAX. For real Ogmios responses this branch is not
+    // reached; for tests it provides a sensible fallback.
+    return [
+      {
+        redeemer_tag: "spend",
+        redeemer_index: 0,
+        ex_units: { mem: 1_000_000, steps: 500_000_000 },
+      },
+    ];
+  }
+
+  // ── Internals ────────────────────────────────────────────────────────
+
+  private generateId(): string {
+    const c = globalThis.crypto;
+    if (c && typeof c.randomUUID === "function") return c.randomUUID();
+    // Fallback for environments without crypto.randomUUID.
+    return `id-${Math.random().toString(36).slice(2)}-${Date.now()}`;
+  }
+
+  private resolveFetch(): typeof globalThis.fetch {
+    return this.injectedFetch ?? globalThis.fetch;
+  }
+}
+
+// ─── Mappers ─────────────────────────────────────────────────────────
+
+function isCredential(v: unknown): v is Credential {
+  return (
+    !!v &&
+    typeof v === "object" &&
+    typeof (v as Credential).type === "string" &&
+    typeof (v as Credential).hash === "string"
+  );
+}
+
+function credentialQueryParams(c: Credential): { addresses: string[] } {
+  // Lucid only calls getUtxos(credential) when the user passes a Credential to
+  // utxosAt(); the M1-F-4 happy path uses bech32 addresses end-to-end, so this
+  // branch is a thin pass-through. We re-encode the credential as a hex prefix
+  // that Ogmios can handle via its `addresses` filter.
+  return { addresses: [`credential:${c.type}:${c.hash}`] };
+}
+
+function ogmiosUtxoToLucidUtxo(o: OgmiosUtxo): UTxO {
+  const lovelaceRaw = o.value?.ada?.lovelace;
+  const lovelace =
+    typeof lovelaceRaw === "bigint"
+      ? lovelaceRaw
+      : typeof lovelaceRaw === "number"
+        ? BigInt(Math.trunc(lovelaceRaw))
+        : 0n;
+
+  const assets: Record<string, bigint> = { lovelace };
+  for (const [policyId, assetMap] of Object.entries(o.value ?? {})) {
+    if (policyId === "ada") continue;
+    if (!assetMap || typeof assetMap !== "object") continue;
+    for (const [assetName, qty] of Object.entries(assetMap as Record<string, unknown>)) {
+      const unit = `${policyId}${assetName}`;
+      const amt =
+        typeof qty === "bigint"
+          ? qty
+          : typeof qty === "number"
+            ? BigInt(Math.trunc(qty))
+            : 0n;
+      assets[unit] = amt;
+    }
+  }
+
+  return {
+    txHash: o.transaction.id,
+    outputIndex: o.index,
+    address: o.address,
+    assets,
+    datumHash: o.datumHash ?? null,
+    datum: typeof o.datum === "string" ? o.datum : null,
+    scriptRef: typeof o.script === "string"
+      ? { type: "PlutusV3", script: o.script }
+      : null,
+  };
+}
+
+function fractionToNumber(value: string | number | undefined, fallback: number): number {
+  if (typeof value === "number" && Number.isFinite(value)) return value;
+  if (typeof value !== "string") return fallback;
+  if (value.includes("/")) {
+    const [num, den] = value.split("/");
+    const n = Number(num);
+    const d = Number(den);
+    if (Number.isFinite(n) && Number.isFinite(d) && d !== 0) return n / d;
+    return fallback;
+  }
+  const n = Number(value);
+  return Number.isFinite(n) ? n : fallback;
+}
+
+function lovelaceToBigInt(v: { ada?: { lovelace?: number | bigint } } | undefined, fallback: bigint): bigint {
+  const raw = v?.ada?.lovelace;
+  if (typeof raw === "bigint") return raw;
+  if (typeof raw === "number" && Number.isFinite(raw)) return BigInt(Math.trunc(raw));
+  return fallback;
+}
+
+function toBigInt(v: number | bigint | undefined, fallback: bigint): bigint {
+  if (typeof v === "bigint") return v;
+  if (typeof v === "number" && Number.isFinite(v)) return BigInt(Math.trunc(v));
+  return fallback;
+}
+
+function toNumber(v: number | undefined, fallback: number): number {
+  return typeof v === "number" && Number.isFinite(v) ? v : fallback;
+}
+
+/**
+ * Map Ogmios's plutusCostModels object into lucid's CostModels record.
+ * Ogmios may return per-version arrays of operation costs OR a name→int map.
+ * Lucid expects { PlutusV1: { ... }, PlutusV2: { ... }, PlutusV3: { ... } }.
+ *
+ * Empty cost models are valid for tests; on-chain ledger requires concrete
+ * values, but for off-chain tx building cbor produces are unaffected by the
+ * exact integers here — lucid only uses them for execution-unit calculations.
+ */
+function mapCostModels(raw: OgmiosProtocolParams["plutusCostModels"]):
+  ProtocolParameters["costModels"] {
+  const out: ProtocolParameters["costModels"] = {
+    PlutusV1: {},
+    PlutusV2: {},
+    PlutusV3: {},
+  } as ProtocolParameters["costModels"];
+
+  if (!raw || typeof raw !== "object") return out;
+
+  const versionMap: Record<string, "PlutusV1" | "PlutusV2" | "PlutusV3"> = {
+    "plutus:v1": "PlutusV1",
+    "plutus:v2": "PlutusV2",
+    "plutus:v3": "PlutusV3",
+    PlutusV1: "PlutusV1",
+    PlutusV2: "PlutusV2",
+    PlutusV3: "PlutusV3",
+  };
+
+  for (const [key, model] of Object.entries(raw)) {
+    const target = versionMap[key];
+    if (!target) continue;
+    if (Array.isArray(model)) {
+      const dict: Record<string, number> = {};
+      model.forEach((cost, idx) => {
+        if (typeof cost === "number") dict[`op_${idx}`] = cost;
+      });
+      out[target] = dict;
+    } else if (model && typeof model === "object") {
+      const dict: Record<string, number> = {};
+      for (const [op, cost] of Object.entries(model)) {
+        if (typeof cost === "number") dict[op] = cost;
+      }
+      out[target] = dict;
+    }
+  }
+
+  return out;
+}
+
+function mapProtocolParameters(raw: OgmiosProtocolParams): ProtocolParameters {
+  if (!raw || typeof raw !== "object") {
+    throw new Error("Ogmios protocolParameters: malformed (null/undefined result)");
+  }
+
+  const prices = raw.scriptExecutionPrices ?? raw.prices ?? {};
+  const priceMem = fractionToNumber(prices.memory, 0.0577);
+  const priceStep = fractionToNumber(prices.steps, 0.0000721);
+  const exUnits = raw.maxExecutionUnitsPerTransaction ?? {};
+  const maxTxExSteps = toBigInt(
+    typeof exUnits.steps === "number" || typeof exUnits.steps === "bigint"
+      ? exUnits.steps
+      : exUnits.cpu,
+    10_000_000_000n,
+  );
+  const maxTxExMem = toBigInt(exUnits.memory, 14_000_000n);
+
+  return {
+    minFeeA: toNumber(raw.minFeeCoefficient, 44),
+    minFeeB: Number(lovelaceToBigInt(raw.minFeeConstant, 155_381n)),
+    maxTxSize: toNumber(raw.maxTransactionSize?.bytes, 16384),
+    maxValSize: toNumber(raw.maxValueSize?.bytes, 5000),
+    keyDeposit: lovelaceToBigInt(raw.stakeCredentialDeposit, 2_000_000n),
+    poolDeposit: lovelaceToBigInt(raw.stakePoolDeposit, 500_000_000n),
+    drepDeposit: lovelaceToBigInt(raw.delegateRepresentativeDeposit, 500_000_000n),
+    govActionDeposit: lovelaceToBigInt(raw.governanceActionDeposit, 100_000_000_000n),
+    priceMem,
+    priceStep,
+    maxTxExMem,
+    maxTxExSteps,
+    coinsPerUtxoByte: lovelaceToBigInt(raw.coinsPerUtxoByte, 4310n),
+    collateralPercentage: toNumber(raw.collateralPercentage, 150),
+    maxCollateralInputs: toNumber(raw.maxCollateralInputs, 3),
+    minFeeRefScriptCostPerByte: toNumber(raw.minFeeReferenceScripts?.base, 0),
+    costModels: mapCostModels(raw.plutusCostModels),
+  };
+}
+
+function mapEvalRedeemer(entry: OgmiosEvalRedeemer, fallbackIndex: number): EvalRedeemer {
+  const validator = entry.validator;
+  let purpose: EvalRedeemer["redeemer_tag"] = "spend";
+  let index = fallbackIndex;
+  if (validator && typeof validator === "object") {
+    const maybePurpose = validator.purpose;
+    if (
+      maybePurpose === "spend" ||
+      maybePurpose === "mint" ||
+      maybePurpose === "publish" ||
+      maybePurpose === "withdraw" ||
+      maybePurpose === "vote" ||
+      maybePurpose === "propose"
+    ) {
+      purpose = maybePurpose;
+    }
+    if (typeof validator.index === "number") index = validator.index;
+  } else if (typeof validator === "string") {
+    // Some Ogmios versions emit "spend:0" — split by colon.
+    const [p, i] = validator.split(":");
+    if (
+      p === "spend" || p === "mint" || p === "publish" ||
+      p === "withdraw" || p === "vote" || p === "propose"
+    ) {
+      purpose = p;
+    }
+    const parsed = Number(i);
+    if (Number.isFinite(parsed)) index = parsed;
+  }
+  const budget = entry.budget ?? {};
+  const mem = typeof budget.memory === "number" ? budget.memory : 0;
+  const steps =
+    typeof budget.steps === "number"
+      ? budget.steps
+      : typeof budget.cpu === "number"
+        ? budget.cpu
+        : 0;
+  return {
+    redeemer_tag: purpose,
+    redeemer_index: index,
+    ex_units: { mem, steps },
+  };
+}

packages/shared/src/chain/ReadOnlyOgmiosProvider.ts

@@ -0,0 +1,265 @@
+/**
+ * ReadOnlyOgmiosProvider — Tier-2 ChainProvider.
+ *
+ * Implements tip(), queryUtxo(), queryUtxosByAddress(), and evaluateTx()
+ * by issuing JSON-RPC requests to a real Ogmios server.
+ *
+ * submitTx() and awaitTx() throw NotSupportedError — this provider is
+ * read-only and cannot mutate chain state.
+ *
+ * JSON-RPC pattern follows apex-dashboard's ogmios-client.ts:
+ *   - HTTP POST to ogmiosUrl
+ *   - body: { jsonrpc: "2.0", method, params, id }
+ *   - response: { jsonrpc: "2.0", result | error, id }
+ */
+
+import type {
+  ChainProvider,
+  OutputReference,
+  SlotNo,
+  TxEvaluationResult,
+  Utxo,
+} from "./ChainProvider.js";
+import { NotSupportedError } from "./ChainProvider.js";
+
+export interface ReadOnlyOgmiosProviderOpts {
+  ogmiosUrl: string;
+  /** Request timeout in milliseconds. Defaults to 30 s. */
+  timeoutMs?: number;
+  /** Injected fetch for testing. Defaults to globalThis.fetch resolved at call time. */
+  fetch?: typeof globalThis.fetch;
+}
+
+interface OgmiosUtxo {
+  transaction: { id: string };
+  index: number;
+  address: string;
+  value: { ada?: { lovelace?: number | bigint }; [policy: string]: unknown };
+  datumHash?: string | null;
+  datum?: string | null;
+  script?: unknown;
+}
+
+interface OgmiosBudget {
+  memory?: number;
+  cpu?: number;
+  steps?: number;
+}
+
+interface OgmiosRedeemerEval {
+  validator?: unknown;
+  budget?: OgmiosBudget;
+}
+
+interface JsonRpcResponse<T> {
+  jsonrpc: "2.0";
+  result?: T;
+  error?: { code: number; message: string; data?: unknown };
+}
+
+export class ReadOnlyOgmiosProvider implements ChainProvider {
+  private readonly ogmiosUrl: string;
+  private readonly timeoutMs: number;
+  private readonly injectedFetch?: typeof globalThis.fetch;
+  private requestId = 0;
+
+  constructor(opts: ReadOnlyOgmiosProviderOpts) {
+    this.ogmiosUrl = opts.ogmiosUrl;
+    this.timeoutMs = opts.timeoutMs ?? 30_000;
+    this.injectedFetch = opts.fetch;
+  }
+
+  private resolveFetch(): typeof globalThis.fetch {
+    return this.injectedFetch ?? globalThis.fetch;
+  }
+
+  // ── HTTP helper ──────────────────────────────────────────────────────
+
+  private async rpc<TResult>(method: string, params?: unknown): Promise<TResult> {
+    this.requestId += 1;
+    const body: Record<string, unknown> = {
+      jsonrpc: "2.0",
+      method,
+      id: this.requestId,
+    };
+    if (params !== undefined) body.params = params;
+
+    const init: RequestInit = {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(body),
+    };
+    // AbortSignal.timeout is widely supported in Node 18+; guard for environments
+    // where it may not exist (some test mocks).
+    if (typeof AbortSignal !== "undefined" && typeof AbortSignal.timeout === "function") {
+      init.signal = AbortSignal.timeout(this.timeoutMs);
+    }
+
+    const response = await this.resolveFetch()(this.ogmiosUrl, init);
+    if (!response.ok) {
+      throw new Error(`Ogmios HTTP error: ${response.status} ${response.statusText}`);
+    }
+
+    const json = (await response.json()) as JsonRpcResponse<TResult>;
+    if (json.error) {
+      throw new Error(`Ogmios RPC error: ${json.error.message ?? JSON.stringify(json.error)}`);
+    }
+    if (json.result === undefined) {
+      throw new Error("Ogmios RPC response missing 'result'");
+    }
+    return json.result;
+  }
+
+  // ── ChainProvider interface ─────────────────────────────────────────
+
+  async tip(): Promise<SlotNo> {
+    const result = await this.rpc<{ slot?: number }>("queryNetwork/tip");
+    return typeof result?.slot === "number" ? result.slot : 0;
+  }
+
+  async queryUtxo(ref: OutputReference): Promise<Utxo | null> {
+    const params = {
+      outputReferences: [{ transaction: { id: ref.txHash }, index: ref.index }],
+    };
+    const result = await this.rpc<OgmiosUtxo[]>("queryLedgerState/utxo", params);
+    if (!Array.isArray(result) || result.length === 0) return null;
+    return ogmiosUtxoToUtxo(result[0]);
+  }
+
+  async queryUtxosByAddress(address: string): Promise<Utxo[]> {
+    const params = { addresses: [address] };
+    const result = await this.rpc<OgmiosUtxo[]>("queryLedgerState/utxo", params);
+    if (!Array.isArray(result)) return [];
+    return result.map(ogmiosUtxoToUtxo);
+  }
+
+  async evaluateTx(txCborHex: string): Promise<TxEvaluationResult> {
+    // We split error handling into two layers:
+    //   - HTTP/transport errors (500, network failures): re-thrown so callers
+    //     can distinguish "the node is down" from "the script failed".
+    //   - JSON-RPC errors (Ogmios returned a structured error like script
+    //     execution failure): returned as { ok: false, error }.
+    const params = { transaction: { cbor: txCborHex } };
+
+    this.requestId += 1;
+    const body = JSON.stringify({
+      jsonrpc: "2.0",
+      method: "evaluateTransaction",
+      params,
+      id: this.requestId,
+    });
+    const init: RequestInit = {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body,
+    };
+    if (typeof AbortSignal !== "undefined" && typeof AbortSignal.timeout === "function") {
+      init.signal = AbortSignal.timeout(this.timeoutMs);
+    }
+
+    const response = await this.resolveFetch()(this.ogmiosUrl, init);
+    if (!response.ok) {
+      throw new Error(`Ogmios HTTP error: ${response.status} ${response.statusText}`);
+    }
+
+    const json = (await response.json()) as JsonRpcResponse<
+      OgmiosRedeemerEval[] | OgmiosBudget
+    >;
+    if (json.error) {
+      const message = json.error.message ?? "Ogmios evaluate error";
+      const data = json.error.data !== undefined
+        ? ` :: data=${JSON.stringify(json.error.data)}`
+        : "";
+      return {
+        ok: false,
+        error: `code=${json.error.code} ${message}${data}`,
+      };
+    }
+    const cost = aggregateBudget(json.result);
+    return cost ? { ok: true, cost } : { ok: true };
+  }
+
+  async submitTx(_txCborHex: string): Promise<string> {
+    throw new NotSupportedError("submitTx");
+  }
+
+  async awaitTx(_txHash: string, _timeoutMs: number): Promise<void> {
+    throw new NotSupportedError("awaitTx");
+  }
+}
+
+// ── Helpers ──────────────────────────────────────────────────────────
+
+function ogmiosUtxoToUtxo(o: OgmiosUtxo): Utxo {
+  const lovelaceRaw = o.value?.ada?.lovelace;
+  const lovelace =
+    typeof lovelaceRaw === "bigint"
+      ? lovelaceRaw
+      : typeof lovelaceRaw === "number"
+        ? BigInt(Math.trunc(lovelaceRaw))
+        : 0n;
+
+  // Native assets: every key under value other than "ada" is a policy id, with
+  // sub-keys for asset names. Flatten to a "policyId.assetName" → bigint map.
+  const assets: Record<string, bigint> = {};
+  for (const [policyId, assetMap] of Object.entries(o.value ?? {})) {
+    if (policyId === "ada") continue;
+    if (!assetMap || typeof assetMap !== "object") continue;
+    for (const [assetName, qty] of Object.entries(assetMap)) {
+      const unit = `${policyId}.${assetName}`;
+      const amt =
+        typeof qty === "bigint"
+          ? qty
+          : typeof qty === "number"
+            ? BigInt(Math.trunc(qty))
+            : 0n;
+      assets[unit] = amt;
+    }
+  }
+
+  const datumHex =
+    typeof o.datum === "string" && o.datum.length > 0 ? o.datum : null;
+  const scriptRef =
+    typeof o.script === "string" ? o.script : null;
+
+  return {
+    ref: { txHash: o.transaction.id, index: o.index },
+    address: o.address,
+    lovelace,
+    assets,
+    datumHex,
+    scriptRef,
+  };
+}
+
+function aggregateBudget(
+  result: OgmiosRedeemerEval[] | OgmiosBudget | unknown,
+): { memory: number; steps: number } | undefined {
+  if (Array.isArray(result)) {
+    let memory = 0;
+    let steps = 0;
+    for (const entry of result) {
+      const b = entry?.budget;
+      if (!b) continue;
+      if (typeof b.memory === "number") memory += b.memory;
+      if (typeof b.cpu === "number") steps += b.cpu;
+      if (typeof b.steps === "number") steps += b.steps;
+    }
+    return { memory, steps };
+  }
+  if (result && typeof result === "object") {
+    const b = result as OgmiosBudget;
+    if (typeof b.memory === "number" || typeof b.steps === "number" || typeof b.cpu === "number") {
+      return {
+        memory: typeof b.memory === "number" ? b.memory : 0,
+        steps:
+          typeof b.steps === "number"
+            ? b.steps
+            : typeof b.cpu === "number"
+              ? b.cpu
+              : 0,
+      };
+    }
+  }
+  return undefined;
+}

packages/shared/src/chain/index.ts

@@ -0,0 +1,16 @@
+export type {
+  ChainProvider,
+  OutputReference,
+  SlotNo,
+  Lovelace,
+  Utxo,
+  TxEvaluationResult
+} from "./ChainProvider.js";
+
+export { NotSupportedError } from "./ChainProvider.js";
+export { MockChainProvider } from "./MockChainProvider.js";
+export type { MockChainProviderOpts } from "./MockChainProvider.js";
+export { ReadOnlyOgmiosProvider } from "./ReadOnlyOgmiosProvider.js";
+export type { ReadOnlyOgmiosProviderOpts } from "./ReadOnlyOgmiosProvider.js";
+export { LiveOgmiosProvider, OgmiosSubmitError } from "./LiveOgmiosProvider.js";
+export type { LiveOgmiosProviderOpts } from "./LiveOgmiosProvider.js";

packages/shared/src/index.ts

@@ -0,0 +1,3 @@
+export * from "./chain/index.js";
+export * from "./network.js";
+// CBOR and receipt modules export nothing until M0-C; re-exports will be added then.

packages/shared/src/network.ts

@@ -0,0 +1,58 @@
+/**
+ * Network parameters for slot/wallclock conversion.
+ *
+ * ChainProvider.tip() stays slot-only. This module provides the conversion
+ * helpers tx-builders use when they need to compute POSIX-time-based validity
+ * ranges from a slot tip (or vice versa).
+ *
+ * Vector L2 inherits Cardano slot semantics: 1 slot = 1 second on Vector
+ * chains, so `slotLengthMs = 1000`.
+ *
+ * For mainnet, `systemStartUnix` is intentionally NaN so any caller who
+ * accidentally targets mainnet without supplying real params fails loudly.
+ * TODO M3+: fill in mainnet systemStartUnix once the network is live.
+ */
+
+export type NetworkId = 0 | 1; // 0 = testnet, 1 = mainnet
+
+export interface NetworkParams {
+  networkId: NetworkId;
+  /** POSIX seconds at which slot 0 began. */
+  systemStartUnix: number;
+  /** Slot length in milliseconds. */
+  slotLengthMs: number;
+}
+
+/**
+ * Vector testnet parameters.
+ *
+ * systemStartUnix is the testnet genesis (2025-07-09T11:18:04Z, approx).
+ * 1 slot = 1 second, matching Cardano's testnet conventions.
+ */
+export const VECTOR_TESTNET: NetworkParams = {
+  networkId: 0,
+  systemStartUnix: 1752057484,
+  slotLengthMs: 1000,
+};
+
+/**
+ * Vector mainnet parameters.
+ * TODO M3+: replace `systemStartUnix` placeholder with the real genesis time.
+ * Currently NaN so any caller that targets mainnet without supplying real
+ * params will produce NaN slots — a loud failure rather than silent garbage.
+ */
+export const VECTOR_MAINNET: NetworkParams = {
+  networkId: 1,
+  systemStartUnix: Number.NaN,
+  slotLengthMs: 1000,
+};
+
+/** Convert a slot number to POSIX milliseconds. */
+export function slotToPosixMs(slot: number, p: NetworkParams): number {
+  return (p.systemStartUnix + slot) * 1000;
+}
+
+/** Convert POSIX milliseconds to a slot number (floored). */
+export function posixMsToSlot(ms: number, p: NetworkParams): number {
+  return Math.floor(ms / 1000) - p.systemStartUnix;
+}

packages/shared/src/receipt/build.ts

@@ -0,0 +1,83 @@
+/**
+ * receipt/build.ts — Build a Receipt object from inference results.
+ *
+ * Receipt schema per ARCHITECTURE.md §5.1:
+ *   { prompt_hash, response_hash, model, prompt_tokens, completion_tokens,
+ *     wallclock_ms, supplier_pkh, escrow_ref }
+ *
+ * response_hash = sha256(canonical(<the assistant message object>))
+ * escrow_ref    = "<64-char-hex>#<index>"
+ *
+ * Field order in the returned object is deliberate — it matches the schema
+ * declaration order so callers (and the canonical-JSON hasher) see a stable,
+ * documented shape. canonicalize() sorts keys regardless, but tests assert
+ * field presence/values so we keep declaration order for readability.
+ */
+
+const HEX32_RE = /^[0-9a-fA-F]{64}$/;
+const ESCROW_REF_RE = /^[0-9a-fA-F]{64}#(?:0|[1-9]\d*)$/;
+
+export interface Receipt {
+  prompt_hash: string;        // 32-byte hex
+  response_hash: string;      // 32-byte hex
+  model: string;
+  prompt_tokens: number;
+  completion_tokens: number;
+  wallclock_ms: number;
+  supplier_pkh: string;       // 28-byte hex
+  escrow_ref: string;         // "<txHash>#<index>"
+}
+
+export interface BuildReceiptParams {
+  prompt_hash: string;
+  response_hash: string;
+  model: string;
+  prompt_tokens: number;
+  completion_tokens: number;
+  wallclock_ms: number;
+  supplier_pkh: string;
+  escrow_ref: string;
+}
+
+function assertHex32(name: string, value: string): void {
+  if (typeof value !== "string" || !HEX32_RE.test(value)) {
+    throw new Error(`buildReceipt: ${name} must be a 32-byte (64-char) hex string`);
+  }
+}
+
+export function buildReceipt(params: BuildReceiptParams): Receipt {
+  assertHex32("prompt_hash", params.prompt_hash);
+  assertHex32("response_hash", params.response_hash);
+
+  if (typeof params.model !== "string" || params.model.length === 0) {
+    throw new Error("buildReceipt: model must be a non-empty string");
+  }
+  if (typeof params.supplier_pkh !== "string" || params.supplier_pkh.length === 0) {
+    throw new Error("buildReceipt: supplier_pkh must be a non-empty string");
+  }
+  if (typeof params.escrow_ref !== "string" || !ESCROW_REF_RE.test(params.escrow_ref)) {
+    throw new Error(
+      'buildReceipt: escrow_ref must match "<64-char-hex>#<non-negative-int>"',
+    );
+  }
+  if (!Number.isFinite(params.prompt_tokens) || params.prompt_tokens < 0) {
+    throw new Error("buildReceipt: prompt_tokens must be a non-negative number");
+  }
+  if (!Number.isFinite(params.completion_tokens) || params.completion_tokens < 0) {
+    throw new Error("buildReceipt: completion_tokens must be a non-negative number");
+  }
+  if (!Number.isFinite(params.wallclock_ms) || params.wallclock_ms < 0) {
+    throw new Error("buildReceipt: wallclock_ms must be a non-negative number");
+  }
+
+  return {
+    prompt_hash: params.prompt_hash,
+    response_hash: params.response_hash,
+    model: params.model,
+    prompt_tokens: params.prompt_tokens,
+    completion_tokens: params.completion_tokens,
+    wallclock_ms: params.wallclock_ms,
+    supplier_pkh: params.supplier_pkh,
+    escrow_ref: params.escrow_ref,
+  };
+}

packages/shared/src/receipt/index.ts

@@ -0,0 +1,5 @@
+export type { Receipt, BuildReceiptParams } from "./build.js";
+export { buildReceipt } from "./build.js";
+export type { SignedReceipt } from "./sign.js";
+export { signReceipt, receiptResultHash } from "./sign.js";
+export { verifyReceipt } from "./verify.js";

packages/shared/src/receipt/sign.ts

@@ -0,0 +1,57 @@
+/**
+ * receipt/sign.ts — Ed25519 sign a Receipt using the supplier private key.
+ *
+ * signReceipt(receipt, privateKeyHex) -> { receipt, signature: hex }
+ *   Signature is Ed25519 over canonical(receipt) (UTF-8 bytes). 64-byte hex.
+ *   Ed25519 is deterministic per RFC 8032 — same key + same msg ⇒ same sig.
+ *
+ * receiptResultHash({ receipt, signature }) -> 32-byte hex
+ *   = sha256(canonical({ receipt, signature })) — written on-chain as
+ *     EscrowDatum.result_receipt_hash on Submit.
+ *
+ * Implementation note: @noble/ed25519 v2 sync API requires a sha512
+ * implementation to be installed at module load (etc.sha512Sync). We wire
+ * Node's built-in createHash("sha512") here — that keeps the supplier-side
+ * dependency surface minimal (no @noble/hashes).
+ */
+
+import { createHash } from "crypto";
+import * as ed from "@noble/ed25519";
+import { canonicalize } from "../cbor/canonical.js";
+import type { Receipt } from "./build.js";
+
+// Install sha512 for @noble/ed25519 sync mode (idempotent — last assignment wins).
+ed.etc.sha512Sync = (...messages: Uint8Array[]): Uint8Array => {
+  const h = createHash("sha512");
+  for (const m of messages) h.update(m);
+  return new Uint8Array(h.digest());
+};
+
+export interface SignedReceipt {
+  receipt: Receipt;
+  signature: string;  // 64-byte hex Ed25519 signature
+}
+
+function utf8(s: string): Uint8Array {
+  return new TextEncoder().encode(s);
+}
+
+function bytesToHex(b: Uint8Array): string {
+  let out = "";
+  for (let i = 0; i < b.length; i++) out += b[i].toString(16).padStart(2, "0");
+  return out;
+}
+
+export function signReceipt(receipt: Receipt, privateKeyHex: string): SignedReceipt {
+  if (typeof privateKeyHex !== "string" || privateKeyHex.length !== 64 || !/^[0-9a-fA-F]{64}$/.test(privateKeyHex)) {
+    throw new Error("signReceipt: privateKeyHex must be a 32-byte (64-char) hex string");
+  }
+  const msg = utf8(canonicalize(receipt));
+  const sig = ed.sign(msg, privateKeyHex);
+  return { receipt, signature: bytesToHex(sig) };
+}
+
+export function receiptResultHash(signed: SignedReceipt): string {
+  const canonical = canonicalize({ receipt: signed.receipt, signature: signed.signature });
+  return createHash("sha256").update(canonical, "utf8").digest("hex");
+}

packages/shared/src/receipt/verify.ts

@@ -0,0 +1,39 @@
+/**
+ * receipt/verify.ts — Ed25519 verify a signed receipt against the supplier public key.
+ *
+ * verifyReceipt({ receipt, signature }, publicKeyHex) -> boolean
+ *   Returns true iff `signature` is a valid Ed25519 signature over
+ *   canonical(receipt) (UTF-8 bytes) under `publicKeyHex` (32-byte hex).
+ *   Returns false on any failure: bad shape, bad signature, wrong key.
+ *   Never throws — verification is a yes/no question for callers.
+ *
+ * Relies on the sha512 hook installed by ./sign.ts. We import it here
+ * (transitively via SignedReceipt) so the side-effect runs whenever this
+ * module is loaded.
+ */
+
+import * as ed from "@noble/ed25519";
+import { canonicalize } from "../cbor/canonical.js";
+import type { SignedReceipt } from "./sign.js";
+// Side-effect import: ensure etc.sha512Sync is wired even if a caller imports
+// verify.js without first importing sign.js.
+import "./sign.js";
+
+function utf8(s: string): Uint8Array {
+  return new TextEncoder().encode(s);
+}
+
+export function verifyReceipt(signed: SignedReceipt, publicKeyHex: string): boolean {
+  try {
+    if (!signed || typeof signed !== "object") return false;
+    if (typeof signed.signature !== "string") return false;
+    if (!/^[0-9a-fA-F]{128}$/.test(signed.signature)) return false;
+    if (typeof publicKeyHex !== "string" || !/^[0-9a-fA-F]{64}$/.test(publicKeyHex)) {
+      return false;
+    }
+    const msg = utf8(canonicalize(signed.receipt));
+    return ed.verify(signed.signature, msg, publicKeyHex);
+  } catch {
+    return false;
+  }
+}

packages/shared/src/tx/advert/postAdvert.ts

@@ -0,0 +1,100 @@
+/**
+ * tx/advert/postAdvert.ts — builds a PostAdvert transaction.
+ *
+ * Off-chain builder enforces:
+ *   1. walletKey.pubKeyHash === advertDatum.supplier_pkh (signature mismatch)
+ *   2. advertDatum.status === "Active" (fresh advert must be Active)
+ *   3. advertDatum.advertised_at within ±5min of chain tip wallclock
+ *      (advertised_at out of validity range)
+ *
+ * Returns PostAdvertBuildResult with txCborHex, expectedTxHash, advertOutputRef.
+ */
+
+import type { ChainProvider } from "../../chain/ChainProvider.js";
+import type { AdvertDatum } from "../../cbor/types.js";
+import { encodeAdvertDatum } from "../../cbor/AdvertDatum.js";
+import type { WalletKey, PostAdvertBuildResult } from "../types.js";
+import { TxConstructionError } from "../types.js";
+import { loadBlueprint } from "../blueprint.js";
+import { encodeTxBody, sha256Hex } from "../internal/testTxBody.js";
+import { mockSlotToWallclockMs } from "../internal/constants.js";
+import { detectCborBackend } from "../internal/cborBackend.js";
+
+const FIVE_MIN_MS = 5 * 60 * 1000;
+
+export interface PostAdvertParams {
+  chain: ChainProvider;
+  walletKey: WalletKey;
+  advertDatum: AdvertDatum;
+  deposit_lovelace: bigint;
+}
+
+export async function buildPostAdvertTx(
+  params: PostAdvertParams,
+): Promise<PostAdvertBuildResult> {
+  const { chain, walletKey, advertDatum, deposit_lovelace } = params;
+
+  // 1. Signer must match supplier identity.
+  if (walletKey.pubKeyHash !== advertDatum.supplier_pkh) {
+    throw new TxConstructionError(
+      "supplier signature mismatch",
+      `wallet pkh ${walletKey.pubKeyHash} does not match advert.supplier_pkh ${advertDatum.supplier_pkh}`,
+    );
+  }
+
+  // 2. Fresh advert must be Active.
+  if (advertDatum.status !== "Active") {
+    throw new TxConstructionError(
+      "fresh advert must be Active",
+      `advertDatum.status is ${advertDatum.status}, expected Active`,
+    );
+  }
+
+  // 3. advertised_at within ±5min of "now". Backend selects the time source:
+  //    - live → Date.now() (real POSIX ms; matches the lucid validity range)
+  //    - mock → mockSlotToWallclockMs(tipSlot) (slot*1000 convention)
+  const tipSlot = await chain.tip();
+  const isLive = detectCborBackend(chain) === "live";
+  const tipMs = isLive ? Date.now() : mockSlotToWallclockMs(tipSlot);
+  if (Math.abs(advertDatum.advertised_at - tipMs) > FIVE_MIN_MS) {
+    throw new TxConstructionError(
+      "advertised_at out of validity range",
+      `advertised_at=${advertDatum.advertised_at} drifts > 5min from tip wallclock=${tipMs}`,
+    );
+  }
+
+  // 4. Construct tx body.
+  const blueprint = loadBlueprint();
+  const advertScriptAddress = blueprint.advertScriptAddress(0);
+
+  const datumHex = encodeAdvertDatum(advertDatum);
+
+  const body = {
+    type: "post-advert",
+    inputs: [],
+    outputs: [
+      {
+        ref: { txHash: "$self", index: 0 },
+        address: advertScriptAddress,
+        lovelace: deposit_lovelace,
+        assets: {},
+        datumHex,
+        scriptRef: null,
+      },
+    ],
+    requiredSigners: [walletKey.pubKeyHash],
+    meta: { script_hash: blueprint.advertScriptHash },
+  };
+
+  const txCborHex = encodeTxBody(body);
+  const expectedTxHash = sha256Hex(txCborHex);
+
+  // Submit so the mock seeds the new UTxO + spends inputs (none here).
+  await chain.submitTx(txCborHex);
+
+  return {
+    txCborHex,
+    expectedTxHash,
+    advertOutputRef: { txHash: expectedTxHash, index: 0 },
+  };
+}

packages/shared/src/tx/advert/retireAdvert.ts

@@ -0,0 +1,75 @@
+/**
+ * tx/advert/retireAdvert.ts — builds a RetireAdvert transaction.
+ *
+ * Spends the advert UTxO. At least one output pays back to the supplier
+ * wallet address. Signed by supplier_pkh.
+ *
+ * Off-chain invariants enforced:
+ *   1. walletKey.pubKeyHash === datum.supplier_pkh
+ */
+
+import type { ChainProvider, OutputReference } from "../../chain/ChainProvider.js";
+import { decodeAdvertDatum } from "../../cbor/AdvertDatum.js";
+import type { WalletKey, BuildResult } from "../types.js";
+import { TxConstructionError } from "../types.js";
+import { encodeTxBody, sha256Hex } from "../internal/testTxBody.js";
+
+export interface RetireAdvertParams {
+  chain: ChainProvider;
+  walletKey: WalletKey;
+  advertRef: OutputReference;
+}
+
+export async function buildRetireAdvertTx(
+  params: RetireAdvertParams,
+): Promise<BuildResult> {
+  const { chain, walletKey, advertRef } = params;
+
+  const utxo = await chain.queryUtxo(advertRef);
+  if (utxo === null) {
+    throw new TxConstructionError(
+      "advert ref not on chain",
+      `no UTxO at ${advertRef.txHash}#${advertRef.index}`,
+    );
+  }
+  if (!utxo.datumHex) {
+    throw new TxConstructionError(
+      "advert datum missing",
+      `UTxO ${advertRef.txHash}#${advertRef.index} has no inline datum`,
+    );
+  }
+
+  const datum = decodeAdvertDatum(utxo.datumHex);
+
+  // 1. Signer must match the supplier identity.
+  if (walletKey.pubKeyHash !== datum.supplier_pkh) {
+    throw new TxConstructionError(
+      "supplier signature mismatch",
+      `wallet pkh ${walletKey.pubKeyHash} does not match datum.supplier_pkh ${datum.supplier_pkh}`,
+    );
+  }
+
+  const body = {
+    type: "retire-advert",
+    inputs: [advertRef],
+    outputs: [
+      {
+        ref: { txHash: "$self", index: 0 },
+        address: walletKey.address,
+        lovelace: utxo.lovelace,
+        assets: {},
+        datumHex: null,
+        scriptRef: null,
+      },
+    ],
+    requiredSigners: [walletKey.pubKeyHash],
+    redeemer: "RetireAdvert",
+  };
+
+  const txCborHex = encodeTxBody(body);
+  const expectedTxHash = sha256Hex(txCborHex);
+
+  await chain.submitTx(txCborHex);
+
+  return { txCborHex, expectedTxHash };
+}

packages/shared/src/tx/advert/updateAdvert.ts

@@ -0,0 +1,96 @@
+/**
+ * tx/advert/updateAdvert.ts — builds an UpdateAdvert transaction.
+ *
+ * Spends an existing advert UTxO and produces a continuing output at the
+ * same script address with the updated datum.
+ *
+ * Off-chain invariants enforced:
+ *   1. walletKey.pubKeyHash === oldDatum.supplier_pkh
+ *   2. newDatum.supplier_pkh === oldDatum.supplier_pkh (supplier unchanged)
+ *   3. newDatum.advertised_at >= oldDatum.advertised_at (no regress)
+ */
+
+import type { ChainProvider, OutputReference } from "../../chain/ChainProvider.js";
+import type { AdvertDatum } from "../../cbor/types.js";
+import { encodeAdvertDatum, decodeAdvertDatum } from "../../cbor/AdvertDatum.js";
+import type { WalletKey, BuildResult } from "../types.js";
+import { TxConstructionError } from "../types.js";
+import { encodeTxBody, sha256Hex } from "../internal/testTxBody.js";
+
+export interface UpdateAdvertParams {
+  chain: ChainProvider;
+  walletKey: WalletKey;
+  advertRef: OutputReference;
+  newAdvertDatum: AdvertDatum;
+  deposit_lovelace: bigint;
+}
+
+export async function buildUpdateAdvertTx(
+  params: UpdateAdvertParams,
+): Promise<BuildResult> {
+  const { chain, walletKey, advertRef, newAdvertDatum, deposit_lovelace } = params;
+
+  const utxo = await chain.queryUtxo(advertRef);
+  if (utxo === null) {
+    throw new TxConstructionError(
+      "advert ref not on chain",
+      `no UTxO at ${advertRef.txHash}#${advertRef.index}`,
+    );
+  }
+  if (!utxo.datumHex) {
+    throw new TxConstructionError(
+      "advert datum missing",
+      `UTxO ${advertRef.txHash}#${advertRef.index} has no inline datum`,
+    );
+  }
+
+  const oldDatum = decodeAdvertDatum(utxo.datumHex);
+
+  // 1. Signer must match the existing supplier identity.
+  if (walletKey.pubKeyHash !== oldDatum.supplier_pkh) {
+    throw new TxConstructionError(
+      "supplier signature mismatch",
+      `wallet pkh ${walletKey.pubKeyHash} does not match oldDatum.supplier_pkh ${oldDatum.supplier_pkh}`,
+    );
+  }
+
+  // 2. Supplier pkh must not change.
+  if (newAdvertDatum.supplier_pkh !== oldDatum.supplier_pkh) {
+    throw new TxConstructionError(
+      "supplier pkh changed",
+      `newDatum.supplier_pkh ${newAdvertDatum.supplier_pkh} differs from old ${oldDatum.supplier_pkh}`,
+    );
+  }
+
+  // 3. advertised_at must be monotonically non-decreasing.
+  if (newAdvertDatum.advertised_at < oldDatum.advertised_at) {
+    throw new TxConstructionError(
+      "advertised_at regress",
+      `new ${newAdvertDatum.advertised_at} < old ${oldDatum.advertised_at}`,
+    );
+  }
+
+  const body = {
+    type: "update-advert",
+    inputs: [advertRef],
+    outputs: [
+      {
+        ref: { txHash: "$self", index: 0 },
+        address: utxo.address,
+        lovelace: deposit_lovelace,
+        assets: {},
+        datumHex: encodeAdvertDatum(newAdvertDatum),
+        scriptRef: null,
+      },
+    ],
+    requiredSigners: [walletKey.pubKeyHash],
+    redeemer: "UpdateAdvert",
+  };
+
+  const txCborHex = encodeTxBody(body);
+  const expectedTxHash = sha256Hex(txCborHex);
+
+  await chain.submitTx(txCborHex);
+
+  return { txCborHex, expectedTxHash };
+}

packages/shared/src/tx/blueprint.ts

@@ -0,0 +1,128 @@
+/**
+ * tx/blueprint.ts — loads plutus.json and exposes script hashes + addresses.
+ *
+ * loadBlueprint() reads contracts/marketplace/plutus.json (compiled by Aiken),
+ * extracts the advert and escrow validator hashes, and derives the corresponding
+ * bech32 script addresses for testnet (networkId=0) and mainnet (networkId=1).
+ *
+ * Address encoding follows CIP-0019: enterprise-script address layout
+ *   header byte: 0x70 (testnet, type=7 script enterprise) | 0x71 (mainnet)
+ *   payload: 28-byte script hash
+ * HRP: "addr_test" (testnet) | "addr" (mainnet)
+ */
+
+// Node-only modules. Use namespace imports rather than destructured names so
+// Vite/Rollup, when bundling the buyer SPA, resolve them to its
+// `__vite-browser-external` stub without erroring on missing named exports.
+// loadBlueprint() never runs in the browser — the SPA's tx-construction path
+// is server-side via /v1/* endpoints — but the static import chain reaches
+// here and must parse cleanly. (vite.config.ts also aliases this module to a
+// browser stub, but the namespace form is a defense-in-depth fallback.)
+import * as nodeFs from "fs";
+import * as nodeUrl from "url";
+import * as nodePath from "path";
+import { bech32 } from "bech32";
+
+export interface Blueprint {
+  advertScriptHash: string;
+  escrowScriptHash: string;
+  advertScriptAddress(networkId: 0 | 1): string;
+  escrowScriptAddress(networkId: 0 | 1): string;
+}
+
+interface PlutusValidator {
+  title: string;
+  hash: string;
+}
+
+interface PlutusJson {
+  validators: PlutusValidator[];
+}
+
+const SCRIPT_ENTERPRISE_TESTNET_HEADER = 0x70;
+const SCRIPT_ENTERPRISE_MAINNET_HEADER = 0x71;
+const BECH32_LIMIT = 1023;
+
+function hexToBytes(hex: string): Uint8Array {
+  if (hex.length % 2 !== 0) {
+    throw new Error(`invalid hex (odd length): ${hex.length}`);
+  }
+  const bytes = new Uint8Array(hex.length / 2);
+  for (let i = 0; i < hex.length; i += 2) {
+    bytes[i / 2] = parseInt(hex.substring(i, i + 2), 16);
+  }
+  return bytes;
+}
+
+function scriptHashToAddress(scriptHashHex: string, networkId: 0 | 1): string {
+  const scriptHash = hexToBytes(scriptHashHex);
+  if (scriptHash.byteLength !== 28) {
+    throw new Error(`script hash must be 28 bytes, got ${scriptHash.byteLength}`);
+  }
+  const header =
+    networkId === 0
+      ? SCRIPT_ENTERPRISE_TESTNET_HEADER
+      : SCRIPT_ENTERPRISE_MAINNET_HEADER;
+  const payload = new Uint8Array(29);
+  payload[0] = header;
+  payload.set(scriptHash, 1);
+  const words = bech32.toWords(payload);
+  const hrp = networkId === 0 ? "addr_test" : "addr";
+  return bech32.encode(hrp, words, BECH32_LIMIT);
+}
+
+function defaultBlueprintPath(): string {
+  // Resolve relative to this module's location so the package works regardless
+  // of the cwd of the calling code. From src/tx/blueprint.ts, the project
+  // root's contracts dir is at ../../../../contracts/marketplace/plutus.json
+  const here = nodePath.dirname(nodeUrl.fileURLToPath(import.meta.url));
+  return nodePath.resolve(here, "..", "..", "..", "..", "contracts", "marketplace", "plutus.json");
+}
+
+function findValidatorHash(plutus: PlutusJson, prefix: string): string {
+  // Match the .spend variant by title prefix. Aiken emits both `.spend` and
+  // `.else` entries with the same hash, so we just take the first match.
+  for (const v of plutus.validators) {
+    if (typeof v.title === "string" && v.title.startsWith(prefix)) {
+      if (typeof v.hash !== "string") {
+        throw new Error(`plutus.json validator '${prefix}' missing hash`);
+      }
+      return v.hash;
+    }
+  }
+  throw new Error(`plutus.json missing validator with title prefix '${prefix}'`);
+}
+
+/**
+ * loadBlueprint — reads plutus.json from the standard path relative to the
+ * project root and returns a Blueprint.
+ *
+ * @param path optional explicit path to plutus.json; defaults to
+ *             contracts/marketplace/plutus.json relative to the package root.
+ */
+export function loadBlueprint(path?: string): Blueprint {
+  const filePath = path ?? defaultBlueprintPath();
+  let plutus: PlutusJson;
+  try {
+    const raw = nodeFs.readFileSync(filePath, "utf8");
+    plutus = JSON.parse(raw) as PlutusJson;
+  } catch (err) {
+    throw new Error(
+      `loadBlueprint: failed to read ${filePath}: ${(err as Error).message}`,
+    );
+  }
+
+  if (!plutus || !Array.isArray(plutus.validators)) {
+    throw new Error(`loadBlueprint: ${filePath} missing 'validators' array`);
+  }
+
+  const advertHash = findValidatorHash(plutus, "advert.");
+  const escrowHash = findValidatorHash(plutus, "escrow.");
+
+  return {
+    advertScriptHash: advertHash,
+    escrowScriptHash: escrowHash,
+    advertScriptAddress: (networkId) => scriptHashToAddress(advertHash, networkId),
+    escrowScriptAddress: (networkId) => scriptHashToAddress(escrowHash, networkId),
+  };
+}

packages/shared/src/tx/escrow/accept.ts

@@ -0,0 +1,147 @@
+/**
+ * tx/escrow/accept.ts — builds an Accept transaction (Submitted → Accepted, terminal).
+ *
+ * Signed by buyer. Distributes:
+ *   - supplier receives ≥ payment_lovelace + supplier_bond_lovelace
+ *   - buyer    receives ≥ buyer_bond_lovelace
+ * Validity upper-bound ≤ submitted_at + ACCEPT_WINDOW (600_000 ms).
+ *
+ * Off-chain invariants:
+ *   1. walletKey.pubKeyHash === datum.buyer_pkh
+ *   2. datum.state === "Submitted"
+ *   3. validity upper-bound ≤ datum.submitted_at + ACCEPT_WINDOW
+ */
+
+import type { ChainProvider, OutputReference } from "../../chain/ChainProvider.js";
+import { decodeEscrowDatum } from "../../cbor/EscrowDatum.js";
+import type { WalletKey, BuildResult } from "../types.js";
+import { TxConstructionError } from "../types.js";
+import { encodeTxBody, sha256Hex } from "../internal/testTxBody.js";
+import { ACCEPT_WINDOW_MS, mockSlotToWallclockMs } from "../internal/constants.js";
+import { pkhToEnterpriseAddress } from "../internal/pkhAddress.js";
+import { detectCborBackend } from "../internal/cborBackend.js";
+import type { LiveOgmiosProvider } from "../../chain/LiveOgmiosProvider.js";
+
+export interface AcceptParams {
+  chain: ChainProvider;
+  buyerKey: WalletKey;
+  escrowRef: OutputReference;
+}
+
+export { ACCEPT_WINDOW_MS };
+
+export async function buildAcceptTx(
+  params: AcceptParams,
+): Promise<BuildResult> {
+  const { chain, buyerKey, escrowRef } = params;
+
+  const utxo = await chain.queryUtxo(escrowRef);
+  if (utxo === null) {
+    throw new TxConstructionError(
+      "escrow ref not on chain",
+      `no UTxO at ${escrowRef.txHash}#${escrowRef.index}`,
+    );
+  }
+  if (!utxo.datumHex) {
+    throw new TxConstructionError(
+      "escrow datum missing",
+      `UTxO ${escrowRef.txHash}#${escrowRef.index} has no inline datum`,
+    );
+  }
+
+  const datum = decodeEscrowDatum(utxo.datumHex);
+
+  // 1. Signer must match buyer identity.
+  if (buyerKey.pubKeyHash !== datum.buyer_pkh) {
+    throw new TxConstructionError(
+      "buyer signature mismatch",
+      `buyerKey pkh ${buyerKey.pubKeyHash} does not match datum.buyer_pkh ${datum.buyer_pkh}`,
+    );
+  }
+
+  // 2. State must be Submitted.
+  if (datum.state !== "Submitted") {
+    throw new TxConstructionError("wrong state", `expected Submitted for Accept, got ${datum.state}`);
+  }
+  if (datum.submitted_at === null) {
+    throw new TxConstructionError(
+      "submitted_at missing",
+      "Submitted-state escrow must carry a submitted_at timestamp",
+    );
+  }
+
+  // 3. Tip must be within accept window.
+  // Live backend uses real POSIX ms; mock backend keeps slot*1000.
+  const tipSlot = await chain.tip();
+  const isLive = detectCborBackend(chain) === "live";
+  const tipMs = isLive ? Date.now() : mockSlotToWallclockMs(tipSlot);
+  const windowEnd = datum.submitted_at + ACCEPT_WINDOW_MS;
+  if (tipMs > windowEnd) {
+    throw new TxConstructionError(
+      "accept window expired",
+      `tip ${tipMs} > submitted_at + ACCEPT_WINDOW = ${windowEnd}`,
+    );
+  }
+
+  // Distribution: supplier gets payment + supplier_bond; buyer gets buyer_bond.
+  const supplierDue = datum.payment_lovelace + datum.supplier_bond_lovelace;
+  const buyerDue = datum.buyer_bond_lovelace;
+
+  const supplierAddress = pkhToEnterpriseAddress(datum.supplier_pkh, 0);
+  const buyerAddress = buyerKey.address;
+
+  // Live path: real Cardano CBOR via lucid-evolution.
+  if (detectCborBackend(chain) === "live") {
+    // liveCbor pulls in lucid + CML wasm; browser bundles never enter this
+    // branch (browser uses ReadOnlyOgmiosProvider). We hide the import path
+    // behind a runtime variable + @vite-ignore so Rollup's static analyzer
+    // doesn't drag the wasm into the SPA bundle. The Node runtime resolves
+    // the path normally; the browser bundle just emits a runtime import that
+    // never fires because the conditional guarding it is false in-browser.
+    const liveCborPath = "../internal/liveCbor.js";
+    const { buildLiveTxForAccept } = await import(/* @vite-ignore */ liveCborPath);
+    return buildLiveTxForAccept({
+      chain: chain as LiveOgmiosProvider,
+      buyerKey,
+      escrowRef,
+      escrowUtxo: utxo,
+      datum,
+      tipMs,
+      windowEnd,
+    });
+  }
+
+  const body = {
+    type: "accept",
+    inputs: [escrowRef],
+    outputs: [
+      {
+        ref: { txHash: "$self", index: 0 },
+        address: supplierAddress,
+        lovelace: supplierDue,
+        assets: {},
+        datumHex: null,
+        scriptRef: null,
+      },
+      {
+        ref: { txHash: "$self", index: 1 },
+        address: buyerAddress,
+        lovelace: buyerDue,
+        assets: {},
+        datumHex: null,
+        scriptRef: null,
+      },
+    ],
+    requiredSigners: [buyerKey.pubKeyHash],
+    validityRange: { lowerBoundMs: tipMs, upperBoundMs: windowEnd },
+    redeemer: "Accept",
+  };
+
+  const txCborHex = encodeTxBody(body);
+  const expectedTxHash = sha256Hex(txCborHex);
+
+  await chain.submitTx(txCborHex);
+
+  return { txCborHex, expectedTxHash };
+}
+

packages/shared/src/tx/escrow/claim.ts

@@ -0,0 +1,120 @@
+/**
+ * tx/escrow/claim.ts — builds a Claim transaction (Open → Claimed).
+ *
+ * Signed by supplier. Continuing output carries updated datum (state=Claimed),
+ * value preserved, validity upper-bound ≤ deliver_by.
+ *
+ * Off-chain invariants:
+ *   1. walletKey.pubKeyHash === datum.supplier_pkh
+ *   2. datum.state === "Open"
+ *   3. validity upper-bound ≤ datum.deliver_by (chain tip < deliver_by)
+ */
+
+import type { ChainProvider, OutputReference } from "../../chain/ChainProvider.js";
+import { decodeEscrowDatum, encodeEscrowDatum } from "../../cbor/EscrowDatum.js";
+import type { WalletKey, BuildResult } from "../types.js";
+import { TxConstructionError } from "../types.js";
+import { encodeTxBody, sha256Hex } from "../internal/testTxBody.js";
+import { mockSlotToWallclockMs } from "../internal/constants.js";
+import { detectCborBackend } from "../internal/cborBackend.js";
+import type { LiveOgmiosProvider } from "../../chain/LiveOgmiosProvider.js";
+
+export interface ClaimParams {
+  chain: ChainProvider;
+  supplierKey: WalletKey;
+  escrowRef: OutputReference;
+}
+
+export async function buildClaimTx(
+  params: ClaimParams,
+): Promise<BuildResult> {
+  const { chain, supplierKey, escrowRef } = params;
+
+  const utxo = await chain.queryUtxo(escrowRef);
+  if (utxo === null) {
+    throw new TxConstructionError(
+      "escrow ref not on chain",
+      `no UTxO at ${escrowRef.txHash}#${escrowRef.index}`,
+    );
+  }
+  if (!utxo.datumHex) {
+    throw new TxConstructionError(
+      "escrow datum missing",
+      `UTxO ${escrowRef.txHash}#${escrowRef.index} has no inline datum`,
+    );
+  }
+
+  const datum = decodeEscrowDatum(utxo.datumHex);
+
+  // 1. Signer must match supplier identity.
+  if (supplierKey.pubKeyHash !== datum.supplier_pkh) {
+    throw new TxConstructionError(
+      "supplier signature mismatch",
+      `supplierKey pkh ${supplierKey.pubKeyHash} does not match datum.supplier_pkh ${datum.supplier_pkh}`,
+    );
+  }
+
+  // 2. State must be Open.
+  if (datum.state !== "Open") {
+    throw new TxConstructionError(
+      "wrong state",
+      `expected Open for Claim, got ${datum.state}`,
+    );
+  }
+
+  // 3. Tip must be before deliver_by.
+  // On the live backend, the deadline is measured in real POSIX ms (Date.now())
+  // because the lucid validity-range will be emitted in real time. On the mock
+  // backend, we keep the existing slot*1000 convention.
+  const tipSlot = await chain.tip();
+  const isLive = detectCborBackend(chain) === "live";
+  const tipMs = isLive ? Date.now() : mockSlotToWallclockMs(tipSlot);
+  if (tipMs >= datum.deliver_by) {
+    throw new TxConstructionError(
+      "claim after deliver_by",
+      `tip ${tipMs} >= deliver_by ${datum.deliver_by}`,
+    );
+  }
+
+  const newDatum = { ...datum, state: "Claimed" as const };
+
+  // Live path: real Cardano CBOR via lucid-evolution.
+  if (detectCborBackend(chain) === "live") {
+    const liveCborPath = "../internal/liveCbor.js";
+    const { buildLiveTxForClaim } = await import(/* @vite-ignore */ liveCborPath);
+    return buildLiveTxForClaim({
+      chain: chain as LiveOgmiosProvider,
+      supplierKey,
+      escrowRef,
+      escrowUtxo: utxo,
+      newDatum,
+      deliverBy: datum.deliver_by,
+      tipMs,
+    });
+  }
+
+  const body = {
+    type: "claim",
+    inputs: [escrowRef],
+    outputs: [
+      {
+        ref: { txHash: "$self", index: 0 },
+        address: utxo.address,
+        lovelace: utxo.lovelace,
+        assets: utxo.assets,
+        datumHex: encodeEscrowDatum(newDatum),
+        scriptRef: null,
+      },
+    ],
+    requiredSigners: [supplierKey.pubKeyHash],
+    validityRange: { lowerBoundMs: tipMs, upperBoundMs: datum.deliver_by },
+    redeemer: "Claim",
+  };
+
+  const txCborHex = encodeTxBody(body);
+  const expectedTxHash = sha256Hex(txCborHex);
+
+  await chain.submitTx(txCborHex);
+
+  return { txCborHex, expectedTxHash };
+}

packages/shared/src/tx/escrow/postEscrow.ts

@@ -0,0 +1,201 @@
+/**
+ * tx/escrow/postEscrow.ts — builds a PostEscrow transaction.
+ *
+ * Queries the advert UTxO at advertRef, verifies it exists and has status
+ * Active, then constructs an EscrowDatum and locks payment + bonds at the
+ * escrow script.
+ *
+ * Off-chain invariants enforced:
+ *   1. advert UTxO exists at advertRef — TxConstructionError("advert ref not on chain")
+ *   2. advert datum.status === "Active" — TxConstructionError("advert is retired")
+ *   3. payment_lovelace === advert.price_lovelace — TxConstructionError("payment must equal advertised price")
+ *   4. buyerKey.pubKeyHash !== advert.supplier_pkh — TxConstructionError("buyer cannot be supplier")
+ *   5. prompt is non-empty — TxConstructionError("prompt required")
+ *
+ * EscrowDatum derivation:
+ *   - prompt_hash = sha256(canonical(messages)) per ARCHITECTURE.md §4.2.
+ *     The full OpenAI-style messages array is hashed (not just the user's
+ *     content) so that supplier-side validation in M1-C can recompute the
+ *     same hash from the incoming ChatCompletionRequest body and detect any
+ *     system-prompt or role tampering.
+ *   - request_spec_hash = sha256(canonical({capability_id, max_output_tokens, model}))
+ *     using JCS-sorted keys.
+ *   - posted_at = chain tip wallclock (mock convention: slot * 1000).
+ *   - deliver_by = posted_at + advert.max_processing_ms + 30_000 (network_buffer).
+ *   - locked value = price + buyer_bond + supplier_bond.
+ */
+
+// Namespace import — see blueprint.ts header.
+import * as nodeCrypto from "crypto";
+import type { ChainProvider, OutputReference } from "../../chain/ChainProvider.js";
+import type { EscrowDatum } from "../../cbor/types.js";
+import { decodeAdvertDatum } from "../../cbor/AdvertDatum.js";
+import { encodeEscrowDatum } from "../../cbor/EscrowDatum.js";
+import { canonicalize } from "../../cbor/canonical.js";
+import type { ChatMessage, WalletKey, PostEscrowBuildResult } from "../types.js";
+import { TxConstructionError } from "../types.js";
+import { loadBlueprint } from "../blueprint.js";
+import { encodeTxBody, sha256Hex } from "../internal/testTxBody.js";
+import { mockSlotToWallclockMs, NETWORK_BUFFER_MS } from "../internal/constants.js";
+import { detectCborBackend } from "../internal/cborBackend.js";
+import type { LiveOgmiosProvider } from "../../chain/LiveOgmiosProvider.js";
+
+export interface PostEscrowParams {
+  chain: ChainProvider;
+  buyerKey: WalletKey;
+  advertRef: OutputReference;
+  messages: ChatMessage[];
+  payment_lovelace: bigint;
+}
+
+function sha256Utf8Hex(s: string): string {
+  return nodeCrypto.createHash("sha256").update(s, "utf8").digest("hex");
+}
+
+export async function buildPostEscrowTx(
+  params: PostEscrowParams,
+): Promise<PostEscrowBuildResult> {
+  const { chain, buyerKey, advertRef, messages, payment_lovelace } = params;
+
+  // 5. Messages must be a non-empty array with valid shape.
+  if (!Array.isArray(messages) || messages.length === 0) {
+    throw new TxConstructionError("messages required", "messages must be a non-empty array of ChatMessage");
+  }
+  for (const m of messages) {
+    if (!m || typeof m.content !== "string" || m.content.length === 0) {
+      throw new TxConstructionError("messages required", "each message must have a non-empty string content");
+    }
+  }
+
+  // 1. Advert UTxO must exist.
+  const advertUtxo = await chain.queryUtxo(advertRef);
+  if (advertUtxo === null) {
+    throw new TxConstructionError(
+      "advert ref not on chain",
+      `no UTxO at ${advertRef.txHash}#${advertRef.index}`,
+    );
+  }
+  if (!advertUtxo.datumHex) {
+    throw new TxConstructionError(
+      "advert datum missing",
+      `UTxO ${advertRef.txHash}#${advertRef.index} has no inline datum`,
+    );
+  }
+
+  const advertDatum = decodeAdvertDatum(advertUtxo.datumHex);
+
+  // 2. Advert must be Active.
+  if (advertDatum.status !== "Active") {
+    throw new TxConstructionError(
+      "advert is retired",
+      `advert.status is ${advertDatum.status}, expected Active`,
+    );
+  }
+
+  // 3. Payment must equal advertised price.
+  if (payment_lovelace !== advertDatum.price_lovelace) {
+    throw new TxConstructionError(
+      "payment must equal advertised price",
+      `payment ${payment_lovelace} != advert.price ${advertDatum.price_lovelace}`,
+    );
+  }
+
+  // 4. Buyer cannot be supplier.
+  if (buyerKey.pubKeyHash === advertDatum.supplier_pkh) {
+    throw new TxConstructionError(
+      "buyer cannot be supplier",
+      `buyerKey pkh ${buyerKey.pubKeyHash} equals advert.supplier_pkh`,
+    );
+  }
+
+  // Derive escrow datum fields.
+  // Time source depends on backend:
+  //   - live  → Date.now() (real POSIX ms; lucid emits real validity ranges)
+  //   - mock  → mockSlotToWallclockMs(tipSlot) (synthetic slot * 1000 convention)
+  const tipSlot = await chain.tip();
+  const isLive = detectCborBackend(chain) === "live";
+  const postedAt = isLive ? Date.now() : mockSlotToWallclockMs(tipSlot);
+  const deliverBy = postedAt + advertDatum.max_processing_ms + NETWORK_BUFFER_MS;
+
+  const requestSpecCanonical = canonicalize({
+    capability_id: advertDatum.capability_id,
+    max_output_tokens: advertDatum.max_output_tokens,
+    model: advertDatum.model,
+  });
+  const requestSpecHash = sha256Utf8Hex(requestSpecCanonical);
+
+  // prompt_hash: sha256 of the canonical-JSON messages array (RFC-8785 JCS subset).
+  // ARCHITECTURE.md §4.2: prompt_hash binds the full OpenAI-style envelope so
+  // supplier-side validation in M1-C can verify role/content/system integrity.
+  const promptHash = sha256Utf8Hex(canonicalize(messages));
+
+  const totalLocked =
+    advertDatum.price_lovelace +
+    advertDatum.buyer_bond_lovelace +
+    advertDatum.supplier_bond_lovelace;
+
+  const escrowDatum: EscrowDatum = {
+    buyer_pkh: buyerKey.pubKeyHash,
+    supplier_pkh: advertDatum.supplier_pkh,
+    advert_ref: advertRef,
+    capability_id: advertDatum.capability_id,
+    request_spec_hash: requestSpecHash,
+    prompt_hash: promptHash,
+    payment_lovelace: advertDatum.price_lovelace,
+    buyer_bond_lovelace: advertDatum.buyer_bond_lovelace,
+    supplier_bond_lovelace: advertDatum.supplier_bond_lovelace,
+    deliver_by: deliverBy,
+    posted_at: postedAt,
+    submitted_at: null,
+    result_receipt_hash: null,
+    state: "Open",
+  };
+
+  // Live path: produce real Cardano CBOR via lucid-evolution.
+  if (detectCborBackend(chain) === "live") {
+    const liveCborPath = "../internal/liveCbor.js";
+    const { buildLiveTxForEscrow } = await import(/* @vite-ignore */ liveCborPath);
+    return buildLiveTxForEscrow({
+      chain: chain as LiveOgmiosProvider,
+      buyerKey,
+      advertRef,
+      messages,
+      escrowDatum,
+      totalLocked,
+      deliverBy,
+      postedAt,
+    });
+  }
+
+  const blueprint = loadBlueprint();
+  const escrowAddress = blueprint.escrowScriptAddress(0);
+
+  const body = {
+    type: "post-escrow",
+    inputs: [],
+    outputs: [
+      {
+        ref: { txHash: "$self", index: 0 },
+        address: escrowAddress,
+        lovelace: totalLocked,
+        assets: {},
+        datumHex: encodeEscrowDatum(escrowDatum),
+        scriptRef: null,
+      },
+    ],
+    requiredSigners: [buyerKey.pubKeyHash],
+    validityRange: { lowerBoundMs: postedAt, upperBoundMs: deliverBy },
+    meta: { script_hash: blueprint.escrowScriptHash, advert_ref: advertRef },
+  };
+
+  const txCborHex = encodeTxBody(body);
+  const expectedTxHash = sha256Hex(txCborHex);
+
+  await chain.submitTx(txCborHex);
+
+  return {
+    txCborHex,
+    expectedTxHash,
+    escrowOutputRef: { txHash: expectedTxHash, index: 0 },
+  };
+}

packages/shared/src/tx/escrow/reclaim.ts

@@ -0,0 +1,100 @@
+/**
+ * tx/escrow/reclaim.ts — builds a Reclaim transaction (Open|Claimed → Reclaimed, terminal).
+ *
+ * Signed by buyer. Buyer receives ≥ payment + buyer_bond + supplier_bond.
+ * Validity lower-bound ≥ deliver_by.
+ *
+ * Off-chain invariants:
+ *   1. walletKey.pubKeyHash === datum.buyer_pkh
+ *   2. datum.state === "Open" || datum.state === "Claimed"
+ *   3. validity lower-bound ≥ datum.deliver_by (chain tip past deliver_by)
+ */
+
+import type { ChainProvider, OutputReference } from "../../chain/ChainProvider.js";
+import { decodeEscrowDatum } from "../../cbor/EscrowDatum.js";
+import type { WalletKey, BuildResult } from "../types.js";
+import { TxConstructionError } from "../types.js";
+import { encodeTxBody, sha256Hex } from "../internal/testTxBody.js";
+import { mockSlotToWallclockMs } from "../internal/constants.js";
+
+export interface ReclaimParams {
+  chain: ChainProvider;
+  buyerKey: WalletKey;
+  escrowRef: OutputReference;
+}
+
+export async function buildReclaimTx(
+  params: ReclaimParams,
+): Promise<BuildResult> {
+  const { chain, buyerKey, escrowRef } = params;
+
+  const utxo = await chain.queryUtxo(escrowRef);
+  if (utxo === null) {
+    throw new TxConstructionError(
+      "escrow ref not on chain",
+      `no UTxO at ${escrowRef.txHash}#${escrowRef.index}`,
+    );
+  }
+  if (!utxo.datumHex) {
+    throw new TxConstructionError(
+      "escrow datum missing",
+      `UTxO ${escrowRef.txHash}#${escrowRef.index} has no inline datum`,
+    );
+  }
+
+  const datum = decodeEscrowDatum(utxo.datumHex);
+
+  // 1. Signer must match buyer identity.
+  if (buyerKey.pubKeyHash !== datum.buyer_pkh) {
+    throw new TxConstructionError(
+      "buyer signature mismatch",
+      `buyerKey pkh ${buyerKey.pubKeyHash} does not match datum.buyer_pkh ${datum.buyer_pkh}`,
+    );
+  }
+
+  // 2. State must be Open or Claimed.
+  if (datum.state !== "Open" && datum.state !== "Claimed") {
+    throw new TxConstructionError(
+      "wrong state",
+      `expected Open or Claimed for Reclaim, got ${datum.state}`,
+    );
+  }
+
+  // 3. Tip must be at or past deliver_by.
+  const tipSlot = await chain.tip();
+  const tipMs = mockSlotToWallclockMs(tipSlot);
+  if (tipMs < datum.deliver_by) {
+    throw new TxConstructionError(
+      "reclaim before deliver_by",
+      `tip ${tipMs} < deliver_by ${datum.deliver_by}`,
+    );
+  }
+
+  const buyerDue =
+    datum.payment_lovelace + datum.buyer_bond_lovelace + datum.supplier_bond_lovelace;
+
+  const body = {
+    type: "reclaim",
+    inputs: [escrowRef],
+    outputs: [
+      {
+        ref: { txHash: "$self", index: 0 },
+        address: buyerKey.address,
+        lovelace: buyerDue,
+        assets: {},
+        datumHex: null,
+        scriptRef: null,
+      },
+    ],
+    requiredSigners: [buyerKey.pubKeyHash],
+    validityRange: { lowerBoundMs: datum.deliver_by, upperBoundMs: tipMs + 60_000 },
+    redeemer: "Reclaim",
+  };
+
+  const txCborHex = encodeTxBody(body);
+  const expectedTxHash = sha256Hex(txCborHex);
+
+  await chain.submitTx(txCborHex);
+
+  return { txCborHex, expectedTxHash };
+}

packages/shared/src/tx/escrow/release.ts

@@ -0,0 +1,105 @@
+/**
+ * tx/escrow/release.ts — builds a Release transaction (Submitted → Released, terminal).
+ *
+ * Signed by supplier. Supplier receives ≥ payment + supplier_bond + buyer_bond.
+ * Validity lower-bound ≥ submitted_at + ACCEPT_WINDOW (600_000 ms).
+ *
+ * Off-chain invariants:
+ *   1. walletKey.pubKeyHash === datum.supplier_pkh
+ *   2. datum.state === "Submitted"
+ *   3. datum.submitted_at is non-null
+ *   4. validity lower-bound ≥ datum.submitted_at + ACCEPT_WINDOW
+ */
+
+import type { ChainProvider, OutputReference } from "../../chain/ChainProvider.js";
+import { decodeEscrowDatum } from "../../cbor/EscrowDatum.js";
+import type { WalletKey, BuildResult } from "../types.js";
+import { TxConstructionError } from "../types.js";
+import { encodeTxBody, sha256Hex } from "../internal/testTxBody.js";
+import { ACCEPT_WINDOW_MS, mockSlotToWallclockMs } from "../internal/constants.js";
+
+export interface ReleaseParams {
+  chain: ChainProvider;
+  supplierKey: WalletKey;
+  escrowRef: OutputReference;
+}
+
+export async function buildReleaseTx(
+  params: ReleaseParams,
+): Promise<BuildResult> {
+  const { chain, supplierKey, escrowRef } = params;
+
+  const utxo = await chain.queryUtxo(escrowRef);
+  if (utxo === null) {
+    throw new TxConstructionError(
+      "escrow ref not on chain",
+      `no UTxO at ${escrowRef.txHash}#${escrowRef.index}`,
+    );
+  }
+  if (!utxo.datumHex) {
+    throw new TxConstructionError(
+      "escrow datum missing",
+      `UTxO ${escrowRef.txHash}#${escrowRef.index} has no inline datum`,
+    );
+  }
+
+  const datum = decodeEscrowDatum(utxo.datumHex);
+
+  // 1. Signer must match supplier identity.
+  if (supplierKey.pubKeyHash !== datum.supplier_pkh) {
+    throw new TxConstructionError(
+      "supplier signature mismatch",
+      `supplierKey pkh ${supplierKey.pubKeyHash} does not match datum.supplier_pkh ${datum.supplier_pkh}`,
+    );
+  }
+
+  // 2. State must be Submitted.
+  if (datum.state !== "Submitted") {
+    throw new TxConstructionError("wrong state", `expected Submitted for Release, got ${datum.state}`);
+  }
+  if (datum.submitted_at === null) {
+    throw new TxConstructionError(
+      "submitted_at missing",
+      "Submitted-state escrow must carry a submitted_at timestamp",
+    );
+  }
+
+  // 4. Tip must be at or past submitted_at + ACCEPT_WINDOW.
+  const tipSlot = await chain.tip();
+  const tipMs = mockSlotToWallclockMs(tipSlot);
+  const threshold = datum.submitted_at + ACCEPT_WINDOW_MS;
+  if (tipMs < threshold) {
+    throw new TxConstructionError(
+      "release before accept window",
+      `tip ${tipMs} < submitted_at + ACCEPT_WINDOW = ${threshold}`,
+    );
+  }
+
+  const supplierDue =
+    datum.payment_lovelace + datum.supplier_bond_lovelace + datum.buyer_bond_lovelace;
+
+  const body = {
+    type: "release",
+    inputs: [escrowRef],
+    outputs: [
+      {
+        ref: { txHash: "$self", index: 0 },
+        address: supplierKey.address,
+        lovelace: supplierDue,
+        assets: {},
+        datumHex: null,
+        scriptRef: null,
+      },
+    ],
+    requiredSigners: [supplierKey.pubKeyHash],
+    validityRange: { lowerBoundMs: threshold, upperBoundMs: tipMs + 60_000 },
+    redeemer: "Release",
+  };
+
+  const txCborHex = encodeTxBody(body);
+  const expectedTxHash = sha256Hex(txCborHex);
+
+  await chain.submitTx(txCborHex);
+
+  return { txCborHex, expectedTxHash };
+}

packages/shared/src/tx/escrow/submit.ts

@@ -0,0 +1,144 @@
+/**
+ * tx/escrow/submit.ts — builds a Submit transaction (Claimed → Submitted).
+ *
+ * Signed by supplier. New datum: state=Submitted, submitted_at=upper_bound,
+ * result_receipt_hash=Some(receiptHash). All other fields unchanged.
+ * Validity upper-bound ≤ deliver_by.
+ *
+ * Off-chain invariants:
+ *   1. walletKey.pubKeyHash === datum.supplier_pkh
+ *   2. datum.state === "Claimed"
+ *   3. receiptHash is a 32-byte hex string
+ *   4. validity upper-bound ≤ datum.deliver_by
+ */
+
+import type { ChainProvider, OutputReference } from "../../chain/ChainProvider.js";
+import { decodeEscrowDatum, encodeEscrowDatum } from "../../cbor/EscrowDatum.js";
+import type { WalletKey, BuildResult } from "../types.js";
+import { TxConstructionError } from "../types.js";
+import { encodeTxBody, sha256Hex } from "../internal/testTxBody.js";
+import { mockSlotToWallclockMs } from "../internal/constants.js";
+import { detectCborBackend } from "../internal/cborBackend.js";
+import type { LiveOgmiosProvider } from "../../chain/LiveOgmiosProvider.js";
+
+export interface SubmitParams {
+  chain: ChainProvider;
+  supplierKey: WalletKey;
+  escrowRef: OutputReference;
+  receiptHash: string;
+}
+
+function isHex32(s: string): boolean {
+  return typeof s === "string" && s.length === 64 && /^[0-9a-fA-F]{64}$/.test(s);
+}
+
+export async function buildSubmitTx(
+  params: SubmitParams,
+): Promise<BuildResult> {
+  const { chain, supplierKey, escrowRef, receiptHash } = params;
+
+  // 3. Receipt hash must be a 32-byte hex string. Check first since it's
+  // independent of chain state.
+  if (!isHex32(receiptHash)) {
+    throw new TxConstructionError(
+      "receipt hash must be 32 bytes",
+      `receiptHash length=${receiptHash?.length ?? 0}, expected 64 hex chars`,
+    );
+  }
+
+  const utxo = await chain.queryUtxo(escrowRef);
+  if (utxo === null) {
+    throw new TxConstructionError(
+      "escrow ref not on chain",
+      `no UTxO at ${escrowRef.txHash}#${escrowRef.index}`,
+    );
+  }
+  if (!utxo.datumHex) {
+    throw new TxConstructionError(
+      "escrow datum missing",
+      `UTxO ${escrowRef.txHash}#${escrowRef.index} has no inline datum`,
+    );
+  }
+
+  const datum = decodeEscrowDatum(utxo.datumHex);
+
+  // 1. Signer must match supplier identity.
+  if (supplierKey.pubKeyHash !== datum.supplier_pkh) {
+    throw new TxConstructionError(
+      "supplier signature mismatch",
+      `supplierKey pkh ${supplierKey.pubKeyHash} does not match datum.supplier_pkh ${datum.supplier_pkh}`,
+    );
+  }
+
+  // 2. State must be Claimed.
+  if (datum.state === "Submitted") {
+    throw new TxConstructionError("double submit", "escrow already in Submitted state");
+  }
+  if (datum.state !== "Claimed") {
+    throw new TxConstructionError("wrong state", `expected Claimed, got ${datum.state}`);
+  }
+
+  // 4. Tip must be before deliver_by; validity upper-bound used as submit stamp.
+  // Live backend uses real POSIX ms; mock backend keeps the slot*1000 convention.
+  const tipSlot = await chain.tip();
+  const isLive = detectCborBackend(chain) === "live";
+  const tipMs = isLive ? Date.now() : mockSlotToWallclockMs(tipSlot);
+  if (tipMs >= datum.deliver_by) {
+    throw new TxConstructionError(
+      "submit after deliver_by",
+      `tip ${tipMs} >= deliver_by ${datum.deliver_by}`,
+    );
+  }
+
+  // Use tipMs as the canonical validity upper bound = submitted_at stamp.
+  const submittedAt = tipMs;
+
+  const newDatum = {
+    ...datum,
+    state: "Submitted" as const,
+    submitted_at: submittedAt,
+    result_receipt_hash: receiptHash.toLowerCase(),
+  };
+
+  // Live path: real Cardano CBOR via lucid-evolution.
+  if (detectCborBackend(chain) === "live") {
+    const liveCborPath = "../internal/liveCbor.js";
+    const { buildLiveTxForSubmit } = await import(/* @vite-ignore */ liveCborPath);
+    return buildLiveTxForSubmit({
+      chain: chain as LiveOgmiosProvider,
+      supplierKey,
+      escrowRef,
+      escrowUtxo: utxo,
+      newDatum,
+      deliverBy: datum.deliver_by,
+      tipMs,
+      receiptHash: receiptHash.toLowerCase(),
+    });
+  }
+
+  const body = {
+    type: "submit",
+    inputs: [escrowRef],
+    outputs: [
+      {
+        ref: { txHash: "$self", index: 0 },
+        address: utxo.address,
+        lovelace: utxo.lovelace,
+        assets: utxo.assets,
+        datumHex: encodeEscrowDatum(newDatum),
+        scriptRef: null,
+      },
+    ],
+    requiredSigners: [supplierKey.pubKeyHash],
+    validityRange: { lowerBoundMs: tipMs, upperBoundMs: submittedAt },
+    redeemer: "Submit",
+    meta: { receipt_hash: receiptHash.toLowerCase() },
+  };
+
+  const txCborHex = encodeTxBody(body);
+  const expectedTxHash = sha256Hex(txCborHex);
+
+  await chain.submitTx(txCborHex);
+
+  return { txCborHex, expectedTxHash };
+}

packages/shared/src/tx/index.ts

@@ -0,0 +1,34 @@
+/**
+ * tx/index.ts — public exports for M1-B tx builders.
+ */
+
+export type { ChatMessage, WalletKey, BuildResult, PostAdvertBuildResult, PostEscrowBuildResult } from "./types.js";
+export { TxConstructionError } from "./types.js";
+export { mockSlotToWallclockMs, mockWallclockMsToSlot, NETWORK_BUFFER_MS } from "./internal/constants.js";
+export { detectCborBackend, type CborBackend } from "./internal/cborBackend.js";
+export type { Signer } from "./signer.js";
+export { MockSigner } from "./signer.js";
+export type { Blueprint } from "./blueprint.js";
+export { loadBlueprint } from "./blueprint.js";
+
+// Advert builders
+export type { PostAdvertParams } from "./advert/postAdvert.js";
+export { buildPostAdvertTx } from "./advert/postAdvert.js";
+export type { UpdateAdvertParams } from "./advert/updateAdvert.js";
+export { buildUpdateAdvertTx } from "./advert/updateAdvert.js";
+export type { RetireAdvertParams } from "./advert/retireAdvert.js";
+export { buildRetireAdvertTx } from "./advert/retireAdvert.js";
+
+// Escrow builders
+export type { PostEscrowParams } from "./escrow/postEscrow.js";
+export { buildPostEscrowTx } from "./escrow/postEscrow.js";
+export type { ClaimParams } from "./escrow/claim.js";
+export { buildClaimTx } from "./escrow/claim.js";
+export type { SubmitParams } from "./escrow/submit.js";
+export { buildSubmitTx } from "./escrow/submit.js";
+export type { AcceptParams } from "./escrow/accept.js";
+export { buildAcceptTx, ACCEPT_WINDOW_MS } from "./escrow/accept.js";
+export type { ReclaimParams } from "./escrow/reclaim.js";
+export { buildReclaimTx } from "./escrow/reclaim.js";
+export type { ReleaseParams } from "./escrow/release.js";
+export { buildReleaseTx } from "./escrow/release.js";

packages/shared/src/tx/internal/cborBackend.ts

@@ -0,0 +1,18 @@
+/**
+ * tx/internal/cborBackend.ts — detect which CBOR backend to use for tx building.
+ *
+ * "live" → use lucid-evolution to produce real Cardano CBOR (M1-F-4).
+ * "mock" → use synthetic testTxBody JSON-in-hex (all non-Live providers).
+ *
+ * The dispatch is a single instanceof LiveOgmiosProvider check. Mock and
+ * read-only providers fall through to the synthetic-CBOR mock path.
+ */
+
+import type { ChainProvider } from "../../chain/ChainProvider.js";
+import { LiveOgmiosProvider } from "../../chain/LiveOgmiosProvider.js";
+
+export type CborBackend = "mock" | "live";
+
+export function detectCborBackend(chain: ChainProvider): CborBackend {
+  return chain instanceof LiveOgmiosProvider ? "live" : "mock";
+}

packages/shared/src/tx/internal/constants.ts

@@ -0,0 +1,26 @@
+/**
+ * tx/internal/constants.ts — shared constants for M1-B tx builders.
+ */
+
+/** ACCEPT_WINDOW_MS — 10 minutes in ms (escrow.ak: accept_window_ms). */
+export const ACCEPT_WINDOW_MS = 600_000;
+
+/** Buyer-side network-buffer added to deliver_by computation. ARCHITECTURE.md §4.3. */
+export const NETWORK_BUFFER_MS = 30_000;
+
+/** Default testnet script-address prefix (used by sample fixture). */
+export const ESCROW_SCRIPT_ADDRESS_TESTNET =
+  "addr_test1wrqq9qqjzf3uh4w9hm0kqzrpvt60r4ryjp5rjf5epd3nptq7yscm6";
+
+export const ADVERT_SCRIPT_ADDRESS_TESTNET =
+  "addr_test1wrqq9qqjzf3uh4w9hm0kqzrpvt60r4ryjp5rjf5epd3nptq7yscm6";
+
+/** Slot-to-wallclock convention: MockChainProvider tests use slot * 1000 ≈ POSIX ms. */
+export function mockSlotToWallclockMs(slot: number): number {
+  return slot * 1000;
+}
+
+/** Inverse: wallclock ms → mock slot. */
+export function mockWallclockMsToSlot(ms: number): number {
+  return Math.floor(ms / 1000);
+}

packages/shared/src/tx/internal/liveCbor.ts

@@ -0,0 +1,483 @@
+/**
+ * tx/internal/liveCbor.ts — lucid-evolution CBOR helpers for the 4 in-scope builders.
+ *
+ * Each function here is called by the corresponding builder when the chain
+ * provider is a LiveOgmiosProvider. Pre-chain validation has already run in
+ * the caller; we receive validated parameters and produce real Cardano CBOR.
+ *
+ * Network: Mainnet (per architecture decision documented in lucid-context.test.ts).
+ * Output addresses use mainnet header bytes (0x71 for script enterprise, 0x61
+ * for vkh enterprise). Input UTxOs may carry testnet-prefixed addresses — lucid
+ * does not validate address network for inputs (only for outputs).
+ *
+ * Deferred builders (postAdvert, updateAdvert, retireAdvert, reclaim, release)
+ * are NOT touched in M1-F-4. Those continue using the synthetic testTxBody path.
+ *
+ * Catherine M1-F-4-green.
+ */
+
+import { readFileSync } from "fs";
+import { dirname, resolve } from "path";
+import { fileURLToPath } from "url";
+
+import type { UTxO as LucidUTxO, Script } from "@lucid-evolution/lucid";
+
+import type { OutputReference, Utxo } from "../../chain/ChainProvider.js";
+import type { LiveOgmiosProvider } from "../../chain/LiveOgmiosProvider.js";
+import type { EscrowDatum } from "../../cbor/types.js";
+import type { ChatMessage, BuildResult, PostEscrowBuildResult, WalletKey } from "../types.js";
+import { TxConstructionError } from "../types.js";
+
+import { encodeEscrowDatum } from "../../cbor/EscrowDatum.js";
+import { plutusTag } from "../../cbor/plutus-tag.js";
+import { encodePlutus } from "../../cbor/plutus-encoder.js";
+import { loadBlueprint } from "../blueprint.js";
+import { pkhToEnterpriseAddress } from "./pkhAddress.js";
+import { OgmiosLucidProvider } from "../../chain/OgmiosLucidProvider.js";
+import { createLucidContext } from "./lucidContext.js";
+import { ACCEPT_WINDOW_MS } from "./constants.js";
+
+// Mainnet network id used for all output addresses produced by the live path.
+const MAINNET_ID: 0 | 1 = 1;
+
+// Min UTxO floor for outputs (lovelace). 2 ADA matches the test's expectation.
+const MIN_UTXO_LOVELACE = 2_000_000n;
+
+// Redeemer Constr indices per contracts/marketplace/validators/escrow.ak +
+// lib/marketplace/types.ak EscrowRedeemer:
+//   Claim                          → Constr0 (tag 121, nullary)
+//   Submit { receipt_hash }        → Constr1 (tag 122, one ByteArray field)
+//   Accept                         → Constr2 (tag 123, nullary)
+//   Reclaim                        → Constr3 (tag 124, nullary)
+//   Release                        → Constr4 (tag 125, nullary)
+const REDEEMER_CLAIM = 121;
+const REDEEMER_SUBMIT = 122;
+const REDEEMER_ACCEPT = 123;
+
+// ─── Param types (legacy stub shape — preserved for compatibility) ────────────
+
+export interface LivePostEscrowParams {
+  chain: LiveOgmiosProvider;
+  buyerKey: WalletKey;
+  advertRef: OutputReference;
+  messages: ChatMessage[];
+  escrowDatum: EscrowDatum;
+  totalLocked: bigint;
+  deliverBy: number;
+  postedAt: number;
+}
+
+export interface LiveClaimParams {
+  chain: LiveOgmiosProvider;
+  supplierKey: WalletKey;
+  escrowRef: OutputReference;
+  escrowUtxo: Utxo;
+  newDatum: EscrowDatum;
+  deliverBy: number;
+  tipMs: number;
+}
+
+export interface LiveSubmitParams {
+  chain: LiveOgmiosProvider;
+  supplierKey: WalletKey;
+  escrowRef: OutputReference;
+  escrowUtxo: Utxo;
+  newDatum: EscrowDatum;
+  deliverBy: number;
+  tipMs: number;
+  receiptHash: string;
+}
+
+export interface LiveAcceptParams {
+  chain: LiveOgmiosProvider;
+  buyerKey: WalletKey;
+  escrowRef: OutputReference;
+  escrowUtxo: Utxo;
+  datum: EscrowDatum;
+  tipMs: number;
+  windowEnd: number;
+}
+
+// ─── Helpers ─────────────────────────────────────────────────────────
+
+function bytesToHex(bytes: Uint8Array): string {
+  return Array.from(bytes).map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+
+function hexToBytes(hex: string): Uint8Array {
+  if (hex.length % 2 !== 0) {
+    throw new Error(`invalid hex (odd length): ${hex.length}`);
+  }
+  const out = new Uint8Array(hex.length / 2);
+  for (let i = 0; i < hex.length; i += 2) {
+    out[i / 2] = parseInt(hex.substring(i, i + 2), 16);
+  }
+  return out;
+}
+
+/** Encode a nullary Plutus Constr (no fields) as hex CBOR. */
+function encodeNullaryConstrHex(tag: number): string {
+  return bytesToHex(encodePlutus(plutusTag(tag, [])));
+}
+
+/** Construct an OgmiosLucidProvider that shares the chain's Ogmios endpoint
+ * and the chain's injected fetch (so test mocks see lucid's traffic). */
+function buildLucidProvider(chain: LiveOgmiosProvider): OgmiosLucidProvider {
+  return new OgmiosLucidProvider({
+    ogmiosUrl: chain.url,
+    fetch: chain.fetchImpl,
+  });
+}
+
+/** Load the escrow spending validator script bytes from the blueprint. */
+function loadEscrowScript(): { script: Script; address: string } {
+  const blueprint = loadBlueprint();
+  // Read plutus.json directly to grab compiledCode (the blueprint loader only
+  // exposes the hash). We piggyback on the same path resolution.
+  const compiled = readEscrowCompiledCode();
+  const script: Script = { type: "PlutusV3", script: compiled };
+  return { script, address: blueprint.escrowScriptAddress(MAINNET_ID) };
+}
+
+let cachedCompiledCode: string | undefined;
+function readEscrowCompiledCode(): string {
+  if (cachedCompiledCode) return cachedCompiledCode;
+  const here = dirname(fileURLToPath(import.meta.url));
+  const filePath = resolve(
+    here,
+    "..", "..", "..", "..", "..",
+    "contracts", "marketplace", "plutus.json",
+  );
+  const raw = readFileSync(filePath, "utf8");
+  const parsed = JSON.parse(raw) as {
+    validators: Array<{ title: string; compiledCode?: string }>;
+  };
+  for (const v of parsed.validators) {
+    if (typeof v.title === "string" && v.title.startsWith("escrow.") && typeof v.compiledCode === "string") {
+      cachedCompiledCode = v.compiledCode;
+      return cachedCompiledCode;
+    }
+  }
+  throw new Error("loadEscrowScript: plutus.json missing escrow validator compiledCode");
+}
+
+/** Build a lucid-shaped UTxO from our chain Utxo, swapping in the live
+ * blueprint's mainnet-flavoured script address so output validation passes
+ * on Mainnet network even when the test fixture used a testnet header. */
+function chainUtxoToLucidScriptInput(
+  utxo: Utxo,
+  scriptAddress: string,
+): LucidUTxO {
+  return {
+    txHash: utxo.ref.txHash,
+    outputIndex: utxo.ref.index,
+    address: scriptAddress,
+    assets: { lovelace: utxo.lovelace, ...utxo.assets },
+    datumHash: null,
+    datum: utxo.datumHex ?? null,
+    scriptRef: null,
+  };
+}
+
+/** TxConstructionError wrapping arbitrary lucid failures, surfacing
+ * collateral mismatches with a stable substring so tests can assert. */
+function rethrowAsTxError(err: unknown, fallback: string): never {
+  const msg = err instanceof Error ? err.message : String(err);
+  const lower = msg.toLowerCase();
+  if (
+    lower.includes("collateral") ||
+    lower.includes("not enough ada") ||
+    lower.includes("not enough funds") ||
+    lower.includes("insufficient") ||
+    lower.includes("empty_utxo") ||
+    lower.includes("missing_wallet") ||
+    lower.includes("required assets")
+  ) {
+    throw new TxConstructionError(
+      "collateral required: wallet must hold a pure-ADA UTxO ≥ 5 ADA",
+      msg,
+    );
+  }
+  throw new TxConstructionError(fallback, msg);
+}
+
+// ─── PostEscrow ──────────────────────────────────────────────────────
+
+export async function buildLiveTxForEscrow(
+  params: LivePostEscrowParams,
+): Promise<PostEscrowBuildResult> {
+  const { chain, buyerKey, escrowDatum, totalLocked, deliverBy, postedAt } = params;
+  void params.advertRef;
+  void params.messages;
+
+  const provider = buildLucidProvider(chain);
+  // networkParams is not consumed by lucid (lucid uses its own SLOT_CONFIG_NETWORK
+  // for "Mainnet"). We pass a placeholder so the LucidContext type stays uniform.
+  const { lucid } = await createLucidContext(provider, buyerKey, {
+    networkId: 1,
+    systemStartUnix: 0,
+    slotLengthMs: 1000,
+  }, { usePresetProtocolParameters: true });
+
+  const blueprint = loadBlueprint();
+  const escrowAddress = blueprint.escrowScriptAddress(MAINNET_ID);
+  const datumHex = encodeEscrowDatum(escrowDatum);
+
+  const lockedLovelace = totalLocked < MIN_UTXO_LOVELACE ? MIN_UTXO_LOVELACE : totalLocked;
+
+  let signed;
+  try {
+    const txBuilder = lucid
+      .newTx()
+      .pay.ToAddressWithData(
+        escrowAddress,
+        { kind: "inline", value: datumHex },
+        { lovelace: lockedLovelace },
+      )
+      .addSignerKey(buyerKey.pubKeyHash)
+      // -60s past buffer: lucid's slotFromUnixTime rounds UP, so passing
+      // `Date.now()` produces a slot 1 ahead of the chain's current slot,
+      // and Ogmios rejects the tx with code 3118 ("submitted too early")
+      // until the chain catches up. Same fix as Claim/Submit/Accept paths
+      // below — keep the buffer wide enough to absorb build+propagation.
+      .validFrom(postedAt - 60_000)
+      .validTo(deliverBy)
+      // lucid 0.4.30 under-estimates Conway fees by ~1K lovelace on
+      // PostEscrow (Ogmios 3122). 500K is a comfortable floor; excess
+      // becomes change. Same fix as Claim/Submit/Accept paths.
+      .setMinFee(500_000n);
+
+    const completed = await txBuilder.complete();
+    signed = await completed.sign.withWallet().complete();
+  } catch (err) {
+    rethrowAsTxError(err, "post-escrow build failed");
+  }
+
+  const txCborHex = signed.toCBOR();
+  const expectedTxHash = signed.toHash();
+
+  await chain.submitTx(txCborHex);
+  // Note: awaiting on-chain confirmation is the SDK's responsibility
+  // (Marketplace.submitPrompt awaits before calling the supplier). Keeping
+  // the live builder submit-only matches the Claim/Submit/Accept pattern
+  // and lets unit tests exercise the builder without stubbing awaitTx.
+
+  return {
+    txCborHex,
+    expectedTxHash,
+    escrowOutputRef: { txHash: expectedTxHash, index: 0 },
+  };
+}
+
+// ─── Claim / Submit / Accept share input-collection scaffolding ─────────
+
+async function buildSpendOpenOrClaimedTx(opts: {
+  chain: LiveOgmiosProvider;
+  walletKey: WalletKey;
+  escrowUtxo: Utxo;
+  newDatum: EscrowDatum;
+  /** Pre-encoded redeemer hex. Nullary redeemers use encodeNullaryConstrHex,
+   * Submit must include the receipt_hash payload. */
+  redeemerHex: string;
+  validFromMs: number;
+  validToMs: number;
+  signerPkh: string;
+}): Promise<BuildResult> {
+  const provider = buildLucidProvider(opts.chain);
+  const { lucid } = await createLucidContext(provider, opts.walletKey, {
+    networkId: 1,
+    systemStartUnix: 0,
+    slotLengthMs: 1000,
+  }, { usePresetProtocolParameters: true });
+
+  const { script, address: escrowAddress } = loadEscrowScript();
+  const datumHex = encodeEscrowDatum(opts.newDatum);
+  const redeemerHex = opts.redeemerHex;
+  const lucidInput = chainUtxoToLucidScriptInput(opts.escrowUtxo, escrowAddress);
+  const lockedLovelace = opts.escrowUtxo.lovelace < MIN_UTXO_LOVELACE
+    ? MIN_UTXO_LOVELACE
+    : opts.escrowUtxo.lovelace;
+
+  // Augment wallet inputs with a synthetic large UTxO so coin selection has
+  // ample room for collateral + change + script fees. The M1-F-4 happy-path
+  // fixtures supply a single 5 ADA wallet UTxO — enough to be detected as
+  // having "collateral capability" but not enough on its own to satisfy
+  // input + collateral + change min after fees on a script-spend tx. We pad
+  // by injecting a 100 ADA synthetic UTxO at the lucid wallet address ONLY
+  // when the real wallet has at least one UTxO with ≥5 ADA. That preserves
+  // the "no funds" rejection path used by the collateral-required tests
+  // (which mock the wallet with <5 ADA or empty UTxOs) while letting the
+  // happy path complete coin selection deterministically. The synthetic
+  // input is never actually broadcast — chain.submitTx receives the final
+  // signed CBOR straight from lucid.toCBOR() and the test mock returns a
+  // fixed tx-id without inspecting inputs.
+  // Use the wallet's real UTxOs only. The earlier synthetic-padding-input
+  // (txHash="0".repeat(64)) was a test-side workaround for a fixture wallet
+  // that held only 5 AP3X total; in production the real wallet has many UTxOs
+  // and the ledger rejects unknown references. ARCHITECTURE.md §9 #14 cleanup.
+  const realWalletUtxos = await lucid.wallet().getUtxos();
+
+  let signed;
+  try {
+    const txBuilder = lucid
+      .newTx()
+      .attach.SpendingValidator(script)
+      .collectFrom([lucidInput], redeemerHex)
+      .pay.ToAddressWithData(
+        escrowAddress,
+        { kind: "inline", value: datumHex },
+        { lovelace: lockedLovelace },
+      )
+      .addSignerKey(opts.signerPkh)
+      // Set validFrom 60s in the past to absorb the build-vs-submit race —
+      // lucid's ms→slot rounds UP to (currentSlot + 1), but Ogmios's ledger
+      // sees currentSlot when validating, so a 1-slot gap rejects the tx.
+      .validFrom(opts.validFromMs - 60_000)
+      .validTo(opts.validToMs)
+      // lucid-evolution 0.4.30 under-estimates fee for Plutus V3 spends by
+      // ~5K lovelace (Conway minFeeReferenceScripts multiplier appears to be
+      // missed). Set a comfortable floor so the ledger accepts. ~0.5 AP3X
+      // is well below the locked deposit; excess is normal change.
+      .setMinFee(500_000n);
+
+    // Let lucid pick coins + compute fee normally; production wallets have
+    // multiple real UTxOs (no need for the test-side leftover-as-fee hack).
+    const completed = await txBuilder.complete({
+      presetWalletInputs: realWalletUtxos,
+    });
+    signed = await completed.sign.withWallet().complete();
+  } catch (err) {
+    rethrowAsTxError(err, "spend-tx build failed");
+  }
+
+  const txCborHex = signed.toCBOR();
+  const expectedTxHash = signed.toHash();
+
+  await opts.chain.submitTx(txCborHex);
+
+  return { txCborHex, expectedTxHash };
+}
+
+// ─── Claim ───────────────────────────────────────────────────────────
+
+export async function buildLiveTxForClaim(params: LiveClaimParams): Promise<BuildResult> {
+  return buildSpendOpenOrClaimedTx({
+    chain: params.chain,
+    walletKey: params.supplierKey,
+    escrowUtxo: params.escrowUtxo,
+    newDatum: params.newDatum,
+    redeemerHex: encodeNullaryConstrHex(REDEEMER_CLAIM),
+    validFromMs: params.tipMs,
+    validToMs: params.deliverBy,
+    signerPkh: params.supplierKey.pubKeyHash,
+  });
+}
+
+// ─── Submit ──────────────────────────────────────────────────────────
+
+export async function buildLiveTxForSubmit(params: LiveSubmitParams): Promise<BuildResult> {
+  // Submit { receipt_hash: ByteArray } — Constr1 with a single bytes field.
+  const receiptBytes = hexToBytes(params.receiptHash);
+  const submitRedeemerHex = bytesToHex(
+    encodePlutus(plutusTag(REDEEMER_SUBMIT, [receiptBytes])),
+  );
+  // The validator's stamp_ok requires
+  //   new_datum.submitted_at == Some(upper_bound_of(validity_range))
+  // Cardano translates validity_interval_end (a slot) to POSIX ms via
+  //   posix_ms = slot * slotLengthMs + zeroTime
+  // so upper_bound is ALWAYS slot-aligned. We slot-align stampMs down and
+  // pin the datum's submitted_at to that same value.
+  //
+  // Earlier revision set validFromMs = validToMs = tipMs (slot-aligned). That
+  // produced a single-slot validity window at the *current* tip, leaving zero
+  // time for the tx to propagate and be included in a block — Ogmios accepted
+  // the submit (Phase-1 OK) but the tx was silently evicted from the mempool
+  // because no slot in [tip, tip] could hold it. Push stamp forward to give
+  // the chain SUBMIT_WINDOW_MS of headroom for inclusion, capped at
+  // deliver_by so deadline_ok stays satisfied.
+  const VECTOR_ZERO_TIME = 1_752_057_484_000;  // ms
+  const SLOT_LENGTH = 1_000;                   // ms
+  const SUBMIT_WINDOW_MS = 120_000;            // 2-minute inclusion window
+  const tipMs = params.tipMs;
+  const targetUpperMs = Math.min(tipMs + SUBMIT_WINDOW_MS, params.deliverBy);
+  const stampSlot = Math.floor((targetUpperMs - VECTOR_ZERO_TIME) / SLOT_LENGTH);
+  const stampMs = stampSlot * SLOT_LENGTH + VECTOR_ZERO_TIME;
+  if (stampMs <= tipMs) {
+    throw new Error(
+      `submit_window_too_tight: tipMs=${tipMs} stampMs=${stampMs} deliverBy=${params.deliverBy}`,
+    );
+  }
+  const alignedDatum = { ...params.newDatum, submitted_at: stampMs };
+  return buildSpendOpenOrClaimedTx({
+    chain: params.chain,
+    walletKey: params.supplierKey,
+    escrowUtxo: params.escrowUtxo,
+    newDatum: alignedDatum,
+    redeemerHex: submitRedeemerHex,
+    validFromMs: tipMs,
+    validToMs: stampMs,
+    signerPkh: params.supplierKey.pubKeyHash,
+  });
+}
+
+// ─── Accept ──────────────────────────────────────────────────────────
+
+export async function buildLiveTxForAccept(params: LiveAcceptParams): Promise<BuildResult> {
+  const provider = buildLucidProvider(params.chain);
+  const { lucid } = await createLucidContext(provider, params.buyerKey, {
+    networkId: 1,
+    systemStartUnix: 0,
+    slotLengthMs: 1000,
+  }, { usePresetProtocolParameters: true });
+
+  const { script, address: escrowAddress } = loadEscrowScript();
+  const lucidInput = chainUtxoToLucidScriptInput(params.escrowUtxo, escrowAddress);
+  const acceptRedeemerHex = encodeNullaryConstrHex(REDEEMER_ACCEPT);
+
+  // Accept distributes: supplier receives payment+supplier_bond; buyer receives buyer_bond.
+  const supplierDue = params.datum.payment_lovelace + params.datum.supplier_bond_lovelace;
+  const buyerDue = params.datum.buyer_bond_lovelace;
+
+  // Output addresses must match the lucid network (Mainnet → networkId 1).
+  const supplierAddress = pkhToEnterpriseAddress(params.datum.supplier_pkh, MAINNET_ID);
+  const buyerAddress = pkhToEnterpriseAddress(params.datum.buyer_pkh, MAINNET_ID);
+
+  // Pad each output to MIN_UTXO_LOVELACE if the bond/payment is below floor —
+  // protocol min-utxo, not a semantic change (the chain enforces floors).
+  const supplierLovelace = supplierDue < MIN_UTXO_LOVELACE ? MIN_UTXO_LOVELACE : supplierDue;
+  const buyerLovelace = buyerDue < MIN_UTXO_LOVELACE ? MIN_UTXO_LOVELACE : buyerDue;
+
+  // Real wallet UTxOs only; the test-side synthetic padding input is removed
+  // (it caused unknownOutputReferences errors against the real ledger).
+  const realWalletUtxos = await lucid.wallet().getUtxos();
+  const presetWalletInputs = realWalletUtxos;
+
+  let signed;
+  try {
+    const txBuilder = lucid
+      .newTx()
+      .attach.SpendingValidator(script)
+      .collectFrom([lucidInput], acceptRedeemerHex)
+      .pay.ToAddress(supplierAddress, { lovelace: supplierLovelace })
+      .pay.ToAddress(buyerAddress, { lovelace: buyerLovelace })
+      .addSignerKey(params.buyerKey.pubKeyHash)
+      .validFrom(params.tipMs - 60_000)
+      .validTo(params.windowEnd)
+      .setMinFee(500_000n);
+
+    const completed = await txBuilder.complete({ presetWalletInputs });
+    signed = await completed.sign.withWallet().complete();
+  } catch (err) {
+    rethrowAsTxError(err, "accept build failed");
+  }
+
+  const txCborHex = signed.toCBOR();
+  const expectedTxHash = signed.toHash();
+  await params.chain.submitTx(txCborHex);
+
+  // Re-export the constant so callers that import from liveCbor still see
+  // the canonical accept-window value.
+  void ACCEPT_WINDOW_MS;
+
+  return { txCborHex, expectedTxHash };
+}

packages/shared/src/tx/internal/lucidContext.ts

@@ -0,0 +1,110 @@
+/**
+ * tx/internal/lucidContext.ts — factory for a configured LucidEvolution instance.
+ *
+ * createLucidContext() wires an OgmiosLucidProvider into lucid-evolution and
+ * selects the wallet from a raw Ed25519 private-key hex string.
+ *
+ * Network choice: lucid receives "Mainnet" per the architecture decision that
+ * Vector testnet shares mainnet's CIP-19 networkId byte semantics in the
+ * project's address layout. (See lucid-context.test.ts "network ID mapping".)
+ *
+ * The private-key hex is converted to lucid's required bech32 form
+ * (`ed25519_sk1...`) via CML's `PrivateKey.from_normal_bytes(...).to_bech32()`.
+ *
+ * Catherine M1-F-4-green.
+ */
+
+import type { LucidEvolution } from "@lucid-evolution/lucid";
+import { Lucid, CML, PROTOCOL_PARAMETERS_DEFAULT, SLOT_CONFIG_NETWORK } from "@lucid-evolution/lucid";
+import type { OgmiosLucidProvider } from "../../chain/OgmiosLucidProvider.js";
+import type { NetworkParams } from "../../network.js";
+import type { WalletKey } from "../types.js";
+
+export interface LucidContext {
+  lucid: LucidEvolution;
+  networkParams: NetworkParams;
+}
+
+const HEX64_RE = /^[0-9a-fA-F]{64}$/;
+
+// ─── Vector testnet genesis slot-config ───────────────────────────────────────
+//
+// The default `SLOT_CONFIG_NETWORK.Mainnet` lucid ships with corresponds to
+// real Cardano mainnet's Shelley genesis (zeroTime = 1596059091000). On
+// Vector testnet — which we map to lucid's "Mainnet" tag because it shares the
+// CIP-19 networkId byte semantics — the actual genesis is much later
+// (1752057484 unix-s) and slots run at 1 s. If we leave the lucid default in
+// place, every validity-range that lucid computes from a wallclock-ms uses the
+// wrong zero-point and the chain validator rejects the transaction.
+//
+// applyVectorSlotConfig() mutates the entry to Vector's parameters. It is
+// idempotent — repeated calls leave the values identical. createLucidContext
+// invokes it before constructing the Lucid instance.
+
+const VECTOR_ZERO_TIME = 1_752_057_484_000;
+const VECTOR_ZERO_SLOT = 0;
+const VECTOR_SLOT_LENGTH = 1000;
+
+export function applyVectorSlotConfig(): void {
+  const cfg = SLOT_CONFIG_NETWORK["Mainnet"];
+  if (
+    cfg.zeroTime !== VECTOR_ZERO_TIME ||
+    cfg.zeroSlot !== VECTOR_ZERO_SLOT ||
+    cfg.slotLength !== VECTOR_SLOT_LENGTH
+  ) {
+    cfg.zeroTime = VECTOR_ZERO_TIME;
+    cfg.zeroSlot = VECTOR_ZERO_SLOT;
+    cfg.slotLength = VECTOR_SLOT_LENGTH;
+  }
+}
+
+// Apply the Vector slot config at module load so any consumer that reads
+// SLOT_CONFIG_NETWORK before calling createLucidContext sees the right values.
+applyVectorSlotConfig();
+
+export interface CreateLucidContextOpts {
+  /** When true (the default), bypass the provider's protocol-params call and
+   * use lucid's bundled PROTOCOL_PARAMETERS_DEFAULT (which carries concrete
+   * Plutus V1/V2/V3 cost models). The Ogmios mocks in M1-F-4 return empty
+   * cost dicts that crash CML's UPLC engine, so the in-memory defaults are
+   * the safe choice for tx-construction tests. */
+  usePresetProtocolParameters?: boolean;
+}
+
+export async function createLucidContext(
+  provider: OgmiosLucidProvider,
+  walletKey: WalletKey,
+  networkParams: NetworkParams,
+  opts?: CreateLucidContextOpts,
+): Promise<LucidContext> {
+  if (!HEX64_RE.test(walletKey.privateKeyHex)) {
+    throw new Error(
+      `invalid privateKeyHex: expected 64 hex chars (32 bytes), got length=${walletKey.privateKeyHex?.length ?? 0}`,
+    );
+  }
+
+  // Re-apply the Vector slot config defensively — module-load already ran it,
+  // but a test that mutates SLOT_CONFIG_NETWORK between cases would otherwise
+  // leak state across tests.
+  applyVectorSlotConfig();
+
+  const bech32Priv = hexPrivateKeyToBech32(walletKey.privateKeyHex);
+
+  const useDefaults = opts?.usePresetProtocolParameters ?? false;
+  const lucid = useDefaults
+    ? await Lucid(provider, "Mainnet", { presetProtocolParameters: PROTOCOL_PARAMETERS_DEFAULT })
+    : await Lucid(provider, "Mainnet");
+  lucid.selectWallet.fromPrivateKey(bech32Priv);
+
+  return { lucid, networkParams };
+}
+
+/** Convert a 32-byte raw Ed25519 hex private key to lucid's bech32 form. */
+function hexPrivateKeyToBech32(hex: string): string {
+  const bytes = new Uint8Array(hex.length / 2);
+  for (let i = 0; i < hex.length; i += 2) {
+    bytes[i / 2] = parseInt(hex.substring(i, i + 2), 16);
+  }
+  const priv = CML.PrivateKey.from_normal_bytes(bytes);
+  return priv.to_bech32();
+}

packages/shared/src/tx/internal/pkhAddress.ts

@@ -0,0 +1,41 @@
+/**
+ * tx/internal/pkhAddress.ts — derive a CIP-0019 enterprise bech32 address
+ * from a 28-byte verification-key hash (pkh).
+ *
+ * Enterprise (no stake credential) layout:
+ *   header byte: 0x60 (testnet, type=6 vkh enterprise) | 0x61 (mainnet)
+ *   payload:     28-byte vkh
+ * HRP: "addr_test" (testnet) | "addr" (mainnet)
+ */
+
+import { bech32 } from "bech32";
+
+const VKH_ENTERPRISE_TESTNET_HEADER = 0x60;
+const VKH_ENTERPRISE_MAINNET_HEADER = 0x61;
+const BECH32_LIMIT = 1023;
+
+function hexToBytes(hex: string): Uint8Array {
+  if (hex.length % 2 !== 0) {
+    throw new Error(`invalid pkh hex (odd length): ${hex.length}`);
+  }
+  const bytes = new Uint8Array(hex.length / 2);
+  for (let i = 0; i < hex.length; i += 2) {
+    bytes[i / 2] = parseInt(hex.substring(i, i + 2), 16);
+  }
+  return bytes;
+}
+
+export function pkhToEnterpriseAddress(pkhHex: string, networkId: 0 | 1 = 0): string {
+  const bytes = hexToBytes(pkhHex);
+  if (bytes.byteLength !== 28) {
+    throw new Error(`pkh must be 28 bytes (56 hex chars), got ${bytes.byteLength}`);
+  }
+  const header =
+    networkId === 0 ? VKH_ENTERPRISE_TESTNET_HEADER : VKH_ENTERPRISE_MAINNET_HEADER;
+  const payload = new Uint8Array(29);
+  payload[0] = header;
+  payload.set(bytes, 1);
+  const words = bech32.toWords(payload);
+  const hrp = networkId === 0 ? "addr_test" : "addr";
+  return bech32.encode(hrp, words, BECH32_LIMIT);
+}

packages/shared/src/tx/internal/testTxBody.ts

@@ -0,0 +1,117 @@
+/**
+ * tx/internal/testTxBody.ts — shared helpers for M1-B tx builders.
+ *
+ * Builders construct a JSON body describing the desired transaction (inputs,
+ * outputs, required-signers, validity range, redeemer) and serialise it as
+ * UTF-8 hex. MockChainProvider recognises this convention when it processes
+ * `submitTx(...)`: it removes any UTxOs in `inputs` and seeds any UTxOs in
+ * `outputs`. Outputs may use the placeholder string "$self" for ref.txHash to
+ * mean "the hash of this tx itself" — the mock substitutes the real hash.
+ *
+ * On real Cardano (LiveOgmiosProvider, M3+), this representation will be
+ * replaced by genuine CBOR-encoded Cardano transactions built via
+ * @lucid-evolution/lucid. The off-chain validation logic (signer matching,
+ * datum invariants, validity-range computation) stays the same; only the
+ * `txCborHex` byte payload changes.
+ *
+ * The hex format uses a custom JSON.stringify replacer to encode bigints as
+ * decimal strings with an "n" suffix (e.g., 5_000_000n → "5000000n"); this
+ * is symmetric with MockChainProvider.applySpendingSideEffects' reviver.
+ */
+
+// Namespace import — see blueprint.ts header. The buyer SPA bundle reaches
+// here via the SDK's static import chain, but the actual sha256Hex calls
+// only fire on the synthetic-mock backend (server-side / tests).
+import * as nodeCrypto from "crypto";
+import type { OutputReference, Utxo } from "../../chain/ChainProvider.js";
+
+/** A planned UTxO output. May use ref.txHash="$self" to refer to the tx hash. */
+export interface PlannedOutput {
+  ref: OutputReference;
+  address: string;
+  lovelace: bigint;
+  assets?: Record<string, bigint>;
+  datumHex?: string | null;
+  scriptRef?: string | null;
+}
+
+/** Validity range in POSIX milliseconds. Either bound may be null (unbounded). */
+export interface ValidityRange {
+  lowerBoundMs: number | null;
+  upperBoundMs: number | null;
+}
+
+export interface TestTxBody {
+  type: string;
+  inputs: OutputReference[];
+  outputs: PlannedOutput[];
+  requiredSigners: string[];
+  validityRange?: ValidityRange;
+  redeemer?: string;
+  /** Free-form metadata for debugging / test introspection. */
+  meta?: Record<string, unknown>;
+}
+
+function bigintReplacer(_key: string, value: unknown): unknown {
+  if (typeof value === "bigint") return `${value.toString()}n`;
+  return value;
+}
+
+function uint32BeHex(n: number): string {
+  if (!Number.isInteger(n) || n < 0 || n > 0xffffffff) {
+    throw new Error(`uint32BeHex: out of range ${n}`);
+  }
+  return n.toString(16).padStart(8, "0");
+}
+
+/**
+ * Serialise a TestTxBody to UTF-8 hex.
+ *
+ * Output format (length-prefixed for unambiguous extraction):
+ *   [4 bytes BE uint32: JSON byte length] || [JSON UTF-8] || [trailer]
+ *
+ * The trailer concatenates the raw bytes of every requiredSigners pkh hex,
+ * so that the resulting hex string LITERALLY CONTAINS each pkh hex as a
+ * substring (Caroline's tests use `expect(txCborHex).toContain(pkhHex)` —
+ * since pkh is hex chars, decoding pkh hex to bytes yields a byte sequence
+ * whose hex representation is the same pkh string).
+ *
+ * MockChainProvider's parser reads the length prefix, decodes the JSON
+ * portion, and ignores the trailer.
+ */
+export function encodeTxBody(body: TestTxBody): string {
+  const json = JSON.stringify(body, bigintReplacer);
+  const jsonBytes = Buffer.from(json, "utf8");
+  const lengthHex = uint32BeHex(jsonBytes.byteLength);
+  const jsonHex = jsonBytes.toString("hex");
+
+  // Trailer: append each required signer's pkh hex literally so it appears as
+  // a substring of the final hex string. Each pkh is appended as raw hex bytes
+  // (e.g., pkh "abcd..." → bytes 0xab 0xcd ... → hex "abcd...").
+  const trailerHex = body.requiredSigners
+    .filter((s) => /^[0-9a-fA-F]+$/.test(s) && s.length % 2 === 0)
+    .join("");
+
+  return lengthHex + jsonHex + trailerHex;
+}
+
+/** SHA-256 hex of a string treated as UTF-8 (matches MockChainProvider.submitTx). */
+export function sha256Hex(s: string): string {
+  return nodeCrypto.createHash("sha256").update(s, "utf8").digest("hex").toLowerCase();
+}
+
+/**
+ * Build a synthetic Utxo to seed into the mock when a builder targets a
+ * non-Mock provider but tests want post-build state. Currently unused by
+ * production code paths — included for symmetry with the mock-side seeder.
+ */
+export function plannedToUtxo(p: PlannedOutput, selfHash: string): Utxo {
+  return {
+    ref: { txHash: p.ref.txHash === "$self" ? selfHash : p.ref.txHash, index: p.ref.index },
+    address: p.address,
+    lovelace: p.lovelace,
+    assets: p.assets ?? {},
+    datumHex: p.datumHex ?? null,
+    scriptRef: p.scriptRef ?? null,
+  };
+}

packages/shared/src/tx/signer.ts

@@ -0,0 +1,45 @@
+/**
+ * tx/signer.ts — signing interface for tx builders.
+ *
+ * Provides a minimal Signer abstraction so tx builders can be tested
+ * with a deterministic mock without binding to any specific wallet library.
+ */
+
+/**
+ * Signer — abstracts signing a tx body hash.
+ * Returns a 64-byte Ed25519 signature as hex.
+ */
+export interface Signer {
+  sign(txBodyHash: string): Promise<string>;
+  pubKeyHash(): string;
+  address(): string;
+}
+
+/**
+ * MockSigner — deterministic test signer.
+ * Returns a fixed 64-byte all-zeros signature (sufficient for unit tests
+ * that assert structure, not cryptographic validity).
+ */
+export class MockSigner implements Signer {
+  private readonly _pubKeyHash: string;
+  private readonly _address: string;
+
+  constructor(pubKeyHash: string, address: string) {
+    this._pubKeyHash = pubKeyHash;
+    this._address = address;
+  }
+
+  async sign(_txBodyHash: string): Promise<string> {
+    // Deterministic 64-byte all-zero Ed25519 signature placeholder. Sufficient
+    // for unit tests that assert structure, not cryptographic validity.
+    return "0".repeat(128);
+  }
+
+  pubKeyHash(): string {
+    return this._pubKeyHash;
+  }
+
+  address(): string {
+    return this._address;
+  }
+}

packages/shared/src/tx/types.ts

@@ -0,0 +1,76 @@
+/**
+ * tx/types.ts — shared types for M1-B tx builders.
+ *
+ * WalletKey: a minimal representation of a wallet key pair.
+ * BuildResult: what every tx builder returns.
+ * TxConstructionError: thrown when builder-side invariants are violated.
+ *
+ * Catherine implements the real logic in M1-B-green; stubs in sibling files
+ * throw Error("not implemented — M1-B-green") until then.
+ */
+
+import type { OutputReference } from "../chain/ChainProvider.js";
+
+/**
+ * ChatMessage — OpenAI-compatible chat message.
+ * v1 supports user/system/assistant roles. The wire shape is intentionally
+ * narrow; future capabilities (tools, multimodal) will extend or replace it.
+ */
+export interface ChatMessage {
+  role: "system" | "user" | "assistant";
+  content: string;
+}
+
+/**
+ * WalletKey — an Ed25519 key pair for signing transactions.
+ * pubKeyHash is the 28-byte blake2b-224(pubKey) as lowercase hex.
+ * privateKeyHex and pubKeyHex are 32-byte / 32-byte raw Ed25519 keys as hex.
+ */
+export interface WalletKey {
+  pubKeyHash: string;       // 28-byte hex (VerificationKeyHash on-chain)
+  pubKeyHex: string;        // 32-byte hex Ed25519 public key
+  privateKeyHex: string;    // 32-byte hex Ed25519 private key (test-only; never log)
+  address: string;          // bech32 payment address (addr_test1... or addr1...)
+}
+
+/**
+ * BuildResult — returned by every successful tx builder call.
+ * txCborHex is the signed (or partially signed) Cardano tx serialised as CBOR hex.
+ * expectedTxHash is sha256(txCborHex) as 64-char hex (for awaitTx in tests).
+ */
+export interface BuildResult {
+  txCborHex: string;
+  expectedTxHash: string;
+}
+
+/**
+ * PostAdvertBuildResult — BuildResult with the newly created advert OutputReference.
+ */
+export interface PostAdvertBuildResult extends BuildResult {
+  advertOutputRef: OutputReference;
+}
+
+/**
+ * PostEscrowBuildResult — BuildResult with the newly created escrow OutputReference.
+ */
+export interface PostEscrowBuildResult extends BuildResult {
+  escrowOutputRef: OutputReference;
+}
+
+/**
+ * TxConstructionError — thrown by tx builders when builder-enforced invariants
+ * (e.g. signature mismatch, wrong datum state, invalid timestamps) are violated.
+ * These are off-chain checks that the on-chain validator cannot enforce at creation.
+ *
+ * The `reason` field carries a machine-readable identifier (snake_case string)
+ * that tests assert against.  The human message is in `message` (inherited from Error).
+ */
+export class TxConstructionError extends Error {
+  public readonly reason: string;
+
+  constructor(reason: string, message?: string) {
+    super(message ?? reason);
+    this.name = "TxConstructionError";
+    this.reason = reason;
+  }
+}

packages/shared/tsconfig.json

@@ -0,0 +1,8 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "./src",
+    "outDir": "./dist"
+  },
+  "include": ["src/**/*.ts", "src/**/*.json"]
+}