@originals/sdk 1.8.1 → 1.8.2

package/dist/utils/hash.js

@@ -5,6 +5,7 @@ export async function sha256Bytes(input) {
     if (!subtle) {
         throw new Error('SubtleCrypto not available in this environment');
     }
+    // Use type assertion to handle Uint8Array<ArrayBufferLike> compatibility with SubtleCrypto
     const digest = await subtle.digest('SHA-256', data);
     return new Uint8Array(digest);
 }

package/package.json

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

package/src/adapters/FeeOracleMock.ts

@@ -0,0 +1,9 @@
+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

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

package/src/adapters/providers/OrdHttpProvider.ts

@@ -0,0 +1,126 @@
+/* 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

@@ -0,0 +1,101 @@
+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

@@ -0,0 +1,66 @@
+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

@@ -0,0 +1,329 @@
+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;
+  }
+}
+
+