From 9ceac8c99140c225387ef23739c1768ffc976a03 Mon Sep 17 00:00:00 2001 From: catbref Date: Sat, 6 Feb 2021 10:59:31 +0000 Subject: [PATCH] Documentation updates --- AutoUpdates.md | 18 +++++++++++-- DATABASE.md | 12 ++++++--- README.md | 2 +- TestNets.md | 69 ++++++++++++++++++++++++++++++++++++++++++++++++++ 4 files changed, 95 insertions(+), 6 deletions(-) create mode 100644 TestNets.md diff --git a/AutoUpdates.md b/AutoUpdates.md index ccb441ca..e565fb06 100644 --- a/AutoUpdates.md +++ b/AutoUpdates.md @@ -1,5 +1,19 @@ # Auto Updates +## TL;DR: how-to + +* Assuming you are in git 'master' branch, at HEAD +* Shutdown local node if running +* Build auto-update download: `tools/build-auto-update.sh` - uploads auto-update file into new git branch +* Restart local node +* Publish auto-update transaction using *private key* for **non-admin** member of "dev" group: + `tools/publish-auto-update.sh non-admin-dev-member-private-key-in-base58` +* Wait for auto-update `ARBITRARY` transaction to be confirmed into a block +* Have "dev" group admins 'approve' auto-update using `tools/approve-auto-update.sh` + This tool will prompt for *private key* of **admin** of "dev" group +* A minimum number of admins are required for approval, and a minimum number of blocks must pass also. +* Nodes will start to download, and apply, the update over the next 20 minutes or so (see CHECK_INTERVAL in AutoUpdate.java) + ## Theory * Using a specific git commit (e.g. abcdef123) we produce a determinstic JAR with consistent hash. * To avoid issues with over-eager anti-virus / firewalls we obfuscate JAR using very simplistic XOR-based method. @@ -25,8 +39,8 @@ The same method is used to obfuscate and de-obfuscate: ## Typical download locations The git SHA1 commit hash is used to replace `%s` in various download locations, e.g.: -* https://github.com/QORT/qortal/raw/%s/qortal.update -* https://raw.githubusercontent.com@151.101.16.133/QORT/qortal/%s/qortal.update +* https://github.com/Qortal/qortal/raw/%s/qortal.update +* https://raw.githubusercontent.com@151.101.16.133/Qortal/qortal/%s/qortal.update These locations are part of the org.qortal.settings.Settings class and can be overriden in settings.json like: ``` diff --git a/DATABASE.md b/DATABASE.md index dc4eb6f1..8c53c640 100644 --- a/DATABASE.md +++ b/DATABASE.md @@ -4,10 +4,10 @@ You can examine your node's database using [HSQLDB's "sqltool"](http://www.hsqld It's a good idea to install "rlwrap" (ReadLine wrapper) too as sqltool doesn't support command history/editing. Typical command line for sqltool would be: -`rlwrap java -cp ${HSQLDB_JAR}:${SQLTOOL_JAR} org.hsqldb.cmdline.SqlTool --rcFile=${SQLTOOL_RC} qora` +`rlwrap java -cp ${HSQLDB_JAR}:${SQLTOOL_JAR} org.hsqldb.cmdline.SqlTool --rcFile=${SQLTOOL_RC} qortal` `${HSQLDB_JAR}` should be set with pathname where Maven downloaded hsqldb, -typically `${HOME}/.m2/repository/org/hsqldb/hsqldb/2.5.0/hsqldb-2.5.0.jar` +typically `${HOME}/.m2/repository/org/hsqldb/hsqldb/2.5.1/hsqldb-2.5.1.jar` `${SQLTOOL_JAR}` should be set with pathname where Maven downloaded sqltool, typically `${HOME}/.m2/repository/org/hsqldb/sqltool/2.5.0/sqltool-2.5.0.jar` @@ -25,10 +25,16 @@ Above `url` component `file:db/blockchain` assumes you will call `sqltool` from Another idea is to assign a shell alias in your `.bashrc` like: ``` -export HSQLDB_JAR=${HOME}/.m2/repository/org/hsqldb/hsqldb/2.5.0/hsqldb-2.5.0.jar +export HSQLDB_JAR=${HOME}/.m2/repository/org/hsqldb/hsqldb/2.5.1/hsqldb-2.5.1.jar export SQLTOOL_JAR=${HOME}/.m2/repository/org/hsqldb/sqltool/2.5.0/sqltool-2.5.0.jar alias sqltool='rlwrap java -cp ${HSQLDB_JAR}:${SQLTOOL_JAR} org.hsqldb.cmdline.SqlTool --rcFile=${SQLTOOL_RC}' ``` So you can simply type: `sqltool qortal` Don't forget to use `SHUTDOWN;` before exiting sqltool so that database files are closed cleanly. + +## Quick and dirty version + +With `sqltool-2.5.0.jar` and `qortal.jar` in current directory, and database in `db/` + +`java -cp qortal.jar:sqltool-2.5.0.jar org.hsqldb.cmdline.SqlTool --inlineRc=url=jdbc:hsqldb:file:db/blockchain` diff --git a/README.md b/README.md index f11a161c..9dd9ad60 100644 --- a/README.md +++ b/README.md @@ -9,4 +9,4 @@ - Create basic *settings.json* file: `echo '{}' > settings.json` - Run JAR in same working directory as *settings.json*: `java -jar target/qortal-1.0.jar` - Wrap in shell script, add JVM flags, redirection, backgrounding, etc. as necessary. -- Or use supplied example shell script: *run.sh* +- Or use supplied example shell script: *start.sh* diff --git a/TestNets.md b/TestNets.md new file mode 100644 index 00000000..6f8e92e6 --- /dev/null +++ b/TestNets.md @@ -0,0 +1,69 @@ +# How to build a testnet + +## Create testnet blockchain config + +- You can begin by copying the mainnet blockchain config `src/main/resources/blockchain.json` +- Insert `"isTestChain": true,` after the opening `{` +- Modify testnet genesis block + +### Testnet genesis block + +- Set `timestamp` to a nearby future value, e.g. 15 mins from 'now' + This is to give yourself enough time to set up other testnet nodes +- Retain the initial `ISSUE_ASSET` transactions! +- Add `ACCOUNT_FLAGS` transactions with `"andMask": -1, "orMask": 1, "xorMask": 0` to create founders +- Add at least one `REWARD_SHARE` transaction otherwise no-one can mint initial blocks! + You will need to calculate `rewardSharePublicKey` (and private key), + or make a new account on mainnet and use self-share key values +- Add `ACCOUNT_LEVEL` transactions to set initial level of accounts as needed +- Add `GENESIS` transactions to add QORT/LEGACY_QORA funds to accounts as needed + +## Testnet `settings.json` + +- Create a new `settings-test.json` +- Make sure to add `"isTestNet": true,` +- Make sure to reference testnet blockchain config file: `"blockchainConfig": "testchain.json",` +- It is a good idea to use a separate database: `"repositoryPath": "db-testnet",` +- You might also need to add `"bitcoinNet": "TEST3",` and `"litecoinNet": "TEST3",` + +## Other nodes + +- Copy `testchain.json` and `settings-test.json` to other nodes +- Alternatively, you can run multiple nodes on the same machine by: + * Copying `settings-test.json` to `settings-test-1.json` + * Configure different `repositoryPath` + * Configure use of different ports: + + `"apiPort": 22391,` + + `"listenPort": 22392,` + +## Starting-up + +- Start up at least as many nodes as `minBlockchainPeers` (or adjust this value instead) +- Probably best to perform API call `DELETE /peers/known` +- Add other nodes via API call `POST /peers ` +- Add minting private key to node(s) via API call `POST /admin/mintingaccounts ` + This key must have corresponding `REWARD_SHARE` transaction in testnet genesis block +- Wait for genesis block timestamp to pass +- A node should mint block 2 approximately 60 seconds after genesis block timestamp +- Other testnet nodes will sync *as long as there is at least `minBlockchainPeers` peers with an "up-to-date" chain` +- You can also use API call `POST /admin/forcesync ` on stuck nodes + +## Dealing with stuck chain + +Maybe your nodes have been offline and no-one has minted a recent testnet block. +Your options are: + +- Start a new testnet from scratch +- Fire up your testnet node(s) +- Force one of your nodes to mint by: + + Set a debugger breakpoint on Settings.getMinBlockchainPeers() + + When breakpoint is hit, change `this.minBlockchainPeers` to zero, then continue +- Once one of your nodes has minted blocks up to 'now', you can use "forcesync" on the other nodes + +## Tools + +- `qort` tool, but use `-t` option for default testnet API port (62391) +- `qort` tool, but first set shell variable: `export BASE_URL=some-node-hostname-or-ip:port` +- `qort` tool, but prepend with one-time shell variable: `BASE_URL=some-node-hostname-or-ip:port qort ......` +- `peer-heights`, but use `-t` option, or `BASE_URL` shell variable as above +