cwi-base v0.4.32

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

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

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

Interface: Result

export interface Result {
    subject: string;
    certifier: string;
}

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

Interface: Settings

export interface Settings {
    trustThreshold: number;
}

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

Interface: TrustEvaluatorParams

export interface TrustEvaluatorParams {
    settings: Settings;
    certifiers: CertifierDetails[];
    results: Result[];
}

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

Interface: IdentityGroupMember

export interface IdentityGroupMember {
    certifier: CertifierDetails;
    subject: string;
}

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

Interface: IdentityGroup

export interface IdentityGroup {
    totalTrust: number;
    members: IdentityGroupMember[];
}

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

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

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: Buffer;
    isChainTip: boolean;
    isActive: boolean;
    headerId: number;
    previousHeaderId: number | null;
}

Property chainWork

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

chainWork: Buffer

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

Interface: LiveBlockHeaderHex

Like LiveBlockHeader but 32 byte fields are hex encoded strings.

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

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

Interface: ChaintracksPackageInfoApi

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

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[];
}

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

Interface: ChaintracksClientApi

Chaintracks client API excluding events and callbacks

export interface ChaintracksClientApi {
    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>;
}

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>

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>

Method findChainTipHeaderHex

Returns the active chain tip header

findChainTipHeaderHex(): Promise<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>

Argument Details

• hash
  • block hash

Method findHeaderForHeight

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

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

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>

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>

Argument Details

• hash
  • block hash

Method findHeaderHexForHeight

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

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

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>

Argument Details

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

Method getChain

Confirms the chain

getChain(): Promise<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>

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>

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>

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

Full Chaintracks API including startListening with callbacks

