💱 narrative done; last technicals

JFWooten4 · ElliotFriend · commit 77423112ec88 · 2025-08-08T16:38:12.000-05:00
diff --git a/docs/learn/fundamentals/liquidity-on-stellar-sdex-liquidity-pools.mdx b/docs/learn/fundamentals/liquidity-on-stellar-sdex-liquidity-pools.mdx
@@ -566,7 +566,7 @@ Issuers of [regulated assets](../../../tokens/control-asset-access.mdx#controlli
 | Authorized to maintain liabilities | Offers to trade $\mathcal{R}$ remain outstanding (and can be cancelled), but no new offers can be created |
 | Not authorized or doesn’t exist | New offer operation fails. Existing offers are cancelled at the time of deauthrization from the issuer (mainginting an existing frozen accoiunt balance) |
 
-In addition to controlling asset use in the orderbook, ssuers can slo enforce authorization and compliance controls on their assets deposited into AMMs (below with details on initial trustline configuration). These optional [trustline flags](../../fundamentals/transactions/list-of-operations.mdx#set-trustline-flags) configured before holding an asset ensure smooth compliance by revoking authorization to prevent an account under inestigation from further (automated) trading. The behavior of an $\mathcal{A}$-$\mathcal{A}$ AMM trustline depends on a few authorization possibilities:
+In addition to controlling asset use in the orderbook, ssuers can slo enforce authorization and compliance controls on their assets deposited into AMMs (below with details on initial trustline configuration). These optional [trustline flags](../../fundamentals/transactions/list-of-operations.mdx#set-trustline-flags) configured before holding an asset ensure smooth compliance by revoking authorization to prevent an account under inestigation from further (automated) trading. The behavior of an $\mathcal{A}$–$\mathcal{A}$ AMM trustline depends on a few authorization possibilities:
 
 | Permissions | Response |
 | --- | --- |
@@ -583,7 +583,7 @@ This design is necessary because an AMM may contain assets from two different is
 
 If the issuer of $\mathcal{A}$ or $\mathcal{A}$ fully revokes authorization after deposit, then the account will automatically withdraw from every liquidity pool containing that asset (and those pool-share trustlines will be deleted). We say that these AMM shares have been "redeemed." This action by the issuer also cancels any outstanding limit orders, as described in the first table.
 
-For example, consider an issuer of $\mathcal{A}$ revokes authorization for an account participating in the $\mathcal{A}$-$\mathcal{A}$, $\mathcal{A}$-$\mathcal{A}$, and $\mathcal{A}$-$\mathcal{A}$ AMMs. The account will redeem from $\mathcal{A}$-$\mathcal{A}$ and $\mathcal{A}$-$\mathcal{A}$, but it will not redeem from $\mathcal{A}$-$\mathcal{A}$. Thus issuers only have authroiztion control of their assets.
+For example, consider an issuer of $\mathcal{A}$ revokes authorization for an account participating in the $\mathcal{A}$–$\mathcal{A}$, $\mathcal{A}$–$\mathcal{A}$, and $\mathcal{A}$–$\mathcal{A}$ AMMs. The account will redeem from $\mathcal{A}$–$\mathcal{A}$ and $\mathcal{A}$–$\mathcal{A}$, but it will not redeem from $\mathcal{A}$–$\mathcal{A}$. Thus issuers only have authroiztion control of their assets.
 
 The ledger creates a [claimable balance](../transactions-specialized/claimable-balances.mdx) for each AMM asset in all redeemed pool-share trustlines, so long as there is a balance being withdrawn and the redeemer is not the issuer of that asset. In the latter case, asstets are simply burned through return to the issuer. The unconditional claimant of the claimable balance is the owner of the deleted pool-share trustline, but this account may not claim the regulated asset until duly authorized by the issuer.
 
@@ -801,7 +801,7 @@ An account can place a passive sell order via the Create Passive Sell Offer oper
 
 Each order in Stellar is quoted with an associated price and is represented as a ratio of the two assets in the order, one being the “quote asset” and the other being the “base asset”. This is to ensure there is no loss of precision when representing the price of the order (as opposed to storing the fraction as a floating-point number).
 
-Prices are specified as a `{numerator, denominator}` pair with both components of the fraction represented as 32-bit signed integers. The numerator is considered the base asset, and the denominator is considered the quote asset. When expressing a price of "Asset A in terms of Asset B,"”" the amount of B is the denominator (and therefore the quote asset), and A is the numerator (and therefore the base asset). As a good rule of thumb, it’s generally correct to be thinking about the base asset that is being bought/sold (in terms of the quote asset).
+Prices are specified as a `{numerator, denominator}` pair with both components of the fraction represented as 32-bit signed integers. The numerator is considered the base asset (like bananas), and the denominator is considered the quote asset (like dollars). When expressing a price of "Asset $\mathcal{A}$ in terms of Asset $\mathcal{B}$," the amount of $\mathcal{B}$ is the denominator (and therefore the quote asset), and $\mathcal{A}$ is the numerator (and therefore the base asset). <!-- TODO: break out to burn -->
 
 The order price you set is independent of the fee you pay for submitting that order in a transaction. Fees are always paid in lumens, and you specify them as a separate parameter when submitting the order to the network. To learn more about transaction fees, see our [section on Fees](../../fundamentals/fees-resource-limits-metering.mdx).
 
@@ -829,7 +829,7 @@ However, users don’t need to participate in the pool to take advantage of what
 
 ### Deterministic Pricing
 
-Instead of relying on the buy and sell orders of the SDEX, AMMs keep assets liquid 24/7 using pooled capital and a mathematical equation. AMMs hold two different assets in a liquidity pool, and the quantities of those assets (or reserves) are inputs for that equation (Asset A \* Asset B = k). If an AMM holds more of the reserve assets, the asset prices move less in response to a trade.
+Instead of relying on the buy and sell orders of the SDEX, AMMs keep assets liquid 24/7 using pooled capital and a mathematical equation. AMMs hold two different assets in a liquidity pool, and the quantities of those assets (or reserves) are inputs for that equation (Asset $\mathcal{A}$ \* Asset $\mathcal{B}$ = k). If an AMM holds more of the reserve assets, the asset prices move less in response to a trade.
 
 When you submit an..
 
@@ -899,9 +899,9 @@ A pool of deposits from accounts allows trades to execute against the predefined
 
 Any eligible participant can deposit assets into an AMM and receive pool shares representing their AMM ownership in return. If there are 150 total pool shares and one user owns 30, they are entitled to withdraw 20% of the liquidity pool asset at any time.
 
-Pool shares are similar to other assets on Stellar, but they cannot be transferred yet. You can only increase the number of pool shares you hold by depositing into a liquidity pool with the `LiquidityPoolDespositOp` and decrease the number of pool shares you hold by withdrawing from a liquidity pool with `LiquidityPoolWithdrawOp`.
+Pool shares are similar to other assets on Stellar, but they cannot be transferred yet. You can only increase the number of pool shares you hold by depositing into a liquidity pool with the `LiquidityPoolDespositOp` and decrease the number of pool shares you hold by withdrawing from a liquidity pool with `LiquidityPoolWithdrawOp`. Accordingly, pool shares cannot be sent in payments, sold using offers, or within claimable balances.
 
-A pool share has two representations. The full representation is used with `ChangeTrustOp`, and the hashed representation is used in all other cases. When constructing the asset representation of a pool share, the assets must be in lexicographical order. For example, A-B is in the correct order but B-A is not. This results in a canonical representation of a pool share.
+A pool share has two representations. The full representation is used with [`ChangeTrustOp`](../../fundamentals/transactions/list-of-operations.mdx#change-trust), and the hashed representation is used in all other cases. When constructing the asset representation of a pool share, the assets must be in lexicographical order. For example, $\mathcal{A}$–$\mathcal{B}$ is in the correct order but $\mathcal{B}$–$\mathcal{A}$ is not. This results in a canonical representation of a pool share.
 
 AMMs charge a fee on all trades and the participants in the liquidity pool receive a share of the fee proportional to their share of the assets in the liquidity pool. Participants collect these fees when they withdraw their assets from the pool. The [communitee agreed](https://groups.google.com/g/stellar-dev/c/Ofb2KXwzva0/m/kyYI8Es9AQAJ) on the current fixed rate of 0.30%, the fee used in UniswapV2. These charges are completely separate from the network fees.
 
@@ -912,7 +912,7 @@ Users need to establish trustlines to three different assets to participate in a
 An account needs a trustline for every pool share it wants to own. It is not possible to deposit into a liquidity pool without a trustline for the corresponding pool share. Pool share trustlines differ from trustlines for other assets in a few ways:
 
 1. A pool share trustline cannot be created unless the account already has trustlines that are authorized or authorized to maintain liabilities for the assets in the liquidity pool. See below for more information about how authorization impacts pool share trustlines.
-2. A pool share trustline requires 2 base reserves instead of 1. For example, an account (2 base reserves) with a trustline for asset A (1 base reserve), a trustline for asset B (1 base reserve), and a trustline for the A-B pool share (2 base reserves) would have a reserve requirement of 6 base reserves.
+2. A pool share trustline requires 2 base reserves instead of 1. For example, an account (2 base reserves) with a trustline for asset $\mathcal{A}$ (1 base reserve), a trustline for asset $\mathcal{B}$ (1 base reserve), and a trustline for the $\mathcal{A}$–$\mathcal{B}$ pool share (2 base reserves) would have a reserve requirement of 6 base reserves.
 
 ## Example Preamble
 
@@ -1157,7 +1157,7 @@ Here, we use `distributeAssets()` to establish trustlines and set up initial bal
 
 :::danger TODO
 
-Case when buying asset an asset, amount aquired > existing trustline amount.
+Case when buying asset an asset, amount aquired > existing trustline amount. implicates https://developers.stellar.org/docs/data/apis/horizon/api-reference/list-liquidity-pools (reserves)
 
 :::
 
@@ -1761,3 +1761,11 @@ func main() {
 ```
 
 </CodeExample>
+
+TODO list:
+
+- passive sell offers (with examples)
+- offerID resplution (https://developers.stellar.org/docs/data/apis/horizon/api-reference/get-offer-by-offer-id) ( more genreally https://developers.stellar.org/docs/data/apis/horizon/api-reference/resources/offers)
+- change op.s to one-liners, and incorpoate the max logic from https://github.com/stellar/new-docs/pull/590/files#diff-b038b9d2cd4d60b0cf8f43750d27e973fcd16fb7062f0b57ecda32e41ceb185eR731-R735
+  - https://developers.stellar.org/docs/learn/fundamentals/transactions/list-of-operations#liquidity-pool-deposit
+  - https://developers.stellar.org/docs/learn/fundamentals/transactions/list-of-operations#liquidity-pool-withdraw
