@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

| | | | | --- | --- | --- | | AbortActionArgs | GetNetworkResult | SignableTransaction | | AbortActionResult | GetPublicKeyArgs | SpecificKeyLinkageResult | | AbortActionResult | GetPublicKeyResult | SubmitDirectTransaction | | AcquireCertificateArgs | GetTransactionOutputResult | SubmitDirectTransactionOutput | | AcquireCertificateResult | GetVersionResult | SubmitDirectTransactionResult | | AuthenticatedResult | IdentityCertificate | TscMerkleProofApi | | BasketInsertion | IdentityCertifier | ValidAbortActionArgs | | CertificateApi | InternalizeActionArgs | ValidAcquireCertificateArgs | | CounterpartyKeyLinkageResult | InternalizeActionResult | ValidBasketInsertion | | CreateActionArgs | InternalizeOutput | ValidCreateActionArgs | | CreateActionInput | KeyDeriverApi | ValidCreateActionInput | | CreateActionInput | KeyLinkageResult | ValidCreateActionOptions | | CreateActionOptions | ListActionsArgs | ValidCreateActionOutput | | CreateActionOptions | ListActionsResult | ValidInternalizeActionArgs | | CreateActionOutput | ListActionsResult | ValidInternalizeOutput | | CreateActionOutput | ListActionsTransaction | ValidListActionsArgs | | CreateActionOutputToRedeem | ListActionsTransactionInput | ValidListCertificatesArgs | | CreateActionParams | ListActionsTransactionOutput | ValidListOutputsArgs | | CreateActionResult | ListCertificatesArgs | ValidProcessActionArgs | | CreateActionResult | ListCertificatesResult | ValidProcessActionOptions | | CreateCertificateResult | ListOutputsArgs | ValidRelinquishOutputArgs | | CreateHmacArgs | ListOutputsResult | ValidSignActionArgs | | CreateHmacResult | MapiResponseApi | ValidSignActionOptions | | CreateSignatureArgs | OptionalEnvelopeEvidenceApi | ValidWalletPayment | | CreateSignatureResult | OutPoint | VerifyHmacArgs | | DiscoverByAttributesArgs | ProveCertificateArgs | VerifyHmacResult | | DiscoverByIdentityKeyArgs | ProveCertificateResult | VerifySignatureArgs | | DiscoverCertificatesResult | ProveCertificateResult | VerifySignatureResult | | DojoCreateTransactionResultApi | RelinquishCertificateArgs | Wallet | | DojoCreateTxOutputApi | RelinquishCertificateResult | WalletAction | | DojoCreateTxResultInstructionsApi | RelinquishOutputArgs | WalletActionInput | | DojoCreateTxResultOutputApi | RelinquishOutputResult | WalletActionOutput | | DojoCreatingTxInputsApi | RevealCounterpartyKeyLinkageArgs | WalletCertificate | | DojoOutputToRedeemApi | RevealCounterpartyKeyLinkageResult | WalletCryptoObject | | DojoSendWithResultsApi | RevealSpecificKeyLinkageArgs | WalletDecryptArgs | | EnvelopeApi | RevealSpecificKeyLinkageResult | WalletDecryptResult | | EnvelopeEvidenceApi | SendWithResult | WalletEncryptArgs | | GetHeaderArgs | SignActionArgs | WalletEncryptResult | | GetHeaderResult | SignActionOptions | WalletEncryptionArgs | | GetHeightResult | SignActionResult | WalletErrorObject | | GetInfoParams | SignActionResult | WalletOutput | | GetInfoResult | SignActionSpend | WalletPayment |

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

Interface: AbortActionArgs

export interface AbortActionArgs {
    reference: Base64String;
}

See also: Base64String

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

Interface: AbortActionResult

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

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

Interface: AbortActionResult

export interface AbortActionResult {
    aborted: boolean;
}

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

Interface: AcquireCertificateArgs

export interface AcquireCertificateArgs {
    type: Base64String;
    certifier: PubKeyHex;
    acquisitionProtocol: AcquisitionProtocol;
    fields: Record<CertificateFieldNameUnder50Bytes, string>;
    serialNumber?: Base64String;
    revocationOutpoint?: OutpointString;
    signature?: HexString;
    certifierUrl?: string;
    keyringRevealer?: KeyringRevealer;
    keyringForSubject?: Record<CertificateFieldNameUnder50Bytes, Base64String>;
    privileged?: BooleanDefaultFalse;
    privilegedReason?: DescriptionString5to50Bytes;
}

