fixup! feat(eth)!: add Eth APIs to /v2 + minor improvements & fixes

Author: rvagg

CHANGELOG.md

@@ -11,18 +11,22 @@
 
 - fix(eth): always return nil for eth transactions not found ([filecoin-project/lotus#12999](https://github.com/filecoin-project/lotus/pull/12999))
 - feat: add gas to application metric reporting `vm/applyblocks_early_gas`, `vm/applyblocks_messages_gas`, `vm/applyblocks_cron_gas` ([filecoin-project/lotus#13030](https://github.com/filecoin-project/lotus/pull/13030))
-- feat: add **Lotus v2 experimental APIs with F3 awareness**:<br>
-  The Lotus V2 APIs introduce a powerful new TipSet selection mechanism that significantly enhances how applications interact with the Filecoin blockchain. The design reduces API footprint, seamlessly handles both traditional Expected Consensus and the new F3 protocol, and provides graceful fallbacks. See [Filecoin v2 APIs](https://filoznotebook.notion.site/Filecoin-V2-APIs-1d0dc41950c1808b914de5966d501658) for an in-depth overview. ([filecoin-project/lotus#13003](https://github.com/filecoin-project/lotus/pull/13003)), ([filecoin-project/lotus#13027](https://github.com/filecoin-project/lotus/pull/13027)), ([filecoin-project/lotus#13034](https://github.com/filecoin-project/lotus/pull/13034))
-- feat: add **Ethereum APIs to v2 with F3 awareness** and minor improvements to v1 Ethereum APIs:<br>
-  The full suite of Ethereum APIs supported by Lotus (aliased by `eth_`, `trace_` etc. for compatibility) are now also exposed on the new V2 API endpoint. Functionality of the APIs remains identical, however the mapping of `"finalized"` and `"safe"` will defer to F3 rather than using fixed epochs. When F3 is operating normally, both of these labels will choose the parent of the F3 finalized epoch rather than their EC fixed values as used in V1 APIs. Use the `/v2` API endpoint to be able to use `"finalized"` and be closer to the chain head when F3 is active. ([filecoin-project/lotus#13026](https://github.com/filecoin-project/lotus/pull/13026))<br>
-  Additional changes to the Ethereum APIs (both V1 and V2) introduced in this release include:
-    - `eth_getBlockTransactionCountByNumber` now takes the standard Ethereum block number specifier: hex encoded integers _or_ labels including `"latest"`, `"safe"` and `"finalized"`.
-    - All APIs that take a `BlockNumberOrHash` now handle the full range of labels: `"pending"`, `"latest"`, `"safe"`, `"finalized"` (previously only the first two were supported). These include: `eth_estimateGas`, `eth_call`, `eth_getCode`, `eth_getStorageAt`, `eth_getBalance`, `eth_getTransactionCount` and `eth_getBlockReceipts`.
-    - `EthGetTransactionByHashLimited`, `EthGetTransactionReceiptLimited` and `EthGetBlockReceiptsLimited` are no longer supported via the gateway, they are an unnecessary implementation detail.
-    - All endpoints that select by block hash or number now properly return `ErrNullRound` error types via the go-jsonrpc API and present a consistent error message via raw JSONRPC.
-    - The `"safe"` label has divergent behaviour between V1 and V2 APIs worth noting:
-      - `/v1` APIs will interpret `"safe"` as a fixed distance of 30 epochs behind `"latest"`, this is unchanged and is based on research into the stability of the chain under normal conditions.
-      - `/v2` APIs will interpret `"safe"` to be the same as `"finalized"` as long as F3 is enabled and properly functioning. In the case of F3 being inactive or otherwise not operational, it will be interpreted as a (*very* pessimistic) fixed distance of 200 epochs behind `"latest"`. This may be revised in a future update.
+- feat: Add **Lotus v2 experimental APIs with F3 awareness** ([filecoin-project/lotus#13003](https://github.com/filecoin-project/lotus/pull/13003)), ([filecoin-project/lotus#13027](https://github.com/filecoin-project/lotus/pull/13027)), ([filecoin-project/lotus#13034](https://github.com/filecoin-project/lotus/pull/13034))<br>
+  The Lotus V2 APIs introduce a powerful new TipSet selection mechanism that significantly enhances how applications interact with the Filecoin blockchain. The design reduces API footprint, seamlessly handles both traditional Expected Consensus and the new F3 protocol, and provides graceful fallbacks. See [Filecoin v2 APIs](https://filoznotebook.notion.site/Filecoin-V2-APIs-1d0dc41950c1808b914de5966d501658) for an in-depth overview.
+- feat: Introduce F3-aware Ethereum APIs via `/v2` endpoint and improve existing `/v1` APIs ([filecoin-project/lotus#13026](https://github.com/filecoin-project/lotus/pull/13026))<br>
+  Lotus now offers two versions of its Ethereum-compatible APIs (`eth_`, `trace_`, etc.) with different finality handling to make use of the upcoming F3 activation:
+  * **`/v2` APIs (New & Recommended):** These APIs fully leverage F3 finality, significantly reducing confirmation times compared to the previous fixed delays.
+    * `"finalized"` tag maps directly to the F3 finalized epoch (much closer to the chain head).
+    * `"safe"` tag maps to the F3 finalized epoch or 200 epochs behind head, whichever is more recent.
+  * **`/v1` APIs (Existing):** These maintain behavior closer to pre-F3 Lotus for compatibility.
+    * `"finalized"` tag continues to use a fixed 900-epoch delay from the head.
+    * `"safe"` tag uses a 30-epoch delay *or* the F3 finalized epoch (whichever is more recent). *After* F3 is fully active on the network, the behavior of `"safe"` on `/v1` will align with `/v2`'s `"safe"`.
+  * **Note:** Previously, `"finalized"` and `"safe"` tags referred to epochs `N-1`. This `-1` offset has been removed in both V1 and V2.
+  * Additional improvements affecting **both `/v1` and `/v2`** Ethereum APIs:
+    * `eth_getBlockTransactionCountByNumber` now accepts standard Ethereum block specifiers (hex numbers _or_ labels like `"latest"`, `"safe"`, `"finalized"`).
+    * Methods accepting `BlockNumberOrHash` now support all standard labels (`"pending"`, `"latest"`, `"safe"`, `"finalized"`). This includes `eth_estimateGas`, `eth_call`, `eth_getCode`, `eth_getStorageAt`, `eth_getBalance`, `eth_getTransactionCount`, and `eth_getBlockReceipts`.
+    * Removed internal `Eth*Limited` methods (e.g., `EthGetTransactionByHashLimited`) from the supported gateway API surface.
+    * Improved error handling: block selection endpoints now consistently return `ErrNullRound` (and corresponding JSONRPC errors) for null tipsets.
 
 # Node and Miner v1.32.2 / 2025-04-04
 

chain/types/ethtypes/eth_types.go

@@ -45,6 +45,14 @@ var ErrInvalidAddress = errors.New("invalid Filecoin Eth address")
 // See https://github.com/filecoin-project/FIPs/blob/master/FRCs/frc-0089.md
 const SafeEpochDelay = abi.ChainEpoch(30)
 
+const (
+	BlockTagEarliest  = "earliest"
+	BlockTagPending   = "pending"
+	BlockTagLatest    = "latest"
+	BlockTagFinalized = "finalized"
+	BlockTagSafe      = "safe"
+)
+
 type EthUint64 uint64
 
 func (e EthUint64) MarshalJSON() ([]byte, error) {
@@ -61,8 +69,9 @@ func (e *EthUint64) UnmarshalJSON(b []byte) error {
 		base := 10
 		if strings.HasPrefix(s, "0x") {
 			base = 16
+			s = s[2:]
 		}
-		parsedInt, err := strconv.ParseUint(strings.Replace(s, "0x", "", -1), base, 64)
+		parsedInt, err := strconv.ParseUint(s, base, 64)
 		if err != nil {
 			return err
 		}
@@ -84,6 +93,16 @@ func EthUint64FromHex(s string) (EthUint64, error) {
 	return EthUint64(parsedInt), nil
 }
 
+// EthUint64FromString parses a uint64 from a string. It accepts both decimal and hex strings.
+func EthUint64FromString(s string) (EthUint64, error) {
+	var parsedInt EthUint64
+	err := parsedInt.UnmarshalJSON([]byte(`"` + s + `"`))
+	if err != nil {
+		return 0, err
+	}
+	return parsedInt, nil
+}
+
 // EthUint64FromBytes parses a uint64 from big-endian encoded bytes.
 func EthUint64FromBytes(b []byte) (EthUint64, error) {
 	if len(b) != 32 {
@@ -1101,7 +1120,9 @@ func (e *EthBlockNumberOrHash) UnmarshalJSON(b []byte) error {
 	if err != nil {
 		return err
 	}
-	if str == "earliest" || str == "pending" || str == "latest" || str == "finalized" || str == "safe" {
+
+	switch str {
+	case BlockTagEarliest, BlockTagPending, BlockTagLatest, BlockTagFinalized, BlockTagSafe:
 		e.PredefinedBlock = &str
 		return nil
 	}

chain/types/ethtypes/eth_types_test.go

@@ -52,6 +52,10 @@ func TestEthIntUnmarshalJSON(t *testing.T) {
 		err := i.UnmarshalJSON(tc.Input.([]byte))
 		require.Nil(t, err)
 		require.Equal(t, tc.Output, i)
+
+		i, err = EthUint64FromString(strings.Replace(string(tc.Input.([]byte)), `"`, "", -1))
+		require.Nil(t, err)
+		require.Equal(t, tc.Output, i)
 	}
 }
 

itests/api_v2_test.go

@@ -125,6 +125,7 @@ func TestAPIV2_ThroughRPC(t *testing.T) {
 				name: "finalized tag is ok",
 				when: func(t *testing.T) {
 					mockF3.Running = true
+					mockF3.Finalizing = true
 					mockF3.LatestCertErr = nil
 					mockF3.LatestCert = plausibleCertAt(t, f3FinalizedEpoch)
 				},
@@ -136,6 +137,7 @@ func TestAPIV2_ThroughRPC(t *testing.T) {
 				name: "safe tag is ec safe distance when more recent than f3 finalized",
 				when: func(t *testing.T) {
 					mockF3.Running = true
+					mockF3.Finalizing = true
 					mockF3.LatestCertErr = nil
 					mockF3.LatestCert = plausibleCertAt(t, f3FinalizedEpoch)
 				},
@@ -147,6 +149,7 @@ func TestAPIV2_ThroughRPC(t *testing.T) {
 				name: "safe tag is f3 finalized when ec minus safe distance is too old",
 				when: func(t *testing.T) {
 					mockF3.Running = true
+					mockF3.Finalizing = true
 					mockF3.LatestCertErr = nil
 					mockF3.LatestCert = plausibleCertAt(t, 890)
 				},
@@ -158,6 +161,7 @@ func TestAPIV2_ThroughRPC(t *testing.T) {
 				name: "finalized tag when f3 not ready falls back to ec",
 				when: func(t *testing.T) {
 					mockF3.Running = true
+					mockF3.Finalizing = true
 					mockF3.LatestCert = nil
 					mockF3.LatestCertErr = api.ErrF3NotReady
 				},
@@ -169,6 +173,7 @@ func TestAPIV2_ThroughRPC(t *testing.T) {
 				name: "finalized tag when f3 fails is error",
 				when: func(t *testing.T) {
 					mockF3.Running = true
+					mockF3.Finalizing = true
 					mockF3.LatestCert = nil
 					mockF3.LatestCertErr = internalF3Error
 				},
@@ -180,6 +185,7 @@ func TestAPIV2_ThroughRPC(t *testing.T) {
 				name: "latest tag when f3 fails is ok",
 				when: func(t *testing.T) {
 					mockF3.Running = true
+					mockF3.Finalizing = true
 					mockF3.LatestCert = nil
 					mockF3.LatestCertErr = internalF3Error
 				},
@@ -191,6 +197,7 @@ func TestAPIV2_ThroughRPC(t *testing.T) {
 				name: "finalized tag when f3 is broken",
 				when: func(t *testing.T) {
 					mockF3.Running = true
+					mockF3.Finalizing = true
 					mockF3.LatestCert = implausibleCert
 					mockF3.LatestCertErr = nil
 				},
@@ -222,6 +229,7 @@ func TestAPIV2_ThroughRPC(t *testing.T) {
 				name: "height with no anchor before finalized epoch is ok",
 				when: func(t *testing.T) {
 					mockF3.Running = true
+					mockF3.Finalizing = true
 					mockF3.LatestCert = plausibleCertAt(t, f3FinalizedEpoch)
 					mockF3.LatestCertErr = nil
 				},
@@ -233,6 +241,7 @@ func TestAPIV2_ThroughRPC(t *testing.T) {
 				name: "height with no anchor after finalized epoch is error",
 				when: func(t *testing.T) {
 					mockF3.Running = true
+					mockF3.Finalizing = true
 					mockF3.LatestCert = plausibleCertAt(t, f3FinalizedEpoch)
 					mockF3.LatestCertErr = nil
 				},
@@ -244,6 +253,7 @@ func TestAPIV2_ThroughRPC(t *testing.T) {
 				name: "height with no anchor when f3 fails is error",
 				when: func(t *testing.T) {
 					mockF3.Running = true
+					mockF3.Finalizing = true
 					mockF3.LatestCert = nil
 					mockF3.LatestCertErr = internalF3Error
 				},
@@ -255,6 +265,7 @@ func TestAPIV2_ThroughRPC(t *testing.T) {
 				name: "height with no anchor and nil f3 cert falling back to ec fails",
 				when: func(t *testing.T) {
 					mockF3.Running = true
+					mockF3.Finalizing = true
 					mockF3.LatestCert = nil
 					mockF3.LatestCertErr = nil
 				},
@@ -266,6 +277,7 @@ func TestAPIV2_ThroughRPC(t *testing.T) {
 				name: "height with anchor to latest",
 				when: func(t *testing.T) {
 					mockF3.Running = true
+					mockF3.Finalizing = true
 					mockF3.LatestCert = plausibleCertAt(t, f3FinalizedEpoch)
 					mockF3.LatestCertErr = nil
 				},
@@ -340,6 +352,7 @@ func TestAPIV2_ThroughRPC(t *testing.T) {
 				name: "finalized tag is ok",
 				when: func(t *testing.T) {
 					mockF3.Running = true
+					mockF3.Finalizing = true
 					mockF3.LatestCertErr = nil
 					mockF3.LatestCert = plausibleCertAt(t, f3FinalizedEpoch)
 				},
@@ -351,6 +364,7 @@ func TestAPIV2_ThroughRPC(t *testing.T) {
 				name: "height with anchor to latest",
 				when: func(t *testing.T) {
 					mockF3.Running = true
+					mockF3.Finalizing = true
 					mockF3.LatestCert = plausibleCertAt(t, f3FinalizedEpoch)
 					mockF3.LatestCertErr = nil
 				},