Skip to content

Commit

Permalink
fix: readme
Browse files Browse the repository at this point in the history
  • Loading branch information
MohsenNz committed Jan 11, 2025
1 parent ea74ee7 commit b2a57d6
Show file tree
Hide file tree
Showing 2 changed files with 180 additions and 149 deletions.
207 changes: 58 additions & 149 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,49 +12,76 @@
[![Discord Chat](https://img.shields.io/discord/308323056592486420.svg)](https://discord.gg/jungochain)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://jungoai.xyz/licenses/MIT)

This repository contains Jungoai's jungochain. Jungochain contains the trusted logic which:
It's the blockchain layer of Jungoai.

1. Runs Bittensor's [consensus mechanism](./docs/consensus.md);
2. Advertises neuron information, IPs, etc., and
3. Facilitates value transfer via JUNGO.
## Run a node

## System Requirements
### System Requirements

* Jungochain needs ~286 MiB to run.
* Architectures other than x86_64 are currently not supported.
* OSs other than Linux and MacOS are currently not supported.
- RAM: ~286 MiB
- Arch: x86_64
- OSs: Linux, MacOS

## Architectures
Jungochain support the following architectures:
### Architectures

## Linux x86_64
### Linux x86_64
Requirements:
* Linux kernel 2.6.32+,
* glibc 2.11+
A fresh FRAME-based [Substrate](https://www.substrate.io/) node, ready for hacking :rocket:

## MacOS x86_64
### MacOS x86_64
Requirements:
* MacOS 10.7+ (Lion+)

## Network requirements
* Jungochain needs access to the public internet
* Jungochain runs on ipv4
* Jungochain listens on the following ports:
1) 9944 - Websocket. This port is used by jungo-sdk. It only accepts connections from localhost. Make sure this port is firewalled off from the public domain.
2) 9933 - RPC. This port is opened, but not used.
3) 30333 - p2p socket. This port accepts connections from other jungochain nodes. Make sure your firewall(s) allow incoming traffic to this port.
* It is assumed your default outgoing traffic policy is ACCEPT. If not, make sure outbound traffic to port 30333 is allowed.
### Network requirements
- Jungochain needs access to the public internet
- Jungochain runs on ipv4
- Jungochain listens on the following ports:
- 9944 - Websocket. This port is used by jungo-sdk. It only accepts connections from localhost. Make sure this port is firewalled off from the public domain.
- 9933 - RPC. This port is opened, but not used.
- 30333 - p2p socket. This port accepts connections from other jungochain nodes. Make sure your firewall(s) allow incoming traffic to this port.
- It is assumed your default outgoing traffic policy is ACCEPT. If not, make sure outbound traffic to port 30333 is allowed.

### Login to ghcr.io

