Skip to content

Commit 3b977e8

Browse files
author
Afonsodalvi
committed
first commit
0 parents  commit 3b977e8

File tree

1,934 files changed

+375177
-0
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

1,934 files changed

+375177
-0
lines changed

‎.github/workflows/test.yml

+45
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
name: CI
2+
3+
on:
4+
push:
5+
pull_request:
6+
workflow_dispatch:
7+
8+
env:
9+
FOUNDRY_PROFILE: ci
10+
11+
jobs:
12+
check:
13+
strategy:
14+
fail-fast: true
15+
16+
name: Foundry project
17+
runs-on: ubuntu-latest
18+
steps:
19+
- uses: actions/checkout@v4
20+
with:
21+
submodules: recursive
22+
23+
- name: Install Foundry
24+
uses: foundry-rs/foundry-toolchain@v1
25+
with:
26+
version: nightly
27+
28+
- name: Show Forge version
29+
run: |
30+
forge --version
31+
32+
- name: Run Forge fmt
33+
run: |
34+
forge fmt --check
35+
id: fmt
36+
37+
- name: Run Forge build
38+
run: |
39+
forge build --sizes
40+
id: build
41+
42+
- name: Run Forge tests
43+
run: |
44+
forge test -vvv
45+
id: test

‎.gitignore

+14
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
# Compiler files
2+
cache/
3+
out/
4+
5+
# Ignores development broadcast logs
6+
!/broadcast
7+
/broadcast/*/31337/
8+
/broadcast/**/dry-run/
9+
10+
# Docs
11+
docs/
12+
13+
# Dotenv file
14+
.env

‎.gitmodules

+9
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
[submodule "lib/forge-std"]
2+
path = lib/forge-std
3+
url = https://github.com/foundry-rs/forge-std
4+
[submodule "lib/openzeppelin-contracts"]
5+
path = lib/openzeppelin-contracts
6+
url = https://github.com/OpenZeppelin/openzeppelin-contracts
7+
[submodule "lib/openzeppelin-contracts-upgradeable"]
8+
path = lib/openzeppelin-contracts-upgradeable
9+
url = https://github.com/OpenZeppelin/openzeppelin-contracts-upgradeable

‎README.md

