feat(protocol): support delayed forced inclusion of txs

.github/workflows/protocol.yml

@@ -10,6 +10,13 @@ on:
       - "!packages/protocol/docs/**"
       - "!packages/protocol/simulation/**"
       - "!packages/protocol/deployments/**"
+      - "!packages/protocol/script/layer2/hekla/**"
+      - "!packages/protocol/script/layer2/mainnet/**"
+      - "!packages/protocol/script/layer1/hekla/**"
+      - "!packages/protocol/script/layer1/mainnet/**"
+      - "!packages/protocol/script/layer1/preconf/**"
+      - "!packages/protocol/script/layer1/provers/**"
+      - "!packages/protocol/script/layer1/team/**"
     branches-ignore:
       - release-please--branches--**
 

.gitignore

@@ -120,3 +120,4 @@ __pycache__/
 
 # Idea
 .idea/
+packages/protocol/snapshots/InboxTest_ProposeAndProve.json

.release-please-manifest.json

@@ -5,7 +5,7 @@
   "packages/fork-diff": "0.6.1",
   "packages/guardian-prover-health-check": "0.1.0",
   "packages/guardian-prover-health-check-ui": "0.2.0",
-  "packages/protocol": "1.11.0",
+  "packages/protocol": "2.0.0",
   "packages/relayer": "0.12.0",
   "packages/snaefell-ui": "1.1.0",
   "packages/supplementary-contracts": "1.0.0",

packages/docs-site/src/content/docs/taiko-protocol/codebase-analysis/taikol2-contract.md

@@ -82,7 +82,7 @@ description: Taiko protocol page for "TaikoL2.sol".
 
    - `parentHash`: Hash of the parent block.
    - `parentGasExcess`: Gas excess for base fee calculation.
-<br/><br/>
+     <br/><br/>
 
 2. **`EIP1559Update`**
    Emitted when gas parameters (e.g., target, excess, base fee) are updated.

packages/protocol/README.md

@@ -15,40 +15,39 @@ To install dependencies:
 foundryup && pnpm install
 ```
 
-## Compilation and Testing
+## Compilation
 
 Taiko’s protocol is split between Layer 1 (L1) and Layer 2 (L2). The smart contracts need to be compiled and tested separately for each layer:
 
-### Layer 1 (Ethereum, Duncan Hardfork)
-
-To compile, run tests, and generate the storage layout for L1:
+To compile and generate the storage layout for L1:
 
 ```bash
 pnpm compile:l1
-pnpm test:l1
 pnpm layout:l1
 ```
 
-### Layer 2 (Taiko, Shanghai Hardfork)
-
 Similarly, for L2:
 
 ```bash
 pnpm compile:l2
-pnpm test:l2
 pnpm layout:l2
 ```
 
-### Compile and Test for Both Layers
-
-To compile and test contracts for both L1 and L2 at once:
+To compile and generate the storage layout for both layers:
 
 ```bash
 pnpm compile
