Skip to main content

dig_account/
error.rs

1//! The crate-wide error type and result alias.
2
3use crate::id::ProfileIx;
4
5/// Convenience result alias for all fallible dig-account operations.
6pub type Result<T> = std::result::Result<T, AccountError>;
7
8/// Every failure mode surfaced by the dig-account public API.
9///
10/// Fail-closed: any ambiguity in an unlock, signing, or custody path resolves to an error here
11/// rather than a silent success.
12#[derive(Debug, thiserror::Error)]
13#[non_exhaustive]
14pub enum AccountError {
15    /// The account (or the requested operation) is locked; unlock first.
16    #[error("account is locked")]
17    Locked,
18
19    /// No profile exists at the requested index.
20    #[error("no profile at index {0}")]
21    ProfileNotFound(ProfileIx),
22
23    /// The exactly-one-default invariant was violated.
24    #[error("default-profile invariant violated: {0}")]
25    DefaultProfileInvariant(String),
26
27    /// A profile is already recorded at this index.
28    ///
29    /// An anchor is evidence of ONE specific on-chain mint, so re-recording an index would replace
30    /// a proof with a different proof. The existing entry is left untouched.
31    #[error("a profile is already registered at index {0}")]
32    ProfileAlreadyRegistered(ProfileIx),
33
34    /// A profile with this IDENTITY is already recorded, at a different index.
35    ///
36    /// A profile IS its on-chain identity. Two entries claiming one DID would derive different
37    /// wallet keys and different DEKs from their two indices while presenting as the same person,
38    /// so the account could receive at an address the identity's own surfaces never show. The
39    /// existing entry is left untouched.
40    #[error("profile {existing} is already registered with identity {did}")]
41    ProfileIdentityAlreadyRegistered {
42        /// The index that already holds this identity.
43        existing: ProfileIx,
44        /// The `did:chia:…` string both entries claim.
45        did: String,
46    },
47
48    /// The ACTIVE profile cannot be hidden from the host's lists.
49    ///
50    /// A hidden active profile is a trap: the UI lists nothing while the wallet keeps deriving and
51    /// receiving at that index. Switch away first, then hide.
52    #[error("the active profile {0} cannot be hidden from lists")]
53    ActiveProfileCannotBeHidden(ProfileIx),
54
55    /// The profile has ENDED on chain — both of its singletons were melted — so it cannot be made
56    /// active, and no host may present it as a live profile.
57    ///
58    /// The entry is deliberately KEPT rather than deleted: its DID string remains the right answer
59    /// to "what did this account used to be", and an absence cannot say that a profile ended.
60    #[error("profile {0} has ended on the blockchain and cannot be made active")]
61    ProfileEnded(ProfileIx),
62
63    /// A profile end was recorded at height 0, which no on-chain confirmation can produce.
64    ///
65    /// Recording one would let a submission masquerade as a confirmation — the same rule the mint
66    /// anchors enforce (`SPEC.md` §2.4).
67    #[error("a profile end at height 0 is not evidence of a confirmed melt")]
68    ProfileEndHeightZero,
69
70    /// A mint is already journalled at this index.
71    ///
72    /// Beginning a second one would re-mint a DID that may already be paid for, orphaning the
73    /// first (dig_ecosystem#2377). Resume the journalled mint instead.
74    #[error("a profile mint is already in progress at index {0}")]
75    MintAlreadyInProgress(ProfileIx),
76
77    /// The two halves of a mint do not belong to each other: the store was launched from some
78    /// other DID's coin.
79    ///
80    /// Each evidence proves only that its OWN coin confirmed, so pairing them is where the
81    /// relationship is checked. Recording this pair would assert a profile that does not exist.
82    /// Both ids are public coin ids.
83    #[error(
84        "the store was launched from DID coin {store_launched_from}, not from this DID's coin {did_coin_id}"
85    )]
86    MismatchedMintHalves {
87        /// The coin of the DID being recorded.
88        did_coin_id: chia_protocol::Bytes32,
89        /// The DID coin the store's launch actually spent.
90        store_launched_from: chia_protocol::Bytes32,
91    },
92
93    /// A disclosed mint fee is above the mint's hard ceiling
94    /// ([`MAX_MINT_FEE_MOJOS`](crate::mint::MAX_MINT_FEE_MOJOS)).
95    ///
96    /// The journalled store fee is the amount a resumed phase B is allowed to spend, so an
97    /// unbounded one turns a restart into a route for handing a wallet coin to a farmer — exactly
98    /// what the DID half's ceiling already refuses. Same ceiling, deliberately: a different limit
99    /// for the second bundle would be a design decision, not a bound.
100    #[error("mint fee of {fee} mojos is above the {ceiling} mojo ceiling")]
101    MintFeeAboveCeiling {
102        /// The fee that was disclosed.
103        fee: u64,
104        /// The largest fee a mint may pay.
105        ceiling: u64,
106    },
107
108    /// A profile registry violated one of its four invariants — usually an edited or corrupt file.
109    ///
110    /// Fail-closed: the registry is not partially loaded, so a host never acts on a half-valid
111    /// profile list.
112    #[error("profile registry invariant violated: {0}")]
113    RegistryInvariant(String),
114
115    /// The account has no active profile, because it has no confirmed profile at all.
116    ///
117    /// This is the pre-mint state of every new account, not a fault: the host's answer is to run
118    /// the first-run mint, never to invent an index.
119    #[error("the account has no active profile")]
120    NoActiveProfile,
121
122    /// An underlying keystore operation failed.
123    #[error("keystore error: {0}")]
124    Keystore(String),
125
126    /// Authentication or unlock-policy evaluation rejected the attempt.
127    #[error("authentication failed: {0}")]
128    Auth(String),
129
130    /// A money-path spend operation failed — spend verification, summary derivation, or signing
131    /// was refused. Fail-closed: the money signer surfaces every rejection here rather than
132    /// producing a signature it could not fully account for.
133    #[error("spend refused: {0}")]
134    Spend(String),
135
136    /// The USER declined the spend at the confirm ceremony.
137    ///
138    /// Distinct from [`PolicyDenied`](Self::PolicyDenied) because the two are different facts about
139    /// different deciders, and a host reports them differently: "you said no" is an ordinary outcome,
140    /// while "the rules say no" may mean a misconfiguration. Merging them would also make the normative
141    /// wire mapping (`SPEC.md` §6.3.1) ambiguous — one crate outcome cannot map to two codes — and
142    /// collapsing outcomes at a boundary is the defect this crate's 0.5.0 shape exists to remove.
143    ///
144    /// Terminal: no further ceremony may permit a spend the user has already refused.
145    #[error("the user declined the spend: {0}")]
146    UserDeclined(String),
147
148    /// The spend is FORBIDDEN by a structural custody rule — no confirmation ceremony can permit it.
149    ///
150    /// A user's refusal is NOT this variant; it is [`UserDeclined`](Self::UserDeclined). Both are
151    /// terminal, but they name different deciders and `SPEC.md` §6.3.1 maps them to different wire
152    /// codes, so a host must be able to tell them apart.
153    ///
154    /// # The escalatable outcome is deliberately NOT an error
155    ///
156    /// "Not auto-approved, but a human could permit it" is
157    /// [`SpendRuling::RequiresConfirmation`](crate::wallet::approval::SpendRuling::RequiresConfirmation)
158    /// — an `Ok` value carrying a
159    /// [`PendingApproval`](crate::wallet::approval::PendingApproval) — never a variant here. When it
160    /// WAS an error variant (`RequireAuth`, removed in 0.5.0), the crate's only consumer collapsed
161    /// every `Err` into one refusal and the confirm ceremony became unreachable for exactly the tiers
162    /// that exist to require it. Every variant in this enum is now terminal for the spend, so
163    /// collapsing them can lose detail but can no longer lose a permission.
164    ///
165    /// The canonical structural case is a vault outflow to anything other than the profile's own hot
166    /// wallet (#1504: every vault outflow MUST pass through the 24h clawback window, so it may only
167    /// ever pay the hot wallet).
168    #[error("spend forbidden by custody policy: {0}")]
169    PolicyDenied(String),
170
171    /// The policy COULD NOT BE EVALUATED for this spend — the answer is unknown, not "no".
172    ///
173    /// Kept separate from [`PolicyDenied`](Self::PolicyDenied) because collapsing "denied by policy"
174    /// with "could not determine policy" into one refusal loses the only signal that the gate is
175    /// malfunctioning (an unreadable clock, an undecodable recipient address, a spend whose value is
176    /// denominated in units no configured limit can bound, a rolling window zero seconds long). Every
177    /// indeterminate outcome refuses the spend, and none of them is escalatable — the condition must be
178    /// fixed, not confirmed away.
179    #[error("spend policy could not be evaluated: {0}")]
180    PolicyIndeterminate(String),
181}
182
183#[cfg(test)]
184mod tests {
185    use super::*;
186
187    #[test]
188    fn locked_displays() {
189        assert_eq!(AccountError::Locked.to_string(), "account is locked");
190    }
191
192    #[test]
193    fn profile_not_found_includes_index() {
194        let e = AccountError::ProfileNotFound(ProfileIx(2));
195        assert_eq!(e.to_string(), "no profile at index 2");
196    }
197
198    #[test]
199    fn keystore_wraps_message() {
200        let e = AccountError::Keystore("disk full".into());
201        assert!(e.to_string().contains("disk full"));
202    }
203
204    /// The two custody refusals MUST stay distinguishable by variant, not only by message text: a
205    /// caller decides whether to refuse outright (`PolicyDenied`) or surface a malfunctioning gate
206    /// (`PolicyIndeterminate`) by matching on the variant. The third outcome — "ask the human" — is a
207    /// `SpendRuling`, not an error, and `spend_policy_has_no_escalatable_error_variant` pins that.
208    #[test]
209    fn the_two_custody_refusals_are_distinct_variants_with_distinct_wording() {
210        let forbidden = AccountError::PolicyDenied("vault outflow".into());
211        let unknown = AccountError::PolicyIndeterminate("clock unreadable".into());
212
213        assert!(matches!(forbidden, AccountError::PolicyDenied(_)));
214        assert!(matches!(unknown, AccountError::PolicyIndeterminate(_)));
215
216        assert_eq!(
217            forbidden.to_string(),
218            "spend forbidden by custody policy: vault outflow"
219        );
220        assert_eq!(
221            unknown.to_string(),
222            "spend policy could not be evaluated: clock unreadable"
223        );
224    }
225}