@originals/sdk 1.4.3 → 1.4.5

package/dist/resources/types.js

@@ -0,0 +1,80 @@
+/**
+ * Resource types for the Originals SDK ResourceManager.
+ *
+ * Resources in the Originals protocol are immutable, content-addressed entities
+ * that can be versioned through a linked hash chain.
+ */
+/**
+ * Common MIME types and their resource type mappings
+ */
+export const MIME_TYPE_MAP = {
+    // Images
+    'image/png': 'image',
+    'image/jpeg': 'image',
+    'image/gif': 'image',
+    'image/webp': 'image',
+    'image/svg+xml': 'image',
+    'image/bmp': 'image',
+    'image/tiff': 'image',
+    // Text
+    'text/plain': 'text',
+    'text/html': 'text',
+    'text/css': 'text',
+    'text/csv': 'text',
+    'text/markdown': 'text',
+    // Code
+    'text/javascript': 'code',
+    'application/javascript': 'code',
+    'text/typescript': 'code',
+    'application/typescript': 'code',
+    'text/x-python': 'code',
+    'application/x-python-code': 'code',
+    'text/x-rust': 'code',
+    'text/x-go': 'code',
+    'text/x-java': 'code',
+    'text/x-c': 'code',
+    'text/x-cpp': 'code',
+    // Data formats
+    'application/json': 'data',
+    'application/xml': 'data',
+    'text/xml': 'data',
+    'application/yaml': 'data',
+    'text/yaml': 'data',
+    'application/toml': 'data',
+    // Documents
+    'application/pdf': 'document',
+    'application/msword': 'document',
+    'application/vnd.openxmlformats-officedocument.wordprocessingml.document': 'document',
+    'application/vnd.ms-excel': 'document',
+    'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet': 'document',
+    'application/vnd.ms-powerpoint': 'document',
+    'application/vnd.openxmlformats-officedocument.presentationml.presentation': 'document',
+    // Audio
+    'audio/mpeg': 'audio',
+    'audio/mp3': 'audio',
+    'audio/wav': 'audio',
+    'audio/ogg': 'audio',
+    'audio/webm': 'audio',
+    'audio/flac': 'audio',
+    // Video
+    'video/mp4': 'video',
+    'video/webm': 'video',
+    'video/ogg': 'video',
+    'video/quicktime': 'video',
+    'video/x-msvideo': 'video',
+    // Binary
+    'application/octet-stream': 'binary',
+    'application/zip': 'binary',
+    'application/gzip': 'binary',
+    'application/x-tar': 'binary',
+    'application/wasm': 'binary',
+};
+/**
+ * Default configuration values
+ */
+export const DEFAULT_RESOURCE_CONFIG = {
+    defaultMaxSize: 10 * 1024 * 1024, // 10MB
+    storeContent: true,
+    allowedContentTypes: [],
+    strictMimeValidation: true,
+};

package/dist/storage/LocalStorageAdapter.d.ts

@@ -0,0 +1,11 @@
+import { GetObjectResult, LocalStorageAdapterOptions, StorageAdapter } from './StorageAdapter';
+export declare class LocalStorageAdapter implements StorageAdapter {
+    private baseDir;
+    private baseUrl?;
+    constructor(options: LocalStorageAdapterOptions);
+    private resolvePath;
+    private toUrl;
+    putObject(domain: string, objectPath: string, content: Uint8Array | string): Promise<string>;
+    getObject(domain: string, objectPath: string): Promise<GetObjectResult | null>;
+    exists(domain: string, objectPath: string): Promise<boolean>;
+}

package/dist/storage/LocalStorageAdapter.js

