ARCHIVE/xahau.js
1
0
Fork 0
mirror of https://github.com/Xahau/xahau.js.git synced 2025-11-19 19:55:51 +00:00
Code Issues Packages Projects Releases Wiki Activity

fix(docs): Update docs

Browse Source
This commit is contained in:
Javi
2020-11-06 11:23:14 +01:00
parent 9f6fa6a4fd
commit 81dfd99642
9 changed files with 141 additions and 6 deletions
Download Patch File Download Diff File Expand all files Collapse all files

65
docs/index.md
View File

@@ -78,6 +78,7 @@
- [prepareCheckCreate](#preparecheckcreate)
- [prepareCheckCancel](#preparecheckcancel)
- [prepareCheckCash](#preparecheckcash)
- [prepareTicket](#prepareticket)
- [sign](#sign)
- [combine](#combine)
- [submit](#submit)
@@ -249,7 +250,7 @@ An *X-address* encodes a hash of the account's public key, a tag, and a checksum
## Account Sequence Number
Every XRP Ledger account has a *sequence number* that is used to keep transactions in order. Every transaction must have a sequence number. A transaction can only be executed if it has the next sequence number in order, of the account sending it. This prevents one transaction from executing twice and transactions executing out of order. The sequence number starts at `1` and increments for each transaction that the account makes.
Every XRP Ledger account has a *sequence number* that is used to keep transactions in order. Every transaction must have a sequence or a ticketSequence number. A transaction can only be executed if it has the next sequence number in order, of the account sending it, or uses a previously generated ticketSequence number. This prevents one transaction from executing twice and transactions executing out of order. The sequence number starts at `1` and increments for each transaction that the account makes.
## Currency
@@ -319,6 +320,7 @@ Type | Description
[paymentChannelCreate](#payment-channel-create) | A `paymentChannelCreate` transaction opens a payment channel between two addresses with XRP set aside for asynchronous payments.
[paymentChannelFund](#payment-channel-fund) | A `paymentChannelFund` transaction adds XRP to a payment channel and optionally sets a new expiration for the channel.
[paymentChannelClaim](#payment-channel-claim) | A `paymentChannelClaim` transaction withdraws XRP from a channel and optionally requests to close it.
[ticketCreate](#ticket-create) | A successful `ticketCreate` transaction adds a Ticket in the directory of the owning account.
## Transaction Flow
@@ -336,6 +338,7 @@ Executing a transaction with `RippleAPI` requires the following four steps:
* [prepareCheckCreate](#preparecheckcreate)
* [prepareCheckCancel](#preparecheckcancel)
* [prepareCheckCash](#preparecheckcash)
* [prepareTicket](#prepareticket)
2. [Sign](#sign) - Cryptographically sign the transaction locally and save the [transaction ID](#transaction-id). Signing is how the owner of an account authorizes a transaction to take place. For multisignature transactions, the `signedTransaction` fields returned by `sign` must be collected and passed to the [combine](#combine) method.
3. [Submit](#submit) - Submit the transaction to the connected server.
4. Verify - Verify that the transaction got validated by querying with [getTransaction](#gettransaction). This is necessary because transactions may fail even if they were successfully submitted.
@@ -359,9 +362,9 @@ maxFee | [value](#value) | *Optional* Deprecated: Use `maxFeeXRP` in the RippleA
maxLedgerVersion | integer,null | *Optional* The highest ledger version that the transaction can be included in. If this option and `maxLedgerVersionOffset` are both omitted, the `maxLedgerVersion` option will default to 3 greater than the current validated ledger version (equivalent to `maxLedgerVersionOffset=3`). Use `null` to not set a maximum ledger version. If not null, this must be an integer greater than 0, or one of the following strings: 'validated', 'closed', 'current'.
maxLedgerVersion | string,null | *Optional* The highest ledger version that the transaction can be included in. If this option and `maxLedgerVersionOffset` are both omitted, the `maxLedgerVersion` option will default to 3 greater than the current validated ledger version (equivalent to `maxLedgerVersionOffset=3`). Use `null` to not set a maximum ledger version. If not null, this must be an integer greater than 0, or one of the following strings: 'validated', 'closed', 'current'.
maxLedgerVersionOffset | integer | *Optional* Offset from current validated ledger version to highest ledger version that the transaction can be included in.
sequence | [sequence](#account-sequence-number) | *Optional* The initiating account's sequence number for this transaction.
sequence | [sequence](#account-sequence-number) | *Optional* The initiating account's sequence number for this transaction. `sequence` and `ticketSequence` are mutually exclusive, only one of them can be set.
signersCount | integer | *Optional* Number of signers that will be signing this transaction.
ticketSequence | [ticket-sequence](#account-sequence-number) | *Optional* The ticket sequence to be used for this transaction.
ticketSequence | [ticket-sequence](#account-sequence-number) | *Optional* The ticket sequence to be used for this transaction. `sequence` and `ticketSequence` are mutually exclusive, only one of them can be set.
We recommend that you specify a `maxLedgerVersion` so that you can quickly determine that a failed transaction will never succeed in the future. It is impossible for a transaction to succeed after the XRP Ledger's consensus-validated ledger version exceeds the transaction's `maxLedgerVersion`. If you omit `maxLedgerVersion`, the "prepare\*" method automatically supplies a `maxLedgerVersion` equal to the current ledger plus 3, which it includes in the return value from the "prepare\*" method.
@@ -5458,6 +5461,62 @@ return api.prepareCheckCash(address, checkCash).then(prepared =>
```
## prepareTicket
`prepareTicket(address: string, ticketCount: number, instructions: object): Promise<object>`
Prepare a ticket transaction. The prepared transaction must subsequently be [signed](#sign) and [submitted](#submit).
### Parameters
Name | Type | Description
---- | ---- | -----------
address | [address](#address) | The address of the account that is creating the transaction.
ticketCount | number | The number of tickets to be created.
instructions | [instructions](#transaction-instructions) | *Optional* Instructions for executing the transaction
### Return Value
This method returns a promise that resolves with an object with the following structure:
<aside class="notice">
All "prepare*" methods have the same return type.
</aside>
Name | Type | Description
---- | ---- | -----------
txJSON | string | The prepared transaction in rippled JSON format.
instructions | object | The instructions for how to execute the transaction after adding automatic defaults.
*instructions.* fee | [value](#value) | The fee to pay for the transaction. See [Transaction Fees](#transaction-fees) for more information. For multi-signed transactions, this fee will be multiplied by (N+1), where N is the number of signatures you plan to provide.
*instructions.* maxLedgerVersion | integer,null | The highest ledger version that the transaction can be included in. Set to `null` if there is no maximum. If not null, this must be an integer greater than 0, or one of the following strings: 'validated', 'closed', 'current'.
*instructions.* maxLedgerVersion | string,null | The highest ledger version that the transaction can be included in. Set to `null` if there is no maximum. If not null, this must be an integer greater than 0, or one of the following strings: 'validated', 'closed', 'current'.
*instructions.* sequence | [sequence](#account-sequence-number) | *Optional* The initiating account's sequence number for this transaction.
*instructions.* ticketSequence | [ticket-sequence](#account-sequence-number) | *Optional* The initiating account's ticket sequence number for this transaction.
### Example
```javascript
const address = 'r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59';
return api.prepareTicket(address, 2).then(prepared => {
/* ... */
}).catch(error => {
/* ... as with all prepare* methods, use a Promise catch block to handle errors ... */
})
```
```json
{
"TransactionType": "TicketCreate",
"Account": "r4SDqUD1ZcfoZrhnsZ94XNFKxYL4oHYJyA",
"TicketCount": 2,
"LastLedgerSequence": 13,
"Fee": "12",
"Sequence": 25
}
```
## sign
```

2
docs/samples/README.md
View File

@@ -1,3 +1,5 @@
Usage:
babel-node balances.js
babel-node cancelall.js (requires setting address and secret in source file first)
babel-node payment.js (requires setting address and secret in source file first)
babel-node ticket.js (requires setting address and secret in source file first)

31
docs/samples/ticket.js Normal file
View File

@@ -0,0 +1,31 @@
'use strict';
const RippleAPI = require('../../src').RippleAPI; // require('ripple-lib')
const address = 'INSERT ADDRESS HERE';
const secret = 'INSERT SECRET HERE';
const api = new RippleAPI({server: 'wss://s1.ripple.com:443'});
const instructions = {
maxLedgerVersionOffset: 5
};
const numberOfTickets = 1;
function quit(message) {
console.log(message);
process.exit(0);
}
function fail(message) {
console.error(message);
process.exit(1);
}
api.connect().then(() => {
console.log('Connected...');
return api.prepareTicket(address, numberOfTickets, instructions).then(prepared => {
console.log('Ticket transaction prepared...');
const {signedTransaction} = api.sign(prepared.txJSON, secret);
console.log('Ticket transaction signed...');
api.submit(signedTransaction).then(quit, fail);
});
}).catch(fail);

2
docs/src/basictypes.md.ejs
View File

@@ -22,7 +22,7 @@ An *X-address* encodes a hash of the account's public key, a tag, and a checksum
## Account Sequence Number
Every XRP Ledger account has a *sequence number* that is used to keep transactions in order. Every transaction must have a sequence number. A transaction can only be executed if it has the next sequence number in order, of the account sending it. This prevents one transaction from executing twice and transactions executing out of order. The sequence number starts at `1` and increments for each transaction that the account makes.
Every XRP Ledger account has a *sequence number* that is used to keep transactions in order. Every transaction must have a sequence or a ticketSequence number. A transaction can only be executed if it has the next sequence number in order, of the account sending it, or uses a previously generated ticketSequence number. This prevents one transaction from executing twice and transactions executing out of order. The sequence number starts at `1` and increments for each transaction that the account makes.
## Currency

1
docs/src/index.md.ejs
View File

@@ -49,6 +49,7 @@
<%- include('prepareCheckCreate.md.ejs') %>
<%- include('prepareCheckCancel.md.ejs') %>
<%- include('prepareCheckCash.md.ejs') %>
<%- include('prepareTicket.md.ejs') %>
<%- include('sign.md.ejs') %>
<%- include('combine.md.ejs') %>
<%- include('submit.md.ejs') %>

32
docs/src/prepareTicket.md.ejs Normal file
View File

@@ -0,0 +1,32 @@
## prepareTicket
`prepareTicket(address: string, ticketCount: number, instructions: object): Promise<object>`
Prepare a ticket transaction. The prepared transaction must subsequently be [signed](#sign) and [submitted](#submit).
### Parameters
<%- renderSchema("input/prepare-ticket.json") %>
### Return Value
This method returns a promise that resolves with an object with the following structure:
<aside class="notice">
All "prepare*" methods have the same return type.
</aside>
<%- renderSchema("output/prepare.json") %>
### Example
```javascript
const address = 'r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59';
return api.prepareTicket(address, 2).then(prepared => {
/* ... */
}).catch(error => {
/* ... as with all prepare* methods, use a Promise catch block to handle errors ... */
})
```
<%- renderFixture("responses/prepare-ticket.json") %>

2
docs/src/transactions.md.ejs
View File

@@ -20,6 +20,7 @@ Type | Description
[paymentChannelCreate](#payment-channel-create) | A `paymentChannelCreate` transaction opens a payment channel between two addresses with XRP set aside for asynchronous payments.
[paymentChannelFund](#payment-channel-fund) | A `paymentChannelFund` transaction adds XRP to a payment channel and optionally sets a new expiration for the channel.
[paymentChannelClaim](#payment-channel-claim) | A `paymentChannelClaim` transaction withdraws XRP from a channel and optionally requests to close it.
[ticketCreate](#ticket-create) | A successful `ticketCreate` transaction adds a Ticket in the directory of the owning account.
## Transaction Flow
@@ -37,6 +38,7 @@ Executing a transaction with `RippleAPI` requires the following four steps:
* [prepareCheckCreate](#preparecheckcreate)
* [prepareCheckCancel](#preparecheckcancel)
* [prepareCheckCash](#preparecheckcash)
* [prepareTicket](#prepareticket)
2. [Sign](#sign) - Cryptographically sign the transaction locally and save the [transaction ID](#transaction-id). Signing is how the owner of an account authorizes a transaction to take place. For multisignature transactions, the `signedTransaction` fields returned by `sign` must be collected and passed to the [combine](#combine) method.
3. [Submit](#submit) - Submit the transaction to the connected server.
4. Verify - Verify that the transaction got validated by querying with [getTransaction](#gettransaction). This is necessary because transactions may fail even if they were successfully submitted.