@oracle-agent/oracle 0.1.0

package/src/public-control/aa-adapter.mjs

@@ -0,0 +1,402 @@
+// Oracle Control — ERC-4337 session-key on-chain adapter (Slice E).
+//
+// Wires the provider-neutral session grant produced by session-key-model.mjs
+// to a real account-abstraction encoding stack (viem) so a grant can be
+// turned into:
+//   1. install calldata  — enable a scoped session key on the owner's smart
+//      account (encodeSessionKeyInstall)
+//   2. an unsigned ERC-4337 UserOperation envelope that carries that calldata
+//      (buildUserOperation)
+//   3. revoke calldata   — disable a session key on the smart account
+//      (revokeSessionKey)
+//
+// Hard boundaries (same posture as session-key-model.mjs / policy-schema.mjs):
+//   - No wallet/AA SDK holds or requests the owner's main key here. This
+//     module only ASSEMBLES UNSIGNED data. Signing is the user's wallet,
+//     off-infrastructure — never this adapter, never a server, never a log.
+//   - No live RPC/bundler calls. Any chain read this adapter needs (the
+//     account's current ERC-4337 nonce) goes through a caller-injected
+//     `client` object (duck-typed to viem's PublicClient.readContract shape)
+//     so tests can supply a fully offline mock and production code can pass
+//     a real viem PublicClient without this file changing.
+//   - Import ONLY from ./session-key-model.mjs (grant shape/lifecycle) and
+//     ./policy-schema.mjs (not currently needed here, left available) plus
+//     viem and node builtins. NEVER from the private executor stack
+//     (get-signer.mjs, keystore.mjs, exec-policy.mjs, local-signer/*,
+//     adapters/*, mint-capability.mjs) — this module must never be wired to
+//     private operator wallet.
+//   - Fail-closed: a grant that is not ACTIVE (per session-key-model's own
+//     sessionStatus — expired, revoked, or malformed) is refused BEFORE any
+//     calldata is computed. A tampered "grant-shaped" object whose id does
+//     not match its own fields is refused for the same reason.
+//
+// Session-key module ABI note: real deployed session-key modules differ
+// per AA stack (Safe allowance/session module, Kernel/ZeroDev session
+// validator, Biconomy Nexus session module, a bespoke
+// permissionless/viem session account). This adapter defines the ERC-4337
+// envelope and a documented, generic "install/revoke a scoped session key"
+// function interface (DEFAULT_SESSION_MODULE_ABI) that mirrors the common
+// shape those modules expose. Wiring to one specific deployed module is a
+// matter of passing that module's real `abi`/`moduleAddress` via opts — the
+// grant validation, determinism, and unsigned-userOp assembly below do not
+// change. This file never invents a contract address: `moduleAddress` is a
+// required caller-supplied parameter, not a hardcoded guess.
+
+import {
+  encodeFunctionData,
+  keccak256,
+  stringToHex,
+  numberToHex,
+  isAddress,
+  isHex,
+  getAddress,
+} from "viem";
+
+import {
+  canonicalJson,
+  computeSessionId,
+  sessionStatus,
+  SESSION_STATUS,
+} from "./session-key-model.mjs";
+
+/** Canonical ERC-4337 EntryPoint v0.7 address (public, chain-agnostic
+ *  constant — not private infrastructure). Callers may override
+ *  via opts.entryPoint for a different EntryPoint version/deployment. */
+export const ENTRYPOINT_V07 = "0x0000000071727De22E5E9d8BAf0edAc6f37da032";
+
+/** Minimal EntryPoint ABI slice this adapter needs (nonce read only — this
+ *  adapter never calls the EntryPoint's mutating methods). */
+export const ENTRYPOINT_ABI = [
+  {
+    type: "function",
+    name: "getNonce",
+    stateMutability: "view",
+    inputs: [
+      { name: "sender", type: "address" },
+      { name: "key", type: "uint192" },
+    ],
+    outputs: [{ name: "nonce", type: "uint256" }],
+  },
+];
+
+/**
+ * Generic "session-key module" interface most ERC-4337 session-key
+ * validators expose in one shape or another. This is the DEFAULT abi used
+ * when the caller does not supply a provider-specific one via opts.abi — see
+ * the module-level doc comment above for why the exact selector is left
+ * swappable rather than hardcoded per provider.
+ */
+export const DEFAULT_SESSION_MODULE_ABI = [
+  {
+    type: "function",
+    name: "installSessionKey",
+    stateMutability: "nonpayable",
+    inputs: [
+      { name: "sessionId", type: "bytes32" },
+      { name: "agent", type: "address" },
+      { name: "validAfter", type: "uint48" },
+      { name: "validUntil", type: "uint48" },
+      { name: "actionsHash", type: "bytes32" },
+      { name: "targets", type: "address[]" },
+      { name: "maxValueWei", type: "uint256" },
+      { name: "maxGasWei", type: "uint256" },
+    ],
+    outputs: [],
+  },
+  {
+    type: "function",
+    name: "revokeSessionKey",
+    stateMutability: "nonpayable",
+    inputs: [{ name: "sessionId", type: "bytes32" }],
+    outputs: [],
+  },
+];
+
+function fail(message) {
+  throw new Error(`aa-adapter: ${message}`);
+}
+
+function requireModuleAddress(moduleAddress) {
+  if (typeof moduleAddress !== "string" || !isAddress(moduleAddress)) {
+    fail(
+      "opts.moduleAddress is required and must be a valid 0x address of the " +
+        "deployed session-key module on the owner's smart account (this " +
+        "adapter never guesses/hardcodes a contract address)"
+    );
+  }
+  return getAddress(moduleAddress);
+}
+
+/** Re-derive a grant's identity fields (everything except `id`) and confirm
+ *  they hash to the grant's own `id`, defending against a hand-crafted
+ *  "grant-shaped" object that never went through createSessionGrant(). */
+function assertGrantIntegrity(grant) {
+  if (!grant || grant.mode !== "oracle-session-grant") {
+    fail("input is not a valid session-key-model grant (missing/wrong mode)");
+  }
+  const { id, ...identity } = grant;
+  const recomputed = computeSessionId(identity);
+  if (recomputed !== id) {
+    fail("grant integrity check failed: id does not match grant fields (tampered or hand-built object)");
+  }
+}
+
+/** Refuse to touch out-of-policy grants (expired/revoked/invalid) before any
+ *  calldata is computed. `opts` is forwarded to session-key-model's
+ *  sessionStatus() (nowMs, revocation registry/Set/array). */
+function assertGrantEncodable(grant, opts = {}) {
+  assertGrantIntegrity(grant);
+  const status = sessionStatus(grant, opts);
+  if (status !== SESSION_STATUS.ACTIVE) {
+    fail(`refusing to encode calldata for a ${status} session (${grant.id})`);
+  }
+}
+
+function msToSecondsUint48(ms, label) {
+  const seconds = Math.floor(Number(ms) / 1000);
+  if (!Number.isFinite(seconds) || seconds < 0 || seconds > 0xffffffffffff) {
+    fail(`${label} does not fit a uint48 seconds timestamp`);
+  }
+  return BigInt(seconds);
+}
+
+/**
+ * Deterministic install calldata for enabling a session-key-model grant as a
+ * scoped session key on the owner's ERC-4337 smart account.
+ *
+ * Refuses (throws, no calldata returned) when the grant is not ACTIVE —
+ * expired, revoked, or fails its own integrity check — per assertGrantEncodable.
+ *
+ * @param {object} grant  output of session-key-model.createSessionGrant()
+ * @param {object} opts
+ * @param {string} opts.moduleAddress  REQUIRED — deployed session-key module address
+ * @param {Array}  [opts.abi]          override for DEFAULT_SESSION_MODULE_ABI
+ * @param {number} [opts.nowMs]        forwarded to sessionStatus() for the active check
+ * @param {object|Set|string[]} [opts.revocation]  forwarded to sessionStatus()
+ * @returns {{ to: string, data: `0x${string}`, value: string }}
+ */
+export function encodeSessionKeyInstall(grant, opts = {}) {
+  assertGrantEncodable(grant, opts);
+  const moduleAddress = requireModuleAddress(opts.moduleAddress);
+  const abi = opts.abi ?? DEFAULT_SESSION_MODULE_ABI;
+
+  const agent = getAddress(grant.agent);
+  const targets = grant.targets.map((t) => getAddress(t));
+  const validAfter = msToSecondsUint48(grant.issuedAtMs, "issuedAtMs");
+  const validUntil = msToSecondsUint48(grant.expiresAtMs, "expiresAtMs");
+  // actionsHash: keccak256 over the canonical (already-sorted, deduped) JSON
+  // of the granted action ids — same convention session-key-model.mjs uses
+  // for computeSessionId, so it hashes identically everywhere.
+  const actionsHash = keccak256(stringToHex(canonicalJson(grant.actions)));
+  const maxValueWei = BigInt(grant.maxValueWei);
+  // grant.maxGasWei may be null (no independent gas cap set at the
+  // session-key-model layer); encoded as 0. The deployed module's own
+  // convention decides how 0 is interpreted (commonly "not independently
+  // capped here" — see docs/public-self-custody-aa-adapter.md).
+  const maxGasWei = grant.maxGasWei == null ? 0n : BigInt(grant.maxGasWei);
+
+  const data = encodeFunctionData({
+    abi,
+    functionName: "installSessionKey",
+    args: [grant.id, agent, validAfter, validUntil, actionsHash, targets, maxValueWei, maxGasWei],
+  });
+
+  return { to: moduleAddress, data, value: "0x0" };
+}
+
+/**
+ * Deterministic revoke calldata for disabling a session key on the owner's
+ * smart account. Accepts either a full grant object (its `.id` is used) or
+ * a raw session id string. Unlike install, revoke is allowed even for a
+ * grant that is already expired/revoked (revocation is idempotent per
+ * session-key-model's own createRevocationRegistry) — the only hard refusal
+ * here is a malformed session id.
+ *
+ * @param {object|string} grantOrSessionId
+ * @param {object} opts
+ * @param {string} opts.moduleAddress  REQUIRED — deployed session-key module address
+ * @param {Array}  [opts.abi]          override for DEFAULT_SESSION_MODULE_ABI
+ * @returns {{ to: string, data: `0x${string}`, value: string }}
+ */
+export function revokeSessionKey(grantOrSessionId, opts = {}) {
+  let sessionId;
+  if (typeof grantOrSessionId === "string") {
+    sessionId = grantOrSessionId;
+  } else if (grantOrSessionId && grantOrSessionId.mode === "oracle-session-grant") {
+    assertGrantIntegrity(grantOrSessionId);
+    sessionId = grantOrSessionId.id;
+  } else {
+    fail("revokeSessionKey requires a session-key-model grant object or a raw session id string");
+  }
+  if (!isHex(sessionId) || sessionId.length !== 66) {
+    fail("session id must be a 0x-prefixed 32-byte hash (as produced by computeSessionId)");
+  }
+
+  const moduleAddress = requireModuleAddress(opts.moduleAddress);
+  const abi = opts.abi ?? DEFAULT_SESSION_MODULE_ABI;
+
+  const data = encodeFunctionData({
+    abi,
+    functionName: "revokeSessionKey",
+    args: [sessionId],
+  });
+
+  return { to: moduleAddress, data, value: "0x0" };
+}
+
+const REQUIRED_GAS_FIELDS = [
+  "callGasLimit",
+  "verificationGasLimit",
+  "preVerificationGas",
+  "maxFeePerGas",
+  "maxPriorityFeePerGas",
+];
+
+function toBigIntField(value, label) {
+  if (value == null) fail(`${label} is required`);
+  let n;
+  try {
+    n = typeof value === "bigint" ? value : BigInt(value);
+  } catch {
+    fail(`${label} must be an integer, bigint, or 0x-hex string`);
+  }
+  if (n < 0n) fail(`${label} must not be negative`);
+  return n;
+}
+
+/**
+ * Assemble an UNSIGNED ERC-4337 v0.7 UserOperation envelope carrying the
+ * given callData (typically the output of encodeSessionKeyInstall /
+ * revokeSessionKey, but this function accepts any calldata — it does not
+ * re-check grant policy itself).
+ *
+ * This function never estimates gas and never fabricates fee data: every
+ * gas/fee field is a required, explicit caller input. The only chain read it
+ * performs is the ERC-4337 account nonce, and ONLY when `nonce` is not
+ * supplied directly — in that case it calls `client.readContract(...)`,
+ * duck-typed to viem's PublicClient shape, so:
+ *   - production code passes a real viem PublicClient and gets a real nonce
+ *   - tests pass a plain object with an async readContract() mock and NO
+ *     network call ever happens
+ *
+ * The returned object always has signature: "0x" (empty) and carries no key
+ * material of any kind — signing happens in the user's own wallet, off this
+ * adapter.
+ *
+ * @param {object} params
+ * @param {object} [params.client]  duck-typed viem PublicClient (readContract) — only used if nonce is omitted
+ * @param {string} [params.entryPoint]  defaults to ENTRYPOINT_V07
+ * @param {string} params.sender  smart account address
+ * @param {string} params.callData  0x-prefixed calldata to execute
+ * @param {string|number|bigint} [params.nonce]  explicit nonce override (skips client read)
+ * @param {string|number|bigint} [params.nonceKey]  EntryPoint nonce key (default 0)
+ * @param {string} [params.factory]  smart-account factory address (counterfactual deploy)
+ * @param {string} [params.factoryData]  factory calldata (required if factory is set)
+ * @param {string|number|bigint} params.callGasLimit
+ * @param {string|number|bigint} params.verificationGasLimit
+ * @param {string|number|bigint} params.preVerificationGas
+ * @param {string|number|bigint} params.maxFeePerGas
+ * @param {string|number|bigint} params.maxPriorityFeePerGas
+ * @param {string} [params.paymaster]
+ * @param {string|number|bigint} [params.paymasterVerificationGasLimit]  required if paymaster is set
+ * @param {string|number|bigint} [params.paymasterPostOpGasLimit]  required if paymaster is set
+ * @param {string} [params.paymasterData]  defaults to "0x"
+ */
+export async function buildUserOperation(params = {}) {
+  const {
+    client,
+    entryPoint = ENTRYPOINT_V07,
+    sender,
+    callData,
+    nonce,
+    nonceKey = 0n,
+    factory,
+    factoryData,
+    paymaster,
+    paymasterVerificationGasLimit,
+    paymasterPostOpGasLimit,
+    paymasterData = "0x",
+  } = params;
+
+  if (typeof sender !== "string" || !isAddress(sender)) fail("params.sender must be a valid 0x address");
+  if (typeof callData !== "string" || !isHex(callData)) fail("params.callData must be 0x-prefixed hex");
+  if (typeof entryPoint !== "string" || !isAddress(entryPoint)) fail("params.entryPoint must be a valid 0x address");
+
+  const normalizedSender = getAddress(sender);
+  const normalizedEntryPoint = getAddress(entryPoint);
+
+  for (const field of REQUIRED_GAS_FIELDS) {
+    if (params[field] == null) fail(`params.${field} is required (this adapter does not estimate gas)`);
+  }
+  const callGasLimit = toBigIntField(params.callGasLimit, "callGasLimit");
+  const verificationGasLimit = toBigIntField(params.verificationGasLimit, "verificationGasLimit");
+  const preVerificationGas = toBigIntField(params.preVerificationGas, "preVerificationGas");
+  const maxFeePerGas = toBigIntField(params.maxFeePerGas, "maxFeePerGas");
+  const maxPriorityFeePerGas = toBigIntField(params.maxPriorityFeePerGas, "maxPriorityFeePerGas");
+
+  if ((factory == null) !== (factoryData == null)) {
+    fail("factory and factoryData must both be set (counterfactual deploy) or both omitted");
+  }
+  if (factory != null && (typeof factory !== "string" || !isAddress(factory))) {
+    fail("params.factory must be a valid 0x address");
+  }
+  if (factoryData != null && (typeof factoryData !== "string" || !isHex(factoryData))) {
+    fail("params.factoryData must be 0x-prefixed hex");
+  }
+
+  const hasPaymaster = paymaster != null;
+  if (hasPaymaster) {
+    if (typeof paymaster !== "string" || !isAddress(paymaster)) fail("params.paymaster must be a valid 0x address");
+    if (paymasterVerificationGasLimit == null || paymasterPostOpGasLimit == null) {
+      fail("paymasterVerificationGasLimit and paymasterPostOpGasLimit are required when paymaster is set");
+    }
+  }
+  if (paymasterData != null && (typeof paymasterData !== "string" || !isHex(paymasterData))) {
+    fail("params.paymasterData must be 0x-prefixed hex");
+  }
+
+  let resolvedNonce;
+  if (nonce != null) {
+    resolvedNonce = toBigIntField(nonce, "nonce");
+  } else {
+    if (!client || typeof client.readContract !== "function") {
+      fail(
+        "params.nonce was omitted and no usable client was provided — pass an explicit nonce or a " +
+          "client with an async readContract({address, abi, functionName, args}) method (a real viem " +
+          "PublicClient in production, a mock in tests; this adapter makes no network call itself)"
+      );
+    }
+    const key = toBigIntField(nonceKey, "nonceKey");
+    resolvedNonce = await client.readContract({
+      address: normalizedEntryPoint,
+      abi: ENTRYPOINT_ABI,
+      functionName: "getNonce",
+      args: [normalizedSender, key],
+    });
+    resolvedNonce = toBigIntField(resolvedNonce, "resolved nonce");
+  }
+
+  const userOp = {
+    sender: normalizedSender,
+    nonce: numberToHex(resolvedNonce),
+    factory: factory != null ? getAddress(factory) : null,
+    factoryData: factoryData ?? null,
+    callData,
+    callGasLimit: numberToHex(callGasLimit),
+    verificationGasLimit: numberToHex(verificationGasLimit),
+    preVerificationGas: numberToHex(preVerificationGas),
+    maxFeePerGas: numberToHex(maxFeePerGas),
+    maxPriorityFeePerGas: numberToHex(maxPriorityFeePerGas),
+    paymaster: hasPaymaster ? getAddress(paymaster) : null,
+    paymasterVerificationGasLimit: hasPaymaster ? numberToHex(toBigIntField(paymasterVerificationGasLimit, "paymasterVerificationGasLimit")) : null,
+    paymasterPostOpGasLimit: hasPaymaster ? numberToHex(toBigIntField(paymasterPostOpGasLimit, "paymasterPostOpGasLimit")) : null,
+    paymasterData: hasPaymaster ? paymasterData : null,
+    // Always empty: this adapter assembles UNSIGNED user operations only.
+    // No signature is computed, requested, or accepted here.
+    signature: "0x",
+  };
+
+  return Object.freeze(userOp);
+}
+
+export const _internal = { requireModuleAddress, assertGrantIntegrity, assertGrantEncodable, msToSecondsUint48 };

