Skip to content

Latest commit

 

History

History
81 lines (53 loc) · 5.28 KB

README.md

File metadata and controls

81 lines (53 loc) · 5.28 KB
Raw

Simple App

Simple app is a Java application that runs a basic Sidechain Node, able to receive and send coins from/to the mainchain ("Forward" and "Backward transfers"). It does not come with any application-specific code (e.g. custom boxes or transactions); that logic can be easily added to Simple App, and implement that way a complete, blockchain based distributed application.

Simple App node(s) can also be run without a connection to mainchain.

Execution

You can run Simple App inside an IDE by just executing the SimpleApp class in the examples/simpleapp module.

Otherwise, to run SimpleApp outside the IDE:

  1. Build and package the project 
    mvn package
  2. Go to the project root directory and execute in a command line:
    • (Windows) 
      cd Sidechains-SDK\examples\simpleapp
java -cp ./target/sidechains-sdk-simpleapp-0.3.3.jar;./target/lib/* com.horizen.examples.SimpleApp <path_to_config_file>
    • (Linux) 
      cd ./Sidechains-SDK/examples/simpleapp
java -cp ./target/sidechains-sdk-simpleapp-0.3.3.jar:./target/lib/* com.horizen.examples.SimpleApp <path_to_config_file>
      On some Linux OSs during backward transfers certificates proofs generation a extremely big RAM consumption may happen, that will lead to the process force killing by the OS.

While we keep monitoring the memory footprint of the proofs generation process, we have verified that using Jemalloc library (version 3.x only) instead of Glibc keeps the memory consumption in check. Glibc starting from version 2.26 is affected by this issue. To check and fix this issue on Linux OS follow these steps:

  • Check your version of Glibc. To check your version of Glibc on Ubuntu, run the command ldd --version

  • Install Jemalloc library. Please remember that only version 3.x of the Jemalloc library is tested and will solve the issue. Jemalloc is available as apt package, just execute the command line: - sudo apt-get install libjemalloc1 (Ubuntu) - Locate the installation folder of the Jemalloc library. On Ubuntu 18.04 (64bit) the library should be located in this path: /usr/lib/x86_64-linux-gnu/libjemalloc.so.1 - After the installation, just run export LD_PRELOAD=/usr/lib/x86_64-linux-gnu/libjemalloc.so.1 before starting the sidechain node, or run the sidechain node adding LD_PRELOAD=/usr/lib/x86_64-linux-gnu/libjemalloc.so.1 at the beginning of the java command line as follows:

      ```
  LD_PRELOAD=/usr/lib/x86_64-linux-gnu/libjemalloc.so.1 java -cp ./target/sidechains-sdk-simpleapp-0.3.3.jar:./target/lib/* com.horizen.examples.SimpleApp <path_to_config_file>
  ```
   - In the folder `ci` you will find the script `run_sc.sh` to automatically check and use jemalloc library while starting the sidechain node.

Running Simple App isolated from Mainchain

You can use the predefined sc_settings.conf configuration file, which contains some genesis data that will start a node with a first mainchain block reference and some coins transferred to the sidechain.

Since there will be no real mainchain node running, with the mainchain block reference included by the genesis just made up, the sidechain will not receive any subsequent mainchain information; the sidecahin will run stand-alone, "isolated".

Such a configuration is useful to test a sidechain's logic and behaviour, without any interaction with the mainchain network.

Running Simple App connected to a Mainchain node

This configuration allows the full use of sidechain node functionalities, i.e. create new sidechains, synchronize a sidechain with the mainchain (i.e. mainchain block references are included in sidechain blocks), transfer coins from/to mainchain and vice versa. Please find here a detailed guide on how to setup up this complete configuration.

How to choose the address of the first forward transfers

The sc_create RPC method specifies two public keys, that are part of the Vrf and the ed25519 keypairs. To generate a new pair of secret-public keys, you can use the generatekey and generateVrfKey ScBootstrappingTool commands: e.g. generatekey {"seed":"myuniqueseed"} and generateVrfKey {"seed":"my seed"}

Then you can put the newly generated public keys as destinations in sc_create, and the secret ones into the configuration file, in the wallet.genesisSecrets section.

Please note: if you do not specify genesisSecrets properly, you will not see that balance in the wallet.

How to choose the secret in ScBootstrapping genesisinfo command

Just use a secret generated by the generatekey command.

Sidechain-related RPC commands in Mainchain

  1. sc_create - to create a new sidechain, please refer to example for more details.
  2. sc_send - to send a forward transfers to specific addresses in a sidechain.

For more info please check the Horizen Mainchain zen repository and guides.

Sidechain HTTP API

The node API address is specified in the configuration file, network.bindAddress section. The description of all basic API, with examples, is available as a simple web interface; just type network.bindAddress in any browser to access it.