@bsv/sdk 1.6.25 → 1.7.0

package/docs/reference/storage.md

@@ -22,7 +22,7 @@ Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](
 
 ```ts
 export interface DownloadResult {
-    data: number[];
+    data: Uint8Array;
     mimeType: string | null;
 }
 ```
@@ -85,7 +85,7 @@ Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](
 
 ```ts
 export interface UploadableFile {
-    data: number[];
+    data: Uint8Array | number[];
     type: string;
 }
 ```
@@ -341,13 +341,20 @@ Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](
 ### Variable: getURLForFile
 
 ```ts
-getURLForFile = (file: number[]): string => {
-    const hash = sha256(file);
+getURLForFile = (file: Uint8Array | number[]): string => {
+    const data = file instanceof Uint8Array ? file : Uint8Array.from(file);
+    const hasher = new Hash.SHA256();
+    const chunkSize = 1024 * 1024;
+    for (let i = 0; i < data.length; i += chunkSize) {
+        const chunk = data.subarray(i, i + chunkSize);
+        hasher.update(Array.from(chunk));
+    }
+    const hash = hasher.digest();
     return getURLForHash(hash);
 }
 ```
 
-See also: [getURLForHash](./storage.md#variable-geturlforhash), [sha256](./primitives.md#variable-sha256)
+See also: [getURLForHash](./storage.md#variable-geturlforhash)
 
 Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Enums](#enums), [Variables](#variables)
 

package/docs/tutorials/uhrp-storage.md

@@ -71,7 +71,7 @@ async function basicFileUpload() {
   // Create sample file
   const fileData = new TextEncoder().encode('Hello, UHRP storage!')
   const file = {
-    data: Array.from(fileData),
+    data: fileData,
     type: 'text/plain'
   }
   
@@ -116,7 +116,7 @@ async function basicFileDownload(uhrpUrl: string) {
     
     // Convert to string if text file
     if (result.mimeType?.startsWith('text/')) {
-      const content = new TextDecoder().decode(new Uint8Array(result.data))
+      const content = new TextDecoder().decode(result.data)
       console.log('Content:', content)
     }
     
@@ -172,7 +172,7 @@ class UHRPFileManager {
     tags: string[] = []
   ): Promise<FileMetadata> {
     const file = {
-      data: Array.from(fileData),
+      data: fileData,
       type: mimeType
     }
     
@@ -217,7 +217,7 @@ class UHRPFileManager {
       console.log('File downloaded:', uhrpUrl)
       
       return {
-        data: new Uint8Array(result.data),
+        data: result.data,
         metadata
       }
     } catch (error) {
@@ -371,7 +371,7 @@ class BatchFileOperations {
     const results = await Promise.allSettled(
       files.map(async (file) => {
         const fileObj = {
-          data: Array.from(file.data),
+          data: file.data,
           type: file.type
         }
         
@@ -422,7 +422,7 @@ class BatchFileOperations {
         return {
           success: true,
           url,
-          data: new Uint8Array(result.value.data)
+          data: result.value.data
         }
       } else {
         return {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bsv/sdk",
-  "version": "1.6.25",
+  "version": "1.7.0",
   "type": "module",
   "description": "BSV Blockchain Software Development Kit",
   "main": "dist/cjs/mod.js",

package/src/identity/ContactsManager.ts

@@ -6,11 +6,32 @@ import { Transaction } from '../transaction/index.js'
 export type Contact = DisplayableIdentity & { metadata?: Record<string, any> }
 
 const CONTACT_PROTOCOL_ID: WalletProtocol = [2, 'contact']
-// Local cache key for performance
-const CONTACTS_CACHE_KEY = 'metanet-contacts'
+
+// In-memory cache for cross-platform compatibility
+class MemoryCache {
+  private readonly cache = new Map<string, string>()
+
+  getItem (key: string): string | null {
+    return this.cache.get(key) ?? null
+  }
+
+  setItem (key: string, value: string): void {
+    this.cache.set(key, value)
+  }
+
+  removeItem (key: string): void {
+    this.cache.delete(key)
+  }
+
+  clear (): void {
+    this.cache.clear()
+  }
+}
 
 export class ContactsManager {
   private readonly wallet: WalletInterface
+  private readonly cache = new MemoryCache()
+  private readonly CONTACTS_CACHE_KEY = 'metanet-contacts'
 
   constructor (wallet?: WalletInterface) {
     this.wallet = wallet ?? new WalletClient()
@@ -23,9 +44,9 @@ export class ContactsManager {
    * @returns A promise that resolves with an array of contacts
    */
   async getContacts (identityKey?: PubKeyHex, forceRefresh = false): Promise<Contact[]> {
-    // Check localStorage cache first unless forcing refresh
+    // Check in-memory cache first unless forcing refresh
     if (!forceRefresh) {
-      const cached = localStorage.getItem(CONTACTS_CACHE_KEY)
+      const cached = this.cache.getItem(this.CONTACTS_CACHE_KEY)
       if (cached != null && cached !== '') {
         try {
           const cachedContacts: Contact[] = JSON.parse(cached)
@@ -54,11 +75,12 @@ export class ContactsManager {
     const outputs = await this.wallet.listOutputs({
       basket: 'contacts',
       include: 'entire transactions',
+      includeCustomInstructions: true,
       tags
     })
 
     if (outputs.outputs == null || outputs.outputs.length === 0) {
-      localStorage.setItem(CONTACTS_CACHE_KEY, JSON.stringify([]))
+      this.cache.setItem(this.CONTACTS_CACHE_KEY, JSON.stringify([]))
       return []
     }
 
@@ -95,7 +117,7 @@ export class ContactsManager {
     }
 
     // Cache the loaded contacts
-    localStorage.setItem(CONTACTS_CACHE_KEY, JSON.stringify(contacts))
+    this.cache.setItem(this.CONTACTS_CACHE_KEY, JSON.stringify(contacts))
     const filteredContacts = identityKey != null
       ? contacts.filter(c => c.identityKey === identityKey)
       : contacts
@@ -108,9 +130,16 @@ export class ContactsManager {
    * @param metadata Optional metadata to store with the contact (ex. notes, aliases, etc)
    */
   async saveContact (contact: DisplayableIdentity, metadata?: Record<string, any>): Promise<void> {
-    // Update localStorage cache immediately
-    const cached = localStorage.getItem(CONTACTS_CACHE_KEY)
-    const contacts: Contact[] = (cached != null && cached !== '') ? JSON.parse(cached) : []
+    // Get current contacts from cache or blockchain
+    const cached = this.cache.getItem(this.CONTACTS_CACHE_KEY)
+    let contacts: Contact[]
+    if (cached != null && cached !== '') {
+      contacts = JSON.parse(cached)
+    } else {
+      // If cache is empty, get current data from blockchain
+      contacts = await this.getContacts()
+    }
+
     const existingIndex = contacts.findIndex(c => c.identityKey === contact.identityKey)
     const contactToStore: Contact = {
       ...contact,
@@ -122,7 +151,6 @@ export class ContactsManager {
     } else {
       contacts.push(contactToStore)
     }
-    localStorage.setItem(CONTACTS_CACHE_KEY, JSON.stringify(contacts))
 
     const { hmac: hashedIdentityKey } = await this.wallet.createHmac({
       protocolID: CONTACT_PROTOCOL_ID,
@@ -246,6 +274,7 @@ export class ContactsManager {
 
       if (tx == null) throw new Error('Failed to create contact output')
     }
+    this.cache.setItem(this.CONTACTS_CACHE_KEY, JSON.stringify(contacts))
   }
 
   /**
@@ -253,23 +282,34 @@ export class ContactsManager {
    * @param identityKey The identity key of the contact to remove
    */
   async removeContact (identityKey: string): Promise<void> {
-    // Update localStorage cache
-    const cached = localStorage.getItem(CONTACTS_CACHE_KEY)
+    // Update in-memory cache
+    const cached = this.cache.getItem(this.CONTACTS_CACHE_KEY)
     if (cached != null && cached !== '') {
       try {
         const contacts: Contact[] = JSON.parse(cached)
         const filteredContacts = contacts.filter(c => c.identityKey !== identityKey)
-        localStorage.setItem(CONTACTS_CACHE_KEY, JSON.stringify(filteredContacts))
+        this.cache.setItem(this.CONTACTS_CACHE_KEY, JSON.stringify(filteredContacts))
       } catch (e) {
         console.warn('Failed to update cache after contact removal:', e)
       }
     }
 
+    // Hash the identity key to use as a tag for quick lookup
+    const tags: string[] = []
+    const { hmac: hashedIdentityKey } = await this.wallet.createHmac({
+      protocolID: CONTACT_PROTOCOL_ID,
+      keyID: identityKey,
+      counterparty: 'self',
+      data: Utils.toArray(identityKey, 'utf8')
+    })
+    tags.push(`identityKey ${Utils.toHex(hashedIdentityKey)}`)
+
     // Find and spend the contact's output
     const outputs = await this.wallet.listOutputs({
       basket: 'contacts',
       include: 'entire transactions',
-      includeCustomInstructions: true
+      includeCustomInstructions: true,
+      tags
     })
 
     if (outputs.outputs == null) return

package/src/identity/__tests/IdentityClient.test.ts

@@ -352,9 +352,8 @@ describe('IdentityClient', () => {
     }
 
     beforeEach(() => {
-      // Clear localStorage mocks
-      ; (localStorage.getItem as jest.Mock).mockClear()
-        ; (localStorage.setItem as jest.Mock).mockClear()
+      // Reset wallet mocks for each test
+      jest.clearAllMocks()
     })
 
     describe('saveContact', () => {
@@ -367,12 +366,6 @@ describe('IdentityClient', () => {
 
         await identityClient.saveContact(mockContact)
 
-        // Verify cache was updated
-        expect(localStorage.setItem).toHaveBeenCalledWith(
-          'metanet-contacts',
-          JSON.stringify([mockContact])
-        )
-
         // Verify HMAC was created for tagging
         expect(walletMock.createHmac).toHaveBeenCalledWith({
           protocolID: [2, 'contact'],
@@ -389,7 +382,7 @@ describe('IdentityClient', () => {
           counterparty: 'self'
         })
 
-        // Verify transaction was created
+        // Verify new contact transaction was created
         expect(walletMock.createAction).toHaveBeenCalledWith(
           expect.objectContaining({
             description: 'Add Contact',
@@ -401,6 +394,13 @@ describe('IdentityClient', () => {
             ])
           })
         )
+
+        // Verify contact is now available from cache
+        const contacts = await identityClient.getContacts()
+        expect(contacts).toContainEqual(expect.objectContaining({
+          name: mockContact.name,
+          identityKey: mockContact.identityKey
+        }))
       })
 
       it('should save a contact with metadata', async () => {
@@ -411,36 +411,43 @@ describe('IdentityClient', () => {
 
         await identityClient.saveContact(mockContact, { notes: 'Met at conference' })
 
-        // Verify cache includes metadata
-        expect(localStorage.setItem).toHaveBeenCalledWith(
-          'metanet-contacts',
-          JSON.stringify([mockContactWithMetadata])
-        )
+        // Verify contact with metadata is available from cache
+        const contacts = await identityClient.getContacts()
+        expect(contacts).toContainEqual(expect.objectContaining({
+          name: mockContact.name,
+          identityKey: mockContact.identityKey,
+          metadata: { notes: 'Met at conference' }
+        }))
       })
 
       it('should update existing contact', async () => {
+        // First save a contact to establish it exists
+        ; (walletMock.listOutputs as jest.Mock).mockResolvedValueOnce({
+          outputs: [],
+          BEEF: []
+        })
+        await identityClient.saveContact(mockContact)
+
+        // Now mock finding the existing contact for update
         const existingOutput = {
           outpoint: 'txid.0',
           customInstructions: JSON.stringify({ keyID: 'existingKeyID' })
         }
 
-          // Mock existing contact found - return on specific query with tags
-          ; (walletMock.listOutputs as jest.Mock)
-            .mockResolvedValueOnce({
-              outputs: [existingOutput],
-              BEEF: [1, 2, 3]
-            })
+        ; (walletMock.listOutputs as jest.Mock).mockResolvedValueOnce({
+          outputs: [existingOutput],
+          BEEF: [1, 2, 3]
+        })
 
-          // Mock decrypt returning existing contact with same identityKey
-          ; (walletMock.decrypt as jest.Mock).mockResolvedValue({
-            plaintext: new TextEncoder().encode(JSON.stringify(mockContact))
-          })
+        ; (walletMock.decrypt as jest.Mock).mockResolvedValue({
+          plaintext: new TextEncoder().encode(JSON.stringify(mockContact))
+        })
 
         const updatedContact = { ...mockContact, name: 'Alice Updated' }
         await identityClient.saveContact(updatedContact)
 
-        // Since identityKey matches, should create update action
-        expect(walletMock.createAction).toHaveBeenCalledWith(
+        // Should create update action since contact exists
+        expect(walletMock.createAction).toHaveBeenLastCalledWith(
           expect.objectContaining({
             description: 'Update Contact',
             inputBEEF: [1, 2, 3],
@@ -456,34 +463,40 @@ describe('IdentityClient', () => {
 
     describe('getContacts', () => {
       it('should return cached contacts when available', async () => {
-        const cachedContacts = [mockContact]
-          ; (localStorage.getItem as jest.Mock).mockReturnValue(
-            JSON.stringify(cachedContacts)
-          )
+        // First save a contact to populate cache
+        ; (walletMock.listOutputs as jest.Mock).mockResolvedValue({
+          outputs: [],
+          BEEF: []
+        })
+        await identityClient.saveContact(mockContact)
 
+        // Clear mocks to verify cache is used
+        jest.clearAllMocks()
+
+        // Get contacts should use cache and not call wallet
         const result = await identityClient.getContacts()
 
-        expect(result).toEqual(cachedContacts)
+        expect(result).toContainEqual(expect.objectContaining({
+          name: mockContact.name,
+          identityKey: mockContact.identityKey
+        }))
         expect(walletMock.listOutputs).not.toHaveBeenCalled()
       })
 
       it('should load contacts from wallet basket when cache is empty', async () => {
-        ; (localStorage.getItem as jest.Mock).mockReturnValue(null)
-
         const mockOutput = {
           outpoint: 'txid.0',
           customInstructions: JSON.stringify({ keyID: 'mockKeyID' })
         }
 
-          ; (walletMock.listOutputs as jest.Mock).mockResolvedValue({
-            outputs: [mockOutput],
-            BEEF: [1, 2, 3]
-          })
+        ; (walletMock.listOutputs as jest.Mock).mockResolvedValue({
+          outputs: [mockOutput],
+          BEEF: [1, 2, 3]
+        })
 
-          // Mock decrypt to return the contact data directly as it would be stored
-          ; (walletMock.decrypt as jest.Mock).mockResolvedValue({
-            plaintext: new TextEncoder().encode(JSON.stringify(mockContact))
-          })
+        ; (walletMock.decrypt as jest.Mock).mockResolvedValue({
+          plaintext: new TextEncoder().encode(JSON.stringify(mockContact))
+        })
 
         const result = await identityClient.getContacts()
 
@@ -491,24 +504,30 @@ describe('IdentityClient', () => {
         expect(walletMock.listOutputs).toHaveBeenCalledWith({
           basket: 'contacts',
           include: 'entire transactions',
+          includeCustomInstructions: true,
           tags: []
         })
-        expect(localStorage.setItem).toHaveBeenCalledWith(
-          'metanet-contacts',
-          JSON.stringify([mockContact])
-        )
+
+        // Verify subsequent call uses cache
+        jest.clearAllMocks()
+        const cachedResult = await identityClient.getContacts()
+        expect(cachedResult).toEqual([mockContact])
+        expect(walletMock.listOutputs).not.toHaveBeenCalled()
       })
 
       it('should force refresh when requested', async () => {
-        const cachedContacts = [mockContact]
-          ; (localStorage.getItem as jest.Mock).mockReturnValue(
-            JSON.stringify(cachedContacts)
-          )
-
-          ; (walletMock.listOutputs as jest.Mock).mockResolvedValue({
-            outputs: [],
-            BEEF: []
-          })
+        // First populate cache
+        ; (walletMock.listOutputs as jest.Mock).mockResolvedValue({
+          outputs: [],
+          BEEF: []
+        })
+        await identityClient.saveContact(mockContact)
+
+        // Mock empty result for force refresh
+        ; (walletMock.listOutputs as jest.Mock).mockResolvedValue({
+          outputs: [],
+          BEEF: []
+        })
 
         const result = await identityClient.getContacts(undefined, true)
 
@@ -517,23 +536,30 @@ describe('IdentityClient', () => {
       })
 
       it('should filter by identity key when provided', async () => {
-        const contacts = [mockContact, { ...mockContact, identityKey: 'different-key' }]
-          ; (localStorage.getItem as jest.Mock).mockReturnValue(
-            JSON.stringify(contacts)
-          )
+        // Save two different contacts
+        ; (walletMock.listOutputs as jest.Mock).mockResolvedValue({
+          outputs: [],
+          BEEF: []
+        })
+        await identityClient.saveContact(mockContact)
+        
+        const otherContact = { ...mockContact, identityKey: 'different-key', name: 'Bob' }
+        await identityClient.saveContact(otherContact)
 
+        // Filter by specific identity key
         const result = await identityClient.getContacts(mockContact.identityKey)
 
-        expect(result).toEqual([mockContact])
+        expect(result).toEqual([expect.objectContaining({
+          name: mockContact.name,
+          identityKey: mockContact.identityKey
+        })])
+        expect(result).toHaveLength(1)
       })
 
       it('should throw error on listOutputs failure', async () => {
-        ; (localStorage.getItem as jest.Mock).mockReturnValue(
-          JSON.stringify([mockContact])
+        ; (walletMock.listOutputs as jest.Mock).mockRejectedValue(
+          new Error('List outputs error')
         )
-          ; (walletMock.listOutputs as jest.Mock).mockRejectedValue(
-            new Error('List outputs error')
-          )
 
         await expect(
           identityClient.getContacts(undefined, true)
@@ -543,36 +569,35 @@ describe('IdentityClient', () => {
 
     describe('removeContact', () => {
       it('should remove contact from cache and spend UTXO', async () => {
-        const contacts = [mockContact, { ...mockContact, identityKey: 'other-key' }]
-          ; (localStorage.getItem as jest.Mock).mockReturnValue(
-            JSON.stringify(contacts)
-          )
+        // First save two contacts
+        ; (walletMock.listOutputs as jest.Mock).mockResolvedValue({
+          outputs: [],
+          BEEF: []
+        })
+        await identityClient.saveContact(mockContact)
+        
+        const otherContact = { ...mockContact, identityKey: 'other-key', name: 'Bob' }
+        await identityClient.saveContact(otherContact)
 
+        // Mock finding the contact to remove
         const mockOutput = {
           outpoint: 'txid.0',
           customInstructions: JSON.stringify({ keyID: 'mockKeyID' })
         }
 
-          ; (walletMock.listOutputs as jest.Mock).mockResolvedValue({
-            outputs: [mockOutput],
-            BEEF: [1, 2, 3]
-          })
+        ; (walletMock.listOutputs as jest.Mock).mockResolvedValue({
+          outputs: [mockOutput],
+          BEEF: [1, 2, 3]
+        })
 
-          // Mock decrypt to return the contact that matches the identityKey
-          ; (walletMock.decrypt as jest.Mock).mockResolvedValue({
-            plaintext: new TextEncoder().encode(JSON.stringify(mockContact))
-          })
+        ; (walletMock.decrypt as jest.Mock).mockResolvedValue({
+          plaintext: new TextEncoder().encode(JSON.stringify(mockContact))
+        })
 
         await identityClient.removeContact(mockContact.identityKey)
 
-        // Verify cache was updated (contact removed)
-        expect(localStorage.setItem).toHaveBeenCalledWith(
-          'metanet-contacts',
-          JSON.stringify([{ ...mockContact, identityKey: 'other-key' }])
-        )
-
         // Verify delete action was created
-        expect(walletMock.createAction).toHaveBeenCalledWith(
+        expect(walletMock.createAction).toHaveBeenLastCalledWith(
           expect.objectContaining({
             description: 'Delete Contact',
             inputBEEF: [1, 2, 3],
@@ -584,6 +609,12 @@ describe('IdentityClient', () => {
             outputs: [] // No outputs for deletion
           })
         )
+
+        // Verify contact is removed from cache
+        const remainingContacts = await identityClient.getContacts()
+        expect(remainingContacts).not.toContainEqual(
+          expect.objectContaining({ identityKey: mockContact.identityKey })
+        )
       })
 
       it('should handle contact not found gracefully', async () => {
@@ -592,10 +623,13 @@ describe('IdentityClient', () => {
           BEEF: []
         })
 
-        // Should not throw
+        // Should not throw when contact doesn't exist
         await expect(
           identityClient.removeContact('non-existent-key')
         ).resolves.toBeUndefined()
+
+        // Should not call createAction since no contact found
+        expect(walletMock.createAction).not.toHaveBeenCalled()
       })
     })
   })

package/src/storage/StorageDownloader.ts

@@ -9,7 +9,7 @@ export interface DownloaderConfig {
 }
 
 export interface DownloadResult {
-  data: number[]
+  data: Uint8Array
   mimeType: string | null
 }
 
@@ -58,6 +58,7 @@ export class StorageDownloader {
       throw new Error('Invalid parameter UHRP url')
     }
     const hash = StorageUtils.getHashFromURL(uhrpUrl)
+    const expected = Utils.toHex(hash)
     const downloadURLs = await this.resolve(uhrpUrl)
 
     if (!Array.isArray(downloadURLs) || downloadURLs.length === 0) {
@@ -70,22 +71,37 @@ export class StorageDownloader {
         const result = await fetch(downloadURLs[i], { method: 'GET' })
 
         // If the request fails, continue to the next url
-        if (!result.ok || result.status >= 400) {
+        if (!result.ok || result.status >= 400 || result.body == null) {
           continue
         }
-        const body = await result.arrayBuffer()
-
-        // The body is loaded into a number array
-        const content: number[] = [...new Uint8Array(body)]
-        const contentHash = Hash.sha256(content)
-        for (let i = 0; i < contentHash.length; ++i) {
-          if (contentHash[i] !== hash[i]) {
-            throw new Error('Value of content does not match hash of the url given')
-          }
+
+        const reader = result.body.getReader()
+        const hashStream = new Hash.SHA256()
+        const chunks: Uint8Array[] = []
+        let totalLength = 0
+
+        while (true) {
+          const { done, value } = await reader.read()
+          if (done) break
+          hashStream.update(Array.from(value))
+          chunks.push(value)
+          totalLength += value.length
+        }
+
+        const digest = Utils.toHex(hashStream.digest())
+        if (digest !== expected) {
+          throw new Error('Data integrity error: value of content does not match hash of the url given')
+        }
+
+        const data = new Uint8Array(totalLength)
+        let offset = 0
+        for (const chunk of chunks) {
+          data.set(chunk, offset)
+          offset += chunk.length
         }
 
         return {
-          data: content,
+          data,
           mimeType: result.headers.get('Content-Type')
         }
       } catch (error) {