wallet-toolbox

SERVICES: BSV Wallet Toolbox API Documentation

The documentation is split into various pages, this page covers the Services and related API.

To function properly, a wallet makes use of a variety of services provided by the network:

  1. Broadcast new transactions.
  2. Verify the validity of unspent outputs.
  3. Obtain mined transaction proofs.
  4. Obtain block headers for proof validation.
  5. Obtain exchange rates for UI and fee calculations.

These tasks are the responsibility of the Services class.

Return To Top

API

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

Interfaces

 
ArcConfig
ArcMinerGetTxData
BaseBlockHeader
BitailsConfig
BitailsMerkleProof
BlockHeader
ExchangeRatesIoApi
LiveBlockHeader

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

Interface: ArcConfig

Configuration options for the ARC broadcaster.

export interface ArcConfig {
    apiKey?: string;
    httpClient?: HttpClient;
    deploymentId?: string;
    callbackUrl?: string;
    callbackToken?: string;
    headers?: Record<string, string>;
}
Property apiKey

Authentication token for the ARC API

apiKey?: string
Property callbackToken

default access token for notification callback endpoint. It will be used as a Authorization header for the http callback

callbackToken?: string
Property callbackUrl

notification callback endpoint for proofs and double spend notification

callbackUrl?: string
Property deploymentId

Deployment id used annotating api calls in XDeployment-ID header - this value will be randomly generated if not set

deploymentId?: string
Property headers

additional headers to be attached to all tx submissions.

headers?: Record<string, string>
Property httpClient

The HTTP client used to make requests to the ARC API.

httpClient?: HttpClient

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

Interface: ArcMinerGetTxData
export interface ArcMinerGetTxData {
    status: number;
    title: string;
    blockHash: string;
    blockHeight: number;
    competingTxs: null | string[];
    extraInfo: string;
    merklePath: string;
    timestamp: string;
    txid: string;
    txStatus: string;
}

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

Interface: BaseBlockHeader

These are fields of 80 byte serialized header in order whose double sha256 hash is a block’s hash value and the next block’s previousHash value.

All block hash values and merkleRoot values are 32 byte hex string values with the byte order reversed from the serialized byte order.

export interface BaseBlockHeader {
    version: number;
    previousHash: string;
    merkleRoot: string;
    time: number;
    bits: number;
    nonce: number;
}
Property bits

Block header bits value. Serialized length is 4 bytes.

bits: number
Property merkleRoot

Root hash of the merkle tree of all transactions in this block. Serialized length is 32 bytes.

merkleRoot: string
Property nonce

Block header nonce value. Serialized length is 4 bytes.

nonce: number
Property previousHash

Hash of previous block’s block header. Serialized length is 32 bytes.

previousHash: string
Property time

Block header time value. Serialized length is 4 bytes.

time: number
Property version

Block header version value. Serialized length is 4 bytes.

version: number

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

Interface: BitailsConfig
export interface BitailsConfig {
    apiKey?: string;
    httpClient?: HttpClient;
}
Property apiKey

Authentication token for BitTails API

apiKey?: string
Property httpClient

The HTTP client used to make requests to the API.

httpClient?: HttpClient

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

Interface: BitailsMerkleProof
export interface BitailsMerkleProof {
    index: number;
    txOrId: string;
    target: string;
    nodes: string[];
}

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

Interface: BlockHeader

A BaseBlockHeader extended with its computed hash and height in its chain.

export interface BlockHeader extends BaseBlockHeader {
    height: number;
    hash: string;
}

See also: BaseBlockHeader

Property hash

The double sha256 hash of the serialized BaseBlockHeader fields.

hash: string
Property height

Height of the header, starting from zero.

height: number

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

Interface: ExchangeRatesIoApi
export interface ExchangeRatesIoApi {
    success: boolean;
    timestamp: number;
    base: "EUR" | "USD";
    date: string;
    rates: Record<string, number>;
}

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

Interface: LiveBlockHeader

The “live” portion of the block chain is recent history that can conceivably be subject to reorganizations. The additional fields support tracking orphan blocks, chain forks, and chain reorgs.

