Support for PriceOracles

.ci-config/rippled.cfg

@@ -170,3 +170,11 @@ fixNFTokenRemint
 # 2.0.0-b4 Amendments
 XChainBridge
 DID
+# 2.2.0-b3 Amendments
+fixNFTokenReserve
+fixInnerObjTemplate
+fixAMMOverflowOffer
+PriceOracle
+fixEmptyDID
+fixXChainRewardRounding
+fixPreviousTxnID

.github/workflows/integration_test.yml

@@ -2,7 +2,7 @@ name: Integration test
 
 env:
   POETRY_VERSION: 1.4.2
-  RIPPLED_DOCKER_IMAGE: rippleci/rippled:2.0.0-b4
+  RIPPLED_DOCKER_IMAGE: rippleci/rippled:2.2.0-b3
 
 on:
   push:

CHANGELOG.md

@@ -8,6 +8,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [[Unreleased]]
 - Included `ctid` field in the `tx` request.
 
+### Added
+- Support for the PriceOracle amendment (XLS-47d).
+
 ### Fixed
 - Added support for `XChainModifyBridge` flag maps (fixing an issue with `NFTokenCreateOffer` flag names)
 - Fixed `XChainModifyBridge` validation to allow just clearing of `MinAccountCreateAmount`

CONTRIBUTING.md

@@ -90,7 +90,7 @@ poetry run poe test_unit
 To run integration tests, you'll need a standalone rippled node running with WS port `6006` and JSON RPC port `5005`. You can run a docker container for this:
 
 ```bash
-docker run -p 5005:5005 -p 6006:6006 --interactive -t --volume $PWD/.ci-config:/opt/ripple/etc/ --platform linux/amd64 rippleci/rippled:2.0.0-b4 /opt/ripple/bin/rippled -a --conf /opt/ripple/etc/rippled.cfg
+docker run -p 5005:5005 -p 6006:6006 --interactive -t --volume $PWD/.ci-config:/opt/ripple/etc/ --platform linux/amd64 rippleci/rippled:2.2.0-b3 /opt/ripple/bin/rippled -a --conf /opt/ripple/etc/rippled.cfg
 ```
 
 Breaking down the command:

snippets/oracle.py

@@ -0,0 +1,65 @@
+"""Example of how we can create, update and delete oracles"""
+import time
+
+from xrpl.clients import JsonRpcClient
+from xrpl.models.transactions.oracle_delete import OracleDelete
+from xrpl.models.transactions.oracle_set import OracleSet, PriceData
+from xrpl.transaction.reliable_submission import submit_and_wait
+from xrpl.utils import str_to_hex
+from xrpl.wallet import generate_faucet_wallet
+
+# Create a client to connect to the dev-network
+client = JsonRpcClient("https://s.devnet.rippletest.net:51234")
+
+wallet = generate_faucet_wallet(client, debug=True)
+
+
+_PROVIDER = str_to_hex("provider")
+_ASSET_CLASS = str_to_hex("currency")
+_ORACLE_DOC_ID = 1
+
+create_tx = OracleSet(
+    account=wallet.address,
+    oracle_document_id=_ORACLE_DOC_ID,
+    provider=_PROVIDER,
+    asset_class=_ASSET_CLASS,
+    last_update_time=int(time.time()),
+    price_data_series=[
+        PriceData(base_asset="XRP", quote_asset="USD", asset_price=740, scale=1),
+        PriceData(base_asset="BTC", quote_asset="EUR", asset_price=100, scale=2),
+    ],
+)
+
+response = submit_and_wait(create_tx, client, wallet)
+# TODO: Keshava
+# print(response.result['meta']['TransactionResult'] == 'tesSUCCESS') # does not work
+print(
+    "Result of SetOracle transaction: " + response.result["meta"]["TransactionResult"]
+)
+
+# update the oracle data
+update_tx = OracleSet(
+    account=wallet.address,
+    oracle_document_id=_ORACLE_DOC_ID,
+    last_update_time=int(time.time()),
+    price_data_series=[
+        PriceData(base_asset="XRP", quote_asset="USD", asset_price=742, scale=1),
+        PriceData(base_asset="BTC", quote_asset="EUR", asset_price=103, scale=2),
+    ],
+)
+response = submit_and_wait(update_tx, client, wallet)
+
+print(
+    "Result of the Update Oracle transaction: "
+    + response.result["meta"]["TransactionResult"]
+)
+
+
+# delete the oracle
+delete_tx = OracleDelete(account=wallet.address, oracle_document_id=_ORACLE_DOC_ID)
+response = submit_and_wait(delete_tx, client, wallet)
+
+print(
+    "Result of DeleteOracle transaction: "
+    + response.result["meta"]["TransactionResult"]
+)

