@tevm/voltaire / primitives/TokenBalance

primitives/TokenBalance

Classes

InvalidTokenBalanceError

Defined in: src/primitives/TokenBalance/errors.ts:23 Base validation error

Example

throw new ValidationError('Invalid value', {
  value: '0x123',
  expected: '20 bytes',
  code: 'VALIDATION_ERROR',
  docsPath: '/primitives/address/from-hex#error-handling',
  cause: originalError
})

Extends

ValidationError

Constructors

Constructor

new InvalidTokenBalanceError(message, options?): InvalidTokenBalanceError

Defined in: src/primitives/TokenBalance/errors.ts:24

Parameters

message

string

options?

cause?

Error

code?

string

context?

Record<string, unknown>

docsPath?

string

expected?

string

value?

unknown

Returns

InvalidTokenBalanceError

Overrides

ValidationError.constructor

Properties

cause?

optional cause: Error

Defined in: src/primitives/errors/AbstractError.ts:56 Root cause of this error (for error chaining)

Inherited from

ValidationError.cause

code

code: string

Defined in: src/primitives/errors/AbstractError.ts:39 Machine-readable error code for programmatic handling

Example

'INVALID_FORMAT', 'INVALID_LENGTH'

Inherited from

ValidationError.code

context?

optional context: Record<string, unknown>

Defined in: src/primitives/errors/AbstractError.ts:45 Additional context metadata for debugging

Example

{ value: '0x123', expected: '20 bytes' }

Inherited from

ValidationError.context

docsPath?

optional docsPath: string

Defined in: src/primitives/errors/AbstractError.ts:51 Path to documentation for this error

Example

'/primitives/address/from-hex#error-handling'

Inherited from

ValidationError.docsPath

expected

expected: string

Defined in: src/primitives/errors/ValidationError.ts:19

Inherited from

ValidationError.expected

value

value: unknown

Defined in: src/primitives/errors/ValidationError.ts:18

Inherited from

ValidationError.value

Methods

getErrorChain()

getErrorChain(): string

Defined in: src/primitives/errors/AbstractError.ts:94 Get full error chain as string for logging

Returns

string

Inherited from

ValidationError.getErrorChain

toJSON()

toJSON(): Record<string, unknown>

Defined in: src/primitives/errors/AbstractError.ts:110 Serialize error to JSON for logging/telemetry

Returns

Record<string, unknown>

Inherited from

ValidationError.toJSON

TokenBalanceError

Defined in: src/primitives/TokenBalance/errors.ts:3 Base error for all primitive-related errors

Example

throw new PrimitiveError('Invalid primitive value', {
  code: 'INVALID_PRIMITIVE',
  context: { value: '0x123' },
  docsPath: '/primitives/overview#errors'
})

Extends

PrimitiveError

Constructors

Constructor

new TokenBalanceError(message, options?): TokenBalanceError

Defined in: src/primitives/TokenBalance/errors.ts:4

Parameters

message

string

options?

cause?

Error

code?

string

context?

Record<string, unknown>

docsPath?

string

Returns

TokenBalanceError

Overrides

PrimitiveError.constructor

Properties

cause?

optional cause: Error

Defined in: src/primitives/errors/AbstractError.ts:56 Root cause of this error (for error chaining)

Inherited from

PrimitiveError.cause

code

code: string

Defined in: src/primitives/errors/AbstractError.ts:39 Machine-readable error code for programmatic handling

Example

'INVALID_FORMAT', 'INVALID_LENGTH'

Inherited from

PrimitiveError.code

context?

optional context: Record<string, unknown>

Defined in: src/primitives/errors/AbstractError.ts:45 Additional context metadata for debugging

Example

{ value: '0x123', expected: '20 bytes' }

Inherited from

PrimitiveError.context

docsPath?

optional docsPath: string

Defined in: src/primitives/errors/AbstractError.ts:51 Path to documentation for this error

Example

'/primitives/address/from-hex#error-handling'

Inherited from

PrimitiveError.docsPath

Methods

getErrorChain()

getErrorChain(): string

Defined in: src/primitives/errors/AbstractError.ts:94 Get full error chain as string for logging

Returns

string

Inherited from

PrimitiveError.getErrorChain

toJSON()

toJSON(): Record<string, unknown>

Defined in: src/primitives/errors/AbstractError.ts:110 Serialize error to JSON for logging/telemetry

Returns

Record<string, unknown>

