Skip to content

Commit 25d1ac0

Browse files
author
Chris Clark
committed
Add documentation for API events
1 parent f534baf commit 25d1ac0

File tree

5 files changed

+165
-25
lines changed

5 files changed

+165
-25
lines changed

‎docs/index.md

+75-8
Original file line numberDiff line numberDiff line change
@@ -55,6 +55,9 @@
5555
- [submit](#submit)
5656
- [generateAddress](#generateaddress)
5757
- [computeLedgerHash](#computeledgerhash)
58+
- [API Events](#api-events)
59+
- [ledgerClosed](#ledgerclosed)
60+
- [error](#error)
5861

5962
<!-- END doctoc generated TOC please keep comment here to allow auto update -->
6063

@@ -211,7 +214,7 @@ A *transaction specification* specifies what a transaction should do. Each [Tran
211214

212215
## Payment
213216

214-
See [Transcation Types](#transaction-types) for a description.
217+
See [Transaction Types](#transaction-types) for a description.
215218

216219
Name | Type | Description
217220
---- | ---- | -----------
@@ -264,7 +267,7 @@ paths | string | *Optional* The paths of trustlines and orders to use in executi
264267

265268
## Trustline
266269

267-
See [Transcation Types](#transaction-types) for a description.
270+
See [Transaction Types](#transaction-types) for a description.
268271

269272
Name | Type | Description
270273
---- | ---- | -----------
@@ -295,7 +298,7 @@ ripplingDisabled | boolean | *Optional* If true, payments cannot ripple through
295298

296299
## Order
297300

298-
See [Transcation Types](#transaction-types) for a description.
301+
See [Transaction Types](#transaction-types) for a description.
299302

300303
Name | Type | Description
301304
---- | ---- | -----------
@@ -329,7 +332,7 @@ passive | boolean | *Optional* If enabled, the offer will not consume offers tha
329332

330333
## Order Cancellation
331334

332-
See [Transcation Types](#transaction-types) for a description.
335+
See [Transaction Types](#transaction-types) for a description.
333336

334337
Name | Type | Description
335338
---- | ---- | -----------
@@ -345,7 +348,7 @@ orderSequence | [sequence](#account-sequence-number) | The [account sequence num
345348

346349
## Settings
347350

348-
See [Transcation Types](#transaction-types) for a description.
351+
See [Transaction Types](#transaction-types) for a description.
349352

350353
Name | Type | Description
351354
---- | ---- | -----------
@@ -376,7 +379,7 @@ transferRate | number,null | *Optional* The fee to charge when users transfer t
376379

377380
## Suspended Payment Creation
378381

379-
See [Transcation Types](#transaction-types) for a description.
382+
See [Transaction Types](#transaction-types) for a description.
380383

381384
Name | Type | Description
382385
---- | ---- | -----------
@@ -425,7 +428,7 @@ memos[] | object | Memo objects represent arbitrary data that can be included in
425428

426429
## Suspended Payment Cancellation
427430

428-
See [Transcation Types](#transaction-types) for a description.
431+
See [Transaction Types](#transaction-types) for a description.
429432

430433
Name | Type | Description
431434
---- | ---- | -----------
@@ -450,7 +453,7 @@ memos[] | object | Memo objects represent arbitrary data that can be included in
450453

451454
## Suspended Payment Execution
452455

453-
See [Transcation Types](#transaction-types) for a description.
456+
See [Transaction Types](#transaction-types) for a description.
454457

455458
Name | Type | Description
456459
---- | ---- | -----------
@@ -3306,3 +3309,67 @@ return api.computeLedgerHash(ledger);
33063309
"F4D865D83EB88C1A1911B9E90641919A1314F36E1B099F8E95FE3B7C77BE3349"
33073310
```
33083311

3312+
# API Events
3313+
3314+
## ledgerClosed
3315+
3316+
This event is emitted whenever a new ledger version is validated on the connected server.
3317+
3318+
### Return Value
3319+
3320+
Name | Type | Description
3321+
---- | ---- | -----------
3322+
feeBase | integer | Base fee, in drops.
3323+
feeReference | integer | Cost of the 'reference transaction' in 'fee units'.
3324+
ledgerHash | string | Unique hash of the ledger that was closed, as hex.
3325+
ledgerTimestamp | date-time string | The time at which this ledger closed.
3326+
reserveBase | integer | The minimum reserve, in drops of XRP, that is required for an account.
3327+
reserveIncrement | integer | The increase in account reserve that is added for each item the account owns, such as offers or trust lines.
3328+
transactionCount | integer | Number of new transactions included in this ledger.
3329+
ledgerVersion | integer | Ledger version of the ledger that closed.
3330+
validatedLedgerVersions | string | Range of ledgers that the server has available. This may be discontiguous.
3331+
3332+
### Example
3333+
3334+
```javascript
3335+
api.on('ledgerClosed', ledger => {
3336+
console.log(JSON.stringify(ledger, null, 2));
3337+
});
3338+
```
3339+
3340+
3341+
```json
3342+
{
3343+
"feeBase": 10,
3344+
"feeReference": 10,
3345+
"ledgerVersion": 14804627,
3346+
"ledgerHash": "9141FA171F2C0CE63E609466AF728FF66C12F7ACD4B4B50B0947A7F3409D593A",
3347+
"ledgerTimestamp": "2015-07-23T05:50:40.000Z",
3348+
"reserveBase": 20000000,
3349+
"reserveIncrement": 5000000,
3350+
"transactionCount": 19,
3351+
"validatedLedgerVersions": "13983423-14804627"
3352+
}
3353+
```
3354+
3355+
3356+
## error
3357+
3358+
This event is emitted when there is an error on the connection to the server.
3359+
3360+
### Return Value
3361+
3362+
The first parameter is a string indicating the error type, which may be `badMessage` (meaning that rippled returned a malformed message), or one of the [rippled Universal Errors](https://ripple.com/build/rippled-apis/#universal-errors). The second parameter is a message explaining the error, or the message that caused the error in the case of `badMessage`.
3363+
3364+
### Example
3365+
3366+
```javascript
3367+
api.on('error', (errorCode, errorMessage) => {
3368+
console.log(errorCode + ': ' + errorMessage);
3369+
});
3370+
```
3371+
3372+
```
3373+
tooBusy: The server is too busy to help you now.
3374+
```
3375+

‎docs/src/events.md.ejs

+39
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
# API Events
2+
3+
## ledgerClosed
4+
5+
This event is emitted whenever a new ledger version is validated on the connected server.
6+
7+
### Return Value
8+
9+
<%- renderSchema('output/ledger-closed.json') %>
10+
11+
### Example
12+
13+
```javascript
14+
api.on('ledgerClosed', ledger => {
15+
console.log(JSON.stringify(ledger, null, 2));
16+
});
17+
```
18+
19+
<%- renderFixture('responses/ledger-closed.json') %>
20+
21+
## error
22+
23+
This event is emitted when there is an error on the connection to the server.
24+
25+
### Return Value
26+
27+
The first parameter is a string indicating the error type, which may be `badMessage` (meaning that rippled returned a malformed message), or one of the [rippled Universal Errors](https://ripple.com/build/rippled-apis/#universal-errors). The second parameter is a message explaining the error, or the message that caused the error in the case of `badMessage`.
28+
29+
### Example
30+
31+
```javascript
32+
api.on('error', (errorCode, errorMessage) => {
33+
console.log(errorCode + ': ' + errorMessage);
34+
});
35+
```
36+
37+
```
38+
tooBusy: The server is too busy to help you now.
39+
```

‎docs/src/index.md.ejs

+1
Original file line numberDiff line numberDiff line change
@@ -33,3 +33,4 @@
3333
<% include submit.md.ejs %>
3434
<% include generateAddress.md.ejs %>
3535
<% include computeLedgerHash.md.ejs %>
36+
<% include events.md.ejs %>

‎docs/src/specifications.md.ejs

+8-8
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@ A *transaction specification* specifies what a transaction should do. Each [Tran
44

55
## Payment
66

7-
See [Transcation Types](#transaction-types) for a description.
7+
See [Transaction Types](#transaction-types) for a description.
88

99
<%- renderSchema('specifications/payment.json') %>
1010

@@ -14,7 +14,7 @@ See [Transcation Types](#transaction-types) for a description.
1414

1515
## Trustline
1616

17-
See [Transcation Types](#transaction-types) for a description.
17+
See [Transaction Types](#transaction-types) for a description.
1818

1919
<%- renderSchema('specifications/trustline.json') %>
2020

@@ -24,7 +24,7 @@ See [Transcation Types](#transaction-types) for a description.
2424

2525
## Order
2626

27-
See [Transcation Types](#transaction-types) for a description.
27+
See [Transaction Types](#transaction-types) for a description.
2828

2929
<%- renderSchema('specifications/order.json') %>
3030

@@ -34,7 +34,7 @@ See [Transcation Types](#transaction-types) for a description.
3434

3535
## Order Cancellation
3636

37-
See [Transcation Types](#transaction-types) for a description.
37+
See [Transaction Types](#transaction-types) for a description.
3838

3939
<%- renderSchema('specifications/order-cancellation.json') %>
4040

@@ -44,7 +44,7 @@ See [Transcation Types](#transaction-types) for a description.
4444

4545
## Settings
4646

47-
See [Transcation Types](#transaction-types) for a description.
47+
See [Transaction Types](#transaction-types) for a description.
4848

4949
<%- renderSchema('output/get-settings.json') %>
5050

@@ -54,7 +54,7 @@ See [Transcation Types](#transaction-types) for a description.
5454

5555
## Suspended Payment Creation
5656

57-
See [Transcation Types](#transaction-types) for a description.
57+
See [Transaction Types](#transaction-types) for a description.
5858

5959
<%- renderSchema('specifications/suspended-payment-creation.json') %>
6060

@@ -64,7 +64,7 @@ See [Transcation Types](#transaction-types) for a description.
6464

6565
## Suspended Payment Cancellation
6666

67-
See [Transcation Types](#transaction-types) for a description.
67+
See [Transaction Types](#transaction-types) for a description.
6868

6969
<%- renderSchema('specifications/suspended-payment-cancellation.json') %>
7070

@@ -74,7 +74,7 @@ See [Transcation Types](#transaction-types) for a description.
7474

7575
## Suspended Payment Execution
7676

77-
See [Transcation Types](#transaction-types) for a description.
77+
See [Transaction Types](#transaction-types) for a description.
7878

7979
<%- renderSchema('specifications/suspended-payment-execution.json') %>
8080

‎src/common/schemas/output/ledger-closed.json

+42-9
Original file line numberDiff line numberDiff line change
@@ -4,15 +4,48 @@
44
"description": "A ledgerClosed event message",
55
"type": "object",
66
"properties": {
7-
"feeBase": {"type": "integer", "minimum": 0},
8-
"feeReference": {"type": "integer", "minimum": 0},
9-
"ledgerHash": {"$ref": "hash256"},
10-
"ledgerVersion": {"$ref": "ledgerVersion"},
11-
"ledgerTimestamp": {"type": "string", "format": "date-time"},
12-
"reserveBase": {"type": "integer", "minimum": 0},
13-
"reserveIncrement": {"type": "integer", "minimum": 0},
14-
"transactionCount": {"type": "integer", "minimum": 0},
15-
"validatedLedgerVersions": {"type": "string"}
7+
"feeBase": {
8+
"type": "integer",
9+
"minimum": 0,
10+
"description": "Base fee, in drops."
11+
},
12+
"feeReference": {
13+
"type": "integer",
14+
"minimum": 0,
15+
"description": "Cost of the 'reference transaction' in 'fee units'."
16+
},
17+
"ledgerHash": {
18+
"$ref": "hash256",
19+
"description": "Unique hash of the ledger that was closed, as hex."
20+
},
21+
"ledgerVersion": {
22+
"$ref": "ledgerVersion",
23+
"description": "Ledger version of the ledger that closed."
24+
},
25+
"ledgerTimestamp": {
26+
"type": "string",
27+
"format": "date-time",
28+
"description": "The time at which this ledger closed."
29+
},
30+
"reserveBase": {
31+
"type": "integer",
32+
"minimum": 0,
33+
"description": "The minimum reserve, in drops of XRP, that is required for an account."
34+
},
35+
"reserveIncrement": {
36+
"type": "integer",
37+
"minimum": 0,
38+
"description": "The increase in account reserve that is added for each item the account owns, such as offers or trust lines."
39+
},
40+
"transactionCount": {
41+
"type": "integer",
42+
"minimum": 0,
43+
"description": "Number of new transactions included in this ledger."
44+
},
45+
"validatedLedgerVersions": {
46+
"type": "string",
47+
"description": "Range of ledgers that the server has available. This may be discontiguous."
48+
}
1649
},
1750
"addtionalProperties": false,
1851
"required": ["feeBase", "feeReference", "ledgerHash", "ledgerTimestamp",

0 commit comments

Comments
 (0)