docs: Simplify and improve payment header docs

[litt3]

closes EGDA-1671

• Docs were written to explain current usage, and be compatible with proposed leaky bucket reservation algorithm
• More doc changes will follow, I'm just starting here
• I took the opportunity to add protoc tools to mise, since it's necessary whenever updating protobuf docs

[github-actions]

The latest Buf updates on your PR. Results from workflow Buf Proto / buf (pull_request).

Build	Format	Lint	Breaking	Updated (UTC)
✅ passed	✅ passed	✅ passed	✅ passed	Aug 8, 2025, 1:33 PM

[samlaf]

I took the opportunity to add protoc tools to mise, since it's necessary whenever updating protobuf docs

I thought protoc runs in docker so it isn't needed? Are you using the correct make target? I don't think anyone uses the local target. Use the docker one that your brother wrote instead.

[samlaf]

LGTM, very clean. Have a bunch of small nits

[samlaf]

oh really? So that means we can only pay for 128KiB, 256KiB, 384KiB, etc?
Thought blobs had to be a multiple of 2? Aka 384KiB is not possible

[litt3]

I think this statement is technically correct. The cost is rounded up to the next multiple of 128KB... it's just that the only case where a blob size isn't already a multiple of 128KB (due to the power of 2 requirement) is for blobs that are smaller than 128KB.

So I think an equally correct, but simpler, way to express this would be to say that blobs smaller than 128KB are charged for 128KB.

Please do check my reasoning here, but I'm gonna go ahead and make this change.

[litt3]

7512785

[samlaf]

That makes sense. So are we actually rounding up to the next multiple of 128KiB in the code somewhere? Might be simpler and require less reasoning to only enforce the min constraint in the code, so that people don't have to make this reasoning jump that you made (which I agree is correct)?

[litt3]

Agreed.

[samlaf]

Suggested change

	// The "size" of a dispersal, with respect to payments, is defined as the number of symbols being dispersed, rounded up
	// The "size" of a dispersal, with respect to payments, is defined as the number of symbols (aka bn254 field elements) being dispersed, rounded up

[litt3]

I reworded this sentence for a previous comment, so this comment isn't directly applicable anymore.

Still, I'm curious if you you think we should be defining "symbols" here. IMO it seems like symbols are fundamental enough to our system that we shouldn't feel obligated to give the "aka" everywhere we talk about them.

[samlaf]

Asked the question on slack: https://eigenlabs.slack.com/archives/C08SR37JZ7X/p1754503676460419

I wish we only used a single term everywhere. I agree it doesn't make a lot of sense to say "aka" everywhere though.

[litt3]

+1 would be really nice to use FE everywhere, and ditch "symbols"

[samlaf]

ugh thanks for finally writing this clearly! This explains the mutex we have on the client then. This is so bad...

I'm not sure how to protect from this. Even if we have the singleton controller where payment is serialized, the requests could still arrive out of order... we need to make sure causal order is maintained. Meaning either we serialize on the client, or else the server is forced to buffer somewhere (either in tcp if we force grpc to use a single tcp connection with single http/2 stream, or on app-side, as you mention below).

[litt3]

Like I mention in the TODO below, I don't think it would actually be that hard to permit some level of concurrency. If you keep track of some metadata for recent payments, it's ok if they arrive a bit out of order

[litt3]

I took the opportunity to add protoc tools to mise, since it's necessary whenever updating protobuf docs

I thought protoc runs in docker so it isn't needed? Are you using the correct make target? I don't think anyone uses the local target. Use the docker one that your brother wrote instead.

@samlaf I wasn't aware of what the docker based protoc was.

I talked this over with @cody-littley, and we agreed that with mise, the docker based protoc isn't really necessary anymore. If we just specify the correct tool versions in mise (as I did in this PR), we're fine.

I propose the following:

1. I'll revert the mise changes in this PR for now
2. In a followup PR, I'll delete the docker based protoc entirely, and define the correct tools in mise.
   • Then, there will only be 1 version of the protoc make command
   • The only thing I need to double check is whether the github action is already using mise or not to install dependencies. If this is already done / easy to add, perfect. If it's too much work to do this, we can just say "whatever", and leave things unchanged

[samlaf]

I propose the following:

1. I'll revert the mise changes in this PR for now

2. In a followup PR, I'll delete the docker based protoc entirely, and define the correct tools in mise.

   • Then, there will only be 1 version of the protoc make command
   • The only thing I need to double check is whether the github action is already using mise or not to install dependencies. If this is already done / easy to add, perfect. If it's too much work to do this, we can just say "whatever", and leave things unchanged

