alloy_node_bindings/nodes/
geth.rs

1//! Utilities for launching a Geth dev-mode instance.
2
3use crate::{
4    utils::{extract_endpoint, extract_value, unused_port, GracefulShutdown},
5    NodeError, NODE_DIAL_LOOP_TIMEOUT, NODE_STARTUP_TIMEOUT,
6};
7use alloy_genesis::{CliqueConfig, Genesis};
8use alloy_primitives::Address;
9use k256::ecdsa::SigningKey;
10use std::{
11    ffi::OsString,
12    fs::{create_dir, File},
13    io::{BufRead, BufReader},
14    path::PathBuf,
15    process::{Child, ChildStderr, Command, Stdio},
16    time::Instant,
17};
18use tempfile::tempdir;
19use url::Url;
20
21/// The exposed APIs
22const API: &str = "eth,net,web3,txpool,admin,personal,miner,debug";
23
24/// The geth command
25const GETH: &str = "geth";
26
27/// Whether or not node is in `dev` mode and configuration options that depend on the mode.
28#[derive(Clone, Copy, Debug, PartialEq, Eq)]
29pub enum NodeMode {
30    /// Options that can be set in dev mode
31    Dev(DevOptions),
32    /// Options that cannot be set in dev mode
33    NonDev(PrivateNetOptions),
34}
35
36impl Default for NodeMode {
37    fn default() -> Self {
38        Self::Dev(Default::default())
39    }
40}
41
42/// Configuration options that can be set in dev mode.
43#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
44pub struct DevOptions {
45    /// The interval at which the dev chain will mine new blocks.
46    pub block_time: Option<u64>,
47}
48
49/// Configuration options that cannot be set in dev mode.
50#[derive(Clone, Copy, Debug, PartialEq, Eq)]
51pub struct PrivateNetOptions {
52    /// The p2p port to use.
53    pub p2p_port: Option<u16>,
54
55    /// Whether or not peer discovery is enabled.
56    pub discovery: bool,
57}
58
59impl Default for PrivateNetOptions {
60    fn default() -> Self {
61        Self { p2p_port: None, discovery: true }
62    }
63}
64
65/// A geth instance. Will close the instance when dropped.
66///
67/// Construct this using [`Geth`].
68#[derive(Debug)]
69pub struct GethInstance {
70    pid: Child,
71    host: String,
72    port: u16,
73    p2p_port: Option<u16>,
74    auth_port: Option<u16>,
75    ipc: Option<PathBuf>,
76    data_dir: Option<PathBuf>,
77    genesis: Option<Genesis>,
78    clique_private_key: Option<SigningKey>,
79}
80
81impl GethInstance {
82    /// Returns the host of this instance
83    pub fn host(&self) -> &str {
84        &self.host
85    }
86
87    /// Returns the port of this instance
88    pub const fn port(&self) -> u16 {
89        self.port
90    }
91
92    /// Returns the p2p port of this instance
93    pub const fn p2p_port(&self) -> Option<u16> {
94        self.p2p_port
95    }
96
97    /// Returns the auth port of this instance
98    pub const fn auth_port(&self) -> Option<u16> {
99        self.auth_port
100    }
101
102    /// Returns the HTTP endpoint of this instance
103    #[doc(alias = "http_endpoint")]
104    pub fn endpoint(&self) -> String {
105        format!("http://{}:{}", self.host, self.port)
106    }
107
108    /// Returns the Websocket endpoint of this instance
109    pub fn ws_endpoint(&self) -> String {
110        format!("ws://{}:{}", self.host, self.port)
111    }
112
113    /// Returns the IPC endpoint of this instance
114    pub fn ipc_endpoint(&self) -> String {
115        self.ipc.clone().map_or_else(|| "geth.ipc".to_string(), |ipc| ipc.display().to_string())
116    }
117
118    /// Returns the HTTP endpoint url of this instance
119    #[doc(alias = "http_endpoint_url")]
120    pub fn endpoint_url(&self) -> Url {
121        Url::parse(&self.endpoint()).unwrap()
122    }
123
124    /// Returns the Websocket endpoint url of this instance
125    pub fn ws_endpoint_url(&self) -> Url {
126        Url::parse(&self.ws_endpoint()).unwrap()
127    }
128
129    /// Returns the path to this instances' data directory
130    pub const fn data_dir(&self) -> Option<&PathBuf> {
131        self.data_dir.as_ref()
132    }
133
134    /// Returns the genesis configuration used to configure this instance
135    pub const fn genesis(&self) -> Option<&Genesis> {
136        self.genesis.as_ref()
137    }
138
139    /// Returns the private key used to configure clique on this instance
140    #[deprecated = "clique support was removed in geth >=1.14"]
141    pub const fn clique_private_key(&self) -> Option<&SigningKey> {
142        self.clique_private_key.as_ref()
143    }
144
145    /// Takes the stderr contained in the child process.
146    ///
147    /// This leaves a `None` in its place, so calling methods that require a stderr to be present
148    /// will fail if called after this.
149    pub fn stderr(&mut self) -> Result<ChildStderr, NodeError> {
150        self.pid.stderr.take().ok_or(NodeError::NoStderr)
151    }
152
153    /// Blocks until geth adds the specified peer, using 20s as the timeout.
154    ///
155    /// Requires the stderr to be present in the `GethInstance`.
156    pub fn wait_to_add_peer(&mut self, id: &str) -> Result<(), NodeError> {
157        let mut stderr = self.pid.stderr.as_mut().ok_or(NodeError::NoStderr)?;
158        let mut err_reader = BufReader::new(&mut stderr);
159        let mut line = String::new();
160        let start = Instant::now();
161
162        while start.elapsed() < NODE_DIAL_LOOP_TIMEOUT {
163            line.clear();
164            err_reader.read_line(&mut line).map_err(NodeError::ReadLineError)?;
165
166            // geth ids are truncated
167            let truncated_id = if id.len() > 16 { &id[..16] } else { id };
168            if line.contains("Adding p2p peer") && line.contains(truncated_id) {
169                return Ok(());
170            }
171        }
172        Err(NodeError::Timeout)
173    }
174}
175
176impl Drop for GethInstance {
177    fn drop(&mut self) {
178        GracefulShutdown::shutdown(&mut self.pid, 10, "geth");
179    }
180}
181
182/// Builder for launching `geth`.
183///
184/// # Panics
185///
186/// If `spawn` is called without `geth` being available in the user's $PATH
187///
188/// # Example
189///
190/// ```no_run
191/// use alloy_node_bindings::Geth;
192///
193/// let port = 8545u16;
194/// let url = format!("http://localhost:{}", port).to_string();
195///
196/// let geth = Geth::new().port(port).block_time(5000u64).spawn();
197///
198/// drop(geth); // this will kill the instance
199/// ```
200#[derive(Clone, Debug, Default)]
201#[must_use = "This Builder struct does nothing unless it is `spawn`ed"]
202pub struct Geth {
203    program: Option<PathBuf>,
204    host: Option<String>,
205    port: Option<u16>,
206    authrpc_port: Option<u16>,
207    ipc_path: Option<PathBuf>,
208    ipc_enabled: bool,
209    data_dir: Option<PathBuf>,
210    chain_id: Option<u64>,
211    insecure_unlock: bool,
212    keep_err: bool,
213    genesis: Option<Genesis>,
214    mode: NodeMode,
215    clique_private_key: Option<SigningKey>,
216    args: Vec<OsString>,
217}
218
219impl Geth {
220    /// Creates an empty Geth builder.
221    pub fn new() -> Self {
222        Self::default()
223    }
224
225    /// Creates a Geth builder which will execute `geth` at the given path.
226    ///
227    /// # Example
228    ///
229    /// ```
230    /// use alloy_node_bindings::Geth;
231    /// # fn a() {
232    /// let geth = Geth::at("../go-ethereum/build/bin/geth").spawn();
233    ///
234    /// println!("Geth running at `{}`", geth.endpoint());
235    /// # }
236    /// ```
237    pub fn at(path: impl Into<PathBuf>) -> Self {
238        Self::new().path(path)
239    }
240
241    /// Sets the `path` to the `geth` executable
242    ///
243    /// By default, it's expected that `geth` is in `$PATH`, see also
244    /// [`std::process::Command::new()`]
245    pub fn path<T: Into<PathBuf>>(mut self, path: T) -> Self {
246        self.program = Some(path.into());
247        self
248    }
249
250    /// Puts the `geth` instance in `dev` mode.
251    pub fn dev(mut self) -> Self {
252        self.mode = NodeMode::Dev(Default::default());
253        self
254    }
255
256    /// Returns whether the node is launched in Clique consensus mode.
257    pub const fn is_clique(&self) -> bool {
258        self.clique_private_key.is_some()
259    }
260
261    /// Calculates the address of the Clique consensus address.
262    pub fn clique_address(&self) -> Option<Address> {
263        self.clique_private_key.as_ref().map(|pk| Address::from_public_key(pk.verifying_key()))
264    }
265
266    /// Sets the Clique Private Key to the `geth` executable, which will be later
267    /// loaded on the node.
268    ///
269    /// The address derived from this private key will be used to set the `miner.etherbase` field
270    /// on the node.
271    #[deprecated = "clique support was removed in geth >=1.14"]
272    pub fn set_clique_private_key<T: Into<SigningKey>>(mut self, private_key: T) -> Self {
273        self.clique_private_key = Some(private_key.into());
274        self
275    }
276
277    /// Sets the port which will be used when the `geth-cli` instance is launched.
278    ///
279    /// If port is 0 then the OS will choose a random port.
280    /// [GethInstance::port] will return the port that was chosen.
281    pub fn port<T: Into<u16>>(mut self, port: T) -> Self {
282        self.port = Some(port.into());
283        self
284    }
285
286    /// Sets the host which will be used when the `geth` instance is launched.
287    ///
288    /// Defaults to `localhost`.
289    pub fn host<T: Into<String>>(mut self, host: T) -> Self {
290        self.host = Some(host.into());
291        self
292    }
293
294    /// Sets the port which will be used for incoming p2p connections.
295    ///
296    /// This will put the geth instance into non-dev mode, discarding any previously set dev-mode
297    /// options.
298    pub fn p2p_port(mut self, port: u16) -> Self {
299        match &mut self.mode {
300            NodeMode::Dev(_) => {
301                self.mode = NodeMode::NonDev(PrivateNetOptions {
302                    p2p_port: Some(port),
303                    ..Default::default()
304                })
305            }
306            NodeMode::NonDev(opts) => opts.p2p_port = Some(port),
307        }
308        self
309    }
310
311    /// Sets the block-time which will be used when the `geth-cli` instance is launched.
312    ///
313    /// This will put the geth instance in `dev` mode, discarding any previously set options that
314    /// cannot be used in dev mode.
315    pub const fn block_time(mut self, block_time: u64) -> Self {
316        self.mode = NodeMode::Dev(DevOptions { block_time: Some(block_time) });
317        self
318    }
319
320    /// Sets the chain id for the geth instance.
321    pub const fn chain_id(mut self, chain_id: u64) -> Self {
322        self.chain_id = Some(chain_id);
323        self
324    }
325
326    /// Allow geth to unlock accounts when rpc apis are open.
327    pub const fn insecure_unlock(mut self) -> Self {
328        self.insecure_unlock = true;
329        self
330    }
331
332    /// Enable IPC for the geth instance.
333    pub const fn enable_ipc(mut self) -> Self {
334        self.ipc_enabled = true;
335        self
336    }
337
338    /// Disable discovery for the geth instance.
339    ///
340    /// This will put the geth instance into non-dev mode, discarding any previously set dev-mode
341    /// options.
342    pub fn disable_discovery(mut self) -> Self {
343        self.inner_disable_discovery();
344        self
345    }
346
347    fn inner_disable_discovery(&mut self) {
348        match &mut self.mode {
349            NodeMode::Dev(_) => {
350                self.mode =
351                    NodeMode::NonDev(PrivateNetOptions { discovery: false, ..Default::default() })
352            }
353            NodeMode::NonDev(opts) => opts.discovery = false,
354        }
355    }
356
357    /// Sets the IPC path for the socket.
358    ///
359    /// This also enables IPC, as setting a path implies the intent to use IPC.
360    pub fn ipc_path<T: Into<PathBuf>>(mut self, path: T) -> Self {
361        self.ipc_path = Some(path.into());
362        self.ipc_enabled = true;
363        self
364    }
365
366    /// Sets the data directory for geth.
367    pub fn data_dir<T: Into<PathBuf>>(mut self, path: T) -> Self {
368        self.data_dir = Some(path.into());
369        self
370    }
371
372    /// Sets the `genesis.json` for the geth instance.
373    ///
374    /// If this is set, geth will be initialized with `geth init` and the `--datadir` option will be
375    /// set to the same value as `data_dir`.
376    ///
377    /// This is destructive and will overwrite any existing data in the data directory.
378    pub fn genesis(mut self, genesis: Genesis) -> Self {
379        self.genesis = Some(genesis);
380        self
381    }
382
383    /// Sets the port for authenticated RPC connections.
384    pub const fn authrpc_port(mut self, port: u16) -> Self {
385        self.authrpc_port = Some(port);
386        self
387    }
388
389    /// Keep the handle to geth's stderr in order to read from it.
390    ///
391    /// Caution: if the stderr handle isn't used, this can end up blocking.
392    pub const fn keep_stderr(mut self) -> Self {
393        self.keep_err = true;
394        self
395    }
396
397    /// Adds an argument to pass to the `geth`.
398    pub fn push_arg<T: Into<OsString>>(&mut self, arg: T) {
399        self.args.push(arg.into());
400    }
401
402    /// Adds multiple arguments to pass to the `geth`.
403    pub fn extend_args<I, S>(&mut self, args: I)
404    where
405        I: IntoIterator<Item = S>,
406        S: Into<OsString>,
407    {
408        for arg in args {
409            self.push_arg(arg);
410        }
411    }
412
413    /// Adds an argument to pass to `geth`.
414    ///
415    /// Pass any arg that is not supported by the builder.
416    pub fn arg<T: Into<OsString>>(mut self, arg: T) -> Self {
417        self.args.push(arg.into());
418        self
419    }
420
421    /// Adds multiple arguments to pass to `geth`.
422    ///
423    /// Pass any args that is not supported by the builder.
424    pub fn args<I, S>(mut self, args: I) -> Self
425    where
426        I: IntoIterator<Item = S>,
427        S: Into<OsString>,
428    {
429        for arg in args {
430            self = self.arg(arg);
431        }
432        self
433    }
434
435    /// Consumes the builder and spawns `geth`.
436    ///
437    /// # Panics
438    ///
439    /// If spawning the instance fails at any point.
440    #[track_caller]
441    pub fn spawn(self) -> GethInstance {
442        self.try_spawn().unwrap()
443    }
444
445    /// Consumes the builder and spawns `geth`. If spawning fails, returns an error.
446    pub fn try_spawn(mut self) -> Result<GethInstance, NodeError> {
447        let bin_path = self
448            .program
449            .as_ref()
450            .map_or_else(|| GETH.as_ref(), |bin| bin.as_os_str())
451            .to_os_string();
452        let mut cmd = Command::new(&bin_path);
453        // `geth` uses stderr for its logs
454        cmd.stderr(Stdio::piped());
455
456        // If no port provided, let the os chose it for us
457        let mut port = self.port.unwrap_or(0);
458        let port_s = port.to_string();
459
460        // If IPC is not enabled on the builder, disable it.
461        if !self.ipc_enabled {
462            cmd.arg("--ipcdisable");
463        }
464
465        // Open the HTTP API
466        cmd.arg("--http");
467        cmd.arg("--http.port").arg(&port_s);
468        cmd.arg("--http.api").arg(API);
469
470        if let Some(ref host) = self.host {
471            cmd.arg("--http.addr").arg(host);
472        }
473
474        // Open the WS API
475        cmd.arg("--ws");
476        cmd.arg("--ws.port").arg(port_s);
477        cmd.arg("--ws.api").arg(API);
478
479        if let Some(ref host) = self.host {
480            cmd.arg("--ws.addr").arg(host);
481        }
482
483        // pass insecure unlock flag if set
484        let is_clique = self.is_clique();
485        if self.insecure_unlock || is_clique {
486            cmd.arg("--allow-insecure-unlock");
487        }
488
489        if is_clique {
490            self.inner_disable_discovery();
491        }
492
493        // Set the port for authenticated APIs
494        let authrpc_port = self.authrpc_port.unwrap_or_else(&mut unused_port);
495        cmd.arg("--authrpc.port").arg(authrpc_port.to_string());
496
497        // use geth init to initialize the datadir if the genesis exists
498        if is_clique {
499            let clique_addr = self.clique_address();
500            if let Some(genesis) = &mut self.genesis {
501                // set up a clique config with an instant sealing period and short (8 block) epoch
502                let clique_config = CliqueConfig { period: Some(0), epoch: Some(8) };
503                genesis.config.clique = Some(clique_config);
504
505                let clique_addr = clique_addr.ok_or_else(|| {
506                    NodeError::CliqueAddressError(
507                        "could not calculates the address of the Clique consensus address."
508                            .to_string(),
509                    )
510                })?;
511
512                // set the extraData field
513                let extra_data_bytes =
514                    [&[0u8; 32][..], clique_addr.as_ref(), &[0u8; 65][..]].concat();
515                genesis.extra_data = extra_data_bytes.into();
516            }
517
518            let clique_addr = self.clique_address().ok_or_else(|| {
519                NodeError::CliqueAddressError(
520                    "could not calculates the address of the Clique consensus address.".to_string(),
521                )
522            })?;
523
524            self.genesis = Some(Genesis::clique_genesis(
525                self.chain_id.ok_or(NodeError::ChainIdNotSet)?,
526                clique_addr,
527            ));
528
529            // we must set the etherbase if using clique
530            // need to use format! / Debug here because the Address Display impl doesn't show the
531            // entire address
532            cmd.arg("--miner.etherbase").arg(format!("{clique_addr:?}"));
533        }
534
535        if let Some(genesis) = &self.genesis {
536            // create a temp dir to store the genesis file
537            let temp_genesis_dir = tempdir().map_err(NodeError::CreateDirError)?;
538            let temp_genesis_path = temp_genesis_dir.path().join("genesis.json");
539
540            // create the genesis file
541            let mut file = File::create(&temp_genesis_path).map_err(|_| {
542                NodeError::GenesisError("could not create genesis file".to_string())
543            })?;
544
545            // serialize genesis and write to file
546            serde_json::to_writer_pretty(&mut file, &genesis).map_err(|_| {
547                NodeError::GenesisError("could not write genesis to file".to_string())
548            })?;
549
550            let mut init_cmd = Command::new(bin_path);
551            if let Some(data_dir) = &self.data_dir {
552                init_cmd.arg("--datadir").arg(data_dir);
553            }
554
555            // set the stderr to null so we don't pollute the test output
556            init_cmd.stderr(Stdio::null());
557
558            init_cmd.arg("init").arg(temp_genesis_path);
559            let res = init_cmd
560                .spawn()
561                .map_err(NodeError::SpawnError)?
562                .wait()
563                .map_err(NodeError::WaitError)?;
564            // .expect("failed to wait for geth init to exit");
565            if !res.success() {
566                return Err(NodeError::InitError);
567            }
568
569            // temp_genesis_dir is dropped here, automatically cleaning up
570        }
571
572        if let Some(data_dir) = &self.data_dir {
573            cmd.arg("--datadir").arg(data_dir);
574
575            // create the directory if it doesn't exist
576            if !data_dir.exists() {
577                create_dir(data_dir).map_err(NodeError::CreateDirError)?;
578            }
579        }
580
581        // Dev mode with custom block time
582        let mut p2p_port = match self.mode {
583            NodeMode::Dev(DevOptions { block_time }) => {
584                cmd.arg("--dev");
585                if let Some(block_time) = block_time {
586                    cmd.arg("--dev.period").arg(block_time.to_string());
587                }
588                None
589            }
590            NodeMode::NonDev(PrivateNetOptions { p2p_port, discovery }) => {
591                // if no port provided, let the os chose it for us
592                let port = p2p_port.unwrap_or(0);
593                cmd.arg("--port").arg(port.to_string());
594
595                // disable discovery if the flag is set
596                if !discovery {
597                    cmd.arg("--nodiscover");
598                }
599                Some(port)
600            }
601        };
602
603        if let Some(chain_id) = self.chain_id {
604            cmd.arg("--networkid").arg(chain_id.to_string());
605        }
606
607        // debug verbosity is needed to check when peers are added
608        cmd.arg("--verbosity").arg("4");
609
610        if let Some(ipc) = &self.ipc_path {
611            cmd.arg("--ipcpath").arg(ipc);
612        }
613
614        cmd.args(self.args);
615
616        let mut child = cmd.spawn().map_err(NodeError::SpawnError)?;
617
618        let stderr = child.stderr.take().ok_or(NodeError::NoStderr)?;
619
620        let start = Instant::now();
621        let mut reader = BufReader::new(stderr);
622
623        // we shouldn't need to wait for p2p to start if geth is in dev mode - p2p is disabled in
624        // dev mode
625        let mut p2p_started = matches!(self.mode, NodeMode::Dev(_));
626        let mut ports_started = false;
627
628        loop {
629            if start + NODE_STARTUP_TIMEOUT <= Instant::now() {
630                let _ = child.kill();
631                return Err(NodeError::Timeout);
632            }
633
634            let mut line = String::with_capacity(120);
635            reader.read_line(&mut line).map_err(NodeError::ReadLineError)?;
636
637            if matches!(self.mode, NodeMode::NonDev(_)) && line.contains("Started P2P networking") {
638                p2p_started = true;
639            }
640
641            if !matches!(self.mode, NodeMode::Dev(_)) {
642                // try to find the p2p port, if not in dev mode
643                if line.contains("New local node record") {
644                    if let Some(port) = extract_value("tcp=", &line) {
645                        p2p_port = port.parse::<u16>().ok();
646                    }
647                }
648            }
649
650            // geth 1.9.23 uses "server started" while 1.9.18 uses "endpoint opened"
651            // the unauthenticated api is used for regular non-engine API requests
652            if line.contains("HTTP endpoint opened")
653                || (line.contains("HTTP server started") && !line.contains("auth=true"))
654            {
655                // Extracts the address from the output
656                if let Some(addr) = extract_endpoint("endpoint=", &line) {
657                    // use the actual http port
658                    port = addr.port();
659                }
660
661                ports_started = true;
662            }
663
664            // Encountered an error such as Fatal: Error starting protocol stack: listen tcp
665            // 127.0.0.1:8545: bind: address already in use
666            if line.contains("Fatal:") {
667                let _ = child.kill();
668                return Err(NodeError::Fatal(line));
669            }
670
671            // If all ports have started we are ready to be queried.
672            if ports_started && p2p_started {
673                break;
674            }
675        }
676
677        if self.keep_err {
678            // re-attach the stderr handle if requested
679            child.stderr = Some(reader.into_inner());
680        } else {
681            // We need to consume the stderr otherwise geth is non-responsive and RPC server results
682            // in connection refused.
683            // See: <https://github.com/alloy-rs/alloy/issues/2091#issuecomment-2676134147>
684            std::thread::spawn(move || {
685                let mut buf = String::new();
686                loop {
687                    let _ = reader.read_line(&mut buf);
688                }
689            });
690        }
691
692        Ok(GethInstance {
693            pid: child,
694            host: self.host.unwrap_or_else(|| "localhost".to_string()),
695            port,
696            ipc: self.ipc_path,
697            data_dir: self.data_dir,
698            p2p_port,
699            auth_port: self.authrpc_port,
700            genesis: self.genesis,
701            clique_private_key: self.clique_private_key,
702        })
703    }
704}
705
706#[cfg(test)]
707mod tests {
708    use super::*;
709
710    #[test]
711    fn can_set_host() {
712        let geth = Geth::new().host("0.0.0.0").dev().try_spawn();
713        if let Ok(geth) = geth {
714            assert_eq!(geth.host(), "0.0.0.0");
715            assert!(geth.endpoint().starts_with("http://0.0.0.0:"));
716            assert!(geth.ws_endpoint().starts_with("ws://0.0.0.0:"));
717        }
718    }
719
720    #[test]
721    fn default_host_is_localhost() {
722        let geth = Geth::new().dev().try_spawn();
723        if let Ok(geth) = geth {
724            assert_eq!(geth.host(), "localhost");
725            assert!(geth.endpoint().starts_with("http://localhost:"));
726            assert!(geth.ws_endpoint().starts_with("ws://localhost:"));
727        }
728    }
729}
alloy_node_bindings/nodes/geth.rs

alloy_node_bindings/nodes/
geth.rs
