@ocap/types 1.28.9 → 1.29.0

package/interfaces/state.ts

@@ -0,0 +1,327 @@
+// core/types/interfaces/state.ts
+// State interfaces that extend Proto T*State types for local storage format
+
+import type {
+  TAccountState,
+  TAssetFactoryState,
+  TAssetState,
+  TDelegateState,
+  TEvidenceState,
+  TRollupBlock,
+  TRollupState,
+  TStakeState,
+  TTokenFactoryState,
+  TTokenState,
+} from '../lib/state_pb';
+import type { TCreateAssetTx } from '../lib/tx_pb';
+import type {
+  TAssetFactoryHook,
+  TIndexedFactoryInput,
+  TNFTDisplay,
+  TNFTEndpoint,
+  TStateContext,
+  TVariableInput,
+} from '../lib/type_pb';
+
+/** Storage format with ISO 8601 string timestamps */
+export interface IStateContext extends Omit<TStateContext, 'genesisTime' | 'renaissanceTime'> {
+  genesisTime: string;
+  renaissanceTime: string;
+}
+
+export interface IStateContextInput {
+  txHash?: string;
+  txTime?: string;
+}
+
+export interface IState {
+  address: string;
+  context?: IStateContext;
+  /** Protobuf google.protobuf.Any - structure varies by state type */
+  data?: unknown;
+}
+
+export interface IStateWithOwner extends IState {
+  owner: string;
+  issuer: string;
+}
+
+export type StateChangeType = 'create' | 'update' | 'delete';
+
+/** State kind for change events - named to avoid conflict with StateType enum from enum_pb */
+export type StateKind =
+  | 'account'
+  | 'asset'
+  | 'token'
+  | 'token-factory'
+  | 'asset-factory'
+  | 'stake'
+  | 'delegation'
+  | 'rollup'
+  | 'rollup-block'
+  | 'evidence';
+
+export interface IStateChangeEvent<T extends IState = IState> {
+  type: StateChangeType;
+  stateType: StateKind;
+  address: string;
+  before?: T;
+  after?: T;
+}
+
+// ============ Extended State Interfaces ============
+
+/** Token balance map: tokenAddress -> amount */
+export type TokenBalanceMap = Record<string, string>;
+
+/** tokens: Record instead of Array<TIndexedTokenInput>, nonce: number instead of string */
+export interface IAccountState
+  extends Omit<
+    TAccountState,
+    'tokens' | 'nonce' | 'context' | 'balance' | 'gasBalance' | 'type' | 'numTxs' | 'numAssets' | 'data'
+  > {
+  tokens: TokenBalanceMap;
+  nonce: number;
+  context: IStateContext;
+  /** Protobuf google.protobuf.Any - structure varies by account type */
+  data?: unknown;
+}
+
+/** consumedTime: string (ISO 8601), endpoint/display with proper types */
+export interface IAssetState extends Omit<TAssetState, 'consumedTime' | 'endpoint' | 'display' | 'context' | 'data'> {
+  consumedTime: string;
+  /** NFT endpoint - simplified to string (endpoint.id) in storage, or full object */
+  endpoint?: string | TNFTEndpoint | null;
+  /** NFT display metadata */
+  display?: TNFTDisplay | null;
+  context: IStateContext;
+  /** Protobuf google.protobuf.Any - application-specific asset data */
+  data?: unknown;
+}
+
+export interface IForeignToken {
+  contractAddress: string;
+  [key: string]: unknown;
+}
+
+export interface ITokenMetadata {
+  type: 'json';
+  value?: {
+    communityUrl?: string | null;
+    issuer: string;
+  };
+}
+
+/** foreignToken/metadata simplified, optional fields with null support */
+export interface ITokenState
+  extends Omit<
+    TTokenState,
+    | 'foreignToken'
+    | 'metadata'
+    | 'context'
+    | 'data'
+    | 'icon'
+    | 'maxTotalSupply'
+    | 'issuer'
+    | 'website'
+    | 'tokenFactoryAddress'
+    | 'spenders'
+    | 'minters'
+    | 'type'
+  > {
+  foreignToken?: IForeignToken | null;
+  metadata?: ITokenMetadata | null;
+  icon?: string | null;
+  maxTotalSupply?: string | null;
+  issuer?: string | null;
+  website?: string | null;
+  tokenFactoryAddress?: string | null;
+  spenders?: string[] | null;
+  minters?: string[] | null;
+  type?: 'Token' | 'CreditToken' | 'BondingCurveToken' | null;
+  context: IStateContext;
+  /** Protobuf google.protobuf.Any - structure varies by token type */
+  data?: unknown;
+}
+
+/** Extends TAssetFactoryHook with compiled field for contract hooks */
+export interface IFactoryHook extends TAssetFactoryHook {
+  /** Compiled contract calls when type is 'contract' - structure varies by call type */
+  compiled?: unknown[];
+}
+
+/** Factory input - extends TIndexedFactoryInput, tokens simplified to address+value */
+export interface IFactoryInput extends Omit<TIndexedFactoryInput, 'tokens' | 'variables'> {
+  /** Additional token requirements (without decimal/unit/symbol metadata) */
+  tokens?: Array<{ address: string; value: string }>;
+  /** Variable definitions (description optional in storage) */
+  variables?: Array<Omit<TVariableInput, 'value' | 'description'> & { description?: string }>;
+}
+
+/** tokens: Record, hooks: IFactoryHook[], lastSettlement: string (ISO 8601) */
+export interface IAssetFactoryState
+  extends Omit<
+    TAssetFactoryState,
+    | 'tokens'
+    | 'hooks'
+    | 'lastSettlement'
+    | 'input'
+    | 'output'
+    | 'display'
+    | 'context'
+    | 'data'
+    | 'balance'
+    | 'settlement'
+    | 'limit'
+  > {
+  tokens: TokenBalanceMap;
+  hooks?: IFactoryHook[];
+  lastSettlement: string;
+  /** Factory input - tokens/assets required to mint */
+  input?: IFactoryInput;
+  /** Factory output template for minted assets */
+  output?: TCreateAssetTx;
+  /** Display metadata for the factory itself */
+  display?: TNFTDisplay | null;
+  /** Settlement mode: 'instant' settles immediately, 'periodic' batches settlements */
+  settlement?: 'instant' | 'periodic';
+  /** Max number of assets that can be minted, 0 means unlimited */
+  limit?: number;
+  context: IStateContext;
+  /** Protobuf google.protobuf.Any - application-specific data */
+  data?: unknown;
+}
+
+/** tokens/revokedTokens: Record instead of Array */
+export interface IStakeState extends Omit<TStakeState, 'tokens' | 'revokedTokens' | 'context' | 'data'> {
+  tokens: TokenBalanceMap;
+  revokedTokens: TokenBalanceMap;
+  context: IStateContext;
+  /** Protobuf google.protobuf.Any - structure varies by stake type */
+  data?: unknown;
+}
+
+/** Token limit in delegation ops */
+export interface IDelegationTokenLimit {
+  address: string;
+  toList?: string[];
+  txCount?: number;
+  txAllowance?: string;
+  totalAllowance?: string;
+  validUntil?: number;
+  rate?: { interval: number; anchor?: number } | null;
+  txSent?: number;
+  lastTx?: number;
+  spentAllowance?: string;
+}
+
+/** Asset limit in delegation ops */
+export interface IDelegationAssetLimit {
+  address?: string[];
+  toList?: string[];
+  txCount?: number;
+  validUntil?: number;
+  rate?: { interval: number; anchor?: number } | null;
+  txSent?: number;
+  lastTx?: number;
+}
+
+/** Operation limit in delegation */
+export interface IDelegationOpLimit {
+  tokens?: IDelegationTokenLimit[];
+  assets?: IDelegationAssetLimit[];
+}
+
+/** Delegation ops: typeUrl -> operation with limits */
+export type IDelegationOps = Record<string, { limit: IDelegationOpLimit }>;
+
+/** ops: IDelegationOps instead of opsMap */
+export interface IDelegateState extends Omit<TDelegateState, 'opsMap' | 'context' | 'data'> {
+  ops?: IDelegationOps | null;
+  context: IStateContext;
+  /** Protobuf google.protobuf.Any - structure varies by delegation type */
+  data?: unknown;
+}
+
+export interface IRollupValidator {
+  pk: string;
+  address: string;
+  endpoint: string;
+}
+
+/** validators: IRollupValidator[], optional fields with null support */
+export interface IRollupState
+  extends Omit<
+    TRollupState,
+    | 'seedValidators'
+    | 'validators'
+    | 'context'
+    | 'data'
+    | 'vaultAddress'
+    | 'blockHash'
+    | 'issuer'
+    | 'tokenInfo'
+    | 'totalDepositAmount'
+    | 'totalWithdrawAmount'
+    | 'foreignToken'
+  > {
+  seedValidators: IRollupValidator[];
+  validators: IRollupValidator[];
+  vaultAddress?: string | null;
+  blockHash?: string | null;
+  issuer?: string | null;
+  context: IStateContext;
+  /** Protobuf google.protobuf.Any - structure varies by rollup type */
+  data?: unknown;
+}
+
+/** Signature data for rollup blocks */
+export interface IBlockSignature {
+  signer: string;
+  pk?: string | Uint8Array;
+  signature?: string | Uint8Array;
+}
+
+/** address: alias for hash (StateDB key), signatures: IBlockSignature[] */
+export interface IRollupBlock
+  extends Omit<
+    TRollupBlock,
+    'signatures' | 'context' | 'data' | 'previousHash' | 'mintedAmount' | 'burnedAmount' | 'rewardAmount'
+  > {
+  address: string;
+  signatures: IBlockSignature[];
+  previousHash?: string | null;
+  mintedAmount?: string | null;
+  burnedAmount?: string | null;
+  rewardAmount?: string | null;
+  context: IStateContext;
+  /** Protobuf google.protobuf.Any - structure varies by block type */
+  data?: unknown;
+}
+
+/** address: alias for hash (StateDB key) */
+export interface IEvidenceState extends Omit<TEvidenceState, 'context' | 'data'> {
+  address: string;
+  context: IStateContext;
+  /** Protobuf google.protobuf.Any - structure varies by evidence type */
+  data?: unknown;
+}
+
+export interface ITokenFactoryCurve {
+  type: 'linear' | 'constant' | 'quadratic';
+  basePrice?: string;
+  slope?: string;
+  fixedPrice?: string;
+  constant?: number;
+}
+
+/** owner instead of ownerAddress, status: string instead of enum */
+export interface ITokenFactoryState
+  extends Omit<TTokenFactoryState, 'ownerAddress' | 'status' | 'curve' | 'context' | 'token' | 'reserveToken'> {
+  owner: string;
+  status: 'ACTIVE' | 'PAUSED';
+  curve?: ITokenFactoryCurve | null;
+  context: IStateContext;
+  /** Protobuf google.protobuf.Any - structure varies by token factory type */
+  data?: unknown;
+}

