Skip to content

Commit 1d28b3b

Browse files
eaceteacet
authored
quantum phase 4: lock parity with tests, fixtures, docs, and CI (#5)
<!-- Thank you for your Pull Request. Please provide a description above and review the requirements below. Bug fixes and new features should include tests. Contributors guide: https://github.com/foundry-rs/foundry/blob/HEAD/CONTRIBUTING.md The contributors guide includes instructions for running rustfmt and building the documentation. --> <!-- ** Please select "Allow edits from maintainers" in the PR Options ** --> ## Motivation <!-- Explain the context and why you're making that change. What is the problem you're trying to solve? In some cases there is not a problem and this can be thought of as being the motivation for your change. --> ## Solution <!-- Summarize the solution and provide any necessary context needed to understand the code change. --> ## PR Checklist - [ ] Added Tests - [ ] Added Documentation - [ ] Breaking changes
1 parent 5f1a14b commit 1d28b3b

19 files changed

Lines changed: 930 additions & 351 deletions

File tree

‎.github/workflows/ci-quantum.yml‎

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
1+
name: CI Quantum
2+
3+
permissions: {}
4+
5+
on:
6+
push:
7+
branches: [master]
8+
pull_request:
9+
workflow_dispatch:
10+
11+
concurrency:
12+
group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }}
13+
cancel-in-progress: true
14+
15+
env:
16+
CARGO_TERM_COLOR: always
17+
RUSTC_WRAPPER: "sccache"
18+
QUANTUM_FOUNDRY_BASE_COMMIT: "f1abb2ca347187bb6dea8c3881ca44ce50aab1e7"
19+
QUANTUM_HARNESS_COMMIT: "8f3612c60f9fa66ea3a09eab99a2e0802f373673"
20+
21+
jobs:
22+
quantum-check:
23+
runs-on: depot-ubuntu-latest
24+
timeout-minutes: 60
25+
permissions:
26+
contents: read
27+
steps:
28+
- uses: actions/checkout@v6
29+
with:
30+
persist-credentials: false
31+
- uses: dtolnay/rust-toolchain@e97e2d8cc328f1b50210efc529dca0028893a2d9 # master
32+
with:
33+
toolchain: nightly
34+
components: rustfmt, clippy
35+
36+
- uses: mozilla-actions/sccache-action@7d986dd989559c6ecdb630a3fd2557667be217ad # v0.0.9
37+
- uses: Swatinem/rust-cache@f13886b937689c021905a6b90929199931d60db1 # v2
38+
39+
- name: Format check
40+
run: cargo fmt --all --check
41+
42+
- name: Clippy
43+
run: cargo clippy --workspace --all-targets -- -D warnings
44+
45+
# Quantum-scoped package tests lock the adapter, envelope, and lifecycle
46+
# contracts. The broader `cargo test --workspace` target is intentionally
47+
# not gated in CI because it inherits upstream Foundry tests that hit
48+
# external networks (Etherscan, live mainnet RPC, flaky fork endpoints)
49+
# and fail in isolated CI environments regardless of this fork's changes.
50+
- name: Quantum package tests
51+
run: cargo test -p foundry-common -p foundry-primitives -p foundry-cli -p cast
52+
53+
# Targeted Quantum regression: pinned golden fixture and composite RLP envelope.
54+
# Multiple filters must follow `--` (cargo test accepts only a single
55+
# positional TESTNAME before `--`; libtest then applies all post-`--`
56+
# filters as an OR under `--exact`).
57+
- name: Quantum fixture regression
58+
run: |
59+
cargo test -p foundry-common --lib -- --exact \
60+
transactions::quantum::tests::generated_fixture_matches_checked_in_phase0_example \
61+
transactions::quantum::tests::detached_p256_cosigner_is_attached_to_composite_signature

‎.github/workflows/ci-tempo.yml‎

Lines changed: 0 additions & 138 deletions
This file was deleted.

‎Cargo.lock‎

Lines changed: 4 additions & 4 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎README.md‎

