diff --git a/docs/README.md b/docs/README.md index ee3c46d..6f4d199 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,4 +1,4 @@ -# agora specification & documentation +# Agora specification & documentation This folder contains all of the specification and architecture documentation of agora. @@ -15,4 +15,4 @@ Agora makes extensive use of plutarch. So it's prerequisite for understanding th The following is a list of words/shorthands that are frequently used: - **Governance Token (GT)**: The token that holds value within the protocol and is used for voting, rewards, etc. _Examples: Liqwid's LQ_. -- **Authority Token (GAT)**: A token that delegates authority of a particular script / token. See [tech-design/authority-token.md](..) +- **Authority Token (GAT)**: A token that delegates authority of a particular script / token. See [tech-design/authority-token.md](./tech-design/authority-token.md) diff --git a/docs/diagrams/GovernanceAuthorityToken.dot b/docs/diagrams/GovernanceAuthorityToken.dot new file mode 100644 index 0000000..a4be5c4 --- /dev/null +++ b/docs/diagrams/GovernanceAuthorityToken.dot @@ -0,0 +1,238 @@ +digraph GovernanceAuthorityToken { + + rankdir = LR; + // Inputs: + + ////////////////////////////////////////////////////////////////////////////// + // governance in + governance_datum + [ shape = record + , label = + "{{ GovernanceState + }}" + ]; + + governance_addr + [ shape = record + , label = "{{ Script | Governance }}" + , style = "bold" + ]; + + ////////////////////////////////////////////////////////////////////////////// + // proposal in + proposal_datum + [ shape = record + , label = "{{ ProposalState }}" + ]; + + proposal_addr + -> proposal_redeemer + [style = "dashed", dir="none"]; + + proposal_addr + [ shape = record + , label = "{{ Script | Proposal }}" + , style = "bold" + ]; + + governance_datum + -> governance_addr [style = "dashed"]; + + governance_redeemer + [ shape = record + , label = "{{ GovernanceAction | MintAuthorityTokens }}" + ]; + + governance_addr + -> governance_redeemer + [style = "dashed", dir="none"]; + + proposal_datum -> proposal_addr [style = "dashed"]; + + ////////////////////////////////////////////////////////////////////////////// + // user wallet in + user_wallet_min_ada_in + [ shape = ellipse + , label = min utxo> + ]; + + user_wallet_in + [ shape = box + , label = "User Inputs" + , style = "bold" + , peripheries = 2 + ]; + + user_wallet_min_ada_in + -> user_wallet_in + [ style = "dashed" + ]; + + + tx1 + [ shape = diamond + , label = "Tx1" + , style = "bold" + ]; + + user_wallet_in -> tx1; + governance_addr -> tx1; + proposal_addr -> tx1; + + ////////////////////////////////////////////////////////////////////////////// + // governance out + governance_datum_out + [ shape = record + , label = + "{{ GovernanceState + }}" + ]; + + governance_addr_out + [ shape = record + , label = "{{ Script | Governance }}" + , style = "bold" + ]; + + + governance_datum_out + -> governance_addr_out + [ style = "dashed" + ]; + + ////////////////////////////////////////////////////////////////////////////// + // proposal out + proposal_datum_out + -> proposal_addr_out + [ style = "dashed" + ]; + + proposal_redeemer + [ shape = record + , label = + "{{ ProposalAction | FinishVoting }}" + ]; + + + proposal_datum_out + [ shape = record + , label = + "{{ ProposalState }}" + ]; + + proposal_addr_out + [ shape = record + , label = "{{ Script | Proposal }}" + , style = "bold" + ]; + + + ////////////////////////////////////////////////////////////////////////////// + // effect out + effect_governance_token_out + [ shape = ellipse + , label = + ]; + + effect_addr_out + [ shape = record + , label = "{{ Script | Effect }}" + , style = "bold" + ]; + + effect_governance_token_out + -> effect_addr_out + [ style = "dashed" + ]; + + effect_min_ada_out + -> effect_addr_out + [ style = "dashed" + ]; + + effect_min_ada_out + [ shape = ellipse + , label = min utxo> + ]; + + tx1 -> governance_addr_out; + tx1 -> proposal_addr_out; + tx1 -> effect_addr_out; + + ////////////////////////////////////////////////////////////////////////////// + ////////////////////////////////////////////////////////////////////////////// + + ////////////////////////////////////////////////////////////////////////////// + // effect in + effect_addr_out2 + [ shape = record + , label = "{{ Script | Effect }}" + , style = "bold" + ]; + + ////////////////////////////////////////////////////////////////////////////// + // market in + market_addr_in + [ shape = record + , label = "{{ Script | Market }}" + , style = "bold" + ]; + + market_datum_in + [ shape = record + , label = "{{ MarketState | params: A }}" + ]; + + market_datum_in + -> market_addr_in + [ style = "dashed" + ]; + + ////////////////////////////////////////////////////////////////////////////// + // market out + market_addr_out + [ shape = record + , label = "{{ Script | Market }}" + , style = "bold" + ]; + + market_datum_out + [ shape = record + , label = "{{ MarketState | params: f(A) }}" + ]; + + market_datum_out + -> market_addr_out + [ style = "dashed" + ]; + + tx2 + [ shape = diamond + , label = "Tx2" + , style = "bold" + ]; + + user_wallet_min_ada_out + [ shape = ellipse + , label = min utxo> + ]; + + user_wallet_out + [ shape = box + , label = "User Outputs" + , style = "bold" + , peripheries = 2 + ]; + + user_wallet_min_ada_out + -> user_wallet_out + [ style = "dashed" + ]; + + effect_addr_out -> tx2; + market_addr_in -> tx2; + tx2 -> user_wallet_out; + tx2 -> effect_addr_out2; + tx2 -> market_addr_out; + +} diff --git a/docs/diagrams/GovernanceAuthorityToken.png b/docs/diagrams/GovernanceAuthorityToken.png new file mode 100644 index 0000000..60878f1 Binary files /dev/null and b/docs/diagrams/GovernanceAuthorityToken.png differ diff --git a/docs/diagrams/GovernanceAuthorityToken.svg b/docs/diagrams/GovernanceAuthorityToken.svg new file mode 100644 index 0000000..fcaee17 --- /dev/null +++ b/docs/diagrams/GovernanceAuthorityToken.svg @@ -0,0 +1,322 @@ + + + + + + +GovernanceAuthorityToken + + + +governance_datum + +GovernanceState + + + +governance_addr + +Script + +Governance + + + +governance_datum->governance_addr + + + + + +governance_redeemer + +GovernanceAction + +MintAuthorityTokens + + + +governance_addr->governance_redeemer + + + + +tx1 + +Tx1 + + + +governance_addr->tx1 + + + + + +proposal_datum + +ProposalState + + + +proposal_addr + +Script + +Proposal + + + +proposal_datum->proposal_addr + + + + + +proposal_redeemer + +ProposalAction + +FinishVoting + + + +proposal_addr->proposal_redeemer + + + + +proposal_addr->tx1 + + + + + +user_wallet_min_ada_in + +ADA: +min utxo + + + +user_wallet_in + + +User Inputs + + + +user_wallet_min_ada_in->user_wallet_in + + + + + +user_wallet_in->tx1 + + + + + +governance_addr_out + +Script + +Governance + + + +tx1->governance_addr_out + + + + + +proposal_addr_out + +Script + +Proposal + + + +tx1->proposal_addr_out + + + + + +effect_addr_out + +Script + +Effect + + + +tx1->effect_addr_out + + + + + +governance_datum_out + +GovernanceState + + + +governance_datum_out->governance_addr_out + + + + + +proposal_datum_out + +ProposalState + + + +proposal_datum_out->proposal_addr_out + + + + + +effect_governance_token_out + +GovernanceAuthorityToken: 1 + + + +effect_governance_token_out->effect_addr_out + + + + + +tx2 + +Tx2 + + + +effect_addr_out->tx2 + + + + + +effect_min_ada_out + +ADA: +min utxo + + + +effect_min_ada_out->effect_addr_out + + + + + +effect_addr_out2 + +Script + +Effect + + + +market_addr_in + +Script + +Market + + + +market_addr_in->tx2 + + + + + +market_datum_in + +MarketState + +params: A + + + +market_datum_in->market_addr_in + + + + + +market_addr_out + +Script + +Market + + + +market_datum_out + +MarketState + +params: f(A) + + + +market_datum_out->market_addr_out + + + + + +tx2->effect_addr_out2 + + + + + +tx2->market_addr_out + + + + + +user_wallet_out + + +User Outputs + + + +tx2->user_wallet_out + + + + + +user_wallet_min_ada_out + +ADA: +min utxo + + + +user_wallet_min_ada_out->user_wallet_out + + + + + diff --git a/docs/diagrams/Makefile b/docs/diagrams/Makefile new file mode 100644 index 0000000..61135ce --- /dev/null +++ b/docs/diagrams/Makefile @@ -0,0 +1,27 @@ +SHELL := /usr/bin/env bash + +.PHONY: diagrams clean_diagrams + +usage: + @echo "usage: make [OPTIONS]" + @echo + @echo "Available commands:" + @echo " diagrams -- Create the diagrams from .dot files" + @echo " clean_diagrams -- Delete the diagram images" + +DOT_INPUTS := $(wildcard ./*.dot) +DOT_SVGS := $(patsubst %.dot,%.svg,$(DOT_INPUTS)) +DOT_PNGS := $(patsubst %.dot,%.png,$(DOT_INPUTS)) + +diagrams: $(DOT_SVGS) $(DOT_PNGS) + @echo $(DOT_SVGS) + +clean_diagrams: + rm $(DOT_SVGS) + rm $(DOT_PNGS) + +%.png: %.svg + convert $< $@ + +%.svg: %.dot + dot -Tsvg $< -o $@ diff --git a/flake.nix b/flake.nix index fa687a4..6b00c58 100644 --- a/flake.nix +++ b/flake.nix @@ -292,6 +292,8 @@ haskellPackages.record-dot-preprocessor entr gnumake + + graphviz ]; additional = ps: [ ps.plutarch ps.plutus-ledger ];