Skip to content

M1 acceptance: code cleanup + product designs + upstream sync#1

Open
jhfnetboy wants to merge 9 commits into
aastar-devfrom
m1/acceptance-and-planning
Open

M1 acceptance: code cleanup + product designs + upstream sync#1
jhfnetboy wants to merge 9 commits into
aastar-devfrom
m1/acceptance-and-planning

Conversation

@jhfnetboy
Copy link
Copy Markdown
Member

@jhfnetboy jhfnetboy commented May 5, 2026 •
edited
Loading

背景 / Background

仓库：AAStarCommunity/UltraRelay-AAStar — AAStar 对 ZeroDev/ultra-relay（本身是 Pimlico Alto 的 fork）的私有 fork，作为 AAStar ERC-4337 生产 bundler 使用，支持 xPNTs 代币免 Gas、SuperPaymaster 生态集成。

分支说明：

  • aastar-dev — AAStar 的主开发分支（相当于 main），所有功能分支都 merge 到这里
  • m1/acceptance-and-planning → aastar-dev：本 PR

里程碑：M1 —— 把这个 bundler 交付为可生产部署的标准 ERC-4337 bundler（OP-Sepolia + OP-Mainnet），在进入 M2（绿色通道/trusted-paymasters）和 M3（X402 收费）之前完成基础设施验收。

本 PR 包含什么 / What's in this PR

1. 上游同步

从 zerodevapp/ultra-relay:main 合并 6 个新 commit（无冲突），包含：

2. 代码清理（同步提交上游 PR zerodevapp#27）

  • 删除 eth_sendUserOperation.ts 中的 debug console.log（每笔 UO 都打印）
  • 修正 --max-bundle-count CLI 描述（原描述说"单 bundle 内 op 数"，实际是"每 entrypoint 每次 getBundles 的 bundle 数"）

3. Bug 修复（Codex review 发现，共 10 个修复）

文件 问题 修复
src/executor/executorManager.ts autoScalingBundling() 未将 maxBundleCount 传给 getBundles()，CLI 参数静默失效 传入 this.config.maxBundleCount
src/rpc/methods/debug_bundler_sendBundleNow.ts 多 entrypoint 时只提交 bundles[0]，其余 entrypoint 的 ops 被 dequeue 但丢弃 loop 提交所有 bundle，per-bundle try/catch 防单点异常
src/rpc/server.ts (/wallets) 返回 config.executorPrivateKeys 全量，未尊重 --max-executors 截断 改用 getAvailableWallets(config)
src/cli/config/bundler.ts max-bundle-count 接受负整数，负值 truthy 会使 bundling 静默停止 加 .min(1) 校验
src/cli/config/options.ts --max-bundle-count 描述仍含"per bundle op count"误导 + 硬编码行号 更新为 per-entrypoint 语义，引用函数名
test/e2e/tests/wallets.test.ts refillingWallets 类型写成 Address[]（实际是 boolean），断言逻辑全错 改为 boolean，更新所有断言
test/e2e/tests/wallets.test.ts 缺少 chainId 具体值断言，foundry.id 未验 加 expect(body.chainId).toBe(foundry.id)
test/e2e/tests/wallets.test.ts Set 比较未检测重复地址 加 toHaveLength 断言
docs/M1_DESIGN.md §2.4 描述"单 bundle op 数上限"（完全错误）+ §5.5 行号已失效 更新为 per-entrypoint 语义

4. 产品设计文档（6 个，3800+ 行）

  • docs/M1_DESIGN.md — 协议核心验收矩阵 + 5 个 Known Limitations
  • docs/M2_DESIGN.md — 绿色通道 / trusted-paymasters + EIP-7702
  • docs/M3_DESIGN.md — X402 收费 + 监控 + 多链
  • docs/SUBSCRIPTION_DESIGN.md — 长期订阅计费方案（AirAccount session key + aPNTs 自动抵扣）
  • docs/RUNBOOK.md — 生产部署必配项
  • docs/UPSTREAM_PR_QUEUE.md — 上游 PR 队列

