@originals/sdk 1.1.0

package/src/migration/validation/LifecycleValidator.ts

@@ -0,0 +1,64 @@
+/**
+ * LifecycleValidator - Validates lifecycle state transitions
+ */
+
+import {
+  MigrationOptions,
+  MigrationValidationResult,
+  ValidationError,
+  ValidationWarning,
+  IValidator
+} from '../types';
+import { OriginalsConfig } from '../../types';
+
+export class LifecycleValidator implements IValidator {
+  constructor(private config: OriginalsConfig) {}
+
+  async validate(options: MigrationOptions): Promise<MigrationValidationResult> {
+    const errors: ValidationError[] = [];
+    const warnings: ValidationWarning[] = [];
+
+    try {
+      // All lifecycle states are compatible with all layers
+      // This validator checks for pending operations that might interfere
+
+      // For now, lifecycle is always compatible
+      // Future enhancements could check for:
+      // - Pending operations on source DID
+      // - State machine compatibility
+      // - Event history preservation capability
+
+      return {
+        valid: errors.length === 0,
+        errors,
+        warnings,
+        estimatedCost: {
+          storageCost: 0,
+          networkFees: 0,
+          totalCost: 0,
+          currency: 'sats'
+        },
+        estimatedDuration: 30
+      };
+    } catch (error) {
+      errors.push({
+        code: 'LIFECYCLE_VALIDATION_ERROR',
+        message: 'Error validating lifecycle compatibility',
+        details: { error: error instanceof Error ? error.message : String(error) }
+      });
+
+      return {
+        valid: false,
+        errors,
+        warnings,
+        estimatedCost: {
+          storageCost: 0,
+          networkFees: 0,
+          totalCost: 0,
+          currency: 'sats'
+        },
+        estimatedDuration: 0
+      };
+    }
+  }
+}

package/src/migration/validation/StorageValidator.ts

@@ -0,0 +1,79 @@
+/**
+ * StorageValidator - Validates storage adapter compatibility
+ */
+
+import {
+  MigrationOptions,
+  MigrationValidationResult,
+  ValidationError,
+  ValidationWarning,
+  IValidator
+} from '../types';
+import { OriginalsConfig } from '../../types';
+
+export class StorageValidator implements IValidator {
+  constructor(private config: OriginalsConfig) {}
+
+  async validate(options: MigrationOptions): Promise<MigrationValidationResult> {
+    const errors: ValidationError[] = [];
+    const warnings: ValidationWarning[] = [];
+
+    try {
+      const storageAdapter = (this.config as any).storageAdapter;
+
+      // Check if storage adapter is available
+      if (!storageAdapter) {
+        warnings.push({
+          code: 'NO_STORAGE_ADAPTER',
+          message: 'No storage adapter configured; using memory storage (not persistent)'
+        });
+      }
+
+      // Check large file support for partial migrations
+      if (options.partialMode) {
+        // Verify storage adapter supports chunked uploads
+        if (storageAdapter && typeof storageAdapter.putChunk !== 'function') {
+          warnings.push({
+            code: 'NO_CHUNKED_UPLOAD_SUPPORT',
+            message: 'Storage adapter does not support chunked uploads; partial mode may be inefficient'
+          });
+        }
+      }
+
+      // Estimate storage costs (minimal for webvh, zero for peer/btco)
+      const storageCost = options.targetLayer === 'webvh' ? 0.001 : 0;
+
+      return {
+        valid: errors.length === 0,
+        errors,
+        warnings,
+        estimatedCost: {
+          storageCost,
+          networkFees: 0,
+          totalCost: storageCost,
+          currency: 'sats'
+        },
+        estimatedDuration: 50
+      };
+    } catch (error) {
+      errors.push({
+        code: 'STORAGE_VALIDATION_ERROR',
+        message: 'Error validating storage compatibility',
+        details: { error: error instanceof Error ? error.message : String(error) }
+      });
+
+      return {
+        valid: false,
+        errors,
+        warnings,
+        estimatedCost: {
+          storageCost: 0,
+          networkFees: 0,
+          totalCost: 0,
+          currency: 'sats'
+        },
+        estimatedDuration: 0
+      };
+    }
+  }
+}

package/src/migration/validation/ValidationPipeline.ts

