Resolve tester feedback: live /nodes metadata, protocol selection, +1d grace docs#16
Open
Sentinel-Bluebuilder wants to merge 1 commit into
Open
Conversation
…d grace docs Addresses the x402 dVPN end-to-end test report (2026-06-22). Issue #1 — /nodes returned empty metadata in production (online: 0, protocol: null, byCountry: {}). Root cause was 4 compounding bugs in the node status probe (server/src/sentinel.ts): - new URL() on a bare host:port threw / misparsed -> normalizeRemoteAddrToUrl() - probed /status (404) instead of the v3 root path / - read numeric status.type instead of v3 string service_type for protocol - read status.max_peers instead of qos.max_peers Now probes all remote_addrs (first reachable wins) and surfaces real address, online, protocol, country, city, moniker, peers, maxPeers, version and lastSeen per node, with byCountry + byProtocol summaries. Issue #2 — provisioning could instruct a protocol the selected node did not speak (v2ray instructions on a WireGuard node). Implemented protocol selection end-to-end: - request body `protocol: "v2ray" | "wireguard"` pinned before payment - pre-payment validation (INVALID_PROTOCOL / PROTOCOL_UNAVAILABLE) so no USDC is spent on a guaranteed-fail request - node matching honors the requested protocol - 200 response returns the node's ACTUAL nodeProtocol + full node metadata - instructions are generated from the selected node's real protocol - GET /nodes gains ?protocol= and ?country= filters Issue #7 — clarified the 1-day-grant-grants-~48h behavior: the +1 day is a deliberate fee-grant grace buffer (the grant must outlive the paid window so a session started at the very end can still pay gas). Documented and now surfaced as a distinct expiresAtPaid alongside expiresAt. Docs (recs #5/#6): added a no-root V2Ray worked example and a Linux WireGuard full-tunnel example using the splitIPs: ["0.0.0.0/0","::/0"] workaround in docs/llms.txt; mirrored the new request/response fields and /nodes filters in docs/index.html JSON-LD. NOTE: the /manifest + provisioning changes are server code and require an operator Docker redeploy to take effect on x402.sentinel.co; the docs/ changes go live on the next GitHub Pages publish.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Resolves the issues + recommendations from the x402 Sentinel dVPN end-to-end test report (2026-06-22, RESULT: PASS).
Issue #1 —
/nodesreturned empty metadata in productionThe live endpoint reported
online: 0,protocol: nullfor all 726 nodes, andbyCountry: {}. Traced to 4 compounding bugs in the node status probe (server/src/sentinel.ts):new URL("host:port")threw / misparsed bare addressesnormalizeRemoteAddrToUrl()helper (mirrors the SDK'sresolveNodeUrl)/status→ 404 on v3 nodes/status.typefor protocol (v3 uses a string)service_typestringstatus.max_peersqos.max_peersNow probes all
remote_addrs(first reachable wins) and surfaces realaddress, online, protocol, country, city, moniker, peers, maxPeers, version, lastSeenper node, withbyCountryandbyProtocolsummaries.Issue #2 — protocol mismatch (v2ray instructions on a WireGuard node)
Implemented protocol selection end-to-end:
protocol: "v2ray" | "wireguard"pins the tunnel typeINVALID_PROTOCOL/PROTOCOL_UNAVAILABLE) so no USDC is spent on a guaranteed-fail requestnodeProtocol+ fullnodemetadatainstructionsare generated from the selected node's real protocolGET /nodesgains?protocol=and?country=filtersIssue #7 — 1-day grant granting ~48h
Confirmed intentional: the +1 day is a deliberate fee-grant grace buffer so the grant outlives the paid window (a session started at the very end can still pay gas). Now documented and surfaced as a distinct
expiresAtPaidalongsideexpiresAt.Docs (recs #5 / #6)
docs/llms.txt: added a no-root V2Ray worked example and a Linux WireGuard full-tunnel example using thesplitIPs: ["0.0.0.0/0", "::/0"]workaround.docs/index.html: mirrored the new request/response fields and/nodesfilters in the JSON-LD spec.Not in this PR
blue-js-sdk.The
/manifest+ provisioning changes are server code and require an operator Docker redeploy to take effect onx402.sentinel.co. Thedocs/changes go live on the next GitHub Pages publish.