Documentation / @xo-cash/primitives

@xo-cash/primitives

XO primitives

⚠️ This project is in early development phase. Use it only if you understand what you are doing and accept the risks. Do not use funds you are not willing to lose. Minor version bumps may introduce breaking changes

Package Philosophy

Each primitive validates its input in the constructor and throws immediately if the value is invalid. Once an instance exists, it is guaranteed to be valid and can be used anywhere without re-checking.

Primitives only validate inputs and transform values between formats. They do not contain business logic.

Installation

bash

npm install @xo-cash/primitives

Usage

typescript

import { PublicKey, PrivateKey } from '@xo-cash/primitives';

License

MIT

CommitIdentifier

Defined in: source/commit-identifier.ts:26

Commit Identifier Primitive. Validates and wraps the COMMIT_IDENTIFIER_BYTE_LENGTH byte commit identifier, which is generated as COMMIT_IDENTIFIER_BYTE_LENGTH random bytes when a new invitation commit is created.

typescript

import { CommitIdentifier } from '@xo-cash/primitives';

const id = new CommitIdentifier('a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6').toHex();

Constructors

Constructor

new CommitIdentifier(commitIdentifier): CommitIdentifier;

Defined in: primitives/dist/index.d.mts:29

Construct a new Commit Identifier Primitive. Validates that the input encodes exactly COMMIT_IDENTIFIER_BYTE_LENGTH bytes and is valid hexadecimal.

Parameters

Parameter	Type	Description
`commitIdentifier`	`string` \| `Uint8Array`<`ArrayBufferLike`>	The commit identifier as bytes or a COMMIT_IDENTIFIER_HEX_LENGTH-character hex string.

Returns

CommitIdentifier

Throws

CommitIdentifierInvalidInputTypeError If input type is not Uint8Array or string.

Throws

CommitIdentifierByteLengthInvalidError If the Uint8Array is not exactly COMMIT_IDENTIFIER_BYTE_LENGTH bytes.

Throws

CommitIdentifierHexLengthInvalidError If the string is not exactly COMMIT_IDENTIFIER_HEX_LENGTH characters.

Throws

CommitIdentifierHexFormatInvalidError If the string contains non-hexadecimal characters.

Methods

equals()

equals(other): boolean;

Defined in: source/commit-identifier.ts:151

Check if this commit identifier equals another commit identifier.

Parameters

Parameter	Type	Description
`other`	`CommitIdentifier`	The other commit identifier to compare.

Returns

boolean

True if both encode the same COMMIT_IDENTIFIER_BYTE_LENGTH bytes, false otherwise.

Throws

InvalidInstanceError If other is not a CommitIdentifier instance.

toBytes()

toBytes(): Uint8Array;

Defined in: source/commit-identifier.ts:140

Transform: Bytes representation of this commit identifier.

Returns

Uint8Array

A copy of the COMMIT_IDENTIFIER_BYTE_LENGTH byte identifier.

toHex()

toHex(): string;

Defined in: source/commit-identifier.ts:131

Transform: Hex representation of this commit identifier.

Returns

string

The COMMIT_IDENTIFIER_HEX_LENGTH-character hex string.

fromBytes()

static fromBytes(value): CommitIdentifier;

Defined in: source/commit-identifier.ts:65

Construct a CommitIdentifier from a Uint8Array.

Parameters

Parameter	Type	Description
`value`	`Uint8Array`	The commit identifier as a COMMIT_IDENTIFIER_BYTE_LENGTH byte Uint8Array.

Returns

CommitIdentifier

A new CommitIdentifier instance.

Throws

CommitIdentifierByteLengthInvalidError If the array is not exactly COMMIT_IDENTIFIER_BYTE_LENGTH bytes.

fromString()

static fromString(value): CommitIdentifier;

Defined in: source/commit-identifier.ts:54

Construct a CommitIdentifier from a hex string.

Parameters

Parameter	Type	Description
`value`	`string`	The commit identifier as a hex string.

Returns

CommitIdentifier

A new CommitIdentifier instance.

Throws

CommitIdentifierHexLengthInvalidError If the string is not COMMIT_IDENTIFIER_HEX_LENGTH characters.

Throws

CommitIdentifierHexFormatInvalidError If the string contains non-hex characters.

CommitIdentifierAllZeroesError

Defined in: source/errors.ts:597

Error thrown when a commit identifier consists entirely of zero bytes, indicating a suspected placeholder value.

Extends

Error

Constructors

Constructor

new CommitIdentifierAllZeroesError(): CommitIdentifierAllZeroesError;

Defined in: source/errors.ts:597

Returns

CommitIdentifierAllZeroesError

Overrides

Error.constructor

CommitIdentifierByteLengthInvalidError

Defined in: source/errors.ts:561

Error thrown when a Uint8Array commit identifier is not exactly COMMIT_IDENTIFIER_BYTE_LENGTH bytes.

Extends

Error

Constructors

Constructor

new CommitIdentifierByteLengthInvalidError(receivedByteLength): CommitIdentifierByteLengthInvalidError;

Defined in: primitives/dist/index.d.mts:423

Parameters

Parameter	Type
`receivedByteLength`	`number`

Returns

CommitIdentifierByteLengthInvalidError

Overrides

Error.constructor

CommitIdentifierHexFormatInvalidError

Defined in: source/errors.ts:585

Error thrown when a string commit identifier is the correct length but contains non-hex characters.

Extends

Error

Constructors

Constructor

new CommitIdentifierHexFormatInvalidError(): CommitIdentifierHexFormatInvalidError;

Defined in: source/errors.ts:585

Returns

CommitIdentifierHexFormatInvalidError

Overrides

Error.constructor

CommitIdentifierHexLengthInvalidError

Defined in: source/errors.ts:573

Error thrown when a string commit identifier is not exactly COMMIT_IDENTIFIER_HEX_LENGTH characters.

Extends

Error

Constructors

Constructor

new CommitIdentifierHexLengthInvalidError(receivedLength): CommitIdentifierHexLengthInvalidError;

Defined in: primitives/dist/index.d.mts:431

Parameters

Parameter	Type
`receivedLength`	`number`

Returns

CommitIdentifierHexLengthInvalidError

Overrides

Error.constructor

CommitIdentifierInvalidInputTypeError

Defined in: source/errors.ts:549

Error thrown when a commit identifier input is not a Uint8Array or string.

Extends

Error

Constructors

Constructor

new CommitIdentifierInvalidInputTypeError(receivedType): CommitIdentifierInvalidInputTypeError;

Defined in: primitives/dist/index.d.mts:415

Parameters

Parameter	Type
`receivedType`	`string`

Returns

CommitIdentifierInvalidInputTypeError

Overrides

Error.constructor

CommitIdentifierMaximumError

Defined in: source/errors.ts:609

Error thrown when a commit identifier consists entirely of 0xFF bytes, indicating a suspected placeholder value.

Extends

Error

Constructors

Constructor

new CommitIdentifierMaximumError(): CommitIdentifierMaximumError;

Defined in: source/errors.ts:609

Returns

CommitIdentifierMaximumError

Overrides

Error.constructor

COMMIT_IDENTIFIER_BYTE_LENGTH

const COMMIT_IDENTIFIER_BYTE_LENGTH: 16 = 16;

Defined in: source/defaults.ts:124

Byte length of a commit identifier.

COMMIT_IDENTIFIER_HEX_LENGTH

const COMMIT_IDENTIFIER_HEX_LENGTH: number;

Defined in: source/defaults.ts:131

Character length of a commit identifier hex string.

ExtendedPublicKey

Defined in: source/extended-public-key.ts:22

Extended Public Key Primitive. Validates and wraps a BIP32 extended public key string (xpub on mainnet, tpub on testnet). Used as invitation entity identifiers and anywhere an HD public key must be carried as an encoded string.

typescript

import { ExtendedPublicKey } from '@xo-cash/primitives';

const xpub = new ExtendedPublicKey(extendedPublicKeyString).toString();

Constructors

Constructor

new ExtendedPublicKey(extendedPublicKey, network?): ExtendedPublicKey;

Defined in: primitives/dist/index.d.mts:579

Construct a new Extended Public Key primitive. Validates that the input decodes to an HD public key on the expected network.

Parameters

Parameter	Type	Description
`extendedPublicKey`	`string` \| `Uint8Array`<`ArrayBufferLike`>	Extended public key as 78 byte BIP32 payload bytes or a Base58Check string (xpub or tpub).
`network?`	`HdKeyNetwork`	Expected network for this key. Defaults to 'mainnet'.

Returns

ExtendedPublicKey

Throws

ExtendedPublicKeyInvalidInputTypeError If input type is not a Uint8Array or string.

Throws

ExtendedPublicKeyInvalidError If the input is not a valid extended public key.

Throws

ExtendedPublicKeyNetworkMismatchError If the key's encoded network does not match the expected network.

Methods

equals()

equals(other): boolean;

Defined in: source/extended-public-key.ts:129

Check if this extended public key equals another extended public key.

Parameters

Parameter	Type	Description
`other`	`ExtendedPublicKey`	The other extended public key to compare.

Returns

boolean

True if the extended public keys are equal, false otherwise.

Throws

InvalidInstanceError If the other argument is not an ExtendedPublicKey instance.

toBytes()

toBytes(): Uint8Array;

Defined in: source/extended-public-key.ts:108

Transform: Bytes representation of the 78 byte BIP32 payload.

Returns

Uint8Array

The BIP32 payload bytes.

toString()

toString(): string;

Defined in: source/extended-public-key.ts:118

Transform: Base58Check extended public key string (xpub or tpub).

Returns

string

Base58Check extended public key string.

fromBytes()

static fromBytes(value, network?): ExtendedPublicKey;

Defined in: source/extended-public-key.ts:63

Construct an ExtendedPublicKey from a 78 byte BIP32 payload.

Parameters

Parameter	Type	Description
`value`	`Uint8Array`	The 78 byte BIP32 payload bytes.
`network?`	`HdKeyNetwork`	Expected network for this key. Defaults to 'mainnet'.

Returns

ExtendedPublicKey

A new ExtendedPublicKey instance.

Throws

ExtendedPublicKeyInvalidError If the bytes do not encode a valid extended public key.

Throws

ExtendedPublicKeyNetworkMismatchError If the key's encoded network does not match the expected network.

fromString()

static fromString(value, network?): ExtendedPublicKey;

Defined in: source/extended-public-key.ts:50

Construct an ExtendedPublicKey from a Base58Check string (xpub or tpub).

Parameters

Parameter	Type	Description
`value`	`string`	The Base58Check extended public key string.
`network?`	`HdKeyNetwork`	Expected network for this key. Defaults to 'mainnet'.

Returns

ExtendedPublicKey

A new ExtendedPublicKey instance.

Throws

ExtendedPublicKeyInvalidError If the string is not a valid extended public key.

Throws

ExtendedPublicKeyNetworkMismatchError If the key's encoded network does not match the expected network.

ExtendedPublicKeyInvalidError

Defined in: source/errors.ts:90

Error thrown when extended public key decoding fails.

Extends

