feat: add AMM support

CHANGELOG.md

@@ -106,6 +106,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Function to parse the final account balances from a transaction's metadata
 - Function to parse order book changes from a transaction's metadata
 - Support for Ed25519 seeds that don't use the `sEd` prefix
+- Support for Automated Market Maker (AMM) transactions and requests as defined in XLS-30.
 - Add docs to`get_account_transactions` explaining how to allow pagination through all transaction history [#462]
 - Common field `ticket_sequence` to Transaction class
 

tests/unit/models/requests/test_amm_info.py

@@ -0,0 +1,16 @@
+from unittest import TestCase
+
+from xrpl.models.currencies import XRP, IssuedCurrency
+from xrpl.models.requests import AMMInfo
+
+_ASSET = XRP()
+_ASSET_2 = IssuedCurrency(currency="USD", issuer="rN6zcSynkRnf8zcgTVrRL8K7r4ovE7J4Zj")
+
+
+class TestAMMInfo(TestCase):
+    def test_asset_asset2(self):
+        request = AMMInfo(
+            asset=_ASSET,
+            asset2=_ASSET_2,
+        )
+        self.assertTrue(request.is_valid())

tests/unit/models/test_base_model.py

@@ -4,6 +4,7 @@
 
 from xrpl.models import XRPLModelException
 from xrpl.models.amounts import IssuedCurrencyAmount
+from xrpl.models.currencies import XRP, IssuedCurrency
 from xrpl.models.requests import (
     AccountChannels,
     BookOffers,
@@ -16,6 +17,8 @@
     SubmitOnly,
 )
 from xrpl.models.transactions import (
+    AMMBid,
+    AuthAccount,
     CheckCreate,
     Memo,
     Payment,
@@ -597,3 +600,72 @@ def test_to_xrpl_signer(self):
             ],
         }
         self.assertEqual(tx.to_xrpl(), expected)
+
+    def test_to_xrpl_auth_accounts(self):
+        tx = AMMBid(
+            account="r9LqNeG6qHxjeUocjvVki2XR35weJ9mZgQ",
+            asset=XRP(),
+            asset2=IssuedCurrency(
+                currency="ETH", issuer="rpGtkFRXhgVaBzC5XCR7gyE2AZN5SN3SEW"
+            ),
+            bid_min=IssuedCurrencyAmount(
+                currency="5475B6C930B7BDD81CDA8FBA5CED962B11218E5A",
+                issuer="r3628pXjRqfw5zfwGfhSusjZTvE3BoxEBw",
+                value="25",
+            ),
+            bid_max=IssuedCurrencyAmount(
+                currency="5475B6C930B7BDD81CDA8FBA5CED962B11218E5A",
+                issuer="r3628pXjRqfw5zfwGfhSusjZTvE3BoxEBw",
+                value="35",
+            ),
+            auth_accounts=[
+                AuthAccount(account="rNZdsTBP5tH1M6GHC6bTreHAp6ouP8iZSh"),
+                AuthAccount(account="rfpFv97Dwu89FTyUwPjtpZBbuZxTqqgTmH"),
+                AuthAccount(account="rzzYHPGb8Pa64oqxCzmuffm122bitq3Vb"),
+                AuthAccount(account="rhwxHxaHok86fe4LykBom1jSJ3RYQJs1h4"),
+            ],
+        )
+        expected = {
+            "Account": "r9LqNeG6qHxjeUocjvVki2XR35weJ9mZgQ",
+            "Asset": {"currency": "XRP"},
+            "Asset2": {
+                "currency": "ETH",
+                "issuer": "rpGtkFRXhgVaBzC5XCR7gyE2AZN5SN3SEW",
+            },
+            "BidMin": {
+                "currency": "5475B6C930B7BDD81CDA8FBA5CED962B11218E5A",
+                "issuer": "r3628pXjRqfw5zfwGfhSusjZTvE3BoxEBw",
+                "value": "25",
+            },
+            "BidMax": {
+                "currency": "5475B6C930B7BDD81CDA8FBA5CED962B11218E5A",
+                "issuer": "r3628pXjRqfw5zfwGfhSusjZTvE3BoxEBw",
+                "value": "35",
+            },
+            "AuthAccounts": [
+                {
+                    "AuthAccount": {
+                        "Account": "rNZdsTBP5tH1M6GHC6bTreHAp6ouP8iZSh",
+                    }
+                },
+                {
+                    "AuthAccount": {
+                        "Account": "rfpFv97Dwu89FTyUwPjtpZBbuZxTqqgTmH",
+                    }
+                },
+                {
+                    "AuthAccount": {
+                        "Account": "rzzYHPGb8Pa64oqxCzmuffm122bitq3Vb",
+                    }
+                },
+                {
+                    "AuthAccount": {
+                        "Account": "rhwxHxaHok86fe4LykBom1jSJ3RYQJs1h4",
+                    }
+                },
+            ],
+            "TransactionType": "AMMBid",
+            "SigningPubKey": "",
+            "Flags": 0,
+        }
+        self.assertEqual(tx.to_xrpl(), expected)

