Closes #660

contracts/admin/src/lib.rs

@@ -608,6 +608,11 @@ pub struct UpgradeProposal {
     /// the pre-quorum clock only: it decides `Pending` to `Expired` and nothing
     /// else. Any post-quorum execution deadline is timelock state owned by #660.
     pub expires_at: u64,
+    /// Unix timestamp (seconds) when the post-quorum execution timelock expires.
+    /// `None` while the proposal has not yet reached quorum; set to
+    /// `env.ledger().timestamp() + TIMELOCK_DELAY_SECS` the moment quorum is
+    /// first reached and never reset by later votes.
+    pub timelock_expires_at: Option<u64>,
 }
 
 /// Strkey of the well-known Stellar "null" account: an ed25519 public key
@@ -1293,6 +1298,18 @@ fn _start_timelock_if_quorate(env: &Env, proposal_id: u64) {
     extend_instance_ttl(env);
 }
 
+/// Records the timelock expiration for an [`UpgradeProposal`] when quorum is first reached.
+///
+/// Sets `timelock_expires_at` to `Some(env.ledger().timestamp() + TIMELOCK_DELAY_SECS)`
+/// the moment quorum is reached (`proposal.status == ProposalStatus::Approved`).
+/// Idempotent: if `timelock_expires_at` is already `Some`, it is never reset by later votes.
+fn _start_upgrade_timelock_if_quorate(env: &Env, proposal: &mut UpgradeProposal) {
+    if proposal.status == ProposalStatus::Approved && proposal.timelock_expires_at.is_none() {
+        proposal.timelock_expires_at =
+            Some(env.ledger().timestamp().saturating_add(TIMELOCK_DELAY_SECS));
+    }
+}
+
 /// Returns the unix timestamp at which `proposal_id`'s timelock expires, if any.
 ///
 /// @notice Returns `Some(unlock_time)` once the proposal has reached quorum, `None` before that.
