Review the tutorial join-dal-as-baker

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

@@ -2,17 +2,19 @@
 title: "Step 4: Run an Octez baking daemon"
 authors: Tezos core developers, Tim McMackin
 last_update:
-  date: 27 August 2024
+  date: 2 December 2024
 ---
 
 Now that you have a DAL node, you can run a baking daemon that can attest to DAL data or restart an existing baking daemon to connect it to the DAL node.
 
 1. To run a baking daemon that connects to the DAL, start it as usual and pass the URL to your DAL node to it with the `--dal-node` argument:
 
    ```bash
-   octez-baker-PsParisC run with local node "$HOME/.tezos-node" my_baker --liquidity-baking-toggle-vote pass --adaptive-issuance-vote on --dal-node http://127.0.0.1:10732 >> "$HOME/octez-baker.log" 2>&1
+   octez-baker-PsParisC run with local node "$HOME/.tezos-node" my_baker --liquidity-baking-toggle-vote pass --adaptive-issuance-vote on --dal-node http://127.0.0.1:10732
    ```
 
+   You may append `>>"$HOME/octez-baker.log" 2>&1` to redirect its output in a log file.
+
 1. Ensure that the baker 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.
@@ -36,7 +38,7 @@ You can also refer to [Run a persistent baking node](https://opentezos.com/node-
 
    This command returns all of the topics that the baker is subscribed to in the format `{"slot_index":<index>,"pkh":"<ADDRESS OF BAKER>"}` where `index` varies between `0` included and the number of slot indexes excluded.
 
-   You can also look at the baker logs to see if it injects the expected operations. At each level, the baker is expected to:
+   You can also look at the baker logs to see if it injects the expected operations. At each level, the baker is expected to do a subset of these operations:
 
       - Receive a block proposal (log message: "received new proposal ... at level ..., round ...")
       - Inject a preattestation for it (log message: "injected preattestation ... for my_baker (&lt;address&gt;) for level ..., round ...")
@@ -91,3 +93,11 @@ The amount of tez that the account stakes determines how often it is called on t
 Therefore, staking more tez brings more rewards but does not reduce the attestation delay.
 
 :::
+
+## Checking for (pre-)attestations
+
+After the delay computed above has passed, **the baker log** (not the Octez node log, neither the DAL node log) should contain lines about:
+
+- Consensus pre-attestations: `injected preattestation ...`
+- Consensus attestations: `injected attestation ...`
+- Attach DAL attestations: `ready to attach DAL attestation ...`

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

@@ -2,12 +2,12 @@
 title: "Step 3: Run an Octez DAL node"
 authors: Tezos core developers, Tim McMackin
 last_update:
-  date: 27 November 2024
+  date: 2 December 2024
 ---
 
 The DAL node is responsible for temporarily storing data and providing it to bakers and Smart Rollups.
 
-1. Ensure that the port that the DAL node runs on is accessible from outside its system.
+1. Ensure that the port that the DAL node runs on (by default, 11732) is accessible from outside its system.
 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.
 
@@ -16,17 +16,19 @@ For example, this command initializes the DAL node with the address of a local `
 
    ```bash
    octez-dal-node config init --endpoint http://127.0.0.1:8732 \
-     --attester-profiles=tz1QCVQinE8iVj1H2fckqx6oiM85CNJSK9Sx
+     --attester-profiles=tz1...
    ```
 
    You cannot use the `my_baker` alias from the Octez client as in the previous section, so you must specify the address of your baker's account explicitly.
 
 1. Start the DAL node by running this command:
 
    ```bash
-   octez-dal-node run >> "$HOME/octez-dal-node.log" 2>&1
+   octez-dal-node run
    ```
 
+   You may append `>>"$HOME/octez-dal-node.log" 2>&1` to redirect its output in a log file.
+
    This, too, may take some time to launch the first time because it needs to generate a new identity file, this time for the DAL network.
 
    If you need to change the address or port that the DAL node listens for connections to other nodes on, pass the `--public-addr` argument.
@@ -38,6 +40,9 @@ For example, this command initializes the DAL node with the address of a local `
    curl http://localhost:10732/p2p/points/info
    ```
 
+   where `10732` is the default port on which the DAL node serves RPC calls.
+   You can override it with the `--rpc-addr` argument.
+
    The response lists the network connections that the DAL node has, as in this example:
 
    ```json

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

@@ -2,7 +2,7 @@
 title: "Step 1: Run an Octez node"
 authors: Tezos core developers, Tim McMackin
 last_update:
-  date: 21 October 2024
+  date: 2 December 2024
 ---
 
 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.
@@ -44,9 +44,10 @@ For example, to initialize it for Ghostnet, run this command:
    ```
 
    By default, the node stores its data in the folder `$HOME/.tezos-node`.
+   If this directory is not empty, you may have need to rename it (to keep its data) or remove it.
 
 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:
+For example, the command to download a Ghostnet snapshot from the European servers might look like this:
 
    ```bash
    wget -O snapshot_file https://snapshots.eu.tzinit.org/ghostnet/rolling
@@ -63,16 +64,18 @@ For example, the command to download a Ghostnet snapshot from the EU servers mig
 1. Start the node:
 
    ```
-   octez-node run --rpc-addr 127.0.0.1:8732 --log-output="$HOME/octez-node.log"
+   octez-node run --rpc-addr 127.0.0.1:8732
    ```
 
+   You may add option `--log-output="$HOME/octez-node.log"` to redirect its output in a log file.
+
    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.
+You can also refer to [Setting up Octez Services](https://tezos.gitlab.io/introduction/services.html) in the Octez documentation.
 
 1. Optional: When the node has bootstrapped and caught up with the current head block, you can delete the snapshot file to save space.
 

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

@@ -1,27 +1,32 @@
 ---
-title: "Step 5: Verify attestation rights"
+title: "Step 5: Troubleshooting"
 authors: Tezos core developers, Tim McMackin
 last_update:
-  date: 18 October 2024
+  date: 2 December 2024
 ---
 
-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:
+If after the delay that you calculated in [Step 4: Run an Octez baking daemon](/tutorials/join-dal-baker/run-baker), the baker does not start inserting consensus (pre-)attestations and DAL attestations, follow these instructions to diagnose and fix the issue.
 
 1. Record the address of your baker account in an environment variable so you can use it for commands that cannot get addresses by their Octez client aliases:
 
    ```bash
    MY_BAKER="$(octez-client show address my_baker | head -n 1 | cut -d ' ' -f 2)"
    ```
 
-1. Run this command to get the attestation rights for the baker in the current cycle:
+1. Run these commands to get the (consensus) attestation rights for the baker in the current cycle:
 
-   ```bash
-   octez-client rpc get /chains/main/blocks/head/helpers/attestation_rights?delegate="$MY_BAKER"
-   ```
+   1. Get the current cycle by running this command:
+
+      ```bash
+      octez-client rpc get /chains/main/blocks/head | jq | grep '"cycle"'
+      ```
+
+   1. Use the current cycle as the `<current-cycle>` parameter in this command.
+   Beware, this command may take several minutes to finish if the list of rights is long:
 
-   If the baker has no rights, the command returns an empty array: `[]`.
+      ```bash
+      octez-client rpc get "/chains/main/blocks/head/helpers/attestation_rights?delegate=$MY_BAKER&cycle=<current-cycle>"
+      ```
 
    When the baker has attestation rights, the command returns information about them, as in this example:
 
@@ -30,42 +35,29 @@ Follow these steps to verify that your DAL node is receiving attestation rights:
     "delegates":
       [ { "delegate": "tz1Zs6zjxtLxmff51tK2AVgvm4PNmdNhLcHE",
           "first_slot": 280, "attestation_power": 58,
-          "consensus_key": "tz1Zs6zjxtLxmff51tK2AVgvm4PNmdNhLcHE" } ] } ]
+          "consensus_key": "tz1Zs6zjxtLxmff51tK2AVgvm4PNmdNhLcHE" } ] }
+      ...
+    ]
    ```
 
-   If the command returns an empty array (`[]`), the delay may not be over.
+   If the command returns an empty array (`[]`), the baker has no rights in the specified cycle.
 
-   If the delay has expired and you still haven't received attestation rights, try these troubleshooting steps:
+   - Check to see if you will receive rights two cycles in the future, using commands similar to those above for the current cycle.
+   You can see who will receive rights no farther than two cycles in the future.
+   This number of cycles is set by the `consensus_rights_delay` network parameter.
 
-   - Make sure that your node and baker are running.
+     If this returns a list of future attestation rights for your account, you must wait for that cycle to arrive.
 
-   - 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.
+   - Otherwise, make sure that your node and baker are running.
 
    - 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.
    If necessary you can get more from the faucet.
 
-   - Check to see if you will receive rights two cycles in the future:
-
-      1. Run this command to get the current cycle:
-
-         ```bash
-         octez-client rpc get /chains/main/blocks/head | jq | grep '"cycle"'
-         ```
-
-      1. Add two to the cycle and run this command to see what rights your account will have in that cycle.
-      For example, if the current cycle is 149, run this command to get its rights in cycle 151:
-
-         ```bash
-         octez-client rpc get /chains/main/blocks/head/helpers/baking_rights\?cycle=151\&delegate=$MY_BAKER\&max_round=2
-         ```
-
-         If this command returns a list of future attestation rights for your account, the delay has not expired yet and you must wait for that cycle to arrive.
-
    - Check to see if you are active and re-register as a delegate if necessary:
 
-      1. Run this command to see if your account is active:
+      1. Run this command to see if your account is marked as inactive:
 
          ```bash
          octez-client rpc get /chains/main/blocks/head/context/delegates/$MY_BAKER/deactivated
