feat(discovery-core): add secretfelt type and unify key param naming

.claude/rules/code-style.md

@@ -154,3 +154,10 @@ Apply these guidelines when writing or reviewing code in this codebase.
 - Place public functions at the top of the module, before their private helpers
 - Readers should encounter the high-level orchestration first and drill into details top-down
 - *Example:* `pub async fn sync_incoming_state(...)` at the top, followed by `process_channel(...)`, then `process_subchannel(...)`
+
+### Imports at scope top, not inline
+- Place `use` statements at the top of the scope they serve — module-level for module-wide usage, `#[cfg(test)] mod tests` top for test-only usage
+- Never put `use` inside function bodies; hoist to the enclosing module
+- Use short imported names in signatures and bodies, not inline qualified paths like `super::types::Foo` or `crate::module::Bar`
+- *Bad:* `fn f(key: &super::types::SecretFelt)` with no import; `use crate::Foo;` inside a function body
+- *Good:* `use super::types::SecretFelt;` at module top, then `fn f(key: &SecretFelt)`

.claude/skills/pr-splitter/SKILL.md

@@ -346,7 +346,7 @@ If anything fails, fix before reporting to user.
 
 #### 7f. Report to user
 
-Brief: files applied, verification result, any warnings. Changes are staged.
+Brief: files applied, verification result, any warnings. Suggest a commit message.
 
 #### 7g. Update plan and track progress
 

crates/discovery-core/Cargo.toml

@@ -12,10 +12,11 @@ starknet-crypto = "0.8"
 starknet-types-core = { version = "0.2", features = ["curve", "serde"] }
 starknet-providers = "0.16"
 tracing = "0.1"
+serde = { version = "1.0", features = ["derive"] }
 url = "2"
+zeroize = "1"
 
 [dev-dependencies]
-serde = { version = "1.0", features = ["derive"] }
 serde_json = "1.0"
 tokio = { version = "1", features = ["rt-multi-thread", "macros"] }
 tracing-subscriber = { version = "0.3", features = ["env-filter"] }

crates/discovery-core/src/discovery/incoming_channels.rs

@@ -8,7 +8,7 @@ use starknet_types_core::felt::Felt;
 use super::{DiscoveryError, COST_CHANNEL_INFO, COST_NUM_CHANNELS};
 use crate::io_budget::IoBudget;
 use crate::privacy_pool::decryption::decrypt_channel_info;
-use crate::privacy_pool::types::ChannelInfo;
+use crate::privacy_pool::types::{ChannelInfo, SecretFelt};
 use crate::privacy_pool::views::IViews;
 
 /// A discovered and decrypted incoming channel.
