docs(adr): Change Textual SignDoc to struct (#15282)

cosmos · Mar 14, 2023 · a539a03 · a539a03
1 parent 0282cfe
commit a539a03
Show file tree

Hide file tree

Showing 4 changed files with 36 additions and 15 deletions.
diff --git a/docs/architecture/adr-050-sign-mode-textual.md b/docs/architecture/adr-050-sign-mode-textual.md
@@ -13,6 +13,7 @@
 * Dec 06, 2022: Re-ordering of envelope screens.
 * Dec 14, 2022: Mention exceptions for invertability.
 * Jan 23, 2022: Switch Screen.Text to Title+Content.
+* Mar 07, 2023: Change SignDoc from array to struct containing array.
 
 ## Status
 
@@ -135,7 +136,9 @@ type Screen struct {
   Expert bool
 }
 
-type SignDocTextual = []Screen
+type SignDocTextual struct {
+  Screens []Screen
+}
 ```
 
 We do not plan to use protobuf serialization to form the sequence of bytes
@@ -147,8 +150,13 @@ The encoding is defined by the following CDDL ([RFC 8610](https://www.rfc-editor
 ;;; CDDL (RFC 8610) Specification of SignDoc for SIGN_MODE_TEXTUAL.
 ;;; Must be encoded using CBOR deterministic encoding (RFC 8949, section 4.2.1).
 
-;; A Textual document is an array of screens.
-screens = [* screen]
+;; A Textual document is a struct containing one field: an array of screens.
+sign_doc = {
+  screens_key: [* screen],
+}
+
+;; The key is an integer to keep the encoding small.
+screens_key = 1
 
 ;; A screen consists of a text string, an indentation, and the expert flag,
 ;; represented as an integer-keyed map. All entries are optional
@@ -169,6 +177,8 @@ indent_key = 3
 expert_key = 4
 ```
 
+Defining the sign_doc as directly an array of screens has also been considered. However, given the possibility of future iterations of this specification, using a single-keyed struct has been chosen over the former proposal, as structs allow for easier backwards-compatibility.
+
 ## Details
 
 In the examples that follow, screens will be shown as lines of text,

diff --git a/x/tx/signing/textual/encode.go b/x/tx/signing/textual/encode.go
@@ -7,15 +7,24 @@ import (
 )
 
 var (
+	// Keys in the SignDoc struct
+	screensKey = cbor.NewUint(1)
+
+	// Keys in the Screen struct
 	titleKey   = cbor.NewUint(1)
 	contentKey = cbor.NewUint(2)
 	indentKey  = cbor.NewUint(3)
 	expertKey  = cbor.NewUint(4)
 )
 
-// encode encodes an array of screens according to the CDDL:
+// encode encodes a struct containing an array of screens according to the
+// CDDL:
+//
+//	sign_doc = {
+//	  screens_key: [* screen],
+//	}
+//	screens_key = 1
 //
-//	screens = [* screen]
 //	screen = {
 //	  ? title_key: tstr,
 //	  ? content_key: tstr,
@@ -33,7 +42,9 @@ func encode(screens []Screen, w io.Writer) error {
 	for _, s := range screens {
 		arr = arr.Append(s.Cbor())
 	}
-	return arr.Encode(w)
+
+	signDoc := cbor.NewMap(cbor.NewEntry(screensKey, arr))
+	return signDoc.Encode(w)
 }
 
 func (s Screen) Cbor() cbor.Cbor {

diff --git a/x/tx/signing/textual/internal/testdata/e2e.json b/x/tx/signing/textual/internal/testdata/e2e.json
@@ -64,7 +64,7 @@
 			{ "title": "Gas limit", "content": "100'000", "expert": true },
 			{ "title": "Hash of raw bytes", "content": "785bd306ea8962cdb9600089bdd65f3dc029e1aea112dee69e19546c9adad86e", "expert": true }
 		],
-		"cbor": "8fa20168436861696e20696402686d792d636861696ea2016e4163636f756e74206e756d626572026131a2016853657175656e6365026132a301674164647265737302782d636f736d6f7331756c6176336873656e7570737771666b77327933737570356b677471776e767161386579687304f5a3016a5075626c6963206b657902781f2f636f736d6f732e63727970746f2e736563703235366b312e5075624b657904f5a401634b657902785230324542204444374620453446442045423736204443384120323035452046363544203739304320443330452038413337203541354320323532382045423341203932334120463146422034443739203444030104f5a102781e54686973207472616e73616374696f6e206861732031204d657373616765a3016d4d6573736167652028312f312902781c2f636f736d6f732e62616e6b2e763162657461312e4d736753656e640301a3016c46726f6d206164647265737302782d636f736d6f7331756c6176336873656e7570737771666b77327933737570356b677471776e76716138657968730302a3016a546f206164647265737302782d636f736d6f7331656a726634637572327779366b667572673966326a707070326833616665356836706b6835740302a30166416d6f756e74026731302041544f4d0302a1026e456e64206f66204d657373616765a2016446656573026a302e3030322041544f4da30169476173206c696d697402673130302730303004f5a3017148617368206f66207261772062797465730278403738356264333036656138393632636462393630303038396264643635663364633032396531616561313132646565363965313935343663396164616438366504f5"
+		"cbor": "a1018fa20168436861696e20696402686d792d636861696ea2016e4163636f756e74206e756d626572026131a2016853657175656e6365026132a301674164647265737302782d636f736d6f7331756c6176336873656e7570737771666b77327933737570356b677471776e767161386579687304f5a3016a5075626c6963206b657902781f2f636f736d6f732e63727970746f2e736563703235366b312e5075624b657904f5a401634b657902785230324542204444374620453446442045423736204443384120323035452046363544203739304320443330452038413337203541354320323532382045423341203932334120463146422034443739203444030104f5a102781e54686973207472616e73616374696f6e206861732031204d657373616765a3016d4d6573736167652028312f312902781c2f636f736d6f732e62616e6b2e763162657461312e4d736753656e640301a3016c46726f6d206164647265737302782d636f736d6f7331756c6176336873656e7570737771666b77327933737570356b677471776e76716138657968730302a3016a546f206164647265737302782d636f736d6f7331656a726634637572327779366b667572673966326a707070326833616665356836706b6835740302a30166416d6f756e74026731302041544f4d0302a1026e456e64206f66204d657373616765a2016446656573026a302e3030322041544f4da30169476173206c696d697402673130302730303004f5a3017148617368206f66207261772062797465730278403738356264333036656138393632636462393630303038396264643635663364633032396531616561313132646565363965313935343663396164616438366504f5"
 	},
 	{
 		"name": "a bit of everything",
@@ -257,6 +257,6 @@
 			{ "content": "End of Non critical extension options", "expert": true },
 			{ "title": "Hash of raw bytes", "content": "7ea02e8f0baed2db969e2d9ae4dc51fa31116259bd42897588072faf0ebb4d2e", "expert": true }
 		],
