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
Per BIP173, encoded strings are limited to 90 characters. encode, decode,
and decodeToBytes 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
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:
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.
Strict decoding
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:
Unknown characters, including whitespace: base64.decode('aGk=\n') throws
Non-canonical or missing padding: base64.decode('aGk') throws (use base64nopad)
Non-zero bits in the final partial group: base64.decode('aGl=') throws
Mixed-case bech32 strings, per BIP173
Wrong input types: passing a non-string to decode or a non-Uint8Array to encode throws
This 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.
Design rationale
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) -> Bdecode(B) -> A where X = decode(encode(X)) # encode(decode(X)) can be !== X! # because decoding can normalize inpute.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):
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.
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.
The same applies to base36, which shares the implementation.
Both reject inputs over 2,048 bytes and encoded strings over 4,096 characters before conversion.
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.
Security
The library has been audited:
at version 2.2.0, in Apr 2026, by ourselves (self-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.
Supply chain security
Commits are signed with PGP keys to prevent forgery. Be sure to verify the commit signatures
Releases are made transparently through token-less GitHub CI and Trusted Publishing. Be sure to verify the provenance logs for authenticity.
Rare releasing is practiced to minimize the need for re-audits by end-users.
Dependencies are minimized and strictly pinned to reduce supply-chain risk.
We use as few dependencies as possible.
Version ranges are locked, and changes are checked with npm-diff.
Dev dependencies are excluded from end-user installs; they’re only used for development and build steps.
For this package, there are 0 dependencies; and a few dev dependencies:
jsbt is used for benchmarking / testing / build tooling and developed by the same author
prettier, fast-check and typescript are used for code quality / test generation / ts compilation
Speed
Run benchmarks with npm run benchmark. Results on Apple M4, Node.js v24:
base16 encode x 344 mib/secbase16 decode x 142 mib/secbase32 encode x 427 mib/secbase32 decode x 165 mib/secbase64 encode x 18.7 gib/secbase64 decode x 6.63 gib/secbase64nopad encode x 486 mib/secbase64nopad decode x 214 mib/secbase58 encode 32 B x 32.2 mib/secbase58 decode 32 B x 60.2 mib/secutf8 encode x 1.81 gib/secutf8 decode x 1.78 gib/secbech32 toWords x 351 mib/secbech32 fromWords x 161 mib/sec