docs: next-release fee documentation (integration of #425, #439, #432, #436)#441
docs: next-release fee documentation (integration of #425, #439, #432, #436)#441MuncleUscles wants to merge 15 commits into
Conversation
…p-empirical, can-take-minutes nuance, leave-and-track best practice, queue position
Add three protocol/reference docs pages sourced from genlayer-consensus v0.6-dev: - Protocol Randomness (concept): how the seed-chained, ECDSA-signature + keccak256 randomness mechanism drives stake-weighted validator/leader selection, per-recipient seed rotation, replay-resistance, and the acknowledged grinding / initial-seed limitations. - Deterministic Violations & Tribunals (concept): hash-mismatch detection of provably-wrong deterministic results, the liveness (idleness) vs safety (violation) split, the automatic tribunal adjudication, and the slashing (5% leader / 1% validator, 2-epoch delay) plus the ADR-025 designed permanent-ban outcome. - Error & Revert Reference (developer reference): the 280 custom errors from the consensus ABI, each with its keccak256 4-byte selector, a one-line meaning and cause/fix, grouped by area, plus common encoding pitfalls (RLP-wrapped write calldata). Wire all three into their _meta.json files and cross-link from the appeal-process, slashing, and staking-guide pages.
New guide under Frontend & SDK Integration covering how the developer NFT is minted, how it earns from the fee share and inflation share, when rewards become claimable, and how to read/claim with GenLayerJS. Uses the new getDeveloperNft / getClaimableRewardsFrom* / claimNft* actions.
# Conflicts: # pages/developers/decentralized-applications/_meta.json
# Conflicts: # pages/developers/decentralized-applications/_meta.json
✅ Deploy Preview for genlayer-docs ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
📝 WalkthroughWalkthroughAdded documentation and navigation for developer fees, transaction integration, NFT rewards, custom errors, optimistic-democracy concepts, protocol randomness, and validator operations, including operator wallet funding requirements. ChangesDeveloper documentation
Optimistic democracy concepts
Validator operations
Estimated code review effort: 3 (Moderate) | ~30 minutes Possibly related PRs
Suggested reviewers: 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
There was a problem hiding this comment.
Actionable comments posted: 5
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@pages/developers/decentralized-applications/developer-nft-rewards.mdx`:
- Around line 112-123: Ensure the no-NFT guard around getDeveloperNft remains
active before the feeRewards and inflationRewards examples: return or throw when
nft is null, or move both getClaimableRewardsFromFees and
getClaimableRewardsFromInflation calls inside the non-null branch so nft.nftId
is accessed safely.
- Around line 137-155: Update the “Claim everything” description for
claimNftRewards to state that it claims accumulated fee rewards plus inflation
for up to 50 finalized epochs. Explain that callers must repeat the claim, or
use claimNftEpochs in batches, when additional finalized epochs remain.
In
`@pages/developers/decentralized-applications/fee-profiling-and-estimation.mdx`:
- Around line 23-46: The profile example conflicts with the documented default
headroom of 1.25. Update the example under “Profiles are keyed by contract
method name” to show headroom-adjusted execution budget and message fees, or
explicitly label it as a raw/headroom-1.0 example; keep rotations unchanged if
headroom does not apply to that field.
In `@pages/developers/decentralized-applications/fees-and-transaction-kit.mdx`:
- Line 3: Qualify the mandatory fee-parameter guidance in the fees and
transaction documentation to exclude gasless Studio deployments, which may
submit transactions without fees. Update the introductory statement to apply
only to fee-charging networks or explicitly reference the gasless exception
described in fee-outcomes-and-debugging.mdx.
In
`@pages/understand-genlayer-protocol/core-concepts/optimistic-democracy/protocol-randomness.mdx`:
- Around line 41-55: The Known Limitations section overstates randomness after
the first selection by claiming full unpredictability is restored. In the
“Initial-seed predictability” bullet, replace that claim with wording that
subsequent signature-driven advances reduce dependence on the initial
block-derived seed, while acknowledging the residual grinding influence
described in “Grinding at the margins.”
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: 7b671519-8ff2-4849-97ee-981a521b7001
📒 Files selected for processing (16)
pages/developers/_meta.jsonpages/developers/decentralized-applications/_meta.jsonpages/developers/decentralized-applications/developer-nft-rewards.mdxpages/developers/decentralized-applications/fee-outcomes-and-debugging.mdxpages/developers/decentralized-applications/fee-profiling-and-estimation.mdxpages/developers/decentralized-applications/fees-and-transaction-kit.mdxpages/developers/decentralized-applications/transaction-kit-integration.mdxpages/developers/error-reference.mdxpages/developers/staking-guide.mdxpages/understand-genlayer-protocol/core-concepts/optimistic-democracy/_meta.jsonpages/understand-genlayer-protocol/core-concepts/optimistic-democracy/appeal-process.mdxpages/understand-genlayer-protocol/core-concepts/optimistic-democracy/deterministic-violations-and-tribunals.mdxpages/understand-genlayer-protocol/core-concepts/optimistic-democracy/protocol-randomness.mdxpages/understand-genlayer-protocol/core-concepts/optimistic-democracy/slashing.mdxpages/validators/_meta.jsonpages/validators/network-keeper-roles.mdx
| ```typescript | ||
| // All-time accumulated fee rewards not yet claimed. | ||
| const feeRewards = await client.getClaimableRewardsFromFees({ | ||
| nftId: nft.nftId, | ||
| }); | ||
|
|
||
| // Inflation rewards over the next `numberOfEpochsToClaim` finalized epochs, | ||
| // starting from lastClaimedEpoch + 1. | ||
| const inflationRewards = await client.getClaimableRewardsFromInflation({ | ||
| nftId: nft.nftId, | ||
| numberOfEpochsToClaim: 50n, | ||
| }); |
There was a problem hiding this comment.
🩺 Stability & Availability | 🟠 Major | ⚡ Quick win
Keep the no-NFT guard active for subsequent examples.
getDeveloperNft can return null, but the next snippet unconditionally accesses nft.nftId. A first-time developer following these examples will hit a runtime error. Return/throw after the null case or place the read and claim examples inside the non-null branch.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@pages/developers/decentralized-applications/developer-nft-rewards.mdx` around
lines 112 - 123, Ensure the no-NFT guard around getDeveloperNft remains active
before the feeRewards and inflationRewards examples: return or throw when nft is
null, or move both getClaimableRewardsFromFees and
getClaimableRewardsFromInflation calls inside the non-null branch so nft.nftId
is accessed safely.
| **Claim everything** — sweeps all accumulated fee rewards plus inflation for every finalized epoch: | ||
|
|
||
| ```typescript | ||
| const txHash = await client.claimNftRewards({ | ||
| nftId: nft.nftId, | ||
| }); | ||
| ``` | ||
|
|
||
| **Claim a bounded number of epochs** — useful when many epochs have accumulated: | ||
|
|
||
| ```typescript | ||
| const txHash = await client.claimNftEpochs({ | ||
| nftId: nft.nftId, | ||
| numberOfEpochsToClaim: 50n, | ||
| }); | ||
| ``` | ||
|
|
||
| <Callout type="warning"> | ||
| A single claim processes **at most 50 epochs of inflation** at a time. If more than 50 finalized epochs have accumulated since your last claim, use `claimNftEpochs` (or call the claim repeatedly) to clear them in batches. The read view `getClaimableRewardsFromInflation` does **not** enforce this 50-epoch cap, so it can report more than a single claim will actually pay out — size your claim accordingly. |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟠 Major | ⚡ Quick win
Correct the “claim everything” description.
The page says claimNftRewards sweeps inflation for every finalized epoch, but the warning says a single claim processes at most 50 epochs. Describe it as claiming fee rewards plus up to 50 inflation epochs, and explain how to repeat claims for the remainder.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@pages/developers/decentralized-applications/developer-nft-rewards.mdx` around
lines 137 - 155, Update the “Claim everything” description for claimNftRewards
to state that it claims accumulated fee rewards plus inflation for up to 50
finalized epochs. Explain that callers must repeat the claim, or use
claimNftEpochs in batches, when additional finalized epochs remain.
| Profiles are keyed by contract method name, not by pytest test name and not by arguments. | ||
|
|
||
| If five tests call `register_and_claim`, all five observations are merged into one `methods.register_and_claim` entry. For each field, the profiler keeps the maximum value observed across the whole run, then applies headroom to fee and time-unit values. | ||
|
|
||
| Example: | ||
|
|
||
| | Test path | Execution budget | Message fees | Rotations | | ||
| | --- | ---: | ---: | ---: | | ||
| | user already registered, no referral message | 600 | 0 | 0 | | ||
| | new user, emits referral message | 200 | 800 | 1 | | ||
|
|
||
| The generated profile uses: | ||
|
|
||
| ```json | ||
| { | ||
| "methods": { | ||
| "register_and_claim": { | ||
| "executionBudgetPerRound": "600", | ||
| "totalMessageFees": "800", | ||
| "rotationsPerRound": "1" | ||
| } | ||
| } | ||
| } | ||
| ``` |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
Make the headroom behavior explicit in the profile example.
The text says the profiler applies headroom, and the default is 1.25, but the example outputs the raw maxima (600 and 800). Either show the headroom-adjusted values or label this as a raw/headroom-1.0 example; otherwise readers may implement the wrong fee budget.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@pages/developers/decentralized-applications/fee-profiling-and-estimation.mdx`
around lines 23 - 46, The profile example conflicts with the documented default
headroom of 1.25. Update the example under “Profiles are keyed by contract
method name” to show headroom-adjusted execution budget and message fees, or
explicitly label it as a raw/headroom-1.0 example; keep rotations unchanged if
headroom does not apply to that field.
| @@ -0,0 +1,47 @@ | |||
| # Fees and Transaction Policy | |||
|
|
|||
| GenLayer apps should treat fees as a measured application policy, not as ad hoc math at submission time. Whether you are building a web frontend, a backend service, a CLI or an automation script, the transaction must include fee parameters that are large enough for the path it can execute. | |||
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
Qualify the mandatory fee-parameter statement for gasless networks.
This says every transaction must include fee parameters, but fee-outcomes-and-debugging.mdx lines 25-33 says gasless Studio deployments submit without fee parameters. Limit this statement to fee-charging networks or link to the gasless exception.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@pages/developers/decentralized-applications/fees-and-transaction-kit.mdx` at
line 3, Qualify the mandatory fee-parameter guidance in the fees and transaction
documentation to exclude gasless Studio deployments, which may submit
transactions without fees. Update the introductory statement to apply only to
fee-charging networks or explicitly reference the gasless exception described in
fee-outcomes-and-debugging.mdx.
| - **The seed depends on inputs the operator does not fully control.** Advancing the seed requires a signature from a specific participant, and the resulting value is hashed. An operator cannot freely choose the next seed; they can only contribute their prescribed signature at their prescribed step. | ||
|
|
||
| - **The seed is consumed as it advances.** Selection and seed advancement are bound together in the consensus flow: the seed used for a transaction's committee is fixed at activation and read from there, so it cannot be re-derived mid-transaction to fabricate a favorable outcome. Once the seed advances, a signature that was valid against the old seed no longer verifies against the new one, so past proofs cannot be replayed to roll the seed back. | ||
|
|
||
| - **Selection is fresh per round.** Even a participant who learns the current seed only learns it for the round at hand; the next round's seed depends on a signature that does not yet exist. | ||
|
|
||
| Together these mean that, in the normal case, a validator learns whether it was selected at the moment selection happens — not early enough to reposition stake or otherwise engineer the outcome. | ||
|
|
||
| ## Known Limitations | ||
|
|
||
| GenLayer documents the properties of this mechanism plainly, including where it is weaker than an idealized random beacon: | ||
|
|
||
| - **Grinding at the margins.** Because a participant produces the signature that advances the seed, a participant who is willing to withhold or choose *when* to submit has some limited ability to influence the resulting value — a "grinding" surface. The scheme constrains this (the signer is fixed and the output is hashed), but it does not offer the formal grinding-resistance of a construction whose output no single party can compute alone. | ||
|
|
||
| - **Initial-seed predictability.** Each recipient's seed chain has to start somewhere, and it is derived in part from block data (block hash, timestamp, number) that a block producer has bounded influence over. In principle this means the *first-ever* selection for a brand-new recipient could be weakly predicted by an actor able to influence block production. The impact is limited and self-correcting: only that first selection is affected, and every subsequent signature-driven advance restores full unpredictability. |
There was a problem hiding this comment.
🔒 Security & Privacy | 🟡 Minor | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
set -euo pipefail
file="pages/understand-genlayer-protocol/core-concepts/optimistic-democracy/protocol-randomness.mdx"
echo "== File outline =="
wc -l "$file"
echo
nl -ba "$file" | sed -n '1,220p'
echo
echo "== Search for related randomness wording =="
rg -n "full unpredictability|grinding|withhold|initial-seed|seed chain|randomness" pages/understand-genlayer-protocol -SRepository: genlayerlabs/genlayer-docs
Length of output: 321
🏁 Script executed:
#!/bin/bash
set -euo pipefail
file="pages/understand-genlayer-protocol/core-concepts/optimistic-democracy/protocol-randomness.mdx"
echo "== Target lines 35-64 =="
awk 'NR>=35 && NR<=64 { printf("%4d %s\n", NR, $0) }' "$file"
echo
echo "== Related wording in docs =="
rg -n "full unpredictability|unpredictability|grinding|withhold|initial-seed|seed chain|block hash|timestamp" pages/understand-genlayer-protocol -SRepository: genlayerlabs/genlayer-docs
Length of output: 6190
Soften the post-first-round randomness guarantee.
Lines 53-55 already describe signer withholding/timing as a grinding surface, so “every subsequent signature-driven advance restores full unpredictability” is too strong. Rephrase this as reducing dependence on the initial block-derived seed while keeping the residual grinding caveat.
🧰 Tools
🪛 LanguageTool
[style] ~47-~47: For conciseness, consider replacing this expression with an adverb.
Context: ...alidator learns whether it was selected at the moment selection happens — not early enough to...
(AT_THE_MOMENT)
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In
`@pages/understand-genlayer-protocol/core-concepts/optimistic-democracy/protocol-randomness.mdx`
around lines 41 - 55, The Known Limitations section overstates randomness after
the first selection by claiming full unpredictability is restored. In the
“Initial-seed predictability” bullet, replace that claim with wording that
subsequent signature-driven advances reduce dependence on the initial
block-derived seed, while acknowledging the residual grinding influence
described in “Grinding at the margins.”
|
Added validator operator-gas guidance in commit d84ca63: clarifies that staked GEN cannot pay operator gas, adds funding and balance-verification steps, and adds the funded-operator pre-start check. Node follow-up: NOD-1014. Verified with the full npm run build. |
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (1)
pages/validators/setup-guide.mdx (1)
106-106: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low valueConsider fixing the sentence fragment flagged by LanguageTool.
The clause "Can be the same as the owner, but a separate account is recommended" lacks a subject. Adding "It" before "can" would form a complete sentence and improve readability.
✏️ Proposed fix
-| **Operator** | Hot wallet on your server that signs blocks and submits validator transactions. It must hold liquid GEN to pay gas. Can be the same as the owner, but a separate account is recommended. | Node config: `operatorAddress` | +| **Operator** | Hot wallet on your server that signs blocks and submits validator transactions. It must hold liquid GEN to pay gas. It can be the same as the owner, but a separate account is recommended. | Node config: `operatorAddress` |🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@pages/validators/setup-guide.mdx` at line 106, In the Operator description, update the sentence fragment beginning “Can be the same as the owner” to begin with “It can be the same as the owner, but a separate account is recommended.”Source: Linters/SAST tools
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@pages/validators/setup-guide.mdx`:
- Around line 149-170: The operator balance verification uses the unsupported
`genlayer balances --beneficiary` command. In the “Fund the Operator Wallet”
section, replace it with the documented `genlayer account show` flow, targeting
the operator account/address and instructing users to verify its balance on the
node’s target network.
---
Nitpick comments:
In `@pages/validators/setup-guide.mdx`:
- Line 106: In the Operator description, update the sentence fragment beginning
“Can be the same as the owner” to begin with “It can be the same as the owner,
but a separate account is recommended.”
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: 83433284-706a-4979-b361-57a4a721c7c7
📒 Files selected for processing (1)
pages/validators/setup-guide.mdx
| #### Fund the Operator Wallet | ||
|
|
||
| The operator signs and submits on-chain validator duties, including epoch priming, proposals, votes, and finalization. A separate operator therefore needs a liquid GEN balance for gas. GEN staked through the Validator Wallet, including vesting-backed stake, cannot pay the operator's gas. | ||
|
|
||
| Send a gas buffer to the operator address from a funded account before starting the node. You can use your wallet UI or, when the funding account is stored in the CLI, run: | ||
|
|
||
| ```bash copy | ||
| genlayer account send 0xYourOperatorAddress... 10gen | ||
| ``` | ||
|
|
||
| The required buffer depends on network activity and gas prices. Monitor and top it up before it runs out. Verify the operator balance on the node's target network: | ||
|
|
||
| ```bash copy | ||
| genlayer balances --beneficiary 0xYourOperatorAddress... | ||
| ``` | ||
|
|
||
| <Callout type="warning" emoji="⛽"> | ||
| A zero operator balance prevents priming and other consensus transactions even | ||
| when the Validator Wallet has enough stake. The node can remain synced while | ||
| missing validator duties, so verify this balance independently of sync health. | ||
| </Callout> | ||
|
|
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
# Search for CLI command definitions or references to verify these subcommands exist.
rg -n 'account send' --type=md -g '!**/node_modules/**' .
rg -n 'balances.*--beneficiary' --type=md -g '!**/node_modules/**' .
rg -n 'balances' --type=md -g '!**/node_modules/**' pages/ | head -20Repository: genlayerlabs/genlayer-docs
Length of output: 164
🏁 Script executed:
#!/bin/bash
set -euo pipefail
# Find the setup guide and related CLI docs.
git ls-files 'pages/**/*.mdx' 'pages/**/*.md' | sed -n '1,200p'
# Search for the specific command forms and nearby CLI references.
rg -n --hidden --glob '!**/node_modules/**' --glob '!**/.git/**' \
'genlayer account send|account send|genlayer balances|balances --beneficiary|--beneficiary|beneficiary' \
pages . 2>/dev/null | sed -n '1,200p'
# Look for CLI command docs that define subcommands or balance-related commands.
rg -n --hidden --glob '!**/node_modules/**' --glob '!**/.git/**' \
'Command|subcommand|CLI|balance' \
pages docs . 2>/dev/null | sed -n '1,200p'Repository: genlayerlabs/genlayer-docs
Length of output: 41463
🏁 Script executed:
#!/bin/bash
set -euo pipefail
# Inspect the CLI reference command list and account/balance-related pages.
sed -n '1,220p' pages/api-references/genlayer-cli/index.mdx
printf '\n--- account send ---\n'
sed -n '1,120p' pages/api-references/genlayer-cli/accounts/account/send.mdx
printf '\n--- account overview ---\n'
sed -n '1,120p' pages/api-references/genlayer-cli/accounts/account.mdx
printf '\n--- balance-related search ---\n'
rg -n --hidden --glob '!**/node_modules/**' --glob '!**/.git/**' \
'title: .*balance|balances|beneficiary|account show|account list|account send' \
pages/api-references/genlayer-cli pages/validators/setup-guide.mdxRepository: genlayerlabs/genlayer-docs
Length of output: 4295
🏁 Script executed:
#!/bin/bash
set -euo pipefail
# Inspect the account show command and any CLI balance-related options.
sed -n '1,160p' pages/api-references/genlayer-cli/accounts/account/show.mdx
printf '\n--- search for balance-related CLI flags/commands ---\n'
rg -n --hidden --glob '!**/node_modules/**' --glob '!**/.git/**' \
'balance|balances|beneficiary|show \[options\]|--account <name>|--network <network>|--rpc <rpcUrl>' \
pages/api-references/genlayer-cliRepository: genlayerlabs/genlayer-docs
Length of output: 1142
Replace the balance check command
genlayer account send is documented, but genlayer balances --beneficiary ... isn’t a supported CLI command. Use the documented genlayer account show flow for the operator account instead.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@pages/validators/setup-guide.mdx` around lines 149 - 170, The operator
balance verification uses the unsupported `genlayer balances --beneficiary`
command. In the “Fund the Operator Wallet” section, replace it with the
documented `genlayer account show` flow, targeting the operator account/address
and instructing users to verify its balance on the node’s target network.
Integration branch bundling the next-release fee-related documentation PRs into a single reviewable branch.
Bundled PRs
Merge notes
pages/developers/decentralized-applications/_meta.json(navigation). docs: fee policy, profiling, and transaction kit guides #425 and docs: developer NFT rewards page #439 both add sibling entries there, andmainhad independently retitledtesting. Resolved by keeping all four fee nav entries + the NFT rewards entry + main's "Testing in Studio" title.main; its raw diff looked large but it really only touched 6 files. Merge handled this correctly.Verification
scripts/generate-full-docs.jsruns clean (216 pages).Review guidance
Each source PR (#425, #439, #432, #436) can still be reviewed individually; this branch is for integrated review / a single merge to
main. Closes nothing automatically — decide whether to merge this bundle or the individual PRs.Summary by CodeRabbit