Add forest api test-stateful subcommand

.config/forest.dic

@@ -16,6 +16,7 @@ blockstore/SM
 BLS
 butterflynet
 calibnet
+calldata
 callee
 canonicalization
 CAR/SM
@@ -51,6 +52,7 @@ Ethereum
 eth
 exa
 EVM
+f4
 F3
 FFI
 FIL

.github/workflows/forest.yml

@@ -396,7 +396,39 @@
           chmod +x ~/.cargo/bin/forest*
       - run: ./scripts/tests/calibnet_eth_mapping_check.sh
         timeout-minutes: ${{ fromJSON(env.SCRIPT_TIMEOUT_MINUTES) }}
+  calibnet-api-test-stateful:
+    needs:
+      - build-ubuntu
+    name: Calibnet api test-stateful check
+    runs-on: ubuntu-24.04
+    steps:
+      - run: lscpu
+      - uses: actions/cache@v4
+        with:
+          path: "${{ env.FIL_PROOFS_PARAMETER_CACHE }}"
+          key: proof-params-keys
+      - name: Checkout Sources
+        uses: actions/checkout@v4
+      - uses: actions/download-artifact@v5
+        with:
+          name: "forest-${{ runner.os }}"
+          path: ~/.cargo/bin
+      - uses: actions/download-artifact@v4
+        with:
+          name: "forest-${{ runner.os }}"
+          path: ~/.cargo/bin
+      - name: Set permissions
+        run: |
+          chmod +x ~/.cargo/bin/forest*
+      - name: Api test stateful check
+        env:
+          CALIBNET_WALLET: "${{ secrets.CALIBNET_WALLET }}"
+        run: |
+          if [[ "$CALIBNET_WALLET" != "" ]]; then
+            ./scripts/tests/calibnet_api_test_stateful_check.sh "$CALIBNET_WALLET"
+          fi
+        timeout-minutes: ${{ fromJSON(env.SCRIPT_TIMEOUT_MINUTES) }}
   db-migration-checks:
     needs:
       - build-ubuntu
     runs-on: ubuntu-24.04
@@ -603,6 +635,7 @@
       - calibnet-no-discovery-checks
       - calibnet-kademlia-checks
       - calibnet-eth-mapping-check
+      - calibnet-api-test-stateful
       - db-migration-checks
       - local-devnet-check
       # - local-devnet-curio-check

Cargo.toml

@@ -208,6 +208,7 @@ tera = { version = "1", default-features = false }
 thiserror = "2"
 tokio = { version = "1", features = ['full'] }
 tokio-stream = { version = "0.1", features = ["fs", "io-util"] }
+tokio-tungstenite = "0.27.0"
 tokio-util = { version = "0.7", features = ["compat", "io-util"] }
 toml = "0.8"
 tower = { version = "0.5", features = ["util"] }

documentation/src/developer_documentation/rpc_stateful_tests.md

