@unicitylabs/sphere-sdk 0.1.5 → 0.1.7

package/README.md

@@ -109,8 +109,8 @@ if (created && generatedMnemonic) {
   console.log('Save this mnemonic:', generatedMnemonic);
 }
 
-// Get identity
-console.log('Address:', sphere.identity?.l1Address);
+// Get identity (L3 DIRECT address is primary)
+console.log('Address:', sphere.identity?.directAddress);
 
 // Check balance
 const balance = await sphere.payments.getBalance();
@@ -155,6 +155,28 @@ const providers = createBrowserProviders({
 });
 ```
 
+## Testnet Faucet
+
+To get test tokens on testnet, you **must first register a nametag**:
+
+```typescript
+// 1. Create wallet and register nametag
+const { sphere } = await Sphere.init({
+  ...createBrowserProviders({ network: 'testnet' }),
+  autoGenerate: true,
+  nametag: 'myname',  // Register @myname
+});
+
+// 2. Request tokens from faucet using nametag
+const response = await fetch('https://faucet.unicity.network/api/v1/faucet/request', {
+  method: 'POST',
+  headers: { 'Content-Type': 'application/json' },
+  body: JSON.stringify({ unicityId: 'myname', coin: 'unicity', amount: 100 }),
+});
+```
+
+> **Note:** The faucet requires a registered nametag. Requests without a valid nametag will fail.
+
 ## Multi-Address Support
 
 The SDK supports HD (Hierarchical Deterministic) wallets with multiple addresses:
@@ -187,20 +209,22 @@ console.log(addr2.address, addr2.publicKey);
 
 ### Identity Properties
 
+**Important:** L3 (DIRECT address) is the primary address for the Unicity network. L1 address is only used for ALPHA blockchain operations.
+
 ```typescript
 interface Identity {
   chainPubkey: string;         // 33-byte compressed secp256k1 public key (for L3 chain)
-  l1Address: string;           // L1 address (alpha1...)
-  directAddress?: string;      // L3 DIRECT address (DIRECT://...)
+  directAddress?: string;      // L3 DIRECT address (DIRECT://...) - PRIMARY ADDRESS
+  l1Address: string;           // L1 address (alpha1...) - for ALPHA blockchain only
   ipnsName?: string;           // IPNS name for token sync
   nametag?: string;            // Registered nametag (@username)
 }
 
-// Access identity
-console.log(sphere.identity?.l1Address);        // alpha1qw3e...
-console.log(sphere.identity?.directAddress);    // DIRECT://0000be36...
+// Access identity - use directAddress as primary
+console.log(sphere.identity?.directAddress);    // DIRECT://0000be36... (PRIMARY)
+console.log(sphere.identity?.nametag);          // alice (human-readable)
+console.log(sphere.identity?.l1Address);        // alpha1qw3e... (L1 only)
 console.log(sphere.identity?.chainPubkey);      // 02abc123... (33-byte compressed)
-console.log(sphere.identity?.nametag);          // alice
 ```
 
 ### Address Change Event
@@ -1057,6 +1081,8 @@ function getRelayStatuses() {
 
 Nametags provide human-readable addresses (e.g., `@alice`) for receiving payments.
 
+> **Important:** Nametags are required to use the testnet faucet. Register a nametag before requesting test tokens.
+
 > **Note:** Nametag minting requires an aggregator API key for proof verification. Configure it via the `oracle.apiKey` option when creating providers. Contact Unicity to obtain an API key.
 
 ### Registering a Nametag

package/dist/core/index.cjs

@@ -2312,7 +2312,7 @@ var LIMITS = {
 };
 
 // types/txf.ts
-var ARCHIVED_PREFIX = "_archived_";
+var ARCHIVED_PREFIX = "archived-";
 var FORKED_PREFIX = "_forked_";
 var RESERVED_KEYS = ["_meta", "_nametag", "_tombstones", "_invalidatedNametags", "_outbox", "_mintOutbox", "_sent", "_invalid", "_integrity"];
 function isTokenKey(key) {
@@ -3261,16 +3261,14 @@ var PaymentsModule = class {
         const result = await provider.load();
         if (result.success && result.data) {
           this.loadFromStorageData(result.data);
-          this.log(`Loaded from provider ${id}: ${this.tokens.size} tokens`);
+          this.log(`Loaded metadata from provider ${id}`);
           break;
         }
       } catch (err) {
         console.error(`[Payments] Failed to load from provider ${id}:`, err);
       }
     }
-    if (this.tokens.size === 0) {
-      await this.loadTokensFromFileStorage();
-    }
+    await this.loadTokensFromFileStorage();
     await this.loadNametagFromFileStorage();
     const historyData = await this.deps.storage.get(STORAGE_KEYS_ADDRESS.TRANSACTION_HISTORY);
     if (historyData) {
@@ -3908,7 +3906,8 @@ var PaymentsModule = class {
     for (const [providerId, provider] of providers) {
       if (!provider.listTokenIds || !provider.getToken) continue;
       try {
-        const tokenIds = await provider.listTokenIds();
+        const allIds = await provider.listTokenIds();
+        const tokenIds = allIds.filter((id) => id.startsWith("token-"));
         this.log(`Found ${tokenIds.length} token files in ${providerId}`);
         for (const tokenId of tokenIds) {
           try {
@@ -3959,9 +3958,7 @@ var PaymentsModule = class {
         console.warn(`[Payments] Failed to load tokens from ${providerId}:`, error);
       }
     }
-    if (this.tokens.size > 0) {
-      await this.save();
-    }
+    this.log(`Loaded ${this.tokens.size} tokens from file storage`);
   }
   /**
    * Update an existing token
@@ -4822,9 +4819,9 @@ var PaymentsModule = class {
     return data ? JSON.parse(data) : [];
   }
   async createStorageData() {
-    const tokens = Array.from(this.tokens.values());
     return await buildTxfStorageData(
-      tokens,
+      [],
+      // Empty - active tokens stored as token-xxx files
       {
         version: 1,
         address: this.deps.identity.l1Address,