status-im
/
nimbus-eth2
mirror of https://github.com/status-im/nimbus-eth2.git
2
0
Fork 0
Code Issues Projects Releases Wiki Activity

Migrate docs to mkdocs (#3900) 

`mkdocs` works with markdown similar to `mdbook` but is generally more
pleasing to the eye and has several nice UX features.

This PR does the bulk of the transition - likely, a followup would be
needed to fully make use of the extra features and navigation.

Book pages have been kept url-compatible, meaning that for the most
part, old links should continue to work!

Co-authored-by: Etan Kissling <etan@status.im>
This commit is contained in:
Jacek Sieka 2022-07-22 21:47:24 +02:00 committed by GitHub
parent ddb7a3ecf0
commit dbd3d02e63
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
40 changed files with 540 additions and 904 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

9
Makefile
View File

@ -658,14 +658,13 @@ libnfuzz.a: | build deps
[[ -e "$@" ]] && mv "$@" build/ || true # workaround for https://github.com/nim-lang/Nim/issues/12745
book:
"$(MAKE)" -C docs book
auditors-book:
[[ "$$(mdbook --version)" = "mdbook v0.4.18" ]] || { echo "'mdbook v0.4.18' not found in PATH. See 'docs/README.md'. Aborting."; exit 1; }
[[ "$$(mdbook-toc --version)" == "mdbook-toc 0.8.0" ]] || { echo "'mdbook-toc 0.8.0' not found in PATH. See 'docs/README.md'. Aborting."; exit 1; }
[[ "$$(mdbook-open-on-gh --version)" == "mdbook-open-on-gh 2.1.0" ]] || { echo "'mdbook-open-on-gh 2.1.0' not found in PATH. See 'docs/README.md'. Aborting."; exit 1; }
[[ "$$(mdbook-admonish --version)" == "mdbook-admonish 1.7.0" ]] || { echo "'mdbook-open-on-gh 1.7.0' not found in PATH. See 'docs/README.md'. Aborting."; exit 1; }
cd docs/the_nimbus_book && \
mdbook build
auditors-book:
cd docs/the_auditors_handbook && \
mdbook build
@ -680,7 +679,7 @@ publish-book: | book auditors-book
rm -rf tmp-book/* && \
mkdir -p tmp-book/auditors-book && \
cp -a docs/the_nimbus_book/CNAME tmp-book/ && \
cp -a docs/the_nimbus_book/book/* tmp-book/ && \
cp -a docs/the_nimbus_book/site/* tmp-book/ && \
cp -a docs/the_auditors_handbook/book/* tmp-book/auditors-book/ && \
cd tmp-book && \
git add . && { \

1
docs/.gitignore vendored Normal file
View File

@ -0,0 +1 @@
mkdocs

17
docs/Makefile Normal file
View File

@ -0,0 +1,17 @@
mkdocs: mkdocs/bin/mkdocs
mkdocs/bin/mkdocs:
test -d mkdocs || python -m venv mkdocs
. mkdocs/bin/activate; pip install -r requirements.txt
compile:
. mkdocs/bin/activate; pip-compile requirements.in
sync:
. mkdocs/bin/activate; pip-sync requirements.txt
serve: mkdocs
. mkdocs/bin/activate; cd the_nimbus_book; mkdocs serve
book: mkdocs
. mkdocs/bin/activate; cd the_nimbus_book; mkdocs build

2
docs/requirements.in Normal file
View File

@ -0,0 +1,2 @@
pip-tools
mkdocs-material

73
docs/requirements.txt Normal file
View File

@ -0,0 +1,73 @@
#
# This file is autogenerated by pip-compile with python 3.10
# To update, run:
#
# pip-compile requirements.in
#
build==0.8.0
# via pip-tools
click==8.1.3
# via
# mkdocs
# pip-tools
ghp-import==2.1.0
# via mkdocs
importlib-metadata==4.12.0
# via mkdocs
jinja2==3.1.2
# via
# mkdocs
# mkdocs-material
markdown==3.3.7
# via
# mkdocs
# mkdocs-material
# pymdown-extensions
markupsafe==2.1.1
# via jinja2
mergedeep==1.3.4
# via mkdocs
mkdocs==1.3.1
# via mkdocs-material
mkdocs-material==8.3.9
# via -r requirements.in
mkdocs-material-extensions==1.0.3
# via mkdocs-material
packaging==21.3
# via
# build
# mkdocs
pep517==0.12.0
# via build
pip-tools==6.8.0
# via -r requirements.in
pygments==2.12.0
# via mkdocs-material
pymdown-extensions==9.5
# via mkdocs-material
pyparsing==3.0.9
# via packaging
python-dateutil==2.8.2
# via ghp-import
pyyaml==6.0
# via
# mkdocs
# pyyaml-env-tag
pyyaml-env-tag==0.1
# via mkdocs
six==1.16.0
# via python-dateutil
tomli==2.0.1
# via
# build
# pep517
watchdog==2.1.9
# via mkdocs
wheel==0.37.1
# via pip-tools
zipp==3.8.1
# via importlib-metadata
# The following packages are considered to be unsafe in a requirements file:
# pip
# setuptools

1
docs/the_nimbus_book/.gitignore vendored
View File

@ -1 +1,2 @@
book
site

20
docs/the_nimbus_book/book.toml
View File

@ -1,20 +0,0 @@
[book]
authors = ["Lee Ting Ting", "Jacek Sieka", "Sacha Saint-Leger"]
language = "en"
multilingual = false
src = "src"
title = "The Nimbus Beacon Chain Book"
[preprocessor.open-on-gh]
command = "mdbook-open-on-gh"
renderer = ["html"]
[preprocessor.admonish]
command = "mdbook-admonish"
assets_version = "2.0.0" # do not edit: managed by `mdbook-admonish install`
[output.html]
additional-css = ["custom.css", "mdbook-admonish.css"]
git-repository-url = "https://github.com/status-im/nimbus-eth2"
git-branch = "unstable"

51
docs/the_nimbus_book/custom.css
View File

@ -1,51 +0,0 @@
.light {
--bg: hsl(0, 0%, 100%);
--fg: #333333;
--sidebar-bg: #fafafa;
--sidebar-fg: #364149;
--sidebar-non-existant: #aaaaaa;
--sidebar-active: #ff9c00;
--sidebar-spacer: #f4f4f4;
--scrollbar: #cccccc;
--icons: #cccccc;
--icons-hover: #333333;
--links: #ff9c00;
--inline-code-color: #6e6b5e;
--theme-popup-bg: #fafafa;
--theme-popup-border: #cccccc;
--theme-hover: #e6e6e6;
--quote-bg: rgb(250,250,250);
--table-border-color: hsl(0, 0%, 95%);
--table-header-bg: hsl(0, 0%, 80%);
--table-alternate-bg: hsl(0, 0%, 97%);
--searchbar-border-color: #aaa;
--searchbar-bg: #fafafa;
--searchbar-fg: #000;
--searchbar-shadow-color: #aaa;
--searchresults-header-fg: #666;
--searchresults-border-color: #888;
--searchresults-li-bg: #e4f2fe;
--search-mark-bg: #a2cff5;
}
blockquote {
padding: 10px 20px;
}
footer {
margin-top: 1rem;
margin-bottom: 1rem;
font-size: 0.8em;
text-align: center;
border-top: 1px solid black;
padding: 10px 0;
}

352
docs/the_nimbus_book/mdbook-admonish.css
View File

@ -1,352 +0,0 @@
@charset "UTF-8";
:root {
--md-admonition-icon--note:
url("data:image/svg+xml;charset=utf-8,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24'><path d='M20.71 7.04c.39-.39.39-1.04 0-1.41l-2.34-2.34c-.37-.39-1.02-.39-1.41 0l-1.84 1.83 3.75 3.75M3 17.25V21h3.75L17.81 9.93l-3.75-3.75L3 17.25z'/></svg>");
--md-admonition-icon--abstract:
url("data:image/svg+xml;charset=utf-8,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24'><path d='M17 9H7V7h10m0 6H7v-2h10m-3 6H7v-2h7M12 3a1 1 0 0 1 1 1 1 1 0 0 1-1 1 1 1 0 0 1-1-1 1 1 0 0 1 1-1m7 0h-4.18C14.4 1.84 13.3 1 12 1c-1.3 0-2.4.84-2.82 2H5a2 2 0 0 0-2 2v14a2 2 0 0 0 2 2h14a2 2 0 0 0 2-2V5a2 2 0 0 0-2-2z'/></svg>");
--md-admonition-icon--info:
url("data:image/svg+xml;charset=utf-8,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24'><path d='M13 9h-2V7h2m0 10h-2v-6h2m-1-9A10 10 0 0 0 2 12a10 10 0 0 0 10 10 10 10 0 0 0 10-10A10 10 0 0 0 12 2z'/></svg>");
--md-admonition-icon--tip:
url("data:image/svg+xml;charset=utf-8,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24'><path d='M17.66 11.2c-.23-.3-.51-.56-.77-.82-.67-.6-1.43-1.03-2.07-1.66C13.33 7.26 13 4.85 13.95 3c-.95.23-1.78.75-2.49 1.32-2.59 2.08-3.61 5.75-2.39 8.9.04.1.08.2.08.33 0 .22-.15.42-.35.5-.23.1-.47.04-.66-.12a.58.58 0 0 1-.14-.17c-1.13-1.43-1.31-3.48-.55-5.12C5.78 10 4.87 12.3 5 14.47c.06.5.12 1 .29 1.5.14.6.41 1.2.71 1.73 1.08 1.73 2.95 2.97 4.96 3.22 2.14.27 4.43-.12 6.07-1.6 1.83-1.66 2.47-4.32 1.53-6.6l-.13-.26c-.21-.46-.77-1.26-.77-1.26m-3.16 6.3c-.28.24-.74.5-1.1.6-1.12.4-2.24-.16-2.9-.82 1.19-.28 1.9-1.16 2.11-2.05.17-.8-.15-1.46-.28-2.23-.12-.74-.1-1.37.17-2.06.19.38.39.76.63 1.06.77 1 1.98 1.44 2.24 2.8.04.14.06.28.06.43.03.82-.33 1.72-.93 2.27z'/></svg>");
--md-admonition-icon--success:
url("data:image/svg+xml;charset=utf-8,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24'><path d='m9 20.42-6.21-6.21 2.83-2.83L9 14.77l9.88-9.89 2.83 2.83L9 20.42z'/></svg>");
--md-admonition-icon--question:
url("data:image/svg+xml;charset=utf-8,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24'><path d='m15.07 11.25-.9.92C13.45 12.89 13 13.5 13 15h-2v-.5c0-1.11.45-2.11 1.17-2.83l1.24-1.26c.37-.36.59-.86.59-1.41a2 2 0 0 0-2-2 2 2 0 0 0-2 2H8a4 4 0 0 1 4-4 4 4 0 0 1 4 4 3.2 3.2 0 0 1-.93 2.25M13 19h-2v-2h2M12 2A10 10 0 0 0 2 12a10 10 0 0 0 10 10 10 10 0 0 0 10-10c0-5.53-4.5-10-10-10z'/></svg>");
--md-admonition-icon--warning:
url("data:image/svg+xml;charset=utf-8,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24'><path d='M13 14h-2V9h2m0 9h-2v-2h2M1 21h22L12 2 1 21z'/></svg>");
--md-admonition-icon--failure:
url("data:image/svg+xml;charset=utf-8,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24'><path d='M20 6.91 17.09 4 12 9.09 6.91 4 4 6.91 9.09 12 4 17.09 6.91 20 12 14.91 17.09 20 20 17.09 14.91 12 20 6.91z'/></svg>");
--md-admonition-icon--danger:
url("data:image/svg+xml;charset=utf-8,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24'><path d='M11 15H6l7-14v8h5l-7 14v-8z'/></svg>");
--md-admonition-icon--bug:
url("data:image/svg+xml;charset=utf-8,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24'><path d='M14 12h-4v-2h4m0 6h-4v-2h4m6-6h-2.81a5.985 5.985 0 0 0-1.82-1.96L17 4.41 15.59 3l-2.17 2.17a6.002 6.002 0 0 0-2.83 0L8.41 3 7 4.41l1.62 1.63C7.88 6.55 7.26 7.22 6.81 8H4v2h2.09c-.05.33-.09.66-.09 1v1H4v2h2v1c0 .34.04.67.09 1H4v2h2.81c1.04 1.79 2.97 3 5.19 3s4.15-1.21 5.19-3H20v-2h-2.09c.05-.33.09-.66.09-1v-1h2v-2h-2v-1c0-.34-.04-.67-.09-1H20V8z'/></svg>");
--md-admonition-icon--example:
url("data:image/svg+xml;charset=utf-8,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24'><path d='M7 13v-2h14v2H7m0 6v-2h14v2H7M7 7V5h14v2H7M3 8V5H2V4h2v4H3m-1 9v-1h3v4H2v-1h2v-.5H3v-1h1V17H2m2.25-7a.75.75 0 0 1 .75.75c0 .2-.08.39-.21.52L3.12 13H5v1H2v-.92L4 11H2v-1h2.25z'/></svg>");
--md-admonition-icon--quote:
url("data:image/svg+xml;charset=utf-8,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24'><path d='M14 17h3l2-4V7h-6v6h3M6 17h3l2-4V7H5v6h3l-2 4z'/></svg>");
--md-details-icon:
url("data:image/svg+xml;charset=utf-8,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24'><path d='M8.59 16.58 13.17 12 8.59 7.41 10 6l6 6-6 6-1.41-1.42Z'/></svg>");
}
:is(.admonition) {
display: flow-root;
margin: 1.5625em 0;
padding: 0 1.2rem;
color: var(--fg);
page-break-inside: avoid;
background-color: var(--bg);
border: 0 solid black;
border-inline-start-width: 0.4rem;
border-radius: 0.2rem;
box-shadow: 0 0.2rem 1rem rgba(0, 0, 0, 0.05), 0 0 0.1rem rgba(0, 0, 0, 0.1);
}
@media print {
:is(.admonition) {
box-shadow: none;
}
}
:is(.admonition) > * {
box-sizing: border-box;
}
:is(.admonition) :is(.admonition) {
margin-top: 1em;
margin-bottom: 1em;
}
:is(.admonition) > .tabbed-set:only-child {
margin-top: 0;
}
html :is(.admonition) > :last-child {
margin-bottom: 1.2rem;
}
a.admonition-anchor-link {
display: none;
position: absolute;
left: -1.2rem;
padding-right: 1rem;
}
a.admonition-anchor-link:link, a.admonition-anchor-link:visited {
color: var(--fg);
}
a.admonition-anchor-link:link:hover, a.admonition-anchor-link:visited:hover {
text-decoration: none;
}
a.admonition-anchor-link::before {
content: "§";
}
:is(.admonition-title, summary) {
position: relative;
margin-block: 0;
margin-inline: -1.6rem -1.2rem;
padding-block: 0.8rem;
padding-inline: 4.4rem 1.2rem;
font-weight: 700;
background-color: rgba(68, 138, 255, 0.1);
display: flex;
}
:is(.admonition-title, summary) p {
margin: 0;
}
html :is(.admonition-title, summary):last-child {
margin-bottom: 0;
}
:is(.admonition-title, summary)::before {
position: absolute;
top: 0.625em;
inset-inline-start: 1.6rem;
width: 2rem;
height: 2rem;
background-color: #448aff;
mask-image: url('data:image/svg+xml;charset=utf-8,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"></svg>');
-webkit-mask-image: url('data:image/svg+xml;charset=utf-8,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"></svg>');
mask-repeat: no-repeat;
-webkit-mask-repeat: no-repeat;
mask-size: contain;
-webkit-mask-size: contain;
content: "";
}
:is(.admonition-title, summary):hover a.admonition-anchor-link {
display: initial;
}
details.admonition > summary.admonition-title::after {
position: absolute;
top: 0.625em;
inset-inline-end: 1.6rem;
height: 2rem;
width: 2rem;
background-color: currentcolor;
mask-image: var(--md-details-icon);
-webkit-mask-image: var(--md-details-icon);
mask-repeat: no-repeat;
-webkit-mask-repeat: no-repeat;
mask-size: contain;
-webkit-mask-size: contain;
content: "";
transform: rotate(0deg);
transition: transform 0.25s;
}
details[open].admonition > summary.admonition-title::after {
transform: rotate(90deg);
}
:is(.admonition):is(.note) {
border-color: #448aff;
}
:is(.note) > :is(.admonition-title, summary) {
background-color: rgba(68, 138, 255, 0.1);
}
:is(.note) > :is(.admonition-title, summary)::before {
background-color: #448aff;
mask-image: var(--md-admonition-icon--note);
-webkit-mask-image: var(--md-admonition-icon--note);
mask-repeat: no-repeat;
-webkit-mask-repeat: no-repeat;
mask-size: contain;
-webkit-mask-repeat: no-repeat;
}
:is(.admonition):is(.abstract, .summary, .tldr) {
border-color: #00b0ff;
}
:is(.abstract, .summary, .tldr) > :is(.admonition-title, summary) {
background-color: rgba(0, 176, 255, 0.1);
}
:is(.abstract, .summary, .tldr) > :is(.admonition-title, summary)::before {
background-color: #00b0ff;
mask-image: var(--md-admonition-icon--abstract);
-webkit-mask-image: var(--md-admonition-icon--abstract);
mask-repeat: no-repeat;
-webkit-mask-repeat: no-repeat;
mask-size: contain;
-webkit-mask-repeat: no-repeat;
}
:is(.admonition):is(.info, .todo) {
border-color: #00b8d4;
}
:is(.info, .todo) > :is(.admonition-title, summary) {
background-color: rgba(0, 184, 212, 0.1);
}
:is(.info, .todo) > :is(.admonition-title, summary)::before {
background-color: #00b8d4;
mask-image: var(--md-admonition-icon--info);
-webkit-mask-image: var(--md-admonition-icon--info);
mask-repeat: no-repeat;
-webkit-mask-repeat: no-repeat;
mask-size: contain;
-webkit-mask-repeat: no-repeat;
}
:is(.admonition):is(.tip, .hint, .important) {
border-color: #00bfa5;
}
:is(.tip, .hint, .important) > :is(.admonition-title, summary) {
background-color: rgba(0, 191, 165, 0.1);
}
:is(.tip, .hint, .important) > :is(.admonition-title, summary)::before {
background-color: #00bfa5;
mask-image: var(--md-admonition-icon--tip);
-webkit-mask-image: var(--md-admonition-icon--tip);
mask-repeat: no-repeat;
-webkit-mask-repeat: no-repeat;
mask-size: contain;
-webkit-mask-repeat: no-repeat;
}
:is(.admonition):is(.success, .check, .done) {
border-color: #00c853;
}
:is(.success, .check, .done) > :is(.admonition-title, summary) {
background-color: rgba(0, 200, 83, 0.1);
}
:is(.success, .check, .done) > :is(.admonition-title, summary)::before {
background-color: #00c853;
mask-image: var(--md-admonition-icon--success);
-webkit-mask-image: var(--md-admonition-icon--success);
mask-repeat: no-repeat;
-webkit-mask-repeat: no-repeat;
mask-size: contain;
-webkit-mask-repeat: no-repeat;
}
:is(.admonition):is(.question, .help, .faq) {
border-color: #64dd17;
}
:is(.question, .help, .faq) > :is(.admonition-title, summary) {
background-color: rgba(100, 221, 23, 0.1);
}
:is(.question, .help, .faq) > :is(.admonition-title, summary)::before {
background-color: #64dd17;
mask-image: var(--md-admonition-icon--question);
-webkit-mask-image: var(--md-admonition-icon--question);
mask-repeat: no-repeat;
-webkit-mask-repeat: no-repeat;
mask-size: contain;
-webkit-mask-repeat: no-repeat;
}
:is(.admonition):is(.warning, .caution, .attention) {
border-color: #ff9100;
}
:is(.warning, .caution, .attention) > :is(.admonition-title, summary) {
background-color: rgba(255, 145, 0, 0.1);
}
:is(.warning, .caution, .attention) > :is(.admonition-title, summary)::before {
background-color: #ff9100;
mask-image: var(--md-admonition-icon--warning);
-webkit-mask-image: var(--md-admonition-icon--warning);
mask-repeat: no-repeat;
-webkit-mask-repeat: no-repeat;
mask-size: contain;
-webkit-mask-repeat: no-repeat;
}
:is(.admonition):is(.failure, .fail, .missing) {
border-color: #ff5252;
}
:is(.failure, .fail, .missing) > :is(.admonition-title, summary) {
background-color: rgba(255, 82, 82, 0.1);
}
:is(.failure, .fail, .missing) > :is(.admonition-title, summary)::before {
background-color: #ff5252;
mask-image: var(--md-admonition-icon--failure);
-webkit-mask-image: var(--md-admonition-icon--failure);
mask-repeat: no-repeat;
-webkit-mask-repeat: no-repeat;
mask-size: contain;
-webkit-mask-repeat: no-repeat;
}
:is(.admonition):is(.danger, .error) {
border-color: #ff1744;
}
:is(.danger, .error) > :is(.admonition-title, summary) {
background-color: rgba(255, 23, 68, 0.1);
}
:is(.danger, .error) > :is(.admonition-title, summary)::before {
background-color: #ff1744;
mask-image: var(--md-admonition-icon--danger);
-webkit-mask-image: var(--md-admonition-icon--danger);
mask-repeat: no-repeat;
-webkit-mask-repeat: no-repeat;
mask-size: contain;
-webkit-mask-repeat: no-repeat;
}
:is(.admonition):is(.bug) {
border-color: #f50057;
}
:is(.bug) > :is(.admonition-title, summary) {
background-color: rgba(245, 0, 87, 0.1);
}
:is(.bug) > :is(.admonition-title, summary)::before {
background-color: #f50057;
mask-image: var(--md-admonition-icon--bug);
-webkit-mask-image: var(--md-admonition-icon--bug);
mask-repeat: no-repeat;
-webkit-mask-repeat: no-repeat;
mask-size: contain;
-webkit-mask-repeat: no-repeat;
}
:is(.admonition):is(.example) {
border-color: #7c4dff;
}
:is(.example) > :is(.admonition-title, summary) {
background-color: rgba(124, 77, 255, 0.1);
}
:is(.example) > :is(.admonition-title, summary)::before {
background-color: #7c4dff;
mask-image: var(--md-admonition-icon--example);
-webkit-mask-image: var(--md-admonition-icon--example);
mask-repeat: no-repeat;
-webkit-mask-repeat: no-repeat;
mask-size: contain;
-webkit-mask-repeat: no-repeat;
}
:is(.admonition):is(.quote, .cite) {
border-color: #9e9e9e;
}
:is(.quote, .cite) > :is(.admonition-title, summary) {
background-color: rgba(158, 158, 158, 0.1);
}
:is(.quote, .cite) > :is(.admonition-title, summary)::before {
background-color: #9e9e9e;
mask-image: var(--md-admonition-icon--quote);
-webkit-mask-image: var(--md-admonition-icon--quote);
mask-repeat: no-repeat;
-webkit-mask-repeat: no-repeat;
mask-size: contain;
-webkit-mask-repeat: no-repeat;
}
.navy :is(.admonition) {
background-color: var(--sidebar-bg);
}
.ayu :is(.admonition), .coal :is(.admonition) {
background-color: var(--theme-hover);
}
.rust :is(.admonition) {
background-color: var(--sidebar-bg);
color: var(--sidebar-fg);
}
.rust .admonition-anchor-link:link, .rust .admonition-anchor-link:visited {
color: var(--sidebar-fg);
}

106
docs/the_nimbus_book/mkdocs.yml Normal file
View File

@ -0,0 +1,106 @@
# yaml-language-server: $schema=https://squidfunk.github.io/mkdocs-material/schema.json
site_name: The Nimbus Guide
theme:
name: material
features:
- navigation.expand
- navigation.top
palette:
scheme: default
primary: orange
accent: amber
# Support urls previously used by mdbook
use_directory_urls: false
repo_url: https://github.com/status-im/nimbus-eth2
edit_uri: edit/unstable/docs/the_nimbus_book/src
site_url: https://nimbus.guide
docs_dir: src
markdown_extensions:
- admonition
- pymdownx.details
- pymdownx.highlight:
anchor_linenums: true
- pymdownx.inlinehilite
- pymdownx.snippets
- pymdownx.superfences
- pymdownx.tabbed:
alternate_style: true
nav:
- Summary:
- 'philosophy.md'
- 'hardware.md'
- 'preparation.md'
- 'merge.md'
- Quickstart:
- 'quick-start.md'
- 'run-a-validator.md'
- Downloads:
- 'binaries.md'
- 'docker.md'
- How-to (beacon node):
- 'install.md'
- 'build.md'
- 'start-syncing.md'
- 'trusted-node-sync.md'
- 'web3-backup.md'
- How-to (validator):
- 'deposit.md'
- 'keys.md'
- 'connect-eth2.md'
- 'graffiti.md'
- 'suggested-fee-recipient.md'
- 'keep-an-eye.md'
- 'voluntary-exit.md'
- 'validator-monitor.md'
- 'more-keys.md'
- 'additional-validator.md'
- 'validator-client.md'
- How-to (misc):
- 'keep-updated.md'
- 'eth1.md'
- 'goerli-eth.md'
- 'beacon-node-systemd.md'
- 'log-rotate.md'
- 'checksums.md'
- 'database-backup.md'
- 'logging.md'
- 'email-notifications.md'
- 'profits.md'
- 'health.md'
- 'networking.md'
- 'prater.md'
- 'kiln.md'
- Guides:
- 'metrics-pretty-pictures.md'
- 'infura-guide.md'
- 'migration.md'
- 'pi-guide.md'
- 'attestation-performance.md'
- Security:
- 'security_issues.md'
- 'audit.md'
- 'distribution_internals.md'
- Reference:
- 'rest-api.md'
- 'keymanager-api.md'
- 'options.md'
- 'data-dir.md'
- 'migration-options.md'
- 'troubleshooting.md'
- 'developers.md'
- 'contribute.md'
- 'resources.md'
- 'faq.md'
- 'api.md'

76
docs/the_nimbus_book/src/SUMMARY.md
View File

@ -1,76 +0,0 @@
# Summary
- [Introduction](./intro.md)
- [Design goals](./philosophy.md)
- [System requirements](./hardware.md)
- [Mainnet checklist](./preparation.md)
- [Merge readiness](./merge.md)
# Quickstart
- [Run the beacon node](./quick-start.md)
- [Run a validator](./run-a-validator.md)
# Downloads
- [Binaries](./binaries.md)
- [Docker](./docker.md)
- [Source code](./build.md)
# How-to (beacon node)
- [Install dependencies](./install.md)
- [Build the beacon node](./build.md)
- [Sync from scratch](./start-syncing.md)
- [Sync from a trusted node (checkpoint sync)](./trusted-node-sync.md)
- [Add a backup web3 provider](./web3-backup.md)
# How-to (validator)
- [Make a deposit](./deposit.md)
- [Import your validator keys](./keys.md)
- [Start validating](./connect-eth2.md)
- [Graffiti the blockchain](./graffiti.md)
- [Set up transaction fee recipient](./suggested-fee-recipient.md)
- [Keep an eye on your validator](./keep-an-eye.md)
- [Perform a voluntary exit](./voluntary-exit.md)
- [Monitor validator actions](./validator-monitor.md)
- [Recover or generate keys](./more-keys.md)
- [Add an additional validator](./additional-validator.md)
- [Run a separate validator client](./validator-client.md)
# How-to (misc)
- [Upgrade / downgrade Nimbus](./keep-updated.md)
- [Run an Execution client](./eth1.md)
- [Obtain Goerli ETH](./goerli-eth.md)
- [Set up a systemd service](./beacon-node-systemd.md)
- [Set up log rotation](./log-rotate.md)
- [Verify the integrity of Nimbus](./checksums.md)
- [Back up your database](./database-backup.md)
- [Set up logging](./logging.md)
- [Set up email notifications](./email-notifications.md)
- [Optimise for profitability](./profits.md)
- [Monitor the health of your node](./health.md)
- [Networking](./networking.md)
- [Prater testnet](./prater.md)
- [Kiln testnet](./kiln.md)
# Guides
- [Grafana and Prometheus](./metrics-pretty-pictures.md)
- [Create your own Infura endpoint](./infura-guide.md)
- [Migrate from another client](./migration.md)
- [Validate with a Raspberry Pi](./pi-guide.md)
- [Analyze attestation performance](./attestation-performance.md)
# Security
- [Security Issues / Responsible Disclosure](./security_issues.md)
- [Security Audit](./audit.md)
- [Reproducible Builds](./distribution_internals.md)
# Reference
- [REST API](./rest-api.md)
- [Keymanager API](./keymanager-api.md)
- [Help / Command line options](./options.md)
- [Data directory](./data-dir.md)
- [Advanced migration options](./migration-options.md)
- [Troubleshooting](./troubleshooting.md)
- [For developers](./developers.md)
- [Contribute](./contribute.md)
- [Resources](./resources.md)
- [FAQ](./faq.md)
- [JSON-RPC API (deprecated)](./api.md)

5
docs/the_nimbus_book/src/additional-validator.md
View File

@ -4,6 +4,5 @@ To add an additional validator, [generate a new key](./more-keys.md) then follow
You'll have to [restart](./connect-eth2.md) the beacon node for the changes to take effect.
```admonish tip
A single Nimbus instance is able to handle multiple validators.
```
!!! tip
A single Nimbus instance is able to handle multiple validators.

5
docs/the_nimbus_book/src/api.md
View File

@ -1,8 +1,7 @@
# JSON-RPC API
```admonish warning
As of v22.6.0, the Nimbus JSON-RPC interface has been **removed** following an extended deprecation period. You are encouraged to migrate your applications to the [REST API](./rest-api.md).
```
!!! warning
As of v22.6.0, the Nimbus JSON-RPC interface has been **removed** following an extended deprecation period. You are encouraged to migrate your applications to the [REST API](./rest-api.md).
The JSON-RPC API pre-dated the REST API and was based on early designs of the beacon chain.

20
docs/the_nimbus_book/src/beacon-node-systemd.md
View File

@ -4,9 +4,8 @@ This page will take you through how to set up a `systemd` service for your beaco
`systemd` is used in order to have a command or program run when your device boots (i.e. add it as a service). Once this is done, you can start/stop enable/disable from the linux prompt.
```admonish note
[`systemd`](https://systemd.io/) is a service manager designed specifically for Linux - it cannot be used on Windows / Mac. You can get more information about systemd [here](https://fedoramagazine.org/what-is-an-init-system/)
```
!!! note
[`systemd`](https://systemd.io/) is a service manager designed specifically for Linux - it cannot be used on Windows / Mac. You can get more information about systemd [here](https://fedoramagazine.org/what-is-an-init-system/)
When installing Nimbus via your package manager, a user and service will already have been created for you and you can skip straight to the configuration section.
@ -35,9 +34,8 @@ curl -s https://raw.githubusercontent.com/status-im/nimbus-eth2/stable/scripts/p
The format of service files is documented in the [systemd manual](https://www.freedesktop.org/software/systemd/man/systemd.service.html).
```admonish tip
Automatic restarts increase the risk that the doppelganger detection fails - set `RestartPreventExitStatus=1031` to prevent this from happening
```
!!! tip
Automatic restarts increase the risk that the doppelganger detection fails - set `RestartPreventExitStatus=1031` to prevent this from happening
### 3. Configure your service
@ -59,9 +57,8 @@ The service file contains several options for controlling Nimbus. Important opti
* `Environment=METRICS_ENABLED`: Metrics are used for monitoring the node - see the [metrics](./metrics-pretty-pictures.md) setup guide
* `ExecStart=`: Custom options - see the [options](./options.md) guide
```admonish note
The example assumes Nimbus was installed in `/usr/bin/nimbus_beacon_node` - if you installed Nimbus elsewhere, make sure to update this path.
```
!!! note
The example assumes Nimbus was installed in `/usr/bin/nimbus_beacon_node` - if you installed Nimbus elsewhere, make sure to update this path.
### 4. Notify systemd of the newly added service
@ -112,9 +109,8 @@ When using a service, the beacon node is running as a different user - key impor
sudo -u nimbus /usr/bin/nimbus_beacon_node deposit import --data-dir=/var/lib/nimbus/shared_mainnet_0 /path/to/keys
```
```admonish note
Make sure to use the same `--data-dir` option as is used in the service file! Some guides use `--data-dir=/var/lib/nimbus` instead.
```
!!! note
Make sure to use the same `--data-dir` option as is used in the service file! Some guides use `--data-dir=/var/lib/nimbus` instead.
## Running multiple beacon nodes

15
docs/the_nimbus_book/src/build.md
View File

@ -2,15 +2,13 @@
Building the beacon node from source ensures that all hardware-specific optimizations are turned on. The build process itself is simple and fully automated, but may take a few minutes.
```admonish note
Nimbus is written in the [Nim](https://nim-lang.org) programming language - the correct version will automatically be downloaded as part of the build process!
```
!!! note
Nimbus is written in the [Nim](https://nim-lang.org) programming language - the correct version will automatically be downloaded as part of the build process!
## Prerequisites
```admonish tip
If you are planning to use the precompiled binaries, you can skip this section and go straight to the [binaries](./binaries.md)!
```
!!! tip
If you are planning to use the precompiled binaries, you can skip this section and go straight to the [binaries](./binaries.md)!
When building from source, you will need additional build dependencies to be installed:
@ -85,6 +83,5 @@ To build the Nimbus beacon node and its dependencies, run:
make -j4 nimbus_beacon_node
```
```admonish tip
Omit `-j4` on systems with 4GB of memory or less.
```
!!! tip
Omit `-j4` on systems with 4GB of memory or less.

18
docs/the_nimbus_book/src/connect-eth2.md
View File

@ -6,17 +6,15 @@ Once your keys have been [imported](./keys.md), it is time to restart the beacon
Press `Ctrl-c` to stop the beacon node if it's running, then use the same command as before to run it again:
**Mainnet**
=== "Mainnet"
```sh
./run-mainnet-beacon-node.sh
```
```sh
./run-mainnet-beacon-node.sh
```
**Prater**
```sh
./run-prater-beacon-node.sh
```
=== "Prater"
```sh
./run-prater-beacon-node.sh
```
## Check the logs

15
docs/the_nimbus_book/src/data-dir.md
View File

@ -4,9 +4,8 @@ Nimbus stores all the information it needs to run in a data directory. In this d
When following the installation guide, the chain data will be stored in `build/data` with separate directories for each chain (mainnet, prater, etc).
```admonish tip
The `--data-dir=/path/to/data` allows picking a specific data directory to store the chain - make sure you use the same `--data-dir` option for all beacon node commands!
```
!!! tip
The `--data-dir=/path/to/data` allows picking a specific data directory to store the chain - make sure you use the same `--data-dir` option for all beacon node commands!
## Contents
@ -33,9 +32,8 @@ The `db` folder contains historical chain data and information about the latest
These two folders contain your validator keys as well as the passwords needed to unlock them when starting the beacon node.
```admonish warning
Be careful not to copy the `secrets` and `validator` folders, leaving them in two locations - instead, always move them to the new location! Using the same validators with two nodes poses a significant slashing risk!
```
!!! warning
Be careful not to copy the `secrets` and `validator` folders, leaving them in two locations - instead, always move them to the new location! Using the same validators with two nodes poses a significant slashing risk!
## Moving the data directory
@ -94,9 +92,8 @@ find <data-dir>/validators -type f -exec icacls {} /inheritance:r /grant:r $USER
find <data-dir>/secrets -type f -exec icacls {} /inheritance:r /grant:r $USERDOMAIN\\$USERNAME:\(F\) \;
```
```admonish note
Make sure you run the above from inside `Git Bash`, these commands will not work from inside the standard Windows Command Prompt. If you don't already have a `Git Bash` shell, you'll need to install [Git for Windows](https://gitforwindows.org/).
```
!!! note
Make sure you run the above from inside `Git Bash`, these commands will not work from inside the standard Windows Command Prompt. If you don't already have a `Git Bash` shell, you'll need to install [Git for Windows](https://gitforwindows.org/).
In sum:

57
docs/the_nimbus_book/src/deposit.md
View File

@ -2,16 +2,14 @@
To make a deposit, you will need to generate keys then submit a deposit transaction to the execution chain.
```admonish tip
The process of setting up a validator is also documented at the Ethereum launchpad site:
!!! tip
The process of setting up a validator is also documented at the Ethereum launchpad site:
* [Mainnet](https://launchpad.ethereum.org/)
* [Prater](https://prater.launchpad.ethereum.org/)
```
* [Mainnet](https://launchpad.ethereum.org/)
* [Prater](https://prater.launchpad.ethereum.org/)
```admonish tip
Use Prater to stress test / future proof your set up against peak mainnet load. See [here](./prater.md) for all you need to know
```
!!! tip
Use Prater to stress test / future proof your set up against peak mainnet load. See [here](./prater.md) for all you need to know
## Download the deposit tool
@ -30,41 +28,36 @@ tar xvf staking_deposit-cli-9ab0b05-linux-amd64.tar.gz --strip-components 2
## Generate keys
```admonish tip
You can increase the security of this process by downloading a [Live linux image](https://ubuntu.com/tutorials/try-ubuntu-before-you-install). To do so, copy `deposit` to a USB stick, boot into the live image, and run the tool from inside the image. Make sure you **don't** enable Wifi and unplug any Ethernet cables when using this process.
```
!!! tip
You can increase the security of this process by downloading a [Live linux image](https://ubuntu.com/tutorials/try-ubuntu-before-you-install). To do so, copy `deposit` to a USB stick, boot into the live image, and run the tool from inside the image. Make sure you **don't** enable Wifi and unplug any Ethernet cables when using this process.
The deposit tool generates a seed phrase, and uses this to create validator and withdrawal keys.
```admonish warn
If you lose you seed phrase and your withdrawal key, your funds will be lost forever!
```
!!! warn
If you lose you seed phrase and your withdrawal key, your funds will be lost forever!
**Mainnet**
=== "Mainnet"
```sh
# Run the deposit tool and follow the instructions on screen
./deposit new-mnemonic --chain mainnet
```
```sh
# Run the deposit tool and follow the instructions on screen
./deposit new-mnemonic --chain mainnet
```
**Prater**
```sh
# Run the deposit tool and follow the instructions on screen
./deposit new-mnemonic --chain prater
```
=== "Prater"
```sh
# Run the deposit tool and follow the instructions on screen
./deposit new-mnemonic --chain prater
```
## Make the deposit
Once created, the keys are used to create a deposit transaction on the Ethereum execution chain. Follow the instructions at https://launchpad.ethereum.org/en/upload-deposit-data to upload the deposit data.
```admonish warning
If you are making a mainnet deposit make sure you verify that the deposit contract you are interacting with is the correct one.
!!! warning
If you are making a mainnet deposit make sure you verify that the deposit contract you are interacting with is the correct one.
You should verify that the address is indeed: [0x00000000219ab540356cBB839Cbe05303d7705Fa](https://etherscan.io/address/0x00000000219ab540356cBB839Cbe05303d7705Fa)
```
You should verify that the address is indeed: [0x00000000219ab540356cBB839Cbe05303d7705Fa](https://etherscan.io/address/0x00000000219ab540356cBB839Cbe05303d7705Fa)
```admonish info
Once you send off your transaction(s), your validator will be put in a queue based on deposit time. Getting through the queue may take a few hours or days (assuming the chain is finalising). No validators are accepted into the validator set while the chain isn't finalising. The `Pending Validators` metric on the [beaconcha.in](https://beaconcha.in/) will give you the size of the queue.
```
!!! info
Once you send off your transaction(s), your validator will be put in a queue based on deposit time. Getting through the queue may take a few hours or days (assuming the chain is finalising). No validators are accepted into the validator set while the chain isn't finalising. The `Pending Validators` metric on the [beaconcha.in](https://beaconcha.in/) will give you the size of the queue.
With the keys created, you're ready to perform the [key import](./keys.md).

32
docs/the_nimbus_book/src/eth1.md
View File

@ -12,13 +12,11 @@ You can pass one or more `--web3-url` parameters to the node. Any additional web
./run-mainnet-beacon-node.sh --web3-url=ws://127.0.0.1:8546 --web3-url=http://other:8545
```
```admonish warn
You need to run your own execution client after [the merge](./merge.md) - relying on third-party services such as Infura, Alchemy and Pocket will not be possible.
```
!!! warn
You need to run your own execution client after [the merge](./merge.md) - relying on third-party services such as Infura, Alchemy and Pocket will not be possible.
```admonish note
Syncing an execution client may take hours or even days, depending on your hardware!
```
!!! note
Syncing an execution client may take hours or even days, depending on your hardware!
## Nimbus
@ -34,24 +32,26 @@ See the [Installing Geth](https://geth.ethereum.org/docs/install-and-build/insta
Once you have geth installed, make sure to enable the JSON-RPC WebSocket interface when running geth:
**Testnet**
```
geth --goerli --ws
```
=== "Mainnet"
```
geth --ws
```
**Mainnet**
```
geth --ws
```
=== "Goerli"
```
geth --goerli --ws
```
>**Note:** The `--ws` flag is needed to enable the websocket RPC API. This allows Nimbus to query the eth1 chain using Web3 API calls.
!!! note
The `--ws` flag is needed to enable the websocket RPC API. This allows Nimbus to query the eth1 chain using Web3 API calls.
### 3. Leave Geth running
Let it sync - Geth uses snap sync by default. It may take anywhere between a few hours and a couple of days.
>**N.B.** It is safe to run Nimbus and start validating even if Geth hasn't fully synced yet
!!! note
It is safe to run Nimbus and start validating even if Geth hasn't fully synced yet
You'll know Geth has finished syncing, when you start seeing logs that look like the following:

5
docs/the_nimbus_book/src/faq.md
View File

@ -55,9 +55,8 @@ To stress test it, add `--subscribe-all-subnets` to the [beacon node options](./
To add an additional validator, follow [the same steps](./keys.md) as you did when you added your first. You'll have to restart the beacon node for the changes to take effect.
```admonish note
Note that a single Nimbus instance is able to handle multiple validators.
```
!!! note
Note that a single Nimbus instance is able to handle multiple validators.
## Networking

17
docs/the_nimbus_book/src/graffiti.md
View File

@ -2,14 +2,13 @@
You can use your node's graffiti flag to make your mark on history and forever engrave some words of your choice into an Ethereum block. You will be able to see it using the block explorer.
**Mainnet**
=== "Mainnet"
```sh
./run-mainnet-beacon-node.sh --graffiti="<YOUR_WORDS>"
```
```sh
./run-mainnet-beacon-node.sh --graffiti="<YOUR_WORDS>"
```
**Prater**
```sh
./run-prater-beacon-node.sh --graffiti="<YOUR_WORDS>"
```
=== "Prater"
```sh
./run-prater-beacon-node.sh --graffiti="<YOUR_WORDS>"
```

52
docs/the_nimbus_book/src/index.md Normal file
View File

@ -0,0 +1,52 @@
# The Nimbus Guide
!!! note
If you're eager to get started, check out our [quickstart guide](./quick-start.md).
Nimbus is client for the Ethereum `consensus layer` (eth2) and `execution layer` (eth1) that is [lightweight](https://our.status.im/ethereum-is-green/), [secure](./audit.md) and easy to use.
This book describes the consensus layer client, `nimbus-eth2`, in particular.
Its efficiency and low resource consumption allows it to perform well on all kinds of systems, ranging from Raspberry Pi's and mobile devices where it contributes to low power consumption and security -- to powerful servers where it leaves resources free to perform other tasks, such as running an [execution node](./eth1.md).
</br>
<blockquote class="twitter-tweet"><p lang="en" dir="ltr">&quot;just because it [Nimbus] is optimized to be minimally resource intensive, doesn&#39;t mean you can&#39;t run it on a server. It means that when you do run it on a server, it is consuming a lot less resources.&quot; <a href="https://t.co/F2sdZouBtD">https://t.co/F2sdZouBtD</a></p>&mdash; Nimbus (@ethnimbus) <a href="https://twitter.com/ethnimbus/status/1376836270245154817?ref_src=twsrc%5Etfw">March 30, 2021</a></blockquote> <script async src="https://platform.twitter.com/widgets.js" charset="utf-8"></script>
</br>
This book explains the ways in which you can use Nimbus to either monitor the beacon chain or become a fully-fledged validator.
!!! tip
[The Merge 🐼](https://ethereum.org/en/upgrades/merge/) is happening soon! Bookmark our [merge readiness](./merge.md) page to stay on top of how you need to prepare.
!!! note
Staking and becoming a validator on Ethereum requires 32 ETH, a stable high-speed internet connection and an always-on server. Before staking, make sure that you understand the requirements and practice setting up a validator on a testnet. [Pooled staking](https://ethereum.org/en/staking/pools/) and [Staking as a service](https://ethereum.org/en/staking/saas/) are alternative ways to stake in the network. You can also run a Nimbus node without staking.
## Helpful resources
- [nimbus-eth2 repository](https://github.com/status-im/nimbus-eth2)
- [eth2 specification](https://github.com/ethereum/consensus-specs/tree/v1.2.0-rc.1#phase-0)
- [Ben Edgington's annotated spec](https://benjaminion.xyz/eth2-annotated-spec/phase0/beacon-chain/)
- [Vitalik's annotated spec](https://github.com/ethereum/annotated-spec/blob/master/phase0/beacon-chain.md)
- [Danny Ryan's annotated spec](https://notes.ethereum.org/@djrtwo/Bkn3zpwxB)
### Get in touch
Need help with anything? Join us on [Status](https://join.status.im/nimbus-general) and [Discord](https://discord.gg/9dWwPnG).
### Donate
If you'd like to contribute to Nimbus development:
* Our donation address is [`0x70E47C843E0F6ab0991A3189c28F2957eb6d3842`](https://etherscan.io/address/0x70E47C843E0F6ab0991A3189c28F2957eb6d3842)
* We're also listed on [GitCoin](https://gitcoin.co/grants/137/nimbus-2)
### Stay updated
Subscribe to our newsletter [here](https://subscribe.nimbus.guide/).
### Disclaimer
This documentation assumes Nimbus is in its ideal state. The project is still under active development. Please submit a [Github issue](https://github.com/status-im/nimbus-eth2/issues) if you come across a problem.

53
docs/the_nimbus_book/src/intro.md
View File

@ -1,52 +1 @@
# The Nimbus book
```admonish
If you're eager to get started, check out our [quickstart guide](./quick-start.md).
```
Nimbus is client for the Ethereum `consensus layer` (eth2) and `execution layer` (eth1) that is [lightweight](https://our.status.im/ethereum-is-green/), [secure](./audit.md) and easy to use.
This book describes the consensus layer client, `nimbus-eth2`, in particular.
Its efficiency and low resource consumption allows it to perform well on all kinds of systems, ranging from Raspberry Pi's and mobile devices where it contributes to low power consumption and security -- to powerful servers where it leaves resources free to perform other tasks, such as running an [execution node](./eth1.md).
</br>
<blockquote class="twitter-tweet"><p lang="en" dir="ltr">&quot;just because it [Nimbus] is optimized to be minimally resource intensive, doesn&#39;t mean you can&#39;t run it on a server. It means that when you do run it on a server, it is consuming a lot less resources.&quot; <a href="https://t.co/F2sdZouBtD">https://t.co/F2sdZouBtD</a></p>&mdash; Nimbus (@ethnimbus) <a href="https://twitter.com/ethnimbus/status/1376836270245154817?ref_src=twsrc%5Etfw">March 30, 2021</a></blockquote> <script async src="https://platform.twitter.com/widgets.js" charset="utf-8"></script>
</br>
This book explains the ways in which you can use Nimbus to either monitor the beacon chain or become a fully-fledged validator.
```admonish tip
[The Merge](https://ethereum.org/en/upgrades/merge/) is happening soon! Bookmark our [merge readiness](./merge.md) page to stay on top of how you need to prepare.
```
> **N.B.** Staking and becoming a validator on Ethereum requires 32 ETH, a stable high-speed internet connection and an always-on server. Before staking, make sure that you understand the requirements and practice setting up a validator on a testnet. [Pooled staking](https://ethereum.org/en/staking/pools/) and [Staking as a service](https://ethereum.org/en/staking/saas/) are alternative ways to stake in the network. You can also run a Nimbus node without staking.
## Helpful resources
- [nimbus-eth2 repository](https://github.com/status-im/nimbus-eth2)
- [eth2 specification](https://github.com/ethereum/consensus-specs/tree/v1.2.0-rc.1#phase-0)
- [Ben Edgington's annotated spec](https://benjaminion.xyz/eth2-annotated-spec/phase0/beacon-chain/)
- [Vitalik's annotated spec](https://github.com/ethereum/annotated-spec/blob/master/phase0/beacon-chain.md)
- [Danny Ryan's annotated spec](https://notes.ethereum.org/@djrtwo/Bkn3zpwxB)
### Get in touch
Need help with anything? Join us on [Status](https://join.status.im/nimbus-general) and [Discord](https://discord.gg/9dWwPnG).
### Donate
If you'd like to contribute to Nimbus development:
* Our donation address is [`0x70E47C843E0F6ab0991A3189c28F2957eb6d3842`](https://etherscan.io/address/0x70E47C843E0F6ab0991A3189c28F2957eb6d3842)
* We're also listed on [GitCoin](https://gitcoin.co/grants/137/nimbus-2)
### Stay updated
Subscribe to our newsletter [here](https://subscribe.nimbus.guide/).
### Disclaimer
This documentation assumes Nimbus is in its ideal state. The project is still under active development. Please submit a [Github issue](https://github.com/status-im/nimbus-eth2/issues) if you come across a problem.
[Moved](./index.md)

20
docs/the_nimbus_book/src/keep-updated.md
View File

@ -2,15 +2,13 @@
Make sure you stay on the lookout for any critical updates to Nimbus. This best way to do so is through the **announcements** channel on our [discord](https://discord.com/invite/XRxWahP). The release page can be found [here](https://github.com/status-im/nimbus-eth2/releases/).
```admonish note
If your beacon node is already running, you'll need to restart it for the changes to take effect.
```
!!! note
If your beacon node is already running, you'll need to restart it for the changes to take effect.
To update to the latest version, either download the binary or compile the beacon node release (see below).
```admonish tip
To check which version of Nimbus you're currently running, run `build/nimbus_beacon_node --version`
```
!!! tip
To check which version of Nimbus you're currently running, run `build/nimbus_beacon_node --version`
## Binaries
@ -43,9 +41,8 @@ make -j4 nimbus_beacon_node
Now, restart your node.
```admonish tip
In order to minimise downtime, we recommend updating and [rebuilding](./build.md) the beacon node **before restarting**.
```
!!! tip
In order to minimise downtime, we recommend updating and [rebuilding](./build.md) the beacon node **before restarting**.
## Urgency guidelines
@ -75,9 +72,8 @@ make nimbus_beacon_node
Now, restart your node.
```admonish note
Alternatively, you can grab the appropriate binary release - create a backup of your `build` folder, then download the appropriate binary from here: [https://github.com/status-im/nimbus-eth2/releases/tag/v1.3.0](https://github.com/status-im/nimbus-eth2/releases/tag/v1.3.0)
```
!!! note
Alternatively, you can grab the appropriate binary release - create a backup of your `build` folder, then download the appropriate binary from here: [https://github.com/status-im/nimbus-eth2/releases/tag/v1.3.0](https://github.com/status-im/nimbus-eth2/releases/tag/v1.3.0)
### Go back to stable

5
docs/the_nimbus_book/src/keymanager-api.md
View File

@ -1,8 +1,7 @@
# Keymanager API
```admonish warning
This feature is currently in BETA - we are still testing it and implementation details may change in response to community feedback. **We strongly advise against using it on mainnet** - your validators may get slashed
```
!!! warning
This feature is currently in BETA - we are still testing it and implementation details may change in response to community feedback. **We strongly advise against using it on mainnet** - your validators may get slashed
The standardized [Keymanager API](https://ethereum.github.io/keymanager-APIs/) can be used to add, remove, or [migrate](./migration.md) validators on the fly while the beacon node is running.

61
docs/the_nimbus_book/src/keys.md
View File

@ -1,42 +1,41 @@
# Import your validator keys into Nimbus
```admonish tip
`systemd` service file users will want to follow the [service file guide](./beacon-node-systemd.md#import-validator-keys) instead!
```
!!! tip
`systemd` service file users will want to follow the [service file guide](./beacon-node-systemd.md#import-validator-keys) instead!
Having followed the [deposit](./deposit.md) guide, you will have a `validator_keys` folder containing several `.json` files in the `nimbus-eth2` directory.
We'll import the signing key of each validator to the [data directory](./data-dir.md) using the `deposits import` command:
**Mainnet**
```sh
build/nimbus_beacon_node deposits import --data-dir=build/data/shared_mainnet_0
```
**Prater**
```sh
build/nimbus_beacon_node deposits import --data-dir=build/data/shared_prater_0
```
=== "Mainnet"
```sh
build/nimbus_beacon_node deposits import --data-dir=build/data/shared_mainnet_0
```
```admonish note
You'll be asked to enter the password you created to encrypt your keystore(s).
```
=== "Prater"
```sh
build/nimbus_beacon_node deposits import --data-dir=build/data/shared_prater_0
```
!!! note
You'll be asked to enter the password you created to encrypt your keystore(s).
If your `validator_keys` folder is stored elsewhere, you can pass its location to the import command:
**Mainnet**
```sh
build/nimbus_beacon_node deposits import \
--data-dir=build/data/shared_mainnet_0 \
/path/to/keys
```
=== "Mainnet"
```sh
build/nimbus_beacon_node deposits import \
--data-dir=build/data/shared_mainnet_0 \
/path/to/keys
```
**Prater**
```sh
build/nimbus_beacon_node deposits import \
--data-dir=build/data/shared_prater_0 \
/path/to/keys
```
=== "Prater"
```sh
build/nimbus_beacon_node deposits import \
--data-dir=build/data/shared_prater_0 \
/path/to/keys
```
Replacing `/path/to/keys` with the full pathname of where the `validator_keys` directory is found.
@ -45,15 +44,13 @@ On success, a message will be printed that your keys have been imported:
NOT 2022-07-19 17:36:37.578+02:00 Keystore imported
```
```admonish note title=''
`NOT` is short for `NOTICE` and not not :)
```
!!! note ""
`NOT` is short for `NOTICE` and not not :)
After importing keys, it's time to [restart](./connect-eth2.md) the node and check that the keys have been picked up by the beacon node.
```admonish tip
You can read more about the different types of keys [here](https://blog.ethereum.org/2020/05/21/keys/) - the `deposit import` command will import the **signing key** only.
```
!!! tip
You can read more about the different types of keys [here](https://blog.ethereum.org/2020/05/21/keys/) - the `deposit import` command will import the **signing key** only.
## Troubleshooting

5
docs/the_nimbus_book/src/logging.md
View File

@ -4,9 +4,8 @@
Nimbus offers several options for logging - by default, logs are written to stdout using the [chronicles](https://github.com/status-im/nim-chronicles#introduction) `textlines` format which is convenient to read and can be used with tooling for [heroku/logfmt](https://brandur.org/logfmt).
```admonish tip
`NOT` at the beginning of a log line means 'NOTICE`
```
!!! tip
`NOT` at the beginning of a log line means 'NOTICE`
## Change log level

18
docs/the_nimbus_book/src/migration.md
View File

@ -1,11 +1,11 @@
# Migrate from another client
This guide will take you through the basics of how to migrate to Nimbus from another client. *See [here](./migration-options.md) for advanced options*.
The main pain point involves the exporting and importing of the [slashing protection database](https://eips.ethereum.org/EIPS/eip-3076), since each client takes a slightly different approach here.
**The most important takeaway is that you ensure that two clients will never validate with the same keys at the same time.** In other words, you must ensure that your original client is stopped, and no longer validating, before importing your keys into Nimbus.
!!! warning
**The most important takeaway is that you ensure that two clients will never validate with the same keys at the same time.** In other words, you must ensure that your original client is stopped, and no longer validating, before importing your keys into Nimbus.
> **Please take your time to get this right.** Don't hesitate to reach out to us in the `#helpdesk` channel of [our discord](https://discord.gg/j3nYBUeEad) if you come across a stumbling block. We are more than happy to help guide you through the migration process. Given what's at stake, there is no such thing as a stupid question.
@ -17,9 +17,9 @@ The easiest way to do this is to follow the [beacon node quick start guide](./qu
Once your Nimbus beacon node has synced and you're satisfied that it's working, move to **Step 2**.
> **Tip:** See here for how to [keep track of your syncing progress](keep-an-eye.md#keep-track-of-your-syncing-progress).
>
>
> Alternatively, If you run the Nimbus beacon node with the `--rest` option enabled (e.g. `./run-mainnet-beacon-node.sh --rest`), you can obtain your node's syncing status by running:
>
>
> ```
> curl -X GET http://localhost:5052/eth/v1/node/syncing
> ```
@ -50,8 +50,8 @@ It's important that you disable the Prysm validator as well as stopping it, to p
Run the following to export your Prysm validator's [slashing protection](https://eips.ethereum.org/EIPS/eip-3076) history:
```
prysm.sh validator slashing-protection-history export \
--datadir=/your/prysm/wallet \
prysm.sh validator slashing-protection-history export \
--datadir=/your/prysm/wallet \
--slashing-protection-export-dir=/path/to/export_dir
```
@ -94,7 +94,7 @@ This will export your history in the correct format to `slashing-protection.json
### From Teku
#### 1. Disable Teku
#### 1. Disable Teku
If you're using systemd and your service is called `teku`, run the following command to stop and disable the service:
@ -125,7 +125,7 @@ Where:
#### 1. Disable the Nimbus validator client
Once your Nimbus beacon node on your new setup has synced and you're satisfied that it's working, stop and disable the Nimbus validator client on your current setup.
Once your Nimbus beacon node on your new setup has synced and you're satisfied that it's working, stop and disable the Nimbus validator client on your current setup.
If you're using systemd and your service is called `nimbus-eth2-mainnet`, run the following commands to stop and disable the service:
@ -169,7 +169,7 @@ Replacing `/path/to/export_dir` with the file/directory you specified when you e
## Step 5 - Start the Nimbus validator
Follow the instructions [here](./connect-eth2.html) to start your validator using our pre-built [binaries](./binaries.md).
Follow the instructions [here](./connect-eth2.md) to start your validator using our pre-built [binaries](./binaries.md).
If you prefer to use Docker, see [here](./docker.md)

76
docs/the_nimbus_book/src/more-keys.md
View File

@ -14,31 +14,29 @@ Specifically, we'll be using the `existing-mnemonic` command. Here's a descripti
## Recover existing key
```admonish warning
Recovering validator keys from a mnemonic should only be used as a last resort. Exposing your mnemonic to a computer at any time puts it at risk of being compromised. Your mnemonic is not encrypted and if leaked, can be used to steal your funds.
```
!!! warning
Recovering validator keys from a mnemonic should only be used as a last resort. Exposing your mnemonic to a computer at any time puts it at risk of being compromised. Your mnemonic is not encrypted and if leaked, can be used to steal your funds.
```admonish note
The commands below assume you are trying to recover the first key you created, hence `--validator_start_index` has been set to `0`.
```
!!! note
The commands below assume you are trying to recover the first key you created, hence `--validator_start_index` has been set to `0`.
Run the following command from the directory which contains the `deposit` executable:
**Mainnet**
```
./deposit existing-mnemonic \
--validator_start_index 0 \
--num_validators 1 \
--chain mainnet
```
=== "Mainnet"
```
./deposit existing-mnemonic \
--validator_start_index 0 \
--num_validators 1 \
--chain mainnet
```
**Prater**
```
./deposit existing-mnemonic \
--validator_start_index 0 \
--num_validators 1 \
--chain prater
```
=== "Prater"
```
./deposit existing-mnemonic \
--validator_start_index 0 \
--num_validators 1 \
--chain prater
```
You'll be prompted to enter your mnemonic, and a new password for your keystore.
@ -48,31 +46,29 @@ Copy the `validator_keys` directory to `nimbus-eth2` and then follow the instruc
## Generate another key
```admonish warning
If you wish to use your new key with a separate client instance, make sure not to include your first key in the second setup - doing so will lead to it being slashed!
```
!!! warning
If you wish to use your new key with a separate client instance, make sure not to include your first key in the second setup - doing so will lead to it being slashed!
```admonish note
The commands below assume you already have one key and wish to generate a second, hence `--validator_start_index` has been set to `1` (as `0` would be the original key)
```
!!! note
The commands below assume you already have one key and wish to generate a second, hence `--validator_start_index` has been set to `1` (as `0` would be the original key)
Run the following command from the directory which contains the `deposit` executable:
**Mainnet**
```
./deposit existing-mnemonic \
--validator_start_index 1 \
--num_validators 1 \
--chain mainnet
```
=== "Mainnet"
```
./deposit existing-mnemonic \
--validator_start_index 1 \
--num_validators 1 \
--chain mainnet
```
**Prater**
```
./deposit existing-mnemonic \
--validator_start_index 1 \
--num_validators 1 \
--chain prater
```
=== "Prater"
```
./deposit existing-mnemonic \
--validator_start_index 1 \
--num_validators 1 \
--chain prater
```
You'll be prompted to enter your mnemonic, and a new password for your keystore.

17
docs/the_nimbus_book/src/options.md
View File

@ -123,15 +123,16 @@ sub-commands should appear in a section of the file matching the sub-command nam
Here is an example config file illustrating all of the above:
```admonish example title='nimbus-eth2-config.toml'
# Comments look like this
doppelganger-detection = true
web3-url = ["ws://192.168.1.10:8000"]
num-threads = 0
!!! example "nimbus-eth2.toml"
```toml
# Comments look like this
doppelganger-detection = true
web3-url = ["ws://192.168.1.10:8000"]
num-threads = 0
[trustedNodeSync]
trusted-node-url = "http://192.168.1.20:5052"
```
[trustedNodeSync]
trusted-node-url = "http://192.168.1.20:5052"
```
## Exit Codes

15
docs/the_nimbus_book/src/pi-guide.md
View File

@ -21,17 +21,16 @@ One of the most important aspects of the Raspberry Pi experience is trying to ma
- Basic understanding of the [command line](https://www.learnenough.com/command-line-tutorial/basics)
- 200GB SSD (2TB recommended if also running execution client)
```admonish note
You will need an SSD to run the Nimbus (without an SSD drive you have absolutely no chance of syncing the Ethereum blockchain). You have two options:
!!! note
You will need an SSD to run the Nimbus - mechanical hard drives are typically too slow to run an Ethereum node. You have two options:
1. Use an USB portable SSD disk such as the Samsung T5 Portable SSD.
2. Use an USB 3.0 External Hard Drive Case with a SSD Disk. For example, [Ethereum on Arm](https://twitter.com/EthereumOnARM) use an Inateck 2.5 Hard Drive Enclosure FE2011. Make sure to buy a case with an UASP compliant chip, particularly, one of these: JMicron (JMS567 or JMS578) or ASMedia (ASM1153E).
1. Use an USB portable SSD disk such as the Samsung T5 Portable SSD.
2. Use an USB 3.0 External Hard Drive Case with a SSD Disk. For example, [Ethereum on Arm](https://twitter.com/EthereumOnARM) use an Inateck 2.5 Hard Drive Enclosure FE2011. Make sure to buy a case with an UASP compliant chip, particularly, one of these: JMicron (JMS567 or JMS578) or ASMedia (ASM1153E).
In both cases, avoid low quality SSD disks (the SSD is a key component of your node and can drastically affect both the performance and sync time). Keep in mind that you need to plug the disk to an USB 3.0 port (the blue port).
In both cases, avoid low quality SSD disks (the SSD is a key component of your node and can drastically affect both the performance and sync time). Keep in mind that you need to plug the disk to an USB 3.0 port (the blue port).
```admonish note
If you have a Raspberry Pi 4 and are getting bad speeds transferring data to/from USB3.0 SSDs, please [read this recommended fix.](https://www.raspberrypi.org/forums/viewtopic.php?t=245931#p1501426)
```
!!! note
If you have a Raspberry Pi 4 and are getting bad speeds transferring data to/from USB3.0 SSDs, please [read this recommended fix.](https://www.raspberrypi.org/forums/viewtopic.php?t=245931#p1501426)
### 1. Download Raspberry Pi Imager

36
docs/the_nimbus_book/src/quick-start.md
View File

@ -10,13 +10,12 @@ Running a beacon node is a [worthwhile endeavor](https://vitalik.ca/general/2021
The guide assumes [Ubuntu Linux](https://ubuntu.com/download/server) is being used, and therefore some familiarity with [the linux command line](https://ubuntu.com/tutorials/command-line-for-beginners) is needed.
```admonish note
To become a validator, you will first need to be running a beacon node.
```
!!! note
To become a validator, you will first need to be running a beacon node.
!!! tip
You can practice running the node safely on the [Prater testnet](./prater.md) - throughout, we'll provide instructions for both Prater and Mainnet.
```admonish note
You can practice running the node safely on the [Prater testnet](./prater.md) - throughout, we'll provide instructions for both Prater and Mainnet.
```
## 1. Prepare
@ -37,9 +36,8 @@ wget https://github.com/status-im/nimbus-eth2/releases/download/v22.6.1/nimbus-e
tar xvf nimbus-eth2_Linux_amd64_22.6.1_2444e994.tar.gz --strip-components 1 -C nimbus-eth2
```
```admonish tip
Advanced users looking to take advantage of hardware-specific features and optimization may wish to [build from source](./build.md) instead!
```
!!! tip
Advanced users looking to take advantage of hardware-specific features and optimization may wish to [build from source](./build.md) instead!
## 3. Start the node
@ -49,19 +47,19 @@ Once you've installed the binaries, you can [start the node](./start-syncing.md)
cd nimbus-eth2
```
**Mainnet**
=== "Mainnet"
```sh
# Start a mainnet node
./run-mainnet-beacon-node.sh
```
```sh
# Start a mainnet node
./run-mainnet-beacon-node.sh
```
**Prater**
=== "Prater"
```sh
# Start a prater testnet node
./run-prater-beacon-node.sh
```
```sh
# Start a prater testnet node
./run-prater-beacon-node.sh
```
Once the beacon node starts, you'll see it logging information to the console, like so:

14
docs/the_nimbus_book/src/run-a-validator.md
View File

@ -2,13 +2,12 @@
Once your beacon node is [running and synced](./quick-start.md), the next step is to set up a validator.
```admonish note
Unlike other beacon chain clients, Nimbus does not require setting up a separate validator client process - the beacon node can itself perform validator duties.
!!! note
Unlike other beacon chain clients, Nimbus does not require setting up a separate validator client process - the beacon node can itself perform validator duties.
This is a simple, safe and efficient way to get started.
This is a simple, safe and efficient way to get started.
Advanced users may want to use a separate [validator client](./validator-client.md) process instead.
```
Advanced users may want to use a separate [validator client](./validator-client.md) process instead.
## 1. Deposit
@ -22,6 +21,5 @@ Advanced users may want to use a separate [validator client](./validator-client.
[Start performing duties](./connect-eth2.md) by restarting the node
```admonish tip
While that's all there is to it, it is essential that you both [keep an eye on your validator](keep-an-eye.md) and [keep Nimbus updated](keep-updated.md) regularly 💫
```
!!! tip
While that's all there is to it, it is essential that you both [keep an eye on your validator](keep-an-eye.md) and [keep Nimbus updated](keep-updated.md) regularly 💫

17
docs/the_nimbus_book/src/start-syncing.md
View File

@ -4,21 +4,18 @@ Before you can use your node, it needs to sync with the network. Syncing starts
If you are planning to become a validator, you should ensure that your beacon node is [completely synced](./keep-an-eye.md#keep-track-of-your-syncing-progress) before submitting your deposit, or you might miss attestations and proposal duties until it has finished syncing.
```admonish tip
To get started more quickly, you can perform a [trusted node sync](./trusted-node-sync.md) instead - this requires access to a synced node or a third-party service.
```
!!! tip
To get started more quickly, you can perform a [trusted node sync](./trusted-node-sync.md) instead - this requires access to a synced node or a third-party service.
```admonish note
You need need to run an execution client (**web3 provider**) together with the beacon node. See [here](./eth1.md) for instructions on how to do so.
```
!!! note
You need need to run an execution client (**web3 provider**) together with the beacon node. See [here](./eth1.md) for instructions on how to do so.
## Networks
Using Nimbus, you can connect either to a testnet, or mainnet. Mainnet is the main ethereum network where real assets are at stake, while testnets are used by users and developers alike to test their node and setup before committing real assets.
```admonish tip
If this is the first time you're setting up your node, it is recommended you run it on a testnet first. Later, when everything is working, you can easily switch to mainned.
```
!!! tip
If this is the first time you're setting up your node, it is recommended you run it on a testnet first. Later, when everything is working, you can easily switch to mainned.
### Testnet
@ -78,4 +75,4 @@ More information is available from the [options](./options.md) page.
## Keep track of your sync progress
See [here](./keep-an-eye.html#keep-track-of-your-syncing-progress) for how to keep track of your sync progress.
See [here](./keep-an-eye.md#keep-track-of-your-syncing-progress) for how to keep track of your sync progress.

17
docs/the_nimbus_book/src/troubleshooting.md
View File

@ -1,18 +1,16 @@
# Troubleshooting
```admonish note
The commands on this page refer to mainnet. If you're running on `prater` or another testnet, replace `mainnet` accordingly
```
!!! note
The commands on this page refer to mainnet. If you're running on `prater` or another testnet, replace `mainnet` accordingly
We are continuously making improvements to both stability and resource usage. If you run into any problem with Nimbus and are not running the latest version, chances are they have already been fixed - see the [update guide](./keep-updated.md) for instructions of how to upgrade.
If you can't find a solution to your problem here, get in touch with us on our [discord](https://discord.com/invite/XRxWahP)!
```admonish note
When installing Nimbus, you will typically be using the latest `stable` release.
!!! note
When installing Nimbus, you will typically be using the latest `stable` release.
However, the latest changes happen in the `unstable` branch - if you're looking to test the chaings coming to the _next_ Nimbus release, consider building Nimbus from [source](./keep-updated.md#build-from-source) using the `unstable` branch.
```
However, the latest changes happen in the `unstable` branch - if you're looking to test the chaings coming to the _next_ Nimbus release, consider building Nimbus from [source](./keep-updated.md#build-from-source) using the `unstable` branch.
## Networking
@ -84,9 +82,8 @@ If, on start, you see `The command 'noCommand' does not accept arguments`
Double check to see if your command line flags are in the correct format, i.e. `--foo=bar`, `--baz`, or `--foo-bar=qux`.
```admonish tip
All options accepting values need a `=` between the option name and the value!
```
!!! tip
All options accepting values need a `=` between the option name and the value!
### Address already in use error

59
docs/the_nimbus_book/src/trusted-node-sync.md
View File

@ -1,8 +1,7 @@
# Sync from a trusted node
```admonish title=''
This feature is available from `v1.7.0` onwards
```
!!! note ""
This feature is available from `v1.7.0` onwards
When you [start the beacon node](./quick-start.md) for the first time, it will connect to the beacon chain network and start syncing automatically - a process that can take several days.
@ -16,32 +15,28 @@ It is possibly to use trusted node sync with a third-party API provider -- see [
## Perform a trusted node sync
```admonish tip
Make sure to replace `http://localhost:5052` in the commands below with the appropriate endpoint of the trusted beacon node. `http://localhost:5052` is the default endpoint exposed by Nimbus, but this is not consistent across all clients.
!!! tip
Make sure to replace `http://localhost:5052` in the commands below with the appropriate endpoint of the trusted beacon node. `http://localhost:5052` is the default endpoint exposed by Nimbus, but this is not consistent across all clients.
For example, if your trusted node is a [Prysm node](https://docs.prylabs.network/docs/how-prysm-works/ethereum-public-api#performing-requests-against-a-local-prysm-node), it exposes `127.0.0.1:3500` by default. Which means you would run the commands below with `--trusted-node-url=http://127.0.0.1:3500`
```
For example, if your trusted node is a [Prysm node](https://docs.prylabs.network/docs/how-prysm-works/ethereum-public-api#performing-requests-against-a-local-prysm-node), it exposes `127.0.0.1:3500` by default. Which means you would run the commands below with `--trusted-node-url=http://127.0.0.1:3500`
**Mainnet**
=== "Mainnet"
```sh
build/nimbus_beacon_node trustedNodeSync \
--network:mainnet \
--data-dir=build/data/shared_mainnet_0 \
--trusted-node-url=http://localhost:5052
```
```sh
build/nimbus_beacon_node trustedNodeSync \
--network:mainnet \
--data-dir=build/data/shared_mainnet_0 \
--trusted-node-url=http://localhost:5052
```
=== "Prater"
```sh
build/nimbus_beacon_node trustedNodeSync --network:prater \
--data-dir=build/data/shared_prater_0 \
--trusted-node-url=http://localhost:5052
```
**Prater (testnet)**
```sh
build/nimbus_beacon_node trustedNodeSync --network:prater \
--data-dir=build/data/shared_prater_0 \
--trusted-node-url=http://localhost:5052
```
```admonish note
Because trusted node sync by default copies all blocks via REST, you may hit API limits if you are using a third-party provider. If this happens to you, you may need to use the `--backfill` option to [delay the backfill of the block history](./trusted-node-sync.md#delay-block-history-backfill).
```
!!! note
Because trusted node sync by default copies all blocks via REST, you may hit API limits if you are using a third-party provider. If this happens to you, you may need to use the `--backfill` option to [delay the backfill of the block history](./trusted-node-sync.md#delay-block-history-backfill).
## Verify you synced the correct chain
@ -55,12 +50,11 @@ curl http://localhost:5052/eth/v1/beacon/blocks/head/root
The `head` root is also printed in the log output at regular intervals.
```admonish note
The same [Beacon API](./rest-api.md) request works with any third-party provider.
!!! note
The same [Beacon API](./rest-api.md) request works with any API provider.
For example, to compare it out with our mainnet [testing server](rest-api.md#test-your-tooling-against-our-servers), you can run:
`curl -X GET http://testing.mainnet.beacon-api.nimbus.team/eth/v1/beacon/blocks/head/root`
```
For example, to compare it out with our mainnet [testing server](rest-api.md#test-your-tooling-against-our-servers), you can run:
`curl -X GET http://testing.mainnet.beacon-api.nimbus.team/eth/v1/beacon/blocks/head/root`
## Advanced
@ -72,9 +66,8 @@ It is possible to get started more quickly by delaying the backfill of the block
You can also resume the trusted node backfill at any time by simply running the trusted node sync command again.
```admonish
While backfilling blocks, your node will not be able to answer historical requests or sync requests. This might lead to you being de-scored, and eventually disconnected, by your peers.
```
!!! note
While backfilling blocks, your node will not be able to answer historical requests or sync requests. This might lead to you being de-scored, and eventually disconnected, by your peers.
### Modify sync point

20
docs/the_nimbus_book/src/validator-client.md
View File

@ -1,16 +1,14 @@
# Run a separate validator client
```admonish warning
This feature is currently in BETA - we are still testing it and implementation details may change in response to community feedback. **We strongly advise against using it on mainnet** - your validators may get slashed
```
!!! warning
This feature is currently in BETA - we are still testing it and implementation details may change in response to community feedback. **We strongly advise against using it on mainnet** - your validators may get slashed
By default, Nimbus loads validator keys into the main beacon node process, which is a simple, safe and efficient way to run a validator.
Advanced users may wish to run validators in a separate process, allowing more flexible deployment strategies. The Nimbus beacon node supports both its own and third-party validator clients via the built-in [REST API](./rest-api.md).
```admonish warning
So far, all slashings with known causes have been linked to overly complex setups involving separation between beacon node and validator client! Only use this setup if you've taken steps to mitigate the increased risk.
```
!!! warning
So far, all slashings with known causes have been linked to overly complex setups involving separation between beacon node and validator client! Only use this setup if you've taken steps to mitigate the increased risk.
## Build
@ -38,13 +36,11 @@ build/nimbus_beacon_node deposits import \
--data-dir:build/data/vc_shared_prater_0 "<YOUR VALIDATOR KEYS DIRECTORY>"
```
```admonish warning
Do not use the same data directory for beacon node and validator client - they will both try to load the same keys which may result in slashing!
```
!!! warning
Do not use the same data directory for beacon node and validator client - they will both try to load the same keys which may result in slashing!
```admonish warning
If you are migrating your keys from the beacon node to the validator client, simply move the `secrets` and `validators` folders in the beacon node data directory to the data directory of the validator client
```
!!! warning
If you are migrating your keys from the beacon node to the validator client, simply move the `secrets` and `validators` folders in the beacon node data directory to the data directory of the validator client
With the keys imported, you are ready to start validator client:

10
docs/the_nimbus_book/src/validator-monitor.md
View File

@ -1,8 +1,7 @@
# Validator monitoring
```admonish warning
This feature is currently in BETA - implementation details such as metric names and counters may change in response to community feedback.
```
!!! warning
This feature is currently in BETA - implementation details such as metric names and counters may change in response to community feedback.
The validator monitoring feature allows for tracking the life-cycle and performance of one or more validators in detail.
@ -58,9 +57,8 @@ NOT 2021-11-17 20:53:42.108+01:00 Attestation failed to match head top
Failures are reported with a lag of two epochs (~13 minutes) - to examine the log for potential root causes, the logs from the epoch in the failure message should be looked at.
```admonish warning
It should be noted that metrics are tracked for the current history - in the case of a reorg on the chain - in particular a deep reorg - no attempt is made to revisit previously reported values. In the case that finality is delayed, the risk of stale metrics increases.
```
!!! warning
It should be noted that metrics are tracked for the current history - in the case of a reorg on the chain - in particular a deep reorg - no attempt is made to revisit previously reported values. In the case that finality is delayed, the risk of stale metrics increases.
Likewise, many metrics, such as aggregation inclusion, reflect conditions on the network - it may happen that the same message is counted more than once under certain conditions.

47
docs/the_nimbus_book/src/voluntary-exit.md
View File

@ -1,43 +1,38 @@
# Perform a voluntary exit
```admonish title=''
This feature is available from `v1.7.0` onwards - earlier versions relied on the now removed [JSON-RPC API](./api.md).
```
!!! note ""
This feature is available from `v1.7.0` onwards - earlier versions relied on the now removed [JSON-RPC API](./api.md).
Voluntary exits allow validators to permanently stop performing their duties, and eventually recover the deposit.
Exits are subject to a wait period that depends on the length of the exit queue. While a validator is exiting, it still must perform its duties in order not to lose funds to inactivity penalities.
```admonish warning
Voluntary exits are **irreversible**. You won't be able to validate again with the same key.
!!! warning
Voluntary exits are **irreversible**. You won't be able to validate again with the same key.
You will also not be able to withdraw your funds until a future hard fork that enables withdrawals.*
```
You will also not be able to withdraw your funds until a future hard fork that enables withdrawals.*
```admonish note
Voluntary exits won't be processed if the chain isn't finalising.
```
!!! note
Voluntary exits won't be processed if the chain isn't finalising.
To perform a voluntary exit, make sure your beacon node is running with the `--rest`option enabled (e.g. `./run-mainnet-beacon-node.sh --rest`), then run:
=== "Mainnet"
```
build/nimbus_beacon_node deposits exit \
--data-dir=build/data/shared_mainnet_0 \
--validator=<VALIDATOR_PUBLIC_KEY>
```
**Mainnet**
```
build/nimbus_beacon_node deposits exit \
--data-dir=build/data/shared_mainnet_0 \
--validator=<VALIDATOR_PUBLIC_KEY>
```
=== "Prater"
```
build/nimbus_beacon_node deposits exit \
--data-dir=build/data/shared_prater_0 \
--validator=<VALIDATOR_PUBLIC_KEY>
```
**Prater**
```
build/nimbus_beacon_node deposits exit \
--data-dir=build/data/shared_prater_0 \
--validator=<VALIDATOR_PUBLIC_KEY>
```
```admonish note
Make sure your `<VALIDATOR_PUBLIC_KEY>` is prefixed with `0x`. In other words the public key should look like `0x95e3...`
```
!!! note
Make sure your `<VALIDATOR_PUBLIC_KEY>` is prefixed with `0x`. In other words the public key should look like `0x95e3...`
## `rest-url` parameter

5
docs/the_nimbus_book/src/web3-backup.md
View File

@ -4,9 +4,8 @@ It's a good idea to add a backup web3 provider in case your main one goes down.
For example, if your primary execution client is a [local Geth](./eth1.md#geth), but you want to use [Infura](./infura-guide.md) as a backup you would run:
```admonish warn
After [the merge](./merge.md), it will no longer be possible to rely on third-party services like Infura to run a beacon node!
```
!!! warn
After [the merge](./merge.md), it will no longer be possible to rely on third-party services like Infura to run a beacon node!
```sh
./run-mainnet-beacon-node.sh \