See also: AcquisitionProtocol, Base64String, BooleanDefaultFalse, CertificateFieldNameUnder50Bytes, DescriptionString5to50Bytes, HexString, KeyringRevealer, OutpointString, PubKeyHex

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

Interface: AcquireCertificateResult

export interface AcquireCertificateResult extends WalletCertificate {
}

See also: WalletCertificate

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

Interface: AuthenticatedResult

export interface AuthenticatedResult {
    authenticated: boolean;
}

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

Interface: BasketInsertion

export interface BasketInsertion {
    basket: BasketStringUnder300Bytes;
    customInstructions?: string;
    tags?: OutputTagStringUnder300Bytes[];
}

See also: BasketStringUnder300Bytes, OutputTagStringUnder300Bytes

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

export interface CreateActionArgs {
    description: DescriptionString5to50Bytes;
    inputBEEF?: BEEF;
    inputs?: CreateActionInput[];
    outputs?: CreateActionOutput[];
    lockTime?: PositiveIntegerOrZero;
    version?: PositiveIntegerOrZero;
    labels?: LabelStringUnder300Bytes[];
    options?: CreateActionOptions;
}

See also: BEEF, CreateActionInput, CreateActionOptions, CreateActionOutput, DescriptionString5to50Bytes, LabelStringUnder300Bytes, PositiveIntegerOrZero

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

export interface CreateActionInput {
    outpoint: OutpointString;
    inputDescription: DescriptionString5to50Bytes;
    unlockingScript?: HexString;
    unlockingScriptLength?: PositiveInteger;
    sequenceNumber?: PositiveIntegerOrZero;
}

See also: DescriptionString5to50Bytes, HexString, OutpointString, PositiveInteger, PositiveIntegerOrZero

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[];
    randomizeOutputs?: boolean;
}

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 randomizeOutputs

optional. When set to false, the wallet will avoid randomizing the order of outputs within the transaction.

randomizeOutputs?: boolean

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

export interface CreateActionOptions {
    signAndProcess?: BooleanDefaultTrue;
    acceptDelayedBroadcast?: BooleanDefaultTrue;
    trustSelf?: TrustSelf;
    knownTxids?: TXIDHexString[];
    returnTXIDOnly?: BooleanDefaultFalse;
    noSend?: BooleanDefaultFalse;
    noSendChange?: OutpointString[];
    sendWith?: TXIDHexString[];
    randomizeOutputs?: BooleanDefaultTrue;
}

See also: BooleanDefaultFalse, BooleanDefaultTrue, OutpointString, TXIDHexString, 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: CreateActionOutput

export interface CreateActionOutput {
    lockingScript: HexString;
    satoshis: SatoshiValue;
    outputDescription: DescriptionString5to50Bytes;
    basket?: BasketStringUnder300Bytes;
    customInstructions?: string;
    tags?: OutputTagStringUnder300Bytes[];
}

See also: BasketStringUnder300Bytes, DescriptionString5to50Bytes, HexString, OutputTagStringUnder300Bytes, SatoshiValue

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

export interface CreateActionResult {
    txid?: TXIDHexString;
    tx?: AtomicBEEF;
    noSendChange?: OutpointString[];
    sendWithResults?: SendWithResult[];
    signableTransaction?: SignableTransaction;
}

See also: AtomicBEEF, OutpointString, SendWithResult, SignableTransaction, TXIDHexString

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

export interface CreateHmacArgs extends WalletEncryptionArgs {
    data: Byte[];
}

See also: Byte, WalletEncryptionArgs

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

Interface: CreateHmacResult

export interface CreateHmacResult {
    hmac: Byte[];
}

See also: Byte

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

Interface: CreateSignatureArgs

export interface CreateSignatureArgs extends WalletEncryptionArgs {
    data?: Byte[];
    hashToDirectlySign?: Byte[];
}

See also: Byte, WalletEncryptionArgs

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

Interface: CreateSignatureResult

export interface CreateSignatureResult {
    signature: Byte[];
}

See also: Byte

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

Interface: DiscoverByAttributesArgs

export interface DiscoverByAttributesArgs {
    attributes: Record<CertificateFieldNameUnder50Bytes, string>;
    limit?: PositiveIntegerDefault10Max10000;
    offset?: PositiveIntegerOrZero;
    seekPermission?: BooleanDefaultTrue;
}

