docs: add xrpl.js code snippets over to xrpl-py

CONTRIBUTING.md

@@ -119,7 +119,7 @@ To see the output:
 cd docs/_build/html/
 
 # Open the index file to view it in a browser:
-open _build/html/index.html
+open index.html
 ```
 
 ## Update `definitions.json`

docs/index.rst

@@ -30,6 +30,7 @@ If you run into any bugs or other problems with the library, please report them
    :maxdepth: 1
    :caption: Table of Contents
 
+   source/snippets
    source/xrpl.account
    source/xrpl.ledger
    source/xrpl.transaction

docs/source/get_transaction.rst

@@ -0,0 +1,5 @@
+Get Transaction
+==========================
+
+.. autofunction:: snippets.get_transaction.async_get_transaction
+.. literalinclude:: ../../snippets/get_transaction.py

docs/source/partial_payment.rst

@@ -0,0 +1,5 @@
+Partial Payment
+==========================
+
+.. autofunction:: snippets.partial_payment.async_partial_payment
+.. literalinclude:: ../../snippets/partial_payment.py

docs/source/paths.rst

@@ -0,0 +1,5 @@
+Partial Payment
+==========================
+
+.. autofunction:: snippets.paths.async_create_tx_with_paths
+.. literalinclude:: ../../snippets/paths.py

docs/source/reliable_transaction_submission.rst

@@ -0,0 +1,5 @@
+Reliable Transaction Submission
+================================
+
+.. autofunction:: snippets.reliable_transaction_submission.async_send_reliable_tx
+.. literalinclude:: ../../snippets/reliable_transaction_submission.py

docs/source/send_escrow.rst

@@ -0,0 +1,5 @@
+Send Escrow
+==========================
+
+.. autofunction:: snippets.send_escrow.async_send_escrow
+.. literalinclude:: ../../snippets/send_escrow.py

docs/source/set_regular_key.rst

@@ -0,0 +1,5 @@
+Set Regular Key
+==========================
+
+.. autofunction:: snippets.set_regular_key.async_set_regular_key
+.. literalinclude:: ../../snippets/set_regular_key.py

docs/source/snippets.rst

@@ -0,0 +1,14 @@
+XRPL Code Snippets
+================
+
+Code snippets to demonstrate basic usage of the xrpl-py library.
+
+.. toctree::
+   :maxdepth: 1
+
+   get_transaction
+   partial_payment
+   paths
+   reliable_transaction_submission
+   send_escrow
+   set_regular_key

snippets/get_transaction.py

@@ -0,0 +1,49 @@
+"""A snippet that walks us through getting a transaction."""
+from xrpl.asyncio.clients import AsyncWebsocketClient
+from xrpl.models.requests import Ledger, Tx
+
+
+async def async_get_transaction() -> None:
+    """
+    Async snippet that walks us through getting a transaction.
+
+    Args:
+        client: The async network client to use to send the request.
+
+    Raises:
+        Exception: if meta not included in the transaction response.
+    """
+    async with AsyncWebsocketClient("wss://s.altnet.rippletest.net:51233") as client:
+        await client.open()
+
+        ledger_request = Ledger(transactions=True, ledger_index="validated")
+        ledger_response = await client.request(ledger_request)
+        print(ledger_response)
+
+        transactions = ledger_response.result["ledger"]["transactions"]
+
+        if transactions:
+            tx = await client.request(Tx(transaction=transactions[0]))
+            print(tx)
+
+            # the meta field would be a string(hex)
+            # when the `binary` parameter is `true` for the `tx` request.
+            if tx.result["meta"] is None:
+                raise Exception("meta not included in the response")
+
+            # delivered_amount is the amount actually received by the destination account.
+            # Use this field to determine how much was delivered,
+            # regardless of whether the transaction is a partial payment.
+            # https://xrpl.org/transaction-metadata.html#delivered_amount
+            if type(tx.result["meta"] != "string"):
+                if "delivered_amount" in tx.result["meta"]:
+                    print("delivered_amount:", tx.result["meta"]["delivered_amount"])
+                else:
+                    print("delivered_amount: undefined")
+
+        await client.close()
+
+
+# uncomment the lines below to run the snippet
+# import asyncio
+# asyncio.run(async_get_transaction())

snippets/partial_payment.py

@@ -0,0 +1,134 @@
+"""A snippet that walks us through using a partial payment."""
+from xrpl.asyncio.clients import AsyncWebsocketClient
+from xrpl.asyncio.transaction import (
+    safe_sign_and_autofill_transaction,
+    send_reliable_submission,
+)
+from xrpl.asyncio.wallet import generate_faucet_wallet
+from xrpl.models.amounts import IssuedCurrencyAmount
+from xrpl.models.requests import AccountLines
+from xrpl.models.transactions import Payment, PaymentFlag, TrustSet
+
+
+async def async_partial_payment() -> None:
+    """
+    Async snippet that walks us through using a partial payment.
+
+    Args:
+        client: The async network client to use to send the request.
+    """
+    async with AsyncWebsocketClient("wss://s.altnet.rippletest.net:51233") as client:
+        await client.open()
+
+        # creating wallets as prerequisite
+        wallet1 = await generate_faucet_wallet(client, debug=True)
+        wallet2 = await generate_faucet_wallet(client, debug=True)
+
+        # create a trustline to issue an IOU `FOO` and set limit on it
+        trust_set_tx = TrustSet(
+            account=wallet2.classic_address,
+            limit_amount=IssuedCurrencyAmount(
+                currency="FOO",
+                value="10000000000",
+                issuer=wallet1.classic_address,
+            ),
+        )
+
+        signed_trust_set_tx = await safe_sign_and_autofill_transaction(
+            trust_set_tx, wallet2, client
+        )
+        await send_reliable_submission(signed_trust_set_tx, client)
+
+        print("Balances after trustline is claimed:")
+        print(
+            (await client.request(AccountLines(account=wallet1.classic_address))).result[
+                "lines"
+            ]
+        )
+        print(
+            (await client.request(AccountLines(account=wallet2.classic_address))).result[
+                "lines"
+            ]
+        )
+
+        # initially, the issuer(wallet1) sends an amount to the other account(wallet2)
+        issue_quantity = "3840"
+        payment_tx = Payment(
+            account=wallet1.classic_address,
+            amount=IssuedCurrencyAmount(
+                currency="FOO",
+                value=issue_quantity,
+                issuer=wallet1.classic_address,
+            ),
+            destination=wallet2.classic_address,
+        )
+
+        # submit payment
+        signed_payment_tx = await safe_sign_and_autofill_transaction(
+            payment_tx, wallet1, client
+        )
+        payment_response = await send_reliable_submission(signed_payment_tx, client)
+        print(payment_response)
+
+        print("Balances after wallet1 sends 3840 FOO to wallet2:")
+        print(
+            (await client.request(AccountLines(account=wallet1.classic_address))).result[
+                "lines"
+            ]
+        )
+        print(
+            (await client.request(AccountLines(account=wallet2.classic_address))).result[
+                "lines"
+            ]
+        )
+
+        # Send money less than the amount specified on 2 conditions:
+        # 1. Sender has less money than the aamount specified in the payment Tx.
+        # 2. Sender has the tfPartialPayment flag activated.
+
+        # Other ways to specify flags are by using Hex code and decimal code.
+        # eg. For partial payment(tfPartialPayment)
+        # decimal ->131072, hex -> 0x00020000
+        partial_payment_tx = Payment(
+            account=wallet2.classic_address,
+            amount=IssuedCurrencyAmount(
+                currency="FOO",
+                value="4000",
+                issuer=wallet1.classic_address,
+            ),
+            destination=wallet1.classic_address,
+            flags=[PaymentFlag.TF_PARTIAL_PAYMENT],
+            send_max=IssuedCurrencyAmount(
+                currency="FOO",
+                value="1000000",
+                issuer=wallet1.classic_address,
+            ),
+        )
+
+        # submit payment
+        signed_partial_payment_tx = await safe_sign_and_autofill_transaction(
+            partial_payment_tx, wallet2, client
+        )
+        partial_payment_response = await send_reliable_submission(
+            signed_partial_payment_tx, client
+        )
+        print(partial_payment_response)
+
+        print("Balances after Partial Payment, when wallet2 tried to send 4000 FOOs")
+        print(
+            (await client.request(AccountLines(account=wallet1.classic_address))).result[
+                "lines"
+            ]
+        )
+        print(
+            (await client.request(AccountLines(account=wallet2.classic_address))).result[
+                "lines"
+            ]
+        )
+
+        await client.close()
+
+
+# uncomment the lines below to run the snippet
+# import asyncio
+# asyncio.run(async_partial_payment())

snippets/paths.py

@@ -0,0 +1,58 @@
+"""A snippet that walks us through creating a transaction with a path."""
+from xrpl.asyncio.clients import AsyncWebsocketClient
+from xrpl.asyncio.transaction import safe_sign_and_autofill_transaction
+from xrpl.asyncio.wallet import generate_faucet_wallet
+from xrpl.models.amounts import IssuedCurrencyAmount
+from xrpl.models.currencies.xrp import XRP
+from xrpl.models.requests import RipplePathFind
+from xrpl.models.transactions import Payment
+
+
+async def async_create_tx_with_paths() -> None:
+    """
+    Async snippet that walks us through creating a transaction with a path.
+
+    Args:
+        client: The async network client to use to send the request.
+    """
+    async with AsyncWebsocketClient("wss://s.altnet.rippletest.net:51233") as client:
+        await client.open()
+
+        wallet = await generate_faucet_wallet(client, debug=True)
+        destination_account = "rKT4JX4cCof6LcDYRz8o3rGRu7qxzZ2Zwj"
+        destination_amount = IssuedCurrencyAmount(
+            value="0.001",
+            currency="USD",
+            issuer="rVnYNK9yuxBz4uP8zC8LEFokM2nqH3poc",
+        )
+
+        path_request = RipplePathFind(
+            source_account=wallet.classic_address,
+            source_currencies=[XRP()],
+            destination_account=destination_account,
+            destination_amount=destination_amount,
+        )
+
+        path_response = await client.request(path_request)
+        print(path_response)
+
+        paths = path_response.result["alternatives"][0]["paths_computed"]
+        print(paths)
+
+        payment_tx = Payment(
+            account=wallet.classic_address,
+            amount=destination_amount,
+            destination=destination_account,
+            paths=paths,
+        )
+
+        print(
+            "signed: ", await safe_sign_and_autofill_transaction(payment_tx, wallet, client)
+        )
+
+        await client.close()
+
+
+# uncomment the lines below to run the snippet
+# import asyncio
+# asyncio.run(async_create_tx_with_paths())