hyperstack_interpreter/
lib.rs

1//! # hyperstack-interpreter
2//!
3//! AST transformation runtime and VM for HyperStack streaming pipelines.
4//!
5//! This crate provides the core components for processing Solana blockchain
6//! events into typed state projections:
7//!
8//! - **AST Definition** - Type-safe schemas for state and event handlers
9//! - **Bytecode Compiler** - Compiles specs into optimized bytecode  
10//! - **Virtual Machine** - Executes bytecode to process events
11//! - **TypeScript Generation** - Generate client SDKs automatically
12//!
13//! ## Example
14//!
15//! ```rust,ignore
16//! use hyperstack_interpreter::{TypeScriptCompiler, TypeScriptConfig};
17//!
18//! let config = TypeScriptConfig::default();
19//! let compiler = TypeScriptCompiler::new(config);
20//! let typescript = compiler.compile(&spec)?;
21//! ```
22//!
23//! ## Feature Flags
24//!
25//! - `otel` - OpenTelemetry integration for distributed tracing and metrics
26
27pub mod ast;
28pub mod compiler;
29pub mod metrics_context;
30pub mod proto_router;
31pub mod resolvers;
32pub mod rust;
33pub mod spec_trait;
34pub mod typescript;
35pub mod vm;
36
37// Re-export commonly used items
38pub use metrics_context::{FieldAccessor, FieldRef, MetricsContext};
39pub use resolvers::{InstructionContext, KeyResolution, ResolveContext, ReverseLookupUpdater};
40pub use typescript::{write_typescript_to_file, TypeScriptCompiler, TypeScriptConfig};
41pub use vm::{
42    CapacityWarning, CleanupResult, PendingAccountUpdate, PendingQueueStats, QueuedAccountUpdate,
43    StateTableConfig, UpdateContext, VmMemoryStats,
44};
45
46// Re-export macros for convenient use
47// The field! macro is the new recommended way to create field references
48// The field_accessor! macro is kept for backward compatibility
49
50use serde::{Deserialize, Serialize};
51use serde_json::Value;
52
53#[derive(Debug, Clone, Serialize, Deserialize)]
54pub struct Mutation {
55    pub export: String,
56    pub key: Value,
57    pub patch: Value,
58}
59
60/// Generic wrapper for event data that includes context metadata
61/// This ensures type safety for events captured in entity specs
62///
63/// # Runtime Structure
64/// Events captured with `#[event]` are automatically wrapped in this structure:
65/// ```json
66/// {
67///   "timestamp": 1234567890,
68///   "data": { /* event-specific data */ },
69///   "slot": 381471241,
70///   "signature": "4xNEYTVL8DB28W87..."
71/// }
72/// ```
73#[derive(Debug, Clone, Serialize, Deserialize)]
74pub struct EventWrapper<T = Value> {
75    /// Unix timestamp when the event was processed
76    pub timestamp: i64,
77    /// The event-specific data
78    pub data: T,
79    /// Optional slot number from UpdateContext
80    #[serde(skip_serializing_if = "Option::is_none")]
81    pub slot: Option<u64>,
82    /// Optional transaction signature from UpdateContext
83    #[serde(skip_serializing_if = "Option::is_none")]
84    pub signature: Option<String>,
85}
86
87/// Generic wrapper for account capture data that includes context metadata
88/// This ensures type safety for accounts captured with `#[capture]` in entity specs
89///
90/// # Runtime Structure
91/// Accounts captured with `#[capture]` are automatically wrapped in this structure:
92/// ```json
93/// {
94///   "timestamp": 1234567890,
95///   "account_address": "C6P5CpJnYHgpGvCGuXYAWL6guKH5LApn3QwTAZmNUPCj",
96///   "data": { /* account-specific data (filtered, no __ fields) */ },
97///   "slot": 381471241,
98///   "signature": "4xNEYTVL8DB28W87..."
99/// }
100/// ```
101#[derive(Debug, Clone, Serialize, Deserialize)]
102pub struct CaptureWrapper<T = Value> {
103    /// Unix timestamp when the account was captured
104    pub timestamp: i64,
105    /// The account address (base58 encoded public key)
106    pub account_address: String,
107    /// The account data (already filtered to remove internal __ fields)
108    pub data: T,
109    /// Optional slot number from UpdateContext
110    #[serde(skip_serializing_if = "Option::is_none")]
111    pub slot: Option<u64>,
112    /// Optional transaction signature from UpdateContext
113    #[serde(skip_serializing_if = "Option::is_none")]
114    pub signature: Option<String>,
115}
hyperstack_interpreter/lib.rs

hyperstack_interpreter/
lib.rs
