feat: add support for XLS-38d

.vscode/settings.json

@@ -13,12 +13,18 @@
  "asyncio",
  "autofills",
  "binarycodec",
+ "Clawback",
+ "isnumeric",
  "keypair",
  "keypairs",
  "multisign",
  "nftoken",
  "rippletest",
  "ripplex",
- "xaddress"
+ "xaddress",
+ "xchain"
  ],
+ "[python]": {
+ "editor.defaultFormatter": "ms-python.black-formatter"
+ }
 }

CHANGELOG.md

@@ -8,31 +8,42 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [[Unreleased]]
 
 ### Added
-- Added new syntax for `SetFee` psuedo transaction sent after the [XRPFees](https://xrpl.org/known-amendments.html#xrpfees) amendment. (Backwards compatible)
+
+- Added new syntax for `SetFee` pseudo transaction sent after the [XRPFees](https://xrpl.org/known-amendments.html#xrpfees) amendment. (Backwards compatible)
 - Update request models related to AMM
+- Support for [XLS-38d (XChainBridge)](https:/XRPLF/XRPL-Standards/tree/master/XLS-38d-XChainBridge)
 
 ## [2.3.0] - 2023-08-24
+
 ### Added
+
 - Add AMM support [XLS-30](https:/XRPLF/XRPL-Standards/discussions/78)
 
 ## [2.2.0] - 2023-08-07
+
 ### Added
+
 - Added new `Clawback` transaction as per [XLS-39](https:/XRPLF/XRPL-Standards/discussions/94)
 
 ## [2.1.0] - 2023-07-24
+
 ### Fixed
-- Replaced alias for `classic_address` with separate property to work around this mypy issue: 
+
+- Replaced alias for `classic_address` with separate property to work around this mypy issue:
  https:/python/mypy/issues/6700
 
 ## [2.0.0] - 2023-07-05
+
 ### Added:
+
 - Wallet support for regular key compatibility
 - Added new ways of wallet generation: `from_seed`, `from_secret`, `from_entropy`, `from_secret_numbers`
 - Added `address` alias to `Wallet.classic_address`
  - Replaced `Wallet.classic_address` with `Wallet.address` to avoid confusion. (`classic_address` is the same as your XRPL account `address`, and is only called classic since it's an older standard than `x-address`)
 - Added `network_id` to clients in order to use the `Client` with networks beyond mainnet
 
 ### Changed:
+
 - Updated params for `Wallet` class constructor
 - `Wallet.address` is now readonly
 - Removed `sequence` from `Wallet` class
@@ -45,11 +56,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - `XRP.to_amount` now converts from XRP to drops, instead of expecting a drops amount
 
 ### Fixed:
+
 - Added a sort of the account IDs in `multisign`, so that the `multisign` always works.
 - Add `ledger_hash` and `ledger_index` to `account_nfts`, `nft_buy_offers`, and `nft_sell_offers` requests.
 - Add `nft_page` to `ledger_entry` request.
 
 ### Removed:
+
 - `send_reliable_submission` has been replaced by `submit_and_wait`
 - Longer aliases for signing/submitting functions have been removed. Specifically
  - `submit_transaction` is now `submit`
@@ -65,26 +78,33 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
  - `get_transaction_from_hash`
 
 ## [1.9.0] - 2023-06-13
+
 ### Added:
+
 - Added `submit_and_wait` to sign (if needed), autofill, submit a transaction and wait for its final outcome
 - `submit` and `send_reliable_submission` now accept an optional boolean param `fail_hard` (if `True` halt the submission if it's not immediately validated)
 - Added sidechain devnet support to faucet generation
 - Added `user_agent` and `usage_context` to `generate_faucet_wallet`
 
 ### Changed:
+
 - Allowed keypairs.sign to take a hex string in addition to bytes
 
 ### Fixed:
+
 - Refactored `does_account_exist` and `get_balance` to avoid deprecated methods and use `ledger_index` parameter
 - Fixed crashes in the `SignerListSet` validation
 - Improved error messages in `send_reliable_submission`
 - Better error handling in reliable submission
 
 ### Removed:
+
 - RPCs and utils related to the old sidechain design
 
 ## [1.8.0] - 2023-04-10
+
 ### Added:
+
 - Created function alias to `safe_sign_transaction` called `sign` - safe originally used to indicate local offline signing (keys aren't exposed)
 - Created function alias to `safe_sign_and_autofill_transaction` called `autofill_and_sign` to reflect order of operations
 - Created function alias to `submit_transaction` called `submit`
@@ -95,21 +115,25 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Added the algorithm used to encode a wallet's seed to the wallet.
 
 ### Changed:
+
 - `check_fee` now has a higher limit that is less likely to be hit
 - When connected hooks v2 testnet generate_faucet_wallet now defaults to using the faucet instead of requiring specification
 - Deprecated `get_account_info`, `get_transaction_from_hash`, `get_account_payment_transactions` for direct requests
 - Private function `request_impl` has been renamed to `_request_impl`. Users should always use `request` over `request_impl`.
 - Removed nft-devnet faucet support as it has been decommissioned ([Blog Post](https://xrpl.org/blog/2023/nft-devnet-decommission.html))
 
 ### Fixed:
+
 - Properly type the instance functions of NestedModel
 - Add additional check to `txnNotFound` error from `reliable_submission` due to race condition
 - Add `nft_offer` type in `AccountObjects`
 - Handle errors better in `send_reliable_submission`
 - Made `send_reliable_submission` wait the full duration until `LastLedgerSequence` passes by
 
 ## [1.7.0] - 2022-10-12
+
 ### Added:
+
 - Support for ExpandedSignerList amendment that expands the maximum signer list to 32 entries
 - Function to parse the final account balances from a transaction's metadata
 - Function to parse order book changes from a transaction's metadata
@@ -119,42 +143,53 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Common field `ticket_sequence` to Transaction class
 
 ### Fixed:
+
 - Typing for factory classmethods on models
 - Use properly encoded transactions in `Sign`, `SignFor`, and `SignAndSubmit`
 - Fix Sphinx build errors due to incompatible version bumps
 
 ## [1.6.0] - 2022-06-02
+
 ### Added:
+
 - Support for dynamic fee calculation
 - Function to parse account balances from a transaction's metadata
 - Better error handling for invalid client URL
 - Exported SubscribeBook
 
 ### Fixed
+
 - Resolve `txnNotFound` error with `send_reliable_submission` when waiting for a submitted malformed transaction
 - Small typing mistake in GenericRequest
 - Fix bug in GenericRequest.to_dict()
 
 ## [1.5.0] - 2022-04-25
+
 ### Added
+
 - Support setting flags with booleans. For each transaction type supporting flags there is a `FlagInterface` to set the flags with booleans.
 - `federator_info` RPC support
 - Helper method for creating a cross-chain payment to/from a sidechain
 - Helper method for parsing an NFTokenID
 
 ### Fixed
+
 - Updated NFT names to match new 1.9.0 rippled names
 - `xrpl.asyncio.clients` exports (now includes `request_to_websocket`, `websocket_to_response`)
 - Adds optional `owner` field to NFTokenBurn
 - Allows lower-case currency codes
 
 ## [1.4.0] - 2022-02-24
+
 ### Added
+
 - Sync and async `generate_faucet_wallet` functions now support a custom
  faucet host
 
 ## [1.3.0] - 2021-12-17
+
 ### Added
+
 - Support for the [XLS-20 NFT proposal](https:/XRPLF/XRPL-Standards/discussions/46)
 - `xrpl.models.amounts.get_amount_value` helper function
 - `xrpl.utils.str_to_hex` and `xrpl.utils.hex_to_str` helpers
@@ -168,6 +203,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Exports `Transaction`, `Response`, pseudo-transactions at the `xrpl.models` level
 
 ### Fixed
+
 - Improves typing of `Response.result`
 - Makes the default ledger version for `get_next_valid_seq_number` `current` instead of `validated`
 - Stops erroring on non-`tesSUCCESS` responses in reliable transaction submission
@@ -181,21 +217,28 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Fixes bug where autofilling using an `xAddress` with `None` in the Destination Tag threw a KeyError
 
 ## [1.2.0] - 2021-11-09
+
 ### Added
+
 - Support for Python 3.10
 
 ### Fixed
+
 - Improves documentation on using websocket clients.
 - Fixes an issue sending NoRippleCheck requests
 - Allows projects that use xrpl-py as a dependency to use typing
 
 ## [1.1.1] - 2021-07-02
+
 ### Fixed
+
 - Fixes an issue encoding some non-standard currency values
 - Corrects installation instructions in documentation
 
 ## [1.1.0] - 2021-06-16
+
 ### Added
+
 - Option for `Transaction.flags` to be a `List` of `int`s instead of just an `int`
 - Instance method in `Transaction` objects to calculate their hashes locally
 - Additional reliability to `send_reliable_submission` by getting the hash before submitting
@@ -211,6 +254,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - A general `from_dict` method for `Request` models, analogous to `Transaction.from_dict`
 
 ### Fixed
+
 - Typos in docs/tests
 - Improved readability of the README/documentation
 - Expose `xrpl.utils` at the top level
@@ -221,6 +265,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Better error message reporting
 
 ## [1.0.0] - 2021-03-31
+
 ### Added
+
 - Initial release! Please open up an issue in our repo if you have any
  feedback or issues to report.

snippets/bridge_transfer.py

@@ -0,0 +1,105 @@
+"""CLI command for setting up a bridge."""
+
+from pprint import pprint
+from time import sleep
+
+from xrpl.account import does_account_exist, get_balance
+from xrpl.clients import JsonRpcClient
+from xrpl.models import (
+ AccountObjects,
+ AccountObjectType,
+ XChainAccountCreateCommit,
+ XChainBridge,
+ XChainCommit,
+ XChainCreateClaimID,
+)
+from xrpl.transaction import submit_and_wait
+from xrpl.utils import get_xchain_claim_id, xrp_to_drops
+from xrpl.wallet import Wallet, generate_faucet_wallet
+
+locking_client = JsonRpcClient("https://sidechain-net1.devnet.rippletest.net:51234")
+issuing_client = JsonRpcClient("https://sidechain-net2.devnet.rippletest.net:51234")
+
+locking_chain_door = "rMAXACCrp3Y8PpswXcg3bKggHX76V3F8M4"
+bridge_data = locking_client.request(
+ AccountObjects(account=locking_chain_door, type=AccountObjectType.BRIDGE)
+).result["account_objects"][0]
+bridge = XChainBridge.from_xrpl(bridge_data["XChainBridge"])
+print(bridge)
+
+print("Funding a wallet via the faucet on the locking chain...")
+wallet1 = generate_faucet_wallet(locking_client, debug=True)
+print(wallet1)
+wallet2 = Wallet.create()
+
+print(f"Creating {wallet2.classic_address} on the issuing chain via the bridge...")
+
+fund_tx = XChainAccountCreateCommit(
+ account=wallet1.classic_address,
+ xchain_bridge=bridge,
+ signature_reward=bridge_data["SignatureReward"],
+ destination=wallet2.classic_address,
+ amount=str(int(bridge_data["MinAccountCreateAmount"]) * 2),
+)
+fund_response = submit_and_wait(fund_tx, locking_client, wallet1)
+pprint(fund_response.result)
+
+
+print("Waiting for the attestation to go through on the issuing chain...")
+ledgers_waited = 0
+MAX_LEDGERS_WAITED = 5
+while ledgers_waited < MAX_LEDGERS_WAITED:
+ sleep(4)
+ if does_account_exist(wallet2.classic_address, issuing_client):
+ print(
+ f"Destination account {wallet2.classic_address} has been created via the "
+ "bridge"
+ )
+ initial_balance = get_balance(wallet2.classic_address, issuing_client)
+ break
+
+ ledgers_waited += 1
+ if ledgers_waited == MAX_LEDGERS_WAITED:
+ raise Exception("Destination account creation via the bridge failed.")
+
+print(
+ "Submitting XChainCreateClaimID transaction on the issuing chain to get an "
+ "XChainOwnedClaimID for the transfer..."
+)
+create_claim_id_tx = XChainCreateClaimID(
+ account=wallet2.classic_address,
+ xchain_bridge=bridge,
+ signature_reward=bridge_data["SignatureReward"],
+ other_chain_source=wallet1.classic_address,
+)
+create_claim_id_result = submit_and_wait(create_claim_id_tx, issuing_client, wallet2)
+pprint(create_claim_id_result.result)
+
+# Extract new sequence number from metadata
+xchain_claim_id = get_xchain_claim_id(create_claim_id_result.result["meta"])
+
+# XChainCommit
+
+print("Sending XChainCommit tx to lock the funds for transfer...")
+commit_tx = XChainCommit(
+ account=wallet1.classic_address,
+ amount=xrp_to_drops(1),
+ xchain_bridge=bridge,
+ xchain_claim_id=xchain_claim_id,
+ other_chain_destination=wallet2.classic_address,
+)
+commit_result = submit_and_wait(commit_tx, locking_client, wallet1)
+pprint(commit_result.result)
+
+print("Waiting for the attestation to go through on the issuing chain...")
+ledgers_waited = 0
+while ledgers_waited < MAX_LEDGERS_WAITED:
+ sleep(4)
+ current_balance = get_balance(wallet2.classic_address, issuing_client)
+ if current_balance != initial_balance:
+ print("Transfer is complete!")
+ break
+
+ ledgers_waited += 1
+ if ledgers_waited == MAX_LEDGERS_WAITED:
+ raise Exception("Bridge transfer failed.")

snippets/paths.py

@@ -36,7 +36,7 @@
 paths = path_response.result["alternatives"][0]["paths_computed"]
 print(paths)
 
-# # Create a Payment to send money from wallet to destination_account using path
+# Create a Payment to send money from wallet to destination_account using path
 payment_tx = Payment(
  account=wallet.address,
  amount=destination_amount,