bringing sdc-mental-models branch up to date (#632)

* feat: provide a means of receiving simple feedback from users (#587) * feat: provide a means of receiving simple feedback from users Here, we have swizzled (ejected) the `DocItem/Footer` component from docusaurus, and are inserting our own `ReaderFeedback` component into it before the rest of the doc footer content. Also, the `custom.scss` file has been used to style this element in a consistent manner with the rest of the site. This is the first step to resolve #586: The user interaction can now take place. From here, we will work on integrating the custom events into Google analytics. Ultimately, we will like to implment this feature into the `stellar-docs` repository, as well. Refs: #586 * Moving some React state things around * Including an `alt` tag for the like/dislike buttons * use the `pageId` for `eventLabel` in the send event * style: Linting the code * style: changing inline svg tag to be on newlines, changine filename to `jsx` * feat: Inserting the `DocItem/Footer` components on `dapps` and `api` pages * feat: migrating to the GA4 plugin in docusaurus * Testing with a new ga4 tracking id for preview domain * add some console statements to test what's happening * add configuration for test gtag container for this pr preview * feat: use `gtag` over the deprecated `ga` function * adding my own test gtag? * Remove the `gtag` function call, and just register state * removing the old-style google analytics tag for good * remove staging tag manager containers in preparation for production * replace staging ga4 tracking id with production tracking id * use `@site/static` for feedback button imports, rename file extension * rpc: rename expirationLedgerSeq to liveUntilLedgerSeq (#625) * rpc: rename expirationLedgerSeq to liveUntilLedgerSeq * rpc: rename expiration ledger in openrpc file --------- Co-authored-by: Elliot Voris <[email protected]> * Remove docker image hashes (#628) * remove mentions of specific image hashes in docker commands * update docker image hash to most recent version on releases page * Update WASM retrieval tutorial (#627) * docs: explain the diagnostic events that are emitted in sandbox (#593) * docs: explain the diagnostic events that are emitted in sandbox Perhaps this approach is too verbose? I think having the explanation of what is being seen right there in the tutorial is useful at this early step in the "getting started" section. A new developer is more likely to understand what they see, and remember what it is in the future if we don't try to interrupt their flow at this point by sending them to another page for some (possibly irrelevant) info. I may be incorrect there, and I'm happy to hear opinions from others. Refs: #521 * docs: add a space between two words * editorial in Update hello-world.mdx --------- Co-authored-by: Bri Wylde <[email protected]> * Fix a couple typos in rust-dialect.mdx (#630) --------- Co-authored-by: Elliot Voris <[email protected]> Co-authored-by: Alfonso Acosta <[email protected]> Co-authored-by: George <[email protected]> Co-authored-by: Bri Wylde <[email protected]> Co-authored-by: Sapo-Dorado <[email protected]>
stellar-deprecated · Oct 31, 2023 · 9da60ce · 9da60ce
1 parent 7e80de9
commit 9da60ce
Show file tree

Hide file tree

Showing 15 changed files with 260 additions and 48 deletions.
diff --git a/api/methods/getLedgerEntries.mdx b/api/methods/getLedgerEntries.mdx
@@ -26,7 +26,7 @@ import {RpcMethod} from "@site/src/components/RpcMethod";
         "key": "AAAAB+qfy4GuVKKfazvyk4R9P9fpo2n9HICsr+xqvVcTF+DC",
         "xdr": "AAAABwAAAADqn8uBrlSin2s78pOEfT/X6aNp/RyArK/sar1XExfgwgAAAAphIGNvbnRyYWN0AAA=",
         "lastModifiedLedgerSeq": "13",
-        "expirationLedgerSeq": "95"
+        "liveUntilLedgerSeq": "95"
       }
     ],
     "latestLedger": "179436"
