alloy_network/transaction/
builder.rs

1use super::signer::NetworkWallet;
2use crate::Network;
3use alloy_primitives::{Address, Bytes, ChainId, TxKind, U256};
4use alloy_rpc_types_eth::{AccessList, TransactionInputKind};
5use alloy_sol_types::SolCall;
6use futures_utils_wasm::impl_future;
7
8pub use alloy_network_primitives::{TransactionBuilder4844, TransactionBuilder7702};
9
10/// Result type for transaction builders
11pub type BuildResult<T, N> = Result<T, UnbuiltTransactionError<N>>;
12
13/// An unbuilt transaction, along with some error.
14#[derive(Debug, thiserror::Error)]
15#[error("Failed to build transaction: {error}")]
16pub struct UnbuiltTransactionError<N: Network> {
17    /// The original request that failed to build.
18    pub request: N::TransactionRequest,
19    /// The error that occurred.
20    #[source]
21    pub error: TransactionBuilderError<N>,
22}
23
24/// Error type for transaction builders.
25#[derive(Debug, thiserror::Error)]
26pub enum TransactionBuilderError<N: Network> {
27    /// Invalid transaction request
28    #[error("{0} transaction can't be built due to missing keys: {1:?}")]
29    InvalidTransactionRequest(N::TxType, Vec<&'static str>),
30
31    /// Signer cannot produce signature type required for transaction.
32    #[error("Signer cannot produce signature type required for transaction")]
33    UnsupportedSignatureType,
34
35    /// Signer error.
36    #[error(transparent)]
37    Signer(#[from] alloy_signer::Error),
38
39    /// A custom error.
40    #[error("{0}")]
41    Custom(#[source] Box<dyn std::error::Error + Send + Sync + 'static>),
42}
43
44impl<N: Network> TransactionBuilderError<N> {
45    /// Instantiate a custom error.
46    pub fn custom<E>(e: E) -> Self
47    where
48        E: std::error::Error + Send + Sync + 'static,
49    {
50        Self::Custom(Box::new(e))
51    }
52
53    /// Convert the error into an unbuilt transaction error.
54    pub const fn into_unbuilt(self, request: N::TransactionRequest) -> UnbuiltTransactionError<N> {
55        UnbuiltTransactionError { request, error: self }
56    }
57}
58
59/// A Transaction builder for a network.
60///
61/// Transaction builders are primarily used to construct typed transactions that can be signed with
62/// [`TransactionBuilder::build`], or unsigned typed transactions with
63/// [`TransactionBuilder::build_unsigned`].
64///
65/// Transaction builders should be able to construct all available transaction types on a given
66/// network.
67#[doc(alias = "TxBuilder")]
68pub trait TransactionBuilder<N: Network>: Default + Sized + Send + Sync + 'static {
69    /// Get the chain ID for the transaction.
70    fn chain_id(&self) -> Option<ChainId>;
71
72    /// Set the chain ID for the transaction.
73    fn set_chain_id(&mut self, chain_id: ChainId);
74
75    /// Builder-pattern method for setting the chain ID.
76    fn with_chain_id(mut self, chain_id: ChainId) -> Self {
77        self.set_chain_id(chain_id);
78        self
79    }
80
81    /// Get the nonce for the transaction.
82    fn nonce(&self) -> Option<u64>;
83
84    /// Set the nonce for the transaction.
85    fn set_nonce(&mut self, nonce: u64);
86
87    /// Builder-pattern method for setting the nonce.
88    fn with_nonce(mut self, nonce: u64) -> Self {
89        self.set_nonce(nonce);
90        self
91    }
92
93    /// Get the input data for the transaction.
94    fn input(&self) -> Option<&Bytes>;
95
96    /// Set the input data for the transaction.
97    fn set_input<T: Into<Bytes>>(&mut self, input: T);
98
99    /// Builder-pattern method for setting the input data.
100    fn with_input<T: Into<Bytes>>(mut self, input: T) -> Self {
101        self.set_input(input);
102        self
103    }
104
105    /// Set the input data for the transaction, respecting the input kind
106    fn set_input_kind<T: Into<Bytes>>(&mut self, input: T, _: TransactionInputKind) {
107        // forward all to input by default
108        self.set_input(input);
109    }
110
111    /// Builder-pattern method for setting the input data, respecting the input kind
112    fn with_input_kind<T: Into<Bytes>>(mut self, input: T, kind: TransactionInputKind) -> Self {
113        self.set_input_kind(input, kind);
114        self
115    }
116
117    /// Get the sender for the transaction.
118    fn from(&self) -> Option<Address>;
119
120    /// Set the sender for the transaction.
121    fn set_from(&mut self, from: Address);
122
123    /// Builder-pattern method for setting the sender.
124    fn with_from(mut self, from: Address) -> Self {
125        self.set_from(from);
126        self
127    }
128
129    /// Get the kind of transaction.
130    fn kind(&self) -> Option<TxKind>;
131
132    /// Clear the kind of transaction.
133    fn clear_kind(&mut self);
134
135    /// Set the kind of transaction.
136    fn set_kind(&mut self, kind: TxKind);
137
138    /// Builder-pattern method for setting the kind of transaction.
139    fn with_kind(mut self, kind: TxKind) -> Self {
140        self.set_kind(kind);
141        self
142    }
143
144    /// Get the recipient for the transaction.
145    fn to(&self) -> Option<Address> {
146        if let Some(TxKind::Call(addr)) = self.kind() {
147            return Some(addr);
148        }
149        None
150    }
151
152    /// Set the recipient for the transaction.
153    fn set_to(&mut self, to: Address) {
154        self.set_kind(to.into());
155    }
156
157    /// Builder-pattern method for setting the recipient.
158    fn with_to(mut self, to: Address) -> Self {
159        self.set_to(to);
160        self
161    }
162
163    /// Set the `to` field to a create call.
164    fn set_create(&mut self) {
165        self.set_kind(TxKind::Create);
166    }
167
168    /// Set the `to` field to a create call.
169    fn into_create(mut self) -> Self {
170        self.set_create();
171        self
172    }
173
174    /// Deploy the code by making a create call with data. This will set the
175    /// `to` field to [`TxKind::Create`].
176    fn set_deploy_code<T: Into<Bytes>>(&mut self, code: T) {
177        self.set_input(code.into());
178        self.set_create()
179    }
180
181    /// Deploy the code by making a create call with data. This will set the
182    /// `to` field to [`TxKind::Create`].
183    fn with_deploy_code<T: Into<Bytes>>(mut self, code: T) -> Self {
184        self.set_deploy_code(code);
185        self
186    }
187
188    /// Set the data field to a contract call. This will clear the `to` field
189    /// if it is set to [`TxKind::Create`].
190    fn set_call<T: SolCall>(&mut self, t: &T) {
191        self.set_input(t.abi_encode());
192        if matches!(self.kind(), Some(TxKind::Create)) {
193            self.clear_kind();
194        }
195    }
196
197    /// Make a contract call with data.
198    fn with_call<T: SolCall>(mut self, t: &T) -> Self {
199        self.set_call(t);
200        self
201    }
202
203    /// Calculates the address that will be created by the transaction, if any.
204    ///
205    /// Returns `None` if the transaction is not a contract creation (the `to` field is set), or if
206    /// the `from` or `nonce` fields are not set.
207    fn calculate_create_address(&self) -> Option<Address> {
208        if !self.kind().is_some_and(|to| to.is_create()) {
209            return None;
210        }
211        let from = self.from()?;
212        let nonce = self.nonce()?;
213        Some(from.create(nonce))
214    }
215
216    /// Get the value for the transaction.
217    fn value(&self) -> Option<U256>;
218
219    /// Set the value for the transaction.
220    fn set_value(&mut self, value: U256);
221
222    /// Builder-pattern method for setting the value.
223    fn with_value(mut self, value: U256) -> Self {
224        self.set_value(value);
225        self
226    }
227
228    /// Get the legacy gas price for the transaction.
229    fn gas_price(&self) -> Option<u128>;
230
231    /// Set the legacy gas price for the transaction.
232    fn set_gas_price(&mut self, gas_price: u128);
233
234    /// Builder-pattern method for setting the legacy gas price.
235    fn with_gas_price(mut self, gas_price: u128) -> Self {
236        self.set_gas_price(gas_price);
237        self
238    }
239
240    /// Get the max fee per gas for the transaction.
241    fn max_fee_per_gas(&self) -> Option<u128>;
242
243    /// Set the max fee per gas  for the transaction.
244    fn set_max_fee_per_gas(&mut self, max_fee_per_gas: u128);
245
246    /// Builder-pattern method for setting max fee per gas .
247    fn with_max_fee_per_gas(mut self, max_fee_per_gas: u128) -> Self {
248        self.set_max_fee_per_gas(max_fee_per_gas);
249        self
250    }
251
252    /// Get the max priority fee per gas for the transaction.
253    fn max_priority_fee_per_gas(&self) -> Option<u128>;
254
255    /// Set the max priority fee per gas for the transaction.
256    fn set_max_priority_fee_per_gas(&mut self, max_priority_fee_per_gas: u128);
257
258    /// Builder-pattern method for setting max priority fee per gas.
259    fn with_max_priority_fee_per_gas(mut self, max_priority_fee_per_gas: u128) -> Self {
260        self.set_max_priority_fee_per_gas(max_priority_fee_per_gas);
261        self
262    }
263    /// Get the gas limit for the transaction.
264    fn gas_limit(&self) -> Option<u64>;
265
266    /// Set the gas limit for the transaction.
267    fn set_gas_limit(&mut self, gas_limit: u64);
268
269    /// Builder-pattern method for setting the gas limit.
270    fn with_gas_limit(mut self, gas_limit: u64) -> Self {
271        self.set_gas_limit(gas_limit);
272        self
273    }
274
275    /// Get the EIP-2930 access list for the transaction.
276    fn access_list(&self) -> Option<&AccessList>;
277
278    /// Sets the EIP-2930 access list.
279    fn set_access_list(&mut self, access_list: AccessList);
280
281    /// Builder-pattern method for setting the access list.
282    fn with_access_list(mut self, access_list: AccessList) -> Self {
283        self.set_access_list(access_list);
284        self
285    }
286
287    /// Check if all necessary keys are present to build the specified type,
288    /// returning a list of missing keys.
289    fn complete_type(&self, ty: N::TxType) -> Result<(), Vec<&'static str>>;
290
291    /// Check if all necessary keys are present to build the currently-preferred
292    /// transaction type, returning a list of missing keys.
293    fn complete_preferred(&self) -> Result<(), Vec<&'static str>> {
294        self.complete_type(self.output_tx_type())
295    }
296
297    /// Assert that the builder prefers a certain transaction type. This does
298    /// not indicate that the builder is ready to build. This function uses a
299    /// `dbg_assert_eq!` to check the builder status, and will have no affect
300    /// in release builds.
301    fn assert_preferred(&self, ty: N::TxType) {
302        debug_assert_eq!(self.output_tx_type(), ty);
303    }
304
305    /// Assert that the builder prefers a certain transaction type. This does
306    /// not indicate that the builder is ready to build. This function uses a
307    /// `dbg_assert_eq!` to check the builder status, and will have no affect
308    /// in release builds.
309    fn assert_preferred_chained(self, ty: N::TxType) -> Self {
310        self.assert_preferred(ty);
311        self
312    }
313
314    /// Apply a function to the builder, returning the modified builder.
315    fn apply<F>(self, f: F) -> Self
316    where
317        F: FnOnce(Self) -> Self,
318    {
319        f(self)
320    }
321
322    /// Apply a fallible function to the builder, returning the modified builder or an error.
323    fn try_apply<F, E>(self, f: F) -> Result<Self, E>
324    where
325        F: FnOnce(Self) -> Result<Self, E>,
326    {
327        f(self)
328    }
329
330    /// True if the builder contains all necessary information to be submitted
331    /// to the `eth_sendTransaction` endpoint.
332    fn can_submit(&self) -> bool;
333
334    /// True if the builder contains all necessary information to be built into
335    /// a valid transaction.
336    fn can_build(&self) -> bool;
337
338    /// Returns the transaction type that this builder will attempt to build.
339    /// This does not imply that the builder is ready to build.
340    #[doc(alias = "output_transaction_type")]
341    fn output_tx_type(&self) -> N::TxType;
342
343    /// Returns the transaction type that this builder will build. `None` if
344    /// the builder is not ready to build.
345    #[doc(alias = "output_transaction_type_checked")]
346    fn output_tx_type_checked(&self) -> Option<N::TxType>;
347
348    /// Trim any conflicting keys and populate any computed fields (like blob
349    /// hashes).
350    ///
351    /// This is useful for transaction requests that have multiple conflicting
352    /// fields. While these may be buildable, they may not be submitted to the
353    /// RPC. This method should be called before RPC submission, but is not
354    /// necessary before building.
355    fn prep_for_submission(&mut self);
356
357    /// Build an unsigned, but typed, transaction.
358    fn build_unsigned(self) -> BuildResult<N::UnsignedTx, N>;
359
360    /// Build a signed transaction.
361    fn build<W: NetworkWallet<N>>(
362        self,
363        wallet: &W,
364    ) -> impl_future!(<Output = Result<N::TxEnvelope, TransactionBuilderError<N>>>);
365}
alloy_network/transaction/builder.rs

alloy_network/transaction/
builder.rs
