From ee0522909fcfc4c58e004fbad1ba3065346b44e1 Mon Sep 17 00:00:00 2001 From: "Ryan G. Young" Date: Tue, 9 Mar 2021 11:52:22 -0800 Subject: [PATCH 01/18] initial structure and first code samples --- .../get-started/get-started-build-apps.md | 80 +++++++++++++++++++ dactyl-config.yml | 12 +++ 2 files changed, 92 insertions(+) create mode 100644 content/tutorials/get-started/get-started-build-apps.md diff --git a/content/tutorials/get-started/get-started-build-apps.md b/content/tutorials/get-started/get-started-build-apps.md new file mode 100644 index 0000000000..e4bea6014a --- /dev/null +++ b/content/tutorials/get-started/get-started-build-apps.md @@ -0,0 +1,80 @@ +# Get Started Building Apps on the XRP Ledger + + +When you're working with the XRP Ledger, there are a few things you'll need to manage with your app or integration, whether you're adding XRP into your [wallet](xref: wallets.md), integrating with the [decentralized exchange](xref: decentralized-exchange.md), or [issuing and managing tokens](xref:issued-currencies.md). This tutorial walks you through these common patterns and provides sample code for implementing them. + +Here are the basic steps you'll need to cover for almost any XRP Ledger project: + +1. [Generate keys.](#generate-keys) +2. [Connect to the XRP Ledger.](#connect) +3. [Query the XRP Ledger.](#query) +4. [Submit a transaction.](#submit-transaction) +5. [Verify results.](#verify-results) + +**Tip:** These steps roughly correspond to the best practices described in the [reliable transaction submission guide](xref:reliable-transaction-submission.md). + + +## Set up your environment + +Requirements for setting up your environment vary depending on the programming lanuage and tools you choose to use in your project; see the docs for the tools and libaries for details specific to the framework you want to work with. + +But regardless of the tools you use, there are a few things you'll need to work with the XRP Ledger. + +* Network client - You need a network client to query the XRP Ledger. SDKs and other libraries typically use the framework-native network modules for network connections. If you're only testing or exploring, you could use the [Websocket API](https://xrpl.org/websocket-api-tool.html) or [JSON-RPC](https://xrpl.org/xrp-ledger-rpc-tool.html) tools. +* [Account](xref: accounts.md) - If you want to interact with the Ledger by sumbitting transactions, you'll need an address, an XRP balance, and secret keys to manage the account. To get started on the Testnet or Devnet, you can use the [XRP Faucets](https://xrpl.org/xrp-testnet-faucet.html) to get an address, XRP balances, and keys. + + +For library-specific requirements, see the README for each project: + +* [ripple-lib](https://github.com/ripple/ripple-lib) (JavaScript) +* [xrpl-py](https://github.com/xpring-eng/xrpl-py) (Python) +* [xrpl-4j](https://github.com/XRPLF/xrpl4j) (Java) + +## Generate keys + +You need [keys](https://xrpl.org/cryptographic-keys.html) to sign transactions that you submit to the XRP Ledger. + +For testing and development purposes, you can get keys (and XRP balances) from [XRP Faucets](https://xrpl.org/xrp-testnet-faucet.html). + +Otherwise, you should take care to store your keys and set up a [secure signing method](https://xrpl.org/set-up-secure-signing.html). + +To generate keys, you can use any of the following methods: + + + +*JavaScript (ripple-lib)* + +``` +return api.generateAddress(); +``` + +*Python (xrpl-py)* + +``` +seed = keypairs.generate_seed() +public, private = keypairs.derive_keypair(seed) +``` + +*Java (xrpl4j)* + +``` +WalletFactory walletFactory = DefaultWalletFactory.getInstance(); +SeedWalletGenerationResult seedWalletGenerationResult = walletFactory.randomWallet(true); +``` + + + + +## Connect + +To make queries and submit transactions, you need to establish a connection to the XRP Ledger. + +## Query + +## Submit transaction + +## Verify results + + + + diff --git a/dactyl-config.yml b/dactyl-config.yml index 474695359d..c91fda6f4d 100644 --- a/dactyl-config.yml +++ b/dactyl-config.yml @@ -1580,6 +1580,18 @@ pages: targets: - ja + - md: tutorials/get-started/get-started-build-apps.md + html: get-started-build-apps.html + funnel: Build + doc_type: Tutorials + category: Get Started + template: template-doc.html + blurb: Learn the patterns to use when building apps on the XRP Ledger. + filters: + - js_editor + targets: + - en + - md: tutorials/get-started/get-started-with-the-rippled-api.md html: get-started-with-the-rippled-api.html funnel: Build From 12355f6a9dce0289bcba52b924def58c6e13f4da Mon Sep 17 00:00:00 2001 From: "Ryan G. Young" Date: Wed, 10 Mar 2021 17:45:35 -0800 Subject: [PATCH 02/18] add code samples for connect and query steps --- .../get-started/get-started-build-apps.md | 133 +++++++++++++++--- dactyl-config.yml | 8 -- 2 files changed, 115 insertions(+), 26 deletions(-) diff --git a/content/tutorials/get-started/get-started-build-apps.md b/content/tutorials/get-started/get-started-build-apps.md index e4bea6014a..7a6c468a35 100644 --- a/content/tutorials/get-started/get-started-build-apps.md +++ b/content/tutorials/get-started/get-started-build-apps.md @@ -1,7 +1,16 @@ -# Get Started Building Apps on the XRP Ledger +--- +html: build-apps.html +funnel: Build +doc_type: Tutorials +category: Get Started +blurb: Learn the common patterns for building apps on the XRP Ledger. +cta_text: Build Apps +--- + +# Build Apps on the XRP Ledger -When you're working with the XRP Ledger, there are a few things you'll need to manage with your app or integration, whether you're adding XRP into your [wallet](xref: wallets.md), integrating with the [decentralized exchange](xref: decentralized-exchange.md), or [issuing and managing tokens](xref:issued-currencies.md). This tutorial walks you through these common patterns and provides sample code for implementing them. +When you're working with the XRP Ledger, there are a few things you'll need to manage with your app or integration, whether you're adding XRP into your [wallet](xref: wallets.md), integrating with the [decentralized exchange](xref: decentralized-exchange.md), or [issuing and managing tokens](xref:issued-currencies.md). This tutorial walks you through the patterns common to all of these use cases and provides sample code for implementing them. Here are the basic steps you'll need to cover for almost any XRP Ledger project: @@ -11,24 +20,34 @@ Here are the basic steps you'll need to cover for almost any XRP Ledger project: 4. [Submit a transaction.](#submit-transaction) 5. [Verify results.](#verify-results) -**Tip:** These steps roughly correspond to the best practices described in the [reliable transaction submission guide](xref:reliable-transaction-submission.md). +**Tip:** These steps roughly correspond to the best practices described in the [reliable transaction submission guide](xref:reliable-transaction-submission.md). Refer to that before you start building for production. +## Learning Goals + +In this tutorial, you'll learn: + +* The basic building blocks of XRP Ledger-based applications. +* How to generate keys. +* How to connect to the XRP Ledger. +* How to submit a transaction, including preparing and signing it. +* How to put these steps together to create a simple app that submits a transaction to the XRP Ledger Testnet. ## Set up your environment Requirements for setting up your environment vary depending on the programming lanuage and tools you choose to use in your project; see the docs for the tools and libaries for details specific to the framework you want to work with. -But regardless of the tools you use, there are a few things you'll need to work with the XRP Ledger. +Regardless of the tools you use, there are a few things you'll need to work with the XRP Ledger. Most available libraries provide built-in network clients and creating accounts. -* Network client - You need a network client to query the XRP Ledger. SDKs and other libraries typically use the framework-native network modules for network connections. If you're only testing or exploring, you could use the [Websocket API](https://xrpl.org/websocket-api-tool.html) or [JSON-RPC](https://xrpl.org/xrp-ledger-rpc-tool.html) tools. -* [Account](xref: accounts.md) - If you want to interact with the Ledger by sumbitting transactions, you'll need an address, an XRP balance, and secret keys to manage the account. To get started on the Testnet or Devnet, you can use the [XRP Faucets](https://xrpl.org/xrp-testnet-faucet.html) to get an address, XRP balances, and keys. + +* **Network client** - You need a network client to query the XRP Ledger. SDKs and other libraries typically use the framework-native network modules. If you're only testing or exploring, you could use the [Websocket API](https://xrpl.org/websocket-api-tool.html) or [JSON-RPC](https://xrpl.org/xrp-ledger-rpc-tool.html) tools. +* **[Account](xref: accounts.md)** - If you want to interact with the Ledger by sumbitting transactions, you'll need an address, an XRP balance, and secret keys to manage the account. To get started on the Testnet or Devnet, you can use the [XRP Faucets](https://xrpl.org/xrp-testnet-faucet.html) to get an address, XRP balances, and keys. For library-specific requirements, see the README for each project: -* [ripple-lib](https://github.com/ripple/ripple-lib) (JavaScript) -* [xrpl-py](https://github.com/xpring-eng/xrpl-py) (Python) -* [xrpl-4j](https://github.com/XRPLF/xrpl4j) (Java) +* **JavaScript:** [ripple-lib](https://github.com/ripple/ripple-lib) +* **Python:** [xrpl-py](https://github.com/xpring-eng/xrpl-py) +* **Java:** [xrpl-4j](https://github.com/XRPLF/xrpl4j) ## Generate keys @@ -42,22 +61,22 @@ To generate keys, you can use any of the following methods: -*JavaScript (ripple-lib)* - -``` -return api.generateAddress(); -``` - *Python (xrpl-py)* -``` +```py seed = keypairs.generate_seed() public, private = keypairs.derive_keypair(seed) ``` +*JavaScript (ripple-lib)* + +```javascript +return api.generateAddress(); +``` + *Java (xrpl4j)* -``` +```java WalletFactory walletFactory = DefaultWalletFactory.getInstance(); SeedWalletGenerationResult seedWalletGenerationResult = walletFactory.randomWallet(true); ``` @@ -67,12 +86,90 @@ SeedWalletGenerationResult seedWalletGenerationResult = walletFactory.randomWall ## Connect -To make queries and submit transactions, you need to establish a connection to the XRP Ledger. +To make queries that you can use in your app and submit transactions, you need to establish a connection to the XRP Ledger. There are a few ways to do this. The following sections describe each option in more detail. + +**Warning:** Never use publicly available servers to sign transactions. For more information about security and signing, see [](xref: set-up-secure-signing.md). + +If you only want to explore the XRP Ledger, you can use the [Ledger Explorer](https://livenet.xrpl.org/) to see the Ledger progress in real-time and dig into specific accounts or transactions. + + + + +*Python (xrpl-py)* + +```py +client = JsonRpcClient(http://s1.ripple.com:51234/) +``` + +*JavaScript (ripple-lib)* + +```js +ripple = require('ripple-lib') +api = new ripple.RippleAPI({server: 'wss://s.altnet.rippletest.net:51233'}) +api.connect() +``` + +*Java (xrpl4j)* + +```java +private final XrplClient xrplClient = new XrplClient(HttpUrl.parse("https://s1.ripple.com:51234")); +``` + + + + +### Other connection options + + +#### Connect via Core Server + +The XRP Ledger's core server software, [`rippled`](the-rippled-server.html), natively exposes several interfaces that you can access by connecting to [publicly available servers](xref: get-started-with-the-rippled-api.md#public-servers) or running your own server. These interfaces include: + +* [JSON-RPC](xref: get-started-with-the-rippled-api.md#json-rpc) - If you're familiar with RESTful APIs, this interface will be the most familiar to you. You can use standard HTTP clients (like [Postman](https://www.postman.com/), [Insomnia](https://insomnia.rest/), or [RESTED for Firefox](https://addons.mozilla.org/en-US/firefox/addon/rested/)) to make calls via this interface. +* [WebSocket API](xref:get-started-with-the-rippled-api.md#websocket-api) - + +For a complete list of these interfaces and their associated methods, see [](xref: get-started-with-the-rippled-api.md). + ## Query +Before you submit a transaction to the XRP Ledger, you should query it to check your account status and balances to make sure that the transaction will succeed. + + + +*Python (xrpl-py)* + +```py +account_info = RequestMethod.ACCOUNT_INFO(rPT1Sjq2YGrBMTttX4GZHjKu9dyfzbpAYe) +``` + +*JavaScript (ripple-lib)* + +```js +const myAddress = 'rPT1Sjq2YGrBMTttX4GZHjKu9dyfzbpAYe'; + +console.log('getting account info for', myAddress); +return api.getAccountInfo(myAddress); +``` + +*Java (xrpl4j)* + +```java + AccountInfoResult accountInfo = this.scanForResult(() -> this.getValidatedAccountInfo(wallet.classicAddress())); + assertThat(accountInfo.status()).isNotEmpty().get().isEqualTo("success"); +``` + + + + ## Submit transaction +When you're ready + +### Prepare transaction + +### Sign transaction + ## Verify results diff --git a/dactyl-config.yml b/dactyl-config.yml index c91fda6f4d..ae6b848192 100644 --- a/dactyl-config.yml +++ b/dactyl-config.yml @@ -1581,14 +1581,6 @@ pages: - ja - md: tutorials/get-started/get-started-build-apps.md - html: get-started-build-apps.html - funnel: Build - doc_type: Tutorials - category: Get Started - template: template-doc.html - blurb: Learn the patterns to use when building apps on the XRP Ledger. - filters: - - js_editor targets: - en From 337180bb007cb8107cf2696133168ed378f95f69 Mon Sep 17 00:00:00 2001 From: "Ryan G. Young" Date: Thu, 11 Mar 2021 16:09:54 -0800 Subject: [PATCH 03/18] add new independent py tutorial and env setup --- .../get-started-with-python-sdk.md | 210 ++++++++++++++++++ dactyl-config.yml | 4 + 2 files changed, 214 insertions(+) create mode 100644 content/tutorials/get-started/get-started-with-python-sdk.md diff --git a/content/tutorials/get-started/get-started-with-python-sdk.md b/content/tutorials/get-started/get-started-with-python-sdk.md new file mode 100644 index 0000000000..6ad57e11e8 --- /dev/null +++ b/content/tutorials/get-started/get-started-with-python-sdk.md @@ -0,0 +1,210 @@ +--- +html: get-started-python.html +funnel: Build +doc_type: Tutorials +category: Get Started +blurb: Build a simple Python app that interacts with the XRP Ledger. +cta_text: Build Apps +--- + +# Get Started with Python and the XRP Ledger + +This tutorial walks you through the basics of building an XRP Ledger-connected application using [xrpl-py](https://github.com/xpring-eng/xrpl-py), a [Python](https://www.python.org) library that makes it easy to integrate XRP Ledger functionality into your apps. + + +## Learning Goals + +In this tutorial, you'll learn: + +* How to set up your environment for Python development. +* The basic building blocks of XRP Ledger-based applications. +* How to generate keys. +* How to connect to the XRP Ledger. +* How to submit a transaction, including preparing and signing it. +* How to put these steps together to create a simple app that submits a transaction to the XRP Ledger Testnet. + +## Environment Setup + +Complete the steps in the following sections to prepare your environment for development. + +Here are the pre-requisites for `xrpl-py`: + +* [Python 3.7](https://www.python.org/downloads/) or later +* [`pyenv`](https://github.com/pyenv/pyenv) +* [`poetry`](https://python-poetry.org/docs/) +* [`pre-commit`](https://pre-commit.com/) + +### Install the library + +You can get `xrpl-py` through these methods: + +* Clone the repo: + + git clone git@github.com:xpring-eng/xrpl-py.git + +* Install with `pip`: + + pip3 install xrpl-py + +* Download from [Python Package Index (PyPI)](https://pypi.org/) + +### Set up Python environment + +To make it easy to manage your Python environment with `xrpl-py`, including switching between versions, install `pyenv` and follow these steps: + +* Install [`pyenv`](https://github.com/pyenv/pyenv): + + brew install pyenv + + For other installation options, see the [`pyenv` README](https://github.com/pyenv/pyenv#installation). + +* Use `pyenv` to install the optimized version for `xrpl-py` (currently 3.9.1): + + pyenv install 3.9.1 + +* Set the [global](https://github.com/pyenv/pyenv/blob/master/COMMANDS.md#pyenv-global) version of Python with `pyenv`: + + pyenv global 3.9.1 + +### Set up shell environment + +To enable autcompletion and other functionality from your shell, add `pyenv` to your environment. + +These steps assume that you're using a [Zsh](http://zsh.sourceforge.net/) shell. For other shells, see the [`pyenv` README](https://github.com/pyenv/pyenv#basic-github-checkout). + + +* Add `pyenv init` to your Zsh shell: + + echo -e 'if command -v pyenv 1>/dev/null 2>&1; then\n eval "$(pyenv init -)"\nfi' >> ~/.zshrc + +* Source or restart your terminal: + + . ~/.zshrc + +### Manage dependencies and virutal environment + +To simplify managing library dependencies and the virtual environment, `xrpl-py` uses [`poetry`](https://python-poetry.org/docs). + +* [Install `poetry`](https://python-poetry.org/docs/#osx-linux-bashonwindows-install-instructions): + + curl -sSL https://raw.githubusercontent.com/python-poetry/poetry/master/get-poetry.py | python - + poetry install + +### Set up `pre-commit` hooks + +To run linting and other checks, `xrpl-py` uses [`pre-commit`](https://pre-commit.com/). + +**Note:** You only need to install `pre-commit` if you want to contribute code to `xrpl-py` or generate the reference documentation locally. + + +* Install `pre-commit`: + + pip3 install pre-commit + pre-commit install + +### Generate reference docs + +You can see the SDK reference docs at <<>>. You can also generate them locally using `poetry` and `sphinx`: + +```bash +# Go to the docs/ folder +cd docs/ + +# Build the docs +poetry run sphinx-apidoc -o source/ ../xrpl +poetry run make html +``` + +To see the output: + +```bash +# Go to docs/_build/html/ +cd docs/_build/html/ + +# Open the index file to view it in a browser: +open docs/_build/html/index.html +``` + +## Start building + +When you're working with the XRP Ledger, there are a few things you'll need to manage with your app or integration, whether you're adding XRP into your [wallet](xref: wallets.md), integrating with the [decentralized exchange](xref: decentralized-exchange.md), or [issuing and managing tokens](xref:issued-currencies.md). This tutorial walks you through the patterns common to all of these use cases and provides sample code for implementing them. + +Here are the basic steps you'll need to cover for almost any XRP Ledger project: + +1. [Generate keys.](#generate-keys) +2. [Connect to the XRP Ledger.](#connect) +3. [Query the XRP Ledger.](#query) +4. [Submit a transaction.](#submit-transaction) +5. [Verify results.](#verify-results) + +### Generate keys + +You need [keys](https://xrpl.org/cryptographic-keys.html) to sign transactions that you submit to the XRP Ledger. + +For testing and development purposes, you can get keys (and XRP balances) from [XRP Faucets](https://xrpl.org/xrp-testnet-faucet.html). + +Otherwise, you should take care to store your keys and set up a [secure signing method](https://xrpl.org/set-up-secure-signing.html). + + + +*Python (xrpl-py)* + +```py +seed = keypairs.generate_seed() +public, private = keypairs.derive_keypair(seed) +``` + + + +### Connect + +To make queries that you can use in your app and submit transactions, you need to establish a connection to the XRP Ledger. There are a few ways to do this. The following sections describe each option in more detail. + +**Warning:** Never use publicly available servers to sign transactions. For more information about security and signing, see [](xref: set-up-secure-signing.md). + +If you only want to explore the XRP Ledger, you can use the [Ledger Explorer](https://livenet.xrpl.org/) to see the Ledger progress in real-time and dig into specific accounts or transactions. + + + + +*Python (xrpl-py)* + +```py +client = JsonRpcClient(http://s1.ripple.com:51234/) +``` + + + + +### Query + +Before you submit a transaction to the XRP Ledger, you should query it to check your account status and balances to make sure that the transaction will succeed. + + + +*Python (xrpl-py)* + +```py +account_info = RequestMethod.ACCOUNT_INFO(rPT1Sjq2YGrBMTttX4GZHjKu9dyfzbpAYe) +``` + + + +### Submit transaction + +When you're ready to submit a transaction, follow the steps below. + +#### Prepare transaction + +```python + tx = Transaction( + account=_ACCOUNT, + fee=_FEE, + sequence=_SEQUENCE, + transaction_type=TransactionType.ACCOUNT_SET + ) +``` + +#### Sign transaction + +### Verify results \ No newline at end of file diff --git a/dactyl-config.yml b/dactyl-config.yml index ae6b848192..28466caf77 100644 --- a/dactyl-config.yml +++ b/dactyl-config.yml @@ -1584,6 +1584,10 @@ pages: targets: - en + - md: tutorials/get-started/get-started-with-python-sdk.md + targets: + - en + - md: tutorials/get-started/get-started-with-the-rippled-api.md html: get-started-with-the-rippled-api.html funnel: Build From 66fd6f8b384dd7796bc9e2208eceb3cd23284935 Mon Sep 17 00:00:00 2001 From: "Ryan G. Young" Date: Tue, 16 Mar 2021 17:31:45 -0700 Subject: [PATCH 04/18] add v rough sample code and initial structure --- .../xrpl-py/simple-python-app.py | 97 +++++++ .../get-started-with-python-sdk.md | 256 +++++++++--------- .../tutorials/get-started/python-env-setup.md | 116 ++++++++ dactyl-config.yml | 4 +- 4 files changed, 339 insertions(+), 134 deletions(-) create mode 100644 content/_code-samples/xrpl-py/simple-python-app.py create mode 100644 content/tutorials/get-started/python-env-setup.md diff --git a/content/_code-samples/xrpl-py/simple-python-app.py b/content/_code-samples/xrpl-py/simple-python-app.py new file mode 100644 index 0000000000..5521cfba66 --- /dev/null +++ b/content/_code-samples/xrpl-py/simple-python-app.py @@ -0,0 +1,97 @@ +import xrpl +from xrpl.models import Wallet +from xrpl.models.transactions.transaction import Transaction, TransactionType + + +# Define the URL of the server you want to use +JSON_RPC_URL = "http://s1.ripple.com:51234/" + +# Define the accounts you're going to use +CLASSIC_ACCOUNT = "" +SENDER_ACCOUNT = "rPT1Sjq2YGrBMTttX4GZHjKu9dyfzbpAYe" +address = "" +DESTINATION_WALLET = generate_faucet_wallet(JSON_RPC_URL).classic_address + +# You can create a wallet using the testnet faucet: +# https://xrpl.org/xrp-testnet-faucet.html +# with the generate_faucet_wallet function +TESTNET_ACCOUNT = generate_faucet_wallet(JSON_RPC_CLIENT).classic_address + +# Define variables to use for transactions +_ACCOUNT = "r9LqNeG6qHxjeUocjvVki2XR35weJ9mZgQ" +_FEE = "0.00001" +_SEQUENCE = 19048 + +# Secrets to use for signing transactions +_SECRET = "randomsecretkey" +_SEED = "randomsecretseedforakey" +_SEED_HEX = "EACEB081770D8ADE216C85445DD6FB002C6B5A2930F2DECE006DA18150CB18F6" +_PASSPHRASE = "mytopsecretpassphrasethatwillneverbehacked" + + +# Create an XRP Ledger wallet +# And create an x-address for the address +def createWallet(): + wallet = Wallet.generate_seed_and_wallet() + address = wallet.classic_address + xaddress = addresscodec.classic_address_to_xaddress( + classic_address, tag, True + ) + print("Classic address:", address) + print("X-address:", xaddress) + + + +# Optionally generate private and public keys +# to manage your XRP Ledger account +def generateKeys(): + seed = keypairs.generate_seed() + public, private = keypairs.derive_keypair(seed) + CLASSIC_ACCOUNT = keypairs.derive_classic_address(public) + print("Here's the public key: ", public + "Store this in a secure place.") + print("Here's the private key: ", private) + +# Look up information about your account +def getAcctInfo(): + client = JsonRpcClient(JSON_RPC_URL) + acct_info = AccountInfo( + account=address, + ledger_index="current", + queue=True, + strict=True, + ) + response = client.request(acct_info) + print("response.status: ", response.status) + print("response.result: ", response.result) + print("response.id: ", response.id) + print("response.type: ", response.type) + +# Prepare the tx by formatting it into +# the shape expected by the XRP Ledger +# and signing it +def prepareSignSubmitTx(): + CLASSIC_ACCOUNT.next_sequence_num = get_next_valid_seq_number(CLASSIC_ACCOUNT, JSON_RPC_CLIENT) + tx = Transaction( + account=_ACCOUNT, + fee=_FEE, + sequence=CLASSIC_ACCOUNT.next_seuqnece_num + 10, + transaction_type=TransactionType. + ) + value = tx.to_dict()["payment_trannsaction"] + signed_tx = Sign( + transaction=value, + seed=_SEED, + seed_hex=_SEED_HEX, + ) + print("Signed transaction: ", signed_tx) + payment_transaction = Payment.from_dict(value) + response = send_reliable_submission( + payment_transaction, CLASSIC_ACCOUNT, JSON_RPC_URL + ) + print("response.result.validated: ", response["validated"]) + print("response.result.meta: ", response.result["meta"]["TransactionResult"], "tesSUCCESS") + if response.result["meta"]["TransactionResult"] != "tesSUCCESS": + print("Transaction not yet validated") + else: + print("Validated!") + \ No newline at end of file diff --git a/content/tutorials/get-started/get-started-with-python-sdk.md b/content/tutorials/get-started/get-started-with-python-sdk.md index 6ad57e11e8..d7fa559af3 100644 --- a/content/tutorials/get-started/get-started-with-python-sdk.md +++ b/content/tutorials/get-started/get-started-with-python-sdk.md @@ -3,129 +3,33 @@ html: get-started-python.html funnel: Build doc_type: Tutorials category: Get Started +subcategory: Get Started Using Python blurb: Build a simple Python app that interacts with the XRP Ledger. cta_text: Build Apps --- -# Get Started with Python and the XRP Ledger +# Get started using Python This tutorial walks you through the basics of building an XRP Ledger-connected application using [xrpl-py](https://github.com/xpring-eng/xrpl-py), a [Python](https://www.python.org) library that makes it easy to integrate XRP Ledger functionality into your apps. -## Learning Goals +## Learning goals In this tutorial, you'll learn: -* How to set up your environment for Python development. +* How to set up your environment for Python development. See [](xref:python-env-setup.md). * The basic building blocks of XRP Ledger-based applications. * How to generate keys. * How to connect to the XRP Ledger. * How to submit a transaction, including preparing and signing it. * How to put these steps together to create a simple app that submits a transaction to the XRP Ledger Testnet. -## Environment Setup +## Requirements -Complete the steps in the following sections to prepare your environment for development. - -Here are the pre-requisites for `xrpl-py`: - -* [Python 3.7](https://www.python.org/downloads/) or later -* [`pyenv`](https://github.com/pyenv/pyenv) -* [`poetry`](https://python-poetry.org/docs/) -* [`pre-commit`](https://pre-commit.com/) - -### Install the library - -You can get `xrpl-py` through these methods: - -* Clone the repo: - - git clone git@github.com:xpring-eng/xrpl-py.git - -* Install with `pip`: - - pip3 install xrpl-py - -* Download from [Python Package Index (PyPI)](https://pypi.org/) - -### Set up Python environment - -To make it easy to manage your Python environment with `xrpl-py`, including switching between versions, install `pyenv` and follow these steps: - -* Install [`pyenv`](https://github.com/pyenv/pyenv): - - brew install pyenv - - For other installation options, see the [`pyenv` README](https://github.com/pyenv/pyenv#installation). - -* Use `pyenv` to install the optimized version for `xrpl-py` (currently 3.9.1): - - pyenv install 3.9.1 - -* Set the [global](https://github.com/pyenv/pyenv/blob/master/COMMANDS.md#pyenv-global) version of Python with `pyenv`: - - pyenv global 3.9.1 - -### Set up shell environment - -To enable autcompletion and other functionality from your shell, add `pyenv` to your environment. - -These steps assume that you're using a [Zsh](http://zsh.sourceforge.net/) shell. For other shells, see the [`pyenv` README](https://github.com/pyenv/pyenv#basic-github-checkout). - - -* Add `pyenv init` to your Zsh shell: - - echo -e 'if command -v pyenv 1>/dev/null 2>&1; then\n eval "$(pyenv init -)"\nfi' >> ~/.zshrc - -* Source or restart your terminal: - - . ~/.zshrc - -### Manage dependencies and virutal environment - -To simplify managing library dependencies and the virtual environment, `xrpl-py` uses [`poetry`](https://python-poetry.org/docs). - -* [Install `poetry`](https://python-poetry.org/docs/#osx-linux-bashonwindows-install-instructions): - - curl -sSL https://raw.githubusercontent.com/python-poetry/poetry/master/get-poetry.py | python - - poetry install - -### Set up `pre-commit` hooks - -To run linting and other checks, `xrpl-py` uses [`pre-commit`](https://pre-commit.com/). - -**Note:** You only need to install `pre-commit` if you want to contribute code to `xrpl-py` or generate the reference documentation locally. - - -* Install `pre-commit`: - - pip3 install pre-commit - pre-commit install - -### Generate reference docs - -You can see the SDK reference docs at <<>>. You can also generate them locally using `poetry` and `sphinx`: - -```bash -# Go to the docs/ folder -cd docs/ - -# Build the docs -poetry run sphinx-apidoc -o source/ ../xrpl -poetry run make html -``` - -To see the output: - -```bash -# Go to docs/_build/html/ -cd docs/_build/html/ - -# Open the index file to view it in a browser: -open docs/_build/html/index.html -``` +For information about setting up your environment for Python development, see [](xref:python-env-setup.md). ## Start building +{% set n = cycler(* range(1,99)) %} When you're working with the XRP Ledger, there are a few things you'll need to manage with your app or integration, whether you're adding XRP into your [wallet](xref: wallets.md), integrating with the [decentralized exchange](xref: decentralized-exchange.md), or [issuing and managing tokens](xref:issued-currencies.md). This tutorial walks you through the patterns common to all of these use cases and provides sample code for implementing them. @@ -137,7 +41,8 @@ Here are the basic steps you'll need to cover for almost any XRP Ledger project: 4. [Submit a transaction.](#submit-transaction) 5. [Verify results.](#verify-results) -### Generate keys +### {{n.next()}}. Generate keys + You need [keys](https://xrpl.org/cryptographic-keys.html) to sign transactions that you submit to the XRP Ledger. @@ -147,64 +52,151 @@ Otherwise, you should take care to store your keys and set up a [secure signing -*Python (xrpl-py)* +*Generate keypairs (xrpl-py)* ```py -seed = keypairs.generate_seed() -public, private = keypairs.derive_keypair(seed) +# Generate private and public keys +# to manage your XRP Ledger account +def generateKeys(): + seed = keypairs.generate_seed() + public, private = keypairs.derive_keypair(seed) + CLASSIC_ACCOUNT = keypairs.derive_classic_address(public) + print("Here's the public key: ", public) + print("Here's the private key: ", private) ``` +*Generate wallet (xrpl-py)* + +```py +# Create an XRP Ledger wallet +# And create an x-address for the address +def createWallet(): + wallet = Wallet.generate_seed_and_wallet() + address = wallet.classic_address + xaddress = addresscodec.classic_address_to_xaddress( + classic_address, tag, True + ) + print("Classic address:", address) + print("X-address:", xaddress) +``` + -### Connect +### {{n.next()}}. Connect To make queries that you can use in your app and submit transactions, you need to establish a connection to the XRP Ledger. There are a few ways to do this. The following sections describe each option in more detail. **Warning:** Never use publicly available servers to sign transactions. For more information about security and signing, see [](xref: set-up-secure-signing.md). +**Caution:** Ripple provides the [Testnet and Devnet](parallel-networks.html) for testing purposes only, and sometimes resets the state of these test networks along with all balances. As a precaution, Ripple recommends **not** using the same addresses on Testnet/Devnet and Mainnet. + + If you only want to explore the XRP Ledger, you can use the [Ledger Explorer](https://livenet.xrpl.org/) to see the Ledger progress in real-time and dig into specific accounts or transactions. - - -*Python (xrpl-py)* - ```py -client = JsonRpcClient(http://s1.ripple.com:51234/) +# Define the URL of the server you want to use +JSON_RPC_URL = "http://s1.ripple.com:51234/" ``` - - - -### Query +### {{n.next()}}. Query Before you submit a transaction to the XRP Ledger, you should query it to check your account status and balances to make sure that the transaction will succeed. - - -*Python (xrpl-py)* ```py -account_info = RequestMethod.ACCOUNT_INFO(rPT1Sjq2YGrBMTttX4GZHjKu9dyfzbpAYe) +# Look up information about your account +def getAcctInfo(): + client = JsonRpcClient(JSON_RPC_URL) + acct_info = AccountInfo( + account=address, + ledger_index="current", + queue=True, + strict=True, + ) + response = client.request(acct_info) + print("response.status: ", response.status) + print("response.result: ", response.result) + print("response.id: ", response.id) + print("response.type: ", response.type) ``` - -### Submit transaction +### {{n.next()}}. Submit transaction -When you're ready to submit a transaction, follow the steps below. +Submitting a transaction to the XRP inolves three distinct steps: + +* Preparing the transaction. +* Signing the transaction. +* Submitting the transaction to an XRP Ledger node. + +With `xrpl-py`, you can combine the these steps by using the `tx.to_dict` function and the `Sign` model. -#### Prepare transaction ```python - tx = Transaction( - account=_ACCOUNT, - fee=_FEE, - sequence=_SEQUENCE, - transaction_type=TransactionType.ACCOUNT_SET + # Prepare the tx by formatting it into +# the shape expected by the XRP Ledger +# and signing it +def prepareSignSubmitTx(): + CLASSIC_ACCOUNT.next_sequence_num = get_next_valid_seq_number(CLASSIC_ACCOUNT, JSON_RPC_CLIENT) + tx = Transaction( + account=_ACCOUNT, + fee=_FEE, + sequence=CLASSIC_ACCOUNT.next_seuqnece_num + 10, + transaction_type=TransactionType. + ) + value = tx.to_dict()["payment_trannsaction"] + signed_tx = Sign( + transaction=value, + seed=_SEED, + seed_hex=_SEED_HEX, + ) + print("Signed transaction: ", signed_tx) + payment_transaction = Payment.from_dict(value) + response = send_reliable_submission( + payment_transaction, CLASSIC_ACCOUNT, JSON_RPC_URL ) + print("response.result.validated: ", response["validated"]) + print("response.result.meta: ", response.result["meta"]["TransactionResult"], "tesSUCCESS") ``` -#### Sign transaction -### Verify results \ No newline at end of file +### {{n.next()}}. Verify results + +To ensure that your transaction has succeeded in a validated ledger, which means that the results are final, you can add simple logic to your submit function: + + +```python +if response.result["meta"]["TransactionResult"] != "tesSUCCESS": + print("Transaction not yet validated") +else: + print("Validated!") +``` + + + +### {{n.next()}}. Putting it all together + +Using these building blocks, we can create a simple app that: + +1. Generates a wallet. +2. Connects to the XRP Ledger. +3. Looks up information about your account. +4. Sends XRP from one account to another. +5. Verifies the transaction in a validated ledger. + + +```python +{% include '_code-samples/xrpl-py/simple-python-app.py' %} +``` + + +## Next steps + +<> + +Try using `xrpl-py` to: + +* Set Account Flags +* Issue a token on the Devnet +* Set up an escrow diff --git a/content/tutorials/get-started/python-env-setup.md b/content/tutorials/get-started/python-env-setup.md new file mode 100644 index 0000000000..16dec48f6f --- /dev/null +++ b/content/tutorials/get-started/python-env-setup.md @@ -0,0 +1,116 @@ +--- +html: set-up-python-env.html +funnel: Build +doc_type: Tutorials +category: Get Started +subcategory: Get Started Using Python +#parent: get-started-python.html - field not used by the site yet +blurb: Set up your environment to start Python development. +cta_text: Build Apps +--- + +## Python Environment Setup + +Complete the steps in the following sections to prepare your environment for development. + +Here are the pre-requisites for `xrpl-py`: + +* [Python 3.7](https://www.python.org/downloads/) or later +* [`pyenv`](https://github.com/pyenv/pyenv) +* [`poetry`](https://python-poetry.org/docs/) +* [`pre-commit`](https://pre-commit.com/) + +### Install the library + +You can get `xrpl-py` through these methods: + +* Clone the repo: + + git clone git@github.com:xpring-eng/xrpl-py.git + +* Install with `pip`: + + pip3 install xrpl-py + +* Download from [Python Package Index (PyPI)](https://pypi.org/) + +### Set up Python environment + +To make it easy to manage your Python environment with `xrpl-py`, including switching between versions, install `pyenv` and follow these steps: + +* Install [`pyenv`](https://github.com/pyenv/pyenv): + + brew install pyenv + + For other installation options, see the [`pyenv` README](https://github.com/pyenv/pyenv#installation). + +* Use `pyenv` to install the optimized version for `xrpl-py` (currently 3.9.1): + + pyenv install 3.9.1 + +* Set the [global](https://github.com/pyenv/pyenv/blob/master/COMMANDS.md#pyenv-global) version of Python with `pyenv`: + + pyenv global 3.9.1 + +### Set up shell environment + +To enable autcompletion and other functionality from your shell, add `pyenv` to your environment. + +These steps assume that you're using a [Zsh](http://zsh.sourceforge.net/) shell. For other shells, see the [`pyenv` README](https://github.com/pyenv/pyenv#basic-github-checkout). + + +* Add `pyenv init` to your Zsh shell: + + echo -e 'if command -v pyenv 1>/dev/null 2>&1; then\n eval "$(pyenv init -)"\nfi' >> ~/.zshrc + +* Source or restart your terminal: + + . ~/.zshrc + +### Manage dependencies and virutal environment + +To simplify managing library dependencies and the virtual environment, `xrpl-py` uses [`poetry`](https://python-poetry.org/docs). + +* [Install `poetry`](https://python-poetry.org/docs/#osx-linux-bashonwindows-install-instructions): + + curl -sSL https://raw.githubusercontent.com/python-poetry/poetry/master/get-poetry.py | python - + poetry install + +### Set up `pre-commit` hooks + +To run linting and other checks, `xrpl-py` uses [`pre-commit`](https://pre-commit.com/). + +**Note:** You only need to install `pre-commit` if you want to contribute code to `xrpl-py` or generate the reference documentation locally. + + +* Install `pre-commit`: + + pip3 install pre-commit + pre-commit install + +### Generate reference docs + +You can see the SDK reference docs at <<>>. You can also generate them locally using `poetry` and `sphinx`: + +```bash +# Go to the docs/ folder +cd docs/ + +# Build the docs +poetry run sphinx-apidoc -o source/ ../xrpl +poetry run make html +``` + +To see the output: + +```bash +# Go to docs/_build/html/ +cd docs/_build/html/ + +# Open the index file to view it in a browser: +open docs/_build/html/index.html +``` + +## Next Steps + +Start building apps! See [](xref:get-started-with-python-sdk.md) for a tutorial that explains how to get started with `xrpl-py`. \ No newline at end of file diff --git a/dactyl-config.yml b/dactyl-config.yml index 28466caf77..ad593eedf6 100644 --- a/dactyl-config.yml +++ b/dactyl-config.yml @@ -1580,11 +1580,11 @@ pages: targets: - ja - - md: tutorials/get-started/get-started-build-apps.md + - md: tutorials/get-started/get-started-with-python-sdk.md targets: - en - - md: tutorials/get-started/get-started-with-python-sdk.md + - md: tutorials/get-started/python-env-setup.md targets: - en From 7f32f1943ec9f858ae4b32436e07b317d066cd8c Mon Sep 17 00:00:00 2001 From: "Ryan G. Young" Date: Fri, 19 Mar 2021 16:56:58 -0700 Subject: [PATCH 05/18] updated sample app per teting and feedback --- .../xrpl-py/simple-python-app.py | 110 +++++++++++++----- 1 file changed, 82 insertions(+), 28 deletions(-) diff --git a/content/_code-samples/xrpl-py/simple-python-app.py b/content/_code-samples/xrpl-py/simple-python-app.py index 5521cfba66..a776cd4bb5 100644 --- a/content/_code-samples/xrpl-py/simple-python-app.py +++ b/content/_code-samples/xrpl-py/simple-python-app.py @@ -1,26 +1,72 @@ import xrpl -from xrpl.models import Wallet -from xrpl.models.transactions.transaction import Transaction, TransactionType + +# Core modules to +# To generate keypairs and encode addresses +from xrpl.core import keypairs +from xrpl.core.addresscodec.main import classic_address_to_xaddress + +# Network client +from xrpl.clients.json_rpc_client import JsonRpcClient + +# To create test wallets +from xrpl.wallet import generate_faucet_wallet + +# Request models +from xrpl.models.requests.account_info import AccountInfo + +# Wallet models +from xrpl.wallet import Wallet + +# Transaction models +from xrpl.models.transactions.transaction import Transaction, TransactionType, AccountSet, Payment +from xrpl.models.transactions import AccountSet +from xrpl.transaction import ( + LastLedgerSequenceExpiredException, +) +from xrpl.transaction.main import ( + safe_sign_and_submit_transaction, + safe_sign_transaction, + submit_transaction_blob, + transaction_json_to_binary_codec_form, +) +from xrpl.transaction.reliable_submission import send_reliable_submission + +# Account models +from xrpl.account import get_next_valid_seq_number -# Define the URL of the server you want to use -JSON_RPC_URL = "http://s1.ripple.com:51234/" -# Define the accounts you're going to use -CLASSIC_ACCOUNT = "" -SENDER_ACCOUNT = "rPT1Sjq2YGrBMTttX4GZHjKu9dyfzbpAYe" -address = "" -DESTINATION_WALLET = generate_faucet_wallet(JSON_RPC_URL).classic_address -# You can create a wallet using the testnet faucet: +#JSON handling +import json + +# Define the network client +JSON_RPC_URL_TESTNET = "https://s.altnet.rippletest.net:51234/" +JSON_RPC_CLIENT_TESTNET = JsonRpcClient(JSON_RPC_URL_TESTNET) + + +JSON_RPC_URL_DEVNET = "https://s.devnet.rippletest.net:51234/" +JSON_RPC_CLIENT_DEVNET = JsonRpcClient(JSON_RPC_URL_DEVNET) + +# Create wallets using the testnet faucet: # https://xrpl.org/xrp-testnet-faucet.html -# with the generate_faucet_wallet function -TESTNET_ACCOUNT = generate_faucet_wallet(JSON_RPC_CLIENT).classic_address +TESTNET_WALLET = generate_faucet_wallet(JSON_RPC_CLIENT_TESTNET) +TESTNET_CLASSIC_ACCOUNT = TESTNET_WALLET.classic_address + +DEVNET_WALLET = generate_faucet_wallet(JSON_RPC_CLIENT_DEVNET) +DEVNET_CLASSIC_ACCOUNT = DEVNET_WALLET.classic_address + +# Define the receiver accounts +TESTNET_DESTINATION_WALLET = generate_faucet_wallet(JSON_RPC_CLIENT_TESTNET) +TESTNET_DESTINATION_ACCOUNT = TESTNET_DESTINATION_WALLET.classic_address + # Define variables to use for transactions _ACCOUNT = "r9LqNeG6qHxjeUocjvVki2XR35weJ9mZgQ" -_FEE = "0.00001" +_FEE = "10" _SEQUENCE = 19048 +SET_FLAG = 8 +MEMO = "I built this with xrpl-py!" # Secrets to use for signing transactions _SECRET = "randomsecretkey" @@ -31,11 +77,11 @@ _PASSPHRASE = "mytopsecretpassphrasethatwillneverbehacked" # Create an XRP Ledger wallet # And create an x-address for the address -def createWallet(): - wallet = Wallet.generate_seed_and_wallet() - address = wallet.classic_address +def create_wallet(): + TESTNET_WALLET = generate_faucet_wallet(JSON_RPC_CLIENT_TESTNET) + wallet2_address = wallet2.classic_address xaddress = addresscodec.classic_address_to_xaddress( - classic_address, tag, True + wallet2_address, tag, True ) print("Classic address:", address) print("X-address:", xaddress) @@ -44,7 +90,7 @@ def createWallet(): # Optionally generate private and public keys # to manage your XRP Ledger account -def generateKeys(): +def generate_keys(): seed = keypairs.generate_seed() public, private = keypairs.derive_keypair(seed) CLASSIC_ACCOUNT = keypairs.derive_classic_address(public) @@ -52,32 +98,40 @@ def generateKeys(): print("Here's the private key: ", private) # Look up information about your account -def getAcctInfo(): +def get_acct_info(): client = JsonRpcClient(JSON_RPC_URL) acct_info = AccountInfo( - account=address, + account=wallet, ledger_index="current", queue=True, strict=True, ) - response = client.request(acct_info) + response = JSON_RPC_CLIENT_TESTNET.request(acct_info) print("response.status: ", response.status) print("response.result: ", response.result) print("response.id: ", response.id) print("response.type: ", response.type) + print("response.result.account_data.Balance", response.result.account_data.Balance) + for key, value in response.result(): + print(key, value) + for k, v in value.result(): + print(k,v) + + # Prepare the tx by formatting it into # the shape expected by the XRP Ledger # and signing it -def prepareSignSubmitTx(): - CLASSIC_ACCOUNT.next_sequence_num = get_next_valid_seq_number(CLASSIC_ACCOUNT, JSON_RPC_CLIENT) - tx = Transaction( - account=_ACCOUNT, +def prepare_sign_submit_tx(): + TESTNET_WALLET.next_sequence_num = get_next_valid_seq_number(TESTNET_CLASSIC_ACCOUNT, JSON_RPC_CLIENT_TESTNET) + account_set = AccountSet( + account=TESTNET_CLASSIC_ACCOUNT, fee=_FEE, - sequence=CLASSIC_ACCOUNT.next_seuqnece_num + 10, - transaction_type=TransactionType. + sequence=TESTNET_WALLET.next_sequence_num, + set_flag=SET_FLAG, ) - value = tx.to_dict()["payment_trannsaction"] + response = safe_sign_and_submit_transaction(account_set, TESTNET_WALLET, JSON_RPC_CLIENT_TESTNET) + value = tx.to_dict()[] signed_tx = Sign( transaction=value, seed=_SEED, From 1f59faa152b424ff11d2812cf8063cf24be0d0e3 Mon Sep 17 00:00:00 2001 From: "Ryan G. Young" Date: Tue, 23 Mar 2021 00:18:36 -0700 Subject: [PATCH 06/18] revise sample app and tutorial --- .../xrpl-py/simple-python-app.py | 86 ++++----- .../get-started/get-started-build-apps.md | 177 ------------------ .../get-started-with-python-sdk.md | 4 +- 3 files changed, 46 insertions(+), 221 deletions(-) delete mode 100644 content/tutorials/get-started/get-started-build-apps.md diff --git a/content/_code-samples/xrpl-py/simple-python-app.py b/content/_code-samples/xrpl-py/simple-python-app.py index a776cd4bb5..cf3ac640ca 100644 --- a/content/_code-samples/xrpl-py/simple-python-app.py +++ b/content/_code-samples/xrpl-py/simple-python-app.py @@ -1,25 +1,12 @@ import xrpl - -# Core modules to -# To generate keypairs and encode addresses from xrpl.core import keypairs from xrpl.core.addresscodec.main import classic_address_to_xaddress - -# Network client from xrpl.clients.json_rpc_client import JsonRpcClient - -# To create test wallets from xrpl.wallet import generate_faucet_wallet - -# Request models from xrpl.models.requests.account_info import AccountInfo - -# Wallet models from xrpl.wallet import Wallet - -# Transaction models -from xrpl.models.transactions.transaction import Transaction, TransactionType, AccountSet, Payment -from xrpl.models.transactions import AccountSet +from xrpl.models.transactions.transaction import Transaction, TransactionType, Memo +from xrpl.models.transactions import AccountSet, Payment from xrpl.transaction import ( LastLedgerSequenceExpiredException, ) @@ -30,14 +17,7 @@ from xrpl.transaction.main import ( transaction_json_to_binary_codec_form, ) from xrpl.transaction.reliable_submission import send_reliable_submission - -# Account models from xrpl.account import get_next_valid_seq_number - - - - -#JSON handling import json # Define the network client @@ -63,30 +43,37 @@ TESTNET_DESTINATION_ACCOUNT = TESTNET_DESTINATION_WALLET.classic_address # Define variables to use for transactions _ACCOUNT = "r9LqNeG6qHxjeUocjvVki2XR35weJ9mZgQ" +_AMOUNT = "20" _FEE = "10" +_MEMO = "I sent this with xrpl-py!" _SEQUENCE = 19048 SET_FLAG = 8 -MEMO = "I built this with xrpl-py!" # Secrets to use for signing transactions -_SECRET = "randomsecretkey" -_SEED = "randomsecretseedforakey" +_SECRET = "" +_SEED = "" _SEED_HEX = "EACEB081770D8ADE216C85445DD6FB002C6B5A2930F2DECE006DA18150CB18F6" _PASSPHRASE = "mytopsecretpassphrasethatwillneverbehacked" -# Create an XRP Ledger wallet -# And create an x-address for the address -def create_wallet(): +# Create an XRP Ledger wallet from the +# testnet faucet and derive an +# x-address for the address +def create_wallet_from_faucet(): TESTNET_WALLET = generate_faucet_wallet(JSON_RPC_CLIENT_TESTNET) - wallet2_address = wallet2.classic_address + wallet_classic_address = TESTNET_WALLET.classic_address xaddress = addresscodec.classic_address_to_xaddress( wallet2_address, tag, True ) - print("Classic address:", address) - print("X-address:", xaddress) - + print("\nClassic address:\n\n", wallet_classic_address) + print("X-address:\n\n", xaddress) +# Create an XRP Ledger wallet from +# a generated seed +def create_wallet_from_seed(): + seed = keypairs.generate_seed() + wallet_from_seed = xrpl.wallet.Wallet(seed) + print(wallet_from_seed) # Optionally generate private and public keys # to manage your XRP Ledger account @@ -94,12 +81,12 @@ def generate_keys(): seed = keypairs.generate_seed() public, private = keypairs.derive_keypair(seed) CLASSIC_ACCOUNT = keypairs.derive_classic_address(public) - print("Here's the public key: ", public + "Store this in a secure place.") - print("Here's the private key: ", private) + print(f"Here's the public key:\n", public) + print(f"Here's the private key:\n", private + "\nStore this in a secure place.") # Look up information about your account def get_acct_info(): - client = JsonRpcClient(JSON_RPC_URL) + client = JsonRpcClient(JSON_RPC_URL_TESTNET) acct_info = AccountInfo( account=wallet, ledger_index="current", @@ -112,12 +99,30 @@ def get_acct_info(): print("response.id: ", response.id) print("response.type: ", response.type) print("response.result.account_data.Balance", response.result.account_data.Balance) - for key, value in response.result(): - print(key, value) - for k, v in value.result(): - print(k,v) +# FUTURE Prepare tx +def prepare_tx_future(): + my_tx_future = Transaction.from_xrpl( + { + "TransactionType": "Payment", + "Amount": "50", + "Destination": "rNZz9HS8mmKqb3jGk28PjNMkkRXRzGdTda", + "Account": "rKQxjvLW67ZkMQdu9wmy73vhrbPcir21SV" + } + ) + TESTNET_WALLET.next_sequence_num = get_next_valid_seq_number(TESTNET_CLASSIC_ACCOUNT, JSON_RPC_CLIENT_TESTNET) + +# CURRENT Prepare tx +def prepare_tx_current(): + my_tx_current = Payment( + account=TESTNET_CLASSIC_ACCOUNT, + amount=_AMOUNT, + destination=TESTNET_DESTINATION_ACCOUNT, + memos=_MEMO, + transaction_type=TransactionType.PAYMENT, + ) + TESTNET_WALLET.next_sequence_num = get_next_valid_seq_number(TESTNET_CLASSIC_ACCOUNT, JSON_RPC_CLIENT_TESTNET) # Prepare the tx by formatting it into # the shape expected by the XRP Ledger @@ -139,9 +144,6 @@ def prepare_sign_submit_tx(): ) print("Signed transaction: ", signed_tx) payment_transaction = Payment.from_dict(value) - response = send_reliable_submission( - payment_transaction, CLASSIC_ACCOUNT, JSON_RPC_URL - ) print("response.result.validated: ", response["validated"]) print("response.result.meta: ", response.result["meta"]["TransactionResult"], "tesSUCCESS") if response.result["meta"]["TransactionResult"] != "tesSUCCESS": diff --git a/content/tutorials/get-started/get-started-build-apps.md b/content/tutorials/get-started/get-started-build-apps.md deleted file mode 100644 index 7a6c468a35..0000000000 --- a/content/tutorials/get-started/get-started-build-apps.md +++ /dev/null @@ -1,177 +0,0 @@ ---- -html: build-apps.html -funnel: Build -doc_type: Tutorials -category: Get Started -blurb: Learn the common patterns for building apps on the XRP Ledger. -cta_text: Build Apps ---- - -# Build Apps on the XRP Ledger - - -When you're working with the XRP Ledger, there are a few things you'll need to manage with your app or integration, whether you're adding XRP into your [wallet](xref: wallets.md), integrating with the [decentralized exchange](xref: decentralized-exchange.md), or [issuing and managing tokens](xref:issued-currencies.md). This tutorial walks you through the patterns common to all of these use cases and provides sample code for implementing them. - -Here are the basic steps you'll need to cover for almost any XRP Ledger project: - -1. [Generate keys.](#generate-keys) -2. [Connect to the XRP Ledger.](#connect) -3. [Query the XRP Ledger.](#query) -4. [Submit a transaction.](#submit-transaction) -5. [Verify results.](#verify-results) - -**Tip:** These steps roughly correspond to the best practices described in the [reliable transaction submission guide](xref:reliable-transaction-submission.md). Refer to that before you start building for production. - -## Learning Goals - -In this tutorial, you'll learn: - -* The basic building blocks of XRP Ledger-based applications. -* How to generate keys. -* How to connect to the XRP Ledger. -* How to submit a transaction, including preparing and signing it. -* How to put these steps together to create a simple app that submits a transaction to the XRP Ledger Testnet. - -## Set up your environment - -Requirements for setting up your environment vary depending on the programming lanuage and tools you choose to use in your project; see the docs for the tools and libaries for details specific to the framework you want to work with. - -Regardless of the tools you use, there are a few things you'll need to work with the XRP Ledger. Most available libraries provide built-in network clients and creating accounts. - - -* **Network client** - You need a network client to query the XRP Ledger. SDKs and other libraries typically use the framework-native network modules. If you're only testing or exploring, you could use the [Websocket API](https://xrpl.org/websocket-api-tool.html) or [JSON-RPC](https://xrpl.org/xrp-ledger-rpc-tool.html) tools. -* **[Account](xref: accounts.md)** - If you want to interact with the Ledger by sumbitting transactions, you'll need an address, an XRP balance, and secret keys to manage the account. To get started on the Testnet or Devnet, you can use the [XRP Faucets](https://xrpl.org/xrp-testnet-faucet.html) to get an address, XRP balances, and keys. - - -For library-specific requirements, see the README for each project: - -* **JavaScript:** [ripple-lib](https://github.com/ripple/ripple-lib) -* **Python:** [xrpl-py](https://github.com/xpring-eng/xrpl-py) -* **Java:** [xrpl-4j](https://github.com/XRPLF/xrpl4j) - -## Generate keys - -You need [keys](https://xrpl.org/cryptographic-keys.html) to sign transactions that you submit to the XRP Ledger. - -For testing and development purposes, you can get keys (and XRP balances) from [XRP Faucets](https://xrpl.org/xrp-testnet-faucet.html). - -Otherwise, you should take care to store your keys and set up a [secure signing method](https://xrpl.org/set-up-secure-signing.html). - -To generate keys, you can use any of the following methods: - - - -*Python (xrpl-py)* - -```py -seed = keypairs.generate_seed() -public, private = keypairs.derive_keypair(seed) -``` - -*JavaScript (ripple-lib)* - -```javascript -return api.generateAddress(); -``` - -*Java (xrpl4j)* - -```java -WalletFactory walletFactory = DefaultWalletFactory.getInstance(); -SeedWalletGenerationResult seedWalletGenerationResult = walletFactory.randomWallet(true); -``` - - - - -## Connect - -To make queries that you can use in your app and submit transactions, you need to establish a connection to the XRP Ledger. There are a few ways to do this. The following sections describe each option in more detail. - -**Warning:** Never use publicly available servers to sign transactions. For more information about security and signing, see [](xref: set-up-secure-signing.md). - -If you only want to explore the XRP Ledger, you can use the [Ledger Explorer](https://livenet.xrpl.org/) to see the Ledger progress in real-time and dig into specific accounts or transactions. - - - - -*Python (xrpl-py)* - -```py -client = JsonRpcClient(http://s1.ripple.com:51234/) -``` - -*JavaScript (ripple-lib)* - -```js -ripple = require('ripple-lib') -api = new ripple.RippleAPI({server: 'wss://s.altnet.rippletest.net:51233'}) -api.connect() -``` - -*Java (xrpl4j)* - -```java -private final XrplClient xrplClient = new XrplClient(HttpUrl.parse("https://s1.ripple.com:51234")); -``` - - - - -### Other connection options - - -#### Connect via Core Server - -The XRP Ledger's core server software, [`rippled`](the-rippled-server.html), natively exposes several interfaces that you can access by connecting to [publicly available servers](xref: get-started-with-the-rippled-api.md#public-servers) or running your own server. These interfaces include: - -* [JSON-RPC](xref: get-started-with-the-rippled-api.md#json-rpc) - If you're familiar with RESTful APIs, this interface will be the most familiar to you. You can use standard HTTP clients (like [Postman](https://www.postman.com/), [Insomnia](https://insomnia.rest/), or [RESTED for Firefox](https://addons.mozilla.org/en-US/firefox/addon/rested/)) to make calls via this interface. -* [WebSocket API](xref:get-started-with-the-rippled-api.md#websocket-api) - - -For a complete list of these interfaces and their associated methods, see [](xref: get-started-with-the-rippled-api.md). - - -## Query - -Before you submit a transaction to the XRP Ledger, you should query it to check your account status and balances to make sure that the transaction will succeed. - - - -*Python (xrpl-py)* - -```py -account_info = RequestMethod.ACCOUNT_INFO(rPT1Sjq2YGrBMTttX4GZHjKu9dyfzbpAYe) -``` - -*JavaScript (ripple-lib)* - -```js -const myAddress = 'rPT1Sjq2YGrBMTttX4GZHjKu9dyfzbpAYe'; - -console.log('getting account info for', myAddress); -return api.getAccountInfo(myAddress); -``` - -*Java (xrpl4j)* - -```java - AccountInfoResult accountInfo = this.scanForResult(() -> this.getValidatedAccountInfo(wallet.classicAddress())); - assertThat(accountInfo.status()).isNotEmpty().get().isEqualTo("success"); -``` - - - - -## Submit transaction - -When you're ready - -### Prepare transaction - -### Sign transaction - -## Verify results - - - - diff --git a/content/tutorials/get-started/get-started-with-python-sdk.md b/content/tutorials/get-started/get-started-with-python-sdk.md index d7fa559af3..a01996c30e 100644 --- a/content/tutorials/get-started/get-started-with-python-sdk.md +++ b/content/tutorials/get-started/get-started-with-python-sdk.md @@ -8,7 +8,7 @@ blurb: Build a simple Python app that interacts with the XRP Ledger. cta_text: Build Apps --- -# Get started using Python +# Get Started Using Python This tutorial walks you through the basics of building an XRP Ledger-connected application using [xrpl-py](https://github.com/xpring-eng/xrpl-py), a [Python](https://www.python.org) library that makes it easy to integrate XRP Ledger functionality into your apps. @@ -17,7 +17,7 @@ This tutorial walks you through the basics of building an XRP Ledger-connected a In this tutorial, you'll learn: -* How to set up your environment for Python development. See [](xref:python-env-setup.md). +* How to set up your environment for Python development. See [](python-env-setup.html). * The basic building blocks of XRP Ledger-based applications. * How to generate keys. * How to connect to the XRP Ledger. From d6180b5a63199feadb39cdf8c996638a38521bd1 Mon Sep 17 00:00:00 2001 From: "Ryan G. Young" Date: Fri, 26 Mar 2021 17:12:06 -0700 Subject: [PATCH 07/18] remove env setup, begin refactor --- .../_code-samples/xrpl-py/get-acct-info.py | 35 ++++ .../xrpl-py/simple-python-app.py | 153 ------------------ ...hon-sdk.md => get-started-using-python.md} | 86 +++++++--- .../tutorials/get-started/python-env-setup.md | 116 ------------- dactyl-config.yml | 6 +- 5 files changed, 100 insertions(+), 296 deletions(-) create mode 100644 content/_code-samples/xrpl-py/get-acct-info.py delete mode 100644 content/_code-samples/xrpl-py/simple-python-app.py rename content/tutorials/get-started/{get-started-with-python-sdk.md => get-started-using-python.md} (58%) delete mode 100644 content/tutorials/get-started/python-env-setup.md diff --git a/content/_code-samples/xrpl-py/get-acct-info.py b/content/_code-samples/xrpl-py/get-acct-info.py new file mode 100644 index 0000000000..e07c30883c --- /dev/null +++ b/content/_code-samples/xrpl-py/get-acct-info.py @@ -0,0 +1,35 @@ +# Define the network client +from xrpl.clients import JsonRpcClient +JSON_RPC_URL = "https://s.altnet.rippletest.net:51234/" +client = JsonRpcClient(JSON_RPC_URL) + + +# Create a wallet using the testnet faucet: +# https://xrpl.org/xrp-testnet-faucet.html +from xrpl.wallet import generate_faucet_wallet +test_wallet = generate_faucet_wallet(client) + +# Create an account str from the wallet +test_account = test_wallet.classic_address + +# Derive an x-address from the classic address: +# https://xrpaddress.info/ +from xrpl.core import addresscodec +test_xaddress = addresscodec.classic_address_to_xaddress(test_account, tag=0, is_test_network=True) +print("\nClassic address:\n\n", test_account) +print("X-address:\n\n", test_xaddress) + + +# Look up info about your account +from xrpl.models.requests.account_info import AccountInfo +acct_info = AccountInfo( + account=test_account, + ledger_index="current", + queue=True, + strict=True, +) +response = client.request(acct_info) +result = response.result +print("response.status: ", response.status) +import json +print(json.dumps(response.result, indent=4, sort_keys=True)) diff --git a/content/_code-samples/xrpl-py/simple-python-app.py b/content/_code-samples/xrpl-py/simple-python-app.py deleted file mode 100644 index cf3ac640ca..0000000000 --- a/content/_code-samples/xrpl-py/simple-python-app.py +++ /dev/null @@ -1,153 +0,0 @@ -import xrpl -from xrpl.core import keypairs -from xrpl.core.addresscodec.main import classic_address_to_xaddress -from xrpl.clients.json_rpc_client import JsonRpcClient -from xrpl.wallet import generate_faucet_wallet -from xrpl.models.requests.account_info import AccountInfo -from xrpl.wallet import Wallet -from xrpl.models.transactions.transaction import Transaction, TransactionType, Memo -from xrpl.models.transactions import AccountSet, Payment -from xrpl.transaction import ( - LastLedgerSequenceExpiredException, -) -from xrpl.transaction.main import ( - safe_sign_and_submit_transaction, - safe_sign_transaction, - submit_transaction_blob, - transaction_json_to_binary_codec_form, -) -from xrpl.transaction.reliable_submission import send_reliable_submission -from xrpl.account import get_next_valid_seq_number -import json - -# Define the network client -JSON_RPC_URL_TESTNET = "https://s.altnet.rippletest.net:51234/" -JSON_RPC_CLIENT_TESTNET = JsonRpcClient(JSON_RPC_URL_TESTNET) - - -JSON_RPC_URL_DEVNET = "https://s.devnet.rippletest.net:51234/" -JSON_RPC_CLIENT_DEVNET = JsonRpcClient(JSON_RPC_URL_DEVNET) - -# Create wallets using the testnet faucet: -# https://xrpl.org/xrp-testnet-faucet.html -TESTNET_WALLET = generate_faucet_wallet(JSON_RPC_CLIENT_TESTNET) -TESTNET_CLASSIC_ACCOUNT = TESTNET_WALLET.classic_address - -DEVNET_WALLET = generate_faucet_wallet(JSON_RPC_CLIENT_DEVNET) -DEVNET_CLASSIC_ACCOUNT = DEVNET_WALLET.classic_address - -# Define the receiver accounts -TESTNET_DESTINATION_WALLET = generate_faucet_wallet(JSON_RPC_CLIENT_TESTNET) -TESTNET_DESTINATION_ACCOUNT = TESTNET_DESTINATION_WALLET.classic_address - - -# Define variables to use for transactions -_ACCOUNT = "r9LqNeG6qHxjeUocjvVki2XR35weJ9mZgQ" -_AMOUNT = "20" -_FEE = "10" -_MEMO = "I sent this with xrpl-py!" -_SEQUENCE = 19048 -SET_FLAG = 8 - -# Secrets to use for signing transactions -_SECRET = "" -_SEED = "" -_SEED_HEX = "EACEB081770D8ADE216C85445DD6FB002C6B5A2930F2DECE006DA18150CB18F6" -_PASSPHRASE = "mytopsecretpassphrasethatwillneverbehacked" - - -# Create an XRP Ledger wallet from the -# testnet faucet and derive an -# x-address for the address -def create_wallet_from_faucet(): - TESTNET_WALLET = generate_faucet_wallet(JSON_RPC_CLIENT_TESTNET) - wallet_classic_address = TESTNET_WALLET.classic_address - xaddress = addresscodec.classic_address_to_xaddress( - wallet2_address, tag, True - ) - print("\nClassic address:\n\n", wallet_classic_address) - print("X-address:\n\n", xaddress) - -# Create an XRP Ledger wallet from -# a generated seed -def create_wallet_from_seed(): - seed = keypairs.generate_seed() - wallet_from_seed = xrpl.wallet.Wallet(seed) - print(wallet_from_seed) - -# Optionally generate private and public keys -# to manage your XRP Ledger account -def generate_keys(): - seed = keypairs.generate_seed() - public, private = keypairs.derive_keypair(seed) - CLASSIC_ACCOUNT = keypairs.derive_classic_address(public) - print(f"Here's the public key:\n", public) - print(f"Here's the private key:\n", private + "\nStore this in a secure place.") - -# Look up information about your account -def get_acct_info(): - client = JsonRpcClient(JSON_RPC_URL_TESTNET) - acct_info = AccountInfo( - account=wallet, - ledger_index="current", - queue=True, - strict=True, - ) - response = JSON_RPC_CLIENT_TESTNET.request(acct_info) - print("response.status: ", response.status) - print("response.result: ", response.result) - print("response.id: ", response.id) - print("response.type: ", response.type) - print("response.result.account_data.Balance", response.result.account_data.Balance) - - -# FUTURE Prepare tx -def prepare_tx_future(): - my_tx_future = Transaction.from_xrpl( - { - "TransactionType": "Payment", - "Amount": "50", - "Destination": "rNZz9HS8mmKqb3jGk28PjNMkkRXRzGdTda", - "Account": "rKQxjvLW67ZkMQdu9wmy73vhrbPcir21SV" - } - ) - TESTNET_WALLET.next_sequence_num = get_next_valid_seq_number(TESTNET_CLASSIC_ACCOUNT, JSON_RPC_CLIENT_TESTNET) - -# CURRENT Prepare tx -def prepare_tx_current(): - my_tx_current = Payment( - account=TESTNET_CLASSIC_ACCOUNT, - amount=_AMOUNT, - destination=TESTNET_DESTINATION_ACCOUNT, - memos=_MEMO, - transaction_type=TransactionType.PAYMENT, - ) - TESTNET_WALLET.next_sequence_num = get_next_valid_seq_number(TESTNET_CLASSIC_ACCOUNT, JSON_RPC_CLIENT_TESTNET) - -# Prepare the tx by formatting it into -# the shape expected by the XRP Ledger -# and signing it -def prepare_sign_submit_tx(): - TESTNET_WALLET.next_sequence_num = get_next_valid_seq_number(TESTNET_CLASSIC_ACCOUNT, JSON_RPC_CLIENT_TESTNET) - account_set = AccountSet( - account=TESTNET_CLASSIC_ACCOUNT, - fee=_FEE, - sequence=TESTNET_WALLET.next_sequence_num, - set_flag=SET_FLAG, - ) - response = safe_sign_and_submit_transaction(account_set, TESTNET_WALLET, JSON_RPC_CLIENT_TESTNET) - value = tx.to_dict()[] - signed_tx = Sign( - transaction=value, - seed=_SEED, - seed_hex=_SEED_HEX, - ) - print("Signed transaction: ", signed_tx) - payment_transaction = Payment.from_dict(value) - print("response.result.validated: ", response["validated"]) - print("response.result.meta: ", response.result["meta"]["TransactionResult"], "tesSUCCESS") - if response.result["meta"]["TransactionResult"] != "tesSUCCESS": - print("Transaction not yet validated") - else: - print("Validated!") - \ No newline at end of file diff --git a/content/tutorials/get-started/get-started-with-python-sdk.md b/content/tutorials/get-started/get-started-using-python.md similarity index 58% rename from content/tutorials/get-started/get-started-with-python-sdk.md rename to content/tutorials/get-started/get-started-using-python.md index a01996c30e..d306c5662f 100644 --- a/content/tutorials/get-started/get-started-with-python-sdk.md +++ b/content/tutorials/get-started/get-started-using-python.md @@ -1,5 +1,5 @@ --- -html: get-started-python.html +html: get-started-using-python.html funnel: Build doc_type: Tutorials category: Get Started @@ -10,36 +10,57 @@ cta_text: Build Apps # Get Started Using Python -This tutorial walks you through the basics of building an XRP Ledger-connected application using [xrpl-py](https://github.com/xpring-eng/xrpl-py), a [Python](https://www.python.org) library that makes it easy to integrate XRP Ledger functionality into your apps. +This tutorial walks you through the basics of building a very simple XRP Ledger-connected application using [`xrpl-py`](https://github.com/XRPLF/xrpl-py), a pure[Python](https://www.python.org) library that makes it easy to interact with the XRP Ledger using native Python models and methods. ## Learning goals In this tutorial, you'll learn: -* How to set up your environment for Python development. See [](python-env-setup.html). * The basic building blocks of XRP Ledger-based applications. -* How to generate keys. * How to connect to the XRP Ledger. -* How to submit a transaction, including preparing and signing it. +* How to generate a wallet on the [Testnet](xrp-testnet-faucet.html). +* How to use the `xrpl-py` library to look up information about an account on the XRP Ledger. * How to put these steps together to create a simple app that submits a transaction to the XRP Ledger Testnet. ## Requirements -For information about setting up your environment for Python development, see [](xref:python-env-setup.md). +The `xrpl-py` library supports [Python 3.7](https://www.python.org/downloads/) and later. + +### Requirements for contributing to the library + +If you want to contribute code to the library itself, install these dependencies to set up your development environment: + +* [`pyenv`](~https://github.com/pyenv/pyenv) +* [`poetry`](~https://python-poetry.org/docs/) +* [`pre-commit`](~https://pre-commit.com/) + + +For more detailed information about setting up your environment and contributing, see [CONTRIBUTING](https://github.com/XRPLF/xrpl-py/blob/master/CONTRIBUTING.md) in the project repo. + + +## Installation + + + +The [`xrpl-py` library](https://github.com/XRPLF/xrpl-py) is available on [PyPI](https://pypi.org/). Install with `pip`: + + +```py +pip3 install xrpl-py +``` ## Start building {% set n = cycler(* range(1,99)) %} -When you're working with the XRP Ledger, there are a few things you'll need to manage with your app or integration, whether you're adding XRP into your [wallet](xref: wallets.md), integrating with the [decentralized exchange](xref: decentralized-exchange.md), or [issuing and managing tokens](xref:issued-currencies.md). This tutorial walks you through the patterns common to all of these use cases and provides sample code for implementing them. +When you're working with the XRP Ledger, there are a few things you'll need to manage, whether you're adding XRP into your [wallet](wallets.html), integrating with the [decentralized exchange](decentralized-exchange.html), or [issuing tokens](issued-currencies.html). This tutorial walks you through basic patterns common to getting started with all of these use cases and provides sample code for implementing them. Here are the basic steps you'll need to cover for almost any XRP Ledger project: -1. [Generate keys.](#generate-keys) -2. [Connect to the XRP Ledger.](#connect) -3. [Query the XRP Ledger.](#query) -4. [Submit a transaction.](#submit-transaction) -5. [Verify results.](#verify-results) +1. [Connect to the XRP Ledger.](#connect) +1. [Generate a wallet.](#generate-wallet) +1. [Query the XRP Ledger.](#query) + ### {{n.next()}}. Generate keys @@ -84,19 +105,40 @@ def createWallet(): ### {{n.next()}}. Connect -To make queries that you can use in your app and submit transactions, you need to establish a connection to the XRP Ledger. There are a few ways to do this. The following sections describe each option in more detail. - -**Warning:** Never use publicly available servers to sign transactions. For more information about security and signing, see [](xref: set-up-secure-signing.md). - -**Caution:** Ripple provides the [Testnet and Devnet](parallel-networks.html) for testing purposes only, and sometimes resets the state of these test networks along with all balances. As a precaution, Ripple recommends **not** using the same addresses on Testnet/Devnet and Mainnet. - - -If you only want to explore the XRP Ledger, you can use the [Ledger Explorer](https://livenet.xrpl.org/) to see the Ledger progress in real-time and dig into specific accounts or transactions. +To make queries and submit transactions, you need to establish a connection to the XRP Ledger. To do this with `xrpl-py`, use the [`xrp.clients` module](https://xrpl-py.readthedocs.io/en/latest/source/xrpl.clients.html): ```py -# Define the URL of the server you want to use -JSON_RPC_URL = "http://s1.ripple.com:51234/" +from xrpl.clients.json_rpc_client import JsonRpcClient +JSON_RPC_URL = "https://s.altnet.rippletest.net:51234/" +client = JsonRpcClient(JSON_RPC_URL) +``` + + +### {{n.next()}}. Generate wallet + +You need [keys](https://xrpl.org/cryptographic-keys.html) to sign transactions that you submit to the XRP Ledger. + +For testing and development purposes, you can get keys (and XRP balances) from [XRP Faucets](https://xrpl.org/xrp-testnet-faucet.html). + +Otherwise, you should take care to store your keys and set up a [secure signing method](https://xrpl.org/set-up-secure-signing.html). + +To make it easy to create a wallet on the Testnet , `xrpl-py` provides the [`generate_faucet_wallet`](https://xrpl-py.readthedocs.io/en/latest/source/xrpl.wallet.html#xrpl.wallet.generate_faucet_wallet) method: + + +```py +from xrpl.wallet import generate_faucet_wallet +test_wallet = generate_faucet_wallet(client) +``` + +This method returns a [`Wallet` instance](https://xrpl-py.readthedocs.io/en/latest/source/xrpl.wallet.html#xrpl.wallet.Wallet) that you can use to sign and submit transactions: + + +```py +seed: shtrT9cYoQNGDs2uvAnK1g459SEXX +pub_key: 033911717E99D025CB3BBE8A10E92263F7F94216D7AE3078A7FF1264B1C46F94FB +priv_key: 00CC00FB2F861EC00CC2282475AB8BF9687A06635499737F329784658978FF87E8 +classic_address: rKm826nMCh25RK5zWmKgMp6EbGbkDoQN39 ``` ### {{n.next()}}. Query diff --git a/content/tutorials/get-started/python-env-setup.md b/content/tutorials/get-started/python-env-setup.md deleted file mode 100644 index 16dec48f6f..0000000000 --- a/content/tutorials/get-started/python-env-setup.md +++ /dev/null @@ -1,116 +0,0 @@ ---- -html: set-up-python-env.html -funnel: Build -doc_type: Tutorials -category: Get Started -subcategory: Get Started Using Python -#parent: get-started-python.html - field not used by the site yet -blurb: Set up your environment to start Python development. -cta_text: Build Apps ---- - -## Python Environment Setup - -Complete the steps in the following sections to prepare your environment for development. - -Here are the pre-requisites for `xrpl-py`: - -* [Python 3.7](https://www.python.org/downloads/) or later -* [`pyenv`](https://github.com/pyenv/pyenv) -* [`poetry`](https://python-poetry.org/docs/) -* [`pre-commit`](https://pre-commit.com/) - -### Install the library - -You can get `xrpl-py` through these methods: - -* Clone the repo: - - git clone git@github.com:xpring-eng/xrpl-py.git - -* Install with `pip`: - - pip3 install xrpl-py - -* Download from [Python Package Index (PyPI)](https://pypi.org/) - -### Set up Python environment - -To make it easy to manage your Python environment with `xrpl-py`, including switching between versions, install `pyenv` and follow these steps: - -* Install [`pyenv`](https://github.com/pyenv/pyenv): - - brew install pyenv - - For other installation options, see the [`pyenv` README](https://github.com/pyenv/pyenv#installation). - -* Use `pyenv` to install the optimized version for `xrpl-py` (currently 3.9.1): - - pyenv install 3.9.1 - -* Set the [global](https://github.com/pyenv/pyenv/blob/master/COMMANDS.md#pyenv-global) version of Python with `pyenv`: - - pyenv global 3.9.1 - -### Set up shell environment - -To enable autcompletion and other functionality from your shell, add `pyenv` to your environment. - -These steps assume that you're using a [Zsh](http://zsh.sourceforge.net/) shell. For other shells, see the [`pyenv` README](https://github.com/pyenv/pyenv#basic-github-checkout). - - -* Add `pyenv init` to your Zsh shell: - - echo -e 'if command -v pyenv 1>/dev/null 2>&1; then\n eval "$(pyenv init -)"\nfi' >> ~/.zshrc - -* Source or restart your terminal: - - . ~/.zshrc - -### Manage dependencies and virutal environment - -To simplify managing library dependencies and the virtual environment, `xrpl-py` uses [`poetry`](https://python-poetry.org/docs). - -* [Install `poetry`](https://python-poetry.org/docs/#osx-linux-bashonwindows-install-instructions): - - curl -sSL https://raw.githubusercontent.com/python-poetry/poetry/master/get-poetry.py | python - - poetry install - -### Set up `pre-commit` hooks - -To run linting and other checks, `xrpl-py` uses [`pre-commit`](https://pre-commit.com/). - -**Note:** You only need to install `pre-commit` if you want to contribute code to `xrpl-py` or generate the reference documentation locally. - - -* Install `pre-commit`: - - pip3 install pre-commit - pre-commit install - -### Generate reference docs - -You can see the SDK reference docs at <<>>. You can also generate them locally using `poetry` and `sphinx`: - -```bash -# Go to the docs/ folder -cd docs/ - -# Build the docs -poetry run sphinx-apidoc -o source/ ../xrpl -poetry run make html -``` - -To see the output: - -```bash -# Go to docs/_build/html/ -cd docs/_build/html/ - -# Open the index file to view it in a browser: -open docs/_build/html/index.html -``` - -## Next Steps - -Start building apps! See [](xref:get-started-with-python-sdk.md) for a tutorial that explains how to get started with `xrpl-py`. \ No newline at end of file diff --git a/dactyl-config.yml b/dactyl-config.yml index ad593eedf6..d02a44f60a 100644 --- a/dactyl-config.yml +++ b/dactyl-config.yml @@ -1580,11 +1580,7 @@ pages: targets: - ja - - md: tutorials/get-started/get-started-with-python-sdk.md - targets: - - en - - - md: tutorials/get-started/python-env-setup.md + - md: tutorials/get-started/get-started-using-python.md targets: - en From f972c23393fd9de54cf3fb15ec10f4c6478276af Mon Sep 17 00:00:00 2001 From: "Ryan G. Young" Date: Sat, 27 Mar 2021 17:11:34 -0700 Subject: [PATCH 08/18] finish revision, use code includes --- .../get-started/get-started-using-python.md | 275 ++++++++---------- 1 file changed, 125 insertions(+), 150 deletions(-) diff --git a/content/tutorials/get-started/get-started-using-python.md b/content/tutorials/get-started/get-started-using-python.md index d306c5662f..7bee41c54d 100644 --- a/content/tutorials/get-started/get-started-using-python.md +++ b/content/tutorials/get-started/get-started-using-python.md @@ -5,23 +5,26 @@ doc_type: Tutorials category: Get Started subcategory: Get Started Using Python blurb: Build a simple Python app that interacts with the XRP Ledger. -cta_text: Build Apps +cta_text: Build an XRP Ledger-connected app +filters: + - interactive_steps --- # Get Started Using Python -This tutorial walks you through the basics of building a very simple XRP Ledger-connected application using [`xrpl-py`](https://github.com/XRPLF/xrpl-py), a pure[Python](https://www.python.org) library that makes it easy to interact with the XRP Ledger using native Python models and methods. +This tutorial walks you through the basics of building a very simple XRP Ledger-connected application using [`xrpl-py`](https://github.com/XRPLF/xrpl-py), a pure [Python](https://www.python.org) library that makes it easy to interact with the XRP Ledger using native Python models and methods. +This tutorial is intended for beginners and should take no longer than 30 minutes to complete. ## Learning goals In this tutorial, you'll learn: * The basic building blocks of XRP Ledger-based applications. -* How to connect to the XRP Ledger. -* How to generate a wallet on the [Testnet](xrp-testnet-faucet.html). +* How to connect to the XRP Ledger using `xrpl-py`. +* How to generate a wallet on the [Testnet](xrp-testnet-faucet.html) using `xrpl-py`. * How to use the `xrpl-py` library to look up information about an account on the XRP Ledger. -* How to put these steps together to create a simple app that submits a transaction to the XRP Ledger Testnet. +* How to put these steps together to create a simple Python app. ## Requirements @@ -29,19 +32,12 @@ The `xrpl-py` library supports [Python 3.7](https://www.python.org/downloads/) a ### Requirements for contributing to the library -If you want to contribute code to the library itself, install these dependencies to set up your development environment: - -* [`pyenv`](~https://github.com/pyenv/pyenv) -* [`poetry`](~https://python-poetry.org/docs/) -* [`pre-commit`](~https://pre-commit.com/) - - -For more detailed information about setting up your environment and contributing, see [CONTRIBUTING](https://github.com/XRPLF/xrpl-py/blob/master/CONTRIBUTING.md) in the project repo. +If you want to contribute code to the library itself, see [CONTRIBUTING](https://github.com/XRPLF/xrpl-py/blob/master/CONTRIBUTING.md) in the project repo. ## Installation - + The [`xrpl-py` library](https://github.com/XRPLF/xrpl-py) is available on [PyPI](https://pypi.org/). Install with `pip`: @@ -62,183 +58,162 @@ Here are the basic steps you'll need to cover for almost any XRP Ledger project: 1. [Query the XRP Ledger.](#query) -### {{n.next()}}. Generate keys - - -You need [keys](https://xrpl.org/cryptographic-keys.html) to sign transactions that you submit to the XRP Ledger. - -For testing and development purposes, you can get keys (and XRP balances) from [XRP Faucets](https://xrpl.org/xrp-testnet-faucet.html). - -Otherwise, you should take care to store your keys and set up a [secure signing method](https://xrpl.org/set-up-secure-signing.html). - - - -*Generate keypairs (xrpl-py)* - -```py -# Generate private and public keys -# to manage your XRP Ledger account -def generateKeys(): - seed = keypairs.generate_seed() - public, private = keypairs.derive_keypair(seed) - CLASSIC_ACCOUNT = keypairs.derive_classic_address(public) - print("Here's the public key: ", public) - print("Here's the private key: ", private) -``` -*Generate wallet (xrpl-py)* - -```py -# Create an XRP Ledger wallet -# And create an x-address for the address -def createWallet(): - wallet = Wallet.generate_seed_and_wallet() - address = wallet.classic_address - xaddress = addresscodec.classic_address_to_xaddress( - classic_address, tag, True - ) - print("Classic address:", address) - print("X-address:", xaddress) -``` - - - - ### {{n.next()}}. Connect To make queries and submit transactions, you need to establish a connection to the XRP Ledger. To do this with `xrpl-py`, use the [`xrp.clients` module](https://xrpl-py.readthedocs.io/en/latest/source/xrpl.clients.html): ```py -from xrpl.clients.json_rpc_client import JsonRpcClient -JSON_RPC_URL = "https://s.altnet.rippletest.net:51234/" -client = JsonRpcClient(JSON_RPC_URL) +{{ include_code("_code-samples/xrpl-py/get-acct-info.py", start_with="# Define the network client", end_before="# Create a wallet using the testnet faucet:")}} ``` ### {{n.next()}}. Generate wallet -You need [keys](https://xrpl.org/cryptographic-keys.html) to sign transactions that you submit to the XRP Ledger. +To store value and execute transactions on the XRP Ledger, you need to create a wallet: a [set of keys](cryptographic-keys.html#key-components) and an [address](accounts.html#addresses) that's been [funded with enough XRP](accounts.html#creating-accounts) to meet the [account reserve](reserves.html#reserves). The address is the identifier of your account and you use the [private key](cryptographic-keys.html#private-key) to sign transactions that you submit to the XRP Ledger. -For testing and development purposes, you can get keys (and XRP balances) from [XRP Faucets](https://xrpl.org/xrp-testnet-faucet.html). -Otherwise, you should take care to store your keys and set up a [secure signing method](https://xrpl.org/set-up-secure-signing.html). +For testing and development purposes, you can use the [XRP Faucets](xrp-testnet-faucet.html) to generate keys and fund the account on the Testnet or Devnet. For production purposes, you should take care to store your keys and set up a [secure signing method](set-up-secure-signing.html). -To make it easy to create a wallet on the Testnet , `xrpl-py` provides the [`generate_faucet_wallet`](https://xrpl-py.readthedocs.io/en/latest/source/xrpl.wallet.html#xrpl.wallet.generate_faucet_wallet) method: + +To make it easy to create a wallet on the Testnet, `xrpl-py` provides the [`generate_faucet_wallet`](https://xrpl-py.readthedocs.io/en/latest/source/xrpl.wallet.html#xrpl.wallet.generate_faucet_wallet) method: ```py -from xrpl.wallet import generate_faucet_wallet -test_wallet = generate_faucet_wallet(client) +{{ include_code("_code-samples/xrpl-py/get-acct-info.py", start_with="# Create a wallet using the testnet faucet", end_before="# Create an account str from the wallet") }} ``` -This method returns a [`Wallet` instance](https://xrpl-py.readthedocs.io/en/latest/source/xrpl.wallet.html#xrpl.wallet.Wallet) that you can use to sign and submit transactions: +This method returns a [`Wallet` instance](https://xrpl-py.readthedocs.io/en/latest/source/xrpl.wallet.html#xrpl.wallet.Wallet): ```py -seed: shtrT9cYoQNGDs2uvAnK1g459SEXX -pub_key: 033911717E99D025CB3BBE8A10E92263F7F94216D7AE3078A7FF1264B1C46F94FB -priv_key: 00CC00FB2F861EC00CC2282475AB8BF9687A06635499737F329784658978FF87E8 -classic_address: rKm826nMCh25RK5zWmKgMp6EbGbkDoQN39 +print(test_wallet) + +# print output +seed: shrPSF6vV3v3yoND9J3NeKks6M3xd +pub_key: 022FA613294CD13FFEA759D0185007DBE763331910509EF8F1635B4F84FA08AEE3 +priv_key: 00D46D49A1A260C24964E6CFD5C85308ACE958E200C14B4DCA73AA5C87288C8F6C +classic_address: raaFKKmgf6CRZttTVABeTcsqzRQ51bNR6Q ``` +#### Using the wallet + +In this tutorial we only query details about the generated account from the XRP Ledger, but you can use the values in the `Wallet` instance to prepare, sign, and submit transactions with `xrpl-py`. + +##### Prepare + +To prepare the transaction: + +```py +from xrpl.models.transactions import Payment + +my_tx_payment = Payment( + account=test_wallet.classic_address, + amount="2200", # in drops: https://xrpl.org/basic-data-types.html#specifying-currency-amounts + destination="rPT1Sjq2YGrBMTttX4GZHjKu9dyfzbpAYe", + sequence=test_wallet.next_sequence_num, +) +``` + +##### Sign + +To sign the transaction: + +```py +from xrpl.transaction import send_reliable_submission + +my_tx_payment_signed = safe_sign_transaction(my_tx_payment,test_wallet) +``` +##### Send + +To send the transaction: + +```py +from xrpl.transaction import send_reliable_submission + +tx_response = send_reliable_submission(my_tx_payment, test_wallet, client) +``` + +##### Derive an X-address + +You can use `xrpl-py`'s [`xrpl.core.addresscodec`](https://xrpl-py.readthedocs.io/en/latest/source/xrpl.core.addresscodec.html) module to derive an [X-address](https://xrpaddress.info/) from the `Wallet.classic_address` field: + +```py +{{ include_code("_code-samples/xrpl-py/get-acct-info.py", start_with="# Derive an x-address from the classic address:", end_before="# Look up info about your account") }} +``` + +The X-address format [packs the address and destination tag](https://github.com/xrp-community/standards-drafts/issues/6) into one more user-friendly value. + ### {{n.next()}}. Query -Before you submit a transaction to the XRP Ledger, you should query it to check your account status and balances to make sure that the transaction will succeed. +You can query the XRP Ledger to get information about [a specific account](account-methods.html), [a specific transaction](tx.html), the state of a [current or a historical ledger](ledger-methods.html), and [the XRP Ledger's decentralized exhange](path-and-order-book-methods.html). You need to make these queries, among other reasons, to look up account info to follow best practices for [reliable transaction submission](reliable-transaction-submission.html). + +Here, we'll use `xrpl-py`'s [`xrpl.account`](https://xrpl-py.readthedocs.io/en/latest/source/xrpl.account.html) module to look up information about the [wallet we generated](#generate-wallet) in the previous step. ```py -# Look up information about your account -def getAcctInfo(): - client = JsonRpcClient(JSON_RPC_URL) - acct_info = AccountInfo( - account=address, - ledger_index="current", - queue=True, - strict=True, - ) - response = client.request(acct_info) - print("response.status: ", response.status) - print("response.result: ", response.result) - print("response.id: ", response.id) - print("response.type: ", response.type) +{{ include_code("_code-samples/xrpl-py/get-acct-info.py", start_with="# Look up info about your account") }} ``` -### {{n.next()}}. Submit transaction - -Submitting a transaction to the XRP inolves three distinct steps: - -* Preparing the transaction. -* Signing the transaction. -* Submitting the transaction to an XRP Ledger node. - -With `xrpl-py`, you can combine the these steps by using the `tx.to_dict` function and the `Sign` model. - - -```python - # Prepare the tx by formatting it into -# the shape expected by the XRP Ledger -# and signing it -def prepareSignSubmitTx(): - CLASSIC_ACCOUNT.next_sequence_num = get_next_valid_seq_number(CLASSIC_ACCOUNT, JSON_RPC_CLIENT) - tx = Transaction( - account=_ACCOUNT, - fee=_FEE, - sequence=CLASSIC_ACCOUNT.next_seuqnece_num + 10, - transaction_type=TransactionType. - ) - value = tx.to_dict()["payment_trannsaction"] - signed_tx = Sign( - transaction=value, - seed=_SEED, - seed_hex=_SEED_HEX, - ) - print("Signed transaction: ", signed_tx) - payment_transaction = Payment.from_dict(value) - response = send_reliable_submission( - payment_transaction, CLASSIC_ACCOUNT, JSON_RPC_URL - ) - print("response.result.validated: ", response["validated"]) - print("response.result.meta: ", response.result["meta"]["TransactionResult"], "tesSUCCESS") -``` - - -### {{n.next()}}. Verify results - -To ensure that your transaction has succeeded in a validated ledger, which means that the results are final, you can add simple logic to your submit function: - - -```python -if response.result["meta"]["TransactionResult"] != "tesSUCCESS": - print("Transaction not yet validated") -else: - print("Validated!") -``` - - - ### {{n.next()}}. Putting it all together -Using these building blocks, we can create a simple app that: +Using these building blocks, we can create a simple Python app that: -1. Generates a wallet. +1. Generates a wallet on the Testnet. 2. Connects to the XRP Ledger. -3. Looks up information about your account. -4. Sends XRP from one account to another. -5. Verifies the transaction in a validated ledger. +3. Looks up and prints information about the account you created. ```python -{% include '_code-samples/xrpl-py/simple-python-app.py' %} +{% include '_code-samples/xrpl-py/get-acct_info.py' %} +``` + +To run the app, you can copy and paste the code into an editor or IDE and run it from there. Or you could download the file from the [XRP Ledger Dev Portal repo](https://github.com/ripple/ripple-dev-portal/tree/master/content/_code-samples/xrpl-py) and run it locally: + + +```sh +git clone git@github.com:ripple/xrpl-dev-portal.git +cd path/to/xrpl-dev-portal/content/_code-samples/xrpl-py/get-acct-info.py +python3 get-acct-info.py +``` + +You should see output similar to this example: + +```sh +Classic address: + + rnQLnSEA1YFMABnCMrkMWFKxnqW6sQ8EWk +X-address: + + T7dRN2ktZGYSTyEPWa9SyDevrwS5yDca4m7xfXTGM3bqff8 +response.status: ResponseStatus.SUCCESS +{ + "account_data": { + "Account": "rnQLnSEA1YFMABnCMrkMWFKxnqW6sQ8EWk", + "Balance": "1000000000", + "Flags": 0, + "LedgerEntryType": "AccountRoot", + "OwnerCount": 0, + "PreviousTxnID": "5A5203AFF41503539D11ADC41BE4185761C5B78B7ED382E6D001ADE83A59B8DC", + "PreviousTxnLgrSeq": 16126889, + "Sequence": 16126889, + "index": "CAD0F7EF3AB91DA7A952E09D4AF62C943FC1EEE41BE926D632DDB34CAA2E0E8F" + }, + "ledger_current_index": 16126890, + "queue_data": { + "txn_count": 0 + }, + "validated": false +} ``` -## Next steps +## Keep on building -<> +Use `xrpl-py` to: -Try using `xrpl-py` to: - -* Set Account Flags -* Issue a token on the Devnet -* Set up an escrow +* [Send XRP](send-xrp.html). +* [Set up secure signing](set-up-secure-signing.html) for your account. +* Set an [account flag](accountset.html#accountset-flags). +* [Create an escrow](use-escrows.html). From ba10bd2e10ae9c4858cc3d422887534a7c329352 Mon Sep 17 00:00:00 2001 From: "Ryan G. Young" Date: Sat, 27 Mar 2021 17:23:03 -0700 Subject: [PATCH 09/18] rebase and add include_code to page --- content/tutorials/get-started/get-started-using-python.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/content/tutorials/get-started/get-started-using-python.md b/content/tutorials/get-started/get-started-using-python.md index 7bee41c54d..ae308add55 100644 --- a/content/tutorials/get-started/get-started-using-python.md +++ b/content/tutorials/get-started/get-started-using-python.md @@ -8,6 +8,7 @@ blurb: Build a simple Python app that interacts with the XRP Ledger. cta_text: Build an XRP Ledger-connected app filters: - interactive_steps + - include_code --- # Get Started Using Python @@ -64,7 +65,7 @@ To make queries and submit transactions, you need to establish a connection to t ```py -{{ include_code("_code-samples/xrpl-py/get-acct-info.py", start_with="# Define the network client", end_before="# Create a wallet using the testnet faucet:")}} +{{ include_code("_code-samples/xrpl-py/get-acct-info.py", start_with="# Define the network client", end_before="# Create a wallet using the testnet faucet:", language="py") }} ``` @@ -80,7 +81,7 @@ To make it easy to create a wallet on the Testnet, `xrpl-py` provides the [`gene ```py -{{ include_code("_code-samples/xrpl-py/get-acct-info.py", start_with="# Create a wallet using the testnet faucet", end_before="# Create an account str from the wallet") }} +{{ include_code("_code-samples/xrpl-py/get-acct-info.py", start_with="# Create a wallet using the testnet faucet", end_before="# Create an account str from the wallet", language="py") }} ``` This method returns a [`Wallet` instance](https://xrpl-py.readthedocs.io/en/latest/source/xrpl.wallet.html#xrpl.wallet.Wallet): From 17add7cab110a9a2cdd121ec8365c71c83bb4137 Mon Sep 17 00:00:00 2001 From: "Ryan G. Young" Date: Mon, 29 Mar 2021 11:11:58 -0700 Subject: [PATCH 10/18] fix include_code syntax errors --- .../get-started/get-started-using-python.md | 21 +++++++------------ 1 file changed, 8 insertions(+), 13 deletions(-) diff --git a/content/tutorials/get-started/get-started-using-python.md b/content/tutorials/get-started/get-started-using-python.md index ae308add55..44e7212adc 100644 --- a/content/tutorials/get-started/get-started-using-python.md +++ b/content/tutorials/get-started/get-started-using-python.md @@ -3,7 +3,6 @@ html: get-started-using-python.html funnel: Build doc_type: Tutorials category: Get Started -subcategory: Get Started Using Python blurb: Build a simple Python app that interacts with the XRP Ledger. cta_text: Build an XRP Ledger-connected app filters: @@ -64,9 +63,7 @@ Here are the basic steps you'll need to cover for almost any XRP Ledger project: To make queries and submit transactions, you need to establish a connection to the XRP Ledger. To do this with `xrpl-py`, use the [`xrp.clients` module](https://xrpl-py.readthedocs.io/en/latest/source/xrpl.clients.html): -```py {{ include_code("_code-samples/xrpl-py/get-acct-info.py", start_with="# Define the network client", end_before="# Create a wallet using the testnet faucet:", language="py") }} -``` ### {{n.next()}}. Generate wallet @@ -80,9 +77,9 @@ For testing and development purposes, you can use the [XRP Faucets](xrp-testnet- To make it easy to create a wallet on the Testnet, `xrpl-py` provides the [`generate_faucet_wallet`](https://xrpl-py.readthedocs.io/en/latest/source/xrpl.wallet.html#xrpl.wallet.generate_faucet_wallet) method: -```py -{{ include_code("_code-samples/xrpl-py/get-acct-info.py", start_with="# Create a wallet using the testnet faucet", end_before="# Create an account str from the wallet", language="py") }} -``` + +{{ include_code("_code-samples/xrpl-py/get-acct-info.py", start_with="# Create a wallet using the testnet faucet:", end_before="# Create an account str from the wallet", language="py") }} + This method returns a [`Wallet` instance](https://xrpl-py.readthedocs.io/en/latest/source/xrpl.wallet.html#xrpl.wallet.Wallet): @@ -139,9 +136,8 @@ tx_response = send_reliable_submission(my_tx_payment, test_wallet, client) You can use `xrpl-py`'s [`xrpl.core.addresscodec`](https://xrpl-py.readthedocs.io/en/latest/source/xrpl.core.addresscodec.html) module to derive an [X-address](https://xrpaddress.info/) from the `Wallet.classic_address` field: -```py -{{ include_code("_code-samples/xrpl-py/get-acct-info.py", start_with="# Derive an x-address from the classic address:", end_before="# Look up info about your account") }} -``` + +{{ include_code("_code-samples/xrpl-py/get-acct-info.py", start_with="# Derive an x-address from the classic address:", end_before="# Look up info about your account", language="py") }} The X-address format [packs the address and destination tag](https://github.com/xrp-community/standards-drafts/issues/6) into one more user-friendly value. @@ -152,9 +148,8 @@ You can query the XRP Ledger to get information about [a specific account](accou Here, we'll use `xrpl-py`'s [`xrpl.account`](https://xrpl-py.readthedocs.io/en/latest/source/xrpl.account.html) module to look up information about the [wallet we generated](#generate-wallet) in the previous step. -```py -{{ include_code("_code-samples/xrpl-py/get-acct-info.py", start_with="# Look up info about your account") }} -``` +{{ include_code("_code-samples/xrpl-py/get-acct-info.py", start_with="# Look up info about your account", language="py") }} + ### {{n.next()}}. Putting it all together @@ -167,7 +162,7 @@ Using these building blocks, we can create a simple Python app that: ```python -{% include '_code-samples/xrpl-py/get-acct_info.py' %} +{% include '_code-samples/xrpl-py/get-acct-info.py' %} ``` To run the app, you can copy and paste the code into an editor or IDE and run it from there. Or you could download the file from the [XRP Ledger Dev Portal repo](https://github.com/ripple/ripple-dev-portal/tree/master/content/_code-samples/xrpl-py) and run it locally: From 5b0fb27aac80a10529ac1a8fde71375edb397c95 Mon Sep 17 00:00:00 2001 From: "Ryan G. Young" Date: Tue, 30 Mar 2021 15:07:36 -0700 Subject: [PATCH 11/18] revise per Rome, Mayuhka feedback --- .../_code-samples/xrpl-py/get-acct-info.py | 2 +- .../get-started/get-started-using-python.md | 55 +++++++++++++------ dactyl-config.yml | 1 + 3 files changed, 41 insertions(+), 17 deletions(-) diff --git a/content/_code-samples/xrpl-py/get-acct-info.py b/content/_code-samples/xrpl-py/get-acct-info.py index e07c30883c..148f449951 100644 --- a/content/_code-samples/xrpl-py/get-acct-info.py +++ b/content/_code-samples/xrpl-py/get-acct-info.py @@ -15,7 +15,7 @@ test_account = test_wallet.classic_address # Derive an x-address from the classic address: # https://xrpaddress.info/ from xrpl.core import addresscodec -test_xaddress = addresscodec.classic_address_to_xaddress(test_account, tag=0, is_test_network=True) +test_xaddress = addresscodec.classic_address_to_xaddress(test_account, tag=12345, is_test_network=True) print("\nClassic address:\n\n", test_account) print("X-address:\n\n", test_xaddress) diff --git a/content/tutorials/get-started/get-started-using-python.md b/content/tutorials/get-started/get-started-using-python.md index 44e7212adc..22113ffdcf 100644 --- a/content/tutorials/get-started/get-started-using-python.md +++ b/content/tutorials/get-started/get-started-using-python.md @@ -30,10 +30,6 @@ In this tutorial, you'll learn: The `xrpl-py` library supports [Python 3.7](https://www.python.org/downloads/) and later. -### Requirements for contributing to the library - -If you want to contribute code to the library itself, see [CONTRIBUTING](https://github.com/XRPLF/xrpl-py/blob/master/CONTRIBUTING.md) in the project repo. - ## Installation @@ -53,18 +49,36 @@ When you're working with the XRP Ledger, there are a few things you'll need to m Here are the basic steps you'll need to cover for almost any XRP Ledger project: -1. [Connect to the XRP Ledger.](#connect) -1. [Generate a wallet.](#generate-wallet) -1. [Query the XRP Ledger.](#query) +1. [Connect to the XRP Ledger.](#1-connect-to-the-xrp-ledger) +1. [Generate a wallet.](#2-generate-wallet) +1. [Query the XRP Ledger.](#3-query-the-xrp-ledger) -### {{n.next()}}. Connect +### {{n.next()}}. Connect to the XRP Ledger To make queries and submit transactions, you need to establish a connection to the XRP Ledger. To do this with `xrpl-py`, use the [`xrp.clients` module](https://xrpl-py.readthedocs.io/en/latest/source/xrpl.clients.html): {{ include_code("_code-samples/xrpl-py/get-acct-info.py", start_with="# Define the network client", end_before="# Create a wallet using the testnet faucet:", language="py") }} +#### Connect to the production XRP Ledger + +The sample code in the previous section shows you how to connect to the Testnet, which is one of the available [parallel networks](parallel-networks.html). When you're ready to integrate with the production XRP Ledger, you'll need to connect to the Mainnet. You can do that in two ways: + +* By [installing the core server](install-rippled.html) (`rippled`) and running a node yourself (the core server connects to the Mainnet by default and you can [change the configuration to use an altnet](connect-your-rippled-to-the-xrp-test-net.html) ). [There are good reasons to run your own core server](the-rippled-server.html#reasons-to-run-your-own-server). If you run your own server, you can coconnect to it like so: + + from xrpl.clients import JsonRpcClient + JSON_RPC_URL = "http://localhost:5005/" + client = JsonRpcClient(JSON_RPC_URL) + + See the example [core server config file](https://github.com/ripple/rippled/blob/c0a0b79d2d483b318ce1d82e526bd53df83a4a2c/cfg/rippled-example.cfg#L1562) for more information about default values. + +* By using one of the [available public servers](get-started-with-the-rippled-api.html#public-servers): + + from xrpl.clients import JsonRpcClient + JSON_RPC_URL = "https://s2.ripple.com:51234/" + client = JsonRpcClient(JSON_RPC_URL) + ### {{n.next()}}. Generate wallet @@ -88,9 +102,8 @@ This method returns a [`Wallet` instance](https://xrpl-py.readthedocs.io/en/late print(test_wallet) # print output -seed: shrPSF6vV3v3yoND9J3NeKks6M3xd -pub_key: 022FA613294CD13FFEA759D0185007DBE763331910509EF8F1635B4F84FA08AEE3 -priv_key: 00D46D49A1A260C24964E6CFD5C85308ACE958E200C14B4DCA73AA5C87288C8F6C +public_key:: 022FA613294CD13FFEA759D0185007DBE763331910509EF8F1635B4F84FA08AEE3 +private_key:: -HIDDEN- classic_address: raaFKKmgf6CRZttTVABeTcsqzRQ51bNR6Q ``` @@ -104,10 +117,11 @@ To prepare the transaction: ```py from xrpl.models.transactions import Payment +from xrpl.utils import xrp_to_drops my_tx_payment = Payment( account=test_wallet.classic_address, - amount="2200", # in drops: https://xrpl.org/basic-data-types.html#specifying-currency-amounts + amount=xrp_to_drops(22), destination="rPT1Sjq2YGrBMTttX4GZHjKu9dyfzbpAYe", sequence=test_wallet.next_sequence_num, ) @@ -139,13 +153,13 @@ You can use `xrpl-py`'s [`xrpl.core.addresscodec`](https://xrpl-py.readthedocs.i {{ include_code("_code-samples/xrpl-py/get-acct-info.py", start_with="# Derive an x-address from the classic address:", end_before="# Look up info about your account", language="py") }} -The X-address format [packs the address and destination tag](https://github.com/xrp-community/standards-drafts/issues/6) into one more user-friendly value. +The X-address format [packs the address and destination tag](https://github.com/xrp-community/standards-drafts/issues/6) into a more user-friendly value. -### {{n.next()}}. Query +### {{n.next()}}. Query the XRP Ledger You can query the XRP Ledger to get information about [a specific account](account-methods.html), [a specific transaction](tx.html), the state of a [current or a historical ledger](ledger-methods.html), and [the XRP Ledger's decentralized exhange](path-and-order-book-methods.html). You need to make these queries, among other reasons, to look up account info to follow best practices for [reliable transaction submission](reliable-transaction-submission.html). -Here, we'll use `xrpl-py`'s [`xrpl.account`](https://xrpl-py.readthedocs.io/en/latest/source/xrpl.account.html) module to look up information about the [wallet we generated](#generate-wallet) in the previous step. +Here, we'll use `xrpl-py`'s [`xrpl.account`](https://xrpl-py.readthedocs.io/en/latest/source/xrpl.account.html) module to look up information about the [wallet we generated](#2-generate-wallet) in the previous step. {{ include_code("_code-samples/xrpl-py/get-acct-info.py", start_with="# Look up info about your account", language="py") }} @@ -204,6 +218,16 @@ response.status: ResponseStatus.SUCCESS } ``` +#### Interpreting the response + +The response fields that you want to inspect in most cases are: + +* `account_data.Sequence` — This is the sequence number of the next valid transaction for the account. You need to specify the sequence number when you prepare transactions. With `xrpl-py`, you can use the [`get_next_valid_seq_number`](https://xrpl-py.readthedocs.io/en/latest/source/xrpl.account.html#xrpl.account.get_next_valid_seq_number) to get this automatically from the XRP Ledger. See an example of this usage in the project [README](https://github.com/XRPLF/xrpl-py#serialize-and-sign-transactions). + +* `account_data.Balance` — This is the account's XRP balance, [in drops](basic-data-types.html#specifying-currency-amounts). You can use this to confirm that you have enough XRP to send (if you're making a payment) and to meet the [current transaction cost](transaction-cost.html#current-transaction-cost) for a given transaction. + +For a detailed description of every response field, see [account_info](account_info.html#response-format). + ## Keep on building @@ -211,5 +235,4 @@ Use `xrpl-py` to: * [Send XRP](send-xrp.html). * [Set up secure signing](set-up-secure-signing.html) for your account. -* Set an [account flag](accountset.html#accountset-flags). * [Create an escrow](use-escrows.html). diff --git a/dactyl-config.yml b/dactyl-config.yml index d02a44f60a..cac243030b 100644 --- a/dactyl-config.yml +++ b/dactyl-config.yml @@ -1583,6 +1583,7 @@ pages: - md: tutorials/get-started/get-started-using-python.md targets: - en + - ja - md: tutorials/get-started/get-started-with-the-rippled-api.md html: get-started-with-the-rippled-api.html From df3a83d7142af8e2fff09a4d9b47859d795b0ab3 Mon Sep 17 00:00:00 2001 From: "Ryan G. Young" Date: Tue, 30 Mar 2021 15:15:30 -0700 Subject: [PATCH 12/18] add validated explanation --- content/tutorials/get-started/get-started-using-python.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/content/tutorials/get-started/get-started-using-python.md b/content/tutorials/get-started/get-started-using-python.md index 22113ffdcf..1689a9cb73 100644 --- a/content/tutorials/get-started/get-started-using-python.md +++ b/content/tutorials/get-started/get-started-using-python.md @@ -224,7 +224,9 @@ The response fields that you want to inspect in most cases are: * `account_data.Sequence` — This is the sequence number of the next valid transaction for the account. You need to specify the sequence number when you prepare transactions. With `xrpl-py`, you can use the [`get_next_valid_seq_number`](https://xrpl-py.readthedocs.io/en/latest/source/xrpl.account.html#xrpl.account.get_next_valid_seq_number) to get this automatically from the XRP Ledger. See an example of this usage in the project [README](https://github.com/XRPLF/xrpl-py#serialize-and-sign-transactions). -* `account_data.Balance` — This is the account's XRP balance, [in drops](basic-data-types.html#specifying-currency-amounts). You can use this to confirm that you have enough XRP to send (if you're making a payment) and to meet the [current transaction cost](transaction-cost.html#current-transaction-cost) for a given transaction. +* `account_data.Balance` — This is the account's XRP balance, [in drops](basic-data-types.html#specifying-currency-amounts). You can use this to confirm that you have enough XRP to send (if you're making a payment) and to meet the [current transaction cost](transaction-cost.html#current-transaction-cost) for a given transaction. + +* `validated` — Indicates whether the returned data is from a [validated ledger](ledgers.html#open-closed-and-validated-ledgers). When sending transactions, it's important to ensure that the results are in a [final](finality-of-results.html) state in a validated ledger before further processing the transaction. For more information about best practices for transaction processing, see [Reliable Transaction Submission](reliable-transaction-submission.html). For a detailed description of every response field, see [account_info](account_info.html#response-format). From 57b9081e4b40d3c64ec3ac4900abb341639020cb Mon Sep 17 00:00:00 2001 From: "Ryan G. Young" Date: Wed, 31 Mar 2021 10:37:59 -0700 Subject: [PATCH 13/18] change current to validated for ledger --- content/_code-samples/xrpl-py/get-acct-info.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/_code-samples/xrpl-py/get-acct-info.py b/content/_code-samples/xrpl-py/get-acct-info.py index 148f449951..1c5e031213 100644 --- a/content/_code-samples/xrpl-py/get-acct-info.py +++ b/content/_code-samples/xrpl-py/get-acct-info.py @@ -24,7 +24,7 @@ print("X-address:\n\n", test_xaddress) from xrpl.models.requests.account_info import AccountInfo acct_info = AccountInfo( account=test_account, - ledger_index="current", + ledger_index="validated", queue=True, strict=True, ) From bd7aa7cf86f4d1b85fc3b7545108657a41085b05 Mon Sep 17 00:00:00 2001 From: "Ryan G. Young" Date: Wed, 31 Mar 2021 13:07:26 -0700 Subject: [PATCH 14/18] remove escrow link --- content/_code-samples/xrpl-py/get-acct-info.py | 2 +- content/tutorials/get-started/get-started-using-python.md | 8 ++++++-- 2 files changed, 7 insertions(+), 3 deletions(-) diff --git a/content/_code-samples/xrpl-py/get-acct-info.py b/content/_code-samples/xrpl-py/get-acct-info.py index 1c5e031213..148f449951 100644 --- a/content/_code-samples/xrpl-py/get-acct-info.py +++ b/content/_code-samples/xrpl-py/get-acct-info.py @@ -24,7 +24,7 @@ print("X-address:\n\n", test_xaddress) from xrpl.models.requests.account_info import AccountInfo acct_info = AccountInfo( account=test_account, - ledger_index="validated", + ledger_index="current", queue=True, strict=True, ) diff --git a/content/tutorials/get-started/get-started-using-python.md b/content/tutorials/get-started/get-started-using-python.md index 1689a9cb73..3ad44bd07f 100644 --- a/content/tutorials/get-started/get-started-using-python.md +++ b/content/tutorials/get-started/get-started-using-python.md @@ -233,8 +233,12 @@ For a detailed description of every response field, see [account_info](account_i ## Keep on building -Use `xrpl-py` to: +Now that you know how to use `xrpl-py` to connect to the XRP Ledger, generate a wallet, and look up information about an account, you can also use `xrpl-py` to: * [Send XRP](send-xrp.html). * [Set up secure signing](set-up-secure-signing.html) for your account. -* [Create an escrow](use-escrows.html). + + + + + From e5c7dfe56ded968bc9b133d5592b47251abaf54c Mon Sep 17 00:00:00 2001 From: mDuo13 Date: Wed, 31 Mar 2021 12:38:53 -0700 Subject: [PATCH 15/18] xrpl-py-tutorial: Fix account_info invalid params, add faucet debug --- content/_code-samples/xrpl-py/get-acct-info.py | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/content/_code-samples/xrpl-py/get-acct-info.py b/content/_code-samples/xrpl-py/get-acct-info.py index 148f449951..e7a8d2008e 100644 --- a/content/_code-samples/xrpl-py/get-acct-info.py +++ b/content/_code-samples/xrpl-py/get-acct-info.py @@ -4,10 +4,10 @@ JSON_RPC_URL = "https://s.altnet.rippletest.net:51234/" client = JsonRpcClient(JSON_RPC_URL) -# Create a wallet using the testnet faucet: +# Create a wallet using the testnet faucet: # https://xrpl.org/xrp-testnet-faucet.html from xrpl.wallet import generate_faucet_wallet -test_wallet = generate_faucet_wallet(client) +test_wallet = generate_faucet_wallet(client, debug=True) # Create an account str from the wallet test_account = test_wallet.classic_address @@ -24,8 +24,7 @@ print("X-address:\n\n", test_xaddress) from xrpl.models.requests.account_info import AccountInfo acct_info = AccountInfo( account=test_account, - ledger_index="current", - queue=True, + ledger_index="validated", strict=True, ) response = client.request(acct_info) From 9fe380ab163a43066f5ebad79f83b990bfaac8ea Mon Sep 17 00:00:00 2001 From: "Ryan G. Young" Date: Wed, 31 Mar 2021 13:45:26 -0700 Subject: [PATCH 16/18] updatee prepare payment section --- .../_code-samples/xrpl-py/prepare-payment.py | 50 +++++++++++++++++++ .../get-started/get-started-using-python.md | 27 +++------- 2 files changed, 56 insertions(+), 21 deletions(-) create mode 100644 content/_code-samples/xrpl-py/prepare-payment.py diff --git a/content/_code-samples/xrpl-py/prepare-payment.py b/content/_code-samples/xrpl-py/prepare-payment.py new file mode 100644 index 0000000000..8d04fb1ce7 --- /dev/null +++ b/content/_code-samples/xrpl-py/prepare-payment.py @@ -0,0 +1,50 @@ + +# Define the network client +from xrpl.clients import JsonRpcClient +JSON_RPC_URL = "https://s.altnet.rippletest.net:51234/" +client = JsonRpcClient(JSON_RPC_URL) + + +# Create a wallet using the testnet faucet: +# https://xrpl.org/xrp-testnet-faucet.html +from xrpl.wallet import generate_faucet_wallet +test_wallet = generate_faucet_wallet(client, debug=True) + +# Create an account str from the wallet +test_account = test_wallet.classic_address + +# Derive an x-address from the classic address: +# https://xrpaddress.info/ +from xrpl.core import addresscodec +test_xaddress = addresscodec.classic_address_to_xaddress(test_account, tag=12345, is_test_network=True) +print("\nClassic address:\n\n", test_account) +print("X-address:\n\n", test_xaddress) + +# Prepare payment +from xrpl.models.transactions import Payment +from xrpl.utils import xrp_to_drops +my_tx_payment = Payment( + account=test_account, + amount=xrp_to_drops(22), + destination="rPT1Sjq2YGrBMTttX4GZHjKu9dyfzbpAYe", + sequence=test_wallet.sequence, +) + +# print prepared payment +print(my_tx_payment) + +# Sign the transaction +from xrpl.transaction import safe_sign_and_autofill_transaction + +my_tx_payment_signed = safe_sign_and_autofill_transaction(my_tx_payment,test_wallet, client) + +# Print signed tx +print("Signed tx:", my_tx_payment_signed) + +# Submit and send the transaction +from xrpl.transaction import send_reliable_submission + +tx_response = send_reliable_submission(my_tx_payment_signed, client) + +# Print tx response +print("Tx response:", tx_response) \ No newline at end of file diff --git a/content/tutorials/get-started/get-started-using-python.md b/content/tutorials/get-started/get-started-using-python.md index 3ad44bd07f..8664361f17 100644 --- a/content/tutorials/get-started/get-started-using-python.md +++ b/content/tutorials/get-started/get-started-using-python.md @@ -33,9 +33,7 @@ The `xrpl-py` library supports [Python 3.7](https://www.python.org/downloads/) a ## Installation - - -The [`xrpl-py` library](https://github.com/XRPLF/xrpl-py) is available on [PyPI](https://pypi.org/). Install with `pip`: +The [`xrpl-py` library](https://github.com/XRPLF/xrpl-py) is available on [PyPI](https://pypi.org/project/xrpl-py/). Install with `pip`: ```py @@ -115,36 +113,23 @@ In this tutorial we only query details about the generated account from the XRP To prepare the transaction: -```py -from xrpl.models.transactions import Payment -from xrpl.utils import xrp_to_drops +{{ include_code("_code-samples/xrpl-py/prepare-payment.py", start_with="# Prepare payment", end_before="# print prepared payment", language="py") }} + -my_tx_payment = Payment( - account=test_wallet.classic_address, - amount=xrp_to_drops(22), - destination="rPT1Sjq2YGrBMTttX4GZHjKu9dyfzbpAYe", - sequence=test_wallet.next_sequence_num, -) -``` ##### Sign To sign the transaction: -```py -from xrpl.transaction import send_reliable_submission +{{ include_code("_code-samples/xrpl-py/prepare-payment.py", start_with="# Sign the transaction", end_before="# Print signed tx", language="py") }} + -my_tx_payment_signed = safe_sign_transaction(my_tx_payment,test_wallet) -``` ##### Send To send the transaction: -```py -from xrpl.transaction import send_reliable_submission +{{ include_code("_code-samples/xrpl-py/prepare-payment.py", start_with="# Submit and send the transaction", end_before="# Print tx response", language="py") }} -tx_response = send_reliable_submission(my_tx_payment, test_wallet, client) -``` ##### Derive an X-address From a8b194c8a92747e88ba14eb93830cac3302b8cfc Mon Sep 17 00:00:00 2001 From: "Ryan G. Young" Date: Wed, 31 Mar 2021 13:52:37 -0700 Subject: [PATCH 17/18] simplify git clone and cd path --- content/tutorials/get-started/get-started-using-python.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/tutorials/get-started/get-started-using-python.md b/content/tutorials/get-started/get-started-using-python.md index 8664361f17..48d9a9e8ce 100644 --- a/content/tutorials/get-started/get-started-using-python.md +++ b/content/tutorials/get-started/get-started-using-python.md @@ -169,7 +169,7 @@ To run the app, you can copy and paste the code into an editor or IDE and run it ```sh git clone git@github.com:ripple/xrpl-dev-portal.git -cd path/to/xrpl-dev-portal/content/_code-samples/xrpl-py/get-acct-info.py +cd xrpl-dev-portal/content/_code-samples/xrpl-py/get-acct-info.py python3 get-acct-info.py ``` From c7dc998adfe390a3248371ba0be208f7286582cc Mon Sep 17 00:00:00 2001 From: mDuo13 Date: Wed, 31 Mar 2021 18:00:59 -0700 Subject: [PATCH 18/18] xrpl-py tutorial: fix links in JA target --- .../get-started/get-started-using-python.md | 50 ++++++++++--------- dactyl-config.yml | 10 ++++ 2 files changed, 36 insertions(+), 24 deletions(-) diff --git a/content/tutorials/get-started/get-started-using-python.md b/content/tutorials/get-started/get-started-using-python.md index 48d9a9e8ce..f739f4c167 100644 --- a/content/tutorials/get-started/get-started-using-python.md +++ b/content/tutorials/get-started/get-started-using-python.md @@ -4,7 +4,7 @@ funnel: Build doc_type: Tutorials category: Get Started blurb: Build a simple Python app that interacts with the XRP Ledger. -cta_text: Build an XRP Ledger-connected app +cta_text: Build an XRP Ledger-connected app filters: - interactive_steps - include_code @@ -14,17 +14,17 @@ filters: This tutorial walks you through the basics of building a very simple XRP Ledger-connected application using [`xrpl-py`](https://github.com/XRPLF/xrpl-py), a pure [Python](https://www.python.org) library that makes it easy to interact with the XRP Ledger using native Python models and methods. -This tutorial is intended for beginners and should take no longer than 30 minutes to complete. +This tutorial is intended for beginners and should take no longer than 30 minutes to complete. ## Learning goals -In this tutorial, you'll learn: +In this tutorial, you'll learn: * The basic building blocks of XRP Ledger-based applications. * How to connect to the XRP Ledger using `xrpl-py`. * How to generate a wallet on the [Testnet](xrp-testnet-faucet.html) using `xrpl-py`. -* How to use the `xrpl-py` library to look up information about an account on the XRP Ledger. -* How to put these steps together to create a simple Python app. +* How to use the `xrpl-py` library to look up information about an account on the XRP Ledger. +* How to put these steps together to create a simple Python app. ## Requirements @@ -43,7 +43,7 @@ pip3 install xrpl-py ## Start building {% set n = cycler(* range(1,99)) %} -When you're working with the XRP Ledger, there are a few things you'll need to manage, whether you're adding XRP into your [wallet](wallets.html), integrating with the [decentralized exchange](decentralized-exchange.html), or [issuing tokens](issued-currencies.html). This tutorial walks you through basic patterns common to getting started with all of these use cases and provides sample code for implementing them. +When you're working with the XRP Ledger, there are a few things you'll need to manage, whether you're adding XRP into your [wallet](wallets.html), integrating with the [decentralized exchange](decentralized-exchange.html), or [issuing tokens](issued-currencies.html). This tutorial walks you through basic patterns common to getting started with all of these use cases and provides sample code for implementing them. Here are the basic steps you'll need to cover for almost any XRP Ledger project: @@ -61,29 +61,29 @@ To make queries and submit transactions, you need to establish a connection to t #### Connect to the production XRP Ledger -The sample code in the previous section shows you how to connect to the Testnet, which is one of the available [parallel networks](parallel-networks.html). When you're ready to integrate with the production XRP Ledger, you'll need to connect to the Mainnet. You can do that in two ways: +The sample code in the previous section shows you how to connect to the Testnet, which is one of the available [parallel networks](parallel-networks.html). When you're ready to integrate with the production XRP Ledger, you'll need to connect to the Mainnet. You can do that in two ways: * By [installing the core server](install-rippled.html) (`rippled`) and running a node yourself (the core server connects to the Mainnet by default and you can [change the configuration to use an altnet](connect-your-rippled-to-the-xrp-test-net.html) ). [There are good reasons to run your own core server](the-rippled-server.html#reasons-to-run-your-own-server). If you run your own server, you can coconnect to it like so: - + from xrpl.clients import JsonRpcClient JSON_RPC_URL = "http://localhost:5005/" client = JsonRpcClient(JSON_RPC_URL) - See the example [core server config file](https://github.com/ripple/rippled/blob/c0a0b79d2d483b318ce1d82e526bd53df83a4a2c/cfg/rippled-example.cfg#L1562) for more information about default values. + See the example [core server config file](https://github.com/ripple/rippled/blob/c0a0b79d2d483b318ce1d82e526bd53df83a4a2c/cfg/rippled-example.cfg#L1562) for more information about default values. * By using one of the [available public servers](get-started-with-the-rippled-api.html#public-servers): from xrpl.clients import JsonRpcClient JSON_RPC_URL = "https://s2.ripple.com:51234/" - client = JsonRpcClient(JSON_RPC_URL) + client = JsonRpcClient(JSON_RPC_URL) ### {{n.next()}}. Generate wallet -To store value and execute transactions on the XRP Ledger, you need to create a wallet: a [set of keys](cryptographic-keys.html#key-components) and an [address](accounts.html#addresses) that's been [funded with enough XRP](accounts.html#creating-accounts) to meet the [account reserve](reserves.html#reserves). The address is the identifier of your account and you use the [private key](cryptographic-keys.html#private-key) to sign transactions that you submit to the XRP Ledger. +To store value and execute transactions on the XRP Ledger, you need to create a wallet: a [set of keys](cryptographic-keys.html#key-components) and an [address](accounts.html#addresses) that's been [funded with enough XRP](accounts.html#creating-accounts) to meet the [account reserve](reserves.html). The address is the identifier of your account and you use the [private key](cryptographic-keys.html#private-key) to sign transactions that you submit to the XRP Ledger. -For testing and development purposes, you can use the [XRP Faucets](xrp-testnet-faucet.html) to generate keys and fund the account on the Testnet or Devnet. For production purposes, you should take care to store your keys and set up a [secure signing method](set-up-secure-signing.html). +For testing and development purposes, you can use the [XRP Faucets](xrp-testnet-faucet.html) to generate keys and fund the account on the Testnet or Devnet. For production purposes, you should take care to store your keys and set up a [secure signing method](set-up-secure-signing.html). To make it easy to create a wallet on the Testnet, `xrpl-py` provides the [`generate_faucet_wallet`](https://xrpl-py.readthedocs.io/en/latest/source/xrpl.wallet.html#xrpl.wallet.generate_faucet_wallet) method: @@ -124,7 +124,8 @@ To sign the transaction: {{ include_code("_code-samples/xrpl-py/prepare-payment.py", start_with="# Sign the transaction", end_before="# Print signed tx", language="py") }} -##### Send + +##### Send To send the transaction: @@ -135,16 +136,16 @@ To send the transaction: You can use `xrpl-py`'s [`xrpl.core.addresscodec`](https://xrpl-py.readthedocs.io/en/latest/source/xrpl.core.addresscodec.html) module to derive an [X-address](https://xrpaddress.info/) from the `Wallet.classic_address` field: - {{ include_code("_code-samples/xrpl-py/get-acct-info.py", start_with="# Derive an x-address from the classic address:", end_before="# Look up info about your account", language="py") }} -The X-address format [packs the address and destination tag](https://github.com/xrp-community/standards-drafts/issues/6) into a more user-friendly value. +The X-address format [packs the address and destination tag](https://github.com/xrp-community/standards-drafts/issues/6) into a more user-friendly value. + ### {{n.next()}}. Query the XRP Ledger You can query the XRP Ledger to get information about [a specific account](account-methods.html), [a specific transaction](tx.html), the state of a [current or a historical ledger](ledger-methods.html), and [the XRP Ledger's decentralized exhange](path-and-order-book-methods.html). You need to make these queries, among other reasons, to look up account info to follow best practices for [reliable transaction submission](reliable-transaction-submission.html). -Here, we'll use `xrpl-py`'s [`xrpl.account`](https://xrpl-py.readthedocs.io/en/latest/source/xrpl.account.html) module to look up information about the [wallet we generated](#2-generate-wallet) in the previous step. +Here, we'll use `xrpl-py`'s [`xrpl.account`](https://xrpl-py.readthedocs.io/en/latest/source/xrpl.account.html) module to look up information about the [wallet we generated](#2-generate-wallet) in the previous step. {{ include_code("_code-samples/xrpl-py/get-acct-info.py", start_with="# Look up info about your account", language="py") }} @@ -156,8 +157,8 @@ Here, we'll use `xrpl-py`'s [`xrpl.account`](https://xrpl-py.readthedocs.io/en/l Using these building blocks, we can create a simple Python app that: 1. Generates a wallet on the Testnet. -2. Connects to the XRP Ledger. -3. Looks up and prints information about the account you created. +2. Connects to the XRP Ledger. +3. Looks up and prints information about the account you created. ```python @@ -170,7 +171,7 @@ To run the app, you can copy and paste the code into an editor or IDE and run it ```sh git clone git@github.com:ripple/xrpl-dev-portal.git cd xrpl-dev-portal/content/_code-samples/xrpl-py/get-acct-info.py -python3 get-acct-info.py +python3 get-acct-info.py ``` You should see output similar to this example: @@ -209,9 +210,9 @@ The response fields that you want to inspect in most cases are: * `account_data.Sequence` — This is the sequence number of the next valid transaction for the account. You need to specify the sequence number when you prepare transactions. With `xrpl-py`, you can use the [`get_next_valid_seq_number`](https://xrpl-py.readthedocs.io/en/latest/source/xrpl.account.html#xrpl.account.get_next_valid_seq_number) to get this automatically from the XRP Ledger. See an example of this usage in the project [README](https://github.com/XRPLF/xrpl-py#serialize-and-sign-transactions). -* `account_data.Balance` — This is the account's XRP balance, [in drops](basic-data-types.html#specifying-currency-amounts). You can use this to confirm that you have enough XRP to send (if you're making a payment) and to meet the [current transaction cost](transaction-cost.html#current-transaction-cost) for a given transaction. +* `account_data.Balance` — This is the account's balance of [XRP, in drops][]. You can use this to confirm that you have enough XRP to send (if you're making a payment) and to meet the [current transaction cost](transaction-cost.html#current-transaction-cost) for a given transaction. -* `validated` — Indicates whether the returned data is from a [validated ledger](ledgers.html#open-closed-and-validated-ledgers). When sending transactions, it's important to ensure that the results are in a [final](finality-of-results.html) state in a validated ledger before further processing the transaction. For more information about best practices for transaction processing, see [Reliable Transaction Submission](reliable-transaction-submission.html). +* `validated` — Indicates whether the returned data is from a [validated ledger](ledgers.html#open-closed-and-validated-ledgers). When sending transactions, it's important to ensure that the results are in a [final](finality-of-results.html) state in a validated ledger before further processing the transaction. For more information about best practices for transaction processing, see [Reliable Transaction Submission](reliable-transaction-submission.html). For a detailed description of every response field, see [account_info](account_info.html#response-format). @@ -224,6 +225,7 @@ Now that you know how to use `xrpl-py` to connect to the XRP Ledger, generate a * [Set up secure signing](set-up-secure-signing.html) for your account. - - - + +{% include '_snippets/rippled-api-links.md' %} +{% include '_snippets/tx-type-links.md' %} +{% include '_snippets/rippled_versions.md' %} diff --git a/dactyl-config.yml b/dactyl-config.yml index cac243030b..f8aeaa52e4 100644 --- a/dactyl-config.yml +++ b/dactyl-config.yml @@ -155,6 +155,16 @@ targets: "consensus.html#calculate-and-share-validations": "consensus.html#検証の計算と共有" # Fix link from untranslated manifest.html: "rippled-server-modes.html#reporting-mode": "rippled-server-modes.html#レポーティングモード" + # Fix links for untranslated get-started-using-python.html: + "the-rippled-server.html#reasons-to-run-your-own-server": "rippled-server-modes.html#ストックサーバーを運用する理由" + "get-started-with-the-rippled-api.html#public-servers": "get-started-with-the-rippled-api.html#公開サーバー" + "cryptographic-keys.html#key-components": "cryptographic-keys.html#キーの生成" + "accounts.html#addresses": "accounts.html#アドレス" + "cryptographic-keys.html#private-key": "cryptographic-keys.html#キーの生成" + "basic-data-types.html#specifying-currency-amounts": "basic-data-types.html#通貨額の指定" + "transaction-cost.html#current-transaction-cost": "transaction-cost.html#現在のトランザクションコスト" + "ledgers.html#open-closed-and-validated-ledgers": "ledgers.html#ツリーの形式" + "account_info.html#response-format": "account_info.html#応答フォーマット" - name: xrp-api-only