⚠️ This book is not complete yet. ⚠️

Contower Book

Documentation for Contower users and developers.

Contower (derived from "Control Tower") is a versatile and innovative development for the Ethereum network, integrating execution and consensus clients with relay functionalities. This combination allows Contower to serve various roles, from a full node client to a lightweight relay, providing flexibility and efficiency in blockchain operations.

We adhere strictly to the ethereum/execution-specs and ethereum/consensus-specs specifications. Our aim is to provide a seamless experience for developers and users, focusing on security, performance, and reliability. Contower is designed to be modular and extensible. We welcome community contributions to help us improve and expand Contower's features.

What is Contower?

Contower is a versatile and innovative Ethereum client that integrates execution and consensus clients with relay functionalities. It is designed to cater to various user needs, from using it as a full node client to a lightweight relay client, providing flexibility and efficiency in blockchain operations. Additionally, Contower supports all EVM-compatible chains, making it a highly adaptable solution for diverse blockchain environments.

Originally developed by Nodura, Contower adheres to the Ethereum specifications for execution and consensus layers, and is licensed under the Apache and MIT licenses.

Contower's relay mechanism significantly enhances node synchronization, allowing nodes to sync faster with the network and enabling immediate chain following upon node startup.

Creating a successful Ethereum client like Contower requires a high-quality implementation that is secure, efficient, and user-friendly, even on consumer hardware. It also involves fostering a strong community of contributors to support and enhance the software continuously.

Helpful sections

Installation: Instructions for installing Contower on your system.
Run a node: Instructions for running a Contower node.
Contributing: Guidelines for contributing to the Contower project.

Community and Support

Join our community for discussions, support, and collaboration:

Installation

Contower runs on Linux, macOS, and Windows.

Installation of Contower is straightforward and can be achieved through a few methods:

We also offer additional guides for specific platforms and use cases:

Encountering Issues?

If you encounter any issues during the installation process, please join our Discord and ask for help in the #🦾support channel or make a post in the #community-forum. Our team and community members will be happy to assist you. You can also join in on the discussions on our GitHub Discussions.

Binaries

Available Binaries

We provide binaries for the following platforms:

x86_64-unknown-linux-gnu
aarch64-unknown-linux-gnu
x86_64-apple-darwin
x86_64-windows

You can find these binaries on our GitHub Releases page. We recommend downloading the latest release for your platform.

Download and Extract

Download from GitHub

After downloading the binary from GitHub in a tar.gz file format, extract it using the following command:

tar -xvzf contower-<version>-<platform>.tar.gz

Replace <version> and <platform> with the correct details.

Add to PATH

To make the binary accessible from any directory, add it to your PATH:

export PATH=$PATH:/path/to/extracted/binary

Replace /path/to/extracted/binary with the actual path to your extracted binary.

Command Line Download

For command line downloads and extractions, follow these platform-specific instructions:

Linux (x86_64 and aarch64)

Download the binary:

curl -LO https://github.com/nodura/contower/releases/download/latest/contower-x86_64-unknown-linux-gnu.tar.gz

For a portable version:

curl -LO https://github.com/nodura/contower/releases/download/latest/contower-x86_64-unknown-linux-gnu-portable.tar.gz

Extract the binary:

tar -xvzf contower-x86_64-unknown-linux-gnu.tar.gz

Add to PATH:
```
export PATH=$PATH:/path/to/extracted/binary
```
Update /path/to/extracted/binary to your specific extraction location.

macOS (x86_64)

Download the binary:

curl -LO https://github.com/nodura/contower/releases/download/latest/contower-x86_64-apple-darwin.tar.gz

For a portable version:

curl -LO https://github.com/nodura/contower/releases/download/latest/contower-x86_64-apple-darwin-portable.tar.gz

Extract the binary:

tar -xvzf contower-x86_64-apple-darwin.tar.gz

Add to PATH:
```
export PATH=$PATH:/path/to/extracted/binary
```
Modify /path/to/extracted/binary with the correct path.

Windows (x86_64)

Download the binary:

Navigate to GitHub Releases and select contower-x86_64-windows.tar.gz for download.
Extract the binary:
- Right-click the downloaded file and select Extract All.
- Choose a destination folder and click Extract.
Add to PATH:
- Press Win + R, type sysdm.cpl, and press Enter.
- Navigate to the Advanced tab and click Environment Variables.
- In the System variables section, select Path and click Edit.
- Click New and add the path to the extracted binary.
- Confirm the changes by clicking OK.

Release Signing Key

We are currently working on providing signed releases. Stay tuned for updates.

Docker

Docker Hub

