[{"data":1,"prerenderedAt":4},["ShallowReactive",2],{"xMBjxUkYty":3},"# Bignum-Lean: Port of s2n-bignum to Lean 4\n\nA port of Amazon's [s2n-bignum](https://github.com/awslabs/s2n-bignum)\nformal verification from HOL Light to Lean 4.\n\n## Overview\n\nThis project aims to port the formally verified cryptographic\narithmetic library s2n-bignum from HOL Light to Lean 4. The s2n-bignum\nlibrary provides high-performance, constant-time implementations of\nbig integer arithmetic operations used in cryptography, with\nmachine-checked proofs of correctness.\n\n## Project Structure\n\n```\nbignum-lean/\n├── Bignum/\n│   ├── Common/                  # Shared between architectures\n│   │   ├── Basic/\n│   │   │   ├── Defs.lean        # bigdigit, highdigits, lowdigits\n│   │   │   └── Lemmas.lean      # Core theorems\n│   │   ├── Word.lean            # 64-bit word arithmetic\n│   │   └── Memory.lean          # Memory model\n│   │\n│   ├── Arm/                     # ARM-specific (AArch64)\n│   │   ├── Machine/\n│   │   │   ├── State.lean       # ARM state (registers, flags, memory)\n│   │   │   ├── Instruction.lean # ARM instruction types\n│   │   │   ├── Decode.lean      # Instruction decoder (bytes → instructions)\n│   │   │   └── Loader.lean      # ELF/Mach-O object file loader\n│   │   ├── Spec.lean            # Pre/post/frame specifications + semantics\n│   │   ├── Generic/             # Generic bignum operations (future)\n│   │   ├── Curve/               # Elliptic curve operations (future)\n│   │   └── Tutorial/            # Port of arm tutorials\n│   │\n│   └── X86/                     # x86-64-specific (future)\n│       ├── Machine/\n│       ├── Spec/\n│       ├── Generic/\n│       ├── Curve/\n│       └── Tutorial/\n│\n└── s2n-bignum/                  # Original HOL Light source (submodule)\n```\n\n## Correspondence with s2n-bignum\n\nEach Lean file documents its correspondence with the original HOL\nLight source. The structure mirrors s2n-bignum's organization by\narchitecture:\n\n### Core Infrastructure\n\n| Lean File                             | HOL Light Source             | Description                         |\n|---------------------------------------|------------------------------|-------------------------------------|\n| `Bignum/Common/Basic/Defs.lean`       | `common/bignum.ml:11-77`     | Core bignum definitions             |\n| `Bignum/Common/Basic/Lemmas.lean`     | `common/bignum.ml:79-150`    | Fundamental theorems                |\n| `Bignum/Common/Word.lean`             | HOL Light `Library/words.ml` | 64-bit word operations              |\n| `Bignum/Common/Memory.lean`           | `common/components.ml`       | Memory model                        |\n| `Bignum/Arm/Machine/State.lean`       | `arm/proofs/arm.ml`          | ARM machine state                   |\n| `Bignum/Arm/Machine/Instruction.lean` | `arm/proofs/instruction.ml`  | ARM instructions                    |\n| `Bignum/Arm/Machine/Decode.lean`      | `arm/proofs/decode.ml`       | Instruction decoder                 |\n| `Bignum/Arm/Machine/Loader.lean`      | `common/common/elf.ml`       | ELF/Mach-O object loader            |\n| `Bignum/Arm/Spec.lean`                | `arm/proofs/arm.ml`          | Semantics + specification framework |\n\n\n## Building\n\n```bash\nlake build\n```\n\n## Development Plan\n\nThe development plan follows the s2n-bignum tutorial progression. Each\nphase implements one tutorial, incrementally building the verification\ninfrastructure. After completing all ARM tutorials, we'll expand to\nx86-64.\n\n### ✅ Phase 0: Foundations (Complete)\n\n**Goal:** Verify a simple 2-instruction linear program\n\n**What we built:**\n- Core bignum definitions (bigdigit, highdigits, lowdigits)\n- ARM state model (registers, flags, memory)\n- Basic instructions (ADD, SUB, ADCS)\n- Operational semantics (instruction execution)\n- Specification framework (`ensures` with pre/post/frame)\n- Instruction decoder (bytes → instructions)\n\n**Deliverable:** `Bignum/Arm/Tutorial/Simple.lean`\n\n### ✅ Phase 1: Program Composition (Complete)\n\n**Goal:** Verify programs by splitting into sequential chunks with\nintermediate assertions\n\n**What we built:**\n- Instructions: `MOV`, `MUL`\n- Tactic: `ENSURES_SEQUENCE_TAC` (split program with intermediate state)\n- Object file loader: `Loader.lean` (ELF/Mach-O `.o` parser)\n\n**Deliverable:** `Bignum/Arm/Tutorial/Sequence.lean`\n\n\n### Phase 2: Conditional Branching\n\n**Goal:** Verify programs with conditional branches\n\n**New capabilities needed:**\n- Instructions: `CMP` (comparison with flags), `B.HI` (conditional\n  branch), `RET`\n- Flag reasoning: `SOME_FLAGS`, condition codes (ZF, CF, NF, VF)\n- Case analysis: branch taken vs not taken\n- Events: microarchitectural event tracking\n\n**Deliverable:** `Bignum/Arm/Tutorial/Branch.lean`\n\n\n### Phase 3: Memory Operations\n\n**Goal:** Verify programs that read/write memory\n\n**New capabilities needed:**\n- Instructions: `LDR` (load register), `STR` (store register)\n- Memory model: `bytes64`, reading/writing 64-bit words\n- Preconditions: `nonoverlapping` (aliasing constraints)\n- MAYCHANGE: track memory locations that may change\n\n**Deliverable:** `Bignum/Arm/Tutorial/Memory.lean`\n\n\n### Phase 4: Loops\n\n**Goal:** Verify programs with simple loops using invariants\n\n**New capabilities needed:**\n- Instructions: `B.NE` (branch if not equal)\n- Tactic: `ENSURES_WHILE_PAUP_TAC` (loop invariant tactic)\n- Loop invariants: relate loop counter to program state\n- Backedge reasoning: prove loop continues until condition\n\n**Deliverable:** `Bignum/Arm/Tutorial/Loop.lean`\n\n\n### Phase 5: Bignum Operations\n\n**Goal:** Verify programs operating on multi-word bignums\n\n**New capabilities needed:**\n- Instructions: `LDP` (load pair of registers)\n- Abstraction: `bignum_from_memory` (read multi-word values)\n- Tactic: `BIGNUM_DIGITIZE_TAC` (split bignum into digits)\n- Full .o parser: complete `define_assert_from_elf` implementation\n\n**Deliverable:** `Bignum/Arm/Tutorial/Bignum.lean`\n\n\n### Phase 6: Read-Only Data\n\n**Goal:** Verify programs that read from .rodata section\n\n**New capabilities needed:**\n- Instructions: `ADRP` (page-relative address), `ADD` (with\n  immediate), `B` (unconditional branch)\n- PC-relative addressing: compute addresses relative to program counter\n- Relocation parser: `define_assert_relocs_from_elf`\n- Read-only section: `bytelist` for constant data\n- Subroutines: `ARM_SUBROUTINE_SIM_TAC` (function call reasoning)\n\n**Deliverable:** `Bignum/Arm/Tutorial/Rodata.lean`\n\n\n### Phase 7: Relational Reasoning - Basics\n\n**Goal:** Prove equivalence of two simple straight-line programs\n\n**New capabilities needed:**\n- Framework: `ensures2` (relational Hoare triple)\n- Tactics:\n  - `ENSURES2_INIT_TAC` (initialize relational symbolic execution)\n  - `ARM_N_STUTTER_LEFT_TAC` (execute left program only)\n  - `ARM_N_STUTTER_RIGHT_TAC` (execute right program only)\n  - `META_EXISTS_TAC`, `UNIFY_REFL_TAC` (unification)\n  - `MONOTONE_MAYCHANGE_CONJ_TAC`\n\n**Deliverable:** `Bignum/Arm/Tutorial/RelSimp.lean`\n\n\n### Phase 8: Relational Reasoning - Equivalence Tactics\n\n**Goal:** Prove equivalence using actions (diff-based approach)\n\n**New capabilities needed:**\n- Helper: `mk_equiv_statement_simple` (build equivalence goal)\n- Predicates: `eqin`, `eqout` (input/output state equivalence)\n- Tactics:\n  - `EQUIV_INITIATE_TAC`\n  - `EQUIV_STEPS_TAC` (lockstep + stuttering based on actions)\n- Actions: list of (\"equal\", ...) and (\"replace\", ...) for instruction alignment\n\n**Deliverable:** `Bignum/Arm/Tutorial/RelEquivTac.lean`\n\n\n### Phase 9: Relational Reasoning - Reordering\n\n**Goal:** Prove equivalence of programs with reordered instructions\n\n**New capabilities needed:**\n- Tactics:\n  - `ARM_N_STEPS_AND_ABBREV_TAC` (execute with abbreviations)\n  - `ARM_N_STEPS_AND_REWRITE_TAC` (execute and match abbreviations)\n- Instruction mapping: list mapping instruction indices between programs\n\n**Deliverable:** `Bignum/Arm/Tutorial/RelReorderTac.lean`\n\n\n### Phase 10: Relational Reasoning - Loops\n\n**Goal:** Prove equivalence of two loops\n\n**New capabilities needed:**\n- Tactic: `ENSURES2_WHILE_PAUP_TAC` (relational loop invariant)\n- Loop synchronization: relate loop counters and invariants\n\n**Deliverable:** `Bignum/Arm/Tutorial/RelLoop.lean`\n\n\n### Phase 11: Relational Reasoning - SIMD/Vectorization\n\n**Goal:** Prove equivalence of scalar vs vectorized implementations\n(128×128→256-bit squaring)\n\n**New capabilities needed:**\n- SIMD/NEON instructions: `LDR Q`, `UMULL_VEC`, `UMULL2_VEC`, `XTN`, `UZP2`,\n  `UMOV`, `EXTR`\n- NEON helper: vector reasoning lemmas and tactics\n- Advanced simplification: `WORD_BITMANIP_SIMP_LEMMAS`, custom word equations\n- Realistic optimization patterns\n\n**Deliverable:** `Bignum/Arm/Tutorial/RelVecEq.lean`\n\n--- \n\nAfter completing all ARM tutorials, expand to x86-64 architecture\nfollowing the same tutorial structure (`x86/tutorial/`).\n\n\n## Design Principles\n\n1. **Incremental Development:** Each phase builds on previous work\n2. **Fidelity to Original:** Maintain close correspondence with s2n-bignum\n3. **Documentation:** Every definition references its HOL Light source\n4. **Reusable Automation:** Build tactic libraries for common patterns\n5. **Validation:** Cross-check against s2n-bignum test suite where possible\n\n## Key Differences from HOL Light\n\n| Aspect           | HOL Light                   | Lean 4                                  |\n|------------------|-----------------------------|-----------------------------------------|\n| **Type System**  | Simple types                | Dependent types                         |\n| **Memory Model** | Component abstraction       | Functional map `Address → Option UInt8` |\n| **Words**        | `:(N)word` type             | `BitVec 64`                             |\n| **Proof Style**  | Tactical (forward/backward) | Tactic + term mode                      |\n| **Automation**   | `WORD_RULE` for arithmetic  | Lean tactics and custom tactics         |\n\n\n## Contributing\n\nWhen adding new verified functions:\n\n1. Reference the corresponding HOL Light file and line numbers\n2. Document the specification (pre/post/frame)\n3. Maintain correspondence comments\n4. Add to the appropriate module (`Generic/`, `Curve/`, etc.)\n5. Update this README with progress\n\n## References\n\n- [s2n-bignum GitHub](https://github.com/awslabs/s2n-bignum)\n- [HOL Light](https://github.com/jrh13/hol-light)\n- [Lean 4 Manual](https://lean-lang.org/lean4/doc/)\n\n",1780113391682]