sphere-sdk

环境要求

• Node.js 环境与 npm（安装 npm 包）
• Browser 平台仅需 SDK；Node.js 平台还需额外安装 ws
• TypeScript 项目（示例代码为 TypeScript/ESM 导入）
• 可访问 testnet2 网关与 wallet-api 服务的网络环境

安装与启动步骤

1. 1安装 SDK

   通过 npm 安装官方包 @unicitylabs/sphere-sdk，这是唯一给出的安装命令，无其他搭建步骤。

   npm install @unicitylabs/sphere-sdk

   复制

2. 2Node.js 补装 ws

   若在 Node.js 端使用，README 平台表要求 SDK 之外再装 ws；浏览器端不需要。

   npm install ws

   复制

3. 3创建基础 Providers

   用 createBrowserProviders 构建 base（存储+传输+oracle）。network 必填且无默认值，oracle.apiKey 是公开的 testnet2 密钥。

   import { createBrowserProviders } from '@unicitylabs/sphere-sdk/impl/browser';
   
   const base = createBrowserProviders({
     network: 'testnet',                                          // testnet2 的别名
     oracle: { apiKey: 'sk_ddc3cfcc001e4a28ac3fad7407f99590' },   // 公开 testnet2 密钥
   });

   复制

4. 4附加 wallet-api 配置

   必须再用 createWalletApiProviders 挂上 wallet-api 传输配置，资金只走这条通道；漏掉会让 Sphere.init 抛 INVALID_CONFIG。

   import { createWalletApiProviders } from '@unicitylabs/sphere-sdk/impl/shared/wallet-api';
   
   const providers = createWalletApiProviders(base, {
     baseUrl: 'https://wallet-api.unicity.network',
     network: 'testnet2',
     deviceId: 'my-stable-device-id',   // 请持久化，避免每次启动重新认证
   });

   复制

5. 5初始化钱包

   Sphere.init 会自动创建钱包；若返回 created 与 generatedMnemonic，务必保存助记词，这是唯一恢复凭证。

   import { Sphere } from '@unicitylabs/sphere-sdk';
   
   const { sphere, created, generatedMnemonic } = await Sphere.init({
     ...providers,
     autoGenerate: true,
   });
   if (created && generatedMnemonic) {
     console.log('SAVE THIS RECOVERY PHRASE:', generatedMnemonic);
   }

   复制

6. 6发送与接收支付

   amount 必须是十进制字符串，不能传 JS number；收件人需有已发布身份，否则报 INVALID_RECIPIENT。

   const result = await sphere.payments.send({
     recipient: '@alice',
     amount: '1000000',
     coinId: 'UCT',
     memo: 'hello',
   });
   console.log(result.status);   // 'completed'
   
   const { transfers } = await sphere.payments.receive();
   sphere.on('transfer:incoming', (t) => console.log('received from', t.senderNametag));
   
   console.log(await sphere.payments.assets());

   复制

关键配置

如何确认成功

Sphere.init 正常返回 sphere 且未抛 INVALID_CONFIG；send 返回 status 为 'completed'，sphere.payments.assets() 能列出资产。

常见问题

注意事项

• 必须有两层 provider：base（存储+传输+oracle）加上 wallet-api 传输配置，只做前者会直接失败。
• network 是必填项，没有默认值；testnet 只是 testnet2 的别名，v1 相关网络（如 goggregator-test、dev）已移除。
• 自动生成的助记词只出现一次，请立即离线保存；私钥留在本地，后端只负责托管库存。
• deviceId 要持久化保存，否则每次启动都需要重新认证。