- Generate a PAT:
- Go to [GitHub Developer Settings](https://github.com/settings/tokens).
- Click *Generate new token* (classic).
- Select scopes: read:packages (to pull images).
- Login to ghcr.io
```bash
echo "<your_personal_access_token>" | docker login ghcr.io -u <your_github_username> --password-stdin
```

---
### Pull docker image:

## For Subnet Development
```bash
docker pull ghcr.io/jungoai/jungochain:0.1.0-devnet
```

### Run image

Simply run:

```bash
. ./scripts/bootstrap/run_by_docker.sh
```

todo
Or if you want this options run:

### Lite node vs Archive node
```bash
# --name <NAME> # (optional) show your node name in telemetry
# --telemetry-url <ADDR> # (optional) telemetry address
# --rpc # (optional) expose rpc to external requests
# --archive # (optional) if you want to run archive node (it needs about 1.5 TB storage)
. ./scripts/bootstrap/run_by_docker.sh --name your-disired-name --rpc --archive --telemetry-url "wss://telemetry.polkadot.io/submit/ 0"
```

---

## Run a Subnet

todo
Checkout [Jungo Echo Subnet](https://github.com/jungoai/jungo-echo-subnet) example.

---

Expand Down Expand Up @@ -102,10 +129,9 @@ This command will start the single-node development chain with non-persistent st
./target/release/jungochain-node --dev
```

Purge the development chain's state:

Running debug with logs.
```bash
./target/release/jungochain-node purge-chain --dev
RUST_LOG=runtime=debug ./target/release/jungochain-node -- --nocapture
```

Start the development chain with detailed logging:
Expand All @@ -114,11 +140,6 @@ Start the development chain with detailed logging:
RUST_BACKTRACE=1 ./target/release/jungochain-node -ldebug --dev
```

Running debug with logs.
```bash
RUST_LOG=runtime=debug ./target/release/jungochain-node -- --nocapture
```

Running individual tests
```bash
SKIP_WASM_BUILD=1 \
Expand Down Expand Up @@ -181,7 +202,7 @@ is ran. The following commands show how to use a newly created folder as our db
mkdir my-chain-state

# Use of that folder to store the chain state
./target/release/node-template --dev --base-path ./my-chain-state/
./target/release/jungochain-node --dev --base-path ./my-chain-state/

# Check the folder structure created inside the base path after running the chain
ls ./my-chain-state
Expand All @@ -199,50 +220,6 @@ to interact with your chain. [Click
here](https://polkadot.js.org/apps/#/explorer?rpc=ws://localhost:9944) connecting the Apps to your
local node template.

### Multi-Node Local Testnet

If you want to see the multi-node consensus algorithm in action, refer to our
[Simulate a network tutorial](https://docs.substrate.io/tutorials/build-a-blockchain/simulate-network/).

## Template Structure

A Substrate project such as this consists of a number of components that are spread across a few
directories.

### Node Capabilities

A blockchain node is an application that allows users to participate in a blockchain network.
Substrate-based blockchain nodes expose a number of capabilities:

- Networking: Substrate nodes use the [`libp2p`](https://libp2p.io/) networking stack to allow the
nodes in the network to communicate with one another.
- Consensus: Blockchains must have a way to come to
[consensus](https://docs.substrate.io/main-docs/fundamentals/consensus/) on the state of the
network. Substrate makes it possible to supply custom consensus engines and also ships with
several consensus mechanisms that have been built on top of
[Web3 Foundation research](https://research.web3.foundation/en/latest/polkadot/NPoS/index.html).
- RPC Server: A remote procedure call (RPC) server is used to interact with Substrate nodes.

**Directory structure**

There are several files in the [`node`](./node/) directory. Make a note of the following important files:

- [`chain_spec.rs`](./node/src/chain_spec.rs): A
[chain specification](https://docs.substrate.io/main-docs/build/chain-spec/) is a
source code file that defines a Substrate chain's initial (genesis) state. Chain specifications
are useful for development and testing, and critical when architecting the launch of a
production chain. Take note of the `development_config` and `testnet_genesis` functions, which
are used to define the genesis state for the local development chain configuration. These
functions identify some
[well-known accounts](https://docs.substrate.io/reference/command-line-tools/subkey/)
and use them to configure the blockchain's initial state.
- [`service.rs`](./node/src/service.rs): This file defines the node implementation. Take note of
the libraries that this file imports and the names of the functions it invokes. In particular,
there are references to consensus-related topics, such as the
[block finalization and forks](https://docs.substrate.io/main-docs/fundamentals/consensus/#finalization-and-forks)
and other [consensus mechanisms](https://docs.substrate.io/main-docs/fundamentals/consensus/#default-consensus-models)
such as Aura for block authoring and GRANDPA for finality.

### CLI help

After the node has been [built](#build), refer to the embedded documentation to learn more about the
Expand All @@ -252,77 +229,9 @@ capabilities and configuration parameters that it exposes:
./target/release/jungochain-node --help
```

### Runtime

In Substrate, the terms
"runtime" and "state transition function"
are analogous - they refer to the core logic of the blockchain that is responsible for validating
blocks and executing the state changes they define. The Substrate project in this repository uses
[FRAME](https://docs.substrate.io/main-docs/fundamentals/runtime-intro/#frame) to construct a
blockchain runtime. FRAME allows runtime developers to declare domain-specific logic in modules
called "pallets". At the heart of FRAME is a helpful
[macro language](https://docs.substrate.io/reference/frame-macros/) that makes it easy to
create pallets and flexibly compose them to create blockchains that can address
[a variety of needs](https://substrate.io/ecosystem/projects/).

Review the [FRAME runtime implementation](./runtime/src/lib.rs) included in this template and note
the following:

- This file configures several pallets to include in the runtime. Each pallet configuration is
defined by a code block that begins with `impl $PALLET_NAME::Config for Runtime`.
- The pallets are composed into a single runtime by way of the
[`construct_runtime!`](https://crates.parity.io/frame_support/macro.construct_runtime.html)
macro, which is part of the core
FRAME Support [system](https://docs.substrate.io/reference/frame-pallets/#system-pallets) library.

### Pallets

The runtime in this project is constructed using many FRAME pallets that ship with the
[core Substrate repository](https://github.com/paritytech/substrate/tree/master/frame) and a
template pallet that is [defined in the `pallets`](./pallets/template/src/lib.rs) directory.

A FRAME pallet is compromised of a number of blockchain primitives:

- Storage: FRAME defines a rich set of powerful
[storage abstractions](https://docs.substrate.io/main-docs/build/runtime-storage/) that makes
it easy to use Substrate's efficient key-value database to manage the evolving state of a
blockchain.
- Dispatchables: FRAME pallets define special types of functions that can be invoked (dispatched)
from outside of the runtime in order to update its state.
- Events: Substrate uses [events and errors](https://docs.substrate.io/main-docs/build/events-errors/)
to notify users of important changes in the runtime.
- 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/node-template --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/node-template --dev --ws-external
# Purge the local dev chain
./scripts/docker_run.sh ./target/release/node-template purge-chain --dev
## For Subnet Development

# Check whether the code is compilable
./scripts/docker_run.sh cargo check
```
-->
Checkout [Jungo SDK](https://github.com/jungoai/jungo-sdk).

## License
The MIT License (MIT)
Expand Down
122 changes: 122 additions & 0 deletions scripts/bootstrap/run_by_docker.sh
Original file line number Diff line number Diff line change
@@ -0,0 +1,122 @@
# Initialize variable defaults
args=()
node_name="nodeX" # default node name
archive_opt=""
rpc_methods_opt=""
unsafe_rpc_external_opt=""
telemetry_url_opt=""

# Parse arguments
while [[ $# -gt 0 ]]; do
case "$1" in
--name)
if [[ -n "$2" && $2 != "--" ]]; then
node_name="$2"
shift 2 # Remove both the option and its value
else
echo "Error: --option requires a value."
exit 1
fi
;;
--archive)
archive_opt="--state-pruning archive"
shift # Remove the current argument
;;
--rpc)
rpc_methods_opt="--rpc-methods Safe"
unsafe_rpc_external_opt="--unsafe-rpc-external"
shift # Remove the current argument
;;
--telemetry-url)
if [[ -n "$2" && $2 != "--" ]]; then
telemetry_url_opt="--telemetry-url $2"
shift 2 # Remove both the option and its value
else
echo "Error: --option requires a value."
exit 1
fi
;;
--)
shift # Remove the '--' delimiter
args+=("$@") # Collect the remaining arguments
break
;;
*)
echo "Unknown argument: $1"
exit 1
;;
esac
done

# Variables
chain_image="ghcr.io/jungoai/jungochain:0.1.0-devnet"
chain_type="devnet"
base_path_="$HOME/.jungochain" #"/var/lib/jungochain"
address="0.0.0.0"
port=30333
rpc_port=9944
boot_nodes="/ip4/52.14.41.79/tcp/30333/p2p/12D3KooWPVLR5YFa6nBcXU4wi7KJtwSx1VGuYQ4gzS3QTLkTFhSm"

base_path="$base_path_/$node_name"
chain_spec="$base_path_/$chain_type"_spec.json
chain_spec_raw="${chain_spec%.*}"_raw.json

log_max_size="10m"
log_max_file=10

mkdir -p "$base_path_"

export_spec() {
docker run -v "$base_path_":"$base_path_" "$chain_image" \
build-spec \
--disable-default-bootnode \
--chain "$chain_type" \
> "$chain_spec"
}

spec_to_raw() {
docker run -v "$base_path_":"$base_path_" "$chain_image" \
build-spec \
--chain "$chain_spec" \
--raw \
--disable-default-bootnode \
> "$chain_spec_raw"
}

export_raw_spec() {
export_spec
spec_to_raw
}

run_() {
docker run \
--network host \
-v "$base_path_:$base_path_" \
--log-driver json-file \
--log-opt max-size="$log_max_size" \
--log-opt max-file="$log_max_file" \
"$chain_image" \
\
--base-path "$base_path" \
--chain "$chain_spec_raw" \
--name "$node_name" \
--public-addr /ip4/"$address"/tcp/"$port" \
--port "$port" \
--rpc-port "$rpc_port" \
--rpc-cors all \
--rpc-max-connections 5000 \
$rpc_methods_opt \
$unsafe_rpc_external_opt \
$archive_opt \
$telemetry_url_opt \
--bootnodes "$boot_nodes" \
--unsafe-force-node-key-generation

}

run() {
export_raw_spec
run_
}

run

0 comments on commit b2a57d6

Please sign in to comment.