@xylabs/hex

Base functionality used throughout XY Labs TypeScript/JavaScript libraries

Reference

@xylabs/hex

Interfaces

| Interface | Description | | ------ | ------ | | HexConfig | Configuration of validation and output format |

Type Aliases

| Type Alias | Description | | ------ | ------ | | AddressTransformZodType | The output type of AddressTransformZod after parsing and transformation. | | AddressValidationZodType | The output type of AddressValidationZod after parsing. | | Address | A validated 20-byte address string type, inferred from the AddressZod schema. | | EthAddress | Branded type representing a validated Ethereum address with 0x prefix. | | HashBitLength | Valid bit lengths for hash values. | | BrandedHash | Branded type representing a validated hash hex string. | | Hash | A validated hash string type, inferred from the HashZod schema. | | BrandedHex | Branded type representing a validated lowercase hex string. | | Hex | A validated hex string type, inferred from the HexZod schema. |

Variables

| Variable | Description | | ------ | ------ | | HexRegEx | Regular expression matching a lowercase hex string without prefix. | | HexRegExWithPrefix | Regular expression matching a lowercase hex string with a 0x prefix. | | AddressTransformZod | Zod schema that accepts a string, bigint, or number and transforms it into a validated Address. | | AddressValidationZod | Zod schema that validates a string is a properly formatted 40-character hex address. | | ZERO_ADDRESS | A 160-bit zero address constant. | | ADDRESS_LENGTH | The character length of an address hex string (40 hex characters / 20 bytes). | | AddressRegEx | Regular expression matching a 20-byte (40 hex character) address string. | | AddressZod | Zod schema that validates and transforms a string into a branded Address type. | | EthAddressRegEx | Regular expression matching a 20-byte Ethereum address with 0x prefix (mixed case). | | EthAddressToStringZod | Zod schema that validates a string is a properly formatted Ethereum address. | | ~~EthAddressToStringSchema~~ | - | | EthAddressFromStringZod | Zod schema that validates and transforms a string into an EthAddress type. | | ~~EthAddressFromStringSchema~~ | - | | ETH_ZERO_ADDRESS | The zero Ethereum address constant (0x followed by 40 zero characters). | | EthAddressZod | Zod schema that validates a string as a properly formatted Ethereum address using regex and type guard. | | HASH_LENGTH | The byte length of a standard hash (32 bytes / 256 bits). | | HashRegEx | Regular expression matching a 32-byte (64 hex character) hash string. | | ZERO_HASH | A 256-bit zero hash constant. | | HashBitLength | Array of all valid hash bit lengths for runtime validation. | | HashZod | Zod schema that validates and transforms a string into a branded Hash type. | | HashToJsonZod | Zod schema that transforms a Hash to a plain string for JSON serialization. | | JsonToHashZod | Zod schema that parses a JSON string into a validated Hash, throwing on invalid input. | | HexZod | Zod schema that validates and transforms a string into a branded Hex type. | | BigIntToJsonZod | Zod schema that transforms a non-negative BigInt into a hex string for JSON serialization. | | JsonToBigIntZod | Zod schema that parses a JSON hex string into a BigInt. |

Functions

