Document single-sided Liq AMM design and original diagrams

docs/design.md

@@ -0,0 +1,84 @@
+# Proposed design and worked examples
+
+## 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).
+
+## 1. Single-sided liquidity entry
+
+The supplied diagram shows an LP depositing 100 ETH into the AMM. Liq specially mints 100 LiqETH into the pool, backed by the deposited assets and associated controls. The pool records 100 LiqETH of mint liability against the position.
+
+| Item | Amount |
+| --- | ---: |
+| Native contribution | 100 ETH |
+| Specially minted inventory | 100 LiqETH |
+| Mint liability | 100 LiqETH |
+| Trading reserves | 100 ETH + 100 LiqETH |
+| Net LP position at assumed 1:1 settlement | 100 ETH equivalent |
+
+The two trading reserves are not two independently funded LP contributions. LP entitlement is the residual after liability settlement. A conventional unrestricted LP burn/withdrawal must not bypass that settlement.
+
+## 2. Periodic payment
+
+The supplied diagram shows a crank triggering a payment from the pool to Liq, labeled 2.8% APY, at the same frequency as Ethereum mainnet payments.
+
+The rate is a proposed diagram input, not a verified staking rate or an agreed implementation parameter. Assessment base, accrual convention, reward destination, funding source and missed-payment behavior remain open. A crank executes accounting/payment; it does not produce yield.
+
+Review recommendation: accrue charges by elapsed time or an explicitly selected index and settle accrued amounts before withdrawals. Distinguish actual staking income, trading fees, subsidy and LP-principal expenditure.
+
+## 3. Withdrawal examples
+
+Assumptions for these illustrations: a 100-LiqETH liability, 1:1 ordinary backing conversion, no accrued charges and no settlement fees.
+
+### 105 ETH / 95 LiqETH
+
+1. Allocate the position's reserves and liability.
+2. Transfer 5 ETH from its reserves into ordinary Liq backing.
+3. Mint 5 ordinarily backed LiqETH.
+4. Burn 100 LiqETH and discharge the 100-LiqETH special-mint liability.
+5. Return 100 ETH to the LP.
+
+Step 2 is the necessary economic interpretation of the diagram's “mint and burn” gap treatment. Minting and burning without supplying the missing backing does not discharge the economic obligation.
+
+### 95 ETH / 105 LiqETH
+
+1. Burn 100 LiqETH and discharge the liability.
+2. Return 95 ETH and the remaining 5 LiqETH to the LP.
+
+Surplus LiqETH must retain its normal backing and redemption rights.
+
+### Constant-product qualification
+
+The supplied 105/95 and 95/105 figures are illustrative balances, not exact fee-free constant-product outcomes from 100/100. The initial product is 10,000; 105 × 95 is 9,975.
+
+- At 105 ETH, constant-product reserves would contain approximately 95.238095 LiqETH; settling the gap returns approximately 100.238095 ETH.
+- At 95 ETH, reserves would contain approximately 105.263158 LiqETH; settlement returns 95 ETH + 5.263158 LiqETH.
+
+Actual settlement returns the calculated residual, accounting for fees, charges and losses; it does not guarantee the original native contribution.
+
+## 4. Baseline solvency condition
+
+Let E be immediately available ETH, L be LiqETH available to burn, and D be the outstanding special-mint liability, all normalized to the relevant units.
+
+Under enforceable 1:1 liability settlement:
+
+```text
+required ETH for liability settlement = max(D - L, 0)
+E >= max(D - L, 0)
+equivalently: E + L >= D
+```
+
+Pool-held LiqETH cancels liability; it is not counted as independent external collateral. The condition depends on actual settlement rights and correct recognition of rewards, redemptions and other obligations.
+
+Review recommendation: evaluate after every balance-changing operation, including LP removal, fee extraction, yield-support payment, minting and backing settlement—not only swaps. Define an equity buffer separately if one is required.
+
+For the initial constant-product 100/100 pool, swaps alone preserve E + L >= 200 while D = 100. The baseline condition therefore does not constrain those ordinary swaps. Solvency does not establish immediate external-redemption liquidity.
+
+## 5. Integration boundaries
+
+MCP context consulted on November 6, 2026:
+
+- `wire-ethereum`, reviewed commit `6cb712bb36244472471ee0e03f02778551e15679`: separate LiqETH token, accounting, staking, withdrawal and yield surfaces.
+- `capital-staking`, reviewed commit `7a43dc9202a76a89110f49031bc20e90968a048b`: authorized LiqSOL minting, Token-2022 share accounting and transfer hooks, distribution and withdrawal receipts.
+
+These summaries do not establish a current live implementation of special AMM-backed issuance. Special minting, redemption settlement, reward treatment and backing recognition require explicit integration design.

docs/open-questions.md

@@ -0,0 +1,47 @@
+# Open design questions
+
+## Backing and external redemption
+
+- Are special-minted tokens fully fungible with ordinary LiqETH/LiqSOL, including redemption and reward rights?
+- How does Liq recognize AMM-controlled assets as backing without double counting assets and token claims?
+- When a trader takes LIQ out of the AMM and redeems through Liq, who supplies the native asset and how does the AMM liability change?
+- Can Liq draw backing directly from the AMM, or does redemption create a payable? How does either route affect reserves and the AMM curve?
+- How are settled claims prevented from being paid or cancelled twice?
+
+## Multiple LPs and ownership
+
+- How is a later native-only deposit priced when reserves are imbalanced?
+- Does special minting always match the native contribution 1:1, or follow a different rule after initial bootstrap?
+- Are liabilities pooled pro rata or tracked per position?
+- How do partial exits, share transfers, position splits and additional deposits carry liability and accrued charges?
+- Are LP interests fungible tokens or position-specific records?
+
+## Yield-support payment
+
+- Is the charge assessed on total special issuance, net circulating exposure or another base?
+- Is 2.8% a fixed rate, an example or a dynamic benchmark? APR or compounded APY?
+- Do swap fees fund it, and what happens when fees are insufficient?
+- Does pool-held LIQ earn rewards? Who receives those rewards, and how are internal flows netted?
+- How are accrual, settlement cadence, missed cranks and arrears handled on each chain?
+
+## Curve and settlement
+
+- Is the swap invariant ordinary constant product or a specialized native/LIQ curve?
+- Is 1:1 conversion a principal accounting rule or an enforceable immediate redemption rate? How are reward indices and losses handled?
+- What additional equity/reserve buffer is required beyond E + L >= D?
+- How are reserve changes caused by payments and redemption settlement reflected in curve accounting?
+- Can withdrawals return both assets, as illustrated, or must native-only exit also be supported?
+
+## Chain-specific implementation
+
+- Ethereum: native ETH versus WETH reserve interface; permitted mint/burn and backing-transfer entrypoints; reward/accounting integration.
+- Solana: SOL versus wrapped SOL interface; authorized mint PDA, share accounting, transfer-hook accounts, reward treatment and withdrawal-receipt integration.
+- Both: atomic mint/liability creation, settlement-before-release, rounding direction, callback/reentrancy behavior and transaction failure rollback.
+
+## Next examples to draw and simulate
+
+1. External LIQ redemption while its special-mint liability remains open.
+2. A second LP depositing into a 150 ETH / 75 LiqETH pool.
+3. Partial withdrawal followed by LP-position transfer.
+4. Fees insufficient to meet accrued yield-support payments.
+5. Last LP exit with LIQ still circulating outside the pool.