Inherited from

PrimitiveError.toJSON

TokenBalanceOverflowError

Defined in: src/primitives/TokenBalance/errors.ts:47 Base validation error

Example

throw new ValidationError('Invalid value', {
  value: '0x123',
  expected: '20 bytes',
  code: 'VALIDATION_ERROR',
  docsPath: '/primitives/address/from-hex#error-handling',
  cause: originalError
})

Extends

ValidationError

Constructors

Constructor

new TokenBalanceOverflowError(message, options?): TokenBalanceOverflowError

Defined in: src/primitives/TokenBalance/errors.ts:48

Parameters

message

string

options?

cause?

Error

code?

string

context?

Record<string, unknown>

docsPath?

string

expected?

string

value?

unknown

Returns

TokenBalanceOverflowError

Overrides

ValidationError.constructor

Properties

cause?

optional cause: Error

Defined in: src/primitives/errors/AbstractError.ts:56 Root cause of this error (for error chaining)

Inherited from

ValidationError.cause

code

code: string

Defined in: src/primitives/errors/AbstractError.ts:39 Machine-readable error code for programmatic handling

Example

'INVALID_FORMAT', 'INVALID_LENGTH'

Inherited from

ValidationError.code

context?

optional context: Record<string, unknown>

Defined in: src/primitives/errors/AbstractError.ts:45 Additional context metadata for debugging

Example

{ value: '0x123', expected: '20 bytes' }

Inherited from

ValidationError.context

docsPath?

optional docsPath: string

Defined in: src/primitives/errors/AbstractError.ts:51 Path to documentation for this error

Example

'/primitives/address/from-hex#error-handling'

Inherited from

ValidationError.docsPath

expected

expected: string

Defined in: src/primitives/errors/ValidationError.ts:19

Inherited from

ValidationError.expected

value

value: unknown

Defined in: src/primitives/errors/ValidationError.ts:18

Inherited from

ValidationError.value

Methods

getErrorChain()

getErrorChain(): string

Defined in: src/primitives/errors/AbstractError.ts:94 Get full error chain as string for logging

Returns

string

Inherited from

ValidationError.getErrorChain

toJSON()

toJSON(): Record<string, unknown>

Defined in: src/primitives/errors/AbstractError.ts:110 Serialize error to JSON for logging/telemetry

Returns

Record<string, unknown>

Inherited from

ValidationError.toJSON

Type Aliases

TokenBalanceType

TokenBalanceType = bigint & object

Defined in: src/primitives/TokenBalance/TokenBalanceType.ts:10 TokenBalance type - ERC-20 token balance

Type Declaration

[brand]

readonly [brand]: "TokenBalance"

See

https://voltaire.tevm.sh/primitives/token-balance for TokenBalance documentation
https://eips.ethereum.org/EIPS/eip-20 for ERC-20 specification

Since

0.0.0

Variables

compare()

const compare: (a, b) => number = _compare

Defined in: src/primitives/TokenBalance/index.ts:34 Compare two TokenBalance values

Parameters

a

TokenBalanceType First TokenBalance

b

TokenBalanceType Second TokenBalance

Returns

number -1 if a < b, 0 if a === b, 1 if a > b

See

https://voltaire.tevm.sh/primitives/token-balance for TokenBalance documentation

Since

0.0.0

Example

import * as TokenBalance from './primitives/TokenBalance/index.js';
const a = TokenBalance.from(100n);
const b = TokenBalance.from(200n);
const result = TokenBalance.compare(a, b); // -1

constants

const constants: object

Defined in: src/primitives/TokenBalance/index.ts:40

Type Declaration

DECIMALS

DECIMALS: object

Common decimal counts for ERC-20 tokens

DECIMALS.DAI

DAI: number = 18

DECIMALS.ETH

ETH: number = 18

DECIMALS.USDC

USDC: number = 6

DECIMALS.USDT

USDT: number = 6

DECIMALS.WBTC

WBTC: number = 8

DECIMALS.WETH

WETH: number = 18

MAX

MAX: bigint

Maximum TokenBalance value (2^256 - 1)

MIN

MIN: bigint

Minimum TokenBalance value (0)

equals()

const equals: (a, b) => boolean = _equals

Defined in: src/primitives/TokenBalance/index.ts:33 Check if two TokenBalance values are equal

Parameters

a

TokenBalanceType First TokenBalance

b

TokenBalanceType Second TokenBalance

