cwi-base v0.4.79

cwi-base

Base classes, types, utilities for implementation support of CWI components, Project Babbage applications and services.

API

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

Interfaces

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 Buffer values with the byte order reversed from the serialized byte order.

export interface BaseBlockHeader {
    version: number;
    previousHash: Buffer;
    merkleRoot: Buffer;
    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: Buffer

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: Buffer

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: BaseBlockHeaderHex

Like BlockHeader but 32 byte fields are hex encoded strings.

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

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: Buffer;
}

See also: BaseBlockHeader

Property hash

The double sha256 hash of the serialized BaseBlockHeader fields.

hash: Buffer

Property height

Height of the header, starting from zero.

height: number

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

Interface: BlockHeaderHex

Like BlockHeader but 32 byte fields are hex encoded strings.

export interface BlockHeaderHex extends BaseBlockHeaderHex {
    height: number;
    hash: string;
}

See also: BaseBlockHeaderHex

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

Interface: CertifierDetails

export interface CertifierDetails {
    name: string;
    icon: string;
    note: string;
    publicKey: string;
    trust: number;
}

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

Interface: ChaintracksApi

Full Chaintracks API including startListening with callbacks

export interface ChaintracksApi extends ChaintracksClientApi {
    startListening(listening?: () => void): Promise<void>;
}

See also: ChaintracksClientApi

Method startListening

Start or resume listening for new headers.

Calls synchronize to catch up on headers that were found while not listening.

Begins listening to any number of configured new header notification services.

Begins sending notifications to subscribed listeners only after processing any previously found headers.

May be called if already listening or synchronizing to listen.

listening callback will be called after listening for new live headers has begun. Alternatively, the listening API function which returns a Promise can be awaited.

startListening(listening?: () => void): Promise<void>

Argument Details

• listening
  • callback indicates when listening for new headers has started.

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

Interface: ChaintracksClientApi

Chaintracks client API excluding events and callbacks

export interface ChaintracksClientApi extends ChainTracker {
    getChain(): Promise<Chain>;
    getInfo(): Promise<ChaintracksInfoApi>;
    getPresentHeight(): Promise<number>;
    getHeaders(height: number, count: number): Promise<Buffer>;
    getHeadersHex(height: number, count: number): Promise<string>;
    findChainTipHeader(): Promise<BlockHeader>;
    findChainTipHeaderHex(): Promise<BlockHeaderHex>;
    findChainTipHash(): Promise<Buffer>;
    findChainTipHashHex(): Promise<string>;
    findChainWorkForBlockHash(hash: Buffer | string): Promise<Buffer | undefined>;
    findChainWorkHexForBlockHash(hash: Buffer | string): Promise<string | undefined>;
    findHeaderForBlockHash(hash: Buffer | string): Promise<BlockHeader | undefined>;
    findHeaderHexForBlockHash(hash: Buffer | string): Promise<BlockHeaderHex | undefined>;
    findHeaderForHeight(height: number): Promise<BlockHeader | undefined>;
    findHeaderHexForHeight(height: number): Promise<BlockHeaderHex | undefined>;
    findHeaderForMerkleRoot(merkleRoot: Buffer | string, height?: number): Promise<BlockHeader | undefined>;
    findHeaderHexForMerkleRoot(root: Buffer | string, height?: number): Promise<BlockHeaderHex | undefined>;
    addHeader(header: BaseBlockHeader | BaseBlockHeaderHex): Promise<void>;
    startListening(): Promise<void>;
    listening(): Promise<void>;
    isListening(): Promise<boolean>;
    isSynchronized(): Promise<boolean>;
    subscribeHeaders(listener: HeaderListener): Promise<string>;
    subscribeReorgs(listener: ReorgListener): Promise<string>;
    unsubscribe(subscriptionId: string): Promise<boolean>;
    isValidRootForHeight(root: string, height: number): Promise<boolean>;
    currentHeight: () => Promise<number>;
}

See also: BaseBlockHeader, BaseBlockHeaderHex, BlockHeader, BlockHeaderHex, Chain, ChaintracksInfoApi, HeaderListener, ReorgListener

Method addHeader

Submit a possibly new header for adding

If the header is invalid or a duplicate it will not be added.

This header will be ignored if the previous header has not already been inserted when this header is considered for insertion.

addHeader(header: BaseBlockHeader | BaseBlockHeaderHex): Promise<void>

See also: BaseBlockHeader, BaseBlockHeaderHex

Returns

immediately

Method findChainTipHash

Returns the block hash of the active chain tip.

findChainTipHash(): Promise<Buffer>

Method findChainTipHashHex

Returns the block hash of the active chain tip.

findChainTipHashHex(): Promise<string>

Method findChainTipHeader

Returns the active chain tip header

findChainTipHeader(): Promise<BlockHeader>

See also: BlockHeader

Method findChainTipHeaderHex

Returns the active chain tip header

findChainTipHeaderHex(): Promise<BlockHeaderHex>

See also: BlockHeaderHex

Method findChainWorkForBlockHash

Only returns a value for headers in live storage. Returns undefined if hash is unknown or in bulk storage.

findChainWorkForBlockHash(hash: Buffer | string): Promise<Buffer | undefined>

Returns

chainwork of block header with given hash

Method findChainWorkHexForBlockHash

Only returns a value for headers in live storage. Returns undefined if hash is unknown or in bulk storage.

findChainWorkHexForBlockHash(hash: Buffer | string): Promise<string | undefined>

Returns

chainwork of block header with given hash

Method findHeaderForBlockHash

Returns block header for a given block hash

findHeaderForBlockHash(hash: Buffer | string): Promise<BlockHeader | undefined>

See also: BlockHeader

Argument Details

