ms_codec/
error.rs

1//! ms-codec error taxonomy. Variants mirror SPEC §4 decoder validity rules
2//! plus the encoder-side validation surface from SPEC §3.5 / §3.5.1.
3
4use std::fmt;
5
6/// ms-codec error type.
7#[derive(Debug)]
8#[non_exhaustive]
9pub enum Error {
10    /// Upstream codex32 parse / checksum failure (delegated from rust-codex32).
11    Codex32(codex32::Error),
12    /// HRP was not "ms" (SPEC §4 rule 2).
13    WrongHrp {
14        /// The HRP that was observed.
15        got: String,
16    },
17    /// Threshold was not 0 (SPEC §4 rule 3).
18    ThresholdNotZero {
19        /// The threshold-position byte (ASCII digit) that was observed.
20        got: u8,
21    },
22    /// Share-index was not 's' — BIP-93 requires 's' for threshold=0 (SPEC §4 rule 4).
23    ShareIndexNotSecret {
24        /// The share-index character that was observed.
25        got: char,
26    },
27    /// Tag bytes were not in the codex32 alphabet (SPEC §4 rule 5).
28    TagInvalidAlphabet {
29        /// The 4-byte id-field bytes that failed alphabet validation.
30        got: [u8; 4],
31    },
32    /// Tag was structurally valid but not in RESERVED_TAG_TABLE (SPEC §4 rule 6).
33    UnknownTag {
34        /// The 4-byte tag that was not recognized.
35        got: [u8; 4],
36    },
37    /// Tag was in RESERVED_TAG_TABLE but reserved-not-emitted in v0.1 (SPEC §4 rule 7,
38    /// SPEC §3.5.1 encoder symmetry).
39    ReservedTagNotEmittedInV01 {
40        /// The 4-byte reserved tag (one of seed/xprv/mnem/prvk in v0.1).
41        got: [u8; 4],
42    },
43    /// Reserved-prefix byte was not 0x00 (SPEC §4 rule 8).
44    ReservedPrefixViolation {
45        /// The non-zero prefix byte that was observed.
46        got: u8,
47    },
48    /// Total string length was outside the v0.1 emittable set (SPEC §4 rule 9).
49    UnexpectedStringLength {
50        /// The total string length that was observed.
51        got: usize,
52        /// The set of v0.1-emittable lengths.
53        allowed: &'static [usize],
54    },
55    /// Payload byte length did not match the tag's spec (SPEC §3.5, §4 rule 10).
56    PayloadLengthMismatch {
57        /// The 4-byte tag whose length set was checked against.
58        tag: [u8; 4],
59        /// The set of valid byte lengths for this tag.
60        expected: &'static [usize],
61        /// The observed payload byte length (after stripping the prefix byte).
62        got: usize,
63    },
64    /// BCH error-correction (`bch_decode`) reported the input is uncorrectable
65    /// — the number of symbol errors exceeds the regular code's `t = 4`
66    /// correction capacity (singleton bound `d = 8`). Surfaced by
67    /// [`crate::decode_with_correction`] when `bch_decode::decode_regular_errors`
68    /// returns `None`, or when a post-correction re-verification step fails
69    /// (catches pathological 5+-error patterns that fool the decoder into
70    /// producing a "consistent" but invalid locator). Added v0.2.0 per plan
71    /// §1 D29 + §2.B.2.
72    ///
73    /// `bound = 8` is the BCH(93,80,8) singleton bound. ms1 is single-chunk
74    /// only — no `chunk_index` field (cf. md-codec's `TooManyErrors` which
75    /// carries chunk-set context).
76    TooManyErrors {
77        /// Singleton bound for the BCH regular code (always 8).
78        bound: u8,
79    },
80}
81
82impl fmt::Display for Error {
83    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
84        match self {
85            Error::Codex32(e) => write!(f, "codex32 parse error: {:?}", e),
86            Error::WrongHrp { got } => write!(f, "wrong HRP: got {:?}, expected \"ms\"", got),
87            Error::ThresholdNotZero { got } => {
88                write!(
89                    f,
90                    "threshold not 0 (got '{}'); v0.1 is single-string only",
91                    *got as char
92                )
93            }
94            Error::ShareIndexNotSecret { got } => {
95                write!(
96                    f,
97                    "share-index not 's' (got '{}'); BIP-93 requires 's' for threshold=0",
98                    got
99                )
100            }
101            Error::TagInvalidAlphabet { got } => {
102                write!(f, "tag bytes not in codex32 alphabet: {:?}", got)
103            }
104            Error::UnknownTag { got } => write!(
105                f,
106                "unknown tag {:?}; not a member of RESERVED_TAG_TABLE",
107                std::str::from_utf8(got).unwrap_or("<non-utf8>")
108            ),
109            Error::ReservedTagNotEmittedInV01 { got } => write!(
110                f,
111                "tag {:?} reserved-not-emitted in v0.1; deferred to v0.2+",
112                std::str::from_utf8(got).unwrap_or("<non-utf8>")
113            ),
114            Error::ReservedPrefixViolation { got } => {
115                write!(f, "reserved-prefix byte was 0x{:02x}, expected 0x00", got)
116            }
117            Error::UnexpectedStringLength { got, allowed } => {
118                write!(f, "string length {} outside v0.1 set {:?}", got, allowed)
119            }
120            Error::PayloadLengthMismatch { tag, expected, got } => write!(
121                f,
122                "tag {:?} payload length {} not in expected set {:?}",
123                std::str::from_utf8(tag).unwrap_or("<non-utf8>"),
124                got,
125                expected
126            ),
127            Error::TooManyErrors { bound } => {
128                write!(f, "more than {} errors; uncorrectable", bound)
129            }
130        }
131    }
132}
133
134impl std::error::Error for Error {
135    fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
136        // codex32::Error doesn't impl std::error::Error in v0.1.0; chain stops here.
137        None
138    }
139}
140
141impl From<codex32::Error> for Error {
142    fn from(e: codex32::Error) -> Self {
143        Error::Codex32(e)
144    }
145}
146
147/// Result alias for ms-codec.
148pub type Result<T> = std::result::Result<T, Error>;
ms_codec/error.rs

ms_codec/
error.rs
