@k256/sdk 0.1.7 → 0.2.0

package/dist/types/index.d.cts

@@ -99,6 +99,37 @@ interface RoutePlanStep {
     /** Percentage of input for this step (0-100) */
     percent: number;
 }
+/**
+ * Mini block statistics (compact form used in FeeMarket.recentBlocks)
+ */
+interface BlockMiniStats {
+    slot: number;
+    cuConsumed: number;
+    txCount: number;
+    utilizationPct: number;
+    avgCuPrice: number;
+}
+/**
+ * Direction of the fee trend
+ */
+type TrendDirection = 'rising' | 'falling' | 'stable';
+/**
+ * Full block-level statistics (standalone message 0x0F)
+ */
+interface BlockStats {
+    slot: number;
+    cuConsumed: number;
+    executionCu: number;
+    cuLimit: number;
+    cuRemaining: number;
+    utilizationPct: number;
+    txCount: number;
+    avgCuPerTx: number;
+    avgCuPrice: number;
+    minCuPrice: number;
+    maxCuPrice: number;
+    timestampMs: number;
+}
 /**
  * Per-writable-account fee data
  *
@@ -152,6 +183,10 @@ interface FeeMarket {
     blocksInWindow: number;
     /** Per-account fee data */
     accounts: AccountFee[];
+    /** Recent block mini-stats (v3) */
+    recentBlocks: BlockMiniStats[];
+    /** Fee trend direction (v3) */
+    trend: TrendDirection;
 }
 /**
  * Network congestion state
@@ -231,4 +266,4 @@ interface SubscribeQuoteRequest {
     refreshIntervalMs?: number;
 }
 
-export { type AccountFee, type Blockhash, type FeeMarket, type Heartbeat, NetworkState, type OrderLevel, type Pool, type PoolUpdate, type Quote, type RoutePlanStep, type SubscribeQuoteRequest, type SubscribeRequest, type Token };
+export { type AccountFee, type BlockMiniStats, type BlockStats, type Blockhash, type FeeMarket, type Heartbeat, NetworkState, type OrderLevel, type Pool, type PoolUpdate, type Quote, type RoutePlanStep, type SubscribeQuoteRequest, type SubscribeRequest, type Token, type TrendDirection };

package/dist/types/index.d.ts

@@ -99,6 +99,37 @@ interface RoutePlanStep {
     /** Percentage of input for this step (0-100) */
     percent: number;
 }
+/**
+ * Mini block statistics (compact form used in FeeMarket.recentBlocks)
+ */
+interface BlockMiniStats {
+    slot: number;
+    cuConsumed: number;
+    txCount: number;
+    utilizationPct: number;
+    avgCuPrice: number;
+}
+/**
+ * Direction of the fee trend
+ */
+type TrendDirection = 'rising' | 'falling' | 'stable';
+/**
+ * Full block-level statistics (standalone message 0x0F)
+ */
+interface BlockStats {
+    slot: number;
+    cuConsumed: number;
+    executionCu: number;
+    cuLimit: number;
+    cuRemaining: number;
+    utilizationPct: number;
+    txCount: number;
+    avgCuPerTx: number;
+    avgCuPrice: number;
+    minCuPrice: number;
+    maxCuPrice: number;
+    timestampMs: number;
+}
 /**
  * Per-writable-account fee data
  *
@@ -152,6 +183,10 @@ interface FeeMarket {
     blocksInWindow: number;
     /** Per-account fee data */
     accounts: AccountFee[];
