wrkoracle

README

WRKOracle

The official Unification WRKChain Oracle software for recording WRKChain block header hashes to Mainchain

Build and installation

Prerequisites

Go 1.13+ is required to install the WRKOracle binary

Install go by following the official docs. Once Go is installed, set your $PATH environment variable:

$ mkdir -p $HOME/go/bin
$ echo "export PATH=$PATH:$(go env GOPATH)/bin">>$HOME/.bash_profile
$ source $HOME/.bash_profile

Build

The build Make target can be used to build. The binary will be output to ./build/wrkoracle:

make build

Install

Use:

make install

to install the wrkoracle binary into your $GOPATH/bin

Run:

wrkoracle version --long

to verify it has installed correctly

Initialisation

First, you will need to import a valid Mainchain account key into the WrkOracle keyring. This can be either a new key:

wrkoracle keys add my_wrkoracle_acc

or by importing a key from an existing Mnemonic:

wrkoracle keys add my_wrkoracle_acc --recover

In either case, the account will need sufficient UND to run the Oracle and submit hashes to Mainchain.

WRKOracle must then be initialised with default values by running:

wrkoracle init [wrkchain_type]

E.g.

wrkoracle init geth

This will create a skeleton configuration file in $HOME/.und_wrkoracle/config/config.toml as follows:

broadcast-mode = "block"
chain-id = ""
frequency = "60"
from = ""
hash1 = "ReceiptHash"
hash2 = "TxHash"
hash3 = "Root"
indent = true
keyring-backend = "os"
mainchain-rest = ""
node = ""
output = "json"
parent-hash = true
trust-node = false
wrkchain-id = ""
wrkchain-rpc = ""
wrkchain-type = "geth"

Configuration options

The configuration values can be set in $HOME/.und_wrkoracle/config/config.toml, or passed to the binary at runtime as --flags (e.g. --chain-id).

