astra-network

module
v0.0.0-...-3da4c06 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jun 16, 2022 License: LGPL-3.0

README

Astra

Build Status gopherbadger-tag-do-not-edit Discord Github Action Go Report Card

General Documentation

https://docs.astranetwork.com

API Guide

http://api.astranetwork.com/

Requirements

Go 1.16.3
sudo snap install go --channel=1.16/stable --classic
GMP and OpenSSL

On macOS:

brew install gmp
brew install openssl
sudo ln -sf /usr/local/opt/openssl@1.1 /usr/local/opt/openssl

On Linux (Ubuntu)

sudo apt install libgmp-dev  libssl-dev  make gcc g++ git

On Linux (Cent OS / Amazon Linux 2)

sudo yum install glibc-static gmp-devel gmp-static openssl-libs openssl-static gcc-c++
Docker (for testing)

On macOS:

brew install --cask docker
open /Applications/Docker.app

On Linux, reference official documentation here.

Bash 4+

For macOS, you can reference this guide. For Linux, you can reference this guide.

Dev Environment

Most repos from astra-net assumes the GOPATH convention. More information here.

First Install

Clone and set up all of the repos with the following set of commands:

  1. Create the appropriate directories:
mkdir -p $(go env GOPATH)/src/github.com/astra-net
cd $(go env GOPATH)/src/github.com/astra-net

If you get 'unknown command' or something along those lines, make sure to install golang first.

  1. Clone this repo & dependent repos.
git clone https://github.com/astra-net/mcl.git
git clone https://github.com/astra-net/bls.git
git clone https://github.com/astra-net/astra-network.git
cd astra-network
  1. Build the astra binary & dependent libs
go mod tidy
make

Run bash scripts/install_build_tools.sh to ensure build tools are of correct versions. If you get 'missing go.sum entry for module providing package <package_name>', run go mod tidy.

Dev Docker Image

Included in this repo is a Dockerfile that has a full astra development environment and comes with emacs, vim, ag, tig and other creature comforts. Most importantly, it already has the go environment with our C/C++ based library dependencies (libbls and mcl) set up correctly for you.

You can build the docker image for yourself with the following commands:

cd $(go env GOPATH)/src/github.com/astra-net/astra-network
make clean
docker build -t astra .

If your build machine has an ARM-based chip, like Apple silicon (M1), the image is built for linux/arm64 by default. To build for x86_64, apply the --platform arg like so:

docker build --platform linux/amd64 -t astra .

Learn more about the --platform arg and multi-CPU architecture support, here and here.

Then you can start your docker container with the following command:

docker run --rm --name astra -it -v "$(go env GOPATH)/src/github.com/astra-net/astra-network:/root/go/src/github.com/astra-net/astra-network" astra /bin/bash

Note that the astra repo will be shared between your docker container and your host machine. However, everything else in the docker container will be ephemeral.

If you need to open another shell, just do:

docker exec -it astra /bin/bash

Learn more about docker here.

Build

The make command should automatically build the Astra binary & all dependent libs.

However, if you wish to bypass the Makefile, first export the build flags:

export CGO_CFLAGS="-I$GOPATH/src/github.com/astra-net/bls/include -I$GOPATH/src/github.com/astra-net/mcl/include -I/usr/local/opt/openssl/include"
export CGO_LDFLAGS="-L$GOPATH/src/github.com/astra-net/bls/lib -L/usr/local/opt/openssl/lib"
export LD_LIBRARY_PATH=$GOPATH/src/github.com/astra-net/bls/lib:$GOPATH/src/github.com/astra-net/mcl/lib:/usr/local/opt/openssl/lib
export LIBRARY_PATH=$LD_LIBRARY_PATH
export DYLD_FALLBACK_LIBRARY_PATH=$LD_LIBRARY_PATH
export GO111MODULE=on

Then you can build all executables with the following command:

bash ./scripts/go_executable_build.sh -S

Reference bash ./scripts/go_executable_build.sh -h for more build options

Debugging

One can start a local network (a.k.a localnet) with your current code using the following command:

make debug

This localnet has 2 shards, with 11 nodes on shard 0 (+1 explorer node) and 10 nodes on shard 0 (+1 explorer node).

The shard 0 endpoint will be on the explorer at http://localhost:9599. The shard 1 endpoint will be on the explorer at http://localhost:9598.

You can view the localnet configuration at /test/configs/local-resharding.txt. The fields for the config are (space-delimited & in order) ip, port, mode, bls_pub_key, and shard (optional).

One can force kill the local network with the following command:

make debug-kill

You can view all make commands with make help

Testing

To keep things consistent, we have a docker image to run all tests. These are the same tests ran on the pull request checks.

Note that all testing docker container binds a couple of ports to the host machine for your convince. The ports are:

  • 9500 - Shard 0 RPC for a validator
  • 9501 - Shard 1 RPC for a validator
  • 9599 - Shard 0 RPC for an explorer
  • 9598 - Shard 1 RPC for an explorer
  • 9799 - Shard 0 Rosetta (for an explorer)
  • 9798 - Shard 1 Rosetta (for an explorer)
  • 9899 - Shard 0 WS for an explorer
  • 9898 - Shard 1 WS for an explorer

    This allows you to use curl, astra CLI, postman, rosetta-cli, etc... on your host machine to play with or probe the localnet that was used for the test.

