README
: Fetch XRPL transaction data (auto failover) xrpl-txdata
This lib. allows you to fetch XRP ledger transaction outcome from a number of (full history) XRP ledger nodes. This lib. will automatically setup connections when fetching from a selected node takes too long. The first (sane) reply will be returned.
This lib. will get you the fastest response possible while setting up the lowest amount of WebSocket connections to full history XRPL nodes possible.
This package can be used in Node/Typescript projects (xrpl-txdata
) or used (browserified) in the browser.
Not only the requested transaction will be returned (or the not found
response if the transaction can't be found): the parsed balances (transaction outcome) will be calculated (form the transaction metadata) and returned as well.
A simple ES6 JS example can be found in samples/dev.js
.
Syntax
Basic usage: construct (using defaults), fetch one transaction and close WebSocket connection(s) after getting a result.
const txd = new TxData()
const main = async () => {
// getOne(): fetch one tx and close connection(s) after a reply
const tx = await txd.getOne('B34EFCDA6A9D6B19670E19ECD3CFD638177EED92B863756DD96CFD197B940515')
console.log(tx)
}
main()
Fetching multiple transactionos and close the WebSocket connection(s) programmatically:
const txd = new TxData()
const main = async () => {
// get(): fetch a tx, keep connetion(s) alive
const tx1 = await txd.get('B34EFCDA6A9D6B19670E19ECD3CFD638177EED92B863756DD96CFD197B940515')
console.log(tx1)
const tx2 = await txd.get('A17E4DEAD62BF705D9B73B4EAD2832F1C55C6C5A0067327A45E497FD8D31C0E3')
console.log(tx2)
// Done, not interested in more tx data, close connection(s)
txd.end()
}
main()
Advanced options
By default, these full history nodes will be used (in order):
wss://xrplcluster.com
(more info)wss://xrpl.link
(fallback endpoint forwss://xrplcluster.com
)wss://s2.ripple.com
The default timeout configuration will:
- Try to connect, query & get a response (per tx) within 1250ms (1.25 seconds) before trying the next node
- Try to connect, query & get a response (per tx) within 10 seconds
The first node to anwer the request will result in a resolved query.
To overrule the nodes (full history required), provide an array with websocket endpoints to the constructor in the order you'd like them to be used:
const txd = new TxData([
'wss://my-fh-xprl-node.local',
'wss://s2.ripple.com',
'wss://xrplcluster.com'
])
To overrule the default 1250 / 10000 ms timeouts, provide an object to the constructor (second param.):
// Empty array (endpoints) will result in using the default server list
const txd = new TxData([], {
// Try the next server after 0.75 sec.
EndpointTimeoutMs: 750,
// Throw an error if none of the servers connected & replied in 5 seconds
OverallTimeoutMs: 5000
})
Use in the browser
You can clone this repository and run:
npm run install
to install dependenciesnpm run build
to build the source codenpm run browserify
to browserify this lib.
Now the dist/browser.js
file will exist, for you to use in a browser.
Alternatively you can get a prebuilt / prebuilt & minified version from Github.
Response (format)
The response of a .get(someTxHash)
/ .getOne(someTxHash)
call contains four properties:
host
(string): the endpoint (connetion url) of the first node replying to the requestresolvedBy
(string):"generator"
if the host replied within theEndpointTimeoutMs
timeout,"emitter"
if the first reply came in after theEndpointTimeoutMs
timeout, but before the next host repliedresult
(object): containing the error or transaction response from the XRPL nodebalanceChanges
(object): containing the parsed balance changes for all accounts affected by this transaction
Formatted output
The balanceChanges
object contains (per element) a formatted
property. This contains the amount and currency
in formatted form: value decoded as NFT value (xls-14d) (when this applies) and the currency code decoded from HEX / xls-15d format.
Sample: response for a non existing transaction:
{
"result": {
"error": "txnNotFound",
"error_code": 29,
"error_message": "Transaction not found.",
"request": {...},
"status": "error",
"type": "response"
},
"resolvedBy": "generator",
"host": "wss://s2.ripple.com/",
"balanceChanges": {}
}
Sample: response for an existing transaction (simple payment):
{
"result": {
"Account": "r4bA4uZgXadPMzURqGLCvCmD48FmXJWHCG",
"Amount": "1000000",
"Destination": "rPdvC6ccq8hCdPKSPJkPmyZ4Mi1oG2FFkT",
"Fee": "12",
"TransactionType": "Payment",
"date": 655453821,
"meta": {...},
"validated": true,
...
},
"resolvedBy": "emitter",
"host": "wss://xrplcluster.com/",
"balanceChanges": {
"r4bA4uZgXadPMzURqGLCvCmD48FmXJWHCG": [
{
"counterparty": "",
"currency": "XRP",
"value": "-1.000012",
"formatted": { "value": "-1.000012", "currency": "XRP" }
}
],
"rPdvC6ccq8hCdPKSPJkPmyZ4Mi1oG2FFkT": [
{
"counterparty": "",
"currency": "XRP",
"value": "1",
"formatted": { "value": "1", "currency": "XRP" }
}
]
}
}
Sample: response for an existing transaction (Decentralized Exchange trade):
{
"result": {
"Account": "rPdvC6ccq8hCdPKSPJkPmyZ4Mi1oG2FFkT",
"Fee": "15",
"Flags": 2148007936,
"TakerGets": "15000000000",
"TakerPays": {
"currency": "EUR",
"issuer": "rhub8VRN55s94qWKDv6jmDy1pUykJzF3wq",
"value": "3999"
},
"TransactionType": "OfferCreate",
"ledger_index": 46223027,
"meta": {...},
"validated": true,
...
},
"resolvedBy": "generator",
"host": "wss://s2.ripple.com/",
"balanceChanges": {
"rhub8VRN55s94qWKDv6jmDy1pUykJzF3wq": [
{
"counterparty": "rPdvC6ccq8hCdPKSPJkPmyZ4Mi1oG2FFkT",
"currency": "EUR",
"value": "-1571.649031281391",
"formatted": { "value": "-1571.649031281391", "currency": "XRP" }
},
...
],
"rPdvC6ccq8hCdPKSPJkPmyZ4Mi1oG2FFkT": [
{
"counterparty": "rhub8VRN55s94qWKDv6jmDy1pUykJzF3wq",
"currency": "EUR",
"value": "1571.649031281391",
"formatted": { "value": "1571.649031281391", "currency": "XRP" }
},
{
"counterparty": "",
"currency": "XRP",
"value": "-5749.538284",
"formatted": { "value": "-5749.538284", "currency": "XRP" }
}
],
...
}
}