@originals/sdk 1.8.1 → 1.8.2

package/src/bitcoin/BroadcastClient.ts

@@ -0,0 +1,54 @@
+export interface TransactionStatus {
+  confirmed: boolean;
+  confirmations?: number;
+}
+
+export interface Broadcaster {
+  (txHex: string): Promise<string>; // returns txid
+}
+
+export interface StatusProvider {
+  (txid: string): Promise<TransactionStatus>;
+}
+
+export interface BroadcastOptions {
+  pollIntervalMs?: number;
+  maxAttempts?: number;
+}
+
+/**
+ * Broadcast client with idempotency and confirmation polling.
+ * Designed to be predictable and simple, honoring behavior expected by the
+ * ordinalsplus legacy components which are finicky about retries.
+ */
+export class BroadcastClient {
+  private inflight = new Map<string, Promise<string>>();
+
+  constructor(private readonly broadcaster: Broadcaster, private readonly statusProvider: StatusProvider) {}
+
+  broadcastIdempotent(txidKey: string, create: () => Promise<string>): Promise<string> {
+    if (this.inflight.has(txidKey)) return this.inflight.get(txidKey)!;
+    const p = (async () => create())();
+    this.inflight.set(txidKey, p);
+    return p.finally(() => this.inflight.delete(txidKey));
+  }
+
+  async broadcastAndConfirm(txHex: string, options: BroadcastOptions = {}): Promise<{ txid: string; confirmations: number }>
+  {
+    const txid = await this.broadcastIdempotent(txHex, () => this.broadcaster(txHex));
+    const interval = Math.max(100, options.pollIntervalMs ?? 500);
+    const maxAttempts = Math.max(1, options.maxAttempts ?? 20);
+    let attempts = 0;
+    let last: TransactionStatus = { confirmed: false };
+    while (attempts < maxAttempts) {
+      last = await this.statusProvider(txid);
+      if (last.confirmed) {
+        return { txid, confirmations: last.confirmations ?? 1 };
+      }
+      await new Promise(r => setTimeout(r, interval));
+      attempts++;
+    }
+    return { txid, confirmations: last.confirmations ?? 0 };
+  }
+}
+

package/src/bitcoin/OrdinalsClient.ts

