Extend block parameter methods to accept 'finalized' and 'safe' as block tags (#3950)

Signed-off-by: Fabio Di Fabio <fabio.difabio@consensys.net>

CHANGELOG.md

@@ -4,6 +4,7 @@
 
 ### Additions and Improvements
 - \[EXPERIMENTAL\] Add checkpoint sync `--sync-mode="X_CHECKPOINT"` [#3849](https://github.com/hyperledger/besu/pull/3849)
+- Support `finalized` and `safe` as tags for the block parameter in RPC APIs [#3950](https://github.com/hyperledger/besu/pull/3950)
 
 ### Bug Fixes
 

ethereum/api/src/main/java/org/hyperledger/besu/ethereum/api/jsonrpc/internal/methods/AbstractBlockParameterMethod.java

@@ -16,12 +16,15 @@ package org.hyperledger.besu.ethereum.api.jsonrpc.internal.methods;
 
 import org.hyperledger.besu.ethereum.api.jsonrpc.internal.JsonRpcRequestContext;
 import org.hyperledger.besu.ethereum.api.jsonrpc.internal.parameters.BlockParameter;
+import org.hyperledger.besu.ethereum.api.jsonrpc.internal.response.JsonRpcError;
 import org.hyperledger.besu.ethereum.api.jsonrpc.internal.response.JsonRpcErrorResponse;
 import org.hyperledger.besu.ethereum.api.jsonrpc.internal.response.JsonRpcResponse;
 import org.hyperledger.besu.ethereum.api.jsonrpc.internal.response.JsonRpcSuccessResponse;
 import org.hyperledger.besu.ethereum.api.query.BlockchainQueries;
+import org.hyperledger.besu.ethereum.core.BlockHeader;
 
 import java.util.Optional;
+import java.util.function.Function;
 import java.util.function.Supplier;
 
 import com.google.common.base.Suppliers;
@@ -57,21 +60,41 @@ public abstract class AbstractBlockParameterMethod implements JsonRpcMethod {
     return resultByBlockNumber(request, blockchainQueriesSupplier.get().headBlockNumber());
   }
 
+  protected Object finalizedResult(final JsonRpcRequestContext request) {
+    return posRelatedResult(request, BlockchainQueries::finalizedBlockHeader);
+  }
+
+  protected Object safeResult(final JsonRpcRequestContext request) {
+    return posRelatedResult(request, BlockchainQueries::safeBlockHeader);
+  }
+
+  private Object posRelatedResult(
+      final JsonRpcRequestContext request,
+      final Function<BlockchainQueries, Optional<BlockHeader>> blockHeaderSupplier) {
+
+    return blockHeaderSupplier
+        .apply(blockchainQueriesSupplier.get())
+        .map(header -> resultByBlockNumber(request, header.getNumber()))
+        .orElseGet(
+            () ->
+                new JsonRpcErrorResponse(request.getRequest().getId(), JsonRpcError.UNKNOWN_BLOCK));
+  }
+
   protected Object findResultByParamType(final JsonRpcRequestContext request) {
     final BlockParameter blockParam = blockParameter(request);
-
-    final Object result;
     final Optional<Long> blockNumber = blockParam.getNumber();
+
     if (blockNumber.isPresent()) {
-      result = resultByBlockNumber(request, blockNumber.get());
+      return resultByBlockNumber(request, blockNumber.get());
     } else if (blockParam.isLatest()) {
-      result = latestResult(request);
+      return latestResult(request);
+    } else if (blockParam.isFinalized()) {
+      return finalizedResult(request);
+    } else if (blockParam.isSafe()) {
+      return safeResult(request);
     } else {
-      // If block parameter is not numeric or latest, it is pending.
-      result = pendingResult(request);
+      return pendingResult(request);
     }
-
-    return result;
   }
 
   @Override

ethereum/api/src/main/java/org/hyperledger/besu/ethereum/api/jsonrpc/internal/parameters/BlockParameter.java

@@ -21,8 +21,8 @@ import java.util.Optional;
 
 import com.fasterxml.jackson.annotation.JsonCreator;
 
-// Represents a block parameter that can be a special value ("pending", "earliest", "latest") or
-// a number formatted as a hex string.
+// Represents a block parameter that can be a special value ("pending", "earliest", "latest",
+// "finalized", "safe") or a number formatted as a hex string.
 // See: https://github.com/ethereum/wiki/wiki/JSON-RPC#the-default-block-parameter
 public class BlockParameter {
 
@@ -31,6 +31,8 @@ public class BlockParameter {
   public static final BlockParameter EARLIEST = new BlockParameter("earliest");
   public static final BlockParameter LATEST = new BlockParameter("latest");
   public static final BlockParameter PENDING = new BlockParameter("pending");
+  public static final BlockParameter FINALIZED = new BlockParameter("finalized");
+  public static final BlockParameter SAFE = new BlockParameter("safe");
 
   @JsonCreator
   public BlockParameter(final String value) {
@@ -49,6 +51,14 @@ public class BlockParameter {
         type = BlockParameterType.PENDING;
         number = Optional.empty();
         break;
+      case "finalized":
+        type = BlockParameterType.FINALIZED;
+        number = Optional.empty();
+        break;
+      case "safe":
+        type = BlockParameterType.SAFE;
+        number = Optional.empty();
+        break;
       default:
         type = BlockParameterType.NUMERIC;
         number = Optional.of(Long.decode(value));
@@ -77,6 +87,14 @@ public class BlockParameter {
     return this.type == BlockParameterType.EARLIEST;
   }
 
+  public boolean isFinalized() {
+    return this.type == BlockParameterType.FINALIZED;
+  }
+
+  public boolean isSafe() {
+    return this.type == BlockParameterType.SAFE;
+  }
+
   public boolean isNumeric() {
     return this.type == BlockParameterType.NUMERIC;
   }
@@ -103,6 +121,8 @@ public class BlockParameter {
     EARLIEST,
     LATEST,
     PENDING,
-    NUMERIC
+    NUMERIC,
+    FINALIZED,
+    SAFE
   }
 }

ethereum/api/src/main/java/org/hyperledger/besu/ethereum/api/jsonrpc/internal/response/JsonRpcError.java

@@ -33,6 +33,9 @@ public enum JsonRpcError {
 
   METHOD_NOT_ENABLED(-32604, "Method not enabled"),
 
+  // eth_getBlockByNumber specific error message
+  UNKNOWN_BLOCK(-39001, "Unknown block"),
+
   // eth_sendTransaction specific error message
   ETH_SEND_TX_NOT_AVAILABLE(
       -32604,

ethereum/api/src/main/java/org/hyperledger/besu/ethereum/api/query/BlockchainQueries.java

@@ -139,6 +139,24 @@ public class BlockchainQueries {
     return blockchain.getChainHeadBlockNumber();
   }
 
+  /**
+   * Return the header of the last finalized block.
+   *
+   * @return The header of the last finalized block.
+   */
+  public Optional<BlockHeader> finalizedBlockHeader() {
+    return blockchain.getFinalized().flatMap(blockchain::getBlockHeader);
+  }
+
+  /**
+   * Return the header of the last safe block.
+   *
+   * @return The header of the last safe block.
+   */
+  public Optional<BlockHeader> safeBlockHeader() {
+    return blockchain.getSafeBlock().flatMap(blockchain::getBlockHeader);
+  }
+
   /**
    * Determines the block header for the address associated with this storage index.
    *

ethereum/api/src/test/java/org/hyperledger/besu/ethereum/api/jsonrpc/internal/methods/EthGetBlockByNumberTest.java

@@ -0,0 +1,189 @@
+/*
+ * Copyright Hyperledger Besu Contributors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on
+ * an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations under the License.
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+package org.hyperledger.besu.ethereum.api.jsonrpc.internal.methods;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.assertj.core.api.Assertions.assertThatThrownBy;
+import static org.hyperledger.besu.ethereum.core.InMemoryKeyValueStorageProvider.createInMemoryBlockchain;
+import static org.mockito.Mockito.spy;
+import static org.mockito.Mockito.verifyNoMoreInteractions;
+import static org.mockito.Mockito.when;
+
+import org.hyperledger.besu.ethereum.api.jsonrpc.internal.JsonRpcRequest;
+import org.hyperledger.besu.ethereum.api.jsonrpc.internal.JsonRpcRequestContext;
+import org.hyperledger.besu.ethereum.api.jsonrpc.internal.exception.InvalidJsonRpcParameters;
+import org.hyperledger.besu.ethereum.api.jsonrpc.internal.response.JsonRpcError;
+import org.hyperledger.besu.ethereum.api.jsonrpc.internal.response.JsonRpcErrorResponse;
+import org.hyperledger.besu.ethereum.api.jsonrpc.internal.response.JsonRpcResponse;
+import org.hyperledger.besu.ethereum.api.jsonrpc.internal.response.JsonRpcResponseType;
+import org.hyperledger.besu.ethereum.api.jsonrpc.internal.response.JsonRpcSuccessResponse;
+import org.hyperledger.besu.ethereum.api.jsonrpc.internal.results.BlockResult;
+import org.hyperledger.besu.ethereum.api.jsonrpc.internal.results.BlockResultFactory;
+import org.hyperledger.besu.ethereum.api.query.BlockchainQueries;
+import org.hyperledger.besu.ethereum.chain.MutableBlockchain;
+import org.hyperledger.besu.ethereum.core.Block;
+import org.hyperledger.besu.ethereum.core.BlockDataGenerator;
+import org.hyperledger.besu.ethereum.core.BlockHeader;
+import org.hyperledger.besu.ethereum.core.Synchronizer;
+import org.hyperledger.besu.ethereum.core.TransactionReceipt;
+import org.hyperledger.besu.ethereum.worldstate.WorldStateArchive;
+
+import java.util.List;
+
+import org.junit.Before;
+import org.junit.Test;
+import org.junit.runner.RunWith;
+import org.mockito.Mock;
+import org.mockito.junit.MockitoJUnitRunner;
+
+@RunWith(MockitoJUnitRunner.class)
+public class EthGetBlockByNumberTest {
+  private static final String JSON_RPC_VERSION = "2.0";
+  private static final String ETH_METHOD = "eth_getBlockByNumber";
+  private static final int BLOCKCHAIN_LENGTH = 4;
+  private static final int FINALIZED_BLOCK_HEIGHT = 1;
+  private static final int SAFE_BLOCK_HEIGHT = 2;
+  private static final BlockDataGenerator blockDataGenerator = new BlockDataGenerator();
+
+  private final BlockResultFactory blockResult = new BlockResultFactory();
+  private BlockchainQueries blockchainQueries;
+  private MutableBlockchain blockchain;
+  private EthGetBlockByNumber method;
+  @Mock private Synchronizer synchronizer;
+  @Mock private WorldStateArchive worldStateArchive;
+
+  @Before
+  public void setUp() {
+    blockchain = createInMemoryBlockchain(blockDataGenerator.genesisBlock());
+
+    for (int i = 1; i < BLOCKCHAIN_LENGTH; i++) {
+      final BlockDataGenerator.BlockOptions options =
+          new BlockDataGenerator.BlockOptions()
+              .setBlockNumber(i)
+              .setParentHash(blockchain.getBlockHashByNumber(i - 1).orElseThrow());
+      final Block block = blockDataGenerator.block(options);
+      final List<TransactionReceipt> receipts = blockDataGenerator.receipts(block);
+
+      blockchain.appendBlock(block, receipts);
+    }
+
+    BlockHeader lastestHeader = blockchain.getChainHeadBlock().getHeader();
+    when(worldStateArchive.isWorldStateAvailable(
+            lastestHeader.getStateRoot(), lastestHeader.getHash()))
+        .thenReturn(Boolean.TRUE);
+
+    blockchainQueries = spy(new BlockchainQueries(blockchain, worldStateArchive));
+
+    method = new EthGetBlockByNumber(blockchainQueries, blockResult, synchronizer);
+  }
+
+  @Test
+  public void returnsCorrectMethodName() {
+    assertThat(method.getName()).isEqualTo(ETH_METHOD);
+  }
+
+  @Test
+  public void exceptionWhenNoParamsSupplied() {
+    assertThatThrownBy(() -> method.response(requestWithParams()))
+        .isInstanceOf(InvalidJsonRpcParameters.class);
+    verifyNoMoreInteractions(blockchainQueries);
+  }
+
+  @Test
+  public void exceptionWhenNoNumberSupplied() {
+    assertThatThrownBy(() -> method.response(requestWithParams("false")))
+        .isInstanceOf(InvalidJsonRpcParameters.class);
+    verifyNoMoreInteractions(blockchainQueries);
+  }
+
+  @Test
+  public void exceptionWhenNoBoolSupplied() {
+    assertThatThrownBy(() -> method.response(requestWithParams("0")))
+        .isInstanceOf(InvalidJsonRpcParameters.class)
+        .hasMessage("Missing required json rpc parameter at index 1");
+    verifyNoMoreInteractions(blockchainQueries);
+  }
+
+  @Test
+  public void exceptionWhenNumberParamInvalid() {
+    assertThatThrownBy(() -> method.response(requestWithParams("invalid", "true")))
+        .isInstanceOf(InvalidJsonRpcParameters.class)
+        .hasMessage("Invalid json rpc parameter at index 0");
+    verifyNoMoreInteractions(blockchainQueries);
+  }
+
+  @Test
+  public void exceptionWhenBoolParamInvalid() {
+    assertThatThrownBy(() -> method.response(requestWithParams("0", "maybe")))
+        .isInstanceOf(InvalidJsonRpcParameters.class)
+        .hasMessage("Invalid json rpc parameter at index 1");
+    verifyNoMoreInteractions(blockchainQueries);
+  }
+
+  @Test
+  public void errorWhenAskingFinalizedButFinalizedIsNotPresent() {
+    JsonRpcResponse resp = method.response(requestWithParams("finalized", "false"));
+    assertThat(resp.getType()).isEqualTo(JsonRpcResponseType.ERROR);
+    JsonRpcErrorResponse errorResp = (JsonRpcErrorResponse) resp;
+    assertThat(errorResp.getError()).isEqualTo(JsonRpcError.UNKNOWN_BLOCK);
+  }
+
+  @Test
+  public void errorWhenAskingSafeButSafeIsNotPresent() {
+    JsonRpcResponse resp = method.response(requestWithParams("safe", "false"));
+    assertThat(resp.getType()).isEqualTo(JsonRpcResponseType.ERROR);
+    JsonRpcErrorResponse errorResp = (JsonRpcErrorResponse) resp;
+    assertThat(errorResp.getError()).isEqualTo(JsonRpcError.UNKNOWN_BLOCK);
+  }
+
+  @Test
+  public void successWhenAskingEarliest() {
+    assertSuccess("earliest", 0L);
+  }
+
+  @Test
+  public void successWhenAskingLatest() {
+    assertSuccess("latest", BLOCKCHAIN_LENGTH - 1);
+  }
+
+  @Test
+  public void successWhenAskingFinalized() {
+    assertSuccessPos("finalized", FINALIZED_BLOCK_HEIGHT);
+  }
+
+  @Test
+  public void successWhenAskingSafe() {
+    assertSuccessPos("safe", SAFE_BLOCK_HEIGHT);
+  }
+
+  private void assertSuccess(final String tag, final long height) {
+    JsonRpcResponse resp = method.response(requestWithParams(tag, "false"));
+    assertThat(resp.getType()).isEqualTo(JsonRpcResponseType.SUCCESS);
+    JsonRpcSuccessResponse successResp = (JsonRpcSuccessResponse) resp;
+    BlockResult blockResult = (BlockResult) successResp.getResult();
+    assertThat(blockResult.getHash())
+        .isEqualTo(blockchain.getBlockHashByNumber(height).get().toString());
+  }
+
+  private void assertSuccessPos(final String tag, final long height) {
+    blockchain.setSafeBlock(blockchain.getBlockByNumber(SAFE_BLOCK_HEIGHT).get().getHash());
+    blockchain.setFinalized(blockchain.getBlockByNumber(FINALIZED_BLOCK_HEIGHT).get().getHash());
+    assertSuccess(tag, height);
+  }
+
+  private JsonRpcRequestContext requestWithParams(final Object... params) {
+    return new JsonRpcRequestContext(new JsonRpcRequest(JSON_RPC_VERSION, ETH_METHOD, params));
+  }
+}