@originals/sdk 1.4.2 → 1.4.5

package/dist/utils/bitcoin-address.js

@@ -0,0 +1,113 @@
+import * as bitcoin from 'bitcoinjs-lib';
+/**
+ * Maps our network names to bitcoinjs-lib network configurations
+ */
+const getNetwork = (network) => {
+    switch (network) {
+        case 'mainnet':
+            return bitcoin.networks.bitcoin;
+        case 'regtest':
+            // Regtest uses testnet parameters but with bcrt prefix
+            // However, since many regtest addresses in tests use testnet format,
+            // we accept both testnet and regtest addresses for regtest network
+            return bitcoin.networks.regtest;
+        case 'signet':
+            // Signet uses the same bech32 prefix as testnet (tb1)
+            return bitcoin.networks.testnet;
+        default:
+            throw new Error(`Unsupported network: ${network}`);
+    }
+};
+/**
+ * Validates a Bitcoin address format and checksum for the given network.
+ *
+ * This function uses bitcoinjs-lib's address.toOutputScript() which performs:
+ * - Format validation (bech32, base58check)
+ * - Checksum verification
+ * - Network prefix validation
+ *
+ * @param address - The Bitcoin address to validate
+ * @param network - The network to validate against ('mainnet', 'regtest', 'signet')
+ * @returns true if the address is valid for the network
+ * @throws Error with descriptive message if validation fails
+ *
+ * @example
+ * ```typescript
+ * // Valid mainnet address
+ * validateBitcoinAddress('bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq', 'mainnet'); // true
+ *
+ * // Invalid checksum
+ * validateBitcoinAddress('bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdd', 'mainnet'); // throws
+ *
+ * // Wrong network
+ * validateBitcoinAddress('bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq', 'testnet'); // throws
+ * ```
+ */
+export function validateBitcoinAddress(address, network) {
+    // Input validation
+    if (!address || typeof address !== 'string') {
+        throw new Error('Address must be a non-empty string');
+    }
+    const trimmedAddress = address.trim();
+    if (trimmedAddress.length === 0) {
+        throw new Error('Address cannot be empty');
+    }
+    // Check for mock/test addresses that should not be allowed in production
+    if (/^(mock-|test-)/i.test(trimmedAddress)) {
+        throw new Error('Mock or test addresses are not valid Bitcoin addresses');
+    }
+    // Validate address length (Bitcoin addresses are typically 26-90 characters)
+    if (trimmedAddress.length < 26 || trimmedAddress.length > 90) {
+        throw new Error(`Invalid address length: ${trimmedAddress.length} characters (expected 26-90)`);
+    }
+    try {
+        // Get the appropriate network configuration
+        const networkConfig = getNetwork(network);
+        // Use bitcoinjs-lib to validate the address format and checksum
+        // This will throw if the address is invalid
+        bitcoin.address.toOutputScript(trimmedAddress, networkConfig);
+        return true;
+    }
+    catch (error) {
+        // For regtest, also try testnet network as many tools use testnet addresses for regtest
+        if (network === 'regtest') {
+            try {
+                bitcoin.address.toOutputScript(trimmedAddress, bitcoin.networks.testnet);
+                return true;
+            }
+            catch {
+                // Fall through to error handling below
+            }
+        }
+        // Parse the error to provide more specific feedback
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        // Check for common error patterns and provide helpful messages
+        if (errorMessage.includes('Invalid checksum') || errorMessage.includes('checksum')) {
+            throw new Error(`Invalid Bitcoin address checksum for address: ${trimmedAddress}`);
+        }
+        if (errorMessage.includes('Invalid prefix') || errorMessage.includes('prefix')) {
+            throw new Error(`Invalid address prefix for ${network} network: ${trimmedAddress}`);
+        }
+        if (errorMessage.includes('too short') || errorMessage.includes('too long')) {
+            throw new Error(`Invalid address length for ${network}: ${trimmedAddress}`);
+        }
+        // Generic invalid address error
+        throw new Error(`Invalid Bitcoin address for ${network} network: ${trimmedAddress} (${errorMessage})`);
+    }
+}
+/**
+ * Validates a Bitcoin address and returns a boolean instead of throwing
+ *
+ * @param address - The Bitcoin address to validate
+ * @param network - The network to validate against
+ * @returns true if valid, false otherwise
+ */
+export function isValidBitcoinAddress(address, network) {
+    try {
+        validateBitcoinAddress(address, network);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/utils/cbor.d.ts

@@ -0,0 +1,2 @@
+export declare function encode(input: unknown): Uint8Array;
+export declare function decode<T = unknown>(bytes: Uint8Array | ArrayBuffer | Buffer): T;

package/dist/utils/cbor.js

@@ -0,0 +1,9 @@
+import * as cbor from 'cbor-js';
+export function encode(input) {
+    const encoded = cbor.encode(input);
+    return new Uint8Array(encoded);
+}
+export function decode(bytes) {
+    const view = new Uint8Array(bytes);
+    return cbor.decode(view.buffer);
+}

package/dist/utils/encoding.d.ts

@@ -0,0 +1,37 @@
+export declare function encodeBase64UrlMultibase(bytes: Uint8Array): string;
+export declare function decodeBase64UrlMultibase(s: string): Uint8Array;
+export declare function hexToBytes(hex: string): Uint8Array;
+export declare const MULTIBASE_BASE58BTC_HEADER = "z";
+export declare const MULTIBASE_BASE64URL_HEADER = "u";
+export declare const MULTICODEC_ED25519_PUB_HEADER: Uint8Array<ArrayBuffer>;
+export declare const MULTICODEC_ED25519_PRIV_HEADER: Uint8Array<ArrayBuffer>;
+export declare const MULTICODEC_X25519_PUB_HEADER: Uint8Array<ArrayBuffer>;
+export declare const MULTICODEC_X25519_PRIV_HEADER: Uint8Array<ArrayBuffer>;
+export declare const MULTICODEC_SECP256K1_PUB_HEADER: Uint8Array<ArrayBuffer>;
+export declare const MULTICODEC_SECP256K1_PRIV_HEADER: Uint8Array<ArrayBuffer>;
+export declare const MULTICODEC_BLS12381_G2_PUB_HEADER: Uint8Array<ArrayBuffer>;
+export declare const MULTICODEC_BLS12381_G2_PRIV_HEADER: Uint8Array<ArrayBuffer>;
+export declare const base64: {
+    encode: (unencoded: any) => string;
+    decode: (encoded: any) => Uint8Array;
+};
+export declare const utf8: {
+    encode: (unencoded: string) => Uint8Array;
+    decode: (encoded: Uint8Array) => string;
+};
+export declare const base64url: {
+    encode: (unencoded: any) => string;
+    decode: (encoded: any) => Uint8Array;
+};
+export declare const base58: {
+    encode: (unencoded: Uint8Array) => string;
+    decode: (encoded: string) => Uint8Array;
+};
+export declare const multibase: {
+    encode: (val: Uint8Array, encoding: "base58btc" | "base64url") => string;
+    decode: (val: string) => Uint8Array;
+};
+export declare const multikey: {
+    encode: (header: Uint8Array, val: Uint8Array) => string;
+    decode: (header: Uint8Array, val: string) => Uint8Array;
+};

package/dist/utils/encoding.js

@@ -0,0 +1,120 @@
+import b58 from 'b58';
+export function encodeBase64UrlMultibase(bytes) {
+    return 'z' + Buffer.from(bytes).toString('base64url');
+}
+export function decodeBase64UrlMultibase(s) {
+    if (!s || s[0] !== 'z') {
+        throw new Error('Invalid Multibase encoding');
+    }
+    return Buffer.from(s.slice(1), 'base64url');
+}
+export function hexToBytes(hex) {
+    const clean = hex.startsWith('0x') ? hex.slice(2) : hex;
+    if (clean.length % 2 !== 0) {
+        throw new Error('Invalid hex string length');
+    }
+    const out = new Uint8Array(clean.length / 2);
+    for (let i = 0; i < clean.length; i += 2) {
+        const byteStr = clean.substring(i, i + 2);
+        const value = parseInt(byteStr, 16);
+        if (Number.isNaN(value)) {
+            throw new Error('Invalid hex string');
+        }
+        out[i / 2] = value;
+    }
+    return out;
+}
+// multibase base58-btc header
+export const MULTIBASE_BASE58BTC_HEADER = 'z';
+// multibase base64url header
+export const MULTIBASE_BASE64URL_HEADER = 'u';
+// multicodec ed25519-pub header as varint
+export const MULTICODEC_ED25519_PUB_HEADER = new Uint8Array([0xed, 0x01]);
+// multicodec ed25519-priv header as varint
+export const MULTICODEC_ED25519_PRIV_HEADER = new Uint8Array([0x80, 0x26]);
+// multicodec x25519-pub header as varint
+export const MULTICODEC_X25519_PUB_HEADER = new Uint8Array([0xec, 0x01]);
+// multicodec x25519-priv header as varint
+export const MULTICODEC_X25519_PRIV_HEADER = new Uint8Array([0x82, 0x26]);
+// multicode secp256k1-pub header as varint
+export const MULTICODEC_SECP256K1_PUB_HEADER = new Uint8Array([0xe7, 0x01]);
+// multicode secp256k1-priv header as varint
+export const MULTICODEC_SECP256K1_PRIV_HEADER = new Uint8Array([0x13, 0x01]);
+// multicodec bls12381g2-pub header as varint
+export const MULTICODEC_BLS12381_G2_PUB_HEADER = new Uint8Array([0xeb, 0x01]);
+// multicodec bls12381g2-priv header as varint
+export const MULTICODEC_BLS12381_G2_PRIV_HEADER = new Uint8Array([0x8a, 0x26]);
+export const base64 = {
+    encode: (unencoded) => {
+        return Buffer.from(unencoded || '').toString('base64');
+    },
+    decode: (encoded) => {
+        return new Uint8Array(Buffer.from(encoded || '', 'base64').buffer);
+    }
+};
+export const utf8 = {
+    encode: (unencoded) => {
+        return new TextEncoder().encode(unencoded);
+    },
+    decode: (encoded) => {
+        return new TextDecoder().decode(encoded);
+    }
+};
+export const base64url = {
+    encode: (unencoded) => {
+        const encoded = base64.encode(unencoded);
+        return encoded.replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/g, '');
+    },
+    decode: (encoded) => {
+        encoded = encoded.replace(/-/g, '+').replace(/_/g, '/');
+        while (encoded.length % 4)
+            encoded += '=';
+        return base64.decode(encoded);
+    }
+};
+export const base58 = {
+    encode: (unencoded) => {
+        return b58.encode(unencoded);
+    },
+    decode: (encoded) => {
+        return b58.decode(encoded);
+    }
+};
+export const multibase = {
+    encode: (val, encoding) => {
+        if (encoding === 'base58btc') {
+            const baseEncoded = base58.encode(val);
+            return MULTIBASE_BASE58BTC_HEADER + baseEncoded;
+        }
+        else if (encoding === 'base64url') {
+            return MULTIBASE_BASE64URL_HEADER + base64url.encode(val);
+        }
+        throw new Error('Invalid multibase encoding.');
+    },
+    decode: (val) => {
+        if (val.startsWith(MULTIBASE_BASE58BTC_HEADER)) {
+            return base58.decode(val.substring(1));
+        }
+        else if (val.startsWith(MULTIBASE_BASE64URL_HEADER)) {
+            return base64url.decode(val.substring(1));
+        }
+        throw new Error('Multibase value does not have expected header.');
+    }
+};
+export const multikey = {
+    encode: (header, val) => {
+        const mcBytes = new Uint8Array(header.length + val.length);
+        mcBytes.set(header);
+        mcBytes.set(val, header.length);
+        return multibase.encode(mcBytes, 'base58btc');
+    },
+    decode: (header, val) => {
+        const mcValue = multibase.decode(val);
+        for (let i = 0; i < header.length; i++) {
+            if (mcValue[i] !== header[i]) {
+                throw new Error('Multikey value does not have expected header.');
+            }
+        }
+        return mcValue.slice(header.length);
+    }
+};

package/dist/utils/hash.d.ts

@@ -0,0 +1 @@
+export declare function sha256Bytes(input: string | Uint8Array): Promise<Uint8Array>;

package/dist/utils/hash.js

@@ -0,0 +1,5 @@
+export async function sha256Bytes(input) {
+    const data = typeof input === 'string' ? new TextEncoder().encode(input) : input;
+    const digest = await globalThis.crypto.subtle.digest('SHA-256', data);
+    return new Uint8Array(digest);
+}

package/dist/utils/retry.d.ts

@@ -0,0 +1,10 @@
+export interface RetryOptions {
+    maxRetries?: number;
+    baseDelayMs?: number;
+    maxDelayMs?: number;
+    backoffFactor?: number;
+    jitterFactor?: number;
+    isRetriable?: (error: unknown) => boolean;
+    onRetry?: (attempt: number, delayMs: number, error: unknown) => void;
+}
+export declare function withRetry<T>(fn: () => Promise<T>, options?: RetryOptions): Promise<T>;

package/dist/utils/retry.js

@@ -0,0 +1,35 @@
+const DEFAULTS = {
+    maxRetries: 3,
+    baseDelayMs: 300,
+    maxDelayMs: 10000,
+    backoffFactor: 2,
+    jitterFactor: 0.1,
+    isRetriable: () => true,
+    onRetry: () => { }
+};
+function sleep(ms) {
+    return new Promise(resolve => setTimeout(resolve, ms));
+}
+function computeDelay(attempt, opts) {
+    const exp = opts.baseDelayMs * Math.pow(opts.backoffFactor, attempt);
+    const withJitter = exp + ((Math.random() * 2 - 1) * opts.jitterFactor * exp);
+    return Math.min(Math.max(0, Math.floor(withJitter)), opts.maxDelayMs);
+}
+export async function withRetry(fn, options = {}) {
+    const opts = { ...DEFAULTS, ...options };
+    let lastError;
+    for (let attempt = 0; attempt <= opts.maxRetries; attempt++) {
+        try {
+            return await fn();
+        }
+        catch (err) {
+            lastError = err;
+            if (attempt >= opts.maxRetries || !opts.isRetriable(err))
+                break;
+            const delay = computeDelay(attempt, opts);
+            opts.onRetry(attempt + 1, delay, err);
+            await sleep(delay);
+        }
+    }
+    throw lastError;
+}

package/dist/utils/satoshi-validation.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Maximum number of satoshis in Bitcoin's total supply (21 million BTC)
+ * 21,000,000 BTC * 100,000,000 satoshis/BTC = 2,100,000,000,000,000 satoshis
+ */
+export declare const MAX_SATOSHI_SUPPLY = 2100000000000000;
+/**
+ * Validation result interface for satoshi number validation
+ */
+export interface SatoshiValidationResult {
+    valid: boolean;
+    error?: string;
+}
+/**
+ * Validates a satoshi number for use in Bitcoin ordinals and did:btco DIDs.
+ *
+ * @param satoshi - The satoshi identifier to validate (string or number)
+ * @returns Validation result with descriptive error if invalid
+ *
+ * @example
+ * ```typescript
+ * const result = validateSatoshiNumber('123456');
+ * if (!result.valid) {
+ *   throw new Error(result.error);
+ * }
+ * ```
+ */
+export declare function validateSatoshiNumber(satoshi: string | number): SatoshiValidationResult;
+/**
+ * Parses a satoshi identifier from various formats and validates it.
+ *
+ * Supported formats:
+ * - Plain satoshi number: "123456"
+ * - did:btco DID: "did:btco:123456", "did:btco:test:123456", "did:btco:sig:123456"
+ * - Ordinal notation: "123456" (same as plain number, for future extensions)
+ *
+ * @param identifier - The identifier to parse
+ * @returns The extracted satoshi number
+ * @throws {StructuredError} If the identifier format is invalid or satoshi is invalid
+ *
+ * @example
+ * ```typescript
+ * const satoshi = parseSatoshiIdentifier('did:btco:123456');
+ * console.log(satoshi); // 123456
+ * ```
+ */
+export declare function parseSatoshiIdentifier(identifier: string): number;
+/**
+ * Validates a satoshi number and throws an error if invalid.
+ * Convenience wrapper around validateSatoshiNumber for code that expects exceptions.
+ *
+ * @param satoshi - The satoshi identifier to validate
+ * @throws {StructuredError} If the satoshi is invalid
+ *
+ * @example
+ * ```typescript
+ * assertValidSatoshi('123456'); // OK
+ * assertValidSatoshi(''); // throws StructuredError
+ * ```
+ */
+export declare function assertValidSatoshi(satoshi: string | number): void;

package/dist/utils/satoshi-validation.js

@@ -0,0 +1,156 @@
+import { StructuredError } from './telemetry';
+/**
+ * Maximum number of satoshis in Bitcoin's total supply (21 million BTC)
+ * 21,000,000 BTC * 100,000,000 satoshis/BTC = 2,100,000,000,000,000 satoshis
+ */
+export const MAX_SATOSHI_SUPPLY = 2100000000000000;
+/**
+ * Validates a satoshi number for use in Bitcoin ordinals and did:btco DIDs.
+ *
+ * @param satoshi - The satoshi identifier to validate (string or number)
+ * @returns Validation result with descriptive error if invalid
+ *
+ * @example
+ * ```typescript
+ * const result = validateSatoshiNumber('123456');
+ * if (!result.valid) {
+ *   throw new Error(result.error);
+ * }
+ * ```
+ */
+export function validateSatoshiNumber(satoshi) {
+    // Check for null, undefined, or empty string
+    if (satoshi === null || satoshi === undefined || satoshi === '') {
+        return {
+            valid: false,
+            error: 'Satoshi identifier cannot be null, undefined, or empty string'
+        };
+    }
+    // Convert to string for validation
+    const satoshiStr = String(satoshi).trim();
+    // Check for empty string after trimming
+    if (satoshiStr === '') {
+        return {
+            valid: false,
+            error: 'Satoshi identifier cannot be empty or whitespace-only string'
+        };
+    }
+    // Check for numeric format (must be all digits, no decimals, no scientific notation)
+    if (!/^[0-9]+$/.test(satoshiStr)) {
+        return {
+            valid: false,
+            error: 'Satoshi identifier must be a non-negative integer (no decimals, no scientific notation, no non-numeric characters)'
+        };
+    }
+    // Convert to number for range validation
+    const satoshiNum = Number(satoshiStr);
+    // Check for valid number conversion
+    if (!Number.isFinite(satoshiNum)) {
+        return {
+            valid: false,
+            error: 'Satoshi identifier must be a finite number'
+        };
+    }
+    // Check for decimals (would be truncated by Number())
+    if (satoshiNum !== Math.floor(satoshiNum)) {
+        return {
+            valid: false,
+            error: 'Satoshi identifier cannot contain decimal places'
+        };
+    }
+    // Check for negative numbers
+    if (satoshiNum < 0) {
+        return {
+            valid: false,
+            error: 'Satoshi identifier must be non-negative (>= 0)'
+        };
+    }
+    // Check for maximum supply range
+    if (satoshiNum > MAX_SATOSHI_SUPPLY) {
+        return {
+            valid: false,
+            error: `Satoshi identifier must be within Bitcoin's total supply (0 to ${MAX_SATOSHI_SUPPLY.toLocaleString()})`
+        };
+    }
+    return { valid: true };
+}
+/**
+ * Parses a satoshi identifier from various formats and validates it.
+ *
+ * Supported formats:
+ * - Plain satoshi number: "123456"
+ * - did:btco DID: "did:btco:123456", "did:btco:test:123456", "did:btco:sig:123456"
+ * - Ordinal notation: "123456" (same as plain number, for future extensions)
+ *
+ * @param identifier - The identifier to parse
+ * @returns The extracted satoshi number
+ * @throws {StructuredError} If the identifier format is invalid or satoshi is invalid
+ *
+ * @example
+ * ```typescript
+ * const satoshi = parseSatoshiIdentifier('did:btco:123456');
+ * console.log(satoshi); // 123456
+ * ```
+ */
+export function parseSatoshiIdentifier(identifier) {
+    if (!identifier || typeof identifier !== 'string') {
+        throw new StructuredError('INVALID_SATOSHI_IDENTIFIER', 'Satoshi identifier must be a non-empty string');
+    }
+    const trimmed = identifier.trim();
+    if (trimmed === '') {
+        throw new StructuredError('INVALID_SATOSHI_IDENTIFIER', 'Satoshi identifier cannot be empty or whitespace-only');
+    }
+    let satoshiStr;
+    // Check if it's a did:btco DID
+    if (trimmed.startsWith('did:btco:')) {
+        const parts = trimmed.split(':');
+        // Handle different network prefixes:
+        // did:btco:123456 (mainnet)
+        // did:btco:test:123456 (testnet)
+        // did:btco:sig:123456 (signet)
+        if (parts.length === 3) {
+            // Mainnet format: did:btco:satoshi
+            satoshiStr = parts[2];
+        }
+        else if (parts.length === 4) {
+            // Network-specific format: did:btco:network:satoshi
+            const network = parts[2];
+            if (network !== 'test' && network !== 'sig') {
+                throw new StructuredError('INVALID_SATOSHI_IDENTIFIER', `Invalid did:btco DID format: unsupported network "${network}"`);
+            }
+            satoshiStr = parts[3];
+        }
+        else {
+            throw new StructuredError('INVALID_SATOSHI_IDENTIFIER', 'Invalid did:btco DID format: expected "did:btco:satoshi" or "did:btco:network:satoshi"');
+        }
+    }
+    else {
+        // Assume it's a plain satoshi number
+        satoshiStr = trimmed;
+    }
+    // Validate the extracted satoshi
+    const validation = validateSatoshiNumber(satoshiStr);
+    if (!validation.valid) {
+        throw new StructuredError('INVALID_SATOSHI_IDENTIFIER', validation.error || 'Invalid satoshi identifier');
+    }
+    return Number(satoshiStr);
+}
+/**
+ * Validates a satoshi number and throws an error if invalid.
+ * Convenience wrapper around validateSatoshiNumber for code that expects exceptions.
+ *
+ * @param satoshi - The satoshi identifier to validate
+ * @throws {StructuredError} If the satoshi is invalid
+ *
+ * @example
+ * ```typescript
+ * assertValidSatoshi('123456'); // OK
+ * assertValidSatoshi(''); // throws StructuredError
+ * ```
+ */
+export function assertValidSatoshi(satoshi) {
+    const result = validateSatoshiNumber(satoshi);
+    if (!result.valid) {
+        throw new StructuredError('INVALID_SATOSHI', result.error || 'Invalid satoshi identifier');
+    }
+}

package/dist/utils/serialization.d.ts

@@ -0,0 +1,14 @@
+import { DIDDocument, VerifiableCredential } from '../types';
+type DocumentLoader = (url: string) => Promise<{
+    documentUrl: string;
+    document: any;
+    contextUrl: string | null;
+}>;
+export declare function serializeDIDDocument(didDoc: DIDDocument): string;
+export declare function deserializeDIDDocument(data: string): DIDDocument;
+export declare function serializeCredential(vc: VerifiableCredential): string;
+export declare function deserializeCredential(data: string): VerifiableCredential;
+export declare function canonicalizeDocument(doc: any, options?: {
+    documentLoader?: DocumentLoader;
+}): Promise<string>;
+export {};

package/dist/utils/serialization.js

@@ -0,0 +1,76 @@
+import jsonld from 'jsonld';
+// Import context documents from src/contexts
+import credentialsV1Context from '../contexts/credentials-v1.json';
+import credentialsV2Context from '../contexts/credentials-v2.json';
+import dataIntegrityV2Context from '../contexts/data-integrity-v2.json';
+import didsContext from '../contexts/dids.json';
+import ed255192020Context from '../contexts/ed255192020.json';
+import ordinalsContext from '../contexts/ordinals-plus.json';
+import originalsContext from '../contexts/originals.json';
+// Full context documents for proper canonicalization
+const PRELOADED_CONTEXTS = {
+    // W3C and standard contexts
+    'https://www.w3.org/2018/credentials/v1': credentialsV1Context,
+    'https://www.w3.org/ns/credentials/v2': credentialsV2Context,
+    'https://w3id.org/security/data-integrity/v2': dataIntegrityV2Context,
+    'https://www.w3.org/ns/did/v1': didsContext,
+    'https://w3id.org/security/suites/ed25519-2020/v1': ed255192020Context,
+    // Custom contexts
+    'https://ordinals.plus/vocab/v1': ordinalsContext,
+    // Originals network contexts (all three networks use the same context document)
+    'https://originals.build/context': originalsContext, // Legacy
+    'https://pichu.originals.build/context': originalsContext, // Production
+    'https://cleffa.originals.build/context': originalsContext, // Staging
+    'https://magby.originals.build/context': originalsContext, // Development
+};
+const defaultDocumentLoader = async (url) => {
+    const preloaded = PRELOADED_CONTEXTS[url];
+    if (preloaded) {
+        return { documentUrl: url, document: preloaded, contextUrl: null };
+    }
+    throw new Error(`Document not found in PRELOADED_CONTEXTS: ${url}`);
+};
+export function serializeDIDDocument(didDoc) {
+    // Serialize to JSON-LD with proper context
+    return JSON.stringify(didDoc, null, 2);
+}
+export function deserializeDIDDocument(data) {
+    // Parse from JSON-LD
+    try {
+        const parsed = JSON.parse(data);
+        return parsed;
+    }
+    catch (error) {
+        throw new Error('Invalid DID Document JSON');
+    }
+}
+export function serializeCredential(vc) {
+    // Serialize VC to JSON-LD
+    return JSON.stringify(vc, null, 2);
+}
+export function deserializeCredential(data) {
+    // Parse VC from JSON-LD
+    try {
+        const parsed = JSON.parse(data);
+        return parsed;
+    }
+    catch (error) {
+        throw new Error('Invalid Verifiable Credential JSON');
+    }
+}
+export async function canonicalizeDocument(doc, options = {}) {
+    try {
+        return await jsonld.canonize(doc, {
+            algorithm: 'URDNA2015',
+            format: 'application/n-quads',
+            documentLoader: options.documentLoader ?? defaultDocumentLoader,
+            useNative: false,
+            rdfDirection: 'i18n-datatype',
+            safe: false // Disable safe mode to allow custom contexts
+        });
+    }
+    catch (error) {
+        const message = error?.message ?? String(error);
+        throw new Error(`Failed to canonicalize document: ${message}`);
+    }
+}

package/dist/utils/telemetry.d.ts

@@ -0,0 +1,17 @@
+export type TelemetryLevel = 'debug' | 'info' | 'warn' | 'error';
+export interface TelemetryEvent {
+    name: string;
+    level?: TelemetryLevel;
+    attributes?: Record<string, unknown>;
+}
+export interface TelemetryHooks {
+    onEvent?: (event: TelemetryEvent) => void;
+    onError?: (error: StructuredError) => void;
+}
+export declare class StructuredError extends Error {
+    readonly code: string;
+    readonly details?: Record<string, unknown>;
+    constructor(code: string, message: string, details?: Record<string, unknown>);
+}
+export declare function emitTelemetry(hooks: TelemetryHooks | undefined, event: TelemetryEvent): void;
+export declare function emitError(hooks: TelemetryHooks | undefined, error: StructuredError): void;