Skip to content

Commit

Permalink
feat: update README and docs
Browse files Browse the repository at this point in the history
  • Loading branch information
@aldoborrero
aldoborrero committed Apr 28, 2023
1 parent 187edc5 commit 1e15a96
Show file tree
Hide file tree
Showing 2 changed files with 86 additions and 219 deletions.
236 changes: 31 additions & 205 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -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">
Expand All @@ -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
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.

### NixOS
This project is developed entirely in [Nix Flakes](https://nixos.wiki/wiki/Flakes) (but it offers compatiblity with legacy Nix thanks to `flake-compat`).

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.
## Documentation

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.
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.

### Non-NixOS

To get started, run the following:

1. [Install Nix](https://nixos.org/download.html):

```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.

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

- [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`
🔨 Welcome to ethereum.nix

#### Execution Clients
[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`
docs-build - Build docs
docs-serve - Serve docs

#### Validators
[Testing]

- [vouch](https://github.com/attestantio/vouch): `nix run .#vouch`
test - Build and run a test

### MEV Utilities
[Tools]

- [mev-boost](https://github.com/flashbots/mev-boost/): `nix run .#mev-boost`
fmt - Format the source tree

#### Signers
[general commands]

- [web3signer](https://github.com/ConsenSys/web3signer): `nix run .#web3signer`
- [dirk](https://github.com/attestantio/dirk): `nix run .#dirk`
menu - prints this menu

#### Utilities / Tools / Other
direnv: export +DEVSHELL_DIR +IN_NIX_SHELL +NIXPKGS_PATH +PRJ_DATA_DIR +PRJ_ROOT +name ~PATH ~XDG_DATA_DIRS
```

- [ethdo](https://github.com/wealdtech/ethdo): `nix run .#ethdo`
### Requirements

## NixOS Modules
To make the most of this repo you should have the following installed:

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.
- [Nix](https://nixos.org/)
- [Direnv](https://direnv.net/)

### Geth
### Docs

```nix
services.ethereum.geth.mainnet = {
enable = true;
openFirewall = true;
service.supplementaryGroups = [users.groups.keys.name];
};
To build the docs run `docs-build`. The output will be inside of `./result`.

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";
};
};
```
To serve the docs run `docs-serve`. You can edit the docs in `./docs`.

### 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 `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 `test -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 `format` command.

## Contribute

Expand Down
69 changes: 55 additions & 14 deletions docs/getting-started/installation.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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"),
Expand All @@ -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>

0 comments on commit 1e15a96

Please sign in to comment.