Documentation

Guides and reference for Aristotle

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 add and offset, 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 bool other 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.

rust
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:

markdown
# 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:

shell
$ 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:

markdown
## 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:

markdown
## 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:

text
leanprover/lean4:v4.34.0

Add a lakefile.toml in the same directory, using the public Iris snapshot for Lean 4.34:

toml
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:

shell
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.