export interface LiveBlockHeader extends BlockHeader {
    chainWork: string;
    isChainTip: boolean;
    isActive: boolean;
    headerId: number;
    previousHeaderId: number | null;
}

See also: BlockHeader

Property chainWork

The cummulative chainwork achieved by the addition of this block to the chain. Chainwork only matters in selecting the active chain.

chainWork: string
Property headerId

As there may be more than one header with identical height values due to orphan tracking, headers are assigned a unique headerId while part of the “live” portion of the block chain.

headerId: number
Property isActive

True only if this header is currently on the active chain.

isActive: boolean
Property isChainTip

True only if this header is currently a chain tip. e.g. There is no header that follows it by previousHash or previousHeaderId.

isChainTip: boolean
Property previousHeaderId

Every header in the “live” portion of the block chain is linked to an ancestor header through both its previousHash and previousHeaderId properties.

Due to forks, there may be multiple headers with identical previousHash and previousHeaderId values. Of these, only one (the header on the active chain) will have isActive === true.

previousHeaderId: number | null

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

Classes

 
ARC
Bitails
SdkWhatsOnChain
ServiceCollection
Services
WhatsOnChain

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

Class: ARC

Represents an ARC transaction broadcaster.

export class ARC {
    readonly URL: string;
    readonly apiKey: string | undefined;
    readonly deploymentId: string;
    readonly callbackUrl: string | undefined;
    readonly callbackToken: string | undefined;
    readonly headers: Record<string, string> | undefined;
    constructor(URL: string, config?: ArcConfig);
    constructor(URL: string, apiKey?: string);
    constructor(URL: string, config?: string | ArcConfig) 
    async postRawTx(rawTx: HexString, txids?: string[]): Promise<sdk.PostTxResultForTxid> 
    async postBeef(beef: Beef, txids: string[]): Promise<sdk.PostBeefResult> 
    async getTxData(txid: string): Promise<ArcMinerGetTxData> 
}

See also: ArcConfig, ArcMinerGetTxData, PostBeefResult, PostTxResultForTxid

Constructor

Constructs an instance of the ARC broadcaster.

constructor(URL: string, config?: ArcConfig)

See also: ArcConfig

Argument Details

Constructor

Constructs an instance of the ARC broadcaster.

constructor(URL: string, apiKey?: string)

Argument Details

Method getTxData

This seems to only work for recently submitted txids…but that’s all we need to complete postBeef!

async getTxData(txid: string): Promise<ArcMinerGetTxData>

See also: ArcMinerGetTxData

Method postBeef

ARC does not natively support a postBeef end-point aware of multiple txids of interest in the Beef.

It does process multiple new transactions, however, which allows results for all txids of interest to be collected by the /v1/tx/${txid} endpoint.

async postBeef(beef: Beef, txids: string[]): Promise<sdk.PostBeefResult>

See also: PostBeefResult

Method postRawTx

The ARC ‘/v1/tx’ endpoint, as of 2025-02-17 supports all of the following hex string formats:

  1. Single serialized raw transaction.
  2. Single EF serialized raw transaction (untested).
  3. V1 serialized Beef (results returned reflect only the last transaction in the beef)

The ARC ‘/v1/tx’ endpoint, as of 2025-02-17 DOES NOT support the following hex string formats:

  1. V2 serialized Beef
async postRawTx(rawTx: HexString, txids?: string[]): Promise<sdk.PostTxResultForTxid>

See also: PostTxResultForTxid

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

Class: Bitails
export class Bitails {
    readonly chain: sdk.Chain;
    readonly apiKey: string;
    readonly URL: string;
    readonly httpClient: HttpClient;
    constructor(chain: sdk.Chain = "main", config: BitailsConfig = {}) 
    getHttpHeaders(): Record<string, string> 
    async postBeef(beef: Beef, txids: string[]): Promise<sdk.PostBeefResult> 
    async postRaws(raws: HexString[], txids?: string[]): Promise<sdk.PostBeefResult> 
    async getMerklePath(txid: string, services: sdk.WalletServices): Promise<sdk.GetMerklePathResult> 
}

See also: BitailsConfig, Chain, GetMerklePathResult, PostBeefResult, WalletServices

Method postBeef

Bitails does not natively support a postBeef end-point aware of multiple txids of interest in the Beef.

