Implement V12 support for TypeScript.

Author: ro-tex

typescript/README.md

@@ -27,7 +27,7 @@ TypeScript SDK for accessing Chainlink Data Streams with real-time streaming and
 - **Real-time streaming** via WebSocket connections
 - **High Availability mode** with multiple connections and automatic failover
 - **Historical data access** via REST API
-- **Automatic report decoding** for all supported formats (V2, V3, V4, V5, V6, V7, V8, V9, V10, V11, V13)
+- **Automatic report decoding** for all supported formats (V2, V3, V4, V5, V6, V7, V8, V9, V10, V11, V12, V13)
 - **Metrics** for monitoring and observability
 - **Type-safe** with full TypeScript support
 - **Event-driven architecture** for complete developer control
@@ -48,12 +48,14 @@ npm install @chainlink/data-streams-sdk
 **Set your credentials:**
 
 Option 1 - Environment variables:
+
 ```bash
 export API_KEY="your_api_key_here"
 export USER_SECRET="your_user_secret_here"
 ```
 
 Option 2 - `.env` file:
+
 ```bash
 # Create .env file from template
 cp .env.example .env
@@ -64,6 +66,7 @@ USER_SECRET="your_user_secret_here"
 ```
 
 **Basic streaming:**
+
 ```typescript
 import { createClient, LogLevel } from '@chainlink/data-streams-sdk';
 
@@ -104,17 +107,17 @@ interface Config {
   userSecret: string;              // User secret for authentication
   endpoint: string;                // REST API URL
   wsEndpoint: string;              // WebSocket URL
-  
+
   // Optional - Request & Retry
   timeout?: number;                // Request timeout (default: 30000ms)
   retryAttempts?: number;          // Retry attempts (default: 3)
   retryDelay?: number;             // Retry delay (default: 1000ms)
-  
+
   // Optional - High Availability
   haMode?: boolean;                // Enable HA mode (default: false)
   haConnectionTimeout?: number;    // HA connection timeout (default: 10000ms)
   connectionStatusCallback?: (isConnected: boolean, host: string, origin: string) => void;
-  
+
   // Optional - Logging
   logging?: LoggingConfig;         // See Logging Configuration section
 }
@@ -148,6 +151,7 @@ const haClient = createClient({
 ## Examples
 
 **Quick Commands:**
+
 ```bash
 # Real-time streaming
 npx ts-node examples/stream-reports.ts 0x000359843a543ee2fe414dc14c7e7920ef10f4372990b79d6361cdc0dd1ba782
@@ -166,7 +170,7 @@ npx ts-node examples/list-feeds.ts
 See [`examples/README.md`](./examples/README.md) for detailed usage instructions, setup, and all available examples including:
 
 - **Streaming:** Basic streaming, HA mode, metrics monitoring
-- **REST API:** Latest reports, historical data, bulk operations, feed management  
+- **REST API:** Latest reports, historical data, bulk operations, feed management
 - **Configuration:** Logging setup, debugging, monitoring integration
 
 ## API Reference
@@ -191,7 +195,6 @@ await stream.close();
 const metrics = stream.getMetrics();
 ```
 
-
 ### Stream Options
 
 ```typescript
@@ -235,8 +238,9 @@ const decoded = decodeReport(report.fullReport, report.feedID);
 ### Schema Auto-Detection
 
 The SDK automatically detects and decodes all report versions based on Feed ID patterns:
+
 - **V2**: Feed IDs starting with `0x0002`
-- **V3**: Feed IDs starting with `0x0003` (Crypto Streams)  
+- **V3**: Feed IDs starting with `0x0003` (Crypto Streams)
 - **V4**: Feed IDs starting with `0x0004` (Real-World Assets)
 - **V5**: Feed IDs starting with `0x0005`
 - **V6**: Feed IDs starting with `0x0006` (Multiple Price Values)
@@ -245,14 +249,16 @@ The SDK automatically detects and decodes all report versions based on Feed ID p
 - **V9**: Feed IDs starting with `0x0009` (NAV Fund Data)
 - **V10**: Feed IDs starting with `0x000a` (Tokenized Equity)
 - **V11**: Feed IDs starting with `0x000b` (Deutsche Boerse)
