Basic documentation (#66)

* documentation: start work on new document

* Intro and a diagram

* Update README

* Add some text on the scripts

* Add some TODOs

* detailed explanation of a transfer transaction

* Add paragraph on access control policy

---------

Co-authored-by: Jann Müller <jann@BL4FRCFK>

README.md

@@ -8,55 +8,60 @@ The POC is based on [CIP-0143](https://github.com/colll78/CIPs/blob/patch-3/CIP-
 
 # Architecture
 
-The system is designed so that all actions except the initial deployment of the programmable logic UTxOs can be performed through a web UI with browser-based wallets. The REST API therefore exposes a number of endpoints that produce fully-balanced-but-not-signed transactions. The intention is for the caller (web UI) to sign the transactions with the web-based wallet and submit them to the network. The backend uses blockfrost to query the blockchain. As a result, the server is pretty light-weight and does not even need its own database or a full cardano node.
+See [doc/architecture.md](doc/architecture.md)
 
-# Usage
-
-There is a CLI tool `wst-poc-cli` that performs the initial deployment of the system and runs the REST server. A signing key file is needed for the initial deployment but not for the operation of the server. A blockfrost token is needed for both the initial deployment.
-
-(TO DO - document CLI operations)
-
-# FAQs
-
-## How is this system different from Djed?
-
-Djed is an algorithmic stablecoin that is backed by Ada. In Djed we keep the entire reserves of the stablecoin in a UTxO that is controlled by the Djed contract. Every user of Djed can verify that the reserves exist and that there is enough Ada to pay out all Djed holders.
+## Contents of this repository
 
-This POC implements a _fiat-backed stablecoin_. This means that the reserves exist in a bank account outside of the blockchain, and we have to trust the issuer of the stablecoin that every token that's been issued on-chain is backed by one USD in the bank account.
+This repository contains 
+* Prototype implementation of CIP-0143 in Plutarch
+* Prototype implementation of Access Control Policy in Plutarch
+* Transaction building code for initial deployment, minting programmable tokens, transferring programmable tokens, adding addresses to the blacklist (ie. freezing), and seizing funds from blacklisted addresses. Based on sc-tools and cardano-api.
+* Emulator tests for the nominal cases (happy path) based on the actual ledger implementation and mainnet protocol parameters.
+* A user interface that implements the use cases using browser-based wallets. Based on next.js and lucid.
+* An OCI container image with the on-chain code, the off-chain code and the UI
 
-From a technical perspective, not having to manage the reserve on-chain makes the design of this POC somewhat simpler: We don't need to maintain a global state (the Djed UTxO) that all orders have to synchronise with. The challenge in this POC lies in the programmable token logic.
+With the container image it is possible to run the complete system locally with just a single command.
+There is no need to install the build toolchain or to operate a cardano node or related infrastructure.
+The image can even be used to interact with existing deployments of the POC.
 
-## How does the system scale?
-
-The core idea of the regulated stablecoin is to run a check every time the owner of some amount of regulated tokens changes. This check is performed by the _transfer logic script_, a plutus program that consults a list of sanctioned addresses to ensure that the receiving address is not on it. 
-
-The list of sanctioned addresses is the only data structure that (a) needs to be read from by every transaction of the transfer logic script and (b) gets changed regularly during the operation of the stablecoin.
-
-All other factors (number of scripts, script budget, max. number of transfer checks per transaction and so forth) are fixed and do not depend on the number of users.
+# Usage
 
-It is important to note that the list of sanctioned addresses scales in space (number of UTxOs), but working with the data structure is done in constant time due to the way the data is laid out.
+The easiest way to get started is by running the [wst](https://github.com/input-output-hk/wsc-poc/pkgs/container/wst) image locally:
 
-There is also no risk of UTxO congestion as the "system outputs" are used as reference inputs and not spent by user-to-user transfers. Each user-to-user transfer is processed independently.
+```bash
+docker run --rm -p 8080:8080 --env WST_BLOCKFROST_TOKEN=previewXYZ ghcr.io/input-output-hk/wst:pr-67 manage 08a8d0bb8717839931b0a594f7c28b0a3b7c78f6e9172e977e250eab7637d879.0 start
+```
 
-### Sanctioned Addresses
+Then open [localhost:8080/mint-authority.html](localhost:8080/mint-authority.html) in the browser.
 
-The list of sanctioned addresses is stored on-chain as a [_linked list_](https://github.com/Anastasia-Labs/plutarch-linked-list). This means that each entry (address) in the list is represented as a single transaction output that includes the address itself as well as a pointer to the next address in lexicographical order.
+Some notes
+1. `podman` or others can be used instead of `docker`
+2. `previewXYZ` must be replaced by a valid [blockfrost token](https://docs.blockfrost.io/#description/tokens) for the preview network
+3. The tag `pr-67` corresponds to PR 67
+4. `08a8d0bb8717839931b0a594f7c28b0a3b7c78f6e9172e977e250eab7637d879.0` is the transaction input that was used to initialise the deployment on the preview network.
 
-When checking a transfer, the transfer logic script is provided with a single reference input containing the relevant entry in the ordered linked list. 
+# Contributing
 
-The transfer transaction does not spend the linked list output, therefore the same linked list output can be used by many transactions in the same block and across multiple blocks.
+## Backend
 
-#### How many sanctioned addresses are there?
+* Run the tests with `cabal test all`
+* Enter the nix shell with `nix develop`
 
-Publicly available data on Tether (the largest fiat stablecoin) indicates that Tether has a total of [1990 sanctioned addresses](https://dune.com/phabc/usdt---banned-addresses), out of [109 million on-chain wallets](https://tether.io/news/how-many-usdt-on-chain-holders-are-there/) (Dec. 2024). This suggests that about 0.002 percent of addresses need to be blacklisted.
+## Frontend
 
-If our system achieved the scale of Tether then we would need about 1200 UTxOs to store the linked list. At current Ada prices this would amount to 1800 USD in min Ada UTxO deposits, an amount that will be refunded in its entirety when the linked list is deleted.
+```bash
+cd frontend
+npm install
+npm run dev
+```
 
-USDC, another fiat-stablecoin, currently has [264 blacklisted addresses](https://bloxy.info/txs/events_sc/0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48?signature_id=257159) and 3m users, with a blacklist ratio of about 0.009 percent.
+[!IMPORTANT]
+Please make sure that the UI can be exported to a set of static assets.
+This is necessary for the OCI image.
+In particular, the command `npm run export` should succeed.
 
-# Contributing
+## Issues
 
-* Run the tests with `cabal test all`.
-* Run `cabal run wst-poc-mock-server`  to start a mock server that serves fake data
+Check out [the issue tracker](https://github.com/input-output-hk/wsc-poc/issues)
 
 Bug reports and contributions are welcome!