-		"cbor": "983fa20168436861696e20696402686d792d636861696ea2016e4163636f756e74206e756d626572026131a2016853657175656e6365026132a301674164647265737302782d636f736d6f7331756c6176336873656e7570737771666b77327933737570356b677471776e767161386579687304f5a3016a5075626c6963206b657902781f2f636f736d6f732e63727970746f2e736563703235366b312e5075624b657904f5a401634b657902785230324542204444374620453446442045423736204443384120323035452046363544203739304320443330452038413337203541354320323532382045423341203932334120463146422034443739203444030104f5a102781f54686973207472616e73616374696f6e206861732032204d65737361676573a3016d4d6573736167652028312f322902781d2f636f736d6f732e617574687a2e763162657461312e4d7367457865630301a301674772616e74656502782d636f736d6f7331756c6176336873656e7570737771666b77327933737570356b677471776e76716138657968730302a301644d73677302653120416e790302a3016a4d7367732028312f312902781c2f636f736d6f732e62616e6b2e763162657461312e4d736753656e640303a3016c46726f6d206164647265737302782d636f736d6f7331756c6176336873656e7570737771666b77327933737570356b677471776e76716138657968730304a3016a546f206164647265737302782d636f736d6f7331656a726634637572327779366b667572673966326a707070326833616665356836706b6835740304a30166416d6f756e74026731302041544f4d0304a2026b456e64206f66204d7367730302a3016d4d6573736167652028322f322902762f636f736d6f732e676f762e76312e4d7367566f74650301a3016b50726f706f73616c2069640261310302a30165566f74657202782d636f736d6f7331756c6176336873656e7570737771666b77327933737570356b677471776e76716138657968730302a301664f7074696f6e026f564f54455f4f5054494f4e5f5945530302a301684d65746164617461027901e34c6f72656d20697073756d20646f6c6f722073697420616d65742c20636f6e73656374657475722061646970697363696e6720656c69742c2073656420646f20656975736d6f642074656d706f7220696e6369646964756e74207574206c61626f726520657420646f6c6f7265206d61676e6120616c697175612e20557420656e696d206164206d696e696d2076656e69616d2c2071756973206e6f737472756420657865726369746174696f6e20756c6c616d636f206c61626f726973206e69736920757420616c697175697020657820656120636f6d6d6f646f20636f6e7365717561742e2044756973206175746520697275726520646f6c6f7220696e20726570726568656e646572697420696e20766f6c7570746174652076656c697420657373652063696c6c756d20646f6c6f726520657520667567696174206e756c6c612070617269617475722e204578636570746575722073696e74206f6363616563617420637570696461746174206e6f6e2070726f6964656e742c2073756e7420696e2063756c706120717569206f666669636961206465736572756e74206d6f6c6c697420616e696d20696420657374206c61626f72756d2e20416c736f20697420656e647320696e2020612073696e676c6520616d70657273616e6420400302a1026e456e64206f66204d657373616765a201644d656d6f0278193e20e29a9befb88f5c7532363942e29a9befb88f2020202020a2016446656573026a302e3030322041544f4da3016946656520706179657202782d636f736d6f7331656a726634637572327779366b667572673966326a707070326833616665356836706b68357404f5a3016b466565206772616e74657202782d636f736d6f7331756c6176336873656e7570737771666b77327933737570356b677471776e767161386579687304f5a201635469700277302e30322041544f4d2c2033302730303020756f736d6fa2016654697070657202782d636f736d6f7331656a726634637572327779366b667572673966326a707070326833616665356836706b683574a30169476173206c696d697402673130302730303004f5a3016e54696d656f7574206865696768740262323004f5a3016c4f74686572207369676e6572026c31205369676e6572496e666f04f5a401724f74686572207369676e65722028312f312902715369676e6572496e666f206f626a656374030104f5a4016a5075626c6963206b65790278292f636f736d6f732e63727970746f2e6d756c74697369672e4c6567616379416d696e6f5075624b6579030204f5a401695468726573686f6c64026132030304f5a4016b5075626c6963206b65797302653220416e79030304f5a401715075626c6963206b6579732028312f322902781f2f636f736d6f732e63727970746f2e736563703235366b312e5075624b6579030404f5a401634b657902785230323537203445424520304246432037353446203539363720334241312031423237203530304620393135382041444532204531374520314130312038324230204341384220433635322034444230203933030504f5a401715075626c6963206b6579732028322f322902781d2f636f736d6f732e63727970746f2e656432353531392e5075624b6579030404f5a401634b657902785230333135203043343720463138412041333237203136413620353437452044413842203733363920303637442043453131204431343120363234352042373738203735364320463833352039363738203737030504f5a30272456e64206f66205075626c6963206b657973030304f5a401694d6f646520696e666f026f4d6f6465496e666f206f626a656374030204f5a401654d756c7469026c4d756c7469206f626a656374030304f5a4016842697461727261790276436f6d706163744269744172726179206f626a656374030404f5a40171457874726120626974732073746f726564026135030504f5a40165456c656d7302623438030504f5a4016a4d6f646520696e666f73026a32204d6f6465496e666f030404f5a401704d6f646520696e666f732028312f3229026f4d6f6465496e666f206f626a656374030504f5a4016653696e676c65026d53696e676c65206f626a656374030604f5a401644d6f646502781b5349474e5f4d4f44455f4c45474143595f414d494e4f5f4a534f4e030704f5a401704d6f646520696e666f732028322f3229026f4d6f6465496e666f206f626a656374030504f5a4016653696e676c65026d53696e676c65206f626a656374030604f5a401644d6f646502781b5349474e5f4d4f44455f4c45474143595f414d494e4f5f4a534f4e030704f5a30271456e64206f66204d6f646520696e666f73030404f5a4016853657175656e6365026135030204f5a20273456e64206f66204f74686572207369676e657204f5a30171457874656e73696f6e206f7074696f6e7302653120416e7904f5a40177457874656e73696f6e206f7074696f6e732028312f31290278192f636f736d6f732e626173652e763162657461312e436f696e030104f5a30266352041544f4d030204f5a2027818456e64206f6620457874656e73696f6e206f7074696f6e7304f5a301781e4e6f6e20637269746963616c20657874656e73696f6e206f7074696f6e7302653120416e7904f5a40178244e6f6e20637269746963616c20657874656e73696f6e206f7074696f6e732028312f312902781b2f636f736d6f732e617574682e763162657461312e506172616d73030104f5a401734d6178206d656d6f206368617261637465727302623130030204f5a2027825456e64206f66204e6f6e20637269746963616c20657874656e73696f6e206f7074696f6e7304f5a3017148617368206f66207261772062797465730278403765613032653866306261656432646239363965326439616534646335316661333131313632353962643432383937353838303732666166306562623464326504f5"
+		"cbor": "a101983fa20168436861696e20696402686d792d636861696ea2016e4163636f756e74206e756d626572026131a2016853657175656e6365026132a301674164647265737302782d636f736d6f7331756c6176336873656e7570737771666b77327933737570356b677471776e767161386579687304f5a3016a5075626c6963206b657902781f2f636f736d6f732e63727970746f2e736563703235366b312e5075624b657904f5a401634b657902785230324542204444374620453446442045423736204443384120323035452046363544203739304320443330452038413337203541354320323532382045423341203932334120463146422034443739203444030104f5a102781f54686973207472616e73616374696f6e206861732032204d65737361676573a3016d4d6573736167652028312f322902781d2f636f736d6f732e617574687a2e763162657461312e4d7367457865630301a301674772616e74656502782d636f736d6f7331756c6176336873656e7570737771666b77327933737570356b677471776e76716138657968730302a301644d73677302653120416e790302a3016a4d7367732028312f312902781c2f636f736d6f732e62616e6b2e763162657461312e4d736753656e640303a3016c46726f6d206164647265737302782d636f736d6f7331756c6176336873656e7570737771666b77327933737570356b677471776e76716138657968730304a3016a546f206164647265737302782d636f736d6f7331656a726634637572327779366b667572673966326a707070326833616665356836706b6835740304a30166416d6f756e74026731302041544f4d0304a2026b456e64206f66204d7367730302a3016d4d6573736167652028322f322902762f636f736d6f732e676f762e76312e4d7367566f74650301a3016b50726f706f73616c2069640261310302a30165566f74657202782d636f736d6f7331756c6176336873656e7570737771666b77327933737570356b677471776e76716138657968730302a301664f7074696f6e026f564f54455f4f5054494f4e5f5945530302a301684d65746164617461027901e34c6f72656d20697073756d20646f6c6f722073697420616d65742c20636f6e73656374657475722061646970697363696e6720656c69742c2073656420646f20656975736d6f642074656d706f7220696e6369646964756e74207574206c61626f726520657420646f6c6f7265206d61676e6120616c697175612e20557420656e696d206164206d696e696d2076656e69616d2c2071756973206e6f737472756420657865726369746174696f6e20756c6c616d636f206c61626f726973206e69736920757420616c697175697020657820656120636f6d6d6f646f20636f6e7365717561742e2044756973206175746520697275726520646f6c6f7220696e20726570726568656e646572697420696e20766f6c7570746174652076656c697420657373652063696c6c756d20646f6c6f726520657520667567696174206e756c6c612070617269617475722e204578636570746575722073696e74206f6363616563617420637570696461746174206e6f6e2070726f6964656e742c2073756e7420696e2063756c706120717569206f666669636961206465736572756e74206d6f6c6c697420616e696d20696420657374206c61626f72756d2e20416c736f20697420656e647320696e2020612073696e676c6520616d70657273616e6420400302a1026e456e64206f66204d657373616765a201644d656d6f0278193e20e29a9befb88f5c7532363942e29a9befb88f2020202020a2016446656573026a302e3030322041544f4da3016946656520706179657202782d636f736d6f7331656a726634637572327779366b667572673966326a707070326833616665356836706b68357404f5a3016b466565206772616e74657202782d636f736d6f7331756c6176336873656e7570737771666b77327933737570356b677471776e767161386579687304f5a201635469700277302e30322041544f4d2c2033302730303020756f736d6fa2016654697070657202782d636f736d6f7331656a726634637572327779366b667572673966326a707070326833616665356836706b683574a30169476173206c696d697402673130302730303004f5a3016e54696d656f7574206865696768740262323004f5a3016c4f74686572207369676e6572026c31205369676e6572496e666f04f5a401724f74686572207369676e65722028312f312902715369676e6572496e666f206f626a656374030104f5a4016a5075626c6963206b65790278292f636f736d6f732e63727970746f2e6d756c74697369672e4c6567616379416d696e6f5075624b6579030204f5a401695468726573686f6c64026132030304f5a4016b5075626c6963206b65797302653220416e79030304f5a401715075626c6963206b6579732028312f322902781f2f636f736d6f732e63727970746f2e736563703235366b312e5075624b6579030404f5a401634b657902785230323537203445424520304246432037353446203539363720334241312031423237203530304620393135382041444532204531374520314130312038324230204341384220433635322034444230203933030504f5a401715075626c6963206b6579732028322f322902781d2f636f736d6f732e63727970746f2e656432353531392e5075624b6579030404f5a401634b657902785230333135203043343720463138412041333237203136413620353437452044413842203733363920303637442043453131204431343120363234352042373738203735364320463833352039363738203737030504f5a30272456e64206f66205075626c6963206b657973030304f5a401694d6f646520696e666f026f4d6f6465496e666f206f626a656374030204f5a401654d756c7469026c4d756c7469206f626a656374030304f5a4016842697461727261790276436f6d706163744269744172726179206f626a656374030404f5a40171457874726120626974732073746f726564026135030504f5a40165456c656d7302623438030504f5a4016a4d6f646520696e666f73026a32204d6f6465496e666f030404f5a401704d6f646520696e666f732028312f3229026f4d6f6465496e666f206f626a656374030504f5a4016653696e676c65026d53696e676c65206f626a656374030604f5a401644d6f646502781b5349474e5f4d4f44455f4c45474143595f414d494e4f5f4a534f4e030704f5a401704d6f646520696e666f732028322f3229026f4d6f6465496e666f206f626a656374030504f5a4016653696e676c65026d53696e676c65206f626a656374030604f5a401644d6f646502781b5349474e5f4d4f44455f4c45474143595f414d494e4f5f4a534f4e030704f5a30271456e64206f66204d6f646520696e666f73030404f5a4016853657175656e6365026135030204f5a20273456e64206f66204f74686572207369676e657204f5a30171457874656e73696f6e206f7074696f6e7302653120416e7904f5a40177457874656e73696f6e206f7074696f6e732028312f31290278192f636f736d6f732e626173652e763162657461312e436f696e030104f5a30266352041544f4d030204f5a2027818456e64206f6620457874656e73696f6e206f7074696f6e7304f5a301781e4e6f6e20637269746963616c20657874656e73696f6e206f7074696f6e7302653120416e7904f5a40178244e6f6e20637269746963616c20657874656e73696f6e206f7074696f6e732028312f312902781b2f636f736d6f732e617574682e763162657461312e506172616d73030104f5a401734d6178206d656d6f206368617261637465727302623130030204f5a2027825456e64206f66204e6f6e20637269746963616c20657874656e73696f6e206f7074696f6e7304f5a3017148617368206f66207261772062797465730278403765613032653866306261656432646239363965326439616534646335316661333131313632353962643432383937353838303732666166306562623464326504f5"
 	}
 ]
