Pacaya

packages/protocol/Makefile

@@ -0,0 +1,72 @@
+.DEFAULT_TARGET: help
+
+SOLIDITY_VERSION=^0.8.24
+TEST_TREE_MARKDOWN=TEST_TREE.md
+SOURCE_FILES=$(shell find test -type f -name '*.t.yaml')
+TREE_FILES = $(SOURCE_FILES:.t.yaml=.tree)
+TARGET_TEST_FILES = $(SOURCE_FILES:.tree=.t.sol)
+MAKE_TEST_TREE=deno run ./script/make-test-tree.ts
+MAKEFILE=Makefile
+
+.PHONY: help
+help:
+	@echo "Available targets:"
+	@grep -E '^[a-zA-Z0-9_-]+:.*?## .*$$' $(MAKEFILE) \
+	   | sed -n 's/^\(.*\): \(.*\)##\(.*\)/- make \1  \3/p'
+
+all: sync markdown ##      Builds all tree files and updates the test tree markdown
+
+sync: $(TREE_FILES) ##     Scaffold or sync tree files into solidity tests
+	@for file in $^; do \
+		if [ ! -f $${file%.tree}.t.sol ]; then \
+			echo "[Scaffold]   $${file%.tree}.t.sol" ; \
+			bulloak scaffold -s $(SOLIDITY_VERSION) --vm-skip -w $$file ; \
+		else \
+			echo "[Sync file]  $${file%.tree}.t.sol" ; \
+			bulloak check --fix $$file ; \
+		fi \
+	done
+
+check: $(TREE_FILES) ##    Checks if solidity files are out of sync
+	bulloak check $^
+
+markdown: $(TEST_TREE_MARKDOWN) ## Generates a markdown file with the test definitions rendered as a tree
+
+# Internal targets
+
+# Generate a markdown file with the test trees
+$(TEST_TREE_MARKDOWN): $(TREE_FILES)
+	@echo "[Markdown]   TEST_TREE.md"
+	@echo "# Test tree definitions" > $@
+	@echo "" >> $@
+	@echo "Below is the graphical definition of the contract tests implemented on [the test folder](./test)" >> $@
+	@echo "" >> $@
+
+	@for file in $^; do \
+		echo "\`\`\`" >> $@ ; \
+		cat $$file >> $@ ; \
+		echo "\`\`\`" >> $@ ; \
+		echo "" >> $@ ; \
+	done
+
+# Internal dependencies and transformations
+
+$(TREE_FILES): $(SOURCE_FILES)
+
+%.tree: %.t.yaml
+	@for file in $^; do \
+	  echo "[Convert]    $$file -> $${file%.t.yaml}.tree" ; \
+		cat $$file | $(MAKE_TEST_TREE) > $${file%.t.yaml}.tree ; \
+	done
+
+# Global
+
+.PHONY: init
+init: ##     Check the dependencies and prompt to install if needed
+	@which deno > /dev/null && echo "Deno is available" || echo "Install Deno:  curl -fsSL https://deno.land/install.sh | sh"
+	@which bulloak > /dev/null && echo "bulloak is available" || echo "Install bulloak:  cargo install bulloak"
+
+.PHONY: clean
+clean: ##    Clean the intermediary tree files
+	rm -f $(TREE_FILES)
+	rm -f $(TEST_TREE_MARKDOWN)

packages/protocol/README.md

