@bsv/sdk 1.4.0 → 1.4.2

package/dist/types/src/registry/RegistryClient.d.ts

@@ -0,0 +1,94 @@
+import { WalletInterface } from '../wallet/index.js';
+import { BroadcastResponse, BroadcastFailure } from '../transaction/index.js';
+import { DefinitionData, DefinitionType, RegistryQueryMapping, RegistryRecord } from './types/index.js';
+/**
+ * RegistryClient manages on-chain registry definitions for three types:
+ * - BasketMap (basket-based items)
+ * - ProtoMap (protocol-based items)
+ * - CertMap (certificate-based items)
+ *
+ * It provides methods to:
+ * - Register new definitions using pushdrop-based UTXOs.
+ * - Resolve existing definitions using a overlay lookup service.
+ * - List registry entries associated with the operator's wallet.
+ * - Revoke an existing registry entry by spending its UTXO.
+ *
+ * Registry operators use this client to establish and manage
+ * canonical references for baskets, protocols, and certificates types.
+ */
+export declare class RegistryClient {
+    private readonly wallet;
+    private network;
+    constructor(wallet?: WalletInterface);
+    /**
+     * Publishes a new on-chain definition for baskets, protocols, or certificates.
+     * The definition data is encoded in a pushdrop-based UTXO.
+     *
+     * Registry operators (i.e., identity key owners) can create these definitions
+     * to establish canonical references for basket IDs, protocol specs, or certificate schemas.
+     *
+     * @param data - The structured information needed to register an item of kind 'basket', 'protocol', or 'certificate'.
+     * @returns A promise with the broadcast result or failure.
+     */
+    registerDefinition(data: DefinitionData): Promise<BroadcastResponse | BroadcastFailure>;
+    /**
+     * Resolves registrant tokens of a particular type using a lookup service.
+     *
+     * The query object shape depends on the registry type:
+     * - For "basket", the query is of type BasketMapQuery:
+     *   { basketID?: string; name?: string; registryOperators?: string[]; }
+     * - For "protocol", the query is of type ProtoMapQuery:
+     *   { name?: string; registryOperators?: string[]; protocolID?: string; securityLevel?: number; }
+     * - For "certificate", the query is of type CertMapQuery:
+     *   { type?: string; name?: string; registryOperators?: string[]; }
+     *
+     * @param definitionType - The registry type, which can be 'basket', 'protocol', or 'certificate'.
+     * @param query - The query object used to filter registry records, whose shape is determined by the registry type.
+     * @returns A promise that resolves to an array of matching registry records.
+     */
+    resolve<T extends DefinitionType>(definitionType: T, query: RegistryQueryMapping[T]): Promise<DefinitionData[]>;
+    /**
+     * Lists the registry operator's published definitions for the given type.
+     *
+     * Returns parsed registry records including transaction details such as txid, outputIndex, satoshis, and the locking script.
+     *
+     * @param definitionType - The type of registry definition to list ('basket', 'protocol', or 'certificate').
+     * @returns A promise that resolves to an array of RegistryRecord objects.
+     */
+    listOwnRegistryEntries(definitionType: DefinitionType): Promise<RegistryRecord[]>;
+    /**
+     * Revokes a registry record by spending its associated UTXO.
+     *
+     * This function creates a transaction that spends the UTXO corresponding to the provided registry record,
+     * revoking the registry entry. It prepares an unlocker using the appropriate wallet protocol,
+     * builds a signable transaction, signs it, and then broadcasts the finalized transaction.
+     *
+     * @param registryRecord - The registry record to revoke. It must include a valid txid, outputIndex, and lockingScript.
+     * @returns A promise that resolves with either a BroadcastResponse upon success or a BroadcastFailure on error.
+     * @throws If required fields are missing or if transaction creation/signing fails.
+     */
+    revokeOwnRegistryEntry(registryRecord: RegistryRecord): Promise<BroadcastResponse | BroadcastFailure>;
+    private buildPushDropFields;
+    /**
+     * Decodes a pushdrop locking script for a given registry kind,
+     * returning a typed record with the appropriate fields.
+     */
+    private parseLockingScript;
+    /**
+     * Returns the (protocolID, keyID) used for pushdrop based on the registry kind.
+     */
+    private getWalletProtocol;
+    /**
+     * Returns the name of the basket used by the wallet
+     */
+    private getBasketName;
+    /**
+     * Returns the broadcast topic to be used with SHIPBroadcaster.
+     */
+    private getBroadcastTopic;
+    /**
+     * Returns the lookup service name to use.
+     */
+    private getServiceName;
+}
+//# sourceMappingURL=RegistryClient.d.ts.map

