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 spec_trait;
33pub mod typescript;
34pub mod vm;
35
36// Re-export commonly used items
37pub use typescript::{TypeScriptCompiler, TypeScriptConfig, write_typescript_to_file};
38pub use resolvers::{ResolveContext, InstructionContext, KeyResolution, ReverseLookupUpdater};
39pub use vm::{PendingAccountUpdate, PendingQueueStats, UpdateContext};
40pub use metrics_context::{MetricsContext, FieldAccessor, FieldRef};
41
42// Re-export macros for convenient use
43// The field! macro is the new recommended way to create field references
44// The field_accessor! macro is kept for backward compatibility
45
46use serde::{Deserialize, Serialize};
47use serde_json::Value;
48
49#[derive(Debug, Clone, Serialize, Deserialize)]
50pub struct Mutation {
51    pub export: String,
52    pub key: Value,
53    pub patch: Value,
54}
55
56/// Generic wrapper for event data that includes context metadata
57/// This ensures type safety for events captured in entity specs
58/// 
59/// # Runtime Structure
60/// Events captured with `#[event]` are automatically wrapped in this structure:
61/// ```json
62/// {
63///   "timestamp": 1234567890,
64///   "data": { /* event-specific data */ },
65///   "slot": 381471241,
66///   "signature": "4xNEYTVL8DB28W87..."
67/// }
68/// ```
69#[derive(Debug, Clone, Serialize, Deserialize)]
70pub struct EventWrapper<T = Value> {
71    /// Unix timestamp when the event was processed
72    pub timestamp: i64,
73    /// The event-specific data
74    pub data: T,
75    /// Optional slot number from UpdateContext
76    #[serde(skip_serializing_if = "Option::is_none")]
77    pub slot: Option<u64>,
78    /// Optional transaction signature from UpdateContext
79    #[serde(skip_serializing_if = "Option::is_none")]
80    pub signature: Option<String>,
81}
82
83/// Generic wrapper for account capture data that includes context metadata
84/// This ensures type safety for accounts captured with `#[capture]` in entity specs
85/// 
86/// # Runtime Structure
87/// Accounts captured with `#[capture]` are automatically wrapped in this structure:
88/// ```json
89/// {
90///   "timestamp": 1234567890,
91///   "account_address": "C6P5CpJnYHgpGvCGuXYAWL6guKH5LApn3QwTAZmNUPCj",
92///   "data": { /* account-specific data (filtered, no __ fields) */ },
93///   "slot": 381471241,
94///   "signature": "4xNEYTVL8DB28W87..."
95/// }
96/// ```
97#[derive(Debug, Clone, Serialize, Deserialize)]
98pub struct CaptureWrapper<T = Value> {
99    /// Unix timestamp when the account was captured
100    pub timestamp: i64,
101    /// The account address (base58 encoded public key)
102    pub account_address: String,
103    /// The account data (already filtered to remove internal __ fields)
104    pub data: T,
105    /// Optional slot number from UpdateContext
106    #[serde(skip_serializing_if = "Option::is_none")]
107    pub slot: Option<u64>,
108    /// Optional transaction signature from UpdateContext
109    #[serde(skip_serializing_if = "Option::is_none")]
110    pub signature: Option<String>,
111}
hyperstack_interpreter/lib.rs

hyperstack_interpreter/
lib.rs
