mirror of
https://github.com/XRPLF/xrpl-dev-portal.git
synced 2026-07-30 02:20:21 +00:00
final version of tutorials guide
This commit is contained in:
Oliver Eggert
@@ -5,119 +5,163 @@ paths:
|
||||
|
||||
# XRPL Tutorial Conventions
|
||||
|
||||
The template below shows the full structure a tutorial should follow; HTML comments provide instructions on how to fill it in. If the tutorial doesn't already link to a specific code sample, prompt the user for which code samples to use.
|
||||
The template below shows the full structure a tutorial should follow. HTML comments serve two roles, distinguished by prefix:
|
||||
|
||||
- `<!-- TODO: ... -->` marks a slot that needs to be filled in by the author
|
||||
- `<!-- RULE: ... -->` describes the convention that applies at that spot
|
||||
|
||||
If the tutorial doesn't already link to a specific code sample, prompt the user for which code samples to use.
|
||||
|
||||
---
|
||||
|
||||
# Tutorial Title
|
||||
<!-- Title should be an imperative task. -->
|
||||
|
||||
This tutorial shows you how to <!-- 2-3 sentences of what/why/when. Link out to concept docs rather than explaining at length. {% amendment-disclaimer name="LendingProtocol" /%} -->
|
||||
<!-- RULE: Title should be an imperative task. -->
|
||||
This tutorial shows you how to <!-- TODO: 2-3 sentences of what/why/when. Link out to concept docs rather than explaining at length. If the tutorial uses a feature that isn't enabled on mainnet yet, add the {% amendment-disclaimer /%} markdoc tag. You can verify the status of amendments at https://xrpl.org/resources/known-amendments.md -->
|
||||
|
||||
|
||||
## Goals
|
||||
|
||||
By following this tutorial, you should learn how to:
|
||||
By the end of this tutorial, you will be able to:
|
||||
|
||||
<!-- TODO: 2-4 bullet points describing what the reader will learn. If the tutorial includes a GUI, also include a screenshot of the final product here. -->
|
||||
<!-- TODO: Bullet points describing what the reader will learn. -->
|
||||
|
||||
|
||||
## Prerequisites
|
||||
|
||||
<!-- RULE: List any knowledge and tool requirements in addition to the ones listed below. -->
|
||||
To complete this tutorial, you should:
|
||||
|
||||
- Have a basic understanding of the XRP Ledger.
|
||||
- Have an [XRP Ledger client library](../../references/client-libraries.md), such as **xrpl.js**, installed.
|
||||
<!-- TODO: Add knowledge prerequisites (especially tutorials this one builds on), basic dependencies (xrpl client library), required on-chain state (e.g., for an AMM trade, the AMM must exist), and amendments (use {% amendment-disclaimer %} for amendment-gated features). Tutorial-specific dependencies belong in the steps below — readers gloss over Prerequisites. -->
|
||||
|
||||
- Have an [XRP Ledger client library](../../references/client-libraries.md) installed. This page provides examples for the following:
|
||||
<!-- TODO: Update the list of supported languages. -->
|
||||
- **JavaScript** with the [xrpl.js library][]. See [Get Started Using JavaScript][] for setup steps.
|
||||
- **Python** with the [xrpl-py library][]. See [Get Started Using Python][] for setup steps.
|
||||
- **Go** with the [xrpl-go library][]. See [Get Started Using Go][] for setup steps.
|
||||
- **Java** with the [xrpl4j library][]. See [Get Started Using Java][] for setup steps.
|
||||
|
||||
## Source Code
|
||||
|
||||
<!-- TODO: Update the repo-link path to the topic parent folder housing all the sample codes. -->
|
||||
You can find the complete source code for this tutorial's examples in the {% repo-link path="_code-samples/<topic>/" %}code samples section of this website's repository{% /repo-link %}.
|
||||
<!-- TODO: Update the path= to point to this tutorial's _code-samples/<topic>/ folder. -->
|
||||
|
||||
|
||||
## Usage
|
||||
<!-- TODO: Include this section ONLY for sample-app tutorials — a GUI with multiple inputs, a CLI with options/parameters, or multiple scripts that run in a specific order. Omit entirely for single-file linear scripts. If the sample has a UI, optionally embed a video. -->
|
||||
|
||||
|
||||
## Steps
|
||||
<!-- 3-7 numbered ### subsections total. Fewer suggests the page shouldn't be a tutorial; more suggests splitting into multiple tutorials. Each step corresponds to one {% code-snippet %} (wrapped in {% tabs %}). Each ### heading is imperative, sentence-case. Each step continues the code sample from the previous step without skipping. If the script depends on prior on-chain state, add an explicit check step and also mention the requirement in Prerequisites above. -->
|
||||
<!-- RULE: Language-specific instructions are always wrapped in {% tabs %} markdoc, even if only one language is used. Each step after 1 uses the {% code-snippet %} markdoc tag. Code samples use unique comments to break code samples into logical steps. The first snippet in step 2 omits `from=`; the last step snippet omits `before=`. NEVER copy-paste source code into the tutorial. -->
|
||||
|
||||
### 1. Install dependencies
|
||||
<!-- Always begin with dependencies; readers gloss over Prerequisites. Include tutorial-specific dependencies here, not in Prerequisites above. -->
|
||||
|
||||
<!-- TODO: Update the list of commands to match included code sample languages. -->
|
||||
{% tabs %}
|
||||
{% tab label="JavaScript" %}
|
||||
From the code sample folder, use `npm` to install dependencies:
|
||||
|
||||
```sh
|
||||
npm i
|
||||
```bash
|
||||
npm install
|
||||
```
|
||||
{% /tab %}
|
||||
|
||||
{% tab label="Python" %}
|
||||
From the code sample folder, set up a virtual environment and use `pip` to install dependencies:
|
||||
|
||||
```sh
|
||||
```bash
|
||||
python -m venv .venv
|
||||
source .venv/bin/activate
|
||||
pip install -r requirements.txt
|
||||
```
|
||||
{% /tab %}
|
||||
|
||||
{% tab label="Go" %}
|
||||
From the code sample folder, use `go` to install dependencies.
|
||||
|
||||
```bash
|
||||
go mod tidy
|
||||
```
|
||||
{% /tab %}
|
||||
|
||||
{% tab label="Java" %}
|
||||
From the code sample folder, use `mvn` to install dependencies.
|
||||
|
||||
```bash
|
||||
mvn install
|
||||
```
|
||||
{% /tab %}
|
||||
{% /tabs %}
|
||||
|
||||
|
||||
### 2. Connect and get account(s)
|
||||
<!-- This step typically covers: importing dependencies, instantiating the client (variable name MUST be `client`), defining hardcoded values/constants, and deriving wallets or funding via faucet. Split into multiple steps if it grows past 15-20 lines. Never hardcode secret keys — use the faucet, an env var, or user-paste. Use the client library's "submit and wait" function for transactions. WebSocket/JSON-RPC calls: latest API version, `validated` ledger. -->
|
||||
### 2. Set up client and accounts
|
||||
<!-- RULE: This step covers: importing dependencies, instantiating the client, defining hardcoded values/constants, deriving wallets, loading setup data, or funding new wallets via faucet. The code sample should have this front-loaded already. -->
|
||||
|
||||
To get started, import the client library and instantiate an API client. <!-- TODO: mention wallets/test accounts if applicable. -->
|
||||
To get started, import the necessary libraries and instantiate a client to connect to the XRPL. This example imports:
|
||||
<!-- TODO: List the imports used in the code samples and what they're used for. Follow this sample format:
|
||||
|
||||
{% tabs %}
|
||||
{% tab label="JavaScript" %}
|
||||
{% code-snippet file="/_code-samples/<topic>/js/<file>.js" language="js" before="// TODO" /%}
|
||||
{% /tab %}
|
||||
- `xrpl`: Used for XRPL client connection, transaction submission, and wallet handling.
|
||||
- `fs` and `child_process`: Used to run tutorial set up scripts.
|
||||
|
||||
{% code-snippet file="/_code-samples/lending-protocol/js/createLoanBroker.js" language="js" before="// This step checks" /%}
|
||||
{% /tab %}
|
||||
{% tab label="Python" %}
|
||||
{% code-snippet file="/_code-samples/<topic>/py/<file>.py" language="py" before="# TODO" /%}
|
||||
- `xrpl`: Used for XRPL client connection, transaction submission, and wallet handling.
|
||||
- `json`: Used for loading and formatting JSON data.
|
||||
- `os`, `subprocess`, and `sys`: Used to run tutorial set up scripts.
|
||||
|
||||
{% code-snippet file="/_code-samples/lending-protocol/py/create_loan_broker.py" language="py" before="# This step checks" /%}
|
||||
{% /tab %}
|
||||
{% /tabs %}
|
||||
<!-- Wrap all snippets in {% tabs %} even when only one language is provided. Use unique comments in the source as from=/before= anchors. The first snippet omits from=; the last snippet omits before=. NEVER copy-paste source code into the tutorial — synchronization is brittle. Never put critical information ONLY in code comments — comments aren't translated; tutorial prose is. -->
|
||||
|
||||
-->
|
||||
|
||||
<!-- TODO: If the code sample uses setup data, add additional explanation for the loaded data. Follow this sample format:
|
||||
|
||||
Next, load the vault owner account and vault ID. The vault owner will also be the loan broker.
|
||||
{% tabs %}
|
||||
{% tab label="JavaScript" %}
|
||||
{% code-snippet file="/_code-samples/lending-protocol/js/createLoanBroker.js" language="js" from="// This step checks" before="// Prepare LoanBrokerSet" /%}
|
||||
|
||||
This example uses preconfigured accounts and vault data from the `lendingSetup.js` script, but you can replace `loanBroker` and `vaultID` with your own values.
|
||||
{% /tab %}
|
||||
{% tab label="Python" %}
|
||||
{% code-snippet file="/_code-samples/lending-protocol/py/create_loan_broker.py" language="py" from="# This step checks" before="# Prepare LoanBrokerSet" /%}
|
||||
|
||||
This example uses preconfigured accounts and vault data from the `lending_setup.py` script, but you can replace `loan_broker` and `vault_id` with your own values.
|
||||
{% /tab %}
|
||||
{% /tabs %}
|
||||
|
||||
-->
|
||||
|
||||
|
||||
### 3. <!-- TODO: imperative sentence-case heading for this step -->
|
||||
<!-- Duplicate this entire step block (heading + description + tabs + post-snippet text) for each additional step. Code samples should be `scripts` (not full applications or isolated snippets) for most tutorials — they demonstrate XRPL-specific functionality with minimal distractions and are easy to run end-to-end. Avoid JSON-RPC / WebSocket / commandline examples as primary sample code — they encourage insecure key handling and can't represent application logic. -->
|
||||
<!-- RULE: Each step from 3 and on should follow the code sample, broken down by the major steps defined by code comments. Duplicate this block for each additional step. Steps generally follow a prepare transaction, submit transaction, extract transaction response cadence. -->
|
||||
<!-- TODO: Briefly describe what happens in each step before adding the {% code-snippet %}. Follow this sample format:
|
||||
|
||||
<!-- TODO: brief description of what happens in this step. -->
|
||||
Create the [LoanBrokerSet transaction][] object. The management fee rate is set in 1/10th basis points. A value of `1000` equals 1% (100 basis points).
|
||||
|
||||
{% tabs %}
|
||||
{% tab label="JavaScript" %}
|
||||
{% code-snippet file="/_code-samples/<topic>/js/<file>.js" language="js" from="// TODO" before="// TODO next" /%}
|
||||
{% code-snippet file="/_code-samples/lending-protocol/js/createLoanBroker.js" language="js" from="// Prepare LoanBrokerSet" before="// Submit, sign" /%}
|
||||
{% /tab %}
|
||||
|
||||
{% tab label="Python" %}
|
||||
{% code-snippet file="/_code-samples/<topic>/py/<file>.py" language="py" from="# TODO" before="# TODO next" /%}
|
||||
{% code-snippet file="/_code-samples/lending-protocol/py/create_loan_broker.py" language="py" from="# Prepare LoanBrokerSet" before="# Submit, sign" /%}
|
||||
{% /tab %}
|
||||
{% /tabs %}
|
||||
|
||||
<!-- TODO: Optional follow-up text after the code — e.g., expected output, details to note for later. If the snippet calls an API method, link to the relevant reference doc (the common-links partials at the bottom of the file enable auto-links like `[ledger method][]`). -->
|
||||
-->
|
||||
|
||||
|
||||
## See Also
|
||||
|
||||
<!-- TODO: Links to related tutorials, use cases, and references. Include reference docs for every API method, transaction type, and ledger entry used in the tutorial — even if those links are redundant with inline links throughout the prose. -->
|
||||
<!-- TODO: Links to related concepts, tutorials, use cases, and references. Include reference docs for every API method, transaction type, and ledger entry used in the tutorial — even if those links are redundant with inline links throughout the prose. Follow this sample format:
|
||||
|
||||
**Concepts**:
|
||||
- [Lending Protocol][]
|
||||
- [Single Asset Vault](../../../../concepts/tokens/single-asset-vaults.md)
|
||||
|
||||
**Tutorials**:
|
||||
- [Create a Single Asset Vault](../use-single-asset-vaults/create-a-single-asset-vault.md)
|
||||
- [Deposit and Withdraw First-Loss Capital](./deposit-and-withdraw-cover.md)
|
||||
- [Create a Loan](./create-a-loan.md)
|
||||
|
||||
**References**:
|
||||
- [LoanBrokerSet transaction][]
|
||||
|
||||
-->
|
||||
|
||||
{% raw-partial file="/docs/_snippets/common-links.md" /%}
|
||||
|
||||
---
|
||||
|
||||
## Sample code conventions
|
||||
|
||||
Sample code referenced by `{% code-snippet %}` lives at `_code-samples/<topic>/<lang>/` with both:
|
||||
- A `README.md` at the topic root (used as the title/description on the [Code Samples](/resources/code-samples/) page)
|
||||
- A per-language `README.md` describing install and run
|
||||
|
||||
Language guidelines:
|
||||
- **JavaScript:** xrpl.js, `package.json` with `"type": "module"`, ESM imports (not CommonJS), `await` over `.then()`, [JavaScript Standard Style](https://standardjs.com), `JSON.stringify(obj, null, 2)` when dumping objects to console.
|
||||
- **Python:** xrpl-py, `requirements.txt`, `JsonRpcClient` (async only when needed), [Black Style](https://black.readthedocs.io/en/stable/).
|
||||
|
||||
Reference in New Issue
Block a user