Returns

boolean true if equal

See

https://voltaire.tevm.sh/primitives/token-balance for TokenBalance documentation

Since

0.0.0

Example

import * as TokenBalance from './primitives/TokenBalance/index.js';
const a = TokenBalance.from(100n);
const b = TokenBalance.from(100n);
const result = TokenBalance.equals(a, b); // true

ERC20_SELECTORS

const ERC20_SELECTORS: object

Defined in: src/primitives/TokenBalance/index.ts:47

Type Declaration

allowance

readonly allowance: "0xdd62ed3e" = "0xdd62ed3e"

approve

readonly approve: "0x095ea7b3" = "0x095ea7b3"

balanceOf

readonly balanceOf: "0x70a08231" = "0x70a08231"

totalSupply

readonly totalSupply: "0x18160ddd" = "0x18160ddd"

transfer

readonly transfer: "0xa9059cbb" = "0xa9059cbb"

transferFrom

readonly transferFrom: "0x23b872dd" = "0x23b872dd"

format()

const format: (balance, decimals, maxDecimals?) => string = _format

Defined in: src/primitives/TokenBalance/index.ts:35 Format TokenBalance for display with decimals

Parameters

balance

TokenBalanceType TokenBalance value

decimals

number Number of decimal places (e.g., 18 for ETH, 6 for USDC)

maxDecimals?

number Maximum decimal places to display (for rounding)

Returns

string Formatted string (e.g., “1.234567”)

See

https://voltaire.tevm.sh/primitives/token-balance for TokenBalance documentation

Since

0.0.0

Example

import * as TokenBalance from './primitives/TokenBalance/index.js';
const balance = TokenBalance.from(1234567890123456789n);
const formatted = TokenBalance.format(balance, 18); // "1.234567890123456789"
const rounded = TokenBalance.format(balance, 18, 6); // "1.234568"

from()

const from: (value) => TokenBalanceType = _from

Defined in: src/primitives/TokenBalance/index.ts:29 Create TokenBalance from bigint, number, or string

Parameters

value

bigint, number, or decimal/hex string string | number | bigint

Returns

TokenBalanceType TokenBalance value

See

https://voltaire.tevm.sh/primitives/token-balance for TokenBalance documentation

Since

0.0.0

Throws

If value is out of range or invalid

Example

import * as TokenBalance from './primitives/TokenBalance/index.js';
const balance = TokenBalance.from(1000000000000000000n); // 1 token with 18 decimals
const fromNumber = TokenBalance.from(100);
const fromHex = TokenBalance.from("0xff");

fromBaseUnit()

const fromBaseUnit: (amount, decimals) => TokenBalanceType = _fromBaseUnit

Defined in: src/primitives/TokenBalance/index.ts:36 Convert from human-readable base unit to raw TokenBalance

Parameters

amount

string Human-readable amount (e.g., “1.5” for 1.5 tokens)

decimals

number Number of decimal places (e.g., 18 for ETH, 6 for USDC)

Returns

TokenBalanceType TokenBalance value

See

https://voltaire.tevm.sh/primitives/token-balance for TokenBalance documentation

Since

0.0.0

Throws

If amount format is invalid

Example

import * as TokenBalance from './primitives/TokenBalance/index.js';
const balance = TokenBalance.fromBaseUnit("1.5", 18); // 1500000000000000000n
const usdc = TokenBalance.fromBaseUnit("100.5", 6); // 100500000n

toBaseUnit()

const toBaseUnit: (balance) => bigint = _toBaseUnit

Defined in: src/primitives/TokenBalance/index.ts:37 Convert TokenBalance to base unit bigint (raw value)

Parameters

balance

TokenBalanceType TokenBalance value

Returns

bigint Raw bigint value

See

https://voltaire.tevm.sh/primitives/token-balance for TokenBalance documentation

Since

0.0.0

Example

import * as TokenBalance from './primitives/TokenBalance/index.js';
const balance = TokenBalance.from(1500000000000000000n);
const raw = TokenBalance.toBaseUnit(balance); // 1500000000000000000n

toBigInt()

const toBigInt: (balance) => bigint = _toBigInt

Defined in: src/primitives/TokenBalance/index.ts:31 Convert TokenBalance to bigint

Parameters

balance

TokenBalanceType TokenBalance value to convert

Returns

bigint bigint value

See

https://voltaire.tevm.sh/primitives/token-balance for TokenBalance documentation

