Skip to content

Commit

Permalink
Clean and split up README (#297)
Browse files Browse the repository at this point in the history 
Co-authored-by: Cirrus Gai <[email protected]>
  • Loading branch information
@vitsalis @gitferry
vitsalis and gitferry authored Feb 2, 2023
1 parent 3ac1222 commit f039053
Show file tree
Hide file tree
Showing 4 changed files with 170 additions and 141 deletions.
161 changes: 20 additions & 141 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,162 +1,41 @@
# Babylon

## Requirements
Bringing Bitcoin security to Cosmos and beyond.

- Go 1.19
[![Website](https://badgen.net/badge/icon/website?label=)](https://babylonchain.io)
[![Whitepaper](https://badgen.net/badge/icon/whitepaper?label=)](https://arxiv.org/abs/2207.08392)
[![Twitter](https://badgen.net/badge/icon/twitter?icon=twitter&label)](https://twitter.com/babylon_chain)
[![Discord](https://badgen.net/badge/icon/discord?icon=discord&label)](https://discord.gg/babylonchain)

## Development requirements
## Build and install

- Go 1.19
- Docker
The babylond application based on the [Cosmos SDK](https://github.com/cosmos/cosmos-sdk) is the main application of the Babylon network.
This repository is used to build the Babylon core application to join the Babylon network.

## Building
### Requirements
To build and install, you need to have Go 1.19 available.
Follow the instructions on the [Golang page](https://go.dev/doc/install) to do that.

To build the chain, simply:
To build the binary:
```console
make build
```

This will lead to the creation of a `babylond` executable under the `build`
directory.
The binary will then be available at `./build/babylond` .

## Installing

To build the chain and install a babylon executable:
To install:
```console
make install
```

## Testing

```console
make test
```

## Running a node

The following commands assume that the `babylond` executable has been
installed. If the repository was only built, then `./build/babylond` should be
used in its place.

### Generating the node configuration
The configuration for a single node can be created through the `testnet`
command. While the testnet command can create an arbitrary number of nodes that
communicate on a testnet, here we focus on the setup of a single node.
```console
babylond testnet \
--v 1 \
--output-dir ./.testnet \
--starting-ip-address 192.168.10.2 \
--keyring-backend test \
--chain-id chain-test
```

The flags specify the following:
- `--output-dir <testnet-dir>`: Specifies that the testnet files should
reside under this directory.
- `--v <N>`: Leads to the creation of `N` nodes, each one residing under the
`<testnet-dir>/node{i}`. In this case `i={0..N-1}`.
- `--starting-ip-address <ip>`: Specifies the IP address for the nodes. For example,
`192.168.10.2` leads to the first node running on `192.168.10.2:46656`, the
second one on `192.168.10.3:46656` etc.
- `--keyring-backend {os,file,test}`: Specifies the backend to use for the keyring. Available
choices include `os`, `file`, and `test`. We use `test` for convenience.
- `--chain-id`: An identifier for the chain. Useful when perrforming operations
later.

In this case, we generated a single node. If we take a look under `.testnet`:
```console
$ ls .testnet
gentxs node0
```

The `gentxs` directory contains the genesis transactions. It contains
transactions that assign bbn tokens to a single address that is defined for each
node.

The `node0` directory contains the the following,
```console
$ ls .testnet/node0/babylond
config data key_seed.json keyring-test
```

A brief description of the contents:
- `config`: Contains the configuration files for the node.
- `data`: Contains the database storage for the node.
- `key_seed.json`: Seed to generate the keys maintained by the keyring.
- `keyring-test`: Contains the test keyring. This directory was created because
we provided the `--keyring-backend test` flag. The `testnet` command, creates
a validator node named `node{i}` (depends on the node name), and assigns
bbn tokens to it through a transaction written to `.testnet/gentxs/node{i}.json`.
The keys for this node can be pointed to by the `node{i}` name.

### Running the node
```console
babylond start --home ./.testnet/node0/babylond
```

### Logs

The logs for a particular node can be found under
`.testnets/node{id}/babylond/babylond.log`.

### Performing queries
## Documentation

After building a node and starting it, you can perform queries.
```console
babylond --home .testnet/node{i}/babylond/ --chain-id <chain-id> \
query <module-name> <query-name>
```
For the most up-to-date documentation please visit [docs.babylonchain.io](https://docs.babylonchain.io)

For example, in order to get the hashes maintained by the `btcligthclient`
module:
```console
$ babylond --home .testnet/node0/babylond/ --chain-id chain-test query btclightclient hashes
## Joining the testnet

hashes:
- 00000000000000000002bf1c218853bc920f41f74491e6c92c6bc6fdc881ab47
pagination:
next_key: null
total: "1"
```

### Submitting transactions

After building a node and running it, one can send transactions as follows:
```console
babylond --home .testnet/node{i}/babylond --chain-id <chain-id> \
--keyring-backend {os,file,test} --fees <amount><denom> \
--from <key-name> --broadcast-mode {sync,async,block} \
tx <module-name> <tx-name> [data]
```
Please follow the instructions on the [Joining the Testnet documentation page](https://docs.babylonchain.io/docs/testnet/overview).

The `--fees` flag specifies the amount of fees that we are willing to pay and
the denomination and the `--from` flag denotes the name of the key that we want
to use to sign the transaction (i.e. from which account we want this
transaction to happen). The `--broadcast-mode` specifies how long we want to
wait until we receive a response from the CLI: `async` means immediately,
`sync` means after the transaction has been validated through `CheckTx`,
and `block` means after the transaction has been processed by the next block.
## Contributing

For example, in the `btclightclient` module, in order
to submit a header, one should:
```console
babylond --home .testnet/node0/babylond --chain-id chain-test \
--keyring-backend test --fees 100bbn \
--from node0 --broadcast-mode block \
tx btclightclient insert-header <header-hex>
```

## Running a multi-node testnet

We provide support for running a multi-node testnet using Docker. To build it

```console
make localnet-start
```

The corresponding node directories can be found under `.testnets`
```console
$ ls .testnets
gentxs node0 node1 node2 node3
```
The [docs](./docs) directory contains the necessary information on how to get started using the babylond executable for development purposes.
10 changes: 10 additions & 0 deletions docs/README.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,10 @@
# Babylon Developer Docs

This page contains documentation targeted at individuals that want to contribute to the Babylon repository.

For user-facing docs, visit the [Babylon documentation page](https://docs.babylonchain.io).

## Contents

- [Development Requirements](./dev-reqs.md)
- [Running a node for testing purposes](./run-node.md)
5 changes: 5 additions & 0 deletions docs/dev-reqs.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
## Development Requirements

To develop the Babylon repository, the following requirements are recommended:
- Golang version 1.19
- Docker
135 changes: 135 additions & 0 deletions docs/run-node.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,135 @@
## Running a node

The following commands assume that the `babylond` executable has been
installed. If the repository was only built, then `./build/babylond` should be
used in its place.

### Generating the node configuration
The configuration for a single node can be created through the `testnet`
command. While the `testnet` command can create an arbitrary number of nodes that
communicate on a testnet, here we focus on the setup of a single node.
```console
babylond testnet \
--v 1 \
--output-dir ./.testnet \
--starting-ip-address 192.168.10.2 \
--keyring-backend test \
--chain-id chain-test
```

The flags specify the following:
- `--output-dir <testnet-dir>`: Specifies that the testnet files should
reside under this directory.
- `--v <N>`: Leads to the creation of `N` nodes, each one residing under the
`<testnet-dir>/node{i}`. In this case `i={0..N-1}`.
- `--starting-ip-address <ip>`: Specifies the IP address for the nodes. For example,
`192.168.10.2` leads to the first node running on `192.168.10.2:46656`, the
second one on `192.168.10.3:46656` etc.
- `--keyring-backend {os,file,test}`: Specifies the backend to use for the keyring. Available
choices include `os`, `file`, and `test`. We use `test` for convenience.
- `--chain-id`: An identifier for the chain. Useful when perrforming operations
later.

In this case, we generated a single node. If we take a look under `.testnet`:
```console
$ ls .testnet
gentxs node0
```

The `gentxs` directory contains the genesis transactions. It contains
transactions that assign bbn tokens to a single address that is defined for each
node.

The `node0` directory contains the the following,
```console
$ ls .testnet/node0/babylond
config data key_seed.json keyring-test
```

A brief description of the contents:
- `config`: Contains the configuration files for the node.
- `data`: Contains the database storage for the node.
- `key_seed.json`: Seed to generate the keys maintained by the keyring.
- `keyring-test`: Contains the test keyring. This directory was created because
we provided the `--keyring-backend test` flag. The `testnet` command, creates
a validator node named `node{i}` (depends on the node name), and assigns
bbn tokens to it through a transaction written to `.testnet/gentxs/node{i}.json`.
The keys for this node can be pointed to by the `node{i}` name.

### Running the node
```console
babylond start --home ./.testnet/node0/babylond
```

### Logs

The logs for a particular node can be found under
`.testnets/node{id}/babylond/babylond.log`.

### Performing queries

After building a node and starting it, you can perform queries.
```console
babylond --home .testnet/node{i}/babylond/ --chain-id <chain-id> \
query <module-name> <query-name>
```

For example, in order to get the hashes maintained by the `btcligthclient`
module:
```console
$ babylond --home .testnet/node0/babylond/ --chain-id chain-test query btclightclient hashes

hashes:
- 00000000000000000002bf1c218853bc920f41f74491e6c92c6bc6fdc881ab47
pagination:
next_key: null
total: "1"
```

### Submitting transactions

After building a node and running it, one can send transactions as follows:
```console
babylond --home .testnet/node{i}/babylond --chain-id <chain-id> \
--keyring-backend {os,file,test} --fees <amount><denom> \
--from <key-name> --broadcast-mode {sync,async,block} \
tx <module-name> <tx-name> [data]
```

The `--fees` flag specifies the amount of fees that we are willing to pay and
the denomination and the `--from` flag denotes the name of the key that we want
to use to sign the transaction (i.e. from which account we want this
transaction to happen). The `--broadcast-mode` specifies how long we want to
wait until we receive a response from the CLI: `async` means immediately,
`sync` means after the transaction has been validated through `CheckTx`,
and `block` means after the transaction has been processed by the next block.

For example, in the `btclightclient` module, in order
to submit a header, one should:
```console
babylond --home .testnet/node0/babylond --chain-id chain-test \
--keyring-backend test --fees 100bbn \
--from node0 --broadcast-mode block \
tx btclightclient insert-header <header-hex>
```

## Running a multi-node testnet

We provide support for running a multi-node testnet using Docker. To build it

```console
make localnet-start
```

The corresponding node directories can be found under `.testnets`
```console
$ ls .testnets
gentxs node0 node1 node2 node3
```

## Testing

```console
make test
```

0 comments on commit f039053

Please sign in to comment.