@bsv/sdk
Version:
BSV Blockchain Software Development Kit
950 lines • 59.3 kB
TypeScript
/**
* @typedef {boolean} BooleanDefaultFalse
* Represents an optional boolean parameter, which defaults to `false` if not provided.
*/
export type BooleanDefaultFalse = boolean;
/**
* @typedef {boolean} BooleanDefaultTrue
* Represents an optional boolean parameter, which defaults to `true` if not provided.
*/
export type BooleanDefaultTrue = boolean;
/**
* @typedef {number} Byte
* Represents an integer from 0 to 255 (inclusive).
* @minimum 0
* @maximum 255
*/
export type Byte = number;
/**
* @typedef {number} PositiveIntegerOrZero
* A positive integer, includes zero and has an upper bound of `2^32 - 1`.
* @minimum 0
* @maximum 4294967295
*/
export type PositiveIntegerOrZero = number;
/**
* @typedef {number} PositiveInteger
* A positive integer that excludes zero, and has an upper bound of `2^32 - 1`.
* @minimum 1
* @maximum 4294967295
*/
export type PositiveInteger = number;
/**
* @typedef {number} PositiveIntegerMax10
* A positive integer that excludes zero, and has an upper bound of 10.
* @minimum 1
* @maximum 10
*/
export type PositiveIntegerMax10 = number;
/**
* @typedef {number} PositiveIntegerDefault10Max10000
* A positive integer that defaults to 10, and has an upper bound of 10000.
* @minimum 1
* @default 10
* @maximum 10000
*/
export type PositiveIntegerDefault10Max10000 = number;
/**
* @typedef {number} SatoshiValue
* Represents a value in Satoshis, constrained by the max supply of Bitcoin (2.1 * 10^15 Satoshis).
* @minimum 1
* @maximum 2100000000000000
*/
export type SatoshiValue = number;
/**
* @typedef {string} ISOTimestampString
* Represents an ISO timestamp string.
*/
export type ISOTimestampString = string;
/**
* @typedef {string} HexString
* A string containing only hexadecimal characters (0-9, a-f).
*/
export type HexString = string;
/**
* @typedef {HexString} TXIDHexString
* Represents a transaction ID, enforced to be exactly 64 characters in length and in hexadecimal format.
* @length 64
*/
export type TXIDHexString = HexString;
/**
* @typedef {string} OutpointString
* Represents a transaction ID and output index pair. The TXID is given as a hex string followed by a period "." and then the output index is given as a decimal integer.
*/
export type OutpointString = string;
/**
* @typedef {HexString} PubKeyHex
* Represents a compressed DER secp256k1 public key, exactly 66 hex characters (33 bytes) in length.
* @length 66
*/
export type PubKeyHex = HexString;
/**
* @typedef {string} Base64String
* A standard base64 encoded string.
*/
export type Base64String = string;
/**
* @typedef {string} OriginatorDomainNameStringUnder250Bytes
* Represents the fully qualified domain name (FQDN) of the application that originates the request.
*/
export type OriginatorDomainNameStringUnder250Bytes = string;
/**
* @typedef {string & { minLength: 5, maxLength: 50 }} DescriptionString5to50Bytes
* A string used for descriptions, with a length between 5 and 50 characters.
*/
export type DescriptionString5to50Bytes = string;
/**
* @typedef {string & { maxLength: 300 }} BasketStringUnder300Bytes
* A string for naming baskets, with a maximum length of 300 characters.
*/
export type BasketStringUnder300Bytes = string;
/**
* @typedef {string & { maxLength: 300 }} OutputTagStringUnder300Bytes
* A string for tagging outputs, with a maximum length of 300 characters.
*/
export type OutputTagStringUnder300Bytes = string;
/**
* @typedef {string & { maxLength: 300 }} LabelStringUnder300Bytes
* A string for labeling transactions, with a maximum length of 300 characters.
*/
export type LabelStringUnder300Bytes = string;
/**
* @typedef {Byte[]} BEEF
* An array of integers, each ranging from 0 to 255, indicating transaction data in BEEF (BRC-62) format.
*/
export type BEEF = Byte[];
/**
* @typedef {Byte[]} AtomicBEEF
* An array of integers, each ranging from 0 to 255, indicating transaction data in Atomic BEEF (BRC-95) format.
*/
export type AtomicBEEF = Byte[];
/**
* @typedef {string & { minLength: 5, maxLength: 400 }} ProtocolString5To400Bytes
* A protocol identifier with a length between 5 and 400 characters.
*/
export type ProtocolString5To400Bytes = string;
/**
* @typedef {string & { maxLength: 800 }} KeyIDStringUnder800Bytes
* Represents a key identifier string, with a maximum length of 800 characters.
*/
export type KeyIDStringUnder800Bytes = string;
/**
* @typedef {string & { maxLength: 50 }} CertificateFieldNameUnder50Bytes
* Represents a certificate field name with a maximum length of 50 characters.
*/
export type CertificateFieldNameUnder50Bytes = string;
/**
* @typedef {string & { maxLength: 100 }} EntityNameStringMax100Bytes
* Represents a trusted entity name with a maximum length of 100 characters.
*/
export type EntityNameStringMax100Bytes = string;
/**
* @typedef {string & { maxLength: 500 }} EntityIconURLStringMax500Bytes
* Represents a trusted entity icon URL with a maximum length of 500 characters.
*/
export type EntityIconURLStringMax500Bytes = string;
/**
* @typedef {string & { minLength: 7, maxLength: 30 }} VersionString7To30Bytes
* Represents a version string, with a length between 7 and 30 characters.
*
* The format is [vendor]-[major].[minor].[patch]
*/
export type VersionString7To30Bytes = string;
/**
* @typedef {string & { minLength: 10, maxLength: 40 }} ErrorCodeString10To40Bytes
* Represents a machine-readable error code string, with a length between 10 and 40 characters.
*/
export type ErrorCodeString10To40Bytes = string;
/**
* @typedef {string & { minLength: 20, maxLength: 200 }} ErrorDescriptionString20To200Bytes
* Represents a human-readable error description string, with a length between 20 and 200 characters.
*/
export type ErrorDescriptionString20To200Bytes = string;
export type WalletNetwork = 'mainnet' | 'testnet';
/**
* @enum {number} SecurityLevels
*
* Silent = 0 Silently grants the request with no user interation.
* App = 1 Requires user approval for every application.
* Counterparty = 2 Requires user approval per counterparty per application.
*/
export declare enum SecurityLevels {
Silent = 0,
App = 1,
Counterparty = 2
}
/**
*
* SecurityLevel for protocols.
* 0 = Silently grants the request with no user interation.
* 1 = Requires user approval for every application.
* 2 = Requires user approval per counterparty per application.
*
*/
export type SecurityLevel = 0 | 1 | 2;
export type WalletProtocol = [SecurityLevel, ProtocolString5To400Bytes];
export type WalletCounterparty = PubKeyHex | 'self' | 'anyone';
export type AcquisitionProtocol = 'direct' | 'issuance';
export type KeyringRevealer = PubKeyHex | 'certifier';
export type ActionStatus = 'completed' | 'unprocessed' | 'sending' | 'unproven' | 'unsigned' | 'nosend' | 'nonfinal' | 'failed';
/**
* Controls behavior of input BEEF validation.
*
* If `known`, input transactions may omit supporting validity proof data for all TXIDs known to this wallet.
*
* If undefined, input BEEFs must be complete and valid.
*/
export type TrustSelf = 'known';
/**
* @param {OutpointString} outpoint - The outpoint being consumed.
* @param {DescriptionString5to50Bytes} inputDescription - A description of this input for contextual understanding of what it consumes.
* @param {HexString} unlockingScript - Optional. The unlocking script needed to release the specified UTXO.
* @param {PositiveInteger} unlockingScriptLength - Optional. Length of the unlocking script, in case it will be provided later using `signAction`.
* @param {PositiveIntegerOrZero} sequenceNumber - Optional. The sequence number applied to the input.
*/
export interface CreateActionInput {
outpoint: OutpointString;
inputDescription: DescriptionString5to50Bytes;
unlockingScript?: HexString;
unlockingScriptLength?: PositiveInteger;
sequenceNumber?: PositiveIntegerOrZero;
}
/**
* @param {HexString} lockingScript - The locking script that dictates how the output can later be spent.
* @param {SatoshiValue} satoshis - Number of Satoshis that constitute this output.
* @param {DescriptionString5to50Bytes} outputDescription - Description of what this output represents.
* @param {BasketStringUnder300Bytes} [basket] - Name of the basket where this UTXO will be held, if tracking is desired.
* @param {string} [customInstructions] - Custom instructions attached onto this UTXO, often utilized within application logic to provide necessary unlocking context or track token histories.
* @param {OutputTagStringUnder300Bytes[]} [tags] - Tags assigned to the output for sorting or filtering.
*/
export interface CreateActionOutput {
lockingScript: HexString;
satoshis: SatoshiValue;
outputDescription: DescriptionString5to50Bytes;
basket?: BasketStringUnder300Bytes;
customInstructions?: string;
tags?: OutputTagStringUnder300Bytes[];
}
/**
* @param {BooleanDefaultTrue} [signAndProcess] - Optional. If true and all inputs have unlockingScripts, the new transaction will be signed and handed off for processing by the network; result `txid` and `tx` are valid and `signableTransaciton` is undefined. If false or an input has an unlockingScriptLength, result `txid` and `tx` are undefined and `signableTransaction` is valid.
* @param {BooleanDefaultTrue} [acceptDelayedBroadcast] - Optional. If true, the transaction will be sent to the network by a background process; use `noSend` and `sendWith` options to batch chained transactions. If false, the transaction will be broadcast to the network and any errors returned in result; note that rapidly sent chained transactions may still fail due to network propagation delays.
* @param {'known'} [trustSelf] - Optional. If `known`, input transactions may omit supporting validity proof data for TXIDs known to this wallet.
* @param {TXIDHexString[]} [knownTxids] - Optional. When working with large chained transactions using `noSend` and `sendWith` options, include TXIDs of inputs that may be assumed to be valid even if not already known by this wallet.
* @param {BooleanDefaultFalse} [returnTXIDOnly] - Optional. If true, only a TXID will be returned instead of a transaction.
* @param {BooleanDefaultFalse} [noSend] - Optional. If true, the transaction will be constructed but not sent to the network. Supports the creation of chained batches of transactions using the `sendWith` option.
* @param {OutPoint[]} [noSendChange] - Optional. Valid when `noSend` is true. May contain `noSendChange` outpoints previously returned by prior `noSend` actions in the same batch of chained actions.
* @param {TXIDHexString[]} [sendWith] - Optional. Sends a batch of actions previously created as `noSend` actions to the network; either synchronously if `acceptDelayedBroadcast` is true or by a background process.
* @param {BooleanDefaultTrue} [randomizeOutputs] — optional. When set to false, the wallet will avoid randomizing the order of outputs within the transaction.
*/
export interface CreateActionOptions {
signAndProcess?: BooleanDefaultTrue;
acceptDelayedBroadcast?: BooleanDefaultTrue;
trustSelf?: TrustSelf;
knownTxids?: TXIDHexString[];
returnTXIDOnly?: BooleanDefaultFalse;
noSend?: BooleanDefaultFalse;
noSendChange?: OutpointString[];
sendWith?: TXIDHexString[];
randomizeOutputs?: BooleanDefaultTrue;
}
export type SendWithResultStatus = 'unproven' | 'sending' | 'failed';
export interface SendWithResult {
txid: TXIDHexString;
status: SendWithResultStatus;
}
/**
* Indicates status of a new Action following a `createAction` or `signAction` in immediate mode:
* When `acceptDelayedBroadcast` is falses.
*
* 'success': The action has been broadcast and accepted by the bitcoin processing network.
* 'doulbeSpend': The action has been confirmed to double spend one or more inputs, and by the "first-seen-rule" is the loosing transaction.
* 'invalidTx': The action was rejected by the processing network as an invalid bitcoin transaction.
* 'serviceError': The broadcast services are currently unable to reach the bitcoin network. The action is now queued for delayed retries.
*/
export type ReviewActionResultStatus = 'success' | 'doubleSpend' | 'serviceError' | 'invalidTx';
export interface ReviewActionResult {
txid: TXIDHexString;
status: ReviewActionResultStatus;
/**
* Any competing txids reported for this txid, valid when status is 'doubleSpend'.
*/
competingTxs?: string[];
/**
* Merged beef of competingTxs, valid when status is 'doubleSpend'.
*/
competingBeef?: number[];
}
export interface SignableTransaction {
tx: AtomicBEEF;
reference: Base64String;
}
export interface CreateActionResult {
txid?: TXIDHexString;
tx?: AtomicBEEF;
noSendChange?: OutpointString[];
sendWithResults?: SendWithResult[];
signableTransaction?: SignableTransaction;
}
/**
* @param {DescriptionString5to50Bytes} description - A human-readable description of the action represented by this transaction.
* @param {BEEF} [inputBEEF] - BEEF data associated with the set of input transactions from which UTXOs will be consumed.
* @param {CreateActionInput[]} [inputs] - An optional array of input objects used in the transaction.
* @param {CreateActionOutput[]} [outputs] - An optional array of output objects for the transaction.
* @param {PositiveIntegerOrZero} [lockTime] - Optional lock time for the transaction.
* @param {PositiveInteger} [version] - Optional transaction version specifier.
* @param {LabelStringUnder300Bytes[]} [labels] - Optional labels providing additional categorization for the transaction.
* @param {CreateActionOptions} [options] - Optional settings modifying transaction processing behavior.
*/
export interface CreateActionArgs {
description: DescriptionString5to50Bytes;
inputBEEF?: BEEF;
inputs?: CreateActionInput[];
outputs?: CreateActionOutput[];
lockTime?: PositiveIntegerOrZero;
version?: PositiveIntegerOrZero;
labels?: LabelStringUnder300Bytes[];
options?: CreateActionOptions;
}
/**
* @param {HexString} unlockingScript - The unlocking script for the corresponding input.
* @param {PositiveIntegerOrZero} [sequenceNumber] - The sequence number of the input.
*/
export interface SignActionSpend {
unlockingScript: HexString;
sequenceNumber?: PositiveIntegerOrZero;
}
/**
* @param {BooleanDefaultTrue} [acceptDelayedBroadcast] - Optional. If true, transaction will be sent to the network by a background process; use `noSend` and `sendWith` options to batch chained transactions. If false, transaction will be broadcast to the network and any errors returned in result; note that rapidly sent chained transactions may still fail due to network propagation delays.
* @param {'known'} [trustSelf] - Optional. If `known`, input transactions may omit supporting validity proof data for TXIDs known to this wallet or included in `knownTxids`.
* @param {TXIDHexString[]} [knownTxids] - Optional. When working with large chained transactions using `noSend` and `sendWith` options, include TXIDs of inputs that may be assumed to be valid even if not already known by this wallet.
* @param {BooleanDefaultFalse} [returnTXIDOnly] - Optional. If true, only a TXID will be returned instead of a transaction.
* @param {BooleanDefaultFalse} [noSend] - Optional. If true, the transaction will be constructed but not sent to the network. Supports the creation of chained batches of transactions using the `sendWith` option.
* @param {TXIDHexString[]} [sendWith] - Optional. Sends a batch of actions previously created as `noSend` actions to the network; either synchronously if `acceptDelayedBroadcast` is true or by a background process.
*/
export interface SignActionOptions {
acceptDelayedBroadcast?: BooleanDefaultTrue;
returnTXIDOnly?: BooleanDefaultFalse;
noSend?: BooleanDefaultFalse;
sendWith?: TXIDHexString[];
}
/**
* @param {Record<PositiveIntegerOrZero, SignActionSpend>} spends - Map of input indexes to the corresponding unlocking script and optional sequence number.
* @param {Base64String} reference - Reference number returned from the call to `createAction`.
* @param {SignActionOptions} [options] - Optional settings modifying transaction processing behavior.
*/
export interface SignActionArgs {
spends: Record<PositiveIntegerOrZero, SignActionSpend>;
reference: Base64String;
options?: SignActionOptions;
}
/**
*
*/
export interface SignActionResult {
txid?: TXIDHexString;
tx?: AtomicBEEF;
sendWithResults?: SendWithResult[];
}
/**
* @param {Base64String} reference - Reference number for the transaction to abort.
*/
export interface AbortActionArgs {
reference: Base64String;
}
export interface AbortActionResult {
aborted: true;
}
export type AcquireCertificateResult = WalletCertificate;
/**
* @param {LabelStringUnder300Bytes[]} labels - An array of labels used to filter actions.
* @param {'any' | 'all'} [labelQueryMode] - Specifies how to match labels (default is any which matches any of the labels).
* @param {BooleanDefaultFalse} [includeLabels] - Whether to include transaction labels in the result set.
* @param {BooleanDefaultFalse} [includeInputs] - Whether to include input details in the result set.
* @param {BooleanDefaultFalse} [includeInputSourceLockingScripts] - Whether to include input source locking scripts in the result set.
* @param {BooleanDefaultFalse} [includeInputUnlockingScripts] - Whether to include input unlocking scripts in the result set.
* @param {BooleanDefaultFalse} [includeOutputs] - Whether to include output details in the result set.
* @param {BooleanDefaultFalse} [includeOutputLockingScripts] - Whether to include output locking scripts in the result set.
* @param {PositiveIntegerDefault10Max10000} [limit] - The maximum number of transactions to retrieve.
* @param {PositiveIntegerOrZero} [offset] - Number of transactions to skip before starting to return the results.
* @param {BooleanDefaultTrue} [seekPermission] — Whether to seek permission from the user for this operation if required. Default true, will return an error rather than proceed if set to false.
*/
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;
}
export interface WalletActionInput {
sourceOutpoint: OutpointString;
sourceSatoshis: SatoshiValue;
sourceLockingScript?: HexString;
unlockingScript?: HexString;
inputDescription: DescriptionString5to50Bytes;
sequenceNumber: PositiveIntegerOrZero;
}
export interface WalletActionOutput {
satoshis: SatoshiValue;
lockingScript?: HexString;
spendable: boolean;
customInstructions?: string;
tags: OutputTagStringUnder300Bytes[];
outputIndex: PositiveIntegerOrZero;
outputDescription: DescriptionString5to50Bytes;
basket: BasketStringUnder300Bytes;
}
export interface WalletOutput {
satoshis: SatoshiValue;
lockingScript?: HexString;
spendable: boolean;
customInstructions?: string;
tags?: OutputTagStringUnder300Bytes[];
outpoint: OutpointString;
labels?: LabelStringUnder300Bytes[];
}
export interface WalletAction {
txid: TXIDHexString;
satoshis: SatoshiValue;
status: ActionStatus;
isOutgoing: boolean;
description: DescriptionString5to50Bytes;
labels?: LabelStringUnder300Bytes[];
version: PositiveIntegerOrZero;
lockTime: PositiveIntegerOrZero;
inputs?: WalletActionInput[];
outputs?: WalletActionOutput[];
}
export interface ListActionsResult {
totalActions: PositiveIntegerOrZero;
actions: WalletAction[];
}
/**
* @param {Base64String} derivationPrefix - Payment-level derivation prefix used by the sender for key derivation (for payments).
* @param {Base64String} derivationSuffix - Specific output-level derivation suffix used by the sender for key derivation (for payments).
* @param {PubKeyHex} senderIdentityKey - Public identity key of the sender (for payments).
*/
export interface WalletPayment {
derivationPrefix: Base64String;
derivationSuffix: Base64String;
senderIdentityKey: PubKeyHex;
}
/**
* @param {BasketStringUnder300Bytes} basket - Basket in which to place the output (for insertions).
* @param {string} [customInstructions] - Optionally provided custom instructions attached to the output (for insertions).
* @param {OutputTagStringUnder300Bytes[]} [tags] - Tags attached to the output (for insertions).
*/
export interface BasketInsertion {
basket: BasketStringUnder300Bytes;
customInstructions?: string;
tags?: OutputTagStringUnder300Bytes[];
}
/**
* @param {PositiveIntegerOrZero} outputIndex - Index of the output within the transaction.
* @param {'payment' | 'insert'} protocol - Specifies whether the output is a payment (to be received into the wallet balance) or an insert operation (into a particular basket).
* @param {WalletPayment} [paymentRemittance] - Optional. Remittance data, structured accordingly for the payment operation.
* @param {BasketInsertion} [insertionRemittance] - Optional. Remittance data, structured accordingly for the insertion operation.
*/
export interface InternalizeOutput {
outputIndex: PositiveIntegerOrZero;
protocol: 'wallet payment' | 'basket insertion';
paymentRemittance?: WalletPayment;
insertionRemittance?: BasketInsertion;
}
/**
* @param {BEEF} tx - Atomic BEEF-formatted transaction to internalize.
* @param {InternalizeOutput[]} outputs - Metadata about outputs, processed differently based on payment or insertion types.
* @param {DescriptionString5to50Bytes} description - Human-readable description of the transaction being internalized.
* @param {LabelStringUnder300Bytes[]} [labels] - Optional labels associated with this transaction.
* @param {BooleanDefaultTrue} [seekPermission] — Whether to seek permission from the user for this operation if required. Default true, will return an error rather than proceed if set to false.
*/
export interface InternalizeActionArgs {
tx: AtomicBEEF;
outputs: InternalizeOutput[];
description: DescriptionString5to50Bytes;
labels?: LabelStringUnder300Bytes[];
seekPermission?: BooleanDefaultTrue;
}
export interface InternalizeActionResult {
accepted: true;
}
/**
* @param {BasketStringUnder300Bytes} basket - The associated basket name whose outputs should be listed.
* @param {OutputTagStringUnder300Bytes[]} [tags] - Filter outputs based on these tags.
* @param {'all' | 'any'} [tagQueryMode] - Filter mode, defining whether all or any of the tags must match. By default, any tag can match.
* @param {'locking scripts' | 'entire transactions'} [include] - Whether to include locking scripts (with each output) or entire transactions (as aggregated BEEF, at the top level) in the result. By default, unless specified, neither are returned.
* @param {BooleanDefaultFalse} [includeEntireTransactions] - Whether to include the entire transaction(s) in the result.
* @param {BooleanDefaultFalse} [includeCustomInstructions] - Whether custom instructions should be returned in the result.
* @param {BooleanDefaultFalse} [includeTags] - Whether the tags associated with the output should be returned.
* @param {BooleanDefaultFalse} [includeLabels] - Whether the labels associated with the transaction containing the output should be returned.
* @param {PositiveIntegerDefault10Max10000} [limit] - Optional limit on the number of outputs to return.
* @param {number} [offset] - If positive or zero: Number of outputs to skip before starting to return results, oldest first.
* If negative: Outputs are returned newest first and offset of -1 is the newest output.
* When using negative offsets, caution is required as new outputs may be added between calls,
* potentially causing outputs to be duplicated across calls.
* @param {BooleanDefaultTrue} [seekPermission] — Whether to seek permission from the user for this operation if required. Default true, will return an error rather than proceed if set to false.
*/
export interface ListOutputsArgs {
basket: BasketStringUnder300Bytes;
tags?: OutputTagStringUnder300Bytes[];
tagQueryMode?: 'all' | 'any';
include?: 'locking scripts' | 'entire transactions';
includeCustomInstructions?: BooleanDefaultFalse;
includeTags?: BooleanDefaultFalse;
includeLabels?: BooleanDefaultFalse;
limit?: PositiveIntegerDefault10Max10000;
offset?: number;
seekPermission?: BooleanDefaultTrue;
}
export interface ListOutputsResult {
totalOutputs: PositiveIntegerOrZero;
BEEF?: BEEF;
outputs: WalletOutput[];
}
export interface RelinquishOutputArgs {
basket: BasketStringUnder300Bytes;
output: OutpointString;
}
export interface RelinquishOutputResult {
relinquished: true;
}
/**
* @param {WalletProtocol} protocolID - The security level and protocol string under which the data should be encrypted.
* @param {KeyIDStringUnder800Bytes} keyID - Key ID under which the encryption will be performed.
* @param {DescriptionString5to50Bytes} [privilegedReason] - Reason provided for privileged access, required if this is a privileged operation.
* @param {WalletCounterparty} [counterparty] - Public key of the counterparty (if two-party encryption is desired).
* @param {BooleanDefaultFalse} [privileged] - Whether this is a privileged request.
* @param {BooleanDefaultTrue} [seekPermission] — Whether to seek permission from the user for this operation if required. Default true, will return an error rather than proceed if set to false.
*/
export interface WalletEncryptionArgs {
protocolID: WalletProtocol;
keyID: KeyIDStringUnder800Bytes;
counterparty?: WalletCounterparty;
privileged?: BooleanDefaultFalse;
privilegedReason?: DescriptionString5to50Bytes;
seekPermission?: BooleanDefaultTrue;
}
/**
* When `identityKey` is true, `WalletEncryptionArgs` are not used.
*
* When `identityKey` is undefined, `WalletEncryptionArgs` are required.
*
* @param {BooleanDefaultFalse|true} [identityKey] - Use true to retrieve the current user's own identity key, overriding any protocol ID, key ID, or counterparty specified.
* @param {BooleanDefaultFalse} [forSelf] - Whether to return the public key derived from the current user's own identity (as opposed to the counterparty's identity).
*/
export interface GetPublicKeyArgs extends Partial<WalletEncryptionArgs> {
identityKey?: true;
forSelf?: BooleanDefaultFalse;
}
/**
* @param {PubKeyHex} counterparty - The public key of the counterparty involved in the linkage.
* @param {PubKeyHex} verifier - The public key of the verifier requesting the linkage information.
* @param {DescriptionString5to50Bytes} [privilegedReason] - Reason provided for privileged access, required if this is a privileged operation.
* @param {BooleanDefaultFalse} [privileged] - Whether this is a privileged request.
*/
export interface RevealCounterpartyKeyLinkageArgs {
counterparty: PubKeyHex;
verifier: PubKeyHex;
privileged?: BooleanDefaultFalse;
privilegedReason?: DescriptionString5to50Bytes;
}
/**
* @param {PubKeyHex} counterparty - The public key of the counterparty involved in the linkage.
* @param {PubKeyHex} verifier - The public key of the verifier requesting the linkage information.
* @param {WalletProtocol} protocolID - The security level and protocol string associated with the linkage information to reveal.
* @param {KeyIDStringUnder800Bytes} keyID - The key ID associated with the linkage information to reveal.
* @param {DescriptionString5to50Bytes} [privilegedReason] - Optional. Reason provided for privileged access, required if this is a privileged operation.
* @param {BooleanDefaultFalse} [privileged] - Optional. Whether this is a privileged request.
*/
export interface RevealSpecificKeyLinkageArgs {
counterparty: WalletCounterparty;
verifier: PubKeyHex;
protocolID: WalletProtocol;
keyID: KeyIDStringUnder800Bytes;
privilegedReason?: DescriptionString5to50Bytes;
privileged?: BooleanDefaultFalse;
}
/**
*/
export interface KeyLinkageResult {
encryptedLinkage: Byte[];
encryptedLinkageProof: Byte[];
prover: PubKeyHex;
verifier: PubKeyHex;
counterparty: PubKeyHex;
}
/**
*/
export interface RevealCounterpartyKeyLinkageResult extends KeyLinkageResult {
revelationTime: ISOTimestampString;
}
/**
*/
export interface RevealSpecificKeyLinkageResult extends KeyLinkageResult {
protocolID: WalletProtocol;
keyID: KeyIDStringUnder800Bytes;
proofType: Byte;
}
/**
* @param {Byte[]} plaintext - Array of bytes constituting the plaintext data to be encrypted.
*/
export interface WalletEncryptArgs extends WalletEncryptionArgs {
plaintext: Byte[];
}
export interface WalletEncryptResult {
ciphertext: Byte[];
}
/**
* @param {Byte[]} ciphertext - Encrypted bytes, including the initialization vector, for decryption.
*/
export interface WalletDecryptArgs extends WalletEncryptionArgs {
ciphertext: Byte[];
}
export interface WalletDecryptResult {
plaintext: Byte[];
}
/**
* @param {Byte[]} data - Input data (in bytes) for which the HMAC needs to be created.
*/
export interface CreateHmacArgs extends WalletEncryptionArgs {
data: Byte[];
}
export interface CreateHmacResult {
hmac: Byte[];
}
/**
* @param {Byte[]} data - The input data whose HMAC is to be verified.
* @param {Byte[]} hmac - Byte array representing the HMAC value to be verified.
*/
export interface VerifyHmacArgs extends WalletEncryptionArgs {
data: Byte[];
hmac: Byte[];
}
export interface VerifyHmacResult {
valid: true;
}
/**
* @param {Byte[]} [data] - Data to be signed using the derived private key with ECDSA. Required unless directly signing a hash.
* @param {Byte[]} [hashToDirectlySign] - Sign a pre-hashed value in situations where data can't or shouldn't be revealed, whether due to its size or for privacy.
*/
export interface CreateSignatureArgs extends WalletEncryptionArgs {
data?: Byte[];
hashToDirectlySign?: Byte[];
}
export interface CreateSignatureResult {
signature: Byte[];
}
/**
* @param {Byte[]} [args.data] - The data originally signed, which is required for verification unless directly verifying a hash.
* @param {Byte[]} [args.hashToDirectlyVerify] - Optional field to verify the signature against a precomputed hash instead of data.
* @param {Byte[]} args.signature - The DER-encoded ECDSA signature to validate.
* @param {BooleanDefaultFalse} [args.forSelf] - Whether the signature to be verified was created by this user rather than the counterparty.
*/
export interface VerifySignatureArgs extends WalletEncryptionArgs {
data?: Byte[];
hashToDirectlyVerify?: Byte[];
signature: Byte[];
forSelf?: BooleanDefaultFalse;
}
export interface VerifySignatureResult {
valid: true;
}
/**
* @param {Base64String} type - Type identifier for the certificate.
* @param {PubKeyHex} certifier - The public identity key of the certifier.
* @param {AcquisitionProtocol} acquisitionProtocol - Specifies the acquisition process, set to either 'issuance' or 'direct'.
* @param {Record<CertificateFieldNameUnder50Bytes, string>} fields - The fields included within the certificate.
* @param {Base64String} [serialNumber] - Serial number of the certificate to acquire (required when the acquisition protocol is direct).
* @param {string} [revocationOutpoint] - Reference for an outpoint comprising a Bitcoin token that, if ever spent, marks the certificate as invalid (required when the acquisition protocol is direct).
* @param {HexString} [signature] - Signature over the certificate (required when the acquisition protocol is direct).
* @param {string} [certifierUrl] - URL of the certifier where certificate acquisition requests will be sent (required when the acquisition protocol is issuance).
* @param {KeyringRevealer} [keyringRevealer] - The public identity key of the entity revealing the keyring to the user, if different from the certifier (required when the acquisition protocol is direct).
* @param {Record<CertificateFieldNameUnder50Bytes, Base64String>} [keyringForSubject] - Keyring revealing all certificate fields to the subject (required when the acquisition protocol is direct).
* @param {BooleanDefaultFalse} [privileged] - Whether this is a privileged request.
* @param {DescriptionString5to50Bytes} [privilegedReason] - Reason provided for privileged access, required if this is a privileged operation.
*/
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;
}
export interface WalletCertificate {
type: Base64String;
subject: PubKeyHex;
serialNumber: Base64String;
certifier: PubKeyHex;
revocationOutpoint: OutpointString;
signature: HexString;
fields: Record<CertificateFieldNameUnder50Bytes, string>;
}
export interface IdentityCertifier {
name: EntityNameStringMax100Bytes;
iconUrl: EntityIconURLStringMax500Bytes;
description: DescriptionString5to50Bytes;
trust: PositiveIntegerMax10;
}
export interface IdentityCertificate extends WalletCertificate {
certifierInfo: IdentityCertifier;
publiclyRevealedKeyring: Record<CertificateFieldNameUnder50Bytes, Base64String>;
decryptedFields: Record<CertificateFieldNameUnder50Bytes, string>;
}
/**
* @param {PubKeyHex[]} certifiers - An array of public keys for specific certifiers (filters by these certifiers).
* @param {Base64String[]} types - An array of certificate types issued by any of the specified certifiers, which should be returned.
* @param {PositiveIntegerDefault10Max10000} [limit] - Maximum number of certificates to return.
* @param {PositiveIntegerOrZero} [offset] - Number of records to skip before starting to return results.
* @param {BooleanDefaultFalse} [privileged] - Whether this is a privileged request.
* @param {DescriptionString5to50Bytes} [privilegedReason] - Reason provided for privileged access, required if this is a privileged operation.
*/
export interface ListCertificatesArgs {
certifiers: PubKeyHex[];
types: Base64String[];
limit?: PositiveIntegerDefault10Max10000;
offset?: PositiveIntegerOrZero;
privileged?: BooleanDefaultFalse;
privilegedReason?: DescriptionString5to50Bytes;
}
export interface CertificateResult extends WalletCertificate {
keyring?: Record<CertificateFieldNameUnder50Bytes, Base64String>;
verifier?: string;
}
export interface ListCertificatesResult {
totalCertificates: PositiveIntegerOrZero;
certificates: CertificateResult[];
}
/**
* @param {WalletCertificate} certificate - The specific identity certificate being proven.
* @param {CertificateFieldNameUnder50Bytes[]} fieldsToReveal - Array of field names that need to be revealed to the verifier.
* @param {PubKeyHex} verifier - Public key of the verifier, to whom the key revelations will be made.
* @param {BooleanDefaultFalse} [privileged] - Whether this is a privileged request.
* @param {DescriptionString5to50Bytes} [privilegedReason] - Reason provided for privileged access, required if this is a privileged operation.
*/
export interface ProveCertificateArgs {
certificate: Partial<WalletCertificate>;
fieldsToReveal: CertificateFieldNameUnder50Bytes[];
verifier: PubKeyHex;
privileged?: BooleanDefaultFalse;
privilegedReason?: DescriptionString5to50Bytes;
}
export interface ProveCertificateResult {
keyringForVerifier: Record<CertificateFieldNameUnder50Bytes, Base64String>;
certificate?: WalletCertificate;
verifier?: PubKeyHex;
}
/**
* @param {Base64String} type - Type identifier for the certificate.
* @param {PubKeyHex} certifier - The public identity key of the certifier.
* @param {Base64String} serialNumber - Serial number of the certificate to relinquish.
*/
export interface RelinquishCertificateArgs {
type: Base64String;
serialNumber: Base64String;
certifier: PubKeyHex;
}
export interface RelinquishCertificateResult {
relinquished: true;
}
export interface AuthenticatedResult {
authenticated: true;
}
export interface GetHeightResult {
height: PositiveInteger;
}
/**
* @param {PositiveInteger} height - Specifies the height at which the block header needs to be retrieved.
*/
export interface GetHeaderArgs {
height: PositiveInteger;
}
export interface GetHeaderResult {
header: HexString;
}
export interface GetNetworkResult {
network: WalletNetwork;
}
export interface GetVersionResult {
version: VersionString7To30Bytes;
}
/**
* @param {PubKeyHex} identityKey - Identity key used to filter and discover certificates.
* @param {PositiveIntegerDefault10Max10000} [limit] - Maximum number of certificates to return in the response.
* @param {PositiveIntegerOrZero} [offset] - Skip this number of records before starting to provide results.
* @param {BooleanDefaultTrue} [seekPermission] — Whether to seek permission from the user for this operation if required. Default true, will return an error rather than proceed if set to false.
*/
export interface DiscoverByIdentityKeyArgs {
identityKey: PubKeyHex;
limit?: PositiveIntegerDefault10Max10000;
offset?: PositiveIntegerOrZero;
seekPermission?: BooleanDefaultTrue;
}
/**
*/
export interface DiscoverCertificatesResult {
totalCertificates: PositiveIntegerOrZero;
certificates: IdentityCertificate[];
}
/**
* @param {Record<CertificateFieldNameUnder50Bytes, string>} attributes - The attributes used to discover the certificates.
* @param {PositiveIntegerDefault10Max10000} [limit] - Optional limit on the number of results returned.
* @param {PositiveIntegerOrZero} [offset] - Starts retrieval of results after the specified number of records.
* @param {BooleanDefaultTrue} [seekPermission] — Whether to seek permission from the user for this operation if required. Default true, will return an error rather than proceed if set to false.
*/
export interface DiscoverByAttributesArgs {
attributes: Record<CertificateFieldNameUnder50Bytes, string>;
limit?: PositiveIntegerDefault10Max10000;
offset?: PositiveIntegerOrZero;
seekPermission?: BooleanDefaultTrue;
}
/**
* Every method of the `Wallet` interface has a return value of the form `Promise<object>`.
* When errors occur, an exception object may be thrown which must conform to the `WalletErrorObject` interface.
* Serialization layers can rely on the `isError` property being unique to error objects.
* Deserialization should rethrow `WalletErrorObject` conforming objects.
*/
export interface WalletErrorObject extends Error {
isError: true;
}
/**
*
*/
export interface GetPublicKeyResult {
publicKey: PubKeyHex;
}
/**
* The Wallet interface defines a wallet capable of various tasks including transaction creation and signing,
* encryption, decryption, identity certificate management, identity verification, and communication
* with applications as per the BRC standards. This interface allows applications to interact with
* the wallet for a range of functionalities aligned with the Babbage architectural principles.
*
* Error Handling
*
* Every method of the `Wallet` interface has a return value of the form `Promise<object>`.
* When an error occurs, an exception object may be thrown which must conform to the `WalletErrorObject` interface.
* Serialization layers can rely on the `isError` property being unique to error objects to
* deserialize and rethrow `WalletErrorObject` conforming objects.
*/
export interface WalletInterface {
/**
* Retrieves a derived or identity public key based on the requested protocol, key ID, counterparty, and other factors.
*
* @param {GetPublicKeyArgs} args - Arguments to specify which public key to retrieve.
* @param {OriginatorDomainNameStringUnder250Bytes} [originator] - Fully-qualified domain name (FQDN) of the application that originated the request.
* @returns {Promise<GetPublicKeyResult>}} Resolves to an object containing the public key, or an error response.
*/
getPublicKey: (args: GetPublicKeyArgs, originator?: OriginatorDomainNameStringUnder250Bytes) => Promise<GetPublicKeyResult>;
/**
* Reveals the key linkage between ourselves and a counterparty, to a particular verifier, across all interactions with the counterparty.
*
* @param {RevealCounterpartyKeyLinkageArgs} args - Contains information about counterparty, verifier, and whether the operation is privileged.
* @param {OriginatorDomainNameStringUnder250Bytes} [originator] - Fully-qualified domain name (FQDN) of the application that originated the request.
* @returns {Promise<RevealSpecificKeyLinkageResult>} Resolves to the key linkage, or an error response.
*/
revealCounterpartyKeyLinkage: (args: RevealCounterpartyKeyLinkageArgs, originator?: OriginatorDomainNameStringUnder250Bytes) => Promise<RevealCounterpartyKeyLinkageResult>;
/**
* Reveals the key linkage between ourselves and a counterparty, to a particular verifier, with respect to a specific interaction.
*
* @param {RevealSpecificKeyLinkageArgs} args - The object defining the counterparty, verifier, protocol, and keyID for which linkage should be revealed.
* @param {OriginatorDomainNameStringUnder250Bytes} [originator] - Fully-qualified domain name (FQDN) of the application that originated the request.
* @returns {Promise<RevealSpecificKeyLinkageResult>} The promise returns the requested linkage information, or an error object.
*/
revealSpecificKeyLinkage: (args: RevealSpecificKeyLinkageArgs, originator?: OriginatorDomainNameStringUnder250Bytes) => Promise<RevealSpecificKeyLinkageResult>;
/**
* Encrypts the provided plaintext data using derived keys, based on the protocol ID, key ID, counterparty, and other factors.
*
* @param {WalletEncryptArgs} args - Information needed for encryption, including the plaintext, protocol ID, and key ID.
* @param {OriginatorDomainNameStringUnder250Bytes} [originator] - Fully-qualified domain name (FQDN) of the application that originated the request.
* @returns {Promise<WalletEncryptResult>} Resolves to the encrypted ciphertext bytes or an error if encryption fails.
*/
encrypt: (args: WalletEncryptArgs, originator?: OriginatorDomainNameStringUnder250Bytes) => Promise<WalletEncryptResult>;
/**
* Decrypts the provided ciphertext using derived keys, based on the protocol ID, key ID, counterparty, and other factors.
*
* @param {WalletDecryptArgs} args - Contains the ciphertext, protocol ID, and key ID required to decrypt the data.
* @param {OriginatorDomainNameStringUnder250Bytes} [originator] - Fully-qualified domain name (FQDN) of the application that originated the request.
* @returns {Promise<WalletDecryptResult>} Resolves to the decryption result, containing the plaintext data or an error.
*/
decrypt: (args: WalletDecryptArgs, originator?: OriginatorDomainNameStringUnder250Bytes) => Promise<WalletDecryptResult>;
/**
* Creates an HMAC (Hash-based Message Authentication Code) based on the provided data, protocol, key ID, counterparty, and other factors.
*
* @param {CreateHmacArgs} args - Arguments containing the data, protocol ID, and key ID to generate the HMAC from.
* @param {OriginatorDomainNameStringUnder250Bytes} [originator] - Fully-qualified domain name (FQDN) of the application that originated the request.
* @returns {Promise<CreateHmacResult>} Resolves to an object containing the generated HMAC bytes, or an error if the creation fails.
*/
createHmac: (args: CreateHmacArgs, originator?: OriginatorDomainNameStringUnder250Bytes) => Promise<CreateHmacResult>;
/**
* Verifies an HMAC (Hash-based Message Authentication Code) based on the provided data, protocol, key ID, counterparty, and other factors.
*
* @param {VerifyHmacArgs} args - Arguments containing the HMAC data, protocol ID, and key ID needed for verification.
* @param {OriginatorDomainNameStringUnder250Bytes} [originator] - Fully-qualified domain name (FQDN) of the application that originated the request.
* @returns {Promise<VerifyHmacResult>} Resolves to an object confirming whether the HMAC was valid or an error.
*/
verifyHmac: (args: VerifyHmacArgs, originator?: OriginatorDomainNameStringUnder250Bytes) => Promise<VerifyHmacResult>;
/**
* Creates a digital signature for the provided data or hash using a specific protocol, key, and optionally considering privilege and counterparty.
*
* @param {CreateSignatureArgs} args - Arguments to specify data, protocol, key ID, and privilege for creating the signature.
* @param {OriginatorDomainNameStringUnder250Bytes} [originator] - Fully-qualified domain name (FQDN) of the application that originated the request.
* @returns {Promise<CreateSignatureResult>} The promise will resolve to an object containing the DER-encoded ECDSA signature, or an error on failure.
*/
createSignature: (args: CreateSignatureArgs, originator?: OriginatorDomainNameStringUnder250Bytes) => Promise<CreateSignatureResult>;
/**
* Verifies a digital signature for the provided data or hash using a specific protocol, key, and optionally considering privilege and counterparty.
*
* @param {VerifySignatureArgs} args - Arguments specifying the data, signature, protocol, and key ID.
* @param {OriginatorDomainNameStringUnder250Bytes} [originator] - Fully-qualified domain name (FQDN) of the application that originated the request.
* @returns {Promise<VerifySignatureResult>} The promise resolves to a boolean object indicating whether the signature was valid or an error message.
*/
verifySignature: (args: VerifySignatureArgs, originator?: OriginatorDomainNameStringUnder250Bytes) => Promise<VerifySignatureResult>;
/**
* Creates a new Bitcoin transaction based on the provided inputs, outputs, labels, locks, and other options.
*
* @param {CreateActionArgs} args - The arguments required to create the transaction.
* @param {OriginatorDomainNameStringUnder250Bytes} [originator] - Fully-qualified domain name (FQDN) of the application that originated the request.
* @returns {Promise<CreateActionResult>} The promise returns different structures based on the outcome: error response, response with TXID, response with transaction, or info about signable transaction (partial BEEF and reference number).
*/
createAction: (args: CreateActionArgs, originator?: OriginatorDomainNameStringUnder250Bytes) => Promise<CreateActionResult>;
/**
* Signs a transaction previously created using `createAction`.
*
* @param {SignActionArgs} args - Arguments to sign the transaction.
* @param {OriginatorDomainNameStringUnder250Bytes} [originator] - Fully-qualified domain name (FQDN) of the application that originated the request.
* @returns {Promise<SignActionResult>} The promise returns an error response or a response with either the completed transaction or TXID.
*/
signAction: (args: SignActionArgs, originator?: OriginatorDomainNameStringUnder250Bytes) => Promise<SignActionResult>;
/**
* Aborts a transaction that is in progress and has not yet been finalized or sent to the network.
*
* @param {AbortActionArgs} args - Arguments to identify the transaction that needs to be aborted.
* @param {OriginatorDomainNameStringUnder250Bytes} [originator] - Fully-qualified domain name (FQDN) of the application that originated the request.
* @returns {Promise<AbortActionResult>} The promise resolves to an object indicating the abortion result (either success or error).
*/
abortAction: (args: AbortActionArgs, originator?: OriginatorDomainNameStringUnder250Bytes) => Promise<AbortActionResult>;
/**
* Lists all transactions matching the specified labels.
*
* @param {ListActionsArgs} args - Arguments to specify how to filter or retrieve transactions.
* @param {OriginatorDomainNameStringUnder250Bytes} [originator] - Fully-qualified domain name (FQDN) of the application that originated the request.
* @returns {Promise<ListActionsResult>} The promise resolves to an object containing actions, their metadata, inputs, and outputs if applicable, or an error object.
*/
listActions: (args: ListActionsArgs, originator?: OriginatorDomainNameStringUnder250Bytes) => Promise<ListActionsResult>;
/**
* Submits a transaction to be internalized and optionally labeled, outputs paid to the wallet balance, inserted into baskets, and/or tagged.
*
* @param {InternalizeActionArgs} args - Arguments required to internalize the transaction.
* @param {OriginatorDomainNameStringUnder250Bytes} [originator] - Fully-qualified domain name (FQDN) of the application that originated the request.
* @returns {Promise<InternalizeActionResult>} The promise resolves to an object indicating the success of the operation or an error obje