From 9aea1fca18c835a5af484b00f8113076bf02d939 Mon Sep 17 00:00:00 2001 From: Steve Goodman Date: Thu, 2 May 2024 12:35:08 +0300 Subject: [PATCH] Updated Cairo builtins, changed name of file from builtins.adoc to cairo-builtins.adoc. --- .../architecture_and_concepts/nav.adoc | 2 +- .../pages/Smart_Contracts/builtins.adoc | 152 ------------------ .../pages/Smart_Contracts/cairo-builtins.adoc | 26 +++ 3 files changed, 27 insertions(+), 153 deletions(-) delete mode 100644 components/Starknet/modules/architecture_and_concepts/pages/Smart_Contracts/builtins.adoc create mode 100644 components/Starknet/modules/architecture_and_concepts/pages/Smart_Contracts/cairo-builtins.adoc diff --git a/components/Starknet/modules/architecture_and_concepts/nav.adoc b/components/Starknet/modules/architecture_and_concepts/nav.adoc index 72426f39b8..4e9ee5c349 100644 --- a/components/Starknet/modules/architecture_and_concepts/nav.adoc +++ b/components/Starknet/modules/architecture_and_concepts/nav.adoc @@ -31,7 +31,7 @@ *** xref:Smart_Contracts/starknet-events.adoc[Events] *** xref:Smart_Contracts/contract-syntax.adoc[Migrating a contract from Cairo v1 to Cairo v2] *** xref:Smart_Contracts/cairo-and-sierra.adoc[Cairo and Sierra] -*** xref:Smart_Contracts/builtins.adoc[Builtins] +*** xref:Smart_Contracts/cairo-builtins.adoc[Builtins] *** xref:Smart_Contracts/serialization_of_Cairo_types.adoc[Serialization of Cairo types] *** xref:Smart_Contracts/system-calls-cairo1.adoc[System calls] *** xref:Smart_Contracts/execution_info.adoc[Execution information for the current block] diff --git a/components/Starknet/modules/architecture_and_concepts/pages/Smart_Contracts/builtins.adoc b/components/Starknet/modules/architecture_and_concepts/pages/Smart_Contracts/builtins.adoc deleted file mode 100644 index e8683fbb73..0000000000 --- a/components/Starknet/modules/architecture_and_concepts/pages/Smart_Contracts/builtins.adoc +++ /dev/null @@ -1,152 +0,0 @@ -[id="cairo_builtins"] -= Cairo Builtins - -_Builtins_, in Cairo, are predefined optimized low-level execution units that the Cairo VM uses to perform predefined computations that are expensive to perform in standard Cairo. Builtins enhance the functionality of the Cairo VM, enabling you to perform certain tasks, such as using the Poseidon hash, range-checks, or ECDSA signature verifications, more efficiently, using less gas. - -[#list-of-cairo-builtins] -.List of Cairo builtins - -[cols="1,2,2"] -|=== -| Builtin | Example | Explanation - -| `pedersen` -| `result = pedersen(x, y)` -| `pedersen(x: felt252, y: felt252) -> felt252` - -Hashes two elements and retrieves a single field element output. - -| `poseidon_hash` -| `result = poseidon_hash(x, y)` -| `poseidon_hash(x: felt, y: felt) -> (res: felt)` - -Hashes two elements and retrieves a single field element output. - -| `poseidon_hash_single` -| `result = poseidon_hash_single(x)` -| `poseidon_hash_single(x: felt) -> (res: felt)` - -Hashes one element `x` and retrieves a single field element output. - -| `poseidon_hash_many` -| `result = poseidon_hash_many(n, y)` -| `poseidon_hash_many(n: felt, elements: felt*) -> (res: felt)` - -Hashes n elements and retrieves a single field element output. - -| `poseidon_hash_span` -| `result = poseidon_hash_span(data)` -| `poseidon_hash_span(mut span: Span) -> felt252` - -Computes the Pedersen hash of the given input `data`. - -| `<` -| `a < b` -| Less than comparison . - -| `\<=` -| `a \<= b` -| Less than or equal to comparison. - -| `==` -| `a == b` -| Equality comparison. - -| `!=` -| `a != b` -| Non-equality comparison. - -| `>` -| `a > b` -| Greater than comparison. - -| `>=` -| `a >= b` -| Greater than or equal to comparison. - -| `check_ecdsa_signature` -| `valid = check_ecdsa_signature(message, public_key, signature_r, signature_s)` -| Checks if (signature_r, signature_s) is a valid signature for the given public_key on the given message. - -Return TRUE if the signature is valid, FALSE otherwise. - -| `verify_ecdsa_signature` -| `verify_ecdsa_signature(message, public_key, signature_r, signature_s)` -| Verifies that the prover knows a signature of the given public_key on the given message. - -| `keccak_u256s_le_inputs` -| `keccak_u256s_le_inputs(input)` -| `keccak_u256s_le_inputs(mut input: Span) -> u256` - -Computes the keccak256 of multiple u256 values. - -The input values are interpreted as little-endian. - -The 32-byte result is represented as a little-endian u256. - -| `keccak_u256s_be_inputs` -| `keccak_u256s_be_inputs(input)` -| `keccak_u256s_be_inputs(mut input: Span) -> u256` - -Computes the keccak256 of multiple u256 values. - -The input values are interpreted as big-endian. - -The 32-byte result is represented as a little-endian u256. - -| `cairo_keccak` -| `cairo_keccak(input, last_input_word, last_input_num_bytes)` -| `cairo_keccak(ref input: Array, last_input_word: u64, last_input_num_bytes: usize) -> u256` - -Computes the keccak of `input` + `last_input_num_bytes` LSB bytes of `last_input_word`. - -To use this function, split the input into words of 64 bits (little endian). - -| `&` -| `a & b` -| Bitwise AND. - -| `\|` -| `a \| b` -| Bitwise OR. - -| `^` -| `a ^ b` -| Bitwise XOR. - -| `~` -| `~a` -| Bitwise NOT. - -| `ec_double` -| `ec_double(p)` -| Doubles a point (computes p + p) on the EC. - -| `ec_add` -| `ec_add(p, q)` -| Adds two points on the EC. - -| `ec_sub` -| `ec_sub(p, q)` -| Subtracts a point from another on the EC. - -| `ec_op` -| `ec_op(p, m, q)` -| `ec_op(p: EcPoint, m: felt, q: EcPoint) -> (r: EcPoint)` - -Computes p + m * q on the EC. - -| `ec_mul` -| `ec_mul(m, p)` -| `ec_mul(m: felt, p: EcPoint) -> (r: EcPoint)` - -Computes m * p on the EC. - -| `chained_ec_op` -| `chained_ec_op(p, m, q, len)` -| `chained_ec_op(p: EcPoint, m: felt*, q: EcPoint*, len: felt) -> (r: EcPoint)` - -Computes p + m[0] * q[0] + m[1] * q[1] + ... m[len - 1] * q[len - 1] on the EC. - -|=== - diff --git a/components/Starknet/modules/architecture_and_concepts/pages/Smart_Contracts/cairo-builtins.adoc b/components/Starknet/modules/architecture_and_concepts/pages/Smart_Contracts/cairo-builtins.adoc new file mode 100644 index 0000000000..6a78a78eb3 --- /dev/null +++ b/components/Starknet/modules/architecture_and_concepts/pages/Smart_Contracts/cairo-builtins.adoc @@ -0,0 +1,26 @@ +[id="cairo-builtins"] += Cairo builtins + +_Builtins_ in Cairo are predefined optimized low-level execution units that the Cairo VM refers to in order to perform predefined computations that are expensive to perform in standard Cairo. Builtins enhance the functionality of the Cairo VM, enabling you to perform certain tasks, such as using the Poseidon hash, range-checks, or ECDSA signature verifications, more efficiently, using less gas. + +In contrast to CairoZero, where you needed to consiously write code to take advantage of builitn optimizations, in Cairo, you simply write high-level code without doing anything special, and when the Cairo VM executes the code, certain operations take advantage of builtins to optimize logic and use less gas. + +[#list-of-cairo-builtins] +.List of Cairo builtins + +[cols="1,2",] +|=== +|Name of builtin | Description + +|Pedersen |Computes the Pedersen hash over two elements. For more information see xref:architecture_and_concepts:Cryptography/hash-functions.adoc[]. +|Poseidon |Computes the Hades permutation on three field elements. For more info, see xref to Hash functions topic. The Cairo corelib functions use this builtin under the hood. The Cairo corelib functions are defined in link:https://github.com/starkware-libs/cairo/blob/v2.6.0/corelib/src/starknet/info.cairo[`info.cairo`] in the Cairo GitHub repository. +|Range check a| +Checks whether a field element is in the range [0,2^128^-1]. + +All arithmetic comparisons use the range check builtin. + +|ECDSA |Verifies the validity of an ECDSA signature over the STARK curve. +|Keccak | _TBD_ +|Bitwise |Computes the bitwise operations `OR`, `AND`, and `XOR` of two felts. +|EC_OP |Multiplies a point on the STARK curve by a scalar. +|=== \ No newline at end of file