From 96f39b03aa5f63d50a26023939eeb2d5810ca20c Mon Sep 17 00:00:00 2001 From: mDuo13 Date: Tue, 17 Feb 2015 18:08:41 -0800 Subject: [PATCH 1/2] [DOC] rippled - account_currencies public method (draft) --- content/rippled.md | 149 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 149 insertions(+) diff --git a/content/rippled.md b/content/rippled.md index 4f7e5ae21c..51c61d6970 100644 --- a/content/rippled.md +++ b/content/rippled.md @@ -492,6 +492,155 @@ The `rippled` application, in addition to acting as a server, can be run (as a s # Managing Accounts # Accounts are the core unit of authentication in the Ripple Network. Each account can hold balances in multiple currencies, and all transactions must be signed by an account's secret key. In order for an account to exist in a validated ledger version, it must hold a minimum reserve amount of XRP. (The [reserve for an account](https://ripple.com/wiki/Reserves) increases with the amount of data it is responsible for in the shared ledger.) It is expected that accounts will correspond loosely to individual users. + +## account_currencies ## +[[Source]
](https://github.com/ripple/rippled/blob/df966a9ac6dd986585ecccb206aff24452e41a30/src/ripple/rpc/handlers/AccountCurrencies.cpp "Source") + +The `account_currencies` command retrieves a list of currencies that an account can send or receive. (How is "can send" defined?) + +#### Request Format #### +An example of the request format: + +
+ +*WebSocket* + +``` +{ + "command": "account_currencies", + "account": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59", + "strict": true, + "ledger_index": "validated", + "account_index": 0 +} +``` + +*JSON-RPC* + +``` +{ + "method": "account_currencies", + "params": [ + { + "account": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59", + "account_index": 0, + "ledger_index": "validated", + "strict": true + } + ] +} +``` + + +
+ +The request includes the following parameters: + +| Field | Type | Description | +|-------|------|-------------| +| account | String | A unique identifier for the account, most commonly the account's address. | +| strict | Boolean | (Optional) If true, only accept an address or public key for the account parameter. Defaults to false. | +| ledger\_hash | String | (Optional) A 20-byte hex string for the ledger version to use. (See [Specifying a Ledger](#specifying-a-ledger-instance)) | +| 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 a Ledger](#specifying-a-ledger-instance))| +| account\_index | Unsigned Integer | (Optional) Something to do with account sequence number?? Defaults to 0. | + +#### Response Format #### + +An example of a successful response: + +
+ +*WebSocket* + +``` +{ + "result": { + "ledger_index": 11775844, + "receive_currencies": [ + "BTC", + "CNY", + "DYM", + "EUR", + "JOE", + "MXN", + "USD", + "015841551A748AD2C1F76FF6ECB0CCCD00000000" + ], + "send_currencies": [ + "ASP", + "BTC", + "CHF", + "CNY", + "DYM", + "EUR", + "JOE", + "JPY", + "MXN", + "USD" + ], + "validated": true + }, + "status": "success", + "type": "response" +} +``` + +*JSON-RPC* + +``` +200 OK +{ + "result": { + "ledger_index": 11775823, + "receive_currencies": [ + "BTC", + "CNY", + "DYM", + "EUR", + "JOE", + "MXN", + "USD", + "015841551A748AD2C1F76FF6ECB0CCCD00000000" + ], + "send_currencies": [ + "ASP", + "BTC", + "CHF", + "CNY", + "DYM", + "EUR", + "JOE", + "JPY", + "MXN", + "USD" + ], + "status": "success", + "validated": true + } +} +``` + +
+ +The response follows the [standard format](#response-formatting), with a successful result containing the following fields: + +| Field | Type | Description | +|-------|------|-------------| +| ledger\_hash | String | (May be omitted) The identifying hash of the ledger version used to retrieve this data, as hex. | +| ledger\_index | Integer | The sequence number of the ledger version used to retrieve this data. | +| receive\_currencies | Array of Strings | Array of currency codes for currencies that this account can receive. Each currency is either a 3-letter [ISO 4217 Currency Code](http://www.xe.com/iso4217.php) or a 160-bit hex value according to the [currency format](https://wiki.ripple.com/Currency_format). | +| send\_currencies | Array of Strings | Array of currency codes for currencies that this account can send. Each currency is either a 3-letter [ISO 4217 Currency Code](http://www.xe.com/iso4217.php) or a 160-bit hex value according to the [currency format](https://wiki.ripple.com/Currency_format). | +| validated | Boolean | If `true`, this data comes from a validated ledger. | + +#### Possible Errors #### + +* Any of the [universal error types](#universal-errors). +* `invalidParams` - One or more fields are specified incorrectly, or one or more required fields are missing. +* `actNotFound` - The address specified in the `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. + + + ## account_info ## [[Source]
](https://github.com/ripple/rippled/blob/master/src/ripple/rpc/handlers/AccountInfo.cpp "Source") From 805ef0885f7037edb08015fff9d870c1b6c58370 Mon Sep 17 00:00:00 2001 From: mDuo13 Date: Thu, 26 Feb 2015 15:12:18 -0800 Subject: [PATCH 2/2] [DOC] rippled - account_currencies is ready to go --- content/rippled.md | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/content/rippled.md b/content/rippled.md index 51c61d6970..bbc77fe1a5 100644 --- a/content/rippled.md +++ b/content/rippled.md @@ -496,7 +496,7 @@ Accounts are the core unit of authentication in the Ripple Network. Each account ## account_currencies ## [[Source]
](https://github.com/ripple/rippled/blob/df966a9ac6dd986585ecccb206aff24452e41a30/src/ripple/rpc/handlers/AccountCurrencies.cpp "Source") -The `account_currencies` command retrieves a list of currencies that an account can send or receive. (How is "can send" defined?) +The `account_currencies` command retrieves a simple list of currencies that an account can send or receive, based on its trustlines. (This is not a thoroughly confirmed list, but it can be used to populate user interfaces.) #### Request Format #### An example of the request format: @@ -531,7 +531,6 @@ An example of the request format: } ``` - The request includes the following parameters: @@ -539,10 +538,11 @@ The request includes the following parameters: | Field | Type | Description | |-------|------|-------------| | account | String | A unique identifier for the account, most commonly the account's address. | -| strict | Boolean | (Optional) If true, only accept an address or public key for the account parameter. Defaults to false. | +| strict | Boolean | (Optional) If true, only accept an address or public key for the account parameter. Defaults to false. | | ledger\_hash | String | (Optional) A 20-byte hex string for the ledger version to use. (See [Specifying a Ledger](#specifying-a-ledger-instance)) | | 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 a Ledger](#specifying-a-ledger-instance))| -| account\_index | Unsigned Integer | (Optional) Something to do with account sequence number?? Defaults to 0. | + +The following field is deprecated and should not be provided: `account_index`. #### Response Format #### @@ -632,6 +632,8 @@ The response follows the [standard format](#response-formatting), with a success | send\_currencies | Array of Strings | Array of currency codes for currencies that this account can send. Each currency is either a 3-letter [ISO 4217 Currency Code](http://www.xe.com/iso4217.php) or a 160-bit hex value according to the [currency format](https://wiki.ripple.com/Currency_format). | | validated | Boolean | If `true`, this data comes from a validated ledger. | +*Note:* The currencies that an account can send or receive are defined based on a simple check of its trust lines. if an account has a trust line for a currency and enough room to increase its balance, it can receive that currency. If the trustline's balance can go down, the account can send that currency. This method *does not* check whether the trust line is frozen or authorized. + #### Possible Errors #### * Any of the [universal error types](#universal-errors).