use std::sync::LazyLock;
use starknet::core::types::Felt;
use starknet::core::utils::get_selector_from_name;
use super::events::DecodedEvent;
use super::functions::RawCall;
use super::outside_execution::{OutsideExecutionInfo, OutsideExecutionVersion};
use crate::data::types::{SnEvent, SnTransaction};
use crate::utils::felt_to_u128;
pub static POOL_ADDRESS: LazyLock<Felt> = LazyLock::new(|| {
Felt::from_hex("0x040337b1af3c663e86e333bab5a4b28da8d4652a15a69beee2b677776ffe812a").unwrap()
});
pub const POOL_DEPLOY_BLOCK: u64 = 8978970;
struct EventSelectors {
note_used: Felt,
enc_note_created: Felt,
open_note_created: Felt,
open_note_deposited: Felt,
deposit: Felt,
withdrawal: Felt,
viewing_key_set: Felt,
}
static EVENT_SELECTORS: LazyLock<EventSelectors> = LazyLock::new(|| EventSelectors {
note_used: Felt::from_hex("0x0247fc60d782e0094e7f98c47f277d92a3345d07a436f1f56b27a9b62be2322e")
.unwrap(),
enc_note_created: Felt::from_hex(
"0x023c20207be8b1ef4430c25eef8ce779c9745ebe04139555ae81bd4f8fdd6ec5",
)
.unwrap(),
open_note_created: Felt::from_hex(
"0x022330482fd296a27cf9096807b4a3622cd619d31cce42c1e55655914e8459ee",
)
.unwrap(),
open_note_deposited: Felt::from_hex(
"0x025b6da03c4858d11cb0708d5cb6be79b190fb32eb7a7ce83804e07cbbb9bead",
)
.unwrap(),
withdrawal: Felt::from_hex(
"0x002eed7e29b3502a726faf503ac4316b7101f3da813654e8df02c13449e03da8",
)
.unwrap(),
deposit: get_selector_from_name("Deposit").unwrap(),
viewing_key_set: get_selector_from_name("ViewingKeySet").unwrap(),
});
fn classify_event(event: &DecodedEvent) -> Option<PrivacyEventKind> {
if event.contract_address != *POOL_ADDRESS {
return None;
}
let selector = event.raw.keys.first()?;
let s = &*EVENT_SELECTORS;
if *selector == s.note_used {
Some(PrivacyEventKind::NoteUsed)
} else if *selector == s.enc_note_created {
Some(PrivacyEventKind::EncNoteCreated)
} else if *selector == s.open_note_created {
Some(PrivacyEventKind::OpenNoteCreated)
} else if *selector == s.open_note_deposited {
Some(PrivacyEventKind::OpenNoteDeposited)
} else if *selector == s.deposit {
Some(PrivacyEventKind::Deposit)
} else if *selector == s.withdrawal {
Some(PrivacyEventKind::Withdrawal)
} else if *selector == s.viewing_key_set {
Some(PrivacyEventKind::ViewingKeySet)
} else {
None
}
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
enum PrivacyEventKind {
NoteUsed,
EncNoteCreated,
OpenNoteCreated,
OpenNoteDeposited,
Deposit,
Withdrawal,
ViewingKeySet,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum PoolEventMatch {
Note(Felt),
Nullifier(Felt),
}
pub fn match_pool_event(event: &SnEvent) -> Option<PoolEventMatch> {
if event.from_address != *POOL_ADDRESS {
return None;
}
let selector = event.keys.first()?;
let s = &*EVENT_SELECTORS;
let payload = event.keys.get(1).copied()?;
if *selector == s.enc_note_created {
Some(PoolEventMatch::Note(payload))
} else if *selector == s.note_used {
Some(PoolEventMatch::Nullifier(payload))
} else {
None
}
}
#[derive(Debug, Clone, Default)]
pub struct ActionMix {
pub notes_used: usize,
pub enc_notes_created: usize,
pub open_notes_created: usize,
pub open_notes_deposited: usize,
pub deposits: usize,
pub withdrawals: usize,
pub viewing_keys_set: usize,
pub invoke_external: usize,
}
impl ActionMix {
pub fn total(&self) -> usize {
self.notes_used
+ self.enc_notes_created
+ self.open_notes_created
+ self.open_notes_deposited
+ self.deposits
+ self.withdrawals
+ self.viewing_keys_set
+ self.invoke_external
}
}
#[derive(Debug, Clone)]
pub struct PublicDeposit {
pub user_addr: Felt,
pub token: Felt,
pub amount: u128,
}
#[derive(Debug, Clone)]
pub struct PublicWithdrawal {
pub to_addr: Felt,
pub token: Felt,
pub amount: u128,
}
#[derive(Debug, Clone)]
pub struct OpenNote {
pub token: Felt,
pub note_id: Felt,
}
#[derive(Debug, Clone)]
pub struct OpenNoteDeposit {
pub depositor: Felt,
pub token: Felt,
pub note_id: Felt,
pub amount: u128,
}
#[derive(Debug, Clone)]
pub struct ViewingKeyRegistration {
pub user_addr: Felt,
pub public_key: Felt,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum ViewingKeyStatus {
Valid,
Mismatch,
}
pub fn validate_viewing_key(
registration: &ViewingKeyRegistration,
supplied: &crate::decode::privacy_crypto::types::SecretFelt,
) -> ViewingKeyStatus {
let derived = crate::decode::privacy_crypto::keys::public_from_private(supplied);
if derived == registration.public_key {
ViewingKeyStatus::Valid
} else {
ViewingKeyStatus::Mismatch
}
}
#[derive(Debug, Clone)]
pub struct PrivacySummary {
pub actions: ActionMix,
pub deposits: Vec<PublicDeposit>,
pub withdrawals: Vec<PublicWithdrawal>,
pub open_notes_created: Vec<OpenNote>,
pub open_notes_deposited: Vec<OpenNoteDeposit>,
pub enc_notes_created: Vec<Felt>,
pub nullifiers: Vec<Felt>,
pub viewing_keys_set: Vec<ViewingKeyRegistration>,
pub invoke_external: Option<InvokeExternalRef>,
pub pool_fee_fri: Option<u128>,
pub paymaster: PaymasterMode,
pub intender: Option<Felt>,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum PaymasterMode {
None,
KnownRelayer,
OutsideExecution,
PrivateSponsored,
PaymasterForwarder,
}
impl PaymasterMode {
pub fn is_sponsored(&self) -> bool {
!matches!(self, Self::None)
}
}
#[derive(Debug, Clone)]
pub struct InvokeExternalRef {
pub target: Felt,
pub selector: Felt,
pub function_name: Option<String>,
}
pub fn summarize(
tx: &SnTransaction,
decoded_calls: &[RawCall],
decoded_events: &[DecodedEvent],
outside_executions: &[OutsideExecutionInfo],
) -> Option<PrivacySummary> {
let has_pool_call = decoded_calls
.iter()
.any(|c| c.contract_address == *POOL_ADDRESS);
let has_pool_oe_inner = outside_executions.iter().any(|oe| {
oe.inner_calls
.iter()
.any(|c| c.contract_address == *POOL_ADDRESS)
});
let has_pool_event = decoded_events
.iter()
.any(|e| e.contract_address == *POOL_ADDRESS);
if !(has_pool_call || has_pool_oe_inner || has_pool_event) {
return None;
}
let mut actions = ActionMix::default();
let mut deposits = Vec::new();
let mut withdrawals = Vec::new();
let mut open_notes_created = Vec::new();
let mut open_notes_deposited = Vec::new();
let mut enc_notes_created = Vec::new();
let mut nullifiers = Vec::new();
let mut viewing_keys_set = Vec::new();
for ev in decoded_events {
let Some(kind) = classify_event(ev) else {
continue;
};
match kind {
PrivacyEventKind::NoteUsed => {
actions.notes_used += 1;
if let Some(nullifier) = ev.raw.keys.get(1).copied() {
nullifiers.push(nullifier);
}
}
PrivacyEventKind::EncNoteCreated => {
actions.enc_notes_created += 1;
if let Some(note_id) = ev.raw.keys.get(1).copied() {
enc_notes_created.push(note_id);
}
}
PrivacyEventKind::OpenNoteCreated => {
actions.open_notes_created += 1;
if let (Some(token), Some(note_id)) =
(ev.raw.keys.get(1).copied(), ev.raw.keys.get(2).copied())
{
open_notes_created.push(OpenNote { token, note_id });
}
}
PrivacyEventKind::OpenNoteDeposited => {
actions.open_notes_deposited += 1;
if let (Some(depositor), Some(token), Some(note_id)) = (
ev.raw.keys.get(1).copied(),
ev.raw.keys.get(2).copied(),
ev.raw.keys.get(3).copied(),
) {
let amount = ev.raw.data.first().map(felt_to_u128).unwrap_or(0);
open_notes_deposited.push(OpenNoteDeposit {
depositor,
token,
note_id,
amount,
});
}
}
PrivacyEventKind::Deposit => {
actions.deposits += 1;
if let (Some(user_addr), Some(token)) =
(ev.raw.keys.get(1).copied(), ev.raw.keys.get(2).copied())
{
let amount = ev.raw.data.first().map(felt_to_u128).unwrap_or(0);
deposits.push(PublicDeposit {
user_addr,
token,
amount,
});
}
}
PrivacyEventKind::Withdrawal => {
actions.withdrawals += 1;
if let (Some(to_addr), Some(token)) =
(ev.raw.keys.get(1).copied(), ev.raw.keys.get(2).copied())
{
let amount = ev.raw.data.last().map(felt_to_u128).unwrap_or(0);
withdrawals.push(PublicWithdrawal {
to_addr,
token,
amount,
});
}
}
PrivacyEventKind::ViewingKeySet => {
actions.viewing_keys_set += 1;
if let (Some(user_addr), Some(public_key)) =
(ev.raw.keys.get(1).copied(), ev.raw.keys.get(2).copied())
{
viewing_keys_set.push(ViewingKeyRegistration {
user_addr,
public_key,
});
}
}
}
}
let strk_token =
Felt::from_hex("0x04718f5a0fc34cc1af16a1cdee98ffb20c31f5cd61d6ab07201858f4287c938d")
.unwrap();
let erc20_transfer_selector =
Felt::from_hex("0x0099cd8bde557814842a3121e8ddfd433a539b8c9f14bf31ebf108d12e6196e9")
.unwrap();
let mut withdrawal_match: Vec<bool> = vec![false; withdrawals.len()];
let mut fee_total: u128 = 0;
let mut saw_pool_strk_transfer = false;
for ev in decoded_events {
if ev.contract_address != strk_token
|| ev.raw.keys.first() != Some(&erc20_transfer_selector)
|| ev.raw.keys.get(1) != Some(&*POOL_ADDRESS)
{
continue;
}
saw_pool_strk_transfer = true;
let to = ev.raw.keys.get(2).copied().unwrap_or(Felt::ZERO);
let amt = ev.raw.data.first().map(felt_to_u128).unwrap_or(0);
let matched = withdrawals.iter().enumerate().position(|(i, w)| {
!withdrawal_match[i] && w.token == strk_token && w.to_addr == to && w.amount == amt
});
if let Some(idx) = matched {
withdrawal_match[idx] = true;
} else {
fee_total = fee_total.saturating_add(amt);
}
}
let pool_fee_fri = if saw_pool_strk_transfer && fee_total > 0 {
Some(fee_total)
} else {
None
};
let invoke_external = outside_executions
.iter()
.flat_map(|oe| oe.inner_calls.iter())
.find(|c| c.contract_address != *POOL_ADDRESS)
.or_else(|| {
decoded_calls
.iter()
.find(|c| c.contract_address != *POOL_ADDRESS)
})
.map(|c| InvokeExternalRef {
target: c.contract_address,
selector: c.selector,
function_name: c.function_name.clone(),
});
let paymaster = if !outside_executions.is_empty() {
if outside_executions
.iter()
.any(|oe| oe.version == OutsideExecutionVersion::PrivateSponsored)
{
PaymasterMode::PrivateSponsored
} else {
PaymasterMode::OutsideExecution
}
} else if decoded_calls
.iter()
.any(|c| is_known_paymaster_forwarder(&c.contract_address))
{
PaymasterMode::PaymasterForwarder
} else if is_known_paymaster_sender(&tx.sender()) {
PaymasterMode::KnownRelayer
} else {
PaymasterMode::None
};
let intender = outside_executions.first().map(|oe| oe.intender);
Some(PrivacySummary {
actions,
deposits,
withdrawals,
open_notes_created,
open_notes_deposited,
enc_notes_created,
nullifiers,
viewing_keys_set,
invoke_external,
pool_fee_fri,
paymaster,
intender,
})
}
fn is_known_paymaster_sender(sender: &Felt) -> bool {
PAYMASTER_FORWARDERS.iter().any(|p| p == sender)
}
fn is_known_paymaster_forwarder(addr: &Felt) -> bool {
PAYMASTER_FORWARDERS.iter().any(|p| p == addr)
}
static PAYMASTER_FORWARDERS: LazyLock<Vec<Felt>> = LazyLock::new(|| {
[
"0x0127021a1b5a52d3174c2ab077c2b043c80369250d29428cee956d76ee51584f",
"0x02314f5a43e28fdffd953b2482749f9ed21ced41bfcda186dcbcd91cc61b4054",
]
.iter()
.filter_map(|h| Felt::from_hex(h).ok())
.collect()
});
#[cfg(test)]
mod tests {
use super::*;
use crate::data::types::SnEvent;
fn make_event(from: Felt, keys: Vec<Felt>, data: Vec<Felt>) -> DecodedEvent {
DecodedEvent {
contract_address: from,
event_name: None,
decoded_keys: Vec::new(),
decoded_data: Vec::new(),
raw: SnEvent {
from_address: from,
keys,
data,
transaction_hash: Felt::ZERO,
block_number: 0,
event_index: 0,
},
}
}
fn pool() -> Felt {
*POOL_ADDRESS
}
fn pool_call() -> RawCall {
RawCall {
contract_address: pool(),
selector: Felt::ZERO,
data: Vec::new(),
function_name: Some("apply_actions".to_string()),
function_def: None,
contract_abi: None,
}
}
fn invoke_tx_with_sender(sender: Felt) -> SnTransaction {
SnTransaction::Invoke(crate::data::types::InvokeTx {
hash: Felt::ZERO,
sender_address: sender,
calldata: Vec::new(),
nonce: None,
version: Felt::from(3u64),
actual_fee: None,
execution_status: crate::data::types::ExecutionStatus::Succeeded,
block_number: 0,
index: 0,
tip: 0,
resource_bounds: None,
})
}
#[test]
fn validate_viewing_key_round_trips() {
use crate::decode::privacy_crypto::keys::public_from_private;
use crate::decode::privacy_crypto::types::SecretFelt;
let priv_key = SecretFelt::new(Felt::from(0xc0ffeeu64));
let pub_key = public_from_private(&priv_key);
let user = Felt::from(0xabcdu64);
let reg = ViewingKeyRegistration {
user_addr: user,
public_key: pub_key,
};
assert_eq!(
validate_viewing_key(®, &priv_key),
ViewingKeyStatus::Valid
);
let bad_reg = ViewingKeyRegistration {
user_addr: user,
public_key: pub_key + Felt::ONE,
};
assert_eq!(
validate_viewing_key(&bad_reg, &priv_key),
ViewingKeyStatus::Mismatch
);
}
#[test]
fn returns_none_for_non_privacy_tx() {
let tx = invoke_tx_with_sender(Felt::from(1u64));
let other_call = RawCall {
contract_address: Felt::from_hex(
"0x04270219d365d6b017231b52e92b3fb5d7c8378b05e9abc97724537a80e93b0f",
)
.unwrap(), selector: Felt::ZERO,
data: Vec::new(),
function_name: None,
function_def: None,
contract_abi: None,
};
assert!(summarize(&tx, &[other_call], &[], &[]).is_none());
}
#[test]
fn counts_action_mix_from_events() {
let s = &*EVENT_SELECTORS;
let tx = invoke_tx_with_sender(Felt::from(1u64));
let p = pool();
let null_a = Felt::from(0xAAu64);
let null_b = Felt::from(0xBBu64);
let token =
Felt::from_hex("0x04718f5a0fc34cc1af16a1cdee98ffb20c31f5cd61d6ab07201858f4287c938d")
.unwrap();
let note_id = Felt::from(0x100u64);
let to_addr = Felt::from(0xCAFEu64);
let depositor = Felt::from(0xBEEFu64);
let events = vec![
make_event(p, vec![s.note_used, null_a], vec![]),
make_event(p, vec![s.note_used, null_b], vec![]),
make_event(
p,
vec![s.open_note_created, token, note_id],
vec![Felt::ZERO; 3], ),
make_event(
p,
vec![s.withdrawal, to_addr, token],
vec![
Felt::ZERO,
Felt::ZERO,
Felt::ZERO,
Felt::from(0xde0b6b3a7640000u128),
],
),
make_event(
p,
vec![s.open_note_deposited, depositor, token, note_id],
vec![Felt::from(0xde0b6b3a7640000u128), Felt::ZERO],
),
];
let summary = summarize(&tx, &[pool_call()], &events, &[]).expect("privacy tx");
assert_eq!(summary.actions.notes_used, 2);
assert_eq!(summary.actions.open_notes_created, 1);
assert_eq!(summary.actions.withdrawals, 1);
assert_eq!(summary.actions.open_notes_deposited, 1);
assert_eq!(summary.actions.total(), 5);
assert_eq!(summary.nullifiers, vec![null_a, null_b]);
assert_eq!(summary.withdrawals.len(), 1);
assert_eq!(summary.withdrawals[0].to_addr, to_addr);
assert_eq!(summary.withdrawals[0].token, token);
assert_eq!(summary.withdrawals[0].amount, 0xde0b6b3a7640000u128);
assert_eq!(summary.open_notes_deposited[0].depositor, depositor);
assert_eq!(
summary.open_notes_deposited[0].amount,
0xde0b6b3a7640000u128
);
}
#[test]
fn detects_paymaster_sender() {
let avnu =
Felt::from_hex("0x0127021a1b5a52d3174c2ab077c2b043c80369250d29428cee956d76ee51584f")
.unwrap();
let tx = invoke_tx_with_sender(avnu);
let summary = summarize(&tx, &[pool_call()], &[], &[]).unwrap();
assert_eq!(summary.paymaster, PaymasterMode::KnownRelayer);
assert!(summary.paymaster.is_sponsored());
}
#[test]
fn detects_oe_wrapped_pool_call() {
let s = &*EVENT_SELECTORS;
let strk =
Felt::from_hex("0x4718f5a0fc34cc1af16a1cdee98ffb20c31f5cd61d6ab07201858f4287c938d")
.unwrap();
let avnu_forwarder =
Felt::from_hex("0x0127021a1b5a52d3174c2ab077c2b043c80369250d29428cee956d76ee51584f")
.unwrap();
let relayer = Felt::from_hex("0x22d28").unwrap();
let tx = invoke_tx_with_sender(relayer);
let approve = RawCall {
contract_address: strk,
selector: Felt::ZERO,
data: Vec::new(),
function_name: Some("transfer".into()),
function_def: None,
contract_abi: None,
};
let forwarder_call = RawCall {
contract_address: avnu_forwarder,
selector: Felt::ZERO,
data: Vec::new(),
function_name: Some("execute_from_outside_v2".into()),
function_def: None,
contract_abi: None,
};
let user_addr = Felt::from(0xCAFEu64);
let oe = OutsideExecutionInfo {
intender: user_addr,
caller: avnu_forwarder,
nonce: Felt::ZERO,
execute_after: 0,
execute_before: u64::MAX,
inner_calls: vec![RawCall {
contract_address: pool(),
selector: Felt::ZERO,
data: Vec::new(),
function_name: Some("apply_actions".into()),
function_def: None,
contract_abi: None,
}],
signature: Vec::new(),
version: super::super::outside_execution::OutsideExecutionVersion::V2,
};
let pool_to_forwarder_amount: u128 = 0x3782dace9d900000;
let events = vec![
DecodedEvent {
contract_address: strk,
event_name: None,
decoded_keys: Vec::new(),
decoded_data: Vec::new(),
raw: SnEvent {
from_address: strk,
keys: vec![
Felt::from_hex(
"0x99cd8bde557814842a3121e8ddfd433a539b8c9f14bf31ebf108d12e6196e9",
)
.unwrap(),
pool(),
avnu_forwarder,
],
data: vec![Felt::from(pool_to_forwarder_amount), Felt::ZERO],
transaction_hash: Felt::ZERO,
block_number: 0,
event_index: 0,
},
},
make_event(
pool(),
vec![s.withdrawal, avnu_forwarder, strk],
vec![
Felt::ZERO,
Felt::ZERO,
Felt::ZERO,
Felt::from(pool_to_forwarder_amount),
],
),
];
let summary = summarize(&tx, &[approve, forwarder_call], &events, &[oe])
.expect("OE-wrapped pool call should still be recognized as a privacy tx");
assert_eq!(summary.actions.withdrawals, 1);
assert!(
summary.pool_fee_fri.is_none(),
"withdrawal payout must not be counted as the pool fee"
);
assert_eq!(summary.paymaster, PaymasterMode::OutsideExecution);
assert_eq!(summary.intender, Some(user_addr));
}
#[test]
fn detects_private_sponsored_oe() {
let avnu_forwarder =
Felt::from_hex("0x0127021a1b5a52d3174c2ab077c2b043c80369250d29428cee956d76ee51584f")
.unwrap();
let relayer = Felt::from_hex("0x22d28").unwrap();
let tx = invoke_tx_with_sender(relayer);
let forwarder_call = RawCall {
contract_address: avnu_forwarder,
selector: Felt::ZERO,
data: Vec::new(),
function_name: Some("execute_private_sponsored".into()),
function_def: None,
contract_abi: None,
};
let oe = OutsideExecutionInfo {
intender: avnu_forwarder,
caller: Felt::ZERO,
nonce: Felt::ZERO,
execute_after: 0,
execute_before: u64::MAX,
inner_calls: vec![RawCall {
contract_address: pool(),
selector: Felt::ZERO,
data: Vec::new(),
function_name: Some("apply_actions".into()),
function_def: None,
contract_abi: None,
}],
signature: Vec::new(),
version: super::super::outside_execution::OutsideExecutionVersion::PrivateSponsored,
};
let summary = summarize(&tx, &[forwarder_call], &[], &[oe])
.expect("OE-wrapped pool call should be recognized as a privacy tx");
assert_eq!(summary.paymaster, PaymasterMode::PrivateSponsored);
assert!(summary.paymaster.is_sponsored());
}
fn raw_event(from: Felt, keys: Vec<Felt>, tx_hash: Felt) -> SnEvent {
SnEvent {
from_address: from,
keys,
data: Vec::new(),
transaction_hash: tx_hash,
block_number: 0,
event_index: 0,
}
}
#[test]
fn match_pool_event_returns_note_id_for_enc_note_created() {
let s = &*EVENT_SELECTORS;
let note_id = Felt::from(0xC0FFEEu64);
let ev = raw_event(pool(), vec![s.enc_note_created, note_id], Felt::ZERO);
assert_eq!(match_pool_event(&ev), Some(PoolEventMatch::Note(note_id)));
}
#[test]
fn match_pool_event_returns_nullifier_for_note_used() {
let s = &*EVENT_SELECTORS;
let nullifier = Felt::from(0xDEADBEEFu64);
let ev = raw_event(pool(), vec![s.note_used, nullifier], Felt::ZERO);
assert_eq!(
match_pool_event(&ev),
Some(PoolEventMatch::Nullifier(nullifier))
);
}
#[test]
fn match_pool_event_ignores_non_pool_events() {
let s = &*EVENT_SELECTORS;
let other = Felt::from(0xBEEFu64);
let ev = raw_event(
other,
vec![s.enc_note_created, Felt::from(1u64)],
Felt::ZERO,
);
assert_eq!(match_pool_event(&ev), None);
}
#[test]
fn match_pool_event_ignores_other_pool_events() {
let s = &*EVENT_SELECTORS;
let ev = raw_event(
pool(),
vec![s.deposit, Felt::from(1u64), Felt::from(2u64)],
Felt::ZERO,
);
assert_eq!(match_pool_event(&ev), None);
}
#[test]
fn match_pool_event_handles_truncated_keys() {
let s = &*EVENT_SELECTORS;
let ev = raw_event(pool(), vec![s.enc_note_created], Felt::ZERO);
assert_eq!(match_pool_event(&ev), None);
}
}