From 5b18e8008d8a438127e4f99aaac9b7f8a2e1013a Mon Sep 17 00:00:00 2001 From: jhfnetboy Date: Tue, 28 Apr 2026 20:14:49 +0700 Subject: [PATCH 1/5] =?UTF-8?q?chore:=20Apache=202.0=20license=20complianc?= =?UTF-8?q?e=20=E2=80=94=20bilingual=20five-file=20set?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add/update LICENSE, NOTICE, TRADEMARK.md, LICENSE-zh.md, TRADEMARK-zh.md per MushroomDAO ecosystem standard. --- LICENSE | 180 ++++++++++++++++++++++++++++++++++++++++++++++++ LICENSE-zh.md | 80 +++++++++++++++++++++ NOTICE | 21 ++++++ TRADEMARK-zh.md | 143 ++++++++++++++++++++++++++++++++++++++ TRADEMARK.md | 177 +++++++++++++++++++++++++++++++++++++++++++++++ 5 files changed, 601 insertions(+) create mode 100644 LICENSE create mode 100644 LICENSE-zh.md create mode 100644 NOTICE create mode 100644 TRADEMARK-zh.md create mode 100644 TRADEMARK.md diff --git a/LICENSE b/LICENSE new file mode 100644 index 000000000..234f29e11 --- /dev/null +++ b/LICENSE @@ -0,0 +1,180 @@ + Apache License + Version 2.0, January 2004 + http://www.apache.org/licenses/ + +TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION + +1. Definitions. + +"License" shall mean the terms and conditions for use, reproduction, and +distribution as defined by Sections 1 through 9 of this document. + +"Licensor" shall mean the copyright owner or entity authorized by the +copyright owner that is granting the License. + +"Legal Entity" shall mean the union of the acting entity and all other +entities that control, are controlled by, or are under common control with +that entity. For the purposes of this definition, "control" means (i) the +power, direct or indirect, to cause the direction or management of such +entity, whether by contract or otherwise, or (ii) ownership of fifty +percent (50%) or more of the outstanding shares, or (iii) beneficial +ownership of such entity. + +"You" (or "Your") shall mean an individual or Legal Entity exercising +permissions granted by this License. + +"Source" form shall mean the preferred form for making modifications, +including but not limited to software source code, documentation source, +and configuration files. + +"Object" form shall mean any form resulting from mechanical transformation +or translation of a Source form, including but not limited to compiled +object code, generated documentation, and conversions to other media types. + +"Work" shall mean the work of authorship, whether in Source or Object form, +made available under the License, as indicated by a copyright notice that +is included in or attached to the work (an example is provided in the +Appendix below). + +"Derivative Works" shall mean any work, whether in Source or Object form, +that is based on (or derived from) the Work and for which the editorial +revisions, annotations, elaborations, or other modifications represent, +as a whole, an original work of authorship. For the purposes of this +License, Derivative Works shall not include works that remain separable +from, or merely link (or bind by name) to the interfaces of, the Work +and Derivative Works thereof. + +"Contribution" shall mean any work of authorship, including the original +version of the Work and any modifications or additions to that Work or +Derivative Works thereof, that is intentionally submitted to the Licensor +for inclusion in the Work by the copyright owner or by an individual or +Legal Entity authorized to submit on behalf of the copyright owner. For +the purposes of this definition, "submitted" means any form of electronic, +verbal, or written communication sent to the Licensor or its +representatives, including but not limited to communication on electronic +mailing lists, source code control systems, and issue tracking systems +that are managed by, or on behalf of, the Licensor for the purpose of +discussing and improving the Work, but excluding communication that is +conspicuously marked or otherwise designated in writing by the copyright +owner as "Not a Contribution." + +"Contributor" shall mean Licensor and any individual or Legal Entity on +behalf of whom a Contribution has been received by the Licensor and +subsequently incorporated within the Work. + +2. Grant of Copyright License. Subject to the terms and conditions of this +License, each Contributor hereby grants to You a perpetual, worldwide, +non-exclusive, no-charge, royalty-free, irrevocable copyright license to +reproduce, prepare Derivative Works of, publicly display, publicly perform, +sublicense, and distribute the Work and such Derivative Works in Source or +Object form. + +3. Grant of Patent License. Subject to the terms and conditions of this +License, each Contributor hereby grants to You a perpetual, worldwide, +non-exclusive, no-charge, royalty-free, irrevocable (except as stated in +this section) patent license to make, have made, use, offer to sell, sell, +import, and otherwise transfer the Work, where such license applies only +to those patent claims licensable by such Contributor that are necessarily +infringed by their Contribution(s) alone or by combination of their +Contribution(s) with the Work to which such Contribution(s) was submitted. +If You institute patent litigation against any entity (including a +cross-claim or counterclaim in a lawsuit) alleging that the Work or a +Contribution incorporated within the Work constitutes direct or +contributory patent infringement, then any patent licenses granted to You +under this License for that Work shall terminate as of the date such +litigation is filed. + +4. Redistribution. You may reproduce and distribute copies of the Work or +Derivative Works thereof in any medium, with or without modifications, and +in Source or Object form, provided that You meet the following conditions: + +(a) You must give any other recipients of the Work or Derivative Works a +copy of this License; and + +(b) You must cause any modified files to carry prominent notices stating +that You changed the files; and + +(c) You must retain, in the Source form of any Derivative Works that You +distribute, all copyright, patent, trademark, and attribution notices from +the Source form of the Work, excluding those notices that do not pertain to +any part of the Derivative Works; and + +(d) If the Work includes a "NOTICE" text file as part of its distribution, +then any Derivative Works that You distribute must include a readable copy +of the attribution notices contained within such NOTICE file, excluding any +notices that do not pertain to any part of the Derivative Works, in at +least one of the following places: within a NOTICE text file distributed as +part of the Derivative Works; within the Source form or documentation, if +provided along with the Derivative Works; or, within a display generated by +the Derivative Works, if and wherever such third-party notices normally +appear. The contents of the NOTICE file are for informational purposes only +and do not modify the License. You may add Your own attribution notices +within Derivative Works that You distribute, alongside or as an addendum to +the NOTICE text from the Work, provided that such additional attribution +notices cannot be construed as modifying the License. + +You may add Your own copyright statement to Your modifications and may +provide additional or different license terms and conditions for use, +reproduction, or distribution of Your modifications, or for any such +Derivative Works as a whole, provided Your use, reproduction, and +distribution of the Work otherwise complies with the conditions stated in +this License. + +5. Submission of Contributions. Unless You explicitly state otherwise, any +Contribution intentionally submitted for inclusion in the Work by You to +the Licensor shall be under the terms and conditions of this License, +without any additional terms or conditions. Notwithstanding the above, +nothing herein shall supersede or modify the terms of any separate license +agreement you may have executed with Licensor regarding such Contributions. + +6. Trademarks. This License does not grant permission to use the trade +names, trademarks, service marks, or product names of the Licensor, except +as required for reasonable and customary use in describing the origin of +the Work and reproducing the content of the NOTICE file. + +7. Disclaimer of Warranty. Unless required by applicable law or agreed to +in writing, Licensor provides the Work (and each Contributor provides its +Contributions) on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +KIND, either express or implied, including, without limitation, any +warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or +FITNESS FOR A PARTICULAR PURPOSE. You are solely responsible for +determining the appropriateness of using or redistributing the Work and +assume any risks associated with Your exercise of permissions under this +License. + +8. Limitation of Liability. In no event and under no legal theory, whether +in tort (including negligence), contract, or otherwise, unless required by +applicable law (such as deliberate and grossly negligent acts) or agreed to +in writing, shall any Contributor be liable to You for damages, including +any direct, indirect, special, incidental, or consequential damages of any +character arising as a result of this License or out of the use or +inability to use the Work (including but not limited to damages for loss of +goodwill, work stoppage, computer failure or malfunction, or any and all +other commercial damages or losses), even if such Contributor has been +advised of the possibility of such damages. + +9. Accepting Warranty or Additional Liability. While redistributing the +Work or Derivative Works thereof, You may choose to offer, and charge a fee +for, acceptance of support, warranty, indemnity, or other liability +obligations and/or rights consistent with this License. However, in +accepting such obligations, You may act only on Your own behalf and on Your +sole responsibility, not on behalf of any other Contributor, and only if +You agree to indemnify, defend, and hold each Contributor harmless for any +liability incurred by, or claims asserted against, such Contributor by +reason of your accepting any such warranty or additional liability. + +END OF TERMS AND CONDITIONS + +Copyright 2024-present MushroomDAO Contributors + +Licensed under the Apache License, Version 2.0 (the "License"); +you may not use this file except in compliance with the License. +You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. diff --git a/LICENSE-zh.md b/LICENSE-zh.md new file mode 100644 index 000000000..a92c6acdd --- /dev/null +++ b/LICENSE-zh.md @@ -0,0 +1,80 @@ +# Apache 许可证 2.0 版 — 非官方中文参考译本 + +> **重要声明**：本文件为 Apache License 2.0 的非官方中文参考译本，仅供理解之用。 +> 本译本不具有法律效力，以英文原版 `LICENSE` 文件为准。 +> 英文原版：http://www.apache.org/licenses/LICENSE-2.0 +> +> **IMPORTANT**: This is an unofficial Chinese translation of the Apache License 2.0, +> provided for reference only. It is NOT legally binding. The authoritative version +> is the English original in the `LICENSE` file. + +--- + +## Apache 许可证 + +版本 2.0，2004 年 1 月 + +http://www.apache.org/licenses/ + +### 使用、复制和分发的条款和条件 + +**1. 定义** + +"许可证"是指本文件第 1 至第 9 节所定义的使用、复制和分发的条款和条件。 + +"许可方"是指授予本许可证的版权所有者或由版权所有者授权的实体。 + +"法律实体"是指行为实体与所有控制该实体、被该实体控制或与该实体处于共同控制之下的其他实体的联合体。就此定义而言，"控制"是指 (i) 通过合同或其他方式直接或间接引导或管理该实体的权力，或 (ii) 持有百分之五十 (50%) 或更多的已发行股份，或 (iii) 该实体的受益所有权。 + +"您"（或"您的"）是指行使本许可证授予的权限的个人或法律实体。 + +"源"形式是指进行修改的首选形式，包括但不限于软件源代码、文档源和配置文件。 + +"目标"形式是指由源形式经机械转换或翻译产生的任何形式，包括但不限于编译的目标代码、生成的文档以及转换为其他媒体类型的内容。 + +"作品"是指根据本许可证提供的、以源形式或目标形式表现的著作权作品，如附在作品中或与作品关联的版权声明所示。 + +"衍生作品"是指基于（或派生自）该作品的、以源形式或目标形式表现的任何作品，其中的编辑修订、注释、阐述或其他修改作为整体构成原创性著作。就本许可证而言，衍生作品不包括与该作品及其衍生作品的接口保持分离或仅通过名称链接（或绑定）的作品。 + +"贡献"是指任何著作权作品，包括该作品的原始版本及对该作品或其衍生作品的任何修改或补充，由版权所有者或由获得版权所有者授权的个人或法律实体有意提交给许可方以纳入该作品。就此定义而言，"提交"是指发送给许可方或其代表的任何形式的电子、口头或书面通信，包括但不限于由许可方或代表许可方管理的、以讨论和改进该作品为目的的电子邮件列表、源代码控制系统和问题跟踪系统上的通信，但不包括版权所有者以书面形式明确标记或以其他方式指定为"非贡献"的通信。 + +"贡献者"是指许可方和其贡献已被许可方接收并纳入该作品的任何个人或法律实体。 + +**2. 版权许可的授予。** 在遵守本许可证条款和条件的前提下，每位贡献者特此授予您永久的、全球性的、非排他性的、免费的、免版税的、不可撤销的版权许可，以复制、准备衍生作品、公开展示、公开表演、再许可和分发该作品及其衍生作品（以源形式或目标形式）。 + +**3. 专利许可的授予。** 在遵守本许可证条款和条件的前提下，每位贡献者特此授予您永久的、全球性的、非排他性的、免费的、免版税的、不可撤销的（本节另有规定的除外）专利许可，以制造、委托制造、使用、许诺销售、销售、进口和以其他方式转让该作品，该许可仅适用于该贡献者可许可的、因其贡献单独或其贡献与提交贡献时的作品组合而必然被侵犯的专利权利要求。如果您对任何实体（包括诉讼中的交叉索赔或反诉）提起专利诉讼，声称该作品或纳入该作品的贡献构成直接或间接专利侵权，则根据本许可证授予您的关于该作品的任何专利许可自该诉讼提起之日起终止。 + +**4. 再分发。** 您可以在任何媒介中复制和分发该作品或其衍生作品的副本（无论是否经过修改，以源形式或目标形式），前提是您满足以下条件： + +(a) 您必须向该作品或衍生作品的任何其他接收者提供本许可证的副本；且 + +(b) 您必须使任何修改过的文件带有显著的声明，说明您更改了这些文件；且 + +(c) 您必须在您分发的任何衍生作品的源形式中保留来自该作品源形式的所有版权、专利、商标和归属声明，但不包括与衍生作品的任何部分无关的声明；且 + +(d) 如果该作品包含 "NOTICE" 文本文件作为其分发的一部分，则您分发的任何衍生作品必须在以下至少一个位置包含该 NOTICE 文件中所含归属声明的可读副本（不包括与衍生作品的任何部分无关的声明）：作为衍生作品一部分分发的 NOTICE 文本文件中；衍生作品附带的源形式或文档中；或者，在衍生作品生成的显示中（如果此类第三方声明通常出现在此处）。NOTICE 文件的内容仅供参考，不修改本许可证。 + +**5. 贡献的提交。** 除非您另有明确声明，否则您有意提交给许可方以纳入该作品的任何贡献均应遵守本许可证的条款和条件，不附加任何额外条款或条件。 + +**6. 商标。** 本许可证不授予使用许可方的商号、商标、服务标志或产品名称的许可，除非在描述该作品的来源和复制 NOTICE 文件内容时合理和惯常使用。 + +**7. 免责声明。** 除非适用法律要求或以书面形式同意，许可方按"原样"提供该作品（每位贡献者按"原样"提供其贡献），不附带任何明示或暗示的保证或条件，包括但不限于所有权、不侵权、适销性或特定用途适用性的保证或条件。 + +**8. 责任限制。** 在任何情况下，无论基于何种法律理论，无论是侵权（包括过失）、合同还是其他理论，除非适用法律要求（如故意和重大过失行为）或以书面形式同意，任何贡献者均不对您承担损害赔偿责任。 + +**9. 接受保证或附加责任。** 在再分发该作品或其衍生作品时，您可以选择提供并收取费用，以接受与本许可证一致的支持、保证、赔偿或其他责任义务和/或权利。但在接受此类义务时，您只能代表您自己并由您自行承担责任，不得代表任何其他贡献者。 + +--- + +条款和条件结束 + +版权所有 2024-至今 MushroomDAO 贡献者 + +根据 Apache 许可证 2.0 版（以下简称"许可证"）获得许可； +除非遵守本许可证，否则您不得使用本文件。 +您可以在以下网址获取许可证副本： + +http://www.apache.org/licenses/LICENSE-2.0 + +除非适用法律要求或以书面形式同意，根据本许可证分发的软件按"原样"分发， +不附带任何明示或暗示的保证或条件。请参阅许可证以了解管辖权限和限制的具体语言。 diff --git a/NOTICE b/NOTICE new file mode 100644 index 000000000..b9c523338 --- /dev/null +++ b/NOTICE @@ -0,0 +1,21 @@ +Mycelium Protocol — SuperRelay +Copyright 2024-present MushroomDAO Contributors + +This product includes software developed by MushroomDAO +(https://github.com/MushroomDAO). + +Licensed under the Apache License, Version 2.0. +See LICENSE file for full terms. +本产品使用 Apache 许可证 2.0 版，参见 LICENSE 文件（英文原版）及 LICENSE-zh.md（中文参考译本）。 + +== Attribution / 归属声明 == + +Per Apache 2.0 Section 4(d), derivative works that distribute this software +must retain this NOTICE file. +根据 Apache 2.0 第 4(d) 条，分发本软件的衍生作品必须保留本 NOTICE 文件。 + +== Trademark / 商标 == + +MushroomDAO, Mycelium Protocol, GToken, PNTs, and related names are trademarks +of MushroomDAO. Forks must rebrand. See TRADEMARK.md (English) / TRADEMARK-zh.md (中文). +MushroomDAO、Mycelium Protocol、GToken、PNTs 及相关名称为 MushroomDAO 的商标。分叉须更名。 diff --git a/TRADEMARK-zh.md b/TRADEMARK-zh.md new file mode 100644 index 000000000..ebae466e8 --- /dev/null +++ b/TRADEMARK-zh.md @@ -0,0 +1,143 @@ +# MushroomDAO 商标政策 + +> 最后更新：2026-04-15 +> 英文版（法律效力等同）：[TRADEMARK.md](TRADEMARK.md) + +--- + +## 目的 + +MushroomDAO 的源代码根据 Apache 许可证 2.0 版开放——这是一个完全宽松的、经 OSI 批准的开源许可证。任何人都可以使用、修改和分发代码，包括用于商业目的。 + +但是，MushroomDAO 及其产品的**名称、标志和品牌**不在 Apache 2.0 许可证的覆盖范围内。本商标政策说明了您可以和不可以对 MushroomDAO 的标识做什么。 + +本政策参照 [Mozilla 基金会商标政策](https://www.mozilla.org/en-US/foundation/trademarks/policy/)制定。该政策确立了一个先例：开源代码可以自由分叉，但要求分叉版本使用不同的品牌名称（例如 Debian 将 Firefox 重新命名为 Iceweasel）。 + +--- + +## 受保护的名称 + +以下名称是 MushroomDAO 及其关联实体的商标： + +### 项目与协议名称 +- **MushroomDAO** +- **Mycelium Protocol** / **Mycelium**（菌丝协议） +- **Park Protocol** +- **CityOS** +- **Cos72** +- **Sin90** + +### 代币与积分名称 +- **GToken** +- **PNTs** / **xPNTs** / **aPNTs** +- **Spores** + +### 产品与服务名称 +- **AAStar** +- **AirAccount** +- **SuperPaymaster** +- **OpenNest** +- **AuraAI** + +### 公司与组织名称 +- **HyperCapital** + +--- + +## 受保护的标志 + +以下标志受到保护（实际文件待添加）： + +- MushroomDAO 标志（蘑菇图标 + 文字标识） +- AAStar 标志 +- AuraAI 标志 +- Mycelium Protocol 标志 +- GToken 符号 + +*（标志文件将在品牌设计完成后存放于此目录，预计 2026 年第三季度。）* + +--- + +## 使用规则 + +### 您可以： + +1. **自由使用代码** —— 根据 Apache 2.0 许可证，商标政策不限制代码的使用。 + +2. **说明兼容性。** 您可以在描述性文字、文档和营销材料中如实声明您的项目"兼容 Mycelium Protocol"或"基于 MushroomDAO 技术构建"。 + +3. **链接到 MushroomDAO。** 您可以链接到 MushroomDAO 的仓库、网站和文档。 + +4. **讨论 MushroomDAO。** 您可以在文章、博客文章、演讲和其他关于该项目的评论中使用这些名称。 + +### "Powered By" / 兼容性声明： + +分叉和衍生作品**可以**在描述性文字（如 README、文档、营销文案）中使用 **"Compatible with Mycelium Protocol"**（兼容菌丝协议）或 **"Powered by Mycelium"**（由菌丝驱动）等短语，**前提是**它们确实与 Mycelium Protocol 网络互操作。这些属于许可的**指示性合理使用**——它们描述事实关系，而非品牌隶属。 + +这与下面的分叉更名要求是分开的：您必须从**产品名称和界面**中移除 MushroomDAO 商标，但可以在**文档和营销文字**中使用描述性兼容声明。 + +所有分叉和衍生作品**必须**根据 Apache 2.0 第 4(d) 条保留 NOTICE 文件。 + +### 您不可以： + +1. **在产品名称中使用受保护名称。** 您不得将产品命名为"Mycelium Wallet"、"MushroomDAO Enterprise"、"GToken Exchange"或任何暗示官方隶属的类似名称。 + +2. **未经书面许可使用受保护标志。** + +3. **暗示背书或隶属关系。** 您不得暗示您的项目受到 MushroomDAO 的背书、与其有关联或是其官方组成部分（除非获得明确的书面授权）。 + +4. **注册易混淆的类似名称。** 您不得注册与上述受保护名称容易混淆的域名、社交媒体账户或商标。 + +5. **删除 NOTICE 文件。** 您不得从再分发或衍生作品中删除 NOTICE 文件。这是 Apache 2.0 许可证（第 4 条）的要求，与本商标政策无关。 + +### 分叉规则： + +如果您分叉了 MushroomDAO 的仓库： + +- 您**必须**从分叉中移除所有 MushroomDAO 商标，包括： + - 界面、文档和配置中的产品名称 + - 标志、图标和品牌资产 + - 暗示该分叉是 MushroomDAO 官方产品的引用 +- 您**可以**声明："本项目是 MushroomDAO [原始仓库名] 的分叉" +- 您**必须**为分叉选择不包含任何受保护名称的新名称 + +这与 Debian 将 Firefox 重新命名为 Iceweasel 的模式相同：代码在 Mozilla 公共许可证下自由可用，但 Firefox 的名称和标志需要单独的商标许可。 + +--- + +## 请求许可 + +如果您希望以上述规则未涵盖的方式使用 MushroomDAO 商标，请联系我们： + +- **邮箱：** jason@aastar.io +- **GitHub：** 在 [MushroomDAO/.github](https://github.com/MushroomDAO/.github/issues) 提交 issue + +我们通常支持社区使用，并将在 14 天内回复。 + +--- + +## 执行 + +MushroomDAO 保留以下权利： + +- 要求移除未经授权的商标使用 +- 提前 30 天通知撤销先前授予的商标许可 +- 在故意侵权的情况下采取法律行动 + +我们倾向于在采取正式行动之前通过友好沟通解决商标问题。 + +--- + +## 开源承诺 + +MushroomDAO 致力于遵守由[开源促进会](https://opensource.org)维护的[开源定义](https://opensource.org/osd)。 + +我们选择真正的开源（[Apache 2.0](https://opensource.org/licenses/Apache-2.0)，经 OSI 批准）作为构建数字公共物品的行为。我们请求您尊重使这一切成为可能的归属声明。 + +--- + +## 联系方式 + +- **商标咨询：** jason@aastar.io +- **项目一般问题：** https://github.com/MushroomDAO/.github/issues +- **Telegram：** https://t.me/Account_Abstraction_Community diff --git a/TRADEMARK.md b/TRADEMARK.md new file mode 100644 index 000000000..4297f677d --- /dev/null +++ b/TRADEMARK.md @@ -0,0 +1,177 @@ +# MushroomDAO Trademark Policy + +> Last updated: 2026-04-28 +> 中文版 / Chinese version: [TRADEMARK-zh.md](TRADEMARK-zh.md) + +--- + +## Purpose + +MushroomDAO's source code is licensed under the Apache License 2.0 — a fully +permissive, OSI-approved open source license. Anyone may use, modify, and +distribute the code, including for commercial purposes. + +However, the **names, logos, and branding** of MushroomDAO and its products are +**not** covered by the Apache 2.0 license. This trademark policy explains what +you can and cannot do with MushroomDAO's marks. + +This policy is modeled after the [Mozilla Foundation Trademark Policy](https://www.mozilla.org/en-US/foundation/trademarks/policy/), +which established the precedent that open source code can be freely forked while +requiring forks to use different branding (e.g., Firefox → Iceweasel in Debian). + +--- + +## Protected Names + +The following names are trademarks of MushroomDAO and its affiliated entities: + +### Project & Protocol Names +- **MushroomDAO** +- **Mycelium Protocol** / **Mycelium** +- **Park Protocol** +- **CityOS** +- **Cos72** +- **Sin90** + +### Token & Points Names +- **GToken** +- **PNTs** / **xPNTs** / **aPNTs** +- **Spores** + +### Product & Service Names +- **AAStar** +- **AirAccount** +- **SuperPaymaster** +- **OpenNest** +- **AuraAI** + +### Company & Organization Names +- **HyperCapital** + +--- + +## Protected Logos + +The following logos are protected (actual files to be added): + +- MushroomDAO logo (mushroom icon + wordmark) +- AAStar logo +- AuraAI logo +- Mycelium Protocol logo +- GToken symbol + +*(Logo files will be deposited in this directory when brand design is finalized, estimated Q3 2026.)* + +--- + +## Rules for Use + +### You MAY: + +1. **Use the code freely** under Apache 2.0 — the trademark policy does not + restrict code usage. + +2. **Refer to compatibility.** You may truthfully state that your project is + "compatible with Mycelium Protocol" or "built on MushroomDAO technology" + in descriptive text, documentation, and marketing materials. + +3. **Link to MushroomDAO.** You may link to MushroomDAO's repositories, + website, and documentation. + +4. **Discuss MushroomDAO.** You may use the names in articles, blog posts, + talks, and other commentary about the project. + +### "Powered By" / Compatibility Statements: + +Forks and derivative works **MAY** use the phrases **"Compatible with Mycelium +Protocol"** or **"Powered by Mycelium"** in descriptive text (e.g., README, +documentation, marketing copy), **ONLY IF** they actually interoperate with +the Mycelium Protocol network. These are permitted **nominative uses** — they +describe a factual relationship, not brand affiliation. + +This is separate from the fork rebranding requirement below: you must remove +MushroomDAO trademarks from your **product name and UI**, but you may use +descriptive compatibility statements in **documentation and marketing text**. + +All forks and derivatives **MUST** retain the NOTICE file per Apache 2.0 +Section 4(d). + +### You MAY NOT: + +1. **Use protected names in your product name.** You may NOT name your + product "Mycelium Wallet", "MushroomDAO Enterprise", "GToken Exchange", + or any similar formulation that implies official affiliation. + +2. **Use protected logos** without written permission from MushroomDAO. + +3. **Imply endorsement or affiliation.** You may NOT suggest that your + project is endorsed by, affiliated with, or an official part of + MushroomDAO without explicit written authorization. + +4. **Register confusingly similar names.** You may NOT register domain + names, social media accounts, or trademarks that are confusingly + similar to the protected names listed above. + +5. **Delete the NOTICE file.** You may NOT remove the NOTICE file from + redistributions or derivative works. This is required by the Apache 2.0 + license (Section 4), independent of this trademark policy. + +### Forks: + +If you fork a MushroomDAO repository: + +- You **must** remove all MushroomDAO trademarks from the fork, including: + - Product names in the UI, documentation, and configuration + - Logos, icons, and branding assets + - References that imply the fork is an official MushroomDAO product +- You **may** state: "This project is a fork of [original repo name] by MushroomDAO" +- You **must** choose a new name for your fork that does not include any + protected names + +This is the same model used by Debian when they rebranded Firefox as Iceweasel: +the code was freely available under the Mozilla Public License, but the Firefox +name and logo required separate trademark permission. + +--- + +## Requesting Permission + +If you would like to use a MushroomDAO trademark in a way not covered by the +rules above, please contact us: + +- **Email:** jason@aastar.io +- **GitHub:** Open an issue in [MushroomDAO/.github](https://github.com/MushroomDAO/.github/issues) + +We are generally supportive of community use and will respond within 14 days. + +--- + +## Enforcement + +MushroomDAO reserves the right to: + +- Request removal of unauthorized trademark use +- Revoke previously granted trademark permissions with 30 days notice +- Take legal action in cases of willful infringement + +We prefer to resolve trademark issues through friendly communication before +taking formal action. + +--- + +## Open Source Commitment + +MushroomDAO is committed to the [Open Source Definition](https://opensource.org/osd) +as maintained by the [Open Source Initiative](https://opensource.org). + +We have chosen genuine open source ([Apache 2.0](https://opensource.org/licenses/Apache-2.0), +OSI-approved) as an act of building digital public goods. We ask that you respect +the attribution that makes this possible. + +--- + +## Contact + +- **Trademark inquiries:** jason@aastar.io +- **General project questions:** https://github.com/MushroomDAO/.github/issues +- **Telegram:** https://t.me/Account_Abstraction_Community From 760766e71363a6307e0b8bddd5f1a41db1c008c2 Mon Sep 17 00:00:00 2001 From: jhfnetboy Date: Tue, 28 Apr 2026 20:24:19 +0700 Subject: [PATCH 2/5] docs: update license badge from MIT to Apache-2.0 # Conflicts: # README.md --- README.md | 792 ++++++++++++++++++++++++++++++++++++++++++++++++------ 1 file changed, 711 insertions(+), 81 deletions(-) diff --git a/README.md b/README.md index 9bae589c5..206be916d 100644 --- a/README.md +++ b/README.md @@ -1,140 +1,770 @@ -# Rundler +# SuperRelay v0.1.5 - Enterprise API Gateway for Account Abstraction -[![gh_ci_badge]][gh_ci_link] -[![tg_badge]][tg_link] +**English** | [中文](#中文版本) -[gh_ci_badge]: https://github.com/alchemyplatform/rundler/workflows/ci/badge.svg -[gh_ci_link]: https://github.com/alchemyplatform/rundler/actions/workflows/ci.yml -[tg_badge]: https://img.shields.io/endpoint?color=neon&logo=telegram&label=chat&url=https://mogyo.ro/quart-apis/tgmembercount?chat_id=rundler -[tg_link]: https://t.me/rundler +AAStar's SuperPaymaster includes SuperRelay and SuperPaymaster contracts. SuperRelay is an enterprise API gateway built on Rundler (Alchemy's ERC-4337 bundler) that provides gas sponsorship + authentication & authorization + enterprise policies + monitoring & alerting through zero-invasion architecture for the ERC-4337 ecosystem. -**High-performance, modular implementation of an ERC-4337 bundler** +## 🌐 New Gateway Architecture (v0.1.5) -![Rundler Banner](./docs/images/rundler-banner.jpg) +**Architecture Advantages**: +- **Single Binary Deployment**: Unified binary deployment, simplified operations +- **Zero-Invasion Design**: Zero modifications to upstream rundler project, ensuring update capability +- **Internal Routing**: Access rundler components through internal method calls, avoiding RPC overhead +- **Enterprise Features**: Authentication, rate limiting, policy execution unified at gateway layer -[Run](#running) | [Developer Docs](./docs) +## 🔄 Dual-Service Architecture Flow Diagram -🚧 *Under active development, see [status](#status) below.* 🚧 +SuperRelay implements a dual-service compatible architecture with component sharing, providing both enterprise features and full rundler compatibility: -## Overview +```mermaid +graph TD + A[Client Applications] --> B{Service Selection} -**Rundler** (**R**ust B**undler**) is an [ERC-4337][eip_link] bundler implementation written in Rust. Rundler is designed to achieve high-performance and high-reliability in cloud deployments via a modular architecture. + B -->|Legacy Clients| C[Rundler Service :3001] + B -->|Enterprise Clients| D[SuperRelay Gateway :3000] -Built, maintained, and used by [Alchemy](https://www.alchemy.com/) to push the limits of user experience on EVM chains via [Account Abstraction](https://www.alchemy.com/blog/account-abstraction). + C --> C1[🔄 Native ERC-4337 APIs] + C1 --> C2[Direct Rundler Components Access] -### Goals + D --> D1[🔐 Enterprise Middleware] + D1 --> D2[Authentication & Authorization] + D2 --> D3[Rate Limiting & Policy Check] + D3 --> D4{Request Type Analysis} -Rundler is meant to power the ERC-4337 ecosystem with an implementation that users can rely on to scale to their needs while maintaining high reliability. As ERC-4337 is a nascent technology, Rundler strives to be on the bleeding edge of feature support and the team will be contributing to push the protocol forward. + D4 -->|pm_* methods| E[PaymasterService Processing] + D4 -->|eth_* methods| F[Direct Rundler Routing] -Our goals with Rundler: + E --> E1[Gas Sponsorship Logic] + E1 --> E2[Signature Generation] + E2 --> E3[Submit to Shared Rundler Components] -1. **ERC-4337 Specification Compliance**: Rundler strives to implement the full ERC-4337 specification and to maintain support as the specification changes and new onchain components are released. This includes new Entry Point contract support, support for the upcoming P2P mempool specification, support for alternative mempools, and more. -2. **High Performance and Reliability**: Rundler strives to power the most demanding workloads in cloud environments. Rust was chosen for its high performance and memory safety. Rundler's modular architecture lets providers choose to run the stateless components (RPC, builder) in a fully horizontally scalable manner connecting to the stateful components (mempool, p2p, event cache) via the network. Rundler's bundle builder is designed to be able to support the full gas throughput of the network it's building for. -3. **Extendability/Chain Support**: ERC-4337 is designed to support any EVM chain. However, different EVM supporting networks have different rules around how they support things like gas usage, gas fees, precompiles, etc. Rundler is designed to be extendable and easily adapted to support any EVM chain. -4. **Modularity**: Rundler is written in a modular manner, allowing its components to be run as a single integrated binary, or as a distributed system. Rundler also strives for its individual crates to be used to support future ERC-4337 tooling. + F --> F1[EthApi/RundlerApi/DebugApi] -## Status + subgraph SHARED["🔧 Shared Rundler Components (Arc)"] + G[Provider - Ethereum Connection] + H[Pool - Memory Pool Management] + I[Builder - Transaction Building] + J[Sender - Blockchain Submission] + G --> H + H --> I + I --> J + end -Rundler is under active development. It is used in Alchemy's cloud to power Alchemy's Account Abstraction APIs. However, Rundler is rapidly being upgraded, features are being added, interfaces will have breaking changes, and the ERC-4337 spec is evolving from onchain learnings. + C2 --> SHARED + E3 --> SHARED + F1 --> SHARED -The documentation is work in progress, and we are working to improve it. Please [reach out](#help) with any questions. + J --> K[🌐 Ethereum Network] + K --> L[EntryPoint Contract Execution] -**Use in production at your own risk.** + L --> M[Transaction Confirmation] + M --> N[Response Generation] -### ERC-4337 Entry Point Version Support + N --> O{Response Routing} + O -->|Legacy Path| P[JSON-RPC Response :3001] + O -->|Enterprise Path| Q[JSON-RPC Response :3000] -Rundler currently supports the following Entry Point versions: - * [v0.6.0](https://github.com/eth-infinitism/account-abstraction/tree/v0.6.0) - * [v0.7.0](https://github.com/eth-infinitism/account-abstraction/tree/v0.7.0) + P --> A + Q --> A -See more on Entry Point support [here](docs/architecture/entry_point.md). + style D fill:#e1f5fe + style E fill:#e8f5e8 + style SHARED fill:#fff3e0 + style K fill:#f3e5f5 + style C fill:#fce4ec +``` + +**核心架构特点**: +- **双服务兼容**: Legacy客户端使用`:3001`原生rundler服务，Enterprise客户端使用`:3000`网关服务 +- **组件共享**: 两个服务共享相同的rundler核心组件实例，避免资源重复 +- **正确流程**: PaymasterService签名后将UserOperation提交给共享的rundler组件处理 +- **零侵入**: Rundler原生服务完全保持不变，100%向后兼容 +- **企业增强**: Gateway服务提供认证、限流、策略、监控等企业级功能 + +## 🏗️ Zero-Invasion Architecture Design + +**Core Principle**: Implement feature extensions through external wrapper gateway, rundler core code remains completely unchanged -### Chain Support +### High-Level Architecture +``` +SuperRelay API Gateway (Port 3000) + ├── 🔐 Authentication & Authorization Module (JWT/API Key) + ├── 🚦 Rate Limiting Module (Memory/Redis) + ├── 📋 Policy Execution Module (TOML Configuration) + └── 🎯 Smart Router + ├── PaymasterService → Internal Method Calls → Gas Sponsorship Logic + ├── EthApi → Internal Method Calls → Standard ERC-4337 Methods + ├── RundlerApi → Internal Method Calls → Rundler-specific Methods + ├── DebugApi → Internal Method Calls → Debug Interfaces + └── 📊 Monitoring System → Reuse Existing Rundler Metrics + ↓ + 🌐 Ethereum Network (EntryPoint Contract) +``` + +### Detailed Component Architecture + +```mermaid +graph TB + subgraph CLIENT["🖥️ Client Layer"] + C1[DApp/Wallet] + C2[SDK/Libraries] + C3[CLI Tools] + end + + subgraph GATEWAY["🌐 SuperRelay Gateway (Port 3000)"] + subgraph MIDDLEWARE["🛡️ Middleware Stack"] + MW1[CORS Handler] + MW2[Request Logger] + MW3[Rate Limiter] + MW4[Auth Validator] + end + + subgraph ROUTER["🎯 Smart Router"] + R1[Method Parser] + R2[Route Dispatcher] + R3[Response Builder] + end + + subgraph SERVICES["🔧 Service Layer"] + subgraph PAYMASTER["💳 PaymasterRelay Service"] + PM1[Policy Engine] + PM2[Signer Manager] + PM3[KMS Integration] + PM4[Validation Module] + end + + subgraph GATEWAY_MODULES["📦 Gateway Modules"] + GM1[Health Checker] + GM2[E2E Validator] + GM3[Security Checker] + GM4[Authorization Checker] + GM5[Data Integrity Checker] + end + end + end + + subgraph RUNDLER["⚙️ Rundler Core (Shared Components)"] + subgraph PROVIDER["🔌 Provider Layer"] + P1[Alloy Provider] + P2[EVM Provider] + P3[DA Gas Oracle] + P4[Fee Estimator] + end + + subgraph POOL["🏊 Pool Management"] + PL1[LocalPoolBuilder] + PL2[PoolHandle] + PL3[Mempool Storage] + PL4[Operation Validator] + end + + subgraph BUILDER["🏗️ Builder Service"] + B1[Bundle Builder] + B2[Transaction Sender] + B3[Nonce Manager] + end + + subgraph RPC["🔄 RPC Service (Port 3001)"] + RPC1[EthApi] + RPC2[RundlerApi] + RPC3[DebugApi] + RPC4[AdminApi] + end + end + + subgraph BLOCKCHAIN["⛓️ Blockchain Layer"] + BC1[Ethereum Network] + BC2[EntryPoint Contract] + BC3[Paymaster Contract] + BC4[Account Contracts] + end + + %% Client connections + C1 --> MW1 + C2 --> MW1 + C3 --> MW1 + + %% Middleware flow + MW1 --> MW2 + MW2 --> MW3 + MW3 --> MW4 + MW4 --> R1 + + %% Router dispatching + R1 --> R2 + R2 -->|pm_* methods| PM1 + R2 -->|eth_* methods| RPC1 + R2 -->|rundler_* methods| RPC2 + R2 -->|debug_* methods| RPC3 + R2 -->|health checks| GM1 + + %% PaymasterService flow + PM1 --> PM2 + PM2 --> PM3 + PM3 --> PM4 + PM4 --> PL2 + + %% Health and validation + GM1 --> GM2 + GM2 --> GM3 + GM3 --> GM4 + GM4 --> GM5 + + %% Rundler components interaction + RPC1 --> P1 + RPC2 --> PL2 + RPC3 --> B1 + + P1 --> P2 + P2 --> P3 + P3 --> P4 + + PL2 --> PL3 + PL3 --> PL4 + PL4 --> B1 + + B1 --> B2 + B2 --> B3 + B3 --> BC1 + + %% Blockchain interaction + BC1 --> BC2 + BC2 --> BC3 + BC2 --> BC4 + + %% Response flow + BC2 --> R3 + R3 --> C1 + + style GATEWAY fill:#e1f5fe + style PAYMASTER fill:#e8f5e8 + style RUNDLER fill:#fff3e0 + style BLOCKCHAIN fill:#f3e5f5 +``` -Rundler has been tested on the following networks and their testnets: +### Component Dependency Matrix + +| Component | Dependencies | Communication Protocol | Purpose | +|-----------|-------------|----------------------|----------| +| **Gateway Layer** | | | | +| PaymasterGateway | GatewayRouter, PaymasterRelayService | Internal Method Calls | Main gateway orchestrator | +| GatewayRouter | EthApi, RundlerApi, DebugApi | Direct Function Calls | Request routing and dispatching | +| Middleware Stack | Tower-HTTP, Axum | HTTP/JSON-RPC | Request preprocessing | +| **PaymasterRelay** | | | | +| PaymasterRelayService | SignerManager, PolicyEngine, LocalPoolHandle | Arc Shared State | Gas sponsorship service | +| SignerManager | KMS Module, Alloy Signer | Async Traits | Key management and signing | +| PolicyEngine | TOML Config, Validation Module | File I/O | Policy enforcement | +| **Rundler Core** | | | | +| LocalPoolHandle | Provider, Mempool | Arc> | Operation pool management | +| AlloyProvider | Alloy Libraries | HTTP/WebSocket | Blockchain connectivity | +| EVM Provider | AlloyProvider, ChainSpec | Internal Structs | EVM-specific operations | +| Builder Service | Pool, Provider, Signer | Message Passing | Bundle building and submission | +| **Monitoring** | | | | +| Health System | All Components | Status Checks | System health monitoring | +| Metrics Collector | Prometheus | HTTP Metrics Export | Performance monitoring | + +### Data Flow and Component Interactions + +```mermaid +sequenceDiagram + participant Client + participant Gateway as SuperRelay Gateway + participant MW as Middleware Stack + participant Router + participant PM as PaymasterService + participant Pool as Pool Handle + participant Provider + participant Blockchain + + %% Standard UserOperation submission with Paymaster + Client->>Gateway: POST /pm_sponsorUserOperation + Gateway->>MW: CORS + Auth + Rate Limit + MW->>Router: Route to PaymasterService + + Router->>PM: Process sponsorship request + PM->>PM: Check policies + PM->>PM: Generate signature + PM->>Pool: Submit to mempool + + Pool->>Provider: Validate operation + Provider->>Blockchain: Simulate transaction + Blockchain-->>Provider: Validation result + Provider-->>Pool: Return status + + Pool-->>PM: Operation added + PM-->>Router: Return paymasterAndData + Router-->>Client: JSON-RPC Response + + %% Bundle building and submission + Note over Pool,Provider: Periodic bundle building + Pool->>Pool: Collect operations + Pool->>Provider: Build bundle + Provider->>Blockchain: Submit bundle + Blockchain-->>Provider: Transaction hash + Provider-->>Pool: Update status +``` -* Ethereum -* OP Stack - * Generally any OP stack chain should work. - * Rundler has been explicitly tested on Optimism, Base, Zora, and Frax. -* Arbitrum Orbit - * Generally any Arbitrum Orbit chain should work. - * Rundler has been explicitly tested on Arbitrum One. -* Polygon POS +### Module Hierarchy and Workspace Structure -## Developers +``` +super-relay/ +├── bin/ # Binary crates +│ ├── super-relay/ # Main gateway binary +│ │ └── src/ +│ │ └── main.rs # Entry point with dual-service mode +│ ├── rundler/ # Original rundler binary +│ ├── dashboard/ # Monitoring dashboard +│ └── integration-tests/ # E2E test suite +│ +├── crates/ # Library crates +│ ├── gateway/ # Gateway core functionality +│ │ ├── src/ +│ │ │ ├── lib.rs # Public API exports +│ │ │ ├── gateway.rs # PaymasterGateway implementation +│ │ │ ├── router.rs # Request routing logic +│ │ │ ├── middleware.rs # HTTP middleware stack +│ │ │ ├── health.rs # Health check endpoints +│ │ │ ├── security.rs # Security validation +│ │ │ ├── authorization.rs # Auth & permissions +│ │ │ ├── validation.rs # Data integrity checks +│ │ │ └── e2e_validator.rs # End-to-end validation +│ │ └── Cargo.toml +│ │ +│ ├── paymaster-relay/ # Paymaster service +│ │ ├── src/ +│ │ │ ├── lib.rs +│ │ │ ├── service.rs # PaymasterRelayService +│ │ │ ├── signer.rs # SignerManager +│ │ │ ├── policy.rs # PolicyEngine +│ │ │ ├── kms.rs # KMS integration +│ │ │ ├── validation.rs # Operation validation +│ │ │ ├── rpc.rs # RPC handlers +│ │ │ └── swagger.rs # API documentation +│ │ └── Cargo.toml +│ │ +│ ├── pool/ # Mempool management +│ ├── builder/ # Bundle building +│ ├── provider/ # Blockchain providers +│ ├── rpc/ # RPC service implementations +│ ├── sim/ # Simulation engine +│ ├── signer/ # Transaction signing +│ ├── types/ # Common types +│ └── utils/ # Utility functions +│ +├── config/ # Configuration files +│ ├── config.toml # Main configuration +│ └── paymaster-policies.toml # Paymaster policies +│ +├── scripts/ # Automation scripts +│ ├── start_superrelay.sh # Start all services +│ ├── test_integration.sh # Run integration tests +│ └── format.sh # Code formatting +│ +└── Cargo.toml # Workspace configuration +``` -### Contributing +### Component Communication Patterns + +```mermaid +graph LR + subgraph "Synchronous Communication" + A1[Direct Function Calls] + A2[Trait Method Invocations] + A3[Arc Shared State Access] + end + + subgraph "Asynchronous Communication" + B1[Tokio Channels] + B2[Future Chaining] + B3[Event Notifications] + end + + subgraph "External Communication" + C1[JSON-RPC over HTTP] + C2[WebSocket Connections] + C3[gRPC Streams] + end + + A1 --> |Gateway→Router| D[Internal Routing] + A2 --> |Service→Pool| E[Component Integration] + A3 --> |Shared Components| F[State Management] + + B1 --> |Pool→Builder| G[Task Coordination] + B2 --> |Async Operations| H[Non-blocking I/O] + B3 --> |Status Updates| I[Event Handling] + + C1 --> |Client→Gateway| J[API Requests] + C2 --> |Provider→Blockchain| K[Real-time Updates] + C3 --> |Monitoring→Metrics| L[Telemetry] +``` -See [CONTRIBUTING.md](CONTRIBUTING.md). +[![Rust](https://img.shields.io/badge/Rust-1.70%2B-orange)](https://www.rust-lang.org) +[![License](https://img.shields.io/badge/License-Apache%202.0-blue)](LICENSE) +[![Status](https://img.shields.io/badge/Status-Production%20Ready-green)](https://github.com/AAStarCommunity/SuperRelay) -### Running +## 🚀 Quick Start -The easiest way to run Rundler is via a docker container. There is currently no pre-built image. See our [docker documentation](docs/docker.md) for further instructions. +SuperRelay 提供**双协议分离架构**，您可以根据需要独立启动不同的服务： -### Developing +### 🌐 双协议架构说明 +- **JSON-RPC 服务** (端口 3000) - 为区块链工具 (web3.js, ethers.js) 和 DApp 提供标准接口 +- **HTTP REST API** (端口 9000) - 为 Web/Mobile 应用提供 REST 接口 + 交互式 Swagger UI -For detailed instructions see [developing](docs/developing.md). +### 启动选项 -Install [prerequisites](docs/developing.md#setup). +#### 选项1：启动 JSON-RPC 服务 (推荐用于区块链开发) +```bash +# 克隆项目 +git clone https://github.com/AAStarCommunity/SuperRelay.git +cd SuperRelay -Clone the repository and checkout submodules: +# 启动传统的 JSON-RPC 服务，兼容所有 ERC-4337 工具 +./scripts/start_superrelay.sh +# 🌐 服务地址: http://localhost:3000 +# 🧪 测试: curl -X POST http://localhost:3000 -d '{"jsonrpc":"2.0","method":"pm_sponsorUserOperation","params":[...],"id":1}' ``` -git clone https://github.com/alchemyplatform/rundler -cd rundler -git submodule update --init --recursive + +#### 选项2：启动 HTTP REST API + Swagger UI (推荐用于 API 测试) +```bash +# 启动 HTTP REST API 服务器和交互式文档 +./scripts/start_api_server.sh +# 🌐 Swagger UI: http://localhost:9000/swagger-ui/ +# 🏥 健康检查: http://localhost:9000/health +# 🧪 测试: curl -X POST http://localhost:9000/api/v1/sponsor -d '{"user_op":{},"entry_point":"0x..."}' ``` -Run unit tests: +#### 选项3：双服务模式 (完整功能) +```bash +# 同时启动两种协议服务 (JSON-RPC + REST API) +./target/debug/super-relay dual-service --enable-paymaster +# 🔄 JSON-RPC: http://localhost:3000 +# 🌐 REST API: http://localhost:9000/swagger-ui/ ``` -make test-unit + +### 1. 快速开发环境设置 + +### 2. Test API Functionality + +```bash +# Health check +curl http://localhost:3000/health + +# Test PaymasterRelay API +curl -X POST http://localhost:3000 \ + -H "Content-Type: application/json" \ + -d '{ + "jsonrpc": "2.0", + "id": 1, + "method": "pm_sponsorUserOperation", + "params": [ + { + "sender": "0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266", + "nonce": "0x0", + "callData": "0x", + "callGasLimit": "0x186A0", + "verificationGasLimit": "0x186A0", + "preVerificationGas": "0x5208", + "maxFeePerGas": "0x3B9ACA00", + "maxPriorityFeePerGas": "0x3B9ACA00" + }, + "0x5FF137D4b0FDCD49DcA30c7CF57E578a026d2789" + ] + }' + +# Test standard ERC-4337 API +curl -X POST http://localhost:3000 \ + -H "Content-Type: application/json" \ + -d '{ + "jsonrpc": "2.0", + "id": 1, + "method": "eth_supportedEntryPoints", + "params": [] + }' ``` -Run ERC-4337 spec tests: +### 3. 访问接口文档 (推荐) + +```bash +# 方式1：使用新的 utoipa 自动生成的 Swagger UI (推荐) +./scripts/start_api_server.sh +# 🌐 访问: http://localhost:9000/swagger-ui/ +# ✨ 特性: 自动生成、实时更新、可交互测试 + +# 方式2：使用遗留的独立 Web UI (备选) +./scripts/start_web_ui.sh +# 📱 访问: http://localhost:9000/ +# 📋 说明: 静态文档，需要手动维护 ``` -# Only need to run once to install testing frameworks -cd test/spec-tests/v0_6/bundler-spec-tests && pdm install && pdm run update-deps -cd test/spec-tests/v0_7/bundler-spec-tests && pdm install && pdm run update-deps -# Run the v0.6 and v0.7 tests -make test-spec-integrated +**推荐使用方式1** - utoipa自动生成的文档始终与代码同步，支持实时API测试。 + +### 4. Verify Gateway Functionality + +```bash +# Check gateway status +curl http://localhost:3000/health | jq + +# View Prometheus metrics +curl http://localhost:3000/metrics + +# Run complete test suite +./scripts/test_integration.sh ``` -### Help +## 📊 Service Port Description + +| Service | Port | Description | +|---------|------|------------| +| **JSON-RPC API** | 3000 | 主要的 ERC-4337 bundler 服务 (区块链工具使用) | +| **HTTP REST API** | 9000 | REST 接口 + utoipa 自动生成 Swagger UI | +| 遗留 Web UI | 9000 | 独立的静态文档部署 (可选) | +| Anvil (Development) | 8545 | 本地以太坊测试网络 | +| Prometheus Metrics | 3000/metrics | 监控指标端点 | + +### 🔗 访问地址 +- **Swagger UI (推荐)**: http://localhost:9000/swagger-ui/ +- **JSON-RPC 端点**: http://localhost:3000 +- **健康检查**: http://localhost:9000/health 或 http://localhost:3000/health +- **OpenAPI 规范**: http://localhost:9000/api-doc/openapi.json + +## 🎯 Core Features + +✅ **Zero-Invasion Architecture** - Rundler core code completely unchanged +✅ **Single Binary Deployment** - Simplified operations, reduced complexity +✅ **Internal Routing** - High-performance internal method calls +✅ **Enterprise Features** - Authentication, rate limiting, policies, monitoring +✅ **Independent Web UI** - Frontend/backend separation, technology stack freedom +✅ **Complete ERC-4337 Support** - v0.6/v0.7 format compatibility -If you have questions regarding the Rundler codebase, please first look through our [documentation](./docs/). +## 🚀 SDK Integration Guide -With further questions: +SuperRelay provides enterprise-grade Account Abstraction services with simple SDK integration for DApps and wallets. -* [Github discussions](https://github.com/alchemyplatform/rundler/discussions) -* [Telegram][tg_link] -* [Github issues](https://github.com/alchemyplatform/rundler/issues/new/choose) +### Node.js Quick Integration -If you have questions regarding Alchemy's APIs or service, kindly refrain from discussion here. Please join the [Discord](https://discord.com/invite/alchemyplatform) or reach out to support@alchemy.com. +```bash +# Install dependencies +npm install ethers axios -### Security +# Basic setup +git clone https://github.com/AAStarCommunity/SuperRelay.git +cd SuperRelay && ./scripts/start_superrelay.sh +``` + +```javascript +// Simple UserOperation sponsorship +const { ethers } = require('ethers'); +const axios = require('axios'); + +const client = { + SUPER_RELAY_URL: 'http://localhost:3000', + ENTRY_POINT: '0x5FbDB2315678afecb367f032d93F642f64180aa3' +}; + +// Sponsor a UserOperation +async function sponsorUserOp(userOp) { + const response = await axios.post(client.SUPER_RELAY_URL, { + jsonrpc: "2.0", + id: 1, + method: "pm_sponsorUserOperation", + params: [userOp, client.ENTRY_POINT] + }); + return response.data.result; // Returns paymasterAndData +} +``` + +### Key Integration Features -For security concerns do not file a public ticket, please reach out to security@alchemy.com. +- **🎯 Gas Sponsorship**: `pm_sponsorUserOperation` API for seamless gas abstraction +- **⚡ ERC-4337 Compatible**: Full support for standard UserOperation flow +- **🔧 Multiple Networks**: Works with Anvil, Sepolia, Mainnet +- **📊 Enterprise Ready**: Built-in rate limiting, auth, and monitoring -See [SECURITY.md](SECURITY.md) for details. +### Developer Resources -## Acknowledgements +| Resource | Description | Link | +|----------|-------------|------| +| **SDK Integration Guide** | Complete Node.js integration tutorial | [docs/SDK-Integration-Guide.md](docs/SDK-Integration-Guide.md) | +| **Demo Application** | Working demo with examples | [demo/](demo/) | +| **Scripts Collection** | Automated setup and testing tools | [scripts/](scripts/) | +| **Swagger UI** | Interactive API documentation | `http://localhost:9000/swagger-ui/` | + +### Quick Start Scripts + +```bash +# Complete development environment setup +./scripts/start_anvil.sh # Start test network +./scripts/deploy_entrypoint.sh # Deploy EntryPoint contract +./scripts/setup_test_accounts.sh # Configure test accounts +./scripts/start_superrelay.sh # Launch SuperRelay gateway + +# Run demo and tests +cd demo && npm install && npm run demo +./scripts/test_integration.sh # Comprehensive test suite +``` -The work on this project would not have been possible without the amazing contributions from: +**⚡ Ready in under 2 minutes** - Complete Account Abstraction infrastructure -- [ERC-4337 team](https://github.com/eth-infinitism/account-abstraction): The ERC-4337 team has pioneered the standard, and has answered countless questions during our development. They developed the [bundler reference implementation](https://github.com/eth-infinitism/bundler) and [spec tests](https://github.com/eth-infinitism/bundler-spec-tests) that were invaluable during our development process. We are excited to continue to work with this team to push ERC-4337 ahead. -- [Reth](https://github.com/paradigmxyz/reth): Shout-out to the Reth team, from which we've taken inspiration for many of our practices in this repo (including this README). They are pushing the Ethereum Rust ecosystem forward in an open way. We thank the Reth team for their continued contributions. +## 📚 Documentation Navigation -[eip_link]: https://eips.ethereum.org/EIPS/eip-4337 +### 👩‍💻 **Developers** +- **[SDK Integration Guide](docs/SDK-Integration-Guide.md)** - Complete Node.js SDK integration tutorial +- **[Technical Architecture Analysis](docs/Architecture-Analysis.md)** - Deep dive into system design & Rundler integration +- **[API Interface Documentation](docs/API-Analysis.md)** - Complete REST API and Swagger UI guide +- **[Testing Guide](docs/Testing-Analysis.md)** - Unit testing, integration testing full coverage + +### 🏗️ **Architects** +- **[Solution Design](docs/Solution.md)** - Business requirements & technical solutions +- **[Comprehensive Review Report](docs/Comprehensive-Review.md)** - Overall project scoring and competitiveness analysis + +### 🚀 **DevOps Engineers** +- **[Deployment Guide](docs/Deploy.md)** - Production environment deployment and configuration +- **[Installation Documentation](docs/Install.md)** - User installation and update guide +- **[Version Changes](docs/Changes.md)** - Complete version history and changelog + +### 🧪 **Test Engineers** +- **[Testing Summary](docs/Testing-Summary.md)** - Test coverage and result statistics +- **[User Scenario Testing](docs/UserCaseTest.md)** - End-to-end user scenario validation + +### 🛠️ **Essential Scripts Reference** + +| Script | Purpose | Command | +|--------|---------|---------| +| **Environment Setup** | Complete dev environment | `./scripts/start_anvil.sh && ./scripts/deploy_entrypoint.sh` | +| **Service Launch** | Start SuperRelay services | `./scripts/start_superrelay.sh` | +| **API Testing** | Test Swagger API endpoints | `./scripts/test_swagger_api.sh` | +| **Integration Tests** | Full test suite execution | `./scripts/test_integration.sh` | +| **Production Deploy** | Production environment setup | `./scripts/start_production.sh` | +| **Code Formatting** | Rust code formatting | `./scripts/format.sh` | + +### 📦 **Demo Applications** + +- **[Node.js Demo](demo/)** - SuperPaymaster SDK usage examples +- **[Package Configuration](demo/package.json)** - NPM dependencies and scripts +- **[Demo Script](demo/superPaymasterDemo.js)** - Complete working example + +## 🛠️ Installation Requirements + +- **Rust** 1.70+ +- **Foundry** (Anvil) +- **jq** (for script processing) + +## 📄 License + +This project is licensed under [GNU Lesser General Public License v3.0](LICENSE). + +## 🆘 Support & Community + +- **[GitHub Issues](https://github.com/AAStarCommunity/SuperRelay/issues)** - Issue reports and feature requests +- **[Documentation Website](https://docs.aastar.io/)** - Complete documentation and tutorials + +--- + +# 中文版本 + +AAStar 的 SuperPaymaster 包括了 SuperRelay 和 SuperPaymaster 合约。SuperRelay 是一个基于 Rundler (Alchemy 的 ERC-4337 bundler) 的企业级 API 网关，通过零侵入架构为 ERC-4337 生态提供 gas 赞助 + 认证授权 + 企业策略 + 监控告警功能。 + +## 🚀 快速体验 + +```bash +# 1. 克隆项目 +git clone https://github.com/AAStarCommunity/SuperRelay.git && cd SuperRelay + +# 2. 一键启动 +./scripts/start_superrelay.sh + +# 3. 验证服务 (新终端) +curl http://localhost:3000/health +``` + +🎉 **SuperRelay 启动成功！** +- 🌐 Swagger UI: http://localhost:9000/ +- 📊 API 端点：http://localhost:3000 +- 📈 监控面板：http://localhost:3000/metrics + +## 🧪 测试与验证 + +### 快速测试步骤 + +```bash +# 健康检查 +curl http://localhost:3000/health + +# 测试 Paymaster 赞助功能 +curl -X POST http://localhost:3000 \ + -H "Content-Type: application/json" \ + -d '{ + "jsonrpc": "2.0", + "id": 1, + "method": "pm_sponsorUserOperation", + "params": [ + { + "sender": "0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266", + "nonce": "0x0", + "callData": "0x", + "callGasLimit": "0x186A0", + "verificationGasLimit": "0x186A0", + "preVerificationGas": "0x5208", + "maxFeePerGas": "0x3B9ACA00", + "maxPriorityFeePerGas": "0x3B9ACA00" + }, + "0x5FF137D4b0FDCD49DcA30c7CF57E578a026d2789" + ] + }' + +# 测试标准 ERC-4337 API +curl -X POST http://localhost:3000 \ + -H "Content-Type: application/json" \ + -d '{ + "jsonrpc": "2.0", + "id": 1, + "method": "eth_supportedEntryPoints", + "params": [] + }' + +# 运行完整测试套件 +./scripts/test_integration.sh +``` + +## 📊 性能表现 + +**关键指标**: +- 🚀 **TPS**: 25+ 事务/秒 +- ⚡ **响应时间**: <200ms (API 调用) +- 🎯 **成功率**: >99.9% (生产环境) +- 📦 **内存使用**: <100MB (典型运行) +- 🔄 **启动时间**: <30 秒 (完整服务) + +## 🔧 故障排除 + +### 常见问题 + +**Q: 启动时提示 "Private key configuration required"** +```bash +# 检查环境文件 +cat .env +# 重新生成配置 +cp .env.dev .env && source .env +``` + +**Q: Anvil 连接失败** +```bash +# 检查 Anvil 是否运行 +ps aux | grep anvil +# 手动启动 Anvil +anvil --host 0.0.0.0 --port 8545 --chain-id 31337 +``` -## License +### 获取帮助 +- 📖 [完整文档](docs/) - 详细的技术文档 +- 🐛 [Issue 反馈](https://github.com/AAStarCommunity/SuperRelay/issues) -The Rundler library (i.e. all code outside of the `bin` directory) is licensed under the GNU Lesser General Public License v3.0, also included in our repository in the COPYING.LESSER file. +--- -The Rundler binaries (i.e. all code inside of the `bin` directory) are licensed under the GNU General Public License v3.0, also included in our repository in the COPYING file. +
-The Rundler library and binaries are licensed under Unicode License v3.0, also included in the UNICODE file. +**⭐ 如果这个项目对你有帮助，请给我们一个星标！** -Copyright 2023 Alchemy Insights, Inc. +*Made with ❤️ by [AAStar Community](https://github.com/AAStarCommunity)* -Contact: Alchemy Insights, Inc., 548 Market St., PMB 49099, San Francisco, CA 94104; legal@alchemy.com +
\ No newline at end of file From c79b01f088a04116abe941cd100587b4f246fdb4 Mon Sep 17 00:00:00 2001 From: jhfnetboy Date: Tue, 28 Apr 2026 20:28:38 +0700 Subject: [PATCH 3/5] docs: standardize License section (Apache 2.0, fix LGPL error) --- README.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 206be916d..67b068a74 100644 --- a/README.md +++ b/README.md @@ -651,7 +651,8 @@ cd demo && npm install && npm run demo ## 📄 License -This project is licensed under [GNU Lesser General Public License v3.0](LICENSE). +This project is licensed under the [Apache License, Version 2.0](LICENSE). +Copyright 2024-present MushroomDAO Contributors. See [NOTICE](./NOTICE) for attribution. ## 🆘 Support & Community @@ -767,4 +768,4 @@ anvil --host 0.0.0.0 --port 8545 --chain-id 31337 *Made with ❤️ by [AAStar Community](https://github.com/AAStarCommunity)* - \ No newline at end of file + From 1afb18b3a97cfdddfb2fdde9dc362ef0ef42f4ce Mon Sep 17 00:00:00 2001 From: jhfnetboy Date: Wed, 29 Apr 2026 09:00:38 +0700 Subject: [PATCH 4/5] docs: add all 5 license file links to README --- README.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 67b068a74..c044861ca 100644 --- a/README.md +++ b/README.md @@ -649,10 +649,11 @@ cd demo && npm install && npm run demo - **Foundry** (Anvil) - **jq** (for script processing) -## 📄 License +## License This project is licensed under the [Apache License, Version 2.0](LICENSE). -Copyright 2024-present MushroomDAO Contributors. See [NOTICE](./NOTICE) for attribution. +Copyright 2024-present MushroomDAO Contributors. +See [NOTICE](./NOTICE) · [TRADEMARK.md](./TRADEMARK.md) · [LICENSE-zh.md](./LICENSE-zh.md) · [TRADEMARK-zh.md](./TRADEMARK-zh.md) for details. ## 🆘 Support & Community From adec3ca6fc6c69b9cf8fabdb79f6b3f273e33e52 Mon Sep 17 00:00:00 2001 From: jhfnetboy Date: Wed, 29 Apr 2026 09:54:35 +0700 Subject: [PATCH 5/5] chore: add CONTRIBUTING guide and CLA assistant workflow --- .github/workflows/cla.yml | 39 +++++++++++++ CONTRIBUTING.md | 116 ++++++++------------------------------ 2 files changed, 64 insertions(+), 91 deletions(-) create mode 100644 .github/workflows/cla.yml diff --git a/.github/workflows/cla.yml b/.github/workflows/cla.yml new file mode 100644 index 000000000..dc2b7ff86 --- /dev/null +++ b/.github/workflows/cla.yml @@ -0,0 +1,39 @@ +# CLA Assistant GitHub Action +# Copy this file to: .github/workflows/cla.yml in each repo +# +# Prerequisites: +# 1. Go to repo Settings → Secrets → add secret named CLA_TOKEN +# (a Personal Access Token with repo scope from an org admin account) +# 2. The CLA text lives at: +# https://github.com/AAStarCommunity/Brood/blob/main/protocol/CLA.md + +name: CLA Assistant + +on: + issue_comment: + types: [created] + pull_request_target: + types: [opened, closed, synchronize] + +permissions: + actions: write + contents: write + pull-requests: write + statuses: write + +jobs: + cla-check: + runs-on: ubuntu-latest + steps: + - name: CLA Assistant + uses: contributor-assistant/github-action@v2.6.1 + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + PERSONAL_ACCESS_TOKEN: ${{ secrets.CLA_TOKEN }} + with: + path-to-signatures: 'signatures/cla.json' + path-to-document: 'https://github.com/AAStarCommunity/Brood/blob/main/protocol/CLA.md' + branch: 'cla-signatures' + allowlist: bot*,dependabot[bot],github-actions[bot] + remote-organization-name: AAStarCommunity + remote-repository-name: Brood diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 7762bdbd3..8ed062ed8 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,109 +1,43 @@ -## Contributing to Rundler +# Contributing Guide -Thanks for your interest in improving Rundler! +> Part of [Mycelium Protocol](https://github.com/AAStarCommunity/Brood) ecosystem. +> Full contribution guide & CLA text: [protocol/CONTRIBUTING.md](https://github.com/AAStarCommunity/Brood/blob/main/protocol/CONTRIBUTING.md) -There are multiple opportunities to contribute at any level. It doesn't matter if you are just getting started with Rust or are an expert, we can use your help. +--- -**No contribution is too small and all contributions are valued.** +## Apache 2.0 — 2 分钟白话版 -This document will help you get started. **Do not let the document intimidate you**. -It should be considered as a guide to help you navigate the process. +本项目使用 Apache License 2.0，对所有人开放： -The [Telegram][dev-tg] is available for any concerns you may have that are not covered in this guide. +**可以做**：免费用、商业用、修改、集成进闭源产品、分发 +**必须做**：保留版权行 · 保留 NOTICE 文件 · 修改文件须注明 · 不能蹭品牌（见 TRADEMARK.md） +**不要求**：改了代码不用开源（这是和 GPL 最大的区别） -If you contribute to this project, your contributions will be made to the project as follows: (a) contributions to the Rundler library (i.e. all code outside of the `bin` directory) will be licensed under the GNU Lesser General Public License v3.0, also included in our repository in the COPYING.LESSER file; and (b) contributions to the Rundler binaries (i.e. all code inside of the `bin` directory) will be licensed under the GNU General Public License v3.0, also included in our repository in the COPYING file. +--- -### Ways to contribute +## 签署 CLA -There are fundamentally three ways an individual can contribute: +本项目要求所有贡献者签署 **CLA（贡献者许可协议）**，以确保项目对所有贡献代码有清晰的法律授权。 -1. **By opening an issue:** For example, if you believe that you have uncovered a bug - in Rundler, creating a new issue in the [issue tracker][gh-issues] is the way to report it. -2. **By adding context:** Providing additional context to existing issues, - such as screenshots and code snippets to help resolve issues. -3. **By resolving issues:** Typically this is done in the form of either - demonstrating that the issue reported is not a problem after all, or more often, - by opening a pull request that fixes the underlying problem, in a concrete and - reviewable manner. +> **CLA 是什么**：你签一次的声明："我提交的代码是我的原创（或我有权提交），授权本项目在 Apache 2.0 下使用。" +> **为什么需要**：没有明确授权，项目分发你的代码存在法律漏洞。 +> **怎么签**：提交 PR 后，`@cla-assistant` 机器人自动评论并引导你签名，只需 1 分钟，永久有效，只签一次。 -**Anybody can participate in any stage of contribution**. We urge you to participate in the discussion around bugs and participate in reviewing PRs. +完整 CLA 协议文本：[CLA.md](https://github.com/AAStarCommunity/Brood/blob/main/protocol/CLA.md) | [中文参考译本](https://github.com/AAStarCommunity/Brood/blob/main/protocol/CLA-zh.md) -### Submitting a bug report +--- -When filing a new bug report in the [issue tracker][gh-issues], you will be presented with a basic form to fill out. +## 贡献流程 -If you believe that you have uncovered a bug, please fill out the form to the best of your ability. Do not worry if you cannot answer every detail, just fill in what you can. Contributors will ask follow-up questions if something is unclear. - -The most important pieces of information we need in a bug report are: - -- The Rundler version you are on (and that it is up to date) -- The platform you are on (Windows, macOS, an M1 Mac or Linux) -- Code snippets if this is happening in relation to testing or building code -- Concrete steps to reproduce the bug - -In order to rule out the possibility of the bug being in your project, the code snippets should be as minimal as possible. It is better if you can reproduce the bug with a small snippet as opposed to an entire project! - -### Submitting a feature request - -When adding a feature request in the issue tracker, you will be presented with a basic form to fill out. - -Please include as detailed of an explanation as possible of the feature you would like, adding additional context if necessary. - -If you have examples of other tools that have the feature you are requesting, please include them as well. - -### Resolving an issue - -Pull requests are the way concrete changes are made to the code, documentation, and dependencies of Rundler. - -Even tiny pull requests, like fixing wording, are greatly appreciated. Before making a large change, it is usually a good idea to first open an issue describing the change to solicit feedback and guidance. This will increase the likelihood of the PR getting merged. - -Please also make sure that the following commands pass if you have changed the code: - -```sh -cargo check --all -cargo test --all --all-features -cargo +nightly fmt -- --check -cargo +nightly clippy --all --all-features -- -D warnings -``` - -If you are working in VSCOde, we recommend you install the [rust-analyzer](https://marketplace.visualstudio.com/items?itemName=rust-lang.rust-analyzer) extension, and use the following VSCode user settings: ``` - "[rust]": { - "editor.defaultFormatter": "rust-lang.rust-analyzer", - "editor.formatOnSave": true - }, - "rust-analyzer.rustfmt.extraArgs": [ - "+nightly" - ], - "rust-analyzer.check.command": "clippy", - "rust-analyzer.files.excludeDirs": [ - "crates/sim/contracts", - "crates/sim/tracer", - "crates/builder/proto", - "crates/pool/proto", - "test", - ], +Fork → 新建分支 → 写代码 → 提交 PR → 签 CLA → Review → Merge ``` -If you are working on a larger feature, we encourage you to open up a draft pull request, to make sure that other contributors are not duplicating work. - -#### Adding tests - -If the change being proposed alters code, it is either adding new functionality to Rundler, or fixing existing, broken functionality. -In both of these cases, the pull request should include one or more tests to ensure that Rundler does not regress in the future. - -#### Commits - -It is a recommended best practice to keep your changes as logically grouped as possible within individual commits. There is no limit to the number of commits any single pull request may have, and many contributors find it easier to review changes that are split across multiple commits. -That said, if you have a number of commits that are "checkpoints" and don't represent a single logical change, please squash those together. - -We follow the [conventional commits](https://www.conventionalcommits.org/en/v1.0.0/) specification to make sure that all of our commits are formatted and properly tailored to the change that the commit is making. Please choose commit messages that correctly describe the change you are making. - -#### Opening the pull request - -From within GitHub, opening a new pull request will present you with a template that should be filled out. Please try your best at filling out the details, but feel free to skip parts if you're not sure what to put. +- 分支命名：`feat/xxx` · `fix/xxx` · `docs/xxx` +- Commit 规范：[Conventional Commits](https://www.conventionalcommits.org/) +- 问题反馈：在本仓库提 Issue -*Adapted from the [Reth contributing guide](https://github.com/paradigmxyz/reth/blob/main/CONTRIBUTING.md).* +## License -[dev-tg]: https://t.me/rundler -[gh-issues]: https://github.com/alchemyplatform/rundler/issues/new/choose +Contributions are licensed under [Apache License 2.0](LICENSE). +See [NOTICE](./NOTICE) · [TRADEMARK.md](./TRADEMARK.md) · [LICENSE-zh.md](./LICENSE-zh.md) · [TRADEMARK-zh.md](./TRADEMARK-zh.md) for details.