Update and improve smart rollup tutorial (#118)

* This should be the last tutorial because of the complexity * Title * Intro * What is a smart rollup? * prereqs * What is a smart rollup v2 * Applications that communicate with other blockchains * Enable embedded HTML in markdown * Diagram * Need to communicate * Tutorial application * Tweaks * Setup and build * Sandbox * build troubleshooting * Debug mode and optimizing the kernel * tweaks * Deploying the kernel and running the node * Notes on next steps * references and next steps * comments * list numbering * not getting into this yet * tweaks * To open a new one * origination clarifications from Emma * You originate the rollup, not the kernel * update references * reorder intro sections * clarify main function * tweaks * The tutorial doesn't provide enough info for the user to do this; comment for now * cleaning up comments and todos * Separate into sections * run `$CC --version` Co-authored-by: Emma Turner <[email protected]> * grep for wasm32 directly * This shouldn't be needed anymore * Use new version of Rust if this PR is accepted: https://gitlab.com/trili/hello-world-kernel/-/merge_requests/2 * How the installer kernel works * Converted to binary * Split lines * Remove reference to smart contract tutorial * Line breaks for better appearance Co-authored-by: Emma Turner <[email protected]> * To originate the kernel on Tezos, it must fit within the maximum size for a layer 1 operation. * Release build of kernel * Optimize the release kernel * Parallel with smart contracts and link to tutorial * Debug the installer kernel * Create wasm first to debug, then generate hex to originate * this is a wasm file * line breaks * Don't start the sandbox until you need it * To get the kernel running... * Split up this topic to stress the interaction * which provides the hash and timestamp of the previous block * to request data from outside of layer 1. Co-authored-by: Emma Turner <[email protected]> * Shows that the upgrade was successful * hex-encoded Co-authored-by: Emma Turner <[email protected]> * reduce the size of Co-authored-by: Emma Turner <[email protected]> * the maximum size for a layer 1 operation (32KB) * Use rustc for rust version instead of cargo * Make sure that Docker desktop is running. --------- Co-authored-by: Emma Turner <[email protected]>
trilitech · Oct 27, 2023 · e59d3d6 · e59d3d6
1 parent 76a80e4
commit e59d3d6
Show file tree

Hide file tree

Showing 8 changed files with 627 additions and 466 deletions.
diff --git a/markdoc/tags.js b/markdoc/tags.js
@@ -11,6 +11,19 @@ import CalendlyEmbed from '@/components/CalendlyEmbed';
 // Import the built-in Next.js tags
 import { comment } from '@markdoc/next.js/tags'
 
+// Custom tag to allow embedding HTML elements
+const UnescapedHtml = ({ htmlWrapperTag = 'div', children }) => {
+  const html =
+    typeof children === 'string'
+      ? children
+      : typeof children.props.children === 'string'
+      ? children.props.children
+      : children.props.children.join('')
+
+  const CustomTag = htmlWrapperTag
+  return <CustomTag dangerouslySetInnerHTML={{ __html: html }} />
+}
+
 const tags = {
   callout: {
     attributes: {
@@ -82,6 +95,13 @@ const tags = {
   calendlyEmbed: {
     render: CalendlyEmbed,
   },
+  html: {
+    render: UnescapedHtml,
+    attributes: {
+      htmlWrapperTag: { type: String },
+      children: { type: String },
+    },
+  },
   // tabs: {
   //   render: Tabs,
   //   attributes: {},

diff --git a/src/components/Layout.jsx b/src/components/Layout.jsx
@@ -285,10 +285,6 @@ const tutorialNavigation = [
           },
         ],
       },
-      {
-        title: 'Deploy your own smart rollup',
-        href: '/tutorials/smart-rollups',
-      },
       {
         title: 'Create an NFT',
         href: '/tutorials/create-an-nft',
@@ -351,6 +347,36 @@ const tutorialNavigation = [
           },
         ],
       },
+      {
+        title: 'Deploy a smart rollup',
+        href: '/tutorials/smart-rollups',
+        children: [
+          {
+            title: "Introduction",
+            href: '/tutorials/smart-rollups',
+          },
+          {
+            title: "Part 1: Setting up the application",
+            href: '/tutorials/smart-rollups/set-up',
+          },
+          {
+            title: "Part 2: Running the kernel in debug mode",
+            href: '/tutorials/smart-rollups/debug',
+          },
+          {
+            title: "Part 3: Optimizing the kernel",
+            href: '/tutorials/smart-rollups/optimize',
+          },
+          {
+            title: "Part 4: Deploying (originating) the rollup",
+            href: '/tutorials/smart-rollups/deploy',
+          },
+          {
+            title: "Part 5: Running and interacting with the rollup node",
+            href: '/tutorials/smart-rollups/run',
+          },
+        ],
+      },
     ],
   },
 ]

