Add balance changes parser

CHANGELOG.md

@@ -8,6 +8,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [[Unreleased]]
 ### Added:
 - Support for dynamic fee calculation
+- Add function to parse account balances from a transaction's metadata
 
 ### Fixed
 - Resolve `txnNotFound` error with `send_reliable_submission` when waiting for a submitted malformed transaction

docs/source/xrpl.utils.txn_parser.rst

@@ -0,0 +1 @@
+:orphan:

docs/source/xrpl.utils.txn_parser.utils.rst

@@ -0,0 +1 @@
+:orphan:

pyproject.toml

@@ -39,6 +39,7 @@ websockets = [
     {version = ">=9.0.1 <11.0", python = ">= 3.7, < 3.10"},
     {version = "^10.0", python = "^3.10"}
 ]
+pydash = "^5.1.0"
 
 [tool.poetry.dev-dependencies]
 flake8 = "^3.8.4"

tests/unit/utils/txn_parser/test_invalid_txn.py

@@ -0,0 +1,22 @@
+from __future__ import annotations
+
+from copy import deepcopy
+from unittest import TestCase
+
+import xrpl.utils
+from tests.unit.utils.txn_parser.transaction import TXN
+
+meta_not_included_txn = deepcopy(TXN)
+meta_not_included_txn.pop("meta")
+no_nodes_txn = deepcopy(TXN)
+no_nodes_txn["meta"].clear()
+
+
+class TestInvalidTxn(TestCase):
+    def test_meta_not_included(self: TestInvalidTxn):
+        with self.assertRaises(xrpl.utils.XRPLTxnFieldsException):
+            xrpl.utils.parse_balance_changes(transaction=meta_not_included_txn)
+
+    def test_no_nodes(self: TestInvalidTxn):
+        with self.assertRaises(xrpl.utils.XRPLTxnFieldsException):
+            xrpl.utils.parse_balance_changes(transaction=no_nodes_txn)

tests/unit/utils/txn_parser/test_parse_balance_changes.py

@@ -0,0 +1,41 @@
+from __future__ import annotations
+
+from unittest import TestCase
+
+from tests.unit.utils.txn_parser.transaction import TXN
+from xrpl.utils import parse_balance_changes
+
+
+class TestParseBalanceChanges(TestCase):
+    def test(self: TestParseBalanceChanges):
+        actual = parse_balance_changes(transaction=TXN)
+        excpected = {
+            "rwwyrB83G6hS8vp4oLMqwRiMNLWToVCX6L": [
+                {
+                    "issuer": "rLBnhMjV6ifEHYeV4gaS6jPKerZhQddFxW",
+                    "currency": "5452535259000000000000000000000000000000",
+                    "value": "10",
+                }
+            ],
+            "rLBnhMjV6ifEHYeV4gaS6jPKerZhQddFxW": [
+                {
+                    "issuer": "rwwyrB83G6hS8vp4oLMqwRiMNLWToVCX6L",
+                    "currency": "5452535259000000000000000000000000000000",
+                    "value": "-10",
+                },
+                {
+                    "issuer": "rME2LXH8Che2BZRbu5LCRKWju9U3ARaEPd",
+                    "currency": "5452535259000000000000000000000000000000",
+                    "value": "10",
+                },
+            ],
+            "rME2LXH8Che2BZRbu5LCRKWju9U3ARaEPd": [
+                {
+                    "issuer": "rLBnhMjV6ifEHYeV4gaS6jPKerZhQddFxW",
+                    "currency": "5452535259000000000000000000000000000000",
+                    "value": "-10",
+                },
+                {"issuer": "", "currency": "XRP", "value": "-0.000012"},
+            ],
+        }
+        self.assertEqual(first=actual, second=excpected)

tests/unit/utils/txn_parser/transaction.py

