Sphere SDK

这是面向**自主经济代理（autonomous economic agents）**的 SDK。它为代理提供了身份、钱包，以及发现其他代理、与之协商并完成点对点结算的能力，同时兼具完美的隐私性和极速的最终确认特性。

使用 Sphere 的代理可以持有资产、发现交易对手、发送消息、进行原子级交易、开具发票并完成结算——所有这一切都基于点对点轨道进行。资产是自带验证证明、在各方之间直接转移的自包含载体对象。无需广播，无需 mempool，也无需 gas 拍卖。 它在浏览器、Node.js 和命令行中以相同的方式运行。

---

安装

npm install @unicitylabs/sphere-sdk
# Node.js 还需要一个 WebSocket 库:
npm install @unicitylabs/sphere-sdk ws

设计理念

在 Unicity 上，资产并非验证者轮流更新的全局数据库中的一行数据。它们是自带历史记录和有效性证明的自包含加密对象（即不记名工具），并在双方之间直接转移。

这一特性使得代理间的商业行为变得切实可行。自主代理无法在每次微交互时等待区块空间或支付 gas 拍卖费用，也不能依赖受信任的索引器来判断自己是否已收到款项——转账证明本身即是支付。Sphere 是一个客户端工具包，它将这种底层架构转化为代理真正需要的功能：身份、发现、消息传递、交易和结算。

你可以用它构建什么

功能	模块	为你的代理提供什么
身份	identity	加密身份（@nametag + secp256k1 密钥对）— HD 多地址，每个地址对应一个 nametag
支付	payments	发送和接收不记名代币
支付请求	payments	向交易对手请求资金并异步跟踪响应
发票与结算	accounting	开具发票、接收付款和处理退款 —— 商业中的开单与收款功能
发现	market	发布交易意向并搜索匹配的交易对手 —— 代理如何“找到”彼此
原子互换	swap	通过签名的互换清单和 nametag 绑定进行点对点交易 —— 无需受信中间人即可完成双向交易
直接消息	communications	基于 Nostr 的 P2P 直接消息和广播（NIP-04 加密）
群聊	groupChat	基于 NIP-29 中继的群组消息，支持角色和审核管理
代币备份	token sync	去中心化同步至 IPFS/IPNS，支持浏览器和 Node.js
dApp ↔ 钱包	Connect	用于浏览器插件集成的 ConnectClient / ConnectHost

快速入门

import { Sphere } from '@unicitylabs/sphere-sdk';
import { createBrowserProviders } from '@unicitylabs/sphere-sdk/impl/browser';
// Node.js: import { createNodeProviders } from '@unicitylabs/sphere-sdk/impl/nodejs';

// 1. 创建钱包 (testnet 仅供实验)
const { sphere, created, generatedMnemonic } = await Sphere.init({
  ...createBrowserProviders({ network: 'testnet' }),
  autoGenerate: true,   // 如果尚未存在钱包，则自动生成一个
  nametag: 'alice',     // 认领 Unicity ID @alice (通过 @alice 接收资金还需要链上铸造 — 参见 docs/UNICITY-ID.md)
});

// 2. 首次运行？向用户展示助记词以便备份。
if (created && generatedMnemonic) {
  console.log('请保存此恢复助记词:', generatedMnemonic);
}

// 3. 我是谁？
console.log('我的昵称: @' + sphere.identity?.nametag);

// 4. 向 @bob 发送 1,000,000 个基础单位 (= 1 UCT，当代币有 6 位小数时)
await sphere.payments.send({
  recipient: '@bob',
  coinId: 'UCT',       // 要发送的代币
  amount: '1000000',   // 以代币最小单位表示的金额，以字符串形式书写
});

这是一次真实的用户间转账——通过加密验证，无需你自己的后端支持。

获取测试代币。 在 testnet 上，你必须先认领一个 Unicity ID，然后从水龙头（faucet）申请代币。请参阅 Node.js 和 Browser 的快速入门指南。

核心概念

使用 Sphere SDK 只需理解以下四个概念：

• Token (代币) — 数字价值的单位（如 UCT）。用户的钱包可以持有多种不同类型的代币。
• Wallet (钱包) — 由 12 个单词的恢复助记词创建。助记词是用户备份所需的唯一凭证；丢失它意味着钱包永久丢失。
• Unicity ID — 人类可读的昵称（如 @alice），人们通过它向你转账或发送消息。每个钱包都可以认领一个。（在 SDK 的 API 中，这被称为 nametag。）
• Network (网络) — 用于构建和实验的 testnet。