x402 多语言支付协议仓库贡献指南从 AI 辅助开发到新增链与新 Scheme 的完整流程【免费下载链接】x402A payments protocol for the internet. Built on HTTP.项目地址: https://gitcode.com/GitHub_Trending/x4/x402导读本文基于 x402 仓库根目录的 CONTRIBUTING.md系统梳理这个互联网原生支付协议A payments protocol for the internet. Built on HTTP.的完整贡献规范。你将掌握AI 辅助开发时的输出约束与合规要求、TypeScript/Python/Go 三套 SDK 的测试与 Changelog 工具链、Paywall 跨语言模板的再生成流程以及新增支付 Scheme 和新增链支持含三 PR 工作流的准入标准与实现路径从而在真实资金转移场景下提交安全、可信、可合并的贡献。一、贡献指南的定位与核心原则x402 是一个面向互联网的开放支付协议客户端client为某个资源resource付费资源服务器resource server提供服务facilitator 负责支付的验证与执行。由于协议处理的是真实的价值转移其贡献指南的第一原则不是如何写代码而是如何保证安全与可信合入贡献由 x402 Foundation 团队根据贡献的风险与实现质量自行裁量而非机械执行任何关于支付、签名、结算的逻辑错误都可能造成真实资金损失贡献的形式不仅限于代码还包括新的 scheme资金移动方式、中间件middleware、新链支持等。这意味着贡献者在动手之前必须先理解仓库的整体布局与各语言 SDK 的既有模式再按规范提交。二、AI 辅助贡献可用但有硬性红线x402 明确允许使用 LLM 与代码助手参与贡献同时设定了一套防止低质量机器生成 PR 淹没维护者的规则提交前必须人工审查 AI 输出不得在未亲自验证生成代码的情况下打开非 Draft PR去除冗余与废话AI 容易产出冗长的文档、注释、PR 描述与提交信息应精简到清晰、有用为止去除重复代码与测试显式与清晰是好的重复与过度解释不是重点核对支付与签名逻辑AI 会生成看起来正确但细节错误的代码——错误的签名流程、错误的链常量、与规范不符的伪造 header。贡献者必须在提交前自行拦截不要批量生成低质量 PRAI 提升的是产出速度应把速度用在更少但更高质量的贡献上显著 AI 使用需披露若 PR 大部分由 AI 生成请在 PR 描述中注明。这不是减分项而是帮助审查者校准审查重点如检查幻觉 API、伪造的测试断言。附带后果明显未经人工审查的 AI 输出泛泛的填充注释、幻觉、冗余样板、套模板的 PR 描述可能不经详细审查直接关闭。官方推荐的 Agent 系统提示词文档给出了可直接放入CLAUDE.md、.cursorrules、codex-instructions.md等本地工作区配置不提交到仓库的完整提示词核心内容如下You are contributing to x402, an open protocol for internet-native payments. x402 handles real value transfer — correctness is critical. Follow these rules for all code, documentation, and commit messages you produce: 1. CONCISE OUTPUT ONLY. Do not add filler comments, redundant docstrings, or verbose explanations. Every line of documentation or commentary must carry useful information. 2. NO REDUNDANCY. Do not generate duplicate or near-duplicate code, tests, or explanations. If logic already exists, use it — do not rewrite it. 3. VERIFY AGAINST THE SPEC. Before writing payment, signing, or settlement logic, read the relevant spec in specs/. Do not invent header names, payload fields, or signing flows. If unsure whether a field or constant exists, search the codebase — do not guess. 4. MATCH EXISTING PATTERNS. Read the surrounding code before generating new code. Match the style, naming conventions, error handling, and test patterns already in use for that SDK (TypeScript, Python, Go, or Java). 5. DO NOT ADD UNREQUESTED FEATURES. Implement exactly what was asked. 6. COMMIT MESSAGES. Use conventional commits (feat:, fix:, docs:, chore:). Keep the subject line under 72 characters. The body should explain why, not what — the diff shows what changed. 7. CHAIN AND TOKEN CONSTANTS. Never hardcode chain IDs, token addresses, or decimal values from memory. Always reference the constants defined in the codebase (e.g., mechanisms/evm/constants, mechanisms/svm/constants). 8. TEST CORRECTNESS. Generated tests must assert meaningful behavior, not just that the function doesnt throw. Do not fabricate expected values — derive them from the spec or existing test fixtures.其中第 3 条与第 7 条在仓库中有直接印证例如 Go SDK 的 go/mechanisms/evm/constants.go 集中定义了 Scheme 标识符、EIP-3009/Permit2 函数名、PERMIT2Address、MULTICALL3Address、X402ExactPermit2ProxyAddressvanity 地址0x4020...0001等常量TypeScript 与 Python 侧同样有对应的mechanisms/evm/constants文件。凡涉及链 ID、代币地址、小数位都必须引用这些既有常量而不是凭记忆硬编码。三、仓库结构与多语言 SDK 布局贡献指南给出的顶层结构如下x402/ ├── typescript/ # TypeScript SDK (pnpm monorepo) ├── python/ # Python SDK ├── go/ # Go SDK ├── java/ # Java SDK ├── specs/ # Protocol specifications └── examples/ # Example implementations ├── typescript/ ├── python/ └── go/从当前仓库实际内容看这一骨架得到了进一步扩展specs/下按schemes/exact、upto 及按链区分的实现、transports-v1/、transports-v2/HTTP、MCP、A2A组织docs/存放面向用户的 GitBook/Mintlify 文档源contracts/为 EVM 智能合约含 Permit2 代理与审计报告e2e/是跨 SDK 的端到端测试go/mechanisms/evm/还包含 exact 与 upto 两套完整机制。每个 SDK 都有一份语言专属的贡献指南供不同技术栈的贡献者按图索骥指南主要内容TypeScript 开发指南pnpm Turborepo 工作区结构、Node ≥18/pnpm ≥10.7 前置要求、包依赖分层、lint/format 命令Python 开发指南uv 管理单包、Pydantic 类型与py.typed、Ruff 规范、pytest-asyncio 自动模式Go 开发指南Go 1.24、golangci-lint、Makefile 命令体系、errors.go中的类型化错误规范编写指南规范类型scheme/transport/core、MUST/SHOULD/MAY 措辞、安全考量章节从源码看三套 SDK 的实现分工以 TypeScript 为例typescript/CONTRIBUTING.md 给出了包依赖的分层结构x402/core ↑ x402/evm, x402/svm ↑ x402/express, x402/hono, x402/next, x402/axios, x402/fetch即core提供与传输无关的协议原语mechanisms包实现链相关逻辑HTTP 包提供框架集成——这也是新增机制时必须遵循的分层边界机制包依赖 coreHTTP 包依赖机制包反之不得依赖。四、标准贡献工作流指南给出了六步标准流程1. 查找或创建 Issue动手前先检查既有 issue对于较大的功能建议先发起 discussion 讨论方案。2. Fork 并 Clone 仓库Fork 仓库后克隆自己的 fork 到本地。3. 创建分支git checkout -b feature/your-feature-name4. 修改代码遵循语言专属开发指南见上文三张子指南为新功能编写测试按需更新文档。5. 测试只运行你修改的包对应的测试# TypeScript cd typescript pnpm test # Python cd python/x402 uv run pytest # Go cd go make test从仓库实际配置看这些命令都有对应的底层实现支撑typescript/package.json 通过 Turborepo 编排build/lint/format/test等脚本test:integration定向跑x402/core、x402/evm等机制包go/Makefile 中make test实际执行go test -race -cover ./...make verify则串联fmt lint test作为提交前的快速自检Python 侧uv run pytest对应python/x402/下tests/unit与tests/integrations两个测试目录。6. 提交 PR完整填写 PR 模板关联相关 issue确保 CI 通过。五、Changelog 工具链三个 SDK 三种工具对于影响用户可见行为的变更行为变化、bug 修复、新功能、破坏性变更必须为所修改的 SDK 添加 changelog fragment纯文档修改和内部重构可跳过。SDK工具Fragment 位置创建命令TypeScriptChangesetstypescript/.changeset/*.mdpnpm -C typescript changesetGoChangiego/.changes/unreleased/*make -C go changelog-newPythonpython/x402 v2Towncrierpython/x402/changelog.d/PR.type.mdcd python/x402 uv run towncrier create --content Fixed ... 123.bugfix.md补充细节TypeScriptpnpm changeset为交互式命令需要选择要发布的包、提供过去时态的变更摘要并选择发布类型——patchbug 修复、无 API 变更、minor向后兼容的新功能、major破坏性变更。拿不准时修复选 patch、非破坏性新功能选 minor维护者会在审查和发布时调整版本号。Pythonfragment 命名约定为PR.type.md允许的 type 为feature | bugfix | doc | removal | misc维护者发布时用uv run towncrier build --yes --versionX.Y.Z合并 fragment。Go维护者侧的批量合并流程为make changelog-batch VERSIONv0.1.0再make changelog-merge见 go/Makefile 中 changie 相关 target。六、提交签名所有提交必须签名所有提交必须使用 GPG/SSH 签名后再推送git config --global commit.gpgsign true提交签名应在提交前配置完成未签名的提交无法通过合入流程。七、Paywall 变更一次修改、五处产物paywall 是一个横跨 TypeScript、Go、Python 的浏览器端 UI 组件。修改 TypeScript 中的 paywall 源码后需要重新生成各语言的模板文件cd typescript pnpm --filter x402/paywall build:paywall该命令会在以下位置生成模板文件PR 中需一并提交语言生成文件TypeScripttypescript/packages/http/paywall/src/evm/gen/template.ts、typescript/packages/http/paywall/src/svm/gen/template.tsGogo/http/evm_paywall_template.go、go/http/svm_paywall_template.goPythonpython/x402/http/paywall/evm_paywall_template.pysvm 模板同目录从仓库实际文件看这些生成产物确实存在且一一对应例如 go/http/evm_paywall_template.go 与 go/http/svm_paywall_template.goTypeScript 侧则按链分别输出到src/evm/gen/template.ts与src/svm/gen/template.ts。规则是修改 paywall 源码必须同步提交重新生成的模板否则跨语言产物会不一致。八、新增 Scheme三步提案制Scheme 定义了资金如何从 client 流向 server。不同的 scheme 具有不同的操作语义——例如exact先付固定金额再访问资源如支付 $1 阅读一篇文章与upto按请求实际消耗的资源付费如按 token 生成量计费的 LLM行为截然不同。新增 scheme 需要经过 x402 Foundation 团队的严格审查推荐流程为打开一个只含 spec 的 PR把方案文档放入specs/schemes/在该 PR 中讨论架构与目的spec 合入后再进行实现。spec 写作遵循 specs/CONTRIBUTING.md使用scheme_template.md方案总览与scheme_impl_template.md链实现模板必须包含 payload 结构、验证逻辑、结算逻辑三要素并以 MUST/SHOULD/MAY 精确措辞。可参考已合入的规范范例 specs/schemes/exact/scheme_exact_evm.md含PAYMENT-SIGNATUREheader payload 示例、验证五步、结算逻辑以及仓库中已有的 scheme_exact_svm.md、scheme_upto_evm.md 等多链实现。九、新增链支持三 PR 工作流x402 的目标是链无关chain-agnostic。由于不同链的最佳实践不同同一 scheme 在不同链上的机制实现可能完全不同例如在 Ethereum 与 Solana 上实现exact的方式截然不同如果方案机制偏离参考实现x402 Foundation 会在接受前对该链上的方案重新审计。9.1 快捷路径仅为 EVM 链添加默认资产如果只是为 EVM 兼容链添加美元定价$0.10所需的默认稳定币不需要走下面的完整三 PR 流程直接参考 DEFAULT_ASSETS.md在 TypeScript、Go、Python 三个 SDK 的常量文件中同步添加 CAIP-2 键对应的代币信息地址、EIP-712name/version、decimals、资产转移方式三处必须使用相同参数。对应文件分别为typescript/packages/mechanisms/evm/src/shared/defaultAssets.ts、go/mechanisms/evm/constants.goNetworkConfigsmap与 Python 的python/x402/mechanisms/evm/constants.pyNETWORK_CONFIGSdict。9.2 完整流程新增链族PR 1仅提交规范为某一个支付 scheme 的实现提交 spec添加specs/schemes/scheme/scheme_scheme_chain.md遵循现有 spec 格式参考 specs/schemes/exact/scheme_exact_evm.md必须包含payload 结构、验证逻辑、结算逻辑写作规范见 specs/CONTRIBUTING.md。PR 2参考实现spec 获批后先在一个 SDKTypeScript、Python 或 Go 三选一中实现包结构TS 创建sdk/packages/mechanisms/chain/Py/Go 创建sdk/mechanisms/chain/不得修改 core 包必需接口各 SDK 一一对应SDK接口TypeScriptx402/coreSchemeNetworkClient、SchemeNetworkServer、SchemeNetworkFacilitatorGogithub.com/x402-foundation/x402/goClientScheme、ServerScheme、FacilitatorSchemePythonx402SchemeNetworkClient、SchemeNetworkServer、SchemeNetworkFacilitator必需测试三个层级类型目的参考位置单元测试隔离的组件测试typescript/packages/mechanisms/evm/test/unit/集成测试client/server/facilitator 全流程typescript/packages/mechanisms/evm/test/integrations/端到端测试跨 SDK 全栈验证e2e/示例保持现有用户示例精简将新链按网络前缀字母序添加到examples/sdk/*/advanced/all_networks的 server、client、facilitator 三类示例中后续步骤按既有模式补充包发布工作流、为新增包编写 README参考typescript/packages/mechanisms/evm/README.mddocs/中的 GitDocs 会由 Mintlify 自动更新。PR 3补充其他 SDK 实现参考实现合入后可跟进实现其余 SDK 的对应机制。9.3 接口语义的源码印证以 EVM 为例go/mechanisms/evm/constants.go 揭示了机制包背后的实现细节exact方案在 EVM 上通过 EIP-3009transferWithAuthorization推荐真正无 gas或 Permit2 代理任意 ERC-20 的通用回退完成转账facilitator 只能作为交易广播者无法篡改金额与收款方upto方案则使用独立的X402UptoPermit2ProxyAddress0x4020...0002。这套常量体系正是上文 AI 提示词第 7 条从代码库引用常量而非记忆硬编码的直接依据。十、HTTP 中间件与示例中间件新增 HTTP 框架集成如 Echo、Chi 或新 TS/Python 框架时应遵循目标框架的最佳实践、包含测试、并沿用既有 x402 client/server 模式。Go 侧可参考 go/http/gin/middleware.go 的完整模式通过HTTPResourceServer.HandleRequest()处理PAYMENT-SIGNATUREheader 并返回 402 或放行TypeScript 侧可参考typescript/packages/http/express/src/adapter.ts的 adapter 模式。示例各语言示例位于 examples/新增示例时遵循对应语言指南中的模式Go 示例需提供引用本地 SDK 的go.mod通过replace指令指向仓库内的go模块。十一、获取帮助搜索既有 issue避免重复提问用新 issue 提出疑问查阅各语言专属贡献指南与角色文档Go 侧还有 CLIENT.md、SERVER.md、FACILITATOR.md 供使用模式参考。结语一份以可信为第一诉求的贡献规范纵观整份指南x402 的贡献流程始终围绕两个关键词展开安全性真实资金转移、签名与结算逻辑必须经过人工核验与跨 SDK 一致性检查与可维护性精简输出、复用既有常量与模式、强制 changelog fragment、paywall 五处产物同步。无论是人类开发者还是 AI 编程 Agent遵循这份规范的核心要义都在于用更少、更高质量、更可验证的贡献换取协议在更多网络与更多 scheme 上的可信扩展。【免费下载链接】x402A payments protocol for the internet. Built on HTTP.项目地址: https://gitcode.com/GitHub_Trending/x4/x402创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考