gate-evm-tools 1.0.28 → 1.2.0

package/runtime/delivery/pending.ts

@@ -0,0 +1,98 @@
+/** Typed evidence consumer. Durable finalized observation production/query is supplied by the launcher (Task6a). */
+import type { ReleaseExecutionTransaction } from '../workflow/lib/transactionPlanner';
+import { canonicalData, canonicalJson, deepFreeze, digest, exactObject, nonempty } from '../workflow/lib/canonicalData';
+import { assertPendingUupsCurrentState, assertPendingUupsPreparation, planDeployment, sameAddress, type PendingUupsBindingInput, type PendingUupsResolution, type PendingUupsResolverPort } from '../workflow/lib/pendingUupsBinding';
+import { parseDeliveryPlan, type DeliveryPlan } from './plan';
+import { parseDerivedBindings, type DerivedBindings } from './bindings';
+import { parsePreparationJournal, type PreparationEntry } from './journal';
+import { validateNetworkAlias } from './policy';
+export interface PendingEvidenceIdentity {
+  executionId: string; target: string; inputsHash: string; artifactHash: string; planHash: string;
+  selectedStepIds: string[];
+  infrastructure: { scheme: 'evm'; factory: string; multicall: string; placeholderImplementation: string };
+  derivedValues: DerivedBindings;
+}
+export interface ObservationReference { observationId: string; transactionId: string; transactionHash: string }
+export interface PendingUupsEvidence {
+  identity: PendingEvidenceIdentity;
+  candidate: { deploymentId: string; executionId: string; target: string; instanceId: string; contractInfoKey: string; address: string };
+  plan: DeliveryPlan; preparations: PreparationEntry[]; observations: ObservationReference[];
+}
+export interface FinalizedTransactionObservation {
+  observationId: string; executionId: string; target: string; planHash: string;
+  transaction: ReleaseExecutionTransaction; transactionHash: string;
+  receipt: { transactionHash: string; status: 1; blockNumber: string; blockHash: string };
+}
+export interface FinalizedObservationPort {
+  /** Trusted query capability must establish canonical inclusion and configured finality before returning.
+   * This consumer cannot establish finality from caller JSON or a `finalized: true` flag. */
+  readFinalized(observationId: string): Promise<FinalizedTransactionObservation | undefined>;
+}
+function hash32(raw: unknown, label: string): string {
+  if (typeof raw !== 'string' || !/^0x[\da-f]{64}$/.test(raw)) throw new Error(`Invalid ${label}`); return raw;
+}
+function parseIdentity(raw: unknown): PendingEvidenceIdentity {
+  const v = exactObject(raw, ['executionId', 'target', 'inputsHash', 'artifactHash', 'planHash', 'selectedStepIds', 'infrastructure', 'derivedValues'], 'pending evidence identity');
+  nonempty(v.executionId, 'executionId'); validateNetworkAlias(v.target, 'target', false);
+  digest(v.inputsHash, 'inputsHash'); digest(v.artifactHash, 'artifactHash'); digest(v.planHash, 'planHash');
+  if (!Array.isArray(v.selectedStepIds) || !v.selectedStepIds.length || v.selectedStepIds.some(id => typeof id !== 'string' || !id) || new Set(v.selectedStepIds).size !== v.selectedStepIds.length) throw new Error('Invalid selectedStepIds');
+  const infra = exactObject(v.infrastructure, ['scheme', 'factory', 'multicall', 'placeholderImplementation'], 'pending infrastructure');
+  if (infra.scheme !== 'evm') throw new Error('Pending delivery evidence requires EVM');
+  for (const key of ['factory', 'multicall', 'placeholderImplementation']) if (typeof infra[key] !== 'string' || !/^0x[\da-f]{40}$/.test(infra[key] as string)) throw new Error('Invalid pending infrastructure address');
+  const derived = parseDerivedBindings(v.derivedValues);
+  if (derived.executionId !== v.executionId) throw new Error('Pending derived execution identity mismatch');
+  return deepFreeze(v as unknown as PendingEvidenceIdentity);
+}
+export async function validatePendingUupsEvidence(options: {
+  input: PendingUupsBindingInput; identity: PendingEvidenceIdentity; evidence: unknown; finalized: FinalizedObservationPort;
+}): Promise<PendingUupsResolution> {
+  if (!options.finalized || typeof options.finalized.readFinalized !== 'function') throw new Error('Pending reuse requires a trusted finalized observation resolver');
+  const identity = parseIdentity(options.identity), input = options.input;
+  const v = exactObject(options.evidence, ['identity', 'candidate', 'plan', 'preparations', 'observations'], 'pending UUPS evidence');
+  if (canonicalJson(parseIdentity(v.identity)) !== canonicalJson(identity)) throw new Error('Pending evidence identity mismatch');
+  const plan = parseDeliveryPlan(v.plan);
+  if (plan.executionId !== identity.executionId || plan.target !== identity.target || plan.inputsHash !== identity.inputsHash || plan.planHash !== identity.planHash || canonicalJson(plan.derivedBindings) !== canonicalJson(identity.derivedValues)) throw new Error('Pending plan identity mismatch');
+  if (input.network !== identity.target || !identity.selectedStepIds.includes(input.stepId) || input.scheme !== identity.infrastructure.scheme || !sameAddress(input.factory, identity.infrastructure.factory) || !sameAddress(input.multicall, identity.infrastructure.multicall) || !sameAddress(input.placeholderImplementationAddress, identity.infrastructure.placeholderImplementation)) throw new Error('Pending selection/infrastructure identity mismatch');
+  const candidate = exactObject(v.candidate, ['deploymentId', 'executionId', 'target', 'instanceId', 'contractInfoKey', 'address'], 'pending candidate');
+  if (candidate.deploymentId !== input.taskId || candidate.deploymentId !== plan.deploymentId || candidate.executionId !== identity.executionId || candidate.target !== input.network || candidate.instanceId !== input.instanceId || candidate.contractInfoKey !== input.contractInfoKey) throw new Error('Pending candidate identity mismatch');
+  const preparations = parsePreparationJournal(v.preparations, plan.transactions, plan.derivedBindings, { target: plan.target, chainId: plan.chainId, expectedStepIds: plan.deploymentBindings.map(b => b.stepId) });
+  for (const entry of preparations) {
+    const binding = plan.deploymentBindings.find(b => b.stepId === entry.stepId)!;
+    if (binding.preparationHash !== entry.preparationHash || canonicalJson(binding.transactionIds) !== canonicalJson(entry.mappings.map(m => m.transactionId)) || canonicalJson(binding.derivedKeys) !== canonicalJson(entry.derivedKeys)) throw new Error('Pending plan preparation binding mismatch');
+  }
+  const matching = preparations.filter(p => p.stepId === input.stepId);
+  if (matching.length !== 1) throw new Error('Pending evidence requires exactly one matching preparation');
+  const entry = matching[0], { request, plan: gatePlan } = entry.prepared;
+  assertPendingUupsPreparation(input, entry.change, request, gatePlan);
+  const proxy = planDeployment(gatePlan, 'proxy'), implementation = planDeployment(gatePlan, 'implementation');
+  if (!sameAddress(candidate.address, proxy.address)) throw new Error('Pending candidate address mismatch');
+  if (!Array.isArray(v.observations) || v.observations.length !== plan.transactions.length || !v.observations.length) throw new Error('Pending receipt completeness mismatch');
+  const seen = new Set<string>(), observationIds: string[] = [];
+  for (const [index, raw] of v.observations.entries()) {
+    const ref = exactObject(raw, ['observationId', 'transactionId', 'transactionHash'], 'observation reference');
+    const observationId = nonempty(ref.observationId, 'observationId'), tx = plan.transactions[index];
+    if (seen.has(observationId) || ref.transactionId !== tx.transactionId) throw new Error('Duplicate or unordered pending receipt mapping');
+    seen.add(observationId); observationIds.push(observationId); hash32(ref.transactionHash, 'reference transaction hash');
+    const observed = await options.finalized.readFinalized(observationId);
+    if (!observed) throw new Error('Finalized observation is unavailable');
+    const o = exactObject(observed, ['observationId', 'executionId', 'target', 'planHash', 'transaction', 'transactionHash', 'receipt'], 'finalized observation');
+    const receipt = exactObject(o.receipt, ['transactionHash', 'status', 'blockNumber', 'blockHash'], 'finalized receipt');
+    if (o.observationId !== observationId || o.executionId !== identity.executionId || o.target !== identity.target || o.planHash !== identity.planHash || o.transactionHash !== ref.transactionHash || canonicalJson(o.transaction) !== canonicalJson(tx) || receipt.transactionHash !== o.transactionHash || receipt.status !== 1) throw new Error('Finalized receipt/transaction/plan identity mismatch');
+    hash32(o.transactionHash, 'observed transaction hash'); hash32(receipt.blockHash, 'receipt block hash');
+    if (typeof receipt.blockNumber !== 'string' || !/^(0|[1-9][0-9]*)$/.test(receipt.blockNumber)) throw new Error('Invalid finalized block number');
+  }
+  await assertPendingUupsCurrentState(input, proxy.address, implementation.address);
+  return deepFreeze({ implementationAddress: implementation.address, implementationSalt: implementation.salt, proxyAddress: proxy.address, artifactDigest: gatePlan.artifact.digest,
+    binding: { executionId: identity.executionId, target: identity.target, planHash: identity.planHash, artifactDigest: gatePlan.artifact.digest, observationIds } });
+}
+export function pendingUupsResolver(input: {
+  identity: PendingEvidenceIdentity;
+  resolveEvidence(query: PendingUupsBindingInput): Promise<unknown | undefined>;
+  finalized: FinalizedObservationPort;
+}): PendingUupsResolverPort {
+  const identity = parseIdentity(canonicalData(input.identity));
+  return { resolve: async query => {
+    const evidence = await input.resolveEvidence(query);
+    return evidence === undefined ? undefined : validatePendingUupsEvidence({ input: query, identity, evidence, finalized: input.finalized });
+  } };
+}

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;
+}