Merge pull request #14 from davxy/improve-readme

Improve READMEs

Author: davxy

README.md

@@ -2,9 +2,44 @@
 
 JAM protocol version 0.6.1
 
-## Index
-
+## Codec
+ 
 - [Codec](./codec/README.md)
+
+## State Transition Functions
+
+We offer two types of test vectors:
+
+- **Tiny**: designed for quick adjustments and prototyping, with reduced
+  - validators count: 6
+  - cores count: 2
+  - epoch period: 12
+  - core assignment rotation period: 4
+  - ticket attempts: 3
+
+- **Full**: vectors with production specs
+  - validators count: 1023
+  - cores count: 341
+  - epoch period: 600
+  - core assignment rotation period: 10
+  - ticket attempts: 2
+
+### STF Output
+
+Technically, the STF execution process does not inherently produce auxiliary
+outputs beyond the success or failure result. In this context, we propose
+an extension to include additional information that may be beneficial for
+implementors or useful for executing other subsystems reliant on values
+generated post-STF execution.
+
+When the error or success values are not pertinent to your test vector
+processing procedures, you may disregard them as necessary.
+
+A mapping of error code semantics is provided within the ASN.1 schema for each
+specific subsystem.
+
+### Vectors
+
 - [Safrole](./safrole/README.md)
 - [Disputes](./disputes/README.md)
 - [History](./history/README.md)

accumulate/README.md

@@ -3,7 +3,7 @@
 Both JSON and SCALE formats conform to the JAM ASN.1 [schema](../jam-types-asn/jam-types.asn)
 and this subsystem STF specific [schema](./accumulate.asn).
 
-### Test Service Code
+## Test Service Code
 
 Test vectors invoke the `accumulate` method of the provided [test-service](./test-service).  
 

assurances/README.md

@@ -1,28 +1,8 @@
 # Availability Assurances STF Test Vectors
 
-We offer two types of test vectors:
-
-- Tiny: These are designed for quick adjustments and prototyping, with reduced validators (6)
-  and cores count (2).
-- Full: These vectors use production validators (1023) and cores count (341)
-
 Both JSON and SCALE formats conform to the JAM ASN.1 [schema](../jam-types-asn/jam-types.asn)
 and this subsystem STF specific [schema](./assurances.asn).
 
-## STF Output
-
-Technically, the STF execution process does not inherently produce auxiliary
-outputs beyond the success or failure result. In this context, we propose
-an extension to include additional information that may be beneficial for
-implementors or useful for executing other subsystems reliant on values
-generated post-STF execution.
-
-When the error or success values are not pertinent to your test vector
-processing procedures, you may disregard them as necessary.
-
-A mapping of error code semantics is provided within the ASN.1 schema for this
-subsystem.
-
 ## Tiny Vectors
 
 - [no_assurances-1](tiny/no_assurances-1.json)🟢

authorizations/README.md

@@ -1,10 +1,5 @@
 # Authorizations STF Test Vectors
 
-We offer two types of test vectors:
-
-- Tiny: These are designed for quick adjustments and prototyping, with reduced cores count (2)
-- Full: These vectors use production cores count (341).
-
 Both JSON and SCALE formats conform to the JAM ASN.1 [schema](../jam-types-asn/jam-types.asn)
 and this subsystem STF specific [schema](./authorizations.asn).
 

codec/README.md

@@ -40,31 +40,17 @@ any other future vectors focused on logic testing.
 ## Vectors
 
 - [refine_context](data/refine_context.json)
-
 - [work_item](data/work_item.json)
-
 - [work_package](data/work_package.json)
-
 - [work_result_0](data/work_result_0.json)
-
 - [work_result_1](data/work_result_1.json)
-
 - [work_report](data/work_report.json)
-
 - [tickets_extrinsic](data/tickets_extrinsic.json)
-
 - [disputes_extrinsic](data/disputes_extrinsic.json)
-
 - [preimages_extrinsic](data/preimages_extrinsic.json)
-
 - [assurance_extrinsic](data/assurances_extrinsic.json)
