Formally prove the correctness of Sqrt.sol and Cbrt.sol

.github/workflows/cbrt-formal.yml

@@ -0,0 +1,76 @@
+name: Cbrt.sol Formal Check
+
+on:
+  push:
+    branches:
+      - master
+    paths:
+      - src/vendor/Cbrt.sol
+      - src/wrappers/CbrtWrapper.sol
+      - formal/cbrt/**
+      - formal/python/**
+      - test/0.8.25/Cbrt.t.sol
+      - test/0.8.25/formal-model/FormalModelFFI.t.sol
+      - test/0.8.25/formal-model/CbrtModel.t.sol
+      - .github/workflows/cbrt-formal.yml
+  pull_request:
+    paths:
+      - src/vendor/Cbrt.sol
+      - src/wrappers/CbrtWrapper.sol
+      - formal/cbrt/**
+      - formal/python/**
+      - test/0.8.25/Cbrt.t.sol
+      - test/0.8.25/formal-model/FormalModelFFI.t.sol
+      - test/0.8.25/formal-model/CbrtModel.t.sol
+      - .github/workflows/cbrt-formal.yml
+
+jobs:
+  cbrt-formal:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          submodules: recursive
+
+      - name: Install Foundry
+        uses: foundry-rs/foundry-toolchain@v1
+
+      - name: Install Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install pinned Lean toolchain
+        run: |
+          curl https://raw.githubusercontent.com/leanprover/elan/917c18d0ad52f649c2603dc8b973f5b9fa5f8f43/elan-init.sh -sSf | sh -s -- -y --default-toolchain none
+          echo "$HOME/.elan/bin" >> "$GITHUB_PATH"
+          LEAN_TOOLCHAIN="$(cat formal/cbrt/CbrtProof/lean-toolchain)"
+          "$HOME/.elan/bin/elan" toolchain install "$LEAN_TOOLCHAIN"
+          "$HOME/.elan/bin/elan" default "$LEAN_TOOLCHAIN"
+
+      - name: Install solc 0.8.34
+        run: forge build -- src/chains/Mainnet/TakerSubmitted.sol
+        env:
+          FOUNDRY_SOLC_VERSION: 0.8.34
+
+      - name: Generate Lean model from Cbrt.sol via Yul IR
+        run: |
+          forge inspect src/wrappers/CbrtWrapper.sol:CbrtWrapper ir | \
+            python3 -W error -m formal.python.cbrt.generate_cbrt_model \
+              --yul - \
+              --output formal/cbrt/CbrtProof/CbrtProof/GeneratedCbrtModel.lean
+
+      - name: Generate finite certificate from cbrt spec
+        run: |
+          python3 -m formal.python.cbrt.generate_cbrt_cert \
+            --output formal/cbrt/CbrtProof/CbrtProof/FiniteCert.lean
+
+      - name: Build Cbrt proof and model evaluator
+        working-directory: formal/cbrt/CbrtProof
+        run: lake build && lake build cbrt-model
+
+      - name: Fuzz-test Lean model against Solidity
+        run: |
+          FOUNDRY_PROFILE=formal-model forge test \
+            --skip 'src/*' --skip 'test/unit/*' --skip 'test/integration/*' --skip 'test/0.8.28/*' \
+            --match-contract CbrtModelTest

.github/workflows/cbrt512-formal.yml

@@ -0,0 +1,87 @@
+name: 512Math cbrt Formal Check
+
+on:
+  push:
+    branches:
+      - master
+    paths:
+      - src/utils/512Math.sol
+      - src/vendor/Cbrt.sol
+      - src/wrappers/CbrtWrapper.sol
+      - src/wrappers/Cbrt512Wrapper.sol
+      - formal/cbrt/**
+      - formal/python/**
+      - test/0.8.25/formal-model/FormalModelFFI.t.sol
+      - test/0.8.25/formal-model/Cbrt512Model.t.sol
+      - .github/workflows/cbrt512-formal.yml
+  pull_request:
+    paths:
+      - src/utils/512Math.sol
+      - src/vendor/Cbrt.sol
+      - src/wrappers/CbrtWrapper.sol
+      - src/wrappers/Cbrt512Wrapper.sol
+      - formal/cbrt/**
+      - formal/python/**
+      - test/0.8.25/formal-model/FormalModelFFI.t.sol
+      - test/0.8.25/formal-model/Cbrt512Model.t.sol
+      - .github/workflows/cbrt512-formal.yml
+
+jobs:
+  cbrt512-formal:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          submodules: recursive
+
+      - name: Install Foundry
+        uses: foundry-rs/foundry-toolchain@v1
+
+      - name: Install Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install pinned Lean toolchain
+        run: |
+          curl https://raw.githubusercontent.com/leanprover/elan/917c18d0ad52f649c2603dc8b973f5b9fa5f8f43/elan-init.sh -sSf | sh -s -- -y --default-toolchain none
+          echo "$HOME/.elan/bin" >> "$GITHUB_PATH"
+          LEAN_TOOLCHAIN="$(cat formal/cbrt/Cbrt512Proof/lean-toolchain)"
+          test "$LEAN_TOOLCHAIN" = "$(cat formal/cbrt/CbrtProof/lean-toolchain)"
+          "$HOME/.elan/bin/elan" toolchain install "$LEAN_TOOLCHAIN"
+          "$HOME/.elan/bin/elan" default "$LEAN_TOOLCHAIN"
+
+      - name: Install solc 0.8.34
+        run: forge build -- src/chains/Mainnet/TakerSubmitted.sol
+        env:
+          FOUNDRY_SOLC_VERSION: 0.8.34
+
+      - name: Generate 256-bit Lean model (CbrtProof dependency)
+        run: |
+          forge inspect src/wrappers/CbrtWrapper.sol:CbrtWrapper ir | \
+            python3 -W error -m formal.python.cbrt.generate_cbrt_model \
+              --yul - \
+              --output formal/cbrt/CbrtProof/CbrtProof/GeneratedCbrtModel.lean
+
+      - name: Generate finite certificate from cbrt spec
+        run: |
+          python3 -m formal.python.cbrt.generate_cbrt_cert \
+            --output formal/cbrt/CbrtProof/CbrtProof/FiniteCert.lean
+
+      - name: Generate 512-bit Lean model from Cbrt512Wrapper via Yul IR
+        run: |
+          FOUNDRY_SOLC_VERSION=0.8.34 \
+            forge inspect src/wrappers/Cbrt512Wrapper.sol:Cbrt512Wrapper ir | \
+            python3 -W error -m formal.python.cbrt.generate_cbrt512_model \
+              --yul - \
+              --output formal/cbrt/Cbrt512Proof/Cbrt512Proof/GeneratedCbrt512Model.lean
+
+      - name: Build Cbrt512 proof and model evaluator
+        working-directory: formal/cbrt/Cbrt512Proof
+        run: lake build && lake build cbrt512-model
+
+      - name: Fuzz-test Lean model against Solidity
+        run: |
+          FOUNDRY_PROFILE=formal-model forge test \
+            --skip 'src/*' --skip 'test/unit/*' --skip 'test/integration/*' --skip 'test/0.8.28/*' \
+            --match-contract Cbrt512ModelTest

.github/workflows/sqrt-formal.yml

@@ -0,0 +1,76 @@
+name: Sqrt.sol Formal Check
+
+on:
+  push:
+    branches:
+      - master
+    paths:
+      - src/vendor/Sqrt.sol
+      - src/wrappers/SqrtWrapper.sol
+      - formal/sqrt/**
+      - formal/python/**
+      - test/0.8.25/Sqrt.t.sol
+      - test/0.8.25/formal-model/FormalModelFFI.t.sol
+      - test/0.8.25/formal-model/SqrtModel.t.sol
+      - .github/workflows/sqrt-formal.yml
+  pull_request:
+    paths:
+      - src/vendor/Sqrt.sol
+      - src/wrappers/SqrtWrapper.sol
+      - formal/sqrt/**
+      - formal/python/**
+      - test/0.8.25/Sqrt.t.sol
+      - test/0.8.25/formal-model/FormalModelFFI.t.sol
+      - test/0.8.25/formal-model/SqrtModel.t.sol
+      - .github/workflows/sqrt-formal.yml
+
+jobs:
+  sqrt-formal:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          submodules: recursive
+
+      - name: Install Foundry
+        uses: foundry-rs/foundry-toolchain@v1
+
+      - name: Install Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install pinned Lean toolchain
+        run: |
+          curl https://raw.githubusercontent.com/leanprover/elan/917c18d0ad52f649c2603dc8b973f5b9fa5f8f43/elan-init.sh -sSf | sh -s -- -y --default-toolchain none
+          echo "$HOME/.elan/bin" >> "$GITHUB_PATH"
+          LEAN_TOOLCHAIN="$(cat formal/sqrt/SqrtProof/lean-toolchain)"
+          "$HOME/.elan/bin/elan" toolchain install "$LEAN_TOOLCHAIN"
+          "$HOME/.elan/bin/elan" default "$LEAN_TOOLCHAIN"
+
+      - name: Install solc 0.8.34
+        run: forge build -- src/chains/Mainnet/TakerSubmitted.sol
+        env:
+          FOUNDRY_SOLC_VERSION: 0.8.34
+
+      - name: Generate Lean model from Sqrt.sol via Yul IR
+        run: |
+          forge inspect src/wrappers/SqrtWrapper.sol:SqrtWrapper ir | \
+            python3 -W error -m formal.python.sqrt.generate_sqrt_model \
+              --yul - \
+              --output formal/sqrt/SqrtProof/SqrtProof/GeneratedSqrtModel.lean
+
+      - name: Generate finite certificate from sqrt spec
+        run: |
+          python3 -m formal.python.sqrt.generate_sqrt_cert \
+            --output formal/sqrt/SqrtProof/SqrtProof/FiniteCert.lean
+
+      - name: Build Sqrt proof and model evaluator
+        working-directory: formal/sqrt/SqrtProof
+        run: lake build && lake build sqrt-model
+
+      - name: Fuzz-test Lean model against Solidity
+        run: |
+          FOUNDRY_PROFILE=formal-model forge test \
+            --skip 'src/*' --skip 'test/unit/*' --skip 'test/integration/*' --skip 'test/0.8.28/*' \
+            --match-contract SqrtModelTest

.github/workflows/sqrt512-formal.yml

@@ -0,0 +1,85 @@
+name: 512Math sqrt Formal Check
+
+on:
+  push:
+    branches:
+      - master
+    paths:
+      - src/utils/512Math.sol
+      - src/vendor/Sqrt.sol
+      - src/wrappers/Sqrt512Wrapper.sol
+      - formal/sqrt/**
+      - formal/python/**
+      - test/0.8.25/formal-model/FormalModelFFI.t.sol
+      - test/0.8.25/formal-model/Sqrt512Model.t.sol
+      - .github/workflows/sqrt512-formal.yml
+  pull_request:
+    paths:
+      - src/utils/512Math.sol
+      - src/vendor/Sqrt.sol
+      - src/wrappers/Sqrt512Wrapper.sol
+      - formal/sqrt/**
+      - formal/python/**
+      - test/0.8.25/formal-model/FormalModelFFI.t.sol
+      - test/0.8.25/formal-model/Sqrt512Model.t.sol
+      - .github/workflows/sqrt512-formal.yml
+
+jobs:
+  sqrt512-formal:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          submodules: recursive
+
+      - name: Install Foundry
+        uses: foundry-rs/foundry-toolchain@v1
+
+      - name: Install Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install pinned Lean toolchain
+        run: |
+          curl https://raw.githubusercontent.com/leanprover/elan/917c18d0ad52f649c2603dc8b973f5b9fa5f8f43/elan-init.sh -sSf | sh -s -- -y --default-toolchain none
+          echo "$HOME/.elan/bin" >> "$GITHUB_PATH"
+          LEAN_TOOLCHAIN="$(cat formal/sqrt/Sqrt512Proof/lean-toolchain)"
+          test "$LEAN_TOOLCHAIN" = "$(cat formal/sqrt/SqrtProof/lean-toolchain)"
+          "$HOME/.elan/bin/elan" toolchain install "$LEAN_TOOLCHAIN"
+          "$HOME/.elan/bin/elan" default "$LEAN_TOOLCHAIN"
+
+      - name: Install solc 0.8.34
+        run: forge build -- src/chains/Mainnet/TakerSubmitted.sol
+        env:
+          FOUNDRY_SOLC_VERSION: 0.8.34
+
+      - name: Generate 256-bit Lean model (SqrtProof dependency)
+        run: |
+          forge inspect src/wrappers/SqrtWrapper.sol:SqrtWrapper ir | \
+            python3 -W error -m formal.python.sqrt.generate_sqrt_model \
+              --yul - \
+              --output formal/sqrt/SqrtProof/SqrtProof/GeneratedSqrtModel.lean
+
+      - name: Generate finite certificate from sqrt spec
+        run: |
+          python3 -m formal.python.sqrt.generate_sqrt_cert \
+            --output formal/sqrt/SqrtProof/SqrtProof/FiniteCert.lean
+
+      - name: Generate 512-bit Lean model from Sqrt512Wrapper via Yul IR
+        run: |
+          FOUNDRY_SOLC_VERSION=0.8.34 \
+            forge inspect src/wrappers/Sqrt512Wrapper.sol:Sqrt512Wrapper ir | \
+            python3 -W error -m formal.python.sqrt.generate_sqrt512_model \
+              --yul - \
+              --output formal/sqrt/Sqrt512Proof/Sqrt512Proof/GeneratedSqrt512Model.lean
+
+      - name: Build Sqrt512 proof and model evaluator
+        working-directory: formal/sqrt/Sqrt512Proof
+        run: lake build && lake build sqrt512-model
+
+      - name: Fuzz-test Lean model against Solidity
+        run: |
+          FOUNDRY_PROFILE=formal-model forge test \
+            --skip 'src/*' --skip 'test/unit/*' --skip 'test/integration/*' --skip 'test/0.8.28/*' \
+            --match-contract Sqrt512ModelTest

.github/workflows/yul-to-lean-unit.yml

@@ -0,0 +1,45 @@
+name: Translator Unit Tests
+
+on:
+  push:
+    branches:
+      - master
+    paths:
+      - formal/**/*.py
+      - pyproject.toml
+      - .github/workflows/yul-to-lean-unit.yml
+  pull_request:
+    paths:
+      - formal/**/*.py
+      - pyproject.toml
+      - .github/workflows/yul-to-lean-unit.yml
+
+jobs:
+  yul-to-lean-unit:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install Python tooling
+        run: |
+          python3 -m pip install \
+            black==26.3.0 \
+            isort==7.0.0 \
+            mypy==1.19.1
+
+      - name: Check formatting with black
+        run: python3 -m black --check formal
+
+      - name: Check import ordering with isort
+        run: python3 -m isort --check-only --filter-files formal
+
+      - name: Type-check formal Python
+        run: python3 -m mypy formal
+
+      - name: Run translator unit tests
+        run: python3 -m unittest formal.python.test_yul_to_lean -v

.gitignore

@@ -30,3 +30,6 @@ node_modules
 
 # user-specific local configuration
 /config/
+
+# Python bytecode cache directories
+__pycache__/