| Function | Description | | ------ | ------ | | HexRegExMinMax | Creates a RegExp matching lowercase hex strings with a byte length in the given range. | | HexRegExMinMaxMixedCaseWithPrefix | Creates a RegExp matching mixed-case hex strings with a 0x prefix and a byte length in the given range. | | asAddress | Attempts to coerce a value into an Address type, returning undefined or throwing based on the assert config. | | asAddressV2 | - | | isAddress | Type guard that checks whether a value is a valid 160-bit address. | | isAddressV2 | - | | toAddress | Converts a value to a 160-bit Address hex string. | | toAddressV2 | - | | toEthAddress | Converts a value to a 0x-prefixed Ethereum address string. | | isEthAddress | Type guard that checks whether a value is a valid 0x-prefixed Ethereum address. | | asEthAddress | Attempts to coerce a value into an EthAddress, returning undefined or throwing based on the assert config. | | asHash | Attempts to coerce a value into a Hash type, returning undefined or throwing based on the assert config. | | isHashBitLength | Type guard that checks whether a value is a valid hash bit length. | | isHash | Type guard that checks whether a value is a valid hash of the specified bit length. | | asHex | Attempts to coerce a value into a Hex type, returning undefined or throwing based on the assert config. | | hexFrom | Takes unknown value and tries our best to convert it to a hex string | | hexFromArrayBuffer | Convert an ArrayBuffer to a hex string | | hexFromBigInt | Convert a bigint to a hex string | | hexFromHexString | Normalizes a hex string by stripping an optional 0x prefix, lowercasing, and padding to byte/bit boundaries. | | hexFromNumber | Converts a number to a hex string by converting to BigInt first. | | isHex | Type guard that checks whether a value is a valid hex string. | | isHexZero | Checks whether a hex string represents a zero value. | | toHexLegacy | Converts an ArrayBuffer to a hex string without padding or normalization. | | bitsToNibbles | Converts a bit count to the equivalent number of hex nibbles (4 bits each). | | nibblesToBits | Converts a nibble count to the equivalent number of bits. | | toHex | takes any value and tries our best to convert it to a hex string | | hexToBigInt | Converts a Hex string to a BigInt. |

functions

HexRegExMinMax

@xylabs/hex

function HexRegExMinMax(minBytes?: number, maxBytes?: number): RegExp;

Creates a RegExp matching lowercase hex strings with a byte length in the given range.

Parameters

| Parameter | Type | Default value | Description | | ------ | ------ | ------ | ------ | | minBytes | number | 0 | Minimum number of bytes (default 0) | | maxBytes | number | ... | Maximum number of bytes |

Returns

RegExp

A RegExp for validating hex strings within the byte range

HexRegExMinMaxMixedCaseWithPrefix

@xylabs/hex

function HexRegExMinMaxMixedCaseWithPrefix(minBytes?: number, maxBytes?: number): RegExp;

Creates a RegExp matching mixed-case hex strings with a 0x prefix and a byte length in the given range.

Parameters

| Parameter | Type | Default value | Description | | ------ | ------ | ------ | ------ | | minBytes | number | 0 | Minimum number of bytes (default 0) | | maxBytes | number | ... | Maximum number of bytes |

Returns

RegExp

A RegExp for validating prefixed hex strings within the byte range

asAddress

@xylabs/hex

Call Signature

function asAddress(value: unknown): BrandedAddress | undefined;

Attempts to coerce a value into an Address type, returning undefined or throwing based on the assert config.

Parameters

| Parameter | Type | Description | | ------ | ------ | ------ | | value | unknown | The value to coerce (must be a string) |

Returns

BrandedAddress | undefined

The value as Address, or undefined if coercion fails and assert is not set

Call Signature

function asAddress(value: unknown, assert: AssertConfig): BrandedAddress;

Attempts to coerce a value into an Address type, returning undefined or throwing based on the assert config.

Parameters

| Parameter | Type | Description | | ------ | ------ | ------ | | value | unknown | The value to coerce (must be a string) | | assert | AssertConfig | If provided, throws on failure instead of returning undefined |

Returns

BrandedAddress

The value as Address, or undefined if coercion fails and assert is not set

asAddressV2

@xylabs/hex

function asAddressV2(value: unknown, assert?: boolean): BrandedAddress | undefined;

Alpha

Parameters

| Parameter | Type | Default value | | ------ | ------ | ------ | | value | unknown | undefined | | assert | boolean | false |

Returns

BrandedAddress | undefined

asEthAddress

@xylabs/hex

Call Signature

function asEthAddress(value: unknown): EthAddress | undefined;

Attempts to coerce a value into an EthAddress, returning undefined or throwing based on the assert config.

Parameters

| Parameter | Type | Description | | ------ | ------ | ------ | | value | unknown | The value to coerce (must be a string) |

Returns

EthAddress | undefined

The value as EthAddress, or undefined if coercion fails and assert is not set

Call Signature

function asEthAddress(value: unknown, assert: AssertConfig): EthAddress;

Attempts to coerce a value into an EthAddress, returning undefined or throwing based on the assert config.

Parameters

