feat(vault): authorized caller for metering

Author: DavisVT

contracts/vault/ACCESS_CONTROL.md

@@ -75,3 +75,29 @@ The `transfer_ownership` function allows the current owner to hand over full con
 ### Admin Transition
 
 The `set_admin` function allows the current admin (typically the owner initially) to delegate operational control (like settlement and distribution) to a dedicated service account.
+
+---
+
+## Migration: Owner-Only Metering → Backend-Signed Metering
+
+### Background
+
+In the initial deployment model, only the vault owner could invoke `deduct` and `batch_deduct`. This required the owner's key to be present in the metering path, which is impractical for automated, high-frequency backend services.
+
+### Current Model
+
+The `set_authorized_caller` function allows the owner to designate a single backend address (e.g., a matching engine or metering service) that may call deduct flows alongside the owner. Both the owner and the authorized caller are permitted; all other addresses are rejected.
+
+### Migration Steps
+
+1. Deploy or upgrade the vault contract containing `set_authorized_caller`.
+2. The owner calls `set_authorized_caller(owner, backend_address)` to register the backend signing key.
+3. The backend service signs and submits `deduct` / `batch_deduct` transactions using its own key.
+4. The owner's key is no longer required in the hot metering path.
+
+### Operational Notes
+
+- Only the owner may call `set_authorized_caller`; the backend cannot self-register.
+- Rotating the backend key requires calling `set_authorized_caller` again with the new address. The previous address is replaced atomically.
+- Every change emits a `set_auth_caller` event (topics: `("set_auth_caller", owner)`, data: `new_caller`) for audit purposes.
+- Passing the vault contract's own address or the currently stored address as `new_caller` is rejected.

contracts/vault/src/lib.rs

@@ -244,19 +244,45 @@ impl CalloraVault {
         }
     }
 
