update geth-developers docs - md formatting
This commit is contained in:
parent
18ae820f7a
commit
0bb421adc5
|
@ -1,17 +1,13 @@
|
|||
---
|
||||
title: Contributing
|
||||
description: Guidlines for contributing to Geth
|
||||
---
|
||||
|
||||
We welcome contributions from anyone on the internet, and are grateful for even the smallest of fixes!
|
||||
|
||||
## Contributing to the Geth source code
|
||||
|
||||
If you'd like to contribute to the Geth source code, please fork the
|
||||
[Github repository](https://github.com/ethereum/go-ethereum), fix, commit and send a pull request for the
|
||||
maintainers to review and merge into the main code base. If you wish to submit more complex changes
|
||||
though, please check up with the core devs first on our Discord Server to ensure those changes are in
|
||||
line with the general philosophy of the project and/or get some early feedback which can make both your
|
||||
efforts much lighter as well as our review and merge procedures quick and simple.
|
||||
If you'd like to contribute to the Geth source code, please fork the [Github repository](https://github.com/ethereum/go-ethereum), fix, commit and send a pull request for the maintainers to review and merge into the main code base. If you wish to submit more complex changes though, please check up with the core devs first on our Discord Server to ensure those changes are in line with the general philosophy of the project and/or get some early feedback which can make both your efforts much lighter as well as our review and merge procedures quick and simple.
|
||||
|
||||
Please make sure your contributions adhere to our coding guidelines:
|
||||
|
||||
|
@ -21,22 +17,15 @@ Please make sure your contributions adhere to our coding guidelines:
|
|||
* Commit messages should be prefixed with the package(s) they modify.
|
||||
E.g. "eth, rpc: make trace configs optional"
|
||||
|
||||
Pull requests generally need to be based on and opened against the `master` branch, unless by explicit agreement because the work is contributing to some more complex feature branch.
|
||||
|
||||
Pull requests generally need to be based on and opened against the `master` branch,
|
||||
unless by explicit agreement because the work is contributing to some more complex
|
||||
feature branch.
|
||||
All pull requests will be reviewed according to the [Code Review guidelines](/content/docs/developers/geth-developer/code-review-guidelines.md).
|
||||
|
||||
All pull requests will be reviewed according to the
|
||||
[Code Review guidelines](/content/docs/developers/geth-developer/code-review-guidelines.md).
|
||||
|
||||
We encourage an early pull request approach, meaning pull requests are created as early
|
||||
as possible even without the completed fix/feature. This will let core devs and other
|
||||
volunteers know you picked up an issue. These early PRs should indicate 'in progress' status.
|
||||
We encourage an early pull request approach, meaning pull requests are created as early as possible even without the completed fix/feature. This will let core devs and other volunteers know you picked up an issue. These early PRs should indicate 'in progress' status.
|
||||
|
||||
## Contributing to the Geth website
|
||||
|
||||
The Geth website is hosted separately from Geth itself. The contribution guidelines are the same. Please
|
||||
for the Geth website Github repository and raise pull requests for the maintainers to review and merge.
|
||||
The Geth website is hosted separately from Geth itself. The contribution guidelines are the same. Please for the Geth website Github repository and raise pull requests for the maintainers to review and merge.
|
||||
|
||||
## License
|
||||
|
||||
|
|
|
@ -1,13 +1,13 @@
|
|||
---
|
||||
title: Private Networks
|
||||
sort_key: D
|
||||
description: Tutorial on setting up private Ethereum networks
|
||||
---
|
||||
|
||||
This guide explains how to set up a private network of multiple Geth nodes. An Ethereum network is private if the nodes are not connected to the main network. In this context private only means reserved or isolated, rather than protected or secure. A fully controlled, private Ethereum network is useful as a backend for core developers working on issues relating to networking/blockchain syncing etc. Private networks are also useful for Dapp developers testing multi-block and multi-user scenarios.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
To follow the tutorial on this page it is necessary to have a working Geth installation (instructions [here](/docs/install-and-build/installing-geth)). It is also helpful to understand Geth fundamentals (see [Getting Started](/docs/getting-started)).
|
||||
To follow the tutorial on this page it is necessary to have a working Geth installation (instructions [here](content/docs/getting_started/Installing-Geth.md)). It is also helpful to understand Geth fundamentals (see [Getting Started](/content/docs/getting_started/getting_started.md)).
|
||||
|
||||
|
||||
## Private Networks
|
||||
|
@ -34,10 +34,7 @@ Geth's PoW algorithm, [Ethhash](https://ethereum.org/en/developers/docs/consensu
|
|||
|
||||
#### Clique
|
||||
|
||||
Clique consensus is a PoA system where new blocks can be created by authorized 'signers' only. The clique consenus protocol is specified in [EIP-225][clique-eip]. The initial set of authorized signers is configured in the genesis block. Signers can be authorized and de-authorized using a voting mechanism, thus allowing the set of signers to change while the blockchain operates. Clique can be configured to target any block time (within reasonable limits) since it isn't tied to the difficulty adjustment.
|
||||
|
||||
|
||||
[clique-eip]: https://eips.ethereum.org/EIPS/eip-225
|
||||
Clique consensus is a PoA system where new blocks can be created by authorized 'signers' only. The clique consenus protocol is specified in [EIP-225](https://eips.ethereum.org/EIPS/eip-225). The initial set of authorized signers is configured in the genesis block. Signers can be authorized and de-authorized using a voting mechanism, thus allowing the set of signers to change while the blockchain operates. Clique can be configured to target any block time (within reasonable limits) since it isn't tied to the difficulty adjustment.
|
||||
|
||||
|
||||
### Creating The Genesis Block
|
||||
|
@ -46,7 +43,7 @@ Every blockchain starts with a genesis block. When Geth is run with default sett
|
|||
|
||||
- Ethereum platform features enabled at launch (`config`). Enabling and disabling features once the blockchain is running requires scheduling a [hard fork](https://ethereum.org/en/glossary/#hard-fork).
|
||||
|
||||
- Initial block gas limit (`gasLimit`). This impacts how much EVM computation can happen within a single block. Mirroring the main Ethereum network is generally a [good choice][gaslimit-chart]. The block gas limit can be adjusted after launch using the `--miner.gastarget` command-line flag.
|
||||
- Initial block gas limit (`gasLimit`). This impacts how much EVM computation can happen within a single block. Mirroring the main Ethereum network is generally a [good choice](https://etherscan.io/chart/gaslimit). The block gas limit can be adjusted after launch using the `--miner.gastarget` command-line flag.
|
||||
|
||||
- Initial allocation of ether (`alloc`). This determines how much ether is available to the addresses listed in the genesis block. Additional ether can be created through mining as the chain progresses.
|
||||
|
||||
|
@ -55,7 +52,7 @@ Every blockchain starts with a genesis block. When Geth is run with default sett
|
|||
|
||||
Below is an example of a `genesis.json` file for a PoA network. The `config` section ensures that all known protocol changes are available and configures the 'clique' engine to be used for consensus. Note that the initial signer set must be configured through the `extradata` field. This field is required for Clique to work.
|
||||
|
||||
The signer account keys can be generated using the [geth account](./managing-your-accounts) command (this command can be run multiple times to create more than one signer key).
|
||||
The signer account keys can be generated using the [geth account](/content/docs/fundamentals/account-management.md) command (this command can be run multiple times to create more than one signer key).
|
||||
|
||||
```shell
|
||||
geth account new --datadir data
|
||||
|
@ -474,8 +471,4 @@ The same steps can then be repeated to attach a console to Node 2.
|
|||
|
||||
## Summary
|
||||
|
||||
This page explored the various options for configuring a local private network. A step by step guide showed how to set up and launch a private network, unlock the associated accounts, attach a console to check the network status and make some basic interactions.
|
||||
|
||||
|
||||
|
||||
[gaslimit-chart]: https://etherscan.io/chart/gaslimit
|
||||
This page explored the various options for configuring a local private network. A step by step guide showed how to set up and launch a private network, unlock the associated accounts, attach a console to check the network status and make some basic interactions.
|
|
@ -1,107 +1,72 @@
|
|||
---
|
||||
title: Code Review Guidelines
|
||||
sort_key: B
|
||||
description: Explanation of how code PRs are reviewed
|
||||
---
|
||||
|
||||
The only way to get code into Geth is to submit a pull request (PR). Those pull requests
|
||||
need to be reviewed by someone. This document is a guide that explains our expectations
|
||||
around PRs for both authors and reviewers.
|
||||
The only way to get code into Geth is to submit a pull request (PR). Those pull requests need to be reviewed by someone. This document is a guide that explains our expectations around PRs for both authors and reviewers.
|
||||
|
||||
## Terminology
|
||||
|
||||
* The **author** of a pull request is the entity who wrote the diff and submitted it to
|
||||
GitHub.
|
||||
* The **author** of a pull request is the entity who wrote the diff and submitted it to GitHub.
|
||||
|
||||
* The **team** consists of people with commit rights on the go-ethereum repository.
|
||||
|
||||
* The **reviewer** is the person assigned to review the diff. The reviewer must be a team
|
||||
member.
|
||||
* The **reviewer** is the person assigned to review the diff. The reviewer must be a team member.
|
||||
|
||||
* The **code owner** is the person responsible for the subsystem being modified by the PR.
|
||||
|
||||
## The Process
|
||||
|
||||
The first decision to make for any PR is whether it's worth including at all. This
|
||||
decision lies primarily with the code owner, but may be negotiated with team members.
|
||||
The first decision to make for any PR is whether it's worth including at all. This decision lies primarily with the code owner, but may be negotiated with team members.
|
||||
|
||||
To make the decision we must understand what the PR is about. If there isn't enough
|
||||
description content or the diff is too large, request an explanation. Anyone can do this
|
||||
part.
|
||||
To make the decision we must understand what the PR is about. If there isn't enough description content or the diff is too large, request an explanation. Anyone can do this part.
|
||||
|
||||
We expect that reviewers check the style and functionality of the PR, providing comments
|
||||
to the author using the GitHub review system. Reviewers should follow up with the PR until
|
||||
it is in good shape, then **approve** the PR. Approved PRs can be merged by any code owner.
|
||||
We expect that reviewers check the style and functionality of the PR, providing comments to the author using the GitHub review system. Reviewers should follow up with the PR until it is in good shape, then **approve** the PR. Approved PRs can be merged by any code owner.
|
||||
|
||||
When communicating with authors, be polite and respectful.
|
||||
|
||||
### Code Style
|
||||
|
||||
We expect `gofmt`ed code. For contributions of significant size, we expect authors to
|
||||
understand and use the guidelines in [Effective Go][effgo]. Authors should avoid common
|
||||
mistakes explained in the [Go Code Review Comments][revcomment] page.
|
||||
We expect `gofmt`ed code. For contributions of significant size, we expect authors to understand and use the guidelines in [Effective Go](https://golang.org/doc/effective_go.html). Authors should avoid common mistakes explained in the [Go Code Review Comments](https://github.com/golang/go/wiki/CodeReviewComments) page.
|
||||
|
||||
### Functional Checks
|
||||
|
||||
For PRs that fix an issue, reviewers should try reproduce the issue and verify that the
|
||||
pull request actually fixes it. Authors can help with this by including a unit test that
|
||||
fails without (and passes with) the change.
|
||||
For PRs that fix an issue, reviewers should try reproduce the issue and verify that the pull request actually fixes it. Authors can help with this by including a unit test that fails without (and passes with) the change.
|
||||
|
||||
For PRs adding new features, reviewers should attempt to use the feature and comment on
|
||||
how it feels to use it. Example: if a PR adds a new command line flag, use the program
|
||||
with the flag and comment on whether the flag feels useful.
|
||||
For PRs adding new features, reviewers should attempt to use the feature and comment on how it feels to use it. Example: if a PR adds a new command line flag, use the program with the flag and comment on whether the flag feels useful.
|
||||
|
||||
We expect appropriate unit test coverage. Reviewers should verify that new code is covered
|
||||
by unit tests.
|
||||
We expect appropriate unit test coverage. Reviewers should verify that new code is covered by unit tests.
|
||||
|
||||
### CI
|
||||
|
||||
Code submitted must pass all unit tests and static analysis ("lint") checks. We use Travis
|
||||
CI to test code on Linux, macOS and AppVeyor to test code on Microsoft Windows.
|
||||
Code submitted must pass all unit tests and static analysis ("lint") checks. We use Travis CI to test code on Linux, macOS and AppVeyor to test code on Microsoft Windows.
|
||||
|
||||
For failing CI builds, the issue may not be related to the PR itself. Such failures are
|
||||
usually related to flakey tests. These failures can be ignored (authors don't need to fix
|
||||
unrelated issues), but please file a GH issue so the test gets fixed eventually.
|
||||
For failing CI builds, the issue may not be related to the PR itself. Such failures are usually related to flakey tests. These failures can be ignored (authors don't need to fix unrelated issues), but please file a GH issue so the test gets fixed eventually.
|
||||
|
||||
### Commit Messages
|
||||
|
||||
Commit messages on the master branch should follow the rule below. PR authors are not
|
||||
required to use any particular style because the message can be modified at merge time.
|
||||
Enforcing commit message style is the responsibility of the person merging the PR.
|
||||
Commit messages on the master branch should follow the rule below. PR authors are not required to use any particular style because the message can be modified at merge time. Enforcing commit message style is the responsibility of the person merging the PR.
|
||||
|
||||
The commit message style we use is similar to the style used by the Go project:
|
||||
|
||||
The first line of the change description is conventionally a one-line summary of the
|
||||
change, prefixed by the primary affected Go package. It should complete the sentence "This
|
||||
change modifies go-ethereum to _____." The rest of the description elaborates and should
|
||||
provide context for the change and explain what it does.
|
||||
The first line of the change description is conventionally a one-line summary of the change, prefixed by the primary affected Go package. It should complete the sentence "This change modifies go-ethereum to _____." The rest of the description elaborates and should provide context for the change and explain what it does.
|
||||
|
||||
Template:
|
||||
|
||||
```text
|
||||
package/path: change XYZ
|
||||
|
||||
Longer explanation of the change in the commit. You can use
|
||||
multiple sentences here. It's usually best to include content
|
||||
from the PR description in the final commit message.
|
||||
|
||||
Longer explanation of the change in the commit. You can use multiple sentences here. It's usually best to include content from the PR description in the final commit message.
|
||||
|
||||
issue notices, e.g. "Fixes #42353".
|
||||
```
|
||||
|
||||
### Special Situations And How To Deal With Them
|
||||
|
||||
Reviewers may find themselves in one of the sitations below. Here's how to deal
|
||||
with them:
|
||||
Reviewers may find themselves in one of the sitations below. Here's how to deal with them:
|
||||
|
||||
* The author doesn't follow up: ping them after a while (i.e. after a few days). If there
|
||||
is no further response, close the PR or complete the work yourself.
|
||||
* The author doesn't follow up: ping them after a while (i.e. after a few days). If there is no further response, close the PR or complete the work yourself.
|
||||
|
||||
* Author insists on including refactoring changes alongside bug fix: We can tolerate small
|
||||
refactorings alongside any change. If you feel lost in the diff, ask the author to
|
||||
submit the refactoring as an independent PR, or at least as an independent commit in the
|
||||
same PR.
|
||||
* Author insists on including refactoring changes alongside bug fix: We can tolerate small refactorings alongside any change. If you feel lost in the diff, ask the author to submit the refactoring as an independent PR, or at least as an independent commit in the same PR.
|
||||
|
||||
* Author keeps rejecting feedback: reviewers have authority to reject any change for technical reasons.
|
||||
If you're unsure, ask the team for a second opinion. The PR can be closed if no consensus can be reached.
|
||||
|
||||
[effgo]: https://golang.org/doc/effective_go.html
|
||||
[revcomment]: https://github.com/golang/go/wiki/CodeReviewComments
|
||||
* Author keeps rejecting feedback: reviewers have authority to reject any change for technical reasons. If you're unsure, ask the team for a second opinion. The PR can be closed if no consensus can be reached.
|
||||
|
|
|
@ -1,6 +1,6 @@
|
|||
---
|
||||
title: Developer mode
|
||||
sort_key: B
|
||||
description: Instructions for setting up Geth in developer mode
|
||||
---
|
||||
|
||||
It is often convenient for developers to work in an environment where changes to client or application software can be deployed and tested rapidly and without putting real-world users or assets at risk. For this purpose, Geth has a `--dev` flag that spins up Geth in "developer mode". This creates a single-node Ethereum test network with no connections to any external peers. It exists solely on the local machine. Starting Geth in developer mode does the following:
|
||||
|
|
|
@ -1,27 +1,20 @@
|
|||
---
|
||||
title: Getting Started
|
||||
sort_key: A
|
||||
description: Entry point for developers working on Geth
|
||||
---
|
||||
|
||||
This document is the entry point for developers who wish to work on Geth.
|
||||
Developers are people who are interested to build, develop, debug, submit
|
||||
This document is the entry point for developers who wish to work on Geth. Developers are people who are interested to build, develop, debug, submit
|
||||
a bug report or pull request or otherwise contribute to the Geth source code.
|
||||
|
||||
Please see [Contributing](/content/docs/developers/contributing.md) for the
|
||||
Geth contribution guidelines.
|
||||
Please see [Contributing](/content/docs/developers/contributing.md) for the Geth contribution guidelines.
|
||||
|
||||
## Building and Testing
|
||||
|
||||
Developers should use a recent version of Go for building and testing. We use the go
|
||||
toolchain for development, which you can get from the [Go downloads page][go-install].
|
||||
|
||||
Geth is a Go module, and uses the [Go modules system][go-modules] to manage
|
||||
dependencies. Using `GOPATH` is not required to build go-ethereum.
|
||||
Developers should use a recent version of Go for building and testing. We use the go toolchain for development, which you can get from the [Go downloads page](https://golang.org/doc/install). Geth is a Go module, and uses the [Go modules system](https://github.com/golang/go/wiki/Modules) to manage dependencies. Using `GOPATH` is not required to build go-ethereum.
|
||||
|
||||
### Building Executables
|
||||
|
||||
Switch to the go-ethereum repository root directory.
|
||||
All code can be built using the go tool, placing the resulting binary in `$GOPATH/bin`.
|
||||
Switch to the go-ethereum repository root directory. All code can be built using the go tool, placing the resulting binary in `$GOPATH/bin`.
|
||||
|
||||
```text
|
||||
go install -v ./...
|
||||
|
@ -49,8 +42,7 @@ Running an individual test:
|
|||
go test -v ./eth -run TestMethod
|
||||
```
|
||||
|
||||
**Note**: here all tests with prefix _TestMethod_ will be run, so if TestMethod and
|
||||
TestMethod1 both exist then both tests will run.
|
||||
**Note**: here all tests with prefix _TestMethod_ will be run, so if TestMethod and TestMethod1 both exist then both tests will run.
|
||||
|
||||
Running benchmarks, eg.:
|
||||
|
||||
|
@ -58,19 +50,13 @@ Running benchmarks, eg.:
|
|||
go test -v -bench . -run BenchmarkJoin
|
||||
```
|
||||
|
||||
For more information, see the [go test flags][testflag] documentation.
|
||||
For more information, see the [go test flags](https://golang.org/cmd/go/#hdr-Testing_flags) documentation.
|
||||
|
||||
### Stack Traces
|
||||
|
||||
If Geth is started with the `--pprof` option, a debugging HTTP server is made available
|
||||
on port 6060. Navigating to <http://localhost:6060/debug/pprof> displays the heap,
|
||||
running routines etc. By clicking "full goroutine stack dump" a trace can be generated
|
||||
that is useful for debugging.
|
||||
If Geth is started with the `--pprof` option, a debugging HTTP server is made available on port 6060. Navigating to <http://localhost:6060/debug/pprof> displays the heap, running routines etc. By clicking "full goroutine stack dump" a trace can be generated that is useful for debugging.
|
||||
|
||||
Note that if multiple instances of Geth exist, port `6060` will only work for the first
|
||||
instance that was launched. To generate stacktraces for other instances,
|
||||
they should be started up with alternative pprof ports. Ensure `stderr` is being
|
||||
redirected to a logfile.
|
||||
Note that if multiple instances of Geth exist, port `6060` will only work for the first instance that was launched. To generate stacktraces for other instances, they should be started up with alternative pprof ports. Ensure `stderr` is being redirected to a logfile.
|
||||
|
||||
```
|
||||
geth -port=30300 -verbosity 5 --pprof --pprof.port 6060 2>> /tmp/00.glog
|
||||
|
@ -78,8 +64,7 @@ geth -port=30301 -verbosity 5 --pprof --pprof.port 6061 2>> /tmp/01.glog
|
|||
geth -port=30302 -verbosity 5 --pprof --pprof.port 6062 2>> /tmp/02.glog
|
||||
```
|
||||
|
||||
Alternatively to kill the clients (in case they hang or stalled syncing, etc)
|
||||
and have the stacktrace too, use the `-QUIT` signal with `kill`:
|
||||
Alternatively to kill the clients (in case they hang or stalled syncing, etc) and have the stacktrace too, use the `-QUIT` signal with `kill`:
|
||||
|
||||
```
|
||||
killall -QUIT geth
|
||||
|
@ -87,10 +72,8 @@ killall -QUIT geth
|
|||
|
||||
This will dump stack traces for each instance to their respective log file.
|
||||
|
||||
[install-guide]: ../install-and-build/installing-geth
|
||||
[code-review]: ../developers/code-review-guidelines
|
||||
[cross-compile]: ../install-and-build/cross-compile
|
||||
[go-modules]: https://github.com/golang/go/wiki/Modules
|
||||
[discord]: https://discord.gg/invite/nthXNEv
|
||||
[go-install]: https://golang.org/doc/install
|
||||
[testflag]: https://golang.org/cmd/go/#hdr-Testing_flags
|
||||
|
||||
## Where to go next
|
||||
|
||||
Read the remaning pages in the Geth developer section, and get building!
|
||||
|
||||
|
|
|
@ -1,27 +1,21 @@
|
|||
---
|
||||
title: DNS Discovery Setup Guide
|
||||
sort_key: C
|
||||
description: Instructions for setting up DNS discovery
|
||||
---
|
||||
|
||||
This document explains how to set up an [EIP 1459][dns-eip] node list using the devp2p
|
||||
developer tool. The focus of this guide is creating a public list for the Ethereum mainnet
|
||||
and public testnets, but it may also be helpful for setting up DNS-based discovery for a
|
||||
private network.
|
||||
This document explains how to set up an [EIP 1459](https://eips.ethereum.org/EIPS/eip-1459) node list using the devp2p developer tool. The focus of this guide is creating a public list for the Ethereum mainnet and public testnets, but it may also be helpful for setting up DNS-based discovery for a private network.
|
||||
|
||||
DNS-based node lists can serve as a fallback option when connectivity to the discovery DHT
|
||||
is unavailable. In this guide, node lists will be created by crawling the discovery DHT, then
|
||||
publishing the resulting node sets under chosen DNS names.
|
||||
DNS-based node lists can serve as a fallback option when connectivity to the discovery DHT is unavailable. In this guide, node lists will be reated by crawling the discovery DHT, then publishing the resulting node sets under chosen DNS names.
|
||||
|
||||
### Installing the devp2p command
|
||||
|
||||
`cmd/devp2p` is a developer utility and is not included in the Geth distribution. You can
|
||||
install this command using `go get`:
|
||||
`cmd/devp2p` is a developer utility and is not included in the Geth distribution. You can install this command using `go get`:
|
||||
|
||||
```shell
|
||||
go get github.com/ethereum/go-ethereum/cmd/devp2p
|
||||
```
|
||||
|
||||
To create a signing key, you might also need the `ethkey` utility.
|
||||
To create a signing key, the `ethkey` utility is needed.
|
||||
|
||||
```shell
|
||||
go get github.com/ethereum/go-ethereum/cmd/ethkey
|
||||
|
@ -29,9 +23,7 @@ go get github.com/ethereum/go-ethereum/cmd/ethkey
|
|||
|
||||
### Crawling the v4 DHT
|
||||
|
||||
Our first step is to compile a list of all reachable nodes. The DHT crawler in cmd/devp2p
|
||||
is a batch process which runs for a set amount of time. You should should schedule this command
|
||||
to run at a regular interval. To create a node list, run
|
||||
Our first step is to compile a list of all reachable nodes. The DHT crawler in cmd/devp2p is a batch process which runs for a set amount of time. You should should schedule this command to run at a regular interval. To create a node list, run
|
||||
|
||||
```shell
|
||||
devp2p discv4 crawl -timeout 30m all-nodes.json
|
||||
|
@ -73,53 +65,36 @@ The following filter flags are available:
|
|||
|
||||
### Creating DNS trees
|
||||
|
||||
To turn a node list into a DNS node tree, the list needs to be signed. To do this, you
|
||||
need a key pair. To create the key file in the correct format, you can use the cmd/ethkey
|
||||
utility. Please choose a good password to encrypt the key on disk.
|
||||
To turn a node list into a DNS node tree, the list needs to be signed. To do this, a key pair is required. To create the key file in the correct format, the cmd/ethkey utility should be used. Choose a strong password to encrypt the key on disk!
|
||||
|
||||
```shell
|
||||
ethkey generate dnskey.json
|
||||
```
|
||||
|
||||
Now use `devp2p dns sign` to update the signature of the node list. If your list's
|
||||
directory name differs from the name you want to publish it at, please specify the DNS
|
||||
name the using the `-domain` flag. This command will prompt for the key file password and
|
||||
update the tree signature.
|
||||
Now use `devp2p dns sign` to update the signature of the node list. If the list's directory name differs from the name it will be published at,specify the DNS name the using the `-domain` flag. This command will prompt for the key file password and update the tree signature.
|
||||
|
||||
```shell
|
||||
devp2p dns sign mainnet.nodes.example.org dnskey.json
|
||||
```
|
||||
|
||||
The resulting DNS tree metadata is stored in the
|
||||
`mainnet.nodes.example.org/enrtree-info.json` file.
|
||||
The resulting DNS tree metadata is stored in the `mainnet.nodes.example.org/enrtree-info.json` file.
|
||||
|
||||
### Publishing DNS trees
|
||||
|
||||
Now that the tree is signed, it can be published to a DNS provider. cmd/devp2p currently
|
||||
supports publishing to CloudFlare DNS and Amazon Route53. You can also export TXT records
|
||||
as a JSON file and publish them yourself.
|
||||
Now that the tree is signed, it can be published to a DNS provider. cmd/devp2p currently supports publishing to CloudFlare DNS and Amazon Route53.TXT records can also be exported as a JSON file and published independently.
|
||||
|
||||
To publish to CloudFlare, first create an API token in the management console. cmd/devp2p
|
||||
expects the API token in the `CLOUDFLARE_API_TOKEN` environment variable. Now use the
|
||||
following command to upload DNS TXT records via the CloudFlare API:
|
||||
To publish to CloudFlare, first create an API token in the management console. cmd/devp2p expects the API token in the `CLOUDFLARE_API_TOKEN` environment variable. Now use the following command to upload DNS TXT records via the CloudFlare API:
|
||||
|
||||
```shell
|
||||
devp2p dns to-cloudflare mainnet.nodes.example.org
|
||||
```
|
||||
|
||||
Note that this command uses the domain name specified during signing. Any existing records
|
||||
below this name will be erased by cmd/devp2p.
|
||||
Note that this command uses the domain name specified during signing. Any existing records below this name will be erased by cmd/devp2p.
|
||||
|
||||
### Using DNS trees with Geth
|
||||
|
||||
Once your tree is available through a DNS name, you can tell geth to use it with the
|
||||
`--discovery.dns` command line flag. Node trees are referenced using the `enrtree://` URL
|
||||
scheme. You can find the URL of your tree in the `enrtree-info.json` file created by
|
||||
`devp2p dns sign`. Just pass the URL as an argument to the flag in order to make use of
|
||||
the published tree.
|
||||
Once a tree is available through a DNS name, Geth can use it with the `--discovery.dns` command line flag. Node trees are referenced using the `enrtree://` URL scheme. The URL of the tree can be found in the `enrtree-info.json` file created by `devp2p dns sign`. Pass the URL as an argument to the flag in order to make use of the published tree.
|
||||
|
||||
```shell
|
||||
geth --discovery.dns "enrtree://AMBMWDM3J6UY3M32TMMROUNLX6Y3YTLVC3DC6HN2AVG5NHNSAXDW6@mainnet.nodes.example.org"
|
||||
```
|
||||
|
||||
[dns-eip]: https://eips.ethereum.org/EIPS/eip-1459
|
||||
|
|
|
@ -1,19 +1,19 @@
|
|||
---
|
||||
title: Issue Handling Workflow
|
||||
sort_key: B
|
||||
description: Instructions for managing Github issues
|
||||
---
|
||||
|
||||
### (Draft proposal)
|
||||
### Draft proposal
|
||||
|
||||
Keep the number of open issues under 820
|
||||
* Keep the number of open issues under 820
|
||||
|
||||
Keep the ratio of open issues per all issues under 13%
|
||||
* Keep the ratio of open issues per all issues under 13%
|
||||
|
||||
Have 50 issues labelled [help wanted](https://github.com/ethereum/go-ethereum/labels/help%20wanted) and 50 [good first issue](https://github.com/ethereum/go-ethereum/labels/good%20first%20issue).
|
||||
* Have 50 issues labelled [help wanted](https://github.com/ethereum/go-ethereum/labels/help%20wanted) and 50 [good first issue](https://github.com/ethereum/go-ethereum/labels/good%20first%20issue).
|
||||
|
||||
Use structured labels of the form `<category>:<label>` or if need be `<category>:<main>/<sub>`, for example `area: plugins/foobuzzer`.
|
||||
* Use structured labels of the form `<category>:<label>` or if need be `<category>:<main>/<sub>`, for example `area: plugins/foobuzzer`.
|
||||
|
||||
Use the following labels. Areas and statuses depend on the application and workflow.
|
||||
* Use the following labels. Areas and statuses depend on the application and workflow.
|
||||
- area
|
||||
- `area: android`
|
||||
- `area: clef`
|
||||
|
@ -46,12 +46,15 @@ It's ok to not set a due date for a milestone, but once you release it, close it
|
|||
Optionally, use a project board to collect issues of a larger effort that has an end state and overarches multiple releases.
|
||||
|
||||
## Workflow
|
||||
We have a weekly or bi-weekly triage meeting. Issues are preselected by [labelling them "status:triage" and sorted the oldest ones first](https://github.com/ethereum/go-ethereum/issues?q=is%3Aopen+is%3Aissue+label%3Astatus%3Atriage+sort%3Acreated-asc). This is when we go through the new issues and do one of the following
|
||||
|
||||
The Geth core team hold a weekly or bi-weekly triage meeting. Issues are preselected by [labelling them "status:triage" and sorted the oldest ones first](https://github.com/ethereum/go-ethereum/issues?q=is%3Aopen+is%3Aissue+label%3Astatus%3Atriage+sort%3Acreated-asc). This is when the team goes through the new issues and do one of the following
|
||||
|
||||
1. Close it.
|
||||
1. Assign it to "Coming soon" milestone which doesn't have an end date.
|
||||
1. Move it to the "Future" milestone.
|
||||
1. Change its status to "Need:\<what-is-needed\>".
|
||||
2. Assign it to "Coming soon" milestone which doesn't have an end date.
|
||||
3. Move it to the "Future" milestone.
|
||||
4. Change its status to "Need:\<what-is-needed\>".
|
||||
|
||||
Optional further activities:
|
||||
|
||||
* Label the issue with the appropriate area/component.
|
||||
* Add a section to the FAQ or add a wiki page. Link to it from the issue.
|
||||
|
|
|
@ -1,49 +1,31 @@
|
|||
---
|
||||
title: Vulnerability disclosure
|
||||
sort_key: A
|
||||
description: Instructions for disclosing vulnerabilities to the Geth team
|
||||
---
|
||||
|
||||
In the software world, it is expected for security vulnerabilities to be immediately
|
||||
announced, thus giving operators an opportunity to take protective measure against
|
||||
attackers.
|
||||
In the software world, it is expected for security vulnerabilities to be immediately announced, thus giving operators an opportunity to take protective measure against attackers.
|
||||
|
||||
Vulnerabilies typically take two forms:
|
||||
|
||||
1. Vulnerabilies that, if exploited, would harm the software operator. In the case of
|
||||
Geth, examples would be:
|
||||
1. Vulnerabilies that, if exploited, would harm the software operator. In the case of Geth, examples would be:
|
||||
- A bug that would allow remote reading or writing of OS files, or
|
||||
- Remote command execution, or
|
||||
- Bugs that would leak cryptographic keys
|
||||
2. Vulnerabilies that, if exploited, would harm the Ethereum mainnet. In the case of
|
||||
Geth, examples would be:
|
||||
2. Vulnerabilies that, if exploited, would harm the Ethereum mainnet. In the case of Geth, examples would be:
|
||||
- Consensus vulnerabilities, which would cause a chain split,
|
||||
- Denial-of-service during block processing, whereby a malicious transaction could cause the geth-portion of the network to crash.
|
||||
- Denial-of-service via p2p networking, whereby portions of the network could be made
|
||||
inaccessible due to crashes or resource consumption.
|
||||
|
||||
In most cases so far, vulnerabilities in Geth have been of the second type, where the
|
||||
health of the network is a concern, rather than individual node operators. For such
|
||||
issues, we reserve the right to silently patch and ship fixes in new releases.
|
||||
In most cases so far, vulnerabilities in Geth have been of the second type, where the health of the network is a concern, rather than individual node operators. For such issues, Geth reserves the right to silently patch and ship fixes in new releases.
|
||||
|
||||
### Why silent patches
|
||||
|
||||
In the case of Ethereum, it takes a lot of time (weeks, months) to get node operators to
|
||||
update even to a scheduled hard fork. If we were to highlight that a release contains
|
||||
important consensus or DoS fixes, there is always a risk of someone trying to beat node
|
||||
operators to the punch, and exploit the vulnerability. Delaying a potential attack
|
||||
sufficiently to make the majority of node operators immune may be worth the temporary loss
|
||||
of transparency.
|
||||
In the case of Ethereum, it takes a lot of time (weeks, months) to get node operators to update even to a scheduled hard fork. If we were to highlight that a release contains important consensus or DoS fixes, there is always a risk of someone trying to beat node operators to the punch, and exploit the vulnerability. Delaying a potential attack sufficiently to make the majority of node operators immune may be worth the temporary loss of transparency.
|
||||
|
||||
The primary goal for the Geth team is the health of the Ethereum network as a whole, and
|
||||
the decision whether or not to publish details about a serious vulnerability boils down to
|
||||
minimizing the risk and/or impact of discovery and exploitation.
|
||||
The primary goal for the Geth team is the health of the Ethereum network as a whole, and the decision whether or not to publish details about a serious vulnerability boils down to minimizing the risk and/or impact of discovery and exploitation.
|
||||
|
||||
At certain times, it's better to remain silent. This practice is also followed by other
|
||||
projects such as
|
||||
[Monero](https://www.getmonero.org/2017/05/17/disclosure-of-a-major-bug-in-cryptonote-based-currencies.html),
|
||||
[ZCash](https://electriccoin.co/blog/zcash-counterfeiting-vulnerability-successfully-remediated/)
|
||||
and
|
||||
[Bitcoin](https://www.coindesk.com/the-latest-bitcoin-bug-was-so-bad-developers-kept-its-full-details-a-secret).
|
||||
At certain times, it's better to remain silent. This practice is also followed by other projects such as [Monero](https://www.getmonero.org/2017/05/17/disclosure-of-a-major-bug-in-cryptonote-based-currencies.html), [ZCash](https://electriccoin.co/blog/zcash-counterfeiting-vulnerability-successfully-remediated/) and [Bitcoin](https://www.coindesk.com/the-latest-bitcoin-bug-was-so-bad-developers-kept-its-full-details-a-secret).
|
||||
|
||||
### Public transparency
|
||||
|
||||
|
@ -53,26 +35,19 @@ As of November 2020, our policy going forward is:
|
|||
- After 4-8 weeks, we will disclose that `X` contained a security-fix.
|
||||
- After an additional 4-8 weeks, we will publish the details about the vulnerability.
|
||||
|
||||
We hope that this provides sufficient balance between transparency versus the need for
|
||||
secrecy, and aids node operators and downstream projects in keeping up to date with what
|
||||
versions to run on their infrastructure.
|
||||
We hope that this provides sufficient balance between transparency versus the need for secrecy, and aids node operators and downstream projects in keeping up to date with what versions to run on their infrastructure.
|
||||
|
||||
In keeping with this policy, we have taken inspiration from [Solidity bug disclosure](https://solidity.readthedocs.io/en/develop/bugs.html) - see below.
|
||||
|
||||
## Disclosed vulnerabilities
|
||||
|
||||
On the Geth Github can find a JSON-formatted list ([`vulnerabilities.json`](vulnerabilities.json))
|
||||
of some of the known security-relevant vulnerabilities concerning Geth.
|
||||
On the Geth Github can find a JSON-formatted list ([`vulnerabilities.json`](vulnerabilities.json)) of some of the known security-relevant vulnerabilities concerning Geth.
|
||||
|
||||
As of version `1.9.25`, Geth has a built-in command to check whether it is affected by any publically disclosed vulnerability,
|
||||
using the command `geth version-check`. This command will fetch the latest json file (and the accompanying
|
||||
[signature-file](vulnerabilities.json.minisig), and cross-check the data against it's own
|
||||
version number.
|
||||
As of version `1.9.25`, Geth has a built-in command to check whether it is affected by any publically disclosed vulnerability, using the command `geth version-check`. This command will fetch the latest json file (and the accompanying [signature-file](vulnerabilities.json.minisig), and cross-check the data against it's own version number.
|
||||
|
||||
The list of vulnerabilities was started in November 2020, and covers mainly `v1.9.7` and forward.
|
||||
|
||||
The JSON file of known vulnerabilities below is a list of objects, one for each
|
||||
vulnerability, with the following keys:
|
||||
The JSON file of known vulnerabilities below is a list of objects, one for each vulnerability, with the following keys:
|
||||
|
||||
- `name`
|
||||
- Unique name given to the vulnerability.
|
||||
|
@ -101,8 +76,6 @@ vulnerability, with the following keys:
|
|||
|
||||
### What about Github security advisories
|
||||
|
||||
We prefer to not rely on Github as the only/primary publishing protocol for security
|
||||
advisories, but we plan to use the Github-advisory process as a second channel for
|
||||
disseminating vulnerability-information.
|
||||
We prefer to not rely on Github as the only/primary publishing protocol for security advisories, but we plan to use the Github-advisory process as a second channel for disseminating vulnerability-information.
|
||||
|
||||
Advisories published via Github can be accessed [here](https://github.com/ethereum/go-ethereum/security/advisories?state=published).
|
||||
|
|
Loading…
Reference in New Issue