package/interfaces/statedb.ts

@@ -0,0 +1,193 @@
+// core/types/interfaces/statedb.ts
+
+import type { EventEmitter } from 'node:events';
+
+import type { TTransactionReceipt } from '../lib/type_pb';
+import type { Promisable } from './base';
+import type {
+  IAccountState,
+  IAssetFactoryState,
+  IAssetState,
+  IDelegateState,
+  IEvidenceState,
+  IRollupBlock,
+  IRollupState,
+  IStakeState,
+  IStateContext,
+  ITokenFactoryState,
+  ITokenState,
+} from './state';
+
+/** Hook function type - args can be any type depending on hook trigger */
+export type HookFunction = (...args: unknown[]) => void;
+
+/** Operation context - index signature allows for protocol-specific context data */
+export interface IOperationContext {
+  [key: string]: unknown;
+}
+
+/** Chain token configuration stored in chain state */
+export interface IChainTokenInfo {
+  symbol?: string;
+  decimal?: number;
+  name?: string;
+  description?: string;
+  unit?: string;
+  totalSupply?: string;
+  initialSupply?: string;
+  address?: string;
+  foreignToken?: { contractAddress?: string; chainId?: number } | null;
+}
+
+export interface IChainState {
+  address: string;
+  chainId: string;
+  version?: string;
+  accounts?: Array<{ address: string; pk?: string; balance?: number; moniker?: string }>;
+  moderator?: { address: string; pk?: string };
+  token?: IChainTokenInfo;
+  transaction?: Record<string, unknown>;
+  vaults?: { txGas?: string[]; txFee?: string[] };
+  context?: IStateContext;
+}
+
+/** Transaction data stored in tx state */
+export interface ITxData {
+  chainId?: string;
+  delegator?: string;
+  from?: string;
+  nonce?: number;
+  serviceFee?: string;
+  gasFee?: string;
+  gasPaid?: string;
+  pk?: string;
+  signature?: string;
+  signatures?: Array<{ signer?: string; delegator?: string; pk?: string; signature?: string }>;
+  itx?: { __typename?: string; typeUrl?: string };
+  itxJson?: Record<string, unknown>;
+  /** Extra transaction data - format varies by transaction source */
+  extra?: unknown;
+}
+
+export interface ITxState {
+  hash: string;
+  code?: string;
+  height?: number;
+  index?: number;
+  receipts?: TTransactionReceipt[];
+  receiptsVerified?: boolean;
+  receiver?: string;
+  sender?: string;
+  time?: string;
+  tx?: ITxData;
+  type?: string;
+  finalized?: boolean;
+  valid?: boolean;
+}
+
+export interface IBalanceState {
+  address: string;
+  tokenAddress: string;
+  balance: string;
+  context?: IStateContext;
+}
+
+export type StateEventHandler<T> = (state: T, ctx?: IOperationContext) => void | Promise<void>;
+
+export interface IStateTable<T = unknown> {
+  name: string;
+  primaryKey: string;
+  uniqIndex?: string | string[];
+
+  create(id: string, attrs: Partial<T>, context?: IOperationContext): Promisable<T>;
+  get(id: string, context?: IOperationContext): Promisable<T | null>;
+  update(id: string, updates: Partial<T>, context?: IOperationContext): Promisable<T>;
+  updateOrCreate(exist: T | null, state: Partial<T>, context?: IOperationContext): Promisable<T>;
+  history(id: string, context?: IOperationContext): Promisable<T[]>;
+  reset(context?: IOperationContext): Promisable<void>;
+
+  pre(name: string, fn: HookFunction): void;
+  post(name: string, fn: HookFunction): void;
+  on(event: 'create' | 'update', handler: StateEventHandler<T>): void;
+  emit(event: 'create' | 'update', state: T, ctx?: IOperationContext): void;
+
+  generatePrimaryKey(doc: string | Record<string, unknown>): string;
+  updateCache(data: Record<string, unknown>, context: IOperationContext | null | undefined): void;
+  getCache(key: string | Record<string, unknown>, context: IOperationContext): T | null;
+
+  markReady(): void;
+  onReady(cb: () => void): void;
+}
+
+export interface IBalanceTable extends IStateTable<IBalanceState> {
+  getBalance(address: string, context?: IOperationContext): Promisable<Record<string, string>>;
+  updateBalance(
+    params: { address: string; tokens: Record<string, string>; context?: IOperationContext },
+    context?: IOperationContext
+  ): Promisable<Record<string, string>>;
+}
+
+export interface ITokenTable extends IStateTable<ITokenState> {
+  existBySymbol(symbol: string, context?: IOperationContext): Promisable<boolean>;
+}
+
+export interface IRollupTable extends IStateTable<IRollupState> {
+  existByToken(token: string, context?: IOperationContext): Promisable<boolean>;
+}
+
+export interface IReady extends EventEmitter {
+  ready: boolean;
+  readyCallbacks: Array<() => void>;
+  readyMarks: Record<string, boolean>;
+  markReady(mark?: string): void;
+  onReady(cb: () => void): void;
+}
+
+/** Table names available in IStateDB */
+export type StateDBTableName =
+  | 'chain'
+  | 'account'
+  | 'asset'
+  | 'token'
+  | 'tx'
+  | 'factory'
+  | 'tokenFactory'
+  | 'stake'
+  | 'delegation'
+  | 'rollup'
+  | 'rollupBlock'
+  | 'evidence'
+  | 'balance';
+
+export interface IStateDB extends IReady {
+  name: string;
+  version?: string;
+  tables: readonly string[];
+  readyListenersAttached: boolean;
+
+  attachReadyListeners(): void;
+
+  chain: IStateTable<IChainState>;
+  account: IStateTable<IAccountState>;
+  asset: IStateTable<IAssetState>;
+  token: ITokenTable;
+  tx: IStateTable<ITxState>;
+
+  factory: IStateTable<IAssetFactoryState>;
+  tokenFactory: IStateTable<ITokenFactoryState>;
+
+  stake: IStateTable<IStakeState>;
+  delegation: IStateTable<IDelegateState>;
+
+  rollup: IRollupTable;
+  rollupBlock: IStateTable<IRollupBlock>;
+
+  evidence: IStateTable<IEvidenceState>;
+  balance: IBalanceTable;
+
+  /** Run function within a database transaction - txn type depends on StateDB implementation (dolt, fs, memory) */
+  runAsLambda?<T>(fn: (txn: unknown) => T | Promise<T>, options?: Record<string, unknown>): Promise<T>;
+
+  /** Get table by name - use this for dynamic table access */
+  getTable?(name: StateDBTableName): IStateTable<unknown>;
+}