@@ -0,0 +1,120 @@
+import { OrdinalsInscription, BitcoinTransaction } from '../types';
+import { decode as decodeCbor } from '../utils/cbor';
+import { hexToBytes } from '../utils/encoding';
+
+export class OrdinalsClient {
+  constructor(
+    private rpcUrl: string,
+    private network: 'mainnet' | 'regtest' | 'signet'
+  ) {}
+
+  async getInscriptionById(id: string): Promise<OrdinalsInscription | null> {
+    if (!id) return null;
+    return this.resolveInscription(id);
+  }
+
+  async getInscriptionsBySatoshi(satoshi: string): Promise<OrdinalsInscription[]> {
+    const info = await this.getSatInfo(satoshi);
+    if (!info.inscription_ids.length) return [];
+    const inscriptions = await Promise.all(info.inscription_ids.map(id => this.resolveInscription(id)));
+    return inscriptions.filter((x): x is OrdinalsInscription => x !== null);
+  }
+
+  broadcastTransaction(tx: BitcoinTransaction): Promise<string> {
+    return Promise.resolve(tx.txid || 'txid');
+  }
+
+  getTransactionStatus(_txid: string): Promise<{
+    confirmed: boolean;
+    blockHeight?: number;
+    confirmations?: number;
+  }> {
+    return Promise.resolve({ confirmed: false });
+  }
+
+  estimateFee(blocks: number = 1): Promise<number> {
+    return Promise.resolve(Math.max(1, blocks) * 10);
+  }
+
+  // Added provider-like helper methods commonly expected by higher-level resolvers
+  // Minimal placeholder implementations suitable for unit testing
+
+  async getSatInfo(satoshi: string): Promise<{ inscription_ids: string[] }> {
+    const data = await this.fetchJson<any>(`/sat/${satoshi}`);
+    if (!data) return { inscription_ids: [] };
+    // Support both {inscription_ids: []} and {data: {inscription_ids: []}} shapes via fetchJson
+    const inscriptionIds = Array.isArray(data.inscription_ids) ? data.inscription_ids : [];
+    return { inscription_ids: inscriptionIds };
+  }
+
+  async resolveInscription(identifier: string): Promise<OrdinalsInscription | null> {
+    if (!identifier) return null;
+    const info = await this.fetchJson<any>(`/inscription/${identifier}`);
+    if (!info) return null;
+
+    // Fetch content bytes
+    const contentUrl = info.content_url || `${this.rpcUrl}/content/${identifier}`;
+    const contentRes = await fetch(String(contentUrl));
+    if (!contentRes.ok) throw new Error(`Failed to fetch inscription content: ${contentRes.status}`);
+    const contentArrayBuf = await contentRes.arrayBuffer();
+    const content = Buffer.from(new Uint8Array(contentArrayBuf));
+
+    // owner_output may be 'txid:vout'
+    let txid = 'unknown';
+    let vout = 0;
+    if (typeof info.owner_output === 'string' && info.owner_output.includes(':')) {
+      const [tid, v] = info.owner_output.split(':');
+      txid = tid;
+      vout = Number(v) || 0;
+    }
+
+    // sat number provided as number or string
+    const satoshi = String(info.sat ?? '');
+
+    const inscription: OrdinalsInscription = {
+      satoshi,
+      inscriptionId: info.inscription_id || identifier,
+      content,
+      contentType: info.content_type || 'application/octet-stream',
+      txid,
+      vout,
+      blockHeight: info.block_height
+    };
+
+    return inscription;
+  }
+
+  async getMetadata(inscriptionId: string): Promise<Record<string, unknown> | null> {
+    if (!inscriptionId) return null;
+    const base = this.rpcUrl.replace(/\/$/, '');
+    const res = await fetch(`${base}/r/metadata/${inscriptionId}`, { headers: { 'Accept': 'application/json' } });
+    if (!res.ok) {
+      return null;
+    }
+    let text = (await res.text()).trim();
+    if (text.startsWith('"') && text.endsWith('"')) {
+      try {
+        text = JSON.parse(text);
+      } catch (_) {
+        // Keep original text if parsing fails
+      }
+    }
+    try {
+      const bytes = hexToBytes(text);
+      return decodeCbor<Record<string, unknown>>(bytes);
+    } catch (_) {
+      return null;
+    }
+  }
+
+  private async fetchJson<T>(path: string): Promise<T | null> {
+    const url = `${this.rpcUrl.replace(/\/$/, '')}${path}`;
+    const res = await fetch(url, { headers: { 'Accept': 'application/json' } });
+    if (!res.ok) return null;
+    const body: any = await res.json();
+    // Accept { data: T } or T
+    return (body && typeof body === 'object' && 'data' in body) ? body.data : body;
+  }
+}
+
+

package/src/bitcoin/PSBTBuilder.ts

