bs58

bs58 is a minimal JavaScript library for Base58 encoding and decoding, the scheme used by Bitcoin and other cryptocurrencies to represent binary data as human-friendly alphanumeric strings that avoid visually ambiguous characters like 0, O, I, and l. It wraps the generic base-x encoder with Bitcoin’s specific 58-character alphabet, exposing simple encode(input) and decode(input) functions that accept a Uint8Array, Buffer, or plain array and return the encoded string (or vice versa).

The library ships as dual ESM/CJS builds with matching TypeScript type declarations, has a single runtime dependency (base-x), and is widely used as a building block by higher-level crypto libraries such as bs58check for address checksum encoding.

What You Get

• encode() and decode() functions for converting between binary data and Base58 strings
• Dual ESM and CommonJS builds with matching TypeScript type declarations
• Bitcoin’s standard 58-character alphabet baked in, so no alphabet configuration is required
• A minimal dependency footprint, with the encoding logic itself delegated to a single dependency (base-x)

Common Use Cases

• Encoding Bitcoin, Litecoin, and other cryptocurrency addresses for display
• Decoding user-supplied addresses back into raw bytes for validation
• Serializing public keys or hashes into a human-copyable string format
• Acting as the encoding primitive underneath checksum libraries like bs58check

Under The Hood

Architecture bs58’s entire implementation is a single-file shim: ts_src/index.ts defines the Bitcoin Base58 alphabet constant and passes it straight into base-x’s factory function, re-exporting the result as the package’s default export. There is no internal layering because there is virtually no logic in this package — the actual arbitrary-base encode/decode algorithm lives entirely in the base-x dependency. The build pipeline compiles that one source file twice, once per tsconfig (ESM and CJS targets), then a postbuild script renames the CJS output’s .js/.ts extensions to .cjs/.cts so both module systems resolve correctly. Because bs58 has no abstraction of its own beyond the alphabet constant, a breaking change to base-x’s exported factory signature would break bs58 immediately with no adapter layer to absorb it.

Tech Stack The package targets modern JavaScript/TypeScript (TypeScript 5.5 via tsc) and declares a single runtime dependency, base-x ^5.0.0, which performs the actual arbitrary-base conversion math. Dev tooling includes tape for unit tests, ts-standard for JavaScript Standard-style linting, rimraf for clean builds, and @types/node for ambient Node types. There is no web framework, ORM, or database involved — it is a pure, standalone encoding utility distributed via npm and consumed directly or through wrapper packages like bs58check. GitHub Actions (main_ci.yml) runs three jobs on every push: unit tests, the standard lint check, and a gitdiff check that rebuilds the package and fails if the committed build output has drifted from source.

Code Quality Tests live in test/index.js using tape, running encode/decode round-trips against fixtures in test/fixtures.json that include both valid cases and explicit invalid-input cases — including an assertion that decode() throws a ‘Non-base58 character’ error rather than silently truncating or miscoding malformed input. Linting is enforced via ts-standard as a required CI job, and TypeScript provides static typing for the wrapper’s public API, though the wrapper itself contains almost no branching logic to type-check beyond the re-export. There is no explicit error-handling code in bs58’s own source since invalid-input handling is delegated entirely to base-x; quality here shows up as disciplined process (tests, lint, CI, build-diff verification) around a deliberately tiny surface area.

What Makes It Unique bs58 is not a novel encoding technique — it is a thin, canonical alphabet configuration on top of the generic base-x encoder, existing to save consumers from having to look up or hand-roll Bitcoin’s specific 58-character alphabet. Its value is as a stable, long-standing npm package name that a wide swath of cryptocurrency tooling (wallet libraries, address-checksum packages like bs58check) depends on as a trusted building block, rather than any distinctive internal technique.