511 lines
14 KiB
Markdown
511 lines
14 KiB
Markdown
# 链上分账支付平台
|
||
|
||
`支付` `DeFi` `NFC` `智能体` `分账` `Web3`
|
||
|
||
# SplitHub
|
||
|
||
> 面向朋友、商家和现场场馆的链上 NFC 碰一碰支付。
|
||
|
||
SplitHub 让加密支付变得轻松自然、即时便捷。
|
||
|
||
你可以与朋友分摊账单、向商家付款，并通过 Arx Halo NFC 芯片实现刷卡支付，同时 DeFi 智能体在后台处理流动性。最终呈现的是一种快速、熟悉的支付体验，无需用户将闲置资金提前存入钱包等待消费。
|
||
|
||
产品背后最核心的理念很简单：
|
||
|
||
**芯片用于授权，而非存储。**
|
||
|
||
即使芯片丢失，用户也不会损失资金。资本始终由钱包和智能体控制，持续产生收益，并在真实支付发生时即时划拨。
|
||
|
||
---
|
||
|
||
## 已上线产品功能
|
||
|
||
SplitHub 目前围绕以下几个清晰的产品模块构建：
|
||
|
||
| 功能 | 用户入口 | 已实现内容 |
|
||
| --- | --- | --- |
|
||
| **商店** | `/store` | 店铺创建、商品目录、结账、收益分成、数据分析及自治店铺管理智能体 |
|
||
| **DeFi** | `/defi` | 基于 Vincent 的金库管理，支持 Aave 存款、提款及计划驱动操作 |
|
||
| **智能体支付** | `/agents-pay` | 即时支付就绪、碰一碰限额及流动性调度，用户无需持有闲置余额即可付款 |
|
||
| **账单分摊** | `/splits`、`/settle`、`/requests` | 群组消费、余额管理、付款请求、圈子及结算 |
|
||
| **碰一碰支付** | 结账与结算流程 | Arx Halo 芯片授权，覆盖消费者与商家支付路径 |
|
||
|
||
这些模块在底层通过 **智能体支付** 相互连接：
|
||
|
||
- 用户资本可持续在 DeFi 中产生收益
|
||
- 应用实时检查支付就绪状态
|
||
- 智能体可在有效支付前即时划转资金
|
||
- 即使钱包未预存可用余额，用户也能碰一碰完成支付
|
||
|
||
这是核心产品优势：**资本效率与结账速度两全其美**。
|
||
|
||
---
|
||
|
||
## 为什么值得关注
|
||
|
||
大多数加密支付产品让用户在便利性与安全性之间二选一：
|
||
|
||
- 将资金预存入消费钱包，接受闲置资本风险
|
||
- 将资金存放他处，接受繁琐的结账体验
|
||
|
||
SplitHub 消除了这一两难困境。
|
||
|
||
使用 SplitHub：
|
||
|
||
- 用户可社交化地分摊账单、清算债务
|
||
- 商家可接受 NFC 碰一碰支付
|
||
- 活动运营者可运营摊位和场馆商业
|
||
- 资金可在 DeFi 中持续产生 APY，直到真正需要时再划出
|
||
- 芯片无需被当作存有大量价值的钱包来对待
|
||
|
||
这是一种更贴近现实的加密支付思维模型：
|
||
|
||
**先碰一碰，按需划款。**
|
||
|
||
---
|
||
|
||
## 功能亮点
|
||
|
||
### 1. 商店
|
||
|
||
商店是完整的产品模块，而非单纯的演示结账页面。
|
||
|
||
- 创建关联活动网络的商家店面
|
||
- 管理商品目录和库存
|
||
- 将结账收益在管理员与运营钱包之间分成
|
||
- 查看营收、失败订单、低库存商品和畅销品
|
||
- 挂载可监控并响应店铺状态的自治管理智能体
|
||
|
||
这使 SplitHub 成为商家、摊位和场馆网络的商业运营层。
|
||
|
||
### 2. DeFi
|
||
|
||
DeFi 模块为金库层提供了专属的用户体验。
|
||
|
||
- 接入 Vincent 钱包基础设施
|
||
- 查看 Privy、智能体及 Aave 余额
|
||
- 生成计划驱动的资本配置决策
|
||
- 从用户钱包向智能体钱包充值
|
||
- 将闲置 USDC 部署至 Aave
|
||
- 需要流动性时将资本提取回来
|
||
|
||
目标很简单：让支付资本保持活跃而非闲置。
|
||
|
||
### 3. 智能体支付
|
||
|
||
智能体支付是连接结账与 DeFi 的机制。
|
||
|
||
- 评估用户是否能覆盖其配置的碰一碰限额
|
||
- 综合考量芯片关联钱包余额、智能体流动性及 Aave 储备
|
||
- 实时决策是否需要充值或提款
|
||
- 在支付前即时划转资金
|
||
- 让用户无需预存专用消费钱包即可碰一碰支付
|
||
|
||
这是产品的核心差异化优势。
|
||
|
||
### 4. 社交与碰一碰支付
|
||
|
||
SplitHub 保留了原有的社交支付体验：
|
||
|
||
- 创建共享消费
|
||
- 追踪朋友间的余额
|
||
- 发送付款请求
|
||
- 通过圈子自动分摊消费
|
||
- 一键碰一碰完成结算
|
||
|
||
同样的碰一碰原语也驱动商家和场馆结账。
|
||
|
||
---
|
||
|
||
## 智能体支付工作原理
|
||
|
||
高层次流程如下：
|
||
|
||
1. 用户发起碰一碰支付。
|
||
2. SplitHub 验证支付上下文和消费规则。
|
||
3. 智能体检查支付钱包是否已能覆盖本次交易。
|
||
4. 若不能，系统评估可用流动余额及 DeFi 储备。
|
||
5. 即时划转资金。
|
||
6. 以相同的碰一碰体验完成支付。
|
||
|
||
这赋予 SplitHub 两项重要产品特性：
|
||
|
||
- **安全性**：资金不会永久存放在芯片上
|
||
- **效率性**：闲置资本可持续产生 APY，直至支付时刻
|
||
|
||
---
|
||
|
||
## 核心用户流程
|
||
|
||
### 账单分摊
|
||
|
||
用户通过 Privy 登录，创建消费记录，添加参与者，并通过 Supabase 实时查看余额变化。结算时，碰一碰授权支付，链上清算债务。
|
||
|
||
### 向商家付款
|
||
|
||
用户进入为商店、摊位和场馆运营者设计的轻量结账流程。SplitHub 处理支付逻辑，同时保持交互足够简洁以适应真实使用场景。
|
||
|
||
### 碰一碰支付
|
||
|
||
Arx Halo 芯片签署支付意图。应用协调交易流程、钱包状态及就绪检查，使碰一碰感觉即时流畅。
|
||
|
||
### 保持资金高效运转
|
||
|
||
SplitHub 无需强制用户持有无效的结账余额，可将闲置资本路由至 DeFi 并在需要时取回。这通过 **DeFi** 和 **智能体支付** 模块对外呈现。
|
||
|
||
---
|
||
|
||
## 当前产品覆盖范围
|
||
|
||
本仓库中的活跃产品模块包括：
|
||
|
||
- 商店仪表板、商品目录、结账、数据分析及分成收款订单流程
|
||
- 店铺管理智能体、智能体日志、验证及补货自动化
|
||
- 通过 Vincent + Aave 进行 DeFi 存款和提款
|
||
- 智能体金库、支付就绪、碰一碰限额及即时资金划拨
|
||
- 分摊仪表板和余额追踪
|
||
- 单方及多方结算流程
|
||
- 带可分享链接的付款请求
|
||
- 圈子自动分摊
|
||
- 积分 / 场馆支付界面
|
||
- 活动和摊位支付
|
||
- 覆盖社交与商家流程的碰一碰芯片授权
|
||
|
||
---
|
||
|
||
## DeFi 功能
|
||
|
||
本仓库中的 `DeFi` 模块由真实的规划和执行服务支撑，而非静态的资产组合界面。
|
||
|
||
已实现的 DeFi 能力包括：
|
||
|
||
- Vincent 会话处理与钱包发现
|
||
- 跨用户钱包、智能体钱包和 Aave 储备的金库快照
|
||
- 结合 OpenAI 与确定性回退验证的计划驱动持仓逻辑
|
||
- Privy 到智能体的充值交易构建
|
||
- Aave 存款和提款流程
|
||
- 用于资本配置的场景对比与推理界面
|
||
|
||
在产品层面，这是 SplitHub 让资金在等待下一次支付期间持续增值的部分。
|
||
|
||
---
|
||
|
||
## 智能体支付功能
|
||
|
||
`智能体支付` 是支付就绪层，使碰一碰体验即使在用户支付钱包中没有可用余额时也能保持流畅。
|
||
|
||
已实现的智能体支付能力包括：
|
||
|
||
- 用户级碰一碰限额配置
|
||
- 综合芯片钱包余额、智能体流动余额和 Aave 可提款储备的就绪检查
|
||
- 用于预估支付金额的近期消费信号分析
|
||
- 可在现有余额、流动智能体资金和 Aave 提款之间决策的即时支付准备
|
||
- 支付资金说明与推理界面
|
||
- 集成到结算和支付流程，用户可先碰一碰再按需划款
|
||
|
||
这是使产品与众不同的功能：**用户无需为结账就绪而暴露闲置资本即可完成支付**。
|
||
|
||
---
|
||
|
||
## 商店平台功能
|
||
|
||
商店层不只是 UI 演示。`packages/nextjs/app/api/stores` 中的 API 为 SplitHub 的结账和智能体工作流实现了真实的商家运营后端。
|
||
|
||
### 商店 API
|
||
|
||
已实现的商店能力包括：
|
||
|
||
- 含管理员、运营者、收益分成、代币和智能体配置的店铺创建
|
||
- 基于钱包的运营者店铺仪表板查询
|
||
- 单店营收、订单质量、低库存商品和畅销品分析
|
||
- 商品目录创建、列表和更新
|
||
- 实时购物车的结账报价生成
|
||
- 含两段签名收款的结账确认（运营者和管理员各一段）
|
||
- 待处理、已完成和失败订单的生命周期管理
|
||
- 成功结账后自动扣减库存
|
||
|
||
这使商家流程超越了"碰一碰支付"，支持**分成收款、运营可视化和库存感知结账**。
|
||
|
||
### 商店智能体控制
|
||
|
||
商店 API 还暴露了智能体管理原语：
|
||
|
||
- 为店铺创建管理智能体
|
||
- 暂停或重新激活该智能体
|
||
- 查看有助于判断何时需要自治运行的分析数据
|
||
|
||
这意味着 SplitHub 不仅支持商家支付，还为每家店铺提供了运营自动化层。
|
||
|
||
---
|
||
|
||
## Trigger 驱动的自动化
|
||
|
||
`packages/nextjs/trigger` 中的后台任务是新产品方向的重要组成部分。
|
||
|
||
### 自治店铺运行
|
||
|
||
`store-agent-run.ts` 为指定店铺执行自治运行并记录：
|
||
|
||
- 哪家店铺运行了
|
||
- 运行 ID 和状态
|
||
- 采取了多少行动
|
||
- 本次运行产生的决策摘要
|
||
|
||
这是将店铺智能体从配置对象转变为真正能够行动的执行路径。
|
||
|
||
### 定时健康扫描
|
||
|
||
`store-health-scan.ts` 按计划运行，检查活跃店铺智能体的运营问题，例如：
|
||
|
||
- 低库存商品
|
||
- 失败订单
|
||
|
||
当店铺需要关注时，扫描会自动排队执行后台店铺智能体运行。若一切正常，则跳过该店铺。从产品角度看，这意味着 SplitHub 现在支持**商家监控和干预循环**，而不只是结账。
|
||
|
||
商店 API 层与 Trigger 任务共同为产品增添了新维度：
|
||
|
||
**SplitHub 正在成为具备自治运营能力的商业平台，而非仅仅是碰一碰支付前端。**
|
||
|
||
---
|
||
|
||
## 架构
|
||
|
||
SplitHub 是一个全栈 Monorepo。
|
||
|
||
### 前端
|
||
|
||
- Next.js
|
||
- React
|
||
- Tailwind CSS
|
||
- DaisyUI
|
||
- Zustand
|
||
- Wagmi / Viem
|
||
- Privy 认证与嵌入式钱包
|
||
|
||
### 支付与 NFC
|
||
|
||
- Arx Halo 芯片签名
|
||
- EIP-712 风格授权流程
|
||
- 直接钱包提交支付
|
||
|
||
### 后端与数据
|
||
|
||
- Supabase Postgres
|
||
- Supabase 实时订阅
|
||
- 支付、商店、活动和智能体操作的应用 API 路由
|
||
- 商品目录管理、数据分析、结账和智能体控制的商店 API
|
||
- 付款请求、结算、碰一碰限额和 Vincent 金库端点
|
||
|
||
### 智能合约
|
||
|
||
- Foundry
|
||
- Solidity
|
||
- OpenZeppelin 合约
|
||
- Base Sepolia 部署目标
|
||
|
||
### 智能体与 DeFi 层
|
||
|
||
- Vincent 钱包基础设施
|
||
- Aave 资本存款
|
||
- OpenAI 驱动的规划与店铺智能体工作流
|
||
- Trigger.dev 店铺智能体后台任务
|
||
- 定时店铺健康扫描与自治运行编排
|
||
- 即时支付资金划拨与就绪评估
|
||
|
||
---
|
||
|
||
## 仓库结构
|
||
|
||
```text
|
||
packages/
|
||
nextjs/
|
||
app/ Next.js 应用路由和 API 端点
|
||
components/ 分摊、积分、活动、商店、结算等产品 UI
|
||
hooks/ 钱包、芯片、结算和 Vincent 钩子
|
||
services/ 产品逻辑、商店服务、DeFi、金库、通知
|
||
lib/ 共享区块链、Supabase 和 Vincent 工具函数
|
||
supabase/ Schema 参考和迁移文件
|
||
|
||
foundry/
|
||
contracts/ SplitHub 合约
|
||
script/ 部署和芯片注册脚本
|
||
test/ 合约测试
|
||
```
|
||
|
||
---
|
||
|
||
## 主要合约
|
||
|
||
| 合约 | 职责 |
|
||
| --- | --- |
|
||
| `SplitHubRegistry` | 将 NFC 芯片与所有者关联 |
|
||
| `SplitHubPayments` | 支付执行与授权检查 |
|
||
| `CreditToken` | 场馆积分代币逻辑 |
|
||
|
||
---
|
||
|
||
## 快速开始
|
||
|
||
### 前置条件
|
||
|
||
- Bun `>= 1.3.8`
|
||
- Foundry
|
||
- 一个 Supabase 项目
|
||
- 一个 Privy 应用
|
||
- 可选：用于智能体支付和 DeFi 流程的 Vincent + OpenAI 凭证
|
||
|
||
### 1. 安装依赖
|
||
|
||
```bash
|
||
bun install
|
||
```
|
||
|
||
### 2. 配置前端环境变量
|
||
|
||
复制前端环境变量模板：
|
||
|
||
```bash
|
||
cp packages/nextjs/.env.example packages/nextjs/.env.local
|
||
```
|
||
|
||
重要变量：
|
||
|
||
```bash
|
||
NEXT_PUBLIC_SUPABASE_URL=...
|
||
NEXT_PUBLIC_SUPABASE_ANON_KEY=...
|
||
NEXT_PUBLIC_PRIVY_APP_ID=...
|
||
NEXT_PUBLIC_APP_URL=http://localhost:3000
|
||
|
||
RELAYER_PRIVATE_KEY=0x...
|
||
|
||
VINCENT_API_KEY=ssk_...
|
||
VINCENT_API_BASE=https://heyvincent.ai
|
||
|
||
OPENAI_API_KEY=sk_...
|
||
OPENAI_STORE_AGENT_MODEL=gpt-5.4-mini
|
||
|
||
NEXT_PUBLIC_ONESIGNAL_APP_ID=...
|
||
ONESIGNAL_REST_API_KEY=...
|
||
|
||
STORE_SUPPLIER_WEBHOOK_URL=...
|
||
STORE_SUPPLIER_SHARED_SECRET=...
|
||
STORE_SUPPLIER_TIMEOUT_MS=15000
|
||
```
|
||
|
||
### 3. 配置 Foundry 环境变量
|
||
|
||
```bash
|
||
cp packages/foundry/.env.example packages/foundry/.env
|
||
```
|
||
|
||
按需填写 RPC、验证和部署者配置。
|
||
|
||
### 4. 启动应用
|
||
|
||
在仓库根目录执行：
|
||
|
||
```bash
|
||
bun run start
|
||
```
|
||
|
||
或直接运行 Next.js 应用：
|
||
|
||
```bash
|
||
cd packages/nextjs
|
||
bun run dev
|
||
```
|
||
|
||
### 5. 可选：本地链工作流
|
||
|
||
```bash
|
||
bun run chain
|
||
bun run deploy:local
|
||
```
|
||
|
||
---
|
||
|
||
## 常用命令
|
||
|
||
### 应用
|
||
|
||
```bash
|
||
bun run start
|
||
bun run next:lint
|
||
bun run next:check-types
|
||
bun run next:build
|
||
```
|
||
|
||
### 合约
|
||
|
||
```bash
|
||
bun run chain
|
||
bun run compile
|
||
bun run test
|
||
bun run deploy:local
|
||
bun run deploy:base
|
||
```
|
||
|
||
### Trigger.dev 店铺智能体
|
||
|
||
```bash
|
||
cd packages/nextjs
|
||
bun run dev:trigger
|
||
```
|
||
|
||
---
|
||
|
||
## 推荐演示路由
|
||
|
||
若想快速了解产品，从这里开始：
|
||
|
||
- `/store`
|
||
- `/defi`
|
||
- `/agents-pay`
|
||
- `/splits`
|
||
- `/settle`
|
||
- `/credits`
|
||
- `/events`
|
||
|
||
---
|
||
|
||
## 产品说明
|
||
|
||
### 安全立场
|
||
|
||
SplitHub 的设计原则是**芯片不是金库**。
|
||
|
||
这很重要，因为：
|
||
|
||
- 丢失芯片不应意味着丢失资金
|
||
- 支付授权可以保持轻量
|
||
- 消费控制可在钱包和智能体层面执行
|
||
- 资金可存放在别处，直到真正需要支付的时刻
|
||
|
||
### 为什么 APY 在这里很重要
|
||
|
||
大多数支付产品忽视闲置资本。
|
||
|
||
SplitHub 将闲置支付资本视为可主动管理的金库。如果资金在等待下一次碰一碰，系统可以将其路由至 DeFi 并即时取回，在不降低资本效用的前提下提升支付体验。
|
||
|
||
---
|
||
|
||
## 文档
|
||
|
||
本仓库中的其他文档：
|
||
|
||
- [lit-code-dev.md](./lit-code-dev.md)
|
||
- [lit-code-usage.md](./lit-code-usage.md)
|
||
|
||
---
|
||
|
||
## 项目状态
|
||
|
||
SplitHub 是一个活跃的原型/产品构建，融合了：
|
||
|
||
- 社交消费分摊
|
||
- 商家与场馆支付
|
||
- 基于 NFC 的碰一碰授权
|
||
- 智能体支持的即时资金划拨
|
||
- DeFi 驱动的资本效率
|
||
|
||
如果你在评估本项目，理解它的最佳方式不是将其视为简单的加密结账应用，而是将其视为**一个带有智能体管理金库层的原生碰一碰支付系统**。 |