| Parameter | Type | Description | | ------ | ------ | ------ | | value | unknown | The value to coerce (must be a string) | | assert | AssertConfig | If provided, throws on failure instead of returning undefined |

Returns

EthAddress

The value as EthAddress, or undefined if coercion fails and assert is not set

asHash

@xylabs/hex

Call Signature

function asHash(value: unknown): BrandedHash | undefined;

Attempts to coerce a value into a Hash type, returning undefined or throwing based on the assert config.

Parameters

| Parameter | Type | Description | | ------ | ------ | ------ | | value | unknown | The value to coerce (must be a string) |

Returns

BrandedHash | undefined

The value as Hash, or undefined if coercion fails and assert is not set

Call Signature

function asHash(value: unknown, assert: AssertConfig): BrandedHash;

Attempts to coerce a value into a Hash type, returning undefined or throwing based on the assert config.

Parameters

| Parameter | Type | Description | | ------ | ------ | ------ | | value | unknown | The value to coerce (must be a string) | | assert | AssertConfig | If provided, throws on failure instead of returning undefined |

Returns

BrandedHash

The value as Hash, or undefined if coercion fails and assert is not set

asHex

@xylabs/hex

Call Signature

function asHex(value: unknown): BrandedHex | undefined;

Attempts to coerce a value into a Hex type, returning undefined or throwing based on the assert config.

Parameters

| Parameter | Type | Description | | ------ | ------ | ------ | | value | unknown | The value to coerce (must be a string) |

Returns

BrandedHex | undefined

The value as Hex, or undefined if coercion fails and assert is not set

Call Signature

function asHex(value: unknown, assert: AssertConfig): BrandedHex;

Attempts to coerce a value into a Hex type, returning undefined or throwing based on the assert config.

Parameters

| Parameter | Type | Description | | ------ | ------ | ------ | | value | unknown | The value to coerce (must be a string) | | assert | AssertConfig | If provided, throws on failure instead of returning undefined |

Returns

BrandedHex

The value as Hex, or undefined if coercion fails and assert is not set

bitsToNibbles

@xylabs/hex

function bitsToNibbles(value: number): number;

Converts a bit count to the equivalent number of hex nibbles (4 bits each).

Parameters

| Parameter | Type | Description | | ------ | ------ | ------ | | value | number | The number of bits (must be a multiple of 4) |

Returns

number

The number of nibbles

hexFrom

@xylabs/hex

function hexFrom(value: string | number | bigint | ArrayBufferLike, config?: HexConfig): BrandedHex;

Takes unknown value and tries our best to convert it to a hex string

Parameters

| Parameter | Type | Description | | ------ | ------ | ------ | | value | string | number | bigint | ArrayBufferLike | Supported types are string, number, bigint, and ArrayBuffer | | config? | HexConfig | Configuration of output format and validation |

Returns

BrandedHex

hexFromArrayBuffer

@xylabs/hex

function hexFromArrayBuffer(buffer: ArrayBufferLike, config?: HexConfig): BrandedHex;

Convert an ArrayBuffer to a hex string

Parameters

| Parameter | Type | Description | | ------ | ------ | ------ | | buffer | ArrayBufferLike | The buffer to be converted | | config? | HexConfig | Configuration of output format and validation |

Returns

BrandedHex

hexFromBigInt

@xylabs/hex

function hexFromBigInt(value: bigint, config?: HexConfig): BrandedHex;

Convert a bigint to a hex string

Parameters

| Parameter | Type | Description | | ------ | ------ | ------ | | value | bigint | The bigint to be converted | | config | HexConfig | Configuration of output format and validation |

Returns

BrandedHex

hexFromHexString

@xylabs/hex

function hexFromHexString(value: string, config?: HexConfig): BrandedHex;

Normalizes a hex string by stripping an optional 0x prefix, lowercasing, and padding to byte/bit boundaries.

Parameters

| Parameter | Type | Description | | ------ | ------ | ------ | | value | string | The hex string to normalize (with or without 0x prefix) | | config | HexConfig | Configuration for prefix, byteSize, and bitLength padding |

Returns

BrandedHex

The normalized Hex string

hexFromNumber

@xylabs/hex

function hexFromNumber(value: number, config?: HexConfig): BrandedHex;

