docs: ADR-008 – Improvements on rewards withdrawal experience.

CHANGELOG.md

@@ -35,6 +35,7 @@ Contains all the PRs that improved the code without changing the behaviours.
 - [#481](https://github.com/archway-network/archway/pull/481) - Add Release Checklist issue type 
 - [](https://github.com/archway-network/archway/pull/502) - Improve rewards withdrawal experience by allowing a Metadata owner to set that rewards directly go to the reward address.
 - [#504](https://github.com/archway-network/archway/pull/504) - Interchain test gh workflow now runs on PRs targetting release branches as well as main 
+- [#462](https://github.com/archway-network/archway/pull/462) - adding docs ADR-008 – Improvements on rewards withdrawal experience
 
 ### Improvements
 

docs/adr/ADR-008-withdrawal-ux-improvements.md

@@ -0,0 +1,48 @@
+# ADR-008 – Refined Withdrawal User Experience
+
+Date: 2023-09-27
+
+## Status
+
+Proposed
+
+## Context
+
+Developer feedback suggests that the process of withdrawing gas and inflationary rewards on Archway is currently cumbersome
+and expensive. The existing process necessitates a contract to process a series of reward records, leading to substantial
+gas charges. Implementing this consumption process at the contract level is non-trivial.
+
+While the present reward withdrawal mechanism offers precision and supports the development of intricate distribution 
+contracts, many use-cases do not demand such detailed control. Developers often prefer a simpler approach where rewards
+are directly sent to a singular address.
+
+## Decision
+
+A new attribute named `withdraw_to_wallet` will be introduced in the `ContractMetadata`. When this attribute is
+activated (set to true), instead of generating a `RewardRecord` for the contract upon accruing gas or inflationary
+rewards, the rewards will be directly dispatched to the `ContractMetadata.withdraw_address`.
+
+- If `withdraw_to_wallet` is set to false, the `RewardRecord` will be generated, necessitating manual withdrawal.
+- If `withdraw_to_wallet` is set to true, the `RewardRecord` will not be generated, and rewards will be directly sent
+to the `ContractMetadata.withdraw_address`.
+
+By doing this when a consumer invokes a `MsgSetContractMetadata` TX, it will be allowed to set the `withdraw_to_wallet`
+to `true`. 
+
+## Consequences
+
+### Positive
+
+1. Eliminates the need for state migrations which, in the case of rewards, could be time-consuming due to extensive reward
+state data.
+2. Facilitates the creation of complex reward distribution contracts.
+3. Simplifies scenarios where a developer merely desires the funds to be sent to a specific address.
+4. Allows the owner to switch between automatic and manual distribution whenever necessary.
+
+### Neutral
+
+1. Existing `RewardRecords` will still require manual consumption.
+
+### Negative
+
+No known negative consequences at this time.