creator-paywall

💸 クリエイター向けペイウォール

最小限でドロップインな暗号資産サブスクリプションペイウォールです。役割は 2 つだけ: ウォレット認証 + サブスクリプション 検証。プラットフォームになるためではなく、クリエイターの既存プロダクトに埋め込むために作られています。

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 エージェントウォレットに直接受け取りたい — 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 エージェントの EVM ウォレット。 wallet_info ツールを呼び出し、ethereum アドレスを使用します。

ステップ 2 — 雛形を作成します。 init スクリプトを実行します（テンプレートをコピーし、.env を書き込み、npm インストールを実行）:

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 を編集します: 各エントリはユーザーが選択できる 1 つの (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 がブロックされます。 フロントエンドは トークンベース認証 （localStorage + Authorization: Bearer）を使用し、Cookie は使いません。フロントエンドを書き直す場合もこれを維持してください — Cookie セッションはプレビューフレーム内でサイレントに失敗します（ログインが「何も起きない」状態になります）。
2. プレビューは /preview/<id>/ 配下で配信されます。 すべてのフロントエンド API 呼び出しは相対パス （document.baseURI を基準に解決される）でなければならず、絶対パス /api/... にしてはいけません — 絶対パスはルート ドメインに到達して 404 になり、空白ページになります。
3. ウォレットは iframe 内でブロックされることがよくあります。 UI/状態はフレーム内で動作しますが、実際に MetaMask の署名/送金をトリガーするには、ユーザーはプレビューを新しいブラウザタブまたは ウォレットのアプリ内ブラウザで開くか、公開 URL に公開する必要があります。フロントエンドはすでにこれについて警告しています。
4. ネイティブコイン（ETH/BNB）はログスキャンできません。 「Check payment」ボタンは getLogs を使用しますが、 これは ERC20 の Transfer イベントしか捕捉しません。ネイティブの支払いは txHash の送信で確認する必要があります （UI は送金後にこれを自動で処理します。手動での貼り付けはフォールバックです）。
5. バックグラウンドポーリングはありません — 設計上。 確認はオンデマンドのみです（支払い後の txHash ポーリング、 「Check payment」ボタン、手動ハッシュ）。パブリック RPC の使用量を最小限に抑えます。ブロックスキャンのループを追加しないでください。
6. 金額の照合には == ではなく >= を使用します。 転送時手数料 / 丸めに対して安全です。これを維持してください。

クリエイター自身のプロダクトへの統合

全体は 2 つのミドルウェアに集約されます:

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 を置き換えることで独自の DB を持ち込めます（それ以外はすべてストレージ非依存です）。
• セッションは Bearer トークン（/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）を本番用 DB に置き換えます。
• community-publish スキルで公開してパブリック URL を取得します（iframe ウォレットの制限も修正されます）。