walletd_mnemonics_core/
lib.rs

1//! This library provides a common interface for handling mnemonics
2pub use hex;
3
4pub mod seed;
5pub use self::seed::Seed;
6pub mod prelude;
7
8#[doc(hidden)]
9pub use std::str::FromStr;
10
11/// Provide a common interface for
12/// different mnemonic protocols.
13pub trait Mnemonic {
14    /// The associated Language struct
15    type Language;
16    /// The associated MnemonicType struct
17    type MnemonicType;
18    /// The associated Builder struct for the Mnemonic
19    type MnemonicBuilder;
20    type Mnemonic;
21    type ErrorType;
22
23    /// Generates a new [mnemonic][Self::Mnemonic] given the [language][Self::Language], [mnemonic type][Self::MnemonicType], and
24    /// an optional passphrase.
25    fn new(
26        language: Self::Language,
27        mnemonic_type: Self::MnemonicType,
28        passphrase: Option<&str>,
29    ) -> Self::Mnemonic;
30
31    /// Recovers a [mnemonic][Self::Mnemonic] given the given the [language][Self::Language], [mnemonic type][Self::MnemonicType], and
32    /// an optional passphrase.
33    fn from_phrase(
34        language: Self::Language,
35        phrase: &str,
36        specified_passphrase: Option<&str>,
37    ) -> Result<Self::Mnemonic, Self::ErrorType>;
38
39    /// Recovers a [mnemonic][Self::Mnemonic] given the mnemonic phrase and optional passphrase,
40    /// attempts to auto detect the language of the mnemonic phrase.
41    /// Returns an [error][Self::ErrorType] if the language cannot be detected or the provided mnemonic phrase was invalid.
42    fn detect_language(
43        phrase: &str,
44        specified_passphrase: Option<&str>,
45    ) -> Result<Self::Mnemonic, Self::ErrorType>;
46
47    /// Returns the [builder][Self::MnemonicBuilder] for the [mnemonic][Self::Mnemonic].
48    fn builder() -> Self::MnemonicBuilder;
49
50    /// Returns the [seed][Seed] associated with the mnemonic phrase.
51    fn to_seed(&self) -> Seed;
52
53    // Returns the [language][Self::Language] for the mnemonic.
54    fn language(&self) -> Self::Language;
55
56    // Returns the mnemonic phrase.
57    fn phrase(&self) -> String;
58
59    // Returns the [mnemonic type][Self::MnemonicType].
60    fn mnemonic_type(&self) -> Self::MnemonicType;
61}
62
63/// Provides a builder pattern for creating a [Mnemonic].
64pub trait MnemonicBuilder {
65    /// The associated Mnemonic struct
66    type Mnemonic;
67    /// The associated Language struct
68    type Language;
69    /// The associated MnemonicType struct
70    type MnemonicType;
71
72    /// The type of error that can be returned by the builder
73    type ErrorType;
74
75    /// Creates a new builder struct with default values.
76    ///
77    /// The default values depend on the implementation of the builder.
78    fn new() -> Self;
79
80    /// Specifies the seed from which the mnemonic struct is recovered.
81    ///
82    /// If a passphrase is specified with the [passphrase][MnemonicBuilder::passphrase] method, the seed recovered using
83    /// the [restore][MnemonicBuilder::restore] or [build][MnemonicBuilder::build] method will be the encrypted version of the seed which takes
84    /// into account the passphrase value.
85    fn mnemonic_seed(&mut self, seed: &Seed) -> &mut Self;
86
87    /// Specifies the mnemonic phrase from which the mnemonic struct is
88    /// recovered.
89    fn mnemonic_phrase(&mut self, mnemonic_phrase: &str) -> &mut Self;
90
91    /// Specifies the language for the mnemonic phrase, can be used when
92    /// recovering a mnemonic phrase or generating a new mnemonic phrase.
93    fn language(&mut self, language: Self::Language) -> &mut Self;
94
95    /// Specifies a passphrase to use to offset/encrypt the seed recovered from
96    /// the mnemonic phrase.
97    fn passphrase(&mut self, passphrase: &str) -> &mut Self;
98
99    /// Specifies the [mnemonic type][Self::mnemonic_type] to use when recovering or generating a
100    /// mnemonic phrase.
101    fn mnemonic_type(&mut self, mnemonic_type: Self::MnemonicType) -> &mut Self;
102
103    /// Sets the [specified language][Self::Language] to None.
104    ///
105    /// When used with [mnemonic_phrase][MnemonicBuilder::mnemonic_phrase] and [build][MnemonicBuilder::build] or [restore][MnemonicBuilder::restore], automatically detects the language of the mnemonic phrase and returns an error if the mnemonic phrase is invalid for every [mnemonic][Self::Mnemonic] [language][Self::Language] wordlist.
106    fn detect_language(&mut self) -> &mut Self;
107
108    /// Builds a mnemonic struct given the specifications provided to the
109    /// builder.
110    ///
111    /// [build()][MnemonicBuilder::build()] can be used in place of [generate()][MnemonicBuilder::generate()] or [restore()][MnemonicBuilder::restore()] and will emulate the appropriate behavior based on the specifications provided to the builder.   
112    fn build(&self) -> Result<Self::Mnemonic, Self::ErrorType>;
113
114    /// Restore a previously used mnemonic based on the given specifications.
115    ///
116    /// Will return an [error][Self::ErrorType] in cases that not enough information was provided to restore the mnemonic or if any provided specifications conflict with each other.
117    fn restore(&self) -> Result<Self::Mnemonic, Self::ErrorType>;
118
119    /// Generate a new mnemonic which follows the provided specifications.
120    fn generate(&self) -> Result<Self::Mnemonic, Self::ErrorType>;
121}
122
123/// The Language trait is used to provide a common interface for the
124/// different Language implementations in different walletD mnemonic libraries.
125pub trait Language {
126    type Language;
127
128    /// Returns the default [Language] for the implementation.
129    fn new() -> Self::Language;
130}
walletd_mnemonics_core/lib.rs

walletd_mnemonics_core/
lib.rs
