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.

Feature status

This is an experimental feature. The API and behaviour may change in future versions of Scarb. Oracles are currently available in scarb execute with the --experimental-oracles flag Support is also planned in future versions of cairo-test and snforge.

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

• stdio:./path/to/binary: The runtime executes a local binary and pipes data between your Cairo program and the process's standard input (stdin) and standard output (stdout).
• stdio:python3 ./my_oracle.py: The runtime executes a command with arguments, allowing for more flexible process invocation.
• stdio:npx -y my_oracle: The runtime can execute package managers or other command-line tools.
• builtin:name: The runtime may provide pre-compiled, optimized "builtin" oracles for common tasks. For example, builtin:fs may refer to a runtime-provided oracle for filesystem operations, which is more efficient and secure than invoking a generic script.

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