See also: BooleanDefaultTrue, CertificateFieldNameUnder50Bytes, PositiveIntegerDefault10Max10000, PositiveIntegerOrZero

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

Interface: DiscoverByIdentityKeyArgs

export interface DiscoverByIdentityKeyArgs {
    identityKey: PubKeyHex;
    limit?: PositiveIntegerDefault10Max10000;
    offset?: PositiveIntegerOrZero;
    seekPermission?: BooleanDefaultTrue;
}

See also: BooleanDefaultTrue, PositiveIntegerDefault10Max10000, PositiveIntegerOrZero, PubKeyHex

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

Interface: DiscoverCertificatesResult

export interface DiscoverCertificatesResult {
    totalCertificates: PositiveIntegerOrZero;
    certificates: IdentityCertificate[];
}

See also: IdentityCertificate, PositiveIntegerOrZero

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

export interface GetHeaderArgs {
    height: PositiveInteger;
}

See also: PositiveInteger

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

Interface: GetHeaderResult

export interface GetHeaderResult {
    header: HexString;
}

See also: HexString

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

Interface: GetHeightResult

export interface GetHeightResult {
    height: PositiveInteger;
}

See also: PositiveInteger

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

export interface GetNetworkResult {
    network: WalletNetwork;
}

See also: WalletNetwork

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

Interface: GetPublicKeyArgs

When identityKey is true, WalletEncryptionArgs are not used.

When identityKey is undefined, WalletEncryptionArgs are required.

export interface GetPublicKeyArgs extends Partial<WalletEncryptionArgs> {
    identityKey?: true;
    forSelf?: BooleanDefaultFalse;
}

See also: BooleanDefaultFalse, WalletEncryptionArgs

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

Interface: GetPublicKeyResult

export interface GetPublicKeyResult {
    publicKey: PubKeyHex;
}

See also: PubKeyHex

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

export interface GetVersionResult {
    version: VersionString7To30Bytes;
}

See also: VersionString7To30Bytes

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

Interface: IdentityCertificate

export interface IdentityCertificate extends WalletCertificate {
    certifierInfo: IdentityCertifier;
    publiclyRevealedKeyring: Record<CertificateFieldNameUnder50Bytes, Base64String>;
    decryptedFields: Record<CertificateFieldNameUnder50Bytes, string>;
}

See also: Base64String, CertificateFieldNameUnder50Bytes, IdentityCertifier, WalletCertificate

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

Interface: IdentityCertifier

export interface IdentityCertifier {
    name: EntityNameStringMax100Bytes;
    iconUrl: EntityIconURLStringMax500Bytes;
    description: DescriptionString5to50Bytes;
    trust: PositiveIntegerMax10;
}

See also: DescriptionString5to50Bytes, EntityIconURLStringMax500Bytes, EntityNameStringMax100Bytes, PositiveIntegerMax10

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

Interface: InternalizeActionArgs

export interface InternalizeActionArgs {
    tx: AtomicBEEF;
    outputs: InternalizeOutput[];
    description: DescriptionString5to50Bytes;
    labels?: LabelStringUnder300Bytes[];
    seekPermission?: BooleanDefaultTrue;
}

See also: AtomicBEEF, BooleanDefaultTrue, DescriptionString5to50Bytes, InternalizeOutput, LabelStringUnder300Bytes

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

Interface: InternalizeActionResult

export interface InternalizeActionResult {
    accepted: true;
}

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

Interface: InternalizeOutput

export interface InternalizeOutput {
    outputIndex: PositiveIntegerOrZero;
    protocol: "wallet payment" | "basket insertion";
    paymentRemittance?: WalletPayment;
    insertionRemittance?: BasketInsertion;
}

See also: BasketInsertion, PositiveIntegerOrZero, WalletPayment

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

Interface: KeyDeriverApi

export interface KeyDeriverApi {
    rootKey: PrivateKey;
    identityKey: string;
    derivePublicKey(protocolID: WalletProtocol, keyID: string, counterparty: Counterparty, forSelf?: boolean): PublicKey;
    derivePrivateKey(protocolID: WalletProtocol, keyID: string, counterparty: Counterparty): PrivateKey;
    deriveSymmetricKey(protocolID: WalletProtocol, keyID: string, counterparty: Counterparty): SymmetricKey;
    revealCounterpartySecret(counterparty: Counterparty): number[];
    revealSpecificSecret(counterparty: Counterparty, protocolID: WalletProtocol, keyID: string): number[];
}