+    /** Recent block mini-stats (v3) */
+    recentBlocks: BlockMiniStats[];
+    /** Fee trend direction (v3) */
+    trend: TrendDirection;
 }
 /**
  * Network congestion state
@@ -231,4 +266,4 @@ interface SubscribeQuoteRequest {
     refreshIntervalMs?: number;
 }
 
-export { type AccountFee, type Blockhash, type FeeMarket, type Heartbeat, NetworkState, type OrderLevel, type Pool, type PoolUpdate, type Quote, type RoutePlanStep, type SubscribeQuoteRequest, type SubscribeRequest, type Token };
+export { type AccountFee, type BlockMiniStats, type BlockStats, type Blockhash, type FeeMarket, type Heartbeat, NetworkState, type OrderLevel, type Pool, type PoolUpdate, type Quote, type RoutePlanStep, type SubscribeQuoteRequest, type SubscribeRequest, type Token, type TrendDirection };

package/dist/types/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/types/index.ts"],"names":["NetworkState"],"mappings":";AAuKO,IAAK,YAAA,qBAAAA,aAAAA,KAAL;AACL,EAAAA,aAAAA,CAAAA,aAAAA,CAAA,SAAM,CAAA,CAAA,GAAN,KAAA;AACA,EAAAA,aAAAA,CAAAA,aAAAA,CAAA,YAAS,CAAA,CAAA,GAAT,QAAA;AACA,EAAAA,aAAAA,CAAAA,aAAAA,CAAA,UAAO,CAAA,CAAA,GAAP,MAAA;AACA,EAAAA,aAAAA,CAAAA,aAAAA,CAAA,eAAY,CAAA,CAAA,GAAZ,WAAA;AAJU,EAAA,OAAAA,aAAAA;AAAA,CAAA,EAAA,YAAA,IAAA,EAAA","file":"index.js","sourcesContent":["/**\n * Shared type definitions for K256 SDK\n *\n * These types are used across WebSocket and REST API modules.\n *\n * @module @k256/sdk/types\n */\n\n/**\n * Pool state from DEX\n */\nexport interface Pool {\n  /** Pool address (Base58) */\n  address: string;\n  /** Protocol/DEX name */\n  protocol: string;\n  /** Token mints in the pool (Base58) */\n  tokenMints: string[];\n  /** Token balances (as strings for precision) */\n  tokenBalances: string[];\n  /** Token decimals */\n  tokenDecimals: number[];\n}\n\n/**\n * Real-time pool state update\n */\nexport interface PoolUpdate extends Pool {\n  /** Global sequence number (monotonically increasing) */\n  sequence: number;\n  /** Solana slot when updated */\n  slot: number;\n  /** Write version within slot */\n  writeVersion: number;\n  /** Best bid price/size (orderbook pools only) */\n  bestBid?: OrderLevel;\n  /** Best ask price/size (orderbook pools only) */\n  bestAsk?: OrderLevel;\n}\n\n/**\n * Order book level (bid or ask)\n */\nexport interface OrderLevel {\n  /** Price in base units (as string for precision) */\n  price: string;\n  /** Size in base units (as string for precision) */\n  size: string;\n}\n\n/**\n * Token metadata\n */\nexport interface Token {\n  /** Token mint address (Base58) */\n  mint: string;\n  /** Token symbol (e.g., \"SOL\", \"USDC\") */\n  symbol: string;\n  /** Token name */\n  name: string;\n  /** Decimal places */\n  decimals: number;\n  /** Logo URL (optional) */\n  logoUri?: string;\n  /** Coingecko ID (optional) */\n  coingeckoId?: string;\n}\n\n/**\n * Swap quote from aggregator\n */\nexport interface Quote {\n  /** Input token mint (Base58) */\n  inputMint: string;\n  /** Output token mint (Base58) */\n  outputMint: string;\n  /** Input amount (as string for precision) */\n  inAmount: string;\n  /** Output amount (as string for precision) */\n  outAmount: string;\n  /** Price impact in basis points */\n  priceImpactBps: number;\n  /** Slippage in basis points */\n  slippageBps: number;\n  /** Route plan (DEXes used) */\n  routePlan: RoutePlanStep[];\n  /** Context slot */\n  contextSlot: number;\n  /** Algorithm used for routing */\n  algorithm: string;\n}\n\n/**\n * Step in a swap route\n */\nexport interface RoutePlanStep {\n  /** DEX/protocol name */\n  protocol: string;\n  /** Pool address (Base58) */\n  poolAddress: string;\n  /** Input mint for this step */\n  inputMint: string;\n  /** Output mint for this step */\n  outputMint: string;\n  /** Percentage of input for this step (0-100) */\n  percent: number;\n}\n\n/**\n * Per-writable-account fee data\n *\n * Solana's scheduler limits each writable account to 12M CU per block.\n * Fee pricing is per-account: the fee you pay should be\n * max(p75(account) for account in your writable accounts).\n */\nexport interface AccountFee {\n  /** Account public key (Base58) */\n  pubkey: string;\n  /** Total transactions touching this account in the window */\n  totalTxs: number;\n  /** Number of slots where this account was active */\n  activeSlots: number;\n  /** Total CU consumed by transactions touching this account */\n  cuConsumed: number;\n  /** Account utilization percentage (0-100) of 12M CU limit */\n  utilizationPct: number;\n  /** 25th percentile fee in microlamports/CU */\n  p25: number;\n  /** 50th percentile fee in microlamports/CU */\n  p50: number;\n  /** 75th percentile fee in microlamports/CU */\n  p75: number;\n  /** 90th percentile fee in microlamports/CU */\n  p90: number;\n  /** Minimum non-zero fee observed */\n  minNonzeroPrice: number;\n}\n\n/**\n * Fee market update (per-writable-account model)\n *\n * Replaces the old flat PriorityFees struct. Now provides per-account\n * fee data so clients can price transactions based on the specific\n * writable accounts they touch.\n */\nexport interface FeeMarket {\n  /** Current slot */\n  slot: number;\n  /** Timestamp in milliseconds */\n  timestampMs: number;\n  /** Recommended fee in microlamports/CU (max p75 across hottest accounts) */\n  recommended: number;\n  /** Network state (0=low, 1=normal, 2=high, 3=extreme) */\n  state: NetworkState;\n  /** Whether data is stale */\n  isStale: boolean;\n  /** Block utilization percentage (0-100) */\n  blockUtilizationPct: number;\n  /** Number of blocks in the observation window */\n  blocksInWindow: number;\n  /** Per-account fee data */\n  accounts: AccountFee[];\n}\n\n/**\n * Network congestion state\n */\nexport enum NetworkState {\n  Low = 0,\n  Normal = 1,\n  High = 2,\n  Congested = 3,\n}\n\n/**\n * Recent blockhash for transactions\n */\nexport interface Blockhash {\n  /** Slot of blockhash */\n  slot: number;\n  /** Timestamp in milliseconds */\n  timestampMs: number;\n  /** Recent blockhash (Base58) */\n  blockhash: string;\n  /** Block height */\n  blockHeight: number;\n  /** Last valid block height for transactions */\n  lastValidBlockHeight: number;\n  /** Whether data is stale */\n  isStale: boolean;\n}\n\n/**\n * WebSocket connection heartbeat\n */\nexport interface Heartbeat {\n  /** Server timestamp in milliseconds */\n  timestampMs: number;\n  /** Connection uptime in seconds */\n  uptimeSecs: number;\n  /** Total messages sent */\n  messagesSent: number;\n  /** Pool updates sent */\n  poolUpdatesSent: number;\n  /** Messages dropped (slow client) */\n  messagesDropped: number;\n  /** Whether pool updates are enabled */\n  poolUpdatesEnabled: boolean;\n  /** Subscribed channels */\n  subscribedChannels: string[];\n  /** Server sequence number */\n  serverSequence: number;\n}\n\n/**\n * Subscribe request for WebSocket\n */\nexport interface SubscribeRequest {\n  /** Channels to subscribe to */\n  channels: ('pools' | 'priority_fees' | 'blockhash')[];\n  /** Response format (default: binary) */\n  format?: 'binary' | 'json';\n  /** Filter by protocol names */\n  protocols?: string[];\n  /** Filter by pool addresses (Base58) */\n  pools?: string[];\n  /** Filter by token pairs [[mintA, mintB], ...] */\n  tokenPairs?: [string, string][];\n}\n\n/**\n * Quote subscription request\n */\nexport interface SubscribeQuoteRequest {\n  /** Input token mint (Base58) */\n  inputMint: string;\n  /** Output token mint (Base58) */\n  outputMint: string;\n  /** Amount in base units */\n  amount: number;\n  /** Slippage tolerance in basis points */\n  slippageBps?: number;\n  /** Refresh interval in milliseconds */\n  refreshIntervalMs?: number;\n}\n"]}
+{"version":3,"sources":["../../src/types/index.ts"],"names":["NetworkState"],"mappings":";AA6MO,IAAK,YAAA,qBAAAA,aAAAA,KAAL;AACL,EAAAA,aAAAA,CAAAA,aAAAA,CAAA,SAAM,CAAA,CAAA,GAAN,KAAA;AACA,EAAAA,aAAAA,CAAAA,aAAAA,CAAA,YAAS,CAAA,CAAA,GAAT,QAAA;AACA,EAAAA,aAAAA,CAAAA,aAAAA,CAAA,UAAO,CAAA,CAAA,GAAP,MAAA;AACA,EAAAA,aAAAA,CAAAA,aAAAA,CAAA,eAAY,CAAA,CAAA,GAAZ,WAAA;AAJU,EAAA,OAAAA,aAAAA;AAAA,CAAA,EAAA,YAAA,IAAA,EAAA","file":"index.js","sourcesContent":["/**\n * Shared type definitions for K256 SDK\n *\n * These types are used across WebSocket and REST API modules.\n *\n * @module @k256/sdk/types\n */\n\n/**\n * Pool state from DEX\n */\nexport interface Pool {\n  /** Pool address (Base58) */\n  address: string;\n  /** Protocol/DEX name */\n  protocol: string;\n  /** Token mints in the pool (Base58) */\n  tokenMints: string[];\n  /** Token balances (as strings for precision) */\n  tokenBalances: string[];\n  /** Token decimals */\n  tokenDecimals: number[];\n}\n\n/**\n * Real-time pool state update\n */\nexport interface PoolUpdate extends Pool {\n  /** Global sequence number (monotonically increasing) */\n  sequence: number;\n  /** Solana slot when updated */\n  slot: number;\n  /** Write version within slot */\n  writeVersion: number;\n  /** Best bid price/size (orderbook pools only) */\n  bestBid?: OrderLevel;\n  /** Best ask price/size (orderbook pools only) */\n  bestAsk?: OrderLevel;\n}\n\n/**\n * Order book level (bid or ask)\n */\nexport interface OrderLevel {\n  /** Price in base units (as string for precision) */\n  price: string;\n  /** Size in base units (as string for precision) */\n  size: string;\n}\n\n/**\n * Token metadata\n */\nexport interface Token {\n  /** Token mint address (Base58) */\n  mint: string;\n  /** Token symbol (e.g., \"SOL\", \"USDC\") */\n  symbol: string;\n  /** Token name */\n  name: string;\n  /** Decimal places */\n  decimals: number;\n  /** Logo URL (optional) */\n  logoUri?: string;\n  /** Coingecko ID (optional) */\n  coingeckoId?: string;\n}\n\n/**\n * Swap quote from aggregator\n */\nexport interface Quote {\n  /** Input token mint (Base58) */\n  inputMint: string;\n  /** Output token mint (Base58) */\n  outputMint: string;\n  /** Input amount (as string for precision) */\n  inAmount: string;\n  /** Output amount (as string for precision) */\n  outAmount: string;\n  /** Price impact in basis points */\n  priceImpactBps: number;\n  /** Slippage in basis points */\n  slippageBps: number;\n  /** Route plan (DEXes used) */\n  routePlan: RoutePlanStep[];\n  /** Context slot */\n  contextSlot: number;\n  /** Algorithm used for routing */\n  algorithm: string;\n}\n\n/**\n * Step in a swap route\n */\nexport interface RoutePlanStep {\n  /** DEX/protocol name */\n  protocol: string;\n  /** Pool address (Base58) */\n  poolAddress: string;\n  /** Input mint for this step */\n  inputMint: string;\n  /** Output mint for this step */\n  outputMint: string;\n  /** Percentage of input for this step (0-100) */\n  percent: number;\n}\n\n/**\n * Mini block statistics (compact form used in FeeMarket.recentBlocks)\n */\nexport interface BlockMiniStats {\n  slot: number\n  cuConsumed: number\n  txCount: number\n  utilizationPct: number\n  avgCuPrice: number\n}\n\n/**\n * Direction of the fee trend\n */\nexport type TrendDirection = 'rising' | 'falling' | 'stable'\n\n/**\n * Full block-level statistics (standalone message 0x0F)\n */\nexport interface BlockStats {\n  slot: number\n  cuConsumed: number\n  executionCu: number\n  cuLimit: number\n  cuRemaining: number\n  utilizationPct: number\n  txCount: number\n  avgCuPerTx: number\n  avgCuPrice: number\n  minCuPrice: number\n  maxCuPrice: number\n  timestampMs: number\n}\n\n/**\n * Per-writable-account fee data\n *\n * Solana's scheduler limits each writable account to 12M CU per block.\n * Fee pricing is per-account: the fee you pay should be\n * max(p75(account) for account in your writable accounts).\n */\nexport interface AccountFee {\n  /** Account public key (Base58) */\n  pubkey: string;\n  /** Total transactions touching this account in the window */\n  totalTxs: number;\n  /** Number of slots where this account was active */\n  activeSlots: number;\n  /** Total CU consumed by transactions touching this account */\n  cuConsumed: number;\n  /** Account utilization percentage (0-100) of 12M CU limit */\n  utilizationPct: number;\n  /** 25th percentile fee in microlamports/CU */\n  p25: number;\n  /** 50th percentile fee in microlamports/CU */\n  p50: number;\n  /** 75th percentile fee in microlamports/CU */\n  p75: number;\n  /** 90th percentile fee in microlamports/CU */\n  p90: number;\n  /** Minimum non-zero fee observed */\n  minNonzeroPrice: number;\n}\n\n/**\n * Fee market update (per-writable-account model)\n *\n * Replaces the old flat PriorityFees struct. Now provides per-account\n * fee data so clients can price transactions based on the specific\n * writable accounts they touch.\n */\nexport interface FeeMarket {\n  /** Current slot */\n  slot: number;\n  /** Timestamp in milliseconds */\n  timestampMs: number;\n  /** Recommended fee in microlamports/CU (max p75 across hottest accounts) */\n  recommended: number;\n  /** Network state (0=low, 1=normal, 2=high, 3=extreme) */\n  state: NetworkState;\n  /** Whether data is stale */\n  isStale: boolean;\n  /** Block utilization percentage (0-100) */\n  blockUtilizationPct: number;\n  /** Number of blocks in the observation window */\n  blocksInWindow: number;\n  /** Per-account fee data */\n  accounts: AccountFee[];\n  /** Recent block mini-stats (v3) */\n  recentBlocks: BlockMiniStats[];\n  /** Fee trend direction (v3) */\n  trend: TrendDirection;\n}\n\n/**\n * Network congestion state\n */\nexport enum NetworkState {\n  Low = 0,\n  Normal = 1,\n  High = 2,\n  Congested = 3,\n}\n\n/**\n * Recent blockhash for transactions\n */\nexport interface Blockhash {\n  /** Slot of blockhash */\n  slot: number;\n  /** Timestamp in milliseconds */\n  timestampMs: number;\n  /** Recent blockhash (Base58) */\n  blockhash: string;\n  /** Block height */\n  blockHeight: number;\n  /** Last valid block height for transactions */\n  lastValidBlockHeight: number;\n  /** Whether data is stale */\n  isStale: boolean;\n}\n\n/**\n * WebSocket connection heartbeat\n */\nexport interface Heartbeat {\n  /** Server timestamp in milliseconds */\n  timestampMs: number;\n  /** Connection uptime in seconds */\n  uptimeSecs: number;\n  /** Total messages sent */\n  messagesSent: number;\n  /** Pool updates sent */\n  poolUpdatesSent: number;\n  /** Messages dropped (slow client) */\n  messagesDropped: number;\n  /** Whether pool updates are enabled */\n  poolUpdatesEnabled: boolean;\n  /** Subscribed channels */\n  subscribedChannels: string[];\n  /** Server sequence number */\n  serverSequence: number;\n}\n\n/**\n * Subscribe request for WebSocket\n */\nexport interface SubscribeRequest {\n  /** Channels to subscribe to */\n  channels: ('pools' | 'priority_fees' | 'blockhash')[];\n  /** Response format (default: binary) */\n  format?: 'binary' | 'json';\n  /** Filter by protocol names */\n  protocols?: string[];\n  /** Filter by pool addresses (Base58) */\n  pools?: string[];\n  /** Filter by token pairs [[mintA, mintB], ...] */\n  tokenPairs?: [string, string][];\n}\n\n/**\n * Quote subscription request\n */\nexport interface SubscribeQuoteRequest {\n  /** Input token mint (Base58) */\n  inputMint: string;\n  /** Output token mint (Base58) */\n  outputMint: string;\n  /** Amount in base units */\n  amount: number;\n  /** Slippage tolerance in basis points */\n  slippageBps?: number;\n  /** Refresh interval in milliseconds */\n  refreshIntervalMs?: number;\n}\n"]}

