implement StampParserService: Classic Stamps + SRC-721 via OLGA P2WSH

New parser for the Bitcoin Stamps ecosystem beyond SRC-20. Detects:
- Classic Stamps (NFT images: PNG/GIF/SVG/WebP/HTML via P2WSH)
- SRC-721 (composable layered NFTs, JSON via P2WSH)
- SRC-101 (domain names, JSON via P2WSH) -- type ready, needs test tx

OLGA P2WSH format (block 833,000+): data encoded in v0_p2wsh output
scriptpubkeys. Each output = 0020 + 32 raw bytes. Concatenate all
(skip idx 0), strip trailing zeros, 2-byte BE length prefix, raw data.

Two flavors found on mainnet:
- Counterparty-issued (Classic Stamps): no stamp: prefix, raw file bytes
- Direct Bitcoin (SRC-20/101 OLGA): stamp: prefix before content
Both handled by extractOlgaData().

MIME detection via magic bytes (PNG/GIF/WebP/JPEG/BMP) and text
pattern matching (SVG/HTML/JSON). Based on stampchain indexer source
(enhanced_mime_detection.py).

Wired into: DigitalArtifactsParserService, DigitalArtifactAnalyserService,
flags (ordpool_stamp, ordpool_src721, ordpool_src101), index.ts exports.

Existing SRC-20 parser unchanged -- still handles ARC4 multisig path.

Author: hans-crypto

src/digital-artifact-analyser.service.ts

@@ -438,6 +438,18 @@ export class DigitalArtifactAnalyserService {
         flags |= OrdpoolTransactionFlags.ordpool_counterparty;
         break;
 
+      case DigitalArtifactType.Stamp:
+        flags |= OrdpoolTransactionFlags.ordpool_stamp;
+        break;
+
+      case DigitalArtifactType.Src721:
+        flags |= OrdpoolTransactionFlags.ordpool_src721;
+        break;
+
+      case DigitalArtifactType.Src101:
+        flags |= OrdpoolTransactionFlags.ordpool_src101;
+        break;
+
       case DigitalArtifactType.Inscription:
         const inscription = artifact as ParsedInscription;
         flags |= OrdpoolTransactionFlags.ordpool_inscription;
@@ -551,7 +563,10 @@ export class DigitalArtifactAnalyserService {
       isFlagSetOnTransaction(tx, OrdpoolTransactionFlags.ordpool_counterparty) ||
       isFlagSetOnTransaction(tx, OrdpoolTransactionFlags.ordpool_rune) ||
       isFlagSetOnTransaction(tx, OrdpoolTransactionFlags.ordpool_brc20) ||
-      isFlagSetOnTransaction(tx, OrdpoolTransactionFlags.ordpool_src20);
+      isFlagSetOnTransaction(tx, OrdpoolTransactionFlags.ordpool_src20) ||
+      isFlagSetOnTransaction(tx, OrdpoolTransactionFlags.ordpool_stamp) ||
+      isFlagSetOnTransaction(tx, OrdpoolTransactionFlags.ordpool_src721) ||
+      isFlagSetOnTransaction(tx, OrdpoolTransactionFlags.ordpool_src101);
   }
 
 

src/digital-artifacts-parser.service.ts

@@ -5,6 +5,7 @@ import { InscriptionParserService } from './inscription/inscription-parser.servi
 import { LabitbuParserService } from './labitbu/labitbu-parser.service';
 import { RuneParserService } from './rune/rune-parser.service';
 import { Src20ParserService } from './src20/src20-parser.service';
+import { StampParserService } from './stamp/stamp-parser.service';
 import { DigitalArtifact } from './types/digital-artifact';
 import { OnParseError } from './types/parser-options';
 import { TransactionSimple } from './types/transaction-simple';
@@ -62,6 +63,11 @@ export class DigitalArtifactsParserService {
       artifacts.push(parsedSrc20);
     }
 
+    const parsedStamp = StampParserService.parse(transaction, onError);
+    if (parsedStamp) {
+      artifacts.push(parsedStamp);
+    }
+
     return artifacts;
   }
 }

