starkzap-rs 0.1.1

A Rust SDK for seamless Starknet wallet integration — starkzap v1 mirror
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111

use thiserror::Error;

/// Unified error type for all starkzap-rs operations.
#[derive(Debug, Error)]
pub enum StarkzapError {
    // ── Provider / RPC ────────────────────────────────────────────────────────
    #[error("RPC provider error: {0}")]
    Provider(#[from] starknet::providers::ProviderError),

    #[error("Account error: {0}")]
    Account(String),

    // ── Signing ───────────────────────────────────────────────────────────────
    #[error("Signer error: {0}")]
    Signer(String),

    #[error("Cartridge session error: {0}")]
    Cartridge(String),

    #[error("Invalid private key: must be a 0x-prefixed hex felt")]
    InvalidPrivateKey,

    #[error("Invalid address: {0}")]
    InvalidAddress(String),

    #[error(
        "Signer address is unavailable and could not be derived from the selected account preset"
    )]
    MissingSignerAddress,

    #[error("Signer public key is unavailable")]
    MissingPublicKey,

    #[error("Configured address {provided} does not match preset-derived address {expected}")]
    AddressMismatch { provided: String, expected: String },

    // ── Transactions ──────────────────────────────────────────────────────────
    #[error("Transaction rejected: {reason}")]
    TransactionRejected { reason: String },

    #[error("Transaction reverted: {reason}")]
    TransactionReverted { reason: String },

    #[error("Transaction wait timed out after {attempts} attempts")]
    WaitTimeout { attempts: u32 },

    // ── Amounts ───────────────────────────────────────────────────────────────
    #[error("Amount parse error: '{input}' is not a valid decimal string")]
    AmountParse { input: String },

    #[error("Amount overflow: value exceeds u128::MAX")]
    AmountOverflow,

    // ── Tokens ────────────────────────────────────────────────────────────────
    #[error("Unknown token: {symbol}")]
    UnknownToken { symbol: String },

    // ── Paymaster ─────────────────────────────────────────────────────────────
    #[error("Paymaster request failed ({status}): {body}")]
    PaymasterRequest { status: u16, body: String },

    #[error("Paymaster response missing field: {field}")]
    PaymasterMalformed { field: String },

    #[error("Paymaster feature is not supported by the configured backend: {feature}")]
    PaymasterUnsupported { feature: String },

    #[error("Paymaster validation failed: {reason}")]
    PaymasterValidation { reason: String },

    // ── Privy (feature = "privy") ─────────────────────────────────────────────
    #[cfg(feature = "privy")]
    #[error("Privy API error ({status}): {body}")]
    PrivyApi { status: u16, body: String },

    #[cfg(feature = "privy")]
    #[error("Privy signing failed: {0}")]
    PrivySigning(String),

    // ── Staking ───────────────────────────────────────────────────────────────
    #[error("Staking error: {0}")]
    Staking(String),

    #[error("No pools found for staker: {address}")]
    NoPoolsFound { address: String },

    // ── Deployment ────────────────────────────────────────────────────────────
    #[error("Account deploy failed: {0}")]
    DeployFailed(String),

    #[error("Account is not deployed and deploy was not requested")]
    NotDeployed,

    // ── HTTP ──────────────────────────────────────────────────────────────────
    #[error("HTTP error: {0}")]
    Http(#[from] reqwest::Error),

    // ── Serialization ─────────────────────────────────────────────────────────
    #[error("Serialization error: {0}")]
    Serialize(#[from] serde_json::Error),

    // ── Misc ──────────────────────────────────────────────────────────────────
    #[error("Hex decode error: {0}")]
    HexDecode(#[from] hex::FromHexError),

    #[error("{0}")]
    Other(String),
}

/// Convenience alias used throughout the crate.
pub type Result<T> = std::result::Result<T, StarkzapError>;