fix(contract): signal incomplete rotation from legacy admin aliases (#1159)

[Dennis-Ritchie1]

Closes #1159

Problem

transfer_admin / update_admin used to complete an admin rotation in one transaction. They now delegate to propose_admin — and that downgrade was invisible. Tooling and runbooks written against the old semantics see a successful transaction, conclude the handover is done, and (per the old documented procedure) decommission the outgoing key. If accept_admin never lands, the proposal expires after ~28.8 hours and the factory is stuck permanently under a key that no longer exists: no guardian override, no timelock bypass.

What changed

Contract — the aliases now say what they actually did, twice over:

• Return value. Both return an AdminRotationReceipt instead of ():

  Field	Value
  rotation_complete	always false — state.admin is unchanged
  pending_admin	the address that must accept
  expires_at_ledger	ledger at which the proposal lapses
  required_next_call	accept_admin

  A client decoding the old void return fails loudly instead of silently reporting success.

• Event. Both emit adm_dep — (current_admin, new_admin, expiry_ledger, deprecated_entrypoint) — in addition to adm_prop, so existing rotation monitoring keeps working while gaining a distinct signal that some caller still assumes one-step semantics.

Docs:

• docs/mainnet-deployment-checklist.md gains an Admin Key Rotation section: 8 ordered steps where accept_admin and a get_state() verification (admin = <new> and pending_admin = null) are required before the old key may be retired.
• docs/incident-response.md: break-glass activation (§7.4) and emergency rotation (§6.1) are rewritten as two transactions plus verification; new §2.5 Stale pending admin proposals documents thresholds, response order, and the TTL decision; adm_dep added to the alerting list; the tabletop exercise now rehearses both signatures.
• README, SECURITY.md and docs/contract-abi.md mark the aliases deprecated and document the receipt and the new event.

Monitoring: scripts/check-pending-admin-proposal.sh — cron-able (≤15 min) check that reads get_state(), ages the proposal against the TTL and exits 1 (warn, 6h), 2 (page, 12h), 3 (already expired), 4 (check failed).

TTL decision (documented either way, as the issue asked): left at 17,280 ledgers with no renew entrypoint. Renewal would have to be authorized by the current admin — the very key that is unavailable in the scenario a longer TTL is meant to rescue — while a long-lived proposal is a standing, accept-anytime claim on the factory if the proposed key is later lost. Recorded in lib.rs next to the constant and in runbook §2.5.

Frontend: adm_dep added to CONTRACT_TOPIC_MAP, ContractEventType and parseRpcEvent (decodes the entrypoint name so the stale caller can be traced).

Tests

• test_transfer_admin_receipt_signals_incomplete_rotation / test_update_admin_receipt_signals_incomplete_rotation — the receipt states the rotation has not happened and names accept_admin; its expiry matches state.
• test_legacy_aliases_emit_an_extra_deprecation_event — the aliases emit two events where propose_admin emits one.
• test_transfer_admin_alone_never_rotates_admin_even_after_expiry / ..._update_admin_... — locks in current behaviour: calling an alias alone leaves state.admin unchanged, accept_admin fails with ProposalExpired afterwards, and the old admin retains every privilege.
• Frontend: adm_dep decode test.

205 contract tests pass; cargo fmt --check and cargo clippy --all-targets clean; frontend typecheck, lint and stellar-impl tests pass; event-topic, ABI-doc and validation drift checks pass.

Acceptance criteria

• The on-chain result of transfer_admin / update_admin cannot be read as a completed rotation — rotation_complete: false in the return value, adm_dep in the event stream.
• The deployment checklist and every admin-rotation runbook sequence accept_admin (and its verification) as required before decommissioning the old key.
• A stale pending-admin-proposal monitoring recommendation exists in docs/incident-response.md (§2.5), backed by a script.

[github-actions]

🎉 This PR is included in version 1.8.6 🎉

The release is available on GitHub release

Your semantic-release bot 📦🚀