gate-evm-tools 1.0.28 → 1.0.31

package/runtime/delivery/data.ts

@@ -0,0 +1,94 @@
+/** Delivery's own-data JSON boundary. Numbers are safe integers only; ABI integers may be decimal strings. */
+export function strictData<T = unknown>(raw: T, label = "delivery data"): T {
+  return copyOwnData(raw, label);
+}
+/** Internal partial-value boundary: the only non-JSON value permitted is the caller's sentinel. */
+export function copyOwnData<T>(raw: T, label: string, sentinel?: symbol): T {
+  const active = new Set<object>();
+  const visit = (value: unknown, path: string): unknown => {
+    if (sentinel !== undefined && value === sentinel) return value;
+    if (
+      value === null ||
+      typeof value === "string" ||
+      typeof value === "boolean"
+    )
+      return value;
+    if (typeof value === "number" && Number.isSafeInteger(value)) return value;
+    if (!value || typeof value !== "object")
+      throw new Error(
+        `${path} requires JSON own data (safe integer numbers only)`,
+      );
+    if (active.has(value)) throw new Error(`${path} contains a cycle`);
+    if (Object.getOwnPropertySymbols(value).length)
+      throw new Error(`${path} contains symbol fields`);
+    if (
+      !(
+        Array.isArray(value) ? [Array.prototype] : [Object.prototype, null]
+      ).includes(Object.getPrototypeOf(value))
+    )
+      throw new Error(`${path} requires plain own data`);
+    active.add(value);
+    const result: Record<string, unknown> | unknown[] = Array.isArray(value)
+      ? []
+      : {};
+    const keys = Object.getOwnPropertyNames(value);
+    if (
+      Array.isArray(value) &&
+      (keys.length !== value.length + 1 ||
+        keys.some(
+          (k) =>
+            k !== "length" &&
+            (!/^(0|[1-9][0-9]*)$/.test(k) || Number(k) >= value.length),
+        ))
+    )
+      throw new Error(`${path} contains sparse or extra array data`);
+    for (const key of keys.sort()) {
+      if (Array.isArray(value) && key === "length") continue;
+      const d = Object.getOwnPropertyDescriptor(value, key)!;
+      if (!d.enumerable || !("value" in d))
+        throw new Error(`${path}.${key} requires own enumerable data`);
+      Object.defineProperty(result, key, {
+        value: visit(d.value, `${path}.${key}`),
+        enumerable: true,
+        writable: true,
+        configurable: true,
+      });
+    }
+    active.delete(value);
+    return result;
+  };
+  return visit(raw, label) as T;
+}
+export function ownPath(
+  value: unknown,
+  parts: readonly string[],
+  label = "reference",
+): unknown {
+  let current = value;
+  for (const part of parts) {
+    if (!current || typeof current !== "object")
+      throw new Error(`${label} not found`);
+    if (
+      !(
+        Array.isArray(current) ? [Array.prototype] : [Object.prototype, null]
+      ).includes(Object.getPrototypeOf(current))
+    )
+      throw new Error(`${label} requires plain own data`);
+    const d = Object.getOwnPropertyDescriptor(current, part);
+    if (!d || !d.enumerable || !("value" in d) || d.value === undefined)
+      throw new Error(`${label} requires existing own data`);
+    current = d.value;
+  }
+  return current;
+}
+export const pointerPart = (key: string): string =>
+  key.replace(/~/g, "~0").replace(/\//g, "~1");
+export function pointerParts(path: string): string[] {
+  if (path === "") return [];
+  if (!path.startsWith("/") || /~(?![01])/.test(path))
+    throw new Error("Invalid JSON pointer");
+  return path
+    .slice(1)
+    .split("/")
+    .map((p) => p.replace(/~1/g, "/").replace(/~0/g, "~"));
+}

package/runtime/delivery/development.ts

@@ -0,0 +1,262 @@
+/** Tool-side development lifecycle. Production host authorization and Safe execution are separate milestones. */
+import fs from 'node:fs';
+import path from 'node:path';
+import {createRequire} from 'node:module';
+import ts from 'typescript';
+import {existingCodeCoverage,requiredExistingAddresses} from './existing-code';
+import {yieldCompilerIo} from './compiler-io';
+import {openDeliveryConfiguration} from './configuration';
+import {getCreate2Address} from 'ethers';
+import {artifactIdentity,BytecodeChecker,prepareEvmManifestCandidate,mergeEvmManifestCandidate,parseTargetManifest,hashStorageLayout,resolveTargetManifestPaths} from 'gate-evm-tools/workflow';
+import {canonicalData,canonicalJson,deepFreeze,semanticHash} from '../workflow/lib/canonicalData';
+import {typedValue,parseTypedValue} from '../workflow/lib/typedValue';
+import type {VerificationObservation,TypedValue} from '../workflow/lib/evidencePorts';
+import type {WorkflowStep} from '../workflow/lib/parameters';
+import type {WorkflowHre} from '../workflow/lib/context';
+import {WorkflowState} from '../workflow/lib/state';
+import {validateContractInfo,resolveDeployment,type ContractInfo} from '../workflow/lib/deployments';
+import {validateDeploymentInfo,type DeploymentInfo} from '../workflow/lib/deploymentInfo';
+import type {DeploymentChange} from '../workflow/lib/deploymentRecords';
+import {runDeliverySteps} from './engine';
+import {VerificationJournal,parseVerificationObservation} from './verification';
+import {parseDeliveryPlan} from './plan';
+import {DeliveryOperationIdentities} from './identities';
+import {parsePreparationJournal,type PreparationEntry} from './journal';
+import type {DeliveryCollection} from './planning';
+import type {DeliveryAggregate,DeliveryAggregateOptions} from './aggregate';
+import {openAggregateSources} from './aggregate-inputs';
+import {loadDeliveryPublicTarget} from './config';
+import {inputDigest,readInputBytes} from './input-files';
+import {createDeliveryEoaExecution,type EoaExecutionOptions,type EoaHashReferences} from './eoa';
+import {byteHash,fileBytes,readDevelopmentJournal,atomicDevelopmentWrite,withDevelopmentFileLock,commitDevelopmentFilesLocked,type DevelopmentFile} from './materialization';
+import {runDevelopmentCheckCode,validateDevelopmentCheckReport,type ExpectedDevelopmentCode} from './check-code';
+const same=(a:unknown,b:unknown,label:string)=>{if(canonicalJson(a)!==canonicalJson(b))throw Error(`${label} mismatch`);};
+const json=(v:unknown)=>canonicalJson(v)+'\n';
+function value(raw:TypedValue):any {const v=parseTypedValue(raw);switch(v.type){case 'bigint':return BigInt(v.value as string).toString();case 'number':return Number(v.value);case 'array':return v.value.map(value);case 'object':return Object.fromEntries(Object.entries(v.value).map(([k,x])=>[k,value(x)]));default:return v.value;}}
+function operations(plan:DeliveryCollection['plan'],steps:readonly WorkflowStep[]):WorkflowStep[] {
+ if(new Set(steps.map(s=>s.id)).size!==steps.length)throw Error('Duplicate frozen source');
+ same(steps.filter(s=>s.kind==='custom').map(s=>s.id),plan.customBindings.map(c=>c.sourceStepId),'Frozen custom source coverage');
+ const ids=new DeliveryOperationIdentities(),result:WorkflowStep[]=[];
+ for(const source of steps){
+  const descriptors=source.kind==='custom'?plan.customBindings.find(c=>c.sourceStepId===source.id)!.operations:[source];
+  for(const operation of descriptors){
+   const stepId=ids.register(source.id,source.kind==='custom'?operation.id:null,operation.kind);
+   result.push({...operation,id:stepId});
+  }
+ }
+ same(ids.seal(),plan.operationBindings,'Frozen operation coverage');return result;
+}
+export function expectedDevelopmentAssertions(collection:Pick<DeliveryCollection,'plan'|'verification'>,steps:readonly WorkflowStep[]):VerificationObservation[] {
+ const plan=parseDeliveryPlan(collection.plan),observations=collection.verification.map(parseVerificationObservation);
+ if(!observations.length||!plan.verificationBindings.length)throw Error('Development acceptance requires nonempty business assertions');
+ const checks=operations(plan,steps).filter(s=>s.kind==='check');
+ if(checks.length!==plan.verificationBindings.length)throw Error('Incomplete frozen business assertion set');
+ const expected:VerificationObservation[]=[];
+ for(const [i,step] of checks.entries()){
+  const binding=plan.verificationBindings[i],calls=step.calls as any[];
+  if(binding.stepId!==step.id||!Array.isArray(calls)||!calls.length)throw Error('Business assertion step identity mismatch');
+  const rows=observations.filter(o=>o.stepId===step.id);
+  same(binding.assertionIds,calls.map((_,index)=>`${step.id}:${index}`),'Expected assertion IDs');same(rows.map(o=>o.assertionId),binding.assertionIds,'Complete assertions');same(semanticHash(rows),binding.verificationHash,'Frozen verification hash');
+  for(const [index,observation] of rows.entries()){
+   const call=calls[index];same(observation.definition,{method:call.method,args:typedValue(call.args??[]),expect:typedValue(call.expect)},'Frozen assertion definition');
+   if(observation.contract!==step.contract||observation.abiName!==(step.abi??step.contract))throw Error('Business assertion ABI identity mismatch');expected.push(observation);
+  }
+ }
+ same(expected,observations,'Ordered assertion set');return deepFreeze(expected);
+}
+/** Pure candidate merge; preparations must come from the sealed journal parser. */
+export function mergeDevelopmentRegistration(input:{
+ registry:unknown;metadata:unknown;base:{registry:ContractInfo;metadata:DeploymentInfo};
+ target:string;deploymentId:string;executionId:string;recordPath:string;updatedAt:string;
+ changes:readonly (DeploymentChange&{address:string;proxyKind?:'uups'})[];preparations:readonly PreparationEntry[];
+}):{registry:ContractInfo;metadata:DeploymentInfo} {
+ const {base,target}=input,registry=validateContractInfo(input.registry),metadata=validateDeploymentInfo(input.metadata);
+ registry[target]??={};metadata.networks[target]??={};
+ for(const c of input.changes){
+  same(resolveDeployment(registry,target,c.instanceId)??null,resolveDeployment(base.registry,target,c.instanceId)??null,'Same-instance registry base');
+  same(metadata.networks[target][c.instanceId]??null,base.metadata.networks[target]?.[c.instanceId]??null,'Same-instance metadata base');
+  const previous=resolveDeployment(registry,target,c.instanceId);
+  if(previous&&previous.key!==c.contractInfoKey){
+   const entry=input.preparations.find(p=>p.stepId===c.stepId),request=entry?.prepared.request;
+   if(c.kind!=='upgrade'||c.proxyKind!=='uups'||entry?.change.kind!=='upgrade'||request?.kind!=='uups-upgrade'||entry.prepared.plan.kind!=='uups-upgrade'
+    ||entry.change.instanceId!==c.instanceId||entry.change.contractInfoKey!==c.contractInfoKey||entry.change.actualContract!==c.actualContract
+    ||previous.address.toLowerCase()!==request.proxy.toLowerCase()||previous.address.toLowerCase()!==c.address.toLowerCase()||c.proxyAddress?.toLowerCase()!==request.proxy.toLowerCase())throw Error('Contract candidate key conflict');
+   delete registry[target][previous.key];
+  }
+  if(previous&&previous.address.toLowerCase()!==c.address.toLowerCase()&&c.previousAddress?.toLowerCase()!==previous.address.toLowerCase())throw Error('Contract candidate address conflict');
+  registry[target][c.contractInfoKey]=c.address;
+  metadata.networks[target][c.instanceId]={contractInfoKey:c.contractInfoKey,address:c.address,actualContract:c.actualContract,...(c.proxyKind?{proxyKind:c.proxyKind,implementationAddress:c.implementationAddress}:{}),source:{kind:'deployment',deploymentId:input.deploymentId,executionId:input.executionId,recordPath:input.recordPath},updatedAt:input.updatedAt};
+ }
+ return {registry:validateContractInfo(registry),metadata:validateDeploymentInfo(metadata)};
+}
+export interface DevelopmentDeliveryOptions {
+ root:string;source:DeliveryAggregateOptions;aggregate:DeliveryAggregate;target:string;hre:WorkflowHre;
+ execution:Omit<EoaExecutionOptions,'plan'|'provider'>;
+ /** Optional durable file progress notification. Throwing leaves a recoverable file-only intent. */
+ onFileCommitted?:(path:string)=>void;
+}
+/** Persist the returned aggregate separately to resume; never rerun producers/scripts for sends. */
+export async function createDevelopmentDelivery(options:DevelopmentDeliveryOptions) {
+ const root=fs.realpathSync(options.root),aggregate=deepFreeze(canonicalData(options.aggregate) as unknown as DeliveryAggregate),source=deepFreeze(canonicalData(options.source) as unknown as DeliveryAggregateOptions);
+ const collection=aggregate.collections.find(c=>c.plan.target===options.target);if(!collection)throw Error('Missing selected aggregate collection');
+ const plan=parseDeliveryPlan(collection.plan),target=aggregate.inputs.business.targets.find(t=>t.id===plan.target);
+ if(plan.environment!=='dev'||!target||target.environment!=='dev'||source.selection!=='development'||source.targets.length!==1||source.targets[0].executionId!==plan.executionId||source.targets[0].request.network!==plan.target)throw Error('Development source/target identity mismatch');
+ if(fs.realpathSync(path.resolve(source.workspaceRoot,source.projectRoot))!==root)throw Error('Development project root mismatch');
+ const expected=expectedDevelopmentAssertions(collection,aggregate.inputs.business.steps);
+ const preparations=parsePreparationJournal(collection.preparations,plan.transactions,plan.derivedBindings,{target:plan.target,chainId:plan.chainId,expectedStepIds:plan.deploymentBindings.map(b=>b.stepId)});
+ same(preparations.map(p=>({stepId:p.stepId,preparationHash:p.preparationHash,transactionIds:p.mappings.map(m=>m.transactionId),derivedKeys:p.derivedKeys})),plan.deploymentBindings,'Sealed preparation bindings');
+ if(!plan.transactions.length)throw Error('Development acceptance requires actual transactions');
+ const rows=aggregate.inputs.targets;
+ const computed=semanticHash({version:1,business:aggregate.inputs.business,sourceDefinitions:aggregate.inputs.sourceDefinitions,runtime:aggregate.inputs.runtime,files:aggregate.inputs.files,targets:rows.map(row=>({target:row.target,configuration:row.configuration.configurationRuntimeHash,sourceConfiguration:row.sourceConfiguration.configurationRuntimeHash,compiler:row.compiler.stableDigest,custom:row.custom}))});
+ same(plan.deploymentId,aggregate.inputs.business.deploymentId,'Business deployment identity');same(computed,aggregate.inputsHash,'Aggregate input hash');same(plan.inputsHash,computed,'Plan inputs');same(plan.sourceDefinitionHash,aggregate.sourceDefinitionHash,'Plan source');same(semanticHash(aggregate.inputs.sourceDefinitions),aggregate.sourceDefinitionHash,'Source hash');
+ const hre=options.hre,provider={request:(method:string,params:readonly unknown[])=>hre.network.provider.request({method,params:[...params]})};
+ if(options.execution.context.finality.kind==='confirmations'&&BigInt(options.execution.context.finality.depth)<BigInt(Math.max(1,target.finality.confirmations)))throw Error('Development finality below configured policy');
+ const identity=semanticHash({schema:'gate-delivery-development',version:1,executionId:plan.executionId,planHash:plan.planHash,target:plan.target,inputsHash:computed,sourceDefinitionHash:plan.sourceDefinitionHash,runtimeIdentity:plan.runtimeIdentity,context:options.execution.context});
+ const recordPath=`scripts/tasks/${plan.deploymentId}/results/${plan.target}/${plan.executionId}/deployment.json`,sessionPath=`.gate-delivery/development/${plan.executionId}.json`;
+ async function assertCurrent(){
+  if(createRequire(path.join(root,'package.json'))('hardhat')!==hre)throw Error('Development requires the actual validated project HRE');
+  const observation=openDeliveryConfiguration({workspaceRoot:source.workspaceRoot,projectRoot:source.projectRoot,network:plan.target});
+  try {
+   // Each observation independently validates every extender against the actual
+   // pinned adapter. The source worker additionally installs its context guard;
+   // that startup callback is not a semantic execution configuration difference.
+   const current=observation.seal().configuration;
+   const frozen=JSON.parse(canonicalJson(rows.find(r=>r.target===plan.target)!.sourceConfiguration.configuration));
+   // Remove exactly the optional guard registered in our verified hardhat entry.
+   // Preserve every other callback's identity, count, kind, and execution order.
+   const adapter=fs.readFileSync(path.join(__dirname,'hardhat.js'),'utf8'),ast=ts.createSourceFile('hardhat.js',adapter,ts.ScriptTarget.Latest,true,ts.ScriptKind.JS),guards:string[]=[];
+   const visit=(node:ts.Node):void=>{if(ts.isCallExpression(node)&&node.expression.getText(ast)==='extendEnvironment'&&node.arguments.length===1){const callback=node.arguments[0];if(ts.isArrowFunction(callback)&&callback.getText(ast).includes('Actual HRE network conflict: expected'))guards.push(semanticHash(callback.getText(ast)));}ts.forEachChild(node,visit);};visit(ast);
+   if(guards.length!==1)throw Error('Owned context guard identity unavailable');
+   for(const row of frozen.extenders){const active=current.extenders.find((x:any)=>x.kind===row.kind);if(row.kind==='extendEnvironment'&&active&&row.callbacks.length===active.callbacks.length+1){if(row.callbacks.filter((x:string)=>x===guards[0]).length!==1)throw Error('Unexpected context extender difference');row.callbacks=row.callbacks.filter((x:string)=>x!==guards[0]);}}
+   same(current,frozen,'Actual development runtime configuration');
+  }finally{observation.close();}
+  await yieldCompilerIo();
+  if(path.resolve(hre.config.paths.root)!==root||hre.network.name!==plan.target||(hre.network.config as any).zksync===true)throw Error('Development HRE/root/target mismatch');
+  same(loadDeliveryPublicTarget(root,plan.target,'dev'),target,'Current target');
+  if(String((await hre.ethers.provider.getNetwork()).chainId)!==plan.chainId||BigInt(await provider.request('eth_chainId',[]) as string).toString()!==plan.chainId)throw Error('Development provider chain mismatch');
+  const current=openAggregateSources({workspaceRoot:source.workspaceRoot,projectRoot:source.projectRoot,requests:source.targets.map(t=>t.request)});same(current.definitions,aggregate.inputs.sourceDefinitions,'Current eligible source');
+  for(const file of aggregate.inputs.files)if(inputDigest(readInputBytes(root,file.path))!==file.digest)throw Error(`Current immutable input changed: ${file.path}`);
+  same(JSON.parse(fs.readFileSync(path.join(__dirname,'../runtime-identity.json'),'utf8')),plan.runtimeIdentity,'Current runtime');
+  await yieldCompilerIo();
+ }
+ async function assertArtifacts(){
+  const artifacts=[];
+  for(const prep of preparations){const artifact=await hre.artifacts.readArtifact(prep.prepared.plan.contract);same(artifactIdentity(artifact,'evm'),prep.prepared.plan.artifact,'Actual artifact');artifacts.push(artifactIdentity(artifact,'evm'));}
+  const compiler=rows.find(r=>r.target===plan.target)!.compiler;
+  for(const artifact of compiler.artifacts){if(inputDigest(readInputBytes(root,artifact.path))!==inputDigest(artifact.contents))throw Error('CheckCode compilation artifact drift');}
+  return preparations.length?artifacts:pureCoverage().artifacts;
+ }
+ await assertCurrent();
+ const base=await withDevelopmentFileLock(root,async()=>{
+  const old=fileBytes(root,sessionPath);if(old!==null){const session=JSON.parse(old);if(session.identity!==identity||session.planHash!==plan.planHash||session.recordPath!==recordPath)throw Error('Development session identity conflict');return session;}
+  const paths=resolveTargetManifestPaths(root,plan.target,Number(plan.chainId),{}),manifestPath=path.relative(root,paths.file).split(path.sep).join('/');
+  if(paths.file!==paths.fallbackFile&&fileBytes(root,path.relative(root,paths.fallbackFile))!==null)throw Error('Noncanonical manifest fallback requires explicit migration');
+  const manifestBytes=fileBytes(root,manifestPath),manifests=manifestBytes===null?[]:[{path:manifestPath,contents:manifestBytes}];
+  const session={version:1,manifests,identity,planHash:plan.planHash,recordPath,registry:validateContractInfo(JSON.parse(fileBytes(root,'contractInfo.json')??'{}')),metadata:validateDeploymentInfo(JSON.parse(fileBytes(root,'deploymentInfo.json')??'{"version":1,"networks":{}}'))};
+  atomicDevelopmentWrite(root,sessionPath,json(session));return session;
+ });
+ function pureCoverage(){return existingCodeCoverage({target:plan.target,addresses:requiredExistingAddresses(collection!),registry:base.registry,metadata:base.metadata,compiler:rows.find(r=>r.target===plan.target)!.compiler,manifests:base.manifests??[]});}
+ async function assertExistingCode(){
+  if(preparations.length)return;
+  const coverage=pureCoverage(),checker=new BytecodeChecker(hre,{},'evm');
+  for(const row of coverage.expected){const code=await hre.ethers.provider.getCode(row.address),local=await checker.getLocalBytecode(row.contract);if(code==='0x'||!checker.compareBytecode(code,local.bytecode,local.abi,local.immutableReferences).matches)throw Error('Existing development code mismatch');}
+  for(const m of coverage.manifests){if(byteHash(readInputBytes(root,m.file))!==m.hash)throw Error('Existing UUPS manifest changed');const storage=await provider.request('eth_getStorageAt',[m.proxy,'0x360894a13ba1a3210667c828492db98dca3e2076cc3735a920a3ca505d382bbc','latest']);if(typeof storage!=='string'||storage.slice(-40).toLowerCase()!==m.implementation.slice(2))throw Error('Existing UUPS implementation changed');}
+ }
+ await assertArtifacts();await assertExistingCode();
+ const execution=createDeliveryEoaExecution({...options.execution,plan,provider});
+ async function verifyBusiness(){
+  const journal=new VerificationJournal(expected.map(o=>({stepId:o.stepId,callIndex:o.callIndex,assertionId:o.assertionId})));
+  const checks=plan.verificationBindings.map(binding=>{const checks=expected.filter(o=>o.stepId===binding.stepId),first=checks[0];return {id:binding.stepId,kind:'check',contract:first.contract,abi:first.abiName,address:first.address,calls:checks.map(o=>({method:o.method,args:value(o.args),expect:value(o.expected)}))};});
+  const context={root,taskId:plan.deploymentId,executionId:plan.executionId,taskDir:path.join(root,aggregate.inputs.business.businessRoot),targetId:plan.target,target:{...target!,openzeppelin:target!.openzeppelin!},targetParams:{},existingDeploymentPolicies:{},config:{},runtime:{hre},mode:'verify' as const,simulation:{},state:new WorkflowState(),externalCalls:[],operatorReceipts:[],reporter:{event(){},result(){}},verification:journal};
+  await runDeliverySteps(context,checks);
+  const actual=journal.seal();
+  for(const [i,o] of actual.entries()){
+   const frozen=expected[i];same({...o,definition:frozen.definition,actual:frozen.actual},{...frozen},'Actual business observation identity');
+   // Shared ABI comparison already checked typed actual vs expected, without coercing undefined.
+  }
+  if(actual.length!==expected.length)throw Error('Incomplete actual business observations');return actual.map((o,i)=>({...o,definition:expected[i].definition}));
+ }
+ async function deploymentState(){
+  const checker=new BytecodeChecker(hre,{},'evm'),changes=new Map<string,any>(),candidates=[];
+  for(const entry of preparations){
+   const p=entry.prepared.plan,r=entry.prepared.request;
+   for(const deployment of p.deployments){
+    if(deployment.initCodeHash&&'factory' in r&&getCreate2Address(r.factory,deployment.salt,deployment.initCodeHash).toLowerCase()!==deployment.address.toLowerCase())throw Error('Prepared CREATE2 address mismatch');
+    const code=await hre.ethers.provider.getCode(deployment.address);if(code==='0x')throw Error('Prepared deployment has no actual code');
+    const name=deployment.role==='proxy'?'@openzeppelin/contracts/proxy/ERC1967/ERC1967Proxy.sol:ERC1967Proxy':p.contract;
+    const local=await checker.getLocalBytecode(name),comparison=checker.compareBytecode(code,local.bytecode,local.abi,local.immutableReferences);if(!comparison.matches)throw Error(`Prepared deployed code mismatch: ${name}`);
+   }
+   const deployed=p.deployments.find(d=>d.role==='proxy')?.address??('proxy' in r?r.proxy:p.deployments.find(d=>d.role==='contract')?.address);
+   if(!deployed)throw Error('Prepared deployment address missing');
+   const change={...entry.change,address:deployed,...(p.proxyKind==='uups'?{proxyAddress:deployed,proxyKind:'uups'}:{})};changes.set(change.instanceId,change);
+  }
+  for(const change of changes.values())if(change.proxyKind==='uups'){
+   const entry=[...preparations].reverse().find(p=>p.change.instanceId===change.instanceId)!;
+   const candidate=await prepareEvmManifestCandidate({root,scheme:'evm',network:plan.target,target:plan.target,proxy:change.address,contract:entry.prepared.plan.contract,constructorArgs:change.constructorArgs??[],skipTxHash:true,hre,compile:false});
+   const expectedImplementation=entry.prepared.plan.deployments.find(d=>d.role==='implementation')?.address??change.implementationAddress;
+   if(!expectedImplementation||candidate.implementation.toLowerCase()!==expectedImplementation.toLowerCase())throw Error('Final UUPS implementation mismatch');
+   same(candidate.artifact,entry.prepared.plan.artifact,'UUPS artifact');change.implementationAddress=candidate.implementation;candidates.push(candidate);
+  }
+  return {changes:[...changes.values()],candidates};
+ }
+ async function materialize(finalized:unknown,assertions:VerificationObservation[]){
+  const state=await deploymentState();await assertArtifacts();await assertExistingCode();
+  const result=await withDevelopmentFileLock(root,async()=>{
+   if(!preparations.length){const coverage=pureCoverage(),currentRegistry=validateContractInfo(JSON.parse(fileBytes(root,'contractInfo.json')??'{}')),currentMetadata=validateDeploymentInfo(JSON.parse(fileBytes(root,'deploymentInfo.json')??'{"version":1,"networks":{}}'));for(const alias of coverage.aliases){same(resolveDeployment(currentRegistry,plan.target,alias)??null,resolveDeployment(base.registry,plan.target,alias)??null,'Existing development registry');same(currentMetadata.networks[plan.target]?.[alias]??null,base.metadata.networks[plan.target]?.[alias]??null,'Existing development metadata');}}
+   const prior=readDevelopmentJournal(root,plan.executionId);
+   if(prior){
+    if(prior.identity!==identity)throw Error('Materialization execution identity conflict');
+    const allowed=[recordPath,'contractInfo.json','deploymentInfo.json',...new Set(state.candidates.map(c=>path.relative(root,c.paths.file).split(path.sep).join('/')))];
+    same(prior.files.map((f:any)=>f.path).sort(),allowed.sort(),'Materialization journal paths');
+    const record=JSON.parse(prior.files.find((f:any)=>f.path===recordPath).after);
+    same({identity:record.identity,executionId:record.executionId,planHash:record.planHash,preparations:record.preparations,finalized:record.finalized,assertions:record.assertions,changes:record.changes},{identity,executionId:plan.executionId,planHash:plan.planHash,preparations,finalized,assertions,changes:state.changes},'Materialization record evidence');
+    const nextRegistry=validateContractInfo(JSON.parse(prior.files.find((f:any)=>f.path==='contractInfo.json').after)),nextMetadata=validateDeploymentInfo(JSON.parse(prior.files.find((f:any)=>f.path==='deploymentInfo.json').after));
+    for(const c of state.changes){same(resolveDeployment(nextRegistry,plan.target,c.instanceId),{key:c.contractInfoKey,address:c.address},'Journal registry');const m=nextMetadata.networks[plan.target]?.[c.instanceId];if(!m||m.address.toLowerCase()!==c.address.toLowerCase()||m.actualContract!==c.actualContract||m.source.kind!=='deployment'||m.source.executionId!==plan.executionId||m.source.recordPath!==recordPath)throw Error('Journal metadata identity mismatch');}
+    return commitDevelopmentFilesLocked({root,executionId:plan.executionId,identity,files:prior.files.map(({path,before,after}:DevelopmentFile)=>({path,before,after}))},options.onFileCommitted);}
+   const registryBefore=fileBytes(root,'contractInfo.json'),metadataBefore=fileBytes(root,'deploymentInfo.json');
+   const {registry,metadata}=mergeDevelopmentRegistration({registry:JSON.parse(registryBefore??'{}'),metadata:JSON.parse(metadataBefore??'{"version":1,"networks":{}}'),base,target:plan.target,deploymentId:plan.deploymentId,executionId:plan.executionId,recordPath,updatedAt:new Date().toISOString(),changes:state.changes,preparations});
+   const files:DevelopmentFile[]=[{path:recordPath,before:fileBytes(root,recordPath),after:json({version:1,identity,taskId:plan.deploymentId,executionId:plan.executionId,network:plan.target,planHash:plan.planHash,inputsHash:plan.inputsHash,sourceDefinitionHash:plan.sourceDefinitionHash,runtimeIdentity:plan.runtimeIdentity,preparations,finalized,assertions,changes:state.changes})}];
+   if(files[0].before!==null)throw Error('Deployment record already exists without journal');
+   files.push({path:'contractInfo.json',before:registryBefore,after:state.changes.length?json(validateContractInfo(registry)):registryBefore??json(registry)},{path:'deploymentInfo.json',before:metadataBefore,after:state.changes.length?json(validateDeploymentInfo(metadata)):metadataBefore??json(metadata)});
+   const manifests=new Map<string,DevelopmentFile>();
+   for(const candidate of state.candidates){const relative=path.relative(root,candidate.paths.file).split(path.sep).join('/');if(candidate.paths.fallbackFile!==candidate.paths.file&&fs.existsSync(candidate.paths.fallbackFile))throw Error('Noncanonical manifest fallback requires explicit migration');
+    const old=manifests.get(relative),before=old?.before??fileBytes(root,relative),document=old?parseTargetManifest(Buffer.from(old.after)):before===null?{manifestVersion:'3.2',impls:{},proxies:[]}:parseTargetManifest(Buffer.from(before));
+    manifests.set(relative,{path:relative,before,after:json(mergeEvmManifestCandidate(document,candidate))});
+   }
+   files.push(...manifests.values());return commitDevelopmentFilesLocked({root,executionId:plan.executionId,identity,files},options.onFileCommitted);
+  });
+  for(const candidate of state.candidates){const manifest=parseTargetManifest(fs.readFileSync(candidate.paths.file)),entry=manifest.impls[candidate.versionKey];if(!entry||![entry.address,...(entry.allAddresses??[])].some(a=>a.toLowerCase()===candidate.implementation)||hashStorageLayout(entry.layout)!==candidate.layoutHash||!manifest.proxies.some(p=>p.address.toLowerCase()===candidate.proxy&&p.kind==='uups'))throw Error('Committed target manifest mismatch');}
+  return {journal:result,changes:state.changes,manifests:!preparations.length?pureCoverage().manifests:state.candidates.map(c=>({file:path.relative(root,c.paths.file),hash:byteHash(fs.readFileSync(c.paths.file)),layoutHash:c.layoutHash,proxy:c.proxy,implementation:c.implementation}))};
+ }
+ return Object.freeze({plan,
+  async continue(input:{unsigned?:unknown;hashReferences?:EoaHashReferences}={}){
+   await assertCurrent();await assertArtifacts();
+   // Reconciliation always precedes signing; a complete durable prefix can only resume file/verification work.
+   let result=await execution.reconcile(input.hashReferences);
+   if(result.status!=='complete'){
+    const active=plan.transactions[result.snapshot.completedCount];
+    if(active&&active.route!=='operator')return {status:'waiting-external-execution',execution:result};
+    if(input.unsigned===undefined)return {status:result.status,execution:result};
+    result=await execution.execute(input.unsigned);return {status:result.status,execution:result};
+   }
+   const assertions=await verifyBusiness(),finalized=result.snapshot.transactions.map(t=>t.observation!);
+   const materialization=await materialize(finalized,assertions);
+   const registry=fileBytes(root,'contractInfo.json')!,metadata=fileBytes(root,'deploymentInfo.json')!,effective:Record<string,Record<string,string>>={[plan.target]:{}},expectedCode:ExpectedDevelopmentCode[]=[];
+   for(const c of materialization.changes){effective[plan.target][c.contractInfoKey]=c.address;const alias=c.contractInfoKey.includes(':')?c.contractInfoKey.split(':')[0]:c.contractInfoKey;expectedCode.push({key:alias,contract:c.actualContract,address:c.implementationAddress??c.address});if(c.proxyKind==='uups')expectedCode.push({key:`${alias}_Proxy`,contract:'ERC1967Proxy',address:c.address});}
+   if(!preparations.length){const coverage=pureCoverage();Object.assign(effective,coverage.effective);expectedCode.push(...coverage.expected);}
+   const acceptancePath=`.gate-delivery/development/${plan.executionId}.acceptance.json`,priorAcceptance=fileBytes(root,acceptancePath);
+   if(priorAcceptance!==null){
+    const saved=JSON.parse(priorAcceptance),code=saved.checkCode;
+    same({identity:saved.identity,executionId:saved.executionId,planHash:saved.planHash,target:saved.target,inputsHash:saved.inputsHash,sourceDefinitionHash:saved.sourceDefinitionHash,runtimeIdentity:saved.runtimeIdentity,finalized:saved.finalized,assertions:saved.assertions,materialization:saved.materialization},{identity,executionId:plan.executionId,planHash:plan.planHash,target:plan.target,inputsHash:plan.inputsHash,sourceDefinitionHash:plan.sourceDefinitionHash,runtimeIdentity:plan.runtimeIdentity,finalized,assertions,materialization:{intentHash:materialization.journal.intentHash,recordPath,manifests:materialization.manifests}},'Saved development acceptance');
+    if(saved.version!==1||saved.status!=='accepted'||code?.version!==1||code.executionId!==plan.executionId||code.planHash!==plan.planHash||code.target!==plan.target||typeof code.rawFile!=='string'||!code.rawFile.startsWith(`.gate-delivery/check-code/${plan.executionId}/`)||code.registryHash!==byteHash(registry)||code.metadataHash!==byteHash(metadata)||code.effectiveHash!==byteHash(json(effective)))throw Error('Saved CheckCode identity mismatch');
+    const raw=fileBytes(root,code.rawFile);if(raw===null||byteHash(raw)!==code.rawHash)throw Error('Saved CheckCode raw bytes mismatch');validateDevelopmentCheckReport(JSON.parse(raw),plan.target,expectedCode);same(code.artifacts,await assertArtifacts(),'Saved CheckCode artifacts');
+    await assertCurrent();await execution.reconcile();return {status:'accepted',acceptance:deepFreeze(saved)};
+   }
+   const code=await runDevelopmentCheckCode({root,target:plan.target,executionId:plan.executionId,planHash:plan.planHash,manifestDir:target.openzeppelin!.manifestDir,registry,metadata,effective,expected:expectedCode,assertArtifacts});
+   await assertCurrent();await execution.reconcile();
+   const acceptance=deepFreeze({version:1,status:'accepted',identity,executionId:plan.executionId,planHash:plan.planHash,target:plan.target,inputsHash:plan.inputsHash,sourceDefinitionHash:plan.sourceDefinitionHash,runtimeIdentity:plan.runtimeIdentity,finalized,assertions,materialization:{intentHash:materialization.journal.intentHash,recordPath,manifests:materialization.manifests},checkCode:code});
+   atomicDevelopmentWrite(root,`.gate-delivery/development/${plan.executionId}.acceptance.json`,json(acceptance));return {status:'accepted',acceptance};
+  },
+  export:()=>execution.export(),
+ });
+}

package/runtime/delivery/engine.ts

@@ -0,0 +1,29 @@
+import type { ReferenceObservation } from './references';
+import { createDeliveryValidation } from './validation';
+import { strictData } from './data';
+import type { WorkflowContext } from "../workflow/lib/context";
+import type { WorkflowStep } from "../workflow/lib/parameters";
+import { runWorkflowSteps } from "../workflow/engine";
+
+export type DeliveryStepContext = Omit<WorkflowContext, "mode"> & {
+  mode: "simulate" | "verify";
+};
+
+// Step execution only. The delivery launcher owns fork lifecycle and future
+// qualification sealing; durable transaction execution has a separate API.
+export const runDeliverySteps = async (
+  context: DeliveryStepContext,
+  steps: readonly WorkflowStep[],
+): Promise<{ references: readonly ReferenceObservation[] }> => {
+  if (context.mode !== "simulate" && context.mode !== "verify") {
+    throw new Error("Delivery step engine only supports simulate and verify");
+  }
+  steps = strictData(steps);
+  if (steps.some((step) => step.kind === "custom")) {
+    throw new Error("Delivery custom operations require the separate planning API");
+  }
+  const validation = createDeliveryValidation(context);
+  await validation.preflight(steps);
+  await runWorkflowSteps({ ...context, validation }, steps);
+  return Object.freeze({ references: validation.observations() });
+};

package/runtime/delivery/eoa-observation.ts

@@ -0,0 +1,106 @@
+import { deepFreeze, digest, exactObject } from '../workflow/lib/canonicalData';
+import { immutableDeliveryPlan } from './export';
+import { strictData } from './data';
+import { same, type SignedRecord, type UnsignedEnvelope } from './execution-model';
+import { verifyEoaSigned } from './eoa-signed';
+import { hash32, uint256, type TransactionObservation } from './observations';
+import type { DeliveryPlan } from './plan';
+
+export class EoaRpcFailure extends Error { constructor(cause: unknown) { super(`EOA RPC failed: ${cause instanceof Error ? cause.message : String(cause)}`, { cause }); } }
+export interface EoaRpc { request(method: string, params: readonly unknown[]): Promise<unknown>; }
+export type EoaFinality = { kind: 'rpc_finalized' } | { kind: 'confirmations'; depth: string };
+export interface EoaExecutionContext {
+    executionId: string; planHash: string; releaseHash: string; operator: string;
+    policyHash: string; chainId: string; target: string; finality: EoaFinality;
+}
+export function executionContext(raw: unknown, plan: DeliveryPlan): EoaExecutionContext {
+    const c = exactObject(strictData(raw), ['executionId','planHash','releaseHash','operator','policyHash','chainId','target','finality'], 'EOA execution context');
+    for (const key of ['executionId','planHash','operator','chainId','target'] as const) if (c[key] !== plan[key]) throw new Error(`Execution context ${key} mismatch`);
+    digest(c.releaseHash, 'release'); digest(c.policyHash, 'policy');
+    const f = c.finality as EoaFinality;
+    exactObject(f, f?.kind === 'rpc_finalized' ? ['kind'] : ['kind','depth'], 'finality policy');
+    if (f.kind !== 'rpc_finalized' && (f.kind !== 'confirmations' || BigInt(uint256(f.depth, 'confirmation depth')) < 1n)) throw new Error('Invalid explicit finality policy');
+    return deepFreeze(c as unknown as EoaExecutionContext);
+}
+function object(v: unknown, label: string): Record<string, unknown> { if (!v || typeof v !== 'object' || Array.isArray(v)) throw new Error(`Invalid RPC ${label}`); return v as Record<string, unknown>; }
+export function rpcQuantity(v: unknown): string {
+    // Some providers zero-pad hex quantities. Parse exactly with BigInt, never Number.
+    if (typeof v !== 'string' || !/^0x[0-9a-fA-F]+$/.test(v)) throw new Error('Invalid RPC quantity');
+    return uint256(BigInt(v).toString(), 'RPC quantity');
+}
+function address(v: unknown): string { if (typeof v !== 'string' || !/^0x[0-9a-fA-F]{40}$/.test(v)) throw new Error('Invalid RPC address'); return v.toLowerCase(); }
+function bytes(v: unknown): string { if (typeof v !== 'string' || !/^0x(?:[0-9a-fA-F]{2})*$/.test(v)) throw new Error('Invalid RPC bytes'); return v.toLowerCase(); }
+function hash(v: unknown): string { return hash32(bytes(v), 'RPC hash'); }
+const tag = (v: string) => '0x' + BigInt(v).toString(16);
+export async function verifyEoaChain(provider: EoaRpc, context: EoaExecutionContext): Promise<void> {
+    if (rpcQuantity(await provider.request('eth_chainId', [])) !== context.chainId) throw new Error('RPC chain identity mismatch');
+}
+export async function verifyEoaCode(provider: EoaRpc, executor: string, block: string): Promise<void> {
+    if (await provider.request('eth_getCode', [executor, block]) !== '0x') throw new Error('Unsupported executor: EOA with empty code required');
+}
+function rpcEnvelope(tx: Record<string, unknown>): UnsignedEnvelope {
+    const typeString = rpcQuantity(tx.type);
+    if (!['0','1','2'].includes(typeString)) throw new Error('Unsupported RPC transaction type');
+    const type = Number(typeString) as 0 | 1 | 2;
+    const accessList = type === 0 ? [] : (() => {
+        if (!Array.isArray(tx.accessList)) throw new Error('Missing RPC access list');
+        return tx.accessList.map(item => { const a = object(item, 'access list'); if (!Array.isArray(a.storageKeys)) throw new Error('Invalid RPC storage keys'); return { address: address(a.address), storageKeys: a.storageKeys.map(hash) }; });
+    })();
+    if (type === 0 && tx.accessList !== undefined && !same(tx.accessList, [])) throw new Error('Legacy RPC access list mismatch');
+    let chainId: string;
+    if (type === 0) {
+        // EIP-155 legacy JSON-RPC responses need not expose chainId. The protected
+        // signature's v is the chain identity; never substitute the current RPC chain.
+        const v = BigInt(rpcQuantity(tx.v));
+        if (v < 37n) throw new Error('Unprotected legacy RPC chain identity');
+        chainId = ((v - 35n) / 2n).toString();
+        if (tx.chainId !== undefined && rpcQuantity(tx.chainId) !== chainId) throw new Error('Legacy RPC chainId/v mismatch');
+    } else chainId = rpcQuantity(tx.chainId);
+    return { chainId, signer: address(tx.from), nonce: rpcQuantity(tx.nonce), to: address(tx.to), value: rpcQuantity(tx.value), data: bytes(tx.input), operation: 0, type, gasLimit: rpcQuantity(tx.gas), gasPrice: type === 2 ? null : rpcQuantity(tx.gasPrice), maxFeePerGas: type === 2 ? rpcQuantity(tx.maxFeePerGas) : null, maxPriorityFeePerGas: type === 2 ? rpcQuantity(tx.maxPriorityFeePerGas) : null, accessList };
+}
+export function eoaObservationReference(transactionId: string, transactionHash: string): string { return `${transactionId}@${hash32(transactionHash, 'transaction hash')}`; }
+export interface EoaObservationRequest {
+    plan: unknown; context: EoaExecutionContext; provider: EoaRpc; index: number; transactionHash: string;
+    original?: { unsigned: UnsignedEnvelope; signed: SignedRecord };
+}
+/** Finite, read-only hash query. Missing RPC results remain pending. No block scanning or fallback finality. */
+export async function observeEoaTransaction(input: EoaObservationRequest): Promise<TransactionObservation | undefined> {
+    const plan = immutableDeliveryPlan(input.plan), context = executionContext(input.context, plan), { index } = input;
+    const provider: EoaRpc = { async request(method, params) { try { return await input.provider.request(method, params); } catch (error) { throw new EoaRpcFailure(error); } } };
+    const expected = plan.transactions[index], transactionHash = hash32(input.transactionHash, 'transaction hash');
+    if (!expected) throw new Error('Unknown plan transaction index');
+    if (expected.operation !== 0) throw new Error('Unsupported EOA operation');
+    await verifyEoaChain(provider, context);
+    const txRaw = await provider.request('eth_getTransactionByHash', [transactionHash]);
+    const receiptRaw = await provider.request('eth_getTransactionReceipt', [transactionHash]);
+    if (txRaw === null || receiptRaw === null) return;
+    const tx = object(txRaw, 'transaction'), receipt = object(receiptRaw, 'receipt'), actual = rpcEnvelope(tx);
+    if (hash(tx.hash) !== transactionHash || hash(receipt.transactionHash) !== transactionHash || actual.chainId !== plan.chainId || actual.signer !== expected.executor || actual.to !== expected.to || actual.value !== expected.value || actual.data !== expected.data || address(receipt.from) !== expected.executor || address(receipt.to) !== expected.to) throw new Error('RPC transaction/receipt identity mismatch');
+    if (input.original) {
+        const signed = verifyEoaSigned(input.original.signed.rawTransaction, input.original.unsigned);
+        if (!same(signed, input.original.signed) || signed.transactionHash !== transactionHash || !same(actual, input.original.unsigned)) throw new Error('RPC transaction differs from original signed envelope');
+    }
+    if (tx.blockHash === null || tx.blockNumber === null || tx.transactionIndex === null) return;
+    const blockHash = hash(receipt.blockHash), blockNumber = rpcQuantity(receipt.blockNumber), indexString = rpcQuantity(receipt.transactionIndex);
+    if (hash(tx.blockHash) !== blockHash || rpcQuantity(tx.blockNumber) !== blockNumber || rpcQuantity(tx.transactionIndex) !== indexString) throw new Error('RPC inclusion identity mismatch');
+    const canonicalRaw = await provider.request('eth_getBlockByNumber', [tag(blockNumber), false]);
+    if (canonicalRaw === null) return;
+    const canonical = object(canonicalRaw, 'canonical block');
+    if (hash(canonical.hash) !== blockHash) return; // Unfinalized reorg: reread the same hash later.
+    if (rpcQuantity(canonical.number) !== blockNumber || !Array.isArray(canonical.transactions) || BigInt(indexString) >= BigInt(canonical.transactions.length) || hash(canonical.transactions[Number(indexString)]) !== transactionHash) throw new Error('RPC canonical inclusion mismatch');
+    await verifyEoaCode(provider, expected.executor, tag(blockNumber));
+    const headRaw = await provider.request('eth_getBlockByNumber', [context.finality.kind === 'rpc_finalized' ? 'finalized' : 'latest', false]);
+    if (headRaw === null) return;
+    const head = object(headRaw, 'finality block'), headNumber = rpcQuantity(head.number), headHash = hash(head.hash);
+    const headCanonicalRaw = await provider.request('eth_getBlockByNumber', [tag(headNumber), false]);
+    if (headCanonicalRaw === null) return;
+    const headCanonical = object(headCanonicalRaw, 'canonical finality block');
+    if (hash(headCanonical.hash) !== headHash || rpcQuantity(headCanonical.number) !== headNumber) return;
+    // Close the observation window by rereading inclusion after finality/code queries.
+    const endRaw = await provider.request('eth_getBlockByNumber', [tag(blockNumber), false]);
+    if (endRaw === null || hash(object(endRaw, 'canonical block').hash) !== blockHash) return;
+    const finalized = context.finality.kind === 'rpc_finalized' ? BigInt(headNumber) >= BigInt(blockNumber) : BigInt(headNumber) - BigInt(blockNumber) + 1n >= BigInt(context.finality.depth);
+    const status = rpcQuantity(receipt.status);
+    if (status !== '0' && status !== '1') throw new Error('Invalid RPC receipt status');
+    return deepFreeze({ observationId: eoaObservationReference(expected.transactionId, transactionHash), executionId: plan.executionId, planHash: plan.planHash, chainId: plan.chainId, target: plan.target, transaction: expected, transactionHash, state: finalized ? status === '1' ? 'finalized-success' : 'finalized-reverted' : 'included-unfinalized', blockNumber, blockHash });
+}

package/runtime/delivery/eoa-signed.ts

@@ -0,0 +1,55 @@
+/** Exact EIP-155 / EIP-2930 / EIP-1559 signed bytes. No Number conversion of quantities. */
+import { decodeRlp, encodeRlp, keccak256, recoverAddress } from 'ethers';
+import { same, unsignedHash, type UnsignedEnvelope, type SignedRecord } from './execution-model';
+import { uint256 } from './observations';
+
+type Rlp = string | Rlp[];
+function list(v: Rlp, length?: number): Rlp[] {
+    if (!Array.isArray(v) || (length !== undefined && v.length !== length)) throw new Error('Invalid signed RLP list');
+    return v;
+}
+function bytes(v: Rlp): string {
+    if (typeof v !== 'string' || !/^0x(?:[0-9a-f]{2})*$/.test(v)) throw new Error('Invalid signed RLP bytes');
+    return v;
+}
+function quantity(v: Rlp): string {
+    const b = bytes(v);
+    if (b.startsWith('0x00')) throw new Error('Noncanonical signed quantity');
+    return uint256(b === '0x' ? '0' : BigInt(b).toString(), 'signed quantity');
+}
+function address(v: Rlp): string {
+    const b = bytes(v);
+    if (!/^0x[0-9a-f]{40}$/.test(b)) throw new Error('Invalid signed destination/address');
+    return b;
+}
+function rlpQuantity(n: bigint): string { const s = n.toString(16); return n === 0n ? '0x' : '0x' + (s.length % 2 ? '0' : '') + s; }
+export function verifyEoaSigned(raw: unknown, frozen: UnsignedEnvelope): SignedRecord {
+    if (frozen.operation !== 0) throw new Error('Unsupported EOA operation');
+    if (typeof raw !== 'string' || !/^0x(?:[0-9a-f]{2})+$/.test(raw)) throw new Error('Invalid signed bytes');
+    const first = parseInt(raw.slice(2, 4), 16), type = first >= 0xc0 ? 0 : first;
+    if (![0, 1, 2].includes(type)) throw new Error('Unsupported signed transaction type');
+    const prefix = type ? raw.slice(0, 4) : '0x', payload = type ? '0x' + raw.slice(4) : raw;
+    const fields = list(decodeRlp(payload) as Rlp, type === 0 ? 9 : type === 1 ? 11 : 12);
+    if (encodeRlp(fields) !== payload) throw new Error('Noncanonical signed RLP');
+    const unsigned = fields.slice(0, -3), [v, r, s] = fields.slice(-3).map(quantity);
+    let parity: bigint, chainId: string;
+    if (type === 0) {
+        if (BigInt(v) < 35n) throw new Error('Signed legacy transaction requires EIP-155 chain identity');
+        parity = (BigInt(v) - 35n) % 2n; chainId = ((BigInt(v) - 35n) / 2n).toString();
+        unsigned.push(rlpQuantity(BigInt(chainId)), '0x', '0x');
+    } else { chainId = quantity(fields[0]); parity = BigInt(v); }
+    if (parity > 1n) throw new Error('Invalid signed parity');
+    const signingHash = keccak256(prefix + encodeRlp(unsigned).slice(2));
+    const signer = recoverAddress(signingHash, { r: '0x' + BigInt(r).toString(16).padStart(64, '0'), s: '0x' + BigInt(s).toString(16).padStart(64, '0'), yParity: Number(parity) as 0 | 1 }).toLowerCase();
+    const offset = type ? 1 : 0, gasIndex = type === 2 ? 4 : offset + 2;
+    const accessList = type === 0 ? [] : list(fields[gasIndex + 4]).map(entry => {
+        const [a, keys] = list(entry, 2);
+        return { address: address(a), storageKeys: list(keys).map(k => { const b = bytes(k); if (!/^0x[0-9a-f]{64}$/.test(b)) throw new Error('Invalid signed storage key'); return b; }) };
+    });
+    const actual: UnsignedEnvelope = {
+        chainId, signer, nonce: quantity(fields[offset]), to: address(fields[gasIndex + 1]), value: quantity(fields[gasIndex + 2]), data: bytes(fields[gasIndex + 3]), operation: 0, type: type as 0 | 1 | 2,
+        gasLimit: quantity(fields[gasIndex]), gasPrice: type === 2 ? null : quantity(fields[offset + 1]), maxFeePerGas: type === 2 ? quantity(fields[3]) : null, maxPriorityFeePerGas: type === 2 ? quantity(fields[2]) : null, accessList,
+    };
+    if (!same(actual, frozen)) throw new Error('Actual signed transaction differs from frozen approval snapshot');
+    return { rawTransaction: raw, transactionHash: keccak256(raw), unsignedDigest: unsignedHash(frozen) };
+}