package/interfaces/testing.ts

@@ -0,0 +1,122 @@
+// core/types/interfaces/testing.ts
+// Utility types for testing purposes
+
+import type { DeepPartial } from './base';
+import type { IChainConfig } from './config';
+import type { IReadyContext } from './pipeline';
+import type { IAccountState, IAssetState, IDelegateState, IStakeState, ITokenState } from './state';
+import type { IStateDB, ITxState } from './statedb';
+
+// ============ Error Types ============
+
+/**
+ * Custom error interface with code property for pipeline errors
+ * Compatible with @ocap/util CustomError
+ */
+export interface ITestError extends Error {
+  code?: string;
+}
+
+/**
+ * Next callback type for pipe functions
+ */
+export type PipeNextFn = (err?: ITestError) => void;
+
+// ============ Context Types ============
+
+/**
+ * Partial transaction context for test setup
+ * Allows creating context objects with only the fields needed for a specific test
+ * Uses IReadyContext as the base which includes all phase fields
+ */
+export type PartialTransactionContext<TItx = unknown> = DeepPartial<IReadyContext<TItx>>;
+
+/**
+ * Mock StateDB type for testing
+ * All methods are optional to allow partial mocking
+ */
+export type MockStateDB = Partial<IStateDB>;
+
+/**
+ * Mock ChainConfig for testing
+ * All fields are optional
+ */
+export type MockChainConfig = DeepPartial<IChainConfig>;
+
+// ============ State Types ============
+
+/**
+ * Mock account state for testing
+ */
+export type MockAccountState = DeepPartial<IAccountState>;
+
+/**
+ * Mock asset state for testing
+ */
+export type MockAssetState = DeepPartial<IAssetState>;
+
+/**
+ * Mock token state for testing
+ */
+export type MockTokenState = DeepPartial<ITokenState>;
+
+/**
+ * Mock stake state for testing
+ */
+export type MockStakeState = DeepPartial<IStakeState>;
+
+/**
+ * Mock delegate state for testing
+ */
+export type MockDelegateState = DeepPartial<IDelegateState>;
+
+/**
+ * Mock tx state for testing
+ */
+export type MockTxState = DeepPartial<ITxState>;
+
+// ============ Full Test Context ============
+
+/**
+ * Create a type-safe partial context for testing
+ * Usage: const ctx = createTestContext<MyItxType>({ senderState: mockState });
+ */
+export type TestContext<TItx = unknown> = PartialTransactionContext<TItx> & {
+  // Ensure required base fields are present
+  txBase64: string;
+  statedb: MockStateDB;
+  config: MockChainConfig;
+};
+
+// ============ Pipe Function Types ============
+
+/**
+ * Helper type for mocking pipe functions in tests
+ */
+export type MockPipeFunction<TContext = unknown> = (context: TContext, next: PipeNextFn) => void | Promise<void>;
+
+/**
+ * Helper type for mocking error pipe functions in tests
+ */
+export type MockErrorPipeFunction<TContext = unknown> = (
+  err: ITestError,
+  context: TContext,
+  next: PipeNextFn
+) => void | Promise<void>;
+
+// ============ Test Result Types ============
+
+/**
+ * Result type for executeTx helper in protocol tests
+ */
+export interface IExecuteResult {
+  err?: Error | null;
+  txHash?: string;
+}
+
+/**
+ * Pipe test result with optional error
+ */
+export interface IPipeTestResult {
+  err?: ITestError;
+}

package/lib/enum_pb.d.ts

@@ -1,8 +1,6 @@
 // package: ocap
 // file: enum.proto
 
-import * as jspb from "google-protobuf";
-
 export interface StatusCodeMap {
   OK: 0;
   INVALID_NONCE: 1;
@@ -195,4 +193,3 @@ export interface ProtocolStatusMap {
 }
 
 export const ProtocolStatus: ProtocolStatusMap;
-