feat: add page for describing cairo builtins

components/Starknet/modules/architecture_and_concepts/nav.adoc

@@ -31,6 +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/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]

components/Starknet/modules/architecture_and_concepts/pages/Smart_Contracts/builtins.adoc

@@ -0,0 +1,152 @@
+[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>) -> 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>) -> 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>) -> 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<u64>, 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.
+
+|===
+