dig-account 0.26.2

The DIG Network user Account: the fat, strictly-logical crate for everything an account does — the Account+Profile object model, unlock policy + keystore crypto, the in-process identity+money signer, per-profile key/DEK derivation, DID+dig-store mint/sign, and all wallet ops. Headless (no UI). Consumed by dig-app.
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
//! The STORE half of a profile mint, as types: [`PendingStoreLaunch`] (pushed, unproven) and
//! [`ConfirmedStore`] (proven on chain).
//!
//! This is the exact twin of [`evidence`](super::evidence) for the second of the two bundles a
//! profile needs. A profile is a DID singleton PLUS a dig-store launched from it, and the store half
//! is subject to the same failure: a push that was accepted, a coin that never confirmed, and a
//! surface that has already told the user a profile exists.
//!
//! # The invariant these types enforce
//!
//! **A store is recorded only from evidence of an actual on-chain launch.** [`ConfirmedStore`]
//! carries a `confirmed_height: u32` — not an `Option` — has private fields, exactly one
//! crate-private constructor ([`ConfirmedStore::from_confirmed`]), no `Default` and no
//! `Deserialize`. There is no way to assemble one from a key, from a push receipt, or from optimism.
//!
//! # What this does NOT prove
//!
//! Exactly what [`evidence`](super::evidence) does not prove, for the same reason: every field is
//! the chain source's testimony, and in a typical deployment that source is the same node the bundle
//! was pushed to. The five rules in [`ConfirmedStore::from_confirmed`] close the DEGENERATE
//! fabrications (genesis, the future, a height predating the push, an unrelated coin) and buy real
//! reorg safety against an HONEST source. They cost a dishonest one nothing. The mitigation is the
//! caller's: pass a trusted or aggregating `ChainSource`.
//!
//! It also does not prove the store's CONTENT. [`ConfirmedStore::committed_root`] is the root the
//! launch spend committed to, carried through from the bundle this crate built — the chain proves a
//! coin exists, not that any particular bytes hash to that root.

use chia_protocol::Bytes32;
use dig_chainsource_interface::CoinRecord;

use super::evidence::MIN_CONFIRMATION_DEPTH;

/// A dig-store launch that has been signed and pushed, and is NOT yet proven on chain.
///
/// Deliberately not a store: it names what to look for, and nothing may treat it as a profile. The
/// caller polls the chain with it until a [`ConfirmedStore`] comes back.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct PendingStoreLaunch {
    /// The store singleton's launcher id — the store's permanent identifier once it confirms.
    launcher_id: Bytes32,
    /// The id of the store coin the pushed bundle creates. Confirmation of THIS coin is the evidence.
    store_coin_id: Bytes32,
    /// The DID coin this launch spends. If the chain reports it spent while no store coin exists,
    /// some OTHER spend consumed it and this bundle can never be included.
    did_coin_id: Bytes32,
    /// The root the launch spend commits to. Carried through from the bundle this crate built, so a
    /// chain source cannot choose it.
    committed_root: [u8; 32],
    /// The chain's peak immediately BEFORE the push. A confirmation cannot predate it.
    pushed_at_height: u32,
}

impl PendingStoreLaunch {
    /// Record what a pushed store launch is, and when. `pub(crate)`: only the mint flow constructs
    /// one, and only from the bundle it actually built and pushed
    /// ([`store_launch`](super::store_launch)).
    pub(crate) fn new(
        launcher_id: Bytes32,
        store_coin_id: Bytes32,
        did_coin_id: Bytes32,
        committed_root: [u8; 32],
        pushed_at_height: u32,
    ) -> Self {
        Self {
            launcher_id,
            store_coin_id,
            did_coin_id,
            committed_root,
            pushed_at_height,
        }
    }

    /// The store singleton launcher id this launch will produce.
    pub fn launcher_id(&self) -> Bytes32 {
        self.launcher_id
    }

    /// The store coin whose confirmation is this launch's evidence.
    pub fn store_coin_id(&self) -> Bytes32 {
        self.store_coin_id
    }

    /// The DID coin this launch spends — its sole input from the chain's point of view.
    pub fn did_coin_id(&self) -> Bytes32 {
        self.did_coin_id
    }

    /// The root the launch spend commits to.
    pub fn committed_root(&self) -> [u8; 32] {
        self.committed_root
    }

