Blobstream docs feedback

[rootulp]

I have some feedback from reading the first four page of Blobstream docs

1. ✅ The links to these two ADRs seems out of place. The topics of: valsets and data commitments haven't been introduced yet so this assumes some prior knowledge.

   docs/nodes/blobstream-intro.md

   Lines 36 to 41 in 756234b

   	The specification of Blobstream `Valset`s, which track the Celestia validator set
   	changes, can be found in [ADR 002](https://github.com/celestiaorg/celestia-app/blob/main/docs/architecture/adr-002-qgb-valset.md).
   	Blobstream data commitments, which represent commitments over sets of blocks
   	defined by a data commitment window, are discussed more in-depth in
   	[ADR 003](https://github.com/celestiaorg/celestia-app/blob/main/docs/architecture/adr-003-qgb-data-commitments.md).

2. ✅ The term ValSet is written with inconsistent casing. Sometimes it is Valset. Sometimes it is ValSet. We should use consistent casing. IMO the best form to use is ValidatorSet
3. ✅ In this diagram, why is there an arrow from Celestia validator node to Blobstream relayer? That line isn't explained in the text.

   docs/nodes/blobstream-intro.md

   Line 52 in 756234b

   

4. ✅ The Golang version for Blobstream claims 1.20.2 but the repo uses 1.21 so I think this constant needs to be bumped

   docs/nodes/blobstream-binary.md

   Line 18 in 756234b

   1. [Install Go](https://go.dev/doc/install) {{constants.golangBlobstream}}

5. ✅ https://docs.celestia.org/nodes/blobstream-binary contains content copy + pasted from the README of blobstream. I don't think it should contain the Contributing section b/c that's applicable to readers of the Github README but not as applicable to readers of the docs (who just want to run the binary).
6. ✅ The blockspace race is over and I don't think the network is still supported. Proposal to remove:

   docs/nodes/blobstream-orchestrator.md

   Lines 25 to 27 in 756234b

   	Bootstrapper for the Blockspace Race is:
   	- `/dns/bootstr-incent-1.celestia.tools/tcp/30000/p2p/12D3KooWSGZ2LXW2soQFHgU82uLfN7pNW5gMMkTnu1fhMXG43TvP`

7. ✅ What does "This latter" mean?

   docs/nodes/blobstream-orchestrator.md

   Line 45 in 756234b

   - Access to your EVM address private key. This latter doesn't need to be funded in any network. If yours is not yet set, check the [register an EVM address](#register-evm-address) section.

8. ✅ "The team" is a bit vague here. Proposal to delete that sentence entirely.

   docs/nodes/blobstream-orchestrator.md

   Line 46 in 756234b

   - A list of bootstrappers for the P2P network. These will be shared by the team for every network we plan on supporting.

9. ✅ There are no flags listed in

   docs/nodes/blobstream-orchestrator.md

   Lines 112 to 121 in 756234b

   	The orchestrator accepts the following flags:
   	```sh
   	blobstream orchestrator start --help
   	Starts the Blobstream orchestrator to sign attestations
   	Usage:
   	blobstream orchestrator start <flags> [flags]
   	```

10. ✅ What does "find the latter" mean here? https://github.com/celestiaorg/docs/blob/756234bb6be524c2cc8f7ba674f645d7cd8b0a1e/nodes/blobstream-orchestrator.md?plain=1#L123C31-L123C31
11. ✅ I think this section should come before the start command:

    docs/nodes/blobstream-orchestrator.md

    Line 139 in 756234b

    ### Open the P2P port

12. ✅ "This latter" doesn't make sense

    docs/nodes/blobstream-orchestrator.md

    Line 163 in 756234b

    When creating a validator, a random EVM address corresponding to its operator is set in the Blobstream state. This latter will be used by the orchestrator to sign attestations. And since validators will generally not have access to its corresponding private key, that address needs to be edited with one whose private key is known to the validator operator.

13. ✅ Remove this note about BSR

    docs/nodes/blobstream-orchestrator.md

    Line 280 in 756234b

    Note: A validator set change is triggered if more than 5% of the total staking power of the network changes (0.5% for BSR). This means that even if you change your EVM address, and you don't see your orchestrator signing, it's alright. Just wait until the validator set changes, and then your orchestrator will automatically start signing.

14. ✅ Multiple other instances of "This latter" which don't make sense.

cc: @sweexordious

[jcstein]

thank you for this feedback, super helpful! notes on current plan for blobstream for context:

1. i’m working on consolidating these two pages and finding a home for the intro page, what do you think of that? at least, i’d like to make nodes/blobstream-intro more accurate based on this from github

• https://docs.celestia.org/developers/blobstream
• https://docs.celestia.org/nodes/blobstream-intro

2. I'm thinking of keeping nodes/blobstream-* to be only things that are relevant to running the orchestrator-relayer. on that note, [the docs that are imported from orchestrator-relayer repo]

• docs/importBlobstream.mjs

  Lines 5 to 20 in 756234b

  	{
  	url: 'https://raw.githubusercontent.com/celestiaorg/orchestrator-relayer/main/docs/deploy.md',
  	fileName: 'blobstream-deploy.md',
  	},
  	{
  	url: 'https://raw.githubusercontent.com/celestiaorg/orchestrator-relayer/main/docs/keys.md',
  	fileName: 'blobstream-keys.md',
  	},
  	{
  	url: 'https://raw.githubusercontent.com/celestiaorg/orchestrator-relayer/main/docs/orchestrator.md',
  	fileName: 'blobstream-orchestrator.md',
  	},
  	{
  	url: 'https://raw.githubusercontent.com/celestiaorg/orchestrator-relayer/main/docs/relayer.md',
  	fileName: 'blobstream-relayer.md',
  	},

  and need to be edited in the source there before being added to docs site are:
• https://docs.celestia.org/nodes/blobstream-orchestrator
• https://docs.celestia.org/nodes/blobstream-keys
• https://docs.celestia.org/nodes/blobstream-relayer
• https://docs.celestia.org/nodes/blobstream-deploy
  • one that is missing from this import is the bootstrapper.md doc and i think it may be something that should be in the node section

[rootulp]

i’m working on consolidating these two pages and finding a home for the intro page, what do you think of that?

Makes sense to me.

the docs that are imported from orchestrator-relayer repo

ahh so does that mean the issues I suggested above should not be fixed in the docs repo but should be fixed in the orchestrator-relayer repo?

[jcstein]

I'm going to pushed to a branch shortly with a reformatted blobstream-intro and updated blobstream-binary, addressing your points 1-5

ahh so does that mean the issues I suggested above should not be fixed in the docs repo but should be fixed in the orchestrator-relayer repo?

the others are still relevant to docs, but just need to be edited in orchestrator-relayer first, then pulled in (i'll get to this automation eventually, for now the script works)

i’m working on consolidating these two pages and finding a home for the intro page, what do you think of that?

Makes sense to me.

I think i'm going to consoildate blobstream-intro and blobstream-binary so people don't end up on the overview thinking it's the overview of blobstream for developers

[jcstein]

I will make changes for 6-14 next week (if SweeXordious doesn't beat me to it), 1-5 addressed in #1261

[rach-id]

👍 👍 @jcstein Let me know if you need any information about these changes or want me to handle any of them

[jcstein]

I'll go ahead and update orch-relayer repo today and make a PR @sweexordious

[rach-id]

Awesome, thanks a lot

[jcstein]

you're welcome! for "10. What does "find the latter" mean here? https://github.com/celestiaorg/docs/blob/756234bb6be524c2cc8f7ba674f645d7cd8b0a1e/nodes/blobstream-orchestrator.md?plain=1#L123C31-L123C31" @sweexordious what is "latter" referring to here?

[rach-id]

@jcstein the orchestrator's TOML config file

[jcstein]

celestiaorg/orchestrator-relayer#603 🫡