feat: introduction of devshell

README.md

@@ -1,5 +1,5 @@
 <div align="center" style="margin-top: 1em; margin-bottom: 3em;">
-  <h1>ethereum.nix = Ethereum + Nix 🫶</h1>
+  <h1>ethereum.nix = Ethereum 🫶 Nix</h1>
 </div>
 
 <p align="center">
@@ -16,239 +16,65 @@
 
 This is an experimental Nix project for integrating the most interesting / important projects in the Ethereum ecosystem as Nix packages / NixOS modules.
 
-Many of the packages found ~~~~here will be added to `nixpkgs` repository once they're stable / mature enough. But for some others, more experimental ones, they can reside here.
-
-This project is developed entirely in [Nix Flakes](https://nixos.wiki/wiki/Flakes).
-
-## Usage
-
-<details>
-  <summary>As a flake (recommended)</summary>
-
-```nix
-{
-  inputs = {
-    ethereum-nix = {
-      url = "github:nix-community/ethereum.nix";
-      inputs.nixpkgs.follows = "nixpkgs";
-    };
-    nixpkgs.url = "nixpkgs/nixos-unstable";
-  };
-
-  outputs = { self, ethereum-nix, nixpkgs }: {
-    nixosConfigurations.nixos = nixpkgs.lib.nixosSystem {
-      system = "x86_64-linux";
-      modules = [
-        ({ pkgs, ... }: {
-          nixpkgs.overlays = [ ethereum-nix.overlays.default ];
-        })
-      ];
-    };
-  };
-}
-```
-
-</details>
-
-<details>
-  <summary>As an overlay</summary>
-
-```nix
-# configuration.nix
-{ pkgs, ... }: {
-  nixpkgs.overlays = [
-    (import "${fetchTarball "https://github.com/nix-community/ethereum.nix/archive/main.tar.gz"}/overlays.nix")
-  ];
-  environment.systemPackages = with pkgs; [
-    teku
-    lighthouse
-    # <...>
-  ];
-}
-```
-
-</details>
-
-## Setup
-
-### NixOS
-
-If you're on NixOS, chances are you know what you're doing. If you don't have installed `direnv`, clone this repository and when entering inside the folder, just execute `nix develop`. It will load a `devShell` environment ready to be used.
-
-Optional: [install direnv](https://github.com/direnv/direnv#basic-installation), so whenever you enter inside the directory, it will run `nix develop` for you automatically.
-
-### Non-NixOS
+Many of the packages found on `ethereum.nix` will be added to `nixpkgs` repository once they're stable / mature enough. But for some others, more experimental ones, they can reside here.
 
-To get started, run the following:
+This project is developed entirely in [Nix Flakes](https://nixos.wiki/wiki/Flakes) (but it offers compatiblity with legacy Nix thanks to [`flake-compat`](https://github.com/nix-community/flake-compat)).
 
-1. [Install Nix](https://nixos.org/download.html):
+## Documentation
 
-```bash
-$ curl -L https://nixos.org/nix/install | sh
-```
-
-2. Clone this repository and when entering inside the folder, just execute `nix develop`. It will load a `devShell` environment ready to be used.
+We recommend you [to have a look at our documentation](https://nix-community.github.io/ethereum.nix/) that shows how to use `ethereum.nix` effectively.
 
-Optional: [install direnv](https://github.com/direnv/direnv#basic-installation), so whenever you enter inside the directory, it will run `nix develop` for you automatically.
+Any PR improving documentation is welcomed.
 
 ## Development
 
-### Docs
-
-To serve the docs run `, docs-serve`. You can edit the docs in `./docs`.
-
-To build the docs run `, docs-build`. The output will be inside of `./result`.
-
-### Running tests
-
-To run all tests you can use `nix flake check`, it will build all packages and run all tests.
-
-To execute a specific test you can use `, test -h` which will provide more information.
-
-### Formatting
-
-You can manually format using the `format` command like so:
+We are using [`devshell`](https://github.com/numtide/devshell) to have nice development environments. When prompted run `direnv allow` and you will then be met with the following prompt:
 
 ```bash
-, fmt
-```
-
-## Applications
-
-> Note: every command has a local and a remote variant. The local variant requires
-> that the command is run from within the cloned repo. The remote variant can be run
-> from wherever.
->
-> Local: nix run .#my-app-name
->
-> Remote: nix run github:nix-community/ethereum.nix#my-app-name
->
-> For brevity and consistency, all the commands are listed in the local variant
-
-### Executables provided
-
-#### Consensus Clients
+🔨 Welcome to ethereum.nix
 
-- [prysm](https://github.com/prysmaticlabs/prysm):
-  - beacon-chain: `nix run .#prysm-beacon-chain`
-  - client-stats: `nix run .#prysm-client-stats`
-  - prysmctl: `nix run .#prysm-ctl`
-  - validator: `nix run .#prysm-validator`
-- [teku](https://github.com/ConsenSys/teku): `nix run .#teku`
-- [lighthouse](https://github.com/sigp/lighthouse): `nix run .#lighthouse`
+[Docs]
 
-#### Execution Clients
+  docs-build - Build docs
+  docs-serve - Serve docs
 
-- [besu](https://github.com/hyperledger/besu): `nix run .#besu`
-- [erigon](https://github.com/ledgerwatch/erigon): `nix run .#erigon`
-- [geth](https://github.com/ethereum/go-ethereum):
-  - abidump: `nix run .#abidump`
-  - abigen: `nix run .#abigen`
-  - bootnode: `nix run .#bootnode`
-  - clef: `nix run .#clef`
-  - devp2p: `nix run .#devp2p`
-  - ethkey: `nix run .#ethkey`
-  - evm: `nix run .#evm`
-  - faucet: `nix run .#faucet`
-  - geth: `nix run .#geth`
-  - rlpdump: `nix run .#rlpdump`
+[Testing]
 
-#### Validators
+  test       - Build and run a test
 
-- [vouch](https://github.com/attestantio/vouch): `nix run .#vouch`
+[Tools]
 
-### MEV Utilities
+  fmt        - Format the source tree
 
-- [mev-boost](https://github.com/flashbots/mev-boost/): `nix run .#mev-boost`
+[general commands]
 
-#### Signers
+  menu       - prints this menu
 
-- [web3signer](https://github.com/ConsenSys/web3signer): `nix run .#web3signer`
-- [dirk](https://github.com/attestantio/dirk): `nix run .#dirk`
+direnv: export +DEVSHELL_DIR +IN_NIX_SHELL +NIXPKGS_PATH +PRJ_DATA_DIR +PRJ_ROOT +name ~PATH ~XDG_DATA_DIRS
+```
 
-#### Utilities / Tools / Other
+### Requirements
 
-- [ethdo](https://github.com/wealdtech/ethdo): `nix run .#ethdo`
+To make the most of this repo you should have the following installed:
 
-## NixOS Modules
+- [Nix](https://nixos.org/)
+- [Direnv](https://direnv.net/)
 
-We provide modules for configuring and running various services. Some process arguments have been nix'ified. For those
-which aren't there is typically and an `extraArgs` array that can be passed to the process.
+### Docs
 
-### Geth
+To build the docs locally run `docs-build`. The output will be inside of `./result`.
 
-```nix
-services.ethereum.geth.mainnet = {
-    enable = true;
-    openFirewall = true;
-    service.supplementaryGroups = [users.groups.keys.name];
-};
+To serve the docs locally (after building them previously) run `docs-serve`. You can edit the docs in `./docs`.
 
-services.ethereum.geth.goerli = {
-    enable = true;
-    openFirewall = true;
-    args = {
-      network = "goerli";
-      dataDir = "/data/ethereum/goerli/geth";
-      authrpc.jwtsecret = sops.secrets.geth_jwt_secret.path;
-      service.supplementaryGroups = [users.groups.keys.name];
-    }
-};
-```
-
-### Prysm Beacon Chain
-
-```nix
-services.ethereum.prysm.beacon.mainnet = {
-    enable = true;
-    args = {
-      jwt-secret = secrets.prysm_jwt_secret.path;
-      service.supplementaryGroups = [users.groups.keys.name];
-    };
-};
-
-services.ethereum.prysm.beacon.goerli = {
-    enable = true;
-    args = {
-      network = "goerli";
-      dataDir = "/data/ethereum/goerli/prysm-beacon";
-      jwt-secret = secrets.prysm_jwt_secret.path;
-      service.supplementaryGroups = [users.groups.keys.name];
-      checkpoint.sync-url = "https://goerli.checkpoint-sync.ethpandaops.io";
-      genesis.beacon-api-url = "https://goerli.checkpoint-sync.ethpandaops.io";
-    };
-};
-```
-
-### Erigon
-
-```nix
-services.ethereum.erigon.sepolia = {
-  enable = true;
-  openFirewall = true;
-  args = {
-    chain = "sepolia";
-    datadir = "/data/ethereum/sepolia/erigon";
-    http = {
-      enable = true;
-      addr = "0.0.0.0";
-      api = ["eth" "erigon" "engine" "sealer" "net"];
-      vhosts = ["localhost" "dione"];
-    };
-  };
-};
-```
+### Running tests
 
-## Libraries
+To run all tests you can use `check` (alias for `nix flake check`), it will build all packages and run all tests.
 
-Some crypto projects may need specific libraries to be available to compile properly. Below you can find the list of included ones:
+To execute a specific test you can use `tests -h` which will provide more information.
 
-### Libraries provided
+### Formatting
 
-- [evmc](https://github.com/ethereum/evmc/)
-- [bls](https://github.com/herumi/bls)
-- [blst](https://github.com/supranational/blst)
-- [mcl](https://github.com/herumi/mcl)
+You can manually format the source using the `fmt` command.
 
 ## Contribute
 

docs/getting-started/installation.md

@@ -2,49 +2,88 @@
 title: "Installation"
 ---
 
-# Getting Started
+# Installation
 
-This is an experimental project for integrating interesting and important projects in the Ethereum
-ecosystem as Nix packages and NixOS modules.
+Below you'll find several examples of how to use `ethereum.nix`. Choose appropriately depending on if you're using `Nix Flakes` or not.
 
-## Installation
+<details>
+  <summary>With flakes without using overlays (recommended)</summary>
 
-### with flakes
+```nix title="flake.nix"
+{
+  inputs = {
+    nixpkgs.url = "github:nixos/nixpkgs/22.11";
+    ethereum-nix = {
+      url = "github:nix-community/ethereum.nix";
+      inputs.nixpkgs.follows = "nixpkgs";
+    };
+  };
+
+  outputs = inputs @ { self, ethereum-nix, nixpkgs, ... }: let
+    system = "x86_64-linux";
+  in {
+    nixosConfigurations.my-system = nixpkgs.lib.nixosSystem {
+      inherit system;
+      pkgs = nixpkgs.legacyPackages.${system};
+      modules = [
+        # optional: add nixos modules via the default nixosModule
+        ethereum-nix.nixosModules.${system}.default
+
+        ({pkgs, system, ...}: {
+          environment.systemPackages = (with ethereum-nix.packages.${system}; [
+            teku
+            lighthouse
+            # ...
+          ]);
+        })
+      ];
+    };
+  };
+}
+```
+
+</details>
+
+<details>
+  <summary>With flakes using overlays</summary>
 
 ```nix title="flake.nix"
 {
   inputs = {
+    nixpkgs.url = "github:nixos/nixpkgs/22.11";
     ethereum-nix = {
       url = "github:nix-community/ethereum.nix";
       inputs.nixpkgs.follows = "nixpkgs";
     };
   };
 
-  outputs = { self, ethereum-nix, nixpkgs }: let
+  outputs = inputs @ { self, ethereum-nix, nixpkgs, ... }: let
     system = "x86_64-linux";
 
     pkgs = import inputs.nixpkgs {
-        inherit system;
-        overlays = [
-          # add packages via the default overlay
-          ethereum-nix.overlays.default
-        ];
+      inherit system;
+      overlays = [
+        # add packages via the default overlay
+        ethereum-nix.overlays.default
+      ];
     };
 
   in {
     nixosConfigurations.my-system = nixpkgs.lib.nixosSystem {
       inherit system pkgs;
       modules = [
-        # add nixos modules via the default nixosModule
+        # optional: add nixos modules via the default nixosModule
         ethereum-nix.nixosModules.${system}.default
       ];
     };
   };
 }
 ```
 
-### without flakes
+</details>
 
+<details>
+  <summary>Without flakes</summary>
 ```nix title="default.nix"
 {
   ethereum-nix ? import (fetchTarball "https://github.com/nix-community/ethereum.nix/archive/main.tar.gz"),
@@ -61,11 +100,13 @@ ecosystem as Nix packages and NixOS modules.
   my-machine = pkgs.lib.nixosSystem {
     inherit system pkgs;
     modules = [
-      # add nixos modules via the default nixosModule
+      # optional: add nixos modules via the default nixosModule
       ethereum-nix.nixosModules.${system}.default
     ];
   };
 }
 ```
 
 1. You must ensure that your `NIX_PATH` has `nixpkgs` pointing to a version that contains nixos modules e.g. `nixpkgs=https://github.com/NixOS/nixpkgs/archive/nixos-22.11.tar.gz`
+
+</details>