hop_channels/

lib.rs

#![forbid(unsafe_code)]
//! Persistent state machines driven by HOP polynomial actions.

use std::io;

use hop_actions::{apply_action, Action, ActionError};
use hop_core::{CompanionMatrix, CoreError, Field, StreamGenerator};

#[cfg(feature = "torsor_masking")]
pub mod mask;
pub mod proj;
pub mod store;
pub mod store_fs;

use crate::proj::try_row0_of_poly;
use store::{ChannelSnapshot, ChannelStore};

/// Errors returned by checked channel operations.
#[derive(thiserror::Error, Debug)]
#[non_exhaustive]
pub enum ChannelError {
    /// The initial or projected vector has the wrong dimension.
    #[error("dimension mismatch: expected {expected}, got {actual}")]
    DimensionMismatch { expected: usize, actual: usize },
    /// An action violated the channel action contract.
    #[error("invalid action: {0}")]
    Action(#[from] ActionError),
    /// HOP Core rejected a checked state or transform operation.
    #[error("invalid channel algebra: {0}")]
    Core(#[from] CoreError),
    /// Persistent storage failed.
    #[error("channel storage failed: {0}")]
    Storage(#[from] io::Error),
    /// No snapshot existed for the requested channel.
    #[error("channel snapshot was not found")]
    SnapshotNotFound,
    /// The loaded snapshot belonged to a different channel identifier.
    #[error("snapshot channel identifier does not match requested identifier")]
    SnapshotIdMismatch,
    /// Applying another action would overflow the channel height.
    #[error("channel height exhausted")]
    HeightOverflow,
}

/// A persistent channel state machine.
pub struct Channel {
    id: [u8; 32],
    c: CompanionMatrix,
    state: Vec<Field>,
    height: u64,
    store: Option<Box<dyn ChannelStore>>,
}

/// Marker representing the producer side of a channel.
pub struct Producer;

/// A checked linear projection over channel states.
pub struct Subscriber {
    row0: Vec<Field>,
}

impl Channel {
    /// Opens a channel after checking that its initial state has the right size.
    pub fn try_open(
        c: CompanionMatrix,
        init: Vec<Field>,
        id: [u8; 32],
    ) -> Result<Self, ChannelError> {
        let expected = c.dimension();
        if init.len() != expected {
            return Err(ChannelError::DimensionMismatch {
                expected,
                actual: init.len(),
            });
        }
        Ok(Self {
            id,
            c,
            state: init,
            height: 0,
            store: None,
        })
    }

    /// Returns the channel identifier.
    pub const fn id(&self) -> &[u8; 32] {
        &self.id
    }

    /// Returns the immutable companion matrix defining this channel.
    pub const fn companion(&self) -> &CompanionMatrix {
        &self.c
    }

    /// Returns the current channel state.
    pub fn state(&self) -> &[Field] {
        &self.state
    }

    /// Returns the channel dimension.
    pub fn dimension(&self) -> usize {
        self.c.dimension()
    }

    /// Returns the number of committed actions.
    pub const fn height(&self) -> u64 {
        self.height
    }

    /// Returns whether this channel has a persistence backend attached.
    pub const fn has_store(&self) -> bool {
        self.store.is_some()
    }

    /// Attaches a persistence backend.
    pub fn with_store(mut self, store: Box<dyn ChannelStore>) -> Self {
        self.store = Some(store);
        self
    }

    /// Builds a complete channel snapshot.
    pub fn snapshot(&self) -> ChannelSnapshot {
        self.snapshot_with(&self.state, self.height)
    }

    /// Returns the producer-side marker for this channel.
    pub const fn producer(&self) -> Producer {
        Producer
    }

    /// Builds a checked subscriber projection from polynomial coefficients.
    pub fn try_subscribe_with_g(&self, g_coeffs: &[u64]) -> Result<Subscriber, ChannelError> {
        let action = Action {
            g_coeffs: g_coeffs.to_vec(),
            nonce: 0,
            mask_row0: None,
        };
        action.validate_for_dimension(self.dimension())?;
        Ok(Subscriber {
            row0: try_row0_of_poly(&self.c, g_coeffs)?,
        })
    }

    /// Applies and durably records one polynomial action.
    ///
    /// The action's optional mask is metadata for projection protocols; channel
    /// state evolution is defined solely by `state <- g(C) * state`.
    pub fn apply(&mut self, action: &Action) -> Result<(), ChannelError> {
        let next_state = apply_action(&self.c, &self.state, action)?;
        let next_height = self
            .height
            .checked_add(1)
            .ok_or(ChannelError::HeightOverflow)?;

        if let Some(store) = &self.store {
            store.append_action(&self.id, next_height, action)?;
        }

        self.state = next_state;
        self.height = next_height;

        Ok(())
    }

    /// Saves a checkpoint when a storage backend is attached.
    pub fn save_now(&self) -> Result<(), ChannelError> {
        if let Some(store) = &self.store {
            store.save(&self.snapshot())?;
        }
        Ok(())
    }

    /// Restores a checkpoint and replays actions after its height.
    pub fn restore(id: [u8; 32], store: Box<dyn ChannelStore>) -> Result<Self, ChannelError> {
        let snapshot = store.load(&id)?.ok_or(ChannelError::SnapshotNotFound)?;
        if snapshot.id != id {
            return Err(ChannelError::SnapshotIdMismatch);
        }
        let mut channel = Self::try_open(snapshot.c, snapshot.state, id)?;
        channel.height = snapshot.height;

        let actions = store.read_actions_from(&id, channel.height)?;
        for action in actions {
            channel.apply_without_persistence(&action)?;
        }
        channel.store = Some(store);
        Ok(channel)
    }

    fn snapshot_with(&self, state: &[Field], height: u64) -> ChannelSnapshot {
        ChannelSnapshot {
            id: self.id,
            c: self.c.clone(),
            state: state.to_vec(),
            height,
        }
    }

    fn apply_without_persistence(&mut self, action: &Action) -> Result<(), ChannelError> {
        let next_state = apply_action(&self.c, &self.state, action)?;
        let next_height = self
            .height
            .checked_add(1)
            .ok_or(ChannelError::HeightOverflow)?;
        self.state = next_state;
        self.height = next_height;
        Ok(())
    }
}

impl Subscriber {
    /// Returns the checked projection row.
    pub fn row(&self) -> &[Field] {
        &self.row0
    }

    /// Projects a dimension-matched state into one field element.
    pub fn project(&self, state: &[Field]) -> Result<Field, ChannelError> {
        if state.len() != self.row0.len() {
            return Err(ChannelError::DimensionMismatch {
                expected: self.row0.len(),
                actual: state.len(),
            });
        }
        Ok(self
            .row0
            .iter()
            .zip(state)
            .fold(Field::zero(), |sum, (weight, value)| {
                sum + (*weight * *value)
            }))
    }

    /// Generates `n` projected stream elements.
    pub fn stream(
        &self,
        mut stream: StreamGenerator,
        n: usize,
    ) -> Result<Vec<Field>, ChannelError> {
        let dimension = stream.dimension();
        if self.row0.len() != dimension {
            return Err(ChannelError::DimensionMismatch {
                expected: dimension,
                actual: self.row0.len(),
            });
        }
        let mut transform = vec![vec![Field::zero(); dimension]; dimension];
        transform[0] = self.row0.clone();
        stream.set_transform(transform)?;
        Ok((0..n).map(|_| stream.step()).collect())
    }
}

#[cfg(feature = "torsor_masking")]
impl Subscriber {
    /// Produces a twisted projection row `row * h(C)`.
    pub fn twisted_row(
        &self,
        c: &CompanionMatrix,
        nonce: u64,
        degree: usize,
    ) -> Result<Vec<Field>, crate::mask::MaskError> {
        crate::mask::try_apply_twist_row(c, &self.row0, nonce, degree)
    }
}