@bsv/overlay-discovery-services 0.1.0

package/docs/SLAP/slap-lookup-service.md

@@ -0,0 +1,353 @@
+
+Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes)
+
+### Interfaces
+
+| |
+| --- |
+| [SHIPQuery](#interface-shipquery) |
+| [SHIPRecord](#interface-shiprecord) |
+| [SLAPQuery](#interface-slapquery) |
+| [SLAPRecord](#interface-slaprecord) |
+| [UTXOReference](#interface-utxoreference) |
+
+Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes)
+
+---
+
+#### Interface: SHIPQuery
+
+```ts
+export interface SHIPQuery {
+    domain?: string;
+    topics?: string[];
+}
+```
+
+Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes)
+
+---
+#### Interface: SHIPRecord
+
+```ts
+export interface SHIPRecord {
+    txid: string;
+    outputIndex: number;
+    identityKey: string;
+    domain: string;
+    topic: string;
+    createdAt: Date;
+}
+```
+
+Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes)
+
+---
+#### Interface: SLAPQuery
+
+```ts
+export interface SLAPQuery {
+    domain?: string;
+    service?: string;
+}
+```
+
+Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes)
+
+---
+#### Interface: SLAPRecord
+
+```ts
+export interface SLAPRecord {
+    txid: string;
+    outputIndex: number;
+    identityKey: string;
+    domain: string;
+    service: string;
+    createdAt: Date;
+}
+```
+
+Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes)
+
+---
+#### Interface: UTXOReference
+
+```ts
+export interface UTXOReference {
+    txid: string;
+    outputIndex: number;
+}
+```
+
+Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes)
+
+---
+### Classes
+
+| |
+| --- |
+| [SLAPLookupService](#class-slaplookupservice) |
+| [SLAPStorage](#class-slapstorage) |
+
+Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes)
+
+---
+
+#### Class: SLAPLookupService
+
+Implements the SLAP lookup service
+
+The SLAP lookup service allows querying for service availability within the
+overlay network. This service listens for SLAP-related UTXOs and stores relevant
+records for lookup purposes.
+
+```ts
+export class SLAPLookupService implements LookupService {
+    constructor(public storage: SLAPStorage) 
+    async outputAdded?(txid: string, outputIndex: number, outputScript: Script, topic: string): Promise<void> 
+    async outputSpent?(txid: string, outputIndex: number, topic: string): Promise<void> 
+    async outputDeleted?(txid: string, outputIndex: number, topic: string): Promise<void> 
+    async lookup(question: LookupQuestion): Promise<LookupAnswer | LookupFormula> 
+    async getDocumentation(): Promise<string> 
+    async getMetaData(): Promise<{
+        name: string;
+        shortDescription: string;
+        iconURL?: string;
+        version?: string;
+        informationURL?: string;
+    }> 
+}
+```
+
+See also: [SLAPStorage](#class-slapstorage)
+
+<details>
+
+<summary>Class SLAPLookupService Details</summary>
+
+##### Method getDocumentation
+
+Returns documentation specific to this overlay lookup service.
+
+```ts
+async getDocumentation(): Promise<string> 
+```
+
+Returns
+
+A promise that resolves to the documentation string.
+
+##### Method getMetaData
+
+Returns metadata associated with this lookup service.
+
+```ts
+async getMetaData(): Promise<{
+    name: string;
+    shortDescription: string;
+    iconURL?: string;
+    version?: string;
+    informationURL?: string;
+}> 
+```
+
+Returns
+
+A promise that resolves to an object containing metadata.
+
+##### Method lookup
+
+Answers a lookup query.
+
+```ts
+async lookup(question: LookupQuestion): Promise<LookupAnswer | LookupFormula> 
+```
+
+Returns
+
+A promise that resolves to a lookup answer or formula.
+
+Argument Details
+
++ **question**
+  + The lookup question to be answered.
+
+##### Method outputAdded
+
+Handles the addition of a new output to the topic.
+
+```ts
+async outputAdded?(txid: string, outputIndex: number, outputScript: Script, topic: string): Promise<void> 
+```
+
+Argument Details
+
++ **txid**
+  + The transaction ID containing the output.
++ **outputIndex**
+  + The index of the output in the transaction.
++ **outputScript**
+  + The script of the output to be processed.
++ **topic**
+  + The topic associated with the output.
+
+##### Method outputDeleted
+
+Handles the deletion of an output in the topic.
+
+```ts
+async outputDeleted?(txid: string, outputIndex: number, topic: string): Promise<void> 
+```
+
+Argument Details
+
++ **txid**
+  + The transaction ID of the deleted output.
++ **outputIndex**
+  + The index of the deleted output.
++ **topic**
+  + The topic associated with the deleted output.
+
+##### Method outputSpent
+
+Handles the spending of an output in the topic.
+
+```ts
+async outputSpent?(txid: string, outputIndex: number, topic: string): Promise<void> 
+```
+
+Argument Details
+
++ **txid**
+  + The transaction ID of the spent output.
++ **outputIndex**
+  + The index of the spent output.
++ **topic**
+  + The topic associated with the spent output.
+
+</details>
+
+Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes)
+
+---
+#### Class: SLAPStorage
+
+Implements a storage engine for SLAP protocol
+
+```ts
+export class SLAPStorage {
+    constructor(private readonly db: Db) 
+    async ensureIndexes(): Promise<void> 
+    async storeSLAPRecord(txid: string, outputIndex: number, identityKey: string, domain: string, service: string): Promise<void> 
+    async deleteSLAPRecord(txid: string, outputIndex: number): Promise<void> 
+    async findRecord(query: {
+        domain?: string;
+        service?: string;
+    }): Promise<UTXOReference[]> 
+    async findAll(): Promise<UTXOReference[]> 
+}
+```
+
+See also: [UTXOReference](#interface-utxoreference)
+
+<details>
+
+<summary>Class SLAPStorage Details</summary>
+
+##### Constructor
+
+Constructs a new SLAPStorage instance
+
+```ts
+constructor(private readonly db: Db) 
+```
+
+Argument Details
+
++ **db**
+  + connected mongo database instance
+
+##### Method deleteSLAPRecord
+
+Deletes a SLAP record
+
+```ts
+async deleteSLAPRecord(txid: string, outputIndex: number): Promise<void> 
+```
+
+Argument Details
+
++ **txid**
+  + transaction id
++ **outputIndex**
+  + index of the UTXO
+
+##### Method ensureIndexes
+
+Ensures the necessary indexes are created for the collections.
+
+```ts
+async ensureIndexes(): Promise<void> 
+```
+
+##### Method findAll
+
+Returns all results tracked by the overlay
+
+```ts
+async findAll(): Promise<UTXOReference[]> 
+```
+See also: [UTXOReference](#interface-utxoreference)
+
+Returns
+
+returns matching UTXO references
+
+##### Method findRecord
+
+Finds SLAP records based on a given query object.
+
+```ts
+async findRecord(query: {
+    domain?: string;
+    service?: string;
+}): Promise<UTXOReference[]> 
+```
+See also: [UTXOReference](#interface-utxoreference)
+
+Returns
+
+returns matching UTXO references
+
+Argument Details
+
++ **query**
+  + The query object which may contain properties for domain or service.
+
+##### Method storeSLAPRecord
+
+Stores a SLAP record
+
+```ts
+async storeSLAPRecord(txid: string, outputIndex: number, identityKey: string, domain: string, service: string): Promise<void> 
+```
+
+Argument Details
+
++ **txid**
+  + transaction id
++ **outputIndex**
+  + index of the UTXO
++ **identityKey**
+  + identity key
++ **domain**
+  + domain name
++ **service**
+  + service name
+
+</details>
+
+Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes)
+
+---

package/docs/SLAP/slap-storage.md

@@ -0,0 +1,207 @@
+
+Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes)
+
+### Interfaces
+
+| |
+| --- |
+| [SHIPQuery](#interface-shipquery) |
+| [SHIPRecord](#interface-shiprecord) |
+| [SLAPQuery](#interface-slapquery) |
+| [SLAPRecord](#interface-slaprecord) |
+| [UTXOReference](#interface-utxoreference) |
+
+Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes)
+
+---
+
+#### Interface: SHIPQuery
+
+```ts
+export interface SHIPQuery {
+    domain?: string;
+    topics?: string[];
+}
+```
+
+Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes)
+
+---
+#### Interface: SHIPRecord
+
+```ts
+export interface SHIPRecord {
+    txid: string;
+    outputIndex: number;
+    identityKey: string;
+    domain: string;
+    topic: string;
+    createdAt: Date;
+}
+```
+
+Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes)
+
+---
+#### Interface: SLAPQuery
+
+```ts
+export interface SLAPQuery {
+    domain?: string;
+    service?: string;
+}
+```
+
+Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes)
+
+---
+#### Interface: SLAPRecord
+
+```ts
+export interface SLAPRecord {
+    txid: string;
+    outputIndex: number;
+    identityKey: string;
+    domain: string;
+    service: string;
+    createdAt: Date;
+}
+```
+
+Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes)
+
+---
+#### Interface: UTXOReference
+
+```ts
+export interface UTXOReference {
+    txid: string;
+    outputIndex: number;
+}
+```
+
+Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes)
+
+---
+### Classes
+
+#### Class: SLAPStorage
+
+Implements a storage engine for SLAP protocol
+
+```ts
+export class SLAPStorage {
+    constructor(private readonly db: Db) 
+    async ensureIndexes(): Promise<void> 
+    async storeSLAPRecord(txid: string, outputIndex: number, identityKey: string, domain: string, service: string): Promise<void> 
+    async deleteSLAPRecord(txid: string, outputIndex: number): Promise<void> 
+    async findRecord(query: {
+        domain?: string;
+        service?: string;
+    }): Promise<UTXOReference[]> 
+    async findAll(): Promise<UTXOReference[]> 
+}
+```
+
+See also: [UTXOReference](#interface-utxoreference)
+
+<details>
+
+<summary>Class SLAPStorage Details</summary>
+
+##### Constructor
+
+Constructs a new SLAPStorage instance
+
+```ts
+constructor(private readonly db: Db) 
+```
+
+Argument Details
+
++ **db**
+  + connected mongo database instance
+
+##### Method deleteSLAPRecord
+
+Deletes a SLAP record
+
+```ts
+async deleteSLAPRecord(txid: string, outputIndex: number): Promise<void> 
+```
+
+Argument Details
+
++ **txid**
+  + transaction id
++ **outputIndex**
+  + index of the UTXO
+
+##### Method ensureIndexes
+
+Ensures the necessary indexes are created for the collections.
+
+```ts
+async ensureIndexes(): Promise<void> 
+```
+
+##### Method findAll
+
+Returns all results tracked by the overlay
+
+```ts
+async findAll(): Promise<UTXOReference[]> 
+```
+See also: [UTXOReference](#interface-utxoreference)
+
+Returns
+
+returns matching UTXO references
+
+##### Method findRecord
+
+Finds SLAP records based on a given query object.
+
+```ts
+async findRecord(query: {
+    domain?: string;
+    service?: string;
+}): Promise<UTXOReference[]> 
+```
+See also: [UTXOReference](#interface-utxoreference)
+
+Returns
+
+returns matching UTXO references
+
+Argument Details
+
++ **query**
+  + The query object which may contain properties for domain or service.
+
+##### Method storeSLAPRecord
+
+Stores a SLAP record
+
+```ts
+async storeSLAPRecord(txid: string, outputIndex: number, identityKey: string, domain: string, service: string): Promise<void> 
+```
+
+Argument Details
+
++ **txid**
+  + transaction id
++ **outputIndex**
+  + index of the UTXO
++ **identityKey**
+  + identity key
++ **domain**
+  + domain name
++ **service**
+  + service name
+
+</details>
+
+Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes)
+
+---

package/docs/SLAP/slap-topic-manager.md

@@ -0,0 +1,122 @@
+
+Links: [API](#api), [Classes](#classes), [Variables](#variables)
+
+### Classes
+
+#### Class: SLAPTopicManager
+
+SLAP Topic Manager
+Implements the TopicManager interface for SLAP (Service Lookup Availability Protocol) tokens.
+
+The SLAP Topic Manager identifies admissible outputs based on SLAP protocol requirements.
+SLAP tokens facilitate the advertisement of lookup services availability within the overlay network.
+
+```ts
+export class SLAPTopicManager implements TopicManager {
+    async identifyAdmissibleOutputs(beef: number[], previousCoins: number[]): Promise<AdmittanceInstructions> 
+    async getDocumentation(): Promise<string> 
+    async getMetaData(): Promise<{
+        name: string;
+        shortDescription: string;
+        iconURL?: string;
+        version?: string;
+        informationURL?: string;
+    }> 
+}
+```
+
+<details>
+
+<summary>Class SLAPTopicManager Details</summary>
+
+##### Method getDocumentation
+
+Returns documentation specific to the SLAP topic manager.
+
+```ts
+async getDocumentation(): Promise<string> 
+```
+
+Returns
+
+A promise that resolves to the documentation string.
+
+##### Method getMetaData
+
+Returns metadata associated with this topic manager.
+
+```ts
+async getMetaData(): Promise<{
+    name: string;
+    shortDescription: string;
+    iconURL?: string;
+    version?: string;
+    informationURL?: string;
+}> 
+```
+
+Returns
+
+A promise that resolves to an object containing metadata.
+
+##### Method identifyAdmissibleOutputs
+
+Identifies admissible outputs for SLAP tokens.
+
+```ts
+async identifyAdmissibleOutputs(beef: number[], previousCoins: number[]): Promise<AdmittanceInstructions> 
+```
+
+Returns
+
+A promise that resolves with the admittance instructions.
+
+Argument Details
+
++ **beef**
+  + The transaction data in BEEF format.
++ **previousCoins**
+  + The previous coins to consider.
+
+</details>
+
+Links: [API](#api), [Classes](#classes), [Variables](#variables)
+
+---
+### Variables
+
+| |
+| --- |
+| [isValidServiceName](#variable-isvalidservicename) |
+| [verifyToken](#variable-verifytoken) |
+
+Links: [API](#api), [Classes](#classes), [Variables](#variables)
+
+---
+
+#### Variable: isValidServiceName
+
+```ts
+isValidServiceName = (service: string): boolean => {
+    const serviceRegex = /^(?!_)(?!.*__)[a-z_]{1,50}(?<!_)$/;
+    return serviceRegex.test(service);
+}
+```
+
+Links: [API](#api), [Classes](#classes), [Variables](#variables)
+
+---
+#### Variable: verifyToken
+
+```ts
+verifyToken = (identityKey: string, lockingPublicKey: string, fields: Buffer[], signature: string): void => {
+    const pubKey = PublicKey.fromString(lockingPublicKey);
+    const hasValidSignature = pubKey.verify(Array.from(Buffer.concat(fields)), Signature.fromDER(signature, "hex"));
+    if (!hasValidSignature)
+        throw new Error("Invalid signature!");
+}
+```
+
+Links: [API](#api), [Classes](#classes), [Variables](#variables)
+
+---

package/mod.ts

@@ -0,0 +1,15 @@
+export * from './src/SHIP/SHIPLookupService.js'
+export * from './src/SHIP/SHIPStorage.js'
+export * from './src/SHIP/SHIPTopicManager.js'
+
+export * from './src/SLAP/SLAPLookupService.js'
+export * from './src/SLAP/SLAPStorage.js'
+export * from './src/SLAP/SLAPTopicManager.js'
+
+export * from './src/LegacyNinjaAdvertiser.js'
+
+export * from './src/utils/isValidDomain.js'
+export * from './src/utils/isValidServiceName.js'
+export * from './src/utils/verifyToken.js'
+
+export * from './src/types.js'