@@ -0,0 +1,53 @@
+// 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';
+export class LocalStorageAdapter {
+    constructor(options) {
+        this.baseDir = options.baseDir;
+        this.baseUrl = options.baseUrl;
+    }
+    resolvePath(domain, objectPath) {
+        const safeDomain = domain.replace(/[^a-zA-Z0-9.-]/g, '_');
+        const cleanPath = objectPath.replace(/^\/+/, '');
+        return path.join(this.baseDir, safeDomain, cleanPath);
+    }
+    toUrl(domain, objectPath) {
+        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, objectPath, content) {
+        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, objectPath) {
+        const fullPath = this.resolvePath(domain, objectPath);
+        try {
+            const content = await fs.readFile(fullPath);
+            return { content: new Uint8Array(content) };
+        }
+        catch (e) {
+            if (e && e.code === 'ENOENT')
+                return null;
+            throw e;
+        }
+    }
+    async exists(domain, objectPath) {
+        const fullPath = this.resolvePath(domain, objectPath);
+        try {
+            await fs.access(fullPath);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+}

package/dist/storage/MemoryStorageAdapter.d.ts

@@ -0,0 +1,6 @@
+import { GetObjectResult, StorageAdapter } from './StorageAdapter';
+export declare class MemoryStorageAdapter implements StorageAdapter {
+    putObject(domain: string, objectPath: string, content: Uint8Array | string): Promise<string>;
+    getObject(domain: string, objectPath: string): Promise<GetObjectResult | null>;
+    exists(domain: string, objectPath: string): Promise<boolean>;
+}

package/dist/storage/MemoryStorageAdapter.js

@@ -0,0 +1,21 @@
+const globalStore = new Map();
+function key(domain, objectPath) {
+    const cleanPath = objectPath.replace(/^\/+/, '');
+    return `${domain}::${cleanPath}`;
+}
+export class MemoryStorageAdapter {
+    async putObject(domain, objectPath, content) {
+        const data = typeof content === 'string' ? new TextEncoder().encode(content) : content;
+        globalStore.set(key(domain, objectPath), data);
+        return `mem://${domain}/${objectPath.replace(/^\/+/, '')}`;
+    }
+    async getObject(domain, objectPath) {
+        const stored = globalStore.get(key(domain, objectPath));
+        if (!stored)
+            return null;
+        return { content: stored };
+    }
+    async exists(domain, objectPath) {
+        return globalStore.has(key(domain, objectPath));
+    }
+}

package/dist/storage/StorageAdapter.d.ts

@@ -0,0 +1,16 @@
+export interface PutOptions {
+    contentType?: string;
+}
+export interface GetObjectResult {
+    content: Uint8Array;
+    contentType?: string;
+}
+export interface StorageAdapter {
+    putObject(domain: string, path: string, content: Uint8Array | string, options?: PutOptions): Promise<string>;
+    getObject(domain: string, path: string): Promise<GetObjectResult | null>;
+    exists(domain: string, path: string): Promise<boolean>;
+}
+export interface LocalStorageAdapterOptions {
+    baseDir: string;
+    baseUrl?: string;
+}

package/dist/storage/StorageAdapter.js

@@ -0,0 +1 @@
+export {};

package/dist/storage/index.d.ts

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

package/dist/storage/index.js

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

package/dist/types/bitcoin.d.ts

@@ -0,0 +1,84 @@
+export interface OrdinalsInscription {
+    satoshi: string;
+    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;
+    scriptPubKey: string;
+    address?: string;
+}
+export interface Utxo {
+    txid: string;
+    vout: number;
+    value: number;
+    scriptPubKey?: string;
+    address?: string;
+    inscriptions?: string[];
+    locked?: boolean;
+}
+/**
+ * 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 declare const DUST_LIMIT_SATS = 546;
+export interface KeyPair {
+    privateKey: string;
+    publicKey: string;
+}
+export type KeyType = 'ES256K' | 'Ed25519' | 'ES256';

package/dist/types/bitcoin.js

@@ -0,0 +1 @@
+export const DUST_LIMIT_SATS = 546;

package/dist/types/common.d.ts

@@ -0,0 +1,82 @@
+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';
+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;
+    webvhNetwork?: WebVHNetworkName;
+    storageAdapter?: StorageAdapter;
+    feeOracle?: FeeOracleAdapter;
+    ordinalsProvider?: OrdinalsProvider;
+    telemetry?: TelemetryHooks;
+    logging?: {
+        level?: LogLevel;
+        outputs?: LogOutput[];
+        includeTimestamps?: boolean;
+        includeContext?: boolean;
+        eventLogging?: EventLoggingConfig;
+        sanitizeLogs?: boolean;
+    };
+    metrics?: {
+        enabled?: boolean;
+        exportFormat?: 'json' | 'prometheus';
+        collectCache?: boolean;
+    };
+}
+export interface AssetResource {
+    id: string;
+    type: string;
+    url?: string;
+    content?: string;
+    contentType: string;
+    hash: string;
+    size?: number;
+    version?: number;
+    previousVersionHash?: string;
+    createdAt?: string;
+}
+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 Turnkey
+ */
+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>;
+}

package/dist/types/common.js

@@ -0,0 +1 @@
+export {};

package/dist/types/credentials.d.ts

@@ -0,0 +1,75 @@
+import { LayerType } from './common';
+export interface VerifiableCredential {
+    '@context': string[];
+    type: string[];
+    id?: string;
+    issuer: string | Issuer;
+    issuanceDate: string;
+    expirationDate?: string;
+    credentialSubject: CredentialSubject;
+    credentialStatus?: CredentialStatus;
+    proof?: Proof | Proof[];
+}
+export interface Issuer {
+    id: string;
+    name?: string;
+}
+export interface CredentialSubject {
+    id?: string;
+    [key: string]: any;
+}
+export interface CredentialStatus {
+    id: string;
+    type: string;
+}
+export interface Proof {
+    type: string;
+    created: string;
+    verificationMethod: string;
+    proofPurpose: string;
+    proofValue: string;
+}
+export interface VerifiablePresentation {
+    '@context': string[];
+    type: string[];
+    id?: string;
+    holder: string;
+    verifiableCredential: VerifiableCredential[];
+    proof?: Proof | Proof[];
+}
+export interface ResourceCreatedCredential extends VerifiableCredential {
+    credentialSubject: {
+        id: string;
+        resourceId: string;
+        resourceType: string;
+        createdAt: string;
+        creator: string;
+    };
+}
+export interface ResourceUpdatedCredential extends VerifiableCredential {
+    credentialSubject: {
+        id: string;
+        resourceId: string;
+        updatedAt: string;
+        updateReason?: string;
+    };
+}
+export interface ResourceMigratedCredential extends VerifiableCredential {
+    credentialSubject: {
+        id: string;
+        resourceId: string;
+        fromLayer: LayerType;
+        toLayer: LayerType;
+        migratedAt: string;
+        migrationReason?: string;
+    };
+}
+export interface KeyRecoveryCredential extends VerifiableCredential {
+    credentialSubject: {
+        id: string;
+        recoveredAt: string;
+        recoveryReason: string;
+        previousVerificationMethods: string[];
+        newVerificationMethod: string;
+    };
+}

package/dist/types/credentials.js

@@ -0,0 +1 @@
+export {};

package/dist/types/did.d.ts

@@ -0,0 +1,26 @@
+export interface DIDDocument {
+    '@context': string[];
+    id: string;
+    verificationMethod?: VerificationMethod[];
+    authentication?: (string | VerificationMethod)[];
+    assertionMethod?: (string | VerificationMethod)[];
+    keyAgreement?: (string | VerificationMethod)[];
+    capabilityInvocation?: (string | VerificationMethod)[];
+    capabilityDelegation?: (string | VerificationMethod)[];
+    service?: ServiceEndpoint[];
+    controller?: string[];
+    alsoKnownAs?: string[];
+}
+export interface VerificationMethod {
+    id: string;
+    type: string;
+    controller: string;
+    publicKeyMultibase: string;
+    revoked?: string;
+    compromised?: string;
+}
+export interface ServiceEndpoint {
+    id: string;
+    type: string;
+    serviceEndpoint: string | object;
+}

package/dist/types/did.js

@@ -0,0 +1 @@
+export {};

package/dist/types/index.d.ts

@@ -0,0 +1,5 @@
+export * from './common';
+export * from './did';
+export * from './credentials';
+export * from './bitcoin';
+export * from './network';

package/dist/types/index.js

@@ -0,0 +1,5 @@
+export * from './common';
+export * from './did';
+export * from './credentials';
+export * from './bitcoin';
+export * from './network';

package/dist/types/network.d.ts

@@ -0,0 +1,78 @@
+/**
+ * WebVH Network Configuration
+ *
+ * Defines the three deployment networks for the Originals Protocol:
+ * - magby: Development network (patch versions) → Bitcoin regtest
+ * - cleffa: Staging network (minor versions) → Bitcoin signet
+ * - pichu: Production network (major versions) → Bitcoin mainnet
+ */
+export type WebVHNetworkName = 'magby' | 'cleffa' | 'pichu';
+export type BitcoinNetworkName = 'mainnet' | 'regtest' | 'signet';
+export type VersionStability = 'patch' | 'minor' | 'major';
+export interface WebVHNetworkConfig {
+    name: WebVHNetworkName;
+    domain: string;
+    stability: VersionStability;
+    description: string;
+    contextUrl: string;
+    bitcoinNetwork: BitcoinNetworkName;
+}
+/**
+ * Network configurations for the Originals Protocol WebVH deployments
+ */
+export declare const WEBVH_NETWORKS: Record<WebVHNetworkName, WebVHNetworkConfig>;
+/**
+ * Default network for backward compatibility
+ */
+export declare const DEFAULT_WEBVH_NETWORK: WebVHNetworkName;
+/**
+ * Get network configuration by name
+ * @param network - Network name
+ * @returns Network configuration
+ */
+export declare function getNetworkConfig(network: WebVHNetworkName): WebVHNetworkConfig;
+/**
+ * Get network domain
+ * @param network - Network name
+ * @returns Network domain
+ */
+export declare function getNetworkDomain(network: WebVHNetworkName): string;
+/**
+ * Get network context URL
+ * @param network - Network name
+ * @returns Context URL for the network
+ */
+export declare function getNetworkContextUrl(network: WebVHNetworkName): string;
+/**
+ * Validate that a version string matches the network's stability requirements
+ * @param version - Semver version string (e.g., "1.2.3")
+ * @param network - Network name
+ * @returns True if the version is allowed on this network
+ */
+export declare function validateVersionForNetwork(version: string, network: WebVHNetworkName): boolean;
+/**
+ * Get the appropriate network for a given version
+ * Returns the most restrictive network that accepts this version
+ * @param version - Semver version string
+ * @returns Recommended network name
+ */
+export declare function getRecommendedNetworkForVersion(version: string): WebVHNetworkName;
+/**
+ * Get the corresponding Bitcoin network for a WebVH network
+ * This ensures consistent environment mapping across the stack:
+ * - magby (dev) → regtest (dev)
+ * - cleffa (staging) → signet (staging)
+ * - pichu (production) → mainnet (production)
+ *
+ * @param webvhNetwork - WebVH network name
+ * @returns Corresponding Bitcoin network name
+ */
+export declare function getBitcoinNetworkForWebVH(webvhNetwork: WebVHNetworkName): BitcoinNetworkName;
+/**
+ * Get the WebVH network that corresponds to a Bitcoin network
+ * This is the reverse mapping of getBitcoinNetworkForWebVH
+ *
+ * @param bitcoinNetwork - Bitcoin network name
+ * @returns Corresponding WebVH network name, or undefined if no mapping exists
+ */
+export declare function getWebVHNetworkForBitcoin(bitcoinNetwork: BitcoinNetworkName): WebVHNetworkName | undefined;