• hash
  • block hash

Method findHeaderForHeight

Returns block header for a given block height on active chain.

findHeaderForHeight(height: number): Promise<BlockHeader | undefined>

See also: BlockHeader

Method findHeaderForMerkleRoot

Returns block header for a given possible height and specific merkleRoot The height, available for all mined blocks, allows fast and compact indexing of bulk headers. Confirms that the found header has the request merkleRoot or returns undefined.

findHeaderForMerkleRoot(merkleRoot: Buffer | string, height?: number): Promise<BlockHeader | undefined>

See also: BlockHeader

Argument Details

• height
  • optional, may be required for bulk header lookup.

Method findHeaderHexForBlockHash

Returns block header for a given block hash

findHeaderHexForBlockHash(hash: Buffer | string): Promise<BlockHeaderHex | undefined>

See also: BlockHeaderHex

Argument Details

• hash
  • block hash

Method findHeaderHexForHeight

Returns block header for a given block height on active chain.

findHeaderHexForHeight(height: number): Promise<BlockHeaderHex | undefined>

See also: BlockHeaderHex

Method findHeaderHexForMerkleRoot

Returns block header for a given possible height and specific merkleRoot The height, available for all mined blocks, allows fast and compact indexing of bulk headers. Confirms that the found header has the request merkleRoot or returns undefined.

findHeaderHexForMerkleRoot(root: Buffer | string, height?: number): Promise<BlockHeaderHex | undefined>

See also: BlockHeaderHex

Argument Details

• height
  • optional, may be required for bulk header lookup.

Method getChain

Confirms the chain

getChain(): Promise<Chain>

See also: Chain

Method getHeaders

Adds headers in 80 byte serialized format to a buffer. Only adds active headers. Buffer length divided by 80 is the actual number returned.

getHeaders(height: number, count: number): Promise<Buffer>

Argument Details

• height
  • of first header
• count
  • of headers, maximum

Method getHeadersHex

Adds headers in 80 byte serialized format to a buffer. Only adds active headers. Buffer length divided by 80 is the actual number returned.

getHeadersHex(height: number, count: number): Promise<string>

Argument Details

• height
  • of first header
• count
  • of headers, maximum

Method getInfo

getInfo(): Promise<ChaintracksInfoApi>

See also: ChaintracksInfoApi

Returns

Summary of configuration and state.

Method getPresentHeight

Return the latest chain height from configured bulk ingestors.

getPresentHeight(): Promise<number>

Method isListening

Returns true if actively listening for new headers and client api is enabled.

isListening(): Promise<boolean>

Method isSynchronized

Returns true if synchronize has completed at least once.

isSynchronized(): Promise<boolean>

Method listening

Returns a Promise that will resolve when the previous call to startListening enters the listening-for-new-headers state.

listening(): Promise<void>

Method startListening

Start or resume listening for new headers.

Calls synchronize to catch up on headers that were found while not listening.

Begins listening to any number of configured new header notification services.

Begins sending notifications to subscribed listeners only after processing any previously found headers.

May be called if already listening or synchronizing to listen.

The listening API function which returns a Promise can be awaited.

startListening(): Promise<void>

Method subscribeHeaders

Subscribe to "header" events.

subscribeHeaders(listener: HeaderListener): Promise<string>

See also: HeaderListener

Returns

identifier for this subscription

Throws

ERR_NOT_IMPLEMENTED if callback events are not supported

Method subscribeReorgs

Subscribe to "reorganization" events.

subscribeReorgs(listener: ReorgListener): Promise<string>

See also: ReorgListener

Returns

identifier for this subscription

Throws

ERR_NOT_IMPLEMENTED if callback events are not supported

Method unsubscribe

Cancels all subscriptions with the given subscriptionId which was previously returned by a subscribe method.

unsubscribe(subscriptionId: string): Promise<boolean>

Returns

true if a subscription was canceled

Argument Details

• subscriptionId
  • value previously returned by subscribeToHeaders or subscribeToReorgs

Throws

ERR_NOT_IMPLEMENTED if callback events are not supported

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

Interface: ChaintracksInfoApi

export interface ChaintracksInfoApi {
    chain: Chain;
    heightBulk: number;
    heightLive: number;
    storageEngine: string;
    bulkStorage: string | undefined;
    bulkIndex: string | undefined;
    bulkIngestors: string[];
    liveIngestors: string[];
    packages: ChaintracksPackageInfoApi[];
}

See also: Chain, ChaintracksPackageInfoApi

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

Interface: ChaintracksPackageInfoApi

export interface ChaintracksPackageInfoApi {
    name: string;
    version: string;
}

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

Interface: DojoAliasApi

export interface DojoAliasApi extends DojoEntityTimeStampApi {
    aliasId?: number;
    created_at?: Date | null;
    updated_at?: Date | null;
    alias: string;
    domain: string;
    avatarName?: string;
    avatarPhotoURL?: string;
    reservationCompleted: boolean;
    userId: number;
    destinationBasketId: number;
}

See also: DojoEntityTimeStampApi

Property alias

max length of 30

alias: string

Property avatarName

max length of 30

avatarName?: string

Property avatarPhotoURL

max length of 100

avatarPhotoURL?: string

Property domain

max length of 30

domain: string

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

Interface: DojoAvatarApi

export interface DojoAvatarApi {
    name: string;
    photoURL: string;
}

Property name

The name of the user

name: string

Property photoURL

An HTTPS or UHRP URL to a photo of the user

photoURL: string

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

Interface: DojoCertificateApi

