@babbage/sdk-ts v0.2.65

@babbage/sdk-ts

Build Babbage apps in TypeScript

NPM Package

GitHub Repository

Installation

npm i @babbage/sdk

By Example

There are a few example projects you can check out which implement the Babbage SDK:

• 🎵Tempo: A platform for creating and sharing music, and empowering artists with micropayments
• ✅Simple ToDo List: An app that demonstrates the basics of Bitcoin tokenization and identity

Documentation

📒 The JavaScript API is documented below the examples, in the API section

The 📚Babbage Learn website hosts the concepts, guides and reference materials that show you how the SDK works.

Example Usage

Encryption

import { encrypt, decrypt } from '@babbage/sdk-ts'

// Encrypt and decrypt data using the Babbage SDK
const encryptedData = await encrypt({
  plaintext: Buffer.from('some data'),
  protocolID: [0, 'Hello World'],
  keyID: '1'
})

// The same protocol and key ID is needed for decryption
const decryptedData = await decrypt({
  ciphertext: encryptedData,
  protocolID: [0, 'Hello World'],
  keyID: '1',
  returnType: 'string'
})

Creating and Redeeming Bitcoin tokens

This example also uses PushDrop

import { createAction } from '@babbage/sdk-ts'
import { create, redeem } from 'pushdrop'

const bitcoinOutputScript = await create({
  fields: [ // The "fields" are the data payload to attach to the token.
    Buffer.from('My First Token'),
    Buffer.from('My name is Ty') // Tokens can represent anything!
  ],
  // The "first token" protocol and key ID can be used to sign and 
  // lock this new Bitcoin PushDrop token.
  protocolID: 'first token',
  keyID: '1'
})

const newToken = await createAction({
  // The Bitcoin transaction ("Action" with a capital A) has an output, 
  // because it has led to the creation of a new Bitcoin token.
  outputs: [{
    // The output amount is how much Bitcoin (measured in "satoshis") 
    // this token is worth. Let's use 1000 satoshis.
    satoshis: 1000,
    // The output script for this token was created by the PushDrop library, 
    // which you can see above.
    script: bitcoinOutputScript
  }],
  // Finally, we'll describe the Action for the user
  description: 'Create my first token'
})

// Here, we're using the PushDrop library to unlcok / redeem the PushDrop 
// token that was previously created. By providing this information, 
// PushDrop can "unlock" and spend the token. When the token gets spent, 
// the user gets their 1000 satoshis back.
const unlockingScript = await pushdrop.redeem({
  // To unlock the token, we need to use the same "first token" protocol 
  // and key ID as when we created the token before. Otherwise, the 
  // key won't fit the lock and the Bitcoins won't come out.
  protocolID: 'first token',
  keyID: '1',
  // We're telling PushDrop which previous transaction and output we want to
  // unlock, so that the correct unlocking puzzle can be prepared.
  prevTxId: newToken.txid,
  outputIndex: 0, // The first output from the transaction
  // We also give PushDrop a copy of the locking puzzle ("script") that 
  // we want to open, which is helpful in preparing to unlock it.
  lockingScript: bitcoinOutputScript,
  // Finally, the number of satoshis we are expecting to unlock when the 
  // puzzle gets solved.
  outputAmount: 1000
})

// Now, we're going to use the unlocking puzle that PushDrop has prepared for us,
// so that the user can get their Bitcoins back. This is another "Action", which
// is just a Bitcoin transaction.
// The amount the user gets back will be slightly less, because of transaction fees.
await createAction({
  inputs: { // These are inputs, which unlock Bitcoin tokens.
    // The input comes from the token which we're completing
    [newToken.txid]: {
      ...newToken,
      // The output we want to redeem is specified here, and we also give 
      // the unlocking puzzle ("script") from PushDrop.
      outputsToRedeem: [{
        index: 0, // The first output of the transaction
        unlockingScript
      }]
    }
  },
  // Let the user know why they're getting some Bitcoins back
  description: 'Redeem my first token'
})

🏆 After reading the above two examples, could you implement a token with encrypted data? 🏆

API

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

Interfaces

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

Interface: AbortActionResult

export interface AbortActionResult {
    referenceNumber: string;
    log?: string;
}

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

Interface: CertificateApi

export interface CertificateApi {
    type: string;
    subject: string;
    validationKey: string;
    serialNumber: string;
    certifier: string;
    revocationOutpoint: string;
    signature: string;
    fields?: Record<string, string>;
}

Property certifier

max length of 255

certifier: string

Property fields

