API

Links: API, Interfaces, Classes, Functions, Types, Enums, Variables

Interfaces


DownloadResult
DownloaderConfig
EstimateCostResult
FindFileData
HostScopeOptions
RenewFileResult
RenewPerHostResult
UploadFileResult
UploadableFile
UploaderConfig

Links: API, Interfaces, Classes, Functions, Types, Enums, Variables

Interface: DownloadResult

export interface DownloadResult {
    data: Uint8Array;
    mimeType: string | null;
}

Links: API, Interfaces, Classes, Functions, Types, Enums, Variables

Interface: DownloaderConfig

export interface DownloaderConfig {
    networkPreset: "mainnet" | "testnet" | "local";
}

Links: API, Interfaces, Classes, Functions, Types, Enums, Variables

Interface: EstimateCostResult

export interface EstimateCostResult {
    quotes: Array<{
        host: string;
        amount: number;
    }>;
    resilienceLevel: number;
    totalForResilience: number;
    meetsResilienceThreshold: boolean;
}

Property meetsResilienceThreshold

False when publishFile would throw without uploading.

meetsResilienceThreshold: boolean

Property quotes

Cheapest-first quotes from configured providers.

quotes: Array<{
    host: string;
    amount: number;
}>

Property totalForResilience

Sum of the cheapest resilienceLevel amounts (or all collected, if below threshold).

totalForResilience: number

Links: API, Interfaces, Classes, Functions, Types, Enums, Variables

Interface: FindFileData

export interface FindFileData {
    name: string;
    size: string;
    mimeType: string;
    expiryTime: number;
    hostedBy?: string[];
}

Property hostedBy

Providers that reported this UHRP URL. Omitted in single-host mode.

hostedBy?: string[]

Links: API, Interfaces, Classes, Functions, Types, Enums, Variables

Interface: HostScopeOptions

export interface HostScopeOptions {
    hostedBy?: string[];
}

Property hostedBy

Restrict the operation to this subset of configured providers.

hostedBy?: string[]

Links: API, Interfaces, Classes, Functions, Types, Enums, Variables

Interface: RenewFileResult

export interface RenewFileResult {
    status: string;
    prevExpiryTime?: number;
    newExpiryTime?: number;
    amount?: number;
    results?: RenewPerHostResult[];
}

Property amount

Total satoshis paid across every host that renewed.

amount?: number

Property results

Per-host outcomes. Omitted in single-host mode.

results?: RenewPerHostResult[]

Interface: RenewPerHostResult

export interface RenewPerHostResult {
    host: string;
    status: "success" | "error";
    prevExpiryTime?: number;
    newExpiryTime?: number;
    amount?: number;
    error?: string;
}

Links: API, Interfaces, Classes, Functions, Types, Enums, Variables

Interface: UploadFileResult

export interface UploadFileResult {
    published: boolean;
    uhrpURL: string;
    hostedBy: string[];
}

Property hostedBy

Providers that successfully hosted the file.

hostedBy: string[]

Links: API, Interfaces, Classes, Functions, Types, Enums, Variables

Interface: UploadableFile

export interface UploadableFile {
    data: Uint8Array | number[];
    type: string;
}

Links: API, Interfaces, Classes, Functions, Types, Enums, Variables

Interface: UploaderConfig

export interface UploaderConfig {
    storageURL?: string;
    storageURLs?: string[];
    resilienceLevel?: number;
    wallet: WalletInterface;
}

Property resilienceLevel

Minimum replicas to store the file on. Defaults to 1.

resilienceLevel?: number

Property storageURL

Legacy single-host URL. Mutually exclusive with storageURLs.

storageURL?: string

Property storageURLs

Explicit provider list. Takes precedence over storageURL.

storageURLs?: string[]

Links: API, Interfaces, Classes, Functions, Types, Enums, Variables

Classes


RenewResiliencyError
StorageDownloader
StorageUploader

Links: API, Interfaces, Classes, Functions, Types, Enums, Variables

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.

export class RenewResiliencyError extends Error {
    readonly results: RenewPerHostResult[];
    readonly requiredSuccesses: number;
    readonly successCount: number;
    constructor(message: string, results: RenewPerHostResult[], requiredSuccesses: number, successCount: number) 
}