+104
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,104 @@
1+
# Merkle Tree Implementations for Whitelist and Token Minting
2+
3+
This repository demonstrates two approaches to managing whitelists in Ethereum-based smart contracts using **Cartesian Merkle Tree (CMT)** and **Binary Merkle Tree (BMT)**. These methods enable cryptographic validation of authorized users for ERC20 token minting.
4+
5+
## Cartesian Merkle Tree Overview
6+
7+
A **Cartesian Merkle Tree (CMT)** is a hybrid data structure combining features of:
8+
1. **Binary Search Trees (BST):** Ensures ordered insertion for fast lookup.
9+
2. **Heap Structures:** Maintains a heap priority, ensuring deterministic balancing.
10+
3. **Merkle Trees:** Cryptographically secure trees where each node stores a hash of its children, allowing efficient proof generation and validation.
11+
12+
### Key Features of CMT
13+
* **Dynamic Management:** Supports adding and removing nodes dynamically.
14+
* **Advanced Proofs:** Handles inclusion and exclusion proofs.
15+
* **Deterministic:** The structure remains consistent regardless of the insertion order.
16+
17+
### Benefits of CMT
18+
* **Ideal for dynamic whitelists:** Update permissions at runtime without redeploying the contract.
19+
* **Optimized for privacy:** Supports zero-knowledge proof (ZK-proof) applications.
20+
* **Secure:** Ensures robust cryptographic integrity for validation.
21+
22+
### Use Cases
23+
* **Whitelist Management:** Dynamically add and remove users at runtime.
24+
* **Zero-Knowledge Applications:** Verify data without revealing sensitive information.
25+
26+
---
27+
28+
## Binary Merkle Tree Overview
29+
30+
A **Binary Merkle Tree (BMT)** is a simpler structure where each node stores a hash derived from its child nodes. It is widely used for efficient validation of inclusion proofs in pre-defined datasets.
31+
32+
### Key Features of BMT
33+
* **Simple Structure:** Designed for static datasets.
34+
* **Inclusion Proofs:** Focused on validating the presence of data.
35+
* **Lightweight and Efficient:** Reduces computational complexity.
36+
37+
### Benefits of BMT
38+
* **Straightforward Implementation:** Easy to integrate and understand.
39+
* **Ideal for static whitelists:** Perfect for use cases where the whitelist doesn't change.
40+
* **Seamless Integration:** Works with libraries like OpenZeppelin's `MerkleProof`.
41+
42+
### Use Cases
43+
* **Static Whitelists:** Verify pre-computed whitelists for token minting.
44+
* **Efficient Validation:** Quickly validate authorized users.
45+
46+
---
47+
48+
## Differences Between CMT and BMT
49+
50+
| **Criteria** | **Cartesian Merkle Tree (CMT)** | **Binary Merkle Tree (BMT)** |
51+
|---------------------------|----------------------------------------------|--------------------------------------------|
52+
| **Structure** | Combination of BST, heap, and Merkle Tree | Simple binary Merkle Tree |
53+
| **Dynamic Management** | Supports dynamic addition and removal | Designed for static datasets |
54+
| **Proof Types** | Inclusion and exclusion | Inclusion only |
55+
| **Complexity** | Higher complexity, supports advanced cases | Lower complexity, easy to implement |
56+
| **Use Cases** | Dynamic whitelists, ZK-proof applications | Static whitelists, basic validation |
57+
58+
---
59+
60+
## Token Minting with Merkle Trees
61+
62+
### Why Use Merkle Trees for Whitelist Management?
63+
* **Security:** Ensures only authorized users interact with the contract.
64+
* **Efficiency:** Reduces validation costs using cryptographic proofs.
65+
* **Flexibility:** CMT allows dynamic updates, while BMT is optimized for static setups.
66+
67+
### Implementation Highlights
68+
1. **Whitelist Validation:** Both approaches use cryptographic proofs to validate user inclusion.
69+
2. **Token Minting:** Users can mint tokens only if they provide a valid proof.
70+
3. **Merkle Root Management:** Contracts validate proofs using the root hash of the Merkle Tree.
71+
72+
### When to Use Each Approach
73+
* **Use CMT** for dynamic whitelists where permissions need to change frequently.
74+
* **Use BMT** for static whitelists that are pre-defined and unlikely to change.
75+
76+
---
77+
78+
## How to Run Tests
79+
80+
### Prerequisites
81+
* **Foundry:** A testing framework for Solidity.
82+
* **Node.js:** To manage dependencies and scripts.
83+
84+
### Steps
85+
1. **Clone the Repository:**
86+
```bash
87+
git clone https://github.com/your-repo/merkle-trees.git
88+
cd merkle-trees
89+
```
90+
91+
2. **Install Dependencies:**
92+
```bash
93+
forge install
94+
```
95+
96+
3. **Run Tests:**
97+
```bash
98+
forge test
99+
```
100+
101+
---
102+
103+
This README provides a comprehensive overview of Cartesian and Binary Merkle Tree implementations for secure whitelist management and token minting. Choose the approach that best fits your project's needs!
104+

‎foundry.toml

+11
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
[profile.default]
2+
src = "src"
3+
out = "out"
4+
libs = ["lib"]
5+
6+
remappings = [
7+
'@openzeppelin/contracts/=lib/openzeppelin-contracts/contracts/',
8+
'@openzeppelin/contracts-upgradeable/=lib/openzeppelin-contracts-upgradeable/contracts/',
9+
]
10+
11+
# See more config options https://github.com/foundry-rs/foundry/blob/master/crates/config/README.md#all-options

‎goMKT/go.mod

+3
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
module markleTrees/goMKT
2+
3+
go 1.23.4

‎goMKT/main.go

Whitespace-only changes.

‎goMKT/markleMint/markleCMT.go

+3
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
package markleMint
2+
3+

‎goMKT/markleMint/markleSimple.go

+3
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
package markleMint
2+
3+

‎lib/forge-std/.gitattributes

+1
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
src/Vm.sol linguist-generated

‎lib/forge-std/.github/workflows/ci.yml