package/dist/ws/index.cjs

@@ -53,6 +53,8 @@ var MessageType = {
   Heartbeat: 13,
   /** Batched pool updates for high throughput */
   PoolUpdateBatch: 14,
+  /** Block-level statistics (v3) */
+  BlockStats: 15,
   /** Error message (UTF-8 string) */
   Error: 255
 };
@@ -130,6 +132,25 @@ function decodeMessage(data) {
         });
         offset += 92;
       }
+      const recentBlocksCount = Number(payloadView.getBigUint64(offset, true));
+      offset += 8;
+      const recentBlocks = [];
+      for (let i = 0; i < recentBlocksCount; i++) {
+        const rbSlot = Number(payloadView.getBigUint64(offset, true));
+        offset += 8;
+        const rbCuConsumed = Number(payloadView.getBigUint64(offset, true));
+        offset += 8;
+        const rbTxCount = payloadView.getUint32(offset, true);
+        offset += 4;
+        const rbUtilizationPct = payloadView.getFloat32(offset, true);
+        offset += 4;
+        const rbAvgCuPrice = Number(payloadView.getBigUint64(offset, true));
+        offset += 8;
+        recentBlocks.push({ slot: rbSlot, cuConsumed: rbCuConsumed, txCount: rbTxCount, utilizationPct: rbUtilizationPct, avgCuPrice: rbAvgCuPrice });
+      }
+      const trendByte = payloadView.getUint8(offset);
+      offset += 1;
+      const trend = trendByte === 0 ? "rising" : trendByte === 1 ? "falling" : "stable";
       return {
         type: "fee_market",
         data: {
@@ -140,7 +161,9 @@ function decodeMessage(data) {
           isStale,
           blockUtilizationPct,
           blocksInWindow,
-          accounts
+          accounts,
+          recentBlocks,
+          trend
         }
       };
     }
