alloy_rpc_types_eth/transaction/
receipt.rs

1use crate::Log;
2use alloy_consensus::{ReceiptEnvelope, TxReceipt, TxType};
3use alloy_network_primitives::ReceiptResponse;
4use alloy_primitives::{Address, BlockHash, TxHash, B256};
5use alloy_sol_types::SolEvent;
6
7/// Transaction receipt
8///
9/// This type is generic over an inner [`ReceiptEnvelope`] which contains
10/// consensus data and metadata.
11#[derive(Clone, Debug, PartialEq, Eq)]
12#[cfg_attr(any(test, feature = "arbitrary"), derive(arbitrary::Arbitrary))]
13#[cfg_attr(feature = "serde", derive(serde::Serialize))]
14#[cfg_attr(feature = "serde", serde(rename_all = "camelCase"))]
15#[doc(alias = "TxReceipt")]
16pub struct TransactionReceipt<T = ReceiptEnvelope<Log>> {
17    /// The receipt envelope, which contains the consensus receipt data.
18    #[cfg_attr(feature = "serde", serde(flatten))]
19    pub inner: T,
20    /// Transaction Hash.
21    #[doc(alias = "tx_hash")]
22    pub transaction_hash: TxHash,
23    /// Index within the block.
24    #[cfg_attr(feature = "serde", serde(default, with = "alloy_serde::quantity::opt"))]
25    #[doc(alias = "tx_index")]
26    pub transaction_index: Option<u64>,
27    /// Hash of the block this transaction was included within.
28    #[cfg_attr(feature = "serde", serde(default))]
29    pub block_hash: Option<BlockHash>,
30    /// Number of the block this transaction was included within.
31    #[cfg_attr(feature = "serde", serde(default, with = "alloy_serde::quantity::opt"))]
32    pub block_number: Option<u64>,
33    /// Gas used by this transaction alone.
34    #[cfg_attr(feature = "serde", serde(with = "alloy_serde::quantity"))]
35    pub gas_used: u64,
36    /// The price paid post-execution by the transaction (i.e. base fee + priority fee). Both
37    /// fields in 1559-style transactions are maximums (max fee + max priority fee), the amount
38    /// that's actually paid by users can only be determined post-execution
39    #[cfg_attr(feature = "serde", serde(with = "alloy_serde::quantity"))]
40    pub effective_gas_price: u128,
41    /// Blob gas used by the eip-4844 transaction
42    ///
43    /// This is None for non eip-4844 transactions
44    #[cfg_attr(
45        feature = "serde",
46        serde(
47            skip_serializing_if = "Option::is_none",
48            with = "alloy_serde::quantity::opt",
49            default
50        )
51    )]
52    pub blob_gas_used: Option<u64>,
53    /// The price paid by the eip-4844 transaction per blob gas.
54    #[cfg_attr(
55        feature = "serde",
56        serde(
57            skip_serializing_if = "Option::is_none",
58            with = "alloy_serde::quantity::opt",
59            default
60        )
61    )]
62    pub blob_gas_price: Option<u128>,
63    /// Address of the sender
64    pub from: Address,
65    /// Address of the receiver. None when its a contract creation transaction.
66    pub to: Option<Address>,
67    /// Contract address created, or None if not a deployment.
68    pub contract_address: Option<Address>,
69}
70
71#[cfg(feature = "serde")]
72impl<'de, T> serde::Deserialize<'de> for TransactionReceipt<T>
73where
74    T: serde::Deserialize<'de>,
75{
76    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
77    where
78        D: serde::Deserializer<'de>,
79    {
80        #[derive(serde::Deserialize)]
81        #[serde(rename_all = "camelCase")]
82        struct ReceiptDeserHelper<T = ReceiptEnvelope<Log>> {
83            #[serde(flatten)]
84            inner: T,
85            transaction_hash: TxHash,
86            #[serde(default, with = "alloy_serde::quantity::opt")]
87            transaction_index: Option<u64>,
88            #[serde(default)]
89            block_hash: Option<BlockHash>,
90            #[serde(default, with = "alloy_serde::quantity::opt")]
91            block_number: Option<u64>,
92            #[serde(with = "alloy_serde::quantity")]
93            gas_used: u64,
94            // Optional fields for gas prices
95            // 1. Use effectiveGasPrice if present
96            // 2. Fallback to use gasPrice
97            // 3. Default to 0 if neither is present
98            #[serde(default, alias = "gasPrice", with = "alloy_serde::quantity::opt")]
99            effective_gas_price: Option<u128>,
100            #[serde(
101                default,
102                skip_serializing_if = "Option::is_none",
103                with = "alloy_serde::quantity::opt"
104            )]
105            blob_gas_used: Option<u64>,
106            #[serde(
107                default,
108                skip_serializing_if = "Option::is_none",
109                with = "alloy_serde::quantity::opt"
110            )]
111            blob_gas_price: Option<u128>,
112            from: Address,
113            to: Option<Address>,
114            contract_address: Option<Address>,
115        }
116
117        let helper = ReceiptDeserHelper::deserialize(deserializer)?;
118        Ok(Self {
119            inner: helper.inner,
120            transaction_hash: helper.transaction_hash,
121            transaction_index: helper.transaction_index,
122            block_hash: helper.block_hash,
123            block_number: helper.block_number,
124            gas_used: helper.gas_used,
125            effective_gas_price: helper.effective_gas_price.unwrap_or(0),
126            blob_gas_used: helper.blob_gas_used,
127            blob_gas_price: helper.blob_gas_price,
128            from: helper.from,
129            to: helper.to,
130            contract_address: helper.contract_address,
131        })
132    }
133}
134
135impl AsRef<ReceiptEnvelope<Log>> for TransactionReceipt {
136    fn as_ref(&self) -> &ReceiptEnvelope<Log> {
137        &self.inner
138    }
139}
140
141impl TransactionReceipt {
142    /// Returns the status of the transaction.
143    pub const fn status(&self) -> bool {
144        match &self.inner {
145            ReceiptEnvelope::Eip1559(receipt)
146            | ReceiptEnvelope::Eip2930(receipt)
147            | ReceiptEnvelope::Eip4844(receipt)
148            | ReceiptEnvelope::Eip7702(receipt)
149            | ReceiptEnvelope::Legacy(receipt) => receipt.receipt.status.coerce_status(),
150        }
151    }
152
153    /// Returns the transaction type.
154    #[doc(alias = "tx_type")]
155    pub const fn transaction_type(&self) -> TxType {
156        self.inner.tx_type()
157    }
158
159    /// Calculates the address that will be created by the transaction, if any.
160    ///
161    /// Returns `None` if the transaction is not a contract creation (the `to` field is set), or if
162    /// the `from` field is not set.
163    pub fn calculate_create_address(&self, nonce: u64) -> Option<Address> {
164        if self.to.is_some() {
165            return None;
166        }
167        Some(self.from.create(nonce))
168    }
169
170    /// Attempts to decode the logs to the provided log type.
171    ///
172    /// Returns the first log that decodes successfully.
173    ///
174    /// Returns None, if none of the logs could be decoded to the provided log type or if there
175    /// are no logs.
176    pub fn decoded_log<E: SolEvent>(&self) -> Option<alloy_primitives::Log<E>> {
177        self.logs().iter().find_map(|log| E::decode_log(&log.inner).ok())
178    }
179}
180
181impl<T> TransactionReceipt<T> {
182    /// Maps the inner receipt value of this receipt.
183    pub fn map_inner<U, F>(self, f: F) -> TransactionReceipt<U>
184    where
185        F: FnOnce(T) -> U,
186    {
187        TransactionReceipt {
188            inner: f(self.inner),
189            transaction_hash: self.transaction_hash,
190            transaction_index: self.transaction_index,
191            block_hash: self.block_hash,
192            block_number: self.block_number,
193            gas_used: self.gas_used,
194            effective_gas_price: self.effective_gas_price,
195            blob_gas_used: self.blob_gas_used,
196            blob_gas_price: self.blob_gas_price,
197            from: self.from,
198            to: self.to,
199            contract_address: self.contract_address,
200        }
201    }
202
203    /// Consumes the type and returns the wrapped receipt.
204    pub fn into_inner(self) -> T {
205        self.inner
206    }
207}
208
209impl<L> TransactionReceipt<ReceiptEnvelope<L>> {
210    /// Converts the receipt's log type by applying a function to each log.
211    ///
212    /// Returns the receipt with the new log type.
213    pub fn map_logs<U>(self, f: impl FnMut(L) -> U) -> TransactionReceipt<ReceiptEnvelope<U>> {
214        self.map_inner(|inner| inner.map_logs(f))
215    }
216
217    /// Converts the transaction receipt's [`ReceiptEnvelope`] with a custom log type into a
218    /// [`ReceiptEnvelope`] with the primitives [`alloy_primitives::Log`] type by converting the
219    /// logs.
220    pub fn into_primitives_receipt(
221        self,
222    ) -> TransactionReceipt<ReceiptEnvelope<alloy_primitives::Log>>
223    where
224        L: Into<alloy_primitives::Log>,
225    {
226        self.map_logs(Into::into)
227    }
228
229    /// Get the receipt logs.
230    pub fn logs(&self) -> &[L] {
231        self.inner.logs()
232    }
233}
234
235impl<T: TxReceipt<Log = Log>> ReceiptResponse for TransactionReceipt<T> {
236    fn contract_address(&self) -> Option<Address> {
237        self.contract_address
238    }
239
240    fn status(&self) -> bool {
241        self.inner.status()
242    }
243
244    fn block_hash(&self) -> Option<BlockHash> {
245        self.block_hash
246    }
247
248    fn block_number(&self) -> Option<u64> {
249        self.block_number
250    }
251
252    fn transaction_hash(&self) -> TxHash {
253        self.transaction_hash
254    }
255
256    fn transaction_index(&self) -> Option<u64> {
257        self.transaction_index
258    }
259
260    fn gas_used(&self) -> u64 {
261        self.gas_used
262    }
263
264    fn effective_gas_price(&self) -> u128 {
265        self.effective_gas_price
266    }
267
268    fn blob_gas_used(&self) -> Option<u64> {
269        self.blob_gas_used
270    }
271
272    fn blob_gas_price(&self) -> Option<u128> {
273        self.blob_gas_price
274    }
275
276    fn from(&self) -> Address {
277        self.from
278    }
279
280    fn to(&self) -> Option<Address> {
281        self.to
282    }
283
284    fn cumulative_gas_used(&self) -> u64 {
285        self.inner.cumulative_gas_used()
286    }
287
288    fn state_root(&self) -> Option<B256> {
289        self.inner.status_or_post_state().as_post_state()
290    }
291}
292
293impl From<TransactionReceipt> for TransactionReceipt<ReceiptEnvelope<alloy_primitives::Log>> {
294    fn from(value: TransactionReceipt) -> Self {
295        value.into_primitives_receipt()
296    }
297}
298
299#[cfg(test)]
300mod test {
301    use super::*;
302    use crate::TransactionReceipt;
303    use alloy_consensus::{Eip658Value, Receipt, ReceiptWithBloom};
304    use alloy_primitives::{address, b256, bloom, Bloom};
305    use arbitrary::Arbitrary;
306    use rand::Rng;
307    use similar_asserts::assert_eq;
308
309    #[test]
310    fn transaction_receipt_arbitrary() {
311        let mut bytes = [0u8; 1024];
312        rand::thread_rng().fill(bytes.as_mut_slice());
313
314        let _: TransactionReceipt =
315            TransactionReceipt::arbitrary(&mut arbitrary::Unstructured::new(&bytes)).unwrap();
316    }
317
318    #[test]
319    #[cfg(feature = "serde")]
320    fn test_sanity() {
321        let json_str = r#"{"transactionHash":"0x21f6554c28453a01e7276c1db2fc1695bb512b170818bfa98fa8136433100616","blockHash":"0x4acbdefb861ef4adedb135ca52865f6743451bfbfa35db78076f881a40401a5e","blockNumber":"0x129f4b9","logsBloom":"0x00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000010000000000000000000000000000200000000000000000040000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000400000800000000000000000000000000000000004000000000000000000800000000100000020000000000000000000080000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000010000000000000000000000000000000010000000000000000000000000000","gasUsed":"0xbde1","contractAddress":null,"cumulativeGasUsed":"0xa42aec","transactionIndex":"0x7f","from":"0x9a53bfba35269414f3b2d20b52ca01b15932c7b2","to":"0xdac17f958d2ee523a2206206994597c13d831ec7","type":"0x2","effectiveGasPrice":"0xfb0f6e8c9","logs":[{"blockHash":"0x4acbdefb861ef4adedb135ca52865f6743451bfbfa35db78076f881a40401a5e","address":"0xdac17f958d2ee523a2206206994597c13d831ec7","logIndex":"0x118","data":"0x00000000000000000000000000000000000000000052b7d2dcc80cd2e4000000","removed":false,"topics":["0x8c5be1e5ebec7d5bd14f71427d1e84f3dd0314c0f7b2291e5b200ac8c7c3b925","0x0000000000000000000000009a53bfba35269414f3b2d20b52ca01b15932c7b2","0x00000000000000000000000039e5dbb9d2fead31234d7c647d6ce77d85826f76"],"blockNumber":"0x129f4b9","transactionIndex":"0x7f","transactionHash":"0x21f6554c28453a01e7276c1db2fc1695bb512b170818bfa98fa8136433100616"}],"status":"0x1"}"#;
322
323        let receipt: TransactionReceipt = serde_json::from_str(json_str).unwrap();
324        assert_eq!(
325            receipt.transaction_hash,
326            b256!("21f6554c28453a01e7276c1db2fc1695bb512b170818bfa98fa8136433100616")
327        );
328
329        const EXPECTED_BLOOM: Bloom = bloom!("00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000010000000000000000000000000000200000000000000000040000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000400000800000000000000000000000000000000004000000000000000000800000000100000020000000000000000000080000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000010000000000000000000000000000000010000000000000000000000000000");
330        const EXPECTED_CGU: u64 = 0xa42aec;
331
332        assert!(matches!(
333            receipt.inner,
334            ReceiptEnvelope::Eip1559(ReceiptWithBloom {
335                receipt: Receipt {
336                    status: Eip658Value::Eip658(true),
337                    cumulative_gas_used: EXPECTED_CGU,
338                    ..
339                },
340                logs_bloom: EXPECTED_BLOOM
341            })
342        ));
343
344        let log = receipt.inner.as_receipt().unwrap().logs.first().unwrap();
345        assert_eq!(log.address(), address!("dac17f958d2ee523a2206206994597c13d831ec7"));
346        assert_eq!(log.log_index, Some(0x118));
347        assert_eq!(
348            log.topics(),
349            vec![
350                b256!("8c5be1e5ebec7d5bd14f71427d1e84f3dd0314c0f7b2291e5b200ac8c7c3b925"),
351                b256!("0000000000000000000000009a53bfba35269414f3b2d20b52ca01b15932c7b2"),
352                b256!("00000000000000000000000039e5dbb9d2fead31234d7c647d6ce77d85826f76")
353            ],
354        );
355
356        assert_eq!(
357            serde_json::to_value(&receipt).unwrap(),
358            serde_json::from_str::<serde_json::Value>(json_str).unwrap()
359        );
360    }
361
362    #[test]
363    #[cfg(feature = "serde")]
364    fn deserialize_pre_eip658_receipt() {
365        let receipt_json = r#"
366        {
367            "transactionHash": "0xea1093d492a1dcb1bef708f771a99a96ff05dcab81ca76c31940300177fcf49f",
368            "blockHash": "0x8e38b4dbf6b11fcc3b9dee84fb7986e29ca0a02cecd8977c161ff7333329681e",
369            "blockNumber": "0xf4240",
370            "logsBloom": "0x00000000000000000000000000000000000800000000000000000000000800000000000000000400000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000008000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000001000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000400000000000000000",
371            "gasUsed": "0x723c",
372            "root": "0x284d35bf53b82ef480ab4208527325477439c64fb90ef518450f05ee151c8e10",
373            "contractAddress": null,
374            "cumulativeGasUsed": "0x723c",
375            "transactionIndex": "0x0",
376            "from": "0x39fa8c5f2793459d6622857e7d9fbb4bd91766d3",
377            "to": "0xc083e9947cf02b8ffc7d3090ae9aea72df98fd47",
378            "type": "0x0",
379            "effectiveGasPrice": "0x12bfb19e60",
380            "logs": [
381                {
382                    "blockHash": "0x8e38b4dbf6b11fcc3b9dee84fb7986e29ca0a02cecd8977c161ff7333329681e",
383                    "address": "0xc083e9947cf02b8ffc7d3090ae9aea72df98fd47",
384                    "logIndex": "0x0",
385                    "data": "0x00000000000000000000000039fa8c5f2793459d6622857e7d9fbb4bd91766d30000000000000000000000000000000000000000000000056bc75e2d63100000",
386                    "removed": false,
387                    "topics": [
388                    "0xe1fffcc4923d04b559f4d29a8bfc6cda04eb5b0d3c460751c2402c5c5cc9109c"
389                    ],
390                    "blockNumber": "0xf4240",
391                    "transactionIndex": "0x0",
392                    "transactionHash": "0xea1093d492a1dcb1bef708f771a99a96ff05dcab81ca76c31940300177fcf49f"
393                }
394            ]
395        }
396        "#;
397
398        let receipt = serde_json::from_str::<TransactionReceipt>(receipt_json).unwrap();
399
400        assert_eq!(
401            receipt.transaction_hash,
402            b256!("ea1093d492a1dcb1bef708f771a99a96ff05dcab81ca76c31940300177fcf49f")
403        );
404    }
405
406    // <https://github.com/alloy-rs/alloy/issues/2019>
407    #[test]
408    fn no_effective_gas_price_deser() {
409        // <https://xdcscan.com/tx/0x968c2d0a7b38bfd7f57684298b5b4cda08b591e9f59b60e865a6eb8b531ef837>
410        let json = r#"{"blockHash":"0x0fe66313f8b3f8d88d19ac13b05de0f6e0ef7fcb3293db0869062493ff98f9db","blockNumber":"0x4d34901","contractAddress":null,"cumulativeGasUsed":"0x157e6","from":"0x7ee0d8c9a1374e3d5ce33d48cd09578251af708f","gasUsed":"0x157e6","logs":[{"address":"0x03396fe4e58a0778679e2731564f064fa5256c6e","topics":["0x4736edcab43476194077e25fadaf13bbfb18c7db442202d616b41fd1d549dc9c","0x0000000000000000000000000000000000000000000000000e3762762ff00800","0x0000000000000000000000000000000000000000000000000000000067179cea"],"data":"0x","blockNumber":"0x4d34901","transactionHash":"0x968c2d0a7b38bfd7f57684298b5b4cda08b591e9f59b60e865a6eb8b531ef837","transactionIndex":"0x0","blockHash":"0x0fe66313f8b3f8d88d19ac13b05de0f6e0ef7fcb3293db0869062493ff98f9db","logIndex":"0x0","removed":false}],"logsBloom":"0x00000400000000000000000000000000000400010000000000000000000000000000000000000000000000000000000000000000000000000000000000000000002000000080000000000000000000000000000000000000000000000000000000000008000000000000000000000000000000010000000000000000000000000000000000000000000000400000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000010000004000000000000000000000000000000000000000000040000000000000000000000000000000000000000010000000000000000000000000000000","status":"0x1","to":"0x03396fe4e58a0778679e2731564f064fa5256c6e","transactionHash":"0x968c2d0a7b38bfd7f57684298b5b4cda08b591e9f59b60e865a6eb8b531ef837","transactionIndex":"0x0","type":"0x0"}"#;
411
412        let receipt: TransactionReceipt = serde_json::from_str(json).unwrap();
413
414        assert_eq!(receipt.effective_gas_price, 0);
415
416        let with_gas_price = r#"{"blockHash":"0x0fe66313f8b3f8d88d19ac13b05de0f6e0ef7fcb3293db0869062493ff98f9db","blockNumber":"0x4d34901","contractAddress":null,"cumulativeGasUsed":"0x157e6","from":"0x7ee0d8c9a1374e3d5ce33d48cd09578251af708f","gasUsed":"0x157e6","gasPrice":"0x2e90edd00","logs":[{"address":"0x03396fe4e58a0778679e2731564f064fa5256c6e","topics":["0x4736edcab43476194077e25fadaf13bbfb18c7db442202d616b41fd1d549dc9c","0x0000000000000000000000000000000000000000000000000e3762762ff00800","0x0000000000000000000000000000000000000000000000000000000067179cea"],"data":"0x","blockNumber":"0x4d34901","transactionHash":"0x968c2d0a7b38bfd7f57684298b5b4cda08b591e9f59b60e865a6eb8b531ef837","transactionIndex":"0x0","blockHash":"0x0fe66313f8b3f8d88d19ac13b05de0f6e0ef7fcb3293db0869062493ff98f9db","logIndex":"0x0","removed":false}],"logsBloom":"0x00000400000000000000000000000000000400010000000000000000000000000000000000000000000000000000000000000000000000000000000000000000002000000080000000000000000000000000000000000000000000000000000000000008000000000000000000000000000000010000000000000000000000000000000000000000000000400000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000010000004000000000000000000000000000000000000000000040000000000000000000000000000000000000000010000000000000000000000000000000","status":"0x1","to":"0x03396fe4e58a0778679e2731564f064fa5256c6e","transactionHash":"0x968c2d0a7b38bfd7f57684298b5b4cda08b591e9f59b60e865a6eb8b531ef837","transactionIndex":"0x0","type":"0x0"}"#;
417
418        let receipt_with_gas_price: TransactionReceipt =
419            serde_json::from_str(with_gas_price).unwrap();
420
421        assert_eq!(receipt_with_gas_price.effective_gas_price, 12500000000);
422
423        let proper_receipt = r#"{"blockHash":"0x0fe66313f8b3f8d88d19ac13b05de0f6e0ef7fcb3293db0869062493ff98f9db","blockNumber":"0x4d34901","contractAddress":null,"cumulativeGasUsed":"0x157e6","from":"0x7ee0d8c9a1374e3d5ce33d48cd09578251af708f","gasUsed":"0x157e6","effectiveGasPrice":"0x2e90edd00","logs":[{"address":"0x03396fe4e58a0778679e2731564f064fa5256c6e","topics":["0x4736edcab43476194077e25fadaf13bbfb18c7db442202d616b41fd1d549dc9c","0x0000000000000000000000000000000000000000000000000e3762762ff00800","0x0000000000000000000000000000000000000000000000000000000067179cea"],"data":"0x","blockNumber":"0x4d34901","transactionHash":"0x968c2d0a7b38bfd7f57684298b5b4cda08b591e9f59b60e865a6eb8b531ef837","transactionIndex":"0x0","blockHash":"0x0fe66313f8b3f8d88d19ac13b05de0f6e0ef7fcb3293db0869062493ff98f9db","logIndex":"0x0","removed":false}],"logsBloom":"0x00000400000000000000000000000000000400010000000000000000000000000000000000000000000000000000000000000000000000000000000000000000002000000080000000000000000000000000000000000000000000000000000000000008000000000000000000000000000000010000000000000000000000000000000000000000000000400000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000010000004000000000000000000000000000000000000000000040000000000000000000000000000000000000000010000000000000000000000000000000","status":"0x1","to":"0x03396fe4e58a0778679e2731564f064fa5256c6e","transactionHash":"0x968c2d0a7b38bfd7f57684298b5b4cda08b591e9f59b60e865a6eb8b531ef837","transactionIndex":"0x0","type":"0x0"}"#;
424        let proper_receipt: TransactionReceipt = serde_json::from_str(proper_receipt).unwrap();
425        assert_eq!(proper_receipt.effective_gas_price, 12500000000);
426    }
427}
alloy_rpc_types_eth/transaction/receipt.rs

alloy_rpc_types_eth/transaction/
receipt.rs
