docs: add docs for starknet-core (#636)

Author: xJonathanLEI

starknet-core/src/chain_id.rs

@@ -1,12 +1,14 @@
 use starknet_types_core::felt::Felt;
 
+/// The chain identifier for Starknet Mainnet. A Cairo short string encoding of `SN_MAIN`.
 pub const MAINNET: Felt = Felt::from_raw([
     502562008147966918,
     18446744073709551615,
     18446744073709551615,
     17696389056366564951,
 ]);
 
+/// The chain identifier for Starknet Goerli. A Cairo short string encoding of `SN_GOERLI`.
 #[deprecated = "The Goerli testnet has been shutdown"]
 pub const TESTNET: Felt = Felt::from_raw([
     398700013197595345,
@@ -15,6 +17,7 @@ pub const TESTNET: Felt = Felt::from_raw([
     3753493103916128178,
 ]);
 
+/// The chain identifier for Starknet Goerli 2. A Cairo short string encoding of `SN_GOERLI2`.
 #[deprecated = "The Goerli testnet has been shutdown"]
 pub const TESTNET2: Felt = Felt::from_raw([
     33650220878420990,
@@ -23,6 +26,7 @@ pub const TESTNET2: Felt = Felt::from_raw([
     1663542769632127759,
 ]);
 
+/// The chain identifier for Starknet Sepolia. A Cairo short string encoding of `SN_SEPOLIA`.
 pub const SEPOLIA: Felt = Felt::from_raw([
     507980251676163170,
     18446744073709551615,

starknet-core/src/crypto.rs

@@ -6,16 +6,23 @@ use starknet_crypto::{rfc6979_generate_k, sign, verify, SignError, VerifyError};
 mod errors {
     use core::fmt::{Display, Formatter, Result};
 
+    /// Errors when performing ECDSA [`sign`](fn.ecdsa_sign) operations.
     #[derive(Debug)]
     pub enum EcdsaSignError {
+        /// The message hash is not in the range of `[0, 2^251)`.
         MessageHashOutOfRange,
     }
 
     #[derive(Debug)]
+    /// Errors when performing ECDSA [`verify`](fn.ecdsa_verify) operations.
     pub enum EcdsaVerifyError {
+        /// The message hash is not in the range of `[0, 2^251)`.
         MessageHashOutOfRange,
+        /// The public key is not a valid point on the STARK curve.
         InvalidPublicKey,
+        /// The `r` value is not in the range of `[0, 2^251)`.
         SignatureROutOfRange,
+        /// The `s` value is not in the range of `[0, 2^251)`.
         SignatureSOutOfRange,
     }
 
@@ -46,6 +53,16 @@ mod errors {
 }
 pub use errors::{EcdsaSignError, EcdsaVerifyError};
 
+/// Computes the Pedersen hash of a list of [`Felt`].
+///
+/// The hash is computed by starting with `0`, hashing it recursively against all elements in
+/// the list, and finally also hashing against the length of the list.
+///
+/// For example, calling `compute_hash_on_elements([7, 8])` would return:
+///
+/// ```markdown
+/// pedersen_hash(pedersen_hash(pedersen_hash(0, 7)), 8), 2)
+/// ```
 pub fn compute_hash_on_elements<'a, ESI, II>(data: II) -> Felt
 where
     ESI: ExactSizeIterator<Item = &'a Felt>,
@@ -62,6 +79,8 @@ where
     pedersen_hash(&current_hash, &data_len)
 }
 
+/// Signs a hash using deterministic ECDSA on the STARK curve. The signature returned can be used
+/// to recover the public key.
 pub fn ecdsa_sign(
     private_key: &Felt,
     message_hash: &Felt,
@@ -89,6 +108,7 @@ pub fn ecdsa_sign(
     }
 }
 
+/// Verified an ECDSA signature on the STARK curve.
 pub fn ecdsa_verify(
     public_key: &Felt,
     message_hash: &Felt,

starknet-core/src/lib.rs

@@ -1,15 +1,22 @@
+//! Core data types and utilities for Starknet.
+
+#![deny(missing_docs)]
 #![cfg_attr(not(feature = "std"), no_std)]
 #![allow(clippy::comparison_chain)]
-#![doc = include_str!("../README.md")]
 
+/// Module containing custom serialization/deserialization implementations.
 pub mod serde;
 
+/// Module containing core types for representing objects in Starknet.
 pub mod types;
 
+/// High-level utilities for cryptographic operations used in Starknet.
 pub mod crypto;
 
+/// Utilities for performing commonly used algorithms in Starknet.
 pub mod utils;
 
+/// Chain IDs for commonly used public Starknet networks.
 pub mod chain_id;
 
 extern crate alloc;

starknet-core/src/serde/byte_array.rs

@@ -1,3 +1,4 @@
+/// Serializing and deserializing [`Vec<u8>`] with base64 encoding.
 pub mod base64 {
     use alloc::{fmt::Formatter, format, vec::*};
 
@@ -6,6 +7,7 @@ pub mod base64 {
 
     struct Base64Visitor;
 
+    /// Serializes [`Vec<u8>`] as base64 string.
     pub fn serialize<S, T>(value: T, serializer: S) -> Result<S::Ok, S::Error>
     where
         S: Serializer,
@@ -14,6 +16,7 @@ pub mod base64 {
         serializer.serialize_str(&STANDARD.encode(value.as_ref()))
     }
 
+    /// Deserializes [`Vec<u8>`] from base64 string.
     pub fn deserialize<'de, D>(deserializer: D) -> Result<Vec<u8>, D::Error>
     where
         D: Deserializer<'de>,

starknet-core/src/serde/mod.rs

@@ -1,5 +1,7 @@
+/// Custom serialization/deserialization implementations for [`Vec<u8>`].
 pub mod byte_array;
 
+/// Custom serialization/deserialization implementations for [`Felt`].
 pub mod unsigned_field_element;
 
 pub(crate) mod num_hex;

starknet-core/src/serde/unsigned_field_element.rs

@@ -12,12 +12,16 @@ use starknet_types_core::felt::Felt;
 const PRIME: U256 =
     U256::from_be_hex("0800000000000011000000000000000000000000000000000000000000000001");
 
+/// Serialize/deserialize [`Felt`] as hex strings. For use with `serde_with`.
 #[derive(Debug)]
 pub struct UfeHex;
 
+/// Serialize/deserialize [`Option<Felt>`] as hex strings. For use with `serde_with`.
 #[derive(Debug)]
 pub struct UfeHexOption;
 
+/// Serialize/deserialize [`Option<Felt>`] as hex strings in a pending block hash context. For use
+/// with `serde_with`.
 #[derive(Debug)]
 pub struct UfePendingBlockHash;
 

starknet-core/src/types/codegen.rs

@@ -3,7 +3,7 @@
 //     https://github.com/xJonathanLEI/starknet-jsonrpc-codegen
 
 // Code generated with version:
-//     https://github.com/xJonathanLEI/starknet-jsonrpc-codegen#fbd3aed2a08d6b29328e87ee0bbfb7e80f7051b0
+//     https://github.com/xJonathanLEI/starknet-jsonrpc-codegen#f1278dfb2ae57d319093421c038f6ec7a3dfba2f
 
 // These types are ignored from code generation. Implement them manually:
 // - `RECEIPT_BLOCK`
@@ -24,6 +24,7 @@
 // - `TXN`
 // - `TXN_RECEIPT`
 
+#![allow(missing_docs)]
 #![allow(clippy::doc_markdown)]
 #![allow(clippy::missing_const_for_fn)]