diff --git a/content/references/xrpljs2-migration-guide.md b/content/references/xrpljs2-migration-guide.md index 8570c59daf..41d26d8496 100644 --- a/content/references/xrpljs2-migration-guide.md +++ b/content/references/xrpljs2-migration-guide.md @@ -49,6 +49,33 @@ const xrpl = require("xrpl"); })(); ``` +## Validated Results + +By default, most methods in ripple-lib 1.x only returned results that were validated by the [consensus process](consensus.html) and final. The xrpl.js equivalents of many methods use the [`Client.request()` method](https://js.xrpl.org/classes/Client.html#request) to call the WebSocket API, where the XRP Ledger server's default settings often use the current (pending) ledger to serve data. + +Sometimes you want to use the current open ledger to get data because it has the pending results of many transactions that are likely to succeed, such as when looking up the state of the [decentralized exchange](decentralized-exchange.html). In other cases, you want to use a validated ledger, which only incorporates the results of transactions that are finalized. + +When making API requests with xrpl.js 2.0 using the , you should explicitly [specify what ledger to use](basic-data-types.html#specifying-ledgers). For example, to look up trust lines using a _validated ledger_: + +**ripple-lib 1.x:** + +```js +const trustlines = await api.getTrustlines("rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn") +console.log(trustlines) +``` + +**xrpl.js 2.0:** + +```js +const trustlines = await client.request({ + "command": "account_lines", + "account": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn", + "ledger_index": "validated" +}) +console.log(trustlines.result) +``` + + ## Transaction Submission In xrpl.js there are specific helper functions for signing and submitting transactions and waiting for the XRP Ledger blockchain to confirm those transactions' final outcomes. Use the `submitAndWait(tx_json, wallet)` method to sign a prepared transaction with the given wallet and submit it, like in this example: @@ -71,35 +98,152 @@ try { Alternatively, you can use the `sign` method of a wallet to sign a transaction and then use `submitAndWait(tx_blob)` to submit it. This can be useful for building [reliable transaction submission](reliable-transaction-submission.html) that can recover from power outages and other disasters. (The library does not handle disaster recovery on its own.) +### Controlling LastLedgerSequence + +In ripple-lib 1.x, you could specify a `instructions.maxLedgerVersionOffset` when preparing a transaction to define the `LastLedgerSequence` parameter of the prepared transaction as being some number of ledgers _after_ the latest validated one at the time. In 2.0, you can do this by looking up the latest validated ledger index, then specifying the `LastLedgerSequence` explicitly before auto-filling the transaction. + +**xrpl.js 2.0:** + +```js +const vli = await client.getLedgerIndex() + +const prepared = await client.autofill({ + "TransactionType": "Payment", + "Account": sender, + "Amount": xrpl.xrpToDrops("50.2"), + "Destination": "rPT1Sjq2YGrBMTttX4GZHjKu9dyfzbpAYe", + "LastLedgerSequence": vli+75 // gives ~5min, rather than the default ~1min +}) +``` + +Like the old prepare methods, `Client.autofill()` provides a reasonable `LastLedgerSequence` value by default. To prepare a transaction _without_ a `LastLedgerSequence` field, pass it with the value `null`: + +```js +const prepared = await client.autofill({ + "TransactionType": "Payment", + "Account": sender, + "Amount": xrpl.xrpToDrops("50.2"), + "Destination": "rPT1Sjq2YGrBMTttX4GZHjKu9dyfzbpAYe", + "LastLedgerSequence": null // Transaction never expires +}) +``` -## Quick Reference of Equivalents +## Events and Subscriptions + +In 1.x, you could subscribe to ledger events and API errors using the `.on()` method of the `RippleAPI` class; or you could subscribe to specific WebSocket message types using `.connection.on()`. These have been merged into the [`Client.on()` method](https://js.xrpl.org/classes/Client.html#on). Additionally, the client library no longer automatically subscribes to ledger close events when connecting to an XRP Ledger server, so **you must explicitly subscribe to the ledger stream** to get ledger close events in addition to adding a handler. + +To subscribe to ledger close events, use `Client.request(method)` to call the [subscribe method][] with `"streams": ["ledger"]`. To attach event handlers, use `Client.on(event_type, callback)`. You can make these calls in either order. + +The RippleAPI-specific `ledger` event type from 1.x has been removed; instead, use `ledgerClosed` events. These event messages contain the same data, but the format matches the [Ledger Stream](subscribe.html#ledger-stream) messages in the WebSocket API. + +Example: + +**ripple-lib 1.x:** + +```js +api.on("ledger", (ledger) => { + console.log(`Ledger #${ledger.ledgerVersion} closed! + It contains ${ledger.transactionCount} transaction(s) and has + the ledger_hash ${ledger.ledgerHash}.` + ) +}) +// "ledger" events happen automatically while API is connected. +``` + +**xrpl.js 2.0:** + +```js +client.on("ledgerClosed", (ledger) => { + console.log(`Ledger #${ledger.ledger_index} closed! + It contains ${ledger.txn_count} transaction(s) and has + the ledger_hash ${ledger.ledger_hash}.` + ) +}) +// Must explicitly subscribe to the "ledger" stream to get "ledgerClosed" events +client.request({ + "command": "subscribe", + "streams": ["ledger"] +}) +``` + + +## Reference of Equivalents In ripple-lib 1.x all methods and properties were on instances of the `RippleAPI` class. In xrpl.js 2.x, some methods are static methods of the library and some methods belong to specific classes. | RippleAPI instance method / property | xrpl.js method / property| Notes | |-------------------|----------------|---| | `new ripple.RippleAPI({server: url})` | `new xrpl.Client(url)` | Use `xrpl.BroadcastClient([url1, url2, ..])` to connect to multiple servers. | -| `request(command, options)` | `Client.request(options)` | The `command` field moved into the `options` object for consistency with the WebSocket API; also, the return value . | -| `hasNextPage(response)` | ***TODO (check for marker?)*** | See also: `Client.requestNextPage()` and `Client.requestAll()` | +| `request(command, options)` | `Client.request(options)` |