refactor: temporary extras require proof of lock

Author: ARR4N

libevm/extraslock.go

@@ -0,0 +1,63 @@
+// Copyright 2025 the libevm authors.
+//
+// The libevm additions to go-ethereum are free software: you can redistribute
+// them and/or modify them under the terms of the GNU Lesser General Public License
+// as published by the Free Software Foundation, either version 3 of the License,
+// or (at your option) any later version.
+//
+// The libevm additions are distributed in the hope that they will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser
+// General Public License for more details.
+//
+// You should have received a copy of the GNU Lesser General Public License
+// along with the go-ethereum library. If not, see
+// <http://www.gnu.org/licenses/>.
+
+package libevm
+
+import (
+	"errors"
+	"sync"
+	"sync/atomic"
+)
+
+var (
+	extrasMu     sync.Mutex
+	extrasHandle atomic.Uint64
+)
+
+// WithTemporaryExtrasLock takes a global lock and calls `fn` with a handle that
+// can be used to prove that the lock is held. All package-specific temporary
+// overrides require this proof.
+//
+// WithTemporaryExtrasLock MUST NOT be used on a live chain. It is solely
+// intended for off-chain consumers that require access to extras.
+func WithTemporaryExtrasLock(fn func(lock ExtrasLock) error) error {
+	extrasMu.Lock()
+	defer func() {
+		extrasHandle.Add(1)
+		extrasMu.Unlock()
+	}()
+
+	v := extrasHandle.Load()
+	return fn(ExtrasLock{&v})
+}
+
+// ErrExpiredExtrasLock is returned by [ExtrasLock.Verify] if the lock has been
+// persisted beyond the call to [WithTemporaryExtrasLock] that created it.
+var ErrExpiredExtrasLock = errors.New("libevm.ExtrasLock expired")
+
+// An ExtrasLock is a handle that proves a current call to
+// [WithTemporaryExtrasLock].
+type ExtrasLock struct {
+	handle *uint64
+}
+
+// Verify verifies that the lock is valid.
+func (l ExtrasLock) Verify() error {
+	if *l.handle != extrasHandle.Load() {
+		return ErrExpiredExtrasLock
+	}
+	return nil
+}

libevm/extraslock_test.go

@@ -0,0 +1,47 @@
+// Copyright 2025 the libevm authors.
+//
+// The libevm additions to go-ethereum are free software: you can redistribute
+// them and/or modify them under the terms of the GNU Lesser General Public License
+// as published by the Free Software Foundation, either version 3 of the License,
+// or (at your option) any later version.
+//
+// The libevm additions are distributed in the hope that they will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser
+// General Public License for more details.
+//
+// You should have received a copy of the GNU Lesser General Public License
+// along with the go-ethereum library. If not, see
+// <http://www.gnu.org/licenses/>.
+
+package libevm_test
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+
+	// Testing from outside the package to guarantee usage of the public API only.
+	. "github.com/ava-labs/libevm/libevm"
+)
+
+func TestExtrasLock(t *testing.T) {
+	var zero ExtrasLock
+	assert.Panics(t, func() { zero.Verify() }, "Verify() method of zero-value ExtrasLock{}")
+
+	assert.NoError(t,
+		WithTemporaryExtrasLock((ExtrasLock).Verify),
+		"WithTemporaryExtrasLock((ExtrasLock).Verify)",
+	)
+
+	var persisted ExtrasLock
+	WithTemporaryExtrasLock(func(l ExtrasLock) error {
+		persisted = l
+		return nil
+	})
+
+	assert.ErrorIs(
+		t, persisted.Verify(), ErrExpiredExtrasLock,
+		"Verify() of persisted ExtrasLock",
+	)
+}

libevm/temporary/temporary.go

@@ -21,6 +21,7 @@ import (
 	"math/big"
 	"reflect"
 
+	"github.com/ava-labs/libevm/libevm"
 	"github.com/ava-labs/libevm/libevm/pseudo"
 	"github.com/ava-labs/libevm/libevm/register"
 	"github.com/ava-labs/libevm/log"
@@ -106,11 +107,18 @@ func payloadsAndConstructors[C ChainConfigHooks, R RulesHooks](e Extras[C, R]) (
 // call this function directly. Use the libevm/temporary.WithRegisteredExtras()
 // function instead as it atomically overrides all possible packages.
 func WithTempRegisteredExtras[C ChainConfigHooks, R RulesHooks](
+	lock libevm.ExtrasLock,
 	e Extras[C, R],
-	fn func(ExtraPayloads[C, R]),
-) {
+	fn func(ExtraPayloads[C, R]) error,
+) error {
+	if err := lock.Verify(); err != nil {
+		return err
+	}
+
 	payloads, ctors := payloadsAndConstructors(e)
-	registeredExtras.TempOverride(ctors, func() { fn(payloads) })
+	var err error
+	registeredExtras.TempOverride(ctors, func() { err = fn(payloads) })
+	return err
 }
 
 // TestOnlyClearRegisteredExtras clears the [Extras] previously passed to

params/config.libevm.go

@@ -1,4 +1,4 @@
-// Copyright 2024 the libevm authors.
+// Copyright 2024-2025 the libevm authors.
 //
 // The libevm additions to go-ethereum are free software: you can redistribute
 // them and/or modify them under the terms of the GNU Lesser General Public License
@@ -13,6 +13,7 @@
 // You should have received a copy of the GNU Lesser General Public License
 // along with the go-ethereum library. If not, see
 // <http://www.gnu.org/licenses/>.
+
 package params
 
 import (
@@ -23,6 +24,7 @@ import (
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
 
+	"github.com/ava-labs/libevm/libevm"
 	"github.com/ava-labs/libevm/libevm/pseudo"
 	"github.com/ava-labs/libevm/libevm/register"
 )
@@ -329,16 +331,20 @@ func TestTempRegisteredExtras(t *testing.T) {
 
 	t.Run("before_temp", testPrimaryExtras)
 	t.Run("WithTempRegisteredExtras", func(t *testing.T) {
-		WithTempRegisteredExtras(
-			override,
-			func(extras ExtraPayloads[overrideCC, overrideRules]) { // deliberately shadow `extras`
-				assertRulesCopiedFromChainConfig(
-					t, extras, "hello, world",
-					func(cc *overrideCC, x string) { cc.X = x },
-					func(r *overrideRules) string { return r.X },
-				)
-			},
-		)
+		err := libevm.WithTemporaryExtrasLock(func(lock libevm.ExtrasLock) error {
+			return WithTempRegisteredExtras(
+				lock, override,
+				func(extras ExtraPayloads[overrideCC, overrideRules]) error { // deliberately shadow `extras`
+					assertRulesCopiedFromChainConfig(
+						t, extras, "hello, world",
+						func(cc *overrideCC, x string) { cc.X = x },
+						func(r *overrideRules) string { return r.X },
+					)
+					return nil
+				},
+			)
+		})
+		require.NoError(t, err)
 	})
 	t.Run("after_temp", testPrimaryExtras)
 }