feat: gastime package (#9)

Introduces the gas clock, an extension of a `proxytime.Time[gas.Gas]`
that also tracks a "continuous" equivalent of ACP-176 gas excess at
gas-unit resolution instead of per second.

Closes #11

Author: ARR4N

gastime/cmpopt.go

@@ -0,0 +1,24 @@
+// Copyright (C) 2025, Ava Labs, Inc. All rights reserved.
+// See the file LICENSE for licensing terms.
+
+//go:build !prod && !nocmpopts
+
+package gastime
+
+import (
+	"github.com/ava-labs/avalanchego/vms/components/gas"
+	"github.com/google/go-cmp/cmp"
+	"github.com/google/go-cmp/cmp/cmpopts"
+
+	"github.com/ava-labs/strevm/proxytime"
+)
+
+// CmpOpt returns a configuration for [cmp.Diff] to compare [Time] instances in
+// tests.
+func CmpOpt() cmp.Option {
+	return cmp.Options{
+		cmp.AllowUnexported(TimeMarshaler{}),
+		cmpopts.IgnoreTypes(canotoData_TimeMarshaler{}),
+		proxytime.CmpOpt[gas.Gas](proxytime.CmpRateInvariantsByValue),
+	}
+}

gastime/gastime.go

@@ -0,0 +1,174 @@
+// Copyright (C) 2025, Ava Labs, Inc. All rights reserved.
+// See the file LICENSE for licensing terms.
+
+// Package gastime measures time based on the consumption of gas.
+package gastime
+
+import (
+	"math"
+
+	"github.com/ava-labs/avalanchego/vms/components/gas"
+	"github.com/holiman/uint256"
+
+	"github.com/ava-labs/strevm/intmath"
+	"github.com/ava-labs/strevm/proxytime"
+)
+
+// Time represents an instant in time, its passage measured in [gas.Gas]
+// consumption. It is not thread safe nor is the zero value valid.
+//
+// In addition to the passage of time, it also tracks excess consumption above a
+// target, as described in [ACP-194] as a "continuous" version of [ACP-176].
+//
+// Copying a Time, either directly or by dereferencing a pointer, will result in
+// undefined behaviour. Use [Time.Clone] instead as it reestablishes internal
+// invariants.
+//
+// [ACP-176]: https://github.com/avalanche-foundation/ACPs/tree/main/ACPs/176-dynamic-evm-gas-limit-and-price-discovery-updates
+// [ACP-194]: https://github.com/avalanche-foundation/ACPs/tree/main/ACPs/194-streaming-asynchronous-execution
+type Time struct {
+	TimeMarshaler
+}
+
+// makeTime is a constructor shared by [New] and [Time.Clone].
+func makeTime(t *proxytime.Time[gas.Gas], target, excess gas.Gas) *Time {
+	tm := &Time{
+		TimeMarshaler: TimeMarshaler{
+			Time:   t,
+			target: target,
+			excess: excess,
+		},
+	}
+	tm.establishInvariants()
+	return tm
+}
+
+func (tm *Time) establishInvariants() {
+	tm.Time.SetRateInvariants(&tm.target, &tm.excess)
+}
+
+// New returns a new [Time], set from a Unix timestamp. The consumption of
+// `target` * [TargetToRate] units of [gas.Gas] is equivalent to a tick of 1
+// second. Targets are clamped to [MaxTarget].
+func New(unixSeconds uint64, target, startingExcess gas.Gas) *Time {
+	target = clampTarget(target)
+	return makeTime(proxytime.New(unixSeconds, rateOf(target)), target, startingExcess)
+}
+
+// TargetToRate is the ratio between [Time.Target] and [proxytime.Time.Rate].
+const TargetToRate = 2
+
+// MaxTarget is the maximum allowable [Time.Target] to avoid overflows of the
+// associated [proxytime.Time.Rate]. Values above this are silently clamped.
+const MaxTarget = gas.Gas(math.MaxUint64 / TargetToRate)
+
+func rateOf(target gas.Gas) gas.Gas { return target * TargetToRate }
+func clampTarget(t gas.Gas) gas.Gas { return min(t, MaxTarget) }
+func roundRate(r gas.Gas) gas.Gas   { return (r / TargetToRate) * TargetToRate }
+
+// Clone returns a deep copy of the time.
+func (tm *Time) Clone() *Time {
+	// [proxytime.Time.Clone] explicitly does NOT clone the rate invariants, so
+	// we reestablish them as if we were constructing a new instance.
+	return makeTime(tm.Time.Clone(), tm.target, tm.excess)
+}
+
+// Target returns the `T` parameter of ACP-176.
+func (tm *Time) Target() gas.Gas {
+	return tm.target
+}
+
+// Excess returns the `x` variable of ACP-176.
+func (tm *Time) Excess() gas.Gas {
+	return tm.excess
+}
+
+// Price returns the price of a unit of gas, i.e. the "base fee".
+func (tm *Time) Price() gas.Price {
+	return gas.CalculatePrice(1 /* M */, tm.excess, tm.excessScalingFactor())
+}
+
+// excessScalingFactor returns the K variable of ACP-103/176, i.e. 87*T, capped
+// at [math.MaxUint64].
+func (tm *Time) excessScalingFactor() gas.Gas {
+	const (
+		targetToK         = 87
+		overflowThreshold = math.MaxUint64 / targetToK
+	)
+	if tm.target > overflowThreshold {
+		return math.MaxUint64
+	}
+	return targetToK * tm.target
+}
+
+// BaseFee is equivalent to [Time.Price], returning the result as a uint256 for
+// compatibility with geth/libevm objects.
+func (tm *Time) BaseFee() *uint256.Int {
+	return uint256.NewInt(uint64(tm.Price()))
+}
+
+// SetRate changes the gas rate per second, rounding down the argument if it is
+// not a multiple of [TargetToRate]. See [Time.SetTarget] re potential error(s).
+func (tm *Time) SetRate(r gas.Gas) error {
+	_, err := tm.TimeMarshaler.SetRate(roundRate(r))
+	return err
+}
+
+// SetTarget changes the target gas consumption per second, clamping the
+// argument to [MaxTarget]. It returns an error if the scaled [Time.Excess]
+// overflows as a result of the scaling.
+func (tm *Time) SetTarget(t gas.Gas) error {
+	_, err := tm.TimeMarshaler.SetRate(rateOf(clampTarget(t))) // also updates [Time.Target] as it was passed to [proxytime.Time.SetRateInvariants]
+	return err
+}
+
+// Tick is equivalent to [proxytime.Time.Tick] except that it also updates the
+// gas excess.
+func (tm *Time) Tick(g gas.Gas) {
+	tm.Time.Tick(g)
+
+	R, T := tm.Rate(), tm.Target()
+	quo, _, _ := intmath.MulDiv(g, R-T, R) // overflow is impossible as (R-T)/R < 1
+	tm.excess += quo
+}
+
+// FastForwardTo is equivalent to [proxytime.Time.FastForwardTo] except that it
+// may also update the gas excess.
+func (tm *Time) FastForwardTo(to uint64) {
+	sec, frac := tm.Time.FastForwardTo(to)
+	if sec == 0 && frac.Numerator == 0 {
+		return
+	}
+
+	R, T := tm.Rate(), tm.Target()
+
+	// Excess is reduced by the amount of gas skipped (g), multiplied by T/R.
+	// However, to avoid overflow, the implementation needs to be a bit more
+	// complicated. The reduction in excess can be calculated as follows (math
+	// notation, not code, and ignoring the bounding at zero):
+	//
+	// s := seconds fast-forwarded (`sec`)
+	// f := `frac.Numerator`
+	// x := excess
+	//
+	// dx = -g·T/R
+	// = -(sR + f)·T/R
+	// = -sR·T/R - fT/R
+	// = -sT - fT/R
+	//
+	// Note that this is equivalent to the ACP reduction of T·dt because dt is
+	// equal to s + f/R since `frac.Denominator == R` is a documented invariant.
+	// Therefore dx = -(s + f/R)·T, but we separate the terms differently for
+	// our implementation.
+
+	// -sT
+	if s := gas.Gas(sec); tm.excess/T >= s { // sT <= x; division is safe because T > 0
+		tm.excess -= s * T
+	} else { // sT > x
+		tm.excess = 0
+	}
+
+	// -fT/R
+	quo, _, _ := intmath.MulDiv(frac.Numerator, T, R) // overflow is impossible as T/R < 1
+	tm.excess = intmath.BoundedSubtract(tm.excess, quo, 0)
+}