feat(protocol): expose getUncleProofDelay function (#7058)

* expose avgProofTime for block id so users of bridge can see expectation of when their L2 block which contains their transaction can roughly be expected * rename * lint * chore(docs): auto commit solidity docs Co-authored-by: cyberhorsey <cyberhorsey@users.noreply.github.com>
taikoxyz · Jan 4, 2023 · dd0f011 · dd0f011
1 parent 1206494
commit dd0f011
Show file tree

Hide file tree

Showing 12 changed files with 229 additions and 114 deletions.
diff --git a/.husky/pre-commit b/.husky/pre-commit
@@ -1,4 +1,4 @@
 #!/usr/bin/env sh
 . "$(dirname -- "$0")/_/husky.sh"
 
-pnpm --filter "@taiko/proto" lint-staged
+pnpm --filter "@taiko/protocol" lint-staged
diff --git a/packages/protocol/contracts/L1/TaikoL1.sol b/packages/protocol/contracts/L1/TaikoL1.sol
@@ -284,6 +284,10 @@ contract TaikoL1 is EssentialContract, IHeaderSync, TaikoEvents {
         return state.forkChoices[id][parentHash].provers;
     }
 
+    function getUncleProofDelay(uint256 blockId) public view returns (uint64) {
+        return LibUtils.getUncleProofDelay(state, getConfig(), blockId);
+    }
+
     function getConfig() public pure virtual returns (TaikoData.Config memory) {
         return LibSharedConfig.getConfig();
     }

diff --git a/packages/protocol/contracts/L1/libs/LibProving.sol b/packages/protocol/contracts/L1/libs/LibProving.sol
@@ -300,7 +300,7 @@ library LibProving {
 
             require(
                 block.timestamp <
-                    LibUtils.uncleProofDeadline({
+                    LibUtils.getUncleProofDeadline({
                         state: state,
                         config: config,
                         fc: fc,

diff --git a/packages/protocol/contracts/L1/libs/LibUtils.sol b/packages/protocol/contracts/L1/libs/LibUtils.sol
@@ -143,20 +143,28 @@ library LibUtils {
         return (feeBase * gamma) / 1024;
     }
 
-    // Returns a deterministic deadline for uncle proof submission.
-    function uncleProofDeadline(
+    function getUncleProofDelay(
         TaikoData.State storage state,
         TaikoData.Config memory config,
-        TaikoData.ForkChoice storage fc,
         uint256 blockId
     ) internal view returns (uint64) {
         if (blockId <= 2 * config.maxNumBlocks) {
-            return fc.provenAt + config.initialUncleDelay;
+            return config.initialUncleDelay;
         } else {
-            return fc.provenAt + state.avgProofTime;
+            return state.avgProofTime;
         }
     }
 
+    // Returns a deterministic deadline for uncle proof submission.
+    function getUncleProofDeadline(
+        TaikoData.State storage state,
+        TaikoData.Config memory config,
+        TaikoData.ForkChoice storage fc,
+        uint256 blockId
+    ) internal view returns (uint64) {
+        return fc.provenAt + getUncleProofDelay(state, config, blockId);
+    }
+
     function hashMetadata(
         TaikoData.BlockMetadata memory meta
     ) internal pure returns (bytes32) {

diff --git a/packages/protocol/contracts/L1/libs/LibVerifying.sol b/packages/protocol/contracts/L1/libs/LibVerifying.sol
@@ -238,7 +238,7 @@ library LibVerifying {
         return
             fc.blockHash != 0 &&
             block.timestamp >
-            LibUtils.uncleProofDeadline({
+            LibUtils.getUncleProofDeadline({
                 state: state,
                 config: config,
                 fc: fc,

diff --git a/packages/protocol/tasks/deploy_L1.ts b/packages/protocol/tasks/deploy_L1.ts
@@ -85,7 +85,10 @@ export async function deployContracts(hre: any) {
     const ProofVerifier = await utils.deployContract(hre, "ProofVerifier");
     await utils.waitTx(
         hre,
-        await AddressManager.setAddress(`${chainId}.proof_verifier`, ProofVerifier.address)
+        await AddressManager.setAddress(
+            `${chainId}.proof_verifier`,
+            ProofVerifier.address
+        )
     );
 
     await utils.waitTx(

diff --git a/packages/protocol/test/L1/TaikoL1.test.ts b/packages/protocol/test/L1/TaikoL1.test.ts
@@ -29,7 +29,7 @@ describe("TaikoL1", function () {
             await ethers.getContractFactory("LibProving", {
                 libraries: {
                     LibReceiptDecoder: libReceiptDecoder.address,
-                    LibTxDecoder: libTxDecoder.address
+                    LibTxDecoder: libTxDecoder.address,
                 },
             })
         ).deploy();
@@ -41,16 +41,13 @@ describe("TaikoL1", function () {
         genesisHash = randomBytes32();
         const feeBase = BigNumber.from(10).pow(18);
         taikoL1 = await (
-            await ethers.getContractFactory(
-                "TestTaikoL1",
-                {
-                    libraries: {
-                        LibVerifying: libVerifying.address,
-                        LibProposing: libProposing.address,
-                        LibProving: libProving.address,
-                    },
-                }
-            )
+            await ethers.getContractFactory("TestTaikoL1", {
+                libraries: {
+                    LibVerifying: libVerifying.address,
+                    LibProposing: libProposing.address,
+                    LibProving: libProving.address,
+                },
+            })
         ).deploy();
         await taikoL1.init(addressManager.address, genesisHash, feeBase);
     });
@@ -85,6 +82,26 @@ describe("TaikoL1", function () {
             expect(provers).to.be.empty;
         });
     });
+
+    describe("getDelayForBlockId()", async function () {
+        it("should return  initial uncle delay for block id <= 2 * K_MAX_NUM_BLOCKS", async function () {
+            const constants = await taikoL1.getConfig();
+            const maxNumBlocks = constants[1];
+            const delay = await taikoL1.getUncleProofDelay(maxNumBlocks.mul(2));
+            const initialUncleDelay = 60;
+            expect(delay).to.be.eq(initialUncleDelay);
+        });
+
+        it("should return avg proof time for block id > 2 * K_MAX_NUM_BLOCKS", async function () {
+            const constants = await taikoL1.getConfig();
+            const maxNumBlocks = constants[1];
+            const delay = await taikoL1.getUncleProofDelay(
+                maxNumBlocks.mul(2).add(1)
+            );
+            const avgProofTime = 0; // no proofs have been generated
+            expect(delay).to.be.eq(avgProofTime);
+        });
+    });
 });
 
 function randomBytes32() {

diff --git a/packages/website/docs/smart-contracts/L1/ProofVerifier.md b/packages/website/docs/smart-contracts/L1/ProofVerifier.md
@@ -0,0 +1,27 @@
+## IProofVerifier
+
+### verifyZKP
+
+```solidity
+function verifyZKP(bytes verificationKey, bytes zkproof, bytes32 blockHash, address prover, bytes32 txListHash) external pure returns (bool verified)
+```
+
+### verifyMKP
+
+```solidity
+function verifyMKP(bytes key, bytes value, bytes proof, bytes32 root) external pure returns (bool verified)
+```
+
+## ProofVerifier
+
+### verifyZKP
+
+```solidity
+function verifyZKP(bytes verificationKey, bytes zkproof, bytes32 blockHash, address prover, bytes32 txListHash) external pure returns (bool)
+```
+
+### verifyMKP
+
+```solidity
+function verifyMKP(bytes key, bytes value, bytes proof, bytes32 root) external pure returns (bool)
+```
diff --git a/packages/website/docs/smart-contracts/L1/TaikoData.md b/packages/website/docs/smart-contracts/L1/TaikoData.md
@@ -0,0 +1,98 @@
+## TaikoData
+
+### Config
+
+```solidity
+struct Config {
+  uint256 chainId;
+  uint256 maxNumBlocks;
+  uint256 blockHashHistory;
+  uint256 zkProofsPerBlock;
+  uint256 maxVerificationsPerTx;
+  uint256 commitConfirmations;
+  uint256 maxProofsPerForkChoice;
+  uint256 blockMaxGasLimit;
+  uint256 maxTransactionsPerBlock;
+  uint256 maxBytesPerTxList;
+  uint256 minTxGasLimit;
+  uint256 anchorTxGasLimit;
+  uint256 feePremiumLamda;
+  uint256 rewardBurnBips;
+  uint256 proposerDepositPctg;
+  uint256 feeBaseMAF;
+  uint256 blockTimeMAF;
+  uint256 proofTimeMAF;
+  uint64 rewardMultiplierPctg;
+  uint64 feeGracePeriodPctg;
+  uint64 feeMaxPeriodPctg;
+  uint64 blockTimeCap;
+  uint64 proofTimeCap;
+  uint64 boostrapDiscountHalvingPeriod;
+  uint64 initialUncleDelay;
+  bool enableTokenomics;
+}
+```
+
+### BlockMetadata
+
+```solidity
+struct BlockMetadata {
+  uint256 id;
+  uint256 l1Height;
+  bytes32 l1Hash;
+  address beneficiary;
+  bytes32 txListHash;
+  bytes32 mixHash;
+  bytes extraData;
+  uint64 gasLimit;
+  uint64 timestamp;
+  uint64 commitHeight;
+  uint64 commitSlot;
+}
+```
+
+### ProposedBlock
+
+```solidity
+struct ProposedBlock {
+  bytes32 metaHash;
+  uint256 deposit;
+  address proposer;
+  uint64 proposedAt;
+}
+```
+
+### ForkChoice
+
+```solidity
+struct ForkChoice {
+  bytes32 blockHash;
+  uint64 provenAt;
+  address[] provers;
+}
+```
+
+### State
+
+```solidity
+struct State {
+  mapping(uint256 => bytes32) l2Hashes;
+  mapping(uint256 => struct TaikoData.ProposedBlock) proposedBlocks;
+  mapping(uint256 => mapping(bytes32 => struct TaikoData.ForkChoice)) forkChoices;
+  mapping(address => mapping(uint256 => bytes32)) commits;
+  uint64 genesisHeight;
+  uint64 genesisTimestamp;
+  uint64 __reservedA1;
+  uint64 statusBits;
+  uint256 feeBase;
+  uint64 nextBlockId;
+  uint64 lastProposedAt;
+  uint64 avgBlockTime;
+  uint64 __avgGasLimit;
+  uint64 latestVerifiedHeight;
+  uint64 latestVerifiedId;
+  uint64 avgProofTime;
+  uint64 __reservedC1;
+  uint256[42] __gap;
+}
+```
diff --git a/packages/website/docs/smart-contracts/L1/TaikoEvents.md b/packages/website/docs/smart-contracts/L1/TaikoEvents.md
@@ -0,0 +1,31 @@
+## TaikoEvents
+
+### BlockVerified
+
+```solidity
+event BlockVerified(uint256 id, bytes32 blockHash)
+```
+
+### BlockCommitted
+
+```solidity
+event BlockCommitted(uint64 commitSlot, uint64 commitHeight, bytes32 commitHash)
+```
+
+### BlockProposed
+
+```solidity
+event BlockProposed(uint256 id, struct TaikoData.BlockMetadata meta)
+```
+
+### BlockProven
+
+```solidity
+event BlockProven(uint256 id, bytes32 parentHash, bytes32 blockHash, uint64 timestamp, uint64 provenAt, address prover)
+```
+
+### Halted
+
+```solidity
+event Halted(bool halted)
+```