clawpowers 1.1.4 → 2.2.0

package/native/crates/fee/src/lib.rs

@@ -0,0 +1,281 @@
+//! clawpowers-fee — Fee schedule calculation for transactions and swaps.
+//!
+//! [`FeeSchedule`] holds basis-point rates for different operation types and
+//! computes the fee for a given [`TokenAmount`].
+
+use alloy_primitives::Address;
+use clawpowers_tokens::{TokenAmount, TokenError};
+use serde::{Deserialize, Serialize};
+use thiserror::Error;
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+/// Default transaction fee: 77 bps = 0.77%.
+pub const DEFAULT_TX_FEE_BPS: u64 = 77;
+
+/// Default swap fee: 30 bps = 0.30%.
+pub const DEFAULT_SWAP_FEE_BPS: u64 = 30;
+
+/// Placeholder fee recipient address used by [`FeeSchedule::default`].
+pub const PLACEHOLDER_FEE_RECIPIENT: Address = Address::ZERO;
+
+// ---------------------------------------------------------------------------
+// FeeType
+// ---------------------------------------------------------------------------
+
+/// Fee classification.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum FeeType {
+    /// Standard on-chain transaction fee.
+    Transaction,
+    /// DEX swap fee.
+    Swap,
+    /// Custom fee with explicit basis points.
+    Custom(u64),
+}
+
+// ---------------------------------------------------------------------------
+// Errors
+// ---------------------------------------------------------------------------
+
+/// Errors produced by fee operations.
+#[derive(Debug, Error, PartialEq, Eq)]
+pub enum FeeError {
+    /// Token arithmetic failed.
+    #[error("token arithmetic error: {0}")]
+    Token(String),
+    /// Basis-point rate exceeds 10 000 (100%).
+    #[error("invalid basis points: {0} (max 10000)")]
+    InvalidBps(u64),
+    /// Computed fee would exceed the gross amount.
+    #[error("fee ({fee_bps} bps) would exceed gross amount")]
+    FeeExceedsAmount {
+        /// The basis-point rate that caused the violation.
+        fee_bps: u64,
+    },
+}
+
+impl From<TokenError> for FeeError {
+    fn from(e: TokenError) -> Self {
+        FeeError::Token(e.to_string())
+    }
+}
+
+// ---------------------------------------------------------------------------
+// FeeCalculation
+// ---------------------------------------------------------------------------
+
+/// The result of a fee calculation.
+#[derive(Debug, Clone)]
+pub struct FeeCalculation {
+    /// The original, pre-fee amount.
+    pub gross_amount: TokenAmount,
+    /// The fee portion deducted from `gross_amount`.
+    pub fee_amount: TokenAmount,
+    /// The amount remaining after fee deduction.
+    pub net_amount: TokenAmount,
+    /// The address that will receive the fee.
+    pub fee_recipient: Address,
+    /// The type of fee that was applied.
+    pub fee_type: FeeType,
+}
+
+// ---------------------------------------------------------------------------
+// FeeSchedule
+// ---------------------------------------------------------------------------
+
+/// Configures fee rates and the recipient address for the protocol.
+#[derive(Debug, Clone)]
+pub struct FeeSchedule {
+    /// Transaction fee in basis points (default: 77 = 0.77%).
+    pub tx_fee_bps: u64,
+    /// Swap fee in basis points (default: 30 = 0.30%).
+    pub swap_fee_bps: u64,
+    /// Address that accumulates collected fees.
+    pub fee_recipient: Address,
+}
+
+impl Default for FeeSchedule {
+    fn default() -> Self {
+        Self {
+            tx_fee_bps: DEFAULT_TX_FEE_BPS,
+            swap_fee_bps: DEFAULT_SWAP_FEE_BPS,
+            fee_recipient: PLACEHOLDER_FEE_RECIPIENT,
+        }
+    }
+}
+
+impl FeeSchedule {
+    /// Creates a new [`FeeSchedule`] with explicit parameters.
+    pub fn new(tx_fee_bps: u64, swap_fee_bps: u64, fee_recipient: Address) -> Self {
+        Self {
+            tx_fee_bps,
+            swap_fee_bps,
+            fee_recipient,
+        }
+    }
+
+    /// Returns the effective basis-point rate for the given `fee_type`.
+    fn bps_for(&self, fee_type: &FeeType) -> u64 {
+        match fee_type {
+            FeeType::Transaction => self.tx_fee_bps,
+            FeeType::Swap => self.swap_fee_bps,
+            FeeType::Custom(bps) => *bps,
+        }
+    }
+
+    /// Calculates a fee for `amount` and the given `fee_type`.
+    ///
+    /// # Errors
+    ///
+    /// - [`FeeError::InvalidBps`] — rate exceeds 10 000.
+    /// - [`FeeError::Token`] — arithmetic overflow.
+    /// - [`FeeError::FeeExceedsAmount`] — fee ≥ gross.
+    pub fn calculate(
+        &self,
+        amount: TokenAmount,
+        fee_type: FeeType,
+    ) -> Result<FeeCalculation, FeeError> {
+        let bps = self.bps_for(&fee_type);
+        if bps > 10_000 {
+            return Err(FeeError::InvalidBps(bps));
+        }
+
+        let fee_amount = amount
+            .checked_mul_bps(bps)
+            .ok_or_else(|| FeeError::Token("overflow in checked_mul_bps".to_string()))?;
+
+        let net_amount = amount
+            .sub(&fee_amount)
+            .map_err(|_| FeeError::FeeExceedsAmount { fee_bps: bps })?;
+
+        Ok(FeeCalculation {
+            gross_amount: amount,
+            fee_amount,
+            net_amount,
+            fee_recipient: self.fee_recipient,
+            fee_type,
+        })
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use alloy_primitives::Address;
+
+    fn usdc(amount: f64) -> TokenAmount {
+        TokenAmount::from_human(amount, 6)
+    }
+
+    fn eth(amount: f64) -> TokenAmount {
+        TokenAmount::from_human(amount, 18)
+    }
+
+    #[test]
+    fn default_fee_schedule_values() {
+        let s = FeeSchedule::default();
+        assert_eq!(s.tx_fee_bps, 77);
+        assert_eq!(s.swap_fee_bps, 30);
+        assert_eq!(s.fee_recipient, Address::ZERO);
+    }
+
+    #[test]
+    fn tx_fee_usdc_1000() {
+        let s = FeeSchedule::default();
+        let calc = s.calculate(usdc(1000.0), FeeType::Transaction).unwrap();
+        // 1000 USDC × 77/10000 = 7.7 USDC
+        assert!((calc.fee_amount.to_human() - 7.7).abs() < 0.000_001);
+        assert!((calc.net_amount.to_human() - 992.3).abs() < 0.000_001);
+        assert_eq!(calc.fee_type, FeeType::Transaction);
+    }
+
+    #[test]
+    fn tx_fee_usdc_1() {
+        let s = FeeSchedule::default();
+        let calc = s.calculate(usdc(1.0), FeeType::Transaction).unwrap();
+        // 1 USDC × 77/10000 = 0.0077 USDC
+        assert!((calc.fee_amount.to_human() - 0.0077).abs() < 0.000_001);
+    }
+
+    #[test]
+    fn swap_fee_usdc_1000() {
+        let s = FeeSchedule::default();
+        let calc = s.calculate(usdc(1000.0), FeeType::Swap).unwrap();
+        // 1000 USDC × 30/10000 = 3 USDC
+        assert!((calc.fee_amount.to_human() - 3.0).abs() < 0.000_001);
+        assert_eq!(calc.fee_type, FeeType::Swap);
+    }
+
+    #[test]
+    fn swap_fee_custom_50bps() {
+        let s = FeeSchedule::new(30, 50, Address::ZERO);
+        let calc = s.calculate(usdc(200.0), FeeType::Swap).unwrap();
+        // 200 USDC × 50/10000 = 1 USDC
+        assert!((calc.fee_amount.to_human() - 1.0).abs() < 0.000_001);
+    }
+
+    #[test]
+    fn tx_fee_eth_1() {
+        let s = FeeSchedule::default();
+        let calc = s.calculate(eth(1.0), FeeType::Transaction).unwrap();
+        // 1 ETH × 77/10000 = 0.0077 ETH
+        assert!((calc.fee_amount.to_human() - 0.0077).abs() < 0.000_001);
+    }
+
+    #[test]
+    fn swap_fee_eth_10() {
+        let s = FeeSchedule::default();
+        let calc = s.calculate(eth(10.0), FeeType::Swap).unwrap();
+        // 10 ETH × 30/10000 = 0.03 ETH
+        assert!((calc.fee_amount.to_human() - 0.03).abs() < 0.000_001);
+    }
+
+    #[test]
+    fn zero_amount_returns_zero_fee() {
+        let s = FeeSchedule::default();
+        let calc = s.calculate(usdc(0.0), FeeType::Transaction).unwrap();
+        assert!(calc.fee_amount.is_zero());
+        assert!(calc.net_amount.is_zero());
+    }
+
+    #[test]
+    fn custom_fee_type_100bps() {
+        let s = FeeSchedule::default();
+        let calc = s.calculate(usdc(100.0), FeeType::Custom(100)).unwrap();
+        // 100 USDC × 100/10000 = 1 USDC
+        assert!((calc.fee_amount.to_human() - 1.0).abs() < 0.000_001);
+    }
+
+    #[test]
+    fn fee_recipient_propagated() {
+        use alloy_primitives::address;
+        let recipient = address!("d8dA6BF26964aF9D7eEd9e03E53415D37aA96045");
+        let s = FeeSchedule::new(77, 30, recipient);
+        let calc = s.calculate(usdc(500.0), FeeType::Transaction).unwrap();
+        assert_eq!(calc.fee_recipient, recipient);
+    }
+
+    #[test]
+    fn gross_equals_fee_plus_net() {
+        let s = FeeSchedule::default();
+        let gross = usdc(123.456789);
+        let calc = s.calculate(gross.clone(), FeeType::Swap).unwrap();
+        let reconstructed = calc.fee_amount.add(&calc.net_amount).unwrap();
+        assert_eq!(reconstructed, calc.gross_amount);
+    }
+
+    #[test]
+    fn bps_over_10000_is_rejected() {
+        let s = FeeSchedule::new(10_001, 30, Address::ZERO);
+        let err = s.calculate(usdc(1.0), FeeType::Transaction).unwrap_err();
+        assert_eq!(err, FeeError::InvalidBps(10_001));
+    }
+}

package/native/crates/index/Cargo.toml

@@ -0,0 +1,16 @@
+[package]
+name = "clawpowers-index"
+version.workspace = true
+edition.workspace = true
+license.workspace = true
+
+[dependencies]
+serde = { workspace = true }
+serde_json = { workspace = true }
+thiserror = { workspace = true }
+tracing = { workspace = true }
+uuid = { workspace = true }
+clawpowers-compression = { path = "../compression" }
+
+[dev-dependencies]
+rand = { workspace = true }

package/native/crates/index/src/lib.rs

@@ -0,0 +1,277 @@
+//! Vector index adapter for TurboMemory.
+//!
+//! Exposes a [`VectorIndex`] trait and an [`InMemoryIndex`] implementation
+//! that stores compressed vectors via [`TurboCompressor`] and retrieves
+//! nearest neighbours using brute-force cosine similarity.
+
+use clawpowers_compression::{CompressedVector, CompressionConfig, TurboCompressor};
+use thiserror::Error;
+use uuid::Uuid;
+
+/// Errors produced by the index.
+#[derive(Debug, Error)]
+pub enum IndexError {
+    /// The query vector has a different dimensionality than the index.
+    #[error("dimension mismatch: expected {expected}, got {got}")]
+    DimensionMismatch {
+        /// Expected dimensionality.
+        expected: usize,
+        /// Provided dimensionality.
+        got: usize,
+    },
+    /// The requested number of results is zero.
+    #[error("top_k must be > 0")]
+    ZeroTopK,
+    /// Underlying compression error.
+    #[error("compression error: {0}")]
+    Compression(#[from] clawpowers_compression::CompressionError),
+}
+
+/// A shorthand result type for [`IndexError`].
+pub type Result<T> = std::result::Result<T, IndexError>;
+
+/// A single ranked search result.
+#[derive(Debug, Clone)]
+pub struct SearchResult {
+    /// Identifier of the matching vector.
+    pub id: Uuid,
+    /// Similarity score (cosine similarity, higher is more similar).
+    pub score: f32,
+}
+
+/// Trait for vector stores used by TurboMemory.
+pub trait VectorIndex {
+    /// Insert a vector under `id`.
+    fn insert(&mut self, id: Uuid, vector: Vec<f32>) -> Result<()>;
+    /// Return the `top_k` most similar vectors to `query`, ranked descending by score.
+    fn search(&self, query: &[f32], top_k: usize) -> Result<Vec<SearchResult>>;
+    /// Remove the vector with `id`. Returns `true` if it was present.
+    fn remove(&mut self, id: &Uuid) -> Result<bool>;
+    /// Number of vectors currently in the index.
+    fn len(&self) -> usize;
+    /// Return `true` if the index contains no vectors.
+    fn is_empty(&self) -> bool {
+        self.len() == 0
+    }
+}
+
+struct Entry {
+    id: Uuid,
+    /// Stored for potential future fast-path approximate distance calculations.
+    #[allow(dead_code)]
+    compressed: CompressedVector,
+    /// Original vector used for exact cosine similarity.
+    original: Vec<f32>,
+}
+
+/// In-memory brute-force vector index backed by TurboQuant compression.
+///
+/// Suitable for up to ~100 K vectors.
+pub struct InMemoryIndex {
+    compressor: TurboCompressor,
+    entries: Vec<Entry>,
+}
+
+impl InMemoryIndex {
+    /// Create a new index with the given compression configuration.
+    pub fn new(config: CompressionConfig) -> Self {
+        let compressor = TurboCompressor::new(config);
+        Self {
+            compressor,
+            entries: Vec::new(),
+        }
+    }
+
+    /// Create an index with sensible defaults for `dimensions`.
+    pub fn with_dimensions(dimensions: usize) -> Self {
+        Self::new(CompressionConfig {
+            dimensions,
+            quantization_bits: 8,
+            rotation_seed: 0xDEAD_BEEF_CAFE_1234,
+        })
+    }
+}
+
+impl VectorIndex for InMemoryIndex {
+    fn insert(&mut self, id: Uuid, vector: Vec<f32>) -> Result<()> {
+        let compressed = self.compressor.compress(&vector)?;
+        self.entries.push(Entry {
+            id,
+            compressed,
+            original: vector,
+        });
+        Ok(())
+    }
+
+    fn search(&self, query: &[f32], top_k: usize) -> Result<Vec<SearchResult>> {
+        if top_k == 0 {
+            return Err(IndexError::ZeroTopK);
+        }
+        let dim = self.compressor.config.dimensions;
+        if query.len() != dim {
+            return Err(IndexError::DimensionMismatch {
+                expected: dim,
+                got: query.len(),
+            });
+        }
+        let mut scored: Vec<(f32, &Entry)> = self
+            .entries
+            .iter()
+            .map(|e| (cosine_similarity(query, &e.original), e))
+            .collect();
+        scored.sort_by(|a, b| b.0.partial_cmp(&a.0).unwrap_or(std::cmp::Ordering::Equal));
+        Ok(scored
+            .into_iter()
+            .take(top_k)
+            .map(|(score, e)| SearchResult { id: e.id, score })
+            .collect())
+    }
+
+    fn remove(&mut self, id: &Uuid) -> Result<bool> {
+        let before = self.entries.len();
+        self.entries.retain(|e| &e.id != id);
+        Ok(self.entries.len() < before)
+    }
+
+    fn len(&self) -> usize {
+        self.entries.len()
+    }
+}
+
+fn cosine_similarity(a: &[f32], b: &[f32]) -> f32 {
+    let dot: f32 = a.iter().zip(b.iter()).map(|(x, y)| x * y).sum();
+    let na: f32 = a.iter().map(|x| x * x).sum::<f32>().sqrt();
+    let nb: f32 = b.iter().map(|x| x * x).sum::<f32>().sqrt();
+    if na < f32::EPSILON || nb < f32::EPSILON {
+        0.0
+    } else {
+        dot / (na * nb)
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    const DIM: usize = 32;
+
+    fn make_index() -> InMemoryIndex {
+        InMemoryIndex::with_dimensions(DIM)
+    }
+
+    fn unit_vec(hot: usize) -> Vec<f32> {
+        let mut v = vec![0.0_f32; DIM];
+        v[hot % DIM] = 1.0;
+        v
+    }
+
+    fn rand_vec(seed: u64) -> Vec<f32> {
+        let mut x = seed;
+        (0..DIM)
+            .map(|_| {
+                x = x
+                    .wrapping_mul(6_364_136_223_846_793_005)
+                    .wrapping_add(1_442_695_040_888_963_407);
+                ((x >> 33) as f32 / u32::MAX as f32) * 2.0 - 1.0
+            })
+            .collect()
+    }
+
+    #[test]
+    fn test_insert_increases_len() {
+        let mut idx = make_index();
+        assert_eq!(idx.len(), 0);
+        idx.insert(Uuid::new_v4(), rand_vec(1)).expect("insert");
+        assert_eq!(idx.len(), 1);
+    }
+
+    #[test]
+    fn test_empty_index_search_returns_empty() {
+        let idx = make_index();
+        assert!(idx.search(&rand_vec(2), 5).expect("search").is_empty());
+    }
+
+    #[test]
+    fn test_is_empty() {
+        let mut idx = make_index();
+        assert!(idx.is_empty());
+        idx.insert(Uuid::new_v4(), rand_vec(3)).expect("insert");
+        assert!(!idx.is_empty());
+    }
+
+    #[test]
+    fn test_search_returns_nearest_neighbour() {
+        let mut idx = make_index();
+        let query = unit_vec(0);
+        let id_match = Uuid::new_v4();
+        let id_other = Uuid::new_v4();
+        idx.insert(id_match, unit_vec(0)).expect("insert match");
+        idx.insert(id_other, unit_vec(1)).expect("insert other");
+        let results = idx.search(&query, 1).expect("search");
+        assert_eq!(results.len(), 1);
+        assert_eq!(results[0].id, id_match);
+    }
+
+    #[test]
+    fn test_search_results_ordered_by_score_descending() {
+        let mut idx = make_index();
+        let query = rand_vec(42);
+        for i in 0..5 {
+            idx.insert(Uuid::new_v4(), rand_vec(i + 100))
+                .expect("insert");
+        }
+        let results = idx.search(&query, 5).expect("search");
+        for w in results.windows(2) {
+            assert!(w[0].score >= w[1].score, "{} < {}", w[0].score, w[1].score);
+        }
+    }
+
+    #[test]
+    fn test_search_top_k_limits_results() {
+        let mut idx = make_index();
+        for i in 0..10 {
+            idx.insert(Uuid::new_v4(), rand_vec(i)).expect("insert");
+        }
+        assert_eq!(idx.search(&rand_vec(99), 3).expect("search").len(), 3);
+    }
+
+    #[test]
+    fn test_remove_existing_returns_true() {
+        let mut idx = make_index();
+        let id = Uuid::new_v4();
+        idx.insert(id, rand_vec(5)).expect("insert");
+        assert!(idx.remove(&id).expect("remove"));
+        assert_eq!(idx.len(), 0);
+    }
+
+    #[test]
+    fn test_remove_nonexistent_returns_false() {
+        let mut idx = make_index();
+        assert!(!idx.remove(&Uuid::new_v4()).expect("remove"));
+    }
+
+    #[test]
+    fn test_removed_vector_not_in_results() {
+        let mut idx = make_index();
+        let query = unit_vec(0);
+        let id = Uuid::new_v4();
+        idx.insert(id, unit_vec(0)).expect("insert");
+        idx.remove(&id).expect("remove");
+        assert!(
+            !idx.search(&query, 10)
+                .expect("search")
+                .iter()
+                .any(|r| r.id == id)
+        );
+    }
+
+    #[test]
+    fn test_zero_top_k_errors() {
+        let mut idx = make_index();
+        let _ = idx.insert(Uuid::new_v4(), rand_vec(6));
+        assert!(matches!(
+            idx.search(&rand_vec(7), 0).expect_err("e"),
+            IndexError::ZeroTopK
+        ));
+    }
+}

package/native/crates/policy/Cargo.toml

@@ -0,0 +1,17 @@
+[package]
+name = "clawpowers-policy"
+version.workspace = true
+edition.workspace = true
+license.workspace = true
+
+[dependencies]
+serde = { workspace = true }
+serde_json = { workspace = true }
+thiserror = { workspace = true }
+tracing = { workspace = true }
+chrono = { workspace = true }
+alloy-primitives = { workspace = true }
+clawpowers-tokens = { path = "../tokens" }
+
+[dev-dependencies]
+tokio = { workspace = true }