EllipticZero

Русская версия

EllipticZero is a source-available local lab for bounded defensive ECC research and smart-contract audits.

It is built for researchers, audit teams, and protocol teams that want local evidence instead of model-only output.

Simple outside, strict inside: load a contract or choose an ECC target, write the research idea, let bounded agents select local checks, then review evidence, risk lanes, confidence, and follow-up guidance.

Session report preview

What You Get

• a local-first workflow for ECC research and smart-contract audits
• tool-backed evidence instead of model-only claims
• compact smart-contract finding cards for risk, evidence, fix direction, and recheck path
• reproducible sessions, traces, manifests, bundles, and replay
• evidence coverage, toolchain fingerprints, and secret-redacted JSON exports
• benchmark packs and golden cases for evaluator-facing smoke checks
• cautious reports with manual-review boundaries and remediation direction

License TL;DR: Read, evaluate, run locally, and use for research or internal review under FSL-1.1-ALv2. Building a competing commercial product, hosted/SaaS service, OEM integration, white-label product, resale package, or paid security platform around EllipticZero requires a separate commercial license. Each published version becomes Apache-2.0 after two years.

Why EllipticZero

EllipticZero is built for evidence-first local research, not unchecked agent autonomy. The system keeps agent reasoning, local computation, artifacts, replay, confidence, and manual-review boundaries visible in one workflow.

Its goal is to help a careful reviewer narrow what should be checked next, what the local evidence actually supports, and what still requires human judgment.

Evaluate Quickly

If you are reviewing EllipticZero as a researcher, security team, or potential commercial partner, start with:

• EVALUATION.md for the evaluation path and benchmark scorecard
• SECURITY.md for sandbox, provider, artifact, and data-handling boundaries
• examples/golden_cases/README.md for stable ECC and smart-contract smoke cases
• COMMERCIAL_LICENSE.md if your use case involves a product, hosted service, OEM, white-label, resale, or similar commercial path

Detailed Capabilities

• orchestrator-centered research sessions
• Math, Cryptography, Strategy, Hypothesis, Critic, and Report agents
• sandboxed local runners for symbolic, formal, property-based, fuzz, and ECC testbed checks
• built-in ECC benchmark packs for point anomalies, encoding edges, curve aliases, curve-family transitions, subgroup/cofactor and twist hygiene, and bounded domain completeness
• smart-contract audit tools for parser, compile, repo-scale inventory, first-party vs dependency scoping, protocol maps, review lanes, function-family prioritization, and cross-file priority fusion
• built-in smart-contract corpora for asset-flow, vault/share, oracle freshness, collateral/liquidation and liquidation-fee review, protocol-fee/reserve-buffer/debt accounting, bad-debt socialization, and related protocol-style review families
• bounded repo-scale casebooks for upgrade/storage, governance/timelock, asset-flow, oracle/liquidation, protocol accounting, rewards/distribution, stablecoin/collateral, AMM/liquidity, bridge/custody, staking/rebase, keeper/auction, treasury/vesting, insurance/recovery, and vault/permit lanes, plus optional Slither, Foundry, and Echidna adapters when installed locally
• built-in smart-contract benchmark packs for static baseline review, repo-casebook benchmarking, protocol-style repo benchmarking, upgrade/control benchmarking, governance/timelock benchmarking, rewards/distribution benchmarking, stablecoin/collateral benchmarking, AMM/liquidity benchmarking, bridge/custody benchmarking, staking/rebase benchmarking, keeper/auction benchmarking, treasury/vesting benchmarking, insurance/recovery benchmarking, vault/permission benchmarking, and lending-style protocol benchmarking
• golden/synthetic example cases with expected report shapes for evaluator-facing ECC and smart-contract smoke checks
• traces, manifests, bundles, replay, and doctor/self-check
• evidence coverage summaries, report snapshot summaries, toolchain fingerprints, and secret-redacted session/trace/bundle JSON snapshots
• mock by default, plus openai, openrouter, gemini, and anthropic when configured

Quick Start

Requirements:

• Python 3.11+
• local filesystem access for artifacts
• an API key only if you want to move beyond mock

Install:

python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
pip install -e .[lab]

Or use:

.\scripts\setup_local_lab.ps1

Smart-contract-focused local setup:

.\scripts\setup_local_lab.ps1 -Profile smart-contract-static

Launch the interface:

python -m app.main --interactive

Run the self-check:

python -m app.main --doctor

Run a safe evaluation case:

python -m app.main --golden-case contract-vault-permission-lane

Inside the interactive console, use F2 or L to switch between EN and RU.

Common Commands

Direct research session:

python -m app.main "Inspect whether secp256k1 metadata labels remain consistent across local reasoning and tool output."

Bounded exploratory mode:

python -m app.main "Explore whether ECC point parsing and on-curve checks reveal bounded defensive research leads." --research-mode sandboxed_exploratory

Smart-contract audit from a local file:

python -m app.main --domain smart_contract_audit --contract-file .\contracts\Vault.sol "Audit the contract for low-level call review surfaces and externally reachable value flow."

Smart-contract audit from inline code:

python -m app.main --domain smart_contract_audit --contract-code "pragma solidity ^0.8.20; contract Vault {}" "Review the contract for reachable admin, upgrade, and external-call surfaces."

Smart-contract benchmark pack from a local file:

python -m app.main --domain smart_contract_audit --contract-file .\contracts\Vault.sol --pack contract_static_benchmark_pack "Benchmark the contract with bounded static analysis and parser-to-surface cross-checks."

