This crate is a compiler and JIT engine that transforms Sierra (or Cairo) +sources into MLIR, which can be +JIT-executed or further +compiled into a binary +ahead of time.
+First make sure you have a working environment and are able to compile the +project without issues. Make sure to follow the setup guide +on steps on how to do this.
+It is generally recommended to use the optimized-dev cargo profile when
+testing or running programs, the make target make build-dev will be useful for
+this.
In addition to the tools included in Cairo Native, it is also recommended you
+have cairo-compile and cairo-run installed to check how the generated sierra
+code looks like, and to compare results manually (when required) which will help
+greatly when implementing functionality into Cairo Native.
You can check the cairo repository +for more info on how to get those tools.
+After having implemented your desired feature or bug fix, you should check it +passes all tests and lints, also make sure to add any needed test cases for the +added code.
+# Check it passes all lints
+make check
+
+# Check it passes all tests
+make test
+Then you are free to go and make a PR!
+This will explain how the project is structured, without going into much details +yet:
+The major dependencies of the project are the following:
+pedersen,
+keccak and dictionaries that would be quite complex to implement from
+the ground up in MLIR (Basically would be like coding a complex hash
+function in pseudo assembly).Within this project there are lots of functions with the same signature. +As their arguments have all the same meaning, they are documented here:
+context: NativeContext: The MLIR context.module: &NativeModule: The compiled MLIR program, with other relevant
+information such as program registry and metadata.program: &Program: The Sierra input program.registry: &ProgramRegistry<TType, TLibfunc>: The registry extracted
+from the program.metadata: &mut MetadataStorage: Current compiler metadata.The code is laid out in the following sections:
+ src
+ ├─ arch.rs Trampoline assembly for calling functions with dynamic signatures.
+ ├─ arch/ Architecture-specific code for the trampoline.
+ ├─ bin/ Binary programs
+ ├─ block_ext.rs A melior (MLIR) block trait extension to write less code.
+ ├─ cache.rs Types and implementations of compiled program caches.
+ ├─ compiler.rs The glue code of the compiler, has the codegen for
+ the function signatures and calls the libfunc
+ codegen implementations.
+ ├─ context.rs The MLIR context wrapper, provides the compile method.
+ ├─ debug.rs
+ ├─ docs.rs Documentation modules.
+ ├─ error.rs Error handling,
+ ├─ execution_result.rs Program result parsing.
+ ├─ executor.rs The executor & related code,
+ ├─ ffi.cpp Missing FFI C wrappers,
+ ├─ ffi.rs Missing FFI C wrappers, rust side.
+ ├─ lib.rs The main lib file.
+ ├─ libfuncs.rs Cairo Sierra libfunc glue code & implementations,
+ ├─ metadata.rs Metadata injector to use within the compilation process.
+ ├─ module.rs The MLIR module wrapper.
+ ├─ starknet.rs Starknet syscall handler glue code.
+ ├─ starknet_stub.rs
+ ├─ types.rs Cairo to MLIR type information,
+ ├─ utils.rs Internal utilities.
+ └─ values.rs JIT serialization.
+Path: src/libfuncs
Here are stored all the library function implementations in MLIR, this +contains the majority of the code.
+To store information about the different types of library functions sierra
+has, we divide them into the following using the enum SierraLibFunc:
dup, store_tempPath: src/statements
Here is the code that processes the statements of non-library functions. +It handles dataflow, branching, function calls, variable storage and also +has implementations for the inline library functions.
+These are extra utility functions unrelated to sierra that aid in the +development, such as wrapping return values and printing them.
+The API contains two structs, NativeContext and NativeExecutor.
+The main purpose of NativeContext is MLIR initialization, compilation and
+lowering to LLVM.
+NativeExecutor in the other hand is responsible of executing MLIR
+compiled sierra programs from an entrypoint. Programs and JIT states can be
+cached in contexts where their execution will be done multiple times.
use starknet_types_core::felt::Felt;
+use cairo_native::context::NativeContext;
+use cairo_native::executor::JitNativeExecutor;
+use cairo_native::values::JitValue;
+use std::path::Path;
+
+let program_path = Path::new("programs/examples/hello.cairo");
+// Compile the cairo program to sierra.
+let sierra_program = cairo_native::utils::cairo_to_sierra(program_path);
+
+// Instantiate a Cairo Native MLIR context. This data structure is responsible for the MLIR
+// initialization and compilation of sierra programs into a MLIR module.
+let native_context = NativeContext::new();
+
+// Compile the sierra program into a MLIR module.
+let native_program = native_context.compile(&sierra_program, None).unwrap();
+
+// The parameters of the entry point.
+let params = &[JitValue::Felt252(Felt::from_bytes_be_slice(b"user"))];
+
+// Find the entry point id by its name.
+let entry_point = "hello::hello::greet";
+let entry_point_id = cairo_native::utils::find_function_id(&sierra_program, entry_point);
+
+// Instantiate the executor.
+let native_executor = JitNativeExecutor::from_native_module(native_program, Default::default());
+
+// Execute the program.
+let result = native_executor
+ .invoke_dynamic(entry_point_id, params, None)
+ .unwrap();
+
+println!("Cairo program was compiled and executed successfully.");
+println!("{:?}", result);This is a usage example using the API for an easy Cairo program that +requires the least setup to get running. It allows you to compile and +execute a program using the JIT.
+Example code to run a program:
+ +use starknet_types_core::felt::Felt;
+use cairo_native::context::NativeContext;
+use cairo_native::executor::NativeExecutor;
+use cairo_native::values::JitValue;
+use std::path::Path;
+
+fn main() {
+ let program_path = Path::new("programs/examples/hello.cairo");
+ // Compile the cairo program to sierra.
+ let sierra_program = cairo_native::utils::cairo_to_sierra(program_path);
+
+ // Instantiate a Cairo Native MLIR context. This data structure is responsible for the MLIR
+ // initialization and compilation of sierra programs into a MLIR module.
+ let native_context = NativeContext::new();
+
+ // Compile the sierra program into a MLIR module.
+ let native_program = native_context.compile(&sierra_program).unwrap();
+
+ // The parameters of the entry point.
+ let params = &[JitValue::Felt252(Felt::from_bytes_be_slice(b"user"))];
+
+ // Find the entry point id by its name.
+ let entry_point = "hello::hello::greet";
+ let entry_point_id = cairo_native::utils::find_function_id(&sierra_program, entry_point);
+
+ // Instantiate the executor.
+ let native_executor = NativeExecutor::new(native_program);
+
+ // Execute the program.
+ let result = native_executor
+ .execute(entry_point_id, params, None)
+ .unwrap();
+
+ println!("Cairo program was compiled and executed successfully.");
+ println!("{:?}", result);
+}Example code to run a Starknet contract:
+ +use starknet_types_core::felt::Felt;
+use cairo_lang_compiler::CompilerConfig;
+use cairo_lang_starknet::contract_class::compile_path;
+use cairo_native::context::NativeContext;
+use cairo_native::executor::NativeExecutor;
+use cairo_native::utils::find_entry_point_by_idx;
+use cairo_native::values::JitValue;
+use cairo_native::{
+ metadata::syscall_handler::SyscallHandlerMeta,
+ starknet::{BlockInfo, ExecutionInfo, StarkNetSyscallHandler, SyscallResult, TxInfo, U256},
+};
+use std::path::Path;
+
+/// To run a starknet contract, we need to use a syscall handler, here we show how to implement one (at the end).
+#[derive(Debug)]
+struct SyscallHandler;
+
+fn main() {
+ let path = Path::new("programs/examples/hello_starknet.cairo");
+
+ let contract = compile_path(
+ path,
+ None,
+ CompilerConfig {
+ replace_ids: true,
+ ..Default::default()
+ },
+ )
+ .unwrap();
+
+ let entry_point = contract.entry_points_by_type.constructor.get(0).unwrap();
+ let sierra_program = contract.extract_sierra_program().unwrap();
+
+ let native_context = NativeContext::new();
+
+ let mut native_program = native_context.compile(&sierra_program).unwrap();
+ native_program
+ .insert_metadata(SyscallHandlerMeta::new(&mut SyscallHandler))
+ .unwrap();
+
+ // Call the echo function from the contract using the generated wrapper.
+ let entry_point_fn =
+ find_entry_point_by_idx(&sierra_program, entry_point.function_idx).unwrap();
+
+ let fn_id = &entry_point_fn.id;
+
+ let native_executor = NativeExecutor::new(native_program);
+
+ let result = native_executor
+ .execute_contract(
+ fn_id,
+ // The calldata
+ &[JitValue::Felt252(Felt::ONE)],
+ u64::MAX.into(),
+ )
+ .expect("failed to execute the given contract");
+
+ println!();
+ println!("Cairo program was compiled and executed successfully.");
+ println!("{result:#?}");
+}
+
+// Implement an example syscall handler.
+impl StarkNetSyscallHandler for SyscallHandler {
+ fn get_block_hash(
+ &mut self,
+ block_number: u64,
+ _gas: &mut u128,
+ ) -> SyscallResult<Felt> {
+ println!("Called `get_block_hash({block_number})` from MLIR.");
+ Ok(Felt::from_bytes_be_slice(b"get_block_hash ok"))
+ }
+
+ fn get_execution_info(
+ &mut self,
+ _gas: &mut u128,
+ ) -> SyscallResult<cairo_native::starknet::ExecutionInfo> {
+ println!("Called `get_execution_info()` from MLIR.");
+ Ok(ExecutionInfo {
+ block_info: BlockInfo {
+ block_number: 1234,
+ block_timestamp: 2345,
+ sequencer_address: 3456.into(),
+ },
+ tx_info: TxInfo {
+ version: 4567.into(),
+ account_contract_address: 5678.into(),
+ max_fee: 6789,
+ signature: vec![1248.into(), 2486.into()],
+ transaction_hash: 9876.into(),
+ chain_id: 8765.into(),
+ nonce: 7654.into(),
+ },
+ caller_address: 6543.into(),
+ contract_address: 5432.into(),
+ entry_point_selector: 4321.into(),
+ })
+ }
+
+ fn deploy(
+ &mut self,
+ class_hash: Felt,
+ contract_address_salt: Felt,
+ calldata: &[Felt],
+ deploy_from_zero: bool,
+ _gas: &mut u128,
+ ) -> SyscallResult<(Felt, Vec<Felt>)> {
+ println!("Called `deploy({class_hash}, {contract_address_salt}, {calldata:?}, {deploy_from_zero})` from MLIR.");
+ Ok((
+ class_hash + contract_address_salt,
+ calldata.iter().map(|x| x + &Felt::ONE).collect(),
+ ))
+ }
+
+ fn replace_class(
+ &mut self,
+ class_hash: Felt,
+ _gas: &mut u128,
+ ) -> SyscallResult<()> {
+ println!("Called `replace_class({class_hash})` from MLIR.");
+ Ok(())
+ }
+
+ fn library_call(
+ &mut self,
+ class_hash: Felt,
+ function_selector: Felt,
+ calldata: &[Felt],
+ _gas: &mut u128,
+ ) -> SyscallResult<Vec<Felt>> {
+ println!(
+ "Called `library_call({class_hash}, {function_selector}, {calldata:?})` from MLIR."
+ );
+ Ok(calldata.iter().map(|x| x * Felt::from(3)).collect())
+ }
+
+ fn call_contract(
+ &mut self,
+ address: Felt,
+ entry_point_selector: Felt,
+ calldata: &[Felt],
+ _gas: &mut u128,
+ ) -> SyscallResult<Vec<Felt>> {
+ println!(
+ "Called `call_contract({address}, {entry_point_selector}, {calldata:?})` from MLIR."
+ );
+ Ok(calldata.iter().map(|x| x * Felt::from(3)).collect())
+ }
+
+ fn storage_read(
+ &mut self,
+ address_domain: u32,
+ address: Felt,
+ _gas: &mut u128,
+ ) -> SyscallResult<Felt> {
+ println!("Called `storage_read({address_domain}, {address})` from MLIR.");
+ Ok(address * Felt::from(3))
+ }
+
+ fn storage_write(
+ &mut self,
+ address_domain: u32,
+ address: Felt,
+ value: Felt,
+ _gas: &mut u128,
+ ) -> SyscallResult<()> {
+ println!("Called `storage_write({address_domain}, {address}, {value})` from MLIR.");
+ Ok(())
+ }
+
+ fn emit_event(
+ &mut self,
+ keys: &[Felt],
+ data: &[Felt],
+ _gas: &mut u128,
+ ) -> SyscallResult<()> {
+ println!("Called `emit_event({keys:?}, {data:?})` from MLIR.");
+ Ok(())
+ }
+
+ fn send_message_to_l1(
+ &mut self,
+ to_address: Felt,
+ payload: &[Felt],
+ _gas: &mut u128,
+ ) -> SyscallResult<()> {
+ println!("Called `send_message_to_l1({to_address}, {payload:?})` from MLIR.");
+ Ok(())
+ }
+
+ fn keccak(
+ &mut self,
+ input: &[u64],
+ _gas: &mut u128,
+ ) -> SyscallResult<cairo_native::starknet::U256> {
+ println!("Called `keccak({input:?})` from MLIR.");
+ Ok(U256(Felt::from(1234567890).to_le_bytes()))
+ }
+
+ /*
+ ... more code here, check out the full example in examples/starknet.rs
+ */
+}
+For more examples, check out the examples/ directory.
This section describes the entire process Cairo Native goes through to +compile a Cairo program to either a shared library (and how to use it) or a +MLIR module for use in the JIT engine.
+If you check lib.rs you will see the high level modules of the project.
The compiler module is what glues together everything. +You should read its module level documentation. +But the basic flow is like this:
+Program and iterate over its functions.stateDiagram-v2
+ state "Load sierra program" as sierra
+ state "Initialize compiler" as init
+ state "Initialize execution engine" as engine
+ state if_skip_jit <<choice>>
+ state "Load MLIR dialects" as dialects
+ state "Create builtin module" as module
+ state "Create libc wrappers" as libc
+ state "Process Types" as types
+ state "Process Library functions" as libfuncs
+ state "Save non-flow function info" as func_info
+ state "Process functions" as funcs
+ state "Calculate block ranges per function" as blocks
+ state "Process statements" as statements
+ state "Apply MLIR passes" as passes
+ [*] --> Initialize
+ state Initialize {
+ sierra --> init
+ init --> if_skip_jit
+ if_skip_jit --> engine: if JIT
+ if_skip_jit --> dialects: if Compile
+ engine --> dialects
+ }
+ Initialize --> Compile
+ state Compile {
+ module --> libc
+ libc --> types
+ types --> libfuncs
+ types --> func_info
+ func_info --> libfuncs
+ libfuncs --> funcs
+ funcs --> blocks
+ blocks --> statements
+ }
+ Compile --> passes
+ passes --> Output
+ Output --> [*]
+The first step is to get the sierra code from the given cairo program, this
+is done using the relevant methods from the cairo_lang_compiler crate.
This gives us a cairo_lang_sierra::program::Program which has the following
+structure:
pub struct Program {
+ pub type_declarations: Vec<TypeDeclaration, Global>,
+ pub libfunc_declarations: Vec<LibfuncDeclaration, Global>,
+ pub statements: Vec<GenStatement<StatementIdx>, Global>,
+ pub funcs: Vec<GenFunction<StatementIdx>, Global>,
+}The compilation process consists in parsing these fields to produce the +relevant MLIR IR code.
+To do all this we will need a MLIR Context and a module created with that +context, the module describes a compilation unit, in this case, the cairo +program.
+In Cairo Native we provide a API around initializing the context, namely
+NativeContext which does the following when
+created:
The NativeContext has a method called
+compile,
+which does the heavy lifting and returns a NativeModule.
+This module contains the generated MLIR IR code.
The compile method does the following:
+compile method.This internal compile method then loops on the program function
+declarations calling the compile_func method on each of them.
compile_func)This method generates the structure of the function in MLIR, meaning it will +create the region the body of the function will live on, and then a block +for each statement, each with it’s relevant arguments and return values. It +will also check each statement whether it is branching, and store the +predecessors of each block, to handle jumps.
+While handling each statement on the function, it will build the types it
+finds from the arguments and return values as it encounters them, this is
+done using the trait TypeBuilder.
After having the function structure created, we proceed to creating the +initial state, which is a Hash map holding the local variables we currently +have, the parameters.
+Using this initial state, it builds the entry block, which is the first +block the function enters when it’s called, it has the function arguments +as parameters.
+Then it loops on the statements of the function, on each statement it does +the following:
+This storage is shared everywhere in the compilation process and allows to +easily share data to the relevant places, for example the Gas Metadata +allows getting the gas cost for a given statement, or the enum snapshot +metadata to get the relevant variants in the libfunc builder.
+We part from the point where the program has been compiled into MLIR IR, +and we hold the MLIR Context and Module.
+From this point, we convert all the dialects within this IR into the LLVM +MLIR Dialect, which is a needed precondition to transform the MLIR IR into +LLVM IR. This is done through passes which are the basis of how LLVM works.
+ +Given a MLIR Module with only the LLVM dialect, we can translate it,
+currently the LLVM MLIR API for this is only available in C++, so we had
+to make our temporary C API wrapper (which we contributed to upstream LLVM.
+After that we also need to use the llvm-sys crate which provides the C
+API bindings in Rust.
The required method is mlirTranslateModuleToLLVMIR which takes a MLIR
+Module and a LLVM Context (not a MLIR one!). The LLVM Context will be used
+to create a LLVM Module, which we can then compile to machine code.
The process is a bit verbose but interesting, LLVM itself is a target +independent code generator, but to compile down we need an actual target, +to do so we initialize the required target and utilities (in this case we +initialize all targets the current compiled LLVM supports):
+ +LLVM_InitializeAllTargets();
+LLVM_InitializeAllTargetInfos();
+LLVM_InitializeAllTargetMCs();
+LLVM_InitializeAllAsmPrinters();
+LLVM_InitializeAllAsmParsers();After that we create a LLVM context, and pass it along the module to the
+mlirTranslateModuleToLLVMIR method:
let llvm_module = mlirTranslateModuleToLLVMIR(mlir_module_op, llvm_context);Then we need to create the target machine, which needs a target triple, the +CPU name and CPU features. After creating the target machine, we can emit +the object file either to a memory buffer or a file.
+ +let machine = LLVMCreateTargetMachine(
+ target,
+ target_triple.cast(),
+ target_cpu.cast(),
+ target_cpu_features.cast(),
+ LLVMCodeGenOptLevel::LLVMCodeGenLevelNone, // opt level
+ LLVMRelocMode::LLVMRelocDynamicNoPic,
+ LLVMCodeModel::LLVMCodeModelDefault,
+);
+
+let mut out_buf: MaybeUninit<LLVMMemoryBufferRef> = MaybeUninit::uninit();
+
+LLVMTargetMachineEmitToMemoryBuffer(
+ machine,
+ llvm_module,
+ LLVMCodeGenFileType::LLVMObjectFile,
+ error_buffer,
+ out_buf.as_mut_ptr(),
+);After emitting the object file, we need to pass it to a linker to get our
+shared library. This is currently done by executing ld, with the proper
+flags to create a shared library on each platform, as a process using a
+temporary file, because it can’t be piped.
graph TD
+ A[MLIR Module using all available dialects]
+ --> |Passes| B[Canonicalized MLIR module using only the LLVM dialect]
+ B --> BB[mlirTranslateModuleToLLVMIR]
+ BB --> C[LLVM IR Module]
+ D[Create LLVM Context] --> BB
+ C --> E[Emit Binary Object]
+ F[Create Target LLVM Machine] --> E
+ E --> |Link the object file| G[Shared Library]
+To load the library, we use the crate libloading, passing it the path to
+our shared library.
Then we initialize the AotNativeExecutor with the loaded library and the
+program registry.
This initialization internally does the following:
+let function_name = format!("_mlir_ciface_{function_name}");libloading
+allows us to have a function signature at compile time to make sure we
+call it properly, but we need to ignore this as we want to call any
+function given the library and the registry.graph TD
+ A[Load library with libloading] --> B[Get the function pointer]
+ C[Generate the target symbol's name] --> B
+ D[Extract the function signature from the program's registry] --> E[Setup the arguments]
+ E --> F[Call the trampoline function]
+ B --> F
+ F --> G[Interpret the results]
+ G --> H[Cleanup and deallocate]
+MLIR has a single canonicalization pass, which iteratively applies the +canonicalization patterns of all loaded dialects in a greedy way. +Canonicalization is best-effort and not guaranteed to bring the entire IR in +a canonical form. It applies patterns until either fix point is reached or +the maximum number of iterations/rewrites (as specified via pass options) is +exhausted. This is for efficiency reasons and to ensure that faulty patterns +cannot cause infinite looping.
+Good read about this: https://sunfishcode.github.io/blog/2018/10/22/Canonicalization.html
+Given the following Cairo program:
+ +// This is the cairo program. It just adds two numbers together and returns the
+// result in an enum whose variant is selected using the result's parity.
+enum Parity<T> {
+ Even: T,
+ Odd: T,
+}
+/// Add `lhs` and `rhs` together and return the result in `Parity::Even` if it's
+/// even or `Parity::Odd` otherwise.
+fn run(lhs: u128, rhs: u128) -> Parity<u128> {
+ let res = lhs + rhs;
+ if (res & 1) == 0 {
+ Parity::Even(res)
+ } else {
+ Parity::Odd(res)
+} }Let’s see how it is executed. We start with the following Rust code:
+ +let program = get_sierra_program(); // The result of the `cairo-compile` program.
+let module = get_native_module(&program); // This compiles the Sierra program to
+ // MLIR (not covered here).Given a compiled Cairo program in an MLIR module, once it is lowered to the LLVM dialect we have two options to execute it: AOT and JIT.
+If we decide to use the JIT executor we just create the jit runner and we’re done.
+ +let program = get_sierra_program();
+let module = get_native_module(&program);
+
+// The optimization level can be `None`, `Less`, `Default` or `Aggressive`. They
+// are equivalent to compiling a C program using `-O0`, `-O1`, `-O2` and `-O3`
+// respectively.
+let engine = JitNativeExecutor::from_native_module(module, OptLevel::Default);Preparing the AOT executor is more complicated since we need to compile it into a shared library and load it from disk.
+ +let program = get_sierra_program();
+let module = get_native_module(&program);
+
+// Internally, this method will run all the steps mentioned before internally into
+// temporary files and return a working `AotNativeExecutor`.
+let engine = AotNativeExecutor::from_native_module(module, OptLevel::Default);You can use caches to keep the compiled programs in memory or disk and reuse them between runs. You may use the ProgramCache type, or alternatively just AotProgramCache or JitProgramCache directly.
Adding programs to the program cache involves steps not covered here, but once they’re inserted you can get executors like this:
+ +let engine = program_cache.get(key).expect("program not found");Regardless of whether we decided to go with AOT or JIT, the program invocation involves the exact same steps. We need to know the entrypoint that we’ll be calling and its arguments.
+In a future we may be able to implement compile-time trampolines for known program signatures, but for now we need to call the invoke_dynamic or invoke_dynamic_with_syscall_handler methods which works with any signature.
++Note: A trampoline is a function that invokes an compiled MLIR function from Rust code.],
+
Now we need to find the function id:
+ +let program = get_sierra_program();
+
+// The utility function needs the symbol of the entry point, which is built as
+// follows:
+// <module-name>::<module-name>::<function-name>(<function-idx>)
+//
+// The `<function-idx>` comes from the Sierra program. It's the index of the
+// function in the function declaration section.
+let function_id = find_function_id(&program, "program::program::main(f0)");The arguments must be placed in a list of JitValue instances. The builtins should be ignored since they are filled in automatically. The only builtins required are the GasBuiltin and System (aka. the syscall handler). They are only mandatory when required by the program itself.
let engine = get_execution_engine(); // This creates the execution engine (covered before).
+
+let args = [
+ JitValue::Uint128(1234),
+ JitValue::Uint128(4321),
+];++Note: Although it’s called
+JitValuefor now, it’s not tied in any way to the JIT engine.JitValues are used for both the AOT and JIT engines.],
Finally we can invoke the program like this:
+ +let engine = get_execution_engine();
+
+let function_id = find_function_id(&program, "program::program::main(f0)");
+let args = [
+ JitValue::Uint128(1234),
+ JitValue::Uint128(4321),
+];
+
+let execution_result = engine.invoke_dynamic(
+ function_id, // The entry point function id.
+ args, // The slice of `JitValue`s.
+ None, // The available gas (if any).
+)?;
+
+// The return value has some useful information about the execution, like:
+// - The remaining gas, if any was supplied.
+// - The program's return value.
+// - The builtin usage statistics. These contain the number of times each builtin has been used.
+println!("Remaining gas: {:?}", execution_result.remaining_gas);
+println!("Return value: {:#?}", execution_result.return_value);
+println!("Builtin stats: {:?}", execution_result.builtin_stats);Running the code above should print the following:
+ +Remaining gas: None
+Return value: Enum {
+ tag: 0,
+ value: Struct {
+ fields: [
+ Enum {
+ tag: 1,
+ value: Uint128(
+ 5555,
+ ),
+ debug_name: Some(
+ "sample::sample::Parity::<core::integer::u128>",
+ ),
+ },
+ ],
+ debug_name: Some(
+ "Tuple<sample::sample::Parity::<core::integer::u128>>",
+ ),
+ },
+ debug_name: Some(
+ "core::panics::PanicResult::<(sample::sample::Parity::<core::integer::u128>,)>",
+ ),
+}
+Builtin stats: BuiltinStats { bitwise: 1, ec_op: 0, range_check: 1, pedersen: 0, poseidon: 0, segment_arena: 0 }Contracts always have the same interface, therefore they have an alternative to invoke_dynamic called invoke_contract_dynamic.
fn(Span<felt252>) -> PanicResult<Span<felt252>>;This wrapper will attempt to deserialize the real contract arguments from the span of felts, invoke the contracts, and finally serialize and return the result. When this deserialization fails, the contract will panic with the mythical Failed to deserialize param #N error.
If the example program had the same interface as a contract (a span of felts) then it’d be invoked like this:
+ +let engine = get_execution_engine();
+
+let function_id = find_function_id(&program, "program::program::main(f0)");
+let args = [
+ Felt::from(1234),
+ Felt::from(4321),
+];
+
+let execution_result = engine.invoke_dynamic(
+ function_id, // The entry point function id.
+ args, // The slice of `JitValue`s.
+ None, // The available gas (if any).
+)?;
+
+// The return value has some useful information about the execution, like:
+// - The remaining gas, if any was supplied.
+// - Whether the contract execution panicked.
+// - The contract's return values.
+// - The builtin usage statistics. These contain the number of times each builtin has been used.
+println!("Remaining gas: {:?}", execution_result.remaining_gas);
+println!("Failure flag: {:?}", execution_result.failure_flag);
+println!("Return value: {:?}", execution_result.return_value);
+println!("Builtin stats: {:?}", execution_result.builtin_stats);Running the code above should print the following:
+Remaining gas: None
+Failure flag: false
+Return value: [
+ JitValue::Felt252(1),
+ JitValue::Felt252(5555),
+]
+Builtin stats: BuiltinStats { bitwise: 1, ec_op: 0, range_check: 1, pedersen: 0, poseidon: 0, segment_arena: 0 }
+Sometimes we need to use stuff that would be too complicated or error-prone to implement in MLIR, but that we have readily available from Rust. That’s when we use the runtime library.
+When using the JIT it’ll be automatically linked (if compiled with support for it, which is enabled by default). If using the AOT, the CAIRO_NATIVE_RUNTIME_LIBDIR environment variable will have to be modified to point to the directory that contains libcairo_native_runtime.a, which is built and placed in said folder by make build.
Although it’s implemented in Rust, its functions use the C ABI and have Rust’s name mangling disabled. This means that to the extern observer it’s technically indistinguishible from a library written in C. By doing this we’re making the functions callable from MLIR.
+The syscall handler is similar to the runtime in the sense that we have C-compatible functions called from MLIR, but it’s different in that they’re built into Cairo Native itself rather than an external library, and that their implementation is user-dependent.
+To allow for user-provided syscall handler implementations we pass a pointer to a vtable every time we detect a System builtin. We need a vtable and cannot use function names because the methods themselves are generic over the syscall handler implementation.
++Note: The
+Systemis used only for syscalls; every syscall has it, therefore it’s a perfect candidate for this use.
Those wrappers then receive a mutable reference to the syscall handler implementation. They are responsible of converting the MLIR-compatible inputs to the Rust representations, calling the implementation, and then converting the results back into MLIR-compatible formats.
+This means that as far as the user is concerned, writing a syscall handler is equivalent to implementing the trait StarknetSyscallHandler for a custom type.
Normally, calling FFI functions in Rust is as easy as defining an extern function using C-compatible types. We can’t do this here because we don’t know the function’s signature.
+It all boils down to the SystemV ABI in x86_64 or its equivalent for ARM. Both of them are really similar:
There’s a few other quirks, like which registers are caller vs callee-saved, but they’re not that relevant in this case.
+Argument location in x86_64:
+| # | Reg. | Description |
+|––|—––|————————|
+| 1 | rdi | A single 64-bit value. |
+| 2 | rsi | A single 64-bit value. |
+| 3 | rdx | A single 64-bit value. |
+| 4 | rcx | A single 64-bit value. |
+| 5 | r8 | A single 64-bit value. |
+| 6 | r9 | A single 64-bit value. |
+| 7+ | Stack | Everything else. |
Argument location in aarch64:
| # | Reg. | Description |
|---|---|---|
| 1 | x0 | A single 64-bit value. |
| 2 | x1 | A single 64-bit value. |
| 3 | x2 | A single 64-bit value. |
| 4 | x3 | A single 64-bit value. |
| 5 | x4 | A single 64-bit value. |
| 6 | x5 | A single 64-bit value. |
| 7 | x6 | A single 64-bit value. |
| 8 | x7 | A single 64-bit value. |
| 9+ | Stack | Everything else. |
Usually function calls have arguments of types other than just 64-bit integers. In those cases, for values smaller than 64 bits the smaller register variants are written. For values larger than 64 bits the value is split into multiple registers, but there’s a catch: if when splitting the value only one value would remain in registers then that register is padded and the entire value goes into the stack. For example, an u128 that would be split between registers and the stack is always padded and written entirely in the stack.
For complex values like structs, the types are flattened into a list of values when written into registers, or just written into the stack the same way they would be written into memory (aka. with the correct alignment, etc).
+As mentioned before, return values may be either returned in registers or memory (most likely the stack, but not necessarily).
+Argument location in x86_64:
| # | Reg | Description |
|---|---|---|
| 1 | rax | A single 64-bit value. |
| 2 | rdx | The “continuation” of rax |
Argument location in aarch64:
| # | Reg | Description |
|---|---|---|
| 1 | x0 | A single 64-bit value |
| 2 | x1 | The “continuation” of x0 |
| 3 | x2 | The “continuation” of x1 |
| 4 | x3 | The “continuation” of x2 |
Values are different that arguments in that only a single value is returned. If more than a single value needs to be returned then it’ll use a pointer.
+When a pointer is involved we need to pass it as the first argument. This means that every actual argument has to be shifted down one slot, pushing more stuff into the stack in the process.
+We cannot really influence what values are in the register or the stack from Rust, therefore we need something written in assembler to put everything into place and invoke the function pointer.
+This is where the trampoline comes in. It’s a simple assembler function that does three things:
+This function always has the same signature, which is C-compatible, and therefore can be used with Rust’s FFI facilities without problems.
+In other words, complex values require a return pointer while simple values do not but may still use multiple registers if they don’t fit within one.
+This section documents how programs generated by Cairo Native keep track of +gas and builtins during execution.
+Gas management in a blockchain environment involves accounting for the amount +of computation performed during the execution of a transaction. This is used +to accurately charge the user at the end of the execution or to revert early +if the transaction consumes more gas than provided by the sender.
+This documentation assumes prior knowledge about Sierra and about the way +gas accounting is performed in Sierra. For those seeking to deepen their +understanding, refer to Enitrat’s Medium post about +Sierra +and greged’s about +gas accounting in Sierra.
+The gas builtin is used in Sierra in order to perform gas accounting. It is
+passed as an input to all function calls and holds the current remaining
+gas. It is represented in MLIR by a simple u128.
The process of calculating gas begins at the very outset of the compilation +process. During the initial setup of the Sierra program, metadata about the +program, including gas information, is extracted. Using gas helper functions +from the Cairo compiler, +the consumed cost (steps, memory holes, builtins usage) for each statement +in the Sierra code is stored in a HashMap.
+The action of withdrawing gas can be split in two steps:
+withdraw_gas libfunc call.The withdraw_gas libfunc takes the current leftover gas as input and uses
+the calculated gas cost for the statement to deduct the appropriate amount
+from the gas builtin. In the compiled IR, gas withdrawal appears as the
+total gas being reduced by a predefined constant. Additionally, the libfunc
+branches based on whether the remaining gas is greater than or equal to the
+amount being withdrawn.
Let’s illustrate this with a simple example using the following Cairo 1 code:
+ +fn run_test() {
+ let mut i: u8 = 0;
+ let mut val = 0;
+ while i < 5 {
+ val = val + i;
+ i = i + 1;
+ }
+}As noted earlier, gas usage is initially computed by the Cairo compiler for +each state. A snippet of the resulting HashMap shows the cost for each +statement:
+...
+(
+ StatementIdx(26),
+ Const,
+): 2680,
+(
+ StatementIdx(26),
+ Pedersen,
+): 0,
+(
+ StatementIdx(26),
+ Poseidon,
+): 0,
+...
+For statement 26, the cost of the Const token type (a combination of step,
+memory hole, and range check costs) is 2680, while other costs are 0.
+Let’s see which libfunc is called at statement 26:
...
+disable_ap_tracking() -> (); // 25
+withdraw_gas([0], [1]) { fallthrough([4], [5]) 84([6], [7]) }; // 26
+branch_align() -> (); // 27
+const_as_immediate<Const<u8, 5>>() -> ([8]); // 28
+...
+When the Cairo native compiler reaches statement 26, it combines all costs
+into gas using the Cairo compiler code. In this example, the total cost is
+2680 gas. This value is used in the withdraw_gas libfunc and the compiled
+corresponding IR to withdraw the gas and determine whether execution should
+revert or continue. This can be observed in the following MLIR dump:
llvm.func @"test::test::run_test[expr16](f0)"(%arg0: i64 loc(unknown), %arg1: i128 loc(unknown), %arg2: i8 loc(unknown), %arg3: i8 loc(unknown)) -> !llvm.struct<(i64, i128, struct<(i64, array<24 x i8>)>)> attributes {llvm.emit_c_interface} {
+ ...
+ %12 = llvm.mlir.constant(5 : i8) : i8 loc(#loc1)
+ %13 = llvm.mlir.constant(2680 : i128) : i128 loc(#loc1)
+ %14 = llvm.mlir.constant(1 : i64) : i64 loc(#loc1)
+ ...
+ ^bb1(%27: i64 loc(unknown), %28: i128 loc(unknown), %29: i8 loc(unknown), %30: i8 loc(unknown)): // 2 preds: ^bb0, ^bb6
+ %31 = llvm.add %27, %14 : i64 loc(#loc13)
+ %32 = llvm.icmp "uge" %28, %13 : i128 loc(#loc13)
+ %33 = llvm.intr.usub.sat(%28, %13) : (i128, i128) -> i128 loc(#loc13)
+ llvm.cond_br %32, ^bb2(%29 : i8), ^bb7(%5, %23, %23, %31 : i252, !llvm.ptr, !llvm.ptr, i64) loc(#loc13)
+ ...
+Here, we see the constant 2680 defined at the begining of the function.
+In basic block 1, the withdraw_gas operations are performed: by comparing
+%28 (remaining gas) and %13 (gas cost), the result stored in %32
+determines the conditional branching. A saturating subtraction between the
+remaining gas and the gas cost is then performed, updating the remaining gas
+in the IR.
The final gas usage can be easily retrieved from the gas builtin value +returned by the function. This is accomplished when +parsing the return values +from the function call:
+ +...
+for type_id in &function_signature.ret_types {
+ let type_info = registry.get_type(type_id).unwrap();
+ match type_info {
+ CoreTypeConcrete::GasBuiltin(_) => {
+ remaining_gas = Some(match &mut return_ptr {
+ Some(return_ptr) => unsafe { *read_value::<u128>(return_ptr) },
+ None => {
+ // If there's no return ptr then the function only returned the gas. We don't
+ // need to bother with the syscall handler builtin.
+ ((ret_registers[1] as u128) << 64) | ret_registers[0] as u128
+ }
+ });
+ }
+ ...
+ }
+ ...
+}
+...This code snippet extracts the remaining gas from the return pointer based +on the function’s signature. If the function only returns the gas value, +the absence of a return pointer is handled appropriately, ensuring accurate +gas accounting.
+The Cairo Native compiler records the usage of each builtins in order to +provide information about the program’s builtins consumption. +This information is NOT used for the gas calculation, as the gas cost of +builtins is already taken into account during the gas accounting process. +The builtins counter types can each be found in the types folder. +Taking the Pedersen hash as an example, we see +that the counters will be represented as i64 integers in MLIR. +Counters are then simply incremented by one each time the builtins are +called from within the program.
+Let us consider the following Cairo program which uses the pedersen builtin:
use core::integer::bitwise;
+use core::pedersen::pedersen;
+
+fn run_test() {
+ let mut hash = pedersen(1.into(), 2.into());
+ hash += 1;
+}We expect Native to increment the pedersen counter by 1 given the above code.
+Let’s first check how this compiles to Sierra:
const_as_immediate<Const<felt252, 1>>() -> ([1]); // 0
+const_as_immediate<Const<felt252, 2>>() -> ([2]); // 1
+store_temp<felt252>([1]) -> ([1]); // 2
+store_temp<felt252>([2]) -> ([2]); // 3
+pedersen([0], [1], [2]) -> ([3], [4]); // 4
+drop<felt252>([4]) -> (); // 5
+store_temp<Pedersen>([3]) -> ([3]); // 6
+return([3]); // 7
+
+contracts::run_test@0([0]: Pedersen) -> (Pedersen);
+In the compiled Sierra, we can see that the pedersen builtin is passed
+with the call to the run_test which starts at statement 0. It is then
+used in the call to the pedersen libfunc. We would expect to see the
+pedersen counter incremented by 1 in the Native compiler. Below is the
+compiled MLIR dump for the same program:
...
+llvm.func @"test::test::run_test(f0)"(%arg0: i64 loc(unknown)) -> i64 attributes {llvm.emit_c_interface} {
+ %0 = llvm.mlir.constant(2 : i256) : i256 loc(#loc1)
+ %1 = llvm.mlir.constant(1 : i256) : i256 loc(#loc1)
+ %2 = llvm.mlir.constant(1 : i64) : i64 loc(#loc1)
+ %3 = llvm.alloca %2 x i256 {alignment = 16 : i64} : (i64) -> !llvm.ptr loc(#loc2)
+ %4 = llvm.alloca %2 x i256 {alignment = 16 : i64} : (i64) -> !llvm.ptr loc(#loc2)
+ %5 = llvm.alloca %2 x i256 {alignment = 16 : i64} : (i64) -> !llvm.ptr loc(#loc2)
+ %6 = llvm.add %arg0, %2 : i64 loc(#loc2)
+ %7 = llvm.intr.bswap(%1) : (i256) -> i256 loc(#loc2)
+ %8 = llvm.intr.bswap(%0) : (i256) -> i256 loc(#loc2)
+ llvm.store %7, %3 {alignment = 16 : i64} : i256, !llvm.ptr loc(#loc2)
+ llvm.store %8, %4 {alignment = 16 : i64} : i256, !llvm.ptr loc(#loc2)
+ llvm.call @cairo_native__libfunc__pedersen(%5, %3, %4) : (!llvm.ptr, !llvm.ptr, !llvm.ptr) -> () loc(#loc2)
+ llvm.return %6 : i64 loc(#loc3)
+ } loc(#loc1)
+ ...
+The compiled MLIR function run_test takes a single argument as input, the
+pedersen counter and returns the incremented counter at the end of the call.
+The counter is incremented by 1 in the MLIR code, in the statement
+%6 = llvm.add %arg0, %2 : i64 loc(#loc2), which takes the %arg0 input
+and adds %2 to it. We can see from statement
+%2 = llvm.mlir.constant(1 : i64) : i64 loc(#loc1) that %2 holds the
+constant 1.
+When this compiled MLIR code is called, the initial value of all builtin
+counters is set to 0 as can be seen in the
+invoke_dynamic function.
🚧 WIP
+A libfunc usually works with a type, such as felt252. The compiler
+needs to have information on this type, such as its layout and size.
+This is defined in src/types.rs and src/types/{typename}.rs.
On each src/types/{typename}.rs such as src/types/felt252.rs you will
+find a build function, this has all the necessary arguments to generate
+the proper type and return a MLIR type, such as
+IntegerType::new(context, 252) (a 252 bit integer).
In src/types.rs we need to declare the type layout, for example the
+felt252 would have the layout returned by get_integer_layout(252).
+A type that doesn’t have size would be Layout::new::<()>(), or if the
+type is a pointer like box: Layout::new::<*mut ()>()
When adding a type, we also need to add the serialization and +deserialization functionality, so we can use it with the JIT runner.
+You can find this functionality under src/values.rs and
+src/values/{typename}.rs. As you can see, the project is quite organized
+if you have a feel of its layout.
Serialization is done using Serde, and each type provides a deserialize
+and serialize function. The inner workings of such functions can be a bit
+complex due to how the JIT runner works. You need to work with pointers and
+unsafe rust.
In values.rs we should also declare whether the type is complex under
+is_complex in the ValueBuilder trait implementation.
++Complex types are always passed by pointer (both as params and return +values) and require a stack allocation. Examples of complex values include +structs and enums, but not felts since LLVM considers them integers.
+
When deserializing (a.k.a converting the inputs so the JIT runner
+accepts them), you are passed a bump allocator arena from Bumpalo, the
+general idea is to get the layout and size of the type, allocate it under
+the arena, get a pointer, and return it. Which will later be passed to the
+MLIR JIT runner. It is important the pointers passed are allocated by the
+arena and not Rust itself.
Then we need to hookup de deserialize method in values.rs deserialize
+method.
When serializing a type, you will get a ptr: NonNull<()> (non null
+pointer), which you will have to cast, dereference and then deserialize.
For a simple type to learn how it works, we recommend checking
+src/values/uint8.rs, for more complex types, check src/values/felt252.rs.
+The hardest types to understand are the enums, dictionaries and arrays,
+since they are complex types.
Then we need to hookup de serialize method in values.rs serialize method.
Libfuncs are implemented under src/libfuncs.rs and
+src/libfuncs/{libfunc_name}.rs. Just like types.
Using the src/libfuncs/felt252.rs libfuncs as a aid:
/// Select and call the correct libfunc builder function from the selector.
+pub fn build<'ctx, 'this, TType, TLibfunc>(
+ context: &'ctx Context,
+ registry: &ProgramRegistry<TType, TLibfunc>,
+ entry: &'this Block<'ctx>,
+ location: Location<'ctx>,
+ helper: &LibfuncHelper<'ctx, 'this>,
+ metadata: &mut MetadataStorage,
+ selector: &Felt252Concrete,
+) -> Result<()>
+where
+ TType: GenericType,
+ TLibfunc: GenericLibfunc,
+ <TType as GenericType>::Concrete: TypeBuilder<TType, TLibfunc, Error = CoreTypeBuilderError>,
+ <TLibfunc as GenericLibfunc>::Concrete: LibfuncBuilder<TType, TLibfunc, Error = Error>,
+{
+ match selector {
+ Felt252Concrete::BinaryOperation(info) => {
+ build_binary_operation(context, registry, entry, location, helper, metadata, info)
+ }
+ Felt252Concrete::Const(info) => {
+ build_const(context, registry, entry, location, helper, metadata, info)
+ }
+ Felt252Concrete::IsZero(info) => {
+ build_is_zero(context, registry, entry, location, helper, metadata, info)
+ }
+ }
+}You can see it also defines a build function, in this case the last method +is a selector, this means in this case we have a group of related libfuncs, +which we will implement in this same file. This is where calls to melior +(MLIR) and most MLIR code is located, where one gets their hands dirty.
+After implementing the libfuncs, we need to hookup the build method in
+the src/libfuncs.rs match statement.
An example libfunc, converting a u8 to a felt252, extensively commented:
+ +/// Generate MLIR operations for the `u8_to_felt252` libfunc.
+pub fn build_to_felt252<'ctx, 'this, TType, TLibfunc>(
+ // The Context from MLIR, this is like the heart of the MLIR API, its required to create most stuff like types.
+ context: &'ctx Context,
+ // This is the sierra program registry, it aids us at finding types, functions, etc.
+ registry: &ProgramRegistry<TType, TLibfunc>,
+ // This is the MLIR entry block for this libfunc. Remember we append operations to blocks.
+ entry: &'this Block<'ctx>,
+ // The already created MLIR location for this libfunc, we need to pass this to all the MLIR operations.
+ location: Location<'ctx>,
+ // A helper, which also works as a MLIR Module, it has useful functions for stuff like branching to other libfuncs.
+ helper: &LibfuncHelper<'ctx, 'this>,
+ // The metadata storage, contains extra information needed on some libfuncs. Check out `src/metadata.rs` to learn how it works.
+ metadata: &mut MetadataStorage,
+ // The sierra information for this specific library function. This libfunc only contains signature information, but
+ // others which are generic over a type will contain information about that type, for example array related libfuncs.
+ info: &SignatureOnlyConcreteLibfunc,
+) -> Result<()>
+where
+ TType: GenericType,
+ TLibfunc: GenericLibfunc,
+ <TType as GenericType>::Concrete: TypeBuilder<TType, TLibfunc, Error = CoreTypeBuilderError>,
+ <TLibfunc as GenericLibfunc>::Concrete: LibfuncBuilder<TType, TLibfunc, Error = Error>,
+{
+ // We retrieve the felt252 type from the registry and call the "build" method to create the MLIR type.
+ // We could also just call get_type() to hold on to the sierra type, and then `.layout(registry)` to get the type layout,
+ // which is needed in some libfuncs doing more complex stuff.
+ let felt252_ty = registry
+ .get_type(&info.branch_signatures()[0].vars[0].ty)?
+ .build(context, helper, registry, metadata)?;
+
+ // Retrieve the first argument passed to this library function, in this case its the u8 value we need to convert.
+ let value: Value = entry.argument(0)?.into();
+
+ // We create a "extui" operation from the "arith" dialect, which basically zero extends the value to have the same bits as the given type.
+ let op = entry.append_operation(arith::extui(value, felt252_ty, location));
+
+ // Get the result from the operation, in this case it's the extended value
+ let result = op.result(0)?.into();
+
+ // Using the helper argument, append the branching operation to the next statement, passing result as our output variable.
+ entry.append_operation(helper.br(0, &[result], location));
+
+ Ok(())
+}More info on the extui operation: https://mlir.llvm.org/docs/Dialects/ArithOps/#arithextui-arithextuiop
These 2 env vars will dump the generated MLIR code from any compilation on the current working directory as:
+dump.mlir: The MLIR code after passes without locations.dump-debug.mlir: The MLIR code after passes with locations.dump-prepass.mlir: The MLIR code before without locations.dump-prepass-debug.mlir: The MLIR code before passes with locations.Do note that the MLIR with locations is in pretty form and thus not suitable to pass to mlir-opt.
export NATIVE_DEBUG_DUMP_PREPASS=1
+export NATIVE_DEBUG_DUMP=1
+To debug with LLDB (or another debugger), we must compile the binary with the with-debug-utils feature.
cargo build --bin cairo-native-run --features with-debug-utils
+Then, we can add the a debugger breakpoint trap. To add it at a given sierra statement, we can set the following env var:
+export NATIVE_DEBUG_TRAP_AT_STMT=10
+The trap instruction may not end up exactly where the statement is.
+If we want to manually set the breakpoint (for example, when executing a particular libfunc), then we can use the DebugUtils metadata in the code.
#[cfg(feature = "with-debug-utils")]
+{
+ metadata.get_mut::<DebugUtils>()
+ .unwrap()
+ .debug_breakpoint_trap(block, location)?;
+}Now, we need to execute cairo-native-run from our debugger (LLDB). If we want to see the source locations, we also need to set the NATIVE_DEBUG_DUMP env var and execute the program with AOT.
lldb -- target/debug/cairo-native-run -s programs/recursion.cairo --available-gas 99999999 --run-mode aot
+Some usefull lldb commands:
+process launch: starts the programframe select: shows the current line informationthread step-in: makes a source level single stepthread continue: continues execution of the current processdisassemble --frame --mixed: shows assembly instructions mixed with source level codeEnable logging to see the compilation process:
+export RUST_LOG="cairo_native=trace"
+debug_utils print utilities, more info here:#[cfg(feature = "with-debug-utils")]
+{
+ metadata.get_mut::<DebugUtils>()
+ .unwrap()
+ .print_pointer(context, helper, entry, ptr, location)?;
+}Contracts are difficult to debug for various reasons, including:
+Some of them have workarounds:
+There are various options for obtaining the contract, which include:
+curl with the contract class.Example:
+curl --location --request POST 'https://mainnet.juno.internal.lambdaclass.com' \
+--header 'Content-Type: application/json' \
+--data-raw '{
+ "jsonrpc": "2.0",
+ "method": "starknet_getClass",
+ "id": 0,
+ "params": {
+ "class_hash": "0x036078334509b514626504edc9fb252328d1a240e4e948bef8d0c08dff45927f",
+ "block_id": 657887
+}
+}'
+Both should provide us with the contract, but if we’re manually invoking the API we’ll need to process the JSON a bit to:
+The contract JSON contains the Sierra program in a useless form (in the sense +that we cannot understand anything), as well as some information about the +entry points and some ABI types. We’ll need the Sierra program (in Sierra +format, not the JSON) to be able to understand what should be happening.
+We can use the starknet-sierra-extract-code binary, which can be found in
+the cairo project when compiled from source (not in the binary distribution).
+That binary will extract the Sierra program without any debug information,
+which is still not very useful.
Once we have the Sierra we can run the +Sierra mapper to autogenerate +some type, libfunc and function names so that we know what we’re looking at +without losing our mind. The Sierra mapper can be run multiple times, adding +more names manually as the user sees fit.
+First of all we need to know which contract is actually failing. Most +of the time the contract where it crashes isn’t the transaction’s class +hash, but a chain of contract/library calls.
+To know which contract is being called we can add some debugging prints in +the replay that logs contract executions. For example:
+ +impl StarknetSyscallHandler for ReplaySyscallHandler {
+ // ...
+
+ fn library_call(
+ &mut self,
+ class_hash: Felt,
+ function_selector: Felt,
+ calldata: &[Felt],
+ remaining_gas: &mut u128,
+ ) -> SyscallResult<Vec<Felt>> {
+ // ...
+
+ println!("Starting execution of contract {class_hash} on selector {function_selector} with calldata {calldata:?}.");
+ let result = executor.invoke_contract_dynamic(...);
+ println!("Finished execution of contract {class_hash}.");
+ if result.failure_flag {
+ println!("Execution of contract {class_hash} failed.");
+ }
+
+ // ...
+ }
+
+ fn call_contract(
+ &mut self,
+ address: Felt,
+ entry_point_selector: Felt,
+ calldata: &[Felt],
+ remaining_gas: &mut u128,
+ ) -> SyscallResult<Vec<Felt>> {
+ // ...
+
+ println!("Starting execution of contract {class_hash} on selector {function_selector} with calldata {calldata:?}.");
+ let result = executor.invoke_contract_dynamic(...);
+ println!("Finished execution of contract {class_hash}.");
+ if result.failure_flag {
+ println!("Execution of contract {class_hash} failed.");
+ }
+
+ // ...
+ }
+}If we run something like the above then the +replay should start +printing the log of what’s actually being executed and where it crashes. +It may print multiple times the error message, but only the first one is +the relevant one (the others should be the contract call chain in reverse +order). Once we know which contract is being called and its calldata we can +download and extract its Sierra as detailed above.
+We then need to know where it fails within the contract. To do that we
+can look at the error message and deduce where it’s used based on the Sierra
+program. For example, the error message u256_mul overflow is felt-encoded
+as 0x753235365f6d756c206f766572666c6f77, or
+39879774624083218221774975706286902767479 in decimal. If we look for
+usages of that specific value we’ll most likely find all the places where
+that error can be thrown. Now we just need to narrow them down to a single
+one and we’ll be able to actually start debugging.
An idea on how to do that is modifying Cairo native so that it adds a +breakpoint every time a constant with that error message is generated. +For example:
+ +/// Generate MLIR operations for the `felt252_const` libfunc.
+pub fn build_const<'ctx, 'this>(
+ context: &'ctx Context,
+ registry: &ProgramRegistry<CoreType, CoreLibfunc>,
+ entry: &'this Block<'ctx>,
+ location: Location<'ctx>,
+ helper: &LibfuncHelper<'ctx, 'this>,
+ metadata: &mut MetadataStorage,
+ info: &Felt252ConstConcreteLibfunc,
+) -> Result<()> {
+ let value = match info.c.sign() {
+ Sign::Minus => {
+ let prime = metadata
+ .get::<PrimeModuloMeta<Felt>>()
+ .ok_or(Error::MissingMetadata)?
+ .prime();
+ (&info.c + prime.to_bigint().expect("always is Some"))
+ .to_biguint()
+ .expect("always is positive")
+ }
+ _ => info.c.to_biguint().expect("sign already checked"),
+ };
+ let felt252_ty = registry.build_type(
+ context,
+ helper,
+ registry,
+ metadata,
+ &info.branch_signatures()[0].vars[0].ty,
+ )?;
+ if value == "39879774624083218221774975706286902767479".parse().unwrap() {
+ // If using the debugger:
+ metadata
+ .get_mut::<crate::metadata::debug_utils::DebugUtils>()
+ .unwrap()
+ .debug_breakpoint_trap(entry, location)
+ .unwrap();
+ // If not using the debugger (not tested, may not provide useful information).
+ metadata
+ .get_mut::<crate::metadata::debug_utils::DebugUtils>()
+ .unwrap()
+ .debug_print(
+ context,
+ helper,
+ entry,
+ &format!("Invoked felt252_const<error_msg> at {location}."),
+ location,
+ )
+ .unwrap();
+ }
+ let value = entry.const_int_from_type(context, location, value, felt252_ty)?;
+ entry.append_operation(helper.br(0, &[value], location));
+ Ok(())
+}Using the debugger will also provide the internal call backtrace (of the +contract) and register values, so it’s the recommended way, but depending on +the contract it may not be feasible (ex. the contract is too big and running +the debugger is not practical due to the amount of time it takes to get to +the crash).
+Once we know exactly where it crashes we can follow the control flow of the +Sierra program backwards and discover how it reached that point.
+In some cases the problem may be somewhere completely different from where
+the error is thrown. In other words, the error we’re seeing may be a side
+effect of a completely different bug. For example, in a u256_mul overflow,
+the bug may be found in the mul operation implementation, or alternatively it
+may just be that the values passed to it are not what they should be. That’s
+why it’s important to check for those cases and keep following the control
+flow backwards as required.
Before fixing the bug it’s really important to know:
+u64_sqrt, could the same bug happen in u32_sqrt and others?)The last one is really important since we don’t want to cause more bugs +fixing the ones we already have. To understand the side effects we need to +have a full understanding of the bug, which implies having an answer to (at +least) all the other things to know before fixing it.
+Once we know all that we can:
+++Note: Those steps must be done in that order. Otherwise we risk +unconsciously avoiding bugs in our tests for our bug fix implementation by +building our tests from our implementation instead of the correct +behaviour.
+
🚧 TODO
+Sierra uses a list of builtin functions that implement the language +functionality, those are called library functions, short: libfuncs. +Basically every statement in a sierra program is a call to a libfunc, thus +they are the core of Cairo Native.
+Each libfunc takes input variables and outputs some other variables. Note
+that in cairo a function that has 2 arguments may have more in sierra, due
+to “implicits” / “builtins”, which are arguments passed hidden from the
+user, such as the GasBuiltin.
MLIR is composed of dialects, which is like a IR of it’s own, and this +IR can be converted to another dialect IR (if the functionality exists). +This is what makes MLIR shine.
+Some commonly used dialects in this project:
+addi, subi for addition and subtraction.br and cond_br, which are unconditional and conditional jumps.The MLIR IR is composed recursively like this: Operation -> Region -> Block -> Operations
Each operation has 1 or more region, each region has 1 or more blocks, each +block has 1 or more operations.
+This way a MLIR program can be composed.
+MLIR provides a set of transformations that can optimize the IR.
+Such as canonicalize.
Check out https://mlir.llvm.org/docs/Canonicalization/ and https://mlir.llvm.org/docs/Passes/.
+In our case, llvm is our target, so we end up translating all dialects down +to the LLVM dialect, which then gets converted to LLVM IR.
+Resources marked with → are best.
+raviqqe/meliorfemtomc/mlir-sys Rust bindings to the MLIR C API.GetFirefly/firefly An alternative BEAM implementation, designed for WebAssembly.Optimization levels.
-Starknet contract execution result.
-remaining_gas: u128§failure_flag: bool§return_values: Vec<Felt>§error_msg: Option<String>Convert a [ExecuteResult] to a [NativeExecutionResult]
remaining_gas: u128§failure_flag: bool§return_values: Vec<Felt>§error_msg: Option<String>Convert an ExecutionResult into a ContractExecutionResult
source. Read morepub struct JitNativeExecutor<'m> { /* private fields */ }A MLIR JIT execution engine in the context of Cairo Native.
-Execute a program with the given params.
-See [cairo_native::jit_runner::execute]
Execute a program with the given params.
-See [cairo_native::jit_runner::execute]
This crate is a compiler and JIT engine that transforms Sierra (or Cairo) sources into MLIR, -which can be JIT-executed or further -compiled into a binary -ahead of time.
-The API contains two structs, NativeContext and NativeExecutor.
-The main purpose of NativeContext is MLIR initialization, compilation and lowering to LLVM.
-NativeExecutor in the other hand is responsible of executing MLIR compiled sierra programs
-from an entrypoint.
-Programs and JIT states can be cached in contexts where their execution will be done multiple
-times.
use starknet_types_core::felt::Felt;
-use cairo_native::context::NativeContext;
-use cairo_native::executor::JitNativeExecutor;
-use cairo_native::values::JitValue;
-use std::path::Path;
-
-let program_path = Path::new("programs/examples/hello.cairo");
-// Compile the cairo program to sierra.
-let sierra_program = cairo_native::utils::cairo_to_sierra(program_path);
-
-// Instantiate a Cairo Native MLIR context. This data structure is responsible for the MLIR
-// initialization and compilation of sierra programs into a MLIR module.
-let native_context = NativeContext::new();
-
-// Compile the sierra program into a MLIR module.
-let native_program = native_context.compile(&sierra_program).unwrap();
-
-// The parameters of the entry point.
-let params = &[JitValue::Felt252(Felt::from_bytes_be_slice(b"user"))];
-
-// Find the entry point id by its name.
-let entry_point = "hello::hello::greet";
-let entry_point_id = cairo_native::utils::find_function_id(&sierra_program, entry_point);
-
-// Instantiate the executor.
-let native_executor = JitNativeExecutor::from_native_module(native_program, Default::default());
-
-// Execute the program.
-let result = native_executor
- .invoke_dynamic(entry_point_id, params, None)
- .unwrap();
-
-println!("Cairo program was compiled and executed successfully.");
-println!("{:?}", result);Within this project there are lots of functions with the same signature. As their arguments have -all the same meaning, they are documented here:
+A compiler to convert Cairo’s intermediate representation “Sierra” code
+to machine code via MLIR and LLVM.
+
context: NativeContext: The MLIR context.module: &NativeModule: The compiled MLIR program, with other relevant information such as program registry and metadata.program: &Program: The Sierra input program.registry: &ProgramRegistry<TType, TLibfunc>: The registry extracted from the program.metadata: &mut MetadataStorage: Current compiler metadata.For in-depth documentation, see the developer documentation.
+🚧 Cairo Native is still being built therefore API breaking changes might happen +often so use it at your own risk. 🚧
+For versions under 1.0 cargo doesn’t comply with
+semver, so we advise to pin the version the version you
+use. This can be done by adding cairo-native = "0.1.0" to your Cargo.toml
++This step applies to all operating systems.
+
Run the following make target to install the dependencies (both Linux and macOS):
+make deps
+Since Linux distributions change widely, you need to install LLVM 18 via your +package manager, compile it or check if the current release has a Linux binary.
+If you are on Debian/Ubuntu, check out the repository https://apt.llvm.org/ +Then you can install with:
+sudo apt-get install llvm-18 llvm-18-dev llvm-18-runtime clang-18 clang-tools-18 lld-18 libpolly-18-dev libmlir-18-dev mlir-18-tools
+If you decide to build from source, here are some indications:
+# Go to https://github.com/llvm/llvm-project/releases
+# Download the latest LLVM 18 release:
+# The blob to download is called llvm-project-18.x.x.src.tar.xz
+
+# For example
+wget https://github.com/llvm/llvm-project/releases/download/llvmorg-18.1.7/llvm-project-18.1.7.src.tar.xz
+tar xf llvm-project-18.1.7.src.tar.xz
+
+cd llvm-project-18.1.7.src.tar
+mkdir build
+cd build
+
+# The following cmake command configures the build to be installed to /opt/llvm-18
+cmake -G Ninja ../llvm \
+ -DLLVM_ENABLE_PROJECTS="mlir;clang;clang-tools-extra;lld;polly" \
+ -DLLVM_BUILD_EXAMPLES=OFF \
+ -DLLVM_TARGETS_TO_BUILD="Native" \
+ -DCMAKE_INSTALL_PREFIX=/opt/llvm-18 \
+ -DCMAKE_BUILD_TYPE=RelWithDebInfo \
+ -DLLVM_PARALLEL_LINK_JOBS=4 \
+ -DLLVM_ENABLE_BINDINGS=OFF \
+ -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++ -DLLVM_ENABLE_LLD=ON \
+ -DLLVM_ENABLE_ASSERTIONS=OFF
+
+ninja install
+Setup a environment variable called MLIR_SYS_180_PREFIX, LLVM_SYS_181_PREFIX
+and TABLEGEN_180_PREFIX pointing to the llvm directory:
# For Debian/Ubuntu using the repository, the path will be /usr/lib/llvm-18
+export MLIR_SYS_180_PREFIX=/usr/lib/llvm-18
+export LLVM_SYS_181_PREFIX=/usr/lib/llvm-18
+export TABLEGEN_180_PREFIX=/usr/lib/llvm-18
+Alternatively, if installed from Debian/Ubuntu repository, then you can use
+env.sh to automatically setup the environment variables.
source env.sh
+The makefile deps target (which you should have ran before) installs LLVM 18
+with brew for you, afterwards you need to execute the env.sh script to setup
+the needed environment variables.
source env.sh
+Running make by itself will check whether the required LLVM installation and
+corelib is found, and then list available targets.
% make
+LLVM is correctly set at /opt/homebrew/opt/llvm.
+./scripts/check-corelib-version.sh 2.6.4
+Usage:
+ deps: Installs the necesary dependencies.
+ build: Builds the cairo-native library and binaries in release mode.
+ build-native: Builds cairo-native with the target-cpu=native rust flag.
+ build-dev: Builds cairo-native under a development-optimized profile.
+ runtime: Builds the runtime library required for AOT compilation.
+ check: Checks format and lints.
+ test: Runs all tests.
+ proptest: Runs property tests.
+ coverage: Runs all tests and computes test coverage.
+ doc: Builds documentation.
+ doc-open: Builds and opens documentation in browser.
+ bench: Runs the hyperfine benchmark script.
+ bench-ci: Runs the criterion benchmarks for CI.
+ install: Invokes cargo to install the cairo-native tools.
+ clean: Cleans the built artifacts.
+ stress-test Runs a command which runs stress tests.
+ stress-plot Plots the results of the stress test command.
+ stress-clean Clean the cache of AOT compiled code of the stress test command.
+Aside from the compilation and execution engine library, Cairo Native includes +a few command-line tools to aid development, and some useful scripts.
+These are:
+/scripts/ foldercairo-native-compilecairo-native-dumpcairo-native-runcairo-native-testcairo-native-stressscarb-native-dumpscarb-native-testcairo-native-compileCompiles a Cairo project outputting the generated MLIR and the shared library.
+Exits with 1 if the compilation or run fails, otherwise 0.
+
+Usage: cairo-native-compile [OPTIONS] <PATH> [OUTPUT_MLIR] [OUTPUT_LIBRARY]
+
+Arguments:
+ <PATH> The Cairo project path to compile and run its tests
+ [OUTPUT_MLIR] The output path for the mlir, if none is passed, out.mlir will be the default
+ [OUTPUT_LIBRARY] If a path is passed, a dynamic library will be compiled and saved at that path
+
+Options:
+ -s, --single-file Whether path is a single file
+ --allow-warnings Allows the compilation to succeed with warnings
+ -r, --replace-ids Replaces sierra ids with human-readable ones
+ -O, --opt-level <OPT_LEVEL> Optimization level, Valid: 0, 1, 2, 3. Values higher than 3 are considered as 3 [default: 0]
+ -h, --help Print help
+ -V, --version Print version
+cairo-native-dumpUsage: cairo-native-dump [OPTIONS] <INPUT>
+
+Arguments:
+ <INPUT>
+
+Options:
+ -o, --output <OUTPUT> [default: -]
+ --starknet Compile a starknet contract
+ -h, --help Print help
+cairo-native-runThis tool allows to run programs using the JIT engine, like the cairo-run
+tool, the parameters can only be felt values.
Example: echo '1' | cairo-native-run 'program.cairo' 'program::program::main' --inputs - --outputs -
Exits with 1 if the compilation or run fails, otherwise 0.
+
+Usage: cairo-native-run [OPTIONS] <PATH>
+
+Arguments:
+ <PATH> The Cairo project path to compile and run its tests
+
+Options:
+ -s, --single-file Whether path is a single file
+ --allow-warnings Allows the compilation to succeed with warnings
+ --available-gas <AVAILABLE_GAS> In cases where gas is available, the amount of provided gas
+ --run-mode <RUN_MODE> Run with JIT or AOT (compiled) [default: jit] [possible values: aot, jit]
+ -O, --opt-level <OPT_LEVEL> Optimization level, Valid: 0, 1, 2, 3. Values higher than 3 are considered as 3 [default: 0]
+ -h, --help Print help
+ -V, --version Print version
+cairo-native-testThis tool mimics the cairo-test
+tool
+and is identical to it in interface, the only feature it doesn’t have is the profiler.
Compiles a Cairo project and runs all the functions marked as `#[test]`.
+Exits with 1 if the compilation or run fails, otherwise 0.
+
+Usage: cairo-native-test [OPTIONS] <PATH>
+
+Arguments:
+ <PATH> The Cairo project path to compile and run its tests
+
+Options:
+ -s, --single-file Whether path is a single file
+ --allow-warnings Allows the compilation to succeed with warnings
+ -f, --filter <FILTER> The filter for the tests, running only tests containing the filter string [default: ]
+ --include-ignored Should we run ignored tests as well
+ --ignored Should we run only the ignored tests
+ --starknet Should we add the starknet plugin to run the tests
+ --run-mode <RUN_MODE> Run with JIT or AOT (compiled) [default: jit] [possible values: aot, jit]
+ -O, --opt-level <OPT_LEVEL> Optimization level, Valid: 0, 1, 2, 3. Values higher than 3 are considered as 3 [default: 0]
+ -h, --help Print help
+ -V, --version Print version
+For single files, you can use the -s, --single-file option.
For a project, it needs to have a cairo_project.toml specifying the
+crate_roots. You can find an example under the cairo-tests/ folder, which
+is a cairo project that works with this tool.
cairo-native-test -s myfile.cairo
+
+cairo-native-test ./cairo-tests/
+This will run all the tests (functions marked with the #[test] attribute).
cairo-native-stressThis tool runs a stress test on Cairo Native.
+A stress tester for Cairo Native
+
+It compiles Sierra programs with Cairo Native, caches, and executes them with AOT runner. The compiled dynamic libraries are stored in `AOT_CACHE_DIR` relative to the current working directory.
+
+Usage: cairo-native-stress [OPTIONS] <ROUNDS>
+
+Arguments:
+ <ROUNDS>
+ Amount of rounds to execute
+
+Options:
+ -o, --output <OUTPUT>
+ Output file for JSON formatted logs
+
+ -h, --help
+ Print help (see a summary with '-h')
+To quickly run a stress test and save logs as json, run:
+make stress-test
+This takes a lot of time to finish (it will probably crash first), you can kill +the program at any time.
+To plot the results, run:
+make stress-plot
+To clear the cache directory, run:
+make stress-clean
+scarb-native-dumpThis tool mimics the scarb build command.
+You can download it on our releases page.
This tool should be run at the directory where a Scarb.toml file is and it will
+behave like scarb build, leaving the MLIR files under the target/ folder
+besides the generated JSON sierra files.
scarb-native-testThis tool mimics the scarb test command.
+You can download it on our releases page.
Compiles all packages from a Scarb project matching `packages_filter` and
+runs all functions marked with `#[test]`. Exits with 1 if the compilation
+or run fails, otherwise 0.
+
+Usage: scarb-native-test [OPTIONS]
+
+Options:
+ -p, --package <SPEC> Packages to run this command on, can be a concrete package name (`foobar`) or a prefix glob (`foo*`) [env: SCARB_PACKAGES_FILTER=] [default: *]
+ -w, --workspace Run for all packages in the workspace
+ -f, --filter <FILTER> Run only tests whose name contain FILTER [default: ]
+ --include-ignored Run ignored and not ignored tests
+ --ignored Run only ignored tests
+ --run-mode <RUN_MODE> Run with JIT or AOT (compiled) [default: jit] [possible values: aot, jit]
+ -O, --opt-level <OPT_LEVEL> Optimization level, Valid: 0, 1, 2, 3. Values higher than 3 are considered as 3 [default: 0]
+ -h, --help Print help
+ -V, --version Print version
+cargo install hyperfine src
- ├─ context.rs - The MLIR context wrapper, provides the compile method.
- ├─ utils.rs - Internal utilities.
- ├─ metadata/ - Metadata injector to use within the compilation process
- ├─ executor/ - Code related to the executor of programs.
- ├─ module.rs - The MLIR module wrapper.
- ├─ arch/ - Trampoline assembly for calling functions with dynamic signatures.
- ├─ executor.rs - The executor code.
- ├─ ffi.cpp - Missing FFI C wrappers
- ├─ libfuncs - Cairo Sierra libfunc implementations
- ├─ libfuncs.rs - Cairo Sierra libfunc glue code
- ├─ starknet.rs - Starknet syscall handler glue code.
- ├─ ffi.rs - Missing FFI C wrappers, rust side.
- ├─ block_ext.rs - A melior (MLIR) block trait extension to write less code.
- ├─ lib.rs - The main lib file.
- ├─ execution_result.rs - Program result parsing.
- ├─ values.rs - JIT serialization.
- ├─ metadata.rs - Metadata injector to use within the compilation process.
- ├─ compiler.rs - The glue code of the compiler, has the codegen for the function signatures
- and calls the libfunc codegen implementations.
- ├─ error.rs - Error handling
- ├─ bin - Binary programs
- ├─ types - Cairo to MLIR type information
-cairo_nativeYou need to setup some environment variables:
+$MLIR_SYS_180_PREFIX=/path/to/llvm18 # Required for non-standard LLVM install locations.
+$LLVM_SYS_181_PREFIX=/path/to/llvm18 # Required for non-standard LLVM install locations.
+$TABLEGEN_180_PREFIX=/path/to/llvm18 # Required for non-standard LLVM install locations.
+You can then run the bench makefile target:
make bench
+The bench target will run the ./scripts/bench-hyperfine.sh script.
+This script runs hyperfine commands to compare the execution time of programs in the ./programs/benches/ folder.
+Each program is compiled and executed via the execution engine with the cairo-native-run command and via the cairo-vm with the cairo-run command provided by the cairo codebase.
+The cairo-run command should be available in the $PATH and ideally compiled with cargo build --release.
+If you want the benchmarks to run using a specific build, or the cairo-run commands conflicts with something (e.g. the cairo-svg package binaries in macos) then the command to run cairo-run with a full path can be specified with the $CAIRO_RUN environment variable.
cairo_nativeError for metadata calculations.
-self and other values to be equal, and is used
+self and other values to be equal, and is used
by ==.Used as return value for Nullables that are null.
U::from(self).\nCalls U::from(self).\nCompiler libfunc infrastructure\nCode generation metadata\nConverts a MLIR module to a compile object, that can be …\nLinks the passed object into a shared library, stored on …\nStarknet related code for cairo_native\nA (somewhat) usable implementation of the starknet syscall …\nCompiler type infrastructure\nVarious utilities\nJIT params and return values de/serialization\nReturns the argument unchanged.\nCalls U::from(self).\nReturns the argument unchanged.\nCalls U::from(self).\nA Cache for programs with the same context.\nReturns the argument unchanged.\nCalls U::from(self).\nContext of IRs, dialects and passes for Cairo programs …\nCompiles a sierra program into MLIR and then lowers to …\nReturns the argument unchanged.\nInitialize an MLIR context.\nCalls U::from(self).\nContains the error value\nContains the success value\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nStarknet contract execution result.\nThe result of the JIT execution.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nConvert a [ExecuteResult] to a [NativeExecutionResult]\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nA MLIR JIT execution engine in the context of Cairo Native.\nThe cairo native executor, either AOT or JIT based.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nUtility to convert a NativeModule into an AotNativeExecutor…\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nInvoke the given function by its function id, with the …\nExecute a program with the given params.\nInvoke the given function by its function id, with the …\nExecute a program with the given params.\nInvoke the given function by its function id, with the …\nA libfunc branching target.\nError type returned by this trait’s methods.\nA block within the current libfunc.\nGeneration of MLIR operations from their Sierra …\nHelper struct which contains logic generation for extra …\nA statement’s branch target by its index.\nAP tracking libfuncs\nInserts a new block after all the current libfunc’s …\nArray libfuncs\nBitwise libfuncs\nBoolean libfuncs\nBounded int libfuncs\nBox libfuncs\nCreates an unconditional branching operation out of the …\nBranch alignment libfunc\nGenerate the MLIR operations.\nBytes31-related libfuncs\nCasting libfuncs\nCircuit libfuncs\nCreates a conditional binary branching operation, …\nConst libfuncs\nBranch alignment libfunc\nDebug libfuncs\nAP tracking libfuncs\nState value duplication libfunc\nElliptic curve libfuncs\nEnum-related libfuncs\nFelt-related libfuncs\nFelt dictionary libfuncs\nFelt dictionary entry libfuncs\nReturns the argument unchanged.\nReturns the argument unchanged.\nFunction call libfuncs\nGas management libfuncs\nReturn the initialization block.\nCalls U::from(self).\nCalls U::from(self).\nReturn the target function if the statement is a function …\nMemory-related libfuncs\nNullable libfuncs\nPedersen hashing libfuncs\nPoseidon hashing libfuncs\ni128-related libfuncs\ni16-related libfuncs\ni32-related libfuncs\ni64-related libfuncs\ni8-related libfuncs\nSnapshot taking libfuncs\nStarknet libfuncs\nStruct-related libfuncs\nCreates a conditional multi-branching operation, …\nu128-related libfuncs\nu16-related libfuncs\nu256-related libfuncs\nu32-related libfuncs\nu512-related libfuncs\nu64-related libfuncs\nu8-related libfuncs\nUnconditional jump libfunc\nNon-zero unwrapping libfuncs\nSelect and call the correct libfunc builder function from …\nGenerate MLIR operations for the disable_ap_tracking …\nGenerate MLIR operations for the enable_ap_tracking …\nGenerate MLIR operations for the revoke_ap_tracking. …\nSelect and call the correct libfunc builder function from …\nGenerate MLIR operations for the array_append libfunc.\nGenerate MLIR operations for the array_get libfunc.\nGenerate MLIR operations for the array_len libfunc.\nGenerate MLIR operations for the array_new libfunc.\nGenerate MLIR operations for the array_pop_front libfunc.\nGenerate MLIR operations for the array_pop_front_consume …\nGenerate MLIR operations for the array_slice libfunc.\nGenerate MLIR operations for the array_snapshot_pop_back …\nGenerate MLIR operations for the array_snapshot_pop_front …\nGenerate MLIR operations for the span_from_tuple libfunc.\nGenerate MLIR operations for the bitwise libfunc.\nSelect and call the correct libfunc builder function from …\nGenerate MLIR operations for the bool_not_impl libfunc.\nGenerate MLIR operations for the unbox libfunc.\nSelect and call the correct libfunc builder function from …\nSelect and call the correct libfunc builder function from …\nGenerate MLIR operations for the into_box libfunc.\nGenerate MLIR operations for the unbox libfunc.\nGenerate MLIR operations for the branch_align libfunc.\nSelect and call the correct libfunc builder function from …\nGenerate MLIR operations for the bytes31_const libfunc.\nGenerate MLIR operations for the u8_from_felt252 libfunc.\nGenerate MLIR operations for the bytes31_to_felt252 …\nSelect and call the correct libfunc builder function from …\nGenerate MLIR operations for the downcast libfunc.\nGenerate MLIR operations for the upcast libfunc.\nSelect and call the correct libfunc builder function from …\nSelect and call the correct libfunc builder function from …\nGenerate MLIR operations for the const_as_box libfunc.\nGenerate MLIR operations for the const_as_immediate …\nGenerate MLIR operations for the coupon libfuncs. In …\nGenerate MLIR operations for the coupon libfunc.\nGenerate MLIR operations for the coupon libfunc.\nGenerate MLIR operations for the drop libfunc.\nGenerate MLIR operations for the dup libfunc.\nSelect and call the correct libfunc builder function from …\nGenerate MLIR operations for the ec_point_is_zero libfunc.\nGenerate MLIR operations for the ec_neg libfunc.\nGenerate MLIR operations for the ec_point_from_x_nz …\nGenerate MLIR operations for the ec_state_add libfunc.\nGenerate MLIR operations for the ec_state_add_mul libfunc.\nGenerate MLIR operations for the ec_state_try_finalize_nz …\nGenerate MLIR operations for the ec_state_init libfunc.\nGenerate MLIR operations for the ec_point_try_new_nz …\nGenerate MLIR operations for the ec_point_unwrap libfunc.\nGenerate MLIR operations for the ec_point_zero libfunc.\nSelect and call the correct libfunc builder function from …\nGenerate MLIR operations for the enum_from_bounded_int …\nGenerate MLIR operations for the enum_init libfunc.\nGenerate MLIR operations for the enum_match libfunc.\nGenerate MLIR operations for the enum_snapshot_match …\nSelect and call the correct libfunc builder function from …\nGenerate MLIR operations for the following libfuncs:\nGenerate MLIR operations for the felt252_const libfunc.\nGenerate MLIR operations for the felt252_is_zero libfunc.\nSelect and call the correct libfunc builder function from …\nSelect and call the correct libfunc builder function from …\nGenerate MLIR operations for the function_call libfunc.\nSelect and call the correct libfunc builder function from …\nGenerate MLIR operations for the withdraw_gas_all libfunc.\nGenerate MLIR operations for the get_builtin_costs libfunc.\nGenerate MLIR operations for the get_builtin_costs libfunc.\nGenerate MLIR operations for the withdraw_gas libfunc.\nSelect and call the correct libfunc builder function from …\nGenerate MLIR operations for the alloc_local libfunc.\nGenerate MLIR operations for the finalize_locals libfunc.\nGenerate MLIR operations for the rename libfunc.\nGenerate MLIR operations for the store_local libfunc.\nGenerate MLIR operations for the store_temp libfunc.\nSelect and call the correct libfunc builder function from …\nSelect and call the correct libfunc builder function from …\nSelect and call the correct libfunc builder function from …\nSelect and call the correct libfunc builder function from …\nGenerate MLIR operations for the i128_const libfunc.\nGenerate MLIR operations for the i128_diff libfunc.\nGenerate MLIR operations for the i128_eq libfunc.\nGenerate MLIR operations for the i128_from_felt252 libfunc.\nGenerate MLIR operations for the i128_is_zero libfunc.\nGenerate MLIR operations for the i128 operation libfunc.\nGenerate MLIR operations for the i128_to_felt252 libfunc.\nSelect and call the correct libfunc builder function from …\nGenerate MLIR operations for the i16_const libfunc.\nGenerate MLIR operations for the i16_diff libfunc.\nGenerate MLIR operations for the i16_eq libfunc.\nGenerate MLIR operations for the i16_from_felt252 libfunc.\nGenerate MLIR operations for the i16_is_zero libfunc.\nGenerate MLIR operations for the i16 operation libfunc.\nGenerate MLIR operations for the i16_to_felt252 libfunc.\nGenerate MLIR operations for the i16_widemul libfunc.\nSelect and call the correct libfunc builder function from …\nGenerate MLIR operations for the i32_const libfunc.\nGenerate MLIR operations for the i32_diff libfunc.\nGenerate MLIR operations for the i32_eq libfunc.\nGenerate MLIR operations for the i32_from_felt252 libfunc.\nGenerate MLIR operations for the i32_is_zero libfunc.\nGenerate MLIR operations for the i32 operation libfunc.\nGenerate MLIR operations for the i32_to_felt252 libfunc.\nGenerate MLIR operations for the i32_widemul libfunc.\nSelect and call the correct libfunc builder function from …\nGenerate MLIR operations for the i64_const libfunc.\nGenerate MLIR operations for the i64_diff libfunc.\nGenerate MLIR operations for the i64_eq libfunc.\nGenerate MLIR operations for the i64_from_felt252 libfunc.\nGenerate MLIR operations for the i64_is_zero libfunc.\nGenerate MLIR operations for the i64 operation libfunc.\nGenerate MLIR operations for the i64_to_felt252 libfunc.\nGenerate MLIR operations for the i64_widemul libfunc.\nSelect and call the correct libfunc builder function from …\nGenerate MLIR operations for the i8_const libfunc.\nGenerate MLIR operations for the i8_diff libfunc.\nGenerate MLIR operations for the i8_eq libfunc.\nGenerate MLIR operations for the i8_from_felt252 libfunc.\nGenerate MLIR operations for the i8_is_zero libfunc.\nGenerate MLIR operations for the i8 operation libfunc.\nGenerate MLIR operations for the i8_to_felt252 libfunc.\nGenerate MLIR operations for the i8_widemul libfunc.\nGenerate MLIR operations for the snapshot_take libfunc.\nSelect and call the correct libfunc builder function from …\nFrom the corelib\nFrom the corelib\nSelect and call the correct libfunc builder function from …\nGenerate MLIR operations for the struct_construct libfunc.\nGenerate MLIR operations for the struct_deconstruct …\nGenerate MLIR operations for the struct_construct libfunc.\nSelect and call the correct libfunc builder function from …\nGenerate MLIR operations for the u128_byte_reverse libfunc.\nGenerate MLIR operations for the u128_const libfunc.\nGenerate MLIR operations for the u128_safe_divmod libfunc.\nGenerate MLIR operations for the u128_equal libfunc.\nGenerate MLIR operations for the u128s_from_felt252 …\nGenerate MLIR operations for the u128_guarantee_mul …\nGenerate MLIR operations for the u128_guarantee_verify …\nGenerate MLIR operations for the u128_is_zero libfunc.\nGenerate MLIR operations for the u128_add and u128_sub …\nGenerate MLIR operations for the u128_sqrt libfunc.\nGenerate MLIR operations for the u128_to_felt252 libfunc.\nSelect and call the correct libfunc builder function from …\nGenerate MLIR operations for the u16_const libfunc.\nGenerate MLIR operations for the u16_safe_divmod libfunc.\nGenerate MLIR operations for the u16_eq libfunc.\nGenerate MLIR operations for the u16_from_felt252 libfunc.\nGenerate MLIR operations for the u16_is_zero libfunc.\nGenerate MLIR operations for the u16 operation libfunc.\nGenerate MLIR operations for the u16_sqrt libfunc.\nGenerate MLIR operations for the u16_to_felt252 libfunc.\nGenerate MLIR operations for the u16_widemul libfunc.\nSelect and call the correct libfunc builder function from …\nGenerate MLIR operations for the u256_safe_divmod libfunc.\nGenerate MLIR operations for the u256_is_zero libfunc.\nGenerate MLIR operations for the u256_sqrt libfunc.\nGenerate MLIR operations for the u256_guarantee_inv_mod_n …\nSelect and call the correct libfunc builder function from …\nGenerate MLIR operations for the u32_const libfunc.\nGenerate MLIR operations for the u32_safe_divmod libfunc.\nGenerate MLIR operations for the u32_eq libfunc.\nGenerate MLIR operations for the u32_from_felt252 libfunc.\nGenerate MLIR operations for the u32_is_zero libfunc.\nGenerate MLIR operations for the u32 operation libfunc.\nGenerate MLIR operations for the u32_sqrt libfunc.\nGenerate MLIR operations for the u32_to_felt252 libfunc.\nGenerate MLIR operations for the u32_widemul libfunc.\nSelect and call the correct libfunc builder function from …\nGenerate MLIR operations for the u512_safe_divmod_by_u256 …\nSelect and call the correct libfunc builder function from …\nGenerate MLIR operations for the u64_const libfunc.\nGenerate MLIR operations for the u64_safe_divmod libfunc.\nGenerate MLIR operations for the u64_eq libfunc.\nGenerate MLIR operations for the u64_from_felt252 libfunc.\nGenerate MLIR operations for the u64_is_zero libfunc.\nGenerate MLIR operations for the u64 operation libfunc.\nGenerate MLIR operations for the u64_sqrt libfunc.\nGenerate MLIR operations for the u64_to_felt252 libfunc.\nGenerate MLIR operations for the u64_widemul libfunc.\nSelect and call the correct libfunc builder function from …\nGenerate MLIR operations for the u8_const libfunc.\nGenerate MLIR operations for the u8_safe_divmod libfunc.\nGenerate MLIR operations for the u8_eq libfunc.\nGenerate MLIR operations for the u8_from_felt252 libfunc.\nGenerate MLIR operations for the u8_is_zero libfunc.\nGenerate MLIR operations for the u8 operation libfunc.\nGenerate MLIR operations for the u8_sqrt libfunc.\nGenerate MLIR operations for the u8_to_felt252 libfunc.\nGenerate MLIR operations for the u8_widemul libfunc.\nGenerate MLIR operations for the jump libfunc.\nGenerate MLIR operations for the unwrap_non_zero libfunc.\nMetadata container.\nDebug utilities\nReturns the argument unchanged.\nRetrieve a reference to some metadata.\nRetrieve a mutable reference to some metadata.\nInsert some metadata and return a mutable reference.\nCalls U::from(self).\nCreate an empty metadata container.\nFinite field prime modulo\nMemory allocation external bindings\nRemove some metadata and return its last value.\nRuntime library bindings\nTail recursion information\nReturns the argument unchanged.\nReturns the argument unchanged.\nCalls U::from(self).\nCalls U::from(self).\nPrints the given &str.\nDump a memory region at runtime.\nReturns the argument unchanged.\nCalls U::from(self).\nReturns the argument unchanged.\nCalls U::from(self).\nHolds global gas info.\nError for metadata calculations.\nConfiguration for metadata computation.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the initial value for the gas counter. If …\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nPrime modulo number metadata.\nReturns the argument unchanged.\nCalls U::from(self).\nCreate the metadata from the prime number.\nReturn the stored prime number.\nMemory allocation realloc metadata.\nCalls the free function.\nReturns the argument unchanged.\nCalls U::from(self).\nRegister the bindings to the realloc C function and return …\nCalls the realloc function, returns a op with 1 result: an …\nRuntime library bindings metadata.\nRegister if necessary, then invoke the dict_alloc_new() …\nRegister if necessary, then invoke the dict_alloc_new() …\nRegister if necessary, then invoke the dict_gas_refund() …\nRegister if necessary, then invoke the dict_get() function.\nRegister if necessary, then invoke the dict_insert() …\nRegister if necessary, then invoke the dict_clone() …\nReturns the argument unchanged.\nCalls U::from(self).\nRegister if necessary, then invoke the debug::print() …\nRegister if necessary, then invoke the ec_point_from_x_nz()…\nRegister if necessary, then invoke the …\nRegister if necessary, then invoke the ec_state_add() …\nRegister if necessary, then invoke the ec_state_add_mul() …\nRegister if necessary, then invoke the ec_state_init() …\nRegister if necessary, then invoke the poseidon() function.\nRegister if necessary, then invoke the pedersen() function.\nRegister if necessary, then invoke the vtable_cheatcode() …\nReturns the argument unchanged.\nCalls U::from(self).\nThe tail recursion metadata.\nReturn the current depth counter value.\nReturns the argument unchanged.\nCalls U::from(self).\nCreate the tail recursion meta.\nReturn the recursion target block.\nReturn the return target block, if set.\nSet the return target block.\nA MLIR module in the context of Cairo Native. It is …\nReturns the argument unchanged.\nRetrieve a reference to some stored metadata.\nInsert some metadata for the program execution and return …\nCalls U::from(self).\nRemoves metadata\nContains the error value\nBinary representation of a Felt (in MLIR).\nContains the success value\nBinary representation of a u256 (in MLIR).\nRuntime function that calls the cheatcode syscall\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nEvent emitted by the emit_event syscall.\nA (somewhat) usable implementation of the starknet syscall …\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nError type returned by this trait’s methods.\nGeneration of MLIR types from their Sierra counterparts.\nArray type\nBitwise type\nBoundedInt type\nBox type\nBuild the MLIR type.\nBuiltin costs type\nbytes31 type\nCircuit type\nCoupon type.\nElliptic curve operation type\nElliptic curve point type\nElliptic curve state type\nEnum type\nfelt252 type\nFelt dictionary type\nFelt dictionary entry type\nReturns the argument unchanged.\nGas builtin type\nIf the type is an integer, return its value range.\nCalls U::from(self).\nReturn whether the type is a BoundedInt<>, either directly …\nReturn whether the type is a builtin.\nReturn whether the type requires a return pointer when …\nReturn whether the type is a felt252, either directly or …\nWhether the layout should be allocated in memory (either …\nReturn whether the Sierra type resolves to a zero-sized …\nGenerate the layout of the MLIR type.\nNon-zero type\nNullable type\nPedersen type\nPoseidon type\nBuiltin costs type\nSegment arena type\nSnapshot type\nSquashed Felt dictionary type\nStarknet types\nStruct type\nUnsigned 128-bit integer type\nUnsigned 128-bit multiplication guarantee type\nUnsigned 16-bit integer type\nUnsigned 32-bit integer type\nUnsigned 64-bit integer type\nUnsigned 8-bit integer type\nUninitialized type\nIf the type is a enum type, return all possible variants.\nBuild the MLIR type.\nBuild the MLIR type.\nBuild the MLIR type.\nBuild the MLIR type.\nBuild the MLIR type.\nBuild the MLIR type.\nBuild the MLIR type.\nBuild the MLIR type.\nBuild the MLIR type.\nBuild the MLIR type.\nBuild the MLIR type.\nAn MLIR type with its memory layout.\nBuild the MLIR type.\nExtract layout for the default enum representation, its …\nExtract the type and layout for the default enum …\nThe felt252 prime modulo.\nBuild the MLIR type.\nReturns the argument unchanged.\nReturns the argument unchanged.\nCalls U::from(self).\nCalls U::from(self).\nBuild the MLIR type.\nBuild the MLIR type.\nBuild the MLIR type.\nBuild the MLIR type.\nBuild the MLIR type.\nBuild the MLIR type.\nBuild the MLIR type.\nBuild the MLIR type.\nBuild the MLIR type.\nBuild the MLIR type.\nBuild the MLIR type.\nBuild the MLIR type.\nBuild the MLIR type.\nBuild the MLIR type.\nBuild the MLIR type.\nBuild the MLIR type.\nBuild the MLIR type.\nBuild the MLIR type.\nBuild the MLIR type.\nBuild the MLIR type.\nCompile a cairo program found at the given path to sierra.\nCreates the execution engine, with all symbols registered.\nReturn a type that calls a closure when formatted using …\nParse any type that can be a bigint to a felt that can be …\nParse a short string into a felt that can be used in the …\nParse a numeric string into felt, wrapping negatives …\nReturns the given entry point if present.\nReturns the given entry point if present.\nGiven a string representing a function name, searches in …\nReturns the argument unchanged.\nGenerate a function name.\nReturn the layout for an integer of arbitrary width.\nCalls U::from(self).\nCopied from std.\nWidth in bits when the offset is not necessarily zero …\nEdit: Copied from the std lib.\nWidth in bits when the offset is zero (aka. the natural …\nall elements need to be same type\nA JitValue is a value that can be passed to the JIT engine …\nUsed as return value for Nullables that are null.\nString to felt\nReturns the argument unchanged.\nCalls U::from(self).")
\ No newline at end of file
+searchState.loadedDescShard("cairo_native", 0, "⚡ Cairo Native ⚡\nA error from the LLVM API.\nOptimization levels.\nRun the compiler on a program. The compiled program is …\nCairo Native Compiler and Execution Engine\nVarious error types used thorough the crate.\nExecutors\nReturns the argument unchanged.\nReturns the argument unchanged.\nCalls U::from(self).\nCalls U::from(self).\nCompiler libfunc infrastructure\nCode generation metadata\nConverts a MLIR module to a compile object, that can be …\nLinks the passed object into a shared library, stored on …\nStarknet related code for cairo_native\nA (somewhat) usable implementation of the starknet syscall …\nCompiler type infrastructure\nVarious utilities\nJIT params and return values de/serialization\nReturns the argument unchanged.\nCalls U::from(self).\nReturns the argument unchanged.\nCalls U::from(self).\nA Cache for programs with the same context.\nReturns the argument unchanged.\nCalls U::from(self).\nContext of IRs, dialects and passes for Cairo programs …\nCompiles a sierra program into MLIR and then lowers to …\nReturns the argument unchanged.\nInitialize an MLIR context.\nCalls U::from(self).\nOverview\nCompilation Walkthrough\nExecution Walkthrough\nGas and Builtins Accounting\nImplementing Libfuncs\nDebugging\nSierra Resources\nMLIR Resources\nContains the error value\nContains the success value\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nStarknet contract execution result.\nThe result of the JIT execution.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nConvert an ExecutionResult into a ContractExecutionResult\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nA MLIR JIT execution engine in the context of Cairo Native.\nThe cairo native executor, either AOT or JIT based.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nUtility to convert a NativeModule into an AotNativeExecutor…\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nInvoke the given function by its function id, with the …\nExecute a program with the given params.\nInvoke the given function by its function id, with the …\nExecute a program with the given params.\nInvoke the given function by its function id, with the …\nA libfunc branching target.\nError type returned by this trait’s methods.\nA block within the current libfunc.\nGeneration of MLIR operations from their Sierra …\nHelper struct which contains logic generation for extra …\nA statement’s branch target by its index.\nAP tracking libfuncs\nInserts a new block after all the current libfunc’s …\nArray libfuncs\nBitwise libfuncs\nBoolean libfuncs\nBounded int libfuncs\nBox libfuncs\nCreates an unconditional branching operation out of the …\nBranch alignment libfunc\nGenerate the MLIR operations.\nBytes31-related libfuncs\nCasting libfuncs\nCircuit libfuncs\nCreates a conditional binary branching operation, …\nConst libfuncs\nBranch alignment libfunc\nDebug libfuncs\nAP tracking libfuncs\nState value duplication libfunc\nElliptic curve libfuncs\nEnum-related libfuncs\nFelt-related libfuncs\nFelt dictionary libfuncs\nFelt dictionary entry libfuncs\nReturns the argument unchanged.\nReturns the argument unchanged.\nFunction call libfuncs\nGas management libfuncs\nReturn the initialization block.\nCalls U::from(self).\nCalls U::from(self).\nReturn the target function if the statement is a function …\nMemory-related libfuncs\nNullable libfuncs\nPedersen hashing libfuncs\nPoseidon hashing libfuncs\ni128-related libfuncs\ni16-related libfuncs\ni32-related libfuncs\ni64-related libfuncs\ni8-related libfuncs\nSnapshot taking libfuncs\nStarknet libfuncs\nStruct-related libfuncs\nCreates a conditional multi-branching operation, …\nu128-related libfuncs\nu16-related libfuncs\nu256-related libfuncs\nu32-related libfuncs\nu512-related libfuncs\nu64-related libfuncs\nu8-related libfuncs\nUnconditional jump libfunc\nNon-zero unwrapping libfuncs\nSelect and call the correct libfunc builder function from …\nGenerate MLIR operations for the disable_ap_tracking …\nGenerate MLIR operations for the enable_ap_tracking …\nGenerate MLIR operations for the revoke_ap_tracking. …\nSelect and call the correct libfunc builder function from …\nGenerate MLIR operations for the array_append libfunc.\nGenerate MLIR operations for the array_get libfunc.\nGenerate MLIR operations for the array_len libfunc.\nGenerate MLIR operations for the array_new libfunc.\nGenerate MLIR operations for the array_pop_front libfunc.\nGenerate MLIR operations for the array_pop_front_consume …\nGenerate MLIR operations for the array_slice libfunc.\nGenerate MLIR operations for the array_snapshot_pop_back …\nGenerate MLIR operations for the array_snapshot_pop_front …\nGenerate MLIR operations for the span_from_tuple libfunc.\nGenerate MLIR operations for the bitwise libfunc.\nSelect and call the correct libfunc builder function from …\nGenerate MLIR operations for the bool_not_impl libfunc.\nGenerate MLIR operations for the unbox libfunc.\nSelect and call the correct libfunc builder function from …\nSelect and call the correct libfunc builder function from …\nGenerate MLIR operations for the into_box libfunc.\nGenerate MLIR operations for the unbox libfunc.\nGenerate MLIR operations for the branch_align libfunc.\nSelect and call the correct libfunc builder function from …\nGenerate MLIR operations for the bytes31_const libfunc.\nGenerate MLIR operations for the u8_from_felt252 libfunc.\nGenerate MLIR operations for the bytes31_to_felt252 …\nSelect and call the correct libfunc builder function from …\nGenerate MLIR operations for the downcast libfunc.\nGenerate MLIR operations for the upcast libfunc.\nSelect and call the correct libfunc builder function from …\nSelect and call the correct libfunc builder function from …\nGenerate MLIR operations for the const_as_box libfunc.\nGenerate MLIR operations for the const_as_immediate …\nGenerate MLIR operations for the coupon libfuncs. In …\nGenerate MLIR operations for the coupon libfunc.\nGenerate MLIR operations for the coupon libfunc.\nGenerate MLIR operations for the drop libfunc.\nGenerate MLIR operations for the dup libfunc.\nSelect and call the correct libfunc builder function from …\nGenerate MLIR operations for the ec_point_is_zero libfunc.\nGenerate MLIR operations for the ec_neg libfunc.\nGenerate MLIR operations for the ec_point_from_x_nz …\nGenerate MLIR operations for the ec_state_add libfunc.\nGenerate MLIR operations for the ec_state_add_mul libfunc.\nGenerate MLIR operations for the ec_state_try_finalize_nz …\nGenerate MLIR operations for the ec_state_init libfunc.\nGenerate MLIR operations for the ec_point_try_new_nz …\nGenerate MLIR operations for the ec_point_unwrap libfunc.\nGenerate MLIR operations for the ec_point_zero libfunc.\nSelect and call the correct libfunc builder function from …\nGenerate MLIR operations for the enum_from_bounded_int …\nGenerate MLIR operations for the enum_init libfunc.\nGenerate MLIR operations for the enum_match libfunc.\nGenerate MLIR operations for the enum_snapshot_match …\nSelect and call the correct libfunc builder function from …\nGenerate MLIR operations for the following libfuncs:\nGenerate MLIR operations for the felt252_const libfunc.\nGenerate MLIR operations for the felt252_is_zero libfunc.\nSelect and call the correct libfunc builder function from …\nSelect and call the correct libfunc builder function from …\nGenerate MLIR operations for the function_call libfunc.\nSelect and call the correct libfunc builder function from …\nGenerate MLIR operations for the withdraw_gas_all libfunc.\nGenerate MLIR operations for the get_builtin_costs libfunc.\nGenerate MLIR operations for the get_builtin_costs libfunc.\nGenerate MLIR operations for the withdraw_gas libfunc.\nSelect and call the correct libfunc builder function from …\nGenerate MLIR operations for the alloc_local libfunc.\nGenerate MLIR operations for the finalize_locals libfunc.\nGenerate MLIR operations for the rename libfunc.\nGenerate MLIR operations for the store_local libfunc.\nGenerate MLIR operations for the store_temp libfunc.\nSelect and call the correct libfunc builder function from …\nSelect and call the correct libfunc builder function from …\nSelect and call the correct libfunc builder function from …\nSelect and call the correct libfunc builder function from …\nGenerate MLIR operations for the i128_const libfunc.\nGenerate MLIR operations for the i128_diff libfunc.\nGenerate MLIR operations for the i128_eq libfunc.\nGenerate MLIR operations for the i128_from_felt252 libfunc.\nGenerate MLIR operations for the i128_is_zero libfunc.\nGenerate MLIR operations for the i128 operation libfunc.\nGenerate MLIR operations for the i128_to_felt252 libfunc.\nSelect and call the correct libfunc builder function from …\nGenerate MLIR operations for the i16_const libfunc.\nGenerate MLIR operations for the i16_diff libfunc.\nGenerate MLIR operations for the i16_eq libfunc.\nGenerate MLIR operations for the i16_from_felt252 libfunc.\nGenerate MLIR operations for the i16_is_zero libfunc.\nGenerate MLIR operations for the i16 operation libfunc.\nGenerate MLIR operations for the i16_to_felt252 libfunc.\nGenerate MLIR operations for the i16_widemul libfunc.\nSelect and call the correct libfunc builder function from …\nGenerate MLIR operations for the i32_const libfunc.\nGenerate MLIR operations for the i32_diff libfunc.\nGenerate MLIR operations for the i32_eq libfunc.\nGenerate MLIR operations for the i32_from_felt252 libfunc.\nGenerate MLIR operations for the i32_is_zero libfunc.\nGenerate MLIR operations for the i32 operation libfunc.\nGenerate MLIR operations for the i32_to_felt252 libfunc.\nGenerate MLIR operations for the i32_widemul libfunc.\nSelect and call the correct libfunc builder function from …\nGenerate MLIR operations for the i64_const libfunc.\nGenerate MLIR operations for the i64_diff libfunc.\nGenerate MLIR operations for the i64_eq libfunc.\nGenerate MLIR operations for the i64_from_felt252 libfunc.\nGenerate MLIR operations for the i64_is_zero libfunc.\nGenerate MLIR operations for the i64 operation libfunc.\nGenerate MLIR operations for the i64_to_felt252 libfunc.\nGenerate MLIR operations for the i64_widemul libfunc.\nSelect and call the correct libfunc builder function from …\nGenerate MLIR operations for the i8_const libfunc.\nGenerate MLIR operations for the i8_diff libfunc.\nGenerate MLIR operations for the i8_eq libfunc.\nGenerate MLIR operations for the i8_from_felt252 libfunc.\nGenerate MLIR operations for the i8_is_zero libfunc.\nGenerate MLIR operations for the i8 operation libfunc.\nGenerate MLIR operations for the i8_to_felt252 libfunc.\nGenerate MLIR operations for the i8_widemul libfunc.\nGenerate MLIR operations for the snapshot_take libfunc.\nSelect and call the correct libfunc builder function from …\nFrom the corelib\nFrom the corelib\nSelect and call the correct libfunc builder function from …\nGenerate MLIR operations for the struct_construct libfunc.\nGenerate MLIR operations for the struct_deconstruct …\nGenerate MLIR operations for the struct_construct libfunc.\nSelect and call the correct libfunc builder function from …\nGenerate MLIR operations for the u128_byte_reverse libfunc.\nGenerate MLIR operations for the u128_const libfunc.\nGenerate MLIR operations for the u128_safe_divmod libfunc.\nGenerate MLIR operations for the u128_equal libfunc.\nGenerate MLIR operations for the u128s_from_felt252 …\nGenerate MLIR operations for the u128_guarantee_mul …\nGenerate MLIR operations for the u128_guarantee_verify …\nGenerate MLIR operations for the u128_is_zero libfunc.\nGenerate MLIR operations for the u128_add and u128_sub …\nGenerate MLIR operations for the u128_sqrt libfunc.\nGenerate MLIR operations for the u128_to_felt252 libfunc.\nSelect and call the correct libfunc builder function from …\nGenerate MLIR operations for the u16_const libfunc.\nGenerate MLIR operations for the u16_safe_divmod libfunc.\nGenerate MLIR operations for the u16_eq libfunc.\nGenerate MLIR operations for the u16_from_felt252 libfunc.\nGenerate MLIR operations for the u16_is_zero libfunc.\nGenerate MLIR operations for the u16 operation libfunc.\nGenerate MLIR operations for the u16_sqrt libfunc.\nGenerate MLIR operations for the u16_to_felt252 libfunc.\nGenerate MLIR operations for the u16_widemul libfunc.\nSelect and call the correct libfunc builder function from …\nGenerate MLIR operations for the u256_safe_divmod libfunc.\nGenerate MLIR operations for the u256_is_zero libfunc.\nGenerate MLIR operations for the u256_sqrt libfunc.\nGenerate MLIR operations for the u256_guarantee_inv_mod_n …\nSelect and call the correct libfunc builder function from …\nGenerate MLIR operations for the u32_const libfunc.\nGenerate MLIR operations for the u32_safe_divmod libfunc.\nGenerate MLIR operations for the u32_eq libfunc.\nGenerate MLIR operations for the u32_from_felt252 libfunc.\nGenerate MLIR operations for the u32_is_zero libfunc.\nGenerate MLIR operations for the u32 operation libfunc.\nGenerate MLIR operations for the u32_sqrt libfunc.\nGenerate MLIR operations for the u32_to_felt252 libfunc.\nGenerate MLIR operations for the u32_widemul libfunc.\nSelect and call the correct libfunc builder function from …\nGenerate MLIR operations for the u512_safe_divmod_by_u256 …\nSelect and call the correct libfunc builder function from …\nGenerate MLIR operations for the u64_const libfunc.\nGenerate MLIR operations for the u64_safe_divmod libfunc.\nGenerate MLIR operations for the u64_eq libfunc.\nGenerate MLIR operations for the u64_from_felt252 libfunc.\nGenerate MLIR operations for the u64_is_zero libfunc.\nGenerate MLIR operations for the u64 operation libfunc.\nGenerate MLIR operations for the u64_sqrt libfunc.\nGenerate MLIR operations for the u64_to_felt252 libfunc.\nGenerate MLIR operations for the u64_widemul libfunc.\nSelect and call the correct libfunc builder function from …\nGenerate MLIR operations for the u8_const libfunc.\nGenerate MLIR operations for the u8_safe_divmod libfunc.\nGenerate MLIR operations for the u8_eq libfunc.\nGenerate MLIR operations for the u8_from_felt252 libfunc.\nGenerate MLIR operations for the u8_is_zero libfunc.\nGenerate MLIR operations for the u8 operation libfunc.\nGenerate MLIR operations for the u8_sqrt libfunc.\nGenerate MLIR operations for the u8_to_felt252 libfunc.\nGenerate MLIR operations for the u8_widemul libfunc.\nGenerate MLIR operations for the jump libfunc.\nGenerate MLIR operations for the unwrap_non_zero libfunc.\nMetadata container.\nDebug utilities\nReturns the argument unchanged.\nRetrieve a reference to some metadata.\nRetrieve a mutable reference to some metadata.\nInsert some metadata and return a mutable reference.\nCalls U::from(self).\nCreate an empty metadata container.\nFinite field prime modulo\nMemory allocation external bindings\nRemove some metadata and return its last value.\nRuntime library bindings\nTail recursion information\nReturns the argument unchanged.\nReturns the argument unchanged.\nCalls U::from(self).\nCalls U::from(self).\nPrints the given &str.\nDump a memory region at runtime.\nReturns the argument unchanged.\nCalls U::from(self).\nReturns the argument unchanged.\nCalls U::from(self).\nHolds global gas info.\nError for metadata calculations.\nConfiguration for metadata computation.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the initial value for the gas counter. If …\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nPrime modulo number metadata.\nReturns the argument unchanged.\nCalls U::from(self).\nCreate the metadata from the prime number.\nReturn the stored prime number.\nMemory allocation realloc metadata.\nCalls the free function.\nReturns the argument unchanged.\nCalls U::from(self).\nRegister the bindings to the realloc C function and return …\nCalls the realloc function, returns a op with 1 result: an …\nRuntime library bindings metadata.\nRegister if necessary, then invoke the dict_alloc_new() …\nRegister if necessary, then invoke the dict_alloc_new() …\nRegister if necessary, then invoke the dict_gas_refund() …\nRegister if necessary, then invoke the dict_get() function.\nRegister if necessary, then invoke the dict_insert() …\nRegister if necessary, then invoke the dict_clone() …\nReturns the argument unchanged.\nCalls U::from(self).\nRegister if necessary, then invoke the debug::print() …\nRegister if necessary, then invoke the ec_point_from_x_nz()…\nRegister if necessary, then invoke the …\nRegister if necessary, then invoke the ec_state_add() …\nRegister if necessary, then invoke the ec_state_add_mul() …\nRegister if necessary, then invoke the ec_state_init() …\nRegister if necessary, then invoke the poseidon() function.\nRegister if necessary, then invoke the pedersen() function.\nRegister if necessary, then invoke the vtable_cheatcode() …\nReturns the argument unchanged.\nCalls U::from(self).\nThe tail recursion metadata.\nReturn the current depth counter value.\nReturns the argument unchanged.\nCalls U::from(self).\nCreate the tail recursion meta.\nReturn the recursion target block.\nReturn the return target block, if set.\nSet the return target block.\nA MLIR module in the context of Cairo Native. It is …\nReturns the argument unchanged.\nRetrieve a reference to some stored metadata.\nInsert some metadata for the program execution and return …\nCalls U::from(self).\nRemoves metadata\nContains the error value\nBinary representation of a Felt (in MLIR).\nContains the success value\nBinary representation of a u256 (in MLIR).\nRuntime function that calls the cheatcode syscall\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nEvent emitted by the emit_event syscall.\nA (somewhat) usable implementation of the starknet syscall …\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nError type returned by this trait’s methods.\nGeneration of MLIR types from their Sierra counterparts.\nArray type\nBitwise type\nBoundedInt type\nBox type\nBuild the MLIR type.\nBuiltin costs type\nbytes31 type\nCircuit type\nCoupon type.\nElliptic curve operation type\nElliptic curve point type\nElliptic curve state type\nEnum type\nfelt252 type\nFelt dictionary type\nFelt dictionary entry type\nReturns the argument unchanged.\nGas builtin type\nIf the type is an integer, return its value range.\nCalls U::from(self).\nReturn whether the type is a BoundedInt<>, either directly …\nReturn whether the type is a builtin.\nReturn whether the type requires a return pointer when …\nReturn whether the type is a felt252, either directly or …\nWhether the layout should be allocated in memory (either …\nReturn whether the Sierra type resolves to a zero-sized …\nGenerate the layout of the MLIR type.\nNon-zero type\nNullable type\nPedersen type\nPoseidon type\nBuiltin costs type\nSegment arena type\nSnapshot type\nSquashed Felt dictionary type\nStarknet types\nStruct type\nUnsigned 128-bit integer type\nUnsigned 128-bit multiplication guarantee type\nUnsigned 16-bit integer type\nUnsigned 32-bit integer type\nUnsigned 64-bit integer type\nUnsigned 8-bit integer type\nUninitialized type\nIf the type is a enum type, return all possible variants.\nBuild the MLIR type.\nBuild the MLIR type.\nBuild the MLIR type.\nBuild the MLIR type.\nBuild the MLIR type.\nBuild the MLIR type.\nBuild the MLIR type.\nBuild the MLIR type.\nBuild the MLIR type.\nBuild the MLIR type.\nBuild the MLIR type.\nAn MLIR type with its memory layout.\nBuild the MLIR type.\nExtract layout for the default enum representation, its …\nExtract the type and layout for the default enum …\nThe felt252 prime modulo.\nBuild the MLIR type.\nReturns the argument unchanged.\nReturns the argument unchanged.\nCalls U::from(self).\nCalls U::from(self).\nBuild the MLIR type.\nBuild the MLIR type.\nBuild the MLIR type.\nBuild the MLIR type.\nBuild the MLIR type.\nBuild the MLIR type.\nBuild the MLIR type.\nBuild the MLIR type.\nBuild the MLIR type.\nBuild the MLIR type.\nBuild the MLIR type.\nBuild the MLIR type.\nBuild the MLIR type.\nBuild the MLIR type.\nBuild the MLIR type.\nBuild the MLIR type.\nBuild the MLIR type.\nBuild the MLIR type.\nBuild the MLIR type.\nBuild the MLIR type.\nCompile a cairo program found at the given path to sierra.\nCreates the execution engine, with all symbols registered.\nReturn a type that calls a closure when formatted using …\nParse any type that can be a bigint to a felt that can be …\nParse a short string into a felt that can be used in the …\nParse a numeric string into felt, wrapping negatives …\nReturns the given entry point if present.\nReturns the given entry point if present.\nGiven a string representing a function name, searches in …\nReturns the argument unchanged.\nGenerate a function name.\nReturn the layout for an integer of arbitrary width.\nCalls U::from(self).\nCopied from std.\nWidth in bits when the offset is not necessarily zero …\nEdit: Copied from the std lib.\nWidth in bits when the offset is zero (aka. the natural …\nall elements need to be same type\nA JitValue is a value that can be passed to the JIT engine …\nUsed as return value for Nullables that are null.\nString to felt\nReturns the argument unchanged.\nCalls U::from(self).")
\ No newline at end of file
diff --git a/settings.html b/settings.html
index ee3127433..72f3253b8 100644
--- a/settings.html
+++ b/settings.html
@@ -1 +1 @@
-1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +
//! # Cairo Native Compiler and Execution Engine
+
+#[allow(clippy::needless_doctest_main)]
+#[cfg_attr(doc, aquamarine::aquamarine)]
+#[doc = include_str!("../docs/overview.md")]
+pub mod section01 {}
+
+#[cfg_attr(doc, aquamarine::aquamarine)]
+#[doc = include_str!("../docs/compilation_walkthrough.md")]
+pub mod section02 {}
+
+#[cfg_attr(doc, aquamarine::aquamarine)]
+#[doc = include_str!("../docs/execution_walkthrough.md")]
+pub mod section03 {}
+
+#[cfg_attr(doc, aquamarine::aquamarine)]
+#[doc = include_str!("../docs/gas_builtin_accounting.md")]
+pub mod section04 {}
+
+#[cfg_attr(doc, aquamarine::aquamarine)]
+#[doc = include_str!("../docs/implementing_libfuncs.md")]
+pub mod section05 {}
+
+#[cfg_attr(doc, aquamarine::aquamarine)]
+#[doc = include_str!("../docs/debugging.md")]
+pub mod section06 {}
+
+#[cfg_attr(doc, aquamarine::aquamarine)]
+#[doc = include_str!("../docs/sierra.md")]
+pub mod section07 {}
+
+#[cfg_attr(doc, aquamarine::aquamarine)]
+#[doc = include_str!("../docs/mlir.md")]
+pub mod section08 {}
+use crate::{
error::Error,
execution_result::{ContractExecutionResult, ExecutionResult},
@@ -224,8 +220,6 @@
}
/// Execute a program with the given params.
- ///
- /// See [`cairo_native::jit_runner::execute`]
pub fn invoke_dynamic(
&self,
function_id: &FunctionId,
@@ -248,8 +242,6 @@
}
/// Execute a program with the given params.
- ///
- /// See [`cairo_native::jit_runner::execute`]
pub fn invoke_dynamic_with_syscall_handler(
&self,
function_id: &FunctionId,
diff --git a/src/cairo_native/lib.rs.html b/src/cairo_native/lib.rs.html
index af85fc273..af125abe4 100644
--- a/src/cairo_native/lib.rs.html
+++ b/src/cairo_native/lib.rs.html
@@ -32,184 +32,15 @@
32
33
34
-35
-36
-37
-38
-39
-40
-41
-42
-43
-44
-45
-46
-47
-48
-49
-50
-51
-52
-53
-54
-55
-56
-57
-58
-59
-60
-61
-62
-63
-64
-65
-66
-67
-68
-69
-70
-71
-72
-73
-74
-75
-76
-77
-78
-79
-80
-81
-82
-83
-84
-85
-86
-87
-88
-89
-90
-91
-92
-93
-94
-95
-96
-97
-98
-99
-100
-101
-102
-103
-104
-105
-106
-107
-108
-109
-110
-111
-112
-113
-114
-115
-116
-117
-118
-//! # Cairo Sierra to MLIR compiler and JIT engine
-//!
-//! This crate is a compiler and JIT engine that transforms Sierra (or Cairo) sources into MLIR,
-//! which can be [JIT-executed](https://en.wikipedia.org/wiki/Just-in-time_compilation) or further
-//! compiled into a binary
-//! [ahead of time](https://en.wikipedia.org/wiki/Ahead-of-time_compilation).
-//!
-//! ## Usage
-//!
-//! The API contains two structs, `NativeContext` and `NativeExecutor`.
-//! The main purpose of `NativeContext` is MLIR initialization, compilation and lowering to LLVM.
-//! `NativeExecutor` in the other hand is responsible of executing MLIR compiled sierra programs
-//! from an entrypoint.
-//! Programs and JIT states can be cached in contexts where their execution will be done multiple
-//! times.
-//!
-//! ```
-//! use starknet_types_core::felt::Felt;
-//! use cairo_native::context::NativeContext;
-//! use cairo_native::executor::JitNativeExecutor;
-//! use cairo_native::values::JitValue;
-//! use std::path::Path;
-//!
-//! let program_path = Path::new("programs/examples/hello.cairo");
-//! // Compile the cairo program to sierra.
-//! let sierra_program = cairo_native::utils::cairo_to_sierra(program_path);
-//!
-//! // Instantiate a Cairo Native MLIR context. This data structure is responsible for the MLIR
-//! // initialization and compilation of sierra programs into a MLIR module.
-//! let native_context = NativeContext::new();
-//!
-//! // Compile the sierra program into a MLIR module.
-//! let native_program = native_context.compile(&sierra_program).unwrap();
-//!
-//! // The parameters of the entry point.
-//! let params = &[JitValue::Felt252(Felt::from_bytes_be_slice(b"user"))];
-//!
-//! // Find the entry point id by its name.
-//! let entry_point = "hello::hello::greet";
-//! let entry_point_id = cairo_native::utils::find_function_id(&sierra_program, entry_point);
-//!
-//! // Instantiate the executor.
-//! let native_executor = JitNativeExecutor::from_native_module(native_program, Default::default());
-//!
-//! // Execute the program.
-//! let result = native_executor
-//! .invoke_dynamic(entry_point_id, params, None)
-//! .unwrap();
-//!
-//! println!("Cairo program was compiled and executed successfully.");
-//! println!("{:?}", result);
-//! ```
-//!
-//! ## Common definitions
-//!
-//! Within this project there are lots of functions with the same signature. As their arguments have
-//! all the same meaning, they are documented here:
-//!
-//! - `context: NativeContext`: The MLIR context.
-//! - `module: &NativeModule`: The compiled MLIR program, with other relevant information such as program registry and metadata.
-//! - `program: &Program`: The Sierra input program.
-//! - `registry: &ProgramRegistry<TType, TLibfunc>`: The registry extracted from the program.
-//! - `metadata: &mut MetadataStorage`: Current compiler metadata.
-//!
-//! ## Project layout
-//!
-//! ```txt
-//! src
-//! ├─ context.rs - The MLIR context wrapper, provides the compile method.
-//! ├─ utils.rs - Internal utilities.
-//! ├─ metadata/ - Metadata injector to use within the compilation process
-//! ├─ executor/ - Code related to the executor of programs.
-//! ├─ module.rs - The MLIR module wrapper.
-//! ├─ arch/ - Trampoline assembly for calling functions with dynamic signatures.
-//! ├─ executor.rs - The executor code.
-//! ├─ ffi.cpp - Missing FFI C wrappers
-//! ├─ libfuncs - Cairo Sierra libfunc implementations
-//! ├─ libfuncs.rs - Cairo Sierra libfunc glue code
-//! ├─ starknet.rs - Starknet syscall handler glue code.
-//! ├─ ffi.rs - Missing FFI C wrappers, rust side.
-//! ├─ block_ext.rs - A melior (MLIR) block trait extension to write less code.
-//! ├─ lib.rs - The main lib file.
-//! ├─ execution_result.rs - Program result parsing.
-//! ├─ values.rs - JIT serialization.
-//! ├─ metadata.rs - Metadata injector to use within the compilation process.
-//! ├─ compiler.rs - The glue code of the compiler, has the codegen for the function signatures
-//! and calls the libfunc codegen implementations.
-//! ├─ error.rs - Error handling
-//! ├─ bin - Binary programs
-//! ├─ types - Cairo to MLIR type information
-//! ```
-
-// #![warn(missing_docs)]
-#![allow(clippy::missing_safety_doc)]
+#![allow(clippy::missing_safety_doc)]
+#![allow(rustdoc::bare_urls)]
+// The following line contains a markdown reference link.
+// This is necessary to override the link destination in the README.md file, so
+// that when the README.md is rendered standalone (e.g. on Github) it points to
+// the online version, and when rendered by rustdoc to the docs module rendered
+// page.
+//! [developer documentation]: docs
+#![doc = include_str!("../README.md")]
pub use self::{
compiler::compile,
@@ -222,6 +53,7 @@
mod compiler;
pub mod context;
pub mod debug;
+pub mod docs;
pub mod error;
pub mod execution_result;
pub mod executor;