chore: Add Stellar x402 plugin example and guide #592
Conversation
WalkthroughThis PR adds comprehensive documentation and a complete working example for the x402 Facilitator plugin for OpenZeppelin Relayer. It includes a new guide document, example project structure with Docker setup, plugin configuration, and API route definitions. Changes
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes Areas requiring attention:
Suggested labels
Suggested reviewers
Poem
Pre-merge checks and finishing touches❌ Failed checks (1 inconclusive)
✅ Passed checks (2 passed)
✨ Finishing touches
🧪 Generate unit tests (beta)
Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (9)
examples/x402-facilitator-plugin-example/x402-facilitator/package.json (1)
13-13: Pin the GitHub dependency to a specific version or tag.The plugin dependency uses
github:OpenZeppelin/relayer-plugin-x402-facilitatorwithout a version or tag. This can lead to non-deterministic builds and unexpected breaking changes.Apply this diff to pin to a specific commit, tag, or branch:
- "@openzeppelin/relayer-plugin-x402-facilitator": "github:OpenZeppelin/relayer-plugin-x402-facilitator", + "@openzeppelin/relayer-plugin-x402-facilitator": "github:OpenZeppelin/relayer-plugin-x402-facilitator#v1.0.0",Or use a commit SHA for maximum reproducibility:
- "@openzeppelin/relayer-plugin-x402-facilitator": "github:OpenZeppelin/relayer-plugin-x402-facilitator", + "@openzeppelin/relayer-plugin-x402-facilitator": "github:OpenZeppelin/relayer-plugin-x402-facilitator#abc1234",docs/guides/index.mdx (1)
23-25: Add a description for the new guide.The other guide entries include a descriptive paragraph explaining what the guide covers. Consider adding a similar description for consistency.
Apply this diff:
### Stellar x402 Facilitator Guide +A guide to implementing the x402 payment facilitation protocol on Stellar. Learn how to configure the facilitator plugin, verify payment payloads, and settle transactions using OpenZeppelin Relayer. + [Read the Stellar x402 Facilitator Guide →](./stellar-x402-facilitator-guide.mdx)Note: There's also a typo with double spaces in "Stellar x402" on line 25.
examples/x402-facilitator-plugin-example/README.md (2)
199-199: Convert URL to proper markdown link.For better accessibility and consistency with markdown best practices, convert the URL to a proper link.
Apply this diff:
-The plugin implements the API defined by the x402 v1 spec, so it works with any packages in that ecosystem. For more information on available packages, see `https://github.com/coinbase/x402`. +The plugin implements the API defined by the x402 v1 spec, so it works with any packages in that ecosystem. For more information on available packages, see the [x402 repository](https://github.com/coinbase/x402).
265-268: Convert URLs to proper markdown links.For better accessibility and consistency, convert the backtick-wrapped URLs to proper markdown links.
Apply this diff:
## Learn more -- OpenZeppelin Relayer docs: `https://docs.openzeppelin.com/relayer` -- Stellar SDK: `https://stellar.github.io/js-stellar-sdk/` -- Coinbase x402 GitHub repo: `https://github.com/coinbase/x402` +- [OpenZeppelin Relayer docs](https://docs.openzeppelin.com/relayer) +- [Stellar SDK](https://stellar.github.io/js-stellar-sdk/) +- [Coinbase x402 GitHub repo](https://github.com/coinbase/x402)examples/x402-facilitator-plugin-example/docker-compose.yaml (2)
9-18: Redundant configuration: secrets and environment variables.The configuration defines both secrets (lines 9-12, 58-64) and environment variables (lines 14, 17-18) that reference the same values from the host environment. This creates unnecessary complexity.
Since the secrets are sourced from environment variables (lines 58-64), and the service also reads those same environment variables directly (lines 14, 17-18), the secrets mechanism provides no additional security benefit here.
Option 1 (Recommended): Use only environment variables for simplicity:
ports: - 8080:8080/tcp - secrets: - - api_key - - keystore_passphrase - - redis_url environment: REDIS_URL: ${REDIS_URL} RATE_LIMIT_REQUESTS_PER_SECOND: 10 RATE_LIMIT_BURST: 50 API_KEY: ${API_KEY} KEYSTORE_PASSPHRASE: ${KEYSTORE_PASSPHRASE} ... -secrets: - api_key: - environment: API_KEY - keystore_passphrase: - environment: KEYSTORE_PASSPHRASE - redis_url: - environment: REDIS_URLOption 2: If secrets are intended for production use with Docker Swarm or external secret managers, document that environment-based secrets are only for development and provide guidance for production secret management.
Also applies to: 58-64
27-27: Adjust comment phrasing for example code.The comment "Mount your specific plugin" suggests this is a template to be modified, but this is complete example code that should work as-is.
Apply this diff:
- - ./x402-facilitator:/app/plugins/x402-facilitator # Mount your specific plugin + - ./x402-facilitator:/app/plugins/x402-facilitator # Mount the x402-facilitator plugindocs/guides/stellar-x402-facilitator-guide.mdx (3)
43-47: Clarify pnpm installation context.The instruction to
cd pluginsbefore runningpnpm addmay not work as expected ifplugins/doesn't have its ownpackage.json. Consider clarifying whether this assumes a monorepo workspace structure or if the command should be run from the repository root.```bash -# From the root of your Relayer repository -cd plugins -pnpm add @openzeppelin/relayer-plugin-x402-facilitator +# From the root of your Relayer repository (assuming plugins/ has its own package.json) +cd plugins && pnpm add @openzeppelin/relayer-plugin-x402-facilitator + +# Or from the root if using workspaces +pnpm add @openzeppelin/relayer-plugin-x402-facilitator --filter plugins--- `109-109`: **Clarify raw_response default vs recommended value.** The description states `raw_response` defaults to `false` but is "recommended for x402 compatibility". The example on line 78 sets it to `true`. Consider rewording to make the recommendation clearer. ```diff -- `raw_response`: Whether to return raw plugin response without ApiResponse wrapper (default: false, recommended for x402 compatibility) +- `raw_response`: Whether to return raw plugin response without ApiResponse wrapper (default: false; **set to true** for x402 compatibility)
181-182: Consider documenting environment variable support for API key.Hardcoding
channel_service_api_keyin config files is a security risk. If the plugin supports environment variable references (similar to thepassphraseconfig in signers), document that pattern here to encourage secure credential management.
📜 Review details
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (9)
docs/guides/index.mdx(1 hunks)docs/guides/stellar-x402-facilitator-guide.mdx(1 hunks)examples/x402-facilitator-plugin-example/.env.example(1 hunks)examples/x402-facilitator-plugin-example/README.md(1 hunks)examples/x402-facilitator-plugin-example/config/config.json(1 hunks)examples/x402-facilitator-plugin-example/docker-compose.yaml(1 hunks)examples/x402-facilitator-plugin-example/x402-facilitator/index.ts(1 hunks)examples/x402-facilitator-plugin-example/x402-facilitator/package.json(1 hunks)examples/x402-facilitator-plugin-example/x402-facilitator/tsconfig.json(1 hunks)
🧰 Additional context used
🪛 dotenv-linter (4.0.0)
examples/x402-facilitator-plugin-example/.env.example
[warning] 2-2: [UnorderedKey] The API_KEY key should go before the REDIS_URL key
(UnorderedKey)
[warning] 3-3: [UnorderedKey] The KEYSTORE_PASSPHRASE key should go before the REDIS_URL key
(UnorderedKey)
🪛 Gitleaks (8.30.0)
examples/x402-facilitator-plugin-example/README.md
[high] 184-185: Discovered a potential authorization token provided in a curl command header, which could compromise the curl accessed resource.
(curl-auth-header)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (6)
- GitHub Check: boostsecurity - boostsecurityio/semgrep-pro
- GitHub Check: Redirect rules - openzeppelin-relayer
- GitHub Check: Header rules - openzeppelin-relayer
- GitHub Check: Pages changed - openzeppelin-relayer
- GitHub Check: Analyze (rust)
- GitHub Check: semgrep/ci
🔇 Additional comments (8)
examples/x402-facilitator-plugin-example/x402-facilitator/tsconfig.json (1)
1-13: LGTM! TypeScript configuration is appropriate.The configuration uses appropriate compiler options for a Node.js plugin with strict type-checking enabled and modern JavaScript target.
examples/x402-facilitator-plugin-example/.env.example (1)
1-3: LGTM! Environment example is clear.The environment variables are appropriately defined with a sensible default for REDIS_URL and placeholders for secrets that users need to fill in.
Note: The static analysis warnings about key ordering can be safely ignored—the order of environment variables is not functionally significant.
examples/x402-facilitator-plugin-example/README.md (1)
184-186: LGTM! Example command is appropriate.The curl command with placeholder demonstrates proper authentication header usage. The Gitleaks warning is a false positive—this is documentation showing users the pattern to follow with their own API key.
examples/x402-facilitator-plugin-example/config/config.json (1)
1-54: LGTM! Configuration structure is well-defined.The configuration properly defines the relayer, signer, networks, and plugin with appropriate settings for the x402 facilitator on Stellar testnet. The asset contract address CBIELTK6YBZJU5UP2WWQEUCYKLPU6AUNZ2BQ4WWFEIE3USCIHMXQDAMA is correct for USDC on Stellar testnet.
examples/x402-facilitator-plugin-example/x402-facilitator/package.json (1)
14-19: Verify package versions are available.ts-node@10.9.2 and typescript@5.3.3 are available; however, the specific versions for @types/node@24.0.3 and @openzeppelin/relayer-sdk@1.8.0 require confirmation through npm registry queries, as they are not documented in publicly available sources.
examples/x402-facilitator-plugin-example/x402-facilitator/index.ts (1)
1-1: The x402 Facilitator plugin GitHub dependency is correctly configured with documented setup steps.The handler re-export from
@openzeppelin/relayer-plugin-x402-facilitatoruses a properly formatted GitHub dependency specification inpackage.json. The example's README includes explicit installation instructions (pnpm installandpnpm run build) as part of the setup process, indicating this is a maintained OpenZeppelin dependency. No action required for this example.docs/guides/stellar-x402-facilitator-guide.mdx (2)
222-250: LGTM!The x402-express integration example is well-structured and demonstrates the key configuration points clearly, including the facilitator URL, network selection, and authentication headers pattern.
283-286: Verified external documentation links.Three of four linked resources are confirmed accessible and valid:
- OpenZeppelin Relayer Documentation: https://docs.openzeppelin.com/relayer ✓
- Stellar SDK Documentation: https://stellar.github.io/js-stellar-sdk/ ✓
- Coinbase x402 GitHub Repository: https://github.com/coinbase/x402 ✓
- x402 Facilitator Plugin Repository: https://github.com/OpenZeppelin/relayer-plugin-x402-facilitator (unable to confirm)
All provided links point to official, authoritative sources.
Summary
This PR will add x402 facilitator plugin example + docs
Plugin: https://github.com/OpenZeppelin/relayer-plugin-x402-facilitator
Note: Depends on #587
Testing Process
Checklist
Note
If you are using Relayer in your stack, consider adding your team or organization to our list of Relayer Users in the Wild!
Summary by CodeRabbit
Release Notes
Documentation
Examples
✏️ Tip: You can customize this high-level summary in your review settings.