需要 reviewer 重点检查 / Review focus

  1. debug_bundler_sendBundleNow.ts — loop + try/catch 逻辑是否正确（debug 端点，仅开发模式启用）
  2. server.ts getWallets — getAvailableWallets(config) 替换是否正确（与 senderManager 行为对齐）
  3. executorManager.ts — getBundles(this.config.maxBundleCount) 是否有副作用（maxBundleCount 为 undefined 时行为不变）
  4. wallets.test.ts — refillingWallets: boolean 断言是否与端点实际返回值一致

测试计划 / Test plan

  • 上游 merge 无冲突
  • 10 个 Codex review 问题全部修复（6 轮 review 迭代）
  • pnpm install && pnpm run build 通过
  • cd test/e2e && pnpm test (wallets.test.ts + 其他 e2e)
  • pnpm run test:spec（需要 Geth + 手动启动 bundler）
  • OP-Sepolia 灰度部署验收

关联 / Related

jhfnetboy added 9 commits May 5, 2026 09:55
@jhfnetboy
docs: add M1 acceptance design + M2/M3 plans + Subscription + RUNBOOK…
157787f 
… + Upstream PR queue

Three milestone designs + one product planning + two operational docs:

- M1_DESIGN.md (29K) — protocol core acceptance, ZeroDev fork rationale,
  AAStar PR zerodevapp#12-zerodevapp#15 verification, M1-new features (rate limit, upstream
  sync), known limitations (JSON logging fallback, implicit boost, etc.)
- M2_DESIGN.md (54K) — green lane / trusted-paymasters / paymasterProfiles
  plugin (≤5 hooks), fast-lane in mempool/executor, EIP-7702 implementation,
  safety three-layer model
- M3_DESIGN.md (63K) — X402 charging, xPNTs prepaid receivables, monitoring,
  upstream sync automation, RPC cost governance, operator attestation,
  postOp gas profiling, multi-chain rollout
- SUBSCRIPTION_DESIGN.md (79K) — long-term product planning for external-user
  subscription model: API key + on-chain SubscriptionManager + aPNTs auto-deduct
  via AirAccount session key (length-based dispatch: 105B ECDSA / 148B P256)
- RUNBOOK.md — production deployment must-haves: --chain-type op-stack,
  IP allowlist, BETTER_STACK_TOKEN, monthly upstream sync, troubleshooting
- UPSTREAM_PR_QUEUE.md — tracks PRs to be sent to zerodevapp/ultra-relay:
  cleanup commit (in flight), drop-log structuring, --allow-implicit-boost
  flag, JSON logging fallback fix
@jhfnetboy
chore: remove debug log and clarify max-bundle-count description
ce954af 
Two minor cleanups suitable for upstreaming to zerodevapp/ultra-relay:

1. Remove leftover debug console.log("=== eth_sendUserOperation called ===")
   in eth_sendUserOperation handler (introduced in commit 702f9af alto merge).

2. Fix --max-bundle-count CLI description: the flag actually caps the number
   of BUNDLES produced per getBundles() iteration (see mempool.ts:725-773),
   not the number of UserOperations within a single bundle. The previous
   wording misled operators configuring the flag.

No behavior change.
@jhfnetboy
test(e2e): add /wallets endpoint coverage
443f5d5 
Adds an e2e test for the AAStar /wallets HTTP endpoint introduced in PR zerodevapp#15.
Covers: happy path, address-set match against configured executor keys,
EIP-55 checksum format. The endpoint had no test coverage before (M1 §3.4
acceptance gap).

