arete_interpreter/
lib.rs

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

arete_interpreter/
lib.rs
