From d1c3a551ab92a7697d77b07a5e234fb68aac9faa Mon Sep 17 00:00:00 2001 From: tamirms Date: Thu, 2 Mar 2023 20:11:49 +0000 Subject: [PATCH] Update documentation for getTransaction() and sendTransaction() (#336) --- api/methods/getTransaction.mdx | 108 ++++++++++++++++++++++++++ api/methods/getTransactionStatus.mdx | 109 --------------------------- api/methods/sendTransaction.mdx | 31 ++++---- 3 files changed, 122 insertions(+), 126 deletions(-) create mode 100644 api/methods/getTransaction.mdx delete mode 100644 api/methods/getTransactionStatus.mdx diff --git a/api/methods/getTransaction.mdx b/api/methods/getTransaction.mdx new file mode 100644 index 000000000..28faec07f --- /dev/null +++ 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 + +- `` - transaction hash to query, as a hex-encoded string + +## Returns + +- `` + - `status`: `` - the current status of the transaction by hash, one of: + - `SUCCESS` + - `NOT_FOUND` + - `FAILED` + - `latestLedger`: `` - The latest ledger known to Soroban-RPC at the time it handled the `getTransaction()` request. + - `latestLedgerCloseTime`: `` - The unix timestamp of the close time of the latest ledger known to Soroban-RPC at the time it handled the `getTransaction()` request. + - `oldestLedger`: `` - The oldest ledger ingested by Soroban-RPC at the time it handled the `getTransaction()` request. + - `oldestLedgerCloseTime`: `` - The unix timestamp of the close time of the oldest ledger ingested by Soroban-RPC at the time it handled the `getTransaction()` request. + - `ledger`: `` - (optional) The sequence of the ledger which included the transaction. This field is only present if `status` is `SUCCESS` or `FAILED`. + - `createdAt`: `` - (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`: `` - (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`: `` - (optional) Indicates whether the transaction was fee bumped. This field is only present if `status` is `SUCCESS` or `FAILED`. + - `envelopeXdr`: `` - (optional) A base64 encoded string of the raw TransactionEnvelope XDR struct for this transaction. + - `resultXdr`: `` - (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`: `` - (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 deleted file mode 100644 index 9950225a3..000000000 --- a/api/methods/getTransactionStatus.mdx +++ /dev/null @@ -1,109 +0,0 @@ ---- -sidebar_position: 8 ---- - -:::note - -The `getTransactionStatus` method is still a work-in-progress. - -::: - -Clients will poll this to tell when the transaction has been completed. - -- TODO: Figure out result/error and how that fits into the jsonrpc response object -- TODO: Figure out return values for non-contract-invocation transactions - -## Parameters - -- `` - transaction hash to query, as a hex-encoded string - -## Returns - -- `` - - `id`: `` - hash of the transaction as a hex-encoded string - - `status`: `` - the current status of the transaction by hash, one of: - - pending - - success - - error - - `results`: `` - (optional) Will be present on completed successful transactions. - - xdr: ` - xdr-encoded return value of the contract call - - TODO: Anything else we should include? Gas spent? - - `envelopeXdr`: `` - (optional) A base64 encoded string of the raw TransactionEnvelope XDR struct for this transaction. - - `resultXdr`: `` - (optional) A base64 encoded string of the raw TransactionResult XDR struct for this transaction. - - `resultMetaXdr`: `` - (optional) A base64 encoded string of the raw TransactionResultMeta XDR struct for this transaction. - - `error`: `` - (optional) Will be present on failed transactions. - - `code`: `` - Short unique string representing the type of error - - `message`: `` - Human friendly summary of the error - - `data`: `` - (optional) More data related to the error if available - -## Examples - -### Request - -```json -{ - "jsonrpc": "2.0", - "id": 8675309, - "method": "getTransactionStatus", - "params": { - "hash": "97eb77da26e21d6a032fc0c311831d94a702ba336037da7c8a5ec51b3e39c485" - } -} -``` - -### Response - -#### Pending - -```json -{ - "jsonrpc": "2.0", - "id": 8675309, - "result": { - "id": "d70916f8b8aa55c13d5974a38e32a3efe440ef6870c0f0a07075d1c128d23698", - "status": "pending" - } -} -``` - -#### Success - -```json -{ - "jsonrpc": "2.0", - "id": 8675309, - "result": { - "id": "d70916f8b8aa55c13d5974a38e32a3efe440ef6870c0f0a07075d1c128d23698", - "status": "success", - "results": [ - { - "xdr": "AAAAAQAAAAY=" - } - ] - } -} -``` - -#### Error - -```json -{ - "jsonrpc": "2.0", - "id": 8675309, - "result": { - "id": "48dd243d4683745b7efa9f4fe6182f944b03cfd169135657e39c974e9b1fc50d", - "status": "error", - "error": { - "code": "tx_submission_failed", - "message": "Transaction submission failed", - "data": { - "envelope_xdr": "AAAAAgAAAAAdq+kGxmBG/ikQNdYHQ2fBAG+8Av/xp1ZfPZ9Xt42ragAAAGQAAoAp/////gAAAAEAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAEAAAAAAAAACgAAAAVoZWxsbwAAAAAAAAEAAAAHc29yb2JhbgAAAAAAAAAAAbeNq2oAAABAc6zcO/sTKyF26B1iJygLVrhhcVfK05rNW9gyeNwqSVeMFkHXpZ6D/6mqSB0KtvacxK4/VoiwWPrBQGPelnktBQ==", - "result_codes": { - "transaction": "tx_bad_seq" - }, - "result_xdr": "AAAAAAAAAAD////7AAAAAA==" - } - } - } -} -``` diff --git a/api/methods/sendTransaction.mdx b/api/methods/sendTransaction.mdx index 07625a982..73b803a90 100644 --- a/api/methods/sendTransaction.mdx +++ b/api/methods/sendTransaction.mdx @@ -4,13 +4,10 @@ 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 - `` - The signed transaction to broadcast (serialized in base64) @@ -18,16 +15,15 @@ This supports all transactions, not only smart contract-related transactions. ## Returns - `` - - `id`: `` The transaction hash (in an hex-encoded string), and the initial transaction status, ("pending" or something), unless we can reject it immediately. - - `status`: `` - the current status of the transaction by hash, one of: - - `pending` - - `success` - - `error` - - `error`: `` - (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`: `` The transaction hash (in an hex-encoded string). + - `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`: `` - The latest ledger known to Soroban-RPC at the time it handled the `sendTransaction()` request. + - `latestLedgerCloseTime`: `` - The unix timestamp of the close time of the latest ledger known to Soroban-RPC at the time it handled the `sendTransaction()` request. + - `errorResultXdr`: `` - (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" } } ```