feat(node): integrating topdown cert into interpreters

Cargo.toml

@@ -127,6 +127,7 @@ multihash = { version = "0.18.1", default-features = false, features = [
 ] }
 num-bigint = "0.4"
 num-derive = "0.3"
+num-rational = "0.4.1"
 num-traits = "0.2"
 num_enum = "0.7.2"
 paste = "1"

contracts/contracts/errors/IPCErrors.sol

@@ -61,7 +61,7 @@ error NotValidator(address);
 error OldConfigurationNumber();
 error PQDoesNotContainAddress();
 error PQEmpty();
-error ParentFinalityAlreadyCommitted();
+error TopdownCheckpointAlreadyCommitted();
 error PostboxNotExist();
 error SignatureReplay();
 error SubnetAlreadyKilled();

contracts/contracts/gateway/GatewayGetterFacet.sol

@@ -1,7 +1,7 @@
 // SPDX-License-Identifier: MIT OR Apache-2.0
 pragma solidity ^0.8.23;
 
-import {BottomUpCheckpoint, BottomUpMsgBatch, IpcEnvelope, ParentFinality} from "../structs/CrossNet.sol";
+import {BottomUpCheckpoint, BottomUpMsgBatch, IpcEnvelope, TopdownCheckpoint} from "../structs/CrossNet.sol";
 import {QuorumInfo} from "../structs/Quorum.sol";
 import {SubnetID, Subnet} from "../structs/Subnet.sol";
 import {Membership} from "../structs/Subnet.sol";
