docs: add Vellar x402 facilitator to Stellar ecosystem - #2836
Open
davedumto wants to merge 5 commits into
Open
Conversation
Contributor
There was a problem hiding this comment.
Pull request overview
Adds the pre-production Vellar facilitator to Stellar’s x402 documentation.
Changes:
- Adds a Community facilitators subsection.
- Documents Vellar’s discovery, MCP tooling, fee sponsorship, links, and status.
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
- Intro sentence now accounts for the community subsection instead of claiming two options. - Bazaar cataloging happens only when the settled payment's payload carries the discovery extension; say so, and note that payments without it settle normally but are not cataloged. - The MCP discovery server is a separate stdio process run locally and pointed at the facilitator URL; the hosted instance has no MCP endpoint. - The open external audit blocks a mainnet release tag, not running a mainnet instance; reword the status note to match the project's own checklist.
Contributor
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 1 out of 1 changed files in this pull request and generated no new comments.
Suppressed comments (1)
docs/build/agentic-payments/x402/README.mdx:110
- Carrying the Bazaar extension does not guarantee that the resource is added: the facilitator can still reject cataloging for invalid discovery data, an unbound
payTo, or an ownership-binding mismatch while allowing settlement to succeed. Please describe cataloging as conditional so sellers do not treat a successful extended settlement as proof that they were listed.
endpoints with a **Bazaar discovery layer**: when a payment settles and its
payload carries the Bazaar discovery extension, the resource is added to a
searchable catalog, so sellers that use the extension are listed without a
The note said an external security audit was still open. The facilitator's pre-mainnet security review is complete with findings tracked to closure; the remaining gate on a mainnet release is a separate audit of the spending-limit policy contract, which has not been run. The other three review points (facilitator count, Bazaar extension requirement for cataloging, and MCP being a separate stdio server) were already addressed in aa3268c.
Contributor
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 1 out of 1 changed files in this pull request and generated no new comments.
Suppressed comments (1)
Previously missed (1) — in code that hasn't changed since the last review.
docs/build/agentic-payments/x402/README.mdx:117
- Fee sponsorship does not mean every buyer can hold no XLM. A classic account holding the payment asset normally still needs XLM for its account and trustline reserves unless those reserves are separately sponsored (
docs/learn/fundamentals/lumens.mdx:30-40), while this facilitator only sponsors the settlement transaction fee. Please limit the claim to that fee.
The intro to the facilitators section still said two options were available while listing three, which left the community entry reading as an afterthought rather than part of the count. It now says two production implementations plus one community-run pre-production option. The other three Copilot comments were already addressed on this branch: cataloging is stated as conditional on the payload carrying the Bazaar discovery extension, MCP is described as a separate local stdio server rather than an endpoint on the hosted URL, and the mainnet statement already separates the completed facilitator review from the outstanding policy contract audit.
Contributor
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 1 out of 1 changed files in this pull request and generated no new comments.
Suppressed comments (3)
docs/build/agentic-payments/x402/README.mdx:117
- Fee sponsorship does not mean every buyer can hold zero XLM. Classic Stellar accounts must maintain their base reserve, and an asset trustline adds another reserve unless those reserves are separately sponsored (
docs/learn/fundamentals/lumens.mdx:28-40). Since Vellar supports classic-keypair buyers, narrow this claim to transaction fees.
facilitator sponsors the network fee on settlement, so buyers hold only the
payment asset and no XLM.
docs/build/agentic-payments/x402/README.mdx:129
- This understates the remaining audit scope. Vellar's current mainnet checklist marks an external audit of the facilitator as not started, while its technical plan says that review covers the facilitator and all three provenance contracts, not only the spending-limit contract (
technical-doc.md:591-609,technical-doc.md:679-684). Please describe the full gate so readers do not infer that the other components have already passed an independent review.
findings tracked to closure. A mainnet release is additionally gated on a
separate audit of the spending-limit policy contract, which has not yet been
run. The hosted instance runs on a free tier, so the first request after an
docs/build/agentic-payments/x402/README.mdx:128
- The linked project's current
docs/security-audit.mdexplicitly keeps F6 open (“RELOCATED, not eliminated”) and distinguishes open/deferred/external findings, so “findings tracked to closure” overstates the review outcome. Please describe the review as complete while preserving that some residual risks remain documented.
instance. The pre-mainnet security review of the facilitator is complete, with
findings tracked to closure. A mainnet release is additionally gated on a
separate audit of the spending-limit policy contract, which has not yet been
Three corrections, all verified against the facilitator repo: 1. Cataloging is conditional, not automatic. Carrying the Bazaar extension does not guarantee a listing: it is refused for invalid discovery data or when the resource URL is already bound to a different recipient, while settlement succeeds either way. 2. Fee sponsorship covers the settlement transaction fee only. Classic Stellar accounts still maintain their own base and trustline reserves, so the previous 'no XLM' claim was too broad. 3. Audit scope corrected. The completed review is internal, and F5/F6/F8 remain open or deferred rather than closed. The external audit covers the facilitator and its three provenance contracts, not the spending-limit contract alone, and has not been commissioned.
Comment on lines
+130
to
+135
| instance. The facilitator has completed an internal pre-mainnet security review, | ||
| with most findings closed and the remainder documented as open or deferred. A | ||
| mainnet release is separately gated on an external audit covering the | ||
| facilitator and its three provenance contracts, which has not yet been | ||
| commissioned. The hosted instance runs on a free tier, so the first request | ||
| after an idle period can take up to a minute. |
Author
There was a problem hiding this comment.
Respectfully, I think this reverses the earlier finding rather than restoring it. The 09:13:36Z review on the previous revision flagged the spending-limit-only wording as understating the scope, and asked for the full gate to be described; 9d30a1d is that change.
The current text matches the project's own documents:
- technical-doc.md, pre-mainnet checklist item 1: "External security audit | Not started".
- technical-doc.md, milestone 3: the audit covers "Facilitator + its three provenance contracts (attestation registry, verified-recipient policy, spending-limit policy)", described as "a second, independent review on top of the already-completed pre-mainnet review".
- docs/mainnet-deployment-checklist.md: "Item 1 (external security audit) remains open and is a hard blocker".
So the completed review is the internal pre-mainnet one, and the outstanding external audit covers the facilitator plus all three contracts, not the spending-limit contract alone. The "separate audit of the spending-limit policy contract" wording in fe2112e was my error, which is why it was corrected.
Happy to reword for clarity if any part reads ambiguously, but I do not think reverting to the narrower scope would be accurate.
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
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.
Adds Vellar to the x402 facilitators section under a new Community facilitators
subsection.
Vellar is a hosted x402 facilitator for Stellar with:
Live on testnet: https://vellar-facilitator.onrender.com
GitHub: https://github.com/Vellar-Wallet/vellar-facilitator
Docs: https://docs.vellar.xyz
Status: testnet, pre-production. Mainnet gated on external security review.
A note on placement
I added a new
### Community facilitatorssubsection rather than a third entryalongside the Coinbase and Built on Stellar facilitators, because those two are
production and mainnet-capable and this one is neither. The "Two options are
available for Stellar" sentence is deliberately left unchanged. The new
subsection carries a line stating these are not maintained by SDF, so it should
also serve any future community entries rather than being Vellar-specific.
The entry states the testnet-only and pre-production status inline, and notes
that the hosted instance runs on a free tier so the first request after an idle
period can take up to a minute. That seemed better than a reader clicking the
link, waiting, and assuming the service is down.
Filed as a draft. Happy to revise placement, wording, or length based on
maintainer feedback before marking ready, or to drop it entirely if a community
section is not something you want in this page.