ADR 004: Fee module locking in the presence of severe bugs

docs/architecture/README.md

@@ -30,6 +30,7 @@ To suggest an ADR, please make use of the [ADR template](./adr-template.md) prov
 | [001](./adr-001-coin-source-tracing.md) | ICS-20 coin denomination format | Accepted, Implemented |
 | [002](./adr-002-go-module-versioning.md) | Go module versioning | Accepted |
 | [003](./adr-003-ics27-acknowledgement.md) | ICS27 acknowledgement format | Accepted |
+| [004](./adr-004-ics29-lock-fee-module.md) | ICS29 module locking upon escrow out of balance | Accepted |
 | [015](./adr-015-ibc-packet-receiver.md) | IBC Packet Routing | Accepted |
 | [025](./adr-025-ibc-passive-channels.md) | IBC passive channels | Deprecated |
 | [026](./adr-026-ibc-client-recovery-mechanisms.md) | IBC client recovery mechansisms | Accepted |

docs/architecture/adr-004-ics29-lock-fee-module.md

@@ -0,0 +1,55 @@
+# ADR 004: Lock fee module upon escrow out of balance
+
+## Changelog
+* 03/03/2022: initial draft
+
+## Status
+
+Accepted
+
+## Context
+
+The fee module maintains an escrow account for each of the fees escrowed to incentivize packet relays. 
+It also tracks each packet fee escrowed separately from the escrow account. This is because the escrow account only maintains a total balance. It has no reference for which coins belonged to which packet fee. 
+In the presence of a severe bug, it is possible the escrow balance will become out of sync with the packet fees marked as escrowed.
+The ICS29 module should be capable of elegantly handling such a scenario.
+
+## Decision
+
+We will allow for the ICS29 module to become "locked" if the escrow balance is determined to be out of sync with the packet fees marked as escrowed. 
+A "locked" fee module will not allow for packet escrows to occur nor will it distribute fees. All IBC callbacks will skip performing fee logic, similar to fee disabled channels. 
+
+Manual intervention will be needed to unlock the fee module. 
+
+### Sending side
+
+Special behaviour will have to be accounted for in `OnAcknowledgementPacket`. Since the counterparty will continue to send incentivized acknowledgements for fee enabled channels, the acknowledgement will need to be unmarshalled into an incentivized acknowledgement before calling the underlying application `OnAcknowledgePacket` callback. 
+
+When distributing fees, a cached context should be used. If the escrow account balance would become negative, the current state changes should be discarded and the fee module should be locked using the uncached context. This prevents fees from being partially distributed for a given packetID.
+
+### Receiving side
+
+`OnRecvPacket` should remain unaffected by the fee module becoming locked since escrow accounts only affect the sending side. 
+
+## Consequences
+
+### Positive
+
+The fee module can be elegantly disabled in the presence of severe bugs.
+
+### Negative
+
+Extra logic is added to account for edge cases which are only possible in the presence of bugs. 
+
+### Neutral
+
+## References
+
+Issues:
+- [#821](https://github.com/cosmos/ibc-go/issues/821)
+- [#860](https://github.com/cosmos/ibc-go/issues/860)
+
+PR's:
+- [#1031](https://github.com/cosmos/ibc-go/pull/1031)
+- [#1029](https://github.com/cosmos/ibc-go/pull/1029)
+- [#1056](https://github.com/cosmos/ibc-go/pull/1056)