From eb3bbbe369f0f847439348e6ce05f96e037d5400 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Niklas=20G=C3=B6gge?= Date: Thu, 23 Jul 2020 19:06:21 +0200 Subject: [PATCH] Update readme.md --- readme.md | 81 +++++++++++++++++++++++++++++-------------------------- 1 file changed, 43 insertions(+), 38 deletions(-) diff --git a/readme.md b/readme.md index 1cf597ef..2a02e1a0 100644 --- a/readme.md +++ b/readme.md @@ -1,4 +1,4 @@ -# utreexo +# Utreexo A dynamic hash based accumulator designed for the Bitcoin UTXO set @@ -8,70 +8,75 @@ Currently under active development. If you're interested and have questions, ch Logs for freenode are [here](http://gnusha.org/utreexo/) -### walkthrough +--- +## Walkthrough Here's how to get utreexo running to test out what it can do. This currently is testing/research level code and should not be expected to be stable or secure. But it also should work, and if it doesn't please report bugs! ---- +To demonstrate utreexo we went with a client-server model. We have made prebuild binaries to run utreexo on Linux, Mac and Windows available here: https://github.com/mit-dci/utreexo/releases but you can also build from source. -* first, get the Bitcoin blockchain. Try testnet as it's smaller. (you can get Bitcoin Core from http://github.com/bitcoin/bitcoin) +### Client +#### Build from source ``` -[ ...install bitcoin core ] -$ echo "testnet=1" > ~/.bitcoin/bitcoin.conf -$ bitcoind --daemon -[wait for testnet to sync] -$ du -h ~/.bitcoin/testnet3/blocks/ - 214M ~/.bitcoin/testnet3/blocks/index - 24G ~/.bitcoin/testnet3/blocks/ -[OK looks like it's there] -$ bitcoin-cli stop +$ go get github.com/mit-dci/utreexo +$ cd ~/go/src/github.com/mit-dci/utreexo/cmd/utreexoclient +$ go build ``` -* get utreexo code - +#### Run +Running the client can take a couple of hours (There are still lots of performance optimisations to be done to speed things up). +The client downloads blocks with inclusion proofs from the server and validates them. ``` -$ go get github.com/mit-dci/utreexo +$ ./utreexoclient +[the client is able to resume from where it left off. Use ctrl+c to stop it.] +[To resume, just do `/utreexoclient` again] ``` -* build utreexo +*There is a `host` flag to specify a different server and a `watchaddr` flag to specify the address that you want to watch. To view all options use the `help` flag* + +If you pause the client it will create the `pollardFile` which holds the accumulator roots. As an experiment you can copy this file to a different machine and resume the client at the height it was paused. +### Server +To try utreexo you do not need to run a server as we have a server set up for testing purposes which the client connects to by default. If you want to run your own server you can, see instructions below. + +#### Build from source ``` -$ cd ~/go/src/github.com/mit-dci/utreexo/cmd/ +$ go get github.com/mit-dci/utreexo +$ cd ~/go/src/github.com/mit-dci/utreexo/cmd/utreexoserver $ go build ``` -This will give you the `cmd` binary. +#### Run -`cmd` contains various commands that go from indexing the `blk*.dat` files from Bitcoin Core to building the Bridge Node and the Compact State Node. To view all the available commands and flags, just run `./cmd` by itself. - -First we need to organize the blocks in the `.dat` files, build a proof file and a db that keeps record of how long each transaction lasts until it is spent. - -First, the `genproofs` command builds all the block proofs for the blockchain and the db for how long a transaction lasts. +If you want to run a server you will need the Bitcoin blockchain. Try testnet as it's smaller. (you can get Bitcoin Core from http://github.com/bitcoin/bitcoin or https://bitcoin.org/en/download) ``` -$ cd ~/.bitcoin/testnet3/blocks -$ ./cmd genproofs -net=testnet # -net=testnet flag needed for testnet. Leave out for mainnet -[... takes time and builds block proofs] -[genproofs is able to resume from where it left off. Use ctrl+c to stop it.] -[To resume, just do `./cmd genproofs -net=testnet` again] +[ ...install bitcoin core ] +$ echo "testnet=1" > ~/.bitcoin/bitcoin.conf +$ bitcoind --daemon +[wait for testnet to sync] +$ du -h ~/.bitcoin/testnet3/blocks/ + 214M ~/.bitcoin/testnet3/blocks/index + 24G ~/.bitcoin/testnet3/blocks/ +[OK looks like it's there] +$ bitcoin-cli stop ``` +**Note:** bitcoind has to be stopped before running the server. -* `genproofs` should take a few hours. It does two things. First, it goes through the blockchain, maintains the full merkle forest, and saves proofs for each block to disk. Second, it saves each TXO and height with LevelDB to make a TXO time-to-live (basically how long each TXO lasts until it is spent) for caching purposes. This is what the bridge node and archive node would do in a real node. Next, you can run `cmd ibdsim -net=testnet`; it will perform IBD (initial block download) as a compact node which maintains only a reduced state, and accepts proofs (which are created in the `proof.dat` file during the previous step). - -After genproofs has generated the proofs, it will start a local server to serve the blocks to ibdsim. With genproofs running, run the following: +The server should take a few hours. It does two things. First, it goes through the blockchain, maintains the full merkle forest, and saves proofs for each block to disk. Second, it saves each TXO and height with LevelDB to make a TXO time-to-live (basically how long each TXO lasts until it is spent) for caching purposes. This is what the bridge node and archive node would do in a real node. ``` $ cd ~/.bitcoin/testnet3/blocks -$ ./cmd ibdsim -net=testnet # -net=testnet flag needed for testnet. Leave out for mainnet -[... takes time and does utreexo sync simulation] -[ibdsim is able to resume from where it left off. Use ctrl+c to stop it.] -[To resume, just do `./cmd ibdsim -net=testnet` again] +$ ./utreexoserver #path probably differs on your system +[... takes time and builds block proofs] +[the server is able to resume from where it left off. Use ctrl+c to stop it.] +[To resume, just do `./cmd genproofs -net=testnet` again] ``` -* `ibdsim` is the CSN node and it will call genproofs and ask for blocks with the Utreexo accumulator proofs. It will receive the proofs and validate the inclusion. +After the server has generated the proofs, it will start a local server to serve the blocks to clients. -Note that your folders or filenames might be different, but this should give you the idea and work on default Linux/golang setups. If you've tried this and it doesn't work and you'd like to help out, you can either fix the code or documentation so that it works and make a pull request, or open an issue describing what doesn't work. +**Note**: your folders or filenames might be different, but this should give you the idea and work on default Linux/golang setups. If you've tried this and it doesn't work and you'd like to help out, you can either fix the code or documentation so that it works and make a pull request, or open an issue describing what doesn't work. ### Windows walkthrough