@oracle-agent/oracle 0.11.0 → 0.13.0

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

@@ -1,402 +0,0 @@
-// 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

@@ -1,227 +0,0 @@
-// 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";