+- **V12**: Feed IDs starting with `0x000c` (Nav Fund Data + Next)
 - **V13**: Feed IDs starting with `0x000d` (Best Bid/Ask)
 
 ### Common Fields
 
 All reports include standard metadata:
+
 ```typescript
 interface BaseFields {
-  version: "V2" | "V3" | "V4" | "V5" | "V6" | "V7" | "V8" | "V9" | "V10" | "V11" | "V13";
+  version: "V2" | "V3" | "V4" | "V5" | "V6" | "V7" | "V8" | "V9" | "V10" | "V11" | "V12" | "V13";
   nativeFee: bigint;
   linkFee: bigint;
   expiresAt: number;
@@ -265,7 +271,7 @@ interface BaseFields {
 ### Schema-Specific Fields
 
 - **V2/V3/V4**: `price: bigint` - Standard price data
-- **V3**: `bid: bigint, ask: bigint` - Crypto bid/ask spreads  
+- **V3**: `bid: bigint, ask: bigint` - Crypto bid/ask spreads
 - **V4**: `marketStatus: MarketStatus` - Real-world asset market status
 - **V5**: `rate: bigint, timestamp: number, duration: number` - Interest rate data with observation timestamp and duration
 - **V6**: `price: bigint, price2: bigint, price3: bigint, price4: bigint, price5: bigint` - Multiple price values in a single payload
@@ -274,6 +280,7 @@ interface BaseFields {
 - **V9**: `navPerShare: bigint, navDate: number, aum: bigint, ripcord: number` - NAV fund data
 - **V10**: `price: bigint, lastUpdateTimestamp: number, marketStatus: MarketStatus, currentMultiplier: bigint, newMultiplier: bigint, activationDateTime: number, tokenizedPrice: bigint` - Tokenized equity data
 - **V11**: `mid: bigint, LastSeenTimestampNs: number, bid: bigint, vidVolume: number, ask: bigint, askVolume: number, lastTradedPrice: bigint, marketStatus: MarketStatus` - Deutsche Boerse
+- **V12**: `navPerShare: bigint, nextNavPerShare: bigint, navDate: number, ripcord: number` - NAV fund data + Next
 - **V13**: `bestAsk: bigint, bestBid: bigint, askVolume: number, bidVolume: number, lastTradedPrice: bigint` - Best Bid/Ask
 
 For complete field definitions, see the [documentation](https://docs.chain.link/data-streams/reference/report-schema-v3).
@@ -283,7 +290,7 @@ For complete field definitions, see the [documentation](https://docs.chain.link/
 HA mode establishes multiple simultaneous connections for zero-downtime operation:
 
 - **Automatic failover** between connections
-- **Report deduplication** across connections  
+- **Report deduplication** across connections
 - **Automatic origin discovery** to find available endpoints
 - **Per-connection monitoring** and statistics
 
@@ -305,22 +312,22 @@ const client = createClient({
 
 ### Error Types Overview
 
-| **Error Type** | **When Thrown** | **Key Properties** |
-|---|---|---|
-| `ValidationError` | Invalid feed IDs, timestamps, parameters | `message` |
-| `AuthenticationError` | Invalid credentials, HMAC failures | `message` |
-| `APIError` | HTTP 4xx/5xx, network timeouts, rate limits | `statusCode`, `message` |
-| `ReportDecodingError` | Corrupted report data, unsupported versions | `message` |
-| `WebSocketError` | Connection failures, protocol errors | `message` |
-| `OriginDiscoveryError` | HA discovery failures | `cause`, `message` |
-| `MultiConnectionError` | All HA connections failed | `message` |
-| `PartialConnectionFailureError` | Some HA connections failed | `failedConnections`, `totalConnections` |
-| `InsufficientConnectionsError` | HA degraded performance | `availableConnections`, `requiredConnections` |
+| **Error Type**                  | **When Thrown**                             | **Key Properties**                            |
+|---------------------------------|---------------------------------------------|-----------------------------------------------|
+| `ValidationError`               | Invalid feed IDs, timestamps, parameters    | `message`                                     |
+| `AuthenticationError`           | Invalid credentials, HMAC failures          | `message`                                     |
+| `APIError`                      | HTTP 4xx/5xx, network timeouts, rate limits | `statusCode`, `message`                       |
+| `ReportDecodingError`           | Corrupted report data, unsupported versions | `message`                                     |
+| `WebSocketError`                | Connection failures, protocol errors        | `message`                                     |
+| `OriginDiscoveryError`          | HA discovery failures                       | `cause`, `message`                            |
+| `MultiConnectionError`          | All HA connections failed                   | `message`                                     |
+| `PartialConnectionFailureError` | Some HA connections failed                  | `failedConnections`, `totalConnections`       |
+| `InsufficientConnectionsError`  | HA degraded performance                     | `availableConnections`, `requiredConnections` |
 
 ### Usage Examples
 
 ```typescript