Since

0.0.0

Example

import * as TokenBalance from './primitives/TokenBalance/index.js';
const balance = TokenBalance.from(1000000n);
const bigint = TokenBalance.toBigInt(balance); // 1000000n

toHex()

const toHex: (balance) => string = _toHex

Defined in: src/primitives/TokenBalance/index.ts:32 Convert TokenBalance to hex string

Parameters

balance

TokenBalanceType TokenBalance value to convert

Returns

string Hex string with 0x prefix

See

https://voltaire.tevm.sh/primitives/token-balance for TokenBalance documentation

Since

0.0.0

Example

import * as TokenBalance from './primitives/TokenBalance/index.js';
const balance = TokenBalance.from(255n);
const hex = TokenBalance.toHex(balance); // "0xff"

toNumber()

const toNumber: (balance) => number = _toNumber

Defined in: src/primitives/TokenBalance/index.ts:30 Convert TokenBalance to number (unsafe for large values)

Parameters

balance

TokenBalanceType TokenBalance value to convert

Returns

number number value

See

https://voltaire.tevm.sh/primitives/token-balance for TokenBalance documentation

Since

0.0.0

Throws

If value exceeds Number.MAX_SAFE_INTEGER

Example

import * as TokenBalance from './primitives/TokenBalance/index.js';
const balance = TokenBalance.from(100n);
const num = TokenBalance.toNumber(balance); // 100

Functions

_compare()

_compare(a, b): number

Defined in: src/primitives/TokenBalance/compare.js:17 Compare two TokenBalance values

Parameters

a

TokenBalanceType First TokenBalance

b

TokenBalanceType Second TokenBalance

Returns

number -1 if a < b, 0 if a === b, 1 if a > b

See

https://voltaire.tevm.sh/primitives/token-balance for TokenBalance documentation

Since

0.0.0

Example

import * as TokenBalance from './primitives/TokenBalance/index.js';
const a = TokenBalance.from(100n);
const b = TokenBalance.from(200n);
const result = TokenBalance.compare(a, b); // -1

_equals()

_equals(a, b): boolean

Defined in: src/primitives/TokenBalance/equals.js:17 Check if two TokenBalance values are equal

Parameters

a

TokenBalanceType First TokenBalance

b

TokenBalanceType Second TokenBalance

Returns

boolean true if equal

See

https://voltaire.tevm.sh/primitives/token-balance for TokenBalance documentation

Since

0.0.0

Example

import * as TokenBalance from './primitives/TokenBalance/index.js';
const a = TokenBalance.from(100n);
const b = TokenBalance.from(100n);
const result = TokenBalance.equals(a, b); // true

_format()

_format(balance, decimals, maxDecimals?): string

Defined in: src/primitives/TokenBalance/format.js:18 Format TokenBalance for display with decimals

Parameters

balance

TokenBalanceType TokenBalance value

decimals

number Number of decimal places (e.g., 18 for ETH, 6 for USDC)

maxDecimals?

number Maximum decimal places to display (for rounding)

Returns

string Formatted string (e.g., “1.234567”)

See

https://voltaire.tevm.sh/primitives/token-balance for TokenBalance documentation

Since

0.0.0

Example

import * as TokenBalance from './primitives/TokenBalance/index.js';
const balance = TokenBalance.from(1234567890123456789n);
const formatted = TokenBalance.format(balance, 18); // "1.234567890123456789"
const rounded = TokenBalance.format(balance, 18, 6); // "1.234568"

_from()

_from(value): TokenBalanceType

Defined in: src/primitives/TokenBalance/from.js:20 Create TokenBalance from bigint, number, or string

Parameters

value

bigint, number, or decimal/hex string string | number | bigint

Returns

TokenBalanceType TokenBalance value

See

https://voltaire.tevm.sh/primitives/token-balance for TokenBalance documentation

Since

0.0.0

Throws

If value is out of range or invalid

Example

import * as TokenBalance from './primitives/TokenBalance/index.js';
const balance = TokenBalance.from(1000000000000000000n); // 1 token with 18 decimals
const fromNumber = TokenBalance.from(100);
const fromHex = TokenBalance.from("0xff");

_fromBaseUnit()

_fromBaseUnit(amount, decimals): TokenBalanceType

Defined in: src/primitives/TokenBalance/fromBaseUnit.js:19 Convert from human-readable base unit to raw TokenBalance

Parameters

