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 asblock
, so thatwrkoracle
waits for the Tx to be processed in a Mainchain block. Requiredchain-id
: The chain ID of Mainchain hashes are being submitted to, e.g.UND-Mainchain-DevNet
,UND-Mainchain-TestNet
, orUND-Mainchain-MainNet
Requiredfrequency
: frequency in seconds that the WRKOracle should poll your WRKChain for the latest block header and submit the hashes to Mainchain. Requiredfrom
: default account that should be used by WRKOracle to sign the transactions, as named when importing the account above, e.g.my_wrkoracle_acc
. Requiredhash1
,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. Requiredmainchain-rest
: The REST server for Mainchain, e.g. https://rest-testnet.unification.io. Requirednode
: Mainchain node to broadcast Txs to, e.g.tcp://localhost:26656
if you are running you own local full Mainchain node. Requiredtrust-node
: Trust connected full node (don't verify proofs for responses). Requiredwrkchain-id
: The integer ID of your WRKChain, as given when the WRKChain was registered on Mainchain. Requiredwrkchain-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:
I[2020-03-11|12:55:36.872] Check WRKChain metadata pkg=mainchain
I[2020-03-11|12:55:36.880] Start running WRKOracle pkg=oracle
I[2020-03-11|12:55:36.880] start poll pkg=oracle time=2020-03-11T12:55:36.880866909Z
I[2020-03-11|12:55:36.880] polling WRKChain for latest block pkg=oracle
I[2020-03-11|12:55:36.881] Get block for WRKChain pkg=wrkchains moniker=wrkchain1 type=geth rpc=http://127.0.0.1:7545
I[2020-03-11|12:55:36.893] Got WRKChain block pkg=wrkchains
I[2020-03-11|12:55:36.893] WRKChain Height pkg=wrkchains height=13289
I[2020-03-11|12:55:36.893] WRKChain Block Hash pkg=wrkchains blockhash=0x349723088c3fa5a8871c31e256cd2a8ff5e1c19d75c5e76d48b85e28c1038f0d
I[2020-03-11|12:55:36.893] WRKChain Parent Hash pkg=wrkchains parenthash=0xb9673407d6ee07ccbb3d8f7808666b879ec79a1e423d6cdae05c486223a4fc00
I[2020-03-11|12:55:36.893] WRKChain Hash1 pkg=wrkchains ref=ReceiptHash value=0x56e81f171bcc55a6ff8345e692c0f86e5b48e01b996cadc001622fb5e363b421
I[2020-03-11|12:55:36.893] WRKChain Hash2 pkg=wrkchains ref=TxHash value=0x56e81f171bcc55a6ff8345e692c0f86e5b48e01b996cadc001622fb5e363b421
I[2020-03-11|12:55:36.893] WRKChain Hash3 pkg=wrkchains ref=Root value=0xcf4a880479b49b6439dd833b27a387d58aff0d97df68d1c31e40d9bc2f814b7d
I[2020-03-11|12:55:36.897] recording latest WRKChain block pkg=oracle
I[2020-03-11|12:55:36.897] Generate msg pkg=mainchain
I[2020-03-11|12:55:36.897] Broadcasting Tx and waiting for response... pkg=mainchain
I[2020-03-11|12:55:36.897] WRKChain header hash recording fee pkg=mainchain fee=1000000000nund
I[2020-03-11|12:55:36.911] gas estimate: 147430 pkg=mainchain
I[2020-03-11|12:55:41.880] Tx broadcast pkg=mainchain hash=3C0AFAFC23E061677391E31495658F5388F1A6815A99FF2A680C682398FFABDB
I[2020-03-11|12:55:41.880] Success! Recorded in Mainchain Block pkg=mainchain height=2531
I[2020-03-11|12:55:41.881] Gas used: pkg=mainchain gas=96972
I[2020-03-11|12:55:41.881] end poll. Next poll due: pkg=oracle due=2020-03-11T12:55:46.880958102Z
I[2020-03-11|12:55:41.881] ----------------------------------- pkg=oracle
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:
I[2020-03-11|12:56:32.424] Check WRKChain metadata pkg=mainchain
I[2020-03-11|12:56:32.427] getting requested WRKChain block header and recording pkg=oracle moniker=wrkchain1 height=12222
I[2020-03-11|12:56:32.427] Get block for WRKChain pkg=wrkchains moniker=wrkchain1 type=geth rpc=http://127.0.0.1:7545
I[2020-03-11|12:56:32.444] Got WRKChain block pkg=wrkchains
I[2020-03-11|12:56:32.444] WRKChain Height pkg=wrkchains height=12222
I[2020-03-11|12:56:32.444] WRKChain Block Hash pkg=wrkchains blockhash=0x30e0ddcb301abc5e4312a3f84d4b8dc184d47b88d21d75e2247b2bee4affb824
I[2020-03-11|12:56:32.444] WRKChain Parent Hash pkg=wrkchains parenthash=0x2cb59e0daeaac6372f7205e8dd32a6e9bf64ccadd7a1dc85823e9cc6d9a04a08
I[2020-03-11|12:56:32.444] WRKChain Hash1 pkg=wrkchains ref=ReceiptHash value=0x56e81f171bcc55a6ff8345e692c0f86e5b48e01b996cadc001622fb5e363b421
I[2020-03-11|12:56:32.444] WRKChain Hash2 pkg=wrkchains ref=TxHash value=0x56e81f171bcc55a6ff8345e692c0f86e5b48e01b996cadc001622fb5e363b421
I[2020-03-11|12:56:32.444] WRKChain Hash3 pkg=wrkchains ref=Root value=0xea0d716b09464a350b67f13001e67ab04518a58ba7f745f67078693698a47e34
I[2020-03-11|12:56:32.446] Generate msg pkg=mainchain
I[2020-03-11|12:56:32.446] Broadcasting Tx and waiting for response... pkg=mainchain
I[2020-03-11|12:56:32.446] WRKChain header hash recording fee pkg=mainchain fee=1000000000nund
I[2020-03-11|12:56:32.451] gas estimate: 140335 pkg=mainchain
I[2020-03-11|12:56:35.492] Tx broadcast pkg=mainchain hash=1F0A5DD144D7B6F616552E5461F81769674700B9707D22EF380A9447E0D63881
I[2020-03-11|12:56:35.492] Success! Recorded in Mainchain Block pkg=mainchain height=2541
I[2020-03-11|12:56:35.492] Gas used: pkg=mainchain gas=92242
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.
Note: Neither Mainchain or WRKOracle currently keep any internal records regarding what
is mapped onto the hash1
, hash2
and hash3
values at submission time. It is up to the
WRKChain and WRKOracle operators to keep track of this information externally so that any
validation process can compare the correct hash values. This is especially important if the
hash mapping is changed at any point during the life of the WRKChain. For example, from
WRKChain block height 100,000, the operator may wish to change hash1
submissions from
ReceiptHash
to UncleHash
, in which case the operator should keep a record of this
and update any validation processes accordingly.
geth
based chains
For geth
based WRKChains, WRKOracle supports the following 5 optional hashes
to be submitted:
Header.ReceiptHash
- Merkle root hash for the ReceiptsHeader.TxHash
- Merkle root hash for the TxHeader.Root
- Merkle root hash for RootHeader.UncleHash
- Uncle HashHeader.MixDigest
By default during initialisation, WRKOracle maps them as follows:
hash1
= ReceiptHash
hash2
= TxHash
hash3
= Root
tendermint
/ cosmos
based chains
For tendermint
and cosmos
based WRKChains, WRKOracle supports the following 7 optional
hashes:
Block.Header.DataHash
- MerkleRoot of transaction hashes in this blockBlock.Header.AppHash
- state after txs from the previous blockBlock.Header.ValidatorsHash
- validators for the current blockBlock.Header.LastResultsHash
- root hash of all results from the txs from the previous blockBlock.Header.LastCommitHash
- commit from validators from the last blockBlock.Header.ConsensusHash
- consensus params for current blockBlock.Header.NextValidatorsHash
- validators for the next block
By default during initialisation, WRKOracle maps the following hashes:
hash1
= DataHash
hash2
= AppHash
hash3
= ValidatorsHash