export interface DojoCertificateApi extends DojoEntityTimeStampApi, CreateCertificateResult {
    certificateId?: number;
    created_at?: Date | null;
    updated_at?: Date | null;
    userId: number;
    type: string;
    subject: string;
    validationKey: string;
    serialNumber: string;
    certifier: string;
    revocationOutpoint: string;
    signature: string;
    fields?: Record<string, string>;
    masterKeyring?: Record<string, string>;
    isDeleted?: boolean;
}

See also: DojoEntityTimeStampApi

Property certifier

max length of 255

certifier: string

Property fields

Certificate fields object constructed from fieldName and fieldValue properties of DojoCertificateFieldApi instances associated with this certificate.

fields?: Record<string, string>

Property isDeleted

Optional. Indicates whether the certificate is deleted. isDeleted defaults to false.

isDeleted?: boolean

Property masterKeyring

Certificate masterKeyring object constructed from fieldName and masterKey properties of DojoCertificateFieldApi instances associated with this certificate.

masterKeyring?: Record<string, string>

Property revocationOutpoint

max length of 255

revocationOutpoint: string

Property serialNumber

max length of 255

serialNumber: string

Property signature

max length of 255

signature: string

Property subject

max length of 255

subject: string

Property type

max length of 255

type: string

Property validationKey

max length of 255

validationKey: string

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

Interface: DojoCertificateFieldApi

export interface DojoCertificateFieldApi extends DojoEntityTimeStampApi {
    userId: number;
    certificateId: number;
    created_at?: Date | null;
    updated_at?: Date | null;
    fieldName: string;
    fieldValue: string;
    masterKey: string;
}

See also: DojoEntityTimeStampApi

Property fieldName

max length of 100

fieldName: string

Property fieldValue

max length of 255

fieldValue: string

Property masterKey

base64 encrypted master field revelation key

masterKey: string

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

Interface: DojoClientApi

User specific public Dojo API accessible from all Dojo implementations including DojoExpressClient HTTP client

export interface DojoClientApi extends DojoPublicApi, DojoSyncApi {
    isDojoExpressClient(): boolean;
    authenticate(identityKey?: string, addIfNew?: boolean): Promise<void>;
    getDojoIdentity(): Promise<DojoIdentityApi>;
    sync(logger?: DojoLoggerApi): Promise<void>;
    setSyncDojosByConfig(syncDojoConfigs: SyncDojoConfigBaseApi[], options?: DojoSyncOptionsApi): Promise<void>;
    getSyncDojosByConfig(): Promise<{
        dojos: SyncDojoConfigBaseApi[];
        options?: DojoSyncOptionsApi;
    }>;
    getUser(): DojoClientUserApi;
    getAvatar(): Promise<DojoAvatarApi>;
    setAvatar(avatar: DojoAvatarApi): Promise<void>;
    getCurrentPaymails(): Promise<string[]>;
    saveCertificate(certificate: DojoCertificateApi): Promise<number>;
    findCertificates(certifiers?: string[], types?: Record<string, string[]>): Promise<DojoCertificateApi[]>;
    getTotalOfUnspentOutputs(basket?: string): Promise<number | undefined>;
    updateOutpointStatus(txid: string, vout: number, spendable: boolean): Promise<void>;
    getTotalOfAmounts(direction: "incoming" | "outgoing", options?: DojoGetTotalOfAmountsOptions): Promise<number>;
    getNetOfAmounts(options?: DojoGetTotalOfAmountsOptions): Promise<number>;
    updateTransactionStatus(reference: string, status: DojoTransactionStatusApi): Promise<void>;
    getTransactions(options?: DojoGetTransactionsOptions): Promise<DojoGetTransactionsResultApi>;
    createTransactionSdk(args: sdk.ValidCreateActionArgs, originator?: sdk.OriginatorDomainNameStringUnder250Bytes): Promise<DojoCreateTransactionSdkResult>;
    processActionSdk(params: DojoProcessActionSdkParams, originator?: sdk.OriginatorDomainNameStringUnder250Bytes): Promise<DojoProcessActionSdkResults>;
    abortActionSdk(vargs: sdk.ValidAbortActionArgs, originator?: sdk.OriginatorDomainNameStringUnder250Bytes): Promise<sdk.AbortActionResult>;
    listActionsSdk(vargs: sdk.ValidListActionsArgs, originator?: sdk.OriginatorDomainNameStringUnder250Bytes): Promise<sdk.ListActionsResult>;
    listOutputsSdk(vargs: sdk.ValidListOutputsArgs, originator?: sdk.OriginatorDomainNameStringUnder250Bytes): Promise<sdk.ListOutputsResult>;
    acquireCertificateSdk(vargs: sdk.ValidAcquireDirectCertificateArgs, originator?: sdk.OriginatorDomainNameStringUnder250Bytes): Promise<sdk.AcquireCertificateResult>;
    listCertificatesSdk(vargs: sdk.ValidListCertificatesArgs, originator?: sdk.OriginatorDomainNameStringUnder250Bytes): Promise<DojoListCertificatesResult>;
    proveCertificatesSdk(vargs: sdk.ValidProveCertificateArgs, originator?: sdk.OriginatorDomainNameStringUnder250Bytes): Promise<DojoWalletCertificate>;
    relinquishCertificateSdk(vargs: sdk.ValidRelinquishCertificateArgs, originator?: sdk.OriginatorDomainNameStringUnder250Bytes): Promise<sdk.RelinquishCertificateResult>;
    discoverByIdentityKeySdk(vargs: sdk.ValidDiscoverByIdentityKeyArgs, originator?: sdk.OriginatorDomainNameStringUnder250Bytes): Promise<sdk.DiscoverCertificatesResult>;
    discoverByAttributesSdk(vargs: sdk.ValidDiscoverByAttributesArgs, originator?: sdk.OriginatorDomainNameStringUnder250Bytes): Promise<sdk.DiscoverCertificatesResult>;
    relinquishOutputSdk(vargs: sdk.ValidRelinquishOutputArgs, originator?: sdk.OriginatorDomainNameStringUnder250Bytes): Promise<sdk.RelinquishOutputResult>;
    isValidRootForHeight(root: string, height: number): Promise<boolean>;
    currentHeight: () => Promise<number>;
    internalizeActionSdk(dargs: DojoInternalizeActionArgs, originator?: sdk.OriginatorDomainNameStringUnder250Bytes): Promise<sdk.InternalizeActionResult>;
    getTransactionOutputs(options?: DojoGetTransactionOutputsOptions): Promise<DojoGetTransactionOutputsResultApi>;
    getTransactionLabels(options?: DojoGetTransactionLabelsOptions): Promise<DojoGetTransactionLabelsResultApi>;
    getBeefForTransaction(txid: string, options?: DojoGetBeefOptions): Promise<Beef>;
    getEnvelopeForTransaction(txid: string): Promise<EnvelopeApi | undefined>;
    getEnvelopesOfConflictingTransactions(txid: string): Promise<EnvelopeApi[]>;
    getPendingTransactions(referenceNumber?: string): Promise<DojoPendingTxApi[]>;
    createTransaction(params: DojoCreateTransactionParams): Promise<DojoCreateTransactionResultApi>;
    processTransaction(params: DojoProcessTransactionParams): Promise<DojoProcessTransactionResultApi>;
    submitDirectTransaction(params: DojoSubmitDirectTransactionParams): Promise<DojoSubmitDirectTransactionResultApi>;
    copyState(since?: Date): Promise<DojoUserStateApi>;
    softDeleteCertificate(partial: Partial<DojoCertificateApi>, trx?: TrxToken): Promise<number>;
    softDeleteOutputTag(partial: Partial<DojoOutputTagApi>, trx?: TrxToken): Promise<number>;
    softDeleteTxLabel(partial: Partial<DojoTxLabelApi>, trx?: TrxToken): Promise<number>;
    softDeleteOutputBasket(partial: Partial<DojoOutputBasketApi>, trx?: TrxToken): Promise<number>;
    labelTransaction(txid: string | number | Partial<DojoTransactionApi>, label: string, trx?: TrxToken): Promise<void>;
    unlabelTransaction(txid: string | number | Partial<DojoTransactionApi>, label: string, trx?: TrxToken): Promise<void>;
    tagOutput(partial: Partial<DojoOutputApi>, tag: string, trx?: TrxToken): Promise<void>;
    untagOutput(partial: Partial<DojoOutputApi>, tag: string, trx?: TrxToken): Promise<void>;
    unbasketOutput(partial: Partial<DojoOutputApi>, trx?: TrxToken): Promise<void>;
    getHeight(): Promise<number>;
    getMerkleRootForHeight(height: number): Promise<string | undefined>;
    getHeaderForHeight(height: number): Promise<number[] | undefined>;
    destroy(): Promise<void>;
}

