Merge pull request #111 from hyperledger-labs/docs

Move content from README to docs

Author: Chengxuan

.github/workflows/docs.yaml

@@ -0,0 +1,61 @@
+name: Docs Site
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - 'doc-site/docs/**'
+  pull_request:
+    paths:
+      - 'doc-site/docs/**'
+  release:
+    types: [released]
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    env:
+      LATEST_TAG: ''
+    permissions:
+      contents: write
+    steps:
+      - name: Checkout source
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Setup Docs Deploy
+        run: |
+          git config --global user.name "GitHub Actions"
+          git config --global user.email "noreply@github.com"
+
+      - name: Get the latest tag
+        run: |
+          git fetch --tags
+          latest_tag=$(git tag -l | sort -V | grep -v "rc" | tail -n 1)
+          echo "latest tag: $latest_tag"
+          echo "LATEST_TAG=$latest_tag" >> $GITHUB_ENV
+
+      - name: Install docs dependencies
+        working-directory: doc-site
+        run: pip install -r requirements.txt
+
+      - name: Update doc site for release
+        if: github.event.action == 'released' && github.ref_name != env.LATEST_TAG
+        working-directory: doc-site
+        run: mike deploy ${{ github.event.release.tag_name }} --push
+
+      - name: Update doc site for latest release
+        if: github.event.action == 'released' && github.ref_name == env.LATEST_TAG
+        working-directory: doc-site
+        run: mike deploy ${{ github.event.release.tag_name }} latest -u --push
+
+      - name: Update doc site for `main` branch
+        if: ${{ github.event_name == 'push' }}
+        working-directory: doc-site
+        run: mike deploy head --push
+
+      - name: Test building the doc site but do not deploy it
+        if: ${{ github.event_name == 'pull_request' }}
+        working-directory: doc-site
+        run: mkdocs build

.gitignore

@@ -1 +1,2 @@
 .DS_Store
+.vscode/launch.json

README.md

@@ -0,0 +1,3 @@
+# Specify version of MkDocs Material
+FROM squidfunk/mkdocs-material:latest
+RUN pip install mike

doc-site/.devcontainer/Dockerfile

@@ -0,0 +1,20 @@
+{
+	"name": "MkDocs Material editor",
+	"dockerFile": "Dockerfile",
+	"workspaceMount": "source=${localWorkspaceFolder}/doc-site,target=/docs,type=bind",
+	"workspaceFolder": "/docs",
+	"customizations": {
+		"vscode": {
+			"settings": {
+				"terminal.integrated.shell.linux": "/bin/sh"
+			},
+			"extensions": [
+				"ms-vscode-remote.remote-containers"
+			]
+		}
+	},
+	"forwardPorts": [
+		8001
+	],
+	"postStartCommand": "mkdocs serve -a localhost:8001",
+}

doc-site/.devcontainer/devcontainer.json

@@ -0,0 +1,2 @@
+venv
+site

doc-site/.gitignore