    /// The chain's peak height immediately before this launch was pushed.
    ///
    /// A caller builds its own timeout from this: `peak - pushed_at_height` is how many blocks the
    /// launch has been waiting, which is a real elapsed measure rather than a spinner.
    pub fn pushed_at_height(&self) -> u32 {
        self.pushed_at_height
    }
}

/// A dig-store that EXISTS on chain, and the evidence that it does.
///
/// Constructible only by [`from_confirmed`](Self::from_confirmed) from a confirmed [`CoinRecord`] of
/// the exact coin the launch bundle created. See the module docs for what that can and cannot prove.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ConfirmedStore {
    /// The store singleton launcher id (the store's permanent identifier).
    launcher_id: Bytes32,
    /// The confirmed store coin.
    coin_id: Bytes32,
    /// The block height at which that coin was confirmed. Not optional: an unconfirmed launch
    /// cannot be represented by this type.
    confirmed_height: u32,
    /// The DID coin this store was launched FROM, carried through from the launch this evidence
    /// proves.
    ///
    /// This is what makes the store attributable: a confirmed store coin on its own says a store
    /// exists somewhere, and only this field says WHOSE. [`ProfileAnchor`](crate::ProfileAnchor)
    /// pairs the two halves of a mint by comparing it against the DID's own coin id.
    did_coin_id: Bytes32,
    /// The root the launch spend committed to.
    committed_root: [u8; 32],
}

impl ConfirmedStore {
    /// The ONLY way to obtain a [`ConfirmedStore`].
    ///
    /// Returns `None` — never a partially-populated value — unless every one of these holds. They
    /// are the same five rules
    /// [`MintedDid::from_confirmed`](super::evidence::MintedDid::from_confirmed) applies, for the
    /// same reasons:
    ///
    /// 1. **The record is the coin `pending` says the bundle creates.** A record of any other coin
    ///    proves nothing about this launch.
    /// 2. **It carries a confirmed height.** An unconfirmed record is a mempool observation.
    /// 3. **That height is not genesis.** No coin is created in block 0, so a `0` is fabricated.
    /// 4. **It does not predate the push.** A launch cannot appear in a block that already existed
    ///    when it was broadcast.
    /// 5. **It is buried under [`MIN_CONFIRMATION_DEPTH`] blocks**, so a shallow reorg cannot
    ///    silently undo a store already recorded as permanent. This also rejects a height in the
    ///    FUTURE — one past the source's own peak has a depth of 1.
    //
    // This is the ONLY way to obtain a `ConfirmedStore`, and a `ConfirmedStore` is half of what a
    // `ProfileAnchor` needs. It stays `pub(crate)` deliberately: widening it would let a host
    // fabricate store evidence with no chain read at all. A host reaches a `ConfirmedStore` as the
    // OUTPUT of a real mint — `ProfileMintStatus::Confirmed` (dig_ecosystem#2511) — never by
    // constructing one.
    pub(crate) fn from_confirmed(
        pending: &PendingStoreLaunch,
        record: &CoinRecord,
        peak_height: u32,
    ) -> Option<Self> {
        if record.coin.coin_id() != pending.store_coin_id() {
            return None;
        }
        let confirmed_height = record.confirmed_height?;
        if confirmed_height == 0 || confirmed_height < pending.pushed_at_height() {
            return None;
        }
        // `peak - confirmed` is the number of blocks built ON TOP; the confirming block itself is
        // the first of the depth, hence the +1.
        if peak_height
            .saturating_sub(confirmed_height)
            .saturating_add(1)
            < MIN_CONFIRMATION_DEPTH
        {
            return None;
        }
        Some(Self {
            launcher_id: pending.launcher_id(),
            coin_id: pending.store_coin_id(),
            confirmed_height,
            did_coin_id: pending.did_coin_id(),
            committed_root: pending.committed_root(),
        })
    }

    /// The store singleton launcher id.
    pub fn launcher_id(&self) -> Bytes32 {
        self.launcher_id
    }

    /// The confirmed store coin id.
    pub fn coin_id(&self) -> Bytes32 {
        self.coin_id
    }

    /// The block height at which the store coin was confirmed.
    pub fn confirmed_height(&self) -> u32 {
        self.confirmed_height
    }