Endpoint contract: GET /wallets -> { wallets: Address[], chainId: number }
Note: utility wallet is NOT included in the response (per current impl,
src/rpc/server.ts:179-196).
@jhfnetboy
docs+test: align with upstream sync (utility wallet in /wallets, PR z…
8ef9099 
…erodevapp#27 status)

Post upstream/main merge (commits a526e11..4a0372a), reflect new state:

- test/e2e/tests/wallets.test.ts: assert utilityWalletAddress + refillingWallets
  fields per upstream PR zerodevapp#17 (3f3bc2c) — handler now returns
  { wallets, chainId, utilityWalletAddress, refillingWallets }
- docs/M1_DESIGN.md §3.4: remove "utility not included" caveat; document the
  new shape; reference upstream 3f3bc2c
- docs/M1_DESIGN.md §5.5 Limitation 1: note upstream PRs zerodevapp#18/zerodevapp#19 added logtail
  transport error handling + dead-transport noop, but the fallback logic
  (no token → pino-pretty) is unchanged, so this limitation still applies
- docs/UPSTREAM_PR_QUEUE.md: PR #1 status moved to "待 review"
  (zerodevapp#27)
@jhfnetboy
fix: remove hardcoded line numbers from max-bundle-count comment
5158e34 
Line numbers drift as code evolves; reference the function name instead.
@jhfnetboy
fix: correct refillingWallets type in test + wire maxBundleCount to g…
4e73ae3 
…etBundles

refillingWallets is a boolean config flag (not Address[]) per upstream PR zerodevapp#17
source (bundler.ts:96 z.boolean()); update test type and assertions.

Pass this.config.maxBundleCount to getBundles() so --max-bundle-count CLI
option actually takes effect (was silently ignored).
@jhfnetboy
fix: clarify max-bundle-count is per-entrypoint cap, update docs
fbfe5a7 
The cap is applied independently per entrypoint in getBundles(); with N
entrypoints and maxBundleCount=M, up to N*M bundles may be returned.
Update options.ts description and M1_DESIGN.md §2.4 + §5.5 to reflect
actual semantics instead of claiming a global total-bundle limit.
@jhfnetboy
fix: submit all bundles in debug handler, respect max-executors in /w…
1832148 
…allets, validate max-bundle-count >= 1

- debug_bundler_sendBundleNow: submit all bundles from all entrypoints
  (getBundles(1) returns 1 bundle per entrypoint; previous code only
  submitted bundles[0], silently dropping ops from other entrypoints)
- /wallets endpoint: use getAvailableWallets() to respect --max-executors
  cap instead of returning the full executorPrivateKeys list
- max-bundle-count schema: add .min(1) so negative values are rejected
  at startup (negative truthy values would have disabled bundling silently)
@jhfnetboy
fix: guard each bundle submission in debug handler to continue on par…
bc38114 
…tial failure

A single entrypoint's executor error no longer aborts the entire loop;
remaining entrypoint bundles are still attempted.
fanhousanbu
fanhousanbu approved these changes May 6, 2026
View reviewed changes
Copy link
Copy Markdown

@fanhousanbu fanhousanbu left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

✅ Approved

代码改动均为正向修复，无 CRITICAL/HIGH，docs 内容准确。

关键 Bug Fix 确认

  • executorManager.ts：getBundles() 之前未传 maxBundleCount，--max-bundle-count CLI flag 实际无效。本 PR 补上，配合 bundler.ts 的 .min(1) 校验，行为与文档一致。
  • debug_bundler_sendBundleNow.ts：旧代码只提交 bundles[0]，多 entrypoint 场景其余 bundle 被丢弃。新代码遍历全部 bundle，partial failure 继续提交剩余，符合 debug handler 语义。
  • /wallets：改用 getAvailableWallets() 正确返回 utility + refilling 地址，配合 upstream PR zerodevapp#17 字段对齐。

MEDIUM（非阻断）— debug handler 的 silent catch

} catch {
    // continue submitting remaining entrypoint bundles
}

发生 submission error 时完全静默。虽然是 debug endpoint（生产关闭），但调试时一旦某个 entrypoint bundle 提交失败，submitted = true 仍可能因另一个成功而返回 txHash，掩盖了部分失败。建议加一行：

} catch (err) {
    logger.warn({ err }, "debug_bundler_sendBundleNow: bundle submission failed, continuing")
}

LOW — max-bundle-count 无上限
.min(1) 防止了 0，但没有 .max(N) 上限。极端值（如 999999）行为退化为无限制，和不设 flag 等价。可考虑加 .max(100) 或在 options 里文档化"不设则无限"。不阻断。

Docs 质量高，M1–M3 边界清晰，--chain-type op-stack 漏配风险在 RUNBOOK 里已标注。

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@fanhousanbu fanhousanbu fanhousanbu approved these changes

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@jhfnetboy @fanhousanbu