• English
  • Русский

# Custom Blockchain

This article explains how to setup custom Waves blockchain to be used for experimental activities.

For most tasks such as getting familiar with blockchain, sending transactions and developing smart contracts its enough to deploy one node with custom blockchain in Docker.

To setup private blockchain with multiple nodes proceed with Setup Jar Node With Custom Blockchain section.

# Deploy Node With Custom Blockchain in Docker

The easiest way to setup custom Waves blockchain with one private node is to install docker and run Docker container with Waves custom blockchain node.

# Setup Jar Node With Custom Blockchain

You can run one or multiple Jar-nodes to setup custom blockchain. For that, create genesis block and specify blockchain parameters in node configuration file.

# Step 1

The node installation is supported in OpenJDK versions 8, 11, and 17.

If you don't have OpenJDK installed, install OpenJDK 11

  • On Ubuntu:

    sudo apt-get update
sudo apt-get install openjdk-11-jre-headless

  • On macOS:

    brew install [email protected]

  • On Windows: as described in the documentation.

# Step 2

Download the latest version of jar node (waves-all-{version}.jar file).

# Step 3

Create genesis.example.conf file with genesis block parameters in the JAR file location directory.

Example:

genesis-generator
{
  network-type: "L"  # your custom network identifier byte
  initial-balance: 10000000000000000  # initial balance in wavelets
  average-block-delay: 60s # average block delay
  # timestamp: 1500635421931 # current time by default
  # base-target: 999 # variable that adjusts the average block delay; calculated automatically if not specified
  
  # the sum of shares should be = initial-balance
  distributions = 
  [
    { 
      seed-text: "foo0"
      nonce: 0
      amount: 10000000000000000
    }
  ]

  # pre-activated-features = [1,2,15] # by default all features will be activated from height 0
}

# Step 4

Run the genesis block generator command:

java -cp waves-all-{version}.jar com.wavesplatform.GenesisBlockGenerator genesis.example.conf

The result will be written to the genesis.conf file (you can use arbitrary file name), and it will look as follows:

Addresses:

 Seed text:           foo0
 Seed:                3csAfH
 Account seed:        58zgAnBg775J6NKd4qVtfeX3m5TBMeizHNY9STvm2N87
 Private account key: FYLXp1ecxQ6WCPD4axTotHU9RVfPCBLfSeKx1XSCyvdT
 Public account key:  GbGEY3XVc2ohdv6hQBukVKSTQyqP8rjQ8Kigkj6bL57S
 Account address:     3JfE6tjeT7PnpuDQKxiVNLn4TJUFhuMaaT5
 ===
Settings:
waves {
  blockchain.custom {
    address-scheme-character = L
    functionality {
      pre-activated-features = null # undefines all previously defined pre-activated features
      pre-activated-features = {1 = 0, 2 = 0, 3 = 0, 4 = 0, 5 = 0, 6 = 0, 7 = 0, 8 = 0, 9 = 0, 10 = 0, 11 = 0, 12 = 0, 13 = 0, 14 = 0, 15 = 0}
    }
    genesis {
      average-block-delay = 60s
      base-target = 122
      timestamp = 1612954141684 # 2021-02-10T10:49:01.684Z
      block-timestamp = 1612954141684 # 2021-02-10T10:49:01.684Z
      signature = "3k64TQfLUkLWjCWkajPHfLovWoKpYgH6sTJrymog5nA3PZfqo9Qa1dKtRsDmvavULgEkMGACsxH2eCsnrua4JX9F"
      initial-balance = 10000000000000000
      transactions = [
        {recipient = "3JfE6tjeT7PnpuDQKxiVNLn4TJUFhuMaaT5", amount = 10000000000000000}
      ]
    }
  }

#  wallet {
#    seed = 3csAfH
#    password =
#  }
}

The Addresses section lists the accounts to which the assets are distributed in the genesis block, the waves section will be used later in Step 5.

# Step 5

In the JAR file location directory create *.conf file with any name (for example waves-custom-network.conf) and edit it with a text editor. Use example configuration file for reference.

See Node Configuration article for more information about Waves configuration file.

If the directory parameter is not redefined, the default node directory is:

*nix macOS Windows
$XDG_DATA_HOME/waves-custom-<character>* or $HOME/.local/share/waves-custom-<character>* $HOME/Library/Application Support/waves-custom-<character>* %LOCALAPPDATA%/waves-custom-<character>*

Paste the content generated in Step 4 in configuration file. Instead of pasting manually, you can write include "genesis.conf", where the genesis.conf is a filename from the Step 4.

Set waves.wallet parameters. Use Seed (Seed text in base58) value generated with genesis generator tool in Step 4 as the value of waves.wallet.seed parameter.

In waves.network section, set port, known-peers (list the nodes of your custom network), node-name, and declared-address parameters.

To use the REST API for your node, set enable, port, and api-key-hash (see the API Key article) parameters in waves.rest-api section.

The waves.blockchain.custom.functionality section makes it possible to customize the functionality of your blockchain, including:

  • Enable/disable features on your node by modifying the pre-activated-features parameter. Supported features are described in the Features article.
  • Set start points for blockchain functions (validations) activated by timestamp or height instead of feature mechanism.
  • Specify the addresses each receiving 1/3 of the block reward in the dao-address and xtn-buyback-address parameters. If the address (or both) is not specified, the corresponding share of block reward goes to the block generator.

# Step 6

Start your custom node with the following command:

java -jar waves-all-{version}.jar waves-custom-network.conf

Note: You can run an existing node (deb or jar) with your custom configuration file manually.

# Add Nodes to Your Network

You can add more nodes to your network using waves.network.known-peers parameter. Specify the address and port of the existing node with the same network parameters like "127.0.0.1:6860". If you are making several nodes locally, then do not forget to change for the new nodes the network port waves.network.port, the API port waves.rest-api.port, directory for the data waves.directory and wallet seed waves.wallet.seed.

# Setup Other Services

You can setup your custom blockchain with other services such as:

Activation protocol
Node REST API