Certificate fields object where keys are field names and values are field value.

fields?: 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: CounterpartyKeyLinkageResult

export interface CounterpartyKeyLinkageResult {
    type: "counterparty-revelation";
    prover: string;
    verifier: string;
    counterparty: string;
    revelationTime: string;
    encryptedLinkage: string;
}

Property revelationTime

ISO date string

revelationTime: string

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

Interface: CreateActionInput

export interface CreateActionInput extends OptionalEnvelopeEvidenceApi {
    outputsToRedeem: CreateActionOutputToRedeem[];
}

See also: CreateActionOutputToRedeem, OptionalEnvelopeEvidenceApi

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

Interface: CreateActionOptions

export interface CreateActionOptions {
    acceptDelayedBroadcast?: boolean;
    trustSelf?: TrustSelf;
    knownTxids?: string[];
    resultFormat?: "beef" | "none";
    noSend?: boolean;
    noSendChange?: OutPoint[];
    sendWith?: string[];
}

See also: OutPoint, TrustSelf

Property acceptDelayedBroadcast

true if local validation and self-signed mapi response is sufficient. Upon return, transaction will have sending status. Watchman will proceed to send the transaction asynchronously.

false if a valid mapi response from the bitcoin transaction processing network is required. Upon return, transaction will have unproven status. Watchman will proceed to prove transaction.

default true

acceptDelayedBroadcast?: boolean

Property knownTxids

If the caller already has envelopes or BUMPS for certain txids, pass them in this array and they will be assumed to be valid and not returned again in the results.

knownTxids?: string[]

Property noSend

If true, successfully created transactions remain in the nosend state. A proof will be sought but it will not be considered an error if the txid remains unknown.

Supports testing, user control over broadcasting of transactions, and batching.

noSend?: boolean

Property noSendChange

Available transaction fee payment output(s) belonging to the user.

Only change outputs previously created by a noSend transaction.

Supports chained noSend transactions by minimizing the consumption and non-replenishment of change outputs.

noSendChange?: OutPoint[]

See also: OutPoint

Property resultFormat

If 'beef', the results will format new transaction and supporting input proofs in BEEF format. If 'none', the results will include only the txid of the new transaction. Otherwise, the results will use EnvelopeEvidenceApi format.

resultFormat?: "beef" | "none"

Property sendWith

Setting sendWith to an array of txid values for previously created noSend transactions causes all of them to be sent to the bitcoin network as a single batch of transactions.

When using sendWith, createAction can be called without inputs or outputs, in which case previously created noSend transactions will be sent without creating a new transaction.

sendWith?: string[]

Property trustSelf

If undefined, normal case, all inputs must be provably valid by chain of rawTx and merkle proof values, and results will include new rawTx and proof chains for new outputs.

If 'known', any input txid corresponding to a previously processed transaction may ommit its rawTx and proofs, and results will exclude new rawTx and proof chains for new outputs.

trustSelf?: TrustSelf

See also: TrustSelf

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

Interface: CreateActionOutput

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