tests/unit/models/transactions/test_amm_bid.py

@@ -0,0 +1,66 @@
+from unittest import TestCase
+
+from xrpl.models.amounts import IssuedCurrencyAmount
+from xrpl.models.currencies import XRP, IssuedCurrency
+from xrpl.models.exceptions import XRPLModelException
+from xrpl.models.transactions import AMMBid, AuthAccount
+
+_ACCOUNT = "r9LqNeG6qHxjeUocjvVki2XR35weJ9mZgQ"
+_ASSET = XRP()
+_ASSET2 = IssuedCurrency(currency="ETH", issuer="rpGtkFRXhgVaBzC5XCR7gyE2AZN5SN3SEW")
+_AUTH_ACCOUNTS = [
+    AuthAccount(
+        account="rNZdsTBP5tH1M6GHC6bTreHAp6ouP8iZSh",
+    ),
+    AuthAccount(
+        account="rfpFv97Dwu89FTyUwPjtpZBbuZxTqqgTmH",
+    ),
+    AuthAccount(
+        account="rzzYHPGb8Pa64oqxCzmuffm122bitq3Vb",
+    ),
+    AuthAccount(
+        account="rhwxHxaHok86fe4LykBom1jSJ3RYQJs1h4",
+    ),
+]
+_LPTOKEN_CURRENCY = "5475B6C930B7BDD81CDA8FBA5CED962B11218E5A"
+_LPTOKEN_ISSUER = "r3628pXjRqfw5zfwGfhSusjZTvE3BoxEBw"
+
+
+class TestAMMBid(TestCase):
+    def test_tx_valid(self):
+        tx = AMMBid(
+            account=_ACCOUNT,
+            asset=_ASSET,
+            asset2=_ASSET2,
+            bid_min=IssuedCurrencyAmount(
+                currency=_LPTOKEN_CURRENCY,
+                issuer=_LPTOKEN_ISSUER,
+                value="25",
+            ),
+            bid_max=IssuedCurrencyAmount(
+                currency=_LPTOKEN_CURRENCY,
+                issuer=_LPTOKEN_ISSUER,
+                value="35",
+            ),
+            auth_accounts=_AUTH_ACCOUNTS,
+        )
+        self.assertTrue(tx.is_valid())
+
+    def test_auth_accounts_length_error(self):
+        auth_accounts = _AUTH_ACCOUNTS.copy()
+        auth_accounts.append(
+            AuthAccount(
+                account="r3X6noRsvaLapAKCG78zAtWcbhB3sggS1s",
+            ),
+        )
+        with self.assertRaises(XRPLModelException) as error:
+            AMMBid(
+                account=_ACCOUNT,
+                asset=_ASSET,
+                asset2=_ASSET2,
+                auth_accounts=auth_accounts,
+            )
+            self.assertEqual(
+                error.exception.args[0],
+                "{'auth_accounts': 'Length must not be greater than 4'}",
+            )

