From 561eabc8908f385c2506ef8d5f29f8bdaa8f2768 Mon Sep 17 00:00:00 2001 From: Arcticae Date: Thu, 27 Jun 2024 17:01:03 +0200 Subject: [PATCH 1/2] Move documentation from the appendix to the cairo code & refine it --- sncast_std/src/lib.cairo | 155 ++++++++++++++++++++++++++++++++++++++- 1 file changed, 153 insertions(+), 2 deletions(-) diff --git a/sncast_std/src/lib.cairo b/sncast_std/src/lib.cairo index 1a46796ea2..bc6da764f7 100644 --- a/sncast_std/src/lib.cairo +++ b/sncast_std/src/lib.cairo @@ -113,6 +113,27 @@ impl DisplayCallResult of Display { } } +/// Calls a contract +/// - `contract_address` - address of the contract which will be called +/// - `function_selector` - hashed name of the target function (can be obtained with `selector!` macro) +/// - `calldata` - calldata for the function inputs, serialized with `Serde` +/// Returns [`CallResult`] with the returned data from the called function, or [`ScriptCommandError`] in case of failure +/// +/// Usage example: +/// ``` +/// use sncast_std::{call, CallResult}; +/// use starknet::{ContractAddress}; +/// +/// fn main() { +/// let contract_address: ContractAddress = 0x1e52f6ebc3e594d2a6dc2a0d7d193cb50144cfdfb7fdd9519135c29b67e427 +/// .try_into() +/// .expect('Invalid contract address value'); +/// +/// let call_result = call(contract_address, selector!("get"), array![0x1]).expect('call failed'); +/// println!("call_result: {}", call_result); +/// println!("debug call_result: {:?}", call_result); +/// } +/// ``` pub fn call( contract_address: ContractAddress, function_selector: felt252, calldata: Array:: ) -> Result { @@ -135,9 +156,12 @@ pub fn call( result_data } +/// Result of successfully submitting a `Declare` transaction #[derive(Drop, Clone, Debug, Serde)] pub struct DeclareResult { + /// Resulting class hash which was declared during the transaction pub class_hash: ClassHash, + /// A hash which references the transaction in which the declaration was made pub transaction_hash: felt252, } @@ -146,7 +170,27 @@ impl DisplayDeclareResult of Display { write!(f, "class_hash: {}, transaction_hash: {}", *self.class_hash, *self.transaction_hash) } } - +/// Declares a contract from the project on the network +/// - `contract_name` - name of a contract as Cairo string. +/// It is a name of the contract (part after `mod` keyword) e.g. `"HelloStarknet"`. +/// - `max_fee` - The fee in tokens you're willing to pay for the transaction. +/// If not provided, max fee will be automatically estimated via estimation endpoint. +/// - `nonce` - Account nonce for declare transaction. +/// If not provided, nonce will be set automatically (by fetching it from the account contract in the background). +/// Returns [`DeclareResult`] if declare was successful or a [`ScriptCommandError`] in case of failure +/// +/// Usage example: +/// ``` +/// use sncast_std::{declare, DeclareResult}; +/// +/// fn main() { +/// let max_fee = 9999999; +/// let declare_result = declare("HelloStarknet", Option::Some(max_fee), Option::None).expect('declare failed'); +/// +/// println!("declare_result: {}", declare_result); +/// println!("debug declare_result: {:?}", declare_result); +/// } +/// ``` pub fn declare( contract_name: ByteArray, max_fee: Option, nonce: Option ) -> Result { @@ -191,6 +235,45 @@ impl DisplayDeployResult of Display { } } +/// Submits a deployment transaction, via invocation of Universal Deployer Contract (UDC) +/// - `class_hash` - class hash (retrieved from [`declare`]) of a contract to deploy +/// - `constructor_calldata` - calldata for the constructor, serialized with `Serde` +/// - `salt` - optional salt for the contract address, used for providing address uniqueness +/// - `unique` - determines if the deployment should be origin dependent or not. + Origin independent calculation only takes into account class hash, salt and constructor arguments. + Origin dependent address calculation additionally includes account address and UDC address + in the resulting contracts' address. +/// - `max_fee` - The fee in tokens you're willing to pay for the transaction. +/// If not provided, max fee will be automatically estimated via estimation endpoint. +/// - `nonce` - Account nonce for declare transaction. +/// If not provided, nonce will be set automatically (by fetching it from the account contract in the background). +/// Returns `DeployResult` or `ScriptCommandError` in case of failure +/// +/// Usage example: +/// ``` +/// use sncast_std::{deploy, DeployResult}; +/// +/// fn main() { +/// let max_fee = 9999999; +/// let salt = 0x1; +/// let nonce = 0x1; +/// let class_hash: ClassHash = 0x03a8b191831033ba48ee176d5dde7088e71c853002b02a1cfa5a760aa98be046 +/// .try_into() +/// .expect('Invalid class hash value'); +/// +/// let deploy_result = deploy( +/// class_hash, +/// ArrayTrait::new(), +/// Option::Some(salt), +/// true, +/// Option::Some(max_fee), +/// Option::Some(nonce) +/// ).expect('deploy failed'); +/// +/// println!("deploy_result: {}", deploy_result); +/// println!("debug deploy_result: {:?}", deploy_result); +/// } +/// ``` pub fn deploy( class_hash: ClassHash, constructor_calldata: Array::, @@ -242,6 +325,34 @@ impl DisplayInvokeResult of Display { } } +/// Submits a transaction with given contracts' function invocation +/// - `contract_address` - address of the contract which will be invoked +/// - `entry_point_selector` - hashed name of the target function (can be obtained with `selector!` macro) +/// - `calldata` - inputs for the invoked function, serialized with `Serde` +/// - `max_fee` - The fee in tokens you're willing to pay for the transaction. +/// If not provided, max fee will be automatically estimated via estimation endpoint. +/// - `nonce` - Account nonce for declare transaction. +/// If not provided, nonce will be set automatically (by fetching it from the account contract in the background). +/// Returns `InvokeResult` or `ScriptCommandError` if *submitting* the transaction failed +/// +/// Usage example: +/// ``` +/// use sncast_std::{invoke, InvokeResult}; +/// use starknet::{ContractAddress}; +/// +/// fn main() { +/// let contract_address: ContractAddress = 0x1e52f6ebc3e594d2a6dc2a0d7d193cb50144cfdfb7fdd9519135c29b67e427 +/// .try_into() +/// .expect('Invalid contract address value'); +/// +/// let invoke_result = invoke( +/// contract_address, selector!("put"), array![0x1, 0x2], Option::None, Option::None +/// ).expect('invoke failed'); +/// +/// println!("invoke_result: {}", invoke_result); +/// println!("debug invoke_result: {:?}", invoke_result); +/// } +/// ``` pub fn invoke( contract_address: ContractAddress, entry_point_selector: felt252, @@ -276,17 +387,36 @@ pub fn invoke( result_data } +/// Gets nonce of an account for a given block tag +/// - `block_tag` - block tag name in form of shortstring (one of 'pending' or 'latest'). +/// Returns active accounts' nonce as `felt252`. +/// +/// Usage example: +/// ``` +/// use sncast_std::{get_nonce}; +/// +/// fn main() { +/// let nonce = get_nonce('latest'); +/// println!("nonce: {}", nonce); +/// println!("debug nonce: {:?}", nonce); +/// } +/// ``` pub fn get_nonce(block_tag: felt252) -> felt252 { let inputs = array![block_tag]; let buf = handle_cheatcode(cheatcode::<'get_nonce'>(inputs.span())); *buf[0] } +/// Represents the status in the transaction lifecycle and its' User -> L2 -> L1 journey #[derive(Drop, Clone, Debug, Serde, PartialEq)] pub enum FinalityStatus { + /// Transaction was received by the node successfully Received, + /// Transaction was rejected on stage of validation by sequencer Rejected, + /// Transaction was executed and entered an actual created block on L2 AcceptedOnL2, + /// The transaction was accepted on Ethereum AcceptedOnL1 } @@ -303,9 +433,12 @@ pub impl DisplayFinalityStatus of Display { } +/// Result of cairo code execution for the transaction after validation #[derive(Drop, Copy, Debug, Serde, PartialEq)] pub enum ExecutionStatus { + /// The transaction was successfully executed by the sequencer Succeeded, + /// The transaction passed validation but failed during execution in the sequencer Reverted, } @@ -319,10 +452,12 @@ pub impl DisplayExecutionStatus of Display { } } - +/// A structure representing status of the transaction execution after its' submission #[derive(Drop, Clone, Debug, Serde, PartialEq)] pub struct TxStatusResult { + /// Represents the status of the transaction in the L2 -> L1 pipeline pub finality_status: FinalityStatus, + /// Result of the cairo code execution. Present when the transaction was actually included in the block. pub execution_status: Option } @@ -337,6 +472,22 @@ pub impl DisplayTxStatusResult of Display { } } + +/// Gets the status of a transaction. Useful for assessment of completion status for the transaction. +/// - `transaction_hash` - A `felt252` representing hash of the transaction (i.e. result of `deploy`/`invoke`/`declare`) +/// Returns `TxStatusResult` or `ScriptCommandError` if retrieving the status failed +/// +/// Usage example: +/// ``` +/// use sncast_std::{tx_status}; +/// +/// fn main() { +/// let transaction_hash = 0x00ae35dacba17cde62b8ceb12e3b18f4ab6e103fa2d5e3d9821cb9dc59d59a3c; +/// let status = tx_status(transaction_hash).expect("Failed to get transaction status"); +/// +/// println!("transaction status: {:?}", status); +/// } +/// ``` pub fn tx_status(transaction_hash: felt252) -> Result { let mut inputs = array![transaction_hash]; From c3f00db08f52e08dcaeb103c6e8313445c73c5bf Mon Sep 17 00:00:00 2001 From: Arcticae Date: Thu, 27 Jun 2024 17:19:15 +0200 Subject: [PATCH 2/2] Fix syntax --- sncast_std/src/lib.cairo | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/sncast_std/src/lib.cairo b/sncast_std/src/lib.cairo index bc6da764f7..e648316b0b 100644 --- a/sncast_std/src/lib.cairo +++ b/sncast_std/src/lib.cairo @@ -240,9 +240,9 @@ impl DisplayDeployResult of Display { /// - `constructor_calldata` - calldata for the constructor, serialized with `Serde` /// - `salt` - optional salt for the contract address, used for providing address uniqueness /// - `unique` - determines if the deployment should be origin dependent or not. - Origin independent calculation only takes into account class hash, salt and constructor arguments. - Origin dependent address calculation additionally includes account address and UDC address - in the resulting contracts' address. +/// Origin independent calculation only takes into account class hash, salt and constructor arguments. +/// Origin dependent address calculation additionally includes account address and UDC address +/// in the resulting contracts' address. /// - `max_fee` - The fee in tokens you're willing to pay for the transaction. /// If not provided, max fee will be automatically estimated via estimation endpoint. /// - `nonce` - Account nonce for declare transaction.