Error

Constructors

Constructor

new ExtendedPublicKeyInvalidError(reason): ExtendedPublicKeyInvalidError;

Defined in: primitives/dist/index.d.mts:109

Parameters

Parameter	Type
`reason`	`string`

Returns

ExtendedPublicKeyInvalidError

Overrides

Error.constructor

ExtendedPublicKeyInvalidInputTypeError

Defined in: source/errors.ts:78

Error thrown when extended public key input type is invalid.

Extends

Error

Constructors

Constructor

new ExtendedPublicKeyInvalidInputTypeError(receivedType): ExtendedPublicKeyInvalidInputTypeError;

Defined in: primitives/dist/index.d.mts:101

Parameters

Parameter	Type
`receivedType`	`string`

Returns

ExtendedPublicKeyInvalidInputTypeError

Overrides

Error.constructor

ExtendedPublicKeyNetworkMismatchError

Defined in: source/errors.ts:102

Error thrown when the network encoded in the extended public key does not match the expected network.

Extends

Error

Constructors

Constructor

new ExtendedPublicKeyNetworkMismatchError(expectedNetwork, receivedNetwork): ExtendedPublicKeyNetworkMismatchError;

Defined in: primitives/dist/index.d.mts:117

Parameters

Parameter	Type
`expectedNetwork`	`string`
`receivedNetwork`	`string`

Returns

ExtendedPublicKeyNetworkMismatchError

Overrides

Error.constructor

FungibleTokenAmount

Defined in: source/fungible-token-amount.ts:24

Fungible Token Amount Primitive. Validates and wraps a fungible token amount. Accepts bigint or string and ensures the value is a non-negative integer within [0, MAX_FUNGIBLE_TOKEN_AMOUNT]. Provides arithmetic and comparison operations, each returning a new instance.

typescript

import { FungibleTokenAmount } from '@xo-cash/primitives';

const tokenAmount = new FungibleTokenAmount('1000').toBigInt();

Constructors

Constructor

new FungibleTokenAmount(amount): FungibleTokenAmount;

Defined in: primitives/dist/index.d.mts:649

Construct a new Fungible Token Amount Primitive. Validates that the provided value is in range [0, MAX_FUNGIBLE_TOKEN_AMOUNT].

Parameters

Parameter	Type	Description
`amount`	`string` \| `bigint`	The provided fungible token amount.

Throws

FungibleTokenAmountInvalidStringError If string is not a plain decimal integer.

Throws

FungibleTokenAmountOutOfRangeError If the value is outside [0, MAX_FUNGIBLE_TOKEN_AMOUNT].

Methods

add()

add(other): FungibleTokenAmount;

Defined in: source/fungible-token-amount.ts:152

Add another FungibleTokenAmount to this instance and return a new instance with the result.

Parameters

Parameter	Type	Description
`other`	`FungibleTokenAmount`	The amount to add.

Returns

FungibleTokenAmount

A new instance representing the sum.

Throws

InvalidInstanceError If other is not a FungibleTokenAmount instance.

Throws

FungibleTokenAmountOutOfRangeError If the sum exceeds MAX_FUNGIBLE_TOKEN_AMOUNT.

equals()

equals(other): boolean;

Defined in: source/fungible-token-amount.ts:183

Check if this equals another FungibleTokenAmount.

Parameters

Parameter	Type	Description
`other`	`FungibleTokenAmount`	The other amount to compare.

Returns

boolean

True if equal, false otherwise.

Throws

InvalidInstanceError If other is not a FungibleTokenAmount instance.

greaterThan()

greaterThan(other): boolean;

Defined in: source/fungible-token-amount.ts:228

Check if this is greater than another FungibleTokenAmount.

Parameters

Parameter	Type	Description
`other`	`FungibleTokenAmount`	The other amount to compare.

Returns

boolean

True if this > other, false otherwise.

Throws

InvalidInstanceError If other is not a FungibleTokenAmount instance.

greaterThanOrEqual()

greaterThanOrEqual(other): boolean;

Defined in: source/fungible-token-amount.ts:243

Check if this is greater than or equal to another FungibleTokenAmount.

Parameters

Parameter	Type	Description
`other`	`FungibleTokenAmount`	The other amount to compare.

Returns

boolean

True if this >= other, false otherwise.

Throws

InvalidInstanceError If other is not a FungibleTokenAmount instance.

lessThan()

lessThan(other): boolean;

Defined in: source/fungible-token-amount.ts:198

Check if this is less than another FungibleTokenAmount.

Parameters

Parameter	Type	Description
`other`	`FungibleTokenAmount`	The other amount to compare.

Returns

boolean

True if this < other, false otherwise.

Throws

InvalidInstanceError If other is not a FungibleTokenAmount instance.

lessThanOrEqual()

lessThanOrEqual(other): boolean;

Defined in: source/fungible-token-amount.ts:213

Check if this is less than or equal to another FungibleTokenAmount.

Parameters

Parameter	Type	Description
`other`	`FungibleTokenAmount`	The other amount to compare.

Returns

boolean

True if this <= other, false otherwise.

Throws

InvalidInstanceError If other is not a FungibleTokenAmount instance.

subtract()

subtract(other): FungibleTokenAmount;

Defined in: source/fungible-token-amount.ts:168

Subtract another FungibleTokenAmount from this instance and return a new instance with the result.

Parameters

Parameter	Type	Description
`other`	`FungibleTokenAmount`	The amount to subtract.

Returns

FungibleTokenAmount

A new instance representing the difference.

Throws

InvalidInstanceError If other is not a FungibleTokenAmount instance.

Throws

FungibleTokenAmountOutOfRangeError If the result would be negative.

toBigInt()

toBigInt(): bigint;

Defined in: source/fungible-token-amount.ts:131

Transform: The fungible token amount as a bigint.

Returns

bigint

The amount as a bigint.

toString()

toString(): string;

Defined in: source/fungible-token-amount.ts:140

Transform: The fungible token amount as a string.

Returns

string

The decimal string representation.

fromBigInt()

static fromBigInt(value): FungibleTokenAmount;

Defined in: source/fungible-token-amount.ts:52

Construct a FungibleTokenAmount from a bigint value.

Parameters

Parameter	Type	Description
`value`	`bigint`	The fungible token amount as a bigint.

Returns

FungibleTokenAmount

A new FungibleTokenAmount instance.

Throws

FungibleTokenAmountOutOfRangeError If value is outside [0, MAX_FUNGIBLE_TOKEN_AMOUNT].

fromString()

static fromString(value): FungibleTokenAmount;

Defined in: source/fungible-token-amount.ts:65

Construct a FungibleTokenAmount from a decimal integer string.

Parameters

Parameter	Type	Description
`value`	`string`	The fungible token amount as a decimal integer string.

Returns

FungibleTokenAmount

A new FungibleTokenAmount instance.

Throws

FungibleTokenAmountStringTooLongError If string exceeds MAX_FUNGIBLE_TOKEN_AMOUNT_STRING_LENGTH.

Throws

FungibleTokenAmountInvalidStringError If string is not a plain decimal integer.

Throws

FungibleTokenAmountOutOfRangeError If value exceeds MAX_FUNGIBLE_TOKEN_AMOUNT.

FungibleTokenAmountInvalidInputTypeError

Defined in: source/errors.ts:321

Error thrown when a fungible token amount input is not a bigint or string.

Extends

Error

Constructors

Constructor

new FungibleTokenAmountInvalidInputTypeError(receivedType): FungibleTokenAmountInvalidInputTypeError;

Defined in: primitives/dist/index.d.mts:263

Parameters

Parameter	Type
`receivedType`	`string`

Returns

FungibleTokenAmountInvalidInputTypeError

Overrides

Error.constructor

FungibleTokenAmountInvalidStringError

Defined in: source/errors.ts:345

Error thrown when a fungible token amount provided as a string does not resolve to a non-negative integer.

Extends

Error

Constructors

Constructor

new FungibleTokenAmountInvalidStringError(receivedString): FungibleTokenAmountInvalidStringError;

Defined in: primitives/dist/index.d.mts:279

Parameters

Parameter	Type
`receivedString`	`string`

Returns

FungibleTokenAmountInvalidStringError

Overrides

Error.constructor

FungibleTokenAmountOutOfRangeError

Defined in: source/errors.ts:333

Error thrown when a fungible token amount is outside the range [0, MAX_FUNGIBLE_TOKEN_AMOUNT].

Extends

Error

Constructors

Constructor

new FungibleTokenAmountOutOfRangeError(value): FungibleTokenAmountOutOfRangeError;

Defined in: primitives/dist/index.d.mts:271

Parameters

Parameter	Type
`value`	`bigint`

Returns

FungibleTokenAmountOutOfRangeError

Overrides

Error.constructor

FungibleTokenAmountStringTooLongError

Defined in: source/errors.ts:357

Error thrown when a fungible token amount provided as a string exceeds the maximum allowed length.

Extends

Error

Constructors

Constructor

new FungibleTokenAmountStringTooLongError(receivedLength): FungibleTokenAmountStringTooLongError;

Defined in: primitives/dist/index.d.mts:287

Parameters

Parameter	Type
`receivedLength`	`number`

Returns

FungibleTokenAmountStringTooLongError

Overrides

Error.constructor

FUNGIBLE_TOKEN_AMOUNT_DECIMAL_STRING_PATTERN

const FUNGIBLE_TOKEN_AMOUNT_DECIMAL_STRING_PATTERN: RegExp;

Defined in: source/defaults.ts:43

Same pattern as DECIMAL_INTEGER_STRING_PATTERN. Used to validate fungible token amount string inputs.

MAX_FUNGIBLE_TOKEN_AMOUNT

const MAX_FUNGIBLE_TOKEN_AMOUNT: 9223372036854775807n = 9223372036854775807n;

Defined in: source/defaults.ts:78

Maximum fungible token amount. Equals 2^63 - 1.

MAX_FUNGIBLE_TOKEN_AMOUNT_STRING_LENGTH

const MAX_FUNGIBLE_TOKEN_AMOUNT_STRING_LENGTH: number;

Defined in: source/defaults.ts:86

Maximum length of the string representation of the maximum fungible token amount. Used to reject oversized strings before pattern validation.

InvitationIdentifier

Defined in: source/invitation-identifier.ts:26

Invitation Identifier Primitive. Validates and wraps the INVITATION_IDENTIFIER_BYTE_LENGTH byte invitation identifier, which is generated as INVITATION_IDENTIFIER_BYTE_LENGTH random bytes when a new invitation is created.

typescript

import { InvitationIdentifier } from '@xo-cash/primitives';

const id = new InvitationIdentifier('a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6').toHex();

Constructors

Constructor

new InvitationIdentifier(invitationIdentifier): InvitationIdentifier;

Defined in: primitives/dist/index.d.mts:767

Construct a new Invitation Identifier Primitive. Validates that the input encodes exactly INVITATION_IDENTIFIER_BYTE_LENGTH bytes and, for string inputs, that all characters are valid hexadecimal.

Parameters

Parameter	Type	Description
`invitationIdentifier`	`string` \| `Uint8Array`<`ArrayBufferLike`>	The invitation identifier as bytes or a INVITATION_IDENTIFIER_HEX_LENGTH-character hex string.

Returns

InvitationIdentifier

Throws

InvitationIdentifierInvalidInputTypeError If input type is not Uint8Array or string.

Throws

InvitationIdentifierByteLengthInvalidError If the Uint8Array is not exactly INVITATION_IDENTIFIER_BYTE_LENGTH bytes.

Throws

InvitationIdentifierHexLengthInvalidError If the string is not exactly INVITATION_IDENTIFIER_HEX_LENGTH characters.

Throws

InvitationIdentifierHexFormatInvalidError If the string contains non-hexadecimal characters.

Methods

equals()

equals(other): boolean;

Defined in: source/invitation-identifier.ts:152

Check if this invitation identifier equals another invitation identifier.

Parameters

Parameter	Type	Description
`other`	`InvitationIdentifier`	The other invitation identifier to compare.

Returns

boolean

True if both encode the same INVITATION_IDENTIFIER_BYTE_LENGTH bytes, false otherwise.

Throws

InvalidInstanceError If other is not an InvitationIdentifier instance.

toBytes()

toBytes(): Uint8Array;

Defined in: source/invitation-identifier.ts:141

Transform: Bytes representation of this invitation identifier.

Returns

Uint8Array

A copy of the INVITATION_IDENTIFIER_BYTE_LENGTH byte identifier.

toHex()

toHex(): string;

Defined in: source/invitation-identifier.ts:132

Transform: Hex representation of this invitation identifier.

Returns

string

The INVITATION_IDENTIFIER_HEX_LENGTH-character hex string.

fromBytes()

static fromBytes(value): InvitationIdentifier;

Defined in: source/invitation-identifier.ts:66

Construct an InvitationIdentifier from a Uint8Array.

Parameters

Parameter	Type	Description
`value`	`Uint8Array`	The invitation identifier as a INVITATION_IDENTIFIER_BYTE_LENGTH byte Uint8Array.

Returns

InvitationIdentifier

A new InvitationIdentifier instance.

Throws

InvitationIdentifierByteLengthInvalidError If the array is not exactly INVITATION_IDENTIFIER_BYTE_LENGTH bytes.

fromString()

static fromString(value): InvitationIdentifier;

Defined in: source/invitation-identifier.ts:55

Construct an InvitationIdentifier from a INVITATION_IDENTIFIER_HEX_LENGTH-character hex string.

Parameters

Parameter	Type	Description
`value`	`string`	The invitation identifier as a INVITATION_IDENTIFIER_HEX_LENGTH-character hex string.

Returns

InvitationIdentifier

A new InvitationIdentifier instance.

Throws

InvitationIdentifierHexLengthInvalidError If the string is not INVITATION_IDENTIFIER_HEX_LENGTH characters.

Throws

InvitationIdentifierHexFormatInvalidError If the string contains non-hex characters.

InvitationIdentifierAllZeroesError

Defined in: source/errors.ts:669

Error thrown when an invitation identifier consists entirely of zero bytes, indicating a suspected placeholder value.

Extends

Error

Constructors

Constructor

new InvitationIdentifierAllZeroesError(): InvitationIdentifierAllZeroesError;

Defined in: source/errors.ts:669

Returns

InvitationIdentifierAllZeroesError

Overrides

Error.constructor

InvitationIdentifierByteLengthInvalidError

Defined in: source/errors.ts:633

Error thrown when a Uint8Array invitation identifier is not exactly INVITATION_IDENTIFIER_BYTE_LENGTH bytes.

Extends

Error

Constructors

Constructor

new InvitationIdentifierByteLengthInvalidError(receivedByteLength): InvitationIdentifierByteLengthInvalidError;

Defined in: primitives/dist/index.d.mts:471

Parameters

Parameter	Type
`receivedByteLength`	`number`

Returns

InvitationIdentifierByteLengthInvalidError

Overrides

Error.constructor

InvitationIdentifierHexFormatInvalidError

Defined in: source/errors.ts:657

Error thrown when a string invitation identifier is the correct length but contains non-hex characters.

Extends

Error

Constructors

Constructor

new InvitationIdentifierHexFormatInvalidError(): InvitationIdentifierHexFormatInvalidError;

Defined in: source/errors.ts:657

Returns

InvitationIdentifierHexFormatInvalidError

Overrides

Error.constructor

InvitationIdentifierHexLengthInvalidError

Defined in: source/errors.ts:645

Error thrown when a string invitation identifier is not exactly INVITATION_IDENTIFIER_HEX_LENGTH characters.

Extends

Error

Constructors

Constructor

new InvitationIdentifierHexLengthInvalidError(receivedLength): InvitationIdentifierHexLengthInvalidError;

Defined in: primitives/dist/index.d.mts:479

Parameters

Parameter	Type
`receivedLength`	`number`

Returns

InvitationIdentifierHexLengthInvalidError

Overrides

Error.constructor

InvitationIdentifierInvalidInputTypeError

Defined in: source/errors.ts:621

Error thrown when an invitation identifier input is not a Uint8Array or string.

Extends

Error

Constructors

Constructor

new InvitationIdentifierInvalidInputTypeError(receivedType): InvitationIdentifierInvalidInputTypeError;

Defined in: primitives/dist/index.d.mts:463

Parameters

Parameter	Type
`receivedType`	`string`

Returns

InvitationIdentifierInvalidInputTypeError

Overrides

Error.constructor

InvitationIdentifierMaximumError

Defined in: source/errors.ts:681

Error thrown when an invitation identifier consists entirely of 0xFF bytes, indicating a suspected placeholder value.

Extends

Error

Constructors

Constructor

new InvitationIdentifierMaximumError(): InvitationIdentifierMaximumError;

Defined in: source/errors.ts:681

Returns

InvitationIdentifierMaximumError

Overrides

Error.constructor

INVITATION_IDENTIFIER_BYTE_LENGTH

const INVITATION_IDENTIFIER_BYTE_LENGTH: 16 = 16;

Defined in: source/defaults.ts:138

Byte length of an invitation identifier.

INVITATION_IDENTIFIER_HEX_LENGTH

const INVITATION_IDENTIFIER_HEX_LENGTH: number;

Defined in: source/defaults.ts:145

Character length of an invitation identifier hex string.

NFTCommitment

Defined in: source/nft-commitment.ts:25

NFT Commitment Primitive. Validates and wraps the commitment data field of a non-fungible token. Accepts a Uint8Array or a hex string. The maximum accepted length is NFT_COMMITMENT_MAX_BYTE_LENGTH bytes.

typescript

import { NFTCommitment } from '@xo-cash/primitives';

// The constructor validates the commitment, so no additional type checking is needed before building outputs.
for (const output of outputs) {
   if (output.token?.nft !== undefined) {
       const commitment = new NFTCommitment(output.token.nft.commitment);
       transactionOutputs.push({ ...output, token: { ...output.token, nft: { commitment: commitment.toBytes() } } });
   }
}

Constructors

Constructor

new NFTCommitment(commitment): NFTCommitment;

Defined in: primitives/dist/index.d.mts:839

Construct a new NFT Commitment Primitive. Validates that the input encodes at most NFT_COMMITMENT_MAX_BYTE_LENGTH bytes, and that string inputs are valid hex.

Parameters

Parameter	Type	Description
`commitment`	`string` \| `Uint8Array`<`ArrayBufferLike`>	The commitment data as bytes (Uint8Array) or a hex string.

Returns

NFTCommitment

Throws

NFTCommitmentInvalidInputTypeError If input type is not Uint8Array or string.

Throws

NFTCommitmentInvalidError If the string contains non-hex characters.

Throws

NFTCommitmentTooLongError If the input exceeds NFT_COMMITMENT_MAX_BYTE_LENGTH bytes.

Methods

equals()

equals(other): boolean;

Defined in: source/nft-commitment.ts:133

Check if this commitment equals another commitment.

Parameters

Parameter	Type	Description
`other`	`NFTCommitment`	The other commitment to compare.

Returns

boolean

True if both encode the same bytes, false otherwise.

Throws

InvalidInstanceError If other is not an NFTCommitment instance.

toBytes()

toBytes(): Uint8Array;

Defined in: source/nft-commitment.ts:121

Transform: Bytes representation of this commitment.

Returns

Uint8Array

A copy of the commitment bytes.

toHex()

toHex(): string;

Defined in: source/nft-commitment.ts:112

Transform: Hex representation of this commitment.

Returns

string

The hex string. Returns an empty string for a zero byte commitment.

fromBytes()

static fromBytes(value): NFTCommitment;

Defined in: source/nft-commitment.ts:64

Construct an NFTCommitment from a Uint8Array.

Parameters

Parameter	Type	Description
`value`	`Uint8Array`	The commitment data as bytes.

Returns

NFTCommitment

A new NFTCommitment instance.

Throws

NFTCommitmentTooLongError If the array exceeds NFT_COMMITMENT_MAX_BYTE_LENGTH bytes.

fromString()

static fromString(value): NFTCommitment;

Defined in: source/nft-commitment.ts:53

Construct an NFTCommitment from a hex string.

Parameters

Parameter	Type	Description
`value`	`string`	The commitment data as a hex string. An empty string produces a zero byte commitment.

Returns

NFTCommitment

A new NFTCommitment instance.

Throws

NFTCommitmentInvalidInputTypeError If value is not a string.

Throws

NFTCommitmentInvalidError If the string contains non-hex characters.

Throws

NFTCommitmentTooLongError If the decoded bytes exceed NFT_COMMITMENT_MAX_BYTE_LENGTH bytes.

NFTCommitmentInvalidError

Defined in: source/errors.ts:381

Error thrown when an NFT commitment string input contains non-hex characters.

Extends

Error

Constructors

Constructor

new NFTCommitmentInvalidError(): NFTCommitmentInvalidError;

Defined in: source/errors.ts:381

Returns

NFTCommitmentInvalidError

Overrides

Error.constructor

NFTCommitmentInvalidInputTypeError

Defined in: source/errors.ts:369

Error thrown when an NFT commitment input is not a Uint8Array or string.

Extends

Error

Constructors

Constructor

new NFTCommitmentInvalidInputTypeError(receivedType): NFTCommitmentInvalidInputTypeError;

Defined in: primitives/dist/index.d.mts:295

Parameters

Parameter	Type
`receivedType`	`string`

Returns

NFTCommitmentInvalidInputTypeError

Overrides

Error.constructor

NFTCommitmentTooLongError

Defined in: source/errors.ts:393

Error thrown when an NFT commitment exceeds the maximum allowed byte length.

Extends

Error

Constructors

Constructor

new NFTCommitmentTooLongError(receivedLength): NFTCommitmentTooLongError;

Defined in: primitives/dist/index.d.mts:311

Parameters

Parameter	Type
`receivedLength`	`number`

Returns

NFTCommitmentTooLongError

Overrides

Error.constructor

NFT_COMMITMENT_MAX_BYTE_LENGTH