-
 - [guarantees_extrinsic](data/guarantees_extrinsic.json)
-
 - [header_0](data/header_0.json)
-
 - [header_1](data/header_1.json)
-
 - [extrinsic](data/extrinsic.json)
-
 - [block](data/block.json)

disputes/README.md

@@ -1,28 +1,8 @@
 # Disputes STF Test Vectors
 
-We offer two types of test vectors:
-
-- Tiny: These are designed for quick adjustments and prototyping, with reduced validators (6)
-  and a shorter epoch duration (12).
-- Full: These vectors use production validators count (1023) and epoch duration (600).
-
 Both JSON and SCALE formats conform to the JAM ASN.1 [schema](../jam-types-asn/jam-types.asn)
 and this subsystem STF specific [schema](./disputes.asn).
 
-## STF Output
-
-Technically, the STF execution process does not inherently produce auxiliary
-outputs beyond the success or failure result. In this context, we propose
-an extension to include additional information that may be beneficial for
-implementors or useful for executing other subsystems reliant on values
-generated post-STF execution.
-
-When the error or success values are not pertinent to your test vector
-processing procedures, you may disregard them as necessary.
-
-A mapping of error code semantics is provided within the ASN.1 schema for this
-subsystem.
-
 ## Availability Assignments
 
 Most tests use *null* entries for state availability assignments (*rho*).
@@ -33,79 +13,54 @@ tests that verify the invalidation of assignments following a verdict.
 
 - [progress_with_no_verdicts-1](tiny/progress_with_no_verdicts.json) 🟢 
   - No verdicts, nothing special happens
-
 - [progress_with_verdicts-1](tiny/progress_with_verdicts-1.json) 🔴
   - Not sorted work reports within a verdict
-
 - [progress_with_verdicts-2](tiny/progress_with_verdicts-2.json) 🔴
   - Not unique votes within a verdict
-
 - [progress_with_verdicts-3](tiny/progress_with_verdicts-3.json) 🔴
   - Not sorted, valid verdicts
-
 - [progress_with_verdicts-4](tiny/progress_with_verdicts-4.json) 🟢
   - Sorted, valid verdicts
-
 - [progress_with_verdicts-5](tiny/progress_with_verdicts-5.json) 🔴
   - Not homogeneous judgements, but positive votes count is not correct
-
 - [progress_with_verdicts-6](tiny/progress_with_verdicts-6.json) 🟢
   - Not homogeneous judgements, results in wonky verdict
-
 - [progress_with_culprits-1](tiny/progress_with_culprits-1.json) 🔴
   - Missing culprits for bad verdict
-
 - [progress_with_culprits-2](tiny/progress_with_culprits-2.json) 🔴
   - Single culprit for bad verdict
-
 - [progress_with_culprits-3](tiny/progress_with_culprits-3.json) 🔴
   - Two culprits for bad verdict, not sorted
-
 - [progress_with_culprits-4](tiny/progress_with_culprits-4.json) 🟢
   - Two culprits for bad verdict, sorted
-
 - [progress_with_culprits-5](tiny/progress_with_culprits-5.json) 🔴
   - Report an already recorded verdict, with culprits
-
 - [progress_with_culprits-6](tiny/progress_with_culprits-6.json) 🔴
   - Culprit offender already in the offenders list
-
 - [progress_with_culprits-7](tiny/progress_with_culprits-7.json) 🔴
   - Offender relative to a not present verdict
-
 - [progress_with_faults-1](tiny/progress_with_faults-1.json) 🔴
   - Missing faults for good verdict
-
 - [progress_with_faults-2](tiny/progress_with_faults-2.json) 🟢
   - One fault offender for good verdict
-
 - [progress_with_faults-3](tiny/progress_with_faults-3.json) 🔴
   - Two fault offenders for a good verdict, not sorted
-
 - [progress_with_faults-4](tiny/progress_with_faults-4.json) 🟢
   - Two fault offenders for a good verdict, sorted
-
 - [progress_with_faults-5](tiny/progress_with_faults-5.json) 🔴
   - Report an already recorded verdict, with faults
