From 47b47b3e185e3d26b899d3b3fac8aa81b46a0b12 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Jann=20M=C3=BCller?= <j-mueller@users.noreply.github.com>
Date: Mon, 9 Dec 2024 12:52:45 +0100
Subject: [PATCH] Add some documentation

---
 doc/architecture.md | 92 +++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 92 insertions(+)
 create mode 100644 doc/architecture.md

diff --git a/doc/architecture.md b/doc/architecture.md
new file mode 100644
index 0000000..0ded592
--- /dev/null
+++ b/doc/architecture.md
@@ -0,0 +1,92 @@
+# Architecture
+
+## Transactions
+
+The proof-of-concept must facilitate the following *transaction families*:
+
+1. Modify the access list. Replace the root of the merkle tree with a new hash.
+2. Transfer ownership of regulated token from one address to another
+3. Send regulated token back to token issuer (seizing funds)
+
+Each of those transaction families will be implemented as a stake validator and "yields to" scripts for minting and spending policies.
+
+Note that we don't consider the "setup transactions" here. For example, creating the initial access list, minting the access list NFT, first transfer of programmable token to programmable token validator. These are technically necessary to take the protocol from POC to product, but they are not required for the demonstration.
+
+### 1. Modifying the access list
+
+Transaction inputs
+- UTxOs (spending)
+  - Old access list UTxO
+- UTxOs (reference)
+  - Validator script 
+
+Transaction outputs
+- Access list UTxO
+  - Datum: New access list (root of merkle tree)
+  - Value: Access list NFT
+  - Address: Validator that yields to stake script
+
+Transaction logic
+- Redeemer:
+  * Min UTxO value
+  * Index of input in list of inputs
+- Conditions
+  * Signature of token issuer must be present
+  * No minting or burning of access list tokens
+  * New access list outputs meets the requirements
+
+### 2. Transfering ownership
+
+Transaction inputs
+- UTxOs (spending)
+  - Old token locking validator
+
+- UTxOs (reference)
+  - Validator script
+  - Access list UTxO with root of merkle tree
+
+Transaction outputs
+- Token locking UTxO
+  - Datum: New owner
+  - Value: 
+  
+Transaction logic
+- Redeemer:
+  * Min UTxO value
+  * Index of input in list of inputs
+  * Index of access list in list of reference inputs
+  * Proofs of non-membership in merkle tree for current owner and new owner
+- Conditions
+  * Signature of current owner must be present
+  * Both proofs of non-membership are valid
+  * No minting or burning of programmable tokens
+
+### 3. Seizing funds
+
+Transaction inputs
+- UTxOs (spending)
+  - Old token locking validator
+- UTxOs (reference)
+  - Validator script
+  - Access list UTxO
+
+Transaction outputs
+- Token locking UTxO
+  - Datum: Owner = minting authority
+  
+Transaction logic
+- Redeemer:
+  * Min UTxO value
+  * Index of input in list of inputs
+  * Index of access list in list of reference inputs
+  * Proof of membership of current owner in merkle tree
+- Conditions
+  * Signature of minting authority must be present
+  * Proof of membership is valid
+  * No minting or burning of programmable tokens
+
+## API
+
+A REST API must be implemented to faciliate the construction of transactions and to perform queries of ownership. It should have one endpoint for each of the three transactions listed above to construct a balanced transaction that can be signed by the user / minting authority.
+
+The API does not need any kind of authentication as all the keys and related data are managed by the clients.
\ No newline at end of file