Lines changed: 99 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,102 @@
1+
<br>
2+
<br>
3+
4+
<p align="center">
5+
<a href="https://quantum.systems">
6+
<picture>
7+
<source media="(prefers-color-scheme: dark)" srcset="https://quantum.systems/images/logo-white.svg">
8+
<img alt="tempo combomark" src="https://quantum.systems/images/logo-white.svg" width="auto" height="120">
9+
</picture>
10+
</a>
11+
</p>
12+
13+
<br>
14+
<br>
15+
16+
# Quantum Foundry
17+
18+
Quantum is a post-quantum-ready EVM execution environment with a dedicated native transaction type (`0x7A`), explicit account lanes, and an ML-DSA-44 primary signer with optional detached classical cosigners.
19+
20+
`Quantum Foundry` is a custom fork of [Foundry](https://github.com/foundry-rs/foundry) that integrates Quantum's native envelope, KeyVault lifecycle UX, and detached-cosigner contract directly into the familiar Foundry developer workflow.
21+
22+
This fork is a drop-in replacement for upstream Foundry while Quantum-specific features are being stabilized; it tracks Foundry commit `f1abb2ca347187bb6dea8c3881ca44ce50aab1e7` and the Quantum harness commit `8f3612c60f9fa66ea3a09eab99a2e0802f373673`. See [`docs/dev/quantum-phase0-implementation-note.md`](./docs/dev/quantum-phase0-implementation-note.md) for the frozen RPC, signer, and ABI contract.
23+
24+
## Installation
25+
26+
```sh
27+
curl -L https://raw.githubusercontent.com/multivmlabs/quantum-foundry/HEAD/foundryup/install | bash
28+
foundryup --network quantum
29+
```
30+
31+
This installs the Quantum-enabled `forge`, `cast`, `anvil`, and `chisel` from this fork's GitHub Releases into `~/.foundry-quantum/bin/`. The separate directory means quantum-foundry coexists with an existing upstream Foundry install at `~/.foundry/` — neither installer overwrites the other's binaries. If both are on your `PATH`, the one listed earlier wins for commands like `forge` and `cast`.
32+
33+
<details>
34+
<summary>Building from source (contributors and unsupported platforms)</summary>
35+
36+
```sh
37+
cargo build --release -p forge -p cast -p anvil -p chisel
38+
```
39+
40+
The `target/release` binaries are drop-in replacements for upstream `forge`, `cast`, `anvil`, and `chisel`.
41+
42+
</details>
43+
44+
## Devnet
45+
46+
Quantum's public devnet is available for early testing. **Note: the devnet is unstable — state may be wiped, chain ID may change, and downtime should be expected. A public testnet is targeted for mid-2026.**
47+
48+
| Property | Value |
49+
| ------------------ | ------------------------------------- |
50+
| **Network Name** | Quantum Devnet |
51+
| **Chain ID** | `1337` |
52+
| **HTTP URL** | `https://devnet2.rpc.quantum.systems` |
53+
| **Block Explorer** | `https://quantumscan.org/` |
54+
55+
Example:
56+
57+
```sh
58+
cast block-number --rpc-url https://devnet2.rpc.quantum.systems
59+
```
60+
61+
## Changeset
62+
63+
Key Quantum extensions on top of upstream Foundry:
64+
65+
- In `cast send`:
66+
- `--quantum`: opt into the explicit Quantum adapter path (selection is explicit in v1, not inferred from chain ID).
67+
- `--quantum.sender <ADDRESS>`: explicit Quantum account-lane address. Quantum writes never auto-derive the sender from the signing key.
68+
- `--quantum.key-id <KEY_ID>`: account-lane key ID; defaults to `0` for ordinary v1 flows.
69+
- `--quantum.primary-seed-file <PATH>`: canonical v1 ML-DSA-44 signer seed (single 32-byte hex seed, with or without `0x`).
70+
- `--quantum.cosigner-artifact <PATH>`: optional detached v1 cosigner artifact JSON; schemes `p256` and `ecdsa` are supported and the artifact's `signing_hash` must match the fork-computed Quantum signing hash byte-for-byte.
71+
- KeyVault lifecycle selectors (`bootstrapKey`, `addKey`, `removeKey`, `updateKeyAuth`) are rejected by the `cast send` pre-build guard and must be submitted through `cast quantum` instead.
72+
73+
- In `cast quantum` (new subcommand group for KeyVault lifecycle UX):
74+
- `cast quantum bootstrap`: primary-only `bootstrapKey()` through the shared `0x7A` signing pipeline.
75+
- `cast quantum add-key`: `addKey(...)` with `--auth-key-id` (signer lane) distinct from `--target-key-id` (entry being added) so the two lanes cannot be confused.
76+
- `cast quantum remove-key`: `removeKey(uint32)`.
77+
- `cast quantum update-key-auth`: `updateKeyAuth(...)` with the same auth-lane / target-lane separation.
78+
- All lifecycle writes auto-apply the fixed `QUANTUM_LIFECYCLE_GAS_FLOOR` (2,100,000) because validator-published transient state cannot be reproduced by `eth_estimateGas`.
79+
80+
- In `cast call`:
81+
- Fails closed on KeyVault lifecycle selectors with the frozen `QUANTUM_CALL_LIFECYCLE_REJECTION_MESSAGE`, preserving ordinary read paths on standard RPC simulation.
82+
83+
- In `forge create`:
84+
- `--quantum` and the `--quantum.*` flags route CREATE through the shared Quantum adapter with the same explicit sender / key-id / seed / cosigner contract as `cast send`.
85+
86+
- In `forge script`:
87+
- Scripted broadcast routes through the shared Quantum adapter for supported write shapes and fails closed on unsupported Quantum script shapes with a stable rejection message.
88+
89+
- Additionally:
90+
- A shared `QuantumWriteRequestV1` write contract with fail-closed v1 validation: `nonce_key` must be `0`, multi-call bundles are rejected, and lifecycle-selector misuse is caught before signing.
91+
- Detached cosigner artifact v1 (`version = 1`, `scheme`, `signing_hash`, `public_key`, `signature`) with composite-signature RLP layout using scheme bytes `0x01` (ML-DSA), `0x02` (P256), `0x03` (ECDSA).
92+
- KeyVault lifecycle calldata builders derived from a shared `sol!` interface whose selectors are asserted byte-for-byte against the Phase 0 frozen constants.
93+
- A pinned golden fixture (`testdata/fixtures/quantum/phase0/raw-send-primary.json`) that locks the raw `0x7A` envelope bytes end-to-end.
94+
95+
See [`docs/dev/quantum-adapter-touchpoints.md`](./docs/dev/quantum-adapter-touchpoints.md) for the full manifest of Quantum-modified files.
96+
97+
<br>
98+
<br>
99+
1100
<div align="center">
2101
<img src=".github/assets/banner.png" alt="Foundry banner" />
3102

0 commit comments

Comments
 (0)