Core Lib Documentation: Starknet module (#6895)

Co-authored-by: enitrat <[email protected]>

Author: TAdev0

corelib/src/starknet.cairo

@@ -1,3 +1,19 @@
+//! Functionalities for interacting with the Starknet network.
+//!
+//! # Core Components
+//!
+//! - **Storage**: The `storage` module defines abstractions on how to interact with Starknet
+//! contract storage.
+//! - **Syscalls**: The `syscalls` module contains the extern declarations for all the system calls
+//! available in Starknet.
+//! - **Contract Addresses**: The `contract_address` and `eth_address` modules provide types and
+//! utilities for working with Starknet contract addresses and Ethereum addresses.
+//! - **Cryptography**: The `secp256k1`, `secp256r1`, `secp256_trait`, and `eth_signature` modules
+//! handle various elliptic curve operations.
+//! - **Execution Info**: The `info` module exposes functions for accessing information about the
+//! current contract execution, such as the caller address, contract address, block info, and
+//! transaction info.
+
 #[allow(unused_imports)]
 use core::box::Box;
 #[allow(unused_imports)]
@@ -9,9 +25,7 @@ use core::traits::{Into, TryInto};
 #[allow(unused_imports)]
 use core::zeroable::Zeroable;
 
-/// Store trait and implementations for various types.
 pub mod storage_access;
-/// Re-imports
 pub use storage_access::{Store, StorageAddress};
 #[allow(unused_imports)]
 use storage_access::{
@@ -20,7 +34,6 @@ use storage_access::{
     storage_address_try_from_felt252,
 };
 
-/// Module containing all the extern declaration of the syscalls.
 pub mod syscalls;
 #[allow(unused_imports)]
 use syscalls::{
@@ -30,12 +43,10 @@ use syscalls::{
     get_class_hash_at_syscall,
 };
 
-/// secp256
 pub mod secp256_trait;
 pub mod secp256k1;
 pub mod secp256r1;
 
-/// ContractAddress
 pub mod contract_address;
 pub use contract_address::{ContractAddress, contract_address_const};
 #[allow(unused_imports)]
@@ -44,20 +55,17 @@ use contract_address::{
     contract_address_try_from_felt252,
 };
 
-/// EthAddress
 pub mod eth_address;
 pub use eth_address::EthAddress;
 #[allow(unused_imports)]
 use eth_address::{
     EthAddressIntoFelt252, EthAddressSerde, EthAddressZeroable, Felt252TryIntoEthAddress,
 };
 
-/// EthSignature
 pub mod eth_signature;
 #[allow(unused_imports)]
 use eth_signature::verify_eth_signature;
 
-/// ClassHash
 pub mod class_hash;
 pub use class_hash::ClassHash;
 #[allow(unused_imports)]
@@ -66,7 +74,7 @@ use class_hash::{
     class_hash_try_from_felt252,
 };
 
-/// Not `pub` on purpose, only used for direct reexport by the next line.
+// Not `pub` on purpose, only used for direct reexport by the next line.
 mod info;
 pub use info::{
     v2::ExecutionInfo as ExecutionInfo, BlockInfo, v2::TxInfo as TxInfo, get_execution_info,
@@ -80,91 +88,37 @@ pub use event::Event;
 pub mod account;
 pub use account::AccountContract;
 
-/// This module contains the storage-related types and traits for Cairo contracts. It provides
-/// abstractions for reading and writing to Starknet storage.
-///
-/// The front facing interface for the user is simple and intuitive, for example consider the
-/// following storage struct:
-/// ```
-/// #[storage]
-/// struct Storage {
-///     a: felt252,
-///     b: Map<felt252, felt52>,
-///     c: Map<felt52, Map<felt52, felt52>>,
-/// }
-/// ```
-/// The user can access the storage members `a` and `b` using the following code:
-/// ```
-/// fn use_storage(self: @ContractState) {
-///     let a_value = self.a.read();
-///     // For a Map, the user can use the `entry` method to access the value at a specific key:
-///     let b_value = self.b.entry(42).read();
-///     // Or simply pass the key to the `read` method:
-///     let b_value = self.b.read(42);
-///     // Accessing a nested Map must be done using the `entry` method, either:
-///     let c_value = self.c.entry(42).entry(43).read()
-///     // Or:
-///     let c_value = self.c.entry(42).read(43);
-/// }
-///  ```
-///
-/// Under the hood, the storage access is more complex. The life cycle of a storage object is as
-/// follows:
-/// 1. The storage struct of a contract is represented by a `FlattenedStorage` struct, which
-///    can be derefed into a struct containing a member for each storage member of the contract.
-///    This member can be either a `StorageBase` or a `FlattenedStorage` instance. Members are
-///    represented as a `FlattenedStorage` if the storage member is attributed with either
-///    `#[substorage(v0)]` (for backward compatibility) or `#[flat]`. `FlattenedStorage` is used to
-///    structure the storage access; however, it does not affect the address of the storage object.
-/// 2. `StorageBase` members of a `FlattenedStorage` struct hold a single `felt252` value, which is
-///    the Keccak hash of the name of the member. For simple types, this value will be the address
-///    of the member in the storage.
-/// 3. `StorageBase` members are then converted to `StoragePath` instances, which are essentially
-///    a wrapper around a `HashState` instance, used to account for more values when computing the
-///    address of the storage object. `StoragePath` instances can be updated with values coming from
-///    two sources:
-///     - Storage nodes, which are structs that represent another struct with all its members
-///       in the storage, similar to `FlattenedStorage`. However, unlike `FlattenedStorage`, the
-///       path to the storage node does affect the address of the storage object. See `StorageNode`
-///       for more details.
-///     - Storage collections, specifically `Map` and `Vec`, simulate the behavior of collections by
-///       updating the hash state with the key or index of the collection member.
-/// 4. After finishing the updates, the `StoragePath` instance is finalized, resulting in a
-///    `StoragePointer0Offset` instance, which is a pointer to the address of the storage object. If
-///    the pointer is to an object of size greater than 1, the object is stored in a sequential
-///    manner starting from the address of the pointer. The whole object can be read or written
-///    using `read` and `write` methods, and specific members can also be accessed in the case of a
-///    struct. See `SubPointers` for more details.
-///
-/// The transitioning between the different types of storage objects is also called from the
-/// `Deref` trait, and thus, allowing an access to the members of the storage object in a simple
-/// way.
-///
-/// The types mentioned above are generic in the stored object type. This is done to provide
-/// specific behavior for each type of stored object, e.g., a `StoragePath` of `Map` type will have
-/// an `entry` method, but it won't have a `read` or `write` method, as `Map` is not storable by
-/// itself, only its values are.
-/// The generic type of the storage object can also be wrapped with a `Mutable` type, which
-/// indicates that the storage object is mutable, i.e., it was created from a `ref` contract state,
-/// and thus the object can be written to.
 pub mod storage;
 
 pub extern type System;
 
-/// An Helper function to force the inclusion of `System` in the list of implicits.
+// A helper function to force the inclusion of `System` in the list of implicits.
 #[deprecated(
     feature: "use_system_implicit",
     note: "Use `core::internal::require_implicit::<System>` instead.",
 )]
 fn use_system_implicit() implicits(System) {}
 
-/// The result type for a syscall.
+/// The `Result` type for a syscall.
 pub type SyscallResult<T> = Result<T, Array<felt252>>;
 
+/// Trait for handling syscalls results.
 pub trait SyscallResultTrait<T> {
-    /// If `val` is `Result::Ok(x)`, returns `x`. Otherwise, panics with the revert reason.
+    /// Unwraps a syscall result, yielding the content of an `Ok`.
+    ///
+    /// # Panics
+    ///
+    /// Panics with the syscall error message if the value is an `Err`.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// let result = starknet::syscalls::get_execution_info_v2_syscall();
+    /// let info = result.unwrap_syscall();
+    /// ```
     fn unwrap_syscall(self: SyscallResult<T>) -> T;
 }
+
 impl SyscallResultTraitImpl<T> of SyscallResultTrait<T> {
     fn unwrap_syscall(self: SyscallResult<T>) -> T {
         match self {
@@ -174,10 +128,11 @@ impl SyscallResultTraitImpl<T> of SyscallResultTrait<T> {
     }
 }
 
-/// The expected return value of the `__validate*__` functions of an accounted contract.
+/// The expected return value of the `__validate__` function in account contracts.
+///
+/// This constant is used to indicate that a transaction validation was successful.
+/// Account contracts must return this value from their `__validate__` function to
+/// signal that the transaction should proceed.
 pub const VALIDATED: felt252 = 'VALID';
 
-/// Module for starknet testing only.
-/// Provides functions useful for testing event emission, starknet state information, and the
-/// cheatcode concept in general.
 pub mod testing;

corelib/src/starknet/storage.cairo

@@ -1,3 +1,74 @@
+//! Contains the storage-related types and traits for Cairo contracts and provides abstractions for
+//! reading and writing to Starknet storage.
+//!
+//! The front facing interface for the user is simple and intuitive, for example consider the
+//! following storage struct:
+//!
+//! ```
+//! #[storage]
+//! struct Storage {
+//!     a: felt252,
+//!     b: Map<felt252, felt52>,
+//!     c: Map<felt52, Map<felt52, felt52>>,
+//! }
+//! ```
+//!
+//! The user can access the storage members `a` and `b` using the following code:
+//!
+//! ```
+//! fn use_storage(self: @ContractState) {
+//!     let a_value = self.a.read();
+//!     // For a Map, the user can use the `entry` method to access the value at a specific key:
+//!     let b_value = self.b.entry(42).read();
+//!     // Or simply pass the key to the `read` method:
+//!     let b_value = self.b.read(42);
+//!     // Accessing a nested Map must be done using the `entry` method, either:
+//!     let c_value = self.c.entry(42).entry(43).read()
+//!     // Or:
+//!     let c_value = self.c.entry(42).read(43);
+//! }
+//!  ```
+//!
+//! Under the hood, the storage access is more complex. The life cycle of a storage object is as
+//! follows:
+//! 1. The storage struct of a contract is represented by a `FlattenedStorage` struct, which
+//!    can be derefed into a struct containing a member for each storage member of the contract.
+//!    This member can be either a `StorageBase` or a `FlattenedStorage` instance. Members are
+//!    represented as a `FlattenedStorage` if the storage member is attributed with either
+//!    `#[substorage(v0)]` (for backward compatibility) or `#[flat]`. `FlattenedStorage` is used to
+//!    structure the storage access; however, it does not affect the address of the storage object.
+//! 2. `StorageBase` members of a `FlattenedStorage` struct hold a single `felt252` value, which is
+//!    the Keccak hash of the name of the member. For simple types, this value will be the address
+//!    of the member in the storage.
+//! 3. `StorageBase` members are then converted to `StoragePath` instances, which are essentially
+//!    a wrapper around a `HashState` instance, used to account for more values when computing the
+//!    address of the storage object. `StoragePath` instances can be updated with values coming from
+//!    two sources:
+//!     - Storage nodes, which are structs that represent another struct with all its members
+//!       in the storage, similar to `FlattenedStorage`. However, unlike `FlattenedStorage`, the
+//!       path to the storage node does affect the address of the storage object. See `StorageNode`
+//!       for more details.
+//!     - Storage collections, specifically `Map` and `Vec`, simulate the behavior of collections by
+//!       updating the hash state with the key or index of the collection member.
+//! 4. After finishing the updates, the `StoragePath` instance is finalized, resulting in a
+//!    `StoragePointer0Offset` instance, which is a pointer to the address of the storage object. If
+//!    the pointer is to an object of size greater than 1, the object is stored in a sequential
+//!    manner starting from the address of the pointer. The whole object can be read or written
+//!    using `read` and `write` methods, and specific members can also be accessed in the case of a
+//!    struct. See `SubPointers` for more details.
+//!
+//! The transitioning between the different types of storage objects is also called from the
+//! `Deref` trait, and thus, allowing an access to the members of the storage object in a simple
+//! way.
+//!
+//! The types mentioned above are generic in the stored object type. This is done to provide
+//! specific behavior for each type of stored object, e.g., a `StoragePath` of `Map` type will have
+//! an `entry` method, but it won't have a `read` or `write` method, as `Map` is not storable by
+//! itself, only its values are.
+//! The generic type of the storage object can also be wrapped with a `Mutable` type, which
+//! indicates that the storage object is mutable, i.e., it was created from a `ref` contract state,
+//! and thus the object can be written to.
+
 use core::traits::Into;
 #[allow(unused_imports)]
 use core::pedersen::HashState;