@@ -0,0 +1,76 @@
+# RPC Stateful Tests
+
+Some methods in the Filecoin Ethereum JSON-RPC API require stateful interactions for meaningful testing. These tests validate both **schema compatibility** and **method semantics**, especially for RPC endpoints that rely on internal node state.
+
+This includes:
+
+- All subscription-based methods
+- Filter-related methods (e.g., `eth_newFilter`, `eth_getFilterLogs`)
+
+## Prerequisites
+
+Before running the tests, perform the following setup steps:
+
+1. Run a Lotus or Forest node (calibnet recommended). Make sure `FULLNODE_API_INFO` is defined.
+2. Create an f4 address, fund it, and deploy a test smart contract (the deployed contract must emit an event with a known topic when invoked).
+3. The f4 address must hold enough FIL to invoke the contract.
+
+   Run the test suite with:
+  `forest-tool api test-stateful --to <CONTRACT_ADDR> --from <FROM_ADDR> --payload <INVOKE_PAYLOAD> --topic <TOPIC>`
+
+   where:
+
+    - `CONTRACT_ADDR`: f4 address of the deployed smart contract
+    - `FROM_ADDR`: f4 address invoking the contract
+    - `INVOKE_PAYLOAD`: Calldata that will trigger the contract's event
+    - `TOPIC`: The event topic expected to be emitted during invocation
+
+## Example output
+
+```console
+export FULLNODE_API_INFO="<TOKEN>:/ip4/127.0.0.1/tcp/1234/http"
+forest-tool api test-stateful \
+  --to t410f2jhqlciub25ad3immo5kug2fluj625xiex6lbyi \
+  --from t410f5uudc3yoiodsva73rxyx5sxeiaadpaplsu6mofy \
+  --payload 40c10f19000000000000000000000000ed28316f0e43872a83fb8df17ecae440003781eb00000000000000000000000000000000000000000000000006f05b59d3b20000 \
+  --topic 0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef
+running 7 tests
+test eth_newFilter install/uninstall ... ok
+test eth_newFilter under limit ... ok
+test eth_newFilter just under limit ... ok
+test eth_newFilter over limit ... ok
+test eth_newBlockFilter works ... ok
+test eth_newPendingTransactionFilter works ... ok
+test eth_getFilterLogs works ... ok
+test result: ok. 7 passed; 0 failed; 0 ignored; 0 filtered out
+```
+
+The goal is to ensure that Forest now passes all the existing scenarios. These scenarios are not exhaustive, and additional ones can be added as needed.
+
+## Adding a new test
+
+To extend test coverage for another RPC method or cover more semantics:
+
+1. Add the RPC method to Forest if not yet implemented, following the guidance in [RPC compatibility guide](./rpc_api_compatibility.md).
+2. Create a new test scenario in:
+[`stateful_tests.rs`](../../../src/tool/subcommands/api_cmd/stateful_tests.rs)
+3. Your internal test function should return `Ok(())` on success. Use `anyhow::Result` for error handling.
+
+   Ensure the test behaves consistently on both Lotus and Forest nodes.
+
+## Example test function
+```rust
+pub async fn test_eth_method(client: Arc<Client>) -> anyhow::Result<()> {
+    // Setup call to the method
+    // Assert intermediate states
+    // State cleanup
+    // Return Ok when the sequence completes successfully
+    Ok(())
+}
+```
+
+## Notes
+
+The current test framework assumes a running node and a valid wallet.
+
+Consider implementing `forest-tool evm deploy` and `forest-tool evm invoke` subcommands to simplify contract deployment and test invocation.

scripts/tests/calibnet_api_test_stateful_check.sh

@@ -0,0 +1,34 @@
+#!/usr/bin/env bash
+# This script tests RPC API stateful tests on a live forest node.
+# It requires both `forest`, `forest-wallet` and `forest-tool` to be in the PATH.
+
+set -euxo pipefail
+
+source "$(dirname "$0")/harness.sh"
+
+
+forest_init "$@"
+
+# This is the address of a Calibnet pre-deployed simple ERC20 contract.
+# You can find the hex and source code in 'src/tool/subcommands/api_cmd/contracts/erc20'.
+TO_ADDRESS="t410fp6e7drelxau7nf76tcn6gva22t5jafefhevubwi"
+
+FROM_ADDRESS="t410f2avianksmit2cl2bqk53qant7nm7rdmk63twa5y"
+
+# This payload corresponds to minting new tokens for the 'FROM_ADDRESS' and will trigger a log event upon success.
+# To compute the calldata, you can use the 'cast calldata' subcommand with the following arguments:
+# cast calldata "mint(address,uint256)" 0x7f89f1c48bb829f697fe989be3541ad4fa901485 1000000000000000000
+#
+# Note that 0x7f89f1c48bb829f697fe989be3541ad4fa901485 is the Ethereum address corresponding to the contract f4 address.
+PAYLOAD="0x40c10f190000000000000000000000007f89f1c48bb829f697fe989be3541ad4fa9014850000000000000000000000000000000000000000000000000de0b6b3a7640000"
+
+# This topic is derived using the keccak256 hash of the event signature 'Mint(address,uint256)'
+# To compute the topic, you can use the 'cast keccak256' subcommand with the following argument:
+# cast keccak256 "Mint(address,uint256)"
+TOPIC="0x0f6798a560793a54c3bcfe86a93cde1e73087d944c0ea20544137d4121396885"
+
+$FOREST_TOOL_PATH api test-stateful \
+  --to "$TO_ADDRESS" \
+  --from "$FROM_ADDRESS" \
+  --payload "$PAYLOAD" \
+  --topic "$TOPIC"

scripts/tests/harness.sh

