@unicitylabs/sphere-sdk 0.2.1 → 0.2.3

package/README.md

@@ -152,7 +152,7 @@ const providers = createBrowserProviders({
   oracle: { url: 'https://custom-aggregator.example.com' }, // custom oracle
 });
 
-// Enable L1 with network defaults
+// L1 is enabled by default — customize if needed
 const providers = createBrowserProviders({
   network: 'testnet',
   l1: { enableVesting: true },  // uses testnet electrum URL automatically
@@ -332,17 +332,20 @@ sphere.payments.onPaymentRequest((request) => {
 Access L1 payments through `sphere.payments.l1`:
 
 ```typescript
-// L1 configuration is optional (has defaults)
+// L1 is enabled by default with lazy Fulcrum connection.
+// Connection to Fulcrum is deferred until first L1 operation.
 const { sphere } = await Sphere.init({
   ...providers,
   autoGenerate: true,
-  l1: {
-    electrumUrl: 'wss://fulcrum.alpha.unicity.network:50004',  // default
-    defaultFeeRate: 10,  // sat/byte, default
-    enableVesting: true, // default
-  },
+  // L1 config is optional — defaults are applied automatically:
+  // electrumUrl: network-specific (mainnet: fulcrum.alpha.unicity.network)
+  // defaultFeeRate: 10 sat/byte
+  // enableVesting: true
 });
 
+// To explicitly disable L1:
+// const { sphere } = await Sphere.init({ ...providers, l1: null });
+
 // Get L1 balance
 const balance = await sphere.payments.l1.getBalance();
 console.log('L1 Balance:', balance.total);
@@ -847,14 +850,6 @@ const providers = createBrowserProviders({
   },
 });
 
-// Enable multiple sync backends
-const providers = createBrowserProviders({
-  network: 'mainnet',
-  tokenSync: {
-    ipfs: { enabled: true, useDht: true },
-    cloud: { enabled: true, provider: 'aws', bucket: 'my-backup' },  // future
-  },
-});
 ```
 
 ## Token Sync Backends
@@ -864,7 +859,7 @@ The SDK supports multiple token sync backends that can be enabled independently:
 | Backend | Status | Description |
 |---------|--------|-------------|
 | `ipfs` | ✅ Ready | Decentralized IPFS/IPNS with Helia browser DHT |
-| `mongodb` | ✅ Ready | MongoDB for centralized token storage |
+| `mongodb` | 🚧 Planned | MongoDB for centralized token storage |
 | `file` | 🚧 Planned | Local file system (Node.js) |
 | `cloud` | 🚧 Planned | Cloud storage (AWS S3, GCP, Azure) |
 
@@ -880,29 +875,6 @@ const providers = createBrowserProviders({
     },
   },
 });
-
-// Enable MongoDB sync
-const providers = createBrowserProviders({
-  network: 'mainnet',
-  tokenSync: {
-    mongodb: {
-      enabled: true,
-      uri: 'mongodb://localhost:27017',
-      database: 'sphere_wallet',
-      collection: 'tokens',
-    },
-  },
-});
-
-// Multiple backends for redundancy
-const providers = createBrowserProviders({
-  tokenSync: {
-    ipfs: { enabled: true },
-    mongodb: { enabled: true, uri: 'mongodb://localhost:27017', database: 'wallet' },
-    file: { enabled: true, directory: './tokens', format: 'txf' },
-    cloud: { enabled: true, provider: 'aws', bucket: 'wallet-backup' },
-  },
-});
 ```
 
 ## Custom Token Storage Provider
@@ -985,32 +957,32 @@ const { sphere } = await Sphere.init({
 
 ## Dynamic Provider Management (Runtime)
 
-After `Sphere.init()` is called, you can add/remove token storage providers dynamically through UI:
+After `Sphere.init()` is called, you can add/remove token storage providers dynamically:
 
 ```typescript
-import { createMongoDbStorageProvider } from './my-mongodb-provider';
+import { createIpfsStorageProvider } from '@unicitylabs/sphere-sdk/impl/browser/ipfs';
 
-// Add a new provider at runtime (e.g., user enables MongoDB sync in settings)
-const mongoProvider = createMongoDbStorageProvider({
-  uri: 'mongodb://localhost:27017',
-  database: 'sphere_wallet',
+// Add a new provider at runtime (e.g., user enables IPFS sync in settings)
+const ipfsProvider = createIpfsStorageProvider({
+  gateways: ['https://ipfs.io'],
+  useDht: true,
 });
 
-await sphere.addTokenStorageProvider(mongoProvider);
+await sphere.addTokenStorageProvider(ipfsProvider);
 
 // Provider is now active and will be used in sync operations
 
 // Check if provider exists
-if (sphere.hasTokenStorageProvider('mongodb-token-storage')) {
-  console.log('MongoDB sync is enabled');
+if (sphere.hasTokenStorageProvider('ipfs-token-storage')) {
+  console.log('IPFS sync is enabled');
 }
 
 // Get all active providers
 const providers = sphere.getTokenStorageProviders();
 console.log('Active providers:', Array.from(providers.keys()));
 
-// Remove a provider (e.g., user disables MongoDB sync)
-await sphere.removeTokenStorageProvider('mongodb-token-storage');
+// Remove a provider (e.g., user disables IPFS sync)
+await sphere.removeTokenStorageProvider('ipfs-token-storage');
 
 // Listen for per-provider sync events
 sphere.on('sync:provider', (event) => {
@@ -1026,25 +998,6 @@ sphere.on('sync:provider', (event) => {
 await sphere.payments.sync();
 ```
 
-### Multiple Providers Example
-
-```typescript
-// User configures multiple sync backends via UI
-const ipfsProvider = createIpfsStorageProvider({ gateways: ['https://ipfs.io'] });
-const mongoProvider = createMongoDbStorageProvider({ uri: 'mongodb://...' });
-const s3Provider = createS3StorageProvider({ bucket: 'wallet-backup' });
-
-// Add all providers
-await sphere.addTokenStorageProvider(ipfsProvider);
-await sphere.addTokenStorageProvider(mongoProvider);
-await sphere.addTokenStorageProvider(s3Provider);
-
-// Sync syncs with ALL active providers
-// If one fails, others continue (fault-tolerant)
-const result = await sphere.payments.sync();
-console.log(`Synced: +${result.added} -${result.removed}`);
-```
-
 ## Dynamic Relay Management
 
 Nostr relays can be added or removed at runtime through the transport provider: