doc(examples): add drand VRF lottery walkthrough#41
Conversation
![claude[bot]](https://avatars.githubusercontent.com/in/1236702?s=60&v=4){kind=small}
|
Good addition overall — the walkthrough is clear, the adversarial-path section is a nice touch, and the gas-profile callout about Two issues flagged inline:
|
- settle() now follows checks-effects-interactions: settled = true before the oracle call - README settle snippet matches the contract - Clarify that verify() is a separate oracle helper from verifyNormalized
|
Both previous review comments have been addressed — checks-effects-interactions is now correct in The walkthrough, security checklist, gas profile, and adversarial-path coverage are all solid. No further issues. |
…ject - Move contract under src/, add foundry.toml, .gitignore, .env.example - Add unit tests with a mock oracle (forge test: 8 passing) - Add deploy/open/settle shell scripts that drive the lifecycle end-to-end - deploy script queries eth_estimateGas on the node to work around MegaETH's dual-gas model - Rewrite README with a project layout and quick-start
|
Good addition overall. The two previous review threads (checks-effects-interactions order, and the stray One remaining issue: four relative links to Everything else looks clean:
|
GitBook only serves .md files, so relative .sol links 404 on the live docs site. Leave the paths as inline code instead.
|
Good shape. Resolved the three previous threads about One remaining nit: the project layout code block (line 25 of Everything else looks correct:
|
Clones the upstream DrandVerifier repo into .drandverifier/ (git-ignored), builds DrandOracleQuicknet, deploys with the node's gas estimate, runs a known-good sanity check, and writes ORACLE_ADDRESS back into .env. Verified end-to-end on MegaETH Testnet.
|
Overall this is a clean, well-structured example. The checks-effects-interactions fix, the Two remaining issues: 1. Unresolved inline thread — missing language identifier 2. function publishTime() external view returns (uint256) {
if (revealRound == 0) return 0;
return GENESIS + uint256(revealRound - 1) * PERIOD;
} |
|
Good PR overall — well-structured walkthrough, clean contract with CEI correctly applied, and all five previously-flagged issues were addressed. One thing remaining before merge: two fenced code blocks in README.md still lack language identifiers (required by |
Replace the hand-stripped scaffold with a verbatim copy of the upstream DrandVerifier workspace (src/, test/, lib/bls-solidity, lib/forge-std, lib/solady, scripts, etc.) plus shell automation for the end-to-end lifecycle (deploy-oracle, deploy-lottery, open, settle). `forge test` runs 123 tests in-tree. Docs repo lint configs now skip `docs/**/examples/**/lib/**` and `dependencies/` so vendored library markdown doesn't block CI.
ReviewOverall this is well-structured — the deployed contracts were verified end-to-end and the Still unresolved from prior review
New inline comments
Minor (non-blocking)
|
Replace the prior scaffold with a 1:1 copy of /home/william/workspace/drand-lottery-demo — the dedicated demo repo with DrandLottery.sol, forge Script-based deploys, demo.sh, soldeer-managed deps, and the DrandVerifier submodule vendored at dependencies/DrandVerifier. Lint excludes updated so the docs repo's markdownlint/prettier/lychee skip the example's dependencies/ tree.
…ring
Match the upstream drand-lottery-demo layout: dependencies/DrandVerifier is
a proper git submodule pinned to the same commit (ccf2336), not vendored
files. Adds a top-level .gitmodules entry on the docs repo.
Consumers clone with:
git submodule update --init --recursive
after which forge build / forge test work.
|
The contract rename and the previous round of fixes addressed the bulk of the earlier feedback — the Two threads are still open and must be addressed before merge:
New: one-sentence-per-line throughout prose — added an inline comment on the opening paragraphs. The same 80-char hard-wrapping pattern appears in the Setup, Deploy, End-to-end demo, and Known limitations sections too; please sweep the whole file. |
|
Three open threads still need addressing before merge, plus two new items. Open threads (unaddressed)
New: one-sentence-per-line rule
A minimal commit-reveal lottery that consumes [DrandOracleQuicknet](https://github.com/Zodomo/DrandVerifier) to draw a fair winner using drand quicknet randomness.
The whole point of this demo is to show what a _consumer_ contract has to add around the stateless drand verifier to make randomness safely usable.
The verifier answers one question — "is this a valid drand beacon?" — and nothing else.
Everything about **when** to consume it, **which round** to use, and **how to lock inputs** is the application's responsibility.
This contract shows the minimum correct discipline.New: code blocks without language identifiers Lines 23 and 209 of |
… rename folder to vrf-drand-quicknet-lottery
ReviewFour threads from the previous round are still open — please address them before merge:
New inline comments added for three more fenced code blocks that are missing a language identifier (flow diagram, directory tree, expected output). |
Documents DrandOracleQuicknet as MegaETH's preinstalled VRF service. Covers what VRF is, the MegaETH service addresses, what drand is, the verifier API surface, a minimal consumer pattern, offchain beacon fetching (curl/cast/viem), and commit-reveal security caveats. Links to the existing drand-lottery example as the runnable companion.
ReviewThe VRF page ( Still open from previous roundsThese threads have not been addressed:
New issues (filed inline)
|
…3 core pitfalls - Drop the Chainlink-comparison table and 'MegaETH's ethos' aside; the page describes what the service is, not what it isn't - Inline reference to Zodomo/DrandVerifier where DrandOracleQuicknet is introduced and again at the start of the how-to-use section - Round-time math now cites the drand protocol specification as the authoritative source for beacon timing - Collapse 8 caveats into 3 core pitfalls: (1) commit-to-future-round + lock inputs, (2) own the state the verifier doesn't (freshness, replay, encoding), (3) handle drand stalls
The formulas were just restating the inline math already shown in the minimal pattern code example. Drand spec reference is preserved in the References section.
ReviewResolved (latest commit): The Round-time math section was dropped from Still open — 7 threads require fixes before merge:
All seven have inline suggestions already posted in prior threads. No new issues found. |
|
The content and structure here are solid — good use of Outstanding items (already threaded inline):
All of these are covered by the existing inline threads — no new findings beyond what's already been raised. |
Replace ambiguous 'key holder' language with named properties (Correctness / Uniqueness / Unpredictability) and generic 'producer'. Matches drand's actual trust model where no single party holds the key.
ReviewThis is a clean, well-structured PR — solid VRF explainer in 9 prior threads resolved. 7 remain open and all are still applicable to the current diff. Summarizing what needs to land before merge:
No new issues to add — everything above is already tracked in the open threads. |
… nav entry - Security caveats section now scopes itself as integration-level and points readers to drand's own Security Model for protocol-level concerns (threshold, front-running, DoS). - Stalls caveat deep-links to drand's DoS scenarios for context on stall duration. - Remove Examples entry from SUMMARY.md; example content stays in-tree but is no longer in the docs nav.
|
The new revision restructures the example under However, all 7 threads from the previous round remain open and unaddressed in this revision. Nothing new to flag beyond them, but these need to be fixed before merging:
Each of these has a suggestion already written in the corresponding inline thread. |
Review — round 2Good progress: the contract reentrancy ordering, the Seven threads from the previous review are still open against the new
One new issue logged inline on |
- Add YAML frontmatter with description - Rename H1 to 'Drand VRF Lottery' to match inbound links - Reflow prose to one-sentence-per-line per repo convention - Add 'text' language identifiers to ASCII/output code blocks - src/DrandLottery.sol: early-return publishTimeOf(0) to avoid arithmetic underflow
Deployed at 0x7a53a6eFA81c426838fcf4824E6e207923969b36 on chain 4326 (tx 0x224796d88164397c05b071d1389ade72de5b7a8d3bd04d466d7c995f3193a3de). Verified end-to-end against a live drand quicknet beacon.
|
Good progress — 6 of the 8 previous threads are now resolved. Two remain: 1.
```diff 2. The prose sections are now correctly formatted, but several bullet items still pack two sentences on one line. Per
Split each into two bullets or move the second sentence to a new indented line. |
|
Good revision pass — all 7 threads from the previous round have been addressed and are now resolved. One issue remains open before this is mergeable. Still blocking:
Suggested fix: - - [Verifiable Randomness (VRF)](dev/vrf.md)
+ - [Verifiable Randomness (VRF)](dev/vrf.md)
+ - [Drand VRF Lottery](dev/examples/vrf-drand-quicknet-lottery/README.md)Everything else — frontmatter, language identifiers, heading, one-sentence-per-line, |
GitBook requires every page referenced elsewhere to appear in SUMMARY.md or relative links 404. The lottery example is linked three times from dev/vrf.md (intro hint, 'Worked example' section, References). Adding it as a child of the VRF page keeps the flat nav structure (no 'Examples' heading) while making the page reachable.
|
All 19 prior threads are resolved (the open SUMMARY.md thread was addressed by this revision and has been resolved above). One new issue: The minimal Everything else looks good: YAML frontmatter, H1/sidebar alignment, code block language tags, sentence-per-line prose, |
…example verifyNormalized returns (bool, normalizedRoundHash, chainScopedHash). The chainScopedHash binds the random value to address(this) and block.chainid, so the same beacon can't be replayed across chains or contracts. Match the worked example's choice in the minimal pattern.
|
All previous review threads are now resolved. No remaining issues found. Checklist verified: YAML frontmatter present on both new pages, H1 matches SUMMARY.md sidebar title, all code blocks have language identifiers, one sentence per line, no broken .sol hyperlinks, SUMMARY.md updated, publishTimeOf underflow guard in place, settle() follows CEI, and the minimal pattern in vrf.md correctly uses the 3rd return value (chainScopedHash) consistent with the worked example. |
1 participant
Summary
Adds a runnable developer example under
docs/dev/examples/vrf-drand-lottery/demonstrating publicly-verifiable onchain randomness via drand quicknet on MegaETH Testnet.The example covers:
DrandLotteryDemo.solcontract (commit-reveal, single-slot) that consumes the stateless DrandVerifier oracle viaverifyNormalized.docs/SUMMARY.mdgets a new "Examples" subsection under "Developer Docs".Test plan
This PR was generated by an automated agent.