acp-176/226 refactor to common package #4292

ceyonur · 2025-09-17T22:01:13Z

Why this should be merged

Refactors common parts from acp-176 and acp-226 into common package.

How this works

Uses TargetExcessParam structure to define common functions, so that different implementations/parameters can use the same functions

How this was tested

existing tests

Need to be documented in RELEASES.md?

no

Copilot

Pull Request Overview

Refactors common functionality from ACP-176 and ACP-226 implementations into a shared common package to reduce code duplication and improve maintainability.

Introduces TargetExcessParams structure to encapsulate parameters and functions for target excess calculations
Moves exponential calculation logic from gas package to a new math utility function
Updates both ACP implementations to use the shared common package functions

Reviewed Changes

Copilot reviewed 5 out of 7 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
vms/evm/upgrades/common/target_excess.go	New common package with shared target excess calculation functions and parameters structure
vms/evm/upgrades/acp226/acp226.go	Refactored to use common package functions, removing duplicate implementation
vms/evm/upgrades/acp176/acp176.go	Refactored to use common package functions, removing duplicate implementation
vms/components/gas/gas.go	Simplified to use new math utility function for exponential calculations
utils/math/exponential.go	New utility function extracted from gas package for exponential calculations

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

vms/evm/upgrades/common/target_excess.go

ceyonur · 2025-09-19T11:28:02Z

vms/evm/acp176/acp176.go

@@ -154,7 +157,7 @@ func (s *State) UpdateTargetExcess(desiredTargetExcess gas.Gas) {
 	)

 	// Ensure the gas capacity does not exceed the maximum capacity.
-	newMaxCapacity := mulWithUpperBound(newTargetPerSecond, TargetToMaxCapacity) // C
+	newMaxCapacity := gas.Gas(common.MulWithUpperBound(uint64(newTargetPerSecond), TargetToMaxCapacity)) // C
 	s.Gas.Capacity = min(s.Gas.Capacity, newMaxCapacity)


this now uses golang builtin min, would it be a problem? cc @StephenButtolph

vms/evm/upgrades/acp226/acp226.go

vms/evm/upgrades/acp226/acp226_test.go

utils/math/exponential.go

vms/evm/upgrades/common/target_excess.go

michaelkaplan13

One nit, and think we should update/remove the "target" terminology from target_excess.go since it's not just applying to the gas target anymore, but otherwise LGTM.

vms/evm/upgrades/acp226/acp226.go

vms/evm/excess/params.go

Signed-off-by: Ceyhun Onur <[email protected]>

…alanchego into ceyonur/acp-176-226-refactor

joshua-kim · 2025-09-26T17:24:45Z

utils/math/exponential.go

+
+		maxOutput uint256.Int
+	)
+	num.SetUint64(numerator)     // range is [0, MaxUint64]


nit: All of these range comments seem overly verbose since it's already known that the range of a unit64 is the range of a uint64. Should we get rid of them?

joshua-kim · 2025-09-26T17:27:11Z

utils/math/exponential.go

+//	def fake_exponential(factor: int, numerator: int, denominator: int) -> int:
+//		i = 1
+//		output = 0
+//		numerator_accum = factor * denominator
+//		while numerator_accum > 0:
+//			output += numerator_accum
+//			numerator_accum = (numerator_accum * numerator) // (denominator * i)
+//			i += 1
+//		return output // denominator
+//
+// This implementation is optimized with the knowledge that any value greater
+// than MaxUint64 gets returned as MaxUint64. This means that every intermediate
+// value is guaranteed to be at most MaxUint193. So, we can safely use
+// uint256.Int.
+//
+// This function does not perform any memory allocations.


It seems overly verbose to me that we document this - isn't this just a translation of the below source code? Wonder if we should just get rid of this too.

joshua-kim · 2025-09-26T17:28:14Z

utils/math/exponential.go