Send rawTx in txids order from beef.

async postBeef(beef: Beef, txids: string[]): Promise<sdk.PostBeefResult>

See also: PostBeefResult

Method postRaws
async postRaws(raws: HexString[], txids?: string[]): Promise<sdk.PostBeefResult>

See also: PostBeefResult

Argument Details

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

Class: SdkWhatsOnChain

Represents a chain tracker based on What’s On Chain .

export default class SdkWhatsOnChain implements ChainTracker {
    readonly network: string;
    readonly apiKey: string;
    protected readonly URL: string;
    protected readonly httpClient: HttpClient;
    constructor(network: "main" | "test" | "stn" = "main", config: WhatsOnChainConfig = {}) 
    async isValidRootForHeight(root: string, height: number): Promise<boolean> 
    async currentHeight(): Promise<number> 
    protected getHttpHeaders(): Record<string, string> 
}
Constructor

Constructs an instance of the WhatsOnChain ChainTracker.

constructor(network: "main" | "test" | "stn" = "main", config: WhatsOnChainConfig = {})

Argument Details

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

Class: ServiceCollection
export class ServiceCollection<T> {
    services: {
        name: string;
        service: T;
    }[];
    _index: number;
    constructor(services?: {
        name: string;
        service: T;
    }[]) 
    add(s: {
        name: string;
        service: T;
    }): ServiceCollection<T> 
    remove(name: string): void 
    get name() 
    get service() 
    get allServices() 
    get count() 
    get index() 
    reset() 
    next(): number 
    clone(): ServiceCollection<T> 
}

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

Class: Services
export class Services implements sdk.WalletServices {
    static createDefaultOptions(chain: sdk.Chain): sdk.WalletServicesOptions 
    options: sdk.WalletServicesOptions;
    whatsonchain: WhatsOnChain;
    arc: ARC;
    bitails: Bitails;
    getMerklePathServices: ServiceCollection<sdk.GetMerklePathService>;
    getRawTxServices: ServiceCollection<sdk.GetRawTxService>;
    postBeefServices: ServiceCollection<sdk.PostBeefService>;
    getUtxoStatusServices: ServiceCollection<sdk.GetUtxoStatusService>;
    getStatusForTxidsServices: ServiceCollection<sdk.GetStatusForTxidsService>;
    getScriptHashHistoryServices: ServiceCollection<sdk.GetScriptHashHistoryService>;
    updateFiatExchangeRateServices: ServiceCollection<sdk.UpdateFiatExchangeRateService>;
    chain: sdk.Chain;
    constructor(optionsOrChain: sdk.Chain | sdk.WalletServicesOptions) 
    async getChainTracker(): Promise<ChainTracker> 
    async getBsvExchangeRate(): Promise<number> 
    async getFiatExchangeRate(currency: "USD" | "GBP" | "EUR", base?: "USD" | "GBP" | "EUR"): Promise<number> 
    get getProofsCount() 
    get getRawTxsCount() 
    get postBeefServicesCount() 
    get getUtxoStatsCount() 
    async getStatusForTxids(txids: string[], useNext?: boolean): Promise<sdk.GetStatusForTxidsResult> 
    hashOutputScript(script: string): string 
    async getUtxoStatus(output: string, outputFormat?: sdk.GetUtxoStatusOutputFormat, outpoint?: string, useNext?: boolean): Promise<sdk.GetUtxoStatusResult> 
    async getScriptHashHistory(hash: string, useNext?: boolean): Promise<sdk.GetScriptHashHistoryResult> 
    postBeefCount = 0;
    async postBeef(beef: Beef, txids: string[]): Promise<sdk.PostBeefResult[]> 
    async getRawTx(txid: string, useNext?: boolean): Promise<sdk.GetRawTxResult> 
    async invokeChaintracksWithRetry<R>(method: () => Promise<R>): Promise<R> 
    async getHeaderForHeight(height: number): Promise<number[]> 
    async getHeight(): Promise<number> 
    async hashToHeader(hash: string): Promise<sdk.BlockHeader> 
    async getMerklePath(txid: string, useNext?: boolean): Promise<sdk.GetMerklePathResult> 
    targetCurrencies = ["USD", "GBP", "EUR"];
    async updateFiatExchangeRates(rates?: sdk.FiatExchangeRates, updateMsecs?: number): Promise<sdk.FiatExchangeRates> 
    async nLockTimeIsFinal(tx: string | number[] | BsvTransaction | number): Promise<boolean> 
}

