From 6ce13ba8a4a736e5db791e2e71bc071f674ff46b Mon Sep 17 00:00:00 2001
From: Slyghtning <hieblmi@protonmail.com>
Date: Wed, 1 Jul 2026 12:05:14 +0200
Subject: [PATCH] staticaddr/deposit: document lock ordering

Document the lock-order invariant between Manager.mu and individual
deposit locks.

Later changes need both locks in the same path, so make the rule
explicit before the locking surface grows.
---
 staticaddr/deposit/deposit.go | 4 ++++
 staticaddr/deposit/manager.go | 4 ++++
 2 files changed, 8 insertions(+)

diff --git a/staticaddr/deposit/deposit.go b/staticaddr/deposit/deposit.go
index 4cb64bc9..2121d170 100644
--- a/staticaddr/deposit/deposit.go
+++ b/staticaddr/deposit/deposit.go
@@ -29,6 +29,10 @@ func (r *ID) FromByteSlice(b []byte) error {
 
 // Deposit bundles an utxo at a static address together with manager-relevant
 // data.
+//
+// Lock order: if both Manager.mu and a Deposit lock are needed, acquire
+// Manager.mu before Deposit.Lock. Never acquire Manager.mu while holding a
+// Deposit lock.
 type Deposit struct {
 	sync.Mutex
 
diff --git a/staticaddr/deposit/manager.go b/staticaddr/deposit/manager.go
index 4da45ada..d07ba58a 100644
--- a/staticaddr/deposit/manager.go
+++ b/staticaddr/deposit/manager.go
@@ -58,6 +58,10 @@ type ManagerConfig struct {
 }
 
 // Manager manages the address state machines.
+//
+// Lock order: if both Manager.mu and a Deposit lock are needed, acquire
+// Manager.mu before Deposit.Lock. Never acquire Manager.mu while holding a
+// Deposit lock.
 type Manager struct {
 	cfg *ManagerConfig