From 125a1c78933826000b692f6c0401ff51d810d908 Mon Sep 17 00:00:00 2001 From: geminilclaw Date: Sat, 21 Mar 2026 20:01:06 +0800 Subject: [PATCH 1/2] update readme --- .gitignore | 2 +- README.md | 64 +++++++++++++++++++++++++++--------------------------- 2 files changed, 33 insertions(+), 33 deletions(-) diff --git a/.gitignore b/.gitignore index e920ceb..ed6bd84 100644 --- a/.gitignore +++ b/.gitignore @@ -1,6 +1,6 @@ out/ cache/ broadcast/ -lib/ +# lib/ (Removed to allow submodules to be tracked) .env .env.* diff --git a/README.md b/README.md index dfbafd3..a00918e 100644 --- a/README.md +++ b/README.md @@ -1,57 +1,57 @@ # PayNode Smart Contracts -基于 Solidity 开发的非托管 M2M (Machine-to-Machine) 支付路由合约，旨在为 AI Agent 提供极低延迟、高可验证性的支付基础设施。 +Solidity-based non-custodial M2M (Machine-to-Machine) payment routing contracts, designed to provide ultra-low latency and high-verifiability payment infrastructure for AI Agents. -## 📜 许可证 (License) +## 📜 License **Business Source License 1.1 (BSL-1.1)** -- 允许所有非商业用途及特定条件下的商业用途。 -- 自发布起 2 年后自动转为 **GPL-3.0-or-later**。 +- Allows all non-commercial use and commercial use under specific conditions. +- Automatically transitions to **GPL-3.0-or-later** 2 years after publication. -## ⚡ Stateless 设计与 Gas 优势 +## ⚡ Stateless Design and Gas Advantages -`PayNodeRouter` 采用**无状态 (Stateless)** 架构设计，这是为了极致优化 M2M 场景下的 Gas 消耗： +`PayNodeRouter` adopts a **Stateless** architectural design, which is intended to optimize Gas consumption in M2M scenarios to the extreme: -1. **零存储 (No SSTORE):** 合约内部不维护 `orderId` 的结算状态。这意味着我们不需要在链上通过存储变量记录订单是否已付。 -2. **事件驱动 (Event-driven):** 所有的支付证明均通过 `PaymentReceived` 事件抛出。 - - `orderId` 被定义为 `indexed`，方便 SDK/后端通过 Bloom Filter 快速检索。 -3. **验证成本转移:** 支付的“真实性”由 SDK 侧与 RPC 交互验证。这使得单笔支付的 Gas 消耗仅为基本的转账操作 + 事件抛出（约 60k-80k Gas）。 -4. **Gas 比较:** 相比于传统的托管/订单管理合约（通常需 150k+ Gas），PayNode 在 Base L2 上的执行成本降低了 50% 以上。 +1. **Zero Storage (No SSTORE):** The contract does not maintain the settlement status of `orderId` internally. This means we do not need to record whether an order has been paid via storage variables on-chain. +2. **Event-driven:** All payment proofs are emitted through the `PaymentReceived` event. + - `orderId` is defined as `indexed`, facilitating fast retrieval by SDKs/backends using Bloom Filters. +3. **Verification Cost Transfer:** The "authenticity" of the payment is verified by the SDK side through interaction with the RPC. This keeps the Gas consumption of a single payment to basic transfer operations + event emission (approximately 60k-80k Gas). +4. **Gas Comparison:** Compared to traditional custodial/order management contracts (which typically require 150k+ Gas), PayNode's execution cost on Base L2 is reduced by more than 50%. -## 🔄 `pay()` 核心函数逻辑 +## 🔄 `pay()` Core Function Logic -`pay()` 函数是协议的主要入口点，执行流程如下： +The `pay()` function is the primary entry point of the protocol, with the following execution flow: -1. **输入参数校验:** - - 确保 `merchant` 与 `token` 地址有效。 - - `amount` 必须大于 0。 -2. **费率计算 (Protocol Fee Split):** - - 协议目前设定 **1% (100 BPS)** 的固定费用。 +1. **Input Parameter Validation:** + - Ensure `merchant` and `token` addresses are valid. + - `amount` must be greater than 0. +2. **Fee Calculation (Protocol Fee Split):** + - The protocol currently sets a fixed fee of **1% (100 BPS)**. - `merchantAmount = amount * 99%` - `protocolFee = amount * 1%` -3. **原子性资产转移 (SafeERC20):** - - 使用 `IERC20.safeTransferFrom` 从 `msg.sender` 处划扣资产。 - - 资产直接流向 `merchant` 地址。 - - 费率直接流向 `protocolTreasury` 地址。 -4. **日志发射 (Emit Evidence):** - - 抛出 `PaymentReceived(orderId, merchant, payer, token, amount, fee)`。 - - SDK 捕获此事件以确认支付状态。 +3. **Atomic Asset Transfer (SafeERC20):** + - Use `IERC20.safeTransferFrom` to deduct assets from `msg.sender`. + - Assets flow directly to the `merchant` address. + - Fees flow directly to the `protocolTreasury` address. +4. **Log Emission (Emit Evidence):** + - Emit `PaymentReceived(orderId, merchant, payer, token, amount, fee)`. + - SDKs capture this event to confirm payment status. -## 🚀 进阶功能: `payWithPermit` +## 🚀 Advanced Feature: `payWithPermit` -为了彻底消除 AI Agent 支付时的 "Two-Step Approval" (Approve + Transfer) 带来的 UX 摩擦与多重 Gas 消耗，协议支持 EIP-2612 Permit。Agent 仅需离线签名，SDK 即可在单笔交易中完成所有支付逻辑。 +To completely eliminate the UX friction and multiple Gas consumptions brought by "Two-Step Approval" (Approve + Transfer) when AI Agents pay, the protocol supports EIP-2612 Permit. Agents only need to sign offline, and the SDK can complete all payment logic in a single transaction. -## 🛠️ 开发指南 +## 🛠️ Development Guide -使用 Foundry 套件进行测试与部署： +Use the Foundry suite for testing and deployment: ```bash -# 编译 +# Compile forge build -# 运行全量测试 (包含 Fuzzing 测试) +# Run full tests (including Fuzzing tests) forge test -vvv -# 部署至 Base Sepolia +# Deploy to Base Sepolia forge script script/Deploy.s.sol --rpc-url $BASE_RPC --broadcast ``` From 8e683028aadc34319175030fca8907eaf6c3e033 Mon Sep 17 00:00:00 2001 From: geminilclaw Date: Sat, 21 Mar 2026 20:02:28 +0800 Subject: [PATCH 2/2] update ignore --- .gitignore | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.gitignore b/.gitignore index ed6bd84..e920ceb 100644 --- a/.gitignore +++ b/.gitignore @@ -1,6 +1,6 @@ out/ cache/ broadcast/ -# lib/ (Removed to allow submodules to be tracked) +lib/ .env .env.*