If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/kroma-network/tachyon shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across all four use cases

• 5 active contributors
• Distributed ownership (top contributor 49% of recent commits)
• MIT licensed
• CI configured
• Tests present
• ⚠ Stale — last commit 1y ago

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live kroma-network/tachyon repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/kroma-network/tachyon.

What it runs against: a local clone of kroma-network/tachyon — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in kroma-network/tachyon | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | Last commit ≤ 556 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of kroma-network/tachyon. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/kroma-network/tachyon.git
#   cd tachyon
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of kroma-network/tachyon and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "kroma-network/tachyon(\\.git)?\\b" \\
  && ok "origin remote is kroma-network/tachyon" \\
  || miss "origin remote is not kroma-network/tachyon (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 556 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~526d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/kroma-network/tachyon"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Tachyon is a modular GPU-accelerated zero-knowledge proof backend written in C++ that implements finite fields (BabyBear, Goldilocks, Mersenne-31, KoalaBear, BinaryFields), elliptic curves (BN254, BLS12-381, Secp256k1, Pallas, Vesta), and commitment schemes (GWC, SHPlonk, Pedersen). It enables developers to build custom ZK proving systems with CPU/GPU interoperability by aligning code structure to algebraic structures. Bazel-based monorepo: core algebraic primitives in C++ (finite fields, curves), benchmarking layer in benchmark/ (ec/, fft/, msm/), language bindings via bazel/tachyon_py.bzl, bazel/tachyon_node.bzl, bazel/tachyon_rust.bzl, with vendored ecosystem implementations (vendors/scroll_halo2, vendors/plonky3, vendors/sp1) and Rust workspace members in tachyon/rs/.

ZK protocol developers and cryptography engineers building proving systems (e.g., circuit compilers, L2 rollup backends, privacy-preserving applications) who need high-performance field arithmetic and polynomial commitment operations on both CPU and GPU without reimplementing the mathematical foundations.

Actively developed with comprehensive CI/CD via .github/workflows/ci.yml, multi-language support (C++, Rust, Python, TypeScript bindings), and extensive benchmarking infrastructure (benchmark/ directory with ec/, fft/, msm/, poseidon benchmarks). Production-ready for core primitives (finite fields, curves, GWC/SHPlonk) though FRI commitment on GPU is still under construction (🏗️).

Large surface area (5.6M LOC C++, vendored dependencies like scroll_halo2, plonky3, sp1) increases maintenance burden; relies on CUDA/GPU availability for advertised performance gains; monorepo structure with mixed Rust/C++ can complicate builds. No obvious abandonment signals, but GPU-specific features introduce platform fragmentation risk.

Active work on GPU support for commitment schemes (FRI is 🏗️), modular ZK backend architecture, and multi-language interoperability (Python pybind11 deps in bazel/pybind11_deps.bzl, TypeScript/Node bindings). Benchmark suite actively expanded across MSM, FFT, Poseidon variants.

git clone https://github.com/kroma-network/tachyon.git
cd tachyon
bazel build //... # Requires Bazel (see .bazelversion)
bazel test //... # Run test suite
bazel run //benchmark/ec:ec_double_benchmark_gpu # Example GPU benchmark

Daily commands: No traditional 'dev server'; this is a library. Build with bazel build //:all, run benchmarks via bazel run //benchmark/ec:*, execute tests with bazel test //.... GPU benchmarks require CUDA toolchain configured (see .bazelrc).

• bazel/tachyon.bzl: Central Bazel configuration macro that orchestrates C++/GPU builds across the monorepo
• benchmark/ec/ec_double_benchmark_gpu.cc: Concrete example of GPU kernel dispatch and benchmarking pattern for elliptic curve operations
• bazel/tachyon_py.bzl: Defines Python binding rules via pybind11; essential for understanding multi-language interop
• .bazelrc: Contains CUDA/GPU toolchain configuration; modifying this is critical for GPU builds
• Cargo.toml: Rust workspace root; defines Rust sub-projects (tachyon/rs) that provide alternative bindings
• .github/workflows/ci.yml: CI pipeline showing test matrix (CPU/GPU), build targets, and integration points

New finite field: Add struct in tachyon/math/fields/ and implement trait; new elliptic curve: create in tachyon/math/elliptic_curves/ with coordinate system variants; new commitment scheme: add to tachyon/crypto/commitments/ following GWC/SHPlonk patterns; language binding: create Bazel rules in bazel/tachyon_*.bzl and wrapper in respective language directory; benchmarks: add .cc file in benchmark/{ec,fft,msm}/ and reference in BUILD.bazel.