    /// The DID coin this store was launched from — the only thing that ties the store to an
    /// identity.
    pub fn did_coin_id(&self) -> Bytes32 {
        self.did_coin_id
    }

    /// The root the launch spend committed to.
    ///
    /// This is not proof of content: it is the value this crate put into the bundle it built. A
    /// reader that needs the bytes must fetch and hash them.
    pub fn committed_root(&self) -> [u8; 32] {
        self.committed_root
    }

    /// Every field of this evidence, in declaration order, for the mirror test in
    /// [`ConfirmedStoreRecord`](crate::registry::ConfirmedStoreRecord).
    ///
    /// The destructuring is exhaustive and deliberately `..`-free: a field added to
    /// [`ConfirmedStore`] fails to compile HERE, which is what forces the mirror and its test to
    /// grow with it. A hand-maintained list of assertions cannot do that — which is exactly how
    /// `did_coin_id`, the field that makes a store attributable, came to be mirrored nowhere and
    /// asserted nowhere.
    #[cfg(test)]
    pub(crate) fn every_field(&self) -> (Bytes32, Bytes32, u32, Bytes32, [u8; 32]) {
        let Self {
            launcher_id,
            coin_id,
            confirmed_height,
            did_coin_id,
            committed_root,
        } = self;
        (
            *launcher_id,
            *coin_id,
            *confirmed_height,
            *did_coin_id,
            *committed_root,
        )
    }
}