package/src/public-control/build-registry.mjs

@@ -0,0 +1,227 @@
+// Oracle BUILD registry — the deploy verb, bounded.
+//
+// Oracle's scope model was built for TRADING: read, watch, prepare:trade,
+// prepare:mint, agent:execute. Every one of those moves value through contracts
+// that ALREADY EXIST. "Build on Stable" is a different verb: it brings a new
+// contract into existence.
+//
+// The danger of a deploy verb is that "deploy" normally means "run arbitrary
+// bytecode", which no policy can meaningfully allowlist — a compromised agent
+// just ships whatever it wants. So this module does NOT implement that.
+//
+// What it implements: deploy-through-a-pinned-factory. Oracle may call ONE
+// allowlisted function on ONE allowlisted factory address per chain. The shape
+// of what gets created, and its economics, live in that factory's audited code,
+// not in anything the agent chooses. Bounded by construction.
+//
+// Hard rules enforced here:
+//   1. No raw bytecode. A request carrying `bytecode`/`initCode`/`data` is
+//      rejected outright — that is the arbitrary-deploy path and it stays shut.
+//   2. Factory must be explicitly allowlisted for that exact chainId.
+//   3. Unknown chain -> reject. Unknown factory -> reject. Fail closed.
+//   4. Building is a PROPOSAL by default. Executing needs a separate scope AND
+//      a separate global arm flag, mirroring how execute is gated today.
+
+import { deployGloballyEnabled } from "../flags.mjs";
+
+const ADDR_RE = /^0x[0-9a-fA-F]{40}$/;
+
+/** Fields that would smuggle arbitrary-deploy authority through a build request. */
+const FORBIDDEN_FIELDS = ["bytecode", "initCode", "init_code", "data", "creationCode", "salt"];
+
+/**
+ * Allowlisted build targets, per chain.
+ *
+ * `address: null` means "capability known, target not yet pinned" — Oracle
+ * understands how to build this thing but physically cannot until an operator
+ * supplies a verified factory address. Stable's TokenFactory is deliberately
+ * null: the contracts exist and are audited, but nothing is deployed to 988
+ * mainnet yet, so there is no address to trust.
+ */
+export const BUILD_REGISTRY = {
+  988: {
+    chainName: "Stable Mainnet",
+    factories: {
+      "stable.tokenFactory": {
+        address: envAddress("ORACLE_STABLE_TOKEN_FACTORY"),
+        // The ONLY function Oracle may call on it.
+        method: "createLaunch",
+        creates: ["token", "curve", "feeSplitter"],
+        // Economics are fixed in the audited contract, NOT chosen by the agent.
+        fixed: {
+          creatorFeeBps: 7000,
+          protocolFeeBps: 3000,
+          curveFeeBps: 100,
+          graduationReserveBps: 2000,
+          maxReflectionBps: 3000,
+        },
+        description:
+          "Create a bonding-curve token launch. Fee split, curve params, and " +
+          "graduation ratio are hardcoded in the audited factory.",
+      },
+    },
+  },
+};
+
+function envAddress(name) {
+  const v = String(process.env[name] || "").trim();
+  return ADDR_RE.test(v) ? v : null;
+}
+
+/** Every build target Oracle knows about, including unpinned ones. */
+export function listBuildTargets() {
+  const out = [];
+  for (const [chainId, entry] of Object.entries(BUILD_REGISTRY)) {
+    for (const [key, f] of Object.entries(entry.factories)) {
+      out.push({
+        chainId: Number(chainId),
+        chainName: entry.chainName,
+        target: key,
+        method: f.method,
+        creates: f.creates,
+        fixed: f.fixed,
+        description: f.description,
+        address: f.address,
+        // A target with no pinned address cannot be built, by design.
+        available: Boolean(f.address),
+      });
+    }
+  }
+  return out;
+}
+
+/**
+ * Validate a build request. Returns a normalized plan or throws.
+ * Never touches the network. Never signs. Never broadcasts.
+ */
+export function validateBuildRequest(input = {}) {
+  if (!input || typeof input !== "object" || Array.isArray(input)) {
+    throw new Error("build request must be an object");
+  }
+
+  // 1. Arbitrary-deploy attempt -> hard reject before anything else.
+  for (const f of FORBIDDEN_FIELDS) {
+    if (f in input) {
+      throw new Error(
+        `arbitrary deploy is not supported: remove "${f}". ` +
+          "Oracle builds only through allowlisted factories.",
+      );
+    }
+  }
+
+  const chainId = Number(input.chainId);
+  if (!Number.isInteger(chainId)) throw new Error("chainId required");
+
+  const chain = BUILD_REGISTRY[chainId];
+  if (!chain) throw new Error(`chain ${chainId} has no build targets (fail closed)`);
+
+  const targetKey = String(input.target || "").trim();
+  if (!targetKey) throw new Error("target required");
+
+  const factory = chain.factories[targetKey];
+  if (!factory) {
+    throw new Error(
+      `unknown build target "${targetKey}" on chain ${chainId} (fail closed)`,
+    );
+  }
+
+  if (!factory.address) {
+    throw new Error(
+      `build target "${targetKey}" has no pinned factory address on chain ${chainId}. ` +
+        "An operator must supply a verified address before Oracle can build here.",
+    );
+  }
+
+  // 2. Args are validated against the factory's own rules, not free-form.
+  const args = validateLaunchArgs(input.args || {}, factory);
+
+  return {
+    chainId,
+    chainName: chain.chainName,
+    target: targetKey,
+    factory: factory.address,
+    method: factory.method,
+    creates: factory.creates,
+    fixed: factory.fixed,
+    args,
+  };
+}
+
+/** Argument rules for the stable.tokenFactory createLaunch shape. */
+function validateLaunchArgs(args, factory) {
+  const name = String(args.name || "").trim();
+  const symbol = String(args.symbol || "").trim();
+  const creator = String(args.creator || "").trim();
+  const imageURI = String(args.imageURI || "").trim();
+  const socialsURI = String(args.socialsURI || "").trim();
+  const reflectionBps = Number(args.reflectionBps ?? 0);
+
+  if (!name || name.length > 64) throw new Error("args.name required (1-64 chars)");
+  if (!symbol || symbol.length > 16) throw new Error("args.symbol required (1-16 chars)");
+  if (!ADDR_RE.test(creator)) throw new Error("args.creator must be a valid address");
+  if (imageURI.length > 512 || socialsURI.length > 512) throw new Error("args URI too long");
+
+  const maxRefl = factory.fixed?.maxReflectionBps ?? 0;
+  if (!Number.isInteger(reflectionBps) || reflectionBps < 0 || reflectionBps > maxRefl) {
+    throw new Error(`args.reflectionBps must be an integer 0-${maxRefl}`);
+  }
+
+  return { name, symbol, imageURI, socialsURI, creator, reflectionBps };
+}
+
+/**
+ * Turn a validated request into a PROPOSAL. This is what `prepare:build`
+ * produces: a fully-described, human-readable statement of what would be
+ * created. It carries no authority and cannot be executed.
+ */
+export function buildProposal(input) {
+  const plan = validateBuildRequest(input);
+  return {
+    kind: "build.proposal",
+    executable: false,
+    chainId: plan.chainId,
+    chainName: plan.chainName,
+    target: plan.target,
+    factory: plan.factory,
+    method: plan.method,
+    creates: plan.creates,
+    args: plan.args,
+    fixedEconomics: plan.fixed,
+    summary: renderBuildProposal(plan),
+  };
+}
+
+/** Plain-English render so a user sees exactly what they authorize. */
+export function renderBuildProposal(plan) {
+  const f = plan.fixed || {};
+  const lines = [
+    `Create "${plan.args.name}" ($${plan.args.symbol}) on ${plan.chainName}.`,
+    `Factory: ${plan.factory} (${plan.method})`,
+    `Creates: ${plan.creates.join(", ")}`,
+    `Creator: ${plan.args.creator}`,
+  ];
+  if (plan.args.reflectionBps > 0) {
+    lines.push(`Reflections: ${(plan.args.reflectionBps / 100).toFixed(2)}% of trade fees to holders`);
+  }
+  lines.push(
+    `Fixed by the audited factory (agent cannot change): ` +
+      `creator ${(f.creatorFeeBps || 0) / 100}% / protocol ${(f.protocolFeeBps || 0) / 100}% of fees, ` +
+      `${(f.curveFeeBps || 0) / 100}% trade fee, ` +
+      `${(f.graduationReserveBps || 0) / 100}% of supply to LP at graduation.`,
+  );
+  lines.push("No arbitrary code is deployed. Only this factory call.");
+  return lines.join("\n");
+}
+
+/**
+ * Whether an actual build broadcast is permitted right now.
+ * Requires BOTH the explicit scope AND the global arm flag — same
+ * belt-and-braces posture as execute.
+ */
+export function buildExecutionAllowed(scopes = []) {
+  const hasScope = Array.isArray(scopes) && scopes.includes(BUILD_EXECUTE_SCOPE);
+  return { allowed: hasScope && deployGloballyEnabled(), hasScope, armed: deployGloballyEnabled() };
+}
+
+export const BUILD_PREPARE_SCOPE = "prepare:build";
+export const BUILD_EXECUTE_SCOPE = "build:factory";