cwi-external-services
Advanced tools
Readme
Implementations of external service APIs.
Standardized service APIs for use within CWI.
Links: API, Interfaces, Classes, Functions, Types
Links: API, Interfaces, Classes, Functions, Types
As defined in https://github.com/bitcoin-sv-specs/brfc-merchantapi/blob/master/README.md
export interface MapiTxStatusPayloadApi {
apiVersion: string;
timestamp: string;
txid: string;
returnResult: string;
blockHash: string;
blockHeight: number;
confirmations: number;
minerId: string;
txSecondMempoolExpiry: number;
merkleProof?: TscMerkleProofApi;
}
Links: API, Interfaces, Classes, Functions, Types
As defined in https://github.com/bitcoin-sv-specs/brfc-merchantapi/blob/master/README.md
export interface MapiCallbackPayloadApi {
apiVersion: string;
timestamp: string;
blockHash: string;
blockHeight: number;
callbackTxId: string;
callbackReason: string;
callbackPayload: string;
}
Links: API, Interfaces, Classes, Functions, Types
Used to parse payloads when only confirmation that a miner acknowledges a specific txid matters.
export interface MapiTxidReturnResultApi {
apiVersion?: string;
timestamp?: string;
txid: string;
returnResult: string;
}
Links: API, Interfaces, Classes, Functions, Types
As defined in https://github.com/bitcoin-sv-specs/brfc-merchantapi/blob/master/README.md
export interface MapiPostTxPayloadApi {
apiVersion: string;
timestamp: string;
txid: string;
returnResult: string;
resultDescription: string;
minerId: string;
currentHighestBlockHash?: string;
currentHighestBlockHeight?: number;
txSecondMempoolExpiry?: number;
failureRetryable?: boolean;
warnings?: unknown[];
conflictedWith?: unknown[];
}
Links: API, Interfaces, Classes, Functions, Types
export interface PostTransactionMapiMinerApi {
name: string;
url: string;
authType: "none" | "bearer";
authToken?: string;
}
Links: API, Interfaces, Classes, Functions, Types
export interface ExchangeRatesIoApi {
success: boolean;
timestamp: number;
base: "EUR" | "USD";
date: string;
rates: Record<string, number>;
}
Links: API, Interfaces, Classes, Functions, Types
export interface CwiExternalServicesOptions {
mainTaalApiKey?: string;
testTaalApiKey?: string;
bsvExchangeRate: BsvExchangeRateApi;
bsvUpdateMsecs: number;
fiatExchangeRates: FiatExchangeRatesApi;
fiatUpdateMsecs: number;
disableMapiCallback?: boolean;
exchangeratesapiKey?: string;
chaintracksFiatExchangeRatesUrl?: string;
}
Links: API, Interfaces, Classes, Functions, Types
Defines standard interfaces to access functionality implemented by external transaction processing services.
export interface CwiExternalServicesApi {
getBsvExchangeRate(): Promise<number>;
getFiatExchangeRate(currency: "USD" | "GBP" | "EUR", base?: "USD" | "GBP" | "EUR"): Promise<number>;
getRawTx(txid: string | Buffer, chain: Chain, useNext?: boolean): Promise<GetRawTxResultApi>;
getTransaction(txid: string | Buffer, chain: Chain, useNext?: boolean): Promise<Transaction>;
getTransactionOutput(vout: number, txid: string | Buffer, chain: Chain, useNext?: boolean): Promise<TransactionOutput>;
getMerkleProof(txid: string | Buffer, chain: Chain, useNext?: boolean): Promise<GetMerkleProofResultApi>;
postRawTx(rawTx: string | Buffer, chain: Chain, callback?: MapiCallbackApi): Promise<PostRawTxResultApi[]>;
getUtxoStatus(output: string | Buffer, chain: Chain, outputFormat?: GetUtxoStatusOutputFormatApi, useNext?: boolean): Promise<GetUtxoStatusResultApi>;
}
Approximate exchange rate US Dollar / BSV, USD / BSV
This is the US Dollar price of one BSV
getBsvExchangeRate(): Promise<number>
Approximate exchange rate currency per base.
getFiatExchangeRate(currency: "USD" | "GBP" | "EUR", base?: "USD" | "GBP" | "EUR"): Promise<number>
Attempts to obtain the merkle proof associated with a 32 byte transaction hash (txid).
Cycles through configured transaction processing services attempting to get a valid response.
On success: Result txid is the requested transaction hash Result proof will be the merkle proof. Result name will be the responding service's identifying name. Returns result without incrementing active service.
On failure: Result txid is the requested transaction hash Result mapi will be the first mapi response obtained (service name and response), or null Result error will be the first error thrown (service name and CwiError), or null Increments to next configured service and tries again until all services have been tried.
getMerkleProof(txid: string | Buffer, chain: Chain, useNext?: boolean): Promise<GetMerkleProofResultApi>
Argument Details
Attempts to obtain the raw transaction bytes associated with a 32 byte transaction hash (txid).
Cycles through configured transaction processing services attempting to get a valid response.
On success: Result txid is the requested transaction hash Result rawTx will be Buffer containing raw transaction bytes. Result name will be the responding service's identifying name. Returns result without incrementing active service.
On failure: Result txid is the requested transaction hash Result mapi will be the first mapi response obtained (service name and response), or null Result error will be the first error thrown (service name and CwiError), or null Increments to next configured service and tries again until all services have been tried.
getRawTx(txid: string | Buffer, chain: Chain, useNext?: boolean): Promise<GetRawTxResultApi>
Argument Details
Typically uses getRawTx to lookup a raw transaction to return a parsed Transaction.
getTransaction(txid: string | Buffer, chain: Chain, useNext?: boolean): Promise<Transaction>
Argument Details
Throws
ERR_INVALID_PARAMETER if txid does not exist, or can't be found, on chain.
Typically uses getTransaction to obtain a parsed Transaction and returns a specific TransactionOutput.
getTransactionOutput(vout: number, txid: string | Buffer, chain: Chain, useNext?: boolean): Promise<TransactionOutput>
Argument Details
Throws
ERR_INVALID_PARAMETER if txid does not exist, or can't be found, on chain, or if vout is invalid.
Attempts to determine the UTXO status of a transaction output.
Cycles through configured transaction processing services attempting to get a valid response.
getUtxoStatus(output: string | Buffer, chain: Chain, outputFormat?: GetUtxoStatusOutputFormatApi, useNext?: boolean): Promise<GetUtxoStatusResultApi>
Argument Details
outputFormat.output is 32 then 'hashBE`, otherwise 'script'.Attempts to post a new transaction to each configured external transaction processing service.
Asynchronously posts the transaction simultaneously to all the configured services.
postRawTx(rawTx: string | Buffer, chain: Chain, callback?: MapiCallbackApi): Promise<PostRawTxResultApi[]>
Returns
an array of PostRawTxResultApi objects with results of posting to each service
Argument Details
Links: API, Interfaces, Classes, Functions, Types
An API that enables unique callback IDs to be generated for potentially multiple independent callback clients.
export interface MapiCallbackApi {
getId: () => Promise<string>;
url: string;
}
Each call to this method generates a unique callbackID string and creates a record of the circumstances under which it was generated.
getId: () => Promise<string>
The public url to which callbacks will occur.
Callback requests must include a previously getId generated callbackID which must match
an already existing callback record.
url: string
Links: API, Interfaces, Classes, Functions, Types
Properties on result returned from CwiExternalServicesApi function getMerkleProof.
export interface GetMerkleProofResultApi {
name?: string;
proof?: TscMerkleProofApi | TscMerkleProofApi[];
mapi?: {
name?: string;
resp: MapiResponseApi;
};
error?: {
name?: string;
err: CwiError;
};
}
The first exception error that occurred during processing, if any.
error?: {
name?: string;
err: CwiError;
}
The first valid mapi response received from a service, if any. Relevant when no proof was received.
mapi?: {
name?: string;
resp: MapiResponseApi;
}
The name of the service returning the proof, or undefined if no proof
name?: string
Multiple proofs may be returned when a transaction also appears in one or more orphaned blocks
proof?: TscMerkleProofApi | TscMerkleProofApi[]
Links: API, Interfaces, Classes, Functions, Types
Properties on result returned from CwiExternalServicesApi function getRawTx.
export interface GetRawTxResultApi {
txid: string;
name?: string;
rawTx?: Buffer;
mapi?: {
name?: string;
resp: MapiResponseApi;
};
error?: {
name?: string;
err: CwiError;
};
}
The first exception error that occurred during processing, if any.
error?: {
name?: string;
err: CwiError;
}
The first valid mapi response received from a service, if any. Relevant when no proof was received.
mapi?: {
name?: string;
resp: MapiResponseApi;
}
The name of the service returning the rawTx, or undefined if no rawTx
name?: string
Multiple proofs may be returned when a transaction also appears in one or more orphaned blocks
rawTx?: Buffer
Transaction hash or rawTx (and of initial request)
txid: string
Links: API, Interfaces, Classes, Functions, Types
Properties on array items of result returned from CwiExternalServicesApi function postRawTx.
export interface PostRawTxResultApi {
name: string;
callbackID?: string;
status: "success" | "error";
mapi?: MapiResponseApi;
payload?: MapiPostTxPayloadApi;
error?: CwiError;
alreadyKnown?: boolean;
}
if true, the transaction was already known to this service. Usually treat as a success.
Potentially stop posting to additional transaction processors.
alreadyKnown?: boolean
callbackID associated with this request
callbackID?: string
When status is 'error', provides code and description
Specific potential errors: ERR_BAD_REQUEST ERR_EXTSVS_DOUBLE_SPEND ERR_EXTSVS_ALREADY_MINED (description has error details) ERR_EXTSVS_INVALID_TRANSACTION (description has error details) ERR_EXTSVS_TXID_INVALID (service response txid doesn't match rawTx) ERR_EXTSVS_MAPI_SIGNATURE_INVALID ERR_EXTSVS_MAPI_UNSUPPORTED_ENCODING ERR_EXTSVS_MAPI_UNSUPPORTED_MIMETYPE ERR_EXTSVS_MAPI_MISSING (description has service request error details)
error?: CwiError
Raw mapi response including stringified payload
mapi?: MapiResponseApi
The name of the service to which the transaction was submitted for processing
name: string
Parsed and signature verified mapi payload
payload?: MapiPostTxPayloadApi
'success' - The transaction was accepted for processing
status: "success" | "error"
Links: API, Interfaces, Classes, Functions, Types
export interface GetUtxoStatusDetailsApi {
height?: number;
txid?: string;
index?: number;
amount?: number;
}
if isUtxo, the amount of the matching unspent transaction output
typically there will be only one, but future orphans can result in multiple values
amount?: number
if isUtxo, the block height containing the matching unspent transaction output
typically there will be only one, but future orphans can result in multiple values
height?: number
if isUtxo, the output index in the transaction containing of the matching unspent transaction output
typically there will be only one, but future orphans can result in multiple values
index?: number
if isUtxo, the transaction hash (txid) of the transaction containing the matching unspent transaction output
typically there will be only one, but future orphans can result in multiple values
txid?: string
Links: API, Interfaces, Classes, Functions, Types
export interface GetUtxoStatusResultApi {
name: string;
status: "success" | "error";
error?: CwiError;
isUtxo?: boolean;
details: GetUtxoStatusDetailsApi[];
}
Additional details about occurances of this output script as a utxo.
Normally there will be one item in the array but due to the possibility of orphan races there could be more than one block in which it is a valid utxo.
details: GetUtxoStatusDetailsApi[]
When status is 'error', provides code and description
error?: CwiError
true if the output is associated with at least one unspent transaction output
isUtxo?: boolean
The name of the service to which the transaction was submitted for processing
name: string
'success' - the operation was successful, non-error results are valid. 'error' - the operation failed, error may have relevant information.
status: "success" | "error"
Links: API, Interfaces, Classes, Functions, Types
export interface GetScriptHistoryDetailsApi {
txid: string;
height?: number;
fee?: number;
}
the fee paid by the transaction referencing this output script, may be an input or output
typically valid if the transaction has not been mined.
fee?: number
the block height of the transaction referencing this output script, may be an input or output
typically valid if the transaction has been mined.
height?: number
the hash of the transaction referencing this output script, may be an input or output
txid: string
Links: API, Interfaces, Classes, Functions, Types
export interface GetScriptHistoryResultApi {
name: string;
status: "success" | "error";
error?: CwiError;
details: GetScriptHistoryDetailsApi[];
}
Additional details about occurances of this output script.
Sorted by decreasing fee, then decreasing height. i.e. most likely spending transaction first.
details: GetScriptHistoryDetailsApi[]
When status is 'error', provides code and description
error?: CwiError
The name of the service to which the transaction was submitted for processing
name: string
'success' - the operation was successful, non-error results are valid. 'error' - the operation failed, error may have relevant information.
status: "success" | "error"
Links: API, Interfaces, Classes, Functions, Types
export interface BsvExchangeRateApi {
timestamp: Date;
base: "USD";
rate: number;
}
Links: API, Interfaces, Classes, Functions, Types
export interface FiatExchangeRatesApi {
timestamp: Date;
base: "USD";
rates: Record<string, number>;
}
Links: API, Interfaces, Classes, Functions, Types
Links: API, Interfaces, Classes, Functions, Types
Expected txid ${expected} doesn't match proof txid ${actual}
export class ERR_EXTSVS_FAILURE extends CwiError {
constructor(public url: string, public cwiError?: CwiError, description?: string)
}
Links: API, Interfaces, Classes, Functions, Types
Expected txid ${expected} doesn't match proof txid ${actual}
export class ERR_EXTSVS_TXID_INVALID extends CwiError {
constructor(expected?: string, actual?: string)
}
Links: API, Interfaces, Classes, Functions, Types
Header for block hash ${hash} was not found.
export class ERR_EXTSVS_BLOCK_HASH_MISSING extends CwiError {
constructor(hash?: string)
}
Links: API, Interfaces, Classes, Functions, Types
Header for block height ${height} was not found.
export class ERR_EXTSVS_BLOCK_HEIGHT_MISSING extends CwiError {
constructor(height?: number)
}
Links: API, Interfaces, Classes, Functions, Types
Exceeded max envelope depth ${maxDepth}
export class ERR_EXTSVS_ENVELOPE_DEPTH extends CwiError {
constructor(maxDepth: number)
}
Links: API, Interfaces, Classes, Functions, Types
Expected merkleRoot ${expected} doesn't match computed ${actual}
export class ERR_EXTSVS_MERKLEROOT_INVALID extends CwiError {
constructor(expected?: string, actual?: string)
}
Links: API, Interfaces, Classes, Functions, Types
MerkleRoot ${merkleRoot} was not found in active chain.
export class ERR_EXTSVS_MERKLEROOT_MISSING extends CwiError {
constructor(merkleRoot?: string)
}
Links: API, Interfaces, Classes, Functions, Types
Unsupported merkle proof target type ${targetType}.
export class ERR_EXTSVS_MERKLEPROOF_TAGET_TYPE extends CwiError {
constructor(targetType?: string | number)
}
Links: API, Interfaces, Classes, Functions, Types
Unsupported merkle proof node type ${nodeType}.
export class ERR_EXTSVS_MERKLEPROOF_NODE_TYPE extends CwiError {
constructor(nodeType?: string | number)
}
Links: API, Interfaces, Classes, Functions, Types
Merkle proof parsing error.
export class ERR_EXTSVS_MERKLEPROOF_PARSING extends CwiError {
constructor()
}
Links: API, Interfaces, Classes, Functions, Types
Merkle proof unsuported feature ${feature}.
export class ERR_EXTSVS_MERKLEPROOF_UNSUPPORTED extends CwiError {
constructor(feature?: string)
}
Links: API, Interfaces, Classes, Functions, Types
Required Mapi response is missing.
export class ERR_EXTSVS_MAPI_MISSING extends CwiError {
constructor(description?: string)
}
Links: API, Interfaces, Classes, Functions, Types
Mapi response signature is invalid.
export class ERR_EXTSVS_MAPI_SIGNATURE_INVALID extends CwiError {
constructor()
}
Links: API, Interfaces, Classes, Functions, Types
mAPI response unsupported mimetype ${mimeType}
export class ERR_EXTSVS_MAPI_UNSUPPORTED_MIMETYPE extends CwiError {
constructor(mimeType?: string)
}
Links: API, Interfaces, Classes, Functions, Types
mAPI response unsupported encoding ${encoding}
export class ERR_EXTSVS_MAPI_UNSUPPORTED_ENCODING extends CwiError {
constructor(encoding?: string)
}
Links: API, Interfaces, Classes, Functions, Types
mAPI response unsupported returnResult ${result}
export class ERR_EXTSVS_MAPI_UNSUPPORTED_RETURNRESULT extends CwiError {
constructor(result?: string)
}
Links: API, Interfaces, Classes, Functions, Types
Transaction is invalid.
export class ERR_EXTSVS_INVALID_TRANSACTION extends CwiError {
constructor(description?: string)
}
Links: API, Interfaces, Classes, Functions, Types
Txid of broadcast transaction doesn't match returned txid.
export class ERR_EXTSVS_INVALID_TXID extends CwiError {
constructor(description?: string)
}
Links: API, Interfaces, Classes, Functions, Types
Transaction with txid of ${txid} is a double spend.
This class does not include spendingTransactions, see ERR_DOUBLE_SPEND if required.
export class ERR_EXTSVS_DOUBLE_SPEND extends CwiError {
constructor(public txid: string, description?: string)
}
Links: API, Interfaces, Classes, Functions, Types
Transaction was already mined.
export class ERR_EXTSVS_ALREADY_MINED extends CwiError {
constructor(description?: string)
}
Links: API, Interfaces, Classes, Functions, Types
export class ServiceCollection<T> {
services: {
name: string;
service: T;
}[];
_index: number;
constructor()
add(s: {
name: string;
service: T;
}): ServiceCollection<T>
remove(name: string): void
get name()
get service()
get allServices()
get count()
get index()
next(): number
}
Links: API, Interfaces, Classes, Functions, Types
export class CwiExternalServices implements CwiExternalServicesApi {
static createDefaultOptions(): CwiExternalServicesOptions
options: CwiExternalServicesOptions;
getMerkleProofServices: ServiceCollection<GetMerkleProofServiceApi>;
getRawTxServices: ServiceCollection<GetRawTxServiceApi>;
postRawTxServices: ServiceCollection<PostRawTxServiceApi>;
getUtxoStatusServices: ServiceCollection<GetUtxoStatusServiceApi>;
getScriptHistoryServices: ServiceCollection<GetScriptHistoryServiceApi>;
updateFiatExchangeRateServices: ServiceCollection<UpdateFiatExchangeRateServiceApi>;
constructor(options?: CwiExternalServicesOptions)
async getBsvExchangeRate(): Promise<number>
async getFiatExchangeRate(currency: "USD" | "GBP" | "EUR", base?: "USD" | "GBP" | "EUR"): Promise<number>
targetCurrencies = ["USD", "GBP", "EUR"];
async updateFiatExchangeRates(rates?: FiatExchangeRatesApi, updateMsecs?: number): Promise<FiatExchangeRatesApi>
get getProofsCount()
get getRawTxsCount()
get postRawTxsCount()
get getUtxoStatsCount()
async getUtxoStatus(output: string | Buffer, chain: Chain, outputFormat?: GetUtxoStatusOutputFormatApi, useNext?: boolean): Promise<GetUtxoStatusResultApi>
async getScriptHistory(output: string | Buffer, chain: Chain, outputFormat?: GetUtxoStatusOutputFormatApi, useNext?: boolean): Promise<GetScriptHistoryResultApi>
async verifyOutput(output: {
outputScript: Buffer | null;
amount: number | null;
}, chain: Chain): Promise<boolean>
async postRawTx(rawTx: string | Buffer, chain: Chain, callback?: MapiCallbackApi): Promise<PostRawTxResultApi[]>
async getRawTx(txid: string | Buffer, chain: Chain, useNext?: boolean): Promise<GetRawTxResultApi>
async getTransaction(txid: string | Buffer, chain: Chain, useNext?: boolean): Promise<Transaction>
async getTransactionOutput(vout: number, txid: string | Buffer, chain: Chain, useNext?: boolean): Promise<TransactionOutput>
async getMerkleProof(txid: string | Buffer, chain: Chain, useNext?: boolean): Promise<GetMerkleProofResultApi>
}
Links: API, Interfaces, Classes, Functions, Types
Links: API, Interfaces, Classes, Functions, Types
export function createMapiPostTxResponse(txid: string, key: string, resultDescription: string, returnResult = "success"): {
mapi: MapiResponseApi;
payloadData: MapiPostTxPayloadApi;
}
Links: API, Interfaces, Classes, Functions, Types
Verifies the payload signature on a mAPI response object
export function checkMapiResponse(response: MapiResponseApi)
Throws
ERR_EXTSVS_MAPI_SIGNATURE_INVALID if signature fails to validate.
https://github.com/bitcoin-sv-specs/brfc-misc/tree/master/jsonenvelope
Links: API, Interfaces, Classes, Functions, Types
export function signMapiPayload(payload: string, privateKey: string): string
Links: API, Interfaces, Classes, Functions, Types
Parses a mAPI mimetype 'application/json' response payload after verifying the envelope signature.
Throws on verification errors.
export function getMapiJsonResponsePayload<T>(response: MapiResponseApi): T
Returns
parse JSON payload object
Argument Details
Links: API, Interfaces, Classes, Functions, Types
Validates the mapi response signature and parses payload as transaction status.
Throws an error if payload txid doesn't match requested txid.
Throws an error if payload returnResult is not 'success' or 'failure'.
'failure' indicates the txid is unknown to the service.
'success' indicates the txid is known to the service and status was returned.
export function getMapiTxStatusPayload(txid: string | Buffer | undefined, response: MapiResponseApi): MapiTxStatusPayloadApi
Argument Details
Links: API, Interfaces, Classes, Functions, Types
export function getMapiCallbackPayload(txid: string | Buffer | undefined, response: MapiResponseApi): MapiCallbackPayloadApi
Links: API, Interfaces, Classes, Functions, Types
export function verifyMapiResponseForTxid<T extends MapiTxidReturnResultApi>(response: MapiResponseApi, txid?: string | Buffer, checkFailure?: boolean): T
Links: API, Interfaces, Classes, Functions, Types
export function getMapiPostTxPayload(response: MapiResponseApi, txid?: string | Buffer, checkFailure?: boolean): MapiPostTxPayloadApi
Links: API, Interfaces, Classes, Functions, Types
export function checkMapiResponseForTxid(response: MapiResponseApi, txid?: string | Buffer): boolean
Links: API, Interfaces, Classes, Functions, Types
export async function postRawTxToGorillaPool(txid: string | Buffer, rawTx: string | Buffer, chain: Chain, callback?: MapiCallbackApi): Promise<PostRawTxResultApi>
Links: API, Interfaces, Classes, Functions, Types
export function postRawTxToTaal(txid: string | Buffer, rawTx: string | Buffer, chain: Chain, callback?: MapiCallbackApi, apiKey?: string): Promise<PostRawTxResultApi>
Links: API, Interfaces, Classes, Functions, Types
export async function postRawTxToMapiMiner(txid: string | Buffer, rawTx: string | Buffer, miner: PostTransactionMapiMinerApi, callback?: MapiCallbackApi): Promise<PostRawTxResultApi>
Links: API, Interfaces, Classes, Functions, Types
export async function postRawTxToWhatsOnChain(txid: string | Buffer | undefined, rawTx: string | Buffer, chain: Chain, callback?: MapiCallbackApi): Promise<PostRawTxResultApi>
Links: API, Interfaces, Classes, Functions, Types
export async function getRawTxFromWhatsOnChain(txid: string | Buffer, chain: Chain): Promise<GetRawTxResultApi>
Links: API, Interfaces, Classes, Functions, Types
GorillaPool.io MAINNET ONLY
has a mapi transaction status endpoint for mainNet, not for testNet, and does NOT return merkle proofs...
mapiResponse is signed and has txStatus payload. { apiVersion: "", timestamp: "2023-03-23T02:14:39.362Z", txid: "9c31ed1dea4ec1aae0475addc0a74eaed68b718d9983d42b111c387d6696a949", returnResult: "success", resultDescription: "", blockHash: "00000000000000000e155235fd83a8757c44c6299e63104fb12632368f3f0cc9", blockHeight: 700000, confirmations: 84353, minerId: "03ad780153c47df915b3d2e23af727c68facaca4facd5f155bf5018b979b9aeb83", txSecondMempoolExpiry: 0, }
export async function getProofFromGorillaPool(txid: string | Buffer, chain: Chain): Promise<GetMerkleProofResultApi>
Links: API, Interfaces, Classes, Functions, Types
Taal.com has the most functional txStatus and merkleProof endpoint for both mainNet and testNet
Proofs use targetType "header" which is converted to "merkleRoot".
Proofs correctly use duplicate computed node value symbol "*".
An apiKey must be used and must correspond to the target chain: mainNet or testNet.
export async function getProofFromTaal(txid: string | Buffer, apiKey: string): Promise<GetMerkleProofResultApi>
Links: API, Interfaces, Classes, Functions, Types
metastreme.com has a partially conforming merkleProof implementation.
Both mainNet and testNet are supported.
Proofs incorrectly included a copy of the computed value instead of "*" along right side of merkle tree.
targetType of hash
export async function getProofFromMetastreme(txid: string | Buffer, chain: Chain): Promise<GetMerkleProofResultApi>
Links: API, Interfaces, Classes, Functions, Types
WhatOnChain.com has their own "hash/pos/R/L" proof format and a more TSC compliant proof format.
The "/proof" endpoint returns an object for each node with "hash" and "pos" properties. "pos" can have values "R" or "L". Normally "pos" indicates which side of a concatenation the provided "hash" goes with one exception! EXCEPTION: When the provided should be "*" indicating edge-of-the-tree-duplicate-computed-value, they include the expected computed value and the pos value is always "L", even when it should really be "R". This only matters if you are trying to compute index from the "R" and "L" values.
export async function getProofFromWhatsOnChain(txid: string | Buffer, chain: Chain): Promise<GetMerkleProofResultApi>
Links: API, Interfaces, Classes, Functions, Types
WhatOnChain.com has their own "hash/pos/R/L" proof format and a more TSC compliant proof format.
The "/proof/tsc" endpoint is much closer to the TSC specification. It provides "index" directly and each node is just the provided hash value. The "targetType" is unspecified and thus defaults to block header hash, requiring a Chaintracks lookup to get the merkleRoot... Duplicate hash values are provided in full instead of being replaced by "*".
export async function getProofFromWhatsOnChainTsc(txid: string | Buffer, chain: Chain): Promise<GetMerkleProofResultApi>
Links: API, Interfaces, Classes, Functions, Types
export async function getUtxoStatusFromWhatsOnChain(output: string | Buffer, chain: Chain, outputFormat?: GetUtxoStatusOutputFormatApi): Promise<GetUtxoStatusResultApi>
Links: API, Interfaces, Classes, Functions, Types
export async function getScriptHistoryFromWhatsOnChain(output: string | Buffer, chain: Chain, outputFormat?: GetUtxoStatusOutputFormatApi): Promise<GetScriptHistoryResultApi>
Links: API, Interfaces, Classes, Functions, Types
export function validateScriptHash(output: string | Buffer, outputFormat?: GetUtxoStatusOutputFormatApi): string
Links: API, Interfaces, Classes, Functions, Types
export async function updateBsvExchangeRate(rate?: BsvExchangeRateApi, updateMsecs?: number): Promise<BsvExchangeRateApi>
Links: API, Interfaces, Classes, Functions, Types
export async function updateChaintracksFiatExchangeRates(targetCurrencies: string[], options: CwiExternalServicesOptions): Promise<FiatExchangeRatesApi>
Links: API, Interfaces, Classes, Functions, Types
export async function updateExchangeratesapi(targetCurrencies: string[], options: CwiExternalServicesOptions): Promise<FiatExchangeRatesApi>
Links: API, Interfaces, Classes, Functions, Types
export async function getExchangeRatesIo(key: string): Promise<ExchangeRatesIoApi>
Links: API, Interfaces, Classes, Functions, Types
GorillaPool.io has a mapi transaction status endpoint for mainNet, not for testNet, and does NOT return merkle proofs...
mapiResponse is signed and has txStatus payload. { apiVersion: "", timestamp: "2023-03-23T02:14:39.362Z", txid: "9c31ed1dea4ec1aae0475addc0a74eaed68b718d9983d42b111c387d6696a949", returnResult: "success", resultDescription: "", blockHash: "00000000000000000e155235fd83a8757c44c6299e63104fb12632368f3f0cc9", blockHeight: 700000, confirmations: 84353, minerId: "03ad780153c47df915b3d2e23af727c68facaca4facd5f155bf5018b979b9aeb83", txSecondMempoolExpiry: 0, }
export async function getMerkleProofFromGorillaPool(txid: string | Buffer): Promise<TscMerkleProofApi | undefined>
Links: API, Interfaces, Classes, Functions, Types
Taal.com has the most functional txStatus and merkleProof endpoint for both mainNet and testNet
Proofs use targetType "header" which is converted to "merkleRoot".
Proofs correctly use duplicate computed node value symbol "*".
An apiKey must be used and must correspond to the target chain: mainNet or testNet.
export async function getMerkleProofFromTaal(txid: string | Buffer, apiKey: string): Promise<TscMerkleProofApi | undefined>
Links: API, Interfaces, Classes, Functions, Types
metastreme.com has a partially conforming merkleProof implementation.
Both mainNet and testNet are supported.
Proofs incorrectly included a copy of the computed value instead of "*" along right side of merkle tree.
targetType of hash is used which prevents automatic proof checking as the target root value isn't known without a lookup request.
export async function getMerkleProofFromMetastreme(txid: string | Buffer, chain: Chain): Promise<TscMerkleProofApi | undefined>
Links: API, Interfaces, Classes, Functions, Types
WhatOnChain.com has their own "hash/pos/R/L" proof format and a more TSC compliant proof format.
The "/proof" endpoint returns an object for each node with "hash" and "pos" properties. "pos" can have values "R" or "L". Normally "pos" indicates which side of a concatenation the provided "hash" goes with one exception! EXCEPTION: When the provided should be "*" indicating edge-of-the-tree-duplicate-computed-value, they include the expected computed value and the pos value is always "L", even when it should really be "R". This only matters if you are trying to compute index from the "R" and "L" values.
export async function getMerkleProofFromWhatsOnChain(txid: string | Buffer, chain: Chain): Promise<TscMerkleProofApi | undefined>
Links: API, Interfaces, Classes, Functions, Types
WhatOnChain.com has their own "hash/pos/R/L" proof format and a more TSC compliant proof format.
The "/proof/tsc" endpoint is much closer to the TSC specification. It provides "index" directly and each node is just the provided hash value. The "targetType" is unspecified and thus defaults to block header hash, requiring a Chaintracks lookup to get the merkleRoot... Duplicate hash values are provided in full instead of being replaced by "*".
export async function getMerkleProofFromWhatsOnChainTsc(txid: string | Buffer, chain: Chain): Promise<TscMerkleProofApi | undefined>
Links: API, Interfaces, Classes, Functions, Types
Implement merkle proof per https://tsc.bitcoinassociation.net/standards/merkle-proof-standardised-format/
We extend the current standard by implementing targetType 'height' (binary value 3). This extension avoids the need to maintain a merkleroot or block hash index for all headers, reducing the space required by 50%.
Other extensions are not currently supported.
Supports partial and full binary format as well as hex strings.
External Assumptions:
Checking the proof verifies these claims:
Implications:
export async function checkMerkleProof(txid: string | Buffer, proof: TscMerkleProofApi | Buffer, chaintracks: ChaintracksClientApi): Promise<BlockHeader>
Returns
The block header containing the verified merkleRoot
Argument Details
Links: API, Interfaces, Classes, Functions, Types
Attempts to validate whether or not an outpoint has been spent by using the WhatsOnChain API
export async function getSpentStatusForOutpoint(outpoint: string, chain: Chain): Promise<boolean>
Links: API, Interfaces, Classes, Functions, Types
| GetMerkleProofServiceApi |
| GetRawTxServiceApi |
| GetScriptHistoryServiceApi |
| GetUtxoStatusOutputFormatApi |
| GetUtxoStatusServiceApi |
| PostRawTxServiceApi |
| UpdateFiatExchangeRateServiceApi |
Links: API, Interfaces, Classes, Functions, Types
export type GetUtxoStatusOutputFormatApi = "hashLE" | "hashBE" | "script"
Links: API, Interfaces, Classes, Functions, Types
export type GetUtxoStatusServiceApi = (output: string | Buffer, chain: Chain, outputFormat?: GetUtxoStatusOutputFormatApi) => Promise<GetUtxoStatusResultApi>
Links: API, Interfaces, Classes, Functions, Types
export type GetScriptHistoryServiceApi = (output: string | Buffer, chain: Chain, outputFormat?: GetUtxoStatusOutputFormatApi) => Promise<GetScriptHistoryResultApi>
Links: API, Interfaces, Classes, Functions, Types
export type GetMerkleProofServiceApi = (txid: string | Buffer, chain: Chain) => Promise<GetMerkleProofResultApi>
Links: API, Interfaces, Classes, Functions, Types
export type GetRawTxServiceApi = (txid: string | Buffer, chain: Chain) => Promise<GetRawTxResultApi>
Links: API, Interfaces, Classes, Functions, Types
export type UpdateFiatExchangeRateServiceApi = (targetCurrencies: string[], options: CwiExternalServicesOptions) => Promise<FiatExchangeRatesApi>
Links: API, Interfaces, Classes, Functions, Types
export type PostRawTxServiceApi = (txid: string | Buffer, rawTx: string | Buffer, chain: Chain, callback?: MapiCallbackApi) => Promise<PostRawTxResultApi>
Links: API, Interfaces, Classes, Functions, Types
The license for the code in this repository is the Open BSV License.
FAQs
Implementations of external service APIs and standardized APIs for use within CWI
The npm package cwi-external-services receives a total of 370 weekly downloads. As such, cwi-external-services popularity was classified as not popular.
We found that cwi-external-services demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 3 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Tea.xyz, a crypto project aimed at rewarding open source contributions, is once again facing backlash due to an influx of spam packages flooding public package registries.
Security News
As cyber threats become more autonomous, AI-powered defenses are crucial for businesses to stay ahead of attackers who can exploit software vulnerabilities at scale.
Security News
UnitedHealth Group disclosed that the ransomware attack on Change Healthcare compromised protected health information for millions in the U.S., with estimated costs to the company expected to reach $1 billion.