@@ -0,0 +1,106 @@
+import type { Utxo } from '../types/bitcoin';
+
+export interface PsbtOutput {
+  address: string;
+  value: number;
+}
+
+export interface BuildPsbtParams {
+  utxos: Utxo[];
+  outputs: PsbtOutput[];
+  changeAddress: string;
+  feeRate: number; // sat/vB
+  network: 'mainnet' | 'testnet' | 'regtest' | 'signet';
+  dustLimit?: number;
+}
+
+export interface BuildPsbtResult {
+  psbtBase64: string; // opaque PSBT representation (base64-encoded payload)
+  selectedUtxos: Utxo[];
+  fee: number;
+  changeOutput?: PsbtOutput;
+}
+
+function estimateVBytes(inputs: number, outputs: number): number {
+  const overhead = 10; // base tx overhead
+  const inSize = 68;   // rough P2WPKH/any-segwit input size
+  const outSize = 31;  // P2WPKH output size
+  return Math.ceil(overhead + inputs * inSize + outputs * outSize);
+}
+
+export class PSBTBuilder {
+  constructor(private readonly dustLimit = 546) {}
+
+  build(params: BuildPsbtParams): BuildPsbtResult {
+    const { utxos, outputs, changeAddress, feeRate } = params;
+    if (!utxos || utxos.length === 0) throw new Error('No UTXOs');
+    if (!outputs || outputs.length === 0) throw new Error('No outputs');
+
+    // Sort UTXOs ascending by value for simple greedy selection
+    const sorted = [...utxos].sort((a, b) => a.value - b.value);
+
+    // Start with smallest set to cover target + estimated fee; refine iteratively
+    const targetValue = outputs.reduce((s, o) => s + o.value, 0);
+    let selected: Utxo[] = [];
+    let total = 0;
+
+    const pick = () => {
+      selected = [];
+      total = 0;
+      for (const u of sorted) {
+        selected.push(u);
+        total += u.value;
+        const vbytes = estimateVBytes(selected.length, outputs.length + 1); // +1 potential change
+        const fee = Math.ceil(vbytes * feeRate);
+        if (total >= targetValue + fee) break;
+      }
+      if (total < targetValue) throw new Error('Insufficient funds');
+    };
+
+    pick();
+    const initialVBytes = estimateVBytes(selected.length, outputs.length + 1);
+    let fee = Math.ceil(initialVBytes * feeRate);
+    let change = total - targetValue - fee;
+    let includeChange = change >= this.dustLimit;
+
+    // Re-estimate once we know whether change is included
+    const finalVBytes = estimateVBytes(selected.length, outputs.length + (includeChange ? 1 : 0));
+    fee = Math.ceil(finalVBytes * feeRate);
+    change = total - targetValue - fee;
+    includeChange = change >= this.dustLimit;
+
+    let changeOutput: PsbtOutput | undefined;
+    if (!includeChange) {
+      // Add dust to fee
+      fee = total - targetValue;
+    } else {
+      changeOutput = { address: changeAddress, value: change };
+    }
+
+    // Construct a minimal PSBT-like payload for dry-run/testing. We intentionally avoid
+    // bringing heavy bitcoin libraries here; this builder focuses on deterministic
+    // selection, fee estimation, and change handling.
+    const payload = {
+      version: 0,
+      inputs: selected.map(u => ({ txid: u.txid, vout: u.vout })),
+      outputs: [
+        ...outputs.map(o => ({ address: o.address, value: o.value })),
+        ...(changeOutput ? [changeOutput] : [])
+      ],
+      fee
+    };
+    // Base64 encode via Node when available; fallback to btoa if present
+    const json = JSON.stringify(payload);
+    let psbtBase64: string;
+    try {
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-unsafe-member-access
+      const B: any = (global as any).Buffer;
+      psbtBase64 = B ? B.from(json, 'utf8').toString('base64') : (global as any).btoa(json);
+    } catch {
+      psbtBase64 = `psbt:${json}`;
+    }
+
+    return { psbtBase64, selectedUtxos: selected, fee, changeOutput };
+  }
+}
+

package/src/bitcoin/fee-calculation.ts

@@ -0,0 +1,38 @@
+/**
+ * Bitcoin Transaction Fee Calculation
+ * 
+ * Utilities for calculating transaction fees based on size and fee rate.
+ * Ported from legacy ordinalsplus transaction infrastructure.
+ */
+
+// Define minimum relay fee rate (sats/vB)
+// Increased slightly from Bitcoin Core default of 1.0 for safety
+const MIN_RELAY_FEE_RATE = 1.1; 
+
+/**
+ * Calculate transaction fee based on vbytes and fee rate, ensuring minimum relay fee.
+ * 
+ * @param vbytes - The virtual size of the transaction.
+ * @param feeRate - The desired fee rate in sats/vbyte.
+ * @returns The calculated fee in satoshis (bigint).
+ */
+export const calculateFee = (vbytes: number, feeRate: number): bigint => {
+    // Ensure inputs are valid numbers
+    if (isNaN(vbytes) || vbytes <= 0 || isNaN(feeRate) || feeRate <= 0) {
+        console.warn(`[calculateFee] Invalid input: vbytes=${vbytes}, feeRate=${feeRate}. Returning 0.`);
+        return 0n;
+    }
+
+    // Calculate fee based on the desired fee rate
+    const calculatedFee = Math.ceil(vbytes * feeRate);
+    
+    // Calculate the minimum fee required for relay
+    const minimumFee = Math.ceil(vbytes * MIN_RELAY_FEE_RATE);
+    
+    // Return the higher of the calculated fee or minimum relay fee
+    // Ensure the result is a positive integer (minimum 1 sat)
+    const finalFee = BigInt(Math.max(1, calculatedFee, minimumFee)); 
+    
+    return finalFee;
+};
+