See also: ARC, Bitails, BlockHeader, Chain, FiatExchangeRates, GetMerklePathResult, GetMerklePathService, GetRawTxResult, GetRawTxService, GetScriptHashHistoryResult, GetScriptHashHistoryService, GetStatusForTxidsResult, GetStatusForTxidsService, GetUtxoStatusOutputFormat, GetUtxoStatusResult, GetUtxoStatusService, PostBeefResult, PostBeefService, ServiceCollection, UpdateFiatExchangeRateService, WalletServices, WalletServicesOptions, WhatsOnChain

Method hashOutputScript
hashOutputScript(script: string): string

Returns

script hash in ‘hashLE’ format, which is the default.

Argument Details

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

Class: WhatsOnChain
export class WhatsOnChain extends SdkWhatsOnChain {
    services: Services;
    constructor(chain: sdk.Chain = "main", config: WhatsOnChainConfig = {}, services?: Services) 
    async getStatusForTxids(txids: string[]): Promise<sdk.GetStatusForTxidsResult> 
    async getTxPropagation(txid: string): Promise<number> 
    async getRawTx(txid: string): Promise<string | undefined> 
    async getRawTxResult(txid: string): Promise<sdk.GetRawTxResult> 
    async postBeef(beef: Beef, txids: string[]): Promise<sdk.PostBeefResult> 
    async postRawTx(rawTx: HexString): Promise<sdk.PostTxResultForTxid> 
    async getMerklePath(txid: string, services: sdk.WalletServices): Promise<sdk.GetMerklePathResult> 
    async updateBsvExchangeRate(rate?: sdk.BsvExchangeRate, updateMsecs?: number): Promise<sdk.BsvExchangeRate> 
    async getUtxoStatus(output: string, outputFormat?: sdk.GetUtxoStatusOutputFormat, outpoint?: string): Promise<sdk.GetUtxoStatusResult> 
    async getScriptHashConfirmedHistory(hash: string): Promise<sdk.GetScriptHashHistoryResult> 
    async getScriptHashUnconfirmedHistory(hash: string): Promise<sdk.GetScriptHashHistoryResult> 
    async getScriptHashHistory(hash: string): Promise<sdk.GetScriptHashHistoryResult> 
}

See also: BsvExchangeRate, Chain, GetMerklePathResult, GetRawTxResult, GetScriptHashHistoryResult, GetStatusForTxidsResult, GetUtxoStatusOutputFormat, GetUtxoStatusResult, PostBeefResult, PostTxResultForTxid, SdkWhatsOnChain, Services, WalletServices

Method getRawTx

May return undefined for unmined transactions that are in the mempool.

async getRawTx(txid: string): Promise<string | undefined>

Returns

raw transaction as hex string or undefined if txid not found in mined block.

Method getStatusForTxids

POST https://api.whatsonchain.com/v1/bsv/main/txs/status Content-Type: application/json data: “{"txids":["6815f8014db74eab8b7f75925c68929597f1d97efa970109d990824c25e5e62b"]}”

result for a mined txid: [{ “txid”:”294cd1ebd5689fdee03509f92c32184c0f52f037d4046af250229b97e0c8f1aa”, “blockhash”:”000000000000000004b5ce6670f2ff27354a1e87d0a01bf61f3307f4ccd358b5”, “blockheight”:612251, “blocktime”:1575841517, “confirmations”:278272 }]

result for a valid recent txid: [{“txid”:”6815f8014db74eab8b7f75925c68929597f1d97efa970109d990824c25e5e62b”}]

result for an unknown txid: [{“txid”:”6815f8014db74eab8b7f75925c68929597f1d97efa970109d990824c25e5e62c”,”error”:”unknown”}]

async getStatusForTxids(txids: string[]): Promise<sdk.GetStatusForTxidsResult>

See also: GetStatusForTxidsResult

Method getTxPropagation