Converts a number to a hex string by converting to BigInt first.

Parameters

| Parameter | Type | Description | | ------ | ------ | ------ | | value | number | The number to convert | | config? | HexConfig | Optional hex output configuration |

Returns

BrandedHex

The hex string representation

hexToBigInt

@xylabs/hex

function hexToBigInt(hex: BrandedHex): bigint;

Converts a Hex string to a BigInt.

Parameters

| Parameter | Type | Description | | ------ | ------ | ------ | | hex | BrandedHex | The hex string to convert |

Returns

bigint

The BigInt representation of the hex value

isAddress

@xylabs/hex

function isAddress(value: unknown, config?: HexConfig): value is BrandedAddress;

Type guard that checks whether a value is a valid 160-bit address.

Parameters

| Parameter | Type | Description | | ------ | ------ | ------ | | value | unknown | The value to check | | config | HexConfig | Optional hex config (defaults to 160-bit, no prefix) |

Returns

value is BrandedAddress

True if the value is a valid Address

isAddressV2

@xylabs/hex

function isAddressV2(value: unknown): value is BrandedAddress;

Alpha

Parameters

| Parameter | Type | | ------ | ------ | | value | unknown |

Returns

value is BrandedAddress

isEthAddress

@xylabs/hex

function isEthAddress(value: unknown, config?: HexConfig): value is EthAddress;

Type guard that checks whether a value is a valid 0x-prefixed Ethereum address.

Parameters

| Parameter | Type | Description | | ------ | ------ | ------ | | value | unknown | The value to check | | config | HexConfig | Optional hex config (defaults to 160-bit with prefix) |

Returns

value is EthAddress

True if the value is a valid EthAddress

isHash

@xylabs/hex

function isHash(value: unknown, bitLength?: HashBitLength): value is BrandedHash;

Type guard that checks whether a value is a valid hash of the specified bit length.

Parameters

| Parameter | Type | Default value | Description | | ------ | ------ | ------ | ------ | | value | unknown | undefined | The value to check | | bitLength | HashBitLength | 256 | The expected bit length of the hash (defaults to 256) |

Returns

value is BrandedHash

True if the value is a valid Hash

isHashBitLength

@xylabs/hex

function isHashBitLength(value: unknown): value is HashBitLength;

Type guard that checks whether a value is a valid hash bit length.

Parameters

| Parameter | Type | Description | | ------ | ------ | ------ | | value | unknown | The value to check |

Returns

value is HashBitLength

True if the value is one of the supported HashBitLength values

isHex

@xylabs/hex

function isHex(value: unknown, config?: HexConfig): value is BrandedHex;

Type guard that checks whether a value is a valid hex string.

Parameters

| Parameter | Type | Description | | ------ | ------ | ------ | | value | unknown | The value to check | | config? | HexConfig | Optional configuration for prefix and bit length validation |

Returns

value is BrandedHex

True if the value is a valid Hex string

isHexZero

@xylabs/hex

function isHexZero(value?: string): boolean | undefined;

Checks whether a hex string represents a zero value.

Parameters

| Parameter | Type | Description | | ------ | ------ | ------ | | value? | string | The hex string to check |

Returns

boolean | undefined

True if zero, false if non-zero, or undefined if the input is not a string

nibblesToBits

@xylabs/hex

function nibblesToBits(value: number): number;

Converts a nibble count to the equivalent number of bits.

Parameters

| Parameter | Type | Description | | ------ | ------ | ------ | | value | number | The number of nibbles |

Returns

number

The number of bits

toAddress

@xylabs/hex

function toAddress(value: string | number | bigint | ArrayBufferLike, config?: HexConfig): BrandedAddress;

Converts a value to a 160-bit Address hex string.

Parameters

| Parameter | Type | Description | | ------ | ------ | ------ | | value | string | number | bigint | ArrayBufferLike | The value to convert (string, number, bigint, or ArrayBuffer) | | config | HexConfig | Optional hex config (defaults to 160-bit, no prefix) |

Returns

BrandedAddress

The value as an Address

toAddressV2

@xylabs/hex

function toAddressV2(value: unknown, assert?: boolean): BrandedAddress | undefined;

Alpha