snippets/oracle_aggregate.py

@@ -0,0 +1,48 @@
+"""Snippet demonstrates obtaining aggregate statistics of PriceOracles"""
+import time
+
+from xrpl.clients import JsonRpcClient
+from xrpl.models.requests.get_aggregate_price import GetAggregatePrice, OracleInfo
+from xrpl.models.transactions.oracle_set import OracleSet, PriceData
+from xrpl.transaction.reliable_submission import submit_and_wait
+from xrpl.utils import str_to_hex
+from xrpl.wallet import generate_faucet_wallet
+
+# Create a client to connect to the dev-network
+client = JsonRpcClient("https://s.devnet.rippletest.net:51234")
+
+_PROVIDER = str_to_hex("provider")
+_ASSET_CLASS = str_to_hex("currency")
+
+# list stores the (account, oracle_document_id) information
+oracle_info = []
+
+for i in range(10):
+    # new (pseudo-random) addresses are generated
+    wallet = generate_faucet_wallet(client, debug=True)
+    create_tx = OracleSet(
+        account=wallet.address,
+        oracle_document_id=i,
+        provider=_PROVIDER,
+        asset_class=_ASSET_CLASS,
+        last_update_time=int(time.time()),
+        price_data_series=[
+            PriceData(
+                base_asset="XRP", quote_asset="USD", asset_price=740 + i, scale=1
+            ),
+            PriceData(
+                base_asset="BTC", quote_asset="EUR", asset_price=100 + i, scale=2
+            ),
+        ],
+    )
+
+    response = submit_and_wait(create_tx, client, wallet)
+
+    # store the (account, oracle_document_id) for future use
+    oracle_info.append(OracleInfo(account=wallet.address, oracle_document_id=i))
+
+get_agg_request = GetAggregatePrice(
+    base_asset="XRP", quote_asset="USD", oracles=oracle_info
+)
+response = client.request(get_agg_request)
+print(response)

tests/integration/transactions/test_delete_oracle.py

@@ -0,0 +1,61 @@
+import random
+import time
+
+from tests.integration.integration_test_case import IntegrationTestCase
+from tests.integration.it_utils import (
+    sign_and_reliable_submission_async,
+    test_async_and_sync,
+)
+from tests.integration.reusable_values import WALLET
+from xrpl.models import AccountObjects, AccountObjectType, OracleDelete, OracleSet
+from xrpl.models.response import ResponseStatus
+from xrpl.models.transactions.oracle_set import PriceData
+from xrpl.utils import str_to_hex
+
+_PROVIDER = str_to_hex("chainlink")
+_ASSET_CLASS = str_to_hex("currency")
+
+
+class TestDeleteOracle(IntegrationTestCase):
+    @test_async_and_sync(globals())
+    async def test_basic(self, client):
+        oracle_id = random.randint(100, 10000)
+
+        # Create PriceOracle, to be deleted later
+        tx = OracleSet(
+            account=WALLET.address,
+            # if oracle_document_id is not modified, the (sync, async) +
+            # (json, websocket) combination of integration tests will update the same
+            # oracle object using identical "LastUpdateTime". Updates to an oracle must
+            # be more recent than its previous LastUpdateTime
+            oracle_document_id=oracle_id,
+            provider=_PROVIDER,
+            asset_class=_ASSET_CLASS,
+            last_update_time=int(time.time()),
+            price_data_series=[
+                PriceData(
+                    base_asset="XRP", quote_asset="USD", asset_price=740, scale=1
+                ),
+                PriceData(
+                    base_asset="BTC", quote_asset="EUR", asset_price=100, scale=2
+                ),
+            ],
+        )
+        response = await sign_and_reliable_submission_async(tx, WALLET, client)
+        self.assertEqual(response.status, ResponseStatus.SUCCESS)
+        self.assertEqual(response.result["engine_result"], "tesSUCCESS")
+
+        # Create PriceOracle to delete
+        tx = OracleDelete(
+            account=WALLET.address,
+            oracle_document_id=oracle_id,
+        )
+        response = await sign_and_reliable_submission_async(tx, WALLET, client)
+        self.assertEqual(response.status, ResponseStatus.SUCCESS)
+        self.assertEqual(response.result["engine_result"], "tesSUCCESS")
+
+        # confirm that the PriceOracle was actually deleted
+        account_objects_response = await client.request(
+            AccountObjects(account=WALLET.address, type=AccountObjectType.ORACLE)
+        )
+        self.assertEqual(len(account_objects_response.result["account_objects"]), 0)

