Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

fix: update some obvious gaps / inaccuracies in the main readmes #4738

Merged
merged 1 commit into from
Apr 9, 2024
Merged

fix: update some obvious gaps / inaccuracies in the main readmes #4738

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
51 changes: 20 additions & 31 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,20 +2,23 @@

# Chainflip

This repo contains everything you need to run a validator node on the Chainflip network.
[Chainflip](https://chainflip.io/) is a decentralized protocol for cross-chain crypto-currency swaps.

For an in-depth introduction to Chainflip, the [official docs](https://docs.chainflip.io/) are the best place to start.

If you are interested in contributing to the codebase or in digging into the nitty gritty details of the protocol, you have come to the right place. Please read on.

## Getting started

The project is organised using rust workspaces. See the `Cargo.toml` in this directory for a list of contained
workspaces. Each workspace should have its own `README` with instructions on how to get started. If not, please raise an
issue!
workspaces. Each workspace should have its own `README` with instructions on how to get started. If not, please raise an issue!

## Compile and run tests

To compile the code execute:

```bash
cargo build --release
cargo cf-build-release
```

To run the test suite execute:
Expand All @@ -24,7 +27,7 @@ To run the test suite execute:
cargo cf-test-ci
```

> **_NOTE:_** ci-test-ci is an alias for cargo test with additional flags.
> **_NOTE:_** cf-test-ci is an alias for cargo test with additional flags. These aliases are defined in [.cargo/config.toml](.cargo/config.toml).

## Contributing

Expand All @@ -44,11 +47,6 @@ Please see this as a guideline rather than rigidly enforced rules. We will defin
with `rustfmt` in due course. It should be straightforward to integrate this with your favourite editor for
auto-formatting.

> TODO: research and set up .rustfmt and/or .editorconfig settings, and enforce with CI. We may need to have separate
> settings files for each sub-project since substrate code has some funky settings by default and we may want to stick
> to
> a more common setup for our non-substrate components.

### Branching and merging

Before making any changes:
Expand Down Expand Up @@ -81,24 +79,23 @@ The following commands should be executed from the repo root directory.
- Clean up old build objects (sometimes this will fix compile problems):
- `cargo clean`
- `cargo clean -p <package>`
- Audit external dependencies (The CI runs this <https://github.com/chainflip-io/chainflip-backend/issues/1175>):<br>
`cargo audit`
- Audit external dependencies.<br>
Requires cargo-audit(`cargo install cargo-audit`)):<br>
`cargo cf-audit`

## Localnet

You can run a local single-node testnet (Localnet), in Docker. This will allow you to quickly iterate on a particular
commit.

### Prerequisits
### Prerequisites

You will need to download [Docker](https://docs.docker.com/get-docker/), docker-compose and
the [1Password CLI 2](https://developer.1password.com/docs/cli/get-started/).

#### Login to 1Password

The simplest way to login is to go via
the [1Password app](https://developer.1password.com/docs/cli/get-started#step-1-connect-1password-cli-with-the-1password-app)
. Make sure you have v8 of 1Password installed.
The simplest way to login is to go via the [1Password app](https://developer.1password.com/docs/cli/get-started#step-1-connect-1password-cli-with-the-1password-app). Make sure you have v8 of 1Password installed.

Verify you can connect to 1Password with:

Expand All @@ -108,18 +105,15 @@ op vault ls

#### Login to Docker

The script will ask you to log in to our Docker container registry. You will need to create
a [Classic PAT](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token#creating-a-personal-access-token-classic)
for this.
The script will ask you to log in to our Docker container registry. You will need to create a [Classic PAT](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token#creating-a-personal-access-token-classic) for this.

You only need to enable the `packages:read` permission.

When creating a new PAT, you need to delete the `.setup_complete` file under `localnet`, which will cause the manage.sh to ask you again for the PAT you created.

### Creating a Localnet

Localnets use binaries built locally. To create a Localnet for your current branch, you will first need to build.
You can use either release or debug builds.
Localnets use binaries built locally. To create a Localnet for your current branch, you will first need to build. You can use either release or debug builds.

From the repo root, run the following:

Expand All @@ -128,8 +122,7 @@ cargo build
./localnet/manage.sh
```

If this is your first Localnet, the script will ask you to authenticate to Docker and 1Password. The script might fail
if you haven't done this yet.
If this is your first Localnet, the script will ask you to authenticate to Docker and 1Password. The script might fail if you haven't done this yet.

After set up completion, you will see the following:

Expand All @@ -150,18 +143,14 @@ After set up completion, you will see the following:
- **logs** - Tail the logs for your current Localnet.
- **yeet** - Destroy your current Localnet, and remove all data including docker images. You should use this if you are getting some weird caching issues.

### Log Filtering
### Log Filtering in the Chainflip Engine

These commands can be used to control which logs the engine outputs at runtime.

- `curl -X GET 127.0.0.1:36079/tracing` (Returns the current filtering directives)
- `curl --json '"debug,warp=off,hyper=off,jsonrpc=off,web3=off,reqwest=off"' (Sets the filter directives so the default is DEBUG, and the logging in modules warp, hyper, jsonrpc, web3, and reqwest is turned off)
- `curl -X POST -H 'Content-Type: application/json' -d '"debug,warp=off,hyper=off,jsonrpc=off,web3=off,reqwest=off"' 127.0.0.1:36079/tracing` (Equivalent to the above, but without using the --sjon short-hand)
- `curl --json '"debug,warp=off,hyper=off,jsonrpc=off,web3=off,reqwest=off"` (Sets the filter directives so the default is DEBUG, and the logging in modules warp, hyper, jsonrpc, web3, and reqwest is turned off)
- `curl -X POST -H 'Content-Type: application/json' -d '"debug,warp=off,hyper=off,jsonrpc=off,web3=off,reqwest=off"' 127.0.0.1:36079/tracing` (Equivalent to the above, but without using the --json short-hand)

The `RUST_LOG` environment variable controls the initial filtering directives if specified at engine startup.
[manage.sh](localnet%2Fmanage.sh)
The syntax for specifying filtering directives is given here: <https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html>

## Testnet

To start a multi node testnet you can use the [chainflip-testnet-tools](https://github.com/chainflip-io/chainflip-testnet-tools). A multi-node testnet can be useful to test more complex test scenarios under more realistic conditions.
The syntax for specifying filtering directives is given here: <https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html>
107 changes: 35 additions & 72 deletions state-chain/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,59 +10,20 @@ Follow these steps to get started :hammer_and_wrench:

First, complete the [basic Rust setup instructions](./doc/rust-setup.md).

### Makefile

Use Rust's native `cargo` command to build and launch the template node:

```sh
cargo run --release -- --dev --tmp
```

### Build

The `cargo run` command will perform an initial build. Use the following command to build the node without launching it:
Use the following command to build the node without launching it:

```sh
cargo build --release
```

### Chain Specification Docs

Docs on custom chain specifications can be found at <https://docs.substrate.io/main-docs/build/chain-spec/>.

In order to create a custom chain specification use `./target/release/chainflip-node build-spec --help` to find out how.

### Benchmark

To benchmark the node for a production release you can run:

```sh
./state-chain/scripts/benchmark-all.sh
cargo cf-build-release
```

This script is building the node, executing the benchmarks, updating the weight files and guide you through adding the diff of any benchmark.

### Embedded Docs
## Run

Once the project has been built, the following command can be used to explore all parameters and subcommands:

```sh
./target/release/chainflip-node -h
```

## Run

The provided `cargo run` command will launch a temporary node and its state will be discarded after you terminate the
process. After the project has been built, there are other ways to launch the node.

### Configuration

For local development you need to set the following env vars:

```bash
export STATE_CHAIN_GATEWAY_ADDRESS="0x..."
export KEY_MANAGER_ADDRESS="0x..."
export ETHEREUM_CHAIN_ID=4
./target/release/chainflip-node --help
```

### Single-Node Development Chain
Expand All @@ -73,7 +34,7 @@ This command will start the single-node development chain with persistent state:
./target/release/chainflip-node --dev
```

Purge the development chain's state:
Purging the development chain's state:

```bash
./target/release/chainflip-node purge-chain --dev
Expand All @@ -85,13 +46,41 @@ Start the development chain with detailed logging:
RUST_LOG=debug RUST_BACKTRACE=1 ./target/release/chainflip-node -lruntime=debug --dev
```

> See the section on localnets in the top-level [README](../README.md#localnet) file.

### Connecting to a live network

You can connect to a live network by specifying the appropriate *raw* chainspec.

For example, for perseverance testnet:

```sh
./target/release/chainflip-node --chain=./state-chain/node/chainspecs/perseverance.chainspec.raw.json
```

### Multi-Node Local Testnet

With a little effort you can run a local testnet [using docker compose](doc/docker-compose).

## Template Structure
### Benchmark

To benchmark the node for a production release you need to build with the runtime-benchmarks feature enable.

```sh
cargo cf-build-benchmarks
```

After that you can run:

```sh
./state-chain/scripts/benchmark-all.sh
```

This will run the benchmarks and update the weights files for each pallet.

## Components

A Substrate project such as this consists of a number of components that are spread across a few directories.
Chainflip's State Chain is build using Substrate and the directory structure is based on common substrate conventions.

### Node

Expand Down Expand Up @@ -177,29 +166,3 @@ A FRAME pallet is compromised of a number of blockchain primitives:
- Errors: When a dispatchable fails, it returns an error.
- Config: The `Config` configuration interface is used to define the types and parameters upon
which a FRAME pallet depends.

### Run in Docker

First, install [Docker](https://docs.docker.com/get-docker/) and
[Docker Compose](https://docs.docker.com/compose/install/).

Then run the following command to start a single node development chain.

```bash
./scripts/docker_run.sh
```

This command will firstly compile your code, and then start a local development network. You can also replace the
default command (`cargo build --release && ./target/release/chainflip-node --dev --ws-external`)
by appending your own. A few useful ones are as follow.

```bash
# Run Substrate node without re-compiling
./scripts/docker_run.sh ./target/release/chainflip-node --dev --ws-external

# Purge the local dev chain
./scripts/docker_run.sh ./target/release/chainflip-node purge-chain --dev

# Check whether the code is compilable
./scripts/docker_run.sh cargo check
```
Loading