nibgate

Nibgate — 付费内容开放协议

网站 | 文档 | X

Nibgate 是面向创作者自有作品的内容发现、解锁与信誉验证层。创作者将内容保留在自己的域名上。Nibgate 会验证来源、索引结构化公开元数据、记录解锁／付款信号，并帮助人类和 AI Agent 发现优质内容，而无需将内容迁移到封闭的市场中。

基于 Arc 和 x402 协议构建，已在主网运行并镜像至测试网，支持两种支付通道：Circle Gateway（EIP-3009 协调器）和直接向创作者收款地址转账 USDC。

主要软件包：

• SDK（packages/nibgate/） — 用于在任意创作者网站上设置付费内容门控的 @nibgate/sdk npm 软件包。提供浏览器和服务器入口、x402／Gateway 解锁、事件流以及链上评分。包含两种支付通道共用的访问控制规则（canAccess、normalizeWhitelist、paidCutoffWallets）和加密原语（crypto.js）。
• 钱包（packages/wallet/） — 带有 ./react 入口的 @nibgate/wallet npm 软件包：共享的 Reown AppKit（AppKit + wagmi）钱包提供程序、SIWE 登录，以及 Hub 页眉、Nibshare 和 Subblogs 使用的 <NibgateUnlock>／GatewayWallet 单次结账功能。
• Subblogs（subblogs/） — 面向创作者、运行于 *.nibgate.xyz 的完整博客平台。支持文章、照片、音乐、视频、文档，以及免费和付费帖子。采用 Next.js 前端（端口 3002）、Express 后端（端口 4000）和 PostgreSQL。支持 SIWE 钱包身份验证、白名单／仅限邀请的等级，以及静态加密 AES-256-GCM。
• Hub（frontend/ + backend/） — 主应用 nibgate.xyz：公共网站、创作者控制面板、Explore 发现页面、分析、API、Nibshare 快速分享通道和小组件托管。
• CLI（packages/cli/） — 用于本地开发、网站验证和 Hub 连接的内部工具。
• 文档（docs/） — 位于 docs.nibgate.xyz 的文档网站。

产品理念

开放网络需要一套用于发现付费优质资源的内容发现标准。Nibgate 提供验证层，用于证明：

1. 此域名由这位创作者控制
2. 此内容存在于此路由
3. 人类或 Agent 可以解锁此内容
4. 这位创作者拥有来自已验证活动的真实信誉信号
5. 此资源的付款记录会直接汇入配置的收款地址

创作者自有网站仍是事实来源，而 Hub 则成为围绕已验证内容的公共索引、分析界面和信誉图谱。

它由四个相互连接的部分组成：

1. 小组件：创作者在自己的网站上粘贴一个脚本。它会证明域名所有权、创建访客／会话上下文，并向 Nibgate 发送浏览器安全的页面活动数据。
2. 软件包：创作者安装 @nibgate/sdk npm 软件包，在自己的网站上为真实内容设置门控。该软件包负责内容、解锁和付款生命周期，并通过小组件桥接报告这些事件。
3. Hub：nibgate.xyz 是创作者控制面板、发现界面和分析层。它会验证网站、存储内容元数据、汇总指标，并展示个人资料／网站／内容／收入数据。
4. 发现层：Explore、公开个人资料、内容元数据、收据和信誉信号，让人类和 AI Agent 能够阅读已验证创作者的内容。

仓库布局

backend/       Express hub API — payment verification, hosted-pay resolution,
               metrics, site/manifest sync, revenue keeper (fee-wallet sweeps)
frontend/      Next.js hub UI — public site, dashboard, Explore, leaderboards
subblogs/      Subblogs — full blog platform for creators (Express+Prisma + Next.js)
packages/      @nibgate/sdk npm package + wallet package + CLI tooling
contracts/     Solidity + Foundry: reputation contracts, per-creator
               GatewayFeeWallet / GatewayFeeWalletFactory (revenue model),
               and TipHoldingFactory / TipHoldingWallet (no-key per-domain
               tip boxes: deterministic CREATE2, keeper release/refund)
docs/          Nextra docs site for docs.nibgate.xyz
scripts/       E2E flows and deployment tooling (reputation, revenue factory)
e2e/           Playwright browser harness (extension + tip flows; run outputs ignored)
extension/     MV3 wallet extension — content detection, tip/hold/refund UI, JEV fallback
jev/           JEV decision layer — deterministic decide/selectMany engine plus
               the real JEV decisions-model client (OpenRouter)
