From 1800aa59b33bab78b347dd9ea9cd08bd238ca2e1 Mon Sep 17 00:00:00 2001 From: Alejandro Cabeza Romero Date: Wed, 27 May 2026 16:41:00 +0200 Subject: [PATCH] Add markdown linting to pre-commit and format files. --- .markdownlint.json | 3 +++ .pre-commit-config.yaml | 5 ++++ CHANGELOG.md | 8 +++---- CONTRIBUTING.md | 51 ++++++++++++++++++++++------------------- README.md | 4 ++-- docs/build-pipeline.md | 2 +- rust/README.md | 8 +++---- 7 files changed, 46 insertions(+), 35 deletions(-) create mode 100644 .markdownlint.json diff --git a/.markdownlint.json b/.markdownlint.json new file mode 100644 index 0000000..8e1eca2 --- /dev/null +++ b/.markdownlint.json @@ -0,0 +1,3 @@ +{ + "MD013": { "line_length": 120, "tables": false } +} diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 74aadb4..ecede80 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -37,6 +37,11 @@ repos: hooks: - id: cargo-machete args: ["rust/"] + - repo: https://github.com/igorshubovych/markdownlint-cli + rev: e72a3ca1632f0b11a07d171449fe447a7ff6795e # v0.48.0 + hooks: + - id: markdownlint + args: ["-f"] - repo: local hooks: - id: cargo-hack-check diff --git a/CHANGELOG.md b/CHANGELOG.md index 19d3153..6bc6efd 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -13,9 +13,9 @@ All notable changes to this project will be documented in this file. Each circuit is now a linkable static archive (`lib{circuit}.a`) with a stable C FFI. Two entry points per circuit: - - `{circuit}_generate_witness(WitnessInput*, Bytes*)`: Generates a witness in memory from a + - `{circuit}_generate_witness(WitnessInput*, Bytes*)`: Generates a witness in memory from a JSON input string and an embedded `.dat` buffer; the caller owns the output buffer. - - `{circuit}_generate_witness_from_files(dat, inputs, output)`: Generates a witness from a `.dat` file and a JSON + - `{circuit}_generate_witness_from_files(dat, inputs, output)`: Generates a witness from a `.dat` file and a JSON input file, writing the witness to an output file. The Rust crates (`lbc-{circuit}-sys`) wrap this FFI directly and can either link against a local build or download a @@ -25,7 +25,7 @@ All notable changes to this project will be documented in this file. - **Bundled static GMP** (#19) - `libgmp` is now compiled from source and statically linked, removing the runtime dependency on a system GMP + `libgmp` is now compiled from source and statically linked, removing the runtime dependency on a system GMP installation, and standardizing the GMP version used across all platforms. - **Older glibc compatibility** (#21) @@ -38,7 +38,7 @@ All notable changes to this project will be documented in this file. - **Symbol resolution conflicts** (#22, #28, #29) - When multiple circuit libraries are linked into the same binary, the linker silently collapsed shared internal + When multiple circuit libraries are linked into the same binary, the linker silently collapsed shared internal symbols to a single definition, corrupting witness parsing and causing SIGSEGV. See [CONTRIBUTING.md](CONTRIBUTING.md#symbol-isolation-in-circuit-libraries) for a full explanation and maintenance diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e8d0bdc..ff4349b 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -6,16 +6,20 @@ #### Sys development -- [Rust](https://rustup.rs/) — the pinned toolchain version is in `rust-toolchain.toml` and will be installed automatically by `rustup`. -- Compiled circuit libraries (`.a` files and `witness_generator.dat`) — see [rust/README.md](rust/README.md) for how to provide them. +- [Rust](https://rustup.rs/) — the pinned toolchain version is in `rust-toolchain.toml` and will be installed + automatically by `rustup`. +- Compiled circuit libraries (`.a` files and `witness_generator.dat`) — see [rust/README.md](rust/README.md) for how to + provide them. #### Building circuits -- `llvm-objcopy` — required for symbol isolation when building circuit static libraries. On macOS, install via `brew install llvm` (LLVM 20+ required). +- `llvm-objcopy` — required for symbol isolation when building circuit static libraries. On macOS, install via `brew + install llvm` (LLVM 20+ required). ### Pre-Commit -[pre-commit](https://pre-commit.com/) covers most of the lints required by CI. It's not mandatory — you can run checks however you like — but it's the easiest way to catch issues before pushing. +[pre-commit](https://pre-commit.com/) covers most of the lints required by CI. It's not mandatory — you can run checks +however you like — but it's the easiest way to catch issues before pushing. #### Installation @@ -43,6 +47,7 @@ The comment there lists every other place that must be updated in sync (nightly #### Tool Versions `taplo`, `cargo-deny`, and `cargo-machete` are pinned in two places that must stay in sync: + - `.pre-commit-config.yaml` (hook `rev`) - `.github/workflows/lint.yml` (`cargo install --version`) @@ -60,11 +65,11 @@ For a full walkthrough of the CI build steps, from `.circom` source to release a Each circuit (PoQ, PoL, PoC, Signature) is compiled into a static archive (`libpoq.a`, `libpol.a`, etc.). All archives share the same symbols, compiled from the same source files but with **different constant values per circuit** (e.g. `get_size_of_witness()` returns 18149 for PoQ and 20531 for PoL). -When two or more circuit libraries are linked into the same binary, the linker silently picks the first definition it +When two or more circuit libraries are linked into the same binary, the linker silently picks the first definition it encounters for each symbol and discards the rest without any sort of error or warning. -The result is that one circuit's constants end up hardwired into functions shared by both circuits, corrupting witness -parsing. -In practice: the wrong `get_size_of_witness()` value causes `loadCircuit` to compute an incorrect buffer size, `pu32` +The result is that one circuit's constants end up hardwired into functions shared by both circuits, corrupting witness +parsing. +In practice: the wrong `get_size_of_witness()` value causes `loadCircuit` to compute an incorrect buffer size, `pu32` walks off the end of the buffer, reads garbage as a length field, and the subsequent `memcpy` reads past the stack guard page, which results in a **SIGSEGV**. @@ -86,26 +91,24 @@ symbols to local, confusing the linker's deduplication logic and causing "reloca symbol in discarded section" errors. `llvm-objcopy` additionally clears the `GRP_COMDAT` flag, turning affected sections into regular non-COMDAT sections. Slightly larger binary, no linker errors. -**Platform notes** - -**macOS** +##### macOS Uses `llvm-objcopy` (from `brew install llvm`, LLVM 20+). Mach-O prepends `_` to every C symbol, so `--keep-global-symbol` arguments must include the leading `_`. The Makefile's `SYM_PREFIX` variable handles this automatically. -**Windows** +##### Windows Uses GNU's `objcopy` (from MinGW binutils). GNU's `objcopy` works correctly on COFF, mapping local binding to storage class `C_STAT`. The ELF `GRP_COMDAT` problem doesn't apply: COFF COMDAT is per-section rather than group-based. -#### Maintenance +#### FFI Maintenance `PUBLIC_SYMS` is hardcoded to `$(PROJECT)_generate_witness` and `$(PROJECT)_generate_witness_from_files` in the -Makefile. If the public FFI API ever changes — entry points renamed or new ones added — update that variable, otherwise +Makefile. If the public FFI API ever changes — entry points renamed or new ones added — update that variable, otherwise the affected symbols will be localized and linking will fail. --- @@ -117,27 +120,28 @@ the affected symbols will be localized and linking will fail. To trigger a release build: 1. Create and push a tag in the format `vX.Y.Z`: + ```bash git tag v1.2.3 -m "Release v1.2.3" git push --tags ``` + 2. This will automatically trigger the `.github/workflows/build_circuits.yml` workflow. 3. Once the workflow finishes, the generated artifacts will be attached to a new release. -> Pull Requests will also generate artifacts, which may be found in the job's page, but won't generate a new release. - -> Currently, releases published this way are marked as **Draft** and **Pre-Release** to ensure that the changelog and -> pre-release steps are manually reviewed first. +> Pull Requests will also generate artifacts, which may be found on the job's page, but won't generate a new release. #### Generated artifacts -For each supported platform (Linux x86_64, Linux aarch64, macOS aarch64, Windows x86_64), a release artifact is generated: +For each supported platform (Linux x86_64, Linux aarch64, macOS aarch64, Windows x86_64), a release artifact is +generated: -**`logos-blockchain-circuits-{version}-{os}-{arch}.tar.gz`** — a complete bundle containing all components needed to generate and verify proofs for all circuits. +**`logos-blockchain-circuits-{version}-{os}-{arch}.tar.gz`** — a complete bundle containing all components needed to +generate and verify proofs for all circuits. **Bundle Structure:** -``` +```text logos-blockchain-circuits-{version}-{os}-{arch}/ ├── lib/ │ └── libgmp.a @@ -158,8 +162,8 @@ The proving keys are generated using the Hermez Powers of Tau ceremony — see [ ### Publishing -After triggering the release, it will appear as a **Draft** and **Pre-Release**. -Before making it public, make sure to: +Releases are marked as **Draft** and **Pre-Release** to ensure the changelog and pre-release steps are manually reviewed +before going public. Before publishing: 1. **Review the changelog** Ensure that all relevant changes are clearly listed and properly formatted. @@ -169,4 +173,3 @@ Before making it public, make sure to: 3. **Mark the release as published** - Uncheck **“This is a pre-release.”** - Publish the release (removing the Draft state). - diff --git a/README.md b/README.md index 8185cb0..96506e9 100644 --- a/README.md +++ b/README.md @@ -12,7 +12,6 @@ ZK-SNARK circuits for the [Logos Blockchain](https://github.com/logos-blockchain | **PoC** — Proof of Claim | A voucher is validly owned and its nullifier is correctly derived | | **Signature** | Knowledge of secret keys and their corresponding public keys | - ## Architecture ```mermaid @@ -40,7 +39,8 @@ flowchart TD DAT -->|Embedded into| G ``` -Each circuit is compiled from Circom source to C++, combined with shared common files (`circom_adapter`, `types`, ...) and a circuit-specific FFI layer (`src/{circuit}/ffi.cpp`), and built into a static library. +Each circuit is compiled from Circom source to C++, combined with shared common files (`circom_adapter`, `types`, ...) +and a circuit-specific FFI layer (`src/{circuit}/ffi.cpp`), and built into a static library. The Rust sys crates link directly against these libraries. diff --git a/docs/build-pipeline.md b/docs/build-pipeline.md index 41c9939..a64671b 100644 --- a/docs/build-pipeline.md +++ b/docs/build-pipeline.md @@ -61,7 +61,7 @@ It consists of two groups of files copied into `{circuit}_cpp/` before compilati - **Circuit-specific entry points** (`src/{circuit}/ffi.cpp`): The public `extern "C"` functions that become the library's API. -``` +```text src/ types.hpp → copied into {circuit}_cpp/ circom_adapter.cpp → copied into {circuit}_cpp/ diff --git a/rust/README.md b/rust/README.md index 547cc22..c38448e 100644 --- a/rust/README.md +++ b/rust/README.md @@ -32,6 +32,7 @@ lbc-poq-sys = { version = "0.5", features = ["prebuilt"] } ``` The cache location depends on the operating system: + - Linux: `~/.cache/logos/blockchain/` - macOS: `~/Library/Caches/logos/blockchain/` - Windows: `%LOCALAPPDATA%\logos\blockchain\` @@ -51,10 +52,10 @@ LBC_LIB_DIR=/path/to/lib # Directory containing the required lib # If using a release bundle, this is the included lib/ directory ``` -> The `justfile` at the repo root contains recipes (`just poq`, `just pol`, etc.) that build the circuit libraries from +> The `justfile` at the repo root contains recipes (`just poq`, `just pol`, etc.) that build the circuit libraries from > source. -> -> This is not yet an officially supported workflow, but it can serve as a reference if you need to produce the +> +> This is not yet an officially supported workflow, but it can serve as a reference if you need to produce the > libraries yourself. ## Usage @@ -91,7 +92,6 @@ fn main() -> Result<(), Error> { The other circuits follow the same pattern under `lbc_pol_sys`, `lbc_poc_sys` and `lbc_signature_sys`. - ## Running tests ```bash