See also: Counterparty, WalletProtocol

Property identityKey

The identity of this key deriver which is normally the public key associated with the rootKey

identityKey: string

Property rootKey

The root key from which all other keys are derived.

rootKey: PrivateKey

Method derivePrivateKey

Derives a private key based on protocol ID, key ID, and counterparty.

derivePrivateKey(protocolID: WalletProtocol, keyID: string, counterparty: Counterparty): PrivateKey

See also: Counterparty, WalletProtocol

Returns

• The derived private key.

Argument Details

• protocolID
  • The protocol ID including a security level and protocol name.
• keyID
  • The key identifier.
• counterparty
  • The counterparty's public key or a predefined value ('self' or 'anyone').

Method derivePublicKey

Derives a public key based on protocol ID, key ID, and counterparty.

derivePublicKey(protocolID: WalletProtocol, keyID: string, counterparty: Counterparty, forSelf?: boolean): PublicKey

See also: Counterparty, WalletProtocol

Returns

• The derived public key.

Argument Details

• protocolID
  • The protocol ID including a security level and protocol name.
• keyID
  • The key identifier.
• counterparty
  • The counterparty's public key or a predefined value ('self' or 'anyone').
• forSelf
  • Optional. false if undefined. Whether deriving for self.

Method deriveSymmetricKey

Derives a symmetric key based on protocol ID, key ID, and counterparty. Note: Symmetric keys should not be derivable by everyone due to security risks.

deriveSymmetricKey(protocolID: WalletProtocol, keyID: string, counterparty: Counterparty): SymmetricKey

See also: Counterparty, WalletProtocol

Returns

• The derived symmetric key.

Argument Details

• protocolID
  • The protocol ID including a security level and protocol name.
• keyID
  • The key identifier.
• counterparty
  • The counterparty's public key or a predefined value ('self' or 'anyone').

Throws

• Throws an error if attempting to derive a symmetric key for 'anyone'.

Method revealCounterpartySecret

Reveals the shared secret between the root key and the counterparty. Note: This should not be used for 'self'.

revealCounterpartySecret(counterparty: Counterparty): number[]

See also: Counterparty

Returns

• The shared secret as a number array.

Argument Details

• counterparty
  • The counterparty's public key or a predefined value ('self' or 'anyone').

Throws

• Throws an error if attempting to reveal a shared secret for 'self'.

Method revealSpecificSecret

Reveals the specific key association for a given protocol ID, key ID, and counterparty.

revealSpecificSecret(counterparty: Counterparty, protocolID: WalletProtocol, keyID: string): number[]

See also: Counterparty, WalletProtocol

Returns

• The specific key association as a number array.

Argument Details

• counterparty
  • The counterparty's public key or a predefined value ('self' or 'anyone').
• protocolID
  • The protocol ID including a security level and protocol name.
• keyID
  • The key identifier.

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

Interface: KeyLinkageResult

export interface KeyLinkageResult {
    encryptedLinkage: Byte[];
    encryptedLinkageProof: Byte[];
    prover: PubKeyHex;
    verifier: PubKeyHex;
    counterparty: PubKeyHex;
}

See also: Byte, PubKeyHex

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

Interface: ListActionsArgs

export interface ListActionsArgs {
    labels: LabelStringUnder300Bytes[];
    labelQueryMode?: "any" | "all";
    includeLabels?: BooleanDefaultFalse;
    includeInputs?: BooleanDefaultFalse;
    includeInputSourceLockingScripts?: BooleanDefaultFalse;
    includeInputUnlockingScripts?: BooleanDefaultFalse;
    includeOutputs?: BooleanDefaultFalse;
    includeOutputLockingScripts?: BooleanDefaultFalse;
    limit?: PositiveIntegerDefault10Max10000;
    offset?: PositiveIntegerOrZero;
    seekPermission?: BooleanDefaultTrue;
}

See also: BooleanDefaultFalse, BooleanDefaultTrue, LabelStringUnder300Bytes, PositiveIntegerDefault10Max10000, PositiveIntegerOrZero

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

export interface ListActionsResult {
    totalActions: PositiveIntegerOrZero;
    actions: WalletAction[];
}

See also: PositiveIntegerOrZero, WalletAction

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?: stri