@@ -214,14 +214,14 @@ print(
 ##### JavaScript
 
 ```javascript
-const { xdr } = require("soroban-client")
+const { Address, xdr } = require("soroban-client");
+
 function getLedgerKeyContractCode(contractId) {
   let ledgerKey = xdr.LedgerKey.contractData(
     new xdr.LedgerKeyContractData({
-      contract: xdr.ScAddress.scAddressTypeContract(contractId),
+      contract: new Address(contractId).toScAddress(),
       key: new xdr.ScVal.scvLedgerKeyContractInstance(),
-      durability: xdr.ContractDataDurability.persistent(),
-      bodyType: xdr.ContractEntryBodyType.dataEntry(),
+      durability: xdr.ContractDataDurability.persistent()
     })
   );
 
@@ -230,7 +230,7 @@ function getLedgerKeyContractCode(contractId) {
 
 console.log(
   getLedgerKeyContractCode(
-    "af9a2527e3b3b5571d63b0246ba32b7d31a5323766df7c60dfc0b3e3ba6fdf23"
+    "CA3D5KRYM6CB7OWQ6TWYRR3Z4T7GNZLKERYNZGGA5SOAOPIFY6YQGAXE"
   )
 )
 // OUTPUT: AAAABq+aJSfjs7VXHWOwJGujK30xpTI3Zt98YN/As+O6b98jAAAAFA==
@@ -304,30 +304,19 @@ print(
 ##### JavaScript
 
 ```javascript
-const { xdr } = require("soroban-client")
+const { xdr } = require("soroban-client");
 
 function getLedgerKeyWasmId(contractCodeLedgerEntryData) {
-
-  let entry = xdr.LedgerEntryData.fromXDR(
+  const entry = xdr.LedgerEntryData.fromXDR(
     contractCodeLedgerEntryData,
     "base64"
   );
 
-  let instance = new xdr.ScContractInstance({
-    executable: entry.contractData()
-      .body()
-      .value()
-      .val()
-  });
+  const instance = entry.contractData().val().instance();
 
   let ledgerKey = xdr.LedgerKey.contractCode(
     new xdr.LedgerKeyContractCode({
-      hash: xdr.ContractExecutable.contractExecutableWasm(instance.executable())
-        .wasmHash()
-        .instance()
-        .executable()
-        .wasmHash(),
-      bodyType: xdr.ContractEntryBodyType.dataEntry()
+      hash: instance.wasmHash()
     })
   );
 
@@ -368,7 +357,7 @@ And the response we get contains (even more) `LedgerEntryData` that we can decod
         "key": "AAAAB2QWKBCU9yGjzDJNxaEZpxEB6A8XsD2S/lKK/sViOLiC",
         "xdr": "AAAABwAAAABkFigQlPcho8wyTcWhGacRAegPF7A9kv5Siv7FYji4ggAAAlQAYXNtAQAAAAEPA2ACfn4BfmABfgF+YAAAAgcBAXYBRwAAAwQDAQICBQMBABEGGQN/AUGAgMAAC38AQYWAwAALfwBBkIDAAAsHMQUGbWVtb3J5AgAFaGVsbG8AAQFfAAMKX19kYXRhX2VuZAMBC19faGVhcF9iYXNlAwIK4QID1gIDAn8CfgF/I4CAgIAAQSBrIgEkgICAgAACQAJAIACnQf8BcSICQQ5GDQAgAkHKAEcNAQtCACEDQXshAgNAAkACQAJAAkAgAkUNAEIBIQQgAkGFgMCAAGotAAAiBUHfAEYNAyAFrSEEIAVBUGpBCkkNAiAFQb9/akEaSQ0BAkAgBUGff2pBGk8NACAEQkV8IQQMBAsQgoCAgAAACyABIAA3AwggASADQgiGQg6ENwMAQQAhAgNAAkAgAkEQRw0AQQAhAgJAA0AgAkEQRg0BIAFBEGogAmogASACaikDADcDACACQQhqIQIMAAsLIAFBEGqtQiCGQgSEQoSAgIAgEICAgIAAIQQgAUEgaiSAgICAACAEDwsgAUEQaiACakICNwMAIAJBCGohAgwACwsgBEJLfCEEDAELIARCUnwhBAsgAkEBaiECIAQgA0IGhoQhAwwACwsAAAsEAAAACwIACwsOAQBBgIDAAAsFSGVsbG8AHhFjb250cmFjdGVudm1ldGF2MAAAAAAAAAAUAAAAJQBDDmNvbnRyYWN0c3BlY3YwAAAAAAAAAAAAAAAFaGVsbG8AAAAAAAABAAAAAAAAAAJ0bwAAAAAAEQAAAAEAAAPqAAAAEQ==",
         "lastModifiedLedgerSeq": "75206",
-        "expirationLedgerSeq": "320384"
+        "liveUntilLedgerSeq": "320384"
       }
     ],
     "latestLedger": "262384"

diff --git a/dapps/guides/docker.mdx b/dapps/guides/docker.mdx
@@ -87,10 +87,6 @@ futurenet)
     ;;
 esac
 
