gate-evm-tools 1.0.31 → 1.2.1

package/runtime/delivery/production-finalization.ts

@@ -2,7 +2,7 @@
 import path from 'node:path';
 import {getCreate2Address,Interface} from 'ethers';
 import {withDefaults} from '@openzeppelin/hardhat-upgrades/dist/utils/options';
-import {BytecodeChecker,artifactIdentity,hashStorageLayout,mergeEvmManifestCandidate,parseTargetManifest,resolveTargetManifestPaths} from 'gate-evm-tools/workflow';
+import {TRANSPARENT_PROXY_ARTIFACT,PROXY_ADMIN_ARTIFACT,ERC1967_ADMIN_SLOT,PROXY_ADMIN_INTERFACE,transparentAdminAddress,assertTransparentAdminImmutable,BytecodeChecker,artifactIdentity,hashStorageLayout,mergeEvmManifestCandidate,parseTargetManifest,resolveTargetManifestPaths} from 'gate-evm-tools/workflow';
 import {canonicalJson,deepFreeze,semanticHash} from '../workflow/lib/canonicalData';
 import {validateContractInfo,resolveDeployment} from '../workflow/lib/deployments';
 import {validateDeploymentInfo} from '../workflow/lib/deploymentInfo';
@@ -67,14 +67,14 @@ export async function finalizeProductionExecution(input:{root:string;ready:Produ
   const p=entry.prepared.plan,r=entry.prepared.request;const compiled=local(p.contract);same(artifactIdentity(compiled.artifact,'evm'),p.artifact,'Prepared sealed artifact');
   for(const deployment of p.deployments){
    if(deployment.initCodeHash&&getCreate2Address(r.factory,deployment.salt,deployment.initCodeHash).toLowerCase()!==deployment.address.toLowerCase())throw Error('Production CREATE2 address mismatch');
-   await compare(deployment.address,deployment.role==='proxy'?'@openzeppelin/contracts/proxy/ERC1967/ERC1967Proxy.sol:ERC1967Proxy':p.contract,`${entry.change.instanceId}:${deployment.role}`);
+   await compare(deployment.address,deployment.role==='proxy'?(p.proxyKind==='transparent'?TRANSPARENT_PROXY_ARTIFACT:'@openzeppelin/contracts/proxy/ERC1967/ERC1967Proxy.sol:ERC1967Proxy'):p.contract,`${entry.change.instanceId}:${deployment.role}`);
   }
   const address=p.deployments.find(d=>d.role==='proxy')?.address??('proxy' in r?r.proxy:p.deployments.find(d=>d.role==='contract')?.address);
   if(!address)throw Error('Production prepared address missing');
-  changes.set(entry.change.instanceId,{...entry.change,address,...(p.proxyKind==='uups'?{proxyAddress:address,proxyKind:'uups'}:{})});
+  changes.set(entry.change.instanceId,{...entry.change,address,...(p.proxyKind?{proxyAddress:address,proxyKind:p.proxyKind}:{})});
  }
  const candidates:any[]=[],expected:ExpectedDevelopmentCode[]=[],effective:Record<string,Record<string,string>>={[plan.target]:{}},checked=new Map<string,{address:string;contract:string;key:string}>();
- function expect(address:string,contract:string,key:string){const row={key,contract,address:address.toLowerCase()},old=checked.get(key);if(old)same(old,row,'Production CheckCode key');else{checked.set(key,row);expected.push(row);}}
+ function expect(address:string,contract:string,key:string){const row={key,contract:local(contract).artifact.contractName,address:address.toLowerCase()},old=checked.get(key);if(old)same(old,row,'Production CheckCode key');else{checked.set(key,row);expected.push(row);}}
  const deployed=[...changes.values()],unchangedAliases=new Set<string>();
  const registrationContext={base,target:plan.target,deploymentId:plan.deploymentId,executionId:plan.executionId,recordPath:recordPath(ready),updatedAt:new Date(Number(BigInt(anchor.timestamp))*1000).toISOString(),changes:deployed,preparations};
  // Apply the same validated upgrade replacement before resolving code coverage.
@@ -84,11 +84,20 @@ export async function finalizeProductionExecution(input:{root:string;ready:Produ
   const rows=Object.entries(registry).filter(([,a])=>a.toLowerCase()===address);if(rows.length!==1)throw Error('Production code target requires unique frozen registration');
   const [key]=rows[0],alias=key.split(':')[0],m=metadata[alias],contract=m?.actualContract??key.split(':').at(-1)!;
   effective[plan.target][key]=address;if(!changes.has(alias))unchangedAliases.add(alias);
-  if(m?.proxyKind&&m.proxyKind!=='uups')throw Error('Unsupported production proxy kind');
-  if(m?.proxyKind==='uups'){
+  if(m?.proxyKind&&m.proxyKind!=='uups'&&m.proxyKind!=='transparent')throw Error('Unsupported production proxy kind');
+  if(m?.proxyKind==='uups'||m?.proxyKind==='transparent'){
    const storage=await rpc('eth_getStorageAt',[address,slot,block]);if(typeof storage!=='string'||!/^0x0{24}[a-fA-F0-9]{40}$/.test(storage))throw Error('Invalid finalized UUPS implementation slot');
    const implementation='0x'+storage.slice(-40).toLowerCase();if(implementation!==m.implementationAddress?.toLowerCase())throw Error('Final production UUPS implementation mismatch');
-   expect(implementation,contract,alias);expect(address,'ERC1967Proxy',`${alias}_Proxy`);
+   expect(implementation,contract,alias);expect(address,m.proxyKind==='transparent'?TRANSPARENT_PROXY_ARTIFACT:'ERC1967Proxy',`${alias}_Proxy`);
+   if(m.proxyKind==='transparent'){
+    const admin=m.proxyAdminAddress?.toLowerCase();if(!admin||admin!==transparentAdminAddress(address)||!m.proxyAdminOwner)throw Error('Missing frozen Transparent admin identity');
+    const value=await rpc('eth_getStorageAt',[address,ERC1967_ADMIN_SLOT,block]);if(typeof value!=='string'||!/^0x0{24}[a-fA-F0-9]{40}$/.test(value)||'0x'+value.slice(-40).toLowerCase()!==admin)throw Error('Final production Transparent admin mismatch');
+    assertTransparentAdminImmutable(await rpc('eth_getCode',[address,block]) as string,local(TRANSPARENT_PROXY_ARTIFACT).immutableReferences,admin);
+    const owner=PROXY_ADMIN_INTERFACE.decodeFunctionResult('owner',await rpc('eth_call',[{to:admin,data:PROXY_ADMIN_INTERFACE.encodeFunctionData('owner')},block]) as string)[0];
+    const version=PROXY_ADMIN_INTERFACE.decodeFunctionResult('UPGRADE_INTERFACE_VERSION',await rpc('eth_call',[{to:admin,data:PROXY_ADMIN_INTERFACE.encodeFunctionData('UPGRADE_INTERFACE_VERSION')},block]) as string)[0];
+    if(owner.toLowerCase()!==m.proxyAdminOwner.toLowerCase()||version!=='5.0.0')throw Error('Final production ProxyAdmin owner/version mismatch');
+    expect(admin,PROXY_ADMIN_ARTIFACT,`${alias}_ProxyAdmin`);
+   }
    const artifact=local(contract).entry;
    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');
@@ -98,7 +107,7 @@ export async function finalizeProductionExecution(input:{root:string;ready:Produ
     if(!request||request.kind==='create2-deploy')throw Error('Missing UUPS preparation selection request');
     // Match the compiler's preparationSelection identity. Canonical request data
     // contains no undefined values; omit official optional top-level safety flags.
-    const options=Object.fromEntries(Object.entries(withDefaults({kind:'uups',constructorArgs:request.constructorArgs,...(request.unsafeAllow?{unsafeAllow:request.unsafeAllow}: {})} as Parameters<typeof withDefaults>[0])).filter(([,value])=>value!==undefined));
+    const options=Object.fromEntries(Object.entries(withDefaults({kind:request.proxyKind,constructorArgs:request.constructorArgs,...(request.unsafeAllow?{unsafeAllow:request.unsafeAllow}: {})} as Parameters<typeof withDefaults>[0])).filter(([,value])=>value!==undefined));
     const encodedArgs=new Interface(artifact.artifact.abi).encodeDeploy(request.constructorArgs),optionsHash=semanticHash(options);
     const selections=compiler.selections.filter(s=>s.fqn===artifact.fqn&&s.artifactDigest===artifact.digest&&s.encodedArgs===encodedArgs&&semanticHash(s.options)===optionsHash);
     if(selections.length!==1)throw Error('Missing unique frozen OZ implementation selection');
@@ -108,11 +117,11 @@ export async function finalizeProductionExecution(input:{root:string;ready:Produ
     // regardless of selections made for other instances of the same artifact.
     const frozen=configuration.manifests?.filter(f=>f.path===manifestPath);if(frozen?.length!==1||frozen[0].contents===null)throw Error('Missing frozen existing UUPS manifest');
     const manifest=parseTargetManifest(Buffer.from(frozen[0].contents)),proxies=manifest.proxies.filter(p=>p.address.toLowerCase()===address),implementations=Object.entries(manifest.impls).filter(([,v])=>v&&[v.address,...(v.allAddresses??[])].some(a=>a.toLowerCase()===implementation));
-    if(proxies.length!==1||proxies[0].kind!=='uups'||implementations.length!==1)throw Error('Invalid frozen existing UUPS manifest registration');
+    if(proxies.length!==1||proxies[0].kind!==m.proxyKind||implementations.length!==1)throw Error('Invalid frozen existing UUPS manifest registration');
     versionKey=implementations[0][0];layout=implementations[0][1]!.layout;
    }
    if(typeof versionKey!=='string'||!/^[a-f0-9]{64}$/.test(versionKey))throw Error('Invalid frozen OZ version');
-   candidates.push({path:manifestPath,proxy:address,implementation,versionKey,layout,layoutHash:hashStorageLayout(layout)});
+   candidates.push({path:manifestPath,proxy:address,proxyKind:m.proxyKind,implementation,versionKey,layout,layoutHash:hashStorageLayout(layout)});
   }else expect(address,contract,alias);
  }
  if(!expected.length)throw Error('Empty production CheckCode coverage');

package/runtime/delivery/production-intent.ts

@@ -0,0 +1,14 @@
+/** Re-simulation may change operator routing, but cannot replace released transaction intent. */
+import { canonicalJson } from '../workflow/lib/canonicalData';
+import { parseCalldataReviews } from './calldata-review';
+import type { DeliveryCollection } from './planning';
+
+export function assertReleasedCalldataIntent(actual: DeliveryCollection, released: DeliveryCollection): void {
+  const current = parseCalldataReviews(actual.calldata, actual.plan.transactions);
+  const frozen = parseCalldataReviews(released.calldata, released.plan.transactions);
+  if (canonicalJson(current) !== canonicalJson(frozen))
+    throw Error('Final simulation changed released calldata ABI intent');
+  for (const key of ['derivationSeed', 'values'] as const)
+    if (canonicalJson(actual.plan.derivedBindings[key]) !== canonicalJson(released.plan.derivedBindings[key]))
+      throw Error('Final simulation changed released derivation');
+}

package/runtime/delivery/production.ts

@@ -1,5 +1,7 @@
 /** Public release-only production boundary. Host capabilities never enter JSON options. */
 import fs from 'node:fs';
+import {customExecutionInput} from './execution-identity';
+import {assertReleasedCalldataIntent} from './production-intent';
 import os from 'node:os';
 import path from 'node:path';
 import { randomUUID } from 'node:crypto';
@@ -16,6 +18,10 @@ import { canonicalJson, deepFreeze, exactObject, semanticHash } from '../workflo
 import { createDeliveryEoaExecution, type EoaExecutionOptions, type EoaHashReferences } from './eoa';
 import type { ReleaseGraphOptions } from './release-graph';
 import type { DeliveryCollection } from './planning';
+import { parseCalldataReviews } from './calldata-review';
+import { projectDeliveryCalls, mergeDeliveryCalls } from './public-calldata';
+import { archiveDeliveryCalls } from './calldata-archive';
+import { serializeDeliveryCalls } from './calldata-format';
 import { finalizeProductionExecution, retainedProductionFinalizationAnchor, type FinalizedAnchor } from './production-finalization';
 export { productionChildEnvironment } from './production-environment';
 export interface ProductionOptions extends ReleaseGraphOptions {
@@ -58,9 +64,12 @@ export function inspectDeliveryProduction(raw: ProductionOptions, command: Produ
     if (record.schema !== 'gate-delivery-production' || record.version !== 1 || record.status !== 'READY' || record.generation !== 'complete' || semanticHash(body) !== artifactHash)
         throw Error('Invalid production READY artifact');
     const plan = parseDeliveryPlan(record.collection.plan);
+    parseCalldataReviews(record.collection.calldata, plan.transactions);
+    const deliveryCalls=projectDeliveryCalls({plan,calldata:record.collection.calldata,operations:current.release.operations as any[],preparations:record.collection.preparations});
+    if(canonicalJson(deliveryCalls)!==canonicalJson(record.deliveryCalls))throw Error('Frozen production public projection mismatch');
     if (record.releaseHash !== current.releaseHash || plan.inputsHash !== current.release.inputsHash || plan.sourceDefinitionHash !== current.release.sourceDefinitionHash || plan.executionId !== current.input.executionId || plan.target !== current.input.target || plan.operator !== current.input.operator.toLowerCase() || plan.environment !== 'prod' || plan.chainId !== String(current.target.chainId))
         throw Error('Production artifact context mismatch');
-    return deepFreeze({ status: 'ready' as const, plan, collection: record.collection as DeliveryCollection, finalization: record.finalization, releaseHash: current.releaseHash, artifactHash, sha256: byteHash(bytes), path: artifactPath(current.input.executionId), ...(current.target.safe ? { safeTarget: current.target.safe } : {}) });
+    return deepFreeze({ status: 'ready' as const, plan, collection: record.collection as DeliveryCollection, deliveryCalls, operations: current.release.operations as any[], finalization: record.finalization, releaseHash: current.releaseHash, artifactHash, sha256: byteHash(bytes), path: artifactPath(current.input.executionId), ...(current.target.safe ? { safeTarget: current.target.safe } : {}) });
 }
 /** Instantiate the delivered business operations, never accept replacement operations or parameters. */
 export async function prepareDeliveryProduction(raw: ProductionOptions) {
@@ -91,7 +100,16 @@ export async function prepareDeliveryProduction(raw: ProductionOptions) {
         const parameter = release.parameters.find((p: any) => p.target === input.target);
         if (!parameter)
             throw Error('Release parameters missing');
-        const staged = await worker.request('stage', { ...common, role: 'target', handshake: ready.handshake, target: current.target, params: parameter.resolved.values, steps: release.operations, deploymentId: input.deploymentId, businessRoot: `scripts/tasks/${input.deploymentId}`, executionId: input.executionId, sourceDefinitionHash: release.sourceDefinitionHash });
+        // Production consumes the released CREATE2 derivation, while its execution
+        // identity and durable progress remain local to this execution.
+        const candidate = JSON.parse(fs.readFileSync(path.join(root, release.candidate.path), 'utf8'));
+        const qualification = candidate.aggregate.collections.find((c: any) => c.plan.target === input.target);
+        if (!qualification) throw Error('Released target qualification missing');
+        const qualificationPlan = parseDeliveryPlan(qualification.plan);
+        if (qualificationPlan.inputsHash !== release.inputsHash || qualificationPlan.target !== input.target)
+            throw Error('Released derivation context mismatch');
+        const derivationSeed = qualificationPlan.derivedBindings.derivationSeed;
+        const staged = await worker.request('stage', { ...common, role: 'target', handshake: ready.handshake, target: current.target, params: parameter.resolved.values, steps: release.operations, deploymentId: input.deploymentId, businessRoot: `scripts/tasks/${input.deploymentId}`, executionId: input.executionId, derivationSeed, sourceDefinitionHash: release.sourceDefinitionHash });
         check();
         if (staged.ready !== true)
             throw Error('Production generation not READY');
@@ -99,15 +117,15 @@ export async function prepareDeliveryProduction(raw: ProductionOptions) {
         check();
         const sourceChecked = await source.request('check');
         check();
-        const candidate = JSON.parse(fs.readFileSync(path.join(root, release.candidate.path), 'utf8'));
         const expected = candidate.aggregate.inputs.targets.find((t: any) => t.target === input.target);
-        for (const [actual, wanted] of [[checked.compiler.stableDigest, expected.compiler.stableDigest], [checked.custom, expected.custom], [checked.configuration.configurationRuntimeHash, expected.configuration.configurationRuntimeHash], [sourceChecked.configuration.configurationRuntimeHash, expected.sourceConfiguration.configurationRuntimeHash]])
+        for (const [actual, wanted] of [[checked.compiler.stableDigest, expected.compiler.stableDigest], [customExecutionInput(checked.custom), customExecutionInput(expected.custom)], [checked.configuration.configurationRuntimeHash, expected.configuration.configurationRuntimeHash], [sourceChecked.configuration.configurationRuntimeHash, expected.sourceConfiguration.configurationRuntimeHash]])
             if (canonicalJson(actual) !== canonicalJson(wanted))
                 throw Error('Final simulation changed released input closure');
         const collection = await worker.request('bind', { inputsHash: release.inputsHash }) as DeliveryCollection;
         check();
+        assertReleasedCalldataIntent(collection, qualification);
         expectedDevelopmentAssertions(collection, release.operations);
-        if (collection.plan.executionId !== input.executionId || collection.plan.operator !== input.operator.toLowerCase())
+        if (collection.plan.executionId !== input.executionId || collection.plan.operator !== input.operator.toLowerCase() || collection.plan.derivedBindings.derivationSeed !== derivationSeed)
             throw Error('Final simulation context mismatch');
         await worker.request('close');
         await source.request('close');
@@ -118,7 +136,8 @@ export async function prepareDeliveryProduction(raw: ProductionOptions) {
             if (paths.file !== paths.fallbackFile && fileBytes(root, path.relative(root, paths.fallbackFile)) !== null)
                 throw Error('Noncanonical manifest fallback requires explicit migration');
             const finalization = { compiler: checked.compiler, registration: { registry: JSON.parse(fileBytes(root, 'contractInfo.json') ?? '{}'), metadata: JSON.parse(fileBytes(root, 'deploymentInfo.json') ?? '{"version":1,"networks":{}}') }, manifests: [{ path: manifestPath, contents: fileBytes(root, manifestPath) }] };
-            const body = { schema: 'gate-delivery-production', version: 1, status: 'READY', generation: 'complete', releaseHash: current.releaseHash, collection, finalization }, record = { ...body, artifactHash: semanticHash(body) };
+            const deliveryCalls=projectDeliveryCalls({plan:collection.plan,calldata:collection.calldata,operations:release.operations,preparations:collection.preparations});
+            const body = { schema: 'gate-delivery-production', version: 1, status: 'READY', generation: 'complete', releaseHash: current.releaseHash, collection, deliveryCalls, finalization }, record = { ...body, artifactHash: semanticHash(body) };
             const prior = fileBytes(root, artifactPath(input.executionId));
             if (prior !== null && prior !== encode(record))
                 throw Error('Execution ID already has immutable final simulation');
@@ -160,7 +179,7 @@ export async function runDeliveryProduction(command: Exclude<ProductionCommand,
             throw Error('PRODUCTION_SIGNER_UNAVAILABLE: trusted host required');
         if (command !== 'export-calldata')
             throw Error('Trusted host observation provider required');
-        return renderProductionExport(ready);
+        return persistProductionExport(input,ready,renderProductionExport(ready));
     }
     const { guard, request, store, finality, signer, approval } = ports;
     const check = () => { guard(); const current = inspectDeliveryProduction(input, command); if (current.status !== 'ready' || current.artifactHash !== ready.artifactHash)
@@ -175,7 +194,7 @@ export async function runDeliveryProduction(command: Exclude<ProductionCommand,
     const result = command === 'execute' ? await kernel.execute(captured?.unsigned) : command === 'export-calldata' ? await kernel.export() : await kernel.reconcile(captured?.hashes ?? {});
     check();
     if (command === 'export-calldata')
-        return renderProductionExport(ready, result as Awaited<ReturnType<typeof kernel.export>>);
+        return persistProductionExport(input,ready,renderProductionExport(ready, result as Awaited<ReturnType<typeof kernel.export>>));
     if (command === 'verify' && (result as any).status === 'complete') {
         try {
             const root = projectRoot(input.workspaceRoot, input.projectRoot), priorAnchor = retainedProductionFinalizationAnchor(root, ready);
@@ -193,14 +212,35 @@ export async function runDeliveryProduction(command: Exclude<ProductionCommand,
     return result;
 }
 import { renderDeliveryExport } from './export';
+async function persistProductionExport(input:ProductionOptions,ready:Extract<ReturnType<typeof inspectDeliveryProduction>,{status:'ready'}>,result:ReturnType<typeof renderProductionExport>){
+ const exported=result.status==='preparation-required'?result.export:result;
+ const deliveryFile=await archiveDeliveryCalls({...input,calls:JSON.parse(exported.json),provenance:{releaseRef:input.releaseRef,sources:[{planHash:ready.plan.planHash,chainId:ready.plan.chainId,artifactHash:ready.artifactHash,releaseHash:ready.releaseHash,executionId:ready.plan.executionId}]},assertCurrent(){const now=inspectDeliveryProduction(input,'export-calldata');if(now.status!=='ready'||now.artifactHash!==ready.artifactHash||now.releaseHash!==ready.releaseHash)throw Error('Production changed during calldata publication');}});
+ const artifact=deepFreeze({...exported,deliveryFile});
+ return result.status==='preparation-required'?deepFreeze({...result,export:artifact}):artifact;
+}
+
+/** Each network is validated independently before one combined immutable JSON is published. */
+export async function exportProductionCalldata(productions:readonly ProductionOptions[]){
+ if(!productions.length)throw Error('Production targets required');
+ const inputs=productions.map(p=>deepFreeze(strictData(p))),first=inputs[0];
+ for(const p of inputs)if(canonicalJson([p.workspaceRoot,p.projectRoot,p.taskId,p.deploymentId,p.releaseRef])!==canonicalJson([first.workspaceRoot,first.projectRoot,first.taskId,first.deploymentId,first.releaseRef]))throw Error('Multi-network delivery must belong to one deployment release');
+ const ready=inputs.map(input=>{const r=inspectDeliveryProduction(input,'export-calldata');if(r.status!=='ready')throw Error('Production calldata generation is pending');return r;});
+ const calls=mergeDeliveryCalls(ready.map(r=>({plan:r.plan,calldata:r.collection.calldata,operations:r.operations,preparations:r.collection.preparations})));
+ const deliveryFile=await archiveDeliveryCalls({...first,calls,provenance:{releaseRef:first.releaseRef,sources:ready.map(r=>({planHash:r.plan.planHash,chainId:r.plan.chainId,artifactHash:r.artifactHash,releaseHash:r.releaseHash,executionId:r.plan.executionId}))},assertCurrent(){inputs.forEach((input,i)=>{const now=inspectDeliveryProduction(input,'export-calldata');if(now.status!=='ready'||now.artifactHash!==ready[i].artifactHash||now.releaseHash!==ready[i].releaseHash)throw Error('Multi-network production changed during publication');});}});
+ return deepFreeze({status:'artifact-delivered' as const,json:serializeDeliveryCalls(calls),deliveryFile});
+}
 export function renderProductionExport(ready: Extract<ReturnType<typeof inspectDeliveryProduction>, {
     status: 'ready';
 }>, exported = renderDeliveryExport(ready.plan)) {
+    if (canonicalJson(exported.model.plan) !== canonicalJson(ready.plan)) throw Error('Exported plan differs from frozen production plan');
+    const calldataReview = { version: 1, planHash: ready.plan.planHash, chainId: ready.plan.chainId,
+        transactions: parseCalldataReviews(ready.collection.calldata, ready.plan.transactions), check: 'matches-frozen-intent' };
     const start = exported.model.completed.length, active = ready.plan.transactions[start], frozen = (exported.model as any).safeEnvelopes ?? [];
     const needsPreparation = !!ready.safeTarget && active?.route === 'external' && !frozen.some((x: any) => x.envelope.start === start);
-    const model = deepFreeze({ ...exported.model, ...(ready.safeTarget ? { safePreparation: needsPreparation ? 'preparation-required' : active?.route === 'external' ? 'ready' : 'not-applicable', futureSafeEnvelopes: 'pending until their segment becomes executable' } : {}), releaseHash: ready.releaseHash, artifactHash: ready.artifactHash });
-    const json = canonicalJson(model);
-    const artifact = deepFreeze({ status: 'artifact-delivered' as const, model, json, markdown: `# Production calldata\n\nRelease: ${ready.releaseHash}\nExecution: ${ready.plan.executionId}\n\n\`\`\`json\n${json}\n\`\`\`\n` });
+    const deliveryContext = { operations: ready.operations, preparations: ready.collection.preparations };
+    const model = deepFreeze({ ...exported.model, calldataReview, deliveryContext, ...(ready.safeTarget ? { safePreparation: needsPreparation ? 'preparation-required' : active?.route === 'external' ? 'ready' : 'not-applicable', futureSafeEnvelopes: 'pending until their segment becomes executable' } : {}), releaseHash: ready.releaseHash, artifactHash: ready.artifactHash });
+    const json = serializeDeliveryCalls(projectDeliveryCalls({ plan: ready.plan, calldata: ready.collection.calldata, operations: ready.operations, preparations: ready.collection.preparations }));
+    const artifact = deepFreeze({ status: 'artifact-delivered' as const, model, json });
     return needsPreparation ? deepFreeze({ status: 'preparation-required' as const, export: artifact }) : artifact;
 }
 import { parseConfigurationDefinition } from './configuration-definition';

package/runtime/delivery/project-files.ts

@@ -34,25 +34,30 @@ export function readFile(root: string, relative: string): string | undefined {
   const file = confinedFile(root, relative);
   return stat(file) ? fs.readFileSync(file, 'utf8') : undefined;
 }
-export function coreMarker(root: string): void {
-  parseCoreMarker(readFile(root, '.gate-template.json') ?? 'null');
+export function deliveryProjectMarker(root: string): void {
+  parseDeliveryProjectMarker(readFile(root, '.gate-template.json') ?? 'null');
 }
-/** Validate the same captured marker bytes whose digest is being bound. */
-export function parseCoreMarker(bytes: string | Buffer): void {
+/** Validate the same captured marker bytes whose digest is bound to current inputs. */
+export function parseDeliveryProjectMarker(bytes: string | Buffer): void {
   const marker = JSON.parse(bytes.toString());
-  if (!marker || marker.template !== 'gateflow-evm-core@1' || marker.templateVersion !== 1 || marker.profile !== 'core') throw new Error('Unsupported core template; no legacy migration is performed');
+  if (!marker || marker.profile !== 'full' || marker.templateVersion !== 1
+    || marker.template !== `gateflow-evm-${marker.profile}@1`) throw new Error('Unsupported EVM template; no legacy migration is performed');
   if (marker.generator?.name !== 'gate-evm-hardhat-foundry' || typeof marker.generator?.version !== 'string'
     || !/^\d+\.\d+\.\d+(?:-[\w.-]+)?$/.test(marker.generator.version)
-    || !marker.generation?.inputs || !marker.generation?.files || !Array.isArray(marker.generation?.preserved)) throw new Error('Invalid core generator provenance');
-  if (marker.generation.state !== 'complete') throw new Error('Core generation is pending or invalid');
-  const inputs = object(marker.generation.inputs, 'core generation provenance inputs');
-  const files = object(marker.generation.files, 'core generation provenance files');
+    || !marker.generation?.inputs || !marker.generation?.files || !Array.isArray(marker.generation?.preserved)) throw new Error('Invalid EVM generator provenance');
+  if (marker.generation.state !== 'complete') throw new Error('EVM generation is pending or invalid');
+  const inputs = object(marker.generation.inputs, 'EVM generation provenance inputs', ['projectName', 'networks', 'examples']);
+  const files = object(marker.generation.files, 'EVM generation provenance files');
   const preserved = marker.generation.preserved as unknown[];
   const optional = ['README.md', 'AGENTS.md', '.gitignore'];
-  const assets = ['package.json', 'hardhat.config.ts', 'tsconfig.json', ...optional, 'contracts/.gitkeep', 'test/.gitkeep'];
+  const assets = ['package.json', 'package-lock.json', 'hardhat.config.ts', 'rpc.env', '.env.example', 'tsconfig.json', ...optional, 'contracts/.gitkeep', 'test/.gitkeep',
+    'foundry.toml', 'config.yaml',
+    ...(Object.hasOwn(files, 'vendor/gate-evm-tools-1.2.0.tgz') ? ['vendor/gate-evm-tools-1.2.0.tgz'] : []),
+    ...(inputs.examples === true ? ['contracts/Counter.sol', 'test/Counter.ts', 'test/Counter.t.sol'] : [])];
   if (typeof inputs.projectName !== 'string' || !inputs.projectName || !Array.isArray(inputs.networks)
+    || typeof inputs.examples !== 'boolean'
     || preserved.some(file => typeof file !== 'string' || !optional.includes(file))
     || new Set(preserved).size !== preserved.length
     || Object.keys(files).sort().join('\n') !== assets.filter(file => !preserved.includes(file)).sort().join('\n')
-    || Object.values(files).some(hash => typeof hash !== 'string' || !/^[a-f0-9]{64}$/.test(hash))) throw new Error('Invalid core generation provenance');
+    || Object.values(files).some(hash => typeof hash !== 'string' || !/^[a-f0-9]{64}$/.test(hash))) throw new Error('Invalid EVM generation provenance');
 }

package/runtime/delivery/project-rpc.ts

@@ -0,0 +1,116 @@
+/** Fixed template RPC syntax. Inspection reads local env data without evaluating project code. */
+import ts from 'typescript';
+import { parseEnv } from 'node:util';
+import { readFile } from './project-files';
+
+export const PROJECT_ENV_BOOTSTRAP = `for (const file of ["rpc.env", ".env"]) {
+  const envFile = join(__dirname, file);
+  if (existsSync(envFile)) {
+    try {
+      process.loadEnvFile(envFile);
+    } catch (error) {
+      if (file !== ".env" || !["ENOENT", "EPERM", "EACCES"].includes((error as NodeJS.ErrnoException).code ?? "")) throw error;
+      console.warn("Project credentials are unavailable; compilation and public checks can continue. Use the application host for credential-bearing delivery operations.");
+    }
+  }
+}`;
+export const PROJECT_RPC_HELPER = [
+  "function rpcUrl(options: { route: string; publicFallback: string | undefined; useBaseRpc: boolean }): string {",
+  "  const fallback = options.publicFallback?.trim() || \"\";",
+  "  const base = process.env.BASE_RPC_URI?.trim();",
+  "  if (!options.useBaseRpc || !base) return fallback;",
+  "  return `${base.replace(/\\/+$/, \"\")}/${options.route}/`;",
+  "}",
+].join('\n');
+const printer = ts.createPrinter({ removeComments: true });
+function syntax(node: ts.Node, file: ts.SourceFile): string {
+  return printer.printNode(ts.EmitHint.Unspecified, node, file);
+}
+function statement(source: string): string {
+  const file = ts.createSourceFile('rpc.ts', source, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
+  return syntax(file.statements[0], file);
+}
+const bootstrapSyntax = statement(PROJECT_ENV_BOOTSTRAP), helperSyntax = statement(PROJECT_RPC_HELPER);
+
+export function projectRpcSyntax(file: ts.SourceFile): { statements: Set<ts.Statement>; bootstrap: boolean; helper: boolean } {
+  const statements = new Set<ts.Statement>();
+  let bootstrap = false, helper = false;
+  const imports = new Set<string>();
+  for (const node of file.statements) {
+    if (ts.isImportDeclaration(node) && ts.isStringLiteral(node.moduleSpecifier)
+      && ['node:fs', 'node:path'].includes(node.moduleSpecifier.text)) {
+      const name = node.moduleSpecifier.text, clause = node.importClause;
+      const wanted = name === 'node:fs' ? 'existsSync' : 'join';
+      if (imports.has(name) || node.attributes || !clause || clause.name || clause.isTypeOnly
+        || !clause.namedBindings || !ts.isNamedImports(clause.namedBindings)
+        || clause.namedBindings.elements.length !== 1 || clause.namedBindings.elements[0].name.text !== wanted
+        || clause.namedBindings.elements[0].propertyName) throw Error('Unsupported project RPC import');
+      imports.add(name); statements.add(node);
+    } else if (ts.isForOfStatement(node) && syntax(node, file) === bootstrapSyntax) {
+      if (bootstrap) throw Error('Duplicate project RPC loader');
+      bootstrap = true; statements.add(node);
+    } else if (ts.isFunctionDeclaration(node) && node.name?.text === 'rpcUrl') {
+      if (helper || syntax(node, file) !== helperSyntax) throw Error('Unsupported project RPC helper');
+      helper = true; statements.add(node);
+    }
+  }
+  if (bootstrap !== (imports.size === 2) || (!bootstrap && imports.size)) throw Error('Incomplete project RPC loader');
+  const config = file.statements.findIndex(node => ts.isVariableStatement(node) || ts.isExportAssignment(node));
+  if (bootstrap && config >= 0 && [...statements].some(node => ts.isForOfStatement(node) && file.statements.indexOf(node) > config))
+    throw Error('Project RPC loader must precede configuration');
+  return { statements, bootstrap, helper };
+}
+
+export function projectRpcOptions(node: ts.CallExpression): { route: string; publicFallback: ts.Expression; useBaseRpc: boolean } {
+  if (!ts.isIdentifier(node.expression) || node.expression.text !== 'rpcUrl' || node.arguments.length !== 1 || node.typeArguments)
+    throw Error('Unsupported project RPC call');
+  const options = node.arguments[0];
+  if (!ts.isObjectLiteralExpression(options)) throw Error('Unsupported project RPC options');
+  const fields = new Map<string, ts.Expression>();
+  for (const property of options.properties) {
+    if (!ts.isPropertyAssignment(property) || (!ts.isIdentifier(property.name) && !ts.isStringLiteral(property.name)))
+      throw Error('Unsupported project RPC option');
+    const name = property.name.text;
+    if (!['route', 'publicFallback', 'useBaseRpc'].includes(name) || fields.has(name)) throw Error('Unsupported project RPC option');
+    fields.set(name, property.initializer);
+  }
+  const route = fields.get('route'), useBaseRpc = fields.get('useBaseRpc'), publicFallback = fields.get('publicFallback');
+  if (!route || !ts.isStringLiteral(route) || !/^[a-zA-Z0-9][a-zA-Z0-9-]*$/.test(route.text)) throw Error('Unsupported project RPC route');
+  if (!publicFallback || !useBaseRpc || ![ts.SyntaxKind.TrueKeyword, ts.SyntaxKind.FalseKeyword].includes(useBaseRpc.kind))
+    throw Error('Project RPC requires a literal useBaseRpc boolean and publicFallback');
+  return { route: route.text, publicFallback, useBaseRpc: useBaseRpc.kind === ts.SyntaxKind.TrueKeyword };
+}
+
+export function resolveProjectRpc(route: string, publicFallback: string | undefined, useBaseRpc: boolean, env: NodeJS.ProcessEnv): string {
+  const base = env.BASE_RPC_URI?.trim();
+  return useBaseRpc && base ? `${base.replace(/\/+$/, '')}/${route}/` : publicFallback?.trim() || '';
+}
+
+function projectEnvironment(root: string, source: string, env: NodeJS.ProcessEnv, files: readonly string[]): NodeJS.ProcessEnv {
+  const file = ts.createSourceFile('hardhat.config.ts', source, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
+  if (!projectRpcSyntax(file).bootstrap) return env;
+  const effective = { ...env };
+  for (const name of files) {
+    try {
+      const contents = readFile(root, name);
+      if (contents === undefined) continue;
+      for (const [key, value] of Object.entries(parseEnv(contents))) if (effective[key] === undefined) effective[key] = value;
+    } catch (error) {
+      if (name === '.env' && ['EPERM', 'EACCES'].includes((error as NodeJS.ErrnoException).code ?? '')) {
+        throw Error('Project credential environment is protected; run credential-bearing delivery operations through the trusted application host. Configure public RPCs in rpc.env.');
+      }
+      throw Error(`Cannot read local project RPC environment (${name})`);
+    }
+  }
+  return effective;
+}
+
+/** Static diagnostics never access the credential file, even when it is readable. */
+export function projectPublicRpcEnvironment(root: string, source: string, env: NodeJS.ProcessEnv): NodeJS.ProcessEnv {
+  return projectEnvironment(root, source, env, ['rpc.env']);
+}
+
+/** Actual runtime observation must retain the same environment semantics as Hardhat. */
+export function projectRpcEnvironment(root: string, source: string, env: NodeJS.ProcessEnv): NodeJS.ProcessEnv {
+  return projectEnvironment(root, source, env, ['rpc.env', '.env']);
+}

package/runtime/delivery/project.ts

@@ -3,8 +3,9 @@ import ts from 'typescript';
 import { positiveInteger, type ProjectNetworkSnapshot } from './protocol';
 import { validateNetworkAlias } from './policy';
 
-export { stat, confinedFile, projectRoot, readFile, coreMarker } from './project-files';
+export { stat, confinedFile, projectRoot, readFile, deliveryProjectMarker } from './project-files';
 import { confinedFile, readFile } from './project-files';
+import { projectRpcSyntax, projectRpcOptions, resolveProjectRpc, projectRpcEnvironment, projectPublicRpcEnvironment } from './project-rpc';
 
 function unwrap(node: ts.Expression): ts.Expression {
   while (ts.isParenthesizedExpression(node) || ts.isAsExpression(node) || ts.isSatisfiesExpression(node)) node = node.expression;
@@ -63,7 +64,7 @@ export function projectDefaultNetwork(root: string): string {
   if (!ts.isStringLiteral(network)) throw new Error('Project defaultNetwork must be a static string for delivery routing');
   return validateNetworkAlias(network.text, 'defaultNetwork');
 }
-function rpcValue(node: ts.Expression, env: NodeJS.ProcessEnv): string | undefined {
+function rpcValue(node: ts.Expression, env: NodeJS.ProcessEnv, helper: boolean): string | undefined {
   node = unwrap(node);
   if (ts.isStringLiteral(node)) return node.text;
   if (ts.isPropertyAccessExpression(node) && ts.isPropertyAccessExpression(node.expression)
@@ -73,19 +74,30 @@ function rpcValue(node: ts.Expression, env: NodeJS.ProcessEnv): string | undefin
     && ts.isIdentifier(node.expression.expression) && node.expression.expression.text === 'process'
     && node.expression.name.text === 'env' && ts.isStringLiteral(node.argumentExpression)) return env[node.argumentExpression.text];
   if (ts.isBinaryExpression(node) && [ts.SyntaxKind.BarBarToken, ts.SyntaxKind.QuestionQuestionToken].includes(node.operatorToken.kind)) {
-    const left = rpcValue(node.left, env);
+    const left = rpcValue(node.left, env, helper);
     return node.operatorToken.kind === ts.SyntaxKind.QuestionQuestionToken
-      ? left ?? rpcValue(node.right, env) : left || rpcValue(node.right, env);
+      ? left ?? rpcValue(node.right, env, helper) : left || rpcValue(node.right, env, helper);
+  }
+  if (helper && ts.isCallExpression(node)) {
+    const options = projectRpcOptions(node);
+    return resolveProjectRpc(options.route, rpcValue(options.publicFallback, env, false), options.useBaseRpc, env);
   }
   throw new Error('Selected network URL must be a literal or process.env reference');
 }
 /** Read the project-owned definitions without evaluating the config, plugins or HRE. */
 export function readProjectNetworkSnapshots(root: string, aliases: string[], env: NodeJS.ProcessEnv = process.env): ProjectNetworkSnapshot[] {
-  return parseProjectNetworkSnapshots(readFile(root, 'hardhat.config.ts') ?? '', aliases, env);
+  const source = readFile(root, 'hardhat.config.ts') ?? '';
+  return parseProjectNetworkSnapshots(source, aliases, projectRpcEnvironment(root, source, env));
+}
+/** Public preflight only: RPCs must be in rpc.env or the supplied environment, never .env. */
+export function readPublicProjectNetworkSnapshots(root: string, aliases: string[], env: NodeJS.ProcessEnv = process.env): ProjectNetworkSnapshot[] {
+  const source = readFile(root, 'hardhat.config.ts') ?? '';
+  return parseProjectNetworkSnapshots(source, aliases, projectPublicRpcEnvironment(root, source, env));
 }
 /** Parse one captured project definition without rereading files or evaluating plugins/HRE. */
 export function parseProjectNetworkSnapshots(source: string, aliases: string[], env: NodeJS.ProcessEnv = process.env): ProjectNetworkSnapshot[] {
-  const { networks } = parseProjectConfig(source);
+  const { file, networks } = parseProjectConfig(source);
+  const { helper } = projectRpcSyntax(file);
   return aliases.map(network => {
     validateNetworkAlias(network, 'network', false);
     const selected = networks.get(network);
@@ -96,7 +108,7 @@ export function parseProjectNetworkSnapshots(source: string, aliases: string[],
     if (fields.has('zksync') && fields.get('zksync')!.kind !== ts.SyntaxKind.FalseKeyword) throw new Error('Delivery requires an EVM network');
     const url = fields.get('url');
     if (!url) throw new Error(`Selected network ${network} requires an RPC URL definition`);
-    return { network, chainId: positiveInteger(Number(chainId.text), 'network chainId'), url: rpcValue(url, env) ?? '' };
+    return { network, chainId: positiveInteger(Number(chainId.text), 'network chainId'), url: rpcValue(url, env, helper) ?? '' };
   });
 }
 export function integratedConfig(source: string): string {

package/runtime/delivery/public-calldata.ts

@@ -0,0 +1,74 @@
+/** Public business projection. Internal provenance and runtime progress stay separate. */
+import { immutableDeliveryPlan } from './export';
+import { parseCalldataReviews } from './calldata-review';
+import type { PreparationEntry } from './journal';
+import { expandDeliveryInvocation, readableInvocationAbi, describeDeliveryInvocation, type ExpandedDetails } from './calldata-details';
+import { nonempty, deepFreeze, canonicalJson, semanticHash } from '../workflow/lib/canonicalData';
+import type { WorkflowStep } from '../workflow/lib/parameters';
+
+export { archiveDeliveryCalls } from './calldata-archive';
+export { serializeDeliveryCalls, deliveryCalldataPath } from './calldata-format';
+
+export interface DeliveryCall {
+  chains: string[]; executor: string; to: string; name: string; description: string;
+  abi: string[]; calldata: string; value?: string;
+  details?: ExpandedDetails;
+}
+export interface PublicCalldataInput { plan: unknown; calldata: unknown; operations: readonly WorkflowStep[]; preparations?: unknown }
+/** Frozen parameters independently re-encode and compare before any public projection. */
+export function projectDeliveryCalls(input: PublicCalldataInput): readonly DeliveryCall[] {
+  const plan = immutableDeliveryPlan(input.plan);
+  const reviews = parseCalldataReviews(input.calldata, plan.transactions);
+  const journal=input.preparations??[];
+  const preparations: PreparationEntry[] = Array.isArray(journal)&&!journal.length&&!plan.deploymentBindings.length?[]
+    : (require('./journal') as typeof import('./journal')).parsePreparationJournal(journal, plan.transactions, plan.derivedBindings, {target:plan.target,chainId:plan.chainId,expectedStepIds:plan.deploymentBindings.map(d=>d.stepId)});
+  return deepFreeze(plan.transactions.map((tx, index) => {
+    if (tx.operation !== 0) throw Error('Public calldata supports ordinary CALL only');
+    const binding = plan.transactionBindings[index], operation = plan.operationBindings.find(o => o.stepId === binding.stepId);
+    if (!operation) throw Error('Public calldata operation binding missing');
+    const source = operation.operationId === null ? input.operations.find(s => s.id === operation.sourceStepId)
+      : plan.customBindings.find(s => s.sourceStepId === operation.sourceStepId)?.operations.find(s => s.id === operation.operationId);
+    if (!source) throw Error('Frozen operation intent missing');
+    const call = binding.callIndex === null ? undefined : (source.calls as any[] | undefined)?.[binding.callIndex];
+    const name = nonempty(call?.name ?? source.name, 'operation name');
+    const description = nonempty(call?.description ?? source.description, 'operation description');
+    const invocation = reviews[index].invocation;
+    if (invocation.kind !== 'function') throw Error('Outer public transaction requires function ABI');
+    const entry=preparations.find(p=>p.mappings.some(m=>m.transactionId===tx.transactionId));
+    const details=expandDeliveryInvocation(invocation,tx.to,{name,description},entry);
+    return { chains: [plan.chainId], executor: tx.executor, to: tx.to, name, description:describeDeliveryInvocation(description,invocation),
+      abi: readableInvocationAbi(invocation), calldata: tx.data, ...(BigInt(tx.value) === 0n ? {} : { value: tx.value }),...(details?{details}:{}) };
+  }));
+}
+
+/** Merge matching logical occurrences, never globally deduplicate calldata. */
+export function mergeDeliveryCalls(inputs: readonly PublicCalldataInput[]): readonly DeliveryCall[] {
+  if(!inputs.length)throw Error('At least one independently frozen network is required');
+  const chains=new Set<string>(), sequences:Array<{chain:string;calls:readonly DeliveryCall[];keys:string[]}>=[];
+  const nodes=new Map<string,{call:DeliveryCall;next:Set<string>;incoming:number}>();
+  for(const input of inputs){
+    const plan=immutableDeliveryPlan(input.plan),chain=plan.chainId,calls=projectDeliveryCalls(input);
+    if(chains.has(chain))throw Error('Duplicate chain projection');chains.add(chain);
+    const keys=calls.map((call,index)=>{
+      const binding=plan.transactionBindings[index],operation=plan.operationBindings.find(o=>o.stepId===binding.stepId)!;
+      const {chains:_,...content}=call;
+      const key=semanticHash({logical:[operation.sourceStepId,operation.operationId,binding.role,binding.callIndex],content});
+      const existing=nodes.get(key);
+      if(existing){if(existing.call.chains.includes(chain))throw Error('Duplicate logical occurrence on one chain');existing.call.chains.push(chain);}
+      else nodes.set(key,{call:{...call,chains:[chain]},next:new Set(),incoming:0});
+      return key;
+    });
+    sequences.push({chain,calls,keys});
+    for(let i=1;i<keys.length;i++){const a=nodes.get(keys[i-1])!,b=nodes.get(keys[i])!;if(!a.next.has(keys[i])){a.next.add(keys[i]);b.incoming++;}}
+  }
+  const queue=[...nodes].filter(([,n])=>n.incoming===0).map(([key])=>key),ordered:DeliveryCall[]=[];
+  for(let at=0;at<queue.length;at++){
+    const node=nodes.get(queue[at])!;ordered.push(node.call);
+    for(const key of node.next){const next=nodes.get(key)!;if(--next.incoming===0)queue.push(key);}
+  }
+  // Conflicting cross-chain ordering cannot share occurrences; keep exact per-chain sequences.
+  const result=ordered.length===nodes.size?ordered:sequences.flatMap(s=>s.calls.map(call=>({...call,chains:[s.chain]})));
+  const content=(call:DeliveryCall)=>{const {chains:_,...rest}=call;return rest;};
+  for(const sequence of sequences)if(canonicalJson(result.filter(c=>c.chains.includes(sequence.chain)).map(content))!==canonicalJson(sequence.calls.map(content)))throw Error('Merged calldata changed per-chain order or coverage');
+  return deepFreeze(result);
+}