From 006fbca1b1ef194bc6a6bf510e61ce634b5299d1 Mon Sep 17 00:00:00 2001 From: Jonathan LEI Date: Mon, 29 Jul 2024 16:38:18 +0800 Subject: [PATCH] docs: add docs for `starknet-contract` --- starknet-contract/src/factory.rs | 35 ++++++++++++++++++++++++++++++++ starknet-contract/src/lib.rs | 12 ++++++++++- 2 files changed, 46 insertions(+), 1 deletion(-) diff --git a/starknet-contract/src/factory.rs b/starknet-contract/src/factory.rs index 299ff0f1..57e25f61 100644 --- a/starknet-contract/src/factory.rs +++ b/starknet-contract/src/factory.rs @@ -20,6 +20,8 @@ const SELECTOR_DEPLOYCONTRACT: Felt = Felt::from_raw([ 18249998464715511309, ]); +/// A contract factory that acts as a blueprint for deploying Starknet smart contracts using the +/// Universal Deployer Contract. #[derive(Debug)] pub struct ContractFactory { class_hash: Felt, @@ -62,10 +64,15 @@ pub struct DeploymentV3<'f, A> { } impl ContractFactory { + /// Constructs a new [`ContractFactory`] from a class hash and an account. + /// + /// The [`ContractFactory`] created uses the default address for the Universal Deployer + /// Contract. To use a custom UDC deployment, use [`new_with_udc`](fn.new_with_udc) instead. pub const fn new(class_hash: Felt, account: A) -> Self { Self::new_with_udc(class_hash, account, UDC_ADDRESS) } + /// Constructs a new [`ContractFactory`] with a custom Universal Deployer Contract address. pub const fn new_with_udc(class_hash: Felt, account: A, udc_address: Felt) -> Self { Self { class_hash, @@ -79,6 +86,8 @@ impl ContractFactory where A: Account, { + /// Generates an instance of [`DeploymentV1`] for sending `INVOKE` v1 transactions for the + /// contract deployment. Pays transaction fees in `ETH`. pub const fn deploy_v1( &self, constructor_calldata: Vec, @@ -96,6 +105,8 @@ where } } + /// Generates an instance of [`DeploymentV3`] for sending `INVOKE` v3 transactions for the + /// contract deployment. Pays transaction fees in `STRK`. pub const fn deploy_v3( &self, constructor_calldata: Vec, @@ -115,6 +126,8 @@ where } } + /// Generates an instance of [`DeploymentV1`] for sending `INVOKE` v1 transactions for the + /// contract deployment. Pays transaction fees in `ETH`. #[deprecated = "use version specific variants (`deploy_v1` & `deploy_v3`) instead"] pub const fn deploy( &self, @@ -127,6 +140,7 @@ where } impl<'f, A> DeploymentV1<'f, A> { + /// Returns a new [`DeploymentV1`] with the `nonce`. pub fn nonce(self, nonce: Felt) -> Self { Self { nonce: Some(nonce), @@ -134,6 +148,7 @@ impl<'f, A> DeploymentV1<'f, A> { } } + /// Returns a new [`DeploymentV1`] with the `max_fee`. pub fn max_fee(self, max_fee: Felt) -> Self { Self { max_fee: Some(max_fee), @@ -141,6 +156,9 @@ impl<'f, A> DeploymentV1<'f, A> { } } + /// Returns a new [`DeploymentV1`] with the fee estimate multiplier. The multiplier is used + /// when transaction fee is not manually specified and must be fetched from a + /// [`Provider`](starknet_providers::Provider) instead. pub fn fee_estimate_multiplier(self, fee_estimate_multiplier: f64) -> Self { Self { fee_estimate_multiplier, @@ -150,6 +168,7 @@ impl<'f, A> DeploymentV1<'f, A> { } impl<'f, A> DeploymentV3<'f, A> { + /// Returns a new [`DeploymentV3`] with the `nonce`. pub fn nonce(self, nonce: Felt) -> Self { Self { nonce: Some(nonce), @@ -157,6 +176,7 @@ impl<'f, A> DeploymentV3<'f, A> { } } + /// Returns a new [`DeploymentV3`] with the `gas`. pub fn gas(self, gas: u64) -> Self { Self { gas: Some(gas), @@ -164,6 +184,7 @@ impl<'f, A> DeploymentV3<'f, A> { } } + /// Returns a new [`DeploymentV3`] with the `gas_price`. pub fn gas_price(self, gas_price: u128) -> Self { Self { gas_price: Some(gas_price), @@ -171,6 +192,9 @@ impl<'f, A> DeploymentV3<'f, A> { } } + /// Returns a new [`DeploymentV3`] with the gas amount estimate multiplier. The multiplier is + /// used when the gas amount is not manually specified and must be fetched from a + /// [`Provider`](starknet_providers::Provider) instead. pub fn gas_estimate_multiplier(self, gas_estimate_multiplier: f64) -> Self { Self { gas_estimate_multiplier, @@ -178,6 +202,9 @@ impl<'f, A> DeploymentV3<'f, A> { } } + /// Returns a new [`DeploymentV3`] with the gas price estimate multiplier. The multiplier is + /// used when the gas price is not manually specified and must be fetched from a + /// [`Provider`](starknet_providers::Provider) instead. pub fn gas_price_estimate_multiplier(self, gas_price_estimate_multiplier: f64) -> Self { Self { gas_price_estimate_multiplier, @@ -234,11 +261,14 @@ impl<'f, A> DeploymentV1<'f, A> where A: ConnectedAccount + Sync, { + /// Estimates transaction fees from a [`Provider`](starknet_providers::Provider). pub async fn estimate_fee(&self) -> Result> { let execution: ExecutionV1<'_, A> = self.into(); execution.estimate_fee().await } + /// Simulates the transaction from a [`Provider`](starknet_providers::Provider). Transaction + /// validation and fee transfer can be skipped. pub async fn simulate( &self, skip_validate: bool, @@ -248,6 +278,7 @@ where execution.simulate(skip_validate, skip_fee_charge).await } + /// Signs and broadcasts the transaction to the network. pub async fn send(&self) -> Result> { let execution: ExecutionV1<'_, A> = self.into(); execution.send().await @@ -258,11 +289,14 @@ impl<'f, A> DeploymentV3<'f, A> where A: ConnectedAccount + Sync, { + /// Estimates transaction fees from a [`Provider`](starknet_providers::Provider). pub async fn estimate_fee(&self) -> Result> { let execution: ExecutionV3<'_, A> = self.into(); execution.estimate_fee().await } + /// Simulates the transaction from a [`Provider`](starknet_providers::Provider). Transaction + /// validation and fee transfer can be skipped. pub async fn simulate( &self, skip_validate: bool, @@ -272,6 +306,7 @@ where execution.simulate(skip_validate, skip_fee_charge).await } + /// Signs and broadcasts the transaction to the network. pub async fn send(&self) -> Result> { let execution: ExecutionV3<'_, A> = self.into(); execution.send().await diff --git a/starknet-contract/src/lib.rs b/starknet-contract/src/lib.rs index cec06190..2a37967e 100644 --- a/starknet-contract/src/lib.rs +++ b/starknet-contract/src/lib.rs @@ -1,2 +1,12 @@ +//! Library for deploying and interacting with Starknet contracts. +//! +//! Currently, this crate only provides a single type [`ContractFactory`] for deploying contracts +//! using the Universal Deployer Contract. +//! +//! In the future, features like ABI-based contract binding generation will be added to allow type- +//! safe interaction with Starknet smart contracts. + +#![deny(missing_docs)] + mod factory; -pub use factory::ContractFactory; +pub use factory::{ContractFactory, DeploymentV1, DeploymentV3};