-    /// Sets the authorized caller permitted to trigger deductions.
-    /// Can only be called by the Owner.
-    pub fn set_authorized_caller(env: Env, caller: Address) {
+    /// Sets the address permitted to invoke deduct flows alongside the owner.
+    ///
+    /// Only the vault owner may call this function. The new authorized caller must
+    /// differ from the address already stored; passing the same address is rejected
+    /// as a meaningless no-op. Passing the vault contract's own address is also
+    /// rejected.
+    ///
+    /// # Arguments
+    /// * `env`        – The environment running the contract.
+    /// * `owner`      – Must be the current vault owner; must authorize this call.
+    /// * `new_caller` – Address to grant deduction rights.
+    ///
+    /// # Panics
+    /// * `"unauthorized: owner only"` – if `owner` is not the vault owner.
+    /// * `"new_caller must differ from current authorized caller"` – if `new_caller`
+    ///   is already the stored authorized caller (meaningless update).
+    /// * `"new_caller must not be the vault contract itself"` – if `new_caller` is
+    ///   the vault's own contract address.
+    ///
+    /// # Events
+    /// Emits topic `("set_auth_caller", owner)` with data `new_caller` on success.
+    pub fn set_authorized_caller(env: Env, owner: Address, new_caller: Address) {
+        owner.require_auth();
+        Self::require_owner(env.clone(), owner.clone());
+        assert!(
+            new_caller != env.current_contract_address(),
+            "new_caller must not be the vault contract itself"
+        );
         let mut meta = Self::get_meta(env.clone());
-        meta.owner.require_auth();
-
-        meta.authorized_caller = Some(caller.clone());
+        if let Some(ref current) = meta.authorized_caller {
+            assert!(
+                new_caller != *current,
+                "new_caller must differ from current authorized caller"
+            );
+        }
+        meta.authorized_caller = Some(new_caller.clone());
         env.storage().instance().set(&StorageKey::Meta, &meta);
-
-        env.events().publish(
-            (Symbol::new(&env, "set_auth_caller"), meta.owner.clone()),
-            caller,
-        );
+        env.events()
+            .publish((Symbol::new(&env, "set_auth_caller"), owner), new_caller);
     }
 
     /// Deposits USDC into the vault.

contracts/vault/src/test.rs

@@ -1409,3 +1409,234 @@ fn get_settlement_before_set_panics() {
     client.init(&owner, &usdc, &None, &None, &None, &None, &None);
     client.get_settlement();
 }
+
+// ---------------------------------------------------------------------------
+// set_authorized_caller + deduct authorization matrix tests
+// ---------------------------------------------------------------------------
+
+/// Helper: init a vault with `balance` and no pre-set authorized caller.
+/// Caller must have already called `env.mock_all_auths()`.
+fn init_vault_no_auth_caller<'a>(
+    env: &'a Env,
+    owner: &Address,
+    balance: i128,
+) -> (Address, CalloraVaultClient<'a>) {
+    let (vault_address, client) = create_vault(env);
+    let (usdc, _, usdc_admin) = create_usdc(env, owner);
+    fund_vault(&usdc_admin, &vault_address, balance);
+    client.init(owner, &usdc, &Some(balance), &None, &None, &None, &None);
+    (vault_address, client)
+}
+
+#[test]
+fn set_authorized_caller_stores_address_and_emits_event() {
+    let env = Env::default();
+    let owner = Address::generate(&env);
+    let backend = Address::generate(&env);
+    env.mock_all_auths();
+    let (vault_address, client) = init_vault_no_auth_caller(&env, &owner, 100);
+
+    client.set_authorized_caller(&owner, &backend);
+
+    // Event emitted: topic ("set_auth_caller", owner), data = backend
+    let events = env.events().all();
+    let ev = events
+        .iter()
+        .find(|e| {
+            !e.1.is_empty() && {
+                let t: Symbol = e.1.get(0).unwrap().into_val(&env);
+                t == Symbol::new(&env, "set_auth_caller")
+            }
+        })
+        .expect("expected set_auth_caller event");
+
+    assert_eq!(ev.0, vault_address);
+    let topic_owner: Address = ev.1.get(1).unwrap().into_val(&env);
+    assert_eq!(topic_owner, owner);
+    let data: Address = ev.2.into_val(&env);
+    assert_eq!(data, backend);
+
+    // Stored correctly (checked after event assertion to avoid resetting event log)
+    let meta = client.get_meta();
+    assert_eq!(meta.authorized_caller, Some(backend));
+}
+
+#[test]
+fn set_authorized_caller_can_be_updated_to_different_address() {
+    let env = Env::default();
+    let owner = Address::generate(&env);
+    let backend_v1 = Address::generate(&env);
+    let backend_v2 = Address::generate(&env);
+    env.mock_all_auths();
+    let (_, client) = init_vault_no_auth_caller(&env, &owner, 100);
+    client.set_authorized_caller(&owner, &backend_v1);
+    client.set_authorized_caller(&owner, &backend_v2);
+
+    let meta = client.get_meta();
+    assert_eq!(meta.authorized_caller, Some(backend_v2));
+}
+
+#[test]
+#[should_panic(expected = "unauthorized: owner only")]
+fn set_authorized_caller_non_owner_rejected() {
+    let env = Env::default();
+    let owner = Address::generate(&env);
+    let attacker = Address::generate(&env);
+    let backend = Address::generate(&env);
+    env.mock_all_auths();
+    let (_, client) = init_vault_no_auth_caller(&env, &owner, 100);
+
+    client.set_authorized_caller(&attacker, &backend);
+}
+
+#[test]
+#[should_panic(expected = "new_caller must differ from current authorized caller")]
+fn set_authorized_caller_same_address_rejected() {
+    let env = Env::default();
+    let owner = Address::generate(&env);
+    let backend = Address::generate(&env);
+    env.mock_all_auths();
+    let (_, client) = init_vault_no_auth_caller(&env, &owner, 100);
+
+    client.set_authorized_caller(&owner, &backend);
+    // Setting the same address again must be rejected
+    client.set_authorized_caller(&owner, &backend);
+}
+
+#[test]
+#[should_panic(expected = "new_caller must not be the vault contract itself")]
+fn set_authorized_caller_vault_address_rejected() {
+    let env = Env::default();
+    let owner = Address::generate(&env);
+    env.mock_all_auths();
+    let (vault_address, client) = init_vault_no_auth_caller(&env, &owner, 100);
+
+    client.set_authorized_caller(&owner, &vault_address);
+}
+
+// --- Deduct authorization matrix ---
+
+#[test]
+fn deduct_matrix_owner_is_allowed() {
+    let env = Env::default();
+    let owner = Address::generate(&env);
+    env.mock_all_auths();
+    let (_, client) = init_vault_no_auth_caller(&env, &owner, 500);
+
+    // Owner can deduct even without an authorized_caller set
+    let remaining = client.deduct(&owner, &100, &None);
+    assert_eq!(remaining, 400);
+}
+
+#[test]
+fn deduct_matrix_authorized_caller_is_allowed() {
+    let env = Env::default();
+    let owner = Address::generate(&env);
+    let backend = Address::generate(&env);
+    env.mock_all_auths();
+    let (_, client) = init_vault_no_auth_caller(&env, &owner, 500);
+
+    client.set_authorized_caller(&owner, &backend);
+
+    let remaining = client.deduct(&backend, &150, &None);
+    assert_eq!(remaining, 350);
+}
+
+#[test]
+fn deduct_matrix_other_address_is_rejected() {
+    let env = Env::default();
+    let owner = Address::generate(&env);
+    let backend = Address::generate(&env);
+    let stranger = Address::generate(&env);
+    env.mock_all_auths();
+    let (_, client) = init_vault_no_auth_caller(&env, &owner, 500);
+
+    client.set_authorized_caller(&owner, &backend);
+
+    let result = client.try_deduct(&stranger, &50, &None);
+    assert!(result.is_err(), "stranger must be rejected from deduct");
+}
+
+#[test]
+fn deduct_matrix_no_authorized_caller_set_non_owner_rejected() {
+    let env = Env::default();
+    let owner = Address::generate(&env);
+    let stranger = Address::generate(&env);
+    env.mock_all_auths();
+    let (_, client) = init_vault_no_auth_caller(&env, &owner, 500);
+
+    // No authorized_caller configured — only owner may deduct
+    let result = client.try_deduct(&stranger, &50, &None);
+    assert!(
+        result.is_err(),
+        "non-owner must be rejected when no authorized_caller is set"
+    );
+}
+
+#[test]
+fn batch_deduct_matrix_owner_is_allowed() {
+    let env = Env::default();
+    let owner = Address::generate(&env);
+    env.mock_all_auths();
+    let (_, client) = init_vault_no_auth_caller(&env, &owner, 500);
+
+    let items = soroban_sdk::vec![
+        &env,
+        DeductItem {
+            amount: 100,
+            request_id: None
+        },
+        DeductItem {
+            amount: 50,
+            request_id: None
+        },
+    ];
+    let remaining = client.batch_deduct(&owner, &items);
+    assert_eq!(remaining, 350);
+}
+
+#[test]
+fn batch_deduct_matrix_authorized_caller_is_allowed() {
+    let env = Env::default();
+    let owner = Address::generate(&env);
+    let backend = Address::generate(&env);
+    env.mock_all_auths();
+    let (_, client) = init_vault_no_auth_caller(&env, &owner, 500);
+
+    client.set_authorized_caller(&owner, &backend);
+
+    let items = soroban_sdk::vec![
+        &env,
+        DeductItem {
+            amount: 200,
+            request_id: None
+        },
+    ];
+    let remaining = client.batch_deduct(&backend, &items);
+    assert_eq!(remaining, 300);
+}
+
+#[test]
+fn batch_deduct_matrix_other_address_is_rejected() {
+    let env = Env::default();
+    let owner = Address::generate(&env);
+    let backend = Address::generate(&env);
+    let stranger = Address::generate(&env);
+    env.mock_all_auths();
+    let (_, client) = init_vault_no_auth_caller(&env, &owner, 500);
+
+    client.set_authorized_caller(&owner, &backend);
+
+    let items = soroban_sdk::vec![
+        &env,
+        DeductItem {
+            amount: 50,
+            request_id: None
+        },
+    ];
+    let result = client.try_batch_deduct(&stranger, &items);
+    assert!(
+        result.is_err(),
+        "stranger must be rejected from batch_deduct"
+    );
+}