export interface ChaintracksApi extends ChaintracksClientApi {
    startListening(listening?: () => void): 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.

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

Public Dojo Api No Authrite authentication required. Not specific to any userId

export interface DojoPublicApi {
    getChain(): Promise<Chain>;
    stats(): Promise<DojoStatsApi>;
}

Method getChain

Return the chain served by this Dojo

Also serves to verifies that all dependent services are on same chain.

getChain(): Promise<Chain>

Method stats

stats(): Promise<DojoStatsApi>

Returns

general storage statistics

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

Interface: SyncDojoConfigBaseApi

Each syncDojo config has the following properties:

'dojoType' one of 'Cloud URL' | 'Sqlite File' | 'MySql Connection' 'dojoIdentityKey' the identity key of the syncDojo. 'dojoName' the name of the syncDojo.

export interface SyncDojoConfigBaseApi {
    dojoType: SyncDojoConfigType;
    dojoIdentityKey: string;
    dojoName?: string;
}

Property dojoIdentityKey

the identity key of the syncDojo.

dojoIdentityKey: string

Property dojoName

the name of the syncDojo.

dojoName?: string

Property dojoType

one of 'Cloud URL' | 'Sqlite File' | 'MySql Connection' | ''

dojoType: SyncDojoConfigType

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

Interface: SyncDojoConfigCloudUrl

The derived SyncDojoConfigCloudUrl interface adds:

'url' the service URL of the cloud dojo with which to sync

'clientPrivateKey' should be the authenticated user's private key matching their identityKey to enable automatic use of Authrite.

'useIdentityKey' may be set to true instead of using 'clientPrivateKey' if the cloud dojo does not use Authrite for access control.

The cloud dojo must exists and must already be configured with matching dojoIdentityKey.

If neither 'clientPrivateKey' or 'useIdentityKey' has a value, will attempt to use the Babbage signing strategy for Authrite.

export interface SyncDojoConfigCloudUrl extends SyncDojoConfigBaseApi {
    url: string;
    clientPrivateKey?: string;
    useIdentityKey?: boolean;
}

Property clientPrivateKey

should be the authenticated user's private key matching their identityKey to enable automatic use of Authrite.

clientPrivateKey?: string

Property url

the service URL of the cloud dojo with which to sync

url: string

Property useIdentityKey

may be set to true instead of using 'clientPrivateKey' if the cloud dojo does not use Authrite for access control.

useIdentityKey?: boolean

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

Interface: SyncDojoConfigMySqlConnection

export interface SyncDojoConfigMySqlConnection extends SyncDojoConfigBaseApi {
    connection: string;
}

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

Interface: SyncDojoConfigSqliteFile

export interface SyncDojoConfigSqliteFile extends SyncDojoConfigBaseApi {
    filename: string;
}

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

Interface: DojoIdentityApi

export interface DojoIdentityApi {
    dojoIdentityKey: string;
    dojoName?: string;
}

Property dojoIdentityKey

The identity key (public key) assigned to this dojo

dojoIdentityKey: string

Property dojoName

The human readable name assigned to this dojo.

dojoName?: string

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

Interface: DojoSyncErrorApi

export interface DojoSyncErrorApi {
    code: string;
    description: string;
    stack?: string;
}

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

Interface: DojoSyncMapApi

export interface DojoSyncMapApi {
    aliasIds: Record<number, number>;
    certificateIds: Record<number, number>;
    commissionIds: Record<number, number>;
    responseIds: Record<number, number>;
    basketIds: Record<number, number>;
    outputIds: Record<number, number>;
    provenTxReqIds: Record<number, number>;
    provenTxIds: Record<number, number>;
    txIds: Record<number, number>;
    txLabelIds: Record<number, number>;
    outputTagIds: Record<number, number>;
}

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

Interface: DojoSyncIdentifyParams

Receipt of DojoSyncIdentityParams via the syncIdentify function starts a dojo to dojo sync.

It may also force a restart of the sync protocol.

The purpose of the Identify phase is to identify both dojo's to each other, the identity of the authenticated user, and the last known sync_state.

export interface DojoSyncIdentifyParams {
    protocolVersion: DojoSyncProtocolVersion;
    userIdentityKey: string;
    dojoIdentityKey: string;
    dojoName?: string;
    refNum: string;
}

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

Interface: DojoSyncIdentifyResultApi

export interface DojoSyncIdentifyResultApi {
    refNum: string;
    identityKey: string;
    name?: string;
    status: DojoSyncStatus;
    when?: Date;
    error?: DojoSyncErrorApi;
}

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

Interface: DojoSyncUpdateParams

export interface DojoSyncUpdateParams {
    protocolVersion: DojoSyncProtocolVersion;
    refNum: string;
    since?: Date;
}

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

Interface: DojoSyncUpdateResultApi

export interface DojoSyncUpdateResultApi {
    refNum: string;
    status: DojoSyncStatus;
    since?: Date;
    state?: DojoUserStateApi;
    error?: DojoSyncErrorApi;
}

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

Interface: DojoSyncMergeParams

export interface DojoSyncMergeParams {
    protocolVersion: DojoSyncProtocolVersion;
    refNum: string;
    when?: Date;
    state?: DojoUserStateApi;
    total?: number;
    iSyncMap?: DojoSyncMapApi;
    error?: DojoSyncErrorApi;
}

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

Interface: DojoSyncMergeResultApi

export interface DojoSyncMergeResultApi {
    refNum: string;
    status: DojoSyncStatus;
    iSyncMap?: DojoSyncMapApi;
    error?: DojoSyncErrorApi;
}

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

Interface: DojoSyncApi

Dojo Sync Protocol

The Dojo Sync Protocol keeps multiple UTXO management services (Dojos) synchronized as updates occur between them.

The protocol relies on the properties of the blockchain to handle specific conflicts.

It is intended to support use cases where there is a primary dojo which periodically synchronizes to backup "syncDojos".

There is no formal conrol within the protocol for determining the primary dojo or transitioning between roles.

Synchronization is initiated from the primary Dojo.

Step 1. Run through the configured syncDojos calling syncIdentify which shares the local dojo and syncDojo's identities. Any syncDojo that responds is added to activeSyncDojos.

Step 2. Run through the activeSyncDojos calling syncUpdate.

export interface DojoSyncApi {
    syncIdentify(params: DojoSyncIdentifyParams): Promise<DojoSyncIdentifyResultApi>;
    syncUpdate(params: DojoSyncUpdateParams): Promise<DojoSyncUpdateResultApi>;
    syncMerge(params: DojoSyncMergeParams): Promise<DojoSyncMergeResultApi>;
    authenticate(identityKey?: string, addIfNew?: boolean): Promise<void>;
    getSyncDojoConfig(): Promise<SyncDojoConfigBaseApi>;
}

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 getSyncDojoConfig

Returns the configuration of this dojo as a syncDojo

getSyncDojoConfig(): Promise<SyncDojoConfigBaseApi>

Method syncIdentify

Called to initiate the sync protocol.

This is the initial protocol step to exchange dojo identityKeys and configure the records in the sync_state and sync_history tables to support the sync protocol.

syncIdentify(params: DojoSyncIdentifyParams): Promise<DojoSyncIdentifyResultApi>

Returns

Equivalent parameters for this syncDojo.

Argument Details

• params
  • Parameters identifying the primary initiating dojo, user, sarting status and protocol version.

Method syncMerge

Informs a syncDojo of the result of merging state received from them.

This is the only valid way that the syncDojo's when field in sync_state is updated which is critical to guaranteeing that un-merged changes are presented until successfully merged.

syncMerge(params: DojoSyncMergeParams): Promise<DojoSyncMergeResultApi>

Method syncUpdate

Receive a state update for the authenticated user from a remote dojo and respond with merge result and any pre-merge local state update for the data interval from since to when

syncUpdate(params: DojoSyncUpdateParams): Promise<DojoSyncUpdateResultApi>

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

Interface: DojoSyncOptionsApi

export interface DojoSyncOptionsApi {
    disableSync?: boolean;
}

Property disableSync

If true, sync is disabled.

disableSync?: boolean

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

Interface: TrxToken

Place holder for the transaction control object used by actual storage provider implementation.

export interface TrxToken {
}

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>;
    getTransactionOutputs(options?: DojoGetTransactionOutputsOptions): Promise<DojoGetTransactionOutputsResultApi>;
    getTransactionLabels(options?: DojoGetTransactionLabelsOptions): Promise<DojoGetTransactionLabelsResultApi>;
    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>;
    destroy(): Promise<void>;
}

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>

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>

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 (Optional)
• params.recipient
  • Optional. The Paymail handle of the recipient of this transaction (Optional)

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[]>

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>

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

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[]>

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>

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>

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>

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>

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

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>

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>

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>

