@babbage/sdk-ts
Advanced tools
Readme
Build Babbage apps in TypeScript
npm i @babbage/sdk
There are a few example projects you can check out which implement the Babbage SDK:
📒 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.
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'
})
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? 🏆
Links: API, Interfaces, Classes, Functions, Types, Variables
Links: API, Interfaces, Classes, Functions, Types, Variables
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;
}
The most efficient way of confirming a proof should also be the most common, when the containing block's height is known.
height?: number
Index of transaction in its block. First transaction is index zero.
index: number
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
Merkle root (length === 32) or serialized block header containing it (length === 80). If string, encoding is hex.
target: string | Buffer
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
export interface MapiResponseApi {
payload: string;
signature: string;
publicKey: string;
encoding?: string;
mimetype?: string;
}
encoding of the payload data
encoding?: string
mime type of the payload data
mimetype?: string
Contents of the envelope. Validate using signature and publicKey. encoding and mimetype may assist with decoding validated payload.
payload: string
public key to use to verify signature of payload data
publicKey: string
signature producted by correpsonding private key on payload data
signature: string
Links: API, Interfaces, Classes, Functions, Types, Variables
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;
}
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[]
Arbitrary reference string associated with the envelope, typically root node only.
reference?: string
Links: API, Interfaces, Classes, Functions, Types, Variables
Either inputs or proof are required.
export interface EnvelopeEvidenceApi {
rawTx: string;
proof?: TscMerkleProofApi | Buffer;
inputs?: Record<string, EnvelopeEvidenceApi>;
txid?: string;
mapiResponses?: MapiResponseApi[];
depth?: number;
}
count of maximum number of chained unproven transactions before a proven leaf node proof nodes have depth zero.
depth?: number
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>
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[]
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
A valid bitcoin transaction encoded as a hex string.
rawTx: string
double SHA256 hash of serialized rawTx. Optional.
txid?: string
Links: API, Interfaces, Classes, Functions, Types, Variables
export interface CertificateApi {
type: string;
subject: string;
validationKey: string;
serialNumber: string;
certifier: string;
revocationOutpoint: string;
signature: string;
fields?: Record<string, string>;
}
max length of 255
certifier: string
Certificate fields object where keys are field names and values are field value.
fields?: Record<string, string>
max length of 255
revocationOutpoint: string
max length of 255
serialNumber: string
max length of 255
signature: string
max length of 255
subject: string
max length of 255
type: string
max length of 255
validationKey: string
Links: API, Interfaces, Classes, Functions, Types, Variables
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>;
}
max length of 255
certifier: string
Certificate fields object where keys are field names and values are field value.
fields?: Record<string, string>
Certificate masterKeyring object where keys are field names and values are field masterKey value.
masterKeyring?: Record<string, string>
max length of 255
revocationOutpoint: string
max length of 255
serialNumber: string
max length of 255
signature: string
max length of 255
subject: string
max length of 255
type: string
max length of 255
validationKey: string
Links: API, Interfaces, Classes, Functions, Types, Variables
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>;
}
max length of 255
certifier: string
Plaintext field names and values of only those fields requested in fieldsToReveal
fields?: Record<string, string>
field revelation keyring for the given verifier
keyring: Record<string, string>
max length of 255
revocationOutpoint: string
max length of 255
serialNumber: string
max length of 255
signature: string
max length of 255
subject: string
max length of 255
type: string
max length of 255
validationKey: string
Links: API, Interfaces, Classes, Functions, Types, Variables
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[];
}
The number of satoshis added or removed from Dojo by this transaction
amount: number
The time the transaction was registered with the Dojo
created_at: string
Whether or not the transaction was created with createTransaction
isOutgoing: boolean
A set of all the labels affixed to the transaction
labels: string[]
The human-readable tag for the transaction, provided by the person who initiated it
note: string
The Paymail handle of the person who received the transaction
recipientPaymail: string
The Dojo reference number for the transaction
referenceNumber: string
The Paymail handle of the person who sent the transaction
senderPaymail: string
The current state of the transaction. Common statuses are completed and unproven.
status: TransactionStatusApi
The transaction ID
txid: string
Links: API, Interfaces, Classes, Functions, Types, Variables
export interface ListActionsTransactionInput {
txid: string;
vout: number;
amount: number;
outputScript: string;
type: string;
spendable: boolean;
spendingDescription?: string;
basket?: string;
tags?: string[];
}
Number of satoshis in the output
amount: number
Optionally included basket assignment.
basket?: string
Hex representation of output locking script
outputScript: string
Whether this output is free to be spent
spendable: boolean
Spending description for this transaction input
spendingDescription?: string
Optionally included tag assignments.
tags?: string[]
Transaction ID of transaction that created the output
txid: string
The type of output, for example "P2PKH" or "P2RPH"
type: string
Index in the transaction of the output
vout: number
Links: API, Interfaces, Classes, Functions, Types, Variables
export interface ListActionsTransactionOutput {
txid: string;
vout: number;
amount: number;
outputScript: string;
type: string;
spendable: boolean;
description?: string;
basket?: string;
tags?: string[];
}
Number of satoshis in the output
amount: number
Optionally included basket assignment.
basket?: string
Output description
description?: string
Hex representation of output locking script
outputScript: string
Whether this output is free to be spent
spendable: boolean
Optionally included tag assignments.
tags?: string[]
Transaction ID of transaction that created the output
txid: string
The type of output, for example "P2PKH" or "P2RPH"
type: string
Index in the transaction of the output
vout: number
Links: API, Interfaces, Classes, Functions, Types, Variables
export interface ListActionsResult {
totalTransactions: number;
transactions: ListActionsTransaction[];
}
The number of transactions in the complete set
totalTransactions: number
The specific transactions from the set that were requested, based on limit and offset
transactions: ListActionsTransaction[]
Links: API, Interfaces, Classes, Functions, Types, Variables
export interface CounterpartyKeyLinkageResult {
type: "counterparty-revelation";
prover: string;
verifier: string;
counterparty: string;
revelationTime: string;
encryptedLinkage: string;
}
ISO date string
revelationTime: string
Links: API, Interfaces, Classes, Functions, Types, Variables
export interface SpecificKeyLinkageResult {
type: "specific-revelation";
prover: string;
verifier: string;
counterparty: string;
protocolID: ProtocolID;
encryptedLinkage: string;
}
Links: API, Interfaces, Classes, Functions, Types, Variables
export interface CreateActionOutputToRedeem {
index: number;
unlockingScript: string | number;
spendingDescription?: string;
sequenceNumber?: number;
}
Zero based output index within its transaction to spend.
index: number
Sequence number to use when spending
sequenceNumber?: number
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
export interface CreateActionInput extends EnvelopeEvidenceApi {
outputsToRedeem: CreateActionOutputToRedeem[];
}
Links: API, Interfaces, Classes, Functions, Types, Variables
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[];
}
Destination output basket name for the new UTXO
basket?: string
Custom spending instructions (metadata, string, optional)
customInstructions?: string
Human-readable output line-item description
description?: string
The amount of the output in satoshis
satoshis: number
The output script that will be included, hex encoded
script: string
Optional array of output tags to assign to this output.
tags?: string[]
Links: API, Interfaces, Classes, Functions, Types, Variables
export interface SignActionResult {
rawTx: string;
inputs: Record<string, EnvelopeEvidenceApi>;
mapiResponses: MapiResponseApi[];
txid: string;
log?: string;
}
Links: API, Interfaces, Classes, Functions, Types, Variables
export interface AbortActionResult {
referenceNumber: string;
log?: string;
}
Links: API, Interfaces, Classes, Functions, Types, Variables
export interface DojoOutputToRedeemApi {
index: number;
unlockingScriptLength: number;
spendingDescription?: string;
}
Zero based output index within its transaction to spend.
index: number
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
export interface DojoCreatingTxInstructionsApi {
type: string;
derivationPrefix?: string;
derivationSuffix?: string;
senderIdentityKey?: string;
paymailHandle?: string;
}
Links: API, Interfaces, Classes, Functions, Types, Variables
export interface DojoCreatingTxInputsApi extends EnvelopeEvidenceApi {
outputsToRedeem: DojoOutputToRedeemApi[];
providedBy: DojoProvidedByApi;
instructions: Record<number, DojoCreatingTxInstructionsApi>;
}
Links: API, Interfaces, Classes, Functions, Types, Variables
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[];
}
Destination output basket name for the new UTXO
basket?: string
Custom spending instructions (metadata, string, optional)
customInstructions?: string
Human-readable output line-item description
description?: string
The amount of the output in satoshis
satoshis: number
The output script that will be included, hex encoded
script: string
Optional array of output tags to assign to this output.
tags?: string[]
Links: API, Interfaces, Classes, Functions, Types, Variables
export interface DojoCreatingTxOutputApi extends DojoCreateTxOutputApi {
providedBy: DojoProvidedByApi;
purpose?: string;
destinationBasket?: string;
derivationSuffix?: string;
keyOffset?: string;
}
Links: API, Interfaces, Classes, Functions, Types, Variables
export interface DojoCreateTransactionResultApi {
inputs: Record<string, DojoCreatingTxInputsApi>;
outputs: DojoCreatingTxOutputApi[];
derivationPrefix: string;
version: number;
lockTime: number;
referenceNumber: string;
paymailHandle: string;
note?: string;
log?: string;
}
Links: API, Interfaces, Classes, Functions, Types, Variables
export interface CreateActionResult {
signActionRequired?: boolean;
createResult?: DojoCreateTransactionResultApi;
rawTx?: string;
inputs: Record<string, EnvelopeEvidenceApi>;
mapiResponses?: MapiResponseApi[];
txid?: string;
log?: string;
}
Links: API, Interfaces, Classes, Functions, Types, Variables
export interface GetTransactionOutputResult {
txid: string;
vout: number;
amount: number;
outputScript: string;
type: string;
spendable: boolean;
envelope?: EnvelopeApi;
customInstructions?: string;
basket?: string;
tags?: string[];
}
Number of satoshis in the output
amount: number
If includeBasket option is true, name of basket to which this output belongs.
basket?: string
When envelope requested, any custom instructions associated with this output.
customInstructions?: string
When requested and available, output validity support envelope.
envelope?: EnvelopeApi
Hex representation of output locking script
outputScript: string
Whether this output is free to be spent
spendable: boolean
If includeTags option is true, tags assigned to this output.
tags?: string[]
Transaction ID of transaction that created the output
txid: string
The type of output, for example "P2PKH" or "P2RPH"
type: string
Index in the transaction of the output
vout: number
Links: API, Interfaces, Classes, Functions, Types, Variables
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
export interface SubmitDirectTransaction {
rawTx: string;
txid?: string;
inputs?: Record<string, EnvelopeEvidenceApi>;
mapiResponses?: MapiResponseApi[];
proof?: TscMerkleProofApi;
outputs: SubmitDirectTransactionOutput[];
referenceNumber?: string;
}
Links: API, Interfaces, Classes, Functions, Types, Variables
export interface SubmitDirectTransactionResult {
transactionId: number;
referenceNumber: string;
}
Links: API, Interfaces, Classes, Functions, Types, Variables
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
Links: API, Interfaces, Classes, Functions, Types, Variables
export default async function makeHttpRequest<R>(routeURL: string, requestInput: RequestInit = {}): Promise<R>
Links: API, Interfaces, Classes, Functions, Types, Variables
Provides a timedout promise.
export default async function promiseWithTimeout<T>(obj: {
timeout: number;
promise: Promise<T>;
error?: Error;
}): Promise<T>
Argument Details
Links: API, Interfaces, Classes, Functions, Types, Variables
export default function getRandomID(): string
Links: API, Interfaces, Classes, Functions, Types, Variables
export default async function connectToSubstrate(): Promise<Communicator>
Links: API, Interfaces, Classes, Functions, Types, Variables
If a log is being kept, add a time stamped line.
export function stampLog(log: string | undefined, lineToAdd: string): string | undefined
Returns
undefined or log extended by time stamped lineToAdd and new line.
Argument Details
Links: API, Interfaces, Classes, Functions, Types, Variables
Replaces individual timestamps with delta msecs.
Looks for two network crossings and adjusts clock for clock skew if found.
Assumes log built by repeated calls to stampLog
export function stampLogFormat(log?: string): string
Returns
reformated multi-line event log
Argument Details
\n.Links: API, Interfaces, Classes, Functions, Types, Variables
Aborts a previously created action which required custom input unlocking script signing.
export async function abortAction(args: {
referenceNumber: string;
log?: string;
}): Promise<AbortActionResult>
Returns
An Action object containing "txid", "rawTx" "mapiResponses" and "inputs".
Argument Details
Links: API, Interfaces, Classes, Functions, Types, Variables
Creates and broadcasts a BitCoin transaction with the provided inputs and outputs.
export async function createAction(args: {
inputs?: Record<string, CreateActionInput>;
outputs?: CreateActionOutput[];
lockTime?: number;
version?: number;
description: string;
labels?: string[];
acceptDelayedBroadcast?: boolean;
log?: string;
}): Promise<CreateActionResult>
Returns
An Action object containing "txid", "rawTx" "mapiResponses" and "inputs".
Argument Details
Links: API, Interfaces, Classes, Functions, Types, Variables
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>
Returns
The SHA-256 HMAC of the data.
Argument Details
Links: API, Interfaces, Classes, Functions, Types, Variables
Creates a signed certificate
export async function createCertificate(args: {
certificateType: string;
fieldObject: Record<string, string>;
certifierUrl: string;
certifierPublicKey: string;
}): Promise<CreateCertificateResult>
Returns
A signed certificate
Argument Details
Links: API, Interfaces, Classes, Functions, Types, Variables
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>
Returns
The ECDSA message signature.
Argument Details
Links: API, Interfaces, Classes, Functions, Types, Variables
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>
Returns
The decrypted plaintext.
Argument Details
Links: API, Interfaces, Classes, Functions, Types, Variables
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>
Returns
The decrypted plaintext TextDecoder decoded to string.
Argument Details
Links: API, Interfaces, Classes, Functions, Types, Variables
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>
Returns
The decrypted plaintext.
Argument Details
Links: API, Interfaces, Classes, Functions, Types, Variables
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
Links: API, Interfaces, Classes, Functions, Types, Variables
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
Links: API, Interfaces, Classes, Functions, Types, Variables
Returns the user's preferred currency for displaying within apps
export async function getPreferredCurrency(args: {
description?: string;
}): Promise<string>
Returns
The user's preferred currency
Argument Details
Links: API, Interfaces, Classes, Functions, Types, Variables
Encrypts data with a key belonging to the user. If a counterparty is provided, also allows the counterparty to decrypt the data. The same protocolID, keyID, counterparty and privileged parameters must be used when decrypting.
export async function encrypt(args: {
plaintext: string | Uint8Array;
protocolID: ProtocolID;
keyID: string;
description?: string;
counterparty?: string;
privileged?: boolean;
returnType?: "Uint8Array" | "string";
}): Promise<string | Uint8Array>
Returns
The encrypted ciphertext.
Argument Details
Links: API, Interfaces, Classes, Functions, Types, Variables
Encrypts data with a key belonging to the user. If a counterparty is provided, also allows the counterparty to decrypt the data. The same protocolID, keyID, counterparty and privileged parameters must be used when decrypting.
export async function encryptAsString(args: {
plaintext: string | Uint8Array;
protocolID: string;
keyID: string;
description?: string;
counterparty?: string;
privileged?: boolean;
}): Promise<string>
Returns
The encrypted ciphertext data as base64 encoded string.
Argument Details
Links: API, Interfaces, Classes, Functions, Types, Variables
Encrypts data with a key belonging to the user. If a counterparty is provided, also allows the counterparty to decrypt the data. The same protocolID, keyID, counterparty and privileged parameters must be used when decrypting.
export async function encryptAsArray(args: {
plaintext: string | Uint8Array;
protocolID: string;
keyID: string;
description?: string;
counterparty?: string;
privileged?: boolean;
}): Promise<Uint8Array>
Returns
The encrypted ciphertext data.
Argument Details
Links: API, Interfaces, Classes, Functions, Types, Variables
Returns found certificates
export async function getCertificates(args: {
certifiers: string[];
types: Record<string, string[]>;
}): Promise<CreateCertificateResult[]>
Returns
An object containing the found certificates
Argument Details
Links: API, Interfaces, Classes, Functions, Types, Variables
Returns the current chain height of the network
export async function getHeight(): Promise<number>
Returns
The current chain height
Links: API, Interfaces, Classes, Functions, Types, Variables
A method to verify the validity of a Merkle root for a given block height.
export async function getMerkleRootForHeight(height: number): Promise<string | undefined>
Returns
Returns the merkle root for height or undefined, if height doesn't have a known merkle root or is invalid.
Links: API, Interfaces, Classes, Functions, Types, Variables
Returns which BSV network we are using (mainnet or testnet)
export async function getNetwork(format?: "default" | "nonet"): Promise<string>
Returns
The current BSV network formatted as requested.
Argument Details
Links: API, Interfaces, Classes, Functions, Types, Variables
Returns the public key. If identityKey is specified, returns the current user's identity key. If a counterparty is specified, derives a public key for the counterparty.
export async function getPublicKey(args: {
protocolID?: ProtocolID;
keyID?: string;
privileged?: boolean;
identityKey?: boolean;
reason?: string;
counterparty?: string;
forSelf?: boolean;
}): Promise<string>
Returns
The user's public key
Argument Details
Links: API, Interfaces, Classes, Functions, Types, Variables
Returns a set of transaction outputs that Dojo has tracked
export async function getTransactionOutputs(args: {
basket?: string;
tracked?: boolean;
spendable?: boolean;
tags?: string[];
type?: string;
includeEnvelope?: boolean;
includeBasket?: boolean;
includeCustomInstructions?: boolean;
includeTags?: boolean;
tagQueryMode?: "all" | "any";
limit?: number;
offset?: number;
}): Promise<GetTransactionOutputResult[]>
Returns
A set of outputs that match the criteria
Argument Details
Links: API, Interfaces, Classes, Functions, Types, Variables
Returns the current version of the kernal
export async function getVersion(): Promise<string>
Returns
The current kernel version (e.g. "0.3.49")
Links: API, Interfaces, Classes, Functions, Types, Variables
Checks if a user is currently authenticated.
export async function isAuthenticated(): Promise<boolean>
Returns
Returns whether a user is currently authenticated.
Links: API, Interfaces, Classes, Functions, Types, Variables
Returns a list of Actions with a given label
export async function listActions(args: {
label: string;
addInputsAndOutputs?: boolean;
includeBasket?: boolean;
includeTags?: boolean;
noRawTx?: boolean;
limit?: number;
offset?: number;
}): Promise<ListActionsResult>
Returns
A set of outputs that match the criteria
Argument Details
Links: API, Interfaces, Classes, Functions, Types, Variables
Creates certificate proof specifically for verifier
export async function proveCertificate(args: {
certificate: CertificateApi;
fieldsToReveal: string[];
verifierPublicIdentityKey: string;
}): Promise<ProveCertificateResult>
Returns
A certificate for presentation to the verifier for field examination
Argument Details
Links: API, Interfaces, Classes, Functions, Types, Variables
Requests group permissions for an application.
export async function requestGroupPermission(): Promise<void>
Returns
Resolves after group permissions are completed by the user.
Links: API, Interfaces, Classes, Functions, Types, Variables
Reveals the linkage between a key held by this user and a key held by another user. In one mode, reveals all keys associated with a counterparty, in the other mode reveals only the linkage of a specific interaction.
Encrypts the linkage value so that only the specified verifier can access it. Refer to BRC-72 for full details.
export async function revealKeyLinkage(args: {
mode: "counterparty" | "specific";
counterparty: string;
verifier: string;
protocolID: ProtocolID;
keyID: string;
description: string;
privileged?: boolean;
}): Promise<CounterpartyKeyLinkageResult | SpecificKeyLinkageResult>
Returns
The revealed linkage payload, as described in BRC-72.
Argument Details
Links: API, Interfaces, Classes, Functions, Types, Variables
Reveals the linkage between a key held by this user and a key held by another user. Reveals all keys associated with a counterparty,
Encrypts the linkage value so that only the specified verifier can access it. Refer to BRC-72 for full details.
export async function revealKeyLinkageCounterparty(args: {
counterparty: string;
verifier: string;
protocolID: ProtocolID;
description: string;
privileged?: boolean;
}): Promise<CounterpartyKeyLinkageResult>
Returns
The revealed linkage payload, as described in BRC-72.
Argument Details
Links: API, Interfaces, Classes, Functions, Types, Variables
Reveals the linkage between a key held by this user and a key held by another user. Reveals only the linkage of a specific interaction.
Encrypts the linkage value so that only the specified verifier can access it. Refer to BRC-72 for full details.
export async function revealKeyLinkageSpecific(args: {
counterparty: string;
verifier: string;
protocolID: ProtocolID;
keyID: string;
description: string;
privileged?: boolean;
}): Promise<SpecificKeyLinkageResult>
Returns
The revealed linkage payload, as described in BRC-72.
Argument Details
Links: API, Interfaces, Classes, Functions, Types, Variables
Completes a previously created action which required custom input unlocking script signing.
export async function signAction(args: {
inputs?: Record<string, CreateActionInput>;
createResult: DojoCreateTransactionResultApi;
acceptDelayedBroadcast?: boolean;
log?: string;
}): Promise<SignActionResult>
Returns
An Action object containing "txid", "rawTx" "mapiResponses" and "inputs".
Argument Details
Links: API, Interfaces, Classes, Functions, Types, Variables
Submits a transaction directly to a ninja
export async function submitDirectTransaction(args: {
protocol?: string;
transaction: SubmitDirectTransaction;
senderIdentityKey: string;
note: string;
amount: number;
labels?: string[];
derivationPrefix?: string;
}): Promise<SubmitDirectTransactionResult>
Returns
Object containing reference number, status=success, and human-readable note acknowledging the transaction
Argument Details
Links: API, Interfaces, Classes, Functions, Types, Variables
Removes the uniquely identified output's basket assignment.
The output will no longer belong to any basket.
This is typically only useful for outputs that are no longer usefull.
export async function unbasketOutput(args: {
txid: string;
vout: number;
basket: string;
}): Promise<void>
Argument Details
Links: API, Interfaces, Classes, Functions, Types, Variables
Verifies that a SHA-256 HMAC was created with a key that belongs to the user.
export async function verifyHmac(args: {
data: Uint8Array | string;
hmac: Uint8Array | string;
protocolID: ProtocolID;
keyID: string;
description?: string;
counterparty?: string;
privileged?: boolean;
}): Promise<boolean>
Returns
Whether the HMAC has been erified.
Argument Details
Links: API, Interfaces, Classes, Functions, Types, Variables
Verifies that a digital signature was created with a key belonging to the user.
export async function verifySignature(args: {
data: Uint8Array | string;
signature: Uint8Array | string;
protocolID: ProtocolID;
keyID: string;
description?: string;
counterparty?: string;
privileged?: boolean;
reason?: string;
}): Promise<boolean>
Returns
An whether the signature was successfully verified.
Argument Details
Links: API, Interfaces, Classes, Functions, Types, Variables
Waits for a user to be authenticated.
export async function waitForAuthentication(): Promise<boolean>
Returns
Always returns true
Links: API, Interfaces, Classes, Functions, Types, Variables
Constructs a
export async function buildTransactionForSignActionUnlocking(ninjaInputs: Record<string, CreateActionInput>, createResult: DojoCreateTransactionResultApi): Promise<Transaction>
Argument Details
Links: API, Interfaces, Classes, Functions, Types, Variables
| DojoProvidedByApi |
| ProtocolID |
| TransactionStatusApi |
Links: API, Interfaces, Classes, Functions, Types, Variables
export type ProtocolID = string | [
0 | 1 | 2,
string
]
Links: API, Interfaces, Classes, Functions, Types, Variables
export type TransactionStatusApi = "completed" | "failed" | "unprocessed" | "sending" | "unproven" | "unsigned"
Links: API, Interfaces, Classes, Functions, Types, Variables
export type DojoProvidedByApi = "you" | "dojo" | "you-and-dojo"
Links: API, Interfaces, Classes, Functions, Types, Variables
BabbageSDK = {
abortAction,
createAction,
createHmac,
createCertificate,
createSignature,
decrypt,
decryptAsArray,
decryptAsString,
discoverByAttributes,
discoverByIdentityKey,
getPreferredCurrency,
encrypt,
encryptAsArray,
encryptAsString,
getCertificates,
getHeight,
getMerkleRootForHeight,
getNetwork,
getPublicKey,
getTransactionOutputs,
getVersion,
isAuthenticated,
listActions,
proveCertificate,
requestGroupPermission,
revealKeyLinkage,
revealKeyLinkageCounterparty,
revealKeyLinkageSpecific,
signAction,
submitDirectTransaction,
unbasketOutput,
verifyHmac,
verifySignature,
waitForAuthentication,
}
Links: API, Interfaces, Classes, Functions, Types, Variables
The Babbage SDK connects to a running Computing with Integrity (CWI) kernel instance, allowing applications to plug into user-owned identities. There are currently three substrates (connection modes) that the SDK can use to link an application to a MetaNet identity provider:
window.CWI interface for communicating with the kernel.localhost:3301 to a running HTTP MetaNet service. This Port 3301 Substrate is named Cicada, in honor of Cicada 3301.The license for this library, which is a wrapper for the proprietary Babbage API, is the Open BSV License. It can only be used on the BSV blockchain. The Babbage API itself, including the rights to create and host Babbage software or any other related infrastructure, is not covered by the Open BSV License and remains proprietary and restricted. The Open BSV License only extends to the code in this repository, and you are not permitted to host Babbage software, servers or create copies or alternative implementations of the proprietary Babbage API without other permission.
FAQs
Build Babbage Apps with TypeScript
The npm package @babbage/sdk-ts receives a total of 14 weekly downloads. As such, @babbage/sdk-ts popularity was classified as not popular.
We found that @babbage/sdk-ts demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 3 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
A new report explores how advancements in LLMs are enhancing cyber threats, including polymorphic malware, personalized spearphishing, and the risk of hijacking customer service bots.
Security News
ESLint has approved an RFC that adds support for TypeScript configuration files, which is aimed at improving the developer experience and recognizing changes in the evolving JavaScript ecosystem.
Security News
The NVD is facing a significant backlog with over 12,500 CVEs awaiting analysis, and more than 50% of known exploited vulnerabilities (KEVs) left unenriched since mid-February.