Auto-prove is a multi-agent pipeline that automatically generates and verifies CVL specifications for Solidity smart contracts. Given a project root, a main contract, and a design document, it analyzes the system's components, formulates properties, and generates CVL specs — running the Certora Prover in a loop to verify them.
The fastest way from a clean clone to a working run. Everything — Python deps, the JRE, all solcX.Y compilers, the RAG knowledge base, and Postgres — is provisioned inside containers; the only host requirement is Docker (with Compose + BuildKit).
git clone --recurse-submodules git@github.com:Certora/AutoProver.git
cd AutoProver
# Claude key, plus your Certora organization API key.
export ANTHROPIC_API_KEY=sk-... CERTORAKEY=...
# A ready-to-run example project (public).
git clone https://github.com/Certora/AutoProverExamples.git
# Builds the image (first time), starts Postgres, runs one-time DB/RAG setup,
# then runs the pipeline. The project root is mounted into the container; the
# contract and design-doc paths are relative to it.
scripts/autoprove AutoProverExamples/SmokeTest src/Answer.sol:Answer design.md
# The design doc is optional — drop it and an agent discovers one from the project:
scripts/autoprove AutoProverExamples/SmokeTest src/Answer.sol:AnswerThe prover runs in the Certora cloud. Add --tui for the interactive UI, --rebuild to force an image rebuild. Pass extra autoprove options after -- (e.g. -- --max-concurrent 2). Under the hood this is just scripts/docker-compose.yml (a profile-gated autoprove service next to postgres); see the header of that file to drive it with raw docker compose commands instead.
Apple Silicon: the image is
linux/amd64(the Solidity compiler binaries are only published for amd64). Enable Docker Desktop → Settings → General → "Use Rosetta for x86/amd64 emulation" — it runs the amd64 image ~near-native; without it, qemu makes the build and the one-time RAG embedding dramatically slower.
The rest of this document covers the host uv flow for development.
You need everything from the AIComposer infrastructure setup:
- Python 3.12+,
uv, Docker with compose rustup— a defaultuv syncbuilds therust/crates (see below)ANTHROPIC_API_KEYin your environment (also when Claude runs on Amazon Bedrock)- PostgreSQL databases running (see below)
- RAG database populated
- Solidity compiler(s) on
$PATH(naming conventionsolcX.Y, e.g.solc8.29)
A uv sync, or any uv run, which revalidates path dependencies, builds the maturin crates under rust/. Without a
toolchain the sync fails outright rather than skipping. Install rustup (a distro cargo package is
not enough: rust-toolchain.toml pins the toolchain and rustup is what reads it), then once, from the repo root:
rustup toolchain install --no-self-updateRe-run that after any bump to rust-toolchain.toml's channel — rustup would otherwise install the new toolchain from
inside the build, where the concurrent cargo calls a sync makes race each other and one dies mid-download.
Not working on the Rust side? uv sync --no-dev skips the crates entirely — the Rust tests then skip themselves instead
of failing, and the CI pyright job runs this way.
Cloud mode (the default): One organization API key in CERTORAKEY submits the jobs and fetches their results. Create it on the organization's API page with Use Certora Prover ticked.
Local mode: You need a full local Prover build from https://github.com/Certora/CertoraProver. From the Prover repo root, run ./gradlew copy-assets and set CERTORA to point to CertoraProver/target. (N.B. Local mode is not yet wired through the scripts/autoprove Docker wrapper.)
From the scripts/ directory:
cd scripts/
docker compose create && docker compose startThis launches a pgvector/pgvector:pg16 container with all databases pre-initialized via init-db.sql. The databases created are:
| Database | Purpose |
|---|---|
rag_db |
CVL manual search (pgvector embeddings) |
langgraph_store_db |
LangGraph document/index store |
langgraph_checkpoint_db |
Workflow checkpoints for resumption |
memory_tool_db |
LLM context memory (hierarchical filesystem) |
audit_db |
Execution history and prover results |
By default the databases are on localhost:5432. Override with environment variables if needed:
export CERTORA_AI_COMPOSER_PGHOST=myhost
export CERTORA_AI_COMPOSER_PGPORT=5433Note: the RAG database has its own connection string (default postgresql://rag_user:rag_password@localhost:5432/rag_db), overridable via --rag-db.
The RAG database must be populated before running auto-prove. This is a two-step process:
# Build the Certora documentation HTML
./scripts/gen_docs.sh
# Populate the RAG DB from the CVL documentation
./scripts/populate_rag.shgen_docs.sh clones the Certora Documentation repo and builds single-page HTML files via Sphinx. populate_rag.sh then chunks and indexes the CVL documentation into rag_db.
To install the scripts for execution simply run:
uv tool install '.[ml,certora-cli]'The certora-cli package is selected via one of three mutually-exclusive extras (pick exactly one): certora-cli (stable/main release), certora-cli-beta, or certora-cli-beta-mirror. The prover extra is an alias for certora-cli (the main release), so '.[ml,prover]' is equivalent to the command above. These extras include all of the dependencies for running the prover scripts (in local mode) and the certoraRun scripts themselves (cloud mode).
The ml group includes sentence-transformers and einops, required for the embedding model (nomic-embed-text-v1.5) used by RAG and the indexed store.
Auto-prove has two entry points: a Textual-based TUI and a headless console mode.
tui-autoprove <project_root> <path/to/Contract.sol:ContractName> [design_doc]console-autoprove <project_root> <path/to/Contract.sol:ContractName> [design_doc]The design_doc is optional. When omitted, a "Design Doc Discovery" phase runs an
agent that searches the project for the best design/specification document and uses
it automatically; the run fails fast with guidance if it finds nothing suitable.
Console mode prints the same pipeline output to stdout without the interactive TUI. Useful for CI or logging. NB if you need to do print debugging, the console_autoprove.py is your best
bet. Debugging in the tui_autoprove.py workflow mandates the use of a python logger.
You will likely want to install the tool using the --editable flag. You'll also want to run uv sync --group test to pull in the testing utilities we use.
| Argument | Description |
|---|---|
project_root |
Root directory of the Solidity project |
main_contract |
Path to the contract file and contract name, separated by :. The path must be relative to or within project_root. Example: src/Token.sol:Token |
system_doc |
Path to a design document (plain text or PDF) describing the system. Optional — auto-discovered from the project when omitted |
| Option | Default | Description |
|---|---|---|
--max-concurrent |
4 | Maximum number of parallel agents for property extraction and CVL generation |
--cache-ns |
None | Cache namespace string. Enables cross-run caching so repeated runs skip completed phases |
--memory-ns |
None | Memory namespace. Defaults to the auto-generated thread ID |
--cloud |
off | Run prover jobs in the Certora cloud instead of locally |
--model |
claude-opus-4-6 |
Anthropic model to use |
--tokens |
10000 | Token budget for LLM responses |
--thinking-tokens |
16384 | Thinking token budget (OpenAI models: high reasoning effort) |
--rag-db |
postgresql://rag_user:rag_password@localhost:5432/rag_db |
RAG database connection string |
tui-autoprove \
AutoProverExamples/SmokeTest \
src/Answer.sol:Answer \
design.md \
--cloud \
--max-concurrent 2 \
--cache-ns my-answer-runBy default the pipeline calls Claude through the Anthropic API. With AUTOPROVER_LLM_BACKEND=bedrock it calls Claude on
Amazon Bedrock instead, through Bedrock's InvokeModel API (https://bedrock-runtime.<region>.amazonaws.com), with
the ChatAnthropicBedrock chat model of langchain-aws.
Every agent that builds its model through composer follows this setting. AutoSetup's own LLM calls still go to the
Anthropic API, so ANTHROPIC_API_KEY is required with either backend.
| Variable | Default | Meaning |
|---|---|---|
AUTOPROVER_LLM_BACKEND |
anthropic |
anthropic or bedrock. Case and surrounding spaces are ignored; any other value stops the run when a model is built. |
AWS_REGION (or AWS_DEFAULT_REGION) |
none | The Bedrock region. Required for bedrock: without it the run stops when a model is built. |
AUTOPROVER_BEDROCK_INFERENCE_PROFILE |
global |
Where Bedrock may process a request. global lets it use any commercial AWS region. A geography such as eu or us keeps requests in that geography and costs about 10% more. |
AUTOPROVER_BEDROCK_MAX_TOKENS |
128000 |
Upper limit on max_tokens in a Bedrock request. A lower value is used unchanged. |
Inference profiles. Bedrock serves current Claude models only through a cross-Region inference profile. The
profile id is the model id with the routing prefix in front, for example global.anthropic.claude-opus-5-5. Not every
model has a profile for every geography: Claude Fable 5 and 5.1 have no eu profile, so a run on Fable needs global
or us. A geographic profile also needs the region in AWS_REGION to be in that geography.
Credentials. Requests are signed with AWS SigV4, using the default AWS credential chain: environment variables, the
shared config and credentials files (profiles, SSO), the task role of an ECS or AWS Batch container, or an EC2
instance profile. No Anthropic API key is used for these requests. Set AWS_ACCESS_KEY_ID and
AWS_SECRET_ACCESS_KEY together. If only one of them is set, Bedrock refuses the request signature. The Anthropic SDK
sends a Bedrock API key instead of signing when AWS_BEARER_TOKEN_BEDROCK is set. Do not set it together with the AWS key variables: the
SDK refuses both at once. When ANTHROPIC_BEDROCK_BASE_URL is set, requests go there instead of the regional endpoint.
Permissions. The role needs the IAM actions bedrock:InvokeModel and bedrock:InvokeModelWithResponseStream.
For a global profile, AWS evaluates three resources for each model: the profile
(arn:aws:bedrock:<region>:<account>:inference-profile/global.anthropic.<model>), the model in the requesting region
(arn:aws:bedrock:<region>::foundation-model/anthropic.<model>), and the model without a region
(arn:aws:bedrock:::foundation-model/anthropic.<model>). For a geographic profile, the role needs the profile and the
model in every region the profile routes to. A service control policy that blocks regions must allow these requests;
see "Global cross-Region inference" in the Amazon Bedrock User Guide. The account must also have access to the Claude
models the run uses.
Model ids stay logical. --model, budgets, logs, pricing and the usage records in job_info.json all use
the Anthropic model ids (claude-opus-5-5). Only the chat model carries the inference profile id
(global.anthropic.claude-opus-5-5), which Bedrock takes in the request path. A Bedrock response names the model by
its Anthropic id, as the Anthropic API does. Do not pass a Bedrock id to --model. Bedrock names a few older models differently, for example
anthropic.claude-haiku-4-5-20251001-v1:0 for claude-haiku-4-5; composer keeps a table of those.
max_tokens. Bedrock reserves a request's max_tokens against the account's tokens-per-minute quota before the
model answers, so an oversized max_tokens throttles a run before its real usage reaches the quota. Bedrock
requests cap max_tokens at AUTOPROVER_BEDROCK_MAX_TOKENS. The default, 128000, is the same as on the Anthropic API.
If the quota is small, a lower value reserves less quota per request, but a turn that reaches the cap is cut off.
Throttling. Bedrock throttles against a per-account quota that parallel requests share. The SDK retries a
throttled request 8 times with its default waits. After that, the run-wide retry policy takes over, as on the
Anthropic API. If Bedrock reports an error after a streamed response started, for example a
ThrottlingException, the run step fails without a retry.
PDFs and other files. Bedrock has no Files API. On Bedrock, a PDF design document (or any other binary file the pipeline gives the model) is sent inline as base64 in every request of the conversation that carries it, with its prompt-cache marker kept. Bedrock rejects a request over 20 MB, and base64 makes a file about a third larger. The run stops with an error that names the file if a document is over 8,000,000 bytes as base64, or if it is a binary file other than a PDF. If a request is still over 20 MB, it fails with the error from Bedrock. A thread started on the Anthropic API that refers to a Files API upload cannot continue on Bedrock: its first Bedrock request fails.
Docker. scripts/autoprove and scripts/docker-compose.yml pass AUTOPROVER_LLM_BACKEND, the region variables,
the Bedrock limits above, AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY / AWS_SESSION_TOKEN,
AWS_BEARER_TOKEN_BEDROCK and ANTHROPIC_BEDROCK_BASE_URL from your shell into the
container. scripts/autoprove stops before it builds anything unless a region is set and either the AWS keys or a
Bedrock API key are exported. ~/.aws is not mounted, so for a profile or SSO session export its credentials first:
eval "$(aws configure export-credentials --format env)"
export AUTOPROVER_LLM_BACKEND=bedrock AWS_REGION=us-east-1
scripts/autoprove AutoProverExamples/SmokeTest src/Answer.sol:Answer design.mdThe pipeline executes the following phases in order:
Analyzes the source code to identify the system's components, contracts, and external actors. Uses filesystem exploration tools to read and understand the codebase. The result is cached and feeds into all subsequent phases.
Runs AutoSetup to analyze compilation and classify external contracts (ERC20s, interfaces, etc.). Generates harness contracts and a prover configuration (compilation_config.conf). Also produces summaries for known external contracts.
Generates CVL summaries for ERC20 contracts and external interfaces discovered in Phase 1. Only runs if the system has external contracts that need summarizing.
For each component identified in Phase 0, an agent analyzes the code and formulates properties to verify. Runs in parallel, bounded by --max-concurrent. Produces a list of property formulations per component.
For each component's properties, an agent generates CVL specs and runs the prover to verify them. Failed specs are revised in a feedback loop. Where a counterexample starts from a state the contract cannot reach, the agent states that relationship as an invariant, proves it in the same spec, and cites it with requireInvariant. Results are written to certora/specs/autospec_{component}.spec with accompanying commentary files. Also bounded by --max-concurrent.
Auto-prove writes its output into the certora/ directory within the project root. Generated specs live under certora/specs/ (the prover resolves CVL imports relative to that directory), while their run configs go to certora/confs/:
certora/specs/autospec_{component}.spec(e.g.autospec_Core_Logic.spec) — per-component specscertora/specs/summaries/*.spec— AutoSetup-generated and protocol-specific summariescertora/confs/*.conf— per-spec prover configs (eachverifypoints at the spec's path relative to the project root)
Each autospec_{component} spec is accompanied by metadata under certora/properties/, keyed by the spec's stem:
certora/properties/{stem}.properties.json— the analysis-phase property formulations (title, sort, methods, description);titleis the cross-reference keycertora/properties/{stem}.property_rules.json— the property→rules mapping ({property title: [rule names]})certora/properties/{stem}.commentary.md— LLM commentary explaining the generated spec
The pipeline returns an AutoProveResult with counts of components analyzed, properties generated, and any failures.
When --cache-ns is provided, auto-prove caches the results of expensive phases (system analysis, property extraction, per-component CVL generation) in the LangGraph store. On subsequent runs with the same --cache-ns, cached results are reused if the inputs (project root, contract path, design doc content) haven't changed.
The cache key is derived from a SHA-256 hash of the project root, design document content, contract path, and contract name. Changing any of these invalidates the cache.
When the design doc is auto-discovered, the discovery step is itself cached under a doc-independent key (project root, contract path, contract name) — so a repeat run on the same project reuses the previously discovered document and skips the discovery agent. Like the main cache, it only invalidates when the cache namespace rotates, not when project files change.
You can view the cache/memory of the various phases by running scripts/autoprove_cache_explorer.py. This script takes the same positional arguments as the *_autoprove.py entrypoints, as well as the --memory-ns and --cache-ns.
This should load up a TUI frame that lets you inspect the currently cached values. You can toggle to memory mode to view (and potentially edit) the memories of the various sub agents.
In headless mode, the CVL Generation agents will produce a mnemonic name. You can pass this mnemonic into the snapshot_viewer.py to view the conversation history of that agent.