Parameters

| Parameter | Type | Default value | | ------ | ------ | ------ | | value | unknown | undefined | | assert | boolean | false |

Returns

BrandedAddress | undefined

toEthAddress

@xylabs/hex

function toEthAddress(value: string | number | bigint | ArrayBufferLike, config?: HexConfig): EthAddress;

Converts a value to a 0x-prefixed Ethereum address string.

Parameters

| Parameter | Type | Description | | ------ | ------ | ------ | | value | string | number | bigint | ArrayBufferLike | The value to convert (string, number, bigint, or ArrayBuffer) | | config | HexConfig | Optional hex config (defaults to 160-bit, no inner prefix) |

Returns

EthAddress

The value as an EthAddress

toHex

@xylabs/hex

function toHex(value: string | number | bigint | ArrayBufferLike, config?: HexConfig): BrandedHex;

takes any value and tries our best to convert it to a hex string

Parameters

| Parameter | Type | Description | | ------ | ------ | ------ | | value | string | number | bigint | ArrayBufferLike | Supported types are string, number, bigint, and ArrayBuffer | | config | HexConfig | Configuration of output format and validation |

Returns

BrandedHex

toHexLegacy

@xylabs/hex

function toHexLegacy(buffer: ArrayBuffer): string;

Converts an ArrayBuffer to a hex string without padding or normalization.

Parameters

| Parameter | Type | Description | | ------ | ------ | ------ | | buffer | ArrayBuffer | The ArrayBuffer to convert |

Returns

string

A lowercase hex string representation of the buffer

interfaces

HexConfig

@xylabs/hex

Configuration of validation and output format

Properties

| Property | Type | | ------ | ------ | | bitLength? | number | | byteSize? | number | | prefix? | boolean |

type-aliases

Address

@xylabs/hex

type Address = z.infer<typeof AddressZod>;

A validated 20-byte address string type, inferred from the AddressZod schema.

AddressTransformZodType

@xylabs/hex

type AddressTransformZodType = z.infer<typeof AddressTransformZod>;

The output type of AddressTransformZod after parsing and transformation.

AddressValidationZodType

@xylabs/hex

type AddressValidationZodType = z.infer<typeof AddressValidationZod>;

The output type of AddressValidationZod after parsing.

BrandedHash

@xylabs/hex

type BrandedHash = Brand<Hex, {
  __hash: true;
}>;

Branded type representing a validated hash hex string.

BrandedHex

@xylabs/hex

type BrandedHex = Brand<Lowercase<string>, {
  __hex: true;
}>;

Branded type representing a validated lowercase hex string.

EthAddress

@xylabs/hex

type EthAddress = Brand<string, {
  __eth_address: true;
}>;

Branded type representing a validated Ethereum address with 0x prefix.

Hash

@xylabs/hex

type Hash = z.infer<typeof HashZod>;

A validated hash string type, inferred from the HashZod schema.

HashBitLength

@xylabs/hex

type HashBitLength = 32 | 64 | 128 | 256 | 512 | 1024 | 2048 | 4096;

Valid bit lengths for hash values.

Hex

@xylabs/hex

type Hex = z.infer<typeof HexZod>;

A validated hex string type, inferred from the HexZod schema.

variables

ADDRESS_LENGTH

@xylabs/hex

const ADDRESS_LENGTH: 40;

The character length of an address hex string (40 hex characters / 20 bytes).

AddressRegEx

@xylabs/hex

const AddressRegEx: RegExp;

Regular expression matching a 20-byte (40 hex character) address string.

AddressTransformZod

@xylabs/hex

const AddressTransformZod: ZodPipe<ZodPipe<ZodUnion<readonly [ZodString, ZodBigInt, ZodNumber]>, ZodTransform<string, string | number | bigint>>, ZodTransform<BrandedAddress, string>>;

Zod schema that accepts a string, bigint, or number and transforms it into a validated Address.

AddressValidationZod

@xylabs/hex

const AddressValidationZod: ZodPipe<ZodString, ZodTransform<BrandedAddress, string>>;

Zod schema that validates a string is a properly formatted 40-character hex address.

AddressZod

@xylabs/hex

