Update authority-tokens.md

Leaving some comments/questions from my first read-through (starting in alphabetical order in `tech-design`).

I'll probably have answered most of these by the time I'm finished going through all the docs, but it will do us well to make this as easy to read straight through as possible. 

General comments:
-----

- It'd be good to pick an entry-point/give an overview in the README. This way you can keep track of when different concepts are introduced, and contributors to the spec will have a better idea of what they can assume their audience knows.
- These docs are Liqwid-centric (and I believe I've skimmed earlier versions in the `liqwid-specs` repo) right now. We should decide whether we want to keep these specs focused on Liqwid, or if it would make sense to build up a small, hypothetical, minimum-viable-example that gets extended with Agora. The benefits of the former are that you can point to a real-world example of Agora's principles and implementation in practice; the latter could be more useful in a "here's how to integrate Agora into a project" tutorial

docs/tech-design/authority-tokens.md

@@ -18,7 +18,9 @@
 
 ## Authority Tokens
 
-In order to allow proposals to have a large number of potential effects, and to be extensible for different applications of governance, it is useful to have the effects be decided at a later time. In Ethereum systems, often times this is done by encoding some untyped data and calls to specific contract hashes. Compound encodes it with `address[] Proposal.targets` (the contracts to be called) and `bytes[] Proposal.calldatas` (the data to be passed). Of course, this doesn't quite translate to Cardano's EUTXO model, so we need to achieve this some different way.
+In order to allow proposals to have a large number of potential effects, and to be extensible for different applications of governance, it is useful to have the effects be decided at a later time. In Ethereum systems, often times this is done by encoding some untyped data and calls to specific contract hashes. [Compound](https://medium.com/compound-finance/compound-governance-5531f524cf68) encodes it with `address[] Proposal.targets` (the contracts to be called) and `bytes[] Proposal.calldatas` (the data to be passed). Of course, this doesn't quite translate to Cardano's EUTXO model, so we need to achieve this some different way.
+
+> Peter, 2022-01-24: "(...) be decided at a later time". later with respect to what? This could mean the effect is decided after the proposal, or that Agora doesn't specify a fixed set of effects at compile-time/run-time, etc. If it's simple enough to state, it may be helpful to say "it is useful to have the effects be decided when (...) is known.
 
 In order to allow this flexibility, there are two facts that we rely on:
 - We trust the community to validate the proposal entirely, including whether or not the effects encoded in it are written correctly. (This may mean we have a set of known and trusted effects we agree are correct and safe, collectively)
@@ -26,13 +28,31 @@ In order to allow this flexibility, there are two facts that we rely on:
 
 To achieve the former is rather simple, the effect validator's source code is available for anyone to look at, and it hashes correctly to the hash stored in the proposal itself. So, the LQ holders can decide on whether it is a positive for the system.
 
+> Peter, 2022-01-24: At this point in reading, its not obvious that "effect"s have validators. This is likely explained elsewhere, but this should be kept in mind when considering the order in which these specs should be read.
+> Peter, 2022-01-24: Update: after some more reading, it sounds like the Effect/GAT pair is basically a way to short-circuit the "normal" validation of a UTxO at one of the component addresses; it basically says "ignore your usual validation logic; I have a GAT, so this transaction must be approved".
+
 In order to achieve the latter, we must introduce some way to give effects authority to perform their actions.
 
 We do this by handing out "Governance Authority Tokens" (GATs) to each of the the effects belonging to a proposal after the proposal passes. When these authority tokens are *burned*, they act as a way of saying "the DAO validated this, so trust that I will ensure this transaction is correct".
 
-The components that need to be adjustable at a later point, will need to allow this as means for proving authority and validation of a transaction. So, for example, a Liqwid Market might need to have its parameters updated, the following diagram shows how this would happen after a proposal has successfully been voted on and passed:
+The components that need to be adjustable at a later point will need to allow this as means for proving authority and validation of a transaction. So, for example, a Liqwid Market might need to have its parameters updated, the following diagram shows how this would happen after a proposal has successfully been voted on and passed:
 
-![](../diagrams/GovernanceAuthorityToken.svg)
+> Peter, 2022-01-24: RE: "(...) need to be adjustable at a (...)": could it make more sense to say "adjusted via governance"?
+
+![Governance Authority Token UTxO flow diagram](../diagrams/GovernanceAuthorityToken.svg)
+
+> Peter, 2022-01-24: You should add a link to what conventions you're following for you UTxO flows to the README
+
+> Peter 2022-01-24: I think I see what's going on here, but it could use some annotations/additional description.
+> Tx1, a.) A proposal is closed via Tx1, and the transaction emits a continuing `Proposal` and `Governance` UtXO,
+>     along with an "Effect" UTxO (presumably identified in the content of the proposal). The Effect UTxO encodes effect `f` in it's validation logic.
+>     Question: where is this effect encoded?
+> Tx1, b.) In the same transaction, a GAT is minted and paid to the UTxO. 
+> Tx1, c.) The `min utxo` ADA is paid to the Effect UTxO from "user inputs". I'm not certain where this is, but I'm assuming it's accumulated during voting or something? What is it used for?   
+> Tx2, a.) The Effect UTxO and the component to be governed are consumed in transaction 2.  
+> Tx2, b.) The Market's usual validation logic is short-circuited since the GAT was burned, and the continuing Market UTxO updates its datum.
+> Tx2, c.) There is a continuing "Effect" UTxO; presumably, this serves as a proof that an effect has taken place? Meaning that a sequence of effects that require a particular order of execution can consume the output UTxO as a witness?
+> Tx2, d.) The min ADA is paid to "user outputs"; is this just "collateral" to make sure that the effect is executed in a timely fashion?
 
 As a result of this approach, there's a number of benefits, but also details we need to watch out for:
 
@@ -50,3 +70,8 @@ Having delegated the authority of *the entire system* in a single token is a lot
 - We have the transaction be executed by one of a number of community trusted members. This of course is something that is encoded in the effect, rather than anywhere else.
 
 Hopefully, this is sufficient to ensure the transactions are created correctly, and nothing unexpected slips in. This problem is no more complicated or dangerous than elsewhere where we delegate certain trust or authority to just the validation or movement of a token.
+
+
+> 2022-01-24, Peter: Have you considered placing the validator hash of the effect script in the token name? This could tie a proposal to a GAT to a validator, instead of having any GAT work with any effect script.
+
+> 2022-01-24, Peter: This section could use some additional explaination/pseudo-code of the what the GAT minting policy would look like and what additional validation logic would go into a govern-able component