-
 - [progress_with_faults-6](tiny/progress_with_faults-6.json) 🔴
   - Fault offender already in the offenders list
-
 - [progress_with_faults-7](tiny/progress_with_faults-7.json) 🔴
   - Auditor marked as offender, but vote matches the verdict.
-
 - [progress_invalidates_avail_assignments-1](tiny/progress_invalidates_avail_assignments-1.json) 🟢
   - Invalidation of availability assignments
-
 - [progress_with_bad_signatures-1](tiny/progress_with_bad_signatures-1.json) 🔴
   - Bad signature within the verdict judgements
-
 - [progress_with_bad_signatures-2](tiny/progress_with_bad_signatures-2.json) 🔴
   - Bad signature within the culprits sequence
-
 - [progress_with_verdict_signatures_from_previous_set-1](tiny/progress_with_verdict_signatures_from_previous_set-1.json) 🟢
   - Use previous epoch validators set for verdict signatures verification
-
 - [progress_with_verdict_signatures_from_previous_set-2](tiny/progress_with_verdict_signatures_from_previous_set-2.json) 🔴
   - Age too old for verdicts judgements
 

history/README.md

@@ -1,7 +1,5 @@
 # Blocks History STF Test Vectors
 
-Both JSON and SCALE formats conform to the specified ASN.1 schema provided [here](./history.asn).
-
 Both JSON and SCALE formats conform to the JAM ASN.1 [schema](../jam-types-asn/jam-types.asn)
 and this subsystem STF specific [schema](./history.asn).
 
@@ -26,12 +24,9 @@ the input `accumulate_root`.
 
 - [progress_blocks_history-1](data/progress_blocks_history-1.json) 🟢 
   - Empty history queue.
-
 - [progress_blocks_history-2](data/progress_blocks_history-2.json) 🟢 
   - Not empty nor full history queue.
-
 - [progress_blocks_history-3](data/progress_blocks_history-3.json) 🟢 
   - Fill the history queue.
-
 - [progress_blocks_history-4](data/progress_blocks_history-4.json) 🟢 
   - Shift the history queue.

preimages/README.md

@@ -3,10 +3,13 @@
 Both JSON and SCALE formats conform to the JAM ASN.1 [schema](../jam-types-asn/jam-types.asn)
 and this subsystem STF specific [schema](./preimages.asn).
 
-## Services Accounts
-
-TODO
-
 ## Vectors
 
-TODO
+- [preimage_needed-1.json](./data/preimage_needed-1.json) 🟢
+  - Nothing is provided.
+- [preimage_needed-2.json](./data/preimage_needed-2.json) 🟢
+  - Provide one solicited blob.
+- [preimage_not_needed-1.json](./data/preimage_not_needed-1.json) 🔴
+  - Provide two blobs, but one of them has not been solicited.
+- [preimage_not_needed-2.json](./data/preimage_not_needed-2.json) 🔴
+  - Provide two blobs, but one of them has already been provided.

reports/README.md

@@ -1,29 +1,8 @@
 # Work Reports STF Test Vectors
 
-We offer two types of test vectors:
-
-- Tiny: These are designed for quick adjustments and prototyping, with reduced validators (6)
-  cores count (2) and report core assignment rotation period (4).
-- Full: These vectors use production validators (1023), cores count (341) and report core
-  assignment rotation period (10).
-
 Both JSON and SCALE formats conform to the JAM ASN.1 [schema](../jam-types-asn/jam-types.asn)
 and this subsystem STF specific [schema](./reports.asn).
 
-## STF Output
-
-Technically, the STF execution process does not inherently produce auxiliary
-outputs beyond the success or failure result. In this context, we propose
-an extension to include additional information that may be beneficial for
-implementors or useful for executing other subsystems reliant on values
-generated post-STF execution.
-
-When the error or success values are not pertinent to your test vector
-processing procedures, you may disregard them as necessary.
-
-A mapping of error code semantics is provided within the ASN.1 schema for this
-subsystem.
-
 ## Tiny Vectors
 
 - [report_curr_rotation](./tiny/report_curr_rotation-1.json) 🟢