Skip to content

Commit c021d1f

Browse files
Th0rgalclaude
Th0rgal
and
claude
authored
docs: dependency audit, Helios pinning rationale, ethereum_hashing fork rationale (#165, #166, #167) (#175)
- DEPENDENCIES.md: audit every direct dependency across all packages, split into verification-path (security-critical) and UI/tooling (non-critical) categories with per-dependency justification. - Cargo.toml: add inline comments explaining why helios-consensus-core is pinned to git rev 582fda3 (a16z/helios#776 not yet in a tagged release) and why ethereum_hashing uses the ncitron fork (removes ring C dependency in favor of pure-Rust sha2). - README.md: link to DEPENDENCIES.md from the architecture section. Closes #165 Closes #166 Closes #167 Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
1 parent d4d4c4f commit c021d1f

3 files changed

Lines changed: 150 additions & 0 deletions

File tree

‎DEPENDENCIES.md‎

Lines changed: 137 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,137 @@
1+
# Dependency Audit
2+
3+
Why each dependency exists. Organized by package and split into verification-path (security-critical) vs UI/tooling (non-critical).
4+
5+
## Verification Path (security-critical)
6+
7+
These dependencies are in the trust boundary — they handle crypto, schema validation, or EVM execution.
8+
9+
### packages/core (TypeScript)
10+
11+
| Dependency | Version | Purpose |
12+
|---|---|---|
13+
| `viem` | ^2.21 | EIP-712 hashing, ABI decoding, RLP encoding, Merkle Patricia Trie proof verification. Standard Ethereum library with wide adoption and typed APIs. |
14+
| `zod` | ^4.3 | Schema validation at the trust boundary between evidence packages and the verifier. All package fields are validated before any crypto runs. No network access. |
15+
16+
### apps/desktop/src-tauri (Rust)
17+
18+
| Dependency | Version | Purpose |
19+
|---|---|---|
20+
| `helios-consensus-core` | git rev `582fda3` | BLS12-381 sync committee verification for beacon consensus proofs. See [Helios pinning rationale](#helios-pinning-rationale). |
21+
| `alloy` | 1.0.3 | Ethereum consensus types and SSZ deserialization. Used for parsing beacon block headers and execution payloads. Only `consensus` and `ssz` features enabled. |
22+
| `revm` | 34 | Local EVM execution for simulation replay. Runs witness world-state through the EVM to verify packaged simulation effects. Only `std` feature enabled, default features disabled. |
23+
| `tree_hash` | 0.12.1 | SSZ tree hashing for beacon block root computation. |
24+
| `hex` | 0.4 | Hex encoding/decoding for Ethereum address and hash conversions. |
25+
| `eyre` | 0.6.8 | Error handling in Rust verification path. |
26+
| `typenum` | 1 | Compile-time numeric types required by SSZ fixed-length vectors. |
27+
| `time` | 0.3 | Timestamp parsing for non-beacon envelope freshness checks. Only `parsing` feature enabled. |
28+
| `serde` / `serde_json` | 1 | JSON serialization for Tauri IPC between the TypeScript frontend and Rust backend. |
29+
30+
### Patched dependencies
31+
32+
| Dependency | Source | Purpose |
33+
|---|---|---|
34+
| `ethereum_hashing` | ncitron fork, rev `7ee7094` | See [ethereum_hashing fork rationale](#ethereum_hashing-fork-rationale). |
35+
36+
## UI and Tooling (non-critical)
37+
38+
These dependencies are not in the verification trust boundary. They handle rendering, styling, and build tooling.
39+
40+
### apps/desktop (TypeScript frontend)
41+
42+
| Dependency | Version | Purpose |
43+
|---|---|---|
44+
| `react` / `react-dom` | ^18.3 | UI rendering for the desktop verifier frontend. |
45+
| `@tauri-apps/api` | ^2.0 | Tauri framework frontend API (IPC, window management). |
46+
| `@tauri-apps/plugin-fs` | ^2.0 | File system access for loading evidence packages. |
47+
| `@tauri-apps/plugin-dialog` | ^2.0 | Native file picker dialogs. |
48+
| `viem` | ^2.21 | Address formatting utilities in the UI layer. |
49+
| `lucide-react` | ^0.454 | Icon library. |
50+
| `class-variance-authority` | ^0.7 | CSS class composition for component variants. |
51+
| `clsx` | ^2.1 | Conditional classname joining. |
52+
| `tailwind-merge` | ^2.5 | Tailwind CSS class conflict resolution. |
53+
54+
### apps/desktop (dev)
55+
56+
| Dependency | Purpose |
57+
|---|---|
58+
| `@tauri-apps/cli` | Tauri build toolchain. |
59+
| `vite` / `@vitejs/plugin-react` | Frontend bundler. |
60+
| `tailwindcss` / `postcss` | CSS tooling. |
61+
| `typescript` | Type checking. |
62+
63+
### apps/desktop (Rust, non-verification)
64+
65+
| Dependency | Version | Purpose |
66+
|---|---|---|
67+
| `tauri` | 2 | Desktop app framework. `macos-private-api` feature enables native sidebar vibrancy. |
68+
| `tauri-plugin-fs` / `tauri-plugin-dialog` | 2 | Tauri plugins for file and dialog access. |
69+
| `tauri-build` | 2 | Build-time code generation for Tauri. |
70+
| `window-vibrancy` | 0.6 | macOS native vibrancy effect for the sidebar. |
71+
72+
### apps/generator
73+
74+
| Dependency | Version | Purpose |
75+
|---|---|---|
76+
| `next` | ^14.2 | React framework. Serves the generator web app. |
77+
| `react` / `react-dom` | ^18.3 | UI rendering. |
78+
| `lucide-react` | ^0.454 | Icons. |
79+
| `class-variance-authority` / `clsx` / `tailwind-merge` | — | CSS utilities (same as desktop). |
80+
81+
### apps/generator (dev)
82+
83+
| Dependency | Purpose |
84+
|---|---|
85+
| `tailwindcss` / `postcss` / `autoprefixer` | CSS tooling. |
86+
| `eslint` / `eslint-config-next` | Linting. |
87+
| `typescript` | Type checking. |
88+
89+
### packages/core (dev)
90+
91+
| Dependency | Purpose |
92+
|---|---|
93+
| `vitest` | Unit test framework. |
94+
| `typescript` | Type checking. |
95+
| `@types/node` | Node.js type definitions. |
96+
97+
### packages/cli (dev)
98+
99+
| Dependency | Purpose |
100+
|---|---|
101+
| `typescript` | Type checking. |
102+
| `@types/node` | Node.js type definitions. |
103+
104+
## Helios Pinning Rationale
105+
106+
```toml
107+
helios-consensus-core = { git = "https://github.com/a16z/helios", rev = "582fda319ed1ecb5fb82c71f4fa755a32e01031a" }
108+
```
109+
110+
**Why a git rev instead of a tagged release?**
111+
112+
The pinned commit (`582fda3`, 2026-02-18) includes a fix for hex-encoded `blockNumber` and `chainId` fields in beacon API responses ([helios#776](https://github.com/a16z/helios/pull/776)). The latest tagged Helios release is `0.11.0` (2025-12-16), which does not include this fix. SafeLens needs it because beacon finality update responses from some clients return numeric fields as hex strings.
113+
114+
**Commit provenance:** The commit is on the `main` branch of `a16z/helios`, 17 commits ahead of the `0.11.0` tag. It will be included in the next Helios release.
115+
116+
**Action item:** When Helios publishes a release that includes commit `582fda3`, migrate from `rev = "..."` to a version or tag pin.
117+
118+
## ethereum_hashing Fork Rationale
119+
120+
```toml
121+
[patch.crates-io]
122+
ethereum_hashing = { git = "https://github.com/ncitron/ethereum_hashing", rev = "7ee70944ed4fabe301551da8c447e4f4ae5e6c35" }
123+
```
124+
125+
**What the fork changes:** The upstream `ethereum_hashing` crate (by `sigp`) uses the `ring` cryptography library for SHA-256 on x86_64 and falls back to the `sha2` crate on other architectures. The ncitron fork ([commit `7ee7094`](https://github.com/ncitron/ethereum_hashing/commit/7ee70944ed4fabe301551da8c447e4f4ae5e6c35)) removes the `ring` dependency entirely and uses `sha2` unconditionally on all platforms.
126+
127+
**Why this is needed:** `ring` causes cross-compilation issues for non-x86_64 targets (WASM, RISC-V) and adds a heavyweight C dependency. Helios's dependency tree pulls in `ethereum_hashing`, and without this patch, the build requires `ring`'s C compilation toolchain. The `sha2` crate is pure Rust and compiles everywhere.
128+
129+
**Fork author trust:** ncitron is the top contributor to `a16z/helios`. This fork is effectively maintained by the Helios team.
130+
131+
**Upstream status:** The upstream `sigp/ethereum_hashing` added a `sha2` feature flag (post-`v0.8.0`, unreleased) that allows opting into `sha2` without `ring`. However, this is not yet in a tagged release. Once upstream publishes a release with the `sha2` feature, this patch can be replaced with:
132+
133+
```toml
134+
ethereum_hashing = { version = ">=0.9", default-features = false, features = ["sha2"] }
135+
```
136+
137+
and the `[patch.crates-io]` section can be removed.

‎README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -31,6 +31,7 @@ The desktop verifier ships with a CSP that restricts `connect-src` to Tauri IPC
3131

3232
## Architecture and runbooks
3333

34+
- Dependency audit: [`DEPENDENCIES.md`](DEPENDENCIES.md)
3435
- Docs index: [`docs/README.md`](docs/README.md)
3536
- Interpreter precedence contract: [`docs/architecture/interpretation-precedence.md`](docs/architecture/interpretation-precedence.md)
3637
- Verification source contract: [`docs/architecture/verification-source-contract.md`](docs/architecture/verification-source-contract.md)

‎apps/desktop/src-tauri/Cargo.toml‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,11 @@ tauri-plugin-dialog = "2"
1515
window-vibrancy = "0.6"
1616

1717
# Helios consensus verification (Phase 4)
18+
# Pinned to rev 582fda3 (2026-02-18) because it includes a16z/helios#776
19+
# (hex-encoded blockNumber/chainId in beacon API responses), which is not yet
20+
# in a tagged release (latest: 0.11.0, 2025-12-16). Migrate to a version/tag
21+
# pin once Helios publishes a release that includes this commit.
22+
# See DEPENDENCIES.md for full rationale.
1823
helios-consensus-core = { git = "https://github.com/a16z/helios", rev = "582fda319ed1ecb5fb82c71f4fa755a32e01031a", package = "helios-consensus-core" }
1924
alloy = { version = "1.0.3", default-features = false, features = ["consensus", "ssz"] }
2025
tree_hash = "0.12.1"
@@ -25,6 +30,13 @@ time = { version = "0.3", features = ["parsing"] }
2530
revm = { version = "34", default-features = false, features = ["std"] }
2631

2732
[patch.crates-io]
33+
# Fork by ncitron (top Helios contributor) removes the `ring` C dependency and
34+
# uses the pure-Rust `sha2` crate unconditionally. Required because Helios
35+
# pulls in ethereum_hashing, and `ring` causes cross-compilation issues.
36+
# Upstream sigp/ethereum_hashing has an unreleased `sha2` feature flag; once
37+
# that ships in a tagged release, replace this patch with:
38+
# ethereum_hashing = { version = ">=0.9", default-features = false, features = ["sha2"] }
39+
# See DEPENDENCIES.md for full rationale.
2840
ethereum_hashing = { git = "https://github.com/ncitron/ethereum_hashing", rev = "7ee70944ed4fabe301551da8c447e4f4ae5e6c35" }
2941

3042
[features]

0 commit comments

Comments
 (0)