mirror of
https://github.com/XRPLF/xrpl-dev-portal.git
synced 2025-11-20 19:55:54 +00:00
Preauth-related API method docs (draft)
This commit is contained in:
mDuo13
@@ -13,6 +13,7 @@ The types of objects that may appear in the `account_objects` response for an ac
|
||||
- [Escrow objects](escrow.html) for held payments that have not yet been executed or canceled.
|
||||
- [PayChannel objects](paychannel.html) for open payment channels.
|
||||
- [Check objects](check.html) for pending checks.
|
||||
- [DepositPreauth objects](depositpreauth-object.html) for deposit preauthorizations. [New in: rippled 1.1.0][]
|
||||
|
||||
|
||||
## Request Format
|
||||
@@ -64,7 +65,7 @@ The request includes the following parameters:
|
||||
| `Field` | Type | Description |
|
||||
|:---------------|:-------------------------------------------|:---------------|
|
||||
| `account` | String | A unique identifier for the account, most commonly the account's address. |
|
||||
| `type` | String | _(Optional)_ If included, filter results to include only this type of ledger object. The valid types are: `check`, `escrow`, `offer`, `payment_channel`, `signer_list`, and `state` (trust line). <!-- Author's note: Omitted types from this list that can't be owned by an account, and ticket until Tickets are enabled: https://github.com/ripple/rippled/blob/1dbc5a57e6b0e90a9da0d6e56f2f5a99e6ac1d8c/src/ripple/rpc/impl/RPCHelpers.cpp#L676-L686 --> |
|
||||
| `type` | String | _(Optional)_ If included, filter results to include only this type of ledger object. The valid types are: `check`, `deposit_preauth`, `escrow`, `offer`, `payment_channel`, `signer_list`, and `state` (trust line). <!-- Author's note: Omitted types from this list that can't be owned by an account, and ticket until Tickets are enabled: https://github.com/ripple/rippled/blob/1dbc5a57e6b0e90a9da0d6e56f2f5a99e6ac1d8c/src/ripple/rpc/impl/RPCHelpers.cpp#L676-L686 --> |
|
||||
| `ledger_hash` | String | _(Optional)_ A 20-byte hex string for the ledger version to use. (See [Specifying Ledgers][]) |
|
||||
| `ledger_index` | String or Unsigned Integer | _(Optional)_ The sequence number of the ledger to use, or a shortcut string to choose a ledger automatically. (See [Specifying Ledgers][]) |
|
||||
| `limit` | Unsigned Integer | _(Optional)_ The maximum number of objects to include in the results. Must be within the inclusive range 10 to 400 on non-admin connections. Defaults to 200. |
|
||||
|
||||
@@ -52,6 +52,7 @@ This method can retrieve several different types of data. You can select which t
|
||||
6. `check` - Retrieve a [Check object](check.html), which is a potential payment that can be cashed by its recipient. [New in: rippled 1.0.0][]
|
||||
7. `escrow` - Retrieve an [Escrow object](escrow-object.html), which holds XRP until a specific time or condition is met. [New in: rippled 1.0.0][]
|
||||
8. `payment_channel` - Retireve a [PayChannel object](paychannel.html), which holds XRP for asynchronous payments. [New in: rippled 1.0.0][]
|
||||
9. `deposit_preauth` - Retrieve a [DepositPreauth object](depositpreauth-object.html), which tracks preauthorization for payments to accounts requiring [Deposit Authorization](depositauth.html). [New in: rippled 1.1.0][]
|
||||
|
||||
If you specify more than one of the above items, the server retrieves only one of them; it is undefined which it chooses.
|
||||
|
||||
@@ -62,13 +63,16 @@ The full list of parameters recognized by this method is as follows:
|
||||
| `index` | String | _(Optional)_ Specify the [object ID](ledger-object-ids.html) of a single object to retrieve from the ledger. |
|
||||
| `account_root` | String - [Address][] | _(Optional)_ Specify an [AccountRoot object](accountroot.html) to retrieve. |
|
||||
| `check` | String | _(Optional)_ Specify the [object ID](ledger-object-ids.html) of a [Check object](check.html) to retrieve. |
|
||||
| `deposit_preauth` | Object or String | _(Optional)_ Specify a [DepositPreauth object](depositpreauth-object.html) to retrieve. If a string, must be the [object ID](ledger-object-ids.html) of the DepositPreauth object, as hexadecimal. If an object, requires `owner` and `authorized` sub-fields. |
|
||||
| `deposit_preauth.owner` | String - [Address][] | _(Required if `deposit_preauth` is specified as an object)_ The account that provided the preauthorization. |
|
||||
| `deposit_preauth.authorized` | String - [Address][] | _(Required if `deposit_preauth` is specified as an object)_ The account that received the preauthorization. |
|
||||
| `directory` | Object or String | _(Optional)_ Specify a [DirectoryNode](directorynode.html) to retrieve. If a string, must be the [object ID](ledger-object-ids.html) of the directory, as hexadecimal. If an object, requires either `dir_root` or `owner` as a sub-field, plus optionally a `sub_index` sub-field. |
|
||||
| `directory.sub_index` | Unsigned Integer | _(Optional)_ If provided, jumps to a later "page" of the [DirectoryNode](directorynode.html). |
|
||||
| `directory.dir_root` | String | (Required if `directory` is specified as an object and `directory.owner` is not provided) Unique index identifying the directory to retrieve, as a hex string. |
|
||||
| `directory.owner` | String | (Required if `directory` is specified as an object and `directory.dir_root` is not provided) Unique address of the account associated with this directory |
|
||||
| `directory.dir_root` | String | _(Required if `directory` is specified as an object and `directory.owner` is not provided)_ Unique index identifying the directory to retrieve, as a hex string. |
|
||||
| `directory.owner` | String | _(Required if `directory` is specified as an object and `directory.dir_root` is not provided)_ Unique address of the account associated with this directory |
|
||||
| `escrow` | Object or String | _(Optional)_ Specify an [Escrow object](escrow-object.html) to retrieve. If a string, must be the [object ID](ledger-object-ids.html) of the Escrow, as hexadecimal. If an object, requires `owner` and `seq` sub-fields. |
|
||||
| `escrow.owner` | String - [Address][] | (Required if `escrow` is specified as an object) The owner (sender) of the Escrow object. |
|
||||
| `escrow.seq` | Unsigned Integer | (Required if `escrow` is specified as an object) The sequence number of the transaction that created the Escrow object. |
|
||||
| `escrow.owner` | String - [Address][] | _(Required if `escrow` is specified as an object)_ The owner (sender) of the Escrow object. |
|
||||
| `escrow.seq` | Unsigned Integer | _(Required if `escrow` is specified as an object)_ The sequence number of the transaction that created the Escrow object. |
|
||||
| `offer` | Object or String | _(Optional)_ Specify an [Offer object](offer.html) to retrieve. If a string, interpret as the [unique index](ledgers.html#tree-format) to the Offer. If an object, requires the sub-fields `account` and `seq` to uniquely identify the offer. |
|
||||
| `offer.account` | String - [Address][] | (Required if `offer` specified) The account that placed the offer. |
|
||||
| `offer.seq` | Unsigned Integer | (Required if `offer` specified) The sequence number of the transaction that created the Offer object. |
|
||||
|
||||
@@ -0,0 +1,111 @@
|
||||
# deposit_authorized
|
||||
[[Source]<br>](https://github.com/ripple/rippled/blob/817d2339b8632cb2f97d3edd6f7af33aa7631744/src/ripple/rpc/handlers/DepositAuthorized.cpp "Source")
|
||||
|
||||
The `deposit_authorized` command indicates whether one account is authorized to send payments directly to another. See [Deposit Authorization](depositauth.html) for information on how to require authorization to deliver money to your account.
|
||||
|
||||
## Request Format
|
||||
An example of the request format:
|
||||
|
||||
<!-- MULTICODE_BLOCK_START -->
|
||||
|
||||
*WebSocket*
|
||||
|
||||
```json
|
||||
{
|
||||
"id": 1,
|
||||
"command": "deposit_authorized",
|
||||
"source_account": "rnUy2SHTrB9DubsPmkJZUXTf5FcNDGrYEA",
|
||||
"destination_account": "rDg53Haik2475DJx8bjMDSDPj4VX7htaMd",
|
||||
"ledger_index": "validated"
|
||||
}
|
||||
```
|
||||
|
||||
*JSON-RPC*
|
||||
|
||||
```json
|
||||
{
|
||||
"method": "deposit_authorized",
|
||||
"params": [
|
||||
{
|
||||
"source_account": "rnUy2SHTrB9DubsPmkJZUXTf5FcNDGrYEA",
|
||||
"destination_account": "rDg53Haik2475DJx8bjMDSDPj4VX7htaMd",
|
||||
"ledger_index": "validated"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
*Commandline*
|
||||
|
||||
```bash
|
||||
#Syntax: deposit_authorized <source_account> <destination_account> [<ledger>]
|
||||
rippled deposit_authorized rnUy2SHTrB9DubsPmkJZUXTf5FcNDGrYEA rDg53Haik2475DJx8bjMDSDPj4VX7htaMd validated
|
||||
```
|
||||
|
||||
<!-- MULTICODE_BLOCK_END -->
|
||||
|
||||
The request includes the following parameters:
|
||||
|
||||
| `Field` | Type | Description |
|
||||
|:----------------------|:---------------------------|:------------------------|
|
||||
| `source_account` | String - [Address][] | The sender of a possible payment. |
|
||||
| `destination_account` | String - [Address][] | The recipient of a possible payment. |
|
||||
| `ledger_hash` | String | _(Optional)_ A 20-byte hex string for the ledger version to use. (See [Specifying Ledgers][]) |
|
||||
| `ledger_index` | String or Unsigned Integer | _(Optional)_ The sequence number of the ledger to use, or a shortcut string to choose a ledger automatically. (See [Specifying Ledgers][]) |
|
||||
|
||||
|
||||
## Response Format
|
||||
|
||||
An example of a successful response:
|
||||
|
||||
<!-- MULTICODE_BLOCK_START -->
|
||||
|
||||
*WebSocket*
|
||||
|
||||
```json
|
||||
TODO
|
||||
```
|
||||
|
||||
*JSON-RPC*
|
||||
|
||||
```json
|
||||
{
|
||||
"result":
|
||||
{
|
||||
"deposit_authorized": true,
|
||||
"destination_account": "rDg53Haik2475DJx8bjMDSDPj4VX7htaMd",
|
||||
"ledger_hash": "4C99E5F63C0D0B1C2283B4F5DCE2239F80CE92E8B1A6AED1E110C198FC96E659",
|
||||
"ledger_index": 14380380,
|
||||
"source_account": "rnUy2SHTrB9DubsPmkJZUXTf5FcNDGrYEA",
|
||||
"status": "success",
|
||||
"validated": true
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
<!-- MULTICODE_BLOCK_END -->
|
||||
|
||||
The response follows the [standard format][], with a successful result containing the following fields:
|
||||
|
||||
| `Field` | Type | Description |
|
||||
|:-----------------------|:---------------------|:-----------------------------|
|
||||
| `deposit_authorized` | Boolean | Whether the specified source account is authorized to send payments directly to the destination account. If `true`, either the destination account does not require [Deposit Authorization](depositauth.html) or the source account is preauthorized. |
|
||||
| `destination_account` | String - [Address][] | The destination account specified in the request. |
|
||||
| `ledger_hash` | String | _(May be omitted)_ The identifying hash of the ledger that was used to generate this response. |
|
||||
| `ledger_index` | Number | _(May be omitted)_ The sequence number of the ledger version that was used to generate this response. |
|
||||
| `ledger_current_index` | Number | _(May be omitted)_ The sequence number of the current in-progress ledger version that was used to generate this response. |
|
||||
| `source_account` | String - [Address][] | The source account specified in the request. |
|
||||
| `validated` | Boolean | _(May be omitted)_ If `true`, the information comes from a validated ledger version. |
|
||||
|
||||
**Note:** A `deposit_authorized` status of `true` does not guarantee that a payment can be sent from the specified source to the specified destination. For example, the destination account may not have a [trust line](trust-lines-and-issuing.html) for the specified currency, or there may not be sufficient liquidity to deliver a payment.
|
||||
|
||||
## Possible Errors
|
||||
|
||||
* Any of the [universal error types][].
|
||||
* `invalidParams` - One or more fields are specified incorrectly, or one or more required fields are missing.
|
||||
* `actNotFound` - An [Address][] specified in the `source_account` or `destination_account` field of the request does not correspond to an account in the ledger.
|
||||
* `lgrNotFound` - The ledger specified by the `ledger_hash` or `ledger_index` does not exist, or it does exist but the server does not have it.
|
||||
|
||||
|
||||
{% include '_snippets/rippled_versions.md' %}
|
||||
{% include '_snippets/rippled-api-links.md' %}
|
||||
Reference in New Issue
Block a user