semioscan 0.10.0

Production-grade Rust library for blockchain analytics: gas calculation, price extraction, and block window calculations for EVM chains
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
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144

// SPDX-FileCopyrightText: 2025 Semiotic AI, Inc.
//
// SPDX-License-Identifier: Apache-2.0

//! Canonical ERC-20 event definitions for blockchain event decoding
//!
//! This module provides strongly-typed event definitions for the standard ERC-20
//! token events: Transfer and Approval. These events are universal across all
//! ERC-20 tokens and follow the ERC-20 specification.
//!
//! # Event Signatures
//!
//! - **Transfer**: `Transfer(address,address,uint256)`
//! - **Approval**: `Approval(address,address,uint256)`
//!
//! # Example: Decoding Transfer events
//!
//! ```rust,ignore
//! use semioscan::Transfer;
//! use alloy_sol_types::SolEvent;
//! use alloy_rpc_types::Log;
//!
//! // Fetch logs from RPC
//! let logs: Vec<Log> = provider.get_logs(&filter).await?;
//!
//! for log in logs {
//!     match Transfer::decode_log(&log.inner) {
//!         Ok(event) => {
//!             println!("Transfer: {} -> {}, amount: {}",
//!                 event.from, event.to, event.value);
//!         }
//!         Err(e) => eprintln!("Failed to decode: {}", e),
//!     }
//! }
//! ```
//!
//! # Example: Decoding Approval events
//!
//! ```rust,ignore
//! use semioscan::Approval;
//! use alloy_sol_types::SolEvent;
//!
//! match Approval::decode_log(&log.inner) {
//!     Ok(event) => {
//!         println!("Approval: {} approved {} to spend {}",
//!             event.owner, event.spender, event.value);
//!     }
//!     Err(e) => eprintln!("Failed to decode: {}", e),
//! }
//! ```
//!
//! # Example: Using auto-generated event signatures for filters
//!
//! The `sol!` macro automatically generates `SIGNATURE` (string) and `SIGNATURE_HASH` (B256)
//! constants for each event. Use these instead of manually computing hashes:
//!
//! ```rust,ignore
//! use semioscan::Transfer;
//! use alloy_rpc_types::Filter;
//!
//! // Use the pre-computed signature hash (no runtime hashing needed!)
//! let filter = Filter::new()
//!     .event_signature(Transfer::SIGNATURE_HASH)
//!     .address(token_address);
//!
//! // Access the signature string if needed
//! println!("Event signature: {}", Transfer::SIGNATURE);
//! // Prints: "Transfer(address,address,uint256)"
//! ```

use std::fmt::Debug;

use alloy_sol_types::sol;

sol! {
    /// ERC-20 Transfer event
    ///
    /// Emitted when tokens are transferred from one address to another.
    /// This includes:
    /// - Regular transfers between users
    /// - Minting (from = 0x0)
    /// - Burning (to = 0x0)
    ///
    /// # Fields
    ///
    /// - `from`: Address tokens are transferred from (indexed)
    /// - `to`: Address tokens are transferred to (indexed)
    /// - `value`: Amount of tokens transferred (raw, not adjusted for decimals)
    ///
    /// # Example
    ///
    /// ```rust,ignore
    /// use semioscan::Transfer;
    /// use alloy_sol_types::SolEvent;
    ///
    /// let event = Transfer::decode_log(&log.inner)?;
    /// println!("Transfer of {} from {} to {}", event.value, event.from, event.to);
    /// ```
    event Transfer(address indexed from, address indexed to, uint256 value);
}

impl Debug for Transfer {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        write!(
            f,
            "Transfer(from: {}, to: {}, value: {})",
            self.from, self.to, self.value
        )
    }
}

sol! {
    /// ERC-20 Approval event
    ///
    /// Emitted when an owner approves a spender to transfer tokens on their behalf.
    /// This is used for delegated transfers, commonly seen in DEX interactions.
    ///
    /// # Fields
    ///
    /// - `owner`: Address that owns the tokens and grants approval (indexed)
    /// - `spender`: Address that is approved to spend the tokens (indexed)
    /// - `value`: Maximum amount the spender is approved to transfer (raw, not adjusted for decimals)
    ///
    /// # Example
    ///
    /// ```rust,ignore
    /// use semioscan::Approval;
    /// use alloy_sol_types::SolEvent;
    ///
    /// let event = Approval::decode_log(&log.inner)?;
    /// println!("{} approved {} to spend up to {}", event.owner, event.spender, event.value);
    /// ```
    event Approval(address indexed owner, address indexed spender, uint256 value);
}

impl Debug for Approval {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        write!(
            f,
            "Approval(owner: {}, spender: {}, value: {})",
            self.owner, self.spender, self.value
        )
    }
}