feat: add pages for describing cairo builtins

components/Starknet/modules/architecture_and_concepts/nav.adoc

@@ -32,6 +32,7 @@
 *** 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/system-calls-cairo1.adoc[System calls]
+*** 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]

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

@@ -0,0 +1,236 @@
+= Cairo Builtins
+
+== Introduction
+
+Cairo builtins are pre-defined functions provided by the Cairo runtime environment. They serve as fundamental tools for you, as a developer, to efficiently implement various operations within the Cairo smart contract language. These builtins cover a wide range of functionalities, including arithmetic operations, bitwise manipulations, memory access, cryptographic computations, and more. By leveraging Cairo builtins, you can write concise and optimized smart contracts that execute securely and efficiently on the Cairo virtual machine.
+
+Here are some general characteristics and purposes of Cairo builtins:
+
+1. **Efficiency**: Cairo builtins are optimized for performance, allowing you to execute complex operations with minimal overhead.
+
+2. **Security**: Builtins provide essential cryptographic functions, such as hashing and signature verification, enabling you to implement secure and tamper-resistant smart contracts.
+
+3. **Functionality**: Cairo builtins cover a broad spectrum of functionalities, including arithmetic operations (addition, subtraction, multiplication, division), bitwise operations (AND, OR, XOR, NOT), memory access (array manipulation), and cryptographic computations.
+
+4. **Interoperability**: Builtins facilitate interoperability between smart contracts by providing standard functions for common operations, ensuring consistency and compatibility across different contract implementations.
+
+5. **Customizability**: While Cairo builtins offer a rich set of functionalities out-of-the-box, you can extend the capabilities of your smart contracts by combining builtins creatively and implementing custom functions as needed.
+
+
+== List of Cairo Builtins
+
+[cols="1,2,2"]
+|===
+| Symbol | Example | Explanation
+
+| `+`
+| `a + b`
+| Arithmetic addition.
+
+| `+=`
+| `a += b`
+| Arithmetic addition and assignment.
+
+| `-`
+| `a - b`
+| Arithmetic subtraction.
+
+| `-=`
+| `a -= b`
+| Arithmetic subtraction and assignment.
+
+| `*`
+| `a * b`
+| Arithmetic multiplication.
+
+| `*=`
+|`a *= b`
+| Arithmetic multiplication and assignment.
+
+
+| `/`
+| `a / b`
+| Arithmetic division.
+
+| `/=`
+| `a /= b`
+| Arithmetic division and assignment.
+
+| `%`
+| `a % b`
+| Arithmetic remainder.
+
+| `%=`
+| `a %= b`
+| Arithmetic remainder and assignment.
+
+| `-`
+| `-a`
+| Arithmetic negation.
+
+| `&&`
+| `a && b`
+| Short-circuiting logical AND.
+
+| `\|\|`
+| `a \|\| b`
+| Short-circuiting logical OR.
+
+| `!`
+| `!a`
+| Short-circuiting logical NOT.
+
+| `&`
+| `a & b`
+| Bitwise AND.
+
+| `\|`
+| `a \| b`
+| Bitwise OR.
+
+| `^`
+| `a ^ b`
+| Bitwise XOR.
+
+| `~`
+| `~a`
+| Bitwise NOT.
+
+| `<`
+| `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.
+
+| `hash2`
+| `result = hash2(x, y)`
+| `hash2(x: felt, y: felt) -> (res: felt)`
+
+Hashes two elements and retrieves a single field element output.
+
+| `pedersen_hash`
+| `result = pedersen_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`.
+
+| `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.
+
+| `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.
+
+| `cairo_keccak_uint256s`
+| `cairo_keccak_uint256s(n, elements)`
+| `cairo_keccak_uint256s(n_elements: felt, elements: Uint256*) -> (res: Uint256)`
+
+Computes the keccak hash of multiple uint256 numbers (big-endian).
+
+Note that both the output and the input are in big endian representation.
+
+| `cairo_keccak_felts`
+| `cairo_keccak_felts(n, elements)`
+| `cairo_keccak_felts(n_elements: felt, elements: Uint256*) -> (res: Uint256)`
+
+Computes the keccak hash of multiple field elements.
+
+| `cairo_keccak_felts_bigend`
+| `cairo_keccak_felts_bigend(n, elements)`
+| `cairo_keccak_felts_bigend(n_elements: felt, elements: Uint256*) -> (res: Uint256)`
+
+Computes the keccak hash of multiple field elements (big-endian).
+
+| `cairo_keccak`
+| `cairo_keccak(inputs, n)`
+| `cairo_keccak(inputs: felt*, n_bytes: felt) -> (res: Uint256)`
+
+Computes the keccak of input.
+
+To use this function, split the input into words of 64 bits (little endian).
+
+| `cairo_keccak_bigend`
+| `cairo_keccak_bigend(inputs, n)`
+| `cairo_keccak_bigend(inputs: felt*, n_bytes: felt) -> (res: Uint256)`
+
+Same as cairo_keccak, but outputs the hash in big endian representation.
+
+Note that the input is little endian.
+
+| `cairo_keccak_as_words`
+| `cairo_keccak_as_words(inputs, n)`
+| `cairo_keccak_as_words(inputs: felt*, n_bytes: felt) -> (res: Uint256)`
+
+Same as cairo_keccak, but outputs a pointer to 4 64-bit little endian words instead.
+
+|===
+