CUDA requirement: GPU benchmarks fail silently if CUDA is unavailable; check .bazelrc for cuda_enabled flag. Bazel version pinning: .bazelversion specifies exact Bazel release; mismatches cause cryptic build errors. Vendored dependencies: vendors/ contains forked halo2/plonky3; upstream changes won't auto-sync. Workspace isolation: Rust and C++ portions use different dependency trees (Cargo.lock vs Bazel WORKSPACE); version conflicts possible. Benchmark path assumptions: GPU benchmarks assume NVIDIA GPU present; falls back to CPU silently, making perf comparisons misleading.

• Finite Field Arithmetic — Tachyon's core abstraction; all ZK operations (polynomial evaluation, point multiplication) reduce to field operations, and GPU acceleration here multiplies system performance
• Elliptic Curve Point Operations — Commitment schemes (GWC, SHPlonk, Pedersen) and many proof systems rely on EC point arithmetic; Tachyon abstracts over curve families (Weierstrass, Montgomery) to enable GPU kernels
• Polynomial Commitment Schemes — GWC, SHPlonk, and FRI are the three commitment schemes Tachyon implements; choosing between them trades proof size, verification time, and prover cost—this library makes them swappable
• GPU Kernel Compilation and CUDA PTX — Tachyon compiles C++ to GPU kernels via CUDA; understanding GPU memory layout, warp scheduling, and register pressure is essential for optimizing field arithmetic kernels
• Bazel Monorepo Build System — Tachyon uses Bazel extensively (bazel/tachyon*.bzl rules, multi-language support); understanding Bazel's remote execution, caching, and build graphs is required for modifying the build
• Fast Fourier Transform (FFT) — FFT is used in polynomial commitment verification and batch operations; Tachyon benchmarks FFT performance across field implementations (BabyBear, Goldilocks, etc.)
• Multi-Scalar Multiplication (MSM) — MSM is the bottleneck in proof generation for systems using discrete log commitments; Tachyon provides GPU-accelerated MSM for BN254, BLS12-381, and other curves

• arkworks-rs/arkworks-rs — Arkworks is referenced extensively in benchmarks (benchmark/msm/arkworks, benchmark/fft/arkworks, benchmark/poseidon/arkworks); provides alternative Rust ZK backend that Tachyon compares against
• privacy-scaling-explorations/halo2 — Halo2 is vendored as vendors/scroll_halo2 (Scroll fork); Tachyon implements compatible commitment schemes (GWC, SHPlonk) and benchmarks against it
• Plonky3-Community/Plonky3 — Plonky3 is vendored as vendors/plonky3; Tachyon benchmarks FRI and Poseidon2 implementations against it (benchmark/fri/plonky3, benchmark/poseidon2/plonky3)
• matter-labs/era-bellman-cuda — Era Bellman CUDA is a predecessor GPU-accelerated ZK backend; Tachyon builds on similar GPU acceleration patterns with broader field/curve coverage
• ethereum/cysic-sp1 — SP1 is vendored as vendors/sp1; represents downstream proving system that could consume Tachyon as modular backend

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add GPU-accelerated benchmark CI workflow for FFT and MSM across multiple hardware platforms

The repo has extensive benchmark code (benchmark/fft/, benchmark/msm/, benchmark/ec/) with existing results for Mac M3, Ubuntu i9, and RTX 4090, but no automated CI workflow to run these benchmarks on PR submission. This would catch performance regressions and help maintainers validate GPU acceleration improvements across different hardware. The .github/workflows/ directory exists but only has ci.yml and delete_cache.yml.

• [ ] Create .github/workflows/gpu_benchmark.yml that runs benchmark/fft/fft_benchmark_gpu.cc, benchmark/fft/fft_config.cc, and benchmark/ec/ec_double_benchmark_gpu.cc
• [ ] Configure the workflow to parse and compare benchmark output against baseline metrics stored in the repo
• [ ] Add conditional triggers to only run on PRs that modify files in benchmark/, tachyon/gpu, or math/fields to avoid excessive resource usage
• [ ] Document expected hardware requirements and optional GPU runner setup in a BENCHMARK_CI.md file

Add missing Python bindings and tests for core ZK operations exposed via tachyon_py.bzl

The repo includes bazel/tachyon_py.bzl for Python bindings and has Rust workspaces with pybind11 support, but lacks a dedicated test suite and documentation for Python API usage. Given the modular design goal and the existence of benchmark examples in multiple languages (Rust, C++), Python developers should have equal first-class support with corresponding unit tests.

• [ ] Create py_tests/ directory with test_fft.py, test_msm.py, and test_poseidon2.py mirroring benchmark/fft/halo2, benchmark/msm/, and benchmark/poseidon2/ structure
• [ ] Add Python type stubs (.pyi files) for tachyon Python modules to enable IDE autocomplete
• [ ] Update BUILD.bazel files to include py_test rules that validate Python bindings against C++ implementations
• [ ] Add a docs/PYTHON_API.md documenting how to import and use tachyon from Python with concrete examples

