Merge pull request stellar#319 from paulbellamy/dev

Soroban-RPC updates for the release

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.

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.

api/methods/getHealth.mdx

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 2
+sidebar_position: 3
 ---
 
 General node health check.

api/methods/getLatestLedger.mdx

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 3
+sidebar_position: 1
 ---
 
 :::note

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]: <https://laboratory.stellar.org/#xdr-viewer?type=LedgerEntryData&network=futurenet>
+["View XDR" page of the Stellar Laboratory]: <https://laboratory.stellar.org/#xdr-viewer?type=LedgerEntryData&network=futurenet>

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
 
 - `<object>`
+  - `friendbotUrl`: `<string>` (optional) - The URL of this network's "friendbot" faucet
   - `passphrase`: `<string>` - Network passphrase configured
   - `protocolVersion`: `<string>` - Protocol version of the latest ledger

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
+
+- `<hash>` - transaction hash to query, as a hex-encoded string
+
+## Returns
+
+- `<object>`
+  - `id`: `<hash>` - hash of the transaction as a hex-encoded string
+  - `status`: `<status>` - the current status of the transaction by hash, one of:
+    - pending
+    - success
+    - error
+  - `results`: `<object[]>` - (optional) Will be present on completed successful transactions.
+    - xdr: `<xdr.ScVal`> - xdr-encoded return value of the contract call
+    - TODO: Anything else we should include? Gas spent?
+  - `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.
+  - `resultMetaXdr`: `<xdr.TransactionResultMeta>` - (optional) A base64 encoded string of the raw TransactionResultMeta XDR struct for this transaction.
+  - `error`: `<object>` - (optional) Will be present on failed transactions.
+    - `code`: `<string>` - Short unique string representing the type of error
+    - `message`: `<string>` - Human friendly summary of the error
+    - `data`: `<object>` - (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=="
+      }
+    }
+  }
+}
+```

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
+[`increment` example contract]: /docs/getting-started/storing-data

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.