@@ -185,6 +208,51 @@ function decodeMessage(data) {
         }
       };
     }
+    case MessageType.BlockStats: {
+      let offset = 0;
+      const slot = Number(payloadView.getBigUint64(offset, true));
+      offset += 8;
+      const cuConsumed = Number(payloadView.getBigUint64(offset, true));
+      offset += 8;
+      const executionCu = Number(payloadView.getBigUint64(offset, true));
+      offset += 8;
+      const cuLimit = Number(payloadView.getBigUint64(offset, true));
+      offset += 8;
+      const cuRemaining = Number(payloadView.getBigUint64(offset, true));
+      offset += 8;
+      const utilizationPct = payloadView.getFloat32(offset, true);
+      offset += 4;
+      const txCount = payloadView.getUint32(offset, true);
+      offset += 4;
+      const avgCuPerTx = payloadView.getUint32(offset, true);
+      offset += 4;
+      const avgCuPrice = Number(payloadView.getBigUint64(offset, true));
+      offset += 8;
+      const minCuPrice = Number(payloadView.getBigUint64(offset, true));
+      offset += 8;
+      const maxCuPrice = Number(payloadView.getBigUint64(offset, true));
+      offset += 8;
+      const timestampMs = Number(payloadView.getBigUint64(offset, true));
+      offset += 8;
+      return {
+        type: "block_stats",
+        data: {
+          slot,
+          cuConsumed,
+          executionCu,
+          cuLimit,
+          cuRemaining,
+          utilizationPct,
+          txCount,
+          avgCuPerTx,
+          avgCuPrice,
+          minCuPrice,
+          maxCuPrice,
+          timestampMs
+        },
+        receivedAt: Date.now()
+      };
+    }
     default:
       return null;
   }
@@ -642,6 +710,9 @@ var K256WebSocketClient = class {
         case "fee_market":
           this.config.onFeeMarket?.(decoded);
           break;
+        case "block_stats":
+          this.config.onBlockStats?.(decoded);
+          break;
         case "blockhash":
           this.config.onBlockhash?.(decoded);
           break;