Class: StorageDownloader

export class StorageDownloader {
    constructor(config?: DownloaderConfig) 
    public async resolve(uhrpUrl: string): Promise<string[]> 
    public async download(uhrpUrl: string): Promise<DownloadResult> 
}

Method download

Downloads the content from the UHRP URL after validating the hash for integrity.

public async download(uhrpUrl: string): Promise<DownloadResult>

Method resolve

Resolves the UHRP URL to a list of HTTP URLs where content can be downloaded.

public async resolve(uhrpUrl: string): Promise<string[]>

Returns

A promise that resolves to an array of HTTP URLs.

Argument Details

uhrpUrl
The UHRP URL to resolve.

Links: API, Interfaces, Classes, Functions, Types, Enums, Variables

Class: StorageUploader

Client for publishing, finding, listing, and renewing UHRP-hosted files across one or more storage providers.

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, options: HostScopeOptions = {}): Promise<FindFileData> 
    public async listUploads(options: HostScopeOptions = {}): Promise<any> 
    public async renewFile(uhrpUrl: string, additionalMinutes: number, options: HostScopeOptions = {}): Promise<RenewFileResult> 
}

Method estimateCost

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.

public async estimateCost(params: {
    fileSize: number;
    retentionPeriod: number;
}): Promise<EstimateCostResult>

Method findFile

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.

public async findFile(uhrpUrl: string, options: HostScopeOptions = {}): Promise<FindFileData>

See also: FindFileData, HostScopeOptions

Method listUploads

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.

public async listUploads(options: HostScopeOptions = {}): Promise<any>

Method publishFile

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.

public async publishFile(params: {
    file: UploadableFile;
    retentionPeriod: number;
}): Promise<UploadFileResult>

See also: UploadFileResult, UploadableFile

Links: API, Interfaces, Classes, Functions, Types, Enums, Variables

Functions

Types

Enums

Variables


DEFAULT_UHRP_SERVERS
getHashFromURL
getURLForFile
getURLForHash
isValidURL
normalizeURL

Links: API, Interfaces, Classes, Functions, Types, Enums, Variables

Variable: DEFAULT_UHRP_SERVERS

DEFAULT_UHRP_SERVERS: string[] = [
    "https://nanostore.babbage.systems",
    "https://bsv-storage-cloudflare.dev-a3e.workers.dev"
]

Links: API, Interfaces, Classes, Functions, Types, Enums, Variables

Variable: getHashFromURL

getHashFromURL = (URL: string): number[] => {
    URL = normalizeURL(URL);
    const { data, prefix } = fromBase58Check(URL, undefined, 2);
    if (data.length !== 32) {
        throw new Error("Invalid length!");
    }
    if (toHex(prefix as number[]) !== "ce00") {
        throw new Error("Bad prefix");
    }
    return data as number[];
}

See also: fromBase58Check, normalizeURL, toHex

Links: API, Interfaces, Classes, Functions, Types, Enums, Variables

Variable: getURLForFile

getURLForFile = (file: Uint8Array | number[]): string => {
    const data = file instanceof Uint8Array ? file : Uint8Array.from(file);
    const hasher = new Hash.SHA256();
    const chunkSize = 1024 * 1024;
    for (let i = 0; i < data.length; i += chunkSize) {
        const chunk = data.subarray(i, i + chunkSize);
        hasher.update(Array.from(chunk));
    }
    const hash = hasher.digest();
    return getURLForHash(hash);
}

Variable: getURLForHash

getURLForHash = (hash: number[]): string => {
    if (hash.length !== 32) {
        throw new Error("Hash length must be 32 bytes (sha256)");
    }
    return toBase58Check(hash, toArray("ce00", "hex"));
}

Variable: isValidURL

isValidURL = (URL: string): boolean => {
    try {
        getHashFromURL(URL);
        return true;
    }
    catch {
        return false;
    }
}

Variable: normalizeURL

normalizeURL = (URL: string): string => {
    if (URL.toLowerCase().startsWith("uhrp:"))
        URL = URL.slice(5);
    if (URL.startsWith("//"))
        URL = URL.slice(2);
    return URL;
}

Links: API, Interfaces, Classes, Functions, Types, Enums, Variables