package/src/bitcoin/providers/OrdNodeProvider.ts

@@ -0,0 +1,92 @@
+import type { ResourceProvider, LinkedResource, ResourceInfo, Inscription, ResourceCrawlOptions } from './types';
+
+export interface OrdNodeProviderOptions {
+  nodeUrl: string;
+  timeout?: number;
+  network?: 'mainnet' | 'testnet' | 'signet';
+}
+
+export class OrdNodeProvider implements ResourceProvider {
+  private readonly nodeUrl: string;
+  private readonly timeout: number;
+  private readonly network: 'mainnet' | 'testnet' | 'signet';
+
+  constructor(options: OrdNodeProviderOptions) {
+    this.nodeUrl = options.nodeUrl;
+    this.timeout = options.timeout || 5000;
+    this.network = options.network || 'mainnet';
+  }
+
+  async resolve(resourceId: string): Promise<LinkedResource> {
+    return {
+      id: resourceId,
+      type: 'Unknown',
+      contentType: 'application/octet-stream',
+      content_url: `${this.nodeUrl}/content/${resourceId}`
+    };
+  }
+
+  async resolveInscription(inscriptionId: string): Promise<Inscription> {
+    return {
+      id: inscriptionId,
+      sat: 0,
+      content_type: 'text/plain',
+      content_url: `${this.nodeUrl}/content/${inscriptionId}`
+    };
+  }
+
+  async resolveInfo(resourceId: string): Promise<ResourceInfo> {
+    return {
+      id: resourceId,
+      type: 'Unknown',
+      contentType: 'application/octet-stream',
+      createdAt: new Date().toISOString(),
+      updatedAt: new Date().toISOString(),
+      content_url: `${this.nodeUrl}/content/${resourceId}`
+    };
+  }
+
+  async resolveCollection(did: string, _options: { type?: string; limit?: number; offset?: number } = {}): Promise<LinkedResource[]> {
+    return [];
+  }
+
+  async getSatInfo(_satNumber: string): Promise<{ inscription_ids: string[] }> {
+    return { inscription_ids: [] };
+  }
+
+  async getMetadata(_inscriptionId: string): Promise<any> {
+    return null;
+  }
+
+  async *getAllResources(_options: ResourceCrawlOptions = {}): AsyncGenerator<LinkedResource[]> {
+    // no-op generator yields nothing
+    return;
+  }
+
+  async *getAllResourcesChronological(_options: ResourceCrawlOptions = {}): AsyncGenerator<LinkedResource[]> {
+    // no-op generator yields nothing
+    return;
+  }
+
+  async getInscriptionLocationsByAddress(_address: string): Promise<{ id: string; location: string }[]> {
+    return [];
+  }
+
+  async getInscriptionByNumber(_inscriptionNumber: number): Promise<Inscription> {
+    return {
+      id: '0',
+      sat: 0,
+      content_type: 'text/plain',
+      content_url: `${this.nodeUrl}/content/0`
+    };
+  }
+
+  async getAddressOutputs(_address: string): Promise<string[]> {
+    return [];
+  }
+
+  async getOutputDetails(_outpoint: string): Promise<{ value: number; script_pubkey: string; spent: boolean; inscriptions: string[] }> {
+    return { value: 0, script_pubkey: '', spent: false, inscriptions: [] };
+  }
+}
+

package/src/bitcoin/providers/OrdinalsProvider.ts

