From b6bb6d9deba1682c768c01f2f1a7b9891babce63 Mon Sep 17 00:00:00 2001 From: Paul Bellamy Date: Thu, 16 Feb 2023 18:04:14 +0000 Subject: [PATCH] Merge pull request #319 from paulbellamy/dev Soroban-RPC updates for the release --- api/methods/getAccount.mdx | 6 ++ api/methods/getEvents.mdx | 2 +- api/methods/getHealth.mdx | 2 +- api/methods/getLatestLedger.mdx | 2 +- api/methods/getLedgerEntry.mdx | 76 ++++++++++++++++++- api/methods/getNetwork.mdx | 9 +-- api/methods/getTransactionStatus.mdx | 109 +++++++++++++++++++++++++++ api/methods/requestAirdrop.mdx | 30 -------- api/methods/sendTransaction.mdx | 4 +- api/methods/simulateTransaction.mdx | 2 +- 10 files changed, 198 insertions(+), 44 deletions(-) create mode 100644 api/methods/getTransactionStatus.mdx delete mode 100644 api/methods/requestAirdrop.mdx diff --git a/api/methods/getAccount.mdx b/api/methods/getAccount.mdx index 2bf848312..280ebc52b 100644 --- a/api/methods/getAccount.mdx +++ b/api/methods/getAccount.mdx @@ -2,6 +2,12 @@ sidebar_position: 1 --- +:::note + +Deprecated! Use `getLedgerEntry` instead. This method will be removed in the next release. + +::: + Fetch a minimal set of current info about a Stellar account. Needed to get the current sequence number, and balance for the account so you can build a successful transaction. diff --git a/api/methods/getEvents.mdx b/api/methods/getEvents.mdx index 63945ac99..fa359558f 100644 --- a/api/methods/getEvents.mdx +++ b/api/methods/getEvents.mdx @@ -1,5 +1,5 @@ --- -sidebar_position: 6 +sidebar_position: 2 --- Clients can request a filtered list of events emitted by a given ledger range. diff --git a/api/methods/getHealth.mdx b/api/methods/getHealth.mdx index 06a958d2c..c3961f84c 100644 --- a/api/methods/getHealth.mdx +++ b/api/methods/getHealth.mdx @@ -1,5 +1,5 @@ --- -sidebar_position: 2 +sidebar_position: 3 --- General node health check. diff --git a/api/methods/getLatestLedger.mdx b/api/methods/getLatestLedger.mdx index c68662fcb..64ff7e241 100644 --- a/api/methods/getLatestLedger.mdx +++ b/api/methods/getLatestLedger.mdx @@ -1,5 +1,5 @@ --- -sidebar_position: 3 +sidebar_position: 1 --- :::note diff --git a/api/methods/getLedgerEntry.mdx b/api/methods/getLedgerEntry.mdx index 3355c3793..6b1c39046 100644 --- a/api/methods/getLedgerEntry.mdx +++ b/api/methods/getLedgerEntry.mdx @@ -104,6 +104,80 @@ console.log(getLedgerKeySymbol( )) ``` +### Requesting an Account + +:::note + +This functionality is included in the js [soroban-client](https://www.npmjs.com/package/soroban-client) package as `Server.getAccount(address)`. + +::: + +Accounts are stored as ledger entries, so we can use this method to look up an account along with it's current sequence number. + +```js +const SorobanClient = require('soroban-client') +const xdr = SorobanClient.xdr + +const getLedgerKeyAccount = (address) => { + // We can use the `StrKey` library here to decode the address into the public + // key. + const publicKey = SorobanClient.StrKey.decodeEd25519PublicKey(address); + + const ledgerKey = xdr.LedgerKey.account( + new xdr.LedgerKeyAccount({ + accountId: xdr.PublicKey.publicKeyTypeEd25519( + publicKey + ), + }) + ) + return ledgerKey.toXDR('base64') +} + +console.log(getLedgerKeyAccount( + 'GCU5YE6IVBOEZ5LUU5N2NB55VPB5YZNFERT65SSTVXTNMS7IEQWXKBM2' +)) + +# OUTPUT: AAAAAAAAAACp3BPIqFxM9XSnW6aHvavD3GWlJGfuylOt5tZL6CQtdQ== +``` + + +We then take our output from this function, and use it as the `key` parameter in our call to the `getLedgerEntry` method. + +```json +{ + "jsonrpc": "2.0", + "id": 8675309, + "method": "getLedgerEntry", + "params": { + "key": "AAAAAAAAAACp3BPIqFxM9XSnW6aHvavD3GWlJGfuylOt5tZL6CQtdQ==" + } +} +``` + +And the response we get contains the `LedgerEntryData` with the current information about this account. + +```json +{ + "jsonrpc": "2.0", + "id": 8675309, + "result": { + "xdr": "AAAAAAAAAACp3BPIqFxM9XSnW6aHvavD3GWlJGfuylOt5tZL6CQtdQAAABdIdugAAAAADAAAAAAAAAAAAAAAAAAAAAAAAAAAAQAAAAAAAAAAAAAA" + "lastModifiedLedgerSeq": "164303", + "latestLedger": "246819" + } +} +``` + +We can then parse this result as an `xdr.LedgerEntryData` type. + +```js +const parsed = xdr.LedgerEntryData.fromXDR( + 'AAAAAAAAAACp3BPIqFxM9XSnW6aHvavD3GWlJGfuylOt5tZL6CQtdQAAABdIdugAAAAADAAAAAAAAAAAAAAAAAAAAAAAAAAAAQAAAAAAAAAAAAAA', + 'base64' +) +console.log(parsed); +``` + ### Requesting a Contract's WASM Code This can be a bit tricky to wrap your head around, but the conventions do make sense once you let it sink in. @@ -217,4 +291,4 @@ And the response we get contains (even more) `LedgerEntryData` that we can decod ``` [`increment` example contract]: /docs/getting-started/storing-data -["View XDR" page of the Stellar Laboratory]: \ No newline at end of file +["View XDR" page of the Stellar Laboratory]: diff --git a/api/methods/getNetwork.mdx b/api/methods/getNetwork.mdx index 2470aaf5c..dc4730499 100644 --- a/api/methods/getNetwork.mdx +++ b/api/methods/getNetwork.mdx @@ -1,13 +1,7 @@ --- -sidebar_position: 7 +sidebar_position: 5 --- -:::note - -The `getNetwork` method is still a work-in-progress. - -::: - General info about the currently configured network. ## Parameters @@ -17,5 +11,6 @@ General info about the currently configured network. ## Returns - `` + - `friendbotUrl`: `` (optional) - The URL of this network's "friendbot" faucet - `passphrase`: `` - Network passphrase configured - `protocolVersion`: `` - Protocol version of the latest ledger diff --git a/api/methods/getTransactionStatus.mdx b/api/methods/getTransactionStatus.mdx new file mode 100644 index 000000000..b0822cee7 --- /dev/null +++ b/api/methods/getTransactionStatus.mdx @@ -0,0 +1,109 @@ +--- +sidebar_position: 6 +--- + +:::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/requestAirdrop.mdx b/api/methods/requestAirdrop.mdx deleted file mode 100644 index 4c0a2973d..000000000 --- a/api/methods/requestAirdrop.mdx +++ /dev/null @@ -1,30 +0,0 @@ ---- -sidebar_position: 9 ---- - -:::note - -The `requestAirdrop` method is still a work-in-progress. - -::: - -Used outside pubnet to request some lumens from friendbot for a particular account. - -:::note - -Maybe we could replace this with a 'friendbotUrl' field in `getNetwork` method? - -::: - -## Parameters - -- `` - Account pubkey to fund - -## Returns - -- `` - - `transactionId`: `` - Transaction id of the transfer as a hex-encoded string. - -## Errors - -- If this is pubnet (or friendbot is otherwise unavailable). diff --git a/api/methods/sendTransaction.mdx b/api/methods/sendTransaction.mdx index 73b803a90..e30bd89c0 100644 --- a/api/methods/sendTransaction.mdx +++ b/api/methods/sendTransaction.mdx @@ -1,5 +1,5 @@ --- -sidebar_position: 10 +sidebar_position: 7 --- Submit a real transaction to the Stellar network. This is the only way to make changes "on-chain". @@ -57,4 +57,4 @@ The following example request uses a transaction to invoke the `increment` metho } ``` -[`increment` example contract]: /docs/getting-started/storing-data \ No newline at end of file +[`increment` example contract]: /docs/getting-started/storing-data diff --git a/api/methods/simulateTransaction.mdx b/api/methods/simulateTransaction.mdx index 99bd43e7d..ad2db84c0 100644 --- a/api/methods/simulateTransaction.mdx +++ b/api/methods/simulateTransaction.mdx @@ -1,5 +1,5 @@ --- -sidebar_position: 11 +sidebar_position: 8 --- Submit a trial contract invocation to get back return values, expected ledger footprint, and expected costs.