-import { 
+import {
   ValidationError,
   AuthenticationError,
   APIError,
@@ -358,6 +365,7 @@ stream.on('error', (error) => {
 ```
 
 **Catch-all error handling:**
+
 ```typescript
 import { DataStreamsError } from './src';
 
@@ -404,6 +412,7 @@ const client = createClient({
 ```
 
 Using Pino (structured JSON):
+
 ```typescript
 import pino from 'pino';
 import { createClient, LogLevel } from '@chainlink/data-streams-sdk';
@@ -429,6 +438,7 @@ const client = createClient({
 ```
 
 Command-line with pretty output:
+
 ```bash
 PINO_LEVEL=info npx ts-node examples/metrics-monitoring.ts | npx pino-pretty
 ```
@@ -505,10 +515,10 @@ interface LoggingConfig {
     warn?: (message: string, ...args: any[]) => void;
     error?: (message: string, ...args: any[]) => void;
   };
-  
+
   /** Minimum logging level - filters out lower priority logs */
   logLevel?: LogLevel; // DEBUG (0) | INFO (1) | WARN (2) | ERROR (3)
-  
+
   /** Enable WebSocket ping/pong and connection state debugging logs */
   enableConnectionDebug?: boolean;
 }
@@ -533,6 +543,7 @@ const m = stream.getMetrics();
 ```
 
 Simple periodic print (example):
+
 ```typescript
 setInterval(() => {
   const m = stream.getMetrics();

typescript/examples/README.md

@@ -87,7 +87,7 @@ npx ts-node examples/list-feeds.ts
 
 ## Feed IDs
 
-The SDK automatically detects and supports all report schema versions (V2, V3, V4, V5, V6, V7, V8, V9, V10, V11, V13).
+The SDK automatically detects and supports all report schema versions (V2, V3, V4, V5, V6, V7, V8, V9, V10, V11, V12, V13).
 
 For available feed IDs, see the official [Chainlink documentation](https://docs.chain.link/data-streams/).
 

typescript/src/decoder/implementation.ts

@@ -3,6 +3,7 @@ import { ReportDecodingError } from "../types/errors";
 import {
   DecodedV10Report,
   DecodedV11Report,
+  DecodedV12Report,
   DecodedV13Report,
   DecodedV2Report,
   DecodedV3Report,
@@ -13,6 +14,7 @@ import {
   DecodedV8Report,
   DecodedV9Report,
   MarketStatus,
+  Ripcord,
 } from "../types";
 
 import { SDKLogger } from "../utils/logger";
@@ -147,6 +149,19 @@ const reportSchemaV11 = [
   { type: "uint32", name: "marketStatus" },
 ];
 
+const reportSchemaV12 = [
+  { type: "bytes32", name: "feedId" },
+  { type: "uint32", name: "validFromTimestamp" },
+  { type: "uint32", name: "observationsTimestamp" },
+  { type: "uint192", name: "nativeFee" },
+  { type: "uint192", name: "linkFee" },
+  { type: "uint32", name: "expiresAt" },
+  { type: "int192", name: "navPerShare" },
+  { type: "int192", name: "nextNavPerShare" },
+  { type: "uint64", name: "navDate" },
+  { type: "uint32", name: "ripcord" },
+];
+
 const reportSchemaV13 = [
   { type: "bytes32", name: "feedId" },
   { type: "uint32", name: "validFromTimestamp" },
@@ -183,6 +198,7 @@ export function decodeReport(
   | DecodedV9Report
   | DecodedV10Report
   | DecodedV11Report
+  | DecodedV12Report
   | DecodedV13Report {
   logger?.debug(`Decoding report for feed ${feedId}`);
 
@@ -233,6 +249,8 @@ export function decodeReport(
         return decodeV10Report(reportBlob);
       case "000b":
         return decodeV11Report(reportBlob);
+      case "000c":
+        return decodeV12Report(reportBlob);
       case "000d":
         return decodeV13Report(reportBlob);
       default:
@@ -430,7 +448,7 @@ function decodeV9Report(reportBlob: string): DecodedV9Report {
     );
 
     const ripcord = Number(decoded[9]);
-    if (ripcord !== 0 && ripcord !== 1) {
+    if (ripcord !== Ripcord.NORMAL && ripcord !== Ripcord.PAUSED) {
       throw new ReportDecodingError(`Invalid ripcord value: ${ripcord}. Must be 0 (normal) or 1 (paused)`);
     }
 
@@ -515,6 +533,36 @@ function decodeV11Report(reportBlob: string): DecodedV11Report {
   }
 }
 
+function decodeV12Report(reportBlob: string): DecodedV12Report {
+  try {
+    const decoded = globalAbiCoder.decode(
+      reportSchemaV12.map(item => item.type),
+      getBytes(reportBlob)
+    );
+
+    const ripcord = Number(decoded[9]);
+    if (ripcord !== Ripcord.NORMAL && ripcord !== Ripcord.PAUSED) {
+      throw new ReportDecodingError(`Invalid ripcord value: ${ripcord}. Must be 0 (normal) or 1 (paused)`);
+    }
+
+    return {
+      version: "V12",
+      nativeFee: decoded[3],
+      linkFee: decoded[4],
+      expiresAt: Number(decoded[5]),
+      navPerShare: decoded[6],
+      nextNavPerShare: decoded[7],
+      navDate: Number(decoded[8]),
+      ripcord,
+    };
+  } catch (error) {
+    throw new ReportDecodingError(
+      `Failed to decode V12 report: ${error instanceof Error ? error.message : String(error)}`
+    );
+  }
+}
+
+
 function decodeV13Report(reportBlob: string): DecodedV13Report {
   try {
     const decoded = globalAbiCoder.decode(

typescript/src/index.ts

@@ -60,6 +60,7 @@ export type {
   DecodedV9Report,
   DecodedV10Report,
   DecodedV11Report,
+  DecodedV12Report,
   DecodedV13Report,
   MarketStatus,
 } from "./types/report";

typescript/src/types/report.ts

@@ -28,6 +28,11 @@ export enum MarketStatus {
   ACTIVE = 2,
 }
 
+export enum Ripcord {
+  NORMAL = 0,
+  PAUSED = 1,
+}
+
 /**
  * Base interface for all reports before decoding
  */
@@ -185,6 +190,20 @@ export interface DecodedV11Report extends DecodedReportFields {
   marketStatus: number;
 }
 
+/**
+ * Decoded V12 report format (NAV Data + Next).
+ */
+export interface DecodedV12Report extends DecodedReportFields {
+  version: "V12";
+  /** DON's consensus NAV per share (18 decimal precision) */
+  navPerShare: bigint;
+  nextNavPerShare: bigint;
+  /** Timestamp for the date the NAV report was produced */
+  navDate: number;
+  /** Emergency pause flag (0 = normal, 1 = paused - do not consume NAV data) */
+  ripcord: number;
+}
+
 /**
  * Decoded V13 report format (Best Bid/Ask).
  * Provides the best bid/ask prices, bid/ask volume and last traded price.
@@ -215,6 +234,7 @@ export type DecodedReport = (
   | DecodedV9Report
   | DecodedV10Report
   | DecodedV11Report
+  | DecodedV12Report
   | DecodedV13Report
   ) & {
   /** Feed ID this report belongs to */

typescript/src/utils/constants.ts

@@ -23,7 +23,7 @@ export const VALIDATION_REGEX = {
   /** Matches valid feed IDs (0x followed by 64 hex characters) */
   FEED_ID: /^0x[0-9a-fA-F]{64}$/,
   /** Matches valid schema versions (0x0002-0x0009, 0x000a, 0x000d) */
-  SCHEMA_VERSION: /^0x000([2-9]|a|b|d)$/,
+  SCHEMA_VERSION: /^0x000([2-9]|a|b|c|d)$/,
 } as const;
 
 // Request timeout constants