trident/runtime/
mod.rs

1//! Runtime traits for VM execution, proving, and deployment.
2//!
3//! Trident is the weapon. Warriors wield it. Trident defines these
4//! traits; warriors implement them. A warrior is a target-specific
5//! tool (separate crate) that takes compiled Trident output and
6//! handles execution, proving, and deployment for a particular
7//! VM+OS combination.
8//!
9//! Example: **Trisha** (Triton + Neptune warrior) implements `Runner`
10//! via `triton_vm::simulate()`, `Prover` via `triton_vm::prove()`,
11//! and `Deployer` via Neptune RPC — all using Trident's `PrimeField`,
12//! `Poseidon2`, and `Claim` primitives from `crate::field`.
13//!
14//! No heavy dependencies here — only the interface contract and
15//! the serializable `ProgramBundle` artifact format.
16
17pub mod artifact;
18
19use crate::field::proof::Claim;
20pub use artifact::ProgramBundle;
21
22// ─── Types ─────────────────────────────────────────────────────────
23
24/// VM execution result.
25#[derive(Clone, Debug)]
26pub struct ExecutionResult {
27    /// Output field elements (from `write_io` instructions).
28    pub output: Vec<u64>,
29    /// Number of VM cycles consumed.
30    pub cycle_count: u64,
31}
32
33/// Proof artifact: claim + opaque proof bytes.
34///
35/// The `claim` is universal (defined in `field::proof`). The
36/// `proof_bytes` are warrior-specific — their format depends on
37/// the proving system (STARK, SNARK, etc.).
38#[derive(Clone, Debug)]
39pub struct ProofData {
40    /// What the proof asserts (program hash, input, output).
41    pub claim: Claim,
42    /// Serialized proof (format is warrior-specific).
43    pub proof_bytes: Vec<u8>,
44    /// Proof system identifier (e.g. "stark-triton-v2", "groth16-bn254").
45    pub format: String,
46}
47
48/// Input specification for program execution.
49#[derive(Clone, Debug, Default)]
50pub struct ProgramInput {
51    /// Public input field elements (read via `read_io`).
52    pub public: Vec<u64>,
53    /// Secret/divine input field elements (read via `divine`).
54    pub secret: Vec<u64>,
55    /// Nondeterministic digests for `merkle_step` (each is 5 field elements).
56    pub digests: Vec<[u64; 5]>,
57}
58
59// ─── Warrior Traits ────────────────────────────────────────────────
60
61/// Run a compiled program on a VM.
62///
63/// Warriors implement this to execute TASM (or other target assembly)
64/// using the actual VM runtime.
65pub trait Runner {
66    /// Execute the program with the given inputs, returning output
67    /// values and cycle count.
68    fn run(&self, bundle: &ProgramBundle, input: &ProgramInput) -> Result<ExecutionResult, String>;
69}
70
71/// Generate a proof of correct execution.
72///
73/// Warriors implement this to produce a cryptographic proof that the
74/// program executed correctly on the given inputs.
75pub trait Prover {
76    /// Execute and prove, returning the proof artifact.
77    fn prove(&self, bundle: &ProgramBundle, input: &ProgramInput) -> Result<ProofData, String>;
78}
79
80/// Verify a proof against its claim.
81///
82/// Warriors implement this to check that a proof is valid for its
83/// claimed program, input, and output.
84pub trait Verifier {
85    /// Returns true if the proof is valid.
86    fn verify(&self, proof: &ProofData) -> Result<bool, String>;
87}
88
89/// Search for a nonce that satisfies a difficulty target.
90///
91/// Warriors implement this to find a nonce such that
92/// `hash(message ++ nonce) < target`. Used for proof-of-work
93/// mining and computational puzzles.
94pub trait Guesser {
95    /// Search for a valid nonce. Returns the nonce, digest, and
96    /// number of attempts if found within `max_attempts`.
97    fn guess(
98        &self,
99        bundle: &ProgramBundle,
100        input: &ProgramInput,
101        difficulty: u64,
102        max_attempts: u64,
103    ) -> Result<GuessResult, String>;
104}
105
106/// Result of a successful nonce search.
107#[derive(Clone, Debug)]
108pub struct GuessResult {
109    /// The winning nonce value.
110    pub nonce: u64,
111    /// The resulting digest elements.
112    pub digest: Vec<u64>,
113    /// Total nonces attempted before finding the solution.
114    pub attempts: u64,
115}
116
117/// Deploy a program to a chain or runtime.
118///
119/// Warriors implement this for chain-specific deployment (e.g.,
120/// constructing Neptune LockScript/TypeScript, broadcasting
121/// transactions via RPC).
122pub trait Deployer {
123    /// Deploy the program, optionally with a proof.
124    /// Returns a deployment identifier (tx hash, contract address, etc.).
125    fn deploy(&self, bundle: &ProgramBundle, proof: Option<&ProofData>) -> Result<String, String>;
126}
trident/runtime/mod.rs

trident/runtime/
mod.rs