-# this is set to the quickstart `soroban-dev` image anointed as the release
-# for a given Soroban Release, it is captured on Soroban Releases - https://soroban.stellar.org/docs/reference/releases
-QUICKSTART_SOROBAN_DOCKER_SHA=stellar/quickstart:testing@sha256:40636cdb1b9168b47e5dc120949fe3610ff914e8dd43409edb6fa66496bdd9c3
-
 shift
 
 # Run the soroban-preview container
@@ -126,7 +122,7 @@ docker run --rm -ti \
   --name stellar \
   --network soroban-network \
   -p 8000:8000 \
-  "$QUICKSTART_SOROBAN_DOCKER_SHA" \
+  stellar/quickstart:testing \
   $ARGS \
   --enable-soroban-rpc \
   "$@" # Pass through args from the CLI

diff --git a/docs/fundamentals-and-concepts/rust-dialect.mdx b/docs/fundamentals-and-concepts/rust-dialect.mdx
@@ -59,7 +59,7 @@ All standard I/O facilities and access to the operating system that a typical Ru
 
 No operating system, nor any simulation thereof, is present in the contract sandbox. Again, the repertoire of host objects and host functions is intended to replace and largely obviate the need for such facilities from the standard library.
 
-This restriction arises from the fact that contracts need to run with _stronger_ guarantees than those made by typical operating-system APIs. Specifically contracts must perform I/O with all-or-nothing, transactional semantics (relative to their successful execution or failure) as well as serializable consistency. This eliminating most APIs that would relate to typical file I/O. Furthermore contracts must be isolated from all sources of nondeterminism such as networking or process control, which eliminating most of the remaining APIs. Once files, networking and process control are gone, there simply isn't enough left in the standard operating system I/O facililties to bother trying to provide them.
+This restriction arises from the fact that contracts need to run with _stronger_ guarantees than those made by typical operating-system APIs. Specifically contracts must perform I/O with all-or-nothing, transactional semantics (relative to their successful execution or failure) as well as serializable consistency. This eliminates most APIs that would relate to typical file I/O. Furthermore contracts must be isolated from all sources of nondeterminism such as networking or process control, which eliminates most of the remaining APIs. Once files, networking and process control are gone, there simply isn't enough left in the standard operating system I/O facililties to bother trying to provide them.
 
 ## No multithreading
 

