Oracles

An oracle is an external process (like a script, binary, or web service) that exposes custom logic or data to a Cairo program at runtime. You use it to perform tasks the Cairo VM can't, such as accessing real-world data or executing complex, non-provable computations.

Using oracles

The oracle library provides a type-safe interface for interacting with external oracles in Cairo applications. Invoking oracles via this package is the recommended way, as it provides a well-tested, secure, and maintainable interface for oracle interactions.

Go to oracle on scarbs.xyz →

The documentation for this package provides a bird's-eye overview, guidelines, and instructions on how to invoke oracles from Cairo code.

Go to oracle documentation →

In the oracle repository there is also an end-to-end example showcasing the feature. It implements a simple Cairo executable script, that invokes an oracle written in Rust that runs as a child process.

Go to oracle example →

Writing oracles

In Cairo, the oracle abstraction doesn't specify how to implement or execute oracles. Those are details that are specific to the executor being used. Oracles are invoked using generic connection strings with the following format:

protocol:connection params

The Scarb executor supports multiple oracle protocols:

• shell — one‑shot shell command execution returning stdout.
• wasm — run WebAssembly components.

Some oracles may depend on external files. Use the assets field to include them in the build.