tests/integration/transactions/test_set_oracle.py

@@ -0,0 +1,52 @@
+import random
+import time
+
+from tests.integration.integration_test_case import IntegrationTestCase
+from tests.integration.it_utils import (
+    sign_and_reliable_submission_async,
+    test_async_and_sync,
+)
+from tests.integration.reusable_values import WALLET
+from xrpl.models import AccountObjects, AccountObjectType, OracleSet
+from xrpl.models.response import ResponseStatus
+from xrpl.models.transactions.oracle_set import PriceData
+from xrpl.utils import str_to_hex
+
+_PROVIDER = str_to_hex("provider")
+_ASSET_CLASS = str_to_hex("currency")
+
+
+class TestSetOracle(IntegrationTestCase):
+    @test_async_and_sync(globals())
+    async def test_all_fields(self, client):
+        tx = OracleSet(
+            account=WALLET.address,
+            # if oracle_document_id is not modified, the (sync, async) +
+            # (json, websocket) combination of integration tests will update the same
+            # oracle object using identical "LastUpdateTime". Updates to an oracle must
+            # be more recent than its previous LastUpdateTime
+            oracle_document_id=random.randint(100, 300),
+            provider=_PROVIDER,
+            asset_class=_ASSET_CLASS,
+            last_update_time=int(time.time()),
+            price_data_series=[
+                PriceData(
+                    base_asset="XRP", quote_asset="USD", asset_price=740, scale=1
+                ),
+                PriceData(
+                    base_asset="BTC", quote_asset="EUR", asset_price=100, scale=2
+                ),
+            ],
+        )
+        response = await sign_and_reliable_submission_async(tx, WALLET, client)
+        self.assertEqual(response.status, ResponseStatus.SUCCESS)
+        self.assertEqual(response.result["engine_result"], "tesSUCCESS")
+
+        # confirm that the PriceOracle was actually created
+        account_objects_response = await client.request(
+            AccountObjects(account=WALLET.address, type=AccountObjectType.ORACLE)
+        )
+
+        # subsequent integration tests (sync/async + json/websocket) add one
+        # oracle object to the account
+        self.assertTrue(len(account_objects_response.result["account_objects"]) > 0)

tests/unit/models/requests/test_get_aggregate_price.py