@@ -0,0 +1,170 @@
+TXN = {
+    "Account": "rME2LXH8Che2BZRbu5LCRKWju9U3ARaEPd",
+    "Amount": {
+        "currency": "5452535259000000000000000000000000000000",
+        "issuer": "rLBnhMjV6ifEHYeV4gaS6jPKerZhQddFxW",
+        "value": "10",
+    },
+    "Destination": "rwwyrB83G6hS8vp4oLMqwRiMNLWToVCX6L",
+    "Fee": "12",
+    "LastLedgerSequence": 71409597,
+    "Memos": [
+        {
+            "Memo": {
+                "MemoData": "5472616E73616374696F6E537562547970653A204C6561726E696E67"
+            }
+        },
+        {
+            "Memo": {
+                "MemoData": "436F6E67726174756C6174696F6E2066726F6D20746865205"
+                "4726561737572792041636164656D7920F09F8E89F09F8E93"
+            }
+        },
+        {
+            "Memo": {
+                "MemoData": "436F757273653A2050726F7465637420596F757273656C66"
+                "202623383231313B2054686520696D706F7274616E6365206F662044594F52"
+            }
+        },
+        {
+            "Memo": {
+                "MemoData": "4C6573736F6E3A204C6573736F6E20383A20426C61636"
+                "B686F6C696E67202D204C696D6974696E6720496E666C6174696F6E"
+            }
+        },
+        {
+            "Memo": {
+                "MemoData": "596F75722047726164653A2031303025",
+            }
+        },
+    ],
+    "Sequence": 71306845,
+    "SigningPubKey": "EDD07E10AB5C915FAA3487CAA2CD9A2EE38F5DE869A18FADFC5E154BD4C"
+    "D349579",
+    "TransactionType": "Payment",
+    "TxnSignature": "6BB0F2FBB205571E53C6D05C1E92E5E5A9229BFA81189A32A91BA107E018"
+    "0D63977871B98DD908DAC0C043B7710050F54AEB3D28920E25D051A51BC27AAA9706",
+    "date": 704922692,
+    "hash": "F96C046288B5F0FE743C02C796FF457E4E64726DD935673D9D06ADF628151CEC",
+    "inLedger": 71409589,
+    "ledger_index": 71409589,
+    "meta": {
+        "AffectedNodes": [
+            {
+                "ModifiedNode": {
+                    "FinalFields": {
+                        "Balance": {
+                            "currency": "5452535259000000000000000000000000000000",
+                            "issuer": "rrrrrrrrrrrrrrrrrrrrBZbvji",
+                            "value": "165",
+                        },
+                        "Flags": 1114112,
+                        "HighLimit": {
+                            "currency": "5452535259000000000000000000000000000000",
+                            "issuer": "rLBnhMjV6ifEHYeV4gaS6jPKerZhQddFxW",
+                            "value": "0",
+                        },
+                        "HighNode": "11fd",
+                        "LowLimit": {
+                            "currency": "5452535259000000000000000000000000000000",
+                            "issuer": "rwwyrB83G6hS8vp4oLMqwRiMNLWToVCX6L",
+                            "value": "100000000",
+                        },
+                        "LowNode": "0",
+                    },
+                    "LedgerEntryType": "RippleState",
+                    "LedgerIndex": "1C25C21543238F1CC7776AC096DBF2575B561C39FD40B2"
+                    "D2E270BF81C900D852",
+                    "PreviousFields": {
+                        "Balance": {
+                            "currency": "5452535259000000000000000000000000000000",
+                            "issuer": "rrrrrrrrrrrrrrrrrrrrBZbvji",
+                            "value": "155",
+                        }
+                    },
+                    "PreviousTxnID": "A4C406A1A81D741C79E148E65B94B7613D0BF80EA74"
+                    "7E224EC016AE833A7F91A",
+                    "PreviousTxnLgrSeq": 71404087,
+                }
+            },
+            {
+                "ModifiedNode": {
+                    "FinalFields": {
+                        "Balance": {
+                            "currency": "5452535259000000000000000000000000000000",
+                            "issuer": "rrrrrrrrrrrrrrrrrrrrBZbvji",
+                            "value": "-60193",
+                        },
+                        "Flags": 2228224,
+                        "HighLimit": {
+                            "currency": "5452535259000000000000000000000000000000",
+                            "issuer": "rME2LXH8Che2BZRbu5LCRKWju9U3ARaEPd",
+                            "value": "99119930.7682357",
+                        },
+                        "HighNode": "0",
+                        "LowLimit": {
+                            "currency": "5452535259000000000000000000000000000000",
+                            "issuer": "rLBnhMjV6ifEHYeV4gaS6jPKerZhQddFxW",
+                            "value": "0",
+                        },
+                        "LowNode": "11ca",
+                    },
+                    "LedgerEntryType": "RippleState",
+                    "LedgerIndex": "7EC1111F3BDB7E27B681A2769F851DB5BC1C7A"
+                    "362624FD9949CB8D9C35CC64F6",
+                    "PreviousFields": {
+                        "Balance": {
+                            "currency": "5452535259000000000000000000000000000000",
+                            "issuer": "rrrrrrrrrrrrrrrrrrrrBZbvji",
+                            "value": "-60203",
+                        }
+                    },
+                    "PreviousTxnID": "5F530DFF08505CB4CAA588799D1305FFC21"
+                    "19889673FBD99290BC66A7087A294",
+                    "PreviousTxnLgrSeq": 71409584,
+                }
+            },
+            {
+                "ModifiedNode": {
+                    "FinalFields": {
+                        "Account": "rME2LXH8Che2BZRbu5LCRKWju9U3ARaEPd",
+                        "Balance": "14794674",
+                        "Flags": 65536,
+                        "OwnerCount": 1,
+                        "RegularKey": "rLJUjR5L7mtoRc9st3WBotX1yit14C48RL",
+                        "Sequence": 71306846,
+                    },
+                    "LedgerEntryType": "AccountRoot",
+                    "LedgerIndex": "EFA7C1ACD9049645911E6EE1CFC5311054EDBB4"
+                    "FC313603709BE364974227506",
+                    "PreviousFields": {
+                        "Balance": "14794686",
+                        "Sequence": 71306845,
+                    },
+                    "PreviousTxnID": "5F530DFF08505CB4CAA588799D1305FFC2119"
+                    "889673FBD99290BC66A7087A294",
+                    "PreviousTxnLgrSeq": 71409584,
+                }
+            },
+        ],
+        "TransactionIndex": 47,
+        "TransactionResult": "tesSUCCESS",
+        "delivered_amount": {
+            "currency": "5452535259000000000000000000000000000000",
+            "issuer": "rLBnhMjV6ifEHYeV4gaS6jPKerZhQddFxW",
+            "value": "10",
+        },
+    },
+    "validated": True,
+    "warnings": [
+        {
+            "id": 1004,
+            "message": "This is a reporting server.  The default behavior of a "
+            "reporting server is to only return validated data. If you are looking for"
+            ' not yet validated data, include "ledger_index : current" in your'
+            " request, which will cause this server to forward the request to a p2p"
+            " node. If the forward is successful the response will include"
+            ' "forwarded" : "true"',
+        }
+    ],
+}

