@originals/sdk 1.4.2 → 1.4.3

package/src/utils/bitcoin-address.ts

@@ -1,130 +0,0 @@
-import * as bitcoin from 'bitcoinjs-lib';
-
-/**
- * Bitcoin network types supported by the validation
- */
-export type BitcoinNetwork = 'mainnet' | 'regtest' | 'signet';
-
-/**
- * Maps our network names to bitcoinjs-lib network configurations
- */
-const getNetwork = (network: BitcoinNetwork): bitcoin.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: string, network: BitcoinNetwork): boolean {
-  // 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: string, network: BitcoinNetwork): boolean {
-  try {
-    validateBitcoinAddress(address, network);
-    return true;
-  } catch {
-    return false;
-  }
-}

package/src/utils/cbor.ts

@@ -1,12 +0,0 @@
-import * as cbor from 'cbor-js';
-
-export function encode(input: unknown): Uint8Array {
-  const encoded: any = (cbor as any).encode(input);
-  return new Uint8Array(encoded);
-}
-
-export function decode<T = unknown>(bytes: Uint8Array | ArrayBuffer | Buffer): T {
-  const view = new Uint8Array(bytes as any);
-  return (cbor as any).decode(view.buffer) as T;
-}
-

package/src/utils/encoding.ts

@@ -1,127 +0,0 @@
-import b58 from 'b58';
-
-export function encodeBase64UrlMultibase(bytes: Uint8Array): string {
-  return 'z' + Buffer.from(bytes).toString('base64url');
-}
-
-export function decodeBase64UrlMultibase(s: string): Uint8Array {
-  if (!s || s[0] !== 'z') {
-    throw new Error('Invalid Multibase encoding');
-  }
-  return Buffer.from(s.slice(1), 'base64url');
-}
-
-export function hexToBytes(hex: string): Uint8Array {
-  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: any): string => {
-		return Buffer.from(unencoded || '').toString('base64');
-	},
-	decode: (encoded: any): Uint8Array => {
-		return new Uint8Array(Buffer.from(encoded || '', 'base64').buffer);
-	}
-};
-
-export const utf8 = {
-	encode: (unencoded: string): Uint8Array => {
-		return new TextEncoder().encode(unencoded)
-	},
-	decode: (encoded: Uint8Array): string => {
-		return new TextDecoder().decode(encoded);
-	}
-}
-
-export const base64url = {
-	encode: (unencoded: any): string => {
-		const encoded = base64.encode(unencoded);
-		return encoded.replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/g, '');
-	},
-	decode: (encoded: any): Uint8Array => {
-		encoded = encoded.replace(/-/g, '+').replace(/_/g, '/');
-		while (encoded.length % 4) encoded += '=';
-		return base64.decode(encoded);
-	}
-};
-
-export const base58 = {
-	encode: (unencoded: Uint8Array): string => {
-		return b58.encode(unencoded);
-	},
-	decode: (encoded: string): Uint8Array => {
-		return b58.decode(encoded);
-	}
-};
-
-export const multibase = {
-	encode: (val: Uint8Array, encoding: 'base58btc' | 'base64url'): string => {
-		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: string): Uint8Array => {
-		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: Uint8Array, val: Uint8Array): string => {
-		const mcBytes = new Uint8Array(header.length + val.length);
-		mcBytes.set(header);
-		mcBytes.set(val, header.length);
-		return multibase.encode(mcBytes, 'base58btc');
-	},
-	decode: (header: Uint8Array, val: string): Uint8Array => {
-		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/src/utils/hash.ts

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

package/src/utils/retry.ts

@@ -1,46 +0,0 @@
-export interface RetryOptions {
-  maxRetries?: number;
-  baseDelayMs?: number;
-  maxDelayMs?: number;
-  backoffFactor?: number;
-  jitterFactor?: number; // 0..1
-  isRetriable?: (error: unknown) => boolean;
-  onRetry?: (attempt: number, delayMs: number, error: unknown) => void;
-}
-
-const DEFAULTS: Required<RetryOptions> = {
-  maxRetries: 3,
-  baseDelayMs: 300,
-  maxDelayMs: 10_000,
-  backoffFactor: 2,
-  jitterFactor: 0.1,
-  isRetriable: () => true,
-  onRetry: () => {}
-};
-
-function sleep(ms: number): Promise<void> {
-  return new Promise(resolve => setTimeout(resolve, ms));
-}
-
-function computeDelay(attempt: number, opts: Required<RetryOptions>): number {
-  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<T>(fn: () => Promise<T>, options: RetryOptions = {}): Promise<T> {
-  const opts: Required<RetryOptions> = { ...DEFAULTS, ...options } as any;
-  let lastError: unknown;
-  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/src/utils/satoshi-validation.ts

@@ -1,196 +0,0 @@
-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 = 2_100_000_000_000_000;
-
-/**
- * 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 function validateSatoshiNumber(satoshi: string | number): SatoshiValidationResult {
-  // 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: string): number {
-  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: string;
-
-  // 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: string | number): void {
-  const result = validateSatoshiNumber(satoshi);
-  if (!result.valid) {
-    throw new StructuredError('INVALID_SATOSHI', result.error || 'Invalid satoshi identifier');
-  }
-}

package/src/utils/serialization.ts

@@ -1,96 +0,0 @@
-import jsonld from 'jsonld';
-import { DIDDocument, VerifiableCredential } from '../types';
-
-type DocumentLoader = (url: string) => Promise<{
-  documentUrl: string;
-  document: any;
-  contextUrl: string | null;
-}>;
-
-// 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: Record<string, any> = {
-  // 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: DocumentLoader = async (url: string) => {
-  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: DIDDocument): string {
-  // Serialize to JSON-LD with proper context
-  return JSON.stringify(didDoc, null, 2);
-}
-
-export function deserializeDIDDocument(data: string): DIDDocument {
-  // Parse from JSON-LD
-  try {
-    const parsed = JSON.parse(data);
-    return parsed as DIDDocument;
-  } catch (error) {
-    throw new Error('Invalid DID Document JSON');
-  }
-}
-
-export function serializeCredential(vc: VerifiableCredential): string {
-  // Serialize VC to JSON-LD
-  return JSON.stringify(vc, null, 2);
-}
-
-export function deserializeCredential(data: string): VerifiableCredential {
-  // Parse VC from JSON-LD
-  try {
-    const parsed = JSON.parse(data);
-    return parsed as VerifiableCredential;
-  } catch (error) {
-    throw new Error('Invalid Verifiable Credential JSON');
-  }
-}
-
-export async function canonicalizeDocument(
-  doc: any,
-  options: { documentLoader?: DocumentLoader } = {}
-): Promise<string> {
-  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
-    } as any);
-  } catch (error: any) {
-    const message = error?.message ?? String(error);
-    throw new Error(`Failed to canonicalize document: ${message}`);
-  }
-}
-
-

package/src/utils/telemetry.ts

@@ -1,40 +0,0 @@
-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 class StructuredError extends Error {
-  public readonly code: string;
-  public readonly details?: Record<string, unknown>;
-  constructor(code: string, message: string, details?: Record<string, unknown>) {
-    super(message);
-    this.name = 'StructuredError';
-    this.code = code;
-    this.details = details;
-  }
-}
-
-export function emitTelemetry(hooks: TelemetryHooks | undefined, event: TelemetryEvent): void {
-  if (hooks && typeof hooks.onEvent === 'function') {
-    try {
-      hooks.onEvent({ level: 'info', ...event });
-    } catch (_) {}
-  }
-}
-
-export function emitError(hooks: TelemetryHooks | undefined, error: StructuredError): void {
-  if (hooks && typeof hooks.onError === 'function') {
-    try {
-      hooks.onError(error);
-    } catch (_) {}
-  }
-}
-