2018-03-27 15:16:27 -07:00
[![Solana crate ](https://img.shields.io/crates/v/solana.svg )](https://crates.io/crates/solana)
[![Solana documentation ](https://docs.rs/solana/badge.svg )](https://docs.rs/solana)
2018-06-10 21:55:18 -07:00
[![Build status ](https://badge.buildkite.com/d4c4d7da9154e3a8fb7199325f430ccdb05be5fc1e92777e51.svg?branch=master )](https://solana-ci-gate.herokuapp.com/buildkite_public_log?https://buildkite.com/solana-labs/solana/builds/latest/master)
2018-03-27 15:16:27 -07:00
[![codecov ](https://codecov.io/gh/solana-labs/solana/branch/master/graph/badge.svg )](https://codecov.io/gh/solana-labs/solana)
2018-02-14 14:25:49 -08:00
2018-06-06 07:57:26 -07:00
Blockchain, Rebuilt for Scale
2018-03-01 08:16:39 -08:00
===
2018-02-15 12:59:33 -08:00
2018-06-06 07:57:26 -07:00
Solana™ is a new blockchain architecture built from the ground up for scale. The architecture supports
up to 710 thousand transactions per second on a gigabit network.
2018-03-01 08:16:39 -08:00
2018-06-06 07:57:26 -07:00
Disclaimer
2018-03-01 08:16:39 -08:00
===
2018-06-06 07:57:26 -07:00
All claims, content, designs, algorithms, estimates, roadmaps, specifications, and performance measurements described in this project are done with the author's best effort. It is up to the reader to check and validate their accuracy and truthfulness. Furthermore nothing in this project constitutes a solicitation for investment.
2018-02-15 15:09:11 -08:00
2018-04-18 20:17:37 -07:00
Introduction
===
2018-09-06 19:39:37 -07:00
It's possible for a centralized database to process 710,000 transactions per second on a standard gigabit network if the transactions are, on average, no more than 176 bytes. A centralized database can also replicate itself and maintain high availability without significantly compromising that transaction rate using the distributed system technique known as Optimistic Concurrency Control [\[H.T.Kung, J.T.Robinson (1981)\]](http://citeseerx.ist.psu.edu/viewdoc/summary?doi=10.1.1.65.4735). At Solana, we're demonstrating that these same theoretical limits apply just as well to blockchain on an adversarial network. The key ingredient? Finding a way to share time when nodes can't trust one-another. Once nodes can trust time, suddenly ~40 years of distributed systems research becomes applicable to blockchain!
2018-09-06 15:13:58 -07:00
2018-09-06 19:39:37 -07:00
> Perhaps the most striking difference between algorithms obtained by our method and ones based upon timeout is that using timeout produces a traditional distributed algorithm in which the processes operate asynchronously, while our method produces a globally synchronous one in which every process does the same thing at (approximately) the same time. Our method seems to contradict the whole purpose of distributed processing, which is to permit different processes to operate independently and perform different functions. However, if a distributed system is really a single system, then the processes must be synchronized in some way. Conceptually, the easiest way to synchronize processes is to get them all to do the same thing at the same time. Therefore, our method is used to implement a kernel that performs the necessary synchronization--for example, making sure that two different processes do not try to modify a file at the same time. Processes might spend only a small fraction of their time executing the synchronizing kernel; the rest of the time, they can operate independently--e.g., accessing different files. This is an approach we have advocated even when fault-tolerance is not required. The method's basic simplicity makes it easier to understand the precise properties of a system, which is crucial if one is to know just how fault-tolerant the system is. [\[L.Lamport (1984)\]](http://citeseerx.ist.psu.edu/viewdoc/summary?doi=10.1.1.71.1078)
2018-09-06 15:13:58 -07:00
2018-10-16 22:02:08 -07:00
Furthermore, and much to our surprise, it can be implemented using a mechanism that has existed in Bitcoin since day one. The Bitcoin feature is called nLocktime and it can be used to postdate transactions using block height instead of a timestamp. As a Bitcoin client, you'd use block height instead of a timestamp if you don't trust the network. Block height turns out to be an instance of what's being called a Verifiable Delay Function in cryptography circles. It's a cryptographically secure way to say time has passed. In Solana, we use a far more granular verifiable delay function, a SHA 256 hash chain, to checkpoint the ledger and coordinate consensus. With it, we implement Optimistic Concurrency Control and are now well en route towards that theoretical limit of 710,000 transactions per second.
2018-04-18 20:17:37 -07:00
2018-06-01 09:40:06 -07:00
Testnet Demos
2018-03-01 08:16:39 -08:00
===
2018-02-19 08:19:26 -08:00
2018-06-01 09:40:06 -07:00
The Solana repo contains all the scripts you might need to spin up your own
local testnet. Depending on what you're looking to achieve, you may want to
run a different variation, as the full-fledged, performance-enhanced
multinode testnet is considerably more complex to set up than a Rust-only,
singlenode testnode. If you are looking to develop high-level features, such
as experimenting with smart contracts, save yourself some setup headaches and
stick to the Rust-only singlenode demo. If you're doing performance optimization
of the transaction pipeline, consider the enhanced singlenode demo. If you're
doing consensus work, you'll need at least a Rust-only multinode demo. If you want
to reproduce our TPS metrics, run the enhanced multinode demo.
For all four variations, you'd need the latest Rust toolchain and the Solana
source code:
2018-03-08 10:40:42 -08:00
First, install Rust's package manager Cargo.
2018-03-05 15:05:16 -08:00
```bash
2018-03-08 10:40:42 -08:00
$ curl https://sh.rustup.rs -sSf | sh
$ source $HOME/.cargo/env
```
2018-04-20 14:02:10 -07:00
Now checkout the code from github:
```bash
2018-07-13 16:22:02 -07:00
$ git clone https://github.com/solana-labs/solana.git
2018-04-20 14:02:10 -07:00
$ cd solana
```
2018-06-01 09:40:06 -07:00
The demo code is sometimes broken between releases as we add new low-level
features, so if this is your first time running the demo, you'll improve
your odds of success if you check out the
[latest release ](https://github.com/solana-labs/solana/releases )
before proceeding:
```bash
2018-11-05 07:05:03 -08:00
$ git checkout v0.10.0
2018-06-01 09:40:06 -07:00
```
2018-06-20 14:30:32 -07:00
Configuration Setup
2018-06-01 09:40:06 -07:00
---
2018-06-20 14:30:32 -07:00
The network is initialized with a genesis ledger and leader/validator configuration files.
These files can be generated by running the following script.
2018-02-19 11:00:56 -08:00
2018-03-05 15:05:16 -08:00
```bash
2018-06-20 14:30:32 -07:00
$ ./multinode-demo/setup.sh
2018-02-19 11:00:56 -08:00
```
2018-07-31 22:07:53 -07:00
Drone
2018-06-20 14:30:32 -07:00
---
2018-07-31 22:07:53 -07:00
In order for the leader, client and validators to work, we'll need to
spin up a drone to give out some test tokens. The drone delivers Milton
Friedman-style "air drops" (free tokens to requesting clients) to be used in
test transactions.
2018-05-31 14:45:03 -07:00
2018-07-31 22:07:53 -07:00
Start the drone on the leader node with:
2018-03-05 15:05:16 -08:00
```bash
2018-07-31 22:07:53 -07:00
$ ./multinode-demo/drone.sh
2018-03-05 15:05:16 -08:00
```
2018-07-31 22:07:53 -07:00
Singlenode Testnet
2018-07-13 16:22:02 -07:00
---
2018-07-31 22:07:53 -07:00
Before you start a fullnode, make sure you know the IP address of the machine you
want to be the leader for the demo, and make sure that udp ports 8000-10000 are
open on all the machines you want to test with.
2018-07-13 16:22:02 -07:00
2018-09-04 20:41:11 -07:00
Now start the server in a separate shell:
2018-07-13 16:22:02 -07:00
2018-06-01 12:23:11 -07:00
```bash
2018-07-31 22:07:53 -07:00
$ ./multinode-demo/leader.sh
2018-06-01 12:23:11 -07:00
```
2018-09-04 20:41:11 -07:00
Wait a few seconds for the server to initialize. It will print "leader ready..." when it's ready to
2018-07-31 22:07:53 -07:00
receive transactions. The leader will request some tokens from the drone if it doesn't have any.
The drone does not need to be running for subsequent leader starts.
2018-04-26 12:17:36 -07:00
2018-06-01 09:40:06 -07:00
Multinode Testnet
---
2018-09-04 20:41:11 -07:00
To run a multinode testnet, after starting a leader node, spin up some validator nodes in
separate shells:
2018-02-20 12:07:54 -08:00
2018-03-05 15:05:16 -08:00
```bash
2018-09-13 17:58:33 -07:00
$ ./multinode-demo/validator.sh
2018-03-05 15:05:16 -08:00
```
2018-07-13 16:22:02 -07:00
To run a performance-enhanced leader or validator (on Linux),
2018-06-24 10:10:55 -07:00
[CUDA 9.2 ](https://developer.nvidia.com/cuda-downloads ) must be installed on
your system:
2018-09-04 20:41:11 -07:00
2018-06-01 12:23:11 -07:00
```bash
2018-06-24 10:10:55 -07:00
$ ./fetch-perf-libs.sh
2018-07-13 16:22:02 -07:00
$ SOLANA_CUDA=1 ./multinode-demo/leader.sh
2018-09-13 17:58:33 -07:00
$ SOLANA_CUDA=1 ./multinode-demo/validator.sh
2018-06-01 12:23:11 -07:00
```
2018-06-01 09:40:06 -07:00
Testnet Client Demo
---
2018-03-05 15:05:16 -08:00
2018-09-13 17:58:33 -07:00
Now that your singlenode or multinode testnet is up and running let's send it
some transactions!
2018-09-04 20:41:11 -07:00
In a separate shell start the client:
2018-03-05 15:05:16 -08:00
```bash
2018-09-13 17:58:33 -07:00
$ ./multinode-demo/client.sh # runs against localhost by default
2018-02-20 12:07:54 -08:00
```
2018-06-01 09:40:06 -07:00
What just happened? The client demo spins up several threads to send 500,000 transactions
to the testnet as quickly as it can. The client then pings the testnet periodically to see
how many transactions it processed in that time. Take note that the demo intentionally
floods the network with UDP packets, such that the network will almost certainly drop a
bunch of them. This ensures the testnet has an opportunity to reach 710k TPS. The client
demo completes after it has convinced itself the testnet won't process any additional
transactions. You should see several TPS measurements printed to the screen. In the
multinode variation, you'll see TPS measurements for each validator node as well.
2018-02-19 11:00:56 -08:00
2018-08-19 07:11:22 -07:00
Public Testnet
2018-08-17 15:12:28 -07:00
--------------
2018-08-22 01:34:43 -07:00
In this example the client connects to our public testnet. To run validators on the testnet you would need to open udp ports `8000-10000` .
2018-09-04 20:41:11 -07:00
2018-08-17 15:12:28 -07:00
```bash
2018-09-13 17:58:33 -07:00
$ ./multinode-demo/client.sh --network $(dig +short testnet.solana.com):8001 --identity config-private/client-id.json --duration 60
2018-08-17 15:12:28 -07:00
```
2018-09-04 20:41:11 -07:00
2018-08-19 07:11:22 -07:00
You can observe the effects of your client's transactions on our [dashboard ](https://metrics.solana.com:3000/d/testnet/testnet-hud?orgId=2&from=now-30m&to=now&refresh=5s&var-testnet=testnet )
2018-08-17 15:12:28 -07:00
2018-06-19 13:09:09 -07:00
Linux Snap
---
2018-06-23 15:29:22 -07:00
A Linux [Snap ](https://snapcraft.io/ ) is available, which can be used to
2018-06-19 13:09:09 -07:00
easily get Solana running on supported Linux systems without building anything
from source. The `edge` Snap channel is updated daily with the latest
development from the `master` branch. To install:
2018-09-04 20:41:11 -07:00
2018-06-19 13:09:09 -07:00
```bash
$ sudo snap install solana --edge --devmode
```
2018-09-04 20:41:11 -07:00
2018-06-19 13:09:09 -07:00
(`--devmode` flag is required only for `solana.fullnode-cuda` )
Once installed the usual Solana programs will be available as `solona.*` instead
of `solana-*` . For example, `solana.fullnode` instead of `solana-fullnode` .
2018-08-09 16:10:53 -07:00
Update to the latest version at any time with:
2018-09-04 20:41:11 -07:00
2018-06-23 15:29:22 -07:00
```bash
$ snap info solana
$ sudo snap refresh solana --devmode
```
2018-06-24 10:10:55 -07:00
### Daemon support
The snap supports running a leader, validator or leader+drone node as a system
daemon.
2018-07-31 13:06:01 -07:00
Run `sudo snap get solana` to view the current daemon configuration. To view
daemon logs:
1. Run `sudo snap logs -n=all solana` to view the daemon initialization log
2. Runtime logging can be found under `/var/snap/solana/current/leader/` ,
`/var/snap/solana/current/validator/` , or `/var/snap/solana/current/drone/` depending
on which `mode=` was selected. Within each log directory the file `current`
contains the latest log, and the files `*.s` (if present) contain older rotated
logs.
2018-06-24 10:10:55 -07:00
Disable the daemon at any time by running:
2018-09-04 20:41:11 -07:00
2018-06-24 10:10:55 -07:00
```bash
$ sudo snap set solana mode=
```
Runtime configuration files for the daemon can be found in
`/var/snap/solana/current/config` .
#### Leader daemon
2018-09-04 20:41:11 -07:00
2018-06-24 10:10:55 -07:00
```bash
2018-06-29 16:49:23 -07:00
$ sudo snap set solana mode=leader
2018-06-24 10:10:55 -07:00
```
If CUDA is available:
2018-09-04 20:41:11 -07:00
2018-06-24 10:10:55 -07:00
```bash
$ sudo snap set solana mode=leader enable-cuda=1
```
`rsync` must be configured and running on the leader.
1. Ensure rsync is installed with `sudo apt-get -y install rsync`
2. Edit `/etc/rsyncd.conf` to include the following
```
[config]
path = /var/snap/solana/current/config
hosts allow = *
read only = true
```
3. Run `sudo systemctl enable rsync; sudo systemctl start rsync`
4. Test by running `rsync -Pzravv rsync://< ip-address-of-leader > /config
2018-06-28 16:08:59 -07:00
solana-config` from another machine. **If the leader is running on a cloud
2018-06-24 10:10:55 -07:00
provider it may be necessary to configure the Firewall rules to permit ingress
2018-06-28 16:08:59 -07:00
to port tcp:873, tcp:9900 and the port range udp:8000-udp:10000**
2018-06-24 10:10:55 -07:00
To run both the Leader and Drone:
2018-09-04 20:41:11 -07:00
2018-06-24 10:10:55 -07:00
```bash
2018-06-29 16:49:23 -07:00
$ sudo snap set solana mode=leader+drone
2018-06-28 16:08:59 -07:00
2018-06-24 10:10:55 -07:00
```
#### Validator daemon
2018-09-04 20:41:11 -07:00
2018-06-24 10:10:55 -07:00
```bash
2018-06-29 16:49:23 -07:00
$ sudo snap set solana mode=validator
2018-06-28 16:08:59 -07:00
2018-06-24 10:10:55 -07:00
```
If CUDA is available:
2018-09-04 20:41:11 -07:00
2018-06-24 10:10:55 -07:00
```bash
2018-06-29 16:49:23 -07:00
$ sudo snap set solana mode=validator enable-cuda=1
2018-06-24 10:10:55 -07:00
```
By default the validator will connect to **testnet.solana.com** , override
the leader IP address by running:
2018-09-04 20:41:11 -07:00
2018-06-24 10:10:55 -07:00
```bash
$ sudo snap set solana mode=validator leader-address=127.0.0.1 #< -- change IP address
```
2018-09-04 20:41:11 -07:00
2018-06-24 10:10:55 -07:00
It's assumed that the leader will be running `rsync` configured as described in
the previous **Leader daemon** section.
2018-03-01 08:16:39 -08:00
Developing
===
2018-02-15 15:09:11 -08:00
2018-02-16 09:38:12 -08:00
Building
---
Install rustc, cargo and rustfmt:
2018-02-15 15:09:11 -08:00
```bash
$ curl https://sh.rustup.rs -sSf | sh
2018-02-16 09:38:12 -08:00
$ source $HOME/.cargo/env
$ rustup component add rustfmt-preview
2018-02-15 15:09:11 -08:00
```
2018-05-30 19:49:55 -07:00
If your rustc version is lower than 1.26.1, please update it:
2018-05-02 16:38:09 -07:00
```bash
$ rustup update
```
2018-08-22 01:34:43 -07:00
On Linux systems you may need to install libssl-dev, pkg-config, zlib1g-dev, etc. On Ubuntu:
2018-09-04 20:41:11 -07:00
2018-07-02 10:22:37 -07:00
```bash
2018-08-22 01:34:43 -07:00
$ sudo apt-get install libssl-dev pkg-config zlib1g-dev
2018-07-02 10:22:37 -07:00
```
2018-02-15 15:09:11 -08:00
Download the source code:
```bash
2018-03-27 15:16:27 -07:00
$ git clone https://github.com/solana-labs/solana.git
$ cd solana
2018-02-15 15:09:11 -08:00
```
2018-11-07 08:11:05 -08:00
Building the Solana book
---
Install mdbook:
```bash
cargo install mdbook
```
Run any Rust tests in the markdown:
```bash
mdbook test
```
Render markdown as HTML:
```bash
mdbook build
```
Render and view the book:
```bash
mdbook build --open
```
2018-02-16 09:38:12 -08:00
Testing
---
2018-02-15 15:09:11 -08:00
Run the test suite:
```bash
2018-05-26 19:23:18 -07:00
$ cargo test
2018-02-15 15:09:11 -08:00
```
2018-02-16 09:38:12 -08:00
2018-05-28 16:46:47 -07:00
To emulate all the tests that will run on a Pull Request, run:
2018-09-04 20:41:11 -07:00
2018-05-28 16:46:47 -07:00
```bash
$ ./ci/run-local.sh
```
2018-11-06 07:06:36 -08:00
Fullnode Debugging
2018-05-08 13:25:59 -07:00
---
There are some useful debug messages in the code, you can enable them on a per-module and per-level
2018-09-04 20:41:11 -07:00
basis. Before running a leader or validator set the normal RUST\_LOG environment variable.
For example, to enable info everywhere and debug only in the solana::banking_stage module:
2018-05-08 13:25:59 -07:00
```bash
2018-09-04 20:41:11 -07:00
$ export RUST_LOG=info,solana::banking_stage=debug
2018-05-08 13:25:59 -07:00
```
2018-09-04 20:41:11 -07:00
Generally we are using debug for infrequent debug messages, trace for potentially frequent
messages and info for performance-related logging.
2018-06-07 08:22:38 -07:00
2018-09-04 20:41:11 -07:00
You can also attach to a running process with GDB. The leader's process is named
_solana-fullnode_:
```bash
2018-06-07 08:22:38 -07:00
$ sudo gdb
attach < PID >
set logging on
thread apply all bt
```
This will dump all the threads stack traces into gdb.txt
2018-11-06 07:06:36 -08:00
Testnet Debugging
---
We maintain several testnets:
2018-11-07 10:07:06 -08:00
* `testnet` - public stable testnet accessible via testnet.solana.com. Runs 24/7
* `testnet-perf` - permissioned stable testnet running a 24/7 soak test.
* `testnet-edge` - permissioned edge channel testnet. Runs 24/7
* `testnet-edge-perf` - permissioned edge channel testnet running a multi-hour soak test weekday mornings.
* `testnet-beta` - permissioned beta channel testnet. Runs 24/7
* `testnet-beta-perf` - permissioned beta channel testnet running a multi-hour soak test weekday mornings.
2018-11-06 07:06:36 -08:00
## Deploy process
They are deployed with the `ci/testnet-manager.sh` script through a list of [scheduled
buildkite jobs](https://buildkite.com/solana-labs/testnet-management/settings/schedules).
Each testnet can be manually manipulated from buildkite as well. The `-perf`
testnets use a release tarball while the non`-perf` builds use the snap build
(we've observed that the snap build runs slower than a tarball but this has yet
to be root caused).
## Where are the testnet logs?
Attach to the testnet first by running one of:
```bash
$ net/gce.sh config testnet-solana-com
$ net/gce.sh config master-testnet-solana-com
$ net/gce.sh config perf-testnet-solana-com
```
Then run:
```bash
$ net/ssh.sh
```
for log location details
## How do I reset the testnet?
Manually trigger the [testnet-management ](https://buildkite.com/solana-labs/testnet-management ) pipeline
and when prompted select the desired testnet
## How can I scale the tx generation rate?
Increase the TX rate by increasing the number of cores on the client machine which is running
`bench-tps` or run multiple clients. Decrease by lowering cores or using the rayon env
variable `RAYON_NUM_THREADS=<xx>`
## How can I test a change on the testnet?
Currently, a merged PR is the only way to test a change on the testnet. But you
can run your own testnet using the scripts in the `net/` directory.
## Adjusting the number of clients or validators on the testnet
Edit `ci/testnet-manager.sh`
2018-02-16 09:38:12 -08:00
Benchmarking
---
First install the nightly build of rustc. `cargo bench` requires unstable features:
```bash
$ rustup install nightly
```
Run the benchmarks:
```bash
2018-03-19 15:42:28 -07:00
$ cargo +nightly bench --features="unstable"
2018-02-16 09:38:12 -08:00
```
2018-04-04 08:26:32 -07:00
2018-08-16 20:48:11 -07:00
Release Process
---
2018-11-06 08:28:55 -08:00
The release process for this project is described [here ](rfcs/0005-branches-tags-and-channels.md ).
2018-08-16 20:48:11 -07:00
2018-04-04 08:26:32 -07:00
Code coverage
---
2018-06-18 16:36:37 -07:00
To generate code coverage statistics, install cargo-cov. Note: the tool currently only works
in Rust nightly.
2018-04-04 08:26:32 -07:00
```bash
2018-06-18 16:36:37 -07:00
$ cargo +nightly install cargo-cov
2018-04-04 08:26:32 -07:00
```
2018-06-18 16:36:37 -07:00
Run cargo-cov and generate a report:
```bash
$ cargo +nightly cov test
$ cargo +nightly cov report --open
```
The coverage report will be written to `./target/cov/report/index.html`
2018-05-28 16:46:47 -07:00
2018-04-04 08:26:32 -07:00
Why coverage? While most see coverage as a code quality metric, we see it primarily as a developer
productivity metric. When a developer makes a change to the codebase, presumably it's a *solution* to
some problem. Our unit-test suite is how we encode the set of *problems* the codebase solves. Running
the test suite should indicate that your change didn't *infringe* on anyone else's solutions. Adding a
test *protects* your solution from future changes. Say you don't understand why a line of code exists,
try deleting it and running the unit-tests. The nearest test failure should tell you what problem
was solved by that code. If no test fails, go ahead and submit a Pull Request that asks, "what
problem is solved by this code?" On the other hand, if a test does fail and you can think of a
better way to solve the same problem, a Pull Request with your solution would most certainly be
welcome! Likewise, if rewriting a test can better communicate what code it's protecting, please
send us that patch!
2018-11-06 07:06:36 -08:00
2018-11-07 08:11:05 -08:00