@@ -0,0 +1,74 @@
+# Zeto Documentation Site
+
+This directory is based on the [Hyperledger documentation template](https://github.com/hyperledger-labs/documentation-template). The template utilizes MkDocs (documentation at [mkdocs.org](https://www.mkdocs.org)) and the theme Material for MkDocs (documentation at [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/)). Material adds a number of extra features to MkDocs, and Hyperledger repositories can take advantage of the theme's [Insiders](https://squidfunk.github.io/mkdocs-material/insiders/) capabilities.
+
+[Material for MkDocs]: https://squidfunk.github.io/mkdocs-material/
+[Mike]: https://github.com/jimporter/mike
+
+## Prerequisites
+
+To test the documents and update the published site, the following tools are needed:
+
+- A Bash shell
+- git
+- Python 3
+- The [Material for Mkdocs] theme.
+- The [Mike] MkDocs plugin for publishing versions to gh-pages.
+  - Not used locally, but referenced in the `mkdocs.yml` file and needed for
+    deploying the site to gh-pages.
+
+### git
+
+`git` can be installed locally, as described in the [Install Git Guide from GitHub](https://github.com/git-guides/install-git).
+
+### Python 3
+
+`Python 3` can be installed locally, as described in the [Python Getting Started guide](https://www.python.org/about/gettingstarted/).
+
+### Virtual environment
+
+It is recommended to install your Python dependencies in a virtual environment in case you have other conflicting Python installations on your machine. This also removes the need to install these packages globally on your computer.
+
+```bash
+cd doc-site
+python3 -m venv venv
+source venv/bin/activate
+```
+
+### Mkdocs
+
+The Mkdocs-related items can be installed locally, as described in the [Material
+for Mkdocs] installation instructions. The short, case-specific version of those
+instructions follow:
+
+```bash
+pip install -r requirements.txt
+```
+
+### Verify Setup
+
+To verify your setup, check that you can run `mkdocs` by running the command `mkdocs --help` to see the help text.
+
+## Useful MkDocs Commands
+
+The commands you will usually use with `mkdocs` are:
+
+- `mkdocs serve` - Start the live-reloading docs server.
+- `mkdocs build` - Build the documentation site.
+- `mkdocs -h` - Print help message and exit.
+
+## Adding Content
+
+The basic process for adding content to the site is:
+
+- Create a new markdown file under the `docs` folder
+- Add the new file to the table of contents (`nav` section in the `mkdocs.yml` file)
+
+If you are using this as a template for creating your own documentation, please see [the instructions for customization](./docs/index.md).
+
+## Repository layout
+
+    mkdocs.yml    # The configuration file.
+    docs/
+        index.md  # The documentation homepage.
+        ...       # Other markdown pages, images and other files.

doc-site/README.md

@@ -0,0 +1,34 @@
+# Basic Concepts
+
+Zeto is built on the following fundamental concepts.
+
+## Onchain state model: UTXO
+
+The smart contract for a token economy must maintain states onchain. There are two ways to model states: account vs. UTXO.
+
+- The account model is very popular in the existing token standards such as ERC20/721/1155 etc. Each account is an entry in a map that the smart contract maintains, with the value being the account's state such as current balance, or list of assets. A transaction updates the states of one or more accounts.
+- The UTXO model works very differently, by creating states that are independent to each other. Each UTXO state is in one of two modes: unspent or spent. A transaction consumes unspent states, at which point they become spent, and produces new (unspent) states. Each UTXO state specifies the spending rules that must be satisfied when a transaction attempts to spend it.
+
+### UTXO for better parallel processing
+
+The UTXO model is adopted for Zeto instead of the account model, for better support of parallel processing. Due to the necessity of maintaining private states offchain in order to achieve privacy, the client must continuously keep their private states in sync with the smart contract. Using an account model makes it more difficult to achieve this because incoming transfers from other parties would invalidate an account's state, making the account owner unable to spend from its account unless the private state has been sync'ed again. Solutions to this issue, often referred to as front-running, typically involve a spending window with a pending queue. One example of this is [Zether](https://eprint.iacr.org/2019/191), which describes an `epoch` construct with pending transaction queues to address the front-running problem. Using epochs results in limited parallel processing of transactions from the same spending account.
+
+With a UTXO model, on the other hand, since each state is independent of the others, spending multiple UTXOs at the same time, even if they call come from the same owner, can be easily achieved.
+
+### UTXO for better anonymity
+
+With an account model, given that the states are mapped to the owning accounts in the onchain storage, there is an inherent challenge to anonymity, where checking which account was updated by a transaction would reveal the counterparties of a transaction. This could be mitigated by using anonymity sets, where more accounts besides the real sender and receiver of a transaction are updated with an encrypted zero value. However this increases the gas cost of transactions.
+
+With the UTXO model, since each UTXO state describes its own ownership, in a masked form (`hash(value, owner public key, salt)`), there is no revelation of the owning account when a UTXO is spent or produced. Furthermore, the entitlement to spend the private UTXO token is demonstrated by the ZK proof, rather than the transaction signer (aka `msg.sender`). This allows Zeto transactions to be signed by any accounts. Zeto clients are encouraged to use one-time signing keys to submit transactions, such as those from an [HD wallet](https://en.bitcoin.it/wiki/BIP_0032).
+
+## Commitments
+
+Each UTXO is tracked by the smart contract as a hash of the following components: value (for fungible Zeto) or token Id (for non-fungible Zeto), owner public key and salt. These are called commitments. They serve several important purposes:
+
+- Representing the existence of a Zeto token. A Zeto token's value is recognized only if it's commitment is known to the smart contract that maintains the token economy.
+- Hiding the secret information about a Zeto token. The value or token Id and the ownership information are hidden behind the secure hash string, which can not be reverse-engineered back to the secerts.
+- Acting as the public inputs for verifying ZK proofs. All Zeto transactions consume some existing UTXOs and produce some new UTXOs. For the smart contract to be convinced that a transaction is valid, a ZK proof must be provided that demonstrates a transaction proposal conforming to the policies of the specific token implementation. The commitment hashes are critical public inputs in almost all such ZK proof verifications.
+
+## Finality
+
+Each transaction's validity is verified by the smart contract before allowing the proposed input UTXOs to be nullified and the output UTXOs to come into existence. In other words, this is not an optimistic design and as such does not rely on a multi-day challenge period before a transaction is finalized. Every transaction is immediately finalized once it's mined into a block.

doc-site/docs/assets/paladin-icon-light.png

@@ -0,0 +1,22 @@
+# How Zeto tokens work
+
+![Zeto overview](../images/overview.jpg)
+
+- Party A owns 3 Zeto tokens at the beginning: `#1, #2, #3`. The 3 tokens have been minted in the Zeto smart contract and represented by their commitments, aka `hash(value, owner public key, salt)`
+  - As the owner of the tokens, party A also has access to the secrets that the commitments can be opened to, namely the value and salt. The secrets are represented as private states: `s1, s2, s3`
+  - How party A obtained the secrets for the owned tokens, is dependent on the specific Zeto implementation. It can be from offchain channels or from onchain (encrypted) data
+- Party A sends transaction `Tx1` to transfer some value to party B. The transaction consumes 2 tokens `#1, #2` and produces 2 new tokens `#4, #5`. `#5` is the value to be transferred to party B. `#4` is the remainder value that goes back to party A
+  - Even though party A knows the secrets of `#5`, they won't be able to spend the token because party A is not the owner of the token.
+  - Ownership verification is enforced by the Zeto smart contract when it verifies the zero knowledge proofs. Each ZKP circuit ensures that the sender's private key is used as a private input signal to derive the public key, which is then hashed to calculate the commitments
+- Party B sends transaction `Tx2` to transfer some value to party C. This works the same as `Tx1`
+- All parties get the commitments, `#1, #2, ... #7`, from the onchain events
+
+The above diagram illustrates that the secrets are transmitted from the sender to the receiver in an off-chain secure channel. Other means of sharing the secrets are avaiable in Zeto token implementations. For instance, the [Zeto_AnonEnc](https://github.com/hyperledger-labs/zeto/blob/main/solidity/contracts/zeto_anon_enc.sol) implementation includes encrypted secrets in the transaction input, and emits an event with the encrypted values. The encrypted values can only be decrypted by the receiver.
+
+## EC Cryptography
+
+Performing key pair operations, such as deriving the public key from the private key, in the ZKP circuit requires ZKP-friendly curves, for which we picked [Babyjubjub](https://docs.iden3.io/publications/pdfs/Baby-Jubjub.pdf) instead of the regular Ethereum curve (secp256k1).
+
+## Transaction Signing
+
+Another implication to the usage of ZKPs as transaction validity proof and the usage of the Babyjubjub curve, is that the signer of the transaction, eg. `msg.sender`, no longer bears the same significance as in other token implementations such as ERC20, ERC721, where the signer's EVM account address holds the actual assets. In Zeto tokens, it's the Babyjubjub public keys that hold the entitlement to spend the tokens. In fact, the applications are encouraged to use a different signing key for each transaction, to avoid leaking transaction behaviors and breaking anonymity.

doc-site/docs/assets/paladin-logo-dark.svg

@@ -0,0 +1,18 @@
+# Asking a Question
+
+!!! tip
+
+    * check the [FAQs](../faqs.md) to see if your question has already been asked.
+    * make sure you provide all relevant details.
+    * include information about what you have already tried.
+    * review [How to Ask Technical Questions to Get Quality Answers](https://opensource.com/life/16/10/how-ask-technical-questions) prior to asking your question.
+
+## Chat
+
+[Hyperledger’s Discord server](https://discord.gg/hyperledger) is the place to go for real-time chat about everything from quick help to involved discussions.
+
+For general Zeto discussions, join the Discord server and visit _Labs/Zeto_.
+
+## Mailing Lists
+
+The Paladin mailing list is hosted by the Hyperledger Foundation: https://lists.lfdecentralizedtrust.org.