Skip to content

Commit

Permalink
docs: add docs for starknet-accounts
Browse files Browse the repository at this point in the history
  • Loading branch information
@xJonathanLEI
xJonathanLEI committed Jul 29, 2024
1 parent d297f81 commit 46ae4b4
Show file tree
Hide file tree
Showing 9 changed files with 303 additions and 4 deletions.
61 changes: 61 additions & 0 deletions starknet-accounts/src/account/declaration.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -52,6 +52,10 @@ const QUERY_VERSION_THREE: Felt = Felt::from_raw([
]);

impl<'a, A> DeclarationV2<'a, A> {
/// Constructs a new [`DeclarationV2`].
///
/// Users would typically use [`declare_v2`](fn.declare_v2) on an [`Account`] instead of
/// directly calling this method.
pub const fn new(
contract_class: Arc<FlattenedSierraClass>,
compiled_class_hash: Felt,
Expand All @@ -67,20 +71,25 @@ impl<'a, A> DeclarationV2<'a, A> {
}
}

/// Returns a new [`DeclarationV2`] with the `nonce`.
pub fn nonce(self, nonce: Felt) -> Self {
Self {
nonce: Some(nonce),
..self
}
}

/// Returns a new [`DeclarationV2`] with the `max_fee`.
pub fn max_fee(self, max_fee: Felt) -> Self {
Self {
max_fee: Some(max_fee),
..self
}
}

/// Returns a new [`DeclarationV2`] with the fee estimate multiplier. The multiplier is used
/// when transaction fee is not manually specified and must be fetched from a [`Provider`]
/// instead.
pub fn fee_estimate_multiplier(self, fee_estimate_multiplier: f64) -> Self {
Self {
fee_estimate_multiplier,
Expand Down Expand Up @@ -110,6 +119,7 @@ impl<'a, A> DeclarationV2<'a, A>
where
A: ConnectedAccount + Sync,
{
/// Estimates transaction fees from a [`Provider`].
pub async fn estimate_fee(&self) -> Result<FeeEstimate, AccountError<A::SignError>> {
// Resolves nonce
let nonce = match self.nonce {
Expand All @@ -124,6 +134,8 @@ where
self.estimate_fee_with_nonce(nonce).await
}

/// Simulates the transaction from a [`Provider`]. Transaction validation and fee transfer can
/// be skipped.
pub async fn simulate(
&self,
skip_validate: bool,
Expand All @@ -143,6 +155,7 @@ where
.await
}

/// Signs and broadcasts the transaction to the network.
pub async fn send(&self) -> Result<DeclareTransactionResult, AccountError<A::SignError>> {
self.prepare().await?.send().await
}
Expand Down Expand Up @@ -275,6 +288,10 @@ where
}

impl<'a, A> DeclarationV3<'a, A> {
/// Constructs a new [`DeclarationV3`].
///
/// Users would typically use [`declare_v3`](fn.declare_v3) on an [`Account`] instead of
/// directly calling this method.
pub const fn new(
contract_class: Arc<FlattenedSierraClass>,
compiled_class_hash: Felt,
Expand All @@ -292,34 +309,43 @@ impl<'a, A> DeclarationV3<'a, A> {
}
}

/// Returns a new [`DeclarationV3`] with the `nonce`.
pub fn nonce(self, nonce: Felt) -> Self {
Self {
nonce: Some(nonce),
..self
}
}

/// Returns a new [`DeclarationV3`] with the `gas`.
pub fn gas(self, gas: u64) -> Self {
Self {
gas: Some(gas),
..self
}
}

/// Returns a new [`DeclarationV3`] with the `gas_price`.
pub fn gas_price(self, gas_price: u128) -> Self {
Self {
gas_price: Some(gas_price),
..self
}
}

/// Returns a new [`DeclarationV3`] 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`]
/// instead.
pub fn gas_estimate_multiplier(self, gas_estimate_multiplier: f64) -> Self {
Self {
gas_estimate_multiplier,
..self
}
}

/// Returns a new [`DeclarationV3`] 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`]
/// instead.
pub fn gas_price_estimate_multiplier(self, gas_price_estimate_multiplier: f64) -> Self {
Self {
gas_price_estimate_multiplier,
Expand Down Expand Up @@ -351,6 +377,7 @@ impl<'a, A> DeclarationV3<'a, A>
where
A: ConnectedAccount + Sync,
{
/// Estimates transaction fees from a [`Provider`].
pub async fn estimate_fee(&self) -> Result<FeeEstimate, AccountError<A::SignError>> {
// Resolves nonce
let nonce = match self.nonce {
Expand All @@ -365,6 +392,8 @@ where
self.estimate_fee_with_nonce(nonce).await
}

/// Simulates the transaction from a [`Provider`]. Transaction validation and fee transfer can
/// be skipped.
pub async fn simulate(
&self,
skip_validate: bool,
Expand All @@ -384,6 +413,7 @@ where
.await
}

/// Signs and broadcasts the transaction to the network.
pub async fn send(&self) -> Result<DeclareTransactionResult, AccountError<A::SignError>> {
self.prepare().await?.send().await
}
Expand Down Expand Up @@ -570,6 +600,10 @@ where
}

impl<'a, A> LegacyDeclaration<'a, A> {
/// Constructs a new [`LegacyDeclaration`].
///
/// Users would typically use [`declare_legacy`](fn.declare_legacy) on an [`Account`] instead of
/// directly calling this method.
pub const fn new(contract_class: Arc<LegacyContractClass>, account: &'a A) -> Self {
Self {
account,
Expand All @@ -580,20 +614,25 @@ impl<'a, A> LegacyDeclaration<'a, A> {
}
}

/// Returns a new [`LegacyDeclaration`] with the `nonce`.
pub fn nonce(self, nonce: Felt) -> Self {
Self {
nonce: Some(nonce),
..self
}
}

/// Returns a new [`LegacyDeclaration`] with the `max_fee`.
pub fn max_fee(self, max_fee: Felt) -> Self {
Self {
max_fee: Some(max_fee),
..self
}
}

/// Returns a new [`LegacyDeclaration`] with the fee estimate multiplier. The multiplier is used
/// when transaction fee is not manually specified and must be fetched from a [`Provider`]
/// instead.
pub fn fee_estimate_multiplier(self, fee_estimate_multiplier: f64) -> Self {
Self {
fee_estimate_multiplier,
Expand Down Expand Up @@ -623,6 +662,7 @@ impl<'a, A> LegacyDeclaration<'a, A>
where
A: ConnectedAccount + Sync,
{
/// Estimates transaction fees from a [`Provider`].
pub async fn estimate_fee(&self) -> Result<FeeEstimate, AccountError<A::SignError>> {
// Resolves nonce
let nonce = match self.nonce {
Expand All @@ -637,6 +677,8 @@ where
self.estimate_fee_with_nonce(nonce).await
}

/// Simulates the transaction from a [`Provider`]. Transaction validation and fee transfer can
/// be skipped.
pub async fn simulate(
&self,
skip_validate: bool,
Expand All @@ -656,6 +698,7 @@ where
.await
}

/// Signs and broadcasts the transaction to the network.
pub async fn send(&self) -> Result<DeclareTransactionResult, AccountError<A::SignError>> {
self.prepare().await?.send().await
}
Expand Down Expand Up @@ -787,6 +830,7 @@ where
}

impl RawDeclarationV2 {
/// Calculates transaction hash given `chain_id`, `address`, and `query_only`.
pub fn transaction_hash(&self, chain_id: Felt, address: Felt, query_only: bool) -> Felt {
compute_hash_on_elements(&[
PREFIX_DECLARE,
Expand All @@ -805,24 +849,29 @@ impl RawDeclarationV2 {
])
}

/// Gets a reference to the flattened Sierra (Cairo 1) class being declared.
pub fn contract_class(&self) -> &FlattenedSierraClass {
&self.contract_class
}

/// Gets the CASM class hash corresponding to the Sierra class being declared.
pub const fn compiled_class_hash(&self) -> Felt {
self.compiled_class_hash
}

/// Gets the `nonce` of the declaration request.
pub const fn nonce(&self) -> Felt {
self.nonce
}

/// Gets the `max_fee` of the declaration request.
pub const fn max_fee(&self) -> Felt {
self.max_fee
}
}

impl RawDeclarationV3 {
/// Calculates transaction hash given `chain_id`, `address`, and `query_only`.
pub fn transaction_hash(&self, chain_id: Felt, address: Felt, query_only: bool) -> Felt {
let mut hasher = PoseidonHasher::new();

Expand Down Expand Up @@ -876,28 +925,34 @@ impl RawDeclarationV3 {
hasher.finalize()
}

/// Gets a reference to the flattened Sierra (Cairo 1) class being declared.
pub fn contract_class(&self) -> &FlattenedSierraClass {
&self.contract_class
}

/// Gets the CASM class hash corresponding to the Sierra class being declared.
pub const fn compiled_class_hash(&self) -> Felt {
self.compiled_class_hash
}

/// Gets the `nonce` of the declaration request.
pub const fn nonce(&self) -> Felt {
self.nonce
}

/// Gets the `gas` of the declaration request.
pub const fn gas(&self) -> u64 {
self.gas
}

/// Gets the `gas_price` of the declaration request.
pub const fn gas_price(&self) -> u128 {
self.gas_price
}
}

impl RawLegacyDeclaration {
/// Calculates transaction hash given `chain_id`, `address`, and `query_only`.
pub fn transaction_hash(
&self,
chain_id: Felt,
Expand All @@ -920,14 +975,17 @@ impl RawLegacyDeclaration {
]))
}

/// Gets a reference to the legacy (Cairo 0) class being declared.
pub fn contract_class(&self) -> &LegacyContractClass {
&self.contract_class
}

/// Gets the `nonce` of the declaration request.
pub const fn nonce(&self) -> Felt {
self.nonce
}

/// Gets the `max_fee` of the declaration request.
pub const fn max_fee(&self) -> Felt {
self.max_fee
}
Expand All @@ -949,6 +1007,7 @@ impl<'a, A> PreparedDeclarationV2<'a, A>
where
A: ConnectedAccount,
{
/// Signs and broadcasts the transaction to the network.
pub async fn send(&self) -> Result<DeclareTransactionResult, AccountError<A::SignError>> {
let tx_request = self.get_declare_request(false, false).await?;
self.account
Expand Down Expand Up @@ -998,6 +1057,7 @@ impl<'a, A> PreparedDeclarationV3<'a, A>
where
A: ConnectedAccount,
{
/// Signs and broadcasts the transaction to the network.
pub async fn send(&self) -> Result<DeclareTransactionResult, AccountError<A::SignError>> {
let tx_request = self.get_declare_request(false, false).await?;
self.account
Expand Down Expand Up @@ -1066,6 +1126,7 @@ impl<'a, A> PreparedLegacyDeclaration<'a, A>
where
A: ConnectedAccount,
{
/// Signs and broadcasts the transaction to the network.
pub async fn send(&self) -> Result<DeclareTransactionResult, AccountError<A::SignError>> {
let tx_request = self.get_declare_request(false, false).await?;
self.account
Expand Down
Loading

0 comments on commit 46ae4b4

Please sign in to comment.