@ocap/types 1.28.9 → 1.29.1

package/interfaces/pipeline.ts

@@ -0,0 +1,525 @@
+// core/types/interfaces/pipeline.ts
+//
+// Transaction Pipeline Context Type System
+// ========================================
+//
+// This module defines a 5-phase context type hierarchy for transaction processing:
+//
+//   Phase 1: IBaseContext      -> Initial input (txBase64, statedb, config, indexdb)
+//   Phase 2: IDecodedContext   -> After DecodeTx + DecodeItx (tx, itx, txType, txHash)
+//   Phase 3: IGasContext       -> After ExtractState + EnsureTxGas + EnsureTxCost
+//   Phase 4: IReadyContext     -> After TakeStateSnapshot, ready for business logic
+//   Phase 5: IExecutedContext  -> After business logic execution complete
+//
+// Protocol-specific states are provided as Mixin interfaces (IWithSender, IWithAsset, etc.)
+// that can be combined with phase types to create protocol-specific context types.
+//
+// Example:
+//   type DelegateContext = IReadyContext<TDelegateTx> & IWithSender & IWithReceiver & IWithDelegation;
+//
+
+import type { TTokenInput, TTransactionReceipt } from '../lib/type_pb';
+import type { BN } from './base';
+import type { IAny } from './base';
+import type { IChainConfig } from './config';
+import type { IIndexDB } from './indexdb';
+import type {
+  IAccountState,
+  IAssetFactoryState,
+  IAssetState,
+  IDelegateState,
+  IEvidenceState,
+  IRollupBlock,
+  IRollupState,
+  IStakeState,
+  ITokenFactoryState,
+  ITokenState,
+  TokenBalanceMap,
+} from './state';
+import type { IStateDB } from './statedb';
+
+// =============================================================================
+// Common Interfaces
+// =============================================================================
+
+/** Logger interface for pipeline operations */
+export interface IPipelineLogger {
+  /** Logger methods accept any arguments for flexible logging */
+  debug: (message: string, ...args: unknown[]) => void;
+  info: (message: string, ...args: unknown[]) => void;
+  warn: (message: string, ...args: unknown[]) => void;
+  error: (message: string, ...args: unknown[]) => void;
+}
+
+/** Decoded transaction structure from protobuf */
+export interface IDecodedTransaction {
+  from: string;
+  delegator?: string;
+  chainId: string;
+  nonce: number;
+  serviceFee?: string;
+  pk: Uint8Array;
+  signature?: Uint8Array | string;
+  signatures?: IMultiSigData[];
+  /** Used during signature verification to hold processed signatures */
+  signaturesList?: Array<Omit<IMultiSigData, 'signature'>>;
+  itx: IAny;
+  /** Index signature for dynamic field access during verification */
+  [key: string]: unknown;
+}
+
+/** Multi-signature data structure for pipeline (decoded format, not proto) */
+export interface IMultiSigData {
+  signer: string;
+  delegator?: string;
+  pk: Uint8Array;
+  signature: Uint8Array;
+  data?: IAny;
+}
+
+/** Account update record */
+export interface IAccountUpdate {
+  address: string;
+  delta?: string;
+  token?: string;
+  action?: string;
+}
+
+/** Locked state for stake verification */
+export interface ILockedState {
+  address: string;
+  tokens: TokenBalanceMap;
+  assets: string[];
+}
+
+/** Input change tracking for token factory operations */
+export interface IInputChange {
+  address: string;
+  token?: string;
+  delta: string;
+}
+
+/** Validated inner transaction for delegation */
+export interface IValidatedItx {
+  opsList?: Array<{
+    typeUrl?: string;
+    limit?: {
+      tokensList?: Array<{
+        address?: string;
+        txCount?: number;
+        txAllowance?: string;
+        totalAllowance?: string;
+        validUntil?: number;
+        rate?: { interval?: number; anchor?: number } | null;
+      }>;
+      assetsList?: Array<{
+        address?: string[];
+        txCount?: number;
+        validUntil?: number;
+        rate?: { interval?: number; anchor?: number } | null;
+      }>;
+    };
+  }>;
+}
+
+/** Gas stake configuration */
+export interface IGasStake {
+  owner?: string;
+  stakeId?: string;
+  state?: IStakeState | null;
+  valid?: boolean;
+}
+
+/** Token condition for balance verification */
+export interface ITokenCondition {
+  owner: string;
+  tokens: Array<{ address: string; value: BN }>;
+}
+
+/** Output structure for transaction results */
+export interface IOutput {
+  owner: string;
+  tokens?: TTokenInput[];
+  assets?: string[];
+}
+
+/** Input structure for transaction */
+export interface IInput {
+  owner: string;
+  tokensList?: TTokenInput[];
+  assetsList?: string[];
+}
+
+// =============================================================================
+// Phase 1: Base Context
+// =============================================================================
+
+/**
+ * Phase 1: Initial input context
+ *
+ * This is the starting point of the pipeline. Contains only the required
+ * inputs provided by the caller before any processing begins.
+ *
+ * @template TItx - Inner transaction type (default: unknown)
+ */
+export interface IBaseContext<TItx = unknown> {
+  /** Base64 encoded transaction */
+  txBase64: string;
+  /** State database instance */
+  statedb: IStateDB;
+  /** Chain configuration */
+  config: IChainConfig;
+  /** Index database instance */
+  indexdb: IIndexDB;
+  /** Optional logger for pipeline operations */
+  logger?: IPipelineLogger;
+  /** Extra context data */
+  extra?: {
+    /** Gas stake headers from HTTP request */
+    gasStakeHeaders?: { token?: string; pk?: string };
+    /** HTTP request object - format varies by server framework */
+    request?: unknown;
+    /** Extension point for protocol-specific data */
+    [key: string]: unknown;
+  };
+
+  // Internal fields that may be set at any phase
+  /** Database transaction handle - type depends on StateDB implementation */
+  txn?: unknown;
+  /** State helper functions - set by execute.ts */
+  states?: unknown;
+  /** Event queue for indexdb updates */
+  events?: Array<{ table: string; name: string; data: unknown; ctx: Record<string, unknown> }>;
+
+  // Type hint for TItx (not used at runtime)
+  /** @internal Type parameter placeholder */
+  readonly __itxType?: TItx;
+
+  /** Index signature for IOperationContext compatibility and dynamic property access */
+  [key: string]: unknown;
+}
+
+// =============================================================================
+// Phase 1.5: Tx Only Context (intermediate state)
+// =============================================================================
+
+/**
+ * Intermediate context after DecodeTx but before DecodeItx
+ *
+ * At this phase, the outer transaction has been decoded but the inner
+ * transaction (itx) has not been extracted yet. Used by DecodeItx pipe.
+ *
+ * Added by: DecodeTx pipe
+ */
+export interface ITxOnlyContext extends IBaseContext {
+  /** Decoded transaction object (itx is still encoded as Any) */
+  tx: IDecodedTransaction;
+  /** Transaction hash (DID format) */
+  txHash: string;
+  /** Transaction timestamp (ISO 8601) */
+  txTime: string;
+  /** Transaction size in bytes */
+  txSize: number;
+  /** Whether to charge base gas */
+  txBaseGas: boolean;
+}
+
+// =============================================================================
+// Phase 2: Decoded Context
+// =============================================================================
+
+/**
+ * Phase 2: Context after DecodeTx + DecodeItx
+ *
+ * At this phase, the transaction has been decoded from base64 and the inner
+ * transaction (itx) has been extracted. The transaction can now be routed
+ * to the appropriate protocol handler.
+ *
+ * Added by: DecodeTx, DecodeItx pipes
+ *
+ * @template TItx - Inner transaction type
+ */
+export interface IDecodedContext<TItx = unknown> extends ITxOnlyContext {
+  /** Decoded inner transaction */
+  itx: TItx;
+  /** Transaction type URL (e.g., 'fg:t:transfer') */
+  txType: string;
+}
+
+// =============================================================================
+// Phase 3: Gas Context
+// =============================================================================
+
+/**
+ * Phase 3: Context after Gas calculation
+ *
+ * At this phase, states have been extracted (ExtractState) and gas/cost
+ * calculations are complete (EnsureTxGas, EnsureTxCost). The transaction
+ * fees have been calculated and sender updates prepared.
+ *
+ * Added by: ExtractState, EnsureTxGas, EnsureTxCost pipes
+ *
+ * @template TItx - Inner transaction type
+ */
+export interface IGasContext<TItx = unknown> extends IDecodedContext<TItx> {
+  /** Total gas consumed (set by EnsureGas pipe) */
+  totalGas?: BN;
+  /** Gas estimate breakdown (set by EnsureGas pipe) */
+  gasEstimate?: { create: number; update: number; payment?: number };
+  /** Receipts for balance changes */
+  receipts?: TTransactionReceipt[];
+
+  // Fee calculation results
+  /** Pending updates to apply to sender account */
+  senderUpdates?: Record<string, string>;
+  /** Function to update vault balances */
+  updateVaults?: () => Promise<void> | void;
+  /** Sender balance change record */
+  senderChange?: { address: string; token: string; delta: string } | null;
+
+  // Vault configuration (optional - depends on chain config)
+  /** Gas vault address */
+  gasVault?: string;
+  /** Fee vault address */
+  feeVault?: string;
+  /** Gas stake configuration */
+  gasStake?: IGasStake;
+  /** Fee vault change record */
+  feeVaultChange?: { address: string; value: string };
+  /** Gas vault change record */
+  gasVaultChange?: { address: string; value: string };
+
+  // Flags
+  /** Whether gas has been paid */
+  gasPaid?: boolean;
+  /** Whether using gas stake */
+  isGasStake?: boolean;
+
+  // Account updates (populated by updateVaults callback)
+  /** List of account updates applied */
+  updatedAccounts?: IAccountUpdate[];
+}
+
+// =============================================================================
+// Phase 4: Ready Context
+// =============================================================================
+
+/**
+ * Phase 4: Context ready for business logic execution
+ *
+ * At this phase, all preparation is complete:
+ * - Transaction decoded
+ * - States extracted
+ * - Gas calculated
+ * - State snapshot taken
+ *
+ * This is the input type for protocol-specific business logic pipes.
+ * Combine with Mixin interfaces to create protocol-specific context types.
+ *
+ * Added by: TakeStateSnapshot pipe
+ *
+ * @template TItx - Inner transaction type
+ *
+ * @example
+ * ```typescript
+ * // Define protocol-specific context
+ * type DelegateContext = IReadyContext<TDelegateTx>
+ *   & IWithSender
+ *   & IWithReceiver
+ *   & Partial<IWithDelegation>;
+ *
+ * // Use in business logic pipe
+ * runner.use(async (context: DelegateContext, next) => {
+ *   const { senderState, receiverState, delegationState } = context;
+ *   // ... business logic
+ * });
+ * ```
+ */
+export interface IReadyContext<TItx = unknown> extends IGasContext<TItx> {
+  // Vault states (extracted by TakeStateSnapshot if configured)
+  /** Fee vault account state */
+  feeVaultState?: IAccountState;
+  /** Gas vault account state */
+  gasVaultState?: IAccountState;
+}
+
+// =============================================================================
+// Phase 5: Executed Context
+// =============================================================================
+
+/**
+ * Phase 5: Context after business logic execution
+ *
+ * At this phase, the business logic has completed and all state
+ * modifications have been applied. Ready for final verification
+ * (VerifyStateDiff) and transaction persistence.
+ *
+ * @template TItx - Inner transaction type
+ */
+export interface IExecutedContext<TItx = unknown> extends IReadyContext<TItx> {
+  /** List of account updates applied - required at this phase */
+  updatedAccounts: IAccountUpdate[];
+}
+
+// =============================================================================
+// Mixin Interfaces: Account States
+// =============================================================================
+
+/** Mixin: Sender account state is required */
+export interface IWithSender {
+  senderState: IAccountState;
+}
+
+/** Mixin: Receiver account state is required */
+export interface IWithReceiver {
+  receiverState: IAccountState;
+}
+
+/** Mixin: Delegator account state is required */
+export interface IWithDelegator {
+  delegatorState: IAccountState;
+}
+
+/** Mixin: Multiple delegator account states are required */
+export interface IWithDelegators {
+  delegatorStates: IAccountState[];
+}
+
+/** Mixin: Owner account state is required */
+export interface IWithOwner {
+  ownerState: IAccountState;
+  ownerAddress: string;
+}
+
+/** Mixin: Issuer account state is required */
+export interface IWithIssuer {
+  issuerState: IAccountState;
+}
+
+/** Mixin: Multiple issuer account states are required */
+export interface IWithIssuers {
+  issuerStates: IAccountState[];
+}
+
+/** Mixin: Locker account state is required */
+export interface IWithLocker {
+  lockerState: IAccountState;
+  lockerAddress: string;
+}
+
+/** Mixin: Multiple signer states are required */
+export interface IWithSigners {
+  signerStates: IAccountState[];
+  signers: string[];
+}
+
+/** Mixin: Multiple receiver states are required */
+export interface IWithReceivers {
+  receiverStates: IAccountState[];
+  receivers: string[];
+}
+
+/** Mixin: Multiple sender states are required */
+export interface IWithSenders {
+  senderStates: IAccountState[];
+  senders: string[];
+}
+
+// =============================================================================
+// Mixin Interfaces: Protocol States
+// =============================================================================
+
+/** Mixin: Asset state is required */
+export interface IWithAsset {
+  assetState: IAssetState;
+}
+
+/** Mixin: Multiple asset states are required */
+export interface IWithAssets {
+  assetStates: IAssetState[];
+}
+
+/** Mixin: Token state is required */
+export interface IWithToken {
+  tokenState: ITokenState;
+  tokenAddress: string;
+}
+
+/** Mixin: Multiple token states are required */
+export interface IWithTokens {
+  tokenStates: ITokenState[];
+}
+
+/** Mixin: Asset factory state is required */
+export interface IWithFactory {
+  factoryState: IAssetFactoryState;
+}
+
+/** Mixin: Token factory state is required */
+export interface IWithTokenFactory {
+  tokenFactoryState: ITokenFactoryState;
+}
+
+/** Mixin: Stake state is required */
+export interface IWithStake {
+  stakeState: IStakeState;
+  stakeAddress: string;
+}
+
+/** Mixin: Multiple stake states are required */
+export interface IWithStakes {
+  stakeStates: IStakeState[];
+}
+
+/** Mixin: Delegation state is required */
+export interface IWithDelegation {
+  delegationState: IDelegateState;
+}
+
+/** Mixin: Rollup state is required */
+export interface IWithRollup {
+  rollupState: IRollupState;
+}
+
+/** Mixin: Rollup block state is required */
+export interface IWithRollupBlock {
+  rollupBlockState: IRollupState;
+  blockState: IRollupBlock;
+}
+
+/** Mixin: Evidence state is required */
+export interface IWithEvidence {
+  evidenceState: IEvidenceState;
+}
+
+/** Mixin: Locked state is required (for stake operations) */
+export interface IWithLocked {
+  lockedState: ILockedState;
+}
+
+/** FinalizedContext uses unknown for TItx as it represents any possible inner transaction type */
+export type FinalizedContext = IExecutedContext<unknown> &
+  IWithSender &
+  IWithSenders &
+  IWithSigners &
+  IWithReceiver &
+  IWithReceivers &
+  IWithDelegator &
+  IWithDelegators &
+  IWithOwner &
+  IWithIssuer &
+  IWithIssuers &
+  IWithLocker &
+  IWithDelegation &
+  IWithAsset &
+  IWithAssets &
+  IWithToken &
+  IWithTokens &
+  IWithFactory &
+  IWithTokenFactory &
+  IWithStake &
+  IWithStakes &
+  IWithRollup &
+  IWithRollupBlock &
+  IWithEvidence &
+  IWithLocked;