@@ -3967,24 +3984,26 @@ mod tests {
         ["Approved", "Cancelled", "Executed", "Expired", "Pending"];
 
     /// Encoded field names of [`UpgradeProposal`], frozen the same way.
-    const UPGRADE_PROPOSAL_FIELD_NAMES: [&str; 6] = [
+    const UPGRADE_PROPOSAL_FIELD_NAMES: [&str; 7] = [
         "expires_at",
         "proposer",
         "quorum",
         "status",
         "targets",
+        "timelock_expires_at",
         "votes",
     ];
 
     /// Encoded value kind per [`UpgradeProposal`] field. A width change
     /// (`quorum` from `u64` to `u32`) re-encodes the value and orphans stored
     /// proposals exactly as a rename does, and no name check would catch it.
-    const UPGRADE_PROPOSAL_FIELD_KINDS: [(&str, &str); 6] = [
+    const UPGRADE_PROPOSAL_FIELD_KINDS: [(&str, &str); 7] = [
         ("expires_at", "u64"),
         ("proposer", "address"),
         ("quorum", "u64"),
         ("status", "vec"),
         ("targets", "vec"),
+        ("timelock_expires_at", "option"),
         ("votes", "map"),
     ];
 
@@ -4021,6 +4040,7 @@ mod tests {
             quorum: 2,
             status: ProposalStatus::Pending,
             expires_at: 1_724_000_000,
+            timelock_expires_at: None,
         }
     }
 
@@ -4057,6 +4077,7 @@ mod tests {
             ScVal::Address(_) => "address",
             ScVal::Vec(_) => "vec",
             ScVal::Map(_) => "map",
+            ScVal::Void => "option",
             _ => "unexpected",
         }
     }
@@ -4094,6 +4115,7 @@ mod tests {
             quorum: _,
             status: _,
             expires_at: _,
+            timelock_expires_at: _,
         } = &proposal;
 
         let encoded = encoded_fields(&env, proposal);
@@ -4250,6 +4272,7 @@ mod tests {
             quorum: 2,
             status: ProposalStatus::Pending,
             expires_at: env.ledger().timestamp() + 1_000,
+            timelock_expires_at: None,
         };
         seed_upgrade_proposal(&env, &contract_id, 1, &proposal);
 
@@ -4282,6 +4305,7 @@ mod tests {
             quorum: 2,
             status: ProposalStatus::Pending,
             expires_at: env.ledger().timestamp() + 1_000,
+            timelock_expires_at: None,
         };
         seed_upgrade_proposal(&env, &contract_id, 1, &proposal);
 
@@ -4313,6 +4337,7 @@ mod tests {
             quorum: 1,
             status: ProposalStatus::Pending,
             expires_at: env.ledger().timestamp() + 1_000,
+            timelock_expires_at: None,
         };
         seed_upgrade_proposal(&env, &contract_id, 1, &proposal);
 
@@ -4341,6 +4366,7 @@ mod tests {
             quorum: 2,
             status: ProposalStatus::Pending,
             expires_at: env.ledger().timestamp() + 1_000,
+            timelock_expires_at: None,
         };
         seed_upgrade_proposal(&env, &contract_id, 1, &proposal);
 
@@ -4385,6 +4411,7 @@ mod tests {
             quorum: 1,
             status: ProposalStatus::Approved,
             expires_at: env.ledger().timestamp() + 1_000,
+            timelock_expires_at: None,
         };
         seed_upgrade_proposal(&env, &contract_id, 1, &proposal);
 
@@ -4412,6 +4439,7 @@ mod tests {
             quorum: 1,
             status: ProposalStatus::Pending,
             expires_at: env.ledger().timestamp(),
+            timelock_expires_at: None,
         };
         seed_upgrade_proposal(&env, &contract_id, 1, &proposal);
 
@@ -4473,6 +4501,57 @@ mod tests {
         assert!(result.is_err());
     }
 
+    // ── UpgradeProposal timelock state structure (#660) ─────────────────────────
+
+    #[test]
+    fn test_upgrade_proposal_timelock_expires_at_none_on_creation() {
+        let env = Env::default();
+        let proposal = upgrade_proposal_fixture(&env);
+        assert_eq!(proposal.timelock_expires_at, None);
+    }
+
+    #[test]
+    fn test_upgrade_proposal_timelock_expires_at_set_when_quorum_first_reached() {
+        let env = Env::default();
+        let mut proposal = upgrade_proposal_fixture(&env);
+        assert_eq!(proposal.status, ProposalStatus::Pending);
+        assert_eq!(proposal.timelock_expires_at, None);
+
+        proposal.status = ProposalStatus::Approved;
+        _start_upgrade_timelock_if_quorate(&env, &mut proposal);
+
+        let expected_unlock = env.ledger().timestamp().saturating_add(TIMELOCK_DELAY_SECS);
+        assert_eq!(proposal.timelock_expires_at, Some(expected_unlock));
+    }
+
+    #[test]
+    fn test_upgrade_proposal_timelock_expires_at_not_reset_by_later_votes() {
+        let env = Env::default();
+        let mut proposal = upgrade_proposal_fixture(&env);
+        proposal.status = ProposalStatus::Approved;
+        _start_upgrade_timelock_if_quorate(&env, &mut proposal);
+
+        let initial_timelock = proposal.timelock_expires_at;
+        assert!(initial_timelock.is_some());
+
+        // Advance ledger timestamp by 100 seconds
+        env.ledger().set_timestamp(env.ledger().timestamp() + 100);
+
+        // Subsequent votes/calls on already-quorate proposal must not reset timelock_expires_at
+        _start_upgrade_timelock_if_quorate(&env, &mut proposal);
+        assert_eq!(proposal.timelock_expires_at, initial_timelock);
+    }
+
+    #[test]
+    fn test_upgrade_proposal_timelock_expires_at_remains_none_below_quorum() {
+        let env = Env::default();
+        let mut proposal = upgrade_proposal_fixture(&env);
+        assert_eq!(proposal.status, ProposalStatus::Pending);
+
+        _start_upgrade_timelock_if_quorate(&env, &mut proposal);
+        assert_eq!(proposal.timelock_expires_at, None);
+    }
+
     // ── cancel_proposal (#662) ──────────────────────────────────────────────
 
     /// Writes `proposal` directly into the contract's `UpgradeProposal(id)`
@@ -4516,6 +4595,7 @@ mod tests {
             quorum: 2,
             status,
             expires_at: 1_724_000_000,
+            timelock_expires_at: None,
         }
     }
 

contracts/admin/src/tests/proptest.rs

