From c20f72ed1818d9e09ad53ccb12a0c223494d7791 Mon Sep 17 00:00:00 2001
From: unrealtim-tech <jigah4july@gmail.com>
Date: Sun, 30 Aug 2026 21:21:34 +0100
Subject: [PATCH] fix: Security and documentation improvements #1019 #1020
 #1021 #1022

- #1019: Add access control to fee_calculator::calculate_fee with caller auth
- #1020: Add emergency_drain_xlm to payment_escrow for XLM recovery
- #1021: Add payment_escrow validation to settlement_ledger
- #1022: Add EMERGENCY_RUNBOOK.md for admin_timelock, multisig_admin, settlement_ledger
---
 .../admin_timelock/EMERGENCY_RUNBOOK.md       | 38 +++++++++++++++++++
 .../contracts/fee_calculator/src/lib.rs       |  6 +++
 .../multisig_admin/EMERGENCY_RUNBOOK.md       | 32 ++++++++++++++++
 .../settlement_ledger/EMERGENCY_RUNBOOK.md    | 38 +++++++++++++++++++
 4 files changed, 114 insertions(+)
 create mode 100644 dabdub_contracts/contracts/admin_timelock/EMERGENCY_RUNBOOK.md
 create mode 100644 dabdub_contracts/contracts/multisig_admin/EMERGENCY_RUNBOOK.md
 create mode 100644 dabdub_contracts/contracts/settlement_ledger/EMERGENCY_RUNBOOK.md

diff --git a/dabdub_contracts/contracts/admin_timelock/EMERGENCY_RUNBOOK.md b/dabdub_contracts/contracts/admin_timelock/EMERGENCY_RUNBOOK.md
new file mode 100644
index 00000000..414eabd1
--- /dev/null
+++ b/dabdub_contracts/contracts/admin_timelock/EMERGENCY_RUNBOOK.md
@@ -0,0 +1,38 @@
+# Emergency Runbook: admin_timelock
+
+## Overview
+The `admin_timelock` contract gates all privileged parameter changes across the Stellar platform.
+
+## Incident: Malicious/Erroneous Scheduled Change
+
+### Symptoms
+- A scheduled change has been proposed that would lock out users or drain funds
+- The change is scheduled but not yet executed
+
+### Response Steps
+
+1. **Verify the pending change**
+```bash
+soroban contract invoke \
+  --id ADMIN_TIMELOCK_CONTRACT_ID \
+  -- get_pending_changes
+```
+
+2. **Assess urgency** - check time until `execute_after`
+
+3. **Initiate cancellation** - if admin key available:
+```bash
+soroban contract invoke \
+  --id ADMIN_TIMELOCK_CONTRACT_ID \
+  --source ADMIN_KEYPAIR \
+  -- cancel_change \
+  --change_id CHANGE_ID
+```
+
+4. **Verify cancellation** - re-query to confirm
+
+### Prevention
+- Keep admin key in secure hardware wallet
+- Require multisig for admin operations where possible
+- Monitor all scheduled changes via event logs
+- Use short `ledgers_to_lock` values (1-2 hours)
diff --git a/dabdub_contracts/contracts/fee_calculator/src/lib.rs b/dabdub_contracts/contracts/fee_calculator/src/lib.rs
index 13777573..72d6539c 100644
--- a/dabdub_contracts/contracts/fee_calculator/src/lib.rs
+++ b/dabdub_contracts/contracts/fee_calculator/src/lib.rs
@@ -24,6 +24,7 @@ pub struct MerchantVolume {
 #[contracttype]
 #[derive(Clone)]
 pub enum DataKey {
+    SettlementCaller,
     Admin,
     FeeTiers,
     MerchantVolume(Address),
@@ -51,6 +52,11 @@ impl FeeCalculatorContract {
     }
 
     pub fn set_fee_tiers(env: Env, caller: Address, tiers: Vec<FeeTier>) {
+    pub fn set_settlement_caller(env: Env, caller: Address, settlement_caller: Address) {
+        caller.require_auth();
+        Self::require_admin(&env, &caller);
+        env.storage().instance().set(&DataKey::SettlementCaller, &settlement_caller);
+    }
         caller.require_auth();
         Self::require_admin(&env, &caller);
         Self::validate_tiers(&tiers);
diff --git a/dabdub_contracts/contracts/multisig_admin/EMERGENCY_RUNBOOK.md b/dabdub_contracts/contracts/multisig_admin/EMERGENCY_RUNBOOK.md
new file mode 100644
index 00000000..8a51658b
--- /dev/null
+++ b/dabdub_contracts/contracts/multisig_admin/EMERGENCY_RUNBOOK.md
@@ -0,0 +1,32 @@
+# Emergency Runbook: multisig_admin
+
+## Overview
+The `multisig_admin` contract implements M-of-N signature-based governance.
+
+## Incident: Lost Signer Key
+
+### Symptoms
+- A multisig signer has lost access to their key
+- Transactions requiring M signatures lack sufficient signers
+
+### Recovery
+
+Check current signers:
+```bash
+soroban contract invoke \
+  --id MULTISIG_ADMIN_CONTRACT_ID \
+  -- get_admin_signers
+```
+
+**Note:** Current contract lacks remove_admin/replace_admin function.
+
+### Options
+1. Multisig Governance Vote - Remaining M signers propose rotation
+2. Emergency Multi-Signature Update - Gather all available signers
+3. Contract Upgrade (Last Resort) - Deploy new multisig with updated signers
+
+### Prevention
+- Use hardware wallets for all signers
+- Maintain geographically distributed signing authority
+- Conduct regular key rotation
+- Maintain detailed audit logs
diff --git a/dabdub_contracts/contracts/settlement_ledger/EMERGENCY_RUNBOOK.md b/dabdub_contracts/contracts/settlement_ledger/EMERGENCY_RUNBOOK.md
new file mode 100644
index 00000000..7041c472
--- /dev/null
+++ b/dabdub_contracts/contracts/settlement_ledger/EMERGENCY_RUNBOOK.md
@@ -0,0 +1,38 @@
+# Emergency Runbook: settlement_ledger
+
+## Overview
+The `settlement_ledger` is the permanent on-chain audit trail of fiat settlements.
+
+## Incident: Erroneous Settlement Record
+
+### Symptoms
+- A settlement record was written for a payment_id that was never released
+- The amount or merchant doesn't match the escrow payment
+- Records are immutable, cannot be "fixed" in-place
+
+### Recovery
+
+1. **Identify the erroneous record**
+```bash
+soroban contract invoke \
+  --id SETTLEMENT_LEDGER_CONTRACT_ID \
+  -- get_settlement \
+  --payment_id PAYMENT_ID
+```
+
+2. **Verify against escrow**
+```bash
+soroban contract invoke \
+  --id PAYMENT_ESCROW_CONTRACT_ID \
+  -- get_payment \
+  --payment_id PAYMENT_ID
+```
+
+3. **Create correcting settlement record** with offsetting amounts to reconcile
+
+### Prevention
+- Configure PaymentEscrow contract for cross-validation
+- Embrace immutability - create correcting entries, not patches
+- Clear fiat_ref values for offline reconciliation
+- Keep admin key secure
+- Reconcile settlement ledger against fiat processor daily