bun install voltaire

import * as TokenBalance from '@tevm/voltaire/primitives/TokenBalance';

// Create from raw balance (wei-like units)
const balance = TokenBalance.from(1000000000000000000n); // 1 token with 18 decimals

// Format for display
console.log(TokenBalance.format(balance, 18)); // "1.0"

// Convert from human-readable amount
const amount = TokenBalance.fromBaseUnit("100.5", 6); // USDC (6 decimals)
console.log(amount); // 100500000n

// Compare balances
const a = TokenBalance.from(100n);
const b = TokenBalance.from(200n);
console.log(TokenBalance.compare(a, b)); // -1

const balance1 = TokenBalance.from(1000000000000000000n);
const balance2 = TokenBalance.from(100);
const balance3 = TokenBalance.from("0xff");
const balance4 = TokenBalance.from("1000000");

const balance = TokenBalance.from(100n);
const num = TokenBalance.toNumber(balance); // 100

const balance = TokenBalance.from(1000000n);
const bigint = TokenBalance.toBigInt(balance); // 1000000n

const balance = TokenBalance.from(255n);
const hex = TokenBalance.toHex(balance); // "0xff"

const balance = TokenBalance.from(1234567890123456789n);

// Full precision
TokenBalance.format(balance, 18); // "1.234567890123456789"

// Rounded to 6 decimals
TokenBalance.format(balance, 18, 6); // "1.234568"

// USDC (6 decimals)
const usdc = TokenBalance.from(100500000n);
TokenBalance.format(usdc, 6); // "100.5"

// ETH (18 decimals)
const eth = TokenBalance.fromBaseUnit("1.5", 18); // 1500000000000000000n

// USDC (6 decimals)
const usdc = TokenBalance.fromBaseUnit("100.5", 6); // 100500000n

// Integer amounts
const whole = TokenBalance.fromBaseUnit("100", 18); // 100000000000000000000n

// Fractional only
const fraction = TokenBalance.fromBaseUnit(".5", 18); // 500000000000000000n

const balance = TokenBalance.from(1500000000000000000n);
const raw = TokenBalance.toBaseUnit(balance); // 1500000000000000000n

const a = TokenBalance.from(100n);
const b = TokenBalance.from(100n);
TokenBalance.equals(a, b); // true

const a = TokenBalance.from(100n);
const b = TokenBalance.from(200n);
TokenBalance.compare(a, b); // -1

TokenBalance.constants.MAX; // 115792089237316195423570985008687907853269984665640564039457584007913129639935n

TokenBalance.constants.MIN; // 0n

TokenBalance.constants.DECIMALS.ETH;   // 18
TokenBalance.constants.DECIMALS.WETH;  // 18
TokenBalance.constants.DECIMALS.USDC;  // 6
TokenBalance.constants.DECIMALS.USDT;  // 6
TokenBalance.constants.DECIMALS.DAI;   // 18
TokenBalance.constants.DECIMALS.WBTC;  // 8

TokenBalance.ERC20_SELECTORS.balanceOf;     // "0x70a08231"
TokenBalance.ERC20_SELECTORS.transfer;      // "0xa9059cbb"
TokenBalance.ERC20_SELECTORS.approve;       // "0x095ea7b3"
TokenBalance.ERC20_SELECTORS.transferFrom;  // "0x23b872dd"
TokenBalance.ERC20_SELECTORS.totalSupply;   // "0x18160ddd"
TokenBalance.ERC20_SELECTORS.allowance;     // "0xdd62ed3e"

import * as TokenBalance from '@tevm/voltaire/primitives/TokenBalance';
import * as Address from '@tevm/voltaire/Address';

// Encode balanceOf call
const account = Address.from("0x742d35Cc6634C0532925a3b844Bc9e7595f251e3");
const data = encodeBalanceOf(account);

// Decode response
const balance = TokenBalance.from(response); // Raw balance from chain
const formatted = TokenBalance.format(balance, 18); // Format for display
console.log(`Balance: ${formatted} tokens`);

import * as TokenBalance from '@tevm/voltaire/primitives/TokenBalance';
import * as Address from '@tevm/voltaire/Address';

// Convert user input to raw amount
const amount = TokenBalance.fromBaseUnit("10.5", 18); // 10.5 tokens

const to = Address.from("0x...");
const data = encodeTransfer(to, amount);

const balance = TokenBalance.from(userBalance);
const required = TokenBalance.fromBaseUnit("5.0", 18);

if (TokenBalance.compare(balance, required) >= 0) {
  console.log("Sufficient balance");
} else {
  console.log("Insufficient balance");
}

import { InvalidTokenBalanceError } from '@tevm/voltaire/primitives/TokenBalance';

try {
  const balance = TokenBalance.from(-100n);
} catch (error) {
  if (error instanceof InvalidTokenBalanceError) {
    console.error("Invalid balance:", error.message);
  }
}

const balance: TokenBalance = 100n; // ❌ Type error
const balance = TokenBalance.from(100n); // ✅ Correct

function transfer(amount: TokenBalance) {
  // Type-safe: only TokenBalance accepted
}

transfer(100n); // ❌ Type error
transfer(TokenBalance.from(100n)); // ✅ Correct