diff --git a/bin/drk/src/cli_util.rs b/bin/drk/src/cli_util.rs index 6d05f1610..52af7aa31 100644 --- a/bin/drk/src/cli_util.rs +++ b/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") diff --git a/bin/drk/src/main.rs b/bin/drk/src/main.rs index 9e6cdbaf7..2fbd74ac7 100644 --- a/bin/drk/src/main.rs +++ b/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, } diff --git a/doc/src/SUMMARY.md b/doc/src/SUMMARY.md index 9eba72bf2..e2cc132ed 100644 --- a/doc/src/SUMMARY.md +++ b/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) diff --git a/doc/src/testnet/atomic-swap.md b/doc/src/testnet/atomic-swap.md index ba0942594..fc4c939c7 100644 --- a/doc/src/testnet/atomic-swap.md +++ b/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 diff --git a/doc/src/testnet/dao.md b/doc/src/testnet/dao.md index c38ad31ea..66c14cc53 100644 --- a/doc/src/testnet/dao.md +++ b/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 +USAGE: + drk dao vote [vote-weight] -Arguments: - Name or numeric identifier for the DAO - Numeric identifier for the proposal - Vote (0 for NO, 1 for YES) - Vote weight (amount of governance tokens) +FLAGS: + -h, --help Prints help information + -V, --version Prints version information + +ARGS: + Bulla identifier for the proposal + Vote (0 for NO, 1 for YES) + 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 +``` diff --git a/doc/src/testnet/node.md b/doc/src/testnet/node.md index e5971e5dc..dd3261be6 100644 --- a/doc/src/testnet/node.md +++ b/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 ``` diff --git a/doc/src/testnet/airdrop.md b/doc/src/testnet/token.md similarity index 64% rename from doc/src/testnet/airdrop.md rename to doc/src/testnet/token.md index 6efad9dce..dace4f446 100644 --- a/doc/src/testnet/airdrop.md +++ b/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.