src/index.ts

@@ -30,6 +30,8 @@ export * from './rune/rune-parser.service.helper';
 export * from './rune/rune-parser.service';
 export * from './src20/src20-parser.service.helper';
 export * from './src20/src20-parser.service';
+export * from './stamp/stamp-parser.service.helper';
+export * from './stamp/stamp-parser.service';
 export * from './types/digital-artifact';
 export * from './types/mempool';
 export * from './types/ordpool-stats';
@@ -42,6 +44,9 @@ export * from './types/parsed-labitbu';
 export * from './types/parsed-inscription';
 export * from './types/parsed-runestone';
 export * from './types/parsed-src20';
+export * from './types/parsed-stamp';
+export * from './types/parsed-src721';
+export * from './types/parsed-src101';
 export * from './types/parser-options';
 export * from './types/bitcoin-rpc';
 export * from './types/transaction-simple';

src/stamp/stamp-parser.service.helper.ts

@@ -0,0 +1,148 @@
+import { bigEndianBytesToNumber, hexToBytes, concatUint8Arrays } from '../lib/conversions';
+
+/**
+ * Extracts raw file data from OLGA P2WSH outputs.
+ *
+ * OLGA (Octet Linked Graphics & Artifacts) encodes data directly in P2WSH
+ * output scriptpubkeys. Each output is 34 bytes: 0x00 0x20 + 32 bytes of data.
+ * The 32-byte "hash" is NOT a real hash -- it's raw file data.
+ *
+ * Format:
+ * 1. Collect all v0_p2wsh scriptpubkeys (skip index 0 -- reserved for destination)
+ * 2. Strip the 0x0020 prefix from each, giving 32 raw bytes per output
+ * 3. Concatenate, strip trailing zeros
+ * 4. First 2 bytes = big-endian file length
+ * 5. Remaining bytes = raw file data
+ *
+ * Two flavors exist on mainnet:
+ * a) Counterparty-issued stamps (Classic Stamps, SRC-721 via CP):
+ *    Raw file data directly (PNG, GIF, SVG, JSON). No stamp: prefix.
+ * b) Direct Bitcoin stamps (SRC-20 OLGA, SRC-101 OLGA):
+ *    Data starts with "stamp:" prefix, followed by the file content.
+ *
+ * Source: stampchain-io/btc_stamps indexer/src/index_core/transaction_utils.py
+ * Active since block 833,000 (CP_P2WSH_FEAT_BLOCK_START)
+ */
+export function extractOlgaData(
+  vout: { scriptpubkey: string, scriptpubkey_type: string }[]
+): Uint8Array | null {
+
+  // Collect P2WSH outputs at index > 0 (index 0 is reserved for destination/value)
+  // P2WSH scriptpubkey format: 0020 + 32 bytes = 68 hex chars total
+  const chunks: Uint8Array[] = [];
+  for (let i = 1; i < vout.length; i++) {
+    const output = vout[i];
+    if (output.scriptpubkey_type !== 'v0_p2wsh') {
+      continue;
+    }
+    // Must be exactly 68 hex chars (34 bytes: 0x00 0x20 + 32 data bytes)
+    if (output.scriptpubkey.length !== 68) {
+      continue;
+    }
+    // Skip the 0020 prefix (4 hex chars), extract 32 raw bytes
+    chunks.push(hexToBytes(output.scriptpubkey.substring(4)));
+  }
+
+  if (chunks.length === 0) {
+    return null;
+  }
+
+  const allBytes = concatUint8Arrays(chunks);
+
+  // Strip trailing zeros (padding)
+  let end = allBytes.length;
+  while (end > 0 && allBytes[end - 1] === 0) {
+    end--;
+  }
+  if (end < 2) {
+    return null;
+  }
+  const trimmed = allBytes.subarray(0, end);
+
+  // First 2 bytes = big-endian file length
+  const fileLength = bigEndianBytesToNumber(trimmed.subarray(0, 2));
+  if (fileLength === 0 || fileLength > trimmed.length - 2) {
+    return null;
+  }
+
+  // Extract the file data (skip 2-byte length prefix)
+  const fileData = trimmed.subarray(2, 2 + fileLength);
+
+  // Check for "stamp:" prefix (0x7374616d703a) -- used by SRC-20/SRC-101 OLGA
+  // Counterparty-issued OLGA stamps do NOT have this prefix.
+  const STAMP_PREFIX = new Uint8Array([0x73, 0x74, 0x61, 0x6d, 0x70, 0x3a]); // "stamp:"
+  if (fileData.length > STAMP_PREFIX.length &&
+      fileData[0] === 0x73 && fileData[1] === 0x74 && fileData[2] === 0x61 &&
+      fileData[3] === 0x6d && fileData[4] === 0x70 && fileData[5] === 0x3a) {
+    // Strip the stamp: prefix
+    return fileData.subarray(STAMP_PREFIX.length);
+  }
+
+  // No stamp: prefix -- return raw file data (Counterparty-issued OLGA)
+  return fileData;
+}
+
+/**
+ * Detects the MIME type from raw file bytes by checking magic numbers.
+ *
+ * This is the same approach used by the stampchain indexer
+ * (enhanced_mime_detection.py) but simplified for our use case.
+ */
+export function detectMimeType(data: Uint8Array): string | null {
+  if (data.length < 4) {
+    return null;
+  }
+
+  // PNG: 89 50 4e 47 0d 0a 1a 0a
+  if (data[0] === 0x89 && data[1] === 0x50 && data[2] === 0x4e && data[3] === 0x47) {
+    return 'image/png';
+  }
+
+  // GIF87a or GIF89a: 47 49 46 38 (37|39) 61
+  if (data[0] === 0x47 && data[1] === 0x49 && data[2] === 0x46 && data[3] === 0x38) {
+    return 'image/gif';
+  }
+
+  // WebP: 52 49 46 46 ... 57 45 42 50 (RIFF....WEBP)
+  if (data[0] === 0x52 && data[1] === 0x49 && data[2] === 0x46 && data[3] === 0x46 &&
+      data.length >= 12 && data[8] === 0x57 && data[9] === 0x45 && data[10] === 0x42 && data[11] === 0x50) {
+    return 'image/webp';
+  }
+
+  // JPEG: ff d8 ff
+  if (data[0] === 0xff && data[1] === 0xd8 && data[2] === 0xff) {
+    return 'image/jpeg';
+  }
+
+  // BMP: 42 4d (BM)
+  if (data[0] === 0x42 && data[1] === 0x4d) {
+    return 'image/bmp';
+  }
+
+  // Text-based formats: check as UTF-8
+  try {
+    const head = new TextDecoder().decode(data.subarray(0, Math.min(data.length, 256)));
+    const trimmed = head.trimStart();
+
+    // SVG: starts with '<svg' or '<?xml'
+    if (trimmed.startsWith('<svg') || trimmed.startsWith('<?xml')) {
+      return 'image/svg+xml';
+    }
+
+    // HTML: starts with '<!doctype html', '<html', '<head', '<body'
+    const lower = trimmed.toLowerCase();
+    if (lower.startsWith('<!doctype html') || lower.startsWith('<html') ||
+        lower.startsWith('<head') || lower.startsWith('<body')) {
+      return 'text/html';
+    }
+
+    // JSON: starts with '{' or '['
+    if (trimmed.startsWith('{') || trimmed.startsWith('[')) {
+      return 'application/json';
+    }
+  } catch {
+    // not valid UTF-8
+  }
+
+  return null;
+}

