search

entropyxyz / entropy-core

Protocol and cryptography development.
https://docs.entropy.xyz/
GNU Affero General Public License v3.0
11 stars 2 forks source link

readme

Entropy Core

CircleCI

This repo contains the Entropy blockchain node, the Threshold Signature Server (evaluates programs, stores threshold keyshares, and coordinates threshold-signing), and misc. testing utilities for the network.

Our blockchain node is written with Substrate using Substrate's node template.

Documentation

You can also build the API docs yourself:

  1. Install the dependencies
  2. Invoke 
    cargo doc --no-deps --open`

Getting Started

You can begin using this repository in a few different ways. This section describes a few of them.

Getting started with Docker

This repository provides a Docker Compose configuration that spins up a simple, two-node development blockchain. We provide Docker images that you can pull, or you can build from source.

Do this to use the Docker Compose configuration:

  1. Install Docker. Make sure you also have Docker Compose. Confirm this by running: 
    docker compose version
  2. Bring up the configuration: 
    docker compose up --detach # Detaching is optional.
  3. If you need to communicate directly with the threshold signature scheme server from your Docker host machine, you may also need to include its address in your local /etc/hosts file: 
    echo "127.0.0.1 alice-tss-server bob-tss-server charlie-tss-server" | sudo tee -a /etc/hosts
  4. Confirm your local development network is up and running. You can:
    • look at server logs: 
      docker compose logs --follow # Following is also optional.
    • use the Entropy Test CLI to interact with the locally running network: 
      cargo run -p entropy-test-cli -- --chain-endpoint="ws://127.0.0.1:9944" status

Building from source

Dependencies you will need to build locally:

  1. Install Rust
  2. Install Substrate dependencies
  3. Add Rust components 
    rustup target add wasm32-unknown-unknown
rustup component add rust-src
  4. Install wasm-pack 
    curl https://rustwasm.github.io/wasm-pack/installer/init.sh -sSf | sh

Build the chain node and threshold signature scheme (TSS) server binaries by running:

cargo build --release

Run: Single-Node Development Chain

Spinning up a local Entropy node for development and basic testing can be done with:

cargo run --release -p entropy -- --dev --rpc-external

Once built, the binary can also be run directly with:

./target/release/entropy --dev --rpc-external

Optionally, you can also run it with detailed logging:

RUST_BACKTRACE=1 ./target/release/entropy -ldebug --dev --rpc-external

Testing

Testing is done via cargo test.

An Entropy node binary is required in order to succesfully run the server tests.

You can manually provide a binary using the ENTROPY_NODE environment variable.

ENTROPY_NODE="/path/to/entropy" cargo test -p entropy-tss

Or, if no path is specified using ENTROPY_NODE, then the test suite will search in the target folder for a binary. A debug or release binary will be chosen based on how the test suite is built.

For example, running cargo test -p entropy-tss --release will expect a release binary of the Entropy node, which you can build in the following way: cargo build -p entropy --release.

To run individual tests you can specify the test in the following way:

cargo test -p entropy-tss --features unsafe -- test_sign_tx_no_chain --nocapture

Connect with Polkadot-JS Apps Front-end

Once the node template is running locally, you can connect it with Polkadot-JS Apps front-end to interact with your chain. Click here connecting the Apps to your local node template.

Command line interface

A simple command line interface client is included in this repository for test purposes. This can be used with both the local docker-compose network and network deployments.

It is however only intended for use with test networks and has no secure private key storage. For a fully featured command line client see entropyxyz/cli.

Threshold Keys

Alice

Bob

Charlie

Pulling Metadata

Everytime a change to the chain's interface happens, metadata needs to be pulled. You'll need to install Subxt using cargo install subxt-cli. Then run a development chain and then invoke the ./scripts/pull_entropy_metadata.sh script.

Regenerating test keyshares

To speed up running tests, some tests use pre-generated keyshares rather than running a distributed key generation during the test. If you need to regenerate these keyshares because something has changed in either Synedrion or the identities of the test TS servers, you can run:

./scripts/create-test-keyshares.sh`

from the project root. For an explanation of how the test keyshare sets are structured, see create-test-keyshares.

Support

Need help with something not necessarily related to entropy-core?

Head over to the Entropy Community repository for support or to raise a ticket.

Licensing

For the most part, the code in this repository is licensed under AGPL-3.0.

There are some exceptions however:

Modifications made by Entropy to these crates are licensed under AGPL-3.0.