diff --git a/README.md b/README.md index 0ba8a120..e7cadfb9 100644 --- a/README.md +++ b/README.md @@ -2,17 +2,13 @@ [![Test Status](https://travis-ci.org/getamis/istanbul-tools.svg?branch=feature%2Fadd-travis-yml)](https://travis-ci.org/getamis/istanbul-tools) +`istanbul-tools` contains tools for configuring Istanbul BFT (IBFT) network, integration tests for both IBFT Geth and Quorum, and load testing utilities for IBFT Geth. -Istanbul tools contain tools for configuring `extraData` field for istanbul BFT (IBFT) network, integration tests for both IBFT Geth and Quorum, and load testing utilities for IBFT Geth. - -Command line tools ---- - -### Build istanbul command line tools +## Build istanbul command line interface ``` -$ make istanbul -$ build/bin/istanbul +$ make +$ ./build/bin/istanbul --help NAME: istanbul - the istanbul-tools command line interface @@ -22,22 +18,22 @@ USAGE: COMMANDS: extra Istanbul extraData manipulation - genesis Istanbul genesis block generator - help, h Shows a list of commands or help for one command + setup Setup your Istanbul network in seconds + help, h Print this message GLOBAL OPTIONS: --help, -h show help COPYRIGHT: - Copyright 2017 The Amis Authors - + Copyright 2017 The AMIS Authors ``` -#### Extra data tool +### `extra` subcommand -Genesis extra-data encoder and decoder library for Istanbul consensus. - -istanbul-tools is used to generate extra-data field of genesis due to extra-data is combined signer vanity with RLP encoded `Istanbul extra data`. The `Istanbul extra data` struct is defined as follows: +
+Click here to expand + +`extra` helps generate RLP-encoded extra data in `ExtraData` field of the genesis block. Extra data is composed of signer vanity and `IstanbulExtra`. `IstanbulExtra` is defined as follows: ```go type IstanbulExtra struct { @@ -47,11 +43,10 @@ type IstanbulExtra struct { } ``` -Please note: The `Seal`, and `CommittedSeal` is not considered in genesis block. +**Note**: `Seal` and `CommittedSeal` are not considered in genesis block. -##### Extra data subcommand -``` -$ build/bin/istanbul extra +```sh +$ ./build/bin/istanbul extra NAME: istanbul extra - Istanbul extraData manipulation @@ -68,23 +63,25 @@ OPTIONS: ``` -##### Extra data example +#### `extra` examples -###### Encode command +##### `encode` subcommand + +Encode the given file to extra data. -Encode the given file to `Encoded Istanbul extra-data` ``` -$ build/bin/istanbul extra encode --config ./cmd/istanbul/example/config.toml +$ ./build/bin/istanbul extra encode --config ./cmd/istanbul/example/config.toml OUTPUT: Encoded Istanbul extra-data: 0x0000000000000000000000000000000000000000000000000000000000000000f89af85494475cc98b5521ab2a1335683e7567c8048bfe79ed9407d8299de61faed3686ba4c4e6c3b9083d7e2371944fe035ce99af680d89e2c4d73aca01dbfc1bd2fd94dc421209441a754f79c4a4ecd2b49c935aad0312b8410000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000c0 ``` -###### Decode command +##### `decode` subcommand + +Decode extra data from the given input. -Decode extraData for the given input ``` -$ build/bin/istanbul extra decode --extradata 0x0000000000000000000000000000000000000000000000000000000000000000f89af85494475cc98b5521ab2a1335683e7567c8048bfe79ed9407d8299de61faed3686ba4c4e6c3b9083d7e2371944fe035ce99af680d89e2c4d73aca01dbfc1bd2fd94dc421209441a754f79c4a4ecd2b49c935aad0312b8410000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000c0 +$ ./build/bin/istanbul extra decode --extradata 0x0000000000000000000000000000000000000000000000000000000000000000f89af85494475cc98b5521ab2a1335683e7567c8048bfe79ed9407d8299de61faed3686ba4c4e6c3b9083d7e2371944fe035ce99af680d89e2c4d73aca01dbfc1bd2fd94dc421209441a754f79c4a4ecd2b49c935aad0312b8410000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000c0 OUTPUT: vanity: 0x0000000000000000000000000000000000000000000000000000000000000000 @@ -95,45 +92,56 @@ validator: 0xdc421209441a754f79c4a4ecd2b49c935aad0312 seal: 0x0000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000 ``` -##### Genesis subcommand -Genesis subcommand helps generating genesis.json. When `--nodes --verbose` flags are given, a `static-nodes.json` template as well as the validators' node keys, public keys, and addresses are generated. +
+ +### `setup` subcommand + +
+Click here to exapand + +When `--nodes --verbose` flags are given, a `static-nodes.json` template as well as the validators' node keys, public keys, and addresses are generated. + **Note**: the generated `static-nodes.json` template are set with IP `0.0.0.0`, please make according change to match your environment. -###### Genesis tool example +#### `setup` examples + ``` - build/bin/istanbul genesis --num 4 --nodes --verbose ytlin@yt-macbook +$ ./build/bin/istanbul setup --num 4 --nodes --verbose +validators { - "Address": "0xf1b727db98587ee93ad3ac20631b0efb0fa5cef6", - "Nodekey": "b623862cdb98efc608f5fb169718fe043fe5e5fe3e16ab24d4c4629dc32d28bf", - "NodeInfo": "enode://49f11d1996c18e329857b84a0e1432145ff85f8709b57b3c79236eed824625b599f7f11904110319491c286c1ae3792095b39498e3465658914e5e3128c7dfe2@0.0.0.0:30303?discport=0" + "Address": "0x5e5d0e2b80005a7e1f93044ddd64b2df0f8e488d", + "Nodekey": "e5f9b868651ea8f4883744f2753ead9dfcdf7b1d8a96de0e733f406938dca1eb", + "NodeInfo": "enode://8759a8a6921be78ec4e66ec77ae26ba9b3b1a51d1f83b16683c6f25e5a1d95a4de2c5bf4c2c05e1b984fae440236d96063efe933425df72659ee9de824cda6e1@0.0.0.0:30303?discport=0" } { - "Address": "0x1ebbedef9eebcaaac2aaaa078a79fea83f6b3256", - "Nodekey": "075fc12664d3a1ad0ab6f79d4a48f66e4c67ed80253a63a6b69931d4801c95c9", - "NodeInfo": "enode://071cad2c4cdbdf2946b47e65e0053c257c4f67a57b86c4cb26490c5f606be318df66e71fc4850fd22f097de3f8cca56ccb2e8669da02c4e2d6bb4abb017e76f8@0.0.0.0:30303?discport=0" + "Address": "0x1b706dd850229813ee7c4002cd2fedc91380bb5a", + "Nodekey": "2c13ee666b2ce617bf1e0d7fe7c8f058be27ea3a1aaabbfc63570a65f0bdae38", + "NodeInfo": "enode://40dd1e7ba45e5bcd242420986d9d03133ce49399c6197e43254d523e94f547532d4c47c8aaba4b000c5a718568a48013b035c86f3ed8b13248888a15a76761c1@0.0.0.0:30303?discport=0" } { - "Address": "0xb490b19f328ec61e8d333e7781996561ee5c4210", - "Nodekey": "4f5a57880196264bc1789bf050a3e7e2227f76ed3dd7d84542ba2eb8e418666b", - "NodeInfo": "enode://457eef0b80276c48e5e630edd96c0e670733e58f088a5cb2150519ec1f50446b1d06e781c1bdc51e5b2f038427a2baf215f24d3340e31ec1bd22c10bdf00a6e0@0.0.0.0:30303?discport=0" + "Address": "0xdfdf27987b042bb3706d3a7c4b60e80a645744de", + "Nodekey": "8bbf54eace8738f9d3ee90d5b949951f43d89acdb4b883d9188a141bdcd0153e", + "NodeInfo": "enode://d188378b3eef56584b8ebd3da3ad579d39d23511943573cdeae5b8a37b5df22c369bf8900c4f42a9d4d5e55bc3cd357f319de8f833db3232295be22c8accc006@0.0.0.0:30303?discport=0" } { - "Address": "0x1be6bcd71ce0c73d44a2726cf364f4d57c3ee508", - "Nodekey": "d05b431163372cf123ffe7fec6774cfe7f758ca5c7dcaadbb2d2a8d7f5a4c2df", - "NodeInfo": "enode://c9f5ced64a0f2c96b99d8df148f9be07b56a7f4d773c3bca981c7247d6fc4e75c61a09ccb55f5d8c95fbad16c1515ce1d9b2b42c7f2991308ba2e090d3448633@0.0.0.0:30303?discport=0" + "Address": "0x5950b8f849daf1a78e119648c79111721353df59", + "Nodekey": "9179c038483a2547c39f77f121065231d84a9c8d9bd044e1ddc19f653a23c751", + "NodeInfo": "enode://d855be48593e6f2dd6201334e9381a2f01dac4a847385a393b1f664503b7b7020326e9f3f84f2d5713bf360d16566ed2b84d7df0b8b8313a7a4c4cf087ccfe27@0.0.0.0:30303?discport=0" } -=========================================================== + +static-nodes.json [ - "enode://49f11d1996c18e329857b84a0e1432145ff85f8709b57b3c79236eed824625b599f7f11904110319491c286c1ae3792095b39498e3465658914e5e3128c7dfe2@0.0.0.0:30303?discport=0", - "enode://071cad2c4cdbdf2946b47e65e0053c257c4f67a57b86c4cb26490c5f606be318df66e71fc4850fd22f097de3f8cca56ccb2e8669da02c4e2d6bb4abb017e76f8@0.0.0.0:30303?discport=0", - "enode://457eef0b80276c48e5e630edd96c0e670733e58f088a5cb2150519ec1f50446b1d06e781c1bdc51e5b2f038427a2baf215f24d3340e31ec1bd22c10bdf00a6e0@0.0.0.0:30303?discport=0", - "enode://c9f5ced64a0f2c96b99d8df148f9be07b56a7f4d773c3bca981c7247d6fc4e75c61a09ccb55f5d8c95fbad16c1515ce1d9b2b42c7f2991308ba2e090d3448633@0.0.0.0:30303?discport=0" + "enode://8759a8a6921be78ec4e66ec77ae26ba9b3b1a51d1f83b16683c6f25e5a1d95a4de2c5bf4c2c05e1b984fae440236d96063efe933425df72659ee9de824cda6e1@0.0.0.0:30303?discport=0", + "enode://40dd1e7ba45e5bcd242420986d9d03133ce49399c6197e43254d523e94f547532d4c47c8aaba4b000c5a718568a48013b035c86f3ed8b13248888a15a76761c1@0.0.0.0:30303?discport=0", + "enode://d188378b3eef56584b8ebd3da3ad579d39d23511943573cdeae5b8a37b5df22c369bf8900c4f42a9d4d5e55bc3cd357f319de8f833db3232295be22c8accc006@0.0.0.0:30303?discport=0", + "enode://d855be48593e6f2dd6201334e9381a2f01dac4a847385a393b1f664503b7b7020326e9f3f84f2d5713bf360d16566ed2b84d7df0b8b8313a7a4c4cf087ccfe27@0.0.0.0:30303?discport=0" ] -=========================================================== + +genesis.json { "config": { "chainId": 2017, @@ -148,23 +156,23 @@ Genesis subcommand helps generating genesis.json. When `--nodes --verbose` flags } }, "nonce": "0x0", - "timestamp": "0x59cdfa14", - "extraData": "0x0000000000000000000000000000000000000000000000000000000000000000f89af85494f1b727db98587ee93ad3ac20631b0efb0fa5cef6941ebbedef9eebcaaac2aaaa078a79fea83f6b325694b490b19f328ec61e8d333e7781996561ee5c4210941be6bcd71ce0c73d44a2726cf364f4d57c3ee508b8410000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000c0", + "timestamp": "0x5a093aac", + "extraData": "0x0000000000000000000000000000000000000000000000000000000000000000f89af854945e5d0e2b80005a7e1f93044ddd64b2df0f8e488d941b706dd850229813ee7c4002cd2fedc91380bb5a94dfdf27987b042bb3706d3a7c4b60e80a645744de945950b8f849daf1a78e119648c79111721353df59b8410000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000c0", "gasLimit": "0x47b760", "difficulty": "0x1", "mixHash": "0x63746963616c2062797a616e74696e65206661756c7420746f6c6572616e6365", "coinbase": "0x0000000000000000000000000000000000000000", "alloc": { - "1be6bcd71ce0c73d44a2726cf364f4d57c3ee508": { + "1b706dd850229813ee7c4002cd2fedc91380bb5a": { "balance": "0x446c3b15f9926687d2c40534fdb564000000000000" }, - "1ebbedef9eebcaaac2aaaa078a79fea83f6b3256": { + "5950b8f849daf1a78e119648c79111721353df59": { "balance": "0x446c3b15f9926687d2c40534fdb564000000000000" }, - "b490b19f328ec61e8d333e7781996561ee5c4210": { + "5e5d0e2b80005a7e1f93044ddd64b2df0f8e488d": { "balance": "0x446c3b15f9926687d2c40534fdb564000000000000" }, - "f1b727db98587ee93ad3ac20631b0efb0fa5cef6": { + "dfdf27987b042bb3706d3a7c4b60e80a645744de": { "balance": "0x446c3b15f9926687d2c40534fdb564000000000000" } }, @@ -175,31 +183,50 @@ Genesis subcommand helps generating genesis.json. When `--nodes --verbose` flags ``` ``` -build/bin/istanbul genesis --help - +$ ./build/bin/istanbul setup --help NAME: - istanbul genesis - Istanbul genesis block generator + istanbul setup - Setup your Istanbul network in seconds USAGE: - istanbul genesis [command options] [arguments...] + istanbul setup [command options] [arguments...] + +DESCRIPTION: + This tool helps generate: + + * Genesis block + * Static nodes for all validators + * Validator details + + for Istanbul consensus. + OPTIONS: --num value Number of validators (default: 0) - --nodes Print static-nodes.json - --verbose Print more information + --nodes Print static nodes template + --verbose Print validator details ``` -Integration tests ---- -### Istanbul BFT Geth Integration tests -[Test specification](https://github.com/getamis/istanbul-tools/wiki/Istanbul-BFT-Test-Specification) -[Source code](https://github.com/getamis/istanbul-tools/tree/develop/tests/functional) +
-### Istanbul BFT Quorum Integration tests -[Test specification](https://github.com/getamis/istanbul-tools/wiki/Istanbul-BFT-on-Quorum-Test-Specification) -[Source code](https://github.com/getamis/istanbul-tools/tree/develop/tests/quorum/functional) +## Testing +
+Click here to expand + +### Integration tests + +#### Istanbul BFT Geth Integration tests + +* [Test specification](https://github.com/getamis/istanbul-tools/wiki/Istanbul-BFT-Test-Specification) +* [Source code](https://github.com/getamis/istanbul-tools/tree/develop/tests/functional) + +#### Istanbul BFT Quorum Integration tests + +* [Test specification](https://github.com/getamis/istanbul-tools/wiki/Istanbul-BFT-on-Quorum-Test-Specification) +* [Source code](https://github.com/getamis/istanbul-tools/tree/develop/tests/quorum/functional) + +### Load tests -Load tests ---- [Test specification](https://github.com/getamis/istanbul-tools/wiki/Istanbul-BFT-Benchmarking) + +
\ No newline at end of file