Go tests

To run this test, do:

make test-go

This test runs the go tests along with go lint, go fmt, go imports, go mod, and go generate checks.

RPC tests

To run this test, do:

make test-rpc

This test starts a localnet (within the Docker container), ensures it reaches a consensus, and runs a series of tests to ensure correct RPC behavior. This test also acts as a preliminary integration test (more through tests are done on the testnets).

The tests ran by this command can be found here.

If you wish to debug further with the localnet after the tests are done, open a new shell and run:

make test-rpc-attach

This will open a shell in the docker container that is running the Node API tests.

Note that the docker container has the Astra CLI on path, therefore you can use that to debug if needed. For example, one could do astra blockchain latest-headers to check the current block height of localnet. Reference the documentation for the CLI here for more details & commands.

Rosetta tests

To run this test, do:

make test-rosetta

This test starts a localnet (within the Docker container), ensures it reaches a consensus, and runs the Construction & Data API checks using the rosetta-cli. This test also acts as a preliminary integration test (more through tests are done on the testnets).

The config for this test can be found here & here

Similar to the RPC tests, if you wish to debug further with the localnet after the tests are done, open a new shell and run:

make test-rosetta-attach

License

Astra is licensed under GNU Lesser General Public License v3.0. See LICENSE file for the terms and conditions.

Astra includes third-party open-source code. In general, a source subtree with a LICENSE or COPYRIGHT file is from a third party, and our modifications thereto are licensed under the same third-party open source license.

Also please see our Fiduciary License Agreement if you are contributing to the project. By your submission of your contribution to us, you and we mutually agree to the terms and conditions of the agreement.

Contributing To Astra

See CONTRIBUTING for details.

Development Status

Finished Features
  • Fully sharded network with beacon chain and shard chains
  • Sharded P2P network and P2P gossiping
  • FBFT (Fast Byzantine Fault Tolerance) Consensus with BLS multi-signature
  • Consensus view-change protocol
  • Account model and support for Solidity
  • Cross-shard transaction
  • VRF (Verifiable Random Function) and VDF (Verifiable Delay Function)
  • Cross-links
  • EPoS staking mechanism
  • Kademlia routing
Planned Features
  • Resharding
  • Integration with WASM
  • Fast state synchronization
  • Auditable privacy asset using ZK proof

Directories

Path Synopsis
Package accounts implements high level Ethereum account management.
Package accounts implements high level Ethereum account management.
abi
Package abi implements the Ethereum ABI (Application Binary Interface).
Package abi implements the Ethereum ABI (Application Binary Interface).
abi/bind
Package bind generates Ethereum contract Go bindings.
Package bind generates Ethereum contract Go bindings.
keystore
Package keystore implements encrypted storage of secp256k1 private keys.
Package keystore implements encrypted storage of secp256k1 private keys.
api
service/explorer
TODO: refactor this whole module to v0 and v1
TODO: refactor this whole module to v0 and v1
service/prometheus
Package prometheus defines a service which is used for metrics collection and health of a node in Astra.
Package prometheus defines a service which is used for metrics collection and health of a node in Astra.
tracers
Package tracers is a collection of JavaScript transaction tracers.
Package tracers is a collection of JavaScript transaction tracers.
tracers/internal/tracers
Package tracers contains the actual JavaScript tracer assets.
Package tracers contains the actual JavaScript tracer assets.
v0
v1
v2
v3
cmd
common
math
Package math provides integer math utilities.
Package math provides integer math utilities.
ntp
Package core implements the Ethereum consensus protocol.
Package core implements the Ethereum consensus protocol.
rawdb
Package rawdb contains a collection of low level database accessors.
Package rawdb contains a collection of low level database accessors.
state
Package state provides a caching layer atop the Ethereum state trie.
Package state provides a caching layer atop the Ethereum state trie.
types
Package types contains data types related to Ethereum consensus.
Package types contains data types related to Ethereum consensus.
vm
Package vm implements the Ethereum Virtual Machine.
Package vm implements the Ethereum Virtual Machine.
vm/runtime
Package runtime provides a basic execution model for executing EVM code.
Package runtime provides a basic execution model for executing EVM code.
crypto
bls
vdf
Package vdf is a proof-of-concept implementation of a delay function and the security properties are not guaranteed.
Package vdf is a proof-of-concept implementation of a delay function and the security properties are not guaranteed.
vrf
Package vrf defines the interface to a verifiable random function.
Package vrf defines the interface to a verifiable random function.
vrf/p256
Package p256 implements a verifiable random function using curve p256.
Package p256 implements a verifiable random function using curve p256.
eth
rpc
Package rpc implements bi-directional JSON-RPC 2.0 on multiple transports.
Package rpc implements bi-directional JSON-RPC 2.0 on multiple transports.
internal
cli
configs/node
Package nodeconfig includes all the configuration variables for a node.
Package nodeconfig includes all the configuration variables for a node.
configs/sharding
Package shardingconfig defines types and utilities that deal with Astra sharding configuration schedule.
Package shardingconfig defines types and utilities that deal with Astra sharding configuration schedule.
p2p
package p2p
package p2p
rpc
eth
filters
Package filters implements an ethereum filtering system for block, transactions and log events.
Package filters implements an ethereum filtering system for block, transactions and log events.
v1
v2
apr
test

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL