@bsv/sdk 1.4.13 → 1.4.17

package/docs/registry.md

@@ -0,0 +1,383 @@
+# API
+
+Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Enums](#enums), [Variables](#variables)
+
+## Interfaces
+
+| |
+| --- |
+| [BasketDefinitionData](#interface-basketdefinitiondata) |
+| [BasketQuery](#interface-basketquery) |
+| [CertificateDefinitionData](#interface-certificatedefinitiondata) |
+| [CertificateFieldDescriptor](#interface-certificatefielddescriptor) |
+| [CertificateQuery](#interface-certificatequery) |
+| [ProtocolDefinitionData](#interface-protocoldefinitiondata) |
+| [ProtocolQuery](#interface-protocolquery) |
+| [RegistryQueryMapping](#interface-registryquerymapping) |
+| [TokenData](#interface-tokendata) |
+
+Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Enums](#enums), [Variables](#variables)
+
+---
+
+### Interface: BasketDefinitionData
+
+Registry data for a Basket-style record.
+
+```ts
+export interface BasketDefinitionData {
+    definitionType: "basket";
+    basketID: string;
+    name: string;
+    iconURL: string;
+    description: string;
+    documentationURL: string;
+    registryOperator?: PubKeyHex;
+}
+```
+
+See also: [PubKeyHex](./wallet.md#type-pubkeyhex)
+
+Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Enums](#enums), [Variables](#variables)
+
+---
+### Interface: BasketQuery
+
+When searching for basket definitions, we can filter by:
+ - basketID
+ - registryOperators
+ - name
+
+```ts
+export interface BasketQuery {
+    basketID?: string;
+    registryOperators?: string[];
+    name?: string;
+}
+```
+
+Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Enums](#enums), [Variables](#variables)
+
+---
+### Interface: CertificateDefinitionData
+
+Registry data for a Certificate-style record.
+
+```ts
+export interface CertificateDefinitionData {
+    definitionType: "certificate";
+    type: string;
+    name: string;
+    iconURL: string;
+    description: string;
+    documentationURL: string;
+    fields: Record<string, CertificateFieldDescriptor>;
+    registryOperator?: PubKeyHex;
+}
+```
+
+See also: [CertificateFieldDescriptor](./registry.md#interface-certificatefielddescriptor), [PubKeyHex](./wallet.md#type-pubkeyhex)
+
+Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Enums](#enums), [Variables](#variables)
+
+---
+### Interface: CertificateFieldDescriptor
+
+Describes a re-usable structure for certificate fields (used by CertMap).
+
+```ts
+export interface CertificateFieldDescriptor {
+    friendlyName: string;
+    description: string;
+    type: "text" | "imageURL" | "other";
+    fieldIcon: string;
+}
+```
+
+Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Enums](#enums), [Variables](#variables)
+
+---
+### Interface: CertificateQuery
+
+When searching for certificate definitions, we can filter by:
+ - type
+ - name
+ - registryOperators
+
+```ts
+export interface CertificateQuery {
+    type?: string;
+    name?: string;
+    registryOperators?: string[];
+}
+```
+
+Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Enums](#enums), [Variables](#variables)
+
+---
+### Interface: ProtocolDefinitionData
+
+Registry data for a Protocol-style record.
+
+```ts
+export interface ProtocolDefinitionData {
+    definitionType: "protocol";
+    protocolID: WalletProtocol;
+    name: string;
+    iconURL: string;
+    description: string;
+    documentationURL: string;
+    registryOperator?: PubKeyHex;
+}
+```
+
+See also: [PubKeyHex](./wallet.md#type-pubkeyhex), [WalletProtocol](./wallet.md#type-walletprotocol)
+
+Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Enums](#enums), [Variables](#variables)
+
+---
+### Interface: ProtocolQuery
+
+When searching for protocol definitions, we can filter by:
+ - name
+ - registryOperators
+ - protocolID
+
+```ts
+export interface ProtocolQuery {
+    name?: string;
+    registryOperators?: string[];
+    protocolID?: WalletProtocol;
+}
+```
+
+See also: [WalletProtocol](./wallet.md#type-walletprotocol)
+
+Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Enums](#enums), [Variables](#variables)
+
+---
+### Interface: RegistryQueryMapping
+
+A lookup-service mapping of queries by each definition type.
+
+```ts
+export interface RegistryQueryMapping {
+    basket: BasketQuery;
+    protocol: ProtocolQuery;
+    certificate: CertificateQuery;
+}
+```
+
+See also: [BasketQuery](./registry.md#interface-basketquery), [CertificateQuery](./registry.md#interface-certificatequery), [ProtocolQuery](./registry.md#interface-protocolquery)
+
+Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Enums](#enums), [Variables](#variables)
+
+---
+### Interface: TokenData
+
+Common info for the on-chain token/UTXO that points to a registry entry.
+
+```ts
+export interface TokenData {
+    txid: string;
+    outputIndex: number;
+    satoshis: number;
+    lockingScript: string;
+    beef: BEEF;
+}
+```
+
+See also: [BEEF](./wallet.md#type-beef)
+
+Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Enums](#enums), [Variables](#variables)
+
+---
+## Classes
+
+### Class: RegistryClient
+
+RegistryClient manages on-chain registry definitions for three types:
+- basket (basket-based items)
+- protocol (protocol-based items)
+- certificate (certificate-based items)
+
+It provides methods to:
+- Register new definitions using pushdrop-based UTXOs.
+- Resolve existing definitions using a 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 certificate types.
+
+```ts
+export class RegistryClient {
+    constructor(private readonly wallet: WalletInterface = new WalletClient()) 
+    async registerDefinition(data: DefinitionData): Promise<BroadcastResponse | BroadcastFailure> 
+    async resolve<T extends DefinitionType>(definitionType: T, query: RegistryQueryMapping[T]): Promise<DefinitionData[]> 
+    async listOwnRegistryEntries(definitionType: DefinitionType): Promise<RegistryRecord[]> 
+    async revokeOwnRegistryEntry(registryRecord: RegistryRecord): Promise<BroadcastResponse | BroadcastFailure> 
+}
+```
+
+See also: [BroadcastFailure](./transaction.md#interface-broadcastfailure), [BroadcastResponse](./transaction.md#interface-broadcastresponse), [DefinitionData](./registry.md#type-definitiondata), [DefinitionType](./registry.md#type-definitiontype), [RegistryQueryMapping](./registry.md#interface-registryquerymapping), [RegistryRecord](./registry.md#type-registryrecord), [WalletClient](./wallet.md#class-walletclient), [WalletInterface](./wallet.md#interface-walletinterface)
+
+#### Method listOwnRegistryEntries
+
+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.
+
+```ts
+async listOwnRegistryEntries(definitionType: DefinitionType): Promise<RegistryRecord[]> 
+```
+See also: [DefinitionType](./registry.md#type-definitiontype), [RegistryRecord](./registry.md#type-registryrecord)
+
+Returns
+
+A promise that resolves to an array of RegistryRecord objects.
+
+Argument Details
+
++ **definitionType**
+  + The type of registry definition to list ('basket', 'protocol', or 'certificate').
+
+#### Method registerDefinition
+
+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.
+
+```ts
+async registerDefinition(data: DefinitionData): Promise<BroadcastResponse | BroadcastFailure> 
+```
+See also: [BroadcastFailure](./transaction.md#interface-broadcastfailure), [BroadcastResponse](./transaction.md#interface-broadcastresponse), [DefinitionData](./registry.md#type-definitiondata)
+
+Returns
+
+A promise with the broadcast result or failure.
+
+Argument Details
+
++ **data**
+  + Structured information about a 'basket', 'protocol', or 'certificate'.
+
+#### Method resolve
+
+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?: WalletProtocol; }
+- For "certificate", the query is of type CertMapQuery:
+  { type?: string; name?: string; registryOperators?: string[]; }
+
+```ts
+async resolve<T extends DefinitionType>(definitionType: T, query: RegistryQueryMapping[T]): Promise<DefinitionData[]> 
+```
+See also: [DefinitionData](./registry.md#type-definitiondata), [DefinitionType](./registry.md#type-definitiontype), [RegistryQueryMapping](./registry.md#interface-registryquerymapping)
+
+Returns
+
+A promise that resolves to an array of matching registry records.
+
+Argument Details
+
++ **definitionType**
+  + The registry type, which can be 'basket', 'protocol', or 'certificate'.
++ **query**
+  + The query object used to filter registry records, whose shape is determined by the registry type.
+
+#### Method revokeOwnRegistryEntry
+
+Revokes a registry record by spending its associated UTXO.
+
+```ts
+async revokeOwnRegistryEntry(registryRecord: RegistryRecord): Promise<BroadcastResponse | BroadcastFailure> 
+```
+See also: [BroadcastFailure](./transaction.md#interface-broadcastfailure), [BroadcastResponse](./transaction.md#interface-broadcastresponse), [RegistryRecord](./registry.md#type-registryrecord)
+
+Returns
+
+Broadcast success/failure.
+
+Argument Details
+
++ **registryRecord**
+  + Must have valid txid, outputIndex, and lockingScript.
+
+Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Enums](#enums), [Variables](#variables)
+
+---
+## Functions
+
+### Function: deserializeWalletProtocol
+
+```ts
+export function deserializeWalletProtocol(str: string): WalletProtocol 
+```
+
+See also: [WalletProtocol](./wallet.md#type-walletprotocol)
+
+Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Enums](#enums), [Variables](#variables)
+
+---
+## Types
+
+| |
+| --- |
+| [DefinitionData](#type-definitiondata) |
+| [DefinitionType](#type-definitiontype) |
+| [RegistryRecord](#type-registryrecord) |
+
+Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Enums](#enums), [Variables](#variables)
+
+---
+
+### Type: DefinitionData
+
+Union of all possible definition data objects.
+
+```ts
+export type DefinitionData = BasketDefinitionData | ProtocolDefinitionData | CertificateDefinitionData
+```
+
+See also: [BasketDefinitionData](./registry.md#interface-basketdefinitiondata), [CertificateDefinitionData](./registry.md#interface-certificatedefinitiondata), [ProtocolDefinitionData](./registry.md#interface-protocoldefinitiondata)
+
+Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Enums](#enums), [Variables](#variables)
+
+---
+### Type: DefinitionType
+
+We unify the registry “type” to these three strings everywhere:
+  'basket' | 'protocol' | 'certificate'
+
+```ts
+export type DefinitionType = "basket" | "protocol" | "certificate"
+```
+
+Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Enums](#enums), [Variables](#variables)
+
+---
+### Type: RegistryRecord
+
+A registry record is a combination of the typed definition data
+plus the on-chain token data for the UTXO holding it.
+
+```ts
+export type RegistryRecord = DefinitionData & TokenData
+```
+
+See also: [DefinitionData](./registry.md#type-definitiondata), [TokenData](./registry.md#interface-tokendata)
+
+Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Enums](#enums), [Variables](#variables)
+
+---
+## Enums
+
+## Variables
+

package/docs/transaction.md

@@ -1477,7 +1477,7 @@ export default class Transaction {
     addOutput(output: TransactionOutput): void 
     addP2PKHOutput(address: number[] | string, satoshis?: number): void 
     updateMetadata(metadata: Record<string, any>): void 
-    async fee(modelOrFee: FeeModel | number = new SatoshisPerKilobyte(10), changeDistribution: "equal" | "random" = "equal"): Promise<void> 
+    async fee(modelOrFee: FeeModel | number = new SatoshisPerKilobyte(1), changeDistribution: "equal" | "random" = "equal"): Promise<void> 
     getFee(): number 
     async sign(): Promise<void> 
     async broadcast(broadcaster: Broadcaster = defaultBroadcaster()): Promise<BroadcastResponse | BroadcastFailure> 
@@ -1567,11 +1567,11 @@ Argument Details
 #### Method fee
 
 Computes fees prior to signing.
-If no fee model is provided, uses a SatoshisPerKilobyte fee model that pays 10 sat/kb.
+If no fee model is provided, uses a SatoshisPerKilobyte fee model that pays 1 sat/kb.
 If fee is a number, the transaction uses that value as fee.
 
 ```ts
-async fee(modelOrFee: FeeModel | number = new SatoshisPerKilobyte(10), changeDistribution: "equal" | "random" = "equal"): Promise<void> 
+async fee(modelOrFee: FeeModel | number = new SatoshisPerKilobyte(1), changeDistribution: "equal" | "random" = "equal"): Promise<void> 
 ```
 See also: [FeeModel](./transaction.md#interface-feemodel), [SatoshisPerKilobyte](./transaction.md#class-satoshisperkilobyte)
 

package/mod.ts

@@ -15,4 +15,5 @@ export * from './src/auth/index.js'
 export * from './src/overlay-tools/index.js'
 export * from './src/storage/index.js'
 export * from './src/identity/index.js'
-export * from './src/registry/index.js'
+export * from './src/registry/index.js'
+export * from './src/kvstore/index.js'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bsv/sdk",
-  "version": "1.4.13",
+  "version": "1.4.17",
   "type": "module",
   "description": "BSV Blockchain Software Development Kit",
   "main": "dist/cjs/mod.js",
@@ -194,6 +194,16 @@
       "require": "./dist/cjs/src/storage/*.js",
       "types": "./dist/types/src/storage/*.d.ts"
     },
+    "./kvstore": {
+      "import": "./dist/esm/src/kvstore/index.js",
+      "require": "./dist/cjs/src/kvstore/index.js",
+      "types": "./dist/types/src/kvstore/index.d.ts"
+    },
+    "./kvstore/*": {
+      "import": "./dist/esm/src/kvstore/*.js",
+      "require": "./dist/cjs/src/kvstore/*.js",
+      "types": "./dist/types/src/kvstore/*.d.ts"
+    },
     "./umd": {
       "import": "./dist/umd/bundle.js"
     }
@@ -229,23 +239,23 @@
   },
   "homepage": "https://github.com/bitcoin-sv/ts-sdk#readme",
   "devDependencies": {
-    "@eslint/js": "^9.19.0",
+    "@eslint/js": "^9.23.0",
     "@jest/globals": "^29.7.0",
     "@types/jest": "^29.5.14",
     "@types/node": "^22.13.14",
-    "eslint": "^8.57.1",
-    "globals": "^15.14.0",
+    "eslint": "^9.23.0",
+    "globals": "^16.0.0",
     "jest": "^29.7.0",
     "jest-environment-jsdom": "^29.7.0",
-    "ts-jest": "^29.1.1",
-    "ts-loader": "^9.5.1",
+    "ts-jest": "^29.3.1",
+    "ts-loader": "^9.5.2",
     "ts-standard": "^12.0.2",
     "ts2md": "^0.2.8",
     "tsconfig-to-dual-package": "^1.2.0",
     "typescript": "5.1",
-    "typescript-eslint": "^8.22.0",
-    "webpack": "^5.95.0",
-    "webpack-cli": "^5.1.4"
+    "typescript-eslint": "^8.29.0",
+    "webpack": "^5.98.0",
+    "webpack-cli": "^6.0.1"
   },
   "ts-standard": {
     "project": "tsconfig.eslint.json",

package/src/auth/clients/AuthFetch.ts

@@ -222,11 +222,13 @@ export class AuthFetch {
             config.retryCounter ??= 3
             const response = await this.fetch(url, config)
             resolve(response)
+            return
           }
           if (error.message.includes('HTTP server failed to authenticate')) {
             try {
               const response = await this.handleFetchAndValidate(url, config, peerToUse)
               resolve(response)
+              return
             } catch (fetchError) {
               reject(fetchError)
             }

package/src/auth/transports/SimplifiedFetchTransport.ts

@@ -126,23 +126,9 @@ export class SimplifiedFetchTransport implements Transport {
       })
 
       // Check for an acceptable status
-      if (!SUCCESS_STATUS_CODES.includes(response.status)) {
+      if (response.status === 500 && !response.headers.get('x-bsv-auth-request-id')) {
         // Try parsing JSON error
-        let errorInfo;
-        try {
-          errorInfo = await response.json();
-        } catch {
-          // Fallback to text if JSON parse fails
-          const text = await response.text().catch(() => '');
-          throw new Error(`HTTP ${response.status} - ${text || 'Unknown error'}`);
-        }
-
-        // If we find a known { status: 'error', code, description } structure
-        if (errorInfo?.status === 'error' && typeof errorInfo.description === 'string') {
-          const msg = `HTTP ${response.status} - ${errorInfo.description}`;
-          throw new Error(errorInfo.code ? `${msg} (code: ${errorInfo.code})` : msg);
-        }
-
+        const errorInfo = await response.json()
         // Otherwise just throw whatever we got
         throw new Error(`HTTP ${response.status} - ${JSON.stringify(errorInfo)}`);
       }