Documentation
Rust verification
Aristotle formally verifies properties of programs written in Rust. It can verify whole programs, libraries, or individual functions. You state the properties of interest in English, either in the prompt or in a specification file uploaded with your sources, and Aristotle proves them with a machine-checked proof about your code. Every proof establishes that the functions it covers execute without undefined behavior whenever their callers meet the stated preconditions. On request, Aristotle also proves functional correctness: that a function computes what you say it should.
After analysis, Aristotle returns a summary listing each property you asked for and its status, followed by the verification boundary: which of your functions are verified, which parts of the crate the verification does not reach, and everything the result assumes, such as preconditions on function inputs or the assumed behavior of an external dependency. A property that is false is reported as Refuted, with its evidence: an input on which it fails, a formal proof that it is false, or both.
Under the hood
Aristotle compiles the provided Rust code deterministically into our proprietary Lean formal model of Rust execution (onward: the embedding). This embedding is at the level of the Rust mid-level IR (MIR), and tracks pointer provenance, applies the Tree Borrows aliasing rules to references, records which bytes are uninitialized, and covers every choice that the Rust semantics leaves implementation-specific, such as allocation addresses, NaN payloads, and allocation failures. The proofs Aristotle writes use compositional reasoning based on separation logic.
Sources are verified exactly as submitted. Aristotle never edits your Rust to make it easier to analyze: it does not rewrite a function, replace it with a simpler one, or stub out a dependency. The only extra code it may add is a small separate crate that calls your library's public API, to verify a property of one particular instantiation of generic code.
Supported language and platform features
Aristotle supports safe and unsafe Rust, including references and raw pointers; Box, Vec, String
and other standard-library code; traits, dyn dispatch and closures; and raising panics and unwinding.
Input and output. Console and file reads and writes are recorded as a sequence of I/O events. An I/O specification states which outputs are allowed after each sequence of earlier events, and a proof can show that every output of the program is allowed.
Inline assembly is supported for 64-bit unsigned division (div), square root (sqrtss, sqrtsd),
fused multiply-add and prefetch on x86-64; prefetch performs no memory access. Other inline assembly is
rejected by default.
Solana programs are supported when built with target_os = "solana". The Solana syscalls for sysvars,
SHA-256 hashing, program-derived addresses, curve-point validation and cross-program invocation are modeled
by assumed contracts of the Solana runtime. Log output is discarded.
Undefined behavior that Aristotle detects
A successful Aristotle proof rules out:
- accessing memory through a pointer without provenance, outside the allocation identified by its provenance, or after the lifetime of that allocation has ended, such as after it is freed;
- pointer arithmetic that must stay in bounds, such as
addandoffset, leaving its allocation; - misaligned loads and stores;
- accesses that violate the aliasing rules for references;
- loading a value that is invalid for its type, such as uninitialized memory read as an integer, a
boolother than 0 or 1, or an invalid enum discriminant; - invalid frees: freeing twice, through a pointer that is not the start of an allocation, or with the wrong size, alignment or kind of allocation;
- invalid unchecked arithmetic: division or remainder by zero, signed division or remainder overflow, arithmetic overflow, and out-of-range shift counts;
- reaching unreachable code.
The embedding does not yet detect every form of Rust undefined behavior. For example, it does not always check that a reference points to memory that can be dereferenced. Also, when a caller and the called function use different but ABI-compatible types for an argument or result, for example through a function-pointer cast, it does not check that the value is valid at the receiving type.
Installation
Upload your Rust project in the web app, or have your AI assistant send it through the MCP server. To submit from the command line, see MCP & CLI. You do not need a Rust toolchain installed to submit.
Aristotle verifies Cargo packages and workspaces, and Rust source files uploaded without a Cargo
project. For a Cargo project, upload each package's Cargo.toml and sources, together with every
dependency they use; see Dependencies. Rust files uploaded without a Cargo.toml,
one or several, can use only the standard library.
Example workflow
This example uses a fixed-capacity ring buffer in a library crate named ringbuf, with the usual Cargo
layout: Cargo.toml, Cargo.lock and src/lib.rs.
pub const CAPACITY: usize = 8;
pub struct RingBuffer {
data: [u32; CAPACITY],
head: usize, // index of the oldest element
len: usize, // number of elements stored
}
impl RingBuffer {
pub fn new() -> Self {
RingBuffer { data: [0; CAPACITY], head: 0, len: 0 }
}
/// Returns `false`, leaving the buffer unchanged, if it is full.
pub fn push(&mut self, value: u32) -> bool {
if self.len == CAPACITY {
return false;
}
let tail = (self.head + self.len) % CAPACITY;
self.data[tail] = value;
self.len += 1;
true
}
/// Returns `None`, leaving the buffer unchanged, if it is empty.
pub fn pop(&mut self) -> Option<u32> {
if self.len == 0 {
return None;
}
let value = self.data[self.head];
self.head = (self.head + 1) % CAPACITY;
self.len -= 1;
Some(value)
}
pub fn len(&self) -> usize {
self.len
}
}
To specify the intended behavior, add a file ringbuf_spec.md next to Cargo.toml:
# Formally Verify the Ring Buffer
Verify the following properties of `RingBuffer` in `src/lib.rs`, for every buffer reachable
from `RingBuffer::new` through any sequence of `push` and `pop` calls:
- `new()` returns a buffer whose `len()` is 0.
- `push` and `pop` never panic.
- `push` returns `false` and leaves the buffer unchanged when `len() == CAPACITY`; otherwise it
stores `value`, returns `true`, and `len()` increases by exactly one.
- `pop` returns `None` and leaves the buffer unchanged when `len() == 0`; otherwise it returns
the oldest stored value and `len()` decreases by exactly one.
- Values are returned by `pop` in the same order they were stored by `push` (FIFO).
Submit the crate directory with a prompt such as:
$ aristotle submit "Perform the formal verification of the ringbuf crate as specified in ringbuf_spec.md" --project-dir ./ringbuf --wait --destination ringbuf_result.tar.gz
The command creates a project, which you can monitor at
https://aristotle.harmonic.fun/projects. Without --wait
the command returns as soon as the project exists; use aristotle list, aristotle show <project-id>
and aristotle download <project-id> to follow up later.
Before it begins proving, Aristotle turns each property into a precise formal statement. When a
property can reasonably be read more than one way, or needs a precondition you did not state,
Aristotle asks on the project page, in terms of your own functions, types and fields. It can wait up
to 15 minutes for answers, whether or not you pass --wait. With --wait at an interactive terminal,
the CLI also displays questions and accepts your answers. Otherwise, answer on the project page or
with aristotle questions <project-id>. If a necessary answer does not arrive, the affected properties
remain unverified, and the summary explains why.
When every property is proved, the summary looks like this:
## Formal Verification Complete
All 5 requested properties of `RingBuffer` are proved by formal verification of `src/lib.rs`
as submitted.
### Properties
- **`new` starts empty**: `RingBuffer::new().len() == 0`.
- **No panics**: `push` and `pop` return without panicking on every buffer reachable from `new`.
- **`push`**: when `len() == CAPACITY` it returns `false` and changes nothing; otherwise it
stores `value` at index `(head + len) % CAPACITY`, increments `len`, and returns `true`.
- **`pop`**: when `len() == 0` it returns `None` and changes nothing; otherwise it returns
`Some(data[head])`, advances `head` modulo `CAPACITY`, and decrements `len`.
- **FIFO order**: for any sequence of `push` and `pop` calls starting from `new`, the values
returned by successful pops are the successfully pushed values in push order.
### Verification boundary
- **Verified.** `new`, `push`, `pop` and `len`.
- **Not verified.** Nothing else in the crate.
- **Assumed.** Buffers are built through `new`, `push` and `pop`, which maintain
`head < CAPACITY` and `len <= CAPACITY`. The crate has no dependencies.
Suppose instead that push computed the write index as let tail = self.head + self.len;. The
summary then reports the failing case:
## Property Refuted: `push` Can Panic
**`push` violates "`push` and `pop` never panic".** The write index is computed as
`let tail = self.head + self.len;` with no reduction modulo `CAPACITY`, so whenever
`head + len >= CAPACITY` the store `self.data[tail] = value` indexes past the end of `data`.
**Failing case:** call `RingBuffer::new()`, push the values 1 through 8, pop once (so
`head == 1` and `len == 7`), then push the value 9. The store indexes `data[8]` and panics with
`index out of bounds: the len is 8 but the index is 8`.
### Other requested properties
- **`new` starts empty**: proved.
- **`pop`**: proved.
- **`push`** and **FIFO order**: not verified; both depend on the `push` behavior shown above.
Specifying what to verify
Properties may be given in the prompt directly or in any text or Markdown file in the project directory that the prompt refers to. Write them in terms of your own functions, types, fields and variants. Useful things to state explicitly:
- Which functions the properties are about. By default, Aristotle verifies the functions your properties name and the helpers they reach in the supplied code. See External crates for dependency scope and contracts. Functions your properties never reach are not verified, and the summary says so.
- Preconditions your code does not check itself: input ranges, non-empty slices, sorted inputs, invariants a caller must maintain. A property is proved for exactly the inputs its preconditions allow. If a property needs a precondition you did not state, Aristotle asks you about it or adds the precondition to the property and reports the addition.
- Panics. A proof covers what holds when a call returns. If you need a function never to panic on valid inputs, say so, as the example does.
- What "correct" means for functional properties. Freedom from undefined behavior needs no specification beyond the preconditions; functional correctness does.
Generic code is verified for every instantiation your property allows. To verify a property of one particular instantiation, say which one in the property.
Dependencies
Aristotle fetches dependencies before building your project offline. Supported sources are:
- crates.io packages.
- Public HTTPS Git repositories on GitHub, Codeberg, and GitLab, including GitLab subgroups. Repositories that require credentials and SSH URLs are unsupported.
- Path dependencies contained in the upload.
Upload your manifests, Rust sources, Cargo.lock, and any path dependencies. An existing lockfile
must be up to date and pin Git dependencies to full commit hashes. You can use Cargo's branch,
tag, or rev fields in manifests; the lockfile records the resolved commit. If a lockfile is missing,
Aristotle generates it during dependency preparation.
The CLI leaves files listed in .gitignore out of the upload; make sure the upload includes your
lockfile and path dependencies. Preparation reports unsupported sources or dependencies it cannot fetch
before proving starts.
External crates
By default, Aristotle verifies the supplied code needed for your properties, including supplied dependency implementations. It may offer to verify additional dependencies and continues with the default scope while awaiting your answer. Aristotle automatically reuses applicable implementation proofs for individual dependency functions.
For external functions outside that scope, Aristotle reuses applicable contracts or derives them from source code. When source is unavailable, it uses documentation and how your code calls them. These contracts need no approval. The summary states the assumed behavior and every result that depends on it; these function implementations remain unverified. Obligations imposed on your code must still be proved or stated as caller preconditions.
For Solana programs, Aristotle does not verify programs called through cross-program invocation, even when their source is available. Their required guarantees follow the same contract policy; caller-side setup, cleanup and callbacks remain in scope.
Public Lean specifications
When a result includes public Lean specifications, the archive stores them under Spec/ and their
support modules under SepLogic/, alongside your submitted sources, the summary, and any
counterexample reproducers under sim/. The project's Properties table also lists each property's status.
To build the public specifications locally, keep the downloaded Spec/ and SepLogic/ directories
together. With Lean's elan toolchain manager installed, add a lean-toolchain file beside them:
leanprover/lean4:v4.34.0
Add a lakefile.toml in the same directory, using the public Iris snapshot for Lean 4.34:
name = "RustContracts"
defaultTargets = ["Spec", "SepLogic"]
[[require]]
name = "iris"
git = "https://github.com/leanprover-community/iris-lean"
rev = "391b22c69f63169c3b1c9dbb0ff736ebeef6514f" # v4.34.0
subDir = "Iris"
[[lean_lib]]
name = "Spec"
globs = ["Spec.+"]
[[lean_lib]]
name = "SepLogic"
globs = ["SepLogic.+"]
Then run:
lake update && lake build
If a specification imports other public Lean libraries, add their compatible versions as dependencies
in lakefile.toml. This build checks that the published specifications compile. Proof source is not
included in the download.
Current assumptions and limitations
Assumptions
Aristotle assumes that:
- the Rust compiler front end and the translation into the embedding are faithful;
- the compiler has no bugs that affect the program, and does not optimize it based on undefined behavior that the embedding does not detect;
- glibc 2.39, the Linux kernel, and the Solana runtime behave as their assumed contracts state;
- the Lean proof checker is correct, and so is native evaluation where a proof uses it.
Functions Aristotle cannot handle yet
If a function your properties reach cannot be verified yet, the summary lists it by name under "Functions we cannot handle yet", and the properties that depend on it are not verified. Verification continues for the other properties. Functions your properties never reach do not affect the run.
Termination, concurrency, and memory leaks
Aristotle does not currently support reasoning about termination: functional postconditions describe what holds if a function returns. We also do not support reasoning about concurrency or memory leaks. These three forms of reasoning will be incorporated in upcoming follow-ups.
Liveness and complexity analysis
Aristotle does not support reasoning about liveness, deadlock freedom, or program complexity.
Compiler versioning and build configuration
Aristotle currently supports a single compiler version (rustc 1.97.0-nightly from 2026-05-01), and
verifies programs as built for Linux on x86-64 with the recorded profile (release by default), features,
and flags, including overflow-checks. Note that this flag is off in the default release profile:
integer addition, subtraction, multiplication, negation and shifts that overflow wrap, and a proof covers
the wrapping behavior. Division and remainder panic in every profile when the divisor is zero or the
result overflows, as in i32::MIN / -1. To have the other operations panic on overflow too, enable
overflow-checks in the profile.
We are working on providing support for multiple compiler versions, including the Anza Solana fork and the accompanying sBPF layout in follow-up work.
Program start and unsupported operations
main is called without the normal Rust start-up routine. The embedding uses its own allocator instead of a
custom #[global_allocator], and runs no panic hooks.
Unsupported operations include catching a panic, panic payloads that need to be dropped, resume_unwind,
defining C-variadic functions, longjmp, a main that returns Result, signal handlers, fork, and some
forms of mmap and ioctl.
Handling panics
A panic counts as not returning, unless your properties ask about panics; see Specifying what to verify.
When code can panic, a proof about its callers may need a precondition that rules the panic out, such as a bound on the length of a collection. Aristotle states such a precondition in the summary as a limitation of the proof.
Prose specifications
If Aristotle is, for whatever reason, not able to generate a public specification for your property, it will instead provide a prose specification detailing the proved statement or refutation.
Proof source is not returned
If Aristotle claims it has verified a property, this is always based on a machine-checked formal proof about your Rust as submitted. The proof source is not included in the result archive, so building the public specifications does not rerun those proofs.