@bsv/sdk 1.6.24 → 1.6.25

package/docs/reference/identity.md

@@ -48,6 +48,80 @@ Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](
 ---
 ## Classes
 
+| |
+| --- |
+| [ContactsManager](#class-contactsmanager) |
+| [IdentityClient](#class-identityclient) |
+
+Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Enums](#enums), [Variables](#variables)
+
+---
+
+### Class: ContactsManager
+
+```ts
+export class ContactsManager {
+    constructor(wallet?: WalletInterface) 
+    async getContacts(identityKey?: PubKeyHex, forceRefresh = false): Promise<Contact[]> 
+    async saveContact(contact: DisplayableIdentity, metadata?: Record<string, any>): Promise<void> 
+    async removeContact(identityKey: string): Promise<void> 
+}
+```
+
+See also: [Contact](./identity.md#type-contact), [DisplayableIdentity](./identity.md#interface-displayableidentity), [PubKeyHex](./wallet.md#type-pubkeyhex), [WalletInterface](./wallet.md#interface-walletinterface)
+
+#### Method getContacts
+
+Load all records from the contacts basket
+
+```ts
+async getContacts(identityKey?: PubKeyHex, forceRefresh = false): Promise<Contact[]> 
+```
+See also: [Contact](./identity.md#type-contact), [PubKeyHex](./wallet.md#type-pubkeyhex)
+
+Returns
+
+A promise that resolves with an array of contacts
+
+Argument Details
+
++ **identityKey**
+  + Optional specific identity key to fetch
++ **forceRefresh**
+  + Whether to force a check for new contact data
+
+#### Method removeContact
+
+Remove a contact from the contacts basket
+
+```ts
+async removeContact(identityKey: string): Promise<void> 
+```
+
+Argument Details
+
++ **identityKey**
+  + The identity key of the contact to remove
+
+#### Method saveContact
+
+Save or update a Metanet contact
+
+```ts
+async saveContact(contact: DisplayableIdentity, metadata?: Record<string, any>): Promise<void> 
+```
+See also: [DisplayableIdentity](./identity.md#interface-displayableidentity)
+
+Argument Details
+
++ **contact**
+  + The displayable identity information for the contact
++ **metadata**
+  + Optional metadata to store with the contact (ex. notes, aliases, etc)
+
+Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Enums](#enums), [Variables](#variables)
+
+---
 ### Class: IdentityClient
 
 IdentityClient lets you discover who others are, and let the world know who you are.
@@ -58,17 +132,42 @@ export class IdentityClient {
     async publiclyRevealAttributes(certificate: WalletCertificate, fieldsToReveal: CertificateFieldNameUnder50Bytes[]): Promise<BroadcastResponse | BroadcastFailure> 
     async resolveByIdentityKey(args: DiscoverByIdentityKeyArgs): Promise<DisplayableIdentity[]> 
     async resolveByAttributes(args: DiscoverByAttributesArgs): Promise<DisplayableIdentity[]> 
+    public async getContacts(identityKey?: PubKeyHex, forceRefresh = false): Promise<Contact[]> 
+    public async saveContact(contact: DisplayableIdentity, metadata?: Record<string, any>): Promise<void> 
+    public async removeContact(identityKey: PubKeyHex): Promise<void> 
     static parseIdentity(identityToParse: IdentityCertificate): DisplayableIdentity 
 }
 ```
 
-See also: [BroadcastFailure](./transaction.md#interface-broadcastfailure), [BroadcastResponse](./transaction.md#interface-broadcastresponse), [CertificateFieldNameUnder50Bytes](./wallet.md#type-certificatefieldnameunder50bytes), [DEFAULT_IDENTITY_CLIENT_OPTIONS](./identity.md#variable-default_identity_client_options), [DiscoverByAttributesArgs](./wallet.md#interface-discoverbyattributesargs), [DiscoverByIdentityKeyArgs](./wallet.md#interface-discoverbyidentitykeyargs), [DisplayableIdentity](./identity.md#interface-displayableidentity), [IdentityCertificate](./wallet.md#interface-identitycertificate), [OriginatorDomainNameStringUnder250Bytes](./wallet.md#type-originatordomainnamestringunder250bytes), [WalletCertificate](./wallet.md#interface-walletcertificate), [WalletInterface](./wallet.md#interface-walletinterface)
+See also: [BroadcastFailure](./transaction.md#interface-broadcastfailure), [BroadcastResponse](./transaction.md#interface-broadcastresponse), [CertificateFieldNameUnder50Bytes](./wallet.md#type-certificatefieldnameunder50bytes), [Contact](./identity.md#type-contact), [DEFAULT_IDENTITY_CLIENT_OPTIONS](./identity.md#variable-default_identity_client_options), [DiscoverByAttributesArgs](./wallet.md#interface-discoverbyattributesargs), [DiscoverByIdentityKeyArgs](./wallet.md#interface-discoverbyidentitykeyargs), [DisplayableIdentity](./identity.md#interface-displayableidentity), [IdentityCertificate](./wallet.md#interface-identitycertificate), [OriginatorDomainNameStringUnder250Bytes](./wallet.md#type-originatordomainnamestringunder250bytes), [PubKeyHex](./wallet.md#type-pubkeyhex), [WalletCertificate](./wallet.md#interface-walletcertificate), [WalletInterface](./wallet.md#interface-walletinterface)
 
-#### Method parseIdentity
+#### Method getContacts
 
 TODO: Implement once revocation overlay is created
 Remove public certificate revelation from overlay services by spending the identity token
 
+Load all records from the contacts basket
+
+```ts
+public async getContacts(identityKey?: PubKeyHex, forceRefresh = false): Promise<Contact[]> 
+```
+See also: [Contact](./identity.md#type-contact), [PubKeyHex](./wallet.md#type-pubkeyhex)
+
+Returns
+
+A promise that resolves with an array of contacts
+
+Argument Details
+
++ **serialNumber**
+  + Unique serial number of the certificate to revoke revelation
++ **identityKey**
+  + Optional specific identity key to fetch
++ **forceRefresh**
+  + Whether to force a check for new contact data
+
+#### Method parseIdentity
+
 Parse out identity and certifier attributes to display from an IdentityCertificate
 
 ```ts
@@ -82,8 +181,6 @@ Returns
 
 Argument Details
 
-+ **serialNumber**
-  + Unique serial number of the certificate to revoke revelation
 + **identityToParse**
   + The Identity Certificate to parse
 
@@ -112,6 +209,20 @@ Throws
 
 Throws an error if the certificate is invalid, the fields cannot be revealed, or if the broadcast fails.
 
+#### Method removeContact
+
+Remove a contact from the contacts basket
+
+```ts
+public async removeContact(identityKey: PubKeyHex): Promise<void> 
+```
+See also: [PubKeyHex](./wallet.md#type-pubkeyhex)
+
+Argument Details
+
++ **identityKey**
+  + The identity key of the contact to remove
+
 #### Method resolveByAttributes
 
 Resolves displayable identity certificates by specific identity attributes, issued by a trusted entity.
@@ -148,6 +259,22 @@ Argument Details
 + **args**
   + Arguments for requesting the discovery based on the identity key.
 
+#### Method saveContact
+
+Save or update a Metanet contact
+
+```ts
+public async saveContact(contact: DisplayableIdentity, metadata?: Record<string, any>): Promise<void> 
+```
+See also: [DisplayableIdentity](./identity.md#interface-displayableidentity)
+
+Argument Details
+
++ **contact**
+  + The displayable identity information for the contact
++ **metadata**
+  + Optional metadata to store with the contact (ex. notes, aliases, etc)
+
 Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Enums](#enums), [Variables](#variables)
 
 ---
@@ -155,6 +282,19 @@ Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](
 
 ## Types
 
+### Type: Contact
+
+```ts
+export type Contact = DisplayableIdentity & {
+    metadata?: Record<string, any>;
+}
+```
+
+See also: [DisplayableIdentity](./identity.md#interface-displayableidentity)
+
+Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Enums](#enums), [Variables](#variables)
+
+---
 ## Enums
 
 ## Variables

package/package.json

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

package/src/identity/ContactsManager.ts

@@ -0,0 +1,332 @@
+import { PubKeyHex, WalletClient, WalletInterface, WalletProtocol } from '../wallet/index.js'
+import { Utils, Random } from '../primitives/index.js'
+import { DisplayableIdentity } from './types/index.js'
+import { PushDrop } from '../script/index.js'
+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'
+
+export class ContactsManager {
+  private readonly wallet: WalletInterface
+
+  constructor (wallet?: WalletInterface) {
+    this.wallet = wallet ?? new WalletClient()
+  }
+
+  /**
+   * Load all records from the contacts basket
+   * @param identityKey Optional specific identity key to fetch
+   * @param forceRefresh Whether to force a check for new contact data
+   * @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
+    if (!forceRefresh) {
+      const cached = localStorage.getItem(CONTACTS_CACHE_KEY)
+      if (cached != null && cached !== '') {
+        try {
+          const cachedContacts: Contact[] = JSON.parse(cached)
+          return identityKey != null
+            ? cachedContacts.filter(c => c.identityKey === identityKey)
+            : cachedContacts
+        } catch (e) {
+          console.warn('Invalid cached contacts JSON; will reload from chain', e)
+        }
+      }
+    }
+
+    const tags: string[] = []
+    if (identityKey != null) {
+      // Hash the identity key to use as a tag for quick lookup
+      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)}`)
+    }
+
+    // Get all contact outputs from the contacts basket
+    const outputs = await this.wallet.listOutputs({
+      basket: 'contacts',
+      include: 'entire transactions',
+      tags
+    })
+
+    if (outputs.outputs == null || outputs.outputs.length === 0) {
+      localStorage.setItem(CONTACTS_CACHE_KEY, JSON.stringify([]))
+      return []
+    }
+
+    const contacts: Contact[] = []
+
+    // Process each contact output
+    for (const output of outputs.outputs) {
+      try {
+        const [txid, outputIndex] = output.outpoint.split('.')
+        const tx = Transaction.fromBEEF(outputs.BEEF as number[], txid)
+        const lockingScript = tx.outputs[Number(outputIndex)].lockingScript
+
+        // Decode the PushDrop data
+        const decoded = PushDrop.decode(lockingScript)
+        if (output.customInstructions == null) continue
+        const keyID = JSON.parse(output.customInstructions).keyID
+
+        // Decrypt the contact data
+        const { plaintext } = await this.wallet.decrypt({
+          ciphertext: decoded.fields[0],
+          protocolID: CONTACT_PROTOCOL_ID,
+          keyID,
+          counterparty: 'self'
+        })
+
+        // Parse the contact data
+        const contactData: Contact = JSON.parse(Utils.toUTF8(plaintext))
+
+        contacts.push(contactData)
+      } catch (error) {
+        console.warn('ContactsManager: Failed to decode contact output:', error)
+        // Skip this contact and continue with others
+      }
+    }
+
+    // Cache the loaded contacts
+    localStorage.setItem(CONTACTS_CACHE_KEY, JSON.stringify(contacts))
+    const filteredContacts = identityKey != null
+      ? contacts.filter(c => c.identityKey === identityKey)
+      : contacts
+    return filteredContacts
+  }
+
+  /**
+   * Save or update a Metanet contact
+   * @param contact The displayable identity information for the contact
+   * @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) : []
+    const existingIndex = contacts.findIndex(c => c.identityKey === contact.identityKey)
+    const contactToStore: Contact = {
+      ...contact,
+      metadata
+    }
+
+    if (existingIndex >= 0) {
+      contacts[existingIndex] = contactToStore
+    } else {
+      contacts.push(contactToStore)
+    }
+    localStorage.setItem(CONTACTS_CACHE_KEY, JSON.stringify(contacts))
+
+    const { hmac: hashedIdentityKey } = await this.wallet.createHmac({
+      protocolID: CONTACT_PROTOCOL_ID,
+      keyID: contact.identityKey,
+      counterparty: 'self',
+      data: Utils.toArray(contact.identityKey, 'utf8')
+    })
+
+    // Check if this contact already exists (to update it)
+    const outputs = await this.wallet.listOutputs({
+      basket: 'contacts',
+      include: 'entire transactions',
+      includeCustomInstructions: true,
+      tags: [`identityKey ${Utils.toHex(hashedIdentityKey)}`]
+    })
+
+    let existingOutput: any = null
+    let keyID = Utils.toBase64(Random(32))
+    if (outputs.outputs != null) {
+      // Find output by trying to decrypt and checking identityKey in payload
+      for (const output of outputs.outputs) {
+        try {
+          const [txid, outputIndex] = output.outpoint.split('.')
+          const tx = Transaction.fromBEEF(outputs.BEEF as number[], txid)
+          const decoded = PushDrop.decode(tx.outputs[Number(outputIndex)].lockingScript)
+          if (output.customInstructions == null) continue
+          keyID = JSON.parse(output.customInstructions).keyID
+
+          const { plaintext } = await this.wallet.decrypt({
+            ciphertext: decoded.fields[0],
+            protocolID: CONTACT_PROTOCOL_ID,
+            keyID,
+            counterparty: 'self'
+          })
+
+          const storedContact: Contact = JSON.parse(Utils.toUTF8(plaintext))
+          if (storedContact.identityKey === contact.identityKey) {
+            // Found the right output
+            existingOutput = output
+            break
+          }
+        } catch (e) {
+          // Skip malformed or undecryptable outputs
+        }
+      }
+    }
+
+    // Encrypt the contact data directly
+    const contactWithMetadata: Contact = {
+      ...contact,
+      metadata
+    }
+    const { ciphertext } = await this.wallet.encrypt({
+      plaintext: Utils.toArray(JSON.stringify(contactWithMetadata), 'utf8'),
+      protocolID: CONTACT_PROTOCOL_ID,
+      keyID,
+      counterparty: 'self'
+    })
+
+    // Create locking script for the new contact token
+    const lockingScript = await new PushDrop(this.wallet).lock(
+      [ciphertext],
+      CONTACT_PROTOCOL_ID,
+      keyID,
+      'self'
+    )
+
+    if (existingOutput != null) {
+      // Update existing contact by spending its output
+      const [txid, outputIndex] = String(existingOutput.outpoint).split('.')
+      const prevOutpoint = `${txid}.${outputIndex}` as const
+
+      const pushdrop = new PushDrop(this.wallet)
+      const { signableTransaction } = await this.wallet.createAction({
+        description: 'Update Contact',
+        inputBEEF: outputs.BEEF as number[],
+        inputs: [{
+          outpoint: prevOutpoint,
+          unlockingScriptLength: 74,
+          inputDescription: 'Spend previous contact output'
+        }],
+        outputs: [{
+          basket: 'contacts',
+          satoshis: 1,
+          lockingScript: lockingScript.toHex(),
+          outputDescription: `Updated Contact: ${contact.name ?? contact.identityKey.slice(0, 10)}`,
+          tags: [`identityKey ${Utils.toHex(hashedIdentityKey)}`],
+          customInstructions: JSON.stringify({ keyID })
+        }],
+        options: { acceptDelayedBroadcast: false, randomizeOutputs: false } // TODO: Support custom config as needed.
+      })
+
+      if (signableTransaction == null) throw new Error('Unable to update contact')
+
+      const unlocker = pushdrop.unlock(CONTACT_PROTOCOL_ID, keyID, 'self')
+      const unlockingScript = await unlocker.sign(
+        Transaction.fromBEEF(signableTransaction.tx),
+        0
+      )
+
+      const { tx } = await this.wallet.signAction({
+        reference: signableTransaction.reference,
+        spends: { 0: { unlockingScript: unlockingScript.toHex() } }
+      })
+
+      if (tx == null) throw new Error('Failed to update contact output')
+    } else {
+      // Create new contact output
+      const { tx } = await this.wallet.createAction({
+        description: 'Add Contact',
+        outputs: [{
+          basket: 'contacts',
+          satoshis: 1,
+          lockingScript: lockingScript.toHex(),
+          outputDescription: `Contact: ${contact.name ?? contact.identityKey.slice(0, 10)}`,
+          tags: [`identityKey ${Utils.toHex(hashedIdentityKey)}`],
+          customInstructions: JSON.stringify({ keyID })
+        }],
+        options: { acceptDelayedBroadcast: false, randomizeOutputs: false } // TODO: Support custom config as needed.
+      })
+
+      if (tx == null) throw new Error('Failed to create contact output')
+    }
+  }
+
+  /**
+   * Remove a contact from the contacts basket
+   * @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)
+    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))
+      } catch (e) {
+        console.warn('Failed to update cache after contact removal:', e)
+      }
+    }
+
+    // Find and spend the contact's output
+    const outputs = await this.wallet.listOutputs({
+      basket: 'contacts',
+      include: 'entire transactions',
+      includeCustomInstructions: true
+    })
+
+    if (outputs.outputs == null) return
+
+    // Find the output for this specific contact by decrypting and checking identityKey
+    for (const output of outputs.outputs) {
+      try {
+        const [txid, outputIndex] = String(output.outpoint).split('.')
+        const tx = Transaction.fromBEEF(outputs.BEEF as number[], txid)
+        const decoded = PushDrop.decode(tx.outputs[Number(outputIndex)].lockingScript)
+        if (output.customInstructions == null) continue
+        const keyID = JSON.parse(output.customInstructions).keyID
+
+        const { plaintext } = await this.wallet.decrypt({
+          ciphertext: decoded.fields[0],
+          protocolID: CONTACT_PROTOCOL_ID,
+          keyID,
+          counterparty: 'self'
+        })
+
+        const storedContact: Contact = JSON.parse(Utils.toUTF8(plaintext))
+        if (storedContact.identityKey === identityKey) {
+          // Found the contact's output, spend it without creating a new one
+          const prevOutpoint = `${txid}.${outputIndex}` as const
+
+          const pushdrop = new PushDrop(this.wallet)
+          const { signableTransaction } = await this.wallet.createAction({
+            description: 'Delete Contact',
+            inputBEEF: outputs.BEEF as number[],
+            inputs: [{
+              outpoint: prevOutpoint,
+              unlockingScriptLength: 74,
+              inputDescription: 'Spend contact output to delete'
+            }],
+            outputs: [], // No outputs = deletion
+            options: { acceptDelayedBroadcast: false, randomizeOutputs: false } // TODO: Support custom config as needed.
+          })
+
+          if (signableTransaction == null) throw new Error('Unable to delete contact')
+
+          const unlocker = pushdrop.unlock(CONTACT_PROTOCOL_ID, keyID, 'self')
+          const unlockingScript = await unlocker.sign(
+            Transaction.fromBEEF(signableTransaction.tx),
+            0
+          )
+
+          const { tx: deleteTx } = await this.wallet.signAction({
+            reference: signableTransaction.reference,
+            spends: { 0: { unlockingScript: unlockingScript.toHex() } }
+          })
+
+          if (deleteTx == null) throw new Error('Failed to delete contact output')
+          return
+        }
+      } catch (e) {
+        // Skip malformed or undecryptable outputs
+      }
+    }
+  }
+}

package/src/identity/IdentityClient.ts

@@ -6,6 +6,7 @@ import {
   DiscoverByIdentityKeyArgs,
   IdentityCertificate,
   OriginatorDomainNameStringUnder250Bytes,
+  PubKeyHex,
   WalletCertificate,
   WalletClient,
   WalletInterface
@@ -15,6 +16,7 @@ import Certificate from '../auth/certificates/Certificate.js'
 import { PushDrop } from '../script/index.js'
 import { PrivateKey, Utils } from '../primitives/index.js'
 import { TopicBroadcaster } from '../overlay-tools/index.js'
+import { ContactsManager, Contact } from './ContactsManager.js'
 
 /**
  * IdentityClient lets you discover who others are, and let the world know who you are.
@@ -22,6 +24,7 @@ import { TopicBroadcaster } from '../overlay-tools/index.js'
 export class IdentityClient {
   private readonly authClient: AuthFetch
   private readonly wallet: WalletInterface
+  private readonly contactsManager: ContactsManager
   constructor (
     wallet?: WalletInterface,
     private readonly options = DEFAULT_IDENTITY_CLIENT_OPTIONS,
@@ -29,6 +32,7 @@ export class IdentityClient {
   ) {
     this.wallet = wallet ?? new WalletClient()
     this.authClient = new AuthFetch(this.wallet)
+    this.contactsManager = new ContactsManager(this.wallet)
   }
 
   /**
@@ -213,6 +217,33 @@ export class IdentityClient {
   //   return await broadcaster.broadcast(Transaction.fromAtomicBEEF(signedTx as number[]))
   // }
 
+  /**
+   * Load all records from the contacts basket
+   * @param identityKey Optional specific identity key to fetch
+   * @param forceRefresh Whether to force a check for new contact data
+   * @returns A promise that resolves with an array of contacts
+   */
+  public async getContacts (identityKey?: PubKeyHex, forceRefresh = false): Promise<Contact[]> {
+    return await this.contactsManager.getContacts(identityKey, forceRefresh)
+  }
+
+  /**
+   * Save or update a Metanet contact
+   * @param contact The displayable identity information for the contact
+   * @param metadata Optional metadata to store with the contact (ex. notes, aliases, etc)
+   */
+  public async saveContact (contact: DisplayableIdentity, metadata?: Record<string, any>): Promise<void> {
+    return await this.contactsManager.saveContact(contact, metadata)
+  }
+
+  /**
+   * Remove a contact from the contacts basket
+   * @param identityKey The identity key of the contact to remove
+   */
+  public async removeContact (identityKey: PubKeyHex): Promise<void> {
+    return await this.contactsManager.removeContact(identityKey)
+  }
+
   /**
    * Parse out identity and certifier attributes to display from an IdentityCertificate
    * @param identityToParse - The Identity Certificate to parse