diff --git a/x/tx/signing/textual/internal/testdata/encode.json b/x/tx/signing/textual/internal/testdata/encode.json
@@ -1,19 +1,19 @@
 [
     {
         "screens": [],
-        "encoding": "80"
+        "encoding": "a10180"
     },
     {
         "screens": [{}],
-        "encoding": "81a0"
+        "encoding": "a10181a0"
     },
     {
         "screens": [{"content": ""}, {"indent": 0}, {"expert": false}],
-        "encoding": "83a0a0a0"
+        "encoding": "a10183a0a0a0"
     },
     {
         "screens": [{"title": ""}, {"content": ""}, {"indent": 0}, {"expert": false}],
-        "encoding": "84a0a0a0a0"
+        "encoding": "a10184a0a0a0a0"
     },
     {
         "screens": [
@@ -22,22 +22,22 @@
             {"indent": 1},
             {"expert": true}
         ],
-        "encoding": "84a1016131a1026161a10301a104f5"
+        "encoding": "a10184a1016131a1026161a10301a104f5"
     },
     {
         "screens": [
             {"title": "1", "content": "", "indent": 4, "expert": true},
             {"title": "", "content": "a", "indent": 0, "expert": true},
             {"title": "2", "content": "b", "indent": 5, "expert": false}
         ],
-        "encoding": "83a3016131030404f5a202616104f5a30161320261620305"
+        "encoding": "a10183a3016131030404f5a202616104f5a30161320261620305"
     },
     {
         "screens": [
             {"title": "first", "content": "start"},
             {"title": "then", "content": "middle", "indent": 1},
             {"title": "last", "content": "end"}
         ],
-        "encoding": "83a20165666972737402657374617274a301647468656e02666d6964646c650301a201646c6173740263656e64"
+        "encoding": "a10183a20165666972737402657374617274a301647468656e02666d6964646c650301a201646c6173740263656e64"
     }
 ]