@@ -0,0 +1,213 @@
+/**
+ * ValidationPipeline - Orchestrates all validation checks before migration
+ */
+
+import {
+  MigrationOptions,
+  MigrationValidationResult,
+  ValidationError,
+  ValidationWarning,
+  CostEstimate,
+  IValidator
+} from '../types';
+import { DIDCompatibilityValidator } from './DIDCompatibilityValidator';
+import { CredentialValidator } from './CredentialValidator';
+import { StorageValidator } from './StorageValidator';
+import { LifecycleValidator } from './LifecycleValidator';
+import { BitcoinValidator } from './BitcoinValidator';
+import { OriginalsConfig } from '../../types';
+import { DIDManager } from '../../did/DIDManager';
+import { CredentialManager } from '../../vc/CredentialManager';
+import { BitcoinManager } from '../../bitcoin/BitcoinManager';
+
+export class ValidationPipeline {
+  private validators: Map<string, IValidator>;
+
+  constructor(
+    private config: OriginalsConfig,
+    private didManager: DIDManager,
+    private credentialManager: CredentialManager,
+    private bitcoinManager?: BitcoinManager
+  ) {
+    this.validators = new Map();
+    this.initializeValidators();
+  }
+
+  private initializeValidators(): void {
+    this.validators.set('did', new DIDCompatibilityValidator(this.config, this.didManager));
+    this.validators.set('credential', new CredentialValidator(this.config, this.credentialManager));
+    this.validators.set('storage', new StorageValidator(this.config));
+    this.validators.set('lifecycle', new LifecycleValidator(this.config));
+    if (this.bitcoinManager) {
+      this.validators.set('bitcoin', new BitcoinValidator(this.config, this.bitcoinManager));
+    }
+  }
+
+  /**
+   * Run all validation checks for a migration
+   */
+  async validate(options: MigrationOptions): Promise<MigrationValidationResult> {
+    const errors: ValidationError[] = [];
+    const warnings: ValidationWarning[] = [];
+    let estimatedCost: CostEstimate = {
+      storageCost: 0,
+      networkFees: 0,
+      totalCost: 0,
+      currency: 'sats'
+    };
+    let estimatedDuration = 0;
+
+    try {
+      // Basic input validation
+      const inputErrors = this.validateInput(options);
+      if (inputErrors.length > 0) {
+        return {
+          valid: false,
+          errors: inputErrors,
+          warnings: [],
+          estimatedCost,
+          estimatedDuration: 0
+        };
+      }
+
+      // Run DID compatibility validation
+      const didResult = await this.validators.get('did')!.validate(options);
+      errors.push(...didResult.errors);
+      warnings.push(...didResult.warnings);
+      estimatedDuration = Math.max(estimatedDuration, didResult.estimatedDuration);
+
+      // Run credential validation if enabled
+      if (options.credentialIssuance !== false) {
+        const credResult = await this.validators.get('credential')!.validate(options);
+        errors.push(...credResult.errors);
+        warnings.push(...credResult.warnings);
+      }
+
+      // Run storage validation
+      const storageResult = await this.validators.get('storage')!.validate(options);
+      errors.push(...storageResult.errors);
+      warnings.push(...storageResult.warnings);
+      estimatedCost.storageCost = storageResult.estimatedCost.storageCost;
+
+      // Run lifecycle validation
+      const lifecycleResult = await this.validators.get('lifecycle')!.validate(options);
+      errors.push(...lifecycleResult.errors);
+      warnings.push(...lifecycleResult.warnings);
+
+      // Run Bitcoin validation for btco migrations
+      if (options.targetLayer === 'btco') {
+        const bitcoinValidator = this.validators.get('bitcoin');
+        if (!bitcoinValidator) {
+          errors.push({
+            code: 'BITCOIN_VALIDATOR_MISSING',
+            message: 'Bitcoin validator required for btco migrations but not configured',
+            details: { targetLayer: options.targetLayer }
+          });
+        } else {
+          const bitcoinResult = await bitcoinValidator.validate(options);
+          errors.push(...bitcoinResult.errors);
+          warnings.push(...bitcoinResult.warnings);
+          estimatedCost.networkFees = bitcoinResult.estimatedCost.networkFees;
+          estimatedDuration = Math.max(estimatedDuration, bitcoinResult.estimatedDuration);
+        }
+      }
+
+      // Calculate total cost
+      estimatedCost.totalCost = estimatedCost.storageCost + estimatedCost.networkFees;
+
+      return {
+        valid: errors.length === 0,
+        errors,
+        warnings,
+        estimatedCost,
+        estimatedDuration
+      };
+    } catch (error) {
+      errors.push({
+        code: 'VALIDATION_PIPELINE_ERROR',
+        message: 'Unexpected error during validation',
+        details: { error: error instanceof Error ? error.message : String(error) }
+      });
+
+      return {
+        valid: false,
+        errors,
+        warnings,
+        estimatedCost,
+        estimatedDuration
+      };
+    }
+  }
+
+  /**
+   * Validate basic input parameters
+   */
+  private validateInput(options: MigrationOptions): ValidationError[] {
+    const errors: ValidationError[] = [];
+
+    // Validate source DID
+    if (!options.sourceDid || typeof options.sourceDid !== 'string') {
+      errors.push({
+        code: 'INVALID_SOURCE_DID',
+        message: 'Source DID is required and must be a string',
+        field: 'sourceDid'
+      });
+    }
+
+    // Validate target layer
+    if (!options.targetLayer) {
+      errors.push({
+        code: 'INVALID_TARGET_LAYER',
+        message: 'Target layer is required',
+        field: 'targetLayer'
+      });
+    } else if (!['peer', 'webvh', 'btco'].includes(options.targetLayer)) {
+      errors.push({
+        code: 'INVALID_TARGET_LAYER',
+        message: 'Target layer must be one of: peer, webvh, btco',
+        field: 'targetLayer',
+        details: { received: options.targetLayer }
+      });
+    }
+
+    // Validate partial mode options
+    if (options.partialMode) {
+      if (typeof options.partialMode.chunkSize !== 'number' || options.partialMode.chunkSize <= 0) {
+        errors.push({
+          code: 'INVALID_CHUNK_SIZE',
+          message: 'Chunk size must be a positive number',
+          field: 'partialMode.chunkSize'
+        });
+      }
+    }
+
+    // Validate webvh-specific options
+    if (options.targetLayer === 'webvh' && !options.domain) {
+      errors.push({
+        code: 'DOMAIN_REQUIRED',
+        message: 'Domain is required for webvh migrations',
+        field: 'domain'
+      });
+    }
+
+    // Validate btco-specific options
+    if (options.targetLayer === 'btco') {
+      if (options.feeRate !== undefined && (typeof options.feeRate !== 'number' || options.feeRate <= 0)) {
+        errors.push({
+          code: 'INVALID_FEE_RATE',
+          message: 'Fee rate must be a positive number',
+          field: 'feeRate'
+        });
+      }
+    }
+
+    return errors;
+  }
+
+  /**
+   * Quick validation check (basic only, no async operations)
+   */
+  validateQuick(options: MigrationOptions): ValidationError[] {
+    return this.validateInput(options);
+  }
+}

