https://github.com/shrec/ultrafastsecp256k1
Ultra high-performance secp256k1 ECC engine | Python, Node.js, Rust, Go, C#, Swift, Java bindings | CUDA, Metal, OpenCL GPU | ECDSA, Schnorr, FROST, MuSig2, BIP-352 | 15+ platforms
https://github.com/shrec/ultrafastsecp256k1
android arm64 bitcoin constant-time cryptography cuda ecdsa embedded ethereum ffi gpu-cryptography ios nodejs opencl python riscv rust schnorr-signatures secp256k1 webassembly
Last synced: 9 days ago
JSON representation
Ultra high-performance secp256k1 ECC engine | Python, Node.js, Rust, Go, C#, Swift, Java bindings | CUDA, Metal, OpenCL GPU | ECDSA, Schnorr, FROST, MuSig2, BIP-352 | 15+ platforms
- Host: GitHub
- URL: https://github.com/shrec/ultrafastsecp256k1
- Owner: shrec
- License: mit
- Created: 2026-02-02T13:29:44.000Z (4 months ago)
- Default Branch: main
- Last Pushed: 2026-05-31T15:13:30.000Z (12 days ago)
- Last Synced: 2026-05-31T15:23:43.498Z (12 days ago)
- Topics: android, arm64, bitcoin, constant-time, cryptography, cuda, ecdsa, embedded, ethereum, ffi, gpu-cryptography, ios, nodejs, opencl, python, riscv, rust, schnorr-signatures, secp256k1, webassembly
- Language: C++
- Homepage: https://shrec.github.io/UltrafastSecp256k1/
- Size: 460 MB
- Stars: 39
- Watchers: 2
- Forks: 16
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Audit: audit/AUDIT_TEST_PLAN.md
- Citation: CITATION.cff
- Codeowners: .github/CODEOWNERS
- Security: SECURITY.md
- Governance: docs/GOVERNANCE.md
- Roadmap: docs/ROADMAP.md
- Zenodo: .zenodo.json
Awesome Lists containing this project
README
# UltrafastSecp256k1
UltrafastSecp256k1 is a high-performance, multi-backend secp256k1 engine with reproducible audit evidence, compatibility shims, and profile-based review scopes.
It is not a trust request. It is a verification package.
[](https://github.com/shrec/UltrafastSecp256k1/actions/workflows/gate.yml)
[](https://github.com/shrec/UltrafastSecp256k1/actions/workflows/ci.yml)
[](https://github.com/shrec/UltrafastSecp256k1/actions/workflows/security-audit.yml)
[](https://github.com/shrec/UltrafastSecp256k1/actions/workflows/caas.yml)
[](https://sonarcloud.io/summary/new_code?id=shrec_UltrafastSecp256k1)
[](https://github.com/shrec/UltrafastSecp256k1/actions/workflows/codeql.yml)
[](https://securityscorecards.dev/viewer/?uri=github.com/shrec/UltrafastSecp256k1)
[](https://doi.org/10.5281/zenodo.19685027)
> All CI badges track the `dev` branch — the active development branch where all work happens. Releases are tagged on `main` only when explicitly authorized by the repository owner.
---
## What this repository contains
- **Core engine** — CPU/GPU/embedded secp256k1 implementation (`src/cpu`, `src/cuda`, `src/opencl`, `src/metal`).
- **Compatibility shims** — opt-in API-compatible paths for existing projects (`compat/libsecp256k1_shim`, `compat/libsecp256k1_bchn_shim`; not API-identical — see FAQ §drop-in for migration notes).
- **Bindings/FFI** — language integration surfaces (`bindings/`): C, Python, Node.js, Go, Swift, Rust, Java, Dart, C#, WASM, Android.
- **CAAS** — continuous audit and evidence system (`audit/`, `ci/`); not runtime code.
- **Reviewer docs** — scoped evidence, known limitations, replay commands (`docs/`).
> **Bitcoin Core PR candidate — scope:** the proposed Bitcoin Core integration is the
> **CPU ECDSA / Schnorr (BIP-340) verify + sign backend only** — a compile-time *secondary*
> backend selected behind the existing libsecp256k1, **not a replacement**. Explicitly
> **out of scope** for that PR (and reviewed/used separately): the GPU backends
> (CUDA / Metal / OpenCL), WASM, embedded (ESP32/STM32) targets, the non-C++ bindings, and
> the protocol extensions (FROST, MuSig2, adaptor signatures, ECIES, BIP-352). Those are
> real features of the wider engine but are not part of the Core backend candidate.
---
## For Bitcoin Core Reviewers
**Scope:** CPU secp256k1 backend only — ECDSA/Schnorr sign/verify, RFC 6979 nonce, DER parsing, constant-time signing, libsecp256k1-compatible shim. GPU, FFI, bindings, WASM, ZK, multi-coin, and wallet tooling are out of scope for this evaluation.
**NOT A REPLACEMENT.** This PR adds an opt-in compile-time alternative backend (`-DSECP256K1_BACKEND=ultrafast`, default: `bundled`). When bundled, the build is byte-for-byte identical to today. The existing `src/secp256k1/` path and all existing behavior is unchanged.
> **No external third-party security audit has been performed.** All audit evidence is self-generated and independently reproducible via CAAS. See [SECURITY.md](SECURITY.md) §Audit Status.
> **Audit methodology:** CAAS (Continuous Automated Assurance System) — a multi-layer automated audit framework: LLVM ct-verif, Valgrind taint analysis, dudect statistical timing, 419-module unified runner with 270 exploit PoC tests.
**Reproduce from patch (primary — stable):**
```bash
# Point UFSECP at an existing UltrafastSecp256k1 clone (absolute path).
# Required because the patch sits inside docs/ of THIS repo, and on a
# fresh Bitcoin Core clone src/ultrafast_secp256k1 does not exist yet —
# `git -C src/ultrafast_secp256k1 ...` would fail before submodule init.
UFSECP=/absolute/path/to/UltrafastSecp256k1
git clone https://github.com/bitcoin/bitcoin && cd bitcoin
git apply "$UFSECP/docs/INTEGRATION_PATCH.patch"
git submodule update --init src/ultrafast_secp256k1
cmake --preset ultrafast-bench # Release + LTO — required for accurate ConnectBlock numbers
cmake --build out/build-ultrafast-lto -j$(nproc)
ctest --test-dir out/build-ultrafast-lto -j$(nproc)
```
**Reproduce from fork (alternative — may be rebased):**
```bash
# Fork branch may be rebased; prefer the patch path above for reproducibility.
git clone https://github.com/shrec/bitcoin -b feature/ultrafast-secp256k1-backend && cd bitcoin
git submodule update --init src/ultrafast_secp256k1
cmake --preset ultrafast-bench # Release + LTO
cmake --build out/build-ultrafast-lto -j$(nproc)
ctest --test-dir out/build-ultrafast-lto -j$(nproc)
```
**CAAS evidence entry point:**
```bash
python3 ci/caas_runner.py --profile bitcoin-core-backend --json -o btc.json
```
→ [`docs/CAAS_REVIEWER_QUICKSTART.md`](docs/CAAS_REVIEWER_QUICKSTART.md) — start here
→ [`docs/BITCOIN_CORE_BACKEND_EVIDENCE.md`](docs/BITCOIN_CORE_BACKEND_EVIDENCE.md) — evidence package
→ [`docs/DER_PARITY_MATRIX.md`](docs/DER_PARITY_MATRIX.md) — DER/parser parity
**CT signing (CT-vs-CT, production-equivalent, GCC 14.2.0, 2026-05-30):** **~1.33× ECDSA · ~1.26× Schnorr** vs libsecp256k1 (turbo lock CONFIRMED: intel_pstate/no_turbo=1, governor=performance, taskset -c 0 nice -20). Canonical data: [`docs/bench_unified_2026-05-30_gcc14_x86-64.json`](docs/bench_unified_2026-05-30_gcc14_x86-64.json). Full compiler breakdown: [docs/BITCOIN_CORE_BACKEND_EVIDENCE.md §CT Signing](docs/BITCOIN_CORE_BACKEND_EVIDENCE.md).
> **ConnectBlock (primary block-validation workload):** within ±1.5% of libsecp256k1 depending on build configuration.
> - With Release+LTO (GCC 14.2.0, **required for any positive result — without LTO the result is negative**): **+0.9–1.5%** across ConnectBlock aggregate profiles (AllEcdsa, AllSchnorr, Mixed)
> - VerifyScriptP2WPKH individual validation: **parity (Ultra ≤0.4% slower, within noise margin)**
> - Without LTO: **−0.5–1.0%** on all profiles. The earlier ~1.1% deficit was reduced after two
> targeted fixes (PERF-002 redundant y²=x³+7 curve-check removal in commit `40697447`, and the
> DER parser fast-path replacing the previous Scalar-construct round-trip); residual ~0.5–1.0%
> no-LTO deficit is consistent with the size delta of the inlined hot-path
> (**2,310 KB Ultra `.text` vs 1,261 KB libsecp256k1 `.text`, 1.83× — measured 2026-05-22**;
> see [`docs/SHIM_FOOTPRINT_COMPARISON.md`](docs/SHIM_FOOTPRINT_COMPARISON.md)).
> With LTO the cross-TU inliner co-optimises both sides and the deficit flips to a small
> advantage. The `bitcoin-core` deployment profile (`cmake --preset bitcoin-core`) strips
> FROST/ZK/ECIES/BIP-352/Adaptor/Wallet/Pippenger to save **359 KB `.text`** vs the full
> profile; see [`ci/profiles.json`](ci/profiles.json) for the full module set.
> - Taproot key-path signing (wallet, not ConnectBlock): +10% faster (SignTransactionSchnorr)
> - Taproot script-path signing (wallet, not ConnectBlock): +35% faster (SignSchnorrWithMerkleRoot)
> - Canonical data: [`docs/BITCOIN_CORE_BENCH_RESULTS.json`](docs/BITCOIN_CORE_BENCH_RESULTS.json) (measured 2026-05-12, commit `48e7c02f`).
> - For reproducibility, use the commit SHA in `docs/BITCOIN_CORE_BENCH_RESULTS.json` field `"backend_commit"` — do not hardcode a SHA in prose.
---
## Review scope matters
The full repository is multi-platform and multi-product.
The Bitcoin Core evaluation profile is intentionally narrow:
**CPU secp256k1 operations · libsecp256k1-compatible shim · parser/DER parity · nonce/RFC 6979 behavior · constant-time signing evidence · Core test and benchmark evidence.**
GPU, FFI, bindings, WASM, ZK, wallet tooling, and alternate node shims are separate profiles.
→ Scoped audit entry point: [`docs/CAAS_REVIEWER_QUICKSTART.md`](docs/CAAS_REVIEWER_QUICKSTART.md)
→ Profile definitions: [`docs/PRODUCT_PROFILES.md`](docs/PRODUCT_PROFILES.md)
→ Security claims: [`docs/SECURITY_CLAIMS.md`](docs/SECURITY_CLAIMS.md)
---
## Quick Start
**Build from source**
```bash
git clone https://github.com/shrec/UltrafastSecp256k1.git && cd UltrafastSecp256k1
python3 ci/configure_build.py release
cmake --build out/release -j
./out/release/selftest # Expected: "ALL TESTS PASSED"
```
**Package install**
See [docs/BUILDING.md](docs/BUILDING.md) for full install instructions.
Build from source (all platforms):
```bash
git clone https://github.com/shrec/UltrafastSecp256k1 && cd UltrafastSecp256k1
cmake -S . -B out/release -DCMAKE_BUILD_TYPE=Release && cmake --build out/release -j$(nproc)
```
→ [Full build guide](docs/BUILDING.md) · [API reference](docs/API_REFERENCE.md) · [Platform support](docs/CROSS_PLATFORM_TEST_MATRIX.md)
---
## Where to Start
**New here? Start with one of these:**
| Goal | Entry point |
|---|---|
| Independent reviewer / auditor | [docs/AUDITOR_QUICKSTART.md](docs/AUDITOR_QUICKSTART.md) |
| Bitcoin Core evaluation | [docs/CAAS_REVIEWER_QUICKSTART.md](docs/CAAS_REVIEWER_QUICKSTART.md) |
| Try to break the system | [docs/ATTACK_GUIDE.md](docs/ATTACK_GUIDE.md) |
| Understand the security guarantees | [docs/SECURITY_CLAIMS.md](docs/SECURITY_CLAIMS.md) · [docs/AUDIT_TRACEABILITY.md](docs/AUDIT_TRACEABILITY.md) |
| Replay the audit evidence locally | [docs/CAAS_PROTOCOL.md](docs/CAAS_PROTOCOL.md) |
| Integrate into your project | [docs/API_REFERENCE.md](docs/API_REFERENCE.md) · [docs/BUILDING.md](docs/BUILDING.md) |
**Full navigation:**
| If you want to… | Go here |
|---|---|
| Run the audit | [docs/AUDIT_GUIDE.md](docs/AUDIT_GUIDE.md) |
| Try to break the system | [docs/ATTACK_GUIDE.md](docs/ATTACK_GUIDE.md) |
| Understand the guarantees | [docs/AUDIT_TRACEABILITY.md](docs/AUDIT_TRACEABILITY.md) |
| Audit philosophy & design rationale | [docs/AUDIT_PHILOSOPHY.md](docs/AUDIT_PHILOSOPHY.md) |
| Audit methodology specification (CAAS) | [docs/AUDIT_STANDARD.md](docs/AUDIT_STANDARD.md) |
| Independent reviewer quick start | [docs/AUDITOR_QUICKSTART.md](docs/AUDITOR_QUICKSTART.md) |
| Historical audit report (v3.9.0 baseline — ⚠ not current state) | [AUDIT_REPORT.md](docs/AUDIT_REPORT.md) |
| Live audit dashboard | [docs/AUDIT_DASHBOARD.md](docs/AUDIT_DASHBOARD.md) |
| Exploit PoC test catalog | [docs/EXPLOIT_TEST_CATALOG.md](docs/EXPLOIT_TEST_CATALOG.md) |
| Exploit coverage map | [docs/EXPLOIT_COVERAGE_MAP.md](docs/EXPLOIT_COVERAGE_MAP.md) |
| ECDSA edge-case coverage | [docs/ECDSA_EDGE_CASE_COVERAGE.md](docs/ECDSA_EDGE_CASE_COVERAGE.md) |
| Interop matrix (cross-implementation) | [docs/INTEROP_MATRIX.md](docs/INTEROP_MATRIX.md) |
| Threat model | [docs/THREAT_MODEL.md](docs/THREAT_MODEL.md) |
| CAAS protocol (continuous audit) | [docs/CAAS_PROTOCOL.md](docs/CAAS_PROTOCOL.md) |
| Multi-CI reproducible builds | [docs/MULTI_CI_REPRODUCIBLE_BUILD.md](docs/MULTI_CI_REPRODUCIBLE_BUILD.md) |
| Supply-chain local parity | [docs/SUPPLY_CHAIN_LOCAL_PARITY.md](docs/SUPPLY_CHAIN_LOCAL_PARITY.md) |
| Hardware side-channel methodology | [docs/HARDWARE_SIDE_CHANNEL_METHODOLOGY.md](docs/HARDWARE_SIDE_CHANNEL_METHODOLOGY.md) |
| Compliance stance | [docs/COMPLIANCE_STANCE.md](docs/COMPLIANCE_STANCE.md) |
| Security autonomy program | [docs/SECURITY_AUTONOMY_PLAN.md](docs/SECURITY_AUTONOMY_PLAN.md) |
| Research monitor | [docs/RESEARCH_MONITOR.md](docs/RESEARCH_MONITOR.md) |
| ⚖️ Reviewer role prompts | [docs/REVIEWER_PROMPTS/README.md](docs/REVIEWER_PROMPTS/README.md) |
| Backend assurance matrix | [docs/BACKEND_ASSURANCE_MATRIX.md](docs/BACKEND_ASSURANCE_MATRIX.md) |
| CI gating policy | [docs/CI_GATING_POLICY.md](docs/CI_GATING_POLICY.md) |
| ABI layer routing matrix | [docs/LAYER_ROUTING_MATRIX.md](docs/LAYER_ROUTING_MATRIX.md) |
| Build guide | [docs/BUILDING.md](docs/BUILDING.md) |
| C ABI / FFI reference | [docs/API_REFERENCE.md](docs/API_REFERENCE.md) |
| Community benchmarks | [docs/COMMUNITY_BENCHMARKS.md](docs/COMMUNITY_BENCHMARKS.md) |
| Architecture overview | [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) |
| Security claims & contracts | [docs/SECURITY_CLAIMS.md](docs/SECURITY_CLAIMS.md) |
| Secret lifecycle (zeroization, CT) | [docs/SECRET_LIFECYCLE.md](docs/SECRET_LIFECYCLE.md) |
| Cryptographic invariants | [docs/CRYPTO_INVARIANTS.md](docs/CRYPTO_INVARIANTS.md) |
| Thread-safety guarantees | [docs/THREAD_SAFETY.md](docs/THREAD_SAFETY.md) |
| Safe defaults | [docs/SAFE_DEFAULTS.md](docs/SAFE_DEFAULTS.md) |
| Differential testing | [docs/DIFFERENTIAL_TESTING.md](docs/DIFFERENTIAL_TESTING.md) |
| Reproducible builds | [docs/REPRODUCIBLE_BUILDS.md](docs/REPRODUCIBLE_BUILDS.md) |
| Incident response | [docs/INCIDENT_RESPONSE.md](docs/INCIDENT_RESPONSE.md) |
| Install packages | [Installation](#installation) |
| Why this library? | [WHY_ULTRAFASTSECP256K1.md](docs/WHY_ULTRAFASTSECP256K1.md) |
| Cite this work | [CITATION.cff](CITATION.cff) |
| Production adopters | [docs/ADOPTION.md](docs/ADOPTION.md) |
| Funding & grant programmes | [docs/FUNDING_TARGETS.md](docs/FUNDING_TARGETS.md) |
| Sponsor | [github.com/sponsors/shrec](https://github.com/sponsors/shrec) |
> **Claim map:** [docs/ASSURANCE_LEDGER.md](docs/ASSURANCE_LEDGER.md) · **Security policy:** [SECURITY.md](SECURITY.md) · **Discord:** [discord.gg/E4BK8SeMYU](https://discord.gg/E4BK8SeMYU)
---
## Review culture
I welcome negative review.
If you find a real issue, please open it with a reproducer or a clear test case.
Valid findings are fixed, credited, and turned into permanent regression coverage.
The goal is not to defend the code.
The goal is to make the system stronger.
→ Security policy: [SECURITY.md](SECURITY.md) · Exploit catalog: [docs/EXPLOIT_TEST_CATALOG.md](docs/EXPLOIT_TEST_CATALOG.md) · Residual risks: [docs/RESIDUAL_RISK_REGISTER.md](docs/RESIDUAL_RISK_REGISTER.md)
---
## Cite this work
If you use UltrafastSecp256k1 in academic work, please cite:
- **Citation metadata** — [CITATION.cff](CITATION.cff) (also exposed via GitHub's "Cite this repository" button)
- **Zenodo metadata** — [.zenodo.json](.zenodo.json)
- **DOI (Zenodo release)** — [10.5281/zenodo.19685027](https://doi.org/10.5281/zenodo.19685027)
[](https://doi.org/10.5281/zenodo.19685027)
---
## Why This Exists
Traditional model: `code → audit PDF → trust`
This project: `code → test → execution → evidence → continuous verification`
We do not rely on trust. We provide reproducible evidence.
- Every exploit attempt becomes a permanent regression test
- Every commit runs ≈600K explicitly itemized field/scalar/point/CT assertions (plus full-suite KAT/differential/fuzz checks, not individually counted) across 149 non-exploit audit modules and 270 exploit PoCs ( 419 modules total; count via `python3 ci/sync_module_count.py`; canonical data: `docs/canonical_data.json`)
- Every claim maps to a test in [docs/AUDIT_TRACEABILITY.md](docs/AUDIT_TRACEABILITY.md)
- Every performance number has pinned compiler/driver/toolkit versions and raw logs
> If a claim cannot be traced to a test, it is not valid.
For the full breakdown of the audit culture, CI/CD pipeline, formal verification layers, and supply-chain hardening, see [WHY_ULTRAFASTSECP256K1.md](docs/WHY_ULTRAFASTSECP256K1.md).
---
## The Audit Model
Most libraries ship fast code and trust it's correct.
This library ships fast code — then systematically tries to break it, on every commit, permanently.
- New CVE published → PoC written → CI gate added → runs forever
- New ePrint attack → evaluated within 1 day → permanent regression test
- Contributor finds exploit → pull request → built into the system
[How it works](#engineering-quality--self-audit-culture) · [The standard](docs/AUDIT_STANDARD.md)
---
## Performance Snapshot
Benchmark numbers and historical milestones are maintained in [`docs/BENCHMARKS.md`](docs/BENCHMARKS.md) with pinned compiler/driver/toolkit versions, raw logs, and methodology notes.
> All performance claims in this README link to that document. Do not rely on inline numbers without checking the corresponding benchmark entry for hardware, batch size, and measurement conditions.
>
> Canonical raw data (GCC 14.2.0, 2026-05-30): [`docs/bench_unified_2026-05-30_gcc14_x86-64.json`](docs/bench_unified_2026-05-30_gcc14_x86-64.json)
## Why UltrafastSecp256k1? — Detail
> TL;DR is above. This section covers what differentiates this library in depth.
- **Continuous adversarial audit system** -- every exploit attempt becomes a permanent regression test; ≈600K explicitly itemized field/scalar/point/CT assertions (plus full-suite KAT/differential/fuzz checks, not individually counted) per release evidence run, 270 exploit PoCs runner modules in `unified_audit_runner.cpp` (some source files contain multiple registered test functions; all wired, verified by `ci/check_exploit_wiring.py`) across 200+ attack vectors, a block-based PR/push gate, release CAAS gate, and manual deep-assurance workflows — security hardens through executable evidence, not snapshot PDFs ([→ how it works](#engineering-quality--self-audit-culture))
- **High-performance CPU secp256k1 engine** -- optimized generator multiply, scalar multiply, hashing, and serialization pipelines across x86-64, ARM64, RISC-V, and embedded targets ([see bench_unified ratio table](docs/BENCHMARKS.md))
- **Built for modern secp256k1 workloads** -- signing, verification, wallet derivation, threshold protocols, adaptor signatures, ZK primitives, address generation, and large-scale public-key pipelines in one engine
- **Dual-layer security** -- variable-time FAST path for throughput, constant-time CT path for secret-key operations
- **Minimal dependencies** -- No runtime library dependencies for the CPU-only build (no Boost, no OpenSSL). GPU builds require CUDA toolkit, OpenCL runtime, or Metal SDK. Build requires CMake 3.18+ and a C++17 compiler (GCC 10+, Clang 12+, MSVC 2019+, arm-none-eabi, Emscripten)
- **12+ platforms** -- x86-64, ARM64, RISC-V, WASM (experimental — CT evidence incomplete), iOS, Android, ESP32, STM32, CUDA, Metal, OpenCL, plus an early-development ROCm/HIP compatibility path slated for hardware-backed validation
> **The following capabilities are out of scope for the Bitcoin Core CPU backend evaluation profile:**
- **Differentiated GPU secp256k1 surface** -- CUDA, OpenCL, and Metal all implement the stable 16-op GPU C ABI, while CUDA also carries the highest-throughput signing and verification kernels plus **GPU FROST partial verification** ([reproducible benchmark suite and raw logs](docs/BENCHMARKS.md))
- **BIP-352 Silent Payments GPU pipeline** -- the full 7-stage GPU pipeline (k×P → hash → k×G → add → match) on CUDA; throughput and CPU comparison: [GPU bench](docs/BENCHMARKS.md), [standalone CPU benchmark by @craigraw](https://github.com/craigraw/bench_bip352)
- **Field-tested GPU pipeline** -- the CUDA engine has been stress-tested in live high-throughput workflows over long-running sessions and very large point volumes, not only in short synthetic benchmarks
- **Known production adoption** -- publicly disclosed production use includes [SparrowWallet Frigate](https://github.com/sparrowwallet/frigate), with permission to publish the adoption note from Craig Raw (adoption evidence as of 2026-03-29 — verify against current Frigate README for latest status)
> **Benchmark reproducibility:** All numbers come from pinned compiler/driver/toolkit versions with exact commands and raw logs. See [`docs/BENCHMARKS.md`](docs/BENCHMARKS.md) (methodology) and the [live dashboard](https://shrec.github.io/UltrafastSecp256k1/dev/bench/).
> **Why this library, in depth?** See [WHY_ULTRAFASTSECP256K1.md](docs/WHY_ULTRAFASTSECP256K1.md) for a full breakdown of the audit culture, block-based CI/CD pipeline, graph-assisted review model, formal verification layers, and supply-chain hardening that back these claims.
> **Evidence replay prep:** Run `bash ci/external_audit_prep.sh` to produce a reproducible reviewer-facing bundle with preflight outputs, assurance export, traceability artifacts, and an optional full evidence package.
> **Claim map:** Top-level trust claims are keyed in [docs/ASSURANCE_LEDGER.md](docs/ASSURANCE_LEDGER.md): CPU CT routing `A-001`, stable GPU ABI `A-002`, cross-backend GPU parity `A-003`, benchmark reproducibility `A-004`, exploit-audit surface `A-005`, graph-assisted review `A-006`, open self-audit transparency `A-007`, and ROCm/HIP status discipline `A-008`.
**Quick links:** [Discord](https://discord.gg/E4BK8SeMYU) * [Benchmarks](docs/BENCHMARKS.md) * [Community Benchmarks](docs/COMMUNITY_BENCHMARKS.md) * [Adopters](docs/ADOPTION.md) * [Build Guide](docs/BUILDING.md) * [API Reference](docs/API_REFERENCE.md) * [Binding Usage Standard](docs/BINDINGS_USAGE_STANDARD.md) * [Security Policy](SECURITY.md) * [Threat Model](docs/THREAT_MODEL.md) * [Assurance Ledger](docs/ASSURANCE_LEDGER.md) * [AI Audit Protocol](docs/AI_AUDIT_PROTOCOL.md) * [Audit Standard (CAAS)](docs/AUDIT_STANDARD.md) * [**Why This Library?**](docs/WHY_ULTRAFASTSECP256K1.md) * [Porting Guide](docs/PORTING.md) * [**Sponsor**](https://github.com/sponsors/shrec)
### Real-world Adoption
UltrafastSecp256k1 is used by [Sparrow Wallet's Frigate](https://github.com/sparrowwallet/frigate).
Frigate 1.4.0 switched its DuckDB extension to `ufsecp.duckdb_extension` using UltrafastSecp256k1, and its README documents a custom DuckDB extension wrapping UltrafastSecp256k1 for `ufsecp_scan(...)`-based Silent Payments scanning with CUDA, OpenCL and Metal backend support. *(as of Frigate 1.4.0, 2026-03-29 — verify against current Frigate README for latest status)*
See: [Frigate 1.4.0 release](https://github.com/sparrowwallet/frigate/releases/tag/1.4.0) · [Frigate README](https://github.com/sparrowwallet/frigate/blob/master/README.md) · [Details →](docs/ADOPTION.md)
Package traction *(snapshot 2026-03-29 — see linked package pages for current figures)*: [`ufsecp`](https://www.npmjs.com/package/ufsecp) 1,192 npm downloads/30d · [`react-native-ufsecp`](https://www.npmjs.com/package/react-native-ufsecp) 1,295/30d · [`Ufsecp`](https://www.nuget.org/packages/Ufsecp) 1,491 NuGet total. *(See [docs/ADOPTION.md](docs/ADOPTION.md) for full adoption evidence.)*
Full adopter list: [ADOPTERS.md](docs/ADOPTERS.md)
---
[](https://github.com/shrec/UltrafastSecp256k1/stargazers)
[](https://github.com/shrec/UltrafastSecp256k1/network/members)
[](https://github.com/shrec/UltrafastSecp256k1/actions/workflows/gate.yml)
[](https://github.com/shrec/UltrafastSecp256k1/actions/workflows/research-monitor.yml)
[](https://github.com/shrec/UltrafastSecp256k1/releases/latest)
[](https://opensource.org/licenses/MIT)
[](https://en.cppreference.com/w/cpp/17)
[](https://scorecard.dev/viewer/?uri=github.com/shrec/UltrafastSecp256k1)
[](https://www.bestpractices.dev/projects/12011)
[](https://sonarcloud.io/summary/overall?id=shrec_UltrafastSecp256k1)
[](https://discord.gg/E4BK8SeMYU)
**Supported Blockchains (secp256k1-based):**
[](https://bitcoin.org)
[](https://ethereum.org)
[](https://litecoin.org)
[](https://dogecoin.com)
[](https://bitcoincash.org)
[](https://z.cash)
[](https://dash.org)
[](https://www.bnbchain.org)
[](https://polygon.technology)
[](https://avax.network)
[](https://arbitrum.io)
[](https://optimism.io)
[](#secp256k1-supported-coins-27-blockchains)
**GPU & Platform Support:**
[](https://developer.nvidia.com/cuda-toolkit)
[](https://www.khronos.org/opencl/)
[](src/metal/)
[](src/metal/)
[](src/cuda/README.md)
[](bindings/wasm/)
[](https://developer.android.com/ndk)
[](https://riscv.org/)
[](bindings/android/)
[](cmake/ios.toolchain.cmake)
[](https://www.espressif.com/en/products/socs/esp32-s3)
[](https://www.espressif.com/en/products/socs/esp32)
[](https://www.espressif.com/en/products/socs/esp32-c6)
[](https://www.espressif.com/en/products/socs/esp32-p4)
[](https://www.st.com/en/microcontrollers-microprocessors/stm32f103ze.html)
---
## Highlights
- **BIP-352 GPU pipeline** -- full silent payment scanning pipeline on CUDA; benchmark and CPU comparison in [docs/BENCHMARKS.md](docs/BENCHMARKS.md)
- **GPU-accelerated secp256k1** -- high-throughput CUDA verification kernels, batch ECDH, BIP-352 scanning, and BIP-324 encryption on CUDA/OpenCL/Metal; CT-sensitive signing always routes through the CPU CT layer; GPU operations that handle secret material (ECDH, BIP-352, BIP-324) require a trusted single-tenant environment (see [GPU Security Model](docs/BACKEND_ASSURANCE_MATRIX.md))
- **GPU C ABI (`ufsecp_gpu`)** -- stable 16-op FFI for GPU batch ops across CUDA, OpenCL, and Metal, with full backend parity on the public surface
- **Zero-Knowledge cryptographic layer** -- Pedersen commitments, DLEQ proofs, Bulletproof range proofs, Ethereum-compatible Keccak-256
- **Batch operations** -- all-affine Pippenger with touched-bucket optimization; see [docs/BENCHMARKS.md](docs/BENCHMARKS.md) for measured throughput
- **Multi-language bindings** -- Python (`pip install ufsecp`), Node.js (`npm i ufsecp`), Rust, Go, C#/.NET, Java, Swift, PHP, Ruby, Dart, React Native — all via the stable C ABI
- **Embedded device support** -- ESP32-S3, ESP32-P4, ESP32-C6, STM32 Cortex-M
- **Zero-dependency portable core** -- no Boost, no OpenSSL for the CPU-only build; GPU builds require CUDA toolkit, OpenCL runtime, or Metal SDK; compiles anywhere from server-class GPUs to bare-metal microcontrollers
- **Massively parallel workloads** -- batch verification, key scanning, address generation at GPU scale
---
## Engineering Quality & Self-Audit Culture
> Most high-performance cryptographic libraries ship fast code and trust that it is correct.
> UltrafastSecp256k1 ships fast code **and then systematically tries to break it**.
> The internal self-audit system was designed in parallel with the cryptographic implementation as a first-class engineering artifact — not bolted on afterwards.
The governing idea is Bitcoin-style: **don't trust, verify**. The project does not treat assurance as a PDF milestone that must be waited on before the next improvement. Instead, it treats auditability as an always-on property of the repository: reproducible builds, rerunnable tests, structured artifacts, graph-backed code navigation, and continuous adversarial review that anyone can repeat.
This top-level narrative maps directly to the assurance ledger: CT secret-key routing (`A-001`), exploit-style audit coverage (`A-005`), graph-assisted review (`A-006`), and self-audit transparency (`A-007`).
### By the Numbers
| Metric | Value |
|--------|-------|
| Internal audit assertions per build | **≈600K explicitly itemized** field/scalar/point/CT (see [WHY_ULTRAFASTSECP256K1.md](docs/WHY_ULTRAFASTSECP256K1.md)), plus full-suite KAT/differential/fuzz checks (not individually counted) |
| Audit modules (`unified_audit_runner`) | **149 non-exploit modules + 270 exploit PoCs across 10 sections, 0 mandatory failures** (see [docs/AUDIT_COVERAGE.md](docs/AUDIT_COVERAGE.md) for advisory cluster status) |
| Exploit PoC test files | **270 exploit-PoC modules (258 source files), 20+ coverage areas, 0 mandatory failures** |
| CI/CD workflows | **50+ GitHub Actions workflows** |
| Build matrix (arch × config × OS) | **7 × 17 × 5 = 595 theoretical combinations** (actual CI matrix is a subset — see `.github/workflows/` for exact matrix) |
| Differential tests (per push + manual) | **~1,300,000+ checks per deep-assurance run** |
| Constant-time verification pipelines | **5 independent: 3 available as GitHub Actions workflows (`ct-verif.yml`, `valgrind-ct.yml`, `ct-prover.yml`) — triggered manually or on release tag push, not on every commit push; 2 manual/local: dudect statistical, ARM64 native** |
| Fuzzing adversarial corpus | **libFuzzer + ClusterFuzz-Lite (see `.clusterfuzzlite/` and `src/cpu/fuzz/`; corpus count grows with CI runs and is not stored in-repo)** |
| Static analysis tools | **7 (CodeQL, Clang-Tidy, CPPCheck, SonarCloud, Semgrep, Infer, Clang-SA)** |
| Self-audit documents in repo | see [`docs/`](docs/) directory |
| Self-tests passing (all backends) | **76/76** (reproduce: `./out/release/selftest` → "ALL TESTS PASSED"; observed on the 4.1.0 release build) |
### CI/CD Pipeline Highlights
| Workflow | Purpose | Trigger |
|----------|---------|---------|
| `gate.yml` | Block-based PR/push gate: impact detection, fast CAAS gates, selected profile checks, final verdict | Push / PR |
| `release.yml` | Release CAAS gate before build/package fan-out, then full release packaging | Tags / manual |
| `research-monitor.yml` | External research/CVE/paper intake; opens issues only for high-confidence signals | Scheduled / manual |
| Manual deep-assurance workflows | CT-Verif, Valgrind CT, sanitizers, fuzzing, mutation, benchmarks, GPU, CodeQL, Scorecard | Manual / release policy |
### What "Self-Audit Culture" Means in Practice
- Every field arithmetic property is verified algebraically: commutativity, associativity, distributivity, carry propagation, canonical form
- Every constant-time path is verified under **5 independent pipelines: LLVM ct-verif (`ct-verif.yml`), Valgrind taint (`valgrind-ct.yml`), ct-prover/sPIN (`ct-prover.yml`) — available as GitHub Actions workflows, triggered manually or on release tag push; dudect (statistical) and ARM64 native run locally/manually**
- Every ECDSA/Schnorr implementation is cross-validated against **Wycheproof vectors, independent reference golden vectors, and BIP test vectors**
- Performance evidence is tracked through manual/release deep-assurance workflows instead of every-push benchmark fan-out
- Audit results are logged as **structured artifacts** (JSON reports, per-platform logs), not just pass/fail signals
- Differential tests run on every push and via manual deep-assurance workflows; no separate nightly schedule
- All 149 non-exploit audit modules and all 270 exploit PoCs return `AUDIT-READY (self-generated)` status as of the last CAAS gate run. Zero failures — see pinned evidence: [`docs/EXTERNAL_AUDIT_BUNDLE.json`](docs/EXTERNAL_AUDIT_BUNDLE.json).
### Exploit PoC Test Suite (270 Tests, 20+ Coverage Areas)
In addition to the 419-module `unified_audit_runner`, UltrafastSecp256k1 ships **270 exploit-style PoC modules files** that actively try to break the library across its highest-risk surfaces. Each `audit/test_exploit_*.cpp` target builds and runs standalone so failures stay easy to attribute and reproduce.
| Coverage Area | Representative attack focus |
|---------------|-----------------------------|
| ECDSA / Signature | malleability, RFC 6979 KATs, recovery edge cases |
| Schnorr / BIP-340 / Batch | batch soundness, forged signatures, invalid identification paths |
| GLV / ECC Math | endomorphism invariants, multiscalar correctness, Pippenger behavior |
| BIP-32 / BIP-39 / HD Keys | path overflow, hardened isolation, mnemonic and derivation edge cases |
| MuSig2 / FROST | nonce reuse, transcript fork equivocation, stale commitment replay, rogue-key aggregation, Byzantine participants, DKG and Lagrange edge cases |
| Adaptor Signatures / ZK | adaptor parity attacks, Pedersen invariants, malformed ZK proofs |
| Crypto Primitives / AEAD | ChaCha20-Poly1305 integrity, HKDF, SHA/Keccak/RIPEMD KATs |
| ECIES | authentication forgery, encryption correctness, roundtrip safety |
| Bitcoin / Protocol BIPs | BIP-143, BIP-144, BIP-324, SegWit, Taproot protocol edge cases |
| Address / Wallet / Signing | address encoding, wallet API misuse, Ethereum and Bitcoin signing flows |
| Constant-Time / Security | CT divergence, key-recovery style probes, backend divergence detection |
| ElligatorSwift | encoding correctness and ECDH roundtrips |
| Self-Test / Recovery | self-test API behavior and recovery boundary cases |
| Batch Verify | aggregate verification math correctness |
> All 270 registered exploit-PoC modules live in `audit/test_exploit_*.cpp` (258 source files; some files register multiple modules). Build with `python3 ci/configure_build.py audit` (or `cmake -S . -B out/audit -G Ninja -DCMAKE_BUILD_TYPE=Release`) and run them standalone or via `ctest`.
### Self-Audit Document Index
| Document | Contents |
|----------|---------|
| [WHY_ULTRAFASTSECP256K1.md](docs/WHY_ULTRAFASTSECP256K1.md) | Full audit infrastructure, CI pipeline index, formal verification evidence |
| [docs/AUDIT_PHILOSOPHY.md](docs/AUDIT_PHILOSOPHY.md) | Audit philosophy, continuous evidence model, design rationale, common objections answered |
| [AUDIT_REPORT.md](docs/AUDIT_REPORT.md) | Historical baseline audit (641,194 core checks). Live module count comes from `docs/canonical_data.json` (regenerated from `audit/unified_audit_runner.cpp` ALL_MODULES[]) |
| [AUDIT_COVERAGE.md](docs/AUDIT_COVERAGE.md) | Per-module coverage matrix |
| [THREAT_MODEL.md](docs/THREAT_MODEL.md) | Layer-by-layer risk analysis |
| [SECURITY.md](SECURITY.md) | Vulnerability disclosure policy |
| [docs/AUDIT_GUIDE.md](docs/AUDIT_GUIDE.md) | Navigation guide for independent reviewers |
| [docs/CI_ENFORCEMENT.md](docs/CI_ENFORCEMENT.md) | Full CI enforcement policy |
| [docs/BACKEND_ASSURANCE_MATRIX.md](docs/BACKEND_ASSURANCE_MATRIX.md) | Per-backend assurance matrix |
| [docs/AUDIT_TRACEABILITY.md](docs/AUDIT_TRACEABILITY.md) | Requirement-to-test traceability map |
> The assurance model is open self-audit: reproducible tests, traceability, CI enforcement, and public review artifacts that anyone can rerun.
> The project hardens continuously through internal audit on every build and every commit.
---
## Performance
GPU Performance (diagnostic — out of scope for Bitcoin Core backend evaluation)
> GPU throughput numbers are intentionally not published in this README.
>
> **Why:** CLAUDE.md ABSOLUTE rule — every benchmark number must come from a measurement on the current machine and current binary; "diagnostic" or "not verified against current build" annotations on concrete numbers violate that rule even with a label. The previous RTX 5060 Ti table mixed live diagnostic figures with explicitly-stale figures; replacing both with this single pointer keeps the README honest.
>
> **Where to find the current numbers if you need them:**
>
> 1. Build and run `bench_unified --gpu` on your own hardware (the binary covers the same kernel surface the old table reported on).
> 2. The benchmark methodology is documented in `docs/BENCHMARKS.md` (CPU section); the same controlled-run discipline applies to GPU runs (CPU pinning is not relevant for GPU, but turbo-state and PCIe-state pinning are — see the `--gpu-info` flag).
> 3. Canonical bench artifacts live under `docs/bench_unified_*.json`; no GPU artifact is currently checked in because no controlled GPU run has been committed since the v4.0.0 baseline. When one is, this section will be updated to reference it (and `canonical_numbers.json` will carry the ratios via the same sync pipeline that handles CPU numbers).
>
> GPU correctness coverage IS published — see the `BACKEND_ASSURANCE_MATRIX.md` for the CT-clean status of each kernel, and the unified runner's `gpu-*` advisory modules for kernel-level invariant checks.
## Architecture
```
+-------------------------------------------------------+
| Language Bindings (FFI) |
| Python | Node | Rust | Go | C# | Java | Swift | PHP |
+-------------------------------------------------------+
|
Bindings Layer
(ctypes / koffi / cgo
JNA / P/Invoke / FFI)
|
+-------------------------------------------------------+
| UltrafastSecp256k1 Core (C++20) |
| |
| ECDSA | Schnorr | ECDH | MuSig2 | FROST | Pedersen |
| Taproot | BIP-32 HD | Adaptor Sigs | ZK Proofs |
| [FAST layer] [CT layer] |
+-------------------------------------------------------+
|
+--------+---------+---------+---------+----------------+
| CPU | CUDA | OpenCL | Metal | Embedded |
| x86_64 | NVIDIA | AMD/NV | Apple | ESP32 / STM32 |
| ARM64 | sm_50+ | any GPU | Silicon | RISC-V / WASM |
| RISC-V | | | | Cortex-M |
+--------+---------+---------+---------+----------------+
```
## Examples
| Category | Description | Link |
|----------|-------------|------|
| **CPU** | Core ECC, ECDSA, Schnorr, BIP-32, Taproot, Pedersen | [examples/](examples/) |
| **CUDA** | GPU benchmark signing kernels, batch verify, FROST, device management (production secret-key signing uses CPU CT layer) | [examples/](examples/) |
| **OpenCL** | Cross-vendor GPU compute | [examples/](examples/) |
| **Metal** | Apple Silicon GPU acceleration | [examples/](examples/) |
| **Multi-language** | C, Python, Rust, Node.js, Go, Java binding examples | [examples/README.md](examples/README.md) |
| **Embedded** | ESP32-S3, STM32 platform ports | [examples/esp32_test/](examples/esp32_test/) |
## Use Cases
- **Blockchain infrastructure** -- high-throughput transaction validation and signing pipelines (secret-key signing runs on the CPU CT layer; batch verification scales on GPU)
- **Signature verification at scale** -- batch verify millions of signatures per second on GPU
- **Cryptographic research** -- independent secp256k1 implementation with full source access
- **Zero-knowledge pipelines** -- Pedersen commitments, Bulletproofs, DLEQ proofs
- **Embedded cryptographic systems** -- hardware wallets, IoT devices, microcontrollers
- **Key scanning & address generation** -- BIP-352 Silent Payments, vanity address mining
> Star the repository if you find it useful!
---
## Security & Vulnerability Reporting
**Report vulnerabilities** via [GitHub Security Advisories](https://github.com/shrec/UltrafastSecp256k1/security/advisories/new) or email [payysoon@gmail.com](mailto:payysoon@gmail.com).
For production cryptographic systems, perform your own risk review, review the current guarantees in [SUPPORTED_GUARANTEES.md](include/ufsecp/SUPPORTED_GUARANTEES.md), and apply the assurance level appropriate to your deployment.
For the full audit infrastructure breakdown (≈600K itemized assertions, block-based CAAS gates, formal CT verification pipelines, self-audit document index), see the [Engineering Quality & Self-Audit Culture](#engineering-quality--self-audit-culture) section above and [WHY_ULTRAFASTSECP256K1.md](docs/WHY_ULTRAFASTSECP256K1.md).
> **Sponsors / funding partners:** see the "Support the Project" section at the bottom of this README.
---
## secp256k1 Feature Overview
Features are organized into **maturity tiers** (see [SUPPORTED_GUARANTEES.md](include/ufsecp/SUPPORTED_GUARANTEES.md) for detailed guarantees):
| Tier | Category | Component | Status |
|------|----------|-----------|--------|
| **1 -- Core** | Field / Scalar / Point | GLV, Precompute, Batch Inverse | [OK] |
| **1 -- Core** | Assembly | x64 MASM/GAS, BMI2/ADX, ARM64, RISC-V RV64GC | [OK] |
| **1 -- Core** | SIMD | AVX2/AVX-512 batch ops, Montgomery batch inverse | [OK] |
| **1 -- Core** | Constant-Time | CT field/scalar/point -- no secret-dependent branches | [OK] |
| **1 -- Core** | ECDSA | Sign/Verify, RFC 6979, DER/Compact, low-S, Recovery | [OK] |
| **1 -- Core** | Schnorr | BIP-340 sign/verify, tagged hashing, x-only pubkeys | [OK] |
| **1 -- Core** | ECDH | Key exchange (raw, xonly, SHA-256) | [OK] |
| **1 -- Core** | Multi-scalar | Strauss/Shamir dual-scalar multiplication | [OK] |
| **1 -- Core** | Batch verify | ECDSA + Schnorr batch verification | [OK] |
| **1 -- Core** | Hashing | SHA-256 (SHA-NI), SHA-512, HMAC, Keccak-256 | [OK] |
| **1 -- Core** | C ABI | `ufsecp` stable FFI (45 exports) | [OK] |
| **2 -- Protocol** | BIP-32/44 | HD derivation, path parsing, xprv/xpub, coin-type | [OK] |
| **2 -- Protocol** | Taproot | BIP-341/342, tweak, Merkle tree | [OK] |
| **2 -- Protocol** | MuSig2 | BIP-327, key aggregation, 2-round signing | [EXPERIMENTAL] |
| **2 -- Protocol** | FROST | Threshold signatures, t-of-n | [EXPERIMENTAL] |
| **2 -- Protocol** | Adaptor | Schnorr + ECDSA adaptor signatures | [OK] |
| **2 -- Protocol** | Pedersen | Commitments, homomorphic, switch commitments | [OK] |
| **2 -- Protocol** | ZK Proofs | Schnorr sigma, DLEQ, Bulletproof range proofs (64-bit) | [OK] |
| **3 -- Convenience** | Address | P2PKH, P2WPKH, P2TR, Base58, Bech32/m, EIP-55 | [OK] |
| **3 -- Convenience** | Coins | 27 blockchains, auto-dispatch | [OK] |
| **2 -- Protocol** | BIP-352 | Silent Payments scanning pipeline (CPU + GPU) | [OK] |
| **2 -- Protocol** | ECIES | Elliptic curve integrated encryption | [OK] |
| -- | GPU | CUDA, Metal, OpenCL kernels | [OK] · ROCm [EXPERIMENTAL] |
| -- | GPU C ABI | `ufsecp_gpu` -- 19 functions (16 batch ops + 3 lifecycle: ctx/device/error), 3 backends, incl. FROST, BIP-324, BIP-352 | [OK] |
| -- | Platforms | x64, ARM64, RISC-V, ESP32, STM32, WASM, iOS, Android | [OK] |
> **Tier 1** = battle-tested core crypto with stable API. **Tier 2** = protocol-level features, API may evolve. **Tier 3** = convenience utilities.
### BIP-340 Strict Encoding
All public API functions enforce **canonical input encoding** as required by BIP-340 and Bitcoin consensus:
- Signatures with `r >= p` or `s >= n` are **rejected, not reduced**
- Public keys with `x >= p` are **rejected, not reduced**
- Private keys must satisfy `1 <= sk < n`
The C ABI (`ufsecp_*`) returns distinct error codes: `UFSECP_ERR_BAD_SIG` (non-canonical signature) vs `UFSECP_ERR_VERIFY_FAIL` (valid encoding, bad math). See [docs/COMPATIBILITY.md](docs/COMPATIBILITY.md) for details.
---
## BIP-352 Silent Payments Scanning Benchmark
### GPU Pipeline (CUDA, RTX 5060 Ti)
The full 7-stage BIP-352 scanning pipeline runs entirely on-GPU with zero CPU round-trips:
1. **k×P** -- scalar multiply tweak point by scan private key
2. **Serialize** -- compress shared secret to 33-byte SEC1
3. **Tagged SHA-256** -- `BIP0352/SharedSecret` tagged hash
4. **k×G** -- generator multiply by hash scalar
5. **Point add** -- `spend_pubkey + output_point`
6. **Serialize + prefix** -- compress candidate, extract upper 64 bits
7. **Prefix match** -- compare against output prefix list
| Mode | ns/op | Throughput | Notes |
|------|-------|------------|-------|
| GPU pipeline (GLV, w=4) | 179.2 ns | 5.58 M/s | GLV wNAF decomposition |
| **GPU pipeline (LUT)** | **91.0 ns** | **11.00 M/s** | 64 MB precomputed 16×64K generator table |
| GPU pipeline (LUT + pretbl) | 102.1 ns | ~9.79 M/s | Precomputed per-tweak tables |
*500K tweak points per batch, 11 passes, median. Near-optimal occupancy for RTX 5060 Ti (SM 12.0, 36 SMs). ~950 billion candidates/day.*
### GPU vs CPU Comparison
| Platform | Full Pipeline | vs GPU (LUT) |
|----------|--------------|-------|
| **CUDA GPU (RTX 5060 Ti)** | **91.0 ns/op** | **baseline** |
| x86-64 CPU (i5-14400F, GCC 14) | 24,285 ns/op | 267× slower |
| ARM64 CPU (Cortex-A55, Clang 18) | 153,385 ns/op | 1,644× slower |
| RISC-V 64 (SiFive U74, GCC 13) | 257,996 ns/op | 2,765× slower |
### Community & Contributor Benchmarks
See **[docs/COMMUNITY_BENCHMARKS.md](docs/COMMUNITY_BENCHMARKS.md)** for all hardware results submitted by community members — including RTX 5070 Ti (Blackwell) and a standalone BIP-352 CPU comparison vs libsecp256k1. Want to add yours? Instructions are in that file.
### Real-world scanning performance (Frigate / Sparrow Wallet)
Independent benchmarks from [Sparrow Wallet's Frigate](https://github.com/sparrowwallet/frigate) — a DuckDB-based Silent Payments scanning pipeline using UltrafastSecp256k1 via [`ufsecp_scan(...)`](https://github.com/sparrowwallet/duckdb-ufsecp-extension). Results produced by Frigate's `benchmark.py` scanning mainnet to block 914,000.
**GPU scanning (full BIP-352 pipeline, 2-year scan, 133M tweaks):**
| Hardware | Backend | Time | Throughput |
|----------|---------|------|------------|
| 2× NVIDIA RTX 5090 | CUDA | 3.2 s | ~41.5 M/s |
| NVIDIA RTX 5080 | CUDA | 7.7 s | ~17.3 M/s |
| Apple M1 Pro | Metal | 3m 47s | ~584 K/s |
**CPU scanning (full BIP-352 pipeline, 2-year scan, 133M tweaks):**
| Hardware | CPUs | Time | Throughput |
|----------|------|------|------------|
| Intel Core Ultra 9 285K | 24 | 3m 50s | ~577 K/s |
| Apple M1 Pro | 10 | 7m 47s | ~284 K/s |
Source: [Frigate README — Performance](https://github.com/sparrowwallet/frigate/blob/master/README.md#performance)
### CPU vs libsecp256k1 (standalone external benchmark)
Standalone single-threaded benchmark by [@craigraw](https://github.com/craigraw) ([bench_bip352](https://github.com/craigraw/bench_bip352)) — full results in [docs/COMMUNITY_BENCHMARKS.md](docs/COMMUNITY_BENCHMARKS.md). Thank you for the contribution!
**Full pipeline** (10K points, 11 passes, median, GCC 12.4, `-O3 -march=native`, `USE_ASM_X86_64=1`):
| Backend | Median | ns/op | Ratio |
|---------|--------|-------|-------|
| libsecp256k1 | 545.2 ms | 54,519 ns | 1.00x |
| **UltrafastSecp256k1** | **456.1 ms** | **45,615 ns** | **1.20x faster** |
**Per-operation breakdown** (1K points, 11 passes, median):
| Operation | libsecp256k1 | UltrafastSecp256k1 | Ratio |
|-----------|-------------|-------------------|-------|
| k\*P (scalar mul) | 37,975 ns | 26,460 ns | 1.44x faster |
| Serialize compressed (1st) | 36 ns | 15 ns | 2.4x faster |
| Tagged SHA-256 ‡ | 744 ns | 65 ns | 11.4x faster (diagnostic) |
| k\*G (generator mul) | 17,460 ns | 8,559 ns | 2.04x faster |
| Point addition | 2,250 ns | 2,457 ns | 0.92x |
| Serialize compressed (2nd) | 23 ns | 21 ns | 1.1x faster |
> **Note:** Point addition is slightly slower because both inputs have Z=1 (affine), so UltrafastSecp256k1 uses direct affine addition with a field inversion to return an affine result -- this eliminates the separate inversion in serialization.
>
> **‡ Tagged SHA-256 — diagnostic only:** this ratio is environment-dependent. libsecp256k1's SHA-256 throughput depends on whether the comparison build enables SHA-NI / hardware SHA extensions and its compiler flags; on a SHA-NI-enabled libsecp build the gap narrows substantially. Treat this row as a diagnostic of our tagged-hash path, not a portable "faster than libsecp" claim.
---
## 60-Second Quickstart
Get a working selftest in under a minute:
**Option A -- Linux (apt)**
```bash
sudo apt install libufsecp4
ufsecp_selftest # Expected: "OK (version 4.1.x, backend CPU)"
```
**Option B -- npm (any OS)**
```bash
npm i ufsecp
node -e "require('ufsecp').selftest()" # Expected: "OK"
```
**Option C -- Python (any OS)**
```bash
pip install ufsecp
python -c "import ufsecp; ufsecp.selftest()" # Expected: "OK"
```
**Option D -- Build from source**
```bash
git clone https://github.com/shrec/UltrafastSecp256k1.git && cd UltrafastSecp256k1
# Recommended: canonical build under out/release
python3 ci/configure_build.py release
cmake --build out/release -j
# Or classic one-liner:
cmake -S . -B out/release -G Ninja -DCMAKE_BUILD_TYPE=Release && cmake --build out/release -j
./out/release/selftest # Expected: "ALL TESTS PASSED"
```
---
## Platform Support Matrix
| Target | Backend | Install / Entry Point | Status |
|--------|---------|----------------------|--------|
| **Linux x64** | CPU | `apt install libufsecp4` | [OK] Stable |
| **Windows x64** | CPU | NuGet `UltrafastSecp256k1` / [Release .zip](https://github.com/shrec/UltrafastSecp256k1/releases) | [OK] Stable |
| **macOS (x64/ARM64)** | CPU + Metal | `brew install ufsecp` / build from source | [OK] Stable |
| **Android ARM64** | CPU | `implementation 'io.github.shrec:ufsecp'` (Maven) | [OK] Stable |
| **iOS ARM64** | CPU | Swift Package / CocoaPods / XCFramework | [OK] Stable — **⚠️ SPM/CocoaPods builds have CT guards disabled (verification only)** |
| **Browser / Node.js** | WASM | `npm i ufsecp` | [~] Experimental — CT evidence incomplete |
| **ESP32-S3 / ESP32** | CPU | PlatformIO / IDF component | [OK] Tested |
| **ESP32-C6** | CPU (RISC-V RV32) | PlatformIO / IDF component | [OK] Tested |
| **ESP32-P4** | CPU (RISC-V HP dual-core) | PlatformIO / IDF component | [OK] Tested |
| **STM32 (Cortex-M)** | CPU | CMake cross-compile | [OK] Tested |
| **NVIDIA GPU** | CUDA 12+ | Build with `-DSECP256K1_BUILD_CUDA=ON` | [OK] Stable |
| **AMD GPU** | ROCm/HIP | Build with `-DSECP256K1_BUILD_ROCM=ON` | [!] Beta |
| **Apple GPU** | Metal | Build with Metal backend | [..] Experimental (discovery only) |
| **Any GPU** | OpenCL | Build with `-DSECP256K1_BUILD_OPENCL=ON` | [OK] Full (6/6 ops) |
| **RISC-V (RV64GC)** | CPU | Cross-compile | [OK] Tested |
---
## Installation
### Linux (APT -- Debian / Ubuntu)
```bash
# Add repository
curl -fsSL https://shrec.github.io/UltrafastSecp256k1/apt/KEY.gpg | sudo gpg --dearmor -o /etc/apt/keyrings/ultrafastsecp256k1.gpg
echo "deb [signed-by=/etc/apt/keyrings/ultrafastsecp256k1.gpg] https://shrec.github.io/UltrafastSecp256k1/apt stable main" \
| sudo tee /etc/apt/sources.list.d/ultrafastsecp256k1.list
sudo apt update
# Install (runtime only)
sudo apt install libufsecp4
# Install (development -- headers, static lib, cmake/pkgconfig)
sudo apt install libufsecp-dev
```
### Linux (RPM -- Fedora / RHEL)
```bash
# Download from GitHub Releases
curl -LO https://github.com/shrec/UltrafastSecp256k1/releases/latest/download/UltrafastSecp256k1-*.rpm
sudo dnf install ./UltrafastSecp256k1-*.rpm
```
### Arch Linux (AUR)
```bash
# Using yay
yay -S libufsecp
# Or manually
git clone https://aur.archlinux.org/libufsecp.git
cd libufsecp && makepkg -si
```
### From source (any platform)
```bash
# For development/testing, use out/release instead of the bare 'build' dir:
# python3 ci/configure_build.py release
cmake -S . -B out/release -G Ninja \
-DCMAKE_BUILD_TYPE=Release \
-DCMAKE_INSTALL_PREFIX=/usr \
-DSECP256K1_BUILD_SHARED=ON \
-DSECP256K1_INSTALL=ON \
-DSECP256K1_USE_ASM=ON
cmake --build out/release -j$(nproc)
sudo cmake --install out/release
sudo ldconfig
```
### Use in your CMake project
```cmake
find_package(secp256k1-fast REQUIRED)
target_link_libraries(myapp PRIVATE secp256k1::fast)
```
### Use with pkg-config
```bash
g++ myapp.cpp $(pkg-config --cflags --libs ufsecp) -o myapp
```
---
## secp256k1 GPU Acceleration (CUDA / OpenCL / Metal / ROCm)
> **Scope note:** The GPU backends are **not part of the Bitcoin Core secondary CPU backend PR**.
> The Bitcoin Core PR targets the CPU-only library as a compile-time drop-in secp256k1 replacement.
> GPU capabilities require opt-in build flags (`-DSECP256K1_BUILD_CUDA=ON` etc.) and are outside
> the scope of consensus-critical signing paths. See the Bitcoin Core PR description for the
> exact build configuration targeted.
UltrafastSecp256k1 provides full secp256k1 ECDSA + Schnorr sign/verify on GPU across four backends (CUDA, OpenCL, Metal, ROCm). As of February 2026, no other open-source library was known to the authors to cover all four backends; corrections are welcome ([open an issue](https://github.com/shrec/UltrafastSecp256k1/issues)):
GPU Performance tables (diagnostic — unverified against current build, not release-grade evidence. See canonical_numbers.json gpu_throughput.status field.)
| Backend | Hardware | kG/s | ECDSA Sign | ECDSA Verify | Schnorr Sign | Schnorr Verify | FROST Verify |
|---------|----------|------|------------|--------------|--------------|----------------|-------------|
| **CUDA** | RTX 5060 Ti | 4.59 M/s | 4.88 M/s | **4.05 M/s** | 3.66 M/s | **5.38 M/s** | **1.34 M/s** |
| **OpenCL** | RTX 5060 Ti | 3.86 M/s | -- | 2.44 M/s* | -- | 2.82 M/s* | — |
| **Metal** | Apple M3 Pro | 0.33 M/s | -- | -- | -- | -- |
| **ROCm (HIP)** | AMD GPUs | Portable | -- | -- | -- | -- |
*CUDA 12.0, sm_86;sm_89, batch=16K signatures, measured on RTX 5060 Ti. The CUDA path uses our own hybrid GPU execution model, which improved end-to-end throughput by more than 10% during optimization. Metal 2.4, 8x32-bit Comba limbs, 18 GPU cores. (\*) OpenCL ECDSA/Schnorr verify uses extended kernel with lazy-loaded runtime compilation.*
### CUDA Core ECC Operations (Kernel-Only Throughput)
| Operation | Time/Op | Throughput |
|-----------|---------|------------|
| Field Mul | 0.2 ns | 4,142 M/s |
| Field Add | 0.2 ns | 4,130 M/s |
| Field Inv | 10.2 ns | 98.35 M/s |
| Point Add | 1.6 ns | 619 M/s |
| Point Double | 0.8 ns | 1,282 M/s |
| Scalar Mul (Pxk) | 225.8 ns | 4.43 M/s |
| Generator Mul (Gxk) | 217.7 ns | 4.59 M/s |
| Batch Inv (Montgomery) | 2.9 ns | 340 M/s |
| Jac->Affine (per-pt) | 14.9 ns | 66.9 M/s |
### GPU Signature Operations (ECDSA + Schnorr)
| Operation | Time/Op | Throughput | Protocol | Δ vs prev |
|-----------|---------|------------|----------|----------|
| **ECDSA Sign** | **204.8 ns** | **4.88 M/s** | RFC 6979 + low-S | — |
| **ECDSA Verify** | **246.7 ns** | **4.05 M/s** | Shamir + GLV | **+66%** |
| **ECDSA Sign+Recid** | **311.5 ns** | **3.21 M/s** | Recoverable (EIP-155) | — |
| **Schnorr Sign** | **273.4 ns** | **3.66 M/s** | BIP-340 | — |
| **Schnorr Verify** | **185.9 ns** | **5.38 M/s** | BIP-340 + GLV | **+91%** |
| **FROST Partial Verify** | **748.9 ns** | **1.34 M/s** | t-of-n threshold | New |
### CUDA vs OpenCL Comparison (RTX 5060 Ti)
| Operation | CUDA | OpenCL | Winner |
|-----------|------|--------|--------|
| Field Mul | 0.2 ns | 0.2 ns | Tie |
| Field Inv | 10.2 ns | 14.3 ns | **CUDA 1.40x** |
| Point Double | 0.8 ns | 0.9 ns | **CUDA 1.13x** |
| Point Add | 1.6 ns | 1.6 ns | Tie |
| kG (Generator Mul) | 217.7 ns | 258.9 ns | **CUDA 1.19x** |
| BIP352 Pipeline | 91.0 ns | 93.6 ns | **CUDA 1.03x** |
*Benchmarks: 2026-02-14, Linux x86_64, NVIDIA Driver 580.126.09. Both kernel-only (no buffer allocation/copy overhead).*
### Apple Metal (M3 Pro) -- Kernel-Only
| Operation | Time/Op | Throughput |
|-----------|---------|------------|
| Field Mul | 1.9 ns | 527 M/s |
| Field Inv | 106.4 ns | 9.40 M/s |
| Point Add | 10.1 ns | 98.6 M/s |
| Point Double | 5.1 ns | 196 M/s |
| Scalar Mul (Pxk) | 2.94 us | 0.34 M/s |
| Generator Mul (Gxk) | 3.00 us | 0.33 M/s |
*Metal 2.4, 8x32-bit Comba limbs, Apple M3 Pro (18 GPU cores, Unified Memory 18 GB)*
---
## secp256k1 ECDSA & Schnorr Signatures (BIP-340, RFC 6979)
Full signature support across CPU and GPU:
- **ECDSA**: RFC 6979 deterministic nonces, low-S normalization, DER/Compact encoding, public key recovery (recid)
- **Schnorr**: BIP-340 compliant -- tagged hashing, x-only public keys
- **Batch verification**: ECDSA and Schnorr batch verify
- **Multi-scalar**: Shamir's trick (k_1xG + k_2xQ) for fast verification
### CPU Signature Benchmarks (x86-64, Clang 19, AVX2, Release) [archived — see docs/bench_unified_2026-05-30_gcc14_x86-64.json for current GCC 14.2.0 numbers]
| Operation | Time | Throughput |
|-----------|------:|----------:|
| ECDSA Sign (RFC 6979) | 8.5 us | 118,000 op/s |
| ECDSA Verify | 23.6 us | 42,400 op/s |
| Schnorr Sign (BIP-340) | 6.8 us | 146,000 op/s |
| Schnorr Verify (BIP-340) | 24.0 us | 41,600 op/s |
| Key Generation (CT) | 9.5 us | 105,500 op/s |
| Key Generation (fast) | 5.5 us | 182,000 op/s |
| ECDH | 23.9 us | 41,800 op/s |
*All rows above are the FAST (variable-time) path — NOT the production CT signing path. Schnorr sign is ~25% faster than ECDSA sign due to simpler nonce derivation. Measured single-core, pinned, Clang 19 — **archived 2026-02-21, NOT comparable to the current GCC 14.2.0 canonical data** below: [docs/bench_unified_2026-05-30_gcc14_x86-64.json](docs/bench_unified_2026-05-30_gcc14_x86-64.json).*
---
## Constant-Time secp256k1 (Side-Channel Resistance)
The `ct::` namespace provides constant-time operations for secret-key material -- no secret-dependent branches or memory access patterns:
| Operation | FAST | CT | CT overhead |
|-----------|-----:|---:|---:|
| Scalar Mul (k×P) | 35,593 ns | 39,056 ns | 1.10× |
| Generator Mul (k×G) | 9,200 ns | 15,347 ns | 1.67× |
| Scalar Inverse | — | 2,503 ns | CT-only |
| Point Add (complete) | — | 400 ns | CT-only |
| ECDSA sign (end-to-end) | 22,316 ns | 22,501 ns | **0.83%** |
| Schnorr sign (end-to-end) | 17,976 ns | 17,953 ns | **≈0.00%** |
*GCC 14.2.0, Intel i5-14400F, turbo disabled, CPU-pinned. Source: [`docs/bench_unified_2026-05-30_gcc14_x86-64.json`](docs/bench_unified_2026-05-30_gcc14_x86-64.json)*
**CT layer provides:** `ct::field_mul`, `ct::field_inv`, `ct::scalar_mul`, `ct::point_add_complete`, `ct::point_dbl`
**Use the CT layer for**: private key operations, signing, nonce generation, ECDH.
**Use the FAST layer for**: verification, public key derivation, batch processing, benchmarks.
See [THREAT_MODEL.md](docs/THREAT_MODEL.md) for a full layer-by-layer risk assessment.
### CT Evidence & Methodology
| Evidence | Scope | Status |
|----------|-------|--------|
| **No secret-dependent branches** | All `ct::` functions | [OK] Enforced by design, verified via Clang-Tidy checks |
| **No secret-dependent memory access** | All `ct::` table lookups use constant-index cmov | [OK] |
| **ASan + UBSan CI** | Every push -- catches undefined behavior in CT paths | [OK] CI |
| **Timing tests (dudect)** | CPU field/scalar ops | [OK] Implemented in CI + manual deep-assurance + native ARM64 |
| **Deterministic CT verification** | `ct-verif` LLVM + Valgrind CT | [OK] Implemented |
**Assumptions:** CT guarantees depend on compiler not introducing secret-dependent branches during optimization. Builds use `-O2` with Clang; MSVC may require additional flags. Micro-architectural side channels (Spectre, power analysis) are outside current scope -- see [THREAT_MODEL.md](docs/THREAT_MODEL.md).
---
## Zero-Knowledge Proofs (Schnorr Sigma, DLEQ, Bulletproofs)
UltrafastSecp256k1 provides ZK proof primitives over the secp256k1 curve:
| Proof Type | Prove | Verify | Proof Size | Use Cases |
|------------|-------|--------|------------|-----------|
| **Knowledge Proof** | 20.3 us | 21.8 us | 64 bytes | Prove knowledge of discrete log (x: P = x*G) |
| **DLEQ Proof** | 40.0 us | 56.4 us | 64 bytes | Prove log_G(P) == log_H(Q) -- VRFs, adaptor sigs, atomic swaps |
| **Bulletproof Range** | 13,467 us | 2,634 us | ~620 bytes | Prove committed value in [0, 2^64) -- Confidential Transactions |
**Security model:**
- All proving operations use the **CT layer** (constant-time, side-channel resistant)
- All verification uses the **FAST layer** (variable-time; public inputs only — no secret material)
- Non-interactive via **Fiat-Shamir** (tagged SHA-256)
- Nothing-up-my-sleeve generators for Bulletproofs (no trusted setup)
**API:** `#include ` -- namespace `secp256k1::zk`
```cpp
// Knowledge proof: prove you know x such that P = x*G
auto proof = zk::knowledge_prove(secret, pubkey, msg, aux_rand);
bool ok = zk::knowledge_verify(proof, pubkey, msg);
// DLEQ: prove log_G(P) == log_H(Q)
auto dleq = zk::dleq_prove(secret, G, H, P, Q, aux_rand);
bool ok = zk::dleq_verify(dleq, G, H, P, Q);
// Bulletproof range proof: prove committed value in [0, 2^64)
auto rp = zk::range_prove(value, blinding, commitment, aux_rand);
bool ok = zk::range_verify(commitment, rp);
```
*Benchmarks: i7-14400F, 11 passes, pinned core, median. See [docs/BENCHMARKS.md](docs/BENCHMARKS.md).*
---
## secp256k1 Benchmarks -- Cross-Platform Comparison
### CPU: x86-64 vs ARM64 vs RISC-V
| Operation | x86-64 (Clang 19, AVX2) [archived] | ARM64 (Cortex-A76) | RISC-V (Milk-V Mars) |
|-----------|-------------------------:|--------------------:|---------------------:|
| Field Mul | 17 ns | 74 ns | 95 ns |
| Field Square | 14 ns | 50 ns | 70 ns |
| Field Add | 1 ns | 8 ns | 11 ns |
| Field Inverse | 1 us | 2 us | 4 us |
| Point Add | 159 ns | 992 ns | 1 us |
| Generator Mul (kxG) | 5 us | 14 us | 33 us |
| Scalar Mul (kxP) | 25 us | 131 us | 154 us |
### GPU: CUDA vs OpenCL vs Metal
| Operation | CUDA (RTX 5060 Ti) | OpenCL (RTX 5060 Ti) | Metal (M3 Pro) |
|-----------|--------------------:|---------------------:|---------------:|
| Field Mul | 0.2 ns | 0.2 ns | 1.9 ns |
| Field Inv | 10.2 ns | 14.3 ns | 106.4 ns |
| Point Add | 1.6 ns | 1.6 ns | 10.1 ns |
| Generator Mul (Gxk) | 217.7 ns | 295.1 ns | 3.00 us |
### Embedded: ESP32-S3 vs ESP32 vs STM32
| Operation | ESP32-S3 LX7 (240 MHz) | ESP32 LX6 (240 MHz) | STM32F103 (72 MHz) |
|-----------|-------------------:|-------------------:|-------------------:|
| Field Mul | 6,105 ns | 6,993 ns | 15,331 ns |
| Field Square | 5,020 ns | 6,247 ns | 12,083 ns |
| Field Add | 850 ns | 985 ns | 4,139 ns |
| Field Inv | 2,524 us | 609 us | 1,645 us |
| **Fast** Scalar x G | 5,226 us | 6,203 us | 37,982 us |
| **CT** Scalar x G | 15,527 us | -- | -- |
| **CT** Generator x k | 4,951 us | -- | -- |
### Field Representation: 5x52 vs 4x64
| Operation | 4x64 | 5x52 | Speedup |
|-----------|------:|------:|--------:|
| Multiplication | 42 ns | 15 ns | **2.76x** |
| Squaring | 31 ns | 13 ns | **2.44x** |
| Addition | 4.3 ns | 1.6 ns | **2.69x** |
| Add chain (32 ops) | 286 ns | 57 ns | **5.01x** |
*5x52 uses `__int128` lazy reduction -- ideal for 64-bit platforms.*
For full benchmark results, see [docs/BENCHMARKS.md](docs/BENCHMARKS.md).
---
## secp256k1 on Embedded (ESP32 / STM32 / ARM Cortex-M)
UltrafastSecp256k1 runs on resource-constrained microcontrollers with **portable C++ (no `__int128`, no assembly required)**:
- **ESP32-S3** (Xtensa LX7 @ 240 MHz): Fast scalar x G in 5.2 ms, **CT generator x k in 4.9 ms**
- **ESP32-PICO-D4** (Xtensa LX6 @ 240 MHz): Scalar x G in 6.2 ms, CT layer available (44.8 ms CT)
- **ESP32-C6** (RISC-V RV32IMAC @ 160 MHz): Scalar x G in ~14 ms, CT layer available
- **ESP32-P4** (RISC-V HP dual-core @ 400 MHz): Scalar x G in ~3 ms, CT layer available
- **STM32F103** (ARM Cortex-M3 @ 72 MHz): Scalar x G in 38 ms with ARM inline assembly (UMULL/ADDS/ADCS)
- **Android ARM64** (RK3588, Cortex-A76 @ 2.256 GHz): Scalar x G in 14 us, Scalar x P in 131 us, ECDSA Sign 30 us
All 37 library tests pass on every embedded target. See [examples/esp32_test/](examples/esp32_test/) and [examples/stm32_test/](examples/stm32_test/).
### Porting to New Platforms
See [PORTING.md](docs/PORTING.md) for a step-by-step checklist to add new CPU architectures, embedded targets, or GPU backends.
---
## WASM secp256k1 (Browser & Node.js)
WebAssembly build via Emscripten -- runs secp256k1 in any modern browser or Node.js:
```bash
./ci/build_wasm.sh # -> build/wasm/dist/
```
Output: `secp256k1_wasm.wasm` + `secp256k1.mjs` (ES6 module with TypeScript declarations).
See [wasm/README.md](bindings/wasm/README.md) for JavaScript/TypeScript integration.
---
## secp256k1 Batch Modular Inverse (Montgomery Trick)
All backends include **batch modular inversion** -- a critical building block for Jacobian->Affine conversion:
| Backend | Function | Notes |
|---------|----------|-------|
| **CPU** | `fe_batch_inverse(FieldElement*, size_t)` | Montgomery trick with scratch buffer |
| **CUDA** | `batch_inverse_montgomery` / `batch_inverse_kernel` | GPU Montgomery trick kernel |
| **Metal** | `batch_inverse` | Chunked parallel threadgroups |
| **OpenCL** | Inline PTX inverse | Batch via host orchestration |
**Algorithm**: Montgomery batch inverse computes N field inversions using only **1 modular inversion + 3(N-1) multiplications**, amortizing the expensive inversion across the entire batch.
For N=1024: ~500x cheaper than individual inversions. A single field inversion costs ~3.5 us (Fermat), while batch amortizes to ~7 ns per element.
### Mixed Addition (Jacobian + Affine)
Branchless mixed addition (`add_mixed_inplace`) uses the **madd-2007-bl** formula: **7M + 4S** (vs 11M + 5S for full Jacobian add).
```cpp
#include
using namespace secp256k1::fast;
Point P = Point::generator();
FieldElement gx = P.x(), gy = P.y();
// Compute 2G using mixed add (7M + 4S)
Point Q = Point::generator();
Q.add_mixed_inplace(gx, gy); // Q = G + G = 2G
// Batch walk: P, P+G, P+2G, ...
Point walker = P;
for (int i = 0; i < 1000; ++i) {
walker.add_mixed_inplace(gx, gy); // walker += G each step
}
```
### GPU Pattern: H-Product Serial Inversion
Production GPU apps use a memory-efficient variant: instead of storing full Z coordinates, `jacobian_add_mixed_h` returns **H = U2 - X1** separately. Since Z_k = Z_0 * H_0 * H_1 * … * H_{k-1}, the entire Z chain is invertible from H values + initial Z_0.
**Cost**: 1 Fermat inversion + 2N multiplications per thread (vs N Fermat inversions naively).
> See `apps/secp256k1_search_gpu_only/gpu_only.cu` (step kernel) + `unified_split.cuh` (batch inversion kernel)
---
## secp256k1 Stable C ABI (`ufsecp`) -- FFI Bindings
Starting with **v3.4.0**, UltrafastSecp256k1 ships a stable C ABI -- `ufsecp` -- designed for FFI bindings (C#, Python, Rust, Go, Java, Node.js, Dart, React Native, PHP, Ruby, etc.):
```
+--------------------------------------------------+
| Your Application |
| (C, C#, Python, Go, Rust, …) |
+------------------+-------------------------------+
| ufsecp C ABI (45 functions)
+------------------▼-------------------------------+
| ufsecp.dll / libufsecp.so |
| Opaque ctx | Error model | ABI versioning |
+--------------+---------------+-------------------+
| FAST layer (variable-time public ops) |
+--------------------------------------------------+
| CT layer (constant-time secret-key ops) |
+--------------------------------------------------+
```
**Default behavior:**
- **C ABI (`ufsecp`)**: Defaults to safe behavior -- all secret-key operations (sign, derive, ECDH) use CT internally. No configuration needed.
- **C++ API**: Exposes both `fast::` and `ct::` namespaces -- the developer chooses explicitly per call site.
### Quick Start (C)
```c
#include "ufsecp.h"
ufsecp_ctx* ctx = NULL;
ufsecp_ctx_create(&ctx);
// Generate keypair
unsigned char seckey[32], pubkey[33];
ufsecp_keygen(ctx, seckey, pubkey);
// ECDSA sign
unsigned char msg[32] = { /* SHA-256 hash */ };
unsigned char sig[64];
ufsecp_ecdsa_sign(ctx, seckey, msg, sig);
// Verify
int valid = 0;
ufsecp_ecdsa_verify(ctx, pubkey, 33, msg, sig, &valid);
ufsecp_ctx_destroy(ctx);
```
### GPU C ABI (`ufsecp_gpu`)
Starting with **v3.3.0**, the GPU layer is fully accessible from any FFI language via `ufsecp_gpu.h`:
| Category | Functions |
|----------|-----------|
| **Discovery** | `gpu_backend_count`, `gpu_backend_name`, `gpu_is_available`, `gpu_device_count`, `gpu_device_info` |
| **Lifecycle** | `gpu_ctx_create`, `gpu_ctx_destroy`, `gpu_last_error`, `gpu_last_error_msg`, `gpu_error_str` |
| **Batch Ops** | `gpu_generator_mul_batch`, `gpu_ecdsa_verify_batch`, `gpu_schnorr_verify_batch`, `gpu_ecdh_batch`, `gpu_hash160_pubkey_batch`, `gpu_msm`, `gpu_frost_verify_partial_batch`, `gpu_ecrecover_batch` |
| Batch Operation | CUDA | OpenCL | Metal |
|----------------|------|--------|-------|
| `generator_mul_batch` | [OK] | [OK] | [OK] |
| `ecdsa_verify_batch` | [OK] | [OK] | [OK] |
| `schnorr_verify_batch` | [OK] | [OK] | [OK] |
| `ecdh_batch` | [OK] | [OK] | [OK] |
| `hash160_pubkey_batch` | [OK] | [OK] | [OK] |
| `msm` | [OK] | [OK] | [OK] |
| `frost_verify_partial_batch` | [OK] | [OK] | [OK] |
| `ecrecover_batch` | [OK] | [..] temporary stub | [..] temporary stub |
See [ufsecp_gpu.h](include/ufsecp/ufsecp_gpu.h) and [GPU Validation Matrix](docs/GPU_VALIDATION_MATRIX.md) for details.
### CPU C ABI Coverage
| Category | Functions |
|----------|-----------|
| **Context** | `ctx_create`, `ctx_destroy`, `selftest`, `last_error` |
| **Keys** | `keygen`, `seckey_verify`, `pubkey_create`, `pubkey_parse`, `pubkey_serialize` |
| **ECDSA** | `ecdsa_sign`, `ecdsa_sign_batch`, `ecdsa_verify`, `ecdsa_sign_der`, `ecdsa_verify_der`, `ecdsa_recover` |
| **Schnorr** | `schnorr_sign`, `schnorr_sign_batch`, `schnorr_verify` |
| **SHA-256** | `sha256` (SHA-NI accelerated) |
| **ECDH** | `ecdh_compressed`, `ecdh_xonly`, `ecdh_raw` |
| **BIP-32** | `bip32_from_seed`, `bip32_derive_child`, `bip32_serialize` |
| **Address** | `address_p2pkh`, `address_p2wpkh`, `address_p2tr` |
| **WIF** | `wif_encode`, `wif_decode` |
| **Tweak** | `pubkey_tweak_add`, `pubkey_tweak_mul` |
| **Version** | `version`, `abi_version`, `version_string` |
See [SUPPORTED_GUARANTEES.md](include/ufsecp/SUPPORTED_GUARANTEES.md) for Tier 1/2/3 stability guarantees.
---
## secp256k1 Use Cases
- **Transaction Signing & Verification** -- CPU constant-time signing + GPU-accelerated batch verification across Bitcoin, Ethereum, and 25+ blockchains
- **Batch Signature Verification** -- verify thousands of ECDSA/Schnorr signatures per second for block validation
- **HD Wallet Key Derivation** -- BIP-32/44 hierarchical deterministic derivation with 27-coin address generation
- **Embedded IoT Signing** -- ESP32 and STM32 on-device key generation and transaction signing
- **High-Throughput Indexing** -- GPU-accelerated public key derivation for address indexing services
- **Zero-Knowledge Proof Systems** -- Pedersen commitments, adaptor signatures for ZK protocols
- **Multi-Party Computation** -- MuSig2 (BIP-327) and FROST threshold signing
- **Cross-Platform Cryptographic Services** -- single codebase across server (CUDA), desktop (OpenCL/Metal), mobile (ARM64), browser (WASM), and embedded (ESP32/STM32)
- **Cryptographic Research & Benchmarking** -- field/group operation microbenchmarks, algorithm variant comparison
> ### Testers Wanted
> We need community testers for platforms we cannot fully validate in CI:
> - **iOS** -- Build & run on real iPhone/iPad hardware with Xcode
> - **AMD GPU (ROCm/HIP)** -- Test on AMD Radeon RX / Instinct GPUs
>
> [Open an issue](https://github.com/shrec/UltrafastSecp256k1/issues) with your results!
---
## Building secp256k1 from Source (CMake)
### Prerequisites
- CMake 3.18+
- C++20 compiler (GCC 11+, Clang/LLVM 15+, MSVC 2022+)
- CUDA Toolkit 12.0+ (optional, for GPU)
- Ninja (recommended)
### CPU-Only Build
```bash
cmake -S . -B out/release -G Ninja -DCMAKE_BUILD_TYPE=Release
cmake --build out/release -j
```
### With CUDA GPU Support
```bash
cmake -S . -B out/release -G Ninja \
-DCMAKE_BUILD_TYPE=Release \
-DSECP256K1_BUILD_CUDA=ON
cmake --build out/release -j
```
### WebAssembly (Emscripten)
```bash
./ci/build_wasm.sh # -> build/wasm/dist/
```
### iOS (XCFramework)
```bash
./ci/build_xcframework.sh # -> build/xcframework/output/
```
Universal XCFramework (arm64 device + arm64 simulator). Also available via **Swift Package Manager** and **CocoaPods**.
### Local ARM64 / RISC-V QEMU Smoke
```bash
# ARM64 cross-build + QEMU smoke
bash ./ci/run-qemu-smoke.sh arm64
# RISC-V cross-build + QEMU smoke
bash ./ci/run-qemu-smoke.sh riscv64
# Both architectures
bash ./ci/run-qemu-smoke.sh all
```
This local helper runs the same cross-arch smoke surface now used in CI:
`run_selftest smoke`, `test_bip324_standalone`, `bench_kP`, and `bench_bip324`.
Install the corresponding cross toolchain, libc sysroot, `qemu-user-static`, and `ninja-build` first.
If you prefer the existing local CI entry point, the same coverage is also available as:
```bash
bash ./ci/local-ci.sh --job qemu-smoke
# Optional: limit to one architecture
SECP256K1_QEMU_SMOKE_TARGET=arm64 bash ./ci/local-ci.sh --job qemu-smoke
SECP256K1_QEMU_SMOKE_TARGET=riscv64 bash ./ci/local-ci.sh --job qemu-smoke
```
### Build Options
| Option | Default | Description |
|--------|---------|-------------|
| `SECP256K1_USE_ASM` | ON | Assembly optimizations (x64/ARM64/RISC-V) |
| `SECP256K1_BUILD_CUDA` | OFF | CUDA GPU support |
| `SECP256K1_BUILD_OPENCL` | OFF | OpenCL GPU support |
| `SECP256K1_BUILD_ROCM` | OFF | ROCm/HIP GPU support (AMD) |
| `SECP256K1_BUILD_TESTS` | ON | Test suite |
| `SECP256K1_BUILD_BENCH` | ON | Benchmarks |
| `SECP256K1_GLV_WINDOW_WIDTH` | platform | GLV window width (4-7); default 5 on x86/ARM/RISC-V, 4 on ESP32/WASM |
| `SECP256K1_RISCV_USE_VECTOR` | ON | RVV vector extension (RISC-V) |
For detailed build instructions, see [docs/BUILDING.md](docs/BUILDING.md).
---
## secp256k1 Quick Start (C++ Examples)
### Basic Point Operations
```cpp
#include
#include
#include
#include
using namespace secp256k1::fast;
int main() {
// Public key derivation: private_key x G = public_key
auto generator = Point::generator();
auto private_key = Scalar::from_hex(
"E9873D79C6D87DC0FB6A5778633389F4453213303DA61F20BD67FC233AA33262"
);
auto public_key = generator * private_key;
std::cout << "Public Key X: " << public_key.x().to_hex() << "\n";
std::cout << "Public Key Y: " << public_key.y().to_hex() << "\n";
return 0;
}
```
```bash
g++ -std=c++20 example.cpp -lufsecp -o example && ./example
```
### GPU Batch Multiplication
```cpp
#include
#include
#include
using namespace secp256k1::fast;
int main() {
std::vector base_points(1'000'000, Point::generator());
std::vector scalars(1'000'000);
for (auto& s : scalars) s = Scalar::random();
cuda::BatchConfig config{.device_id = 0, .threads_per_block = 256, .streams = 4};
auto results = cuda::batch_multiply(base_points, scalars, config);
std::cout << "Processed " << results.size() << " point multiplications\n";
return 0;
}
```
---
## secp256k1 Security Model (FAST vs CT)
Two security profiles are **always active** -- no flag-based selection:
### FAST Profile (Default)
- Maximum throughput, variable-time algorithms
- Use for: verification, batch processing, public key derivation, benchmarking
- [!] **Not safe for secret key operations** -- timing side-channels possible
### CT / Hardened Profile (`ct::` namespace)
- Constant-time arithmetic -- no secret-dependent branches or memory access
- ~1.1–1.9× performance penalty vs FAST for primitive operations (see CT overhead table in docs/BENCHMARKS.md; release-grade measurement: `docs/bench_unified_2026-05-30_gcc14_x86-64.json`, CT overhead table, GCC 14.2.0)
- Use for: signing, private key handling, nonce generation, ECDH
**Choose the appropriate profile for your use case.** Using FAST with secret data is a security vulnerability.
See [THREAT_MODEL.md](docs/THREAT_MODEL.md) for full details.
---
## secp256k1 Supported Coins (27 Blockchains)
Supported Coins (out of scope for Bitcoin Core CPU backend review)
| # | Coin | Ticker | Address Types | BIP-44 |
|---|------|--------|---------------|--------|
| 1 | **Bitcoin** | BTC | P2PKH, P2WPKH (Bech32), P2TR (Bech32m) | m/86'/0' |
| 2 | **Ethereum** | ETH | EIP-55 Checksum | m/44'/60' |
| 3 | **Litecoin** | LTC | P2PKH, P2WPKH | m/84'/2' |
| 4 | **Dogecoin** | DOGE | P2PKH | m/44'/3' |
| 5 | **Bitcoin Cash** | BCH | P2PKH | m/44'/145' |
| 6 | **Bitcoin SV** | BSV | P2PKH | m/44'/236' |
| 7 | **Zcash** | ZEC | P2PKH (transparent) | m/44'/133' |
| 8 | **Dash** | DASH | P2PKH | m/44'/5' |
| 9 | **DigiByte** | DGB | P2PKH, P2WPKH | m/44'/20' |
| 10 | **Namecoin** | NMC | P2PKH | m/44'/7' |
| 11 | **Peercoin** | PPC | P2PKH | m/44'/6' |
| 12 | **Vertcoin** | VTC | P2PKH, P2WPKH | m/44'/28' |
| 13 | **Viacoin** | VIA | P2PKH | m/44'/14' |
| 14 | **Groestlcoin** | GRS | P2PKH, P2WPKH | m/44'/17' |
| 15 | **Syscoin** | SYS | P2PKH | m/44'/57' |
| 16 | **BNB Smart Chain** | BNB | EIP-55 | m/44'/60' |
| 17 | **Polygon** | MATIC | EIP-55 | m/44'/60' |
| 18 | **Avalanche** | AVAX | EIP-55 (C-Chain) | m/44'/60' |
| 19 | **Fantom** | FTM | EIP-55 | m/44'/60' |
| 20 | **Arbitrum** | ARB | EIP-55 | m/44'/60' |
| 21 | **Optimism** | OP | EIP-55 | m/44'/60' |
| 22 | **Ravencoin** | RVN | P2PKH | m/44'/175' |
| 23 | **Flux** | FLUX | P2PKH | m/44'/19167' |
| 24 | **Qtum** | QTUM | P2PKH | m/44'/2301' |
| 25 | **Horizen** | ZEN | P2PKH | m/44'/121' |
| 26 | **Bitcoin Gold** | BTG | P2PKH | m/44'/156' |
| 27 | **Komodo** | KMD | P2PKH | m/44'/141' |
All EVM chains (ETH, BNB, MATIC, AVAX, FTM, ARB, OP) share the same address format (EIP-55 checksummed hex).
---
## secp256k1 Architecture
### Library Stack
```
+----------------------------------------------------------+
| Language Bindings (FFI / C ABI) |
| Python | Node.js | Rust | Go | C# | Java | Swift | PHP |
+----------------------------------------------------------+
|
Bindings Layer
(ctypes / koffi / cgo
JNA / P/Invoke / FFI)
|
+----------------------------------------------------------+
| UltrafastSecp256k1 Core (C++20) |
| |
| Field Arithmetic | Scalar Ops | Point Ops | GLV/Endomo |
| ECDSA | Schnorr BIP-340 | ECDH | MuSig2 | FROST |
| Pedersen | Taproot | BIP-32 HD | Adaptor Sigs | ZK |
| |
| [FAST layer] [CT layer] |
| Variable-time Constant-time |
| Max throughput Side-channel safe |
+----------------------------------------------------------+
|
+----------+----------+----------+----------+--------------+
| CPU | CUDA | OpenCL | Metal | Embedded |
| | | | | |
| x86_64 | NVIDIA | AMD/NVIDIA| Apple | ESP32-S3 |
| ARM64 | sm_50+ | any GPU | Silicon | ESP32-C6 |
| RISC-V | | | | STM32 |
| WASM | | | | Cortex-M |
+----------+----------+----------+----------+--------------+
```
### Hardware Compatibility
| Platform | Architecture | Backend | Status |
|----------|-------------|---------|--------|
| **Desktop CPU** | x86_64 (Intel / AMD) | CPU | [OK] Stable |
| **Desktop CPU** | ARM64 (Apple Silicon, Ampere) | CPU | [OK] Stable |
| **Desktop CPU** | RISC-V RV64GC | CPU | [OK] Stable |
| **Raspberry Pi** | ARM64 (BCM2710, Zero 2 W) | CPU | [..] Testing |
| **NVIDIA GPU** | RTX / GTX / Tesla (sm_50+) | CUDA 12+ | [OK] Stable (8/8 GPU C ABI ops) |
| **AMD GPU** | RDNA / CDNA | OpenCL | [OK] Broad (7/8 GPU C ABI ops; `ecrecover_batch` pending) |
| **AMD GPU** | RDNA / CDNA | ROCm/HIP | [!] Beta |
| **Apple GPU** | Apple Silicon (M1/M2/M3/M4) | Metal | [..] Experimental (7/8 GPU C ABI ops; `ecrecover_batch` pending) |
| **Any GPU** | OpenCL 1.2+ compatible | OpenCL | [OK] Broad (7/8 GPU C ABI ops; `ecrecover_batch` pending) |
| **ESP32-S3** | Xtensa LX7 @ 240 MHz | CPU | [OK] Tested |
| **ESP32-P4** | RISC-V @ 400 MHz | CPU | [OK] Supported |
| **ESP32-C6** | RISC-V (single-core) | CPU | [OK] Supported |
| **STM32** | ARM Cortex-M3/M4 | CPU | [..] Experimental |
| **WebAssembly** | WASM (Emscripten) | CPU | [OK] Stable |
| **Android** | ARM64 (NDK r27c) | CPU | [OK] Stable |
| **iOS** | ARM64 (Xcode) | CPU | [OK] Stable |
> **GPU C ABI ops**: generator_mul_batch, ecdsa_verify_batch, schnorr_verify_batch, ecdh_batch, hash160_pubkey_batch, msm, frost_verify_partial_batch, ecrecover_batch. See [GPU Validation Matrix](docs/GPU_VALIDATION_MATRIX.md) for per-backend details.
### Embedded Targets
| Target | MCU | Clock | Scalar x G | Flash | RAM |
|--------|-----|-------|-----------|-------|-----|
| ESP32-S3 | Xtensa LX7 (dual) | 240 MHz | 5.2 ms | ~120 KB | ~8 KB |
| ESP32-PICO-D4 | Xtensa LX6 (dual) | 240 MHz | 6.2 ms | ~120 KB | ~8 KB |
| ESP32-P4 | RISC-V | 400 MHz | ~3 ms | ~120 KB | ~8 KB |
| ESP32-C6 | RISC-V (single) | 160 MHz | ~12 ms | ~120 KB | ~8 KB |
| STM32F103 | Cortex-M3 | 72 MHz | 38 ms | ~100 KB | ~6 KB |
### Source Directory
```
UltrafastSecp256k1/
+-- cpu/ # CPU-optimized implementation
| +-- include/ # Public headers (field.hpp, scalar.hpp, point.hpp, ecdsa.hpp, schnorr.hpp)
| +-- src/ # Implementation (field_asm_x64.asm, field_asm_riscv64.S, ...)
| +-- fuzz/ # libFuzzer harnesses
| +-- tests/ # Unit tests
+-- cuda/ # CUDA GPU acceleration
+-- opencl/ # OpenCL GPU acceleration
+-- metal/ # Apple Metal GPU acceleration
+-- wasm/ # WebAssembly (Emscripten)
+-- android/ # Android NDK (ARM64)
+-- include/ufsecp/ # Stable C ABI
+-- bindings/ # Language bindings (Rust, Python, Node.js, Go, C#, Java, ...)
+-- examples/
| +-- c_example/ # C API usage
| +-- rust_example/ # Rust FFI example
| +-- python_example/ # Python ctypes example
| +-- nodejs_example/ # Node.js koffi example
| +-- go_example/ # Go cgo example
| +-- java_example/ # Java JNA example
| +-- esp32_test/ # ESP32-S3 Xtensa LX7 port
| +-- stm32_test/ # STM32F103 ARM Cortex-M3 port
+-- docs/ # Documentation
```
---
## secp256k1 Testing & Verification
### Built-in Selftest
Every executable runs a deterministic **Known Answer Test (KAT)** on startup, covering all arithmetic operations:
| Mode | Time | When | What |
|------|------|------|------|
| **smoke** | ~1-2s | App startup, embedded | Core KAT (10 scalar mul, field/scalar identities, boundary vectors) |
| **ci** | ~30-90s | Every push (CI) | Smoke + cross-checks, bilinearity, NAF/wNAF, batch sweeps, algebraic stress |
| **stress** | ~10-60min | Manual / release | CI + 1000 random scalar muls, 500 field triples, batch inverse up to 8192 |
```cpp
#include "secp256k1/selftest.hpp"
using namespace secp256k1::fast;
Selftest(true, SelftestMode::smoke); // Fast startup check
Selftest(true, SelftestMode::ci); // Full CI suite
Selftest(true, SelftestMode::stress, 0xDEADBEEF); // Deep-assurance / release with custom seed
```
### Sanitizer Builds
```bash
cmake --preset cpu-asan && cmake --build out/release/cpu-asan -j # ASan + UBSan
cmake --preset cpu-tsan && cmake --build out/release/cpu-tsan -j # TSan (data races)
ctest --test-dir out/release/cpu-asan --output-on-failure
```
### Fuzz Testing
libFuzzer harnesses cover core arithmetic (`cpu/fuzz/`):
| Target | What it tests |
|--------|---------------|
| `fuzz_field` | add/sub round-trip, mul identity, square, inverse |
| `fuzz_scalar` | add/sub, mul identity, distributive law |
| `fuzz_point` | on-curve check, negate, compress round-trip, dbl vs add |
### Platform CI Coverage
| Platform | Backend | Compiler | Status |
|----------|---------|----------|--------|
| Linux x64 | CPU | GCC 13 / Clang 17 | [OK] CI |
| Linux x64 | CPU | Clang 17 (ASan+UBSan) | [OK] CI |
| Linux x64 | CPU | Clang 17 (TSan) | [OK] CI |
| Windows x64 | CPU | MSVC 2022 | [OK] CI |
| macOS ARM64 | CPU + Metal | AppleClang | [OK] CI |
| iOS ARM64 | CPU | Xcode | [OK] CI |
| Android ARM64 | CPU | NDK r27c | [OK] CI |
| WebAssembly | CPU | Emscripten | [OK] CI |
| ROCm/HIP | CPU + GPU | ROCm 6.3 | [OK] CI |
### Cross-Platform Audit Results
The `unified_audit_runner` executes exploit PoCs, constant-time analysis, differential
testing, standard vectors, fuzzing, protocol security, ABI safety, and performance validation.
> Current module counts and per-platform run results are generated automatically by
> `ci/sync_module_count.py` and are authoritative in
> [`audit/platform-reports/PLATFORM_AUDIT.md`](audit/platform-reports/PLATFORM_AUDIT.md).
> The table previously shown here was a snapshot from an earlier audit cycle and has been
> removed to avoid stale module-count contradictions — always refer to the live report.
---
## secp256k1 Benchmark Targets
| Target | Description |
|--------|-------------|
| `bench_unified` | THE standard: full apple-to-apple vs libsecp256k1 + OpenSSL |
| `bench_ct` | Fast-vs-CT overhead comparison |
| `bench_field_52` | 5x52 field arithmetic micro-benchmarks |
| `bench_field_26` | 10x26 field arithmetic micro-benchmarks |
| `bench_kP` | Scalar multiplication (k*P) benchmarks |
---
## Research Statement
This library explores the **performance ceiling of secp256k1** across CPU architectures (x64, ARM64, RISC-V, Cortex-M, Xtensa) and GPUs (CUDA, OpenCL, Metal, ROCm). Zero external dependencies. Pure C++20.
---
## API Stability
**C++ API**: Not yet stable. Breaking changes may occur before **v4.0**. Core layers (field, scalar, point, ECDSA, Schnorr) are production-ready with full audit coverage. Extended layers (MuSig2, FROST, Adaptor, Pedersen, ZK, Taproot, HD, Coins) are **Experimental** — implemented and covered by PoC exploit tests and CT verification; APIs may change. C++ API signatures may still evolve before v4.0.
**C ABI (`ufsecp`)**: Stable from v3.4.0. ABI version tracked separately. See [SUPPORTED_GUARANTEES.md](include/ufsecp/SUPPORTED_GUARANTEES.md).
---
## Release Signing & Verification
All releases starting from **v3.15.0** are cryptographically signed using
[Sigstore cosign](https://docs.sigstore.dev/) (keyless, GitHub OIDC identity).
Older historical releases remain unsigned but are preserved unchanged.
Every release includes:
| Artifact | Purpose |
|----------|---------|
| `SHA256SUMS` | Checksums for all release archives |
| `SHA256SUMS.sig` | Cosign signature of the manifest |
| `SHA256SUMS.pem` | Signing certificate (Sigstore OIDC) |
| `sbom.cdx.json` | CycloneDX Software Bill of Materials |
| Per-archive `.sig` + `.pem` | Individual artifact signatures |
### Verify checksums
**Linux:**
```bash
curl -LO https://github.com/shrec/UltrafastSecp256k1/releases/latest/download/SHA256SUMS
sha256sum -c SHA256SUMS
```
**macOS:**
```bash
shasum -a 256 -c SHA256SUMS
```
**Windows (PowerShell):**
```powershell
Get-Content SHA256SUMS | ForEach-Object {
$parts = $_ -split ' '
$expected = $parts[0]; $file = $parts[1]
$actual = (Get-FileHash $file -Algorithm SHA256).Hash.ToLower()
if ($actual -eq $expected) { "[OK] $file" } else { "[FAIL] $file" }
}
```
### Verify signature (cosign)
```bash
cosign verify-blob SHA256SUMS \
--signature SHA256SUMS.sig \
--certificate SHA256SUMS.pem \
--certificate-identity-regexp "github.com/shrec/UltrafastSecp256k1" \
--certificate-oidc-issuer https://token.actions.githubusercontent.com
```
| Supply Chain | Status |
|-------------|--------|
| SHA256SUMS for all artifacts | [OK] Every release |
| Cosign / Sigstore manifest signing | [OK] v3.15.0+ |
| Per-artifact Cosign signatures | [OK] v3.15.0+ |
| SLSA Build Provenance (GitHub Attestation) | [OK] Every release |
| CycloneDX SBOM | [OK] Every release |
| Reproducible builds documentation | [OK] Dockerfile.reproducible |
---
## FAQ
**Is UltrafastSecp256k1 a drop-in replacement for libsecp256k1?**
> No. It is an independent implementation with a different API. The C ABI (`ufsecp`) provides a stable FFI surface, but function signatures differ from libsecp256k1. Migration requires code changes.
**Is the API stable?**
> As of v4.0, the C ABI (`ufsecp_*`) and `ct::` signing namespace are stable with SemVer guarantees. The broader C++ API (namespaces `fast::`, experimental modules) is mature for Tier 1 features; breaking changes follow a deprecation cycle. See [docs/ABI_VERSIONING.md](docs/ABI_VERSIONING.md).
**What is the constant-time scope?**
> All functions in `ct::` namespace are constant-time: field arithmetic, scalar arithmetic, point multiplication, complete addition, signing, and ECDH. The C ABI uses CT internally for all secret-key operations. See [CT Evidence](#ct-evidence--methodology) above.
**Which parts are production-safe today?**
> Tier 1 features (core ECC, ECDSA, Schnorr, ECDH, stable C ABI) are extensively tested, fuzzed, regression-gated, and run through sanitizer-backed CI with a strong self-audit trail and reproducible evidence.
**How do I reproduce the benchmarks?**
> See [`docs/BENCHMARKS.md`](docs/BENCHMARKS.md) for exact commands, pinned compiler/driver versions, and raw logs. The [live dashboard](https://shrec.github.io/UltrafastSecp256k1/dev/bench/) tracks performance across commits.
---
## Documentation
| Document | Description |
|----------|-------------|
| [API Reference](docs/API_REFERENCE.md) | Full C++ and C ABI reference |
| [Build Guide](docs/BUILDING.md) | Detailed build instructions for all platforms |
| [Benchmarks](docs/BENCHMARKS.md) | Complete benchmark results and methodology |
| [GPU API](include/ufsecp/ufsecp_gpu.h) | GPU C ABI header (28 functions, 8 ops, 3 backends) |
| [GPU Validation Matrix](docs/GPU_VALIDATION_MATRIX.md) | Per-backend op coverage and validation status |
| [Feature Maturity](docs/FEATURE_MATURITY.md) | Per-feature GPU/CT/fuzz/tier status table |
| [Supported Guarantees](include/ufsecp/SUPPORTED_GUARANTEES.md) | ABI stability tiers and commitment levels |
| [Audit Coverage](docs/AUDIT_COVERAGE.md) | Full audit report with 149 non-exploit modules + 270 exploit PoCs and platform verdicts |
| [Audit Guide](docs/AUDIT_GUIDE.md) | How to run and interpret audit suite |
| [Test Matrix](docs/TEST_MATRIX.md) | Comprehensive test coverage map for auditors |
| [ARM64 Audit & Benchmark](docs/ARM64_AUDIT_BENCHMARK.md) | ARM64 platform certification and performance analysis |
| [Threat Model](docs/THREAT_MODEL.md) | Layer-by-layer security risk assessment |
| [Security Policy](SECURITY.md) | Vulnerability reporting and audit status |
| [Porting Guide](docs/PORTING.md) | Add new platforms, architectures, GPU backends |
| [RISC-V Optimizations](docs/RISCV64_BITCOIN_CORE_BENCHMARK.md) | RISC-V assembly details |
| [ESP32 Setup](docs/ESP32_SETUP.md) | ESP32 embedded development guide |
| [Examples](examples/README.md) | Multi-language binding examples (C, Python, Rust, Node.js, Go, Java) |
| [Contributing](CONTRIBUTING.md) | Development guidelines |
| [Changelog](CHANGELOG.md) | Version history |
---
## Contributing
Contributions are welcome! Please read [CONTRIBUTING.md](CONTRIBUTING.md).
```bash
git clone https://github.com/shrec/UltrafastSecp256k1.git
cd UltrafastSecp256k1
cmake -S . -B build/dev -G Ninja -DCMAKE_BUILD_TYPE=Debug
cmake --build out/release/dev -j
ctest --test-dir out/release/dev --output-on-failure
```
---
## License
**MIT License**
This project is licensed under the MIT License.
Previously released versions (up to v3.14.x) were under AGPL-3.0.
As of v3.15.0 the license is MIT -- to align with the broader Bitcoin ecosystem
and remove adoption friction.
See [LICENSE](LICENSE) for full details.
---
## Contact & Community
| Channel | Link |
|---------|------|
| Issues | [GitHub Issues](https://github.com/shrec/UltrafastSecp256k1/issues) |
| Discussions | [GitHub Discussions](https://github.com/shrec/UltrafastSecp256k1/discussions) |
| Wiki | [Documentation Wiki](https://github.com/shrec/UltrafastSecp256k1/wiki) |
| Benchmarks | [Live Dashboard](https://shrec.github.io/UltrafastSecp256k1/dev/bench/) |
| Security | [Report Vulnerability](https://github.com/shrec/UltrafastSecp256k1/security/advisories/new) |
| Commercial | [payysoon@gmail.com](mailto:payysoon@gmail.com) |
---
## Acknowledgements
UltrafastSecp256k1 is an independent implementation -- written from scratch with our own architecture, hybrid GPU execution model, embedded ports, and optimization techniques. The library's core structure and most performance gains came from direct experimentation, profiling, and iteration. At the same time, no project exists in a vacuum. Studying public research and implementation notes from the wider cryptographic community later helped us validate decisions, avoid weaker paths, and uncover additional optimization opportunities.
We want to acknowledge the teams whose public work informed parts of our journey:
- **[bitcoin-core/secp256k1](https://github.com/bitcoin-core/secp256k1)** -- A major reference point for the ecosystem. UltrafastSecp256k1 was built independently from scratch, but studying their published research later helped us benchmark our own implementations, validate design choices, and extract additional optimization ideas for CPU, GPU, and embedded targets.
- **[Bitcoin Core](https://github.com/bitcoin/bitcoin)** contributors -- For open specifications (BIP-340 Schnorr, BIP-341 Taproot, RFC 6979) and a correctness-first engineering culture that benefits everyone building in this space.
- **Pieter Wuille, Jonas Nick, Tim Ruffing** and the libsecp256k1 maintainers -- For publicly sharing research and implementation insights on side-channel resistance, exhaustive testing, field representation trade-offs, and practical optimization techniques. Their published work was valuable to study in the later optimization phase and helped us push our independently built engine further.
- **[@craigraw](https://github.com/craigraw)** ([Sparrow Wallet](https://sparrowwallet.com)) -- For creating the [bench_bip352](https://github.com/craigraw/bench_bip352) standalone BIP-352 Silent Payments scanning benchmark, which provided an independent, reproducible pipeline comparison between secp256k1 implementations.
- **Community / GigaChad** -- For running the full CUDA test suite on RTX 5070 Ti (Blackwell), confirming 45/45 tests pass, and identifying the `CMAKE_CUDA_SEPARABLE_COMPILATION` flag required for Blackwell devices. Results in [docs/COMMUNITY_BENCHMARKS.md](docs/COMMUNITY_BENCHMARKS.md).
We share our optimizations, GPU kernels, embedded ports, and cross-platform techniques freely -- because open-source cryptography grows stronger when knowledge flows in every direction.
Special thanks to the [Stacker News](https://stacker.news) and [Delving Bitcoin](https://delvingbitcoin.org) communities for their early support and technical feedback.
Extra gratitude to [@0xbitcoiner](https://stacker.news/0xbitcoiner) for the initial outreach and for helping bridge the project with the wider Bitcoin developer ecosystem.
---
## Support the Project
If you find **UltrafastSecp256k1** useful, consider supporting its development!
> **We are actively seeking sponsors for a funded bug bounty program, stronger open audit infrastructure, and ongoing development.**
> See the [Seeking Sponsors](#seeking-sponsors----bug-bounty--development) section above for details.
[![Sponsor](https://img.shields.io/badge/Sponsor_This_Project-GitHub_Spons