@unicitylabs/sphere-sdk 0.2.3 → 0.3.0

package/README.md

@@ -9,7 +9,7 @@ A modular TypeScript SDK for Unicity wallet operations supporting both Layer 1 (
 - **L3 Payments** - Token transfers with state transition proofs
 - **Payment Requests** - Request payments with async response tracking
 - **Nostr Transport** - P2P messaging with NIP-04 encryption
-- **IPFS Storage** - Decentralized token backup with Helia
+- **IPFS Storage** - Decentralized token backup via HTTP API (browser + Node.js)
 - **Token Splitting** - Partial transfer amount calculations
 - **Multi-Address** - HD address derivation (BIP32/BIP44)
 - **TXF Serialization** - Token eXchange Format for storage and transfer
@@ -28,8 +28,8 @@ Choose your platform:
 
 | Platform | Guide | Required | Optional |
 |----------|-------|----------|----------|
-| **Browser** | [QUICKSTART-BROWSER.md](docs/QUICKSTART-BROWSER.md) | SDK only | `helia` (IPFS sync) |
-| **Node.js** | [QUICKSTART-NODEJS.md](docs/QUICKSTART-NODEJS.md) | SDK + `ws` | - |
+| **Browser** | [QUICKSTART-BROWSER.md](docs/QUICKSTART-BROWSER.md) | SDK only | IPFS sync (built-in) |
+| **Node.js** | [QUICKSTART-NODEJS.md](docs/QUICKSTART-NODEJS.md) | SDK + `ws` | IPFS sync (built-in) |
 | **CLI** | See below | SDK + `tsx` | - |
 
 ## CLI (Command Line Interface)
@@ -43,6 +43,9 @@ npm run cli -- --help
 # Initialize new wallet on testnet
 npm run cli -- init --network testnet
 
+# Initialize with nametag (mints token on-chain)
+npm run cli -- init --network testnet --nametag alice
+
 # Import existing wallet
 npm run cli -- init --mnemonic "your 24 words here"
 
@@ -52,35 +55,58 @@ npm run cli -- status
 # Check balance
 npm run cli -- balance
 
-# Show receive address
+# Fetch pending transfers and finalize unconfirmed tokens
+npm run cli -- balance --finalize
+
+# Check for incoming transfers
 npm run cli -- receive
 
-# Send tokens
-npm run cli -- send @alice 1000000
+# Check for incoming transfers and finalize unconfirmed tokens
+npm run cli -- receive --finalize
+
+# Send tokens (instant mode, default)
+npm run cli -- send @alice 1 --coin UCT --instant
+
+# Send tokens (conservative mode — collect all proofs first)
+npm run cli -- send @alice 1 --coin UCT --conservative
+
+# Request test tokens from faucet
+npm run cli -- topup
 
 # Register nametag
 npm run cli -- nametag myname
 
 # Show transaction history
 npm run cli -- history 10
+
+# Verify tokens against aggregator (detect spent tokens)
+npm run cli -- verify-balance
 ```
 
 ### Available CLI Commands
 
 | Category | Command | Description |
 |----------|---------|-------------|
-| **Wallet** | `init [--network <net>] [--mnemonic "<words>"]` | Create or import wallet |
+| **Wallet** | `init [--network <net>] [--mnemonic "<words>"] [--nametag <name>]` | Create or import wallet |
 | | `status` | Show wallet identity |
 | | `config` | Show/set configuration |
-| **Balance** | `balance` | Show L3 token balance |
-| | `tokens` | List all tokens |
+| **Profiles** | `wallet list` | List all wallet profiles |
+| | `wallet use <name>` | Switch to a wallet profile |
+| | `wallet create <name> [--network <net>]` | Create a new wallet profile |
+| | `wallet delete <name>` | Delete a wallet profile |
+| | `wallet current` | Show current wallet profile |
+| **Balance** | `balance [--finalize]` | Show L3 token balance (--finalize: fetch pending + resolve) |
+| | `tokens` | List all tokens with details |
 | | `l1-balance` | Show L1 (ALPHA) balance |
-| **Transfers** | `send <recipient> <amount>` | Send tokens |
-| | `receive` | Show address for receiving |
+| | `topup [coin] [amount]` | Request test tokens from faucet |
+| | `verify-balance [--remove] [-v]` | Verify tokens against aggregator |
+| **Transfers** | `send <to> <amount> [--coin SYM] [--instant\|--conservative]` | Send tokens |
+| | `receive [--finalize]` | Check for incoming transfers |
 | | `history [limit]` | Show transaction history |
 | **Nametags** | `nametag <name>` | Register a nametag |
 | | `nametag-info <name>` | Lookup nametag info |
 | | `my-nametag` | Show current nametag |
+| | `nametag-sync` | Re-publish nametag with chainPubkey |
 | **Utils** | `generate-key` | Generate random key |
 | | `to-human <amount>` | Convert to human readable |
 | | `parse-wallet <file>` | Parse wallet file |
@@ -709,7 +735,7 @@ The SDK includes browser-ready provider implementations:
 | `LocalStorageProvider` | Browser localStorage with SSR fallback |
 | `NostrTransportProvider` | Nostr relay messaging with NIP-04 |
 | `UnicityAggregatorProvider` | Unicity aggregator for state proofs |
-| `IpfsStorageProvider` | Helia-based IPFS with HTTP fallback |
+| `IpfsStorageProvider` | HTTP-based IPFS/IPNS storage (cross-platform) |
 
 ## Node.js Providers
 
@@ -858,20 +884,31 @@ The SDK supports multiple token sync backends that can be enabled independently:
 
 | Backend | Status | Description |
 |---------|--------|-------------|
-| `ipfs` | ✅ Ready | Decentralized IPFS/IPNS with Helia browser DHT |
+| `ipfs` | ✅ Ready | HTTP-based IPFS/IPNS storage (browser + Node.js) |
 | `mongodb` | 🚧 Planned | MongoDB for centralized token storage |
 | `file` | 🚧 Planned | Local file system (Node.js) |
 | `cloud` | 🚧 Planned | Cloud storage (AWS S3, GCP, Azure) |
 
 ```typescript
-// Enable IPFS sync with custom gateways
+// Browser: enable IPFS sync
 const providers = createBrowserProviders({
   network: 'testnet',
   tokenSync: {
     ipfs: {
       enabled: true,
       additionalGateways: ['https://my-gateway.com'],
-      useDht: true,  // Enable browser DHT (Helia)
+    },
+  },
+});
+
+// Node.js: enable IPFS sync
+const providers = createNodeProviders({
+  network: 'testnet',
+  dataDir: './wallet-data',
+  tokensDir: './tokens-data',
+  tokenSync: {
+    ipfs: {
+      enabled: true,
     },
   },
 });
@@ -960,12 +997,12 @@ const { sphere } = await Sphere.init({
 After `Sphere.init()` is called, you can add/remove token storage providers dynamically:
 
 ```typescript
-import { createIpfsStorageProvider } from '@unicitylabs/sphere-sdk/impl/browser/ipfs';
+import { createBrowserIpfsStorageProvider } from '@unicitylabs/sphere-sdk/impl/browser/ipfs';
+// For Node.js: import { createNodeIpfsStorageProvider } from '@unicitylabs/sphere-sdk/impl/nodejs/ipfs';
 
 // Add a new provider at runtime (e.g., user enables IPFS sync in settings)
-const ipfsProvider = createIpfsStorageProvider({
-  gateways: ['https://ipfs.io'],
-  useDht: true,
+const ipfsProvider = createBrowserIpfsStorageProvider({
+  gateways: ['https://my-ipfs-node.com'],
 });
 
 await sphere.addTokenStorageProvider(ipfsProvider);
@@ -1077,7 +1114,7 @@ function getRelayStatuses() {
 
 ## Nametags
 
-Nametags provide human-readable addresses (e.g., `@alice`) for receiving payments.
+Nametags provide human-readable addresses (e.g., `@alice`) for receiving payments. Valid formats: lowercase alphanumeric with `_` or `-` (3–20 chars), or E.164 phone numbers (e.g., `+14155552671`). Input is normalized to lowercase automatically.
 
 > **Important:** Nametags are required to use the testnet faucet. Register a nametag before requesting test tokens.
 
@@ -1211,6 +1248,10 @@ const bobTag = sphere.getNametagForAddress(1);    // 'bob'
 
 ---
 
+See [IPFS Storage Guide](docs/IPFS-STORAGE.md) for complete IPFS/IPNS documentation including configuration, caching, merge rules, and troubleshooting.
+
+---
+
 ## Known Limitations / TODO
 
 ### Wallet Encryption