docs: update Anchor documentation #739

chong-he · 2025-11-12T00:21:35Z

Update the docs to include mainnet configs, and also the FAQs. I am not completely sure about the technical correctness of the content, so feel free to correct me.

Thanks

claude-code-actions-sigp · 2025-11-12T00:21:55Z

Claude encountered an error —— View job

I'll analyze this and get back to you.

chong-he · 2025-11-12T00:29:31Z

docs/vocs.config.ts

    },
  ],
-
-  editLink: {


deleted this because the "edit this page" is not working

diegomrsantos · 2025-11-12T00:49:36Z

@claude review this PR

claude-code-actions-sigp · 2025-11-12T00:49:54Z

Claude finished @diegomrsantos's task —— View job

Review Progress

Read and analyze all changed files
Review FAQ content for technical accuracy
Review mainnet configuration changes
Review other documentation updates
Provide comprehensive feedback

Review Feedback

I've reviewed this documentation PR and found it to be a valuable addition overall. The FAQ section is comprehensive and the mainnet configurations are helpful. Below are my findings organized by file:

docs/docs/pages/faq.mdx ⭐ Major Addition

Positives:

Excellent comprehensive FAQ covering common user scenarios
Good use of real log examples to help users identify issues
Clear explanations of Anchor's role in the SSV network
Helpful troubleshooting guidance

Issues Found:

Typo on line 94: "THe following log" → should be "The following log"
Technical clarity needed (line 94): The FAQ mentions "target peer count (60)" but doesn't explain how this value is determined or where it comes from. Consider clarifying that this is the default maximum or providing context.
Grammar (line 150): "The operator will use public key" → should be "The operator will use the public key"
Grammar (line 150): "the private key is a proof that an operator holds the key corresponds to" → should be "the private key is proof that an operator holds the key that corresponds to"
Grammar (line 166): "you will to run as" → should be "you will need to run as"
Question for author: The FAQ states Anchor takes "about 15 minutes on mainnet to sync" - can someone verify this is accurate for mainnet? This seems fast for a full sync, though it may be referring to syncing Anchor's database (contract events) rather than the beacon/execution clients.

docs/docs/pages/installation.mdx ✅ Good Updates

Changes:

Added mainnet hardware requirements (32GB RAM, 2TB storage) - Correct and helpful
Updated version examples from v1.0.0-rc.1 to v1.1.0 - Appropriate
Fixed command examples: changed anchor node --version to anchor --version - Correct (node is a subcommand, not needed for version check)

No issues found in this file.

docs/docs/pages/running_an_operator.mdx ✅ Good Addition

Changes:

Added mainnet configuration example alongside Hoodi testnet
Removed reference to holesky (deprecated network)

Note: Line 92 shows --datadir ~/.anchor/hoodi in the mainnet example, but this appears to be a copy-paste error. For mainnet, it should be --datadir ~/.anchor/mainnet. However, looking more closely at the example, the comment says "All options used in this example (except for the password-file) are actually used with the default values and can therefore be omitted" - so this might be intentional to show it works regardless. Still, it's confusing. Consider either:

Changing to ~/.anchor/mainnet for clarity
Or adding a comment explaining this is just an example and the path should match your network

docs/docs/pages/running_a_validator_on_ssv.mdx ✅ Minor Improvements

Changes:

Clarified "deposit ETH (minimum 32 ETH for a validator)" - Good addition
Simplified link text from "Staking Deposit CLI" to "ethstaker-deposit-cli" (matches actual repo name) - Good
Removed redundant sentence "Each link contains more detailed information on the process" - Good cleanup

No issues found in this file.

docs/docs/pages/index.mdx, migrate_to_anchor.mdx, vocs.config.ts ✅ Good Updates

Changes:

Updated version references from v1.0.0-rc.1 to v1.0.0
Updated GitHub stars count (50 → 54)
Fixed broken link in migrate_to_anchor.mdx
Removed non-working "edit this page" feature

No issues found in these files.

Summary

Overall Assessment: This is a solid documentation improvement that adds valuable mainnet information and comprehensive FAQs. The changes are technically sound with only minor grammar/typo issues.

Required Changes:

Fix typo: "THe" → "The" (docs/docs/pages/faq.mdx:94)
Fix grammar: "you will to run" → "you will need to run" (docs/docs/pages/faq.mdx:166)

Recommended Changes:

Add missing articles: "use public key" → "use the public key" (docs/docs/pages/faq.mdx:150)
Fix grammar: "key corresponds to" → "key that corresponds to" (docs/docs/pages/faq.mdx:150)
Clarify the datadir path in the mainnet example (docs/docs/pages/running_an_operator.mdx:92) - currently shows ~/.anchor/hoodi for mainnet
Consider adding context about the "60" peer count mentioned in FAQ
Consider verifying the "15 minutes on mainnet" sync time claim

Technical Accuracy: The mainnet configurations (32GB RAM, 2TB storage) align with standard Ethereum node requirements. The FAQ content demonstrates good understanding of Anchor's architecture and common issues.

Great work on this documentation update! 🎉

… update-book

diegomrsantos · 2025-11-12T13:25:02Z

docs/docs/pages/faq.mdx

+Anchor is like a validator client.
+
+Typically, by having Ethereum validators, you will run an execution client, a beacon node and a validator client.
+
+However, if you run Anchor, you do not have to run the validator client. This is because, Anchor will connect with other SSV clients (which can be Anchor or the go-ssv client) to perform validator duties.


I don't know if we want this not to be too technical, but otherwise here is an inspiration:

The SSV Network (Secret Shared Validator network) is a protocol built on Ethereum that allows a validator’s duties to be distributed among multiple operators (node instances) in a trustless way. In SSV, a set of operators collectively run an Ethereum validator by sharing the key (via cryptographic secret sharing) and coordinating actions via a consensus algorithm (a variant of BFT). An SSV node is essentially a specialized client that an operator runs, which communicates with other operators in a cluster to perform validator duties.

Thanks for the review. I combine with the first question, revised made in 828c955

dknopik

Nice, thanks so much! Added a few corrections for typos and some technical notes.

dknopik · 2025-11-13T10:43:22Z

docs/docs/pages/faq.mdx

+INFO Processed contract events from block 1598180      log_count=0
+```
+
+When attestation happens, Anchor will log:


When an attestation

dknopik · 2025-11-13T10:43:40Z

docs/docs/pages/faq.mdx

+
+## How do I know if Anchor is working normally?
+
+A synced and working Anchor has the following logs:


working Anchor node has

dknopik · 2025-11-13T10:55:57Z

docs/docs/pages/faq.mdx

+
+<div id="how-not-working" />
+
+## Why the validator is not attesting?


Why is the validator

dknopik · 2025-11-13T10:56:43Z

docs/docs/pages/faq.mdx

+
+## Why the validator is not attesting?
+
+One reason the validator that you operate on is not performing its duties could be due to some operators are offline. For example, in a cluster of 4 operators, at most 1 operator can be offline.


some operators being offline

dknopik · 2025-11-13T10:57:37Z

docs/docs/pages/faq.mdx

+WARN No attestations were published
+```
+
+If otherwise the logs on Anchor are normal, then there is no action required on your side. Once other operators came back online, the validator should resume attesting.


This is not quite correct. For example, if we can't find a good set of peers (or even no peers at all), one might also see the logs above.

dknopik · 2025-11-13T16:41:07Z

docs/docs/pages/faq.mdx

+WARN Waiting for EL to finish syncing
+```
+The error or warning Logs will go away once the beacon node and the execution client are synced.
+Anchor will sync simultaneously at the same time and will be ready to perform duty soon when the beacon node and the execution client are synced.


Anchor will not sync while the EL is not synced

dknopik · 2025-11-13T16:42:05Z

docs/docs/pages/faq.mdx

+WARN Round timer elapsed
+```
+
+and the node is already at the target peer count (60), you may consider increasing the peer count using `--target-peers`.


as the target peer count is dynamic, claiming 60 here is incorrect

dknopik · 2025-11-13T16:43:03Z

docs/docs/pages/faq.mdx

+
+
+
+
+


remove additional blank lines

chong-he · 2025-11-13T23:43:04Z

Nice, thanks so much! Added a few corrections for typos and some technical notes.

Thanks for the meticulous review, as always. I have address all comments in c72bc1b. Feel free to review and comment or point out any errors

chong-he added 6 commits November 11, 2025 11:24

update book to include mainnet

c7d0f40

update doc

10dd7df

add some faqs

23aa754

add faq

968aa4c

add hooxi

3fbd58f

revise

0c3cec7

chong-he changed the title ~~Update Anchor documentation~~ docs: update Anchor documentation Nov 12, 2025

chong-he added the documentation Improvements or additions to documentation label Nov 12, 2025

chong-he commented Nov 12, 2025

View reviewed changes

docs/vocs.config.ts

},

],