-pnpm test
 pnpm layout
 ```
 
+## Testing
+
+```bash
+pnpm test:l1
+pnpm test:l2
+pnpm test
+```
+
 ## Layer 2 Genesis Block
 
 ### Generating a Dummy Genesis Block

packages/protocol/contracts/layer1/automata-attestation/AutomataDcapV3Attestation.sol

@@ -57,6 +57,8 @@ contract AutomataDcapV3Attestation is IAttestation, EssentialContract {
     event RevokedCertSerialNumAdded(uint256 indexed index, bytes serialNum);
     event RevokedCertSerialNumRemoved(uint256 indexed index, bytes serialNum);
 
+    constructor() EssentialContract(address(0)) { }
+
     // @notice Initializes the contract.
     /// @param sigVerifyLibAddr Address of the signature verification library.
     /// @param pemCertLibAddr Address of certificate library.
@@ -437,7 +439,7 @@ contract AutomataDcapV3Attestation is IAttestation, EssentialContract {
             for (uint256 i; i < 3; ++i) {
                 bool isPckCert = i == 0; // additional parsing for PCKCert
                 bool certDecodedSuccessfully;
-                // todo! move decodeCert offchain
+                // TODO(Yue): move decodeCert offchain
                 (certDecodedSuccessfully, parsedQuoteCerts[i]) = pemCertLib.decodeCert(
                     authDataV3.certification.decodedCertDataArray[i], isPckCert
                 );

packages/protocol/contracts/layer1/automata-attestation/lib/QuoteV3Auth/V3Struct.sol

@@ -37,7 +37,7 @@ library V3Struct {
 
     struct CertificationData {
         uint16 certType;
-        // todo! In encoded path, we need to calculate the size of certDataArray
+        // TODO(Yue): In encoded path, we need to calculate the size of certDataArray
         // certDataSize = len(join((BEGIN_CERT, certArray[i], END_CERT) for i in 0..3))
         // But for plain bytes path, we don't need that.
         uint32 certDataSize;

packages/protocol/contracts/layer1/based/ForcedInclusionInbox.sol

@@ -0,0 +1,106 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.24;
+
+import "@openzeppelin/contracts/token/ERC20/IERC20.sol";
+import "src/shared/common/EssentialContract.sol";
+import "src/shared/based/ITaiko.sol";
+import "src/shared/libs/LibMath.sol";
+import "src/shared/libs/LibNetwork.sol";
+import "src/shared/libs/LibStrings.sol";
+import "src/shared/signal/ISignalService.sol";
+import "src/layer1/verifiers/IVerifier.sol";
+import "./ITaikoInbox.sol";
+import "./IForcedInclusionStore.sol";
+
+/// @title ForcedInclusionInbox
+/// @dev This contract is part of a delayed inbox implementation to enforce the inclusion of
+/// transactions.
+/// The current design is a simplified and can be improved with the following ideas:
+/// 1. **Fee-Based Request Prioritization**:
+///    - Proposers can selectively fulfill pending requests based on transaction fees.
+///    - Requests not yet due can be processed earlier if fees are attractive, incentivizing timely
+/// execution.
+///
+/// 2. **Rate Limit Control**:
+///    - A rate-limiting mechanism ensures a minimum interval of 12*N seconds between request
+/// fulfillments.
+///    - Prevents proposers from being overwhelmed during high request volume, ensuring system
+/// stability.
+///
+/// 3. **Calldata and Blob Support**:
+///    - Supports both calldata and blobs in the transaction list.
+///
+/// 4. **Gas-Efficient Request Storage**:
+///    - Avoids storing full request data in contract storage.
+///    - Saves only the request hash and its timestamp.
+///    - Leverages Ethereum events to store request details off-chain.
+///    - Proposers can reconstruct requests as needed, minimizing on-chain storage and gas
+/// consumption.
+///
+/// @custom:security-contact [email protected]
+contract ForcedInclusionInbox is EssentialContract {
+    using LibMath for uint256;
+
+    event ForcedInclusionProcessed(IForcedInclusionStore.ForcedInclusion);
+
+    uint16 public constant MAX_FORCED_TXS_PER_FORCED_INCLUSION = 512;
+    uint256[50] private __gap;
+
+    constructor(address _resolver) EssentialContract(_resolver) { }
+
+    function init(address _owner) external initializer {
+        __Essential_init(_owner);
+    }
+
+    /// @notice Proposes a batch of blocks.
+    /// @param _forcedInclusionParams An optional ABI-encoded BlockParams for the forced inclusion
+    /// batch.
+    /// @param _params ABI-encoded BlockParams.
+    /// @param _txList The transaction list in calldata. If the txList is empty, blob will be used
+    /// for data availability.
+    function proposeBatchWithForcedInclusion(
+        bytes calldata _forcedInclusionParams,
+        bytes calldata _params,
+        bytes calldata _txList
+    )
+        external
+        nonReentrant
+        returns (ITaikoInbox.BatchInfo memory info_, ITaikoInbox.BatchMetadata memory meta_)
+    {
+        ITaikoInbox inbox = ITaikoInbox(resolveAddress(LibStrings.B_TAIKO, false));
+        (info_, meta_) = inbox.proposeBatch(_params, _txList);
+
+        // Process the next forced inclusion.
+        IForcedInclusionStore store =
+            IForcedInclusionStore(resolveAddress(LibStrings.B_FORCED_INCLUSION_STORE, false));
+
+        IForcedInclusionStore.ForcedInclusion memory inclusion =
+            store.consumeForcedInclusion(msg.sender);
+
+        if (inclusion.createdAt != 0) {
+            ITaikoInbox.BatchParams memory params;
+
+            if (_forcedInclusionParams.length != 0) {
+                params = abi.decode(_forcedInclusionParams, (ITaikoInbox.BatchParams));
+            }
+
+            // Overwrite the batch params to have only 1 block and up to
+            // MAX_FORCED_TXS_PER_FORCED_INCLUSION transactions
+            if (params.blocks.length == 0) {
+                params.blocks = new ITaikoInbox.BlockParams[](1);
+            }
+
+            if (params.blocks[0].numTransactions < MAX_FORCED_TXS_PER_FORCED_INCLUSION) {
+                params.blocks[0].numTransactions = MAX_FORCED_TXS_PER_FORCED_INCLUSION;
+            }
+
+            params.blobParams.blobHashes = new bytes32[](1);
+            params.blobParams.blobHashes[0] = inclusion.blobHash;
+            params.blobParams.byteOffset = inclusion.blobByteOffset;
+            params.blobParams.byteSize = inclusion.blobByteSize;
+
+            inbox.proposeBatch(abi.encode(params), "");
+            emit ForcedInclusionProcessed(inclusion);
+        }
+    }
+}

packages/protocol/contracts/layer1/based/ForcedInclusionStore.sol

@@ -0,0 +1,97 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.24;
+
+import "src/shared/common/EssentialContract.sol";
+import "src/shared/libs/LibMath.sol";
+import "./IForcedInclusionStore.sol";
+import "src/shared/libs/LibAddress.sol";
+import "src/shared/libs/LibStrings.sol";
+
+/// @title ForcedInclusionStore
+/// @dev A contract for storing and managing forced inclusion requests. Forced inclusions allow
+/// users to pay a  fee
+///      to ensure their transactions are included in a block. The contract maintains a FIFO queue
+/// of inclusion requests.
+/// @custom:security-contact
+contract ForcedInclusionStore is EssentialContract, IForcedInclusionStore {
+    using LibAddress for address;
+    using LibMath for uint256;
+
+    uint256 private constant SECONDS_PER_BLOCK = 12;
+
+    uint256 public immutable inclusionDelay;
+    uint256 public immutable fee;
+
+    mapping(uint256 id => ForcedInclusion inclusion) public queue; // slot 1
+    uint64 public head; // slot 2
+    uint64 public tail;
+    uint128 private __reserved1;
+
+    uint256[48] private __gap;
+
+    constructor(
+        address _resolver,
+        uint256 _inclusionDelay,
+        uint256 _fee
+    )
+        EssentialContract(_resolver)
+    {
+        require(_inclusionDelay != 0 && _inclusionDelay % SECONDS_PER_BLOCK == 0, InvalidParams());
+        require(_fee != 0, InvalidParams());
+
+        inclusionDelay = _inclusionDelay;
+        fee = _fee;
+    }
+
+    function init(address _owner) external initializer {
+        __Essential_init(_owner);
+    }
+
+    function storeForcedInclusion(
+        uint8 blobIndex,
+        uint32 blobByteOffset,
+        uint32 blobByteSize
+    )
+        external
+        payable
+    {
+        bytes32 blobHash = _blobHash(blobIndex);
+        require(blobHash != bytes32(0), BlobNotFound());
+        require(msg.value == fee, IncorrectFee());
+
+        ForcedInclusion memory inclusion = ForcedInclusion({
+            blobHash: blobHash,
+            fee: msg.value,
+            createdAt: uint64(block.timestamp),
+            blobByteOffset: blobByteOffset,
+            blobByteSize: blobByteSize
+        });
+
+        queue[tail++] = inclusion;
+
+        emit ForcedInclusionStored(inclusion);
+    }
+
+    function consumeForcedInclusion(address _feeRecipient)
+        external
+        onlyFromNamed(LibStrings.B_TAIKO_FORCED_INCLUSION_INBOX)
+        returns (ForcedInclusion memory inclusion_)
+    {
+        // we only need to check the first one, since it will be the oldest.
+        uint64 _head = head;
+        ForcedInclusion storage inclusion = queue[_head];
+
+        if (inclusion.createdAt != 0 && block.timestamp >= inclusionDelay + inclusion.createdAt) {
+            inclusion_ = inclusion;
+            _feeRecipient.sendEtherAndVerify(inclusion.fee);
+            delete queue[_head];
+            head = _head + 1;
+            emit ForcedInclusionConsumed(inclusion);
+        }
+    }
+
+    // @dev Override this function for easier testing blobs
+    function _blobHash(uint8 blobIndex) internal view virtual returns (bytes32) {
+        return blobhash(blobIndex);
+    }
+}

packages/protocol/contracts/layer1/based/IForcedInclusionInbox.sol

@@ -0,0 +1,27 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.24;
+
+import "./ITaikoInbox.sol";
+import "./IForcedInclusionStore.sol";
+
+/// @title IForcedInclusionInbox
+/// @custom:security-contact [email protected]
+interface IForcedInclusionInbox {
+    event ForcedInclusionProcessed(IForcedInclusionStore.ForcedInclusion);
+
+    /// @notice Proposes a batch of blocks with forced inclusion.
+    /// @param _forcedInclusionParams An optional ABI-encoded BlockParams for the forced inclusion
+    /// batch.
+    /// @param _params ABI-encoded BlockParams.
+    /// @param _txList The transaction list in calldata. If the txList is empty, blob will be used
+    /// for data availability.
+    /// @return info_ The info of the proposed batch.
+    /// @return meta_ The metadata of the proposed batch.
+    function proposeBatchWithForcedInclusion(
+        bytes calldata _forcedInclusionParams,
+        bytes calldata _params,
+        bytes calldata _txList
+    )
+        external
+        returns (ITaikoInbox.BatchInfo memory info_, ITaikoInbox.BatchMetadata memory meta_);
+}

packages/protocol/contracts/layer1/based/IForcedInclusionStore.sol

@@ -0,0 +1,47 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.24;
+
+/// @title IForcedInclusionStore
+/// @custom:security-contact [email protected]
+interface IForcedInclusionStore {
+    /// @dev Error thrown when a blob is not found.
+    error BlobNotFound();
+    /// @dev Error thrown when the parameters are invalid.
+    error InvalidParams();
+    /// @dev Error thrown when the fee is incorrect.
+    error IncorrectFee();
+
+    /// @dev Event emitted when a forced inclusion is stored.
+    event ForcedInclusionStored(ForcedInclusion forcedInclusion);
+    /// @dev Event emitted when a forced inclusion is consumed.
+    event ForcedInclusionConsumed(ForcedInclusion forcedInclusion);
+
+    struct ForcedInclusion {
+        bytes32 blobHash;
+        uint256 fee;
+        uint64 createdAt;
+        uint32 blobByteOffset;
+        uint32 blobByteSize;
+    }
+
+    /// @dev Consume a forced inclusion request.
+    /// The inclusion request must be marked as processed and the priority fee must be paid to the
+    /// caller.
+    /// @return inclusion_ The forced inclusion request.
+    function consumeForcedInclusion(address _feeRecipient)
+        external
+        returns (ForcedInclusion memory);
+
+    /// @dev Store a forced inclusion request.
+    /// The priority fee must be paid to the contract.
+    /// @param blobIndex The index of the blob that contains the transaction data.
+    /// @param blobByteOffset The byte offset in the blob
+    /// @param blobByteSize The size of the blob in bytes
+    function storeForcedInclusion(
+        uint8 blobIndex,
+        uint32 blobByteOffset,
+        uint32 blobByteSize
+    )
+        external
+        payable;
+}