feat: implement initial Lotus V2 State APIs (#13027)

Implement the Lotus V2 APIs for :

* `StateGetActor` - enhanced to accept tipset selector.
* `StateGetID` - enhanced to accept tipset selector / renamed from
  `LookupID` in v1 for consistency.

Tests are added to exercise the end-to-end API call through JSON rpc
with the raw wire format of the JSON-RPC request. Additional factory
functions are added for `TipSetLimit`, a new concept to specify a limit
for tipsets either as absolute height or relative to some
tipset selector. The future State message search APIs in v2 aim to use
Limit in upcoming PRs.

To unblock progress in making incremental progress at v2 apis I am
removing the implementation of StateSimulate and StateCompute in light
of discussions at #13028.

Author: masih

CHANGELOG.md

@@ -10,8 +10,13 @@
 # UNRELEASED
 
 - fix(eth): always return nil for eth transactions not found ([filecoin-project/lotus#12999](https://github.com/filecoin-project/lotus/pull/12999))
-- feat: add experimental v2 APIs that are "F3 aware."  (TODO: expand this section significantly to cover where someone learns about the new APIs, how they enable them, and what expectations they should have around them—i.e., they may change)
 - 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
+  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.
+  Pull requests:
+    - https://github.com/filecoin-project/lotus/pull/13003
+    - https://github.com/filecoin-project/lotus/pull/13027
 
 # Node and Miner v1.32.2 / 2025-04-04
 
@@ -66,7 +71,7 @@ The Lotus v1.32.1 release is a **MANDATORY patch release**, which will deliver t
 - The minimum supported Golang version is now `1.23.6` ([filecoin-project/lotus#12910](https://github.com/filecoin-project/lotus/pull/12910)).
 - The `SupportedProofTypes` field has been removed from the `Filecoin.StateGetNetworkParams` method because it was frequently overlooked during proof type updates and did not accurately reflect the FVM's supported proofs ([filecoin-project/lotus#12881](https://github.com/filecoin-project/lotus/pull/12881)).
 - Introduced `Agent` field to the `Filecoin.Version` response. Note that this change may be breaking, depending on the clients deserialization capabilities. ([filecoin-project/lotus#12904](https://github.com/filecoin-project/lotus/pull/12904)).
-- The `--only-cc` option has been removed from the `lotus-miner sectors extend` command. 
+- The `--only-cc` option has been removed from the `lotus-miner sectors extend` command.
 
 ## 🏛️ Filecoin network version 25 FIPs
 
@@ -120,7 +125,7 @@ For certain node operators, such as full archival nodes or systems that need to
 - chore: switch to pure-go zstd decoder for snapshot imports.  ([filecoin-project/lotus#12857](https://github.com/filecoin-project/lotus/pull/12857))
 - chore: upgrade go-state-types with big.Int{} change that means an empty big.Int is now treated as zero for all operations ([filecoin-project/lotus#12936](https://github.com/filecoin-project/lotus/pull/12936))
 - chore(eth): make `EthGetBlockByNumber` & `EthGetBlockByHash` share the same cache and be impacted by `EthBlkCacheSize` config settings ([filecoin-project/lotus#12979](https://github.com/filecoin-project/lotus/pull/12979))
-- chore(deps): bump go-state-types to v0.16.0-rc8 ([filecoin-project/lotus#12973](https://github.com/filecoin-project/lotus/pull/12973))  
+- chore(deps): bump go-state-types to v0.16.0-rc8 ([filecoin-project/lotus#12973](https://github.com/filecoin-project/lotus/pull/12973))
 - chore: set Mainnet nv25 upgrade epoch and update deps ([filecoin-project/lotus#12986](https://github.com/filecoin-project/lotus/pull/12986))
 - chore(eth): make EthGetBlockByNumber & EthGetBlockByHash share cache code ([filecoin-project/lotus#12979](https://github.com/filecoin-project/lotus/pull/12979))
 
@@ -186,7 +191,7 @@ This is the stable release of the **upcoming MANDATORY Lotus v1.32.0 release**,
 - The minimum supported Golang version is now `1.23.6` ([filecoin-project/lotus#12910](https://github.com/filecoin-project/lotus/pull/12910)).
 - The `SupportedProofTypes` field has been removed from the `Filecoin.StateGetNetworkParams` method because it was frequently overlooked during proof type updates and did not accurately reflect the FVM's supported proofs ([filecoin-project/lotus#12881](https://github.com/filecoin-project/lotus/pull/12881)).
 - Introduced `Agent` field to the `Filecoin.Version` response. Note that this change may be breaking, depending on the clients deserialization capabilities. ([filecoin-project/lotus#12904](https://github.com/filecoin-project/lotus/pull/12904)).
-- The `--only-cc` option has been removed from the `lotus-miner sectors extend` command. 
+- The `--only-cc` option has been removed from the `lotus-miner sectors extend` command.
 
 ## 🏛️ Filecoin network version 25 FIPs
 
@@ -239,7 +244,7 @@ For certain node operators, such as full archival nodes or systems that need to
 - chore: switch to pure-go zstd decoder for snapshot imports.  ([filecoin-project/lotus#12857](https://github.com/filecoin-project/lotus/pull/12857))
 - chore: upgrade go-state-types with big.Int{} change that means an empty big.Int is now treated as zero for all operations ([filecoin-project/lotus#12936](https://github.com/filecoin-project/lotus/pull/12936))
 - chore(eth): make `EthGetBlockByNumber` & `EthGetBlockByHash` share the same cache and be impacted by `EthBlkCacheSize` config settings ([filecoin-project/lotus#12979](https://github.com/filecoin-project/lotus/pull/12979))
-- chore(deps): bump go-state-types to v0.16.0-rc8 ([filecoin-project/lotus#12973](https://github.com/filecoin-project/lotus/pull/12973))  
+- chore(deps): bump go-state-types to v0.16.0-rc8 ([filecoin-project/lotus#12973](https://github.com/filecoin-project/lotus/pull/12973))
 - chore: set Mainnet nv25 upgrade epoch and update deps ([filecoin-project/lotus#12986](https://github.com/filecoin-project/lotus/pull/12986))
 - chore(eth): make EthGetBlockByNumber & EthGetBlockByHash share cache code ([filecoin-project/lotus#12979](https://github.com/filecoin-project/lotus/pull/12979))
 
@@ -420,8 +425,8 @@ This is the final release of the MANDATORY Lotus v1.30.0 release, which delivers
 - If you are running the v1.28.x version of Lotus, please go through the Upgrade Warnings section for the v1.28.* releases and v1.29.*, before upgrading to this release.
 - This release requires a minimum Go version of v1.22.7 or higher.
 - The `releases` branch has been deprecated with the 202408 split of 'Lotus Node' and 'Lotus Miner'. See https://github.com/filecoin-project/lotus/blob/master/LOTUS_RELEASE_FLOW.md#why-is-the-releases-branch-deprecated-and-what-are-alternatives for more info and alternatives for getting the latest release for both the 'Lotus Node' and 'Lotus Miner' based on the Branch and Tag Strategy.
-   - To get the latest Lotus Node tag: git tag -l 'v*' | sort -V -r | head -n 1
-   - To get the latest Lotus Miner tag: git tag -l 'miner/v*' | sort -V -r | head -n 1
+  - To get the latest Lotus Node tag: git tag -l 'v*' | sort -V -r | head -n 1
+  - To get the latest Lotus Miner tag: git tag -l 'miner/v*' | sort -V -r | head -n 1
 
 ## 🏛️ Filecoin network version 24 FIPs
 
@@ -532,4 +537,4 @@ For the set of changes since the last stable release:
 | DemoYeti | 1 | +2/-1 | 1 |
 | qwdsds | 1 | +1/-1 | 1 |
 | Samuel Arogbonlo | 1 | +2/-0 | 2 |
-| Elias Rad | 1 | +1/-1 | 1 |
+| Elias Rad | 1 | +1/-1 | 1 |

api/v2api/full.go

@@ -3,6 +3,8 @@ package v2api
 import (
 	"context"
 
+	"github.com/filecoin-project/go-address"
+
 	"github.com/filecoin-project/lotus/chain/types"
 )
 
@@ -49,4 +51,51 @@ type FullNode interface {
 	//	fmt.Printf("Latest TipSet: %v\n", tipSet)
 	//
 	ChainGetTipSet(context.Context, types.TipSetSelector) (*types.TipSet, error) //perm:read
+
+	// MethodGroup: State
+	// The State method group contains methods for interacting with the Filecoin
+	// blockchain state, including actor information, addresses, and chain data.
+	// These methods allow querying the blockchain state at any point in its history
+	// using flexible TipSet selection mechanisms.
+
+	// StateGetActor retrieves the actor information for the specified address at the
+	// selected tipset.
+	//
+	// This function returns the on-chain Actor object including:
+	//   - Code CID (determines the actor's type)
+	//   - State root CID
+	//   - Balance in attoFIL
+	//   - Nonce (for account actors)
+	//
+	// The TipSetSelector parameter provides flexible options for selecting the tipset:
+	//   - TipSetSelectors.Latest: the most recent tipset with the heaviest weight
+	//   - TipSetSelectors.Finalized: the most recent finalized tipset
+	//   - TipSetSelectors.Height(epoch, previous, anchor): tipset at the specified height
+	//   - TipSetSelectors.Key(key): tipset with the specified key
+	//
+	// See types.TipSetSelector documentation for additional details.
+	//
+	// If the actor does not exist at the specified tipset, this function returns nil.
+	//
+	// Experimental: This API is experimental and may change without notice.
+	StateGetActor(context.Context, address.Address, types.TipSetSelector) (*types.Actor, error) //perm:read
+
+	// StateGetID retrieves the ID address for the specified address at the selected tipset.
+	//
+	// Every actor on the Filecoin network has a unique ID address (format: f0123).
+	// This function resolves any address type (ID, robust, or delegated) to its canonical
+	// ID address representation at the specified tipset.
+	//
+	// The function is particularly useful for:
+	//   - Normalizing different address formats to a consistent representation
+	//   - Following address changes across state transitions
+	//   - Verifying that an address corresponds to an existing actor
+	//
+	// The TipSetSelector parameter provides flexible options for selecting the tipset.
+	// See StateGetActor documentation for details on selection options.
+	//
+	// If the address cannot be resolved at the specified tipset, this function returns nil.
+	//
+	// Experimental: This API is experimental and may change without notice.
+	StateGetID(context.Context, address.Address, types.TipSetSelector) (*address.Address, error) //perm:read
 }