Routing overview:

python -m app.main --show-routing

Built-in golden evaluator cases:

python -m app.main --list-golden-cases
python -m app.main --golden-case contract-repo-scale-lending-protocol

For the safe evaluation case from Quick Start, expected first-screen anchors are Repo Triage Snapshot, ECC Triage Snapshot, Remediation Delta Summary, Finding Cards, Evidence Coverage, reproducibility outputs, and lower export-quality notes for toolchain fingerprint and secret redaction.

Additional CLI utilities:

python -m app.main --evaluation-summary
python -m app.main --evaluation-summary --evaluation-summary-format json
python -m app.main --evaluation-summary --replay-bundle .\artifacts\bundles\session_id
python -m app.main --provider openrouter --provider-context-preview "Preview hosted-provider context before running live agents."
python -m app.main --replay-bundle .\artifacts\bundles\session_id --export-sarif .\artifacts\sarif\session_id.sarif
python -m app.main --replay-bundle .\artifacts\bundles\session_id --export-report-md .\artifacts\reports\session_id.md
python -m app.main --list-synthetic-targets
python -m app.main --list-packs
python -m app.main --live-provider-smoke openai --live-smoke-model gpt-4.1-mini
python -m app.main --live-provider-smoke openrouter --live-smoke-model openrouter/auto
python -m app.main --replay-session .\artifacts\sessions\session_id.json
python -m app.main --domain smart_contract_audit --contract-file .\contracts\Vault.sol --compare-session .\artifacts\sessions\baseline.json "Re-run the bounded audit and record before/after deltas against the saved baseline session."

Runtime Notes

• Configuration is resolved from defaults, configs/settings.yaml, environment variables, and optional .env.
• Supported providers: mock, openai, openrouter, gemini, anthropic.
• The default route uses one provider/model for all roles. Per-agent overrides are optional.
• OpenRouter is supported as an OpenAI-compatible hosted path. Direct smoke checks use openrouter/auto unless a model is pinned.
• Local tooling can include SymPy, Hypothesis, z3-solver, managed solc, bounded mutation probes, ECC testbeds, smart-contract checks, optional SageMath, and optional static analyzers.
• Inputs stay simple: free-form ECC seeds, pasted smart-contract code, inline code, or local .sol / .vy files. Local contract files can derive a bounded repository root automatically.
• Reports cover ECC triage, benchmark posture, family coverage, comparison/regression notes, smart-contract repo triage, inventories, protocol maps, casebook matches, finding cards, review queues, remediation notes, and residual-risk lanes when local evidence supports them.
• Comparison flags (--compare-session, --compare-manifest, --compare-bundle) attach saved baselines to fresh bounded runs for cautious before/after and regression-oriented notes.
• Completed runs can store session JSON, trace JSONL, reproducibility bundles, overview.json, comparative reports, report.md, and review.sarif under artifacts/.
• The interactive console can export report.md and review.sarif from the session-actions menu without requiring export commands.
• Export policy keeps manifest and bundle material inside approved storage roots, redacts likely secrets, and treats SARIF/finding cards as review items rather than proof.
• Unsafe local plugin path layouts are blocked before registry loading. CodeQL and Dependabot workflows support repository hygiene.

See .env.example for local configuration options.

Project Docs

• docs/INDEX.md
• EVALUATION.md
• CHANGELOG.md
• docs/USE_CASES.md
• docs/ENVIRONMENT_PROFILES.md
• ARCHITECTURE.md
• AGENTS.md
• LICENSE_FAQ.md
• LICENSE_TRANSITION.md
• COMMERCIAL_LICENSE.md
• TRADEMARKS.md
• REPRODUCIBILITY.md
• REPORT_SPEC.md
• SECURITY.md
• CONTRIBUTING.md
• examples/README.md
• examples/SAMPLE_OUTPUTS.md
• examples/golden_cases/README.md
• examples/golden_cases/RUNBOOK.md
• examples/golden_cases/EXPECTED_REPORT_SHAPES.md

Verification

python -m pip check
python -m ruff check .
python -m compileall app tests scripts
pytest -q

The project passes the test suite in mock mode.

Donate

If EllipticZero is useful to your work, you can support the project here:

• Bitcoin (BTC): 1ECDSA1b4d5TcZHtqNpcxmY8pBH1GgHntN
• USDT (TRC20): TSWcFVfqCp4WCXrUkkzdCkcLnhtFLNN3Ba

Responsible Use

Use EllipticZero only for authorized local research. Keep experiments bounded, reversible, and inspectable.

License

EllipticZero is licensed under FSL-1.1-ALv2.

The public repository is source-available for evaluation, research, internal use, and other permitted purposes defined by the license.

Each version becomes available under Apache License 2.0 on the second anniversary of the date that version was made available.

If you need rights beyond the public license, including competing commercial use, hosted or managed service use, OEM, white-label, or resale, see COMMERCIAL_LICENSE.md.

This repository is public, but current versions should not be described as OSI-approved open-source releases.

Branding rights are not granted under the code license. See TRADEMARKS.md.

Commercial Use

Evaluation, research, internal review, and local testing are welcome under the public license terms.

If your use case involves a competing commercial product, commercial hosted service, OEM distribution, white-label usage, or resale, you should obtain a separate commercial license.

If you are unsure whether your deployment or product plan crosses that line, contact before shipping or selling it.

See COMMERCIAL_LICENSE.md for the short policy.

Contact

For commercial licensing, collaboration, and partnership inquiries: