@bsv/sdk
Version:
BSV Blockchain Software Development Kit
514 lines • 22.7 kB
TypeScript
import { AbortActionArgs, AcquireCertificateArgs, AcquisitionProtocol, AtomicBEEF, Base64String, BasketInsertion, BasketStringUnder300Bytes, BEEF, BooleanDefaultFalse, BooleanDefaultTrue, CertificateFieldNameUnder50Bytes, CreateActionArgs, CreateActionInput, CreateActionOptions, CreateActionOutput, DescriptionString5to50Bytes, DiscoverByAttributesArgs, DiscoverByIdentityKeyArgs, HexString, InternalizeActionArgs, InternalizeOutput, KeyringRevealer, LabelStringUnder300Bytes, ListActionsArgs, ListCertificatesArgs, ListOutputsArgs, OutpointString, OutputTagStringUnder300Bytes, PositiveInteger, PositiveIntegerDefault10Max10000, PositiveIntegerOrZero, ProveCertificateArgs, PubKeyHex, RelinquishCertificateArgs, RelinquishOutputArgs, SatoshiValue, SignActionArgs, SignActionOptions, SignActionSpend, TrustSelf, TXIDHexString, WalletPayment } from './Wallet.interfaces.js';
import { WalletLoggerInterface } from './WalletLoggerInterface.js';
export declare function parseWalletOutpoint(outpoint: string): {
txid: string;
vout: number;
};
/**
* Validate a satoshi amount.
*
* @param v - value to validate (integer number of satoshis)
* @param name - parameter name used in error messages
* @param min - optional minimum allowed satoshi value
* @returns validated satoshi number
* @throws WERR_INVALID_PARAMETER when invalid
*/
export declare function validateSatoshis(v: number | undefined, name: string, min?: number): number;
/**
* Validate an optional integer. Returns undefined or the validated integer.
*
* @param v - value to validate (may be undefined)
* @param name - parameter name used in error messages
* @param min - optional minimum value
* @param max - optional maximum value
* @returns validated integer or undefined
* @throws WERR_INVALID_PARAMETER when invalid
*/
export declare function validateOptionalInteger(v: number | undefined, name: string, min?: number, max?: number): number | undefined;
/**
* Validate an integer, applying an optional default.
*
* @param v - value to validate (may be undefined)
* @param name - parameter name used in error messages
* @param defaultValue - value to return when v is undefined
* @param min - optional minimum allowed value
* @param max - optional maximum allowed value
* @returns validated integer
* @throws WERR_INVALID_PARAMETER when invalid
*/
export declare function validateInteger(v: number | undefined, name: string, defaultValue?: number, min?: number, max?: number): number;
/**
* Validate a non-negative integer (zero allowed).
*
* @param v - value to validate
* @param name - parameter name used in error messages
* @returns validated integer
* @throws WERR_INVALID_PARAMETER when invalid
*/
export declare function validatePositiveIntegerOrZero(v: number, name: string): number;
/**
* Validate string length in bytes for UTF-8 encoded string.
*
* @param s - string to validate
* @param name - parameter name used in error messages
* @param min - optional minimum byte length
* @param max - optional maximum byte length
* @returns the original string when valid
* @throws WERR_INVALID_PARAMETER when invalid
*/
export declare function validateStringLength(s: string, name: string, min?: number, max?: number): string;
/**
* Validate a Base64 string (structure and decoded size).
*
* @param s - base64 string
* @param name - parameter name used in error messages
* @param min - optional minimum decoded byte length
* @param max - optional maximum decoded byte length
* @returns validated base64 string
* @throws WERR_INVALID_PARAMETER when invalid
*/
export declare function validateBase64String(s: string, name: string, min?: number, max?: number): string;
/**
* Check whether a string is a valid hex string (even length and hex characters).
*
* @param s - input string
* @returns true when s is a valid hex string
*/
export declare function isHexString(s: string): boolean;
/**
* DescriptionString5to2000Bytes alias type (documented).
*/
export type DescriptionString5to2000Bytes = string;
export interface ValidWalletSignerArgs {
logger?: WalletLoggerInterface;
}
export interface ValidCreateActionInput {
outpoint: OutPoint;
inputDescription: DescriptionString5to2000Bytes;
sequenceNumber: PositiveIntegerOrZero;
unlockingScript?: HexString;
unlockingScriptLength: PositiveInteger;
}
/**
* Validate a CreateActionInput structure.
*
* Ensures either unlockingScript or unlockingScriptLength is provided and consistent,
* validates outpoint, description length, and sequence number.
*
* @param i - CreateActionInput to validate
* @returns ValidCreateActionInput
* @throws WERR_INVALID_PARAMETER when invalid
*/
export declare function validateCreateActionInput(i: CreateActionInput): ValidCreateActionInput;
export interface ValidCreateActionOutput {
lockingScript: HexString;
satoshis: SatoshiValue;
outputDescription: DescriptionString5to2000Bytes;
basket?: BasketStringUnder300Bytes;
customInstructions?: string;
tags: BasketStringUnder300Bytes[];
}
/**
* Validate CreateActionOutput fields: locking script, satoshis, description, basket, tags.
*
* @param o - CreateActionOutput to validate
* @returns ValidCreateActionOutput
* @throws WERR_INVALID_PARAMETER when invalid
*/
export declare function validateCreateActionOutput(o: CreateActionOutput): ValidCreateActionOutput;
/**
* Normalize and validate CreateActionOptions, applying defaults for booleans/numbers/arrays.
*
* @param options - CreateActionOptions or undefined
* @returns ValidCreateActionOptions with defaults applied
*/
export declare function validateCreateActionOptions(options?: CreateActionOptions): ValidCreateActionOptions;
export interface ValidProcessActionOptions {
acceptDelayedBroadcast: BooleanDefaultTrue;
returnTXIDOnly: BooleanDefaultFalse;
noSend: BooleanDefaultFalse;
sendWith: TXIDHexString[];
}
export interface ValidCreateActionOptions extends ValidProcessActionOptions {
signAndProcess: boolean;
trustSelf?: TrustSelf;
knownTxids: TXIDHexString[];
noSendChange: OutPoint[];
randomizeOutputs: boolean;
}
export interface ValidSignActionOptions extends ValidProcessActionOptions {
acceptDelayedBroadcast: boolean;
returnTXIDOnly: boolean;
noSend: boolean;
sendWith: TXIDHexString[];
}
export interface ValidProcessActionArgs extends ValidWalletSignerArgs {
options: ValidProcessActionOptions;
isSendWith: boolean;
isNewTx: boolean;
isRemixChange: boolean;
isNoSend: boolean;
isDelayed: boolean;
isTestWerrReviewActions: boolean;
}
export interface ValidCreateActionArgs extends ValidProcessActionArgs {
description: DescriptionString5to2000Bytes;
inputBEEF?: BEEF;
inputs: ValidCreateActionInput[];
outputs: ValidCreateActionOutput[];
lockTime: number;
version: number;
labels: string[];
options: ValidCreateActionOptions;
isSignAction: boolean;
randomVals?: number[];
/**
* If true, signableTransactions will include sourceTransaction for each input,
* including those that do not require signature and those that were also contained
* in the inputBEEF.
*/
includeAllSourceTransactions: boolean;
}
export interface ValidSignActionArgs extends ValidProcessActionArgs {
spends: Record<PositiveIntegerOrZero, SignActionSpend>;
reference: Base64String;
options: ValidSignActionOptions;
}
/**
* Validate the arguments for creating a new action.
*
* @param args
* @returns validated arguments
* @throws primarily WERR_INVALID_PARAMETER if args are invalid.
*/
export declare function validateCreateActionArgs(args: CreateActionArgs, logger?: WalletLoggerInterface): ValidCreateActionArgs;
/**
* Set all default true/false booleans to true or false if undefined.
* Set all possibly undefined numbers to their default values.
* Set all possibly undefined arrays to empty arrays.
* Convert string outpoints to `{ txid: string, vout: number }`
*/
export declare function validateSignActionOptions(options?: SignActionOptions): ValidSignActionOptions;
/**
* Validate SignActionArgs and apply defaults/flags.
*
* @param args - SignActionArgs to validate
* @returns ValidSignActionArgs
*/
export declare function validateSignActionArgs(args: SignActionArgs): ValidSignActionArgs;
export interface ValidAbortActionArgs extends ValidWalletSignerArgs {
reference: Base64String;
}
/**
* Validate AbortActionArgs (ensures reference is a valid base64 string).
*
* @param args - AbortActionArgs
* @returns ValidAbortActionArgs
*/
export declare function validateAbortActionArgs(args: AbortActionArgs): ValidAbortActionArgs;
export interface ValidWalletPayment {
derivationPrefix: Base64String;
derivationSuffix: Base64String;
senderIdentityKey: PubKeyHex;
}
/**
* Validate wallet payment remittance structure.
*
* @param args - WalletPayment or undefined
* @returns ValidWalletPayment or undefined
*/
export declare function validateWalletPayment(args?: WalletPayment): ValidWalletPayment | undefined;
export interface ValidBasketInsertion {
basket: BasketStringUnder300Bytes;
customInstructions?: string;
tags: BasketStringUnder300Bytes[];
}
/**
* Validate a BasketInsertion structure (basket, custom instructions, tags).
*
* @param args - BasketInsertion or undefined
* @returns ValidBasketInsertion or undefined
*/
export declare function validateBasketInsertion(args?: BasketInsertion): ValidBasketInsertion | undefined;
export interface ValidInternalizeOutput {
outputIndex: PositiveIntegerOrZero;
protocol: 'wallet payment' | 'basket insertion';
paymentRemittance?: ValidWalletPayment;
insertionRemittance?: ValidBasketInsertion;
}
/**
* Validate an InternalizeOutput entry.
*
* @param args - InternalizeOutput to validate
* @returns ValidInternalizeOutput
*/
export declare function validateInternalizeOutput(args: InternalizeOutput): ValidInternalizeOutput;
export interface ValidInternalizeActionArgs extends ValidWalletSignerArgs {
tx: AtomicBEEF;
outputs: InternalizeOutput[];
description: DescriptionString5to2000Bytes;
labels: LabelStringUnder300Bytes[];
seekPermission: BooleanDefaultTrue;
}
/**
* Validate originator string (trim/lowercase and part length checks).
*
* @param s - originator string or undefined
* @returns normalized originator or undefined
*/
export declare function validateOriginator(s?: string): string | undefined;
/**
* Validate InternalizeActionArgs: tx, outputs, description, labels, permission flag.
*
* @param args - InternalizeActionArgs to validate
* @returns ValidInternalizeActionArgs
* @throws WERR_INVALID_PARAMETER when invalid
*/
export declare function validateInternalizeActionArgs(args: InternalizeActionArgs): ValidInternalizeActionArgs;
/**
* Validate an optional outpoint string (txid.vout).
*
* @param outpoint - outpoint string or undefined
* @param name - parameter name used in error messages
* @returns validated outpoint string or undefined
*/
export declare function validateOptionalOutpointString(outpoint: string | undefined, name: string): string | undefined;
/**
* Validate an outpoint string of the form txid.vout.
*
* @param outpoint - outpoint string
* @param name - parameter name used in error messages
* @returns normalized outpoint string (validated txid and vout)
* @throws WERR_INVALID_PARAMETER when invalid
*/
export declare function validateOutpointString(outpoint: string, name: string): string;
export interface ValidRelinquishOutputArgs extends ValidWalletSignerArgs {
basket: BasketStringUnder300Bytes;
output: OutpointString;
}
/**
* Validate RelinquishOutputArgs (basket and output).
*
* @param args - RelinquishOutputArgs
* @returns ValidRelinquishOutputArgs
*/
export declare function validateRelinquishOutputArgs(args: RelinquishOutputArgs): ValidRelinquishOutputArgs;
export interface ValidRelinquishCertificateArgs extends ValidWalletSignerArgs {
type: Base64String;
serialNumber: Base64String;
certifier: PubKeyHex;
}
/**
* Validate RelinquishCertificateArgs (type, serialNumber, certifier).
*
* @param args - RelinquishCertificateArgs
* @returns ValidRelinquishCertificateArgs
*/
export declare function validateRelinquishCertificateArgs(args: RelinquishCertificateArgs): ValidRelinquishCertificateArgs;
export interface ValidListCertificatesArgs extends ValidWalletSignerArgs {
partial?: {
type?: Base64String;
serialNumber?: Base64String;
certifier?: PubKeyHex;
subject?: PubKeyHex;
revocationOutpoint?: OutpointString;
signature?: HexString;
};
certifiers: PubKeyHex[];
types: Base64String[];
limit: PositiveIntegerDefault10Max10000;
offset: PositiveIntegerOrZero;
privileged: BooleanDefaultFalse;
privilegedReason?: DescriptionString5to50Bytes;
}
/**
* Validate ListCertificatesArgs: certifiers, types, paging, and optional privileged reason.
*
* @param args - ListCertificatesArgs
* @returns ValidListCertificatesArgs
*/
export declare function validateListCertificatesArgs(args: ListCertificatesArgs): ValidListCertificatesArgs;
export interface ValidAcquireCertificateArgs extends ValidWalletSignerArgs {
acquisitionProtocol: AcquisitionProtocol;
type: Base64String;
serialNumber?: Base64String;
certifier: PubKeyHex;
revocationOutpoint?: OutpointString;
fields: Record<CertificateFieldNameUnder50Bytes, string>;
signature?: HexString;
certifierUrl?: string;
keyringRevealer?: KeyringRevealer;
keyringForSubject?: Record<CertificateFieldNameUnder50Bytes, Base64String>;
privileged: boolean;
privilegedReason?: DescriptionString5to50Bytes;
}
export interface ValidAcquireDirectCertificateArgs extends ValidWalletSignerArgs {
type: Base64String;
serialNumber: Base64String;
certifier: PubKeyHex;
revocationOutpoint: OutpointString;
fields: Record<CertificateFieldNameUnder50Bytes, string>;
signature: HexString;
/**
* validated to an empty string, must be provided by wallet and must
* match expectations of keyringForSubject
*/
subject: PubKeyHex;
keyringRevealer: KeyringRevealer;
keyringForSubject: Record<CertificateFieldNameUnder50Bytes, Base64String>;
privileged: boolean;
privilegedReason?: DescriptionString5to50Bytes;
}
export interface ValidAcquireIssuanceCertificateArgs extends ValidWalletSignerArgs {
type: Base64String;
certifier: PubKeyHex;
certifierUrl: string;
fields: Record<CertificateFieldNameUnder50Bytes, string>;
/**
* validated to an empty string, must be provided by wallet and must
* match expectations of keyringForSubject
*/
subject: PubKeyHex;
privileged: boolean;
privilegedReason?: DescriptionString5to50Bytes;
}
/**
* Validate issuance-specific acquire certificate args.
*
* @param args - AcquireCertificateArgs with acquisitionProtocol === 'issuance'
* @returns ValidAcquireIssuanceCertificateArgs
* @throws when args contain fields invalid for issuance
*/
export declare function validateAcquireIssuanceCertificateArgs(args: AcquireCertificateArgs): ValidAcquireIssuanceCertificateArgs;
/**
* Validate direct-acquisition-specific acquire certificate args.
*
* @param args - AcquireCertificateArgs with acquisitionProtocol === 'direct'
* @returns ValidAcquireDirectCertificateArgs
* @throws when args contain fields invalid for direct acquisition
*/
export declare function validateAcquireDirectCertificateArgs(args: AcquireCertificateArgs): ValidAcquireDirectCertificateArgs;
export interface ValidProveCertificateArgs extends ValidWalletSignerArgs {
type?: Base64String;
serialNumber?: Base64String;
certifier?: PubKeyHex;
subject?: PubKeyHex;
revocationOutpoint?: OutpointString;
signature?: HexString;
fieldsToReveal: CertificateFieldNameUnder50Bytes[];
verifier: PubKeyHex;
privileged: boolean;
privilegedReason?: DescriptionString5to50Bytes;
}
/**
* Validate ProveCertificateArgs including optional certificate fields and reveal list.
*
* @param args - ProveCertificateArgs
* @returns ValidProveCertificateArgs
*/
export declare function validateProveCertificateArgs(args: ProveCertificateArgs): ValidProveCertificateArgs;
export interface ValidDiscoverByIdentityKeyArgs extends ValidWalletSignerArgs {
identityKey: PubKeyHex;
limit: PositiveIntegerDefault10Max10000;
offset: PositiveIntegerOrZero;
seekPermission: boolean;
}
/**
* Validate DiscoverByIdentityKeyArgs, enforcing identity key length and defaults.
*
* @param args - DiscoverByIdentityKeyArgs
* @returns ValidDiscoverByIdentityKeyArgs
*/
export declare function validateDiscoverByIdentityKeyArgs(args: DiscoverByIdentityKeyArgs): ValidDiscoverByIdentityKeyArgs;
export interface ValidDiscoverByAttributesArgs extends ValidWalletSignerArgs {
attributes: Record<CertificateFieldNameUnder50Bytes, string>;
limit: PositiveIntegerDefault10Max10000;
offset: PositiveIntegerOrZero;
seekPermission: boolean;
}
/**
* Validate DiscoverByAttributesArgs: attributes, limit, offset, and permission flag.
*
* @param args - DiscoverByAttributesArgs
* @returns ValidDiscoverByAttributesArgs
*/
export declare function validateDiscoverByAttributesArgs(args: DiscoverByAttributesArgs): ValidDiscoverByAttributesArgs;
export interface ValidListOutputsArgs extends ValidWalletSignerArgs {
basket: BasketStringUnder300Bytes;
tags: OutputTagStringUnder300Bytes[];
tagQueryMode: 'all' | 'any';
includeLockingScripts: boolean;
includeTransactions: boolean;
includeCustomInstructions: BooleanDefaultFalse;
includeTags: BooleanDefaultFalse;
includeLabels: BooleanDefaultFalse;
limit: PositiveIntegerDefault10Max10000;
offset: number;
seekPermission: BooleanDefaultTrue;
knownTxids: string[];
}
/**
* @param {BasketStringUnder300Bytes} args.basket - Required. The associated basket name whose outputs should be listed.
* @param {OutputTagStringUnder300Bytes[]} [args.tags] - Optional. Filter outputs based on these tags.
* @param {'all' | 'any'} [args.tagQueryMode] - Optional. Filter mode, defining whether all or any of the tags must match. By default, any tag can match.
* @param {'locking scripts' | 'entire transactions'} [args.include] - Optional. 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} [args.includeEntireTransactions] - Optional. Whether to include the entire transaction(s) in the result.
* @param {BooleanDefaultFalse} [args.includeCustomInstructions] - Optional. Whether custom instructions should be returned in the result.
* @param {BooleanDefaultFalse} [args.includeTags] - Optional. Whether the tags associated with the output should be returned.
* @param {BooleanDefaultFalse} [args.includeLabels] - Optional. Whether the labels associated with the transaction containing the output should be returned.
* @param {PositiveIntegerDefault10Max10000} [args.limit] - Optional limit on the number of outputs to return.
* @param {number} [args.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} [args.seekPermission] — Optional. 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 declare function validateListOutputsArgs(args: ListOutputsArgs): ValidListOutputsArgs;
export interface ValidListActionsArgs extends ValidWalletSignerArgs {
labels: LabelStringUnder300Bytes[];
labelQueryMode: 'any' | 'all';
includeLabels: BooleanDefaultFalse;
includeInputs: BooleanDefaultFalse;
includeInputSourceLockingScripts: BooleanDefaultFalse;
includeInputUnlockingScripts: BooleanDefaultFalse;
includeOutputs: BooleanDefaultFalse;
includeOutputLockingScripts: BooleanDefaultFalse;
limit: PositiveIntegerDefault10Max10000;
offset: PositiveIntegerOrZero;
seekPermission: BooleanDefaultTrue;
}
/**
* @param {LabelStringUnder300Bytes[]} args.labels - An array of labels used to filter actions.
* @param {'any' | 'all'} [args.labelQueryMode] - Optional. Specifies how to match labels (default is any which matches any of the labels).
* @param {BooleanDefaultFalse} [args.includeLabels] - Optional. Whether to include transaction labels in the result set.
* @param {BooleanDefaultFalse} [args.includeInputs] - Optional. Whether to include input details in the result set.
* @param {BooleanDefaultFalse} [args.includeInputSourceLockingScripts] - Optional. Whether to include input source locking scripts in the result set.
* @param {BooleanDefaultFalse} [args.includeInputUnlockingScripts] - Optional. Whether to include input unlocking scripts in the result set.
* @param {BooleanDefaultFalse} [args.includeOutputs] - Optional. Whether to include output details in the result set.
* @param {BooleanDefaultFalse} [args.includeOutputLockingScripts] - Optional. Whether to include output locking scripts in the result set.
* @param {PositiveIntegerDefault10Max10000} [args.limit] - Optional. The maximum number of transactions to retrieve.
* @param {PositiveIntegerOrZero} [args.offset] - Optional. Number of transactions to skip before starting to return the results.
* @param {BooleanDefaultTrue} [args.seekPermission] — Optional. 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 declare function validateListActionsArgs(args: ListActionsArgs): ValidListActionsArgs;
/**
* Identifies a unique transaction output by its `txid` and index `vout`
*/
export interface OutPoint {
/**
* Transaction double sha256 hash as big endian hex string
*/
txid: string;
/**
* zero based output index within the transaction
*/
vout: number;
}
/**
* `createAction` special operation label name value.
*
* Causes WERR_REVIEW_ACTIONS throw with dummy properties.
*
*/
export declare const specOpThrowReviewActions = "a496e747fc3ad5fabdd4ae8f91184e71f87539bd3d962aa2548942faaaf0047a";
//# sourceMappingURL=validationHelpers.d.ts.map