We are yet to publish our Docker images to Docker Hub. In the meantime, you can build the Docker image locally using the provided Dockerfile.

Building the Docker Image

To build the Docker image, follow these steps:

Run the following command to build the Docker image:
```
docker build . -t contower:local
```
After the build process is complete, you can run the Docker image using the following command:
```
docker run contower:local contower --help
```

This will display the help message for Contower, indicating that the Docker image was built successfully.

Using the Docker image

The functionality to fully utilize the Docker image is not available yet as we are still in the initial stages of development. As we continue to build and implement features, more detailed instructions on how to use the Docker image will be provided. Stay tuned for updates!

Building From Source

Building Contower from source is a straightforward process that can be done on Linux, macOS, and Windows. This guide will walk you through the steps required to build Contower from source.

Prerequisites

Before building Contower from source, ensure you have the following prerequisites installed on your system:

We will show you how to install these prerequisites on different operating systems.

Linux (ubuntu, debian)

To install the prerequisites on Linux, run the following commands:

sudo apt update && sudo apt install -y git gcc g++ make cmake pkg-config llvm-dev libclang-dev clang

Linux (Fedora, RHEL, CentOS)

To install the prerequisites on Fedora, RHEL, or CentOS, run the following commands:

yum -y install git make perl clang cmake

macOS

To install the prerequisites on macOS, you can use Homebrew. Run the following commands:

brew install cmake

Windows

Install Git.
Install the Chocolatey package manager for Windows.
Tips:
- Use PowerShell to install. In Windows, search for PowerShell and run as administrator.
- You must ensure Get-ExecutionPolicy is not Restricted. To test this, run Get-ExecutionPolicy in PowerShell. If it returns restricted, then run Set-ExecutionPolicy AllSigned, and then run
```
Set-ExecutionPolicy Bypass -Scope Process -Force; [System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072; iex ((New-Object System.Net.WebClient).DownloadString('https://community.chocolatey.org/install.ps1'))
```
- To verify that Chocolatey is ready, run choco and it should return the version.

Install Make, CMake and LLVM using Chocolatey:

choco install make

choco install cmake --installargs 'ADD_CMAKE_TO_PATH=System'

choco install llvm

Building Contower

Once you have installed the prerequisites, you can build Contower from source by following these steps:

Clone the Contower repository:

git clone https://github.com/nodura/contower.git

Change to the Contower directory:
```
cd contower
```
Build Contower using Make:
```
git checkout stable
```
```
make
```

Update Contower

To update Contower to the latest version, run the following commands:

cd contower

git fetch

git checkout ${version}

make

Feature Flags

Raspberry Pi

Cross-compiling

Contower supports cross-compiling, allowing users to run a binary on one platform (e.g., aarch64) that was compiled on another platform (e.g., x86_64).

Instructions

Cross-compiling requires Docker, rustembedded/cross, and for the current user to be in the Docker group.

The binaries will be created in the target/ directory of the Contower project.

Checking Docker Group Membership

To ensure you have the necessary permissions to run Docker commands without using sudo, follow these steps to check if you are already in the Docker group:

Open your terminal.
Type the following command:
```
groups
```
Look for docker in the list of groups displayed. If docker is listed, you are already in the Docker group and no further action is needed.

If you are not in the Docker group, follow the steps below to add yourself to the Docker group.

Adding User to Docker Group

To run Docker commands without sudo, add your user to the Docker group:

