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}