package/src/storage/LocalStorageAdapter.ts

@@ -0,0 +1,61 @@
+// Local adapter is optional in this environment; keeping implementation but avoid Node typings
+// eslint-disable-next-line @typescript-eslint/ban-ts-comment
+// @ts-nocheck
+import * as fs from 'fs/promises';
+import * as path from 'path';
+import { GetObjectResult, LocalStorageAdapterOptions, StorageAdapter } from './StorageAdapter';
+
+export class LocalStorageAdapter implements StorageAdapter {
+  private baseDir: string;
+  private baseUrl?: string;
+
+  constructor(options: LocalStorageAdapterOptions) {
+    this.baseDir = options.baseDir;
+    this.baseUrl = options.baseUrl;
+  }
+
+  private resolvePath(domain: string, objectPath: string): string {
+    const safeDomain = domain.replace(/[^a-zA-Z0-9.-]/g, '_');
+    const cleanPath = objectPath.replace(/^\/+/, '');
+    return path.join(this.baseDir, safeDomain, cleanPath);
+  }
+
+  private toUrl(domain: string, objectPath: string): string {
+    const cleanPath = objectPath.replace(/^\/+/, '');
+    if (this.baseUrl) {
+      const trimmed = this.baseUrl.replace(/\/$/, '');
+      return `${trimmed}/${domain}/${cleanPath}`;
+    }
+    return `file://${this.resolvePath(domain, cleanPath)}`;
+  }
+
+  async putObject(domain: string, objectPath: string, content: Uint8Array | string): Promise<string> {
+    const fullPath = this.resolvePath(domain, objectPath);
+    await fs.mkdir(path.dirname(fullPath), { recursive: true });
+    const data = typeof content === 'string' ? Buffer.from(content) : Buffer.from(content);
+    await fs.writeFile(fullPath, data);
+    return this.toUrl(domain, objectPath);
+  }
+
+  async getObject(domain: string, objectPath: string): Promise<GetObjectResult | null> {
+    const fullPath = this.resolvePath(domain, objectPath);
+    try {
+      const content = await fs.readFile(fullPath);
+      return { content: new Uint8Array(content) };
+    } catch (e: any) {
+      if (e && e.code === 'ENOENT') return null;
+      throw e;
+    }
+  }
+
+  async exists(domain: string, objectPath: string): Promise<boolean> {
+    const fullPath = this.resolvePath(domain, objectPath);
+    try {
+      await fs.access(fullPath);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+}
+

package/src/storage/MemoryStorageAdapter.ts

@@ -0,0 +1,29 @@
+import { GetObjectResult, StorageAdapter } from './StorageAdapter';
+
+type DomainPath = string;
+
+const globalStore: Map<DomainPath, Uint8Array> = new Map();
+
+function key(domain: string, objectPath: string): string {
+  const cleanPath = objectPath.replace(/^\/+/, '');
+  return `${domain}::${cleanPath}`;
+}
+
+export class MemoryStorageAdapter implements StorageAdapter {
+  async putObject(domain: string, objectPath: string, content: Uint8Array | string): Promise<string> {
+    const data = typeof content === 'string' ? new TextEncoder().encode(content) : content;
+    globalStore.set(key(domain, objectPath), data);
+    return `mem://${domain}/${objectPath.replace(/^\/+/, '')}`;
+  }
+
+  async getObject(domain: string, objectPath: string): Promise<GetObjectResult | null> {
+    const stored = globalStore.get(key(domain, objectPath));
+    if (!stored) return null;
+    return { content: stored };
+  }
+
+  async exists(domain: string, objectPath: string): Promise<boolean> {
+    return globalStore.has(key(domain, objectPath));
+  }
+}
+

package/src/storage/StorageAdapter.ts

@@ -0,0 +1,25 @@
+export interface PutOptions {
+  contentType?: string;
+}
+
+export interface GetObjectResult {
+  content: Uint8Array;
+  contentType?: string;
+}
+
+export interface StorageAdapter {
+  // Writes content at a path under a logical domain root and returns a public URL
+  putObject(domain: string, path: string, content: Uint8Array | string, options?: PutOptions): Promise<string>;
+
+  // Reads content from a path under a domain root
+  getObject(domain: string, path: string): Promise<GetObjectResult | null>;
+
+  // Checks whether a path exists
+  exists(domain: string, path: string): Promise<boolean>;
+}
+
+export interface LocalStorageAdapterOptions {
+  baseDir: string;
+  baseUrl?: string;
+}
+

package/src/storage/index.ts

@@ -0,0 +1,3 @@
+export * from './StorageAdapter';
+export * from './MemoryStorageAdapter';
+

package/src/types/bitcoin.ts

@@ -0,0 +1,98 @@
+// Bitcoin/Ordinals types
+export interface OrdinalsInscription {
+  satoshi: string; // Unique satoshi identifier
+  inscriptionId: string;
+  content: Buffer;
+  contentType: string;
+  txid: string;
+  vout: number;
+  blockHeight?: number;
+}
+
+export interface BitcoinTransaction {
+  txid: string;
+  vin: TransactionInput[];
+  vout: TransactionOutput[];
+  fee: number;
+  blockHeight?: number;
+  confirmations?: number;
+}
+
+export interface TransactionInput {
+  txid: string;
+  vout: number;
+  scriptSig?: string;
+  witness?: string[];
+}
+
+export interface TransactionOutput {
+  value: number; // satoshis
+  scriptPubKey: string;
+  address?: string;
+}
+
+export interface Utxo {
+  txid: string;
+  vout: number;
+  value: number; // satoshis
+  scriptPubKey?: string;
+  address?: string;
+  inscriptions?: string[]; // inscription ids located on this outpoint
+  locked?: boolean; // if true, cannot be spent due to wallet locks
+}
+
+/**
+ * Extended UTXO interface that tracks whether it contains an Ordinals resource (inscription)
+ */
+export interface ResourceUtxo extends Utxo {
+  /** True if this UTXO contains an inscription or other Ordinals resource */
+  hasResource?: boolean;
+}
+
+/**
+ * Strategy for selecting UTXOs
+ */
+export type UtxoSelectionStrategy = 'minimize_change' | 'minimize_inputs' | 'optimize_size';
+
+/**
+ * Options for resource-aware UTXO selection
+ */
+export interface ResourceUtxoSelectionOptions {
+  /** Required amount in satoshis */
+  requiredAmount: number;
+  /** Fee rate in satoshis per vbyte */
+  feeRate: number;
+  /** Allow using UTXOs that contain resources (default: false) */
+  allowResourceUtxos?: boolean;
+  /** Prefer older UTXOs (default: false) */
+  preferOlder?: boolean;
+  /** Prefer UTXOs with value closer to required amount (default: false) */
+  preferCloserAmount?: boolean;
+  /** List of UTXO IDs to avoid using (format: "txid:vout") */
+  avoidUtxoIds?: string[];
+}
+
+/**
+ * Result of resource-aware UTXO selection
+ */
+export interface ResourceUtxoSelectionResult {
+  /** Selected UTXOs for the transaction */
+  selectedUtxos: ResourceUtxo[];
+  /** Total value of selected UTXOs */
+  totalSelectedValue: number;
+  /** Estimated transaction fee in satoshis */
+  estimatedFee: number;
+  /** Change amount in satoshis (0 if less than dust) */
+  changeAmount: number;
+}
+
+export const DUST_LIMIT_SATS = 546;
+
+export interface KeyPair {
+  privateKey: string; // multibase encoded
+  publicKey: string;  // multibase encoded
+}
+
+export type KeyType = 'ES256K' | 'Ed25519' | 'ES256';
+
+

package/src/types/common.ts

@@ -0,0 +1,92 @@
+import { StorageAdapter, FeeOracleAdapter, OrdinalsProvider } from '../adapters';
+import { TelemetryHooks } from '../utils/telemetry';
+import type { LogLevel, LogOutput } from '../utils/Logger';
+import type { EventLoggingConfig } from '../utils/EventLogger';
+import type { WebVHNetworkName } from './network';
+
+// Base types for the Originals protocol
+export type LayerType = 'did:peer' | 'did:webvh' | 'did:btco';
+
+export interface OriginalsConfig {
+  network: 'mainnet' | 'regtest' | 'signet';
+  bitcoinRpcUrl?: string;
+  defaultKeyType: 'ES256K' | 'Ed25519' | 'ES256';
+  keyStore?: KeyStore;
+  enableLogging?: boolean;
+  // WebVH network selection (defaults to 'pichu' - production)
+  webvhNetwork?: WebVHNetworkName;
+  // Optional pluggable adapters
+  storageAdapter?: StorageAdapter;
+  feeOracle?: FeeOracleAdapter;
+  ordinalsProvider?: OrdinalsProvider;
+  // Optional telemetry hooks
+  telemetry?: TelemetryHooks;
+  // Enhanced logging configuration
+  logging?: {
+    level?: LogLevel;
+    outputs?: LogOutput[];
+    includeTimestamps?: boolean;
+    includeContext?: boolean;
+    eventLogging?: EventLoggingConfig;
+    sanitizeLogs?: boolean; // Remove sensitive data
+  };
+  // Metrics configuration
+  metrics?: {
+    enabled?: boolean;
+    exportFormat?: 'json' | 'prometheus';
+    collectCache?: boolean;
+  };
+}
+
+export interface AssetResource {
+  id: string;                      // Logical resource ID (stable across versions)
+  type: string;                    // 'image', 'text', 'code', 'data', etc.
+  url?: string;
+  content?: string;
+  contentType: string;
+  hash: string;                    // Content hash (unique per version)
+  size?: number;
+  version?: number;                // Version number (default 1)
+  previousVersionHash?: string;    // Link to previous version (by content hash)
+  createdAt?: string;              // ISO timestamp of when this version was created
+}
+
+export interface KeyStore {
+  getPrivateKey(verificationMethodId: string): Promise<string | null>;
+  setPrivateKey(verificationMethodId: string, privateKey: string): Promise<void>;
+}
+
+/**
+ * External signer interface for DID operations (compatible with didwebvh-ts)
+ * This allows integration with external key management systems like Privy
+ */
+export interface ExternalSigner {
+  /**
+   * Sign data and return a proof value
+   * @param input - The signing input containing document and proof
+   * @returns The proof value (typically multibase-encoded signature)
+   */
+  sign(input: { document: Record<string, unknown>; proof: Record<string, unknown> }): Promise<{ proofValue: string }>;
+  
+  /**
+   * Get the verification method ID for this signer
+   * @returns The verification method ID (e.g., "did:key:z6Mk...")
+   */
+  getVerificationMethodId(): string;
+}
+
+/**
+ * External verifier interface for DID operations (compatible with didwebvh-ts)
+ */
+export interface ExternalVerifier {
+  /**
+   * Verify a signature
+   * @param signature - The signature bytes
+   * @param message - The message bytes that were signed
+   * @param publicKey - The public key bytes
+   * @returns True if the signature is valid
+   */
+  verify(signature: Uint8Array, message: Uint8Array, publicKey: Uint8Array): Promise<boolean>;
+}
+
+