@@ -0,0 +1,76 @@
+from unittest import TestCase
+
+from xrpl.models import XRPLModelException
+from xrpl.models.requests import GetAggregatePrice
+from xrpl.models.requests.get_aggregate_price import OracleInfo
+
+_ACCT_STR_1 = "rBwHKFS534tfG3mATXSycCnX8PAd3XJswj"
+_ORACLE_DOC_ID_1 = 1
+
+_ACCT_STR_2 = "rDMKwhm13oJBxBgiWS2SheZhKT5nZP8kez"
+_ORACLE_DOC_ID_2 = 2
+
+
+class TestGetAggregatePrice(TestCase):
+    def test_invalid_requests(self):
+        """Unit test to validate invalid requests"""
+        with self.assertRaises(XRPLModelException):
+            # oracles array must contain at least one element
+            GetAggregatePrice(
+                base_asset="USD",
+                quote_asset="XRP",
+                oracles=[],
+            )
+
+        with self.assertRaises(XRPLModelException):
+            # base_asset is missing in the request
+            GetAggregatePrice(
+                quote_asset="XRP",
+                oracles=[
+                    OracleInfo(
+                        account=_ACCT_STR_1, oracle_document_id=_ORACLE_DOC_ID_1
+                    ),
+                    OracleInfo(
+                        account=_ACCT_STR_2, oracle_document_id=_ORACLE_DOC_ID_2
+                    ),
+                ],
+            )
+
+        with self.assertRaises(XRPLModelException):
+            # quote_asset is missing in the request
+            GetAggregatePrice(
+                base_asset="USD",
+                oracles=[
+                    OracleInfo(
+                        account=_ACCT_STR_1, oracle_document_id=_ORACLE_DOC_ID_1
+                    ),
+                    OracleInfo(
+                        account=_ACCT_STR_2, oracle_document_id=_ORACLE_DOC_ID_2
+                    ),
+                ],
+            )
+
+    def test_valid_request(self):
+        """Unit test for validating archetypical requests"""
+        request = GetAggregatePrice(
+            base_asset="USD",
+            quote_asset="XRP",
+            oracles=[
+                OracleInfo(account=_ACCT_STR_1, oracle_document_id=_ORACLE_DOC_ID_1),
+                OracleInfo(account=_ACCT_STR_2, oracle_document_id=_ORACLE_DOC_ID_2),
+            ],
+        )
+        self.assertTrue(request.is_valid())
+
+        # specifying trim and time_threshold value
+        request = GetAggregatePrice(
+            base_asset="USD",
+            quote_asset="XRP",
+            oracles=[
+                OracleInfo(account=_ACCT_STR_1, oracle_document_id=_ORACLE_DOC_ID_1),
+                OracleInfo(account=_ACCT_STR_2, oracle_document_id=_ORACLE_DOC_ID_2),
+            ],
+            trim=20,
+            time_threshold=10,
+        )
+        self.assertTrue(request.is_valid())

tests/unit/models/requests/test_ledger_entry.py

@@ -2,7 +2,7 @@
 
 from xrpl.models import XRP, LedgerEntry, XChainBridge
 from xrpl.models.exceptions import XRPLModelException
-from xrpl.models.requests.ledger_entry import RippleState
+from xrpl.models.requests.ledger_entry import Oracle, RippleState
 
 
 class TestLedgerEntry(TestCase):
@@ -119,3 +119,36 @@ def test_has_multiple_query_params_is_invalid(self):
                 index="hello",
                 account_root="hello",
             )
+
+    # fetch a valid PriceOracle object
+    def test_get_priceoracle(self):
+        # oracle_document_id is specified as uint
+        req = LedgerEntry(
+            oracle=Oracle(
+                account="rB6XJbxKx2oBSK1E3Hvh7KcZTCCBukWyhv",
+                oracle_document_id=1,
+            ),
+        )
+        self.assertTrue(req.is_valid())
+
+        # oracle_document_id is specified as string
+        req = LedgerEntry(
+            oracle=Oracle(
+                account="rB6XJbxKx2oBSK1E3Hvh7KcZTCCBukWyhv",
+                oracle_document_id="1",
+            ),
+        )
+        self.assertTrue(req.is_valid())
+
+    def test_invalid_priceoracle_object(self):
+        # missing oracle_document_id
+        with self.assertRaises(XRPLModelException):
+            LedgerEntry(
+                oracle=Oracle(account="rB6XJbxKx2oBSK1E3Hvh7KcZTCCBukWyhv"),
+            )
+
+        # missing account information
+        with self.assertRaises(XRPLModelException):
+            LedgerEntry(
+                oracle=Oracle(oracle_document_id=1),
+            )