See also: DojoAvatarApi, DojoCertificateApi, DojoClientUserApi, DojoCreateTransactionParams, DojoCreateTransactionResultApi, DojoCreateTransactionSdkResult, DojoGetBeefOptions, DojoGetTotalOfAmountsOptions, DojoGetTransactionLabelsOptions, DojoGetTransactionLabelsResultApi, DojoGetTransactionOutputsOptions, DojoGetTransactionOutputsResultApi, DojoGetTransactionsOptions, DojoGetTransactionsResultApi, DojoIdentityApi, DojoInternalizeActionArgs, DojoListCertificatesResult, DojoLoggerApi, DojoOutputApi, DojoOutputBasketApi, DojoOutputTagApi, DojoPendingTxApi, DojoProcessActionSdkParams, DojoProcessActionSdkResults, DojoProcessTransactionParams, DojoProcessTransactionResultApi, DojoPublicApi, DojoSubmitDirectTransactionParams, DojoSubmitDirectTransactionResultApi, DojoSyncApi, DojoSyncOptionsApi, DojoTransactionApi, DojoTransactionStatusApi, DojoTxLabelApi, DojoUserStateApi, DojoWalletCertificate, SyncDojoConfigBaseApi, TrxToken

Method authenticate

For Dojo scenarios where it is permissible for Dojo to directly act as a specified user, authenticate that user by supplying their identityKey

For Dojo scenarios where authrite is used to authenticate the local user to a potentially remote Dojo server:

• If identityKey has a value then it used and must match the authenticated value.
• If identityKey is undefined, the authenticated value is used.

Sets userId and identityKey

authenticate(identityKey?: string, addIfNew?: boolean): Promise<void>

Argument Details

• identityKey
  • optional, 33 hex encoded bytes, the user to authenticate's identity key
• addIfNew
  • optional, if true, unknown identityKey is added as new user.

Throws

ERR_UNAUTHORIZED if identityKey is required and invalid

Method copyState

Return a complete copy of all records for the authenticated user.

copyState(since?: Date): Promise<DojoUserStateApi>

See also: DojoUserStateApi

Argument Details

• since
  • optional, start of data interval if specified.

Method createTransaction

Constructs a new transaction spending known outputs (inputs) and creating new outputs.

If the inputs to the transaction go beyond what is needed to fund these outputs (plus the transaction fee), additional Dojo-managed UTXOs will be generated to collect the remainder (see the "outputGeneration" parameter for more on this).

createTransaction(params: DojoCreateTransactionParams): Promise<DojoCreateTransactionResultApi>

See also: DojoCreateTransactionParams, DojoCreateTransactionResultApi

Argument Details

• inputs
  • An object whose keys are TXIDs and whose values are payment envelopes for external inputs to use when funding this transaction.