package/dist/types/src/registry/RegistryClient.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"RegistryClient.d.ts","sourceRoot":"","sources":["../../../../src/registry/RegistryClient.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,eAAe,EAKhB,MAAM,oBAAoB,CAAA;AAI3B,OAAO,EAEL,iBAAiB,EACjB,gBAAgB,EACjB,MAAM,yBAAyB,CAAA;AAShC,OAAO,EAEL,cAAc,EACd,cAAc,EACd,oBAAoB,EACpB,cAAc,EACf,MAAM,kBAAkB,CAAA;AAIzB;;;;;;;;;;;;;;GAcG;AACH,qBAAa,cAAc;IAGvB,OAAO,CAAC,QAAQ,CAAC,MAAM;IAFzB,OAAO,CAAC,OAAO,CAAuB;gBAEnB,MAAM,GAAE,eAAoC;IAG/D;;;;;;;;;OASG;IACG,kBAAkB,CAAE,IAAI,EAAE,cAAc,GAAG,OAAO,CAAC,iBAAiB,GAAG,gBAAgB,CAAC;IA2C9F;;;;;;;;;;;;;;OAcG;IACG,OAAO,CAAC,CAAC,SAAS,cAAc,EACpC,cAAc,EAAE,CAAC,EACjB,KAAK,EAAE,oBAAoB,CAAC,CAAC,CAAC,GAC7B,OAAO,CAAC,cAAc,EAAE,CAAC;IA2B5B;;;;;;;OAOG;IACG,sBAAsB,CAAE,cAAc,EAAE,cAAc,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC;IA8BxF;;;;;;;;;;OAUG;IACG,sBAAsB,CAC1B,cAAc,EAAE,cAAc,GAC7B,OAAO,CAAC,iBAAiB,GAAG,gBAAgB,CAAC;IA0EhD,OAAO,CAAC,mBAAmB;IA8C3B;;;OAGG;YACW,kBAAkB;IAsGhC;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAazB;;OAEG;IACH,OAAO,CAAC,aAAa;IAarB;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAazB;;OAEG;IACH,OAAO,CAAC,cAAc;CAYvB"}

package/dist/types/src/registry/index.d.ts

@@ -0,0 +1,3 @@
+export * from './RegistryClient.js';
+export * from './types/index.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/types/src/registry/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/registry/index.ts"],"names":[],"mappings":"AAAA,cAAc,qBAAqB,CAAA;AACnC,cAAc,kBAAkB,CAAA"}

package/dist/types/src/registry/types/index.d.ts

