oracle

This library provides the core functionality for interacting with oracles in Cairo. Oracles are external, untrusted processes that can be called from Cairo code to fetch data or perform computations not possible within the VM, like accessing web APIs or local files.

What is an oracle?

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 cannot, such as accessing real-world data or executing complex, non-provable computations.

IMPORTANT: The execution of an oracle occurs outside of the Cairo VM. Consequently, its operations are not included in the execution trace and are not verified by the proof. The proof only validates that a call was made to an oracle and that your program correctly handled the data it received. It provides no guarantee whatsoever that the data itself is accurate or legitimate.

How are oracles executed?

Oracle execution is managed by the Cairo runtime (e.g., the scarb execute). The runtime is responsible for interpreting the connection string and facilitating the communication between the Cairo program and the external process.

While the specific protocols are runtime-dependent, here are the common schemes:

• shell — one‑shot shell command execution returning stdout.
  • check out the shell package for ready to use Cairo library that wraps this protocol.
• wasm — run WebAssembly components.

Always consult your specific runtime's documentation for a complete list of supported protocols and available built-in oracles.

Never trust your oracle!

This is the most important security principle in this library. Because oracle execution is not proven, you must operate under the assumption that an oracle can be malicious or compromised. An attacker can intercept or control the oracle to return arbitrary, invalid, or harmful data.

Your Cairo code is the only line of defense. It is your responsibility to validate and verify any data returned by an oracle before it is used in any state-changing logic.

Always treat oracle responses as untrusted input. For example, if your program expects a sorted list of values, it must immediately verify that the list is indeed sorted. Failure to do so creates a critical security vulnerability.

Fully qualified path: oracle

Free functions

Structs

Type aliases

Traits

Impls

Free functions

invoke

Invokes an external oracle process and returns its result.

Avoid calling this function directly in user code. Instead, write oracle interface modules, which group all single oracle features together.

To use an oracle, call invoke with:

1. connection_string: A string describing how to connect to the oracle. The execution runtime handles oracle process management transparently under the hood. Consult your runtime documentation for details what protocols and options are supported. For wasm-based oracles, this is a path to a WASM binary that must be an asset.
2. selector: The name or identifier of the method to invoke on the oracle (as a ByteArray). It acts as a function name or command within the oracle process.
3. calldata: The arguments to pass to the oracle method, as a serializable Cairo type. To pass multiple arguments, use a tuple or struct that implements Serde.

The function returns a Result<R, oracle::Error>, where R is the expected return type, or an error if the invocation fails or the oracle returns an error.

mod math_oracle {
    pub type Result<T> = oracle::Result<T>;

    pub fn pow(x: u64, n: u32) -> Result<u128> {
        oracle::invoke("wasm:math_oracle.wasm", "pow", (x, n))
    }

    pub fn sqrt(x: u64) -> Result<u64> {
        oracle::invoke("wasm:math_oracle.wasm", "sqrt", x)
    }
}

Fully qualified path: oracle::invoke

pub fn invoke<T, +Destruct<T>, +Drop<T>, +Serde<T>, R, +Serde<R>>(
    connection_string: ByteArray, selector: ByteArray, calldata: T,
) -> Result<R, Error>

Structs

Error

An error type that can be raised when invoking oracles.

The internal structure of this type is opaque, but it can be displayed and (de)serialized.

Fully qualified path: oracle::Error

[derive(Drop, Clone, PartialEq, Serde)]
pub struct Error {
    message: ByteArray,
}

Type aliases

Result

Result<T, oracle::Error>

Fully qualified path: oracle::Result

pub type Result<T> = Result<T, Error>;

Traits

ErrorTrait

Fully qualified path: oracle::ErrorTrait

pub trait ErrorTrait

Trait functions

custom

Creates a new oracle::Error with a custom message.

This is useful for oracle-wrapping libraries that need extra error checking in Cairo code.

Fully qualified path: oracle::ErrorTrait::custom

fn custom(message: ByteArray) -> Error

Impls

ErrorImpl

Fully qualified path: oracle::ErrorImpl

pub impl ErrorImpl of ErrorTrait;

Impl functions

custom

Creates a new oracle::Error with a custom message.

This is useful for oracle-wrapping libraries that need extra error checking in Cairo code.

Fully qualified path: oracle::ErrorImpl::custom

fn custom(message: ByteArray) -> Error