schema: add message receipts + description and comments informational fields (#209)

corpus/schema.json

@@ -21,9 +21,19 @@
       "additionalProperties": false,
       "properties": {
         "id": {
+          "title": "a unique identifier that identifies this test vector",
           "type": "string"
         },
         "version": {
+          "title": "the version of this test vector",
+          "type": "string"
+        },
+        "description": {
+          "title": "an optional description of the test vector",
+          "type": "string"
+        },
+        "comment": {
+          "title": "optional comments about this test vector, e.g. applicability, hints, rationale, etc.",
           "type": "string"
         },
         "gen": {
@@ -68,6 +78,26 @@
         }
       }
     },
+    "receipt": {
+      "type": "object",
+      "required": [
+        "exit_code",
+        "return",
+        "gas_used"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "exit_code": {
+          "type": "number"
+        },
+        "return": {
+          "$ref": "#/definitions/hex"
+        },
+        "gas_used": {
+          "type": "number"
+        }
+      }
+    },
     "preconditions": {
       "title": "execution preconditions",
       "description": "preconditions that need to be applied and satisfied before this test vector can be executed",
@@ -92,18 +122,23 @@
           "title": "state tree postconditions",
           "description": "state tree postconditions that must be true for this test vector to pass",
           "$ref": "#/definitions/state_tree"
+        },
+        "receipts": {
+          "title": "receipts to match",
+          "description": "receipts to match, required when using messages-class test vectors; length of this array MUST be equal to length of apply_messages",
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/receipt"
+          }
         }
       }
     },
     "apply_messages": {
-      "title": "messages to apply, hex-encoded",
+      "title": "messages to apply, along with the receipt to expect for each",
       "type": "array",
-      "items": [
-        {
-          "type": "string",
-          "$ref": "#/definitions/hex"
-        }
-      ]
+      "items": {
+        "$ref": "#/definitions/hex"
+      }
     }
   },
   "required": [
@@ -115,7 +150,7 @@
       "description": "test vector class; depending on the value, the apply_* property to provide (and its schema) will vary; the relevant apply property is apply_[class]",
       "type": "string",
       "enum": [
-        "message",
+        "messages",
         "block",
         "tipset",
         "chain"
@@ -146,7 +181,7 @@
       "if": {
         "properties": {
           "class": {
-            "const": "message"
+            "const": "messages"
           }
         }
       },

corpus/single_message.json

@@ -1,34 +1,40 @@
 {
-  "class": "message",
+  "class": "messages",
   "selector": "<some predicate for the driver to determine if this vector applies to the implementation, e.g. to deal with protocol upgrades>",
-
   "_meta": {
     "id": "test_vector_id",
     "version": "version_id",
+    "description": "tests that the VM rejects a message containing...",
+    "comment": "this message should never actually be fed to the VM, because the block would be deemed invalid by the syncer",
     "gen": {
       "source": "lotus",
       "version": "0.4.1+git.27d74337+api0.8.1"
     }
   },
-
   "car_bytes": "0x890043009920583103b5b1fab6769fcb464146d192af785915d8e1dacff264b2be3bcb7bf4064a77cb3b13e27063ea4825dc48cd0a7df77e211916e748002740f0c493a2824200011a09d9c4dc0758c68219091c58c083e7c59e748e070b382a813f4ffe8ead2a090469aaa37f0664b82c092bc78b43fac300335cd2d6e4a8c71ce138003c0fa8ee1707b41aa87f35c811613d59ac53449aef8263aa51c876f2e67c185118ec9628f73442f58e093909ce952e431e770ac693cdbe99f2f9404ad3ca754196ab443c6c66afa41310e705e453496bdcedf0f271529dc7374021d7b80d343397f996d06bf11e753a49eaed7b3ce80a8e9bbaa48bf83223527bd8a2933f002949fdb8058103336a4a979375d5e963cdd7b1",
-
   "preconditions": {
-    "height": 100,
+    "epoch": 100,
     "state_tree": {
       "root_cid": {
         "/": "bafy2bzacebbxsepazfgwepawspvzenb2x64pmqjyan3wgtfpxu5nxez33wzkc"
       }
     }
   },
-
-  "apply_message": "0x89004300ba20583103b85358cc1c968d826c0a0efcde99b6e4db138edfc051f188a4471cfc23ccf7884adbbac912e45f7363774bf16f83ca8f1902b44800505e1442e66b744200011a09d225c80758c68219016f58c099a447a8c80988e1c061dd3a8dd674033c3a6083c4b55cf035e6e8de3baf09436ad00adf6eb14d58ae6691d22ce82255874047e7aa0b9a86bbf424afc6d89dc29f7b253dd04c88a625b86345f05aa0bdee503971c1e9735ed5b81c31ad41a1f10b387d96151d1cbd0c4286267daf04087fd8d5272f870994c3732f3fc4f54287a485d6c8dafb6056df3fc9233f849027b4c1272850435126fef65a8363768a858c0cc5f9d9114ff378ad50cab25ab0a2f685ca63d9f1f7727da4d06db5b80b5f",
-
+  "apply_messages": [
+    "0x89004300ba20583103b85358cc1c968d826c0a0efcde99b6e4db138edfc051f188a4471cfc23ccf7884adbbac912e45f7363774bf16f83ca8f1902b44800505e1442e66b744200011a09d225c80758c68219016f58c099a447a8c80988e1c061dd3a8dd674033c3a6083c4b55cf035e6e8de3baf09436ad00adf6eb14d58ae6691d22ce82255874047e7aa0b9a86bbf424afc6d89dc29f7b253dd04c88a625b86345f05aa0bdee503971c1e9735ed5b81c31ad41a1f10b387d96151d1cbd0c4286267daf04087fd8d5272f870994c3732f3fc4f54287a485d6c8dafb6056df3fc9233f849027b4c1272850435126fef65a8363768a858c0cc5f9d9114ff378ad50cab25ab0a2f685ca63d9f1f7727da4d06db5b80b5f"
+  ],
   "postconditions": {
     "state_tree": {
       "root_cid": {
         "/": "bafy2bzacebbxsepazfgwepawspvzenb2x64pmqjyan3wgtfpxu5nxez33wzkc"
       }
-    }
+    },
+    "receipts": [
+      {
+        "exit_code": 10,
+        "gas_used": 1000,
+        "return": "0x"
+      }
+    ]
   }
 }

tvx/schema.go

@@ -3,8 +3,10 @@ package main
 import (
 	"encoding/hex"
 	"encoding/json"
+	"fmt"
 
 	"github.com/filecoin-project/specs-actors/actors/abi"
+	"github.com/filecoin-project/specs-actors/actors/runtime/exitcode"
 	"github.com/ipfs/go-cid"
 )
 
@@ -29,6 +31,8 @@ type Selector string
 type Metadata struct {
 	ID      string         `json:"id"`
 	Version string         `json:"version"`
+	Desc    string         `json:"description"`
+	Comment string         `json:"comment"`
 	Gen     GenerationData `json:"gen"`
 }
 
@@ -54,9 +58,17 @@ type Preconditions struct {
 	StateTree *StateTree     `json:"state_tree"`
 }
 
+// Receipt represents a receipt to match against.
+type Receipt struct {
+	ExitCode    exitcode.ExitCode `json:"exit_code"`
+	ReturnValue HexEncodedBytes   `json:"return"`
+	GasUsed     int64             `json:"gas_used"`
+}
+
 // Postconditions contain a representation of VM state at th end of the test
 type Postconditions struct {
 	StateTree *StateTree `json:"state_tree"`
+	Receipts  []*Receipt `json:"receipts"`
 }
 
 // MarshalJSON implements json.Marshal for HexEncodedBytes
@@ -94,3 +106,15 @@ type TestVector struct {
 	ApplyMessages []HexEncodedBytes `json:"apply_messages"`
 	Post          *Postconditions   `json:"postconditions"`
 }
+
+// Validate validates this test vector against the JSON schema, and applies
+// further validation rules that cannot be enforced through JSON Schema.
+func (tv TestVector) Validate() error {
+	// TODO validate against JSON Schema.
+	if tv.Class == ClassMessage {
+		if len(tv.Post.Receipts) != len(tv.ApplyMessages) {
+			return fmt.Errorf("length of postcondition receipts must match length of messages to apply")
+		}
+	}
+	return nil
+}