From 614236423e3d9e22d3abeeadabe55df67c5733c3 Mon Sep 17 00:00:00 2001 From: Roy Ben Abraham Date: Wed, 24 Nov 2021 14:24:54 +0700 Subject: [PATCH 1/3] Updated docs/README.md with missing parts from README.md --- docs/README.md | 66 +++++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 62 insertions(+), 4 deletions(-) diff --git a/docs/README.md b/docs/README.md index 1afc7fc..ab30588 100644 --- a/docs/README.md +++ b/docs/README.md @@ -162,11 +162,10 @@ If you want to save the blockchain to host, run: docker run -v ~/ml-blockchain:/tmp/ml-core -t mintlayer-core ``` - ## Create a chain specification -In the preceding example, we used `--chain local` which is a predefined "chain spec" that has Alice and Bob specified as validators along with many other useful defaults. -In this example we will create a two-node network using our own custom chain specification. The process generalizes to more nodes in a straightforward manner. +In the preceding example, we used `--chain=Testnet1Spec.json` which is a predefined chain spec provided by Mintlayer. +In this example we will create a network using our own custom chain specification. Rather than writing our chain spec completely from scratch, we'll just make a few modifications to the one we used before. To start, we need to export the chain spec to a file named @@ -242,7 +241,66 @@ the proper storage keys. Finally share the `customSpecRaw.json` with your all the other validators in the network. -**Note**: Because Rust -> Wasm optimized builds aren't reproducible, each person will get a slightly different Wasm blob which will break consensus if each participant generates the file themselves.For the curious, learn more about this issue in [this blog post](https://dev.to/gnunicorn/hunting-down-a-non-determinism-bug-in-our-rust-wasm-build-4fk1). +**Note**: Because Rust -> Wasm optimized builds aren't reproducible, each person will get a slightly different Wasm blob which will break consensus if each participant generates the file themselves. For the curious, learn more about this issue in [this blog post](https://dev.to/gnunicorn/hunting-down-a-non-determinism-bug-in-our-rust-wasm-build-4fk1). + +### Connect with Polkadot-JS Apps Front-end + +Once the node is running locally, you can connect it to the **Polkadot-JS Apps** front-end +to interact with your chain. [Click here](https://polkadot.js.org/apps/#/explorer?rpc=ws://localhost:9944) to connect your node. + +## Project Structure + +### Node + +- Networking: Mintlayer uses [libp2p](https://libp2p.io/) as its native networking stack for all inter-node communication. +- Bootnodes: Mintlayer has [bootnodes](https://github.com/mintlayer/core/blob/master/assets/bootnodes.json) that a new node will attempt to connect to, unless a specific node is specified by the user. +- Consensus: Mintlayer uses [AURA](https://docs.rs/sc-consensus-aura/0.9.0/sc_consensus_aura/) as its base consensus algorithm for the time being. There will be an update to introduce [DSA](https://www.mintlayer.org/docs/DSA-consensus-paper-draft.pdf) in the future. +- Finality: Since we are using AURA for consensus, we currently rely on [GRANDPA](https://docs.rs/sc-finality-grandpa/0.9.0/sc_finality_grandpa/) for finality. +- Chain Spec: You can find our chain specification in [chain_spec.rs](https://github.com/mintlayer/core/blob/master/node/src/chain_spec.rs). It defines the basics of the chain such as the genesis block and the bootnodes. +- Services: [service.rs](https://github.com/mintlayer/core/blob/master/node/src/service.rs) defines the node implementation itself. It is here you'll find the consensus setup. + +### Runtime + +For more information on what a [runtime](https://substrate.dev/docs/en/knowledgebase/getting-started/glossary#runtime) is follow the link. +Code in the runtime must be written in `no_std` Rust since it compiles to Wasm. + +- lib.rs: The main file in Mintlayer's runtime. Here you'll find the Mintlayer-specific code for block production such as the block production period. +- staking.rs: Mintlayer's staking implementation. + + +### Pallets + +Mintlayer relies on a host of Substrate pallets as well as a few Mintlayer-specific pallets: +- pp: The implementation of programmable pools on Mintlayer. These are essentially Wasm smart contracts. +- utxo: Mintlayer's UTXO system. + +### Libs + +The `libs` is home to code that Mintlayer relies on but isn't technically a pallet: +- chainscript: Mintlayer's Bitcoin script implementation. +- bech32: code for handling transactions with destinations encoded using bech32 + +### Testing + +Unit tests for particular modules are scattered throughout the codebase. +The `test` directory is home to Mintlayer's functional test framework, which includes system-level tests. Heavily based on Bitcoin's functional test framework. + +### Crypto +Currently, Mintlayer uses Schnorr signatures for crypto-related needs. We plan to move to our BLS implementation in the near future. + +### Contributing +[See this guide](https://github.com/mintlayer/core/blob/master/CONTRIBUTING.md) + +### Branches +The key branches of this repository are `master` and `staging`. + +`staging` is used as the development branch, while `master` is used for fully tested. + +To submit a fix or a feature, code your changes on a new branch based on `staging` and create a pull request. This will trigger CI checks and notify the Minlayer team that a new pull request is awaiting review. Once all CI checks have passed and the pull request has been reviewed and approved by a member of the Mintlayer team, the pull request can be merged into `staging`. + +Periodically, the Mintlayer team will merge `staging` into `master`. +Only a select few members of the Mintlayer team have push access to `master` + ## Firewall rules From 3e9fbf54dbb46180791968694e1e504cfe2f937b Mon Sep 17 00:00:00 2001 From: Roy Ben Abraham Date: Wed, 24 Nov 2021 14:49:27 +0700 Subject: [PATCH 2/3] README.md to point to docs/README.md --- README.md | 146 +----------------------------------------------------- 1 file changed, 1 insertion(+), 145 deletions(-) mode change 100644 => 120000 README.md diff --git a/README.md b/README.md deleted file mode 100644 index ef4383d..0000000 --- a/README.md +++ /dev/null @@ -1,145 +0,0 @@ -# Mintlayer core - -https://www.mintlayer.org/ - -For a more technical introduction to Mintlayer visit [our docs](https://docs.mintlayer.org/). - -A draft of the consensus paper can be found [here](https://www.mintlayer.org/docs/DSA-consensus-paper-draft.pdf). - -## Security issues -If you find an issue related to the security of Mintlayer then please contact us at security@mintlayer.org so we can address the issue. Mintlayer has a [bug bounty program](https://www.mintlayer.org/bug-bounties) so if your security issue is valid you are elligble for a reward paid in MLT. Do not disclose the security issue publicly until the core Mintlayer team has agreed the issue can be disclosed. See [SECURITY.md](https://github.com/mintlayer/core/blob/master/SECURITY.md) for more info. - -## Bugs -Non-security related bugs should be opened as [issues](https://github.com/mintlayer/core/issues/new) in the core Mintlayer repo. Give as much detail as possible. If you want to fix a bug then see our guidelines for [contributing](https://github.com/mintlayer/core/blob/master/CONTRIBUTING.md). - -## How to build and run Mintlayer - -### Rust Setup - -First, complete the [basic Rust setup instructions](https://github.com/mintlayer/core/blob/master/doc/rust-setup.md). - -### Run - -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: - -```sh -cargo build --release -``` -or - -`cargo build` to build a debug version - -to purge the local chain run `./target/release/mintlayer-core purge-chain --dev` - -### Docs - -Once the project has been built, the following command can be used to explore all parameters and -subcommands: - -```sh -./target/release/mintlayer-core -h -``` - -You can also find docs in the docs directory and within the directory for a specific pallet or lib. - - -### Single-Node Development Chain - -This command will start the single-node development chain with persistent state: - -```bash -./target/release/mintlayer-core --dev -``` - -Purge the development chain's state: - -```bash -./target/release/mintlayer-core purge-chain --dev -``` - -Start the development chain with detailed logging: - -```bash -RUST_LOG=debug RUST_BACKTRACE=1 ./target/release/mintlayer-core -lruntime=debug --dev -``` - -### Connect with Polkadot-JS Apps Front-end - -Once the node is running locally, you can connect it with **Polkadot-JS Apps** front-end -to interact with your chain. [Click here](https://polkadot.js.org/apps/#/explorer?rpc=ws://localhost:9944) connecting the Apps to your local node. - -### Connect with Mintlayer's UI -TODO - -### Multi-Node Local Testnet - -If you want to see the multi-node consensus algorithm in action, refer to -[our Start a Private Network tutorial](https://substrate.dev/docs/en/tutorials/start-a-private-network/). - -## Project Structure - -### Node - -- Networking: Mintlayer uses [libp2p](https://libp2p.io/) as its native networking stack for all inter-node communication. -- Bootnodes: Mintlayer has [bootnodes](https://github.com/mintlayer/core/blob/master/assets/bootnodes.json) that a new node will attempt to boot to unless a specific node is specified by the user -- Consensus: Mintlayer uses [AURA](https://docs.rs/sc-consensus-aura/0.9.0/sc_consensus_aura/) as its base consensus algorithm for the time being. There will be an update to introduce [DSA](https://www.mintlayer.org/docs/DSA-consensus-paper-draft.pdf) in the future but DSA is still in development. -- Finality: Since we are using AURA for our consensus we currently rely on [GRANDPA](https://docs.rs/sc-finality-grandpa/0.9.0/sc_finality_grandpa/) for finality. -- Chain Spec: You can find our chain specification in [chain_spec.rs](https://github.com/mintlayer/core/blob/master/node/src/chain_spec.rs). It defines the basics of the chain such as the genesis block and the bootnodes. -- Services: [service.rs](https://github.com/mintlayer/core/blob/master/node/src/service.rs) defines the node implementation itself. It is here you'll find the consensus setup. - - -### Runtime - -For more information on what a [runtime](https://substrate.dev/docs/en/knowledgebase/getting-started/glossary#runtime) is follow the link. -Code in the runtime must be written in `no_std` Rust since it compiles to Wasm. - -- lib.rs: The main file in Mintlayer's runtime. Here you'll find the Mintlayer specific code for block production such as the block production period. -- staking.rs: Here you'll find Mintlayer's staking implementation. - - -### Pallets - -Mintlayer relies on a host of Substrate pallets and a few Mintlayer specific pallets. - -- pp: The implementation of programmable pools on Mintlayer. Essentially Wasm smart contracts -- utxo: Mintlayer's UTXO system - -### Libs - -Libs is home to code that is code that Mintlayer relies on but isn't technically a pallet. - -- chainscript: Mintlayer's bitcoin script implementation. -- bech32: code for handling transactions with destinations encoded using bech32 - -### Testing - -You'll find unit tests littered throughout the codebase but the test directory is home to the functional test framework which is heavily based on Bitcoin's functional test framework. - -### Crypto -As it stands Mintlayer uses Schnorr for all crypto-related things. There is a plan to move to our BLS implementation in the near future but this, as it stands, is a work in progress. - -### Contributing -[See this guide](https://github.com/mintlayer/core/blob/master/CONTRIBUTING.md) - -### Branches -The key branches are master and staging. Master is used for fully tested code, staging is used as the development branch. Fixes or features should be created on new branches branched from staging. A PR is then created to merge the branch into staging where it will require a review from a member of the Mintlayer team. To merge into master create a PR to merge staging to master, a review is required and CI will run. Only select people have push access to master. - -### Firewall rules - -The node uses TCP port 30333 for communications, this needs to be opened if you want to allow -inbound connections. - -Using UFW: -`sudo ufw allow 30333/tcp` - -Using iptables: -`sudo iptables -A INPUT -p tcp --dport 30333 -j ACCEPT` diff --git a/README.md b/README.md new file mode 120000 index 0000000..0e01b43 --- /dev/null +++ b/README.md @@ -0,0 +1 @@ +docs/README.md \ No newline at end of file From 44594ac7911ed843a2210a6a190e32c212cc2eea Mon Sep 17 00:00:00 2001 From: Roy Ben Abraham Date: Wed, 24 Nov 2021 15:40:52 +0700 Subject: [PATCH 3/3] Added sections on security and bugs --- docs/README.md | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/docs/README.md b/docs/README.md index ab30588..55b5515 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,5 +1,4 @@ - -# RUNNING +# Running ## Quick start Binaries can be found [here](https://github.com/mintlayer/core/releases). @@ -301,6 +300,11 @@ To submit a fix or a feature, code your changes on a new branch based on `stagin Periodically, the Mintlayer team will merge `staging` into `master`. Only a select few members of the Mintlayer team have push access to `master` +## Security issues +If you find an issue related to the security of Mintlayer then please contact us at security@mintlayer.org so we can address the issue. Mintlayer has a [bug bounty program](https://www.mintlayer.org/bug-bounties) so if your security issue is valid you are elligble for a reward paid in MLT. Do not disclose the security issue publicly until the core Mintlayer team has agreed the issue can be disclosed. See [SECURITY.md](https://github.com/mintlayer/core/blob/master/SECURITY.md) for more info. + +## Bugs +Non-security related bugs should be opened as [issues](https://github.com/mintlayer/core/issues/new) in the core Mintlayer repo. Give as much detail as possible. If you want to fix a bug then see our guidelines for [contributing](https://github.com/mintlayer/core/blob/master/CONTRIBUTING.md). ## Firewall rules