Returns

the certificateId of the new certificate.

Method setAvatar

Update the avatar for the authenticated user.

setAvatar(avatar: DojoAvatarApi): Promise<void>

Method softDeleteCertificate

Soft deletes a certificate.

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

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>

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>

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>

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>

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>

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>

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>

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>

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>

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>

Argument Details

• status
  • New transaction status.

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

Interface: DojoGetTransactionsBaseOptions

export interface DojoGetTransactionsBaseOptions {
    limit?: number;
    offset?: number;
    order?: DojoRecordOrder;
}

Property limit

Optional. How many transactions to return.

limit?: number

Property offset

Optional. How many transactions to skip.

offset?: number

Property order

Optional. Set sort order of results.

order?: DojoRecordOrder

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

Interface: DojoGetTransactionsOptions

export interface DojoGetTransactionsOptions extends DojoGetTransactionsBaseOptions {
    columns?: string[];
    referenceNumber?: string;
    status?: DojoTransactionStatusApi | DojoTransactionStatusApi[];
    label?: string;
    startTime?: Date | string | number;
    endTime?: Date | string | number;
    involving?: string;
    addLabels?: boolean;
    addInputsAndOutputs?: boolean;
    includeBasket?: boolean;
    includeTags?: boolean;
    noRawTx?: boolean;
}

Property addInputsAndOutputs

Optional. If true, include the list of transaction inputs and outputs when retrieving transactions. Enabling this option adds the 'inputs' and 'outputs' properties to each transaction, providing detailed information about the transaction's inputs and outputs.

addInputsAndOutputs?: boolean

Property addLabels

Optional. If true, array of mapped labels is added to each transaction.

addLabels?: boolean

Property columns

Columns to return for each transaction. If undefined or empty, all columns are returned.

columns?: string[]

Property endTime

Optional. Match transactions created on or before this time. Date, ISO string, or seconds since the epoch.

endTime?: Date | string | number

Property includeBasket

If true and addInputsAndOutputs is true, the DojoOutputXApi basket property will be included in inputs and outputs.

includeBasket?: boolean

Property includeTags

If true and addInputsAndOutputs is true, the DojoOutputXApi tags property will be included in inputs and outputs.

includeTags?: boolean

Property involving

Optional. Match transactions with either senderPaymail or recipientPaymail matching this value.

involving?: string

Property label

Optional. Match transactions with this label.

label?: string

Property noRawTx

If true, excludes rawTx and outputScript properties from results.

noRawTx?: boolean

Property referenceNumber

Optional. Match transactions with this referenceNumber.

referenceNumber?: string

Property startTime

Optional. Match transactions created on or after this time. Date, ISO string, or seconds since the epoch.

startTime?: Date | string | number

Property status

Optional. Match transactions with this status.

Defaults to 'unproven', 'completed'

status?: DojoTransactionStatusApi | DojoTransactionStatusApi[]

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

Interface: DojoGetTransactionOutputsOptions