Create the Docker group (if it doesn't already exist):
```
sudo groupadd docker
```
Add your user to the Docker group:
```
sudo usermod -aG docker $USER
```
Restart the Docker service:
```
sudo systemctl restart docker
```
Log out and log back in so that your group membership is re-evaluated, or you can use:
```
newgrp docker
```

After following these steps, you will be able to run Docker commands without needing to prepend them with sudo.

Targets

The Makefile in the project contains four targets for cross-compiling:

build-x86_64: builds an optimized version for x86_64 processors (suitable for most users).
build-x86_64-portable: builds a version for x86_64 processors which avoids using some modern CPU instructions that are incompatible with older CPUs.
build-aarch64: builds an optimized version for 64-bit ARM processors (suitable for Raspberry Pi 4).
build-aarch64-portable: builds a version for 64-bit ARM processors which avoids using some modern CPU instructions. In practice, very few ARM processors lack the instructions necessary to run the faster non-portable build.

For more information about optimized vs portable builds see Portability.

Example

cd contower
make build-aarch64

The contower binary will be compiled inside a Docker container and placed in contower/target/aarch64-unknown-linux-gnu/release.

Feature Flags

We are still working on this feature.

Compilation Profiles

We are still working on this feature.

Contributing to Contower

Contower is an evolving project in the Ethereum ecosystem, focused on bringing innovation and efficiency to blockchain operations. We welcome contributions from developers, writers, and enthusiasts who are interested in enhancing and expanding Contower's capabilities.

Getting Started

Familiarize yourself with the how to contribute guide.
Set up your development environment as described in setup instructions.
Check out the open issues for areas where you can contribute.
- Start with issues labeled good first issue if you're new.
Before starting work on an issue, please comment on it to let others know you're working on it.
Submit your contributions as a pull request for review.

Questions or discussions? Join us on Discord.

Contribution Guidelines

New to Contributing?

If you’re new to contributing or open-source, we recommend reading our docs for more detailed instructions.

Branches

Contower will permenantly have two branches:

stable: Our primary development branch. This is where we merge new features and changes after they have been tested and are ready for release.
unstable: Our secondary development branch. This is where we merge new features and changes before they are moved to stable.

Rust Development

Contower is developed in Rust, and we follow standard Rust conventions. Use clippy and rustfmt for linting and formatting:

$ cargo clippy --all
$ cargo fmt --all --check

Panics

It's crucial to avoid panics in a high-risk environment like the Internet. Panics in Contower represent a significant security vulnerability, especially if external users can trigger them.

Opt for Result or Option instead of panicking. For example, use array.get(1)? instead of array[1].

In situations where a panic is unlikely but still needs to be communicated to the compiler, prefer .expect("Descriptive message") over .unwrap(). It's important to include a comment explaining why a panic is not expected in such cases.

TODOs

Every TODO comment must be linked to a corresponding GitHub issue.


#![allow(unused)]
fn main() {
use std::error::Error;

struct MyExampleStruct;

impl MyExampleStruct {
    pub fn my_function(&mut self, _something: &[u8]) -> Result<String, Box<dyn Error>> {
        // TODO: Implement feature
        // Issue link: https://github.com/nodura/contower/issues/XX
        Ok("Example response".to_string())
    }
}
}

Comments

General Comments

Use line comments (//) rather than block comments (/* ... */).
Comments can be placed either before the item they refer to or after a space on the same line.


#![allow(unused)]
fn main() {
// Description of the struct
struct Contower {}
fn make_blockchain() {} // Inline comment after a space
}

Documentation Comments

Use /// for generating documentation comments.
Place these comments before attributes.


#![allow(unused)]
fn main() {
use std::path::PathBuf;

/// Configuration for the Contower instance, covering the core settings.
/// This general configuration can be extended by other components. #[derive(Clone)]
#[derive(Clone)]
pub struct ContowerConfig {
    pub data_dir: PathBuf,
    pub p2p_listen_port: u16,
}
}

Rust Learning Resources

Rust is a powerful, low-level language offering great control and performance. The Rust Book is an excellent guide to understanding Rust, including its style and usage.

Learning Rust can be challenging, but there are numerous resources available:

Rust Book for a comprehensive introduction.
Rust by Example for practical learning.
Learning Rust With Entirely Too Many Linked Lists for a unique approach.
Rustlings for interactive exercises.
Rust Exercism for coding challenges.
Learn X in Y Minutes - Rust for a quick overview.

Setup Developer Environment

Prerequisites

Before you begin, ensure you have the following tools installed on your system:

Rust (latest stable version)
Git (version control system)
Make
Docker

Setup

Install Rust: Follow the official Rust installation guide to install the latest stable version of Rust.
Install Git: Follow the official Git installation guide to install Git on your system.
Install Make: Make is a build automation tool that simplifies the build process. You can install Make using your package manager:
- Debian/Ubuntu:
```
sudo apt-get install make
```
- Fedora:
```
sudo dnf install make
```
- Arch Linux:
```
sudo pacman -S make
```
- macOS:
```
brew install make
```
- Windows:
  
  You can install Make using the Chocolatey package manager:
```
choco install make
```
Install Docker: Docker is a containerization platform that allows you to package and run applications in isolated environments. Follow the official Docker installation guide to install Docker on your system.
Fork and setup the Contower repository on GitHub. As shown in the Forking documentation.

Linting and Formatting

To maintain code quality and consistency, use clippy for linting and rustfmt for formatting. Install these tools if you haven't already:

rustup component add clippy
rustup component add rustfmt

Getting Help

If you encounter issues that you can't resolve, feel free to reach out for help:

Join our Discord for real-time support.
Open an issue on the GitHub repository.

By following these steps, you should be well on your way to contributing effectively to Contower. Thank you for your contributions!