book: Add initial testnet user guide.

doc/src/SUMMARY.md

@@ -36,6 +36,7 @@
   	- [Network Protocol](misc/hashchain/network_protocol.md)
   - [darkwiki](misc/darkwiki.md)
   - [dnetview](misc/dnetview.md)
+- [Testnet Guide](testnet/guide.md)
 - [Learn](learn/learn.md)
   - [Research](learn/research.md)
   - [ZK explainer](learn/zk_explainer.md)

doc/src/testnet/guide.md

@@ -0,0 +1,195 @@
+DarkFi Testnet User Guide
+=========================
+
+This document presents a short user guide for the initial DarkFi
+testnet. In it, we cover basic setup of the `darkfid` node daemon,
+initializing a wallet, and interacting with the _money contract_,
+which provides infrastructure for payments and atomic swaps.
+
+Since this is still an early phase, we will not be installing any of
+the software system-wide. Instead, we'll be running all the commands
+from the git repository, so we're able to easily pull any necessary
+updates.
+
+
+## Compiling
+
+Refer to the main
+[README](https://github.com/darkrenaissance/darkfi/blob/master/README.md)
+file for instructions on how to install Rust and necessary deps.
+
+Once you have the repository in place, and everything is installed, we
+can compile the `darkfid` node and the `drk` wallet CLI:
+
+```
+$ make darkfid drk
+```
+
+This process will now compile the node and the wallet CLI tool.
+When finished, we can begin using the network. Run `darkfid` once so
+that it spawns its config file on your system. This config file will
+be used by `darkfid` in order to configure itself. The defaults are
+already preset for using the testnet network.
+
+```
+$ ./darkfid
+Config file created in "~.config/darkfi/darkfid_config.toml". Please review it and try again.
+```
+
+
+## Running
+
+Once that's in place, you can run it again and `darkfid` will start,
+create necessary keys for validation of blocks and transactions, and
+begin syncing the blockchain. Keep it running, and you should see a
+`Blockchain is synced!` message after some time.
+
+```
+$ ./darkfid
+```
+
+Now it's time to initialize your wallet. For this we use a separate
+wallet CLI which is created to interface with the smart contract used
+for payments and swaps.
+
+We simply have to initialize a wallet, and create a keypair:
+
+```
+$ ./drk wallet --initialize
+$ ./drk wallet --keygen
+```
+
+The second command will print out your new DarkFi address where you
+can receive payments. Take note of it. Alternatively, you can always
+retrieve it using:
+
+```
+$ ./drk wallet --address
+```
+
+In order to receive incoming coins, you'll need to use the `drk`
+tool to subscribe on `darkfid` so you can receive notifications for
+incoming blocks. The blocks have to be scanned for transactions,
+and to find coins that are intended for you. In another terminal,
+you can run the following commands to first scan the blockchain,
+and then to subscribe to new blocks:
+
+```
+$ ./drk scan
+$ ./drk subscribe
+```
+
+Now you can leave the subscriber running. In case you stop it, just
+run `drk scan` again until the chain is fully scanned, and then you
+should be able to subscribe again.
+
+
+## Airdrops
+
+Now you have your wallet set up. Let's proceed with getting some
+tokens from the faucet. The testnet has a running faucet which is
+able to airdrop arbitrary tokens. For example purposes, we'll use
+the tokens called `DARKfZX1utGbz8ZpnvtCH6i46nSDZEEGa5fMnhoubWPq` and
+`BobvfQrDaf32VNhVtX6Adyi3WGfPpPYZPJBn6rnrxHKm`
+
+So let's airdrop some of these into our wallet:
+
+```
+$ ./drk airdrop 42.69 DARKfZX1utGbz8ZpnvtCH6i46nSDZEEGa5fMnhoubWPq
+$ ./drk airdrop 13.37 BobvfQrDaf32VNhVtX6Adyi3WGfPpPYZPJBn6rnrxHKm
+```
+
+On success, you should see a transaction ID. If successful,
+the airdrop transactions will how be in the consensus' mempool,
+waiting for inclusion in the next block. Depending on the network,
+finalization of the blocks could take some time. You'll have to wait
+for this to happen.  If your `drk subscribe` is running, then after
+some time your balance should be in your wallet.
+
+![pablo-waiting0](pablo0.jpg)
+
+You can check your wallet balance using `drk`:
+
+```
+$ ./drk wallet --balance
+```
+
+## Payments
+
+Using the tokens we got, we can make payments to other addresses. Let's
+try to send some `DARKfZX1utGbz8ZpnvtCH6i46nSDZEEGa5fMnhoubWPq` tokens
+to `8sRwB7AwBTKEkyTW6oMyRoJWZhJwtqGTf7nyHwuJ74pj`:
+
+```
+$ ./drk transfer 2.69 DARKfZX1utGbz8ZpnvtCH6i46nSDZEEGa5fMnhoubWPq \
+    8sRwB7AwBTKEkyTW6oMyRoJWZhJwtqGTf7nyHwuJ74pj > payment_tx
+```
+
+The above command will create a transfer transaction and place it into
+the file called `payment_tx`. Then we can broadcast this transaction
+to the network:
+
+```
+$ ./drk broadcast < payment_tx
+```
+
+On success we'll see a transaction ID. Now again the same finalization
+process has to occur and `8sRwB7AwBTKEkyTW6oMyRoJWZhJwtqGTf7nyHwuJ74pj`
+will receive the tokens you've sent.
+
+![pablo-waiting1](pablo1.jpg)
+
+If you check your balances again, the change should be seen in the
+table immediately:
+
+```
+$ ./drk wallet --balance
+```
+
+## Atomic Swaps
+
+In order to do an atomic swap with someone, you will
+first have to come to consensus on what tokens you wish to
+swap. For example purposes, let's say you want to swap `40`
+`DARKfZX1utGbz8ZpnvtCH6i46nSDZEEGa5fMnhoubWPq` (which is the balance
+you should have left over after doing the above payment) for your
+counterparty's `20` `AcABG4fnmBuT5vuXV8TLdEV8panhk5SdtBZxCCLqQxyL`.
+
+You'll have to initiate the swap and build your half of the swap tx:
+
+```
+$ ./drk otc init -v 40.0:20.0 \
+    -t DARKfZX1utGbz8ZpnvtCH6i46nSDZEEGa5fMnhoubWPq:AcABG4fnmBuT5vuXV8TLdEV8panhk5SdtBZxCCLqQxyL \
+    > half_swap
+```
+
+Then you can send this `half_swap` file to your counterparty and they
+can create the other half by running:
+
+```
+$ ./drk otc join < half_swap > full_swap
+```
+
+They will sign the full_swap file and send it back to you. Finally,
+to make the swap transaction valid, you need so sign it as well,
+and broadcast it:
+
+```
+$ ./drk otc sign < full_swap > signed_swap
+$ ./drk broadcast < signed_swap
+```
+
+On success, you should see a transaction ID. This transaction will now
+also be in the mempool, so you should wait again until it's finalized.
+
+![pablo-waiting2](pablo2.jpg)
+
+After a while you should see the change in balances in your wallet:
+
+```
+$ ./drk wallet --balance
+```
+
+If you see your counterparty's tokens, that means the swap was
+successful.  In case you still see your old tokens, that could mean
+that the swap transaction has not yet been finalized.