diff --git a/Makefile b/Makefile index b9a7803e6..7649be086 100644 --- a/Makefile +++ b/Makefile @@ -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 . && { \ diff --git a/docs/.gitignore b/docs/.gitignore new file mode 100644 index 000000000..016bb16df --- /dev/null +++ b/docs/.gitignore @@ -0,0 +1 @@ +mkdocs diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 000000000..c7d9a1ea2 --- /dev/null +++ b/docs/Makefile @@ -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 diff --git a/docs/requirements.in b/docs/requirements.in new file mode 100644 index 000000000..5d3c26056 --- /dev/null +++ b/docs/requirements.in @@ -0,0 +1,2 @@ +pip-tools +mkdocs-material diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 000000000..f7c82b0d5 --- /dev/null +++ b/docs/requirements.txt @@ -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 diff --git a/docs/the_nimbus_book/.gitignore b/docs/the_nimbus_book/.gitignore index 7585238ef..8081e1d94 100644 --- a/docs/the_nimbus_book/.gitignore +++ b/docs/the_nimbus_book/.gitignore @@ -1 +1,2 @@ book +site diff --git a/docs/the_nimbus_book/book.toml b/docs/the_nimbus_book/book.toml deleted file mode 100644 index 4075639c9..000000000 --- a/docs/the_nimbus_book/book.toml +++ /dev/null @@ -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" - diff --git a/docs/the_nimbus_book/custom.css b/docs/the_nimbus_book/custom.css deleted file mode 100644 index 3b7cb13e4..000000000 --- a/docs/the_nimbus_book/custom.css +++ /dev/null @@ -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; -} diff --git a/docs/the_nimbus_book/mdbook-admonish.css b/docs/the_nimbus_book/mdbook-admonish.css deleted file mode 100644 index 5e360387d..000000000 --- a/docs/the_nimbus_book/mdbook-admonish.css +++ /dev/null @@ -1,352 +0,0 @@ -@charset "UTF-8"; -:root { - --md-admonition-icon--note: - url("data:image/svg+xml;charset=utf-8,"); - --md-admonition-icon--abstract: - url("data:image/svg+xml;charset=utf-8,"); - --md-admonition-icon--info: - url("data:image/svg+xml;charset=utf-8,"); - --md-admonition-icon--tip: - url("data:image/svg+xml;charset=utf-8,"); - --md-admonition-icon--success: - url("data:image/svg+xml;charset=utf-8,"); - --md-admonition-icon--question: - url("data:image/svg+xml;charset=utf-8,"); - --md-admonition-icon--warning: - url("data:image/svg+xml;charset=utf-8,"); - --md-admonition-icon--failure: - url("data:image/svg+xml;charset=utf-8,"); - --md-admonition-icon--danger: - url("data:image/svg+xml;charset=utf-8,"); - --md-admonition-icon--bug: - url("data:image/svg+xml;charset=utf-8,"); - --md-admonition-icon--example: - url("data:image/svg+xml;charset=utf-8,"); - --md-admonition-icon--quote: - url("data:image/svg+xml;charset=utf-8,"); - --md-details-icon: - url("data:image/svg+xml;charset=utf-8,"); -} - -: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,'); - -webkit-mask-image: url('data:image/svg+xml;charset=utf-8,'); - 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); -} diff --git a/docs/the_nimbus_book/mkdocs.yml b/docs/the_nimbus_book/mkdocs.yml new file mode 100644 index 000000000..c1ff70a7c --- /dev/null +++ b/docs/the_nimbus_book/mkdocs.yml @@ -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' diff --git a/docs/the_nimbus_book/src/SUMMARY.md b/docs/the_nimbus_book/src/SUMMARY.md deleted file mode 100644 index 04db422f7..000000000 --- a/docs/the_nimbus_book/src/SUMMARY.md +++ /dev/null @@ -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) diff --git a/docs/the_nimbus_book/src/additional-validator.md b/docs/the_nimbus_book/src/additional-validator.md index d0fb9c681..7b6edaead 100644 --- a/docs/the_nimbus_book/src/additional-validator.md +++ b/docs/the_nimbus_book/src/additional-validator.md @@ -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. diff --git a/docs/the_nimbus_book/src/api.md b/docs/the_nimbus_book/src/api.md index c34386f69..60b2210a5 100644 --- a/docs/the_nimbus_book/src/api.md +++ b/docs/the_nimbus_book/src/api.md @@ -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. diff --git a/docs/the_nimbus_book/src/beacon-node-systemd.md b/docs/the_nimbus_book/src/beacon-node-systemd.md index e298bcd53..889e762a7 100644 --- a/docs/the_nimbus_book/src/beacon-node-systemd.md +++ b/docs/the_nimbus_book/src/beacon-node-systemd.md @@ -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 diff --git a/docs/the_nimbus_book/src/build.md b/docs/the_nimbus_book/src/build.md index 98ae8e844..76fa5cb5b 100644 --- a/docs/the_nimbus_book/src/build.md +++ b/docs/the_nimbus_book/src/build.md @@ -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. diff --git a/docs/the_nimbus_book/src/connect-eth2.md b/docs/the_nimbus_book/src/connect-eth2.md index 872e98dd2..72d11e8e0 100644 --- a/docs/the_nimbus_book/src/connect-eth2.md +++ b/docs/the_nimbus_book/src/connect-eth2.md @@ -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 diff --git a/docs/the_nimbus_book/src/data-dir.md b/docs/the_nimbus_book/src/data-dir.md index c9778e0e6..da0c1f715 100644 --- a/docs/the_nimbus_book/src/data-dir.md +++ b/docs/the_nimbus_book/src/data-dir.md @@ -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 /validators -type f -exec icacls {} /inheritance:r /grant:r $USER find /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: diff --git a/docs/the_nimbus_book/src/deposit.md b/docs/the_nimbus_book/src/deposit.md index 95d27ac77..c058bdcbc 100644 --- a/docs/the_nimbus_book/src/deposit.md +++ b/docs/the_nimbus_book/src/deposit.md @@ -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). diff --git a/docs/the_nimbus_book/src/eth1.md b/docs/the_nimbus_book/src/eth1.md index 26b853270..080bad3e0 100644 --- a/docs/the_nimbus_book/src/eth1.md +++ b/docs/the_nimbus_book/src/eth1.md @@ -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: diff --git a/docs/the_nimbus_book/src/faq.md b/docs/the_nimbus_book/src/faq.md index fb7f6d2a6..6d8a83b48 100644 --- a/docs/the_nimbus_book/src/faq.md +++ b/docs/the_nimbus_book/src/faq.md @@ -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 diff --git a/docs/the_nimbus_book/src/graffiti.md b/docs/the_nimbus_book/src/graffiti.md index c57443636..55bbf21cc 100644 --- a/docs/the_nimbus_book/src/graffiti.md +++ b/docs/the_nimbus_book/src/graffiti.md @@ -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="" + ``` -```sh -./run-mainnet-beacon-node.sh --graffiti="" -``` - -**Prater** -```sh -./run-prater-beacon-node.sh --graffiti="" -``` +=== "Prater" + ```sh + ./run-prater-beacon-node.sh --graffiti="" + ``` diff --git a/docs/the_nimbus_book/src/index.md b/docs/the_nimbus_book/src/index.md new file mode 100644 index 000000000..1208e68e5 --- /dev/null +++ b/docs/the_nimbus_book/src/index.md @@ -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). + +
+ + + +
+ +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. diff --git a/docs/the_nimbus_book/src/intro.md b/docs/the_nimbus_book/src/intro.md index 2064154eb..61aa47fbe 100644 --- a/docs/the_nimbus_book/src/intro.md +++ b/docs/the_nimbus_book/src/intro.md @@ -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). - -
- - - -
- -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) diff --git a/docs/the_nimbus_book/src/keep-updated.md b/docs/the_nimbus_book/src/keep-updated.md index 14b77f228..bf8811ca4 100644 --- a/docs/the_nimbus_book/src/keep-updated.md +++ b/docs/the_nimbus_book/src/keep-updated.md @@ -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 diff --git a/docs/the_nimbus_book/src/keymanager-api.md b/docs/the_nimbus_book/src/keymanager-api.md index f8505a639..0db15ad35 100644 --- a/docs/the_nimbus_book/src/keymanager-api.md +++ b/docs/the_nimbus_book/src/keymanager-api.md @@ -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. diff --git a/docs/the_nimbus_book/src/keys.md b/docs/the_nimbus_book/src/keys.md index 01036483e..76e92e2d2 100644 --- a/docs/the_nimbus_book/src/keys.md +++ b/docs/the_nimbus_book/src/keys.md @@ -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 diff --git a/docs/the_nimbus_book/src/logging.md b/docs/the_nimbus_book/src/logging.md index 3553965ad..20c7bb339 100644 --- a/docs/the_nimbus_book/src/logging.md +++ b/docs/the_nimbus_book/src/logging.md @@ -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 diff --git a/docs/the_nimbus_book/src/migration.md b/docs/the_nimbus_book/src/migration.md index eeac037c3..2167bf399 100644 --- a/docs/the_nimbus_book/src/migration.md +++ b/docs/the_nimbus_book/src/migration.md @@ -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) diff --git a/docs/the_nimbus_book/src/more-keys.md b/docs/the_nimbus_book/src/more-keys.md index 74cbf55aa..82fde4624 100644 --- a/docs/the_nimbus_book/src/more-keys.md +++ b/docs/the_nimbus_book/src/more-keys.md @@ -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. diff --git a/docs/the_nimbus_book/src/options.md b/docs/the_nimbus_book/src/options.md index 0789ef556..a21123603 100644 --- a/docs/the_nimbus_book/src/options.md +++ b/docs/the_nimbus_book/src/options.md @@ -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 diff --git a/docs/the_nimbus_book/src/pi-guide.md b/docs/the_nimbus_book/src/pi-guide.md index d2840025d..65df14156 100644 --- a/docs/the_nimbus_book/src/pi-guide.md +++ b/docs/the_nimbus_book/src/pi-guide.md @@ -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 diff --git a/docs/the_nimbus_book/src/quick-start.md b/docs/the_nimbus_book/src/quick-start.md index 79077ca8a..a70e3de6a 100644 --- a/docs/the_nimbus_book/src/quick-start.md +++ b/docs/the_nimbus_book/src/quick-start.md @@ -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: diff --git a/docs/the_nimbus_book/src/run-a-validator.md b/docs/the_nimbus_book/src/run-a-validator.md index 9887b4c28..089de3507 100644 --- a/docs/the_nimbus_book/src/run-a-validator.md +++ b/docs/the_nimbus_book/src/run-a-validator.md @@ -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 ๐Ÿ’ซ diff --git a/docs/the_nimbus_book/src/start-syncing.md b/docs/the_nimbus_book/src/start-syncing.md index e46967f1d..0b40bef34 100644 --- a/docs/the_nimbus_book/src/start-syncing.md +++ b/docs/the_nimbus_book/src/start-syncing.md @@ -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. diff --git a/docs/the_nimbus_book/src/troubleshooting.md b/docs/the_nimbus_book/src/troubleshooting.md index 7e5104b34..0fd8ef206 100644 --- a/docs/the_nimbus_book/src/troubleshooting.md +++ b/docs/the_nimbus_book/src/troubleshooting.md @@ -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 diff --git a/docs/the_nimbus_book/src/trusted-node-sync.md b/docs/the_nimbus_book/src/trusted-node-sync.md index a5a49698c..ff75b1337 100644 --- a/docs/the_nimbus_book/src/trusted-node-sync.md +++ b/docs/the_nimbus_book/src/trusted-node-sync.md @@ -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 diff --git a/docs/the_nimbus_book/src/validator-client.md b/docs/the_nimbus_book/src/validator-client.md index ad0c30b14..690b49aa6 100644 --- a/docs/the_nimbus_book/src/validator-client.md +++ b/docs/the_nimbus_book/src/validator-client.md @@ -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 "" ``` -```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: diff --git a/docs/the_nimbus_book/src/validator-monitor.md b/docs/the_nimbus_book/src/validator-monitor.md index c75d3f2e4..a60e4a26d 100644 --- a/docs/the_nimbus_book/src/validator-monitor.md +++ b/docs/the_nimbus_book/src/validator-monitor.md @@ -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. diff --git a/docs/the_nimbus_book/src/voluntary-exit.md b/docs/the_nimbus_book/src/voluntary-exit.md index 74afb78dd..118900f15 100644 --- a/docs/the_nimbus_book/src/voluntary-exit.md +++ b/docs/the_nimbus_book/src/voluntary-exit.md @@ -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= + ``` -**Mainnet** -``` -build/nimbus_beacon_node deposits exit \ - --data-dir=build/data/shared_mainnet_0 \ - --validator= -``` +=== "Prater" + ``` + build/nimbus_beacon_node deposits exit \ + --data-dir=build/data/shared_prater_0 \ + --validator= + ``` -**Prater** -``` -build/nimbus_beacon_node deposits exit \ - --data-dir=build/data/shared_prater_0 \ - --validator= -``` - -```admonish note -Make sure your `` is prefixed with `0x`. In other words the public key should look like `0x95e3...` -``` +!!! note + Make sure your `` is prefixed with `0x`. In other words the public key should look like `0x95e3...` ## `rest-url` parameter diff --git a/docs/the_nimbus_book/src/web3-backup.md b/docs/the_nimbus_book/src/web3-backup.md index b69062687..76ade8c25 100644 --- a/docs/the_nimbus_book/src/web3-backup.md +++ b/docs/the_nimbus_book/src/web3-backup.md @@ -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 \