This code of conduct applies to all projects run by the Tendermint/COSMOS team and hence to tendermint.
This code of conduct applies to all projects run by the Tendermint/COSMOS team and hence to tendermint.
@ -6,6 +7,7 @@ This code of conduct applies to all projects run by the Tendermint/COSMOS team a
# Conduct
# Conduct
## Contact: conduct@tendermint.com
## Contact: conduct@tendermint.com
* We are committed to providing a friendly, safe and welcoming environment for all, regardless of level of experience, gender, gender identity and expression, sexual orientation, disability, personal appearance, body size, race, ethnicity, age, religion, nationality, or other similar characteristic.
* We are committed to providing a friendly, safe and welcoming environment for all, regardless of level of experience, gender, gender identity and expression, sexual orientation, disability, personal appearance, body size, race, ethnicity, age, religion, nationality, or other similar characteristic.
@ -29,6 +31,7 @@ This code of conduct applies to all projects run by the Tendermint/COSMOS team a
# Moderation
# Moderation
These are the policies for upholding our community’s standards of conduct. If you feel that a thread needs moderation, please contact the above mentioned person.
These are the policies for upholding our community’s standards of conduct. If you feel that a thread needs moderation, please contact the above mentioned person.
1. Remarks that violate the Tendermint/COSMOS standards of conduct, including hateful, hurtful, oppressive, or exclusionary remarks, are not allowed. (Cursing is allowed, but never targeting another user, and never in a hateful manner.)
1. Remarks that violate the Tendermint/COSMOS standards of conduct, including hateful, hurtful, oppressive, or exclusionary remarks, are not allowed. (Cursing is allowed, but never targeting another user, and never in a hateful manner.)
@ -115,14 +115,14 @@ There are two ways to generate your proto stubs.
### Installation Instructions
### Installation Instructions
To install `protoc`, download an appropriate release (https://github.com/protocolbuffers/protobuf) and then move the provided binaries into your PATH (follow instructions in README included with the download).
To install `protoc`, download an appropriate release (<https://github.com/protocolbuffers/protobuf>) and then move the provided binaries into your PATH (follow instructions in README included with the download).
To install `gogoproto`, do the following:
To install `gogoproto`, do the following:
```
$ go get github.com/gogo/protobuf/gogoproto
$ cd $GOPATH/pkg/mod/github.com/gogo/protobuf@v1.3.1 # or wherever go get installs things
$ make install
```sh
go get github.com/gogo/protobuf/gogoproto
cd $GOPATH/pkg/mod/github.com/gogo/protobuf@v1.3.1 # or wherever go get installs things
make install
```
```
You should now be able to run `make proto-gen` from inside the root Tendermint directory to generate new files from proto files.
You should now be able to run `make proto-gen` from inside the root Tendermint directory to generate new files from proto files.
@ -135,7 +135,7 @@ hacking Tendermint with the commands below.
NOTE: In case you installed Vagrant in 2017, you might need to run
NOTE: In case you installed Vagrant in 2017, you might need to run
`vagrant box update` to upgrade to the latest `ubuntu/xenial64`.
`vagrant box update` to upgrade to the latest `ubuntu/xenial64`.
```
```sh
vagrant up
vagrant up
vagrant ssh
vagrant ssh
make test
make test
@ -218,7 +218,7 @@ If your change should be included in a minor release, please also open a PR agai
You can do this by cherry-picking your commit off master:
You can do this by cherry-picking your commit off master:
```
```sh
$ git checkout rc1/v0.33.5
$ git checkout rc1/v0.33.5
$ git checkout -b {new branch name}
$ git checkout -b {new branch name}
$ git cherry-pick {commit SHA from master}
$ git cherry-pick {commit SHA from master}
@ -232,7 +232,7 @@ After this, you can open a PR. Please note in the PR body if there were merge co
We follow the [Go style guide on commit messages](https://tip.golang.org/doc/contribute.html#commit_messages). Write concise commits that start with the package name and have a description that finishes the sentence "This change modifies Tendermint to...". For example,
We follow the [Go style guide on commit messages](https://tip.golang.org/doc/contribute.html#commit_messages). Write concise commits that start with the package name and have a description that finishes the sentence "This change modifies Tendermint to...". For example,
```
```sh
cmd/debug: execute p.Signal only when p is not nil
cmd/debug: execute p.Signal only when p is not nil
@ -8,12 +8,12 @@ Official releases can be found [here](https://github.com/tendermint/tendermint/r
The Dockerfile for tendermint is not expected to change in the near future. The master file used for all builds can be found [here](https://raw.githubusercontent.com/tendermint/tendermint/master/DOCKER/Dockerfile).
The Dockerfile for tendermint is not expected to change in the near future. The master file used for all builds can be found [here](https://raw.githubusercontent.com/tendermint/tendermint/master/DOCKER/Dockerfile).
Respective versioned files can be found https://raw.githubusercontent.com/tendermint/tendermint/vX.XX.XX/DOCKER/Dockerfile (replace the Xs with the version number).
Respective versioned files can be found <https://raw.githubusercontent.com/tendermint/tendermint/vX.XX.XX/DOCKER/Dockerfile> (replace the Xs with the version number).
## Quick reference
## Quick reference
- **Where to get help:** https://tendermint.com/
- **Where to file issues:** https://github.com/tendermint/tendermint/issues
- **Where to get help:**<https://tendermint.com/>
- **Where to file issues:**<https://github.com/tendermint/tendermint/issues>
- **Supported Docker versions:** [the latest release](https://github.com/moby/moby/releases) (down to 1.6 on a best-effort basis)
- **Supported Docker versions:** [the latest release](https://github.com/moby/moby/releases) (down to 1.6 on a best-effort basis)
As part of our [Coordinated Vulnerability Disclosure
As part of our [Coordinated Vulnerability Disclosure
Policy](https://tendermint.com/security), we operate a [bug
Policy](https://tendermint.com/security), we operate a [bug
bounty](https://hackerone.com/tendermint).
bounty](https://hackerone.com/tendermint).
@ -21,6 +22,7 @@ If you follow these guidelines when reporting an issue to us, we commit to:
* Work with you to understand, resolve and ultimately disclose the issue in a timely fashion
* Work with you to understand, resolve and ultimately disclose the issue in a timely fashion
## Disclosure Process
## Disclosure Process
Tendermint Core uses the following disclosure process:
Tendermint Core uses the following disclosure process:
1. Once a security report is received, the Tendermint Core team works to verify the issue and confirm its severity level using CVSS.
1. Once a security report is received, the Tendermint Core team works to verify the issue and confirm its severity level using CVSS.
@ -37,6 +39,7 @@ Tendermint Core uses the following disclosure process:
This process can take some time. Every effort will be made to handle the bug in as timely a manner as possible, however it's important that we follow the process described above to ensure that disclosures are handled consistently and to keep Tendermint Core and its downstream dependent projects--including but not limited to Gaia and the Cosmos Hub--as secure as possible.
This process can take some time. Every effort will be made to handle the bug in as timely a manner as possible, however it's important that we follow the process described above to ensure that disclosures are handled consistently and to keep Tendermint Core and its downstream dependent projects--including but not limited to Gaia and the Cosmos Hub--as secure as possible.
### Example Timeline
### Example Timeline
The following is an example timeline for the triage and response. The required roles and team members are described in parentheses after each task; however, multiple people can play each role and each person may play multiple roles.
The following is an example timeline for the triage and response. The required roles and team members are described in parentheses after each task; however, multiple people can play each role and each person may play multiple roles.
#### > 24 Hours Before Release Time
#### > 24 Hours Before Release Time
@ -54,6 +57,7 @@ The following is an example timeline for the triage and response. The required r
4. Send emails to validators or other users (PARTNERSHIPS LEAD)
4. Send emails to validators or other users (PARTNERSHIPS LEAD)
2. Cut Cosmos SDK release for eligible versions (COSMOS ENG)
2. Cut Cosmos SDK release for eligible versions (COSMOS ENG)
3. Cut Gaia release for eligible versions (GAIA ENG)
3. Cut Gaia release for eligible versions (GAIA ENG)
@ -64,19 +68,23 @@ The following is an example timeline for the triage and response. The required r
8. Publish Security Advisory and CVE, if CVE has no sensitive information (ADMIN)
8. Publish Security Advisory and CVE, if CVE has no sensitive information (ADMIN)
#### After Release Time
#### After Release Time
1. Write forum post with exploit details (TENDERMINT LEAD)
1. Write forum post with exploit details (TENDERMINT LEAD)
2. Approve pay-out on HackerOne for submitter (ADMIN)
2. Approve pay-out on HackerOne for submitter (ADMIN)
#### 7 Days After Release Time
#### 7 Days After Release Time
1. Publish CVE if it has not yet been published (ADMIN)
1. Publish CVE if it has not yet been published (ADMIN)
2. Publish forum post with exploit details (TENDERMINT ENG, TENDERMINT LEAD)
2. Publish forum post with exploit details (TENDERMINT ENG, TENDERMINT LEAD)
## Supported Releases
## Supported Releases
The Tendermint Core team commits to releasing security patch releases for both the latest minor release as well for the major/minor release that the Cosmos Hub is running.
The Tendermint Core team commits to releasing security patch releases for both the latest minor release as well for the major/minor release that the Cosmos Hub is running.
If you are running older versions of Tendermint Core, we encourage you to upgrade at your earliest opportunity so that you can receive security patches directly from the Tendermint repo. While you are welcome to backport security patches to older versions for your own use, we will not publish or promote these backports.
If you are running older versions of Tendermint Core, we encourage you to upgrade at your earliest opportunity so that you can receive security patches directly from the Tendermint repo. While you are welcome to backport security patches to older versions for your own use, we will not publish or promote these backports.
## Scope
## Scope
The full scope of our bug bounty program is outlined on our [Hacker One program page](https://hackerone.com/tendermint). Please also note that, in the interest of the safety of our users and staff, a few things are explicitly excluded from scope:
The full scope of our bug bounty program is outlined on our [Hacker One program page](https://hackerone.com/tendermint). Please also note that, in the interest of the safety of our users and staff, a few things are explicitly excluded from scope:
* Any third-party services
* Any third-party services
@ -84,6 +92,7 @@ The full scope of our bug bounty program is outlined on our [Hacker One program
* Findings derived from social engineering (e.g., phishing)
* Findings derived from social engineering (e.g., phishing)
## Example Vulnerabilities
## Example Vulnerabilities
The following is a list of examples of the kinds of vulnerabilities that we’re most interested in. It is not exhaustive: there are other kinds of issues we may also be interested in!
The following is a list of examples of the kinds of vulnerabilities that we’re most interested in. It is not exhaustive: there are other kinds of issues we may also be interested in!
### Specification
### Specification
@ -143,6 +152,3 @@ Attacks may come through the P2P network or the RPC layer:
validator and ABCI ( [#4698](https://github.com/tendermint/tendermint/issues/4698) ).
### Blockchain Protocol
### Blockchain Protocol
@ -77,7 +75,7 @@ With this release we are happy to announce the full protobuf migration of the Te
- All proto files have been moved under one directory, `/proto`. This is in line with the recommended file layout by [buf](https://buf.build), you can read more about it [here](https://buf.build/docs/lint-checkers#file_layout)
- All proto files have been moved under one directory, `/proto`. This is in line with the recommended file layout by [buf](https://buf.build), you can read more about it [here](https://buf.build/docs/lint-checkers#file_layout)
- We use the generated protobuf types for only on disk and over the wire serialization. This means that these changes should not effect you as user of Tendermint.
- We use the generated protobuf types for only on disk and over the wire serialization. This means that these changes should not effect you as user of Tendermint.
- A few notable changes in the abci:
- A few notable changes in the abci:
- In `ValidatorUpdates` the public key type has been migrated to a protobuf `oneof` type. Since Tendermint only supports ed25519 validator keys this is the only available key in the oneof.
- In `ValidatorUpdates` the public key type has been migrated to a protobuf `oneof` type. Since Tendermint only supports ed25519 validator keys this is the only available key in the oneof.
See the [consensus spec](https://github.com/tendermint/spec/tree/master/spec/consensus) and the [reactor consensus spec](https://github.com/tendermint/spec/tree/master/spec/reactors/consensus) for more information.
See the [consensus spec](https://github.com/tendermint/spec/tree/master/spec/consensus) and the [reactor consensus spec](https://github.com/tendermint/spec/tree/master/spec/reactors/consensus) for more information.
Over the next few weeks, @brapse, @marbar3778 and I (@tessr) are having a series of meetings to go over the architecture of Tendermint Core. These are my notes from these meetings, which will either serve as an artifact for onboarding future engineers; or will provide the basis for such a document.
Over the next few weeks, @brapse, @marbar3778 and I (@tessr) are having a series of meetings to go over the architecture of Tendermint Core. These are my notes from these meetings, which will either serve as an artifact for onboarding future engineers; or will provide the basis for such a document.
## Communication
## Communication
There are three forms of communication (e.g., requests, responses, connections) that can happen in Tendermint Core: *internode communication*, *intranode communication*, and *client communication*.
There are three forms of communication (e.g., requests, responses, connections) that can happen in Tendermint Core: *internode communication*, *intranode communication*, and *client communication*.
- Internode communication: Happens between a node and other peers. This kind of communication happens over TCP or HTTP. More on this below.
- Internode communication: Happens between a node and other peers. This kind of communication happens over TCP or HTTP. More on this below.
- Intranode communication: Happens within the node itself (i.e., between reactors or other components). These are typically function or method calls, or occasionally happen through an event bus.
- Intranode communication: Happens within the node itself (i.e., between reactors or other components). These are typically function or method calls, or occasionally happen through an event bus.
- Client communiation: Happens between a client (like a wallet or a browser) and a node on the network.
- Client communiation: Happens between a client (like a wallet or a browser) and a node on the network.
@ -13,6 +15,7 @@ There are three forms of communication (e.g., requests, responses, connections)
### Internode Communication
### Internode Communication
Internode communication can happen in two ways:
Internode communication can happen in two ways:
1. TCP connections through the p2p package
1. TCP connections through the p2p package
- Most common form of internode communication
- Most common form of internode communication
- Connections between nodes are persisted and shared across reactors, facilitated by the switch. (More on the switch below.)
- Connections between nodes are persisted and shared across reactors, facilitated by the switch. (More on the switch below.)
@ -24,10 +27,12 @@ Internode communication can happen in two ways:
### P2P Business (the Switch, the PEX, and the Address Book)
### P2P Business (the Switch, the PEX, and the Address Book)
When writing a p2p service, there are two primary responsibilities:
When writing a p2p service, there are two primary responsibilities:
1. Routing: Who gets which messages?
1. Routing: Who gets which messages?
2. Peer management: Who can you talk to? What is their state? And how can you do peer discovery?
2. Peer management: Who can you talk to? What is their state? And how can you do peer discovery?
The first responsibility is handled by the Switch:
The first responsibility is handled by the Switch:
- Responsible for routing connections between peers
- Responsible for routing connections between peers
- Notably _only handles TCP connections_; RPC/HTTP is separate
- Notably _only handles TCP connections_; RPC/HTTP is separate
- Is a dependency for every reactor; all reactors expose a function `setSwitch`
- Is a dependency for every reactor; all reactors expose a function `setSwitch`
@ -42,12 +47,14 @@ The second responsibility is handled by a combination of the PEX and the Address
TODO: What is the PEX and the Address Book?
TODO: What is the PEX and the Address Book?
#### The Nature of TCP, and Introduction to the `mconnection`
#### The Nature of TCP, and Introduction to the `mconnection`
Here are some relevant facts about TCP:
Here are some relevant facts about TCP:
1. All TCP connections have a "frame window size" which represents the packet size to the "confidence;" i.e., if you are sending packets along a new connection, you must start out with small packets. As the packets are received successfully, you can start to send larger and larger packets. (This curve is illustrated below.) This means that TCP connections are slow to spin up.
1. All TCP connections have a "frame window size" which represents the packet size to the "confidence;" i.e., if you are sending packets along a new connection, you must start out with small packets. As the packets are received successfully, you can start to send larger and larger packets. (This curve is illustrated below.) This means that TCP connections are slow to spin up.
3. The syn/ack process also means that there's a high overhead for small, frequent messages
4. Sockets are represented by file descriptors.
2. The syn/ack process also means that there's a high overhead for small, frequent messages
3. Sockets are represented by file descriptors.
In order to have performant TCP connections under the conditions created in Tendermint, we've created the `mconnection`, or the multiplexing connection. It is our own protocol built on top of TCP. It lets us reuse TCP connections to minimize overhead, and it keeps the window size high by sending auxiliary messages when necessary.
In order to have performant TCP connections under the conditions created in Tendermint, we've created the `mconnection`, or the multiplexing connection. It is our own protocol built on top of TCP. It lets us reuse TCP connections to minimize overhead, and it keeps the window size high by sending auxiliary messages when necessary.
@ -57,22 +64,25 @@ The `mconnection` has two methods: `send`, which takes a raw handle to the socke
The `mconnection` is owned by a peer, which is owned (potentially with many other peers) by a (global) transport, which is owned by the (global) switch:
The `mconnection` is owned by a peer, which is owned (potentially with many other peers) by a (global) transport, which is owned by the (global) switch:
<!-- markdownlint-disable -->
```
```
switch
switch
transport
peer
mconnection
peer
mconnection
peer
mconnection
transport
peer
mconnection
peer
mconnection
peer
mconnection
```
```
<!-- markdownlint-restore -->
## node.go
## node.go
node.go is the entrypoint for running a node. It sets up reactors, sets up the switch, and registers all the RPC endpoints for a node.
node.go is the entrypoint for running a node. It sets up reactors, sets up the switch, and registers all the RPC endpoints for a node.
## Types of Nodes
## Types of Nodes
1. Validator Node:
1. Validator Node:
2. Full Node:
2. Full Node:
3. Seed Node:
3. Seed Node:
@ -82,6 +92,7 @@ TODO: Flesh out the differences between the types of nodes and how they're confi
## Reactors
## Reactors
Here are some Reactor Facts:
Here are some Reactor Facts:
- Every reactor holds a pointer to the global switch (set through `SetSwitch()`)
- Every reactor holds a pointer to the global switch (set through `SetSwitch()`)
- The switch holds a pointer to every reactor (`addReactor()`)
- The switch holds a pointer to every reactor (`addReactor()`)
- Every reactor gets set up in node.go (and if you are using custom reactors, this is where you specify that)
- Every reactor gets set up in node.go (and if you are using custom reactors, this is where you specify that)
@ -90,6 +101,7 @@ Here are some Reactor Facts:
- Sometimes reactors talk to each other by fetching references to one another via the switch (which maintains a pointer to each reactor). **Question: Can reactors talk to each other in any other way?**
- Sometimes reactors talk to each other by fetching references to one another via the switch (which maintains a pointer to each reactor). **Question: Can reactors talk to each other in any other way?**
Furthermore, all reactors expose:
Furthermore, all reactors expose:
1. A TCP channel
1. A TCP channel
2. A `receive` method
2. A `receive` method
3. An `addReactor` call
3. An `addReactor` call
@ -99,6 +111,7 @@ The `receive` method can be called many times by the mconnection. It has the sam
The `addReactor` call does a for loop over all the channels on the reactor and creates a map of channel IDs->reactors. The switch holds onto this map, and passes it to the _transport_, a thin wrapper around TCP connections.
The `addReactor` call does a for loop over all the channels on the reactor and creates a map of channel IDs->reactors. The switch holds onto this map, and passes it to the _transport_, a thin wrapper around TCP connections.
The following is an exhaustive (?) list of reactors:
The following is an exhaustive (?) list of reactors:
- Blockchain Reactor
- Blockchain Reactor
- Consensus Reactor
- Consensus Reactor
- Evidence Reactor
- Evidence Reactor
@ -108,6 +121,8 @@ The following is an exhaustive (?) list of reactors:
Each of these will be discussed in more detail later.
Each of these will be discussed in more detail later.
### Blockchain Reactor
### Blockchain Reactor
The blockchain reactor has two responsibilities:
The blockchain reactor has two responsibilities:
1. Serve blocks at the request of peers
1. Serve blocks at the request of peers
2. TODO: learn about the second responsibility of the blockchain reactor
2. TODO: learn about the second responsibility of the blockchain reactor
@ -97,7 +97,7 @@ Currently Tendermint uses [Ed25519](https://ed25519.cr.yp.to/) keys which are wi
## Committing a Block
## Committing a Block
_+2/3 is short for "more than 2/3"_
> **+2/3 is short for "more than 2/3"**
A block is committed when +2/3 of the validator set sign [precommit
A block is committed when +2/3 of the validator set sign [precommit
votes](https://github.com/tendermint/spec/blob/953523c3cb99fdb8c8f7a2d21e3a99094279e9de/spec/blockchain/blockchain.md#vote) for that block at the same `round`.
votes](https://github.com/tendermint/spec/blob/953523c3cb99fdb8c8f7a2d21e3a99094279e9de/spec/blockchain/blockchain.md#vote) for that block at the same `round`.
Marko
4 years ago
GitHub