feat(operations-gen): add zkSync bytecode support to EVM deploy generation

Enable operations-gen to wire zkSync VM deploy bytecode into generated Deploy
operations via zksync_bytecode and zksync_bindings_package config fields.

Author: graham-chainlink

.changeset/clear-beans-deny.md

@@ -0,0 +1,5 @@
+---
+"operations-gen": minor
+---
+
+feat: Add zkSync VM bytecode support to operations-gen. Generated Deploy operations can now include `ZkSyncVM` bytecode via `zksync_bytecode` and `zksync_bindings_package` config fields.

tools/operations-gen/README.md

@@ -136,6 +136,7 @@ contracts:
 | `version`                  | Yes      | Config schema version                                                                                                                                       |
 | `chain_family`             | No       | Target chain family. Only `"evm"` is supported. Defaults to `"evm"`.                                                                                        |
 | `input.gobindings_package` | No       | Parent Go import path or relative filesystem path containing versioned abigen packages. Used to derive contract bindings as `<input.gobindings_package>/<version_path>/<package_name>`. |
+| `input.zksync_bindings_package` | No | Default Go import path or relative filesystem path for zkSync VM deploy bytecode. Used when a contract sets `zksync_bytecode` to a symbol only. |
 | `output.base_path`         | Yes      | Root directory where generated files are written. Relative to the config file.                                                                              |
 
 ### Contract fields
@@ -147,7 +148,8 @@ contracts:
 | `gobindings_package` | No       | Optional full Go import path or relative filesystem path override for this contract's abigen-generated bindings package. Required only when `input.gobindings_package` is not set. |
 | `package_name`       | No       | Override the generated Go package name. Defaults to `snake_case(contract_name)`.                                                                       |
 | `version_path`       | No       | Override the directory path derived from the version. Defaults to `v{major}_{minor}_{patch}`.                                                          |
-| `omit_deploy`        | No       | Skip generation of the `Deploy` operation and bytecode constant. Defaults to `false`.                                                                  |
+| `omit_deploy`        | No       | Skip generation of the `Deploy` operation and bytecode constant. Defaults to `false`. Cannot be combined with `zksync_bytecode`.                                                                  |
+| `zksync_bytecode`    | No       | zkSync VM deploy bytecode symbol, or `{package, symbol}`. Package defaults to `input.zksync_bindings_package`, then the contract's `gobindings_package`. |
 
 ### Function access control
 

tools/operations-gen/generate/templates/evm/operations.tmpl

@@ -23,6 +23,9 @@ import (
 	cld_ops "github.com/smartcontractkit/chainlink-deployments-framework/operations"
 {{- end}}
 	gobindings "{{.GobindingsImport}}"
+{{- if and .ZksyncBytecodeSymbol (not .ZksyncBytecodeUseGobindings)}}
+	zkbindings "{{.ZksyncBytecodeImport}}"
+{{- end}}
 )
 
 var ContractType cldf_deployment.ContractType = "{{.ContractType}}"
@@ -61,6 +64,9 @@ var Deploy = contract.NewDeploy(contract.DeployParams[ConstructorArgs]{
 	BytecodeByTypeAndVersion: map[string]contract.Bytecode{
 		cldf_deployment.NewTypeAndVersion(ContractType, *Version).String(): {
 			EVM: common.FromHex(gobindings.{{.ContractType}}MetaData.Bin),
+{{- if .ZksyncBytecodeSymbol}}
+			ZkSyncVM: {{if .ZksyncBytecodeUseGobindings}}gobindings{{else}}zkbindings{{end}}.{{.ZksyncBytecodeSymbol}},
+{{- end}}
 		},
 	},
 })

tools/operations-gen/internal/families/evm/codegen.go

