narwhal - GitLite

KO | EN

gitlite — search

#javascript #typescript #go #golang #android #deep-learning #nodejs #java #cli #kubernetes #pytorch #mcp #ios #openai

narwhal

(★ 221)

Narwhal and Tusk: A DAG-based Mempool and Efficient BFT Consensus.

File Explorer

Download Latest Version (.zip)

- diagram-primary.svg
- diagram-worker.svg
- diagram.drawio
- - rust.yml
- - __init__
  - aggregate.py
  - commands.py
  - config.py
  - instance.py
  - local.py
  - logs.py
  - plot.py
  - remote.py
  - settings.py
  - utils.py
- .gitignore
- fabfile.py
- README.md
- requirements.txt
- settings.json
- - lib.rs
- Cargo.toml
- - lib.rs
- Cargo.toml
- - lib.rs
- Cargo.toml
- - error.rs
  - lib.rs
  - receiver.rs
  - reliable_sender.rs
  - simple_sender.rs
- Cargo.toml
- - benchmark_client.rs
  - main.rs
- Cargo.toml
- - aggregators.rs
  - certificate_waiter.rs
  - core.rs
  - error.rs
  - garbage_collector.rs
  - header_waiter.rs
  - helper.rs
  - lib.rs
  - messages.rs
  - payload_receiver.rs
  - primary.rs
  - proposer.rs
  - synchronizer.rs
- Cargo.toml
- README.md
- - lib.rs
- Cargo.toml
- - batch_maker.rs
  - helper.rs
  - lib.rs
  - primary_connector.rs
  - processor.rs
  - quorum_waiter.rs
  - synchronizer.rs
  - worker.rs
- Cargo.toml
- README.md
.gitignore
Cargo.toml
CODE_OF_CONDUCT.md
CONTRIBUTING.md
LICENSE
README.md

# Installation Guide

1. Get the code

git clone https://github.com/facebookresearch/narwhal

Downloads the entire project code from GitHub to your computer.

cd narwhal

Moves into the project folder you just downloaded.

2. Python

Easy Recommended

Prerequisites

Git Needed to download the project code from GitHub.
Python 3 On Windows, be sure to check 'Add Python to PATH' during installation.

$ pip install -r requirements.txt

Installs the Python libraries listed in requirements.txt (or similar).

✅ If it runs without errors and prints output in the terminal, it worked.

Pulled directly from this repo's README.

3. Rust

Medium

Prerequisites

Git Needed to download the project code from GitHub.
Rust (rustup) Installing via rustup also installs cargo.

cargo build --release

Compiles the Rust project.

cargo run

Builds and then immediately runs the program.

✅ If cargo build finishes without errors, it worked. The executable is created under target/.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Narwhal and Tusk

[![build status](https://img.shields.io/github/workflow/status/asonnino/narwhal/Rust/master?style=flat-square&logo=github)](https://github.com/asonnino/narwhal/actions)
[![rustc](https://img.shields.io/badge/rustc-1.51+-blue?style=flat-square&logo=rust)](https://www.rust-lang.org)
[![license](https://img.shields.io/badge/license-Apache-blue.svg?style=flat-square)](https://raw.githubusercontent.com/facebookresearch/narwhal/main/LICENSE)

This repo provides an implementation of [Narwhal and Tusk](https://arxiv.org/pdf/2105.11827.pdf). The codebase has been designed to be small, efficient, and easy to benchmark and modify. It has not been designed to run in production but uses real cryptography ([dalek](https://doc.dalek.rs/ed25519_dalek)), networking ([tokio](https://docs.rs/tokio)), and storage ([rocksdb](https://docs.rs/rocksdb)).

## Quick Start
The core protocols are written in Rust, but all benchmarking scripts are written in Python and run with [Fabric](http://www.fabfile.org/).
To deploy and benchmark a testbed of 4 nodes on your local machine, clone the repo and install the python dependencies:
```
$ git clone https://github.com/asonnino/narwhal.git
$ cd narwhal/benchmark
$ pip install -r requirements.txt
```
You also need to install Clang (required by rocksdb) and [tmux](https://linuxize.com/post/getting-started-with-tmux/#installing-tmux) (which runs all nodes and clients in the background). Finally, run a local benchmark using fabric:
```
$ fab local
```
This command may take a long time the first time you run it (compiling rust code in `release` mode may be slow) and you can customize a number of benchmark parameters in `fabfile.py`. When the benchmark terminates, it displays a summary of the execution similarly to the one below.
```
-----------------------------------------
 SUMMARY:
-----------------------------------------
 + CONFIG:
 Faults: 0 node(s)
 Committee size: 4 node(s)
 Worker(s) per node: 1 worker(s)
 Collocate primary and workers: True
 Input rate: 50,000 tx/s
 Transaction size: 512 B
 Execution time: 19 s

Header size: 1,000 B
 Max header delay: 100 ms
 GC depth: 50 round(s)
 Sync retry delay: 10,000 ms
 Sync retry nodes: 3 node(s)
 batch size: 500,000 B
 Max batch delay: 100 ms

+ RESULTS:
 Consensus TPS: 46,478 tx/s
 Consensus BPS: 23,796,531 B/s
 Consensus latency: 464 ms

End-to-end TPS: 46,149 tx/s
 End-to-end BPS: 23,628,541 B/s
 End-to-end latency: 557 ms
-----------------------------------------
```

## Next Steps
The next step is to read the paper [Narwhal and Tusk: A DAG-based Mempool and Efficient BFT Consensus](https://arxiv.org/pdf/2105.11827.pdf). It is then recommended to have a look at the README files of the [worker](https://github.com/asonnino/narwhal/tree/master/worker) and [primary](https://github.com/asonnino/narwhal/tree/master/primary) crates. An additional resource to better understand the Tusk consensus protocol is the paper [All You Need is DAG](https://arxiv.org/abs/2102.08325) as it describes a similar protocol.

The README file of the [benchmark folder](https://github.com/asonnino/narwhal/tree/master/benchmark) explains how to benchmark the codebase and read benchmarks' results. It also provides a step-by-step tutorial to run benchmarks on [Amazon Web Services (AWS)](https://aws.amazon.com) accross multiple data centers (WAN).

## License
This software is licensed as [Apache 2.0](LICENSE).