pub struct Session;Expand description
Entry point for turning stored, encrypted key material into a live signer.
Session is a stateless namespace over the compose-only flow
dig_keystore::Keystore::<K>::load -> unlock -> SignerHandle<K>, plus the
enrollment path that derives the canonical dig-identity signing key and
persists it. It holds no state of its own; every method is associated.
Implementations§
Source§impl Session
impl Session
Sourcepub fn unlock<K: KeyScheme>(
backend: Arc<dyn KeychainBackend>,
path: BackendKey,
password: Password,
) -> Result<UnlockedIdentity<K>>
pub fn unlock<K: KeyScheme>( backend: Arc<dyn KeychainBackend>, path: BackendKey, password: Password, ) -> Result<UnlockedIdentity<K>>
Unlock an existing keystore file into an UnlockedIdentity.
Generic over the storage scheme K: use dig_keystore::L1WalletBls
for a stored, already-derived key (the identity signing key, wallet
keys) and dig_keystore::BlsSigning for a seed-derived validator key.
The scheme is verified against the file’s magic on load, so unlocking a
file with the wrong scheme fails cleanly rather than yielding a bogus key.
§Errors
Returns SessionError::Keystore if the file is missing, the password
is wrong, the ciphertext is tampered, or the scheme does not match.
Sourcepub fn enroll_identity(
backend: Arc<dyn KeychainBackend>,
path: BackendKey,
password: Password,
seed: &[u8],
) -> Result<UnlockedIdentity<L1WalletBls>>
pub fn enroll_identity( backend: Arc<dyn KeychainBackend>, path: BackendKey, password: Password, seed: &[u8], ) -> Result<UnlockedIdentity<L1WalletBls>>
Enroll a new identity: derive the canonical dig-identity BLS signing key
from seed, persist it encrypted under password, and return it
unlocked and ready to sign.
The identity key is derived exactly once, via
dig_identity::master_secret_key_from_seed followed by
dig_identity::derive_identity_sk (the hardened path
m/12381'/8444'/9'/0'), and the resulting secret key’s canonical bytes
are stored. See the module-level note in crate on why the storage
scheme is L1WalletBls (faithful from_bytes round-trip) rather than
BlsSigning (which would re-derive via from_seed and produce a
different key).
§Errors
Returns SessionError::EmptySeed if seed is empty, or
SessionError::Keystore if a file already exists at path or the
write fails.
Sourcepub fn enroll_master_seed(
backend: Arc<dyn KeychainBackend>,
path: BackendKey,
password: Password,
entropy: &[u8; 32],
) -> Result<UnlockedMasterSeed>
pub fn enroll_master_seed( backend: Arc<dyn KeychainBackend>, path: BackendKey, password: Password, entropy: &[u8; 32], ) -> Result<UnlockedMasterSeed>
Enroll a new account root from entropy: seal the 32 bytes of BIP-39
entropy under password in a versioned envelope and return an
UnlockedMasterSeed.
Unlike enroll_identity — which stores the
derived identity scalar and can never recover the root — this path
stores the root itself, so a consumer can reconstruct the wallet
MasterKey (the master-HD model, dig_ecosystem #997), derive the
dig-identity key, and render the 24-word recovery phrase, all from one
value.
entropy is BIP-39 entropy, not an HD seed: it is expanded to the
64-byte seed via to_seed("") at every derivation, which is what makes
the resulting phrase restore identically in Sage and every standard Chia
wallet (dig_ecosystem #1759). Any ENTROPY_LEN CSPRNG bytes are valid
entropy, so a caller may pass fresh randomness directly.
§Errors
Returns SessionError::Keystore if a blob already exists at path
(never silently overwritten) or the write fails.
Sourcepub fn enroll_from_recovery_phrase(
backend: Arc<dyn KeychainBackend>,
path: BackendKey,
password: Password,
phrase: &str,
) -> Result<UnlockedMasterSeed>
pub fn enroll_from_recovery_phrase( backend: Arc<dyn KeychainBackend>, path: BackendKey, password: Password, phrase: &str, ) -> Result<UnlockedMasterSeed>
Enroll an account root from an existing 24-word recovery phrase — the
restore-on-a-new-machine path.
The phrase may be any capitalisation with any whitespace between words
(BIP-39 normalised). Restoring the phrase that
UnlockedMasterSeed::recovery_phrase produced — or one exported from
Sage — reproduces the identical account: same wallet addresses, same
identity key, same per-profile DEKs.
§Errors
SessionError::InvalidRecoveryPhraseif the phrase is not a valid 24-word English BIP-39 mnemonic.SessionError::Keystoreif a blob already exists atpathor the write fails.
Sourcepub fn unlock_master_seed(
backend: Arc<dyn KeychainBackend>,
path: BackendKey,
password: Password,
) -> Result<UnlockedMasterSeed>
pub fn unlock_master_seed( backend: Arc<dyn KeychainBackend>, path: BackendKey, password: Password, ) -> Result<UnlockedMasterSeed>
Unlock an existing account root into an UnlockedMasterSeed.
§Errors
SessionError::LegacySeedFormatif the blob predates the versioned envelope. Its 32 bytes are a raw seed, and are never reinterpreted as BIP-39 entropy — that would silently derive a different wallet. The account must be re-enrolled viaenroll_from_recovery_phrase.SessionError::UnsupportedEnvelopeVersion/SessionError::UnsupportedSeedKindfor a blob from a newer build.SessionError::Keystoreif the blob is missing, the password is wrong, or the ciphertext is tampered.
Auto Trait Implementations§
impl Freeze for Session
impl RefUnwindSafe for Session
impl Send for Session
impl Sync for Session
impl Unpin for Session
impl UnsafeUnpin for Session
impl UnwindSafe for Session
Blanket Implementations§
Source§impl<T> BorrowMut<T> for Twhere
T: ?Sized,
impl<T> BorrowMut<T> for Twhere
T: ?Sized,
Source§fn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
impl<ST, DT> CastableFrom<ST, Initialized, Initialized> for DT
impl<ST, DT> CastableFrom<ST, Uninit, Uninit> for DT
Source§impl<T> FmtForward for T
impl<T> FmtForward for T
Source§fn fmt_binary(self) -> FmtBinary<Self>where
Self: Binary,
fn fmt_binary(self) -> FmtBinary<Self>where
Self: Binary,
self to use its Binary implementation when Debug-formatted.Source§fn fmt_display(self) -> FmtDisplay<Self>where
Self: Display,
fn fmt_display(self) -> FmtDisplay<Self>where
Self: Display,
self to use its Display implementation when
Debug-formatted.Source§fn fmt_lower_exp(self) -> FmtLowerExp<Self>where
Self: LowerExp,
fn fmt_lower_exp(self) -> FmtLowerExp<Self>where
Self: LowerExp,
self to use its LowerExp implementation when
Debug-formatted.Source§fn fmt_lower_hex(self) -> FmtLowerHex<Self>where
Self: LowerHex,
fn fmt_lower_hex(self) -> FmtLowerHex<Self>where
Self: LowerHex,
self to use its LowerHex implementation when
Debug-formatted.Source§fn fmt_octal(self) -> FmtOctal<Self>where
Self: Octal,
fn fmt_octal(self) -> FmtOctal<Self>where
Self: Octal,
self to use its Octal implementation when Debug-formatted.Source§fn fmt_pointer(self) -> FmtPointer<Self>where
Self: Pointer,
fn fmt_pointer(self) -> FmtPointer<Self>where
Self: Pointer,
self to use its Pointer implementation when
Debug-formatted.Source§fn fmt_upper_exp(self) -> FmtUpperExp<Self>where
Self: UpperExp,
fn fmt_upper_exp(self) -> FmtUpperExp<Self>where
Self: UpperExp,
self to use its UpperExp implementation when
Debug-formatted.Source§fn fmt_upper_hex(self) -> FmtUpperHex<Self>where
Self: UpperHex,
fn fmt_upper_hex(self) -> FmtUpperHex<Self>where
Self: UpperHex,
self to use its UpperHex implementation when
Debug-formatted.Source§impl<T> Pipe for Twhere
T: ?Sized,
impl<T> Pipe for Twhere
T: ?Sized,
Source§fn pipe<R>(self, func: impl FnOnce(Self) -> R) -> Rwhere
Self: Sized,
fn pipe<R>(self, func: impl FnOnce(Self) -> R) -> Rwhere
Self: Sized,
Source§fn pipe_ref<'a, R>(&'a self, func: impl FnOnce(&'a Self) -> R) -> Rwhere
R: 'a,
fn pipe_ref<'a, R>(&'a self, func: impl FnOnce(&'a Self) -> R) -> Rwhere
R: 'a,
self and passes that borrow into the pipe function. Read moreSource§fn pipe_ref_mut<'a, R>(&'a mut self, func: impl FnOnce(&'a mut Self) -> R) -> Rwhere
R: 'a,
fn pipe_ref_mut<'a, R>(&'a mut self, func: impl FnOnce(&'a mut Self) -> R) -> Rwhere
R: 'a,
self and passes that borrow into the pipe function. Read moreSource§fn pipe_borrow<'a, B, R>(&'a self, func: impl FnOnce(&'a B) -> R) -> R
fn pipe_borrow<'a, B, R>(&'a self, func: impl FnOnce(&'a B) -> R) -> R
Source§fn pipe_borrow_mut<'a, B, R>(
&'a mut self,
func: impl FnOnce(&'a mut B) -> R,
) -> R
fn pipe_borrow_mut<'a, B, R>( &'a mut self, func: impl FnOnce(&'a mut B) -> R, ) -> R
Source§fn pipe_as_ref<'a, U, R>(&'a self, func: impl FnOnce(&'a U) -> R) -> R
fn pipe_as_ref<'a, U, R>(&'a self, func: impl FnOnce(&'a U) -> R) -> R
self, then passes self.as_ref() into the pipe function.Source§fn pipe_as_mut<'a, U, R>(&'a mut self, func: impl FnOnce(&'a mut U) -> R) -> R
fn pipe_as_mut<'a, U, R>(&'a mut self, func: impl FnOnce(&'a mut U) -> R) -> R
self, then passes self.as_mut() into the pipe
function.Source§fn pipe_deref<'a, T, R>(&'a self, func: impl FnOnce(&'a T) -> R) -> R
fn pipe_deref<'a, T, R>(&'a self, func: impl FnOnce(&'a T) -> R) -> R
self, then passes self.deref() into the pipe function.impl<T> Read<Exclusive, BecauseExclusive> for Twhere
T: ?Sized,
Source§impl<T> Tap for T
impl<T> Tap for T
Source§fn tap_borrow<B>(self, func: impl FnOnce(&B)) -> Self
fn tap_borrow<B>(self, func: impl FnOnce(&B)) -> Self
Borrow<B> of a value. Read moreSource§fn tap_borrow_mut<B>(self, func: impl FnOnce(&mut B)) -> Self
fn tap_borrow_mut<B>(self, func: impl FnOnce(&mut B)) -> Self
BorrowMut<B> of a value. Read moreSource§fn tap_ref<R>(self, func: impl FnOnce(&R)) -> Self
fn tap_ref<R>(self, func: impl FnOnce(&R)) -> Self
AsRef<R> view of a value. Read moreSource§fn tap_ref_mut<R>(self, func: impl FnOnce(&mut R)) -> Self
fn tap_ref_mut<R>(self, func: impl FnOnce(&mut R)) -> Self
AsMut<R> view of a value. Read moreSource§fn tap_deref<T>(self, func: impl FnOnce(&T)) -> Self
fn tap_deref<T>(self, func: impl FnOnce(&T)) -> Self
Deref::Target of a value. Read moreSource§fn tap_deref_mut<T>(self, func: impl FnOnce(&mut T)) -> Self
fn tap_deref_mut<T>(self, func: impl FnOnce(&mut T)) -> Self
Deref::Target of a value. Read moreSource§fn tap_dbg(self, func: impl FnOnce(&Self)) -> Self
fn tap_dbg(self, func: impl FnOnce(&Self)) -> Self
.tap() only in debug builds, and is erased in release builds.Source§fn tap_mut_dbg(self, func: impl FnOnce(&mut Self)) -> Self
fn tap_mut_dbg(self, func: impl FnOnce(&mut Self)) -> Self
.tap_mut() only in debug builds, and is erased in release
builds.Source§fn tap_borrow_dbg<B>(self, func: impl FnOnce(&B)) -> Self
fn tap_borrow_dbg<B>(self, func: impl FnOnce(&B)) -> Self
.tap_borrow() only in debug builds, and is erased in release
builds.Source§fn tap_borrow_mut_dbg<B>(self, func: impl FnOnce(&mut B)) -> Self
fn tap_borrow_mut_dbg<B>(self, func: impl FnOnce(&mut B)) -> Self
.tap_borrow_mut() only in debug builds, and is erased in release
builds.Source§fn tap_ref_dbg<R>(self, func: impl FnOnce(&R)) -> Self
fn tap_ref_dbg<R>(self, func: impl FnOnce(&R)) -> Self
.tap_ref() only in debug builds, and is erased in release
builds.Source§fn tap_ref_mut_dbg<R>(self, func: impl FnOnce(&mut R)) -> Self
fn tap_ref_mut_dbg<R>(self, func: impl FnOnce(&mut R)) -> Self
.tap_ref_mut() only in debug builds, and is erased in release
builds.Source§fn tap_deref_dbg<T>(self, func: impl FnOnce(&T)) -> Self
fn tap_deref_dbg<T>(self, func: impl FnOnce(&T)) -> Self
.tap_deref() only in debug builds, and is erased in release
builds.