@scure/base
Advanced tools
Secure, audited & 0-dep implementation of base64, bech32, base58, base32 & base16
Audited & minimal implementation of bech32, base64, base58, base32 & base16.
scure — audited micro-libraries.
npm install @scure/base
deno add jsr:@scure/base
We support all major platforms and runtimes. The library is hybrid ESM / Common.js package.
Every codec has the same API: encode(bytes: Uint8Array): string and
decode(str: string): Uint8Array. Invalid input throws Error —
see Strict decoding. Exceptions are bech32 / bech32m
(words-based API) and base58check (requires external sha256); both are
described below.
| Codec | Spec | Padding | Notes |
|---|---|---|---|
base16 | RFC 4648 §8 | — | Uppercase; decode is case-sensitive. Use hex for case-insensitive decoding |
hex | — | — | Lowercase; decode accepts both cases. Native Uint8Array.fromHex when available |
base32, base32nopad | RFC 4648 §6 | = / no | Uppercase; decode is case-sensitive |
base32hex, base32hexnopad | RFC 4648 §7 | = / no | Different alphabet ordering than base32 |
base32crockford | Crockford | — | Decode is case-insensitive and normalizes O→0, I→1, L→1 |
base64, base64nopad | RFC 4648 §4 | = / no | Native Uint8Array.fromBase64 when available |
base64url, base64urlnopad | RFC 4648 §5 | = / no | URL-safe alphabet; native builtin when available |
base58, base58flickr, base58xrp | draft-msporny | — | O(n²), only for small constant-size inputs — see below |
base58xmr | Monero | — | Processes 8-byte blocks, which makes it linear |
createBase58check(sha256) | Base58check | — | Returns a codec; caller injects sha256 |
bech32, bech32m | BIP173, BIP350 | — | Words-based API with (prefix, words) |
utf8, ascii | — | — | String ↔ bytes coders, strict validation |
import { base16, base32, base64, base58 } from '@scure/base';
// Flavors
import {
base58flickr,
base58xmr,
base58xrp,
base32nopad,
base32hex,
base32hexnopad,
base32crockford,
base64nopad,
base64url,
base64urlnopad,
hex,
} from '@scure/base';
const data = Uint8Array.from([1, 2, 3]);
base64.decode(base64.encode(data));
// Convert utf8 string to Uint8Array
const data2 = new TextEncoder().encode('hello');
base58.encode(data2);
// Everything has the same API except for bech32 and base58check
base32.encode(data);
base16.encode(data);
base32hex.encode(data);
Also, the internal export __TESTS.base64Fallback is identical to base64, but never uses native code.
base58check is a special case: you need to pass sha256() function:
npm install @noble/hashes
import { createBase58check } from '@scure/base';
import { sha256 } from '@noble/hashes/sha2.js';
const base58check = createBase58check(sha256);
const data = Uint8Array.from([1, 2, 3]);
base58check.encode(data);
import { bech32, bech32m } from '@scure/base';
const words = bech32.toWords(new TextEncoder().encode('hello'));
const addr = bech32.encode('test', words);
console.log(addr); // "test1dpjkcmr09ys0qs"
const { prefix, words: decoded } = bech32.decode(addr);
console.log(prefix); // "test"
console.log(new TextDecoder().decode(bech32.fromWords(decoded))); // "hello"
console.log(bech32.decodeUnsafe('invalid')); // undefined, instead of throwing
// bech32m (BIP350) has the same API
bech32m.decode(bech32m.encode('test', words));
// Shortcuts which convert bytes to words and back for you
const addr2 = bech32.encodeFromBytes('test', new TextEncoder().encode('hello'));
const { bytes } = bech32.decodeToBytes(addr2);
Per BIP173, encoded strings are limited to 90 characters. encode and decode
accept an optional limit argument to raise the limit (Lightning invoices are
longer), or false to disable it entirely.
We provide low-level bech32 operations. If you need high-level methods for BTC (addresses, and others), use scure-btc-signer instead.
Bitcoin addresses use both 5-bit words and bytes representations.
They can't be parsed using bech32.decodeToBytes.
Same applies to Lightning Invoice Protocol
BOLT-11.
We have many tests in ./test/bip173.test.ts that serve as minimal examples of
Bitcoin address and Lightning Invoice Protocol parsers.
Keep in mind that you'll need to verify the examples before using them in your code.
Do something like this:
import { bech32 } from '@scure/base';
const address = bech32.encode('bc', [0, ...bech32.toWords(new Uint8Array(20))]);
const decoded = bech32.decode(address);
// NOTE: words in bitcoin addresses contain version as first element,
// with actual witness program words in rest
// BIP-141: The value of the first push is called the "version byte".
// The following byte vector pushed is called the "witness program".
const [version, ...dataW] = decoded.words;
const program = bech32.fromWords(dataW); // actual witness program
hex, utf8 and ascii are string ↔ bytes coders. They follow the same
BytesCoder interface, so encode takes bytes and returns a string,
while decode takes a string and returns bytes:
import { hex, utf8, ascii } from '@scure/base';
hex.decode('0102ff'); // Uint8Array([1, 2, 255]); accepts "0102FF" too
hex.encode(Uint8Array.from([1, 2, 255])); // "0102ff", always lowercase
utf8.decode('hey'); // Uint8Array([104, 101, 121])
utf8.encode(Uint8Array.from([104, 101, 121])); // "hey"
ascii.decode('ABC'); // Uint8Array([65, 66, 67])
Unlike base16, hex emits lowercase and decodes either case, matching
Node.js Buffer hex strings. utf8 is strict: it throws on invalid UTF-8
bytes and on malformed UTF-16 strings with lone surrogates, instead of
silently emitting replacement characters. ascii rejects anything outside
of 7-bit ASCII.
hex, base64 and base64url transparently use native
Uint8Array.fromHex / fromBase64 builtins when the runtime provides them,
falling back to the pure-JS implementation otherwise. Validation behavior is
identical on both paths.
If decode(str) succeeds, the input was canonical, with a small documented
set of normalizations (hex and base32crockford case-folding, bech32
accepting all-uppercase strings). Everything else throws:
base64.decode('aGk=\n') throwsbase64.decode('aGk') throws (use base64nopad)base64.decode('aGl=') throwsdecode or a non-Uint8Array to encode throwsThis matters for security-sensitive code: malleable encodings enable
transaction-ID and signature malleability, cache-poisoning and
double-spending of allowlists. It also guarantees encode(decode(str))
either returns an equivalent canonical string or throws — unlike atob,
which accepts and silently normalizes malformed input.
The code may look unnecessarily complicated; but the structure actually makes it much easier to reason about. Any encoding library consists of two functions:
encode(A) -> B
decode(B) -> A
where X = decode(encode(X))
# encode(decode(X)) can be !== X!
# because decoding can normalize input
e.g.
base58checksum = {
encode(): {
// checksum
// radix conversion
// alphabet
},
decode(): {
// alphabet
// radix conversion
// checksum
}
}
But instead of creating two big functions for each specific case,
we create them from tiny composable building blocks
(alphabet, radix, padding, checksum, chain):
base58checksum = chain(checksum(), radix(), alphabet())
Which is the same as chain/pipe/sequence function in Functional Programming, but significantly more useful since it enforces same order of execution of encode/decode. Basically you only define encode (in declarative way) and get correct decode for free. So, instead of reasoning about two big functions you need only reason about primitives and encode chain. The design revealed obvious bug in older version of the lib, where xmr version of base58 had errors in decode's block processing.
Uint8Array is represented as big-endian number:
[1, 2, 3, 4, 5] -> 1*(256**4) + 2*(256**3) 3*(256**2) + 4*(256**1) + 5*(256**0)
where 256 = 2**8 (8 bits per byte)
which is then converted to a number in another radix/base (16/32/58/64, etc).
However, generic conversion between bases has quadratic O(n^2) time complexity.
Which means base58 has quadratic time complexity too. Use base58 only when you have small constant sized input, because variable length sized input from user can cause DoS.
On the other hand, if both bases are power of same number (like 2**8 <-> 2**64),
there is linear algorithm. For now we have implementation for power-of-two bases only (radix2).
base58xmr sidesteps the issue differently: it encodes in fixed 8-byte blocks,
which keeps it linear at the cost of a slightly different (Monero-specific) format.
The library has been audited:
The library was initially developed for js-ethereum-cryptography.
At commit ae00e6d7,
it was extracted to a separate package called micro-base.
After the audit we've decided to use @scure NPM namespace for security.
For this package, there are 0 dependencies; and a few dev dependencies:
Run benchmarks with npm run benchmark. Results on Apple M4, Node.js v24:
base16 encode x 344 mib/sec
base16 decode x 142 mib/sec
base32 encode x 427 mib/sec
base32 decode x 165 mib/sec
base64 encode x 18.7 gib/sec
base64 decode x 6.63 gib/sec
base64nopad encode x 486 mib/sec
base64nopad decode x 214 mib/sec
base58 encode 32 B x 32.2 mib/sec
base58 decode 32 B x 60.2 mib/sec
utf8 encode x 1.81 gib/sec
utf8 decode x 1.78 gib/sec
bech32 toWords x 351 mib/sec
bech32 fromWords x 161 mib/sec
MIT (c) Paul Miller (https://paulmillr.com), see LICENSE file.
base-x is a library for encoding and decoding data in various base formats, including Base58. It is similar to @scure/base in terms of functionality but focuses more on Base58 and other custom base encodings.
bs58 is a library specifically for Base58 encoding and decoding. It is highly optimized for performance and is commonly used in cryptocurrency applications. Unlike @scure/base, it does not support other base formats like Base64 or Base16.
base64-js is a library for Base64 encoding and decoding. It is lightweight and efficient, similar to @scure/base, but it only supports Base64 encoding and decoding.
FAQs
Secure, audited & 0-dep implementation of base64, bech32, base58, base32 & base16
The npm package @scure/base receives a total of 6,837,547 weekly downloads. As such, @scure/base popularity was classified as popular.
We found that @scure/base demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Security News
GPT-6 Astra hits 100% on ExploitBench and finds zero-days autonomously, while independent tests reveal scope violations and monitoring gaps.
Product
Socket can now send alerts and supply chain attack notifications to Microsoft Teams, with filters that route the right updates to each channel.
Security News
pnpm 12 rewrites the package manager in Rust, cutting install times by up to 90% while preserving pnpm 11 workflows and lockfiles.