@oracle-agent/oracle 0.1.0 → 0.2.0

package/src/data/providers/poly-clob.mjs

@@ -0,0 +1,460 @@
+import { stampPrepared } from "../../prepare-envelope.mjs";
+// Polymarket CLOB — prepare + local sign helpers for Oracle.
+// Prepare path builds unsigned EIP-712 order envelopes (no keys).
+// Sign/post is for @oracle-agent/operator poly-exec (local only, no VPS).
+
+import { createHmac, randomInt } from "node:crypto";
+import {
+  Wallet,
+  keccak256,
+  concat,
+  hexlify,
+  toUtf8Bytes,
+  zeroPadValue,
+  getCreate2Address,
+  AbiCoder,
+} from "ethers";
+
+export const POLY_CHAIN_ID = 137;
+export const POLY_CLOB_REST = "https://clob.polymarket.com";
+
+const CTF_EXCHANGE_V2 = "0xE111180000d2663C0091e4f400237545B87B996B";
+const NEG_RISK_CTF_EXCHANGE_V2 = "0xe2222d279d744050d28e00520010520000310F59";
+const BYTES32_ZERO =
+  "0x0000000000000000000000000000000000000000000000000000000000000000";
+const COLLATERAL_DECIMALS = 6;
+
+// Deposit wallet CREATE2 (Polymarket relayer)
+const DEPOSIT_WALLET_FACTORY = "0x00000000000Fb5C9ADea0298D729A0CB3823Cc07";
+const DEPOSIT_WALLET_IMPLEMENTATION = "0x58CA52ebe0DadfdF531Cde7062e76746de4Db1eB";
+const ERC1967_CONST1 = "0xcc3735a920a3ca505d382bbc545af43d6000803e6038573d6000fd5b3d6000f3";
+const ERC1967_CONST2 = "0x5155f3363d3d373d3d363d7f360894a13ba1a3210667c828492db98dca3e2076";
+const ERC1967_PREFIX = 0x61003d3d8160233d3973n;
+
+const EIP712_DOMAIN_V2 = {
+  name: "Polymarket CTF Exchange",
+  version: "2",
+  chainId: POLY_CHAIN_ID,
+};
+
+const ORDER_TYPES_V2 = {
+  Order: [
+    { name: "salt", type: "uint256" },
+    { name: "maker", type: "address" },
+    { name: "signer", type: "address" },
+    { name: "tokenId", type: "uint256" },
+    { name: "makerAmount", type: "uint256" },
+    { name: "takerAmount", type: "uint256" },
+    { name: "side", type: "uint8" },
+    { name: "signatureType", type: "uint8" },
+    { name: "timestamp", type: "uint256" },
+    { name: "metadata", type: "bytes32" },
+    { name: "builder", type: "bytes32" },
+  ],
+};
+
+const ROUNDING_CONFIG = {
+  "0.1": { price: 1, size: 2, amount: 3 },
+  "0.01": { price: 2, size: 2, amount: 4 },
+  "0.001": { price: 3, size: 2, amount: 5 },
+  "0.0001": { price: 4, size: 2, amount: 6 },
+};
+
+function _initCodeHashERC1967(implementation, args) {
+  const argHex = args.startsWith("0x") ? args.slice(2) : args;
+  const n = BigInt(argHex.length / 2);
+  const combined = ERC1967_PREFIX + (n << 56n);
+  const prefixHex = "0x" + combined.toString(16).padStart(20, "0");
+  return keccak256(concat([prefixHex, implementation, "0x6009", ERC1967_CONST2, ERC1967_CONST1, args]));
+}
+
+/** Deterministic Polymarket deposit wallet for an EOA (Polygon). */
+export function deriveDepositWallet(owner) {
+  const walletId = zeroPadValue(String(owner).toLowerCase(), 32);
+  const args = AbiCoder.defaultAbiCoder().encode(
+    ["address", "bytes32"],
+    [DEPOSIT_WALLET_FACTORY, walletId]
+  );
+  const salt = keccak256(args);
+  const bytecodeHash = _initCodeHashERC1967(DEPOSIT_WALLET_IMPLEMENTATION, args);
+  return getCreate2Address(DEPOSIT_WALLET_FACTORY, salt, bytecodeHash);
+}
+
+function decimalPlaces(n) {
+  const s = String(n);
+  if (!s.includes(".")) return 0;
+  return s.split(".")[1].replace(/0+$/, "").length;
+}
+
+function roundDown(n, dp) {
+  const f = 10 ** dp;
+  return Math.floor(n * f + 1e-12) / f;
+}
+
+function roundUp(n, dp) {
+  const f = 10 ** dp;
+  return Math.ceil(n * f - 1e-12) / f;
+}
+
+function roundNormal(n, dp) {
+  const f = 10 ** dp;
+  return Math.round(n * f + Number.EPSILON) / f;
+}
+
+/** Official-client-style maker/taker raw amounts (decimal, not fixed-point). */
+export function getOrderRawAmounts(side, size, price, roundConfig) {
+  const rawPrice = roundNormal(Number(price), roundConfig.price);
+  const isBuy = side === "BUY";
+
+  if (isBuy) {
+    const rawTakerAmt = roundDown(Number(size), roundConfig.size);
+    let rawMakerAmt = rawTakerAmt * rawPrice;
+    if (decimalPlaces(rawMakerAmt) > roundConfig.amount) {
+      rawMakerAmt = roundUp(rawMakerAmt, roundConfig.amount + 4);
+      if (decimalPlaces(rawMakerAmt) > roundConfig.amount) {
+        rawMakerAmt = roundDown(rawMakerAmt, roundConfig.amount);
+      }
+    }
+    return { rawMakerAmt, rawTakerAmt };
+  }
+
+  const rawMakerAmt = roundDown(Number(size), roundConfig.size);
+  let rawTakerAmt = rawMakerAmt * rawPrice;
+  if (decimalPlaces(rawTakerAmt) > roundConfig.amount) {
+    rawTakerAmt = roundUp(rawTakerAmt, roundConfig.amount + 4);
+    if (decimalPlaces(rawTakerAmt) > roundConfig.amount) {
+      rawTakerAmt = roundDown(rawTakerAmt, roundConfig.amount);
+    }
+  }
+  return { rawMakerAmt, rawTakerAmt };
+}
+
+export function toRawAmountStr(value) {
+  const str = Number(value).toFixed(COLLATERAL_DECIMALS);
+  const [integer, fraction = ""] = str.split(".");
+  const raw = integer + fraction.padEnd(COLLATERAL_DECIMALS, "0").slice(0, COLLATERAL_DECIMALS);
+  return raw.replace(/^0+/, "") || "0";
+}
+
+export function buildHmacSignature(secret, timestamp, method, requestPath, body) {
+  let message = String(timestamp) + method + requestPath;
+  if (body) message += body;
+  // Polymarket secrets are base64 (sometimes base64url)
+  const normalized = String(secret).replace(/-/g, "+").replace(/_/g, "/");
+  const secretBuf = Buffer.from(normalized, "base64");
+  const sig = createHmac("sha256", secretBuf).update(message).digest("base64");
+  return sig.replace(/\+/g, "-").replace(/\//g, "_");
+}
+
+export function buildL2Headers(creds, address, method, path, body) {
+  const timestamp = Math.floor(Date.now() / 1000).toString();
+  const signature = buildHmacSignature(creds.secret, timestamp, method, path, body);
+  return {
+    POLY_ADDRESS: address,
+    POLY_SIGNATURE: signature,
+    POLY_TIMESTAMP: timestamp,
+    POLY_API_KEY: creds.key,
+    POLY_PASSPHRASE: creds.passphrase,
+    "content-type": "application/json",
+  };
+}
+
+/**
+ * Build V2 order message + domain (no sign).
+ */
+export function buildOrderV2Message(params = {}) {
+  const {
+    tokenId,
+    side,
+    price,
+    size,
+    maker,
+    signer,
+    negRisk = false,
+    tickSize = "0.01",
+    orderType = "GTC",
+    signatureType = 0,
+    metadata = BYTES32_ZERO,
+    builder = BYTES32_ZERO,
+  } = params;
+
+  if (!tokenId) throw new Error("tokenId required");
+  if (side !== "BUY" && side !== "SELL") throw new Error("side must be BUY or SELL");
+  if (!maker || !signer) throw new Error("maker and signer required");
+  const px = Number(price);
+  const sz = Number(size);
+  if (!(px > 0 && px < 1)) throw new Error(`price out of (0,1): ${price}`);
+  if (!(sz > 0)) throw new Error(`size must be > 0: ${size}`);
+  if (![0, 3].includes(Number(signatureType))) {
+    throw new Error(`Desk poly supports signatureType 0 (EOA) or 3 (deposit wallet), got ${signatureType}`);
+  }
+
+  const roundConfig = ROUNDING_CONFIG[String(tickSize)] || ROUNDING_CONFIG["0.01"];
+  const { rawMakerAmt, rawTakerAmt } = getOrderRawAmounts(side, sz, px, roundConfig);
+  const makerAmount = toRawAmountStr(rawMakerAmt);
+  const takerAmount = toRawAmountStr(rawTakerAmt);
+  const salt = String(randomInt(1, 2 ** 31 - 1));
+  const timestamp = Date.now().toString();
+  const sideInt = side === "BUY" ? 0 : 1;
+  const exchange = negRisk ? NEG_RISK_CTF_EXCHANGE_V2 : CTF_EXCHANGE_V2;
+
+  const orderMessage = {
+    salt,
+    maker,
+    signer,
+    tokenId: String(tokenId),
+    makerAmount,
+    takerAmount,
+    side: sideInt,
+    signatureType: Number(signatureType),
+    timestamp,
+    metadata,
+    builder,
+  };
+
+  const domain = { ...EIP712_DOMAIN_V2, verifyingContract: exchange };
+  const notionalUsdc = side === "BUY" ? rawMakerAmt : rawTakerAmt;
+
+  return {
+    domain,
+    types: ORDER_TYPES_V2,
+    value: orderMessage,
+    orderType,
+    side,
+    notionalUsdc,
+    exchange,
+  };
+}
+
+/** ERC-7739-wrapped POLY_1271 signature for deposit wallets (sigType=3). */
+export async function signOrderV2_1271(wallet, orderMessage, exchangeAddress) {
+  const ORDER_TYPE_STRING =
+    "Order(uint256 salt,address maker,address signer,uint256 tokenId," +
+    "uint256 makerAmount,uint256 takerAmount,uint8 side,uint8 signatureType," +
+    "uint256 timestamp,bytes32 metadata,bytes32 builder)";
+  const ORDER_TYPE_HASH = keccak256(toUtf8Bytes(ORDER_TYPE_STRING));
+  const DOMAIN_TYPE_HASH = keccak256(
+    toUtf8Bytes("EIP712Domain(string name,string version,uint256 chainId,address verifyingContract)")
+  );
+  const NAME_HASH = keccak256(toUtf8Bytes(EIP712_DOMAIN_V2.name));
+  const VERSION_HASH = keccak256(toUtf8Bytes(EIP712_DOMAIN_V2.version));
+
+  const appDomainSep = keccak256(
+    AbiCoder.defaultAbiCoder().encode(
+      ["bytes32", "bytes32", "bytes32", "uint256", "address"],
+      [DOMAIN_TYPE_HASH, NAME_HASH, VERSION_HASH, BigInt(POLY_CHAIN_ID), exchangeAddress]
+    )
+  );
+
+  const contentsHash = keccak256(
+    AbiCoder.defaultAbiCoder().encode(
+      [
+        "bytes32",
+        "uint256",
+        "address",
+        "address",
+        "uint256",
+        "uint256",
+        "uint256",
+        "uint8",
+        "uint8",
+        "uint256",
+        "bytes32",
+        "bytes32",
+      ],
+      [
+        ORDER_TYPE_HASH,
+        BigInt(orderMessage.salt),
+        orderMessage.maker,
+        orderMessage.signer,
+        BigInt(orderMessage.tokenId),
+        BigInt(orderMessage.makerAmount),
+        BigInt(orderMessage.takerAmount),
+        orderMessage.side,
+        orderMessage.signatureType,
+        BigInt(orderMessage.timestamp),
+        orderMessage.metadata,
+        orderMessage.builder,
+      ]
+    )
+  );
+
+  const innerSig = await wallet.signTypedData(
+    { ...EIP712_DOMAIN_V2, verifyingContract: exchangeAddress },
+    {
+      TypedDataSign: [
+        { name: "contents", type: "Order" },
+        { name: "name", type: "string" },
+        { name: "version", type: "string" },
+        { name: "chainId", type: "uint256" },
+        { name: "verifyingContract", type: "address" },
+        { name: "salt", type: "bytes32" },
+      ],
+      Order: ORDER_TYPES_V2.Order,
+    },
+    {
+      contents: orderMessage,
+      name: "DepositWallet",
+      version: "1",
+      chainId: POLY_CHAIN_ID,
+      verifyingContract: orderMessage.maker, // deposit wallet (ERC-1271)
+      salt: BYTES32_ZERO,
+    }
+  );
+
+  const orderTypeHex = hexlify(toUtf8Bytes(ORDER_TYPE_STRING));
+  const lenHex = "0x" + (186).toString(16).padStart(4, "0");
+  return concat([innerSig, appDomainSep, contentsHash, orderTypeHex, lenHex]);
+}
+
+/**
+ * Build + sign V2 order.
+ * mode:
+ *   - eoa (0): maker=funder or wallet
+ *   - deposit (3): maker=signer=deriveDepositWallet(eoa)  [default auto for desk agent]
+ */
+export async function buildSignedOrderV2(wallet, params = {}) {
+  const eoa = wallet.address;
+  let signatureType = params.signatureType;
+  let funder = params.funderAddress || eoa;
+
+  // Auto deposit-wallet flow when requested or when env forces it
+  const preferDeposit =
+    params.useDepositWallet === true ||
+    process.env.MAD_POLY_USE_DEPOSIT_WALLET === "1" ||
+    signatureType === 3;
+
+  if (preferDeposit || signatureType === undefined) {
+    // default path for accounts that reject EOA maker: try deposit wallet
+    if (preferDeposit || process.env.MAD_POLY_USE_DEPOSIT_WALLET !== "0") {
+      const dw = deriveDepositWallet(eoa);
+      // if caller didn't force eoa-only, use deposit when useDepositWallet or auto
+      if (preferDeposit || params.autoDeposit !== false) {
+        // keep eoa as default unless deposit forced — placeLimitOrder sets useDepositWallet on retry
+      }
+    }
+  }
+
+  if (params.useDepositWallet || signatureType === 3) {
+    funder = deriveDepositWallet(eoa);
+    signatureType = 3;
+  } else {
+    signatureType = signatureType ?? 0;
+  }
+
+  // sigType 3: maker = deposit wallet; signer = EOA (must match API key address)
+  // (CLOB: "order signer address has to be the address of the API KEY")
+  const orderSigner = eoa;
+  const built = buildOrderV2Message({
+    ...params,
+    maker: funder,
+    signer: orderSigner,
+    signatureType,
+  });
+
+  const signature =
+    signatureType === 3
+      ? await signOrderV2_1271(wallet, built.value, built.exchange)
+      : await wallet.signTypedData(built.domain, built.types, built.value);
+
+  return {
+    order: {
+      salt: parseInt(built.value.salt, 10),
+      maker: built.value.maker,
+      signer: built.value.signer,
+      tokenId: built.value.tokenId,
+      makerAmount: built.value.makerAmount,
+      takerAmount: built.value.takerAmount,
+      side: built.side,
+      signatureType: built.value.signatureType,
+      timestamp: built.value.timestamp,
+      metadata: built.value.metadata,
+      builder: built.value.builder,
+      expiration: "0",
+      signature,
+    },
+    owner: null,
+    orderType: built.orderType,
+    _meta: {
+      exchange: built.exchange,
+      notionalUsdc: built.notionalUsdc,
+      domain: built.domain,
+      types: built.types,
+      value: built.value,
+      depositWallet: signatureType === 3 ? funder : null,
+      eoa,
+    },
+  };
+}
+
+/**
+ * POST signed order to CLOB. Requires L2 creds.
+ */
+export async function postClobOrder({
+  payload,
+  creds,
+  address,
+  clobRest = POLY_CLOB_REST,
+  fetchImpl = globalThis.fetch,
+} = {}) {
+  if (!creds?.key || !creds?.secret || !creds?.passphrase) {
+    throw new Error("L2 creds required (key/secret/passphrase)");
+  }
+  const body = JSON.stringify(payload);
+  const path = "/order";
+  const headers = buildL2Headers(creds, address, "POST", path, body);
+  const res = await fetchImpl(`${clobRest.replace(/\/$/, "")}${path}`, {
+    method: "POST",
+    headers,
+    body,
+  });
+  const text = await res.text();
+  let data;
+  try {
+    data = JSON.parse(text);
+  } catch {
+    data = { raw: text };
+  }
+  if (!res.ok) {
+    const err = new Error(
+      `CLOB POST /order failed (${res.status}): ${text.slice(0, 300)}`
+    );
+    err.status = res.status;
+    err.body = data;
+    throw err;
+  }
+  return data;
+}
+
+/** Max notional USDC for a single desk order (env MAD_POLY_MAX_NOTIONAL, default 25). */
+export function polyMaxNotional() {
+  const n = Number(process.env.MAD_POLY_MAX_NOTIONAL || "25");
+  return Number.isFinite(n) && n > 0 ? n : 25;
+}
+
+
+/** Prepare-only: unsigned CLOB order envelope for operator to sign locally. */
+export function polyPrepareOrder(args = {}) {
+  const built = buildOrderV2Message(args);
+  return stampPrepared(
+    {
+      provider: "poly-clob",
+      kind: "poly-order",
+      chainId: POLY_CHAIN_ID,
+      tokenId: String(args.tokenId),
+      side: built.side,
+      orderType: built.orderType,
+      notionalUsdc: built.notionalUsdc,
+      exchange: built.exchange,
+      domain: built.domain,
+      types: built.types,
+      value: built.value,
+      tickSize: args.tickSize || "0.01",
+      negRisk: Boolean(args.negRisk),
+      signatureType: Number(args.signatureType ?? 0),
+      // amounts echoed for caps
+      maxNotionalUsdc: args.maxNotionalUsdc ?? null,
+    },
+    { provider: "poly-clob", kind: "poly-order" }
+  );
+}

package/src/data/providers/satflow.mjs

@@ -7,6 +7,7 @@
 
 import { btcAddress } from "./bitcoin-esplora.mjs";
 import { resolveProviderEndpoint, credentialedHeaders } from "../provider-endpoint.mjs";
+import { stampPrepared } from "../../prepare-envelope.mjs";
 
 export const SATFLOW_BASE = "https://api.satflow.com/v1";
 
@@ -294,7 +295,7 @@ export async function satflowPreparePurchase(args = {}, opts = {}) {
     throw new Error(`satflow: purchase price ${settled} sats exceeds maxSats cap ${maxSats} — PSBT withheld`);
   }
 
-  return {
+  return stampPrepared({
     provider: "satflow",
     kind: "purchase-intent",
     executionReady: false,
@@ -314,7 +315,7 @@ export async function satflowPreparePurchase(args = {}, opts = {}) {
       data?.psbt ||
       null,
     note: "Sign PSBT in a Bitcoin wallet. Broadcast only through the user's wallet or an explicitly armed Bitcoin execution plane.",
-  };
+  });
 }
 
 /** List intent — unsigned listing PSBTs */
@@ -324,7 +325,7 @@ export async function satflowPrepareList(args = {}, opts = {}) {
     throw new Error("satflow: list requires inscription_id or runes_output");
   }
   const data = await sfFetch("/intent/sell", { method: "POST", body, opts });
-  return {
+  return stampPrepared({
     provider: "satflow",
     kind: "list-intent",
     requiresUserSignature: true,
@@ -332,5 +333,5 @@ export async function satflowPrepareList(args = {}, opts = {}) {
     intent: data,
     unsignedPsbt: data?.unsignedListingPSBTBase64 || data?.unsigned_psbt || null,
     note: "Sign listing PSBTs in a Bitcoin wallet; listing broadcast is outside the data plane.",
-  };
+  });
 }

package/src/data/providers/solana-rpc.mjs

@@ -23,6 +23,15 @@ function paramsWithCommitment(params, commitment) {
 }
 
 export async function solanaRpc(method, params = [], opts = {}) {
+  const methodName = String(method || "");
+  if (
+    methodName === "sendTransaction" ||
+    methodName === "sendRawTransaction" ||
+    methodName === "simulateBundle" && false ||
+    /^send/i.test(methodName)
+  ) {
+    throw new Error(`solana-rpc: ${methodName} refused — @oracle-agent/oracle is prepare-only (no broadcast)`);
+  }
   const result = await httpJson(rpcUrl(opts), {
     method: "POST",
     body: {

package/src/data/providers/uniswap-v3.mjs

@@ -4,6 +4,7 @@
 import { Interface, getAddress, isAddress } from "ethers";
 import { rpcCall } from "./evm-rpc.mjs";
 import { attachAutoSlippage, bindAutoSlippageGuardToCall } from "../../auto-slippage.mjs";
+import { stampPrepared } from "../../prepare-envelope.mjs";
 
 /** @type {Record<number, { quoter: string, weth: string, usdc: string, name: string }>} */
 export const UNI_V3_CHAINS = {
@@ -246,7 +247,7 @@ export async function uniV3PrepareExactIn(q = {}, opts = {}) {
   const nowSeconds = Number(opts.nowSeconds ?? Math.floor(Date.now() / 1000));
   const deadline = nowSeconds + deadlineWindow;
   const data = ROUTER_IFACE.encodeFunctionData("multicall", [deadline, [exact]]);
-  return {
+  return stampPrepared({
     provider: "uniswap-v3",
     calldataReady: true,
     // NOT executable authority. The bytes are assembled but nothing is signed:
@@ -273,7 +274,7 @@ export async function uniV3PrepareExactIn(q = {}, opts = {}) {
       value: nativeInput ? quote.amountIn : "0",
       slippageGuard: bindAutoSlippageGuardToCall(quote.autoSlippage, { chainId, venue: meta.router, data }),
     },
-  };
+  });
 }
 
 export async function uniV3Health(opts = {}) {

package/src/index.mjs

@@ -7,6 +7,7 @@
 // public package entrypoint, so importing the package cannot hand a caller a
 // signer.
 
+export { stampPrepared, assertPreparedEnvelope, computePrepareHash } from "./prepare-envelope.mjs";
 export { data, dataCall, dataHealth, dataCatalog } from "./data/desk-data.mjs";
 export { registerProvider, getProvider, listProviders } from "./data/catalog.mjs";
 

package/src/onboarding/agent-keys.mjs

@@ -8,6 +8,10 @@ import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { normalizeScopes, EXECUTE_SCOPE, DEFAULT_SCOPES } from "../scopes.mjs";
 
+// API keys are 32+ bytes of CSPRNG output, not user-chosen passwords. SHA-256
+// is the right lookup hash here (same class as GitHub PATs). Slow password
+// KDFs would only add DoS surface on every authenticated request.
+// codeql[js/insufficient-password-hash]
 function hashKey(raw) {
   return createHash("sha256").update(String(raw), "utf8").digest("hex");
 }

package/src/prepare-envelope.mjs

@@ -0,0 +1,108 @@
+// Canonical prepare envelope — stamped by @oracle-agent/oracle prepare helpers,
+// verified by @oracle-agent/operator before any local sign/submit.
+// Keeps agentic UX identical: prepare() → exec(prepared). Blocks handcrafted actions.
+
+import { createHash } from "node:crypto";
+
+export const PREPARE_VERSION = 1;
+/** Default max age for a prepared envelope at sign time (ms). */
+export const PREPARE_MAX_AGE_MS = 5 * 60 * 1000;
+
+function stableStringify(value) {
+  if (value === null || typeof value !== "object") return JSON.stringify(value);
+  if (Array.isArray(value)) return `[${value.map(stableStringify).join(",")}]`;
+  const keys = Object.keys(value).sort();
+  return `{${keys.map((k) => `${JSON.stringify(k)}:${stableStringify(value[k])}`).join(",")}}`;
+}
+
+/** Fields that bind the envelope (must not include the stamp fields themselves). */
+export function prepareBodyForHash(prepared) {
+  const {
+    oraclePrepared,
+    prepareHash,
+    preparedAt,
+    prepareVersion,
+    note,
+    // strip volatile display-only
+    ...body
+  } = prepared || {};
+  return body;
+}
+
+export function computePrepareHash(prepared) {
+  const body = prepareBodyForHash(prepared);
+  return createHash("sha256").update(stableStringify(body)).digest("hex");
+}
+
+/**
+ * Stamp a prepare result. Call at the end of every prepare helper.
+ * @param {object} payload  provider-specific prepare fields (action/tx/psbt/...)
+ */
+export function stampPrepared(payload, { provider, kind } = {}) {
+  if (!payload || typeof payload !== "object") throw new Error("stampPrepared: payload object required");
+  const base = {
+    ...payload,
+    provider: payload.provider || provider,
+    kind: payload.kind || kind,
+    requiresUserSignature: payload.requiresUserSignature !== false,
+    signingReady: false,
+    broadcastReady: false,
+    executionReady: false,
+  };
+  if (!base.provider) throw new Error("stampPrepared: provider required");
+  if (!base.kind) throw new Error("stampPrepared: kind required");
+  const preparedAt = Date.now();
+  const prepareVersion = PREPARE_VERSION;
+  const withMeta = { ...base, preparedAt, prepareVersion };
+  const prepareHash = computePrepareHash(withMeta);
+  return {
+    ...withMeta,
+    oraclePrepared: true,
+    prepareHash,
+  };
+}
+
+/**
+ * Verify a prepared envelope before operator sign.
+ * @throws on mismatch / expiry / missing stamp
+ */
+export function assertPreparedEnvelope(prepared, {
+  maxAgeMs = PREPARE_MAX_AGE_MS,
+  nowMs = Date.now(),
+  providers = null,
+  kinds = null,
+  label = "operator",
+} = {}) {
+  if (!prepared || typeof prepared !== "object") {
+    throw new Error(`${label}: prepared envelope object required`);
+  }
+  if (prepared.oraclePrepared !== true) {
+    throw new Error(
+      `${label}: refused handcrafted action — pass a stamped prepare result from @oracle-agent/oracle (oraclePrepared missing)`
+    );
+  }
+  if (Number(prepared.prepareVersion) !== PREPARE_VERSION) {
+    throw new Error(`${label}: unsupported prepareVersion ${prepared.prepareVersion}`);
+  }
+  const age = nowMs - Number(prepared.preparedAt || 0);
+  if (!Number.isFinite(age) || age < 0 || age > maxAgeMs) {
+    throw new Error(`${label}: prepare envelope expired or clock-skewed (ageMs=${age}, max=${maxAgeMs})`);
+  }
+  const expected = computePrepareHash(prepared);
+  if (String(prepared.prepareHash || "") !== expected) {
+    throw new Error(`${label}: prepareHash mismatch — payload was altered after prepare`);
+  }
+  if (providers) {
+    const allow = new Set(providers);
+    if (!allow.has(prepared.provider)) {
+      throw new Error(`${label}: provider ${prepared.provider} not allowed here`);
+    }
+  }
+  if (kinds) {
+    const allow = new Set(kinds);
+    if (!allow.has(prepared.kind)) {
+      throw new Error(`${label}: kind ${prepared.kind} not allowed here`);
+    }
+  }
+  return true;
+}