gate-evm-tools 1.0.28 → 1.0.31

package/runtime/delivery/plan.ts

@@ -0,0 +1,337 @@
+/** Pure internal canonical plan. This does not establish release readiness or verify project files. */
+import {
+  normalizeTransactions,
+  type ReleaseExecutionTransaction,
+} from "../workflow/lib/transactionPlanner";
+import {
+  canonicalJson,
+  deepFreeze,
+  digest,
+  exactObject,
+  nonempty,
+  semanticHash,
+} from "../workflow/lib/canonicalData";
+import {
+  bindDeliveryTransactions,
+  parseOperationBindings,
+  type OperationBinding,
+  type TransactionBinding,
+} from "./identities";
+import {
+  parseCustomInputClosure,
+  type CustomInputClosure,
+} from "./closure-format";
+import { parseCustomEvidence, type CustomEvidence } from "./custom-format";
+import { validateNetworkAlias } from "./policy";
+import { parseDerivedBindings, type DerivedBindings } from "./bindings";
+export interface DeliveryPlanHeader {
+  version: 1;
+  schema: "gate-delivery-plan";
+  deploymentId: string;
+  environment: "dev" | "prod";
+  target: string;
+  chainId: string;
+  executionId: string;
+  operator: string;
+  sourceDefinitionHash: string;
+  inputsHash: string;
+  runtimeIdentity: { version: string; digest: string };
+}
+export interface DeploymentBinding {
+  stepId: string;
+  preparationHash: string;
+  transactionIds: string[];
+  derivedKeys: string[];
+}
+export interface VerificationBinding {
+  stepId: string;
+  assertionIds: string[];
+  verificationHash: string;
+}
+export interface DeliveryPlanBody extends DeliveryPlanHeader {
+  /** Total execution order: each entry follows every preceding entry, including external routes. */
+  transactions: ReleaseExecutionTransaction[];
+  deploymentBindings: DeploymentBinding[];
+  verificationBindings: VerificationBinding[];
+  derivedBindings: DerivedBindings;
+  operationBindings: OperationBinding[];
+  customBindings: CustomEvidence[];
+  customInputClosure: CustomInputClosure | null;
+  transactionBindings: TransactionBinding[];
+}
+export interface DeliveryPlan extends DeliveryPlanBody {
+  planHash: string;
+}
+const headerKeys = [
+  "version",
+  "schema",
+  "deploymentId",
+  "environment",
+  "target",
+  "chainId",
+  "executionId",
+  "operator",
+  "sourceDefinitionHash",
+  "inputsHash",
+  "runtimeIdentity",
+];
+const bodyKeys = [
+  ...headerKeys,
+  "transactions",
+  "deploymentBindings",
+  "verificationBindings",
+  "derivedBindings",
+  "operationBindings",
+  "customBindings",
+  "customInputClosure",
+  "transactionBindings",
+];
+export function parseDeliveryPlanHeader(raw: unknown): DeliveryPlanHeader {
+  const value = exactObject(raw, headerKeys, "delivery plan header");
+  if (value.version !== 1 || value.schema !== "gate-delivery-plan")
+    throw new Error("Unsupported delivery plan schema/version");
+  if (value.environment !== "dev" && value.environment !== "prod")
+    throw new Error("delivery environment must be dev or prod");
+  validateNetworkAlias(value.target, "target", false);
+  if (
+    typeof value.chainId !== "string" ||
+    !/^[1-9][0-9]*$/.test(value.chainId) ||
+    BigInt(value.chainId) >= 2n ** 256n
+  )
+    throw new Error("chainId must be a positive uint256 decimal string");
+  if (
+    typeof value.operator !== "string" ||
+    !/^0x[\da-fA-F]{40}$/.test(value.operator) ||
+    /^0x0{40}$/.test(value.operator)
+  )
+    throw new Error("Invalid operator");
+  const runtime = exactObject(
+    value.runtimeIdentity,
+    ["version", "digest"],
+    "runtimeIdentity"
+  );
+  return deepFreeze({
+    version: 1,
+    schema: "gate-delivery-plan",
+    deploymentId: nonempty(value.deploymentId, "deploymentId"),
+    environment: value.environment,
+    target: value.target as string,
+    chainId: value.chainId,
+    executionId: nonempty(value.executionId, "executionId"),
+    operator: value.operator.toLowerCase(),
+    sourceDefinitionHash: digest(
+      value.sourceDefinitionHash,
+      "sourceDefinitionHash"
+    ),
+    inputsHash: digest(value.inputsHash, "inputsHash"),
+    runtimeIdentity: {
+      version: nonempty(runtime.version, "runtime version"),
+      digest: digest(runtime.digest, "runtime"),
+    },
+  });
+}
+function strings(raw: unknown, label: string): string[] {
+  if (!Array.isArray(raw)) throw new Error(`${label} must be an array`);
+  const list = raw.map((v) => nonempty(v, label));
+  if (new Set(list).size !== list.length)
+    throw new Error(`${label} contains duplicates`);
+  return list;
+}
+function normalizeBody(raw: unknown): DeliveryPlanBody {
+  const value = exactObject(raw, bodyKeys, "delivery plan");
+  const header = parseDeliveryPlanHeader(
+    Object.fromEntries(headerKeys.map((k) => [k, value[k]]))
+  );
+  const transactions = normalizeTransactions(
+    value.transactions,
+    header.operator
+  );
+  if (
+    transactions.some(
+      (tx) => tx.scheme !== undefined || tx.factoryDeps !== undefined
+    )
+  )
+    throw new Error("Delivery plans support explicit EVM transactions only");
+  if (transactions.some((tx) => BigInt(tx.value) >= 2n ** 256n))
+    throw new Error("transaction value exceeds uint256");
+  const operationBindings = parseOperationBindings(value.operationBindings);
+  if (!Array.isArray(value.customBindings))
+    throw new Error("custom bindings must be an array");
+  const customBindings = value.customBindings.map(parseCustomEvidence);
+  const customInputClosure =
+    value.customInputClosure === null
+      ? null
+      : parseCustomInputClosure(value.customInputClosure);
+  if (!!customBindings.length !== !!customInputClosure)
+    throw new Error("Missing or unrelated custom input closure");
+  if (customInputClosure) {
+    for (const binding of customBindings) {
+      for (const key of ["roots", "edges", "packages"] as const) {
+        const union = new Set(
+          customInputClosure[key].map((item) => canonicalJson(item))
+        );
+        if (
+          binding.closure[key].some((item) => !union.has(canonicalJson(item)))
+        )
+          throw new Error("Custom closure union mismatch");
+      }
+      for (const file of binding.closure.files) {
+        if (
+          !customInputClosure.files.some(
+            (candidate) =>
+              candidate.path === file.path &&
+              candidate.digest === file.digest &&
+              (file.emittedDigest === null ||
+                candidate.emittedDigest === file.emittedDigest)
+          )
+        )
+          throw new Error("Custom closure file union mismatch");
+      }
+      if (
+        canonicalJson(binding.closure.compiler) !==
+          canonicalJson(customInputClosure.compiler) ||
+        canonicalJson(binding.closure.hostAdapter) !==
+          canonicalJson(customInputClosure.hostAdapter) ||
+        canonicalJson(binding.closure.resolver) !==
+          canonicalJson(customInputClosure.resolver)
+      )
+        throw new Error("Custom closure compiler mismatch");
+    }
+  }
+  if (
+    new Set(customBindings.map((b) => b.sourceStepId)).size !==
+    customBindings.length
+  )
+    throw new Error("duplicate custom binding");
+  for (const custom of customBindings) {
+    const operations = operationBindings.filter(
+      (b) => b.sourceStepId === custom.sourceStepId
+    );
+    if (
+      canonicalJson(operations.map((b) => [b.operationId, b.kind])) !==
+      canonicalJson(custom.operations.map((o) => [o.id, o.kind]))
+    )
+      throw new Error("custom operation order/identity mismatch");
+  }
+  if (
+    operationBindings.some(
+      (b) =>
+        b.operationId !== null &&
+        !customBindings.some((c) => c.sourceStepId === b.sourceStepId)
+    )
+  )
+    throw new Error("Missing custom evidence");
+  const transactionBindings = bindDeliveryTransactions(
+    transactions,
+    operationBindings
+  );
+  if (
+    canonicalJson(value.transactionBindings) !==
+    canonicalJson(transactionBindings)
+  )
+    throw new Error("Delivery transaction reverse mapping mismatch");
+  const derivedBindings = parseDerivedBindings(value.derivedBindings);
+  if (derivedBindings.executionId !== header.executionId)
+    throw new Error("derived bindings execution identity mismatch");
+  if (
+    !Array.isArray(value.deploymentBindings) ||
+    !Array.isArray(value.verificationBindings)
+  )
+    throw new Error("plan bindings must be arrays");
+  const used = new Set<string>();
+  const deploymentBindings = value.deploymentBindings.map((raw) => {
+    const b = exactObject(
+      raw,
+      ["stepId", "preparationHash", "transactionIds", "derivedKeys"],
+      "deployment binding"
+    );
+    const stepId = nonempty(b.stepId, "stepId"),
+      transactionIds = strings(b.transactionIds, "transactionIds"),
+      derivedKeys = strings(b.derivedKeys, "derivedKeys");
+    for (const id of transactionIds) {
+      if (
+        used.has(id) ||
+        !transactions.some(
+          (tx) =>
+            tx.transactionId === id &&
+            (tx.stepId === stepId || tx.stepId === `${stepId}-implementation`)
+        )
+      )
+        throw new Error("deployment binding transaction mismatch");
+      used.add(id);
+    }
+    if (derivedKeys.some((k) => !Object.hasOwn(derivedBindings.values, k)))
+      throw new Error("deployment binding derived key mismatch");
+    return {
+      stepId,
+      preparationHash: digest(b.preparationHash, "preparation"),
+      transactionIds,
+      derivedKeys,
+    };
+  });
+  if (
+    new Set(deploymentBindings.map((b) => b.stepId)).size !==
+    deploymentBindings.length
+  )
+    throw new Error("duplicate deployment binding");
+  const assertions = new Set<string>();
+  const verificationBindings = value.verificationBindings.map((raw) => {
+    const b = exactObject(
+      raw,
+      ["stepId", "assertionIds", "verificationHash"],
+      "verification binding"
+    );
+    const assertionIds = strings(b.assertionIds, "assertionIds");
+    for (const id of assertionIds) {
+      if (assertions.has(id)) throw new Error("duplicate assertionId");
+      assertions.add(id);
+    }
+    return {
+      stepId: nonempty(b.stepId, "stepId"),
+      assertionIds,
+      verificationHash: digest(b.verificationHash, "verification"),
+    };
+  });
+  if (
+    new Set(verificationBindings.map((b) => b.stepId)).size !==
+    verificationBindings.length
+  )
+    throw new Error("duplicate verification binding");
+  return {
+    ...header,
+    transactions,
+    deploymentBindings,
+    verificationBindings,
+    derivedBindings,
+    operationBindings,
+    customBindings,
+    customInputClosure,
+    transactionBindings,
+  };
+}
+export function sealDeliveryPlan(raw: unknown): DeliveryPlan {
+  const body = normalizeBody(raw);
+  return deepFreeze({ ...body, planHash: semanticHash(body) });
+}
+export function parseDeliveryPlan(
+  raw: unknown,
+  expectedIdentity?: DeliveryPlanHeader
+): DeliveryPlan {
+  const value = exactObject(raw, [...bodyKeys, "planHash"], "delivery plan");
+  const { planHash, ...body } = value;
+  const plan = sealDeliveryPlan(body);
+  if (digest(planHash, "planHash") !== plan.planHash)
+    throw new Error("delivery plan hash mismatch");
+  if (
+    expectedIdentity &&
+    canonicalJson(
+      parseDeliveryPlanHeader(
+        Object.fromEntries(
+          headerKeys.map((k) => [k, plan[k as keyof DeliveryPlan]])
+        )
+      )
+    ) !== canonicalJson(parseDeliveryPlanHeader(expectedIdentity))
+  )
+    throw new Error("delivery plan identity mismatch");
+  return plan;
+}