tests/unit/models/transactions/test_amm_create.py

@@ -0,0 +1,52 @@
+from sys import maxsize
+from unittest import TestCase
+
+from xrpl.models.amounts import IssuedCurrencyAmount
+from xrpl.models.exceptions import XRPLModelException
+from xrpl.models.transactions import AMMCreate
+
+_ACCOUNT = "r9LqNeG6qHxjeUocjvVki2XR35weJ9mZgQ"
+_IOU_ISSUER = "rPyfep3gcLzkosKC9XiE77Y8DZWG6iWDT9"
+
+
+class TestAMMCreate(TestCase):
+    def test_tx_is_valid(self):
+        tx = AMMCreate(
+            account=_ACCOUNT,
+            amount="1000",
+            amount2=IssuedCurrencyAmount(
+                currency="USD", issuer=_IOU_ISSUER, value="1000"
+            ),
+            trading_fee=12,
+        )
+        self.assertTrue(tx.is_valid())
+
+    def test_trading_fee_too_high(self):
+        with self.assertRaises(XRPLModelException) as error:
+            AMMCreate(
+                account=_ACCOUNT,
+                amount="1000",
+                amount2=IssuedCurrencyAmount(
+                    currency="USD", issuer=_IOU_ISSUER, value="1000"
+                ),
+                trading_fee=maxsize,
+            )
+            self.assertEqual(
+                error.exception.args[0],
+                "{'trading_fee': 'Must be between 0 and 1000'}",
+            )
+
+    def test_trading_fee_negative_number(self):
+        with self.assertRaises(XRPLModelException) as error:
+            AMMCreate(
+                account=_ACCOUNT,
+                amount="1000",
+                amount2=IssuedCurrencyAmount(
+                    currency="USD", issuer=_IOU_ISSUER, value="1000"
+                ),
+                trading_fee=-1,
+            )
+            self.assertEqual(
+                error.exception.args[0],
+                "{'trading_fee': 'Must be between 0 and 1000'}",
+            )

tests/unit/models/transactions/test_amm_delete.py

@@ -0,0 +1,17 @@
+from unittest import TestCase
+
+from xrpl.models.currencies import XRP, IssuedCurrency
+from xrpl.models.transactions import AMMDelete
+
+
+class TestAMMDeposit(TestCase):
+    def test_tx_valid(self):
+        tx = AMMDelete(
+            account="r9LqNeG6qHxjeUocjvVki2XR35weJ9mZgQ",
+            sequence=1337,
+            asset=XRP(),
+            asset2=IssuedCurrency(
+                currency="ETH", issuer="rpGtkFRXhgVaBzC5XCR7gyE2AZN5SN3SEW"
+            ),
+        )
+        self.assertTrue(tx.is_valid())

tests/unit/models/transactions/test_amm_deposit.py

