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    pub fn ipc_path<T: Into<PathBuf>>(mut self, path: T) -> Self {
359        self.ipc_path = Some(path.into());
360        self
361    }
362
363    /// Sets the data directory for geth.
364    pub fn data_dir<T: Into<PathBuf>>(mut self, path: T) -> Self {
365        self.data_dir = Some(path.into());
366        self
367    }
368
369    /// Sets the `genesis.json` for the geth instance.
370    ///
371    /// If this is set, geth will be initialized with `geth init` and the `--datadir` option will be
372    /// set to the same value as `data_dir`.
373    ///
374    /// This is destructive and will overwrite any existing data in the data directory.
375    pub fn genesis(mut self, genesis: Genesis) -> Self {
376        self.genesis = Some(genesis);
377        self
378    }
379
380    /// Sets the port for authenticated RPC connections.
381    pub const fn authrpc_port(mut self, port: u16) -> Self {
382        self.authrpc_port = Some(port);
383        self
384    }
385
386    /// Keep the handle to geth's stderr in order to read from it.
387    ///
388    /// Caution: if the stderr handle isn't used, this can end up blocking.
389    pub const fn keep_stderr(mut self) -> Self {
390        self.keep_err = true;
391        self
392    }
393
394    /// Adds an argument to pass to the `geth`.
395    pub fn push_arg<T: Into<OsString>>(&mut self, arg: T) {
396        self.args.push(arg.into());
397    }
398
399    /// Adds multiple arguments to pass to the `geth`.
400    pub fn extend_args<I, S>(&mut self, args: I)
401    where
402        I: IntoIterator<Item = S>,
403        S: Into<OsString>,
404    {
405        for arg in args {
406            self.push_arg(arg);
407        }
408    }
409
410    /// Adds an argument to pass to `geth`.
411    ///
412    /// Pass any arg that is not supported by the builder.
413    pub fn arg<T: Into<OsString>>(mut self, arg: T) -> Self {
414        self.args.push(arg.into());
415        self
416    }
417
418    /// Adds multiple arguments to pass to `geth`.
419    ///
420    /// Pass any args that is not supported by the builder.
421    pub fn args<I, S>(mut self, args: I) -> Self
422    where
423        I: IntoIterator<Item = S>,
424        S: Into<OsString>,
425    {
426        for arg in args {
427            self = self.arg(arg);
428        }
429        self
430    }
431
432    /// Consumes the builder and spawns `geth`.
433    ///
434    /// # Panics
435    ///
436    /// If spawning the instance fails at any point.
437    #[track_caller]
438    pub fn spawn(self) -> GethInstance {
439        self.try_spawn().unwrap()
440    }
441
442    /// Consumes the builder and spawns `geth`. If spawning fails, returns an error.
443    pub fn try_spawn(mut self) -> Result<GethInstance, NodeError> {
444        let bin_path = self
445            .program
446            .as_ref()
447            .map_or_else(|| GETH.as_ref(), |bin| bin.as_os_str())
448            .to_os_string();
449        let mut cmd = Command::new(&bin_path);
450        // `geth` uses stderr for its logs
451        cmd.stderr(Stdio::piped());
452
453        // If no port provided, let the os chose it for us
454        let mut port = self.port.unwrap_or(0);
455        let port_s = port.to_string();
456
457        // If IPC is not enabled on the builder, disable it.
458        if !self.ipc_enabled {
459            cmd.arg("--ipcdisable");
460        }
461
462        // Open the HTTP API
463        cmd.arg("--http");
464        cmd.arg("--http.port").arg(&port_s);
465        cmd.arg("--http.api").arg(API);
466
467        if let Some(ref host) = self.host {
468            cmd.arg("--http.addr").arg(host);
469        }
470
471        // Open the WS API
472        cmd.arg("--ws");
473        cmd.arg("--ws.port").arg(port_s);
474        cmd.arg("--ws.api").arg(API);
475
476        if let Some(ref host) = self.host {
477            cmd.arg("--ws.addr").arg(host);
478        }
479
480        // pass insecure unlock flag if set
481        let is_clique = self.is_clique();
482        if self.insecure_unlock || is_clique {
483            cmd.arg("--allow-insecure-unlock");
484        }
485
486        if is_clique {
487            self.inner_disable_discovery();
488        }
489
490        // Set the port for authenticated APIs
491        let authrpc_port = self.authrpc_port.unwrap_or_else(&mut unused_port);
492        cmd.arg("--authrpc.port").arg(authrpc_port.to_string());
493
494        // use geth init to initialize the datadir if the genesis exists
495        if is_clique {
496            let clique_addr = self.clique_address();
497            if let Some(genesis) = &mut self.genesis {
498                // set up a clique config with an instant sealing period and short (8 block) epoch
499                let clique_config = CliqueConfig { period: Some(0), epoch: Some(8) };
500                genesis.config.clique = Some(clique_config);
501
502                let clique_addr = clique_addr.ok_or_else(|| {
503                    NodeError::CliqueAddressError(
504                        "could not calculates the address of the Clique consensus address."
505                            .to_string(),
506                    )
507                })?;
508
509                // set the extraData field
510                let extra_data_bytes =
511                    [&[0u8; 32][..], clique_addr.as_ref(), &[0u8; 65][..]].concat();
512                genesis.extra_data = extra_data_bytes.into();
513            }
514
515            let clique_addr = self.clique_address().ok_or_else(|| {
516                NodeError::CliqueAddressError(
517                    "could not calculates the address of the Clique consensus address.".to_string(),
518                )
519            })?;
520
521            self.genesis = Some(Genesis::clique_genesis(
522                self.chain_id.ok_or(NodeError::ChainIdNotSet)?,
523                clique_addr,
524            ));
525
526            // we must set the etherbase if using clique
527            // need to use format! / Debug here because the Address Display impl doesn't show the
528            // entire address
529            cmd.arg("--miner.etherbase").arg(format!("{clique_addr:?}"));
530        }
531
532        if let Some(genesis) = &self.genesis {
533            // create a temp dir to store the genesis file
534            let temp_genesis_dir = tempdir().map_err(NodeError::CreateDirError)?;
535            let temp_genesis_path = temp_genesis_dir.path().join("genesis.json");
536
537            // create the genesis file
538            let mut file = File::create(&temp_genesis_path).map_err(|_| {
539                NodeError::GenesisError("could not create genesis file".to_string())
540            })?;
541
542            // serialize genesis and write to file
543            serde_json::to_writer_pretty(&mut file, &genesis).map_err(|_| {
544                NodeError::GenesisError("could not write genesis to file".to_string())
545            })?;
546
547            let mut init_cmd = Command::new(bin_path);
548            if let Some(data_dir) = &self.data_dir {
549                init_cmd.arg("--datadir").arg(data_dir);
550            }
551
552            // set the stderr to null so we don't pollute the test output
553            init_cmd.stderr(Stdio::null());
554
555            init_cmd.arg("init").arg(temp_genesis_path);
556            let res = init_cmd
557                .spawn()
558                .map_err(NodeError::SpawnError)?
559                .wait()
560                .map_err(NodeError::WaitError)?;
561            // .expect("failed to wait for geth init to exit");
562            if !res.success() {
563                return Err(NodeError::InitError);
564            }
565
566            // temp_genesis_dir is dropped here, automatically cleaning up
567        }
568
569        if let Some(data_dir) = &self.data_dir {
570            cmd.arg("--datadir").arg(data_dir);
571
572            // create the directory if it doesn't exist
573            if !data_dir.exists() {
574                create_dir(data_dir).map_err(NodeError::CreateDirError)?;
575            }
576        }
577
578        // Dev mode with custom block time
579        let mut p2p_port = match self.mode {
580            NodeMode::Dev(DevOptions { block_time }) => {
581                cmd.arg("--dev");
582                if let Some(block_time) = block_time {
583                    cmd.arg("--dev.period").arg(block_time.to_string());
584                }
585                None
586            }
587            NodeMode::NonDev(PrivateNetOptions { p2p_port, discovery }) => {
588                // if no port provided, let the os chose it for us
589                let port = p2p_port.unwrap_or(0);
590                cmd.arg("--port").arg(port.to_string());
591
592                // disable discovery if the flag is set
593                if !discovery {
594                    cmd.arg("--nodiscover");
595                }
596                Some(port)
597            }
598        };
599
600        if let Some(chain_id) = self.chain_id {
601            cmd.arg("--networkid").arg(chain_id.to_string());
602        }
603
604        // debug verbosity is needed to check when peers are added
605        cmd.arg("--verbosity").arg("4");
606
607        if let Some(ipc) = &self.ipc_path {
608            cmd.arg("--ipcpath").arg(ipc);
609        }
610
611        cmd.args(self.args);
612
613        let mut child = cmd.spawn().map_err(NodeError::SpawnError)?;
614
615        let stderr = child.stderr.take().ok_or(NodeError::NoStderr)?;
616
617        let start = Instant::now();
618        let mut reader = BufReader::new(stderr);
619
620        // we shouldn't need to wait for p2p to start if geth is in dev mode - p2p is disabled in
621        // dev mode
622        let mut p2p_started = matches!(self.mode, NodeMode::Dev(_));
623        let mut ports_started = false;
624
625        loop {
626            if start + NODE_STARTUP_TIMEOUT <= Instant::now() {
627                let _ = child.kill();
628                return Err(NodeError::Timeout);
629            }
630
631            let mut line = String::with_capacity(120);
632            reader.read_line(&mut line).map_err(NodeError::ReadLineError)?;
633
634            if matches!(self.mode, NodeMode::NonDev(_)) && line.contains("Started P2P networking") {
635                p2p_started = true;
636            }
637
638            if !matches!(self.mode, NodeMode::Dev(_)) {
639                // try to find the p2p port, if not in dev mode
640                if line.contains("New local node record") {
641                    if let Some(port) = extract_value("tcp=", &line) {
642                        p2p_port = port.parse::<u16>().ok();
643                    }
644                }
645            }
646
647            // geth 1.9.23 uses "server started" while 1.9.18 uses "endpoint opened"
648            // the unauthenticated api is used for regular non-engine API requests
649            if line.contains("HTTP endpoint opened")
650                || (line.contains("HTTP server started") && !line.contains("auth=true"))
651            {
652                // Extracts the address from the output
653                if let Some(addr) = extract_endpoint("endpoint=", &line) {
654                    // use the actual http port
655                    port = addr.port();
656                }
657
658                ports_started = true;
659            }
660
661            // Encountered an error such as Fatal: Error starting protocol stack: listen tcp
662            // 127.0.0.1:8545: bind: address already in use
663            if line.contains("Fatal:") {
664                let _ = child.kill();
665                return Err(NodeError::Fatal(line));
666            }
667
668            // If all ports have started we are ready to be queried.
669            if ports_started && p2p_started {
670                break;
671            }
672        }
673
674        if self.keep_err {
675            // re-attach the stderr handle if requested
676            child.stderr = Some(reader.into_inner());
677        } else {
678            // We need to consume the stderr otherwise geth is non-responsive and RPC server results
679            // in connection refused.
680            // See: <https://github.com/alloy-rs/alloy/issues/2091#issuecomment-2676134147>
681            std::thread::spawn(move || {
682                let mut buf = String::new();
683                loop {
684                    let _ = reader.read_line(&mut buf);
685                }
686            });
687        }
688
689        Ok(GethInstance {
690            pid: child,
691            host: self.host.unwrap_or_else(|| "localhost".to_string()),
692            port,
693            ipc: self.ipc_path,
694            data_dir: self.data_dir,
695            p2p_port,
696            auth_port: self.authrpc_port,
697            genesis: self.genesis,
698            clique_private_key: self.clique_private_key,
699        })
700    }
701}
702
703#[cfg(test)]
704mod tests {
705    use super::*;
706
707    #[test]
708    fn can_set_host() {
709        let geth = Geth::new().host("0.0.0.0").dev().try_spawn();
710        if let Ok(geth) = geth {
711            assert_eq!(geth.host(), "0.0.0.0");
712            assert!(geth.endpoint().starts_with("http://0.0.0.0:"));
713            assert!(geth.ws_endpoint().starts_with("ws://0.0.0.0:"));
714        }
715    }
716
717    #[test]
718    fn default_host_is_localhost() {
719        let geth = Geth::new().dev().try_spawn();
720        if let Ok(geth) = geth {
721            assert_eq!(geth.host(), "localhost");
722            assert!(geth.endpoint().starts_with("http://localhost:"));
723            assert!(geth.ws_endpoint().starts_with("ws://localhost:"));
724        }
725    }
726}
alloy_node_bindings/nodes/geth.rs

alloy_node_bindings/nodes/
geth.rs
