From c4519790a8511f9a88b3ae571dc86e49a4749884 Mon Sep 17 00:00:00 2001 From: Oliver Eggert Date: Thu, 23 Jul 2026 11:23:55 -0700 Subject: [PATCH 01/24] initial commit of simplexrpl docs --- docs/_snippets/simplexrpl-response-fields.md | 10 ++ docs/_snippets/simplexrpl-write-options.md | 7 + docs/simpleXRPL/get-started.md | 129 +++++++++++++++ docs/simpleXRPL/index.md | 45 ++++++ .../references/connector-routing.md | 60 +++++++ docs/simpleXRPL/references/index.md | 93 +++++++++++ .../references/verticals/account/activate.md | 57 +++++++ .../references/verticals/account/create.md | 51 ++++++ .../verticals/account/depositPreauth.md | 54 +++++++ .../references/verticals/account/fund.md | 57 +++++++ .../references/verticals/account/index.md | 21 +++ .../verticals/account/listOffers.md | 48 ++++++ .../references/verticals/account/retrieve.md | 56 +++++++ .../references/verticals/account/set.md | 70 ++++++++ .../verticals/account/setRegularKey.md | 53 +++++++ .../references/verticals/credential/accept.md | 60 +++++++ .../references/verticals/credential/delete.md | 60 +++++++ .../references/verticals/credential/index.md | 18 +++ .../references/verticals/credential/issue.md | 62 ++++++++ .../references/verticals/credential/list.md | 50 ++++++ .../verticals/credential/retrieve.md | 65 ++++++++ .../references/verticals/domain/create.md | 66 ++++++++ .../references/verticals/domain/delete.md | 57 +++++++ .../references/verticals/domain/index.md | 18 +++ .../references/verticals/domain/list.md | 49 ++++++ .../references/verticals/domain/retrieve.md | 57 +++++++ .../verticals/domain/setCredentials.md | 66 ++++++++ docs/simpleXRPL/references/verticals/index.md | 25 +++ .../references/verticals/iou/authorize.md | 63 ++++++++ .../references/verticals/iou/buyOffer.md | 70 ++++++++ .../references/verticals/iou/cancelOffer.md | 57 +++++++ .../references/verticals/iou/clawback.md | 66 ++++++++ .../references/verticals/iou/index.md | 25 +++ .../references/verticals/iou/issue.md | 63 ++++++++ .../references/verticals/iou/list.md | 50 ++++++ .../references/verticals/iou/listOffers.md | 52 ++++++ .../references/verticals/iou/lock.md | 64 ++++++++ .../references/verticals/iou/retrieve.md | 65 ++++++++ .../references/verticals/iou/sellOffer.md | 70 ++++++++ .../references/verticals/iou/transfer.md | 62 ++++++++ .../references/verticals/iou/unlock.md | 64 ++++++++ .../references/verticals/token/authorize.md | 57 +++++++ .../references/verticals/token/cancelOffer.md | 57 +++++++ .../references/verticals/token/createOffer.md | 67 ++++++++ .../references/verticals/token/destroy.md | 57 +++++++ .../references/verticals/token/grantHolder.md | 59 +++++++ .../references/verticals/token/index.md | 27 ++++ .../references/verticals/token/issue.md | 85 ++++++++++ .../references/verticals/token/list.md | 58 +++++++ .../references/verticals/token/listOffers.md | 60 +++++++ .../references/verticals/token/lock.md | 59 +++++++ .../references/verticals/token/retrieve.md | 62 ++++++++ .../verticals/token/revokeHolder.md | 59 +++++++ .../references/verticals/token/transfer.md | 60 +++++++ .../references/verticals/token/unauthorize.md | 57 +++++++ .../references/verticals/token/unlock.md | 59 +++++++ .../references/verticals/xrp/index.md | 14 ++ .../references/verticals/xrp/transfer.md | 62 ++++++++ .../tutorials/connect-custodians.md | 93 +++++++++++ .../tutorials/create-permissioned-domain.md | 74 +++++++++ .../tutorials/cross-custodian-workflows.md | 94 +++++++++++ docs/simpleXRPL/tutorials/discover-acounts.md | 65 ++++++++ docs/simpleXRPL/tutorials/external-signer.md | 118 ++++++++++++++ .../tutorials/implement-aws-kms-signer.md | 52 ++++++ .../tutorials/implement-pkcs11-signer.md | 150 ++++++++++++++++++ .../tutorials/inititialize-clients.md | 61 +++++++ .../tutorials/issue-and-distribute-iou.md | 77 +++++++++ docs/simpleXRPL/tutorials/issue-rwa-as-mpt.md | 77 +++++++++ docs/simpleXRPL/tutorials/place-dex-order.md | 89 +++++++++++ .../tutorials/read-routing-reports.md | 79 +++++++++ index.page.tsx | 2 +- redocly.yaml | 6 +- sidebars.yaml | 150 +++++++++++++++++- 73 files changed, 4374 insertions(+), 7 deletions(-) create mode 100644 docs/_snippets/simplexrpl-response-fields.md create mode 100644 docs/_snippets/simplexrpl-write-options.md create mode 100644 docs/simpleXRPL/get-started.md create mode 100644 docs/simpleXRPL/index.md create mode 100644 docs/simpleXRPL/references/connector-routing.md create mode 100644 docs/simpleXRPL/references/index.md create mode 100644 docs/simpleXRPL/references/verticals/account/activate.md create mode 100644 docs/simpleXRPL/references/verticals/account/create.md create mode 100644 docs/simpleXRPL/references/verticals/account/depositPreauth.md create mode 100644 docs/simpleXRPL/references/verticals/account/fund.md create mode 100644 docs/simpleXRPL/references/verticals/account/index.md create mode 100644 docs/simpleXRPL/references/verticals/account/listOffers.md create mode 100644 docs/simpleXRPL/references/verticals/account/retrieve.md create mode 100644 docs/simpleXRPL/references/verticals/account/set.md create mode 100644 docs/simpleXRPL/references/verticals/account/setRegularKey.md create mode 100644 docs/simpleXRPL/references/verticals/credential/accept.md create mode 100644 docs/simpleXRPL/references/verticals/credential/delete.md create mode 100644 docs/simpleXRPL/references/verticals/credential/index.md create mode 100644 docs/simpleXRPL/references/verticals/credential/issue.md create mode 100644 docs/simpleXRPL/references/verticals/credential/list.md create mode 100644 docs/simpleXRPL/references/verticals/credential/retrieve.md create mode 100644 docs/simpleXRPL/references/verticals/domain/create.md create mode 100644 docs/simpleXRPL/references/verticals/domain/delete.md create mode 100644 docs/simpleXRPL/references/verticals/domain/index.md create mode 100644 docs/simpleXRPL/references/verticals/domain/list.md create mode 100644 docs/simpleXRPL/references/verticals/domain/retrieve.md create mode 100644 docs/simpleXRPL/references/verticals/domain/setCredentials.md create mode 100644 docs/simpleXRPL/references/verticals/index.md create mode 100644 docs/simpleXRPL/references/verticals/iou/authorize.md create mode 100644 docs/simpleXRPL/references/verticals/iou/buyOffer.md create mode 100644 docs/simpleXRPL/references/verticals/iou/cancelOffer.md create mode 100644 docs/simpleXRPL/references/verticals/iou/clawback.md create mode 100644 docs/simpleXRPL/references/verticals/iou/index.md create mode 100644 docs/simpleXRPL/references/verticals/iou/issue.md create mode 100644 docs/simpleXRPL/references/verticals/iou/list.md create mode 100644 docs/simpleXRPL/references/verticals/iou/listOffers.md create mode 100644 docs/simpleXRPL/references/verticals/iou/lock.md create mode 100644 docs/simpleXRPL/references/verticals/iou/retrieve.md create mode 100644 docs/simpleXRPL/references/verticals/iou/sellOffer.md create mode 100644 docs/simpleXRPL/references/verticals/iou/transfer.md create mode 100644 docs/simpleXRPL/references/verticals/iou/unlock.md create mode 100644 docs/simpleXRPL/references/verticals/token/authorize.md create mode 100644 docs/simpleXRPL/references/verticals/token/cancelOffer.md create mode 100644 docs/simpleXRPL/references/verticals/token/createOffer.md create mode 100644 docs/simpleXRPL/references/verticals/token/destroy.md create mode 100644 docs/simpleXRPL/references/verticals/token/grantHolder.md create mode 100644 docs/simpleXRPL/references/verticals/token/index.md create mode 100644 docs/simpleXRPL/references/verticals/token/issue.md create mode 100644 docs/simpleXRPL/references/verticals/token/list.md create mode 100644 docs/simpleXRPL/references/verticals/token/listOffers.md create mode 100644 docs/simpleXRPL/references/verticals/token/lock.md create mode 100644 docs/simpleXRPL/references/verticals/token/retrieve.md create mode 100644 docs/simpleXRPL/references/verticals/token/revokeHolder.md create mode 100644 docs/simpleXRPL/references/verticals/token/transfer.md create mode 100644 docs/simpleXRPL/references/verticals/token/unauthorize.md create mode 100644 docs/simpleXRPL/references/verticals/token/unlock.md create mode 100644 docs/simpleXRPL/references/verticals/xrp/index.md create mode 100644 docs/simpleXRPL/references/verticals/xrp/transfer.md create mode 100644 docs/simpleXRPL/tutorials/connect-custodians.md create mode 100644 docs/simpleXRPL/tutorials/create-permissioned-domain.md create mode 100644 docs/simpleXRPL/tutorials/cross-custodian-workflows.md create mode 100644 docs/simpleXRPL/tutorials/discover-acounts.md create mode 100644 docs/simpleXRPL/tutorials/external-signer.md create mode 100644 docs/simpleXRPL/tutorials/implement-aws-kms-signer.md create mode 100644 docs/simpleXRPL/tutorials/implement-pkcs11-signer.md create mode 100644 docs/simpleXRPL/tutorials/inititialize-clients.md create mode 100644 docs/simpleXRPL/tutorials/issue-and-distribute-iou.md create mode 100644 docs/simpleXRPL/tutorials/issue-rwa-as-mpt.md create mode 100644 docs/simpleXRPL/tutorials/place-dex-order.md create mode 100644 docs/simpleXRPL/tutorials/read-routing-reports.md diff --git a/docs/_snippets/simplexrpl-response-fields.md b/docs/_snippets/simplexrpl-response-fields.md new file mode 100644 index 00000000..5353a563 --- /dev/null +++ b/docs/_snippets/simplexrpl-response-fields.md @@ -0,0 +1,10 @@ +Every simpleXRPL write resolves to a `SubmissionResult` — a union tagged by `source`, with the backend's raw response preserved verbatim. Its common fields are: + +| Field | Type | Description | +| --- | --- | --- | +| `intent` | `T` | The method-specific output. See the method's response values below. | +| `source` | `'rippled' \| 'custody' \| 'palisade'` | Which backend produced the result; discriminates `response`. | +| `response` | `TxResponse` \| custody record \| Palisade record | The backend's raw response, preserved verbatim. | +| `txHash` | `string` _(optional)_ | The XRPL transaction hash, once the transaction is on-ledger. | +| `intentId` | `string` _(optional)_ | The custodian intent id, when the path produced one. | +| `idempotencyKey` | `string` _(optional)_ | The UUIDv7 this submission carried. Pass it back as a later call's `idempotencyKey` to retry to the same intent. | diff --git a/docs/_snippets/simplexrpl-write-options.md b/docs/_snippets/simplexrpl-write-options.md new file mode 100644 index 00000000..f66ef400 --- /dev/null +++ b/docs/_snippets/simplexrpl-write-options.md @@ -0,0 +1,7 @@ +`options` is an optional second argument that sets the source account and overrides the fee. + +| Option | Type | Required | Description | +| --- | --- | --- | --- | +| `from` | `AccountSelector` | No | The account to act as. Defaults to the primary signer's primary account. (For IOU verbs, this is the issuer.) | +| `fee` | `FeeIntent` | No | Fee override. | +| `idempotencyKey` | `string` | No | A prior submission's `idempotencyKey`, to retry to the same intent instead of creating a duplicate. Auto-generated when omitted. | diff --git a/docs/simpleXRPL/get-started.md b/docs/simpleXRPL/get-started.md new file mode 100644 index 00000000..e5007597 --- /dev/null +++ b/docs/simpleXRPL/get-started.md @@ -0,0 +1,129 @@ +--- +seo: + description: Install simpleXRPL, initialize the client, connect a custodian, and run your first XRP Ledger operation. +labels: + - SDKs +--- + +# Get Started + +This guide takes you from install to your first on-ledger operation in three steps: **initialize the client**, **set up a custodian**, and **run a vertical operation**. The examples target the XRPL Testnet with a local signer so you can run them as-is, then swap in a production custodian when you're ready. + +## Prerequisites + +- **Node.js >= 20.19.** simpleXRPL is Node-targeted and not intended to run in the browser. +- Install the package: + +```sh +npm install simplexrpl +``` + +## 1. Initialize the client + +`SimpleXRPL.init(...)` is the single entry point — you never construct the client with `new`. It binds one or more already-authenticated signing backends (the **connectors**) to a network and builds the account index. + +```ts +import { LocalSigner, SimpleXRPL } from 'simplexrpl' + +const client = await SimpleXRPL.init({ + // Point at a rippled endpoint. `faucetUrl` is only used on test networks + // (by `client.account.fund`). + rippledUrl: 'wss://s.altnet.rippletest.net:51233', + faucetUrl: 'https://faucet.altnet.rippletest.net/accounts', + + // Bind one or more connectors. Here, a single local-signing backend that + // reads its seeds from the environment (`XRPL_*_SEED`). + signers: [LocalSigner.fromEnv()], +}) + +// ... use the client ... + +await client.disconnect() +``` + +- **`primarySigner`** is the default backend for verbs called without an explicit account. It defaults to `signers[0]`, so you only set it when you bind more than one connector. +- With **no `signers`**, the client is read-only: reads work, but write verbs throw `NoSignerError` until a signer is added. +- Bind an account at runtime (for example, a freshly created wallet) with `client.registerLocalAccount(seed)`. + +See [Initialize the client](tutorials/inititialize-clients.md) for the full walkthrough, and [Client and initialization](references/index.md#client-and-initialization) for the configuration reference. + +## 2. Set up a custodian + +The **connector** determines how operations run and who holds the keys. simpleXRPL ships three, each constructed and authenticated on its own, then handed to `init`: + +- **`LocalSigner`** — self-custody; keys held in-process. For development and testing. +- **`RippleCustody`** — routes through Ripple Custody. For production. +- **`PalisadeCustody`** — routes through Palisade. For production. + +The local signer in Step 1 is enough for development. For production, construct a custodian connector and bind it instead of (or alongside) the local one: + +```ts +import { + LocalSigner, + PalisadeCustody, + RippleCustody, + SimpleXRPL, +} from 'simplexrpl' + +// Ripple Custody — authenticates with an intent-author key and operates within +// one Custody domain. `fromEnv` reads the `RIPPLE_CUSTODY_*` variables. +const rippleCustody = await RippleCustody.fromEnv({ + primary: process.env.RIPPLE_CUSTODY_PRIMARY ?? '', +}) + +// Palisade — authenticates via OAuth client credentials and acts on a +// specific vault/wallet. +const palisade = await PalisadeCustody.create({ + baseUrl: 'https://api.sandbox.palisade.co', + clientId: process.env.PALISADE_CLIENT_ID ?? '', + clientSecret: process.env.PALISADE_CLIENT_SECRET ?? '', + primary: { + vaultId: process.env.PALISADE_VAULT_ID ?? '', + walletId: process.env.PALISADE_WALLET_ID ?? '', + }, + // Enable the raw sign-only fallback for transactors the custodian has no + // native operation for. Off by default. + allowRawSigning: false, +}) + +const client = await SimpleXRPL.init({ + rippledUrl: 'wss://s.altnet.rippletest.net:51233', + signers: [rippleCustody, palisade, LocalSigner.fromEnv()], + primarySigner: rippleCustody, +}) +``` + +Read credentials from your environment or secrets manager — never hard-code keys. Once bound, every vertical verb works the same regardless of which connector owns the account: the SDK routes each write to the custodian that holds it. + +{% admonition type="info" name="Note" %} +Whether an operation runs through a custodian's **native** path or the **raw-signing fallback** is decided per operation, and fallback is off unless you opt in. See [Operation Execution](index.md#operation-execution) and the [Connector Routing](references/connector-routing.md) table. +{% /admonition %} + +See [Connect to custodians](tutorials/connect-custodians.md) for the full per-connector setup. + +## 3. Run a vertical operation + +Operations are grouped into domain-specific **verticals** — `xrp`, `token`, `iou`, `credential`, `domain`, and `account` — reached off the client. Each verb reads as business intent rather than protocol mechanics. Here's the simplest one, a native XRP payment: + +```ts +const result = await client.xrp.transfer({ + to: 'rDestination...', + amount: '10', +}) + +console.log(result.txHash) +``` + +- A write verb uses the **primary account** by default; target a different bound account by passing `from` in the options. +- Every write resolves to a `SubmissionResult` carrying the transaction hash, the backend's response, and a typed `intent` output. See [Results and handles](references/index.md#results-and-handles). +- **Reads** (such as `client.account.retrieve()`) need no signer and submit nothing. + +{% admonition type="success" name="Tip" %} +On a test network, create and fund an account first with [`account.create()`](references/verticals/account/create.md) and [`account.fund()`](references/verticals/account/fund.md), then use its address as the source or destination. +{% /admonition %} + +## Next steps + +- **Tutorials** — end-to-end workflows: [Issue an RWA as an MPT](tutorials/issue-rwa-as-mpt.md), [Issue and distribute an IOU](tutorials/issue-and-distribute-iou.md), [Place a DEX order](tutorials/place-dex-order.md), and more. +- **Reference** — every vertical, method, connector, and type: [Reference](references/index.md). +- **Concepts** — what simpleXRPL is and why: [What is simpleXRPL](index.md). diff --git a/docs/simpleXRPL/index.md b/docs/simpleXRPL/index.md new file mode 100644 index 00000000..8350fb10 --- /dev/null +++ b/docs/simpleXRPL/index.md @@ -0,0 +1,45 @@ +--- +seo: + description: simpleXRPL is an opinionated TypeScript SDK that lets institutional developers express XRP Ledger operations as business intent and route them through the custodians they already use. +labels: + - SDKs +--- + +# simpleXRPL + +The `simpleXRPL` is an opinionated TypeScript SDK for the XRP Ledger, built for institutional developers who interact with the ledger through a custodian. It raises the level of your code from XRPL protocol mechanics to business operations that the SDK routes through institutional custodians. Concretely, this means: + +- `simpleXRPL` defines the shape of business operations, handling the underlying XRPL transactions and custodian API calls. +- Your code doesn't change even if you switch custodians or operate across several at once. + +{% admonition type="info" name="Note" %} +`simpleXRPL` is pre-1.0. The public API may change between releases and no sandbox exists yet to test native custodian operations. +{% /admonition %} + + +## How It Works + +`simpleXRPL` is built around four concepts: + +- **Client**: Establishes the network connection and the connector configuration. Both are immutable for the client's lifetime; to change either, you create a new client. +- **Connector**: The execution model that determines *how* operations run and *who* holds account keys. Each connector exposes a uniform interface to the rest of the SDK, so the same code runs across all of them. +- **Accounts**: A separate abstraction, bound to a custodian or a local seed and given a logical name. +- **Verticals**: Domain-specific classes that group related business operations. + + +## Operation Execution + +For every operation, on every connector, `simpleXRPL` has a statically defined routing decision that it reports at initialization: + +- **Native**: Maps onto an endpoint the custodian exposes and natively handles. +- **Raw signing fallback (opt-in)**: The custodian has no native endpoint yet, so the SDK constructs and submits the necessary transactions to the XRPL. Raw-signing is only used if you explicitly enable it for a specific operation. +- **Unavailable**: The custodian doesn't expost a native endpoint and raw signing isn't permitted for this operation. + +{% admonition type="info" name="Note" %} +For a complete list of supported operations by connector, see the [Connector Routing Table](./references/connector-routing.md) +{% /admonition %} + + +## Next steps + +Ready to build? See [Get Started](./get-started.md) to install `simpleXRPL`, connect a custodian, and run your first operation. diff --git a/docs/simpleXRPL/references/connector-routing.md b/docs/simpleXRPL/references/connector-routing.md new file mode 100644 index 00000000..f2e93b05 --- /dev/null +++ b/docs/simpleXRPL/references/connector-routing.md @@ -0,0 +1,60 @@ +--- +seo: + description: The connector routing table — per XRPL transactor and per custodian, whether an operation routes native, requires the raw-signing fallback, or is unavailable. +labels: + - SDKs +--- + +# Connector Routing + +[Source](https://github.com/ripple/simpleXRPL/blob/50619258cf753008e8a185eaeb3ceca489e5998a/docs/connector-routing.md) + +How simpleXRPL dispatches each XRPL transactor per connector. Derived directly from each custodian's native-operation set and the transactors the verticals build, so it always matches the code. + +{% admonition type="info" name="Note" %} +This page is generated from the SDK source by `scripts/gen-connector-routing.mjs` — do not edit by hand. Regenerate with `npm run docgen:routing`. +{% /admonition %} + +## Transactor → connector path + +The pipeline routes by transactor type: **Local** signs everything in-process; a custodian uses its **native** operation when the transactor is in its capability set, otherwise the **raw** sign-only fallback, otherwise the write is rejected. + +| Transactor | Local | Ripple Custody | Palisade | +| --- | --- | --- | --- | +| `AccountSet` | signs locally | **native** | **native** | +| `Clawback` | signs locally | **native** | **native** | +| `CredentialAccept` | signs locally | raw fallback¹ | raw fallback¹ | +| `CredentialCreate` | signs locally | raw fallback¹ | raw fallback¹ | +| `CredentialDelete` | signs locally | raw fallback¹ | raw fallback¹ | +| `DepositPreauth` | signs locally | **native** | raw fallback¹ | +| `EscrowFinish` | signs locally | **native** | raw fallback¹ | +| `MPTokenAuthorize` | signs locally | **native** | raw fallback¹ | +| `MPTokenIssuanceCreate` | signs locally | **native** | raw fallback¹ | +| `MPTokenIssuanceDestroy` | signs locally | **native** | raw fallback¹ | +| `MPTokenIssuanceSet` | signs locally | **native** | raw fallback¹ | +| `OfferCancel` | signs locally | raw fallback¹ | **native** | +| `OfferCreate` | signs locally | **native** | **native** | +| `Payment` | signs locally | **native** | **native** | +| `PermissionedDomainDelete` | signs locally | raw fallback¹ | raw fallback¹ | +| `PermissionedDomainSet` | signs locally | raw fallback¹ | raw fallback¹ | +| `SetRegularKey` | signs locally | raw fallback¹ | raw fallback¹ | +| `TrustSet` | signs locally | **native** | **native** | + +¹ **raw fallback** applies only when raw signing is enabled on that custodian (`allowRawSigning`). With raw signing disabled, a non-native transactor is rejected with `SignerCapabilityError` — use a Local account or a custodian that natively supports it. The raw path signs the encoded transaction and submits it through the shared XRPL connection. + +## Vertical → transactors + +Which XRPL transactors each vertical builds. Cross-reference with the table above to see how a given method routes on each connector. + +| Vertical | Transactors emitted | +| --- | --- | +| `account` | `AccountSet`, `DepositPreauth`, `Payment`, `SetRegularKey` | +| `credential` | `CredentialAccept`, `CredentialCreate`, `CredentialDelete` | +| `domain` | `PermissionedDomainDelete`, `PermissionedDomainSet` | +| `iou` | `AccountSet`, `Clawback`, `OfferCancel`, `OfferCreate`, `Payment`, `TrustSet` | +| `token` | `MPTokenAuthorize`, `MPTokenIssuanceCreate`, `MPTokenIssuanceDestroy`, `MPTokenIssuanceSet`, `OfferCancel`, `OfferCreate`, `Payment` | +| `xrp` | `Payment` | + +--- + +_Native-ops sets: `NATIVE_XRPL_TRANSACTORS` (Ripple Custody), `PALISADE_NATIVE_TRANSACTORS` (Palisade). Local signs all transactors._ diff --git a/docs/simpleXRPL/references/index.md b/docs/simpleXRPL/references/index.md new file mode 100644 index 00000000..1def89de --- /dev/null +++ b/docs/simpleXRPL/references/index.md @@ -0,0 +1,93 @@ +--- +seo: + description: Reference index for the simpleXRPL SDK — its verticals, connectors, the amount and asset model, submission results, and the error hierarchy. +labels: + - SDKs +--- + +# Reference + +This section is the map of simpleXRPL's public API surface: the client entry point, the business-intent verticals, the custodian connectors, the amount and asset model, submission results, and the error hierarchy. Complete type-level signatures for every symbol are generated from the source with TypeDoc; the tables below are the curated index of what you actually build against. + +New to simpleXRPL? Start with [What is simpleXRPL](../index.md) for the concepts, then [Get Started](../get-started.md) to install and connect a custodian. + +{% admonition type="info" name="Note" %} +This index covers the public surface only. Internal and testing seams (the dispatch pipeline, injected I/O ports, and the production ledger port) are intentionally omitted — you don't call them directly. +{% /admonition %} + +## Client and initialization + +The client owns the network connection and the connector configuration, both immutable for its lifetime. + +| Symbol | Description | +| --- | --- | +| `SimpleXRPL` | The entry point. `SimpleXRPL.init(...)` establishes the network, connector, and account bindings. | +| `SimpleXRPLClient` | The runtime client returned by `init`; exposes the verticals. | +| `SimpleXRPLConfig` | The initialization configuration shape (network, connector, accounts). | +| `NetworkInfo` | Resolved network details for the connected client. | + +## Verticals + +Operations are grouped into domain-specific **verticals**, one per area of XRPL functionality and reached off the client. See [Verticals](verticals/index.md) for what a vertical is and the full list of verticals and their methods. + +## Connectors + +The connector is the execution model — it determines how operations run and who holds the keys. See [Operation Execution](../index.md#operation-execution) for how each operation routes. + +| Connector | Use | Key configuration types | +| --- | --- | --- | +| `LocalSigner` | Development and testing; holds `xrpl` wallets in-process. | `LocalSignerCreateOptions`, `LocalSignerFromEnvOptions` | +| `RippleCustody` | Production; routes through Ripple Custody. | `RippleCustodyOptions`, `RippleCustodyAuthOptions`, `RippleCustodyFromEnvOptions` | +| `PalisadeCustody` | Production; routes through Palisade. | `PalisadeCustodyConfig`, `PalisadeWalletRef` | + +## Amounts and assets + +The amount model represents XRP, IOU, and MPT values and handles decimal/scale conversion. + +| Symbol | Description | +| --- | --- | +| `Amount` | A value paired with the asset it denominates. | +| `Asset` | The asset an amount is in (XRP, IOU, or MPT). | +| `XRP_ASSET` | The canonical XRP asset constant. | +| `iou(currency, issuer)` | Construct an issued-currency asset. | +| `mpt(mptIssuanceId, scale?)` | Construct an MPT asset; `scale` is the decimal places between display value and on-ledger base units. | +| `toLedgerAmount` / `fromLedgerAmount` | Convert between display amounts and on-ledger base units. | +| `LedgerAmount` | The on-ledger (base-unit) amount representation. | + +## Results and handles + +| Symbol | Description | +| --- | --- | +| `SubmissionResult` | The terminal result of an operation; carries the discriminated `source`/`response` pairing and the vertical's typed `intent` output. | +| `SubmissionResultFields` | The common fields present on every submission result. | +| `SubmissionPath` | Which path the operation took (native vs. raw-signing). | +| `SubmissionHandle` | Handle over an asynchronously-submitted operation, for flows that resolve later. | +| `CustodyTransactionResult` / `PalisadeTransactionResult` | The connector-specific transaction record inside the result. | + +The `*Intent` types (`XrpTransferIntent`, `MptIssueIntent`, `IOUIssueIntent`, `DomainIntent`, and the rest) are the typed `intent` payloads attached to each result. + +## Errors + +All errors extend `SimpleXRPLError`, so you can catch the base class or narrow to a specific type. + +| Error | Raised when | +| --- | --- | +| `SimpleXRPLError` | Base class for every SDK error. | +| `NoSignerError` | No signer/connector owns the target account. | +| `SignerCapabilityError` | The operation can't be signed on this connector (native path missing, or raw signing not enabled). | +| `AccountNotFoundError` | The referenced account is not bound to the client. | +| `AmbiguousAccountError` | The account reference matches more than one bound account. | +| `RippledSubmitError` | The transaction reached a terminal on-ledger failure (non-`tesSUCCESS`). | +| `IntentPendingError` | A custodian intent is still awaiting approval when a terminal result was expected. | +| `IntentValidationError` | A custodian rejected the intent as invalid. | +| `MultiStepFailureError` | A multi-step operation failed partway through. | +| `CustodyApiError` / `CustodyAuthError` | Ripple Custody API or authentication failure. | +| `PalisadeApiError` / `PalisadeAuthError` | Palisade API or authentication failure. | + +## Related reference + +Companion reference pages that live alongside this index: + +- **Function-to-transactor mapping** — the underlying XRPL transactor(s) each method expands into (also shown inline on each method page). +- [**Connector routing table**](connector-routing.md) — per operation and per connector, whether it routes native, requires raw-signing fallback, or is unavailable. +- **Institutional defaults** — the full set of defaults the SDK applies unless overridden. diff --git a/docs/simpleXRPL/references/verticals/account/activate.md b/docs/simpleXRPL/references/verticals/account/activate.md new file mode 100644 index 00000000..883976f4 --- /dev/null +++ b/docs/simpleXRPL/references/verticals/account/activate.md @@ -0,0 +1,57 @@ +--- +seo: + description: Account.activate activates a created account by sending it XRP from the operator account, then enabling rippling. +labels: + - SDKs +--- + +# account.activate() + +[Source](https://github.com/ripple/simpleXRPL/blob/50619258cf753008e8a185eaeb3ceca489e5998a/src/verticals/account.ts#L151) + +Activate a created account by sending it XRP from the operator (primary) account, then enabling rippling. This is the any-network counterpart to [`fund`](fund.md); the account must be signable by this client (e.g. from [`create`](create.md)). + +## Signature + +```ts +account.activate( + params: AccountActivateParams, + options?: AccountWriteOptions, +): Promise> +``` + +### Parameters + +| Parameter | Type | Required | Description | +| --- | --- | --- | --- | +| `destination` | `string` | Yes | The r-address to activate (typically from `Account.create`). | +| `amount` | `string` | No | XRP to send. Defaults to the network's base reserve (plus a small buffer). | + +### Options + +{% raw-partial file="/docs/_snippets/simplexrpl-write-options.md" /%} + +### Response + +Resolves to a `SubmissionResult` (from the `defaultRipple` settings change). + +{% raw-partial file="/docs/_snippets/simplexrpl-response-fields.md" /%} + +#### Response values + +`Account.activate` attaches no `intent` output; `intent` is `undefined`. + +### Underlying XRPL transactors + +Runs as an ordered, multi-step sequence: + +1. [`Payment`](https://xrpl.org/docs/references/protocol/transactions/types/payment) — the operator sends XRP to the destination. +2. [`AccountSet`](https://xrpl.org/docs/references/protocol/transactions/types/accountset) — the new account enables rippling (`defaultRipple`). + +## Example + +```ts +await client.account.activate({ + destination: 'rNewAccount...', +}) +``` diff --git a/docs/simpleXRPL/references/verticals/account/create.md b/docs/simpleXRPL/references/verticals/account/create.md new file mode 100644 index 00000000..02b02b93 --- /dev/null +++ b/docs/simpleXRPL/references/verticals/account/create.md @@ -0,0 +1,51 @@ +--- +seo: + description: Account.create generates a new XRPL keypair locally and registers it. No transaction is submitted. +labels: + - SDKs +--- + +# account.create() + +[Source](https://github.com/ripple/simpleXRPL/blob/50619258cf753008e8a185eaeb3ceca489e5998a/src/verticals/account.ts#L72) + +Generate a new XRPL keypair locally and register it so it can be funded and used right away. Use this only to mint an additional account outside of `SimpleXRPL.init`. + +{% admonition type="warning" name="Warning" %} +Nothing is written to the ledger until the account is funded. The returned `seed` (and `privateKey`) are secret and are the only way to control the account — store them securely and never log or transmit them. +{% /admonition %} + +## Signature + +```ts +account.create(): AccountCredentials +``` + +### Parameters + +None. `Account.create` takes no arguments. + +### Response + +Returns an `AccountCredentials` object **synchronously** — this is the one `Account` verb that does not submit a transaction, so it does not return a `SubmissionResult`. + +#### Response values + +| Field | Type | Description | +| --- | --- | --- | +| `address` | `string` | The classic r-address. | +| `publicKey` | `string` | The public key (hex). | +| `privateKey` | `string` | The private key (hex) — sensitive. | +| `seed` | `string` | The account seed (secret) — sensitive. | + +### Underlying XRPL transactor + +None. `Account.create` generates a keypair locally and writes nothing to the ledger. Use [`activate`](activate.md) or [`fund`](fund.md) to bring the account on-ledger. + +## Example + +```ts +const { address, seed } = client.account.create() + +console.log(address) +``` diff --git a/docs/simpleXRPL/references/verticals/account/depositPreauth.md b/docs/simpleXRPL/references/verticals/account/depositPreauth.md new file mode 100644 index 00000000..3f17ef0d --- /dev/null +++ b/docs/simpleXRPL/references/verticals/account/depositPreauth.md @@ -0,0 +1,54 @@ +--- +seo: + description: Account.depositPreauth grants or revokes deposit preauthorization for another account via a DepositPreauth transaction. +labels: + - SDKs +--- + +# account.depositPreauth() + +[Source](https://github.com/ripple/simpleXRPL/blob/50619258cf753008e8a185eaeb3ceca489e5998a/src/verticals/account.ts#L263) + +Grant or revoke deposit preauthorization for another account. + +## Signature + +```ts +account.depositPreauth( + params: DepositPreauthParams, + options?: AccountWriteOptions, +): Promise> +``` + +### Parameters + +| Parameter | Type | Required | Description | +| --- | --- | --- | --- | +| `authorize` | `string` | No | An r-address to preauthorize for deposits. | +| `unauthorize` | `string` | No | An r-address to remove preauthorization from. | + +### Options + +{% raw-partial file="/docs/_snippets/simplexrpl-write-options.md" /%} + +### Response + +Resolves to a `SubmissionResult`. + +{% raw-partial file="/docs/_snippets/simplexrpl-response-fields.md" /%} + +#### Response values + +`Account.depositPreauth` attaches no `intent` output; `intent` is `undefined`. + +### Underlying XRPL transactor + +Builds and submits a single [`DepositPreauth`](https://xrpl.org/docs/references/protocol/transactions/types/depositpreauth) transaction. + +## Example + +```ts +await client.account.depositPreauth({ + authorize: 'rTrusted...', +}) +``` diff --git a/docs/simpleXRPL/references/verticals/account/fund.md b/docs/simpleXRPL/references/verticals/account/fund.md new file mode 100644 index 00000000..b6844141 --- /dev/null +++ b/docs/simpleXRPL/references/verticals/account/fund.md @@ -0,0 +1,57 @@ +--- +seo: + description: Account.fund funds a created account from a testnet/devnet faucet, then enables rippling via an AccountSet transaction. +labels: + - SDKs +--- + +# account.fund() + +[Source](https://github.com/ripple/simpleXRPL/blob/50619258cf753008e8a185eaeb3ceca489e5998a/src/verticals/account.ts#L124) + +Fund a created account via the network faucet (testnet/devnet), then enable rippling. The account must be one this client can sign for (e.g. from [`create`](create.md)). + +{% admonition type="info" name="Note" %} +`fund` requires a faucet-capable ledger (testnet/devnet). On other networks it throws — use [`activate`](activate.md) to fund from an operator account instead. +{% /admonition %} + +## Signature + +```ts +account.fund( + params: AccountFundParams, + options?: AccountWriteOptions, +): Promise> +``` + +### Parameters + +| Parameter | Type | Required | Description | +| --- | --- | --- | --- | +| `destination` | `string` | Yes | The r-address to fund (typically from `Account.create`). | + +### Options + +{% raw-partial file="/docs/_snippets/simplexrpl-write-options.md" /%} + +### Response + +Resolves to a `SubmissionResult` (from the `defaultRipple` settings change). + +{% raw-partial file="/docs/_snippets/simplexrpl-response-fields.md" /%} + +#### Response values + +`Account.fund` attaches no `intent` output; `intent` is `undefined`. + +### Underlying XRPL transactor + +Funds the account via the network faucet (an off-ledger request, not a submitted transaction), then builds and submits a single [`AccountSet`](https://xrpl.org/docs/references/protocol/transactions/types/accountset) transaction to enable rippling (`defaultRipple`). + +## Example + +```ts +await client.account.fund({ + destination: 'rNewAccount...', +}) +``` diff --git a/docs/simpleXRPL/references/verticals/account/index.md b/docs/simpleXRPL/references/verticals/account/index.md new file mode 100644 index 00000000..11bc90ef --- /dev/null +++ b/docs/simpleXRPL/references/verticals/account/index.md @@ -0,0 +1,21 @@ +--- +seo: + description: The Account vertical in simpleXRPL manages account creation, funding, settings, regular keys, and deposit preauthorization. +labels: + - SDKs +--- + +# Account + +The `Account` vertical handles account creation, funding, and administration. (The class is named `AccountVertical` to avoid colliding with the `Account` record type; it is reached as `client.account`.) + +| Method | Description | +| --- | --- | +| [create](create.md) | Generate a new keypair locally (no transaction). | +| [activate](activate.md) | Activate a created account with operator-funded XRP. | +| [fund](fund.md) | Fund a created account from a testnet/devnet faucet. | +| [set](set.md) | Update account settings and flags. | +| [setRegularKey](setRegularKey.md) | Set or remove the account's regular key. | +| [depositPreauth](depositPreauth.md) | Grant or revoke deposit preauthorization. | +| [retrieve](retrieve.md) | Read an account's on-chain state. | +| [listOffers](listOffers.md) | List the DEX offers placed by an account. | diff --git a/docs/simpleXRPL/references/verticals/account/listOffers.md b/docs/simpleXRPL/references/verticals/account/listOffers.md new file mode 100644 index 00000000..3977449a --- /dev/null +++ b/docs/simpleXRPL/references/verticals/account/listOffers.md @@ -0,0 +1,48 @@ +--- +seo: + description: Account.listOffers lists the open DEX offers placed by an account. Read-only. +labels: + - SDKs +--- + +# account.listOffers() + +[Source](https://github.com/ripple/simpleXRPL/blob/50619258cf753008e8a185eaeb3ceca489e5998a/src/verticals/account.ts#L105) + +List the open DEX offers placed by an account. + +## Signature + +```ts +account.listOffers( + params?: AccountListOffersParams, +): Promise +``` + +### Parameters + +| Parameter | Type | Required | Description | +| --- | --- | --- | --- | +| `account` | `string` | No | The account whose offers to list. Defaults to the primary signer's account. | + +### Response + +Resolves to a `ListOffersResult`: + +| Field | Type | Description | +| --- | --- | --- | +| `data` | `readonly OfferSummary[]` | The shaped open offers. See [`token.listOffers`](../token/listOffers.md#offersummary) for `OfferSummary`. | + +### Underlying XRPL request + +Read-only — no signer is required and nothing is submitted. Queries the ledger with [`account_offers`](https://xrpl.org/docs/references/http-websocket-apis/public-api-methods/account-methods/account_offers). + +## Example + +```ts +const { data } = await client.account.listOffers() + +for (const offer of data) { + console.log(offer.offerSequence, offer.type, offer.amount) +} +``` diff --git a/docs/simpleXRPL/references/verticals/account/retrieve.md b/docs/simpleXRPL/references/verticals/account/retrieve.md new file mode 100644 index 00000000..37f8460e --- /dev/null +++ b/docs/simpleXRPL/references/verticals/account/retrieve.md @@ -0,0 +1,56 @@ +--- +seo: + description: Account.retrieve reads an account's on-chain state — balance, sequence, owner count, and flags. Read-only. +labels: + - SDKs +--- + +# account.retrieve() + +[Source](https://github.com/ripple/simpleXRPL/blob/50619258cf753008e8a185eaeb3ceca489e5998a/src/verticals/account.ts#L93) + +Read an account's on-chain state — XRP balance, sequence, owner count, and flags. + +## Signature + +```ts +account.retrieve( + params?: AccountRetrieveParams, +): Promise +``` + +### Parameters + +| Parameter | Type | Required | Description | +| --- | --- | --- | --- | +| `account` | `string` | No | The account to read. Defaults to the primary signer's account. | + +### Response + +Resolves to an `AccountRetrieveResult`: + +| Field | Type | Description | +| --- | --- | --- | +| `data` | `AccountData` | The point-in-time account snapshot. | + +#### AccountData + +| Field | Type | Description | +| --- | --- | --- | +| `address` | `string` | The account's r-address. | +| `xrpBalance` | `string` | The XRP balance (converted from drops). | +| `sequence` | `number` | The account sequence number. | +| `ownerCount` | `number` | The number of owned ledger objects (drives the reserve). | +| `flags` | `Readonly>` | Account flags as booleans, as reported by `account_flags`. | + +### Underlying XRPL request + +Read-only — no signer is required and nothing is submitted. Queries the ledger with [`account_info`](https://xrpl.org/docs/references/http-websocket-apis/public-api-methods/account-methods/account_info) (flags are resolved via `account_flags`). + +## Example + +```ts +const { data } = await client.account.retrieve() + +console.log(data.xrpBalance) +``` diff --git a/docs/simpleXRPL/references/verticals/account/set.md b/docs/simpleXRPL/references/verticals/account/set.md new file mode 100644 index 00000000..94d3cdbc --- /dev/null +++ b/docs/simpleXRPL/references/verticals/account/set.md @@ -0,0 +1,70 @@ +--- +seo: + description: Account.set updates account settings and flags via an AccountSet transaction. +labels: + - SDKs +--- + +# account.set() + +[Source](https://github.com/ripple/simpleXRPL/blob/50619258cf753008e8a185eaeb3ceca489e5998a/src/verticals/account.ts#L190) + +Update account settings. Flags are named booleans (`true` enables, `false` disables); `transferRate`, `tickSize`, and `domain` are set directly. At least one parameter is required. + +{% admonition type="info" name="Note" %} +A single `AccountSet` can enable at most one flag and disable at most one, so toggling more than one flag in the same direction is rejected — call `set()` once per such change. +{% /admonition %} + +## Signature + +```ts +account.set( + params: AccountSetParams, + options?: AccountWriteOptions, +): Promise> +``` + +### Parameters + +All parameters are optional individually, but at least one must be provided. + +| Parameter | Type | Required | Description | +| --- | --- | --- | --- | +| `noFreeze` | `boolean` | No | Permanently give up the ability to freeze trust lines (irreversible). | +| `clawbackEnabled` | `boolean` | No | Permanently allow this issuer to claw back issued tokens (irreversible). | +| `trustLineLocking` | `boolean` | No | Permanently allow trust-line locking (irreversible). | +| `disableMaster` | `boolean` | No | Permanently disable the master key pair (irreversible). | +| `requireAuth` | `boolean` | No | Require holders to be authorized before they can hold issued tokens. | +| `requireDest` | `boolean` | No | Require a destination tag on incoming payments. | +| `defaultRipple` | `boolean` | No | Enable rippling on trust lines by default. | +| `globalFreeze` | `boolean` | No | Freeze all trust lines issued by this account. | +| `disallowXRP` | `boolean` | No | Disallow incoming XRP payments (advisory). | +| `transferRate` | `number` | No | Transfer fee for issued currencies, as a percentage (`0.5` = 0.5%, range 0–100). | +| `tickSize` | `number` | No | Tick size for offers (3–15, or `0` to disable). | +| `domain` | `string` | No | The account domain, as a plain string (hex-encoded on the ledger). | + +### Options + +{% raw-partial file="/docs/_snippets/simplexrpl-write-options.md" /%} + +### Response + +Resolves to a `SubmissionResult`. + +{% raw-partial file="/docs/_snippets/simplexrpl-response-fields.md" /%} + +#### Response values + +`Account.set` attaches no `intent` output; `intent` is `undefined`. + +### Underlying XRPL transactor + +Builds and submits a single [`AccountSet`](https://xrpl.org/docs/references/protocol/transactions/types/accountset) transaction. + +## Example + +```ts +await client.account.set({ + requireAuth: true, +}) +``` diff --git a/docs/simpleXRPL/references/verticals/account/setRegularKey.md b/docs/simpleXRPL/references/verticals/account/setRegularKey.md new file mode 100644 index 00000000..bd6540a6 --- /dev/null +++ b/docs/simpleXRPL/references/verticals/account/setRegularKey.md @@ -0,0 +1,53 @@ +--- +seo: + description: Account.setRegularKey sets or removes the account's regular key via a SetRegularKey transaction. +labels: + - SDKs +--- + +# account.setRegularKey() + +[Source](https://github.com/ripple/simpleXRPL/blob/50619258cf753008e8a185eaeb3ceca489e5998a/src/verticals/account.ts#L235) + +Set or remove the account's regular key. + +## Signature + +```ts +account.setRegularKey( + params: SetRegularKeyParams = {}, + options?: AccountWriteOptions, +): Promise> +``` + +### Parameters + +| Parameter | Type | Required | Description | +| --- | --- | --- | --- | +| `regularKey` | `string` | No | The regular key r-address to set. Omit to remove the current regular key. | + +### Options + +{% raw-partial file="/docs/_snippets/simplexrpl-write-options.md" /%} + +### Response + +Resolves to a `SubmissionResult`. + +{% raw-partial file="/docs/_snippets/simplexrpl-response-fields.md" /%} + +#### Response values + +`Account.setRegularKey` attaches no `intent` output; `intent` is `undefined`. + +### Underlying XRPL transactor + +Builds and submits a single [`SetRegularKey`](https://xrpl.org/docs/references/protocol/transactions/types/setregularkey) transaction. + +## Example + +```ts +await client.account.setRegularKey({ + regularKey: 'rRegularKey...', +}) +``` diff --git a/docs/simpleXRPL/references/verticals/credential/accept.md b/docs/simpleXRPL/references/verticals/credential/accept.md new file mode 100644 index 00000000..1f048639 --- /dev/null +++ b/docs/simpleXRPL/references/verticals/credential/accept.md @@ -0,0 +1,60 @@ +--- +seo: + description: Credential.accept accepts a credential issued to the calling account via a CredentialAccept transaction. +labels: + - SDKs +--- + +# credential.accept() + +[Source](https://github.com/ripple/simpleXRPL/blob/50619258cf753008e8a185eaeb3ceca489e5998a/src/verticals/credential.ts#L103) + +Accept a credential issued to the calling account. The calling account is the holder. + +## Signature + +```ts +credential.accept( + params: CredentialAcceptParams, + options?: CredentialWriteOptions, +): Promise`. + +{% raw-partial file="/docs/_snippets/simplexrpl-response-fields.md" /%} + +#### Response values + +For `Credential.accept`, the `intent` echoes: + +| Field | Type | Description | +| --- | --- | --- | +| `issuer` | `string` | The issuer r-address of the accepted credential. | +| `credType` | `string` | The credential type that was accepted. | + +### Underlying XRPL transactor + +Builds and submits a single [`CredentialAccept`](https://xrpl.org/docs/references/protocol/transactions/types/credentialaccept) transaction. + +## Example + +```ts +await client.credential.accept({ + credType: 'KYC', + issuer: 'rIssuer...', +}) +``` diff --git a/docs/simpleXRPL/references/verticals/credential/delete.md b/docs/simpleXRPL/references/verticals/credential/delete.md new file mode 100644 index 00000000..792d5d9c --- /dev/null +++ b/docs/simpleXRPL/references/verticals/credential/delete.md @@ -0,0 +1,60 @@ +--- +seo: + description: Credential.delete deletes an on-ledger credential, as either its issuer or its holder, via a CredentialDelete transaction. +labels: + - SDKs +--- + +# credential.delete() + +[Source](https://github.com/ripple/simpleXRPL/blob/50619258cf753008e8a185eaeb3ceca489e5998a/src/verticals/credential.ts#L133) + +Delete a credential, as either its issuer or its holder. + +## Signature + +```ts +credential.delete( + params: CredentialDeleteParams, + options?: CredentialWriteOptions, +): Promise`. + +{% raw-partial file="/docs/_snippets/simplexrpl-response-fields.md" /%} + +#### Response values + +For `Credential.delete`, the `intent` echoes: + +| Field | Type | Description | +| --- | --- | --- | +| `credType` | `string` | The credential type that was deleted. | + +### Underlying XRPL transactor + +Builds and submits a single [`CredentialDelete`](https://xrpl.org/docs/references/protocol/transactions/types/credentialdelete) transaction. + +## Example + +```ts +await client.credential.delete({ + credType: 'KYC', + issuer: 'rIssuer...', +}) +``` diff --git a/docs/simpleXRPL/references/verticals/credential/index.md b/docs/simpleXRPL/references/verticals/credential/index.md new file mode 100644 index 00000000..57e53297 --- /dev/null +++ b/docs/simpleXRPL/references/verticals/credential/index.md @@ -0,0 +1,18 @@ +--- +seo: + description: The Credential vertical in simpleXRPL issues, accepts, and deletes on-ledger credentials. +labels: + - SDKs +--- + +# Credential + +The `Credential` vertical issues, accepts, and deletes on-ledger [credentials](https://xrpl.org/docs/concepts/decentralized-storage/credentials). + +| Method | Description | +| --- | --- | +| [issue](issue.md) | Issue a credential to a destination account. | +| [accept](accept.md) | Accept a credential issued to the calling account. | +| [delete](delete.md) | Delete a credential, as either its issuer or its holder. | +| [retrieve](retrieve.md) | Read a single credential. | +| [list](list.md) | List the credentials an account holds or issued. | diff --git a/docs/simpleXRPL/references/verticals/credential/issue.md b/docs/simpleXRPL/references/verticals/credential/issue.md new file mode 100644 index 00000000..832f1e69 --- /dev/null +++ b/docs/simpleXRPL/references/verticals/credential/issue.md @@ -0,0 +1,62 @@ +--- +seo: + description: Credential.issue issues an on-ledger credential to a destination account via a CredentialCreate transaction. +labels: + - SDKs +--- + +# credential.issue() + +[Source](https://github.com/ripple/simpleXRPL/blob/50619258cf753008e8a185eaeb3ceca489e5998a/src/verticals/credential.ts#L67) + +Issue a credential to a destination account. The calling account is the issuer. + +## Signature + +```ts +credential.issue( + params: CredentialIssueParams, + options?: CredentialWriteOptions, +): Promise`. + +{% raw-partial file="/docs/_snippets/simplexrpl-response-fields.md" /%} + +#### Response values + +For `Credential.issue`, the `intent` echoes: + +| Field | Type | Description | +| --- | --- | --- | +| `destination` | `string` | The destination (holder) r-address the credential was issued to. | +| `credType` | `string` | The credential type that was issued. | + +### Underlying XRPL transactor + +Builds and submits a single [`CredentialCreate`](https://xrpl.org/docs/references/protocol/transactions/types/credentialcreate) transaction. + +## Example + +```ts +await client.credential.issue({ + destination: 'rHolder...', + credType: 'KYC', +}) +``` diff --git a/docs/simpleXRPL/references/verticals/credential/list.md b/docs/simpleXRPL/references/verticals/credential/list.md new file mode 100644 index 00000000..258e88cd --- /dev/null +++ b/docs/simpleXRPL/references/verticals/credential/list.md @@ -0,0 +1,50 @@ +--- +seo: + description: Credential.list lists the credentials an account holds or issued. Read-only. +labels: + - SDKs +--- + +# credential.list() + +[Source](https://github.com/ripple/simpleXRPL/blob/50619258cf753008e8a185eaeb3ceca489e5998a/src/verticals/credential.ts#L54) + +List credentials an account holds (default) or issued. + +## Signature + +```ts +credential.list( + params?: CredentialListParams, +): Promise +``` + +### Parameters + +| Parameter | Type | Required | Description | +| --- | --- | --- | --- | +| `role` | `'holder' \| 'issuer'` | No | Query as `holder` (default) or `issuer`. | +| `account` | `string` | No | The account whose credentials to list. Defaults to the primary signer's account. | + +### Response + +Resolves to a `CredentialListResult`, where `credentials[i]` corresponds to `data[i]`: + +| Field | Type | Description | +| --- | --- | --- | +| `credentials` | `readonly CredentialRef[]` | The identifier of each credential (`credType`, `issuer`, `holder`). | +| `data` | `readonly CredentialData[]` | The shaped credentials. See [`credential.retrieve`](retrieve.md#credentialdata) for `CredentialData`. | + +### Underlying XRPL request + +Read-only — no signer is required and nothing is submitted. Queries the ledger with [`account_objects`](https://xrpl.org/docs/references/http-websocket-apis/public-api-methods/account-methods/account_objects). + +## Example + +```ts +const { data } = await client.credential.list({ role: 'holder' }) + +for (const cred of data) { + console.log(cred.credType, cred.accepted) +} +``` diff --git a/docs/simpleXRPL/references/verticals/credential/retrieve.md b/docs/simpleXRPL/references/verticals/credential/retrieve.md new file mode 100644 index 00000000..08161097 --- /dev/null +++ b/docs/simpleXRPL/references/verticals/credential/retrieve.md @@ -0,0 +1,65 @@ +--- +seo: + description: Credential.retrieve reads a single credential by type and issuer. Read-only. +labels: + - SDKs +--- + +# credential.retrieve() + +[Source](https://github.com/ripple/simpleXRPL/blob/50619258cf753008e8a185eaeb3ceca489e5998a/src/verticals/credential.ts#L42) + +Retrieve a single credential by type and issuer (point-in-time). + +## Signature + +```ts +credential.retrieve( + params: CredentialRetrieveParams, +): Promise +``` + +### Parameters + +| Parameter | Type | Required | Description | +| --- | --- | --- | --- | +| `credType` | `string` | Yes | The credential type. | +| `issuer` | `string` | Yes | The issuer r-address. | +| `account` | `string` | No | The holder (subject). Defaults to the primary signer's account. | + +### Response + +Resolves to a `CredentialRetrieveResult`: + +| Field | Type | Description | +| --- | --- | --- | +| `credType` | `string` | The credential type. | +| `issuer` | `string` | The issuer r-address. | +| `holder` | `string` | The holder (subject) r-address. | +| `data` | `CredentialData \| undefined` | The credential snapshot, or `undefined` if none exists. | + +#### CredentialData + +| Field | Type | Description | +| --- | --- | --- | +| `credType` | `string` | The credential type. | +| `issuer` | `string` | The issuer r-address. | +| `holder` | `string` | The holder (subject) r-address. | +| `accepted` | `boolean` | Whether the holder has accepted the credential. | +| `uri` | `string` _(optional)_ | The optional URI (decoded from hex). | +| `expiration` | `number` _(optional)_ | Expiration (seconds since the Ripple epoch), if set. | + +### Underlying XRPL request + +Read-only — no signer is required and nothing is submitted. Queries the ledger with [`ledger_entry`](https://xrpl.org/docs/references/http-websocket-apis/public-api-methods/ledger-methods/ledger_entry). + +## Example + +```ts +const { data } = await client.credential.retrieve({ + credType: 'KYC', + issuer: 'rIssuer...', +}) + +console.log(data?.accepted) +``` diff --git a/docs/simpleXRPL/references/verticals/domain/create.md b/docs/simpleXRPL/references/verticals/domain/create.md new file mode 100644 index 00000000..f402f705 --- /dev/null +++ b/docs/simpleXRPL/references/verticals/domain/create.md @@ -0,0 +1,66 @@ +--- +seo: + description: Domain.create creates a new permissioned domain via a PermissionedDomainSet transaction. +labels: + - SDKs +--- + +# domain.create() + +[Source](https://github.com/ripple/simpleXRPL/blob/50619258cf753008e8a185eaeb3ceca489e5998a/src/verticals/domain.ts#L70) + +Create a new permissioned domain. + +## Signature + +```ts +domain.create( + params: DomainCreateParams, + options?: DomainWriteOptions, +): Promise> +``` + +### Parameters + +| Parameter | Type | Required | Description | +| --- | --- | --- | --- | +| `credList` | `AcceptedCredential[]` | Yes | The credentials the domain accepts (at least one). | + +Each `AcceptedCredential` is: + +| Field | Type | Required | Description | +| --- | --- | --- | --- | +| `issuer` | `string` | Yes | The issuer r-address. | +| `credType` | `string` | Yes | The credential type, as a plain string (hex-encoded on the ledger). | + +### Options + +{% raw-partial file="/docs/_snippets/simplexrpl-write-options.md" /%} + +### Response + +Resolves to a `SubmissionResult`. + +{% raw-partial file="/docs/_snippets/simplexrpl-response-fields.md" /%} + +#### Response values + +For `Domain.create`, the `intent` (`DomainIntent`) carries: + +| Field | Type | Description | +| --- | --- | --- | +| `domainID` | `string` | The id of the newly created domain, discovered from the transaction result. | + +### Underlying XRPL transactor + +Builds and submits a single [`PermissionedDomainSet`](https://xrpl.org/docs/references/protocol/transactions/types/permissioneddomainset) transaction (with no domain id, creating a new domain). + +## Example + +```ts +const { intent } = await client.domain.create({ + credList: [{ issuer: 'rIssuer...', credType: 'KYC' }], +}) + +console.log(intent.domainID) +``` diff --git a/docs/simpleXRPL/references/verticals/domain/delete.md b/docs/simpleXRPL/references/verticals/domain/delete.md new file mode 100644 index 00000000..134842c7 --- /dev/null +++ b/docs/simpleXRPL/references/verticals/domain/delete.md @@ -0,0 +1,57 @@ +--- +seo: + description: Domain.delete deletes a permissioned domain via a PermissionedDomainDelete transaction. +labels: + - SDKs +--- + +# domain.delete() + +[Source](https://github.com/ripple/simpleXRPL/blob/50619258cf753008e8a185eaeb3ceca489e5998a/src/verticals/domain.ts#L123) + +Delete a permissioned domain. + +## Signature + +```ts +domain.delete( + params: DomainDeleteParams, + options?: DomainWriteOptions, +): Promise> +``` + +### Parameters + +| Parameter | Type | Required | Description | +| --- | --- | --- | --- | +| `domain` | `string` | Yes | The domain id to delete. | + +### Options + +{% raw-partial file="/docs/_snippets/simplexrpl-write-options.md" /%} + +### Response + +Resolves to a `SubmissionResult`. + +{% raw-partial file="/docs/_snippets/simplexrpl-response-fields.md" /%} + +#### Response values + +For `Domain.delete`, the `intent` (`DomainIntent`) echoes: + +| Field | Type | Description | +| --- | --- | --- | +| `domainID` | `string` | The domain id that was deleted. | + +### Underlying XRPL transactor + +Builds and submits a single [`PermissionedDomainDelete`](https://xrpl.org/docs/references/protocol/transactions/types/permissioneddomaindelete) transaction. + +## Example + +```ts +await client.domain.delete({ + domain: 'A1B2...', +}) +``` diff --git a/docs/simpleXRPL/references/verticals/domain/index.md b/docs/simpleXRPL/references/verticals/domain/index.md new file mode 100644 index 00000000..a288fc3a --- /dev/null +++ b/docs/simpleXRPL/references/verticals/domain/index.md @@ -0,0 +1,18 @@ +--- +seo: + description: The Domain vertical in simpleXRPL creates, updates, and deletes permissioned domains. +labels: + - SDKs +--- + +# Domain + +The `Domain` vertical creates, updates, and deletes [permissioned domains](https://xrpl.org/docs/concepts/tokens/decentralized-exchange/permissioned-dexes). + +| Method | Description | +| --- | --- | +| [create](create.md) | Create a new permissioned domain. | +| [setCredentials](setCredentials.md) | Update the accepted credentials of an existing domain. | +| [delete](delete.md) | Delete a permissioned domain. | +| [retrieve](retrieve.md) | Read a single permissioned domain by id. | +| [list](list.md) | List the permissioned domains an account owns. | diff --git a/docs/simpleXRPL/references/verticals/domain/list.md b/docs/simpleXRPL/references/verticals/domain/list.md new file mode 100644 index 00000000..e4cfa2bc --- /dev/null +++ b/docs/simpleXRPL/references/verticals/domain/list.md @@ -0,0 +1,49 @@ +--- +seo: + description: Domain.list lists every permissioned domain owned by an account. Read-only. +labels: + - SDKs +--- + +# domain.list() + +[Source](https://github.com/ripple/simpleXRPL/blob/50619258cf753008e8a185eaeb3ceca489e5998a/src/verticals/domain.ts#L59) + +List every permissioned domain owned by an account. + +## Signature + +```ts +domain.list( + params?: DomainListParams +): Promise +``` + +### Parameters + +| Parameter | Type | Required | Description | +| --- | --- | --- | --- | +| `account` | `string` | No | The owner whose domains to list. Defaults to the primary signer's account. | + +### Response + +Resolves to a `DomainListResult`, where `domains[i]` corresponds to `data[i]`: + +| Field | Type | Description | +| --- | --- | --- | +| `domains` | `readonly string[]` | The domain id of each owned domain. | +| `data` | `readonly DomainData[]` | The shaped domains. See [`domain.retrieve`](retrieve.md#domaindata) for `DomainData`. | + +### Underlying XRPL request + +Read-only — no signer is required and nothing is submitted. Queries the ledger with [`account_objects`](https://xrpl.org/docs/references/http-websocket-apis/public-api-methods/account-methods/account_objects). + +## Example + +```ts +const { data } = await client.domain.list() + +for (const domain of data) { + console.log(domain.domainID) +} +``` diff --git a/docs/simpleXRPL/references/verticals/domain/retrieve.md b/docs/simpleXRPL/references/verticals/domain/retrieve.md new file mode 100644 index 00000000..de2783a2 --- /dev/null +++ b/docs/simpleXRPL/references/verticals/domain/retrieve.md @@ -0,0 +1,57 @@ +--- +seo: + description: Domain.retrieve reads a permissioned domain by id. Read-only. +labels: + - SDKs +--- + +# domain.retrieve() + +[Source](https://github.com/ripple/simpleXRPL/blob/50619258cf753008e8a185eaeb3ceca489e5998a/src/verticals/domain.ts#L47) + +Retrieve a permissioned domain by id (point-in-time). + +## Signature + +```ts +domain.retrieve( + params: DomainRetrieveParams, +): Promise +``` + +### Parameters + +| Parameter | Type | Required | Description | +| --- | --- | --- | --- | +| `domainID` | `string` | Yes | The domain id to fetch. | + +### Response + +Resolves to a `DomainRetrieveResult`: + +| Field | Type | Description | +| --- | --- | --- | +| `domainID` | `string` | The queried domain id. | +| `data` | `DomainData \| undefined` | The domain snapshot, or `undefined` if no such domain exists. | + +#### DomainData + +| Field | Type | Description | +| --- | --- | --- | +| `domainID` | `string` | The domain's on-chain id. | +| `owner` | `string` | The owning account's r-address. | +| `credList` | `readonly AcceptedCredential[]` | The credentials the domain accepts (each `{ issuer, credType }`, credential types decoded from hex). | + +### Underlying XRPL request + +Read-only — no signer is required and nothing is submitted. Queries the ledger with [`ledger_entry`](https://xrpl.org/docs/references/http-websocket-apis/public-api-methods/ledger-methods/ledger_entry). + +## Example + +```ts +const { data } = await client.domain.retrieve({ + domainID: 'A1B2...', +}) + +console.log(data?.owner) +``` diff --git a/docs/simpleXRPL/references/verticals/domain/setCredentials.md b/docs/simpleXRPL/references/verticals/domain/setCredentials.md new file mode 100644 index 00000000..5a507393 --- /dev/null +++ b/docs/simpleXRPL/references/verticals/domain/setCredentials.md @@ -0,0 +1,66 @@ +--- +seo: + description: Domain.setCredentials updates the accepted credentials of an existing permissioned domain via a PermissionedDomainSet transaction. +labels: + - SDKs +--- + +# domain.setCredentials() + +[Source](https://github.com/ripple/simpleXRPL/blob/50619258cf753008e8a185eaeb3ceca489e5998a/src/verticals/domain.ts#L96) + +Update the accepted credentials of an existing permissioned domain. + +## Signature + +```ts +domain.setCredentials( + params: DomainSetCredentialsParams, + options?: DomainWriteOptions, +): Promise> +``` + +### Parameters + +| Parameter | Type | Required | Description | +| --- | --- | --- | --- | +| `domain` | `string` | Yes | The domain id to update. | +| `credList` | `AcceptedCredential[]` | Yes | The credentials the domain accepts (at least one). | + +Each `AcceptedCredential` is: + +| Field | Type | Required | Description | +| --- | --- | --- | --- | +| `issuer` | `string` | Yes | The issuer r-address. | +| `credType` | `string` | Yes | The credential type, as a plain string (hex-encoded on the ledger). | + +### Options + +{% raw-partial file="/docs/_snippets/simplexrpl-write-options.md" /%} + +### Response + +Resolves to a `SubmissionResult`. + +{% raw-partial file="/docs/_snippets/simplexrpl-response-fields.md" /%} + +#### Response values + +For `Domain.setCredentials`, the `intent` (`DomainIntent`) echoes: + +| Field | Type | Description | +| --- | --- | --- | +| `domainID` | `string` | The domain id that was updated. | + +### Underlying XRPL transactor + +Builds and submits a single [`PermissionedDomainSet`](https://xrpl.org/docs/references/protocol/transactions/types/permissioneddomainset) transaction naming the existing domain id. + +## Example + +```ts +await client.domain.setCredentials({ + domain: 'A1B2...', + credList: [{ issuer: 'rIssuer...', credType: 'KYC' }], +}) +``` diff --git a/docs/simpleXRPL/references/verticals/index.md b/docs/simpleXRPL/references/verticals/index.md new file mode 100644 index 00000000..bbcc68c8 --- /dev/null +++ b/docs/simpleXRPL/references/verticals/index.md @@ -0,0 +1,25 @@ +--- +seo: + description: A vertical is a domain-specific class of business-intent operations in simpleXRPL — one per area of XRPL functionality, reached off the client. +labels: + - SDKs +--- + +# Verticals + +A **vertical** is a domain-specific class that groups related operations — one per area of XRPL functionality. Each vertical's methods are the _business-intent verbs_ for that domain (`token.issue(...)`, `iou.transfer(...)`), and each vertical is reached off the client under a lowercase name (`client.token`, `client.iou`). The term contrasts with _horizontal_ operations that cut across domains, such as payments and batch transactions. + +Most vertical methods submit a transaction and resolve to a `Promise>`, where `T` is the method's typed [intent output](../index.md#results-and-handles); they also accept an optional second argument to target a non-primary account and override the fee. (A few helpers differ — for example, `Account.create` generates a keypair and returns synchronously.) Each vertical's page lists its methods; every method has its own page with parameters, response, and the underlying XRPL transactor(s). + +| Vertical | Reached as | What it does | +| --- | --- | --- | +| [XRP](xrp/index.md) | `client.xrp` | Native XRP payments. | +| [Token](token/index.md) | `client.token` | Issue and manage [Multi-Purpose Tokens (MPTs)](https://xrpl.org/docs/concepts/tokens/fungible-tokens/multi-purpose-tokens) and place DEX offers. | +| [IOU](iou/index.md) | `client.iou` | Issue and manage trust-line-based issued currencies. | +| [Credential](credential/index.md) | `client.credential` | Issue, accept, and delete on-ledger [credentials](https://xrpl.org/docs/concepts/decentralized-storage/credentials). | +| [Domain](domain/index.md) | `client.domain` | Create, update, and delete [permissioned domains](https://xrpl.org/docs/concepts/tokens/decentralized-exchange/permissioned-dexes). | +| [Account](account/index.md) | `client.account` | Account creation, funding, and administration. | + +{% admonition type="info" name="Note" %} +Where a vertical's natural class name would collide with a type, the class is suffixed — the Account vertical's class is `AccountVertical` — but it is still reached as `client.account`. +{% /admonition %} diff --git a/docs/simpleXRPL/references/verticals/iou/authorize.md b/docs/simpleXRPL/references/verticals/iou/authorize.md new file mode 100644 index 00000000..f3e88bac --- /dev/null +++ b/docs/simpleXRPL/references/verticals/iou/authorize.md @@ -0,0 +1,63 @@ +--- +seo: + description: IOU.authorize authorizes a holder to hold an IOU via a TrustSet transaction with the authorize flag. +labels: + - SDKs +--- + +# iou.authorize() + +[Source](https://github.com/ripple/simpleXRPL/blob/50619258cf753008e8a185eaeb3ceca489e5998a/src/verticals/iou.ts#L152) + +Grant authorization for a holder to hold this IOU. Only meaningful when the issuer's account has `asfRequireAuth` set. + +{% admonition type="info" name="Note" %} +There is no matching `unauthorize`: the underlying authorize flag is one-way and cannot be cleared once set. To reversibly block a trust line, use [`IOU.lock`](lock.md) instead. +{% /admonition %} + +## Signature + +```ts +iou.authorize( + params: IOUAuthorizeParams, + options?: IOUWriteOptions, +): Promise> +``` + +### Parameters + +| Parameter | Type | Required | Description | +| --- | --- | --- | --- | +| `ticker` | `string` | Yes | The currency code (3-character ISO-4217-style or 40-character hex; other codes are auto-encoded to hex). | +| `holder` | `string` | Yes | The holder's r-address being authorized. | + +### Options + +{% raw-partial file="/docs/_snippets/simplexrpl-write-options.md" /%} + +### Response + +Resolves to a `SubmissionResult`. + +{% raw-partial file="/docs/_snippets/simplexrpl-response-fields.md" /%} + +#### Response values + +For `IOU.authorize`, the `intent` (`IOUAuthorizeIntent`) echoes: + +| Field | Type | Description | +| --- | --- | --- | +| `holder` | `string` | The holder's r-address that was authorized. | + +### Underlying XRPL transactor + +Builds and submits a single [`TrustSet`](https://xrpl.org/docs/references/protocol/transactions/types/trustset) transaction with the authorize flag set. + +## Example + +```ts +await client.iou.authorize({ + ticker: 'USD', + holder: 'rHolder...', +}) +``` diff --git a/docs/simpleXRPL/references/verticals/iou/buyOffer.md b/docs/simpleXRPL/references/verticals/iou/buyOffer.md new file mode 100644 index 00000000..6e578c31 --- /dev/null +++ b/docs/simpleXRPL/references/verticals/iou/buyOffer.md @@ -0,0 +1,70 @@ +--- +seo: + description: IOU.buyOffer places a DEX order to acquire more of this IOU via an OfferCreate transaction. +labels: + - SDKs +--- + +# iou.buyOffer() + +[Source](https://github.com/ripple/simpleXRPL/blob/50619258cf753008e8a185eaeb3ceca489e5998a/src/verticals/iou.ts#L303) + +Place an order on the DEX to acquire more of this IOU. + +## Signature + +```ts +iou.buyOffer( + params: IOUOfferParams, + options?: IOUWriteOptions, +): Promise> +``` + +### Parameters + +| Parameter | Type | Required | Description | +| --- | --- | --- | --- | +| `ticker` | `string` | Yes | The currency code (3-character ISO-4217-style or 40-character hex; other codes are auto-encoded to hex). | +| `amount` | `number` | Yes | The number of units of this IOU to buy. | +| `orderType` | `IOUOrderType` | Yes | The order type: `'limit'`, `'market'`, `'fok'`, or `'passive'`. | +| `price` | `IOUOfferPrice` | Yes | What's offered in payment — XRP, an MPT, or another IOU (see below). | +| `domainID` | `string` | No | Restrict the offer to a permissioned domain. Omit for the open DEX. | +| `hybrid` | `boolean` | No | Whether a domain-scoped offer also works the open DEX. Only meaningful with `domainID`; defaults to `true` when `domainID` is set. | +| `offerSequence` | `number` | No | A prior offer sequence to replace. | + +`price` (`IOUOfferPrice`) is one of: + +| Shape | Description | +| --- | --- | +| `{ currency: 'XRP'; amount: number }` | Priced in XRP. | +| `{ mptIssuanceId: string; amount: number }` | Priced in an MPT. | +| `{ ticker: string; issuer: string; amount: number }` | Priced in another IOU. | + +### Options + +{% raw-partial file="/docs/_snippets/simplexrpl-write-options.md" /%} + +### Response + +Resolves to a `SubmissionResult`. + +{% raw-partial file="/docs/_snippets/simplexrpl-response-fields.md" /%} + +#### Response values + +`IOU.buyOffer` attaches no `intent` output; `intent` is `undefined`. + +### Underlying XRPL transactor + +Builds and submits a single [`OfferCreate`](https://xrpl.org/docs/references/protocol/transactions/types/offercreate) transaction. Throws an `IntentValidationError` if `price` is MPT-denominated. + +## Example + +```ts +await client.iou.buyOffer({ + ticker: 'USD', + amount: 100, + orderType: 'limit', + price: { currency: 'XRP', amount: 50 }, +}) +``` diff --git a/docs/simpleXRPL/references/verticals/iou/cancelOffer.md b/docs/simpleXRPL/references/verticals/iou/cancelOffer.md new file mode 100644 index 00000000..f859a578 --- /dev/null +++ b/docs/simpleXRPL/references/verticals/iou/cancelOffer.md @@ -0,0 +1,57 @@ +--- +seo: + description: IOU.cancelOffer cancels a standing DEX offer placed by the issuer via an OfferCancel transaction. +labels: + - SDKs +--- + +# iou.cancelOffer() + +[Source](https://github.com/ripple/simpleXRPL/blob/50619258cf753008e8a185eaeb3ceca489e5998a/src/verticals/iou.ts#L335) + +Cancel a standing offer placed by this IOU's issuer. + +## Signature + +```ts +iou.cancelOffer( + params: IOUCancelOfferParams, + options?: IOUWriteOptions, +): Promise`. + +{% raw-partial file="/docs/_snippets/simplexrpl-response-fields.md" /%} + +#### Response values + +For `IOU.cancelOffer`, the `intent` echoes: + +| Field | Type | Description | +| --- | --- | --- | +| `offerSequence` | `number` | The sequence number of the offer that was canceled. | + +### Underlying XRPL transactor + +Builds and submits a single [`OfferCancel`](https://xrpl.org/docs/references/protocol/transactions/types/offercancel) transaction. + +## Example + +```ts +await client.iou.cancelOffer({ + offerSequence: 42, +}) +``` diff --git a/docs/simpleXRPL/references/verticals/iou/clawback.md b/docs/simpleXRPL/references/verticals/iou/clawback.md new file mode 100644 index 00000000..3b3234f1 --- /dev/null +++ b/docs/simpleXRPL/references/verticals/iou/clawback.md @@ -0,0 +1,66 @@ +--- +seo: + description: IOU.clawback reclaims a holder's balance back to the issuer via a Clawback transaction. +labels: + - SDKs +--- + +# iou.clawback() + +[Source](https://github.com/ripple/simpleXRPL/blob/50619258cf753008e8a185eaeb3ceca489e5998a/src/verticals/iou.ts#L234) + +Reclaim a holder's balance back to the issuer. + +{% admonition type="info" name="Note" %} +Verifies the issuer has `asfAllowTrustLineClawback` enabled first (a ledger read), throwing a clear error if not. That flag can only be enabled before the issuer owns any trust lines, offers, or other ledger objects, which this SDK does not itself pre-check. +{% /admonition %} + +## Signature + +```ts +iou.clawback( + params: IOUClawbackParams, + options?: IOUWriteOptions, +): Promise> +``` + +### Parameters + +| Parameter | Type | Required | Description | +| --- | --- | --- | --- | +| `ticker` | `string` | Yes | The currency code (3-character ISO-4217-style or 40-character hex; other codes are auto-encoded to hex). | +| `holder` | `string` | Yes | The holder's r-address to claw the currency back from. | +| `amount` | `number` | Yes | The amount to claw back. | + +### Options + +{% raw-partial file="/docs/_snippets/simplexrpl-write-options.md" /%} + +### Response + +Resolves to a `SubmissionResult`. + +{% raw-partial file="/docs/_snippets/simplexrpl-response-fields.md" /%} + +#### Response values + +For `IOU.clawback`, the `intent` (`IOUClawbackIntent`) echoes: + +| Field | Type | Description | +| --- | --- | --- | +| `holder` | `string` | The holder's r-address clawed back from. | +| `amount` | `number` | The amount clawed back. | + +### Underlying XRPL transactor + +Builds and submits a single [`Clawback`](https://xrpl.org/docs/references/protocol/transactions/types/clawback) transaction. + +## Example + +```ts +await client.iou.clawback({ + ticker: 'USD', + holder: 'rHolder...', + amount: 50, +}) +``` diff --git a/docs/simpleXRPL/references/verticals/iou/index.md b/docs/simpleXRPL/references/verticals/iou/index.md new file mode 100644 index 00000000..0944469e --- /dev/null +++ b/docs/simpleXRPL/references/verticals/iou/index.md @@ -0,0 +1,25 @@ +--- +seo: + description: The IOU vertical in simpleXRPL issues and manages trust-line-based issued currencies. +labels: + - SDKs +--- + +# IOU + +The `IOU` vertical issues and manages trust-line-based issued currencies. Each verb acts as the IOU's **issuer** — the account resolved from `from` (default: the primary signer's account) signs, and its address is the currency issuer. Callers name their own counterparty (`holder` / `destination`) per call. + +| Method | Description | +| --- | --- | +| [issue](issue.md) | Bootstrap a new trust-line-based IOU between two environment-sourced accounts. | +| [transfer](transfer.md) | Send IOU value to a destination account. | +| [authorize](authorize.md) | Authorize a holder to hold this IOU. | +| [lock](lock.md) | Freeze a holder's trust line (individual + deep freeze). | +| [unlock](unlock.md) | Restore a frozen holder's trust line. | +| [clawback](clawback.md) | Reclaim a holder's balance back to the issuer. | +| [buyOffer](buyOffer.md) | Place a DEX order to acquire this IOU. | +| [sellOffer](sellOffer.md) | Place a DEX order to sell this IOU. | +| [cancelOffer](cancelOffer.md) | Cancel a standing offer. | +| [retrieve](retrieve.md) | Read a single IOU trust line. | +| [list](list.md) | List an account's IOU trust lines. | +| [listOffers](listOffers.md) | List all open offers in the market for an IOU. | diff --git a/docs/simpleXRPL/references/verticals/iou/issue.md b/docs/simpleXRPL/references/verticals/iou/issue.md new file mode 100644 index 00000000..09423776 --- /dev/null +++ b/docs/simpleXRPL/references/verticals/iou/issue.md @@ -0,0 +1,63 @@ +--- +seo: + description: IOU.issue bootstraps a new trust-line-based IOU between two environment-sourced accounts via AccountSet and TrustSet transactions. +labels: + - SDKs +--- + +# iou.issue() + +[Source](https://github.com/ripple/simpleXRPL/blob/50619258cf753008e8a185eaeb3ceca489e5998a/src/verticals/iou.ts#L83) + +Generate a new trust-line-based IOU between two developer-controlled accounts sourced from the environment. + +{% admonition type="info" name="Note" %} +Unlike the other IOU verbs, `issue` takes no `options`. It bootstraps both accounts from the environment: it reads `XRPL_ISSUER_SEED` and `XRPL_HOT_WALLET_SEED`, has the issuer enable rippling, then has the hot wallet extend trust up to the maximum limit. No `Payment` runs, so no value exists yet — use [`IOU.transfer`](transfer.md) to send some. +{% /admonition %} + +## Signature + +```ts +iou.issue( + params: IOUIssueParams, +): Promise> +``` + +### Parameters + +| Parameter | Type | Required | Description | +| --- | --- | --- | --- | +| `ticker` | `string` | Yes | The currency code: a 3-character ISO-4217-style code or a 40-character hex code. Any other code (e.g. a 5-character ticker) is auto-encoded to the 40-character hex form. | + +### Response + +Resolves to a `SubmissionResult` (from the final step). + +{% raw-partial file="/docs/_snippets/simplexrpl-response-fields.md" /%} + +#### Response values + +For `IOU.issue`, the `intent` (`IOUIssueIntent`) carries: + +| Field | Type | Description | +| --- | --- | --- | +| `iouID` | `string` | The currency code and issuer of the new IOU, e.g. `USD.rIssuer...`. | + +### Underlying XRPL transactors + +Runs as an ordered, multi-step sequence (no rollback on partial failure): + +1. [`AccountSet`](https://xrpl.org/docs/references/protocol/transactions/types/accountset) — the issuer enables rippling (`defaultRipple`). +2. [`TrustSet`](https://xrpl.org/docs/references/protocol/transactions/types/trustset) — the hot wallet extends trust to the issuer, up to the maximum limit. + +Throws an `IntentValidationError` if the required seeds aren't set, or a `MultiStepFailureError` if either step fails. + +## Example + +```ts +const { intent } = await client.iou.issue({ + ticker: 'USD', +}) + +console.log(intent.iouID) +``` diff --git a/docs/simpleXRPL/references/verticals/iou/list.md b/docs/simpleXRPL/references/verticals/iou/list.md new file mode 100644 index 00000000..75c32d76 --- /dev/null +++ b/docs/simpleXRPL/references/verticals/iou/list.md @@ -0,0 +1,50 @@ +--- +seo: + description: IOU.list lists every IOU trust line for an account. Read-only. +labels: + - SDKs +--- + +# iou.list() + +[Source](https://github.com/ripple/simpleXRPL/blob/50619258cf753008e8a185eaeb3ceca489e5998a/src/verticals/iou.ts#L119) + +List every IOU trust line for an account. + +## Signature + +```ts +iou.list( + params?: IOUListParams +): Promise +``` + +### Parameters + +| Parameter | Type | Required | Description | +| --- | --- | --- | --- | +| `role` | `'holder' \| 'issuer'` | No | Query as `holder` (default) or `issuer`. | +| `account` | `string` | No | The account whose trust lines to list. Defaults to the primary signer's account. | + +### Response + +Resolves to an `IOUListResult`, where `ious[i]` corresponds to `data[i]`: + +| Field | Type | Description | +| --- | --- | --- | +| `ious` | `readonly string[]` | The `iouID` of each line, composable into the write verbs. | +| `data` | `readonly IOUTrustLine[]` | The shaped trust lines. See [`iou.retrieve`](retrieve.md#ioutrustline) for `IOUTrustLine`. | + +### Underlying XRPL request + +Read-only — no signer is required and nothing is submitted. Queries the ledger with [`account_lines`](https://xrpl.org/docs/references/http-websocket-apis/public-api-methods/account-methods/account_lines). + +## Example + +```ts +const { data } = await client.iou.list() + +for (const line of data) { + console.log(line.currency, line.balance) +} +``` diff --git a/docs/simpleXRPL/references/verticals/iou/listOffers.md b/docs/simpleXRPL/references/verticals/iou/listOffers.md new file mode 100644 index 00000000..b72f7bb5 --- /dev/null +++ b/docs/simpleXRPL/references/verticals/iou/listOffers.md @@ -0,0 +1,52 @@ +--- +seo: + description: IOU.listOffers lists all open offers in the market for an IOU (both sides of the order book). Read-only. +labels: + - SDKs +--- + +# iou.listOffers() + +[Source](https://github.com/ripple/simpleXRPL/blob/50619258cf753008e8a185eaeb3ceca489e5998a/src/verticals/iou.ts#L130) + +List all open offers in the market for this IOU (both sides), tagged buy/sell relative to it. + +{% admonition type="info" name="Note" %} +Unlike [`token.listOffers`](../token/listOffers.md) and [`account.listOffers`](../account/listOffers.md) — which list a single **account's own** resting offers — `iou.listOffers` reads the whole **order book** for the IOU across all accounts. +{% /admonition %} + +## Signature + +```ts +iou.listOffers( + params: IOUListOffersParams, +): Promise +``` + +### Parameters + +| Parameter | Type | Required | Description | +| --- | --- | --- | --- | +| `ticker` | `string` | Yes | The IOU currency code to anchor the book on. | +| `issuer` | `string` | Yes | The IOU issuer's r-address. | + +### Response + +Resolves to a `ListOffersResult`: + +| Field | Type | Description | +| --- | --- | --- | +| `data` | `readonly OfferSummary[]` | The shaped open offers, tagged buy/sell relative to the IOU. See [`token.listOffers`](../token/listOffers.md#offersummary) for `OfferSummary`. | + +### Underlying XRPL request + +Read-only — no signer is required and nothing is submitted. Queries both sides of the order book with [`book_offers`](https://xrpl.org/docs/references/http-websocket-apis/public-api-methods/path-and-order-book-methods/book_offers). + +## Example + +```ts +const { data } = await client.iou.listOffers({ + ticker: 'USD', + issuer: 'rIssuer...', +}) +``` diff --git a/docs/simpleXRPL/references/verticals/iou/lock.md b/docs/simpleXRPL/references/verticals/iou/lock.md new file mode 100644 index 00000000..27291952 --- /dev/null +++ b/docs/simpleXRPL/references/verticals/iou/lock.md @@ -0,0 +1,64 @@ +--- +seo: + description: IOU.lock freezes a holder's trust line via individual and deep freeze TrustSet transactions. +labels: + - SDKs +--- + +# iou.lock() + +[Source](https://github.com/ripple/simpleXRPL/blob/50619258cf753008e8a185eaeb3ceca489e5998a/src/verticals/iou.ts#L187) + +Freeze a holder's ability to send and receive this IOU: an individual freeze followed by a deep freeze. + +## Signature + +```ts +iou.lock( + params: IOULockParams, + options?: IOUWriteOptions, +): Promise> +``` + +### Parameters + +| Parameter | Type | Required | Description | +| --- | --- | --- | --- | +| `ticker` | `string` | Yes | The currency code (3-character ISO-4217-style or 40-character hex; other codes are auto-encoded to hex). | +| `holder` | `string` | Yes | The holder's r-address whose trust line is locked. | + +### Options + +{% raw-partial file="/docs/_snippets/simplexrpl-write-options.md" /%} + +### Response + +Resolves to a `SubmissionResult` (from the final step). + +{% raw-partial file="/docs/_snippets/simplexrpl-response-fields.md" /%} + +#### Response values + +For `IOU.lock`, the `intent` (`IOULockIntent`) echoes: + +| Field | Type | Description | +| --- | --- | --- | +| `holder` | `string` | The holder's r-address whose trust line was locked. | + +### Underlying XRPL transactors + +Runs as an ordered, multi-step sequence (no rollback on partial failure): + +1. [`TrustSet`](https://xrpl.org/docs/references/protocol/transactions/types/trustset) — sets the individual freeze. +2. [`TrustSet`](https://xrpl.org/docs/references/protocol/transactions/types/trustset) — sets the deep freeze. + +Throws a `MultiStepFailureError` if either step fails. + +## Example + +```ts +await client.iou.lock({ + ticker: 'USD', + holder: 'rHolder...', +}) +``` diff --git a/docs/simpleXRPL/references/verticals/iou/retrieve.md b/docs/simpleXRPL/references/verticals/iou/retrieve.md new file mode 100644 index 00000000..2c3677a4 --- /dev/null +++ b/docs/simpleXRPL/references/verticals/iou/retrieve.md @@ -0,0 +1,65 @@ +--- +seo: + description: IOU.retrieve reads a single IOU trust line between an account and an issuer. Read-only. +labels: + - SDKs +--- + +# iou.retrieve() + +[Source](https://github.com/ripple/simpleXRPL/blob/50619258cf753008e8a185eaeb3ceca489e5998a/src/verticals/iou.ts#L109) + +Read a single IOU trust line (point-in-time). + +## Signature + +```ts +iou.retrieve( + params: IOURetrieveParams +): Promise +``` + +### Parameters + +| Parameter | Type | Required | Description | +| --- | --- | --- | --- | +| `ticker` | `string` | Yes | The currency code (3-character ISO-4217-style or 40-character hex; other codes are auto-encoded to hex). | +| `issuer` | `string` | Yes | The IOU issuer's r-address. | +| `account` | `string` | No | The holder account to read from. Defaults to the primary signer's account. | + +### Response + +Resolves to an `IOURetrieveResult`: + +| Field | Type | Description | +| --- | --- | --- | +| `iouID` | `string` | Currency code and issuer, e.g. `USD.rIssuer...` — pass to the write verbs. | +| `data` | `IOUTrustLine \| undefined` | The point-in-time trust-line snapshot, or `undefined` if no line exists. | + +#### IOUTrustLine + +| Field | Type | Description | +| --- | --- | --- | +| `currency` | `string` | The currency ticker (hex codes decoded to ASCII where printable). | +| `peer` | `string` | The counterparty r-address (the issuer, when querying as `holder`). | +| `balance` | `string` | The trust-line balance, from the queried account's perspective. | +| `limit` | `string` | The queried account's trust limit. | +| `limitPeer` | `string` | The counterparty's trust limit. | +| `noRipple` | `boolean` | Whether rippling is disabled on this line. | +| `frozen` | `boolean` | Whether the queried account has frozen this line. | +| `authorized` | `boolean` | Whether the line is authorized (issuer authorized the holder). | + +### Underlying XRPL request + +Read-only — no signer is required and nothing is submitted. Queries the ledger with [`account_lines`](https://xrpl.org/docs/references/http-websocket-apis/public-api-methods/account-methods/account_lines). + +## Example + +```ts +const { data } = await client.iou.retrieve({ + ticker: 'USD', + issuer: 'rIssuer...', +}) + +console.log(data?.balance) +``` diff --git a/docs/simpleXRPL/references/verticals/iou/sellOffer.md b/docs/simpleXRPL/references/verticals/iou/sellOffer.md new file mode 100644 index 00000000..ee979e11 --- /dev/null +++ b/docs/simpleXRPL/references/verticals/iou/sellOffer.md @@ -0,0 +1,70 @@ +--- +seo: + description: IOU.sellOffer places a DEX order to sell this IOU via an OfferCreate transaction. +labels: + - SDKs +--- + +# iou.sellOffer() + +[Source](https://github.com/ripple/simpleXRPL/blob/50619258cf753008e8a185eaeb3ceca489e5998a/src/verticals/iou.ts#L319) + +Place an order on the DEX to sell this IOU. + +## Signature + +```ts +iou.sellOffer( + params: IOUOfferParams, + options?: IOUWriteOptions, +): Promise> +``` + +### Parameters + +| Parameter | Type | Required | Description | +| --- | --- | --- | --- | +| `ticker` | `string` | Yes | The currency code (3-character ISO-4217-style or 40-character hex; other codes are auto-encoded to hex). | +| `amount` | `number` | Yes | The number of units of this IOU to sell. | +| `orderType` | `IOUOrderType` | Yes | The order type: `'limit'`, `'market'`, `'fok'`, or `'passive'`. | +| `price` | `IOUOfferPrice` | Yes | What's wanted in return — XRP, an MPT, or another IOU (see below). | +| `domainID` | `string` | No | Restrict the offer to a permissioned domain. Omit for the open DEX. | +| `hybrid` | `boolean` | No | Whether a domain-scoped offer also works the open DEX. Only meaningful with `domainID`; defaults to `true` when `domainID` is set. | +| `offerSequence` | `number` | No | A prior offer sequence to replace. | + +`price` (`IOUOfferPrice`) is one of: + +| Shape | Description | +| --- | --- | +| `{ currency: 'XRP'; amount: number }` | Priced in XRP. | +| `{ mptIssuanceId: string; amount: number }` | Priced in an MPT. | +| `{ ticker: string; issuer: string; amount: number }` | Priced in another IOU. | + +### Options + +{% raw-partial file="/docs/_snippets/simplexrpl-write-options.md" /%} + +### Response + +Resolves to a `SubmissionResult`. + +{% raw-partial file="/docs/_snippets/simplexrpl-response-fields.md" /%} + +#### Response values + +`IOU.sellOffer` attaches no `intent` output; `intent` is `undefined`. + +### Underlying XRPL transactor + +Builds and submits a single [`OfferCreate`](https://xrpl.org/docs/references/protocol/transactions/types/offercreate) transaction. Throws an `IntentValidationError` if `price` is MPT-denominated. + +## Example + +```ts +await client.iou.sellOffer({ + ticker: 'USD', + amount: 100, + orderType: 'limit', + price: { currency: 'XRP', amount: 50 }, +}) +``` diff --git a/docs/simpleXRPL/references/verticals/iou/transfer.md b/docs/simpleXRPL/references/verticals/iou/transfer.md new file mode 100644 index 00000000..ebb55783 --- /dev/null +++ b/docs/simpleXRPL/references/verticals/iou/transfer.md @@ -0,0 +1,62 @@ +--- +seo: + description: IOU.transfer sends issued-currency value to a destination account via a Payment transaction. +labels: + - SDKs +--- + +# iou.transfer() + +[Source](https://github.com/ripple/simpleXRPL/blob/50619258cf753008e8a185eaeb3ceca489e5998a/src/verticals/iou.ts#L267) + +Send a specified amount of this IOU to a destination account. + +## Signature + +```ts +iou.transfer( + params: IOUTransferParams, + options?: IOUWriteOptions, +): Promise> +``` + +### Parameters + +| Parameter | Type | Required | Description | +| --- | --- | --- | --- | +| `ticker` | `string` | Yes | The currency code (3-character ISO-4217-style or 40-character hex; other codes are auto-encoded to hex). | +| `destination` | `string` | Yes | The destination r-address. | +| `amount` | `number` | Yes | The amount to send. | + +### Options + +{% raw-partial file="/docs/_snippets/simplexrpl-write-options.md" /%} + +### Response + +Resolves to a `SubmissionResult`. + +{% raw-partial file="/docs/_snippets/simplexrpl-response-fields.md" /%} + +#### Response values + +For `IOU.transfer`, the `intent` (`IOUTransferIntent`) echoes: + +| Field | Type | Description | +| --- | --- | --- | +| `destination` | `string` | Destination r-address. | +| `amount` | `number` | Amount sent. | + +### Underlying XRPL transactor + +Builds and submits a single [`Payment`](https://xrpl.org/docs/references/protocol/transactions/types/payment) transaction. + +## Example + +```ts +await client.iou.transfer({ + ticker: 'USD', + destination: 'rHolder...', + amount: 100, +}) +``` diff --git a/docs/simpleXRPL/references/verticals/iou/unlock.md b/docs/simpleXRPL/references/verticals/iou/unlock.md new file mode 100644 index 00000000..f80faab7 --- /dev/null +++ b/docs/simpleXRPL/references/verticals/iou/unlock.md @@ -0,0 +1,64 @@ +--- +seo: + description: IOU.unlock restores a frozen holder's trust line by clearing deep and individual freeze via TrustSet transactions. +labels: + - SDKs +--- + +# iou.unlock() + +[Source](https://github.com/ripple/simpleXRPL/blob/50619258cf753008e8a185eaeb3ceca489e5998a/src/verticals/iou.ts#L209) + +Restore a holder's ability to send and receive this IOU: clears the deep freeze, then the individual freeze. + +## Signature + +```ts +iou.unlock( + params: IOULockParams, + options?: IOUWriteOptions, +): Promise> +``` + +### Parameters + +| Parameter | Type | Required | Description | +| --- | --- | --- | --- | +| `ticker` | `string` | Yes | The currency code (3-character ISO-4217-style or 40-character hex; other codes are auto-encoded to hex). | +| `holder` | `string` | Yes | The holder's r-address whose trust line is unlocked. | + +### Options + +{% raw-partial file="/docs/_snippets/simplexrpl-write-options.md" /%} + +### Response + +Resolves to a `SubmissionResult` (from the final step). + +{% raw-partial file="/docs/_snippets/simplexrpl-response-fields.md" /%} + +#### Response values + +For `IOU.unlock`, the `intent` (`IOULockIntent`) echoes: + +| Field | Type | Description | +| --- | --- | --- | +| `holder` | `string` | The holder's r-address whose trust line was unlocked. | + +### Underlying XRPL transactors + +Runs as an ordered, multi-step sequence (no rollback on partial failure): + +1. [`TrustSet`](https://xrpl.org/docs/references/protocol/transactions/types/trustset) — clears the deep freeze. +2. [`TrustSet`](https://xrpl.org/docs/references/protocol/transactions/types/trustset) — clears the individual freeze. + +Throws a `MultiStepFailureError` if either step fails. + +## Example + +```ts +await client.iou.unlock({ + ticker: 'USD', + holder: 'rHolder...', +}) +``` diff --git a/docs/simpleXRPL/references/verticals/token/authorize.md b/docs/simpleXRPL/references/verticals/token/authorize.md new file mode 100644 index 00000000..87acb886 --- /dev/null +++ b/docs/simpleXRPL/references/verticals/token/authorize.md @@ -0,0 +1,57 @@ +--- +seo: + description: Token.authorize opts the calling account in to holding an MPT issuance via an MPTokenAuthorize transaction. +labels: + - SDKs +--- + +# token.authorize() + +[Source](https://github.com/ripple/simpleXRPL/blob/50619258cf753008e8a185eaeb3ceca489e5998a/src/verticals/token.ts#L155) + +Opt the calling account in to hold an MPT issuance. + +## Signature + +```ts +token.authorize( + params: MptAuthorizeParams, + options?: TokenWriteOptions, +): Promise`. + +{% raw-partial file="/docs/_snippets/simplexrpl-response-fields.md" /%} + +#### Response values + +For `Token.authorize`, the `intent` echoes: + +| Field | Type | Description | +| --- | --- | --- | +| `mptIssuanceId` | `string` | The MPT issuance id that was authorized. | + +### Underlying XRPL transactor + +Builds and submits a single [`MPTokenAuthorize`](https://xrpl.org/docs/references/protocol/transactions/types/mptokenauthorize) transaction. + +## Example + +```ts +await client.token.authorize({ + mptIssuanceId: '005C...', +}) +``` diff --git a/docs/simpleXRPL/references/verticals/token/cancelOffer.md b/docs/simpleXRPL/references/verticals/token/cancelOffer.md new file mode 100644 index 00000000..cb587ca9 --- /dev/null +++ b/docs/simpleXRPL/references/verticals/token/cancelOffer.md @@ -0,0 +1,57 @@ +--- +seo: + description: Token.cancelOffer cancels a standing DEX offer via an OfferCancel transaction. +labels: + - SDKs +--- + +# token.cancelOffer() + +[Source](https://github.com/ripple/simpleXRPL/blob/50619258cf753008e8a185eaeb3ceca489e5998a/src/verticals/token.ts#L336) + +Cancel a standing offer. + +## Signature + +```ts +token.cancelOffer( + params: CancelOfferParams, + options?: TokenWriteOptions, +): Promise`. + +{% raw-partial file="/docs/_snippets/simplexrpl-response-fields.md" /%} + +#### Response values + +For `Token.cancelOffer`, the `intent` echoes: + +| Field | Type | Description | +| --- | --- | --- | +| `offerSequence` | `number` | The sequence number of the offer that was canceled. | + +### Underlying XRPL transactor + +Builds and submits a single [`OfferCancel`](https://xrpl.org/docs/references/protocol/transactions/types/offercancel) transaction. + +## Example + +```ts +await client.token.cancelOffer({ + offerSequence: 42, +}) +``` diff --git a/docs/simpleXRPL/references/verticals/token/createOffer.md b/docs/simpleXRPL/references/verticals/token/createOffer.md new file mode 100644 index 00000000..320c9aa6 --- /dev/null +++ b/docs/simpleXRPL/references/verticals/token/createOffer.md @@ -0,0 +1,67 @@ +--- +seo: + description: Token.createOffer places an offer on the XRP Ledger decentralized exchange via an OfferCreate transaction. +labels: + - SDKs +--- + +# token.createOffer() + +[Source](https://github.com/ripple/simpleXRPL/blob/50619258cf753008e8a185eaeb3ceca489e5998a/src/verticals/token.ts#L299) + +Place an offer on the decentralized exchange (DEX). + +## Signature + +```ts +token.createOffer( + params: CreateOfferParams, + options?: TokenWriteOptions, +): Promise> +``` + +### Parameters + +| Parameter | Type | Required | Description | +| --- | --- | --- | --- | +| `takerGets` | `Amount` | Yes | What the account gives (XRP or IOU — MPT is not DEX-tradeable). | +| `takerPays` | `Amount` | Yes | What the account wants (XRP or IOU). | +| `expiration` | `number` | No | Offer expiration, in seconds since the Ripple epoch. | +| `offerSequence` | `number` | No | A prior offer sequence to replace. | +| `flags` | `OfferFlags` | No | Offer flags (see below). | + +The `flags` object accepts: + +| Flag | Type | Required | Description | +| --- | --- | --- | --- | +| `passive` | `boolean` | No | Do not consume offers that exactly match. | +| `immediateOrCancel` | `boolean` | No | Consume matching offers immediately; never place the remainder. | +| `fillOrKill` | `boolean` | No | Consume the full amount or cancel entirely. | +| `sell` | `boolean` | No | Interpret the offer as selling `takerGets`. | + +### Options + +{% raw-partial file="/docs/_snippets/simplexrpl-write-options.md" /%} + +### Response + +Resolves to a `SubmissionResult`. + +{% raw-partial file="/docs/_snippets/simplexrpl-response-fields.md" /%} + +#### Response values + +`Token.createOffer` attaches no `intent` output; `intent` is `undefined`. + +### Underlying XRPL transactor + +Builds and submits a single [`OfferCreate`](https://xrpl.org/docs/references/protocol/transactions/types/offercreate) transaction. Throws an `IntentValidationError` if either amount is an MPT. + +## Example + +```ts +await client.token.createOffer({ + takerGets: { asset: XRP_ASSET, value: '10' }, + takerPays: { asset: iou('USD', 'rIssuer...'), value: '5' }, +}) +``` diff --git a/docs/simpleXRPL/references/verticals/token/destroy.md b/docs/simpleXRPL/references/verticals/token/destroy.md new file mode 100644 index 00000000..d2cbaac3 --- /dev/null +++ b/docs/simpleXRPL/references/verticals/token/destroy.md @@ -0,0 +1,57 @@ +--- +seo: + description: Token.destroy destroys an MPT issuance via an MPTokenIssuanceDestroy transaction. +labels: + - SDKs +--- + +# token.destroy() + +[Source](https://github.com/ripple/simpleXRPL/blob/50619258cf753008e8a185eaeb3ceca489e5998a/src/verticals/token.ts#L239) + +Destroy an MPT issuance. Only succeeds when no tokens are outstanding. + +## Signature + +```ts +token.destroy( + params: MptDestroyParams, + options?: TokenWriteOptions, +): Promise`. + +{% raw-partial file="/docs/_snippets/simplexrpl-response-fields.md" /%} + +#### Response values + +For `Token.destroy`, the `intent` echoes: + +| Field | Type | Description | +| --- | --- | --- | +| `mptIssuanceId` | `string` | The MPT issuance id that was destroyed. | + +### Underlying XRPL transactor + +Builds and submits a single [`MPTokenIssuanceDestroy`](https://xrpl.org/docs/references/protocol/transactions/types/mptokenissuancedestroy) transaction. + +## Example + +```ts +await client.token.destroy({ + mptIssuanceId: '005C...', +}) +``` diff --git a/docs/simpleXRPL/references/verticals/token/grantHolder.md b/docs/simpleXRPL/references/verticals/token/grantHolder.md new file mode 100644 index 00000000..95fc1f00 --- /dev/null +++ b/docs/simpleXRPL/references/verticals/token/grantHolder.md @@ -0,0 +1,59 @@ +--- +seo: + description: Token.grantHolder lets an issuer authorize a specific holder to hold an MPT via an MPTokenAuthorize transaction. +labels: + - SDKs +--- + +# token.grantHolder() + +[Source](https://github.com/ripple/simpleXRPL/blob/50619258cf753008e8a185eaeb3ceca489e5998a/src/verticals/token.ts#L183) + +As the issuer, grant a specific holder permission to hold this MPT (allow-listing). Use this when the issuance requires authorization. + +## Signature + +```ts +token.grantHolder( + params: MptHolderParams, + options?: TokenWriteOptions, +): Promise`. + +{% raw-partial file="/docs/_snippets/simplexrpl-response-fields.md" /%} + +#### Response values + +For `Token.grantHolder`, the `intent` echoes: + +| Field | Type | Description | +| --- | --- | --- | +| `mptIssuanceId` | `string` | The MPT issuance id the holder was granted on. | + +### Underlying XRPL transactor + +Builds and submits a single [`MPTokenAuthorize`](https://xrpl.org/docs/references/protocol/transactions/types/mptokenauthorize) transaction naming the holder. + +## Example + +```ts +await client.token.grantHolder({ + mptIssuanceId: '005C...', + holder: 'rHolder...', +}) +``` diff --git a/docs/simpleXRPL/references/verticals/token/index.md b/docs/simpleXRPL/references/verticals/token/index.md new file mode 100644 index 00000000..b938917d --- /dev/null +++ b/docs/simpleXRPL/references/verticals/token/index.md @@ -0,0 +1,27 @@ +--- +seo: + description: The Token vertical in simpleXRPL issues and manages Multi-Purpose Tokens (MPTs) and places DEX offers. +labels: + - SDKs +--- + +# Token + +The `Token` vertical issues and manages [Multi-Purpose Tokens (MPTs)](https://xrpl.org/docs/concepts/tokens/fungible-tokens/multi-purpose-tokens) and places offers on the decentralized exchange. + +| Method | Description | +| --- | --- | +| [issue](issue.md) | Create a new MPT issuance. | +| [transfer](transfer.md) | Send MPT units to another account. | +| [authorize](authorize.md) | Opt the calling account in to holding a token. | +| [unauthorize](unauthorize.md) | Opt the calling account out of holding a token. | +| [grantHolder](grantHolder.md) | Issuer authorizes a specific holder (allow-listing). | +| [revokeHolder](revokeHolder.md) | Issuer revokes a specific holder's permission. | +| [lock](lock.md) | Lock a token issuance, or a specific holder's balance. | +| [unlock](unlock.md) | Unlock a token issuance, or a specific holder's balance. | +| [destroy](destroy.md) | Destroy an MPT issuance. | +| [createOffer](createOffer.md) | Place an offer on the DEX. | +| [cancelOffer](cancelOffer.md) | Cancel a standing offer. | +| [retrieve](retrieve.md) | Read a single MPT issuance by id. | +| [list](list.md) | List the MPTs an account holds or issued. | +| [listOffers](listOffers.md) | List the DEX offers placed by an account. | diff --git a/docs/simpleXRPL/references/verticals/token/issue.md b/docs/simpleXRPL/references/verticals/token/issue.md new file mode 100644 index 00000000..4ccaac85 --- /dev/null +++ b/docs/simpleXRPL/references/verticals/token/issue.md @@ -0,0 +1,85 @@ +--- +seo: + description: Token.issue creates a new Multi-Purpose Token (MPT) issuance via an MPTokenIssuanceCreate transaction. +labels: + - SDKs +--- + +# token.issue() + +[Source](https://github.com/ripple/simpleXRPL/blob/50619258cf753008e8a185eaeb3ceca489e5998a/src/verticals/token.ts#L134) + +Create a new MPT issuance. + +## Signature + +```ts +token.issue( + params: MptIssueParams, + options?: TokenWriteOptions, +): Promise> +``` + +### Parameters + +| Parameter | Type | Required | Description | +| --- | --- | --- | --- | +| `metadata` | `MPTokenMetadata \| string` | Yes | Token metadata: a structured object (encoded per the XLS-89 standard) or a raw string (UTF-8 hex-encoded as-is). Validated against XLS-89; non-compliant metadata is rejected before submission. | +| `assetScale` | `number` | No | Decimal places between the display value and base units. Defaults to `2`. | +| `maximumAmount` | `string` | No | Maximum issuable amount, in base units. | +| `transferFee` | `number` | No | Transfer fee on secondary sales, as a percentage (`0.5` = 0.5%, range 0–50). | +| `flags` | `MptIssueFlags` | No | Capability flags (see below). | + +The `flags` object accepts: + +| Flag | Type | Required | Description | +| --- | --- | --- | --- | +| `canLock` | `boolean` | No | The issuer can lock the token (globally or per-holder). | +| `requireAuth` | `boolean` | No | Holders must be authorized before they can hold the token. | +| `canEscrow` | `boolean` | No | The token can be used in escrows. | +| `canTrade` | `boolean` | No | The token can be traded on the DEX. | +| `canTransfer` | `boolean` | No | The token can be transferred between holders. | +| `canClawback` | `boolean` | No | The issuer can claw back the token. | + +{% admonition type="info" name="Note" %} +`issue()` applies opinionated, overridable defaults so a bare call yields a usable token: `canLock`, `canEscrow`, `canTrade`, `canTransfer`, and `canClawback` are all enabled, and `requireAuth` is off. Pass any flag explicitly to override it. MPT capability flags are **permanent** once the issuance exists. +{% /admonition %} + +### Options + +{% raw-partial file="/docs/_snippets/simplexrpl-write-options.md" /%} + +### Response + +Resolves to a `SubmissionResult`. + +{% raw-partial file="/docs/_snippets/simplexrpl-response-fields.md" /%} + +#### Response values + +For `Token.issue`, the `intent` (`MptIssueIntent`) carries: + +| Field | Type | Description | +| --- | --- | --- | +| `mptIssuanceId` | `string` | The id of the newly created MPT issuance. | + +### Underlying XRPL transactor + +Builds and submits a single [`MPTokenIssuanceCreate`](https://xrpl.org/docs/references/protocol/transactions/types/mptokenissuancecreate) transaction. + +## Example + +```ts +const { intent } = await client.token.issue({ + metadata: { + ticker: 'TBILL', + name: 'Acme T-Bill Token', + icon: 'https://acme.example/icon.png', + asset_class: 'rwa', + asset_subclass: 'treasury', + issuer_name: 'Acme Inc', + }, +}) + +console.log(intent.mptIssuanceId) +``` diff --git a/docs/simpleXRPL/references/verticals/token/list.md b/docs/simpleXRPL/references/verticals/token/list.md new file mode 100644 index 00000000..eaab5a73 --- /dev/null +++ b/docs/simpleXRPL/references/verticals/token/list.md @@ -0,0 +1,58 @@ +--- +seo: + description: Token.list lists the MPTs an account holds or issued. Read-only. +labels: + - SDKs +--- + +# token.list() + +[Source](https://github.com/ripple/simpleXRPL/blob/50619258cf753008e8a185eaeb3ceca489e5998a/src/verticals/token.ts#L79) + +List the MPTs an account holds (default) or issued. + +## Signature + +```ts +token.list( + params?: TokenListParams +): Promise +``` + +### Parameters + +| Parameter | Type | Required | Description | +| --- | --- | --- | --- | +| `role` | `'holder' \| 'issuer'` | No | List tokens the account holds (default) or issued. | +| `account` | `string` | No | The account to query. Defaults to the primary signer's account. | + +### Response + +Resolves to a `TokenListResult`, where `tokens[i]` corresponds to `data[i]`: + +| Field | Type | Description | +| --- | --- | --- | +| `tokens` | `readonly string[]` | The MPT issuance id of each token. | +| `data` | `readonly TokenListEntry[]` | The shaped entries. | + +#### TokenListEntry + +| Field | Type | Description | +| --- | --- | --- | +| `tokenID` | `string` | The MPT issuance id. | +| `balance` | `string` _(optional)_ | The account's balance (present for `role: 'holder'`). | +| `issuance` | `TokenData` _(optional)_ | The full issuance snapshot (present for `role: 'issuer'`). See [`token.retrieve`](retrieve.md#tokendata) for `TokenData`. | + +### Underlying XRPL request + +Read-only — no signer is required and nothing is submitted. Queries the ledger with [`account_objects`](https://xrpl.org/docs/references/http-websocket-apis/public-api-methods/account-methods/account_objects). + +## Example + +```ts +const { data } = await client.token.list({ role: 'holder' }) + +for (const entry of data) { + console.log(entry.tokenID, entry.balance) +} +``` diff --git a/docs/simpleXRPL/references/verticals/token/listOffers.md b/docs/simpleXRPL/references/verticals/token/listOffers.md new file mode 100644 index 00000000..639ba31e --- /dev/null +++ b/docs/simpleXRPL/references/verticals/token/listOffers.md @@ -0,0 +1,60 @@ +--- +seo: + description: Token.listOffers lists the open DEX offers placed by an account. Read-only. +labels: + - SDKs +--- + +# token.listOffers() + +[Source](https://github.com/ripple/simpleXRPL/blob/50619258cf753008e8a185eaeb3ceca489e5998a/src/verticals/token.ts#L89) + +List the open DEX offers placed by an account. + +## Signature + +```ts +token.listOffers( + params?: TokenListOffersParams, +): Promise +``` + +### Parameters + +| Parameter | Type | Required | Description | +| --- | --- | --- | --- | +| `account` | `string` | No | The account whose offers to list. Defaults to the primary signer's account. | + +### Response + +Resolves to a `ListOffersResult`: + +| Field | Type | Description | +| --- | --- | --- | +| `data` | `readonly OfferSummary[]` | The shaped open offers. | + +#### OfferSummary + +Each offer mirrors the `createOffer` / `buyOffer` / `sellOffer` input format, so it's composable back into those write verbs. + +| Field | Type | Description | +| --- | --- | --- | +| `offerSequence` | `number` | The offer's sequence number (pass to `cancelOffer`). | +| `amount` | `number` | The quantity of the base asset being traded. | +| `price` | `IOUOfferPrice` | What is paid/received for it, in offer-price form. | +| `orderType` | `'limit' \| 'passive'` | Resting offers are `limit`, or `passive` when the passive flag is set. | +| `type` | `'buy' \| 'sell'` | Whether the offer buys or sells the base asset. | + +### Underlying XRPL request + +Read-only — no signer is required and nothing is submitted. Queries the ledger with [`account_offers`](https://xrpl.org/docs/references/http-websocket-apis/public-api-methods/account-methods/account_offers). + +## Example + +```ts +const { data } = await client.token.listOffers() + +for (const offer of data) { + console.log(offer.offerSequence, offer.type, offer.amount) +} +``` diff --git a/docs/simpleXRPL/references/verticals/token/lock.md b/docs/simpleXRPL/references/verticals/token/lock.md new file mode 100644 index 00000000..8cfe5653 --- /dev/null +++ b/docs/simpleXRPL/references/verticals/token/lock.md @@ -0,0 +1,59 @@ +--- +seo: + description: Token.lock locks an MPT issuance or a specific holder's balance via an MPTokenIssuanceSet transaction. +labels: + - SDKs +--- + +# token.lock() + +[Source](https://github.com/ripple/simpleXRPL/blob/50619258cf753008e8a185eaeb3ceca489e5998a/src/verticals/token.ts#L211) + +Lock an MPT issuance, or a specific holder's balance when `holder` is given. + +## Signature + +```ts +token.lock( + params: MptLockParams, + options?: TokenWriteOptions, +): Promise`. + +{% raw-partial file="/docs/_snippets/simplexrpl-response-fields.md" /%} + +#### Response values + +For `Token.lock`, the `intent` carries: + +| Field | Type | Description | +| --- | --- | --- | +| `mptIssuanceId` | `string` | The MPT issuance id that was locked. | +| `locked` | `boolean` | The resulting lock state (`true`). | + +### Underlying XRPL transactor + +Builds and submits a single [`MPTokenIssuanceSet`](https://xrpl.org/docs/references/protocol/transactions/types/mptokenissuanceset) transaction with the lock flag set. + +## Example + +```ts +await client.token.lock({ + mptIssuanceId: '005C...', +}) +``` diff --git a/docs/simpleXRPL/references/verticals/token/retrieve.md b/docs/simpleXRPL/references/verticals/token/retrieve.md new file mode 100644 index 00000000..6af0d917 --- /dev/null +++ b/docs/simpleXRPL/references/verticals/token/retrieve.md @@ -0,0 +1,62 @@ +--- +seo: + description: Token.retrieve reads a single MPT issuance by id, with flags and XLS-89 metadata decoded. Read-only. +labels: + - SDKs +--- + +# token.retrieve() + +[Source](https://github.com/ripple/simpleXRPL/blob/50619258cf753008e8a185eaeb3ceca489e5998a/src/verticals/token.ts#L67) + +Retrieve a single MPT issuance by id (point-in-time), with flags decoded to booleans and XLS-89 metadata decoded. + +## Signature + +```ts +token.retrieve( + params: TokenRetrieveParams, +): Promise +``` + +### Parameters + +| Parameter | Type | Required | Description | +| --- | --- | --- | --- | +| `mptIssuanceId` | `string` | Yes | The MPT issuance id to fetch. | + +### Response + +Resolves to a `TokenRetrieveResult`: + +| Field | Type | Description | +| --- | --- | --- | +| `tokenID` | `string` | The queried MPT issuance id. | +| `data` | `TokenData \| undefined` | The issuance snapshot, or `undefined` if no such issuance exists. | + +#### TokenData + +| Field | Type | Description | +| --- | --- | --- | +| `tokenID` | `string` | The MPT issuance id. | +| `issuer` | `string` | The issuer r-address. | +| `assetScale` | `number` | Decimal places between display value and base units. | +| `maximumAmount` | `string` _(optional)_ | Maximum issuable amount (base units), if capped. | +| `outstandingAmount` | `string` | Amount currently in circulation (base units). | +| `transferFee` | `number` | Secondary-transfer fee, as a percentage. | +| `flags` | `MptFlags` | Capability flags decoded to booleans: `canLock`, `requireAuth`, `canEscrow`, `canTrade`, `canTransfer`, `canClawback`. | +| `metadata` | `MPTokenMetadata` _(optional)_ | Decoded XLS-89 metadata, if present and well-formed. | + +### Underlying XRPL request + +Read-only — no signer is required and nothing is submitted. Queries the ledger with [`ledger_entry`](https://xrpl.org/docs/references/http-websocket-apis/public-api-methods/ledger-methods/ledger_entry). + +## Example + +```ts +const { data } = await client.token.retrieve({ + mptIssuanceId: '005C...', +}) + +console.log(data?.outstandingAmount) +``` diff --git a/docs/simpleXRPL/references/verticals/token/revokeHolder.md b/docs/simpleXRPL/references/verticals/token/revokeHolder.md new file mode 100644 index 00000000..f8648dd7 --- /dev/null +++ b/docs/simpleXRPL/references/verticals/token/revokeHolder.md @@ -0,0 +1,59 @@ +--- +seo: + description: Token.revokeHolder lets an issuer revoke a specific holder's permission to hold an MPT via an MPTokenAuthorize transaction. +labels: + - SDKs +--- + +# token.revokeHolder() + +[Source](https://github.com/ripple/simpleXRPL/blob/50619258cf753008e8a185eaeb3ceca489e5998a/src/verticals/token.ts#L197) + +As the issuer, revoke a specific holder's permission to hold this MPT. + +## Signature + +```ts +token.revokeHolder( + params: MptHolderParams, + options?: TokenWriteOptions, +): Promise`. + +{% raw-partial file="/docs/_snippets/simplexrpl-response-fields.md" /%} + +#### Response values + +For `Token.revokeHolder`, the `intent` echoes: + +| Field | Type | Description | +| --- | --- | --- | +| `mptIssuanceId` | `string` | The MPT issuance id the holder was revoked on. | + +### Underlying XRPL transactor + +Builds and submits a single [`MPTokenAuthorize`](https://xrpl.org/docs/references/protocol/transactions/types/mptokenauthorize) transaction naming the holder, with the unauthorize flag set. + +## Example + +```ts +await client.token.revokeHolder({ + mptIssuanceId: '005C...', + holder: 'rHolder...', +}) +``` diff --git a/docs/simpleXRPL/references/verticals/token/transfer.md b/docs/simpleXRPL/references/verticals/token/transfer.md new file mode 100644 index 00000000..d996fc7d --- /dev/null +++ b/docs/simpleXRPL/references/verticals/token/transfer.md @@ -0,0 +1,60 @@ +--- +seo: + description: Token.transfer sends MPT units to another account via a Payment transaction. +labels: + - SDKs +--- + +# token.transfer() + +[Source](https://github.com/ripple/simpleXRPL/blob/50619258cf753008e8a185eaeb3ceca489e5998a/src/verticals/token.ts#L266) + +Send an MPT amount to another account. + +## Signature + +```ts +token.transfer( + params: TokenTransferParams, + options?: TokenWriteOptions, +): Promise`. + +{% raw-partial file="/docs/_snippets/simplexrpl-response-fields.md" /%} + +#### Response values + +For `Token.transfer`, the `intent` echoes: + +| Field | Type | Description | +| --- | --- | --- | +| `to` | `string` | Destination r-address. | +| `amount` | `string` | The amount sent, as a decimal string. | + +### Underlying XRPL transactor + +Builds and submits a single [`Payment`](https://xrpl.org/docs/references/protocol/transactions/types/payment) transaction. Throws an `IntentValidationError` if `amount`'s asset is not an MPT — use [`XRP.transfer`](../xrp/transfer.md) for XRP. + +## Example + +```ts +await client.token.transfer({ + to: 'rHolder...', + amount: { asset: mpt('005C...'), value: '100' }, +}) +``` diff --git a/docs/simpleXRPL/references/verticals/token/unauthorize.md b/docs/simpleXRPL/references/verticals/token/unauthorize.md new file mode 100644 index 00000000..f541f092 --- /dev/null +++ b/docs/simpleXRPL/references/verticals/token/unauthorize.md @@ -0,0 +1,57 @@ +--- +seo: + description: Token.unauthorize opts the calling account out of holding an MPT issuance via an MPTokenAuthorize transaction. +labels: + - SDKs +--- + +# token.unauthorize() + +[Source](https://github.com/ripple/simpleXRPL/blob/50619258cf753008e8a185eaeb3ceca489e5998a/src/verticals/token.ts#L169) + +Opt the calling account out of holding an MPT issuance. The account's balance must be `0`. + +## Signature + +```ts +token.unauthorize( + params: MptAuthorizeParams, + options?: TokenWriteOptions, +): Promise`. + +{% raw-partial file="/docs/_snippets/simplexrpl-response-fields.md" /%} + +#### Response values + +For `Token.unauthorize`, the `intent` echoes: + +| Field | Type | Description | +| --- | --- | --- | +| `mptIssuanceId` | `string` | The MPT issuance id that was deauthorized. | + +### Underlying XRPL transactor + +Builds and submits a single [`MPTokenAuthorize`](https://xrpl.org/docs/references/protocol/transactions/types/mptokenauthorize) transaction, with the unauthorize flag set. + +## Example + +```ts +await client.token.unauthorize({ + mptIssuanceId: '005C...', +}) +``` diff --git a/docs/simpleXRPL/references/verticals/token/unlock.md b/docs/simpleXRPL/references/verticals/token/unlock.md new file mode 100644 index 00000000..2efafa0b --- /dev/null +++ b/docs/simpleXRPL/references/verticals/token/unlock.md @@ -0,0 +1,59 @@ +--- +seo: + description: Token.unlock unlocks an MPT issuance or a specific holder's balance via an MPTokenIssuanceSet transaction. +labels: + - SDKs +--- + +# token.unlock() + +[Source](https://github.com/ripple/simpleXRPL/blob/50619258cf753008e8a185eaeb3ceca489e5998a/src/verticals/token.ts#L225) + +Unlock a previously locked MPT issuance, or a specific holder's balance when `holder` is given. + +## Signature + +```ts +token.unlock( + params: MptLockParams, + options?: TokenWriteOptions, +): Promise`. + +{% raw-partial file="/docs/_snippets/simplexrpl-response-fields.md" /%} + +#### Response values + +For `Token.unlock`, the `intent` carries: + +| Field | Type | Description | +| --- | --- | --- | +| `mptIssuanceId` | `string` | The MPT issuance id that was unlocked. | +| `locked` | `boolean` | The resulting lock state (`false`). | + +### Underlying XRPL transactor + +Builds and submits a single [`MPTokenIssuanceSet`](https://xrpl.org/docs/references/protocol/transactions/types/mptokenissuanceset) transaction with the unlock flag set. + +## Example + +```ts +await client.token.unlock({ + mptIssuanceId: '005C...', +}) +``` diff --git a/docs/simpleXRPL/references/verticals/xrp/index.md b/docs/simpleXRPL/references/verticals/xrp/index.md new file mode 100644 index 00000000..28b3fa9a --- /dev/null +++ b/docs/simpleXRPL/references/verticals/xrp/index.md @@ -0,0 +1,14 @@ +--- +seo: + description: The XRP vertical in simpleXRPL handles native XRP value transfers. +labels: + - SDKs +--- + +# XRP + +The `XRP` vertical handles native XRP value transfers. + +| Method | Description | +| --- | --- | +| [transfer](transfer.md) | Send native XRP from one account to another. | diff --git a/docs/simpleXRPL/references/verticals/xrp/transfer.md b/docs/simpleXRPL/references/verticals/xrp/transfer.md new file mode 100644 index 00000000..d90490a8 --- /dev/null +++ b/docs/simpleXRPL/references/verticals/xrp/transfer.md @@ -0,0 +1,62 @@ +--- +seo: + description: XRP.transfer sends native XRP from one account to another via a Payment transaction. +labels: + - SDKs +--- + +# xrp.transfer() + +[Source](https://github.com/ripple/simpleXRPL/blob/50619258cf753008e8a185eaeb3ceca489e5998a/src/verticals/xrp.ts#L67) + +Send native XRP from one account to another. + +## Signature + +```ts +xrp.transfer( + params: XrpTransferParams, + options?: XrpTransferOptions, +): Promise> +``` + +### Parameters + +| Parameter | Type | Required | Description | +| --- | --- | --- | --- | +| `to` | `string` | Yes | Destination r-address. | +| `amount` | `string` | Yes | Amount to send, as a decimal string in XRP (e.g. `'10'`, `'0.25'`). | + +### Options + +{% raw-partial file="/docs/_snippets/simplexrpl-write-options.md" /%} + +### Response + +Resolves to a `SubmissionResult`. + +{% raw-partial file="/docs/_snippets/simplexrpl-response-fields.md" /%} + +#### Response values + +For `XRP.transfer`, the `intent` (`XrpTransferIntent`) carries: + +| Field | Type | Description | +| --- | --- | --- | +| `to` | `string` | Destination r-address. | +| `amount` | `string` | Amount sent, in XRP. | + +### Underlying XRPL transactor + +Builds and submits a single [`Payment`](https://xrpl.org/docs/references/protocol/transactions/types/payment) transaction. + +## Example + +```ts +const result = await client.xrp.transfer({ + to: 'rDestination...', + amount: '10', +}) + +console.log(result.txHash) +``` diff --git a/docs/simpleXRPL/tutorials/connect-custodians.md b/docs/simpleXRPL/tutorials/connect-custodians.md new file mode 100644 index 00000000..edfeb634 --- /dev/null +++ b/docs/simpleXRPL/tutorials/connect-custodians.md @@ -0,0 +1,93 @@ +--- +seo: + description: Construct and authenticate each simpleXRPL connector, then bind them so every vertical verb routes to the custodian that owns the account. +labels: + - SDKs +--- + +# Connect To Custodians + +Construct and authenticate each connector independently, then bind them with `SimpleXRPL.init`. Once bound, every vertical verb routes automatically to the custodian that owns the acting account. + +```ts +/** + * Custodian-specific connections. + * + * Each connector is constructed and authenticated independently, then passed to + * `SimpleXRPL.init`. Once bound, every vertical verb works the same regardless + * of which connector owns the acting account — the SDK routes each write to the + * custodian that holds the account. + * + * Config is read from the environment / your secrets manager so this drops + * straight into your app — never hard-code credentials or keys. Endpoints below + * point at the sandbox / testnet; swap them for production when you go live. + */ +import { + LocalSigner, + PalisadeCustody, + RippleCustody, + SimpleXRPL, +} from 'simplexrpl' + +// --- Palisade (Wallet-as-a-Service) --------------------------------------- + +// Palisade authenticates via OAuth client credentials and acts on a specific +// vault/wallet. `create` exchanges credentials and discovers the org's wallets. +const palisade = await PalisadeCustody.create({ + baseUrl: 'https://api.sandbox.palisade.co', // sandbox (TESTNET data) + clientId: process.env.PALISADE_CLIENT_ID ?? '', + clientSecret: process.env.PALISADE_CLIENT_SECRET ?? '', + primary: { + vaultId: process.env.PALISADE_VAULT_ID ?? '', + walletId: process.env.PALISADE_WALLET_ID ?? '', + }, + // Enable the raw sign-only fallback for transactors Palisade has no native + // operation for. Off by default. + allowRawSigning: false, +}) + +// --- Ripple Custody ------------------------------------------------------- + +// Ripple Custody authenticates with an intent-author key (PEM contents or a +// path to a `.pem`) exchanged for a token, and operates within one Custody +// domain. Unlike Palisade — which has one shared, public sandbox URL — a +// Custody deployment is per-tenant: its gateway/token URLs point at the +// instance Ripple provisions for you (sandbox or production), so they belong +// in config rather than hard-coded. `fromEnv` reads every `RIPPLE_CUSTODY_*` +// variable for exactly this reason: +const rippleCustody = await RippleCustody.fromEnv({ + primary: process.env.RIPPLE_CUSTODY_PRIMARY ?? '', +}) + +// The explicit form, if you configure it yourself rather than via the env: +// const rippleCustody = await RippleCustody.create({ +// gatewayUrl: process.env.RIPPLE_CUSTODY_GATEWAY_URL ?? '', +// auth: { +// signingKey: process.env.RIPPLE_CUSTODY_AUTH_SIGNING_KEY ?? '', +// tokenUrl: process.env.RIPPLE_CUSTODY_AUTH_TOKEN_URL ?? '', +// }, +// domainId: process.env.RIPPLE_CUSTODY_DOMAIN_ID ?? '', +// primary: process.env.RIPPLE_CUSTODY_PRIMARY ?? '', +// }) + +// --- Local signing (self-custody; keys held in-process) ------------------- +// For self-custodied accounts. `fromEnv` scans the environment for seeds. +const local = LocalSigner.fromEnv() + +// --- Bind the connectors -------------------------------------------------- + +const client = await SimpleXRPL.init({ + rippledUrl: 'wss://s.altnet.rippletest.net:51233', // XRPL Testnet + signers: [palisade, rippleCustody, local], + // The default backend for verbs called without an explicit `from`. + primarySigner: rippleCustody, +}) + +console.log('connected with', client.signers.length, 'connectors') +await client.disconnect() +``` + +## See Also + +- [Client and initialization](../references/index.md#client-and-initialization) +- [Connectors](../references/index.md#connectors) diff --git a/docs/simpleXRPL/tutorials/create-permissioned-domain.md b/docs/simpleXRPL/tutorials/create-permissioned-domain.md new file mode 100644 index 00000000..a23a99fb --- /dev/null +++ b/docs/simpleXRPL/tutorials/create-permissioned-domain.md @@ -0,0 +1,74 @@ +--- +seo: + description: Set up a permissioned domain that restricts participation to credential holders, then scope DEX offers to it. +labels: + - SDKs +--- + +# Create A Permissioned Domain + +A permissioned domain restricts who can participate based on the credentials they hold. Create the domain with the credentials it accepts, then scope DEX offers to it with `domainID`. + +```ts +/** + * Set up a permissioned domain and trade inside it. + * + * A permissioned domain restricts who can participate based on the credentials + * they hold. Create the domain with the credentials it accepts, then scope DEX + * offers to it with `domainID`. + */ +import { LocalSigner, SimpleXRPL } from 'simplexrpl' + +const client = await SimpleXRPL.init({ + rippledUrl: 'wss://s.altnet.rippletest.net:51233', + signers: [LocalSigner.fromEnv()], +}) + +// 1. Create the domain, listing the credentials it accepts (issuer + type). +const domain = await client.domain.create({ + credList: [ + { issuer: 'rKycIssuer0000000000000000000000000', credType: 'KYC' }, + { issuer: 'rAccreditation000000000000000000000', credType: 'ACCREDITED' }, + ], +}) +const domainID = domain.intent.domainID +console.log('permissioned domain:', domainID) + +// 2. Update the accepted credentials later if the policy changes. +await client.domain.setCredentials({ + domain: domainID, + credList: [ + { issuer: 'rKycIssuer0000000000000000000000000', credType: 'KYC' }, + ], +}) + +// 3. Place a domain-scoped DEX offer. With `domainID` set, the offer defaults +// to hybrid (also crosses the open DEX) unless `hybrid: false` is passed. +await client.iou.sellOffer({ + ticker: 'USD', + amount: 100, + orderType: 'limit', + price: { currency: 'XRP', amount: 50 }, + domainID, + hybrid: false, // permissioned-only: do not touch the open DEX +}) + +// 4. Read it back (no signer required). `retrieve` resolves a domain by id and +// returns its owner and accepted-credential list (decoded from hex); `list` +// returns every domain owned by an account (defaults to the primary). +const read = await client.domain.retrieve({ domainID }) +console.log('accepts:', read.data?.credList) + +const owned = await client.domain.list() +console.log('owned domains:', owned.domains) + +await client.disconnect() +``` + +## See Also + +- [`domain.create()`](../references/verticals/domain/create.md) +- [`domain.setCredentials()`](../references/verticals/domain/setCredentials.md) +- [`domain.retrieve()`](../references/verticals/domain/retrieve.md) +- [`domain.list()`](../references/verticals/domain/list.md) +- [`iou.sellOffer()`](../references/verticals/iou/sellOffer.md) diff --git a/docs/simpleXRPL/tutorials/cross-custodian-workflows.md b/docs/simpleXRPL/tutorials/cross-custodian-workflows.md new file mode 100644 index 00000000..93056482 --- /dev/null +++ b/docs/simpleXRPL/tutorials/cross-custodian-workflows.md @@ -0,0 +1,94 @@ +--- +seo: + description: Drive accounts held by different custodians from a single client, using per-call routing or an ordered multi-step sequence. +labels: + - SDKs +--- + +# Run A Workflow Across Custodians + +A single client can drive accounts held by different connectors. Sequence work across them either with per-call `from` routing (the common case) or with `runMultiStep`, which commits an ordered (transaction, account) sequence — steps that can target different custodians — from one call site. + +```ts +/** + * Run a workflow across two custodians. + * + * A single client can drive accounts held by different connectors. Two ways to + * sequence work across them: + * + * 1. Vertical verbs with `from` — each call routes to the custodian that owns + * the named account. Best for the common case. + * 2. `runMultiStep` — commits an ordered (transaction, account) sequence step + * by step (no rollback), where steps can target different custodians. Best + * when the order matters and you want one call site. + */ +import { + PalisadeCustody, + RippleCustody, + runMultiStep, + SimpleXRPL, +} from 'simplexrpl' +import type { Transaction } from 'simplexrpl' + +// A common institutional split: the issuer is held in Ripple Custody (governed +// approvals), the distribution/hot wallet in Palisade. One client drives both. +// Config comes from the environment / your secrets manager. +const custody = await RippleCustody.fromEnv({ + primary: process.env.RIPPLE_CUSTODY_PRIMARY ?? '', +}) +const palisade = await PalisadeCustody.create({ + baseUrl: 'https://api.sandbox.palisade.co', // sandbox (TESTNET data) + clientId: process.env.PALISADE_CLIENT_ID ?? '', + clientSecret: process.env.PALISADE_CLIENT_SECRET ?? '', + primary: { + vaultId: process.env.PALISADE_VAULT_ID ?? '', + walletId: process.env.PALISADE_WALLET_ID ?? '', + }, +}) + +const client = await SimpleXRPL.init({ + rippledUrl: 'wss://s.altnet.rippletest.net:51233', // XRPL Testnet + signers: [custody, palisade], +}) + +// One account on each connector. +const issuer = client.resolveAccount(custody.primary.address) +const hotWallet = client.resolveAccount(palisade.primary.address) + +// --- Approach 1: vertical verbs, each targeting a different custodian ------ +// Issue an IOU as the Custody issuer, then pay out from the Palisade wallet. +await client.iou.issue({ ticker: 'USD' }) +await client.xrp.transfer( + { to: 'rBeneficiary00000000000000000000000', amount: '25' }, + { from: hotWallet.address }, +) + +// --- Approach 2: an ordered multi-step workflow across both ---------------- +const stepOne: Transaction = { + TransactionType: 'Payment', + Account: issuer.address, + Destination: 'rBeneficiary00000000000000000000000', + Amount: '1000000', +} +const stepTwo: Transaction = { + TransactionType: 'Payment', + Account: hotWallet.address, + Destination: 'rBeneficiary00000000000000000000000', + Amount: '2000000', +} + +// Step 1 signs on Ripple Custody, step 2 on Palisade — each routed +// automatically to the connector that owns the account. +const results = await runMultiStep(client, [ + { transaction: stepOne, account: issuer }, + { transaction: stepTwo, account: hotWallet }, +]) +console.log(`workflow committed ${results.length} steps`) + +await client.disconnect() +``` + +## See Also + +- [`iou.issue()`](../references/verticals/iou/issue.md) +- [`xrp.transfer()`](../references/verticals/xrp/transfer.md) diff --git a/docs/simpleXRPL/tutorials/discover-acounts.md b/docs/simpleXRPL/tutorials/discover-acounts.md new file mode 100644 index 00000000..12b9e54e --- /dev/null +++ b/docs/simpleXRPL/tutorials/discover-acounts.md @@ -0,0 +1,65 @@ +--- +seo: + description: List and resolve the accounts each custodian discovered, and re-discover at runtime, from the single account index init builds. +labels: + - SDKs +--- + +# Discover Accounts + +Custodians discover their accounts at construction, and `init` merges them into one index keyed by r-address. List them per-connector or across the whole client, resolve a specific account, and re-discover at runtime. + +```ts +/** + * Account discovery. + * + * Custodians discover their accounts at construction; `init` merges them into a + * single index keyed by r-address. You can list them per-connector or across + * the whole client, resolve a specific account, and re-discover at runtime. + */ +import { LocalSigner, SimpleXRPL } from 'simplexrpl' + +const client = await SimpleXRPL.init({ + rippledUrl: 'wss://s.altnet.rippletest.net:51233', + signers: [LocalSigner.fromEnv()], +}) + +// 1. Every account the client knows, across all connectors (r-address → account). +for (const [address, account] of client.accounts) { + console.log(address, '→', account.signer.kind) +} + +// 2. Per-connector discovery: ask a single custodian what it owns. +for (const signer of client.signers) { + const owned = await signer.listAccounts() + console.log(signer.kind, 'owns', owned.length, 'account(s)') +} + +// 3. Resolve the account a verb would act on. With no argument, the primary +// signer's primary account; or pass an r-address / a { signer } selector. +const primary = client.resolveAccount() +console.log('primary:', primary.address) +const specific = client.resolveAccount('rSomeKnownAddress0000000000000000000') +console.log('resolved:', specific.address) + +// 4. Re-discover after upstream changes (e.g. a new custodian wallet). +await client.refreshAccounts() + +// 5. Read an account's on-chain state (no signer required). With no argument it +// reads the primary signer's account; pass an r-address to read any account. +const state = await client.account.retrieve() +console.log('primary balance (XRP):', state.data.xrpBalance) +console.log( + 'sequence:', + state.data.sequence, + 'owner objects:', + state.data.ownerCount, +) + +await client.disconnect() +``` + +## See Also + +- [`account.retrieve()`](../references/verticals/account/retrieve.md) +- [Client and initialization](../references/index.md#client-and-initialization) diff --git a/docs/simpleXRPL/tutorials/external-signer.md b/docs/simpleXRPL/tutorials/external-signer.md new file mode 100644 index 00000000..828bc3f6 --- /dev/null +++ b/docs/simpleXRPL/tutorials/external-signer.md @@ -0,0 +1,118 @@ +--- +seo: + description: Implement the ExternalSignerPort seam end to end with a mock signer, and switch between secp256k1 and ed25519. +labels: + - SDKs +--- + +# Implement An External Signer + +The `ExternalSignerPort` seam lets you plug in your own signer. This sample implements it with an in-process key so it actually signs and submits against a mock ledger, and shows how to switch between the secp256k1 and ed25519 schemes. In production you swap the mock for a KMS or HSM signer — nothing else changes. + +```ts +/** + * External signing end to end, with a mock signer — and switching algorithms. + * + * The `ExternalSignerPort` seam covers both XRPL signature schemes. This sample + * implements it with an in-process key (via `@noble/curves`) so it actually + * signs and "submits" a transaction against a mock ledger — handy for local + * tests. In production you swap the mock for a KMS or HSM signer; nothing else + * changes. + * + * secp256k1 vs ed25519 is just a different port implementation — pick whichever + * your signer's key uses. The SDK routes the crypto accordingly (secp256k1: + * SHA-512Half digest → low-S → DER; ed25519: sign the message directly). + */ +import { ed25519 } from '@noble/curves/ed25519' +import { secp256k1 } from '@noble/curves/secp256k1' +import { ExternalSigner, SimpleXRPL } from 'simplexrpl' +import type { Ed25519SignerPort, Secp256k1SignerPort } from 'simplexrpl' + +import { inMemoryLedger } from './mocks.js' + +// --- Mock signers (in-process keys — for local testing only) --------------- + +/** + * A mock secp256k1 signer. A real one delegates the digest to a KMS/HSM. + * + * @param privHex - The 32-byte private key hex (test only). + * @returns The port. + */ +function mockSecp256k1(privHex: string): Secp256k1SignerPort { + const priv = Buffer.from(privHex, 'hex') + return { + algorithm: 'secp256k1', + publicKey: async (): Promise => + Buffer.from(secp256k1.getPublicKey(priv, true)) + .toString('hex') + .toUpperCase(), + signDigest: async (digest: Uint8Array) => { + const sig = secp256k1.sign(digest, priv) + return { r: sig.r, s: sig.s } + }, + } +} + +/** + * A mock ed25519 signer. XRPL prefixes the public key with `ED`. + * + * @param privHex - The 32-byte private key hex (test only). + * @returns The port. + */ +function mockEd25519(privHex: string): Ed25519SignerPort { + const priv = Buffer.from(privHex, 'hex') + return { + algorithm: 'ed25519', + publicKey: async (): Promise => + `ED${Buffer.from(ed25519.getPublicKey(priv)).toString('hex')}`.toUpperCase(), + signMessage: async (message: Uint8Array): Promise => + ed25519.sign(message, priv), + } +} + +/** + * Bind a signer, then build + sign + submit a real transfer through it. + * + * @param signer - The external signer port (either algorithm). + * @param label - A label for the log line. + */ +async function signAndSubmit( + signer: Secp256k1SignerPort | Ed25519SignerPort, + label: string, +): Promise { + const custody = await ExternalSigner.create({ signer }) + const client = await SimpleXRPL.init({ + rippledUrl: 'wss://s.altnet.rippletest.net:51233', + signers: [custody], + ledger: inMemoryLedger(), + }) + const result = await client.xrp.transfer({ + to: client.account.create().address, + amount: '10', + }) + console.log( + `${label}: account ${custody.primary.address} signed & submitted ` + + `(source=${result.source}, hash=${result.txHash})`, + ) + await client.disconnect() +} + +// Switch algorithms by swapping the port — the pipeline is identical. +await signAndSubmit( + mockSecp256k1( + 'c9537c5a2f3f7e1d4b6a8c0e2f4d6b8a1c3e5f7091b3d5f7a9c1e3050709b0d0f', + ), + 'secp256k1', +) +await signAndSubmit( + mockEd25519( + '9d61b19deffebc3a6c1f6b2d7e5f8a0b1c2d3e4f5061728394a5b6c7d8e9f001', + ), + 'ed25519', +) +``` + +## See Also + +- [`account.create()`](../references/verticals/account/create.md) +- [`xrp.transfer()`](../references/verticals/xrp/transfer.md) diff --git a/docs/simpleXRPL/tutorials/implement-aws-kms-signer.md b/docs/simpleXRPL/tutorials/implement-aws-kms-signer.md new file mode 100644 index 00000000..d13b000e --- /dev/null +++ b/docs/simpleXRPL/tutorials/implement-aws-kms-signer.md @@ -0,0 +1,52 @@ +--- +seo: + description: Sign transactions with a secp256k1 key held in AWS KMS using the simplexrpl/aws-kms adapter; the private key never leaves KMS. +labels: + - SDKs +--- + +# Sign With AWS KMS + +simpleXRPL ships an AWS KMS adapter as a subpath import (`simplexrpl/aws-kms`). The private key stays in KMS and never enters the process — the SDK hands KMS a digest and assembles the signature. + +```ts +/** + * Sign with a key held in AWS KMS. + * + * simpleXRPL ships an AWS KMS adapter as a subpath import. The private key + * stays in KMS and never enters the process: the SDK hands KMS a digest and + * assembles the signature. Requires the optional peer dependency + * `@aws-sdk/client-kms` and an `ECC_SECG_P256K1` (secp256k1) KMS key. + * + * Credentials come from the standard AWS chain (env vars, shared profile, or an + * instance/role). This drops into your app once those and the key id are set. + */ +import { AwsKmsSigner } from 'simplexrpl/aws-kms' +import { ExternalSigner, SimpleXRPL } from 'simplexrpl' + +// The KMS-backed signer. Its XRPL account is derived from the key's public key. +const signer = AwsKmsSigner.create({ + keyId: process.env.AWS_KMS_KEY_ID ?? '', + region: process.env.AWS_REGION ?? 'us-east-1', +}) +const custody = await ExternalSigner.create({ signer }) + +const client = await SimpleXRPL.init({ + rippledUrl: 'wss://s.altnet.rippletest.net:51233', // XRPL Testnet + signers: [custody], +}) + +// The KMS account signs like any other connector — build, sign (in KMS), submit. +// Replace with a real, funded destination r-address. +const result = await client.xrp.transfer({ + to: 'rPT1Sjq2YGrBMTttX4GZHjKu9dyfzbpAYe', + amount: '10', +}) +console.log('submitted via KMS-held key:', result.txHash) + +await client.disconnect() +``` + +## See Also + +- [`xrp.transfer()`](../references/verticals/xrp/transfer.md) diff --git a/docs/simpleXRPL/tutorials/implement-pkcs11-signer.md b/docs/simpleXRPL/tutorials/implement-pkcs11-signer.md new file mode 100644 index 00000000..3ec322f2 --- /dev/null +++ b/docs/simpleXRPL/tutorials/implement-pkcs11-signer.md @@ -0,0 +1,150 @@ +--- +seo: + description: Implement the ExternalSignerPort seam against a PKCS#11 HSM — you provide the public key and digest signing; the SDK owns the XRPL crypto. +labels: + - SDKs +--- + +# Implement A PKCS#11 HSM Signer + +For an HSM, you implement the same `ExternalSignerPort` seam against your device: you provide only "give me the public key" and "sign this digest," and the SDK owns the XRPL crypto. HSM setups vary, so this is a reference to adapt rather than a drop-in. + +```ts +/** + * Bring-your-own HSM signer (PKCS#11). + * + * simpleXRPL ships an AWS KMS adapter (`simplexrpl/aws-kms`); for an HSM you + * implement the same `ExternalSignerPort` seam against your device. HSM setups + * vary (slot, PIN, key label, vendor library), so this is a reference to adapt + * rather than a drop-in — the SDK owns the XRPL crypto (SHA-512Half digest, + * low-S normalization, DER encoding); you only provide "give me the public key" + * and "sign this digest". + * + * Wire the `Hsm` interface below to your PKCS#11 binding (e.g. `pkcs11js` or + * `graphene-lib`); the exact calls are noted per method. + */ +import { secp256k1 } from '@noble/curves/secp256k1' +import { ExternalSigner, SimpleXRPL } from 'simplexrpl' +import type { EcdsaSignature, Secp256k1SignerPort } from 'simplexrpl' + +import { inMemoryLedger } from './mocks.js' + +/** secp256k1 sizes: 32-byte scalars, 65-byte uncompressed point (0x04‖X‖Y). */ +const SCALAR_BYTES = 32 +const POINT_BYTES = 65 +const COMPRESSED_EVEN = 0x02 +const COMPRESSED_ODD = 0x03 +const EVEN = 2 + +/** + * The narrow slice of your HSM the signer needs. Implement it with your PKCS#11 + * binding against an ECDSA secp256k1 key. + */ +interface Hsm { + /** + * The key's public point. In PKCS#11: `C_GetAttributeValue(session, + * pubKeyHandle, [CKA_EC_POINT])` — a DER OCTET STRING wrapping the + * uncompressed point (`0x04‖X‖Y`). + */ + readonly ecPoint: () => Promise + + /** + * Sign a 32-byte digest and return the raw 64-byte `r‖s`. In PKCS#11: + * `C_SignInit(session, { mechanism: CKM_ECDSA }, privKeyHandle)` then + * `C_Sign(session, digest)`. + * + * IMPORTANT: use `CKM_ECDSA` (signs the digest as-is), NOT `CKM_ECDSA_SHA256` + * — XRPL's digest is SHA-512Half, and letting the HSM re-hash would corrupt + * the signature. + */ + readonly signDigest: (digest: Uint8Array) => Promise +} + +/** + * Strip the DER OCTET STRING wrapper `CKA_EC_POINT` uses; the uncompressed + * point is the trailing 65 bytes. + * + * @param ecPoint - The raw `CKA_EC_POINT` attribute value. + * @returns The uncompressed point (`0x04‖X‖Y`). + */ +function uncompressedPoint(ecPoint: Uint8Array): Buffer { + return Buffer.from(ecPoint).subarray(-POINT_BYTES) +} + +/** An {@link Secp256k1SignerPort} backed by a PKCS#11 HSM. */ +class Pkcs11Signer implements Secp256k1SignerPort { + public readonly algorithm = 'secp256k1' + + public constructor(private readonly hsm: Hsm) {} + + /** + * Compress the HSM's public point to XRPL's 33-byte hex form. + * + * @returns The compressed public key hex. + */ + public async publicKey(): Promise { + const point = uncompressedPoint(await this.hsm.ecPoint()) + const x = point.subarray(1, 1 + SCALAR_BYTES) + const y = point.subarray(1 + SCALAR_BYTES) + const prefix = + y[y.length - 1] % EVEN === 0 ? COMPRESSED_EVEN : COMPRESSED_ODD + return Buffer.concat([Buffer.from([prefix]), x]) + .toString('hex') + .toUpperCase() + } + + /** + * Split the HSM's raw `r‖s` signature into scalars; the SDK normalizes to + * low-S and DER-encodes. + * + * @param digest - The 32-byte digest to sign. + * @returns The signature scalars. + */ + public async signDigest(digest: Uint8Array): Promise { + const raw = Buffer.from(await this.hsm.signDigest(digest)) + return { + r: BigInt(`0x${raw.subarray(0, SCALAR_BYTES).toString('hex')}`), + s: BigInt(`0x${raw.subarray(SCALAR_BYTES).toString('hex')}`), + } + } +} + +// DEMO ONLY: an in-process key standing in for the HSM so this file runs +// end to end. Your real `Hsm` calls PKCS#11 (see the notes above) and returns +// the same shapes — a DER-wrapped `CKA_EC_POINT` and a raw `r‖s` — so nothing +// downstream changes. +function demoHsm(privHex: string): Hsm { + const priv = Buffer.from(privHex, 'hex') + return { + ecPoint: async (): Promise => + secp256k1.getPublicKey(priv, false), // 65-byte 0x04‖X‖Y + signDigest: async (digest: Uint8Array): Promise => + secp256k1.sign(digest, priv).toCompactRawBytes(), // raw r‖s + } +} + +const hsm = demoHsm( + 'c9537c5a2f3f7e1d4b6a8c0e2f4d6b8a1c3e5f7091b3d5f7a9c1e3050709b0d0f', +) +const custody = await ExternalSigner.create({ signer: new Pkcs11Signer(hsm) }) +const client = await SimpleXRPL.init({ + rippledUrl: 'wss://s.altnet.rippletest.net:51233', // XRPL Testnet + signers: [custody], + ledger: inMemoryLedger(), // omit in production to use the live XRPL connection +}) + +// `client.xrp`, `client.iou`, etc. now sign through the HSM — the private key +// never leaves the device. Build → sign (in the HSM) → submit: +const destination = client.account.create().address +const result = await client.xrp.transfer({ to: destination, amount: '10' }) +console.log( + `HSM account ${custody.primary.address} signed & submitted ` + + `(source=${result.source}, hash=${result.txHash})`, +) +await client.disconnect() +``` + +## See Also + +- [`account.create()`](../references/verticals/account/create.md) +- [`xrp.transfer()`](../references/verticals/xrp/transfer.md) diff --git a/docs/simpleXRPL/tutorials/inititialize-clients.md b/docs/simpleXRPL/tutorials/inititialize-clients.md new file mode 100644 index 00000000..fb72e52a --- /dev/null +++ b/docs/simpleXRPL/tutorials/inititialize-clients.md @@ -0,0 +1,61 @@ +--- +seo: + description: Initialize the simpleXRPL client with SimpleXRPL.init — bind connectors to a network and build the account index. +labels: + - SDKs +--- + +# Initialize The Client + +`SimpleXRPL.init(...)` is the single entry point: it binds already-authenticated connectors to a network and builds the account index. The client is never constructed with `new`. + +```ts +/** + * Initialization: choosing a network, connectors, and binding accounts. + * + * `SimpleXRPL.init(...)` is the only entry point — it binds pre-constructed, + * already-authenticated custodians (the "connectors") to a network and builds + * the account index. The client is never constructed with `new`. + */ +import { LocalSigner, SimpleXRPL } from 'simplexrpl' + +// 1. Choose a network by pointing at a rippled endpoint. `faucetUrl` is only +// used on test networks (for `client.account.fund`). +const client = await SimpleXRPL.init({ + rippledUrl: 'wss://s.altnet.rippletest.net:51233', + faucetUrl: 'https://faucet.altnet.rippletest.net/accounts', + + // 2. Choose your connector(s). Each custodian is constructed and + // authenticated on its own, then handed to `init`. Here we bind a single + // local-signing backend that reads its seeds from the environment. + signers: [LocalSigner.fromEnv()], + + // 3. `primarySigner` is the default backend for verbs called without an + // explicit account. Defaults to `signers[0]`, so this line is optional. + // primarySigner: someSigner, +}) + +// With no `signers`, the client is read-only: reads work, but write verbs throw +// `NoSignerError` until a signer is added. + +// 4. Bind (register) an account at runtime — e.g. a freshly created wallet — +// so verbs can act on it immediately. Returns the registered account. +const seed = process.env.NEW_ACCOUNT_SEED +if (seed !== undefined) { + const account = client.registerLocalAccount(seed) + console.log('registered', account.address) +} + +// 5. Verbs default to the primary account; target any bound account with `from`. +await client.xrp.transfer({ + to: 'rDestination00000000000000000000000', + amount: '10', +}) + +await client.disconnect() +``` + +## See Also + +- [Client and initialization](../references/index.md#client-and-initialization) +- [`xrp.transfer()`](../references/verticals/xrp/transfer.md) diff --git a/docs/simpleXRPL/tutorials/issue-and-distribute-iou.md b/docs/simpleXRPL/tutorials/issue-and-distribute-iou.md new file mode 100644 index 00000000..738104b2 --- /dev/null +++ b/docs/simpleXRPL/tutorials/issue-and-distribute-iou.md @@ -0,0 +1,77 @@ +--- +seo: + description: Issue a trust-line currency (IOU) and distribute it: bootstrap the issuer and hot wallet, then transfer the currency out. +labels: + - SDKs +--- + +# Issue And Distribute An IOU + +`issue` bootstraps the issuer and a hot wallet from the environment (the issuer enables rippling and the hot wallet extends a trust line); no value exists until `transfer` sends the currency out. Every verb acts as the issuer, selected via `from`. + +```ts +/** + * Issue and distribute an IOU (trust-line currency). + * + * `issue` bootstraps the issuer and a hot wallet from the environment + * (`XRPL_ISSUER_SEED`, `XRPL_HOT_WALLET_SEED`): the issuer enables rippling and + * the hot wallet extends a trust line. No value exists yet — `transfer` sends + * the currency out from the issuer. Every verb acts as the issuer, selected via + * `from` (defaults to the primary signer's account). + */ +import { LocalSigner, SimpleXRPL } from 'simplexrpl' + +const client = await SimpleXRPL.init({ + rippledUrl: 'wss://s.altnet.rippletest.net:51233', + signers: [LocalSigner.fromEnv()], +}) + +// 1. Issue. Returns the IOU id, e.g. "USD.rIssuer...". +const issued = await client.iou.issue({ ticker: 'USD' }) +console.log('issued', issued.intent.iouID) + +// 2. Distribute: send 1,000 USD from the issuer to a holder. The holder must +// already trust the issuer for this currency (the hot wallet set up in step +// 1 does; other holders extend their own trust line first). +await client.iou.transfer({ + ticker: 'USD', + destination: 'rHolder00000000000000000000000000000', + amount: 1000, +}) + +// 3. Optional issuer controls, all scoped to the same currency: +// - authorize a holder (when the issuer requires authorization) +// - lock / unlock a holder's line (reversible freeze) +// - clawback (requires clawback enabled before any trust lines exist) +await client.iou.authorize({ + ticker: 'USD', + holder: 'rHolder00000000000000000000000000000', +}) + +// 4. Read it back (no signer required). `retrieve` returns a single shaped +// trust line for the holder→issuer pair; `list` returns all of an account's +// lines. Pass `account` to read any address, or omit it for the primary. +// The issuer is the second half of the iouID ("USD.rIssuer..."). +const [, issuer] = issued.intent.iouID.split('.') +const holder = 'rHolder00000000000000000000000000000' + +const line = await client.iou.retrieve({ + ticker: 'USD', + issuer, + account: holder, +}) +console.log('holder balance:', line.data?.balance ?? '0') + +const all = await client.iou.list({ account: holder }) +console.log('holder trust lines:', all.ious) + +await client.disconnect() +``` + +## See Also + +- [`iou.issue()`](../references/verticals/iou/issue.md) +- [`iou.transfer()`](../references/verticals/iou/transfer.md) +- [`iou.authorize()`](../references/verticals/iou/authorize.md) +- [`iou.retrieve()`](../references/verticals/iou/retrieve.md) +- [`iou.list()`](../references/verticals/iou/list.md) diff --git a/docs/simpleXRPL/tutorials/issue-rwa-as-mpt.md b/docs/simpleXRPL/tutorials/issue-rwa-as-mpt.md new file mode 100644 index 00000000..69817465 --- /dev/null +++ b/docs/simpleXRPL/tutorials/issue-rwa-as-mpt.md @@ -0,0 +1,77 @@ +--- +seo: + description: Issue a Real-World Asset as a Multi-Purpose Token (MPT) through Ripple Custody, with XLS-89 metadata validated before submission. +labels: + - SDKs +--- + +# Issue An RWA As An MPT + +Real-World Assets are issued as Multi-Purpose Tokens (MPTs) via the `token` vertical. Here the issuer is a Ripple Custody account, so Custody signs and submits the issuance as one governed action, with XLS-89 metadata validated before submission. + +```ts +/** + * Issue a Real-World Asset (RWA) through Ripple Custody. + * + * RWAs are issued as Multi-Purpose Tokens (MPTs) via the `token` vertical. + * Metadata follows the XLS-89 standard and is validated before submission + * (`asset_class: 'rwa'` requires an `asset_subclass`). Here the issuer is a + * Ripple Custody account: Custody signs and submits the issuance as one + * governed action, subject to the domain's approval policy. + */ +import { RippleCustody, SimpleXRPL } from 'simplexrpl' + +// The Custody-held issuer account; Custody governs every write it signs. +const ISSUER_ADDRESS = process.env.RIPPLE_CUSTODY_PRIMARY ?? '' + +// Config (gateway, token endpoint, domain, intent-author key) comes from +// `RIPPLE_CUSTODY_*` environment variables via `fromEnv`. +const custody = await RippleCustody.fromEnv({ primary: ISSUER_ADDRESS }) + +const client = await SimpleXRPL.init({ + rippledUrl: 'wss://s.altnet.rippletest.net:51233', // XRPL Testnet + signers: [custody], +}) + +const result = await client.token.issue( + { + metadata: { + ticker: 'TBILL', + name: 'Acme 3-Month T-Bill', + icon: 'https://acme.example/tbill.png', + asset_class: 'rwa', + asset_subclass: 'treasury', + issuer_name: 'Acme Capital', + }, + // 2 decimal places of display precision. + assetScale: 2, + // 0.5% fee on secondary transfers. + transferFee: 0.5, + // Keep the issuer able to claw back (compliance); other capabilities on. + flags: { canClawback: true, canTransfer: true }, + }, + // Issue as the Custody account. Omit `from` to use the primary signer. + { from: ISSUER_ADDRESS }, +) + +// `MPTokenIssuanceCreate` is native to Ripple Custody, so this returns once the +// governed action reaches a terminal state — or throws `IntentPendingError` if +// it's still awaiting approval past the timeout. +console.log('issued MPT:', result.intent.mptIssuanceId) + +// Read the issuance back (no signer required): flags are decoded to booleans, +// the transfer fee to a percentage, and XLS-89 metadata is parsed. +const token = await client.token.retrieve({ + mptIssuanceId: result.intent.mptIssuanceId, +}) +console.log('transfer fee (%):', token.data?.transferFee) +console.log('can claw back:', token.data?.flags.canClawback) +console.log('metadata:', token.data?.metadata?.name) + +await client.disconnect() +``` + +## See Also + +- [`token.issue()`](../references/verticals/token/issue.md) +- [`token.retrieve()`](../references/verticals/token/retrieve.md) diff --git a/docs/simpleXRPL/tutorials/place-dex-order.md b/docs/simpleXRPL/tutorials/place-dex-order.md new file mode 100644 index 00000000..5e6919ea --- /dev/null +++ b/docs/simpleXRPL/tutorials/place-dex-order.md @@ -0,0 +1,89 @@ +--- +seo: + description: Place buy and sell orders on the XRP Ledger DEX with the iou and token verticals, using familiar order types. +labels: + - SDKs +--- + +# Place A DEX Order + +The `iou` vertical places orders to buy or sell an issued currency; the `token` vertical places generic offers between any two DEX-tradeable assets (XRP or IOU). The order type controls how the offer is worked. + +```ts +/** + * Place an order on the DEX. + * + * The `iou` vertical places orders to buy or sell an issued currency; the + * `token` vertical places generic offers between any two DEX-tradeable assets + * (XRP or IOU). Order type controls how the offer is worked. + */ +import { iou, LocalSigner, SimpleXRPL, XRP_ASSET } from 'simplexrpl' + +const client = await SimpleXRPL.init({ + rippledUrl: 'wss://s.altnet.rippletest.net:51233', + signers: [LocalSigner.fromEnv()], +}) + +// --- Via the IOU vertical: sell 100 USD for 50 XRP ------------------------- +// orderType: 'limit' rests on the book; 'market' = immediate-or-cancel; +// 'fok' = fill-or-kill; 'passive' = rest without crossing. +const sell = await client.iou.sellOffer({ + ticker: 'USD', + amount: 100, + orderType: 'limit', + price: { currency: 'XRP', amount: 50 }, +}) +console.log('sell offer submitted:', sell.txHash) + +// Buy 100 USD, paying in another IOU (EUR): +await client.iou.buyOffer({ + ticker: 'USD', + amount: 100, + orderType: 'fok', + price: { + ticker: 'EUR', + issuer: 'rEurIssuer000000000000000000000000', + amount: 90, + }, +}) + +// Read your resting offers back (no signer required) — each is shaped with its +// sequence, amount, price, and buy/sell type, ready to compose or cancel. +const mine = await client.account.listOffers() +for (const offer of mine.data) { + console.log(offer.type, offer.amount, '@', offer.price) +} + +// Or read the whole USD order book (both sides), regardless of who placed them: +const book = await client.iou.listOffers({ + ticker: 'USD', + issuer: 'rIssuer00000000000000000000000000000', +}) +console.log('resting USD offers:', book.data.length) + +// Cancel a resting offer by its sequence number — here, the first one read back: +if (mine.data.length > 0) { + await client.iou.cancelOffer({ offerSequence: mine.data[0].offerSequence }) +} + +// --- Via the token vertical: a generic XRP/IOU offer ----------------------- +await client.token.createOffer({ + takerGets: { asset: XRP_ASSET, value: '50' }, + takerPays: { + asset: iou('USD', 'rIssuer00000000000000000000000000000'), + value: '100', + }, + flags: { immediateOrCancel: true }, +}) + +await client.disconnect() +``` + +## See Also + +- [`iou.buyOffer()`](../references/verticals/iou/buyOffer.md) +- [`iou.sellOffer()`](../references/verticals/iou/sellOffer.md) +- [`iou.cancelOffer()`](../references/verticals/iou/cancelOffer.md) +- [`iou.listOffers()`](../references/verticals/iou/listOffers.md) +- [`token.createOffer()`](../references/verticals/token/createOffer.md) +- [`account.listOffers()`](../references/verticals/account/listOffers.md) diff --git a/docs/simpleXRPL/tutorials/read-routing-reports.md b/docs/simpleXRPL/tutorials/read-routing-reports.md new file mode 100644 index 00000000..9009b77f --- /dev/null +++ b/docs/simpleXRPL/tutorials/read-routing-reports.md @@ -0,0 +1,79 @@ +--- +seo: + description: Ask how a transactor would route for an account — native, raw-signing fallback, local, or rejected — before you submit. +labels: + - SDKs +--- + +# Read Routing Reports + +Before submitting, you can ask how a given transactor would route for a given account: signed locally, through a custodian’s native operation, via the raw sign-only fallback, or rejected. This lets you (and your reviewers) see exactly what will happen up front. + +```ts +/** + * Call the routing report. + * + * Before submitting, you can ask how a given transactor would route for a + * given account: signed locally, through a custodian's native operation, via + * the raw sign-only fallback, or rejected. `dispatch` returns that path and + * `isNativePath` tells you whether it goes through the custodian's own network + * rather than the shared ledger. + */ +import { + dispatch, + isNativePath, + LocalSigner, + SignerCapabilityError, + SimpleXRPL, +} from 'simplexrpl' +import type { SubmissionPath, TransactorType } from 'simplexrpl' + +const client = await SimpleXRPL.init({ + rippledUrl: 'wss://s.altnet.rippletest.net:51233', + signers: [LocalSigner.fromEnv()], +}) + +// The transactors the SDK's verticals emit. +const TRANSACTORS: TransactorType[] = [ + 'Payment', + 'TrustSet', + 'AccountSet', + 'OfferCreate', + 'OfferCancel', + 'Clawback', + 'MPTokenIssuanceCreate', + 'CredentialCreate', + 'PermissionedDomainSet', +] + +const account = client.resolveAccount() + +// A connector also advertises what it can do directly via `capabilities()`. +const caps = account.signer.capabilities() +console.log(`account ${account.address} (${account.signer.kind})`) +console.log(' raw signing:', caps.allowRaw ? 'enabled' : 'disabled') + +for (const transactor of TRANSACTORS) { + let path: SubmissionPath | 'rejected' = 'rejected' + try { + path = dispatch(account, transactor) + } catch (error) { + // `dispatch` throws when the custodian can neither natively nor raw-sign + // the transactor; anything else is unexpected, so rethrow it. + if (!(error instanceof SignerCapabilityError)) throw error + } + const via = + path === 'rejected' + ? '(unsupported)' + : isNativePath(path) + ? '(custodian network)' + : '(shared ledger)' + console.log(` ${transactor.padEnd(24)} → ${path} ${via}`) +} + +await client.disconnect() +``` + +## See Also + +- [Connector Routing](../references/connector-routing.md) diff --git a/index.page.tsx b/index.page.tsx index 7d57a23d..96bbfe8e 100644 --- a/index.page.tsx +++ b/index.page.tsx @@ -21,7 +21,7 @@ export default function Page() { - +

Prepare and submit up to 8 transactions in a single batch.

diff --git a/redocly.yaml b/redocly.yaml index c3fc6b6e..34698fb8 100644 --- a/redocly.yaml +++ b/redocly.yaml @@ -14,12 +14,12 @@ redirects: $ref: redirects.yaml navbar: items: - - label: Home - page: index.page.tsx - label: Open Source Projects page: docs/index.md - label: Roadmap - page: ripplex-roadmap.md + page: ripplex-roadmap.md + - label: simpleXRPL + page: docs/simpleXRPL/index.md footer: items: - group: About diff --git a/sidebars.yaml b/sidebars.yaml index ff1d1c10..d8f4fcb7 100644 --- a/sidebars.yaml +++ b/sidebars.yaml @@ -1,7 +1,151 @@ -- page: ripplex-roadmap.md - page: docs/index.md -- group: Prerelease Docs - expanded: true +- page: ripplex-roadmap.md +- group: simpleXRPL + page: docs/simpleXRPL/index.md + expanded: false + items: + - page: docs/simpleXRPL/get-started.md + - group: Tutorials + expanded: false + items: + - page: docs/simpleXRPL/tutorials/inititialize-clients.md + - page: docs/simpleXRPL/tutorials/connect-custodians.md + - page: docs/simpleXRPL/tutorials/discover-acounts.md + - page: docs/simpleXRPL/tutorials/issue-rwa-as-mpt.md + - page: docs/simpleXRPL/tutorials/issue-and-distribute-iou.md + - page: docs/simpleXRPL/tutorials/place-dex-order.md + - page: docs/simpleXRPL/tutorials/create-permissioned-domain.md + - page: docs/simpleXRPL/tutorials/cross-custodian-workflows.md + - page: docs/simpleXRPL/tutorials/read-routing-reports.md + - page: docs/simpleXRPL/tutorials/external-signer.md + - page: docs/simpleXRPL/tutorials/implement-aws-kms-signer.md + - page: docs/simpleXRPL/tutorials/implement-pkcs11-signer.md + - group: References + page: docs/simpleXRPL/references/index.md + expanded: false + items: + - page: docs/simpleXRPL/references/connector-routing.md + label: Connector Routing + - group: Verticals + page: docs/simpleXRPL/references/verticals/index.md + expanded: false + items: + - group: XRP + page: docs/simpleXRPL/references/verticals/xrp/index.md + expanded: false + items: + - page: docs/simpleXRPL/references/verticals/xrp/transfer.md + label: transfer() + - group: Token + page: docs/simpleXRPL/references/verticals/token/index.md + expanded: false + items: + - page: docs/simpleXRPL/references/verticals/token/issue.md + label: issue() + - page: docs/simpleXRPL/references/verticals/token/transfer.md + label: transfer() + - page: docs/simpleXRPL/references/verticals/token/authorize.md + label: authorize() + - page: docs/simpleXRPL/references/verticals/token/unauthorize.md + label: unauthorize() + - page: docs/simpleXRPL/references/verticals/token/grantHolder.md + label: grantHolder() + - page: docs/simpleXRPL/references/verticals/token/revokeHolder.md + label: revokeHolder() + - page: docs/simpleXRPL/references/verticals/token/lock.md + label: lock() + - page: docs/simpleXRPL/references/verticals/token/unlock.md + label: unlock() + - page: docs/simpleXRPL/references/verticals/token/destroy.md + label: destroy() + - page: docs/simpleXRPL/references/verticals/token/createOffer.md + label: createOffer() + - page: docs/simpleXRPL/references/verticals/token/cancelOffer.md + label: cancelOffer() + - page: docs/simpleXRPL/references/verticals/token/retrieve.md + label: retrieve() + - page: docs/simpleXRPL/references/verticals/token/list.md + label: list() + - page: docs/simpleXRPL/references/verticals/token/listOffers.md + label: listOffers() + - group: IOU + page: docs/simpleXRPL/references/verticals/iou/index.md + expanded: false + items: + - page: docs/simpleXRPL/references/verticals/iou/issue.md + label: issue() + - page: docs/simpleXRPL/references/verticals/iou/transfer.md + label: transfer() + - page: docs/simpleXRPL/references/verticals/iou/authorize.md + label: authorize() + - page: docs/simpleXRPL/references/verticals/iou/lock.md + label: lock() + - page: docs/simpleXRPL/references/verticals/iou/unlock.md + label: unlock() + - page: docs/simpleXRPL/references/verticals/iou/clawback.md + label: clawback() + - page: docs/simpleXRPL/references/verticals/iou/buyOffer.md + label: buyOffer() + - page: docs/simpleXRPL/references/verticals/iou/sellOffer.md + label: sellOffer() + - page: docs/simpleXRPL/references/verticals/iou/cancelOffer.md + label: cancelOffer() + - page: docs/simpleXRPL/references/verticals/iou/retrieve.md + label: retrieve() + - page: docs/simpleXRPL/references/verticals/iou/list.md + label: list() + - page: docs/simpleXRPL/references/verticals/iou/listOffers.md + label: listOffers() + - group: Credential + page: docs/simpleXRPL/references/verticals/credential/index.md + expanded: false + items: + - page: docs/simpleXRPL/references/verticals/credential/issue.md + label: issue() + - page: docs/simpleXRPL/references/verticals/credential/accept.md + label: accept() + - page: docs/simpleXRPL/references/verticals/credential/delete.md + label: delete() + - page: docs/simpleXRPL/references/verticals/credential/retrieve.md + label: retrieve() + - page: docs/simpleXRPL/references/verticals/credential/list.md + label: list() + - group: Domain + page: docs/simpleXRPL/references/verticals/domain/index.md + expanded: false + items: + - page: docs/simpleXRPL/references/verticals/domain/create.md + label: create() + - page: docs/simpleXRPL/references/verticals/domain/setCredentials.md + label: setCredentials() + - page: docs/simpleXRPL/references/verticals/domain/delete.md + label: delete() + - page: docs/simpleXRPL/references/verticals/domain/retrieve.md + label: retrieve() + - page: docs/simpleXRPL/references/verticals/domain/list.md + label: list() + - group: Account + page: docs/simpleXRPL/references/verticals/account/index.md + expanded: false + items: + - page: docs/simpleXRPL/references/verticals/account/create.md + label: create() + - page: docs/simpleXRPL/references/verticals/account/activate.md + label: activate() + - page: docs/simpleXRPL/references/verticals/account/fund.md + label: fund() + - page: docs/simpleXRPL/references/verticals/account/set.md + label: set() + - page: docs/simpleXRPL/references/verticals/account/setRegularKey.md + label: setRegularKey() + - page: docs/simpleXRPL/references/verticals/account/depositPreauth.md + label: depositPreauth() + - page: docs/simpleXRPL/references/verticals/account/retrieve.md + label: retrieve() + - page: docs/simpleXRPL/references/verticals/account/listOffers.md + label: listOffers() +- group: Amendments + expanded: false items: - page: docs/xls-85-token-escrow/index.page.tsx - page: docs/xls-81-permissioned-dexes/index.page.tsx From d4dae48083f060f1a237bfdebbffe1f3a7adb483 Mon Sep 17 00:00:00 2001 From: Oliver Eggert Date: Thu, 23 Jul 2026 11:30:48 -0700 Subject: [PATCH 02/24] fix frontmatter build error --- docs/simpleXRPL/tutorials/issue-and-distribute-iou.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/simpleXRPL/tutorials/issue-and-distribute-iou.md b/docs/simpleXRPL/tutorials/issue-and-distribute-iou.md index 738104b2..531c0504 100644 --- a/docs/simpleXRPL/tutorials/issue-and-distribute-iou.md +++ b/docs/simpleXRPL/tutorials/issue-and-distribute-iou.md @@ -1,6 +1,6 @@ --- seo: - description: Issue a trust-line currency (IOU) and distribute it: bootstrap the issuer and hot wallet, then transfer the currency out. + description: "Issue a trust-line currency (IOU) and distribute it: bootstrap the issuer and hot wallet, then transfer the currency out." labels: - SDKs --- From ad216a955f25fbbeeaa8703dd5186049535c756d Mon Sep 17 00:00:00 2001 From: Oliver Eggert Date: Thu, 23 Jul 2026 14:09:01 -0700 Subject: [PATCH 03/24] update frontmatter and clean up landing page --- docs/simpleXRPL/get-started.md | 5 ++-- docs/simpleXRPL/index.md | 28 ++++++++++--------- .../references/connector-routing.md | 3 +- docs/simpleXRPL/references/index.md | 3 +- .../references/verticals/account/activate.md | 3 +- .../references/verticals/account/create.md | 3 +- .../verticals/account/depositPreauth.md | 3 +- .../references/verticals/account/fund.md | 3 +- .../references/verticals/account/index.md | 3 +- .../verticals/account/listOffers.md | 3 +- .../references/verticals/account/retrieve.md | 3 +- .../references/verticals/account/set.md | 3 +- .../verticals/account/setRegularKey.md | 3 +- .../references/verticals/credential/accept.md | 3 +- .../references/verticals/credential/delete.md | 3 +- .../references/verticals/credential/index.md | 3 +- .../references/verticals/credential/issue.md | 3 +- .../references/verticals/credential/list.md | 3 +- .../verticals/credential/retrieve.md | 3 +- .../references/verticals/domain/create.md | 3 +- .../references/verticals/domain/delete.md | 3 +- .../references/verticals/domain/index.md | 3 +- .../references/verticals/domain/list.md | 3 +- .../references/verticals/domain/retrieve.md | 3 +- .../verticals/domain/setCredentials.md | 3 +- docs/simpleXRPL/references/verticals/index.md | 3 +- .../references/verticals/iou/authorize.md | 3 +- .../references/verticals/iou/buyOffer.md | 3 +- .../references/verticals/iou/cancelOffer.md | 3 +- .../references/verticals/iou/clawback.md | 3 +- .../references/verticals/iou/index.md | 3 +- .../references/verticals/iou/issue.md | 3 +- .../references/verticals/iou/list.md | 3 +- .../references/verticals/iou/listOffers.md | 3 +- .../references/verticals/iou/lock.md | 3 +- .../references/verticals/iou/retrieve.md | 3 +- .../references/verticals/iou/sellOffer.md | 3 +- .../references/verticals/iou/transfer.md | 3 +- .../references/verticals/iou/unlock.md | 3 +- .../references/verticals/token/authorize.md | 3 +- .../references/verticals/token/cancelOffer.md | 3 +- .../references/verticals/token/createOffer.md | 3 +- .../references/verticals/token/destroy.md | 3 +- .../references/verticals/token/grantHolder.md | 3 +- .../references/verticals/token/index.md | 3 +- .../references/verticals/token/issue.md | 3 +- .../references/verticals/token/list.md | 3 +- .../references/verticals/token/listOffers.md | 3 +- .../references/verticals/token/lock.md | 3 +- .../references/verticals/token/retrieve.md | 3 +- .../verticals/token/revokeHolder.md | 3 +- .../references/verticals/token/transfer.md | 3 +- .../references/verticals/token/unauthorize.md | 3 +- .../references/verticals/token/unlock.md | 3 +- .../references/verticals/xrp/index.md | 3 +- .../references/verticals/xrp/transfer.md | 3 +- .../tutorials/connect-custodians.md | 3 +- .../tutorials/create-permissioned-domain.md | 3 +- .../tutorials/cross-custodian-workflows.md | 3 +- docs/simpleXRPL/tutorials/discover-acounts.md | 3 +- docs/simpleXRPL/tutorials/external-signer.md | 3 +- .../tutorials/implement-aws-kms-signer.md | 3 +- .../tutorials/implement-pkcs11-signer.md | 3 +- .../tutorials/inititialize-clients.md | 3 +- .../tutorials/issue-and-distribute-iou.md | 3 +- docs/simpleXRPL/tutorials/issue-rwa-as-mpt.md | 3 +- docs/simpleXRPL/tutorials/place-dex-order.md | 3 +- .../tutorials/read-routing-reports.md | 3 +- 68 files changed, 150 insertions(+), 81 deletions(-) diff --git a/docs/simpleXRPL/get-started.md b/docs/simpleXRPL/get-started.md index e5007597..825ef316 100644 --- a/docs/simpleXRPL/get-started.md +++ b/docs/simpleXRPL/get-started.md @@ -2,7 +2,8 @@ seo: description: Install simpleXRPL, initialize the client, connect a custodian, and run your first XRP Ledger operation. labels: - - SDKs + - simpleXRPL + - SDK --- # Get Started @@ -96,7 +97,7 @@ const client = await SimpleXRPL.init({ Read credentials from your environment or secrets manager — never hard-code keys. Once bound, every vertical verb works the same regardless of which connector owns the account: the SDK routes each write to the custodian that holds it. {% admonition type="info" name="Note" %} -Whether an operation runs through a custodian's **native** path or the **raw-signing fallback** is decided per operation, and fallback is off unless you opt in. See [Operation Execution](index.md#operation-execution) and the [Connector Routing](references/connector-routing.md) table. +Whether an operation runs through a custodian's **native** path or the **raw-signing fallback** is decided per operation; the fallback is off by default and enabled per connector via `allowRawSigning`. See [Operation Execution](index.md#operation-execution) and the [Connector Routing](references/connector-routing.md) table. {% /admonition %} See [Connect to custodians](tutorials/connect-custodians.md) for the full per-connector setup. diff --git a/docs/simpleXRPL/index.md b/docs/simpleXRPL/index.md index 8350fb10..f4b98ed2 100644 --- a/docs/simpleXRPL/index.md +++ b/docs/simpleXRPL/index.md @@ -2,17 +2,19 @@ seo: description: simpleXRPL is an opinionated TypeScript SDK that lets institutional developers express XRP Ledger operations as business intent and route them through the custodians they already use. labels: - - SDKs + - simpleXRPL + - SDK --- # simpleXRPL +[Source](https://github.com/ripple/simpleXRPL) -The `simpleXRPL` is an opinionated TypeScript SDK for the XRP Ledger, built for institutional developers who interact with the ledger through a custodian. It raises the level of your code from XRPL protocol mechanics to business operations that the SDK routes through institutional custodians. Concretely, this means: +The `simpleXRPL` is an opinionated TypeScript SDK for the XRP Ledger, built for institutional developers who interact with the ledger through a custodian. It raises the level of your code from XRPL protocol mechanics to business operations that the SDK routes through your institutional custodians. Concretely, this means: - `simpleXRPL` defines the shape of business operations, handling the underlying XRPL transactions and custodian API calls. - Your code doesn't change even if you switch custodians or operate across several at once. -{% admonition type="info" name="Note" %} +{% admonition type="warning" name="Caution" %} `simpleXRPL` is pre-1.0. The public API may change between releases and no sandbox exists yet to test native custodian operations. {% /admonition %} @@ -21,25 +23,25 @@ The `simpleXRPL` is an opinionated TypeScript SDK for the XRP Ledger, built for `simpleXRPL` is built around four concepts: -- **Client**: Establishes the network connection and the connector configuration. Both are immutable for the client's lifetime; to change either, you create a new client. -- **Connector**: The execution model that determines *how* operations run and *who* holds account keys. Each connector exposes a uniform interface to the rest of the SDK, so the same code runs across all of them. -- **Accounts**: A separate abstraction, bound to a custodian or a local seed and given a logical name. -- **Verticals**: Domain-specific classes that group related business operations. +- **Clients**: Establishes the network connection and the connector configuration. Both are immutable for the client's lifetime; to change either, you create a new client. +- **Connectors**: The execution model that determines *how* operations run and *who* holds account keys. Each connector exposes a uniform interface to the rest of the SDK, so the same code runs across all of them. +- **Accounts**: An XRPL [account](https://xrpl.org/docs/concepts/accounts) paired with the connector that signs for it. +- **Verticals**: Domain-specific classes and methods that group related business operations. ## Operation Execution For every operation, on every connector, `simpleXRPL` has a statically defined routing decision that it reports at initialization: -- **Native**: Maps onto an endpoint the custodian exposes and natively handles. -- **Raw signing fallback (opt-in)**: The custodian has no native endpoint yet, so the SDK constructs and submits the necessary transactions to the XRPL. Raw-signing is only used if you explicitly enable it for a specific operation. -- **Unavailable**: The custodian doesn't expost a native endpoint and raw signing isn't permitted for this operation. +- **Native**: Maps onto an endpoint a custodian exposes and natively handles. +- **Raw Signing**: For an operation the custodian exposes no native support for, the SDK builds the underlying XRPL transactions, has the custodian sign the raw bytes, and submits them to the XRPL directly. Raw signing is off by default and enabled per connector; once on, it covers every operation that connector can't handle natively. +- **Unavailable**: The custodian doesn't expose a native endpoint and raw signing isn't enabled on the connector, so this operation is rejected. {% admonition type="info" name="Note" %} -For a complete list of supported operations by connector, see the [Connector Routing Table](./references/connector-routing.md) +For a complete list of supported operations by connector, see [Connector Routing](./references/connector-routing.md) {% /admonition %} -## Next steps +## See Also -Ready to build? See [Get Started](./get-started.md) to install `simpleXRPL`, connect a custodian, and run your first operation. +- [Get Started](./get-started.md) diff --git a/docs/simpleXRPL/references/connector-routing.md b/docs/simpleXRPL/references/connector-routing.md index f2e93b05..3c93fb8f 100644 --- a/docs/simpleXRPL/references/connector-routing.md +++ b/docs/simpleXRPL/references/connector-routing.md @@ -2,7 +2,8 @@ seo: description: The connector routing table — per XRPL transactor and per custodian, whether an operation routes native, requires the raw-signing fallback, or is unavailable. labels: - - SDKs + - simpleXRPL + - SDK --- # Connector Routing diff --git a/docs/simpleXRPL/references/index.md b/docs/simpleXRPL/references/index.md index 1def89de..4828a49a 100644 --- a/docs/simpleXRPL/references/index.md +++ b/docs/simpleXRPL/references/index.md @@ -2,7 +2,8 @@ seo: description: Reference index for the simpleXRPL SDK — its verticals, connectors, the amount and asset model, submission results, and the error hierarchy. labels: - - SDKs + - simpleXRPL + - SDK --- # Reference diff --git a/docs/simpleXRPL/references/verticals/account/activate.md b/docs/simpleXRPL/references/verticals/account/activate.md index 883976f4..afd82adb 100644 --- a/docs/simpleXRPL/references/verticals/account/activate.md +++ b/docs/simpleXRPL/references/verticals/account/activate.md @@ -2,7 +2,8 @@ seo: description: Account.activate activates a created account by sending it XRP from the operator account, then enabling rippling. labels: - - SDKs + - simpleXRPL + - SDK --- # account.activate() diff --git a/docs/simpleXRPL/references/verticals/account/create.md b/docs/simpleXRPL/references/verticals/account/create.md index 02b02b93..a4f11f4f 100644 --- a/docs/simpleXRPL/references/verticals/account/create.md +++ b/docs/simpleXRPL/references/verticals/account/create.md @@ -2,7 +2,8 @@ seo: description: Account.create generates a new XRPL keypair locally and registers it. No transaction is submitted. labels: - - SDKs + - simpleXRPL + - SDK --- # account.create() diff --git a/docs/simpleXRPL/references/verticals/account/depositPreauth.md b/docs/simpleXRPL/references/verticals/account/depositPreauth.md index 3f17ef0d..d81430e0 100644 --- a/docs/simpleXRPL/references/verticals/account/depositPreauth.md +++ b/docs/simpleXRPL/references/verticals/account/depositPreauth.md @@ -2,7 +2,8 @@ seo: description: Account.depositPreauth grants or revokes deposit preauthorization for another account via a DepositPreauth transaction. labels: - - SDKs + - simpleXRPL + - SDK --- # account.depositPreauth() diff --git a/docs/simpleXRPL/references/verticals/account/fund.md b/docs/simpleXRPL/references/verticals/account/fund.md index b6844141..d569ac56 100644 --- a/docs/simpleXRPL/references/verticals/account/fund.md +++ b/docs/simpleXRPL/references/verticals/account/fund.md @@ -2,7 +2,8 @@ seo: description: Account.fund funds a created account from a testnet/devnet faucet, then enables rippling via an AccountSet transaction. labels: - - SDKs + - simpleXRPL + - SDK --- # account.fund() diff --git a/docs/simpleXRPL/references/verticals/account/index.md b/docs/simpleXRPL/references/verticals/account/index.md index 11bc90ef..5f03db6b 100644 --- a/docs/simpleXRPL/references/verticals/account/index.md +++ b/docs/simpleXRPL/references/verticals/account/index.md @@ -2,7 +2,8 @@ seo: description: The Account vertical in simpleXRPL manages account creation, funding, settings, regular keys, and deposit preauthorization. labels: - - SDKs + - simpleXRPL + - SDK --- # Account diff --git a/docs/simpleXRPL/references/verticals/account/listOffers.md b/docs/simpleXRPL/references/verticals/account/listOffers.md index 3977449a..91884229 100644 --- a/docs/simpleXRPL/references/verticals/account/listOffers.md +++ b/docs/simpleXRPL/references/verticals/account/listOffers.md @@ -2,7 +2,8 @@ seo: description: Account.listOffers lists the open DEX offers placed by an account. Read-only. labels: - - SDKs + - simpleXRPL + - SDK --- # account.listOffers() diff --git a/docs/simpleXRPL/references/verticals/account/retrieve.md b/docs/simpleXRPL/references/verticals/account/retrieve.md index 37f8460e..2155f438 100644 --- a/docs/simpleXRPL/references/verticals/account/retrieve.md +++ b/docs/simpleXRPL/references/verticals/account/retrieve.md @@ -2,7 +2,8 @@ seo: description: Account.retrieve reads an account's on-chain state — balance, sequence, owner count, and flags. Read-only. labels: - - SDKs + - simpleXRPL + - SDK --- # account.retrieve() diff --git a/docs/simpleXRPL/references/verticals/account/set.md b/docs/simpleXRPL/references/verticals/account/set.md index 94d3cdbc..6931cc10 100644 --- a/docs/simpleXRPL/references/verticals/account/set.md +++ b/docs/simpleXRPL/references/verticals/account/set.md @@ -2,7 +2,8 @@ seo: description: Account.set updates account settings and flags via an AccountSet transaction. labels: - - SDKs + - simpleXRPL + - SDK --- # account.set() diff --git a/docs/simpleXRPL/references/verticals/account/setRegularKey.md b/docs/simpleXRPL/references/verticals/account/setRegularKey.md index bd6540a6..53ce45a9 100644 --- a/docs/simpleXRPL/references/verticals/account/setRegularKey.md +++ b/docs/simpleXRPL/references/verticals/account/setRegularKey.md @@ -2,7 +2,8 @@ seo: description: Account.setRegularKey sets or removes the account's regular key via a SetRegularKey transaction. labels: - - SDKs + - simpleXRPL + - SDK --- # account.setRegularKey() diff --git a/docs/simpleXRPL/references/verticals/credential/accept.md b/docs/simpleXRPL/references/verticals/credential/accept.md index 1f048639..7ce1bebe 100644 --- a/docs/simpleXRPL/references/verticals/credential/accept.md +++ b/docs/simpleXRPL/references/verticals/credential/accept.md @@ -2,7 +2,8 @@ seo: description: Credential.accept accepts a credential issued to the calling account via a CredentialAccept transaction. labels: - - SDKs + - simpleXRPL + - SDK --- # credential.accept() diff --git a/docs/simpleXRPL/references/verticals/credential/delete.md b/docs/simpleXRPL/references/verticals/credential/delete.md index 792d5d9c..e349d903 100644 --- a/docs/simpleXRPL/references/verticals/credential/delete.md +++ b/docs/simpleXRPL/references/verticals/credential/delete.md @@ -2,7 +2,8 @@ seo: description: Credential.delete deletes an on-ledger credential, as either its issuer or its holder, via a CredentialDelete transaction. labels: - - SDKs + - simpleXRPL + - SDK --- # credential.delete() diff --git a/docs/simpleXRPL/references/verticals/credential/index.md b/docs/simpleXRPL/references/verticals/credential/index.md index 57e53297..3def6c1c 100644 --- a/docs/simpleXRPL/references/verticals/credential/index.md +++ b/docs/simpleXRPL/references/verticals/credential/index.md @@ -2,7 +2,8 @@ seo: description: The Credential vertical in simpleXRPL issues, accepts, and deletes on-ledger credentials. labels: - - SDKs + - simpleXRPL + - SDK --- # Credential diff --git a/docs/simpleXRPL/references/verticals/credential/issue.md b/docs/simpleXRPL/references/verticals/credential/issue.md index 832f1e69..4b4f5b4f 100644 --- a/docs/simpleXRPL/references/verticals/credential/issue.md +++ b/docs/simpleXRPL/references/verticals/credential/issue.md @@ -2,7 +2,8 @@ seo: description: Credential.issue issues an on-ledger credential to a destination account via a CredentialCreate transaction. labels: - - SDKs + - simpleXRPL + - SDK --- # credential.issue() diff --git a/docs/simpleXRPL/references/verticals/credential/list.md b/docs/simpleXRPL/references/verticals/credential/list.md index 258e88cd..cd3c4bc2 100644 --- a/docs/simpleXRPL/references/verticals/credential/list.md +++ b/docs/simpleXRPL/references/verticals/credential/list.md @@ -2,7 +2,8 @@ seo: description: Credential.list lists the credentials an account holds or issued. Read-only. labels: - - SDKs + - simpleXRPL + - SDK --- # credential.list() diff --git a/docs/simpleXRPL/references/verticals/credential/retrieve.md b/docs/simpleXRPL/references/verticals/credential/retrieve.md index 08161097..5d6edd30 100644 --- a/docs/simpleXRPL/references/verticals/credential/retrieve.md +++ b/docs/simpleXRPL/references/verticals/credential/retrieve.md @@ -2,7 +2,8 @@ seo: description: Credential.retrieve reads a single credential by type and issuer. Read-only. labels: - - SDKs + - simpleXRPL + - SDK --- # credential.retrieve() diff --git a/docs/simpleXRPL/references/verticals/domain/create.md b/docs/simpleXRPL/references/verticals/domain/create.md index f402f705..a75bb0ea 100644 --- a/docs/simpleXRPL/references/verticals/domain/create.md +++ b/docs/simpleXRPL/references/verticals/domain/create.md @@ -2,7 +2,8 @@ seo: description: Domain.create creates a new permissioned domain via a PermissionedDomainSet transaction. labels: - - SDKs + - simpleXRPL + - SDK --- # domain.create() diff --git a/docs/simpleXRPL/references/verticals/domain/delete.md b/docs/simpleXRPL/references/verticals/domain/delete.md index 134842c7..117f7ac6 100644 --- a/docs/simpleXRPL/references/verticals/domain/delete.md +++ b/docs/simpleXRPL/references/verticals/domain/delete.md @@ -2,7 +2,8 @@ seo: description: Domain.delete deletes a permissioned domain via a PermissionedDomainDelete transaction. labels: - - SDKs + - simpleXRPL + - SDK --- # domain.delete() diff --git a/docs/simpleXRPL/references/verticals/domain/index.md b/docs/simpleXRPL/references/verticals/domain/index.md index a288fc3a..676c2a09 100644 --- a/docs/simpleXRPL/references/verticals/domain/index.md +++ b/docs/simpleXRPL/references/verticals/domain/index.md @@ -2,7 +2,8 @@ seo: description: The Domain vertical in simpleXRPL creates, updates, and deletes permissioned domains. labels: - - SDKs + - simpleXRPL + - SDK --- # Domain diff --git a/docs/simpleXRPL/references/verticals/domain/list.md b/docs/simpleXRPL/references/verticals/domain/list.md index e4cfa2bc..b7489461 100644 --- a/docs/simpleXRPL/references/verticals/domain/list.md +++ b/docs/simpleXRPL/references/verticals/domain/list.md @@ -2,7 +2,8 @@ seo: description: Domain.list lists every permissioned domain owned by an account. Read-only. labels: - - SDKs + - simpleXRPL + - SDK --- # domain.list() diff --git a/docs/simpleXRPL/references/verticals/domain/retrieve.md b/docs/simpleXRPL/references/verticals/domain/retrieve.md index de2783a2..7477ee3a 100644 --- a/docs/simpleXRPL/references/verticals/domain/retrieve.md +++ b/docs/simpleXRPL/references/verticals/domain/retrieve.md @@ -2,7 +2,8 @@ seo: description: Domain.retrieve reads a permissioned domain by id. Read-only. labels: - - SDKs + - simpleXRPL + - SDK --- # domain.retrieve() diff --git a/docs/simpleXRPL/references/verticals/domain/setCredentials.md b/docs/simpleXRPL/references/verticals/domain/setCredentials.md index 5a507393..62644f15 100644 --- a/docs/simpleXRPL/references/verticals/domain/setCredentials.md +++ b/docs/simpleXRPL/references/verticals/domain/setCredentials.md @@ -2,7 +2,8 @@ seo: description: Domain.setCredentials updates the accepted credentials of an existing permissioned domain via a PermissionedDomainSet transaction. labels: - - SDKs + - simpleXRPL + - SDK --- # domain.setCredentials() diff --git a/docs/simpleXRPL/references/verticals/index.md b/docs/simpleXRPL/references/verticals/index.md index bbcc68c8..388cb868 100644 --- a/docs/simpleXRPL/references/verticals/index.md +++ b/docs/simpleXRPL/references/verticals/index.md @@ -2,7 +2,8 @@ seo: description: A vertical is a domain-specific class of business-intent operations in simpleXRPL — one per area of XRPL functionality, reached off the client. labels: - - SDKs + - simpleXRPL + - SDK --- # Verticals diff --git a/docs/simpleXRPL/references/verticals/iou/authorize.md b/docs/simpleXRPL/references/verticals/iou/authorize.md index f3e88bac..bffaac79 100644 --- a/docs/simpleXRPL/references/verticals/iou/authorize.md +++ b/docs/simpleXRPL/references/verticals/iou/authorize.md @@ -2,7 +2,8 @@ seo: description: IOU.authorize authorizes a holder to hold an IOU via a TrustSet transaction with the authorize flag. labels: - - SDKs + - simpleXRPL + - SDK --- # iou.authorize() diff --git a/docs/simpleXRPL/references/verticals/iou/buyOffer.md b/docs/simpleXRPL/references/verticals/iou/buyOffer.md index 6e578c31..95944d22 100644 --- a/docs/simpleXRPL/references/verticals/iou/buyOffer.md +++ b/docs/simpleXRPL/references/verticals/iou/buyOffer.md @@ -2,7 +2,8 @@ seo: description: IOU.buyOffer places a DEX order to acquire more of this IOU via an OfferCreate transaction. labels: - - SDKs + - simpleXRPL + - SDK --- # iou.buyOffer() diff --git a/docs/simpleXRPL/references/verticals/iou/cancelOffer.md b/docs/simpleXRPL/references/verticals/iou/cancelOffer.md index f859a578..f95dd3cb 100644 --- a/docs/simpleXRPL/references/verticals/iou/cancelOffer.md +++ b/docs/simpleXRPL/references/verticals/iou/cancelOffer.md @@ -2,7 +2,8 @@ seo: description: IOU.cancelOffer cancels a standing DEX offer placed by the issuer via an OfferCancel transaction. labels: - - SDKs + - simpleXRPL + - SDK --- # iou.cancelOffer() diff --git a/docs/simpleXRPL/references/verticals/iou/clawback.md b/docs/simpleXRPL/references/verticals/iou/clawback.md index 3b3234f1..63e43945 100644 --- a/docs/simpleXRPL/references/verticals/iou/clawback.md +++ b/docs/simpleXRPL/references/verticals/iou/clawback.md @@ -2,7 +2,8 @@ seo: description: IOU.clawback reclaims a holder's balance back to the issuer via a Clawback transaction. labels: - - SDKs + - simpleXRPL + - SDK --- # iou.clawback() diff --git a/docs/simpleXRPL/references/verticals/iou/index.md b/docs/simpleXRPL/references/verticals/iou/index.md index 0944469e..f770e1ae 100644 --- a/docs/simpleXRPL/references/verticals/iou/index.md +++ b/docs/simpleXRPL/references/verticals/iou/index.md @@ -2,7 +2,8 @@ seo: description: The IOU vertical in simpleXRPL issues and manages trust-line-based issued currencies. labels: - - SDKs + - simpleXRPL + - SDK --- # IOU diff --git a/docs/simpleXRPL/references/verticals/iou/issue.md b/docs/simpleXRPL/references/verticals/iou/issue.md index 09423776..435309d3 100644 --- a/docs/simpleXRPL/references/verticals/iou/issue.md +++ b/docs/simpleXRPL/references/verticals/iou/issue.md @@ -2,7 +2,8 @@ seo: description: IOU.issue bootstraps a new trust-line-based IOU between two environment-sourced accounts via AccountSet and TrustSet transactions. labels: - - SDKs + - simpleXRPL + - SDK --- # iou.issue() diff --git a/docs/simpleXRPL/references/verticals/iou/list.md b/docs/simpleXRPL/references/verticals/iou/list.md index 75c32d76..c97272dd 100644 --- a/docs/simpleXRPL/references/verticals/iou/list.md +++ b/docs/simpleXRPL/references/verticals/iou/list.md @@ -2,7 +2,8 @@ seo: description: IOU.list lists every IOU trust line for an account. Read-only. labels: - - SDKs + - simpleXRPL + - SDK --- # iou.list() diff --git a/docs/simpleXRPL/references/verticals/iou/listOffers.md b/docs/simpleXRPL/references/verticals/iou/listOffers.md index b72f7bb5..217994f1 100644 --- a/docs/simpleXRPL/references/verticals/iou/listOffers.md +++ b/docs/simpleXRPL/references/verticals/iou/listOffers.md @@ -2,7 +2,8 @@ seo: description: IOU.listOffers lists all open offers in the market for an IOU (both sides of the order book). Read-only. labels: - - SDKs + - simpleXRPL + - SDK --- # iou.listOffers() diff --git a/docs/simpleXRPL/references/verticals/iou/lock.md b/docs/simpleXRPL/references/verticals/iou/lock.md index 27291952..3617cc45 100644 --- a/docs/simpleXRPL/references/verticals/iou/lock.md +++ b/docs/simpleXRPL/references/verticals/iou/lock.md @@ -2,7 +2,8 @@ seo: description: IOU.lock freezes a holder's trust line via individual and deep freeze TrustSet transactions. labels: - - SDKs + - simpleXRPL + - SDK --- # iou.lock() diff --git a/docs/simpleXRPL/references/verticals/iou/retrieve.md b/docs/simpleXRPL/references/verticals/iou/retrieve.md index 2c3677a4..a0805f0f 100644 --- a/docs/simpleXRPL/references/verticals/iou/retrieve.md +++ b/docs/simpleXRPL/references/verticals/iou/retrieve.md @@ -2,7 +2,8 @@ seo: description: IOU.retrieve reads a single IOU trust line between an account and an issuer. Read-only. labels: - - SDKs + - simpleXRPL + - SDK --- # iou.retrieve() diff --git a/docs/simpleXRPL/references/verticals/iou/sellOffer.md b/docs/simpleXRPL/references/verticals/iou/sellOffer.md index ee979e11..ae6da44e 100644 --- a/docs/simpleXRPL/references/verticals/iou/sellOffer.md +++ b/docs/simpleXRPL/references/verticals/iou/sellOffer.md @@ -2,7 +2,8 @@ seo: description: IOU.sellOffer places a DEX order to sell this IOU via an OfferCreate transaction. labels: - - SDKs + - simpleXRPL + - SDK --- # iou.sellOffer() diff --git a/docs/simpleXRPL/references/verticals/iou/transfer.md b/docs/simpleXRPL/references/verticals/iou/transfer.md index ebb55783..ad12602a 100644 --- a/docs/simpleXRPL/references/verticals/iou/transfer.md +++ b/docs/simpleXRPL/references/verticals/iou/transfer.md @@ -2,7 +2,8 @@ seo: description: IOU.transfer sends issued-currency value to a destination account via a Payment transaction. labels: - - SDKs + - simpleXRPL + - SDK --- # iou.transfer() diff --git a/docs/simpleXRPL/references/verticals/iou/unlock.md b/docs/simpleXRPL/references/verticals/iou/unlock.md index f80faab7..9b7ec90f 100644 --- a/docs/simpleXRPL/references/verticals/iou/unlock.md +++ b/docs/simpleXRPL/references/verticals/iou/unlock.md @@ -2,7 +2,8 @@ seo: description: IOU.unlock restores a frozen holder's trust line by clearing deep and individual freeze via TrustSet transactions. labels: - - SDKs + - simpleXRPL + - SDK --- # iou.unlock() diff --git a/docs/simpleXRPL/references/verticals/token/authorize.md b/docs/simpleXRPL/references/verticals/token/authorize.md index 87acb886..276c9f54 100644 --- a/docs/simpleXRPL/references/verticals/token/authorize.md +++ b/docs/simpleXRPL/references/verticals/token/authorize.md @@ -2,7 +2,8 @@ seo: description: Token.authorize opts the calling account in to holding an MPT issuance via an MPTokenAuthorize transaction. labels: - - SDKs + - simpleXRPL + - SDK --- # token.authorize() diff --git a/docs/simpleXRPL/references/verticals/token/cancelOffer.md b/docs/simpleXRPL/references/verticals/token/cancelOffer.md index cb587ca9..29e6bbc1 100644 --- a/docs/simpleXRPL/references/verticals/token/cancelOffer.md +++ b/docs/simpleXRPL/references/verticals/token/cancelOffer.md @@ -2,7 +2,8 @@ seo: description: Token.cancelOffer cancels a standing DEX offer via an OfferCancel transaction. labels: - - SDKs + - simpleXRPL + - SDK --- # token.cancelOffer() diff --git a/docs/simpleXRPL/references/verticals/token/createOffer.md b/docs/simpleXRPL/references/verticals/token/createOffer.md index 320c9aa6..365b8ec4 100644 --- a/docs/simpleXRPL/references/verticals/token/createOffer.md +++ b/docs/simpleXRPL/references/verticals/token/createOffer.md @@ -2,7 +2,8 @@ seo: description: Token.createOffer places an offer on the XRP Ledger decentralized exchange via an OfferCreate transaction. labels: - - SDKs + - simpleXRPL + - SDK --- # token.createOffer() diff --git a/docs/simpleXRPL/references/verticals/token/destroy.md b/docs/simpleXRPL/references/verticals/token/destroy.md index d2cbaac3..2ff6e441 100644 --- a/docs/simpleXRPL/references/verticals/token/destroy.md +++ b/docs/simpleXRPL/references/verticals/token/destroy.md @@ -2,7 +2,8 @@ seo: description: Token.destroy destroys an MPT issuance via an MPTokenIssuanceDestroy transaction. labels: - - SDKs + - simpleXRPL + - SDK --- # token.destroy() diff --git a/docs/simpleXRPL/references/verticals/token/grantHolder.md b/docs/simpleXRPL/references/verticals/token/grantHolder.md index 95fc1f00..bbd016dd 100644 --- a/docs/simpleXRPL/references/verticals/token/grantHolder.md +++ b/docs/simpleXRPL/references/verticals/token/grantHolder.md @@ -2,7 +2,8 @@ seo: description: Token.grantHolder lets an issuer authorize a specific holder to hold an MPT via an MPTokenAuthorize transaction. labels: - - SDKs + - simpleXRPL + - SDK --- # token.grantHolder() diff --git a/docs/simpleXRPL/references/verticals/token/index.md b/docs/simpleXRPL/references/verticals/token/index.md index b938917d..8864892c 100644 --- a/docs/simpleXRPL/references/verticals/token/index.md +++ b/docs/simpleXRPL/references/verticals/token/index.md @@ -2,7 +2,8 @@ seo: description: The Token vertical in simpleXRPL issues and manages Multi-Purpose Tokens (MPTs) and places DEX offers. labels: - - SDKs + - simpleXRPL + - SDK --- # Token diff --git a/docs/simpleXRPL/references/verticals/token/issue.md b/docs/simpleXRPL/references/verticals/token/issue.md index 4ccaac85..b1c244b9 100644 --- a/docs/simpleXRPL/references/verticals/token/issue.md +++ b/docs/simpleXRPL/references/verticals/token/issue.md @@ -2,7 +2,8 @@ seo: description: Token.issue creates a new Multi-Purpose Token (MPT) issuance via an MPTokenIssuanceCreate transaction. labels: - - SDKs + - simpleXRPL + - SDK --- # token.issue() diff --git a/docs/simpleXRPL/references/verticals/token/list.md b/docs/simpleXRPL/references/verticals/token/list.md index eaab5a73..97c93c8c 100644 --- a/docs/simpleXRPL/references/verticals/token/list.md +++ b/docs/simpleXRPL/references/verticals/token/list.md @@ -2,7 +2,8 @@ seo: description: Token.list lists the MPTs an account holds or issued. Read-only. labels: - - SDKs + - simpleXRPL + - SDK --- # token.list() diff --git a/docs/simpleXRPL/references/verticals/token/listOffers.md b/docs/simpleXRPL/references/verticals/token/listOffers.md index 639ba31e..71bbe85e 100644 --- a/docs/simpleXRPL/references/verticals/token/listOffers.md +++ b/docs/simpleXRPL/references/verticals/token/listOffers.md @@ -2,7 +2,8 @@ seo: description: Token.listOffers lists the open DEX offers placed by an account. Read-only. labels: - - SDKs + - simpleXRPL + - SDK --- # token.listOffers() diff --git a/docs/simpleXRPL/references/verticals/token/lock.md b/docs/simpleXRPL/references/verticals/token/lock.md index 8cfe5653..892b28f9 100644 --- a/docs/simpleXRPL/references/verticals/token/lock.md +++ b/docs/simpleXRPL/references/verticals/token/lock.md @@ -2,7 +2,8 @@ seo: description: Token.lock locks an MPT issuance or a specific holder's balance via an MPTokenIssuanceSet transaction. labels: - - SDKs + - simpleXRPL + - SDK --- # token.lock() diff --git a/docs/simpleXRPL/references/verticals/token/retrieve.md b/docs/simpleXRPL/references/verticals/token/retrieve.md index 6af0d917..d6200efd 100644 --- a/docs/simpleXRPL/references/verticals/token/retrieve.md +++ b/docs/simpleXRPL/references/verticals/token/retrieve.md @@ -2,7 +2,8 @@ seo: description: Token.retrieve reads a single MPT issuance by id, with flags and XLS-89 metadata decoded. Read-only. labels: - - SDKs + - simpleXRPL + - SDK --- # token.retrieve() diff --git a/docs/simpleXRPL/references/verticals/token/revokeHolder.md b/docs/simpleXRPL/references/verticals/token/revokeHolder.md index f8648dd7..779cfe0c 100644 --- a/docs/simpleXRPL/references/verticals/token/revokeHolder.md +++ b/docs/simpleXRPL/references/verticals/token/revokeHolder.md @@ -2,7 +2,8 @@ seo: description: Token.revokeHolder lets an issuer revoke a specific holder's permission to hold an MPT via an MPTokenAuthorize transaction. labels: - - SDKs + - simpleXRPL + - SDK --- # token.revokeHolder() diff --git a/docs/simpleXRPL/references/verticals/token/transfer.md b/docs/simpleXRPL/references/verticals/token/transfer.md index d996fc7d..1715930f 100644 --- a/docs/simpleXRPL/references/verticals/token/transfer.md +++ b/docs/simpleXRPL/references/verticals/token/transfer.md @@ -2,7 +2,8 @@ seo: description: Token.transfer sends MPT units to another account via a Payment transaction. labels: - - SDKs + - simpleXRPL + - SDK --- # token.transfer() diff --git a/docs/simpleXRPL/references/verticals/token/unauthorize.md b/docs/simpleXRPL/references/verticals/token/unauthorize.md index f541f092..1491fac4 100644 --- a/docs/simpleXRPL/references/verticals/token/unauthorize.md +++ b/docs/simpleXRPL/references/verticals/token/unauthorize.md @@ -2,7 +2,8 @@ seo: description: Token.unauthorize opts the calling account out of holding an MPT issuance via an MPTokenAuthorize transaction. labels: - - SDKs + - simpleXRPL + - SDK --- # token.unauthorize() diff --git a/docs/simpleXRPL/references/verticals/token/unlock.md b/docs/simpleXRPL/references/verticals/token/unlock.md index 2efafa0b..b6b4daa7 100644 --- a/docs/simpleXRPL/references/verticals/token/unlock.md +++ b/docs/simpleXRPL/references/verticals/token/unlock.md @@ -2,7 +2,8 @@ seo: description: Token.unlock unlocks an MPT issuance or a specific holder's balance via an MPTokenIssuanceSet transaction. labels: - - SDKs + - simpleXRPL + - SDK --- # token.unlock() diff --git a/docs/simpleXRPL/references/verticals/xrp/index.md b/docs/simpleXRPL/references/verticals/xrp/index.md index 28b3fa9a..5ab7d437 100644 --- a/docs/simpleXRPL/references/verticals/xrp/index.md +++ b/docs/simpleXRPL/references/verticals/xrp/index.md @@ -2,7 +2,8 @@ seo: description: The XRP vertical in simpleXRPL handles native XRP value transfers. labels: - - SDKs + - simpleXRPL + - SDK --- # XRP diff --git a/docs/simpleXRPL/references/verticals/xrp/transfer.md b/docs/simpleXRPL/references/verticals/xrp/transfer.md index d90490a8..268d3a4c 100644 --- a/docs/simpleXRPL/references/verticals/xrp/transfer.md +++ b/docs/simpleXRPL/references/verticals/xrp/transfer.md @@ -2,7 +2,8 @@ seo: description: XRP.transfer sends native XRP from one account to another via a Payment transaction. labels: - - SDKs + - simpleXRPL + - SDK --- # xrp.transfer() diff --git a/docs/simpleXRPL/tutorials/connect-custodians.md b/docs/simpleXRPL/tutorials/connect-custodians.md index edfeb634..a30bda8c 100644 --- a/docs/simpleXRPL/tutorials/connect-custodians.md +++ b/docs/simpleXRPL/tutorials/connect-custodians.md @@ -2,7 +2,8 @@ seo: description: Construct and authenticate each simpleXRPL connector, then bind them so every vertical verb routes to the custodian that owns the account. labels: - - SDKs + - simpleXRPL + - SDK --- # Connect To Custodians diff --git a/docs/simpleXRPL/tutorials/create-permissioned-domain.md b/docs/simpleXRPL/tutorials/create-permissioned-domain.md index a23a99fb..8a1a9a11 100644 --- a/docs/simpleXRPL/tutorials/create-permissioned-domain.md +++ b/docs/simpleXRPL/tutorials/create-permissioned-domain.md @@ -2,7 +2,8 @@ seo: description: Set up a permissioned domain that restricts participation to credential holders, then scope DEX offers to it. labels: - - SDKs + - simpleXRPL + - SDK --- # Create A Permissioned Domain diff --git a/docs/simpleXRPL/tutorials/cross-custodian-workflows.md b/docs/simpleXRPL/tutorials/cross-custodian-workflows.md index 93056482..99a46815 100644 --- a/docs/simpleXRPL/tutorials/cross-custodian-workflows.md +++ b/docs/simpleXRPL/tutorials/cross-custodian-workflows.md @@ -2,7 +2,8 @@ seo: description: Drive accounts held by different custodians from a single client, using per-call routing or an ordered multi-step sequence. labels: - - SDKs + - simpleXRPL + - SDK --- # Run A Workflow Across Custodians diff --git a/docs/simpleXRPL/tutorials/discover-acounts.md b/docs/simpleXRPL/tutorials/discover-acounts.md index 12b9e54e..59eb9a5d 100644 --- a/docs/simpleXRPL/tutorials/discover-acounts.md +++ b/docs/simpleXRPL/tutorials/discover-acounts.md @@ -2,7 +2,8 @@ seo: description: List and resolve the accounts each custodian discovered, and re-discover at runtime, from the single account index init builds. labels: - - SDKs + - simpleXRPL + - SDK --- # Discover Accounts diff --git a/docs/simpleXRPL/tutorials/external-signer.md b/docs/simpleXRPL/tutorials/external-signer.md index 828bc3f6..a96b8b68 100644 --- a/docs/simpleXRPL/tutorials/external-signer.md +++ b/docs/simpleXRPL/tutorials/external-signer.md @@ -2,7 +2,8 @@ seo: description: Implement the ExternalSignerPort seam end to end with a mock signer, and switch between secp256k1 and ed25519. labels: - - SDKs + - simpleXRPL + - SDK --- # Implement An External Signer diff --git a/docs/simpleXRPL/tutorials/implement-aws-kms-signer.md b/docs/simpleXRPL/tutorials/implement-aws-kms-signer.md index d13b000e..e10761b2 100644 --- a/docs/simpleXRPL/tutorials/implement-aws-kms-signer.md +++ b/docs/simpleXRPL/tutorials/implement-aws-kms-signer.md @@ -2,7 +2,8 @@ seo: description: Sign transactions with a secp256k1 key held in AWS KMS using the simplexrpl/aws-kms adapter; the private key never leaves KMS. labels: - - SDKs + - simpleXRPL + - SDK --- # Sign With AWS KMS diff --git a/docs/simpleXRPL/tutorials/implement-pkcs11-signer.md b/docs/simpleXRPL/tutorials/implement-pkcs11-signer.md index 3ec322f2..95447318 100644 --- a/docs/simpleXRPL/tutorials/implement-pkcs11-signer.md +++ b/docs/simpleXRPL/tutorials/implement-pkcs11-signer.md @@ -2,7 +2,8 @@ seo: description: Implement the ExternalSignerPort seam against a PKCS#11 HSM — you provide the public key and digest signing; the SDK owns the XRPL crypto. labels: - - SDKs + - simpleXRPL + - SDK --- # Implement A PKCS#11 HSM Signer diff --git a/docs/simpleXRPL/tutorials/inititialize-clients.md b/docs/simpleXRPL/tutorials/inititialize-clients.md index fb72e52a..945dd4c6 100644 --- a/docs/simpleXRPL/tutorials/inititialize-clients.md +++ b/docs/simpleXRPL/tutorials/inititialize-clients.md @@ -2,7 +2,8 @@ seo: description: Initialize the simpleXRPL client with SimpleXRPL.init — bind connectors to a network and build the account index. labels: - - SDKs + - simpleXRPL + - SDK --- # Initialize The Client diff --git a/docs/simpleXRPL/tutorials/issue-and-distribute-iou.md b/docs/simpleXRPL/tutorials/issue-and-distribute-iou.md index 531c0504..77bfdfa5 100644 --- a/docs/simpleXRPL/tutorials/issue-and-distribute-iou.md +++ b/docs/simpleXRPL/tutorials/issue-and-distribute-iou.md @@ -2,7 +2,8 @@ seo: description: "Issue a trust-line currency (IOU) and distribute it: bootstrap the issuer and hot wallet, then transfer the currency out." labels: - - SDKs + - simpleXRPL + - SDK --- # Issue And Distribute An IOU diff --git a/docs/simpleXRPL/tutorials/issue-rwa-as-mpt.md b/docs/simpleXRPL/tutorials/issue-rwa-as-mpt.md index 69817465..61179377 100644 --- a/docs/simpleXRPL/tutorials/issue-rwa-as-mpt.md +++ b/docs/simpleXRPL/tutorials/issue-rwa-as-mpt.md @@ -2,7 +2,8 @@ seo: description: Issue a Real-World Asset as a Multi-Purpose Token (MPT) through Ripple Custody, with XLS-89 metadata validated before submission. labels: - - SDKs + - simpleXRPL + - SDK --- # Issue An RWA As An MPT diff --git a/docs/simpleXRPL/tutorials/place-dex-order.md b/docs/simpleXRPL/tutorials/place-dex-order.md index 5e6919ea..50d24f86 100644 --- a/docs/simpleXRPL/tutorials/place-dex-order.md +++ b/docs/simpleXRPL/tutorials/place-dex-order.md @@ -2,7 +2,8 @@ seo: description: Place buy and sell orders on the XRP Ledger DEX with the iou and token verticals, using familiar order types. labels: - - SDKs + - simpleXRPL + - SDK --- # Place A DEX Order diff --git a/docs/simpleXRPL/tutorials/read-routing-reports.md b/docs/simpleXRPL/tutorials/read-routing-reports.md index 9009b77f..64e3ee9d 100644 --- a/docs/simpleXRPL/tutorials/read-routing-reports.md +++ b/docs/simpleXRPL/tutorials/read-routing-reports.md @@ -2,7 +2,8 @@ seo: description: Ask how a transactor would route for an account — native, raw-signing fallback, local, or rejected — before you submit. labels: - - SDKs + - simpleXRPL + - SDK --- # Read Routing Reports From 35e8fc298c49d2c570ae6ae677a127dbea9c4bed Mon Sep 17 00:00:00 2001 From: Oliver Eggert Date: Thu, 23 Jul 2026 14:11:43 -0700 Subject: [PATCH 04/24] clarify raw signing --- docs/simpleXRPL/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/simpleXRPL/index.md b/docs/simpleXRPL/index.md index f4b98ed2..46643d67 100644 --- a/docs/simpleXRPL/index.md +++ b/docs/simpleXRPL/index.md @@ -34,7 +34,7 @@ The `simpleXRPL` is an opinionated TypeScript SDK for the XRP Ledger, built for For every operation, on every connector, `simpleXRPL` has a statically defined routing decision that it reports at initialization: - **Native**: Maps onto an endpoint a custodian exposes and natively handles. -- **Raw Signing**: For an operation the custodian exposes no native support for, the SDK builds the underlying XRPL transactions, has the custodian sign the raw bytes, and submits them to the XRPL directly. Raw signing is off by default and enabled per connector; once on, it covers every operation that connector can't handle natively. +- **Raw Signing**: For an operation the custodian exposes no native support for, the SDK builds the underlying XRPL transactions, the custodian signs the raw bytes, then the SDK submits them to the XRPL directly. Raw signing is off by default and enabled per connector; once on, it covers every operation that connector can't handle natively. - **Unavailable**: The custodian doesn't expose a native endpoint and raw signing isn't enabled on the connector, so this operation is rejected. {% admonition type="info" name="Note" %} From b6182896b458f2acabbdcb54eca162f122aaf2c0 Mon Sep 17 00:00:00 2001 From: Oliver Eggert Date: Thu, 23 Jul 2026 17:28:07 -0700 Subject: [PATCH 05/24] add connectors --- _code-samples/simplexrpl/README.md | 3 + _code-samples/simplexrpl/getStarted.ts | 109 ++++++++++++++ docs/simpleXRPL/get-started.md | 134 +++++++----------- docs/simpleXRPL/index.md | 2 +- .../{ => connectors}/connector-routing.md | 0 .../simpleXRPL/references/connectors/index.md | 15 ++ .../simpleXRPL/references/connectors/local.md | 68 +++++++++ .../references/connectors/palisade.md | 52 +++++++ .../references/connectors/ripple-custody.md | 70 +++++++++ docs/simpleXRPL/references/index.md | 10 +- .../references/verticals/account/set.md | 2 +- docs/simpleXRPL/references/verticals/index.md | 2 +- .../references/verticals/iou/index.md | 6 +- .../references/verticals/iou/issue.md | 4 +- .../references/verticals/iou/retrieve.md | 4 +- .../tutorials/connect-custodians.md | 94 ------------ docs/simpleXRPL/tutorials/discover-acounts.md | 66 --------- .../tutorials/inititialize-clients.md | 62 -------- .../tutorials/issue-and-distribute-iou.md | 4 +- .../tutorials/read-routing-reports.md | 80 ----------- sidebars.yaml | 14 +- 21 files changed, 390 insertions(+), 411 deletions(-) create mode 100644 _code-samples/simplexrpl/README.md create mode 100644 _code-samples/simplexrpl/getStarted.ts rename docs/simpleXRPL/references/{ => connectors}/connector-routing.md (100%) create mode 100644 docs/simpleXRPL/references/connectors/index.md create mode 100644 docs/simpleXRPL/references/connectors/local.md create mode 100644 docs/simpleXRPL/references/connectors/palisade.md create mode 100644 docs/simpleXRPL/references/connectors/ripple-custody.md delete mode 100644 docs/simpleXRPL/tutorials/connect-custodians.md delete mode 100644 docs/simpleXRPL/tutorials/discover-acounts.md delete mode 100644 docs/simpleXRPL/tutorials/inititialize-clients.md delete mode 100644 docs/simpleXRPL/tutorials/read-routing-reports.md diff --git a/_code-samples/simplexrpl/README.md b/_code-samples/simplexrpl/README.md new file mode 100644 index 00000000..74df7ac0 --- /dev/null +++ b/_code-samples/simplexrpl/README.md @@ -0,0 +1,3 @@ +# simpleXRPL Examples + +This directory contains runnable TypeScript examples that demonstrate `simpleXRPL` business operations. diff --git a/_code-samples/simplexrpl/getStarted.ts b/_code-samples/simplexrpl/getStarted.ts new file mode 100644 index 00000000..4c73d42f --- /dev/null +++ b/_code-samples/simplexrpl/getStarted.ts @@ -0,0 +1,109 @@ +/** + * simpleXRPL — Get Started walkthrough. Config is read from the environment + * (never hard-code keys); endpoints target the XRPL Testnet. + */ +import { + dispatch, + isNativePath, + LocalSigner, + PalisadeCustody, + RippleCustody, + SignerCapabilityError, + SimpleXRPL, +} from 'simplexrpl' +import type { Custodian, SubmissionPath, TransactorType } from 'simplexrpl' + +// --- Initialize the client --- +// `SimpleXRPL.init(...)` is the only entry point — it binds already-authenticated +// connectors to a network and builds the account index. A single local signer +// (seeds from `XRPL_*_SEED`) is enough to run against the Testnet today. +const client = await SimpleXRPL.init({ + // Point at a rippled endpoint. `faucetUrl` is only used on test networks + // (by `client.account.fund`). + rippledUrl: 'wss://s.altnet.rippletest.net:51233', + faucetUrl: 'https://faucet.altnet.rippletest.net/accounts', + signers: [LocalSigner.fromEnv()], + // `primarySigner` is the default backend for verbs called without an explicit + // account; it defaults to `signers[0]`, so it's optional with a single signer. +}) + +// --- Discover your accounts --- +// Connectors discover their accounts at init; the client merges them into one +// index keyed by r-address. +for (const [address, account] of client.accounts) { + console.log(address, '→', account.signer.kind) +} + +// Resolve the account a verb would act on (no argument → the primary account). +const primary = client.resolveAccount() +console.log('primary:', primary.address) + +// Read an account's on-chain state — a read, so no signer is required. +const state = await client.account.retrieve() +console.log('balance (XRP):', state.data.xrpBalance, '| sequence:', state.data.sequence) + +// --- Check how operations route --- +// Before submitting, ask how each transactor would route for an account: signed +// locally, a custodian's native operation, the raw sign-only fallback, or rejected. +const TRANSACTORS: TransactorType[] = [ + 'Payment', + 'TrustSet', + 'OfferCreate', + 'MPTokenIssuanceCreate', + 'CredentialCreate', + 'PermissionedDomainSet', +] +for (const transactor of TRANSACTORS) { + let path: SubmissionPath | 'rejected' = 'rejected' + try { + path = dispatch(primary, transactor) + } catch (error) { + // `dispatch` throws when the connector can neither natively nor raw-sign it. + if (!(error instanceof SignerCapabilityError)) throw error + } + const via = + path === 'rejected' + ? '(unsupported)' + : isNativePath(path) + ? '(custodian network)' + : '(shared ledger)' + console.log(`${transactor.padEnd(24)} → ${path} ${via}`) +} + +// --- Send a payment --- +// Verbs use the primary account by default; target another bound account with `from`. +const result = await client.xrp.transfer({ + to: 'rDestination00000000000000000000000', + amount: '10', +}) +console.log('submitted:', result.txHash) + +await client.disconnect() + +// --- Connect a custodian (production) --- +// For production, construct each custodian connector on its own and pass them to +// `SimpleXRPL.init`'s `signers` in place of (or alongside) the local signer above, +// e.g. `signers: await connectCustodians(), primarySigner: /* your custodian */`. +export async function connectCustodians(): Promise { + // Palisade — OAuth client credentials, acting on a specific vault/wallet. + const palisade = await PalisadeCustody.create({ + baseUrl: 'https://api.sandbox.palisade.co', + clientId: process.env.PALISADE_CLIENT_ID ?? '', + clientSecret: process.env.PALISADE_CLIENT_SECRET ?? '', + primary: { + vaultId: process.env.PALISADE_VAULT_ID ?? '', + walletId: process.env.PALISADE_WALLET_ID ?? '', + }, + // Enable the raw sign-only fallback for transactors Palisade has no native + // operation for. Off by default. + allowRawSigning: false, + }) + + // Ripple Custody — an intent-author key exchanged for a token; one Custody + // domain. `fromEnv` reads the `RIPPLE_CUSTODY_*` variables. + const rippleCustody = await RippleCustody.fromEnv({ + primary: process.env.RIPPLE_CUSTODY_PRIMARY ?? '', + }) + + return [palisade, rippleCustody, LocalSigner.fromEnv()] +} diff --git a/docs/simpleXRPL/get-started.md b/docs/simpleXRPL/get-started.md index 825ef316..7b818bc2 100644 --- a/docs/simpleXRPL/get-started.md +++ b/docs/simpleXRPL/get-started.md @@ -1,6 +1,6 @@ --- seo: - description: Install simpleXRPL, initialize the client, connect a custodian, and run your first XRP Ledger operation. + description: Install simpleXRPL, initialize the client, connect a custodian, discover your accounts, check routing, and send your first XRP Ledger payment. labels: - simpleXRPL - SDK @@ -8,116 +8,84 @@ labels: # Get Started -This guide takes you from install to your first on-ledger operation in three steps: **initialize the client**, **set up a custodian**, and **run a vertical operation**. The examples target the XRPL Testnet with a local signer so you can run them as-is, then swap in a production custodian when you're ready. +This tutorial takes you through the basics of sending your first operation on the XRP Ledger with simpleXRPL. + + +## Goals + +By the end of this tutorial, you will be able to: + +- Initialize a client. +- Connect a custodian. +- Discover your accounts. +- Check how an operation will route before you submit it. +- Transfer XRP between accounts. + ## Prerequisites -- **Node.js >= 20.19.** simpleXRPL is Node-targeted and not intended to run in the browser. -- Install the package: +To complete this tutorial, you should: -```sh -npm install simplexrpl -``` +- Have some familiarity with writing code in TypeScript. +- Have **Node.js version 20.19** or later. -## 1. Initialize the client -`SimpleXRPL.init(...)` is the single entry point — you never construct the client with `new`. It binds one or more already-authenticated signing backends (the **connectors**) to a network and builds the account index. +## Source Code -```ts -import { LocalSigner, SimpleXRPL } from 'simplexrpl' +You can find the complete source code for this tutorial's examples in the [code samples section of this website's repository](https://github.com/ripple/opensource.ripple.com/tree/main/_code-samples/simplexrpl/getStarted.ts) -const client = await SimpleXRPL.init({ - // Point at a rippled endpoint. `faucetUrl` is only used on test networks - // (by `client.account.fund`). - rippledUrl: 'wss://s.altnet.rippletest.net:51233', - faucetUrl: 'https://faucet.altnet.rippletest.net/accounts', - // Bind one or more connectors. Here, a single local-signing backend that - // reads its seeds from the environment (`XRPL_*_SEED`). - signers: [LocalSigner.fromEnv()], -}) +## Steps -// ... use the client ... +### 1. Install dependencies -await client.disconnect() +```sh +npm install simplexrpl ``` +### 2. Initialize the client + +`SimpleXRPL.init(...)` is the single entry point — you never construct the client with `new`. It binds one or more already-authenticated signing backends (the **connectors**) to a network and builds the account index. + +{% code-snippet file="/_code-samples/simplexrpl/getStarted.ts" language="ts" before="// --- Discover your accounts ---" /%} + - **`primarySigner`** is the default backend for verbs called without an explicit account. It defaults to `signers[0]`, so you only set it when you bind more than one connector. - With **no `signers`**, the client is read-only: reads work, but write verbs throw `NoSignerError` until a signer is added. - Bind an account at runtime (for example, a freshly created wallet) with `client.registerLocalAccount(seed)`. -See [Initialize the client](tutorials/inititialize-clients.md) for the full walkthrough, and [Client and initialization](references/index.md#client-and-initialization) for the configuration reference. - -## 2. Set up a custodian - -The **connector** determines how operations run and who holds the keys. simpleXRPL ships three, each constructed and authenticated on its own, then handed to `init`: - -- **`LocalSigner`** — self-custody; keys held in-process. For development and testing. -- **`RippleCustody`** — routes through Ripple Custody. For production. -- **`PalisadeCustody`** — routes through Palisade. For production. - -The local signer in Step 1 is enough for development. For production, construct a custodian connector and bind it instead of (or alongside) the local one: - -```ts -import { - LocalSigner, - PalisadeCustody, - RippleCustody, - SimpleXRPL, -} from 'simplexrpl' - -// Ripple Custody — authenticates with an intent-author key and operates within -// one Custody domain. `fromEnv` reads the `RIPPLE_CUSTODY_*` variables. -const rippleCustody = await RippleCustody.fromEnv({ - primary: process.env.RIPPLE_CUSTODY_PRIMARY ?? '', -}) - -// Palisade — authenticates via OAuth client credentials and acts on a -// specific vault/wallet. -const palisade = await PalisadeCustody.create({ - baseUrl: 'https://api.sandbox.palisade.co', - clientId: process.env.PALISADE_CLIENT_ID ?? '', - clientSecret: process.env.PALISADE_CLIENT_SECRET ?? '', - primary: { - vaultId: process.env.PALISADE_VAULT_ID ?? '', - walletId: process.env.PALISADE_WALLET_ID ?? '', - }, - // Enable the raw sign-only fallback for transactors the custodian has no - // native operation for. Off by default. - allowRawSigning: false, -}) - -const client = await SimpleXRPL.init({ - rippledUrl: 'wss://s.altnet.rippletest.net:51233', - signers: [rippleCustody, palisade, LocalSigner.fromEnv()], - primarySigner: rippleCustody, -}) -``` +See [Client and initialization](references/index.md#client-and-initialization) for the full configuration reference. + +### 3. Connect a custodian + +The local signer above is enough for development. For production, construct a custodian connector and pass it to `init`'s `signers` — in place of, or alongside, the local one. simpleXRPL ships **Ripple Custody** and **Palisade**, each constructed and authenticated on its own: + +{% code-snippet file="/_code-samples/simplexrpl/getStarted.ts" language="ts" from="// --- Connect a custodian (production) ---" /%} Read credentials from your environment or secrets manager — never hard-code keys. Once bound, every vertical verb works the same regardless of which connector owns the account: the SDK routes each write to the custodian that holds it. {% admonition type="info" name="Note" %} -Whether an operation runs through a custodian's **native** path or the **raw-signing fallback** is decided per operation; the fallback is off by default and enabled per connector via `allowRawSigning`. See [Operation Execution](index.md#operation-execution) and the [Connector Routing](references/connector-routing.md) table. +Whether an operation runs through a custodian's **native** path or the **raw-signing fallback** is decided per operation; the fallback is off by default and enabled per connector via `allowRawSigning`. See [Operation Execution](index.md#operation-execution) and the [Connector Routing](references/connectors/connector-routing.md) table. {% /admonition %} -See [Connect to custodians](tutorials/connect-custodians.md) for the full per-connector setup. +### 4. Discover your accounts -## 3. Run a vertical operation +Connectors discover their accounts at init; the client merges them into a single index keyed by r-address. List them, resolve the primary, and read on-chain state — a read needs no signer: -Operations are grouped into domain-specific **verticals** — `xrp`, `token`, `iou`, `credential`, `domain`, and `account` — reached off the client. Each verb reads as business intent rather than protocol mechanics. Here's the simplest one, a native XRP payment: +{% code-snippet file="/_code-samples/simplexrpl/getStarted.ts" language="ts" from="// --- Discover your accounts ---" before="// --- Check how operations route ---" /%} -```ts -const result = await client.xrp.transfer({ - to: 'rDestination...', - amount: '10', -}) +### 5. Check how operations route -console.log(result.txHash) -``` +Before you submit, ask how a given transactor would route for an account — signed locally, through a custodian's native operation, via the raw sign-only fallback, or rejected: + +{% code-snippet file="/_code-samples/simplexrpl/getStarted.ts" language="ts" from="// --- Check how operations route ---" before="// --- Send a payment ---" /%} + +### 6. Send a payment + +Operations are grouped into domain-specific **verticals** — `xrp`, `token`, `iou`, `credential`, `domain`, and `account` — reached off the client. Each verb uses the primary account by default; target a different bound account with `from`. Here's a native XRP payment: + +{% code-snippet file="/_code-samples/simplexrpl/getStarted.ts" language="ts" from="// --- Send a payment ---" before="// --- Connect a custodian (production) ---" /%} -- A write verb uses the **primary account** by default; target a different bound account by passing `from` in the options. -- Every write resolves to a `SubmissionResult` carrying the transaction hash, the backend's response, and a typed `intent` output. See [Results and handles](references/index.md#results-and-handles). -- **Reads** (such as `client.account.retrieve()`) need no signer and submit nothing. +Every write resolves to a `SubmissionResult` carrying the transaction hash, the backend's raw response, and a typed `intent` output. See [Results and handles](references/index.md#results-and-handles). {% admonition type="success" name="Tip" %} On a test network, create and fund an account first with [`account.create()`](references/verticals/account/create.md) and [`account.fund()`](references/verticals/account/fund.md), then use its address as the source or destination. diff --git a/docs/simpleXRPL/index.md b/docs/simpleXRPL/index.md index 46643d67..fb6db527 100644 --- a/docs/simpleXRPL/index.md +++ b/docs/simpleXRPL/index.md @@ -38,7 +38,7 @@ For every operation, on every connector, `simpleXRPL` has a statically defined r - **Unavailable**: The custodian doesn't expose a native endpoint and raw signing isn't enabled on the connector, so this operation is rejected. {% admonition type="info" name="Note" %} -For a complete list of supported operations by connector, see [Connector Routing](./references/connector-routing.md) +For a complete list of supported operations by connector, see [Connector Routing](./references/connectors/connector-routing.md) {% /admonition %} diff --git a/docs/simpleXRPL/references/connector-routing.md b/docs/simpleXRPL/references/connectors/connector-routing.md similarity index 100% rename from docs/simpleXRPL/references/connector-routing.md rename to docs/simpleXRPL/references/connectors/connector-routing.md diff --git a/docs/simpleXRPL/references/connectors/index.md b/docs/simpleXRPL/references/connectors/index.md new file mode 100644 index 00000000..0d59d81e --- /dev/null +++ b/docs/simpleXRPL/references/connectors/index.md @@ -0,0 +1,15 @@ +--- +seo: + description: A connector is a signing backend in simpleXRPL — LocalSigner, RippleCustody, or PalisadeCustody — constructed on its own and bound to the client at initialization. +labels: + - simpleXRPL + - SDK +--- + +# Connectors + +A connector is a signing backend: it determines how an operation runs and which custodian holds your account keys. Each is constructed and authenticated on its own, then passed to the client constructed by `simpleXRPL` in a `signers` array. `simpleXRPL` supports these connectors: + +- [Local](./local.md) +- [Ripple Custody](./ripple-custody.md) +- [Palisade](./palisade.md) diff --git a/docs/simpleXRPL/references/connectors/local.md b/docs/simpleXRPL/references/connectors/local.md new file mode 100644 index 00000000..66b5a599 --- /dev/null +++ b/docs/simpleXRPL/references/connectors/local.md @@ -0,0 +1,68 @@ +--- +seo: + description: LocalSigner is simpleXRPL's self-custody connector — it holds xrpl wallets in-process and signs locally, for development and testing. +labels: + - simpleXRPL + - SDK +--- + +# Local + +[Source](https://github.com/ripple/simpleXRPL/blob/50619258cf753008e8a185eaeb3ceca489e5998a/src/custodians/local/local-signer.ts#L22) + +`LocalSigner` is self-custody: it holds one or more `xrpl` wallets in-process and signs locally. For development and testing. It is constructed synchronously — no authentication, so unlike the custodial connectors its constructors are not `async`. + +## LocalSigner.fromEnv() + +```ts +LocalSigner.fromEnv(options?: LocalSignerFromEnvOptions): LocalSigner +``` + +Builds one wallet per `XRPL_*_SEED` environment variable (matching `XRPL__SEED` and a plain `XRPL_SEED`) — one wallet per match. The primary defaults to the first seed found. + +### Parameters + +`options` (`LocalSignerFromEnvOptions`) is optional: + +| Field | Type | Required | Description | +| --- | --- | --- | --- | +| `primary` | `string` | No | The primary account's r-address. Defaults to the first seed in scan order. | +| `env` | `object` | No | Environment source to scan — a map of variable names to values. Defaults to `process.env`. | + +## LocalSigner.fromSeed() + +```ts +LocalSigner.fromSeed(seed: string): LocalSigner +``` + +Builds a single wallet from a seed string. + +### Parameters + +| Parameter | Type | Required | Description | +| --- | --- | --- | --- | +| `seed` | `string` | Yes | The wallet seed (the caller's responsibility to source). | + +## LocalSigner.create() + +```ts +LocalSigner.create(options: LocalSignerCreateOptions): LocalSigner +``` + +Builds from pre-constructed `xrpl` `Wallet` objects. + +### Parameters + +`options` (`LocalSignerCreateOptions`): + +| Field | Type | Required | Description | +| --- | --- | --- | --- | +| `wallets` | `array` | Yes | The xrpl `Wallet` objects this signer holds (at least one). | +| `primary` | `string` | No | The primary account's r-address. Defaults to the first wallet. | + +## Example + +```ts +// One wallet per XRPL_*_SEED in the environment. +const local = LocalSigner.fromEnv() +``` diff --git a/docs/simpleXRPL/references/connectors/palisade.md b/docs/simpleXRPL/references/connectors/palisade.md new file mode 100644 index 00000000..5a75d0bc --- /dev/null +++ b/docs/simpleXRPL/references/connectors/palisade.md @@ -0,0 +1,52 @@ +--- +seo: + description: PalisadeCustody is simpleXRPL's production connector for Palisade — construction config and required fields for create(). +labels: + - simpleXRPL + - SDK +--- + +# Palisade + +[Source](https://github.com/ripple/simpleXRPL/blob/50619258cf753008e8a185eaeb3ceca489e5998a/src/custodians/palisade/config.ts#L10) + +`PalisadeCustody` routes through Palisade (Wallet-as-a-Service). It authenticates via OAuth2 client credentials and acts on a specific vault/wallet. + +## PalisadeCustody.create() + +```ts +PalisadeCustody.create(config: PalisadeCustodyConfig): Promise +``` + +Exchanges the credentials and discovers the org's wallets. + +### Parameters + +`config` (`PalisadeCustodyConfig`): + +| Field | Type | Required | Description | +| --- | --- | --- | --- | +| `baseUrl` | `string` | Yes | Palisade API base URL (must be HTTPS). | +| `clientId` | `string` | Yes | OAuth2 client-credentials id. | +| `clientSecret` | `string` | Yes | OAuth2 client-credentials secret (held in memory only). | +| `primary` | `object` | Yes | The wallet used when a verb is called without an explicit account. | +| `primary.vaultId` | `string` | Yes | The primary wallet's vault id. | +| `primary.walletId` | `string` | Yes | The primary wallet's id. | +| `allowRawSigning` | `boolean` | No | Allow the raw fallback for transactors/fields Palisade can't map. Defaults to `false`. | +| `defaultTimeoutMs` | `number` | No | How long to wait for a native submission to reach a terminal status. | +| `http` | `object` | No | Advanced: a custom HTTP transport (implements `PalisadeHttpPort`). Defaults to the production fetch port; most callers omit it. | +| `now` | `function` | No | Injectable clock for the auth service, returning epoch ms (`() => number`). Defaults to `Date.now`. | + +## Example + +```ts +const palisade = await PalisadeCustody.create({ + baseUrl: 'https://api.sandbox.palisade.co', + clientId: process.env.PALISADE_CLIENT_ID ?? '', + clientSecret: process.env.PALISADE_CLIENT_SECRET ?? '', + primary: { + vaultId: process.env.PALISADE_VAULT_ID ?? '', + walletId: process.env.PALISADE_WALLET_ID ?? '', + }, +}) +``` diff --git a/docs/simpleXRPL/references/connectors/ripple-custody.md b/docs/simpleXRPL/references/connectors/ripple-custody.md new file mode 100644 index 00000000..cdba8b22 --- /dev/null +++ b/docs/simpleXRPL/references/connectors/ripple-custody.md @@ -0,0 +1,70 @@ +--- +seo: + description: RippleCustody is simpleXRPL's production connector for Ripple Custody — construction options and required fields for create() and fromEnv(). +labels: + - simpleXRPL + - SDK +--- + +# Ripple Custody + +[Source](https://github.com/ripple/simpleXRPL/blob/50619258cf753008e8a185eaeb3ceca489e5998a/src/custodians/ripple/construction.ts#L30) + +`RippleCustody` routes through Ripple Custody, operating within one Custody domain. It authenticates with an intent-author key exchanged for a token. A Custody deployment is per-tenant, so its gateway and token URLs point at the instance provisioned for you. + +## RippleCustody.create() + +```ts +RippleCustody.create(options: RippleCustodyOptions): Promise +``` + +Construct with every value passed explicitly. + +### Parameters + +`options` (`RippleCustodyOptions`): + +| Field | Type | Required | Description | +| --- | --- | --- | --- | +| `gatewayUrl` | `string` | Yes | The Custody gateway base URL. | +| `auth` | `object` | Yes | Intent-author credentials and token endpoint. | +| `auth.signingKey` | `string` | Yes | Intent-author private key: PEM contents, or a path to a `.pem` file. | +| `auth.tokenUrl` | `string` | Yes | The Custody token endpoint URL. | +| `auth.publicKey` | `string` | No | Matching public key, base64 SPKI DER. Derived from `signingKey` if omitted. | +| `domainId` | `string` | Yes | The Custody domain this custodian operates in. | +| `primary` | `string` | Yes | The primary account's r-address; validated against the discovered set. | +| `allowRawSigning` | `boolean` | No | Enable the raw-signing fallback. Defaults to `false`. | +| `defaultFee` | `object` | No | Fee tier: `{ priority?: 'low' \| 'medium' \| 'high' }`. Backends that can't honor the tier auto-price and warn. Defaults to `low`. | +| `defaultDryRun` | `boolean` | No | Pre-flight every write through Custody's dry-run. Defaults to `false`. | +| `defaultTimeoutMs` | `number` | No | How long `submitAndWait` polls before throwing `IntentPendingError`. | +| `http` | `object` | No | Advanced: a custom HTTP transport (implements `CustodyHttpPort`). Defaults to the production fetch port; most callers omit it. | + +## RippleCustody.fromEnv() + +```ts +RippleCustody.fromEnv(options: RippleCustodyFromEnvOptions): Promise +``` + +Reads the endpoints, credentials, and domain from environment variables — `RIPPLE_CUSTODY_GATEWAY_URL`, `RIPPLE_CUSTODY_AUTH_SIGNING_KEY`, `RIPPLE_CUSTODY_AUTH_TOKEN_URL`, `RIPPLE_CUSTODY_AUTH_PUBLIC_KEY` (optional), and `RIPPLE_CUSTODY_DOMAIN_ID` — then applies these options: + +### Parameters + +`options` (`RippleCustodyFromEnvOptions`): + +| Field | Type | Required | Description | +| --- | --- | --- | --- | +| `primary` | `string` | Yes | The primary account's r-address; validated against the discovered set. | +| `allowRawSigning` | `boolean` | No | Enable the raw-signing fallback. Defaults to `false`. | +| `defaultFee` | `object` | No | Fee tier: `{ priority?: 'low' \| 'medium' \| 'high' }`. Backends that can't honor the tier auto-price and warn. Defaults to `low`. | +| `defaultDryRun` | `boolean` | No | Pre-flight every write through Custody's dry-run. Defaults to `false`. | +| `defaultTimeoutMs` | `number` | No | How long `submitAndWait` polls before throwing `IntentPendingError`. | +| `env` | `object` | No | Environment source to scan — a map of variable names to values. Defaults to `process.env`. | +| `http` | `object` | No | Advanced: a custom HTTP transport (implements `CustodyHttpPort`). Defaults to the production fetch port; most callers omit it. | + +## Example + +```ts +const rippleCustody = await RippleCustody.fromEnv({ + primary: process.env.RIPPLE_CUSTODY_PRIMARY ?? '', +}) +``` diff --git a/docs/simpleXRPL/references/index.md b/docs/simpleXRPL/references/index.md index 4828a49a..900e2a09 100644 --- a/docs/simpleXRPL/references/index.md +++ b/docs/simpleXRPL/references/index.md @@ -33,13 +33,7 @@ Operations are grouped into domain-specific **verticals**, one per area of XRPL ## Connectors -The connector is the execution model — it determines how operations run and who holds the keys. See [Operation Execution](../index.md#operation-execution) for how each operation routes. - -| Connector | Use | Key configuration types | -| --- | --- | --- | -| `LocalSigner` | Development and testing; holds `xrpl` wallets in-process. | `LocalSignerCreateOptions`, `LocalSignerFromEnvOptions` | -| `RippleCustody` | Production; routes through Ripple Custody. | `RippleCustodyOptions`, `RippleCustodyAuthOptions`, `RippleCustodyFromEnvOptions` | -| `PalisadeCustody` | Production; routes through Palisade. | `PalisadeCustodyConfig`, `PalisadeWalletRef` | +The connector is the execution model — it determines how operations run and who holds the keys. See [Connectors](connectors/index.md) for each connector ([LocalSigner](connectors/local.md), [RippleCustody](connectors/ripple-custody.md), [PalisadeCustody](connectors/palisade.md)) and its configuration fields, and [Operation Execution](../index.md#operation-execution) for how each operation routes. ## Amounts and assets @@ -90,5 +84,5 @@ All errors extend `SimpleXRPLError`, so you can catch the base class or narrow t Companion reference pages that live alongside this index: - **Function-to-transactor mapping** — the underlying XRPL transactor(s) each method expands into (also shown inline on each method page). -- [**Connector routing table**](connector-routing.md) — per operation and per connector, whether it routes native, requires raw-signing fallback, or is unavailable. +- [**Connector routing table**](connectors/connector-routing.md) — per operation and per connector, whether it routes native, requires raw-signing fallback, or is unavailable. - **Institutional defaults** — the full set of defaults the SDK applies unless overridden. diff --git a/docs/simpleXRPL/references/verticals/account/set.md b/docs/simpleXRPL/references/verticals/account/set.md index 6931cc10..f51b953a 100644 --- a/docs/simpleXRPL/references/verticals/account/set.md +++ b/docs/simpleXRPL/references/verticals/account/set.md @@ -33,7 +33,7 @@ All parameters are optional individually, but at least one must be provided. | --- | --- | --- | --- | | `noFreeze` | `boolean` | No | Permanently give up the ability to freeze trust lines (irreversible). | | `clawbackEnabled` | `boolean` | No | Permanently allow this issuer to claw back issued tokens (irreversible). | -| `trustLineLocking` | `boolean` | No | Permanently allow trust-line locking (irreversible). | +| `trustLineLocking` | `boolean` | No | Permanently allow trust line locking (irreversible). | | `disableMaster` | `boolean` | No | Permanently disable the master key pair (irreversible). | | `requireAuth` | `boolean` | No | Require holders to be authorized before they can hold issued tokens. | | `requireDest` | `boolean` | No | Require a destination tag on incoming payments. | diff --git a/docs/simpleXRPL/references/verticals/index.md b/docs/simpleXRPL/references/verticals/index.md index 388cb868..30cbbd69 100644 --- a/docs/simpleXRPL/references/verticals/index.md +++ b/docs/simpleXRPL/references/verticals/index.md @@ -16,7 +16,7 @@ Most vertical methods submit a transaction and resolve to a `Promise Date: Thu, 23 Jul 2026 18:01:22 -0700 Subject: [PATCH 06/24] clean up connector pages --- .../simpleXRPL/references/connectors/local.md | 25 +++++++-------- .../references/connectors/palisade.md | 12 +++---- .../references/connectors/ripple-custody.md | 32 ++++++++++++------- 3 files changed, 38 insertions(+), 31 deletions(-) diff --git a/docs/simpleXRPL/references/connectors/local.md b/docs/simpleXRPL/references/connectors/local.md index 66b5a599..533327de 100644 --- a/docs/simpleXRPL/references/connectors/local.md +++ b/docs/simpleXRPL/references/connectors/local.md @@ -10,56 +10,55 @@ labels: [Source](https://github.com/ripple/simpleXRPL/blob/50619258cf753008e8a185eaeb3ceca489e5998a/src/custodians/local/local-signer.ts#L22) -`LocalSigner` is self-custody: it holds one or more `xrpl` wallets in-process and signs locally. For development and testing. It is constructed synchronously — no authentication, so unlike the custodial connectors its constructors are not `async`. +A local connector holds one or more XRPL accounts in-process and signs operations locally. This connector is intended for development and testing purposes. Since this method doesn't require external authentication, it is constructed synchornously unlike other connectors. ## LocalSigner.fromEnv() +Builds one wallet per `XRPL_*_SEED` environment variable (matching `XRPL__SEED` and a plain `XRPL_SEED`) — one wallet per match. The primary defaults to the first seed found. + ```ts LocalSigner.fromEnv(options?: LocalSignerFromEnvOptions): LocalSigner ``` -Builds one wallet per `XRPL_*_SEED` environment variable (matching `XRPL__SEED` and a plain `XRPL_SEED`) — one wallet per match. The primary defaults to the first seed found. - -### Parameters - -`options` (`LocalSignerFromEnvOptions`) is optional: +### Options | Field | Type | Required | Description | | --- | --- | --- | --- | | `primary` | `string` | No | The primary account's r-address. Defaults to the first seed in scan order. | | `env` | `object` | No | Environment source to scan — a map of variable names to values. Defaults to `process.env`. | + ## LocalSigner.fromSeed() +Builds a single wallet from a seed string. + ```ts LocalSigner.fromSeed(seed: string): LocalSigner ``` -Builds a single wallet from a seed string. - ### Parameters | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `seed` | `string` | Yes | The wallet seed (the caller's responsibility to source). | + ## LocalSigner.create() +Builds from pre-constructed `xrpl` `Wallet` objects. + ```ts LocalSigner.create(options: LocalSignerCreateOptions): LocalSigner ``` -Builds from pre-constructed `xrpl` `Wallet` objects. - -### Parameters - -`options` (`LocalSignerCreateOptions`): +### Options | Field | Type | Required | Description | | --- | --- | --- | --- | | `wallets` | `array` | Yes | The xrpl `Wallet` objects this signer holds (at least one). | | `primary` | `string` | No | The primary account's r-address. Defaults to the first wallet. | + ## Example ```ts diff --git a/docs/simpleXRPL/references/connectors/palisade.md b/docs/simpleXRPL/references/connectors/palisade.md index 5a75d0bc..a0a7c1c5 100644 --- a/docs/simpleXRPL/references/connectors/palisade.md +++ b/docs/simpleXRPL/references/connectors/palisade.md @@ -10,19 +10,18 @@ labels: [Source](https://github.com/ripple/simpleXRPL/blob/50619258cf753008e8a185eaeb3ceca489e5998a/src/custodians/palisade/config.ts#L10) -`PalisadeCustody` routes through Palisade (Wallet-as-a-Service). It authenticates via OAuth2 client credentials and acts on a specific vault/wallet. +Palisade is a Wallet-as-a-Service. This connector authenticates via OAuth2 client credentials and acts on specific vaults/wallets. + ## PalisadeCustody.create() +Exchanges the credentials and discovers the org's wallets. + ```ts PalisadeCustody.create(config: PalisadeCustodyConfig): Promise ``` -Exchanges the credentials and discovers the org's wallets. - -### Parameters - -`config` (`PalisadeCustodyConfig`): +### Config | Field | Type | Required | Description | | --- | --- | --- | --- | @@ -37,6 +36,7 @@ Exchanges the credentials and discovers the org's wallets. | `http` | `object` | No | Advanced: a custom HTTP transport (implements `PalisadeHttpPort`). Defaults to the production fetch port; most callers omit it. | | `now` | `function` | No | Injectable clock for the auth service, returning epoch ms (`() => number`). Defaults to `Date.now`. | + ## Example ```ts diff --git a/docs/simpleXRPL/references/connectors/ripple-custody.md b/docs/simpleXRPL/references/connectors/ripple-custody.md index cdba8b22..5d9c42ec 100644 --- a/docs/simpleXRPL/references/connectors/ripple-custody.md +++ b/docs/simpleXRPL/references/connectors/ripple-custody.md @@ -10,19 +10,18 @@ labels: [Source](https://github.com/ripple/simpleXRPL/blob/50619258cf753008e8a185eaeb3ceca489e5998a/src/custodians/ripple/construction.ts#L30) -`RippleCustody` routes through Ripple Custody, operating within one Custody domain. It authenticates with an intent-author key exchanged for a token. A Custody deployment is per-tenant, so its gateway and token URLs point at the instance provisioned for you. +Ripple Custody authenticates with an intent-author key exchanged for a token. A Custody deployment is per-tenant, so its gateway and token URLs point at the instance provisioned for you. + ## RippleCustody.create() +Construct with every value passed explicitly. + ```ts RippleCustody.create(options: RippleCustodyOptions): Promise ``` -Construct with every value passed explicitly. - -### Parameters - -`options` (`RippleCustodyOptions`): +### Options | Field | Type | Required | Description | | --- | --- | --- | --- | @@ -39,17 +38,16 @@ Construct with every value passed explicitly. | `defaultTimeoutMs` | `number` | No | How long `submitAndWait` polls before throwing `IntentPendingError`. | | `http` | `object` | No | Advanced: a custom HTTP transport (implements `CustodyHttpPort`). Defaults to the production fetch port; most callers omit it. | + ## RippleCustody.fromEnv() +Reads the endpoints, credentials, and domain from environment variables. + ```ts RippleCustody.fromEnv(options: RippleCustodyFromEnvOptions): Promise ``` -Reads the endpoints, credentials, and domain from environment variables — `RIPPLE_CUSTODY_GATEWAY_URL`, `RIPPLE_CUSTODY_AUTH_SIGNING_KEY`, `RIPPLE_CUSTODY_AUTH_TOKEN_URL`, `RIPPLE_CUSTODY_AUTH_PUBLIC_KEY` (optional), and `RIPPLE_CUSTODY_DOMAIN_ID` — then applies these options: - -### Parameters - -`options` (`RippleCustodyFromEnvOptions`): +### Options | Field | Type | Required | Description | | --- | --- | --- | --- | @@ -58,9 +56,19 @@ Reads the endpoints, credentials, and domain from environment variables — `RIP | `defaultFee` | `object` | No | Fee tier: `{ priority?: 'low' \| 'medium' \| 'high' }`. Backends that can't honor the tier auto-price and warn. Defaults to `low`. | | `defaultDryRun` | `boolean` | No | Pre-flight every write through Custody's dry-run. Defaults to `false`. | | `defaultTimeoutMs` | `number` | No | How long `submitAndWait` polls before throwing `IntentPendingError`. | -| `env` | `object` | No | Environment source to scan — a map of variable names to values. Defaults to `process.env`. | +| `env` | `object` | No | The object those variables are read from — a map of names to values. Defaults to `process.env`. | | `http` | `object` | No | Advanced: a custom HTTP transport (implements `CustodyHttpPort`). Defaults to the production fetch port; most callers omit it. | +{% admonition type="info" name="Note" %} +`env` requires these keys: +- `RIPPLE_CUSTODY_GATEWAY_URL` +- `RIPPLE_CUSTODY_AUTH_SIGNING_KEY` +- `RIPPLE_CUSTODY_AUTH_TOKEN_URL` +- `RIPPLE_CUSTODY_AUTH_PUBLIC_KEY` (optional) +- `RIPPLE_CUSTODY_DOMAIN_ID` +{% /admonition %} + + ## Example ```ts From ec18829a05a1c5dc62eb1ec30cd5465adb9bcb6f Mon Sep 17 00:00:00 2001 From: Oliver Eggert Date: Thu, 23 Jul 2026 20:18:31 -0700 Subject: [PATCH 07/24] formatting cleanup --- docs/_snippets/simplexrpl-response-fields.md | 2 +- docs/simpleXRPL/references/connectors/local.md | 6 ++++++ docs/simpleXRPL/references/connectors/palisade.md | 2 ++ .../simpleXRPL/references/connectors/ripple-custody.md | 4 ++++ .../references/verticals/account/activate.md | 10 +++++----- docs/simpleXRPL/references/verticals/account/create.md | 8 ++++---- .../references/verticals/account/depositPreauth.md | 10 +++++----- docs/simpleXRPL/references/verticals/account/fund.md | 10 +++++----- .../references/verticals/account/listOffers.md | 6 +++--- .../references/verticals/account/retrieve.md | 8 ++++---- docs/simpleXRPL/references/verticals/account/set.md | 10 +++++----- .../references/verticals/account/setRegularKey.md | 10 +++++----- .../references/verticals/credential/accept.md | 10 +++++----- .../references/verticals/credential/delete.md | 10 +++++----- .../references/verticals/credential/issue.md | 10 +++++----- .../simpleXRPL/references/verticals/credential/list.md | 6 +++--- .../references/verticals/credential/retrieve.md | 8 ++++---- docs/simpleXRPL/references/verticals/domain/create.md | 10 +++++----- docs/simpleXRPL/references/verticals/domain/delete.md | 10 +++++----- docs/simpleXRPL/references/verticals/domain/list.md | 6 +++--- .../simpleXRPL/references/verticals/domain/retrieve.md | 8 ++++---- .../references/verticals/domain/setCredentials.md | 10 +++++----- docs/simpleXRPL/references/verticals/iou/authorize.md | 10 +++++----- docs/simpleXRPL/references/verticals/iou/buyOffer.md | 10 +++++----- .../simpleXRPL/references/verticals/iou/cancelOffer.md | 10 +++++----- docs/simpleXRPL/references/verticals/iou/clawback.md | 10 +++++----- docs/simpleXRPL/references/verticals/iou/issue.md | 8 ++++---- docs/simpleXRPL/references/verticals/iou/list.md | 6 +++--- docs/simpleXRPL/references/verticals/iou/listOffers.md | 6 +++--- docs/simpleXRPL/references/verticals/iou/lock.md | 10 +++++----- docs/simpleXRPL/references/verticals/iou/retrieve.md | 8 ++++---- docs/simpleXRPL/references/verticals/iou/sellOffer.md | 10 +++++----- docs/simpleXRPL/references/verticals/iou/transfer.md | 10 +++++----- docs/simpleXRPL/references/verticals/iou/unlock.md | 10 +++++----- .../simpleXRPL/references/verticals/token/authorize.md | 10 +++++----- .../references/verticals/token/cancelOffer.md | 10 +++++----- .../references/verticals/token/createOffer.md | 10 +++++----- docs/simpleXRPL/references/verticals/token/destroy.md | 10 +++++----- .../references/verticals/token/grantHolder.md | 10 +++++----- docs/simpleXRPL/references/verticals/token/issue.md | 10 +++++----- docs/simpleXRPL/references/verticals/token/list.md | 8 ++++---- .../references/verticals/token/listOffers.md | 8 ++++---- docs/simpleXRPL/references/verticals/token/lock.md | 10 +++++----- docs/simpleXRPL/references/verticals/token/retrieve.md | 8 ++++---- .../references/verticals/token/revokeHolder.md | 10 +++++----- docs/simpleXRPL/references/verticals/token/transfer.md | 10 +++++----- .../references/verticals/token/unauthorize.md | 10 +++++----- docs/simpleXRPL/references/verticals/token/unlock.md | 10 +++++----- docs/simpleXRPL/references/verticals/xrp/transfer.md | 10 +++++----- 49 files changed, 219 insertions(+), 207 deletions(-) diff --git a/docs/_snippets/simplexrpl-response-fields.md b/docs/_snippets/simplexrpl-response-fields.md index 5353a563..6c26e028 100644 --- a/docs/_snippets/simplexrpl-response-fields.md +++ b/docs/_snippets/simplexrpl-response-fields.md @@ -2,7 +2,7 @@ Every simpleXRPL write resolves to a `SubmissionResult` — a union tagged by | Field | Type | Description | | --- | --- | --- | -| `intent` | `T` | The method-specific output. See the method's response values below. | +| `intent` | `T` | The method-specific output. See the method's return fields below. | | `source` | `'rippled' \| 'custody' \| 'palisade'` | Which backend produced the result; discriminates `response`. | | `response` | `TxResponse` \| custody record \| Palisade record | The backend's raw response, preserved verbatim. | | `txHash` | `string` _(optional)_ | The XRPL transaction hash, once the transaction is on-ledger. | diff --git a/docs/simpleXRPL/references/connectors/local.md b/docs/simpleXRPL/references/connectors/local.md index 533327de..3d7b7423 100644 --- a/docs/simpleXRPL/references/connectors/local.md +++ b/docs/simpleXRPL/references/connectors/local.md @@ -16,6 +16,8 @@ A local connector holds one or more XRPL accounts in-process and signs operation Builds one wallet per `XRPL_*_SEED` environment variable (matching `XRPL__SEED` and a plain `XRPL_SEED`) — one wallet per match. The primary defaults to the first seed found. +### Signature + ```ts LocalSigner.fromEnv(options?: LocalSignerFromEnvOptions): LocalSigner ``` @@ -32,6 +34,8 @@ LocalSigner.fromEnv(options?: LocalSignerFromEnvOptions): LocalSigner Builds a single wallet from a seed string. +### Signature + ```ts LocalSigner.fromSeed(seed: string): LocalSigner ``` @@ -47,6 +51,8 @@ LocalSigner.fromSeed(seed: string): LocalSigner Builds from pre-constructed `xrpl` `Wallet` objects. +### Signature + ```ts LocalSigner.create(options: LocalSignerCreateOptions): LocalSigner ``` diff --git a/docs/simpleXRPL/references/connectors/palisade.md b/docs/simpleXRPL/references/connectors/palisade.md index a0a7c1c5..b78d8f50 100644 --- a/docs/simpleXRPL/references/connectors/palisade.md +++ b/docs/simpleXRPL/references/connectors/palisade.md @@ -17,6 +17,8 @@ Palisade is a Wallet-as-a-Service. This connector authenticates via OAuth2 clien Exchanges the credentials and discovers the org's wallets. +### Signature + ```ts PalisadeCustody.create(config: PalisadeCustodyConfig): Promise ``` diff --git a/docs/simpleXRPL/references/connectors/ripple-custody.md b/docs/simpleXRPL/references/connectors/ripple-custody.md index 5d9c42ec..9e9bbdc1 100644 --- a/docs/simpleXRPL/references/connectors/ripple-custody.md +++ b/docs/simpleXRPL/references/connectors/ripple-custody.md @@ -17,6 +17,8 @@ Ripple Custody authenticates with an intent-author key exchanged for a token. A Construct with every value passed explicitly. +### Signature + ```ts RippleCustody.create(options: RippleCustodyOptions): Promise ``` @@ -43,6 +45,8 @@ RippleCustody.create(options: RippleCustodyOptions): Promise Reads the endpoints, credentials, and domain from environment variables. +### Signature + ```ts RippleCustody.fromEnv(options: RippleCustodyFromEnvOptions): Promise ``` diff --git a/docs/simpleXRPL/references/verticals/account/activate.md b/docs/simpleXRPL/references/verticals/account/activate.md index afd82adb..411ef0cb 100644 --- a/docs/simpleXRPL/references/verticals/account/activate.md +++ b/docs/simpleXRPL/references/verticals/account/activate.md @@ -21,28 +21,28 @@ account.activate( ): Promise> ``` -### Parameters +## Parameters | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `destination` | `string` | Yes | The r-address to activate (typically from `Account.create`). | | `amount` | `string` | No | XRP to send. Defaults to the network's base reserve (plus a small buffer). | -### Options +## Options {% raw-partial file="/docs/_snippets/simplexrpl-write-options.md" /%} -### Response +## Returns Resolves to a `SubmissionResult` (from the `defaultRipple` settings change). {% raw-partial file="/docs/_snippets/simplexrpl-response-fields.md" /%} -#### Response values +### Return fields `Account.activate` attaches no `intent` output; `intent` is `undefined`. -### Underlying XRPL transactors +## Underlying XRPL transactors Runs as an ordered, multi-step sequence: diff --git a/docs/simpleXRPL/references/verticals/account/create.md b/docs/simpleXRPL/references/verticals/account/create.md index a4f11f4f..2d7990f0 100644 --- a/docs/simpleXRPL/references/verticals/account/create.md +++ b/docs/simpleXRPL/references/verticals/account/create.md @@ -22,15 +22,15 @@ Nothing is written to the ledger until the account is funded. The returned `seed account.create(): AccountCredentials ``` -### Parameters +## Parameters None. `Account.create` takes no arguments. -### Response +## Returns Returns an `AccountCredentials` object **synchronously** — this is the one `Account` verb that does not submit a transaction, so it does not return a `SubmissionResult`. -#### Response values +### Return fields | Field | Type | Description | | --- | --- | --- | @@ -39,7 +39,7 @@ Returns an `AccountCredentials` object **synchronously** — this is the one `Ac | `privateKey` | `string` | The private key (hex) — sensitive. | | `seed` | `string` | The account seed (secret) — sensitive. | -### Underlying XRPL transactor +## Underlying XRPL transactor None. `Account.create` generates a keypair locally and writes nothing to the ledger. Use [`activate`](activate.md) or [`fund`](fund.md) to bring the account on-ledger. diff --git a/docs/simpleXRPL/references/verticals/account/depositPreauth.md b/docs/simpleXRPL/references/verticals/account/depositPreauth.md index d81430e0..15dbfe77 100644 --- a/docs/simpleXRPL/references/verticals/account/depositPreauth.md +++ b/docs/simpleXRPL/references/verticals/account/depositPreauth.md @@ -21,28 +21,28 @@ account.depositPreauth( ): Promise> ``` -### Parameters +## Parameters | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `authorize` | `string` | No | An r-address to preauthorize for deposits. | | `unauthorize` | `string` | No | An r-address to remove preauthorization from. | -### Options +## Options {% raw-partial file="/docs/_snippets/simplexrpl-write-options.md" /%} -### Response +## Returns Resolves to a `SubmissionResult`. {% raw-partial file="/docs/_snippets/simplexrpl-response-fields.md" /%} -#### Response values +### Return fields `Account.depositPreauth` attaches no `intent` output; `intent` is `undefined`. -### Underlying XRPL transactor +## Underlying XRPL transactor Builds and submits a single [`DepositPreauth`](https://xrpl.org/docs/references/protocol/transactions/types/depositpreauth) transaction. diff --git a/docs/simpleXRPL/references/verticals/account/fund.md b/docs/simpleXRPL/references/verticals/account/fund.md index d569ac56..95834230 100644 --- a/docs/simpleXRPL/references/verticals/account/fund.md +++ b/docs/simpleXRPL/references/verticals/account/fund.md @@ -25,27 +25,27 @@ account.fund( ): Promise> ``` -### Parameters +## Parameters | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `destination` | `string` | Yes | The r-address to fund (typically from `Account.create`). | -### Options +## Options {% raw-partial file="/docs/_snippets/simplexrpl-write-options.md" /%} -### Response +## Returns Resolves to a `SubmissionResult` (from the `defaultRipple` settings change). {% raw-partial file="/docs/_snippets/simplexrpl-response-fields.md" /%} -#### Response values +### Return fields `Account.fund` attaches no `intent` output; `intent` is `undefined`. -### Underlying XRPL transactor +## Underlying XRPL transactor Funds the account via the network faucet (an off-ledger request, not a submitted transaction), then builds and submits a single [`AccountSet`](https://xrpl.org/docs/references/protocol/transactions/types/accountset) transaction to enable rippling (`defaultRipple`). diff --git a/docs/simpleXRPL/references/verticals/account/listOffers.md b/docs/simpleXRPL/references/verticals/account/listOffers.md index 91884229..e91fabfb 100644 --- a/docs/simpleXRPL/references/verticals/account/listOffers.md +++ b/docs/simpleXRPL/references/verticals/account/listOffers.md @@ -20,13 +20,13 @@ account.listOffers( ): Promise ``` -### Parameters +## Parameters | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `account` | `string` | No | The account whose offers to list. Defaults to the primary signer's account. | -### Response +## Returns Resolves to a `ListOffersResult`: @@ -34,7 +34,7 @@ Resolves to a `ListOffersResult`: | --- | --- | --- | | `data` | `readonly OfferSummary[]` | The shaped open offers. See [`token.listOffers`](../token/listOffers.md#offersummary) for `OfferSummary`. | -### Underlying XRPL request +## Underlying XRPL request Read-only — no signer is required and nothing is submitted. Queries the ledger with [`account_offers`](https://xrpl.org/docs/references/http-websocket-apis/public-api-methods/account-methods/account_offers). diff --git a/docs/simpleXRPL/references/verticals/account/retrieve.md b/docs/simpleXRPL/references/verticals/account/retrieve.md index 2155f438..bbf15710 100644 --- a/docs/simpleXRPL/references/verticals/account/retrieve.md +++ b/docs/simpleXRPL/references/verticals/account/retrieve.md @@ -20,13 +20,13 @@ account.retrieve( ): Promise ``` -### Parameters +## Parameters | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `account` | `string` | No | The account to read. Defaults to the primary signer's account. | -### Response +## Returns Resolves to an `AccountRetrieveResult`: @@ -34,7 +34,7 @@ Resolves to an `AccountRetrieveResult`: | --- | --- | --- | | `data` | `AccountData` | The point-in-time account snapshot. | -#### AccountData +### AccountData | Field | Type | Description | | --- | --- | --- | @@ -44,7 +44,7 @@ Resolves to an `AccountRetrieveResult`: | `ownerCount` | `number` | The number of owned ledger objects (drives the reserve). | | `flags` | `Readonly>` | Account flags as booleans, as reported by `account_flags`. | -### Underlying XRPL request +## Underlying XRPL request Read-only — no signer is required and nothing is submitted. Queries the ledger with [`account_info`](https://xrpl.org/docs/references/http-websocket-apis/public-api-methods/account-methods/account_info) (flags are resolved via `account_flags`). diff --git a/docs/simpleXRPL/references/verticals/account/set.md b/docs/simpleXRPL/references/verticals/account/set.md index f51b953a..bc745ff8 100644 --- a/docs/simpleXRPL/references/verticals/account/set.md +++ b/docs/simpleXRPL/references/verticals/account/set.md @@ -25,7 +25,7 @@ account.set( ): Promise> ``` -### Parameters +## Parameters All parameters are optional individually, but at least one must be provided. @@ -44,21 +44,21 @@ All parameters are optional individually, but at least one must be provided. | `tickSize` | `number` | No | Tick size for offers (3–15, or `0` to disable). | | `domain` | `string` | No | The account domain, as a plain string (hex-encoded on the ledger). | -### Options +## Options {% raw-partial file="/docs/_snippets/simplexrpl-write-options.md" /%} -### Response +## Returns Resolves to a `SubmissionResult`. {% raw-partial file="/docs/_snippets/simplexrpl-response-fields.md" /%} -#### Response values +### Return fields `Account.set` attaches no `intent` output; `intent` is `undefined`. -### Underlying XRPL transactor +## Underlying XRPL transactor Builds and submits a single [`AccountSet`](https://xrpl.org/docs/references/protocol/transactions/types/accountset) transaction. diff --git a/docs/simpleXRPL/references/verticals/account/setRegularKey.md b/docs/simpleXRPL/references/verticals/account/setRegularKey.md index 53ce45a9..1c18d6da 100644 --- a/docs/simpleXRPL/references/verticals/account/setRegularKey.md +++ b/docs/simpleXRPL/references/verticals/account/setRegularKey.md @@ -21,27 +21,27 @@ account.setRegularKey( ): Promise> ``` -### Parameters +## Parameters | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `regularKey` | `string` | No | The regular key r-address to set. Omit to remove the current regular key. | -### Options +## Options {% raw-partial file="/docs/_snippets/simplexrpl-write-options.md" /%} -### Response +## Returns Resolves to a `SubmissionResult`. {% raw-partial file="/docs/_snippets/simplexrpl-response-fields.md" /%} -#### Response values +### Return fields `Account.setRegularKey` attaches no `intent` output; `intent` is `undefined`. -### Underlying XRPL transactor +## Underlying XRPL transactor Builds and submits a single [`SetRegularKey`](https://xrpl.org/docs/references/protocol/transactions/types/setregularkey) transaction. diff --git a/docs/simpleXRPL/references/verticals/credential/accept.md b/docs/simpleXRPL/references/verticals/credential/accept.md index 7ce1bebe..ef91cb64 100644 --- a/docs/simpleXRPL/references/verticals/credential/accept.md +++ b/docs/simpleXRPL/references/verticals/credential/accept.md @@ -21,24 +21,24 @@ credential.accept( ): Promise`. {% raw-partial file="/docs/_snippets/simplexrpl-response-fields.md" /%} -#### Response values +### Return fields For `Credential.accept`, the `intent` echoes: @@ -47,7 +47,7 @@ For `Credential.accept`, the `intent` echoes: | `issuer` | `string` | The issuer r-address of the accepted credential. | | `credType` | `string` | The credential type that was accepted. | -### Underlying XRPL transactor +## Underlying XRPL transactor Builds and submits a single [`CredentialAccept`](https://xrpl.org/docs/references/protocol/transactions/types/credentialaccept) transaction. diff --git a/docs/simpleXRPL/references/verticals/credential/delete.md b/docs/simpleXRPL/references/verticals/credential/delete.md index e349d903..4cd248a2 100644 --- a/docs/simpleXRPL/references/verticals/credential/delete.md +++ b/docs/simpleXRPL/references/verticals/credential/delete.md @@ -21,7 +21,7 @@ credential.delete( ): Promise`. {% raw-partial file="/docs/_snippets/simplexrpl-response-fields.md" /%} -#### Response values +### Return fields For `Credential.delete`, the `intent` echoes: @@ -47,7 +47,7 @@ For `Credential.delete`, the `intent` echoes: | --- | --- | --- | | `credType` | `string` | The credential type that was deleted. | -### Underlying XRPL transactor +## Underlying XRPL transactor Builds and submits a single [`CredentialDelete`](https://xrpl.org/docs/references/protocol/transactions/types/credentialdelete) transaction. diff --git a/docs/simpleXRPL/references/verticals/credential/issue.md b/docs/simpleXRPL/references/verticals/credential/issue.md index 4b4f5b4f..4976e883 100644 --- a/docs/simpleXRPL/references/verticals/credential/issue.md +++ b/docs/simpleXRPL/references/verticals/credential/issue.md @@ -21,7 +21,7 @@ credential.issue( ): Promise`. {% raw-partial file="/docs/_snippets/simplexrpl-response-fields.md" /%} -#### Response values +### Return fields For `Credential.issue`, the `intent` echoes: @@ -49,7 +49,7 @@ For `Credential.issue`, the `intent` echoes: | `destination` | `string` | The destination (holder) r-address the credential was issued to. | | `credType` | `string` | The credential type that was issued. | -### Underlying XRPL transactor +## Underlying XRPL transactor Builds and submits a single [`CredentialCreate`](https://xrpl.org/docs/references/protocol/transactions/types/credentialcreate) transaction. diff --git a/docs/simpleXRPL/references/verticals/credential/list.md b/docs/simpleXRPL/references/verticals/credential/list.md index cd3c4bc2..c5fb76d4 100644 --- a/docs/simpleXRPL/references/verticals/credential/list.md +++ b/docs/simpleXRPL/references/verticals/credential/list.md @@ -20,14 +20,14 @@ credential.list( ): Promise ``` -### Parameters +## Parameters | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `role` | `'holder' \| 'issuer'` | No | Query as `holder` (default) or `issuer`. | | `account` | `string` | No | The account whose credentials to list. Defaults to the primary signer's account. | -### Response +## Returns Resolves to a `CredentialListResult`, where `credentials[i]` corresponds to `data[i]`: @@ -36,7 +36,7 @@ Resolves to a `CredentialListResult`, where `credentials[i]` corresponds to `dat | `credentials` | `readonly CredentialRef[]` | The identifier of each credential (`credType`, `issuer`, `holder`). | | `data` | `readonly CredentialData[]` | The shaped credentials. See [`credential.retrieve`](retrieve.md#credentialdata) for `CredentialData`. | -### Underlying XRPL request +## Underlying XRPL request Read-only — no signer is required and nothing is submitted. Queries the ledger with [`account_objects`](https://xrpl.org/docs/references/http-websocket-apis/public-api-methods/account-methods/account_objects). diff --git a/docs/simpleXRPL/references/verticals/credential/retrieve.md b/docs/simpleXRPL/references/verticals/credential/retrieve.md index 5d6edd30..fef5d41a 100644 --- a/docs/simpleXRPL/references/verticals/credential/retrieve.md +++ b/docs/simpleXRPL/references/verticals/credential/retrieve.md @@ -20,7 +20,7 @@ credential.retrieve( ): Promise ``` -### Parameters +## Parameters | Parameter | Type | Required | Description | | --- | --- | --- | --- | @@ -28,7 +28,7 @@ credential.retrieve( | `issuer` | `string` | Yes | The issuer r-address. | | `account` | `string` | No | The holder (subject). Defaults to the primary signer's account. | -### Response +## Returns Resolves to a `CredentialRetrieveResult`: @@ -39,7 +39,7 @@ Resolves to a `CredentialRetrieveResult`: | `holder` | `string` | The holder (subject) r-address. | | `data` | `CredentialData \| undefined` | The credential snapshot, or `undefined` if none exists. | -#### CredentialData +### CredentialData | Field | Type | Description | | --- | --- | --- | @@ -50,7 +50,7 @@ Resolves to a `CredentialRetrieveResult`: | `uri` | `string` _(optional)_ | The optional URI (decoded from hex). | | `expiration` | `number` _(optional)_ | Expiration (seconds since the Ripple epoch), if set. | -### Underlying XRPL request +## Underlying XRPL request Read-only — no signer is required and nothing is submitted. Queries the ledger with [`ledger_entry`](https://xrpl.org/docs/references/http-websocket-apis/public-api-methods/ledger-methods/ledger_entry). diff --git a/docs/simpleXRPL/references/verticals/domain/create.md b/docs/simpleXRPL/references/verticals/domain/create.md index a75bb0ea..f1f23aed 100644 --- a/docs/simpleXRPL/references/verticals/domain/create.md +++ b/docs/simpleXRPL/references/verticals/domain/create.md @@ -21,7 +21,7 @@ domain.create( ): Promise> ``` -### Parameters +## Parameters | Parameter | Type | Required | Description | | --- | --- | --- | --- | @@ -34,17 +34,17 @@ Each `AcceptedCredential` is: | `issuer` | `string` | Yes | The issuer r-address. | | `credType` | `string` | Yes | The credential type, as a plain string (hex-encoded on the ledger). | -### Options +## Options {% raw-partial file="/docs/_snippets/simplexrpl-write-options.md" /%} -### Response +## Returns Resolves to a `SubmissionResult`. {% raw-partial file="/docs/_snippets/simplexrpl-response-fields.md" /%} -#### Response values +### Return fields For `Domain.create`, the `intent` (`DomainIntent`) carries: @@ -52,7 +52,7 @@ For `Domain.create`, the `intent` (`DomainIntent`) carries: | --- | --- | --- | | `domainID` | `string` | The id of the newly created domain, discovered from the transaction result. | -### Underlying XRPL transactor +## Underlying XRPL transactor Builds and submits a single [`PermissionedDomainSet`](https://xrpl.org/docs/references/protocol/transactions/types/permissioneddomainset) transaction (with no domain id, creating a new domain). diff --git a/docs/simpleXRPL/references/verticals/domain/delete.md b/docs/simpleXRPL/references/verticals/domain/delete.md index 117f7ac6..88f903a7 100644 --- a/docs/simpleXRPL/references/verticals/domain/delete.md +++ b/docs/simpleXRPL/references/verticals/domain/delete.md @@ -21,23 +21,23 @@ domain.delete( ): Promise> ``` -### Parameters +## Parameters | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `domain` | `string` | Yes | The domain id to delete. | -### Options +## Options {% raw-partial file="/docs/_snippets/simplexrpl-write-options.md" /%} -### Response +## Returns Resolves to a `SubmissionResult`. {% raw-partial file="/docs/_snippets/simplexrpl-response-fields.md" /%} -#### Response values +### Return fields For `Domain.delete`, the `intent` (`DomainIntent`) echoes: @@ -45,7 +45,7 @@ For `Domain.delete`, the `intent` (`DomainIntent`) echoes: | --- | --- | --- | | `domainID` | `string` | The domain id that was deleted. | -### Underlying XRPL transactor +## Underlying XRPL transactor Builds and submits a single [`PermissionedDomainDelete`](https://xrpl.org/docs/references/protocol/transactions/types/permissioneddomaindelete) transaction. diff --git a/docs/simpleXRPL/references/verticals/domain/list.md b/docs/simpleXRPL/references/verticals/domain/list.md index b7489461..cfec58f7 100644 --- a/docs/simpleXRPL/references/verticals/domain/list.md +++ b/docs/simpleXRPL/references/verticals/domain/list.md @@ -20,13 +20,13 @@ domain.list( ): Promise ``` -### Parameters +## Parameters | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `account` | `string` | No | The owner whose domains to list. Defaults to the primary signer's account. | -### Response +## Returns Resolves to a `DomainListResult`, where `domains[i]` corresponds to `data[i]`: @@ -35,7 +35,7 @@ Resolves to a `DomainListResult`, where `domains[i]` corresponds to `data[i]`: | `domains` | `readonly string[]` | The domain id of each owned domain. | | `data` | `readonly DomainData[]` | The shaped domains. See [`domain.retrieve`](retrieve.md#domaindata) for `DomainData`. | -### Underlying XRPL request +## Underlying XRPL request Read-only — no signer is required and nothing is submitted. Queries the ledger with [`account_objects`](https://xrpl.org/docs/references/http-websocket-apis/public-api-methods/account-methods/account_objects). diff --git a/docs/simpleXRPL/references/verticals/domain/retrieve.md b/docs/simpleXRPL/references/verticals/domain/retrieve.md index 7477ee3a..3ae1796e 100644 --- a/docs/simpleXRPL/references/verticals/domain/retrieve.md +++ b/docs/simpleXRPL/references/verticals/domain/retrieve.md @@ -20,13 +20,13 @@ domain.retrieve( ): Promise ``` -### Parameters +## Parameters | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `domainID` | `string` | Yes | The domain id to fetch. | -### Response +## Returns Resolves to a `DomainRetrieveResult`: @@ -35,7 +35,7 @@ Resolves to a `DomainRetrieveResult`: | `domainID` | `string` | The queried domain id. | | `data` | `DomainData \| undefined` | The domain snapshot, or `undefined` if no such domain exists. | -#### DomainData +### DomainData | Field | Type | Description | | --- | --- | --- | @@ -43,7 +43,7 @@ Resolves to a `DomainRetrieveResult`: | `owner` | `string` | The owning account's r-address. | | `credList` | `readonly AcceptedCredential[]` | The credentials the domain accepts (each `{ issuer, credType }`, credential types decoded from hex). | -### Underlying XRPL request +## Underlying XRPL request Read-only — no signer is required and nothing is submitted. Queries the ledger with [`ledger_entry`](https://xrpl.org/docs/references/http-websocket-apis/public-api-methods/ledger-methods/ledger_entry). diff --git a/docs/simpleXRPL/references/verticals/domain/setCredentials.md b/docs/simpleXRPL/references/verticals/domain/setCredentials.md index 62644f15..8f14e89b 100644 --- a/docs/simpleXRPL/references/verticals/domain/setCredentials.md +++ b/docs/simpleXRPL/references/verticals/domain/setCredentials.md @@ -21,7 +21,7 @@ domain.setCredentials( ): Promise> ``` -### Parameters +## Parameters | Parameter | Type | Required | Description | | --- | --- | --- | --- | @@ -35,17 +35,17 @@ Each `AcceptedCredential` is: | `issuer` | `string` | Yes | The issuer r-address. | | `credType` | `string` | Yes | The credential type, as a plain string (hex-encoded on the ledger). | -### Options +## Options {% raw-partial file="/docs/_snippets/simplexrpl-write-options.md" /%} -### Response +## Returns Resolves to a `SubmissionResult`. {% raw-partial file="/docs/_snippets/simplexrpl-response-fields.md" /%} -#### Response values +### Return fields For `Domain.setCredentials`, the `intent` (`DomainIntent`) echoes: @@ -53,7 +53,7 @@ For `Domain.setCredentials`, the `intent` (`DomainIntent`) echoes: | --- | --- | --- | | `domainID` | `string` | The domain id that was updated. | -### Underlying XRPL transactor +## Underlying XRPL transactor Builds and submits a single [`PermissionedDomainSet`](https://xrpl.org/docs/references/protocol/transactions/types/permissioneddomainset) transaction naming the existing domain id. diff --git a/docs/simpleXRPL/references/verticals/iou/authorize.md b/docs/simpleXRPL/references/verticals/iou/authorize.md index bffaac79..d741599c 100644 --- a/docs/simpleXRPL/references/verticals/iou/authorize.md +++ b/docs/simpleXRPL/references/verticals/iou/authorize.md @@ -25,24 +25,24 @@ iou.authorize( ): Promise> ``` -### Parameters +## Parameters | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `ticker` | `string` | Yes | The currency code (3-character ISO-4217-style or 40-character hex; other codes are auto-encoded to hex). | | `holder` | `string` | Yes | The holder's r-address being authorized. | -### Options +## Options {% raw-partial file="/docs/_snippets/simplexrpl-write-options.md" /%} -### Response +## Returns Resolves to a `SubmissionResult`. {% raw-partial file="/docs/_snippets/simplexrpl-response-fields.md" /%} -#### Response values +### Return fields For `IOU.authorize`, the `intent` (`IOUAuthorizeIntent`) echoes: @@ -50,7 +50,7 @@ For `IOU.authorize`, the `intent` (`IOUAuthorizeIntent`) echoes: | --- | --- | --- | | `holder` | `string` | The holder's r-address that was authorized. | -### Underlying XRPL transactor +## Underlying XRPL transactor Builds and submits a single [`TrustSet`](https://xrpl.org/docs/references/protocol/transactions/types/trustset) transaction with the authorize flag set. diff --git a/docs/simpleXRPL/references/verticals/iou/buyOffer.md b/docs/simpleXRPL/references/verticals/iou/buyOffer.md index 95944d22..5abe3c4d 100644 --- a/docs/simpleXRPL/references/verticals/iou/buyOffer.md +++ b/docs/simpleXRPL/references/verticals/iou/buyOffer.md @@ -21,7 +21,7 @@ iou.buyOffer( ): Promise> ``` -### Parameters +## Parameters | Parameter | Type | Required | Description | | --- | --- | --- | --- | @@ -41,21 +41,21 @@ iou.buyOffer( | `{ mptIssuanceId: string; amount: number }` | Priced in an MPT. | | `{ ticker: string; issuer: string; amount: number }` | Priced in another IOU. | -### Options +## Options {% raw-partial file="/docs/_snippets/simplexrpl-write-options.md" /%} -### Response +## Returns Resolves to a `SubmissionResult`. {% raw-partial file="/docs/_snippets/simplexrpl-response-fields.md" /%} -#### Response values +### Return fields `IOU.buyOffer` attaches no `intent` output; `intent` is `undefined`. -### Underlying XRPL transactor +## Underlying XRPL transactor Builds and submits a single [`OfferCreate`](https://xrpl.org/docs/references/protocol/transactions/types/offercreate) transaction. Throws an `IntentValidationError` if `price` is MPT-denominated. diff --git a/docs/simpleXRPL/references/verticals/iou/cancelOffer.md b/docs/simpleXRPL/references/verticals/iou/cancelOffer.md index f95dd3cb..f2aae789 100644 --- a/docs/simpleXRPL/references/verticals/iou/cancelOffer.md +++ b/docs/simpleXRPL/references/verticals/iou/cancelOffer.md @@ -21,23 +21,23 @@ iou.cancelOffer( ): Promise`. {% raw-partial file="/docs/_snippets/simplexrpl-response-fields.md" /%} -#### Response values +### Return fields For `IOU.cancelOffer`, the `intent` echoes: @@ -45,7 +45,7 @@ For `IOU.cancelOffer`, the `intent` echoes: | --- | --- | --- | | `offerSequence` | `number` | The sequence number of the offer that was canceled. | -### Underlying XRPL transactor +## Underlying XRPL transactor Builds and submits a single [`OfferCancel`](https://xrpl.org/docs/references/protocol/transactions/types/offercancel) transaction. diff --git a/docs/simpleXRPL/references/verticals/iou/clawback.md b/docs/simpleXRPL/references/verticals/iou/clawback.md index 63e43945..09f2dd63 100644 --- a/docs/simpleXRPL/references/verticals/iou/clawback.md +++ b/docs/simpleXRPL/references/verticals/iou/clawback.md @@ -25,7 +25,7 @@ iou.clawback( ): Promise> ``` -### Parameters +## Parameters | Parameter | Type | Required | Description | | --- | --- | --- | --- | @@ -33,17 +33,17 @@ iou.clawback( | `holder` | `string` | Yes | The holder's r-address to claw the currency back from. | | `amount` | `number` | Yes | The amount to claw back. | -### Options +## Options {% raw-partial file="/docs/_snippets/simplexrpl-write-options.md" /%} -### Response +## Returns Resolves to a `SubmissionResult`. {% raw-partial file="/docs/_snippets/simplexrpl-response-fields.md" /%} -#### Response values +### Return fields For `IOU.clawback`, the `intent` (`IOUClawbackIntent`) echoes: @@ -52,7 +52,7 @@ For `IOU.clawback`, the `intent` (`IOUClawbackIntent`) echoes: | `holder` | `string` | The holder's r-address clawed back from. | | `amount` | `number` | The amount clawed back. | -### Underlying XRPL transactor +## Underlying XRPL transactor Builds and submits a single [`Clawback`](https://xrpl.org/docs/references/protocol/transactions/types/clawback) transaction. diff --git a/docs/simpleXRPL/references/verticals/iou/issue.md b/docs/simpleXRPL/references/verticals/iou/issue.md index 0d91143d..723edaf9 100644 --- a/docs/simpleXRPL/references/verticals/iou/issue.md +++ b/docs/simpleXRPL/references/verticals/iou/issue.md @@ -24,19 +24,19 @@ iou.issue( ): Promise> ``` -### Parameters +## Parameters | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `ticker` | `string` | Yes | The currency code: a 3-character ISO-4217-style code or a 40-character hex code. Any other code (e.g. a 5-character ticker) is auto-encoded to the 40-character hex form. | -### Response +## Returns Resolves to a `SubmissionResult` (from the final step). {% raw-partial file="/docs/_snippets/simplexrpl-response-fields.md" /%} -#### Response values +### Return fields For `IOU.issue`, the `intent` (`IOUIssueIntent`) carries: @@ -44,7 +44,7 @@ For `IOU.issue`, the `intent` (`IOUIssueIntent`) carries: | --- | --- | --- | | `iouID` | `string` | The currency code and issuer of the new IOU, e.g. `USD.rIssuer...`. | -### Underlying XRPL transactors +## Underlying XRPL transactors Runs as an ordered, multi-step sequence (no rollback on partial failure): diff --git a/docs/simpleXRPL/references/verticals/iou/list.md b/docs/simpleXRPL/references/verticals/iou/list.md index c97272dd..b6942a89 100644 --- a/docs/simpleXRPL/references/verticals/iou/list.md +++ b/docs/simpleXRPL/references/verticals/iou/list.md @@ -20,14 +20,14 @@ iou.list( ): Promise ``` -### Parameters +## Parameters | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `role` | `'holder' \| 'issuer'` | No | Query as `holder` (default) or `issuer`. | | `account` | `string` | No | The account whose trust lines to list. Defaults to the primary signer's account. | -### Response +## Returns Resolves to an `IOUListResult`, where `ious[i]` corresponds to `data[i]`: @@ -36,7 +36,7 @@ Resolves to an `IOUListResult`, where `ious[i]` corresponds to `data[i]`: | `ious` | `readonly string[]` | The `iouID` of each line, composable into the write verbs. | | `data` | `readonly IOUTrustLine[]` | The shaped trust lines. See [`iou.retrieve`](retrieve.md#ioutrustline) for `IOUTrustLine`. | -### Underlying XRPL request +## Underlying XRPL request Read-only — no signer is required and nothing is submitted. Queries the ledger with [`account_lines`](https://xrpl.org/docs/references/http-websocket-apis/public-api-methods/account-methods/account_lines). diff --git a/docs/simpleXRPL/references/verticals/iou/listOffers.md b/docs/simpleXRPL/references/verticals/iou/listOffers.md index 217994f1..b59befeb 100644 --- a/docs/simpleXRPL/references/verticals/iou/listOffers.md +++ b/docs/simpleXRPL/references/verticals/iou/listOffers.md @@ -24,14 +24,14 @@ iou.listOffers( ): Promise ``` -### Parameters +## Parameters | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `ticker` | `string` | Yes | The IOU currency code to anchor the book on. | | `issuer` | `string` | Yes | The IOU issuer's r-address. | -### Response +## Returns Resolves to a `ListOffersResult`: @@ -39,7 +39,7 @@ Resolves to a `ListOffersResult`: | --- | --- | --- | | `data` | `readonly OfferSummary[]` | The shaped open offers, tagged buy/sell relative to the IOU. See [`token.listOffers`](../token/listOffers.md#offersummary) for `OfferSummary`. | -### Underlying XRPL request +## Underlying XRPL request Read-only — no signer is required and nothing is submitted. Queries both sides of the order book with [`book_offers`](https://xrpl.org/docs/references/http-websocket-apis/public-api-methods/path-and-order-book-methods/book_offers). diff --git a/docs/simpleXRPL/references/verticals/iou/lock.md b/docs/simpleXRPL/references/verticals/iou/lock.md index 3617cc45..255fcd1c 100644 --- a/docs/simpleXRPL/references/verticals/iou/lock.md +++ b/docs/simpleXRPL/references/verticals/iou/lock.md @@ -21,24 +21,24 @@ iou.lock( ): Promise> ``` -### Parameters +## Parameters | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `ticker` | `string` | Yes | The currency code (3-character ISO-4217-style or 40-character hex; other codes are auto-encoded to hex). | | `holder` | `string` | Yes | The holder's r-address whose trust line is locked. | -### Options +## Options {% raw-partial file="/docs/_snippets/simplexrpl-write-options.md" /%} -### Response +## Returns Resolves to a `SubmissionResult` (from the final step). {% raw-partial file="/docs/_snippets/simplexrpl-response-fields.md" /%} -#### Response values +### Return fields For `IOU.lock`, the `intent` (`IOULockIntent`) echoes: @@ -46,7 +46,7 @@ For `IOU.lock`, the `intent` (`IOULockIntent`) echoes: | --- | --- | --- | | `holder` | `string` | The holder's r-address whose trust line was locked. | -### Underlying XRPL transactors +## Underlying XRPL transactors Runs as an ordered, multi-step sequence (no rollback on partial failure): diff --git a/docs/simpleXRPL/references/verticals/iou/retrieve.md b/docs/simpleXRPL/references/verticals/iou/retrieve.md index 5eae76aa..8680af7b 100644 --- a/docs/simpleXRPL/references/verticals/iou/retrieve.md +++ b/docs/simpleXRPL/references/verticals/iou/retrieve.md @@ -20,7 +20,7 @@ iou.retrieve( ): Promise ``` -### Parameters +## Parameters | Parameter | Type | Required | Description | | --- | --- | --- | --- | @@ -28,7 +28,7 @@ iou.retrieve( | `issuer` | `string` | Yes | The IOU issuer's r-address. | | `account` | `string` | No | The holder account to read from. Defaults to the primary signer's account. | -### Response +## Returns Resolves to an `IOURetrieveResult`: @@ -37,7 +37,7 @@ Resolves to an `IOURetrieveResult`: | `iouID` | `string` | Currency code and issuer, e.g. `USD.rIssuer...` — pass to the write verbs. | | `data` | `IOUTrustLine \| undefined` | The point-in-time trust line snapshot, or `undefined` if no line exists. | -#### IOUTrustLine +### IOUTrustLine | Field | Type | Description | | --- | --- | --- | @@ -50,7 +50,7 @@ Resolves to an `IOURetrieveResult`: | `frozen` | `boolean` | Whether the queried account has frozen this line. | | `authorized` | `boolean` | Whether the line is authorized (issuer authorized the holder). | -### Underlying XRPL request +## Underlying XRPL request Read-only — no signer is required and nothing is submitted. Queries the ledger with [`account_lines`](https://xrpl.org/docs/references/http-websocket-apis/public-api-methods/account-methods/account_lines). diff --git a/docs/simpleXRPL/references/verticals/iou/sellOffer.md b/docs/simpleXRPL/references/verticals/iou/sellOffer.md index ae6da44e..a8bd220c 100644 --- a/docs/simpleXRPL/references/verticals/iou/sellOffer.md +++ b/docs/simpleXRPL/references/verticals/iou/sellOffer.md @@ -21,7 +21,7 @@ iou.sellOffer( ): Promise> ``` -### Parameters +## Parameters | Parameter | Type | Required | Description | | --- | --- | --- | --- | @@ -41,21 +41,21 @@ iou.sellOffer( | `{ mptIssuanceId: string; amount: number }` | Priced in an MPT. | | `{ ticker: string; issuer: string; amount: number }` | Priced in another IOU. | -### Options +## Options {% raw-partial file="/docs/_snippets/simplexrpl-write-options.md" /%} -### Response +## Returns Resolves to a `SubmissionResult`. {% raw-partial file="/docs/_snippets/simplexrpl-response-fields.md" /%} -#### Response values +### Return fields `IOU.sellOffer` attaches no `intent` output; `intent` is `undefined`. -### Underlying XRPL transactor +## Underlying XRPL transactor Builds and submits a single [`OfferCreate`](https://xrpl.org/docs/references/protocol/transactions/types/offercreate) transaction. Throws an `IntentValidationError` if `price` is MPT-denominated. diff --git a/docs/simpleXRPL/references/verticals/iou/transfer.md b/docs/simpleXRPL/references/verticals/iou/transfer.md index ad12602a..bf7776cd 100644 --- a/docs/simpleXRPL/references/verticals/iou/transfer.md +++ b/docs/simpleXRPL/references/verticals/iou/transfer.md @@ -21,7 +21,7 @@ iou.transfer( ): Promise> ``` -### Parameters +## Parameters | Parameter | Type | Required | Description | | --- | --- | --- | --- | @@ -29,17 +29,17 @@ iou.transfer( | `destination` | `string` | Yes | The destination r-address. | | `amount` | `number` | Yes | The amount to send. | -### Options +## Options {% raw-partial file="/docs/_snippets/simplexrpl-write-options.md" /%} -### Response +## Returns Resolves to a `SubmissionResult`. {% raw-partial file="/docs/_snippets/simplexrpl-response-fields.md" /%} -#### Response values +### Return fields For `IOU.transfer`, the `intent` (`IOUTransferIntent`) echoes: @@ -48,7 +48,7 @@ For `IOU.transfer`, the `intent` (`IOUTransferIntent`) echoes: | `destination` | `string` | Destination r-address. | | `amount` | `number` | Amount sent. | -### Underlying XRPL transactor +## Underlying XRPL transactor Builds and submits a single [`Payment`](https://xrpl.org/docs/references/protocol/transactions/types/payment) transaction. diff --git a/docs/simpleXRPL/references/verticals/iou/unlock.md b/docs/simpleXRPL/references/verticals/iou/unlock.md index 9b7ec90f..86b70e18 100644 --- a/docs/simpleXRPL/references/verticals/iou/unlock.md +++ b/docs/simpleXRPL/references/verticals/iou/unlock.md @@ -21,24 +21,24 @@ iou.unlock( ): Promise> ``` -### Parameters +## Parameters | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `ticker` | `string` | Yes | The currency code (3-character ISO-4217-style or 40-character hex; other codes are auto-encoded to hex). | | `holder` | `string` | Yes | The holder's r-address whose trust line is unlocked. | -### Options +## Options {% raw-partial file="/docs/_snippets/simplexrpl-write-options.md" /%} -### Response +## Returns Resolves to a `SubmissionResult` (from the final step). {% raw-partial file="/docs/_snippets/simplexrpl-response-fields.md" /%} -#### Response values +### Return fields For `IOU.unlock`, the `intent` (`IOULockIntent`) echoes: @@ -46,7 +46,7 @@ For `IOU.unlock`, the `intent` (`IOULockIntent`) echoes: | --- | --- | --- | | `holder` | `string` | The holder's r-address whose trust line was unlocked. | -### Underlying XRPL transactors +## Underlying XRPL transactors Runs as an ordered, multi-step sequence (no rollback on partial failure): diff --git a/docs/simpleXRPL/references/verticals/token/authorize.md b/docs/simpleXRPL/references/verticals/token/authorize.md index 276c9f54..d6a7754d 100644 --- a/docs/simpleXRPL/references/verticals/token/authorize.md +++ b/docs/simpleXRPL/references/verticals/token/authorize.md @@ -21,23 +21,23 @@ token.authorize( ): Promise`. {% raw-partial file="/docs/_snippets/simplexrpl-response-fields.md" /%} -#### Response values +### Return fields For `Token.authorize`, the `intent` echoes: @@ -45,7 +45,7 @@ For `Token.authorize`, the `intent` echoes: | --- | --- | --- | | `mptIssuanceId` | `string` | The MPT issuance id that was authorized. | -### Underlying XRPL transactor +## Underlying XRPL transactor Builds and submits a single [`MPTokenAuthorize`](https://xrpl.org/docs/references/protocol/transactions/types/mptokenauthorize) transaction. diff --git a/docs/simpleXRPL/references/verticals/token/cancelOffer.md b/docs/simpleXRPL/references/verticals/token/cancelOffer.md index 29e6bbc1..5e22237c 100644 --- a/docs/simpleXRPL/references/verticals/token/cancelOffer.md +++ b/docs/simpleXRPL/references/verticals/token/cancelOffer.md @@ -21,23 +21,23 @@ token.cancelOffer( ): Promise`. {% raw-partial file="/docs/_snippets/simplexrpl-response-fields.md" /%} -#### Response values +### Return fields For `Token.cancelOffer`, the `intent` echoes: @@ -45,7 +45,7 @@ For `Token.cancelOffer`, the `intent` echoes: | --- | --- | --- | | `offerSequence` | `number` | The sequence number of the offer that was canceled. | -### Underlying XRPL transactor +## Underlying XRPL transactor Builds and submits a single [`OfferCancel`](https://xrpl.org/docs/references/protocol/transactions/types/offercancel) transaction. diff --git a/docs/simpleXRPL/references/verticals/token/createOffer.md b/docs/simpleXRPL/references/verticals/token/createOffer.md index 365b8ec4..ce169d85 100644 --- a/docs/simpleXRPL/references/verticals/token/createOffer.md +++ b/docs/simpleXRPL/references/verticals/token/createOffer.md @@ -21,7 +21,7 @@ token.createOffer( ): Promise> ``` -### Parameters +## Parameters | Parameter | Type | Required | Description | | --- | --- | --- | --- | @@ -40,21 +40,21 @@ The `flags` object accepts: | `fillOrKill` | `boolean` | No | Consume the full amount or cancel entirely. | | `sell` | `boolean` | No | Interpret the offer as selling `takerGets`. | -### Options +## Options {% raw-partial file="/docs/_snippets/simplexrpl-write-options.md" /%} -### Response +## Returns Resolves to a `SubmissionResult`. {% raw-partial file="/docs/_snippets/simplexrpl-response-fields.md" /%} -#### Response values +### Return fields `Token.createOffer` attaches no `intent` output; `intent` is `undefined`. -### Underlying XRPL transactor +## Underlying XRPL transactor Builds and submits a single [`OfferCreate`](https://xrpl.org/docs/references/protocol/transactions/types/offercreate) transaction. Throws an `IntentValidationError` if either amount is an MPT. diff --git a/docs/simpleXRPL/references/verticals/token/destroy.md b/docs/simpleXRPL/references/verticals/token/destroy.md index 2ff6e441..5b030194 100644 --- a/docs/simpleXRPL/references/verticals/token/destroy.md +++ b/docs/simpleXRPL/references/verticals/token/destroy.md @@ -21,23 +21,23 @@ token.destroy( ): Promise`. {% raw-partial file="/docs/_snippets/simplexrpl-response-fields.md" /%} -#### Response values +### Return fields For `Token.destroy`, the `intent` echoes: @@ -45,7 +45,7 @@ For `Token.destroy`, the `intent` echoes: | --- | --- | --- | | `mptIssuanceId` | `string` | The MPT issuance id that was destroyed. | -### Underlying XRPL transactor +## Underlying XRPL transactor Builds and submits a single [`MPTokenIssuanceDestroy`](https://xrpl.org/docs/references/protocol/transactions/types/mptokenissuancedestroy) transaction. diff --git a/docs/simpleXRPL/references/verticals/token/grantHolder.md b/docs/simpleXRPL/references/verticals/token/grantHolder.md index bbd016dd..73473b1e 100644 --- a/docs/simpleXRPL/references/verticals/token/grantHolder.md +++ b/docs/simpleXRPL/references/verticals/token/grantHolder.md @@ -21,24 +21,24 @@ token.grantHolder( ): Promise`. {% raw-partial file="/docs/_snippets/simplexrpl-response-fields.md" /%} -#### Response values +### Return fields For `Token.grantHolder`, the `intent` echoes: @@ -46,7 +46,7 @@ For `Token.grantHolder`, the `intent` echoes: | --- | --- | --- | | `mptIssuanceId` | `string` | The MPT issuance id the holder was granted on. | -### Underlying XRPL transactor +## Underlying XRPL transactor Builds and submits a single [`MPTokenAuthorize`](https://xrpl.org/docs/references/protocol/transactions/types/mptokenauthorize) transaction naming the holder. diff --git a/docs/simpleXRPL/references/verticals/token/issue.md b/docs/simpleXRPL/references/verticals/token/issue.md index b1c244b9..8376ffb9 100644 --- a/docs/simpleXRPL/references/verticals/token/issue.md +++ b/docs/simpleXRPL/references/verticals/token/issue.md @@ -21,7 +21,7 @@ token.issue( ): Promise> ``` -### Parameters +## Parameters | Parameter | Type | Required | Description | | --- | --- | --- | --- | @@ -46,17 +46,17 @@ The `flags` object accepts: `issue()` applies opinionated, overridable defaults so a bare call yields a usable token: `canLock`, `canEscrow`, `canTrade`, `canTransfer`, and `canClawback` are all enabled, and `requireAuth` is off. Pass any flag explicitly to override it. MPT capability flags are **permanent** once the issuance exists. {% /admonition %} -### Options +## Options {% raw-partial file="/docs/_snippets/simplexrpl-write-options.md" /%} -### Response +## Returns Resolves to a `SubmissionResult`. {% raw-partial file="/docs/_snippets/simplexrpl-response-fields.md" /%} -#### Response values +### Return fields For `Token.issue`, the `intent` (`MptIssueIntent`) carries: @@ -64,7 +64,7 @@ For `Token.issue`, the `intent` (`MptIssueIntent`) carries: | --- | --- | --- | | `mptIssuanceId` | `string` | The id of the newly created MPT issuance. | -### Underlying XRPL transactor +## Underlying XRPL transactor Builds and submits a single [`MPTokenIssuanceCreate`](https://xrpl.org/docs/references/protocol/transactions/types/mptokenissuancecreate) transaction. diff --git a/docs/simpleXRPL/references/verticals/token/list.md b/docs/simpleXRPL/references/verticals/token/list.md index 97c93c8c..bc8fc529 100644 --- a/docs/simpleXRPL/references/verticals/token/list.md +++ b/docs/simpleXRPL/references/verticals/token/list.md @@ -20,14 +20,14 @@ token.list( ): Promise ``` -### Parameters +## Parameters | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `role` | `'holder' \| 'issuer'` | No | List tokens the account holds (default) or issued. | | `account` | `string` | No | The account to query. Defaults to the primary signer's account. | -### Response +## Returns Resolves to a `TokenListResult`, where `tokens[i]` corresponds to `data[i]`: @@ -36,7 +36,7 @@ Resolves to a `TokenListResult`, where `tokens[i]` corresponds to `data[i]`: | `tokens` | `readonly string[]` | The MPT issuance id of each token. | | `data` | `readonly TokenListEntry[]` | The shaped entries. | -#### TokenListEntry +### TokenListEntry | Field | Type | Description | | --- | --- | --- | @@ -44,7 +44,7 @@ Resolves to a `TokenListResult`, where `tokens[i]` corresponds to `data[i]`: | `balance` | `string` _(optional)_ | The account's balance (present for `role: 'holder'`). | | `issuance` | `TokenData` _(optional)_ | The full issuance snapshot (present for `role: 'issuer'`). See [`token.retrieve`](retrieve.md#tokendata) for `TokenData`. | -### Underlying XRPL request +## Underlying XRPL request Read-only — no signer is required and nothing is submitted. Queries the ledger with [`account_objects`](https://xrpl.org/docs/references/http-websocket-apis/public-api-methods/account-methods/account_objects). diff --git a/docs/simpleXRPL/references/verticals/token/listOffers.md b/docs/simpleXRPL/references/verticals/token/listOffers.md index 71bbe85e..e55bffc6 100644 --- a/docs/simpleXRPL/references/verticals/token/listOffers.md +++ b/docs/simpleXRPL/references/verticals/token/listOffers.md @@ -20,13 +20,13 @@ token.listOffers( ): Promise ``` -### Parameters +## Parameters | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `account` | `string` | No | The account whose offers to list. Defaults to the primary signer's account. | -### Response +## Returns Resolves to a `ListOffersResult`: @@ -34,7 +34,7 @@ Resolves to a `ListOffersResult`: | --- | --- | --- | | `data` | `readonly OfferSummary[]` | The shaped open offers. | -#### OfferSummary +### OfferSummary Each offer mirrors the `createOffer` / `buyOffer` / `sellOffer` input format, so it's composable back into those write verbs. @@ -46,7 +46,7 @@ Each offer mirrors the `createOffer` / `buyOffer` / `sellOffer` input format, so | `orderType` | `'limit' \| 'passive'` | Resting offers are `limit`, or `passive` when the passive flag is set. | | `type` | `'buy' \| 'sell'` | Whether the offer buys or sells the base asset. | -### Underlying XRPL request +## Underlying XRPL request Read-only — no signer is required and nothing is submitted. Queries the ledger with [`account_offers`](https://xrpl.org/docs/references/http-websocket-apis/public-api-methods/account-methods/account_offers). diff --git a/docs/simpleXRPL/references/verticals/token/lock.md b/docs/simpleXRPL/references/verticals/token/lock.md index 892b28f9..ee1e0201 100644 --- a/docs/simpleXRPL/references/verticals/token/lock.md +++ b/docs/simpleXRPL/references/verticals/token/lock.md @@ -21,24 +21,24 @@ token.lock( ): Promise`. {% raw-partial file="/docs/_snippets/simplexrpl-response-fields.md" /%} -#### Response values +### Return fields For `Token.lock`, the `intent` carries: @@ -47,7 +47,7 @@ For `Token.lock`, the `intent` carries: | `mptIssuanceId` | `string` | The MPT issuance id that was locked. | | `locked` | `boolean` | The resulting lock state (`true`). | -### Underlying XRPL transactor +## Underlying XRPL transactor Builds and submits a single [`MPTokenIssuanceSet`](https://xrpl.org/docs/references/protocol/transactions/types/mptokenissuanceset) transaction with the lock flag set. diff --git a/docs/simpleXRPL/references/verticals/token/retrieve.md b/docs/simpleXRPL/references/verticals/token/retrieve.md index d6200efd..34483abe 100644 --- a/docs/simpleXRPL/references/verticals/token/retrieve.md +++ b/docs/simpleXRPL/references/verticals/token/retrieve.md @@ -20,13 +20,13 @@ token.retrieve( ): Promise ``` -### Parameters +## Parameters | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `mptIssuanceId` | `string` | Yes | The MPT issuance id to fetch. | -### Response +## Returns Resolves to a `TokenRetrieveResult`: @@ -35,7 +35,7 @@ Resolves to a `TokenRetrieveResult`: | `tokenID` | `string` | The queried MPT issuance id. | | `data` | `TokenData \| undefined` | The issuance snapshot, or `undefined` if no such issuance exists. | -#### TokenData +### TokenData | Field | Type | Description | | --- | --- | --- | @@ -48,7 +48,7 @@ Resolves to a `TokenRetrieveResult`: | `flags` | `MptFlags` | Capability flags decoded to booleans: `canLock`, `requireAuth`, `canEscrow`, `canTrade`, `canTransfer`, `canClawback`. | | `metadata` | `MPTokenMetadata` _(optional)_ | Decoded XLS-89 metadata, if present and well-formed. | -### Underlying XRPL request +## Underlying XRPL request Read-only — no signer is required and nothing is submitted. Queries the ledger with [`ledger_entry`](https://xrpl.org/docs/references/http-websocket-apis/public-api-methods/ledger-methods/ledger_entry). diff --git a/docs/simpleXRPL/references/verticals/token/revokeHolder.md b/docs/simpleXRPL/references/verticals/token/revokeHolder.md index 779cfe0c..9e910fff 100644 --- a/docs/simpleXRPL/references/verticals/token/revokeHolder.md +++ b/docs/simpleXRPL/references/verticals/token/revokeHolder.md @@ -21,24 +21,24 @@ token.revokeHolder( ): Promise`. {% raw-partial file="/docs/_snippets/simplexrpl-response-fields.md" /%} -#### Response values +### Return fields For `Token.revokeHolder`, the `intent` echoes: @@ -46,7 +46,7 @@ For `Token.revokeHolder`, the `intent` echoes: | --- | --- | --- | | `mptIssuanceId` | `string` | The MPT issuance id the holder was revoked on. | -### Underlying XRPL transactor +## Underlying XRPL transactor Builds and submits a single [`MPTokenAuthorize`](https://xrpl.org/docs/references/protocol/transactions/types/mptokenauthorize) transaction naming the holder, with the unauthorize flag set. diff --git a/docs/simpleXRPL/references/verticals/token/transfer.md b/docs/simpleXRPL/references/verticals/token/transfer.md index 1715930f..ffc4462c 100644 --- a/docs/simpleXRPL/references/verticals/token/transfer.md +++ b/docs/simpleXRPL/references/verticals/token/transfer.md @@ -21,24 +21,24 @@ token.transfer( ): Promise`. {% raw-partial file="/docs/_snippets/simplexrpl-response-fields.md" /%} -#### Response values +### Return fields For `Token.transfer`, the `intent` echoes: @@ -47,7 +47,7 @@ For `Token.transfer`, the `intent` echoes: | `to` | `string` | Destination r-address. | | `amount` | `string` | The amount sent, as a decimal string. | -### Underlying XRPL transactor +## Underlying XRPL transactor Builds and submits a single [`Payment`](https://xrpl.org/docs/references/protocol/transactions/types/payment) transaction. Throws an `IntentValidationError` if `amount`'s asset is not an MPT — use [`XRP.transfer`](../xrp/transfer.md) for XRP. diff --git a/docs/simpleXRPL/references/verticals/token/unauthorize.md b/docs/simpleXRPL/references/verticals/token/unauthorize.md index 1491fac4..cf754ff1 100644 --- a/docs/simpleXRPL/references/verticals/token/unauthorize.md +++ b/docs/simpleXRPL/references/verticals/token/unauthorize.md @@ -21,23 +21,23 @@ token.unauthorize( ): Promise`. {% raw-partial file="/docs/_snippets/simplexrpl-response-fields.md" /%} -#### Response values +### Return fields For `Token.unauthorize`, the `intent` echoes: @@ -45,7 +45,7 @@ For `Token.unauthorize`, the `intent` echoes: | --- | --- | --- | | `mptIssuanceId` | `string` | The MPT issuance id that was deauthorized. | -### Underlying XRPL transactor +## Underlying XRPL transactor Builds and submits a single [`MPTokenAuthorize`](https://xrpl.org/docs/references/protocol/transactions/types/mptokenauthorize) transaction, with the unauthorize flag set. diff --git a/docs/simpleXRPL/references/verticals/token/unlock.md b/docs/simpleXRPL/references/verticals/token/unlock.md index b6b4daa7..c23c7556 100644 --- a/docs/simpleXRPL/references/verticals/token/unlock.md +++ b/docs/simpleXRPL/references/verticals/token/unlock.md @@ -21,24 +21,24 @@ token.unlock( ): Promise`. {% raw-partial file="/docs/_snippets/simplexrpl-response-fields.md" /%} -#### Response values +### Return fields For `Token.unlock`, the `intent` carries: @@ -47,7 +47,7 @@ For `Token.unlock`, the `intent` carries: | `mptIssuanceId` | `string` | The MPT issuance id that was unlocked. | | `locked` | `boolean` | The resulting lock state (`false`). | -### Underlying XRPL transactor +## Underlying XRPL transactor Builds and submits a single [`MPTokenIssuanceSet`](https://xrpl.org/docs/references/protocol/transactions/types/mptokenissuanceset) transaction with the unlock flag set. diff --git a/docs/simpleXRPL/references/verticals/xrp/transfer.md b/docs/simpleXRPL/references/verticals/xrp/transfer.md index 268d3a4c..8b074d64 100644 --- a/docs/simpleXRPL/references/verticals/xrp/transfer.md +++ b/docs/simpleXRPL/references/verticals/xrp/transfer.md @@ -21,24 +21,24 @@ xrp.transfer( ): Promise> ``` -### Parameters +## Parameters | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `to` | `string` | Yes | Destination r-address. | | `amount` | `string` | Yes | Amount to send, as a decimal string in XRP (e.g. `'10'`, `'0.25'`). | -### Options +## Options {% raw-partial file="/docs/_snippets/simplexrpl-write-options.md" /%} -### Response +## Returns Resolves to a `SubmissionResult`. {% raw-partial file="/docs/_snippets/simplexrpl-response-fields.md" /%} -#### Response values +### Return fields For `XRP.transfer`, the `intent` (`XrpTransferIntent`) carries: @@ -47,7 +47,7 @@ For `XRP.transfer`, the `intent` (`XrpTransferIntent`) carries: | `to` | `string` | Destination r-address. | | `amount` | `string` | Amount sent, in XRP. | -### Underlying XRPL transactor +## Underlying XRPL transactor Builds and submits a single [`Payment`](https://xrpl.org/docs/references/protocol/transactions/types/payment) transaction. From e9065b17d88ac9e0e27f6b0cf354b73504bda1cc Mon Sep 17 00:00:00 2001 From: Oliver Eggert Date: Thu, 23 Jul 2026 20:22:20 -0700 Subject: [PATCH 08/24] remove monospace formatting from links --- docs/simpleXRPL/get-started.md | 2 +- .../references/verticals/account/activate.md | 6 +++--- .../references/verticals/account/create.md | 2 +- .../references/verticals/account/depositPreauth.md | 2 +- docs/simpleXRPL/references/verticals/account/fund.md | 6 +++--- .../references/verticals/account/listOffers.md | 4 ++-- .../references/verticals/account/retrieve.md | 2 +- docs/simpleXRPL/references/verticals/account/set.md | 2 +- .../references/verticals/account/setRegularKey.md | 2 +- .../references/verticals/credential/accept.md | 2 +- .../references/verticals/credential/delete.md | 2 +- .../references/verticals/credential/issue.md | 2 +- .../references/verticals/credential/list.md | 4 ++-- .../references/verticals/credential/retrieve.md | 2 +- .../simpleXRPL/references/verticals/domain/create.md | 2 +- .../simpleXRPL/references/verticals/domain/delete.md | 2 +- docs/simpleXRPL/references/verticals/domain/list.md | 4 ++-- .../references/verticals/domain/retrieve.md | 2 +- .../references/verticals/domain/setCredentials.md | 2 +- .../simpleXRPL/references/verticals/iou/authorize.md | 4 ++-- docs/simpleXRPL/references/verticals/iou/buyOffer.md | 2 +- .../references/verticals/iou/cancelOffer.md | 2 +- docs/simpleXRPL/references/verticals/iou/clawback.md | 2 +- docs/simpleXRPL/references/verticals/iou/issue.md | 6 +++--- docs/simpleXRPL/references/verticals/iou/list.md | 4 ++-- .../references/verticals/iou/listOffers.md | 6 +++--- docs/simpleXRPL/references/verticals/iou/lock.md | 4 ++-- docs/simpleXRPL/references/verticals/iou/retrieve.md | 2 +- .../simpleXRPL/references/verticals/iou/sellOffer.md | 2 +- docs/simpleXRPL/references/verticals/iou/transfer.md | 2 +- docs/simpleXRPL/references/verticals/iou/unlock.md | 4 ++-- .../references/verticals/token/authorize.md | 2 +- .../references/verticals/token/cancelOffer.md | 2 +- .../references/verticals/token/createOffer.md | 2 +- .../simpleXRPL/references/verticals/token/destroy.md | 2 +- .../references/verticals/token/grantHolder.md | 2 +- docs/simpleXRPL/references/verticals/token/issue.md | 2 +- docs/simpleXRPL/references/verticals/token/list.md | 4 ++-- .../references/verticals/token/listOffers.md | 2 +- docs/simpleXRPL/references/verticals/token/lock.md | 2 +- .../references/verticals/token/retrieve.md | 2 +- .../references/verticals/token/revokeHolder.md | 2 +- .../references/verticals/token/transfer.md | 2 +- .../references/verticals/token/unauthorize.md | 2 +- docs/simpleXRPL/references/verticals/token/unlock.md | 2 +- docs/simpleXRPL/references/verticals/xrp/transfer.md | 2 +- .../tutorials/create-permissioned-domain.md | 10 +++++----- .../tutorials/cross-custodian-workflows.md | 4 ++-- docs/simpleXRPL/tutorials/external-signer.md | 4 ++-- .../simpleXRPL/tutorials/implement-aws-kms-signer.md | 2 +- docs/simpleXRPL/tutorials/implement-pkcs11-signer.md | 4 ++-- .../simpleXRPL/tutorials/issue-and-distribute-iou.md | 10 +++++----- docs/simpleXRPL/tutorials/issue-rwa-as-mpt.md | 4 ++-- docs/simpleXRPL/tutorials/place-dex-order.md | 12 ++++++------ 54 files changed, 87 insertions(+), 87 deletions(-) diff --git a/docs/simpleXRPL/get-started.md b/docs/simpleXRPL/get-started.md index 7b818bc2..c3227bca 100644 --- a/docs/simpleXRPL/get-started.md +++ b/docs/simpleXRPL/get-started.md @@ -88,7 +88,7 @@ Operations are grouped into domain-specific **verticals** — `xrp`, `token`, `i Every write resolves to a `SubmissionResult` carrying the transaction hash, the backend's raw response, and a typed `intent` output. See [Results and handles](references/index.md#results-and-handles). {% admonition type="success" name="Tip" %} -On a test network, create and fund an account first with [`account.create()`](references/verticals/account/create.md) and [`account.fund()`](references/verticals/account/fund.md), then use its address as the source or destination. +On a test network, create and fund an account first with [account.create()](references/verticals/account/create.md) and [account.fund()](references/verticals/account/fund.md), then use its address as the source or destination. {% /admonition %} ## Next steps diff --git a/docs/simpleXRPL/references/verticals/account/activate.md b/docs/simpleXRPL/references/verticals/account/activate.md index 411ef0cb..acb0d1c4 100644 --- a/docs/simpleXRPL/references/verticals/account/activate.md +++ b/docs/simpleXRPL/references/verticals/account/activate.md @@ -10,7 +10,7 @@ labels: [Source](https://github.com/ripple/simpleXRPL/blob/50619258cf753008e8a185eaeb3ceca489e5998a/src/verticals/account.ts#L151) -Activate a created account by sending it XRP from the operator (primary) account, then enabling rippling. This is the any-network counterpart to [`fund`](fund.md); the account must be signable by this client (e.g. from [`create`](create.md)). +Activate a created account by sending it XRP from the operator (primary) account, then enabling rippling. This is the any-network counterpart to [fund](fund.md); the account must be signable by this client (e.g. from [create](create.md)). ## Signature @@ -46,8 +46,8 @@ Resolves to a `SubmissionResult` (from the `defaultRipple` settings c Runs as an ordered, multi-step sequence: -1. [`Payment`](https://xrpl.org/docs/references/protocol/transactions/types/payment) — the operator sends XRP to the destination. -2. [`AccountSet`](https://xrpl.org/docs/references/protocol/transactions/types/accountset) — the new account enables rippling (`defaultRipple`). +1. [Payment](https://xrpl.org/docs/references/protocol/transactions/types/payment) — the operator sends XRP to the destination. +2. [AccountSet](https://xrpl.org/docs/references/protocol/transactions/types/accountset) — the new account enables rippling (`defaultRipple`). ## Example diff --git a/docs/simpleXRPL/references/verticals/account/create.md b/docs/simpleXRPL/references/verticals/account/create.md index 2d7990f0..f15722b6 100644 --- a/docs/simpleXRPL/references/verticals/account/create.md +++ b/docs/simpleXRPL/references/verticals/account/create.md @@ -41,7 +41,7 @@ Returns an `AccountCredentials` object **synchronously** — this is the one `Ac ## Underlying XRPL transactor -None. `Account.create` generates a keypair locally and writes nothing to the ledger. Use [`activate`](activate.md) or [`fund`](fund.md) to bring the account on-ledger. +None. `Account.create` generates a keypair locally and writes nothing to the ledger. Use [activate](activate.md) or [fund](fund.md) to bring the account on-ledger. ## Example diff --git a/docs/simpleXRPL/references/verticals/account/depositPreauth.md b/docs/simpleXRPL/references/verticals/account/depositPreauth.md index 15dbfe77..b36ffd15 100644 --- a/docs/simpleXRPL/references/verticals/account/depositPreauth.md +++ b/docs/simpleXRPL/references/verticals/account/depositPreauth.md @@ -44,7 +44,7 @@ Resolves to a `SubmissionResult`. ## Underlying XRPL transactor -Builds and submits a single [`DepositPreauth`](https://xrpl.org/docs/references/protocol/transactions/types/depositpreauth) transaction. +Builds and submits a single [DepositPreauth](https://xrpl.org/docs/references/protocol/transactions/types/depositpreauth) transaction. ## Example diff --git a/docs/simpleXRPL/references/verticals/account/fund.md b/docs/simpleXRPL/references/verticals/account/fund.md index 95834230..53dc2499 100644 --- a/docs/simpleXRPL/references/verticals/account/fund.md +++ b/docs/simpleXRPL/references/verticals/account/fund.md @@ -10,10 +10,10 @@ labels: [Source](https://github.com/ripple/simpleXRPL/blob/50619258cf753008e8a185eaeb3ceca489e5998a/src/verticals/account.ts#L124) -Fund a created account via the network faucet (testnet/devnet), then enable rippling. The account must be one this client can sign for (e.g. from [`create`](create.md)). +Fund a created account via the network faucet (testnet/devnet), then enable rippling. The account must be one this client can sign for (e.g. from [create](create.md)). {% admonition type="info" name="Note" %} -`fund` requires a faucet-capable ledger (testnet/devnet). On other networks it throws — use [`activate`](activate.md) to fund from an operator account instead. +`fund` requires a faucet-capable ledger (testnet/devnet). On other networks it throws — use [activate](activate.md) to fund from an operator account instead. {% /admonition %} ## Signature @@ -47,7 +47,7 @@ Resolves to a `SubmissionResult` (from the `defaultRipple` settings c ## Underlying XRPL transactor -Funds the account via the network faucet (an off-ledger request, not a submitted transaction), then builds and submits a single [`AccountSet`](https://xrpl.org/docs/references/protocol/transactions/types/accountset) transaction to enable rippling (`defaultRipple`). +Funds the account via the network faucet (an off-ledger request, not a submitted transaction), then builds and submits a single [AccountSet](https://xrpl.org/docs/references/protocol/transactions/types/accountset) transaction to enable rippling (`defaultRipple`). ## Example diff --git a/docs/simpleXRPL/references/verticals/account/listOffers.md b/docs/simpleXRPL/references/verticals/account/listOffers.md index e91fabfb..5d3d63e0 100644 --- a/docs/simpleXRPL/references/verticals/account/listOffers.md +++ b/docs/simpleXRPL/references/verticals/account/listOffers.md @@ -32,11 +32,11 @@ Resolves to a `ListOffersResult`: | Field | Type | Description | | --- | --- | --- | -| `data` | `readonly OfferSummary[]` | The shaped open offers. See [`token.listOffers`](../token/listOffers.md#offersummary) for `OfferSummary`. | +| `data` | `readonly OfferSummary[]` | The shaped open offers. See [token.listOffers](../token/listOffers.md#offersummary) for `OfferSummary`. | ## Underlying XRPL request -Read-only — no signer is required and nothing is submitted. Queries the ledger with [`account_offers`](https://xrpl.org/docs/references/http-websocket-apis/public-api-methods/account-methods/account_offers). +Read-only — no signer is required and nothing is submitted. Queries the ledger with [account_offers](https://xrpl.org/docs/references/http-websocket-apis/public-api-methods/account-methods/account_offers). ## Example diff --git a/docs/simpleXRPL/references/verticals/account/retrieve.md b/docs/simpleXRPL/references/verticals/account/retrieve.md index bbf15710..963bc61c 100644 --- a/docs/simpleXRPL/references/verticals/account/retrieve.md +++ b/docs/simpleXRPL/references/verticals/account/retrieve.md @@ -46,7 +46,7 @@ Resolves to an `AccountRetrieveResult`: ## Underlying XRPL request -Read-only — no signer is required and nothing is submitted. Queries the ledger with [`account_info`](https://xrpl.org/docs/references/http-websocket-apis/public-api-methods/account-methods/account_info) (flags are resolved via `account_flags`). +Read-only — no signer is required and nothing is submitted. Queries the ledger with [account_info](https://xrpl.org/docs/references/http-websocket-apis/public-api-methods/account-methods/account_info) (flags are resolved via `account_flags`). ## Example diff --git a/docs/simpleXRPL/references/verticals/account/set.md b/docs/simpleXRPL/references/verticals/account/set.md index bc745ff8..29853595 100644 --- a/docs/simpleXRPL/references/verticals/account/set.md +++ b/docs/simpleXRPL/references/verticals/account/set.md @@ -60,7 +60,7 @@ Resolves to a `SubmissionResult`. ## Underlying XRPL transactor -Builds and submits a single [`AccountSet`](https://xrpl.org/docs/references/protocol/transactions/types/accountset) transaction. +Builds and submits a single [AccountSet](https://xrpl.org/docs/references/protocol/transactions/types/accountset) transaction. ## Example diff --git a/docs/simpleXRPL/references/verticals/account/setRegularKey.md b/docs/simpleXRPL/references/verticals/account/setRegularKey.md index 1c18d6da..cc883d06 100644 --- a/docs/simpleXRPL/references/verticals/account/setRegularKey.md +++ b/docs/simpleXRPL/references/verticals/account/setRegularKey.md @@ -43,7 +43,7 @@ Resolves to a `SubmissionResult`. ## Underlying XRPL transactor -Builds and submits a single [`SetRegularKey`](https://xrpl.org/docs/references/protocol/transactions/types/setregularkey) transaction. +Builds and submits a single [SetRegularKey](https://xrpl.org/docs/references/protocol/transactions/types/setregularkey) transaction. ## Example diff --git a/docs/simpleXRPL/references/verticals/credential/accept.md b/docs/simpleXRPL/references/verticals/credential/accept.md index ef91cb64..b001a7d2 100644 --- a/docs/simpleXRPL/references/verticals/credential/accept.md +++ b/docs/simpleXRPL/references/verticals/credential/accept.md @@ -49,7 +49,7 @@ For `Credential.accept`, the `intent` echoes: ## Underlying XRPL transactor -Builds and submits a single [`CredentialAccept`](https://xrpl.org/docs/references/protocol/transactions/types/credentialaccept) transaction. +Builds and submits a single [CredentialAccept](https://xrpl.org/docs/references/protocol/transactions/types/credentialaccept) transaction. ## Example diff --git a/docs/simpleXRPL/references/verticals/credential/delete.md b/docs/simpleXRPL/references/verticals/credential/delete.md index 4cd248a2..12179694 100644 --- a/docs/simpleXRPL/references/verticals/credential/delete.md +++ b/docs/simpleXRPL/references/verticals/credential/delete.md @@ -49,7 +49,7 @@ For `Credential.delete`, the `intent` echoes: ## Underlying XRPL transactor -Builds and submits a single [`CredentialDelete`](https://xrpl.org/docs/references/protocol/transactions/types/credentialdelete) transaction. +Builds and submits a single [CredentialDelete](https://xrpl.org/docs/references/protocol/transactions/types/credentialdelete) transaction. ## Example diff --git a/docs/simpleXRPL/references/verticals/credential/issue.md b/docs/simpleXRPL/references/verticals/credential/issue.md index 4976e883..3bbc89d0 100644 --- a/docs/simpleXRPL/references/verticals/credential/issue.md +++ b/docs/simpleXRPL/references/verticals/credential/issue.md @@ -51,7 +51,7 @@ For `Credential.issue`, the `intent` echoes: ## Underlying XRPL transactor -Builds and submits a single [`CredentialCreate`](https://xrpl.org/docs/references/protocol/transactions/types/credentialcreate) transaction. +Builds and submits a single [CredentialCreate](https://xrpl.org/docs/references/protocol/transactions/types/credentialcreate) transaction. ## Example diff --git a/docs/simpleXRPL/references/verticals/credential/list.md b/docs/simpleXRPL/references/verticals/credential/list.md index c5fb76d4..9009c65a 100644 --- a/docs/simpleXRPL/references/verticals/credential/list.md +++ b/docs/simpleXRPL/references/verticals/credential/list.md @@ -34,11 +34,11 @@ Resolves to a `CredentialListResult`, where `credentials[i]` corresponds to `dat | Field | Type | Description | | --- | --- | --- | | `credentials` | `readonly CredentialRef[]` | The identifier of each credential (`credType`, `issuer`, `holder`). | -| `data` | `readonly CredentialData[]` | The shaped credentials. See [`credential.retrieve`](retrieve.md#credentialdata) for `CredentialData`. | +| `data` | `readonly CredentialData[]` | The shaped credentials. See [credential.retrieve](retrieve.md#credentialdata) for `CredentialData`. | ## Underlying XRPL request -Read-only — no signer is required and nothing is submitted. Queries the ledger with [`account_objects`](https://xrpl.org/docs/references/http-websocket-apis/public-api-methods/account-methods/account_objects). +Read-only — no signer is required and nothing is submitted. Queries the ledger with [account_objects](https://xrpl.org/docs/references/http-websocket-apis/public-api-methods/account-methods/account_objects). ## Example diff --git a/docs/simpleXRPL/references/verticals/credential/retrieve.md b/docs/simpleXRPL/references/verticals/credential/retrieve.md index fef5d41a..736755d2 100644 --- a/docs/simpleXRPL/references/verticals/credential/retrieve.md +++ b/docs/simpleXRPL/references/verticals/credential/retrieve.md @@ -52,7 +52,7 @@ Resolves to a `CredentialRetrieveResult`: ## Underlying XRPL request -Read-only — no signer is required and nothing is submitted. Queries the ledger with [`ledger_entry`](https://xrpl.org/docs/references/http-websocket-apis/public-api-methods/ledger-methods/ledger_entry). +Read-only — no signer is required and nothing is submitted. Queries the ledger with [ledger_entry](https://xrpl.org/docs/references/http-websocket-apis/public-api-methods/ledger-methods/ledger_entry). ## Example diff --git a/docs/simpleXRPL/references/verticals/domain/create.md b/docs/simpleXRPL/references/verticals/domain/create.md index f1f23aed..55f38293 100644 --- a/docs/simpleXRPL/references/verticals/domain/create.md +++ b/docs/simpleXRPL/references/verticals/domain/create.md @@ -54,7 +54,7 @@ For `Domain.create`, the `intent` (`DomainIntent`) carries: ## Underlying XRPL transactor -Builds and submits a single [`PermissionedDomainSet`](https://xrpl.org/docs/references/protocol/transactions/types/permissioneddomainset) transaction (with no domain id, creating a new domain). +Builds and submits a single [PermissionedDomainSet](https://xrpl.org/docs/references/protocol/transactions/types/permissioneddomainset) transaction (with no domain id, creating a new domain). ## Example diff --git a/docs/simpleXRPL/references/verticals/domain/delete.md b/docs/simpleXRPL/references/verticals/domain/delete.md index 88f903a7..8e0f1a84 100644 --- a/docs/simpleXRPL/references/verticals/domain/delete.md +++ b/docs/simpleXRPL/references/verticals/domain/delete.md @@ -47,7 +47,7 @@ For `Domain.delete`, the `intent` (`DomainIntent`) echoes: ## Underlying XRPL transactor -Builds and submits a single [`PermissionedDomainDelete`](https://xrpl.org/docs/references/protocol/transactions/types/permissioneddomaindelete) transaction. +Builds and submits a single [PermissionedDomainDelete](https://xrpl.org/docs/references/protocol/transactions/types/permissioneddomaindelete) transaction. ## Example diff --git a/docs/simpleXRPL/references/verticals/domain/list.md b/docs/simpleXRPL/references/verticals/domain/list.md index cfec58f7..89992c65 100644 --- a/docs/simpleXRPL/references/verticals/domain/list.md +++ b/docs/simpleXRPL/references/verticals/domain/list.md @@ -33,11 +33,11 @@ Resolves to a `DomainListResult`, where `domains[i]` corresponds to `data[i]`: | Field | Type | Description | | --- | --- | --- | | `domains` | `readonly string[]` | The domain id of each owned domain. | -| `data` | `readonly DomainData[]` | The shaped domains. See [`domain.retrieve`](retrieve.md#domaindata) for `DomainData`. | +| `data` | `readonly DomainData[]` | The shaped domains. See [domain.retrieve](retrieve.md#domaindata) for `DomainData`. | ## Underlying XRPL request -Read-only — no signer is required and nothing is submitted. Queries the ledger with [`account_objects`](https://xrpl.org/docs/references/http-websocket-apis/public-api-methods/account-methods/account_objects). +Read-only — no signer is required and nothing is submitted. Queries the ledger with [account_objects](https://xrpl.org/docs/references/http-websocket-apis/public-api-methods/account-methods/account_objects). ## Example diff --git a/docs/simpleXRPL/references/verticals/domain/retrieve.md b/docs/simpleXRPL/references/verticals/domain/retrieve.md index 3ae1796e..12a5116e 100644 --- a/docs/simpleXRPL/references/verticals/domain/retrieve.md +++ b/docs/simpleXRPL/references/verticals/domain/retrieve.md @@ -45,7 +45,7 @@ Resolves to a `DomainRetrieveResult`: ## Underlying XRPL request -Read-only — no signer is required and nothing is submitted. Queries the ledger with [`ledger_entry`](https://xrpl.org/docs/references/http-websocket-apis/public-api-methods/ledger-methods/ledger_entry). +Read-only — no signer is required and nothing is submitted. Queries the ledger with [ledger_entry](https://xrpl.org/docs/references/http-websocket-apis/public-api-methods/ledger-methods/ledger_entry). ## Example diff --git a/docs/simpleXRPL/references/verticals/domain/setCredentials.md b/docs/simpleXRPL/references/verticals/domain/setCredentials.md index 8f14e89b..a2df984b 100644 --- a/docs/simpleXRPL/references/verticals/domain/setCredentials.md +++ b/docs/simpleXRPL/references/verticals/domain/setCredentials.md @@ -55,7 +55,7 @@ For `Domain.setCredentials`, the `intent` (`DomainIntent`) echoes: ## Underlying XRPL transactor -Builds and submits a single [`PermissionedDomainSet`](https://xrpl.org/docs/references/protocol/transactions/types/permissioneddomainset) transaction naming the existing domain id. +Builds and submits a single [PermissionedDomainSet](https://xrpl.org/docs/references/protocol/transactions/types/permissioneddomainset) transaction naming the existing domain id. ## Example diff --git a/docs/simpleXRPL/references/verticals/iou/authorize.md b/docs/simpleXRPL/references/verticals/iou/authorize.md index d741599c..a3ebdaec 100644 --- a/docs/simpleXRPL/references/verticals/iou/authorize.md +++ b/docs/simpleXRPL/references/verticals/iou/authorize.md @@ -13,7 +13,7 @@ labels: Grant authorization for a holder to hold this IOU. Only meaningful when the issuer's account has `asfRequireAuth` set. {% admonition type="info" name="Note" %} -There is no matching `unauthorize`: the underlying authorize flag is one-way and cannot be cleared once set. To reversibly block a trust line, use [`IOU.lock`](lock.md) instead. +There is no matching `unauthorize`: the underlying authorize flag is one-way and cannot be cleared once set. To reversibly block a trust line, use [IOU.lock](lock.md) instead. {% /admonition %} ## Signature @@ -52,7 +52,7 @@ For `IOU.authorize`, the `intent` (`IOUAuthorizeIntent`) echoes: ## Underlying XRPL transactor -Builds and submits a single [`TrustSet`](https://xrpl.org/docs/references/protocol/transactions/types/trustset) transaction with the authorize flag set. +Builds and submits a single [TrustSet](https://xrpl.org/docs/references/protocol/transactions/types/trustset) transaction with the authorize flag set. ## Example diff --git a/docs/simpleXRPL/references/verticals/iou/buyOffer.md b/docs/simpleXRPL/references/verticals/iou/buyOffer.md index 5abe3c4d..d8eb43cf 100644 --- a/docs/simpleXRPL/references/verticals/iou/buyOffer.md +++ b/docs/simpleXRPL/references/verticals/iou/buyOffer.md @@ -57,7 +57,7 @@ Resolves to a `SubmissionResult`. ## Underlying XRPL transactor -Builds and submits a single [`OfferCreate`](https://xrpl.org/docs/references/protocol/transactions/types/offercreate) transaction. Throws an `IntentValidationError` if `price` is MPT-denominated. +Builds and submits a single [OfferCreate](https://xrpl.org/docs/references/protocol/transactions/types/offercreate) transaction. Throws an `IntentValidationError` if `price` is MPT-denominated. ## Example diff --git a/docs/simpleXRPL/references/verticals/iou/cancelOffer.md b/docs/simpleXRPL/references/verticals/iou/cancelOffer.md index f2aae789..29de669c 100644 --- a/docs/simpleXRPL/references/verticals/iou/cancelOffer.md +++ b/docs/simpleXRPL/references/verticals/iou/cancelOffer.md @@ -47,7 +47,7 @@ For `IOU.cancelOffer`, the `intent` echoes: ## Underlying XRPL transactor -Builds and submits a single [`OfferCancel`](https://xrpl.org/docs/references/protocol/transactions/types/offercancel) transaction. +Builds and submits a single [OfferCancel](https://xrpl.org/docs/references/protocol/transactions/types/offercancel) transaction. ## Example diff --git a/docs/simpleXRPL/references/verticals/iou/clawback.md b/docs/simpleXRPL/references/verticals/iou/clawback.md index 09f2dd63..f8dc3ebf 100644 --- a/docs/simpleXRPL/references/verticals/iou/clawback.md +++ b/docs/simpleXRPL/references/verticals/iou/clawback.md @@ -54,7 +54,7 @@ For `IOU.clawback`, the `intent` (`IOUClawbackIntent`) echoes: ## Underlying XRPL transactor -Builds and submits a single [`Clawback`](https://xrpl.org/docs/references/protocol/transactions/types/clawback) transaction. +Builds and submits a single [Clawback](https://xrpl.org/docs/references/protocol/transactions/types/clawback) transaction. ## Example diff --git a/docs/simpleXRPL/references/verticals/iou/issue.md b/docs/simpleXRPL/references/verticals/iou/issue.md index 723edaf9..e7411db9 100644 --- a/docs/simpleXRPL/references/verticals/iou/issue.md +++ b/docs/simpleXRPL/references/verticals/iou/issue.md @@ -13,7 +13,7 @@ labels: Generate a new trust line-based IOU between two developer-controlled accounts sourced from the environment. {% admonition type="info" name="Note" %} -Unlike the other IOU verbs, `issue` takes no `options`. It bootstraps both accounts from the environment: it reads `XRPL_ISSUER_SEED` and `XRPL_HOT_WALLET_SEED`, has the issuer enable rippling, then has the hot wallet extend trust up to the maximum limit. No `Payment` runs, so no value exists yet — use [`IOU.transfer`](transfer.md) to send some. +Unlike the other IOU verbs, `issue` takes no `options`. It bootstraps both accounts from the environment: it reads `XRPL_ISSUER_SEED` and `XRPL_HOT_WALLET_SEED`, has the issuer enable rippling, then has the hot wallet extend trust up to the maximum limit. No `Payment` runs, so no value exists yet — use [IOU.transfer](transfer.md) to send some. {% /admonition %} ## Signature @@ -48,8 +48,8 @@ For `IOU.issue`, the `intent` (`IOUIssueIntent`) carries: Runs as an ordered, multi-step sequence (no rollback on partial failure): -1. [`AccountSet`](https://xrpl.org/docs/references/protocol/transactions/types/accountset) — the issuer enables rippling (`defaultRipple`). -2. [`TrustSet`](https://xrpl.org/docs/references/protocol/transactions/types/trustset) — the hot wallet extends trust to the issuer, up to the maximum limit. +1. [AccountSet](https://xrpl.org/docs/references/protocol/transactions/types/accountset) — the issuer enables rippling (`defaultRipple`). +2. [TrustSet](https://xrpl.org/docs/references/protocol/transactions/types/trustset) — the hot wallet extends trust to the issuer, up to the maximum limit. Throws an `IntentValidationError` if the required seeds aren't set, or a `MultiStepFailureError` if either step fails. diff --git a/docs/simpleXRPL/references/verticals/iou/list.md b/docs/simpleXRPL/references/verticals/iou/list.md index b6942a89..34632036 100644 --- a/docs/simpleXRPL/references/verticals/iou/list.md +++ b/docs/simpleXRPL/references/verticals/iou/list.md @@ -34,11 +34,11 @@ Resolves to an `IOUListResult`, where `ious[i]` corresponds to `data[i]`: | Field | Type | Description | | --- | --- | --- | | `ious` | `readonly string[]` | The `iouID` of each line, composable into the write verbs. | -| `data` | `readonly IOUTrustLine[]` | The shaped trust lines. See [`iou.retrieve`](retrieve.md#ioutrustline) for `IOUTrustLine`. | +| `data` | `readonly IOUTrustLine[]` | The shaped trust lines. See [iou.retrieve](retrieve.md#ioutrustline) for `IOUTrustLine`. | ## Underlying XRPL request -Read-only — no signer is required and nothing is submitted. Queries the ledger with [`account_lines`](https://xrpl.org/docs/references/http-websocket-apis/public-api-methods/account-methods/account_lines). +Read-only — no signer is required and nothing is submitted. Queries the ledger with [account_lines](https://xrpl.org/docs/references/http-websocket-apis/public-api-methods/account-methods/account_lines). ## Example diff --git a/docs/simpleXRPL/references/verticals/iou/listOffers.md b/docs/simpleXRPL/references/verticals/iou/listOffers.md index b59befeb..fff19577 100644 --- a/docs/simpleXRPL/references/verticals/iou/listOffers.md +++ b/docs/simpleXRPL/references/verticals/iou/listOffers.md @@ -13,7 +13,7 @@ labels: List all open offers in the market for this IOU (both sides), tagged buy/sell relative to it. {% admonition type="info" name="Note" %} -Unlike [`token.listOffers`](../token/listOffers.md) and [`account.listOffers`](../account/listOffers.md) — which list a single **account's own** resting offers — `iou.listOffers` reads the whole **order book** for the IOU across all accounts. +Unlike [token.listOffers](../token/listOffers.md) and [account.listOffers](../account/listOffers.md) — which list a single **account's own** resting offers — `iou.listOffers` reads the whole **order book** for the IOU across all accounts. {% /admonition %} ## Signature @@ -37,11 +37,11 @@ Resolves to a `ListOffersResult`: | Field | Type | Description | | --- | --- | --- | -| `data` | `readonly OfferSummary[]` | The shaped open offers, tagged buy/sell relative to the IOU. See [`token.listOffers`](../token/listOffers.md#offersummary) for `OfferSummary`. | +| `data` | `readonly OfferSummary[]` | The shaped open offers, tagged buy/sell relative to the IOU. See [token.listOffers](../token/listOffers.md#offersummary) for `OfferSummary`. | ## Underlying XRPL request -Read-only — no signer is required and nothing is submitted. Queries both sides of the order book with [`book_offers`](https://xrpl.org/docs/references/http-websocket-apis/public-api-methods/path-and-order-book-methods/book_offers). +Read-only — no signer is required and nothing is submitted. Queries both sides of the order book with [book_offers](https://xrpl.org/docs/references/http-websocket-apis/public-api-methods/path-and-order-book-methods/book_offers). ## Example diff --git a/docs/simpleXRPL/references/verticals/iou/lock.md b/docs/simpleXRPL/references/verticals/iou/lock.md index 255fcd1c..d3ae351c 100644 --- a/docs/simpleXRPL/references/verticals/iou/lock.md +++ b/docs/simpleXRPL/references/verticals/iou/lock.md @@ -50,8 +50,8 @@ For `IOU.lock`, the `intent` (`IOULockIntent`) echoes: Runs as an ordered, multi-step sequence (no rollback on partial failure): -1. [`TrustSet`](https://xrpl.org/docs/references/protocol/transactions/types/trustset) — sets the individual freeze. -2. [`TrustSet`](https://xrpl.org/docs/references/protocol/transactions/types/trustset) — sets the deep freeze. +1. [TrustSet](https://xrpl.org/docs/references/protocol/transactions/types/trustset) — sets the individual freeze. +2. [TrustSet](https://xrpl.org/docs/references/protocol/transactions/types/trustset) — sets the deep freeze. Throws a `MultiStepFailureError` if either step fails. diff --git a/docs/simpleXRPL/references/verticals/iou/retrieve.md b/docs/simpleXRPL/references/verticals/iou/retrieve.md index 8680af7b..5f5c291d 100644 --- a/docs/simpleXRPL/references/verticals/iou/retrieve.md +++ b/docs/simpleXRPL/references/verticals/iou/retrieve.md @@ -52,7 +52,7 @@ Resolves to an `IOURetrieveResult`: ## Underlying XRPL request -Read-only — no signer is required and nothing is submitted. Queries the ledger with [`account_lines`](https://xrpl.org/docs/references/http-websocket-apis/public-api-methods/account-methods/account_lines). +Read-only — no signer is required and nothing is submitted. Queries the ledger with [account_lines](https://xrpl.org/docs/references/http-websocket-apis/public-api-methods/account-methods/account_lines). ## Example diff --git a/docs/simpleXRPL/references/verticals/iou/sellOffer.md b/docs/simpleXRPL/references/verticals/iou/sellOffer.md index a8bd220c..591668d4 100644 --- a/docs/simpleXRPL/references/verticals/iou/sellOffer.md +++ b/docs/simpleXRPL/references/verticals/iou/sellOffer.md @@ -57,7 +57,7 @@ Resolves to a `SubmissionResult`. ## Underlying XRPL transactor -Builds and submits a single [`OfferCreate`](https://xrpl.org/docs/references/protocol/transactions/types/offercreate) transaction. Throws an `IntentValidationError` if `price` is MPT-denominated. +Builds and submits a single [OfferCreate](https://xrpl.org/docs/references/protocol/transactions/types/offercreate) transaction. Throws an `IntentValidationError` if `price` is MPT-denominated. ## Example diff --git a/docs/simpleXRPL/references/verticals/iou/transfer.md b/docs/simpleXRPL/references/verticals/iou/transfer.md index bf7776cd..821bdebb 100644 --- a/docs/simpleXRPL/references/verticals/iou/transfer.md +++ b/docs/simpleXRPL/references/verticals/iou/transfer.md @@ -50,7 +50,7 @@ For `IOU.transfer`, the `intent` (`IOUTransferIntent`) echoes: ## Underlying XRPL transactor -Builds and submits a single [`Payment`](https://xrpl.org/docs/references/protocol/transactions/types/payment) transaction. +Builds and submits a single [Payment](https://xrpl.org/docs/references/protocol/transactions/types/payment) transaction. ## Example diff --git a/docs/simpleXRPL/references/verticals/iou/unlock.md b/docs/simpleXRPL/references/verticals/iou/unlock.md index 86b70e18..a3925fd6 100644 --- a/docs/simpleXRPL/references/verticals/iou/unlock.md +++ b/docs/simpleXRPL/references/verticals/iou/unlock.md @@ -50,8 +50,8 @@ For `IOU.unlock`, the `intent` (`IOULockIntent`) echoes: Runs as an ordered, multi-step sequence (no rollback on partial failure): -1. [`TrustSet`](https://xrpl.org/docs/references/protocol/transactions/types/trustset) — clears the deep freeze. -2. [`TrustSet`](https://xrpl.org/docs/references/protocol/transactions/types/trustset) — clears the individual freeze. +1. [TrustSet](https://xrpl.org/docs/references/protocol/transactions/types/trustset) — clears the deep freeze. +2. [TrustSet](https://xrpl.org/docs/references/protocol/transactions/types/trustset) — clears the individual freeze. Throws a `MultiStepFailureError` if either step fails. diff --git a/docs/simpleXRPL/references/verticals/token/authorize.md b/docs/simpleXRPL/references/verticals/token/authorize.md index d6a7754d..766e5bcf 100644 --- a/docs/simpleXRPL/references/verticals/token/authorize.md +++ b/docs/simpleXRPL/references/verticals/token/authorize.md @@ -47,7 +47,7 @@ For `Token.authorize`, the `intent` echoes: ## Underlying XRPL transactor -Builds and submits a single [`MPTokenAuthorize`](https://xrpl.org/docs/references/protocol/transactions/types/mptokenauthorize) transaction. +Builds and submits a single [MPTokenAuthorize](https://xrpl.org/docs/references/protocol/transactions/types/mptokenauthorize) transaction. ## Example diff --git a/docs/simpleXRPL/references/verticals/token/cancelOffer.md b/docs/simpleXRPL/references/verticals/token/cancelOffer.md index 5e22237c..9b81c989 100644 --- a/docs/simpleXRPL/references/verticals/token/cancelOffer.md +++ b/docs/simpleXRPL/references/verticals/token/cancelOffer.md @@ -47,7 +47,7 @@ For `Token.cancelOffer`, the `intent` echoes: ## Underlying XRPL transactor -Builds and submits a single [`OfferCancel`](https://xrpl.org/docs/references/protocol/transactions/types/offercancel) transaction. +Builds and submits a single [OfferCancel](https://xrpl.org/docs/references/protocol/transactions/types/offercancel) transaction. ## Example diff --git a/docs/simpleXRPL/references/verticals/token/createOffer.md b/docs/simpleXRPL/references/verticals/token/createOffer.md index ce169d85..2a01e163 100644 --- a/docs/simpleXRPL/references/verticals/token/createOffer.md +++ b/docs/simpleXRPL/references/verticals/token/createOffer.md @@ -56,7 +56,7 @@ Resolves to a `SubmissionResult`. ## Underlying XRPL transactor -Builds and submits a single [`OfferCreate`](https://xrpl.org/docs/references/protocol/transactions/types/offercreate) transaction. Throws an `IntentValidationError` if either amount is an MPT. +Builds and submits a single [OfferCreate](https://xrpl.org/docs/references/protocol/transactions/types/offercreate) transaction. Throws an `IntentValidationError` if either amount is an MPT. ## Example diff --git a/docs/simpleXRPL/references/verticals/token/destroy.md b/docs/simpleXRPL/references/verticals/token/destroy.md index 5b030194..f9b00e6a 100644 --- a/docs/simpleXRPL/references/verticals/token/destroy.md +++ b/docs/simpleXRPL/references/verticals/token/destroy.md @@ -47,7 +47,7 @@ For `Token.destroy`, the `intent` echoes: ## Underlying XRPL transactor -Builds and submits a single [`MPTokenIssuanceDestroy`](https://xrpl.org/docs/references/protocol/transactions/types/mptokenissuancedestroy) transaction. +Builds and submits a single [MPTokenIssuanceDestroy](https://xrpl.org/docs/references/protocol/transactions/types/mptokenissuancedestroy) transaction. ## Example diff --git a/docs/simpleXRPL/references/verticals/token/grantHolder.md b/docs/simpleXRPL/references/verticals/token/grantHolder.md index 73473b1e..56ec8c0e 100644 --- a/docs/simpleXRPL/references/verticals/token/grantHolder.md +++ b/docs/simpleXRPL/references/verticals/token/grantHolder.md @@ -48,7 +48,7 @@ For `Token.grantHolder`, the `intent` echoes: ## Underlying XRPL transactor -Builds and submits a single [`MPTokenAuthorize`](https://xrpl.org/docs/references/protocol/transactions/types/mptokenauthorize) transaction naming the holder. +Builds and submits a single [MPTokenAuthorize](https://xrpl.org/docs/references/protocol/transactions/types/mptokenauthorize) transaction naming the holder. ## Example diff --git a/docs/simpleXRPL/references/verticals/token/issue.md b/docs/simpleXRPL/references/verticals/token/issue.md index 8376ffb9..5a5784d0 100644 --- a/docs/simpleXRPL/references/verticals/token/issue.md +++ b/docs/simpleXRPL/references/verticals/token/issue.md @@ -66,7 +66,7 @@ For `Token.issue`, the `intent` (`MptIssueIntent`) carries: ## Underlying XRPL transactor -Builds and submits a single [`MPTokenIssuanceCreate`](https://xrpl.org/docs/references/protocol/transactions/types/mptokenissuancecreate) transaction. +Builds and submits a single [MPTokenIssuanceCreate](https://xrpl.org/docs/references/protocol/transactions/types/mptokenissuancecreate) transaction. ## Example diff --git a/docs/simpleXRPL/references/verticals/token/list.md b/docs/simpleXRPL/references/verticals/token/list.md index bc8fc529..0b19f2f6 100644 --- a/docs/simpleXRPL/references/verticals/token/list.md +++ b/docs/simpleXRPL/references/verticals/token/list.md @@ -42,11 +42,11 @@ Resolves to a `TokenListResult`, where `tokens[i]` corresponds to `data[i]`: | --- | --- | --- | | `tokenID` | `string` | The MPT issuance id. | | `balance` | `string` _(optional)_ | The account's balance (present for `role: 'holder'`). | -| `issuance` | `TokenData` _(optional)_ | The full issuance snapshot (present for `role: 'issuer'`). See [`token.retrieve`](retrieve.md#tokendata) for `TokenData`. | +| `issuance` | `TokenData` _(optional)_ | The full issuance snapshot (present for `role: 'issuer'`). See [token.retrieve](retrieve.md#tokendata) for `TokenData`. | ## Underlying XRPL request -Read-only — no signer is required and nothing is submitted. Queries the ledger with [`account_objects`](https://xrpl.org/docs/references/http-websocket-apis/public-api-methods/account-methods/account_objects). +Read-only — no signer is required and nothing is submitted. Queries the ledger with [account_objects](https://xrpl.org/docs/references/http-websocket-apis/public-api-methods/account-methods/account_objects). ## Example diff --git a/docs/simpleXRPL/references/verticals/token/listOffers.md b/docs/simpleXRPL/references/verticals/token/listOffers.md index e55bffc6..a8672fd2 100644 --- a/docs/simpleXRPL/references/verticals/token/listOffers.md +++ b/docs/simpleXRPL/references/verticals/token/listOffers.md @@ -48,7 +48,7 @@ Each offer mirrors the `createOffer` / `buyOffer` / `sellOffer` input format, so ## Underlying XRPL request -Read-only — no signer is required and nothing is submitted. Queries the ledger with [`account_offers`](https://xrpl.org/docs/references/http-websocket-apis/public-api-methods/account-methods/account_offers). +Read-only — no signer is required and nothing is submitted. Queries the ledger with [account_offers](https://xrpl.org/docs/references/http-websocket-apis/public-api-methods/account-methods/account_offers). ## Example diff --git a/docs/simpleXRPL/references/verticals/token/lock.md b/docs/simpleXRPL/references/verticals/token/lock.md index ee1e0201..99c66ca4 100644 --- a/docs/simpleXRPL/references/verticals/token/lock.md +++ b/docs/simpleXRPL/references/verticals/token/lock.md @@ -49,7 +49,7 @@ For `Token.lock`, the `intent` carries: ## Underlying XRPL transactor -Builds and submits a single [`MPTokenIssuanceSet`](https://xrpl.org/docs/references/protocol/transactions/types/mptokenissuanceset) transaction with the lock flag set. +Builds and submits a single [MPTokenIssuanceSet](https://xrpl.org/docs/references/protocol/transactions/types/mptokenissuanceset) transaction with the lock flag set. ## Example diff --git a/docs/simpleXRPL/references/verticals/token/retrieve.md b/docs/simpleXRPL/references/verticals/token/retrieve.md index 34483abe..f7478d33 100644 --- a/docs/simpleXRPL/references/verticals/token/retrieve.md +++ b/docs/simpleXRPL/references/verticals/token/retrieve.md @@ -50,7 +50,7 @@ Resolves to a `TokenRetrieveResult`: ## Underlying XRPL request -Read-only — no signer is required and nothing is submitted. Queries the ledger with [`ledger_entry`](https://xrpl.org/docs/references/http-websocket-apis/public-api-methods/ledger-methods/ledger_entry). +Read-only — no signer is required and nothing is submitted. Queries the ledger with [ledger_entry](https://xrpl.org/docs/references/http-websocket-apis/public-api-methods/ledger-methods/ledger_entry). ## Example diff --git a/docs/simpleXRPL/references/verticals/token/revokeHolder.md b/docs/simpleXRPL/references/verticals/token/revokeHolder.md index 9e910fff..40ec1491 100644 --- a/docs/simpleXRPL/references/verticals/token/revokeHolder.md +++ b/docs/simpleXRPL/references/verticals/token/revokeHolder.md @@ -48,7 +48,7 @@ For `Token.revokeHolder`, the `intent` echoes: ## Underlying XRPL transactor -Builds and submits a single [`MPTokenAuthorize`](https://xrpl.org/docs/references/protocol/transactions/types/mptokenauthorize) transaction naming the holder, with the unauthorize flag set. +Builds and submits a single [MPTokenAuthorize](https://xrpl.org/docs/references/protocol/transactions/types/mptokenauthorize) transaction naming the holder, with the unauthorize flag set. ## Example diff --git a/docs/simpleXRPL/references/verticals/token/transfer.md b/docs/simpleXRPL/references/verticals/token/transfer.md index ffc4462c..ce40d6e7 100644 --- a/docs/simpleXRPL/references/verticals/token/transfer.md +++ b/docs/simpleXRPL/references/verticals/token/transfer.md @@ -49,7 +49,7 @@ For `Token.transfer`, the `intent` echoes: ## Underlying XRPL transactor -Builds and submits a single [`Payment`](https://xrpl.org/docs/references/protocol/transactions/types/payment) transaction. Throws an `IntentValidationError` if `amount`'s asset is not an MPT — use [`XRP.transfer`](../xrp/transfer.md) for XRP. +Builds and submits a single [Payment](https://xrpl.org/docs/references/protocol/transactions/types/payment) transaction. Throws an `IntentValidationError` if `amount`'s asset is not an MPT — use [XRP.transfer](../xrp/transfer.md) for XRP. ## Example diff --git a/docs/simpleXRPL/references/verticals/token/unauthorize.md b/docs/simpleXRPL/references/verticals/token/unauthorize.md index cf754ff1..aea8af36 100644 --- a/docs/simpleXRPL/references/verticals/token/unauthorize.md +++ b/docs/simpleXRPL/references/verticals/token/unauthorize.md @@ -47,7 +47,7 @@ For `Token.unauthorize`, the `intent` echoes: ## Underlying XRPL transactor -Builds and submits a single [`MPTokenAuthorize`](https://xrpl.org/docs/references/protocol/transactions/types/mptokenauthorize) transaction, with the unauthorize flag set. +Builds and submits a single [MPTokenAuthorize](https://xrpl.org/docs/references/protocol/transactions/types/mptokenauthorize) transaction, with the unauthorize flag set. ## Example diff --git a/docs/simpleXRPL/references/verticals/token/unlock.md b/docs/simpleXRPL/references/verticals/token/unlock.md index c23c7556..d28a81fd 100644 --- a/docs/simpleXRPL/references/verticals/token/unlock.md +++ b/docs/simpleXRPL/references/verticals/token/unlock.md @@ -49,7 +49,7 @@ For `Token.unlock`, the `intent` carries: ## Underlying XRPL transactor -Builds and submits a single [`MPTokenIssuanceSet`](https://xrpl.org/docs/references/protocol/transactions/types/mptokenissuanceset) transaction with the unlock flag set. +Builds and submits a single [MPTokenIssuanceSet](https://xrpl.org/docs/references/protocol/transactions/types/mptokenissuanceset) transaction with the unlock flag set. ## Example diff --git a/docs/simpleXRPL/references/verticals/xrp/transfer.md b/docs/simpleXRPL/references/verticals/xrp/transfer.md index 8b074d64..239ee2f8 100644 --- a/docs/simpleXRPL/references/verticals/xrp/transfer.md +++ b/docs/simpleXRPL/references/verticals/xrp/transfer.md @@ -49,7 +49,7 @@ For `XRP.transfer`, the `intent` (`XrpTransferIntent`) carries: ## Underlying XRPL transactor -Builds and submits a single [`Payment`](https://xrpl.org/docs/references/protocol/transactions/types/payment) transaction. +Builds and submits a single [Payment](https://xrpl.org/docs/references/protocol/transactions/types/payment) transaction. ## Example diff --git a/docs/simpleXRPL/tutorials/create-permissioned-domain.md b/docs/simpleXRPL/tutorials/create-permissioned-domain.md index 8a1a9a11..3de6e28b 100644 --- a/docs/simpleXRPL/tutorials/create-permissioned-domain.md +++ b/docs/simpleXRPL/tutorials/create-permissioned-domain.md @@ -68,8 +68,8 @@ await client.disconnect() ## See Also -- [`domain.create()`](../references/verticals/domain/create.md) -- [`domain.setCredentials()`](../references/verticals/domain/setCredentials.md) -- [`domain.retrieve()`](../references/verticals/domain/retrieve.md) -- [`domain.list()`](../references/verticals/domain/list.md) -- [`iou.sellOffer()`](../references/verticals/iou/sellOffer.md) +- [domain.create()](../references/verticals/domain/create.md) +- [domain.setCredentials()](../references/verticals/domain/setCredentials.md) +- [domain.retrieve()](../references/verticals/domain/retrieve.md) +- [domain.list()](../references/verticals/domain/list.md) +- [iou.sellOffer()](../references/verticals/iou/sellOffer.md) diff --git a/docs/simpleXRPL/tutorials/cross-custodian-workflows.md b/docs/simpleXRPL/tutorials/cross-custodian-workflows.md index 99a46815..3a1a7919 100644 --- a/docs/simpleXRPL/tutorials/cross-custodian-workflows.md +++ b/docs/simpleXRPL/tutorials/cross-custodian-workflows.md @@ -91,5 +91,5 @@ await client.disconnect() ## See Also -- [`iou.issue()`](../references/verticals/iou/issue.md) -- [`xrp.transfer()`](../references/verticals/xrp/transfer.md) +- [iou.issue()](../references/verticals/iou/issue.md) +- [xrp.transfer()](../references/verticals/xrp/transfer.md) diff --git a/docs/simpleXRPL/tutorials/external-signer.md b/docs/simpleXRPL/tutorials/external-signer.md index a96b8b68..291265cd 100644 --- a/docs/simpleXRPL/tutorials/external-signer.md +++ b/docs/simpleXRPL/tutorials/external-signer.md @@ -115,5 +115,5 @@ await signAndSubmit( ## See Also -- [`account.create()`](../references/verticals/account/create.md) -- [`xrp.transfer()`](../references/verticals/xrp/transfer.md) +- [account.create()](../references/verticals/account/create.md) +- [xrp.transfer()](../references/verticals/xrp/transfer.md) diff --git a/docs/simpleXRPL/tutorials/implement-aws-kms-signer.md b/docs/simpleXRPL/tutorials/implement-aws-kms-signer.md index e10761b2..12d63324 100644 --- a/docs/simpleXRPL/tutorials/implement-aws-kms-signer.md +++ b/docs/simpleXRPL/tutorials/implement-aws-kms-signer.md @@ -50,4 +50,4 @@ await client.disconnect() ## See Also -- [`xrp.transfer()`](../references/verticals/xrp/transfer.md) +- [xrp.transfer()](../references/verticals/xrp/transfer.md) diff --git a/docs/simpleXRPL/tutorials/implement-pkcs11-signer.md b/docs/simpleXRPL/tutorials/implement-pkcs11-signer.md index 95447318..141baaaa 100644 --- a/docs/simpleXRPL/tutorials/implement-pkcs11-signer.md +++ b/docs/simpleXRPL/tutorials/implement-pkcs11-signer.md @@ -147,5 +147,5 @@ await client.disconnect() ## See Also -- [`account.create()`](../references/verticals/account/create.md) -- [`xrp.transfer()`](../references/verticals/xrp/transfer.md) +- [account.create()](../references/verticals/account/create.md) +- [xrp.transfer()](../references/verticals/xrp/transfer.md) diff --git a/docs/simpleXRPL/tutorials/issue-and-distribute-iou.md b/docs/simpleXRPL/tutorials/issue-and-distribute-iou.md index a020822b..01593b72 100644 --- a/docs/simpleXRPL/tutorials/issue-and-distribute-iou.md +++ b/docs/simpleXRPL/tutorials/issue-and-distribute-iou.md @@ -71,8 +71,8 @@ await client.disconnect() ## See Also -- [`iou.issue()`](../references/verticals/iou/issue.md) -- [`iou.transfer()`](../references/verticals/iou/transfer.md) -- [`iou.authorize()`](../references/verticals/iou/authorize.md) -- [`iou.retrieve()`](../references/verticals/iou/retrieve.md) -- [`iou.list()`](../references/verticals/iou/list.md) +- [iou.issue()](../references/verticals/iou/issue.md) +- [iou.transfer()](../references/verticals/iou/transfer.md) +- [iou.authorize()](../references/verticals/iou/authorize.md) +- [iou.retrieve()](../references/verticals/iou/retrieve.md) +- [iou.list()](../references/verticals/iou/list.md) diff --git a/docs/simpleXRPL/tutorials/issue-rwa-as-mpt.md b/docs/simpleXRPL/tutorials/issue-rwa-as-mpt.md index 61179377..f9405785 100644 --- a/docs/simpleXRPL/tutorials/issue-rwa-as-mpt.md +++ b/docs/simpleXRPL/tutorials/issue-rwa-as-mpt.md @@ -74,5 +74,5 @@ await client.disconnect() ## See Also -- [`token.issue()`](../references/verticals/token/issue.md) -- [`token.retrieve()`](../references/verticals/token/retrieve.md) +- [token.issue()](../references/verticals/token/issue.md) +- [token.retrieve()](../references/verticals/token/retrieve.md) diff --git a/docs/simpleXRPL/tutorials/place-dex-order.md b/docs/simpleXRPL/tutorials/place-dex-order.md index 50d24f86..f1cb90d9 100644 --- a/docs/simpleXRPL/tutorials/place-dex-order.md +++ b/docs/simpleXRPL/tutorials/place-dex-order.md @@ -82,9 +82,9 @@ await client.disconnect() ## See Also -- [`iou.buyOffer()`](../references/verticals/iou/buyOffer.md) -- [`iou.sellOffer()`](../references/verticals/iou/sellOffer.md) -- [`iou.cancelOffer()`](../references/verticals/iou/cancelOffer.md) -- [`iou.listOffers()`](../references/verticals/iou/listOffers.md) -- [`token.createOffer()`](../references/verticals/token/createOffer.md) -- [`account.listOffers()`](../references/verticals/account/listOffers.md) +- [iou.buyOffer()](../references/verticals/iou/buyOffer.md) +- [iou.sellOffer()](../references/verticals/iou/sellOffer.md) +- [iou.cancelOffer()](../references/verticals/iou/cancelOffer.md) +- [iou.listOffers()](../references/verticals/iou/listOffers.md) +- [token.createOffer()](../references/verticals/token/createOffer.md) +- [account.listOffers()](../references/verticals/account/listOffers.md) From 803aebeca80d9bc63b540922992f0cd54f5a5fef Mon Sep 17 00:00:00 2001 From: Oliver Eggert Date: Fri, 24 Jul 2026 12:02:52 -0700 Subject: [PATCH 09/24] update get started --- _code-samples/simplexrpl/getStarted.ts | 105 +++++-------------------- docs/simpleXRPL/get-started.md | 64 ++++++--------- 2 files changed, 42 insertions(+), 127 deletions(-) diff --git a/_code-samples/simplexrpl/getStarted.ts b/_code-samples/simplexrpl/getStarted.ts index 4c73d42f..3fd05a8a 100644 --- a/_code-samples/simplexrpl/getStarted.ts +++ b/_code-samples/simplexrpl/getStarted.ts @@ -1,109 +1,40 @@ -/** - * simpleXRPL — Get Started walkthrough. Config is read from the environment - * (never hard-code keys); endpoints target the XRPL Testnet. - */ -import { - dispatch, - isNativePath, - LocalSigner, - PalisadeCustody, - RippleCustody, - SignerCapabilityError, - SimpleXRPL, -} from 'simplexrpl' -import type { Custodian, SubmissionPath, TransactorType } from 'simplexrpl' +// This Get Started sample walks through the basics of using simpleXRPL. + +import { LocalSigner, SimpleXRPL } from 'simplexrpl' + +// --- Construct a connector --- +// The LocalSigner constructor is a self-custody option that signs locally. +// Intended for testing and development. +const signer = LocalSigner.fromEnv() // --- Initialize the client --- -// `SimpleXRPL.init(...)` is the only entry point — it binds already-authenticated -// connectors to a network and builds the account index. A single local signer -// (seeds from `XRPL_*_SEED`) is enough to run against the Testnet today. const client = await SimpleXRPL.init({ - // Point at a rippled endpoint. `faucetUrl` is only used on test networks - // (by `client.account.fund`). rippledUrl: 'wss://s.altnet.rippletest.net:51233', faucetUrl: 'https://faucet.altnet.rippletest.net/accounts', - signers: [LocalSigner.fromEnv()], - // `primarySigner` is the default backend for verbs called without an explicit - // account; it defaults to `signers[0]`, so it's optional with a single signer. + signers: [signer], }) // --- Discover your accounts --- // Connectors discover their accounts at init; the client merges them into one -// index keyed by r-address. +// index keyed by XRPL address. for (const [address, account] of client.accounts) { - console.log(address, '→', account.signer.kind) + console.log(`${address}: ${account.signer.kind}`) } -// Resolve the account a verb would act on (no argument → the primary account). +// Get the primary account used to submit vertical operations. +// No args returns the primary account. const primary = client.resolveAccount() -console.log('primary:', primary.address) +console.log(`primary: ${primary.address}`) -// Read an account's on-chain state — a read, so no signer is required. +// Read an account's on-chain state. No args retrieves the primary account. const state = await client.account.retrieve() -console.log('balance (XRP):', state.data.xrpBalance, '| sequence:', state.data.sequence) - -// --- Check how operations route --- -// Before submitting, ask how each transactor would route for an account: signed -// locally, a custodian's native operation, the raw sign-only fallback, or rejected. -const TRANSACTORS: TransactorType[] = [ - 'Payment', - 'TrustSet', - 'OfferCreate', - 'MPTokenIssuanceCreate', - 'CredentialCreate', - 'PermissionedDomainSet', -] -for (const transactor of TRANSACTORS) { - let path: SubmissionPath | 'rejected' = 'rejected' - try { - path = dispatch(primary, transactor) - } catch (error) { - // `dispatch` throws when the connector can neither natively nor raw-sign it. - if (!(error instanceof SignerCapabilityError)) throw error - } - const via = - path === 'rejected' - ? '(unsupported)' - : isNativePath(path) - ? '(custodian network)' - : '(shared ledger)' - console.log(`${transactor.padEnd(24)} → ${path} ${via}`) -} +console.log(`balance (XRP): ${state.data.xrpBalance} | sequence: ${state.data.sequence}`) -// --- Send a payment --- -// Verbs use the primary account by default; target another bound account with `from`. +// --- Send an XRP transfer --- const result = await client.xrp.transfer({ to: 'rDestination00000000000000000000000', amount: '10', }) -console.log('submitted:', result.txHash) +console.log(`submitted: ${result.txHash}`) await client.disconnect() - -// --- Connect a custodian (production) --- -// For production, construct each custodian connector on its own and pass them to -// `SimpleXRPL.init`'s `signers` in place of (or alongside) the local signer above, -// e.g. `signers: await connectCustodians(), primarySigner: /* your custodian */`. -export async function connectCustodians(): Promise { - // Palisade — OAuth client credentials, acting on a specific vault/wallet. - const palisade = await PalisadeCustody.create({ - baseUrl: 'https://api.sandbox.palisade.co', - clientId: process.env.PALISADE_CLIENT_ID ?? '', - clientSecret: process.env.PALISADE_CLIENT_SECRET ?? '', - primary: { - vaultId: process.env.PALISADE_VAULT_ID ?? '', - walletId: process.env.PALISADE_WALLET_ID ?? '', - }, - // Enable the raw sign-only fallback for transactors Palisade has no native - // operation for. Off by default. - allowRawSigning: false, - }) - - // Ripple Custody — an intent-author key exchanged for a token; one Custody - // domain. `fromEnv` reads the `RIPPLE_CUSTODY_*` variables. - const rippleCustody = await RippleCustody.fromEnv({ - primary: process.env.RIPPLE_CUSTODY_PRIMARY ?? '', - }) - - return [palisade, rippleCustody, LocalSigner.fromEnv()] -} diff --git a/docs/simpleXRPL/get-started.md b/docs/simpleXRPL/get-started.md index c3227bca..cbc742c0 100644 --- a/docs/simpleXRPL/get-started.md +++ b/docs/simpleXRPL/get-started.md @@ -1,6 +1,6 @@ --- seo: - description: Install simpleXRPL, initialize the client, connect a custodian, discover your accounts, check routing, and send your first XRP Ledger payment. + description: Install simpleXRPL, construct a connector, initialize the client, discover your accounts, and send your first XRP Ledger payment. labels: - simpleXRPL - SDK @@ -15,10 +15,9 @@ This tutorial takes you through the basics of sending your first operation on th By the end of this tutorial, you will be able to: +- Construct a connector. - Initialize a client. -- Connect a custodian. - Discover your accounts. -- Check how an operation will route before you submit it. - Transfer XRP between accounts. @@ -32,7 +31,7 @@ To complete this tutorial, you should: ## Source Code -You can find the complete source code for this tutorial's examples in the [code samples section of this website's repository](https://github.com/ripple/opensource.ripple.com/tree/main/_code-samples/simplexrpl/getStarted.ts) +You can find the complete source code for this tutorial's examples in the [code samples section of this website's repository](https://github.com/ripple/opensource.ripple.com/tree/main/_code-samples/simplexrpl/) ## Steps @@ -43,56 +42,41 @@ You can find the complete source code for this tutorial's examples in the [code npm install simplexrpl ``` -### 2. Initialize the client +### 2. Construct a connector -`SimpleXRPL.init(...)` is the single entry point — you never construct the client with `new`. It binds one or more already-authenticated signing backends (the **connectors**) to a network and builds the account index. +A connector is a signing backend that determines how operations are executed and signed. This guide uses local signing with a `LocalSigner` constructor. This self-custody connector manages accounts and signs locally, making it ideal for testing and development. -{% code-snippet file="/_code-samples/simplexrpl/getStarted.ts" language="ts" before="// --- Discover your accounts ---" /%} +{% code-snippet file="/_code-samples/simplexrpl/getStarted.ts" language="ts" before="// --- Initialize the client ---" /%} -- **`primarySigner`** is the default backend for verbs called without an explicit account. It defaults to `signers[0]`, so you only set it when you bind more than one connector. -- With **no `signers`**, the client is read-only: reads work, but write verbs throw `NoSignerError` until a signer is added. -- Bind an account at runtime (for example, a freshly created wallet) with `client.registerLocalAccount(seed)`. +For production you'd construct a custodian connector instead and pass it to `init` in place of (or alongside) the local one. See [Connectors](./references/connectors/index.md) for how to build each one; every vertical operation then works the same regardless of which connector owns the account. -See [Client and initialization](references/index.md#client-and-initialization) for the full configuration reference. +### 3. Initialize the client -### 3. Connect a custodian +Initializing an account binds connectors to a network and builds the account index. -The local signer above is enough for development. For production, construct a custodian connector and pass it to `init`'s `signers` — in place of, or alongside, the local one. simpleXRPL ships **Ripple Custody** and **Palisade**, each constructed and authenticated on its own: +{% code-snippet file="/_code-samples/simplexrpl/getStarted.ts" language="ts" from="// --- Initialize the client ---" before="// --- Discover your accounts ---" /%} -{% code-snippet file="/_code-samples/simplexrpl/getStarted.ts" language="ts" from="// --- Connect a custodian (production) ---" /%} - -Read credentials from your environment or secrets manager — never hard-code keys. Once bound, every vertical verb works the same regardless of which connector owns the account: the SDK routes each write to the custodian that holds it. - -{% admonition type="info" name="Note" %} -Whether an operation runs through a custodian's **native** path or the **raw-signing fallback** is decided per operation; the fallback is off by default and enabled per connector via `allowRawSigning`. See [Operation Execution](index.md#operation-execution) and the [Connector Routing](references/connectors/connector-routing.md) table. -{% /admonition %} +- `signers[0]` is the default *primary* account used for operations if not specified. +- If you don't set a `signer`, the client is read-only and you will receive a `NoSignerError` when attempting write operations. ### 4. Discover your accounts -Connectors discover their accounts at init; the client merges them into a single index keyed by r-address. List them, resolve the primary, and read on-chain state — a read needs no signer: - -{% code-snippet file="/_code-samples/simplexrpl/getStarted.ts" language="ts" from="// --- Discover your accounts ---" before="// --- Check how operations route ---" /%} - -### 5. Check how operations route - -Before you submit, ask how a given transactor would route for an account — signed locally, through a custodian's native operation, via the raw sign-only fallback, or rejected: - -{% code-snippet file="/_code-samples/simplexrpl/getStarted.ts" language="ts" from="// --- Check how operations route ---" before="// --- Send a payment ---" /%} +Connectors discover their accounts at initialization, and the client merges them into a single index keyed by XRPL account address. List them, resolve the primary, and read on-chain state. -### 6. Send a payment +{% code-snippet file="/_code-samples/simplexrpl/getStarted.ts" language="ts" from="// --- Discover your accounts ---" before="// --- Send an XRP transfer ---" /%} -Operations are grouped into domain-specific **verticals** — `xrp`, `token`, `iou`, `credential`, `domain`, and `account` — reached off the client. Each verb uses the primary account by default; target a different bound account with `from`. Here's a native XRP payment: +### 5. Transfer XRP -{% code-snippet file="/_code-samples/simplexrpl/getStarted.ts" language="ts" from="// --- Send a payment ---" before="// --- Connect a custodian (production) ---" /%} +Operations are grouped into domain-specific verticals reached off the client. This guide sends XRP from the primary address to another. For a full list of vertical operations, see: [Verticals](./references/verticals/index.md). -Every write resolves to a `SubmissionResult` carrying the transaction hash, the backend's raw response, and a typed `intent` output. See [Results and handles](references/index.md#results-and-handles). +{% code-snippet file="/_code-samples/simplexrpl/getStarted.ts" language="ts" from="// --- Send an XRP transfer ---" /%} -{% admonition type="success" name="Tip" %} -On a test network, create and fund an account first with [account.create()](references/verticals/account/create.md) and [account.fund()](references/verticals/account/fund.md), then use its address as the source or destination. -{% /admonition %} -## Next steps +## See Also -- **Tutorials** — end-to-end workflows: [Issue an RWA as an MPT](tutorials/issue-rwa-as-mpt.md), [Issue and distribute an IOU](tutorials/issue-and-distribute-iou.md), [Place a DEX order](tutorials/place-dex-order.md), and more. -- **Reference** — every vertical, method, connector, and type: [Reference](references/index.md). -- **Concepts** — what simpleXRPL is and why: [What is simpleXRPL](index.md). +- **References**: + - [LocalSigner.fromEnv()](./references/connectors/local.md#localsignerfromenv) + - [SimpleXRPL.init()](./references/index.md#client-and-initialization) + - [account.retrieve()](./references/verticals/account/retrieve.md) + - [xrp.transfer()](./references/verticals/xrp/transfer.md) + \ No newline at end of file From 8da9406941a05dd5f73984bf1ab4c16a5eeb2d7d Mon Sep 17 00:00:00 2001 From: oeggert <117319296+oeggert@users.noreply.github.com> Date: Mon, 27 Jul 2026 11:49:43 -0700 Subject: [PATCH 10/24] Update docs/simpleXRPL/get-started.md Co-authored-by: Maria Shodunke --- docs/simpleXRPL/get-started.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/simpleXRPL/get-started.md b/docs/simpleXRPL/get-started.md index cbc742c0..979bde61 100644 --- a/docs/simpleXRPL/get-started.md +++ b/docs/simpleXRPL/get-started.md @@ -8,7 +8,7 @@ labels: # Get Started -This tutorial takes you through the basics of sending your first operation on the XRP Ledger with simpleXRPL. +This tutorial takes you through the basics of sending your first operation on the XRP Ledger with **simpleXRPL**. ## Goals From 1f2ecb37b8169102df5c7d357e9bbad488b8b609 Mon Sep 17 00:00:00 2001 From: oeggert <117319296+oeggert@users.noreply.github.com> Date: Mon, 27 Jul 2026 11:49:59 -0700 Subject: [PATCH 11/24] Update docs/simpleXRPL/index.md Co-authored-by: Maria Shodunke --- docs/simpleXRPL/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/simpleXRPL/index.md b/docs/simpleXRPL/index.md index fb6db527..bdfa0173 100644 --- a/docs/simpleXRPL/index.md +++ b/docs/simpleXRPL/index.md @@ -9,7 +9,7 @@ labels: # simpleXRPL [Source](https://github.com/ripple/simpleXRPL) -The `simpleXRPL` is an opinionated TypeScript SDK for the XRP Ledger, built for institutional developers who interact with the ledger through a custodian. It raises the level of your code from XRPL protocol mechanics to business operations that the SDK routes through your institutional custodians. Concretely, this means: +`simpleXRPL` is an opinionated TypeScript SDK for the XRP Ledger, built for institutional developers who interact with the ledger through a custodian. It raises the level of your code from XRPL protocol mechanics to business operations that the SDK routes through your institutional custodians. Concretely, this means: - `simpleXRPL` defines the shape of business operations, handling the underlying XRPL transactions and custodian API calls. - Your code doesn't change even if you switch custodians or operate across several at once. From acb62d321a226c720f7201adacb6c3209d4c14f6 Mon Sep 17 00:00:00 2001 From: oeggert <117319296+oeggert@users.noreply.github.com> Date: Mon, 27 Jul 2026 11:54:43 -0700 Subject: [PATCH 12/24] Update docs/simpleXRPL/index.md Co-authored-by: Maria Shodunke --- docs/simpleXRPL/index.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/simpleXRPL/index.md b/docs/simpleXRPL/index.md index bdfa0173..1f488b83 100644 --- a/docs/simpleXRPL/index.md +++ b/docs/simpleXRPL/index.md @@ -23,9 +23,9 @@ labels: `simpleXRPL` is built around four concepts: -- **Clients**: Establishes the network connection and the connector configuration. Both are immutable for the client's lifetime; to change either, you create a new client. -- **Connectors**: The execution model that determines *how* operations run and *who* holds account keys. Each connector exposes a uniform interface to the rest of the SDK, so the same code runs across all of them. -- **Accounts**: An XRPL [account](https://xrpl.org/docs/concepts/accounts) paired with the connector that signs for it. +- **Clients**: Establish the network connection and the connector configuration. Both are immutable for a client's lifetime; to change either, you create a new client. +- **Connectors**: Make up the execution model that determines *how* operations run and *who* holds account keys. Each connector exposes a uniform interface to the rest of the SDK, so the same code runs across all of them. +- **Accounts**: XRPL [accounts](https://xrpl.org/docs/concepts/accounts), each paired with the connector that signs for it. - **Verticals**: Domain-specific classes and methods that group related business operations. From 9d92240b736163a7f0063ba65a9a6f054b75fd02 Mon Sep 17 00:00:00 2001 From: oeggert <117319296+oeggert@users.noreply.github.com> Date: Mon, 27 Jul 2026 11:55:09 -0700 Subject: [PATCH 13/24] Update docs/simpleXRPL/tutorials/issue-and-distribute-iou.md Co-authored-by: Maria Shodunke --- docs/simpleXRPL/tutorials/issue-and-distribute-iou.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/simpleXRPL/tutorials/issue-and-distribute-iou.md b/docs/simpleXRPL/tutorials/issue-and-distribute-iou.md index 01593b72..df3137d0 100644 --- a/docs/simpleXRPL/tutorials/issue-and-distribute-iou.md +++ b/docs/simpleXRPL/tutorials/issue-and-distribute-iou.md @@ -8,7 +8,7 @@ labels: # Issue And Distribute An IOU -`issue` bootstraps the issuer and a hot wallet from the environment (the issuer enables rippling and the hot wallet extends a trust line); no value exists until `transfer` sends the currency out. Every verb acts as the issuer, selected via `from`. +`issue` bootstraps the issuer and a hot wallet from the environment (the issuer enables rippling and the hot wallet extends a trust line). No value exists until `transfer` sends the currency out. Every verb acts as the issuer, selected via `from`. ```ts /** From 354f7dd357e51bd486c75e6d07eefca8cab3f2d5 Mon Sep 17 00:00:00 2001 From: Oliver Eggert Date: Fri, 24 Jul 2026 12:37:26 -0700 Subject: [PATCH 14/24] type column cleanup --- docs/_snippets/simplexrpl-write-options.md | 4 ++-- docs/simpleXRPL/references/connectors/local.md | 4 ++-- docs/simpleXRPL/references/connectors/palisade.md | 6 +++--- .../references/connectors/ripple-custody.md | 12 ++++++------ 4 files changed, 13 insertions(+), 13 deletions(-) diff --git a/docs/_snippets/simplexrpl-write-options.md b/docs/_snippets/simplexrpl-write-options.md index f66ef400..9bd1b2ce 100644 --- a/docs/_snippets/simplexrpl-write-options.md +++ b/docs/_snippets/simplexrpl-write-options.md @@ -2,6 +2,6 @@ | Option | Type | Required | Description | | --- | --- | --- | --- | -| `from` | `AccountSelector` | No | The account to act as. Defaults to the primary signer's primary account. (For IOU verbs, this is the issuer.) | -| `fee` | `FeeIntent` | No | Fee override. | +| `from` | `AccountSelector` | No | The account to act as — an r-address string, or an object `{ address }` or `{ signer, account? }`. Defaults to the primary signer's primary account. (For IOU verbs, this is the issuer.) | +| `fee` | `FeeIntent` | No | Fee override. Object shape:
`{ priority?: 'low' \| 'medium' \| 'high' }` | | `idempotencyKey` | `string` | No | A prior submission's `idempotencyKey`, to retry to the same intent instead of creating a duplicate. Auto-generated when omitted. | diff --git a/docs/simpleXRPL/references/connectors/local.md b/docs/simpleXRPL/references/connectors/local.md index 3d7b7423..ad67f380 100644 --- a/docs/simpleXRPL/references/connectors/local.md +++ b/docs/simpleXRPL/references/connectors/local.md @@ -27,7 +27,7 @@ LocalSigner.fromEnv(options?: LocalSignerFromEnvOptions): LocalSigner | Field | Type | Required | Description | | --- | --- | --- | --- | | `primary` | `string` | No | The primary account's r-address. Defaults to the first seed in scan order. | -| `env` | `object` | No | Environment source to scan — a map of variable names to values. Defaults to `process.env`. | +| `env` | `Record` | No | Environment source to scan — a map of variable names to values. Defaults to `process.env`. | ## LocalSigner.fromSeed() @@ -61,7 +61,7 @@ LocalSigner.create(options: LocalSignerCreateOptions): LocalSigner | Field | Type | Required | Description | | --- | --- | --- | --- | -| `wallets` | `array` | Yes | The xrpl `Wallet` objects this signer holds (at least one). | +| `wallets` | `readonly Wallet[]` | Yes | The xrpl `Wallet` objects this signer holds (at least one), e.g. `[Wallet.fromSeed(seed)]`. | | `primary` | `string` | No | The primary account's r-address. Defaults to the first wallet. | diff --git a/docs/simpleXRPL/references/connectors/palisade.md b/docs/simpleXRPL/references/connectors/palisade.md index b78d8f50..9de63e51 100644 --- a/docs/simpleXRPL/references/connectors/palisade.md +++ b/docs/simpleXRPL/references/connectors/palisade.md @@ -30,13 +30,13 @@ PalisadeCustody.create(config: PalisadeCustodyConfig): Promise | `baseUrl` | `string` | Yes | Palisade API base URL (must be HTTPS). | | `clientId` | `string` | Yes | OAuth2 client-credentials id. | | `clientSecret` | `string` | Yes | OAuth2 client-credentials secret (held in memory only). | -| `primary` | `object` | Yes | The wallet used when a verb is called without an explicit account. | +| `primary` | `PalisadeWalletRef` | Yes | The wallet used when a verb is called without an explicit account. | | `primary.vaultId` | `string` | Yes | The primary wallet's vault id. | | `primary.walletId` | `string` | Yes | The primary wallet's id. | | `allowRawSigning` | `boolean` | No | Allow the raw fallback for transactors/fields Palisade can't map. Defaults to `false`. | | `defaultTimeoutMs` | `number` | No | How long to wait for a native submission to reach a terminal status. | -| `http` | `object` | No | Advanced: a custom HTTP transport (implements `PalisadeHttpPort`). Defaults to the production fetch port; most callers omit it. | -| `now` | `function` | No | Injectable clock for the auth service, returning epoch ms (`() => number`). Defaults to `Date.now`. | +| `http` | `PalisadeHttpPort` | No | Advanced: a custom HTTP transport, shape `{ send: (request) => Promise }`. Defaults to the production fetch port; most callers omit it. | +| `now` | `() => number` | No | Injectable clock for the auth service, returning epoch ms, e.g. `() => Date.now()`. Defaults to `Date.now`. | ## Example diff --git a/docs/simpleXRPL/references/connectors/ripple-custody.md b/docs/simpleXRPL/references/connectors/ripple-custody.md index 9e9bbdc1..ada73f2a 100644 --- a/docs/simpleXRPL/references/connectors/ripple-custody.md +++ b/docs/simpleXRPL/references/connectors/ripple-custody.md @@ -28,17 +28,17 @@ RippleCustody.create(options: RippleCustodyOptions): Promise | Field | Type | Required | Description | | --- | --- | --- | --- | | `gatewayUrl` | `string` | Yes | The Custody gateway base URL. | -| `auth` | `object` | Yes | Intent-author credentials and token endpoint. | +| `auth` | `RippleCustodyAuthOptions` | Yes | Intent-author credentials and token endpoint. | | `auth.signingKey` | `string` | Yes | Intent-author private key: PEM contents, or a path to a `.pem` file. | | `auth.tokenUrl` | `string` | Yes | The Custody token endpoint URL. | | `auth.publicKey` | `string` | No | Matching public key, base64 SPKI DER. Derived from `signingKey` if omitted. | | `domainId` | `string` | Yes | The Custody domain this custodian operates in. | | `primary` | `string` | Yes | The primary account's r-address; validated against the discovered set. | | `allowRawSigning` | `boolean` | No | Enable the raw-signing fallback. Defaults to `false`. | -| `defaultFee` | `object` | No | Fee tier: `{ priority?: 'low' \| 'medium' \| 'high' }`. Backends that can't honor the tier auto-price and warn. Defaults to `low`. | +| `defaultFee` | `FeeIntent` | No | Fee tier: `{ priority?: 'low' \| 'medium' \| 'high' }`. Backends that can't honor the tier auto-price and warn. Defaults to `low`. | | `defaultDryRun` | `boolean` | No | Pre-flight every write through Custody's dry-run. Defaults to `false`. | | `defaultTimeoutMs` | `number` | No | How long `submitAndWait` polls before throwing `IntentPendingError`. | -| `http` | `object` | No | Advanced: a custom HTTP transport (implements `CustodyHttpPort`). Defaults to the production fetch port; most callers omit it. | +| `http` | `CustodyHttpPort` | No | Advanced: a custom HTTP transport, shape `{ send: (request) => Promise }`. Defaults to the production fetch port; most callers omit it. | ## RippleCustody.fromEnv() @@ -57,11 +57,11 @@ RippleCustody.fromEnv(options: RippleCustodyFromEnvOptions): Promise` | No | The object those variables are read from — a map of names to values. Defaults to `process.env`. | +| `http` | `CustodyHttpPort` | No | Advanced: a custom HTTP transport, shape `{ send: (request) => Promise }`. Defaults to the production fetch port; most callers omit it. | {% admonition type="info" name="Note" %} `env` requires these keys: From 5dd9f992653ecf2e2a5b8156e457e317a362a920 Mon Sep 17 00:00:00 2001 From: Oliver Eggert Date: Mon, 27 Jul 2026 12:24:49 -0700 Subject: [PATCH 15/24] add reviewer suggestions --- docs/simpleXRPL/references/connectors/connector-routing.md | 2 +- docs/simpleXRPL/references/connectors/local.md | 4 ++-- docs/simpleXRPL/references/connectors/palisade.md | 4 ++-- docs/simpleXRPL/references/connectors/ripple-custody.md | 6 +++--- docs/simpleXRPL/references/index.md | 2 +- docs/simpleXRPL/references/verticals/account/activate.md | 4 ++-- docs/simpleXRPL/references/verticals/account/create.md | 6 +++--- .../references/verticals/account/depositPreauth.md | 2 +- docs/simpleXRPL/references/verticals/account/fund.md | 6 +++--- docs/simpleXRPL/references/verticals/account/listOffers.md | 2 +- docs/simpleXRPL/references/verticals/account/retrieve.md | 2 +- docs/simpleXRPL/references/verticals/account/set.md | 4 ++-- .../references/verticals/account/setRegularKey.md | 2 +- docs/simpleXRPL/references/verticals/credential/accept.md | 4 ++-- docs/simpleXRPL/references/verticals/credential/delete.md | 4 ++-- docs/simpleXRPL/references/verticals/credential/issue.md | 4 ++-- docs/simpleXRPL/references/verticals/credential/list.md | 2 +- docs/simpleXRPL/references/verticals/credential/retrieve.md | 2 +- docs/simpleXRPL/references/verticals/domain/create.md | 2 +- docs/simpleXRPL/references/verticals/domain/delete.md | 2 +- docs/simpleXRPL/references/verticals/domain/list.md | 2 +- docs/simpleXRPL/references/verticals/domain/retrieve.md | 2 +- .../references/verticals/domain/setCredentials.md | 2 +- docs/simpleXRPL/references/verticals/iou/authorize.md | 2 +- docs/simpleXRPL/references/verticals/iou/buyOffer.md | 2 +- docs/simpleXRPL/references/verticals/iou/cancelOffer.md | 4 ++-- docs/simpleXRPL/references/verticals/iou/clawback.md | 4 ++-- docs/simpleXRPL/references/verticals/iou/issue.md | 6 +++--- docs/simpleXRPL/references/verticals/iou/list.md | 2 +- docs/simpleXRPL/references/verticals/iou/listOffers.md | 2 +- docs/simpleXRPL/references/verticals/iou/lock.md | 2 +- docs/simpleXRPL/references/verticals/iou/retrieve.md | 2 +- docs/simpleXRPL/references/verticals/iou/sellOffer.md | 2 +- docs/simpleXRPL/references/verticals/iou/transfer.md | 2 +- docs/simpleXRPL/references/verticals/iou/unlock.md | 2 +- docs/simpleXRPL/references/verticals/token/authorize.md | 2 +- docs/simpleXRPL/references/verticals/token/cancelOffer.md | 2 +- docs/simpleXRPL/references/verticals/token/createOffer.md | 2 +- docs/simpleXRPL/references/verticals/token/destroy.md | 2 +- docs/simpleXRPL/references/verticals/token/grantHolder.md | 4 ++-- docs/simpleXRPL/references/verticals/token/issue.md | 4 ++-- docs/simpleXRPL/references/verticals/token/list.md | 6 +++--- docs/simpleXRPL/references/verticals/token/listOffers.md | 2 +- docs/simpleXRPL/references/verticals/token/lock.md | 4 ++-- docs/simpleXRPL/references/verticals/token/retrieve.md | 2 +- docs/simpleXRPL/references/verticals/token/revokeHolder.md | 4 ++-- docs/simpleXRPL/references/verticals/token/transfer.md | 4 ++-- docs/simpleXRPL/references/verticals/token/unauthorize.md | 4 ++-- docs/simpleXRPL/references/verticals/token/unlock.md | 4 ++-- docs/simpleXRPL/references/verticals/xrp/transfer.md | 4 ++-- docs/simpleXRPL/tutorials/implement-aws-kms-signer.md | 2 +- 51 files changed, 78 insertions(+), 78 deletions(-) diff --git a/docs/simpleXRPL/references/connectors/connector-routing.md b/docs/simpleXRPL/references/connectors/connector-routing.md index 3c93fb8f..97efab34 100644 --- a/docs/simpleXRPL/references/connectors/connector-routing.md +++ b/docs/simpleXRPL/references/connectors/connector-routing.md @@ -8,7 +8,7 @@ labels: # Connector Routing -[Source](https://github.com/ripple/simpleXRPL/blob/50619258cf753008e8a185eaeb3ceca489e5998a/docs/connector-routing.md) +[[Source]](https://github.com/ripple/simpleXRPL/blob/50619258cf753008e8a185eaeb3ceca489e5998a/docs/connector-routing.md) How simpleXRPL dispatches each XRPL transactor per connector. Derived directly from each custodian's native-operation set and the transactors the verticals build, so it always matches the code. diff --git a/docs/simpleXRPL/references/connectors/local.md b/docs/simpleXRPL/references/connectors/local.md index ad67f380..de2e70f6 100644 --- a/docs/simpleXRPL/references/connectors/local.md +++ b/docs/simpleXRPL/references/connectors/local.md @@ -8,13 +8,13 @@ labels: # Local -[Source](https://github.com/ripple/simpleXRPL/blob/50619258cf753008e8a185eaeb3ceca489e5998a/src/custodians/local/local-signer.ts#L22) + [[Source]](https://github.com/ripple/simpleXRPL/blob/50619258cf753008e8a185eaeb3ceca489e5998a/src/custodians/local/local-signer.ts#L22) A local connector holds one or more XRPL accounts in-process and signs operations locally. This connector is intended for development and testing purposes. Since this method doesn't require external authentication, it is constructed synchornously unlike other connectors. ## LocalSigner.fromEnv() -Builds one wallet per `XRPL_*_SEED` environment variable (matching `XRPL__SEED` and a plain `XRPL_SEED`) — one wallet per match. The primary defaults to the first seed found. +Builds one wallet per `XRPL_*_SEED` environment variable (matching `XRPL__SEED` and a plain `XRPL_SEED`). The primary defaults to the first seed found. ### Signature diff --git a/docs/simpleXRPL/references/connectors/palisade.md b/docs/simpleXRPL/references/connectors/palisade.md index 9de63e51..22342bd4 100644 --- a/docs/simpleXRPL/references/connectors/palisade.md +++ b/docs/simpleXRPL/references/connectors/palisade.md @@ -8,7 +8,7 @@ labels: # Palisade -[Source](https://github.com/ripple/simpleXRPL/blob/50619258cf753008e8a185eaeb3ceca489e5998a/src/custodians/palisade/config.ts#L10) +[[Source]](https://github.com/ripple/simpleXRPL/blob/50619258cf753008e8a185eaeb3ceca489e5998a/src/custodians/palisade/config.ts#L10) Palisade is a Wallet-as-a-Service. This connector authenticates via OAuth2 client credentials and acts on specific vaults/wallets. @@ -35,7 +35,7 @@ PalisadeCustody.create(config: PalisadeCustodyConfig): Promise | `primary.walletId` | `string` | Yes | The primary wallet's id. | | `allowRawSigning` | `boolean` | No | Allow the raw fallback for transactors/fields Palisade can't map. Defaults to `false`. | | `defaultTimeoutMs` | `number` | No | How long to wait for a native submission to reach a terminal status. | -| `http` | `PalisadeHttpPort` | No | Advanced: a custom HTTP transport, shape `{ send: (request) => Promise }`. Defaults to the production fetch port; most callers omit it. | +| `http` | `object` | No | A custom HTTP transport (implements `PalisadeHttpPort`). Defaults to the production fetch port; most callers omit it. | | `now` | `() => number` | No | Injectable clock for the auth service, returning epoch ms, e.g. `() => Date.now()`. Defaults to `Date.now`. | diff --git a/docs/simpleXRPL/references/connectors/ripple-custody.md b/docs/simpleXRPL/references/connectors/ripple-custody.md index ada73f2a..1fb2c2e8 100644 --- a/docs/simpleXRPL/references/connectors/ripple-custody.md +++ b/docs/simpleXRPL/references/connectors/ripple-custody.md @@ -8,7 +8,7 @@ labels: # Ripple Custody -[Source](https://github.com/ripple/simpleXRPL/blob/50619258cf753008e8a185eaeb3ceca489e5998a/src/custodians/ripple/construction.ts#L30) +[[Source]](https://github.com/ripple/simpleXRPL/blob/50619258cf753008e8a185eaeb3ceca489e5998a/src/custodians/ripple/construction.ts#L30) Ripple Custody authenticates with an intent-author key exchanged for a token. A Custody deployment is per-tenant, so its gateway and token URLs point at the instance provisioned for you. @@ -60,8 +60,8 @@ RippleCustody.fromEnv(options: RippleCustodyFromEnvOptions): Promise` | No | The object those variables are read from — a map of names to values. Defaults to `process.env`. | -| `http` | `CustodyHttpPort` | No | Advanced: a custom HTTP transport, shape `{ send: (request) => Promise }`. Defaults to the production fetch port; most callers omit it. | +| `env` | `object` | No | The source the `RIPPLE_CUSTODY_*` environment variables are read from, as a map of names to values. Defaults to `process.env`. | +| `http` | `object` | No | A custom HTTP transport (implements `CustodyHttpPort`). Defaults to the production fetch port; most callers omit it. | {% admonition type="info" name="Note" %} `env` requires these keys: diff --git a/docs/simpleXRPL/references/index.md b/docs/simpleXRPL/references/index.md index 900e2a09..b5de07e4 100644 --- a/docs/simpleXRPL/references/index.md +++ b/docs/simpleXRPL/references/index.md @@ -33,7 +33,7 @@ Operations are grouped into domain-specific **verticals**, one per area of XRPL ## Connectors -The connector is the execution model — it determines how operations run and who holds the keys. See [Connectors](connectors/index.md) for each connector ([LocalSigner](connectors/local.md), [RippleCustody](connectors/ripple-custody.md), [PalisadeCustody](connectors/palisade.md)) and its configuration fields, and [Operation Execution](../index.md#operation-execution) for how each operation routes. +The connector is the execution model. It determines how operations run and who holds the keys. See [Connectors](connectors/index.md) for each connector ([LocalSigner](connectors/local.md), [RippleCustody](connectors/ripple-custody.md), [PalisadeCustody](connectors/palisade.md)) and its configuration fields, and [Operation Execution](../index.md#operation-execution) for how each operation routes. ## Amounts and assets diff --git a/docs/simpleXRPL/references/verticals/account/activate.md b/docs/simpleXRPL/references/verticals/account/activate.md index acb0d1c4..2d4503cf 100644 --- a/docs/simpleXRPL/references/verticals/account/activate.md +++ b/docs/simpleXRPL/references/verticals/account/activate.md @@ -8,9 +8,9 @@ labels: # account.activate() -[Source](https://github.com/ripple/simpleXRPL/blob/50619258cf753008e8a185eaeb3ceca489e5998a/src/verticals/account.ts#L151) +[[Source]](https://github.com/ripple/simpleXRPL/blob/50619258cf753008e8a185eaeb3ceca489e5998a/src/verticals/account.ts#L151) -Activate a created account by sending it XRP from the operator (primary) account, then enabling rippling. This is the any-network counterpart to [fund](fund.md); the account must be signable by this client (e.g. from [create](create.md)). +Activate a created account by sending it XRP from the operator (primary) account, then enabling rippling. This is the any-network counterpart to [fund](fund.md). The account must be signable by this client (e.g., from [create](create.md)). ## Signature diff --git a/docs/simpleXRPL/references/verticals/account/create.md b/docs/simpleXRPL/references/verticals/account/create.md index f15722b6..3c683be2 100644 --- a/docs/simpleXRPL/references/verticals/account/create.md +++ b/docs/simpleXRPL/references/verticals/account/create.md @@ -8,12 +8,12 @@ labels: # account.create() -[Source](https://github.com/ripple/simpleXRPL/blob/50619258cf753008e8a185eaeb3ceca489e5998a/src/verticals/account.ts#L72) +[[Source]](https://github.com/ripple/simpleXRPL/blob/50619258cf753008e8a185eaeb3ceca489e5998a/src/verticals/account.ts#L72) Generate a new XRPL keypair locally and register it so it can be funded and used right away. Use this only to mint an additional account outside of `SimpleXRPL.init`. {% admonition type="warning" name="Warning" %} -Nothing is written to the ledger until the account is funded. The returned `seed` (and `privateKey`) are secret and are the only way to control the account — store them securely and never log or transmit them. +Nothing is written to the ledger until the account is funded. The returned `seed` (and `privateKey`) are secret and are the only way to control the account. Store them securely and never log or transmit them. {% /admonition %} ## Signature @@ -28,7 +28,7 @@ None. `Account.create` takes no arguments. ## Returns -Returns an `AccountCredentials` object **synchronously** — this is the one `Account` verb that does not submit a transaction, so it does not return a `SubmissionResult`. +Returns an `AccountCredentials` object **synchronously**. This is the one `Account` operation that does not submit a transaction, so it does not return a `SubmissionResult`. ### Return fields diff --git a/docs/simpleXRPL/references/verticals/account/depositPreauth.md b/docs/simpleXRPL/references/verticals/account/depositPreauth.md index b36ffd15..31dab991 100644 --- a/docs/simpleXRPL/references/verticals/account/depositPreauth.md +++ b/docs/simpleXRPL/references/verticals/account/depositPreauth.md @@ -8,7 +8,7 @@ labels: # account.depositPreauth() -[Source](https://github.com/ripple/simpleXRPL/blob/50619258cf753008e8a185eaeb3ceca489e5998a/src/verticals/account.ts#L263) +[[Source]](https://github.com/ripple/simpleXRPL/blob/50619258cf753008e8a185eaeb3ceca489e5998a/src/verticals/account.ts#L263) Grant or revoke deposit preauthorization for another account. diff --git a/docs/simpleXRPL/references/verticals/account/fund.md b/docs/simpleXRPL/references/verticals/account/fund.md index 53dc2499..69b5b1c7 100644 --- a/docs/simpleXRPL/references/verticals/account/fund.md +++ b/docs/simpleXRPL/references/verticals/account/fund.md @@ -8,12 +8,12 @@ labels: # account.fund() -[Source](https://github.com/ripple/simpleXRPL/blob/50619258cf753008e8a185eaeb3ceca489e5998a/src/verticals/account.ts#L124) +[[Source]](https://github.com/ripple/simpleXRPL/blob/50619258cf753008e8a185eaeb3ceca489e5998a/src/verticals/account.ts#L124) -Fund a created account via the network faucet (testnet/devnet), then enable rippling. The account must be one this client can sign for (e.g. from [create](create.md)). +Fund a created account via the network faucet (Testnet/Devnet), then enable [rippling](https://xrpl.org/docs/concepts/tokens/fungible-tokens/rippling). The account must be one this client can sign for (e.g. from [create](create.md)). {% admonition type="info" name="Note" %} -`fund` requires a faucet-capable ledger (testnet/devnet). On other networks it throws — use [activate](activate.md) to fund from an operator account instead. +`fund` requires a faucet-capable ledger (Testnet/Devnet). On other networks it throws an error, so use [activate](activate.md) to fund from an operator account instead. {% /admonition %} ## Signature diff --git a/docs/simpleXRPL/references/verticals/account/listOffers.md b/docs/simpleXRPL/references/verticals/account/listOffers.md index 5d3d63e0..2ecb449f 100644 --- a/docs/simpleXRPL/references/verticals/account/listOffers.md +++ b/docs/simpleXRPL/references/verticals/account/listOffers.md @@ -8,7 +8,7 @@ labels: # account.listOffers() -[Source](https://github.com/ripple/simpleXRPL/blob/50619258cf753008e8a185eaeb3ceca489e5998a/src/verticals/account.ts#L105) +[[Source]](https://github.com/ripple/simpleXRPL/blob/50619258cf753008e8a185eaeb3ceca489e5998a/src/verticals/account.ts#L105) List the open DEX offers placed by an account. diff --git a/docs/simpleXRPL/references/verticals/account/retrieve.md b/docs/simpleXRPL/references/verticals/account/retrieve.md index 963bc61c..f793ba57 100644 --- a/docs/simpleXRPL/references/verticals/account/retrieve.md +++ b/docs/simpleXRPL/references/verticals/account/retrieve.md @@ -8,7 +8,7 @@ labels: # account.retrieve() -[Source](https://github.com/ripple/simpleXRPL/blob/50619258cf753008e8a185eaeb3ceca489e5998a/src/verticals/account.ts#L93) +[[Source]](https://github.com/ripple/simpleXRPL/blob/50619258cf753008e8a185eaeb3ceca489e5998a/src/verticals/account.ts#L93) Read an account's on-chain state — XRP balance, sequence, owner count, and flags. diff --git a/docs/simpleXRPL/references/verticals/account/set.md b/docs/simpleXRPL/references/verticals/account/set.md index 29853595..e30ae286 100644 --- a/docs/simpleXRPL/references/verticals/account/set.md +++ b/docs/simpleXRPL/references/verticals/account/set.md @@ -8,12 +8,12 @@ labels: # account.set() -[Source](https://github.com/ripple/simpleXRPL/blob/50619258cf753008e8a185eaeb3ceca489e5998a/src/verticals/account.ts#L190) +[[Source]](https://github.com/ripple/simpleXRPL/blob/50619258cf753008e8a185eaeb3ceca489e5998a/src/verticals/account.ts#L190) Update account settings. Flags are named booleans (`true` enables, `false` disables); `transferRate`, `tickSize`, and `domain` are set directly. At least one parameter is required. {% admonition type="info" name="Note" %} -A single `AccountSet` can enable at most one flag and disable at most one, so toggling more than one flag in the same direction is rejected — call `set()` once per such change. +A single `AccountSet` enables at most one flag and disables at most one. Toggling more than one flag in the same direction is rejected. Call `set()` once per such change. {% /admonition %} ## Signature diff --git a/docs/simpleXRPL/references/verticals/account/setRegularKey.md b/docs/simpleXRPL/references/verticals/account/setRegularKey.md index cc883d06..7ae8f584 100644 --- a/docs/simpleXRPL/references/verticals/account/setRegularKey.md +++ b/docs/simpleXRPL/references/verticals/account/setRegularKey.md @@ -8,7 +8,7 @@ labels: # account.setRegularKey() -[Source](https://github.com/ripple/simpleXRPL/blob/50619258cf753008e8a185eaeb3ceca489e5998a/src/verticals/account.ts#L235) +[[Source]](https://github.com/ripple/simpleXRPL/blob/50619258cf753008e8a185eaeb3ceca489e5998a/src/verticals/account.ts#L235) Set or remove the account's regular key. diff --git a/docs/simpleXRPL/references/verticals/credential/accept.md b/docs/simpleXRPL/references/verticals/credential/accept.md index b001a7d2..09c6cc5b 100644 --- a/docs/simpleXRPL/references/verticals/credential/accept.md +++ b/docs/simpleXRPL/references/verticals/credential/accept.md @@ -8,7 +8,7 @@ labels: # credential.accept() -[Source](https://github.com/ripple/simpleXRPL/blob/50619258cf753008e8a185eaeb3ceca489e5998a/src/verticals/credential.ts#L103) +[[Source]](https://github.com/ripple/simpleXRPL/blob/50619258cf753008e8a185eaeb3ceca489e5998a/src/verticals/credential.ts#L103) Accept a credential issued to the calling account. The calling account is the holder. @@ -18,7 +18,7 @@ Accept a credential issued to the calling account. The calling account is the ho credential.accept( params: CredentialAcceptParams, options?: CredentialWriteOptions, -): Promise ``` ## Parameters diff --git a/docs/simpleXRPL/references/verticals/credential/delete.md b/docs/simpleXRPL/references/verticals/credential/delete.md index 12179694..6c6d3567 100644 --- a/docs/simpleXRPL/references/verticals/credential/delete.md +++ b/docs/simpleXRPL/references/verticals/credential/delete.md @@ -8,7 +8,7 @@ labels: # credential.delete() -[Source](https://github.com/ripple/simpleXRPL/blob/50619258cf753008e8a185eaeb3ceca489e5998a/src/verticals/credential.ts#L133) +[[Source]](https://github.com/ripple/simpleXRPL/blob/50619258cf753008e8a185eaeb3ceca489e5998a/src/verticals/credential.ts#L133) Delete a credential, as either its issuer or its holder. @@ -18,7 +18,7 @@ Delete a credential, as either its issuer or its holder. credential.delete( params: CredentialDeleteParams, options?: CredentialWriteOptions, -): Promise ``` ## Parameters diff --git a/docs/simpleXRPL/references/verticals/credential/issue.md b/docs/simpleXRPL/references/verticals/credential/issue.md index 3bbc89d0..92f34027 100644 --- a/docs/simpleXRPL/references/verticals/credential/issue.md +++ b/docs/simpleXRPL/references/verticals/credential/issue.md @@ -8,7 +8,7 @@ labels: # credential.issue() -[Source](https://github.com/ripple/simpleXRPL/blob/50619258cf753008e8a185eaeb3ceca489e5998a/src/verticals/credential.ts#L67) +[[Source]](https://github.com/ripple/simpleXRPL/blob/50619258cf753008e8a185eaeb3ceca489e5998a/src/verticals/credential.ts#L67) Issue a credential to a destination account. The calling account is the issuer. @@ -18,7 +18,7 @@ Issue a credential to a destination account. The calling account is the issuer. credential.issue( params: CredentialIssueParams, options?: CredentialWriteOptions, -): Promise ``` ## Parameters diff --git a/docs/simpleXRPL/references/verticals/credential/list.md b/docs/simpleXRPL/references/verticals/credential/list.md index 9009c65a..5780ce17 100644 --- a/docs/simpleXRPL/references/verticals/credential/list.md +++ b/docs/simpleXRPL/references/verticals/credential/list.md @@ -8,7 +8,7 @@ labels: # credential.list() -[Source](https://github.com/ripple/simpleXRPL/blob/50619258cf753008e8a185eaeb3ceca489e5998a/src/verticals/credential.ts#L54) +[[Source]](https://github.com/ripple/simpleXRPL/blob/50619258cf753008e8a185eaeb3ceca489e5998a/src/verticals/credential.ts#L54) List credentials an account holds (default) or issued. diff --git a/docs/simpleXRPL/references/verticals/credential/retrieve.md b/docs/simpleXRPL/references/verticals/credential/retrieve.md index 736755d2..1ec67565 100644 --- a/docs/simpleXRPL/references/verticals/credential/retrieve.md +++ b/docs/simpleXRPL/references/verticals/credential/retrieve.md @@ -8,7 +8,7 @@ labels: # credential.retrieve() -[Source](https://github.com/ripple/simpleXRPL/blob/50619258cf753008e8a185eaeb3ceca489e5998a/src/verticals/credential.ts#L42) +[[Source]](https://github.com/ripple/simpleXRPL/blob/50619258cf753008e8a185eaeb3ceca489e5998a/src/verticals/credential.ts#L42) Retrieve a single credential by type and issuer (point-in-time). diff --git a/docs/simpleXRPL/references/verticals/domain/create.md b/docs/simpleXRPL/references/verticals/domain/create.md index 55f38293..da402291 100644 --- a/docs/simpleXRPL/references/verticals/domain/create.md +++ b/docs/simpleXRPL/references/verticals/domain/create.md @@ -8,7 +8,7 @@ labels: # domain.create() -[Source](https://github.com/ripple/simpleXRPL/blob/50619258cf753008e8a185eaeb3ceca489e5998a/src/verticals/domain.ts#L70) +[[Source]](https://github.com/ripple/simpleXRPL/blob/50619258cf753008e8a185eaeb3ceca489e5998a/src/verticals/domain.ts#L70) Create a new permissioned domain. diff --git a/docs/simpleXRPL/references/verticals/domain/delete.md b/docs/simpleXRPL/references/verticals/domain/delete.md index 8e0f1a84..94420172 100644 --- a/docs/simpleXRPL/references/verticals/domain/delete.md +++ b/docs/simpleXRPL/references/verticals/domain/delete.md @@ -8,7 +8,7 @@ labels: # domain.delete() -[Source](https://github.com/ripple/simpleXRPL/blob/50619258cf753008e8a185eaeb3ceca489e5998a/src/verticals/domain.ts#L123) +[[Source]](https://github.com/ripple/simpleXRPL/blob/50619258cf753008e8a185eaeb3ceca489e5998a/src/verticals/domain.ts#L123) Delete a permissioned domain. diff --git a/docs/simpleXRPL/references/verticals/domain/list.md b/docs/simpleXRPL/references/verticals/domain/list.md index 89992c65..c64cd156 100644 --- a/docs/simpleXRPL/references/verticals/domain/list.md +++ b/docs/simpleXRPL/references/verticals/domain/list.md @@ -8,7 +8,7 @@ labels: # domain.list() -[Source](https://github.com/ripple/simpleXRPL/blob/50619258cf753008e8a185eaeb3ceca489e5998a/src/verticals/domain.ts#L59) +[[Source]](https://github.com/ripple/simpleXRPL/blob/50619258cf753008e8a185eaeb3ceca489e5998a/src/verticals/domain.ts#L59) List every permissioned domain owned by an account. diff --git a/docs/simpleXRPL/references/verticals/domain/retrieve.md b/docs/simpleXRPL/references/verticals/domain/retrieve.md index 12a5116e..9ac98a08 100644 --- a/docs/simpleXRPL/references/verticals/domain/retrieve.md +++ b/docs/simpleXRPL/references/verticals/domain/retrieve.md @@ -8,7 +8,7 @@ labels: # domain.retrieve() -[Source](https://github.com/ripple/simpleXRPL/blob/50619258cf753008e8a185eaeb3ceca489e5998a/src/verticals/domain.ts#L47) +[[Source]](https://github.com/ripple/simpleXRPL/blob/50619258cf753008e8a185eaeb3ceca489e5998a/src/verticals/domain.ts#L47) Retrieve a permissioned domain by id (point-in-time). diff --git a/docs/simpleXRPL/references/verticals/domain/setCredentials.md b/docs/simpleXRPL/references/verticals/domain/setCredentials.md index a2df984b..bba9aa8e 100644 --- a/docs/simpleXRPL/references/verticals/domain/setCredentials.md +++ b/docs/simpleXRPL/references/verticals/domain/setCredentials.md @@ -8,7 +8,7 @@ labels: # domain.setCredentials() -[Source](https://github.com/ripple/simpleXRPL/blob/50619258cf753008e8a185eaeb3ceca489e5998a/src/verticals/domain.ts#L96) +[[Source]](https://github.com/ripple/simpleXRPL/blob/50619258cf753008e8a185eaeb3ceca489e5998a/src/verticals/domain.ts#L96) Update the accepted credentials of an existing permissioned domain. diff --git a/docs/simpleXRPL/references/verticals/iou/authorize.md b/docs/simpleXRPL/references/verticals/iou/authorize.md index a3ebdaec..b95053ea 100644 --- a/docs/simpleXRPL/references/verticals/iou/authorize.md +++ b/docs/simpleXRPL/references/verticals/iou/authorize.md @@ -8,7 +8,7 @@ labels: # iou.authorize() -[Source](https://github.com/ripple/simpleXRPL/blob/50619258cf753008e8a185eaeb3ceca489e5998a/src/verticals/iou.ts#L152) +[[Source]](https://github.com/ripple/simpleXRPL/blob/50619258cf753008e8a185eaeb3ceca489e5998a/src/verticals/iou.ts#L152) Grant authorization for a holder to hold this IOU. Only meaningful when the issuer's account has `asfRequireAuth` set. diff --git a/docs/simpleXRPL/references/verticals/iou/buyOffer.md b/docs/simpleXRPL/references/verticals/iou/buyOffer.md index d8eb43cf..a2da14c3 100644 --- a/docs/simpleXRPL/references/verticals/iou/buyOffer.md +++ b/docs/simpleXRPL/references/verticals/iou/buyOffer.md @@ -8,7 +8,7 @@ labels: # iou.buyOffer() -[Source](https://github.com/ripple/simpleXRPL/blob/50619258cf753008e8a185eaeb3ceca489e5998a/src/verticals/iou.ts#L303) +[[Source]](https://github.com/ripple/simpleXRPL/blob/50619258cf753008e8a185eaeb3ceca489e5998a/src/verticals/iou.ts#L303) Place an order on the DEX to acquire more of this IOU. diff --git a/docs/simpleXRPL/references/verticals/iou/cancelOffer.md b/docs/simpleXRPL/references/verticals/iou/cancelOffer.md index 29de669c..39424e8d 100644 --- a/docs/simpleXRPL/references/verticals/iou/cancelOffer.md +++ b/docs/simpleXRPL/references/verticals/iou/cancelOffer.md @@ -8,7 +8,7 @@ labels: # iou.cancelOffer() -[Source](https://github.com/ripple/simpleXRPL/blob/50619258cf753008e8a185eaeb3ceca489e5998a/src/verticals/iou.ts#L335) +[[Source]](https://github.com/ripple/simpleXRPL/blob/50619258cf753008e8a185eaeb3ceca489e5998a/src/verticals/iou.ts#L335) Cancel a standing offer placed by this IOU's issuer. @@ -18,7 +18,7 @@ Cancel a standing offer placed by this IOU's issuer. iou.cancelOffer( params: IOUCancelOfferParams, options?: IOUWriteOptions, -): Promise ``` ## Parameters diff --git a/docs/simpleXRPL/references/verticals/iou/clawback.md b/docs/simpleXRPL/references/verticals/iou/clawback.md index f8dc3ebf..e9278c6c 100644 --- a/docs/simpleXRPL/references/verticals/iou/clawback.md +++ b/docs/simpleXRPL/references/verticals/iou/clawback.md @@ -8,12 +8,12 @@ labels: # iou.clawback() -[Source](https://github.com/ripple/simpleXRPL/blob/50619258cf753008e8a185eaeb3ceca489e5998a/src/verticals/iou.ts#L234) +[[Source]](https://github.com/ripple/simpleXRPL/blob/50619258cf753008e8a185eaeb3ceca489e5998a/src/verticals/iou.ts#L234) Reclaim a holder's balance back to the issuer. {% admonition type="info" name="Note" %} -Verifies the issuer has `asfAllowTrustLineClawback` enabled first (a ledger read), throwing a clear error if not. That flag can only be enabled before the issuer owns any trust lines, offers, or other ledger objects, which this SDK does not itself pre-check. +Verifies the issuer has `asfAllowTrustLineClawback` enabled first (a ledger read), throwing a clear error if not. The flag can only be enabled before the issuer owns any trust lines, offers, or other ledger objects, which this SDK does not itself pre-check. {% /admonition %} ## Signature diff --git a/docs/simpleXRPL/references/verticals/iou/issue.md b/docs/simpleXRPL/references/verticals/iou/issue.md index e7411db9..54245cb2 100644 --- a/docs/simpleXRPL/references/verticals/iou/issue.md +++ b/docs/simpleXRPL/references/verticals/iou/issue.md @@ -8,12 +8,12 @@ labels: # iou.issue() -[Source](https://github.com/ripple/simpleXRPL/blob/50619258cf753008e8a185eaeb3ceca489e5998a/src/verticals/iou.ts#L83) +[[Source]](https://github.com/ripple/simpleXRPL/blob/50619258cf753008e8a185eaeb3ceca489e5998a/src/verticals/iou.ts#L83) Generate a new trust line-based IOU between two developer-controlled accounts sourced from the environment. {% admonition type="info" name="Note" %} -Unlike the other IOU verbs, `issue` takes no `options`. It bootstraps both accounts from the environment: it reads `XRPL_ISSUER_SEED` and `XRPL_HOT_WALLET_SEED`, has the issuer enable rippling, then has the hot wallet extend trust up to the maximum limit. No `Payment` runs, so no value exists yet — use [IOU.transfer](transfer.md) to send some. +Unlike the other IOU verbs, `issue` takes no `options`. It bootstraps both accounts from the environment: it reads `XRPL_ISSUER_SEED` and `XRPL_HOT_WALLET_SEED`, has the issuer enable rippling, then has the hot wallet extend trust up to the maximum limit. No `Payment` runs, so no value exists yet. Use [IOU.transfer](transfer.md) to send some. {% /admonition %} ## Signature @@ -28,7 +28,7 @@ iou.issue( | Parameter | Type | Required | Description | | --- | --- | --- | --- | -| `ticker` | `string` | Yes | The currency code: a 3-character ISO-4217-style code or a 40-character hex code. Any other code (e.g. a 5-character ticker) is auto-encoded to the 40-character hex form. | +| `ticker` | `string` | Yes | The currency code: a 3-character ISO-4217-style code or a 40-character hex code. Any other code (e.g., a 5-character ticker) is auto-encoded to the 40-character hex form. | ## Returns diff --git a/docs/simpleXRPL/references/verticals/iou/list.md b/docs/simpleXRPL/references/verticals/iou/list.md index 34632036..3ea262eb 100644 --- a/docs/simpleXRPL/references/verticals/iou/list.md +++ b/docs/simpleXRPL/references/verticals/iou/list.md @@ -8,7 +8,7 @@ labels: # iou.list() -[Source](https://github.com/ripple/simpleXRPL/blob/50619258cf753008e8a185eaeb3ceca489e5998a/src/verticals/iou.ts#L119) +[[Source]](https://github.com/ripple/simpleXRPL/blob/50619258cf753008e8a185eaeb3ceca489e5998a/src/verticals/iou.ts#L119) List every IOU trust line for an account. diff --git a/docs/simpleXRPL/references/verticals/iou/listOffers.md b/docs/simpleXRPL/references/verticals/iou/listOffers.md index fff19577..c9612fe9 100644 --- a/docs/simpleXRPL/references/verticals/iou/listOffers.md +++ b/docs/simpleXRPL/references/verticals/iou/listOffers.md @@ -8,7 +8,7 @@ labels: # iou.listOffers() -[Source](https://github.com/ripple/simpleXRPL/blob/50619258cf753008e8a185eaeb3ceca489e5998a/src/verticals/iou.ts#L130) +[[Source]](https://github.com/ripple/simpleXRPL/blob/50619258cf753008e8a185eaeb3ceca489e5998a/src/verticals/iou.ts#L130) List all open offers in the market for this IOU (both sides), tagged buy/sell relative to it. diff --git a/docs/simpleXRPL/references/verticals/iou/lock.md b/docs/simpleXRPL/references/verticals/iou/lock.md index d3ae351c..2011b5f2 100644 --- a/docs/simpleXRPL/references/verticals/iou/lock.md +++ b/docs/simpleXRPL/references/verticals/iou/lock.md @@ -8,7 +8,7 @@ labels: # iou.lock() -[Source](https://github.com/ripple/simpleXRPL/blob/50619258cf753008e8a185eaeb3ceca489e5998a/src/verticals/iou.ts#L187) +[[Source]](https://github.com/ripple/simpleXRPL/blob/50619258cf753008e8a185eaeb3ceca489e5998a/src/verticals/iou.ts#L187) Freeze a holder's ability to send and receive this IOU: an individual freeze followed by a deep freeze. diff --git a/docs/simpleXRPL/references/verticals/iou/retrieve.md b/docs/simpleXRPL/references/verticals/iou/retrieve.md index 5f5c291d..8e747426 100644 --- a/docs/simpleXRPL/references/verticals/iou/retrieve.md +++ b/docs/simpleXRPL/references/verticals/iou/retrieve.md @@ -8,7 +8,7 @@ labels: # iou.retrieve() -[Source](https://github.com/ripple/simpleXRPL/blob/50619258cf753008e8a185eaeb3ceca489e5998a/src/verticals/iou.ts#L109) +[[Source]](https://github.com/ripple/simpleXRPL/blob/50619258cf753008e8a185eaeb3ceca489e5998a/src/verticals/iou.ts#L109) Read a single IOU trust line (point-in-time). diff --git a/docs/simpleXRPL/references/verticals/iou/sellOffer.md b/docs/simpleXRPL/references/verticals/iou/sellOffer.md index 591668d4..2e333468 100644 --- a/docs/simpleXRPL/references/verticals/iou/sellOffer.md +++ b/docs/simpleXRPL/references/verticals/iou/sellOffer.md @@ -8,7 +8,7 @@ labels: # iou.sellOffer() -[Source](https://github.com/ripple/simpleXRPL/blob/50619258cf753008e8a185eaeb3ceca489e5998a/src/verticals/iou.ts#L319) +[[Source]](https://github.com/ripple/simpleXRPL/blob/50619258cf753008e8a185eaeb3ceca489e5998a/src/verticals/iou.ts#L319) Place an order on the DEX to sell this IOU. diff --git a/docs/simpleXRPL/references/verticals/iou/transfer.md b/docs/simpleXRPL/references/verticals/iou/transfer.md index 821bdebb..a8741c83 100644 --- a/docs/simpleXRPL/references/verticals/iou/transfer.md +++ b/docs/simpleXRPL/references/verticals/iou/transfer.md @@ -8,7 +8,7 @@ labels: # iou.transfer() -[Source](https://github.com/ripple/simpleXRPL/blob/50619258cf753008e8a185eaeb3ceca489e5998a/src/verticals/iou.ts#L267) +[[Source]](https://github.com/ripple/simpleXRPL/blob/50619258cf753008e8a185eaeb3ceca489e5998a/src/verticals/iou.ts#L267) Send a specified amount of this IOU to a destination account. diff --git a/docs/simpleXRPL/references/verticals/iou/unlock.md b/docs/simpleXRPL/references/verticals/iou/unlock.md index a3925fd6..b08bd6a4 100644 --- a/docs/simpleXRPL/references/verticals/iou/unlock.md +++ b/docs/simpleXRPL/references/verticals/iou/unlock.md @@ -8,7 +8,7 @@ labels: # iou.unlock() -[Source](https://github.com/ripple/simpleXRPL/blob/50619258cf753008e8a185eaeb3ceca489e5998a/src/verticals/iou.ts#L209) +[[Source]](https://github.com/ripple/simpleXRPL/blob/50619258cf753008e8a185eaeb3ceca489e5998a/src/verticals/iou.ts#L209) Restore a holder's ability to send and receive this IOU: clears the deep freeze, then the individual freeze. diff --git a/docs/simpleXRPL/references/verticals/token/authorize.md b/docs/simpleXRPL/references/verticals/token/authorize.md index 766e5bcf..ee3b4e71 100644 --- a/docs/simpleXRPL/references/verticals/token/authorize.md +++ b/docs/simpleXRPL/references/verticals/token/authorize.md @@ -8,7 +8,7 @@ labels: # token.authorize() -[Source](https://github.com/ripple/simpleXRPL/blob/50619258cf753008e8a185eaeb3ceca489e5998a/src/verticals/token.ts#L155) +[[Source]](https://github.com/ripple/simpleXRPL/blob/50619258cf753008e8a185eaeb3ceca489e5998a/src/verticals/token.ts#L155) Opt the calling account in to hold an MPT issuance. diff --git a/docs/simpleXRPL/references/verticals/token/cancelOffer.md b/docs/simpleXRPL/references/verticals/token/cancelOffer.md index 9b81c989..a1afc48c 100644 --- a/docs/simpleXRPL/references/verticals/token/cancelOffer.md +++ b/docs/simpleXRPL/references/verticals/token/cancelOffer.md @@ -8,7 +8,7 @@ labels: # token.cancelOffer() -[Source](https://github.com/ripple/simpleXRPL/blob/50619258cf753008e8a185eaeb3ceca489e5998a/src/verticals/token.ts#L336) +[[Source]](https://github.com/ripple/simpleXRPL/blob/50619258cf753008e8a185eaeb3ceca489e5998a/src/verticals/token.ts#L336) Cancel a standing offer. diff --git a/docs/simpleXRPL/references/verticals/token/createOffer.md b/docs/simpleXRPL/references/verticals/token/createOffer.md index 2a01e163..7e6ca632 100644 --- a/docs/simpleXRPL/references/verticals/token/createOffer.md +++ b/docs/simpleXRPL/references/verticals/token/createOffer.md @@ -8,7 +8,7 @@ labels: # token.createOffer() -[Source](https://github.com/ripple/simpleXRPL/blob/50619258cf753008e8a185eaeb3ceca489e5998a/src/verticals/token.ts#L299) +[[Source]](https://github.com/ripple/simpleXRPL/blob/50619258cf753008e8a185eaeb3ceca489e5998a/src/verticals/token.ts#L299) Place an offer on the decentralized exchange (DEX). diff --git a/docs/simpleXRPL/references/verticals/token/destroy.md b/docs/simpleXRPL/references/verticals/token/destroy.md index f9b00e6a..df4ca11a 100644 --- a/docs/simpleXRPL/references/verticals/token/destroy.md +++ b/docs/simpleXRPL/references/verticals/token/destroy.md @@ -8,7 +8,7 @@ labels: # token.destroy() -[Source](https://github.com/ripple/simpleXRPL/blob/50619258cf753008e8a185eaeb3ceca489e5998a/src/verticals/token.ts#L239) +[[Source]](https://github.com/ripple/simpleXRPL/blob/50619258cf753008e8a185eaeb3ceca489e5998a/src/verticals/token.ts#L239) Destroy an MPT issuance. Only succeeds when no tokens are outstanding. diff --git a/docs/simpleXRPL/references/verticals/token/grantHolder.md b/docs/simpleXRPL/references/verticals/token/grantHolder.md index 56ec8c0e..2be27c73 100644 --- a/docs/simpleXRPL/references/verticals/token/grantHolder.md +++ b/docs/simpleXRPL/references/verticals/token/grantHolder.md @@ -8,7 +8,7 @@ labels: # token.grantHolder() -[Source](https://github.com/ripple/simpleXRPL/blob/50619258cf753008e8a185eaeb3ceca489e5998a/src/verticals/token.ts#L183) +[[Source]](https://github.com/ripple/simpleXRPL/blob/50619258cf753008e8a185eaeb3ceca489e5998a/src/verticals/token.ts#L183) As the issuer, grant a specific holder permission to hold this MPT (allow-listing). Use this when the issuance requires authorization. @@ -18,7 +18,7 @@ As the issuer, grant a specific holder permission to hold this MPT (allow-listin token.grantHolder( params: MptHolderParams, options?: TokenWriteOptions, -): Promise ``` ## Parameters diff --git a/docs/simpleXRPL/references/verticals/token/issue.md b/docs/simpleXRPL/references/verticals/token/issue.md index 5a5784d0..1c247638 100644 --- a/docs/simpleXRPL/references/verticals/token/issue.md +++ b/docs/simpleXRPL/references/verticals/token/issue.md @@ -8,7 +8,7 @@ labels: # token.issue() -[Source](https://github.com/ripple/simpleXRPL/blob/50619258cf753008e8a185eaeb3ceca489e5998a/src/verticals/token.ts#L134) +[[Source]](https://github.com/ripple/simpleXRPL/blob/50619258cf753008e8a185eaeb3ceca489e5998a/src/verticals/token.ts#L134) Create a new MPT issuance. @@ -25,7 +25,7 @@ token.issue( | Parameter | Type | Required | Description | | --- | --- | --- | --- | -| `metadata` | `MPTokenMetadata \| string` | Yes | Token metadata: a structured object (encoded per the XLS-89 standard) or a raw string (UTF-8 hex-encoded as-is). Validated against XLS-89; non-compliant metadata is rejected before submission. | +| `metadata` | `MPTokenMetadata \| string` | Yes | Token metadata: a structured object (encoded per the [XLS-89 standard](https://github.com/XRPLF/XRPL-Standards/tree/master/XLS-0089-multi-purpose-token-metadata-schema)) or a raw string (UTF-8 hex-encoded as-is). Validated against XLS-89; non-compliant metadata is rejected before submission. | | `assetScale` | `number` | No | Decimal places between the display value and base units. Defaults to `2`. | | `maximumAmount` | `string` | No | Maximum issuable amount, in base units. | | `transferFee` | `number` | No | Transfer fee on secondary sales, as a percentage (`0.5` = 0.5%, range 0–50). | diff --git a/docs/simpleXRPL/references/verticals/token/list.md b/docs/simpleXRPL/references/verticals/token/list.md index 0b19f2f6..ccf87acb 100644 --- a/docs/simpleXRPL/references/verticals/token/list.md +++ b/docs/simpleXRPL/references/verticals/token/list.md @@ -8,9 +8,9 @@ labels: # token.list() -[Source](https://github.com/ripple/simpleXRPL/blob/50619258cf753008e8a185eaeb3ceca489e5998a/src/verticals/token.ts#L79) +[[Source]](https://github.com/ripple/simpleXRPL/blob/50619258cf753008e8a185eaeb3ceca489e5998a/src/verticals/token.ts#L79) -List the MPTs an account holds (default) or issued. +List the MPTs an account holds or issued. ## Signature @@ -24,7 +24,7 @@ token.list( | Parameter | Type | Required | Description | | --- | --- | --- | --- | -| `role` | `'holder' \| 'issuer'` | No | List tokens the account holds (default) or issued. | +| `role` | `'holder' \| 'issuer'` | No | List tokens the account holds or issued. Defaults to tokens held if ommitted. | | `account` | `string` | No | The account to query. Defaults to the primary signer's account. | ## Returns diff --git a/docs/simpleXRPL/references/verticals/token/listOffers.md b/docs/simpleXRPL/references/verticals/token/listOffers.md index a8672fd2..83d64d6d 100644 --- a/docs/simpleXRPL/references/verticals/token/listOffers.md +++ b/docs/simpleXRPL/references/verticals/token/listOffers.md @@ -8,7 +8,7 @@ labels: # token.listOffers() -[Source](https://github.com/ripple/simpleXRPL/blob/50619258cf753008e8a185eaeb3ceca489e5998a/src/verticals/token.ts#L89) +[[Source]](https://github.com/ripple/simpleXRPL/blob/50619258cf753008e8a185eaeb3ceca489e5998a/src/verticals/token.ts#L89) List the open DEX offers placed by an account. diff --git a/docs/simpleXRPL/references/verticals/token/lock.md b/docs/simpleXRPL/references/verticals/token/lock.md index 99c66ca4..6b499513 100644 --- a/docs/simpleXRPL/references/verticals/token/lock.md +++ b/docs/simpleXRPL/references/verticals/token/lock.md @@ -8,7 +8,7 @@ labels: # token.lock() -[Source](https://github.com/ripple/simpleXRPL/blob/50619258cf753008e8a185eaeb3ceca489e5998a/src/verticals/token.ts#L211) +[[Source]](https://github.com/ripple/simpleXRPL/blob/50619258cf753008e8a185eaeb3ceca489e5998a/src/verticals/token.ts#L211) Lock an MPT issuance, or a specific holder's balance when `holder` is given. @@ -18,7 +18,7 @@ Lock an MPT issuance, or a specific holder's balance when `holder` is given. token.lock( params: MptLockParams, options?: TokenWriteOptions, -): Promise ``` ## Parameters diff --git a/docs/simpleXRPL/references/verticals/token/retrieve.md b/docs/simpleXRPL/references/verticals/token/retrieve.md index f7478d33..58786884 100644 --- a/docs/simpleXRPL/references/verticals/token/retrieve.md +++ b/docs/simpleXRPL/references/verticals/token/retrieve.md @@ -8,7 +8,7 @@ labels: # token.retrieve() -[Source](https://github.com/ripple/simpleXRPL/blob/50619258cf753008e8a185eaeb3ceca489e5998a/src/verticals/token.ts#L67) +[[Source]](https://github.com/ripple/simpleXRPL/blob/50619258cf753008e8a185eaeb3ceca489e5998a/src/verticals/token.ts#L67) Retrieve a single MPT issuance by id (point-in-time), with flags decoded to booleans and XLS-89 metadata decoded. diff --git a/docs/simpleXRPL/references/verticals/token/revokeHolder.md b/docs/simpleXRPL/references/verticals/token/revokeHolder.md index 40ec1491..70f462bc 100644 --- a/docs/simpleXRPL/references/verticals/token/revokeHolder.md +++ b/docs/simpleXRPL/references/verticals/token/revokeHolder.md @@ -8,7 +8,7 @@ labels: # token.revokeHolder() -[Source](https://github.com/ripple/simpleXRPL/blob/50619258cf753008e8a185eaeb3ceca489e5998a/src/verticals/token.ts#L197) +[[Source]](https://github.com/ripple/simpleXRPL/blob/50619258cf753008e8a185eaeb3ceca489e5998a/src/verticals/token.ts#L197) As the issuer, revoke a specific holder's permission to hold this MPT. @@ -18,7 +18,7 @@ As the issuer, revoke a specific holder's permission to hold this MPT. token.revokeHolder( params: MptHolderParams, options?: TokenWriteOptions, -): Promise ``` ## Parameters diff --git a/docs/simpleXRPL/references/verticals/token/transfer.md b/docs/simpleXRPL/references/verticals/token/transfer.md index ce40d6e7..2ddac822 100644 --- a/docs/simpleXRPL/references/verticals/token/transfer.md +++ b/docs/simpleXRPL/references/verticals/token/transfer.md @@ -8,7 +8,7 @@ labels: # token.transfer() -[Source](https://github.com/ripple/simpleXRPL/blob/50619258cf753008e8a185eaeb3ceca489e5998a/src/verticals/token.ts#L266) +[[Source]](https://github.com/ripple/simpleXRPL/blob/50619258cf753008e8a185eaeb3ceca489e5998a/src/verticals/token.ts#L266) Send an MPT amount to another account. @@ -18,7 +18,7 @@ Send an MPT amount to another account. token.transfer( params: TokenTransferParams, options?: TokenWriteOptions, -): Promise ``` ## Parameters diff --git a/docs/simpleXRPL/references/verticals/token/unauthorize.md b/docs/simpleXRPL/references/verticals/token/unauthorize.md index aea8af36..fbe230b2 100644 --- a/docs/simpleXRPL/references/verticals/token/unauthorize.md +++ b/docs/simpleXRPL/references/verticals/token/unauthorize.md @@ -8,7 +8,7 @@ labels: # token.unauthorize() -[Source](https://github.com/ripple/simpleXRPL/blob/50619258cf753008e8a185eaeb3ceca489e5998a/src/verticals/token.ts#L169) +[[Source]](https://github.com/ripple/simpleXRPL/blob/50619258cf753008e8a185eaeb3ceca489e5998a/src/verticals/token.ts#L169) Opt the calling account out of holding an MPT issuance. The account's balance must be `0`. @@ -18,7 +18,7 @@ Opt the calling account out of holding an MPT issuance. The account's balance mu token.unauthorize( params: MptAuthorizeParams, options?: TokenWriteOptions, -): Promise ``` ## Parameters diff --git a/docs/simpleXRPL/references/verticals/token/unlock.md b/docs/simpleXRPL/references/verticals/token/unlock.md index d28a81fd..8613616d 100644 --- a/docs/simpleXRPL/references/verticals/token/unlock.md +++ b/docs/simpleXRPL/references/verticals/token/unlock.md @@ -8,7 +8,7 @@ labels: # token.unlock() -[Source](https://github.com/ripple/simpleXRPL/blob/50619258cf753008e8a185eaeb3ceca489e5998a/src/verticals/token.ts#L225) +[[Source]](https://github.com/ripple/simpleXRPL/blob/50619258cf753008e8a185eaeb3ceca489e5998a/src/verticals/token.ts#L225) Unlock a previously locked MPT issuance, or a specific holder's balance when `holder` is given. @@ -18,7 +18,7 @@ Unlock a previously locked MPT issuance, or a specific holder's balance when `ho token.unlock( params: MptLockParams, options?: TokenWriteOptions, -): Promise ``` ## Parameters diff --git a/docs/simpleXRPL/references/verticals/xrp/transfer.md b/docs/simpleXRPL/references/verticals/xrp/transfer.md index 239ee2f8..9748faae 100644 --- a/docs/simpleXRPL/references/verticals/xrp/transfer.md +++ b/docs/simpleXRPL/references/verticals/xrp/transfer.md @@ -8,7 +8,7 @@ labels: # xrp.transfer() -[Source](https://github.com/ripple/simpleXRPL/blob/50619258cf753008e8a185eaeb3ceca489e5998a/src/verticals/xrp.ts#L67) +[[Source]](https://github.com/ripple/simpleXRPL/blob/50619258cf753008e8a185eaeb3ceca489e5998a/src/verticals/xrp.ts#L67) Send native XRP from one account to another. @@ -25,7 +25,7 @@ xrp.transfer( | Parameter | Type | Required | Description | | --- | --- | --- | --- | -| `to` | `string` | Yes | Destination r-address. | +| `to` | `string` | Yes | Destination account XRPL address. | | `amount` | `string` | Yes | Amount to send, as a decimal string in XRP (e.g. `'10'`, `'0.25'`). | ## Options diff --git a/docs/simpleXRPL/tutorials/implement-aws-kms-signer.md b/docs/simpleXRPL/tutorials/implement-aws-kms-signer.md index 12d63324..38b6f758 100644 --- a/docs/simpleXRPL/tutorials/implement-aws-kms-signer.md +++ b/docs/simpleXRPL/tutorials/implement-aws-kms-signer.md @@ -8,7 +8,7 @@ labels: # Sign With AWS KMS -simpleXRPL ships an AWS KMS adapter as a subpath import (`simplexrpl/aws-kms`). The private key stays in KMS and never enters the process — the SDK hands KMS a digest and assembles the signature. +`simpleXRPL` ships an [AWS KMS](https://docs.aws.amazon.com/kms/latest/developerguide/overview.html) adapter as a subpath import (`simplexrpl/aws-kms`). The private key stays in KMS and never enters the process — the SDK hands KMS a digest and assembles the signature. ```ts /** From caddbf44d2c1a6b76d0d0cac9ef3f06c92bb6771 Mon Sep 17 00:00:00 2001 From: Oliver Eggert Date: Mon, 27 Jul 2026 16:46:11 -0700 Subject: [PATCH 16/24] add external connector --- docs/simpleXRPL/index.md | 2 +- .../references/connectors/external.md | 94 +++++++++++++++++++ .../simpleXRPL/references/connectors/index.md | 3 +- docs/simpleXRPL/references/index.md | 2 +- sidebars.yaml | 1 + 5 files changed, 99 insertions(+), 3 deletions(-) create mode 100644 docs/simpleXRPL/references/connectors/external.md diff --git a/docs/simpleXRPL/index.md b/docs/simpleXRPL/index.md index 1f488b83..4c501abd 100644 --- a/docs/simpleXRPL/index.md +++ b/docs/simpleXRPL/index.md @@ -7,7 +7,7 @@ labels: --- # simpleXRPL -[Source](https://github.com/ripple/simpleXRPL) +[[Source]](https://github.com/ripple/simpleXRPL) `simpleXRPL` is an opinionated TypeScript SDK for the XRP Ledger, built for institutional developers who interact with the ledger through a custodian. It raises the level of your code from XRPL protocol mechanics to business operations that the SDK routes through your institutional custodians. Concretely, this means: diff --git a/docs/simpleXRPL/references/connectors/external.md b/docs/simpleXRPL/references/connectors/external.md new file mode 100644 index 00000000..5d61814f --- /dev/null +++ b/docs/simpleXRPL/references/connectors/external.md @@ -0,0 +1,94 @@ +--- +seo: + description: ExternalSigner is simpleXRPL's connector for keys held in a KMS or HSM. It signs through a caller-supplied port so the private key never enters the process. +labels: + - simpleXRPL + - SDK +--- + +# External + +[[Source]](https://github.com/ripple/simpleXRPL/blob/50619258cf753008e8a185eaeb3ceca489e5998a/src/custodians/external/external-signer.ts#L40) + +An external connector signs with a key held by a KMS (AWS, GCP) or an HSM (PKCS#11, CloudHSM). The SDK owns the rest of the business operation lifecycle. + +`simpleXRPL` ships an AWS KMS adapter; for any other provider you must implement the port yourself. + + +## ExternalSigner.create() + +Fetches the signer's public key and resolves the account it acts as. + +### Signature + +```ts +ExternalSigner.create(options: ExternalSignerOptions): Promise +``` + +### Options + +| Field | Type | Required | Description | +| --- | --- | --- | --- | +| `signer` | `object` | Yes | The KMS/HSM-backed signer for one key. Implements [ExternalSignerPort](#externalsignerport). | +| `address` | `string` | No | The XRPL address to act as. Defaults to the address derived from the signer's public key. | + + +## ExternalSignerPort + +The signing seam to implement, defined by the `algorithm` field. + +### Secp256k1SignerPort + +For secp256k1 keys (e.g., AWS KMS, most PKCS#11 HSMs). + +| Field | Type | Required | Description | +| --- | --- | --- | --- | +| `algorithm` | `string` | Yes | Must be `secp256k1`. | +| `publicKey` | `function` | Yes | An async function, no arguments, returning the public key as an XRPL-format compressed hex string (33 bytes, `02`/`03` prefix). Signature: `() => Promise`. | +| `signDigest` | `function` | Yes | An async function that takes a 32-byte digest (XRPL's SHA-512Half of the signing data, as a byte array) and returns the raw signature scalars — an object `{ r, s }` where each is a `bigint`. The SDK normalizes to low-S and DER-encodes before attaching the signature. Signature: `(digest: Uint8Array) => Promise<{ r: bigint, s: bigint }>`. | + +### Ed25519SignerPort + +For ed25519 keys (e.g., GCP KMS, some HSMs). + +| Field | Type | Required | Description | +| --- | --- | --- | --- | +| `algorithm` | `string` | Yes | Must be `ed25519`. | +| `publicKey` | `function` | Yes | An async function, no arguments, returning the public key as an XRPL-format hex string (33 bytes: the `ED` prefix followed by the 32-byte raw key). Signature: `() => Promise`. | +| `signMessage` | `function` | Yes | An async function that takes the message bytes (a byte array) and returns the raw 64-byte signature (a byte array). ed25519 hashes internally, so there is no pre-digest and no low-S step. Signature: `(message: Uint8Array) => Promise`. | + + +## AWS KMS adapter + +`simpleXRPL` ships a secp256k1 port for AWS KMS, imported from the `simplexrpl/aws-kms` subpath. It requires the peer dependency `@aws-sdk/client-kms` and an `ECC_SECG_P256K1` (secp256k1) KMS key. Credentials come from the standard AWS chain. + +### Signature + +```ts +AwsKmsSigner.create(options: AwsKmsSignerOptions): AwsKmsSigner +``` + +### Options + +| Field | Type | Required | Description | +| --- | --- | --- | --- | +| `keyId` | `string` | Yes | The KMS key id or ARN. Must be an `ECC_SECG_P256K1` (secp256k1) key. | +| `client` | `object` | No | A pre-built AWS KMS client — a `KMSClient` from `@aws-sdk/client-kms`. Provide this, or `region` to construct the default. | +| `region` | `string` | No | AWS region, used to construct the default client when `client` is omitted. | + + +## Example + +```ts +// Sign with a key held in AWS KMS — the private key never leaves KMS. +import { AwsKmsSigner } from 'simplexrpl/aws-kms' +import { ExternalSigner } from 'simplexrpl' + +const signer = AwsKmsSigner.create({ + keyId: process.env.AWS_KMS_KEY_ID ?? '', + region: process.env.AWS_REGION ?? 'us-east-1', +}) + +// The XRPL account is derived from the key's public key. +const external = await ExternalSigner.create({ signer }) +``` diff --git a/docs/simpleXRPL/references/connectors/index.md b/docs/simpleXRPL/references/connectors/index.md index 0d59d81e..9ba8585e 100644 --- a/docs/simpleXRPL/references/connectors/index.md +++ b/docs/simpleXRPL/references/connectors/index.md @@ -1,6 +1,6 @@ --- seo: - description: A connector is a signing backend in simpleXRPL — LocalSigner, RippleCustody, or PalisadeCustody — constructed on its own and bound to the client at initialization. + description: A connector is a signing backend in simpleXRPL — LocalSigner, ExternalSigner, RippleCustody, or PalisadeCustody — constructed on its own and bound to the client at initialization. labels: - simpleXRPL - SDK @@ -11,5 +11,6 @@ labels: A connector is a signing backend: it determines how an operation runs and which custodian holds your account keys. Each is constructed and authenticated on its own, then passed to the client constructed by `simpleXRPL` in a `signers` array. `simpleXRPL` supports these connectors: - [Local](./local.md) +- [External](./external.md) - [Ripple Custody](./ripple-custody.md) - [Palisade](./palisade.md) diff --git a/docs/simpleXRPL/references/index.md b/docs/simpleXRPL/references/index.md index b5de07e4..679e828a 100644 --- a/docs/simpleXRPL/references/index.md +++ b/docs/simpleXRPL/references/index.md @@ -33,7 +33,7 @@ Operations are grouped into domain-specific **verticals**, one per area of XRPL ## Connectors -The connector is the execution model. It determines how operations run and who holds the keys. See [Connectors](connectors/index.md) for each connector ([LocalSigner](connectors/local.md), [RippleCustody](connectors/ripple-custody.md), [PalisadeCustody](connectors/palisade.md)) and its configuration fields, and [Operation Execution](../index.md#operation-execution) for how each operation routes. +The connector is the execution model. It determines how operations run and who holds the keys. See [Connectors](connectors/index.md) for each connector ([LocalSigner](connectors/local.md), [ExternalSigner](connectors/external.md), [RippleCustody](connectors/ripple-custody.md), [PalisadeCustody](connectors/palisade.md)) and its configuration fields, and [Operation Execution](../index.md#operation-execution) for how each operation routes. ## Amounts and assets diff --git a/sidebars.yaml b/sidebars.yaml index 9a2cc794..0ec17497 100644 --- a/sidebars.yaml +++ b/sidebars.yaml @@ -25,6 +25,7 @@ expanded: false items: - page: docs/simpleXRPL/references/connectors/local.md + - page: docs/simpleXRPL/references/connectors/external.md - page: docs/simpleXRPL/references/connectors/ripple-custody.md - page: docs/simpleXRPL/references/connectors/palisade.md - page: docs/simpleXRPL/references/connectors/connector-routing.md From 52bc4b40464fb7c0540821846362577217391526 Mon Sep 17 00:00:00 2001 From: Oliver Eggert Date: Mon, 27 Jul 2026 17:09:20 -0700 Subject: [PATCH 17/24] address reviewer comments and add links to api key docs --- docs/simpleXRPL/references/connectors/palisade.md | 2 +- docs/simpleXRPL/references/connectors/ripple-custody.md | 2 +- docs/simpleXRPL/tutorials/issue-and-distribute-iou.md | 2 +- docs/simpleXRPL/tutorials/issue-rwa-as-mpt.md | 2 +- 4 files changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/simpleXRPL/references/connectors/palisade.md b/docs/simpleXRPL/references/connectors/palisade.md index 22342bd4..952949ed 100644 --- a/docs/simpleXRPL/references/connectors/palisade.md +++ b/docs/simpleXRPL/references/connectors/palisade.md @@ -10,7 +10,7 @@ labels: [[Source]](https://github.com/ripple/simpleXRPL/blob/50619258cf753008e8a185eaeb3ceca489e5998a/src/custodians/palisade/config.ts#L10) -Palisade is a Wallet-as-a-Service. This connector authenticates via OAuth2 client credentials and acts on specific vaults/wallets. +Palisade is a Wallet-as-a-Service. This connector authenticates via OAuth2 client credentials and acts on specific vaults/wallets. See: [Getting started with the API](https://docs.ripple.com/products/wallet/getting-started/getting-started-api) for instructions on creating API credentials to fill in this constructor. ## PalisadeCustody.create() diff --git a/docs/simpleXRPL/references/connectors/ripple-custody.md b/docs/simpleXRPL/references/connectors/ripple-custody.md index 1fb2c2e8..03974541 100644 --- a/docs/simpleXRPL/references/connectors/ripple-custody.md +++ b/docs/simpleXRPL/references/connectors/ripple-custody.md @@ -10,7 +10,7 @@ labels: [[Source]](https://github.com/ripple/simpleXRPL/blob/50619258cf753008e8a185eaeb3ceca489e5998a/src/custodians/ripple/construction.ts#L30) -Ripple Custody authenticates with an intent-author key exchanged for a token. A Custody deployment is per-tenant, so its gateway and token URLs point at the instance provisioned for you. +Ripple Custody authenticates with an intent-author key exchanged for a token. A Custody deployment is per-tenant, so its gateway and token URLs point at the instance provisioned for you. See: [Generate a key pair and register a public key](https://docs.ripple.com/products/custody/identity-and-access/authentication/generate-api-keys-and-register) for instructions on creating API credentials to fill in this constructor. ## RippleCustody.create() diff --git a/docs/simpleXRPL/tutorials/issue-and-distribute-iou.md b/docs/simpleXRPL/tutorials/issue-and-distribute-iou.md index df3137d0..c02dd900 100644 --- a/docs/simpleXRPL/tutorials/issue-and-distribute-iou.md +++ b/docs/simpleXRPL/tutorials/issue-and-distribute-iou.md @@ -8,7 +8,7 @@ labels: # Issue And Distribute An IOU -`issue` bootstraps the issuer and a hot wallet from the environment (the issuer enables rippling and the hot wallet extends a trust line). No value exists until `transfer` sends the currency out. Every verb acts as the issuer, selected via `from`. +`issue` bootstraps the issuer and a hot wallet from the environment (the issuer enables rippling and the hot wallet extends a trust line). No value exists until `transfer` sends the currency out. Every verb acts as the issuer, selected via `from`. The XRP Ledger supports two token standards (MPT and trust line tokens). MPTs have been designed for greater efficiency and ease of use based on lessons learned from trust line tokens, however there are some cases where you may prefer trust line tokens. See: [Which Fungible Token Type to Use](https://xrpl.org/docs/concepts/tokens/fungible-tokens#which-fungible-token-type-to-use). ```ts /** diff --git a/docs/simpleXRPL/tutorials/issue-rwa-as-mpt.md b/docs/simpleXRPL/tutorials/issue-rwa-as-mpt.md index f9405785..07a0c767 100644 --- a/docs/simpleXRPL/tutorials/issue-rwa-as-mpt.md +++ b/docs/simpleXRPL/tutorials/issue-rwa-as-mpt.md @@ -8,7 +8,7 @@ labels: # Issue An RWA As An MPT -Real-World Assets are issued as Multi-Purpose Tokens (MPTs) via the `token` vertical. Here the issuer is a Ripple Custody account, so Custody signs and submits the issuance as one governed action, with XLS-89 metadata validated before submission. +Real-World Assets are issued as Multi-Purpose Tokens (MPTs) via the `token` vertical. Here the issuer is a Ripple Custody account, so Custody signs and submits the issuance as one governed action, with XLS-89 metadata validated before submission. The XRP Ledger supports to token standards (MPT and trust line tokens). MPTs have been designed for greater efficiency and ease of use based on lessons learned from trust line tokens, however there are some cases where you may prefer trust line tokens. See: [Which Fungible Token Type to Use](https://xrpl.org/docs/concepts/tokens/fungible-tokens#which-fungible-token-type-to-use). ```ts /** From a965b590b9aaea6c5212a98bfcbc5a7c68c7f49b Mon Sep 17 00:00:00 2001 From: Oliver Eggert Date: Mon, 27 Jul 2026 17:48:01 -0700 Subject: [PATCH 18/24] move client info to its own page --- docs/simpleXRPL/references/client.md | 99 ++++++++++++++++++++++++++++ docs/simpleXRPL/references/index.md | 9 +-- sidebars.yaml | 1 + 3 files changed, 101 insertions(+), 8 deletions(-) create mode 100644 docs/simpleXRPL/references/client.md diff --git a/docs/simpleXRPL/references/client.md b/docs/simpleXRPL/references/client.md new file mode 100644 index 00000000..bd41bd5c --- /dev/null +++ b/docs/simpleXRPL/references/client.md @@ -0,0 +1,99 @@ +--- +seo: + description: The simpleXRPL client is the runtime entry point — SimpleXRPL.init() builds it, and it exposes the verticals, the discovered accounts, and the ledger connection lifecycle. +labels: + - simpleXRPL + - SDK +--- + +# Client + +[[Source]](https://github.com/ripple/simpleXRPL/blob/50619258cf753008e8a185eaeb3ceca489e5998a/src/client/client.ts#L42) + +`SimpleXRPL.init()` is `simpleXRPL`'s entry point, and it resolves to a **`SimpleXRPLClient`** — the runtime client. The client binds your pre-constructed [connectors](./connectors/index.md) to a network, discovers the accounts they hold, and exposes the [verticals](./verticals/index.md) you call to build operations. Its network connection and connector configuration are fixed for its lifetime. + +A client constructed with no signers is still fully usable for reads; every write operation throws `NoSignerError` until a connector owns the target account. + + +## SimpleXRPL.init() + +Bind connectors to a network and discover their accounts. Resolves to a `SimpleXRPLClient`. + +### Signature + +```ts +SimpleXRPL.init(config: SimpleXRPLConfig): Promise +``` + +### Config + +| Field | Type | Required | Description | +| --- | --- | --- | --- | +| `rippledUrl` | `string` | Yes | The rippled endpoint (`ws(s)://` or `http(s)://`). | +| `faucetUrl` | `string` | No | Faucet endpoint, used on test networks only. | +| `signers` | `array` | No | The pre-constructed connectors (a `Custodian[]`). Omit for a no-signer client that can still read the ledger; write verbs then throw `NoSignerError` until a signer is added. | +| `primarySigner` | `object` | No | The default connector for verbs called without an explicit account. Defaults to the first entry in `signers`. | +| `ledger` | `object` | No | Advanced: the ledger connection used for reads, autofill, and Local/raw submission. Defaults to a connection built from `rippledUrl`; inject a fake in tests. | + + +## SimpleXRPLClient + +### Properties + +Read-only members of the `SimpleXRPLClient` that `SimpleXRPL.init()` returns, set at construction. + +| Property | Type | Description | +| --- | --- | --- | +| `network` | `object` | The network the client is bound to — a `NetworkInfo` with `rippledUrl` (and `faucetUrl` on test networks). | +| `signers` | `array` | The registered connectors, 0 or more (a `Custodian[]`). | +| `primarySigner` | `object` | The default connector, used when a verb is called without an explicit account. `undefined` on a no-signer client. | +| `accounts` | `object` | Every discovered account as a read-only map keyed by r-address (`ReadonlyMap`). | +| `ledger` | `object` | The shared ledger connection for reads, autofill, and Local/raw submission. Created lazily from `network.rippledUrl` when none was injected. | +| `intent` | `object` | Read-only inspector for custodian governance intents (status/await). | + + +### connect() + +Open the ledger connection. + +```ts +SimpleXRPLClient.connect(): Promise +``` + +### disconnect() + +Close the ledger connection and release its resources. + +```ts +SimpleXRPLClient.disconnect(): Promise +``` + +### refreshAccounts() + +Re-discover every connector's accounts and rebuild the account index. New accounts become addressable; accounts removed upstream are gone on the next lookup. Throws `AmbiguousAccountError` if an r-address is claimed by two connectors. + +```ts +SimpleXRPLClient.refreshAccounts(): Promise +``` + +### primaryAddress() + +The primary connector's account address, or `undefined` on a no-signer client. Reads default to this; it never throws, so queries work without a signer. + +```ts +SimpleXRPLClient.primaryAddress(): string | undefined +``` + + +## Example + +```ts +import { SimpleXRPL, LocalSigner } from 'simplexrpl' + +const client = await SimpleXRPL.init({ + rippledUrl: 'wss://s.altnet.rippletest.net:51233', // XRPL Testnet + signers: [LocalSigner.fromEnv()], +}) + +await client.disconnect() +``` diff --git a/docs/simpleXRPL/references/index.md b/docs/simpleXRPL/references/index.md index 679e828a..025adfdb 100644 --- a/docs/simpleXRPL/references/index.md +++ b/docs/simpleXRPL/references/index.md @@ -18,14 +18,7 @@ This index covers the public surface only. Internal and testing seams (the dispa ## Client and initialization -The client owns the network connection and the connector configuration, both immutable for its lifetime. - -| Symbol | Description | -| --- | --- | -| `SimpleXRPL` | The entry point. `SimpleXRPL.init(...)` establishes the network, connector, and account bindings. | -| `SimpleXRPLClient` | The runtime client returned by `init`; exposes the verticals. | -| `SimpleXRPLConfig` | The initialization configuration shape (network, connector, accounts). | -| `NetworkInfo` | Resolved network details for the connected client. | +`SimpleXRPL.init(...)` establishes the network, connector, and account bindings and returns the runtime client, which owns the network connection and connector configuration (both immutable for its lifetime) and exposes the verticals. See [Client](client.md) for the initialization config and the full client surface — its properties, verticals, and methods. ## Verticals diff --git a/sidebars.yaml b/sidebars.yaml index 0ec17497..cfb1dc15 100644 --- a/sidebars.yaml +++ b/sidebars.yaml @@ -20,6 +20,7 @@ page: docs/simpleXRPL/references/index.md expanded: false items: + - page: docs/simpleXRPL/references/client.md - group: Connectors page: docs/simpleXRPL/references/connectors/index.md expanded: false From 5e385d6b00007e9d61a6fb9418d7c23a47d96f91 Mon Sep 17 00:00:00 2001 From: Oliver Eggert Date: Mon, 27 Jul 2026 18:15:00 -0700 Subject: [PATCH 19/24] move amount type to relevant pages --- docs/_snippets/simplexrpl-amount.md | 16 ++++++++ docs/simpleXRPL/references/index.md | 39 +------------------ .../references/verticals/token/createOffer.md | 2 + .../references/verticals/token/transfer.md | 4 +- 4 files changed, 22 insertions(+), 39 deletions(-) create mode 100644 docs/_snippets/simplexrpl-amount.md diff --git a/docs/_snippets/simplexrpl-amount.md b/docs/_snippets/simplexrpl-amount.md new file mode 100644 index 00000000..d605e52e --- /dev/null +++ b/docs/_snippets/simplexrpl-amount.md @@ -0,0 +1,16 @@ +The `Amount` type pairs a value with the asset it denominates: + +```ts +interface Amount { + asset: Asset // what is being moved + value: string // the quantity, as a decimal string in display units (e.g., '10.5') +} +``` + +Build the `asset` field with one of the asset constructors: + +| Constructor | Description | +| --- | --- | +| `XRP_ASSET` | XRP | +| `iou(currency, issuer)` | IOUs: `currency` is a 3-character code or 40-character hex; `issuer` is the issuer's r-address. | +| `mpt(mptIssuanceId, scale?)` | MPTs: `scale` is the decimal places between the display value and on-ledger base units (default `0`). | diff --git a/docs/simpleXRPL/references/index.md b/docs/simpleXRPL/references/index.md index 025adfdb..a22126b6 100644 --- a/docs/simpleXRPL/references/index.md +++ b/docs/simpleXRPL/references/index.md @@ -8,7 +8,7 @@ labels: # Reference -This section is the map of simpleXRPL's public API surface: the client entry point, the business-intent verticals, the custodian connectors, the amount and asset model, submission results, and the error hierarchy. Complete type-level signatures for every symbol are generated from the source with TypeDoc; the tables below are the curated index of what you actually build against. +This section is the map of `simpleXRPL`'s public API surface: the client entry point, the business-intent verticals, the custodian connectors, the amount and asset model, submission results, and the error hierarchy. Complete type-level signatures for every symbol are generated from the source with TypeDoc; the tables below are the curated index of what you actually build against. New to simpleXRPL? Start with [What is simpleXRPL](../index.md) for the concepts, then [Get Started](../get-started.md) to install and connect a custodian. @@ -16,43 +16,6 @@ New to simpleXRPL? Start with [What is simpleXRPL](../index.md) for the concepts This index covers the public surface only. Internal and testing seams (the dispatch pipeline, injected I/O ports, and the production ledger port) are intentionally omitted — you don't call them directly. {% /admonition %} -## Client and initialization - -`SimpleXRPL.init(...)` establishes the network, connector, and account bindings and returns the runtime client, which owns the network connection and connector configuration (both immutable for its lifetime) and exposes the verticals. See [Client](client.md) for the initialization config and the full client surface — its properties, verticals, and methods. - -## Verticals - -Operations are grouped into domain-specific **verticals**, one per area of XRPL functionality and reached off the client. See [Verticals](verticals/index.md) for what a vertical is and the full list of verticals and their methods. - -## Connectors - -The connector is the execution model. It determines how operations run and who holds the keys. See [Connectors](connectors/index.md) for each connector ([LocalSigner](connectors/local.md), [ExternalSigner](connectors/external.md), [RippleCustody](connectors/ripple-custody.md), [PalisadeCustody](connectors/palisade.md)) and its configuration fields, and [Operation Execution](../index.md#operation-execution) for how each operation routes. - -## Amounts and assets - -The amount model represents XRP, IOU, and MPT values and handles decimal/scale conversion. - -| Symbol | Description | -| --- | --- | -| `Amount` | A value paired with the asset it denominates. | -| `Asset` | The asset an amount is in (XRP, IOU, or MPT). | -| `XRP_ASSET` | The canonical XRP asset constant. | -| `iou(currency, issuer)` | Construct an issued-currency asset. | -| `mpt(mptIssuanceId, scale?)` | Construct an MPT asset; `scale` is the decimal places between display value and on-ledger base units. | -| `toLedgerAmount` / `fromLedgerAmount` | Convert between display amounts and on-ledger base units. | -| `LedgerAmount` | The on-ledger (base-unit) amount representation. | - -## Results and handles - -| Symbol | Description | -| --- | --- | -| `SubmissionResult` | The terminal result of an operation; carries the discriminated `source`/`response` pairing and the vertical's typed `intent` output. | -| `SubmissionResultFields` | The common fields present on every submission result. | -| `SubmissionPath` | Which path the operation took (native vs. raw-signing). | -| `SubmissionHandle` | Handle over an asynchronously-submitted operation, for flows that resolve later. | -| `CustodyTransactionResult` / `PalisadeTransactionResult` | The connector-specific transaction record inside the result. | - -The `*Intent` types (`XrpTransferIntent`, `MptIssueIntent`, `IOUIssueIntent`, `DomainIntent`, and the rest) are the typed `intent` payloads attached to each result. ## Errors diff --git a/docs/simpleXRPL/references/verticals/token/createOffer.md b/docs/simpleXRPL/references/verticals/token/createOffer.md index 7e6ca632..29b59ff4 100644 --- a/docs/simpleXRPL/references/verticals/token/createOffer.md +++ b/docs/simpleXRPL/references/verticals/token/createOffer.md @@ -40,6 +40,8 @@ The `flags` object accepts: | `fillOrKill` | `boolean` | No | Consume the full amount or cancel entirely. | | `sell` | `boolean` | No | Interpret the offer as selling `takerGets`. | +{% raw-partial file="/docs/_snippets/simplexrpl-amount.md" /%} + ## Options {% raw-partial file="/docs/_snippets/simplexrpl-write-options.md" /%} diff --git a/docs/simpleXRPL/references/verticals/token/transfer.md b/docs/simpleXRPL/references/verticals/token/transfer.md index 2ddac822..02f6158e 100644 --- a/docs/simpleXRPL/references/verticals/token/transfer.md +++ b/docs/simpleXRPL/references/verticals/token/transfer.md @@ -26,7 +26,9 @@ token.transfer( | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `to` | `string` | Yes | Destination r-address. | -| `amount` | `Amount` | Yes | The MPT amount to send. Its asset must be an MPT (build one with `mpt()`; see the [amount model](../../index.md#amounts-and-assets)). | +| `amount` | `Amount` | Yes | The MPT amount to send; its asset must be an MPT (build it with `mpt()`). | + +{% raw-partial file="/docs/_snippets/simplexrpl-amount.md" /%} ## Options From bf2a67c35f01a75f0ede933962b75843e78b560b Mon Sep 17 00:00:00 2001 From: Oliver Eggert Date: Mon, 27 Jul 2026 18:18:31 -0700 Subject: [PATCH 20/24] add errors page --- docs/simpleXRPL/references/errors.md | 25 +++++++++++++++++++++++++ docs/simpleXRPL/references/index.md | 27 --------------------------- sidebars.yaml | 1 + 3 files changed, 26 insertions(+), 27 deletions(-) create mode 100644 docs/simpleXRPL/references/errors.md diff --git a/docs/simpleXRPL/references/errors.md b/docs/simpleXRPL/references/errors.md new file mode 100644 index 00000000..2824edc9 --- /dev/null +++ b/docs/simpleXRPL/references/errors.md @@ -0,0 +1,25 @@ +--- +seo: + description: The simpleXRPL client errors. +labels: + - simpleXRPL + - SDK +--- + +# Errors + +All errors extend `SimpleXRPLError`, so you can catch the base class or narrow to a specific type. + +| Error | Description | +| --- | --- | +| `SimpleXRPLError` | Base class for every SDK error. | +| `NoSignerError` | No signer/connector owns the target account. | +| `SignerCapabilityError` | The operation can't be signed on this connector (native path missing, or raw signing not enabled). | +| `AccountNotFoundError` | The referenced account is not bound to the client. | +| `AmbiguousAccountError` | The account reference matches more than one bound account. | +| `RippledSubmitError` | The transaction reached a terminal on-ledger failure (non-`tesSUCCESS`). | +| `IntentPendingError` | A custodian intent is still awaiting approval when a terminal result was expected. | +| `IntentValidationError` | A custodian rejected the intent as invalid. | +| `MultiStepFailureError` | A multi-step operation failed partway through. | +| `CustodyApiError` / `CustodyAuthError` | Ripple Custody API or authentication failure. | +| `PalisadeApiError` / `PalisadeAuthError` | Palisade API or authentication failure. | \ No newline at end of file diff --git a/docs/simpleXRPL/references/index.md b/docs/simpleXRPL/references/index.md index a22126b6..fea4072b 100644 --- a/docs/simpleXRPL/references/index.md +++ b/docs/simpleXRPL/references/index.md @@ -15,30 +15,3 @@ New to simpleXRPL? Start with [What is simpleXRPL](../index.md) for the concepts {% admonition type="info" name="Note" %} This index covers the public surface only. Internal and testing seams (the dispatch pipeline, injected I/O ports, and the production ledger port) are intentionally omitted — you don't call them directly. {% /admonition %} - - -## Errors - -All errors extend `SimpleXRPLError`, so you can catch the base class or narrow to a specific type. - -| Error | Raised when | -| --- | --- | -| `SimpleXRPLError` | Base class for every SDK error. | -| `NoSignerError` | No signer/connector owns the target account. | -| `SignerCapabilityError` | The operation can't be signed on this connector (native path missing, or raw signing not enabled). | -| `AccountNotFoundError` | The referenced account is not bound to the client. | -| `AmbiguousAccountError` | The account reference matches more than one bound account. | -| `RippledSubmitError` | The transaction reached a terminal on-ledger failure (non-`tesSUCCESS`). | -| `IntentPendingError` | A custodian intent is still awaiting approval when a terminal result was expected. | -| `IntentValidationError` | A custodian rejected the intent as invalid. | -| `MultiStepFailureError` | A multi-step operation failed partway through. | -| `CustodyApiError` / `CustodyAuthError` | Ripple Custody API or authentication failure. | -| `PalisadeApiError` / `PalisadeAuthError` | Palisade API or authentication failure. | - -## Related reference - -Companion reference pages that live alongside this index: - -- **Function-to-transactor mapping** — the underlying XRPL transactor(s) each method expands into (also shown inline on each method page). -- [**Connector routing table**](connectors/connector-routing.md) — per operation and per connector, whether it routes native, requires raw-signing fallback, or is unavailable. -- **Institutional defaults** — the full set of defaults the SDK applies unless overridden. diff --git a/sidebars.yaml b/sidebars.yaml index cfb1dc15..bccc7186 100644 --- a/sidebars.yaml +++ b/sidebars.yaml @@ -148,6 +148,7 @@ label: retrieve() - page: docs/simpleXRPL/references/verticals/account/listOffers.md label: listOffers() + - page: docs/simpleXRPL/references/errors.md - group: Amendments expanded: false items: From 3d7c49909a69ce3a8fa6e060e34910d4cebeb09e Mon Sep 17 00:00:00 2001 From: Oliver Eggert Date: Mon, 27 Jul 2026 18:23:53 -0700 Subject: [PATCH 21/24] update error page --- docs/simpleXRPL/references/errors.md | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/docs/simpleXRPL/references/errors.md b/docs/simpleXRPL/references/errors.md index 2824edc9..5335cbc2 100644 --- a/docs/simpleXRPL/references/errors.md +++ b/docs/simpleXRPL/references/errors.md @@ -8,6 +8,8 @@ labels: # Errors +[[Source]](https://github.com/ripple/simpleXRPL/blob/50619258cf753008e8a185eaeb3ceca489e5998a/src/errors.ts#L8) + All errors extend `SimpleXRPLError`, so you can catch the base class or narrow to a specific type. | Error | Description | @@ -17,9 +19,12 @@ All errors extend `SimpleXRPLError`, so you can catch the base class or narrow t | `SignerCapabilityError` | The operation can't be signed on this connector (native path missing, or raw signing not enabled). | | `AccountNotFoundError` | The referenced account is not bound to the client. | | `AmbiguousAccountError` | The account reference matches more than one bound account. | +| `DuplicateSignerError` | Two signers target the same backend tenant (same kind and tenant id); rejected at `init`. | | `RippledSubmitError` | The transaction reached a terminal on-ledger failure (non-`tesSUCCESS`). | | `IntentPendingError` | A custodian intent is still awaiting approval when a terminal result was expected. | | `IntentValidationError` | A custodian rejected the intent as invalid. | | `MultiStepFailureError` | A multi-step operation failed partway through. | -| `CustodyApiError` / `CustodyAuthError` | Ripple Custody API or authentication failure. | -| `PalisadeApiError` / `PalisadeAuthError` | Palisade API or authentication failure. | \ No newline at end of file +| `CustodyAuthError` | Authenticating with Ripple Custody failed (challenge/JWT exchange or refresh). | +| `CustodyApiError` | A Ripple Custody API call returned an error (HTTP status, `hint`, and raw body preserved). | +| `PalisadeAuthError` | Authenticating with Palisade failed (API key). | +| `PalisadeApiError` | A Palisade API call returned an error (HTTP status, `hint`, and raw body preserved). | From dc449f432c8a161e96685eaf8001c4c3c64fd3b0 Mon Sep 17 00:00:00 2001 From: Oliver Eggert Date: Mon, 27 Jul 2026 18:25:48 -0700 Subject: [PATCH 22/24] remove reference index page --- docs/simpleXRPL/references/index.md | 17 ----------------- sidebars.yaml | 1 - 2 files changed, 18 deletions(-) delete mode 100644 docs/simpleXRPL/references/index.md diff --git a/docs/simpleXRPL/references/index.md b/docs/simpleXRPL/references/index.md deleted file mode 100644 index fea4072b..00000000 --- a/docs/simpleXRPL/references/index.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -seo: - description: Reference index for the simpleXRPL SDK — its verticals, connectors, the amount and asset model, submission results, and the error hierarchy. -labels: - - simpleXRPL - - SDK ---- - -# Reference - -This section is the map of `simpleXRPL`'s public API surface: the client entry point, the business-intent verticals, the custodian connectors, the amount and asset model, submission results, and the error hierarchy. Complete type-level signatures for every symbol are generated from the source with TypeDoc; the tables below are the curated index of what you actually build against. - -New to simpleXRPL? Start with [What is simpleXRPL](../index.md) for the concepts, then [Get Started](../get-started.md) to install and connect a custodian. - -{% admonition type="info" name="Note" %} -This index covers the public surface only. Internal and testing seams (the dispatch pipeline, injected I/O ports, and the production ledger port) are intentionally omitted — you don't call them directly. -{% /admonition %} diff --git a/sidebars.yaml b/sidebars.yaml index bccc7186..7cfbe51e 100644 --- a/sidebars.yaml +++ b/sidebars.yaml @@ -17,7 +17,6 @@ - page: docs/simpleXRPL/tutorials/implement-aws-kms-signer.md - page: docs/simpleXRPL/tutorials/implement-pkcs11-signer.md - group: References - page: docs/simpleXRPL/references/index.md expanded: false items: - page: docs/simpleXRPL/references/client.md From 65a80086b8f77a2fd10a10ad25a27f4f0f3a5d7f Mon Sep 17 00:00:00 2001 From: Oliver Eggert Date: Thu, 30 Jul 2026 15:30:51 -0700 Subject: [PATCH 23/24] update code samples --- docs/simpleXRPL/get-started.md | 2 +- .../connectors/connector-routing.md | 83 ++++++- docs/simpleXRPL/references/verticals/index.md | 2 +- .../tutorials/create-permissioned-domain.md | 2 +- .../tutorials/cross-custodian-workflows.md | 64 ++---- docs/simpleXRPL/tutorials/external-signer.md | 131 +++++------ .../tutorials/implement-aws-kms-signer.md | 2 +- .../tutorials/implement-pkcs11-signer.md | 204 ++++++++---------- .../tutorials/issue-and-distribute-iou.md | 76 ++++--- docs/simpleXRPL/tutorials/issue-rwa-as-mpt.md | 40 ++-- docs/simpleXRPL/tutorials/place-dex-order.md | 2 +- 11 files changed, 297 insertions(+), 311 deletions(-) diff --git a/docs/simpleXRPL/get-started.md b/docs/simpleXRPL/get-started.md index 979bde61..a3301b76 100644 --- a/docs/simpleXRPL/get-started.md +++ b/docs/simpleXRPL/get-started.md @@ -76,7 +76,7 @@ Operations are grouped into domain-specific verticals reached off the client. Th - **References**: - [LocalSigner.fromEnv()](./references/connectors/local.md#localsignerfromenv) - - [SimpleXRPL.init()](./references/index.md#client-and-initialization) + - [SimpleXRPL.init()](./references/client.md#simplexrplinit) - [account.retrieve()](./references/verticals/account/retrieve.md) - [xrp.transfer()](./references/verticals/xrp/transfer.md) \ No newline at end of file diff --git a/docs/simpleXRPL/references/connectors/connector-routing.md b/docs/simpleXRPL/references/connectors/connector-routing.md index 97efab34..62ce7130 100644 --- a/docs/simpleXRPL/references/connectors/connector-routing.md +++ b/docs/simpleXRPL/references/connectors/connector-routing.md @@ -8,20 +8,26 @@ labels: # Connector Routing -[[Source]](https://github.com/ripple/simpleXRPL/blob/50619258cf753008e8a185eaeb3ceca489e5998a/docs/connector-routing.md) +[[Source]](https://github.com/ripple/simpleXRPL/blob/main/docs/connector-routing.md) -How simpleXRPL dispatches each XRPL transactor per connector. Derived directly from each custodian's native-operation set and the transactors the verticals build, so it always matches the code. +# Connector Routing Table -{% admonition type="info" name="Note" %} -This page is generated from the SDK source by `scripts/gen-connector-routing.mjs` — do not edit by hand. Regenerate with `npm run docgen:routing`. -{% /admonition %} + + +How simpleXRPL dispatches each XRPL transactor per connector. Derived directly +from each custodian's native-operation set and the transactors the verticals +build, so it always matches the code. ## Transactor → connector path -The pipeline routes by transactor type: **Local** signs everything in-process; a custodian uses its **native** operation when the transactor is in its capability set, otherwise the **raw** sign-only fallback, otherwise the write is rejected. +The pipeline routes by transactor type: **Local** signs everything in-process; +a custodian uses its **native** operation when the transactor is in its +capability set, otherwise the **raw** sign-only fallback, otherwise the write +is rejected. | Transactor | Local | Ripple Custody | Palisade | -| --- | --- | --- | --- | +| ------ | ------ | ------ | ------ | | `AccountSet` | signs locally | **native** | **native** | | `Clawback` | signs locally | **native** | **native** | | `CredentialAccept` | signs locally | raw fallback¹ | raw fallback¹ | @@ -41,14 +47,19 @@ The pipeline routes by transactor type: **Local** signs everything in-process; a | `SetRegularKey` | signs locally | raw fallback¹ | raw fallback¹ | | `TrustSet` | signs locally | **native** | **native** | -¹ **raw fallback** applies only when raw signing is enabled on that custodian (`allowRawSigning`). With raw signing disabled, a non-native transactor is rejected with `SignerCapabilityError` — use a Local account or a custodian that natively supports it. The raw path signs the encoded transaction and submits it through the shared XRPL connection. +¹ **raw fallback** applies only when raw signing is enabled on that custodian +(`allowRawSigning`). With raw signing disabled, a non-native transactor is +rejected with `SignerCapabilityError` — use a Local account or a custodian +that natively supports it. The raw path signs the encoded transaction and +submits it through the shared XRPL connection. ## Vertical → transactors -Which XRPL transactors each vertical builds. Cross-reference with the table above to see how a given method routes on each connector. +Which XRPL transactors each vertical builds. Cross-reference with the table +above to see how a given method routes on each connector. | Vertical | Transactors emitted | -| --- | --- | +| ------ | ------ | | `account` | `AccountSet`, `DepositPreauth`, `Payment`, `SetRegularKey` | | `credential` | `CredentialAccept`, `CredentialCreate`, `CredentialDelete` | | `domain` | `PermissionedDomainDelete`, `PermissionedDomainSet` | @@ -56,6 +67,56 @@ Which XRPL transactors each vertical builds. Cross-reference with the table abov | `token` | `MPTokenAuthorize`, `MPTokenIssuanceCreate`, `MPTokenIssuanceDestroy`, `MPTokenIssuanceSet`, `OfferCancel`, `OfferCreate`, `Payment` | | `xrp` | `Payment` | +## Operation → native support + +Each simpleXRPL write operation, the XRPL transactor(s) it emits, and whether +that operation is **native** on each custodian (all its transactors are in the +custodian's native-ops set) or falls back to **raw** signing. Local signs every +operation in-process. Read operations emit no transactor and are omitted. + +| Operation | Transactor(s) | Ripple Custody | Palisade | +| ------ | ------ | ------ | ------ | +| `XRP.transfer()` | `Payment` | **native** | **native** | +| `IOU.issue()` | `TrustSet`, `AccountSet` | **native** | **native** | +| `IOU.authorize()` | `TrustSet` | **native** | **native** | +| `IOU.lock()` | `TrustSet` | **native** | **native** | +| `IOU.unlock()` | `TrustSet` | **native** | **native** | +| `IOU.clawback()` | `Clawback` | **native** | **native** | +| `IOU.transfer()` | `Payment` | **native** | **native** | +| `IOU.buyOffer()` | `OfferCreate` | **native** | **native** | +| `IOU.sellOffer()` | `OfferCreate` | **native** | **native** | +| `IOU.cancelOffer()` | `OfferCancel` | raw fallback¹ | **native** | +| `Token.issue()` | `MPTokenIssuanceCreate` | **native** | raw fallback¹ | +| `Token.authorize()` | `MPTokenAuthorize` | **native** | raw fallback¹ | +| `Token.unauthorize()` | `MPTokenAuthorize` | **native** | raw fallback¹ | +| `Token.grantHolder()` | `MPTokenAuthorize` | **native** | raw fallback¹ | +| `Token.revokeHolder()` | `MPTokenAuthorize` | **native** | raw fallback¹ | +| `Token.lock()` | `MPTokenIssuanceSet` | **native** | raw fallback¹ | +| `Token.unlock()` | `MPTokenIssuanceSet` | **native** | raw fallback¹ | +| `Token.destroy()` | `MPTokenIssuanceDestroy` | **native** | raw fallback¹ | +| `Token.transfer()` | `Payment` | **native** | raw fallback¹ | +| `Token.createOffer()` | `OfferCreate` | **native** | **native** | +| `Token.cancelOffer()` | `OfferCancel` | raw fallback¹ | **native** | +| `Domain.create()` | `PermissionedDomainSet` | raw fallback¹ | raw fallback¹ | +| `Domain.setCredentials()` | `PermissionedDomainSet` | raw fallback¹ | raw fallback¹ | +| `Domain.delete()` | `PermissionedDomainDelete` | raw fallback¹ | raw fallback¹ | +| `Credential.issue()` | `CredentialCreate` | raw fallback¹ | raw fallback¹ | +| `Credential.accept()` | `CredentialAccept` | raw fallback¹ | raw fallback¹ | +| `Credential.delete()` | `CredentialDelete` | raw fallback¹ | raw fallback¹ | +| `Account.fund()` | `Payment`, `AccountSet` | **native** | **native** | +| `Account.activate()` | `Payment`, `AccountSet` | **native** | **native** | +| `Account.set()` | `AccountSet` | **native** | **native** | +| `Account.setRegularKey()` | `SetRegularKey` | raw fallback¹ | raw fallback¹ | +| `Account.depositPreauth()` | `DepositPreauth` | **native** | raw fallback¹ | + +¹ **raw fallback** applies only when raw signing is enabled on that custodian +(`allowRawSigning`); otherwise the operation is rejected with +`SignerCapabilityError`. A multi-transactor operation (e.g. `IOU.issue`) is +native only when every step is native. **Palisade has no native MPT support**, +so `Token.transfer` — which carries an MPT amount — falls back to raw there +even though `Payment` is otherwise native; Ripple Custody handles MPT natively. + --- -_Native-ops sets: `NATIVE_XRPL_TRANSACTORS` (Ripple Custody), `PALISADE_NATIVE_TRANSACTORS` (Palisade). Local signs all transactors._ +_Native-ops sets: `NATIVE_XRPL_TRANSACTORS` (Ripple Custody), +`PALISADE_NATIVE_TRANSACTORS` (Palisade). Local signs all transactors._ diff --git a/docs/simpleXRPL/references/verticals/index.md b/docs/simpleXRPL/references/verticals/index.md index 30cbbd69..cab6e91a 100644 --- a/docs/simpleXRPL/references/verticals/index.md +++ b/docs/simpleXRPL/references/verticals/index.md @@ -10,7 +10,7 @@ labels: A **vertical** is a domain-specific class that groups related operations — one per area of XRPL functionality. Each vertical's methods are the _business-intent verbs_ for that domain (`token.issue(...)`, `iou.transfer(...)`), and each vertical is reached off the client under a lowercase name (`client.token`, `client.iou`). The term contrasts with _horizontal_ operations that cut across domains, such as payments and batch transactions. -Most vertical methods submit a transaction and resolve to a `Promise>`, where `T` is the method's typed [intent output](../index.md#results-and-handles); they also accept an optional second argument to target a non-primary account and override the fee. (A few helpers differ — for example, `Account.create` generates a keypair and returns synchronously.) Each vertical's page lists its methods; every method has its own page with parameters, response, and the underlying XRPL transactor(s). +Most vertical methods submit a transaction and resolve to a `Promise>`, where `T` is the method's typed intent output; they also accept an optional second argument to target a non-primary account and override the fee. (A few helpers differ — for example, `Account.create` generates a keypair and returns synchronously.) Each vertical's page lists its methods; every method has its own page with parameters, response, and the underlying XRPL transactor(s). | Vertical | Reached as | What it does | | --- | --- | --- | diff --git a/docs/simpleXRPL/tutorials/create-permissioned-domain.md b/docs/simpleXRPL/tutorials/create-permissioned-domain.md index 3de6e28b..dcc61b6f 100644 --- a/docs/simpleXRPL/tutorials/create-permissioned-domain.md +++ b/docs/simpleXRPL/tutorials/create-permissioned-domain.md @@ -21,7 +21,7 @@ A permissioned domain restricts who can participate based on the credentials the import { LocalSigner, SimpleXRPL } from 'simplexrpl' const client = await SimpleXRPL.init({ - rippledUrl: 'wss://s.altnet.rippletest.net:51233', + xrpldUrl: 'wss://s.altnet.rippletest.net:51233', signers: [LocalSigner.fromEnv()], }) diff --git a/docs/simpleXRPL/tutorials/cross-custodian-workflows.md b/docs/simpleXRPL/tutorials/cross-custodian-workflows.md index 3a1a7919..99019860 100644 --- a/docs/simpleXRPL/tutorials/cross-custodian-workflows.md +++ b/docs/simpleXRPL/tutorials/cross-custodian-workflows.md @@ -14,22 +14,11 @@ A single client can drive accounts held by different connectors. Sequence work a /** * Run a workflow across two custodians. * - * A single client can drive accounts held by different connectors. Two ways to - * sequence work across them: - * - * 1. Vertical verbs with `from` — each call routes to the custodian that owns - * the named account. Best for the common case. - * 2. `runMultiStep` — commits an ordered (transaction, account) sequence step - * by step (no rollback), where steps can target different custodians. Best - * when the order matters and you want one call site. + * A single client can drive accounts held by different connectors: each vertical + * operation routes automatically to the custodian that owns the account it acts on — + * named via `from`, or the primary signer by default. */ -import { - PalisadeCustody, - RippleCustody, - runMultiStep, - SimpleXRPL, -} from 'simplexrpl' -import type { Transaction } from 'simplexrpl' +import { PalisadeCustody, RippleCustody, SimpleXRPL } from 'simplexrpl' // A common institutional split: the issuer is held in Ripple Custody (governed // approvals), the distribution/hot wallet in Palisade. One client drives both. @@ -39,8 +28,17 @@ const custody = await RippleCustody.fromEnv({ }) const palisade = await PalisadeCustody.create({ baseUrl: 'https://api.sandbox.palisade.co', // sandbox (TESTNET data) - clientId: process.env.PALISADE_CLIENT_ID ?? '', - clientSecret: process.env.PALISADE_CLIENT_SECRET ?? '', + // Two credentials: a wallet-read one (discovery) and a transactions one. + credentials: { + wallets: { + clientId: process.env.PALISADE_WALLETS_CLIENT_ID ?? '', + clientSecret: process.env.PALISADE_WALLETS_CLIENT_SECRET ?? '', + }, + transactions: { + clientId: process.env.PALISADE_TX_CLIENT_ID ?? '', + clientSecret: process.env.PALISADE_TX_CLIENT_SECRET ?? '', + }, + }, primary: { vaultId: process.env.PALISADE_VAULT_ID ?? '', walletId: process.env.PALISADE_WALLET_ID ?? '', @@ -48,44 +46,22 @@ const palisade = await PalisadeCustody.create({ }) const client = await SimpleXRPL.init({ - rippledUrl: 'wss://s.altnet.rippletest.net:51233', // XRPL Testnet + xrpldUrl: 'wss://s.altnet.rippletest.net:51233', // XRPL Testnet signers: [custody, palisade], }) -// One account on each connector. -const issuer = client.resolveAccount(custody.primary.address) +// The distribution/hot wallet on the Palisade connector. const hotWallet = client.resolveAccount(palisade.primary.address) -// --- Approach 1: vertical verbs, each targeting a different custodian ------ -// Issue an IOU as the Custody issuer, then pay out from the Palisade wallet. +// Each operation targets a different custodian. Issue an IOU as the Custody issuer +// (the primary signer), then pay out from the Palisade hot wallet via `from` — +// the client routes each call to the connector that owns the account. await client.iou.issue({ ticker: 'USD' }) await client.xrp.transfer( { to: 'rBeneficiary00000000000000000000000', amount: '25' }, { from: hotWallet.address }, ) -// --- Approach 2: an ordered multi-step workflow across both ---------------- -const stepOne: Transaction = { - TransactionType: 'Payment', - Account: issuer.address, - Destination: 'rBeneficiary00000000000000000000000', - Amount: '1000000', -} -const stepTwo: Transaction = { - TransactionType: 'Payment', - Account: hotWallet.address, - Destination: 'rBeneficiary00000000000000000000000', - Amount: '2000000', -} - -// Step 1 signs on Ripple Custody, step 2 on Palisade — each routed -// automatically to the connector that owns the account. -const results = await runMultiStep(client, [ - { transaction: stepOne, account: issuer }, - { transaction: stepTwo, account: hotWallet }, -]) -console.log(`workflow committed ${results.length} steps`) - await client.disconnect() ``` diff --git a/docs/simpleXRPL/tutorials/external-signer.md b/docs/simpleXRPL/tutorials/external-signer.md index 291265cd..a1445b38 100644 --- a/docs/simpleXRPL/tutorials/external-signer.md +++ b/docs/simpleXRPL/tutorials/external-signer.md @@ -12,80 +12,34 @@ The `ExternalSignerPort` seam lets you plug in your own signer. This sample impl ```ts /** - * External signing end to end, with a mock signer — and switching algorithms. + * External signing end to end — and switching algorithms. * - * The `ExternalSignerPort` seam covers both XRPL signature schemes. This sample - * implements it with an in-process key (via `@noble/curves`) so it actually - * signs and "submits" a transaction against a mock ledger — handy for local - * tests. In production you swap the mock for a KMS or HSM signer; nothing else - * changes. + * The `ExternalSignerPort` seam covers both XRPL signature schemes; the SDK + * routes the crypto by algorithm (secp256k1: SHA-512Half digest → low-S → DER; + * ed25519: sign the message directly). The procedure below is identical for + * either — you just pass a different port. * - * secp256k1 vs ed25519 is just a different port implementation — pick whichever - * your signer's key uses. The SDK routes the crypto accordingly (secp256k1: - * SHA-512Half digest → low-S → DER; ed25519: sign the message directly). + * As shipped this file is illustrative: the in-process demo signers at the + * bottom are commented out. Uncomment them (or plug in your own KMS/HSM-backed + * `ExternalSignerPort`) for the snippet to run. */ -import { ed25519 } from '@noble/curves/ed25519' -import { secp256k1 } from '@noble/curves/secp256k1' import { ExternalSigner, SimpleXRPL } from 'simplexrpl' import type { Ed25519SignerPort, Secp256k1SignerPort } from 'simplexrpl' import { inMemoryLedger } from './mocks.js' -// --- Mock signers (in-process keys — for local testing only) --------------- - -/** - * A mock secp256k1 signer. A real one delegates the digest to a KMS/HSM. - * - * @param privHex - The 32-byte private key hex (test only). - * @returns The port. - */ -function mockSecp256k1(privHex: string): Secp256k1SignerPort { - const priv = Buffer.from(privHex, 'hex') - return { - algorithm: 'secp256k1', - publicKey: async (): Promise => - Buffer.from(secp256k1.getPublicKey(priv, true)) - .toString('hex') - .toUpperCase(), - signDigest: async (digest: Uint8Array) => { - const sig = secp256k1.sign(digest, priv) - return { r: sig.r, s: sig.s } - }, - } -} - -/** - * A mock ed25519 signer. XRPL prefixes the public key with `ED`. - * - * @param privHex - The 32-byte private key hex (test only). - * @returns The port. - */ -function mockEd25519(privHex: string): Ed25519SignerPort { - const priv = Buffer.from(privHex, 'hex') - return { - algorithm: 'ed25519', - publicKey: async (): Promise => - `ED${Buffer.from(ed25519.getPublicKey(priv)).toString('hex')}`.toUpperCase(), - signMessage: async (message: Uint8Array): Promise => - ed25519.sign(message, priv), - } -} - -/** - * Bind a signer, then build + sign + submit a real transfer through it. - * - * @param signer - The external signer port (either algorithm). - * @param label - A label for the log line. - */ +// === What you write with simpleXRPL === +// Bind your external signer, then build → sign → submit. The pipeline is the +// same whether the signer is secp256k1 or ed25519. async function signAndSubmit( signer: Secp256k1SignerPort | Ed25519SignerPort, label: string, ): Promise { const custody = await ExternalSigner.create({ signer }) const client = await SimpleXRPL.init({ - rippledUrl: 'wss://s.altnet.rippletest.net:51233', + xrpldUrl: 'wss://s.altnet.rippletest.net:51233', // XRPL Testnet signers: [custody], - ledger: inMemoryLedger(), + ledger: inMemoryLedger(), // omit in production to use the live XRPL connection }) const result = await client.xrp.transfer({ to: client.account.create().address, @@ -98,19 +52,52 @@ async function signAndSubmit( await client.disconnect() } -// Switch algorithms by swapping the port — the pipeline is identical. -await signAndSubmit( - mockSecp256k1( - 'c9537c5a2f3f7e1d4b6a8c0e2f4d6b8a1c3e5f7091b3d5f7a9c1e3050709b0d0f', - ), - 'secp256k1', -) -await signAndSubmit( - mockEd25519( - '9d61b19deffebc3a6c1f6b2d7e5f8a0b1c2d3e4f5061728394a5b6c7d8e9f001', - ), - 'ed25519', -) +// === Demo signers — uncomment to run, or replace with your own KMS/HSM === +// These use in-process keys via `@noble/curves` so the file runs offline; a +// real port delegates the digest/message to your KMS or HSM. Switch algorithms +// by swapping the port — `signAndSubmit` above doesn't change. +// +// import { ed25519 } from '@noble/curves/ed25519' +// import { secp256k1 } from '@noble/curves/secp256k1' +// +// function mockSecp256k1(privHex: string): Secp256k1SignerPort { +// const priv = Buffer.from(privHex, 'hex') +// return { +// algorithm: 'secp256k1', +// publicKey: async (): Promise => +// Buffer.from(secp256k1.getPublicKey(priv, true)) +// .toString('hex') +// .toUpperCase(), +// signDigest: async (digest: Uint8Array) => { +// const sig = secp256k1.sign(digest, priv) +// return { r: sig.r, s: sig.s } +// }, +// } +// } +// +// function mockEd25519(privHex: string): Ed25519SignerPort { +// const priv = Buffer.from(privHex, 'hex') +// return { +// algorithm: 'ed25519', +// publicKey: async (): Promise => +// `ED${Buffer.from(ed25519.getPublicKey(priv)).toString('hex')}`.toUpperCase(), +// signMessage: async (message: Uint8Array): Promise => +// ed25519.sign(message, priv), +// } +// } +// +// await signAndSubmit( +// mockSecp256k1( +// 'c9537c5a2f3f7e1d4b6a8c0e2f4d6b8a1c3e5f7091b3d5f7a9c1e3050709b0d0f', +// ), +// 'secp256k1', +// ) +// await signAndSubmit( +// mockEd25519( +// '9d61b19deffebc3a6c1f6b2d7e5f8a0b1c2d3e4f5061728394a5b6c7d8e9f001', +// ), +// 'ed25519', +// ) ``` ## See Also diff --git a/docs/simpleXRPL/tutorials/implement-aws-kms-signer.md b/docs/simpleXRPL/tutorials/implement-aws-kms-signer.md index 38b6f758..e2b2ddc9 100644 --- a/docs/simpleXRPL/tutorials/implement-aws-kms-signer.md +++ b/docs/simpleXRPL/tutorials/implement-aws-kms-signer.md @@ -33,7 +33,7 @@ const signer = AwsKmsSigner.create({ const custody = await ExternalSigner.create({ signer }) const client = await SimpleXRPL.init({ - rippledUrl: 'wss://s.altnet.rippletest.net:51233', // XRPL Testnet + xrpldUrl: 'wss://s.altnet.rippletest.net:51233', // XRPL Testnet signers: [custody], }) diff --git a/docs/simpleXRPL/tutorials/implement-pkcs11-signer.md b/docs/simpleXRPL/tutorials/implement-pkcs11-signer.md index 141baaaa..5004aed6 100644 --- a/docs/simpleXRPL/tutorials/implement-pkcs11-signer.md +++ b/docs/simpleXRPL/tutorials/implement-pkcs11-signer.md @@ -15,134 +15,98 @@ For an HSM, you implement the same `ExternalSignerPort` seam against your device * Bring-your-own HSM signer (PKCS#11). * * simpleXRPL ships an AWS KMS adapter (`simplexrpl/aws-kms`); for an HSM you - * implement the same `ExternalSignerPort` seam against your device. HSM setups - * vary (slot, PIN, key label, vendor library), so this is a reference to adapt - * rather than a drop-in — the SDK owns the XRPL crypto (SHA-512Half digest, - * low-S normalization, DER encoding); you only provide "give me the public key" - * and "sign this digest". + * implement the same `ExternalSignerPort` seam against your device. The SDK owns + * the XRPL crypto (SHA-512Half digest, low-S normalization, DER encoding); your + * port only provides "give me the public key" and "sign this digest". * - * Wire the `Hsm` interface below to your PKCS#11 binding (e.g. `pkcs11js` or - * `graphene-lib`); the exact calls are noted per method. + * As shipped this file is illustrative: the PKCS#11 adapter and its in-process + * demo HSM at the bottom are commented out. Uncomment them (or wire the `Hsm` + * interface to your real PKCS#11 binding, e.g. `pkcs11js`) for the snippet to + * run. */ -import { secp256k1 } from '@noble/curves/secp256k1' import { ExternalSigner, SimpleXRPL } from 'simplexrpl' -import type { EcdsaSignature, Secp256k1SignerPort } from 'simplexrpl' +import type { Secp256k1SignerPort } from 'simplexrpl' import { inMemoryLedger } from './mocks.js' -/** secp256k1 sizes: 32-byte scalars, 65-byte uncompressed point (0x04‖X‖Y). */ -const SCALAR_BYTES = 32 -const POINT_BYTES = 65 -const COMPRESSED_EVEN = 0x02 -const COMPRESSED_ODD = 0x03 -const EVEN = 2 - -/** - * The narrow slice of your HSM the signer needs. Implement it with your PKCS#11 - * binding against an ECDSA secp256k1 key. - */ -interface Hsm { - /** - * The key's public point. In PKCS#11: `C_GetAttributeValue(session, - * pubKeyHandle, [CKA_EC_POINT])` — a DER OCTET STRING wrapping the - * uncompressed point (`0x04‖X‖Y`). - */ - readonly ecPoint: () => Promise - - /** - * Sign a 32-byte digest and return the raw 64-byte `r‖s`. In PKCS#11: - * `C_SignInit(session, { mechanism: CKM_ECDSA }, privKeyHandle)` then - * `C_Sign(session, digest)`. - * - * IMPORTANT: use `CKM_ECDSA` (signs the digest as-is), NOT `CKM_ECDSA_SHA256` - * — XRPL's digest is SHA-512Half, and letting the HSM re-hash would corrupt - * the signature. - */ - readonly signDigest: (digest: Uint8Array) => Promise -} - -/** - * Strip the DER OCTET STRING wrapper `CKA_EC_POINT` uses; the uncompressed - * point is the trailing 65 bytes. - * - * @param ecPoint - The raw `CKA_EC_POINT` attribute value. - * @returns The uncompressed point (`0x04‖X‖Y`). - */ -function uncompressedPoint(ecPoint: Uint8Array): Buffer { - return Buffer.from(ecPoint).subarray(-POINT_BYTES) +// === What you write with simpleXRPL === +// `signer` is your Secp256k1SignerPort backed by the HSM (see the adapter +// below). `client.xrp`, `client.iou`, etc. now sign through the HSM — the +// private key never leaves the device. Build → sign (in the HSM) → submit. +async function transferWithHsm(signer: Secp256k1SignerPort): Promise { + const custody = await ExternalSigner.create({ signer }) + const client = await SimpleXRPL.init({ + xrpldUrl: 'wss://s.altnet.rippletest.net:51233', // XRPL Testnet + signers: [custody], + ledger: inMemoryLedger(), // omit in production to use the live XRPL connection + }) + const result = await client.xrp.transfer({ + to: client.account.create().address, + amount: '10', + }) + console.log( + `HSM account ${custody.primary.address} signed & submitted ` + + `(source=${result.source}, hash=${result.txHash})`, + ) + await client.disconnect() } -/** An {@link Secp256k1SignerPort} backed by a PKCS#11 HSM. */ -class Pkcs11Signer implements Secp256k1SignerPort { - public readonly algorithm = 'secp256k1' - - public constructor(private readonly hsm: Hsm) {} - - /** - * Compress the HSM's public point to XRPL's 33-byte hex form. - * - * @returns The compressed public key hex. - */ - public async publicKey(): Promise { - const point = uncompressedPoint(await this.hsm.ecPoint()) - const x = point.subarray(1, 1 + SCALAR_BYTES) - const y = point.subarray(1 + SCALAR_BYTES) - const prefix = - y[y.length - 1] % EVEN === 0 ? COMPRESSED_EVEN : COMPRESSED_ODD - return Buffer.concat([Buffer.from([prefix]), x]) - .toString('hex') - .toUpperCase() - } - - /** - * Split the HSM's raw `r‖s` signature into scalars; the SDK normalizes to - * low-S and DER-encodes. - * - * @param digest - The 32-byte digest to sign. - * @returns The signature scalars. - */ - public async signDigest(digest: Uint8Array): Promise { - const raw = Buffer.from(await this.hsm.signDigest(digest)) - return { - r: BigInt(`0x${raw.subarray(0, SCALAR_BYTES).toString('hex')}`), - s: BigInt(`0x${raw.subarray(SCALAR_BYTES).toString('hex')}`), - } - } -} - -// DEMO ONLY: an in-process key standing in for the HSM so this file runs -// end to end. Your real `Hsm` calls PKCS#11 (see the notes above) and returns -// the same shapes — a DER-wrapped `CKA_EC_POINT` and a raw `r‖s` — so nothing -// downstream changes. -function demoHsm(privHex: string): Hsm { - const priv = Buffer.from(privHex, 'hex') - return { - ecPoint: async (): Promise => - secp256k1.getPublicKey(priv, false), // 65-byte 0x04‖X‖Y - signDigest: async (digest: Uint8Array): Promise => - secp256k1.sign(digest, priv).toCompactRawBytes(), // raw r‖s - } -} - -const hsm = demoHsm( - 'c9537c5a2f3f7e1d4b6a8c0e2f4d6b8a1c3e5f7091b3d5f7a9c1e3050709b0d0f', -) -const custody = await ExternalSigner.create({ signer: new Pkcs11Signer(hsm) }) -const client = await SimpleXRPL.init({ - rippledUrl: 'wss://s.altnet.rippletest.net:51233', // XRPL Testnet - signers: [custody], - ledger: inMemoryLedger(), // omit in production to use the live XRPL connection -}) - -// `client.xrp`, `client.iou`, etc. now sign through the HSM — the private key -// never leaves the device. Build → sign (in the HSM) → submit: -const destination = client.account.create().address -const result = await client.xrp.transfer({ to: destination, amount: '10' }) -console.log( - `HSM account ${custody.primary.address} signed & submitted ` + - `(source=${result.source}, hash=${result.txHash})`, -) -await client.disconnect() +// === Bring-your-own HSM (PKCS#11) — uncomment to run, or wire your device === +// HSM setups vary (slot, PIN, key label, vendor library), so this is a +// reference to adapt. `demoHsm()` (from ./mocks) is an in-process stand-in so +// the file runs offline; swap it for a real PKCS#11 binding. The SDK owns low-S +// normalization + DER encoding; your port returns the raw `r‖s` scalars. +// +// import type { EcdsaSignature } from 'simplexrpl' +// import { demoHsm } from './mocks.js' +// +// // secp256k1 sizes: 32-byte scalars, 65-byte uncompressed point (0x04‖X‖Y). +// const SCALAR_BYTES = 32 +// const POINT_BYTES = 65 +// const COMPRESSED_EVEN = 0x02 +// const COMPRESSED_ODD = 0x03 +// const EVEN = 2 +// +// /** The narrow slice of your HSM the signer needs (PKCS#11, ECDSA secp256k1). */ +// interface Hsm { +// // CKA_EC_POINT — DER OCTET STRING wrapping the uncompressed point 0x04‖X‖Y. +// readonly ecPoint: () => Promise +// // C_Sign with CKM_ECDSA (NOT CKM_ECDSA_SHA256 — the digest is pre-hashed); +// // returns the raw 64-byte r‖s. +// readonly signDigest: (digest: Uint8Array) => Promise +// } +// +// /** Strip the DER wrapper; the uncompressed point is the trailing 65 bytes. */ +// function uncompressedPoint(ecPoint: Uint8Array): Buffer { +// return Buffer.from(ecPoint).subarray(-POINT_BYTES) +// } +// +// /** An ExternalSignerPort backed by a PKCS#11 HSM. */ +// class Pkcs11Signer implements Secp256k1SignerPort { +// public readonly algorithm = 'secp256k1' +// public constructor(private readonly hsm: Hsm) {} +// +// public async publicKey(): Promise { +// const point = uncompressedPoint(await this.hsm.ecPoint()) +// const x = point.subarray(1, 1 + SCALAR_BYTES) +// const y = point.subarray(1 + SCALAR_BYTES) +// const prefix = +// y[y.length - 1] % EVEN === 0 ? COMPRESSED_EVEN : COMPRESSED_ODD +// return Buffer.concat([Buffer.from([prefix]), x]) +// .toString('hex') +// .toUpperCase() +// } +// +// public async signDigest(digest: Uint8Array): Promise { +// const raw = Buffer.from(await this.hsm.signDigest(digest)) +// return { +// r: BigInt(`0x${raw.subarray(0, SCALAR_BYTES).toString('hex')}`), +// s: BigInt(`0x${raw.subarray(SCALAR_BYTES).toString('hex')}`), +// } +// } +// } +// +// await transferWithHsm(new Pkcs11Signer(demoHsm())) ``` ## See Also diff --git a/docs/simpleXRPL/tutorials/issue-and-distribute-iou.md b/docs/simpleXRPL/tutorials/issue-and-distribute-iou.md index c02dd900..6df930be 100644 --- a/docs/simpleXRPL/tutorials/issue-and-distribute-iou.md +++ b/docs/simpleXRPL/tutorials/issue-and-distribute-iou.md @@ -12,59 +12,67 @@ labels: ```ts /** - * Issue and distribute an IOU (trust line currency). + * Issue and distribute an IOU (trust-line currency) with Palisade-held accounts. * - * `issue` bootstraps the issuer and a hot wallet from the environment - * (`XRPL_ISSUER_SEED`, `XRPL_HOT_WALLET_SEED`): the issuer enables rippling and - * the hot wallet extends a trust line. No value exists yet — `transfer` sends - * the currency out from the issuer. Every verb acts as the issuer, selected via - * `from` (defaults to the primary signer's account). + * `issue` sets up the trust line: the issuer enables rippling (`AccountSet`) and + * the hot wallet extends trust (`TrustSet`). Both are Palisade wallets here — + * pass the hot wallet via `holder`, and the issuer defaults to the primary + * signer. No value exists yet — `transfer` sends the currency out. Every + * operation acts as the issuer, selected via `from` (default: the primary). */ -import { LocalSigner, SimpleXRPL } from 'simplexrpl' +import { PalisadeCustody, SimpleXRPL } from 'simplexrpl' + +// The issuer wallet, held in Palisade (the primary signer). Palisade needs two +// credentials: a wallet-read one (discovery) and a transactions one (signing). +const palisade = await PalisadeCustody.create({ + baseUrl: 'https://api.sandbox.palisade.co', // sandbox (TESTNET data) + credentials: { + wallets: { + clientId: process.env.PALISADE_WALLETS_CLIENT_ID ?? '', + clientSecret: process.env.PALISADE_WALLETS_CLIENT_SECRET ?? '', + }, + transactions: { + clientId: process.env.PALISADE_TX_CLIENT_ID ?? '', + clientSecret: process.env.PALISADE_TX_CLIENT_SECRET ?? '', + }, + }, + primary: { + vaultId: process.env.PALISADE_VAULT_ID ?? '', + walletId: process.env.PALISADE_WALLET_ID ?? '', + }, +}) const client = await SimpleXRPL.init({ - rippledUrl: 'wss://s.altnet.rippletest.net:51233', - signers: [LocalSigner.fromEnv()], + xrpldUrl: 'wss://s.altnet.rippletest.net:51233', // XRPL Testnet + signers: [palisade], }) -// 1. Issue. Returns the IOU id, e.g. "USD.rIssuer...". -const issued = await client.iou.issue({ ticker: 'USD' }) +// The hot wallet: a second Palisade wallet in the same org. It extends trust to +// the issuer, and both accounts are signed by Palisade. +const hotWallet = process.env.PALISADE_HOLDER_ADDRESS ?? '' + +// 1. Issue: AccountSet on the issuer (the primary) + a max-limit TrustSet on the +// hot wallet. Returns the IOU id, e.g. "USD.rIssuer...". +const issued = await client.iou.issue({ ticker: 'USD', holder: hotWallet }) console.log('issued', issued.intent.iouID) -// 2. Distribute: send 1,000 USD from the issuer to a holder. The holder must -// already trust the issuer for this currency (the hot wallet set up in step -// 1 does; other holders extend their own trust line first). +// 2. Distribute: send 1,000 USD from the issuer to the hot wallet, which now +// trusts it. Other holders extend their own trust line first. await client.iou.transfer({ ticker: 'USD', - destination: 'rHolder00000000000000000000000000000', + destination: hotWallet, amount: 1000, }) -// 3. Optional issuer controls, all scoped to the same currency: -// - authorize a holder (when the issuer requires authorization) -// - lock / unlock a holder's line (reversible freeze) -// - clawback (requires clawback enabled before any trust lines exist) -await client.iou.authorize({ - ticker: 'USD', - holder: 'rHolder00000000000000000000000000000', -}) - -// 4. Read it back (no signer required). `retrieve` returns a single shaped -// trust line for the holder→issuer pair; `list` returns all of an account's -// lines. Pass `account` to read any address, or omit it for the primary. +// 3. Read it back (no signer required): the hot wallet's shaped USD trust line. // The issuer is the second half of the iouID ("USD.rIssuer..."). const [, issuer] = issued.intent.iouID.split('.') -const holder = 'rHolder00000000000000000000000000000' - const line = await client.iou.retrieve({ ticker: 'USD', issuer, - account: holder, + account: hotWallet, }) -console.log('holder balance:', line.data?.balance ?? '0') - -const all = await client.iou.list({ account: holder }) -console.log('holder trust lines:', all.ious) +console.log('hot wallet balance:', line.data?.balance ?? '0') await client.disconnect() ``` diff --git a/docs/simpleXRPL/tutorials/issue-rwa-as-mpt.md b/docs/simpleXRPL/tutorials/issue-rwa-as-mpt.md index 07a0c767..fbba0a7f 100644 --- a/docs/simpleXRPL/tutorials/issue-rwa-as-mpt.md +++ b/docs/simpleXRPL/tutorials/issue-rwa-as-mpt.md @@ -18,7 +18,8 @@ Real-World Assets are issued as Multi-Purpose Tokens (MPTs) via the `token` vert * Metadata follows the XLS-89 standard and is validated before submission * (`asset_class: 'rwa'` requires an `asset_subclass`). Here the issuer is a * Ripple Custody account: Custody signs and submits the issuance as one - * governed action, subject to the domain's approval policy. + * governed action, subject to the domain's approval policy. `MPTokenIssuanceCreate` + * is native to Ripple Custody, so it flows through the governed native path. */ import { RippleCustody, SimpleXRPL } from 'simplexrpl' @@ -30,34 +31,23 @@ const ISSUER_ADDRESS = process.env.RIPPLE_CUSTODY_PRIMARY ?? '' const custody = await RippleCustody.fromEnv({ primary: ISSUER_ADDRESS }) const client = await SimpleXRPL.init({ - rippledUrl: 'wss://s.altnet.rippletest.net:51233', // XRPL Testnet + xrpldUrl: 'wss://s.altnet.rippletest.net:51233', // XRPL Testnet signers: [custody], }) -const result = await client.token.issue( - { - metadata: { - ticker: 'TBILL', - name: 'Acme 3-Month T-Bill', - icon: 'https://acme.example/tbill.png', - asset_class: 'rwa', - asset_subclass: 'treasury', - issuer_name: 'Acme Capital', - }, - // 2 decimal places of display precision. - assetScale: 2, - // 0.5% fee on secondary transfers. - transferFee: 0.5, - // Keep the issuer able to claw back (compliance); other capabilities on. - flags: { canClawback: true, canTransfer: true }, +// Metadata is the only required input. The issuer is the primary signer (the +// Custody account), and everything else — assetScale, transfer fee, and the +// capability flags (clawback, transfer, …) — is left at its SDK default. +const result = await client.token.issue({ + metadata: { + ticker: 'TBILL', + name: 'Acme 3-Month T-Bill', + icon: 'https://acme.example/tbill.png', + asset_class: 'rwa', + asset_subclass: 'treasury', + issuer_name: 'Acme Capital', }, - // Issue as the Custody account. Omit `from` to use the primary signer. - { from: ISSUER_ADDRESS }, -) - -// `MPTokenIssuanceCreate` is native to Ripple Custody, so this returns once the -// governed action reaches a terminal state — or throws `IntentPendingError` if -// it's still awaiting approval past the timeout. +}) console.log('issued MPT:', result.intent.mptIssuanceId) // Read the issuance back (no signer required): flags are decoded to booleans, diff --git a/docs/simpleXRPL/tutorials/place-dex-order.md b/docs/simpleXRPL/tutorials/place-dex-order.md index f1cb90d9..5680a24e 100644 --- a/docs/simpleXRPL/tutorials/place-dex-order.md +++ b/docs/simpleXRPL/tutorials/place-dex-order.md @@ -21,7 +21,7 @@ The `iou` vertical places orders to buy or sell an issued currency; the `token` import { iou, LocalSigner, SimpleXRPL, XRP_ASSET } from 'simplexrpl' const client = await SimpleXRPL.init({ - rippledUrl: 'wss://s.altnet.rippletest.net:51233', + xrpldUrl: 'wss://s.altnet.rippletest.net:51233', signers: [LocalSigner.fromEnv()], }) From ecfaa7570bbcc5dc011ba22e267543c553d79f76 Mon Sep 17 00:00:00 2001 From: Oliver Eggert Date: Thu, 30 Jul 2026 17:34:33 -0700 Subject: [PATCH 24/24] add reviewer suggestions --- docs/simpleXRPL/references/client.md | 2 +- .../simpleXRPL/references/connectors/index.md | 42 ++++++++++++++++ docs/simpleXRPL/references/types.md | 50 +++++++++++++++++++ .../references/verticals/account/index.md | 2 +- index.page.tsx | 7 +++ sidebars.yaml | 1 + 6 files changed, 102 insertions(+), 2 deletions(-) create mode 100644 docs/simpleXRPL/references/types.md diff --git a/docs/simpleXRPL/references/client.md b/docs/simpleXRPL/references/client.md index bd41bd5c..bf99f282 100644 --- a/docs/simpleXRPL/references/client.md +++ b/docs/simpleXRPL/references/client.md @@ -47,7 +47,7 @@ Read-only members of the `SimpleXRPLClient` that `SimpleXRPL.init()` returns, se | `network` | `object` | The network the client is bound to — a `NetworkInfo` with `rippledUrl` (and `faucetUrl` on test networks). | | `signers` | `array` | The registered connectors, 0 or more (a `Custodian[]`). | | `primarySigner` | `object` | The default connector, used when a verb is called without an explicit account. `undefined` on a no-signer client. | -| `accounts` | `object` | Every discovered account as a read-only map keyed by r-address (`ReadonlyMap`). | +| `accounts` | `object` | Every discovered account as a read-only map keyed by r-address (`ReadonlyMap`). See [`Account`](types.md#account). | | `ledger` | `object` | The shared ledger connection for reads, autofill, and Local/raw submission. Created lazily from `network.rippledUrl` when none was injected. | | `intent` | `object` | Read-only inspector for custodian governance intents (status/await). | diff --git a/docs/simpleXRPL/references/connectors/index.md b/docs/simpleXRPL/references/connectors/index.md index 9ba8585e..dba6b10d 100644 --- a/docs/simpleXRPL/references/connectors/index.md +++ b/docs/simpleXRPL/references/connectors/index.md @@ -14,3 +14,45 @@ A connector is a signing backend: it determines how an operation runs and which - [External](./external.md) - [Ripple Custody](./ripple-custody.md) - [Palisade](./palisade.md) + +Every connector implements the `Custodian` interface. Once constructed, it exposes these fields and methods: + + +## Fields + +| Field | Type | Description | +| --- | --- | --- | +| `kind` | `string` | The backend the connector adapts: `local`, `ripple-custody`, `palisade-custody`, or `external`. | +| `primary` | `object` | The connector's primary account reference. Used when a vertical operation runs without an explicit account. | +| `primary.address` | `string` | The primary account's XRPL r-address. | +| `primary.custodianRef` | `string` or `object`| _(Optional)_ The connector's opaque native id for the account. A `string` for account-id connectors, or a `{vaultId, walletId}` object for vault-based connectors. Absent for local wallets. | + + +## Methods + +### listAccounts() + +List the accounts the connector holds. + +#### Signature + +```ts +connector.listAccounts(): Promise +``` + +#### Parameters + +`listAccounts` takes no arguments. + +#### Returns + +Resolves to an array of [Account](../types.md#account) records the connector discovered and can sign for. + +#### Example + +```ts +const accounts = await connector.listAccounts() + +console.log(accounts.map((account) => account.address)) +``` + diff --git a/docs/simpleXRPL/references/types.md b/docs/simpleXRPL/references/types.md new file mode 100644 index 00000000..9d4fba20 --- /dev/null +++ b/docs/simpleXRPL/references/types.md @@ -0,0 +1,50 @@ +--- +seo: + description: Core types in simpleXRPL — the shared account records (Account, AccountRef) and the account selector used across the client, connectors, and verticals. +labels: + - simpleXRPL + - SDK +--- + +# Core Types + +Core types are the shared records the SDK uses across the client, connectors, and verticals — as opposed to the parameters and results specific to a single operation. They describe how simpleXRPL identifies and references XRPL accounts. + +## Account + +[[Source]](https://github.com/ripple/simpleXRPL/blob/50619258cf753008e8a185eaeb3ceca489e5998a/src/domain/model.ts#L41) + +A discovered account: its r-address paired with the connector that owns and signs for it. The SDK hands you an `Account` from `client.accounts` and [`connector.listAccounts()`](connectors/index.md). It extends [`AccountRef`](#accountref). + +This is distinct from `AccountData`, the on-chain snapshot returned by [`account.retrieve`](verticals/account/retrieve.md). + +| Field | Type | Description | +| --- | --- | --- | +| `address` | `string` | The XRPL r-address — the canonical key the SDK uses to identify the account. | +| `signer` | `object` | The [connector](connectors/index.md) (a `Custodian`) that discovered and signs for this account. | +| `alias` | `string` _(optional)_ | A connector-side alias, when the backend exposes one. | +| `custodianRef` | `string` \| `object` _(optional)_ | The owning connector's opaque native id for the account — a `string` for account-id connectors, or a `{ vaultId, walletId }` object for vault-based connectors; absent for local wallets. | +| `metadata` | `object` _(optional)_ | Advisory-only. Shape `{ kind?, tags? }`, where `kind` is the connector kind (`'local'`, `'ripple-custody'`, `'palisade-custody'`, or `'external'`) and `tags` is a list of strings. | + +## AccountRef + +[[Source]](https://github.com/ripple/simpleXRPL/blob/50619258cf753008e8a185eaeb3ceca489e5998a/src/domain/model.ts#L29) + +The minimal reference to an account — just its r-address and the owning connector's native id. [`Account`](#account) extends it, and a connector's `primary` field is an `AccountRef`. + +| Field | Type | Description | +| --- | --- | --- | +| `address` | `string` | The XRPL r-address. | +| `custodianRef` | `string` \| `object` _(optional)_ | The owning connector's opaque native id for the account — a `string` for account-id connectors, or a `{ vaultId, walletId }` object for vault-based connectors; absent for local wallets. | + +## AccountSelector + +[[Source]](https://github.com/ripple/simpleXRPL/blob/50619258cf753008e8a185eaeb3ceca489e5998a/src/domain/model.ts#L59) + +How you choose the source account for a verb — the `from` option on write operations. It is one of three forms: + +| Form | Type | Description | +| --- | --- | --- | +| r-address | `string` | A bare r-address string. | +| `{ address }` | `object` | An object holding an explicit r-address. | +| `{ signer, account? }` | `object` | A connector, optionally narrowed to one of the accounts it owns (by r-address). | diff --git a/docs/simpleXRPL/references/verticals/account/index.md b/docs/simpleXRPL/references/verticals/account/index.md index 5f03db6b..35817433 100644 --- a/docs/simpleXRPL/references/verticals/account/index.md +++ b/docs/simpleXRPL/references/verticals/account/index.md @@ -8,7 +8,7 @@ labels: # Account -The `Account` vertical handles account creation, funding, and administration. (The class is named `AccountVertical` to avoid colliding with the `Account` record type; it is reached as `client.account`.) +The `Account` vertical handles account creation, funding, and administration. (The class is named `AccountVertical` to avoid colliding with the [`Account`](../../types.md#account) record type — a [core type](../../types.md) used across the SDK; it is reached as `client.account`.) | Method | Description | | --- | --- | diff --git a/index.page.tsx b/index.page.tsx index 96bbfe8e..e638f919 100644 --- a/index.page.tsx +++ b/index.page.tsx @@ -23,6 +23,13 @@ export default function Page() { + +

Integrate with your custodian and build on the XRPL.

+ + +

Prepare and submit up to 8 transactions in a single batch.