tipping/       Nib Tip design record (DESIGN/SPEC/FEES/NON-NIBGATE-CREATORS) —
               protocol reference; implementation lives in packages/nibgate,
               backend tip routes, contracts, and the extension
dr-nib/        Dr. Nib research agent — backend service + hub UI + spend/escrow
               rails (see dr-nib/README.md for the Done/Partial/Pending status)
mcp-registry/ MCP registry record for the hub MCP server
nibgate.config.json  Sample CLI config (routes to local demo content)

仅本地使用、不纳入版本控制：video/、v2-labs/、revenue-model/（研究／概念验证）、端到端测试工具及其运行输出（e2e/）。请参阅 .gitignore。

工作区结构

backend/ 和 frontend/（中心站）

中心站是 Nibgate 的主应用和 API 接口。它同时充当创作者仪表板、公共网站和发现目录：

• /explore 发现瀑布流网格，索引所有创作者内容。
• /ledger 公共活动动态——涵盖所有站点的解锁、付款、小费（包括待领取的已注资款项）、评分和 nibshare，支持搜索和筛选。退款会显示为负数小费条目。
• /pending-tips 公共查询工具，可查询任意精确域名下已注资但尚未领取的小费，包括未在 Nibgate 注册的外部站点。它遵循部署所用的网络：nibgate.xyz 使用主网，testnet.nibgate.xyz 使用测试网。
• /discovery.md 面向 Agent 的指南——以通俗语言介绍 Nibgate 端点、付款流程和评分流程。
• /auth/* 使用 Ethereum 登录（SIWE）身份验证。
• /hub/* 中心站连接、同步、验证和事件接收。
• /hub/ledger?domain=X 公共账本端点，可选域名筛选，用于查看各站点的活动。
• /hub/tips/held?domain=X 公共精确域名查询端点，用于查询尚未领取的小费；请使用对应网络的主网或测试网 API 主机。

subblogs/（子博客——创作者博客平台）

这是一个带付费内容访问控制的创作者博客示例。包含两项服务：

• subblogs/backend/（Express + Prisma）——提供内容页面，通过中心站处理付款，并签发解锁证明。配置 R2 后，所有文章正文和媒体文件（免费和付费内容）都会在静态存储时加密；免费内容在服务器端解密后向所有人提供，付费内容则仅在链上证明验证通过后提供。访问端点（GET /api/<type>/<slug>，是 GET /api/nibgate/access 的简短镜像）是高级内容的唯一可信来源——仅在证明验证通过后返回文章正文。每篇文章页面也会为 Agent 提供自描述信息：GET /api/nibgate/manifest?path=/<type>/<slug> 会返回该文章的机器可读契约（通过 <link rel="alternate"> 元素和 Link 响应标头声明）。
• subblogs/frontend/（Next.js）——公共博客界面。高级内容绝不会出现在 HTML 中。NibgateUnlock 组件会在证明验证通过后，从受保护的访问端点获取内容。管理面板（/admin/posts）提供每篇文章的统计信息表单，展示解锁次数、以 USDC 计的收入，以及每篇文章对应的底层收据。

关键规则：GET /api/blog/posts/:slug 端点会解密并返回免费文章的正文，并从付费文章中移除 body。高级内容正文仅在有效证明通过验证后，由访问端点（GET /api/<type>/<slug> 或 GET /api/nibgate/access）返回。这可防止付费内容出现在页面源代码中，同时确保免费内容仍可公开阅读。

nibshare（快速分享门控内容）

Hub 内托管的快速分享入口：钱包所有者发布加密载荷，可选设置价格和钱包白名单，并且必须设置过期时间（最晚为 7 天后），随后会获得一个 nibgate.xyz/ns/<slug> 短链接。无需域名。正文和媒体始终以 AES-256-GCM 加密后存储在 Cloudflare R2 中；解锁通过服务端解密代理在 Arc 上使用 x402 USDC 完成（免费的公开分享可直接阅读，仅限受邀者的分享需要经会话验证的白名单钱包，付费分享则须先付款）。这是一个私有产品——其内容不会编入公开发现或声誉索引；注重隐私的财务账本条目不会包含分享链接。分享页会向 Agent 自我描述：GET /nibshare/:slug/manifest（也可通过 https://api.nibgate.xyz/ns/<slug> 这个短读取路由访问）会返回机器可读的契约（通过 <meta name="nibgate:*">、JSON-LD、data-nibgate-* 属性、<link rel="alternate"> 元素和 Link 响应头声明），而 Nibgate MCP 服务会将其作为 resolve_share 工具公开。

服务端源代码位于 backend/src/server/nibshare/{controller,service,utils,routes}.js；它将访问决策委托给 SDK 的 access-policy.js（持有凭证规则、先付款后拒绝、幂等收据授权），并提供与 Subblogs 相同的授权、封禁、撤销财务功能。

文档与实现放在一起，而非单独放在顶层目录：

• backend/src/server/nibshare/README.md — 产品、威胁模型、身份验证、环境
• backend/src/server/nibshare/API.md — HTTP 契约
• backend/src/server/nibshare/STORAGE.md — R2 布局、加密、媒体提供
• backend/src/server/nibshare/STORAGE-TIER-PLAN.md — 计划中的 Arweave/Lit 层级（尚未发布）

packages/nibgate/

这是面向公开创作者的包，刻意保持轻量且与框架无关：

npm install @nibgate/sdk

Agent 和编码助手在编辑创作者网站前，应先阅读精简的集成指南：

• 包内副本：node_modules/@nibgate/sdk/SKILL.md
• 公开副本：https://nibgate.xyz/skill.md

它负责：

• 浏览器入口：createGate(...)、nibgate.content(...)、nibgate.view(...)、nibgate.unlockStarted(...)、nibgate.unlockCompleted(...) 和 nibgate.paymentCompleted(...)
• 服务端入口：createNibgateServer(...)、protect(...)、nibgateServer.accessFor(...)、付款质询和解锁令牌验证
• 在 Hub 小组件就绪前对事件进行排队
• 将内容类型规范化为 music、video、article、image 和 document
• 面向人类和 Agent 的访问策略：free、paid 或 blocked
• 解锁策略：MVP 阶段从 one_time 开始，并为之后的计量阅读、流式传输、通行证和 Agent 配额预留空间

packages/cli/

已发布的 @nibgate/cli 包提供创作者设置和运维辅助工具。它负责：

• npx @nibgate/cli
• 本地状态和设置检查
• 配置生成辅助工具
• Hub 连接和域名验证命令
• 未来围绕小组件/包设置的脚手架

公开的 @nibgate/sdk 包负责路由保护、付款质询元数据、解锁令牌和包事件 API。

demo/

仅限本地使用，不纳入此仓库跟踪。一个模拟创作者自有网站的源站应用，用于验证安装流程、基于数据库的内容映射、包事件和受保护内容流程，同时避免污染 Hub 代码。真实模板示例应放在 demo/examples/* 下，每个示例都从一个易于识别的起始仓库出发，并加入 Nibgate 包集成。如果你的检出目录中没有 demo/ 目录，请跳过下方的演示命令——其他所有内容都可正常运行。

网络与部署

Nibgate 运行着两套并行的技术栈。主网是生产环境；测试网与其镜像同步，用于预发布。身份信息会在两套网络间同步；资金和内容则不会：站点（域名、验证信息、所有者钱包、发布者资料）、用户账户（同一钱包在所有环境中对应同一管理员）以及已发布的编辑博客文章会在测试网与主网之间镜像同步。内容目录、解锁记录、付款、评分、指标和会话则各自保留在所属网络中——每条内容或账本记录都带有由 Hub 标记的 network 标签，并且会拒绝链上信息表明来自另一套网络的收据。

	主网	测试网
Hub 站点	https://nibgate.xyz	https://testnet.nibgate.xyz
Hub API	https://api.nibgate.xyz	https://testnet-api.nibgate.xyz
子博客	https://{sub}.nibgate.xyz	https://{sub}.testnet.nibgate.xyz
子博客 API	https://api-subblogs.nibgate.xyz	https://testnet-api-subblogs.nibgate.xyz
分享链接	https://nibgate.xyz/ns/{slug}	https://testnet.nibgate.xyz/ns/{slug}
Arc 链	5042 (eip155:5042)	5042002 (eip155:5042002)
Gateway API	https://gateway-api.circle.com	https://gateway-api-testnet.circle.com
Railway	nibgate-mainnet 项目	nibgate-testnet 项目（Hub、Dr. Nib 和整合后的子博客后端）；整合服务通过验证后，已删除已废弃的独立 nibgate-subblogs-testnet 项目
Vercel	nibgate-frontend、nibgate-subblogs-mainnet	nibgate-frontend-testnet、nibgate-subblogs-testnet

网络由环境变量选择，默认为测试网：

• 后端：NIBGATE_NETWORK=mainnet|testnet（默认为 testnet——缺少变量时绝不会转移真实资金）
• 前端：NEXT_PUBLIC_NIBGATE_NETWORK=mainnet|testnet
• 显式设置的各项环境变量（RPC URL、合约地址、来源地址）始终优先于网络默认值。
• Railway 的 RPC 顺序是有意安排的：Canteen 是测试网主 RPC，dRPC 是主网主 RPC，相应的官方 Arc 端点则是同链的最终回退地址。在使用这些配置的地方，将 ARC_RPC_URL、NIBGATE_PAYMENT_RPC_URL 和 NIBGATE_REPUTATION_RPC_URL 设置为主 RPC；将 ARC_RPC_FALLBACK_URLS 和 NIBGATE_RPC_MIRRORS 都设置为官方端点。此外，Dr. Nib 还会将 DRNIB_RPC_BACKUP 设置为该官方端点，以独立检查签名前的链和区块高度。

由于必要的限制，链参数分散在多个位置（已发布的 @nibgate/wallet 无法导入私有的 @nibgate/internal，子博客引用本地 SDK/钱包源码，运维脚本独立运行）。规范注册表位于 packages/internal/src/networks.js；镜像文件位于 packages/wallet/src/chain.js、subblogs/backend/src/lib/network.js、subblogs/frontend/src/lib/network.ts、scripts/network.mjs 和 contracts/deployments/arc-mainnet.json。如果这些文件出现差异，pnpm networks:check（也包含在 pnpm test 中）会使构建失败。完整参考：网络。

运行

使用 Node 22，从仓库根目录安装一次：

npx [email protected] install --frozen-lockfile

启动后端：

npm run dev:backend

启动前端：

npm run dev:frontend

启动示例创作者来源站点（需要仅在本地提供的 demo/ 目录——如果你的检出版本没有该目录，请跳过）：

cd demo/examples/next-mdx-blog
NIBGATE_SITE_ORIGIN=http://localhost:4301 npm run dev -- -p 4301

打开：

• http://localhost:3001
• http://localhost:3001/explore
• http://localhost:4301

环境

后端变量：

DATABASE_URL=postgresql://USER:PASSWORD@HOST:PORT/railway
CORS_ORIGIN=https://nibgate.xyz,https://testnet.nibgate.xyz,http://localhost:3001
BLOG_OWNER_WALLET=0x558e7BFaF2Cf1A494F44E50D92431Afc060c9D12
RESEND_API_KEY=your_resend_api_key
RESEND_NEWSLETTER_SEGMENT_ID=seg_your_newsletter_segment_id
RESEND_NEWSLETTER_TOPIC_ID=topic_your_newsletter_topic_id
METRIC_HASH_SALT=generate_a_long_random_secret
TRACKING_RATE_LIMIT_MAX=180
TRACKING_RATE_LIMIT_WINDOW_MS=60000
TRACKING_VIEW_DEDUPE_WINDOW_MS=1800000
MANIFEST_SYNC_INTERVAL_MS=900000
MANIFEST_SYNC_RETRY_AFTER_MS=1800000
MANIFEST_SYNC_BATCH_SIZE=100

对于生产环境，请将 Railway Postgres 数据库附加到后端服务，并使用 Railway 的 DATABASE_URL 值。Prisma 数据源现在仅支持 PostgreSQL，因此每个后端环境都必须提供 DATABASE_URL。

BLOG_OWNER_WALLET 是唯一获准从 /dashboard/blog 创建、编辑、发布、保存草稿或删除文章的已签名钱包。其他钱包均无法访问编辑器 API。

新闻通讯订阅首先存储在本地 NewsletterSubscriber 表中。如果配置了 RESEND_API_KEY，后端还会将每条订阅同步到 Resend Contacts。RESEND_NEWSLETTER_SEGMENT_ID 和 RESEND_NEWSLETTER_TOPIC_ID 为可选项，但建议配置，以便将新闻通讯订阅与事务性联系人分开归类。未配置 Resend 环境变量时，订阅仍会保存到本地，并标记为待同步状态。

METRIC_HASH_SALT 用于生成保护隐私的服务端访客哈希，以便分析去重。在生产环境中请使用稳定的密钥；轮换密钥会重置独立访客的连续性。去重默认时长为：页面／资源浏览 30 分钟、内容注册和支付／解锁支付 ID 24 小时、时间事件 5 分钟、互动事件 30 秒。后端还会按站点／IP／访客分组对 /hub/evt 限流（旧版 /api/hub/track 别名仍可使用）。

Manifest 同步会在创作者更改标题、描述、图片、价格、标签或路由时，更新 Explore 和仪表板中的元数据。后端会从 /nibgate.json、/.well-known/nibgate.json、/v1/nibgate/manifest 或 /v1/nibgate/nibgate.json 读取已验证站点的 manifest。创作者也可以从 /dashboard/sites 手动刷新站点；当小组件／软件包产生的事件流量再次出现稳定内容 ID 时，也会更新同一条内容记录。

前端变量：

NEXT_PUBLIC_API_URL=https://api.nibgate.xyz       # mainnet; testnet builds use https://testnet-api.nibgate.xyz
NEXT_PUBLIC_NIBGATE_NETWORK=mainnet               # or testnet (default testnet — a missing var never moves real money)

在本地运行时，请将 NEXT_PUBLIC_API_URL 指向本地后端，以便 /api/* 重写规则和公开的服务端渲染博客页面从同一个 API 读取数据。

对于可随时丢弃的本地开发数据库，在运行后端之前，请同步有意更改过的 Prisma schema 并重新生成客户端：

DATABASE_URL=postgresql://USER:PASSWORD@HOST:PORT/railway \
pnpm --filter @nibgate/cli exec prisma db push

DATABASE_URL=postgresql://USER:PASSWORD@HOST:PORT/railway \
pnpm --filter @nibgate/cli exec prisma generate

生产环境启动不会配置或更改数据库 schema。全新安装和 schema 升级必须先针对正确的数据库，经过单独审核的配置／迁移步骤；在新后端处理流量之前，请检查 SQL 或 schema 差异，确认备份和授权，并且不要使用有破坏性的启动回退方案。仅生成 Prisma 客户端不会创建表。此要求适用于 Hub、Subblogs 和 Dr. Nib（参见 dr-nib/DEPLOY.md）。当前 SDK/RPC 版本无需更改 schema。Hub 保留了现有的幂等启动回填逻辑，用于为 network 为 null 的旧内容／收据／评分／指标／事件行添加标签；即使启动时不涉及 schema，也仍会执行这些现有数据更新。

CLI

实用的本地命令：

npm run routes
npx @nibgate/cli status
npx @nibgate/cli connect
npx @nibgate/cli verify
npx @nibgate/cli event resource_view premium-article
npx @nibgate/cli balance
npx @nibgate/cli deposit 1.0

面向软件包的结构：

npx @nibgate/cli init
npx @nibgate/cli dev
npx @nibgate/cli routes

产品流程

Nibgate 使用经过验证的发现事件架构：

Creator site
  Hub widget
    - verifies ownership
    - owns siteId/token/session context
    - sends events to the backend

  Nibgate package
    - gates real creator content
    - knows content metadata and unlock/payment lifecycle
    - calls window.nibgateHub when content is viewed, unlocked, or paid for

Nibgate backend
  - validates siteId/token/origin
  - stores content metadata
  - stores metric events
  - aggregates dashboard data
  - updates discovery and reputation signals

创作者在自己的网站上安装 @nibgate/sdk 后，该软件包负责：

1. 通过服务器端访问检查，在创作者源站保护付费路由和受限内容
2. 处理 x402/Circle 解锁逻辑
3. 为 music、video、article、image 和 document 注册内容元数据
4. 发送内容级事件，例如 resource_view、unlock_started、unlock_completed 和 payment_completed
5. 用户与受保护内容互动时，将资源 ID、标题、价格和路径传递给 Hub 小组件

对于真实博客和由 CMS 支持的网站，限制访问字段应与创作者自己的数据库或管理界面中的内容记录放在一起。Nibgate 会将该记录映射为资源：

{
  id,
  title,
  type,
  price,
  path,
  access: {
    humans: 'free' | 'paid' | 'blocked',
    agents: 'free' | 'paid' | 'blocked'
  },
  unlock: {
    mode: 'one_time'
  }
}

这适用于 Next.js、React 加 API 后端、Express、NestJS、Remix、SvelteKit、Astro SSR、MDX 服务器渲染、无头 CMS 应用，以及传统 CMS/插件环境。纯静态 HTML 可以使用小组件进行验证和发送事件，但受保护内容仍需要服务器、边缘函数、API 路由或签名 URL。

线上生产流程——付费一次，永久阅读：

pay once -> verify receipt/proof -> issue unlock token -> serve content -> report receipt to Nibgate

该软件包保留了 unlock 策略字段，以便未来版本在不改变创作者集成方式的情况下添加更丰富的模式：

unlock: { mode: 'one_time' }       // live in production (Arc mainnet + testnet)
unlock: { mode: 'metered_stream' } // later: pay by watched seconds/minutes
unlock: { mode: 'metered_read' }   // later: pay by section/paragraph/token window
unlock: { mode: 'time_pass' }      // later: pay for time-limited access
unlock: { mode: 'agent_quota' }    // later: pay for agent reads/crawls

目前只有 one_time 已可用于生产；其余都是未来模式。

Hub 小组件负责：

1. 在创作者域名上添加一个脚本标签，以证明网站所有权
2. 自动发送页面浏览事件
3. 从 data-nibgate-* 属性或 nibgate:* 元标签中检测内容标记
4. 提供 window.nibgateHub.registerContent(...)、window.nibgateHub.track(...) 和解锁/支付辅助函数，以便软件包发送单个资源事件
5. 发送到后端前附加站点 ID、公开令牌、访客 ID、会话 ID、URL、路径、来源页面和滚动深度

Hub 负责：

1. 注册站点
2. 通过获取创作者主页并检查其中是否包含小组件令牌来验证域名所有权
3. 接收页面浏览、内容浏览、解锁、收入和性能事件
4. 为流式传入的软件包/小组件事件中的资源元数据建立索引

这样，真实内容和访问控制都保留在创作者域名上，而 Hub 只存储发现、分析、收益和信誉所需的元数据、事件、收据和汇总数据。

发现与声誉

Nibgate 发现功能不只是一个公开展示库，而是一个经过验证、由创作者拥有的内容索引，人类和 Agent 可以放心浏览、引用、解锁并据此进行支付。

公开账本（/ledger）实时提供每次浏览、解锁、支付和评分的可审计动态，并附有链上证明链接。每一行都可展开查看完整详情，包括钱包地址、交易哈希和时间戳。统计总数会在更新时动态变化。

中心可以按以下条件对内容进行排序和筛选：

1. 已验证的域名所有权
2. 内容类型：music、video、article、image 或 document
3. 创作者资料和用户名
4. 页面浏览量、内容浏览量、解锁尝试次数和付费解锁次数
5. x402 / Arc 主网和测试网收据元数据
6. 新鲜度、标签、来源路由和推荐信号
7. 未来与真实交互相关联的人类和 Agent 反馈

声誉从内容层面开始。在当前 MVP 中，内容、网站和创作者声誉综合了经过验证的 package/widget 活动，以及更有力的支付、解锁收据和已索引的链上评分信号。声誉关键操作必须通过证明验证：支付和解锁收据需要服务提供方证明；评分则需先证明符合解锁资格，然后通过链上声誉合约/索引器接收。

预期的解锁模式仍由创作者网站原生支持：

1. 创作者从自己的网站发布内容元数据
2. 买家或 Agent 通过 x402、Gateway、直接钱包支付或其他由网站支持的方式支付并解锁内容
3. package 将解锁/支付收据报告给 Nibgate
4. 经过验证的收据使该钱包具备评分资格
5. 钱包为该内容提交链上评分交易
6. Nibgate 为评分事件建立索引，将其与解锁证明匹配，并结合分析上下文更新声誉

公开内容声誉可显示为 0.0-5.0 星级评分。网站声誉和创作者声誉则综合内容评分、验证健康度、一致性、收据和来源质量。

创作者声誉应采用 1-100 分制，评估拥有已验证网站及其内容的钱包/账户。这意味着，创作者的信任度可以随着真实解锁、支付收据、符合资格的钱包/Agent 评分、有用的 Agent 反馈，以及可追溯至已验证来源的内容质量信号而提升。这也意味着，即使某个新作品仍在积累信任，创作者的整体声誉也可能已经很高。

本地连接流程

1. 使用钱包登录 Hub。
2. 在仪表板中添加一个站点。
3. 复制生成的小组件脚本。
4. 将其粘贴到创作者网站的 HTML 中。
5. 部署创作者网站。
6. 在 Hub 中点击验证。

小组件代码片段示例：

<script
  async
  src="https://www.nibgate.xyz/widget.js"
  data-nibgate-site="SITE_ID"
  data-nibgate-token="PUBLIC_SITE_TOKEN"
  data-nibgate-api="https://api.nibgate.xyz"
></script>

内容级注册和跟踪应通过小组件由软件包发出：

import { createGate } from '@nibgate/sdk';

const premiumGuide = createGate({
  id: "premium-guide",
  title: "Premium Guide",
  type: "article",
  price: "0.01",
  path: "/premium-guide",
  access: {
    humans: "paid",
    agents: "paid"
  },
  unlock: {
    mode: "one_time"
  }
});

premiumGuide.content();
premiumGuide.view();

await premiumGuide.unlock(async () => {
  // Run payment and server-side verification here.
  return {
    paymentId: "payment_123",
    paymentProvider: "arc-mainnet",
    txHash: "0x...",
    chainExplorerUrl: "https://arcscan.app/tx/0x...",
    revenue: 0.01,
    currency: "USDC"
  };
});

较底层的桥接仍可用于高级集成：

import { nibgate } from '@nibgate/sdk';

nibgate.unlockCompleted("premium-guide", {
  revenue: 0.01,
  currency: "USDC"
});

软件包在底层通过 window.nibgateHub 进行通信。如果创作者代码在异步小组件加载完成前运行，软件包事件会在浏览器中排队，并在小组件可用时发送。

服务端保护位于 @nibgate/sdk/server：

import { createCircleGatewayServer } from '@nibgate/sdk/server';

const nibgateServer = createCircleGatewayServer({
  secret: process.env.NIBGATE_SECRET,
  recipient: process.env.NIBGATE_SELLER_ADDRESS,
  async verifyPayment({ payment }) {
    // Plug Circle/x402 verification here.
    return Boolean(payment.paymentId);
  }
});

export const GET = nibgateServer.protect({
  id: "premium-guide",
  title: "Premium Guide",
  type: "article",
  price: "0.01",
  path: "/premium-guide"
}, async () => {
  return new Response("Premium content");
});

收益采用非托管模式。软件包／服务端流程应将付款发送到为该创作者网站配置的收款地址。一位创作者可以连接多个站点，每个站点都可以使用不同的收款方。Nibgate Hub 会存储付款／解锁记录，用于分析和记账；它不托管资金，也不提供提现流程。

收据处理会根据提供方而异：

• Circle Gateway 付款应仅在 Circle 或网关集成返回真实收据 URL 时，存储 paymentProvider: "circle-gateway"、paymentId 和 receiptUrl。
• Arc 付款应存储 paymentProvider: "arc-mainnet"（测试网使用 "arc-testnet"）、txHash、chainId，以及可选的 Arcscan 交易页面 chainExplorerUrl（https://arcscan.app/tx/0x...，测试网：https://testnet.arcscan.app/tx/0x...）。
• 如果既没有 Circle 收据 URL，也没有 Arc 区块浏览器 URL，Hub 会显示内部记录的付款 ID／哈希，而不会伪造收据。

或在标记中声明：

<article
  data-nibgate-resource
  data-nibgate-id="premium-guide"
  data-nibgate-title="Premium Guide"
  data-nibgate-type="article"
  data-nibgate-price="0.01"
>
  ...
</article>

Hub 端点：

• POST /hub/sites/register
• POST /hub/sites/:websiteId/verify
• POST /hub/track
• GET /hub/sites
• GET /hub/dashboard/content
• GET /hub/dashboard/analytics
• GET /hub/dashboard/earnings

跟踪模型

小组件不会将整个站点视为一个无法区分的整体。它可以记录：

• 加载脚本的每个路由的页面浏览量
• 页面包含 data-nibgate-resource 标记或 nibgate:* 元标签时的资源浏览量
• 已安装的 nibgate 运行时调用 window.nibgateHub.track(...) 时的软件包事件
• 与特定资源 ID 关联的解锁和付款事件

这意味着一个域名可以有许多受跟踪的资源，但 Nibgate 内容类型有意限制为 music、video、article、image 和 document。

存储模型

Hub 存储通过 Prisma 使用 PostgreSQL：

• 创作者内容仍保留在创作者网站上
• 资源元数据由小组件／软件包发出的流式事件创建或更新
• 站点、内容、分析和收益记录存储在 Postgres 中

付款

对于浏览器钱包结账，创作者访问路由必须返回 Circle Gateway 的真实 PAYMENT-REQUIRED 批处理质询。最简单且安全的设置是 createCircleGatewayServer(...)；等效的手动设置是 createNibgateServer({ paymentMode: 'circle-gateway', network: 'eip155:5042' })（主网）或 network: 'eip155:5042002'（测试网）。

收入模式（费用钱包 + 协议费用）

在 Nibgate 托管的界面（Hub 小组件结账、Subblogs）上，付款会进入每位创作者的 GatewayFeeWallet 合约，而不是创作者的 EOA。该合约不可变（无代理/管理员），将 99% 留给创作者，并在 distribute() 时将 1% 的协议费用转入金库——此规则在链上强制执行，部署时设定的上限为 5%。后台 keeper 会将已结算余额转入创作者的钱包。完整模式、图表和环境变量参考：docs/revenue-model 和 contracts/GatewayFeeWallet.sol。

NIBGATE_HOSTED_PAY=true \
NIBGATE_FEE_WALLET_FACTORY=0xYourFactoryAddress \
NIBGATE_TREASURY=0xYourTreasuryAddress \
NIBGATE_FEE_KEEPER=1 \
NIBGATE_KEEPER_PRIVATE_KEY=0xyourKeeperPrivateKey \
npm run dev

keeper 还必须保留足够的 Arc 原生 Gas 余额，以满足完整的部署与结算预估费用。对于待处理的领取/退款中继，先进行费用预估，再将 estimate * gasPrice 与 keeper 余额进行比较，并在签名或广播前安全失败，返回 keeper-gas-insufficient。请监控 keeper 并为其补充资金，留出安全余量；ERC-20 USDC 余额不能支付原生 Gas。

Circle Gateway 模式（需要本地专用的 demo/ 目录）：

NIBGATE_PAYMENT_MODE=circle-gateway \
NIBGATE_SELLER_ADDRESS=0xYourSellerWallet \
NIBGATE_BUYER_PRIVATE_KEY=0xyourBuyerPrivateKey \
NIBGATE_BUYER_CHAIN=arcTestnet \
npm run dev:demo

Gateway 余额辅助工具：

NIBGATE_PAYMENT_MODE=circle-gateway \
NIBGATE_BUYER_PRIVATE_KEY=0xyourBuyerPrivateKey \
NIBGATE_BUYER_CHAIN=arcTestnet \
npx @nibgate/cli balance

NIBGATE_PAYMENT_MODE=circle-gateway \
NIBGATE_BUYER_PRIVATE_KEY=0xyourBuyerPrivateKey \
NIBGATE_BUYER_CHAIN=arcTestnet \
npx @nibgate/cli deposit 1.0

直接通道（转账）

第二种支付通道会将 USDC 直接从买家的钱包发送到创作者的 payTo 地址——无需 Gateway 促成。浏览器结账会广播转账，并在访问重试请求中将交易哈希作为 x-nibgate-transfer-tx 提交；服务器会在链上验证已挖出的收据（USDC Transfer 日志显示转给卖家的金额至少达到价格），然后才铸造解锁凭证。收据会以 paymentProvider: 'direct-transfer' 存储。在解锁 UI 中，NibgateUnlock/useNibgateUnlock 通过 paymentRail 选项（'gateway' 或 'transfer'）在两个通道之间切换。

由于已广播的转账属于公开链上数据，重试请求还必须携带所有权证明：由付款钱包对以下内容进行 EIP-191 签名

Nibgate transfer ownership
tx:<txHash lowercased>
resource:<resource path or url>

并作为 x-nibgate-tx-owner 标头发送（transferOwnershipMessage() 会构建此字符串）。缺少证明或证明不匹配时，会返回 transfer-ownership-proof-required / transfer-owner-mismatch。自托管用户可以通过 NIBGATE_TX_OWNER_PROOF_OPTIONAL=true 选择不启用此验证；托管界面还会针对每个内容 ID 将每个 txHash 限定为只能使用一次。

import { payWithTransfer, createTransferCheckout } from '@nibgate/sdk'

await payWithTransfer(resource, {
  accessPath: '/api/nibgate/access',
  checkout: createTransferCheckout(resource, {
    sendTransfer: async ({ recipient, amount }) => /* broadcast USDC transfer, return { txHash } */
  })
})

与钱包绑定的访问权限

付费解锁与钱包绑定，而非与设备绑定。付款后，钱包即拥有由其收据支持的永久访问权限；在任何设备上重新连接钱包（并通过 SIWE 登录），服务器都会重新验证收据和封禁状态，并再次提供内容——无需重复付款。除非已连接钱包，否则解锁 UI 绝不会仅凭设备存储的证明授予访问权限；断开连接时会重新锁定（拆除载荷并清除证明）。

本地 URL

• Hub 前端：http://localhost:3001
• Hub 探索页：http://localhost:3001/explore
• Hub 后端 API：http://localhost:3000
• Subblogs 前端：http://localhost:3002
• Subblogs 后端 API：http://localhost:4000
• 示例源站：http://localhost:4301
• 演示付费路由：http://localhost:4301/hello-world
• Hub 小组件：http://localhost:3001/widget.js

先运行后端，再运行本地的软件包到 Hub 证明脚本：

npm run dev:backend
npm run e2e:nibgate