mirror of
https://github.com/Xahau/xahau.js.git
synced 2025-12-06 17:27:59 +00:00
4ab808b6de
Using request('submit', ...) allows the ripple-lib API to be effectively
identical to the underlying rippled API. Whereas submit() returns only
certain fields from rippled, using request('submit') gives you rippled's
full response, including the new fields added in rippled v1.5.0.
84 lines
7.5 KiB
Plaintext
84 lines
7.5 KiB
Plaintext
## submit
|
|
|
|
`request('submit', {tx_blob: string, fail_hard: boolean}): Promise<object>`
|
|
|
|
The `submit` method applies a transaction and sends it to the network to be confirmed and included in future ledgers.
|
|
|
|
This method takes a signed, serialized transaction as a binary blob, and submits it to the network as-is. Since signed transaction objects are immutable, no part of the transaction can be modified or automatically filled in after submission.
|
|
|
|
To send a transaction as robustly as possible, you should construct and sign it in advance, persist it somewhere that you can access even after a power outage, then `submit` it as a `tx_blob`. After submission, monitor the network with the `tx` method to see if the transaction was successfully applied; if a restart or other problem occurs, you can safely re-submit the `tx_blob` transaction: it won't be applied twice since it has the same sequence number as the old transaction.
|
|
|
|
### Parameters
|
|
|
|
| `Field` | Type | Description |
|
|
|:------------|:--------|:-----------------------------------------------------|
|
|
| `tx_blob` | String | Hex representation of the signed transaction to submit. This can be a multi-signed transaction. |
|
|
| `fail_hard` | Boolean | (Optional, defaults to false) If true, and the transaction fails locally, do not retry or relay the transaction to other servers |
|
|
|
|
### Return Value
|
|
|
|
When successful, this method returns an object containing the following fields:
|
|
|
|
| `Field` | Type | Description |
|
|
|:------------------------|:--------|:-----------------------------------------|
|
|
| `engine_result` | String | Text [result code](https://xrpl.org/transaction-results.html) indicating the preliminary result of the transaction, for example `tesSUCCESS` |
|
|
| `engine_result_code` | Integer | Numeric version of the [result code](https://xrpl.org/transaction-results.html). **Not recommended.** |
|
|
| `engine_result_message` | String | Human-readable explanation of the transaction's preliminary result |
|
|
| `tx_blob` | String | The complete transaction in hex string format |
|
|
| `tx_json` | Object | The complete transaction in JSON format |
|
|
| `accepted` | Boolean | The value `true` indicates that the transaction was applied, queued, broadcast, or kept for later. The value `false` indicates that none of those happened, so the transaction cannot possibly succeed as long as you do not submit it again and have not already submitted it another time. [New in: rippled 1.5.0] |
|
|
| `account_sequence_available` | Number | The next [Sequence Number](https://xrpl.org/basic-data-types.html#account-sequence) available for the sending account after all pending and [queued](https://xrpl.org/transaction-queue.html) transactions. [New in: rippled 1.5.0] |
|
|
| `account_sequence_next` | number | The next [Sequence Number](https://xrpl.org/basic-data-types.html#account-sequence) for the sending account after all transactions that have been provisionally applied, but not transactions in the [queue](https://xrpl.org/transaction-queue.html). [New in: rippled 1.5.0] |
|
|
| `applied` | Boolean | The value `true` indicates that this transaction was applied to the open ledger. In this case, the transaction is likely, but not guaranteed, to be validated in the next ledger version. [New in: rippled 1.5.0] |
|
|
| `broadcast` | Boolean | The value `true` indicates this transaction was broadcast to peer servers in the peer-to-peer XRP Ledger network. (Note: if the server has no peers, such as in [stand-alone mode](https://xrpl.org/rippled-server-modes.html#reasons-to-run-a-rippled-server-in-stand-alone-mode), the server uses the value `true` for cases where it _would_ have broadcast the transaction.) The value `false` indicates the transaction was not broadcast to any other servers. [New in: rippled 1.5.0] |
|
|
| `kept` | Boolean | The value `true` indicates that the transaction was kept to be retried later. [New in: rippled 1.5.0] |
|
|
| `queued` | Boolean | The value `true` indicates the transaction was put in the [Transaction Queue](https://xrpl.org/transaction-queue.html), which means it is likely to be included in a future ledger version. [New in: rippled 1.5.0] |
|
|
| `open_ledger_cost` | String | The current [open ledger cost](https://xrpl.org/transaction-cost.html#open-ledger-cost) before processing this transaction. Transactions with a lower cost are likely to be [queued](https://xrpl.org/transaction-queue.html). [New in: rippled 1.5.0] |
|
|
| `validated_ledger_index` | Integer | The [ledger index](https://xrpl.org/basic-data-types.html#ledger-index) of the newest validated ledger at the time of submission. This provides a lower bound on the ledger versions that the transaction can appear in as a result of this request. (The transaction could only have been validated in this ledger version or earlier if it had already been submitted before.) |
|
|
|
|
Note: Many situations can prevent a transaction from processing successfully, such as a lack of trust lines connecting the two accounts in a payment, or changes in the state of the ledger since the time the transaction was constructed. Even if nothing is wrong, it may take several seconds to close and validate the ledger version that includes the transaction. Do not consider the transaction's results final until they appear in a validated ledger version.
|
|
|
|
### Example
|
|
|
|
```javascript
|
|
const signedTransaction = '12000022800000002400000007201B007008BC61400000000754D4C068400000000000000C732103E8110048477E60F292DEDA67CF518511E70A15E1E3771B3C024026E1F824832874473045022100D659C836C24FF346A87054E463078D805B19EFE9F10348FD4C6ED6C3F3C4D750022060BE0BFD5E2C4963A1B0E0F21D5BA800969863BA486F71E75C08D76D77C45B22811492F80A3F3849DBB5714A4F2C691CE7D47BEED58083141266204CFBC657E65D9B4D30301FF98644693935';
|
|
const failHard = false;
|
|
const result = await api.request('submit', {
|
|
tx_blob: signedTransaction,
|
|
fail_hard: failHard // optional
|
|
});
|
|
```
|
|
|
|
```json
|
|
{
|
|
"accepted": true,
|
|
"account_sequence_available": 8,
|
|
"account_sequence_next": 8,
|
|
"applied": true,
|
|
"broadcast": true,
|
|
"engine_result": "tesSUCCESS",
|
|
"engine_result_code": 0,
|
|
"engine_result_message": "The transaction was applied. Only final in a validated ledger.",
|
|
"kept": true,
|
|
"open_ledger_cost": "10",
|
|
"queued": false,
|
|
"tx_blob": "12000022800000002400000007201B007008BC61400000000754D4C068400000000000000C732103E8110048477E60F292DEDA67CF518511E70A15E1E3771B3C024026E1F824832874473045022100D659C836C24FF346A87054E463078D805B19EFE9F10348FD4C6ED6C3F3C4D750022060BE0BFD5E2C4963A1B0E0F21D5BA800969863BA486F71E75C08D76D77C45B22811492F80A3F3849DBB5714A4F2C691CE7D47BEED58083141266204CFBC657E65D9B4D30301FF98644693935",
|
|
"tx_json": {
|
|
"Account": "rNQao3Z1irwRjKWSs8heL4a8WKLPKfLrXs",
|
|
"Amount": "123000000",
|
|
"Destination": "rpgHWJdXkSvvzikdJCpuMzU7zWnuqsJRCZ",
|
|
"Fee": "12",
|
|
"Flags": 2147483648,
|
|
"LastLedgerSequence": 7342268,
|
|
"Sequence": 7,
|
|
"SigningPubKey": "03E8110048477E60F292DEDA67CF518511E70A15E1E3771B3C024026E1F8248328",
|
|
"TransactionType": "Payment",
|
|
"TxnSignature": "3045022100D659C836C24FF346A87054E463078D805B19EFE9F10348FD4C6ED6C3F3C4D750022060BE0BFD5E2C4963A1B0E0F21D5BA800969863BA486F71E75C08D76D77C45B22",
|
|
"hash": "FE8D68D7FF5805EB07AF15A1ADF07FB5463CCD2C6C0A15981EB3D26A02E1551C"
|
|
},
|
|
"validated_ledger_index": 7341775
|
|
}
|
|
```
|
|
|
|
(In ripple-lib 1.8.0, [the old `submit` method](https://github.com/ripple/ripple-lib/blob/1.7.0/docs/index.md#submit) was deprecated.)
|