If more funding is needed beyond what is given here to pay for the specified outputs (plus the transaction fee), Dojo will select them from your baskets of unspent outputs (see the "inputSelection" parameter for more on this).

inputsTXID: Must be a payment envelope containing the transaction with output(s) that will be spent and used as input.

inputsTXID.outputsToRedeem: An additional field, an array of outputs from that transaction to be spent.

• params.inputSelection
  • Optional. Algorithmic control over source of additional inputs that may be needed.
• params.outputs
  • Possibly empty, explicit outputs, typically external, to create as part of this transaction.
• params.outputGeneration
  • Optional. Algorithmic control over additional outputs that may be needed.
• params.feeModel
  • Optional. An object representing the fee the transaction will pay.
• params.labels
  • Optional. Each at most 150 characters. Labels can be used to tag transactions into categories
• params.note
  • Optional. A human-readable note detailing this transaction
• params.recipient
  • Optional. The Paymail handle of the recipient of this transaction
• params.options
  • Optional. Processing options.

Method destroy

Releases any persistent resources held by this dojo.

No further access must occur after destroy() has been called.

destroy(): Promise<void>

Method findCertificates

Returns all of the authenticated user's certificates, where the certifier and type values match one of the optionaly

findCertificates(certifiers?: string[], types?: Record<string, string[]>): Promise<DojoCertificateApi[]>

See also: DojoCertificateApi

Argument Details

• certifiers
  • optional array of certifier identifiers, if provided results match at least one value.
• types
  • optional array of certificate types, if provided results match at least one value and only requested fields are returned.

Method getAvatar

Returns the name and photo URL of the user

getAvatar(): Promise<DojoAvatarApi>

See also: DojoAvatarApi

Returns

The avatar of the user

Method getCurrentPaymails

Return array of paymail style identifiers for currently authenticated user in alias@domain format.

Where alias and domain come from the aliases table.

and reservationCompleted is true

getCurrentPaymails(): Promise<string[]>

Method getEnvelopeForTransaction

Returns an Everett Style envelope for the given txid.

A transaction envelope is a tree of inputs where all the leaves are proven transactions. The trivial case is a single leaf: the envelope for a proven transaction is the rawTx and its proof.

Each branching level of the tree corresponds to an unmined transaction without a proof, in which case the envelope is:

• rawTx
• mapiResponses from transaction processors (optional)
• inputs object where keys are this transaction's input txids and values are recursive envelope for those txids.

getEnvelopeForTransaction(txid: string): Promise<EnvelopeApi | undefined>

Argument Details

• txid
  • double hash of raw transaction as hex string

Method getEnvelopesOfConflictingTransactions

Returns array of Everett Style envelopes for transactions that spend one or more of the inputs to transaction with txid, which must exist in Dojo.

This method supports double spend resolution.

getEnvelopesOfConflictingTransactions(txid: string): Promise<EnvelopeApi[]>

Argument Details

• txid
  • double hash of raw transaction as hex string

Method getHeaderForHeight

getHeaderForHeight(height: number): Promise<number[] | undefined>

Returns

serialized block header for the given height or undefined, if height is invalid or unknown.

Method getHeight

Returns the current chain height of the network

getHeight(): Promise<number>

Returns

The current chain height

Method getMerkleRootForHeight

A method to verify the validity of a Merkle root for a given block height.

getMerkleRootForHeight(height: number): Promise<string | undefined>

Returns

merkle root for the given height or undefined, if height doesn't have a known merkle root or is invalid.

Method getNetOfAmounts

Returns the net sum of transaction amounts belonging to authenticated user, incoming plus outgoing, as outgoing amounts are negative and incoming amounts are positive. and optionally matching conditions in options.

getNetOfAmounts(options?: DojoGetTotalOfAmountsOptions): Promise<number>

See also: DojoGetTotalOfAmountsOptions

Method getPendingTransactions

Returns transactions with status of 'unsigned' or 'unprocessed' for authenticated user

Original Dojo returned only these properties: 'transactionId', 'amount', 'created_at', 'referenceNumber', 'senderPaymail', 'truncatedExternalInputs', 'status', 'isOutgoing', 'rawTransaction'

getPendingTransactions(referenceNumber?: string): Promise<DojoPendingTxApi[]>

See also: DojoPendingTxApi

Argument Details

• referenceNumber
  • optional referenceNumber to also match

Method getTotalOfAmounts

Returns the sum of transaction amounts belonging to authenticated user, matching the given direction, and optionally matching conditions in options.

getTotalOfAmounts(direction: "incoming" | "outgoing", options?: DojoGetTotalOfAmountsOptions): Promise<number>

See also: DojoGetTotalOfAmountsOptions

Method getTotalOfUnspentOutputs

Returns the total of spendable output amounts.

Returns undefined if basket is not undefined and doesn't match an existing basket name.

If basket is not undefined, total is restricted to outputs in that basket.

If basket is undefined, total is over all spendable outputs.

getTotalOfUnspentOutputs(basket?: string): Promise<number | undefined>

Returns

total of unspent outputs in named basket

Argument Details

• basket
  • name of existing outputs basket or undefined

Method getTransactionLabels

Returns transaction labels matching options and total matching count available.

getTransactionLabels(options?: DojoGetTransactionLabelsOptions): Promise<DojoGetTransactionLabelsResultApi>

See also: DojoGetTransactionLabelsOptions, DojoGetTransactionLabelsResultApi

Argument Details

• options
  • limit defaults to 25, offset defaults to 0, order defaults to 'descending'

Method getTransactionOutputs

Returns transaction outputs matching options and total matching count available.

