fix: Security and documentation improvements

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)

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);

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

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