@@ -0,0 +1,86 @@
+import { PubKeyHex } from '../../wallet/index.js';
+/**
+ * Determines which category of registry item we are working with.
+ * - "basket" corresponds to BasketMap
+ * - "protocol" corresponds to ProtoMap
+ * - "certificate"  corresponds to CertMap
+ */
+export type DefinitionType = 'basket' | 'protocol' | 'certificate';
+/**
+ * Describes a re-usable structure for certificate fields (used by CertMap).
+ */
+export interface CertificateFieldDescriptor {
+    friendlyName: string;
+    description: string;
+    type: 'text' | 'imageURL' | 'other';
+    fieldIcon: string;
+}
+/**
+ * Registry data for a Basket-style record (BasketMap).
+ */
+export interface BasketDefinitionData {
+    definitionType: 'basket';
+    basketID: string;
+    name: string;
+    iconURL: string;
+    description: string;
+    documentationURL: string;
+    registryOperator?: PubKeyHex;
+}
+/**
+ * Registry data for a Proto-style record (ProtoMap).
+ */
+export interface ProtocolDefinitionData {
+    definitionType: 'protocol';
+    protocolID: string;
+    securityLevel: 0 | 1 | 2;
+    name: string;
+    iconURL: string;
+    description: string;
+    documentationURL: string;
+    registryOperator?: PubKeyHex;
+}
+/**
+ * Registry data for a Cert-style record (CertMap).
+ */
+export interface CertificateDefinitionData {
+    definitionType: 'certificate';
+    type: string;
+    name: string;
+    iconURL: string;
+    description: string;
+    documentationURL: string;
+    fields: Record<string, CertificateFieldDescriptor>;
+    registryOperator?: PubKeyHex;
+}
+export type DefinitionData = BasketDefinitionData | ProtocolDefinitionData | CertificateDefinitionData;
+export interface TokenData {
+    txid: string;
+    outputIndex: number;
+    satoshis: number;
+    lockingScript: string;
+}
+export type RegistryRecord = DefinitionData & TokenData;
+interface BasketMapQuery {
+    basketID?: string;
+    registryOperators?: string[];
+    name?: string;
+}
+interface ProtoMapQuery {
+    name?: string;
+    registryOperators?: string[];
+    protocolID?: string;
+    securityLevel?: number;
+}
+interface CertMapQuery {
+    type?: string;
+    name?: string;
+    registryOperators?: string[];
+}
+export interface RegistryQueryMapping {
+    basket: BasketMapQuery;
+    protocol: ProtoMapQuery;
+    certificate: CertMapQuery;
+}
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/types/src/registry/types/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/registry/types/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAA;AAEjD;;;;;GAKG;AACH,MAAM,MAAM,cAAc,GAAG,QAAQ,GAAG,UAAU,GAAG,aAAa,CAAA;AAElE;;GAEG;AACH,MAAM,WAAW,0BAA0B;IACzC,YAAY,EAAE,MAAM,CAAA;IACpB,WAAW,EAAE,MAAM,CAAA;IACnB,IAAI,EAAE,MAAM,GAAG,UAAU,GAAG,OAAO,CAAA;IACnC,SAAS,EAAE,MAAM,CAAA;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,cAAc,EAAE,QAAQ,CAAA;IACxB,QAAQ,EAAE,MAAM,CAAA;IAChB,IAAI,EAAE,MAAM,CAAA;IACZ,OAAO,EAAE,MAAM,CAAA;IACf,WAAW,EAAE,MAAM,CAAA;IACnB,gBAAgB,EAAE,MAAM,CAAA;IACxB,gBAAgB,CAAC,EAAE,SAAS,CAAA;CAC7B;AAED;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC,cAAc,EAAE,UAAU,CAAA;IAC1B,UAAU,EAAE,MAAM,CAAA;IAClB,aAAa,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;IACxB,IAAI,EAAE,MAAM,CAAA;IACZ,OAAO,EAAE,MAAM,CAAA;IACf,WAAW,EAAE,MAAM,CAAA;IACnB,gBAAgB,EAAE,MAAM,CAAA;IACxB,gBAAgB,CAAC,EAAE,SAAS,CAAA;CAC7B;AAED;;GAEG;AACH,MAAM,WAAW,yBAAyB;IACxC,cAAc,EAAE,aAAa,CAAA;IAC7B,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,MAAM,CAAA;IACZ,OAAO,EAAE,MAAM,CAAA;IACf,WAAW,EAAE,MAAM,CAAA;IACnB,gBAAgB,EAAE,MAAM,CAAA;IACxB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,0BAA0B,CAAC,CAAA;IAClD,gBAAgB,CAAC,EAAE,SAAS,CAAA;CAC7B;AAED,MAAM,MAAM,cAAc,GACtB,oBAAoB,GACpB,sBAAsB,GACtB,yBAAyB,CAAA;AAE7B,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAA;IACZ,WAAW,EAAE,MAAM,CAAA;IACnB,QAAQ,EAAE,MAAM,CAAA;IAChB,aAAa,EAAE,MAAM,CAAA;CACtB;AAED,MAAM,MAAM,cAAc,GAAG,cAAc,GAAG,SAAS,CAAA;AAIvD,UAAU,cAAc;IACtB,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,iBAAiB,CAAC,EAAE,MAAM,EAAE,CAAA;IAC5B,IAAI,CAAC,EAAE,MAAM,CAAA;CACd;AAED,UAAU,aAAa;IACrB,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,iBAAiB,CAAC,EAAE,MAAM,EAAE,CAAA;IAC5B,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,aAAa,CAAC,EAAE,MAAM,CAAA;CACvB;AAED,UAAU,YAAY;IACpB,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,iBAAiB,CAAC,EAAE,MAAM,EAAE,CAAA;CAC7B;AAED,MAAM,WAAW,oBAAoB;IACnC,MAAM,EAAE,cAAc,CAAA;IACtB,QAAQ,EAAE,aAAa,CAAA;IACvB,WAAW,EAAE,YAAY,CAAA;CAC1B"}