+// This function does not perform any memory allocations.
+//
+//nolint:dupword // The python is copied from the EIP-4844 specification
+func CalculateExponential(


Should we call this ApproximateExponential so the caller doesn't have to read the godoc to know this is not an exact result?

joshua-kim · 2025-10-01T17:14:12Z

vms/evm/upgrades/common/excess_params.go

+// See the file LICENSE for licensing terms.
+
+// Package common provides shared utility functions for ACP implementations.
+package common


I really dislike common packages... I feel like it's unclear what the boundary is for what they own and they tend to turn into dumpsters for things that don't fit elsewhere. Would it be reasonable for us to define an excess package instead?

joshua-kim · 2025-10-01T17:14:42Z

vms/evm/upgrades/common/excess_params.go

+
+// AdjustExcess calculates the optimal new excess given the current and desired excess values,
+// ensuring the change does not exceed the maximum excess difference.
+func (p ExcessParams) AdjustExcess(excess, desired uint64) uint64 {


nit: typically receivers start with the first letter of the type (e) unless there's a commonly known abbreviation for the type (like db or vm).

Since we have changed the package name, I think we should rename ExcessParams > Params

joshua-kim · 2025-10-01T17:15:13Z

vms/evm/upgrades/common/excess_params.go

+	MinValue       uint64 // Minimum value (P or M)
+	ConversionRate uint64 // Conversion factor for exponential calculations (D)
+	MaxExcessDiff  uint64 // Maximum change in excess per update (Q)


Where are these letters coming from? Is there some formula we should doc at the top of this type?

I moved those letters to relevant acps

joshua-kim · 2025-10-01T17:15:59Z

vms/evm/upgrades/common/excess_params.go

+)
+
+// ExcessParams contains the parameters needed for excess calculations.
+type ExcessParams struct {


I don't know much about this type so I'm not the person to ask for naming, but should we call this Excess? It seems like a math-y type so I assumed everything inside it was a parameter for its calculations.

I think it's still contains parameters for calculations. It's not the real excess, but it's a set of parameters to be used in excess calculations.

joshua-kim · 2025-10-01T17:17:47Z

vms/evm/excess/params.go

+
+// MulWithUpperBound multiplies two numbers and returns the result. If the
+// result overflows, it returns [math.MaxUint64].
+func MulWithUpperBound(a, b uint64) uint64 {


Does this need to be in this package? Seems like this is only used for acp176 implementation - wondering if we could move and unexport there.

we can move this to acp176 package as an unexported function

github-project-automation bot added this to avalanchego Sep 17, 2025

ceyonur mentioned this pull request Sep 17, 2025

Implement ACP-226 Math #4289

Merged

ceyonur changed the title ~~Ceyonur/acp 176 226 refactor~~ acp-176/226 refactor to common package Sep 17, 2025

Base automatically changed from ceyonur/acp-176-math-package to master September 18, 2025 13:32

ceyonur changed the base branch from master to ceyonur/acp-226-math-package September 18, 2025 16:25

Base automatically changed from ceyonur/acp-226-math-package to master September 18, 2025 19:35

ceyonur added 4 commits September 18, 2025 23:59

refactor common parts from acp-176 and acp-226

b20dfd9

move fake expo calculation to safemath

70d12c3

fix linter

f1609fa

remove extra import

4b1dd83

ceyonur force-pushed the ceyonur/acp-176-226-refactor branch from a9463c2 to 4b1dd83 Compare September 18, 2025 21:00

fix predeclared identifier

62000d4

ceyonur marked this pull request as ready for review September 18, 2025 21:35

ceyonur requested a review from StephenButtolph as a code owner September 18, 2025 21:35

Copilot AI review requested due to automatic review settings September 18, 2025 21:35

Copilot AI reviewed Sep 18, 2025

View reviewed changes

vms/evm/upgrades/common/target_excess.go Outdated Show resolved Hide resolved

use builtin min

1a03e68

ceyonur commented Sep 19, 2025

View reviewed changes

vms/evm/upgrades/acp226/acp226.go Outdated Show resolved Hide resolved

This was referenced Sep 19, 2025

refactor acp-176 math to be reused by acp-226 ava-labs/coreth#1229

Closed

ACP-226: add initial delay excess #4300

Merged

michaelkaplan13 reviewed Sep 19, 2025

View reviewed changes

vms/evm/upgrades/acp226/acp226_test.go Show resolved Hide resolved

michaelkaplan13 reviewed Sep 23, 2025

View reviewed changes

utils/math/exponential.go Show resolved Hide resolved

vms/evm/upgrades/common/target_excess.go Outdated Show resolved Hide resolved

JonathanOppenheimer mentioned this pull request Sep 23, 2025

Make ACP-176 math configurable #4285

Open

michaelkaplan13 reviewed Sep 23, 2025

View reviewed changes

vms/evm/upgrades/acp226/acp226.go Outdated Show resolved Hide resolved

ceyonur added 5 commits September 24, 2025 11:00

remove target prefixes

4b2b0bd

remove comment

e43a12f

revert var name change

9efd27a

Merge branch 'master' into ceyonur/acp-176-226-refactor

5fbcbef

fix import path

d5b7f34

ceyonur requested review from joshua-kim and maru-ava as code owners September 24, 2025 16:27

michaelkaplan13 reviewed Sep 24, 2025

View reviewed changes

vms/evm/excess/params.go Show resolved Hide resolved

Rename target_excess.go to excess_params.go

7f3cfaf

Signed-off-by: Ceyhun Onur <[email protected]>

michaelkaplan13 approved these changes Sep 25, 2025

View reviewed changes

ceyonur added 3 commits September 26, 2025 18:17

Merge branch 'master' into ceyonur/acp-176-226-refactor

7b1b98b

resolve conflict

bc65754

Merge branch 'ceyonur/acp-176-226-refactor' of github.com:ava-labs/av…

e5af5e0

…alanchego into ceyonur/acp-176-226-refactor

joshua-kim moved this to In Progress 🏗️ in avalanchego Sep 29, 2025

StephenButtolph assigned ceyonur Sep 30, 2025

StephenButtolph moved this from In Progress 🏗️ to In Review 🔎 in avalanchego Sep 30, 2025

joshua-kim reviewed Oct 1, 2025

View reviewed changes

joshua-kim moved this from In Review 🔎 to In Progress 🏗️ in avalanchego Oct 1, 2025

ceyonur added 4 commits October 6, 2025 15:59

Merge branch 'master' into ceyonur/acp-176-226-refactor

795236e

reviews

0c58d10

fix import paths

34a58f9

unnecessary conversions

3e17981

ceyonur marked this pull request as draft October 7, 2025 08:19

ceyonur marked this pull request as ready for review October 7, 2025 18:51

Merge branch 'master' into ceyonur/acp-176-226-refactor

43c2413

acp-176/226 refactor to common package #4292

Are you sure you want to change the base?

acp-176/226 refactor to common package #4292

Conversation

ceyonur commented Sep 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Why this should be merged

How this works

How this was tested

Need to be documented in RELEASES.md?

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Reviewed Changes

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

michaelkaplan13 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

ceyonur commented Sep 17, 2025 •

edited

Loading