Add Code Snippets for Liquidity Pools (#653)

overcat · web-flow · commit 9eaf72e180f3 · 2022-04-07T16:55:40.000-04:00
diff --git a/content/docs/glossary/liquidity-pool.mdx b/content/docs/glossary/liquidity-pool.mdx
@@ -160,6 +160,69 @@ function preamble() {
 }
 ```
 
+```python
+from decimal import Decimal
+from typing import List, Any, Dict
+
+from stellar_sdk import *
+
+server = Server("https://horizon-testnet.stellar.org")
+
+
+# Preamble
+def new_tx_builder(source: str) -> TransactionBuilder:
+    network_passphrase = Network.TESTNET_NETWORK_PASSPHRASE
+    base_fee = 100
+    source_account = server.load_account(source)
+    builder = TransactionBuilder(
+        source_account=source_account, network_passphrase=network_passphrase, base_fee=base_fee
+    ).set_timeout(30)
+    return builder
+
+
+# Returns the given asset pair in "protocol order."
+def order_asset(a: Asset, b: Asset) -> List[Asset]:
+    return [a, b] if LiquidityPoolAsset.is_valid_lexicographic_order(a, b) else [b, a]
+
+
+secrets = [
+    "SBGCD73TK2PTW2DQNWUYZSTCTHHVJPL4GZF3GVZMCDL6GYETYNAYOADN",
+    "SAAQFHI2FMSIC6OFPWZ3PDIIX3OF64RS3EB52VLYYZBX6GYB54TW3Q4U",
+    "SCJWYFTBDMDPAABHVJZE3DRMBRTEH4AIC5YUM54QGW57NUBM2XX6433P",
+]
+kps = [Keypair.from_secret(secret=secret) for secret in secrets]
+
+# kp0 issues the assets
+kp0 = kps[0]
+asset_a, asset_b = order_asset(Asset("A", kp0.public_key), Asset("B", kp0.public_key))
+
+
+def distribute_assets(
+        issuer_kp: Keypair, recipient_kp: Keypair, assets: List[Asset]
+) -> Dict[str, Any]:
+    builder = new_tx_builder(issuer_kp.public_key)
+    for asset in assets:
+        builder.append_change_trust_op(
+            asset=asset, limit="100000", source=recipient_kp.public_key
+        ).append_payment_op(
+            destination=recipient_kp.public_key,
+            asset=asset,
+            amount="100000",
+            source=issuer_kp.public_key,
+        )
+
+    tx = builder.build()
+    tx.sign(issuer_kp)
+    tx.sign(recipient_kp)
+    resp = server.submit_transaction(tx)
+    return resp
+
+
+def preamble() -> None:
+    resp1 = distribute_assets(kp0, kps[1], [asset_a, asset_b])
+    resp2 = distribute_assets(kp0, kps[2], [asset_a, asset_b])
+    # ...
+```
 </CodeExample>
 
 Here, we use `distributeAssets()` to establish trustlines and set up initial balances of two custom assets (`A` and `B`, issued by `kp1`) for two accounts (`kp2` and `kp3`). For someone to participate in the pool, they must establish trustlines to each of the asset issuers *and* to the pool share asset (explained below).
@@ -188,6 +251,19 @@ function establishPoolTrustline(account, keypair, poolAsset) {
 }
 ```
 
+```python
+pool_share_asset = LiquidityPoolAsset(asset_a=asset_a, asset_b=asset_b)
+
+
+def establish_pool_trustline(source: Keypair, pool_asset: LiquidityPoolAsset) -> Dict[str, Any]:
+    tx = (
+        new_tx_builder(source.public_key)
+            .append_change_trust_op(asset=pool_asset, limit="100000")
+            .build()
+    )
+    tx.sign(source)
+    return server.submit_transaction(tx)
+```
 </CodeExample>
 
 This lets the participants hold pool shares (refer to the discussion about [pool shares earlier](#liquidity-pool-participation) for details), which means now they can perform deposits and withdrawals.
@@ -223,6 +299,33 @@ function addLiquidity(source, signer, poolId, maxReserveA, maxReserveB) {
 }
 ```
 
+```python
+pool_id = pool_share_asset.liquidity_pool_id
+
+
+def add_liquidity(
+        source: Keypair,
+        pool_id: str,
+        max_reserve_a: Decimal,
+        max_reserve_b: Decimal,
+) -> dict[str, Any]:
+    exact_price = max_reserve_a / max_reserve_b
+    min_price = exact_price - exact_price * Decimal("0.1")
+    max_price = exact_price + exact_price * Decimal("0.1")
+    tx = (
+        new_tx_builder(source.public_key)
+            .append_liquidity_pool_deposit_op(
+            liquidity_pool_id=pool_id,
+            max_amount_a=f"{max_reserve_a:.7f}",
+            max_amount_b=f"{max_reserve_b:.7f}",
+            min_price=min_price,
+            max_price=max_price,
+        )
+            .build()
+    )
+    tx.sign(source)
+    return server.submit_transaction(tx)
+```
 </CodeExample>
 
 When depositing assets into a liquidity pool, you need to define your acceptable price bounds. In the above function, we allow for a +/-10% margin of error from the "spot price". This margin is **by no means a recommendation** and is chosen just for demonstration.
@@ -249,6 +352,38 @@ function removeLiquidity(source, signer, poolId, minReserveA, minReserveB) {
 }
 ```
 
+```python
+def remove_liquidity(
+        source: Keypair, pool_id: str, shares_amount: Decimal
+) -> dict[str, Any]:
+    pool_info = server.liquidity_pools().liquidity_pool(pool_id).call()
+    total_shares = Decimal(pool_info["total_shares"])
+    min_reserve_a = (
+            shares_amount
+            / total_shares
+            * Decimal(pool_info["reserves"][0]["amount"])
+            * Decimal("0.95") 
+    ) # 
+    min_reserve_b = (
+            shares_amount
+            / total_shares
+            * Decimal(pool_info["reserves"][1]["amount"])
+            * Decimal("0.95")
+    )
+    tx = (
+        new_tx_builder(source.public_key)
+            .append_liquidity_pool_withdraw_op(
+            liquidity_pool_id=pool_id,
+            amount=f"{shares_amount:.7f}",
+            min_amount_a=f"{min_reserve_a:.7f}",
+            min_amount_b=f"{min_reserve_b:.7f}",
+        )
+            .build()
+    )
+    tx.sign(source)
+    return server.submit_transaction(tx)
+```
+
 </CodeExample>
 
 Notice here that we specify the minimum amount. Much like with a strict-receive path payment, we're specifying that we're not willing to receive less than this amount of each asset from the pool. This effectively defines a minimum withdrawal price.
@@ -291,6 +426,45 @@ function getSpotPrice() {
 preamble().then(main);
 ```
 
+```python
+def main():
+    deposit_a = Decimal(1000)
+    deposit_b = Decimal(3000)  # maintain a 1:3 ratio
+    establish_pool_trustline(kps[1], pool_share_asset)
+    add_liquidity(kps[1], pool_id, deposit_a, deposit_b)
+    get_spot_price()
+
+    deposit_a = Decimal(2000)
+    deposit_b = Decimal(6000)  # maintain a 1:3 ratio
+    establish_pool_trustline(kps[2], pool_share_asset)
+    add_liquidity(kps[2], pool_id, deposit_a, deposit_b)
+    get_spot_price()
+
+    # kp1 takes all his/her shares out
+    balance = 0
+    for b in server.accounts().account_id(kps[1].public_key).call()["balances"]:
+        if (
+                b["asset_type"] == "liquidity_pool_shares"
+                and b["liquidity_pool_id"] == pool_id
+        ):
+            balance = Decimal(b["balance"])
+            break
+    if not balance:
+        raise
+    remove_liquidity(kps[1], pool_id, balance)
+    get_spot_price()
+
+def get_spot_price():
+    resp = server.liquidity_pools().liquidity_pool(pool_id).call()
+    amount_a = resp["reserves"][0]["amount"]
+    amount_b = resp["reserves"][1]["amount"]
+    spot_price = Decimal(amount_a) / Decimal(amount_b)
+    print(f"Price: {amount_a}/{amount_b} = {spot_price:.7f}")
+
+if __name__ == '__main__':
+    preamble()
+    main()
+```
 </CodeExample>
 
 ### Watching Liquidity Pool Activity
@@ -315,4 +489,19 @@ server.operations()
   });
 ```
 
+```python
+def watch_liquidity_pool_activity():
+    for op in (
+        server.operations()
+        .for_liquidity_pool(liquidity_pool_id=pool_id)
+        .cursor("now")
+        .stream()
+    ):
+        if op["type"] == "liquidity_pool_deposit":
+            print("Reserves deposited:")
+            for r in op["reserves_deposited"]:
+                print(f"    {r['amount']} of {r['asset']}")
+            print(f"    for pool shares: {op['shares_received']}")
+        # ...
+```
 </CodeExample>
