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-05-22 17:01:14 -07:00
[![Build status ](https://badge.buildkite.com/d4c4d7da9154e3a8fb7199325f430ccdb05be5fc1e92777e51.svg )](https://buildkite.com/solana-labs/solana)
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-03-01 08:16:39 -08:00
Disclaimer
===
2018-02-15 12:59:33 -08:00
2018-03-01 08:16:39 -08: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-03-27 16:20:23 -07:00
Solana: High Performance Blockchain
2018-03-01 08:16:39 -08:00
===
2018-03-27 15:16:27 -07:00
Solana™ is a new architecture for a high performance blockchain. It aims to support
2018-03-27 15:31:19 -07:00
over 700 thousand transactions per second on a gigabit network.
2018-02-15 15:09:11 -08:00
2018-04-18 20:17:37 -07:00
Introduction
===
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 178 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)]. 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! Furthermore, and much to our surprise, it can 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 in route towards that theoretical limit of 710,000 transactions per second.
2018-03-05 15:05:16 -08:00
Running the demo
2018-03-01 08:16:39 -08:00
===
2018-02-19 08:19:26 -08:00
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
$ git clone https://github.com/solana-labs/solana.git
$ cd solana
```
2018-05-25 15:56:32 -07:00
The fullnode server is initialized with a ledger from stdin and
2018-03-19 09:23:43 -07:00
generates new ledger entries on stdout. To create the input ledger, we'll need
to create *the mint* and use it to generate a *genesis ledger* . It's done in
2018-04-16 13:44:24 -07:00
two steps because the mint-demo.json file contains private keys that will be
2018-03-07 15:58:01 -08:00
used later in this demo.
2018-02-19 11:00:56 -08:00
2018-03-05 15:05:16 -08:00
```bash
2018-05-26 19:23:18 -07:00
$ echo 1000000000 | cargo run --release --bin solana-mint-demo > mint-demo.json
$ cat mint-demo.json | cargo run --release --bin solana-genesis-demo > genesis.log
2018-02-19 11:00:56 -08:00
```
2018-05-24 23:18:41 -07:00
Before you start the server, make sure you know the IP address of the machine ou want to be the leader for the demo, and make sure that udp ports 8000-10000 are open on all the machines you wan to test with. Now you can start the server:
2018-03-05 15:05:16 -08:00
```bash
2018-05-26 19:23:18 -07:00
$ cat ./multinode-demo/leader.sh
#!/bin/bash
export RUST_LOG=solana=info
sudo sysctl -w net.core.rmem_max=26214400
2018-05-26 19:48:42 -07:00
cat genesis.log leader.log | cargo run --release --features cuda --bin solana-fullnode -- -s leader.json -l leader.json -b 8000 -d 2>& 1 | tee leader-tee.log
2018-05-26 19:23:18 -07:00
$ ./multinode-demo/leader.sh
2018-03-05 15:05:16 -08:00
```
2018-04-26 12:17:36 -07:00
Wait a few seconds for the server to initialize. It will print "Ready." when it's safe
to start sending it transactions.
2018-05-24 23:18:41 -07:00
Now you can start some validators:
2018-02-20 12:07:54 -08:00
2018-03-05 15:05:16 -08:00
```bash
2018-05-26 19:23:18 -07:00
$ cat ./multinode-demo/validator.sh
#!/bin/bash
rsync -v -e ssh $1:~/solana/mint-demo.json .
rsync -v -e ssh $1:~/solana/leader.json .
rsync -v -e ssh $1:~/solana/genesis.log .
rsync -v -e ssh $1:~/solana/leader.log .
rsync -v -e ssh $1:~/solana/libcuda_verify_ed25519.a .
export RUST_LOG=solana=info
sudo sysctl -w net.core.rmem_max=26214400
2018-05-26 19:48:42 -07:00
cat genesis.log leader.log | cargo run --release --features cuda --bin solana-fullnode -- -l validator.json -s validator.json -v leader.json -b 9000 -d 2>& 1 | tee validator-tee.log
2018-05-26 19:23:18 -07:00
$ ./multinode-demo/validator.sh ubuntu@10.0.1.51 #The leader machine
2018-03-05 15:05:16 -08:00
```
2018-05-24 23:18:41 -07:00
Then, in a separate shell, let's execute some transactions. Note we pass in
the JSON configuration file here, not the genesis ledger.
2018-03-05 15:05:16 -08:00
```bash
2018-05-26 19:23:18 -07:00
$ cat ./multinode-demo/client.sh
#!/bin/bash
export RUST_LOG=solana=info
rsync -v -e ssh $1:~/solana/leader.json .
rsync -v -e ssh $1:~/solana/mint-demo.json .
2018-05-26 19:28:22 -07:00
cat mint-demo.json | cargo run --release --bin solana-client-demo -- -l leader.json -c 8100 -n 1
2018-05-26 19:23:18 -07:00
$ ./multinode-demo/client.sh ubuntu@10.0.1.51 #The leader machine
2018-02-20 12:07:54 -08:00
```
2018-05-24 23:18:41 -07:00
Try starting a more validators and reruning the client demo!
2018-02-19 11:00:56 -08:00
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-02 17:06:41 -07:00
If your rustc version is lower than 1.25.0, please update it:
2018-05-02 16:38:09 -07:00
```bash
$ rustup update
```
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-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:
```bash
$ ./ci/run-local.sh
```
2018-05-08 13:25:59 -07:00
Debugging
---
There are some useful debug messages in the code, you can enable them on a per-module and per-level
2018-05-25 15:56:32 -07:00
basis with the normal RUST\_LOG environment variable. Run the fullnode with this syntax:
2018-05-08 13:25:59 -07:00
```bash
2018-05-25 15:56:32 -07:00
$ RUST_LOG=solana::streamer=debug,solana::server=info cat genesis.log | ./target/release/solana-fullnode > transactions0.log
2018-05-08 13:25:59 -07:00
```
2018-05-25 15:56:32 -07:00
to see the debug and info sections for streamer and server respectively. Generally
2018-05-08 13:25:59 -07:00
we are using debug for infrequent debug messages, trace for potentially frequent messages and
info for performance-related logging.
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-04-30 14:20:39 -07:00
To run the benchmarks on Linux with GPU optimizations enabled:
```bash
2018-05-08 06:44:24 -07:00
$ wget https://solana-build-artifacts.s3.amazonaws.com/v0.5.0/libcuda_verify_ed25519.a
2018-04-30 14:20:39 -07:00
$ cargo +nightly bench --features="unstable,cuda"
```
2018-04-04 08:26:32 -07:00
Code coverage
---
To generate code coverage statistics, run kcov via Docker:
```bash
2018-05-28 16:46:47 -07:00
$ ./ci/coverage.sh
2018-04-04 08:26:32 -07:00
```
2018-05-28 16:46:47 -07:00
The coverage report will be written to `./target/cov/index.html`
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!