package/dist/types/src/storage/StorageDownloader.d.ts

@@ -0,0 +1,25 @@
+export interface DownloaderConfig {
+    networkPreset: 'mainnet' | 'testnet' | 'local';
+}
+export interface DownloadResult {
+    data: number[];
+    mimeType: string | null;
+}
+/**
+ * Locates HTTP URLs where content can be downloaded. It uses the passed or the default one.
+ *
+ * @param {Object} obj All parameters are passed in an object.
+ * @param {String} obj.uhrpUrl The UHRP url to resolve.
+ * @param {string} obj.confederacyHost HTTPS URL for for the with default setting.
+ *
+ * @return {Array<String>} An array of HTTP URLs where content can be downloaded.
+ * @throws {Error} If UHRP url parameter invalid or is not an array
+ * or there is an error retrieving url(s) stored in the UHRP token.
+ */
+export declare class StorageDownloader {
+    private readonly networkPreset?;
+    constructor(config?: DownloaderConfig);
+    resolve(uhrpUrl: string): Promise<string[]>;
+    download(uhrpUrl: string): Promise<DownloadResult>;
+}
+//# sourceMappingURL=StorageDownloader.d.ts.map

package/dist/types/src/storage/StorageDownloader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"StorageDownloader.d.ts","sourceRoot":"","sources":["../../../../src/storage/StorageDownloader.ts"],"names":[],"mappings":"AAMA,MAAM,WAAW,gBAAgB;IAC/B,aAAa,EAAE,SAAS,GAAG,SAAS,GAAG,OAAO,CAAA;CAC/C;AAED,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,EAAE,CAAA;IACd,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAA;CACxB;AAED;;;;;;;;;;GAUG;AACH,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAC,CAA6C;gBAE/D,MAAM,CAAC,EAAE,gBAAgB;IAIzB,OAAO,CAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAgB5C,QAAQ,CAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC;CAyCjE"}

package/dist/types/src/storage/__test/StorageDownloader.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=StorageDownloader.test.d.ts.map

package/dist/types/src/storage/__test/StorageDownloader.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"StorageDownloader.test.d.ts","sourceRoot":"","sources":["../../../../../src/storage/__test/StorageDownloader.test.ts"],"names":[],"mappings":""}

package/dist/types/src/storage/index.d.ts

@@ -1,3 +1,4 @@
 export * as StorageUtils from './StorageUtils.js';
 export { StorageUploader } from './StorageUploader.js';
+export { StorageDownloader } from './StorageDownloader.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/types/src/storage/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/storage/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,YAAY,MAAM,mBAAmB,CAAA;AACjD,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/storage/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,YAAY,MAAM,mBAAmB,CAAA;AAEjD,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAA;AAEtD,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAA"}