const NFT_COMMITMENT_MAX_BYTE_LENGTH: 128 = 128;

Defined in: source/defaults.ts:64

Maximum byte length of an NFT commitment field.

NFT_COMMITMENT_MAX_HEX_LENGTH

const NFT_COMMITMENT_MAX_HEX_LENGTH: number;

Defined in: source/defaults.ts:71

Maximum character length of an NFT commitment hex string.

Other

WalletImportFormatType

type WalletImportFormatType = "mainnet" | "mainnetUncompressed" | "testnet" | "testnetUncompressed";

Defined in: crypto/node_modules/@bitauth/libauth/build/lib/key/wallet-import-format.d.ts:20

The network and address format in which a WIF-encoded private key is expected to be used.

WIF-encoding is generally used to encode private keys for Pay to Public Key (P2PKH) addresses – each WIF-encoded private key specifies the compression of the public key to use in the P2PKH address:

The values mainnet and testnet indicate that the address should use the compressed form of the derived public key (33 bytes, beginning with 0x02 or 0x03) on the respective network.
The less common mainnet-uncompressed and testnet-uncompressed values indicate that the address should use the uncompressed form of the public key (65 bytes beginning with 0x04) on the specified network.

PrivateKey

Defined in: source/private-key.ts:25

Private Key Primitive.

typescript

import { PrivateKey } from '@xo-cash/primitives';

const hex = new PrivateKey('privateKeyHex').toHex();

Constructors

Constructor

new PrivateKey(privateKey): PrivateKey;

Defined in: primitives/dist/index.d.mts:903

Construct a new Private Key Primitive, this automatically validates the private key. It is important to throw as soon as possible to avoid any confusion or unexpected behavior.

Parameters

Parameter	Type	Description
`privateKey`	`string` \| `Uint8Array`<`ArrayBufferLike`>	The private key as either bytes (Uint8Array) or string (hex/WIF).

Returns

PrivateKey

Throws

PrivateKeyInvalidError If private key is invalid.

Throws

PrivateKeyInvalidInputTypeError If private key input type is invalid.

Throws

WIFDecodeError If WIF string is malformed.

Methods

destroy()

destroy(): void;

Defined in: source/private-key.ts:207

Destroy the private key by zeroing the bytes and nulling the reference.

Returns

void

equals()

equals(externalPrivateKey): boolean;

Defined in: source/private-key.ts:188

Check if this private key equals another private key.

Parameters

Parameter	Type	Description
`externalPrivateKey`	`PrivateKey`	The other private key to compare.

Returns

boolean

True if the private keys are equal, false otherwise.

Throws

InvalidInstanceError If the other argument is not a PrivateKey instance.

Throws

PrivateKeyDestroyedError If internalPrivateKey or externalPrivateKey is destroyed.

isDestroyed()

isDestroyed(): boolean;

Defined in: source/private-key.ts:138

Check if the private key has been destroyed.

Returns

boolean

True if the private key has been destroyed, false otherwise.

toBytes()

toBytes(): Uint8Array;

Defined in: source/private-key.ts:160

Transform: Bytes representation of this private key.

Returns

Uint8Array

The bytes.

Throws

PrivateKeyDestroyedError If the private key has been destroyed.

toHex()

toHex(): string;

Defined in: source/private-key.ts:148

Transform: Hex representation of this private key.

Returns

string

The hex string.

Throws

PrivateKeyDestroyedError If the private key has been destroyed.

toWif()

toWif(type?): string;

Defined in: source/private-key.ts:174

Transform: WIF representation of this private key.

Parameters

Parameter	Type	Description
`type?`	`WalletImportFormatType`	The type of WIF.

Returns

string

The WIF string.

Throws

PrivateKeyDestroyedError If the private key has been destroyed.

fromBytes()

static fromBytes(value): PrivateKey;

Defined in: source/private-key.ts:75

Construct a PrivateKey from a Uint8Array.

Parameters

Parameter	Type	Description
`value`	`Uint8Array`	The 32 byte secp256k1 private key.

Returns

PrivateKey

A new PrivateKey instance.

Throws

PrivateKeyInvalidError If the bytes do not encode a valid secp256k1 private key.

fromString()

static fromString(value): PrivateKey;

Defined in: source/private-key.ts:64

Construct a PrivateKey from a hex or WIF string.

Parameters

Parameter	Type	Description
`value`	`string`	The private key as a hex string or WIF string.

Returns

PrivateKey

A new PrivateKey instance.

Throws

PrivateKeyInvalidError If the key value is invalid.

Throws

WIFDecodeError If the string looks like WIF but is malformed.

PrivateKeyDestroyedError

Defined in: source/errors.ts:115

Error thrown when an operation is attempted on a destroyed private key. The role indicates which key was destroyed (internalPrivateKey = this instance, externalPrivateKey = the other).

Extends

Error

Constructors

Constructor

new PrivateKeyDestroyedError(role?): PrivateKeyDestroyedError;

Defined in: primitives/dist/index.d.mts:126

Parameters

Parameter	Type
`role?`	`"internalPrivateKey"` \| `"externalPrivateKey"`

Returns

PrivateKeyDestroyedError

Overrides

Error.constructor

PrivateKeyInvalidError

Defined in: source/errors.ts:139

Error thrown when private key is invalid.

Extends

Error

Constructors

Constructor

new PrivateKeyInvalidError(): PrivateKeyInvalidError;

Defined in: source/errors.ts:139

Returns

PrivateKeyInvalidError

Overrides

Error.constructor

PrivateKeyInvalidInputTypeError

Defined in: source/errors.ts:127

Error thrown when private key input type is invalid.

Extends

Error

Constructors

Constructor

new PrivateKeyInvalidInputTypeError(receivedType): PrivateKeyInvalidInputTypeError;

Defined in: primitives/dist/index.d.mts:134

Parameters

Parameter	Type
`receivedType`	`string`

Returns

PrivateKeyInvalidInputTypeError

Overrides

Error.constructor

WIFDecodeError

Defined in: source/errors.ts:152

Error thrown when WIF decoding fails.

Extends

Error

Constructors

Constructor

new WIFDecodeError(reason): WIFDecodeError;

Defined in: primitives/dist/index.d.mts:150

Parameters

Parameter	Type
`reason`	`string`

Returns

WIFDecodeError

Overrides

Error.constructor

PublicKey

Defined in: source/public-key.ts:15

Public Key Primitive.

typescript

import { PublicKey } from '@xo-cash/primitives';

const hex = new PublicKey('publicKeyHex').toHex();

Constructors

Constructor

new PublicKey(publicKey): PublicKey;

Defined in: primitives/dist/index.d.mts:988

Construct a new Public Key Primitive, this automatically validates the public key. It is important to throw as soon as possible to avoid any confusion or unexpected behavior.

Parameters

Parameter	Type	Description
`publicKey`	`string` \| `Uint8Array`<`ArrayBufferLike`>	The public key as either bytes (Uint8Array) or string (hex).

Returns

PublicKey

Throws

PublicKeyInvalidError If public key is invalid.

Throws

PublicKeyInvalidInputTypeError If public key input type is invalid.

Methods

equals()

equals(other): boolean;

Defined in: source/public-key.ts:112

Check if this public key equals another public key.

Parameters

Parameter	Type	Description
`other`	`PublicKey`	The other public key to compare.

Returns

boolean

True if the public keys are equal, false otherwise.

Throws

InvalidInstanceError If the other argument is not a PublicKey instance.

toBytes()

toBytes(): Uint8Array;

Defined in: source/public-key.ts:100

Transform: Bytes representation of this public key.

Returns

Uint8Array

The bytes.

toHex()

toHex(): string;

Defined in: source/public-key.ts:91

Transform: Hex representation of this public key.

Returns

string

The hex string.

fromBytes()

static fromBytes(value): PublicKey;

Defined in: source/public-key.ts:57

Construct a PublicKey from a Uint8Array.

Parameters

Parameter	Type	Description
`value`	`Uint8Array`	The compressed (33 byte) or uncompressed (65 byte) secp256k1 public key bytes.

Returns

PublicKey

A new PublicKey instance.

Throws

PublicKeyInvalidError If the bytes do not encode a valid secp256k1 public key.

fromString()

static fromString(value): PublicKey;

Defined in: source/public-key.ts:46

Construct a PublicKey from a hex string.

Parameters

Parameter	Type	Description
`value`	`string`	The compressed or uncompressed secp256k1 public key as a hex string.

Returns

PublicKey

A new PublicKey instance.

Throws

PublicKeyInvalidError If the string is not a valid hex-encoded secp256k1 public key.

PublicKeyInvalidError

Defined in: source/errors.ts:66

Error thrown when public key is invalid.

Extends

Error

Constructors

Constructor

new PublicKeyInvalidError(): PublicKeyInvalidError;

Defined in: source/errors.ts:66

Returns

PublicKeyInvalidError

Overrides

Error.constructor

PublicKeyInvalidInputTypeError

Defined in: source/errors.ts:54

Error thrown when public key input type is invalid.

Extends

Error

Constructors

Constructor

new PublicKeyInvalidInputTypeError(receivedType): PublicKeyInvalidInputTypeError;

Defined in: primitives/dist/index.d.mts:85

Parameters

Parameter	Type
`receivedType`	`string`

Returns

PublicKeyInvalidInputTypeError

Overrides

Error.constructor

Satoshis

Defined in: source/satoshis.ts:30

Satoshis Primitive. Validated wrapper around a satoshi amount. Accepts bigint, number, or string and ensures the value is a non-negative integer within [0, MAX_REASONABLE_SATOSHIS]. Provides arithmetic and comparison operations, each returning a new instance.

typescript

import { Satoshis } from '@xo-cash/primitives';

const satoshis = new Satoshis(1000n).toBigInt();

Constructors

Constructor

new Satoshis(satoshis): Satoshis;

Defined in: primitives/dist/index.d.mts:1056

Construct a new Satoshis Primitive. Validates that the provided satoshis value is in range [0, MAX_REASONABLE_SATOSHIS].

Parameters

Parameter	Type	Description
`satoshis`	`string` \| `number` \| `bigint`	The provided satoshis value.

Returns

Satoshis

Throws

SatoshisInvalidInputTypeError If input type is invalid.

Throws

SatoshisInvalidNumberError If number is not a non-negative integer.

Throws

SatoshisStringTooLongError If string exceeds MAX_REASONABLE_SATOSHIS_STRING_LENGTH.

Throws

SatoshisInvalidStringError If string is not a plain decimal integer.

Throws

SatoshisOutOfRangeError If the value is outside [0, MAX_REASONABLE_SATOSHIS].

Methods

add()

add(other): Satoshis;

Defined in: source/satoshis.ts:203

Add another Satoshis to this instance and return a new Satoshis with the result.

Parameters

Parameter	Type	Description
`other`	`Satoshis`	The Satoshis to add.

Returns

Satoshis

A new Satoshis instance representing the sum.

Throws

InvalidInstanceError If the other argument is not a Satoshis instance.

Throws

SatoshisOutOfRangeError If the sum exceeds MAX_REASONABLE_SATOSHIS.

equals()

