mirror of
https://github.com/XRPLF/xrpl-dev-portal.git
synced 2025-11-23 21:25:49 +00:00
Information Architecture v3 (#1934)
* Update look up escrows to remove redundant info about lookups via sender/destination. Modify cancel expired escrow for brevity. * Cancel escrow: fix notes * Add draft of updated cancel-escrow.js. * Update intro to escrows. * Add Escrow Tutorial * Minor corrections * Fix headings, add HTML * Update escrow docs This commit re-createsf205a92db2with some adjustments: - Omit the accidentally-created dir full of junk - Fix some typos and one mistake in the Escrow limitations section - Add a table to the EscrowCreate ref to clarify valid combos of fields. * Concept info from send-a-time-held-escrow added to escrow.md * IA: Move "Consensus Network" files This re-creates some work from the original commit56fffe0b9f* Rewrite escrows article (re-created) This commit re-creates relevant work from the following commits:9a4a588f2bUpdate escrow.md context infoe1b017dc83Remove references to using escrow for interledger payments. * IA: Move "XRPL servers" files This re-creates some work from original commit7611979abf* IA: move "production readiness" files. Re-creates work from the following commit:692438693aMove tutorials to concepts * New intro articles Original commit:56fffe0b9f* IA: Reorg account concepts Re-creates some work from original commit56fffe0b9f* IA: reorg transaction concepts Original commits:9d4eff9940WIP - reorg accounts7611979abfWIP dir. reorg * IA: reorg consensus concepts Original commit:56fffe0b9f* IA: Reorg ledger docs Original commit:56fffe0b9f- Rephrased some details of the section * IA: rename issuing/operational addresses page Original commit:56fffe0b9f* Moving use cases * Fleshing out Use Cases Note, the dactyl-config.yml file has not been fully updated. * Clean up checks conceptual info. * Remove redundant checks use case section Original commit:3c29e9c05e* IA: move Dex under tokens Original commit:d08b3ba7d7* Touch up stablecoin issuer use case (#1856) * Consolidate stablecoin use case * Stablecoin issuer: cleanup progress through sending * Stablecoin issuer: reorg second half (Note: the dactyl-config.yml is not fully reconciled yet) * Move rippled and clio tutorials into infrastructure * Remove link to checks amendement. * Add note to account_objects.md about commandline interface type field. * Merge expiration case with lifecycle section. * Interoperability Use Cases * Add graphics to intro * Move escrow use cases to dedicated page. * Update use case page intros and corresponding concept info. * Clarify meaning of direct XRP payments. * Intro link updates * Payment use cases * Remove some unnecessary links in transactions section Original commit:e6fcf4a4dc* Link cleanup in Tokens section Original commit:9588dd5e70* Touch up 'Configure Peering' section Original commit:fc8f0990b8* Clean up links in accounts section Original commit:3da5fde7a8* Add NFT mkt use case * p2p payments: edits to Wallets * Clean up payments use cases * Refine history description * IA: use case cleanup * IA: reconcile servers, ledgers sections * IA: reconcile payment types, tx, tokens * IA: reconcile accounts section * IA: reconcile infra * IA: Fix most broken links * Full Docs Index: omit from sidebar * IA: fix up most broken links * fix Absolute path link to internal content * Quick updates to Software Ecosystem * Remove some absolute links to internal resources * Fix remaining broken links in JA target * Contributing: tweak formatting * Tutorials: fix some minor issues * remove interop use cases * remove intro image and personal references to dennis * alphabetize-transaction-nav * Remove unused files * Add QS escrow tutorials * IA: move ledgers, consensus protocol files around * IA: update nav for new page hierarchy * reordering of topics under new networks and servers top-nav * Move "Naming" to "What is XRP?" * Update dactyl-config.yml Remove xrp.md from the TOC. * Update list-xrp-as-an-exchange.md Update link to what-is-xrp * Update list-xrp-as-an-exchange.ja.md Change link to what-is-xrp * Update currency-formats.md Change link to what-is-xrp * Update currency-formats.ja.md Change link to what-is-xrp * Update cancel-an-expired-escrow.md Change link to what-is-xrp * Update paymentchannelfund.md Change link to what-is-xml * Update look-up-escrows.md Change link to what-is-xrp * Update tokens.md change link to what-is-xrp * Update use-payment-channels.md * Update send-a-time-held-escrow.md Update link to what-is-xml * fix broken links * Update parallel-networks.md Change link to what-is-xml * Update parallel-networks.ja.md * Update invariant-checking.md Remove link to xrp.html * Update invariant-checking.ja.md Remove link to xrp.html * Update transaction-cost.md Change link to what-is-xrp * Update transaction-cost.ja.md Change link to what-is-xrp * Update send-a-conditionally-held-escrow.md Change link to what-is-xrp * Update stablecoin-issuer.md Change link to what-is-xrp * Update tokens.ja.md Change link to what-is-xml * Update autobridging.ja.md Change link to what-is-xrp * Update currency-formats.md update text * reorganize infrastructure nav section * Update currency-formats.md Try removing link altogether. * Update currency-formats.ja.md Remove link to what-is-xrp.html * move commandline usage topic to infrastructure * initial intro rewrite * minor update to language * IA.v3: rm Production Readiness * Delete xrp.md * Update xrp link in snippet * Add redirect for old xrp.html URL * Small edits to 'What is XRP?' article * Add missing imgs * XRP - copy edit per @DennisDawson * restructure tutorials nav and pages * fix broken links * more broken link fixes * Algo trading: 1st draft * Algo trading: notes on taxes * Algo trading: edits per review * algo trading: fix broken link * Ledger structure: rewrite for accuracy and clarity * Update links to removed 'tree format' header * Ledger Structure: Update diagrams * Re-gen CSS for ledger structure changes * Ledger structure: edits per review * IA.v3: fix broken NFT links introduced by rebase * Desktop Wallet (py): update little stuff * Update some capacity/storage details * contribute doc nav update * fix image link in create diagram page * IAv3: Fix 'Ledgers' blurb * Update full history requirements with details from community members * add reviewer suggestions * Edits per @trippled review * Apply suggestions from peer review Co-authored-by: oeggert <117319296+oeggert@users.noreply.github.com> * FH: reword file size limit note per review * Update software ecosystem * updates per review * Minor tweaks to graphics * fixTypos * Update content/concepts/introduction/software-ecosystem.md Co-authored-by: Amarantha Kulkarni <amarantha-k@users.noreply.github.com> * Update content/concepts/introduction/software-ecosystem.md Co-authored-by: Amarantha Kulkarni <amarantha-k@users.noreply.github.com> * [JA] update AccountDelete cost * custom transactors doc * add doc to dactyl config * [JA] fix NonFungibleTokensV1_1 amendment status * [JA] update NFTokenOffer page * Remove old, unused XRP article (#2039) * add reviewer suggestions * Add tooling to check for file/nav consistency - From the repo top, run tool/check_file_consistency.py to look for Markdown files that exist in the "content/" directory but aren't used in the documentation. - New "enforce_filenames" filter prints a warning to console when building, if a file's path and filename don't match expectations based on its place in the nav and top heading. * File consistency checker: correctly handle filenames starting in _ * Remove unused old 'get started' and associated code * Create Resources section & reorg some files - Rename some files/folders based on their place in the nav - Move a bunch of non-documentation stuff, and docs on contributing code and/or docs to the new "Resources" section. - Known issue: nav spills into a second row on page widths between 993px-1110px. To be fixed in a later CSS update, maybe along with making the Resources dropdown multi-column. * Fix #2078 code tab bug CSS not built yet, to reduce merge conflicts. Won't have any effect until that happens. * fix Transaction JSON * [JA] translate contributing contents * fix contributing-to-documentation parent * fix contribute-code blurb * Top nav: add cols for Resources, fix broken links * CSS: fix top nav overflows * Fix broken link from redirect not in JA target * Top nav: add Infra to article types * Update contrib info & rename intro file * [ja] Update link to suggested first page to translate * [ja] fix contribute docs organization * Run private network with docker tutorial (#2065) * [NO-ISSUE] Run private network with docker tutorial Adds a tutorial page in the Infrastructure section on how to run a private XRPL network with Docker. Please let me know if you think this is a useful page to include for developers, whether the steps are clear or not, and if you have suggestions on what can be added to it. * Add minor link fixes and Japanese target * Apply suggestions from code review Co-authored-by: Amarantha Kulkarni <amarantha-k@users.noreply.github.com> * Add link to ripple-docker-testnet setup scripts in See Also section * Update repo URL --------- Co-authored-by: Amarantha Kulkarni <amarantha-k@users.noreply.github.com> * add intro gfx (#2036) * add intro gfx * Move graphic up * Update some graphics with their revised versions * Add updated version of the custodial vs non-custodial graphic --------- Co-authored-by: Amarantha Kulkarni <amarantha-k@users.noreply.github.com> Co-authored-by: Amarantha Kulkarni <akulkarni@ripple.com> * Update to reflect current UNL publishers * [ja] update contributing Co-authored-by: tequ <git@tequ.dev> * Incorporate feedback on "What is XRP" page. (#2099) * Add trademark info for XRP * Revert section to previous state * Fix broken link (#2101) --------- Co-authored-by: Oliver Eggert <oeggert@ripple.com> Co-authored-by: ddawson <dennis.s.dawson@gmail.com> Co-authored-by: Maria Shodunke <mshodunke@ripple.com> Co-authored-by: tequ <git@tequ.dev> Co-authored-by: oeggert <117319296+oeggert@users.noreply.github.com> Co-authored-by: Amarantha Kulkarni <amarantha-k@users.noreply.github.com> Co-authored-by: develoQ <develoQ.jp@gmail.com> Co-authored-by: Maria Shodunke <maria-robobug@users.noreply.github.com> Co-authored-by: Amarantha Kulkarni <akulkarni@ripple.com>
This commit is contained in:
Rome Reginelli
94
content/resources/contribute-code/contribute-code.ja.md
Normal file
94
content/resources/contribute-code/contribute-code.ja.md
Normal file
@@ -0,0 +1,94 @@
|
||||
---
|
||||
html: contribute-code.html
|
||||
parent: resources.html
|
||||
blurb: XRP Ledgerプロトコルにどのように機能を実装するかを学びます。
|
||||
labels:
|
||||
- ブロックチェーン
|
||||
---
|
||||
# コードへの貢献
|
||||
|
||||
XRP Ledgerを動かすソフトウェアはオープンソースです。誰でもダウンロードし、変更し、拡張し、調査することができます。もしあなたがコードに貢献したいのであれば、コミュニティと協力してあなたの変更の仕様を定義し、XRP Ledgerのプロトコルとブロックチェーンの一部になる前にコードをテストすることが重要です。
|
||||
|
||||
# コアサーバのソースコード
|
||||
|
||||
XRP Ledgerを動かすソフトウェアはオープンソースです。コミュニティが参加することで、より良いものが生まれます。[ドキュメント](docs.html)内の"[Source]"リンクから関連するソースコードに直接ジャンプしたり、GitHubでソースコードを閲覧することができます：
|
||||
|
||||
| XRP Ledger ソースコード | |
|
||||
|:-----------------------|:----------------------------------------------------|
|
||||
| リポジトリ | <https://github.com/XRPLF/rippled> |
|
||||
| ライセンス | [Multiple; ISC (permissive)](https://github.com/XRPLF/rippled/blob/develop/LICENSE.md) |
|
||||
| プログラム言語 | C++ |
|
||||
|
||||
何から始めたらいいか分からないという方のために、Dev Null Productionsは、XRP Ledgerサーバー(`rippled`)のコア実装の仕組みや機能を説明した、詳細かつ充実した[**ソースコード・ガイド**](https://xrpintel.com/source)を提供しています。
|
||||
|
||||
|
||||
## XRP Ledgerの規格
|
||||
|
||||
`rippled`に対する変更はXRP Ledger Standard (XLS)、つまり変更の仕様を特定し詳細に記述した文書によって管理されます。開発にコミットする前に、[XRPL-Standardsリポジトリ](https://github.com/XRPLF/XRPL-Standards/discussions)で議論を始める必要があります。これにより、コミュニティはあなたの変更に関して議論し、フィードバックを提供する機会を得ることができます。
|
||||
|
||||
**注記:*** バグ修正にはXLSは必要ありませんが、Amendmentが必要になる場合があります。
|
||||
|
||||
XLSの作成には独自のプロセスがありますが、簡単にまとめると次のようになります：
|
||||
|
||||
1. ディスカッションを開始し、フィードバックを集めます。
|
||||
2. StandardリポジトリにXLSドラフトを作成します。
|
||||
3. XLSドラフトを仕様候補として公開します。
|
||||
|
||||
詳細については、[XLS貢献ガイド](https://github.com/XRPLF/XRPL-Standards/blob/master/CONTRIBUTING.md) をご覧ください。
|
||||
|
||||
|
||||
## Amendmentの実装
|
||||
|
||||
XLSドラフトを作成した後、その変更にAmendmentが必要かどうかを判断する必要があります。特に次のような**トランザクション処理**に影響する変更にはAmendment が必要です。
|
||||
|
||||
- レジャールールを変更し、異なる結果をもたらすもの。
|
||||
- トランザクションの追加または削除。
|
||||
- コンセンサスへの影響がある変更。
|
||||
|
||||
**注記:** 変更にAmendmentが必要ない場合、そのままコーディングとデプロイに進むことができます。
|
||||
|
||||
コードをAmendmentとして実装するには、次のファイルにAmendment情報を追加する必要があります。
|
||||
|
||||
- **Feature.cpp**:
|
||||
|
||||
開発が完了するまで、`Supported`パラメータは`no`に設定してください。
|
||||
|
||||
バグの修正の場合、`DefaultVote`パラメータを`yes`に設定する必要があります。
|
||||
|
||||
- **Feature.h**: `numFeatures` カウンタを増やし、`extern uint256 const` 変数を宣言します。
|
||||
|
||||
|
||||
## コーディングとデプロイ
|
||||
|
||||
一般的な開発プロセスは以下の通りです。
|
||||
|
||||
1. コードを開発するためにはまず、[`rippled` リポジトリ](https://github.com/XRPLF/rippled) をフォークまたはブランチを作成します。
|
||||
|
||||
**ヒント:** 何から始めたらいいかわからない場合は、_Dev Null Productions_ が詳細かつ充実した [`rippled` ソースコードガイド](https://xrpintel.com/source) を提供しています。
|
||||
|
||||
2. 単体テストと統合テストを実行します。独立した環境で作業をテストするにはスタンドアロンモードでサーバを実行するのが良いでしょう。
|
||||
|
||||
3. `XRPLF:develop`にプルリクエストを作成します。
|
||||
|
||||
**Amendment向けの注記:** **Feature.cpp**の`Supported`パラメータを`yes`に更新します。
|
||||
|
||||
4. プルリクエストがXRP Ledgerのメンテナによって承認されると、あなたのコードは`develop`にマージされ、Devnet上で追加のテストを行うことができます。
|
||||
|
||||
**Amendment向けの注記:**
|
||||
- `DefaultVote`パラメータはロックされます。
|
||||
- もしAmendmentに問題が見つかれば、Amendmentの修正と新しいPRの提出を再度行う必要があります。新しいPRでは`DefaultVote`を変更することができます。
|
||||
|
||||
年に4回、`develop`で承認されたPRからリリース候補がビルドされます。このパッケージはTestnetとMainnet上のいくつかのノードにデプロイされます。リリース候補に問題がなければ、コードは`master`にマージされ、メインネット上のノードはこのビルドにアップグレードできます。
|
||||
|
||||
6. 新しいAmendmentは合意形成プロセスを経て、バリデーターがそのAmendmentを有効にするかどうかを投票します。
|
||||
|
||||
|
||||
## コードのフローチャート
|
||||
|
||||
|
||||
|
||||
|
||||
## 関連項目
|
||||
|
||||
- **コンセプト:**
|
||||
- [Amendment](amendments.html)
|
||||
94
content/resources/contribute-code/contribute-code.md
Normal file
94
content/resources/contribute-code/contribute-code.md
Normal file
@@ -0,0 +1,94 @@
|
||||
---
|
||||
html: contribute-code.html
|
||||
parent: resources.html
|
||||
blurb: Learn how features can be coded into the XRP Ledger protocol.
|
||||
labels:
|
||||
- Blockchain
|
||||
---
|
||||
# Contribute Code
|
||||
|
||||
The software that powers the XRP Ledger is open source. Anyone can download, modify, extend, or explore it. If you want to contribute code, it's important to work with the community to define the specifications of your changes and test the code before it becomes a part of the XRP Ledger protocol and blockchain.
|
||||
|
||||
## Core Server Source
|
||||
|
||||
The software that powers the XRP Ledger is open-source, so anyone can download, modify, extend, or explore it. Community involvement makes it better. Look for "[Source]" links in the [documentation](docs.html) to jump directly into the related source code, or browse the source code on GitHub:
|
||||
|
||||
| XRP Ledger Source Code | |
|
||||
|:-----------------------|:----------------------------------------------------|
|
||||
| Repository | <https://github.com/XRPLF/rippled> |
|
||||
| License | [Multiple; ISC (permissive)](https://github.com/ripple/rippled/blob/develop/LICENSE.md) |
|
||||
| Programming Language | C++ |
|
||||
|
||||
If you're not sure where to start, Dev Null Productions provides a detailed and thorough [**Source Code Guide**](https://xrpintel.com/source) that describes the structure and functions of the core XRP Ledger server (`rippled`) implementation.
|
||||
|
||||
|
||||
## XRP Ledger Standards
|
||||
|
||||
Changes to `rippled` are tracked by an XRP Ledger Standard (XLS), a document that identifies and details the specifications of a change. Before committing to development, you must start a discussion in the [XRPL-Standards repo](https://github.com/XRPLF/XRPL-Standards/discussions). This provides the community a chance to discuss and provide feedback about your change.
|
||||
|
||||
**Note:** Bug fixes don't require an XLS, but may require an amendment.
|
||||
|
||||
Creating an XLS has its own process, but can be summarized as:
|
||||
|
||||
1. Start a discussion and gather feedback.
|
||||
2. Create an XLS draft in the standards repo.
|
||||
3. Publishing the XLS draft as a Candidate Specification.
|
||||
|
||||
For details, see the [XLS contributing guide](https://github.com/XRPLF/XRPL-Standards/blob/master/CONTRIBUTING.md).
|
||||
|
||||
|
||||
## Amendment Implementation
|
||||
|
||||
After you've created an XLS draft, you now need to determine if your change requires an amendment. Changes that affect **transaction processing** require amendments, specifically changes that:
|
||||
|
||||
- Modify ledger rules, resulting in different outcomes.
|
||||
- Add or remove transactions.
|
||||
- Affect consensus.
|
||||
|
||||
**Note:** If your change doesn't need an amendment, you can go straight to coding and deployment.
|
||||
|
||||
Implementing code as an amendment requires you to add the amendment to these files:
|
||||
|
||||
- **Feature.cpp**:
|
||||
|
||||
`Supported` parameter should be set to `no` until development is complete.
|
||||
|
||||
`DefaultVote` parameter should be set to `yes` for bug fixes; everything else defaults to `no`.
|
||||
|
||||
- **Feature.h**: Increment the `numFeatures` counter and declare an `extern uint256 const` variable.
|
||||
|
||||
|
||||
## Coding and Deployment
|
||||
|
||||
The general development path breaks down as follows:
|
||||
|
||||
1. Create a fork or branch in the [`rippled` repository](https://github.com/XRPLF/rippled) to develop your code.
|
||||
|
||||
**Tip:** If you're not sure where to start, _Dev Null Productions_ provides a detailed and thorough [`rippled` Source Code Guide](https://xrpintel.com/source).
|
||||
|
||||
2. Run unit and integration tests. Running a server in _stand-alone mode_ is useful for testing your changes in an isolated environment, but you may want to stand up a private network for extensive changes.
|
||||
|
||||
3. Create a pull request on `XRPLF:develop`.
|
||||
|
||||
**Note for Amendments:** Update the `Supported` paramter to `yes` in **Feature.cpp**.
|
||||
|
||||
4. After the pull request is approved by XRP Ledger maintainers, your code is merged into `develop` and additional testing can be done on Devnet.
|
||||
|
||||
**Note for Amendments:**
|
||||
- The `DefaultVote` parameter is now locked.
|
||||
- If problems are found with the amendment, you must restart the process of making fixes and submitting a new PR. You can change the default vote in the new PR.
|
||||
|
||||
5. On a quarterly basis, a release candidate is built from approved PRs on `develop`. The package is deployed to Testnet and a few nodes on Mainnet. If no issues are found with the release candidate, the code is merged into `master` and nodes on Mainnet can upgrade to this build.
|
||||
|
||||
6. New amendments go through the consensus process and validators vote on whether to enable them.
|
||||
|
||||
|
||||
## Code Flowchart
|
||||
|
||||
|
||||
|
||||
|
||||
## See Also
|
||||
|
||||
- **Concepts:**
|
||||
- [Amendments](amendments.html)
|
||||
@@ -0,0 +1,389 @@
|
||||
---
|
||||
html: create-custom-transactors.html
|
||||
parent: contribute-code.html
|
||||
blurb: XRPレジャーとやり取りするためのカスタムトランザクタを作成します。
|
||||
labels:
|
||||
- 開発
|
||||
- ブロックチェーン
|
||||
---
|
||||
# カスタムトランザクタの作成
|
||||
|
||||
_トランザクタ_ はトランザクションを処理し、XRP Ledgerを変更するコードです。カスタムトランザクタを作成することで、`rippled`に新しい機能を追加することができます。このチュートリアルではトランザクタのコーディングについて説明しますが、それをXRPLに追加するにはAmendmentプロセスを経る必要があります。 [XRPレジャーのコードへの貢献](contribute-code-flow.html)をご覧ください。
|
||||
|
||||
トランザクタは 基本的な処理順序に則って処理されます。
|
||||
|
||||
1. シリアライズ型レジャーエントリ(SLE/serialized type ledger entry)の _view_ へアクセスします。
|
||||
2. _view_ 内の値を更新、削除、挿入します。
|
||||
3. 確定した変更を _view_ からレジャーに適用します。
|
||||
|
||||
**注記:** _view_ はレジャーのサンドボックスです。トランザクタは必要なエラーチェックと変更のすべてをサンドボックス内で行い、レジャーでは直接行いません。値が確定した後、変更はレジャーにアトミックに適用されます。
|
||||
|
||||
このチュートリアルでは、既存の`CreateCheck`トランザクションを例として使用します。ソースファイルはここで確認できます。
|
||||
|
||||
- [ヘッダファイル](https://github.com/XRPLF/rippled/blob/master/src/ripple/app/tx/impl/CreateCheck.h)
|
||||
- [CPPファイル](https://github.com/XRPLF/rippled/blob/master/src/ripple/app/tx/impl/CreateCheck.cpp)
|
||||
|
||||
|
||||
## ヘッダファイル
|
||||
|
||||
次の形式でヘッダーファイルを作成します。
|
||||
|
||||
```c++
|
||||
namespace ripple {
|
||||
|
||||
class CreateCheck : public Transactor
|
||||
{
|
||||
public:
|
||||
static constexpr ConsequencesFactoryType ConsequencesFactory{Normal};
|
||||
|
||||
explicit CreateCheck(ApplyContext& ctx) : Transactor(ctx)
|
||||
{
|
||||
}
|
||||
|
||||
static NotTEC
|
||||
preflight(PreflightContext const& ctx);
|
||||
|
||||
static TER
|
||||
preclaim(PreclaimContext const& ctx);
|
||||
|
||||
TER
|
||||
doApply() override;
|
||||
};
|
||||
|
||||
} // namespace ripple
|
||||
```
|
||||
|
||||
`ApplyContext`でトランザクタを初期化すると、トランザクタは以下にアクセスできます：
|
||||
|
||||
- トランザクタをトリガーしたトランザクション。
|
||||
- SLEのビュー。
|
||||
- エラーを記録するためのジャーナル。
|
||||
|
||||
|
||||
## CPPファイル
|
||||
|
||||
### 1. `preflight`関数の追加
|
||||
|
||||
`preflight`関数はレジャーにアクセスする前にトランザクション自体にエラーがないかチェックします。無効なトランザクションや正しく設定されていないトランザクションは拒否されなければなりません。
|
||||
|
||||
- `PreflightContext`はレジャーのビューを持っていません。
|
||||
- レジャーやトランザクションからフィールドを取得するには、次のようにブラケット記法を使用します。
|
||||
|
||||
auto const curExpiration = (*sle*)[~sfExpiration];
|
||||
(*sle)[sfBalance] = (*sle)[sfBalance] + reqDelta;
|
||||
|
||||
**注記:** `~`記号は optional型を返します。
|
||||
|
||||
- レジャーとトランザクションのスキーマはこちらから確認できます。
|
||||
- [`LedgerFormats.cpp`](https://github.com/XRPLF/rippled/blob/master/src/ripple/protocol/impl/LedgerFormats.cpp)
|
||||
- [`TxFormats.cpp`](https://github.com/XRPLF/rippled/blob/master/src/ripple/protocol/impl/TxFormats.cpp)
|
||||
|
||||
-` rippled` はトランザクションの結果を結果コードで表します。[トランザクションの結果](transaction-results.html)をご覧ください。
|
||||
|
||||
```c++
|
||||
CreateCheck::preflight(PreflightContext const& ctx)
|
||||
{
|
||||
// Check if this amendment functionality is enabled on the network.
|
||||
if (!ctx.rules.enabled(featureChecks))
|
||||
return temDISABLED;
|
||||
|
||||
NotTEC const ret{preflight1(ctx)};
|
||||
if (!isTesSuccess(ret))
|
||||
return ret;
|
||||
|
||||
if (ctx.tx.getFlags() & tfUniversalMask)
|
||||
{
|
||||
// There are no flags (other than universal) for CreateCheck yet.
|
||||
JLOG(ctx.j.warn()) << "Malformed transaction: Invalid flags set.";
|
||||
return temINVALID_FLAG;
|
||||
}
|
||||
if (ctx.tx[sfAccount] == ctx.tx[sfDestination])
|
||||
{
|
||||
// They wrote a check to themselves.
|
||||
JLOG(ctx.j.warn()) << "Malformed transaction: Check to self.";
|
||||
return temREDUNDANT;
|
||||
}
|
||||
|
||||
{
|
||||
STAmount const sendMax{ctx.tx.getFieldAmount(sfSendMax)};
|
||||
if (!isLegalNet(sendMax) || sendMax.signum() <= 0)
|
||||
{
|
||||
JLOG(ctx.j.warn()) << "Malformed transaction: bad sendMax amount: "
|
||||
<< sendMax.getFullText();
|
||||
return temBAD_AMOUNT;
|
||||
}
|
||||
|
||||
if (badCurrency() == sendMax.getCurrency())
|
||||
{
|
||||
JLOG(ctx.j.warn()) << "Malformed transaction: Bad currency.";
|
||||
return temBAD_CURRENCY;
|
||||
}
|
||||
}
|
||||
|
||||
if (auto const optExpiry = ctx.tx[~sfExpiration])
|
||||
{
|
||||
if (*optExpiry == 0)
|
||||
{
|
||||
JLOG(ctx.j.warn()) << "Malformed transaction: bad expiration";
|
||||
return temBAD_EXPIRATION;
|
||||
}
|
||||
}
|
||||
|
||||
return preflight2(ctx);
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
### 2. `preclaim`関数の追加
|
||||
|
||||
`preclaim`関数は、現在のレジャーの情報を見る必要があるエラーをチェックします。
|
||||
|
||||
- このステップが結果コード`tesSUCCESS`または`tec`を返した場合、トランザクションはキューに入れられ、ピアに送信されます。
|
||||
|
||||
```c++
|
||||
CreateCheck::preclaim(PreclaimContext const& ctx)
|
||||
{
|
||||
AccountID const dstId{ctx.tx[sfDestination]};
|
||||
|
||||
// Use the `keylet` function to get the key of the SLE. Views have either `read` or `peek` access.
|
||||
// `peek` access allows the developer to modify the SLE returned.
|
||||
auto const sleDst = ctx.view.read(keylet::account(dstId));
|
||||
if (!sleDst)
|
||||
{
|
||||
JLOG(ctx.j.warn()) << "Destination account does not exist.";
|
||||
return tecNO_DST;
|
||||
}
|
||||
|
||||
auto const flags = sleDst->getFlags();
|
||||
|
||||
// Check if the destination has disallowed incoming checks
|
||||
if (ctx.view.rules().enabled(featureDisallowIncoming) &&
|
||||
(flags & lsfDisallowIncomingCheck))
|
||||
return tecNO_PERMISSION;
|
||||
|
||||
if ((flags & lsfRequireDestTag) && !ctx.tx.isFieldPresent(sfDestinationTag))
|
||||
{
|
||||
// The tag is basically account-specific information we don't
|
||||
// understand, but we can require someone to fill it in.
|
||||
JLOG(ctx.j.warn()) << "Malformed transaction: DestinationTag required.";
|
||||
return tecDST_TAG_NEEDED;
|
||||
}
|
||||
|
||||
{
|
||||
STAmount const sendMax{ctx.tx[sfSendMax]};
|
||||
if (!sendMax.native())
|
||||
{
|
||||
// The currency may not be globally frozen
|
||||
AccountID const& issuerId{sendMax.getIssuer()};
|
||||
if (isGlobalFrozen(ctx.view, issuerId))
|
||||
{
|
||||
JLOG(ctx.j.warn()) << "Creating a check for frozen asset";
|
||||
return tecFROZEN;
|
||||
}
|
||||
// If this account has a trustline for the currency, that
|
||||
// trustline may not be frozen.
|
||||
//
|
||||
// Note that we DO allow create check for a currency that the
|
||||
// account does not yet have a trustline to.
|
||||
AccountID const srcId{ctx.tx.getAccountID(sfAccount)};
|
||||
if (issuerId != srcId)
|
||||
{
|
||||
// Check if the issuer froze the line
|
||||
auto const sleTrust = ctx.view.read(
|
||||
keylet::line(srcId, issuerId, sendMax.getCurrency()));
|
||||
if (sleTrust &&
|
||||
sleTrust->isFlag(
|
||||
(issuerId > srcId) ? lsfHighFreeze : lsfLowFreeze))
|
||||
{
|
||||
JLOG(ctx.j.warn())
|
||||
<< "Creating a check for frozen trustline.";
|
||||
return tecFROZEN;
|
||||
}
|
||||
}
|
||||
if (issuerId != dstId)
|
||||
{
|
||||
// Check if dst froze the line.
|
||||
auto const sleTrust = ctx.view.read(
|
||||
keylet::line(issuerId, dstId, sendMax.getCurrency()));
|
||||
if (sleTrust &&
|
||||
sleTrust->isFlag(
|
||||
(dstId > issuerId) ? lsfHighFreeze : lsfLowFreeze))
|
||||
{
|
||||
JLOG(ctx.j.warn())
|
||||
<< "Creating a check for destination frozen trustline.";
|
||||
return tecFROZEN;
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
if (hasExpired(ctx.view, ctx.tx[~sfExpiration]))
|
||||
{
|
||||
JLOG(ctx.j.warn()) << "Creating a check that has already expired.";
|
||||
return tecEXPIRED;
|
||||
}
|
||||
return tesSUCCESS;
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
### 3. Add a `doApply()` function.
|
||||
|
||||
The `doApply()` function has read/write access, enabling you to modify the ledger.
|
||||
|
||||
```c++
|
||||
CreateCheck::doApply()
|
||||
{
|
||||
auto const sle = view().peek(keylet::account(account_));
|
||||
if (!sle)
|
||||
return tefINTERNAL;
|
||||
|
||||
// A check counts against the reserve of the issuing account, but we
|
||||
// check the starting balance because we want to allow dipping into the
|
||||
// reserve to pay fees.
|
||||
{
|
||||
STAmount const reserve{
|
||||
view().fees().accountReserve(sle->getFieldU32(sfOwnerCount) + 1)};
|
||||
|
||||
if (mPriorBalance < reserve)
|
||||
return tecINSUFFICIENT_RESERVE;
|
||||
}
|
||||
|
||||
// Note that we use the value from the sequence or ticket as the
|
||||
// Check sequence. For more explanation see comments in SeqProxy.h.
|
||||
std::uint32_t const seq = ctx_.tx.getSeqProxy().value();
|
||||
Keylet const checkKeylet = keylet::check(account_, seq);
|
||||
auto sleCheck = std::make_shared<SLE>(checkKeylet);
|
||||
|
||||
sleCheck->setAccountID(sfAccount, account_);
|
||||
AccountID const dstAccountId = ctx_.tx[sfDestination];
|
||||
sleCheck->setAccountID(sfDestination, dstAccountId);
|
||||
sleCheck->setFieldU32(sfSequence, seq);
|
||||
sleCheck->setFieldAmount(sfSendMax, ctx_.tx[sfSendMax]);
|
||||
if (auto const srcTag = ctx_.tx[~sfSourceTag])
|
||||
sleCheck->setFieldU32(sfSourceTag, *srcTag);
|
||||
if (auto const dstTag = ctx_.tx[~sfDestinationTag])
|
||||
sleCheck->setFieldU32(sfDestinationTag, *dstTag);
|
||||
if (auto const invoiceId = ctx_.tx[~sfInvoiceID])
|
||||
sleCheck->setFieldH256(sfInvoiceID, *invoiceId);
|
||||
if (auto const expiry = ctx_.tx[~sfExpiration])
|
||||
sleCheck->setFieldU32(sfExpiration, *expiry);
|
||||
|
||||
view().insert(sleCheck);
|
||||
|
||||
auto viewJ = ctx_.app.journal("View");
|
||||
// If it's not a self-send (and it shouldn't be), add Check to the
|
||||
// destination's owner directory.
|
||||
if (dstAccountId != account_)
|
||||
{
|
||||
auto const page = view().dirInsert(
|
||||
keylet::ownerDir(dstAccountId),
|
||||
checkKeylet,
|
||||
describeOwnerDir(dstAccountId));
|
||||
|
||||
JLOG(j_.trace()) << "Adding Check to destination directory "
|
||||
<< to_string(checkKeylet.key) << ": "
|
||||
<< (page ? "success" : "failure");
|
||||
|
||||
if (!page)
|
||||
return tecDIR_FULL;
|
||||
|
||||
sleCheck->setFieldU64(sfDestinationNode, *page);
|
||||
}
|
||||
|
||||
{
|
||||
auto const page = view().dirInsert(
|
||||
keylet::ownerDir(account_),
|
||||
checkKeylet,
|
||||
describeOwnerDir(account_));
|
||||
|
||||
JLOG(j_.trace()) << "Adding Check to owner directory "
|
||||
<< to_string(checkKeylet.key) << ": "
|
||||
<< (page ? "success" : "failure");
|
||||
|
||||
if (!page)
|
||||
return tecDIR_FULL;
|
||||
|
||||
sleCheck->setFieldU64(sfOwnerNode, *page);
|
||||
}
|
||||
// If we succeeded, the new entry counts against the creator's reserve.
|
||||
adjustOwnerCount(view(), sle, 1, viewJ);
|
||||
return tesSUCCESS;
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
## 追加の関数
|
||||
|
||||
必要に応じて、カスタムトランザクタにヘルパー関数を追加することができます。特殊な場合に役立つ特別な関数がいくつかあります。
|
||||
|
||||
|
||||
### `calculateBaseFee`
|
||||
|
||||
ほとんどのトランザクションはデフォルトの[Referenceトランザクションコスト](transaction-cost.html)をそのまま引き継ぎます。しかし、トランザクションで通常以外のトランザクションコストを定義する必要がある場合、トランザクションの`calculateBaseFee`メソッドをカスタムメソッドに置き換えることができます。
|
||||
|
||||
次の例では、`EscrowFinish`ランザクションが条件付きエスクローに対して、フルフィルメントの大きさに応じて追加コストを請求する方法を示しています。
|
||||
|
||||
```c++
|
||||
XRPAmount
|
||||
EscrowFinish::calculateBaseFee(ReadView const& view, STTx const& tx)
|
||||
{
|
||||
XRPAmount extraFee{0};
|
||||
|
||||
if (auto const fb = tx[~sfFulfillment])
|
||||
{
|
||||
extraFee += view.fees().base * (32 + (fb->size() / 16));
|
||||
}
|
||||
|
||||
return Transactor::calculateBaseFee(view, tx) + extraFee;
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
### `makeTxConsequences`
|
||||
|
||||
`rippled`は[`TxConsequences`](https://github.com/XRPLF/rippled/blob/master/src/ripple/app/tx/applySteps.h#L41-L44)クラスを使用して、トランザクション適用時のアカウントへの結果を記述します。このクラスは手数料、使用可能な最大XRP、トランザクションによって消費されたシーケンス番号の数を追跡します。結果には次の3つのタイプがあります。
|
||||
|
||||
- **ノーマル:**トランザクションは署名に影響を与えず、XRP手数料を消費するのみです。手数料を超えてXRPを消費するトランザクションは正常とはみなされません。
|
||||
- **ブロッカー:**トランザクションの署名に影響を与え、有効なトランザクションがその後ろにキューイングされるのを防ぎます。
|
||||
- **カスタム:**トランザクタは結果を決定するために追加の作業を行う必要があります。
|
||||
|
||||
`makeTxConsequences`関数を使うと、以下のような状況に対してカスタム結果を作成することができます：
|
||||
|
||||
- XRPを送信する支払い。
|
||||
- 複数のシーケンス番号を消費するチケット。
|
||||
- 設定されたフラグやフィールドによって、正常またはブロッカーとなるトランザクション。
|
||||
|
||||
**注記:** `TxConsequences`は[トランザクションキュー](transaction-queue.html)にのみ影響します。トランザクションがレジャーに適用されたときに手数料を請求する可能性が高い場合、それはピアに送信されます。手数料を請求する可能性がない場合、またはそれが判断できない場合は、送信されません。
|
||||
|
||||
|
||||
```c++
|
||||
SetAccount::makeTxConsequences(PreflightContext const& ctx)
|
||||
{
|
||||
// The SetAccount may be a blocker, but only if it sets or clears
|
||||
// specific account flags.
|
||||
auto getTxConsequencesCategory = [](STTx const& tx) {
|
||||
if (std::uint32_t const uTxFlags = tx.getFlags();
|
||||
uTxFlags & (tfRequireAuth | tfOptionalAuth))
|
||||
return TxConsequences::blocker;
|
||||
|
||||
if (auto const uSetFlag = tx[~sfSetFlag]; uSetFlag &&
|
||||
(*uSetFlag == asfRequireAuth || *uSetFlag == asfDisableMaster ||
|
||||
*uSetFlag == asfAccountTxnID))
|
||||
return TxConsequences::blocker;
|
||||
|
||||
if (auto const uClearFlag = tx[~sfClearFlag]; uClearFlag &&
|
||||
(*uClearFlag == asfRequireAuth || *uClearFlag == asfDisableMaster ||
|
||||
*uClearFlag == asfAccountTxnID))
|
||||
return TxConsequences::blocker;
|
||||
|
||||
return TxConsequences::normal;
|
||||
};
|
||||
|
||||
return TxConsequences{ctx.tx, getTxConsequencesCategory(ctx.tx)};
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
## 次のステップ
|
||||
|
||||
新しいトランザクタでサーバを再コンパイルし、[スタンドアロンモード](use-stand-alone-mode.html)でテストしてください。もしAmendmentの後ろにトランザクタをコーディングした場合、設定ファイルを使ってその機能を[強制的に有効にする](test-amendments.html)ことができます。
|
||||
389
content/resources/contribute-code/create-custom-transactors.md
Normal file
389
content/resources/contribute-code/create-custom-transactors.md
Normal file
@@ -0,0 +1,389 @@
|
||||
---
|
||||
html: create-custom-transactors.html
|
||||
parent: contribute-code.html
|
||||
blurb: Create custom transactors to interact with the XRP Ledger.
|
||||
labels:
|
||||
- Development
|
||||
- Blockchain
|
||||
---
|
||||
# Create Custom Transactors
|
||||
|
||||
A _transactor_ is code that processes a transaction and modifies the XRP Ledger. Creating custom transactors enables you to add new functionality to `rippled`. This tutorial walks through coding transactors, but you'll have to go through the amendment process to add it to XRPL. See: [Contribute Code to the XRP Ledger](contribute-code.html).
|
||||
|
||||
Transactors follow a basic order of operations:
|
||||
|
||||
1. Access a _view_ into a serialized type ledger entry (SLE).
|
||||
2. Update, erase, or insert values in the _view_.
|
||||
3. Apply the finalized changes from the _view_ to the ledger.
|
||||
|
||||
**Note:** _Views_ are sandboxes into ledgers. Transactors make all necessary error checks and changes in sandboxes, not directly on the ledger. After values are finalized, changes are applied atomically to the ledger.
|
||||
|
||||
This tutorial uses the existing `CreateCheck` transactor as an example. You can view the source files here:
|
||||
|
||||
- [Header File](https://github.com/XRPLF/rippled/blob/master/src/ripple/app/tx/impl/CreateCheck.h)
|
||||
- [CPP File](https://github.com/XRPLF/rippled/blob/master/src/ripple/app/tx/impl/CreateCheck.cpp)
|
||||
|
||||
|
||||
## Header File
|
||||
|
||||
Create a header file in this format:
|
||||
|
||||
```c++
|
||||
namespace ripple {
|
||||
|
||||
class CreateCheck : public Transactor
|
||||
{
|
||||
public:
|
||||
static constexpr ConsequencesFactoryType ConsequencesFactory{Normal};
|
||||
|
||||
explicit CreateCheck(ApplyContext& ctx) : Transactor(ctx)
|
||||
{
|
||||
}
|
||||
|
||||
static NotTEC
|
||||
preflight(PreflightContext const& ctx);
|
||||
|
||||
static TER
|
||||
preclaim(PreclaimContext const& ctx);
|
||||
|
||||
TER
|
||||
doApply() override;
|
||||
};
|
||||
|
||||
} // namespace ripple
|
||||
```
|
||||
|
||||
Initializing the transactor with `ApplyContext` gives it access to:
|
||||
|
||||
- The transaction that triggered the transactor.
|
||||
- A view of the SLE.
|
||||
- A journal to log errors.
|
||||
|
||||
|
||||
## CPP File
|
||||
|
||||
### 1. Add a `preflight` function.
|
||||
|
||||
The `preflight` function checks for errors in the transaction itself before accessing the ledger. It should reject invalid and incorrectly formed transactions.
|
||||
|
||||
- `PreflightContext` doesn't have a view of the ledger.
|
||||
- Use bracket notation to retrieve fields from ledgers and transactions:
|
||||
|
||||
auto const curExpiration = (*sle*)[~sfExpiration];
|
||||
(*sle)[sfBalance] = (*sle)[sfBalance] + reqDelta;
|
||||
|
||||
**Note:** The `~` symbol returns an optional type.
|
||||
|
||||
- You can view ledger and transaction schemas here:
|
||||
- [`LedgerFormats.cpp`](https://github.com/XRPLF/rippled/blob/master/src/ripple/protocol/impl/LedgerFormats.cpp)
|
||||
- [`TxFormats.cpp`](https://github.com/XRPLF/rippled/blob/master/src/ripple/protocol/impl/TxFormats.cpp)
|
||||
|
||||
- `rippled` summarizes transaction results with result codes. See: [Transaction Results](transaction-results.html)
|
||||
|
||||
```c++
|
||||
CreateCheck::preflight(PreflightContext const& ctx)
|
||||
{
|
||||
// Check if this amendment functionality is enabled on the network.
|
||||
if (!ctx.rules.enabled(featureChecks))
|
||||
return temDISABLED;
|
||||
|
||||
NotTEC const ret{preflight1(ctx)};
|
||||
if (!isTesSuccess(ret))
|
||||
return ret;
|
||||
|
||||
if (ctx.tx.getFlags() & tfUniversalMask)
|
||||
{
|
||||
// There are no flags (other than universal) for CreateCheck yet.
|
||||
JLOG(ctx.j.warn()) << "Malformed transaction: Invalid flags set.";
|
||||
return temINVALID_FLAG;
|
||||
}
|
||||
if (ctx.tx[sfAccount] == ctx.tx[sfDestination])
|
||||
{
|
||||
// They wrote a check to themselves.
|
||||
JLOG(ctx.j.warn()) << "Malformed transaction: Check to self.";
|
||||
return temREDUNDANT;
|
||||
}
|
||||
|
||||
{
|
||||
STAmount const sendMax{ctx.tx.getFieldAmount(sfSendMax)};
|
||||
if (!isLegalNet(sendMax) || sendMax.signum() <= 0)
|
||||
{
|
||||
JLOG(ctx.j.warn()) << "Malformed transaction: bad sendMax amount: "
|
||||
<< sendMax.getFullText();
|
||||
return temBAD_AMOUNT;
|
||||
}
|
||||
|
||||
if (badCurrency() == sendMax.getCurrency())
|
||||
{
|
||||
JLOG(ctx.j.warn()) << "Malformed transaction: Bad currency.";
|
||||
return temBAD_CURRENCY;
|
||||
}
|
||||
}
|
||||
|
||||
if (auto const optExpiry = ctx.tx[~sfExpiration])
|
||||
{
|
||||
if (*optExpiry == 0)
|
||||
{
|
||||
JLOG(ctx.j.warn()) << "Malformed transaction: bad expiration";
|
||||
return temBAD_EXPIRATION;
|
||||
}
|
||||
}
|
||||
|
||||
return preflight2(ctx);
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
### 2. Add a `preclaim` function.
|
||||
|
||||
The `preclaim` function checks for errors that require viewing information on the current ledger.
|
||||
|
||||
- If this step returns a result code of `tesSUCCESS` or any `tec` result, the transaction will be queued and broadcast to peers.
|
||||
|
||||
```c++
|
||||
CreateCheck::preclaim(PreclaimContext const& ctx)
|
||||
{
|
||||
AccountID const dstId{ctx.tx[sfDestination]};
|
||||
|
||||
// Use the `keylet` function to get the key of the SLE. Views have either `read` or `peek` access.
|
||||
// `peek` access allows the developer to modify the SLE returned.
|
||||
auto const sleDst = ctx.view.read(keylet::account(dstId));
|
||||
if (!sleDst)
|
||||
{
|
||||
JLOG(ctx.j.warn()) << "Destination account does not exist.";
|
||||
return tecNO_DST;
|
||||
}
|
||||
|
||||
auto const flags = sleDst->getFlags();
|
||||
|
||||
// Check if the destination has disallowed incoming checks
|
||||
if (ctx.view.rules().enabled(featureDisallowIncoming) &&
|
||||
(flags & lsfDisallowIncomingCheck))
|
||||
return tecNO_PERMISSION;
|
||||
|
||||
if ((flags & lsfRequireDestTag) && !ctx.tx.isFieldPresent(sfDestinationTag))
|
||||
{
|
||||
// The tag is basically account-specific information we don't
|
||||
// understand, but we can require someone to fill it in.
|
||||
JLOG(ctx.j.warn()) << "Malformed transaction: DestinationTag required.";
|
||||
return tecDST_TAG_NEEDED;
|
||||
}
|
||||
|
||||
{
|
||||
STAmount const sendMax{ctx.tx[sfSendMax]};
|
||||
if (!sendMax.native())
|
||||
{
|
||||
// The currency may not be globally frozen
|
||||
AccountID const& issuerId{sendMax.getIssuer()};
|
||||
if (isGlobalFrozen(ctx.view, issuerId))
|
||||
{
|
||||
JLOG(ctx.j.warn()) << "Creating a check for frozen asset";
|
||||
return tecFROZEN;
|
||||
}
|
||||
// If this account has a trustline for the currency, that
|
||||
// trustline may not be frozen.
|
||||
//
|
||||
// Note that we DO allow create check for a currency that the
|
||||
// account does not yet have a trustline to.
|
||||
AccountID const srcId{ctx.tx.getAccountID(sfAccount)};
|
||||
if (issuerId != srcId)
|
||||
{
|
||||
// Check if the issuer froze the line
|
||||
auto const sleTrust = ctx.view.read(
|
||||
keylet::line(srcId, issuerId, sendMax.getCurrency()));
|
||||
if (sleTrust &&
|
||||
sleTrust->isFlag(
|
||||
(issuerId > srcId) ? lsfHighFreeze : lsfLowFreeze))
|
||||
{
|
||||
JLOG(ctx.j.warn())
|
||||
<< "Creating a check for frozen trustline.";
|
||||
return tecFROZEN;
|
||||
}
|
||||
}
|
||||
if (issuerId != dstId)
|
||||
{
|
||||
// Check if dst froze the line.
|
||||
auto const sleTrust = ctx.view.read(
|
||||
keylet::line(issuerId, dstId, sendMax.getCurrency()));
|
||||
if (sleTrust &&
|
||||
sleTrust->isFlag(
|
||||
(dstId > issuerId) ? lsfHighFreeze : lsfLowFreeze))
|
||||
{
|
||||
JLOG(ctx.j.warn())
|
||||
<< "Creating a check for destination frozen trustline.";
|
||||
return tecFROZEN;
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
if (hasExpired(ctx.view, ctx.tx[~sfExpiration]))
|
||||
{
|
||||
JLOG(ctx.j.warn()) << "Creating a check that has already expired.";
|
||||
return tecEXPIRED;
|
||||
}
|
||||
return tesSUCCESS;
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
### 3. Add a `doApply()` function.
|
||||
|
||||
The `doApply()` function has read/write access, enabling you to modify the ledger.
|
||||
|
||||
```c++
|
||||
CreateCheck::doApply()
|
||||
{
|
||||
auto const sle = view().peek(keylet::account(account_));
|
||||
if (!sle)
|
||||
return tefINTERNAL;
|
||||
|
||||
// A check counts against the reserve of the issuing account, but we
|
||||
// check the starting balance because we want to allow dipping into the
|
||||
// reserve to pay fees.
|
||||
{
|
||||
STAmount const reserve{
|
||||
view().fees().accountReserve(sle->getFieldU32(sfOwnerCount) + 1)};
|
||||
|
||||
if (mPriorBalance < reserve)
|
||||
return tecINSUFFICIENT_RESERVE;
|
||||
}
|
||||
|
||||
// Note that we use the value from the sequence or ticket as the
|
||||
// Check sequence. For more explanation see comments in SeqProxy.h.
|
||||
std::uint32_t const seq = ctx_.tx.getSeqProxy().value();
|
||||
Keylet const checkKeylet = keylet::check(account_, seq);
|
||||
auto sleCheck = std::make_shared<SLE>(checkKeylet);
|
||||
|
||||
sleCheck->setAccountID(sfAccount, account_);
|
||||
AccountID const dstAccountId = ctx_.tx[sfDestination];
|
||||
sleCheck->setAccountID(sfDestination, dstAccountId);
|
||||
sleCheck->setFieldU32(sfSequence, seq);
|
||||
sleCheck->setFieldAmount(sfSendMax, ctx_.tx[sfSendMax]);
|
||||
if (auto const srcTag = ctx_.tx[~sfSourceTag])
|
||||
sleCheck->setFieldU32(sfSourceTag, *srcTag);
|
||||
if (auto const dstTag = ctx_.tx[~sfDestinationTag])
|
||||
sleCheck->setFieldU32(sfDestinationTag, *dstTag);
|
||||
if (auto const invoiceId = ctx_.tx[~sfInvoiceID])
|
||||
sleCheck->setFieldH256(sfInvoiceID, *invoiceId);
|
||||
if (auto const expiry = ctx_.tx[~sfExpiration])
|
||||
sleCheck->setFieldU32(sfExpiration, *expiry);
|
||||
|
||||
view().insert(sleCheck);
|
||||
|
||||
auto viewJ = ctx_.app.journal("View");
|
||||
// If it's not a self-send (and it shouldn't be), add Check to the
|
||||
// destination's owner directory.
|
||||
if (dstAccountId != account_)
|
||||
{
|
||||
auto const page = view().dirInsert(
|
||||
keylet::ownerDir(dstAccountId),
|
||||
checkKeylet,
|
||||
describeOwnerDir(dstAccountId));
|
||||
|
||||
JLOG(j_.trace()) << "Adding Check to destination directory "
|
||||
<< to_string(checkKeylet.key) << ": "
|
||||
<< (page ? "success" : "failure");
|
||||
|
||||
if (!page)
|
||||
return tecDIR_FULL;
|
||||
|
||||
sleCheck->setFieldU64(sfDestinationNode, *page);
|
||||
}
|
||||
|
||||
{
|
||||
auto const page = view().dirInsert(
|
||||
keylet::ownerDir(account_),
|
||||
checkKeylet,
|
||||
describeOwnerDir(account_));
|
||||
|
||||
JLOG(j_.trace()) << "Adding Check to owner directory "
|
||||
<< to_string(checkKeylet.key) << ": "
|
||||
<< (page ? "success" : "failure");
|
||||
|
||||
if (!page)
|
||||
return tecDIR_FULL;
|
||||
|
||||
sleCheck->setFieldU64(sfOwnerNode, *page);
|
||||
}
|
||||
// If we succeeded, the new entry counts against the creator's reserve.
|
||||
adjustOwnerCount(view(), sle, 1, viewJ);
|
||||
return tesSUCCESS;
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
## Additional Functions
|
||||
|
||||
You can add more helper functions to your custom transactor as necessary. There are a few special functions that are relevant in special cases.
|
||||
|
||||
|
||||
### `calculateBaseFee`
|
||||
|
||||
Most transactions inherit the default [reference transaction cost](transaction-cost.html). However, if your transactor needs to define a non-standard transaction cost, you can replace the transactor's `calculateBaseFee` method with a custom one.
|
||||
|
||||
The following example shows how `EscrowFinish` transactions charge an additional cost on conditional escrows based on the size of the fulfillment:
|
||||
|
||||
```c++
|
||||
XRPAmount
|
||||
EscrowFinish::calculateBaseFee(ReadView const& view, STTx const& tx)
|
||||
{
|
||||
XRPAmount extraFee{0};
|
||||
|
||||
if (auto const fb = tx[~sfFulfillment])
|
||||
{
|
||||
extraFee += view.fees().base * (32 + (fb->size() / 16));
|
||||
}
|
||||
|
||||
return Transactor::calculateBaseFee(view, tx) + extraFee;
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
### `makeTxConsequences`
|
||||
|
||||
`rippled` uses a [`TxConsequences`](https://github.com/XRPLF/rippled/blob/master/src/ripple/app/tx/applySteps.h#L41-L44) class to describe the outcome to an account when applying a transaction. It tracks the fee, maximum possible XRP spent, and how many sequence numbers are consumed by the transaction. There are three types of consequences:
|
||||
|
||||
- **Normal:** The transactor doesn't affect transaction signing and _only_ consumes an XRP fee. Transactions that spend XRP beyond the fee aren't considered normal.
|
||||
- **Blocker:** The transactor affects transaction signing, preventing valid transactions from queueing behind it.
|
||||
- **Custom:** The transactor needs to do additional work to determination consequences.
|
||||
|
||||
The `makeTxConsequences` function enables you to create custom consequences for situations such as:
|
||||
|
||||
- Payments sending XRP.
|
||||
- Tickets consuming more than one sequence number.
|
||||
- Transactions that are normal or blockers, depending on flags or fields set.
|
||||
|
||||
**Note:** `TxConsequences` only affects the [transaction queue](transaction-queue.html). If a transaction is likely to claim a fee when applied to the ledger, it will be broadcast to peers. If it's not likely to claim a fee, or that can't be determined, it won't be broadcast.
|
||||
|
||||
|
||||
```c++
|
||||
SetAccount::makeTxConsequences(PreflightContext const& ctx)
|
||||
{
|
||||
// The SetAccount may be a blocker, but only if it sets or clears
|
||||
// specific account flags.
|
||||
auto getTxConsequencesCategory = [](STTx const& tx) {
|
||||
if (std::uint32_t const uTxFlags = tx.getFlags();
|
||||
uTxFlags & (tfRequireAuth | tfOptionalAuth))
|
||||
return TxConsequences::blocker;
|
||||
|
||||
if (auto const uSetFlag = tx[~sfSetFlag]; uSetFlag &&
|
||||
(*uSetFlag == asfRequireAuth || *uSetFlag == asfDisableMaster ||
|
||||
*uSetFlag == asfAccountTxnID))
|
||||
return TxConsequences::blocker;
|
||||
|
||||
if (auto const uClearFlag = tx[~sfClearFlag]; uClearFlag &&
|
||||
(*uClearFlag == asfRequireAuth || *uClearFlag == asfDisableMaster ||
|
||||
*uClearFlag == asfAccountTxnID))
|
||||
return TxConsequences::blocker;
|
||||
|
||||
return TxConsequences::normal;
|
||||
};
|
||||
|
||||
return TxConsequences{ctx.tx, getTxConsequencesCategory(ctx.tx)};
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
## Next Steps
|
||||
|
||||
Re-compile the server with your new transactor and test it in [stand-alone mode](use-stand-alone-mode.html). If you coded the transactor behind an amendment, you can [force-enable](test-amendments.html) the feature using the config file.
|
||||
@@ -0,0 +1,168 @@
|
||||
---
|
||||
html: contribute-documentation.html
|
||||
parent: resources.html
|
||||
blurb: XRP Ledgerドキュメントのコントリビューションガイドです。
|
||||
---
|
||||
# ドキュメントへの貢献
|
||||
|
||||
XRP Ledger開発者ポータルへの貢献を検討いただきありがとうございます！
|
||||
|
||||
|
||||
私たちは、あなたが興味を持ってくださっていることにとても感動しています。XRP Ledger(XRPL)へ貢献することは、XRPLついて学ぶ素晴らしい機会です。
|
||||
|
||||
私たちはあなたのプルリクエストを喜んでレビューします。プロセスをできるだけ円滑に進めるため、このドキュメントを読み、記載されているガイドラインに従ってください。
|
||||
|
||||
## 当サイトについて
|
||||
|
||||
XRPL Dev Portalでは、開発者が開発を開始するためのサンプルコードやその他の情報を含む、XRP Ledgerの包括的なドキュメントを提供しています。
|
||||
|
||||
本プロジェクトの公式リポジトリは<https://github.com/XRPLF/xrpl-dev-portal>となっています。投稿の著作権はそれぞれの投稿者に帰属しますが、MIT[ライセンス](https://github.com/XRPLF/xrpl-dev-portal/blob/master/LICENSE)の下で提供されなければなりません。
|
||||
|
||||
|
||||
|
||||
## リポジトリの構成
|
||||
|
||||
- [assets/](https://github.com/XRPLF/xrpl-dev-portal/tree/master/assets) - サイトのテンプレートで使用される静的ファイル。
|
||||
- [content/](https://github.com/XRPLF/xrpl-dev-portal/tree/master/content) - ドキュメントを構築するために使用されるソースファイル。ほとんどがMarkdownです。
|
||||
- [content/\_code-samples/](https://github.com/XRPLF/xrpl-dev-portal/tree/master/content/_code-samples) - ドキュメントで使用または参照されているコードサンプル。可能な限り、これらは完全に機能する/実行可能なスクリプトです。
|
||||
- [content/\_img-sources/](https://github.com/XRPLF/xrpl-dev-portal/tree/master/content/_img-sources) - ドキュメントで使用されている画像の元ファイル。`.uxf`ファイルは[Umlet](https://www.umlet.com/)で作成されたダイアグラムです。
|
||||
- [content/\_snippets/](https://github.com/XRPLF/xrpl-dev-portal/tree/master/content/_snippets) - Dactylプリプロセッサを使用して、他のコンテンツファイルに挿入される再利用可能なMarkdownテキストの断片。
|
||||
- [img/](https://github.com/XRPLF/xrpl-dev-portal/tree/master/img) - ドキュメントコンテンツで使用される画像。
|
||||
- [template/](https://github.com/XRPLF/xrpl-dev-portal/tree/master/template) - HTMLを構築するためのテンプレートファイル。
|
||||
- [tool/](https://github.com/XRPLF/xrpl-dev-portal/tree/master/tool) - フィルター、スタイルチェッカー・ルール等のスクリプト。
|
||||
- [styles/](https://github.com/XRPLF/xrpl-dev-portal/tree/master/styles) - assetsフォルダにCSSファイルを生成するための元ファイル(SCSS)。
|
||||
- [`dactyl-config.yml`](https://github.com/XRPLF/xrpl-dev-portal/blob/master/dactyl-config.yml) - サイトのメタデータを含むメイン設定ファイル。設定ファイルのフォーマットについては、[設定フォーマット](#設定ファイルのフォーマット)を参照してください。
|
||||
|
||||
## プルリクエストが承認されるための条件
|
||||
|
||||
レビューやマージが承認される前に、それぞれのプルリクエストは以下の条件を満たしていなければなりません。
|
||||
- インテグレーションテストに合格すること。
|
||||
- レビューの準備が整うまで、[Draft](https://github.blog/2019-02-14-introducing-draft-pull-requests/)としてください。
|
||||
- このリポジトリの[コード規約](https://github.com/XRPLF/xrpl-dev-portal/blob/master/CODE_OF_CONDUCT.ja.md)を遵守してください。
|
||||
|
||||
## Dactylのセットアップ
|
||||
|
||||
ポータルは[Dactyl](https://github.com/ripple/dactyl)を使用して構築されています。
|
||||
|
||||
Dactylには[Python 3](https://python.org/)が必要です。[pip](https://pip.pypa.io/en/stable/)を使ってインストールしてください：
|
||||
|
||||
```
|
||||
pip3 install dactyl
|
||||
```
|
||||
|
||||
## サイトの構築
|
||||
|
||||
このリポジトリでは、[**Dactyl**](https://github.com/ripple/dactyl)を使用して、すべてのドキュメントのHTMLをビルドしています。[Dactylのセットアップ](#dactylのセットアップ)を行った後、プロジェクトのルートディレクトリからサイトをビルドすることができます。
|
||||
|
||||
```
|
||||
dactyl_build
|
||||
```
|
||||
|
||||
生成されたコンテンツは`out/`ディレクトリに出力されます。これらのコンテンツはウェブブラウザでファイルとして開いたり、ウェブサーバで静的コンテンツとして扱うことができます。
|
||||
|
||||
ルートディレクトリからリンクチェックやスタイルチェックを実行することもできます。
|
||||
|
||||
リンクチェックは出力フォルダを空にしてからビルドしてください。
|
||||
|
||||
```
|
||||
dactyl_link_checker
|
||||
```
|
||||
|
||||
スタイルチェックは実験的なものです。
|
||||
|
||||
```
|
||||
dactyl_style_checker
|
||||
```
|
||||
|
||||
## 設定ファイルのフォーマット
|
||||
|
||||
このリポジトリでは、`dactyl-config.yml`ファイルのメタデータとページの[frontmatter](https://dactyl.link/frontmatter.html)を使って、ヘッダー、フッター、サイドバー、パンくずリストなどのナビゲーション要素を生成します。
|
||||
|
||||
新しいページを追加する場合、`dactyl-config.yml`ファイルのpages配列の適切な位置に追加する必要があります。追加例は次のようになります。
|
||||
|
||||
```yaml
|
||||
- md: concepts/the-rippled-server/the-rippled-server.md
|
||||
targets:
|
||||
- en
|
||||
- ja # 翻訳コンテンツがない場合、全てのターゲットを対象とします。
|
||||
```
|
||||
|
||||
Markdownファイル自体は、以下のようなfrontmatterで始まる必要があります。
|
||||
|
||||
```yaml
|
||||
---
|
||||
html: the-rippled-server.html
|
||||
parent: concepts.html
|
||||
template: pagetype-category.html.jinja
|
||||
blurb: rippled is the core peer-to-peer server that manages the XRP Ledger. This section covers concepts that help you learn the "what" and "why" behind fundamental aspects of the rippled server.
|
||||
---
|
||||
```
|
||||
|
||||
少なくとも、ほとんどのページには `html`、`parent`、`blurb` フィールドが必要です(さらに、設定ファイルでは`md`フィールドと`targets`フィールドも必要です)。ここに、またはページの設定ファイルのエントリに任意のキーと値のペアを記述することができますが、以下のものが関係しています。
|
||||
|
||||
### 規約
|
||||
|
||||
ページを作成する際には、以下の規約に従ってください。
|
||||
|
||||
- HTMLのファイル名とMDのファイル名は、拡張子を除いて完全に一致していなければなりません。
|
||||
- ファイル名は"and"や"the"のような単語を含め、ページのタイトルと密接に一致する必要がありますが、スペースや句読点の代わりにハイフンを使用し、すべて小文字にする必要があります。例えば、`cash-a-check-for-an-exact-amount.md`のようにします。ページのタイトルを変更した場合は、ファイル名も変更する必要があります。(すでに別のURLで公開されている場合は、古いURLからのリダイレクトを残してください)
|
||||
- 常にh1ヘッダーでページを始めます。
|
||||
- ページの一番上のh1アンカーにはリンクせず、アンカーなしでページ自体にリンクしてください。これは翻訳時のリンク切れを防ぐのに役立ちます。以降のヘッダーへのリンクは問題ありません。
|
||||
- ページのタイトルに書式( _italics_ や`code font`など)を使わないでください。
|
||||
- Markdownファイルのテキストを折り返さないでください。
|
||||
- コードサンプルの場合、行は80文字以下になるようにしてください。
|
||||
- 迷ったら、[Ciro SantilliのMarkdownスタイルガイド (Writability Profile)](https://cirosantilli.com/markdown-style-guide/)に従ってください。
|
||||
- ランディングページはサブフォルダに入れ、フォルダと同じファイル名とします。例えば、"Accounts"ページグループのランディングページは`accounts/accounts.md`で、HTMLファイル名は`accounts.html`です。
|
||||
|
||||
**注意:** `index.md`は利用しないでください。
|
||||
|
||||
- Markdownやコードサンプルでは、インデントにタブ文字を使用しないでください。**JavaScript**のコードサンプルでは、1字下げにつき2個のスペースを使用してください。
|
||||
|
||||
### 技術用語
|
||||
|
||||
以下の単語やフレーズを説明通りに使用してください。
|
||||
|
||||
| 用語 | 避けるべき用語 | 備考 |
|
||||
|-------------------|----------------|-------|
|
||||
| API, APIs | API's, RPC | Application Programming Interface (アプリケーション・プログラミング・インターフェース)、ソフトウェアが他のソフトウェアと接続するための機能と定義のセット。 |
|
||||
| コアサーバ, XRP Ledgerのコアサーバ | `rippled` | `rippled`という名前は近い将来廃止される可能性が高いので、より一般的な名前で呼ぶことを推奨します。必要なときは、`rippled` をすべて小文字で、コードフォントで呼んでください。(発音は "リップルディー" で、"d" は UNIX の伝統に従って"daemon"を意味します)。
|
||||
| 金融機関 | 銀行, FI, PSP (決済サービスプロバイダ) | この用語は、_銀行_ や他の用語よりも幅広いビジネスを包含し、業界の専門用語の理解に依存しません。 |
|
||||
| レジャーエントリ | レジャーオブジェクト, ノード | XRP Ledgerの状態データ内の単一のオブジェクト。_レジャーオブジェクト_ という用語は、これらの一つを指すこともあれば、レジャー全体を指すこともあります。レジャーの状態データはグラフとして想定できるため、_ノード_ という用語が使われることもありましたが、_ノード_ には他の用途もあるため、混乱を招きます。 |
|
||||
| 流動性提供者 | マーケットメイカー | 2つの通貨または資産間の売買を提供し、多くの場合、取引間の価格差から利益を得る企業または個人。マーケットメーカーという用語は、法域によっては特定の法律上の定義があり、すべての同じ状況で適用されるとは限りません。 |
|
||||
| 悪質業者 | ハッカー | 個人、組織、または自動化されたツールなどによる、機密情報の取得、暗号化の解除、サービスの拒否、その他の安全なリソースへの攻撃を試みる可能性のあるもの。 |
|
||||
| PostgreSQL | Postgres | リレーショナルデータベース・ソフトウェアの特定のブランド。非公式な短いバージョンではなく、常に完全な名前を使用します。 |
|
||||
| オーダーブック | オファーブック | マッチングされ約定されるのを待っているトレード注文のコレクション。通常は取引レートごとにソートされています。 |
|
||||
| サーバ | ノード | サーバとは、ソフトウェアやハードウェアのことで、特にXRP Ledgerのピアツーピアネットワークに接続するものを指します。_ノード_ という用語はこの目的のために使われることもありますが、グラフのエントリやJavaScriptインタプリタであるNode.jsなど、他の意味でも多用されます。 |
|
||||
| ステーブルコイン発行者 | ゲートウェイ | 発行者とは、XRP Ledgerにおいてトークンを発行する組織です。ステーブルコインとは、発行者が外部の資産（例えば不換紙幣）に完全に裏付けられていることを約束しているトークンのことで、ステーブルコインの発行者は、その2つの資産を（場合によっては手数料を払って）交換する入出金操作を提供します。以前は、このユースケースを表現するために（特にリップル社によって）_ゲートウェイ_ という用語が使用されていましたが、業界の他の部分は代わりに _ステーブルコイン発行者_ を採用しました。 |
|
||||
| トランザクションコスト | トランザクション手数料 | XRP Ledgerでトランザクションを送信するために消費されるXRPの金額。これはトランザクションの`Fee`フィールドで指定されますが、_手数料_ という用語は誰かにお金を支払うことを意味するため、_コスト_ の方が望ましいです。 |
|
||||
| トークン | IOU, issuances, issues, 発行済み通貨 | XRP Ledgerのトークンは、_IOU_ という名前から想像されるように、レジャーの外部にある価値を表すことはできません。必要であれば、_代替可能トークン_ を使用して、非代替性トークン(NFT)と区別してください。 |
|
||||
| ウォレット | ウォレット | 文脈によっては、_ウォレット_ はハードウェア、ソフトウェア、暗号鍵ペア、またはオンラインサービスを指します。意味が明確になるように十分な文脈を提供するか、_キーペア_ や _クライアントアプリケーション_ などの別の表現を使用してください。 |
|
||||
| XRP | Ripple, リップル | XRPレジャーのネイティブデジタルアセットまたは暗号通貨。XRPはレジャーの外部の価値を表すトークンではありません。 |
|
||||
| XRP Ledger | Ripple, リップル, Ripple Network, リップルネットワーク, RCL | XRP Ledgerは、過去に様々な場面で「リップルネットワーク」や「リップルコンセンサスレジャー」あるいは「RCL」と呼ばれていました。これらの名称は、コアサーバーのリファレンス実装を開発しているRipple(Ripple Labs)の社名と類似しているため、紛らわしく、廃止されました。 |
|
||||
| XRPL | XRPL | _XRP Ledger_ の略です。_XRPL_ は不明瞭で、_XRP_ のタイプミスのように見えることがあります。 |
|
||||
|
||||
## Frontmatterのフィールド
|
||||
|
||||
このリポジトリのMarkdownファイルのfronmatterは任意のキーと値のペアを含むことができます。以下のフィールドは特定の用途や意味を持ちます。
|
||||
|
||||
| フィールド | 型 | 内容 |
|
||||
|:---------------------|:-----------------|:-----------------------------------|
|
||||
| `html` | String | ページの出力ファイル名。`.html`で終わり、ターゲット内で一意でなければなりません。翻訳版のページでは、ファイル名は英語版のページと同じにしてください。 |
|
||||
| `parent` | String | ページの「親」ページの`html`の値。このページがナビゲーションのどこに表示されるかを示します。 |
|
||||
| `blurb` | String | ページの要約文(プレーンテキストのみ)。ランディングページやソーシャルメディア上でリンクを展開する際のメタデータなど、さまざまな場所に表示されます。 |
|
||||
| `name` | String | ページ名(プレーンテキストのみ)。 Markdownコンテンツのあるファイルでは、Dactylがコンテンツの最初の行のヘッダーから自動的に検出できるため、これを省略する必要があります。これは通常、Markdownファイルを持たないランディングページやその他の特別なページでのみ提供されます。 |
|
||||
| `template` | String | このページで使用するテンプレートファイルのファイル名(`template/`ディレクトリ内)。ほとんどのページはデフォルトのテンプレートを使用します。`pagetype-category.html.jinja`テンプレートは最後に子ページのリストを表示します。特別な、あるいは特にユニークなレイアウトを持つページには、個別のテンプレートが必要になることがあります(通常、`page-`で始まります)。 |
|
||||
| `status` | String | XRP Ledgerメインネットでまだ有効になっていない修正に関連するページでは、`not_enabled`を使用します。これにより、ナビゲーションのページの横にツールチップ付きの"フラスコ"バッジが表示されます。 |
|
||||
| `nav_omit` | Boolean | ナビゲーション要素にこのページを表示しないようにするには`true`を使用します。 |
|
||||
| `top_nav_omit` | Boolean | ページトップのドロップダウンナビゲーションに表示しないようにするには、`true`を使用します。 |
|
||||
| `top_nav_level` | Number | トップナビのドロップダウンでページのインデントレベルを調整します。レベル`2`は、ドロップダウン内でその上のページの子のように表示されるようにインデントされます。 |
|
||||
| `sidebar` | String | U左右のサイドバーを非表示にするには、`disabled`を使用します(ページがベーステンプレートから派生したテンプレートを使用している場合)。 |
|
||||
| `fb_card` | String | Facebookでこのページへのリンクを展開する際に使用する画像のファイル名（`assets/img/`内）。 |
|
||||
| `twitter_card` | String | Twitterでこのページへのリンクを展開する際に使用する画像のファイル名（`assets/img/`内）。 |
|
||||
| `redirect_url` | String | `template: pagetype-redirect.html.jinja`でのみ使用します。ユーザがこのページに移動したときに、指定されたURLに自動的にリダイレクトします。 |
|
||||
| `cta_text` | String | このページにリンクする「call to action」ボタンに表示されるテキスト(特別なランディングページにて表示されます)。 |
|
||||
| `curated_anchors` | Array of Objects | 子ページと同様に、ランディングページに表示するためのアンカーです。配列の各オブジェクトは、人間が読める`name`フィールド(`"Available Modes"`など) と、リンク先のHTML IDを持つ`anchor`フィールド(`"#available-modes"`など)を持つ必要があります。 |
|
||||
| `skip_spell_checker` | Boolean | `true`を使用すると、Dactylのスタイルチェッカーがこのページのスペルチェックをスキップします。 |
|
||||
| `filters` | Array of Strings | このページで使用する追加フィルタのリストです。[フィルタ](https://github.com/ripple/dactyl/blob/master/README.md#filters)はPythonスクリプトで、ページ内容の事前または事後の追加処理を行います。 |
|
||||
| `canonical_url` | String | クエリパラメータを受け取るページの正規URLを提供します。検索エンジンやその他のツールは、ページにリンクする際にこれを使用する可能性があります。 |
|
||||
| `embed_xrpl_js` | Boolean | 最新版の[xrpl.js](https://js.xrpl.org)をこのページで読み込むには`true`を使用してください。 |
|
||||
@@ -0,0 +1,171 @@
|
||||
---
|
||||
html: contribute-documentation.html
|
||||
parent: resources.html
|
||||
blurb: Contribution guides for XRP Ledger documentation.
|
||||
---
|
||||
# Contribute Documentation
|
||||
|
||||
Thanks for considering a contribution to the XRP Ledger Developer Portal!
|
||||
|
||||
We're thrilled you're interested and your help is greatly appreciated. Contributing is a great way to learn about the XRP Ledger (XRPL).
|
||||
|
||||
We are happy to review your pull requests. To make the process as smooth as possible, please read this document and follow the stated guidelines.
|
||||
|
||||
|
||||
## About This Site
|
||||
|
||||
The XRPL Dev Portal provides comprehensive documentation of the the XRP Ledger, including sample code and other information for developers to start building.
|
||||
|
||||
The official source repository for the site is at <https://github.com/XRPLF/xrpl-dev-portal>. Contributions are copyright their respective contributors, but must be provided under the MIT [LICENSE](https://github.com/XRPLF/xrpl-dev-portal/blob/master/LICENSE).
|
||||
|
||||
|
||||
|
||||
## Repository Layout
|
||||
|
||||
- [assets/](https://github.com/XRPLF/xrpl-dev-portal/tree/master/assets) - Static files used by the site's templates.
|
||||
- [content/](https://github.com/XRPLF/xrpl-dev-portal/tree/master/content) - Source files used to build the documentation. Mostly in Markdown.
|
||||
- [content/\_code-samples/](https://github.com/XRPLF/xrpl-dev-portal/tree/master/content/_code-samples) - Code samples used or referenced by the documentation. Where possible, these are fully functional / executable scripts.
|
||||
- [content/\_img-sources/](https://github.com/XRPLF/xrpl-dev-portal/tree/master/content/_img-sources) - Source files for images used in the documentation. Any `.uxf` files are diagrams made with [Umlet](https://www.umlet.com/).
|
||||
- [content/\_snippets/](https://github.com/XRPLF/xrpl-dev-portal/tree/master/content/_snippets) - Reusable chunks of Markdown text that are included in other content files, using the Dactyl preprocessor.
|
||||
- [img/](https://github.com/XRPLF/xrpl-dev-portal/tree/master/img) - Images used by the documentation contents.
|
||||
- [template/](https://github.com/XRPLF/xrpl-dev-portal/tree/master/template) - Template files for building the HTML outputs.
|
||||
- [tool/](https://github.com/XRPLF/xrpl-dev-portal/tree/master/tool) - Filters, style-checker rules, and other scripts.
|
||||
- [styles/](https://github.com/XRPLF/xrpl-dev-portal/tree/master/styles) - Source files (SCSS) to generate the CSS files in the assets folder.
|
||||
- [`dactyl-config.yml`](https://github.com/XRPLF/xrpl-dev-portal/blob/master/dactyl-config.yml) - Main config file, which contains the metadata for the site. For information on our conventions, see [Config Formatting](#config-formatting).
|
||||
|
||||
## Requirements for a Successful Pull Request
|
||||
|
||||
Before being considered for review or merging, each pull request must:
|
||||
- Pass continuous integration tests.
|
||||
- Be [marked as drafts](https://github.blog/2019-02-14-introducing-draft-pull-requests/) until they are ready for review.
|
||||
- Adhere to the [code of conduct](https://github.com/XRPLF/xrpl-dev-portal/blob/master/CODE_OF_CONDUCT.md) for this repository.
|
||||
|
||||
## Dactyl Setup
|
||||
|
||||
The portal is built using [Dactyl](https://github.com/ripple/dactyl).
|
||||
|
||||
Dactyl requires [Python 3](https://python.org/). Install it with [pip](https://pip.pypa.io/en/stable/):
|
||||
|
||||
```
|
||||
pip3 install dactyl
|
||||
```
|
||||
|
||||
## Building the Site
|
||||
|
||||
This repo uses [**Dactyl**](https://github.com/ripple/dactyl) to build HTML display versions of all the documentation. After you've done the [Dactyl Setup](#dactyl-setup), you can build the site from the project root directory:
|
||||
|
||||
```
|
||||
dactyl_build
|
||||
```
|
||||
|
||||
This outputs the generated contents to the `out/` directory. These contents can be opened in a web browser as files or served as static content by a web server.
|
||||
|
||||
You can also run link checking or style checking from the root directory.
|
||||
|
||||
Link checking should be run after emptying the output folder and then building:
|
||||
|
||||
```
|
||||
dactyl_link_checker
|
||||
```
|
||||
|
||||
Style checking is experimental:
|
||||
|
||||
```
|
||||
dactyl_style_checker
|
||||
```
|
||||
|
||||
## Config Formatting
|
||||
|
||||
The templates in this repository use metadata from the `dactyl-config.yml` file as well as the pages' [frontmatter](https://dactyl.link/frontmatter.html) to generate navigation elements in the site, including header, footer, sidebars, and breadcrumbs.
|
||||
|
||||
If you add a new page, you must add it to the appropriate page in the pages array of the `dactyl-config.yml` file. An example entry looks like this:
|
||||
|
||||
```yaml
|
||||
- md: concepts/the-rippled-server/the-rippled-server.md
|
||||
targets:
|
||||
- en
|
||||
- ja # Include in all targets unless you have a translation
|
||||
```
|
||||
|
||||
The Markdown file itself should start with a frontmatter stanza such as the following:
|
||||
|
||||
```yaml
|
||||
---
|
||||
html: the-rippled-server.html
|
||||
parent: concepts.html
|
||||
template: pagetype-category.html.jinja
|
||||
blurb: rippled is the core peer-to-peer server that manages the XRP Ledger. This section covers concepts that help you learn the "what" and "why" behind fundamental aspects of the rippled server.
|
||||
---
|
||||
```
|
||||
|
||||
Most pages should have `html`, `parent` and `blurb` fields in the frontmatter, and the `md` and `targets` fields in the config file. For a fill list
|
||||
|
||||
### Conventions
|
||||
|
||||
Use the following conventions when creating a page:
|
||||
|
||||
- The HTML filename and MD filename should match exactly except for the file extension.
|
||||
- The filenames should closely match the title of the page, including words like "and" and "the", but should be in all lowercase with hyphens instead of spaces and punctuation. For example, `cash-a-check-for-an-exact-amount.md`. If you change the title of a page, change the filename too. (If it has already been published at another URL, leave a redirect from the old URL.)
|
||||
- Always start a page with a h1 header.
|
||||
- Don't link to the top h1 anchor of a page, link to the page itself without an anchor. This helps prevent broken links in translation. It's OK to link to later headers.
|
||||
- Don't use any formatting (like _italics_ or `code font`) in the title of the page.
|
||||
- Don't hard-wrap text in Markdown files.
|
||||
- For code samples, try to keep lines no longer than 80 columns wide.
|
||||
- When in doubt, follow [Ciro Santilli's Markdown Style Guide (Writability Profile)](https://cirosantilli.com/markdown-style-guide/).
|
||||
- Landing pages should be in subfolders and should have the same filename as the folder. For example, the landing page of the "Accounts" page group should be `accounts/accounts.md` with the HTML filename `accounts.html`.
|
||||
|
||||
**Warning:** Don't use `index.md`.
|
||||
|
||||
- Don't use tab characters for indentation in Markdown or code samples. Use 4 spaces per indent, except in **JavaScript** code samples, which should use 2 spaces per indent.
|
||||
|
||||
### Terminology
|
||||
|
||||
Use the following words and phrases as described:
|
||||
|
||||
| Term | Terms to Avoid | Notes |
|
||||
|-------------------|----------------|-------|
|
||||
| API, APIs | API's, RPC | Application Programming Interface, a set of functions and definitions for software to connect to other software. |
|
||||
| core server, core XRP Ledger server | `rippled` | The `rippled` name is probably going to be retired in the near future, so it's better to refer to it by the more generic name. When necessary, refer to `rippled` in all lowercase and code font. (It's pronounced "ripple dee", and the "d" stands for "daemon" per UNIX tradition.)
|
||||
| financial institution | bank, FI, PSP (payment services provider) | This term encompasses a wider range of businesses than just _bank_ or other terms and does not rely on an understanding of industry jargon. |
|
||||
| ledger entry | ledger object, node | A single object inside the state data of the XRP Ledger. The term _ledger object_ could refer to one of these or to the whole ledger. The term _node_ was sometimes used for this case because the ledger's state data can be envisioned as a graph, but this is confusing because _node_ has other uses. |
|
||||
| liquidity provider | market maker | A business or individual who offers to exchange between two currencies or assets, often deriving income from the price differential between trades. The term _market maker_ has a specific legal definition in some jurisdictions and may not apply in all the same circumstances. |
|
||||
| malicious actor | hacker | A person, organization, or even an automated tool which might attempt to acquire secrets, break encryption, deny service, or otherwise attack a secure resource. |
|
||||
| a NFT | an NFT | A NFT object in the XRP Ledger tracks or represents a non-fungible token. Pronounced "nifty" and written _a NFT_ rather than _an NFT_. |
|
||||
| PostgreSQL | Postgres | A specific brand of relational database software. Always use the full name, not an informal short version. |
|
||||
| order book | orderbook, offer book | A collection of trade orders waiting to be matched and executed, typically sorted by exchange rate. Use two words. |
|
||||
| server | node | A server is software and/or hardware, especially the ones that connect to the XRP Ledger peer-to-peer network. The term _node_ is sometimes used for this purpose but is also overloaded with other meanings including entries in a graph and Node.js, a JavaScript interpreter. |
|
||||
| stablecoin issuer | gateway | An issuer is the organization that issues a token in the XRP Ledger. A stablecoin is a token where the issuer promises that it is fully backed by some outside asset (such as fiat currency), with the stablecoin issuer providing deposit and withdraw operations to convert between the two (possibly for a fee). Previously the term _gateway_ was used (especially by Ripple, the company) to describe this use case, but the rest of the industry adopted _stablecoin issuer_ instead. |
|
||||
| transaction cost | transaction fee | The amount of XRP burnt to send a transaction in the XRP Ledger. Even though this is specified in the `Fee` field of transactions, the term _fee_ implies that the money is paid to someone, so _cost_ is preferable. |_
|
||||
| trust line | trustline | Use two words. A trust line is a relationship between two accounts in the XRP Ledger that tracks a balance of tokens between those accounts. |
|
||||
| tokens | IOUs, issuances, issues, issued currencies | A token in the XRP ledger may not represent money owed outside of the ledger as the name _IOU_ implies. Specify _fungible tokens_ if necessary to distinguish from non-fungible tokens. |
|
||||
| wallet | wallet | Depending on the context, _wallet_ could refer to hardware, software, a cryptographic key pair, or an online service. Be sure to provide enough context that the meaning is clear, or use an alternative such as _key pair_ or _client application_. |
|
||||
| WebSocket | web socket, Websockets | A two way protocol for communication on the web. Always singular and in CamelCase. |
|
||||
| XRP | XRPs, ripples | The native digital asset, or cryptocurrency, of the XRP Ledger. XRP is not a token. |
|
||||
| the XRP Ledger | XRP Ledger (no the), Ripple, Ripple Network, RCL | The XRP Ledger was called _the Ripple network_ and the _Ripple Consensus Ledger_ or _RCL_ at various times in the past. These names were confusing and have been retired because of their similarity to the name of the company, Ripple (formerly Ripple Labs) which develops the reference implementation of the core server. |
|
||||
| XRPL | XRPL | Short for _XRP Ledger_. As much as possible, spell out _XRP Ledger_ instead; _XRPL_ is cryptic and looks like it could be a typo for _XRP_. |
|
||||
|
||||
## Frontmatter Fields
|
||||
|
||||
The fronmatter for a Markdown file in this repo can contain arbitrary key-value pairs; the config file entry for the page can add to those or override them. The following fields have specific uses or meaning:
|
||||
|
||||
| Field | Type | Contents |
|
||||
|:---------------------|:-----------------|:-----------------------------------|
|
||||
| `html` | String | Output filename for the page. Should end in `.html` and MUST be unique within the target. For translated pages, leave the filename the same as the English version page. |
|
||||
| `parent` | String | The exact, unique `html` value of this page's "parent" page. Indicates where this page should appear in the navigation. |
|
||||
| `blurb` | String | Human-readable summary of the page. (Plain text only.) Should be about 1 sentence long. This appears in various places, including landing pages and metadata used in unfurling links on social media. |
|
||||
| `name` | String | Human-readable page name. (Plain text only.) For files with Markdown content, you should omit this so that Dactyl can automatically detect it from a header on the first line of the contents instead. This is usually only provided on landing pages or other special pages with no Markdown source file. |
|
||||
| `template` | String | The filename of a template file to use (in the `template/` directory) for this page. Most pages should use the default template. The `pagetype-category.html.jinja` template shows a list of child pages at the end. Pages with special or particularly unique layouts may need individual templates (conventionally, starting with `page-`). |
|
||||
| `status` | String | Use the value `not_enabled` on pages relating to an amendment that is not yet enabled on the XRP Ledger mainnet. This displays a "flask" badge with a tooltip next to the page in the navigation. |
|
||||
| `nav_omit` | Boolean | Use `true` to cause this page not to appear in any navigation elements. |
|
||||
| `top_nav_omit` | Boolean | Use `true` to cause this page not to appear in the page top dropdown navigation. |
|
||||
| `top_nav_level` | Number | Adjust the indentation level for the page in the top nav dropdowns. Level `2` is indented to appear like a child of the page above it in the dropdown. |
|
||||
| `sidebar` | String | Use `disabled` to hide the left and right sidebars (if the page uses a template derived from the base template) |
|
||||
| `fb_card` | String | Filename of an image (in `assets/img/`) to use when unfurling links to this page on Facebook. |
|
||||
| `twitter_card` | String | Filename of an image (in `assets/img/`) to use when unfurling links to this page on Twitter. |
|
||||
| `redirect_url` | String | Use with `template: pagetype-redirect.html.jinja` only. Automatically redirect the user to the provided URL when they navigate to this page. |
|
||||
| `cta_text` | String | Text to appear in "call to action" buttons that link to this page (on special landings). |
|
||||
| `curated_anchors` | Array of Objects | A set of anchors in this page to show, similar to child pages, in landings. Each object in the array should have a human-readable `name` field (such as `"Available Modes"`) and an `anchor` field with the HTML ID to link to (such as `"#available-modes"`). |
|
||||
| `skip_spell_checker` | Boolean | Use `true` to make the Dactyl's style checker skip spell-checking this page. |
|
||||
| `filters` | Array of Strings | A list of additional filters to use on this page. [Filters](https://github.com/ripple/dactyl/blob/master/README.md#filters) are Python scripts that provide additional pre- or post-processing of page contents. |
|
||||
| `canonical_url` | String | Provides the canonical URL for a page that takes query parameters. Search engines and other tools may use this when linking to the page. |
|
||||
| `embed_xrpl_js` | Boolean | Use `true` to have the latest version of [xrpl.js](https://js.xrpl.org) loaded on the page. |
|
||||
@@ -0,0 +1,33 @@
|
||||
---
|
||||
html: creating-diagrams.html
|
||||
parent: contribute-documentation.html
|
||||
blurb: ライトモードとダークモードの設定で適切に動作する図を作成します。
|
||||
---
|
||||
# 図の作成
|
||||
|
||||
このサイトには、SVGの図をライト・ダークモード用に自動的に再カラーリングするコードが含まれています。これは単に画像を反転させるだけではありません。再カラーリングは（ボトムライトに見えないように）グラデーションを同じ方向に保ち、色をその逆ではなくテーマに合った同等なものに置き換えます。例えば、"Ripple blue"は、その逆のオレンジではなく、XRPLグリーンに再カラーリングされます。
|
||||
|
||||
|
||||
|
||||
テーマを意識した再カラーリングでは、図のSVG形式の単一のソースファイルを使用し、CSSを使用して現在のテーマ（明暗）に合わせて再カラーリングされた図を生成します。ユーザがテーマを変更すると、図は即座にそれに合わせて変更されます。
|
||||
|
||||
テーマに対応した図をドキュメントに含めるには、以下のような構文で`include_svg`フィルタを使用します。
|
||||
|
||||
```jinja
|
||||
{{ include_svg("img/anatomy-of-a-ledger-complete.svg", "図1：XRP Ledgerの要素") }}
|
||||
```
|
||||
|
||||
この構文の前後は空行にしてください。該当のSVGファイルは、リポジトリのトップレベルにある[`img/`](https://github.com/XRPLF/xrpl-dev-portal/tree/master/img)フォルダか、そのサブフォルダにあるはずです。2番目の引数は _表題_ で、ユーザが図の上にマウスを置いたときに表示されます。
|
||||
|
||||
作成されたSVGファイルはMarkdownファイルに直接挿入されます。1点制限事項として、箇条書きリストやテーブルのような他のMarkdown構造の中では使用することはできません。
|
||||
|
||||
> **注記:** フィルタのソースコードは[`tool/filter_include_svg.py`](https://github.com/XRPLF/xrpl-dev-portal/blob/master/tool/filter_include_svg.py)です。これは`lxml`がサイトを構築するための依存関係の一つである理由でもあります。
|
||||
|
||||
## Making Diagrams
|
||||
|
||||
図を作成する際には、再カラーリングが正しく適用されるように注意する必要があります。そうしないと、もう一方のテーマ用に再カラーリングしたときに、一部の要素が見えなくなる可能性があります(例えば、白地に白や黒地に黒など)。テーマを考慮したダイアグラムのコードは、[Umlet](https://www.umlet.com/)または[Google Draw](https://docs.google.com/drawings/)のいずれかを使用して作成され、SVGとしてエクスポートされた図をサポートしています。また、図を作成する際には、以下のガイドラインに従ってください。
|
||||
|
||||
- デフォルトでライトモード用の図を作成します。透明な背景色を使用してください。
|
||||
- テーマ対応ダイアグラムのコードがマッピングしている色のみを使用します。色の完全なリストを含む、このためのコードは[`styles/_diagrams.scss`](https://github.com/XRPLF/xrpl-dev-portal/blob/master/styles/_diagrams.scss)にあります。必要であれば、SCSSコードを拡張することで、新しい色を追加することができます。(作業が終わったら、CSSを再エクスポートすることを忘れないでください。[style README](https://github.com/XRPLF/xrpl-dev-portal/blob/master/styles/README.md)を参照してください)。
|
||||
- 可能な限り、埋め込みアイコン/画像の代わりにベクター図形を使用してください。画像の上にテキストを配置する必要がある場合は、テキスト要素に無地の背景を追加し、テーマがマッピングしている色のいずれかを使用してください。
|
||||
- テキストを含む透明な要素を、異なる背景色を持つ要素の上に重ねないでください。テキストを含む要素に直接背景色を適用してください。
|
||||
@@ -0,0 +1,33 @@
|
||||
---
|
||||
html: creating-diagrams.html
|
||||
parent: contribute-documentation.html
|
||||
blurb: Create diagrams that interact properly with light and dark mode settings.
|
||||
---
|
||||
# Creating Diagrams
|
||||
|
||||
The site contains code to automatically recolor SVG diagrams for light and dark mode. This is more than just inverting images. The recoloring keeps gradients going the same direction (so that things don't look bottom-lit) and replaces colors with equivalents that fit with the theme rather than their inverse. For example, "Ripple blue" gets recolored to XRPL green, not its inverse orange. Example:
|
||||
|
||||
|
||||
|
||||
Theme-aware recoloring uses a single source file in SVG format for diagrams, and produces diagrams that are recolored to match the current theme (light/dark) using CSS. If the user changes their theme, the diagrams immediately change to match it.
|
||||
|
||||
To include a theme-aware diagram in a document, use the `include_svg` filter with syntax such as the following:
|
||||
|
||||
```jinja
|
||||
{{ include_svg("img/anatomy-of-a-ledger-complete.svg", "Figure 1: XRP Ledger Elements") }}
|
||||
```
|
||||
|
||||
Leave empty lines before and after this syntax. The SVG file in question should be in the [`img/`](https://github.com/XRPLF/xrpl-dev-portal/tree/master/img) folder at the top level of the repo, or a subfolder of it. The second argument is _title text_, which appears when the user hovers their mouse over the diagram, and can also be used by other software (such as screen readers) to caption the diagram.
|
||||
|
||||
The resulting SVG file is inlined directly into the Markdown file. One limitation is that you can't use it inside other Markdown structures such as bulleted lists or tables.
|
||||
|
||||
> **Note:** The filter source code is [`tool/filter_include_svg.py`](https://github.com/XRPLF/xrpl-dev-portal/blob/master/tool/filter_include_svg.py). This is also the reason that `lxml` is one of the dependencies for building the site.
|
||||
|
||||
## Making Diagrams
|
||||
|
||||
You have to take care when creating diagrams so that the recoloring applies correctly; otherwise, some elements might be invisible (white-on-white or black-on-black, for example) when recolored for the other theme. The theme-aware diagrams code supports diagrams created using either [Umlet](https://www.umlet.com/) or [Google Draw](https://docs.google.com/drawings/) and exported as SVG. Additionally, you should follow these guidelines when making diagrams:
|
||||
|
||||
- Create diagrams for light mode by default. Use a transparent background color.
|
||||
- Only use colors that the theme-aware diagrams code has mappings for. The code for this, including the full list of colors, is in [`styles/_diagrams.scss`](https://github.com/XRPLF/xrpl-dev-portal/blob/master/styles/_diagrams.scss). If needed, you can add new colors by extending the SCSS code. (Don't forget to re-export the CSS when you're done. See the [styles README](https://github.com/XRPLF/xrpl-dev-portal/blob/master/styles/README.md).)
|
||||
- Use actual vector shapes instead of embedded icons/images whenever possible. If you need to put text on top of an image, add a solid background to the text element and use one of the colors the theme has mappings for.
|
||||
- Don't layer transparent elements containing text on top of elements with different background colors. Apply a background color directly to the element that contains the text.
|
||||
@@ -0,0 +1,79 @@
|
||||
---
|
||||
html: documentation-translations.html
|
||||
parent: contribute-documentation.html
|
||||
blurb: このウェブサイトにある文書の翻訳に貢献し、維持する方法を学びましょう。
|
||||
---
|
||||
# 翻訳
|
||||
|
||||
XRP Ledger Dev Portalは大部分が英語で書かれているため、一般的には英語版が最新かつ正確なバージョンです。しかしながら、XRP Ledgerのソフトウェアとコミュニティへのリーチを広げるために、このリポジトリには翻訳版のドキュメントも含まれています。私たちは、他の言語を理解するコミュニティのメンバーが、開発ポータルの内容を母国語で翻訳することを大いに歓迎します。
|
||||
|
||||
`dactyl-config.yml`には利用可能な言語ごとに"target"項目があります(現在、利用可能な言語は英語と日本語です)。このエントリには、次のようにテンプレートファイルで使用される文字列の定義が含まれます。
|
||||
|
||||
```yaml
|
||||
- name: en
|
||||
lang: en
|
||||
display_name: XRP Ledger Dev Portal
|
||||
# These github_ fields are used by the template's "Edit on GitHub" link.
|
||||
# Override them with --vars to change which fork/branch to edit.
|
||||
github_forkurl: https://github.com/XRPLF/xrpl-dev-portal
|
||||
github_branch: master
|
||||
strings:
|
||||
blog: "Blog"
|
||||
search: "Search site with Google..."
|
||||
bc_home: "Home"
|
||||
# ...
|
||||
```
|
||||
|
||||
また、トップレベルの`languages`リストもあり、サポートされている各言語が定義されています。各言語のショートコードは[IETF BCP47](https://tools.ietf.org/html/bcp47)に従ったショートコードでなければなりません。例えば、"en"は英語、"es"はスペイン語、"ja"は日本語、"zh-CN"は簡体字中国語、"zh-TW" は繁体字中国語 (台湾で使用) などです。`display_name`フィールドはその言語でネイティブに書かれた言語名を定義します。`prefix`フィールドはその言語のサイトへのハイパーリンクで使用する接頭辞を定義します。次に`languages`の定義例を示します。
|
||||
|
||||
```yaml
|
||||
languages:
|
||||
- code: en
|
||||
display_name: English
|
||||
prefix: "/"
|
||||
- code: ja
|
||||
display_name: 日本語
|
||||
prefix: "/ja/"
|
||||
```
|
||||
|
||||
同じ`dactyl-config.yml`ファイルには、XRP Ledger Dev Portalの各コンテンツページのエントリがあります。ページが翻訳されている場合、各翻訳ごとに個別の項目があり、その翻訳の“ターゲット"にリンクされています。ページがまだ翻訳されていない場合、すべてのターゲットで英語版が使用されます。(新しいページが英語のみ追加され、他の言語が提供されない場合、リンクチェッカーはそれをリンク切れとして報告します。)
|
||||
|
||||
ページを翻訳するということは、そのページのエントリを他の言語と分割するということです。ページのメタデータは`dactyl-config.yml`ファイルか、ページのMarkdownファイルの先頭にあるfrontmatterに設定します。
|
||||
|
||||
| フィールド | 備考 |
|
||||
|----------|------|
|
||||
| `html` | ページのHTMLファイル名。慣例により、これはすべての言語バージョンで同じであるべきです。 |
|
||||
| `md` | ページのMarkdownソースファイル。翻訳されたMarkdownソースファイルは英語版と同じファイル名を使用してください。ただし、拡張子は英語版の`.md`ではなく、`.{言語コード}.md`を使用してください。例えば、日本語の翻訳ファイルの拡張子は `.ja.md` です。 |
|
||||
| `blurb` | ページの簡単な要約。これは翻訳されるべきです。このテキストは、検索エンジン最適化のためのメタデータや、自動生成されるランディングページで使用されます。 |
|
||||
|
||||
`server_info`メソッドページの英語と日本語の記入例：
|
||||
|
||||
```yaml
|
||||
- md: references/http-websocket-apis/public-api-methods/server-info-methods/server_info.md
|
||||
targets:
|
||||
- en
|
||||
|
||||
- md: references/http-websocket-apis/public-api-methods/server-info-methods/server_info.ja.md
|
||||
targets:
|
||||
- ja
|
||||
```
|
||||
|
||||
翻訳されていないページの記入例：
|
||||
|
||||
```yaml
|
||||
- md: concepts/payment-system-basics/transaction-basics/source-and-destination-tags.md
|
||||
targets:
|
||||
- en
|
||||
- ja
|
||||
```
|
||||
|
||||
## 始めるにあたって
|
||||
|
||||
XRP Ledger Dev Portalをあなたの母国語に翻訳したい場合は、まず["What is the XRP Ledger?" file]({{target.github_forkurl}}/blob/{{target.github_branch}}/content/concepts/introduction/what-is-the-xrp-ledger.md)から始めてください。
|
||||
|
||||
このファイルを`xrp-ledger-overview.{言語コード}.md`として保存します。ここで`{言語コード}`は[IETF BCP47](https://tools.ietf.org/html/bcp47)の言語コードです。(例えば、スペイン語は"es"、日本語は"ja"、簡体字中国語は"zh-CN"、台湾で使われている繁体字中国語は"zh-TW"などです)。そして、あなたのファイルをこのリポジトリに追加する[プルリクエスト](https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/about-pull-requests)を作成してください。リポジトリメンテナの誰かが、サイトに言語を追加するために必要なその他の設定を手伝ってくれるでしょう。
|
||||
|
||||
Markdownコンテンツファイルでは、以下の規則に従ってください。
|
||||
|
||||
- 改行文字(`\n`)のみ（Unixスタイル）。キャリッジリターン文字(`\r`)は使用しないでください（Windowsスタイル）。
|
||||
- UTF-8エンコーディングを使用してください。バイトオーダーマークの使用は避けてください。
|
||||
@@ -0,0 +1,80 @@
|
||||
---
|
||||
html: documentation-translations.html
|
||||
parent: contribute-documentation.html
|
||||
blurb: Learn how to contribute and maintain translations of the documentation on this website.
|
||||
---
|
||||
# Translations
|
||||
|
||||
The XRP Ledger Dev Portal is mostly written in English, so the English version is generally the most up-to-date and accurate version. However, to broaden the reach of the XRP Ledger software and community, this repository also contains translated versions of the documentation. We strongly encourage members of the community who understand other languages to contribute translations of the dev portal contents in their native languages.
|
||||
|
||||
The `dactyl-config.yml` contains a "target" entry for each available language. (Currently, the available languages are English and Japanese.) This entry includes a dictionary of strings used in the template files. For example:
|
||||
|
||||
```yaml
|
||||
- name: en
|
||||
lang: en
|
||||
display_name: XRP Ledger Dev Portal
|
||||
# These github_ fields are used by the template's "Edit on GitHub" link.
|
||||
# Override them with --vars to change which fork/branch to edit.
|
||||
github_forkurl: https://github.com/XRPLF/xrpl-dev-portal
|
||||
github_branch: master
|
||||
strings:
|
||||
blog: "Blog"
|
||||
search: "Search site with Google..."
|
||||
bc_home: "Home"
|
||||
# ...
|
||||
```
|
||||
|
||||
There is also a top-level `languages` listing that defines some properties for each supported language. The short code for each language should be short code according to [IETF BCP47](https://tools.ietf.org/html/bcp47). For example, "en" for English, "es" for Spanish, "ja" for Japanese, "zh-CN" for Simplified Chinese, "zh-TW" for Traditional Chinese (as used in Taiwan), and so on. The `display_name` field defines the language's name as written natively in that language. The `prefix` field defines a prefix to be used in hyperlinks to that language's version of the site. Example `languages` definition:
|
||||
|
||||
```yaml
|
||||
languages:
|
||||
- code: en
|
||||
display_name: English
|
||||
prefix: "/"
|
||||
- code: ja
|
||||
display_name: 日本語
|
||||
prefix: "/ja/"
|
||||
```
|
||||
|
||||
The same `dactyl-config.yml` file contains an entry for each content page in the XRP Ledger Dev Portal. If a page has been translated, there is a separate entry for each translation, linked to the "target" for that translation. If a page has not yet been translated, the English version is used across all targets. (If a new page is added only to English and not other languages, the link checker reports that as a broken link.)
|
||||
|
||||
Translating a page means separating out the entry for that page in the other language. Here are some tips for translating the page's metadata, which can be in either the `dactyl-config.yml` file or the frontmatter at the top of the page's Markdown file:
|
||||
|
||||
| Field | Notes |
|
||||
|-------|-------|
|
||||
| `html` | The HTML file name of the page. By convention, this should be the same across all language versions. |
|
||||
| `md` | The Markdown source file for the page. Translated Markdown source files should use the same filename as the English-language version except that the file extension should be `.{language code}.md` instead of only `.md` for English. For example, Japanese translated files end in `.ja.md`. |
|
||||
| `blurb` | A short summary of the page. This should be translated. This text is used in metadata for search engine optimization and also on automatically-generated landing pages. |
|
||||
|
||||
|
||||
Example of English and Japanese entries for the `server_info` method page:
|
||||
|
||||
```yaml
|
||||
- md: references/http-websocket-apis/public-api-methods/server-info-methods/server_info.md
|
||||
targets:
|
||||
- en
|
||||
|
||||
- md: references/http-websocket-apis/public-api-methods/server-info-methods/server_info.ja.md
|
||||
targets:
|
||||
- ja
|
||||
```
|
||||
|
||||
Example entry for a page that isn't translated:
|
||||
|
||||
```yaml
|
||||
- md: concepts/payment-system-basics/transaction-basics/source-and-destination-tags.md
|
||||
targets:
|
||||
- en
|
||||
- ja
|
||||
```
|
||||
|
||||
## Where to Start
|
||||
|
||||
If you want to translate the XRP Ledger Dev Portal into your native language of choice, start with the ["What is the XRP Ledger?" page]({{target.github_forkurl}}/blob/{{target.github_branch}}/content/concepts/introduction/what-is-the-xrp-ledger.md), which introduces the core concepts behind the XRP Ledger.
|
||||
|
||||
Save the file as `what-is-the-xrp-ledger.{language code}.md`, where `{language code}` is the [IETF BCP47](https://tools.ietf.org/html/bcp47) language code. (For example, "es" for Spanish, "ja" for Japanese, "zh-CN" for Simplified Chinese, "zh-TW" for Traditional Chinese as used in Taiwan, and so on.) Then open a [pull request](https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/about-pull-requests) adding your file to this repository. One of the repository's maintainers can help with the other necessary setup to add the language to the site.
|
||||
|
||||
For the Markdown content files, please use the following conventions:
|
||||
|
||||
- Line-feed newline characters (`\n`) only (Unix style). Do not use carriage return (`\r`) characters (Windows style).
|
||||
- Use UTF-8 encoding. Avoid the use of Byte-order marks.
|
||||
@@ -0,0 +1,83 @@
|
||||
---
|
||||
html: tutorial-guidelines.html
|
||||
parent: contribute-documentation.html
|
||||
blurb: このサイトのチュートリアルの構成と、質の高いチュートリアルを投稿するためのガイドラインを学びましょう。
|
||||
---
|
||||
# チュートリアルガイドライン
|
||||
|
||||
私たちは、開発者がXRP Ledger上でのトランザクションやリクエストの仕組みを学ぶことができる、モジュール式のチュートリアルフレームワークを作成しています。開発者は、ビジネスソリューションについて学ぶためにモジュールを確認し、自身のアプリケーションでスクリプトを再利用することができます。
|
||||
|
||||
|
||||
# 根拠
|
||||
|
||||
開発者は次の2つのことを求めています。
|
||||
|
||||
1. 自分のアプリケーションにコピー＆ペーストできるコードのサンプル。
|
||||
2. 完全なAPIリファレンスのドキュメント。
|
||||
|
||||
コンセプトに関する情報は最小限としチュートリアルを完了するために必要な情報のみとしてください。背景やより深い理解のために、必要であれば、チュートリアルの最後にコンセプトに関するトピックへのリンクを提供してください。
|
||||
|
||||
チュートリアルプログラムは、マルコム・ノウルズが提唱する、社会人の学習を支援するための6つの前提に沿って構成されています。
|
||||
|
||||
1. 大人は、なぜ何かを学ぶ必要があるのかを知る必要があります。
|
||||
2. 大人は、経験を積み重ねる必要があります。
|
||||
3. 大人は、自分の学習に責任を感じる必要があります。
|
||||
4. 大人は、トレーニングが当面の問題を解決してくれるなら、学ぶ準備が整っています。
|
||||
5. 大人は、トレーニングが問題に焦点を当てたものであることを望みます。
|
||||
6. 大人は、動機づけが内発的にもたらされるときに最もよく学びます。
|
||||
|
||||
さらに、ラルフ・スメドレーの「人は楽しいときに最もよく学ぶ」という言葉も付け加えておきましょう。軽い気持ちで学ぶと、学習者をリラックスさせることができ、教材が抵抗なく頭に入ってくるのです。
|
||||
|
||||
|
||||
# サンプルコード vs タスク vs コンセプト vs チュートリアル
|
||||
|
||||
これまで、異なるタイプのドキュメントが _チュートリアル_ として表示されたり、境界線が曖昧なことがありました。ここでは、その違いを定義するのに役立ついくつかの比較を紹介します。
|
||||
|
||||
|
||||
## サンプルコード
|
||||
|
||||
サンプルコードとは、APIの機能を実装するためのベストプラクティスを示す、適切にコメントされたスニペットやアプリケーションのことです。サンプルコードはモジュール化されており、カスタマイズをほとんど必要とせず、再利用可能です。
|
||||
|
||||
サンプルコードは理想的です。なぜなら、上級者は通常、正式なチュートリアルがなくても、サンプルをスキャンしてすぐに使うことができるからです。また、他の人がチュートリアルの基礎として使うこともできます。サンプルコードの開発者は、自分の得意なことに集中することができ、テクニカルライターやサポート担当者は、サンプルを使って質の高いトレーニング資料を作成することができます。
|
||||
|
||||
|
||||
## タスク
|
||||
|
||||
タスクは、特定の目的を達成するためのステップバイステップの指示です。例えば、"Red Hat Linux Serverにrippledをインストールする"などです。タスクドキュメントはあまり教育的なものではありません。実装ごとに一度だけ実行されるタスクや、常におなじみのパターンに従うメンテナンスタスクが頻繁に記述されています。タスクはトラブルシューティングのガイダンスを示します。
|
||||
|
||||
|
||||
## コンセプト
|
||||
|
||||
コンセプトでは、API の要素やそれらがどのように動作するか、どのような場合にそれらを使用するかについて説明します。もしチュートリアルがプログラミングのタスクの前や途中に長い説明を必要とする場合、説明を新しいトピックに分けるか、既存のトピックにリンクして適切なコンテキストを設定する方法を検討してください。
|
||||
|
||||
例えば、3段落のコンテキストと1行のコードは、チュートリアルではなく、コンセプトとして扱うべきでしょう。
|
||||
|
||||
|
||||
## チュートリアル
|
||||
|
||||
チュートリアルは、機能を実装するためのベストプラクティスを示すサンプルコードから始まります。チュートリアルでは、コードの各ブロックの目的を説明しながら、開発のプロセスを段階的に進めていきます。
|
||||
|
||||
チュートリアルではさらに、ビジネス上の問題を解決するために、いくつかの機能を組み合わせます。チュートリアルでは、あるタスクを完了するための簡単な手順を説明します。そして、開発者がいくつかの異なるシナリオを試せるように修正を提案するかもしれません。チュートリアルは、ある限られた範囲の動作に焦点を当てているため、広範なトラブルシューティング情報を必要としないようにすべきです。
|
||||
|
||||
|
||||
## ユースケース
|
||||
|
||||
ユースケースでは、複数の機能を組み合わせて、ビジネス上の問題を解決する実用的なアプリケーションを作成する方法を説明します。ユースケースは、コンテキストを提供し、意思決定プロセスを支援し、実装の各ステップに適切なトピックへのリンクを提供します。
|
||||
|
||||
|
||||
# チュートリアルの構成要素
|
||||
|
||||
このセクションでは、XRPL.orgで使用されているチュートリアルモジュールの要素について説明します。
|
||||
|
||||
|
||||
## サンプルアプリケーション
|
||||
|
||||
XRPLチュートリアルのサンプルコードはモジュール式になっています。例えば、スクリプト1はテストアカウントの作成方法、XRP Ledgerへのアクセス方法、アカウント間でのXRP送金方法を示しています。それ以降のサンプルはスクリプト1の機能を再利用することができます。
|
||||
|
||||
ビジネス上の問題に対する実用的な解決策を示すために必要な、特定の最小限の関数コードを持つ新しいスクリプトを作成してください。サンプルは、ビジネスプロセスを説明するのに十分な動作を持つ逐次的なものでなければなりません。
|
||||
|
||||
たとえば、最初のNFTチュートリアルでは、NFTのミント、取得、バーンの方法を示します。次のチュートリアルでは、売りオファーの作成と受け入れ、買いオファーの作成と受け入れの方法を示します。
|
||||
|
||||
アプリケーションのUXは、トピックに関連するものでない限り、過度に重視しないでください。すべてのチュートリアルで、標準的な外観と操作感のCSSファイルを使用してください。
|
||||
|
||||
可能な限り、他のモジュールのコードを再利用してください。以前のモジュールの動作を変更する必要がある場合があります。関数名をオーバーロードするか、モジュールを修正して別の名前で保存してください。
|
||||
@@ -0,0 +1,83 @@
|
||||
---
|
||||
html: tutorial-guidelines.html
|
||||
parent: contribute-documentation.html
|
||||
blurb: Learn how this site's tutorials are structured and guidelines for contributing quality tutorials.
|
||||
---
|
||||
# Tutorial Guidelines
|
||||
|
||||
We are creating a modular tutorial framework that allows developers to learn how transactions and requests work on the XRP Ledger. Developers can review the modules to learn about business solutions, and potentially repurpose the scripts in their own applications.
|
||||
|
||||
|
||||
# Rationale
|
||||
|
||||
What a developer wants comes down to two things:
|
||||
|
||||
1. Sample code snippets they can copy and paste into their own applications.
|
||||
2. Complete API reference documentation.
|
||||
|
||||
Keep the conceptual information to a minimum – only the information necessary to complete the tutorial. For background or deeper understanding, provide links to the conceptual topics at the end of the tutorial, if needed.
|
||||
|
||||
Modular tutorials follow Malcolm Knowles’ six assumptions for designing adult learning:
|
||||
|
||||
1. Adults need to know why they need to learn something.
|
||||
2. Adults need to build on their experience.
|
||||
3. Adults have a need to feel responsible for their learning.
|
||||
4. Adults are ready to learn if training solves an immediate problem.
|
||||
5. Adults want their training to be problem focused.
|
||||
6. Adults learn best when motivation comes intrinsically.
|
||||
|
||||
Add into that Ralph Smedley’s quote, “We learn best in moments of enjoyment.” Taking a lighter touch helps to relax the learner so that the material flows into their brain with less resistance.
|
||||
|
||||
|
||||
# Sample Code vs. Tasks vs. Concepts vs. Tutorials
|
||||
|
||||
To date, there have been some blurred lines where different types of documentation show up as _Tutorials_. Here are some comparisons that help define the distinction.
|
||||
|
||||
|
||||
## Sample Code
|
||||
|
||||
Sample code is well commented snippets or applications that illustrate best practices for implementing a feature of the API. Sample code is modular and reusable with little customization required.
|
||||
|
||||
Sample code is desirable, because advanced users can typically scan the example and use it immediately without a formal tutorial. It can also be used by others as a basis for tutorials. Sample code developers can focus on what they do well, while technical writers and support personnel can use the samples to create quality training materials.
|
||||
|
||||
|
||||
## Tasks
|
||||
|
||||
Tasks are step-by-step instructions for how to accomplish a specific result. For example, “Installing rippled on a Red Hat Linux Server.” Task documentation is not intended to be particularly educational. It frequently describes tasks that are only performed one time per implementation, or maintenance tasks that always follow a familiar pattern. Tasks provide troubleshooting guidance, since there are likely variables that the user must adjust based on the specifics of their use case.
|
||||
|
||||
|
||||
## Concepts
|
||||
|
||||
Conceptual information describes elements of the API, how they work, and when to use them. If a tutorial requires lengthy explanations before or during the programming tasks, consider how you might separate the exposition into a new topic, or link to existing topics that set the proper context.
|
||||
|
||||
For example, three paragraphs of context and a single line of code would be a concept, not a tutorial.
|
||||
|
||||
|
||||
## Tutorials
|
||||
|
||||
Tutorials begin with sample code that illustrates best practices for implementing a feature. They take the developer step-by-step through the development process, explaining the purpose of each block of code.
|
||||
|
||||
Tutorials further combine a number of features to work together to solve a business problem. They describe the straightforward sunny day path to complete a task. Then, the tutorial might suggest modifications that let the developer try several different scenarios. Due to their focus on a certain limited scope of behavior, tutorials should not require extensive troubleshooting information.
|
||||
|
||||
|
||||
## Use Cases
|
||||
|
||||
Use cases describe how to pull together multiple features to create a practical application that solves a business problem. They provide context and assistance with the decision making process, then provide links to the appropriate topics for each step of implementation.
|
||||
|
||||
|
||||
# Tutorial Components
|
||||
|
||||
This section describes the elements of the modular tutorials used on XRPL.org.
|
||||
|
||||
|
||||
## Sample Application
|
||||
|
||||
XRPL tutorial code samples are modular in nature. For example, Script 1 demonstrates how to create a test account, access the XRP Ledger, and transfer XRP between accounts. Any further samples can reuse the functions in Script 1.
|
||||
|
||||
Create a new script with the specific, minimal function code required to demonstrate the practical solution to a business problem. The examples should be incremental, with just enough behaviors to illustrate a business process.
|
||||
|
||||
For example, the first NFT tutorial shows how to mint, retrieve, and burn an NFT. The next tutorial shows how to create and accept a sell offer, and create and accept a buy offer.
|
||||
|
||||
Don’t focus too much on the UX of the application, unless the look and feel is pertinent to the topic. Use the standard CSS file with the look and feel for all of the tutorials.
|
||||
|
||||
Reuse the code from other modules when possible. There might be situations where you need to modify the behavior from an earlier module. You can either overload the function name or modify the module and save it with a different name.
|
||||
@@ -0,0 +1,54 @@
|
||||
---
|
||||
html: tutorial-structure.html
|
||||
parent: contribute-documentation.html
|
||||
blurb: 一般的なチュートリアルの構成要素の要約です。
|
||||
---
|
||||
# チュートリアルの構成
|
||||
|
||||
各XRP Ledgerチュートリアルは、同一のフォーマットで構成されています。
|
||||
|
||||
1. チュートリアルで説明する機能の簡単な説明。
|
||||
2. コードを実行するための前提条件(必要な場合)、またはサンプルコードへのリンク。
|
||||
3. チュートリアルの機能の使用例。
|
||||
4. サンプルコードの解説と、そのスクリプトの特徴的な要素の紹介。
|
||||
5. 次のステップとして試すべき概念的な情報や優れたチュートリアルへのリンク。
|
||||
|
||||
セットアップ(前提条件)と使用方法とコード開発は分けて考えましょう。これらはそれぞれ異なる活動であり、それぞれ脳の異なる領域を動かします。この3つの要素を一度に考えようとすると、混乱につながります。
|
||||
|
||||
## 説明
|
||||
|
||||
|
||||
|
||||
そのサンプルが何を示しているかを記載してください。可能であれば、各サンプルには関連する特定のタスクを達成するための手順を記述してください。(NFTの売却オファーの作成、売却オファーの受け入れ、売却オファーの削除など)。チュートリアルで説明されている内容を理解するのに十分なコンセプトに関する情報を記載し、必要であれば、追加情報へのリンクも記載します。
|
||||
|
||||
## 前提条件
|
||||
|
||||
|
||||
|
||||
必要なソフトウェアと、チュートリアルを実行するために必要なすべてのサンプルコードへのリンクを提供します。必要であれば、サードパーティのツールの使い方を簡単に説明しますが、ユーザが自由に深く掘り下げることができるように、ソースとなるウェブサイトへのリンクを提供します。
|
||||
|
||||
## 使用例
|
||||
|
||||
|
||||
|
||||
チュートリアルのアプリケーションの完成した動作例を提供することから始めましょう。これは、ソフトウェアを使って問題を解決するチャンスです。
|
||||
|
||||
チュートリアルの各ステップにはスクリーンショットを使用してください。これによって、ユーザは自分でコードを実行しなくてもチュートリアルを理解することができます。もちろん、コードを実行することが _望ましい_ ですが、これにりユーザに選択肢を与えることができます。
|
||||
|
||||
適切な条件におけるシナリオを記述してください。インターネットへの接続が途切れなければ、アプリケーションは問題なく動作するはずです。チュートリアルに関連しないトラブルシューティングの情報を提供しないでください。
|
||||
|
||||
## コード解説
|
||||
|
||||
|
||||
|
||||
コードを1ブロックずつ見ていきましょう。既に説明したトピックを繰り返さないでください。サンプルコードには、HTML構文のような基本的な部分のプログラミング方法については、その実装に独自なものがない限り、詳細な説明はしないでください。
|
||||
|
||||
強調すべき重要なことは、XRPLとのやりとりはすべてトランザクションかリクエストであり、すべてのトランザクションとリクエストは本質的に同じであるということです。私たちが提供するサンプルコードは、トランザクションやリクエストを準備する方法と、返された結果を処理する方法を示しています。1つのトランザクションやリクエストをどのように送信しどのようなレスポンスを返すかを知ることは、他のトランザクションやリクエストの処理について非常に良いヒントとなります。
|
||||
|
||||
(技術的には、リクエストに似た第3のカテゴリーがあります。[Subscriptionメソッド](subscription-methods.html)をご覧ください)。
|
||||
|
||||
## 関連項目
|
||||
|
||||
|
||||
|
||||
チュートリアルの最後には、追加の資料、概念的な情報、学習のにおいて有益な次のステップとなるチュートリアルへのリンクを提供します。
|
||||
@@ -0,0 +1,54 @@
|
||||
---
|
||||
html: tutorial-structure.html
|
||||
parent: contribute-documentation.html
|
||||
blurb: A summary of the parts of a standard tutorial.
|
||||
---
|
||||
# Tutorial Structure
|
||||
|
||||
Each XRP Ledger tutorial follows the same format.
|
||||
|
||||
1. A brief description of the features illustrated in the tutorial.
|
||||
2. Prerequisites for running the code, if needed, or links to the sample code.
|
||||
3. Usage examples of the features in the tutorial.
|
||||
4. A code walkthrough of the sample application, highlighting unique elements in the scripts.
|
||||
5. See Also, with links to conceptual information or good tutorials to try as a next step.
|
||||
|
||||
Separate setup (prerequisites) from usage from code development. These are each different activities that engage different areas of the brain. Trying to think of all three elements at once leads to confusion and headaches.
|
||||
|
||||
## Description
|
||||
|
||||
|
||||
|
||||
List what the sample demonstrates. If possible, each example should describe the steps to accomplish specific related tasks. (For example, create a NFT Sell Offer, Accept a Sell Offer, Delete a Sell Offer.) There should be enough conceptual information to understand what the tutorial illustrates, with links to additional conceptual information, if needed.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
|
||||
|
||||
Provide links to any required software and to all of the example code needed to run the tutorial. If necessary, give simple instructions for using third-party tools, but provide a link to the source website for the customer to do a deeper dive at their leisure.
|
||||
|
||||
## Usage Example
|
||||
|
||||
|
||||
|
||||
Start by providing a finished, working example of the tutorial application. This is an opportunity for immediate success working with the software to solve a problem.
|
||||
|
||||
Use screenshots for each step of the tutorial – these allow the user to understand the tutorial without having to run the code themselves. Of course we _want_ them to run the code, but this gives them a choice.
|
||||
|
||||
Describe the sunny day scenario. The application should run without problems if there is an uninterrupted connection to the internet. Don’t provide a lot of troubleshooting information, unless it’s pertinent to the tutorial.
|
||||
|
||||
## Code Walkthrough
|
||||
|
||||
|
||||
|
||||
Walk through the code, one chunk at a time. Don’t belabor topics that have been discussed in earlier examples. Provide sample code, but don’t provide exhaustive explanations for how to program underlying platforms like HTML syntax unless there is something unique to the implementation.
|
||||
|
||||
An important thing to emphasize is that every interaction with the XRPL is either a transaction or a request, and that all transactions and requests are essentially the same. The sample code we provide shows how to prepare the transaction or request, and how to process the returned results. Knowing how to submit and respond to one transaction or request gives a pretty good idea for how to submit and respond to any transaction or request.
|
||||
|
||||
(Technically there is third category, similar to a request: a notification from a subscription stream. See [Subscription Methods](subscription-methods.html).)
|
||||
|
||||
## See Also
|
||||
|
||||
|
||||
|
||||
At the end of the tutorial, provide links to additional resources, conceptual information, and any tutorials that would be a sensible next step in the learning journey.
|
||||
1243
content/resources/known-amendments.ja.md
Normal file
1243
content/resources/known-amendments.ja.md
Normal file
File diff suppressed because it is too large
Load Diff
1242
content/resources/known-amendments.md
Normal file
1242
content/resources/known-amendments.md
Normal file
File diff suppressed because it is too large
Load Diff
Reference in New Issue
Block a user