@@ -79,20 +71,34 @@ Follow these steps to verify that your DAL node is receiving attestation rights:
          octez-client register key my_baker as delegate
          ```
 
-      1. Find when the next cycle will start by going to a block explorer such as https://ghostnet.tzkt.io.
-      For example, this drop-down shows that the next cycle starts in 29 minutes:
+      When the next cycle starts, Tezos calculates attestation rights for two cycles in the future and includes your baker.
+
+      You can find when the next cycle will start by running these commands:
 
-         <img src="/img/tutorials/tzkt-next-cycle.png" alt="The TZKT block explorer, showing information about the current cycle" style={{width: 300}} />
+        1. Find the last level of the current cycle by running this command:
 
-         When this cycle starts, Tezos calculates attestation rights for a certain number of cycles in the future and includes your baker.
-         The number of cycles is the `consensus_rights_delay` network parameter.
+           ```bash
+           octez-client rpc get "/chains/main/blocks/head/helpers/levels_in_current_cycle"
+           ```
 
-      1. Wait for your baker to receive attestation rights.
+         1. Pass the last level of the cycle as the `<last-block>` parameter in this command:
 
-1. When your baker receives attestation rights as determined by the `/chains/main/blocks/head/helpers/attestation_rights` RPC call, run this command to get the shards that are assigned to your DAL node:
+            ```bash
+            octez-client rpc get "/chains/main/blocks/head/helpers/attestation_rights?level=<last-block>" | grep '"estimated_time"'
+            ```
+
+            The response shows the estimated time when the cycle will end.
+
+
+      You can also find when the next cycle will start by going to a block explorer such as https://ghostnet.tzkt.io.
+      For example, this drop-down shows that the next cycle starts in 29 minutes:
+
+        <img src="/img/tutorials/tzkt-next-cycle.png" alt="The TZKT block explorer, showing information about the current cycle" style={{width: 300}} />
+
+1. When your baker receives attestation rights as determined by the `/chains/main/blocks/head/helpers/attestation_rights` RPC call, run this command to get the shards that are assigned to your DAL node for the next block:
 
    ```bash