2025-02-16 throwing internal server error 500.

async getTxPropagation(txid: string): Promise<number>
Method postBeef

WhatsOnChain does not natively support a postBeef end-point aware of multiple txids of interest in the Beef.

Send rawTx in txids order from beef.

async postBeef(beef: Beef, txids: string[]): Promise<sdk.PostBeefResult>

See also: PostBeefResult

Method postRawTx
async postRawTx(rawTx: HexString): Promise<sdk.PostTxResultForTxid>

See also: PostTxResultForTxid

Returns

txid returned by transaction processor of transaction broadcast

Argument Details

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

Functions

 
arcDefaultUrl
createDefaultWalletServicesOptions
getExchangeRatesIo
isBaseBlockHeader
isBlockHeader
isLive
isLiveBlockHeader
toBinaryBaseBlockHeader
updateChaintracksFiatExchangeRates
updateExchangeratesapi
validateScriptHash

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

Function: arcDefaultUrl
export function arcDefaultUrl(chain: sdk.Chain): string

See also: Chain

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

Function: createDefaultWalletServicesOptions
export function createDefaultWalletServicesOptions(chain: sdk.Chain): sdk.WalletServicesOptions

See also: Chain, WalletServicesOptions

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

Function: getExchangeRatesIo
export async function getExchangeRatesIo(key: string): Promise<ExchangeRatesIoApi>

See also: ExchangeRatesIoApi

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

Function: isBaseBlockHeader

Type guard function.

export function isBaseBlockHeader(header: BaseBlockHeader | BlockHeader | LiveBlockHeader): header is BaseBlockHeader {
    return typeof header.previousHash === "string";
}

See also: BaseBlockHeader, BlockHeader, LiveBlockHeader

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

Function: isBlockHeader

Type guard function.

export function isBlockHeader(header: BaseBlockHeader | BlockHeader | LiveBlockHeader): header is LiveBlockHeader {
    return "height" in header && typeof header.previousHash === "string";
}

See also: BaseBlockHeader, BlockHeader, LiveBlockHeader

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

Function: isLive

Type guard function.

export function isLive(header: BlockHeader | LiveBlockHeader): header is LiveBlockHeader {
    return (header as LiveBlockHeader).headerId !== undefined;
}

See also: BlockHeader, LiveBlockHeader

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

Function: isLiveBlockHeader

Type guard function.

export function isLiveBlockHeader(header: BaseBlockHeader | BlockHeader | LiveBlockHeader): header is LiveBlockHeader {
    return "chainwork" in header && typeof header.previousHash === "string";
}

See also: BaseBlockHeader, BlockHeader, LiveBlockHeader

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

Function: toBinaryBaseBlockHeader

Serializes a block header as an 80 byte array. The exact serialized format is defined in the Bitcoin White Paper such that computing a double sha256 hash of the array computes the block hash for the header.

export function toBinaryBaseBlockHeader(header: sdk.BaseBlockHeader): number[] {
    const writer = new Utils.Writer();
    writer.writeUInt32BE(header.version);
    writer.writeReverse(asArray(header.previousHash));
    writer.writeReverse(asArray(header.merkleRoot));
    writer.writeUInt32BE(header.time);
    writer.writeUInt32BE(header.bits);
    writer.writeUInt32BE(header.nonce);
    const r = writer.toArray();
    return r;
}

See also: BaseBlockHeader, asArray

Returns

80 byte array

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

Function: updateChaintracksFiatExchangeRates
export async function updateChaintracksFiatExchangeRates(targetCurrencies: string[], options: sdk.WalletServicesOptions): Promise<sdk.FiatExchangeRates>

See also: FiatExchangeRates, WalletServicesOptions

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

Function: updateExchangeratesapi
export async function updateExchangeratesapi(targetCurrencies: string[], options: sdk.WalletServicesOptions): Promise<sdk.FiatExchangeRates>

See also: FiatExchangeRates, WalletServicesOptions

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

Function: validateScriptHash
export function validateScriptHash(output: string, outputFormat?: sdk.GetUtxoStatusOutputFormat): string

See also: GetUtxoStatusOutputFormat

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

Types

Variables

This site is open source. Improve this page.