@scure/base
Advanced tools
Secure, audited & 0-dep implementation of base64, bech32, base58, base32 & base16
Audited & minimal implementation of bech32, base64, base58, base32 & base16.
Check out Projects using scure-base.
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.
import { base16, base32, base64, base58 } from '@scure/base';
// Flavors
import {
base58xmr,
base58xrp,
base32nopad,
base32hex,
base32hexnopad,
base32crockford,
base64nopad,
base64url,
base64urlnopad,
} 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);
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 data = Uint8Array.from([1, 2, 3]);
createBase58check(sha256).encode(data);
import { bech32 } from '@scure/base';
const words = bech32.toWords(new TextEncoder().encode('hello'));
const addr = bech32.encode('test', words);
console.log(addr); // "test1w508d6qejxtdg4"
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
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.js 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
The code may feel unnecessarily complicated; but actually it's 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:
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.
Besides base-encodings, we can reuse the same approach with any encode/decode function
(bytes2number, bytes2u32, etc).
For example, you can easily encode entropy to mnemonic (BIP-39):
export function getCoder(wordlist: string[]) {
if (!Array.isArray(wordlist) || wordlist.length !== 2 ** 11 || typeof wordlist[0] !== 'string') {
throw new Error('Wordlist: expected array of 2048 strings');
}
return mbc.chain(mbu.checksum(1, checksum), mbu.radix2(11, true), mbu.alphabet(wordlist));
}
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).
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:
npm install && npm run build && npm test will build the code and run tests.npm run lint / npm run format will run linter / fix linter issues.npm run build:release will build single fileMIT (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 5,274,574 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.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
Five malicious NuGet packages impersonate Chinese .NET libraries to deploy a stealer targeting browser credentials, crypto wallets, SSH keys, and local files.
Security News
pnpm 11 turns on a 1-day Minimum Release Age and blocks exotic subdeps by default, adding safeguards against fast-moving supply chain attacks.
Security News
The remediated findings include organization permission bugs, stale project access after transfers, OIDC replay edge cases, audit logging gaps, and an IDOR in API token deletion.