equals(other): boolean;

Defined in: source/satoshis.ts:234

Check if this equals another Satoshis.

Parameters

Parameter	Type	Description
`other`	`Satoshis`	The other Satoshis to compare.

Returns

boolean

True if equal, false otherwise.

Throws

InvalidInstanceError If the other argument is not a Satoshis instance.

greaterThan()

greaterThan(other): boolean;

Defined in: source/satoshis.ts:279

Check if this is greater than another Satoshis.

Parameters

Parameter	Type	Description
`other`	`Satoshis`	The other Satoshis to compare.

Returns

boolean

True if this > other, false otherwise.

Throws

InvalidInstanceError If the other argument is not a Satoshis instance.

greaterThanOrEqual()

greaterThanOrEqual(other): boolean;

Defined in: source/satoshis.ts:294

Check if this is greater than or equal to another Satoshis.

Parameters

Parameter	Type	Description
`other`	`Satoshis`	The other Satoshis to compare.

Returns

boolean

True if this >= other, false otherwise.

Throws

InvalidInstanceError If the other argument is not a Satoshis instance.

lessThan()

lessThan(other): boolean;

Defined in: source/satoshis.ts:249

Check if this is less than another Satoshis.

Parameters

Parameter	Type	Description
`other`	`Satoshis`	The other Satoshis to compare.

Returns

boolean

True if this < other, false otherwise.

Throws

InvalidInstanceError If the other argument is not a Satoshis instance.

lessThanOrEqual()

lessThanOrEqual(other): boolean;

Defined in: source/satoshis.ts:264

Check if this is less than or equal to another Satoshis.

Parameters

Parameter	Type	Description
`other`	`Satoshis`	The other Satoshis to compare.

Returns

boolean

True if this <= other, false otherwise.

Throws

InvalidInstanceError If the other argument is not a Satoshis instance.

subtract()

subtract(other): Satoshis;

Defined in: source/satoshis.ts:219

Subtract another Satoshis from this instance and return a new Satoshis with the result.

Parameters

Parameter	Type	Description
`other`	`Satoshis`	The Satoshis to subtract.

Returns

Satoshis

A new Satoshis instance representing the difference.

Throws

InvalidInstanceError If the other argument is not a Satoshis instance.

Throws

SatoshisOutOfRangeError If the result would be negative.

toBCH()

toBCH(): number;

Defined in: source/satoshis.ts:191

Transform: The value expressed in BCH as a decimal number. Utility function expected to be used in CashAssembly evaluations.

Returns

number

The BCH amount.

toBigInt()

toBigInt(): bigint;

Defined in: source/satoshis.ts:162

Returns the satoshis value as a bigint.

Returns

bigint

The satoshis value as a bigint.

toSatoshis()

toSatoshis(): bigint;

Defined in: source/satoshis.ts:181

Transform: The satoshis value as a bigint. Utility function expected to be used in CashAssembly evaluations.

Returns

bigint

The satoshis value as a bigint.

toString()

toString(): string;

Defined in: source/satoshis.ts:171

Returns the satoshis value as a string.

Returns

string

The satoshis value as a string.

fromBigInt()

static fromBigInt(value): Satoshis;

Defined in: source/satoshis.ts:60

Construct a Satoshis from a bigint value.

Parameters

Parameter	Type	Description
`value`	`bigint`	The satoshis value as a bigint.

Returns

Satoshis

A new Satoshis instance.

Throws

SatoshisOutOfRangeError If the value is outside [0, MAX_REASONABLE_SATOSHIS].

fromNumber()

static fromNumber(value): Satoshis;

Defined in: source/satoshis.ts:72

Construct a Satoshis from a number value.

Parameters

Parameter	Type	Description
`value`	`number`	The satoshis value as a number.

Returns

Satoshis

A new Satoshis instance.

Throws

SatoshisInvalidNumberError If the value is not a non-negative integer.

Throws

SatoshisOutOfRangeError If the value exceeds MAX_REASONABLE_SATOSHIS.

fromString()

static fromString(value): Satoshis;

Defined in: source/satoshis.ts:85

Construct a Satoshis from a decimal integer string.

Parameters

Parameter	Type	Description
`value`	`string`	The satoshis value as a decimal integer string.

Returns

Satoshis

A new Satoshis instance.

Throws

SatoshisStringTooLongError If the string exceeds MAX_REASONABLE_SATOSHIS_STRING_LENGTH.

Throws

SatoshisInvalidStringError If the string is not a plain decimal integer.

Throws

SatoshisOutOfRangeError If the value exceeds MAX_REASONABLE_SATOSHIS.

SatoshisInvalidInputTypeError

Defined in: source/errors.ts:213

Error thrown when provided satoshis input value type is invalid.

Extends

Error

Constructors

Constructor

new SatoshisInvalidInputTypeError(receivedType): SatoshisInvalidInputTypeError;

Defined in: primitives/dist/index.d.mts:191

Parameters

Parameter	Type
`receivedType`	`string`

Returns

SatoshisInvalidInputTypeError

Overrides

Error.constructor

SatoshisInvalidNumberError

Defined in: source/errors.ts:237

Error thrown when provided satoshis value as number does not resolve to a non-negative integer.

Extends

Error

Constructors

Constructor

new SatoshisInvalidNumberError(receivedValue): SatoshisInvalidNumberError;

Defined in: primitives/dist/index.d.mts:207

Parameters

Parameter	Type
`receivedValue`	`number`

Returns

SatoshisInvalidNumberError

Overrides

Error.constructor

SatoshisInvalidStringError

Defined in: source/errors.ts:249

Error thrown when provided satoshis value as string does not resolve to a non-negative integer.

Extends

Error

Constructors

Constructor

new SatoshisInvalidStringError(receivedString): SatoshisInvalidStringError;

Defined in: primitives/dist/index.d.mts:215

Parameters

Parameter	Type
`receivedString`	`string`

Returns

SatoshisInvalidStringError

Overrides

Error.constructor

SatoshisOutOfRangeError

Defined in: source/errors.ts:225

Error thrown when provided satoshis input value is out of range.

Extends

Error

Constructors

Constructor

new SatoshisOutOfRangeError(value): SatoshisOutOfRangeError;

Defined in: primitives/dist/index.d.mts:199

Parameters

Parameter	Type
`value`	`bigint`

Returns

SatoshisOutOfRangeError

Overrides

Error.constructor

SatoshisStringTooLongError

Defined in: source/errors.ts:261

Error thrown when provided satoshis value as string is longer than the maximum allowed length.

Extends

Error

Constructors

Constructor

new SatoshisStringTooLongError(receivedLength): SatoshisStringTooLongError;

Defined in: primitives/dist/index.d.mts:223

Parameters

Parameter	Type
`receivedLength`	`number`

Returns

SatoshisStringTooLongError

Overrides

Error.constructor

MAX_REASONABLE_SATOSHIS

const MAX_REASONABLE_SATOSHIS: bigint;

Defined in: source/defaults.ts:13

Maximum reasonable satoshis: 21 million Bitcoin Cash × 100 million sat per Bitcoin Cash.

MAX_REASONABLE_SATOSHIS_STRING_LENGTH

const MAX_REASONABLE_SATOSHIS_STRING_LENGTH: number;

Defined in: source/defaults.ts:20

Maximum length of the string representation of reasonable satoshis.

SATOSHIS_DECIMAL_STRING_PATTERN

const SATOSHIS_DECIMAL_STRING_PATTERN: RegExp;

Defined in: source/defaults.ts:35

Same pattern as DECIMAL_INTEGER_STRING_PATTERN. Used to validate satoshi string inputs.

SATOSHIS_PER_BITCOIN_CASH

const SATOSHIS_PER_BITCOIN_CASH: 100000000n = 100000000n;

Defined in: source/defaults.ts:6

Satoshis per Bitcoin Cash (1 Bitcoin Cash = 100 million satoshis).

SchnorrSignature

Defined in: source/schnorr-signature.ts:29

Schnorr Signature Primitive. Wraps a secp256k1 EC-Schnorr-SHA256 signature. The Schnorr signature scheme always produces signatures of exactly SCHNORR_SIGNATURE_BYTE_LENGTH bytes.

Remarks

This primitive checks format only (SCHNORR_SIGNATURE_BYTE_LENGTH byte length and valid hex encoding). It does not verify the signature cryptographically against a message or public key.

typescript

import { SchnorrSignature } from '@xo-cash/primitives';

const sig = new SchnorrSignature(signatureBytes).toHex();

Constructors

Constructor

new SchnorrSignature(signature): SchnorrSignature;

Defined in: primitives/dist/index.d.mts:1199

Construct a new Schnorr Signature Primitive. Validates that the input encodes exactly SCHNORR_SIGNATURE_BYTE_LENGTH bytes and, for string inputs, that all characters are valid hexadecimal.

Parameters

Parameter	Type	Description
`signature`	`string` \| `Uint8Array`<`ArrayBufferLike`>	The signature as bytes or a SCHNORR_SIGNATURE_HEX_LENGTH-character hex string.

Returns

SchnorrSignature

Throws

SchnorrSignatureInvalidInputTypeError If input type is not Uint8Array or string.

Throws

SchnorrSignatureByteLengthInvalidError If the Uint8Array is not exactly SCHNORR_SIGNATURE_BYTE_LENGTH bytes.

Throws

SchnorrSignatureHexLengthInvalidError If the string is not exactly SCHNORR_SIGNATURE_HEX_LENGTH characters.

Throws

SchnorrSignatureHexFormatInvalidError If the string contains non-hexadecimal characters.

Methods

equals()

equals(other): boolean;

Defined in: source/schnorr-signature.ts:154

Check if this signature equals another signature.

Parameters

Parameter	Type	Description
`other`	`SchnorrSignature`	The other signature to compare.

Returns

boolean

True if both encode the same SCHNORR_SIGNATURE_BYTE_LENGTH bytes, false otherwise.

Throws

InvalidInstanceError If other is not a SchnorrSignature instance.

toBytes()

toBytes(): Uint8Array;

Defined in: source/schnorr-signature.ts:143

Transform: Bytes representation of this signature.

Returns

Uint8Array

A copy of the SCHNORR_SIGNATURE_BYTE_LENGTH byte signature.

toHex()

toHex(): string;

Defined in: source/schnorr-signature.ts:134

Transform: Hex representation of this signature.

Returns

string

The SCHNORR_SIGNATURE_HEX_LENGTH-character hex string.

fromBytes()

static fromBytes(value): SchnorrSignature;

Defined in: source/schnorr-signature.ts:68

Construct a SchnorrSignature from a Uint8Array.

Parameters

Parameter	Type	Description
`value`	`Uint8Array`	The signature as a SCHNORR_SIGNATURE_BYTE_LENGTH byte Uint8Array.

Returns

SchnorrSignature

A new SchnorrSignature instance.

Throws

SchnorrSignatureByteLengthInvalidError If the array is not exactly SCHNORR_SIGNATURE_BYTE_LENGTH bytes.

fromString()

static fromString(value): SchnorrSignature;

Defined in: source/schnorr-signature.ts:57