amount

string Human-readable amount (e.g., “1.5” for 1.5 tokens)

decimals

number Number of decimal places (e.g., 18 for ETH, 6 for USDC)

Returns

TokenBalanceType TokenBalance value

See

https://voltaire.tevm.sh/primitives/token-balance for TokenBalance documentation

Since

0.0.0

Throws

If amount format is invalid

Example

import * as TokenBalance from './primitives/TokenBalance/index.js';
const balance = TokenBalance.fromBaseUnit("1.5", 18); // 1500000000000000000n
const usdc = TokenBalance.fromBaseUnit("100.5", 6); // 100500000n

_toBaseUnit()

_toBaseUnit(balance): bigint

Defined in: src/primitives/TokenBalance/toBaseUnit.js:15 Convert TokenBalance to base unit bigint (raw value)

Parameters

balance

TokenBalanceType TokenBalance value

Returns

bigint Raw bigint value

See

https://voltaire.tevm.sh/primitives/token-balance for TokenBalance documentation

Since

0.0.0

Example

import * as TokenBalance from './primitives/TokenBalance/index.js';
const balance = TokenBalance.from(1500000000000000000n);
const raw = TokenBalance.toBaseUnit(balance); // 1500000000000000000n

_toBigInt()

_toBigInt(balance): bigint

Defined in: src/primitives/TokenBalance/toBigInt.js:15 Convert TokenBalance to bigint

Parameters

balance

TokenBalanceType TokenBalance value to convert

Returns

bigint bigint value

See

https://voltaire.tevm.sh/primitives/token-balance for TokenBalance documentation

Since

0.0.0

Example

import * as TokenBalance from './primitives/TokenBalance/index.js';
const balance = TokenBalance.from(1000000n);
const bigint = TokenBalance.toBigInt(balance); // 1000000n

_toHex()

_toHex(balance): string

Defined in: src/primitives/TokenBalance/toHex.js:15 Convert TokenBalance to hex string

Parameters

balance

TokenBalanceType TokenBalance value to convert

Returns

string Hex string with 0x prefix

See

https://voltaire.tevm.sh/primitives/token-balance for TokenBalance documentation

Since

0.0.0

Example

import * as TokenBalance from './primitives/TokenBalance/index.js';
const balance = TokenBalance.from(255n);
const hex = TokenBalance.toHex(balance); // "0xff"

_toNumber()

_toNumber(balance): number

Defined in: src/primitives/TokenBalance/toNumber.js:16 Convert TokenBalance to number (unsafe for large values)

Parameters

balance

TokenBalanceType TokenBalance value to convert

Returns

number number value

See

https://voltaire.tevm.sh/primitives/token-balance for TokenBalance documentation

Since

0.0.0

Throws

If value exceeds Number.MAX_SAFE_INTEGER

Example

import * as TokenBalance from './primitives/TokenBalance/index.js';
const balance = TokenBalance.from(100n);
const num = TokenBalance.toNumber(balance); // 100

​primitives/TokenBalance

​Classes

​InvalidTokenBalanceError

​Example

​Extends

​Constructors

Constructor

Parameters

message

options?

cause?

code?

context?

docsPath?

expected?

value?

Returns

Overrides

​Properties

cause?

Inherited from

code

Example

Inherited from

context?

Example

Inherited from

docsPath?

Example

Inherited from

expected

Inherited from

value

Inherited from

​Methods

getErrorChain()

Returns

Inherited from

toJSON()

Returns

Inherited from

​TokenBalanceError

​Example

​Extends

​Constructors

Constructor

Parameters

message

options?

cause?

code?

context?

docsPath?

Returns

Overrides

​Properties

cause?

Inherited from

code

Example

Inherited from

context?

Example

Inherited from

docsPath?

Example

Inherited from

​Methods

getErrorChain()

Returns

Inherited from

toJSON()

Returns

Inherited from

​TokenBalanceOverflowError

​Example

​Extends

​Constructors

Constructor

Parameters

primitives/TokenBalance

Classes

InvalidTokenBalanceError

Example

Extends

Constructors

Properties

Methods

TokenBalanceError

Example

Extends

Constructors

Properties

Methods

TokenBalanceOverflowError

Example

Extends

Constructors

Properties

Methods

Type Aliases

TokenBalanceType

Type Declaration

See

Since

Variables

compare()

Parameters

Returns

See

Since

Example

constants

Type Declaration