@@ -15,40 +15,111 @@ 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
+
+Tests can be described using yaml files. They will be automatically transformed into solidity test files with [bulloak](https://github.com/alexfertel/bulloak).
+
+Create a file with `.t.yaml` extension within the `test` folder and describe a hierarchy of test cases:
+
+```yaml
+# MyTest.t.yaml
+
+MultisigTest:
+  - given: proposal exists
+    comment: Comment here
+    and:
+      - given: proposal is in the last stage
+        and:
+          - when: proposal can advance
+            then:
+              - it: Should return true
+
+          - when: proposal cannot advance
+            then:
+              - it: Should return false
+
+      - when: proposal is not in the last stage
+        then:
+          - it: should do A
+            comment: This is an important remark
+          - it: should do B
+          - it: should do C
+
+  - when: proposal doesn't exist
+    comment: Testing edge cases here
+    then:
+      - it: should revert
+```
+
+Then install bullok with`cargo install bulloak` and use `make` to automatically sync the described branches into solidity test files.
+
+```sh
+$ make
+Available targets:
+Available targets:
+- make all        Builds all tree files and updates the test tree markdown
+- make sync       Scaffold or sync tree files into solidity tests
+- make check      Checks if solidity files are out of sync
+- make markdown   Generates a markdown file with the test definitions rendered as a tree
+- make init       Check the dependencies and prompt to install if needed
+- make clean      Clean the intermediary tree files
+
+$ make sync
+```
+
+The final output will look like a human readable tree:
+
+```
+# MyTest.tree
+
+EmergencyMultisigTest
+├── Given proposal exists // Comment here
+│   ├── Given proposal is in the last stage
+│   │   ├── When proposal can advance
+│   │   │   └── It Should return true
+│   │   └── When proposal cannot advance
+│   │       └── It Should return false
+│   └── When proposal is not in the last stage
+│       ├── It should do A // Careful here
+│       ├── It should do B
+│       └── It should do C
+└── When proposal doesn't exist // Testing edge cases here
+    └── It should revert
+```
+
+### Run tests
+
+```bash
+pnpm test:l1
+pnpm test:l2
+pnpm test
+```
+
 ## Layer 2 Genesis Block
 
 ### Generating a Dummy Genesis Block

packages/protocol/TEST_TREE.md

@@ -0,0 +1,65 @@
+# Test tree definitions
+
+Below is the graphical definition of the contract tests implemented on [the test folder](./test)
+
+```
+TaikoL1Test
+└── When a new TaikoL1 with 10 block slots and a sync interval of 5
+    ├── When test1
+    │   └── When case-1
+    │       ├── It initializes the genesis block
+    │       ├── It initializes the first transition
+    │       ├── It finalizes the genesis block
+    │       ├── It counts total blocks as 1
+    │       ├── It retrieves correct data for the genesis block
+    │       ├── It retrieves correct data for the genesis block's first transition
+    │       ├── It fails to retrieve block 1, indicating block not found
+    │       ├── It returns the genesis block and its first transition for getLastVerifiedTransitionV3
+    │       └── It returns empty data for getLastSyncedTransitionV3 but does not revert
+    ├── When proposing one more block with custom parameters
+    │   └── When case-2
+    │       ├── It places the block in the first slot
+    │       ├── It sets the block's next transition id to 1
+    │       ├── It the returned metahash should match the block's metahash
+    │       ├── It matches the block's timestamp and anchor block id with the parameters
+    │       ├── It total block count is 2
+    │       └── It retrieves correct data for block 1
+    ├── When proposing one more block with default parameters
+    │   └── When case-3
+    │       ├── It places the block in the first slot
+    │       ├── It sets the block's next transition id to 1
+    │       ├── It the returned metahash should match the block's metahash
+    │       ├── It sets the block's timestamp to the current timestamp
+    │       ├── It sets the block's anchor block id to block.number - 1
+    │       ├── It total block count is 2
+    │       └── It retrieves correct data for block 1
+    ├── When proposing one more block with default parameters but nonzero parentMetaHash
+    │   └── When case-4
+    │       ├── It does not revert when the first block's parentMetaHash matches the genesis block's metahash
+    │       └── It reverts when proposing a second block with a random parentMetaHash
+    └── When proposing 9 blocks as a batch to fill all slots
+        ├── When propose the 11th block before previous blocks are verified
+        │   └── When case-5
+        │       └── It reverts indicating no more slots available
+        ├── When prove all existing blocks with correct first transitions
+        │   ├── When proposing the 11th block after previous blocks are verified
+        │   │   └── When case-6
+        │   │       ├── It total block count is 12
+        │   │       └── It getBlockV3(0) reverts indicating block not found
+        │   └── When case-7
+        │       ├── It total block count is 10
+        │       ├── It returns the block 9 and its first transition for getLastVerifiedTransitionV3
+        │       └── It returns the block 5 and its first transition for getLastSyncedTransitionV3
+        ├── When prove all existing blocks with wrong first transitions
+        │   ├── When prove all existing blocks with correct first transitions2
+        │   │   └── When case-8
+        │   │       ├── It total block count is 10
+        │   │       ├── It returns the block 9 and its first transition for getLastVerifiedTransitionV3
+        │   │       └── It returns the block 5 and its first transition for getLastSyncedTransitionV3
+        │   └── When case-9
+        │       ├── It total block count is 10
+        │       ├── It returns the genesis block and its first transition for getLastVerifiedTransitionV3
+        │       └── It returns empty data for getLastSyncedTransitionV3 but does not revert
+        └── When case-10
+            └── It total block count is 10
+```