feat: Note transport E2E encryption

Author: v0-e

bin/integration-tests/src/tests/transport.rs

@@ -2,7 +2,6 @@ use std::sync::Arc;
 
 use anyhow::{Context, Result};
 use miden_client::account::AccountStorageMode;
-use miden_client::address::{Address, AddressInterface, RoutingParameters};
 use miden_client::asset::FungibleAsset;
 use miden_client::auth::RPO_FALCON_SCHEME_ID;
 use miden_client::keystore::FilesystemKeyStore;
@@ -165,10 +164,16 @@ async fn run_flow(
     .await
     .context("failed to insert faucet in sender")?;
 
-    // Build recipient address
-    let recipient_address = Address::new(recipient_account.id())
-        .with_routing_parameters(RoutingParameters::new(AddressInterface::BasicWallet))
-        .context("failed to build recipient address")?;
+    // Get a recipient's address
+    let recipient_addresses = recipient
+        .test_store()
+        .get_addresses_by_account_id(recipient_account.id())
+        .await
+        .context("failed to get recipient addresses")?;
+    let recipient_address = recipient_addresses
+        .first()
+        .context("recipient should have a default address (with encryption key)")?
+        .clone();
 
     // Ensure recipient has no input notes
     recipient.sync_state().await.context("recipient initial sync")?;

bin/miden-cli/src/lib.rs

@@ -188,10 +188,15 @@ impl Cli {
         let keystore = CliKeyStore::new(cli_config.secret_keys_directory.clone())
             .map_err(CliError::KeyStore)?;
 
+        // Create encryption keystore (shares directory with auth keystore)
+        let encryption_keystore = CliKeyStore::new(cli_config.secret_keys_directory.clone())
+            .map_err(CliError::KeyStore)?;
+
         let mut builder = ClientBuilder::new()
             .sqlite_store(cli_config.store_filepath.clone())
             .grpc_client(&cli_config.rpc.endpoint.clone().into(), Some(cli_config.rpc.timeout_ms))
             .authenticator(Arc::new(keystore.clone()))
+            .encryption_keystore(Arc::new(encryption_keystore))
             .in_debug_mode(in_debug_mode)
             .tx_graceful_blocks(Some(TX_GRACEFUL_BLOCK_DELTA));
 

bin/miden-cli/tests/cli.rs

@@ -1074,12 +1074,14 @@ async fn create_rust_client_with_store_path(
 
     let keystore = CliKeyStore::new(temp_dir())?;
 
+    let encryption_keystore = Arc::new(keystore.clone());
     Ok((
         TestClient::new(
             Arc::new(GrpcClient::new(&endpoint, 10_000)),
             rng,
             store,
             Some(std::sync::Arc::new(keystore.clone())),
+            Some(encryption_keystore),
             ExecutionOptions::new(
                 Some(MAX_TX_EXECUTION_CYCLES),
                 MIN_TX_EXECUTION_CYCLES,

crates/idxdb-store/src/lib.rs

@@ -324,6 +324,9 @@ impl Store for WebStore {
     async fn list_setting_keys(&self) -> Result<Vec<String>, StoreError> {
         self.list_setting_keys().await
     }
+
+    // ENCRYPTION KEYS
+    // --------------------------------------------------------------------------------------------
 }
 
 // UTILS

crates/rust-client/src/account/mod.rs

@@ -39,6 +39,9 @@ use alloc::vec::Vec;
 use miden_lib::account::auth::{AuthEcdsaK256Keccak, AuthRpoFalcon512};
 use miden_lib::account::wallets::BasicWallet;
 use miden_objects::account::auth::PublicKey;
+use miden_objects::address::RoutingParameters;
+use miden_objects::crypto::dsa::eddsa_25519::SecretKey;
+use miden_objects::crypto::ies::{SealingKey, UnsealingKey};
 use miden_objects::note::NoteTag;
 // RE-EXPORTS
 // ================================================================================================
@@ -165,7 +168,40 @@ impl<AUTH> Client<AUTH> {
 
         match tracked_account {
             None => {
-                let default_address = Address::new(account.id());
+                // Generate encryption key pair and create default address with public key
+                let default_address = if let Some(ref keystore) = self.encryption_keystore {
+                    // Generate encryption X25519 key pair
+                    let mut rng = rand::rng();
+                    let secret_key = SecretKey::with_rng(&mut rng);
+                    let public_key = secret_key.public_key();
+
+                    let sealing_key = SealingKey::X25519XChaCha20Poly1305(public_key);
+                    let unsealing_key = UnsealingKey::X25519XChaCha20Poly1305(secret_key);
+
+                    // Create address with encryption key
+                    let address = Address::new(account.id())
+                        .with_routing_parameters(
+                            RoutingParameters::new(AddressInterface::BasicWallet)
+                                .with_encryption_key(sealing_key),
+                        )
+                        .map_err(|e| {
+                            ClientError::ClientInitializationError(format!(
+                                "Failed to create address with encryption key: {e}"
+                            ))
+                        })?;
+
+                    // Store key in keystore by address
+                    keystore.add_encryption_key(&address, &unsealing_key).map_err(|e| {
+                        ClientError::ClientInitializationError(format!(
+                            "Failed to store encryption key: {e}"
+                        ))
+                    })?;
+
+                    address
+                } else {
+                    // No keystore - use plain address
+                    Address::new(account.id())
+                };
 
                 // If the account is not being tracked, insert it into the store regardless of the
                 // `overwrite` flag

crates/rust-client/src/builder.rs

@@ -8,7 +8,7 @@ use miden_tx::ExecutionOptions;
 use miden_tx::auth::TransactionAuthenticator;
 use rand::Rng;
 
-use crate::keystore::FilesystemKeyStore;
+use crate::keystore::{EncryptionKeyStore, FilesystemKeyStore};
 use crate::note_transport::NoteTransportClient;
 use crate::rpc::NodeRpcClient;
 use crate::store::{Store, StoreError};
@@ -36,6 +36,16 @@ enum AuthenticatorConfig<AUTH> {
     Instance(Arc<AUTH>),
 }
 
+/// Represents the configuration for an encryption keystore.
+///
+/// This enum defers encryption keystore instantiation until the build phase.
+enum EncryptionKeystoreConfig {
+    /// Use a filesystem keystore at the given path.
+    Path(String),
+    /// Use a custom encryption keystore instance.
+    Instance(Arc<dyn EncryptionKeyStore + Send + Sync>),
+}
+
 // STORE BUILDER
 // ================================================================================================
 
@@ -59,8 +69,7 @@ pub trait StoreFactory {
 /// A builder for constructing a Miden client.
 ///
 /// This builder allows you to configure the various components required by the client, such as the
-/// RPC endpoint, store, RNG, and keystore. It is generic over the keystore type. By default, it
-/// uses `FilesystemKeyStore<rand::rngs::StdRng>`.
+/// RPC endpoint, store, RNG, and keystore. It is generic over the authenticator type.
 pub struct ClientBuilder<AUTH> {
     /// An optional custom RPC client. If provided, this takes precedence over `rpc_endpoint`.
     rpc_api: Option<Arc<dyn NodeRpcClient>>,
@@ -70,6 +79,8 @@ pub struct ClientBuilder<AUTH> {
     rng: Option<Box<dyn FeltRng>>,
     /// The keystore configuration provided by the user.
     keystore: Option<AuthenticatorConfig<AUTH>>,
+    /// The encryption keystore configuration.
+    encryption_keystore: Option<EncryptionKeystoreConfig>,
     /// A flag to enable debug mode.
     in_debug_mode: DebugMode,
     /// The number of blocks that are considered old enough to discard pending transactions. If
@@ -91,6 +102,7 @@ impl<AUTH> Default for ClientBuilder<AUTH> {
             store: None,
             rng: None,
             keystore: None,
+            encryption_keystore: None,
             in_debug_mode: DebugMode::Disabled,
             tx_graceful_blocks: Some(TX_GRACEFUL_BLOCKS),
             max_block_number_delta: None,
@@ -154,6 +166,16 @@ where
         self
     }
 
+    /// Optionally provide a custom encryption keystore instance.
+    #[must_use]
+    pub fn encryption_keystore<ENC>(mut self, keystore: Arc<ENC>) -> Self
+    where
+        ENC: EncryptionKeyStore + Send + Sync + 'static,
+    {
+        self.encryption_keystore = Some(EncryptionKeystoreConfig::Instance(keystore));
+        self
+    }
+
     /// Optionally set a maximum number of blocks that the client can be behind the network.
     /// By default, there's no maximum.
     #[must_use]
@@ -175,9 +197,11 @@ where
     ///
     /// This stores the keystore path as a configuration option so that actual keystore
     /// initialization is deferred until `build()`. This avoids panicking during builder chaining.
+    /// The same directory will be used for both authentication and encryption keys.
     #[must_use]
     pub fn filesystem_keystore(mut self, keystore_path: &str) -> Self {
         self.keystore = Some(AuthenticatorConfig::Path(keystore_path.to_string()));
+        self.encryption_keystore = Some(EncryptionKeystoreConfig::Path(keystore_path.to_string()));
         self
     }
 
@@ -241,16 +265,29 @@ where
             Some(AuthenticatorConfig::Path(ref path)) => {
                 let keystore = FilesystemKeyStore::new(path.into())
                     .map_err(|err| ClientError::ClientInitializationError(err.to_string()))?;
-                Some(Arc::new(AUTH::from(keystore)))
+                Some(Arc::new(AUTH::from_keystore(keystore)))
             },
             None => None,
         };
 
+        // Initialize the encryption keystore.
+        let encryption_keystore: Option<Arc<dyn EncryptionKeyStore + Send + Sync>> =
+            match self.encryption_keystore {
+                Some(EncryptionKeystoreConfig::Instance(ks)) => Some(ks),
+                Some(EncryptionKeystoreConfig::Path(ref path)) => {
+                    let keystore = FilesystemKeyStore::new(path.into())
+                        .map_err(|err| ClientError::ClientInitializationError(err.to_string()))?;
+                    Some(Arc::new(keystore))
+                },
+                None => None,
+            };
+
         Client::new(
             rpc_api,
             rng,
             store,
             authenticator,
+            encryption_keystore,
             ExecutionOptions::new(
                 Some(MAX_TX_EXECUTION_CYCLES),
                 MIN_TX_EXECUTION_CYCLES,
@@ -271,12 +308,14 @@ where
 // ================================================================================================
 
 /// Marker trait to capture the bounds the builder requires for the authenticator type
-/// parameter
-pub trait BuilderAuthenticator:
-    TransactionAuthenticator + From<FilesystemKeyStore<rand::rngs::StdRng>> + 'static
-{
+/// parameter.
+pub trait BuilderAuthenticator: TransactionAuthenticator + 'static {
+    /// Creates an authenticator from a `FilesystemKeyStore`.
+    fn from_keystore(keystore: FilesystemKeyStore<rand::rngs::StdRng>) -> Self;
 }
-impl<T> BuilderAuthenticator for T where
-    T: TransactionAuthenticator + From<FilesystemKeyStore<rand::rngs::StdRng>> + 'static
-{
+
+impl BuilderAuthenticator for FilesystemKeyStore<rand::rngs::StdRng> {
+    fn from_keystore(keystore: FilesystemKeyStore<rand::rngs::StdRng>) -> Self {
+        keystore
+    }
 }