creator-paywall

💸 Creator Paywall

一个极简、即插即用的加密货币订阅付费墙。只做两件事：钱包认证 + 订阅 校验。它的定位是嵌入创作者已有的产品中，而不是做成一个平台。

Connect wallet → sign SIWE message → session (wallet = identity)
      │
      ├─ pick plan (chain + token + monthly/yearly)
      ├─ transfer tokens to the creator's wallet
      └─ submit txHash → backend verifies on-chain → subscription active

核心技巧： 付款人的地址必须等于已登录的钱包。这样一笔普通 转账就能匹配到某个用户，无需任何备注或订单 ID。匹配规则是 from == logged-in wallet。

何时使用它

• 创作者做出了某样东西（应用、仪表盘、内容、API），并希望收费访问。
• 他们希望加密货币付款直接进入自己的 Starchild agent 钱包 —— 不用 Stripe，不用注册。
• 仅支持订阅模式（按月 / 按年）。不支持按用量计费，不支持法币。

如果创作者需要法币 / 银行卡或自动循环扣款，这个工具就不合适 —— 直接告诉他们。

它是什么

一个小型 Node/Express + viem 应用。约 900 行代码，SQLite 存储（可替换）。链：Ethereum、Base、BSC。 代币：原生币或任意 ERC20（包括创作者自己的自定义代币）。

template/
  config.js          ← the ONLY file most creators edit (chains / tokens / prices / wallet)
  src/auth.js        ← SIWE login + requireAuth / requireSubscription middleware
  src/payments.js    ← on-chain verification (txHash receipt + bounded getLogs scan)
  src/chains.js      ← viem clients + plan/price helpers
  src/db.js          ← SQLite (replace with your DB when integrating)
  src/server.js      ← REST API wiring everything together
  public/index.html  ← demo frontend: 3 views (landing / paywall / member), token-based auth
  README.md          ← integration docs for the creator
  .env.example

快速开始（脚手架生成新实例）

第 1 步 —— 获取创作者的收款钱包。 默认 = 其 Starchild agent 的 EVM 钱包。 调用 wallet_info 工具并使用其中的 ethereum 地址。

第 2 步 —— 生成脚手架。 运行初始化脚本（复制模板、写入 .env、执行 npm install）：

bash skills/creator-paywall/scripts/init.sh <target_dir> <creator_wallet> [jwt_secret] [siwe_domain]
# example:
bash skills/creator-paywall/scripts/init.sh output/projects/my-paywall 0xYourAgentWallet

jwt_secret 如果省略会自动生成。siwe_domain 默认为 localhost（生产环境要设置真实域名）。

第 3 步 —— 设置套餐。 编辑 config.js → PLANS：每一项都是一个 (chain, token, monthly, yearly) 组合， 供用户选择。推荐使用稳定币（法币价值稳定）。对于自定义代币，要设置正确的 decimals。

第 4 步 —— 运行并预览。

# foreground for a quick check, or use the preview tool:

使用 preview 工具：调用 serve，dir=<target_dir>、command="node src/server.js"、port=3007 （端口必须与 .env 中的 PORT 一致）。然后把 /preview/<id>/ 给用户。

关键坑点（构建过程中总结 —— 不要跳过）

1. 预览运行在 iframe 中 → cookie 会被拦截。 前端使用基于 token 的认证 （localStorage + Authorization: Bearer），而不是 cookie。如果你重写前端，要保留这一点 —— 在预览 frame 内部，cookie 会话会静默失败（登录“毫无反应”）。
2. 预览通过 /preview/<id>/ 提供。 所有前端 API 调用都必须使用相对路径 （相对于 document.baseURI 解析），绝不能用绝对的 /api/... —— 绝对路径会打到根 域名并返回 404，导致页面空白。
3. 钱包在 iframe 内常常被拦截。 UI / 状态在 frame 中可用，但要真正 触发 MetaMask 签名 / 转账，用户应在新的浏览器标签页或 钱包内置浏览器中打开预览，或者发布到公开 URL。前端已经对此给出了提示。
4. 原生币（ETH/BNB）无法通过日志扫描。 “Check payment” 按钮使用 getLogs，它 只能捕获 ERC20 的 Transfer 事件。原生币付款必须通过 提交 txHash 来确认 （UI 在发送后会自动处理；手动粘贴是兜底方案）。
5. 没有后台轮询 —— 这是有意为之。 确认只在需要时进行（付款后的 txHash 轮询、 “Check payment” 按钮、手动输入哈希）。这让公共 RPC 的使用量极小。不要添加区块扫描循环。
6. 金额匹配使用 >=，而不是 ==。 对于带转账手续费 / 舍入的情况更安全。保持这样。

集成到创作者自己的产品中

整件事可以归结为两个中间件：

import { requireAuth, requireSubscription } from "./src/auth.js";

app.get("/my/premium", requireAuth, requireSubscription, (req, res) => {
  // req.wallet = user address;  req.subscription.expires_at = unix expiry
  res.json({ ... });
});

• 替换 src/db.js 即可接入你自己的数据库（其他所有部分都与存储无关）。
• 会话通过 Bearer token 工作（由 /api/login 返回）—— 在 SPA 和 iframe 中都可用。
• 订阅续费靠用户再次付款（expires_at 向后顺延）。没有链上自动扣款。

API 接口

方法	路由	认证	用途
GET	/api/config	—	链、方案、创建者钱包
GET	/api/nonce?address=&chainId=&uri=	—	待签名的 SIWE 消息
POST	/api/login {message,signature,chainId}	—	验证 → 返回会话令牌
POST	/api/logout	—	结束会话
GET	/api/me	token	钱包 + 订阅状态
POST	/api/subscribe/intent {chainId,token,period}	token	发起支付 → 金额 + payTo
POST	/api/subscribe/verify {intentId,txHash}	token	确认交易（原生 + ERC20）
POST	/api/subscribe/check {intentId?}	token	扫描 ERC20 支付
GET	/api/protected	token + subscription	示例门控资源

验证规则（怎样才算已支付）

1. 交易已确认（链特定的确认数）且成功
2. 接收方 == 创建者钱包
3. 发送方 == 已登录钱包
4. 代币与所选方案匹配
5. 金额 ≥ 方案价格（>=）
6. txHash 尚未被使用（幂等）

上线部署

• 在 .env 中设置强 JWT_SECRET 和真实的 SIWE_DOMAIN。
• 将 config.js 中的公共 RPC 替换为你自己的（Alchemy/QuickNode）——设置 RPC_ETHEREUM/RPC_BASE/RPC_BSC。
• 将 SQLite（src/db.js）替换为你的生产数据库。
• 通过 community-publish 技能发布以获得公开 URL（同时修复 iframe 钱包限制）。