export interface CreateActionOutput {
    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: CreateActionOutputToRedeem

export interface CreateActionOutputToRedeem {
    index: number;
    unlockingScript: string | number;
    spendingDescription?: string;
    sequenceNumber?: number;
}

Property index

Zero based output index within its transaction to spend, vout.

index: number

Property sequenceNumber

Sequence number to use when spending

sequenceNumber?: number

Property unlockingScript

Hex scriptcode that unlocks the satoshis or the maximum script length (in bytes) if using signAction.

Note that you should create any signatures with SIGHASH_NONE | ANYONECANPAY or similar so that the additional Dojo outputs can be added afterward without invalidating your signature.

unlockingScript: string | number

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

Interface: CreateActionParams

export interface CreateActionParams {
    description: string;
    inputs?: Record<string, CreateActionInput>;
    beef?: Beef | number[];
    outputs?: CreateActionOutput[];
    lockTime?: number;
    version?: number;
    labels?: string[];
    originator?: string;
    options?: CreateActionOptions;
    acceptDelayedBroadcast?: boolean;
    log?: string;
}

See also: CreateActionInput, CreateActionOptions, CreateActionOutput

Property acceptDelayedBroadcast

true if local validation and self-signed mapi response is sufficient. Upon return, transaction will have sending status. Watchman will proceed to send the transaction asynchronously.

false if a valid mapi response from the bitcoin transaction processing network is required. Upon return, transaction will have unproven status. Watchman will proceed to prove transaction.

default true

DEPRECATED: Use options.acceptDelayedBroadcast instead.

acceptDelayedBroadcast?: boolean

Property beef

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

beef?: Beef | number[]

Property description

Human readable string giving the purpose of this transaction. Value will be encrypted prior to leaving this device. Encrypted length limit is 500 characters.

description: string

Property inputs

If an input is self-provided (known to user's Dojo), or if beef is used, envelope evidence can be ommitted, reducing data size and processing time.

each input's outputsToRedeem:

• satoshis must be greater than zero, must match output's value.
• spendingDescription length limit is 50, values are encrypted before leaving this device
• unlockingScript is max byte length for signActionRequired mode, otherwise hex string.

inputs?: Record<string, CreateActionInput>

See also: CreateActionInput

Property labels

transaction labels to apply to this transaction default []

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 options

Processing options.

options?: CreateActionOptions

See also: CreateActionOptions

Property originator

Reserved Admin originators 'projectbabbage.com' 'staging-satoshiframe.babbage.systems' 'satoshiframe.babbage.systems'

originator?: string

Property outputs

each output:

• description length limit is 50, values are encrypted before leaving this device

outputs?: CreateActionOutput[]

See also: CreateActionOutput

Property version

Optional. Transaction version number, default is current standard transaction version value.

version?: number

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

Interface: CreateActionResult

export interface CreateActionResult {
    signActionRequired?: boolean;
    createResult?: DojoCreateTransactionResultApi;
    txid?: string;
    rawTx?: string;
    inputs?: Record<string, OptionalEnvelopeEvidenceApi>;
    beef?: number[];
    noSendChange?: OutPoint[];
    mapiResponses?: MapiResponseApi[];
    sendWithResults?: DojoSendWithResultsApi[];
    options?: CreateActionOptions;
    log?: string;
}

See also: CreateActionOptions, DojoCreateTransactionResultApi, DojoSendWithResultsApi, MapiResponseApi, OptionalEnvelopeEvidenceApi, OutPoint

Property beef

Valid for options.resultFormat 'beef', in which case rawTx and inputs will be undefined.

Change output(s) that may be forwarded to chained noSend transactions.

beef?: number[]

Property createResult

if signActionRequired, the dojo createTransaction results to be forwarded to signAction

createResult?: DojoCreateTransactionResultApi

See also: DojoCreateTransactionResultApi

Property inputs

This is the fully-formed inputs field of this transaction, as per the SPV Envelope specification.

inputs?: Record<string, OptionalEnvelopeEvidenceApi>

See also: OptionalEnvelopeEvidenceApi

Property log

operational and performance logging if enabled.

log?: string

Property mapiResponses

If not signActionRequired, at least one valid mapi response. may be a self-signed response if acceptDelayedBroadcast is true.

If signActionRequired, empty array.

mapiResponses?: MapiResponseApi[]

See also: MapiResponseApi

Property noSendChange

Valid for options.noSend true.

Change output(s) that may be forwarded to chained noSend transactions.

noSendChange?: OutPoint[]

See also: OutPoint

Property options

Processing options.

options?: CreateActionOptions

See also: CreateActionOptions

Property rawTx

if not signActionRequired, fully signed transaction as LE hex string

if signActionRequired:

• All length specified unlocking scripts are zero bytes
• All SABPPP template unlocking scripts have zero byte signatures
• All custom provided unlocking scripts fully copied.

rawTx?: string

Property signActionRequired

true if at least one input's outputsToRedeem uses numeric max script byte length for unlockingScript

If true, in-process transaction will have status unsigned. An unsigned transaction must be completed by signing all remaining unsigned inputs and calling signAction. Failure to complete the process in a timely manner will cause the transaction to transition to failed.

If false or undefined, completed transaction will have status of sending, nosend or unproven, depending on acceptDelayedBroadcast and noSend.

signActionRequired?: boolean

Property txid

if not signActionRequired, signed transaction hash (double SHA256 BE hex string)

txid?: string

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

Interface: CreateCertificateResult

export interface CreateCertificateResult extends CertificateApi {
    type: string;
    subject: string;
    validationKey: string;
    serialNumber: string;
    certifier: string;
    revocationOutpoint: string;
    signature: string;
    fields?: Record<string, string>;
    masterKeyring?: Record<string, string>;
}

See also: CertificateApi

Property certifier

max length of 255

certifier: string

Property fields

Certificate fields object where keys are field names and values are field value.

fields?: Record<string, string>

Property masterKeyring

Certificate masterKeyring object where keys are field names and values are field masterKey value.

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

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

See also: DojoCreateTxResultOutputApi, DojoCreatingTxInputsApi

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

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

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

Interface: DojoCreateTxResultOutputApi

export interface DojoCreateTxResultOutputApi extends DojoCreateTxOutputApi {
    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 extends EnvelopeEvidenceApi {
    outputsToRedeem: DojoOutputToRedeemApi[];
    providedBy: DojoProvidedByApi;
    instructions: Record<number, DojoCreateTxResultInstructionsApi>;
}

See also: DojoCreateTxResultInstructionsApi, DojoOutputToRedeemApi, DojoProvidedByApi, EnvelopeEvidenceApi

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

Interface: DojoOutputToRedeemApi

export interface DojoOutputToRedeemApi {
    index: number;
    unlockingScriptLength: number;
    spendingDescription?: string;
}

Property index

Zero based output index within its transaction to spend.

index: number

Property unlockingScriptLength

byte length of unlocking script

Note: To protect client keys and utxo control, unlocking scripts are never shared with Dojo.

unlockingScriptLength: number

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

Interface: DojoSendWithResultsApi

export interface DojoSendWithResultsApi {
    txid: string;
    transactionId: number;
    reference: string;
    status: "unproven" | "failed" | "sending";
}

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

Interface: EnvelopeApi

Simplest case of an envelope is a rawTx and merkle proof that ties the transaction to a known block header. This will be the case for any sufficiently old transaction.

If the transaction has been mined but for some reason the block headers may not be known, an array of headers linking known headers to the one needed by the proof may be provided. They must be in height order and need to overlap a known header.

If the transaction has not been minded yet but it has been submitted to one or more miners then the mapi responses received, proving that specific miners have received the transaction for processing, are included in the mapiResponses array. Note that the miner reputations must be checked to give weight to these responses.

Additionally, when the transaction hasn't been mined or a proof is unavailable and mapi responses proving miner acceptance are unavailable, then all the transactions providing inputs can be submitted in an inputs object.

The keys of the inputs object are the transaction hashes (txids) of each of the input transactions. The value of each inputs object property is another envelope object.

References: Section 2 of https://projectbabbage.com/assets/simplified-payments.pdf https://gist.github.com/ty-everett/44b6a0e7f3d6c48439f9ff26068f8d8b

export interface EnvelopeApi extends EnvelopeEvidenceApi {
    headers?: string[];
    reference?: string;
}

See also: EnvelopeEvidenceApi

Property headers

For root nodes only. Array of 80 byte block headers encoded as 160 character hex strings Include headers the envelope creator is aware of but which the resipient may not have.

headers?: string[]

Property reference

Arbitrary reference string associated with the envelope, typically root node only.

reference?: string

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

Interface: EnvelopeEvidenceApi

Either inputs or proof are required.

export interface EnvelopeEvidenceApi {
    rawTx: string;
    proof?: TscMerkleProofApi | Buffer;
    inputs?: Record<string, EnvelopeEvidenceApi>;
    txid?: string;
    mapiResponses?: MapiResponseApi[];
    depth?: number;
}

See also: MapiResponseApi, TscMerkleProofApi

Property depth

count of maximum number of chained unproven transactions before a proven leaf node proof nodes have depth zero.

depth?: number

Property inputs

Only one of proof or inputs must be valid. Branching nodes have inputs with a sub envelope (values) for every input transaction txid (keys)

inputs?: Record<string, EnvelopeEvidenceApi>

See also: EnvelopeEvidenceApi

Property mapiResponses

Array of mapi transaction status update responses Only the payload, signature, and publicKey properties are relevant.

Branching inputs nodes only. Array of mapi transaction status update responses confirming unproven transctions have at least been submitted for processing.

mapiResponses?: MapiResponseApi[]

See also: MapiResponseApi

Property proof

Either proof, or inputs, must have a value. Leaf nodes have proofs.

If value is a Buffer, content is binary encoded serialized proof see: chaintracks-spv.utils.serializeTscMerkleProof

proof?: TscMerkleProofApi | Buffer

See also: TscMerkleProofApi

Property rawTx

A valid bitcoin transaction encoded as a hex string.

rawTx: string

Property txid

double SHA256 hash of serialized rawTx. Optional.

txid?: string

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

Interface: GetInfoParams

export interface GetInfoParams {
    description?: string;
}

Property description

Describe the high-level operation being performed, so that the user can make an informed decision if permission is needed.

description?: string

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

Interface: GetInfoResult

export interface GetInfoResult {
    metanetClientVersion: string;
    chain: Chain;
    height: number;
    userId: number;
    userIdentityKey: string;
    dojoIdentityKey: string;
    dojoIdentityName?: string;
    perferredCurrency: string;
}

See also: Chain

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

Interface: GetTransactionOutputResult

export interface GetTransactionOutputResult {
    txid: string;
    vout: number;
    amount: number;
    outputScript: string;
    type: string;
    spendable: boolean;
    envelope?: EnvelopeApi;
    customInstructions?: string;
    basket?: string;
    tags?: string[];
}

See also: EnvelopeApi

Property amount

Number of satoshis in the output

amount: number

Property basket

If includeBasket option is true, name of basket to which this output belongs.

basket?: string

Property customInstructions

When envelope requested, any custom instructions associated with this output.

customInstructions?: string

Property envelope

When requested and available, output validity support envelope.

envelope?: EnvelopeApi

See also: EnvelopeApi

Property outputScript

Hex representation of output locking script

outputScript: string

Property spendable

Whether this output is free to be spent

spendable: boolean

Property tags

If includeTags option is true, tags assigned to this output.

tags?: string[]

Property txid

Transaction ID of transaction that created the output

txid: string

Property type

The type of output, for example "P2PKH" or "P2RPH"

type: string

Property vout

Index in the transaction of the output

vout: number

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

Interface: ListActionsResult

export interface ListActionsResult {
    totalTransactions: number;
    transactions: ListActionsTransaction[];
}

See also: ListActionsTransaction

Property totalTransactions

The number of transactions in the complete set

totalTransactions: number

Property transactions

The specific transactions from the set that were requested, based on limit and offset

transactions: ListActionsTransaction[]

See also: ListActionsTransaction

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

Interface: ListActionsTransaction

export interface ListActionsTransaction {
    txid: string;
    amount: number;
    status: TransactionStatusApi;
    senderPaymail: string;
    recipientPaymail: string;
    isOutgoing: boolean;
    note: string;
    created_at: string;
    referenceNumber: string;
    labels: string[];
    inputs?: ListActionsTransactionInput[];
    outputs?: ListActionsTransactionOutput[];
}

See also: ListActionsTransactionInput, ListActionsTransactionOutput, TransactionStatusApi

Property amount

The number of satoshis added or removed from Dojo by this transaction

amount: number

Property created_at

The time the transaction was registered with the Dojo

created_at: string

Property isOutgoing

Whether or not the transaction was created with createTransaction

isOutgoing: boolean

Property labels

A set of all the labels affixed to the transaction

labels: string[]

Property note

The human-readable tag for the transaction, provided by the person who initiated it

note: string

Property recipientPaymail

The Paymail handle of the person who received the transaction

recipientPaymail: string

Property referenceNumber

The Dojo reference number for the transaction

referenceNumber: string

Property senderPaymail

The Paymail handle of the person who sent the transaction

senderPaymail: string

Property status

The current state of the transaction. Common statuses are completed and unproven.

status: TransactionStatusApi

See also: TransactionStatusApi

Property txid

The transaction ID

txid: string

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

Interface: ListActionsTransactionInput

export interface ListActionsTransactionInput {
    txid: string;
    vout: number;
    amount: number;
    outputScript: string;
    type: string;
    spendable: boolean;
    spendingDescription?: string;
    basket?: string;
    tags?: string[];
}

Property amount

Number of satoshis in the output

amount: number

Property basket

Optionally included basket assignment.

basket?: string

Property outputScript

Hex representation of output locking script

outputScript: string

Property spendable

Whether this output is free to be spent

spendable: boolean

Property spendingDescription

Spending description for this transaction input

spendingDescription?: string

Property tags

Optionally included tag assignments.

tags?: string[]

Property txid

Transaction ID of transaction that created the output

txid: string

Property type

The type of output, for example "P2PKH" or "P2RPH"

type: string

Property vout

Index in the transaction of the output

vout: number

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

Interface: ListActionsTransactionOutput

export interface ListActionsTransactionOutput {
    txid: string;
    vout: number;
    amount: number;
    outputScript: string;
    type: string;
    spendable: boolean;
    description?: string;
    basket?: string;
    tags?: string[];
}

Property amount

Number of satoshis in the output

amount: number

Property basket

Optionally included basket assignment.

basket?: string

Property description

Output description

description?: string

Property outputScript

Hex representation of output locking script

outputScript: string

Property spendable

Whether this output is free to be spent

spendable: boolean

Property tags

Optionally included tag assignments.

tags?: string[]

Property txid

Transaction ID of transaction that created the output

txid: string

Property type

The type of output, for example "P2PKH" or "P2RPH"

type: string

Property vout

Index in the transaction of the output

vout: number

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

Interface: MapiResponseApi

export interface MapiResponseApi {
    payload: string;
    signature: string;
    publicKey: string;
    encoding?: string;
    mimetype?: string;
}

Property encoding

encoding of the payload data

encoding?: string

Property mimetype

mime type of the payload data

mimetype?: string

Property payload

Contents of the envelope. Validate using signature and publicKey. encoding and mimetype may assist with decoding validated payload.

payload: string

Property publicKey

public key to use to verify signature of payload data

publicKey: string

Property signature

signature producted by correpsonding private key on payload data

signature: string

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

Interface: OptionalEnvelopeEvidenceApi

Either rawTx or txid are required. If txid, then it must be a known transaction.

If not a known trxid, either inputs or proof are required.

export interface OptionalEnvelopeEvidenceApi {
    rawTx?: string;
    proof?: TscMerkleProofApi | Buffer;
    inputs?: Record<string, OptionalEnvelopeEvidenceApi>;
    txid?: string;
    mapiResponses?: MapiResponseApi[];
    depth?: number;
}

See also: MapiResponseApi, TscMerkleProofApi

Property depth

count of maximum number of chained unproven transactions before a proven leaf node proof nodes have depth zero.

depth?: number

Property inputs

Only one of proof or inputs must be valid. Branching nodes have inputs with a sub envelope (values) for every input transaction txid (keys)

inputs?: Record<string, OptionalEnvelopeEvidenceApi>

See also: OptionalEnvelopeEvidenceApi

Property mapiResponses

Array of mapi transaction status update responses Only the payload, signature, and publicKey properties are relevant.

Branching inputs nodes only. Array of mapi transaction status update responses confirming unproven transctions have at least been submitted for processing.

mapiResponses?: MapiResponseApi[]

See also: MapiResponseApi

Property proof

Either proof, or inputs, must have a value. Leaf nodes have proofs.

If value is a Buffer, content is binary encoded serialized proof see: chaintracks-spv.utils.serializeTscMerkleProof

proof?: TscMerkleProofApi | Buffer

See also: TscMerkleProofApi

Property rawTx

A valid bitcoin transaction encoded as a hex string.

rawTx?: string

Property txid

double SHA256 hash of serialized rawTx. Optional.

txid?: string

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

Interface: OutPoint

Identifies a unique transaction output by its txid and index vout

export interface OutPoint {
    txid: string;
    vout: number;
}

Property txid

Transaction double sha256 hash as big endian hex string

txid: string

Property vout

zero based output index within the transaction

vout: number

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

Interface: ProveCertificateResult

export interface ProveCertificateResult extends CertificateApi {
    type: string;
    subject: string;
    validationKey: string;
    serialNumber: string;
    certifier: string;
    revocationOutpoint: string;
    signature: string;
    fields?: Record<string, string>;
    keyring: Record<string, string>;
}

See also: CertificateApi

Property certifier

max length of 255

certifier: string

Property fields

Plaintext field names and values of only those fields requested in fieldsToReveal

fields?: Record<string, string>

Property keyring

field revelation keyring for the given verifier

keyring: 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: SignActionResult

export interface SignActionResult {
    rawTx: string;
    inputs: Record<string, EnvelopeEvidenceApi>;
    mapiResponses: MapiResponseApi[];
    txid: string;
    log?: string;
}

See also: EnvelopeEvidenceApi, MapiResponseApi

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

Interface: SpecificKeyLinkageResult

export interface SpecificKeyLinkageResult {
    type: "specific-revelation";
    prover: string;
    verifier: string;
    counterparty: string;
    protocolID: ProtocolID;
    encryptedLinkage: string;
}

See also: ProtocolID

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

Interface: SubmitDirectTransaction

export interface SubmitDirectTransaction {
    rawTx: string;
    txid?: string;
    inputs?: Record<string, OptionalEnvelopeEvidenceApi>;
    mapiResponses?: MapiResponseApi[];
    proof?: TscMerkleProofApi;
    outputs: SubmitDirectTransactionOutput[];
    referenceNumber?: string;
}

See also: MapiResponseApi, OptionalEnvelopeEvidenceApi, SubmitDirectTransactionOutput, TscMerkleProofApi

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

Interface: SubmitDirectTransactionOutput

export interface SubmitDirectTransactionOutput {
    vout: number;
    satoshis: number;
    basket?: string;
    derivationPrefix?: string;
    derivationSuffix?: string;
    customInstructions?: string;
    senderIdentityKey?: string;
    tags?: string[];
}

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

Interface: SubmitDirectTransactionResult

export interface SubmitDirectTransactionResult {
    transactionId: number;
    referenceNumber: string;
}

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

Interface: TscMerkleProofApi

As defined in https://github.com/bitcoin-sv-specs/brfc-merchantapi/blob/master/README.md

export interface TscMerkleProofApi {
    height?: number;
    index: number;
    txOrId: string | Buffer;
    target: string | Buffer;
    nodes: string[] | Buffer;
    targetType?: "hash" | "header" | "merkleRoot" | "height";
    proofType?: "branch" | "tree";
    composite?: boolean;
}

Property height

The most efficient way of confirming a proof should also be the most common, when the containing block's height is known.

height?: number

Property index

Index of transaction in its block. First transaction is index zero.

index: number

Property nodes

Merkle tree sibling hash values required to compute root from txid. Duplicates (sibling hash === computed hash) are indicated by "*" or type byte === 1. type byte === 2... Strings are encoded as hex.

nodes: string[] | Buffer

Property target

Merkle root (length === 32) or serialized block header containing it (length === 80). If string, encoding is hex.

target: string | Buffer

Property txOrId

Full transaction (length > 32 bytes) or just its double SHA256 hash (length === 32 bytes). If string, encoding is hex.

txOrId: string | Buffer

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

Classes

Class: Communicator

export class Communicator {
    static setCached(substrate: string, version: string): Communicator 
    static getCached(): Communicator | undefined 
    async dispatch<P extends object>(args: {
        name: string;
        params: P;
        isGet?: boolean;
        bodyParamKey?: string;
        bodyJsonParams?: boolean;
        contentType?: string;
        nameHttp?: string;
        isNinja?: boolean;
    }): Promise<unknown> 
}

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

Functions

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

Function: abortAction

Aborts a previously created action which required custom input unlocking script signing.

export async function abortAction(args: {
    referenceNumber: string;
    log?: string;
}): Promise<AbortActionResult> 

See also: AbortActionResult

Returns

An Action object containing "txid", "rawTx" "mapiResponses" and "inputs".

Argument Details

• args
  • All parameters for this function are provided in an object

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

Function: asArray

export function asArray(val: Buffer | string | number[], encoding?: BufferEncoding): number[] 

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

Function: asBsvSdkScript

export function asBsvSdkScript(script: string | Buffer | Script): Script 

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

Function: asBsvSdkTx

export function asBsvSdkTx(tx: string | Buffer | Transaction): Transaction 

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

Function: asBuffer

export function asBuffer(val: Buffer | string | number[], encoding?: BufferEncoding): Buffer 

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

Function: asString

export function asString(val: Buffer | string, encoding?: BufferEncoding): string 

Argument Details

• val
  • Value to convert to encoded string if not already a string.

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

Function: buildTransactionForSignActionUnlocking

Constructs a

export async function buildTransactionForSignActionUnlocking(ninjaInputs: Record<string, CreateActionInput>, createResult: DojoCreateTransactionResultApi): Promise<Transaction> 

See also: CreateActionInput, DojoCreateTransactionResultApi

Argument Details

• ninjaInputs
  • Ninja inputs as passed to createAction
• createResult
  • Create transaction results returned by createAction when signActionRequires is true.
• changeKeys
  • Dummy keys can be used to create a transaction with which to generate Ninja input lockingScripts.

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

Function: connectToSubstrate

export default async function connectToSubstrate(): Promise<Communicator> 

See also: Communicator

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

Function: convertMerklePathToProof

Convert a MerklePath to a single BRC-10 proof

export function convertMerklePathToProof(txid: string, mp: MerklePath): TscMerkleProofApi 

See also: TscMerkleProofApi

Returns

transaction proof in BRC-10 string format.

Argument Details

• txid
  • the txid in mp for which a BRC-10 proof is needed
• mp
  • MerklePath

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

Function: convertProofToMerklePath

Convert a single BRC-10 proof to a MerklePath

export function convertProofToMerklePath(txid: string, proof: TscMerkleProofApi): MerklePath 

See also: TscMerkleProofApi

Returns

corresponding MerklePath

Argument Details

• txid
  • transaction hash as big endian hex string
• proof
  • transaction proof in BRC-10 string format.

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

Function: convertProofToMerklePathWithLookup

export async function convertProofToMerklePathWithLookup(txid: string, proof: TscMerkleProofApi, lookupHeight: (targetType: "hash" | "header" | "merkleRoot" | "height", target: string | Buffer) => Promise<number>): Promise<MerklePath> 

See also: TscMerkleProofApi

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

Function: createAction

Creates and broadcasts a BitCoin transaction with the provided inputs and outputs.

export async function createAction(args: CreateActionParams): Promise<CreateActionResult> 

See also: CreateActionParams, CreateActionResult

Returns

An Action object containing "txid", "rawTx" "mapiResponses" and "inputs".

Argument Details

• args
  • All parameters for this function are provided in an object

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

Function: createCertificate

Creates a signed certificate

export async function createCertificate(args: {
    certificateType: string;
    fieldObject: Record<string, string>;
    certifierUrl: string;
    certifierPublicKey: string;
}): Promise<CreateCertificateResult> 

See also: CreateCertificateResult

Returns

A signed certificate

Argument Details

• args
  • All parameters for this function are provided in an object

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

Function: createHmac

Creates a SHA-256 HMAC with a key belonging to the user.

export async function createHmac(args: {
    data: Uint8Array | string;
    protocolID: ProtocolID;
    keyID: string;
    description?: string;
    counterparty?: string;
    privileged?: boolean;
}): Promise<Uint8Array> 

See also: ProtocolID

Returns

The SHA-256 HMAC of the data.

Argument Details

• args
  • All parameters are passed in an object.

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

Function: createSignature

Creates a digital signature with a key belonging to the user. The SHA-256 hash of the data is used with ECDSA.

To allow other users to externally verify the signature, use getPublicKey with the same protocolID, keyID and privileged parameters. The signature should be valid under that public key.

export async function createSignature(args: {
    data: Uint8Array | string;
    protocolID: ProtocolID;
    keyID: string;
    description?: string;
    counterparty?: string;
    privileged?: boolean;
}): Promise<Uint8Array> 

See also: ProtocolID

Returns

The ECDSA message signature.

Argument Details

• args
  • All parameters are passed in an object.

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

Function: decrypt

Decrypts data with a key belonging to the user. The same protocolID, keyID, counterparty and privileged parameters that were used during encryption must be used to successfully decrypt.

export async function decrypt(args: {
    ciphertext: string | Uint8Array;
    protocolID: ProtocolID;
    keyID: string;
    description?: string;
    counterparty?: string;
    privileged?: boolean;
    returnType?: "Uint8Array" | "string";
}): Promise<string | Uint8Array> 

See also: ProtocolID

Returns

The decrypted plaintext.

Argument Details

• args
  • All parameters are passed in an object.

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

Function: decryptAsArray

Decrypts data with a key belonging to the user. The same protocolID, keyID, counterparty and privileged parameters that were used during encryption must be used to successfully decrypt.

export async function decryptAsArray(args: {
    ciphertext: string | Uint8Array;
    protocolID: ProtocolID;
    keyID: string;
    description?: string;
    counterparty?: string;
    privileged?: boolean;
}): Promise<Uint8Array> 

See also: ProtocolID

Returns

The decrypted plaintext.

Argument Details

• args
  • All parameters are passed in an object.

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

Function: decryptAsString

Decrypts data with a key belonging to the user. The same protocolID, keyID, counterparty and privileged parameters that were used during encryption must be used to successfully decrypt.

export async function decryptAsString(args: {
    ciphertext: string | Uint8Array;
    protocolID: ProtocolID;
    keyID: string;
    description?: string;
    counterparty?: string;
    privileged?: boolean;
}): Promise<string> 

See also: ProtocolID

Returns

The decrypted plaintext TextDecoder decoded to string.

Argument Details

• args
  • All parameters are passed in an object.

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

Function: discoverByAttributes

Resolves identity information by attributes from the user's trusted certifiers.

export async function discoverByAttributes(args: {
    attributes: Record<string, string>;
    description: string;
}): Promise<object[]> 

Argument Details

• obj
  • All parameters are provided in an object

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

Function: discoverByIdentityKey

Resolves identity information by identity key from the user's trusted certifiers.

export async function discoverByIdentityKey(args: {
    identityKey: string;
    description: string;
}): Promise<object[]> 

Argument Details

• obj
  • All parameters are provided in an object

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

Function: doubleSha256BE

Calculate the SHA256 hash of the SHA256 hash of a Buffer.

export function doubleSha256BE(data: string | Buffer, encoding?: BufferEncoding): Buffer {
    return doubleSha256HashLE(data, enc