@@ -71,13 +71,13 @@ contract GatewayGetterFacet {
 
     /// @notice Returns the parent chain finality information for a given block number.
     /// @param blockNumber The block number for which to retrieve parent-finality information.
-    function getParentFinality(uint256 blockNumber) external view returns (ParentFinality memory) {
-        return LibGateway.getParentFinality(blockNumber);
+    function getTopdownCheckpoint(uint256 blockNumber) external view returns (TopdownCheckpoint memory) {
+        return LibGateway.getTopdownCheckpoint(blockNumber);
     }
 
     /// @notice Gets the most recent parent-finality information from the parent.
-    function getLatestParentFinality() external view returns (ParentFinality memory) {
-        return LibGateway.getLatestParentFinality();
+    function getLatestTopdownCheckpoint() external view returns (TopdownCheckpoint memory) {
+        return LibGateway.getLatestTopdownCheckpoint();
     }
 
     /// @notice Returns the subnet with the given id.

contracts/contracts/gateway/router/TopDownFinalityFacet.sol

@@ -2,7 +2,7 @@
 pragma solidity ^0.8.23;
 
 import {GatewayActorModifiers} from "../../lib/LibGatewayActorStorage.sol";
-import {ParentFinality} from "../../structs/CrossNet.sol";
+import {TopdownCheckpoint} from "../../structs/CrossNet.sol";
 import {PermissionMode, Validator, ValidatorInfo, StakingChangeRequest, Membership} from "../../structs/Subnet.sol";
 import {LibGateway} from "../../lib/LibGateway.sol";
 
@@ -16,17 +16,17 @@ contract TopDownFinalityFacet is GatewayActorModifiers {
     using LibValidatorTracking for ParentValidatorsTracker;
     using LibValidatorSet for ValidatorSet;
 
-    /// @notice commit the ipc parent finality into storage and returns the previous committed finality
-    /// This is useful to understand if the finalities are consistent or if there have been reorgs.
-    /// If there are no previous committed fainality, it will be default to zero values, i.e. zero height and block hash.
-    /// @param finality - the parent finality
-    /// @return hasCommittedBefore A flag that indicates if a finality record has been committed before.
-    /// @return previousFinality The previous finality information.
-    function commitParentFinality(
-        ParentFinality calldata finality
-    ) external systemActorOnly returns (bool hasCommittedBefore, ParentFinality memory previousFinality) {
-        previousFinality = LibGateway.commitParentFinality(finality);
-        hasCommittedBefore = previousFinality.height != 0;
+    /// @notice commit the ipc topdown checkpoint into storage and returns the previous committed checkpoint
+    /// This is useful to understand if the checkpoints are consistent or if there have been reorgs.
+    /// If there are no previous committed checkpoint, it will be default to zero values, i.e. zero height and block hash.
+    /// @param checkpoint - the topdown checkpoint
+    /// @return hasCommittedBefore A flag that indicates if a checkpoint record has been committed before.
+    /// @return previousCheckpoint The previous checkpoint information.
+    function commitTopdownCheckpoint(
+        TopdownCheckpoint calldata checkpoint
+    ) external systemActorOnly returns (bool hasCommittedBefore, TopdownCheckpoint memory previousCheckpoint) {
+        previousCheckpoint = LibGateway.commitTopdownCheckpoint(checkpoint);
+        hasCommittedBefore = previousCheckpoint.height != 0;
     }
 
     /// @notice Store the validator change requests from parent.

contracts/contracts/interfaces/IGateway.sol

@@ -1,7 +1,7 @@
 // SPDX-License-Identifier: MIT OR Apache-2.0
 pragma solidity ^0.8.23;
 
-import {BottomUpCheckpoint, BottomUpMsgBatch, IpcEnvelope, ParentFinality} from "../structs/CrossNet.sol";
+import {BottomUpCheckpoint, BottomUpMsgBatch, IpcEnvelope, TopdownCheckpoint} from "../structs/CrossNet.sol";
 import {FullActivityRollup} from "../structs/Activity.sol";
 import {SubnetID} from "../structs/Subnet.sol";
 import {FvmAddress} from "../structs/FvmAddress.sol";
@@ -66,7 +66,7 @@ interface IGateway {
     function propagate(bytes32 msgCid) external payable;
 
     /// @notice commit the ipc parent finality into storage
-    function commitParentFinality(ParentFinality calldata finality) external;
+    function commitTopdownCheckpoint(TopdownCheckpoint calldata finality) external;
 
     /// @notice creates a new bottom-up checkpoint
     function createBottomUpCheckpoint(

contracts/contracts/lib/LibGateway.sol

@@ -6,9 +6,9 @@ import {GatewayActorStorage, LibGatewayActorStorage} from "../lib/LibGatewayActo
 import {BURNT_FUNDS_ACTOR} from "../constants/Constants.sol";
 import {SubnetID, Subnet, AssetKind, Asset} from "../structs/Subnet.sol";
 import {SubnetActorGetterFacet} from "../subnet/SubnetActorGetterFacet.sol";
-import {CallMsg, IpcMsgKind, IpcEnvelope, OutcomeType, BottomUpMsgBatch, BottomUpMsgBatch, BottomUpCheckpoint, ParentFinality} from "../structs/CrossNet.sol";
+import {CallMsg, IpcMsgKind, IpcEnvelope, OutcomeType, BottomUpMsgBatch, BottomUpMsgBatch, BottomUpCheckpoint, TopdownCheckpoint} from "../structs/CrossNet.sol";
 import {Membership} from "../structs/Subnet.sol";
-import {CannotSendCrossMsgToItself, MethodNotAllowed, MaxMsgsPerBatchExceeded, InvalidXnetMessage ,OldConfigurationNumber, NotRegisteredSubnet, InvalidActorAddress, ParentFinalityAlreadyCommitted, InvalidXnetMessageReason} from "../errors/IPCErrors.sol";
+import {CannotSendCrossMsgToItself, MethodNotAllowed, MaxMsgsPerBatchExceeded, InvalidXnetMessage ,OldConfigurationNumber, NotRegisteredSubnet, InvalidActorAddress, TopdownCheckpointAlreadyCommitted, InvalidXnetMessageReason} from "../errors/IPCErrors.sol";
 import {CrossMsgHelper} from "../lib/CrossMsgHelper.sol";
 import {FilAddress} from "fevmate/contracts/utils/FilAddress.sol";
 import {SubnetIDHelper} from "../lib/SubnetIDHelper.sol";
@@ -117,27 +117,27 @@ library LibGateway {
 
     /// @notice obtain the ipc parent finality at certain block number
     /// @param blockNumber - the block number to obtain the finality
-    function getParentFinality(uint256 blockNumber) internal view returns (ParentFinality memory) {
+    function getTopdownCheckpoint(uint256 blockNumber) internal view returns (TopdownCheckpoint memory) {
         GatewayActorStorage storage s = LibGatewayActorStorage.appStorage();
         return s.finalitiesMap[blockNumber];
     }
 
     /// @notice obtain the latest committed ipc parent finality
-    function getLatestParentFinality() internal view returns (ParentFinality memory) {
+    function getLatestTopdownCheckpoint() internal view returns (TopdownCheckpoint memory) {
         GatewayActorStorage storage s = LibGatewayActorStorage.appStorage();
-        return getParentFinality(s.latestParentHeight);
+        return getTopdownCheckpoint(s.latestParentHeight);
     }
 
     /// @notice commit the ipc parent finality into storage
     /// @param finality - the finality to be committed
-    function commitParentFinality(
-        ParentFinality calldata finality
-    ) internal returns (ParentFinality memory lastFinality) {
+    function commitTopdownCheckpoint(
+        TopdownCheckpoint calldata finality
+    ) internal returns (TopdownCheckpoint memory lastFinality) {
         GatewayActorStorage storage s = LibGatewayActorStorage.appStorage();
 
         uint256 lastHeight = s.latestParentHeight;
         if (lastHeight >= finality.height) {
-            revert ParentFinalityAlreadyCommitted();
+            revert TopdownCheckpointAlreadyCommitted();
         }
         lastFinality = s.finalitiesMap[lastHeight];
 

contracts/contracts/lib/LibGatewayActorStorage.sol

@@ -3,7 +3,7 @@ pragma solidity ^0.8.23;
 
 import {NotSystemActor, NotEnoughFunds} from "../errors/IPCErrors.sol";
 import {QuorumMap} from "../structs/Quorum.sol";
-import {BottomUpCheckpoint, BottomUpMsgBatch, IpcEnvelope, ParentFinality} from "../structs/CrossNet.sol";
+import {BottomUpCheckpoint, BottomUpMsgBatch, IpcEnvelope, TopdownCheckpoint} from "../structs/CrossNet.sol";
 import {SubnetID, Subnet, ParentValidatorsTracker} from "../structs/Subnet.sol";
 import {Membership} from "../structs/Subnet.sol";
 import {AccountHelper} from "../lib/AccountHelper.sol";
@@ -60,7 +60,7 @@ struct GatewayActorStorage {
     /// SubnetID => Subnet
     mapping(bytes32 => Subnet) subnets;
     /// @notice The parent finalities. Key is the block number, value is the finality struct.
-    mapping(uint256 => ParentFinality) finalitiesMap;
+    mapping(uint256 => TopdownCheckpoint) finalitiesMap;
     /// @notice Postbox keeps track of all the cross-net messages triggered by
     /// an actor that need to be propagated further through the hierarchy.
     /// cross-net message id => CrossMsg

contracts/contracts/structs/CrossNet.sol

@@ -9,9 +9,12 @@ uint64 constant MAX_MSGS_PER_BATCH = 10;
 uint256 constant BATCH_PERIOD = 100;
 
 /// @notice The parent finality for IPC parent at certain height.
-struct ParentFinality {
+struct TopdownCheckpoint {
     uint256 height;
     bytes32 blockHash;
+    /// The commiment of topdown effects (topdown messages + validator changes).
+    /// Current version is the CID.
+    bytes effectsCommitment;
 }
 
 /// @notice A bottom-up checkpoint type.

contracts/test/IntegrationTestBase.sol

@@ -7,7 +7,7 @@ import "../contracts/errors/IPCErrors.sol";
 import {EMPTY_BYTES, METHOD_SEND} from "../contracts/constants/Constants.sol";
 import {ConsensusType} from "../contracts/enums/ConsensusType.sol";
 import {IDiamond} from "../contracts/interfaces/IDiamond.sol";
-import {IpcEnvelope, BottomUpCheckpoint, IpcMsgKind, ParentFinality, CallMsg} from "../contracts/structs/CrossNet.sol";
+import {IpcEnvelope, BottomUpCheckpoint, IpcMsgKind, TopdownCheckpoint, CallMsg} from "../contracts/structs/CrossNet.sol";
 import {FvmAddress} from "../contracts/structs/FvmAddress.sol";
 import {SubnetID, AssetKind, PermissionMode, PermissionMode, Subnet, Asset, IPCAddress, Validator} from "../contracts/structs/Subnet.sol";
 import {SubnetIDHelper} from "../contracts/lib/SubnetIDHelper.sol";
@@ -782,10 +782,14 @@ contract IntegrationTestBase is Test, TestParams, TestRegistry, TestSubnetActor,
         weights[1] = 100;
         weights[2] = 100;
 
-        ParentFinality memory finality = ParentFinality({height: block.number, blockHash: bytes32(0)});
+        TopdownCheckpoint memory finality = TopdownCheckpoint({
+            height: block.number,
+            blockHash: bytes32(0),
+            effectsCommitment: new bytes(0)
+        });
 
         vm.prank(FilAddress.SYSTEM_ACTOR);
-        gatewayDiamond.topDownFinalizer().commitParentFinality(finality);
+        gatewayDiamond.topDownFinalizer().commitTopdownCheckpoint(finality);
     }
 
     function setupWhiteListMethod(address caller, address src) public returns (bytes32) {
@@ -829,11 +833,15 @@ contract IntegrationTestBase is Test, TestParams, TestRegistry, TestSubnetActor,
         weights[0] = weight;
 
         vm.deal(validator, 1);
-        ParentFinality memory finality = ParentFinality({height: block.number, blockHash: bytes32(0)});
+        TopdownCheckpoint memory finality = TopdownCheckpoint({
+            height: block.number,
+            blockHash: bytes32(0),
+            effectsCommitment: new bytes(0)
+        });
         // uint64 n = gatewayDiamond.getter().getLastConfigurationNumber() + 1;
 
         vm.startPrank(FilAddress.SYSTEM_ACTOR);
-        gatewayDiamond.topDownFinalizer().commitParentFinality(finality);
+        gatewayDiamond.topDownFinalizer().commitTopdownCheckpoint(finality);
         vm.stopPrank();
     }
 

contracts/test/helpers/SelectorLibrary.sol

@@ -27,7 +27,7 @@ library SelectorLibrary {
         if (keccak256(abi.encodePacked(facetName)) == keccak256(abi.encodePacked("GatewayGetterFacet"))) {
             return
                 abi.decode(
-                    hex"000000000000000000000000000000000000000000000000000000000000002000000000000000000000000000000000000000000000000000000000000000218789f83b0000000000000000000000000000000000000000000000000000000006c46853000000000000000000000000000000000000000000000000000000002da5794a00000000000000000000000000000000000000000000000000000000dd81b5cf0000000000000000000000000000000000000000000000000000000041b6a2e80000000000000000000000000000000000000000000000000000000038d6693200000000000000000000000000000000000000000000000000000000b3ab3f7400000000000000000000000000000000000000000000000000000000ac12d763000000000000000000000000000000000000000000000000000000004aa8f8a500000000000000000000000000000000000000000000000000000000ca41d5ce00000000000000000000000000000000000000000000000000000000444ead5100000000000000000000000000000000000000000000000000000000d6c5c39700000000000000000000000000000000000000000000000000000000544dddff000000000000000000000000000000000000000000000000000000006ad21bb000000000000000000000000000000000000000000000000000000000a517218f000000000000000000000000000000000000000000000000000000009704276600000000000000000000000000000000000000000000000000000000b1ba49b000000000000000000000000000000000000000000000000000000000f3229131000000000000000000000000000000000000000000000000000000000338150f0000000000000000000000000000000000000000000000000000000094074b03000000000000000000000000000000000000000000000000000000007edeac920000000000000000000000000000000000000000000000000000000006572c1a00000000000000000000000000000000000000000000000000000000c66c66a1000000000000000000000000000000000000000000000000000000003594c3c1000000000000000000000000000000000000000000000000000000009d3070b50000000000000000000000000000000000000000000000000000000042398a9a00000000000000000000000000000000000000000000000000000000fa34a400000000000000000000000000000000000000000000000000000000005d02968500000000000000000000000000000000000000000000000000000000599c7bd10000000000000000000000000000000000000000000000000000000005aff0b3000000000000000000000000000000000000000000000000000000008cfd78e70000000000000000000000000000000000000000000000000000000002e30f9a00000000000000000000000000000000000000000000000000000000a2b6715800000000000000000000000000000000000000000000000000000000",
+                    hex"000000000000000000000000000000000000000000000000000000000000002000000000000000000000000000000000000000000000000000000000000000218789f83b0000000000000000000000000000000000000000000000000000000006c46853000000000000000000000000000000000000000000000000000000002da5794a00000000000000000000000000000000000000000000000000000000dd81b5cf0000000000000000000000000000000000000000000000000000000041b6a2e80000000000000000000000000000000000000000000000000000000038d6693200000000000000000000000000000000000000000000000000000000b3ab3f7400000000000000000000000000000000000000000000000000000000ac12d763000000000000000000000000000000000000000000000000000000004aa8f8a500000000000000000000000000000000000000000000000000000000ca41d5ce00000000000000000000000000000000000000000000000000000000444ead5100000000000000000000000000000000000000000000000000000000d6c5c39700000000000000000000000000000000000000000000000000000000544dddff000000000000000000000000000000000000000000000000000000006ad21bb000000000000000000000000000000000000000000000000000000000a517218f000000000000000000000000000000000000000000000000000000009704276600000000000000000000000000000000000000000000000000000000b1ba49b000000000000000000000000000000000000000000000000000000000f322913100000000000000000000000000000000000000000000000000000000c17117e90000000000000000000000000000000000000000000000000000000094074b030000000000000000000000000000000000000000000000000000000006572c1a00000000000000000000000000000000000000000000000000000000c66c66a1000000000000000000000000000000000000000000000000000000003594c3c1000000000000000000000000000000000000000000000000000000009d3070b50000000000000000000000000000000000000000000000000000000042398a9a000000000000000000000000000000000000000000000000000000003c71caeb00000000000000000000000000000000000000000000000000000000fa34a400000000000000000000000000000000000000000000000000000000005d02968500000000000000000000000000000000000000000000000000000000599c7bd10000000000000000000000000000000000000000000000000000000005aff0b3000000000000000000000000000000000000000000000000000000008cfd78e70000000000000000000000000000000000000000000000000000000002e30f9a00000000000000000000000000000000000000000000000000000000a2b6715800000000000000000000000000000000000000000000000000000000",
                     (bytes4[])
                 );
         }
@@ -55,7 +55,7 @@ library SelectorLibrary {
         if (keccak256(abi.encodePacked(facetName)) == keccak256(abi.encodePacked("TopDownFinalityFacet"))) {
             return
                 abi.decode(
-                    hex"000000000000000000000000000000000000000000000000000000000000002000000000000000000000000000000000000000000000000000000000000000040df144610000000000000000000000000000000000000000000000000000000011196974000000000000000000000000000000000000000000000000000000008fbe0b7c00000000000000000000000000000000000000000000000000000000e49a547d00000000000000000000000000000000000000000000000000000000",
+                    hex"000000000000000000000000000000000000000000000000000000000000002000000000000000000000000000000000000000000000000000000000000000040df144610000000000000000000000000000000000000000000000000000000098ac2e7d000000000000000000000000000000000000000000000000000000008fbe0b7c00000000000000000000000000000000000000000000000000000000e49a547d00000000000000000000000000000000000000000000000000000000",
                     (bytes4[])
                 );
         }