@@ -0,0 +1,56 @@
+import { OrdinalsClient } from '../OrdinalsClient';
+import { withRetry } from '../../utils/retry';
+
+export interface OrdinalsProvider {
+  getSatInfo(satNumber: string): Promise<{ inscription_ids: string[] }>;
+  resolveInscription(inscriptionId: string): Promise<{ id: string; sat: number; content_type: string; content_url: string }>;
+  getMetadata(inscriptionId: string): Promise<any>;
+  estimateFee(blocks?: number): Promise<number>;
+}
+
+export class OrdinalsClientProvider implements OrdinalsProvider {
+  constructor(private client: OrdinalsClient, private options?: { retries?: number; baseUrl?: string }) {}
+
+  async getSatInfo(satNumber: string): Promise<{ inscription_ids: string[] }> {
+    return withRetry(() => this.client.getSatInfo(satNumber), {
+      maxRetries: this.options?.retries ?? 2,
+      isRetriable: () => true
+    });
+  }
+
+  async resolveInscription(inscriptionId: string): Promise<{ id: string; sat: number; content_type: string; content_url: string }> {
+    return withRetry(async () => {
+      const res = await this.client.getInscriptionById(inscriptionId);
+      if (!res) throw new Error('Inscription not found');
+      if (!res.satoshi) throw new Error('Inscription missing satoshi');
+      const sat = Number(String(res.satoshi));
+      if (Number.isNaN(sat)) throw new Error('Invalid satoshi value');
+      if (!res.contentType) throw new Error('Inscription missing contentType');
+      const base = (this.options?.baseUrl || '').replace(/\/$/, '');
+      if (!base) throw new Error('baseUrl is required to construct content_url');
+      const id = res.inscriptionId;
+      const content_url = `${base}/content/${id}`;
+      return {
+        id,
+        sat,
+        content_type: res.contentType,
+        content_url
+      };
+    }, { maxRetries: this.options?.retries ?? 2, isRetriable: () => true });
+  }
+
+  async getMetadata(inscriptionId: string): Promise<any> {
+    return withRetry(() => this.client.getMetadata(inscriptionId), {
+      maxRetries: this.options?.retries ?? 2,
+      isRetriable: () => true
+    });
+  }
+
+  async estimateFee(blocks?: number): Promise<number> {
+    return withRetry(() => this.client.estimateFee(blocks), {
+      maxRetries: this.options?.retries ?? 2,
+      isRetriable: () => true
+    });
+  }
+}
+

package/src/bitcoin/providers/types.ts

@@ -0,0 +1,59 @@
+export interface LinkedResource {
+  id: string;
+  type: string;
+  contentType: string;
+  content_url: string;
+}
+
+export interface Inscription {
+  id: string;
+  sat: number;
+  content_type: string;
+  content_url: string;
+  number?: number;
+  height?: number;
+  timestamp?: number;
+}
+
+export interface ResourceInfo {
+  id: string;
+  type: string;
+  contentType: string;
+  createdAt?: string;
+  updatedAt?: string;
+  content_url: string;
+}
+
+export interface ResourceProvider {
+  resolve(resourceId: string): Promise<LinkedResource>;
+  resolveInscription(inscriptionId: string): Promise<Inscription>;
+  resolveInfo(resourceId: string): Promise<ResourceInfo>;
+  resolveCollection(did: string, options: { type?: string; limit?: number; offset?: number }): Promise<LinkedResource[]>;
+  getSatInfo(satNumber: string): Promise<{ inscription_ids: string[] }>;
+  getMetadata(inscriptionId: string): Promise<any>;
+  getAllResources(options?: ResourceCrawlOptions): AsyncGenerator<LinkedResource[]>;
+  getAllResourcesChronological(options?: ResourceCrawlOptions): AsyncGenerator<LinkedResource[]>;
+  getInscriptionLocationsByAddress(address: string): Promise<InscriptionRefWithLocation[]>;
+  getInscriptionByNumber(inscriptionNumber: number): Promise<Inscription>;
+  getAddressOutputs(address: string): Promise<string[]>;
+  getOutputDetails(outpoint: string): Promise<{ value: number; script_pubkey: string; spent: boolean; inscriptions: string[] }>;
+}
+
+export interface ResourceCrawlOptions {
+  batchSize?: number;
+  startFrom?: number;
+  maxResources?: number;
+  filter?: (resource: LinkedResource) => boolean;
+}
+
+export interface ResourceBatch {
+  resources: LinkedResource[];
+  nextCursor?: number;
+  hasMore: boolean;
+}
+
+export interface InscriptionRefWithLocation {
+  id: string;
+  location: string;
+}
+