gate-evm-tools 1.0.31 → 1.2.1

package/runtime/delivery/compiler.ts

@@ -11,6 +11,7 @@ import { getDeployData, type DeployData } from '@openzeppelin/hardhat-upgrades/d
 import { withDefaults } from '@openzeppelin/hardhat-upgrades/dist/utils/options';
 import { validate, solcInputOutputDecoder, getContractNameAndRunValidation, getStorageLayout, getVersion, getUnlinkedBytecode, assertUpgradeSafe, assertStorageUpgradeSafe, getImplementationAddress } from '@openzeppelin/upgrades-core';
 import { strictData } from './data';
+import { compilerExecutionInput } from './execution-identity';
 import { deepFreeze, semanticHash } from '../workflow/lib/canonicalData';
 import { CompilerFiles, regular, relative, sha256, type CompilerPackage, type CompilerResolution } from './compiler-files';
 import { compilerTaskPins, compilerDispatcherPin } from './compiler-pins';
@@ -45,7 +46,7 @@ type SameForkProof = NonNullable<Awaited<ReturnType<NonNullable<GateToolPreparat
 type OwnedInitial = SameForkInitialPreparation & {selection:Selection};
 // Resolve the same core manifest reader used by the actual preparation call site.
 const { readRegisteredTargetUpgradeState, resolveTargetManifestDirectory } = require(path.join(path.dirname(require.resolve('gate-evm-tools/workflow')), '../core/preparation/manifest.js')) as {
-  readRegisteredTargetUpgradeState(input: {root:string; target:string; chainId:number; proxy:string; currentImplementation:string}): HistoricalObservation['state'];
+  readRegisteredTargetUpgradeState(input: {root:string; target:string; chainId:number; proxy:string; currentImplementation:string; proxyKind?:'uups'|'transparent'}): HistoricalObservation['state'];
   resolveTargetManifestDirectory(root:string,target:string):string;
 };
 export interface CompilerEvidence {
@@ -95,7 +96,7 @@ function projection(sourceName: string, contractName: string, output: Json): Gat
     linkReferences: output.evm?.bytecode?.linkReferences ?? {}, deployedLinkReferences: output.evm?.deployedBytecode?.linkReferences ?? {} });
 }
 function stable(e: Omit<CompilerEvidence, 'stableDigest' | 'exactDigest'>): unknown {
-  return { version: e.version, adapter: e.adapter, toolchain: e.toolchain,
+  return { version: e.version, adapter: e.adapter, toolchain: compilerExecutionInput(e.toolchain),
     jobs: e.jobs.map(j => ({ id: j.id, config: j.config, sources: j.sources, main: j.runs[0] })),
     builds: e.builds, artifacts: e.artifacts, selections: e.selections, baselines: e.baselines.map(({ prior, ...b }) => ({ ...b, prior: { stableDigest: prior.stableDigest, selection: prior.selection } })) };
 }
@@ -404,9 +405,9 @@ class CompilerSession {
         origin = {kind:'target-manifest',manifestPolicy:state.paths.manifestDir,manifestDigest:state.digest,proxy:state.proxyEntry,implementationEntry:persistedOZ(state.implementationEntry)};
       } else {
         const initial = this.#sameForkProofs.get(observation.sameFork);
-        if (!initial || request.kind !== 'uups-upgrade' || initial.selection.digest !== prior.selection.digest
-          || !matchesSameForkInitial(initial,request.target,String(chainId),request.proxy,currentImplementation)) throw new Error('Same-fork baseline requires its owned initial preparation and actual deployment observation');
-        origin = {kind:'same-fork',manifestPolicy:resolveTargetManifestDirectory(this.hre.config.paths.root,request.target),proxy:{address:request.proxy.toLowerCase(),kind:'uups'},sameForkBaselineDigest:observation.sameFork.digest,initial:{request:initial.request,plan:initial.plan}};
+        if (!initial || (request.kind !== 'uups-upgrade' && request.kind !== 'transparent-upgrade') || initial.selection.digest !== prior.selection.digest
+          || !matchesSameForkInitial(initial,request.target,String(chainId),request.proxy,currentImplementation,request.proxyKind)) throw new Error('Same-fork baseline requires its owned initial preparation and actual deployment observation');
+        origin = {kind:'same-fork',manifestPolicy:resolveTargetManifestDirectory(this.hre.config.paths.root,request.target),proxy:{address:request.proxy.toLowerCase(),kind:request.proxyKind},sameForkBaselineDigest:observation.sameFork.digest,initial:{request:initial.request,plan:initial.plan}};
       }
       const baseline: Baseline = strictData({ ...origin, target: request.target, chainId, selection:selection.digest, currentImplementation: currentImplementation.toLowerCase(), implementationKey: prior.selection.version.linkedWithoutMetadata, oldLayout: prior.selection.layout, prior: this.priorQualification(prior) });
       if (!this.#baselines.some(b => semanticHash(b) === semanticHash(baseline))) this.#baselines.push(baseline);
@@ -433,7 +434,7 @@ class CompilerSession {
   }
   readonly sameForkBaseline: NonNullable<GateToolPreparationValidation['sameForkBaseline']> = async input => {
     this.assertRegistry();
-    const matches = [...this.#initialPreparations.values()].filter(p => this.#observedInitials.has(p) && matchesSameForkInitial(p,input.request.target,String(input.chainId),input.request.proxy,input.currentImplementation));
+    const matches = [...this.#initialPreparations.values()].filter(p => this.#observedInitials.has(p) && matchesSameForkInitial(p,input.request.target,String(input.chainId),input.request.proxy,input.currentImplementation,input.request.proxyKind));
     if (!matches.length) return undefined;
     if (matches.length !== 1) throw new Error('Ambiguous same-fork initial preparation');
     const actual = await getImplementationAddress(this.#provider,input.request.proxy);
@@ -460,7 +461,7 @@ class CompilerSession {
     }
   };
   preparationSelection(request: Exclude<GateToolPreparationRequestV1, {kind:'create2-deploy'}>, plan: GateToolPreparationPlanV1): Selection {
-    const options = persistedOZ(withDefaults({ kind: 'uups', constructorArgs: request.constructorArgs, ...(request.unsafeAllow ? { unsafeAllow: request.unsafeAllow } : {}) } as Parameters<typeof withDefaults>[0]));
+    const options = persistedOZ(withDefaults({ kind: request.proxyKind, constructorArgs: request.constructorArgs, ...(request.unsafeAllow ? { unsafeAllow: request.unsafeAllow } : {}) } as Parameters<typeof withDefaults>[0]));
     const matches = [...this.#selections.values()].filter(s => s.fqn === `${plan.artifact.sourceName}:${plan.artifact.contractName}` && semanticHash(s.options) === semanticHash(options));
     if (matches.length !== 1) throw new Error('Preparation reuse requires one prior owned qualified OZ selection');
     return matches[0];
@@ -469,7 +470,7 @@ class CompilerSession {
   async observePreparationPlan(request: GateToolPreparationRequestV1, plan: GateToolPreparationPlanV1): Promise<void> {
     try {
       this.assertRegistry();
-      if (request.kind === 'uups-upgrade' && plan.validation.kind === 'uups-upgrade') {
+      if ((request.kind === 'uups-upgrade' || request.kind === 'transparent-upgrade') && (plan.validation.kind === 'uups-upgrade' || plan.validation.kind === 'transparent-upgrade')) {
         const selected = this.preparationSelection(request,plan);
         const chainId = Number(BigInt(await this.#provider.send('eth_chainId')));
         if (!Number.isSafeInteger(chainId) || chainId <= 0 || String(chainId) !== plan.chainId) throw new Error('Preparation baseline chain mismatch');
@@ -480,14 +481,14 @@ class CompilerSession {
           if (!sameFork || sameFork.digest !== plan.validation.sameForkBaselineDigest) throw new Error('Preparation same-fork baseline digest mismatch');
           this.captureBaseline(request,selected,{sameFork,currentImplementation,chainId});
         } else {
-          const state = readRegisteredTargetUpgradeState({root:this.hre.config.paths.root,target:request.target,chainId,proxy:request.proxy,currentImplementation});
+          const state = readRegisteredTargetUpgradeState({root:this.hre.config.paths.root,target:request.target,chainId,proxy:request.proxy,currentImplementation,proxyKind:request.proxyKind});
           if (state.digest !== plan.validation.manifestDigest) throw new Error('Preparation baseline manifest digest mismatch');
           this.assertRegistry();
           this.captureBaseline(request,selected,{state,currentImplementation,chainId});
         }
       }
       this.preparationPlan(request,plan);
-      if (request.kind === 'uups-placeholder-deploy') {
+      if (request.kind === 'uups-placeholder-deploy' || request.kind === 'transparent-deploy') {
         await validatePreparationSemantics(request,plan,name=>this.hre.artifacts.readArtifact(name));
         const selection = this.preparationSelection(request,plan);
         const initial = deepFreeze({request:normalizePreparationRequest(request),plan:strictData(plan),selection});
@@ -503,11 +504,11 @@ class CompilerSession {
     this.assertRegistry();
     if (request.kind === 'create2-deploy') return;
     const selected = this.preparationSelection(request,plan);
-    if (plan.validation.kind === 'uups-upgrade') {
-      if (request.kind !== 'uups-upgrade') throw new Error('Preparation baseline request mismatch');
+    if (plan.validation.kind === 'uups-upgrade' || plan.validation.kind === 'transparent-upgrade') {
+      if ((request.kind !== 'uups-upgrade' && request.kind !== 'transparent-upgrade')) throw new Error('Preparation baseline request mismatch');
       if (sha256(canonicalPreparationJson(selected.layout)) !== plan.validation.newLayoutHash) throw new Error('Preparation selected new layout mismatch');
       const validation = plan.validation;
-      const matches = this.#baselines.filter(b => b.target === request.target && String(b.chainId) === plan.chainId && b.proxy.address.toLowerCase() === request.proxy.toLowerCase()
+      const matches = this.#baselines.filter(b => b.target === request.target && String(b.chainId) === plan.chainId && b.proxy.address.toLowerCase() === request.proxy.toLowerCase() && b.proxy.kind === request.proxyKind
         && b.currentImplementation === validation.currentImplementation.toLowerCase() && b.selection === selected.digest
         && (b.kind === 'target-manifest' ? validation.sameForkBaselineDigest === undefined && b.manifestDigest === validation.manifestDigest
           : validation.manifestDigest === undefined && b.sameForkBaselineDigest === validation.sameForkBaselineDigest));
@@ -680,20 +681,20 @@ export function parseCompilerEvidence(raw: unknown): CompilerEvidence {
     if (prior.baselines.length || prior.selections.length !== 1 || prior.stableDigest !== b.prior.stableDigest || prior.exactDigest !== b.prior.exactDigest || prior.selections[0].digest !== b.prior.selection || prior.selections[0].version.linkedWithoutMetadata !== b.implementationKey) throw new Error('Historical compiler baseline relation mismatch');
     equal(b.oldLayout, prior.selections[0].layout, 'Historical qualified layout');
     assertStorageUpgradeSafe(b.oldLayout as any,selected.layout as any,selected.options as any);
-    if (b.proxy.kind !== 'uups' || !Number.isSafeInteger(b.chainId) || b.chainId <= 0) throw new Error('Historical baseline identity mismatch');
+    if (selected.options.kind !== b.proxy.kind || prior.selections[0].options.kind !== b.proxy.kind || !['uups','transparent'].includes(b.proxy.kind) || !Number.isSafeInteger(b.chainId) || b.chainId <= 0) throw new Error('Historical baseline identity mismatch');
     if (b.kind === 'target-manifest') {
       equal(b.oldLayout, b.implementationEntry.layout, 'Historical manifest layout');
       if (![b.implementationEntry.address, ...(b.implementationEntry.allAddresses ?? [])].some(a => typeof a === 'string' && a.toLowerCase() === b.currentImplementation)) throw new Error('Historical manifest identity mismatch');
     } else {
       const initial = b.initial, selection = prior.selections[0];
       const layoutHash = sha256(canonicalPreparationJson(b.oldLayout));
-      if (!matchesSameForkInitial(initial,b.target,String(b.chainId),b.proxy.address,b.currentImplementation)
-        || sameForkBaselineDigest(initial,layoutHash) !== b.sameForkBaselineDigest || initial.request.kind !== 'uups-placeholder-deploy') throw new Error('Same-fork initial preparation relation mismatch');
+      if (!matchesSameForkInitial(initial,b.target,String(b.chainId),b.proxy.address,b.currentImplementation,b.proxy.kind)
+        || sameForkBaselineDigest(initial,layoutHash) !== b.sameForkBaselineDigest || (initial.request.kind !== 'uups-placeholder-deploy' && initial.request.kind !== 'transparent-deploy')) throw new Error('Same-fork initial preparation relation mismatch');
       const artifact = prior.artifacts.find(a=>a.digest===selection.artifactDigest)!.artifact;
       equal(artifactIdentity(artifact,'evm'),initial.plan.artifact,'Same-fork prior artifact');
       const encodedArgs = new ContractFactory(artifact.abi,artifact.bytecode).interface.encodeDeploy(initial.request.constructorArgs);
       if (encodedArgs !== selection.encodedArgs || getCreate2Address(initial.request.factory,initial.request.implementationSalt,keccak256(concat([selection.linkedBytecode,encodedArgs]))).toLowerCase() !== b.currentImplementation) throw new Error('Same-fork prior constructor/implementation mismatch');
-      equal(persistedOZ(withDefaults({kind:'uups',constructorArgs:initial.request.constructorArgs,...(initial.request.unsafeAllow ? {unsafeAllow:initial.request.unsafeAllow}: {})} as Parameters<typeof withDefaults>[0])),selection.options,'Same-fork prior options');
+      equal(persistedOZ(withDefaults({kind:initial.request.proxyKind,constructorArgs:initial.request.constructorArgs,...(initial.request.unsafeAllow ? {unsafeAllow:initial.request.unsafeAllow}: {})} as Parameters<typeof withDefaults>[0])),selection.options,'Same-fork prior options');
     }
   }
   return deepFreeze(e);

package/runtime/delivery/config.ts

@@ -52,16 +52,39 @@ export function validateDeliveryTarget(input: unknown): DeliveryTarget {
 }
 export function configDocument(root: string): YAML.Document {
   const contents = readFile(root, 'config.yaml');
+  if (contents !== undefined) parseInputDocument(contents, 'yaml');
   const doc = contents === undefined ? new YAML.Document({}) : YAML.parseDocument(contents);
   if (doc.errors.length || !YAML.isMap(doc.contents)) throw new Error('config.yaml must be a valid mapping');
   return doc;
 }
-/** Validate only the selected delivery target. No fallback to dev, legacy environment, or another target. */
+/** Validate the selected target with its facility defaults, never another network or environment. */
 export function loadDeliveryTarget(root: string, network: string, environment?: DeliveryEnvironment): DeliveryTargetConfig {
   const target = parseSelectedTarget(parseInputDocument(readInputBytes(root, 'config.yaml'), 'yaml'), network, environment);
   confinedFile(root, target.openzeppelin.manifestDir, 'directory');
   return target;
 }
+const FACILITY_FIELDS: Record<string, string[]> = {
+  create2: ['scheme', 'factory', 'leadingZeroBytes', 'caller'],
+  uups: ['placeholderImplementation'],
+  multicall: ['controlledMulticall'],
+};
+/** Only public facilities inherit. Environment, finality, roles and manifest policy remain target-owned. */
+function inheritTargetFacilities(configuration: Record<string, unknown>, target: Record<string, unknown>): Record<string, unknown> {
+  const profiles = configuration._profiles === undefined ? {} : object(configuration._profiles, '_profiles', ['baseProfile', 'dev', 'prod']);
+  const selected = target.environment === 'dev' || target.environment === 'prod' ? target.environment : undefined;
+  const layers = [
+    ['baseProfile', profiles.baseProfile],
+    [selected ?? 'environment', selected ? profiles[selected] : undefined],
+  ] as const;
+  const defaults = layers.map(([name, value]) => value === undefined ? {} : object(value, `_profiles.${name}`, Object.keys(FACILITY_FIELDS)));
+  const result = { ...target };
+  for (const [facility, fields] of Object.entries(FACILITY_FIELDS)) {
+    const sections = [...defaults, target].filter(layer => layer[facility] !== undefined)
+      .map(layer => object(layer[facility], facility, fields));
+    if (sections.length) result[facility] = Object.assign({}, ...sections);
+  }
+  return result;
+}
 function parseSelectedTarget(document: unknown, network: string, environment?: DeliveryEnvironment): DeliveryTargetConfig {
   validateNetworkAlias(network, 'network', false);
   const configuration = object(document, 'config.yaml');
@@ -70,7 +93,7 @@ function parseSelectedTarget(document: unknown, network: string, environment?: D
   if (environment && value.environment !== environment) throw new Error(`Selected target ${network} environment mismatch`);
   const manifest = object(value.openzeppelin, 'openzeppelin');
   validateManifestPolicy(value.environment, manifest.manifestDir, 'delivery');
-  const { network: _network, ...validated } = validateDeliveryTarget({ ...value, network });
+  const { network: _network, ...validated } = validateDeliveryTarget({ ...inheritTargetFacilities(configuration, value), network });
   return deepFreeze(validated) as DeliveryTargetConfig;
 }
 /** Pure projection from the owner's exact captured buffers; creates no input/receipt authority. */

package/runtime/delivery/configuration-definition.ts

@@ -4,10 +4,15 @@ import { parseProjectConfig } from './project';
 import { inputDigest } from './input-files';
 import { validateNetworkAlias } from './policy';
 import { deepFreeze } from '../workflow/lib/canonicalData';
+import { projectRpcSyntax, projectRpcOptions, resolveProjectRpc } from './project-rpc';
+// dist-runtime has its own CommonJS boundary; resolve our built helper by location.
+const resolveHardhatAccounts: typeof import('gate-evm-tools/custody').resolveHardhatAccounts =
+  require('../../dist-cjs/custody/credential.js').resolveHardhatAccounts;
 
 type Data = Record<string, any>;
 export type SecretDefinition = {kind:'literal'; definitionHash:string} | {kind:'env'; name:string}
-  | {kind:'fallback'; operator:'||'|'??'; left:SecretDefinition; right:SecretDefinition};
+  | {kind:'fallback'; operator:'||'|'??'; left:SecretDefinition; right:SecretDefinition}
+  | {kind:'project-rpc'; route:string; useBaseRpc:boolean; base:{kind:'env';name:'BASE_RPC_URI'}; publicFallback:SecretDefinition};
 const fail = (): never => { throw new Error('Unsupported static delivery configuration'); };
 const literalDefinition = (value:string):SecretDefinition => ({kind:'literal',definitionHash:inputDigest(`gate-delivery-secret-definition@1\0${value}`)});
 function unwrap(n:ts.Expression):ts.Expression { while(ts.isParenthesizedExpression(n)||ts.isAsExpression(n)||ts.isSatisfiesExpression(n)) n=n.expression; return n; }
@@ -45,8 +50,21 @@ function headers(n:ts.Expression,env:NodeJS.ProcessEnv):{value:Data;definition:a
   for(const [key,node] of fields(n)){const item=secret(node,env);value[key]=item.value;definition.push({name:literalDefinition(key),value:item.definition});}
   return {value,definition};
 }
-function accounts(n:ts.Expression,local:boolean,env:NodeJS.ProcessEnv):{value:any;definition:any} {
+function networkUrl(n:ts.Expression,env:NodeJS.ProcessEnv,helper:boolean):ReturnType<typeof secret> {
   n=unwrap(n);
+  if(helper&&ts.isCallExpression(n)){
+    const {route,useBaseRpc,publicFallback}=projectRpcOptions(n),fallback=secret(publicFallback,env);
+    return {value:resolveProjectRpc(route,fallback.value,useBaseRpc,env),definition:{kind:'project-rpc',route,useBaseRpc,base:{kind:'env',name:'BASE_RPC_URI'},publicFallback:fallback.definition}};
+  }
+  return secret(n,env);
+}
+function accounts(n:ts.Expression,local:boolean,env:NodeJS.ProcessEnv,credentialResolver:boolean):{value:any;definition:any} {
+  n=unwrap(n);
+  if(!local&&credentialResolver&&ts.isCallExpression(n)&&ts.isIdentifier(n.expression)&&n.expression.text==='resolveHardhatAccounts'&&n.arguments.length===1&&!n.typeArguments){
+    const credential=secret(n.arguments[0],env);
+    if(credential.definition.kind!=='env'||credential.definition.name!=='PRIVATE_KEY')return fail();
+    return {value:resolveHardhatAccounts(credential.value),definition:{kind:'wallet-credential',credential:credential.definition}};
+  }
   if(ts.isStringLiteral(n)&&n.text==='remote'&&!local)return {value:'remote',definition:{kind:'remote'}};
   if(ts.isArrayLiteralExpression(n)){
     const entries=n.elements.map(e=>{
@@ -71,12 +89,12 @@ function accounts(n:ts.Expression,local:boolean,env:NodeJS.ProcessEnv):{value:an
 const common=['chainId','from','gas','gasPrice','gasMultiplier'];
 const localFields=[...common,'initialBaseFeePerGas','hardfork','mining','accounts','blockGasLimit','minGasPrice','throwOnTransactionFailures','throwOnCallFailures','allowUnlimitedContractSize','allowBlocksWithSameTimestamp','initialDate','loggingEnabled','forking','coinbase','chains','enableTransientStorage','enableRip7212'];
 const httpFields=[...common,'url','timeout','httpHeaders','accounts'];
-function network(n:ts.Expression,local:boolean,env:NodeJS.ProcessEnv):{value:Data;definition:Data} {
+function network(n:ts.Expression,local:boolean,env:NodeJS.ProcessEnv,helper:boolean,credentialResolver:boolean):{value:Data;definition:Data} {
   const value:Data={},definition:Data={};
   for(const [key,node] of fields(n)){
     if(!(local?localFields:httpFields).includes(key))return fail();
-    if(key==='url'){const s=secret(node,env);value[key]=s.value;definition[key]=s.definition;}
-    else if(key==='accounts'){const a=accounts(node,local,env);value[key]=a.value;definition[key]=a.definition;}
+    if(key==='url'){const s=networkUrl(node,env,helper);value[key]=s.value;definition[key]=s.definition;}
+    else if(key==='accounts'){const a=accounts(node,local,env,credentialResolver);value[key]=a.value;definition[key]=a.definition;}
     else if(key==='httpHeaders'){const h=headers(node,env);value[key]=h.value;definition[key]=h.definition;}
     else if(key==='forking'){
       const v:Data={},d:Data={};for(const [k,x] of fields(node)){
@@ -109,13 +127,22 @@ export function parseConfigurationDefinition(bytes:Buffer,selected:string,env:No
   try {
     validateNetworkAlias(selected,'network',false);if(selected==='hardhat')fail();
     const {file,fields:top,networks}=parseProjectConfig(new TextDecoder('utf-8',{fatal:true}).decode(bytes));
+    const rpc=projectRpcSyntax(file);
     const plugins:string[]=[];
+    let credentialResolver=false;
     const exported=unwrap(file.statements.filter(ts.isExportAssignment)[0].expression);
     for(const statement of file.statements){
+      if(rpc.statements.has(statement))continue;
       if(ts.isImportDeclaration(statement)){
         if(!ts.isStringLiteral(statement.moduleSpecifier)||statement.attributes)fail();
         const name=(statement.moduleSpecifier as ts.StringLiteral).text;
-        if(statement.importClause){if(name!=='hardhat/config'||!statement.importClause.isTypeOnly||statement.importClause.name||!statement.importClause.namedBindings||!ts.isNamedImports(statement.importClause.namedBindings)||statement.importClause.namedBindings.elements.some(e=>e.name.text!=='HardhatUserConfig'||e.propertyName))fail();}
+        if(statement.importClause){
+          const clause=statement.importClause;
+          if(name==='gate-evm-tools/custody'){
+            if(credentialResolver||clause.isTypeOnly||clause.name||!clause.namedBindings||!ts.isNamedImports(clause.namedBindings)||clause.namedBindings.elements.length!==1||clause.namedBindings.elements[0].name.text!=='resolveHardhatAccounts'||clause.namedBindings.elements[0].propertyName||clause.namedBindings.elements[0].isTypeOnly)fail();
+            credentialResolver=true;
+          }else if(name!=='hardhat/config'||!clause.isTypeOnly||clause.name||!clause.namedBindings||!ts.isNamedImports(clause.namedBindings)||clause.namedBindings.elements.some(e=>e.name.text!=='HardhatUserConfig'||e.propertyName))fail();
+        }
         else {if(!['gate-evm-tools/delivery-hardhat','@nomicfoundation/hardhat-ethers','@nomicfoundation/hardhat-chai-matchers','@openzeppelin/hardhat-upgrades'].includes(name)||plugins.includes(name))fail();plugins.push(name);}
       }else if(ts.isVariableStatement(statement)){if(!ts.isIdentifier(exported)||statement.declarationList.declarations[0]?.name.getText(file)!==exported.text||statement.modifiers?.length||statement.declarationList.declarations.length!==1||!(statement.declarationList.flags&ts.NodeFlags.Const)||file.statements.filter(ts.isVariableStatement).length!==1)fail();}
       else if(!ts.isExportAssignment(statement))fail();
@@ -126,7 +153,7 @@ export function parseConfigurationDefinition(bytes:Buffer,selected:string,env:No
     if(!('solidity'in userConfig))fail();compiler(userConfig.solidity);
     if(userConfig.paths){keys(userConfig.paths,['sources','cache','artifacts','tests']);for(const value of Object.values(userConfig.paths))if(typeof value!=='string'||!value||value.startsWith('/')||value.includes('\\')||value.split('/').some(p=>!p||p==='..'))fail();}
     if(userConfig.defaultNetwork!==undefined)validateNetworkAlias(userConfig.defaultNetwork,'defaultNetwork');
-    userConfig.networks={};for(const [name,node] of networks){validateNetworkAlias(name,'network');const n=network(node,name==='hardhat',env);userConfig.networks[name]=n.value;definition.networks[name]=n.definition;}
+    userConfig.networks={};for(const [name,node] of networks){validateNetworkAlias(name,'network');const n=network(node,name==='hardhat',env,rpc.helper,credentialResolver);userConfig.networks[name]=n.value;definition.networks[name]=n.definition;}
     if(!userConfig.networks[selected])fail();
     return {userConfig,definition:deepFreeze(definition),plugins,explicitDate:Object.hasOwn(userConfig.networks.hardhat??{},'initialDate')};
   }catch{throw new Error('Unsupported static delivery configuration');}

package/runtime/delivery/configuration.ts

@@ -1,6 +1,6 @@
 /** Owned configuration/runtime contributor. It grants no planning, signing or execution authority. */
 import path from 'node:path';
-import {projectRoot,parseCoreMarker} from './project-files';
+import {projectRoot,parseDeliveryProjectMarker} from './project-files';
 import {readInputBytes,inputDigest} from './input-files';
 import {parseConfigurationDefinition} from './configuration-definition';
 import {observeConfigurationHre} from './configuration-hre';
@@ -8,6 +8,8 @@ import {RuntimeObservation,type RuntimeEvidence} from './configuration-runtime';
 import {openPlanCodecObservation,type PlanCodecObservation} from './codec';
 import {deepFreeze,semanticHash,exactObject} from '../workflow/lib/canonicalData';
 import type {DeepReadonly} from './source';
+import {projectRpcEnvironment} from './project-rpc';
+import {runtimeExecutionInput} from './execution-identity';
 
 export interface DeliveryConfigurationOptions {workspaceRoot:string;projectRoot:string;network:string}
 export interface DeliveryConfigurationEvidence {
@@ -34,8 +36,9 @@ export function openDeliveryConfiguration(raw:DeliveryConfigurationOptions):Deli
     if(path.resolve(process.cwd())!==root)throw new Error();
     const config=readInputBytes(root,'hardhat.config.ts'),marker=readInputBytes(root,'.gate-template.json');
     // Marker describes generation provenance; current source is independently observed.
-    parseCoreMarker(marker);
-    const parsed=parseConfigurationDefinition(config,raw.network);
+    parseDeliveryProjectMarker(marker);
+    const parse=(bytes:Buffer)=>parseConfigurationDefinition(bytes,raw.network,projectRpcEnvironment(root,bytes.toString('utf8'),process.env));
+    const parsed=parse(config);
     runtime=new RuntimeObservation(root);codec=openPlanCodecObservation();
     const hre=observeConfigurationHre(root,raw.network,parsed,runtime.files);
     const files=[{path:'hardhat.config.ts',digest:inputDigest(config)},{path:'.gate-template.json',digest:inputDigest(marker)}];
@@ -45,14 +48,14 @@ export function openDeliveryConfiguration(raw:DeliveryConfigurationOptions):Deli
       const compiler=ownedDeliveryCompiler(hre.hre)?.evidence();
       const body={version:1 as const,files,configuration:hre.configuration,runtime:runtime!.observe(),codec:codec!.snapshot,
         compiler:compiler?{adapter:compiler.adapter,stableDigest:compiler.stableDigest,exactDigest:compiler.exactDigest}:null};
-      return deepFreeze({...body,configurationRuntimeHash:semanticHash({...body,compiler:compiler?{adapter:compiler.adapter,stableDigest:compiler.stableDigest}:null})});
+      return deepFreeze({...body,configurationRuntimeHash:semanticHash({...body,runtime:runtimeExecutionInput(body.runtime),compiler:compiler?{adapter:compiler.adapter,stableDigest:compiler.stableDigest}:null})});
     };
     const snapshot=observe();let status:'open'|'sealed'|'failed'|'closed'='open';
     const close=()=>{runtime!.close();codec!.close();};
     const check=()=>{
       const current=readInputBytes(root,'hardhat.config.ts');
       if(inputDigest(current)!==files[0].digest||inputDigest(readInputBytes(root,'.gate-template.json'))!==files[1].digest)throw new Error();
-      hre.assertUnchanged(parseConfigurationDefinition(current,raw.network));codec!.assertUnchanged();runtime!.assertUnchanged();
+      hre.assertUnchanged(parse(current));codec!.assertUnchanged();runtime!.assertUnchanged();
     };
     const assertOpen=()=>{if(status!=='open')throw new Error('Delivery configuration session closed');};
     return Object.freeze({snapshot,

package/runtime/delivery/contract-source.ts

@@ -0,0 +1,112 @@
+/** Bind actual project Solidity inputs to their last source-changing Git commit. */
+import fs from 'node:fs';
+import path from 'node:path';
+import { createHash } from 'node:crypto';
+import { spawnSync } from 'node:child_process';
+import { readInputBytes, inputDigest } from './input-files';
+import { confinedFile } from './project-files';
+import { portablePath } from './protocol';
+import { deepFreeze, semanticHash } from '../workflow/lib/canonicalData';
+import type { DeliveryAggregate } from './aggregate';
+
+export interface ContractSourceIdentity {
+  version: 1;
+  commit: string;
+  projectPath: string;
+  sourcesDirectory: string;
+  files: Array<{ path: string; digest: string }>;
+  sourceHash: string;
+}
+type TreeEntry = { mode: string; oid: string };
+const portable = (value: string) => value.split(path.sep).join('/');
+function git(root: string, args: string[]): string {
+  // These reads must inspect this worktree, including its own index.
+  const env = Object.fromEntries(Object.entries(process.env).filter(([key]) => !key.startsWith('GIT_')));
+  const result = spawnSync('git', ['--no-optional-locks', '-c', 'core.fsmonitor=false', ...args], {
+    cwd: root, env, encoding: 'utf8', timeout: 15000, maxBuffer: 32 * 1024 * 1024,
+  });
+  if (result.error || result.status !== 0) throw Error('Deployment release requires a Git repository with committed contract sources');
+  return result.stdout;
+}
+function sourceFiles(root: string, directory: string): string[] {
+  const files: string[] = [];
+  const visit = (relative: string) => {
+    const absolute = relative === '.' ? root : confinedFile(root, relative, 'directory');
+    if (!fs.existsSync(absolute)) return;
+    for (const entry of fs.readdirSync(absolute, { withFileTypes: true })) {
+      if (['.git', 'node_modules', '.gate-delivery'].includes(entry.name)) continue;
+      const file = relative === '.' ? entry.name : `${relative}/${entry.name}`;
+      if (entry.isSymbolicLink()) throw Error('Contract source directory cannot contain symlinks');
+      if (entry.isDirectory()) visit(file);
+      else if (entry.isFile() && file.endsWith('.sol')) files.push(file);
+    }
+  };
+  visit(directory);
+  return files;
+}
+function tree(root: string, commit: string, scopes: string[], wanted: (file: string) => boolean): Map<string, TreeEntry> {
+  const entries = new Map<string, TreeEntry>();
+  for (const row of git(root, ['ls-tree', '-r', '-z', '--full-tree', commit, '--', ...scopes]).split('\0').filter(Boolean)) {
+    const tab = row.indexOf('\t'), file = row.slice(tab + 1), [mode, kind, oid] = row.slice(0, tab).split(' ');
+    if (!wanted(file)) continue;
+    if (kind !== 'blob' || !['100644', '100755'].includes(mode)) throw Error('Contract sources must be regular committed files');
+    entries.set(file, { mode, oid });
+  }
+  return entries;
+}
+/** Called only with the collector's aggregate; no caller-selected Git reference is accepted. */
+export function captureCommittedContractSource(root: string, aggregate: DeliveryAggregate): Readonly<ContractSourceIdentity> {
+  root = fs.realpathSync(root);
+  const configurations = aggregate.inputs.targets.map(target => target.configuration.configuration.paths?.sources);
+  const directory = configurations[0];
+  if (typeof directory !== 'string' || configurations.some(value => value !== directory)) throw Error('Missing or inconsistent compiled contract source directory');
+  if (directory !== '.') portablePath(directory, 'contract sources directory');
+  const compiled = new Map<string, string>();
+  for (const target of aggregate.inputs.targets) for (const job of target.compiler.jobs) for (const source of job.sources) {
+    if (source.package !== null) continue;
+    portablePath(source.path, 'compiled contract source');
+    if (compiled.has(source.path) && compiled.get(source.path) !== source.digest) throw Error('Conflicting compiled contract sources');
+    compiled.set(source.path, source.digest);
+  }
+  if (!compiled.size) throw Error('Deployment release requires compiled project contract sources');
+  const repo = fs.realpathSync(git(root, ['rev-parse', '--show-toplevel']).trim());
+  const relative = path.relative(repo, root);
+  if (relative.startsWith('..') || path.isAbsolute(relative)) throw Error('Project is outside its contract Git repository');
+  const projectPath = portable(relative) || '.', prefix = relative ? `${portable(relative)}/` : '';
+  const sourceScope = directory === '.' ? prefix.slice(0, -1) || '.' : `${prefix}${directory}`;
+  const paths = new Set([...sourceFiles(root, directory), ...compiled.keys()]);
+  const explicit = new Set([...compiled.keys()].map(file => prefix + file));
+  const wanted = (file: string) => explicit.has(file) || file.endsWith('.sol') && (sourceScope === '.' || file.startsWith(sourceScope + '/'));
+  const scopes = [...new Set([sourceScope, ...explicit])].map(file => `:(literal)${file}`);
+  const committed = tree(repo, 'HEAD', scopes, wanted);
+  const index = new Map<string, TreeEntry>();
+  for (const row of git(repo, ['ls-files', '--stage', '-z', '--', ...scopes]).split('\0').filter(Boolean)) {
+    const tab = row.indexOf('\t'), file = row.slice(tab + 1), [mode, oid, stage] = row.slice(0, tab).split(' ');
+    if (!wanted(file)) continue;
+    if (stage !== '0') throw Error('Contract sources have unresolved Git conflicts');
+    index.set(file, { mode, oid });
+  }
+  const uncommitted = () => { throw Error('Contract sources have uncommitted, staged, untracked or deleted files; commit contract changes before freezing a deployment release'); };
+  if (committed.size !== paths.size || index.size !== committed.size) uncommitted();
+  const format = git(repo, ['rev-parse', '--show-object-format']).trim();
+  if (!['sha1', 'sha256'].includes(format)) throw Error('Unsupported contract Git object format');
+  const files = [...paths].sort().map(file => {
+    const entry = committed.get(prefix + file), staged = index.get(prefix + file);
+    if (!entry || !staged || entry.mode !== staged.mode || entry.oid !== staged.oid) uncommitted();
+    let bytes: Buffer;
+    try { bytes = readInputBytes(root, file); } catch { return uncommitted(); }
+    const oid = createHash(format).update(`blob ${bytes.length}\0`).update(bytes).digest('hex');
+    if (oid !== entry!.oid) uncommitted();
+    const digest = inputDigest(bytes);
+    if (compiled.has(file) && compiled.get(file) !== digest) throw Error('Contract source changed after deployment qualification');
+    return { path: file, digest };
+  });
+  // Ignore script/documentation commits, while retaining source additions and deletions.
+  const glob = sourceScope === '.' ? '**/*.sol' : `${sourceScope}/**/*.sol`;
+  const commit = git(repo, ['log', '-1', '--format=%H', '--first-parent', '--full-history', 'HEAD', '--', `:(glob)${glob}`, ...[...explicit].map(file => `:(literal)${file}`)]).trim();
+  if (!/^(?:[a-f0-9]{40}|[a-f0-9]{64})$/.test(commit)) throw Error('No committed contract source version found');
+  const version = tree(repo, commit, scopes, wanted);
+  if (version.size !== committed.size || [...committed].some(([file, entry]) => version.get(file)?.oid !== entry.oid)) throw Error('Contract commit does not reproduce current contract sources');
+  return deepFreeze({ version: 1 as const, commit, projectPath, sourcesDirectory: directory, files,
+    sourceHash: semanticHash({ sourcesDirectory: directory, files }) });
+}

package/runtime/delivery/custom-format.ts

@@ -94,13 +94,16 @@ function proxy(v: unknown, deploying: boolean): void {
       "initializer",
       "unsafeAllow",
       "constructorArgs",
+      "adminOwner",
       ...(deploying ? [] : ["address", "name", "contract"]),
     ],
     [],
     "proxy"
   );
-  if (p.kind !== undefined && p.kind !== "uups")
-    throw new Error("Only UUPS proxy supported");
+  if (p.kind !== undefined && p.kind !== "uups" && p.kind !== "transparent")
+    throw new Error("Unsupported proxy kind");
+  if(p.kind === "transparent") {if(p.adminOwner === undefined)throw Error("Transparent proxy requires explicit adminOwner");address(p.adminOwner,"proxy.adminOwner");}
+  else if(p.adminOwner !== undefined)throw Error("Only Transparent proxy accepts adminOwner");
   if (p.initializer !== undefined && p.initializer !== false)
     string(p.initializer, "initializer");
   if (p.constructorArgs !== undefined)
@@ -130,6 +133,8 @@ export function parseNativeOperation(raw: unknown): WorkflowStep {
     [
       "id",
       "kind",
+      "name",
+      "description",
       "contract",
       "abi",
       "address",
@@ -159,6 +164,8 @@ export function parseNativeOperation(raw: unknown): WorkflowStep {
   const keys = [
     "id",
     "kind",
+    "name",
+    "description",
     "contract",
     ...(kind === "deploy"
       ? [
@@ -175,6 +182,7 @@ export function parseNativeOperation(raw: unknown): WorkflowStep {
       : ["abi", "address", "deployment", "saveAs", "calls"]),
   ];
   record(base, keys, ["id", "kind", "contract"], "operation");
+  for (const key of ["name", "description"]) if (base[key] !== undefined) string(base[key], key);
   refs(base);
   for (const key of ["abi", "deployment", "saveAs"])
     if (base[key] !== undefined) string(base[key], key);
@@ -220,6 +228,10 @@ export function parseNativeOperation(raw: unknown): WorkflowStep {
     if (base.args !== undefined) array(base.args, "constructor args");
     if (base.proxy !== undefined) {
       proxy(base.proxy, true);
+      if((base.proxy as Record<string,unknown>).kind === 'transparent'){
+        const p=base.proxy as Record<string,unknown>;
+        if(base.upgradeableStrategy!=='transparent-proxy'||base.firstUpgrade!==undefined||p.initializer===undefined)throw Error('Transparent deployment requires transparent-proxy strategy, explicit initializer and no firstUpgrade');
+      } else {
       if (
         (base.proxy as Record<string, unknown>).initializer !== false ||
         base.upgradeableStrategy !== "uups-placeholder-proxy"
@@ -251,6 +263,7 @@ export function parseNativeOperation(raw: unknown): WorkflowStep {
       )
         throw new Error("Invalid unsafeAllow");
       if (first.call !== undefined) upgradeCall(first.call);
+      }
     } else if (
       base.firstUpgrade !== undefined ||
       base.upgradeableStrategy !== undefined
@@ -261,8 +274,9 @@ export function parseNativeOperation(raw: unknown): WorkflowStep {
     if (base.proxy !== undefined) proxy(base.proxy, false);
     else if (base.address === undefined)
       throw new Error("Upgrade requires proxy");
-    if (base.proxyKind !== undefined && base.proxyKind !== "uups")
-      throw new Error("Only UUPS upgrade supported");
+    if (base.proxyKind !== undefined && base.proxyKind !== "uups" && base.proxyKind !== "transparent")
+      throw new Error("Unsupported proxy upgrade kind");
+    if(base.proxyKind === "transparent" && (!base.proxy || typeof base.proxy !== "object" || (base.proxy as Record<string,unknown>).kind!=="transparent"))throw Error("Transparent upgrade requires explicit proxy object and adminOwner");
     if (base.constructorArgs !== undefined)
       array(base.constructorArgs, "constructorArgs");
     if (base.call !== undefined) upgradeCall(base.call);
@@ -275,12 +289,13 @@ export function parseNativeOperation(raw: unknown): WorkflowStep {
         kind === "check"
           ? ["method", "args", "expect"]
           : kind === "call"
-          ? ["method", "args", "value"]
+          ? ["method", "args", "value", "name", "description"]
           : ["method", "args"],
         kind === "check" ? ["method", "expect"] : ["method"],
         "call"
       );
       method(c.method);
+      for (const key of ["name", "description"]) if (c[key] !== undefined) string(c[key], key);
       if (c.args !== undefined) array(c.args, "call args");
       if (c.value !== undefined) quantity(c.value);
     }

package/runtime/delivery/development-inputs.ts

@@ -0,0 +1,42 @@
+/** One immutable copy of the original development preparation, reused by release history. */
+import fs from 'node:fs';
+import path from 'node:path';
+import {randomUUID} from 'node:crypto';
+import {canonicalJson} from '../workflow/lib/canonicalData';
+import {developmentPath,byteHash} from './materialization';
+import {readInputBytes} from './input-files';
+import {projectRoot} from './project-files';
+import {parseDeliveryPlan} from './plan';
+import {safeId} from './protocol';
+import type {DeliveryAggregate,DeliveryAggregateOptions} from './aggregate';
+
+/** Publish complete bytes without replacing another writer's immutable file. */
+export function writeImmutableDeliveryFile(root:string,relative:string,bytes:Buffer):{path:string;sha256:string} {
+ const file=developmentPath(root,relative);
+ const existing=()=>{if(!readInputBytes(root,relative).equals(bytes))throw Error(`Immutable delivery file conflict: ${relative}`);};
+ if(fs.existsSync(file)){existing();return {path:relative,sha256:byteHash(bytes)};}
+ fs.mkdirSync(path.dirname(file),{recursive:true,mode:0o700});
+ const temporary=`${file}.${randomUUID()}.tmp`,fd=fs.openSync(temporary,'wx',0o600);
+ try{fs.writeFileSync(fd,bytes);fs.fsyncSync(fd);}finally{fs.closeSync(fd);}
+ try{
+  try{fs.linkSync(temporary,file);}catch(error){if((error as NodeJS.ErrnoException).code!=='EEXIST')throw error;existing();}
+ }finally{fs.unlinkSync(temporary);}
+ const directory=fs.openSync(path.dirname(file),'r');try{fs.fsyncSync(directory);}finally{fs.closeSync(directory);}
+ return {path:relative,sha256:byteHash(bytes)};
+}
+
+export function persistDevelopmentInputs(input:{root:string;source:DeliveryAggregateOptions;aggregate:DeliveryAggregate}):{sourcePath:string;aggregatePath:string} {
+ const root=fs.realpathSync(input.root),{source,aggregate}=input,plan=parseDeliveryPlan(aggregate.collections[0]?.plan);
+ if(source.selection!=='development'||source.targets.length!==1||aggregate.collections.length!==1||plan.environment!=='dev'
+  ||projectRoot(source.workspaceRoot,source.projectRoot)!==root||source.targets[0].executionId!==plan.executionId||source.targets[0].request.network!==plan.target)
+  throw Error('Development inputs require the original single-target preparation');
+ const id=safeId(plan.executionId,'executionId'),base=`.gate-delivery/development/${id}`;
+ const sourcePath=`${base}.source.json`,aggregatePath=`${base}.aggregate.json`;
+ // Check both existing inputs before publishing either file.
+ const entries:[[string,unknown],[string,unknown]]=[[sourcePath,source],[aggregatePath,aggregate]];
+ for(const [file,value]of entries)if(fs.existsSync(developmentPath(root,file))&&canonicalJson(JSON.parse(readInputBytes(root,file).toString()))!==canonicalJson(value))
+  throw Error(`Immutable delivery file conflict: ${file}`);
+ // Existing preparation bytes remain authoritative, including their original JSON formatting.
+ for(const [file,value]of entries)if(!fs.existsSync(developmentPath(root,file)))writeImmutableDeliveryFile(root,file,Buffer.from(canonicalJson(value)+'\n'));
+ return {sourcePath,aggregatePath};
+}