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

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,

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 {

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,7 +22,7 @@
             {"indent": 1},
             {"expert": true}
         ],
-        "encoding": "84a1016131a1026161a10301a104f5"
+        "encoding": "a10184a1016131a1026161a10301a104f5"
     },
     {
         "screens": [
@@ -30,7 +30,7 @@
             {"title": "", "content": "a", "indent": 0, "expert": true},
             {"title": "2", "content": "b", "indent": 5, "expert": false}
         ],
-        "encoding": "83a3016131030404f5a202616104f5a30161320261620305"
+        "encoding": "a10183a3016131030404f5a202616104f5a30161320261620305"
     },
     {
         "screens": [
@@ -38,6 +38,6 @@
             {"title": "then", "content": "middle", "indent": 1},
             {"title": "last", "content": "end"}
         ],
-        "encoding": "83a20165666972737402657374617274a301647468656e02666d6964646c650301a201646c6173740263656e64"
+        "encoding": "a10183a20165666972737402657374617274a301647468656e02666d6964646c650301a201646c6173740263656e64"
     }
 ]