Common utilities, types, and errors shared across the did-btcr2-js monorepo.
Part of the did-btcr2-js monorepo.
This package is the foundational layer that every other @did-btcr2/* package depends on. It has no workspace dependencies of its own. Its responsibilities:
PatchOperation interface used by the DID update path.KeyBytes, HashBytes, SignatureBytes, etc.), DID-related enums (IdentifierTypes, IdentifierHrp, BitcoinNetworkNames), and the JSONObject family used by canonical signing.DidMethodError base with one subclass per failure domain (MethodError, IdentifierError, UpdateError, ResolveError, KeyManagerError, KeyPairError, MultikeyError, CryptosuiteError, etc.) Every typed error carries a type string tag and a structured data payload.npm install @did-btcr2/common
Or with pnpm:
pnpm add @did-btcr2/common
Ships both ESM and CommonJS. Requires Node >= 22.
| Concern | Entry point |
|---|---|
| Canonicalize an object | canonicalize(obj) |
| Hash canonical bytes | hash(string), canonicalHashBytes(obj) |
| Hash and encode in one call | canonicalHash(obj, { encoding }) |
| Encode/decode hash bytes | encode(bytes, encoding), decode(string, encoding) |
| Build JSON Patch ops | JSONPatch, PatchOperation |
| Base error class | DidMethodError |
| Subclassed errors | MethodError, IdentifierError, UpdateError, ResolveError, KeyPairError, KeyManagerError, MultikeyError, … |
| Byte type aliases | Bytes, KeyBytes, HashBytes, SignatureBytes, DocumentBytes |
| DID enums | IdentifierTypes, IdentifierHrp, BitcoinNetworkNames |
| Cryptosuite names | CryptosuiteName ('bip340-jcs-2025' or 'bip340-rdfc-2025') |
import { canonicalHash, JSONPatch, MethodError } from '@did-btcr2/common';
// Hash a DID document canonically (JCS + SHA-256, base64urlnopad).
const docHash = canonicalHash({ id: 'did:btcr2:k1q5p...', verificationMethod: [] });
// Apply a JSON Patch operation to a document (returns a new document, does not mutate).
const patched = JSONPatch.apply(
{ id: 'did:btcr2:k1q5p...', service: [] },
[{ op: 'add', path: '/service/-', value: { id: '#dwn' } }],
);
// Throw a structured error with type tag + data payload.
throw new MethodError('beacon address mismatch', 'BEACON_VALIDATION', {
address : 'tb1q...',
kind : 'P2WPKH',
});
@noble/hashes, @scure/base, fast-json-patch, and json-canonicalize. @scure/bip32 is an optional peer dependency for HD-key consumers.base64urlnopad is the default for hash encoding; byte comparisons use equalBytes() to handle interop with hex-encoded protocol fields.# From packages/common/
pnpm build # Compile ESM + CJS + type declarations
pnpm build:tests # Compile tests to tests/compiled/
pnpm test # Run the test suite with coverage
pnpm lint # ESLint (zero warnings tolerated)
canonicalize, canonicalHash, JSONPatch, and the error classes in errors.ts.