Construct a SchnorrSignature from a SCHNORR_SIGNATURE_HEX_LENGTH-character hex string.

Parameters

Parameter	Type	Description
`value`	`string`	The signature as a SCHNORR_SIGNATURE_HEX_LENGTH-character hex string.

Returns

SchnorrSignature

A new SchnorrSignature instance.

Throws

SchnorrSignatureHexLengthInvalidError If the string is not SCHNORR_SIGNATURE_HEX_LENGTH characters.

Throws

SchnorrSignatureHexFormatInvalidError If the string contains non-hex characters.

SchnorrSignatureAllZeroesError

Defined in: source/errors.ts:741

Error thrown when a Schnorr signature consists entirely of zero bytes, indicating a suspected placeholder value.

Extends

Error

Constructors

Constructor

new SchnorrSignatureAllZeroesError(): SchnorrSignatureAllZeroesError;

Defined in: source/errors.ts:741

Returns

SchnorrSignatureAllZeroesError

Overrides

Error.constructor

SchnorrSignatureByteLengthInvalidError

Defined in: source/errors.ts:705

Error thrown when a Uint8Array Schnorr signature is not exactly SCHNORR_SIGNATURE_BYTE_LENGTH bytes.

Extends

Error

Constructors

Constructor

new SchnorrSignatureByteLengthInvalidError(receivedByteLength): SchnorrSignatureByteLengthInvalidError;

Defined in: primitives/dist/index.d.mts:519

Parameters

Parameter	Type
`receivedByteLength`	`number`

Returns

SchnorrSignatureByteLengthInvalidError

Overrides

Error.constructor

SchnorrSignatureHexFormatInvalidError

Defined in: source/errors.ts:729

Error thrown when a string Schnorr signature is the correct length but contains non-hex characters.

Extends

Error

Constructors

Constructor

new SchnorrSignatureHexFormatInvalidError(): SchnorrSignatureHexFormatInvalidError;

Defined in: source/errors.ts:729

Returns

SchnorrSignatureHexFormatInvalidError

Overrides

Error.constructor

SchnorrSignatureHexLengthInvalidError

Defined in: source/errors.ts:717

Error thrown when a string Schnorr signature is not exactly SCHNORR_SIGNATURE_HEX_LENGTH characters.

Extends

Error

Constructors

Constructor

new SchnorrSignatureHexLengthInvalidError(receivedLength): SchnorrSignatureHexLengthInvalidError;

Defined in: primitives/dist/index.d.mts:527

Parameters

Parameter	Type
`receivedLength`	`number`

Returns

SchnorrSignatureHexLengthInvalidError

Overrides

Error.constructor

SchnorrSignatureInvalidInputTypeError

Defined in: source/errors.ts:693

Error thrown when a Schnorr signature input is not a Uint8Array or string.

Extends

Error

Constructors

Constructor

new SchnorrSignatureInvalidInputTypeError(receivedType): SchnorrSignatureInvalidInputTypeError;

Defined in: primitives/dist/index.d.mts:511

Parameters

Parameter	Type
`receivedType`	`string`

Returns

SchnorrSignatureInvalidInputTypeError

Overrides

Error.constructor

SchnorrSignatureMaximumError

Defined in: source/errors.ts:753

Error thrown when a Schnorr signature consists entirely of 0xFF bytes, indicating a suspected placeholder value.

Extends

Error

Constructors

Constructor

new SchnorrSignatureMaximumError(): SchnorrSignatureMaximumError;

Defined in: source/errors.ts:753

Returns

SchnorrSignatureMaximumError

Overrides

Error.constructor

SCHNORR_SIGNATURE_BYTE_LENGTH

const SCHNORR_SIGNATURE_BYTE_LENGTH: 64 = 64;

Defined in: source/defaults.ts:153

Byte length of a secp256k1 EC-Schnorr-SHA256 signature. Schnorr signatures produced by libauth are always exactly 64 bytes.

SCHNORR_SIGNATURE_HEX_LENGTH

const SCHNORR_SIGNATURE_HEX_LENGTH: number;

Defined in: source/defaults.ts:160

Character length of a Schnorr signature hex string.

Shared

InvalidInstanceError

Defined in: source/errors.ts:31

Error thrown when an operation receives a value that is not an instance of the expected class. Used by primitive comparison methods when the argument passed is not an instance of the expected class.

Extends

Error

Constructors

Constructor

new InvalidInstanceError(expectedClassName, receivedValue): InvalidInstanceError;

Defined in: primitives/dist/index.d.mts:77

Parameters

Parameter	Type
`expectedClassName`	`string`
`receivedValue`	`unknown`

Returns

InvalidInstanceError

Overrides

Error.constructor

DECIMAL_INTEGER_STRING_PATTERN

const DECIMAL_INTEGER_STRING_PATTERN: RegExp;

Defined in: source/defaults.ts:27

Matches a decimal integer string: "0" or a positive integer with no leading zeros.

TemplateIdentifier

Defined in: source/template-identifier.ts:26

Template Identifier Primitive. Validates and wraps the TEMPLATE_IDENTIFIER_BYTE_LENGTH byte template identifier, which is the SHA-256 hash of the serialized template.

typescript

import { TemplateIdentifier } from '@xo-cash/primitives';

const id = new TemplateIdentifier('cf5839d183aafa050e6d6fda049918764f82331e60b2d2995851108cd2569a94').toHex();

Constructors

Constructor

new TemplateIdentifier(templateIdentifier): TemplateIdentifier;

Defined in: primitives/dist/index.d.mts:1266

Construct a new Template Identifier Primitive. Validates that the input encodes exactly TEMPLATE_IDENTIFIER_BYTE_LENGTH bytes and, for string inputs, that all characters are valid hexadecimal.

Parameters

Parameter	Type	Description
`templateIdentifier`	`string` \| `Uint8Array`<`ArrayBufferLike`>	The template identifier as bytes or a TEMPLATE_IDENTIFIER_HEX_LENGTH-character hex string.

Returns

TemplateIdentifier

Throws

TemplateIdentifierInvalidInputTypeError If input type is not Uint8Array or string.

Throws

TemplateIdentifierByteLengthInvalidError If the Uint8Array is not exactly TEMPLATE_IDENTIFIER_BYTE_LENGTH bytes.

Throws

TemplateIdentifierHexLengthInvalidError If the string is not exactly TEMPLATE_IDENTIFIER_HEX_LENGTH characters.

Throws

TemplateIdentifierHexFormatInvalidError If the string contains non-hexadecimal characters.

Methods

equals()

equals(other): boolean;

Defined in: source/template-identifier.ts:152

Check if this template identifier equals another template identifier.

Parameters

Parameter	Type	Description
`other`	`TemplateIdentifier`	The other template identifier to compare.

Returns

boolean

True if both encode the same TEMPLATE_IDENTIFIER_BYTE_LENGTH bytes, false otherwise.

Throws

InvalidInstanceError If other is not a TemplateIdentifier instance.

toBytes()

toBytes(): Uint8Array;

Defined in: source/template-identifier.ts:141

Transform: Bytes representation of this template identifier.

Returns

Uint8Array

A copy of the TEMPLATE_IDENTIFIER_BYTE_LENGTH byte identifier.

toHex()

toHex(): string;

Defined in: source/template-identifier.ts:132

Transform: Hex representation of this template identifier.

Returns

string

The TEMPLATE_IDENTIFIER_HEX_LENGTH-character hex string.

fromBytes()

static fromBytes(value): TemplateIdentifier;

Defined in: source/template-identifier.ts:66

Construct a TemplateIdentifier from a Uint8Array.

Parameters

Parameter	Type	Description
`value`	`Uint8Array`	The template identifier as a TEMPLATE_IDENTIFIER_BYTE_LENGTH byte Uint8Array.

Returns

TemplateIdentifier

A new TemplateIdentifier instance.

Throws

TemplateIdentifierByteLengthInvalidError If the array is not exactly TEMPLATE_IDENTIFIER_BYTE_LENGTH bytes.

fromString()

static fromString(value): TemplateIdentifier;

Defined in: source/template-identifier.ts:55

Construct a TemplateIdentifier from a TEMPLATE_IDENTIFIER_HEX_LENGTH-character hex string.

Parameters

Parameter	Type	Description
`value`	`string`	The template identifier as a TEMPLATE_IDENTIFIER_HEX_LENGTH-character hex string.

Returns

TemplateIdentifier

A new TemplateIdentifier instance.

Throws

TemplateIdentifierHexLengthInvalidError If the string is not TEMPLATE_IDENTIFIER_HEX_LENGTH characters.

Throws

TemplateIdentifierHexFormatInvalidError If the string contains non-hex characters.

TemplateIdentifierAllZeroesError

Defined in: source/errors.ts:525

Error thrown when a template identifier consists entirely of zero bytes, indicating a suspected placeholder value.

Extends

Error

Constructors

Constructor

new TemplateIdentifierAllZeroesError(): TemplateIdentifierAllZeroesError;

Defined in: source/errors.ts:525

Returns

TemplateIdentifierAllZeroesError

Overrides

Error.constructor

TemplateIdentifierByteLengthInvalidError

Defined in: source/errors.ts:489

Error thrown when a Uint8Array template identifier is not exactly TEMPLATE_IDENTIFIER_BYTE_LENGTH bytes.

Extends

Error

Constructors

Constructor

new TemplateIdentifierByteLengthInvalidError(receivedByteLength): TemplateIdentifierByteLengthInvalidError;

Defined in: primitives/dist/index.d.mts:375

Parameters

Parameter	Type
`receivedByteLength`	`number`

Returns

TemplateIdentifierByteLengthInvalidError

Overrides

Error.constructor

TemplateIdentifierHexFormatInvalidError

Defined in: source/errors.ts:513

Error thrown when a string template identifier is the correct length but contains non-hex characters.

Extends

Error

Constructors

Constructor

new TemplateIdentifierHexFormatInvalidError(): TemplateIdentifierHexFormatInvalidError;

Defined in: source/errors.ts:513

Returns

TemplateIdentifierHexFormatInvalidError

Overrides

Error.constructor

TemplateIdentifierHexLengthInvalidError

Defined in: source/errors.ts:501

Error thrown when a string template identifier is not exactly TEMPLATE_IDENTIFIER_HEX_LENGTH characters.

Extends

Error

Constructors

Constructor

new TemplateIdentifierHexLengthInvalidError(receivedLength): TemplateIdentifierHexLengthInvalidError;

Defined in: primitives/dist/index.d.mts:383

Parameters

Parameter	Type
`receivedLength`	`number`

Returns

TemplateIdentifierHexLengthInvalidError

Overrides

Error.constructor

TemplateIdentifierInvalidInputTypeError

Defined in: source/errors.ts:477

Error thrown when a template identifier input is not a Uint8Array or string.

Extends

Error

Constructors

Constructor

new TemplateIdentifierInvalidInputTypeError(receivedType): TemplateIdentifierInvalidInputTypeError;

Defined in: primitives/dist/index.d.mts:367

Parameters

Parameter	Type
`receivedType`	`string`

