sigil-storage · traits

pub type KeyValuePair = (Vec<u8>, Vec<u8>);

pub trait BlockStore: Send + Sync {
    /// Store a finalized block. Returns an error if a block at the same height
    /// already exists (blocks are append-only).
    fn put_block(&self, block: &Block) -> Result<(), StorageError>;

    /// Retrieve a block by its height, returning `None` if no block exists at
    /// that height.
    fn get_block_by_height(&self, height: u64) -> Result<Option<Block>, StorageError>;

    /// Retrieve a block by its header hash.
    fn get_block_by_hash(&self, hash: &SigilHash) -> Result<Option<Block>, StorageError>;

    /// Return the height of the most recently stored block, or `0` if the
    /// store is empty.
    fn latest_height(&self) -> Result<u64, StorageError>;

    /// Check whether a block at the given height has been stored.
    fn has_block(&self, height: u64) -> Result<bool, StorageError>;

    /// Replace the current tip block with an equivalent block from the
    /// canonical branch. Implementations must refuse non-tip replacement.
    fn replace_tip_block(
        &self,
        _existing: &Block,
        _replacement: &Block,
    ) -> Result<(), StorageError> ;
}

pub trait StateStore: Send + Sync {
    /// Get a value from a partition. Returns `None` if the key does not exist.
    fn get(&self, partition: &str, key: &[u8]) -> Result<Option<Vec<u8>>, StorageError>;

    /// Set a key-value pair in a partition, creating the partition if needed.
    fn put(&self, partition: &str, key: &[u8], value: &[u8]) -> Result<(), StorageError>;

    /// Set multiple key-value pairs as one logical write.
    ///
    /// Durable backends should override this with their native write-batch
    /// primitive. The default implementation preserves the API contract for
    /// simple stores but is not crash-atomic.
    fn put_many(&self, entries: &[(&str, &[u8], &[u8])]) -> Result<(), StorageError> ;

    /// Delete a key from a partition. No-op if the key does not exist.
    fn delete(&self, partition: &str, key: &[u8]) -> Result<(), StorageError>;

    /// Check whether a key exists in a partition.
    fn has(&self, partition: &str, key: &[u8]) -> Result<bool, StorageError>;

    /// Scan all keys that begin with `prefix` in the given partition,
    /// returning at most `limit` entries sorted by key.
    fn scan_prefix(
        &self,
        partition: &str,
        prefix: &[u8],
        limit: usize,
    ) -> Result<Vec<KeyValuePair>, StorageError>;
}

pub trait ReceiptStore: Send + Sync {
    /// Store a receipt. Overwrites any existing receipt with the same
    /// `tx_hash`.
    fn put_receipt(&self, receipt: &Receipt) -> Result<(), StorageError>;

    /// Retrieve a receipt by transaction hash.
    fn get_receipt(&self, tx_hash: &SigilHash) -> Result<Option<Receipt>, StorageError>;

    /// Retrieve all receipts for a given block height, ordered by `tx_index`.
    fn get_receipts_for_block(&self, height: u64) -> Result<Vec<Receipt>, StorageError>;
}