const AddressZod: ZodPipe<ZodString, ZodTransform<BrandedAddress, string>>;

Zod schema that validates and transforms a string into a branded Address type.

BigIntToJsonZod

@xylabs/hex

const BigIntToJsonZod: ZodPipe<ZodBigInt, ZodTransform<BrandedHex, bigint>>;

Zod schema that transforms a non-negative BigInt into a hex string for JSON serialization.

ETH_ZERO_ADDRESS

@xylabs/hex

const ETH_ZERO_ADDRESS: EthAddress;

The zero Ethereum address constant (0x followed by 40 zero characters).

EthAddressFromStringSchema

@xylabs/hex

const EthAddressFromStringSchema: ZodPipe<ZodString, ZodTransform<EthAddress, string>> = EthAddressFromStringZod;

Deprecated

use EthAddressFromStringZod

EthAddressFromStringZod

@xylabs/hex

const EthAddressFromStringZod: ZodPipe<ZodString, ZodTransform<EthAddress, string>>;

Zod schema that validates and transforms a string into an EthAddress type.

EthAddressRegEx

@xylabs/hex

const EthAddressRegEx: RegExp;

Regular expression matching a 20-byte Ethereum address with 0x prefix (mixed case).

EthAddressToStringSchema

@xylabs/hex

const EthAddressToStringSchema: ZodString = EthAddressToStringZod;

Deprecated

use EthAddressToStringZod

EthAddressToStringZod

@xylabs/hex

const EthAddressToStringZod: ZodString;

Zod schema that validates a string is a properly formatted Ethereum address.

EthAddressZod

@xylabs/hex

const EthAddressZod: ZodString & ZodType<EthAddress, string, $ZodTypeInternals<EthAddress, string>>;

Zod schema that validates a string as a properly formatted Ethereum address using regex and type guard.

HASH_LENGTH

@xylabs/hex

const HASH_LENGTH: 32;

The byte length of a standard hash (32 bytes / 256 bits).

HashBitLength

@xylabs/hex

HashBitLength: HashBitLength[];

Array of all valid hash bit lengths for runtime validation.

HashRegEx

@xylabs/hex

const HashRegEx: RegExp;

Regular expression matching a 32-byte (64 hex character) hash string.

HashToJsonZod

@xylabs/hex

const HashToJsonZod: ZodPipe<ZodPipe<ZodString, ZodTransform<BrandedHash, string>>, ZodTransform<string, BrandedHash>>;

Zod schema that transforms a Hash to a plain string for JSON serialization.

HashZod

@xylabs/hex

const HashZod: ZodPipe<ZodString, ZodTransform<BrandedHash, string>>;

Zod schema that validates and transforms a string into a branded Hash type.

HexRegEx

@xylabs/hex

const HexRegEx: RegExp;

Regular expression matching a lowercase hex string without prefix.

HexRegExWithPrefix

@xylabs/hex

const HexRegExWithPrefix: RegExp;

Regular expression matching a lowercase hex string with a 0x prefix.

HexZod

@xylabs/hex

const HexZod: ZodPipe<ZodString, ZodTransform<BrandedHex, string>>;

Zod schema that validates and transforms a string into a branded Hex type.

JsonToBigIntZod

@xylabs/hex

const JsonToBigIntZod: ZodPipe<ZodPipe<ZodString, ZodTransform<BrandedHex, string>>, ZodTransform<bigint, BrandedHex>>;

Zod schema that parses a JSON hex string into a BigInt.

JsonToHashZod

@xylabs/hex

const JsonToHashZod: ZodPipe<ZodString, ZodTransform<BrandedHash, string>>;

Zod schema that parses a JSON string into a validated Hash, throwing on invalid input.

ZERO_ADDRESS

@xylabs/hex

const ZERO_ADDRESS: BrandedAddress;

A 160-bit zero address constant.

ZERO_HASH

@xylabs/hex

const ZERO_HASH: BrandedHash;

A 256-bit zero hash constant.

Part of sdk-js

Maintainers

• Arie Trouw (arietrouw.com)
• Matt Jones
• Joel Carter
• Jordan Trouw

License

See the LICENSE file for license details

Credits

Made with 🔥 and ❄️ by XYLabs