Returns

TemplateIdentifierInvalidInputTypeError

Overrides

Error.constructor

TemplateIdentifierMaximumError

Defined in: source/errors.ts:537

Error thrown when a template identifier consists entirely of 0xFF bytes, indicating a suspected placeholder value.

Extends

Error

Constructors

Constructor

new TemplateIdentifierMaximumError(): TemplateIdentifierMaximumError;

Defined in: source/errors.ts:537

Returns

TemplateIdentifierMaximumError

Overrides

Error.constructor

TEMPLATE_IDENTIFIER_BYTE_LENGTH

const TEMPLATE_IDENTIFIER_BYTE_LENGTH: 32 = 32;

Defined in: source/defaults.ts:110

Byte length of a template identifier.

TEMPLATE_IDENTIFIER_HEX_LENGTH

const TEMPLATE_IDENTIFIER_HEX_LENGTH: number;

Defined in: source/defaults.ts:117

Character length of a template identifier hex string.

Timestamp

Defined in: source/timestamp.ts:24

Timestamp Primitive. Validates and wraps a Unix timestamp in milliseconds. Accepts a number (milliseconds) or any date string recognized by the JavaScript Date constructor. Accepts any timestamp within the full JavaScript Date range.

typescript

import { Timestamp } from '@xo-cash/primitives';

const timestamp = new Timestamp(Date.now()).toIso8601();

Constructors

Constructor

new Timestamp(timestamp): Timestamp;

Defined in: primitives/dist/index.d.mts:1334

Construct a new Timestamp primitive. Validates that the input is a non-negative integer within [0, DATE_MILLISECONDS_MAX], or a valid date string representing a point in time on or after the Unix epoch.

Parameters

Parameter	Type	Description
`timestamp`	`string` \| `number`	Unix timestamp in milliseconds or any date string recognized by the JavaScript Date constructor.

Returns

Timestamp

Throws

TimestampInvalidInputTypeError If input type is not a number or string.

Throws

TimestampNotIntegerError If number input is not an integer.

Throws

TimestampOutOfRangeError If input falls outside [DATE_MILLISECONDS_MIN, DATE_MILLISECONDS_MAX].

Throws

TimestampInvalidStringError If string input does not produce a valid date.

Methods

equals()

equals(other): boolean;

Defined in: source/timestamp.ts:147

Check if this timestamp equals another timestamp.

Parameters

Parameter	Type	Description
`other`	`Timestamp`	The other timestamp to compare.

Returns

boolean

True if both represent the same millisecond, false otherwise.

Throws

InvalidInstanceError If other is not a Timestamp instance.

toIso8601()

toIso8601(): string;

Defined in: source/timestamp.ts:136

Transform: ISO 8601 datetime string in UTC. Utility function expected to be used in CashAssembly evaluations.

Returns

string

ISO 8601 datetime string (e.g. 2024-01-15T10:30:00.000Z).

toNumber()

toNumber(): number;

Defined in: source/timestamp.ts:126

Transform: Milliseconds since the Unix epoch.

Returns

number

Unix timestamp in milliseconds.

fromNumber()

static fromNumber(value): Timestamp;

Defined in: source/timestamp.ts:103

Constructs a Timestamp from a milliseconds number. Equivalent to calling the constructor directly.

Parameters

Parameter	Type	Description
`value`	`number`	Unix timestamp in milliseconds.

Returns

Timestamp

A new Timestamp instance.

Throws

TimestampNotIntegerError If value is not an integer.

Throws

TimestampOutOfRangeError If value falls outside [DATE_MILLISECONDS_MIN, DATE_MILLISECONDS_MAX].

fromString()

static fromString(value): Timestamp;

Defined in: source/timestamp.ts:117

Constructs a Timestamp from a date string. Equivalent to calling the constructor directly. Accepts any string recognized by the JavaScript Date constructor that represents a point in time on or after the Unix epoch.

Parameters

Parameter	Type	Description
`value`	`string`	A date string recognized by the JavaScript Date constructor.

Returns

Timestamp

A new Timestamp instance.

Throws

TimestampInvalidStringError If string does not produce a valid date.

Throws

TimestampOutOfRangeError If the parsed date falls outside [DATE_MILLISECONDS_MIN, DATE_MILLISECONDS_MAX].

TimestampInvalidInputTypeError

Defined in: source/errors.ts:164

Error thrown when timestamp input type is invalid.

Extends

Error

Constructors

Constructor

new TimestampInvalidInputTypeError(receivedType): TimestampInvalidInputTypeError;

Defined in: primitives/dist/index.d.mts:158

Parameters

Parameter	Type
`receivedType`	`string`

Returns

TimestampInvalidInputTypeError

Overrides

Error.constructor

TimestampInvalidStringError

Defined in: source/errors.ts:201

Error thrown when timestamp input as string does not produce a valid date.

Extends

Error

Constructors

Constructor

new TimestampInvalidStringError(receivedValue): TimestampInvalidStringError;

Defined in: primitives/dist/index.d.mts:183

Parameters

Parameter	Type
`receivedValue`	`string`

Returns

TimestampInvalidStringError

Overrides

Error.constructor

TimestampNotIntegerError

Defined in: source/errors.ts:176

Error thrown when timestamp input as number is not an integer.

Extends

Error

Constructors

Constructor

new TimestampNotIntegerError(receivedValue): TimestampNotIntegerError;

Defined in: primitives/dist/index.d.mts:166

Parameters

Parameter	Type
`receivedValue`	`number`

Returns

TimestampNotIntegerError

Overrides

Error.constructor

TimestampOutOfRangeError

Defined in: source/errors.ts:189

Error thrown when timestamp input falls outside the valid JavaScript Date range. [DATE_MILLISECONDS_MIN, DATE_MILLISECONDS_MAX].

Extends

Error

Constructors

Constructor

new TimestampOutOfRangeError(receivedValue): TimestampOutOfRangeError;

Defined in: primitives/dist/index.d.mts:175

Parameters

Parameter	Type
`receivedValue`	`number`

Returns

TimestampOutOfRangeError

Overrides

Error.constructor

DATE_MILLISECONDS_MAX

const DATE_MILLISECONDS_MAX: 8640000000000000 = 8640000000000000;

Defined in: source/defaults.ts:95

Maximum millisecond value accepted by the JavaScript Date object. This equals exactly 100,000,000 days from the Unix epoch. Passing a value beyond this range to Date.prototype.toISOString causes RangeError.

DATE_MILLISECONDS_MIN

const DATE_MILLISECONDS_MIN: number;

Defined in: source/defaults.ts:103

Minimum millisecond value accepted by the JavaScript Date object. Passing a value below this range to Date.prototype.toISOString causes RangeError.

TokenCategory

Defined in: source/token-category.ts:30

Token Category Primitive. Validates and wraps the TOKEN_CATEGORY_BYTE_LENGTH byte token category identifier, which is the transaction hash of the UTXO from which the token was minted (the genesis outpoint). Accepts a Uint8Array or a TOKEN_CATEGORY_HEX_LENGTH-character hex string.

typescript

import { TokenCategory } from '@xo-cash/primitives';

const someTokenCategory = new TokenCategory('cf5839d183aafa050e6d6fda049918764f82331e60b2d2995851108cd2569a94');

const someToken = {
    ...otherProperties,
    category: someTokenCategory.toBytes(),
};

Constructors

Constructor

new TokenCategory(tokenCategory): TokenCategory;

Defined in: primitives/dist/index.d.mts:1411

Construct a new Token Category Primitive. Validates that the input encodes exactly TOKEN_CATEGORY_BYTE_LENGTH bytes.

Parameters

Parameter	Type	Description
`tokenCategory`	`string` \| `Uint8Array`<`ArrayBufferLike`>	The token category as bytes (Uint8Array) or a TOKEN_CATEGORY_HEX_LENGTH-character hex string.

Returns

TokenCategory

Throws

TokenCategoryInvalidInputTypeError If input type is not Uint8Array or string.

Throws

TokenCategoryInvalidByteLengthError If Uint8Array is not exactly TOKEN_CATEGORY_BYTE_LENGTH bytes.

Throws

TokenCategoryInvalidHexLengthError If hex string is not TOKEN_CATEGORY_HEX_LENGTH characters.

Throws

TokenCategoryInvalidHexFormatError If hex string is not valid hexadecimal.

Methods

equals()

equals(other): boolean;

Defined in: source/token-category.ts:136

Check if this token category equals another token category.

Parameters

Parameter	Type	Description
`other`	`TokenCategory`	The other token category to compare.

Returns

boolean

True if both categories encode the same TOKEN_CATEGORY_BYTE_LENGTH bytes, false otherwise.

Throws

InvalidInstanceError If other is not a TokenCategory instance.

toBytes()

toBytes(): Uint8Array;

Defined in: source/token-category.ts:124

Transform: Bytes representation of this token category.

Returns

Uint8Array

A copy of the TOKEN_CATEGORY_BYTE_LENGTH byte category.

toHex()

toHex(): string;

Defined in: source/token-category.ts:115

Transform: Hex representation of this token category.

Returns

string

The TOKEN_CATEGORY_HEX_LENGTH-character hex string.

fromBytes()

static fromBytes(value): TokenCategory;

Defined in: source/token-category.ts:71

Construct a TokenCategory from a Uint8Array.

Parameters

Parameter	Type	Description
`value`	`Uint8Array`	The token category as a TOKEN_CATEGORY_BYTE_LENGTH byte Uint8Array.

Returns

TokenCategory

A new TokenCategory instance.

Throws

TokenCategoryInvalidByteLengthError If the array is not exactly TOKEN_CATEGORY_BYTE_LENGTH bytes.

fromString()

static fromString(value): TokenCategory;

Defined in: source/token-category.ts:60

Construct a TokenCategory from a TOKEN_CATEGORY_HEX_LENGTH-character hex string.

Parameters

Parameter	Type	Description
`value`	`string`	The token category as a TOKEN_CATEGORY_HEX_LENGTH-character hex string.

Returns

TokenCategory

A new TokenCategory instance.

Throws

TokenCategoryInvalidInputTypeError If value is not a string.

Throws

TokenCategoryInvalidHexLengthError If the string is not TOKEN_CATEGORY_HEX_LENGTH characters.

Throws

TokenCategoryInvalidHexFormatError If the string is not valid hexadecimal.

TokenCategoryInvalidByteLengthError

Defined in: source/errors.ts:285

Error thrown when a token category value does not encode exactly TOKEN_CATEGORY_BYTE_LENGTH bytes.

Extends

Error

Constructors

Constructor

new TokenCategoryInvalidByteLengthError(receivedLength): TokenCategoryInvalidByteLengthError;

Defined in: primitives/dist/index.d.mts:239

Parameters

Parameter	Type
`receivedLength`	`number`

Returns

TokenCategoryInvalidByteLengthError

Overrides

Error.constructor

TokenCategoryInvalidHexFormatError

Defined in: source/errors.ts:309

Error thrown when a token category value is not valid hexadecimal.

Extends

Error

Constructors

Constructor

