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 code and a structured context payload.npm install @did-btcr2/common
Or with pnpm:
pnpm add @did-btcr2/common
| 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: [] });
// Construct a JSON Patch operation.
const patch = { op: 'add' as const, path: '/service/-', value: { id: '#dwn' } };
// Throw a structured error with code + context.
throw new MethodError('beacon address mismatch', 'BEACON_VALIDATION', {
address : 'tb1q...',
kind : 'P2WPKH',
});
@noble/hashes and @scure/base.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.