feat(evm): add gas boost retry option for contract deploys [CLD-2779] (#1047)

## Why
In order to take advantage of the contract.NewDeploy method used by the
operations-gen cli, we need to add support for gas limit bumping as we
currently support for legacy deploy MCMS contract changesets.

Note this already exist in cld-changesets
[here](https://github.com/smartcontractkit/cld-changesets/blob/f04fe26c52da79b60e9633d3d06e17f65ecb7893/pkg/family/evm/operations/utils.go#L433),
moving and refactoring this to CLDF makes more sense to other users can
take advantage of this option.

## Summary

- Adds `RetryDeployWithGasBoost` and `GasBoostConfig` for operations2
EVM contract deploys, increasing gas limit and price on retries after
gas-related failures.
- Extends `DeployInput` with optional `GasLimit` and `GasPrice` fields
and applies them via `deployTransactOpts` on EVM deploy paths.
- Classifies retryable gas errors using geth sentinels (`errors.Is`)
with a string fallback for RPC-wrapped messages.

JIRA: https://smartcontract-it.atlassian.net/browse/CLD-2779

Author: graham-chainlink

.changeset/dry-paws-unite.md

@@ -0,0 +1,5 @@
+---
+"chainlink-deployments-framework": minor
+---
+
+feat(operation): support gas bumping option for NewDeploy

chain/evm/operations2/contract/deploy.go

@@ -40,6 +40,13 @@ type DeployInput[ARGS any] struct {
 	Qualifier *string `json:"qualifier,omitempty"`
 	// Args are the parameters passed to the contract constructor.
 	Args ARGS `json:"args"`
+	// GasLimit optionally overrides the deployer gas limit on EVM chains.
+	// Normally set by RetryDeployWithGasBoost after gas-related failures; may also be set manually.
+	GasLimit uint64 `json:"gasLimit,omitempty"`
+	// GasPrice optionally overrides the deployer legacy gas price on EVM chains (wei).
+	// When non-zero, deploy uses a legacy fee transaction and clears any EIP-1559 GasFeeCap/GasTipCap.
+	// Normally set by RetryDeployWithGasBoost after gas-related failures; may also be set manually.
+	GasPrice uint64 `json:"gasPrice,omitempty"`
 }
 
 // Bytecode specifies the exact bytecode to deploy for each supported VM.
@@ -133,7 +140,7 @@ func NewDeploy[ARGS any](params DeployParams[ARGS]) *operations.Operation[Deploy
 				)
 			} else {
 				addr, tx, _, deployErr = deployEVMContract(
-					chain.DeployerKey,
+					deployTransactOpts(chain.DeployerKey, input.GasLimit, input.GasPrice),
 					*parsedABI,
 					bytecode.EVM,
 					chain.Client,

chain/evm/operations2/contract/deployment_test.go

@@ -4,6 +4,7 @@ import (
 	"context"
 	"errors"
 	"fmt"
+	"math/big"
 	"testing"
 
 	"github.com/Masterminds/semver/v3"
@@ -77,6 +78,16 @@ func TestDeploy(t *testing.T) {
 			},
 			isZkSyncVM: false,
 		},
+		{
+			desc: "evm deployment with gas overrides",
+			input: DeployInput[ConstructorArgs]{
+				Args:           ConstructorArgs{Value: 2},
+				TypeAndVersion: deployment.NewTypeAndVersion(testContractType, *semver.MustParse("1.0.0")),
+				GasLimit:       750_000,
+				GasPrice:       25_000_000_000,
+			},
+			isZkSyncVM: false,
+		},
 	}
 
 	for _, test := range tests { //nolint:paralleltest // subtests modify package-level deployZkContract/deployEVMContract vars
@@ -127,6 +138,12 @@ func TestDeploy(t *testing.T) {
 				},
 				IsZkSyncVM: test.isZkSyncVM,
 			}
+			if test.input.GasLimit > 0 || test.input.GasPrice > 0 {
+				chain.DeployerKey = &bind.TransactOpts{
+					GasFeeCap: big.NewInt(100),
+					GasTipCap: big.NewInt(2),
+				}
+			}
 
 			deployZkContract = func(
 				_ context.Context,
@@ -140,7 +157,7 @@ func TestDeploy(t *testing.T) {
 				return address, nil
 			}
 			deployEVMContract = func(
-				_ *bind.TransactOpts,
+				opts *bind.TransactOpts,
 				_ abi.ABI,
 				_ []byte,
 				_ bind.ContractBackend,
@@ -155,6 +172,13 @@ func TestDeploy(t *testing.T) {
 						)),
 					}
 				}
+				if test.input.GasLimit > 0 || test.input.GasPrice > 0 {
+					require.NotNil(t, opts)
+					require.Equal(t, test.input.GasLimit, opts.GasLimit)
+					require.Equal(t, test.input.GasPrice, opts.GasPrice.Uint64())
+					require.Nil(t, opts.GasFeeCap)
+					require.Nil(t, opts.GasTipCap)
+				}
 
 				return address, types.NewTx(&types.LegacyTx{
 					To:   &address,

chain/evm/operations2/contract/gas_boost.go

@@ -0,0 +1,169 @@
+package contract
+
+import (
+	"errors"
+	"math/big"
+	"strings"
+
+	"github.com/ethereum/go-ethereum/accounts/abi/bind"
+	"github.com/ethereum/go-ethereum/core"
+	"github.com/ethereum/go-ethereum/core/txpool"
+	"github.com/ethereum/go-ethereum/core/vm"
+
+	"github.com/smartcontractkit/chainlink-deployments-framework/chain/evm"
+	"github.com/smartcontractkit/chainlink-deployments-framework/operations"
+)
+
+const (
+	defaultInitialGasLimit   = uint64(5_000_000)
+	defaultGasLimitIncrement = uint64(500_000)
+	defaultInitialGasPrice   = uint64(20_000_000_000)
+	defaultGasPriceIncrement = uint64(10_000_000_000)
+)
+
+// GasBoostConfig defines gas limit and price increments applied on deploy retries.
+// Increment fields use pointers so zero is a valid configured value (no increment).
+// A nil increment pointer uses the package default increment.
+type GasBoostConfig struct {
+	InitialGasLimit   uint64  `json:"initialGasLimit"`
+	GasLimitIncrement *uint64 `json:"gasLimitIncrement,omitempty"`
+	InitialGasPrice   uint64  `json:"initialGasPrice"`
+	GasPriceIncrement *uint64 `json:"gasPriceIncrement,omitempty"`
+}
+
+// RetryDeployWithGasBoost enables the default operation retry policy and increases gas on EVM deploy retries.
+// The operation may retry on any failure (per the framework retry policy); gas limit and price are adjusted
+// only when the prior attempt failed with a gas-related error.
+// The first execution attempt uses the chain deployer's default gas settings (auto-estimation).
+// On ZkSync VM chains, gas fields are not adjusted; omit this option for ZkSync-only deploy flows.
+// When cfg is nil, returns a no-op option and retry remains disabled (omit this option instead).
+func RetryDeployWithGasBoost[ARGS any](cfg *GasBoostConfig) operations.ExecuteOption[DeployInput[ARGS], evm.Chain] {
+	if cfg == nil {
+		return func(*operations.ExecuteConfig[DeployInput[ARGS], evm.Chain]) {}
+	}
+	c := *cfg
+
+	return operations.WithRetryInput(func(attempt uint, err error, in DeployInput[ARGS], deps evm.Chain) DeployInput[ARGS] {
+		if deps.IsZkSyncVM || !isGasRetryableError(err) {
+			return in
+		}
+
+		gasLimit, gasPrice := nextBoostedGas(c, attempt, in.GasLimit, in.GasPrice)
+		in.GasLimit = gasLimit
+		in.GasPrice = gasPrice
+
+		return in
+	})
+}
+
+func (cfg GasBoostConfig) gasLimitIncrement() uint64 {
+	if cfg.GasLimitIncrement == nil {
+		return defaultGasLimitIncrement
+	}
+
+	return *cfg.GasLimitIncrement
+}
+
+func (cfg GasBoostConfig) gasPriceIncrement() uint64 {
+	if cfg.GasPriceIncrement == nil {
+		return defaultGasPriceIncrement
+	}
+
+	return *cfg.GasPriceIncrement
+}
+
+func resolveInitialGasLimit(cfg GasBoostConfig) uint64 {
+	if cfg.InitialGasLimit > 0 {
+		return cfg.InitialGasLimit
+	}
+
+	return defaultInitialGasLimit
+}
+
+func resolveInitialGasPrice(cfg GasBoostConfig) uint64 {
+	if cfg.InitialGasPrice > 0 {
+		return cfg.InitialGasPrice
+	}
+
+	return defaultInitialGasPrice
+}
+
+func nextBoostedGas(cfg GasBoostConfig, attempt uint, previousLimit, previousPrice uint64) (gasLimit uint64, gasPrice uint64) {
+	initialGasLimit := resolveInitialGasLimit(cfg)
+	gasLimitIncrement := cfg.gasLimitIncrement()
+	initialGasPrice := resolveInitialGasPrice(cfg)
+	gasPriceIncrement := cfg.gasPriceIncrement()
+
+	if previousLimit > 0 {
+		gasLimit = previousLimit + gasLimitIncrement
+	} else {
+		gasLimit = initialGasLimit + uint64(attempt)*gasLimitIncrement
+	}
+
+	if previousPrice > 0 {
+		gasPrice = previousPrice + gasPriceIncrement
+	} else {
+		gasPrice = initialGasPrice + uint64(attempt)*gasPriceIncrement
+	}
+
+	return gasLimit, gasPrice
+}
+
+func isGasRetryableError(err error) bool {
+	if err == nil {
+		return false
+	}
+
+	if errors.Is(err, vm.ErrOutOfGas) ||
+		errors.Is(err, vm.ErrCodeStoreOutOfGas) ||
+		errors.Is(err, core.ErrIntrinsicGas) ||
+		errors.Is(err, core.ErrFeeCapTooLow) ||
+		errors.Is(err, core.ErrGasLimitReached) ||
+		errors.Is(err, txpool.ErrUnderpriced) ||
+		errors.Is(err, txpool.ErrReplaceUnderpriced) ||
+		errors.Is(err, txpool.ErrTxGasPriceTooLow) ||
+		errors.Is(err, txpool.ErrGasLimit) {
+		return true
+	}
+
+	msg := strings.ToLower(err.Error())
+	for _, pattern := range gasRetryableErrorPatterns {
+		if strings.Contains(msg, pattern) {
+			return true
+		}
+	}
+
+	return false
+}
+
+// gasRetryableErrorPatterns covers RPC and wrapped errors that no longer carry geth sentinels.
+var gasRetryableErrorPatterns = []string{
+	"out of gas",
+	"gas required exceeds allowance",
+	"intrinsic gas too low",
+	"underpriced",
+	"replacement transaction underpriced",
+	"max fee per gas less than block base fee",
+	"exceeds block gas limit",
+}
+
+func deployTransactOpts(base *bind.TransactOpts, gasLimit, gasPrice uint64) *bind.TransactOpts {
+	if base == nil {
+		return nil
+	}
+	if gasLimit == 0 && gasPrice == 0 {
+		return base
+	}
+
+	opts := *base
+	if gasLimit > 0 {
+		opts.GasLimit = gasLimit
+	}
+	if gasPrice > 0 {
+		opts.GasPrice = new(big.Int).SetUint64(gasPrice)
+		opts.GasFeeCap = nil
+		opts.GasTipCap = nil
+	}
+
+	return &opts
+}