dig_store/
types.rs

1//! The shared identifier + value types of the store surface.
2//!
3//! The coin/identity types are re-exported VERBATIM from `dig-merkle` (which re-exports the
4//! `chia-wallet-sdk` byte-source-of-truth) so a consumer depends on ONE canonical shape and never a
5//! shadow copy that could byte-drift:
6//!
7//! - [`Bytes32`] — a 32-byte identifier (a `store_id` / `launcher_id`, a merkle root, a DID id);
8//! - [`Coin`] / [`CoinSpend`] — the Chia coin + confirmed spend;
9//! - [`DataStore`] / [`DigDataStoreMetadata`] — the hydrated DataLayer coin + its on-chain metadata;
10//! - [`DidRef`] — a reference to an owning DID by its launcher id;
11//! - [`MerkleCoinSpend`] — the unsigned result of a lifecycle operation (coin spends + child store).
12//!
13//! Two `dig-store`-owned view types are added here:
14//!
15//! - [`RootHistory`] — the ordered list of merkle roots a store has anchored across its generations,
16//!   produced by the on-chain lineage walk (SPEC §5);
17//! - [`CapsuleIdentity`] — the `(store_id, root_hash)` a capsule declares, recovered OFF-CHAIN from a
18//!   compiled `.dig` module's bytes (SPEC §5/§11). It is the `dig-store`-native view (canonical
19//!   [`Bytes32`]) of a `dig_capsule::capsule::Capsule`, so the whole store surface speaks ONE byte
20//!   type rather than exposing `dig-capsule`'s separate `Bytes32`.
21
22pub use dig_merkle::{
23    Bytes32, Coin, CoinSpend, DataStore, DidRef, DigDataStoreMetadata, MerkleCoinSpend,
24};
25
26/// The ordered history of merkle roots a store has anchored, oldest first.
27///
28/// Each entry is proven on chain by walking the singleton's lineage from the launcher forward (NC-9,
29/// SPEC §5). The last element is the latest root. A live store is never empty (the mint anchors
30/// generation 0); a fully-melted store's history still lists every root it anchored while live.
31#[derive(Debug, Clone, PartialEq, Eq, Default)]
32pub struct RootHistory {
33    /// The anchored roots, oldest → newest.
34    pub roots: Vec<Bytes32>,
35}
36
37impl RootHistory {
38    /// The most recently anchored root, if any.
39    pub fn latest(&self) -> Option<Bytes32> {
40        self.roots.last().copied()
41    }
42
43    /// The number of generations (root anchorings) the store has had.
44    pub fn generation_count(&self) -> usize {
45        self.roots.len()
46    }
47}
48
49/// The identity a capsule declares: one immutable store generation, the pair `(store_id, root_hash)`.
50///
51/// Recovered OFF-CHAIN from a compiled `.dig` module's bytes by [`crate::get_capsule_identity`] /
52/// [`crate::open_capsule`] (SPEC §5/§11). This is `dig-store`'s canonical-[`Bytes32`] view of a
53/// `dig_capsule::capsule::Capsule`.
54///
55/// # `store_id` is NOT self-verified
56///
57/// `root_hash` is proven internally consistent by the reader (it recomputes the merkle root from the
58/// module's committed leaves and rejects a forged one). `store_id`, however, is the store's on-chain
59/// Chia launcher id, baked into the module at compile time and NOT self-verifiable from the module
60/// bytes alone — nothing in the bytes binds them to that launcher. Treat a `store_id` from
61/// [`crate::get_capsule_identity`] as a CLAIM until cross-checked against a trusted anchor (the URN you
62/// resolved, the on-chain singleton, or a verified `ChainSource`). [`crate::open_capsule`] performs
63/// that cross-check for you.
64#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
65pub struct CapsuleIdentity {
66    /// The store's on-chain launcher id (a CLAIM until cross-checked — see the type docs).
67    pub store_id: Bytes32,
68    /// The merkle root of this capsule generation, proven internally consistent by the reader.
69    pub root_hash: Bytes32,
70}
71
72impl CapsuleIdentity {
73    /// The capsule URN `urn:dig:chia:<store_id>:<root_hash>` pinning this exact generation.
74    pub fn capsule_urn(&self) -> String {
75        crate::urn::capsule_urn(self.store_id, self.root_hash)
76    }
77}
78
79#[cfg(test)]
80mod tests {
81    use super::*;
82
83    fn id(b: u8) -> Bytes32 {
84        Bytes32::new([b; 32])
85    }
86
87    #[test]
88    fn capsule_identity_formats_its_pinning_urn() {
89        let identity = CapsuleIdentity {
90            store_id: id(0xaa),
91            root_hash: id(0xbb),
92        };
93        assert_eq!(
94            identity.capsule_urn(),
95            format!("urn:dig:chia:{}:{}", "aa".repeat(32), "bb".repeat(32))
96        );
97    }
98
99    #[test]
100    fn root_history_reports_latest_and_generation_count() {
101        let empty = RootHistory::default();
102        assert_eq!(empty.latest(), None);
103        assert_eq!(empty.generation_count(), 0);
104
105        let history = RootHistory {
106            roots: vec![id(1), id(2), id(3)],
107        };
108        assert_eq!(history.latest(), Some(id(3)));
109        assert_eq!(history.generation_count(), 3);
110    }
111}
dig_store/types.rs

dig_store/
types.rs
