docs: add ETH API information to V2 API documentation

documentation/en/api-experimental-user-facing-v2-docs/CLAUDE.md

@@ -20,8 +20,27 @@ This directory contains the experimental user-facing documentation for Filecoin'
 - `api-v2-experimental.md`: The main user facing documentation file that is copied to Notion.
 - Related code: `api/v2api/full.go` (API implementation)
 - Related code: `chain/types/tipset_selector.go` (Key types)
+- Related code: `node/impl/eth/api.go` (ETH V2 API implementation)
+- Related code: `node/impl/eth/tipsetresolver.go` (ETH block specifier to tipset conversion)
+- Related code: `node/impl/eth/filecoin.go` (Filecoin-specific ETH methods)
 - Generated docs: `documentation/en/api-v2-unstable-methods.md`
 
+## ETH V2 APIs Key Implementation Details
+
+The ETH V2 APIs implementation in PR #13026 introduces important changes to how block specifiers like "safe" and "finalized" work:
+
+1. **TipSet Resolution**: The file `node/impl/eth/tipsetresolver.go` contains the key logic for converting Ethereum block specifiers to Filecoin tipsets. The V2 implementation:
+   - Connects directly to the F3 subsystem for finality information
+   - Implements a more responsive definition of "safe" and "finalized" blocks
+   - Falls back gracefully to EC finality when F3 is not available
+
+2. **Block Handling**: In V2 ETH APIs, there's no longer a `-1` offset that was present in V1. This means:
+   - "latest" truly refers to the latest tipset (head)
+   - "safe" refers to either F3 finalized or head-200, whichever is more recent
+   - "finalized" directly maps to F3 finality when available
+
+3. **Request Path**: Requests to `/v2` ETH endpoints are processed through dedicated handlers that use the F3-aware tipset resolution logic, offering faster confirmation times.
+
 ## Commands
 
 ### Regenerating the Table of Contents

documentation/en/api-experimental-user-facing-v2-docs/api-v2-experimental.md

@@ -8,7 +8,8 @@
 # Meta
 ## Status
 
-- 2025-04-23: This document has been updated to account for the minimum initial set of non-ETH /v2 API groups as specified in [issue #12991](https://github.com/filecoin-project/lotus/issues/12991).
+- 2025-04-24: This document has been updated to include information about Eth APIs in `/v2`.  This was reviewed in [PR #13068](https://github.com/filecoin-project/lotus/pull/13068).
+- 2025-04-23: This document has been updated to account for the minimum initial set of non-Eth /v2 API groups as specified in [issue #12991](https://github.com/filecoin-project/lotus/issues/12991).  This was reviewed in [PR #13051](https://github.com/filecoin-project/lotus/pull/13051)
 - 2025-04-09: This document is still actively a Work In Progress. It has a draft discussing `ChainGetTipSet`. Additional APIs and API Groups will be added as part of working on [issue #12987](https://github.com/filecoin-project/lotus/issues/12987).
 
 ## Table of Contents
@@ -24,8 +25,6 @@ This ToC was generated using [Markdown All in One](https://marketplace.visualstu
   - [Table of Contents](#table-of-contents)
 - [Introduction](#introduction)
 - [The Selector Pattern](#the-selector-pattern)
-- [Overview](#overview)
-  - [Groups](#groups)
 - [Chain](#chain)
   - [ChainGetTipSet](#chaingettipset)
     - [Selector Types](#selector-types)
@@ -43,6 +42,8 @@ This ToC was generated using [Markdown All in One](https://marketplace.visualstu
     - [Parameters](#parameters-1)
     - [Request Example](#request-example-1)
     - [Response](#response-2)
+  - [Ethereum (Eth)](#ethereum-eth)
+    - [Examples](#examples)
 - [Consensus Protocol Notes](#consensus-protocol-notes)
   - [Understanding `finalized` TipSets](#understanding-finalized-tipsets)
     - [Node Configuration Impact](#node-configuration-impact)
@@ -118,19 +119,7 @@ This documentation focuses on the `TipSetSelector` as implemented in the `ChainG
 
 Each API group follows the same design principles of extensibility, expressiveness, and F3 awareness while minimising the API surface area.
 
-The remainder of this documentation explores the `TipSetSelector` in detail, showing how to use it with the `ChainGetTipSet` method through various examples and use cases.
 
-# Overview
-
-This documentation covers the TipSet selection mechanisms in the Filecoin V2 APIs, focusing on the flexible selection patterns introduced for retrieving tipsets from the Filecoin blockchain.
-
-## Groups
-
-- Chain
-    - `ChainGetTipSet`
-- State
-    - `StateGetActor`
-    - `StateGetID`
 
 # Chain
 
@@ -441,6 +430,41 @@ The method returns the ID address (string) corresponding to the input address at
 
 If the address cannot be resolved to an ID address at the specified tipset state (e.g., it never existed or was created after that tipset), an error is returned.
 
+## Ethereum (Eth)
+
+The V2 API namespace includes all the Ethereum (Eth) APIs that `/v1` supports, but the `finalized` and `safe` tags have been updated to consult the F3 subsystem (if enabled) for finality information.  `finalized` and `safe` for the "Eth" APIs has the same meaning and fallback outlined in  [Consensus Protocol Notes](#consensus-protocol-notes).  In addition, in V2, `safe` will look back a maximum 30 epochs, whereas V1 looks back 30.
+
+For a complete list of available Eth methods in V2, refer to the [V2 autogenerated documentation](https://github.com/filecoin-project/lotus/blob/master/documentation/en/api-v2-unstable-methods.md#eth).
+
+### Examples
+**Example: getting an Eth block by number using the `finalized` tag:**
+
+```json
+{
+  "jsonrpc": "2.0",
+  "method": "Eth.GetBlockByNumber",
+  "params": [
+    "finalized",
+    true
+  ],
+  "id": 1
+}
+```
+
+**Example: retrieving account balance at a `safe` block:**
+
+```json
+{
+  "jsonrpc": "2.0",
+  "method": "Eth.GetBalance",
+  "params": [
+    "0x5cbeecf99d3fdb3f25e309cc264f240bb0664031",
+    "safe"
+  ],
+  "id": 1
+}
+```
+
 # Consensus Protocol Notes
 
 The Filecoin network is currently in the process of testing and activating Filecoin Fast Finality (F3), a new consensus mechanism that provides faster finality guarantees. During this transition period, the network will contain a mix of nodes - some with F3 enabled and others still using only the traditional Expected Consensus (EC) finality mechanism.
@@ -1107,7 +1131,7 @@ JSON-RPC allows named parameters (using a JSON object instead of an array for `p
 
 ## Future API Groups
 
-The Filecoin V2 APIs initiative will expand beyond the Chain and State API groups demonstrated in this document. Each API group will follow the same principles of using selectors for expressive queries while maintaining a minimal API surface.
+The Filecoin V2 APIs initiative will expand beyond the Chain, State, and Eth API groups demonstrated in this document. Each API group will follow the same principles of using selectors for expressive queries while maintaining a minimal API surface.
 
 ### State API Group