diff --git a/docs/getting-started/hello-world.mdx b/docs/getting-started/hello-world.mdx
@@ -352,23 +352,72 @@ soroban contract invoke \
     --to friend
 ```
 
-The following output should appear.
+The contract invocation should result in the following output.
 
 ```json
 ["Hello", "friend"]
 ```
 
 :::info The `--` double-dash is required!
+
 This is a general [CLI pattern](https://unix.stackexchange.com/questions/11376/what-does-double-dash-mean) used by other commands like [cargo run](https://doc.rust-lang.org/cargo/commands/cargo-run.html). Everything after the `--`, sometimes called [slop](https://github.com/clap-rs/clap/issues/971), is passed to a child process. In this case, `soroban contract invoke` builds an _implicit CLI_ on-the-fly for the `hello` method in your contract. It can do this because Soroban SDK embeds your contract's schema / interface types right in the `.wasm` file that gets deployed on-chain. You can also try:
 
-    soroban contract invoke ... -- --help
+```bash
+soroban contract invoke ... -- --help
+```
 
 and
 
-    soroban contract invoke ... -- hello --help
+```bash
+soroban contract invoke ... -- hello --help
+```
 
 :::
 
+### Diagnostic Events
+
+You will also notice here (and with any other contract run in the sandbox environment) that some diagnostic output will be displayed on the screen. This is because the `soroban-cli` automatically sets the diagnostic level to "Debug" for contracts running in the sandbox.
+
+Here, we'll see two diagnostic events were emitted by our contract invocation:
+
+1. First is a `fn_call` diagnostic event. It tells you the _kind_ of event, the contract ID that will be called, the name of the function being called, and a vector of the arguments passed to the function. A (greatly simplified) version of this event's body would look like this:
+
+```
+{
+    event: {
+        body: {
+            topics: [
+                Symbol(fn_call),
+                Bytes(0000000000000000000000000000000000000000000000000000000000000001),
+                Symbol(hello),
+            ],
+            data: Symbol(friend),
+        }
+    }
+}
+```
+
+2. Next is a `fn_return` diagnostic event. These events are emitted when a contract call completes and contains the _kind_ of event, the name of the function that is returning, and the value returned by the function. A (greatly simplified) version of this event's body would look like this:
+
+```
+{
+    event: {
+        body: {
+            topics: [
+                Symbol(fn_return),
+                Symbol(hello),
+            ],
+            data: [
+                Symbol(Hello),
+                Symbol(friend),
+            ]
+        }
+    }
+}
+```
+
+You can learn more about diagnostic events in our [Events article](../fundamentals-and-concepts/events#what-are-diagnosticevents).
+
 ## Optimizing Builds
 
 Use `soroban contract optimize` to further minimize the size of the `.wasm`. First, re-install soroban-cli with the `opt` feature:

diff --git a/docs/reference/releases.mdx b/docs/reference/releases.mdx
@@ -31,7 +31,7 @@ Preview releases are software releases that are also released to the [Testnet] t
 | Soroban RPC                  | `v20.0.0-rc4`                                                                                                                      |
 | Stellar Horizon              | `2.27.0~rc2-384`                                                                                                                   |
 | Stellar Friendbot            | `soroban-v0.0.2-alpha`                                                                                                             |
-| Stellar Quickstart           | `docker.io/stellar/quickstart:testing@sha256:40636cdb1b9168b47e5dc120949fe3610ff914e8dd43409edb6fa66496bdd9c3`                     |
+| Stellar Quickstart           | `docker.io/stellar/quickstart:testing@sha256:0c756150e7b3c53603fe36bb932c4e7d7ceaef691906b2d3d952771ccc195559`                     |
 | Stellar JS Stellar Base      | `10.0.0-beta.1`                                                                                                                    |
 | Stellar JS Soroban Client    | `v1.0.0-beta.2`                                                                                                                    |
 | Freighter                    | `5.6.1`                                                                                                                            |

diff --git a/docs/reference/rpc.mdx b/docs/reference/rpc.mdx
@@ -33,13 +33,13 @@ It's also possible to run a contract in the local sandbox environment without a
 
 ### Standalone
 
-To run a local standalone network with the Stellar Quickstart Docker image, run the following command, double-checking that the `sha256` matches the latest on the [Releases](./releases.mdx) page:
+To run a local standalone network with the Stellar Quickstart Docker image, run the following command:
 
 ```bash
 docker run --rm -it \
     -p 8000:8000 \
     --name stellar \
-    stellar/quickstart:testing@sha256:1c98f895f8b69cc843eeaa5230d67044dbeb390a5529d51dd7762d8ff685c3f8 \
+    stellar/quickstart:testing \
     --standalone \
     --enable-soroban-rpc
 ```
@@ -112,7 +112,7 @@ Running your own Testnet node works much the same way as running a Quickstart no
 docker run --rm -it \
     -p 8000:8000 \
     --name stellar \
-    stellar/quickstart:testing@sha256:1c98f895f8b69cc843eeaa5230d67044dbeb390a5529d51dd7762d8ff685c3f8 \
+    stellar/quickstart:testing \
     --testnet \
     --enable-soroban-rpc
 ```

diff --git a/docusaurus.config.js b/docusaurus.config.js
@@ -22,20 +22,15 @@ const config = {
   },
   plugins: [
     "docusaurus-plugin-sass",
-    [
-      '@docusaurus/plugin-google-analytics',
-      {
-        trackingID: 'UA-53373928-1',
-        anonymizeIP: true,
-      },
-    ],
     [
       '@docusaurus/plugin-content-docs',
       {
         id: 'api',
         path: 'api',
         routeBasePath: 'api',
         sidebarPath: require.resolve('./sidebarsApi.js'),
+        editUrl: "https://github.com/stellar/soroban-docs/tree/main/",
+        showLastUpdateTime: true,
       },
     ],
     [
@@ -45,6 +40,8 @@ const config = {
       path: 'dapps',
       routeBasePath: 'dapps',
       sidebarPath: require.resolve('./sidebarsDapps.js'),
+      editUrl: "https://github.com/stellar/soroban-docs/tree/main/",
+      showLastUpdateTime: true,
     },
   ],
     require('./src/dev-server-plugin'),
@@ -65,6 +62,10 @@ const config = {
         theme: {
           customCss: [require.resolve("./src/css/custom.scss")],
         },
+        gtag: {
+          trackingID: "G-YE9KVSTERG",
+          anonymizeIP: true,
+        },
       }),
     ],
   ],

