Update documentation for getTransaction() and sendTransaction() (stel…

…lar#336)
ElliotFriend · Mar 2, 2023 · d1c3a55 · d1c3a55
1 parent c3360df
commit d1c3a55
Show file tree

Hide file tree

Showing 3 changed files with 122 additions and 126 deletions.
diff --git a/api/methods/getTransaction.mdx b/api/methods/getTransaction.mdx
@@ -0,0 +1,108 @@
+---
+sidebar_position: 8
+---
+
+Clients will poll this to tell when the transaction has been completed.
+
+
+## Parameters
+
+- `<hash>` - transaction hash to query, as a hex-encoded string
+
+## Returns
+
+- `<object>`
+  - `status`: `<status>` - the current status of the transaction by hash, one of:
+    - `SUCCESS`
+    - `NOT_FOUND`
+    - `FAILED`
+  - `latestLedger`: `<string>` - The latest ledger known to Soroban-RPC at the time it handled the `getTransaction()` request.
+  - `latestLedgerCloseTime`: `<string>` - The unix timestamp of the close time of the latest ledger known to Soroban-RPC at the time it handled the `getTransaction()` request.
+  - `oldestLedger`: `<string>` - The oldest ledger ingested by Soroban-RPC at the time it handled the `getTransaction()` request.
+  - `oldestLedgerCloseTime`: `<string>` - The unix timestamp of the close time of the oldest ledger ingested by Soroban-RPC at the time it handled the `getTransaction()` request.
+  - `ledger`: `<string>` - (optional) The sequence of the ledger which included the transaction. This field is only present if `status` is `SUCCESS` or `FAILED`.
+  - `createdAt`: `<string>` - (optional) The unix timestamp of when the transaction was included in the ledger. This field is only present if `status` is `SUCCESS` or `FAILED`.
+  - `applicationOrder`: `<number>` - (optional) The index of the transaction among all transactions included in the ledger. This field is only present if `status` is `SUCCESS` or `FAILED`.
+  - `feeBump`: `<boolean>` - (optional) Indicates whether the transaction was fee bumped. This field is only present if `status` is `SUCCESS` or `FAILED`.
+  - `envelopeXdr`: `<xdr.TransactionEnvelope>` - (optional) A base64 encoded string of the raw TransactionEnvelope XDR struct for this transaction.
+  - `resultXdr`: `<xdr.TransactionResult>` - (optional) A base64 encoded string of the raw TransactionResult XDR struct for this transaction. This field is only present if `status` is `SUCCESS` or `FAILED`.
+  - `resultMetaXdr`: `<xdr.TransactionResultMeta>` - (optional) A base64 encoded string of the raw TransactionResultMeta XDR struct for this transaction.
+
+## Examples
+
+### Request
+
+```json
+{
+    "jsonrpc": "2.0",
+    "id": 8675309,
+    "method": "getTransactionStatus",
+    "params": {
+        "hash": "97eb77da26e21d6a032fc0c311831d94a702ba336037da7c8a5ec51b3e39c485"
+    }
+}
+```
+
+### Response
+
+#### Not Found
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 8675309,
+  "result": {
+    "status": "NOT_FOUND",
+    "latestLedger": "45075181",
+    "latestLedgerCloseTime": "1677115742",
+    "oldestLedger": "45070000",
+    "latestLedgerCloseTime": "1677000000"
+  }
+}
+```
+
+#### Success
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 8675309,
+  "result": {
+    "status": "SUCCESS",
+    "latestLedger": "45075181",
+    "latestLedgerCloseTime": "1677115742",
+    "oldestLedger": "45070000",
+    "latestLedgerCloseTime": "1677000000",
+    "ledger": "45070700",
+    "createdAt": "1677009000",
+    "applicationOrder": 1,
+    "feeBump": false,
+    "envelope_xdr": "AAAAAgAAAAC+B6dP3Y3Dk7cO+EXButf4j/a6NgZ8jhUdGd8Y4DLK1QAAJxMB1QqkAGOQiwAAAAEAAAAAAAAAAAAAAABkAG82AAAAAAAAAAEAAAAAAAAAAwAAAAAAAAABRVRYAAAAAACIVkm2vMC7wfGBUXcyyT5KMkEhZr0TEHmgyspvSQ+skwAAAAAFSbLgKG8eYQCUWuIAAAAAR3McdwAAAAAAAAAB4DLK1QAAAEDJvETQ3zLdr1RXE4KEQ+tlmWPh6zpFu/KrAQOrYrYSxpbhB5DPZRJnn+ROtU8TnZhZ6xQ136VrqNQm/+LUOD8D",
+    "resultXdr": "AAAAAAAAAGQAAAAAAAAAAQAAAAAAAAAMAAAAAAAAAAAAAAABAAAAAK36IZP1oM+KV7lU1u8H7BgGjwK6d6hPmU+zpA6rySi3AAAAAEbEAZ4AAAAAAAAAAVJCUk4AAAAArSYZWZeBIAHn1+M0WPwhehxZNiBgvJOx7IVykVOo39UAAAAAFZRBZACYloAAAAANAAAAAAAAAAAAAAAA",
+    "result_meta_xdr": "AAAAAgAAAAIAAAADArFrdQAAAAAAAAAAvgenT92Nw5O3DvhFwbrX+I/2ujYGfI4VHRnfGOAyytUAAAAADH94VAHVCqQAY5CKAAAACAAAAAAAAAAAAAAAAAEAAAAAAAAAAAAAAQAAAAEzXjfgAAAAAAVJxmgAAAACAAAAAAAAAAAAAAAAAAAAAwAAAAACsWtzAAAAAGQAbxMAAAAAAAAAAQKxa3UAAAAAAAAAAL4Hp0/djcOTtw74RcG61/iP9ro2BnyOFR0Z3xjgMsrVAAAAAAx/eFQB1QqkAGOQiwAAAAgAAAAAAAAAAAAAAAABAAAAAAAAAAAAAAEAAAABM1434AAAAAAFScZoAAAAAgAAAAAAAAAAAAAAAAAAAAMAAAAAArFrdQAAAABkAG8eAAAAAAAAAAEAAAAGAAAAAwKxa3MAAAACAAAAAL4Hp0/djcOTtw74RcG61/iP9ro2BnyOFR0Z3xjgMsrVAAAAAEdzHHcAAAAAAAAAAUVUWAAAAAAAiFZJtrzAu8HxgVF3Msk+SjJBIWa9ExB5oMrKb0kPrJMAAAAABUnGaHLv1t0BpbXWAAAAAAAAAAAAAAAAAAAAAQKxa3UAAAACAAAAAL4Hp0/djcOTtw74RcG61/iP9ro2BnyOFR0Z3xjgMsrVAAAAAEdzHHcAAAAAAAAAAUVUWAAAAAAAiFZJtrzAu8HxgVF3Msk+SjJBIWa9ExB5oMrKb0kPrJMAAAAABUmy4ChvHmEAlFriAAAAAAAAAAAAAAAAAAAAAwKxa3UAAAAAAAAAAL4Hp0/djcOTtw74RcG61/iP9ro2BnyOFR0Z3xjgMsrVAAAAAAx/eFQB1QqkAGOQiwAAAAgAAAAAAAAAAAAAAAABAAAAAAAAAAAAAAEAAAABM1434AAAAAAFScZoAAAAAgAAAAAAAAAAAAAAAAAAAAMAAAAAArFrdQAAAABkAG8eAAAAAAAAAAECsWt1AAAAAAAAAAC+B6dP3Y3Dk7cO+EXButf4j/a6NgZ8jhUdGd8Y4DLK1QAAAAAMf3hUAdUKpABjkIsAAAAIAAAAAAAAAAAAAAAAAQAAAAAAAAAAAAABAAAAATNeN+AAAAAABUmy4AAAAAIAAAAAAAAAAAAAAAAAAAADAAAAAAKxa3UAAAAAZABvHgAAAAAAAAADArFrcwAAAAEAAAAAvgenT92Nw5O3DvhFwbrX+I/2ujYGfI4VHRnfGOAyytUAAAABRVRYAAAAAACIVkm2vMC7wfGBUXcyyT5KMkEhZr0TEHmgyspvSQ+skwAAAE+W7pTjf/////////8AAAABAAAAAQAAAAFw+HPyAAAARkSap3YAAAAAAAAAAAAAAAECsWt1AAAAAQAAAAC+B6dP3Y3Dk7cO+EXButf4j/a6NgZ8jhUdGd8Y4DLK1QAAAAFFVFgAAAAAAIhWSba8wLvB8YFRdzLJPkoyQSFmvRMQeaDKym9JD6yTAAAAT5bulON//////////wAAAAEAAAABAAAAAXDzHW4AAABGRJqndgAAAAAAAAAAAAAAAA=="
+  }
+}
+```
+
+#### Failed
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 8675309,
+  "result": {
+    "status": "FAILED",
+    "latestLedger": "45075181",
+    "latestLedgerCloseTime": "1677115742",
+    "oldestLedger": "45070000",
+    "latestLedgerCloseTime": "1677000000",
+    "ledger": "45070700",
+    "createdAt": "1677009000",
+    "applicationOrder": 1,
+    "feeBump": false,
+    "envelope_xdr": "AAAAAgAAAAC+B6dP3Y3Dk7cO+EXButf4j/a6NgZ8jhUdGd8Y4DLK1QAAJxMB1QqkAGOQiwAAAAEAAAAAAAAAAAAAAABkAG82AAAAAAAAAAEAAAAAAAAAAwAAAAAAAAABRVRYAAAAAACIVkm2vMC7wfGBUXcyyT5KMkEhZr0TEHmgyspvSQ+skwAAAAAFSbLgKG8eYQCUWuIAAAAAR3McdwAAAAAAAAAB4DLK1QAAAEDJvETQ3zLdr1RXE4KEQ+tlmWPh6zpFu/KrAQOrYrYSxpbhB5DPZRJnn+ROtU8TnZhZ6xQ136VrqNQm/+LUOD8D",
+    "resultXdr": "AAAAAAAAAGT////7AAAAAA==",
+    "result_meta_xdr": "AAAAAgAAAAIAAAADArFrdQAAAAAAAAAAvgenT92Nw5O3DvhFwbrX+I/2ujYGfI4VHRnfGOAyytUAAAAADH94VAHVCqQAY5CKAAAACAAAAAAAAAAAAAAAAAEAAAAAAAAAAAAAAQAAAAEzXjfgAAAAAAVJxmgAAAACAAAAAAAAAAAAAAAAAAAAAwAAAAACsWtzAAAAAGQAbxMAAAAAAAAAAQKxa3UAAAAAAAAAAL4Hp0/djcOTtw74RcG61/iP9ro2BnyOFR0Z3xjgMsrVAAAAAAx/eFQB1QqkAGOQiwAAAAgAAAAAAAAAAAAAAAABAAAAAAAAAAAAAAEAAAABM1434AAAAAAFScZoAAAAAgAAAAAAAAAAAAAAAAAAAAMAAAAAArFrdQAAAABkAG8eAAAAAAAAAAEAAAAGAAAAAwKxa3MAAAACAAAAAL4Hp0/djcOTtw74RcG61/iP9ro2BnyOFR0Z3xjgMsrVAAAAAEdzHHcAAAAAAAAAAUVUWAAAAAAAiFZJtrzAu8HxgVF3Msk+SjJBIWa9ExB5oMrKb0kPrJMAAAAABUnGaHLv1t0BpbXWAAAAAAAAAAAAAAAAAAAAAQKxa3UAAAACAAAAAL4Hp0/djcOTtw74RcG61/iP9ro2BnyOFR0Z3xjgMsrVAAAAAEdzHHcAAAAAAAAAAUVUWAAAAAAAiFZJtrzAu8HxgVF3Msk+SjJBIWa9ExB5oMrKb0kPrJMAAAAABUmy4ChvHmEAlFriAAAAAAAAAAAAAAAAAAAAAwKxa3UAAAAAAAAAAL4Hp0/djcOTtw74RcG61/iP9ro2BnyOFR0Z3xjgMsrVAAAAAAx/eFQB1QqkAGOQiwAAAAgAAAAAAAAAAAAAAAABAAAAAAAAAAAAAAEAAAABM1434AAAAAAFScZoAAAAAgAAAAAAAAAAAAAAAAAAAAMAAAAAArFrdQAAAABkAG8eAAAAAAAAAAECsWt1AAAAAAAAAAC+B6dP3Y3Dk7cO+EXButf4j/a6NgZ8jhUdGd8Y4DLK1QAAAAAMf3hUAdUKpABjkIsAAAAIAAAAAAAAAAAAAAAAAQAAAAAAAAAAAAABAAAAATNeN+AAAAAABUmy4AAAAAIAAAAAAAAAAAAAAAAAAAADAAAAAAKxa3UAAAAAZABvHgAAAAAAAAADArFrcwAAAAEAAAAAvgenT92Nw5O3DvhFwbrX+I/2ujYGfI4VHRnfGOAyytUAAAABRVRYAAAAAACIVkm2vMC7wfGBUXcyyT5KMkEhZr0TEHmgyspvSQ+skwAAAE+W7pTjf/////////8AAAABAAAAAQAAAAFw+HPyAAAARkSap3YAAAAAAAAAAAAAAAECsWt1AAAAAQAAAAC+B6dP3Y3Dk7cO+EXButf4j/a6NgZ8jhUdGd8Y4DLK1QAAAAFFVFgAAAAAAIhWSba8wLvB8YFRdzLJPkoyQSFmvRMQeaDKym9JD6yTAAAAT5bulON//////////wAAAAEAAAABAAAAAXDzHW4AAABGRJqndgAAAAAAAAAAAAAAAA=="
+  }
+}
+```
diff --git a/api/methods/getTransactionStatus.mdx b/api/methods/getTransactionStatus.mdx
diff --git a/api/methods/sendTransaction.mdx b/api/methods/sendTransaction.mdx
@@ -4,30 +4,26 @@ sidebar_position: 10
 
 Submit a real transaction to the Stellar network. This is the only way to make changes "on-chain".
 
-Unlike Horizon, this does not wait for transaction completion. It simply validates and enqueues the transaction. Clients should call getTransactionStatus to learn about transaction success/failure.
+Unlike Horizon, this does not wait for transaction completion. It simply validates and enqueues the transaction. Clients should call getTransaction to learn about transaction success/failure.
 
 This supports all transactions, not only smart contract-related transactions.
 
-- TODO: Decide on submit-vs-send for naming
-- TODO: Add a return value that would represent the minimal amount of time the client would need to wait before calling getTransactionStatus
-
 ## Parameters
 
 - `<xdr.TransactionEnvelope>` - The signed transaction to broadcast (serialized in base64)
 
 ## Returns
 
 - `<object>`
-  - `id`: `<hash>` The transaction hash (in an hex-encoded string), and the initial transaction status, ("pending" or something), unless we can reject it immediately.
-  - `status`: `<status>` - the current status of the transaction by hash, one of:
-    - `pending`
-    - `success`
-    - `error`
-  - `error`: `<object>` -  (optional) If the transaction was rejected immediately, this will be an error object. See [`getTransactionStatus`](getTransactionStatus) for format.
-
-## Possible Errors
-
-- TODO: Fewer than existing txsub as not waiting for completion
+  - `hash`: `<hash>` The transaction hash (in an hex-encoded string).
+  - `status`: `<status>` - The current status of the transaction by hash, one of:
+    - `PENDING` - The transaction has been accepted by stellar-core.
+    - `DUPLICATE` - The transaction has already been submitted to stellar-core.
+    - `TRY_AGAIN_LATER` - The transaction was not included in the previous 4 ledgers and is banned from the next few ledgers.
+    - `ERROR` - An error occurred from submitting the transaction to stellar-core.
+  - `latestLedger`: `<string>` - The latest ledger known to Soroban-RPC at the time it handled the `sendTransaction()` request.
+  - `latestLedgerCloseTime`: `<string>` - The unix timestamp of the close time of the latest ledger known to Soroban-RPC at the time it handled the `sendTransaction()` request.
+  - `errorResultXdr`: `<xdr.TransactionResult>` -  (optional) If the transaction status is `ERROR`, this will be a base64 encoded string of the raw TransactionResult XDR struct containing details on why stellar-core rejected the transaction.
 
 ## Examples
 
@@ -53,9 +49,10 @@ The following example request uses a transaction to invoke the `increment` metho
   "jsonrpc": "2.0",
   "id": 8675309,
   "result": {
-    "id": "d70916f8b8aa55c13d5974a38e32a3efe440ef6870c0f0a07075d1c128d23698",
-    "status": "pending",
-    "error": null
+    "hash": "d70916f8b8aa55c13d5974a38e32a3efe440ef6870c0f0a07075d1c128d23698",
+    "status": "PENDING",
+    "latestLedger": "45075181",
+    "latestLedgerCloseTime": "1677115742"
   }
 }
 ```