getTransactionOutputs(options?: DojoGetTransactionOutputsOptions): Promise<DojoGetTransactionOutputsResultApi>

See also: DojoGetTransactionOutputsOptions, DojoGetTransactionOutputsResultApi

Argument Details

• options
  • limit defaults to 25, offset defaults to 0, includeEnvelpe defaults to true

Method getTransactions

Returns transactions matching options and total matching count available.

getTransactions(options?: DojoGetTransactionsOptions): Promise<DojoGetTransactionsResultApi>

See also: DojoGetTransactionsOptions, DojoGetTransactionsResultApi

Argument Details

• options
  • limit defaults to 25, offset defaults to 0, addLabels defaults to true, order defaults to 'descending'

Method getUser

Returns authenticated user. Throws an error if isAuthenticated is false.

getUser(): DojoClientUserApi

See also: DojoClientUserApi

Method isDojoExpressClient

Returns true iff and instance of DojoExpressClient (or derived from it)

isDojoExpressClient(): boolean

Method labelTransaction

Labels a transaction

Validates user is authenticated, txid matches an exsiting user transaction, and label value.

Creates new label if necessary.

Adds label to transaction if not already labeled. Note: previously if transaction was already labeled, an error was thrown.

labelTransaction(txid: string | number | Partial<DojoTransactionApi>, label: string, trx?: TrxToken): Promise<void>

See also: DojoTransactionApi, TrxToken

Argument Details

• txid
  • unique transaction identifier, either transactionId, txid, or a partial pattern.
• label
  • the label to be added, will be created if it doesn't already exist

Method processTransaction

After creating a transaction with createTransaction and signing it, submit the serialized raw transaction to transaction processors for processing.

The reference number uniquely identifies the transaction in the database.

Differences from v1: 1. mapi_responses records are created when callbackIDs are generated, they exist before callbackID is given to external transaction processing service.

processTransaction(params: DojoProcessTransactionParams): Promise<DojoProcessTransactionResultApi>

See also: DojoProcessTransactionParams, DojoProcessTransactionResultApi

Returns

DojoProcessTransactionResultApi with txid and status of 'completed' or 'unknown'

Argument Details

• rawTx
  • The signed transaction serialized as a hex string or Buffer, not yet stored in database.
• reference
  • The reference number that you received from createTransaction uniquely identifying the database record.
• outputMap
  • An object whose keys are change output derivation suffixes and whose values are the corresponding output (vout) numbers within the transaction.

Throws

ERR_DOJO_INVALID_REFERENCE if reference is unknown

ERR_DOJO_TRANSACTION_REJECTED if processors reject the transaction

ERR_EXTSVS_DOUBLE_SPEND if transaction double spends an input

Method saveCertificate

Save a new certificate with optional fields.

certificate must belong to aunthenticated user.

certificate.subject must match authenticated user's idenitityKey or throws ERR_DOJO_CERT_SUBJECT

certificate.signature must be valid or throws ERR_DOJO_CERT_INVALID

If { type, subject, validationKey, serialNumber, userId } already exist, throw ERR_DOJO_CERT_DUPE

saveCertificate(certificate: DojoCertificateApi): Promise<number>

See also: DojoCertificateApi

Returns

the certificateId of the new certificate.

Method setAvatar

Update the avatar for the authenticated user.

setAvatar(avatar: DojoAvatarApi): Promise<void>

See also: DojoAvatarApi

Method softDeleteCertificate

Soft deletes a certificate.

softDeleteCertificate(partial: Partial<DojoCertificateApi>, trx?: TrxToken): Promise<number>

See also: DojoCertificateApi, TrxToken

Argument Details

• partial
  • The partial certificate data identifying the certificate to soft delete.

Method softDeleteOutputBasket

Soft deletes an output basket.

softDeleteOutputBasket(partial: Partial<DojoOutputBasketApi>, trx?: TrxToken): Promise<number>

See also: DojoOutputBasketApi, TrxToken

Argument Details

• partial
  • The partial output basket data identifying the basket to soft delete.

Method softDeleteOutputTag

Soft deletes an output tag.

softDeleteOutputTag(partial: Partial<DojoOutputTagApi>, trx?: TrxToken): Promise<number>

See also: DojoOutputTagApi, TrxToken

Argument Details

• partial
  • The partial output tag data identifying the tag to soft delete.

Method softDeleteTxLabel

Soft deletes a transaction label.

softDeleteTxLabel(partial: Partial<DojoTxLabelApi>, trx?: TrxToken): Promise<number>

See also: DojoTxLabelApi, TrxToken

Argument Details

• partial
  • The partial transaction label data identifying the label to soft delete.

Method submitDirectTransaction

This endpoint allows a recipient to submit a transactions that was directly given to them by a sender.

Saves the inputs and key derivation information, allowing the UTXOs to be redeemed in the future.

Sets the transaction to completed and marks the outputs as spendable.

submitDirectTransaction(params: DojoSubmitDirectTransactionParams): Promise<DojoSubmitDirectTransactionResultApi>

See also: DojoSubmitDirectTransactionParams, DojoSubmitDirectTransactionResultApi

Method sync

Sync's this dojo's state for the authenticated user with all of the configured syncDojos

This method must be called when either a local or remote state change occurs, or may have occurred.

User state changes are propagated across all configured syncDojos.

sync(logger?: DojoLoggerApi): Promise<void>

See also: DojoLoggerApi

Argument Details

• logger
  • optional sync progress update logger

Method tagOutput

Tags an output

Validates user is authenticated, partial identifies a single output, and tag value.

Creates new tag if necessary.

Adds tag to output if not already tagged.

tagOutput(partial: Partial<DojoOutputApi>, tag: string, trx?: TrxToken): Promise<void>