impl PendingStoreLaunch {
    /// Every field of this pending launch, in declaration order. See
    /// [`ConfirmedStore::every_field`] for why it destructures exhaustively.
    #[cfg(test)]
    pub(crate) fn every_field(&self) -> (Bytes32, Bytes32, Bytes32, [u8; 32], u32) {
        let Self {
            launcher_id,
            store_coin_id,
            did_coin_id,
            committed_root,
            pushed_at_height,
        } = self;
        (
            *launcher_id,
            *store_coin_id,
            *did_coin_id,
            *committed_root,
            *pushed_at_height,
        )
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use chia_protocol::Coin;

    const ROOT: [u8; 32] = [0xAB; 32];

    /// The height the launch was pushed at, and a peak far enough beyond it that an honest
    /// confirmation at `PUSHED_AT` is buried past [`MIN_CONFIRMATION_DEPTH`].
    const PUSHED_AT: u32 = 4_200_000;
    const PEAK: u32 = PUSHED_AT + MIN_CONFIRMATION_DEPTH;

    fn coin() -> Coin {
        Coin::new(Bytes32::new([1; 32]), Bytes32::new([2; 32]), 1)
    }

    fn pending_for(coin: &Coin) -> PendingStoreLaunch {
        PendingStoreLaunch::new(
            Bytes32::new([9; 32]),
            coin.coin_id(),
            Bytes32::new([4; 32]),
            ROOT,
            PUSHED_AT,
        )
    }

    fn record(coin: Coin, confirmed_height: Option<u32>) -> CoinRecord {
        CoinRecord {
            coin,
            confirmed_height,
            spent_height: None,
            timestamp: None,
            coinbase: false,
        }
    }

    /// The CONTROL. Without it every rejection below could pass because the fixture is broken rather
    /// than because the rule fired.
    #[test]
    fn a_confirmed_store_record_of_the_expected_coin_yields_evidence() {
        let coin = coin();
        let pending = pending_for(&coin);

        let store = ConfirmedStore::from_confirmed(&pending, &record(coin, Some(PUSHED_AT)), PEAK)
            .expect("a buried confirmation of the expected coin is evidence");

        assert_eq!(store.confirmed_height(), PUSHED_AT);
        assert_eq!(store.launcher_id(), pending.launcher_id());
        assert_eq!(store.coin_id(), pending.store_coin_id());
        assert_eq!(
            store.did_coin_id(),
            pending.did_coin_id(),
            "the DID coin the launch spent is carried through, or the store loses its owner"
        );
        assert_ne!(
            store.did_coin_id(),
            store.coin_id(),
            "the fixture must distinguish the two coins, or a transposed field would pass"
        );
        assert_eq!(
            store.committed_root(),
            ROOT,
            "the root comes from the bundle this crate built, never from the record"
        );
    }

    /// An UNCONFIRMED record of the right coin is a mempool observation. This is the exact false
    /// positive the invariant exists to prevent: the coin is correct, the launch really was pushed,
    /// and the chain has still not acknowledged it.
    #[test]
    fn an_unconfirmed_store_record_is_not_evidence() {
        let coin = coin();
        let pending = pending_for(&coin);
        assert!(ConfirmedStore::from_confirmed(&pending, &record(coin, None), PEAK).is_none());
    }

    /// A CONFIRMED record of a DIFFERENT coin proves nothing about this launch. Without the coin-id
    /// check, any confirmed coin the wallet can read would launch a store out of thin air.
    #[test]
    fn a_confirmed_record_of_another_coin_is_not_store_evidence() {
        let pending = pending_for(&coin());
        let other = Coin::new(Bytes32::new([7; 32]), Bytes32::new([8; 32]), 1);
        assert_ne!(other.coin_id(), pending.store_coin_id());

        assert!(
            ConfirmedStore::from_confirmed(&pending, &record(other, Some(PUSHED_AT)), PEAK)
                .is_none()
        );
    }

    /// **Fabrication: genesis.** No coin is created in block 0. The fixture pushes at height 0 so
    /// that EVERY other rule passes and only the genesis rule can reject — with a later push height
    /// the "predates the push" rule would reject it too and this test would not exercise the rule it
    /// names.
    #[test]
    fn a_store_confirmation_at_genesis_is_not_evidence() {
        let coin = coin();
        let pending = PendingStoreLaunch::new(
            Bytes32::new([9; 32]),
            coin.coin_id(),
            Bytes32::new([4; 32]),
            ROOT,
            0,
        );
        let peak = MIN_CONFIRMATION_DEPTH - 1;

        assert!(
            ConfirmedStore::from_confirmed(&pending, &record(coin, Some(0)), peak).is_none(),
            "no coin is created in block 0"
        );
        // The control: the same pending launch, confirmed one block later, IS evidence — so the
        // rejection above is the genesis rule and not some other rule this fixture trips.
        assert!(
            ConfirmedStore::from_confirmed(&pending, &record(coin, Some(1)), peak + 1).is_some()
        );
    }

    /// **Fabrication: the past.** A launch cannot appear in a block that already existed when it was
    /// broadcast, however plausible the height looks.
    #[test]
    fn a_store_confirmation_predating_the_push_is_not_evidence() {
        let coin = coin();
        let pending = pending_for(&coin);
        assert!(
            ConfirmedStore::from_confirmed(&pending, &record(coin, Some(PUSHED_AT - 1)), PEAK)
                .is_none()
        );
    }

    /// **Fabrication: the future.** A height beyond the source's own peak is rejected by the depth
    /// rule, since a future height is zero blocks deep. `u32::MAX` is the shape a node picks when it
    /// wants a naive depth subtraction to underflow into something huge.
    #[test]
    fn a_store_confirmation_past_the_peak_is_not_evidence() {
        let coin = coin();
        let pending = pending_for(&coin);
        for claimed in [PEAK + 1, u32::MAX] {
            assert!(
                ConfirmedStore::from_confirmed(&pending, &record(coin, Some(claimed)), PEAK)
                    .is_none(),
                "a confirmation at {claimed} is past the peak {PEAK}"
            );
        }
    }

    /// **Reorg depth, pinned from BOTH sides.** One block short of the required burial is refused
    /// and exactly at the bound is accepted — a bound tested only from below can confirm nothing but
    /// itself.
    #[test]
    fn the_store_confirmation_depth_bound_holds_from_both_sides() {
        let coin = coin();
        let pending = pending_for(&coin);

        // The confirming block counts as the first of the depth, so a peak of
        // `h + MIN_CONFIRMATION_DEPTH - 1` is exactly at the bound.
        let at_bound = PUSHED_AT + MIN_CONFIRMATION_DEPTH - 1;
        let one_short = at_bound - 1;

        assert!(
            ConfirmedStore::from_confirmed(&pending, &record(coin, Some(PUSHED_AT)), one_short)
                .is_none(),
            "one block short of {MIN_CONFIRMATION_DEPTH} deep is still reversible"
        );
        assert!(
            ConfirmedStore::from_confirmed(&pending, &record(coin, Some(PUSHED_AT)), at_bound)
                .is_some(),
            "exactly {MIN_CONFIRMATION_DEPTH} deep is evidence"
        );
    }
}