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
shellpackage for ready to use Cairo library that wraps this protocol.
- check out the
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
| 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.... |
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. |
Type aliases
| Result | Result<T, oracle::Error> |