export interface DojoGetTransactionOutputsOptions extends DojoGetTransactionsBaseOptions {
    basket?: string;
    tracked?: boolean;
    spendable?: boolean;
    tags?: string[];
    type?: string;
    includeEnvelope?: boolean;
    includeCustomInstructions?: boolean;
    includeBasket?: boolean;
    includeTags?: boolean;
    tagQueryMode?: "all" | "any";
}

Property basket

If provided, indicates which basket the outputs should be selected from.

basket?: string

Property includeBasket

If true, the DojoOutputXApi basket property will be included in results.

includeBasket?: boolean

Property includeCustomInstructions

If provided, returns customInstructions for each output. Note that includeEnvelope also enables including customInstructions

includeCustomInstructions?: boolean

Property includeEnvelope

If provided, returns a structure with the SPV envelopes for the UTXOS that have not been spent.

includeEnvelope?: boolean

Property includeTags

If true, the DojoOutputXApi tags property will be included in results.

includeTags?: boolean

Property spendable

If given as true or false, only outputs that have or have not (respectively) been spent will be returned. If not given, both spent and unspent outputs will be returned.

spendable?: boolean

Property tagQueryMode

When tags contains more than one value, determines if each output returned must have all of the tags or any of the tags.

The default is all

tagQueryMode?: "all" | "any"

Property tags

An optional array of output tag names

tags?: string[]

Property tracked

If provided, only outputs with the corresponding tracked value will be returned (true/false).

tracked?: boolean

Property type

If provided, only outputs of the specified type will be returned. If not provided, outputs of all types will be returned.

type?: string

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

Interface: DojoGetTransactionsResultApi

export interface DojoGetTransactionsResultApi {
    txs: DojoTransactionXApi[];
    total: number;
}

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

Interface: DojoGetTransactionOutputsResultApi

export interface DojoGetTransactionOutputsResultApi {
    outputs: DojoOutputXApi[];
    total: number;
}

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

Interface: DojoGetTransactionLabelsResultApi

export interface DojoGetTransactionLabelsResultApi {
    labels: DojoTxLabelApi[];
    total: number;
}

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

Interface: DojoGetTransactionLabelsOptions

export interface DojoGetTransactionLabelsOptions extends DojoGetTransactionsBaseOptions {
    prefix?: string;
    transactionId?: number;
    sortBy?: DojoTransactionLabelsSortBy;
}

Property prefix

Optional. Filters labels to include only those starting with the specified prefix.

prefix?: string

Property sortBy

Optional. Specify whether to sort by 'label' or 'whenLastUsed'.

sortBy?: DojoTransactionLabelsSortBy

Property transactionId

Optional. Filters labels to include only those associated with the specified transaction ID.

transactionId?: number

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

Interface: DojoGetTotalOfAmountsOptions

export interface DojoGetTotalOfAmountsOptions {
    label?: string;
    startTime?: Date | string | number;
    endTime?: Date | string | number;
    involving?: string;
    direction?: "incoming" | "outgoing";
}

Property direction

Direction of value flow.

direction?: "incoming" | "outgoing"

Property endTime

Optional. Match transactions created on or before this time. Seconds since the epoch.

endTime?: Date | string | number

Property involving

Optional. Match transactions with either senderPaymail or recipientPaymail matching this value.

involving?: string

Property label

Optional. Match transactions with this label.

label?: string

Property startTime

Optional. Match transactions created on or after this time. Seconds since the epoch.

startTime?: Date | string | number

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

Interface: DojoStatsApi

export interface DojoStatsApi {
    users: number;
    transactions: number;
    txLabels: number;
    outputTags: number;
    chain: Chain;
}

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

Interface: DojoUserStateApi

export interface DojoUserStateApi {
    since?: Date;
    user: DojoUserApi;
    certificates: DojoCertificateApi[];
    certificateFields: DojoCertificateFieldApi[];
    commissions: DojoCommissionApi[];
    mapiResponses: DojoMapiResponseApi[];
    outputs: DojoOutputApi[];
    baskets: DojoOutputBasketApi[];
    provenTxReqs: DojoProvenTxReqApi[];
    provenTxs: DojoProvenTxApi[];
    txs: DojoTransactionApi[];
    txLabels: DojoTxLabelApi[];
    txLabelMaps: DojoTxLabelMapApi[];
    outputTags: DojoOutputTagApi[];
    outputTagMaps: DojoOutputTagMapApi[];
}

Property since

If undefined, this is the complete state for the given user.

If a valid Date, these are the entities updated since that date.

since?: Date

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

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

ex