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 canonical_log;
29pub mod compiler;
30pub mod event_type_helpers;
31pub mod metrics_context;
32pub mod proto_router;
33pub mod resolvers;
34pub mod runtime_resolvers;
35pub mod runtime_resolvers_factory;
36pub mod rust;
37pub mod scheduler;
38pub mod slot_hash_cache;
39pub mod spec_trait;
40pub mod typescript;
41pub mod versioned;
42pub mod vm;
43pub mod vm_metrics;
44
45// Re-export slot hash cache functions
46pub use slot_hash_cache::{get_slot_hash, record_slot_hash};
47
48pub use canonical_log::{CanonicalLog, LogLevel};
49pub use metrics_context::{FieldAccessor, FieldRef, MetricsContext};
50pub use resolvers::{
51    InstructionContext, KeyResolution, ResolveContext, ReverseLookupUpdater, TokenMetadata,
52};
53pub use runtime_resolvers::{
54    InProcessResolver, ResolverApplyFuture, ResolverBatchFuture, ResolverBatchResult,
55    RuntimeResolver, RuntimeResolverBatchRequest, RuntimeResolverBatchResponse,
56    RuntimeResolverRequest, RuntimeResolverResponse, SharedRuntimeResolver,
57};
58pub use typescript::{write_typescript_to_file, TypeScriptCompiler, TypeScriptConfig};
59pub use vm::{
60    CapacityWarning, CleanupResult, DirtyTracker, FieldChange, PendingAccountUpdate,
61    PendingQueueStats, QueuedAccountUpdate, ResolverRequest, ResolverTarget, ScheduledCallback,
62    StateTableConfig, UpdateContext, VmMemoryStats,
63};
64
65// Re-export macros for convenient use
66// The field! macro is the new recommended way to create field references
67// The field_accessor! macro is kept for backward compatibility
68
69use serde::{Deserialize, Serialize};
70use serde_json::Value;
71
72#[derive(Debug, Clone, Serialize, Deserialize)]
73pub struct Mutation {
74    pub export: String,
75    pub key: Value,
76    pub patch: Value,
77    #[serde(skip_serializing_if = "Vec::is_empty", default)]
78    pub append: Vec<String>,
79}
80
81/// Generic wrapper for event data that includes context metadata
82/// This ensures type safety for events captured in entity specs
83///
84/// # Runtime Structure
85/// Events captured with `#[event]` are automatically wrapped in this structure:
86/// ```json
87/// {
88///   "timestamp": 1234567890,
89///   "data": { /* event-specific data */ },
90///   "slot": 381471241,
91///   "signature": "4xNEYTVL8DB28W87..."
92/// }
93/// ```
94#[derive(Debug, Clone, Serialize, Deserialize)]
95pub struct EventWrapper<T = Value> {
96    /// Unix timestamp when the event was processed
97    pub timestamp: i64,
98    /// The event-specific data
99    pub data: T,
100    /// Optional slot number from UpdateContext
101    #[serde(skip_serializing_if = "Option::is_none")]
102    pub slot: Option<u64>,
103    /// Optional transaction signature from UpdateContext
104    #[serde(skip_serializing_if = "Option::is_none")]
105    pub signature: Option<String>,
106}
107
108/// Generic wrapper for account capture data that includes context metadata
109/// This ensures type safety for accounts captured with `#[capture]` in entity specs
110///
111/// # Runtime Structure
112/// Accounts captured with `#[capture]` are automatically wrapped in this structure:
113/// ```json
114/// {
115///   "timestamp": 1234567890,
116///   "account_address": "C6P5CpJnYHgpGvCGuXYAWL6guKH5LApn3QwTAZmNUPCj",
117///   "data": { /* account-specific data (filtered, no __ fields) */ },
118///   "slot": 381471241,
119///   "signature": "4xNEYTVL8DB28W87..."
120/// }
121/// ```
122#[derive(Debug, Clone, Serialize, Deserialize)]
123pub struct CaptureWrapper<T = Value> {
124    /// Unix timestamp when the account was captured
125    pub timestamp: i64,
126    /// The account address (base58 encoded public key)
127    pub account_address: String,
128    /// The account data (already filtered to remove internal __ fields)
129    pub data: T,
130    /// Optional slot number from UpdateContext
131    #[serde(skip_serializing_if = "Option::is_none")]
132    pub slot: Option<u64>,
133    /// Optional transaction signature from UpdateContext
134    #[serde(skip_serializing_if = "Option::is_none")]
135    pub signature: Option<String>,
136}
hyperstack_interpreter/lib.rs

hyperstack_interpreter/
lib.rs