Consolidate and document GPU support matrix across benchmark suites (FFT, MSM, EC, FRI, Poseidon)

The repo has benchmarks for FFT (benchmark/fft/), MSM (benchmark/msm/), EC (benchmark/ec/), FRI (benchmark/fri/), and Poseidon variants (benchmark/poseidon/, benchmark/poseidon2/), but no unified documentation or configuration matrix showing which GPU operations are supported, tested, and optimized. This creates confusion for contributors and users about what's production-ready.

• [ ] Create docs/GPU_SUPPORT_MATRIX.md documenting which operations (FFT, MSM, EC doubling, FRI, Poseidon hashing) support GPU acceleration, which fields/curves are supported, and which are WIP
• [ ] Add a benchmark/BUILD.bazel config system to define supported GPU targets across all benchmark suites using a shared tachyon.bzl macro
• [ ] Create benchmark/BENCHMARK_GUIDE.md explaining how to run each benchmark suite locally and interpret results
• [ ] Add validation tests in benchmark/ that ensure all GPU code paths are actually exercised (prevent bitrot of unused GPU optimizations)

• Add CPU benchmarks for FRI commitment scheme (GPU version is 🏗️); implement benchmark/fri/fri_cpu_benchmark.cc and integrate into CI—requires understanding commitment trait patterns from GWC/SHPlonk
• Document field trait implementations with concrete examples; create tachyon/math/fields/FIELD_EXTENSION_GUIDE.md covering BabyBear → Goldilocks extension—helps onboarding and exposes missing trait docs
• Implement TypeScript bindings for Secp256k1 curve operations; extend bazel/tachyon_node.bzl with Secp256k1 wrapper following BN254 pattern already in repo—gap between advertised curve support and actual Node.js API

Tachyon shows a reasonable security posture for a ZK backend project, but has notable gaps in GPU cryptography security validation, dependency management transparency, and security documentation. The primary concerns are: (1) GPU-accelerated cryptographic implementations require specialized security audits for side-channel resistance, (2) vendored dependencies lack clear version tracking and update procedures, and (3) absence of formal security documentation and disclosure policies. The codebase would benefit from formal security audits, automated dependency scanning in CI/CD, and comprehensive security documentation. No obvious secrets, injection vulnerabilities, or critical misconfigurations were detected in the file structure provided.

• Medium · Multiple LICENSE Files Without Clear Attribution — LICENSE.* files at root and Cargo.lock. The codebase contains multiple LICENSE files from different projects (arkworks-rs, era-bellman-cuda, halo2, plonky3, scroll, stwo, EF, chromium, lambdaworks, tensorflow, ulvetanna) which suggests vendored dependencies. Without clear dependency tracking in a lockfile review, there's risk of using outdated or vulnerable versions of these libraries. Fix: Maintain a comprehensive Software Bill of Materials (SBOM). Regularly audit transitive dependencies using cargo audit and cargo deny. Implement automated dependency scanning in CI/CD pipeline via tools like Dependabot or Snyk.
• Medium · GPU-Accelerated Code Without Visible Security Review Markers — benchmark/ec/ec_double_benchmark_gpu.cc, benchmark/fft/fft_benchmark_gpu.cc, and related GPU implementations. The codebase includes GPU-accelerated cryptographic operations (based on benchmark/ec and benchmark/fft directories with GPU implementations). GPU code paths can introduce side-channel vulnerabilities, timing attacks, or memory disclosure if not carefully implemented. No visible code review markers or security audit documentation found. Fix: Conduct formal security audits specifically for GPU-based cryptographic implementations. Implement constant-time operations. Document side-channel resistance measures. Consider using established GPU cryptography libraries with security histories.
• Medium · Vendored Dependencies Without Clear Version Pinning Visibility — vendors/ directory and Cargo.toml workspace members. The vendors/ directory contains vendored copies of external projects (scroll_halo2, plonky3, sp1). Vendoring without clear update procedures can lead to running outdated code with known vulnerabilities. Fix: Establish a clear vendoring policy with documented update schedules. Maintain a manifest of vendored versions. Automate security scanning of vendored code. Consider using workspace dependencies feature instead of vendoring where possible.
• Low · Incomplete README Security Documentation — README.md. The README focuses on overview and community but lacks security guidelines, vulnerability disclosure policy, or security best practices documentation. Fix: Add a SECURITY.md file with: responsible disclosure policy, supported versions, security contact information, and known limitations/considerations for ZK proof implementations.
• Low · Bazel Configuration Without Visible Security Constraints — bazel/ directory and WORKSPACE configuration. Build configuration files (bazel/tachyon*.bzl) don't show explicit security constraints, sandboxing rules, or build artifact signing procedures. Fix: Implement strict sandboxing in Bazel configuration. Add cryptographic verification for build artifacts. Document build security policies. Consider enabling hermetic builds.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.