@bsv/sdk 2.0.12 → 2.0.14

package/docs/index.md

@@ -29,6 +29,8 @@ const { WalletClient, PrivateKey, Transaction } = require("@bsv/sdk");
 
 This interface is what most application developers will use to interact with the BSV blockchain.
 
+BSV Desktop and BSV Browser are the BSV Association reference implementations for BRC-100. Vendor distributions, including Babbage's Metanet Desktop / Metanet Explorer and Hudos Browser, can implement the same interface with their own branding and service defaults.
+
 🚀 **[WalletClient Quickstart](https://fast.brc.dev/)**
 
 - Run SDK code examples without any setup
@@ -53,7 +55,7 @@ Finally, you can deep dive into the details of the interface and types in the re
 - [Primitives](./reference/primitives.md)
 - [Script](./reference/script.md)
 - [Transaction](./reference/transaction.md)
-- [Mutual Authenitcation](./reference/auth.md)
+- [Mutual Authentication](./reference/auth.md)
 - [Identity](./reference/identity.md)
 - [Overlay Tools](./reference/overlay-tools.md)
 - [Registry](./reference/registry.md)

package/docs/reference/identity.md

@@ -372,7 +372,7 @@ defaultIdentity: DisplayableIdentity = {
     abbreviatedKey: "",
     badgeIconURL: "XUUV39HVPkpmMzYNTx7rpKzJvXfeiVyQWg2vfSpjBAuhunTCA9uG",
     badgeLabel: "Not verified by anyone you trust.",
-    badgeClickURL: "https://projectbabbage.com/docs/unknown-identity"
+    badgeClickURL: "https://bsv-blockchain.github.io/ts-sdk/reference/identity/"
 }
 ```
 

package/docs/reference/storage.md

@@ -8,8 +8,11 @@ Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](
 | --- |
 | [DownloadResult](#interface-downloadresult) |
 | [DownloaderConfig](#interface-downloaderconfig) |
+| [EstimateCostResult](#interface-estimatecostresult) |
 | [FindFileData](#interface-findfiledata) |
+| [HostScopeOptions](#interface-hostscopeoptions) |
 | [RenewFileResult](#interface-renewfileresult) |
+| [RenewPerHostResult](#interface-renewperhostresult) |
 | [UploadFileResult](#interface-uploadfileresult) |
 | [UploadableFile](#interface-uploadablefile) |
 | [UploaderConfig](#interface-uploaderconfig) |
@@ -40,6 +43,50 @@ export interface DownloaderConfig {
 
 Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Enums](#enums), [Variables](#variables)
 
+---
+### Interface: EstimateCostResult
+
+```ts
+export interface EstimateCostResult {
+    quotes: Array<{
+        host: string;
+        amount: number;
+    }>;
+    resilienceLevel: number;
+    totalForResilience: number;
+    meetsResilienceThreshold: boolean;
+}
+```
+
+#### Property meetsResilienceThreshold
+
+False when `publishFile` would throw without uploading.
+
+```ts
+meetsResilienceThreshold: boolean
+```
+
+#### Property quotes
+
+Cheapest-first quotes from configured providers.
+
+```ts
+quotes: Array<{
+    host: string;
+    amount: number;
+}>
+```
+
+#### Property totalForResilience
+
+Sum of the cheapest `resilienceLevel` amounts (or all collected, if below threshold).
+
+```ts
+totalForResilience: number
+```
+
+Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Enums](#enums), [Variables](#variables)
+
 ---
 ### Interface: FindFileData
 
@@ -49,9 +96,37 @@ export interface FindFileData {
     size: string;
     mimeType: string;
     expiryTime: number;
+    hostedBy?: string[];
+}
+```
+
+#### Property hostedBy
+
+Providers that reported this UHRP URL. Omitted in single-host mode.
+
+```ts
+hostedBy?: string[]
+```
+
+Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Enums](#enums), [Variables](#variables)
+
+---
+### Interface: HostScopeOptions
+
+```ts
+export interface HostScopeOptions {
+    hostedBy?: string[];
 }
 ```
 
+#### Property hostedBy
+
+Restrict the operation to this subset of configured providers.
+
+```ts
+hostedBy?: string[]
+```
+
 Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Enums](#enums), [Variables](#variables)
 
 ---
@@ -63,6 +138,42 @@ export interface RenewFileResult {
     prevExpiryTime?: number;
     newExpiryTime?: number;
     amount?: number;
+    results?: RenewPerHostResult[];
+}
+```
+
+See also: [RenewPerHostResult](./storage.md#interface-renewperhostresult)
+
+#### Property amount
+
+Total satoshis paid across every host that renewed.
+
+```ts
+amount?: number
+```
+
+#### Property results
+
+Per-host outcomes. Omitted in single-host mode.
+
+```ts
+results?: RenewPerHostResult[]
+```
+See also: [RenewPerHostResult](./storage.md#interface-renewperhostresult)
+
+Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Enums](#enums), [Variables](#variables)
+
+---
+### Interface: RenewPerHostResult
+
+```ts
+export interface RenewPerHostResult {
+    host: string;
+    status: "success" | "error";
+    prevExpiryTime?: number;
+    newExpiryTime?: number;
+    amount?: number;
+    error?: string;
 }
 ```
 
@@ -75,9 +186,18 @@ Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](
 export interface UploadFileResult {
     published: boolean;
     uhrpURL: string;
+    hostedBy: string[];
 }
 ```
 
+#### Property hostedBy
+
+Providers that successfully hosted the file.
+
+```ts
+hostedBy: string[]
+```
+
 Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Enums](#enums), [Variables](#variables)
 
 ---
@@ -97,13 +217,39 @@ Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](
 
 ```ts
 export interface UploaderConfig {
-    storageURL: string;
+    storageURL?: string;
+    storageURLs?: string[];
+    resilienceLevel?: number;
     wallet: WalletInterface;
 }
 ```
 
 See also: [WalletInterface](./wallet.md#interface-walletinterface)
 
+#### Property resilienceLevel
+
+Minimum replicas to store the file on. Defaults to 1.
+
+```ts
+resilienceLevel?: number
+```
+
+#### Property storageURL
+
+Legacy single-host URL. Mutually exclusive with `storageURLs`.
+
+```ts
+storageURL?: string
+```
+
+#### Property storageURLs
+
+Explicit provider list. Takes precedence over `storageURL`.
+
+```ts
+storageURLs?: string[]
+```
+
 Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Enums](#enums), [Variables](#variables)
 
 ---
@@ -111,6 +257,7 @@ Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](
 
 | |
 | --- |
+| [RenewResiliencyError](#class-renewresiliencyerror) |
 | [StorageDownloader](#class-storagedownloader) |
 | [StorageUploader](#class-storageuploader) |
 
@@ -118,6 +265,26 @@ Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](
 
 ---
 
+### Class: RenewResiliencyError
+
+Thrown by `renewFile` when successful renewals fall below the resilience
+threshold. Per-host outcomes are attached so callers can reconcile which
+providers were billed.
+
+```ts
+export class RenewResiliencyError extends Error {
+    readonly results: RenewPerHostResult[];
+    readonly requiredSuccesses: number;
+    readonly successCount: number;
+    constructor(message: string, results: RenewPerHostResult[], requiredSuccesses: number, successCount: number) 
+}
+```
+
+See also: [RenewPerHostResult](./storage.md#interface-renewperhostresult)
+
+Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Enums](#enums), [Variables](#variables)
+
+---
 ### Class: StorageDownloader
 
 ```ts
@@ -170,87 +337,70 @@ Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](
 ---
 ### Class: StorageUploader
 
-The StorageUploader class provides client-side methods for:
-- Uploading files with a specified retention period
-- Finding file metadata by UHRP URL
-- Listing all user uploads
-- Renewing an existing advertisement's expiry time
+Client for publishing, finding, listing, and renewing UHRP-hosted files
+across one or more storage providers.
 
 ```ts
 export class StorageUploader {
     constructor(config: UploaderConfig) 
+    public async estimateCost(params: {
+        fileSize: number;
+        retentionPeriod: number;
+    }): Promise<EstimateCostResult> 
     public async publishFile(params: {
         file: UploadableFile;
         retentionPeriod: number;
     }): Promise<UploadFileResult> 
-    public async findFile(uhrpUrl: string): Promise<FindFileData> 
-    public async listUploads(): Promise<any> 
-    public async renewFile(uhrpUrl: string, additionalMinutes: number): Promise<RenewFileResult> 
+    public async findFile(uhrpUrl: string, options: HostScopeOptions = {}): Promise<FindFileData> 
+    public async listUploads(options: HostScopeOptions = {}): Promise<any> 
+    public async renewFile(uhrpUrl: string, additionalMinutes: number, options: HostScopeOptions = {}): Promise<RenewFileResult> 
 }
 ```
 
-See also: [FindFileData](./storage.md#interface-findfiledata), [RenewFileResult](./storage.md#interface-renewfileresult), [UploadFileResult](./storage.md#interface-uploadfileresult), [UploadableFile](./storage.md#interface-uploadablefile), [UploaderConfig](./storage.md#interface-uploaderconfig)
+See also: [EstimateCostResult](./storage.md#interface-estimatecostresult), [FindFileData](./storage.md#interface-findfiledata), [HostScopeOptions](./storage.md#interface-hostscopeoptions), [RenewFileResult](./storage.md#interface-renewfileresult), [UploadFileResult](./storage.md#interface-uploadfileresult), [UploadableFile](./storage.md#interface-uploadablefile), [UploaderConfig](./storage.md#interface-uploaderconfig)
 
-#### Constructor
+#### Method estimateCost
 
-Creates a new StorageUploader instance.
+Queries the unauthenticated `/quote` endpoint on up to `2 * resilienceLevel`
+providers and returns the cheapest-first quote list plus the aggregate
+cost `publishFile` would pay. No provider is billed.
 
 ```ts
-constructor(config: UploaderConfig) 
+public async estimateCost(params: {
+    fileSize: number;
+    retentionPeriod: number;
+}): Promise<EstimateCostResult> 
 ```
-See also: [UploaderConfig](./storage.md#interface-uploaderconfig)
-
-Argument Details
-
-+ **config**
-  + An object containing the storage server's URL and a wallet interface
+See also: [EstimateCostResult](./storage.md#interface-estimatecostresult)
 
 #### Method findFile
 
-Retrieves metadata for a file matching the given UHRP URL from the `/find` route.
+Fans `/find` out across configured hosts (UHRP storage is host-local,
+so any one host may not know the file) and returns the record with the
+longest remaining expiry. Single-host configurations preserve the
+legacy error-message contract verbatim.
 
 ```ts
-public async findFile(uhrpUrl: string): Promise<FindFileData> 
+public async findFile(uhrpUrl: string, options: HostScopeOptions = {}): Promise<FindFileData> 
 ```
-See also: [FindFileData](./storage.md#interface-findfiledata)
-
-Returns
-
-An object with file name, size, MIME type, and expiry time
-
-Argument Details
-
-+ **uhrpUrl**
-  + The UHRP URL, e.g. "uhrp://abcd..."
-
-Throws
-
-If the server or the route returns an error
+See also: [FindFileData](./storage.md#interface-findfiledata), [HostScopeOptions](./storage.md#interface-hostscopeoptions)
 
 #### Method listUploads
 
-Lists all advertisements belonging to the user from the `/list` route.
+Unions `/list` output across configured hosts, merging duplicate UHRP
+URLs by the longest expiry observed. One failing host does not hide
+the rest. Single-host configurations preserve the legacy error contract.
 
 ```ts
-public async listUploads(): Promise<any> 
+public async listUploads(options: HostScopeOptions = {}): Promise<any> 
 ```
-
-Returns
-
-The array of uploads returned by the server
-
-Throws
-
-If the server or the route returns an error
+See also: [HostScopeOptions](./storage.md#interface-hostscopeoptions)
 
 #### Method publishFile
 
-Publishes a file to the storage server with the specified retention period.
-
-This will:
-1. Request an upload URL from the server.
-2. Perform an HTTP PUT to upload the file’s raw bytes.
-3. Return a UHRP URL referencing the file once published.
+Publishes a file across the cheapest configured providers, falling
+through to the next-cheapest quote if a paid upload fails. Throws when
+the resilience threshold cannot be met.
 
 ```ts
 public async publishFile(params: {
@@ -260,40 +410,6 @@ public async publishFile(params: {
 ```
 See also: [UploadFileResult](./storage.md#interface-uploadfileresult), [UploadableFile](./storage.md#interface-uploadablefile)
 
-Returns
-
-An object with the file's UHRP URL
-
-Throws
-
-If the server or upload step returns a non-OK response
-
-#### Method renewFile
-
-Renews the hosting time for an existing file advertisement identified by uhrpUrl.
-Calls the `/renew` route to add `additionalMinutes` to the GCS customTime
-and re-mint the advertisement token on-chain.
-
-```ts
-public async renewFile(uhrpUrl: string, additionalMinutes: number): Promise<RenewFileResult> 
-```
-See also: [RenewFileResult](./storage.md#interface-renewfileresult)
-
-Returns
-
-An object with the new and previous expiry times, plus any cost
-
-Argument Details
-
-+ **uhrpUrl**
-  + The UHRP URL of the file (e.g., "uhrp://abcd1234...")
-+ **additionalMinutes**
-  + The number of minutes to extend
-
-Throws
-
-If the request fails or the server returns an error
-
 Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Enums](#enums), [Variables](#variables)
 
 ---
@@ -307,6 +423,7 @@ Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](
 
 | |
 | --- |
+| [DEFAULT_UHRP_SERVERS](#variable-default_uhrp_servers) |
 | [getHashFromURL](#variable-gethashfromurl) |
 | [getURLForFile](#variable-geturlforfile) |
 | [getURLForHash](#variable-geturlforhash) |
@@ -317,6 +434,18 @@ Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](
 
 ---
 
+### Variable: DEFAULT_UHRP_SERVERS
+
+```ts
+DEFAULT_UHRP_SERVERS: string[] = [
+    "https://nanostore.babbage.systems",
+    "https://bsv-storage-cloudflare.dev-a3e.workers.dev"
+]
+```
+
+Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Enums](#enums), [Variables](#variables)
+
+---
 ### Variable: getHashFromURL
 
 ```ts
@@ -383,7 +512,7 @@ isValidURL = (URL: string): boolean => {
         getHashFromURL(URL);
         return true;
     }
-    catch (e) {
+    catch {
         return false;
     }
 }

package/docs/reference/transaction.md

@@ -1374,6 +1374,7 @@ export default class MerklePath {
     async verify(txid: string, chainTracker: ChainTracker): Promise<boolean> 
     combine(other: MerklePath): void 
     trim(): void 
+    extract(txids: string[]): MerklePath 
 }
 ```
 
@@ -1418,6 +1419,45 @@ Throws
 
 - If the transaction ID is not part of the Merkle Path.
 
+#### Method extract
+
+Extracts a minimal compound MerklePath covering only the specified transaction IDs.
+
+Given a compound MerklePath (e.g. all block txids at level 0, or a trimmed
+compound path), this method reconstructs the sibling hashes at each tree level
+for every requested txid using cached Map-indexed lookups, then assembles them
+into a single trimmed compound path.
+
+The extracted path is verified to compute the same Merkle root as the source.
+
+```ts
+extract(txids: string[]): MerklePath 
+```
+See also: [MerklePath](./transaction.md#class-merklepath)
+
+Returns
+
+- A new trimmed compound MerklePath covering only the requested txids.
+
+Argument Details
+
++ **txids**
+  + Transaction IDs to extract proofs for.
+
+Throws
+
+- If no txids are provided, a txid is not found, or the roots do not match.
+
+Example
+
+```ts
+// Full block compound path (all txids at level 0)
+const fullBlock = new MerklePath(height, [allTxidsAtLevel0])
+// Extract a smaller compound proof covering just two transactions
+const twoTxProof = fullBlock.extract([txid1, txid2])
+twoTxProof.computeRoot(txid1) // === fullBlock.computeRoot()
+```
+
 #### Method findOrComputeLeaf
 
 Find leaf with `offset` at `height` or compute from level below, recursively.

package/docs/reference/wallet.md

@@ -2930,7 +2930,7 @@ Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](
 ### Class: WERR_REVIEW_ACTIONS
 
 When a `createAction` or `signAction` is completed in undelayed mode (`acceptDelayedBroadcast`: false),
-any unsucccessful result will return the results by way of this exception to ensure attention is
+any unsuccessful result will return the results by way of this exception to ensure attention is
 paid to processing errors.
 
 ```ts
@@ -2945,7 +2945,7 @@ See also: [AtomicBEEF](./wallet.md#type-atomicbeef), [OutpointString](./wallet.m
 
 #### Constructor
 
-All parameters correspond to their comparable `createAction` or `signSction` results
+All parameters correspond to their comparable `createAction` or `signAction` results
 with the exception of `reviewActionResults`;
 which contains more details, particularly for double spend results.
 
@@ -5063,10 +5063,10 @@ Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](
 ### Type: ReviewActionResultStatus
 
 Indicates status of a new Action following a `createAction` or `signAction` in immediate mode:
-When `acceptDelayedBroadcast` is falses.
+When `acceptDelayedBroadcast` is false.
 
 'success': The action has been broadcast and accepted by the bitcoin processing network.
-'doulbeSpend': The action has been confirmed to double spend one or more inputs, and by the "first-seen-rule" is the loosing transaction.
+'doubleSpend': The action has been confirmed to double spend one or more inputs, and by the "first-seen-rule" is the losing transaction.
 'invalidTx': The action was rejected by the processing network as an invalid bitcoin transaction.
 'serviceError': The broadcast services are currently unable to reach the bitcoin network. The action is now queued for delayed retries.
 

package/package.json

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