From 4fd04ff158ad038a6995c922f58a15635cbbf00b Mon Sep 17 00:00:00 2001 From: Hanh Date: Mon, 23 Sep 2024 00:03:16 +1000 Subject: [PATCH] Tutorial docs wip --- docs/.vitepress/config.mjs | 4 ++ docs/tutorial/account.md | 80 +++++++++++++++++++++++++++++++++++ docs/tutorial/mine.md | 1 + docs/tutorial/prereq.md | 10 +++++ docs/tutorial/warp.md | 57 +++++++++++++++++++++++++ docs/tutorial/zcashd.md | 86 ++++++++++++++++++++++++++++++++++++++ 6 files changed, 238 insertions(+) create mode 100644 docs/tutorial/account.md create mode 100644 docs/tutorial/mine.md create mode 100644 docs/tutorial/prereq.md create mode 100644 docs/tutorial/warp.md diff --git a/docs/.vitepress/config.mjs b/docs/.vitepress/config.mjs index aae3a75..b70e7e3 100644 --- a/docs/.vitepress/config.mjs +++ b/docs/.vitepress/config.mjs @@ -17,7 +17,11 @@ export default defineConfig({ text: 'Tutorial', link: '/tutorial', items: [ + { text: 'Prerequisites', link: '/tutorial/prereq' }, { text: 'Setup Zcashd Regtest', link: '/tutorial/zcashd' }, + { text: 'Setup Zcash-Warp Regtest', link: '/tutorial/warp' }, + { text: 'Create a new account', link: '/tutorial/account' }, + { text: 'Mining', link: '/tutorial/mine' }, ] } ], diff --git a/docs/tutorial/account.md b/docs/tutorial/account.md new file mode 100644 index 0000000..cb07348 --- /dev/null +++ b/docs/tutorial/account.md @@ -0,0 +1,80 @@ +# Account Creation + +## Generate a Seed Phrase + +Using the `zcash-warp` command prompt, generate a new +24 word seed phrase: +``` +zcash-warp〉generate-seed 09/22/2024 11:44:54 PM +bus abandon spell scout nuclear bamboo mystery scare network sentence intact north charge level choose family mule design tobacco night online sad invest bleak +zcash-warp〉 09/22/2024 11:44:54 PM +``` + +::: info +Your seed phrase will be different than this one. +::: + +## Create a new database +If you are using `zcash-warp` for the first time, you have to create +a new database + +``` +zcash-warp〉create-database 09/22/2024 11:51:21 PM +``` + +## Create a new account + +Then create an account using that seed phrase. + +``` +zcash-warp〉account create "bus abandon spell scout nuclear bamboo mystery scare network sentence intact north charge level choose family mule design tobacco night online sad invest bleak" "DEMO" 1 +zcash-warp〉 09/22/2024 11:51:54 PM +``` + +- The 2nd argument, "DEMO" is the name of the account. +- The 3rd argument, 1, is its birth height. We are saying that there are no transactions +on this account before block 1. The app does not need to process the blocks before. + +::: tip +On Mainnet, using a birth height is **highly** recommended because it +can save you a lot of time. +::: + +## Balance + +Its balance should be 0 at this point. + +``` +zcash-warp〉balance 1 09/22/2024 11:52:18 PM +Balance: BalanceT { transparent: 0, sapling: 0, orchard: 0 } +zcash-warp〉 09/22/2024 11:52:18 PM +``` + +## Addresses + +Let's query this account addresses. + +Every account has six different addresses: +- a transparent address, +- a sapling address +- an orchard only Unified Addresses +- and UA that combine 2 or 3 receivers: T+S, T+O, S+O and T+S+O + +We ask for an address with the command `address `. +- The first account has number 1. +- The mask is the sum of 1 for Transparent, 2 for Sapling and +4 for Orchard. For example, if you want the transparent & orchard UA, use mask=5 because +5 = 1+4. + +``` +zcash-warp〉address 1 5 09/22/2024 11:56:58 PM +Address: uregtest1jk5cs77cx43humsmyd3f7eah0lvgvhuy8k3hhdgn6rmeu60933vljv2ytrasaf3d5utfz5mxzgwu8jhlg665d4j4v5e5clvkjjv3eks0wy8kjf75zqzl3vm3y2w4e96qzlkhc73yg3w +zcash-warp〉 09/22/2024 11:56:58 PM +``` + +::: info +Your address will be different if you are using a different seed. +::: + +Next, we'll mine some blocks, collect the block reward and send some funds +to the Zcash-warp wallet. diff --git a/docs/tutorial/mine.md b/docs/tutorial/mine.md new file mode 100644 index 0000000..9ec46e9 --- /dev/null +++ b/docs/tutorial/mine.md @@ -0,0 +1 @@ +# Mining diff --git a/docs/tutorial/prereq.md b/docs/tutorial/prereq.md new file mode 100644 index 0000000..2099eb9 --- /dev/null +++ b/docs/tutorial/prereq.md @@ -0,0 +1,10 @@ +# Prerequisites + +In this tutorial, we will assume that you are confortable +with using the command line and that you know how to +edit configuration files. + +Moreover, you need to have `zcashd` and `lightwalletd` +installed. Therefore you might have to build +these apps from their source code on Github or use +a binary package. diff --git a/docs/tutorial/warp.md b/docs/tutorial/warp.md new file mode 100644 index 0000000..017bf15 --- /dev/null +++ b/docs/tutorial/warp.md @@ -0,0 +1,57 @@ +# Zcash Warp + +## Build + +::: info +Skip this section if you have already cloned and built the `zcash-warp` +library and CLI. +::: + +``` +git clone https://github.com/hhanh00/warp.git +cd warp +git submodule update --init +cargo b -r +cd zcash-warp +``` + +This builds `zcash-warp` in `../target/release`. + +## Configuration + +In the `zcash-warp` directory, create a `App.toml` file +with the following content: + +``` +db_path="zec.db" +lwd_url="http://127.0.0.1:9168" +warp_url="http://127.0.0.1:8000" +warp_end_height=0 +confirmations=1 +regtest=true +``` + +- `lwd_url` is the URL to the Lightwalletd server. If you plan to run +it on a different machine, change the IP address accordingly. +- `warp_url` is the URL of the WARP 2 server. We are not going to use +it on this tutorial since we are running on a tiny blockchain. It +is fine to leave the URL as it is. +- A `warp_end_height` of 0 disables WARP 2. +- `confirmations` is set to 1 so that we don't have to wait for more +than 1 confirmation before we can spend the funds we receive. +- Finally, `regtest=true` enables regtest mode. + +::: tip +If you set regtest to false, `zcash-warp` connects to the mainnet chain. +::: + +Now, run `zcash-warp`. If everything is fine, it replies with its +command prompt. + +``` +zcash-warp〉 +``` + +Try entering `help` to get a list of available commands. + +Next, we will create a new account and get its addresses. diff --git a/docs/tutorial/zcashd.md b/docs/tutorial/zcashd.md index e69de29..4b1d42e 100644 --- a/docs/tutorial/zcashd.md +++ b/docs/tutorial/zcashd.md @@ -0,0 +1,86 @@ +# Zcashd + +## Configuration + +If you have `zcashd` compiled from source, it will be in the +`src` folder of the project root. + +We want to run the server in Regtest. In this mode, +the server creates and connects to its own Blockchain +(independent from the main chain). Therefore, you have +full control over when blocks are created and which transactions +are included. + +::: info +On regtest, ZEC has **no value**. +::: + +1. First create a directory (for example `regtest_dir`) where you will put the configuration and data files +2. In this directory, create a `zcash.conf` file with the following content: +``` +regtest=1 +rpcuser=a +rpcpassword=a +nuparams=c2d6d0b4:1 +rpcallowip=192.168.0.0/24 +experimentalfeatures=1 +lightwalletd=1 +txindex=1 +``` + +- The rpcuser and rpcpassword can be anything you want. Don't forget to activate +regtest otherwise the server will connect to the mainnet. +- `nuparam=c2d6d0b4:1` tells the server that NU-5 (the Orchard Network Upgrade) +should be activated at Block #1. +- `rpcallowip` is the network mask that restricts which clients can connect. +In your local net, it is often `192.168.0.0/24`. +- The last 3 options are for `lightwalletd` + +Now start the server with the command: +``` +./src/zcashd --datadir=regtest_dir --daemon +``` +(assuming you used `regtest_dir`) + +After a short while, the server should give you back control of the command line. + +::: tip +The `regtest_dir` should have a `regtest` sub directory and the `zcash.conf` file. +::: + +## Check + +We check that the server is running properly by sending a simple command to it. + +``` +./src/zcash-cli --datadir=regtest_dir getinfo +``` + +It should return something like: +``` +{ + "version": 5080050, + "build": "v5.8.0", + "subversion": "/MagicBean:5.8.0/", + "protocolversion": 170100, + "walletversion": 60000, + "balance": 0.00000000, + "blocks": 0, <-------- Check this + "timeoffset": 0, + "connections": 0, + "proxy": "", + "difficulty": 1, + "testnet": false, + "keypoololdest": 1727010648, + "keypoolsize": 101, + "paytxfee": 0.00000000, + "relayfee": 0.00000100, + "errors": "", + "errorstimestamp": 1727010650 +} +``` + +A block height of 0 indicates that we are running on our blockchain +since we are still at the genesis. + +Next, we'll setup our Zcash Warp wallet.