src/stamp/stamp-parser.service.spec.ts

@@ -0,0 +1,93 @@
+import { readBinaryFileAsUint8Array, readTransaction } from '../../testdata/test.helper';
+import { DigitalArtifactType } from '../types/digital-artifact';
+import { ParsedStamp } from '../types/parsed-stamp';
+import { ParsedSrc721 } from '../types/parsed-src721';
+import { StampParserService } from './stamp-parser.service';
+
+// =============================================================================
+// Classic Stamp -- OLGA P2WSH encoding (Counterparty-issued, no stamp: prefix)
+// =============================================================================
+
+// Real mainnet Classic Stamp: PNG image, 1393 bytes, block 933,540
+// Stamp #1383565 -- pixel art encoded via OLGA P2WSH (44 outputs)
+// Counterparty issuance of CPID A197900000000002026
+const CLASSIC_STAMP_PNG_TXID = '516e62beeffb26fb37f8e95e809274e5bbde76eb75a28357f6bbcd4eedbfe8ca';
+
+// =============================================================================
+// SRC-721 -- OLGA P2WSH encoding (JSON payload)
+// =============================================================================
+
+// Real mainnet SRC-721 mint: {"p":"src-721","op":"mint","c":"A1473703777372088053","ts":[1,4,8,4,5,4,7,0,6,6]}
+// Stamp #1383566, block 933,541, SVG composable NFT
+const SRC721_TXID = 'b74313d300902c0cdf88dc101fb8f4c9ab7ad89c978edd30ca4ee7987cccdedd';
+
+describe('StampParserService', () => {
+
+  // ===========================================================================
+  // Classic Stamp -- OLGA P2WSH with PNG image
+  // ===========================================================================
+
+  describe('Classic Stamp (OLGA P2WSH)', () => {
+    it('should extract a PNG image from P2WSH outputs', () => {
+      const txn = readTransaction(CLASSIC_STAMP_PNG_TXID);
+      const result = StampParserService.parse(txn)!;
+
+      expect(result).not.toBeNull();
+      expect(result.type).toBe(DigitalArtifactType.Stamp);
+      expect(result.transactionId).toBe(CLASSIC_STAMP_PNG_TXID);
+      expect(result.uniqueId).toBe(`${DigitalArtifactType.Stamp}-${CLASSIC_STAMP_PNG_TXID}`);
+
+      const stamp = result as ParsedStamp;
+      expect(stamp.contentType).toBe('image/png');
+
+      // Verify image data
+      const raw = stamp.getDataRaw();
+      expect(raw.length).toBe(1393);
+
+      // PNG magic header: 89 50 4e 47 0d 0a 1a 0a
+      expect(raw[0]).toBe(0x89);
+      expect(raw[1]).toBe(0x50); // P
+      expect(raw[2]).toBe(0x4e); // N
+      expect(raw[3]).toBe(0x47); // G
+
+      // Compare byte-for-byte against the reference image
+      const referenceImage = readBinaryFileAsUint8Array('stamp_1383565_image.png');
+      expect(raw).toEqual(referenceImage);
+
+      // Verify data URI
+      const dataUri = stamp.getDataUri();
+      expect(dataUri.startsWith('data:image/png;base64,')).toBe(true);
+    });
+
+    it('should return null for a transaction without P2WSH outputs', () => {
+      // SRC-20 test tx uses multisig, not P2WSH
+      const txn = readTransaction('50aeb77245a9483a5b077e4e7506c331dc2f628c22046e7d2b4c6ad6c6236ae1');
+      expect(StampParserService.parse(txn)).toBeNull();
+    });
+  });
+
+  // ===========================================================================
+  // SRC-721 -- OLGA P2WSH with JSON payload
+  // ===========================================================================
+
+  describe('SRC-721 (OLGA P2WSH)', () => {
+    it('should parse SRC-721 mint from P2WSH outputs', () => {
+      const txn = readTransaction(SRC721_TXID);
+      const result = StampParserService.parse(txn)!;
+
+      expect(result).not.toBeNull();
+      expect(result.type).toBe(DigitalArtifactType.Src721);
+      expect(result.transactionId).toBe(SRC721_TXID);
+
+      const src721 = result as ParsedSrc721;
+      const content = src721.getContent();
+
+      // Verify exact JSON content
+      const parsed = JSON.parse(content);
+      expect(parsed.p).toBe('src-721');
+      expect(parsed.op).toBe('mint');
+      expect(parsed.c).toBe('A1473703777372088053');
+      expect(parsed.ts).toEqual([1, 4, 8, 4, 5, 4, 7, 0, 6, 6]);
+    });
+  });
+});