diff --git a/src/pages/tutorials/smart-rollups/debug.md b/src/pages/tutorials/smart-rollups/debug.md
@@ -0,0 +1,38 @@
+---
+id: debug
+title: "Part 2: Running the kernel in debug mode"
+lastUpdated: 25th October 2023
+---
+
+Octez provides a command named `octez-smart-rollup-wasm-debugger` that runs smart rollups in debug mode to make it easier to test and observe them.
+Later, you will deploy the rollup to the sandbox, but running it in debug mode first verifies that it built correctly.
+
+1. In the terminal window inside the Docker container, go to the `hello_world_kernel` folder.
+
+1. Run this command to start the rollup and pass an empty message inbox to it:
+
+   ```bash
+   octez-smart-rollup-wasm-debugger \
+     --kernel target/wasm32-unknown-unknown/debug/hello_world_kernel.wasm \
+     --inputs empty_input.json
+   ```
+
+   The command prompt changes again to show that you are in debugging mode, which steps through commands.
+
+1. At the debugging prompt, run this command to send the message inbox to the kernel:
+
+   ```bash
+   step inbox
+   ```
+
+   The response shows the logging information for the kernel, including these parts:
+
+   - The message "Hello, kernel" from the `hello_kernel` function
+   - The message "Got message: Internal(StartOfLevel)," which represents the start of the message inbox
+   - The message "Got message: Internal(InfoPerLevel(InfoPerLevel ...," which provides the hash and timestamp of the previous block
+   - The message "Got message: Internal(EndOfLevel)," which represents the end of the message inbox
+
+1. Press Ctrl + C to end debugging mode.
+
+Now you know that the kernel works.
+In the next section, you optimize the kernel to be deployed to the sandbox.
diff --git a/src/pages/tutorials/smart-rollups/deploy.md b/src/pages/tutorials/smart-rollups/deploy.md
@@ -0,0 +1,66 @@
+---
+id: deploy
+title: "Part 4: Deploying (originating) the rollup"
+lastUpdated: 25th October 2023
+---
+
+Smart rollups are originated in a way similar to smart contracts.
+Instead of running the `octez-client originate contract` command, you run the `octez-client originate smart rollup` command.
+This command creates an address for the rollup and stores a small amount of data about it on layer 1.
+
+1. In the Docker container, in the `hello-world-kernel` folder, run this command to start the sandbox:
+
+   ```bash
+   ./sandbox_node.sh
+   ```
+
+   This command starts a Tezos testing environment, including a baking node running in sandbox mode and a group of test accounts.
+   The console shows repeated messages that show that the node is baking blocks.
+   For more information about sandbox mode, see [sandbox mode](https://tezos.gitlab.io/user/sandbox.html).
+
+   If you see an error that says "Unable to connect to the node," you can ignore it because it happens only once while the node is starting.
+
+1. Leave that terminal instance running for the rest of the tutorial.
+
+1. Open a new terminal window.
+
+1. In the new terminal window, enter the Docker container by running this command:
+
+   ```bash
+   docker exec -it octez-container /bin/sh
+   ```
+
+   Now the second terminal window is running inside the container just like the first one.
+
+1. In the second terminal window, run this command to verify that the sandbox is running with the correct protocol:
+
+   ```bash
+   octez-client rpc get /chains/main/blocks/head/metadata | grep protocol
+   ```
+
+   The response shows the protocol that the sandbox is running, as in this example:
+
+   ```
+   { "protocol": "ProtoALphaALphaALphaALphaALphaALphaALphaALphaDdp3zK",
+     "next_protocol": "ProtoALphaALphaALphaALphaALphaALphaALphaALphaDdp3zK",
+   ```
+
+   If you don't see a message that looks like this one, check for errors in the first terminal window.
+
+   Now the sandbox is running in the Docker container and you can use it to test the rollup.
+
+1. Run this command to deploy the installer kernel to the Tezos sandbox:
+
+   ```bash
+   octez-client originate smart rollup \
+     "test_smart_rollup" from "bootstrap1" \
+     of kind wasm_2_0_0 of type bytes \
+     with kernel file:hello_world_kernel_installer.hex --burn-cap 3
+   ```
+
+   If you need to open a new terminal window within the Docker container, run the command `docker exec -it octez-container /bin/sh`.
+
+   Like the command to originate a smart contract, this command uses the `--burn-cap` argument to allow the transaction to take fees from the account.
+   Also like deploying a smart contract, the response in the terminal shows information about the transaction and the address of the originated smart rollup, which starts with `sr1`.
+
+Now layer 1 is aware of the rollup and nodes can run the rollup kernel.