Tutorial

.github/workflows/docs-deploy.yml

@@ -0,0 +1,57 @@
+name: Deploy VitePress site to Pages
+
+on:
+  push:
+    branches: [docs]
+
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  # Build job
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0 # Not needed if lastUpdated is not enabled
+      - uses: pnpm/action-setup@v3
+        with:
+          version: latest
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: pnpm
+      - name: Setup Pages
+        uses: actions/configure-pages@v4
+      - name: Install dependencies
+        run: pnpm install
+      - name: Build with VitePress
+        run: pnpm docs:build
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: docs/.vitepress/dist
+
+  # Deployment job
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    needs: build
+    runs-on: ubuntu-latest
+    name: Deploy
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.gitignore

@@ -0,0 +1,6 @@
+target/
+.DS_Store
+*.db
+App.toml
+node_modules/
+docs/.vitepress/cache

docs/.vitepress/config.mjs

@@ -0,0 +1,56 @@
+import footnote from 'markdown-it-footnote'
+import { defineConfig } from 'vitepress'
+
+// https://vitepress.dev/reference/site-config
+export default defineConfig({
+  title: "Warp Zcash Wallet Library",
+  description: "A High Performance Wallet Synchronization and Transaction Builder for Zcash",
+  base: '/warp/',
+  themeConfig: {
+    // https://vitepress.dev/reference/default-theme-config
+    nav: [
+      { text: 'Home', link: '/' },
+    ],
+
+    sidebar: [
+      {
+        text: 'About Zcash',
+        link: '/about-zcash/',
+      },
+      {
+        text: 'Tutorial',
+        collapsible: true,
+        collapsed: true,
+        items: [
+          { text: 'Overview', link: '/tutorial/' },
+          { 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' },
+          { text: 'Setup Lightwalletd', link: '/tutorial/lwd' },
+          { text: 'Shield Coinbase Reward', link: '/tutorial/shieldcoinbase' },
+          { text: 'Synchronization', link: '/tutorial/sync' },
+          { text: 'Basic Transaction & Fees', link: '/tutorial/simple_tx' },
+          { text: 'Splitting Notes', link: '/tutorial/split' },
+          { text: 'Diverse Input Notes', link: '/tutorial/multi_notes' },
+          { text: 'Paying a Transparent Address', link: '/tutorial/pay_t' },
+          { text: 'Paying a Shielded Address', link: '/tutorial/pay_z' },
+          { text: 'Paying a Multi-Receiver UA', link: '/tutorial/pay_ua' },
+          { text: 'Using Payment URIs', link: '/tutorial/payment_uri' },
+          { text: 'Max transfer', link: '/tutorial/max' },
+          { text: 'Conclusion', link: '/tutorial/conclusion' },
+        ]
+      }
+    ],
+
+    socialLinks: [
+      { icon: 'github', link: 'https://github.com/hhanh00/warp' }
+    ]
+  },
+  markdown: {
+    config: (md) => {
+      md.use(footnote)
+    }
+  }
+})

docs/about-zcash/index.md

@@ -0,0 +1,3 @@
+# About Zcash
+
+Under construction

docs/index.md

@@ -0,0 +1,24 @@
+---
+# https://vitepress.dev/reference/default-theme-home-page
+layout: home
+
+hero:
+  name: "Warp Zcash Wallet Library"
+  tagline: Synchronization and Transaction Builder
+  actions:
+    - theme: brand
+      text: Tutorial
+      link: /tutorial/
+    - theme: alt
+      text: About Zcash
+      link: /about-zcash
+
+features:
+  - title: Warp (2) Synchronization
+    details: Fastest synchronization available
+  - title: Multi currency
+    details: Supports Zcash, Ycash and any Zcash forks
+  - title: Multi Payments
+    details: Create complex transactions involving Unified Addresses and several pools
+---
+

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 from 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 *7* 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 <account> <mask>`.
+- 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.

docs/tutorial/conclusion.md

@@ -0,0 +1,25 @@
+# Conclusion
+
+We took a tour of Zcash, where we learned how transactions use your wallet notes
+and how this impacts privacy. Zcash has several active pools of funds, and as a
+result, the confidentiality of a transaction depends on what notes your wallet
+has and where you are sending it.
+
+To simplify the user experience, some wallet apps, like Zashi, require you to
+put all your funds into the Orchard pool before you can use them.
+
+However, if you pay someone with a Sapling wallet, your transaction reveals the
+amount. 
+
+::: warning
+Until every wallet app supports Orchard, users need to be aware that **privacy in
+Zcash is a spectrum**. From a t2t transaction to an o2o transaction, we move from
+*no privacy* to *complete privacy*. Understanding this spectrum is paramount to
+making informed decisions.
+:::
+
+Wallet apps cannot foresee what type of address you will send funds to, so they
+will always make assumptions and compromises.
+
+I encourage you to try various scenarios and observe the resulting privacy
+level.

docs/tutorial/index.md

@@ -0,0 +1,25 @@
+# Tutorial
+
+## Topics
+
+This is a (non-exhaustive) list of topics that this tutorial covers.
+
+- start zcashd regtest
+- lightwalletd regtest
+- warp regtest
+- create a wallet in warp
+- mine
+- shield zcashd -> warp
+- transfer funds from warp -> warp
+- split notes
+- transfer pools
+- zip 317
+- pick multiple input notes
+- multiple receiver ua
+- z2z
+- z2o
+- z2t
+- t2t
+- sender pays fees
+- change/no change
+- multi pay

docs/tutorial/lwd.md

@@ -0,0 +1,22 @@
+# Setup Lightwalletd
+
+Actually, Lightwalletd (LWD) does not require much configuration.
+Everything can be specified on the command line.
+
+```
+$ ./lightwalletd --no-tls-very-insecure --zcash-conf-path ./regtest_dir/zcash.conf --data-dir lwd-data --log-file /dev/stdout --grpc-bind-addr 0.0.0.0:9168
+```
+
+- `no-tls-very-insecure` indicates that we are not using SSL, i.e encrypted
+HTTP
+- `zcash-conf-path` must point to the same `zcashd` configuration file
+- `data-dir` gives the path to the LWD data directory
+- `log-file` is self-explanatory
+- `grpc-bind-addr` is where LWD should listen. Here it on port **9168**
+This must match the configuration of `zcash-warp` LWD_URL.
+
+LWD should quickly import the first 101 blocks and wait for block #102.
+
+```
+{"app":"lightwalletd","level":"info","msg":"Waiting for block: 102","time":"2024-09-23T08:58:25+08:00"}
+```