Flesh out the readme, add a todo

README.md

@@ -1 +1,35 @@
-# contracts
+# sundae-contracts
+
+This repository contains version 3 and onward of the smart contracts for the SundaeSwap Protocol.
+
+> Note: Version 1 consisted of the closed source Plutus v1 contracts written in 2021; Version 2 consisted of a short lived attempt to rewrite them in Plutus v2, before we decided to migrate to Aiken. It's also convenient, as we also released a "v2" of the UI, and so many were getting confused when we spoke of the "v2 contracts", not understanding the difference.
+
+## Layout
+
+The repository is organized as follows:
+ - validators: The core validator logic for all contracts
+ - lib:
+   - types: Any type definitions (such as datums and redeemers) used elsewhere in the code
+   - calculation: The math-heavy calculations for each order type
+ - lucid: Some lucid skeleton work for testing and benchmarking the contracts end to end
+ - tests:
+   - examples: Tests which print out example serialized datums and redeemers
+   - unit: Small, purpose focused tests of an individual unit of the contracts
+   - integration: End to end tests that evaluate an entire script context
+
+## Contract architecture
+
+At the highest level, the Sundae v3 protocol is implemented as an extensible set of pool and order contracts, which implement batched AMM order execution and collect protocol fees for doing so.
+
+Some notable differences from the v1 contracts:
+ - Scooper fees (now generically called protocol fees) are collected at the pool UTXO, and can be withdrawn to a specific treasury address by a treasury administrator.
+ - A pool enforces a "start time", before which no trades can happen.
+ - A pool has a starting fee, which decays over some period of time, to a final fee.
+ - A pool is not dependent on a specific order contract, only the structure of the order datum.
+ - An order can be owned by a generic multisig, including a "script" requirement.
+ - An order can donate funds to the pool, useful for protocols that want to build incentives for users
+ - An order can be defined as a "strategy", deferring the details of the order until a later date, so long as its signed by some public key
+ - The stake address attached to a pool can be updated by a treasury administrator
+ - The rewards earned by a pool can be withdrawn to the treasury as protocol fees
+ - Scoopers are not issued tokens to authorize them; they are defined in a global settings datum
+ - Scoopers define the order inputs are processed, rather than relying on what order they appear in the transaction

validators/pool.ak

@@ -319,6 +319,7 @@ validator(settings_policy_id: PolicyId) {
 
         expect Some(initial_lq) = math.sqrt(coin_a_amt_sans_rider * coin_b_amt)
 
+        // TODO: can we use own_script_hash here?
         let new_pool_ref = (settings_datum.pool_script_hash, new_pool_ref_token)
         let new_pool_nft = (settings_datum.pool_script_hash, new_pool_nft_token)
         let new_pool_lq = (settings_datum.pool_script_hash, new_pool_lp_token)
@@ -330,6 +331,7 @@ validator(settings_policy_id: PolicyId) {
         let mint_is_correct =
           value.from_minted_value(ctx.transaction.mint) == expected_mint
 
+        // TODO: can we use own_script_hash here?
         let funds_spent_to_pool =
           coin_a_amt_sans_rider >= 1 && coin_b_amt >= 1 && list.length(
             value.flatten(pool_output.value),
@@ -343,6 +345,7 @@ validator(settings_policy_id: PolicyId) {
         expect Some(metadata_output) =
           list.at(ctx.transaction.outputs, metadata_output_ix)
         expect metadata_output.address == settings_datum.metadata_admin
+        // TODO: can we use own_script_hash here?
         expect value.quantity_of(metadata_output.value, settings_datum.pool_script_hash, new_pool_ref_token) == 1
 
         expect InlineDatum(d) = pool_output.datum