@@ -13,19 +13,22 @@ import (
 // ---- Template data (EVM-specific) ----
 
 type templateData struct {
-	PackageName       string
-	PackageNameHyphen string
-	ContractType      string
-	Version           string
-	GobindingsImport  string
-	NeedsBigInt       bool
-	HasWriteOps       bool
-	OmitDeploy        bool
-	Constructor       *constructorData
-	StructDefs        []structDefData
-	ArgStructs        []argStructData
-	Operations        []OperationData
-	ContractMethods   []contractMethodData
+	PackageName                 string
+	PackageNameHyphen           string
+	ContractType                string
+	Version                     string
+	GobindingsImport            string
+	ZksyncBytecodeSymbol        string
+	ZksyncBytecodeImport        string
+	ZksyncBytecodeUseGobindings bool
+	NeedsBigInt                 bool
+	HasWriteOps                 bool
+	OmitDeploy                  bool
+	Constructor                 *constructorData
+	StructDefs                  []structDefData
+	ArgStructs                  []argStructData
+	Operations                  []OperationData
+	ContractMethods             []contractMethodData
 }
 
 type constructorData struct {
@@ -84,13 +87,16 @@ func generateOperationsFile(info *ContractInfo, tmpl *template.Template) error {
 
 func prepareTemplateData(info *ContractInfo) templateData {
 	data := templateData{
-		PackageName:       info.PackageName,
-		PackageNameHyphen: toKebabCase(info.PackageName),
-		ContractType:      info.Name,
-		Version:           info.Version,
-		GobindingsImport:  info.GobindingsPackage,
-		NeedsBigInt:       ChecksNeedsBigInt(info),
-		OmitDeploy:        info.OmitDeploy,
+		PackageName:                 info.PackageName,
+		PackageNameHyphen:           toKebabCase(info.PackageName),
+		ContractType:                info.Name,
+		Version:                     info.Version,
+		GobindingsImport:            info.GobindingsPackage,
+		ZksyncBytecodeSymbol:        info.ZksyncBytecodeSymbol,
+		ZksyncBytecodeImport:        info.ZksyncBytecodePackage,
+		ZksyncBytecodeUseGobindings: info.ZksyncBytecodeSymbol != "" && info.ZksyncBytecodePackage == info.GobindingsPackage,
+		NeedsBigInt:                 ChecksNeedsBigInt(info),
+		OmitDeploy:                  info.OmitDeploy,
 	}
 
 	if info.Constructor != nil {

tools/operations-gen/internal/families/evm/config.go

@@ -8,6 +8,7 @@ type EvmContractConfig struct {
 	PackageName       string              `yaml:"package_name,omitempty"` // Optional: override package name
 	OmitDeploy        bool                `yaml:"omit_deploy,omitempty"`  // Optional: skip Deploy operation
 	GobindingsPackage string              `yaml:"gobindings_package"`     // Optional: override the derived gobindings import path or relative filesystem path for this contract.
+	ZksyncBytecode    ZksyncBytecodeRef   `yaml:"zksync_bytecode,omitempty"`
 	Functions         []EvmFunctionConfig `yaml:"functions"`
 	ConfigDir         string              `yaml:"-"`
 }
@@ -18,6 +19,9 @@ type EvmInputConfig struct {
 	// Contract packages default to:
 	//   <gobindings_package>/<version_path>/<package_name>
 	GobindingsPackage string `yaml:"gobindings_package"`
+	// ZksyncBindingsPackage is the default Go import path for zkSync VM deploy bytecode.
+	// Used when a contract sets zksync_bytecode to a symbol only.
+	ZksyncBindingsPackage string `yaml:"zksync_bindings_package,omitempty"`
 }
 
 // EvmFunctionConfig selects a contract function and assigns its access control.

tools/operations-gen/internal/families/evm/contract.go

@@ -25,16 +25,18 @@ const (
 
 // ContractInfo holds all parsed information about a contract needed for code generation.
 type ContractInfo struct {
-	Name              string
-	Version           string
-	PackageName       string
-	GobindingsPackage string
-	OutputPath        string
-	OmitDeploy        bool
-	Constructor       *FunctionInfo
-	Functions         map[string]*FunctionInfo
-	FunctionOrder     []string
-	StructDefs        map[string]*structDef
+	Name                  string
+	Version               string
+	PackageName           string
+	GobindingsPackage     string
+	ZksyncBytecodePackage string
+	ZksyncBytecodeSymbol  string
+	OutputPath            string
+	OmitDeploy            bool
+	Constructor           *FunctionInfo
+	Functions             map[string]*FunctionInfo
+	FunctionOrder         []string
+	StructDefs            map[string]*structDef
 }
 
 type structDef struct {
@@ -98,20 +100,31 @@ func extractContractInfo(cfg EvmContractConfig, input EvmInputConfig, output Evm
 	}
 	cfg.GobindingsPackage = resolvedGobindingsPackage
 
+	if cfg.OmitDeploy && !cfg.ZksyncBytecode.IsZero() {
+		return nil, fmt.Errorf("contract %q: zksync_bytecode cannot be set when omit_deploy is true", cfg.Name)
+	}
+
+	zksyncPackage, zksyncSymbol, err := resolveZksyncBytecode(cfg, input, cfg.GobindingsPackage)
+	if err != nil {
+		return nil, err
+	}
+
 	parsedAbi, err := ReadABI(cfg)
 	if err != nil {
 		return nil, err
 	}
 
 	info := &ContractInfo{
-		Name:              cfg.Name,
-		Version:           cfg.Version,
-		PackageName:       packageName,
-		GobindingsPackage: cfg.GobindingsPackage,
-		OutputPath:        core.ContractOutputPath(output.BasePath, versionPath, packageName),
-		OmitDeploy:        cfg.OmitDeploy,
-		Functions:         make(map[string]*FunctionInfo),
-		StructDefs:        make(map[string]*structDef),
+		Name:                  cfg.Name,
+		Version:               cfg.Version,
+		PackageName:           packageName,
+		GobindingsPackage:     cfg.GobindingsPackage,
+		ZksyncBytecodePackage: zksyncPackage,
+		ZksyncBytecodeSymbol:  zksyncSymbol,
+		OutputPath:            core.ContractOutputPath(output.BasePath, versionPath, packageName),
+		OmitDeploy:            cfg.OmitDeploy,
+		Functions:             make(map[string]*FunctionInfo),
+		StructDefs:            make(map[string]*structDef),
 	}
 
 	extractConstructor(info, parsedAbi)

tools/operations-gen/internal/families/evm/evm_golden_test.go

@@ -39,6 +39,13 @@ func TestGenerateFeeQuoter(t *testing.T) {
 	runGoldenGenerationTest(t, "operations_gen_fee_quoter.yaml", "fee_quoter.golden.go")
 }
 
+// TestGenerateLinkTokenWithZksyncBindingsPackage verifies generation when
+// input.zksync_bindings_package and contract zksync_bytecode are both set.
+func TestGenerateLinkTokenWithZksyncBindingsPackage(t *testing.T) {
+	t.Parallel()
+	runGoldenGenerationTest(t, "operations_gen_link_token_zksync_config.yaml", "link_token_zksync.golden.go")
+}
+
 func runGoldenGenerationTest(t *testing.T, configFileName string, goldenFileName string) {
 	t.Helper()
 

tools/operations-gen/internal/families/evm/evm_test.go

@@ -98,3 +98,51 @@ contracts:
 	require.Contains(t, string(got), `gobindings "`+wantGobindingsPackage+`"`)
 	require.NotContains(t, string(got), `gobindings "./testdata/evm/gobindings`)
 }
+
+func TestGenerateResolvesRelativeZksyncBindingsPackage(t *testing.T) {
+	t.Parallel()
+
+	const wantZksyncPackage = "github.com/smartcontractkit/chainlink-deployments-framework/tools/operations-gen/testdata/evm/zksync_bindings"
+	config := `version: "1.0.0"
+chain_family: evm
+
+input:
+  gobindings_package: "github.com/smartcontractkit/chainlink-deployments-framework/tools/operations-gen/testdata/evm/gobindings"
+  zksync_bindings_package: "./testdata/evm/zksync_bindings"
+
+output:
+  base_path: "."
+
+contracts:
+  - contract_name: ManyChainMultiSig
+    version: "1.0.0"
+    package_name: many_chain_multi_sig
+    zksync_bytecode: ManyChainMultiSigZkBytecode
+    functions:
+      - name: owner
+        access: public
+`
+
+	var cfg core.Config
+	require.NoError(t, yaml.Unmarshal([]byte(config), &cfg), "parsing config")
+
+	moduleDir, err := filepath.Abs(filepath.Join("..", "..", ".."))
+	require.NoError(t, err)
+	tmpDir := t.TempDir()
+	outputBasePath, err := filepath.Rel(moduleDir, tmpDir)
+	require.NoError(t, err)
+	cfg.ConfigDir = moduleDir
+	cfg.Output = mustYAMLNode(t, evm.EvmOutputConfig{BasePath: outputBasePath})
+
+	tmpl, err := generate.LoadTemplate("evm")
+	require.NoError(t, err, "loadTemplate")
+
+	require.NoError(t, evm.Handler{}.Generate(cfg, tmpl), "Generate")
+
+	outputPath := core.ContractOutputPath(tmpDir, core.VersionToPath("1.0.0"), "many_chain_multi_sig")
+	got, err := os.ReadFile(outputPath)
+	require.NoError(t, err, "reading generated file %s", outputPath)
+
+	require.Contains(t, string(got), `zkbindings "`+wantZksyncPackage+`"`)
+	require.Contains(t, string(got), "ZkSyncVM: zkbindings.ManyChainMultiSigZkBytecode")
+}

tools/operations-gen/internal/families/evm/zksync_bytecode.go

@@ -0,0 +1,85 @@
+package evm
+
+import (
+	"errors"
+	"fmt"
+
+	"gopkg.in/yaml.v3"
+)
+
+// ZksyncBytecodeRef identifies zkSync VM deploy bytecode for a contract.
+// YAML accepts a shorthand symbol string or {package, symbol}.
+type ZksyncBytecodeRef struct {
+	Package string
+	Symbol  string
+}
+
+func (z *ZksyncBytecodeRef) UnmarshalYAML(value *yaml.Node) error {
+	*z = ZksyncBytecodeRef{}
+	if value == nil {
+		return nil
+	}
+
+	switch value.Kind {
+	case yaml.ScalarNode:
+		if isYAMLNullScalar(value) {
+			return nil
+		}
+		z.Symbol = value.Value
+
+		return nil
+	case yaml.MappingNode:
+		var raw struct {
+			Package string `yaml:"package"`
+			Symbol  string `yaml:"symbol"`
+		}
+		if err := value.Decode(&raw); err != nil {
+			return err
+		}
+		z.Package = raw.Package
+		z.Symbol = raw.Symbol
+		if z.Symbol == "" {
+			return errors.New("zksync_bytecode mapping requires symbol")
+		}
+
+		return nil
+	case yaml.DocumentNode, yaml.SequenceNode, yaml.AliasNode:
+		return fmt.Errorf("zksync_bytecode must be a string or mapping, got %v", value.ShortTag())
+	}
+
+	return fmt.Errorf("zksync_bytecode must be a string or mapping, got %v", value.ShortTag())
+}
+
+func isYAMLNullScalar(value *yaml.Node) bool {
+	return value.Tag == "!!null" || value.Value == "" || value.Value == "~"
+}
+
+func (z ZksyncBytecodeRef) IsZero() bool {
+	return z.Symbol == ""
+}
+
+func resolveZksyncBytecode(
+	cfg EvmContractConfig,
+	input EvmInputConfig,
+	gobindingsPackage string,
+) (packagePath string, symbol string, err error) {
+	if cfg.ZksyncBytecode.IsZero() {
+		return "", "", nil
+	}
+
+	symbol = cfg.ZksyncBytecode.Symbol
+	pkgPath := cfg.ZksyncBytecode.Package
+	if pkgPath == "" {
+		pkgPath = input.ZksyncBindingsPackage
+	}
+	if pkgPath == "" {
+		return gobindingsPackage, symbol, nil
+	}
+
+	resolved, err := resolveGobindingsImportPath(pkgPath, cfg.ConfigDir)
+	if err != nil {
+		return "", "", fmt.Errorf("resolve zksync_bytecode package for contract %q: %w", cfg.Name, err)
+	}
+
+	return resolved, symbol, nil
+}