ARCHIVE/xrpl-dev-portal
1
0
Fork 0
mirror of https://github.com/XRPLF/xrpl-dev-portal.git synced 2025-11-21 04:05:49 +00:00
Code Issues Packages Projects Releases Wiki Activity

start removing Ripple-REST

Browse Source
This commit is contained in:
mDuo13
2016-01-20 20:21:37 -08:00
parent 4d6c063861
commit 63d92fdce0
30 changed files with 258 additions and 8123 deletions
Download Patch File Download Diff File Expand all files Collapse all files

241
content/demurrage.md
View File

@@ -1,241 +0,0 @@
Demurrage in Ripple Currencies
==============================
[Demurrage](http://en.wikipedia.org/wiki/Demurrage_%28currency%29) is a
negative interest rate on assets held that represents the cost of
holding those assets. Ripple supports currencies that have interest or
demurrage rates built into the currency definition, such as
"XAU (-0.5%pa)". Each currency-rate combination is treated as a completely
distinct currency for purposes of pathfinding and order books.
A gateway that wants to charge demurrage for holding assets (such as
gold) can issue a custom currency representing that asset with the
demurrage rate built-in. This is reflected in a different hex
representation for the demurraging currency. Client applications should
represent a demurraging currency by displaying the negative annual
percentage rate along with the currency code.
XRP cannot have demurrage or interest.
Dealing with Demurraging Currencies
-----------------------------------
The rippled server, and consequently the official global ledger, do not
track changes in value due to demurrage in the balance of funds. This
allows demurrage costs to be applied continuously, instead of operating
on fixed intervals. It also prevents demurrage from inflicting
significant additional computational and storage load for servers that
are part of the network. Instead, the fact that particular holdings are
subject to demurrage is tracked in the ledger by virtue of the custom
currency codes. Demurrage is calculated on the entire currency as if it
were interest, according to the following formula:
D = A \* ( e \^ (t/ τ) )
where:
- D is the amount after demurrage
- A is the pre-demurrage amount as recorded in the global ledger
- e is Euler's number
- t is the number of seconds since the [Ripple
Epoch](rippled-apis.html#specifying-time) (0:00 on January 1, 2000
UTC)
- τ is the [e-folding time](http://en.wikipedia.org/wiki/E-folding) in
seconds. This value is calculated from the desired interest rate.
You can think of demurrage in the Ripple Network as similar to
inflation, where the value of all assets affected by it decreases over
time, but the ledger always holds amounts in year-2000 values. (This
representation was chosen as a simplification of the more complicated
representation where individual holdings could track when the demurrage
on them started accruing, because this way it becomes easier to
recognize, exchange, and represent assets with demurrage applied.) Keep
in mind, this does not reflect actual, real-world inflation: instead,
it's hypothetical inflation at a constant rate.
### Calculating e-folding time
It is simple to calculate from a targeted demurrage rate in annual
percent to get a τ value to use in calculating demurrage:
1. First, subtract the demurrage percentage rate from 100% to get the
percentage of initial amount that remains after annual demurrage.
Represent it as a decimal. For example, for 0.5% annual interest,
you would get 0.995
2. Now, take the natural log of that number. For example, ln(0.995).
For traditional demurrage (decrease in value over time), this value
will be negative.
3. Finally, take the number of seconds in one year (31536000) and
divide by the result of the natural log operation. The result is
your e-folding time in seconds, for example -6291418827.045599
If you're curious: Since an e-folding amount represents how long until
an investment increases e times, a negative interest rate means that the
investment would have been worth e times its value that amount of time
in the past. Alternatively, it means that after that amount of seconds,
the investment will be worth 1/e of what it used to be.
### Canonical Calculations
For purposes of calculating demurrage consistently across applications,
the precision used is important. Our canonical source of demurrage
calculations is ripple-lib. By following these specifications, you
should be able to reproduce the demurrage results from ripple-lib
exactly:
First, recall the canonical formula for demurrage:
D = A \* ( e \^ (t/ τ) )
where D is the post-demurrage amount, and A is the pre-demurrage amount.
For the remainder of the formula, e \^ (t/ τ), we call this the
"demurrage coefficient". The demurrage coefficient is always relative to
a specific time, such that demurrage is calculated for the period
starting at the beginning of the Ripple Epoch (00:00:00 January 1, 2000)
The two directional calculations can therefore be simplified to:
1. Find the demurrage coefficient for the reference time
2. Apply it to the amount to convert
1. To convert ledger values to display values, multiply by the
demurrage coefficient
2. To convert display values to ledger values, divide by the
demurrage coefficient
3. Make sure that the converted value can be represented to the desired
accuracy. For example, ledger values submitted to Ripple must fit in
Ripple's [internal format](https://wiki.ripple.com/Currency_format).
For more information on the necessary precision:
The demurrage coefficient should be calculated entirely in [64-bit
IEEE754
doubles](http://en.wikipedia.org/wiki/Double-precision_floating-point_format),
such as the number types native to Javascript, or the float type
available in Python. However, there are some additional notes:
- For purposes of demurrage, one year is defined as exactly 31536000
seconds. This is exactly 365 days, with no adjustments for leap days
or leap seconds.
- The reference time should be specified in seconds, as an integer. If
your clock provides a higher resolution, you should truncate the
reference time to seconds before using it.
Client Applications
-------------------
In order to accurately convey amounts in present-day terms, client
applications must adjust for demurrage. This means a few things:
- When representing the value of a demurraging currency, the display
value should be adjusted to the "post-demurrage" values. (This
generally means that display values will be lower than the ledger
values.)
- When making offers or transactions in a demurraging currency,
amounts entered by the user should be adjusted upward, to interpret
user input as post-demurrage numbers. (This generally means that
amounts written into offers are higher than the user input value)
Client applications must also make sure to distinguish between
currencies with differing amounts of demurrage, and to display the
correct demurrage rates for all currencies with such rates. Currently,
the only Ripple Labs-created client that supports demurrage is Ripple
Trade.
### ripple-lib support
Clients that are built from
[ripple-lib](https://github.com/ripple/ripple-lib) can pass a
`reference_date` as an option to the Amount.from\_human function to
account for demurrage. This function can automatically convert a
human-input number to the necessary amount to hold on the ledger to
represent that value in at a given time. (The amount that is sent to the
rippled server is the hypothetical amount one would have needed in order
to have the desired amount after enduring constant demurrage since the
Ripple Epoch.)
For example, if you're using javascript, you can use ripple-lib utility
to calculate this manually:
```
// create an Amount object for an amount of the demurring currency, in this case 10
// pass in a reference_date that represents today,
// which will calculate how much you will need to represent the requested amount for today
var demAmount = Amount.from_human('10 0158415500000000C1F76FF6ECB0BAC600000000', {reference_date:459990264});
// set the issuer -- optional
demAmount.set_issuer("rHb9CJAWyB4rj91VRWn96DkukG4bwdtyTh");
// get the json format that can be used as TakerPays or TakerGets in the order creation
console.log(demAmount.to_json());
// this will output an Amount with ~10.75 as the value for XAU, which is what is needed to create an
// effective order today for 10 XAU
```
To calculate how much a given amount has demurred up to today:
```
// create a new Amount object
var demAmount = Amount.from_json('10/015841551A748AD2C1F76FF6ECB0CCCD00000000/rHb9CJAWyB4rj91VRWn96DkukG4bwdtyTh');
// apply interest
demAmount = demAmount.applyInterest(new Date());
// get the current amount:
console.log(demAmount.to_json());
Where Does Demurrage Go?
------------------------
To put it simply, the value that depreciates due to demurrage becomes
the property of the gateway issuing the currency. This means that, when
someone holding a balance of currency goes to redeem that currency from
the Gateway, the amount they get is the post-demurrage amount (the
"display amount") relative to the current moment in time.
Note that, when the Gateway issues currency with demurrage, it must also
adjust the values it issues, so that the amount sent to the rippled
server and written in the ledger is already adjusted for demurrage up to
the point in time it was issued.
Demurrage and Money-Making Offers
---------------------------------
Demurrage ensures that particular currencies "drift" in value slowly
over time, so that the same amount on the ledger is worth increasingly
less over time when redeemed. (A balance will never go negative, but it
will get closer and closer to zero value.) However, offers are not
automatically updated to compensate for demurrage that accumulated in
the time since the offer was made. This means that, if you are making an
offer to buy a demurraging currency, you must occasionally adjust your
offer to ask for higher ledger amounts to get the same post-demurrage
actual value. However, we expect this to be a complete non-issue because
the relative value of currencies (especially pseudo-currency commodities
such as precious metals) fluctuates much faster than typical rates of
demurrage.
Since Ripple client applications already adjust for demurrage when
taking human inputs to make an offer, most users will not have to do
anything different when making offers.
Currency Format Details
-----------------------
Currency with demurrage or interest is represented as a 160-bit value
that begins with the value `0x01`. This sets it apart from hashes (which
are always `0x80` or higher) as well as standard currency (`0x00`) and
other currency types we may define in the future (`0x02-0x7F`).
Demurraging currency has the following format:
01 __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __
CURCODE- DATE------- RATE------------------- RESERVED---
- CURCODE is the 3-byte currency code, such as "USD"
- DATE is no longer used, and should always be 0.
- RATE is the e-folding time, formatted as an IEEE Double, represented
in hex. For example, -6291418827.045599 becomes "C1F76FF6ECB0BAC6".
- RESERVED is reserved for future use. It should always be given as 0,
but other values should be accepted for forward-compatibility.

213
content/gateway_guide.md
View File

@@ -284,15 +284,14 @@ Contact [partners@ripple.com](mailto:partners@ripple.com) to see how Ripple Labs
There are several interfaces you can use to connect to Ripple, depending on your needs and your existing software: There are several interfaces you can use to connect to Ripple, depending on your needs and your existing software:
* [`rippled`](rippled-apis.html) provides JSON-RPC and WebSocket APIs that can be used as a low-level interface to all core Ripple functionality. * [`rippled`](rippled-apis.html) provides JSON-RPC and WebSocket APIs that can be used as a low-level interface to all core Ripple functionality.
* The official client library to rippled, [ripple-lib](https://github.com/ripple/ripple-lib) is available for JavaScript, and provides extended convenience features. * [RippleAPI](rippleapi.html) provides a simple API for JavaScript applications.
* [Ripple-REST](ripple-rest.html) provides an easy-to-use RESTful API on top of `rippled`. In particular, Ripple-REST is designed to be easier to use from statically-typed languages.
## Tool Security ## ## Tool Security ##
Any time you submit a Ripple transaction, it must be signed using your secret. However, having your secret means having full control over your account. Therefore, you should never transmit your secret to a server operated by someone else. Instead, use your own server or client application to sign the transactions before sending them out. Any time you submit a Ripple transaction, it must be signed using your secret. However, having your secret means having full control over your account. Therefore, you should never transmit your secret to a server operated by someone else. Instead, use your own server or client application to sign the transactions before sending them out.
The examples in this document show Ripple-REST API methods that include an account secret. This is only safe if you control the Ripple-REST server yourself, *and* you connect to it over a connection that is secure from outside listeners. (For example, you could connect over a loopback (localhost) network, a private subnet, or an encrypted VPN.) Alternatively, you could operate your own `rippled` server; or you can use a client application such as `ripple-lib` to perform local signing before submitting your transactions to a third-party server. The examples in this document show API methods that include an account secret. This is only safe if you control `rippled` server yourself, *and* you connect to it over a connection that is secure from outside listeners. (For example, you could connect over a loopback (localhost) network, a private subnet, or an encrypted VPN.) Alternatively, you could use [RippleAPI](rippleapi.html) to perform local signing before submitting your transactions to a third-party server.
## DefaultRipple ## ## DefaultRipple ##
@@ -301,9 +300,7 @@ The DefaultRipple flag controls whether the balances held in an account's trust
Before asking users to trust its issuing account, a gateway should enable the DefaultRipple flag on that account. Otherwise, the gateway must individually disable the NoRipple flag for each trust line that other accounts extend to it. Before asking users to trust its issuing account, a gateway should enable the DefaultRipple flag on that account. Otherwise, the gateway must individually disable the NoRipple flag for each trust line that other accounts extend to it.
*Note:* Ripple-REST (as of version 1.4.0) does not yet support retrieving or setting the DefaultRipple flag. The following is an example of using a locally-hosted `rippled`'s [`submit` command](rippled-apis.html#submit) submitting an AccountSet transaction to enable the DefaultRipple flag:
The following is an example of using a local [`rippled` JSON-RPC API](ripple-rest.html#update-account-settings) to enable the DefaultRipple flag:
Request: Request:
@@ -371,47 +368,35 @@ Enable the [RequireDest](#requiredest) flag on your hot and cold wallet accounts
## DisallowXRP ## ## DisallowXRP ##
The DisallowXRP flag (`disallow_xrp` in Ripple-REST) is designed to discourage users from sending XRP to an account by accident. This reduces the costs and effort of bouncing undesired payments, if you operate a gateway that does not trade XRP. The DisallowXRP flag is not strictly enforced, because doing so could allow accounts to become permanently unusable if they run out of XRP. Client applications should honor the DisallowXRP flag, but it is intentionally possible to work around. The DisallowXRP flag is designed to discourage users from sending XRP to an account by accident. This reduces the costs and effort of bouncing undesired payments, if you operate a gateway that does not trade XRP. The DisallowXRP flag is not strictly enforced, because doing so could allow accounts to become permanently unusable if they run out of XRP. Client applications should honor the DisallowXRP flag, but it is intentionally possible to work around.
An issuing gateway that does not trade XRP should enable the DisallowXRP flag on all gateway hot and cold wallets. A private exchange that trades in XRP should only enable the DisallowXRP flag on accounts that are not expected to receive XRP. An issuing gateway that does not trade XRP should enable the DisallowXRP flag on all gateway hot and cold wallets. A private exchange that trades in XRP should only enable the DisallowXRP flag on accounts that are not expected to receive XRP.
The following is an example of a [Ripple-REST Update Account Settings request](ripple-rest.html#update-account-settings) to enable the DisallowXRP flag: The following is an example of using a locally-hosted `rippled`'s [`submit` command](rippled-apis.html#submit) submitting an AccountSet transaction to enable the DisallowXRP flag:
Request: Request:
``` ```
POST /v1/accounts/rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn/settings?validated=true POST http://localhost:8088/
{ {
"secret": "sn3nxiW7v8KXzPzAqzyHXbSSKNuN9", "method": "submit",
"settings": { "params": [
"disallow_xrp": true {
} "secret": "sn3nxiW7v8KXzPzAqzyHXbSSKNuN9",
"tx_json": {
"Account": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
"Fee": "15000",
"Flags": 0,
"SetFlag": 3,
"TransactionType": "AccountSet"
}
}
]
} }
``` ```
_(**Reminder:** Don't send your secret to a server you do not control.)_ _(**Reminder:** Don't send your secret to a server you do not control.)_
Response:
```
200 OK
{
"success": true,
"settings": {
"hash": "AC0F7D7735CDDC6D859D0EC4E96A571F71F7481750F4C6C975FC8075801A6FB5",
"ledger": "10560577",
"state": "validated",
"require_destination_tag": false,
"require_authorization": false,
"disallow_xrp": true
}
}
```
The value `"disallow_xrp": true` indicates that the DisallowXRP flag is enabled. A successful response shows `"state": "validated"` when the change has been accepted into a validated Ripple ledger.
## RequireDest ## ## RequireDest ##
@@ -419,42 +404,31 @@ The `RequireDest` flag (`require_destination_tag` in Ripple-REST) is designed to
We recommend enabling the RequireDest flag on all gateway hot and cold wallets. We recommend enabling the RequireDest flag on all gateway hot and cold wallets.
The following is an example of a [Ripple-REST Update Account Settings request](ripple-rest.html#update-account-settings) to enable the RequireDest flag. The following is an example of using a locally-hosted `rippled`'s [`submit` command](rippled-apis.html#submit) submitting an AccountSet transaction to enable the RequireDest flag:
Request: Request:
``` ```
POST /v1/accounts/rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn/settings?validated=true POST http://localhost:8088/
{ {
"secret": "sn3nxiW7v8KXzPzAqzyHXbSSKNuN9", "method": "submit",
"settings": { "params": [
"require_destination_tag": true {
} "secret": "sn3nxiW7v8KXzPzAqzyHXbSSKNuN9",
"tx_json": {
"Account": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
"Fee": "15000",
"Flags": 0,
"SetFlag": 1,
"TransactionType": "AccountSet"
}
}
]
} }
``` ```
_(**Reminder:** Don't send your secret to a server you do not control.)_ _(**Reminder:** Don't send your secret to a server you do not control.)_
Response:
```
200 OK
{
"success": true,
"settings": {
"hash": "F3D2EE87D597BA50EA3A94027583110925E8BAAFE41511F937D65423B18BC2A3",
"ledger": "10560755",
"state": "validated",
"require_destination_tag": true,
"require_authorization": false,
"disallow_xrp": false
}
}
```
The value `"require_destination_tag": true` indicates that the RequireDest flag has been enabled. A successful response shows `"state": "validated"` when the change has been accepted into a validated Ripple ledger.
## RequireAuth ## ## RequireAuth ##
@@ -468,37 +442,30 @@ You can only enable RequireAuth if the account owns no trust lines and no offers
We recommend enabling `RequireAuth` for all hot wallet accounts, and then never approving any accounts, in order to prevent hot wallets from creating issuances even by accident. This is a purely precuationary measure, and does not impede the ability of those accounts to transfer issuances created by the cold wallet, as they are intended to do. We recommend enabling `RequireAuth` for all hot wallet accounts, and then never approving any accounts, in order to prevent hot wallets from creating issuances even by accident. This is a purely precuationary measure, and does not impede the ability of those accounts to transfer issuances created by the cold wallet, as they are intended to do.
The following is an example of a [Ripple-REST Update Account Settings request](ripple-rest.html#update-account-settings) to enable the RequireDest flag. (This method works the same way regardless of whether the account is used as a hot wallet or cold wallet.) The following is an example of using a locally-hosted `rippled`'s [`submit` command](rippled-apis.html#submit) submitting an AccountSet transaction to enable the RequireAuth flag: (This method works the same way regardless of whether the account is used as a hot wallet or cold wallet.)
Request: Request:
``` ```
POST /v1/accounts/rsA2LpzuawewSBQXkiju3YQTMzW13pAAdW/settings?validated=true POST http://localhost:8088/
{ {
"secret": "sn3nxiW7v8KXzPzAqzyHXbSSKNuN9", "method": "submit",
"settings": { "params": [
"require_authorization": true {
} "secret": "sn3nxiW7v8KXzPzAqzyHXbSSKNuN9",
"tx_json": {
"Account": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
"Fee": "15000",
"Flags": 0,
"SetFlag": 2,
"TransactionType": "AccountSet"
}
}
]
} }
``` ```
_(**Reminder:** Don't send your secret to a server you do not control.)_
Response: _(**Reminder:** Don't send your secret to a server you do not control.)_
```
{
"success": true,
"settings": {
"hash": "687702E0C3952E2227B2F7A0B34933EAADD72A572B234D31360AD83D3F193A78",
"ledger": "10596929",
"state": "validated",
"require_destination_tag": false,
"require_authorization": true,
"disallow_xrp": false
}
}
```
### With Cold Wallets ### ### With Cold Wallets ###
@@ -506,46 +473,37 @@ You may also enable `RequireAuth` for your cold wallet in order to use the [Auth
If ACME decides to use Authorized Accounts, ACME creates an interface for users to get their Ripple trust lines authorized by ACME's cold account. After Alice has extended a trust line to ACME from her Ripple account, she goes through the interface on ACME's website to require ACME authorize her trust line. ACME confirms that it has validated Alice's identity information, and then sends a TrustSet transaction to authorize Alice's trust line. If ACME decides to use Authorized Accounts, ACME creates an interface for users to get their Ripple trust lines authorized by ACME's cold account. After Alice has extended a trust line to ACME from her Ripple account, she goes through the interface on ACME's website to require ACME authorize her trust line. ACME confirms that it has validated Alice's identity information, and then sends a TrustSet transaction to authorize Alice's trust line.
The following is an example of using the [Ripple-REST Grant Trustline method](ripple-rest.html#grant-trustline) to authorize the (customer) account rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn to hold issuances of USD from the (cold wallet) account rsA2LpzuawewSBQXkiju3YQTMzW13pAAdW:
The following is an example of using a locally-hosted `rippled`'s [`submit` command](rippled-apis.html#submit) to send a TrustSet transaction authorizing the (customer) account rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn to hold issuances of USD from the (cold wallet) account rsA2LpzuawewSBQXkiju3YQTMzW13pAAdW:
Request: Request:
``` ```
POST /v1/accounts/rsA2LpzuawewSBQXkiju3YQTMzW13pAAdW/trustlines?validated=true POST http://localhost:8088/
{ {
"secret": "sn3nxiW7v8KXzPzAqzyHXbSSKNuN9", "method": "submit",
"trustline": { "params": [
"limit": "0", {
"currency": "USD", "secret": "sn3nxiW7v8KXzPzAqzyHXbSSKNuN9",
"counterparty": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn", "tx_json": {
"authorized": true "Account": "rsA2LpzuawewSBQXkiju3YQTMzW13pAAdW",
} "Fee": "15000",
} "TransactionType": "TrustSet",
``` "LimitAmount": {
_(**Reminder:** Don't send your secret to a server you do not control.)_ "currency": "USD",
"issuer": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
Response: "value": 0
},
``` "Flags": 65536
201 Created }
{ }
"success": true, ]
"trustline": {
"account": "rsA2LpzuawewSBQXkiju3YQTMzW13pAAdW",
"limit": "0",
"currency": "USD",
"counterparty": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
"account_allows_rippling": true,
"account_trustline_frozen": false,
"authorized": true
},
"hash": "4509288EE17F01C83FC7D45850EB066A795EE5DBA17BB4DC98DD4023D31EEE5B",
"ledger": "11158585",
"state": "validated"
} }
``` ```
A successful response shows `"state": "validated"` when the change has been accepted into a validated Ripple ledger. _(**Reminder:** Don't send your secret to a server you do not control.)_
## Robustly Monitoring for Payments ## ## Robustly Monitoring for Payments ##
@@ -699,22 +657,6 @@ POST /v1/accounts/rBEXjfD3MuXKATePRwrk4AqgqzuD9JjQqv/payments?validated=true
} }
``` ```
_(**Reminder:** Don't send your secret to a server you do not control.)_ _(**Reminder:** Don't send your secret to a server you do not control.)_
## Setting Trust Lines in Ripple Trade ##
As part of the [Hot and Cold Wallets](#hot-and-cold-wallets) model, each hot or warm wallet must have a trust line to the cold wallet. You can manually set up those trust lines by following these steps in the Ripple Trade client.
1. Log in and go to the **Fund** tab:
![Fund tab](img/connectgateway_01.png)
2. Click **Gateways** in the sidebar:
![Gateways](img/connectgateway_02.png)
3. Enter the Ripple Name or Ripple Address of the Gateway's **cold wallet**, and click **Save**.
![Enter gateway's name or address, then save](img/connectgateway_03.png)
4. Enter the Ripple Trade password, and click **Submit**. (This allows access to send a transaction to the Ripple Network to create the trust line.)
![Enter password and submit](img/connectgateway_04.png)
5. When the page shows a green "Gateway connected" box, the transaction to create the trust line has succeeded and the Ripple Network has validated it.
![Gateway connected](img/connectgateway_05.png)
## Reliable Transaction Submission ## ## Reliable Transaction Submission ##
@@ -727,16 +669,15 @@ The goal of reliably submitting transactions is to achieve the following two pro
In order to achieve this, there are several steps you can take when submitting transactions: In order to achieve this, there are several steps you can take when submitting transactions:
* Persist details of the transaction before submitting it. * Persist details of the transaction before submitting it.
* Use the `LastLedgerSequence` parameter. (Ripple-REST and ripple-lib do this by default.) * Use the `LastLedgerSequence` parameter. (RippleAPI does this by default.)
* Resubmit a transaction if it has not appeared in a validated ledger whose sequence number is less than or equal to the transaction's `LastLedgerSequence` parameter. * Resubmit a transaction if it has not appeared in a validated ledger whose sequence number is less than or equal to the transaction's `LastLedgerSequence` parameter.
For additional information, consult the [Reliable Transaction Submission](reliable_tx.html) guide. For additional information, consult the [Reliable Transaction Submission](reliable_tx.html) guide.
## ripple.txt and host-meta ## ## ripple.txt ##
The [ripple.txt](https://wiki.ripple.com/Ripple.txt) and host-meta standards provide a way to publish information about your gateway so that automated tools and applications can read and understand it. The [ripple.txt](https://wiki.ripple.com/Ripple.txt) standard provides a way to publish information about your gateway so that automated tools and applications can read and understand it.
For example, if you run a validating `rippled` server, you can use ripple.txt to publish the public key of your validating server. You can also publish information about what currencies your gateway issues, and which Ripple account addresses you control, to protect against impostors or confusion. For example, if you run a validating `rippled` server, you can use ripple.txt to publish the public key of your validating server. You can also publish information about what currencies your gateway issues, and which Ripple account addresses you control, to protect against impostors or confusion.
We recommend implementing one or both of ripple.txt and host-meta. (In the future, we expect ripple.txt to become obsolete, but not yet.)

30
content/intro.md
View File

@@ -1,30 +0,0 @@
# Introduction #
Ripple is a decentralized, peer-to-peer network for moving value using cryptographic technology. For more on the big picture, consult [ripple.com](https://ripple.com/) and check out [our blog](https://ripple.com/blog/).
# Ripple Client Applications #
The official web client for the Ripple Network is available at [https://rippletrade.com/](). There is also an official downloadable client at [http://download.ripple.com/]().
In order to activate your account, you must fund it with enough XRP to meet the account reserve (currently 20 XRP). You can do this in a few different ways:
* You can buy XRP with Bitcoins in the Ripple Trade client, under the [Fund](https://www.rippletrade.com/#/fund) tab.
* You can have someone who is already on the network send a payment to your account's address.
* Keep an eye out for promotions that give away free XRP to developers.
# Ripple APIs #
If you intend to act as a gateway, or if you are a developer with great ideas of how to use the Ripple Network, you will probably want to build a custom client application that you or your customers can use to send, receive, or observe funds on the Ripple Network.
Connecting to the Ripple Network generally means communicating with the Ripple Server software, [`rippled`](https://github.com/ripple/rippled) (pronounced "ripple-dee"). To get started, you can try running a few calls to retrieve information from public servers using the [Ripple API Tool](https://ripple.com/tools/api) or you try downloading and running your own instance of `rippled`.
If you are building your own client, you have several options of interfaces that you can use to interact with the Ripple Network:
| Tool | Summary | Interface | Abstraction Level | Pros | Cons |
|------|---------|-----------------------|-------------------|------|------|
| [gatewayd](https://github.com/ripple/gatewayd) | Skeleton for implementing gateway functionality as a Node.js application | HTTP interface | Very high abstraction | ✓ Most functionality needed to operate a gateway is already implemented | ✗ Only intended for gateways <br> ✗ Requires Node.js |
| [Ripple-REST](?p=ripple-rest-api) | RESTful interface to `rippled` as a Node.js application | HTTP interface | High abstraction | ✓ Simple robust transaction submission <br> ✓ Broad HTTP-client support | ✗ Lacks access to a few features like viewing currency exchange offers <br> ✗ Requires Node.js |
| [ripple-lib](https://github.com/ripple/ripple-lib) | Reference implementation for accessing the WebSocket API | Javascript library | Moderate abstraction | ✓ Simple robust transaction submission<br> ✓ Good balance of simplicity and power | ✗ Javascript only (Clients for other languages are in progress) |
| [rippled WebSocket API](?p=web-sockets-api) | Powerful, asynchronous API built on the WebSocket protocol | [WebSocket](http://en.wikipedia.org/wiki/Websocket) interface | Low abstraction | ✓ Access to all Ripple functionality <br> ✓ Can be pushed ordered stream data | ✗ Fewer convenient abstractions <br> ✗ WebSocket clients are rare outside of Javascript |
| [rippled JSON-RPC API](?p=web-sockets-api) <!--note: that's not a typo, the websocket and json-rpc docs are on the same page--> | Powerful, synchronous API built on the [JSON-RPC convention](http://json-rpc.org/) | HTTP interface | Low abstraction | ✓ Access to almost all Ripple functionality <br> ✓ Broad HTTP-client support | ✗ Fewer convenient abstractions <br> ✗ Callbacks may arrive out of order <br> ✗ No incremental pathfinding |

616
content/reliable_tx.md
View File

@@ -1,6 +1,6 @@
# Reliable Transaction Submission # Reliable Transaction Submission
Gateways and back-end applications should use the best practices described here to ensure that transactions are validated or rejected in a verifiable and timely fashion. Transactions should be submitted to trusted (locally operated) rippled servers. Gateways and back-end applications should use the best practices described here to ensure that transactions are validated or rejected in a verifiable and timely fashion. You should submit transactions to trusted (locally operated) `rippled` servers.
The best practices detailed in this document allow applications to submit transactions to the Ripple network while achieving: The best practices detailed in this document allow applications to submit transactions to the Ripple network while achieving:
@@ -17,7 +17,7 @@ These types of errors can potentially lead to serious problems. For example, an
## Background ## Background
The Ripple protocol provides a ledger shared across all nodes in the network. Through a process of consensus and validation, the network agrees on order in which transactions are applied to (or omitted from) the ledger. <!--See Ripple Ledger Consensus and Validation[b] for an overview of this process.--> The Ripple protocol provides a ledger shared across all nodes in the network. Through a process of consensus and validation, the network agrees on order in which transactions are applied to (or omitted from) the ledger.
Well-formed transactions submitted to trusted Ripple network nodes are usually validated or rejected in a matter of seconds. There are cases, however, in which a well-formed transaction is neither validated nor rejected this quickly. One specific case can occur if the global [transaction cost](tx-cost.html) increases after an application sends a transaction. If the transaction cost increases above what has been specified in the transaction, the transaction will not be included in the next validated ledger. If at some later date the global transaction cost decreases, the transaction may become viable again. If the transaction does not include expiration, there is no limit to how much later this can occur. Well-formed transactions submitted to trusted Ripple network nodes are usually validated or rejected in a matter of seconds. There are cases, however, in which a well-formed transaction is neither validated nor rejected this quickly. One specific case can occur if the global [transaction cost](tx-cost.html) increases after an application sends a transaction. If the transaction cost increases above what has been specified in the transaction, the transaction will not be included in the next validated ledger. If at some later date the global transaction cost decreases, the transaction may become viable again. If the transaction does not include expiration, there is no limit to how much later this can occur.
@@ -28,33 +28,37 @@ Applications face additional challenges, in the event of power or network loss,
### Transaction Timeline ### Transaction Timeline
Ripple provides several APIs for submitting transactions ([rippled](rippled-apis.html), ripple-lib, [Ripple-REST](ripple-rest.html)). Regardless of the API used, the transaction is applied to the ledger as follows. Ripple provides several APIs for submitting transactions, including [`rippled`](rippled-apis.html), and [RippleAPI](rippleapi.html). Regardless of the API used, the transaction is applied to the ledger as follows.
1. A transaction is created and signed by account owner. 1. An account owner creates and signs a transaction.
2. That transaction is submitted to the network as a candidate transaction. 2. The owner submits the transaction to the network as a candidate transaction.
- Malformed or nonsensical transactions are rejected immediately. - Malformed or nonsensical transactions are rejected immediately.
- Well formed transactions may provisionally succeed, then later fail. - Well-formed transactions may provisionally succeed, then later fail.
- Well formed transactions may provisionally fail, then later succeed. - Well-formed transactions may provisionally fail, then later succeed.
3. Through consensus and validation, the transaction is applied to the ledger. Even some failed transactions are applied in order to enforce a cost for being propagated through the network. - Well-formed transactions may provisionally succeed, and then later succeed in a slightly different way. (For example, by consuming a different offer and achieving a better or worse exchange rate than the provisional execution.)
3. Through consensus and validation, the transaction is applied to the ledger. Even some failed transactions are applied, in order to enforce a cost for being propagated through the network.
4. The validated ledger includes the transaction, and its effects are reflected in the ledger state. 4. The validated ledger includes the transaction, and its effects are reflected in the ledger state.
- Transaction results are no longer provisional, success or failure is now final and immutable. - Transaction results are no longer provisional, success or failure is now final and immutable.
*Note:* When submitting a transaction via rippled or ripple-lib, a successful status code returned from a submit command indicates the rippled server has received the candidate transaction, and does not indicate the transaction will be finally applied to the ledger. *Note:* When submitting a transaction via `rippled`, a successful status code returned from a submit command indicates the `rippled` server has received the candidate transaction, and does not indicate the transaction will be finally applied to the ledger.
Ripple APIs may return provisional results based on candidate transactions. Applications must not confuse these with the final, *immutable*, results of a transaction. Immutable results are found only in validated ledgers. Applications may need to query the status of a transaction repeatedly, until the ledger containing the transaction results is validated. APIs may return provisional results based on the result of applying candidate transactions to the current, in-progress ledger. Applications must not confuse these with the final, *immutable*, results of a transaction. Immutable results are found only in validated ledgers. Applications may need to query the status of a transaction repeatedly, until the ledger containing the transaction results is validated.
While applying transactions, Ripple network nodes work with the *last validated ledger*, a snapshot of the ledger state based on transactions the entire network has validated. The process of consensus and validation apply a set of new transactions to the last validated ledger, resulting in a new validated ledger. This new validated ledger instance and the ones that preceded it comprise the ledger history. Each of these validated ledger instances has a sequence number, which is one greater than the sequence number of the preceding instance. While applying transactions, `rippled` servers use the *last validated ledger*, a snapshot of the ledger state based on transactions the entire network has validated. The process of consensus and validation apply a set of new transactions to the last validated ledger in canonical order, resulting in a new validated ledger. This new validated ledger instance and the ones that preceded it comprise the ledger history.
Each validated ledger instances has a sequence number, which is one greater than the sequence number of the preceding instance. Each ledger also has an identifying hash value, which is uniquely determined from its contents. There may be many different versions of in-progress ledgers, which have the same sequence number, but different hash values. Only one version can ever be validated.
Each validated ledger has a canonical order in which transactions apply. This order is deterministic based on the final transaction set of the ledger. In contrast, each `rippled` server's in-progress ledger is calculated incrementally, as transactions are received. The order in which transactions execute provisionally is usually not the same as the order in which transactions execute to build a new validated ledger. This is one reason why the provisional outcome of a transaction may be different than the final result. For example, a payment may achieve a different final exchange rate depending on whether it executes before or after another payment that would consume the same offer.
### LastLedgerSequence ### LastLedgerSequence
[`LastLedgerSequence`](transactions.html#lastledgersequence) is an optional parameter of all transactions. This instructs the Ripple network that a transaction must be validated on or before a specific ledger instance. The transaction will never be included in a ledger instance with a higher sequence number. [`LastLedgerSequence`](transactions.html#lastledgersequence) is an optional parameter of all transactions. This instructs the Ripple Consensus Ledger that a transaction must be validated on or before a specific ledger instance. The Ripple Consensus Ledger never includes a transaction in a ledger instance whose sequence number is higher than the transaction's `LastLedgerSequence` parameter.
Use the `LastLedgerSequence` parameter to prevent undesirable cases where a transaction is not promptly validated yet could become viable at some point in the future. Gateways and other back-end applications should specify the `LastLedgerSequence` parameter on every transaction. Automated processes should use a value of 4 greater than the sequence number of the last validated ledger[1] to ensure that a transaction is validated or rejected in a predictable and timely fashion. Use the `LastLedgerSequence` parameter to prevent undesirable cases where a transaction is not promptly validated yet could become viable at some point in the future. Gateways and other back-end applications should specify the `LastLedgerSequence` parameter on every transaction. Automated processes should use a value of 4 greater than the sequence number of the last validated ledger[1] to ensure that a transaction is validated or rejected in a predictable and timely fashion.
Applications using rippled APIs should explicitly specify a `LastLedgerSequence` when submitting transactions. When using ripple-lib or Ripple-REST, a `LastLedgerSequence` is automatically included. Applications using those APIs are recommended to use the `LastLedgerSequence` calculated by the API. Applications using rippled APIs should explicitly specify a `LastLedgerSequence` when submitting transactions. RippleAPI uses the `maxLedgerVersion` field of [Transaction Instructions](rippleapi.html#transaction-instructions) to specify the `LastLedgerSequence`. RippleAPI automatically provides an appropriate value by default. You can specify `maxLedgerVersion` as `null` to intentionally omit `LastLedgerSequence`, in case you want a transaction that can be executed after an unlimited amount of time.
@@ -121,31 +125,31 @@ For each persisted transaction without validated result:
In order to implement the transaction submission and verification best practices, applications need to perform the following actions. In order to implement the transaction submission and verification best practices, applications need to perform the following actions.
* Determine the signing account's next sequence number 1. Determine the signing account's next sequence number
* Each transaction has an account-specific sequence number. This guarantees the order in which transactions signed by an account are executed and makes it safe to resubmit a transaction without danger of the transaction being applied to the ledger more than once. * Each transaction has an account-specific sequence number. This guarantees the order in which transactions signed by an account are executed and makes it safe to resubmit a transaction without danger of the transaction being applied to the ledger more than once.
* Decide on a `LastLedgerSequence` 3. Decide on a `LastLedgerSequence`
* A transaction's `LastLedgerSequence` is calculated from the last validated ledger sequence number. * A transaction's `LastLedgerSequence` is calculated from the last validated ledger sequence number.
* Construct and sign the transaction 3. Construct and sign the transaction
* The details of a signed transaction are persisted before submission. * Persist the details of a signed transaction before submission.
* Submit the transaction 4. Submit the transaction
* Initial results are provisional and subject to change. * Initial results are provisional and subject to change.
* Determine the final result of a transaction 5. Determine the final result of a transaction
* Final results are an immutable part of the ledger history. * Final results are an immutable part of the ledger history.
An application's means of performing these actions depends on the ripple API the application uses. These interfaces may be any of: An application's means of performing these actions depends on the API the application uses. These interfaces may be any of:
1. [rippled](rippled-apis.html) 1. [`rippled`'s internal APIs](rippled-apis.html)
2. [ripple-rest](ripple-rest.html) 2. [RippleAPI](rippleapi.html)
3. [ripple-lib](https://github.com/ripple/ripple-lib/) 3. Any number of other software APIs layered on top of `rippled`
### rippled - Submitting and Verifying Transactions ### rippled - Submitting and Verifying Transactions
#### Determine the Account Sequence #### Determine the Account Sequence
rippled provides the [account_info](rippled-apis.html#account-info) method to learn an account's sequence number in the last validated ledger. `rippled` provides the [account_info](rippled-apis.html#account-info) method to learn an account's sequence number in the last validated ledger.
Request: JSON-RPC Request:
``` ```
{ {
@@ -159,7 +163,7 @@ Request:
} }
``` ```
Response: Response body:
``` ```
{ {
@@ -184,7 +188,7 @@ Response:
In this example, the account's sequence is **4** (note `"Sequence": 4`, in `"account_data"`) as of the last validated ledger (note `"ledger": "validated"` in the request, and `"validated": "true"` in the response). In this example, the account's sequence is **4** (note `"Sequence": 4`, in `"account_data"`) as of the last validated ledger (note `"ledger": "validated"` in the request, and `"validated": "true"` in the response).
If an application were to submit three transactions signed by this account, they would use sequence numbers 4, 5, and 6. An application should keep a running account sequence number in order to submit multiple transactions without waiting for validation of each one. If an application were to submit three transactions signed by this account, they would use sequence numbers 4, 5, and 6. In order to submit multiple transactions without waiting for validation of each, an application should keep a running account sequence number.
#### Determine the Last Validated Ledger #### Determine the Last Validated Ledger
@@ -240,7 +244,7 @@ In this example the last validated ledger sequence number is 10268596 (found und
#### Construct the Transaction #### Construct the Transaction
`rippled` provides the [RPC sign](rippled-apis.html#sign) to prepare a transaction for submission. This method requires an account secret, which should only be passed to trusted rippled instances. This example issues 10 FOO (a made-up currency) from a gateway to another ripple account. `rippled` provides the [sign method](rippled-apis.html#sign) to prepare a transaction for submission. This method requires an account secret, which should only be passed to trusted `rippled` instances. This example issues 10 FOO (a made-up currency) from a gateway to another Ripple account.
Request: Request:
@@ -307,7 +311,7 @@ Applications should persist the transaction's hash before submitting. The resul
#### Submit the transaction #### Submit the transaction
`rippled` provides the [`submit` method](rippled-apis.html#submit), allowing us to submit the signed transaction. The `tx_blob` parameter was returned from the `sign` method. `rippled` provides the [`submit` method](rippled-apis.html#submit), allowing us to submit the signed transaction. This uses the `tx_blob` parameter that was returned by the `sign` method.
Request: Request:
@@ -468,557 +472,13 @@ The [`server_state` method](rippled-apis.html#server-state) (used earlier to det
} }
``` ```
Our example transaction specified `LastLedgerSequence` 10268600, based on the last validated ledger at the time, plus four. So to determine whether our missing transaction has permanently failed, our rippled server must have ledgers 10268597 through 10268600. If the server has those validated ledgers in its history, **and** `tx` returns `txnNotFound`, then the transaction has failed and will never be included in any ledger. in this case, application logic may dictate building and submitting a replacement transaction with the same account sequence and updated `LastLedgerSequence`. Our example transaction specified `LastLedgerSequence` 10268600, based on the last validated ledger at the time, plus four. So to determine whether our missing transaction has permanently failed, our `rippled` server must have ledgers 10268597 through 10268600. If the server has those validated ledgers in its history, **and** `tx` returns `txnNotFound`, then the transaction has failed and will never be included in any ledger. In this case, application logic may dictate building and submitting a replacement transaction with the same account sequence and updated `LastLedgerSequence`.
The server state may indicate a last validated ledger sequence number less than the specified `LastLedgerSequence`. If so, the `txnNotFound` indicates either (a) the submitted transaction failed to be distributed to the network, or (b) the transaction has been distributed to the network but has not yet been processed. To handle the former case, applications may submit again the same signed transaction. Because the transaction has a unique account sequence number, it will be processed at most once. The server state may indicate a last validated ledger sequence number less than the specified `LastLedgerSequence`. If so, the `txnNotFound` indicates either (a) the submitted transaction failed to be distributed to the network, or (b) the transaction has been distributed to the network but has not yet been processed. To handle the former case, applications may submit again the same signed transaction. Because the transaction has a unique account sequence number, it will be processed at most once.
Finally the server state might indicate one or more gaps in the transaction history. The `completed_ledgers` field shown in the response above indicates that ledgers 10256383 through 10256411 are missing from this rippled instance. Our example transaction can only appear in ledgers 10268597 - 10268600 (based on when it was submitted and `LastLedgerSequence`), so the gap shown here is not relevant. However, if the gap indicated a ledger in that range was missing, then an application would need to query another rippled server (or wait for this one to retrieve the missing ledgers) in order to determine that a `txnNotFound` result is immutable. Finally the server state might indicate one or more gaps in the transaction history. The `completed_ledgers` field shown in the response above indicates that ledgers 10256383 through 10256411 are missing from this rippled instance. Our example transaction can only appear in ledgers 10268597 - 10268600 (based on when it was submitted and `LastLedgerSequence`), so the gap shown here is not relevant. However, if the gap indicated a ledger in that range was missing, then an application would need to query another rippled server (or wait for this one to retrieve the missing ledgers) in order to determine that a `txnNotFound` result is immutable.
### Ripple-REST - Submitting and Verifying Payments
The [Ripple-REST API](ripple-rest.html) provides an interface to Ripple via a [RESTful API](https://en.wikipedia.org/wiki/Representational_state_transfer). It provides robust payment submission features, which include referencing payments by client provided identifiers, re-submitting payments in response to some errors, and automatically calculating transaction parameters such as account sequence, `LastLedgerSequence`, and transaction cost.
This examples that follow refer to Ripple-REST API for *payments*. The REST methods for setting trust lines and modifying account settings does not follow the same pattern. See [RLJS-126](https://ripplelabs.atlassian.net/browse/RLJS-126) for additional details.
#### Construct the Transaction
In Ripple-REST, a GET request retrieves the path options for a payment. The following example issues 10 FOO (a made-up currency) from one account to another.
```
GET /v1/accounts/rG5Ro9e3uGEZVCh3zu5gB9ydKUskCs221W/payments/paths/rawz2WQ8i9FdTHp4KSNpBdyxgFqNpKe8fM/10+FOO+rG5Ro9e3uGEZVCh3zu5gB9ydKUskCs221W
```
The response (below) indicates one payment path exists. (The `payments[0].paths` is present, and empty, when issuing currency directly.)
```
{
"payments": [
{
"no_direct_ripple": false,
"partial_payment": false,
"paths": "[]",
"invoice_id": "",
"destination_amount": {
"issuer": "rG5Ro9e3uGEZVCh3zu5gB9ydKUskCs221W",
"currency": "FOO",
"value": "10"
},
"destination_tag": "",
"destination_account": "rawz2WQ8i9FdTHp4KSNpBdyxgFqNpKe8fM",
"source_slippage": "0",
"source_amount": {
"issuer": "rG5Ro9e3uGEZVCh3zu5gB9ydKUskCs221W",
"currency": "FOO",
"value": "10"
},
"source_tag": "",
"source_account": "rG5Ro9e3uGEZVCh3zu5gB9ydKUskCs221W"
}
],
"success": true
}
```
#### Submit the Payment Transaction
Applications should persist a record of a transaction before submitting it, in order to recover from a catastrophic failure such as a power outage. Ripple-REST accepts a `client_resource_id` which allows an application to look up a transaction. For this example, let's say the application saves the details of the transaction to its payments table with ID 42, so the application creates `client_resource_id` "payment-42".
Before submitting, applications should persist the `client_resource_id`, transaction type, and source account.
Request:
```
POST /v1/accounts/:usGate/payments
Content-Type: application/json
{
"secret": "sssssssssssssssssssssss",
"client_resource_id": "payment-42",
"max_fee": ".1",
"payment": {
"no_direct_ripple": false,
"partial_payment": false,
"paths": "[]",
"invoice_id": "",
"destination_amount": {
"issuer": "rG5Ro9e3uGEZVCh3zu5gB9ydKUskCs221W",
"currency": "FOO",
"value": "10"
},
"destination_tag": "",
"destination_account": "rawz2WQ8i9FdTHp4KSNpBdyxgFqNpKe8fM",
"source_slippage": "0",
"source_amount": {
"issuer": "rG5Ro9e3uGEZVCh3zu5gB9ydKUskCs221W",
"currency": "FOO",
"value": "10"
},
"source_tag": "",
"source_account": "rG5Ro9e3uGEZVCh3zu5gB9ydKUskCs221W"
}
}
```
***Note: only submit your account secret to a trusted Ripple-REST server.***
Response:
```
{
success: true,
client_resource_id: 'payment-42',
status_url: 'http://127.0.0.1:5990/v1/accounts/rG5Ro9e3uGEZVCh3zu5gB9ydKUskCs221W/payments/payment-42' }
```
The payment result remains provisional at this point. Ripple-REST returns a `status_url` where we can eventually learn the final result of the transaction. The `status_url` is based on the `client_resource_id` persisted by the application before submission, so the application can construct the `status_url` even in the event of a power failure before this response is received.
#### Verify the Payment Transaction
A GET request to the transaction's `status_url` retrieves the result.
Request:
```
GET /v1/accounts/rG5Ro9e3uGEZVCh3zu5gB9ydKUskCs221W/payments/payment-42
```
Response:
```
{
"payment": {
"destination_balance_changes": [
{
"issuer": "rG5Ro9e3uGEZVCh3zu5gB9ydKUskCs221W",
"currency": "FOO",
"value": "10"
}
],
"source_balance_changes": [
{
"issuer": "",
"currency": "XRP",
"value": "-0.012"
},
{
"issuer": "rG5Ro9e3uGEZVCh3zu5gB9ydKUskCs221W",
"currency": "FOO",
"value": "-10"
}
],
"fee": "0.012",
"timestamp": "2014-12-02T23:10:10.000Z",
"hash": "DDF9F6E4DC64A1CB056570170FC06B2CBC2701CB500E44AC730BF8C868F6AA15",
"ledger": "10286112",
"result": "tesSUCCESS",
"state": "validated",
"direction": "outgoing",
"partial_payment": false,
"no_direct_ripple": false,
"paths": "[]",
"invoice_id": "",
"destination_amount": {
"value": "10",
"issuer": "rG5Ro9e3uGEZVCh3zu5gB9ydKUskCs221W",
"currency": "FOO"
},
"destination_tag": "",
"destination_account": "rawz2WQ8i9FdTHp4KSNpBdyxgFqNpKe8fM",
"source_slippage": "0",
"source_amount": {
"value": "10",
"issuer": "rG5Ro9e3uGEZVCh3zu5gB9ydKUskCs221W",
"currency": "FOO"
},
"source_tag": "",
"source_account": "rG5Ro9e3uGEZVCh3zu5gB9ydKUskCs221W"
},
"success": true
}
```
In this example, `payment.state: "validated"` indicates the transaction is in a validated ledger. Therefore the results are final and immutable. Any other value for `payment.state` indicates provisional results, an application must check again later to determine final results.
In the preceeding example, `payment.result: "tesSUCCESS"` (along with the `"validated"` state) indicates the payment has been delivered. Any other result code indicates the transaction did not succeed, and application logic may dictate constructing and submitting a new transaction to perform the desired operation.
#### Verify Missing or Failed Payment Transaction
When a GET request to the transaction's `status_url` returns an error, an application must determine whether the final result of a transaction is failure.
Request:
```
GET /v1/accounts/rG5Ro9e3uGEZVCh3zu5gB9ydKUskCs221W/payments/payment-42
```
Response:
```
{
"message": "Transaction not found.",
"error": "txnNotFound",
"error_type": "transaction",
"success": false
}
```
*Note:* The `txnNotFound` error shown above is the current behavior of ripple-REST, but will change in order to make it easier to determine the status of transactions in this case. Follow [RLJS-163](https://ripplelabs.atlassian.net/browse/RLJS-163) for updates regarding this behavior.
The `txnNotFound` error in this example indicates the transaction was received by Ripple-REST, but has failed to appear in a validated ledger. This could be caused certain transaction errors, or possibly because Ripple-REST lost power or network before submitting the transaction to the network. Application logic may dictate constructing and submitting a replacement transaction.
Another error response:
```
{
"message": "A transaction hash was not supplied and there were no entries matching the client_resource_id.",
"error": "Transaction not found",
"error_type": "invalid_request",
"success": false
}
```
This `"Transaction not found"` error indicates the transaction was not received by Ripple-REST, and therefore never sent to the network. Again, application logic may dictate constructing and submitting a replacement transaction.
### ripple-lib - Submitting and Verifying Transactions
[ripple-lib](https://github.com/ripple/ripple-lib) provides a Javascript API for Ripple in Node.js and web browsers. It provides features for robust transaction submission which including automatically calculating account sequence numbers and `LastLedgerSequence`.
#### Construct the Transaction
ripple-lib provides a high level API for creating transactions. In this example, a payment:
var tx = remote.createTransaction('Payment', {
account: ‘rG5Ro9e3uGEZVCh3zu5gB9ydKUskCs221W',
destination: ‘rawz2WQ8i9FdTHp4KSNpBdyxgFqNpKe8fM',
amount: ‘10/FOO/rG5Ro9e3uGEZVCh3zu5gB9ydKUskCs221W'
});
Note that ripple-lib will automatically provide additional details before the transaction is signed and submitted. These details include an account transaction Sequence, `LastLedgerSequence` and transaction cost.
Before submitting, applications should persist the transaction details, so that status may be verified in the event of a failure. Applications have an opportunity to do this by implementing [transaction event handlers](https://github.com/ripple/ripple-lib/blob/61afca2337927a4f331ae02770ccdad5d9bdef17/docs/REFERENCE.md#transaction-events). The `presubmit` event handler is appropriate for saving data before a transaction is submitted to the network. During normal operation, a `state` event is emitted whenever the transaction status changes, including final validation.
The example implementation (below) of a these event handlers simply logs some information about the transaction, in order to show some of the data available to applications. Live applications should implement handlers to **synchronously** persist transactions details, and should throw an error if unable to save the data.
// The 'presubmit' handler receives events before the transaction
// is submitted to the network; also before re-submit attempts.
tx.on('presubmit', function(data) {
console.log('- Presubmit Event Handler -');
// Log information about the transaction.
console.log(this.summary());
// Applications should persist transaction data syncronously,
// before returning from this event handler.
});
// The 'state' handler receives events after any state change, including...
tx.on('state', function(state) {
console.log('- State Event Hander: ' + state + ' -');
// Log information about the transaction.
console.log(this.summary());
// Applications should persist updated transaction state.
});
#### Submit the Transaction
ripple-lib provides `Transaction.submit()` to both sign and submit a transaction. In order to sign, an application must first call `Remote.setSecret(<account>, <secret>)`. Take care to configure ripple-lib to use local signing, as secrets should only be shared with trusted ripple servers.
tx.submit(function(err, res) {
if (err) {
console.log('- Transaction Submit Callback Error -');
console.log(err);
}
else {
console.log('- Transaction Submit Callback -');
console.log(util.inspect(res));
}
});
ripple-lib emits events as it processes the transaction. The presubmit event allows application to persist the transaction hash and other details before it is sent to the network.
```
- Presubmit Event Handler -
{ tx_json:
{ Flags: 2147483648,
TransactionType: 'Payment',
Account: 'rG5Ro9e3uGEZVCh3zu5gB9ydKUskCs221W',
Amount:
{ value: '10',
currency: 'FOO',
issuer: 'rG5Ro9e3uGEZVCh3zu5gB9ydKUskCs221W' },
Destination: 'rawz2WQ8i9FdTHp4KSNpBdyxgFqNpKe8fM',
Fee: '10000',
Sequence: 11,
SigningPubKey: '0267268EE0DDDEE6A862C9FF9DDAF898CF17060A673AF771B565AA2F4AE24E3FC5',
LastLedgerSequence: 10320276,
TxnSignature: '3045022100A61FA3AF1569BC4B1D2161F0055CF9760F8AC473ED374A98FE7E77099B8C63AD02200FF2A59CE4722FC246652125D3A13928392E7D0C5AC073314A573E93BF594856' },
clientID: undefined,
submittedIDs: [ '2120732F77002A9138DE110408EA06C2064F032BC9D44A28C46267C607594203' ],
submissionAttempts: 0,
submitIndex: 10320268,
initialSubmitIndex: 10320268,
lastLedgerSequence: 10320276,
state: 'unsubmitted',
server: undefined,
finalized: false }
```
Note in the preceeding example log output, `tx.state: 'unsubmitted'` indicates the transaction is not yet sent to the network. `tx.submittedIDs` includes the transaction hash, a unique identifier that applications should persist in order to later verify the status of the transaction. ripple-lib has automatically calculated `tx.tx_json.Sequence` and `tx.tx_json.LastLedgerSequence`.
ripple-lib will re-submit a transaction in response to certain errors. Prior to each submission the `presubmit` event provides up-to-date information about the transaction, which applications should persist.
```
- Presubmit Event Handler -
{ tx_json:
{ Flags: 2147483648,
TransactionType: 'Payment',
Account: 'rG5Ro9e3uGEZVCh3zu5gB9ydKUskCs221W',
Amount:
{ value: '10',
currency: 'FOO',
issuer: 'rG5Ro9e3uGEZVCh3zu5gB9ydKUskCs221W' },
Destination: 'rawz2WQ8i9FdTHp4KSNpBdyxgFqNpKe8fM',
Fee: '10000',
Sequence: 11,
SigningPubKey: '0267268EE0DDDEE6A862C9FF9DDAF898CF17060A673AF771B565AA2F4AE24E3FC5',
LastLedgerSequence: 10320278,
TxnSignature: '3045022100D5AC197A9EB35E86B70B4A02C19EC0120C1D6A539B1FE58C364322067E040AE102205EFE429FF40FAFAAAC58B653DCD25642D8A50E222C2D244105F43CEBAAC7DC89' },
clientID: undefined,
submittedIDs:
[ 'AD070F312DE0EB8AB64DDA0C512A4A1E9ED1ACE0AEFBBE6AA1418A2D6F137D13',
'2120732F77002A9138DE110408EA06C2064F032BC9D44A28C46267C607594203' ],
submissionAttempts: 1,
submitIndex: 10320270,
initialSubmitIndex: 10320268,
lastLedgerSequence: 10320278,
state: 'submitted',
server: undefined,
finalized: false,
result:
{ engine_result: 'telINSUF_FEE_P',
engine_result_message: 'Fee insufficient.',
ledger_hash: undefined,
ledger_index: undefined,
transaction_hash: '2120732F77002A9138DE110408EA06C2064F032BC9D44A28C46267C607594203' } }
```
The example above shows the transaction after 1 failed attempts, before a second attempt is submitted. Note that `tx.submittedIDs[0]` is the updated hash which applications should persist.
The `tx.result` is the **provisional** result of the **prior** submission attempt. In this example the initial submit failed with `telINSUF_FEE_P`, which could happen if the network adjusts the transaction cost calculated by ripple-lib immediately before the transaction is processed.
#### Verify the Transaction
During normal operation, events emitted by ripple-lib inform an application of the result of a transaction. The `state` event will emit with `tx.state: 'pending'` with a provisional result; and finally if successful with `tx.state: 'validated'` and `tx.finalized: true`.
```
- State Event Hander: validated -
{ tx_json:
{ Flags: 2147483648,
TransactionType: 'Payment',
Account: 'rG5Ro9e3uGEZVCh3zu5gB9ydKUskCs221W',
Amount:
{ value: '10',
currency: 'FOO',
issuer: 'rG5Ro9e3uGEZVCh3zu5gB9ydKUskCs221W' },
Destination: 'rawz2WQ8i9FdTHp4KSNpBdyxgFqNpKe8fM',
Sequence: 11,
SigningPubKey: '0267268EE0DDDEE6A862C9FF9DDAF898CF17060A673AF771B565AA2F4AE24E3FC5',
Fee: '12000',
LastLedgerSequence: 10320625,
TxnSignature: '3045022100DEFA085B88834F3C27200714AB40F3A67E7E86E726DE630A2955843F6D53010D02202592D709D5F90F9E852CEFB0D5A7F6D39AC0A99BC97A3589BF9FA47018C2CB2C' },
clientID: undefined,
submittedIDs: [ '0E066642EC28DA3C9840202AF4F3CD281A5A2733F2D9BEF38C69DFDC14407E12' ],
submissionAttempts: 1,
submitIndex: 10320617,
initialSubmitIndex: 10320617,
lastLedgerSequence: 10320625,
state: 'validated',
server: undefined,
finalized: true,
result:
{ engine_result: 'tesSUCCESS',
engine_result_message: 'The transaction was applied.',
ledger_hash: '7F936E0F37611982A434B76270C819FDA8240649D7592BDC995FC9AEE2D436AA',
ledger_index: 10320618,
transaction_hash: '0E066642EC28DA3C9840202AF4F3CD281A5A2733F2D9BEF38C69DFDC14407E12' } }
```
If the final state of a transaction is an error, the state event indicates `tx.state: 'failed'` and `tx.finalized: 'true'`:
```
- State Event Hander: failed -
{ tx_json:
{ Flags: 2147483648,
TransactionType: 'Payment',
Account: 'rG5Ro9e3uGEZVCh3zu5gB9ydKUskCs221W',
Amount:
{ value: '10',
currency: 'FOO',
issuer: 'rG5Ro9e3uGEZVCh3zu5gB9ydKUskCs221W' },
Destination: 'rawz2WQ8i9FdTHp4KSNpBdyxgFqNpKe8fM',
Fee: '10000',
Sequence: 11,
SigningPubKey: '0267268EE0DDDEE6A862C9FF9DDAF898CF17060A673AF771B565AA2F4AE24E3FC5',
LastLedgerSequence: 10320296,
TxnSignature: '304402201E3D376CF7C1C99EAC19027EA3EDE15F24D8FA59D4EA90067A09267F8D927ABB0220084B8BFF7D9308CD00A5DA265776DC9BAB9F553A9E6A4ED1A75DD76DCB3B40A9' },
clientID: undefined,
submittedIDs:
[ '895DA495779D51F84E4B79258AAF9A8E51404A79747DD936EE6468FE9A974AEE',
'F14AE631317D11184DEC7066814539E9BB50AB46DF770E3F2367430810C0AE7C',
'80F7460AD3F8172F9CDD69B638E4EA7ED9466A4D495EF8530FE98B8A0909E897',
'23F59C223701D73C2477963E4D1FA3460DAD5A64D813FB9591AF45C4C68A339B',
'B929D9018E842A56FFCA8EB295EDA81C62AE37804F759A19E0B1292C888C8586',
'EC9B4D869B8B9C27F644859F203D54023B01F6C2E9FA12CD34AC8373F9BA67A5',
'47FD42A6604D74A89E006352FBC656843A270EF46B47A3EB1D1098A31A01BC3D',
'BD3D13C57A5FDBB9B1F88C287EC158AA92BF9B75078273678F3124C84F504ABA',
'0B2CC389D5553FB232E4EF45EC67D149B8CD65E17C4BE7A41B5142A0D4A935BD',
'AD070F312DE0EB8AB64DDA0C512A4A1E9ED1ACE0AEFBBE6AA1418A2D6F137D13',
'2120732F77002A9138DE110408EA06C2064F032BC9D44A28C46267C607594203' ],
submissionAttempts: 11,
submitIndex: 10320288,
initialSubmitIndex: 10320268,
lastLedgerSequence: 10320296,
state: 'failed',
server: undefined,
finalized: true,
result:
{ engine_result: 'telINSUF_FEE_P',
engine_result_message: 'Fee insufficient.',
ledger_hash: undefined,
ledger_index: undefined,
transaction_hash: '895DA495779D51F84E4B79258AAF9A8E51404A79747DD936EE6468FE9A974AEE' } }
```
In the event of a power or network failure, an application may be interrupted before these `state` events are emitted. In these cases, applications should retrieve the status of a transaction by its `hash`, one of the details persisted during an earlier `presubmit` event.
var hash = 'C3306CA3ED1B372EAC8A84A84B52752A4E4912BB1A26AB883E969BC987E4D20E';
remote.requestTransaction(hash, function(err, result) {
if (err) {
console.log(err);
}
else {
console.log(result);
}
});
Result of `remote.requestTransaction(<transaction hash>)`:
```
{ Account: 'rG5Ro9e3uGEZVCh3zu5gB9ydKUskCs221W',
Amount:
{ currency: 'FOO',
issuer: 'rG5Ro9e3uGEZVCh3zu5gB9ydKUskCs221W',
value: '10' },
Destination: 'rawz2WQ8i9FdTHp4KSNpBdyxgFqNpKe8fM',
Fee: '10000',
Flags: 2147483648,
LastLedgerSequence: 10303055,
Sequence: 10,
SigningPubKey: '0267268EE0DDDEE6A862C9FF9DDAF898CF17060A673AF771B565AA2F4AE24E3FC5',
TransactionType: 'Payment',
TxnSignature: '304402200C65A9FD9EA7000DCD87688BA92C219074858D530E9A75F32EF2DA1A9C07844E02203A72B2688412CF855306E70D9B9ED541B67BEA8A8EDB90D47B7B227B295CED9B',
date: 470953270,
hash: 'C3306CA3ED1B372EAC8A84A84B52752A4E4912BB1A26AB883E969BC987E4D20E',
inLedger: 10303048,
ledger_index: 10303048,
meta:
{ AffectedNodes: [ [Object], [Object] ],
TransactionIndex: 23,
TransactionResult: 'tesSUCCESS' },
validated: true }
```
Note the response from `requestTransaction` includes **`validated: true`**, indicating the result is in a validated ledger and is final. Without `validated: true`, results are *provisional* and may change. This example shows `meta.TransactionResult: 'tesSUCCESS'`, indicating the transaction was successful.
#### Verify Missing Transaction
`Remote.requestTransaction` may return `txNotFound`:
```
{ [RippleError: Remote reported an error.]
error: 'remoteError',
error_message: 'Remote reported an error.',
remote:
{ error: 'txnNotFound',
error_code: 24,
error_message: 'Transaction not found.',
id: 1,
request:
{ command: 'tx',
id: 1,
transaction: 'F85D840B152328A1A6C11910A6FBF57E1340B6285E3602A1258B7A41EC814119' },
status: 'error',
type: 'response' },
result: 'remoteError',
engine_result: 'remoteError',
result_message: 'Remote reported an error.',
engine_result_message: 'Remote reported an error.',
message: 'Remote reported an error.' }
```
In these cases an application must distinguish between a provisional result and a final result. For this, an application needs the transaction's `initialSubmitIndex` and `LastLedgerSequence`. This information was persisted earlier by the application's `presubmit` event handler. In this example, `initialSubmitIndex` is 10301323 and `LastLedgerSequence` is 10301337.
A call to `Remote.requestServerInfo()` determines whether the server has final, immutable results about the transaction.
remote.requestServerInfo(function(err, result) {
if (err) {
console.log(err);
}
else {
console.log(result);
}
});
Result of `remote.requestServerInfo()`:
```
{ info:
{ build_version: '0.26.4-sp3-private',
complete_ledgers: '32570-10302948',
hostid: 'KNOW',
io_latency_ms: 1,
last_close: { converge_time_s: 2.001, proposers: 5 },
load_factor: 1000,
peers: 44,
pubkey_node: 'n9MADAXTbCnaBYoUcvDzHkTqoTSjVd8VHgJE2KwMBbwRV4pM3j2a',
server_state: 'full',
validated_ledger:
{ age: 4,
base_fee_xrp: 0.00001,
hash: '47EE6EC414FC0B648869CE7108143D916DE38DAC167DADEF541F9A8CED475909',
reserve_base_xrp: 20,
reserve_inc_xrp: 5,
seq: 10302948 },
validation_quorum: 3 } }
```
In this example, `info.complete_ledgers` indicates the server has continuous ledger history up to ledger sequence 10302948. This history includes the span of ledger where the transaction may appear, from 10301323 to 10301337. Therefore, the `txNotFound` result is final, and the transaction has failed immutably.
If the ledger history were not complete through the `LastLedgerSequence`, the application must wait for that ledger to become validated, or the server to sync a more complete history with the network.
## Additional Resources ## Additional Resources
- [Transaction Format](transactions.html) - [Transaction Format](transactions.html)

2
content/rippled.md
View File

@@ -8,7 +8,7 @@ The core peer-to-peer server that operates the Ripple Network is called `rippled
* Client Library - [Javascript](https://github.com/ripple/ripple-lib) * Client Library - [Javascript](https://github.com/ripple/ripple-lib)
# WebSocket and JSON-RPC APIs # # WebSocket and JSON-RPC APIs #
If you want to communicate directly with the `rippled` server, you can use either the WebSocket API or the JSON-RPC API. Both APIs use the same list of commands, with almost entirely the same parameters in each command. Whereas the [Ripple-REST API](ripple-rest.html) provides a simplified interface on top of the WebSocket API for easier integration, these APIs provide the full power of Ripple but require slightly more complexity: If you want to communicate directly with the `rippled` server, you can use either the WebSocket API or the JSON-RPC API. Both APIs use the same list of commands, with almost entirely the same parameters in each command.
* The WebSocket API uses the [WebSocket protocol](http://www.html5rocks.com/en/tutorials/websockets/basics/), available in most browsers and Javascript implementations, to achieve persistent two-way communication. There is not a 1:1 correlation between requests and responses. Some requests prompt the server to send multiple messages back asynchronously; other times, responses may arrive in a different order than the requests that prompted them. The `rippled` server can be configured to accept secured (wss:), unsecured (ws:) WebSocket connections, or both. * The WebSocket API uses the [WebSocket protocol](http://www.html5rocks.com/en/tutorials/websockets/basics/), available in most browsers and Javascript implementations, to achieve persistent two-way communication. There is not a 1:1 correlation between requests and responses. Some requests prompt the server to send multiple messages back asynchronously; other times, responses may arrive in a different order than the requests that prompted them. The `rippled` server can be configured to accept secured (wss:), unsecured (ws:) WebSocket connections, or both.
* The JSON-RPC API relies on simple request-response communication via HTTP or HTTPS. (The `rippled` server can be configured to accept HTTP, HTTPS, or both.) For commands that prompt multiple responses, you can provide a callback URL. * The JSON-RPC API relies on simple request-response communication via HTTP or HTTPS. (The `rippled` server can be configured to accept HTTP, HTTPS, or both.) For commands that prompt multiple responses, you can provide a callback URL.

2511
content/ripplerest_api.md
View File

File diff suppressed because it is too large Load Diff

14
content/transferrate.md
View File

@@ -26,19 +26,19 @@ In this scenario, Salazar (the sender) holds EUR issued by ACME, and wants to de
The transfer fee is represented by a setting on the issuing (**cold wallet**) account. The transfer fee has a maximum precision of 9 digits, and cannot be less than 0% or greater than 100%. The TransferRate setting applies to all currencies issued by the same account. If you want to have different transfer fee percentages for different currencies, use different cold wallets to issue each currency. The transfer fee is represented by a setting on the issuing (**cold wallet**) account. The transfer fee has a maximum precision of 9 digits, and cannot be less than 0% or greater than 100%. The TransferRate setting applies to all currencies issued by the same account. If you want to have different transfer fee percentages for different currencies, use different cold wallets to issue each currency.
## Ripple-REST ## ## RippleAPI ##
In Ripple-REST, the transfer fee is specified in the `transfer_rate` field, as a decimal which represents the amount you must send in order for the recipient to get 1 unit of the same currency. A `transfer_rate` of `1.005` is equivalent to a transfer fee of 0.5%. By default, the `transfer_rate` is set at `1.0`, indicating no fee. The value of `transfer_rate` cannot be less than `1.0` or more than `2.0`. However, the value `0` is special: it is equivalent to `1.0`, meaning no fee. In RippleAPI, the transfer fee is specified in the `transferRate` field, as an integer which represents the amount you must send in order for the recipient to get 1 billion units of the same currency. A `transferRate` of `1005000000` is equivalent to a transfer fee of 0.5%. By default, the `transferRate` is set to no fee. The value of `transferRate` cannot be less than `1000000000` or more than `2000000000`. The value `null` is special: it is equivalent to `1000000000`, meaning no fee.
A gateway can use the [Update Account Settings method](https://ripple.com/build/ripple-rest/#update-account-settings) with its cold wallet to change the `transfer_rate` for its issuances. A gateway can send a [Settings transaction](rippleapi.html#settings) with its cold wallet to change the `transferRate` for its issuances.
You can check an account's `transfer_rate` with the [Get Account Settings method](https://ripple.com/build/ripple-rest/#get-account-settings). You can check an account's `transferRate` with the [getSettings method](rippleapi.html#getsettings).
## rippled ## ## rippled ##
In `rippled`'s JSON-RPC and WebSocket APIs, the transfer fee is specified in the `TransferRate` field, as an integer which represents the amount you must send in order for the recipient to get 1 billion units of the same currency. A `TransferRate` of `1005000000` is equivalent to a transfer fee of 0.5%. By default, the `transfer_rate` is set at `1000000000`, indicating no fee. The value of `TransferRate` cannot be less than `1000000000` or more than `2000000000`. However, value `0` is special: it is equivalent to `1000000000`, meaning no fee. In `rippled`'s JSON-RPC and WebSocket APIs, the transfer fee is specified in the `TransferRate` field, as an integer which represents the amount you must send in order for the recipient to get 1 billion units of the same currency. A `TransferRate` of `1005000000` is equivalent to a transfer fee of 0.5%. By default, the `TransferRate` is set at `1000000000`, indicating no fee. The value of `TransferRate` cannot be less than `1000000000` or more than `2000000000`. However, value `0` is special: it is equivalent to `1000000000`, meaning no fee.
A gateway can submit an [AccountSet transaction](https://ripple.com/build/transactions/#accountset) from its cold wallet to change the `TransferRate` for its issuances. A gateway can submit an [AccountSet transaction](transactions.html#accountset) from its cold wallet to change the `TransferRate` for its issuances.
You can check an account's `TransferRate` with the [account_info command](https://ripple.com/build/rippled-apis/#account-info). If the `TransferRate` is omitted, then that indicates no fee. You can check an account's `TransferRate` with the [`account_info` command](rippled-apis.html#account-info). If the `TransferRate` is omitted, then that indicates no fee.

13
content/whitepapers.md
View File

@@ -1,13 +0,0 @@
Ripple Whitepapers
==================
Ripple has published several whitepapers on the benefits and workings of the Ripple technology stack. The following is a brief selection of useful papers:
* [Ripple Primer](https://ripple.com/ripple_primer.pdf) (PDF)
* [Gateway whitepaper](https://ripple.com/ripple-gateways.pdf) (PDF)
* [Market makers whitepaper](https://ripple.com/ripple-mm.pdf) (PDF)
* [Financial institutions whitepaper](https://ripple.com/ripple-FIs.pdf) (PDF)
* [The Ripple Protocol: A Deep Dive for Finance Professionals](https://ripple.com/files/ripple_deep_dive_final.pdf) (PDF)
* [The Ripple Protocol Consensus Algorithm](https://ripple.com/files/ripple_consensus_whitepaper.pdf) (PDF)
You can find further information about Ripple in the [Knowledge Center](https://ripple.com/knowledge-center/).

3
data-api-v2-tool.html
View File

@@ -60,7 +60,6 @@
<a href="#" class="dropdown-toggle" data-toggle="dropdown">References <span class="caret"></span></a> <a href="#" class="dropdown-toggle" data-toggle="dropdown">References <span class="caret"></span></a>
<ul class="dropdown-menu" role="menu"> <ul class="dropdown-menu" role="menu">
<li><a href="rippled-apis.html">rippled</a></li> <li><a href="rippled-apis.html">rippled</a></li>
<li><a href="ripple-rest.html">Ripple-REST</a></li>
<li><a href="transactions.html">Transactions</a></li> <li><a href="transactions.html">Transactions</a></li>
<li><a href="ripple-ledger.html">Ledger Format</a></li> <li><a href="ripple-ledger.html">Ledger Format</a></li>
<li><a href="data_api_v2.html">Ripple Data API v2</a></li> <li><a href="data_api_v2.html">Ripple Data API v2</a></li>
@@ -78,7 +77,6 @@
<li class="dropdown"> <li class="dropdown">
<a href="#" class="dropdown-toggle" data-toggle="dropdown">API Tools <span class="caret"></span></a> <a href="#" class="dropdown-toggle" data-toggle="dropdown">API Tools <span class="caret"></span></a>
<ul class="dropdown-menu" role="menu"> <ul class="dropdown-menu" role="menu">
<li><a href="rest-api-tool.html">Ripple-REST API Tool</a></li>
<li><a href="ripple-api-tool.html">WebSocket API Tool</a></li> <li><a href="ripple-api-tool.html">WebSocket API Tool</a></li>
<li><a href="data-api-v2-tool.html">Data API v2 Tool</a></li> <li><a href="data-api-v2-tool.html">Data API v2 Tool</a></li>
</ul> </ul>
@@ -160,7 +158,6 @@
<li><a href="freeze.html">Freeze</a></li> <li><a href="freeze.html">Freeze</a></li>
<li><a href="rippled-apis.html">rippled</a></li> <li><a href="rippled-apis.html">rippled</a></li>
<li><a href="rippled-setup.html">rippled Setup</a></li> <li><a href="rippled-setup.html">rippled Setup</a></li>
<li><a href="ripple-rest.html">Ripple-REST</a></li>
<li><a href="transactions.html">Transactions</a></li> <li><a href="transactions.html">Transactions</a></li>
<li><a href="ripple-ledger.html">Ledger Format</a></li> <li><a href="ripple-ledger.html">Ledger Format</a></li>
<li><a href="reliable_tx.html">Reliable Transaction Submission</a></li> <li><a href="reliable_tx.html">Reliable Transaction Submission</a></li>

3
data_api_v2.html
View File

@@ -81,7 +81,6 @@
<a href="#" class="dropdown-toggle" data-toggle="dropdown">References <span class="caret"></span></a> <a href="#" class="dropdown-toggle" data-toggle="dropdown">References <span class="caret"></span></a>
<ul class="dropdown-menu" role="menu"> <ul class="dropdown-menu" role="menu">
<li><a href="rippled-apis.html">rippled</a></li> <li><a href="rippled-apis.html">rippled</a></li>
<li><a href="ripple-rest.html">Ripple-REST</a></li>
<li><a href="transactions.html">Transactions</a></li> <li><a href="transactions.html">Transactions</a></li>
<li><a href="ripple-ledger.html">Ledger Format</a></li> <li><a href="ripple-ledger.html">Ledger Format</a></li>
<li><a href="data_api_v2.html">Ripple Data API v2</a></li> <li><a href="data_api_v2.html">Ripple Data API v2</a></li>
@@ -99,7 +98,6 @@
<li class="dropdown"> <li class="dropdown">
<a href="#" class="dropdown-toggle" data-toggle="dropdown">API Tools <span class="caret"></span></a> <a href="#" class="dropdown-toggle" data-toggle="dropdown">API Tools <span class="caret"></span></a>
<ul class="dropdown-menu" role="menu"> <ul class="dropdown-menu" role="menu">
<li><a href="rest-api-tool.html">Ripple-REST API Tool</a></li>
<li><a href="ripple-api-tool.html">WebSocket API Tool</a></li> <li><a href="ripple-api-tool.html">WebSocket API Tool</a></li>
<li><a href="data-api-v2-tool.html">Data API v2 Tool</a></li> <li><a href="data-api-v2-tool.html">Data API v2 Tool</a></li>
</ul> </ul>
@@ -5242,7 +5240,6 @@ node import/hbase/backfill --startIndex 2000000 --stopIndex 1000000
<li><a href="freeze.html">Freeze</a></li> <li><a href="freeze.html">Freeze</a></li>
<li><a href="rippled-apis.html">rippled</a></li> <li><a href="rippled-apis.html">rippled</a></li>
<li><a href="rippled-setup.html">rippled Setup</a></li> <li><a href="rippled-setup.html">rippled Setup</a></li>
<li><a href="ripple-rest.html">Ripple-REST</a></li>
<li><a href="transactions.html">Transactions</a></li> <li><a href="transactions.html">Transactions</a></li>
<li><a href="ripple-ledger.html">Ledger Format</a></li> <li><a href="ripple-ledger.html">Ledger Format</a></li>
<li><a href="reliable_tx.html">Reliable Transaction Submission</a></li> <li><a href="reliable_tx.html">Reliable Transaction Submission</a></li>

3
fee-voting.html
View File

@@ -81,7 +81,6 @@
<a href="#" class="dropdown-toggle" data-toggle="dropdown">References <span class="caret"></span></a> <a href="#" class="dropdown-toggle" data-toggle="dropdown">References <span class="caret"></span></a>
<ul class="dropdown-menu" role="menu"> <ul class="dropdown-menu" role="menu">
<li><a href="rippled-apis.html">rippled</a></li> <li><a href="rippled-apis.html">rippled</a></li>
<li><a href="ripple-rest.html">Ripple-REST</a></li>
<li><a href="transactions.html">Transactions</a></li> <li><a href="transactions.html">Transactions</a></li>
<li><a href="ripple-ledger.html">Ledger Format</a></li> <li><a href="ripple-ledger.html">Ledger Format</a></li>
<li><a href="data_api_v2.html">Ripple Data API v2</a></li> <li><a href="data_api_v2.html">Ripple Data API v2</a></li>
@@ -99,7 +98,6 @@
<li class="dropdown"> <li class="dropdown">
<a href="#" class="dropdown-toggle" data-toggle="dropdown">API Tools <span class="caret"></span></a> <a href="#" class="dropdown-toggle" data-toggle="dropdown">API Tools <span class="caret"></span></a>
<ul class="dropdown-menu" role="menu"> <ul class="dropdown-menu" role="menu">
<li><a href="rest-api-tool.html">Ripple-REST API Tool</a></li>
<li><a href="ripple-api-tool.html">WebSocket API Tool</a></li> <li><a href="ripple-api-tool.html">WebSocket API Tool</a></li>
<li><a href="data-api-v2-tool.html">Data API v2 Tool</a></li> <li><a href="data-api-v2-tool.html">Data API v2 Tool</a></li>
</ul> </ul>
@@ -193,7 +191,6 @@
<li><a href="freeze.html">Freeze</a></li> <li><a href="freeze.html">Freeze</a></li>
<li><a href="rippled-apis.html">rippled</a></li> <li><a href="rippled-apis.html">rippled</a></li>
<li><a href="rippled-setup.html">rippled Setup</a></li> <li><a href="rippled-setup.html">rippled Setup</a></li>
<li><a href="ripple-rest.html">Ripple-REST</a></li>
<li><a href="transactions.html">Transactions</a></li> <li><a href="transactions.html">Transactions</a></li>
<li><a href="ripple-ledger.html">Ledger Format</a></li> <li><a href="ripple-ledger.html">Ledger Format</a></li>
<li><a href="reliable_tx.html">Reliable Transaction Submission</a></li> <li><a href="reliable_tx.html">Reliable Transaction Submission</a></li>

3
fees.html
View File

@@ -81,7 +81,6 @@
<a href="#" class="dropdown-toggle" data-toggle="dropdown">References <span class="caret"></span></a> <a href="#" class="dropdown-toggle" data-toggle="dropdown">References <span class="caret"></span></a>
<ul class="dropdown-menu" role="menu"> <ul class="dropdown-menu" role="menu">
<li><a href="rippled-apis.html">rippled</a></li> <li><a href="rippled-apis.html">rippled</a></li>
<li><a href="ripple-rest.html">Ripple-REST</a></li>
<li><a href="transactions.html">Transactions</a></li> <li><a href="transactions.html">Transactions</a></li>
<li><a href="ripple-ledger.html">Ledger Format</a></li> <li><a href="ripple-ledger.html">Ledger Format</a></li>
<li><a href="data_api_v2.html">Ripple Data API v2</a></li> <li><a href="data_api_v2.html">Ripple Data API v2</a></li>
@@ -99,7 +98,6 @@
<li class="dropdown"> <li class="dropdown">
<a href="#" class="dropdown-toggle" data-toggle="dropdown">API Tools <span class="caret"></span></a> <a href="#" class="dropdown-toggle" data-toggle="dropdown">API Tools <span class="caret"></span></a>
<ul class="dropdown-menu" role="menu"> <ul class="dropdown-menu" role="menu">
<li><a href="rest-api-tool.html">Ripple-REST API Tool</a></li>
<li><a href="ripple-api-tool.html">WebSocket API Tool</a></li> <li><a href="ripple-api-tool.html">WebSocket API Tool</a></li>
<li><a href="data-api-v2-tool.html">Data API v2 Tool</a></li> <li><a href="data-api-v2-tool.html">Data API v2 Tool</a></li>
</ul> </ul>
@@ -164,7 +162,6 @@
<li><a href="freeze.html">Freeze</a></li> <li><a href="freeze.html">Freeze</a></li>
<li><a href="rippled-apis.html">rippled</a></li> <li><a href="rippled-apis.html">rippled</a></li>
<li><a href="rippled-setup.html">rippled Setup</a></li> <li><a href="rippled-setup.html">rippled Setup</a></li>
<li><a href="ripple-rest.html">Ripple-REST</a></li>
<li><a href="transactions.html">Transactions</a></li> <li><a href="transactions.html">Transactions</a></li>
<li><a href="ripple-ledger.html">Ledger Format</a></li> <li><a href="ripple-ledger.html">Ledger Format</a></li>
<li><a href="reliable_tx.html">Reliable Transaction Submission</a></li> <li><a href="reliable_tx.html">Reliable Transaction Submission</a></li>

18
freeze.html
View File

@@ -81,7 +81,6 @@
<a href="#" class="dropdown-toggle" data-toggle="dropdown">References <span class="caret"></span></a> <a href="#" class="dropdown-toggle" data-toggle="dropdown">References <span class="caret"></span></a>
<ul class="dropdown-menu" role="menu"> <ul class="dropdown-menu" role="menu">
<li><a href="rippled-apis.html">rippled</a></li> <li><a href="rippled-apis.html">rippled</a></li>
<li><a href="ripple-rest.html">Ripple-REST</a></li>
<li><a href="transactions.html">Transactions</a></li> <li><a href="transactions.html">Transactions</a></li>
<li><a href="ripple-ledger.html">Ledger Format</a></li> <li><a href="ripple-ledger.html">Ledger Format</a></li>
<li><a href="data_api_v2.html">Ripple Data API v2</a></li> <li><a href="data_api_v2.html">Ripple Data API v2</a></li>
@@ -99,7 +98,6 @@
<li class="dropdown"> <li class="dropdown">
<a href="#" class="dropdown-toggle" data-toggle="dropdown">API Tools <span class="caret"></span></a> <a href="#" class="dropdown-toggle" data-toggle="dropdown">API Tools <span class="caret"></span></a>
<ul class="dropdown-menu" role="menu"> <ul class="dropdown-menu" role="menu">
<li><a href="rest-api-tool.html">Ripple-REST API Tool</a></li>
<li><a href="ripple-api-tool.html">WebSocket API Tool</a></li> <li><a href="ripple-api-tool.html">WebSocket API Tool</a></li>
<li><a href="data-api-v2-tool.html">Data API v2 Tool</a></li> <li><a href="data-api-v2-tool.html">Data API v2 Tool</a></li>
</ul> </ul>
@@ -140,7 +138,7 @@
<ul> <ul>
<li><a href="#individual-freeze"><strong>Individual Freeze</strong></a> - Freeze one counterparty.</li> <li><a href="#individual-freeze"><strong>Individual Freeze</strong></a> - Freeze one counterparty.</li>
<li><a href="#global-freeze"><strong>Global Freeze</strong></a> - Freeze all counterparties.</li> <li><a href="#global-freeze"><strong>Global Freeze</strong></a> - Freeze all counterparties.</li>
<li><a href="#no-freeze"><strong>No Freeze</strong></a> - Permanently give up the ability to freeze individual counterparties. Also gives up the ability to end a global freeze.</li> <li><a href="#no-freeze"><strong>No Freeze</strong></a> - Permanently give up the ability to freeze individual counterparties, as well as the ability to end a global freeze.</li>
</ul> </ul>
<p>Because no party has a privileged place in the Ripple Consensus Ledger, the freeze feature cannot prevent a counterparty from conducting transactions in XRP or funds issued by other counterparties. No one can freeze XRP.</p> <p>Because no party has a privileged place in the Ripple Consensus Ledger, the freeze feature cannot prevent a counterparty from conducting transactions in XRP or funds issued by other counterparties. No one can freeze XRP.</p>
<p>All freeze settings can be enacted regardless of whether the balance(s) to be frozen are positive or negative. Either the currency issuer or the currency holder can freeze a trust line; however, the effect of a currency holder freezing an issuer is minimal.</p> <p>All freeze settings can be enacted regardless of whether the balance(s) to be frozen are positive or negative. Either the currency issuer or the currency holder can freeze a trust line; however, the effect of a currency holder freezing an issuer is minimal.</p>
@@ -148,12 +146,12 @@
<p>The <strong>Individual Freeze</strong> feature is a setting on a trust line. When an issuing account enables the Individual Freeze setting, the following rules apply:</p> <p>The <strong>Individual Freeze</strong> feature is a setting on a trust line. When an issuing account enables the Individual Freeze setting, the following rules apply:</p>
<ul> <ul>
<li>Payments can still occur directly between the two parties of the frozen trust line.</li> <li>Payments can still occur directly between the two parties of the frozen trust line.</li>
<li>The counterparty of that trust line can no longer decrease its balance on the frozen trust line, except in direct payments to the issuer.</li> <li>The counterparty of that trust line can no longer decrease its balance on the frozen trust line, except in direct payments to the issuer. The counterparty can only send the frozen issuances directly to the issuer.</li>
<li>The counterparty can still receive payments from others on the frozen trust line.</li> <li>The counterparty can still receive payments from others on the frozen trust line.</li>
<li>The counterparty's offers to sell the currency issued on the frozen trust line are <a href="transactions.html#lifecycle-of-an-offer">considered unfunded</a>.</li> <li>The counterparty's offers to sell the currency issued on the frozen trust line are <a href="transactions.html#lifecycle-of-an-offer">considered unfunded</a>.</li>
</ul> </ul>
<p>A gateway can freeze the trust line linking it to a counterparty if that counterparty shows suspicious activity or violates the gateway's terms of use. The gateway should also freeze the counterparty in any connector systems the gateway operates. (Otherwise, an account could still engage in undesired activity by sending payments through the gateway's connector.)</p> <p>A gateway can freeze the trust line linking it to a counterparty if that counterparty shows suspicious activity or violates the gateway's terms of use. The gateway should also freeze the counterparty in any other systems the gateway operates that are connected to the Ripple Consensus Ledger. (Otherwise, an account might still be able to engage in undesired activity by sending payments through the gateway.)</p>
<p>An individual can freeze the trust line to a gateway. This has no effect on transactions between the gateway and other users. It does, however, prevent other accounts, including <a href="gateway_guide.html#hot-and-cold-wallets">hot wallets</a> from sending that gateway's issued currency to the individual. It has no effect on offers.</p> <p>An individual account can freeze its trust line to a gateway. This has no effect on transactions between the gateway and other users. It does, however, prevent other accounts, including <a href="gateway_guide.html#hot-and-cold-wallets">hot wallets</a>, from sending that gateway's issued currency to the individual account. This type of individual freeze has no effect on offers.</p>
<p>The Individual Freeze applies to a single currency only. In order to freeze multiple currencies with a particular counterparty, the account must enable Individual Freeze on the trust lines for each currency individually.</p> <p>The Individual Freeze applies to a single currency only. In order to freeze multiple currencies with a particular counterparty, the account must enable Individual Freeze on the trust lines for each currency individually.</p>
<p>An account cannot enable the Individual Freeze setting if it has previously enabled the <a href="#no-freeze">No Freeze</a> setting.</p> <p>An account cannot enable the Individual Freeze setting if it has previously enabled the <a href="#no-freeze">No Freeze</a> setting.</p>
<h2 id="global-freeze">Global Freeze</h2> <h2 id="global-freeze">Global Freeze</h2>
@@ -170,7 +168,7 @@
<h2 id="no-freeze">No Freeze</h2> <h2 id="no-freeze">No Freeze</h2>
<p>The <strong>No Freeze</strong> feature is a setting on an account that permanently gives up the ability to freeze counterparties. A business can use this feature to treat its issued funds as "more like physical money" in the sense that the business cannot interfere with customers trading it among themselves. The NoFreeze setting has two effects:</p> <p>The <strong>No Freeze</strong> feature is a setting on an account that permanently gives up the ability to freeze counterparties. A business can use this feature to treat its issued funds as "more like physical money" in the sense that the business cannot interfere with customers trading it among themselves. The NoFreeze setting has two effects:</p>
<ul> <ul>
<li>The issuing account can no longer use enable Individual Freeze on any counterparty.</li> <li>The issuing account can no longer enable Individual Freeze on trust lines to any counterparty.</li>
<li>The issuing account can still enable Global Freeze to enact a global freeze, but the account cannot <em>disable</em> Global Freeze.</li> <li>The issuing account can still enable Global Freeze to enact a global freeze, but the account cannot <em>disable</em> Global Freeze.</li>
</ul> </ul>
<p>The Ripple Consensus Ledger cannot force a gateway to honor the obligations that its issued funds represent, so giving up the ability to enable a Global Freeze cannot protect customers. However, giving up the ability to <em>disable</em> a Global Freeze ensures that the Global Freeze feature is not used unfairly against some customers.</p> <p>The Ripple Consensus Ledger cannot force a gateway to honor the obligations that its issued funds represent, so giving up the ability to enable a Global Freeze cannot protect customers. However, giving up the ability to <em>disable</em> a Global Freeze ensures that the Global Freeze feature is not used unfairly against some customers.</p>
@@ -815,7 +813,10 @@ api.connect().then(() =&gt; {
}).catch(console.error); }).catch(console.error);
</code></pre> </code></pre>
<h1 id="see-also">See Also</h1> <h1 id="see-also">See Also</h1>
<p><a href="https://ripple.com/files/GB-2014-02.pdf">Gateway Bulletin GB-2014-02 New Feature: Balance Freeze</a></p> <ul>
<li><a href="https://ripple.com/files/GB-2014-02.pdf">Gateway Bulletin GB-2014-02 New Feature: Balance Freeze</a></li>
<li><a href="https://github.com/ripple/ripple-dev-portal/tree/gh-pages/content/code_samples/freeze">Freeze Code Samples</a></li>
</ul>
</div> </div>
</div> </div>
</div> </div>
@@ -834,7 +835,6 @@ api.connect().then(() =&gt; {
<li><a href="freeze.html">Freeze</a></li> <li><a href="freeze.html">Freeze</a></li>
<li><a href="rippled-apis.html">rippled</a></li> <li><a href="rippled-apis.html">rippled</a></li>
<li><a href="rippled-setup.html">rippled Setup</a></li> <li><a href="rippled-setup.html">rippled Setup</a></li>
<li><a href="ripple-rest.html">Ripple-REST</a></li>
<li><a href="transactions.html">Transactions</a></li> <li><a href="transactions.html">Transactions</a></li>
<li><a href="ripple-ledger.html">Ledger Format</a></li> <li><a href="ripple-ledger.html">Ledger Format</a></li>
<li><a href="reliable_tx.html">Reliable Transaction Submission</a></li> <li><a href="reliable_tx.html">Reliable Transaction Submission</a></li>

200
gateway_guide.html
View File

@@ -81,7 +81,6 @@
<a href="#" class="dropdown-toggle" data-toggle="dropdown">References <span class="caret"></span></a> <a href="#" class="dropdown-toggle" data-toggle="dropdown">References <span class="caret"></span></a>
<ul class="dropdown-menu" role="menu"> <ul class="dropdown-menu" role="menu">
<li><a href="rippled-apis.html">rippled</a></li> <li><a href="rippled-apis.html">rippled</a></li>
<li><a href="ripple-rest.html">Ripple-REST</a></li>
<li><a href="transactions.html">Transactions</a></li> <li><a href="transactions.html">Transactions</a></li>
<li><a href="ripple-ledger.html">Ledger Format</a></li> <li><a href="ripple-ledger.html">Ledger Format</a></li>
<li><a href="data_api_v2.html">Ripple Data API v2</a></li> <li><a href="data_api_v2.html">Ripple Data API v2</a></li>
@@ -99,7 +98,6 @@
<li class="dropdown"> <li class="dropdown">
<a href="#" class="dropdown-toggle" data-toggle="dropdown">API Tools <span class="caret"></span></a> <a href="#" class="dropdown-toggle" data-toggle="dropdown">API Tools <span class="caret"></span></a>
<ul class="dropdown-menu" role="menu"> <ul class="dropdown-menu" role="menu">
<li><a href="rest-api-tool.html">Ripple-REST API Tool</a></li>
<li><a href="ripple-api-tool.html">WebSocket API Tool</a></li> <li><a href="ripple-api-tool.html">WebSocket API Tool</a></li>
<li><a href="data-api-v2-tool.html">Data API v2 Tool</a></li> <li><a href="data-api-v2-tool.html">Data API v2 Tool</a></li>
</ul> </ul>
@@ -346,20 +344,16 @@
<h3 id="apis-and-middleware">APIs and Middleware</h3> <h3 id="apis-and-middleware">APIs and Middleware</h3>
<p>There are several interfaces you can use to connect to Ripple, depending on your needs and your existing software:</p> <p>There are several interfaces you can use to connect to Ripple, depending on your needs and your existing software:</p>
<ul> <ul>
<li><a href="rippled-apis.html"><code>rippled</code></a> provides JSON-RPC and WebSocket APIs that can be used as a low-level interface to all core Ripple functionality.<ul> <li><a href="rippled-apis.html"><code>rippled</code></a> provides JSON-RPC and WebSocket APIs that can be used as a low-level interface to all core Ripple functionality.</li>
<li>The official client library to rippled, <a href="https://github.com/ripple/ripple-lib">ripple-lib</a> is available for JavaScript, and provides extended convenience features.</li> <li><a href="rippleapi.html">RippleAPI</a> provides a simple API for JavaScript applications.</li>
</ul>
</li>
<li><a href="ripple-rest.html">Ripple-REST</a> provides an easy-to-use RESTful API on top of <code>rippled</code>. In particular, Ripple-REST is designed to be easier to use from statically-typed languages.</li>
</ul> </ul>
<h2 id="tool-security">Tool Security</h2> <h2 id="tool-security">Tool Security</h2>
<p>Any time you submit a Ripple transaction, it must be signed using your secret. However, having your secret means having full control over your account. Therefore, you should never transmit your secret to a server operated by someone else. Instead, use your own server or client application to sign the transactions before sending them out.</p> <p>Any time you submit a Ripple transaction, it must be signed using your secret. However, having your secret means having full control over your account. Therefore, you should never transmit your secret to a server operated by someone else. Instead, use your own server or client application to sign the transactions before sending them out.</p>
<p>The examples in this document show Ripple-REST API methods that include an account secret. This is only safe if you control the Ripple-REST server yourself, <em>and</em> you connect to it over a connection that is secure from outside listeners. (For example, you could connect over a loopback (localhost) network, a private subnet, or an encrypted VPN.) Alternatively, you could operate your own <code>rippled</code> server; or you can use a client application such as <code>ripple-lib</code> to perform local signing before submitting your transactions to a third-party server.</p> <p>The examples in this document show API methods that include an account secret. This is only safe if you control <code>rippled</code> server yourself, <em>and</em> you connect to it over a connection that is secure from outside listeners. (For example, you could connect over a loopback (localhost) network, a private subnet, or an encrypted VPN.) Alternatively, you could use <a href="rippleapi.html">RippleAPI</a> to perform local signing before submitting your transactions to a third-party server.</p>
<h2 id="defaultripple">DefaultRipple</h2> <h2 id="defaultripple">DefaultRipple</h2>
<p>The DefaultRipple flag controls whether the balances held in an account's trust lines are <a href="https://ripple.com/knowledge_center/understanding-the-noripple-flag/">allowed to ripple</a> by default. Rippling is what allows users to trade issuances, so a gateway must allow rippling on all the trust lines connected to its issuing (cold wallet) account.</p> <p>The DefaultRipple flag controls whether the balances held in an account's trust lines are <a href="https://ripple.com/knowledge_center/understanding-the-noripple-flag/">allowed to ripple</a> by default. Rippling is what allows users to trade issuances, so a gateway must allow rippling on all the trust lines connected to its issuing (cold wallet) account.</p>
<p>Before asking users to trust its issuing account, a gateway should enable the DefaultRipple flag on that account. Otherwise, the gateway must individually disable the NoRipple flag for each trust line that other accounts extend to it.</p> <p>Before asking users to trust its issuing account, a gateway should enable the DefaultRipple flag on that account. Otherwise, the gateway must individually disable the NoRipple flag for each trust line that other accounts extend to it.</p>
<p><em>Note:</em> Ripple-REST (as of version 1.4.0) does not yet support retrieving or setting the DefaultRipple flag.</p> <p>The following is an example of using a locally-hosted <code>rippled</code>'s <a href="rippled-apis.html#submit"><code>submit</code> command</a> submitting an AccountSet transaction to enable the DefaultRipple flag:</p>
<p>The following is an example of using a local <a href="ripple-rest.html#update-account-settings"><code>rippled</code> JSON-RPC API</a> to enable the DefaultRipple flag:</p>
<p>Request:</p> <p>Request:</p>
<pre><code>POST http://localhost:8088/ <pre><code>POST http://localhost:8088/
{ {
@@ -409,134 +403,104 @@
<p>We recommend making a user interface to generate a destination tag on-demand when a user intends to send money to the gateway. Then, consider that destination tag valid only for a payment with the expected amount. Later, bounce any other transactions that reuse the same destination tag.</p> <p>We recommend making a user interface to generate a destination tag on-demand when a user intends to send money to the gateway. Then, consider that destination tag valid only for a payment with the expected amount. Later, bounce any other transactions that reuse the same destination tag.</p>
<p>Enable the <a href="#requiredest">RequireDest</a> flag on your hot and cold wallet accounts so that users must use a destination tag to indicate where funds should go when they send Ripple payments to your gateway.</p> <p>Enable the <a href="#requiredest">RequireDest</a> flag on your hot and cold wallet accounts so that users must use a destination tag to indicate where funds should go when they send Ripple payments to your gateway.</p>
<h2 id="disallowxrp">DisallowXRP</h2> <h2 id="disallowxrp">DisallowXRP</h2>
<p>The DisallowXRP flag (<code>disallow_xrp</code> in Ripple-REST) is designed to discourage users from sending XRP to an account by accident. This reduces the costs and effort of bouncing undesired payments, if you operate a gateway that does not trade XRP. The DisallowXRP flag is not strictly enforced, because doing so could allow accounts to become permanently unusable if they run out of XRP. Client applications should honor the DisallowXRP flag, but it is intentionally possible to work around. </p> <p>The DisallowXRP flag is designed to discourage users from sending XRP to an account by accident. This reduces the costs and effort of bouncing undesired payments, if you operate a gateway that does not trade XRP. The DisallowXRP flag is not strictly enforced, because doing so could allow accounts to become permanently unusable if they run out of XRP. Client applications should honor the DisallowXRP flag, but it is intentionally possible to work around. </p>
<p>An issuing gateway that does not trade XRP should enable the DisallowXRP flag on all gateway hot and cold wallets. A private exchange that trades in XRP should only enable the DisallowXRP flag on accounts that are not expected to receive XRP.</p> <p>An issuing gateway that does not trade XRP should enable the DisallowXRP flag on all gateway hot and cold wallets. A private exchange that trades in XRP should only enable the DisallowXRP flag on accounts that are not expected to receive XRP.</p>
<p>The following is an example of a <a href="ripple-rest.html#update-account-settings">Ripple-REST Update Account Settings request</a> to enable the DisallowXRP flag:</p> <p>The following is an example of using a locally-hosted <code>rippled</code>'s <a href="rippled-apis.html#submit"><code>submit</code> command</a> submitting an AccountSet transaction to enable the DisallowXRP flag:</p>
<p>Request:</p> <p>Request:</p>
<pre><code>POST /v1/accounts/rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn/settings?validated=true <pre><code>POST http://localhost:8088/
{ {
"secret": "sn3nxiW7v8KXzPzAqzyHXbSSKNuN9", "method": "submit",
"settings": { "params": [
"disallow_xrp": true {
} "secret": "sn3nxiW7v8KXzPzAqzyHXbSSKNuN9",
"tx_json": {
"Account": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
"Fee": "15000",
"Flags": 0,
"SetFlag": 3,
"TransactionType": "AccountSet"
}
}
]
} }
</code></pre> </code></pre>
<p><em>(<strong>Reminder:</strong> Don't send your secret to a server you do not control.)</em></p> <p><em>(<strong>Reminder:</strong> Don't send your secret to a server you do not control.)</em></p>
<p>Response:</p>
<pre><code>200 OK
{
"success": true,
"settings": {
"hash": "AC0F7D7735CDDC6D859D0EC4E96A571F71F7481750F4C6C975FC8075801A6FB5",
"ledger": "10560577",
"state": "validated",
"require_destination_tag": false,
"require_authorization": false,
"disallow_xrp": true
}
}
</code></pre>
<p>The value <code>"disallow_xrp": true</code> indicates that the DisallowXRP flag is enabled. A successful response shows <code>"state": "validated"</code> when the change has been accepted into a validated Ripple ledger.</p>
<h2 id="requiredest">RequireDest</h2> <h2 id="requiredest">RequireDest</h2>
<p>The <code>RequireDest</code> flag (<code>require_destination_tag</code> in Ripple-REST) is designed to prevent users from sending payments to your account while accidentally forgetting the <a href="#source-and-destination-tags">destination tag</a> that identifies who should be credited for the payment. When enabled, the Ripple Network rejects any payment to your account that does not specify a destination tag.</p> <p>The <code>RequireDest</code> flag (<code>require_destination_tag</code> in Ripple-REST) is designed to prevent users from sending payments to your account while accidentally forgetting the <a href="#source-and-destination-tags">destination tag</a> that identifies who should be credited for the payment. When enabled, the Ripple Network rejects any payment to your account that does not specify a destination tag.</p>
<p>We recommend enabling the RequireDest flag on all gateway hot and cold wallets.</p> <p>We recommend enabling the RequireDest flag on all gateway hot and cold wallets.</p>
<p>The following is an example of a <a href="ripple-rest.html#update-account-settings">Ripple-REST Update Account Settings request</a> to enable the RequireDest flag.</p> <p>The following is an example of using a locally-hosted <code>rippled</code>'s <a href="rippled-apis.html#submit"><code>submit</code> command</a> submitting an AccountSet transaction to enable the RequireDest flag:</p>
<p>Request:</p> <p>Request:</p>
<pre><code>POST /v1/accounts/rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn/settings?validated=true <pre><code>POST http://localhost:8088/
{ {
"secret": "sn3nxiW7v8KXzPzAqzyHXbSSKNuN9", "method": "submit",
"settings": { "params": [
"require_destination_tag": true {
} "secret": "sn3nxiW7v8KXzPzAqzyHXbSSKNuN9",
"tx_json": {
"Account": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
"Fee": "15000",
"Flags": 0,
"SetFlag": 1,
"TransactionType": "AccountSet"
}
}
]
} }
</code></pre> </code></pre>
<p><em>(<strong>Reminder:</strong> Don't send your secret to a server you do not control.)</em></p> <p><em>(<strong>Reminder:</strong> Don't send your secret to a server you do not control.)</em></p>
<p>Response:</p>
<pre><code>200 OK
{
"success": true,
"settings": {
"hash": "F3D2EE87D597BA50EA3A94027583110925E8BAAFE41511F937D65423B18BC2A3",
"ledger": "10560755",
"state": "validated",
"require_destination_tag": true,
"require_authorization": false,
"disallow_xrp": false
}
}
</code></pre>
<p>The value <code>"require_destination_tag": true</code> indicates that the RequireDest flag has been enabled. A successful response shows <code>"state": "validated"</code> when the change has been accepted into a validated Ripple ledger.</p>
<h2 id="requireauth">RequireAuth</h2> <h2 id="requireauth">RequireAuth</h2>
<p>The <code>RequireAuth</code> flag (<code>require_authorization</code> in Ripple-REST) prevents a Ripple account's issuances from being held by other users unless the issuer approves them. </p> <p>The <code>RequireAuth</code> flag (<code>require_authorization</code> in Ripple-REST) prevents a Ripple account's issuances from being held by other users unless the issuer approves them. </p>
<p>We recommend enabling RequireAuth for all hot wallet (and warm wallet) accounts, as a precaution. Separately, the Authorized Accounts feature involves <a href="#with-cold-wallets">setting the RequireAuth flag on your cold wallet</a>.</p> <p>We recommend enabling RequireAuth for all hot wallet (and warm wallet) accounts, as a precaution. Separately, the Authorized Accounts feature involves <a href="#with-cold-wallets">setting the RequireAuth flag on your cold wallet</a>.</p>
<p>You can only enable RequireAuth if the account owns no trust lines and no offers in the Ripple ledger, so you must decide whether or not to use it before you start doing business in the Ripple network.</p> <p>You can only enable RequireAuth if the account owns no trust lines and no offers in the Ripple ledger, so you must decide whether or not to use it before you start doing business in the Ripple network.</p>
<h3 id="with-hot-wallets">With Hot Wallets</h3> <h3 id="with-hot-wallets">With Hot Wallets</h3>
<p>We recommend enabling <code>RequireAuth</code> for all hot wallet accounts, and then never approving any accounts, in order to prevent hot wallets from creating issuances even by accident. This is a purely precuationary measure, and does not impede the ability of those accounts to transfer issuances created by the cold wallet, as they are intended to do.</p> <p>We recommend enabling <code>RequireAuth</code> for all hot wallet accounts, and then never approving any accounts, in order to prevent hot wallets from creating issuances even by accident. This is a purely precuationary measure, and does not impede the ability of those accounts to transfer issuances created by the cold wallet, as they are intended to do.</p>
<p>The following is an example of a <a href="ripple-rest.html#update-account-settings">Ripple-REST Update Account Settings request</a> to enable the RequireDest flag. (This method works the same way regardless of whether the account is used as a hot wallet or cold wallet.)</p> <p>The following is an example of using a locally-hosted <code>rippled</code>'s <a href="rippled-apis.html#submit"><code>submit</code> command</a> submitting an AccountSet transaction to enable the RequireAuth flag: (This method works the same way regardless of whether the account is used as a hot wallet or cold wallet.)</p>
<p>Request:</p> <p>Request:</p>
<pre><code>POST /v1/accounts/rsA2LpzuawewSBQXkiju3YQTMzW13pAAdW/settings?validated=true <pre><code>POST http://localhost:8088/
{ {
"secret": "sn3nxiW7v8KXzPzAqzyHXbSSKNuN9", "method": "submit",
"settings": { "params": [
"require_authorization": true {
} "secret": "sn3nxiW7v8KXzPzAqzyHXbSSKNuN9",
} "tx_json": {
</code></pre> "Account": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
<p><em>(<strong>Reminder:</strong> Don't send your secret to a server you do not control.)</em></p> "Fee": "15000",
<p>Response:</p> "Flags": 0,
<pre><code>{ "SetFlag": 2,
"success": true, "TransactionType": "AccountSet"
"settings": { }
"hash": "687702E0C3952E2227B2F7A0B34933EAADD72A572B234D31360AD83D3F193A78", }
"ledger": "10596929", ]
"state": "validated",
"require_destination_tag": false,
"require_authorization": true,
"disallow_xrp": false
}
} }
</code></pre> </code></pre>
<p><em>(<strong>Reminder:</strong> Don't send your secret to a server you do not control.)</em> </p>
<h3 id="with-cold-wallets">With Cold Wallets</h3> <h3 id="with-cold-wallets">With Cold Wallets</h3>
<p>You may also enable <code>RequireAuth</code> for your cold wallet in order to use the <a href="#authorized-accounts">Authorized Accounts</a> feature. The procedure to enable the RequireAuth flag for a cold wallet is the same as <a href="#with-hot-wallets">with hot wallets</a>.</p> <p>You may also enable <code>RequireAuth</code> for your cold wallet in order to use the <a href="#authorized-accounts">Authorized Accounts</a> feature. The procedure to enable the RequireAuth flag for a cold wallet is the same as <a href="#with-hot-wallets">with hot wallets</a>.</p>
<p>If ACME decides to use Authorized Accounts, ACME creates an interface for users to get their Ripple trust lines authorized by ACME's cold account. After Alice has extended a trust line to ACME from her Ripple account, she goes through the interface on ACME's website to require ACME authorize her trust line. ACME confirms that it has validated Alice's identity information, and then sends a TrustSet transaction to authorize Alice's trust line.</p> <p>If ACME decides to use Authorized Accounts, ACME creates an interface for users to get their Ripple trust lines authorized by ACME's cold account. After Alice has extended a trust line to ACME from her Ripple account, she goes through the interface on ACME's website to require ACME authorize her trust line. ACME confirms that it has validated Alice's identity information, and then sends a TrustSet transaction to authorize Alice's trust line.</p>
<p>The following is an example of using the <a href="ripple-rest.html#grant-trustline">Ripple-REST Grant Trustline method</a> to authorize the (customer) account rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn to hold issuances of USD from the (cold wallet) account rsA2LpzuawewSBQXkiju3YQTMzW13pAAdW:</p> <p>The following is an example of using a locally-hosted <code>rippled</code>'s <a href="rippled-apis.html#submit"><code>submit</code> command</a> to send a TrustSet transaction authorizing the (customer) account rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn to hold issuances of USD from the (cold wallet) account rsA2LpzuawewSBQXkiju3YQTMzW13pAAdW:</p>
<p>Request:</p> <p>Request:</p>
<pre><code>POST /v1/accounts/rsA2LpzuawewSBQXkiju3YQTMzW13pAAdW/trustlines?validated=true <pre><code>POST http://localhost:8088/
{ {
"secret": "sn3nxiW7v8KXzPzAqzyHXbSSKNuN9", "method": "submit",
"trustline": { "params": [
"limit": "0", {
"currency": "USD", "secret": "sn3nxiW7v8KXzPzAqzyHXbSSKNuN9",
"counterparty": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn", "tx_json": {
"authorized": true "Account": "rsA2LpzuawewSBQXkiju3YQTMzW13pAAdW",
} "Fee": "15000",
"TransactionType": "TrustSet",
"LimitAmount": {
"currency": "USD",
"issuer": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
"value": 0
},
"Flags": 65536
}
}
]
} }
</code></pre> </code></pre>
<p><em>(<strong>Reminder:</strong> Don't send your secret to a server you do not control.)</em></p> <p><em>(<strong>Reminder:</strong> Don't send your secret to a server you do not control.)</em> </p>
<p>Response:</p>
<pre><code>201 Created
{
"success": true,
"trustline": {
"account": "rsA2LpzuawewSBQXkiju3YQTMzW13pAAdW",
"limit": "0",
"currency": "USD",
"counterparty": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
"account_allows_rippling": true,
"account_trustline_frozen": false,
"authorized": true
},
"hash": "4509288EE17F01C83FC7D45850EB066A795EE5DBA17BB4DC98DD4023D31EEE5B",
"ledger": "11158585",
"state": "validated"
}
</code></pre>
<p>A successful response shows <code>"state": "validated"</code> when the change has been accepted into a validated Ripple ledger.</p>
<h2 id="robustly-monitoring-for-payments">Robustly Monitoring for Payments</h2> <h2 id="robustly-monitoring-for-payments">Robustly Monitoring for Payments</h2>
<p>In order to robustly monitor incoming payments, gateways should do the following:</p> <p>In order to robustly monitor incoming payments, gateways should do the following:</p>
<ul> <ul>
@@ -656,20 +620,6 @@
} }
</code></pre> </code></pre>
<p><em>(<strong>Reminder:</strong> Don't send your secret to a server you do not control.)</em></p> <p><em>(<strong>Reminder:</strong> Don't send your secret to a server you do not control.)</em></p>
<h2 id="setting-trust-lines-in-ripple-trade">Setting Trust Lines in Ripple Trade</h2>
<p>As part of the <a href="#hot-and-cold-wallets">Hot and Cold Wallets</a> model, each hot or warm wallet must have a trust line to the cold wallet. You can manually set up those trust lines by following these steps in the Ripple Trade client.</p>
<ol>
<li>Log in and go to the <strong>Fund</strong> tab:
<img alt="Fund tab" src="img/connectgateway_01.png"/></li>
<li>Click <strong>Gateways</strong> in the sidebar:
<img alt="Gateways" src="img/connectgateway_02.png"/></li>
<li>Enter the Ripple Name or Ripple Address of the Gateway's <strong>cold wallet</strong>, and click <strong>Save</strong>.
<img alt="Enter gateway's name or address, then save" src="img/connectgateway_03.png"/></li>
<li>Enter the Ripple Trade password, and click <strong>Submit</strong>. (This allows access to send a transaction to the Ripple Network to create the trust line.)
<img alt="Enter password and submit" src="img/connectgateway_04.png"/></li>
<li>When the page shows a green "Gateway connected" box, the transaction to create the trust line has succeeded and the Ripple Network has validated it.
<img alt="Gateway connected" src="img/connectgateway_05.png"/></li>
</ol>
<h2 id="reliable-transaction-submission">Reliable Transaction Submission</h2> <h2 id="reliable-transaction-submission">Reliable Transaction Submission</h2>
<p>The goal of reliably submitting transactions is to achieve the following two properties in a finite amount of time:</p> <p>The goal of reliably submitting transactions is to achieve the following two properties in a finite amount of time:</p>
<ul> <ul>
@@ -679,14 +629,13 @@
<p>In order to achieve this, there are several steps you can take when submitting transactions:</p> <p>In order to achieve this, there are several steps you can take when submitting transactions:</p>
<ul> <ul>
<li>Persist details of the transaction before submitting it.</li> <li>Persist details of the transaction before submitting it.</li>
<li>Use the <code>LastLedgerSequence</code> parameter. (Ripple-REST and ripple-lib do this by default.)</li> <li>Use the <code>LastLedgerSequence</code> parameter. (RippleAPI does this by default.)</li>
<li>Resubmit a transaction if it has not appeared in a validated ledger whose sequence number is less than or equal to the transaction's <code>LastLedgerSequence</code> parameter.</li> <li>Resubmit a transaction if it has not appeared in a validated ledger whose sequence number is less than or equal to the transaction's <code>LastLedgerSequence</code> parameter.</li>
</ul> </ul>
<p>For additional information, consult the <a href="reliable_tx.html">Reliable Transaction Submission</a> guide.</p> <p>For additional information, consult the <a href="reliable_tx.html">Reliable Transaction Submission</a> guide.</p>
<h2 id="rippletxt-and-host-meta">ripple.txt and host-meta</h2> <h2 id="rippletxt">ripple.txt</h2>
<p>The <a href="https://wiki.ripple.com/Ripple.txt">ripple.txt</a> and host-meta standards provide a way to publish information about your gateway so that automated tools and applications can read and understand it.</p> <p>The <a href="https://wiki.ripple.com/Ripple.txt">ripple.txt</a> standard provides a way to publish information about your gateway so that automated tools and applications can read and understand it.</p>
<p>For example, if you run a validating <code>rippled</code> server, you can use ripple.txt to publish the public key of your validating server. You can also publish information about what currencies your gateway issues, and which Ripple account addresses you control, to protect against impostors or confusion.</p> <p>For example, if you run a validating <code>rippled</code> server, you can use ripple.txt to publish the public key of your validating server. You can also publish information about what currencies your gateway issues, and which Ripple account addresses you control, to protect against impostors or confusion.</p>
<p>We recommend implementing one or both of ripple.txt and host-meta. (In the future, we expect ripple.txt to become obsolete, but not yet.)</p>
</div> </div>
</div> </div>
</div> </div>
@@ -705,7 +654,6 @@
<li><a href="freeze.html">Freeze</a></li> <li><a href="freeze.html">Freeze</a></li>
<li><a href="rippled-apis.html">rippled</a></li> <li><a href="rippled-apis.html">rippled</a></li>
<li><a href="rippled-setup.html">rippled Setup</a></li> <li><a href="rippled-setup.html">rippled Setup</a></li>
<li><a href="ripple-rest.html">Ripple-REST</a></li>
<li><a href="transactions.html">Transactions</a></li> <li><a href="transactions.html">Transactions</a></li>
<li><a href="ripple-ledger.html">Ledger Format</a></li> <li><a href="ripple-ledger.html">Ledger Format</a></li>
<li><a href="reliable_tx.html">Reliable Transaction Submission</a></li> <li><a href="reliable_tx.html">Reliable Transaction Submission</a></li>

3
index.html
View File

@@ -73,7 +73,6 @@
<a href="#" class="dropdown-toggle" data-toggle="dropdown">References <span class="caret"></span></a> <a href="#" class="dropdown-toggle" data-toggle="dropdown">References <span class="caret"></span></a>
<ul class="dropdown-menu" role="menu"> <ul class="dropdown-menu" role="menu">
<li><a href="rippled-apis.html">rippled</a></li> <li><a href="rippled-apis.html">rippled</a></li>
<li><a href="ripple-rest.html">Ripple-REST</a></li>
<li><a href="transactions.html">Transactions</a></li> <li><a href="transactions.html">Transactions</a></li>
<li><a href="ripple-ledger.html">Ledger Format</a></li> <li><a href="ripple-ledger.html">Ledger Format</a></li>
<li><a href="data_api_v2.html">Ripple Data API v2</a></li> <li><a href="data_api_v2.html">Ripple Data API v2</a></li>
@@ -91,7 +90,6 @@
<li class="dropdown"> <li class="dropdown">
<a href="#" class="dropdown-toggle" data-toggle="dropdown">API Tools <span class="caret"></span></a> <a href="#" class="dropdown-toggle" data-toggle="dropdown">API Tools <span class="caret"></span></a>
<ul class="dropdown-menu" role="menu"> <ul class="dropdown-menu" role="menu">
<li><a href="rest-api-tool.html">Ripple-REST API Tool</a></li>
<li><a href="ripple-api-tool.html">WebSocket API Tool</a></li> <li><a href="ripple-api-tool.html">WebSocket API Tool</a></li>
<li><a href="data-api-v2-tool.html">Data API v2 Tool</a></li> <li><a href="data-api-v2-tool.html">Data API v2 Tool</a></li>
</ul> </ul>
@@ -240,7 +238,6 @@
<li><a href="freeze.html">Freeze</a></li> <li><a href="freeze.html">Freeze</a></li>
<li><a href="rippled-apis.html">rippled</a></li> <li><a href="rippled-apis.html">rippled</a></li>
<li><a href="rippled-setup.html">rippled Setup</a></li> <li><a href="rippled-setup.html">rippled Setup</a></li>
<li><a href="ripple-rest.html">Ripple-REST</a></li>
<li><a href="transactions.html">Transactions</a></li> <li><a href="transactions.html">Transactions</a></li>
<li><a href="ripple-ledger.html">Ledger Format</a></li> <li><a href="ripple-ledger.html">Ledger Format</a></li>
<li><a href="reliable_tx.html">Reliable Transaction Submission</a></li> <li><a href="reliable_tx.html">Reliable Transaction Submission</a></li>

357
js/apitool-methods-ripplerest.js
View File

@@ -1,357 +0,0 @@
//---------- List of requests ------------------------//
// Must be loaded after apitool-rest.js //
var URL_BASE = "https://api.ripple.com:443";
var DOC_BASE = "ripple-rest.html";
var DEFAULT_ADDRESS_1 = "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn";
var DEFAULT_ADDRESS_2 = "ra5nK24KXen9AHvsdFTKHSANinZseWnPcX";
var DEFAULT_ADDRESS_3 = "rJnZ4YHCUsHvQu7R6mZohevKJDHFzVD6Zr";
var DEFAULT_HASH = "9D591B18EDDD34F0B6CF4223A2940AEA2C3CC778925BABF289E0011CD8FA056E";
var DEFAULT_SECRET = "sn3nxiW7v8KXzPzAqzyHXbSSKNuN9";
Request('ACCOUNTS');
Request('Generate Wallet', {
method: GET,
path: "/v1/wallet/new",
description: 'Randomly generate keys for a potential new Ripple account.',
link: '#generate-wallet'
});
Request('Get Account Balances', {
method: GET,
path: '/v1/accounts/{:address}/balances?{:query_params}',
description: 'Retrieve the current balances for the given Ripple account.',
link: '#get-account-balances',
params: {
"{:address}": DEFAULT_ADDRESS_1,
"{:query_params}": "currency=USD"
}
});
Request('Get Account Settings', {
method: GET,
path: '/v1/accounts/{:address}/settings',
description: 'Retrieve the current settings for the given Ripple account.',
link: '#get-account-settings',
params: {
"{:address}": DEFAULT_ADDRESS_1
}
});
Request('Update Account Settings', {
method: POST,
path: '/v1/accounts/{:address}/settings?{:query_params}',
description: 'Change the current settings for the given Ripple account.',
link: '#update-account-settings',
test_only: true,
params: {
"{:address}": DEFAULT_ADDRESS_1,
"{:query_params}": "validated=true"
},
body: {
secret: DEFAULT_SECRET,
settings: {
require_destination_tag: false,
require_authorization: false,
disallow_xrp: false,
disable_master: false,
email_hash: "98b4375e1d753e5b91627516f6d70977"
}
}
});
Request("PAYMENTS");
Request('Prepare Payment', {
method: GET,
path: '/v1/accounts/{:source_address}/payments/paths/{:destination_address}/{:amount}?{:query_params}',
description: 'Retrieve possible payment objects for a desired payment.',
link: '#prepare-payment',
params: {
"{:source_address}": DEFAULT_ADDRESS_1,
"{:destination_address}": DEFAULT_ADDRESS_2,
"{:amount}": "1+USD+rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
"{:query_params}": "source_currencies=USD"
}
});
Request('Submit Payment', {
method: POST,
path: '/v1/accounts/{:source_address}/payments?{:query_params}',
description: 'Send a prepared payment to the network.',
link: '#submit-payment',
test_only: true,
body: {
"secret": DEFAULT_SECRET,
"client_resource_id": "348170b9-16b9-4927-854d-7f9d4a2a692d",
"payment": {
"source_account": DEFAULT_ADDRESS_1,
"source_tag": "",
"source_amount": {
"value": "1",
"currency": "USD",
"issuer": ""
},
"source_slippage": "0",
"destination_account": DEFAULT_ADDRESS_2,
"destination_tag": "",
"destination_amount": {
"value": "1",
"currency": "USD",
"issuer": DEFAULT_ADDRESS_1
},
"invoice_id": "",
"paths": "[]",
"partial_payment": false,
"no_direct_ripple": false
}
},
params: {
"{:source_address}": DEFAULT_ADDRESS_1,
"{:query_params}": "validated=true"
}
});
Request("Confirm Payment", {
method: GET,
path: "/v1/accounts/{:address}/payments/{:id}",
description: "Retrieve details of a payment and its status.",
link: "#confirm-payment",
params: {
"{:address}": DEFAULT_ADDRESS_1,
"{:id}": DEFAULT_HASH
}
});
Request("Get Payment History", {
method: GET,
path: "/v1/accounts/{:address}/payments?{:query_params}",
description: "Browse through the history of payments sent and received by an account.",
link: "#get-payment-history",
params: {
"{:address}": DEFAULT_ADDRESS_1,
"{:query_params}": "direction=incoming&exclude_failed=true"
}
});
Request("ORDERS");
Request("Place Order", {
method: POST,
path: "/v1/accounts/{:address}/orders?{:query_params}",
description: "Place an order on the ripple network.",
link: "#place-order",
test_only: true,
params: {
"{:address}": DEFAULT_ADDRESS_1,
"{:query_params}": "validated=true"
},
body: {
"secret": DEFAULT_SECRET,
"order": {
"type": "sell",
"taker_pays": {
"currency": "JPY",
"value": "4000",
"counterparty": "rMAz5ZnK73nyNUL4foAvaxdreczCkG3vA6"
},
"taker_gets": {
"currency": "USD",
"value": ".25",
"counterparty": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B"
},
"immediate_or_cancel": true
}
}
});
Request("Cancel Order", {
method: DELETE,
path: "/v1/accounts/{:address}/orders/{:order}/?{:query_params}",
description: "Cancel an order on the ripple network.",
link: "#cancel-order",
test_only: true,
params: {
"{:address}": DEFAULT_ADDRESS_1,
"{:query_params}": "validated=true",
"{:order}": "23"
},
body: {
"secret": DEFAULT_SECRET
}
});
Request("Get Account Orders", {
method: GET,
path: "/v1/accounts/{:address}/orders?{:query_params}",
description: "Get open currency-exchange orders associated with the Ripple address.",
link: "#get-account-orders",
params: {
"{:address}": DEFAULT_ADDRESS_3,
"{:query_params}": "ledger=10399192&limit=15"
}
});
Request("Get Order Transaction", {
method: GET,
path: "/v1/accounts/{:address}/orders/{:hash}",
description: "Get the details of an order transaction.",
link: "#get-order-transaction",
params: {
"{:address}": "rEQWVz1qN4DWw5J17s3DgXQzUuVYDSpK6M",
"{:hash}": "D53A3B99AC0C3CAF35D72178390ACA94CD42479A98CEA438EEAFF338E5FEB76D"
}
});
Request("Get Order Book", {
method: GET,
path: "/v1/accounts/{:address}/order_book/{:base}/{:counter}?{:query_params}",
description: "Get the order book for a currency pair",
link: "#get-order-book",
params: {
"{:address}": DEFAULT_ADDRESS_3,
"{:base}": "BTC+rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B",
"{:counter}": "USD+rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B",
"{:query_params}": "limit=10"
}
});
Request("TRUST LINES");
Request("Get Trustlines", {
method: GET,
path: "/v1/accounts/{:address}/trustlines?{:query_params}",
description: "Check the status of one or more trustlines attached to an account.",
link: "#get-trustlines",
params: {
"{:address}": DEFAULT_ADDRESS_1,
"{:query_params}": "currency=USD&counterparty=ra5nK24KXen9AHvsdFTKHSANinZseWnPcX"
}
});
Request("Grant Trustline", {
method: POST,
path: "/v1/accounts/{:address}/trustlines?{:query_params}",
description: "Add or modify a trustline from this account.",
link: "#grant-trustline",
test_only: true,
params: {
"{:address}": DEFAULT_ADDRESS_1,
"{:query_params}": "validated=true"
},
body: {
"secret": DEFAULT_SECRET,
"trustline": {
"limit": "110",
"currency": "USD",
"counterparty": "rMwjYedjc7qqtKYVLiAccJSmCwih4LnE2q",
"account_allows_rippling": false,
"account_trustline_frozen": false
}
}
});
Request("NOTIFICATIONS");
Request("Check Notifications", {
method: GET,
path: "/v1/accounts/{:address}/notifications/{:id}",
description: "Monitor an account for all kinds of transactions.",
link: "#check-notifications",
params: {
"{:address}": DEFAULT_ADDRESS_1,
"{:id}": DEFAULT_HASH
}
});
Request("RIPPLED SERVER STATUS");
Request("Check Connection", {
method: GET,
path: "/v1/server/connected",
description: "Check whether the REST server is connected to a rippled server.",
link: "#check-connection"
});
Request("Get Server Status", {
method: GET,
path: "/v1/server",
description: "Retrieve information about the current status of the Ripple-REST server and the rippled server it is connected to.",
link: "#get-server-status"
});
Request("UTILITIES");
Request("Sign Transaction", {
method: POST,
path: "/v1/transaction/sign",
description: "Sign a Ripple transaction in preparation for submission",
link: "#sign-transaction",
body: {
"secret": DEFAULT_SECRET,
"tx_json": {
"Flags": 0,
"TransactionType": "AccountSet",
"Account": DEFAULT_ADDRESS_1,
"Domain": "726970706C652E636F6D",
"LastLedgerSequence": 8820052,
"Fee": "12",
"Sequence": 2938
}
}
});
Request("Submit Transaction", {
method: POST,
path: "/v1/transaction/submit",
description: "Submit a signed transaction to the Ripple network",
link: "#submit-transaction",
body: {
"tx_blob": "12000322000000002400000B7A201B0086961168400000000000000C732102F89EAEC7667B30F33D0687BBA86C3FE2A08CCA40A9186C5BDE2DAA6FA97A37D87446304402207660BDEF67105CE1EBA9AD35DC7156BAB43FF1D47633199EE257D70B6B9AAFBF0220723E54B026DF8C6FF19DC7CBEB6AB458C7D367B2BE42827E91CBA934143F2729770A726970706C652E636F6D81144FBFF73DA4ECF9B701940F27341FA8020C313443"
}
});
Request("Retrieve Ripple Transaction", {
method: GET,
path: "/v1/transactions/{:id}",
description: "Retrieve a raw Ripple transaction",
link: "#retrieve-ripple-transaction",
params: {
"{:id}": DEFAULT_HASH
}
});
Request("Retrieve Transaction Fee", {
method: GET,
path: "/v1/transaction-fee",
description: "Retrieve the current transaction fee for the connected rippled server(s).",
link: "#retrieve-transaction-fee",
});
Request("Generate UUID", {
method: GET,
path: "/v1/uuid",
description: "Create a universally-unique identifier (UUID) to use as the client resource ID for a payment.",
link: "#create-client-resource-id"
});
//helper to fill the default payment with a new UUID
function get_uuid(callback) {
$.get(URL_BASE + "/v1/uuid").done(callback);
}
$(document).ready(function(){
get_uuid(function(resp,status,xhr) {
requests["submit-payment"].body.client_resource_id = resp.uuid;
if (window.location.hash == "#submit-payment") {
//we might have already loaded the call by the time the AJAX
// completes, so refresh the default body.
// Debatably a bad idea, because if the AJAX takes so long that the
// user has already started editing the call, it'll reset it.
select_request("submit-payment");
}
});
});
//---------- End req. List ---------------------------//

3
paths.html
View File

@@ -81,7 +81,6 @@
<a href="#" class="dropdown-toggle" data-toggle="dropdown">References <span class="caret"></span></a> <a href="#" class="dropdown-toggle" data-toggle="dropdown">References <span class="caret"></span></a>
<ul class="dropdown-menu" role="menu"> <ul class="dropdown-menu" role="menu">
<li><a href="rippled-apis.html">rippled</a></li> <li><a href="rippled-apis.html">rippled</a></li>
<li><a href="ripple-rest.html">Ripple-REST</a></li>
<li><a href="transactions.html">Transactions</a></li> <li><a href="transactions.html">Transactions</a></li>
<li><a href="ripple-ledger.html">Ledger Format</a></li> <li><a href="ripple-ledger.html">Ledger Format</a></li>
<li><a href="data_api_v2.html">Ripple Data API v2</a></li> <li><a href="data_api_v2.html">Ripple Data API v2</a></li>
@@ -99,7 +98,6 @@
<li class="dropdown"> <li class="dropdown">
<a href="#" class="dropdown-toggle" data-toggle="dropdown">API Tools <span class="caret"></span></a> <a href="#" class="dropdown-toggle" data-toggle="dropdown">API Tools <span class="caret"></span></a>
<ul class="dropdown-menu" role="menu"> <ul class="dropdown-menu" role="menu">
<li><a href="rest-api-tool.html">Ripple-REST API Tool</a></li>
<li><a href="ripple-api-tool.html">WebSocket API Tool</a></li> <li><a href="ripple-api-tool.html">WebSocket API Tool</a></li>
<li><a href="data-api-v2-tool.html">Data API v2 Tool</a></li> <li><a href="data-api-v2-tool.html">Data API v2 Tool</a></li>
</ul> </ul>
@@ -262,7 +260,6 @@
<li><a href="freeze.html">Freeze</a></li> <li><a href="freeze.html">Freeze</a></li>
<li><a href="rippled-apis.html">rippled</a></li> <li><a href="rippled-apis.html">rippled</a></li>
<li><a href="rippled-setup.html">rippled Setup</a></li> <li><a href="rippled-setup.html">rippled Setup</a></li>
<li><a href="ripple-rest.html">Ripple-REST</a></li>
<li><a href="transactions.html">Transactions</a></li> <li><a href="transactions.html">Transactions</a></li>
<li><a href="ripple-ledger.html">Ledger Format</a></li> <li><a href="ripple-ledger.html">Ledger Format</a></li>
<li><a href="reliable_tx.html">Reliable Transaction Submission</a></li> <li><a href="reliable_tx.html">Reliable Transaction Submission</a></li>

515
reliable_tx.html
View File

@@ -81,7 +81,6 @@
<a href="#" class="dropdown-toggle" data-toggle="dropdown">References <span class="caret"></span></a> <a href="#" class="dropdown-toggle" data-toggle="dropdown">References <span class="caret"></span></a>
<ul class="dropdown-menu" role="menu"> <ul class="dropdown-menu" role="menu">
<li><a href="rippled-apis.html">rippled</a></li> <li><a href="rippled-apis.html">rippled</a></li>
<li><a href="ripple-rest.html">Ripple-REST</a></li>
<li><a href="transactions.html">Transactions</a></li> <li><a href="transactions.html">Transactions</a></li>
<li><a href="ripple-ledger.html">Ledger Format</a></li> <li><a href="ripple-ledger.html">Ledger Format</a></li>
<li><a href="data_api_v2.html">Ripple Data API v2</a></li> <li><a href="data_api_v2.html">Ripple Data API v2</a></li>
@@ -99,7 +98,6 @@
<li class="dropdown"> <li class="dropdown">
<a href="#" class="dropdown-toggle" data-toggle="dropdown">API Tools <span class="caret"></span></a> <a href="#" class="dropdown-toggle" data-toggle="dropdown">API Tools <span class="caret"></span></a>
<ul class="dropdown-menu" role="menu"> <ul class="dropdown-menu" role="menu">
<li><a href="rest-api-tool.html">Ripple-REST API Tool</a></li>
<li><a href="ripple-api-tool.html">WebSocket API Tool</a></li> <li><a href="ripple-api-tool.html">WebSocket API Tool</a></li>
<li><a href="data-api-v2-tool.html">Data API v2 Tool</a></li> <li><a href="data-api-v2-tool.html">Data API v2 Tool</a></li>
</ul> </ul>
@@ -136,7 +134,7 @@
</div> </div>
<div class='content'> <div class='content'>
<h1 id="reliable-transaction-submission">Reliable Transaction Submission</h1> <h1 id="reliable-transaction-submission">Reliable Transaction Submission</h1>
<p>Gateways and back-end applications should use the best practices described here to ensure that transactions are validated or rejected in a verifiable and timely fashion. Transactions should be submitted to trusted (locally operated) rippled servers.</p> <p>Gateways and back-end applications should use the best practices described here to ensure that transactions are validated or rejected in a verifiable and timely fashion. You should submit transactions to trusted (locally operated) <code>rippled</code> servers.</p>
<p>The best practices detailed in this document allow applications to submit transactions to the Ripple network while achieving:</p> <p>The best practices detailed in this document allow applications to submit transactions to the Ripple network while achieving:</p>
<ol> <ol>
<li><a href="https://en.wikipedia.org/wiki/Idempotence">Idempotency</a> - Transactions will be processed once and only once, or not at all.</li> <li><a href="https://en.wikipedia.org/wiki/Idempotence">Idempotency</a> - Transactions will be processed once and only once, or not at all.</li>
@@ -150,28 +148,31 @@
</ol> </ol>
<p>These types of errors can potentially lead to serious problems. For example, an application that fails to find a prior successful payment transaction might erroneously submit another transaction, duplicating the original payment. This underscores the importance that applications base their actions on authoritive transaction results, using the techniques described in this document.</p> <p>These types of errors can potentially lead to serious problems. For example, an application that fails to find a prior successful payment transaction might erroneously submit another transaction, duplicating the original payment. This underscores the importance that applications base their actions on authoritive transaction results, using the techniques described in this document.</p>
<h2 id="background">Background</h2> <h2 id="background">Background</h2>
<p>The Ripple protocol provides a ledger shared across all nodes in the network. Through a process of consensus and validation, the network agrees on order in which transactions are applied to (or omitted from) the ledger. <!--See Ripple Ledger Consensus and Validation[b] for an overview of this process.--></p> <p>The Ripple protocol provides a ledger shared across all nodes in the network. Through a process of consensus and validation, the network agrees on order in which transactions are applied to (or omitted from) the ledger.</p>
<p>Well-formed transactions submitted to trusted Ripple network nodes are usually validated or rejected in a matter of seconds. There are cases, however, in which a well-formed transaction is neither validated nor rejected this quickly. One specific case can occur if the global <a href="tx-cost.html">transaction cost</a> increases after an application sends a transaction. If the transaction cost increases above what has been specified in the transaction, the transaction will not be included in the next validated ledger. If at some later date the global transaction cost decreases, the transaction may become viable again. If the transaction does not include expiration, there is no limit to how much later this can occur.</p> <p>Well-formed transactions submitted to trusted Ripple network nodes are usually validated or rejected in a matter of seconds. There are cases, however, in which a well-formed transaction is neither validated nor rejected this quickly. One specific case can occur if the global <a href="tx-cost.html">transaction cost</a> increases after an application sends a transaction. If the transaction cost increases above what has been specified in the transaction, the transaction will not be included in the next validated ledger. If at some later date the global transaction cost decreases, the transaction may become viable again. If the transaction does not include expiration, there is no limit to how much later this can occur.</p>
<p>Applications face additional challenges, in the event of power or network loss, ascertaining the status of submitted transactions. Applications must take care both to properly submit a transaction and later to properly ascertain its authoritative results.</p> <p>Applications face additional challenges, in the event of power or network loss, ascertaining the status of submitted transactions. Applications must take care both to properly submit a transaction and later to properly ascertain its authoritative results.</p>
<h3 id="transaction-timeline">Transaction Timeline</h3> <h3 id="transaction-timeline">Transaction Timeline</h3>
<p>Ripple provides several APIs for submitting transactions (<a href="rippled-apis.html">rippled</a>, ripple-lib, <a href="ripple-rest.html">Ripple-REST</a>). Regardless of the API used, the transaction is applied to the ledger as follows.</p> <p>Ripple provides several APIs for submitting transactions, including <a href="rippled-apis.html"><code>rippled</code></a>, and <a href="rippleapi.html">RippleAPI</a>. Regardless of the API used, the transaction is applied to the ledger as follows.</p>
<ol> <ol>
<li>A transaction is created and signed by account owner.</li> <li>An account owner creates and signs a transaction.</li>
<li>That transaction is submitted to the network as a candidate transaction.</li> <li>The owner submits the transaction to the network as a candidate transaction.</li>
<li>Malformed or nonsensical transactions are rejected immediately.</li> <li>Malformed or nonsensical transactions are rejected immediately.</li>
<li>Well formed transactions may provisionally succeed, then later fail.</li> <li>Well-formed transactions may provisionally succeed, then later fail.</li>
<li>Well formed transactions may provisionally fail, then later succeed.</li> <li>Well-formed transactions may provisionally fail, then later succeed.</li>
<li>Through consensus and validation, the transaction is applied to the ledger. Even some failed transactions are applied in order to enforce a cost for being propagated through the network.</li> <li>Well-formed transactions may provisionally succeed, and then later succeed in a slightly different way. (For example, by consuming a different offer and achieving a better or worse exchange rate than the provisional execution.)</li>
<li>Through consensus and validation, the transaction is applied to the ledger. Even some failed transactions are applied, in order to enforce a cost for being propagated through the network.</li>
<li>The validated ledger includes the transaction, and its effects are reflected in the ledger state.</li> <li>The validated ledger includes the transaction, and its effects are reflected in the ledger state.</li>
<li>Transaction results are no longer provisional, success or failure is now final and immutable.</li> <li>Transaction results are no longer provisional, success or failure is now final and immutable.</li>
</ol> </ol>
<p><em>Note:</em> When submitting a transaction via rippled or ripple-lib, a successful status code returned from a submit command indicates the rippled server has received the candidate transaction, and does not indicate the transaction will be finally applied to the ledger.</p> <p><em>Note:</em> When submitting a transaction via <code>rippled</code>, a successful status code returned from a submit command indicates the <code>rippled</code> server has received the candidate transaction, and does not indicate the transaction will be finally applied to the ledger.</p>
<p>Ripple APIs may return provisional results based on candidate transactions. Applications must not confuse these with the final, <em>immutable</em>, results of a transaction. Immutable results are found only in validated ledgers. Applications may need to query the status of a transaction repeatedly, until the ledger containing the transaction results is validated.</p> <p>APIs may return provisional results based on the result of applying candidate transactions to the current, in-progress ledger. Applications must not confuse these with the final, <em>immutable</em>, results of a transaction. Immutable results are found only in validated ledgers. Applications may need to query the status of a transaction repeatedly, until the ledger containing the transaction results is validated.</p>
<p>While applying transactions, Ripple network nodes work with the <em>last validated ledger</em>, a snapshot of the ledger state based on transactions the entire network has validated. The process of consensus and validation apply a set of new transactions to the last validated ledger, resulting in a new validated ledger. This new validated ledger instance and the ones that preceded it comprise the ledger history. Each of these validated ledger instances has a sequence number, which is one greater than the sequence number of the preceding instance.</p> <p>While applying transactions, <code>rippled</code> servers use the <em>last validated ledger</em>, a snapshot of the ledger state based on transactions the entire network has validated. The process of consensus and validation apply a set of new transactions to the last validated ledger in canonical order, resulting in a new validated ledger. This new validated ledger instance and the ones that preceded it comprise the ledger history.</p>
<p>Each validated ledger instances has a sequence number, which is one greater than the sequence number of the preceding instance. Each ledger also has an identifying hash value, which is uniquely determined from its contents. There may be many different versions of in-progress ledgers, which have the same sequence number, but different hash values. Only one version can ever be validated.</p>
<p>Each validated ledger has a canonical order in which transactions apply. This order is deterministic based on the final transaction set of the ledger. In contrast, each <code>rippled</code> server's in-progress ledger is calculated incrementally, as transactions are received. The order in which transactions execute provisionally is usually not the same as the order in which transactions execute to build a new validated ledger. This is one reason why the provisional outcome of a transaction may be different than the final result. For example, a payment may achieve a different final exchange rate depending on whether it executes before or after another payment that would consume the same offer.</p>
<h3 id="lastledgersequence">LastLedgerSequence</h3> <h3 id="lastledgersequence">LastLedgerSequence</h3>
<p><a href="transactions.html#lastledgersequence"><code>LastLedgerSequence</code></a> is an optional parameter of all transactions. This instructs the Ripple network that a transaction must be validated on or before a specific ledger instance. The transaction will never be included in a ledger instance with a higher sequence number.</p> <p><a href="transactions.html#lastledgersequence"><code>LastLedgerSequence</code></a> is an optional parameter of all transactions. This instructs the Ripple Consensus Ledger that a transaction must be validated on or before a specific ledger instance. The Ripple Consensus Ledger never includes a transaction in a ledger instance whose sequence number is higher than the transaction's <code>LastLedgerSequence</code> parameter.</p>
<p>Use the <code>LastLedgerSequence</code> parameter to prevent undesirable cases where a transaction is not promptly validated yet could become viable at some point in the future. Gateways and other back-end applications should specify the <code>LastLedgerSequence</code> parameter on every transaction. Automated processes should use a value of 4 greater than the sequence number of the last validated ledger[1] to ensure that a transaction is validated or rejected in a predictable and timely fashion.</p> <p>Use the <code>LastLedgerSequence</code> parameter to prevent undesirable cases where a transaction is not promptly validated yet could become viable at some point in the future. Gateways and other back-end applications should specify the <code>LastLedgerSequence</code> parameter on every transaction. Automated processes should use a value of 4 greater than the sequence number of the last validated ledger[1] to ensure that a transaction is validated or rejected in a predictable and timely fashion.</p>
<p>Applications using rippled APIs should explicitly specify a <code>LastLedgerSequence</code> when submitting transactions. When using ripple-lib or Ripple-REST, a <code>LastLedgerSequence</code> is automatically included. Applications using those APIs are recommended to use the <code>LastLedgerSequence</code> calculated by the API.</p> <p>Applications using rippled APIs should explicitly specify a <code>LastLedgerSequence</code> when submitting transactions. RippleAPI uses the <code>maxLedgerVersion</code> field of <a href="rippleapi.html#transaction-instructions">Transaction Instructions</a> to specify the <code>LastLedgerSequence</code>. RippleAPI automatically provides an appropriate value by default. You can specify <code>maxLedgerVersion</code> as <code>null</code> to intentionally omit <code>LastLedgerSequence</code>, in case you want a transaction that can be executed after an unlimited amount of time.</p>
<h2 id="best-practices">Best Practices</h2> <h2 id="best-practices">Best Practices</h2>
<h3 id="reliable-transactions-submission">Reliable Transactions Submission</h3> <h3 id="reliable-transactions-submission">Reliable Transactions Submission</h3>
<p>Applications submitting transactions should employ the following practices in order to submit reliably even in the event that a process dies or other failure occurs. Application transaction results must be verified so that applications can act on the final, validated results.</p> <p>Applications submitting transactions should employ the following practices in order to submit reliably even in the event that a process dies or other failure occurs. Application transaction results must be verified so that applications can act on the final, validated results.</p>
@@ -217,28 +218,38 @@
</code></pre> </code></pre>
<h2 id="technical-application">Technical Application</h2> <h2 id="technical-application">Technical Application</h2>
<p>In order to implement the transaction submission and verification best practices, applications need to perform the following actions.</p> <p>In order to implement the transaction submission and verification best practices, applications need to perform the following actions.</p>
<ul> <ol>
<li>Determine the signing account's next sequence number</li> <li>Determine the signing account's next sequence number<ul>
<li>Each transaction has an account-specific sequence number. This guarantees the order in which transactions signed by an account are executed and makes it safe to resubmit a transaction without danger of the transaction being applied to the ledger more than once.</li> <li>Each transaction has an account-specific sequence number. This guarantees the order in which transactions signed by an account are executed and makes it safe to resubmit a transaction without danger of the transaction being applied to the ledger more than once.</li>
<li>Decide on a <code>LastLedgerSequence</code></li> </ul>
</li>
<li>Decide on a <code>LastLedgerSequence</code><ul>
<li>A transaction's <code>LastLedgerSequence</code> is calculated from the last validated ledger sequence number.</li> <li>A transaction's <code>LastLedgerSequence</code> is calculated from the last validated ledger sequence number.</li>
<li>Construct and sign the transaction</li> </ul>
<li>The details of a signed transaction are persisted before submission.</li> </li>
<li>Submit the transaction</li> <li>Construct and sign the transaction<ul>
<li>Persist the details of a signed transaction before submission.</li>
</ul>
</li>
<li>Submit the transaction<ul>
<li>Initial results are provisional and subject to change.</li> <li>Initial results are provisional and subject to change.</li>
<li>Determine the final result of a transaction</li> </ul>
</li>
<li>Determine the final result of a transaction<ul>
<li>Final results are an immutable part of the ledger history.</li> <li>Final results are an immutable part of the ledger history.</li>
</ul> </ul>
<p>An application's means of performing these actions depends on the ripple API the application uses. These interfaces may be any of:</p> </li>
</ol>
<p>An application's means of performing these actions depends on the API the application uses. These interfaces may be any of:</p>
<ol> <ol>
<li><a href="rippled-apis.html">rippled</a></li> <li><a href="rippled-apis.html"><code>rippled</code>'s internal APIs</a></li>
<li><a href="ripple-rest.html">ripple-rest</a></li> <li><a href="rippleapi.html">RippleAPI</a></li>
<li><a href="https://github.com/ripple/ripple-lib/">ripple-lib</a></li> <li>Any number of other software APIs layered on top of <code>rippled</code></li>
</ol> </ol>
<h3 id="rippled-submitting-and-verifying-transactions">rippled - Submitting and Verifying Transactions</h3> <h3 id="rippled-submitting-and-verifying-transactions">rippled - Submitting and Verifying Transactions</h3>
<h4 id="determine-the-account-sequence">Determine the Account Sequence</h4> <h4 id="determine-the-account-sequence">Determine the Account Sequence</h4>
<p>rippled provides the <a href="rippled-apis.html#account-info">account_info</a> method to learn an account's sequence number in the last validated ledger.</p> <p><code>rippled</code> provides the <a href="rippled-apis.html#account-info">account_info</a> method to learn an account's sequence number in the last validated ledger.</p>
<p>Request:</p> <p>JSON-RPC Request:</p>
<pre><code>{ <pre><code>{
"method": "account_info", "method": "account_info",
"params": [ "params": [
@@ -249,7 +260,7 @@
] ]
} }
</code></pre> </code></pre>
<p>Response:</p> <p>Response body:</p>
<pre><code>{ <pre><code>{
"result": { "result": {
"validated": true, "validated": true,
@@ -270,7 +281,7 @@
} }
</code></pre> </code></pre>
<p>In this example, the account's sequence is <strong>4</strong> (note <code>"Sequence": 4</code>, in <code>"account_data"</code>) as of the last validated ledger (note <code>"ledger": "validated"</code> in the request, and <code>"validated": "true"</code> in the response).</p> <p>In this example, the account's sequence is <strong>4</strong> (note <code>"Sequence": 4</code>, in <code>"account_data"</code>) as of the last validated ledger (note <code>"ledger": "validated"</code> in the request, and <code>"validated": "true"</code> in the response).</p>
<p>If an application were to submit three transactions signed by this account, they would use sequence numbers 4, 5, and 6. An application should keep a running account sequence number in order to submit multiple transactions without waiting for validation of each one.</p> <p>If an application were to submit three transactions signed by this account, they would use sequence numbers 4, 5, and 6. In order to submit multiple transactions without waiting for validation of each, an application should keep a running account sequence number.</p>
<h4 id="determine-the-last-validated-ledger">Determine the Last Validated Ledger</h4> <h4 id="determine-the-last-validated-ledger">Determine the Last Validated Ledger</h4>
<p><code>rippled</code> provides the <a href="rippled-apis.html#server-state">server_state</a> command which returns the ledger sequence number of the last validated ledger.</p> <p><code>rippled</code> provides the <a href="rippled-apis.html#server-state">server_state</a> command which returns the ledger sequence number of the last validated ledger.</p>
<p>Request:</p> <p>Request:</p>
@@ -313,7 +324,7 @@
</code></pre> </code></pre>
<p>In this example the last validated ledger sequence number is 10268596 (found under <code>result.state.validated_ledger</code> in the response). Note also this example indicates a gap in ledger history. The server used here would not be able to provide information about the transactions applied during that gap (ledgers 10256383 through 10256411). If configured to do so, the server will eventually retrieve that portion of the ledger history.</p> <p>In this example the last validated ledger sequence number is 10268596 (found under <code>result.state.validated_ledger</code> in the response). Note also this example indicates a gap in ledger history. The server used here would not be able to provide information about the transactions applied during that gap (ledgers 10256383 through 10256411). If configured to do so, the server will eventually retrieve that portion of the ledger history.</p>
<h4 id="construct-the-transaction">Construct the Transaction</h4> <h4 id="construct-the-transaction">Construct the Transaction</h4>
<p><code>rippled</code> provides the <a href="rippled-apis.html#sign">RPC sign</a> to prepare a transaction for submission. This method requires an account secret, which should only be passed to trusted rippled instances. This example issues 10 FOO (a made-up currency) from a gateway to another ripple account.</p> <p><code>rippled</code> provides the <a href="rippled-apis.html#sign">sign method</a> to prepare a transaction for submission. This method requires an account secret, which should only be passed to trusted <code>rippled</code> instances. This example issues 10 FOO (a made-up currency) from a gateway to another Ripple account.</p>
<p>Request:</p> <p>Request:</p>
<pre><code>{ <pre><code>{
"method": "sign", "method": "sign",
@@ -367,7 +378,7 @@
</code></pre> </code></pre>
<p>Applications should persist the transaction's hash before submitting. The result of the <code>sign</code> method includes the hash under <code>tx_json</code>.</p> <p>Applications should persist the transaction's hash before submitting. The result of the <code>sign</code> method includes the hash under <code>tx_json</code>.</p>
<h4 id="submit-the-transaction">Submit the transaction</h4> <h4 id="submit-the-transaction">Submit the transaction</h4>
<p><code>rippled</code> provides the <a href="rippled-apis.html#submit"><code>submit</code> method</a>, allowing us to submit the signed transaction. The <code>tx_blob</code> parameter was returned from the <code>sign</code> method.</p> <p><code>rippled</code> provides the <a href="rippled-apis.html#submit"><code>submit</code> method</a>, allowing us to submit the signed transaction. This uses the <code>tx_blob</code> parameter that was returned by the <code>sign</code> method.</p>
<p>Request:</p> <p>Request:</p>
<pre><code>{ <pre><code>{
"method": "submit", "method": "submit",
@@ -500,446 +511,9 @@
} }
} }
</code></pre> </code></pre>
<p>Our example transaction specified <code>LastLedgerSequence</code> 10268600, based on the last validated ledger at the time, plus four. So to determine whether our missing transaction has permanently failed, our rippled server must have ledgers 10268597 through 10268600. If the server has those validated ledgers in its history, <strong>and</strong> <code>tx</code> returns <code>txnNotFound</code>, then the transaction has failed and will never be included in any ledger. in this case, application logic may dictate building and submitting a replacement transaction with the same account sequence and updated <code>LastLedgerSequence</code>.</p> <p>Our example transaction specified <code>LastLedgerSequence</code> 10268600, based on the last validated ledger at the time, plus four. So to determine whether our missing transaction has permanently failed, our <code>rippled</code> server must have ledgers 10268597 through 10268600. If the server has those validated ledgers in its history, <strong>and</strong> <code>tx</code> returns <code>txnNotFound</code>, then the transaction has failed and will never be included in any ledger. In this case, application logic may dictate building and submitting a replacement transaction with the same account sequence and updated <code>LastLedgerSequence</code>.</p>
<p>The server state may indicate a last validated ledger sequence number less than the specified <code>LastLedgerSequence</code>. If so, the <code>txnNotFound</code> indicates either (a) the submitted transaction failed to be distributed to the network, or (b) the transaction has been distributed to the network but has not yet been processed. To handle the former case, applications may submit again the same signed transaction. Because the transaction has a unique account sequence number, it will be processed at most once.</p> <p>The server state may indicate a last validated ledger sequence number less than the specified <code>LastLedgerSequence</code>. If so, the <code>txnNotFound</code> indicates either (a) the submitted transaction failed to be distributed to the network, or (b) the transaction has been distributed to the network but has not yet been processed. To handle the former case, applications may submit again the same signed transaction. Because the transaction has a unique account sequence number, it will be processed at most once.</p>
<p>Finally the server state might indicate one or more gaps in the transaction history. The <code>completed_ledgers</code> field shown in the response above indicates that ledgers 10256383 through 10256411 are missing from this rippled instance. Our example transaction can only appear in ledgers 10268597 - 10268600 (based on when it was submitted and <code>LastLedgerSequence</code>), so the gap shown here is not relevant. However, if the gap indicated a ledger in that range was missing, then an application would need to query another rippled server (or wait for this one to retrieve the missing ledgers) in order to determine that a <code>txnNotFound</code> result is immutable.</p> <p>Finally the server state might indicate one or more gaps in the transaction history. The <code>completed_ledgers</code> field shown in the response above indicates that ledgers 10256383 through 10256411 are missing from this rippled instance. Our example transaction can only appear in ledgers 10268597 - 10268600 (based on when it was submitted and <code>LastLedgerSequence</code>), so the gap shown here is not relevant. However, if the gap indicated a ledger in that range was missing, then an application would need to query another rippled server (or wait for this one to retrieve the missing ledgers) in order to determine that a <code>txnNotFound</code> result is immutable.</p>
<h3 id="ripple-rest-submitting-and-verifying-payments">Ripple-REST - Submitting and Verifying Payments</h3>
<p>The <a href="ripple-rest.html">Ripple-REST API</a> provides an interface to Ripple via a <a href="https://en.wikipedia.org/wiki/Representational_state_transfer">RESTful API</a>. It provides robust payment submission features, which include referencing payments by client provided identifiers, re-submitting payments in response to some errors, and automatically calculating transaction parameters such as account sequence, <code>LastLedgerSequence</code>, and transaction cost.</p>
<p>This examples that follow refer to Ripple-REST API for <em>payments</em>. The REST methods for setting trust lines and modifying account settings does not follow the same pattern. See <a href="https://ripplelabs.atlassian.net/browse/RLJS-126">RLJS-126</a> for additional details.</p>
<h4 id="construct-the-transaction-1">Construct the Transaction</h4>
<p>In Ripple-REST, a GET request retrieves the path options for a payment. The following example issues 10 FOO (a made-up currency) from one account to another.</p>
<pre><code>GET /v1/accounts/rG5Ro9e3uGEZVCh3zu5gB9ydKUskCs221W/payments/paths/rawz2WQ8i9FdTHp4KSNpBdyxgFqNpKe8fM/10+FOO+rG5Ro9e3uGEZVCh3zu5gB9ydKUskCs221W
</code></pre>
<p>The response (below) indicates one payment path exists. (The <code>payments[0].paths</code> is present, and empty, when issuing currency directly.)</p>
<pre><code>{
"payments": [
{
"no_direct_ripple": false,
"partial_payment": false,
"paths": "[]",
"invoice_id": "",
"destination_amount": {
"issuer": "rG5Ro9e3uGEZVCh3zu5gB9ydKUskCs221W",
"currency": "FOO",
"value": "10"
},
"destination_tag": "",
"destination_account": "rawz2WQ8i9FdTHp4KSNpBdyxgFqNpKe8fM",
"source_slippage": "0",
"source_amount": {
"issuer": "rG5Ro9e3uGEZVCh3zu5gB9ydKUskCs221W",
"currency": "FOO",
"value": "10"
},
"source_tag": "",
"source_account": "rG5Ro9e3uGEZVCh3zu5gB9ydKUskCs221W"
}
],
"success": true
}
</code></pre>
<h4 id="submit-the-payment-transaction">Submit the Payment Transaction</h4>
<p>Applications should persist a record of a transaction before submitting it, in order to recover from a catastrophic failure such as a power outage. Ripple-REST accepts a <code>client_resource_id</code> which allows an application to look up a transaction. For this example, let's say the application saves the details of the transaction to its payments table with ID 42, so the application creates <code>client_resource_id</code> "payment-42".</p>
<p>Before submitting, applications should persist the <code>client_resource_id</code>, transaction type, and source account.</p>
<p>Request:</p>
<pre><code>POST /v1/accounts/:usGate/payments
Content-Type: application/json
{
"secret": "sssssssssssssssssssssss",
"client_resource_id": "payment-42",
"max_fee": ".1",
"payment": {
"no_direct_ripple": false,
"partial_payment": false,
"paths": "[]",
"invoice_id": "",
"destination_amount": {
"issuer": "rG5Ro9e3uGEZVCh3zu5gB9ydKUskCs221W",
"currency": "FOO",
"value": "10"
},
"destination_tag": "",
"destination_account": "rawz2WQ8i9FdTHp4KSNpBdyxgFqNpKe8fM",
"source_slippage": "0",
"source_amount": {
"issuer": "rG5Ro9e3uGEZVCh3zu5gB9ydKUskCs221W",
"currency": "FOO",
"value": "10"
},
"source_tag": "",
"source_account": "rG5Ro9e3uGEZVCh3zu5gB9ydKUskCs221W"
}
}
</code></pre>
<p><strong><em>Note: only submit your account secret to a trusted Ripple-REST server.</em></strong></p>
<p>Response:</p>
<pre><code>{
success: true,
client_resource_id: 'payment-42',
status_url: 'http://127.0.0.1:5990/v1/accounts/rG5Ro9e3uGEZVCh3zu5gB9ydKUskCs221W/payments/payment-42' }
</code></pre>
<p>The payment result remains provisional at this point. Ripple-REST returns a <code>status_url</code> where we can eventually learn the final result of the transaction. The <code>status_url</code> is based on the <code>client_resource_id</code> persisted by the application before submission, so the application can construct the <code>status_url</code> even in the event of a power failure before this response is received.</p>
<h4 id="verify-the-payment-transaction">Verify the Payment Transaction</h4>
<p>A GET request to the transaction's <code>status_url</code> retrieves the result.</p>
<p>Request:</p>
<pre><code>GET /v1/accounts/rG5Ro9e3uGEZVCh3zu5gB9ydKUskCs221W/payments/payment-42
</code></pre>
<p>Response:</p>
<pre><code>{
"payment": {
"destination_balance_changes": [
{
"issuer": "rG5Ro9e3uGEZVCh3zu5gB9ydKUskCs221W",
"currency": "FOO",
"value": "10"
}
],
"source_balance_changes": [
{
"issuer": "",
"currency": "XRP",
"value": "-0.012"
},
{
"issuer": "rG5Ro9e3uGEZVCh3zu5gB9ydKUskCs221W",
"currency": "FOO",
"value": "-10"
}
],
"fee": "0.012",
"timestamp": "2014-12-02T23:10:10.000Z",
"hash": "DDF9F6E4DC64A1CB056570170FC06B2CBC2701CB500E44AC730BF8C868F6AA15",
"ledger": "10286112",
"result": "tesSUCCESS",
"state": "validated",
"direction": "outgoing",
"partial_payment": false,
"no_direct_ripple": false,
"paths": "[]",
"invoice_id": "",
"destination_amount": {
"value": "10",
"issuer": "rG5Ro9e3uGEZVCh3zu5gB9ydKUskCs221W",
"currency": "FOO"
},
"destination_tag": "",
"destination_account": "rawz2WQ8i9FdTHp4KSNpBdyxgFqNpKe8fM",
"source_slippage": "0",
"source_amount": {
"value": "10",
"issuer": "rG5Ro9e3uGEZVCh3zu5gB9ydKUskCs221W",
"currency": "FOO"
},
"source_tag": "",
"source_account": "rG5Ro9e3uGEZVCh3zu5gB9ydKUskCs221W"
},
"success": true
}
</code></pre>
<p>In this example, <code>payment.state: "validated"</code> indicates the transaction is in a validated ledger. Therefore the results are final and immutable. Any other value for <code>payment.state</code> indicates provisional results, an application must check again later to determine final results.</p>
<p>In the preceeding example, <code>payment.result: "tesSUCCESS"</code> (along with the <code>"validated"</code> state) indicates the payment has been delivered. Any other result code indicates the transaction did not succeed, and application logic may dictate constructing and submitting a new transaction to perform the desired operation.</p>
<h4 id="verify-missing-or-failed-payment-transaction">Verify Missing or Failed Payment Transaction</h4>
<p>When a GET request to the transaction's <code>status_url</code> returns an error, an application must determine whether the final result of a transaction is failure.</p>
<p>Request:</p>
<pre><code>GET /v1/accounts/rG5Ro9e3uGEZVCh3zu5gB9ydKUskCs221W/payments/payment-42
</code></pre>
<p>Response:</p>
<pre><code>{
"message": "Transaction not found.",
"error": "txnNotFound",
"error_type": "transaction",
"success": false
}
</code></pre>
<p><em>Note:</em> The <code>txnNotFound</code> error shown above is the current behavior of ripple-REST, but will change in order to make it easier to determine the status of transactions in this case. Follow <a href="https://ripplelabs.atlassian.net/browse/RLJS-163">RLJS-163</a> for updates regarding this behavior.</p>
<p>The <code>txnNotFound</code> error in this example indicates the transaction was received by Ripple-REST, but has failed to appear in a validated ledger. This could be caused certain transaction errors, or possibly because Ripple-REST lost power or network before submitting the transaction to the network. Application logic may dictate constructing and submitting a replacement transaction.</p>
<p>Another error response:</p>
<pre><code>{
"message": "A transaction hash was not supplied and there were no entries matching the client_resource_id.",
"error": "Transaction not found",
"error_type": "invalid_request",
"success": false
}
</code></pre>
<p>This <code>"Transaction not found"</code> error indicates the transaction was not received by Ripple-REST, and therefore never sent to the network. Again, application logic may dictate constructing and submitting a replacement transaction.</p>
<h3 id="ripple-lib-submitting-and-verifying-transactions">ripple-lib - Submitting and Verifying Transactions</h3>
<p><a href="https://github.com/ripple/ripple-lib">ripple-lib</a> provides a Javascript API for Ripple in Node.js and web browsers. It provides features for robust transaction submission which including automatically calculating account sequence numbers and <code>LastLedgerSequence</code>.</p>
<h4 id="construct-the-transaction-2">Construct the Transaction</h4>
<p>ripple-lib provides a high level API for creating transactions. In this example, a payment:</p>
<pre><code>var tx = remote.createTransaction('Payment', {
account: ‘rG5Ro9e3uGEZVCh3zu5gB9ydKUskCs221W',
destination: ‘rawz2WQ8i9FdTHp4KSNpBdyxgFqNpKe8fM',
amount: ‘10/FOO/rG5Ro9e3uGEZVCh3zu5gB9ydKUskCs221W'
});
</code></pre>
<p>Note that ripple-lib will automatically provide additional details before the transaction is signed and submitted. These details include an account transaction Sequence, <code>LastLedgerSequence</code> and transaction cost.</p>
<p>Before submitting, applications should persist the transaction details, so that status may be verified in the event of a failure. Applications have an opportunity to do this by implementing <a href="https://github.com/ripple/ripple-lib/blob/61afca2337927a4f331ae02770ccdad5d9bdef17/docs/REFERENCE.md#transaction-events">transaction event handlers</a>. The <code>presubmit</code> event handler is appropriate for saving data before a transaction is submitted to the network. During normal operation, a <code>state</code> event is emitted whenever the transaction status changes, including final validation.</p>
<p>The example implementation (below) of a these event handlers simply logs some information about the transaction, in order to show some of the data available to applications. Live applications should implement handlers to <strong>synchronously</strong> persist transactions details, and should throw an error if unable to save the data.</p>
<pre><code>// The 'presubmit' handler receives events before the transaction
// is submitted to the network; also before re-submit attempts.
tx.on('presubmit', function(data) {
console.log('- Presubmit Event Handler -');
// Log information about the transaction.
console.log(this.summary());
// Applications should persist transaction data syncronously,
// before returning from this event handler.
});
// The 'state' handler receives events after any state change, including...
tx.on('state', function(state) {
console.log('- State Event Hander: ' + state + ' -');
// Log information about the transaction.
console.log(this.summary());
// Applications should persist updated transaction state.
});
</code></pre>
<h4 id="submit-the-transaction-1">Submit the Transaction</h4>
<p>ripple-lib provides <code>Transaction.submit()</code> to both sign and submit a transaction. In order to sign, an application must first call <code>Remote.setSecret(&lt;account&gt;, &lt;secret&gt;)</code>. Take care to configure ripple-lib to use local signing, as secrets should only be shared with trusted ripple servers.</p>
<pre><code>tx.submit(function(err, res) {
if (err) {
console.log('- Transaction Submit Callback Error -');
console.log(err);
}
else {
console.log('- Transaction Submit Callback -');
console.log(util.inspect(res));
}
});
</code></pre>
<p>ripple-lib emits events as it processes the transaction. The presubmit event allows application to persist the transaction hash and other details before it is sent to the network.</p>
<pre><code>- Presubmit Event Handler -
{ tx_json:
{ Flags: 2147483648,
TransactionType: 'Payment',
Account: 'rG5Ro9e3uGEZVCh3zu5gB9ydKUskCs221W',
Amount:
{ value: '10',
currency: 'FOO',
issuer: 'rG5Ro9e3uGEZVCh3zu5gB9ydKUskCs221W' },
Destination: 'rawz2WQ8i9FdTHp4KSNpBdyxgFqNpKe8fM',
Fee: '10000',
Sequence: 11,
SigningPubKey: '0267268EE0DDDEE6A862C9FF9DDAF898CF17060A673AF771B565AA2F4AE24E3FC5',
LastLedgerSequence: 10320276,
TxnSignature: '3045022100A61FA3AF1569BC4B1D2161F0055CF9760F8AC473ED374A98FE7E77099B8C63AD02200FF2A59CE4722FC246652125D3A13928392E7D0C5AC073314A573E93BF594856' },
clientID: undefined,
submittedIDs: [ '2120732F77002A9138DE110408EA06C2064F032BC9D44A28C46267C607594203' ],
submissionAttempts: 0,
submitIndex: 10320268,
initialSubmitIndex: 10320268,
lastLedgerSequence: 10320276,
state: 'unsubmitted',
server: undefined,
finalized: false }
</code></pre>
<p>Note in the preceeding example log output, <code>tx.state: 'unsubmitted'</code> indicates the transaction is not yet sent to the network. <code>tx.submittedIDs</code> includes the transaction hash, a unique identifier that applications should persist in order to later verify the status of the transaction. ripple-lib has automatically calculated <code>tx.tx_json.Sequence</code> and <code>tx.tx_json.LastLedgerSequence</code>.</p>
<p>ripple-lib will re-submit a transaction in response to certain errors. Prior to each submission the <code>presubmit</code> event provides up-to-date information about the transaction, which applications should persist.</p>
<pre><code>- Presubmit Event Handler -
{ tx_json:
{ Flags: 2147483648,
TransactionType: 'Payment',
Account: 'rG5Ro9e3uGEZVCh3zu5gB9ydKUskCs221W',
Amount:
{ value: '10',
currency: 'FOO',
issuer: 'rG5Ro9e3uGEZVCh3zu5gB9ydKUskCs221W' },
Destination: 'rawz2WQ8i9FdTHp4KSNpBdyxgFqNpKe8fM',
Fee: '10000',
Sequence: 11,
SigningPubKey: '0267268EE0DDDEE6A862C9FF9DDAF898CF17060A673AF771B565AA2F4AE24E3FC5',
LastLedgerSequence: 10320278,
TxnSignature: '3045022100D5AC197A9EB35E86B70B4A02C19EC0120C1D6A539B1FE58C364322067E040AE102205EFE429FF40FAFAAAC58B653DCD25642D8A50E222C2D244105F43CEBAAC7DC89' },
clientID: undefined,
submittedIDs:
[ 'AD070F312DE0EB8AB64DDA0C512A4A1E9ED1ACE0AEFBBE6AA1418A2D6F137D13',
'2120732F77002A9138DE110408EA06C2064F032BC9D44A28C46267C607594203' ],
submissionAttempts: 1,
submitIndex: 10320270,
initialSubmitIndex: 10320268,
lastLedgerSequence: 10320278,
state: 'submitted',
server: undefined,
finalized: false,
result:
{ engine_result: 'telINSUF_FEE_P',
engine_result_message: 'Fee insufficient.',
ledger_hash: undefined,
ledger_index: undefined,
transaction_hash: '2120732F77002A9138DE110408EA06C2064F032BC9D44A28C46267C607594203' } }
</code></pre>
<p>The example above shows the transaction after 1 failed attempts, before a second attempt is submitted. Note that <code>tx.submittedIDs[0]</code> is the updated hash which applications should persist.</p>
<p>The <code>tx.result</code> is the <strong>provisional</strong> result of the <strong>prior</strong> submission attempt. In this example the initial submit failed with <code>telINSUF_FEE_P</code>, which could happen if the network adjusts the transaction cost calculated by ripple-lib immediately before the transaction is processed.</p>
<h4 id="verify-the-transaction-1">Verify the Transaction</h4>
<p>During normal operation, events emitted by ripple-lib inform an application of the result of a transaction. The <code>state</code> event will emit with <code>tx.state: 'pending'</code> with a provisional result; and finally if successful with <code>tx.state: 'validated'</code> and <code>tx.finalized: true</code>.</p>
<pre><code>- State Event Hander: validated -
{ tx_json:
{ Flags: 2147483648,
TransactionType: 'Payment',
Account: 'rG5Ro9e3uGEZVCh3zu5gB9ydKUskCs221W',
Amount:
{ value: '10',
currency: 'FOO',
issuer: 'rG5Ro9e3uGEZVCh3zu5gB9ydKUskCs221W' },
Destination: 'rawz2WQ8i9FdTHp4KSNpBdyxgFqNpKe8fM',
Sequence: 11,
SigningPubKey: '0267268EE0DDDEE6A862C9FF9DDAF898CF17060A673AF771B565AA2F4AE24E3FC5',
Fee: '12000',
LastLedgerSequence: 10320625,
TxnSignature: '3045022100DEFA085B88834F3C27200714AB40F3A67E7E86E726DE630A2955843F6D53010D02202592D709D5F90F9E852CEFB0D5A7F6D39AC0A99BC97A3589BF9FA47018C2CB2C' },
clientID: undefined,
submittedIDs: [ '0E066642EC28DA3C9840202AF4F3CD281A5A2733F2D9BEF38C69DFDC14407E12' ],
submissionAttempts: 1,
submitIndex: 10320617,
initialSubmitIndex: 10320617,
lastLedgerSequence: 10320625,
state: 'validated',
server: undefined,
finalized: true,
result:
{ engine_result: 'tesSUCCESS',
engine_result_message: 'The transaction was applied.',
ledger_hash: '7F936E0F37611982A434B76270C819FDA8240649D7592BDC995FC9AEE2D436AA',
ledger_index: 10320618,
transaction_hash: '0E066642EC28DA3C9840202AF4F3CD281A5A2733F2D9BEF38C69DFDC14407E12' } }
</code></pre>
<p>If the final state of a transaction is an error, the state event indicates <code>tx.state: 'failed'</code> and <code>tx.finalized: 'true'</code>:</p>
<pre><code>- State Event Hander: failed -
{ tx_json:
{ Flags: 2147483648,
TransactionType: 'Payment',
Account: 'rG5Ro9e3uGEZVCh3zu5gB9ydKUskCs221W',
Amount:
{ value: '10',
currency: 'FOO',
issuer: 'rG5Ro9e3uGEZVCh3zu5gB9ydKUskCs221W' },
Destination: 'rawz2WQ8i9FdTHp4KSNpBdyxgFqNpKe8fM',
Fee: '10000',
Sequence: 11,
SigningPubKey: '0267268EE0DDDEE6A862C9FF9DDAF898CF17060A673AF771B565AA2F4AE24E3FC5',
LastLedgerSequence: 10320296,
TxnSignature: '304402201E3D376CF7C1C99EAC19027EA3EDE15F24D8FA59D4EA90067A09267F8D927ABB0220084B8BFF7D9308CD00A5DA265776DC9BAB9F553A9E6A4ED1A75DD76DCB3B40A9' },
clientID: undefined,
submittedIDs:
[ '895DA495779D51F84E4B79258AAF9A8E51404A79747DD936EE6468FE9A974AEE',
'F14AE631317D11184DEC7066814539E9BB50AB46DF770E3F2367430810C0AE7C',
'80F7460AD3F8172F9CDD69B638E4EA7ED9466A4D495EF8530FE98B8A0909E897',
'23F59C223701D73C2477963E4D1FA3460DAD5A64D813FB9591AF45C4C68A339B',
'B929D9018E842A56FFCA8EB295EDA81C62AE37804F759A19E0B1292C888C8586',
'EC9B4D869B8B9C27F644859F203D54023B01F6C2E9FA12CD34AC8373F9BA67A5',
'47FD42A6604D74A89E006352FBC656843A270EF46B47A3EB1D1098A31A01BC3D',
'BD3D13C57A5FDBB9B1F88C287EC158AA92BF9B75078273678F3124C84F504ABA',
'0B2CC389D5553FB232E4EF45EC67D149B8CD65E17C4BE7A41B5142A0D4A935BD',
'AD070F312DE0EB8AB64DDA0C512A4A1E9ED1ACE0AEFBBE6AA1418A2D6F137D13',
'2120732F77002A9138DE110408EA06C2064F032BC9D44A28C46267C607594203' ],
submissionAttempts: 11,
submitIndex: 10320288,
initialSubmitIndex: 10320268,
lastLedgerSequence: 10320296,
state: 'failed',
server: undefined,
finalized: true,
result:
{ engine_result: 'telINSUF_FEE_P',
engine_result_message: 'Fee insufficient.',
ledger_hash: undefined,
ledger_index: undefined,
transaction_hash: '895DA495779D51F84E4B79258AAF9A8E51404A79747DD936EE6468FE9A974AEE' } }
</code></pre>
<p>In the event of a power or network failure, an application may be interrupted before these <code>state</code> events are emitted. In these cases, applications should retrieve the status of a transaction by its <code>hash</code>, one of the details persisted during an earlier <code>presubmit</code> event.</p>
<pre><code>var hash = 'C3306CA3ED1B372EAC8A84A84B52752A4E4912BB1A26AB883E969BC987E4D20E';
remote.requestTransaction(hash, function(err, result) {
if (err) {
console.log(err);
}
else {
console.log(result);
}
});
</code></pre>
<p>Result of <code>remote.requestTransaction(&lt;transaction hash&gt;)</code>:</p>
<pre><code>{ Account: 'rG5Ro9e3uGEZVCh3zu5gB9ydKUskCs221W',
Amount:
{ currency: 'FOO',
issuer: 'rG5Ro9e3uGEZVCh3zu5gB9ydKUskCs221W',
value: '10' },
Destination: 'rawz2WQ8i9FdTHp4KSNpBdyxgFqNpKe8fM',
Fee: '10000',
Flags: 2147483648,
LastLedgerSequence: 10303055,
Sequence: 10,
SigningPubKey: '0267268EE0DDDEE6A862C9FF9DDAF898CF17060A673AF771B565AA2F4AE24E3FC5',
TransactionType: 'Payment',
TxnSignature: '304402200C65A9FD9EA7000DCD87688BA92C219074858D530E9A75F32EF2DA1A9C07844E02203A72B2688412CF855306E70D9B9ED541B67BEA8A8EDB90D47B7B227B295CED9B',
date: 470953270,
hash: 'C3306CA3ED1B372EAC8A84A84B52752A4E4912BB1A26AB883E969BC987E4D20E',
inLedger: 10303048,
ledger_index: 10303048,
meta:
{ AffectedNodes: [ [Object], [Object] ],
TransactionIndex: 23,
TransactionResult: 'tesSUCCESS' },
validated: true }
</code></pre>
<p>Note the response from <code>requestTransaction</code> includes <strong><code>validated: true</code></strong>, indicating the result is in a validated ledger and is final. Without <code>validated: true</code>, results are <em>provisional</em> and may change. This example shows <code>meta.TransactionResult: 'tesSUCCESS'</code>, indicating the transaction was successful.</p>
<h4 id="verify-missing-transaction-1">Verify Missing Transaction</h4>
<p><code>Remote.requestTransaction</code> may return <code>txNotFound</code>:</p>
<pre><code>{ [RippleError: Remote reported an error.]
error: 'remoteError',
error_message: 'Remote reported an error.',
remote:
{ error: 'txnNotFound',
error_code: 24,
error_message: 'Transaction not found.',
id: 1,
request:
{ command: 'tx',
id: 1,
transaction: 'F85D840B152328A1A6C11910A6FBF57E1340B6285E3602A1258B7A41EC814119' },
status: 'error',
type: 'response' },
result: 'remoteError',
engine_result: 'remoteError',
result_message: 'Remote reported an error.',
engine_result_message: 'Remote reported an error.',
message: 'Remote reported an error.' }
</code></pre>
<p>In these cases an application must distinguish between a provisional result and a final result. For this, an application needs the transaction's <code>initialSubmitIndex</code> and <code>LastLedgerSequence</code>. This information was persisted earlier by the application's <code>presubmit</code> event handler. In this example, <code>initialSubmitIndex</code> is 10301323 and <code>LastLedgerSequence</code> is 10301337.</p>
<p>A call to <code>Remote.requestServerInfo()</code> determines whether the server has final, immutable results about the transaction.</p>
<pre><code>remote.requestServerInfo(function(err, result) {
if (err) {
console.log(err);
}
else {
console.log(result);
}
});
</code></pre>
<p>Result of <code>remote.requestServerInfo()</code>:</p>
<pre><code>{ info:
{ build_version: '0.26.4-sp3-private',
complete_ledgers: '32570-10302948',
hostid: 'KNOW',
io_latency_ms: 1,
last_close: { converge_time_s: 2.001, proposers: 5 },
load_factor: 1000,
peers: 44,
pubkey_node: 'n9MADAXTbCnaBYoUcvDzHkTqoTSjVd8VHgJE2KwMBbwRV4pM3j2a',
server_state: 'full',
validated_ledger:
{ age: 4,
base_fee_xrp: 0.00001,
hash: '47EE6EC414FC0B648869CE7108143D916DE38DAC167DADEF541F9A8CED475909',
reserve_base_xrp: 20,
reserve_inc_xrp: 5,
seq: 10302948 },
validation_quorum: 3 } }
</code></pre>
<p>In this example, <code>info.complete_ledgers</code> indicates the server has continuous ledger history up to ledger sequence 10302948. This history includes the span of ledger where the transaction may appear, from 10301323 to 10301337. Therefore, the <code>txNotFound</code> result is final, and the transaction has failed immutably.</p>
<p>If the ledger history were not complete through the <code>LastLedgerSequence</code>, the application must wait for that ledger to become validated, or the server to sync a more complete history with the network.</p>
<h2 id="additional-resources">Additional Resources</h2> <h2 id="additional-resources">Additional Resources</h2>
<ul> <ul>
<li><a href="transactions.html">Transaction Format</a></li> <li><a href="transactions.html">Transaction Format</a></li>
@@ -966,7 +540,6 @@ remote.requestTransaction(hash, function(err, result) {
<li><a href="freeze.html">Freeze</a></li> <li><a href="freeze.html">Freeze</a></li>
<li><a href="rippled-apis.html">rippled</a></li> <li><a href="rippled-apis.html">rippled</a></li>
<li><a href="rippled-setup.html">rippled Setup</a></li> <li><a href="rippled-setup.html">rippled Setup</a></li>
<li><a href="ripple-rest.html">Ripple-REST</a></li>
<li><a href="transactions.html">Transactions</a></li> <li><a href="transactions.html">Transactions</a></li>
<li><a href="ripple-ledger.html">Ledger Format</a></li> <li><a href="ripple-ledger.html">Ledger Format</a></li>
<li><a href="reliable_tx.html">Reliable Transaction Submission</a></li> <li><a href="reliable_tx.html">Reliable Transaction Submission</a></li>

3
reserves.html
View File

@@ -81,7 +81,6 @@
<a href="#" class="dropdown-toggle" data-toggle="dropdown">References <span class="caret"></span></a> <a href="#" class="dropdown-toggle" data-toggle="dropdown">References <span class="caret"></span></a>
<ul class="dropdown-menu" role="menu"> <ul class="dropdown-menu" role="menu">
<li><a href="rippled-apis.html">rippled</a></li> <li><a href="rippled-apis.html">rippled</a></li>
<li><a href="ripple-rest.html">Ripple-REST</a></li>
<li><a href="transactions.html">Transactions</a></li> <li><a href="transactions.html">Transactions</a></li>
<li><a href="ripple-ledger.html">Ledger Format</a></li> <li><a href="ripple-ledger.html">Ledger Format</a></li>
<li><a href="data_api_v2.html">Ripple Data API v2</a></li> <li><a href="data_api_v2.html">Ripple Data API v2</a></li>
@@ -99,7 +98,6 @@
<li class="dropdown"> <li class="dropdown">
<a href="#" class="dropdown-toggle" data-toggle="dropdown">API Tools <span class="caret"></span></a> <a href="#" class="dropdown-toggle" data-toggle="dropdown">API Tools <span class="caret"></span></a>
<ul class="dropdown-menu" role="menu"> <ul class="dropdown-menu" role="menu">
<li><a href="rest-api-tool.html">Ripple-REST API Tool</a></li>
<li><a href="ripple-api-tool.html">WebSocket API Tool</a></li> <li><a href="ripple-api-tool.html">WebSocket API Tool</a></li>
<li><a href="data-api-v2-tool.html">Data API v2 Tool</a></li> <li><a href="data-api-v2-tool.html">Data API v2 Tool</a></li>
</ul> </ul>
@@ -178,7 +176,6 @@
<li><a href="freeze.html">Freeze</a></li> <li><a href="freeze.html">Freeze</a></li>
<li><a href="rippled-apis.html">rippled</a></li> <li><a href="rippled-apis.html">rippled</a></li>
<li><a href="rippled-setup.html">rippled Setup</a></li> <li><a href="rippled-setup.html">rippled Setup</a></li>
<li><a href="ripple-rest.html">Ripple-REST</a></li>
<li><a href="transactions.html">Transactions</a></li> <li><a href="transactions.html">Transactions</a></li>
<li><a href="ripple-ledger.html">Ledger Format</a></li> <li><a href="ripple-ledger.html">Ledger Format</a></li>
<li><a href="reliable_tx.html">Reliable Transaction Submission</a></li> <li><a href="reliable_tx.html">Reliable Transaction Submission</a></li>

217
rest-api-tool.html
View File

@@ -1,217 +0,0 @@
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
<meta name="viewport" content="width=device-width">
<title>Ripple-REST API Tool - Ripple Developer Portal</title>
<!-- favicon -->
<link rel="icon" href="favicon.ico" type="image/x-icon">
<link rel="shortcut icon" href="favicon.ico" type="image/x-icon">
<!-- jQuery -->
<script src="vendor/jquery-1.11.1.min.js"></script>
<!-- Bootstrap -->
<link href="css/bootstrap.min.css" rel="stylesheet">
<script src="js/bootstrap.min.js"></script>
<!-- Custom Stylesheets -->
<link href="font/fonts.css" rel="stylesheet" type="text/css" />
<link href="css/main.css" rel="stylesheet" />
<link href="css/custom.css" rel="stylesheet" />
<link rel="shortcut icon" href="favicon.ico?v=2" type="image/x-icon" />
<link rel="icon" href="favicon.ico?v=2" type="image/x-icon" />
</head>
<body >
<div class="navbar navbar-inverse navbar-fixed-top" role="navigation">
<div class="container">
<div class="navbar-header">
<button type="button" class="navbar-toggle" data-toggle="collapse" data-target=".navbar-collapse">
<span class="sr-only">Toggle navigation</span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
</button>
<a class="navbar-brand" href="./"><img class="small_logo" src="assets/img/ripple_logo_small.png"></a>
</div>
<div class="navbar-collapse collapse">
<ul class="nav navbar-nav">
<li class="dropdown">
<a href="#" class="dropdown-toggle" data-toggle="dropdown">Concepts <span class="caret"></span></a>
<ul class="dropdown-menu" role="menu">
<li><a href="paths.html">Paths</a></li>
<li><a href="fees.html">Fees (Disambiguation)</a></li>
<li><a href="transfer_fees.html">Transfer Fees</a></li>
<li><a href="tx-cost.html">Transaction Cost</a></li>
<li><a href="fee-voting.html">Fee Voting</a></li>
<li><a href="reserves.html">Reserves</a></li>
<li><a href="freeze.html">Freeze</a></li>
</ul>
</li>
<li class="dropdown">
<a href="#" class="dropdown-toggle" data-toggle="dropdown">References <span class="caret"></span></a>
<ul class="dropdown-menu" role="menu">
<li><a href="rippled-apis.html">rippled</a></li>
<li><a href="ripple-rest.html">Ripple-REST</a></li>
<li><a href="transactions.html">Transactions</a></li>
<li><a href="ripple-ledger.html">Ledger Format</a></li>
<li><a href="data_api_v2.html">Ripple Data API v2</a></li>
<li><a href="rippleapi.html">RippleAPI</a></li>
</ul>
</li>
<li class="dropdown">
<a href="#" class="dropdown-toggle" data-toggle="dropdown">Tutorials <span class="caret"></span></a>
<ul class="dropdown-menu" role="menu">
<li><a href="rippled-setup.html">rippled Setup</a></li>
<li><a href="reliable_tx.html">Reliable Transaction Submission</a></li>
<li><a href="gateway_guide.html">Gateway Guide</a></li>
</ul>
</li>
<li class="dropdown">
<a href="#" class="dropdown-toggle" data-toggle="dropdown">API Tools <span class="caret"></span></a>
<ul class="dropdown-menu" role="menu">
<li><a href="rest-api-tool.html">Ripple-REST API Tool</a></li>
<li><a href="ripple-api-tool.html">WebSocket API Tool</a></li>
<li><a href="data-api-v2-tool.html">Data API v2 Tool</a></li>
</ul>
</li>
<li class="dropdown">
<a href="#" class="dropdown-toggle" data-toggle="dropdown">Resources <span class="caret"></span></a>
<ul class="dropdown-menu" role="menu">
<li><a href="https://forum.ripple.com/viewforum.php?f=2">Forums</a></li>
<li><a href="https://www.bountysource.com/teams/ripple/bounties">Bounties</a></li>
<li><a href="https://ripplelabs.atlassian.net/">Bug Tracking</a></li>
<li><a href="https://ripple.com/category/dev-blog/">Dev Blog</a></li>
<li><a href="https://ripple.com/press-releases/">Press Center</a></li>
<li><a href="https://ripple.com/brand-guidelines/">Brand Guidelines</a></li>
</ul>
<li><a href="https://github.com/ripple/ripple-dev-portal" title="GitHub">Site Source</a></li>
</ul>
</div><!--/.nav-collapse -->
</div>
</div>
<script type="text/javascript">
if (window.location.host.indexOf("github.io") > -1) {
document.write("<div style='background-color:red; color:white; position:fixed; top: 50px; right: 150px; padding: 10px 20px;'>DRAFT</div>");
}
</script>
<div class='wrapper'>
<div class='content-root'>
<div id='wrapper'>
<div style="clear:both;"></div>
<div id='command_wrapper'>
<ul id='command_list'>
</ul>
<div id='command_table'>
<div id='io_wrapper'>
<div id='input' class='io'>
<h2>REST Request</h2>
<div id='test_warning' class='alert alert-danger' style='display:none;'>
<h4>Test accounts only!</h4>
<p>Never submit account secrets to a server you do not control, unless you are prepared to lose ownership of the account!</p>
</div>
<div style="clear:both;"></div>
<h3 id='selected_command' title='Reference information'></h3>
<p id='description'></p>
<div id='invalid'>Invalid JSON</div>
<div id='rest_url_wrapper'>
<p><span id='rest_host'>https://api.ripple.com</span><span id='rest_url'></span></p>
</div>
<div id='request_body'></div>
<div id='request_options'>
<div class="button btn btn-primary api" id='request_button'>Send request</div>
</div>
</div>
<div id='output' class='io'>
<h2>Response</h2>
<div>
<img class="loader" src="assets/img/rippleThrobber.png" style="vertical-align: middle; display:none;"/>
<span id='rest_responsecode'></span>
</div>
<div id='response_body'></div>
<div id='tooltip'></div>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
<footer class="footer">
<div class="container">
<div class="row">
<div class="col-md-3">
<h4>Documentation</h4>
<ul class="footer_links">
<li><a href="paths.html">Paths</a></li>
<li><a href="fees.html">Fees (Disambiguation)</a></li>
<li><a href="transfer_fees.html">Transfer Fees</a></li>
<li><a href="tx-cost.html">Transaction Cost</a></li>
<li><a href="fee-voting.html">Fee Voting</a></li>
<li><a href="reserves.html">Reserves</a></li>
<li><a href="freeze.html">Freeze</a></li>
<li><a href="rippled-apis.html">rippled</a></li>
<li><a href="rippled-setup.html">rippled Setup</a></li>
<li><a href="ripple-rest.html">Ripple-REST</a></li>
<li><a href="transactions.html">Transactions</a></li>
<li><a href="ripple-ledger.html">Ledger Format</a></li>
<li><a href="reliable_tx.html">Reliable Transaction Submission</a></li>
<li><a href="gateway_guide.html">Gateway Guide</a></li>
<li><a href="data_api_v2.html">Ripple Data API v2</a></li>
<li><a href="rippleapi.html">RippleAPI</a></li>
</ul>
</div>
<div class="col-md-3">
<h4>Resources</h4>
<ul class="footer_links">
<li><a href="https://ripple.com/press-releases/">Press Center</a></li>
<li><a href="https://ripple.com/brand-guidelines/">Brand Use and Guidelines</a></li>
<li><a href="https://forum.ripple.com/viewforum.php?f=2">Forums</a></li>
<li><a href="https://ripple.com/category/dev-blog/">Dev Blog</a></li>
</ul>
</div>
<div class="col-md-3">
<h4>Ripple Projects</h4>
<ul class="footer_links">
<li><a href="https://www.rippletrade.com">Ripple Trade</a>
<li><a href="https://www.ripplecharts.com">Ripple Charts</a>
<li><a href="https://ripple.com/graph">Ripple Graph</a>
<li><a href="http://codius.org/">Codius</a>
</ul>
</div>
<div class="col-md-3">
<h4>Ripple Labs</h4>
<ul class="footer_links">
<li><a href="https://www.ripplelabs.com/wp-content/uploads/2014/10/ripple_labs_bylaws.pdf">Corporate Bylaws</a></li>
<li><a href="https://www.ripplelabs.com/wp-content/uploads/2014/09/ripple_labs_code_of_conduct1.pdf">Code of Conduct</a></li>
<li><a href="https://www.ripplelabs.com/team/">Team</a></li>
<li><a href="https://www.ripplelabs.com/careers/">Careers</a></li>
<li><a href="https://www.ripplelabs.com/investors/">Investors</a></li>
<li><a href="https://www.ripplelabs.com/advisors/">Advisors</a></li>
<li><a href="https://www.ripplelabs.com/xrp-distribution/">XRP Distribution</a></li>
<li><a href="https://www.ripplelabs.com/contact/">Contact</a></li>
</ul>
</div>
</div>
</div>
</footer>
<link rel='stylesheet' type='text/css' href='css/api-style.css'/>
<link rel='stylesheet' type='text/css' href='css/codemirror.css'/>
<script type='text/javascript' src='js/es5-shim.js'></script>
<script src='vendor/codemirror.min.js'></script>
<script type='text/javascript' src='js/cm-javascript.min.js'></script>
<script type='text/javascript' src='js/jquery.autosize.input.min.js'></script>
<script type='text/javascript' src='js/apitool-rest.js'></script>
<script type='text/javascript' src='js/apitool-methods-ripplerest.js'></script>
</body>
</html>

3
ripple-api-tool.html
View File

@@ -60,7 +60,6 @@
<a href="#" class="dropdown-toggle" data-toggle="dropdown">References <span class="caret"></span></a> <a href="#" class="dropdown-toggle" data-toggle="dropdown">References <span class="caret"></span></a>
<ul class="dropdown-menu" role="menu"> <ul class="dropdown-menu" role="menu">
<li><a href="rippled-apis.html">rippled</a></li> <li><a href="rippled-apis.html">rippled</a></li>
<li><a href="ripple-rest.html">Ripple-REST</a></li>
<li><a href="transactions.html">Transactions</a></li> <li><a href="transactions.html">Transactions</a></li>
<li><a href="ripple-ledger.html">Ledger Format</a></li> <li><a href="ripple-ledger.html">Ledger Format</a></li>
<li><a href="data_api_v2.html">Ripple Data API v2</a></li> <li><a href="data_api_v2.html">Ripple Data API v2</a></li>
@@ -78,7 +77,6 @@
<li class="dropdown"> <li class="dropdown">
<a href="#" class="dropdown-toggle" data-toggle="dropdown">API Tools <span class="caret"></span></a> <a href="#" class="dropdown-toggle" data-toggle="dropdown">API Tools <span class="caret"></span></a>
<ul class="dropdown-menu" role="menu"> <ul class="dropdown-menu" role="menu">
<li><a href="rest-api-tool.html">Ripple-REST API Tool</a></li>
<li><a href="ripple-api-tool.html">WebSocket API Tool</a></li> <li><a href="ripple-api-tool.html">WebSocket API Tool</a></li>
<li><a href="data-api-v2-tool.html">Data API v2 Tool</a></li> <li><a href="data-api-v2-tool.html">Data API v2 Tool</a></li>
</ul> </ul>
@@ -193,7 +191,6 @@
<li><a href="freeze.html">Freeze</a></li> <li><a href="freeze.html">Freeze</a></li>
<li><a href="rippled-apis.html">rippled</a></li> <li><a href="rippled-apis.html">rippled</a></li>
<li><a href="rippled-setup.html">rippled Setup</a></li> <li><a href="rippled-setup.html">rippled Setup</a></li>
<li><a href="ripple-rest.html">Ripple-REST</a></li>
<li><a href="transactions.html">Transactions</a></li> <li><a href="transactions.html">Transactions</a></li>
<li><a href="ripple-ledger.html">Ledger Format</a></li> <li><a href="ripple-ledger.html">Ledger Format</a></li>
<li><a href="reliable_tx.html">Reliable Transaction Submission</a></li> <li><a href="reliable_tx.html">Reliable Transaction Submission</a></li>

3
ripple-ledger.html
View File

@@ -81,7 +81,6 @@
<a href="#" class="dropdown-toggle" data-toggle="dropdown">References <span class="caret"></span></a> <a href="#" class="dropdown-toggle" data-toggle="dropdown">References <span class="caret"></span></a>
<ul class="dropdown-menu" role="menu"> <ul class="dropdown-menu" role="menu">
<li><a href="rippled-apis.html">rippled</a></li> <li><a href="rippled-apis.html">rippled</a></li>
<li><a href="ripple-rest.html">Ripple-REST</a></li>
<li><a href="transactions.html">Transactions</a></li> <li><a href="transactions.html">Transactions</a></li>
<li><a href="ripple-ledger.html">Ledger Format</a></li> <li><a href="ripple-ledger.html">Ledger Format</a></li>
<li><a href="data_api_v2.html">Ripple Data API v2</a></li> <li><a href="data_api_v2.html">Ripple Data API v2</a></li>
@@ -99,7 +98,6 @@
<li class="dropdown"> <li class="dropdown">
<a href="#" class="dropdown-toggle" data-toggle="dropdown">API Tools <span class="caret"></span></a> <a href="#" class="dropdown-toggle" data-toggle="dropdown">API Tools <span class="caret"></span></a>
<ul class="dropdown-menu" role="menu"> <ul class="dropdown-menu" role="menu">
<li><a href="rest-api-tool.html">Ripple-REST API Tool</a></li>
<li><a href="ripple-api-tool.html">WebSocket API Tool</a></li> <li><a href="ripple-api-tool.html">WebSocket API Tool</a></li>
<li><a href="data-api-v2-tool.html">Data API v2 Tool</a></li> <li><a href="data-api-v2-tool.html">Data API v2 Tool</a></li>
</ul> </ul>
@@ -985,7 +983,6 @@
<li><a href="freeze.html">Freeze</a></li> <li><a href="freeze.html">Freeze</a></li>
<li><a href="rippled-apis.html">rippled</a></li> <li><a href="rippled-apis.html">rippled</a></li>
<li><a href="rippled-setup.html">rippled Setup</a></li> <li><a href="rippled-setup.html">rippled Setup</a></li>
<li><a href="ripple-rest.html">Ripple-REST</a></li>
<li><a href="transactions.html">Transactions</a></li> <li><a href="transactions.html">Transactions</a></li>
<li><a href="ripple-ledger.html">Ledger Format</a></li> <li><a href="ripple-ledger.html">Ledger Format</a></li>
<li><a href="reliable_tx.html">Reliable Transaction Submission</a></li> <li><a href="reliable_tx.html">Reliable Transaction Submission</a></li>

3356
ripple-rest.html
View File

File diff suppressed because it is too large Load Diff

3
rippleapi.html
View File

@@ -81,7 +81,6 @@
<a href="#" class="dropdown-toggle" data-toggle="dropdown">References <span class="caret"></span></a> <a href="#" class="dropdown-toggle" data-toggle="dropdown">References <span class="caret"></span></a>
<ul class="dropdown-menu" role="menu"> <ul class="dropdown-menu" role="menu">
<li><a href="rippled-apis.html">rippled</a></li> <li><a href="rippled-apis.html">rippled</a></li>
<li><a href="ripple-rest.html">Ripple-REST</a></li>
<li><a href="transactions.html">Transactions</a></li> <li><a href="transactions.html">Transactions</a></li>
<li><a href="ripple-ledger.html">Ledger Format</a></li> <li><a href="ripple-ledger.html">Ledger Format</a></li>
<li><a href="data_api_v2.html">Ripple Data API v2</a></li> <li><a href="data_api_v2.html">Ripple Data API v2</a></li>
@@ -99,7 +98,6 @@
<li class="dropdown"> <li class="dropdown">
<a href="#" class="dropdown-toggle" data-toggle="dropdown">API Tools <span class="caret"></span></a> <a href="#" class="dropdown-toggle" data-toggle="dropdown">API Tools <span class="caret"></span></a>
<ul class="dropdown-menu" role="menu"> <ul class="dropdown-menu" role="menu">
<li><a href="rest-api-tool.html">Ripple-REST API Tool</a></li>
<li><a href="ripple-api-tool.html">WebSocket API Tool</a></li> <li><a href="ripple-api-tool.html">WebSocket API Tool</a></li>
<li><a href="data-api-v2-tool.html">Data API v2 Tool</a></li> <li><a href="data-api-v2-tool.html">Data API v2 Tool</a></li>
</ul> </ul>
@@ -5158,7 +5156,6 @@ return api.computeLedgerHash(ledger);
<li><a href="freeze.html">Freeze</a></li> <li><a href="freeze.html">Freeze</a></li>
<li><a href="rippled-apis.html">rippled</a></li> <li><a href="rippled-apis.html">rippled</a></li>
<li><a href="rippled-setup.html">rippled Setup</a></li> <li><a href="rippled-setup.html">rippled Setup</a></li>
<li><a href="ripple-rest.html">Ripple-REST</a></li>
<li><a href="transactions.html">Transactions</a></li> <li><a href="transactions.html">Transactions</a></li>
<li><a href="ripple-ledger.html">Ledger Format</a></li> <li><a href="ripple-ledger.html">Ledger Format</a></li>
<li><a href="reliable_tx.html">Reliable Transaction Submission</a></li> <li><a href="reliable_tx.html">Reliable Transaction Submission</a></li>

5
rippled-apis.html
View File

@@ -81,7 +81,6 @@
<a href="#" class="dropdown-toggle" data-toggle="dropdown">References <span class="caret"></span></a> <a href="#" class="dropdown-toggle" data-toggle="dropdown">References <span class="caret"></span></a>
<ul class="dropdown-menu" role="menu"> <ul class="dropdown-menu" role="menu">
<li><a href="rippled-apis.html">rippled</a></li> <li><a href="rippled-apis.html">rippled</a></li>
<li><a href="ripple-rest.html">Ripple-REST</a></li>
<li><a href="transactions.html">Transactions</a></li> <li><a href="transactions.html">Transactions</a></li>
<li><a href="ripple-ledger.html">Ledger Format</a></li> <li><a href="ripple-ledger.html">Ledger Format</a></li>
<li><a href="data_api_v2.html">Ripple Data API v2</a></li> <li><a href="data_api_v2.html">Ripple Data API v2</a></li>
@@ -99,7 +98,6 @@
<li class="dropdown"> <li class="dropdown">
<a href="#" class="dropdown-toggle" data-toggle="dropdown">API Tools <span class="caret"></span></a> <a href="#" class="dropdown-toggle" data-toggle="dropdown">API Tools <span class="caret"></span></a>
<ul class="dropdown-menu" role="menu"> <ul class="dropdown-menu" role="menu">
<li><a href="rest-api-tool.html">Ripple-REST API Tool</a></li>
<li><a href="ripple-api-tool.html">WebSocket API Tool</a></li> <li><a href="ripple-api-tool.html">WebSocket API Tool</a></li>
<li><a href="data-api-v2-tool.html">Data API v2 Tool</a></li> <li><a href="data-api-v2-tool.html">Data API v2 Tool</a></li>
</ul> </ul>
@@ -144,7 +142,7 @@
<li>Client Library - <a href="https://github.com/ripple/ripple-lib">Javascript</a></li> <li>Client Library - <a href="https://github.com/ripple/ripple-lib">Javascript</a></li>
</ul> </ul>
<h1 id="websocket-and-json-rpc-apis">WebSocket and JSON-RPC APIs</h1> <h1 id="websocket-and-json-rpc-apis">WebSocket and JSON-RPC APIs</h1>
<p>If you want to communicate directly with the <code>rippled</code> server, you can use either the WebSocket API or the JSON-RPC API. Both APIs use the same list of commands, with almost entirely the same parameters in each command. Whereas the <a href="ripple-rest.html">Ripple-REST API</a> provides a simplified interface on top of the WebSocket API for easier integration, these APIs provide the full power of Ripple but require slightly more complexity:</p> <p>If you want to communicate directly with the <code>rippled</code> server, you can use either the WebSocket API or the JSON-RPC API. Both APIs use the same list of commands, with almost entirely the same parameters in each command.</p>
<ul> <ul>
<li>The WebSocket API uses the <a href="http://www.html5rocks.com/en/tutorials/websockets/basics/">WebSocket protocol</a>, available in most browsers and Javascript implementations, to achieve persistent two-way communication. There is not a 1:1 correlation between requests and responses. Some requests prompt the server to send multiple messages back asynchronously; other times, responses may arrive in a different order than the requests that prompted them. The <code>rippled</code> server can be configured to accept secured (wss:), unsecured (ws:) WebSocket connections, or both.</li> <li>The WebSocket API uses the <a href="http://www.html5rocks.com/en/tutorials/websockets/basics/">WebSocket protocol</a>, available in most browsers and Javascript implementations, to achieve persistent two-way communication. There is not a 1:1 correlation between requests and responses. Some requests prompt the server to send multiple messages back asynchronously; other times, responses may arrive in a different order than the requests that prompted them. The <code>rippled</code> server can be configured to accept secured (wss:), unsecured (ws:) WebSocket connections, or both.</li>
<li>The JSON-RPC API relies on simple request-response communication via HTTP or HTTPS. (The <code>rippled</code> server can be configured to accept HTTP, HTTPS, or both.) For commands that prompt multiple responses, you can provide a callback URL.</li> <li>The JSON-RPC API relies on simple request-response communication via HTTP or HTTPS. (The <code>rippled</code> server can be configured to accept HTTP, HTTPS, or both.) For commands that prompt multiple responses, you can provide a callback URL.</li>
@@ -5955,7 +5953,6 @@ a successful result containing the following fields:</p>
<li><a href="freeze.html">Freeze</a></li> <li><a href="freeze.html">Freeze</a></li>
<li><a href="rippled-apis.html">rippled</a></li> <li><a href="rippled-apis.html">rippled</a></li>
<li><a href="rippled-setup.html">rippled Setup</a></li> <li><a href="rippled-setup.html">rippled Setup</a></li>
<li><a href="ripple-rest.html">Ripple-REST</a></li>
<li><a href="transactions.html">Transactions</a></li> <li><a href="transactions.html">Transactions</a></li>
<li><a href="ripple-ledger.html">Ledger Format</a></li> <li><a href="ripple-ledger.html">Ledger Format</a></li>
<li><a href="reliable_tx.html">Reliable Transaction Submission</a></li> <li><a href="reliable_tx.html">Reliable Transaction Submission</a></li>

3
rippled-setup.html
View File

@@ -81,7 +81,6 @@
<a href="#" class="dropdown-toggle" data-toggle="dropdown">References <span class="caret"></span></a> <a href="#" class="dropdown-toggle" data-toggle="dropdown">References <span class="caret"></span></a>
<ul class="dropdown-menu" role="menu"> <ul class="dropdown-menu" role="menu">
<li><a href="rippled-apis.html">rippled</a></li> <li><a href="rippled-apis.html">rippled</a></li>
<li><a href="ripple-rest.html">Ripple-REST</a></li>
<li><a href="transactions.html">Transactions</a></li> <li><a href="transactions.html">Transactions</a></li>
<li><a href="ripple-ledger.html">Ledger Format</a></li> <li><a href="ripple-ledger.html">Ledger Format</a></li>
<li><a href="data_api_v2.html">Ripple Data API v2</a></li> <li><a href="data_api_v2.html">Ripple Data API v2</a></li>
@@ -99,7 +98,6 @@
<li class="dropdown"> <li class="dropdown">
<a href="#" class="dropdown-toggle" data-toggle="dropdown">API Tools <span class="caret"></span></a> <a href="#" class="dropdown-toggle" data-toggle="dropdown">API Tools <span class="caret"></span></a>
<ul class="dropdown-menu" role="menu"> <ul class="dropdown-menu" role="menu">
<li><a href="rest-api-tool.html">Ripple-REST API Tool</a></li>
<li><a href="ripple-api-tool.html">WebSocket API Tool</a></li> <li><a href="ripple-api-tool.html">WebSocket API Tool</a></li>
<li><a href="data-api-v2-tool.html">Data API v2 Tool</a></li> <li><a href="data-api-v2-tool.html">Data API v2 Tool</a></li>
</ul> </ul>
@@ -406,7 +404,6 @@ ssdecohJMDPFuUPDkmG1w4objZyp4
<li><a href="freeze.html">Freeze</a></li> <li><a href="freeze.html">Freeze</a></li>
<li><a href="rippled-apis.html">rippled</a></li> <li><a href="rippled-apis.html">rippled</a></li>
<li><a href="rippled-setup.html">rippled Setup</a></li> <li><a href="rippled-setup.html">rippled Setup</a></li>
<li><a href="ripple-rest.html">Ripple-REST</a></li>
<li><a href="transactions.html">Transactions</a></li> <li><a href="transactions.html">Transactions</a></li>
<li><a href="ripple-ledger.html">Ledger Format</a></li> <li><a href="ripple-ledger.html">Ledger Format</a></li>
<li><a href="reliable_tx.html">Reliable Transaction Submission</a></li> <li><a href="reliable_tx.html">Reliable Transaction Submission</a></li>

17
tool/pages.json
View File

@@ -74,13 +74,6 @@
"ripple.com": "https://ripple.com/build/rippled-setup/", "ripple.com": "https://ripple.com/build/rippled-setup/",
"category": "Tutorials" "category": "Tutorials"
}, },
{
"name": "Ripple-REST",
"md": "ripplerest_api.md",
"html": "ripple-rest.html",
"ripple.com": "https://ripple.com/build/ripple-rest/",
"category": "References"
},
{ {
"name": "Transactions", "name": "Transactions",
"md":"tx_format.md", "md":"tx_format.md",
@@ -123,16 +116,6 @@
"ripple.com": "https://ripple.com/build/rippleapi/", "ripple.com": "https://ripple.com/build/rippleapi/",
"category": "References" "category": "References"
}, },
{
"name": "Ripple-REST API Tool",
"template":"template-rest-api-tool.html",
"methods_js": "js/apitool-methods-ripplerest.js",
"category": "API Tools",
"rest_host": "https://api.ripple.com",
"ripple.com": "https://ripple.com/build/rest-tool/",
"html": "rest-api-tool.html",
"targets": ["local","ripple.com"]
},
{ {
"name": "WebSocket API Tool", "name": "WebSocket API Tool",
"template":"template-ripple-api-tool.html", "template":"template-ripple-api-tool.html",

3
transactions.html
View File

@@ -81,7 +81,6 @@
<a href="#" class="dropdown-toggle" data-toggle="dropdown">References <span class="caret"></span></a> <a href="#" class="dropdown-toggle" data-toggle="dropdown">References <span class="caret"></span></a>
<ul class="dropdown-menu" role="menu"> <ul class="dropdown-menu" role="menu">
<li><a href="rippled-apis.html">rippled</a></li> <li><a href="rippled-apis.html">rippled</a></li>
<li><a href="ripple-rest.html">Ripple-REST</a></li>
<li><a href="transactions.html">Transactions</a></li> <li><a href="transactions.html">Transactions</a></li>
<li><a href="ripple-ledger.html">Ledger Format</a></li> <li><a href="ripple-ledger.html">Ledger Format</a></li>
<li><a href="data_api_v2.html">Ripple Data API v2</a></li> <li><a href="data_api_v2.html">Ripple Data API v2</a></li>
@@ -99,7 +98,6 @@
<li class="dropdown"> <li class="dropdown">
<a href="#" class="dropdown-toggle" data-toggle="dropdown">API Tools <span class="caret"></span></a> <a href="#" class="dropdown-toggle" data-toggle="dropdown">API Tools <span class="caret"></span></a>
<ul class="dropdown-menu" role="menu"> <ul class="dropdown-menu" role="menu">
<li><a href="rest-api-tool.html">Ripple-REST API Tool</a></li>
<li><a href="ripple-api-tool.html">WebSocket API Tool</a></li> <li><a href="ripple-api-tool.html">WebSocket API Tool</a></li>
<li><a href="data-api-v2-tool.html">Data API v2 Tool</a></li> <li><a href="data-api-v2-tool.html">Data API v2 Tool</a></li>
</ul> </ul>
@@ -1965,7 +1963,6 @@
<li><a href="freeze.html">Freeze</a></li> <li><a href="freeze.html">Freeze</a></li>
<li><a href="rippled-apis.html">rippled</a></li> <li><a href="rippled-apis.html">rippled</a></li>
<li><a href="rippled-setup.html">rippled Setup</a></li> <li><a href="rippled-setup.html">rippled Setup</a></li>
<li><a href="ripple-rest.html">Ripple-REST</a></li>
<li><a href="transactions.html">Transactions</a></li> <li><a href="transactions.html">Transactions</a></li>
<li><a href="ripple-ledger.html">Ledger Format</a></li> <li><a href="ripple-ledger.html">Ledger Format</a></li>
<li><a href="reliable_tx.html">Reliable Transaction Submission</a></li> <li><a href="reliable_tx.html">Reliable Transaction Submission</a></li>

17
transfer_fees.html
View File

@@ -81,7 +81,6 @@
<a href="#" class="dropdown-toggle" data-toggle="dropdown">References <span class="caret"></span></a> <a href="#" class="dropdown-toggle" data-toggle="dropdown">References <span class="caret"></span></a>
<ul class="dropdown-menu" role="menu"> <ul class="dropdown-menu" role="menu">
<li><a href="rippled-apis.html">rippled</a></li> <li><a href="rippled-apis.html">rippled</a></li>
<li><a href="ripple-rest.html">Ripple-REST</a></li>
<li><a href="transactions.html">Transactions</a></li> <li><a href="transactions.html">Transactions</a></li>
<li><a href="ripple-ledger.html">Ledger Format</a></li> <li><a href="ripple-ledger.html">Ledger Format</a></li>
<li><a href="data_api_v2.html">Ripple Data API v2</a></li> <li><a href="data_api_v2.html">Ripple Data API v2</a></li>
@@ -99,7 +98,6 @@
<li class="dropdown"> <li class="dropdown">
<a href="#" class="dropdown-toggle" data-toggle="dropdown">API Tools <span class="caret"></span></a> <a href="#" class="dropdown-toggle" data-toggle="dropdown">API Tools <span class="caret"></span></a>
<ul class="dropdown-menu" role="menu"> <ul class="dropdown-menu" role="menu">
<li><a href="rest-api-tool.html">Ripple-REST API Tool</a></li>
<li><a href="ripple-api-tool.html">WebSocket API Tool</a></li> <li><a href="ripple-api-tool.html">WebSocket API Tool</a></li>
<li><a href="data-api-v2-tool.html">Data API v2 Tool</a></li> <li><a href="data-api-v2-tool.html">Data API v2 Tool</a></li>
</ul> </ul>
@@ -152,14 +150,14 @@
</ul> </ul>
<h1 id="technical-details">Technical Details</h1> <h1 id="technical-details">Technical Details</h1>
<p>The transfer fee is represented by a setting on the issuing (<strong>cold wallet</strong>) account. The transfer fee has a maximum precision of 9 digits, and cannot be less than 0% or greater than 100%. The TransferRate setting applies to all currencies issued by the same account. If you want to have different transfer fee percentages for different currencies, use different cold wallets to issue each currency.</p> <p>The transfer fee is represented by a setting on the issuing (<strong>cold wallet</strong>) account. The transfer fee has a maximum precision of 9 digits, and cannot be less than 0% or greater than 100%. The TransferRate setting applies to all currencies issued by the same account. If you want to have different transfer fee percentages for different currencies, use different cold wallets to issue each currency.</p>
<h2 id="ripple-rest">Ripple-REST</h2> <h2 id="rippleapi">RippleAPI</h2>
<p>In Ripple-REST, the transfer fee is specified in the <code>transfer_rate</code> field, as a decimal which represents the amount you must send in order for the recipient to get 1 unit of the same currency. A <code>transfer_rate</code> of <code>1.005</code> is equivalent to a transfer fee of 0.5%. By default, the <code>transfer_rate</code> is set at <code>1.0</code>, indicating no fee. The value of <code>transfer_rate</code> cannot be less than <code>1.0</code> or more than <code>2.0</code>. However, the value <code>0</code> is special: it is equivalent to <code>1.0</code>, meaning no fee.</p> <p>In RippleAPI, the transfer fee is specified in the <code>transferRate</code> field, as an integer which represents the amount you must send in order for the recipient to get 1 billion units of the same currency. A <code>transferRate</code> of <code>1005000000</code> is equivalent to a transfer fee of 0.5%. By default, the <code>transferRate</code> is set to no fee. The value of <code>transferRate</code> cannot be less than <code>1000000000</code> or more than <code>2000000000</code>. The value <code>null</code> is special: it is equivalent to <code>1000000000</code>, meaning no fee.</p>
<p>A gateway can use the <a href="https://ripple.com/build/ripple-rest/#update-account-settings">Update Account Settings method</a> with its cold wallet to change the <code>transfer_rate</code> for its issuances.</p> <p>A gateway can send a <a href="rippleapi.html#settings">Settings transaction</a> with its cold wallet to change the <code>transferRate</code> for its issuances.</p>
<p>You can check an account's <code>transfer_rate</code> with the <a href="https://ripple.com/build/ripple-rest/#get-account-settings">Get Account Settings method</a>.</p> <p>You can check an account's <code>transferRate</code> with the <a href="rippleapi.html#getsettings">getSettings method</a>.</p>
<h2 id="rippled">rippled</h2> <h2 id="rippled">rippled</h2>
<p>In <code>rippled</code>'s JSON-RPC and WebSocket APIs, the transfer fee is specified in the <code>TransferRate</code> field, as an integer which represents the amount you must send in order for the recipient to get 1 billion units of the same currency. A <code>TransferRate</code> of <code>1005000000</code> is equivalent to a transfer fee of 0.5%. By default, the <code>transfer_rate</code> is set at <code>1000000000</code>, indicating no fee. The value of <code>TransferRate</code> cannot be less than <code>1000000000</code> or more than <code>2000000000</code>. However, value <code>0</code> is special: it is equivalent to <code>1000000000</code>, meaning no fee.</p> <p>In <code>rippled</code>'s JSON-RPC and WebSocket APIs, the transfer fee is specified in the <code>TransferRate</code> field, as an integer which represents the amount you must send in order for the recipient to get 1 billion units of the same currency. A <code>TransferRate</code> of <code>1005000000</code> is equivalent to a transfer fee of 0.5%. By default, the <code>TransferRate</code> is set at <code>1000000000</code>, indicating no fee. The value of <code>TransferRate</code> cannot be less than <code>1000000000</code> or more than <code>2000000000</code>. However, value <code>0</code> is special: it is equivalent to <code>1000000000</code>, meaning no fee.</p>
<p>A gateway can submit an <a href="https://ripple.com/build/transactions/#accountset">AccountSet transaction</a> from its cold wallet to change the <code>TransferRate</code> for its issuances. </p> <p>A gateway can submit an <a href="transactions.html#accountset">AccountSet transaction</a> from its cold wallet to change the <code>TransferRate</code> for its issuances. </p>
<p>You can check an account's <code>TransferRate</code> with the <a href="https://ripple.com/build/rippled-apis/#account-info">account_info command</a>. If the <code>TransferRate</code> is omitted, then that indicates no fee.</p> <p>You can check an account's <code>TransferRate</code> with the <a href="rippled-apis.html#account-info"><code>account_info</code> command</a>. If the <code>TransferRate</code> is omitted, then that indicates no fee.</p>
</div> </div>
</div> </div>
</div> </div>
@@ -178,7 +176,6 @@
<li><a href="freeze.html">Freeze</a></li> <li><a href="freeze.html">Freeze</a></li>
<li><a href="rippled-apis.html">rippled</a></li> <li><a href="rippled-apis.html">rippled</a></li>
<li><a href="rippled-setup.html">rippled Setup</a></li> <li><a href="rippled-setup.html">rippled Setup</a></li>
<li><a href="ripple-rest.html">Ripple-REST</a></li>
<li><a href="transactions.html">Transactions</a></li> <li><a href="transactions.html">Transactions</a></li>
<li><a href="ripple-ledger.html">Ledger Format</a></li> <li><a href="ripple-ledger.html">Ledger Format</a></li>
<li><a href="reliable_tx.html">Reliable Transaction Submission</a></li> <li><a href="reliable_tx.html">Reliable Transaction Submission</a></li>

3
tx-cost.html
View File

@@ -81,7 +81,6 @@
<a href="#" class="dropdown-toggle" data-toggle="dropdown">References <span class="caret"></span></a> <a href="#" class="dropdown-toggle" data-toggle="dropdown">References <span class="caret"></span></a>
<ul class="dropdown-menu" role="menu"> <ul class="dropdown-menu" role="menu">
<li><a href="rippled-apis.html">rippled</a></li> <li><a href="rippled-apis.html">rippled</a></li>
<li><a href="ripple-rest.html">Ripple-REST</a></li>
<li><a href="transactions.html">Transactions</a></li> <li><a href="transactions.html">Transactions</a></li>
<li><a href="ripple-ledger.html">Ledger Format</a></li> <li><a href="ripple-ledger.html">Ledger Format</a></li>
<li><a href="data_api_v2.html">Ripple Data API v2</a></li> <li><a href="data_api_v2.html">Ripple Data API v2</a></li>
@@ -99,7 +98,6 @@
<li class="dropdown"> <li class="dropdown">
<a href="#" class="dropdown-toggle" data-toggle="dropdown">API Tools <span class="caret"></span></a> <a href="#" class="dropdown-toggle" data-toggle="dropdown">API Tools <span class="caret"></span></a>
<ul class="dropdown-menu" role="menu"> <ul class="dropdown-menu" role="menu">
<li><a href="rest-api-tool.html">Ripple-REST API Tool</a></li>
<li><a href="ripple-api-tool.html">WebSocket API Tool</a></li> <li><a href="ripple-api-tool.html">WebSocket API Tool</a></li>
<li><a href="data-api-v2-tool.html">Data API v2 Tool</a></li> <li><a href="data-api-v2-tool.html">Data API v2 Tool</a></li>
</ul> </ul>
@@ -201,7 +199,6 @@
<li><a href="freeze.html">Freeze</a></li> <li><a href="freeze.html">Freeze</a></li>
<li><a href="rippled-apis.html">rippled</a></li> <li><a href="rippled-apis.html">rippled</a></li>
<li><a href="rippled-setup.html">rippled Setup</a></li> <li><a href="rippled-setup.html">rippled Setup</a></li>
<li><a href="ripple-rest.html">Ripple-REST</a></li>
<li><a href="transactions.html">Transactions</a></li> <li><a href="transactions.html">Transactions</a></li>
<li><a href="ripple-ledger.html">Ledger Format</a></li> <li><a href="ripple-ledger.html">Ledger Format</a></li>
<li><a href="reliable_tx.html">Reliable Transaction Submission</a></li> <li><a href="reliable_tx.html">Reliable Transaction Submission</a></li>