diff --git a/src/analytics-module.js b/src/analytics-module.js
@@ -20,7 +20,7 @@ module.exports = () => ({
             name: 'facebook-domain-verification',
             content: 'll8iy5eqaqpremxnd6bo2qg2qjxrtj',
           },
-        }
+        },
       ],
       preBodyTags: [
         {
@@ -38,8 +38,8 @@ module.exports = () => ({
             <iframe src="https://www.googletagmanager.com/ns.html?id=GTM-55LZM97"
             height="0" width="0" style="display:none;visibility:hidden"></iframe>
           `
-        }
+        },
       ],
     };
   },
-});
+});
diff --git a/src/components/ReaderFeedback/index.js b/src/components/ReaderFeedback/index.js
@@ -0,0 +1,41 @@
+import React, { useState } from "react";
+import useIsBrowser from '@docusaurus/useIsBrowser';
+
+import IconThumbsUp from '@site/static/icons/thumbs-up.svg';
+import IconThumbsDown from '@site/static/icons/thumbs-down.svg';
+
+const ReaderFeedback = ({ pageId }) => {
+  const [feedbackGiven, setFeedbackGiven] = useState(false);
+  const isBrowser = useIsBrowser();
+  if (!isBrowser) {
+    return null;
+  }
+
+  const giveFeedback = (value) => {
+    setFeedbackGiven(true);
+  };
+
+  return (
+    <div className="readerFeedback">
+      {feedbackGiven ? (
+        'Thanks for your feedback!'
+      ) : (
+        <>
+          Did you find this page helpful?
+          <IconThumbsUp
+            className="feedback_thumbsup"
+            alt="Like"
+            onClick={giveFeedback}
+          />
+          <IconThumbsDown
+            className="feedback_thumbsdown"
+            alt="Dislike"
+            onClick={giveFeedback}
+          />
+        </>
+      )}
+    </div>
+  );
+};
+
+export default ReaderFeedback;
diff --git a/src/css/custom.scss b/src/css/custom.scss
@@ -15,6 +15,9 @@
 @import url("https://fonts.googleapis.com/css2?family=IBM+Plex+Sans:wght@400;500&display=swap");
 @import url("https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600&display=swap");
 
+// soroban teal color #4daaa9
+// soroban gold color #f9db4a;
+
 /* You can override the default Infima variables here. */
 :root {
   --ifm-color-primary: #4daaa9;
@@ -47,6 +50,7 @@
 /* For readability concerns, you should choose a lighter palette in dark mode. */
 [data-theme="dark"] {
   --ifm-color-primary: #f9db4a;
+  --ifm-color-secondary: #4daaa9;
   --ifm-navbar-background-color: #1b1b1d;
   --ifm-footer-background-color: #1b1b1d;
   --ifm-background-color: #222222 !important;
@@ -111,4 +115,49 @@ p > code {
   border-radius: 0.5rem;
   font-family: var(--ifm-font-family-mono);
   font-weight: 700;
-}
+}
+
+/* Reader Feedback Box */
+
+.readerFeedback {
+  display: flex;
+  flex-direction: row;
+  justify-content: center;
+  align-items: center;
+  gap: 1rem;
+
+  margin-top: 3rem;
+  padding: 1.5rem 2rem;
+  background-color: var(--ifm-menu-color-background-active);
+  font-weight: 700;
+  color: var(--ifm-color-primary);
+
+  svg {
+    height: 1.5rem;
+    width: 1.5rem;
+    transition: color var(--ifm-transition-fast) var(--ifm-transition-timing-default);
+
+    &:hover,
+    &:focus {
+      cursor: pointer;
+    }
+  }
+
+  .feedback_thumbsup {
+    color: var(--ifm-color-success-lightest);
+
+    &:hover,
+    &:focus {
+      color: var(--ifm-color-success-darkest);
+    }
+  }
+
+  .feedback_thumbsdown {
+    color: var(--ifm-color-danger-lightest);
+
+    &:hover,
+    &:focus {
+      color: var(--ifm-color-danger-darkest);
+    }
+  }
+}