+128
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,128 @@
1+
name: CI
2+
3+
on:
4+
workflow_dispatch:
5+
pull_request:
6+
push:
7+
branches:
8+
- master
9+
10+
jobs:
11+
build:
12+
runs-on: ubuntu-latest
13+
steps:
14+
- uses: actions/checkout@v4
15+
16+
- name: Install Foundry
17+
uses: foundry-rs/foundry-toolchain@v1
18+
with:
19+
version: nightly
20+
21+
- name: Print forge version
22+
run: forge --version
23+
24+
# Backwards compatibility checks:
25+
# - the oldest and newest version of each supported minor version
26+
# - versions with specific issues
27+
- name: Check compatibility with latest
28+
if: always()
29+
run: |
30+
output=$(forge build --skip test)
31+
if echo "$output" | grep -q "Warning"; then
32+
echo "$output"
33+
exit 1
34+
fi
35+
36+
- name: Check compatibility with 0.8.0
37+
if: always()
38+
run: |
39+
output=$(forge build --skip test --use solc:0.8.0)
40+
if echo "$output" | grep -q "Warning"; then
41+
echo "$output"
42+
exit 1
43+
fi
44+
45+
- name: Check compatibility with 0.7.6
46+
if: always()
47+
run: |
48+
output=$(forge build --skip test --use solc:0.7.6)
49+
if echo "$output" | grep -q "Warning"; then
50+
echo "$output"
51+
exit 1
52+
fi
53+
54+
- name: Check compatibility with 0.7.0
55+
if: always()
56+
run: |
57+
output=$(forge build --skip test --use solc:0.7.0)
58+
if echo "$output" | grep -q "Warning"; then
59+
echo "$output"
60+
exit 1
61+
fi
62+
63+
- name: Check compatibility with 0.6.12
64+
if: always()
65+
run: |
66+
output=$(forge build --skip test --use solc:0.6.12)
67+
if echo "$output" | grep -q "Warning"; then
68+
echo "$output"
69+
exit 1
70+
fi
71+
72+
- name: Check compatibility with 0.6.2
73+
if: always()
74+
run: |
75+
output=$(forge build --skip test --use solc:0.6.2)
76+
if echo "$output" | grep -q "Warning"; then
77+
echo "$output"
78+
exit 1
79+
fi
80+
81+
# via-ir compilation time checks.
82+
- name: Measure compilation time of Test with 0.8.17 --via-ir
83+
if: always()
84+
run: forge build --skip test --contracts test/compilation/CompilationTest.sol --use solc:0.8.17 --via-ir
85+
86+
- name: Measure compilation time of TestBase with 0.8.17 --via-ir
87+
if: always()
88+
run: forge build --skip test --contracts test/compilation/CompilationTestBase.sol --use solc:0.8.17 --via-ir
89+
90+
- name: Measure compilation time of Script with 0.8.17 --via-ir
91+
if: always()
92+
run: forge build --skip test --contracts test/compilation/CompilationScript.sol --use solc:0.8.17 --via-ir
93+
94+
- name: Measure compilation time of ScriptBase with 0.8.17 --via-ir
95+
if: always()
96+
run: forge build --skip test --contracts test/compilation/CompilationScriptBase.sol --use solc:0.8.17 --via-ir
97+
98+
test:
99+
runs-on: ubuntu-latest
100+
steps:
101+
- uses: actions/checkout@v4
102+
103+
- name: Install Foundry
104+
uses: foundry-rs/foundry-toolchain@v1
105+
with:
106+
version: nightly
107+
108+
- name: Print forge version
109+
run: forge --version
110+
111+
- name: Run tests
112+
run: forge test -vvv
113+
114+
fmt:
115+
runs-on: ubuntu-latest
116+
steps:
117+
- uses: actions/checkout@v4
118+
119+
- name: Install Foundry
120+
uses: foundry-rs/foundry-toolchain@v1
121+
with:
122+
version: nightly
123+
124+
- name: Print forge version
125+
run: forge --version
126+
127+
- name: Check formatting
128+
run: forge fmt --check

‎lib/forge-std/.github/workflows/sync.yml

+31
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
name: Sync Release Branch
2+
3+
on:
4+
release:
5+
types:
6+
- created
7+
8+
jobs:
9+
sync-release-branch:
10+
runs-on: ubuntu-latest
11+
if: startsWith(github.event.release.tag_name, 'v1')
12+
steps:
13+
- name: Check out the repo
14+
uses: actions/checkout@v4
15+
with:
16+
fetch-depth: 0
17+
ref: v1
18+
19+
# The email is derived from the bots user id,
20+
# found here: https://api.github.com/users/github-actions%5Bbot%5D
21+
- name: Configure Git
22+
run: |
23+
git config user.name github-actions[bot]
24+
git config user.email 41898282+github-actions[bot]@users.noreply.github.com
25+
26+
- name: Sync Release Branch
27+
run: |
28+
git fetch --tags
29+
git checkout v1
30+
git reset --hard ${GITHUB_REF}
31+
git push --force

‎lib/forge-std/.gitignore

+4
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
cache/
2+
out/
3+
.vscode
4+
.idea

0 commit comments

Comments
 (0)