CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-bs58

Base 58 encoding and decoding for cryptocurrency applications

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

SecuritybySnyk

Pending

The risk profile of this skill

Overview
Eval results
Files

index.mddocs/

bs58

bs58 is a JavaScript component for Base 58 encoding and decoding, specifically designed for cryptocurrency applications like Bitcoin and Litecoin. It provides a simple API with encode() and decode() methods for converting between binary data and Base 58 encoded strings using the Bitcoin alphabet.

Package Information

  • Package Name: bs58
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install bs58

Core Imports

import bs58 from "bs58";

For CommonJS:

const bs58 = require("bs58");

Destructured import:

import bs58 from "bs58";
const { encode, decode, decodeUnsafe } = bs58;

Basic Usage

import bs58 from "bs58";

// Encode binary data to Base58 string
const bytes = Uint8Array.from([
  0, 60,  23, 110, 101, 155, 234,
 15, 41, 163, 233, 191, 120, 128,
193, 18, 177, 179,  27,  77, 200,
 38, 38, 129, 135
]);
const address = bs58.encode(bytes);
console.log(address);
// => "16UjcYNBG9GTK4uq2f7yYEbuifqCzoLMGS"

// Decode Base58 string to binary data
const decoded = bs58.decode(address);
console.log(Buffer.from(decoded).toString('hex'));
// => "003c176e659bea0f29a3e9bf7880c112b1b31b4dc826268187"

Capabilities

Base58 Encoding

Encodes binary data to a Base58 string using the Bitcoin alphabet.

function encode(input: Uint8Array | Buffer | Array<number>): string;

Parameters:

  • input: Binary data as Uint8Array, Buffer, or Array of numbers

Returns: Base58-encoded string

Usage Example:

import bs58 from "bs58";

// From Uint8Array
const bytes = new Uint8Array([255, 128, 64, 32]);
const encoded = bs58.encode(bytes);

// From Buffer
const buffer = Buffer.from("hello world", "utf-8");
const encodedBuffer = bs58.encode(buffer);

// From Array
const array = [72, 101, 108, 108, 111];
const encodedArray = bs58.encode(array);

Base58 Decoding

Decodes a Base58 string back to binary data.

function decode(input: string): Uint8Array;

Parameters:

  • input: Base58-encoded string

Returns: Uint8Array containing the decoded binary data

Throws: Error with message "Non-base58 character" when input contains invalid characters

Usage Example:

import bs58 from "bs58";

try {
  const address = "16UjcYNBG9GTK4uq2f7yYEbuifqCzoLMGS";
  const decoded = bs58.decode(address);
  
  // Convert to hex string for display
  const hex = Buffer.from(decoded).toString('hex');
  console.log(hex);
  
  // Convert to regular array
  const array = Array.from(decoded);
  console.log(array);
} catch (error) {
  console.error("Invalid Base58 character:", error.message);
}

Safe Base58 Decoding

Safely decodes a Base58 string, returning undefined instead of throwing an error for invalid input.

function decodeUnsafe(input: string): Uint8Array | undefined;

Parameters:

  • input: Base58-encoded string

Returns: Uint8Array containing the decoded binary data, or undefined if input contains invalid characters

Usage Example:

import bs58 from "bs58";

// Safe decoding that doesn't throw
const validAddress = "16UjcYNBG9GTK4uq2f7yYEbuifqCzoLMGS";
const decoded = bs58.decodeUnsafe(validAddress);

if (decoded) {
  console.log("Valid address:", Buffer.from(decoded).toString('hex'));
} else {
  console.log("Invalid Base58 string");
}

// Handle invalid input gracefully
const invalidAddress = "invalid0string"; // Contains '0' which is not in Base58 alphabet
const result = bs58.decodeUnsafe(invalidAddress);

if (result === undefined) {
  console.log("Input contains invalid Base58 characters");
}

// Useful for validation without exception handling
function isValidBase58(input: string): boolean {
  return bs58.decodeUnsafe(input) !== undefined;
}

Types

interface BaseConverter {
  encode(input: Uint8Array | Buffer | Array<number>): string;
  decode(input: string): Uint8Array;
  decodeUnsafe(input: string): Uint8Array | undefined;
}

declare const bs58: BaseConverter;
export default bs58;

Bitcoin Base58 Alphabet

The bs58 package uses the standard Bitcoin Base58 alphabet, which excludes visually similar characters to prevent confusion:

  • Excluded characters: 0 (zero), O (capital O), I (capital i), l (lowercase L)
  • Full alphabet: 123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz

This alphabet ensures that Base58-encoded strings are human-readable and less prone to transcription errors.

Error Handling

The decode function will throw an error when encountering invalid characters:

import bs58 from "bs58";

try {
  // This will throw because '0' is not in the Base58 alphabet
  bs58.decode("invalid0string");
} catch (error) {
  console.log(error.message); // "Non-base58 character"
}

For safer error handling without exceptions, use decodeUnsafe:

import bs58 from "bs58";

// Safe approach - no exceptions thrown
const result = bs58.decodeUnsafe("invalid0string");
if (result === undefined) {
  console.log("Invalid Base58 string detected");
}

Browser Compatibility

The bs58 package works in both Node.js and browser environments. For browser usage with older bundlers, you may need to create a standalone bundle:

browserify node_modules/bs58/src/cjs/index.cjs -o bs58.bundle.js --standalone bs58

Dependencies

bs58 depends on the base-x library (^5.0.0), which provides the core base encoding functionality. The bs58 package serves as a pre-configured wrapper that uses the Bitcoin Base58 alphabet.

docs

index.md

tile.json