docs: add Accept Payments developer guide#72
Conversation
![claude[bot]](https://avatars.githubusercontent.com/in/1236702?s=60&v=4){kind=small}
There was a problem hiding this comment.
- Summary: New
docs/dev/payments.mddeveloper guide adds the Accept Payments page; SUMMARY.md is updated to register it. - Inline comments: 2 anchorable findings posted on changed lines (both terminology violations against
docs/AGENTS.md). - Body-only items: none.
- Internal links to
read/rpc/realtime_sendRawTransaction.md,read/realtime-api.md, andsend-tx/gas-estimation.mdresolve correctly; the in-page#building-blocksanchor is valid.
There was a problem hiding this comment.
🧭 Re-review update — ✅ Clean
- Reviewed the incremental diff in
30569a9("docs: fix terminology (Testnet, offchain) per review") against the previous review at2fcfca4. - Both prior findings are now addressed:
MegaETH testnet→MegaETH Testnet(lines 13, 210).off-chain→offchain(lines 129, 134–136, 168, 199).
- Spot-checked the rest of
docs/dev/payments.mdagainstdocs/AGENTS.mdanddocs/dev/AGENTS.md: terminology, sentence-per-line, sentence-case H2s, YAML frontmatter, GitBook hint blocks, language-tagged code fences, and relative.mdlinks all look correct. - Internal links (
read/rpc/realtime_sendRawTransaction.md,read/realtime-api.md,send-tx/gas-estimation.md) resolve;#building-blocksin-page anchor is valid;docs/SUMMARY.mdregisters the new page under Developer Docs. - No new actionable findings.
- Still open from earlier reviews: none — both prior threads resolved.
- Rename to Onchain Payments; add Mermaid sequence diagrams and high-level steps to all five flows and the shared HTTP 402 handshake - Link official x402 and MPP specs per flow and in further reading - Add quick-jump links in the flow overview table - Detail the session/gasless escrow actions (initiator, recipient, fund flow) - Note gasless charge/session are demo extensions (EIP-2612, Permit2, EIP-3009) - Warn that onchain payments can be reorged; verify idempotently - Reference the guide from the developer overview
There was a problem hiding this comment.
🧭 Re-review update —
- Reviewed the incremental diff in
83b91fe("docs: rework payments guide with diagrams, specs, and reorg warning") against the previous Clean review at30569a9. - New content in this commit: reorg warning hint, Mermaid sequence diagrams for the shared HTTP 402 handshake and all five flows, official-spec links per flow, expanded action tables for Flow 4 / Flow 5, demo-extension callouts on Flow 3 and Flow 5, page rename to Onchain Payments, and a new Onchain Payments section in
dev/overview.md. - Spot-checked against
docs/AGENTS.md,docs/dev/AGENTS.md, andREVIEW.md: terminology (Testnet, onchain/offchain), sentence-per-line, sentence-case H2s, YAML frontmatter, GitBook hint blocks, language-tagged code fences, and relative.mdlinks all check out. - Internal link targets resolve (
read/rpc/realtime_sendRawTransaction.md,read/realtime-api.md,send-tx/gas-estimation.md); the in-page#building-blocksanchor and the new five#flow-N--…quick-jump anchors all match the H2 headings. docs/SUMMARY.mdanddocs/dev/overview.mdcross-links are wired correctly.
Inline comments: 1 anchorable finding posted on a changed line.
Still open from earlier reviews: none — both prior threads resolved.
There was a problem hiding this comment.
🧭 Re-review update — ✅ Clean
- Reviewed the incremental diff in
c13285("docs: fix dapp casing and clarify Node.js SDKs per review") against the previous review at83b91fe. - The single change addresses the prior open thread on
docs/dev/payments.md:52:DApps … (Node.js)→Dapps have … each with a Node.js SDK.— matches the suggested replacement verbatim. Thread resolved. - Spot-checked the rest of the page against
REVIEW.md,docs/AGENTS.md, anddocs/dev/AGENTS.md: YAML frontmatter, sentence-per-line, sentence-case H2s, terminology (Testnet, onchain/offchain, dapp), GitBook hint blocks, language-tagged code fences, and the in-page#building-blocks/#flow-N--…anchors all still check out. docs/SUMMARY.mdanddocs/dev/overview.mdcross-links remain wired correctly; relative.mdlinks resolve.
No new actionable findings.
Still open from earlier reviews: none — all prior threads resolved.
There was a problem hiding this comment.
- Summary: Re-review of incremental commit
271f032("docs: use DApp capitalization in payments guide and overview") on top of the prior Clean review atc13285. - Inline comments: 1 anchorable finding posted on a changed line.
- Body-only items: none.
Still open from earlier reviews: none — all prior threads resolved.
Add a DApp/DApps terminology-table entry and update the layer tables and writing-rule prose to use DApp consistently.
There was a problem hiding this comment.
🧭 Re-review update
- Reviewed the 5 commits since the previous automated review (
30569a9..b63467b): payments page rework with diagrams + reorg-warning hint, terminology fixes, and DApp casing standardization across agent guides. - No new actionable findings on the incremental diff.
- Internal links from
docs/dev/payments.mdtoread/rpc/realtime_sendRawTransaction.md,read/realtime-api.md, andsend-tx/gas-estimation.mdall resolve to existing pages.
Still open from earlier reviews:
- DApp/dapp repo-wide consistency —
b63467bcodifiedDAppin thedocs/AGENTS.mdterminology table and updated the four agent guides, but ~10 existing pages still usedApp/dapp/dApps/dapps(docs/README.md:35,docs/user/faucet.md:34,docs/user/faq.md:18,42,docs/user/get-started.md:66,docs/dev/send-tx/contracts.md:14,21,docs/dev/execution/system-contracts.md:21,docs/dev/vrf.md:232,docs/dev/read/realtime-api.md:47) and now contradict the new convention. A repo-wide sweep (in this PR or a follow-up) is still needed to make the convention single-form.
There was a problem hiding this comment.
Reviewed this guide against the actual payment-demo implementation — routes, components, signature schemes, contract method names, voucher semantics, and the realtime settlement path all check out. The guide is accurate; just a few small accuracy nits below.
Route map: Flows 4 & 5 should be POST, not GET|POST
In the table under MegaETH-specific payment demo, the two session routes are listed as GET|POST, but their GET handler only returns 405 "MPP session payments must use POST." (src/app/api/mpp/session/route.ts:635, src/app/api/mpp/session-gasless/route.ts:869) — only POST is operational. Verified against a local dev server: GET /api/mpp/session → 405 Allow: POST, while the GET-only charge flow returns a real 402. The demo's own README also lists these as POST (README.md:48-49). Suggested table:
| Flow | Protected route | Demo UI component |
| ---- | ------------------------------- | ------------------------ |
| 1 | `GET /api/protected` | `X402Demo` |
| 2 | `GET /api/mpp/charge` | `MppDemo` |
| 3 | `GET /api/mpp/gasless-charge` | `MppGaslessDemo` |
| 4 | `POST /api/mpp/session` | `MppOfficialSessionDemo` |
| 5 | `POST /api/mpp/session-gasless` | `MppSessionGaslessDemo` |
|
@mega-putin please fix review comments |
|
🔍 Looking into this... |
1 similar comment
|
🔍 Looking into this... |
|
|
Generated-by: engineer-agent
|
All four review comments from @claude[bot] have been addressed in commit 454b221:
Also updated AGENTS.md terminology tables in Generated-by: mega-engineer |
|
@mega-putin please fix the comment by RealiCZ |
|
Done.
Checks run:
Commit:
No comment reply text needed. |
Generated-by: engineer-agent
There was a problem hiding this comment.
- Reviewed incremental commit
454b221("address review feedback: standardize payments terminology") on top of prior reviews. The commit reverts every previously-touched file back to lowercasedappand adds aDecentralized app → dapp, dappsentry todocs/AGENTS.md. This addresses the prior open thread onpayments.md:52(the specific lines flagged there are now lowercase) — resolved. - 1 new actionable finding:
AGENTS.md:18in this PR changesDapp→DApp, which now contradicts the lowercase-dapprule the same PR codifies. Posted inline. - Spot-checked the rest of the page against
docs/AGENTS.mdanddocs/dev/AGENTS.md: terminology (Testnet, onchain/offchain, dapp), sentence-per-line, GitBook hint blocks, YAML frontmatter, relative.mdlinks, and in-page anchors (#building-blocks,#flow-N--…) all still check out.
Still open from earlier reviews:
- Flow 4 & 5 route map:
GET|POSTshould bePOST— human-authored review from @RealiCZ; not yet addressed in454b221. Thepayments.mdroute-map table still listsGET|POST /api/mpp/sessionandGET|POST /api/mpp/session-gasless, but the demoGEThandlers return405.
|
Done.
Checks run:
Commit:
No comment reply text needed. |
Generated-by: engineer-agent
|
@yilongli ❓ Do you want the docs table to keep the demo’s literal route/component names and add a payment-method label (for example, note that (I've paused on this task. Reply here with the answer and I'll continue where I left off.) |
There was a problem hiding this comment.
Clean
- Reviewed incremental changes since the last review (commits 454b221..b3b81ac): AGENTS.md:18 lowered DApp -> dapp to match the new terminology table, and the docs/dev/payments.md route table now lists POST only for flows 4 and 5.
- No new actionable findings.
- Resolved prior thread: AGENTS.md DApp casing (discussion_r3490657512) is now consistent with the docs/AGENTS.md terminology entry added in this PR.
There was a problem hiding this comment.
✅ Clean
- Reviewed PR head
b3b81acagainst repoAGENTS.mdanddocs/AGENTS.mdterminology rules (dapp/dapps, onchain/offchain, MegaETH Testnet) and the developer-layer writing rules. - No new actionable findings since the previous Clean review at the same head commit.
- All earlier Claude-authored threads have been resolved by the author.
There was a problem hiding this comment.
🧭 Re-review update — ✅ Clean
- Reviewed incremental commit
fb4d0a6("docs: update x402 demo route") on top of the prior Clean review atb3b81ac. - Single change: route table entry
GET /api/protected→GET /api/x402/exact(docs/dev/payments.md:328), bringing flow 1 in line with the/api/<protocol>/<method>shape used by flows 2–5. - No new actionable findings.
Still open from earlier reviews:
- yilongli on payments.md:328 — asked that the demo route reflect the payment method instead of
/api/protected. This commit appears to address it (/api/x402/exact); leaving the thread for the human reviewer to resolve.
|
Already addressed.
No additional action needed for the new feedback. |
5 participants
Summary
docs/dev/payments.md— a developer guide for accepting onchain payments in a MegaETH dapp.docs/SUMMARY.mdunder Developer Docs.Test plan
mise run lint—markdownlint-cli2passes (0 errors);prettier --checkpasses; internal links + the same-file anchor validate with lychee (42 OK, 0 errors; external URLs excluded byoffline).docs/dev/AGENTS.mdconventions: YAMLdescriptionfrontmatter, one-sentence-per-line, GitBook{% hint %}blocks, relative.mdlinks, language-tagged code blocks.This PR was generated by an automated agent.