@@ -0,0 +1,127 @@
+from unittest import TestCase
+
+from xrpl.models.amounts import IssuedCurrencyAmount
+from xrpl.models.currencies import XRP, IssuedCurrency
+from xrpl.models.exceptions import XRPLModelException
+from xrpl.models.transactions import AMMDeposit
+from xrpl.models.transactions.amm_deposit import AMMDepositFlag
+
+_ACCOUNT = "r9LqNeG6qHxjeUocjvVki2XR35weJ9mZgQ"
+_ASSET = XRP()
+_ASSET2 = IssuedCurrency(currency="ETH", issuer="rpGtkFRXhgVaBzC5XCR7gyE2AZN5SN3SEW")
+_AMOUNT = "1000"
+_LPTOKEN_CURRENCY = "B3813FCAB4EE68B3D0D735D6849465A9113EE048"
+_LPTOKEN_ISSUER = "rH438jEAzTs5PYtV6CHZqpDpwCKQmPW9Cg"
+
+
+class TestAMMDeposit(TestCase):
+    def test_tx_valid_xrpl_lptokenout(self):
+        tx = AMMDeposit(
+            account=_ACCOUNT,
+            sequence=1337,
+            asset=_ASSET,
+            asset2=_ASSET2,
+            lp_token_out=IssuedCurrencyAmount(
+                currency=_LPTOKEN_CURRENCY,
+                issuer=_LPTOKEN_ISSUER,
+                value=_AMOUNT,
+            ),
+            flags=AMMDepositFlag.TF_LP_TOKEN,
+        )
+        self.assertTrue(tx.is_valid())
+
+    def test_tx_valid_amount(self):
+        tx = AMMDeposit(
+            account=_ACCOUNT,
+            sequence=1337,
+            asset=_ASSET,
+            asset2=_ASSET2,
+            amount=_AMOUNT,
+            flags=AMMDepositFlag.TF_SINGLE_ASSET,
+        )
+        self.assertTrue(tx.is_valid())
+
+    def test_tx_valid_amount_amount2(self):
+        tx = AMMDeposit(
+            account=_ACCOUNT,
+            sequence=1337,
+            asset=_ASSET,
+            asset2=_ASSET2,
+            amount=_AMOUNT,
+            amount2=IssuedCurrencyAmount(
+                currency=_ASSET2.currency, issuer=_ASSET2.issuer, value="500"
+            ),
+            flags=AMMDepositFlag.TF_TWO_ASSET,
+        )
+        self.assertTrue(tx.is_valid())
+
+    def test_tx_valid_amount_lptokenout(self):
+        tx = AMMDeposit(
+            account=_ACCOUNT,
+            sequence=1337,
+            asset=_ASSET,
+            asset2=_ASSET2,
+            amount=_AMOUNT,
+            lp_token_out=IssuedCurrencyAmount(
+                currency=_LPTOKEN_CURRENCY,
+                issuer=_LPTOKEN_ISSUER,
+                value="500",
+            ),
+            flags=AMMDepositFlag.TF_ONE_ASSET_LP_TOKEN,
+        )
+        self.assertTrue(tx.is_valid())
+
+    def test_tx_valid_amount_eprice(self):
+        tx = AMMDeposit(
+            account=_ACCOUNT,
+            sequence=1337,
+            asset=_ASSET,
+            asset2=_ASSET2,
+            amount=_AMOUNT,
+            e_price="25",
+            flags=AMMDepositFlag.TF_LIMIT_LP_TOKEN,
+        )
+        self.assertTrue(tx.is_valid())
+
+    def test_undefined_amount_undefined_lptokenout_invalid_combo(self):
+        with self.assertRaises(XRPLModelException) as error:
+            AMMDeposit(
+                account=_ACCOUNT,
+                sequence=1337,
+                asset=_ASSET,
+                asset2=_ASSET2,
+            )
+            self.assertEqual(
+                error.exception.args[0],
+                "{'AMMDeposit': 'Must set at least `lp_token_out` or `amount`'}",
+            )
+
+    def test_undefined_amount_defined_amount2_invalid_combo(self):
+        with self.assertRaises(XRPLModelException) as error:
+            AMMDeposit(
+                account=_ACCOUNT,
+                sequence=1337,
+                asset=_ASSET,
+                asset2=_ASSET2,
+                amount2=IssuedCurrencyAmount(
+                    currency=_ASSET2.currency, issuer=_ASSET2.issuer, value="500"
+                ),
+            )
+            self.assertEqual(
+                error.exception.args[0],
+                "{'AMMDeposit': 'Must set `amount` with `amount2`'}",
+            )
+
+    def test_undefined_amount_defined_eprice_invalid_combo(self):
+        with self.assertRaises(XRPLModelException) as error:
+            AMMDeposit(
+                account=_ACCOUNT,
+                sequence=1337,
+                asset=_ASSET,
+                asset2=_ASSET2,
+                e_price="25",
+            )
+            self.assertEqual(
+                error.exception.args[0],
+                "{'AMMDeposit': 'Must set `amount` with `e_price`'}",
+            )