# Zedger tokens

Zedger tokens are a class of assets that exist in the Dusk blockchain. They are specific in the privacy of transfers and ownership: regular blockchain users can't figure out the balances of other individuals.

## 1. Genealogy

There are several versions of Zedger tokens, each with different functionality. For each asset its governance shall decide which version to use. Upgrade is possible but difficult.

This document describes the following versions:
* Minimal, denoted by **ZedMin** which supports:
* Asset transfers between users;
* Governance which may stop and resume transfers;
* Inspectors which have access to the holders' registry and the transfer history.
* Basic
* Advanced

## 2. Zedger in the nutshell

Zedger token is a Dusk smart contract. One contract keeps transactions and registry of one asset only. As other contracts in the Dusk blockchain, it can be a regular owner of other tokens, Zedger or regular, and thus may accept and perform transactions in those tokens, for example to pay dividend.

### 2.1 Technology overview

Zedger token stores all transactions as leafs in an authenticated tree:

Each transaction contains encrypted recipient identity, balance, and other data:

In order to make a transfer a sender must spend some other transactions, totalling the current one (possibly making a cashback to themselves in order to make the equality hold). Those transactions are marked as *spent*:


Privacy is achieved by the following technique:
* Transaction amount and recipient address are always encrypted;
* Sender proves in zero knowledge (using Plonk ZKsnark) the ability to send that many tokens;
* It is not revealed which transactions are spent, but also it is not possible to spend the same transfer twice.

It is additionally ensured that an Inspector can decrypt all transactions (and thus can reconstruct all balances) by providing them encryption keys for all transfers.

Cryptographically, the Zedger protocol needs nothing beyond the state-of-the-art crypto schemes:
* Elliptic curve cryptography;
* Symmetric encryption;
* Plonk ZKSnarks.

### 2.2 User experience

Dusk user is able to operate with their Zedger token via a Dapp in a browser or a local wallet. An application needs some user secret in order to attempt decrypting a transfer; if the decryption succeeds the amount is added to the wallet. The software should be able to generate ZK proofs in order to make a spend, which would take some time (the order of a second). Once sent, a transfer can't be undone.

### 2.3 Setup

#### Address

Each user gets an address, technically a public key, which they use to receive transfers. In order for the Inspector to compose a holder registry, all address must be known beforehand (thus no way for one-time addresses).

## 3. Zedger security and privacy

Zedger protocol provides the following security guarantees:
* Only recipient address holder can spend a transfer.

Zedger protocol provides the following privacy guarantees:
* For users not affiliated with a sender or a recipient, there is no way to tell out who are sender and recipient of a transfer.

## 4. Zedger Versions

### 4.1. Minimal version and its features

ZedMin tokens are created with a fixed supply that is assigned to some address. The supply does not change and is publicly available.

### Transfer

**Functionality**: Alice sends Bob $C$ amount of the asset.

**Prerequisites**: Alice knows Bob's address $A$.

**Performance**: Alice must create a ZK proof of transfer correctness, which includes:
* Proof of asset holdings for Alice: expensive.
* Proof of Bob's address being in the holder's book: moderate.
* Proof of Bob and Inspector being able to decrypt the transfer: moderate.

### Registry

**Functionality**: Inspector reconstructs the balances of each holder by decrypting all transfers.

**Prerequisites**: All transfers must be stored.

**Performance**: This is a standard public-symmetric-key hybrid encryption, and it is fast. However, all transfers must be available for decryption. On the other hand, balances can be reconstructed faster from some previous state.

### Pause and Unpause

**Functionality**: Governance stops or resumes contract operations.

**Prerequisites**: No.

**Performance**: Operation just changes a single flag in the contract and thus is instant.

### Inspector

**Functionality**: Governance designates a public key on which all transfer data must be additionally encrypted. The public key may be secret-shared
to allow a threshold of human beings required to decrypt a transfer. This operation is one-time.

**Prerequisites**: No.

**Performance**: Operation is instant.

### Whitelist

**Functionality**: Governance creates a list of addresses eligible for asset holding and stores its Merkle root in the contract. This operation is one-time.

**Prerequisites**: No.

**Performance**: Operation is instant.

## 4.2 Basic version and its features

ZedBase tokens have all ZedMin token features plus the following.

### Mint

**Functionality**: Governance creates $C$ amount of the asset.

**Prerequisites**: No.

**Performance**: Governance keeps its transfers public so there is no ZK proof involved. Operation is fast.

### Burn