See also: DojoOutputApi, TrxToken

Argument Details

• partial
  • unique output identifier as a partial pattern.
• tag
  • the tag to add, will be created if it doesn't already exist

Method unbasketOutput

Removes the uniquely identified output's basket assignment.

The output will no longer belong to any basket.

This is typically only useful for outputs that are no longer usefull.

unbasketOutput(partial: Partial<DojoOutputApi>, trx?: TrxToken): Promise<void>

See also: DojoOutputApi, TrxToken

Argument Details

• partial
  • unique output identifier as a partial pattern.

Method unlabelTransaction

Removes a label from a transaction

Validates user is authenticated, txid matches an exsiting user transaction, and label already exits.

Does nothing if transaction is not labeled.

unlabelTransaction(txid: string | number | Partial<DojoTransactionApi>, label: string, trx?: TrxToken): Promise<void>

See also: DojoTransactionApi, TrxToken

Argument Details

• txid
  • unique transaction identifier, either transactionId, txid, or a partial pattern.
• label
  • the label to be removed from the transaction

Method untagOutput

Removes a tag from an output

Validates user is authenticated, partial identifies a single output, and tag already exits.

Does nothing if output is not tagged.

untagOutput(partial: Partial<DojoOutputApi>, tag: string, trx?: TrxToken): Promise<void>

See also: DojoOutputApi, TrxToken

Argument Details

• partial
  • unique output identifier as a partial pattern.
• tag
  • the tag to be removed from the output

Method updateOutpointStatus

Update spendable of an output that must exist, belonging to the authenticated user, in transaction with txid, at index vout.

updateOutpointStatus(txid: string, vout: number, spendable: boolean): Promise<void>

Method updateTransactionStatus

Update transaction status and associated ouputs (both inputs and outputs) spendable and spentBy properties.

Updated transaction userId must match authenticated user and referenceNumber must match reference.

updateTransactionStatus(reference: string, status: DojoTransactionStatusApi): Promise<void>

See also: DojoTransactionStatusApi

Argument Details

• status
  • New transaction status.

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

Interface: DojoClientUserApi

export interface DojoClientUserApi extends DojoEntityTimeStampApi {
    userId?: number;
    created_at?: Date | null;
    updated_at?: Date | null;
    identityKey: string;
}

See also: DojoEntityTimeStampApi

Property identityKey

max length of 130 hex encoded

identityKey: string

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

Interface: DojoCommissionApi

export interface DojoCommissionApi extends DojoEntityTimeStampApi {
    commissionId?: number;
    created_at?: Date | null;
    updated_at?: Date | null;
    transactionId: number;
    userId: number;
    isRedeemed: boolean;
    keyOffset: string;
    outputScript: Buffer | null;
    satoshis: number;
}

See also: DojoEntityTimeStampApi

Property keyOffset

max length of 130

keyOffset: string

Property satoshis

15 integer digits

satoshis: number

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

Interface: DojoCreateTransactionParams

export interface DojoCreateTransactionParams {
    outputs: DojoCreateTxOutputApi[];
    inputs?: Record<string, DojoTxInputsApi>;
    beef?: Beef | number[];
    inputSelection?: DojoTxInputSelectionApi;
    outputGeneration?: DojoOutputGenerationApi;
    lockTime?: number;
    version?: number;
    feeModel?: DojoFeeModelApi;
    labels?: string[];
    note?: string;
    recipient?: string;
    options?: CreateActionOptions;
    log?: string;
}

See also: DojoCreateTxOutputApi, DojoFeeModelApi, DojoOutputGenerationApi, DojoTxInputSelectionApi, DojoTxInputsApi

Property beef

Optional. Alternate source of validity proof data for inputs. If number[] it must be serialized Beef.

beef?: Beef | number[]

Property feeModel

Optional. An object representing the fee the transaction will pay.

feeModel?: DojoFeeModelApi

See also: DojoFeeModelApi

Property inputSelection

Optional. Algorithmic control over source of additional inputs that may be needed.

inputSelection?: DojoTxInputSelectionApi

See also: DojoTxInputSelectionApi

Property inputs

Optional. Specific inputs to draw on when creating outputs.

inputs?: Record<string, DojoTxInputsApi>

See also: DojoTxInputsApi

Property labels

Optional. Each at most 150 characters. Labels can be used to tag transactions into categories

labels?: string[]

Property lockTime

Optional. Default is zero. When the transaction can be processed into a block:

= 500,000,000 values are interpreted as minimum required unix time stamps in seconds < 500,000,000 values are interpreted as minimum required block height

lockTime?: number

Property log

Optional transaction processing history

log?: string

Property note

Optional. A human-readable note detailing this transaction (Optional)

note?: string

Property options

Processing options.

options?: CreateActionOptions

Property outputGeneration

Optional. Algorithmic control over additional outputs that may be needed.

outputGeneration?: DojoOutputGenerationApi

See also: DojoOutputGenerationApi

Property outputs

Possibly empty, explicit outputs, typically external, to create as part of this transaction.

outputs: DojoCreateTxOutputApi[]

See also: DojoCreateTxOutputApi

Property recipient

Optional. The Paymail handle of the recipient of this transaction (Optional)

recipient?: string

Property version

If not undefined, must match value in associated rawTransaction.

version?: number

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

Interface: DojoCreateTransactionResultApi

export interface DojoCreateTransactionResultApi {
    inputs: Record<string, DojoCreateTxResultInputsApi>;
    inputBeef?: number[];
    outputs: DojoCreateTxResultOutputApi[];
    noSendChangeOutputVouts?: number[];
    derivationPrefix: string;
    version: number;
    lockTime: number;
    referenceNumber: string;
    note?: string;
    options: CreateActionOptions;
    log?: string;
    paymailHandle?: string;
}