xrpl/utils/__init__.py

@@ -9,6 +9,7 @@
     ripple_time_to_datetime,
     ripple_time_to_posix,
 )
+from xrpl.utils.txn_parser import XRPLTxnFieldsException, parse_balance_changes
 from xrpl.utils.xrp_conversions import XRPRangeException, drops_to_xrp, xrp_to_drops
 
 __all__ = [
@@ -23,4 +24,6 @@
     "XRPRangeException",
     "XRPLTimeRangeException",
     "create_cross_chain_payment",
+    "XRPLTxnFieldsException",
+    "parse_balance_changes",
 ]

xrpl/utils/txn_parser/__init__.py

@@ -0,0 +1,6 @@
+"""Transaction parser."""
+
+from xrpl.utils.txn_parser.balance_parser import parse_balance_changes
+from xrpl.utils.txn_parser.utils import XRPLTxnFieldsException
+
+__all__ = ["parse_balance_changes", "XRPLTxnFieldsException"]

xrpl/utils/txn_parser/balance_parser.py

@@ -0,0 +1,51 @@
+"""Parse balance changes of every account involved in the given transaction."""
+
+from typing import Any, Dict, List, Union, cast
+
+from xrpl.utils.txn_parser.utils import (
+    RawTxnType,
+    SubscriptionRawTxnType,
+    compute_balance_changes,
+    normalize_nodes,
+    normalize_transaction,
+    parse_quantities,
+    validate_transaction_fields,
+)
+
+
+def parse_balance_changes(
+    transaction: Union[RawTxnType, SubscriptionRawTxnType],
+) -> Dict[str, Any]:
+    """
+    Parse the balance changes of all accounts affected
+    by the transaction after it occurred.
+
+    Args:
+        transaction: Raw transaction data including the account that
+            sent the transaction and the metadata.
+
+    Returns:
+        All balance changes.
+    """
+    validate_transaction_fields(transaction_data=transaction)
+    if "transaction" in transaction:
+        transaction = cast(SubscriptionRawTxnType, transaction)
+        transaction = normalize_transaction(transaction_data=transaction)
+    nodes = normalize_nodes(transaction_data=transaction)
+    parsedQuantities = parse_quantities(
+        nodes=nodes, value_parser=compute_balance_changes
+    )
+    result: Dict[str, List[Dict[str, str]]] = {}
+    for address, change in parsedQuantities.items():
+        result[address] = []
+        for obj in change:
+            if isinstance(obj.issuer, tuple):
+                obj.issuer = obj.issuer[0]
+            result[address].append(
+                {
+                    "issuer": obj.issuer,
+                    "currency": obj.currency,
+                    "value": obj.value,
+                }
+            )
+    return result

xrpl/utils/txn_parser/utils/__init__.py

@@ -0,0 +1,28 @@
+"""Utils for the transaction parser."""
+
+
+from xrpl.utils.txn_parser.utils.balance_parser import (
+    compute_balance_changes,
+    parse_quantities,
+)
+from xrpl.utils.txn_parser.utils.transaction import (
+    normalize_nodes,
+    normalize_transaction,
+    validate_transaction_fields,
+)
+from xrpl.utils.txn_parser.utils.types import (
+    RawTxnType,
+    SubscriptionRawTxnType,
+    XRPLTxnFieldsException,
+)
+
+__all__ = [
+    "parse_quantities",
+    "compute_balance_changes",
+    "RawTxnType",
+    "SubscriptionRawTxnType",
+    "XRPLTxnFieldsException",
+    "normalize_nodes",
+    "normalize_transaction",
+    "validate_transaction_fields",
+]