From 6fed04fa74f38bb4b2a29f911fe1523b3e82d6b9 Mon Sep 17 00:00:00 2001 From: swampdaddy Date: Fri, 6 Nov 2026 16:33:55 -0500 Subject: [PATCH] Record confirmed AMM accounting and routing decisions --- README.md | 1 + docs/design-decisions.md | 40 ++++++++++++++++++++++++++++++++++++++++ docs/design.md | 2 ++ docs/open-questions.md | 2 ++ 4 files changed, 45 insertions(+) create mode 100644 docs/design-decisions.md diff --git a/README.md b/README.md index 97fc57f..092a122 100644 --- a/README.md +++ b/README.md @@ -14,6 +14,7 @@ The diagrams also propose periodic yield-support payments from the AMM to Liq, t - [Design and worked examples](docs/design.md) - [Open design questions](docs/open-questions.md) +- [Confirmed design decisions](docs/design-decisions.md) - [Original diagram index](diagrams/README.md) The Ethereum examples establish the proposed economic model. Solana needs its own implementation treatment for mint authority, Token-2022 share/transfer-hook accounting, reward distribution and withdrawal receipts. diff --git a/docs/design-decisions.md b/docs/design-decisions.md new file mode 100644 index 0000000..f4f9dd9 --- /dev/null +++ b/docs/design-decisions.md @@ -0,0 +1,40 @@ +# Confirmed design decisions + +Confirmed by Kyle through the design questionnaire on November 6, 2026. These decisions supersede the corresponding open questions and earlier alternatives; they describe the proposed design, not an implemented or deployed system. + +## Liquidity and ownership + +- Subsequent native-only deposits mint matching LIQ in the current pool reserve ratio. +- New LP shares are priced using net equity after the mint liability and accrued obligations, rather than gross reserves. Accrue rewards and charges before pricing entry. +- Matching LIQ minting creates an equal liability and therefore adds no net equity at the assumed 1:1 valuation; the native deposit contributes the new equity. +- LP interests are pooled fungible shares. Each share carries proportional reserve ownership, mint liability and accrued charges, including on transfers and partial exits. +- Withdrawals settle the allocated lien and accrued charges before returning the residual native/LIQ asset mix. +- Shortfall settlement uses 1:1 native-to-LIQ backing conversion. No additional equity buffer is selected beyond covering the lien and other obligations. + +## Trading and withdrawal routing + +- Use a constant-product curve as the initial design and simulation baseline, with swap fees still to be selected. +- The withdrawal proxy maximizes net native output among immediately executable routes, allowing split routing and respecting user minimum output and deadlines. +- Queued ordinary redemption is offered separately as an explicit user choice. +- Ordinary redemption capacity is reserved atomically against uncommitted eligible backing; gross staked balance is not necessarily immediately available liquidity. +- An AMM-routed withdrawal is a swap: LIQ enters pool reserves and the outstanding lien remains unchanged. +- Ordinary redemption burns LIQ and consumes ordinary backing without changing AMM reserves or its lien. +- Special-minted LIQ is fully fungible with ordinary LIQ. Only the designated AMM contract may use the new special-mint entrypoint, and ordinary withdrawal is enforced as proxy-only. + +## Rewards and yield-support obligations + +- Assess yield-support charges on the full outstanding special-mint lien. +- Match the applicable Liq reward-index changes rather than treating the diagram's 2.8% as a fixed rate. Exact chain-specific index integration remains to be verified. +- Pool-held LIQ earns ordinary rewards for LPs. +- Trading fees fund support payments; insufficient fee income reduces LP equity. +- If obligations exhaust available equity, preserve accrued debt and restrict operations that worsen the deficit. Allow repayment or recapitalization; detailed recovery and loss-allocation rules remain open. + +## Remaining design and verification work + +- Select swap fees and any protocol fee allocation. +- Verify Ethereum and Solana reward-index mechanics, including fee treatment, negative changes, reward realization and avoidance of double counting. +- Specify exact net-equity share issuance, rounding, partial-exit and last-LP formulas; validate protection against deposit-price manipulation. +- Define deficit detection, allowed recovery operations and loss allocation. +- Specify proxy quotes, reservation accounting, queue behavior and atomic settlement. +- Validate entry, swaps, reward payments, external redemption and full exit together in worked examples and simulations. +- Resolve native versus wrapped asset interfaces and chain-specific authority, callback and transfer-hook integration. diff --git a/docs/design.md b/docs/design.md index 03bb33c..1f47ce2 100644 --- a/docs/design.md +++ b/docs/design.md @@ -1,5 +1,7 @@ # Proposed design and worked examples +See [confirmed design decisions](design-decisions.md) for subsequent questionnaire answers, which supersede corresponding unresolved choices below. + ## Scope Separate pools on Ethereum and Solana: ETH/LiqETH and SOL/LiqSOL respectively. This document uses ETH examples. Details below distinguish the supplied design from review-derived accounting requirements; unresolved choices are in [open questions](open-questions.md). diff --git a/docs/open-questions.md b/docs/open-questions.md index 377cf05..3c9229f 100644 --- a/docs/open-questions.md +++ b/docs/open-questions.md @@ -1,5 +1,7 @@ # Open design questions +**Update:** See [confirmed design decisions](design-decisions.md) for the November 6 questionnaire answers. Those decisions supersede the corresponding unanswered items below; the original questions and inline responses are retained as review history. + ## Backing and external redemption - Are special-minted tokens fully fungible with ordinary LiqETH/LiqSOL, including redemption and reward rights? Yes