-   octez-client rpc get /chains/main/blocks/head/context/dal/shards?delegates=$MY_BAKER
+   octez-client rpc get "/chains/main/blocks/head/context/dal/shards?delegates=$MY_BAKER"
    ```
 
    The response includes your account's address and a list of shards, as in this example:
@@ -104,7 +110,21 @@ Follow these steps to verify that your DAL node is receiving attestation rights:
 
    These shards are pieces of data that the baker is assigned to attest.
 
-1. Verify the baker's activity on the Explorus block explorer by going to the Consensus Ops page at https://explorus.io/consensus_ops, selecting Ghostnet, and searching for your address.
+   Note that you have to potentially execute the command above during many block levels in order to find a block where you have some shards assigned.
+   There is currently no simple command line to get all your DAL rights for a whole cycle, but you can call it in a loop for future levels until you see some shards.
+   First, get the current level:
+
+   ```bash
+   octez-client rpc get /chains/main/blocks/head | jq '.header.level'
+   ```
+
+   and pass it as the `<current-level>` parameter in this command:
+
+   ```bash
+   l=<current-level>; while true; echo $l; do octez-client rpc get "/chains/main/blocks/head/context/dal/shards?delegates=$MY_BAKER&level=$l"; l=$((l+1)); done
+   ```
+
+1. Verify the baker's activity on the Explorus block explorer by going to the Consensus Ops page at https://explorus.io/consensus_ops, selecting Ghostnet, and searching for your address (only the first few characters).
 
    For example, this screenshot shows consensus operations that include DAL attestations, indicated by a number in the "DAL attestation bitset" column.
 
@@ -113,8 +133,12 @@ Follow these steps to verify that your DAL node is receiving attestation rights:
    If there is no DAL attestation, the block explorer shows a document icon with an X in it: ![](/img/tutorials/dal-explorus-no-attestation-icon.png).
    This icon can appear before the bakers complete attestations and then turn into a binary number when they attest.
 
-Now you have a complete DAL baking setup.
-Your baker is attesting to the availability of DAL data and the DAL node is sharing it to Smart Rollups across the network.
+   If you see the rights, you will see the attestations in the baker's log when scheduled. Now you have a complete DAL baking setup.
+   Your baker is attesting to the availability of DAL data and the DAL node is sharing it to Smart Rollups across the network.
+
+If you don't see DAL attestation rights:
+
+   - 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.
 
 ## Optional: Unstaking your tez and receiving your baking rewards