Skip to main content

Try it Live

Run Base64 examples in the interactive playground

​
Usage Patterns

Practical patterns for Base64 encoding and decoding in Ethereum applications.

​
Data Encoding

​
Binary to Base64

import * as Base64 from 'tevm/Base64';

// Encode binary data
const binaryData = new Uint8Array([1, 2, 3, 4, 5]);
const encoded = Base64.encode(binaryData);
console.log(encoded);  // "AQIDBAU="

// Encode hex to Base64
import * as Hex from 'tevm/Hex';
const hexData = Hex("0x48656c6c6f");  // "Hello"
const base64 = Base64.encode(Hex.toBytes(hexData));
console.log(base64);  // "SGVsbG8="

​
String to Base64

// Encode UTF-8 string
function encodeString(str: string): BrandedBase64 {
  const bytes = new TextEncoder().encode(str);
  return Base64.encode(bytes);
}

const encoded = encodeString("Hello, Ethereum!");
// "SGVsbG8sIEV0aGVyZXVtIQ=="

​
Data Decoding

​
Base64 to Binary

// Decode to bytes
const decoded = Base64.decode(encoded);
console.log(Array(decoded));  // [1, 2, 3, 4, 5]

// Decode to hex
const hex = Hex(decoded);
console.log(Hex.toHex(hex));  // "0x0102030405"

​
Base64 to String

// Decode to UTF-8 string
function decodeString(base64: BrandedBase64): string {
  const bytes = Base64.decode(base64);
  return new TextDecoder().decode(bytes);
}

const text = decodeString(encoded);
console.log(text);  // "Hello, Ethereum!"

​
Validation

​
Input Validation

// Validate before decoding
function safeDecode(input: string): Uint8Array | null {
  if (!Base64.isValid(input)) {
    console.error("Invalid Base64 input");
    return null;
  }

  try {
    return Base64.decode(Base64(input));
  } catch (err) {
    console.error("Decoding failed:", err);
    return null;
  }
}

​
Format Checking

// Check if string is valid Base64
function isBase64String(str: string): boolean {
  return Base64.isValid(str);
}

// Validate and normalize
function normalizeBase64(input: string): BrandedBase64 {
  // Remove whitespace
  const cleaned = input.replace(/\s/g, '');

  if (!Base64.isValid(cleaned)) {
    throw new Error("Invalid Base64 format");
  }

  return Base64(cleaned);
}

​
API Integration

​
JSON Payload Encoding

interface APIPayload {
  data: string;  // Base64 encoded
  signature: string;  // Base64 encoded
}

function createPayload(
  data: Uint8Array,
  signature: Uint8Array
): APIPayload {
  return {
    data: Base64.encode(data),
    signature: Base64.encode(signature)
  };
}

function parsePayload(payload: APIPayload): {
  data: Uint8Array;
  signature: Uint8Array;
} {
  return {
    data: Base64.decode(Base64(payload.data)),
    signature: Base64.decode(Base64(payload.signature))
  };
}

​
URL-safe Encoding

// Convert standard Base64 to URL-safe
function toURLSafe(base64: BrandedBase64): string {
  return base64
    .replace(/\+/g, '-')
    .replace(/\//g, '_')
    .replace(/=+$/, '');  // Remove padding
}

// Convert URL-safe to standard Base64
function fromURLSafe(urlSafe: string): BrandedBase64 {
  let standard = urlSafe
    .replace(/-/g, '+')
    .replace(/_/g, '/');

  // Add padding
  const padding = (4 - (standard.length % 4)) % 4;
  standard += '='.repeat(padding);

  return Base64(standard);
}

​
Storage Patterns

​
Database Storage

// Store binary data as Base64 in database
async function storeBinaryData(
  db: Database,
  key: string,
  data: Uint8Array
): Promise<void> {
  const encoded = Base64.encode(data);
  await db.set(key, encoded);
}

async function loadBinaryData(
  db: Database,
  key: string
): Promise<Uint8Array | null> {
  const encoded = await db.get(key);
  if (!encoded) return null;

  return Base64.decode(Base64(encoded));
}

​
Configuration Files

// Encode keys for JSON config
interface Config {
  privateKey: string;  // Base64
  salt: string;  // Base64
}

function saveConfig(
  privateKey: Uint8Array,
  salt: Uint8Array
): Config {
  return {
    privateKey: Base64.encode(privateKey),
    salt: Base64.encode(salt)
  };
}

function loadConfig(config: Config): {
  privateKey: Uint8Array;
  salt: Uint8Array;
} {
  return {
    privateKey: Base64.decode(Base64(config.privateKey)),
    salt: Base64.decode(Base64(config.salt))
  };
}

​
Testing

​
Test Fixtures

const TEST_VECTORS = [
  { input: "", expected: "" },
  { input: "f", expected: "Zg==" },
  { input: "fo", expected: "Zm8=" },
  { input: "foo", expected: "Zm9v" },
  { input: "foob", expected: "Zm9vYg==" },
  { input: "fooba", expected: "Zm9vYmE=" },
  { input: "foobar", expected: "Zm9vYmFy" }
];

// Test encoding
TEST_VECTORS.forEach(({ input, expected }) => {
  const bytes = new TextEncoder().encode(input);
  const encoded = Base64.encode(bytes);
  console.assert(encoded === expected, `Encoding failed for: ${input}`);
});