From b09e8599d933e1071a0d35e8264ce53ae71fb2b8 Mon Sep 17 00:00:00 2001
From: Dev Ojha <ValarDragon@users.noreply.github.com>
Date: Mon, 17 Sep 2018 08:26:21 -0700
Subject: [PATCH] Merge PR #2334: ADR for global message counter

---
 .../{ => decision-records}/README.md          |  0
 .../adr-001-message-counter.md                | 54 +++++++++++++++++++
 .../{ => decision-records}/adr-template.md    |  2 +-
 3 files changed, 55 insertions(+), 1 deletion(-)
 rename docs/architecture/{ => decision-records}/README.md (100%)
 create mode 100644 docs/architecture/decision-records/adr-001-message-counter.md
 rename docs/architecture/{ => decision-records}/adr-template.md (98%)

diff --git a/docs/architecture/README.md b/docs/architecture/decision-records/README.md
similarity index 100%
rename from docs/architecture/README.md
rename to docs/architecture/decision-records/README.md
diff --git a/docs/architecture/decision-records/adr-001-message-counter.md b/docs/architecture/decision-records/adr-001-message-counter.md
new file mode 100644
index 000000000..0e9f25990
--- /dev/null
+++ b/docs/architecture/decision-records/adr-001-message-counter.md
@@ -0,0 +1,54 @@
+# ADR 001: Global Message Counter
+
+## Context
+
+There is a desire for modules to have a concept of orderings between messages.
+
+One such example is in staking, we currently use an "intra bond tx counter" and
+bond height.
+The purpose these two serve is to providing an ordering for validators with equal stake,
+for usage in the power-ranking of validators.
+We can't use address here, as that would create a bad incentive to grind
+addresses that optimized the sort function, which lowers the private key's
+security.
+Instead we order by whose transaction appeared first, as tracked by bondHeight
+and intra bond tx counter. 
+
+This logic however should not be unique to staking.
+It is very conceivable that many modules in the future will want to be able to
+know the ordering of messages / objects after they were initially created.
+
+## Decision
+
+Create a global message counter field of type int64.
+Note that with int64's, there is no fear of overflow under normal use,
+as it is only getting incremented by one,
+and thus has a space of 9 quintillion values to go through.
+
+This counter must be persisted in state, but can just be read and written on 
+begin/end block respectively.
+This field will get incremented upon every DeliverTx,
+regardless if the transaction succeeds or not. 
+It must also be incremented within the check state for CheckTx.
+The global message ordering field should be set within the context
+so that modules can access it.
+
+## Corollary - Intra block ordering
+In the event that there is desire to just have an intra block msg counter,
+this can easily be derived from the global message counter.
+Simply subtract current counter from first global message counter in the block.
+Thus the relevant module could easily implement this.
+
+## Status
+Proposed
+
+## Consequences
+
+### Positive
+* Moves message ordering out of the set of things staking must keep track of
+* Abstracts the logic well so other modules can use it
+
+### Negative
+* Another thing to implement prelaunch. (Though this should be easy to implement)
+
+### Neutral
diff --git a/docs/architecture/adr-template.md b/docs/architecture/decision-records/adr-template.md
similarity index 98%
rename from docs/architecture/adr-template.md
rename to docs/architecture/decision-records/adr-template.md
index 4ff7ad946..6153a9d1e 100644
--- a/docs/architecture/adr-template.md
+++ b/docs/architecture/decision-records/adr-template.md
@@ -29,4 +29,4 @@ If the proposed change will be large, please also indicate a way to do the chang
 ## References
 > Are there any relevant PR comments, issues that led up to this, or articles referrenced for why we made the given design choice? If so link them here!
 
-* {reference link}
\ No newline at end of file
+* {reference link}