new TokenCategoryInvalidHexFormatError(): TokenCategoryInvalidHexFormatError;

Defined in: source/errors.ts:309

Returns

TokenCategoryInvalidHexFormatError

Overrides

Error.constructor

TokenCategoryInvalidHexLengthError

Defined in: source/errors.ts:297

Error thrown when a token category value does not encode exactly TOKEN_CATEGORY_HEX_LENGTH characters.

Extends

Error

Constructors

Constructor

new TokenCategoryInvalidHexLengthError(receivedLength): TokenCategoryInvalidHexLengthError;

Defined in: primitives/dist/index.d.mts:247

Parameters

Parameter	Type
`receivedLength`	`number`

Returns

TokenCategoryInvalidHexLengthError

Overrides

Error.constructor

TokenCategoryInvalidInputTypeError

Defined in: source/errors.ts:273

Error thrown when a token category input is not a Uint8Array or string.

Extends

Error

Constructors

Constructor

new TokenCategoryInvalidInputTypeError(receivedType): TokenCategoryInvalidInputTypeError;

Defined in: primitives/dist/index.d.mts:231

Parameters

Parameter	Type
`receivedType`	`string`

Returns

TokenCategoryInvalidInputTypeError

Overrides

Error.constructor

TOKEN_CATEGORY_BYTE_LENGTH

const TOKEN_CATEGORY_BYTE_LENGTH: 32 = 32;

Defined in: source/defaults.ts:50

Byte length of a token category identifier.

TOKEN_CATEGORY_HEX_LENGTH

const TOKEN_CATEGORY_HEX_LENGTH: number;

Defined in: source/defaults.ts:57

Character length of a token category hex string.

TransactionHash

Defined in: source/transaction-hash.ts:25

Transaction Hash Primitive.

typescript

import { TransactionHash } from '@xo-cash/primitives';

const txHash = 'cf5839d183aafa050e6d6fda049918764f82331e60b2d2995851108cd2569a94';
const txHashHex = new TransactionHash(txHash).toHex();

Constructors

Constructor

new TransactionHash(transactionHash): TransactionHash;

Defined in: primitives/dist/index.d.mts:1481

Construct a new Transaction Hash Primitive, this automatically validates the transaction hash. It is important to throw as soon as possible to avoid any confusion or unexpected behavior.

Parameters

Parameter	Type	Description
`transactionHash`	`string` \| `Uint8Array`<`ArrayBufferLike`>	The transaction hash as TRANSACTION_HASH_BYTE_LENGTH bytes or TRANSACTION_HASH_HEX_CHARACTER_COUNT character hex.

Returns

TransactionHash

Throws

TransactionHashByteLengthInvalidError If Uint8Array length is not TRANSACTION_HASH_BYTE_LENGTH bytes.

Throws

TransactionHashHexLengthInvalidError If hex string length is not TRANSACTION_HASH_HEX_CHARACTER_COUNT characters.

Throws

TransactionHashHexFormatInvalidError If hex string is not valid hexadecimal.

Throws

TransactionHashInvalidInputTypeError If transaction hash input type is invalid.

Throws

TransactionHashAllZeroesError If all bytes are 0x00.

Throws

TransactionHashMaximumError If all bytes are 0xFF.

Methods

equals()

equals(other): boolean;

Defined in: source/transaction-hash.ts:156

Check if this transaction hash equals another transaction hash.

Parameters

Parameter	Type	Description
`other`	`TransactionHash`	The other transaction hash to compare.

Returns

boolean

True if the transaction hashes are equal, false otherwise.

Throws

InvalidInstanceError If the other argument is not a TransactionHash instance.

toBytes()

toBytes(): Uint8Array;

Defined in: source/transaction-hash.ts:144

Transform: Bytes representation of this transaction hash.

Returns

Uint8Array

The bytes.

toHex()

toHex(): string;

Defined in: source/transaction-hash.ts:135

Transform: Hex representation of this transaction hash.

Returns

string

The hex string.

fromBytes()

static fromBytes(value): TransactionHash;

Defined in: source/transaction-hash.ts:68

Construct a TransactionHash from bytes.

Parameters

Parameter	Type	Description
`value`	`Uint8Array`	The transaction hash as bytes.

Returns

TransactionHash

A new TransactionHash instance.

Throws

TransactionHashByteLengthInvalidError If the bytes are not TRANSACTION_HASH_BYTE_LENGTH bytes.

fromString()

static fromString(value): TransactionHash;

Defined in: source/transaction-hash.ts:57

Construct a TransactionHash from a hex string.

Parameters

Parameter	Type	Description
`value`	`string`	The transaction hash as a hex string.

Returns

TransactionHash

A new TransactionHash instance.

Throws

TransactionHashHexLengthInvalidError If the hex string is not TRANSACTION_HASH_HEX_CHARACTER_COUNT characters.

Throws

TransactionHashHexFormatInvalidError If the hex string contains non-hexadecimal characters.

TransactionHashAllZeroesError

Defined in: source/errors.ts:453

Error thrown when a transaction hash input is TRANSACTION_HASH_BYTE_LENGTH bytes of 0x00.

Extends

Error

Constructors

Constructor

new TransactionHashAllZeroesError(): TransactionHashAllZeroesError;

Defined in: source/errors.ts:453

Returns

TransactionHashAllZeroesError

Overrides

Error.constructor

TransactionHashByteLengthInvalidError

Defined in: source/errors.ts:405

Error thrown when a Uint8Array transaction hash input is not exactly TRANSACTION_HASH_BYTE_LENGTH bytes.

Extends

Error

Constructors

Constructor

new TransactionHashByteLengthInvalidError(receivedByteLength): TransactionHashByteLengthInvalidError;

Defined in: primitives/dist/index.d.mts:319

Parameters

Parameter	Type
`receivedByteLength`	`number`

Returns

TransactionHashByteLengthInvalidError

Overrides

Error.constructor

TransactionHashHexFormatInvalidError

Defined in: source/errors.ts:429

Error thrown when a string transaction hash input is TRANSACTION_HASH_HEX_CHARACTER_COUNT characters but not valid hexadecimal.

Extends

Error

Constructors

Constructor

new TransactionHashHexFormatInvalidError(): TransactionHashHexFormatInvalidError;

Defined in: source/errors.ts:429

Returns

TransactionHashHexFormatInvalidError

Overrides

Error.constructor

TransactionHashHexLengthInvalidError

Defined in: source/errors.ts:417

Error thrown when a string transaction hash input is not exactly TRANSACTION_HASH_HEX_CHARACTER_COUNT characters.

Extends

Error

Constructors

Constructor

new TransactionHashHexLengthInvalidError(receivedCharacterCount): TransactionHashHexLengthInvalidError;

Defined in: primitives/dist/index.d.mts:327

Parameters

Parameter	Type
`receivedCharacterCount`	`number`

Returns

TransactionHashHexLengthInvalidError

Overrides

Error.constructor

TransactionHashInvalidInputTypeError

Defined in: source/errors.ts:441

Error thrown when transaction hash input type is invalid.

Extends

Error

Constructors

Constructor

new TransactionHashInvalidInputTypeError(receivedType): TransactionHashInvalidInputTypeError;

Defined in: primitives/dist/index.d.mts:343

Parameters

Parameter	Type
`receivedType`	`string`

Returns

TransactionHashInvalidInputTypeError

Overrides

Error.constructor

TransactionHashMaximumError

Defined in: source/errors.ts:465

Error thrown when a transaction hash input is TRANSACTION_HASH_BYTE_LENGTH bytes of 0xFF.

Extends

Error

Constructors

Constructor

new TransactionHashMaximumError(): TransactionHashMaximumError;

Defined in: source/errors.ts:465

Returns

TransactionHashMaximumError

Overrides

Error.constructor

TRANSACTION_HASH_BYTE_LENGTH

const TRANSACTION_HASH_BYTE_LENGTH: 32 = 32;

Defined in: source/defaults.ts:167

Byte length of a transaction hash.

TRANSACTION_HASH_HEX_CHARACTER_COUNT

const TRANSACTION_HASH_HEX_CHARACTER_COUNT: number;

Defined in: source/defaults.ts:174

Character length of the hex encoding of a transaction hash.

@xo-cash/primitives ​

Package Philosophy ​

Installation ​

Usage ​

Links ​

License ​

CommitIdentifier ​

CommitIdentifier ​

Constructors ​

Constructor ​

Parameters ​

Returns ​

Throws ​

Throws ​

Throws ​

Throws ​

Methods ​

equals() ​

Parameters ​

Returns ​

Throws ​

toBytes() ​

Returns ​

toHex() ​

Returns ​

fromBytes() ​

Parameters ​

Returns ​

Throws ​

fromString() ​

Parameters ​

Returns ​

Throws ​

Throws ​

CommitIdentifierAllZeroesError ​

Extends ​

Constructors ​

Constructor ​

Returns ​

Overrides ​

CommitIdentifierByteLengthInvalidError ​

Extends ​

Constructors ​

Constructor ​

Parameters ​

Returns ​

Overrides ​

CommitIdentifierHexFormatInvalidError ​

Extends ​

Constructors ​

Constructor ​

Returns ​

Overrides ​

CommitIdentifierHexLengthInvalidError ​

Extends ​

Constructors ​

Constructor ​

Parameters ​

Returns ​

Overrides ​

CommitIdentifierInvalidInputTypeError ​

Extends ​

Constructors ​

Constructor ​

Parameters ​

Returns ​

Overrides ​

CommitIdentifierMaximumError ​

Extends ​

Constructors ​

Constructor ​

Returns ​

Overrides ​

COMMIT_IDENTIFIER_BYTE_LENGTH ​

COMMIT_IDENTIFIER_HEX_LENGTH ​

ExtendedPublicKey ​

ExtendedPublicKey ​

Constructors ​

Constructor ​

Parameters ​

@xo-cash/primitives

Package Philosophy

Installation

Usage

Links

License

CommitIdentifier

CommitIdentifier

Constructors

Constructor

Parameters

Returns

Throws

Throws

Throws

Throws

Methods

equals()

Parameters

Returns

Throws

toBytes()

Returns

toHex()

Returns

fromBytes()

Parameters

Returns

Throws

fromString()

Parameters

Returns

Throws

Throws

CommitIdentifierAllZeroesError

Extends

Constructors

Constructor

Returns

Overrides

CommitIdentifierByteLengthInvalidError

Extends

Constructors

Constructor

Parameters

Returns

Overrides

CommitIdentifierHexFormatInvalidError

Extends

Constructors

Constructor

Returns

Overrides

CommitIdentifierHexLengthInvalidError

Extends

Constructors

Constructor

Parameters

Returns

Overrides

CommitIdentifierInvalidInputTypeError

Extends

Constructors

Constructor

Parameters

Returns

Overrides

CommitIdentifierMaximumError

Extends

Constructors

Constructor

Returns

Overrides

COMMIT_IDENTIFIER_BYTE_LENGTH

COMMIT_IDENTIFIER_HEX_LENGTH

ExtendedPublicKey

ExtendedPublicKey

Constructors

Constructor

Parameters