@originals/sdk 1.8.2 → 1.8.3

package/package.json

@@ -1,12 +1,11 @@
 {
   "name": "@originals/sdk",
-  "version": "1.8.2",
+  "version": "1.8.3",
   "description": "TypeScript SDK for the Originals Protocol - creating, discovering, and transferring digital assets with cryptographically verifiable provenance",
   "type": "module",
-  "main": "src/index.ts",
-  "types": "src/index.ts",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
   "files": [
-    "src",
     "dist"
   ],
   "bin": {
@@ -14,8 +13,8 @@
   },
   "exports": {
     ".": {
-      "types": "./src/index.ts",
-      "import": "./src/index.ts"
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
     }
   },
   "scripts": {

package/src/adapters/FeeOracleMock.ts

@@ -1,9 +0,0 @@
-import { FeeOracleAdapter } from './types';
-
-export class FeeOracleMock implements FeeOracleAdapter {
-  constructor(private feeRate = 7) {}
-  estimateFeeRate(targetBlocks = 1): Promise<number> {
-    return Promise.resolve(Math.max(1, this.feeRate - (targetBlocks - 1)));
-  }
-}
-

package/src/adapters/index.ts

@@ -1,5 +0,0 @@
-export * from './types';
-export * from './FeeOracleMock';
-export * from './providers/OrdMockProvider';
-export * from './providers/OrdHttpProvider';
-

package/src/adapters/providers/OrdHttpProvider.ts

@@ -1,126 +0,0 @@
-/* istanbul ignore file */
-import type { OrdinalsProvider } from '../types';
-
-interface HttpProviderOptions {
-  baseUrl: string;
-}
-
-function buildUrl(baseUrl: string, path: string): string {
-  const base = baseUrl.replace(/\/$/, '');
-  return `${base}${path.startsWith('/') ? '' : '/'}${path}`;
-}
-
-async function fetchJson<T>(url: string): Promise<T | null> {
-  const res = await (globalThis as any).fetch(url, {
-    headers: {
-      'Accept': 'application/json'
-    }
-  });
-  if (!res.ok) return null;
-  return (await res.json()) as T;
-}
-
-export class OrdHttpProvider implements OrdinalsProvider {
-  private readonly baseUrl: string;
-
-  constructor(options: HttpProviderOptions) {
-    if (!options?.baseUrl) {
-      throw new Error('OrdHttpProvider requires baseUrl');
-    }
-    this.baseUrl = options.baseUrl;
-  }
-
-  async getInscriptionById(id: string) {
-    if (!id) return null;
-    const data = await fetchJson<any>(buildUrl(this.baseUrl, `/inscription/${id}`));
-    if (!data) return null;
-    // Expecting a shape similar to Ordinals indexers; adapt minimally
-    const ownerOutput: string | undefined = data.owner_output;
-    let txid = data.txid || 'unknown';
-    let vout = typeof data.vout === 'number' ? data.vout : 0;
-    if (ownerOutput && ownerOutput.includes(':')) {
-      const [tid, v] = ownerOutput.split(':');
-      txid = tid;
-      vout = Number(v) || 0;
-    }
-
-    const contentType = data.content_type || 'application/octet-stream';
-    const contentUrl = data.content_url || buildUrl(this.baseUrl, `/content/${id}`);
-    const contentRes = await (globalThis as any).fetch(contentUrl);
-    if (!contentRes.ok) return null;
-    const buf = (globalThis as any).Buffer
-      ? (globalThis as any).Buffer.from(new Uint8Array(await contentRes.arrayBuffer()))
-      : new Uint8Array(await contentRes.arrayBuffer()) as any;
-
-    return {
-      inscriptionId: data.inscription_id || id,
-      content: buf,
-      contentType,
-      txid,
-      vout,
-      satoshi: String(data.sat ?? ''),
-      blockHeight: data.block_height
-    };
-  }
-
-  async getInscriptionsBySatoshi(satoshi: string) {
-    if (!satoshi) return [];
-    const data = await fetchJson<any>(buildUrl(this.baseUrl, `/sat/${satoshi}`));
-    const ids: string[] = Array.isArray(data?.inscription_ids) ? data.inscription_ids : [];
-    return ids.map((inscriptionId) => ({ inscriptionId }));
-  }
-
-  async broadcastTransaction(_txHexOrObj: unknown): Promise<string> {
-    // For example purposes only, return a placeholder
-    return 'broadcast-txid';
-  }
-
-  async getTransactionStatus(_txid: string) {
-    return { confirmed: false };
-  }
-
-  async estimateFee(blocks: number = 1): Promise<number> {
-    // Basic fallback: some providers expose fee estimates; for example purposes, return linear estimate
-    return 5 * Math.max(1, blocks);
-  }
-
-  async createInscription(params: { data: any; contentType: string; feeRate?: number; }) {
-    // Example placeholder: a real implementation would POST to a service
-    // Here we return a deterministic mock-like result to avoid network coupling in code
-    const inscriptionId = `insc-${Math.random().toString(36).slice(2)}`;
-    const txid = `tx-${Math.random().toString(36).slice(2)}`;
-    return {
-      inscriptionId,
-      revealTxId: txid,
-      txid,
-      vout: 0,
-      blockHeight: undefined,
-      content: params.data,
-      contentType: params.contentType,
-      feeRate: params.feeRate
-    };
-  }
-
-  async transferInscription(inscriptionId: string, _toAddress: string, _options?: { feeRate?: number }) {
-    if (!inscriptionId) throw new Error('inscriptionId required');
-    const txid = `tx-${Math.random().toString(36).slice(2)}`;
-    return {
-      txid,
-      vin: [{ txid: 'prev', vout: 0 }],
-      vout: [{ value: 546, scriptPubKey: 'script' }],
-      fee: 100,
-      confirmations: 0
-    };
-  }
-}
-
-export async function createOrdinalsProviderFromEnv(): Promise<OrdinalsProvider> {
-  const useLive = String(((globalThis as any).process?.env?.USE_LIVE_ORD_PROVIDER) || '').toLowerCase() === 'true';
-  if (useLive) {
-    const baseUrl = ((globalThis as any).process?.env?.ORD_PROVIDER_BASE_URL) || 'https://ord.example.com/api';
-    return new OrdHttpProvider({ baseUrl });
-  }
-  const mod = await import('./OrdMockProvider');
-  return new mod.OrdMockProvider();
-}
-

package/src/adapters/providers/OrdMockProvider.ts

@@ -1,101 +0,0 @@
-import { OrdinalsProvider } from '../types';
-
-export interface OrdMockState {
-  inscriptionsById: Map<string, {
-    inscriptionId: string;
-    content: Buffer;
-    contentType: string;
-    txid: string;
-    vout: number;
-    satoshi?: string;
-    blockHeight?: number;
-  }>;
-  inscriptionsBySatoshi: Map<string, string[]>;
-  feeRate: number;
-}
-
-export class OrdMockProvider implements OrdinalsProvider {
-  private state: OrdMockState;
-
-  constructor(state?: Partial<OrdMockState>) {
-    this.state = {
-      inscriptionsById: new Map(),
-      inscriptionsBySatoshi: new Map(),
-      feeRate: 5,
-      ...state
-    } as OrdMockState;
-  }
-
-  async getInscriptionById(id: string) {
-    const rec = this.state.inscriptionsById.get(id);
-    return rec ? { ...rec } : null;
-  }
-
-  async getInscriptionsBySatoshi(satoshi: string) {
-    const list = this.state.inscriptionsBySatoshi.get(satoshi) || [];
-    return list.map((inscriptionId) => ({ inscriptionId }));
-  }
-
-  async broadcastTransaction(_txHexOrObj: unknown): Promise<string> {
-    return 'mock-broadcast-txid';
-  }
-
-  async getTransactionStatus(txid: string) {
-    return { confirmed: true, blockHeight: 1, confirmations: 1 };
-  }
-
-  async estimateFee(blocks = 1): Promise<number> {
-    return Math.max(1, this.state.feeRate - (blocks - 1));
-  }
-
-  async createInscription(params: { data: Buffer; contentType: string; feeRate?: number; }) {
-    const inscriptionId = `insc-${Math.random().toString(36).slice(2)}`;
-    const txid = `tx-${Math.random().toString(36).slice(2)}`;
-    // Generate a valid numeric satoshi identifier (not sat-123 format)
-    const satoshi = `${Math.floor(Math.random() * 1e12)}`;
-    const vout = 0;
-    const record = {
-      inscriptionId,
-      content: params.data,
-      contentType: params.contentType,
-      txid,
-      vout,
-      satoshi,
-      blockHeight: 1
-    };
-    this.state.inscriptionsById.set(inscriptionId, record);
-    const list = this.state.inscriptionsBySatoshi.get(satoshi) || [];
-    list.push(inscriptionId);
-    this.state.inscriptionsBySatoshi.set(satoshi, list);
-    return {
-      inscriptionId,
-      revealTxId: txid,
-      commitTxId: undefined,
-      satoshi,
-      txid,
-      vout,
-      blockHeight: 1,
-      content: params.data,
-      contentType: params.contentType,
-      feeRate: params.feeRate
-    };
-  }
-
-  async transferInscription(inscriptionId: string, _toAddress: string, _options?: { feeRate?: number }) {
-    const rec = this.state.inscriptionsById.get(inscriptionId);
-    if (!rec) {
-      return Promise.reject(new Error('inscription not found'));
-    }
-    const txid = `tx-${Math.random().toString(36).slice(2)}`;
-    return {
-      txid,
-      vin: [{ txid: rec.txid, vout: rec.vout }],
-      vout: [{ value: 546, scriptPubKey: 'script' }],
-      fee: 100,
-      blockHeight: 1,
-      confirmations: 0,
-      satoshi: rec.satoshi
-    };
-  }
-}
-

package/src/adapters/types.ts

@@ -1,66 +0,0 @@
-export interface StoragePutOptions {
-  contentType?: string;
-  cacheControl?: string;
-}
-
-export interface StorageGetResult {
-  content: Buffer;
-  contentType: string;
-}
-
-export interface StorageAdapter {
-  put(objectKey: string, data: Buffer | string, options?: StoragePutOptions): Promise<string>;
-  get(objectKey: string): Promise<StorageGetResult | null>;
-  delete?(objectKey: string): Promise<boolean>;
-}
-
-export interface FeeOracleAdapter {
-  // Returns sats/vB (or feerate unit appropriate to the network) for the given target blocks
-  estimateFeeRate(targetBlocks?: number): Promise<number>;
-}
-
-export interface OrdinalsProvider {
-  getInscriptionById(id: string): Promise<{
-    inscriptionId: string;
-    content: Buffer;
-    contentType: string;
-    txid: string;
-    vout: number;
-    satoshi?: string;
-    blockHeight?: number;
-  } | null>;
-  getInscriptionsBySatoshi(satoshi: string): Promise<Array<{ inscriptionId: string }>>;
-  broadcastTransaction(txHexOrObj: unknown): Promise<string>;
-  getTransactionStatus(txid: string): Promise<{ confirmed: boolean; blockHeight?: number; confirmations?: number }>;
-  estimateFee(blocks?: number): Promise<number>;
-  createInscription(params: {
-    data: Buffer;
-    contentType: string;
-    feeRate?: number;
-  }): Promise<{
-    inscriptionId: string;
-    revealTxId: string;
-    commitTxId?: string;
-    satoshi?: string;
-    txid?: string;
-    vout?: number;
-    blockHeight?: number;
-    content?: Buffer;
-    contentType?: string;
-    feeRate?: number;
-  }>;
-  transferInscription(
-    inscriptionId: string,
-    toAddress: string,
-    options?: { feeRate?: number }
-  ): Promise<{
-    txid: string;
-    vin: Array<{ txid: string; vout: number }>;
-    vout: Array<{ value: number; scriptPubKey: string; address?: string }>;
-    fee: number;
-    blockHeight?: number;
-    confirmations?: number;
-    satoshi?: string;
-  }>;
-}
-

package/src/bitcoin/BitcoinManager.ts

@@ -1,329 +0,0 @@
-import {
-  OriginalsConfig,
-  OrdinalsInscription,
-  BitcoinTransaction,
-  DUST_LIMIT_SATS
-} from '../types';
-import type { FeeOracleAdapter, OrdinalsProvider } from '../adapters';
-import { emitTelemetry, StructuredError } from '../utils/telemetry';
-import { validateBitcoinAddress } from '../utils/bitcoin-address';
-import { validateSatoshiNumber } from '../utils/satoshi-validation';
-
-export class BitcoinManager {
-  private readonly feeOracle?: FeeOracleAdapter;
-  private readonly ord?: OrdinalsProvider;
-
-  constructor(private config: OriginalsConfig) {
-    this.feeOracle = config.feeOracle;
-    this.ord = config.ordinalsProvider;
-  }
-
-  private async resolveFeeRate(targetBlocks = 1, provided?: number): Promise<number | undefined> {
-    // 1) Prefer external fee oracle
-    if (this.feeOracle) {
-      try {
-        const estimated = await this.feeOracle.estimateFeeRate(targetBlocks);
-        if (typeof estimated === 'number' && Number.isFinite(estimated) && estimated > 0) {
-          emitTelemetry(this.config.telemetry, {
-            name: 'bitcoin.fee.estimated',
-            attributes: { feeRate: estimated, source: 'feeOracle' }
-          });
-          return estimated;
-        }
-      } catch (error) {
-        emitTelemetry(this.config.telemetry, {
-          name: 'bitcoin.fee.error',
-          level: 'warn',
-          attributes: { error: String(error), source: 'feeOracle' }
-        });
-      }
-    }
-
-    // 2) Fallback to ordinals provider if present
-    if (this.ord) {
-      try {
-        const estimated = await this.ord.estimateFee(targetBlocks);
-        if (typeof estimated === 'number' && Number.isFinite(estimated) && estimated > 0) {
-          emitTelemetry(this.config.telemetry, {
-            name: 'bitcoin.fee.estimated',
-            attributes: { feeRate: estimated, source: 'ordinalsProvider' }
-          });
-          return estimated;
-        }
-      } catch (error) {
-        emitTelemetry(this.config.telemetry, {
-          name: 'bitcoin.fee.error',
-          level: 'warn',
-          attributes: { error: String(error), source: 'ordinalsProvider' }
-        });
-      }
-    }
-
-    // 3) If caller provided a valid non-zero fee rate, use it as last resort
-    if (typeof provided === 'number' && Number.isFinite(provided) && provided > 0) {
-      return provided;
-    }
-
-    return undefined;
-  }
-
-  async inscribeData(
-    data: any,
-    contentType: string,
-    feeRate?: number
-  ): Promise<OrdinalsInscription> {
-    // Input validation
-    if (!data) {
-      throw new StructuredError('INVALID_INPUT', 'Data to inscribe cannot be null or undefined');
-    }
-    if (!contentType || typeof contentType !== 'string') {
-      throw new StructuredError('INVALID_INPUT', 'Content type must be a non-empty string');
-    }
-    // Validate contentType is a valid MIME type
-    if (!/^[a-zA-Z0-9][a-zA-Z0-9!#$&^_.+-]{0,126}\/[a-zA-Z0-9][a-zA-Z0-9!#$&^_.+-]{0,126}$/.test(contentType)) {
-      throw new StructuredError('INVALID_INPUT', `Invalid MIME type format: ${contentType}`);
-    }
-    if (feeRate !== undefined && (typeof feeRate !== 'number' || feeRate <= 0 || !Number.isFinite(feeRate))) {
-      throw new StructuredError('INVALID_INPUT', 'Fee rate must be a positive number');
-    }
-    // Security: Reject extremely high fee rates to prevent accidental fund drainage
-    const MAX_REASONABLE_FEE_RATE = 10_000; // sat/vB
-    if (feeRate !== undefined && feeRate > MAX_REASONABLE_FEE_RATE) {
-      throw new StructuredError('INVALID_INPUT', `Fee rate ${feeRate} exceeds maximum reasonable fee rate of ${MAX_REASONABLE_FEE_RATE} sat/vB`);
-    }
-    
-    const effectiveFeeRate = await this.resolveFeeRate(1, feeRate);
-
-    if (!this.ord) {
-      throw new StructuredError(
-        'ORD_PROVIDER_REQUIRED',
-        'Ordinals provider must be configured to inscribe data on Bitcoin. ' +
-        'Please provide an ordinalsProvider in your SDK configuration. ' +
-        'For testing, use: import { OrdMockProvider } from \'@originals/sdk\';'
-      );
-    }
-
-    if (typeof this.ord.createInscription !== 'function') {
-      throw new StructuredError(
-        'ORD_PROVIDER_UNSUPPORTED',
-        'Configured ordinals provider does not support inscription creation'
-      );
-    }
-
-    const creation = await this.ord.createInscription({ data, contentType, feeRate: effectiveFeeRate });
-    const txid = creation.txid ?? creation.revealTxId;
-    if (!creation.inscriptionId || !txid) {
-      throw new StructuredError(
-        'ORD_PROVIDER_INVALID_RESPONSE',
-        'Ordinals provider did not return a valid inscription identifier or transaction id'
-      );
-    }
-
-    let satoshi = creation.satoshi ?? '';
-    if (!satoshi) {
-      satoshi = (await this.getSatoshiFromInscription(creation.inscriptionId)) ?? '';
-    }
-
-    // Validate satoshi before using it
-    if (satoshi) {
-      const validation = validateSatoshiNumber(satoshi);
-      if (!validation.valid) {
-        throw new StructuredError(
-          'INVALID_SATOSHI',
-          `Ordinals provider returned invalid satoshi identifier: ${validation.error}`
-        );
-      }
-    }
-
-    let recordedFeeRate: number | undefined;
-    if (this.feeOracle) {
-      recordedFeeRate = effectiveFeeRate;
-    } else if (typeof feeRate === 'number' && Number.isFinite(feeRate) && feeRate > 0) {
-      recordedFeeRate = feeRate;
-    } else {
-      recordedFeeRate = creation.feeRate ?? effectiveFeeRate;
-    }
-
-    const inscription: OrdinalsInscription & {
-      revealTxId?: string;
-      commitTxId?: string;
-      feeRate?: number;
-    } = {
-      satoshi,
-      inscriptionId: creation.inscriptionId,
-      content: creation.content ?? data,
-      contentType: creation.contentType ?? contentType,
-      txid,
-      vout: typeof creation.vout === 'number' ? creation.vout : 0,
-      blockHeight: creation.blockHeight,
-      revealTxId: creation.revealTxId,
-      commitTxId: creation.commitTxId,
-      feeRate: recordedFeeRate
-    };
-
-    return inscription;
-  }
-
-  async trackInscription(inscriptionId: string): Promise<OrdinalsInscription | null> {
-    if (this.ord) {
-      const info = await this.ord.getInscriptionById(inscriptionId);
-      if (!info) return null;
-      return {
-        satoshi: info.satoshi ?? '',
-        inscriptionId: info.inscriptionId,
-        content: info.content,
-        contentType: info.contentType,
-        txid: info.txid,
-        vout: info.vout,
-        blockHeight: info.blockHeight
-      };
-    }
-    return null;
-  }
-
-  async transferInscription(
-    inscription: OrdinalsInscription,
-    toAddress: string
-  ): Promise<BitcoinTransaction> {
-    // Input validation
-    if (!inscription || typeof inscription !== 'object') {
-      throw new StructuredError('INVALID_INPUT', 'Inscription must be a valid OrdinalsInscription object');
-    }
-    if (!inscription.inscriptionId || typeof inscription.inscriptionId !== 'string') {
-      throw new StructuredError('INVALID_INPUT', 'Inscription must have a valid inscriptionId');
-    }
-    if (!toAddress || typeof toAddress !== 'string') {
-      throw new StructuredError('INVALID_INPUT', 'Destination address must be a non-empty string');
-    }
-    
-    // Validate Bitcoin address format and checksum
-    try {
-      validateBitcoinAddress(toAddress, this.config.network);
-    } catch (error) {
-      const message = error instanceof Error ? error.message : 'Invalid Bitcoin address';
-      throw new StructuredError('INVALID_ADDRESS', message);
-    }
-    
-    const effectiveFeeRate = await this.resolveFeeRate(1);
-
-    if (!this.ord) {
-      throw new StructuredError(
-        'ORD_PROVIDER_REQUIRED',
-        'Ordinals provider must be configured to transfer inscriptions on Bitcoin. ' +
-        'Please provide an ordinalsProvider in your SDK configuration. ' +
-        'For testing, use: import { OrdMockProvider } from \'@originals/sdk\';'
-      );
-    }
-
-    if (typeof this.ord.transferInscription !== 'function') {
-      throw new StructuredError(
-        'ORD_PROVIDER_UNSUPPORTED',
-        'Configured ordinals provider does not support inscription transfers'
-      );
-    }
-
-    const response = await this.ord.transferInscription(inscription.inscriptionId, toAddress, {
-      feeRate: effectiveFeeRate
-    });
-
-    if (!response || !response.txid) {
-      throw new StructuredError(
-        'ORD_PROVIDER_INVALID_RESPONSE',
-        'Ordinals provider did not return a valid transfer transaction'
-      );
-    }
-
-    if (response.satoshi) {
-      inscription.satoshi = response.satoshi;
-    }
-
-    return {
-      txid: response.txid,
-      vin: response.vin ?? [{ txid: inscription.txid, vout: inscription.vout }],
-      vout:
-        response.vout?.length
-          ? response.vout
-          : [{ value: DUST_LIMIT_SATS, scriptPubKey: 'script', address: toAddress }],
-      fee: response.fee,
-      blockHeight: response.blockHeight,
-      confirmations: response.confirmations
-    };
-  }
-
-  async preventFrontRunning(satoshi: string): Promise<boolean> {
-    if (!satoshi) throw new StructuredError('SATOSHI_REQUIRED', 'Satoshi identifier is required');
-    // Naive implementation: check for multiple inscriptions on same satoshi via provider
-    if (this.ord) {
-      const list = await this.ord.getInscriptionsBySatoshi(satoshi);
-      return list.length <= 1;
-    }
-    return true;
-  }
-
-  async getSatoshiFromInscription(inscriptionId: string): Promise<string | null> {
-    if (this.ord) {
-      const info = await this.ord.getInscriptionById(inscriptionId);
-      const satoshi = info?.satoshi;
-      
-      // Validate satoshi before returning
-      if (satoshi) {
-        const validation = validateSatoshiNumber(satoshi);
-        if (!validation.valid) {
-          // Return null if validation fails (don't return empty or invalid string)
-          return null;
-        }
-        return satoshi;
-      }
-      return null;
-    }
-    return null;
-  }
-
-  async validateBTCODID(didId: string): Promise<boolean> {
-    // Validate that a did:btco DID exists on Bitcoin
-    const satoshi = this.extractSatoshiFromBTCODID(didId);
-    if (!satoshi) return false;
-    
-    // Validate the extracted satoshi number
-    const validation = validateSatoshiNumber(satoshi);
-    if (!validation.valid) return false;
-    
-    if (!this.ord) return false;
-    const inscriptions = await this.ord.getInscriptionsBySatoshi(satoshi);
-    return inscriptions.length > 0;
-  }
-
-  private extractSatoshiFromBTCODID(didId: string): string | null {
-    // Extract satoshi identifier from did:btco DID
-    if (!didId.startsWith('did:btco:')) return null;
-    
-    const parts = didId.split(':');
-    let satoshi: string | null = null;
-    
-    // Handle different network prefixes:
-    // did:btco:123456 (mainnet) - 3 parts
-    // did:btco:test:123456 or did:btco:sig:123456 - 4 parts
-    if (parts.length === 3) {
-      satoshi = parts[2];
-    } else if (parts.length === 4) {
-      // Validate network prefix - only 'test' and 'sig' are allowed
-      const network = parts[2];
-      if (network !== 'test' && network !== 'sig') {
-        return null;
-      }
-      satoshi = parts[3];
-    }
-    
-    // Validate the extracted satoshi format
-    if (satoshi) {
-      const validation = validateSatoshiNumber(satoshi);
-      if (!validation.valid) {
-        return null;
-      }
-    }
-    
-    return satoshi;
-  }
-}
-
-