@@ -51,6 +51,7 @@ fn seed_upgrade_proposal(env: &Env, contract_id: &Address, id: u64, proposer: &A
         quorum: 2,
         status: ProposalStatus::Pending,
         expires_at: u64::MAX,
+        timelock_expires_at: None,
     };
     env.as_contract(contract_id, || {
         env.storage()

contracts/admin/test_snapshots/tests/proptest/fuzz_admin_implicitly_has_all_roles.38.json

@@ -4,6 +4,7 @@
     "nonce": 0
   },
   "auth": [
+    [],
     [],
     [],
     [
@@ -259,7 +260,7 @@
                 {
                   "vec": [
                     {
-                      "symbol": "Admin"
+                      "symbol": "Minter"
                     }
                   ]
                 },

contracts/admin/test_snapshots/tests/proptest/fuzz_admin_implicitly_has_all_roles.54.json

@@ -260,7 +260,7 @@
                 {
                   "vec": [
                     {
-                      "symbol": "SuperAdmin"
+                      "symbol": "Minter"
                     }
                   ]
                 },

contracts/admin/test_snapshots/tests/proptest/fuzz_admin_implicitly_has_all_roles.68.json

@@ -4,7 +4,6 @@
     "nonce": 0
   },
   "auth": [
-    [],
     [],
     [],
     [
@@ -260,7 +259,7 @@
                 {
                   "vec": [
                     {
-                      "symbol": "Minter"
+                      "symbol": "Admin"
                     }
                   ]
                 },

contracts/admin/test_snapshots/tests/proptest/fuzz_admin_implicitly_has_all_roles.80.json

@@ -4,7 +4,6 @@
     "nonce": 0
   },
   "auth": [
-    [],
     [],
     [],
     [
@@ -260,7 +259,7 @@
                 {
                   "vec": [
                     {
-                      "symbol": "Minter"
+                      "symbol": "Admin"
                     }
                   ]
                 },

contracts/admin/test_snapshots/tests/proptest/fuzz_grant_role_emits_event.14.json

@@ -21,7 +21,7 @@
                 {
                   "vec": [
                     {
-                      "symbol": "SuperAdmin"
+                      "symbol": "Pauser"
                     }
                   ]
                 },
@@ -127,7 +127,7 @@
                 },
                 "durability": "persistent",
                 "val": {
-                  "u32": 4
+                  "u32": 8
                 }
               }
             },
@@ -292,7 +292,7 @@
                 {
                   "vec": [
                     {
-                      "symbol": "SuperAdmin"
+                      "symbol": "Pauser"
                     }
                   ]
                 },

contracts/admin/test_snapshots/tests/proptest/fuzz_grant_role_emits_event.38.json

@@ -21,7 +21,7 @@
                 {
                   "vec": [
                     {
-                      "symbol": "Pauser"
+                      "symbol": "Admin"
                     }
                   ]
                 },
@@ -127,7 +127,7 @@
                 },
                 "durability": "persistent",
                 "val": {
-                  "u32": 8
+                  "u32": 1
                 }
               }
             },
@@ -292,7 +292,7 @@
                 {
                   "vec": [
                     {
-                      "symbol": "Pauser"
+                      "symbol": "Admin"
                     }
                   ]
                 },

contracts/admin/test_snapshots/tests/proptest/fuzz_grant_role_emits_event.9.json

@@ -21,7 +21,7 @@
                 {
                   "vec": [
                     {
-                      "symbol": "Minter"
+                      "symbol": "SuperAdmin"
                     }
                   ]
                 },
@@ -127,7 +127,7 @@
                 },
                 "durability": "persistent",
                 "val": {
-                  "u32": 2
+                  "u32": 4
                 }
               }
             },
@@ -292,7 +292,7 @@
                 {
                   "vec": [
                     {
-                      "symbol": "Minter"
+                      "symbol": "SuperAdmin"
                     }
                   ]
                 },

contracts/admin/test_snapshots/tests/proptest/fuzz_grant_role_every_variant.46.json

@@ -21,7 +21,7 @@
                 {
                   "vec": [
                     {
-                      "symbol": "Admin"
+                      "symbol": "Minter"
                     }
                   ]
                 },
@@ -128,7 +128,7 @@
                 },
                 "durability": "persistent",
                 "val": {
-                  "u32": 1
+                  "u32": 2
                 }
               }
             },
@@ -259,7 +259,7 @@
                 {
                   "vec": [
                     {
-                      "symbol": "Admin"
+                      "symbol": "Minter"
                     }
                   ]
                 },