@sentio/sdk 2.59.0-rc.23 → 2.59.0-rc.25

package/src/btc/btc-plugin.ts

@@ -7,10 +7,12 @@ import {
   HandlerType,
   ProcessConfigResponse,
   ProcessResult,
+  ProcessStreamResponse_Partitions,
   StartRequest
 } from '@sentio/protos'
 
 import { ServerError, Status } from 'nice-grpc'
+import { PartitionHandlerManager } from '../core/index.js'
 import { TemplateInstanceState } from '../core/template.js'
 import { BTCProcessorState } from './btc-processor.js'
 import { filters2Proto, TransactionFilter } from './filter.js'
@@ -27,6 +29,8 @@ export class BTCPlugin extends Plugin {
     blockHandlers: []
   }
 
+  partitionManager = new PartitionHandlerManager()
+
   async configure(config: ProcessConfigResponse) {
     const handlers: Handlers = {
       txHandlers: [],
@@ -47,6 +51,11 @@ export class BTCPlugin extends Plugin {
       })
       for (const callHandler of processor.callHandlers) {
         const handlerId = handlers.txHandlers.push(callHandler.handler) - 1
+        this.partitionManager.registerPartitionHandler(
+          HandlerType.BTC_TRANSACTION,
+          handlerId,
+          callHandler.partitionHandler
+        )
         const handlerName = callHandler.handlerName
 
         if (callHandler.filter) {
@@ -70,6 +79,7 @@ export class BTCPlugin extends Plugin {
 
       for (const blockHandler of processor.blockHandlers) {
         const handlerId = handlers.blockHandlers.push(blockHandler.handler) - 1
+        this.partitionManager.registerPartitionHandler(HandlerType.BTC_BLOCK, handlerId, blockHandler.partitionHandler)
         contractConfig.intervalConfigs.push({
           slot: 0,
           slotInterval: blockHandler.blockInterval,
@@ -107,6 +117,34 @@ export class BTCPlugin extends Plugin {
     }
   }
 
+  async partition(request: DataBinding): Promise<ProcessStreamResponse_Partitions> {
+    let data: any
+    switch (request.handlerType) {
+      case HandlerType.BTC_TRANSACTION:
+        if (!request.data?.btcTransaction) {
+          throw new ServerError(Status.INVALID_ARGUMENT, "btcTransaction can't be empty")
+        }
+        data = request.data.btcTransaction
+        break
+      case HandlerType.BTC_BLOCK:
+        if (!request.data?.btcBlock) {
+          throw new ServerError(Status.INVALID_ARGUMENT, "btcBlock can't be empty")
+        }
+        data = request.data.btcBlock
+        break
+      default:
+        throw new ServerError(Status.INVALID_ARGUMENT, 'No handle type registered ' + request.handlerType)
+    }
+    const partitions = await this.partitionManager.processPartitionForHandlerType(
+      request.handlerType,
+      request.handlerIds,
+      data
+    )
+    return {
+      partitions
+    }
+  }
+
   async start(request: StartRequest) {}
 
   stateDiff(config: ProcessConfigResponse): boolean {

package/src/btc/btc-processor.ts

@@ -2,7 +2,7 @@ import { ListStateStorage } from '@sentio/runtime'
 import { BlockHandler, BTCBlock, BTCBlockContext, BTCContext, BTCOnIntervalFetchConfig, Transaction } from './types.js'
 import { Data_BTCBlock, Data_BTCTransaction, HandleInterval, ProcessResult } from '@sentio/protos'
 import { TransactionFilters } from './filter.js'
-import { PromiseOrVoid } from '../core/index.js'
+import { HandlerOptions, PromiseOrVoid } from '../core/index.js'
 import { ServerError, Status } from 'nice-grpc'
 import { getHandlerName, proxyProcessor } from '../utils/metrics.js'
 
@@ -26,7 +26,8 @@ export class BTCProcessor {
 
   public onTransaction(
     handler: (transaction: Transaction, ctx: BTCContext) => void | Promise<void>,
-    filter?: TransactionFilters
+    filter?: TransactionFilters,
+    handlerOptions?: HandlerOptions<object, Transaction>
   ) {
     const callHandler = {
       handlerName: getHandlerName(),
@@ -42,7 +43,16 @@ export class BTCProcessor {
         await handler(tx, ctx)
         return ctx.stopAndGetResult()
       },
-      filter
+      filter,
+      partitionHandler: async (call: Data_BTCTransaction): Promise<string | undefined> => {
+        const p = handlerOptions?.partitionKey
+        if (!p) return undefined
+        if (typeof p === 'function') {
+          const tx = call.transaction as Transaction
+          return p(tx)
+        }
+        return p
+      }
     }
     this.callHandlers.push(callHandler)
     return this
@@ -52,7 +62,7 @@ export class BTCProcessor {
     handler: (block: BTCBlock, ctx: BTCBlockContext) => PromiseOrVoid,
     timeInterval: HandleInterval | undefined,
     blockInterval: HandleInterval | undefined,
-    fetchConfig?: BTCOnIntervalFetchConfig
+    handlerOptions?: HandlerOptions<BTCOnIntervalFetchConfig, BTCBlock>
   ): this {
     if (timeInterval) {
       if (timeInterval.backfillInterval < timeInterval.recentInterval) {
@@ -75,7 +85,7 @@ export class BTCProcessor {
         const block = {
           ...header
         } as BTCBlock
-        if (fetchConfig?.getTransactions) {
+        if (handlerOptions?.getTransactions) {
           block.tx = header.rawtx?.map((tx: any) => tx as Transaction)
         }
 
@@ -88,7 +98,21 @@ export class BTCProcessor {
         await handler(block, ctx)
         return ctx.stopAndGetResult()
       },
-      fetchConfig
+      fetchConfig: handlerOptions,
+      partitionHandler: async (data: Data_BTCBlock): Promise<string | undefined> => {
+        const p = handlerOptions?.partitionKey
+        if (!p) return undefined
+        if (typeof p === 'function') {
+          const header = data.block
+          if (!header) return undefined
+          const block = { ...header } as BTCBlock
+          if (handlerOptions?.getTransactions) {
+            block.tx = header.rawtx?.map((tx: any) => tx as Transaction)
+          }
+          return p(block)
+        }
+        return p
+      }
     })
     return this
   }
@@ -97,7 +121,7 @@ export class BTCProcessor {
     handler: (block: BTCBlock, ctx: BTCBlockContext) => PromiseOrVoid,
     blockInterval = 250,
     backfillBlockInterval = 1000,
-    fetchConfig?: BTCOnIntervalFetchConfig
+    handlerOptions?: HandlerOptions<BTCOnIntervalFetchConfig, BTCBlock>
   ): this {
     return this.onInterval(
       handler,
@@ -106,7 +130,7 @@ export class BTCProcessor {
         recentInterval: blockInterval,
         backfillInterval: backfillBlockInterval
       },
-      fetchConfig
+      handlerOptions
     )
   }
 
@@ -114,13 +138,13 @@ export class BTCProcessor {
     handler: (block: BTCBlock, ctx: BTCBlockContext) => PromiseOrVoid,
     timeIntervalInMinutes = 60,
     backfillTimeIntervalInMinutes = 240,
-    fetchConfig?: BTCOnIntervalFetchConfig
+    handlerOptions?: HandlerOptions<BTCOnIntervalFetchConfig, BTCBlock>
   ): this {
     return this.onInterval(
       handler,
       { recentInterval: timeIntervalInMinutes, backfillInterval: backfillTimeIntervalInMinutes },
       undefined,
-      fetchConfig
+      handlerOptions
     )
   }
 }
@@ -137,4 +161,5 @@ export type CallHandler<T> = {
   handlerName: string
   handler: (call: T) => Promise<ProcessResult>
   filter?: TransactionFilters
+  partitionHandler?: (call: T) => Promise<string | undefined>
 }

package/src/btc/types.ts

@@ -126,8 +126,9 @@ export type BlockHandler = {
   handler: (block: Data_BTCBlock) => Promise<ProcessResult>
   handlerName: string
   fetchConfig?: BTCOnIntervalFetchConfig
+  partitionHandler?: (block: Data_BTCBlock) => Promise<string | undefined>
 }
 
 export type BTCOnIntervalFetchConfig = {
-  getTransactions: boolean
+  getTransactions?: boolean
 }

package/src/core/handler-options.ts

@@ -0,0 +1,40 @@
+/**
+ * Function type that extracts a partition key from data.
+ * @template D The data type to process
+ */
+export type PartitionHandler<D> = (data: D) => string | Promise<string>
+
+/**
+ * Handler options that extend fetch configuration with optional partitioning support.
+ * @template F The fetch configuration type (e.g., EthFetchConfig, MoveFetchConfig)
+ * @template D The data type that will be processed (e.g., Event, Transaction, Block)
+ */
+export type HandlerOptions<F, D> = Partial<F> & {
+  /**
+   * Optional partition key for data partitioning.
+   * Can be a static string or a function that computes the key from the data.
+   */
+  partitionKey?: string | PartitionHandler<D>
+}
+
+/**
+ * Merge two handler options, with the second options taking precedence over the first.
+ * @param options1 First handler options
+ * @param options2 Second handler options (takes precedence)
+ * @returns Merged handler options
+ */
+export function mergeHandlerOptions<F, D>(
+  options1?: HandlerOptions<F, D>,
+  options2?: HandlerOptions<F, D>
+): HandlerOptions<F, D> | undefined {
+  if (!options1 && !options2) return undefined
+  if (!options1) return options2
+  if (!options2) return options1
+
+  return {
+    ...options1,
+    ...options2,
+    // For partitionKey, the second option takes precedence
+    partitionKey: options2.partitionKey ?? options1.partitionKey
+  }
+}

package/src/core/index.ts

@@ -22,3 +22,8 @@ export { type Numberish, toBigInteger, toMetricValue } from './numberish.js'
 export { CorePlugin } from './core-plugin.js'
 export { DatabaseSchema } from './database-schema.js'
 export * from './constants.js'
+export { type HandlerOptions, type PartitionHandler, mergeHandlerOptions } from './handler-options.js'
+export {
+  PartitionHandlerManager,
+  type PartitionHandler as PartitionHandlerFunction
+} from './partition-handler-manager.js'

package/src/core/partition-handler-manager.ts

@@ -0,0 +1,94 @@
+import {
+  HandlerType,
+  ProcessStreamResponse_Partitions_Partition,
+  ProcessStreamResponse_Partitions_Partition_SysValue
+} from '@sentio/protos'
+import { ServerError, Status } from 'nice-grpc'
+
+/**
+ * Type for partition handler functions that can process any data type
+ */
+export type PartitionHandler = (request: any) => Promise<string | undefined>
+
+/**
+ * Generic manager for handling partition logic across all chain plugins.
+ * Provides a unified interface for registering, storing, and processing partition handlers.
+ * Chain-specific logic should remain in individual plugins.
+ */
+export class PartitionHandlerManager {
+  private partitionHandlers: Map<HandlerType, Record<number, PartitionHandler>> = new Map()
+
+  /**
+   * Register a partition handler for a specific handler type and ID
+   * @param handlerType The type of handler (e.g., HandlerType.ETH_LOG, HandlerType.APT_EVENT)
+   * @param handlerId The unique ID for this handler instance
+   * @param partitionHandler The partition handler function (optional)
+   */
+  registerPartitionHandler(handlerType: HandlerType, handlerId: number, partitionHandler?: PartitionHandler): void {
+    if (partitionHandler) {
+      const existingHandlers = this.partitionHandlers.get(handlerType) || {}
+      existingHandlers[handlerId] = partitionHandler
+      this.partitionHandlers.set(handlerType, existingHandlers)
+    }
+  }
+
+  /**
+   * Process partition logic for a specific handler type
+   * @param handlerType The type of handler being processed
+   * @param handlerIds Array of handler IDs to process
+   * @param data The data to pass to partition handlers
+   * @returns Record mapping handler IDs to partition results
+   */
+  async processPartitionForHandlerType(
+    handlerType: HandlerType,
+    handlerIds: number[],
+    data: any
+  ): Promise<Record<number, ProcessStreamResponse_Partitions_Partition>> {
+    const result: Record<number, ProcessStreamResponse_Partitions_Partition> = {}
+
+    for (const handlerId of handlerIds) {
+      const partitionHandler = this.partitionHandlers.get(handlerType)?.[handlerId]
+      if (partitionHandler && data) {
+        try {
+          const partitionValue = await partitionHandler(data)
+          result[handlerId] = {
+            userValue: partitionValue
+          }
+        } catch (error) {
+          // If partition handler fails, fall back to unrecognized
+          throw new ServerError(Status.INVALID_ARGUMENT, 'compute partition key failed, error:' + error.message)
+        }
+      } else {
+        result[handlerId] = {
+          sysValue: ProcessStreamResponse_Partitions_Partition_SysValue.UNRECOGNIZED
+        }
+      }
+    }
+
+    return result
+  }
+
+  /**
+   * Clear all partition handlers (useful for testing or reinitialization)
+   */
+  clear(): void {
+    this.partitionHandlers.clear()
+  }
+
+  /**
+   * Get all registered handler types
+   * @returns Array of handler types that have registered partition handlers
+   */
+  getRegisteredHandlerTypes(): HandlerType[] {
+    return Array.from(this.partitionHandlers.keys())
+  }
+
+  /**
+   * Get the number of registered handlers for a specific handler type
+   * @param handlerType The handler type to check
+   * @returns Number of registered handlers for this type
+   */
+  getHandlerCount(handlerType: HandlerType): number {
+    return Object.keys(this.partitionHandlers.get(handlerType) || {}).length
+  }
+}

package/src/cosmos/cosmos-processor.ts

@@ -3,6 +3,7 @@ import { Data_CosmosCall } from '@sentio/protos'
 import { CosmosContext } from './context.js'
 import { CosmosEvent, CosmosTransaction, CosmosTxLog } from './transaction.js'
 import { getHandlerName, proxyProcessor } from '../utils/metrics.js'
+import { HandlerOptions } from '../core/handler-options.js'
 
 export class CosmosProcessor {
   callHandlers: CallHandler<Data_CosmosCall>[] = []
@@ -19,7 +20,8 @@ export class CosmosProcessor {
 
   public onLogEvent(
     logFilters: string[] | string,
-    handler: (log: CosmosTxLog, event: CosmosEvent, context: CosmosContext) => void | Promise<void>
+    handler: (log: CosmosTxLog, event: CosmosEvent, context: CosmosContext) => void | Promise<void>,
+    handlerOptions?: HandlerOptions<object, CosmosTransaction>
   ) {
     const filter = Array.isArray(logFilters) ? logFilters : [logFilters]
     const callHandler = {
@@ -39,6 +41,15 @@ export class CosmosProcessor {
       },
       logConfig: {
         logFilters: filter
+      },
+      partitionHandler: async (call: Data_CosmosCall): Promise<string | undefined> => {
+        const p = handlerOptions?.partitionKey
+        if (!p) return undefined
+        if (typeof p === 'function') {
+          const transaction = call.transaction as CosmosTransaction
+          return p(transaction)
+        }
+        return p
       }
     }
     this.callHandlers.push(callHandler)

package/src/cosmos/types.ts

@@ -13,6 +13,7 @@ export type CallHandler<T> = {
   logConfig?: {
     logFilters: string[]
   }
+  partitionHandler?: (call: T) => Promise<string | undefined>
 }
 
 export type CosmosProcessorConfig = {