doc/testnet: updated everything with latest commands

bin/drk/src/cli_util.rs

@@ -224,8 +224,7 @@ pub fn generate_completions(shell: &str) -> Result<()> {
     let inspect = SubCommand::with_name("inspect")
         .about("Inspect a swap half or the full swap tx from stdin");
 
-    let sign = SubCommand::with_name("sign")
-        .about("Sign a transaction given from stdin as the first-half");
+    let sign = SubCommand::with_name("sign").about("Sign a swap transaction given from stdin");
 
     let otc = SubCommand::with_name("otc")
         .about("OTC atomic swap")

bin/drk/src/main.rs

@@ -301,7 +301,7 @@ enum OtcSubcmd {
     /// Inspect a swap half or the full swap tx from stdin
     Inspect,
 
-    /// Sign a transaction given from stdin as the first-half
+    /// Sign a swap transaction given from stdin
     Sign,
 }
 

doc/src/SUMMARY.md

@@ -11,7 +11,7 @@
 # User Guide
 
 - [Running a Node](testnet/node.md)
-- [Airdrops](testnet/airdrop.md)
+- [Tokens](testnet/token.md)
 - [Payments](testnet/payment.md)
 - [Atomic Swap](testnet/atomic-swap.md)
 - [DAO](testnet/dao.md)

doc/src/testnet/atomic-swap.md

@@ -30,12 +30,38 @@ $ ./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 to sign it as well,
-and broadcast it:
+to make the swap transaction valid, you need to sign it as well
 
 ```
 $ ./drk otc sign < full_swap > signed_swap
-$ ./drk broadcast < signed_swap
+```
+
+Now that the swap is signed, one of the parties (or a third one)
+must attach the corresponding fee:
+
+```
+$ ./drk attach-fee < signed_swap > full_swap_with_fee
+```
+
+Since a new call has been added to the transaction, both parties
+must re-sign the full_swap_with_fee file, one by one.
+
+Party A:
+
+```
+$ ./drk otc sign < full_swap_with_fee > signed_full_swap_with_fee
+```
+
+Party B:
+
+```
+$ ./drk otc sign < signed_full_swap_with_fee > swap_tx
+```
+
+Now the complete swap transaction can be broadcasted:
+
+```
+$ ./drk broadcast < swap_tx
 ```
 
 On success, you should see a transaction ID. This transaction will now

doc/src/testnet/dao.md

@@ -4,11 +4,6 @@ On the testnet, we are also able to create an anonymous DAO. Using
 the `drk` CLI tool, we have a `dao` subcommand that can perform the
 necessary operations.
 
-You can find a script in
-`contrib/localnet/darkfid-single-node/run-dao-test.sh` which
-automatically does all the commands in this tutorial. Just be sure
-to read the comment at the top of the file first.
-
 Let's create a DAO with the following parameters:
 
 * Proposer limit: `20`
@@ -25,47 +20,50 @@ $ ./drk help dao create
 Let's create our DAO.
 
 ```
-$ ./drk dao create 20 10 0.67 MLDY > dao.dat
-$ ./drk dao view < dao.dat
+$ ./drk dao create 20 10 0.67 MLDY > dao_mldy.dat
+$ ./drk dao view < dao_mldy.dat
 ```
 
-The view command will show us the parameters. If everything looks fine,
-we can now import it into our wallet:
+Now this file can be shared amongst all dao members, so they
+hold the generated DAO information and keys. The view command
+will show us the parameters. If everything looks fine, we can
+now import it into our wallet:
 
 ```
-./drk dao import MiladyMakerDAO < dao.dat
-./drk dao list
-./drk dao list MiladyMakerDAO
+$ ./drk dao import MiladyMakerDAO < dao_mldy.dat
+$ ./drk dao list
+$ ./drk dao list MiladyMakerDAO
 ```
 
 ## Minting
 
 If parameters are shown, this means the DAO was successfully imported
-into our wallet. The DAO's index in our wallet is `1`, so we'll use
-that to reference it. Now we can create a transaction that will mint
-the DAO on-chain, and broadcast it:
+into our wallet. We use the DAO name to reference it. Now we can create
+a transaction that will mint the DAO on-chain, and broadcast it:
 
 ```
-./drk dao mint MiladyMakerDAO > dao_mint_tx
-./drk broadcast < dao_mint_tx
+$ ./drk dao mint MiladyMakerDAO > dao_mldy_mint_tx
+$ ./drk broadcast < dao_mldy_mint_tx
 ```
 
 Now the transaction is broadcasted to the network. Wait for it to
 finalize, and if your `drk` is subscribed, after finalization you
-should see a `leaf_position` and a transaction ID when running
+should see a leaf position and a transaction hash when running
 `dao list MiladyMakerDAO`.
 
 ## Sending money to the treasury
 
 Let's send some tokens to the DAO's treasury so we're able to make
-a proposal to send those somewhere. First find the DAO bulla and the
-DAO public key with `dao list` and then create a transfer transaction:
+a proposal to send those somewhere. First, find the DAO bulla, the
+dao contract spend hook and the DAO public key a d then create a
+transfer transaction:
 
 ```
+$ ./drk dao spend-hook
 $ ./drk dao list MiladyMakerDAO
 $ ./drk transfer 10 WCKD {DAO_PUBLIC_KEY} \
-    --dao {DAO_BULLA} > dao_transfer
-$ ./drk broadcast < dao_transfer
+    {DAO_CONTRACT_SPEND_HOOK} {DAO_BULLA} > dao_mldy_transfer_tx
+$ ./drk broadcast < dao_mldy_transfer_tx
 ```
 
 Wait for it to finalize, and if subscribed, you should see the DAO
@@ -77,48 +75,75 @@ $ ./drk dao balance MiladyMakerDAO
 
 ## Creating a proposal
 
-Now that the DAO has something in its treasury, we can create a
-proposal to send it somewhere. Let's send 5 of the 10 tokens to our
-address (we can find that with `drk wallet --address`):
+Now that the DAO has something in its treasury, we can generate a
+transfer proposal to send it somewhere, that will be up to vote
+for 30 block periods. Let's propose to send 5 of the 10 tokens to
+our address (we can find that with `drk wallet --address`):
 
 ```
-$ ./drk dao propose MiladyMakerDAO {YOUR_ADDRESS} 5 WCKD > proposal_tx
-$ ./drk broadcast < proposal_tx
+$ ./drk dao propose-transfer MiladyMakerDAO 30 5 WCKD {YOUR_ADDRESS}
 ```
 
-Once finalized and scanned, the proposal should be viewable in the
-wallet. We can see this with the `proposal` subcommands:
+After command was executed, it will output the generated proposal
+bulla, which we will use to full the proposal information:
 
 ```
-$ ./drk dao proposals MiladyMakerDAO
-$ ./drk dao proposal MiladyMakerDAO 1
+$ ./drk dao proposal {PROPOSAL_BULLA}
 ```
 
+We can export this proposal, to share with rest DAO members.
+The exported file will be encrypted using the DAO keys, so only
+its members can decrypt and import it.
+
+```
+$ ./drk dao proposal {PROPOSAL_BULLA} --export > dao_mldy_transfer_proposal.dat
+$ ./drk dao proposal-import < dao_mldy_transfer_proposal.dat
+```
+
+Now we can create the proposal mint transaction and broadcast it:
+```
+$ ./drk dao proposal {PROPOSAL_BULLA} --mint-proposal > dao_mldy_transfer_proposal_mint_tx
+$ ./drk broadcast < dao_mldy_transfer_proposal_mint_tx
+```
+
+Members that didn't receive the encrypted file will receive the
+proposal when they scan the corresponding block, but its plaintext
+data will be missing, so they should ask the DAO for it.
+Once finalized and scanned, you should see a leaf position and a
+transaction hash when running `dao proposal {PROPOSAL_BULLA}`.
+
 ## Voting on a proposal
 
 Now the DAO members are ready to cast their votes.
 First lets check the `dao vote` subcommand usage.
 
 ```
-$ drk help dao vote
+$ ./drk help dao vote
 Vote on a given proposal
 
-Usage: drk dao vote <DAO_ALIAS> <PROPOSAL_ID> <VOTE> <VOTE_WEIGHT>
+USAGE:
+    drk dao vote <bulla> <vote> [vote-weight]
 
-Arguments:
-  <DAO_ALIAS>    Name or numeric identifier for the DAO
-  <PROPOSAL_ID>  Numeric identifier for the proposal
-  <VOTE>         Vote (0 for NO, 1 for YES)
-  <VOTE_WEIGHT>  Vote weight (amount of governance tokens)
+FLAGS:
+    -h, --help       Prints help information
+    -V, --version    Prints version information
+
+ARGS:
+    <bulla>          Bulla identifier for the proposal
+    <vote>           Vote (0 for NO, 1 for YES)
+    <vote-weight>    Optional vote weight (amount of governance tokens)
 ```
 
-Lets use our 20 MLDY to vote yes to proposal 1.
+Lets use our `MLDY` governance tokens to vote yes to the proposal.
 
 ```
-$ drk dao vote MiladyMakerDAO 1 1 20 > /tmp/dao-vote.tx
-$ drk broadcast < /tmp/dao-vote.tx
+$ ./drk dao vote {PROPOSAL_BULLA} 1 > dao_mldy_transfer_proposal_vote_tx
+$ ./drk broadcast < dao_mldy_transfer_proposal_vote_tx
 ```
 
+Once finalized and scanned, you should see votes information and
+current status when running `dao proposal {PROPOSAL_BULLA}`.
+
 ## Executing the proposal
 
 Once enough votes have been cast that meet the required minimum (quorum)
@@ -126,8 +151,83 @@ and assuming the yes:no votes ratio is bigger than the approval ratio,
 then we are ready to finalize the vote. Any DAO member can perform this
 action.
 
+Since in our tutorial the `MLDY` governance tokens we used surpass the
+quorum, we can execute the proposal right away:
+
 ```
-$ drk dao exec MiladyMakerDAO 1 > /tmp/dao-exec.tx
-$ drk broadcast < /tmp/dao-exec.tx
+$ ./drk dao exec {PROPOSAL_BULLA} > dao_mldy_transfer_proposal_exec_tx
+$ ./drk broadcast < dao_mldy_transfer_proposal_exec_tx
 ```
 
+After the proposal has been executed on chain, we will see that
+the DAO balance has been reduced by 5 `WCKD`, while our own balance
+has been increased by the same amount:
+
+```
+$ ./drk dao balance MiladyMakerDAO
+$ ./drk wallet --balance
+```
+
+## DAO->DAO
+
+Let's now try some more exotic operations!
+
+Since we hold the mint authority of the `MLDY` token,
+instead of transfering some to the DAO, we will mint them
+directly into it:
+
+```
+$ ./drk token mint MLDY 20 {DAO_PUBLIC_KEY} \
+    {DAO_CONTRACT_SPEND_HOOK} {DAO_BULLA} > mint_dao_mldy_tx
+$ ./drk broadcast < mint_dao_mldy_tx
+```
+
+After finalization we will see the dao holding its own
+governance tokens in its treasury:
+
+```
+$ ./drk dao balance MiladyMakerDAO
+```
+
+Now we will create a second dao:
+
+```
+$ ./drk dao create 20 10 0.67 WCKD > dao_wckd.dat
+$ ./drk dao import WickedDAO < dao_wckd.dat
+$ ./drk dao mint WickedDAO > dao_wckd_mint_tx
+$ ./drk broadcast < dao_wckd_mint_tx
+```
+
+We propose a transfer of some of the `MLDY` governance token
+from the DAO treasury to the new DAO we created:
+
+```
+$ ./drk dao list WickedDAO
+$ ./drk dao propose-transfer MiladyMakerDAO 30 6.9 MLDY {WICKED_DAO_PUBLIC_KEY} \
+    {DAO_CONTRACT_SPEND_HOOK} {WICKED_DAO_BULLA}
+$ ./drk dao proposal {PROPOSAL_BULLA} --mint-proposal > dao_mldy_transfer_proposal_wckd_mint_tx
+$ ./drk broadcast < dao_mldy_transfer_proposal_wckd_mint_tx
+```
+
+Vote on the proposal:
+
+```
+$ ./drk dao vote {PROPOSAL_BULLA} 1 > dao_mldy_transfer_proposal_wckd_vote_tx
+$ ./drk broadcast < dao_mldy_transfer_proposal_wckd_vote_tx
+```
+
+And execute it:
+
+```
+$ ./drk dao exec {PROPOSAL_BULLA} > dao_mldy_transfer_proposal_wckd_exec_tx
+$ ./drk broadcast < dao_mldy_transfer_proposal_wckd_exec_tx
+```
+
+After the proposal has been executed on chain, we will see that
+the DAO governance token balance has been reduced by 6.9 `MLDY`,
+while the new DAO balance has been increased by the same amount:
+
+```
+$ ./drk dao balance MiladyMakerDAO
+$ ./drk dao balance WickedDAO
+```

doc/src/testnet/node.md

@@ -6,12 +6,18 @@ 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.
 
+Please read the whole document first before executing commands, to
+understand all the steps required and how each component operates.
+Unless instructed otherwise, each daemon exists/runs on its own
+shell, so don't stop a running one to start another.
+We also strongly suggest to first execute next guide steps on a
+[local environment](#local-deployment) to become familiar with
+each command, before broadcasting transactions to the actual network.
 
 ## 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.
+Refer to the main [DarkFi](../index.html) page 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:
@@ -21,27 +27,21 @@ $ 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.
+When finished, we can begin using the network. Run `darkfid` and `drk`
+once so their config files are spawned on your system. This config files
+will be used by `darkfid` and `drk` in order to configure themselves.
+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.
+$ ./drk
+Config file created in "~/.config/darkfi/drk_config.toml". Please review it and try again.
 ```
 
-
 ## Running
 
-Once that's in place, you can run it again and `darkfid` will start,
-create the 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
-```
+### Wallet initialization
 
 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
@@ -52,16 +52,65 @@ We simply have to initialize a wallet, and create a keypair:
 ```
 $ ./drk wallet --initialize
 $ ./drk wallet --keygen
+$ ./drk wallet --default-address 1
 ```
 
 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:
+retrieve your default address using:
 
 ```
 $ ./drk wallet --address
 ```
 
+### Miner
+
+If you want to help secure the network, you can participate in the mining
+process, by running the native `minerd` mining daemon. First, compile it:
+
+```
+$ make minerd
+```
+
+This process will now compile the mining daemon. When finished, run
+`minerd` once so that it spawns its config file on your system. This
+config file will be used by `minerd` in order to configure itself.
+
+```
+$ ./minerd
+Config file created in "~/.config/darkfi/minerd_config.toml". Please review it and try again.
+```
+
+Once that's in place, you can run it again and `minerd` will start,
+waiting for requests to mine blocks.
+
+```
+$ ./minerd
+```
+
+You now have to configure `darkfid` to use your wallet address as the
+rewards recipient, when submitting blocks to `minerd` to mine. Open
+your config file with your editor of choice (default path is
+`~/.config/darkfi/darkfid_config.toml`) and find the `recipient`
+option under the network configuration you will operate on (for testnet
+it is `[network_config."testnet"]`). Uncomment it by removing the `#`
+character at the start of line, and replace the `YOUR_WALLET_ADDRESS_HERE`
+string with your wallet address.
+
+
+### Darkfid
+
+Now that `darkfid` configuration is in place, you can run it again and
+`darkfid` will start, create the necessary keys for validation of blocks
+and transactions, and begin syncing the blockchain. Keep it running,
+and you should see a `Blockchain synced!` message after some time.
+
+```
+$ ./darkfid
+```
+
+### Wallet sync
+
 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,
@@ -80,30 +129,56 @@ should be able to subscribe again.
 
 ## Local Deployment
 
-For development we recommend running master.
-First we modify the constants specifically for a local testnet.
-This step is optional but you might find scanning takes a long time
-otherwise.
+For development we recommend running master, and use the existing
+`contrib/localnet/darkfid-single-node` folder, which provides
+the corresponding configurations to operate.
+
+First, compile `darkfid` node, `minerd` mining daemon and the `drk`
+wallet CLI:
 
 ```
-cd contrib/localnet/darkfid-single-node/
-./tmux_sessions.sh now
-cd ../../../
-make darkfid
+$ make darkfid minerd drk
 ```
 
-You can run a single consensus full node using this command:
+Enter the localnet folder, generate a wallet, set it as the
+default one and grab its address:
 
 ```
-./tmux_sessions.sh -v
+$ cd contrib/localnet/darkfid-single-node/
+$ ../../../drk -c drk.toml wallet --initialize
+$ ../../../drk -c drk.toml wallet --keygen
+$ ../../../drk -c drk.toml wallet --default-address 1
+$ ../../../drk -c drk.toml wallet --address
 ```
 
+Then we replace the `recipient` field in `darkfid.toml`
+config, existing in the folder, with the output of the last
+command, start `darkfid` and wait until its initialized:
+
+```
+$ ./tmux_sessions.sh
+```
+
+After some blocks have been generated we
+will see some `DRK` in our test wallet.
+On a different shell, navigate to `contrib/localnet/darkfid-single-node`
+folder again and scan for new blocks
+
+```
+$ ../../../drk -c drk.toml scan
+$ ../../../drk -c drk.toml wallet --balance
+```
+
+Don't forget that when using this local node, all operations
+should be executed inside the `contrib/localnet/darkfid-single-node`
+folder, and `./drk` command to be replaced by `../../../drk -c drk.toml`
+
 ## Advanced Usage
 
 To run a node in full debug mode:
 
 ```
-LOG_TARGETS="\!sled,\!net" ./darkfid -v | tee /tmp/darkfid.log
+$ LOG_TARGETS="\!sled,\!net" ./darkfid -vv | tee /tmp/darkfid.log
 ```
 
 The `sled` and `net` targets are very noisy and slow down the node so
@@ -112,6 +187,6 @@ we disable those.
 We can now view the log, and grep through it.
 
 ```
-tail -n +0 -f /tmp/darkfid.log | grep -a --line-buffered -v DEBUG
+$ tail -n +0 -f /tmp/darkfid.log | grep -a --line-buffered -v DEBUG
 ```
 

doc/src/testnet/airdrop.md → doc/src/testnet/token.md

@@ -1,26 +1,17 @@
-# Airdrops
+# Native token
 
-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 native network tokens. 
+Now that you have your wallet set up, you will need some native `DRK`
+tokens in order to be able to perform transactions, since that token
+is used to pay the transaction fees. You can obtain `DRK` either by
+successfully mining a block that gets finalized or by asking for some
+by the community on `darkirc` and/or your comrades.
 
-So let's airdrop some of these into our wallet:
-
-```
-$ ./drk airdrop 42.69
-```
-
-There is a limit of 100 for testnet airdrops currently.
-
-Note: you have to wait some minutes between airdrops since they're
-rate-limited.
-
-On success, you should see a transaction ID. If successful,
-the airdrop transactions will now 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 blocks` is running, then after
-some time your balance should be in your wallet.
+After you request some `DRK` and the other party submitted a transaction
+to the network, it should be in the consensus' mempool, waiting for
+inclusion in the next block(s). 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 new balance
+should be in your wallet.
 
 ![pablo-waiting0](pablo0.jpg)
 
@@ -42,14 +33,8 @@ Example addition:
 $ ./drk alias add {ALIAS} {TOKEN}
 ```
 
-So let's add the native token as `DARK` by executing:
-
-```
-$ ./drk alias add DARK 12ea8e3KVuBhmSnr29iV34Zd2RsD1MEeGk9xJhcipUqx
-```
-
-From now on, we can use `DARK` to refer to the native token when
-executing transactions using it.
+The native token alias `DRK` should already exist, and we can use that
+to refer to the native token when executing transactions using it.
 
 We can also list all our aliases using:
 
@@ -101,6 +86,6 @@ $ ./drk broadcast < mint_tx
 ```
 
 Now the transaction should be published to the network. If you have
-an active block subscription (which you can do with `drk subscribe blocks`),
+an active block subscription (which you can do with `drk subscribe`),
 then when the transaction is finalized, your wallet should have your
 new tokens listed when you request to see the balance.