See also: DojoCreateTxResultInputsApi, DojoCreateTxResultOutputApi

Property inputBeef

This will be a partially valid serialized BEEF value.

Includes proof data for the inputs to the transaction being created. Some txids may be txidOnly, in which case they must be known to Dojo, their rawTx are not included.

It is recommended to the @babbage/sdk-ts package's Beef class to deserialize and complete the creation of a valid beef.

inputBeef?: number[]

Property paymailHandle

DEPRECATED

paymailHandle?: string

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

Interface: DojoCreateTransactionSdkInput

export interface DojoCreateTransactionSdkInput {
    vin: number;
    sourceTxid: string;
    sourceVout: number;
    sourceSatoshis: number;
    sourceLockingScript: string;
    unlockingScriptLength: number;
    providedBy: DojoProvidedByApi;
    type: string;
    spendingDescription?: string;
    derivationPrefix?: string;
    derivationSuffix?: string;
    senderIdentityKey?: string;
}

See also: DojoProvidedByApi

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

Interface: DojoCreateTransactionSdkOutput

export interface DojoCreateTransactionSdkOutput extends sdk.ValidCreateActionOutput {
    vout: number;
    providedBy: DojoProvidedByApi;
    purpose?: string;
    derivationSuffix?: string;
}

See also: DojoProvidedByApi

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

Interface: DojoCreateTransactionSdkResult

export interface DojoCreateTransactionSdkResult {
    inputBeef?: number[];
    inputs: DojoCreateTransactionSdkInput[];
    outputs: DojoCreateTransactionSdkOutput[];
    noSendChangeOutputVouts?: number[];
    derivationPrefix: string;
    version: number;
    lockTime: number;
    referenceNumber: string;
}

See also: DojoCreateTransactionSdkInput, DojoCreateTransactionSdkOutput

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

Interface: DojoCreateTxOutputApi

A specific output to be created as part of a new transactions. These outputs can contain custom scripts as specified by recipients.

export interface DojoCreateTxOutputApi {
    script: string;
    satoshis: number;
    description?: string;
    basket?: string;
    customInstructions?: string;
    tags?: string[];
}

Property basket

Destination output basket name for the new UTXO

basket?: string

Property customInstructions

Custom spending instructions (metadata, string, optional)

customInstructions?: string

Property description

Human-readable output line-item description

description?: string

Property satoshis

The amount of the output in satoshis

satoshis: number

Property script

The output script that will be included, hex encoded

script: string

Property tags

Optional array of output tags to assign to this output.

tags?: string[]

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

Interface: DojoCreateTxResultInputsApi

export interface DojoCreateTxResultInputsApi extends DojoTxInputsApi, OptionalEnvelopeEvidenceApi {
    providedBy: DojoProvidedByApi;
    instructions: Record<number, DojoCreateTxResultInstructionsApi>;
    outputsToRedeem: DojoOutputToRedeemApi[];
    txid: string;
}

See also: DojoCreateTxResultInstructionsApi, DojoOutputToRedeemApi, DojoProvidedByApi, DojoTxInputsApi

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

Interface: DojoCreateTxResultInstructionsApi

export interface DojoCreateTxResultInstructionsApi {
    type: string;
    paymailHandle?: string;
    derivationPrefix?: string;
    derivationSuffix?: string;
    senderIdentityKey?: string;
}

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

Interface: DojoCreateTxResultOutputApi

export interface DojoCreateTxResultOutputApi extends DojoCreateTxOutputApi {
    vout: number;
    providedBy: DojoProvidedByApi;
    purpose?: string;
    destinationBasket?: string;
    derivationSuffix?: string;
    keyOffset?: string;
}

See also: DojoCreateTxOutputApi, DojoProvidedByApi

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

Interface: DojoCreatingTxInputsApi

export interface DojoCreatingTxInputsApi {
    outputsToRedeem: DojoOutputToRedeemApi[];
    beefTx: BeefTx;
}

See also: DojoOutputToRedeemApi

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

Interface: DojoEntityTimeStampApi

export interface DojoEntityTimeStampApi {
    created_at?: Date | null;
    updated_at?: Date | null;
}

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

Interface: DojoFeeModelApi

An object representing the fee the transaction will pay.

export interface DojoFeeModelApi {
    model: "sat/kb";
    value?: number;
}

Property model

The fee model to use, default "sat/kb"

model: "sat/kb"

Property value

When "fee.model" is "sat/kb", this is an integer representing the number of satoshis per kb of block space the transaction will pay in fees.

If undefined, the default value is used which may vary with market conditions.

value?: number

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

Interface: DojoGetBeefOptions

export interface DojoGetBeefOptions {
    trustSelf?: "known";
    knownTxids?: string[];
    mergeToBeef?: Beef | number[];
    ignoreStorage?: boolean;
    ignoreServices?: boolean;
    ignoreNewProven?: boolean;
    minProofLevel?: number;
}

Property ignoreNewProven

optional. Default is false. If true, raw transactions with proofs missing from dojo.storage and obtained from dojo.getServices are not inserted to dojo.storage.

ignoreNewProven?: boolean

Property ignoreServices

optional. Default is false. dojo.getServices is used for raw transaction and merkle proof lookup

ignoreServices?: boolean

Property ignoreStorage

optional. Default is false. dojo.storage is used for raw transaction and merkle proof lookup

ignoreStorage?: boolean

Property knownTxids

list of txids to be included as txidOnly if referenced. Validity is known to caller.

knownTxids?: string[]

Property mergeToBeef

optional. If defined, raw transactions and merkle paths required by txid are merged to this instance and returned. Otherwise a new Beef is constructed and re