**Functionality**: Governance burns $C$ amount of the asset, spending some own transaction.

**Prerequisites**: No.

**Performance**: Governance keeps its transfers public so there is no ZK proof involved. Operation is fast.

### Forced transfer

**Functionality**: Governance marks certain transaction as spent and constructs another transaction of the same amount. This is implemented as an extra flag in the transaction that each transfer checks. The amount is kept private.

**Prerequisites**: No.

**Performance**: The only proof is that the new amount matches the original amount, which is moderately expensive.

## 4.3. Advanced version and its features

### Dividend handling

The Advanced version supports a single dividend asset paid to Zedger token holders. This is done by adding extra fields in the transaction with:
* Date $T$, the most recent for which the dividend has been accrued;
* Amount $Y_T$ of dividend accrued up to $T$.

Given both values, it is easy to recalculate the actual amount $Y_{curr}$ of dividend accrued to the assets in the transaction at any time $T_{curr}$. The amount $Y_{curr}$ is considered as the amount of dividend asset available to the user, and is displayed as such in both user and Inspector software.

When making a transfer at time $T_x$, user recalculates the accrued dividend according to dividend snapshots, adds the newly acquired asset to their balance, and then distributes the dividend asset among the newly created transactions while also setting the new timestamp. In addition to accumulating dividend, it is also possible to withdraw it to an external address.


### Dividend deposit

**Functionality**: Governance deposits dividend to the Zedger asset contract by making a transfer in the dividend asset contract.

**Prerequisites**: Governance must hold enough dividend.

**Performance**: Determined by the dividend contract.

### Set Dividend Payout date

**Functionality**: Governance declares how much dividend is accrued per asset unit at future time $T_f$.

**Prerequisites**: No.

**Performance**: Operation is public and instant.

### Dividend distribution

**Functionality**: When a dividend payout time comes, dividend is distributed to asset holders according to the payout rate and the amount of asset held. This happens automatically as both user software and the protocol consider the dividend distributed exactly in this time.

**Prerequisites**: No.

**Performance**: Operation is instant.

### Dividend withdrawal to external address

**Functionality**: Alice withdraws $Y$ of dividend asset to an external address in the blockchain. This is a regular transfer where the total amount of dividend asset in the newly created transactions is smaller by $Y$, with those $Y$ units being transferred to an external address in the same Dusk transaction.

**Prerequisites**: No.

**Performance**: As expensive as regular Transfer.

### Set Voting

**Functionality**: Governance sets up a poll and a date by which votes are accepted.
Technically it is arranged as Governance provides a public key on which all votes are encrypted. A secret key to each voting key is collectively owned so that only
a group of governance members may initiate the vote disclosure.

**Prerequisites**: No.

**Performance**: Operation is instant.

### Vote

**Functionality**: An asset holder submits a vote and its weight, which is proportional to the amount of assets the holder owns. Each transaction must be voted separately
though it is possible to aggregate some transactions before the voting date. In order to verify the eligibility, each transaction must carry a timestamp and it must
be verified against the voter date. As with regular transfers it is not possible to double vote since every transaction is nullified when votes. User adds their
encrypted vote to a registry where it is automatically accumulated.

**Prerequisites**: Voter must know the list of transfers at some moment during the voting period.

**Performance**: Operation is expensive. It can be made much cheaper though if a user precomputes its balance history and updates it each time a transfer is made. However
it requires extra storage write per transfer.

### Poll count

**Functionality**: Governance decrypts the poll accumulator with its decryption key.

**Prerequisites**: No.

**Performance**: Operation is instant.

### Add/remove governance members

This is handled by another smart contract in the Dusk blockchain, which serves as the governance representative.

### Change Inspector

**Functionality**: Governance changes the public key on which every transfer should encrypt.

**Prerequisites**: No.

**Performance**: The operation is cheap and instant.

### Whitelist modification

**Functionality**: Governance and/or Identity provider adds/removes an address to the list of eligible holders. This operation is public.

**Prerequisites**: No.

**Performance**: Operation is cheap.

### 4.4 Other features

#### 4.4.1 Easy

* Adding simple voting rules like lower bound on the total amount of holders or their asset that has voted.
* Batch: do multiple operations at the same time.
* Revoke voting rights: there must be a separate voters' list different from holders' list.

#### 4.4.2 Hard

* Complicated voting rules like minimal amount of asset to hold in order to be eligible to vote.

#### 4.4.3 N/A

* Delete contract: no benefit.
* Can transfer: transfer always succeeds if the proof passes.