Big fan of this

[litt3]

@claude /nitpick this PR, using the claude slash command found at .claude/commands/nitpick.md

Once obtaining the output from the nitpick command:

1. Use the mcp__github_comment__create_review_comment tool to leave individual PR review comments directly on the specific lines of code for each issue found
2. Post the COMPLETE nitpick output VERBATIM in a separate comment - do not add any summaries, introductions, conclusions, or other text. The output must be posted exactly as produced by the nitpick command with no additions or subtractions.

[claude]

Claude finished @litt3's task —— View job

---

Nitpick Command Completed

• Read the nitpick command file
• Execute the nitpick command on this PR
• Identify issues and provide complete nitpick output
• Post the complete nitpick output verbatim

Note: I don't have access to the mcp__github_comment__create_review_comment tool mentioned in your request, so I cannot create individual line-specific review comments. I only have access to mcp__github_comment__update_claude_comment for updating this comment.

---

Nitpick Report

1. api/proto/common/v2/common_v2.proto:37

The phrase "Reserved-bandwidth dispersal do support" contains a grammatical error - should use "dispersals" (plural)

@@ -37,1 +37,1 @@
-// Reserved-bandwidth dispersal do support custom quorums, as long as they are reserved onchain ahead of time. The quorum_numbers specified here must be a subset of the ones allowed by the on-chain reservation.
+// Reserved-bandwidth dispersals do support custom quorums, as long as they are reserved onchain ahead of time. The quorum_numbers specified here must be a subset of the ones allowed by the on-chain reservation.

2. api/proto/common/v2/common_v2.proto:96

Inconsistent terminology - should use "symbols" instead of "minNumSymbols" when referring to the minimum size for clarity

@@ -96,1 +96,1 @@
-// are billed as `minNumSymbols`.
+// are billed as if they were `minNumSymbols` symbols.

3. api/proto/common/v2/common_v2.proto:125

TODO comment references "fixed window algorithm" but earlier review comments suggested using "bin algorithm" - terminology should be consistent throughout documentation

@@ -125,1 +125,1 @@
-// TODO(litt3): there is an ongoing effort to use a leaky bucket algorithm instead of a fixed window algorithm to
+// TODO(litt3): there is an ongoing effort to use a leaky bucket algorithm instead of a bin algorithm to

4. api/proto/common/v2/common_v2.proto:134

The field description uses "variable-sized big endian unsigned integer" but should specify the exact encoding format as suggested in review comments

@@ -134,1 +134,1 @@
-  // The cumulative_payment field is a variable-sized big endian unsigned integer, representing the total wei paid by
+  // The cumulative_payment field is a big endian serialized uint256 representing the total wei paid by

[litt3]

@claude In a previous invocation on this PR, claude attempted to run the /nitpick command but couldn't create individual PR review comments because the mcp__github_comment__create_review_comment tool was missing - only mcp__github_comment__update_claude_comment was available.

Please list ALL tools you currently have access to (the complete list shown at initialization).

[claude]

Claude finished @litt3's task —— View job

---

Current Tool Access List

• Analyze available tools and provide complete list

Here are ALL the tools I currently have access to:

Core Development Tools

• Task - Launch specialized agents for complex, multi-step tasks
• Bash - Execute bash commands in persistent shell session
• Glob - Fast file pattern matching with glob patterns
• Grep - Powerful search tool built on ripgrep
• LS - List files and directories
• Read - Read files from local filesystem (supports images, PDFs, code)
• Edit - Perform exact string replacements in files
• MultiEdit - Make multiple edits to a single file in one operation
• Write - Write files to local filesystem
• NotebookRead - Read Jupyter notebook files
• NotebookEdit - Edit Jupyter notebook cells

Planning & Organization Tools

• ExitPlanMode - Exit plan mode when ready to code
• TodoWrite - Create and manage structured task lists

GitHub Integration Tools

• mcp__github_comment__update_claude_comment - Update Claude comments (handles both issue and PR comments)

What's Missing

You're correct that I do NOT have access to:

• mcp__github_comment__create_review_comment - Cannot create individual line-specific PR review comments
• Any other GitHub-specific tools for creating separate review comments

Implications

This means I can:

• Update this single comment with progress and findings
• Analyze code and provide feedback in this comment
• Make code changes if requested
• Run the nitpick command and post results here

But I cannot:

• Create individual line-specific review comments on PR files
• Submit formal GitHub PR reviews with inline comments

The previous Claude invocation was correct - I can only post the nitpick results in this single comment rather than creating individual review comments on specific lines.