@@ -74,7 +74,7 @@ pub async fn get_incoming_channel_count<PrivacyPool: IViews>(
 pub async fn discover_incoming_channels<PrivacyPool: IViews>(
     privacy_pool: &PrivacyPool,
     recipient_addr: Felt,
-    private_key: &Felt,
+    private_key: &SecretFelt,
     start_index: u64,
     total_n_channels: u64,
     budget: &IoBudget,
@@ -135,7 +135,7 @@ mod tests {
     async fn test_discover_no_channels() {
         let backend = MockBackend::empty();
         let recipient = Felt::from_hex_unchecked("0x123");
-        let key = Felt::from(1u64);
+        let key = SecretFelt::new(Felt::from(1u64));
         let budget = IoBudget::new(100);
 
         // Test with 0 (start from beginning)
@@ -171,7 +171,7 @@ mod tests {
         let result = discover_incoming_channels(
             &backend,
             fixture.constants.alice_address,
-            &fixture.constants.alice_viewing_key,
+            &SecretFelt::new(fixture.constants.alice_viewing_key),
             0,
             count,
             &budget,
@@ -205,7 +205,7 @@ mod tests {
         let result = discover_incoming_channels(
             &backend,
             fixture.constants.bob_address,
-            &fixture.constants.bob_viewing_key,
+            &SecretFelt::new(fixture.constants.bob_viewing_key),
             0,
             count,
             &budget,
@@ -240,7 +240,7 @@ mod tests {
         let result1 = discover_incoming_channels(
             &backend,
             fixture.constants.alice_address,
-            &fixture.constants.alice_viewing_key,
+            &SecretFelt::new(fixture.constants.alice_viewing_key),
             0,
             count,
             &budget,
@@ -257,7 +257,7 @@ mod tests {
         let result2 = discover_incoming_channels(
             &backend,
             fixture.constants.alice_address,
-            &fixture.constants.alice_viewing_key,
+            &SecretFelt::new(fixture.constants.alice_viewing_key),
             result1.last_index.unwrap() + 1,
             count,
             &budget,
@@ -302,7 +302,7 @@ mod tests {
         let result = discover_incoming_channels(
             &backend,
             fixture.constants.alice_address,
-            &fixture.constants.alice_viewing_key,
+            &SecretFelt::new(fixture.constants.alice_viewing_key),
             0,
             count,
             &budget,

crates/discovery-core/src/privacy_pool/decryption.rs

@@ -7,10 +7,13 @@ use starknet_types_core::{curve::AffinePoint, felt::Felt};
 use thiserror::Error;
 
 use super::hashes::{
-    compute_enc_amount_hash, compute_enc_channel_key_hash, compute_enc_sender_addr_hash,
-    compute_enc_token_hash,
+    compute_enc_amount_hash, compute_enc_channel_key_hash, compute_enc_recipient_addr_hash,
+    compute_enc_sender_addr_hash, compute_enc_token_hash,
+};
+use super::types::{
+    felt_low_u128, ChannelInfo, EncChannelInfo, EncOutgoingChannelInfo, EncSubchannelInfo,
+    SecretFelt,
 };
-use super::types::{felt_low_u128, ChannelInfo, EncChannelInfo, EncSubchannelInfo};
 
 /// Errors that can occur during decryption.
 #[derive(Debug, Error)]
@@ -26,18 +29,14 @@ pub enum DecryptionError {
 /// 1. Recover the ephemeral public key point from its x-coordinate
 /// 2. Compute ECDH shared secret: `shared_point = ephemeral_pubkey * private_key`
 /// 3. Decrypt: `plaintext = ciphertext - hash(tag, shared_x)`
-///
-/// # Security
-///
-/// The caller should zero the `private_key` after use by calling `private_key.zeroize()`.
 pub fn decrypt_channel_info(
     enc: &EncChannelInfo,
-    private_key: &Felt,
+    private_key: &SecretFelt,
 ) -> Result<ChannelInfo, DecryptionError> {
     // Recover the ephemeral public key from x-coordinate..
     let ephemeral_point = AffinePoint::new_from_x(&enc.ephemeral_pubkey, false)
         .ok_or(DecryptionError::InvalidEphemeralPubkey)?;
-    let shared_point = &ephemeral_point * *private_key;
+    let shared_point = &ephemeral_point * **private_key;
     let shared_x = shared_point.x();
 
     // Decrypt: plaintext = ciphertext - hash(tag, shared_x)
@@ -99,6 +98,19 @@ pub fn decrypt_note_amount(
     enc_amount.wrapping_sub(pad)
 }
 
+/// Decrypts an outgoing channel's encrypted recipient address.
+///
+/// `recipient_addr = enc_recipient_addr - hash(ENC_RECIPIENT_ADDR_TAG, sender_addr, private_key, index, 0, salt)`
+pub fn decrypt_outgoing_recipient_addr(
+    enc: &EncOutgoingChannelInfo,
+    sender_addr: Felt,
+    private_key: &SecretFelt,
+    index: u64,
+) -> Felt {
+    let mask = compute_enc_recipient_addr_hash(sender_addr, private_key, index, enc.salt);
+    enc.enc_recipient_addr - mask
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;
@@ -111,7 +123,7 @@ mod tests {
             enc_channel_key: Felt::ONE,
             enc_sender_addr: Felt::TWO,
         };
-        let result = decrypt_channel_info(&enc, &Felt::from(12345u64));
+        let result = decrypt_channel_info(&enc, &SecretFelt::new(Felt::from(12345u64)));
         assert!(matches!(
             result,
             Err(DecryptionError::InvalidEphemeralPubkey)
@@ -128,8 +140,8 @@ mod tests {
             enc_sender_addr: f.outputs.enc_channel_sender_addr,
         };
 
-        let result = decrypt_channel_info(&encrypted, &f.inputs.recipient_private_key)
-            .expect("decryption should succeed");
+        let key = SecretFelt::new(f.inputs.recipient_private_key);
+        let result = decrypt_channel_info(&encrypted, &key).expect("decryption should succeed");
 
         assert_eq!(result.channel_key, f.inputs.channel_key);
         assert_eq!(result.sender_addr, f.inputs.sender);
@@ -167,4 +179,20 @@ mod tests {
         );
         assert_eq!(amount, f.outputs.dec_note_amount as u128);
     }
+
+    #[test]
+    fn test_decrypt_outgoing_recipient_addr_with_cairo_vectors() {
+        let f = load_cairo_ref_fixture();
+
+        let enc = EncOutgoingChannelInfo {
+            salt: f.outputs.enc_outgoing_salt,
+            enc_recipient_addr: f.outputs.enc_outgoing_recipient_addr,
+        };
+
+        let key = SecretFelt::new(f.inputs.sender_private_key);
+        let recipient =
+            decrypt_outgoing_recipient_addr(&enc, f.inputs.sender, &key, f.inputs.index);
+
+        assert_eq!(recipient, f.inputs.recipient);
+    }
 }

crates/discovery-core/src/privacy_pool/hashes.rs

@@ -5,6 +5,8 @@ use std::sync::LazyLock;
 use starknet_crypto::{poseidon_hash_many, PoseidonHasher};
 use starknet_types_core::felt::Felt;
 
+use super::types::SecretFelt;
+
 /// Domain separation tag for encrypted channel key.
 static ENC_CHANNEL_KEY_TAG: LazyLock<Felt> =
     LazyLock::new(|| short_string_to_felt("ENC_CHANNEL_KEY_TAG:V1"));
@@ -126,29 +128,29 @@ pub fn compute_nullifier(
     channel_key: Felt,
     token: Felt,
     index: u64,
-    decryption_key: &Felt,
+    private_key: &SecretFelt,
 ) -> Felt {
     hash(&[
         *NULLIFIER_TAG,
         channel_key,
         token,
         Felt::from(index),
         Felt::ZERO,
-        *decryption_key,
+        **private_key,
     ])
 }
 
 /// Computes the channel key from sender credentials and recipient identity.
 pub fn compute_channel_key(
     sender_addr: Felt,
-    decryption_key: &Felt,
+    private_key: &SecretFelt,
     recipient_addr: Felt,
     recipient_public_key: Felt,
 ) -> Felt {
     hash(&[
         *CHANNEL_KEY_TAG,
         sender_addr,
-        *decryption_key,
+        **private_key,
         recipient_addr,
         recipient_public_key,
     ])
@@ -187,11 +189,15 @@ pub fn compute_subchannel_marker(
 }
 
 /// Computes the outgoing channel id for storage lookup.
-pub fn compute_outgoing_channel_id(sender_addr: Felt, decryption_key: &Felt, index: u64) -> Felt {
+pub fn compute_outgoing_channel_id(
+    sender_addr: Felt,
+    private_key: &SecretFelt,
+    index: u64,
+) -> Felt {
     hash(&[
         *OUTGOING_CHANNEL_ID_TAG,
         sender_addr,
-        *decryption_key,
+        **private_key,
         Felt::from(index),
         Felt::ZERO,
     ])
@@ -200,14 +206,14 @@ pub fn compute_outgoing_channel_id(sender_addr: Felt, decryption_key: &Felt, ind
 /// Computes the encryption mask for the outgoing recipient address.
 pub fn compute_enc_recipient_addr_hash(
     sender_addr: Felt,
-    decryption_key: &Felt,
+    private_key: &SecretFelt,
     index: u64,
     salt: Felt,
 ) -> Felt {
     hash(&[
         *ENC_RECIPIENT_ADDR_TAG,
         sender_addr,
-        *decryption_key,
+        **private_key,
         Felt::from(index),
         Felt::ZERO,
         salt,
@@ -217,6 +223,7 @@ pub fn compute_enc_recipient_addr_hash(
 #[cfg(test)]
 mod tests {
     use super::*;
+    use crate::privacy_pool::types::SecretFelt;
     use crate::test_fixtures::load_cairo_ref_fixture;
 
     #[test]
@@ -275,7 +282,7 @@ mod tests {
                 f.inputs.channel_key,
                 f.inputs.token,
                 f.inputs.index,
-                &f.inputs.sender_private_key,
+                &SecretFelt::new(f.inputs.sender_private_key),
             ),
             f.outputs.nullifier
         );
@@ -296,7 +303,7 @@ mod tests {
     #[test]
     fn test_compute_channel_key() {
         let f = load_cairo_ref_fixture();
-        let key = f.inputs.sender_private_key;
+        let key = SecretFelt::new(f.inputs.sender_private_key);
         assert_eq!(
             compute_channel_key(
                 f.inputs.sender,
@@ -311,7 +318,7 @@ mod tests {
     #[test]
     fn test_compute_outgoing_channel_id() {
         let f = load_cairo_ref_fixture();
-        let key = f.inputs.sender_private_key;
+        let key = SecretFelt::new(f.inputs.sender_private_key);
         assert_eq!(
             compute_outgoing_channel_id(f.inputs.sender, &key, f.inputs.index),
             f.outputs.outgoing_channel_id
@@ -321,7 +328,7 @@ mod tests {
     #[test]
     fn test_compute_enc_recipient_addr_hash() {
         let f = load_cairo_ref_fixture();
-        let key = f.inputs.sender_private_key;
+        let key = SecretFelt::new(f.inputs.sender_private_key);
         assert_eq!(
             compute_enc_recipient_addr_hash(f.inputs.sender, &key, f.inputs.index, f.inputs.salt),
             f.outputs.enc_recipient_addr_hash