Installation and usage of the platform
Deployment of the platform in a private network¶
If your project or solution requires an independent blockchain, you can deploy your own blockchain network based on the Waves Enterprise platform. Our experts will help you configure the delivery of the platform to meet the needs of your project.
However, if you need to change any settings or configure the platform by yourself, this section provides a step-by-step guide for deploying and manual configuring the platform for a private network.
Note
The procedure to create node accounts, sign genesis block and *** when using GOST cryptography with PKI is described in the Deploying platform in a private network when using GOST cryptography with PKI section.
Creation of a node account¶
Create accounts for each node of your future network.
A node account includes an address and a key pair – a public key and a private key.
To generate the keys use the AccountsGeneratorApp utility, which is included in the generators package. You can download this package from the official repository of Waves Enterprise on GitHub by selecting the platform version you use.
The address and the public key will be shown on the command line during account creation using the generators utility. Node’s private key is written to the key storage file keystore.dat
, which is placed in the directory of the node.
Note
If you use GOST cryptography, node account generation is only possible with the operating system GUI and preinstalled CryptoPro components. In this case in UNIX-like systems (Linux, OSX) the key storage is by default located in the directory under /var/opt/cprocsp/keys/root/{username}
, where username
is the user name under which the generator was started.
To create an account, the accounts.conf
configuration file is used, which contains the account generation parameters. This file is located in the directory of each node.
To create a node account, go to its directory and place the downloaded generators.jar file into it. Then run it entering the accounts.conf
file as an argument:
java -jar generators-x.x.x.jar AccountsGeneratorApp accounts.conf
When you create a key pair, you can make up your own password to protect the node’s key pair. Later on, you can use it manually every time you start your node, or you can set global variables to ask for the password at system startup. See the description of the account generator for more information on how to use the password for a node key pair.
If you do not want to use a password to protect the key pair, press the Enter
key, leaving the field blank.
The following messages will be displayed as a result of the utility operation:
2021-02-09 16:03:18,940 INFO [main] c.w.g.AccountsGeneratorApp$ - 1 Address: 3Nu7MwQ1eSmDVwBzrN1nyzR8wqb2yzdUcyN; public key: F4ytnnS6H72ypCEpgNKYftGotpdX83ZxtWRX2dyGzDiA
2021-02-09 16:03:18,942 INFO [main] c.w.g.AccountsGeneratorApp$ - Generator done
A keystore.dat
file will be created in the directory of the node, which contains the account’s public key.
Platform configuration for operation in a private network¶
Following files are used for configuration of the platform:
The
node.conf
is the main configuration file of a node, which defines its operating principles and a set of options.The
api-key-hash.conf
is a configuration file for generatingapi-key-hash
andprivacy-api-key-hash
field values; it is used to configure node authorization when authorization byapi-key
hash method is selected. The guidelines for working with this configuration file will be given when configuring the authorization method of the node.
Note
You can setup node configuration parameters in a single file or in several files, including one file into another, for example:
include required(file("network.conf"))
include required(file("local.conf"))
Put the parameters common for all nodes in one file and set unique node parameters (such as owner-address
) in a separate file for each node.
Below is a step-by-step guide on how to manually configure a single node to work on a private network. If you have multiple nodes deployed on your network, you will need to perform similar configuration steps for each of them.
Step 1. General configuration of the platform
This step configures cryptography, consensus, Docker smart contract execution and mining. All the parameters required for this are located in the node.conf file.
Step 2. Precise platform configuration
This step configures the node’s gRPC and REST API tools, their authorization, TLS, and confidential data access groups. You may need these settings if you change the pre-set settings for your hardware or software configuration.
All necessary parameters are also located in the node.conf node configuration file. The api-key-hash.conf file is also used to configure authorization, which is necessary when selecting the authorization method by a given api-key string hash.
You will also need the keytool utility included in the Java SDK or JRE to configure TLS.
- Precise platform configuration: gRPC and REST API authorization
- Precise platform configuration: node gRPC and REST API configuration
- Precise platform configuration: TLS
- Precise platform configuration: confidential data groups configuration
- Precise platform configuration: anchoring
- Precise platform configuration: snapshot
- Precise platform configuration: node in the watcher mode
Full examples of configuration files to configure each node are given by here.
Obtaining a private network license and associated files¶
To deploy the platform on a private network, you need to get the kind of license that suits your purposes: trial, commercial or non-commercial.
Note
The opensource version of the Waves Enterprise blockchain platform does not require a license.
The license to run a node is tied to the node owner’s key. The license contains the address of the node for which the license is issued.
To discuss the details of your license, contact Waves Enterprise Sales at sales@wavesenterprise.com.
After that, you will be sent the license file. Place the file into the folder whose path is specified in the license-file
parameter of the node configuration file.
Before deployment, familiarize yourself with the blockchain platform system requirements.
Genesis block signing and starting the network¶
After configuring your network’s nodes, you must create a genesis block, the first private blockchain block which contains the transactions that determine a node’s initial balance and permissions.
A genesis block is signed by the GenesisBlockGenerator utility included in the generators package. It uses the node.conf
node configuration file that you set up as an argument:
java -jar generators-x.x.x.jar GenesisBlockGenerator node.conf
As a result, the utility fills the genesis-public-key-base-58
and signature
fields located in the genesis
block of the blockchain
section in the node configuration file with the generated values of the public key and signature of the genesis block.
Example:
genesis-public-key-base-58: "4ozcAj...penxrm"
signature: "5QNVGF...7Bj4Pc"
Note
When using GOST PKI cryptography, it is necessary that the CryptoPro components be installed before signing the genesis block. Also, before starting the GenesisBlockGenerator
you should prepare the node configuration file:
set the
node.crypto.type
parameter togost
;set the
node.crypto.pki.mode
parameter to one of the following values:on
ortest
;add the public key that will be used to sign the genesis block to the
network-participants
section and give it thepermissioner
role there; the public key that will be used to sign the genesis block is also created by the GeneratePkiKeypair generator. The key must be located in the key store on the PC from which the generator is launched.add the identifiers of the root trusted certificates to the configuration file; SHA-1 of certificate fingerprints are used as identifiers; list the network members certificates in DER format encoded to text using Base64; to do this, set the following parameters in the
node.blockchain.custom.genesis.pki
section:
trusted-root-fingerprints
– an array of Base64 strings listing SHA-1 of trusted root certificates fingerprints which should be in the JVM trust-store,
certificates
– an array of Base64 strings containing DER (binary) encoded certificate bodies.
It is also necessary to configure the GenesisBlockGenerator startup environment:
add the root certificates, which will be used as trusted certificates for blockchain validation, to the JVM trust-store. For this purpose you can use for instance the
keystore
utility built into the JVM. Here is an example of the utility call:keytool -import -trustcacerts -alias %CERT_ALIAS% -noprompt -storepass 'changeit' -keystore %PATH_TO_YOUR_JRE%/lib/security/cacerts -file cert-to-add.cer
Then run the GenesisBlockGenerator on the command line, specifying the path to the node configuration file you want to sign, and the alias (address) of the key that will be used to sign the genesis block. For example:
java -cp "generators-x.x.x.jar::./java-csp-5.0.R2/*" com.wavesenterprise.generator.GeneratorLauncher GenesisBlockGenerator ./node_alone.conf 3N1uZiamcpuTnRASi7L17vM8xhbC292UNgU
After signing the genesis block, the platform is fully configured and ready to run the network. You can launch it according to the instructions received from Waves Enterprise specialists.
Attachment of the client application to the private network¶
Once the network is up and running, attach a Waves Enterprise client application to it: with this, network users can send transactions to the blockchain, as well as broadcast and call smart contracts.
Open your browser and enter the network address of your computer with the deployed node software in the address bar.
Register to the web client using any valid email address and log in to the web client.
Open the Select address -> Create address page. To open the menu after the first login, you must enter the password that you entered when you registered your account.
Select Add address from the node keystore and click Continue.
Fill in the fields below. The required values are given in the
credentials.txt
file for the first node in the working directory.
Address name – specify the name of the node;
Node URL – specify the
http://<computer network address>/<node address>
value;Type of authorization on the node – select the authorization type you configured earlier: by JWT-token or by
api-key
;Blockchain address – specify the address of your node;
Key pair password – specify the password to the node key pair if you have set it up while generating the account.
Client description is provided in the article Client.