@@ -139,6 +139,12 @@ function forest_init {
   forest_wait_api
   forest_wait_for_sync
   forest_check_db_stats
+
+  DATA_DIR=$( $FOREST_CLI_PATH config dump | grep "data_dir" | cut -d' ' -f3- | tr -d '"' )
+  ADMIN_TOKEN=$(cat "${DATA_DIR}/token")
+  FULLNODE_API_INFO="${ADMIN_TOKEN}:/ip4/127.0.0.1/tcp/2345/http"
+
+  export FULLNODE_API_INFO
 }
 
 function forest_init_with_f3 {

src/eth/mod.rs

@@ -4,7 +4,7 @@
 mod eip_1559_transaction;
 mod eip_155_transaction;
 mod homestead_transaction;
-mod transaction;
+pub mod transaction;
 
 pub use eip_155_transaction::*;
 pub use eip_1559_transaction::*;

src/eth/transaction.rs

@@ -60,6 +60,7 @@ pub enum EVMMethod {
 
 /// Ethereum transaction which can be of different types.
 /// The currently supported types are defined in [FIP-0091](https://github.com/filecoin-project/FIPs/blob/020bcb412ee20a2879b4a710337959c51b938d3b/FIPS/fip-0091.md).
+#[derive(Debug)]
 pub enum EthTx {
     Homestead(Box<EthLegacyHomesteadTxArgs>),
     Eip1559(Box<EthEip1559TxArgs>),
@@ -155,7 +156,7 @@ impl EthTx {
         }
     }
 
-    fn rlp_signed_message(&self) -> anyhow::Result<Vec<u8>> {
+    pub fn rlp_signed_message(&self) -> anyhow::Result<Vec<u8>> {
         match self {
             Self::Homestead(tx) => (*tx).rlp_signed_message(),
             Self::Eip1559(tx) => (*tx).rlp_signed_message(),

src/rpc/channel.rs

@@ -246,7 +246,7 @@ fn create_notif_message(
 ) -> anyhow::Result<Box<RawValue>> {
     let method = sink.method_name();
     let channel_id = sink.channel_id();
-    let result = serde_json::to_string(result)?;
+    let result = serde_json::to_value(result)?;
     let msg = serde_json::json!({
         "jsonrpc": "2.0",
         "method": method,

src/rpc/methods/eth.rs

@@ -213,6 +213,10 @@ impl EthUint64 {
                 .try_into()?,
         )))
     }
+
+    pub fn to_hex_string(&self) -> String {
+        format!("0x{}", hex::encode(self.0.to_be_bytes()))
+    }
 }
 
 #[derive(
@@ -3038,14 +3042,16 @@ fn eth_filter_result_from_events<DB: Blockstore>(
 }
 
 fn eth_filter_result_from_tipsets(events: &[CollectedEvent]) -> anyhow::Result<EthFilterResult> {
-    Ok(EthFilterResult::Txs(eth_filter_logs_from_tipsets(events)?))
+    Ok(EthFilterResult::Hashes(eth_filter_logs_from_tipsets(
+        events,
+    )?))
 }
 
 fn eth_filter_result_from_messages<DB: Blockstore>(
     ctx: &Ctx<DB>,
     events: &[CollectedEvent],
 ) -> anyhow::Result<EthFilterResult> {
-    Ok(EthFilterResult::Txs(eth_filter_logs_from_messages(
+    Ok(EthFilterResult::Hashes(eth_filter_logs_from_messages(
         ctx, events,
     )?))
 }

src/rpc/methods/eth/types.rs

@@ -556,17 +556,15 @@ impl From<LogFilter> for EthFilterSpec {
 #[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
 #[serde(untagged)]
 pub enum EthFilterResult {
-    Blocks(Vec<EthHash>),
-    Txs(Vec<EthHash>),
+    Hashes(Vec<EthHash>),
     Logs(Vec<EthLog>),
 }
 lotus_json_with_self!(EthFilterResult);
 
 impl EthFilterResult {
     pub fn is_empty(&self) -> bool {
         match self {
-            Self::Blocks(v) => v.is_empty(),
-            Self::Txs(v) => v.is_empty(),
+            Self::Hashes(v) => v.is_empty(),
             Self::Logs(v) => v.is_empty(),
         }
     }
@@ -575,8 +573,7 @@ impl EthFilterResult {
 impl PartialEq for EthFilterResult {
     fn eq(&self, other: &Self) -> bool {
         match (self, other) {
-            (Self::Blocks(a), Self::Blocks(b)) => a == b,
-            (Self::Txs(a), Self::Txs(b)) => a == b,
+            (Self::Hashes(a), Self::Hashes(b)) => a == b,
             (Self::Logs(a), Self::Logs(b)) => a == b,
             _ => self.is_empty() && other.is_empty(),
         }