editLink: {

Copy link

Member Author

chong-he Nov 12, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

deleted this because the "edit this page" is not working

diegomrsantos and others added 5 commits November 12, 2025 01:50

Merge branch 'unstable' into update-book

c063d1e

revise faq a bit

be4cf7c

Merge branch 'update-book' of https://github.com/chong-he/anchor into…

317aeff

… update-book

address Claude comments

cba433a

revise

3b283e5

diegomrsantos reviewed Nov 12, 2025

View reviewed changes

revise

828c955

dknopik reviewed Nov 13, 2025

View reviewed changes

address review comments

c72bc1b

grammar

b5c5cfe


		## How do I know if Anchor is working normally?

		A synced and working Anchor has the following logs:


		<div id="how-not-working" />

		## Why the validator is not attesting?


		## Why the validator is not attesting?

		One reason the validator that you operate on is not performing its duties could be due to some operators are offline. For example, in a cluster of 4 operators, at most 1 operator can be offline.

docs: update Anchor documentation #739

Are you sure you want to change the base?

docs: update Anchor documentation #739

Uh oh!

Conversation

chong-he commented Nov 12, 2025

Uh oh!

claude-code-actions-sigp bot commented Nov 12, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

diegomrsantos commented Nov 12, 2025

Uh oh!

claude-code-actions-sigp bot commented Nov 12, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Review Progress

Review Feedback

docs/docs/pages/faq.mdx ⭐ Major Addition

docs/docs/pages/installation.mdx ✅ Good Updates

docs/docs/pages/running_an_operator.mdx ✅ Good Addition

docs/docs/pages/running_a_validator_on_ssv.mdx ✅ Minor Improvements

docs/docs/pages/index.mdx, migrate_to_anchor.mdx, vocs.config.ts ✅ Good Updates

Summary

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

dknopik left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

chong-he commented Nov 13, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

claude-code-actions-sigp bot commented Nov 12, 2025 •

edited

Loading

claude-code-actions-sigp bot commented Nov 12, 2025 •

edited

Loading