• broadcast-mode: should remain as block, so that wrkoracle waits for the Tx to be processed in a Mainchain block. Required
• chain-id: The chain ID of Mainchain hashes are being submitted to, e.g. UND-Mainchain-DevNet, UND-Mainchain-TestNet, or UND-Mainchain-MainNet Required
• frequency: frequency in seconds that the WRKOracle should poll your WRKChain for the latest block header and submit the hashes to Mainchain. Required
• from: default account that should be used by WRKOracle to sign the transactions, as named when importing the account above, e.g. my_wrkoracle_acc. Required
• hash1, hash2, hash3: optional values mapped to various header hashes, depending on the WRKChain type hashes to Mainchain. See section Hash mapping below. If left empty, no value will be submitted.
• parent-hash: whether or not to optionally submit the WRKChain block header parent hash. Required
• mainchain-rest: The REST server for Mainchain, e.g. https://rest-testnet.unification.io. Required
• node: Mainchain node to broadcast Txs to, e.g. tcp://localhost:26656 if you are running you own local full Mainchain node. Required
• trust-node: Trust connected full node (don't verify proofs for responses). Required
• wrkchain-id: The integer ID of your WRKChain, as given when the WRKChain was registered on Mainchain. Required
• wrkchain-rpc: The RPC node where WRKOracle can query your WRKChain, e.g. http://127.0.0.1:7545, tcp://172.25.0.3:26661 etc.. Required

Running in automated mode

Once your WRKOracle has been configured with the options outlined above, it can run automatically and poll your WRKChain according to the defined frequency, submitting the latest WRKChain block header hashes to Mainchain:

wrkoracle run

WRKOracle will output its status as follows:

starting 2020-03-04 14:43:41.580232302 +0000 GMT
polling WRKChain for latest block
Get block for WRKChain 'wrkchain1', type 'geth' at http://127.0.0.1:7545
Got WRKChain block
WRKChain Height: 61
WRKChain Block Hash: 0x81a23fe7c73711260bebae8b027a6d0897f305407fdb13e6ed0a4effdd2d6e74
WRKChain Parent Hash: 0xe3cdf99657d23461ee590477eb1aec1873b52824910e5369964039757defffdc
WRKChain Hash1: 0x56e81f171bcc55a6ff8345e692c0f86e5b48e01b996cadc001622fb5e363b421
WRKChain Hash2: 0x56e81f171bcc55a6ff8345e692c0f86e5b48e01b996cadc001622fb5e363b421
WRKChain Hash3: 0xe534373922c7a6e23ba0a96bcdf53ade135ad7117b27cc9b0706c3e02360e653
recording latest WRKChain block
Generate msg
Broadcasting Tx and waiting for response...
WRKChain header hash recording fee: 1000000000nund
gas estimate: 140275
Tx Hash: D1F138682C7CB49A67E777CF40B9E242D5C89F754781BF6EDAE78918B3080996
Success! Recorded in Mainchain Block #2737
Gas used: 92202
Done. Next poll due at 2020-03-04 14:44:41.580299426 +0000 GMT
-----------------------------------

Submitting single block headers

Individual WRKChain block headers can be submitted manually. This is useful if you wish to submit historical data to Mainchain:

wrkoracle record [height]

E.g.

wrkoracle record 2424

The result will be output:

getting WRKChain 'wrkchain1' block 2424 and recording
Get block for WRKChain 'wrkchain1', type 'geth' at http://127.0.0.1:7545
Got WRKChain block
WRKChain Height: 2424
WRKChain Block Hash: 0x4fee5d6dd69b21b37c0923d1c1ded45ace4c94af3d1f18a423ea2e25052c25d6
WRKChain Parent Hash: 0x8ae2443997e24ec247116efe275af3cae7bbe1a62071cf52c43cd0e233fac551
WRKChain Hash1: 0x56e81f171bcc55a6ff8345e692c0f86e5b48e01b996cadc001622fb5e363b421
WRKChain Hash2: 0x56e81f171bcc55a6ff8345e692c0f86e5b48e01b996cadc001622fb5e363b421
WRKChain Hash3: 0x7cab995324db9a8556416274bd3367ec385bd3c8643e95052eab60a8e9537681
Generate msg
Broadcasting Tx and waiting for response...
WRKChain header hash recording fee: 1000000000nund
gas estimate: 140275
Tx Hash: 4EAFE4B59198AB4F34A8167FA83042AA1D501A1F2B3A192B8F5496F2DE92E0A3
Success! Recorded in Mainchain Block #2789
Gas used: 92202

Hash mapping

The Hash1, Hash2 and Hash3 are optional values that can be submitted to Mainchain, and are initially mapped by WRKOracle during initialisation to some default values, depending on the WRKChain type.

The mapping can be configured in $HOME/.und_wrkoracle/config/config.toml by setting the corresponding entries for hash1, hash2 and hash3. Leaving the entries empty will result in the hashes being omitted from the WRKChain hash submission. The initialised defaults for each chain type are listed below.

geth based chains

For geth based WRKChains, WRKOracle supports the following three optional hashes to be submitted:

1. Header.ReceiptHash - Merkle root hash for the Receipts
2. Header.TxHash - Merkle root hash for the Tx
3. Header.Root - Merkle root hash for Root

By default during initialisation, WRKOracle maps them as followed:

hash1 = ReceiptHash
hash2 = TxHash
hash3 = Root

tendermint / cosmos based chains

For tendermint and cosmos based WRKChains, WRKOracle supports the following 7 optional hashes:

1. Block.Header.DataHash - MerkleRoot of transaction hashes in this block
2. Block.Header.AppHash - state after txs from the previous block
3. Block.Header.ValidatorsHash - validators for the current block
4. Block.Header.LastResultsHash - root hash of all results from the txs from the previous block
5. Block.Header.LastCommitHash - commit from validators from the last block
6. Block.Header.ConsensusHash - consensus params for current block
7. Block.Header.NextValidatorsHash - validators for the next block

By default during initialisation, WRKOracle maps the following hashes:

hash1 = DataHash
hash2 = AppHash
hash3 = ValidatorsHash