Merge pull request #456 from trilitech/rework-dal-baker-tutorial

Rework DAL baker tutorial

docs/architecture/data-availability-layer.md

@@ -2,14 +2,21 @@
 title: The Data Availability Layer
 authors: "Tim McMackin"
 last_update:
-  date: 10 June 2024
+  date: 17 October 2024
 ---
 
 The Data Availability Layer (DAL) is a companion peer-to-peer network for the Tezos blockchain, designed to provide additional data bandwidth to Smart Rollups.
 It allows users to share large amounts of data in a way that is decentralized and permissionless, because anyone can join the network and post and read data on it.
 
 For a tutorial on how to use the DAL, see [Implement a file archive with the DAL and a Smart Rollup](/tutorials/build-files-archive-with-dal).
 
+## Running DAL nodes
+
+The DAL depends on individual people running nodes, just like Tezos layer 1.
+
+- If you are already a Tezos baker, you can add a DAL node to your setup with the instructions in [Running a DAL attester node](https://tezos.gitlab.io/shell/dal_run.html).
+- For step-by-step instructions on running a DAL node, accessible to anyone, see [Join the DAL as a baker in 5 steps](/tutorials/join-dal-baker).
+
 ## How the DAL works
 
 The DAL relies on a network of DAL nodes that distribute data via a peer-to-peer network.
@@ -115,7 +122,7 @@ For an example of sending larger amounts of data, see [Implement a file archive
 Smart Rollups can use data from the DAL **only after it has been attested by the bakers**.
 Due to the attestation lag, they cannot access DAL data published in the current level, because not enough blocks have elapsed to allow bakers to attest the data.
 
-The more recent level in the past that Smart Rollups can access data from is the current level minus the attestation lag.
+The most recent level in the past that Smart Rollups can access data from is the current level minus the attestation lag.
 They can access the data in that level with the Smart Rollup kernel SDK function `reveal_dal_page`, which accepts the target level, slot, and page to receive, as in this example:
 
 ```rust

docs/tutorials.mdx

@@ -77,6 +77,14 @@ These tutorials contain multiple parts and are intended for developers with some
   link="Start tutorial"
 />
 
+<TutorialCard
+  title="Join the DAL as a baker in 5 steps"
+  emoji="🍞"
+  href="/tutorials/join-dal-baker"
+  description="Learn how to participate in the Data Availability Layer, which is a peer-to-peer network for sharing data across Tezos"
+  link="Start tutorial"
+/>
+
 </TutorialCardContainer>
 
 ## Advanced
@@ -133,12 +141,4 @@ These tutorials are intended for developers who are familiar with Tezos and want
   link="Start tutorial"
 />
 
-<TutorialCard
-  title="Join the DAL as a baker in 5 steps"
-  emoji="🍞"
-  href="/tutorials/join-dal-baker"
-  description="Learn how to participate to the DAL as a baker"
-  link="Start tutorial"
-/>
-
 </TutorialCardContainer>

docs/tutorials/join-dal-baker.md

@@ -2,47 +2,57 @@
 title: Join the DAL as a baker in 5 steps
 authors: Tezos core developers, Tim McMackin
 last_update:
-  date: 19 August 2024
+  date: 21 October 2024
 ---
 
-The Tezos data availability layer (DAL) is a key component for the scalability of Tezos.
-In a nutshell, the DAL increases the data bandwidth available for Tezos Smart Rollups by providing a peer-to-peer network that they can use to fetch data without compromising security.
+The Tezos data availability layer (DAL) is a peer-to-peer network that Tezos Smart Rollups can use to fetch data securely.
+The DAL is a key component for the scalability and bandwidth of Tezos and it's important for bakers to run DAL nodes along with their layer 1 nodes.
 
-When users and dApps submit data to the DAL, layer 1 nodes attest that it is available and DAL nodes distribute it to Smart Rollup nodes, which can store the data and use it.
+## Why are DAL bakers needed?
+
+When users and dApps submit data to the DAL, bakers use DAL nodes to verify that the data is available.
+Then the bakers attest that the data is available.
+Smart Rollup nodes can retrieve the data from DAL nodes only when enough bakers have attested that the data is available.
+Therefore, the DAL needs bakers who run layer 1 nodes, attesters, and DAL nodes.
 
-Just like layer 1, Tezos bakers ensure the security of the DAL.
-Bakers not only produce blocks but also attest that other bakers' blocks are valid and properly published on layer 1.
-In the same way, bakers attest that data published to the DAL is available.
 In the current implementation of the DAL, bakers do not receive extra incentives for attesting DAL data, but they might in the future.
 For now, bakers can join the DAL without risking any reward loss, ensuring a smooth transition.
 
-In this tutorial, you learn how to join Ghostnet as a baker and attest the publication of data on the DAL network on Ghostnet.
+## Do you already run a baker?
+
+For current bakers, it's a straightforward process to add a DAL node.
+If you are familiar with running a node and baker, you can add a DAL node to your existing setup by following the instructions in [Running a DAL attester node](https://tezos.gitlab.io/shell/dal_run.html).
+
+## Running a baker and DAL node from start to finish
+
+This guide covers the process of running a node, baker, and DAL node from start to finish, accessible for Tezos users with no prior experience in baking or running nodes.
+This guide walks you through how to join Ghostnet as a baker and attest the publication of data on the DAL network on Ghostnet.
 The steps for participating on any other network, including Tezos Mainnet, are similar.
 
 :::note Attestation rights delay
 
-This tutorial includes setting up a baker to attest that data is available on the DAL.
+Bakers need attestation rights to attest that data is available on the DAL.
 Depending on the network, it takes time for bakers to get attestation rights.
 The delay on Ghostnet is about 3.5 days, so in this tutorial you do setup work, wait 3.5 days for attestation rights, and verify that your DAL node and baker are working properly.
 
 If you don't want to wait that long, you can use Weeklynet, where the delay is about an hour.
 However, to use Weeklynet, you must use a specific version of the Octez suite.
 You must also be aware that the network completely resets and moves to a new version of the Octez suite every Wednesday.
-For information about using Weeklynet, see [Testing on sandboxes and testnets](../developing/testnets).
+For information about using Weeklynet, see [Testing on sandboxes and testnets](/developing/testnets).
 
 :::
 
-## Tutorial diagram
+## Diagram
 
-In this tutorial, you set up the Octez client and several Octez daemons, including a layer 1 node, a baker, and a DAL node.
+In this guide, you set up the Octez client and several Octez daemons, including a layer 1 node, a baker, and a DAL node.
 The following diagram shows these daemons with a blue background:
 
-![A diagram of the DAL architecture, with the daemons that you create in this tutorial highlighted](/img/tutorials/join-dal-baker-overview.png)
+![A diagram of the DAL architecture, with the daemons that you create in this guide highlighted](/img/tutorials/join-dal-baker-overview.png)
 <!-- https://lucid.app/lucidchart/b6b076ec-194c-4011-8e20-fa348bb983f3/edit?page=0_0# -->
 
 ## Prerequisites
 
-This tutorial requires a cloud-based computer or a computer that stays running constantly.
+To run the Octez daemons persistently, you need a cloud-based computer or a computer that stays running constantly.
 
 ## References
 

docs/tutorials/join-dal-baker/conclusion.md

@@ -5,12 +5,12 @@ last_update:
   date: 13 August 2024
 ---
 
-In this tutorial you have gone through all the steps needed to participate as a baker and DAL node.
+In this guide you have gone through all the steps needed to participate as a baker and DAL node.
 The steps for participating on any other network, including Tezos Mainnet, are similar, but other networks have different parameters.
 For example, the attestation delay on Mainnet is 2 weeks.
 
 You could further improve the setup by defining system services so that the daemons are automatically launched when the machine starts.
 You could also plug a monitoring solution such as the Prometheus + Grafana combo; a Grafana dashboard template for DAL nodes is available in Grafazos.
 The interactions between your baker and the chain can be observed on the Explorus block explorer which is aware of the DAL and can in particular display which DAL slots are being used at each level.
 
-As a next step, you can create a Smart Rollup that uses DAL data in the tutorial [Implement a file archive with the DAL and a Smart Rollup](../build-files-archive-with-dal).
+As a next step, you can create a Smart Rollup that uses DAL data in the tutorial [Implement a file archive with the DAL and a Smart Rollup](/tutorials/build-files-archive-with-dal).

docs/tutorials/join-dal-baker/run-dal-node.md

@@ -11,6 +11,13 @@ The DAL node is responsible for temporarily storing data and providing it to bak
 You may need to adapt your firewall rules or set up network address translation (NAT) to direct external traffic to the DAL node.
 For more information, see [Running a DAL attester node](https://tezos.gitlab.io/shell/dal_run.html) in the Octez documentation.
 
+1. Initialize the DAL node by running its `config init` command, passing the address of your `octez-node` instance and your baker's address.
+For example, this command initializes the DAL node with the address of a local `octez-node` instance on port 8732 and stores data in the default DAL node directory (`~/.tezos-dal-node`):
+
+   ```bash
+   octez-dal-node config init --endpoint http://127.0.0.1:8732 --attester-profiles="$MY_ADDRESS"
+   ```
+
 1. Start the DAL node by running this command:
 
    ```bash
@@ -25,10 +32,54 @@ For more information, see [Running a DAL attester node](https://tezos.gitlab.io/
 1. Verify that the DAL node is connected to the DAL network by running this command:
 
    ```bash
-   curl http://localhost:10732/p2p/gossipsub/connections
+   curl http://localhost:10732/p2p/points/info
+   ```
+
+   The response lists the network connections that the DAL node has, as in this example:
+
+   ```json
+   [
+     {
+       "point": "46.137.127.32:11732",
+       "info": {
+         "trusted": true,
+         "state": {
+           "event_kind": "running",
+           "p2p_peer_id": "idrpUzezw7VJ4NU6phQYuxh88RiU1t"
+         },
+         "p2p_peer_id": "idrpUzezw7VJ4NU6phQYuxh88RiU1t",
+         "last_established_connection": [
+           "idrpUzezw7VJ4NU6phQYuxh88RiU1t",
+           "2024-10-24T15:02:31.549-00:00"
+         ],
+         "last_seen": [
+           "idrpUzezw7VJ4NU6phQYuxh88RiU1t",
+           "2024-10-24T15:02:31.549-00:00"
+         ]
+       }
+     },
+     {
+       "point": "52.31.26.230:11732",
+       "info": {
+         "trusted": true,
+         "state": {
+           "event_kind": "running",
+           "p2p_peer_id": "idqrcQybXbKwWk42bn1XjeZ33xgduC"
+         },
+         "p2p_peer_id": "idqrcQybXbKwWk42bn1XjeZ33xgduC",
+         "last_established_connection": [
+           "idqrcQybXbKwWk42bn1XjeZ33xgduC",
+           "2024-10-24T15:02:31.666-00:00"
+         ],
+         "last_seen": [
+           "idqrcQybXbKwWk42bn1XjeZ33xgduC",
+           "2024-10-24T15:02:31.666-00:00"
+         ]
+       }
+     }
+   ]
    ```
 
-   The response lists the network connections that the DAL node has.
    It may take a few minutes for the node to connect to the DAL network.
 
    You can also verify that the DAL node is connected by viewing its log.

docs/tutorials/join-dal-baker/run-node.md

@@ -2,58 +2,79 @@
 title: "Step 1: Run an Octez node"
 authors: Tezos core developers, Tim McMackin
 last_update:
-  date: 27 August 2024
+  date: 21 October 2024
 ---
 
-To use the Octez suite with Ghostnet, you need a recent build of the Octez binaries.
-You can build the Octez suite from the source code or install prebuilt binaries as described at https://tezos.gitlab.io/introduction/howtoget.html.
+The first thing you need to run a baker and a DAL node is a Tezos layer 1 node, which is an instance of the `octez-node` program and part of the Octez suite of programs.
 
-:::note
+## Installing Octez
 
-If you already have an Octez node and baker running with a delegated account, you can skip to [Step 3: Run an Octez DAL node](./run-dal-node).
+The version of Octez to use depends on the Tezos network that you are using.
 
-:::
+- For Mainnet or Ghostnet, install the most recent release of Octez, including `octez-client`, `octez-node`, `octez-dal-node`, and the baker for the current protocol:
 
-The first step is to configure a Tezos node with the `octez-node` program:
+   - On MacOS, run these commands:
 
-1. Install the Octez suite of programs, including `octez-client`, `octez-node`, and `octez-dal-node` as described in [Installing Octez](https://tezos.gitlab.io/introduction/howtoget.html) in the Octez documentation.
-If you build from source, you can use the `latest_branch` branch to work with Ghostnet.
+      ```bash
+      brew tap serokell/tezos-packaging-stable https://github.com/serokell/tezos-packaging-stable.git
+      brew install tezos-client tezos-node tezos-dal-node tezos-baker-PsParisC
+      ```
+
+   - On Linux and Windows WSL, download and install the built binaries from the [Octez release page](https://gitlab.com/tezos/tezos/-/releases), as in this example for Ubuntu:
+
+      ```bash
+      wget -O octez-binaries-20.3-linux-x86_64.tar.gz https://gitlab.com/tezos/tezos/-/package_files/150896058/download
+      tar xf octez-binaries-20.3-linux-x86_64.tar.gz
+      sudo cp octez-x86_64/octez* /usr/local/bin/
+      ```
 
-1. Initialize the Octez node for Ghostnet, such as in this example:
+- For Weeklynet, look up the necessary version of Octez at https://teztnets.com/weeklynet-about and install it with the instructions there.
+
+For more installation options, see [Installing Octez](https://tezos.gitlab.io/introduction/howtoget.html) in the Octez documentation.
+
+If you build from source, you can use the `latest-release` branch to work with Ghostnet.
+
+## Running the layer 1 node
+
+1. Initialize the Octez node for the network.
+For example, to initialize it for Ghostnet, run this command:
 
    ```bash
    octez-node config init --network ghostnet
    ```
 
-1. Speed up the process of initializing the node by loading a snapshot:
+   By default, the node stores its data in the folder `$HOME/.tezos-node`.
 
-   1. Download a rolling snapshot of Ghostnet from https://snapshot.tzinit.org based on the instructions on that site.
-   For example, the command to download the snapshot from the EU servers might look like this:
+1. Download a rolling snapshot of the network from https://snapshot.tzinit.org based on the instructions on that site.
+For example, the command to download a Ghostnet snapshot from the EU servers might look like this:
 
-      ```bash
-      wget -O snapshot_file https://snapshots.eu.tzinit.org/ghostnet/rolling
-      ```
+   ```bash
+   wget -O snapshot_file https://snapshots.eu.tzinit.org/ghostnet/rolling
+   ```
 
-   1. Load the snapshot in the node by running this command:
+1. Load the snapshot in the node by running this command:
 
-      ```bash
-      octez-node snapshot import snapshot_file
-      ```
+   ```bash
+   octez-node snapshot import snapshot_file
+   ```
+
+1. Install the Zcash parameters as described [Install Zcash Parameters](https://tezos.gitlab.io/introduction/howtoget.html#setup-zcash-params) in the Octez documentation.
 
 1. Start the node:
 
    ```
    octez-node run --rpc-addr 127.0.0.1:8732 --log-output="$HOME/octez-node.log"
    ```
 
+   At first launch, the node generates a fresh identity file used to identify itself on the network.
+   Then it bootstraps the chain, which takes a variable amount of time depending on how many blocks need to be loaded.
+   You don't need to wait for the node to bootstrap now.
+
 1. Ensure that the node runs persistently.
 Look up how to run programs persistently in the documentation for your operating system.
 You can also refer to [Run a persistent baking node](https://opentezos.com/node-baking/baking/persistent-baker/) on opentezos.com.
 
 1. Optional: When the node has bootstrapped and caught up with the current head block, you can delete the snapshot file to save space.
 
-At first launch, the node generates a fresh identity file used to identify itself on the network.
-Then it bootstraps the chain, which takes a variable amount of time depending on how many blocks need to be loaded.
-
 In the meantime, you can continue the baking infrastructure while the node is bootstrapping.
 Continue to [Step 2: Set up a baker account](/tutorials/join-dal-baker/prepare-account).

docs/tutorials/join-dal-baker/verify-rights.md

@@ -2,10 +2,10 @@
 title: "Step 5: Verify attestation rights"
 authors: Tezos core developers, Tim McMackin
 last_update:
-  date: 22 August 2024
+  date: 18 October 2024
 ---
 
-After the delay that you calculated in [Step 4: Run an Octez baking daemon](./run-baker), the baker starts receiving attestation rights, including the rights to attest that DAL data is available.
+After the delay that you calculated in [Step 4: Run an Octez baking daemon](/tutorials/join-dal-baker/run-baker), the baker starts receiving attestation rights, including the rights to attest that DAL data is available.
 
 Follow these steps to verify that your DAL node is receiving attestation rights:
 
@@ -39,6 +39,8 @@ Follow these steps to verify that your DAL node is receiving attestation rights:
 
    - Make sure that your node and baker are running.
 
+   - Verify that your DAL node is connected to the network by following the instructions in [Troubleshooting](https://tezos.gitlab.io/shell/dal_run.html#troubleshooting) in the Octez documentation.
+
    - Verify that the staked balance of your account is at least 6,000 tez by running the command `octez-client get staked balance for my_baker`.
    If the response is less than 6,000 tez, you have not staked enough.
    Ensure that you are registered as a delegate and stake more tez, retaining a small amount for transaction fees.
@@ -139,4 +141,4 @@ The Ghostnet faucet's address is `tz1a4GT7THHaGDiTxgXoatDWcZfJ5j29z5RC`, so you
 octez-client transfer 6000 from my_baker to tz1a4GT7THHaGDiTxgXoatDWcZfJ5j29z5RC
 ```
 
-For a summary of this tutorial, see [Conclusion](./conclusion).
+For a summary, see [Conclusion](/tutorials/join-dal-baker/conclusion).

sidebars.js

@@ -331,6 +331,22 @@ const sidebars = {
     },
     'tutorials/create-an-nft/nft-taquito',
     'tutorials/create-an-nft/nft-tznft',
+    {
+      type: 'category',
+      label: 'Join the DAL as a baker',
+      link: {
+        type: 'doc',
+        id: 'tutorials/join-dal-baker',
+      },
+      items: [
+        'tutorials/join-dal-baker/run-node',
+        'tutorials/join-dal-baker/prepare-account',
+        'tutorials/join-dal-baker/run-dal-node',
+        'tutorials/join-dal-baker/run-baker',
+        'tutorials/join-dal-baker/verify-rights',
+        'tutorials/join-dal-baker/conclusion',
+      ],
+    },
     {
       type: 'html',
       value: '<div>Advanced</div>',
@@ -407,22 +423,6 @@ const sidebars = {
         'tutorials/build-files-archive-with-dal/using-full-slot',
       ],
     },
-    {
-      type: 'category',
-      label: 'Join the DAL as a baker',
-      link: {
-        type: 'doc',
-        id: 'tutorials/join-dal-baker',
-      },
-      items: [
-        'tutorials/join-dal-baker/run-node',
-        'tutorials/join-dal-baker/prepare-account',
-        'tutorials/join-dal-baker/run-dal-node',
-        'tutorials/join-dal-baker/run-baker',
-        'tutorials/join-dal-baker/verify-rights',
-        'tutorials/join-dal-baker/conclusion',
-      ],
-    },
   ],
 };