Skip to content

Commit 26016ac

Browse files
gavofyorkgavofyork
authored
Merge pull request w3f#28 from davxy/polkajam-vectors
STF Vectors
2 parents 041b835 + 85e153b commit 26016ac

File tree

600 files changed

+2905261
-5848
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

600 files changed

+2905261
-5848
lines changed

‎README.md‎

Lines changed: 46 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,51 @@
11
# Test Vectors for the JAM Protocol
22

3-
## Index
3+
JAM protocol version 0.6.4
44

5+
## Codec
6+
57
- [Codec](./codec/README.md)
8+
9+
## State Transition Functions
10+
11+
We offer two types of test vectors:
12+
13+
- **Tiny**: designed for quick adjustments and prototyping, with reduced
14+
- validators count: 6
15+
- cores count: 2
16+
- epoch period: 12
17+
- core assignment rotation period: 4
18+
- ticket attempts: 3
19+
20+
- **Full**: vectors with production specs
21+
- validators count: 1023
22+
- cores count: 341
23+
- epoch period: 600
24+
- core assignment rotation period: 10
25+
- ticket attempts: 2
26+
27+
### STF Output
28+
29+
Technically, the STF execution process does not inherently produce auxiliary
30+
outputs beyond the success or failure result. In this context, we propose
31+
an extension to include additional information that may be beneficial for
32+
implementors or useful for executing other subsystems reliant on values
33+
generated post-STF execution.
34+
35+
When the error or success values are not pertinent to your test vector
36+
processing procedures, you may disregard them as necessary.
37+
38+
A mapping of error code semantics is provided within the ASN.1 schema for each
39+
specific subsystem.
40+
41+
### Vectors
42+
643
- [Safrole](./safrole/README.md)
44+
- [Disputes](./disputes/README.md)
45+
- [History](./history/README.md)
46+
- [Assurances](./assurances/README.md)
47+
- [Reports](./reports/README.md)
48+
- [Statistics](./statistics/README.md)
49+
- [Authorizations](./authorizations/README.md)
50+
- [Preimages](./preimages/README.md)
51+
- [Accumulate](./accumulate/README.md)

‎accumulate/README.md‎

Lines changed: 94 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,94 @@
1+
# Accumulate STF Test Vectors
2+
3+
Both JSON and SCALE formats conform to the JAM ASN.1 [schema](../jam-types-asn/jam-types.asn)
4+
and this subsystem STF specific [schema](./accumulate.asn).
5+
6+
## Test Service Code
7+
8+
Test vectors invoke the `accumulate` method of the provided [test-service](./test-service).
9+
10+
The PVM binary, which refers to the compiled version of the `test-service`, is
11+
generated using the [`jam-pvm-build`](https://crates.io/crates/jam-pvm-build)
12+
tool.
13+
14+
Due to differences in dependencies and compiler versions, the resulting binary
15+
artifact frequently varies, even when generated from identical source code. As
16+
a result, you can just rely on the code blob embedded in the test vectors, which
17+
is available within the `accounts` map.
18+
19+
## Statistics
20+
21+
A subset of service activity statistics ($π_S$) updated by the STF subsystem used
22+
to process these test vectors.
23+
24+
In particular the `accumulate-count` (a.0), `accumulate-gas-used` (a.1),
25+
`on-transfers-count` (t.0) and `on-transfers-gas-used` (t.1).
26+
27+
## Tiny Vectors
28+
29+
- [no_available_reports-1](./tiny/no_available_reports-1.json)
30+
- No reports.
31+
- [process_one_immediate_report-1](./tiny/process_one_immediate_report-1.json)
32+
- Report with no dependencies.
33+
- [enqueue_and_unlock_simple-1](./tiny/enqueue_and_unlock_simple-1.json)
34+
- Report with unsatisfied dependency added to the ready-queue.
35+
- [enqueue_and_unlock_simple-2](./tiny/enqueue_and_unlock_simple-2.json)
36+
- Report with no dependencies that resolves previous dependency.
37+
- [enqueue_and_unlock_with_sr_lookup-1](./tiny/enqueue_and_unlock_with_sr_lookup-1.json)
38+
- Report with unsatisfied segment tree root dependency added to the ready-queue.
39+
- [enqueue_and_unlock_with_sr_lookup-2](./tiny/enqueue_and_unlock_with_sr_lookup-2.json)
40+
- Report with no dependencies that resolves previous dependency.
41+
- [enqueue_and_unlock_chain-1](./tiny/enqueue_and_unlock_chain-1.json)
42+
- Two reports with unsatisfied dependencies added to the ready-queue.
43+
- [enqueue_and_unlock_chain-2](./tiny/enqueue_and_unlock_chain-2.json)
44+
- Two additional reports with unsatisfied dependencies added to the ready-queue.
45+
- [enqueue_and_unlock_chain-3](./tiny/enqueue_and_unlock_chain-3.json)
46+
- Two additional reports. One with unsatisfied dependencies, thus added to the ready-queue.
47+
- One report is accumulated and resolves two previously enqueued reports.
48+
- [enqueue_and_unlock_chain-4](./tiny/enqueue_and_unlock_chain-4.json)
49+
- Report that resolves all remaining queued dependencies.
50+
- [enqueue_and_unlock_chain_wraps-1](./tiny/enqueue_and_unlock_chain_wraps-1.json)
51+
- Two reports with unsatisfied dependencies added to the ready-queue.
52+
- [enqueue_and_unlock_chain_wraps-2](./tiny/enqueue_and_unlock_chain_wraps-2.json)
53+
- Two additional reports, one with no dependencies and thus immediately accumulated.
54+
- The other is pushed to the ready-queue which fills up and wraps around
55+
(ready-queue is a ring buffer).
56+
- [enqueue_and_unlock_chain_wraps-3](./tiny/enqueue_and_unlock_chain_wraps-3.json)
57+
- Two additional reports with unsatisfied dependencies pushed to the ready-queue.
58+
- [enqueue_and_unlock_chain_wraps-4](./tiny/enqueue_and_unlock_chain_wraps-4.json)
59+
- Two additional reports, one with no dependencies and thus immediately accumulated.
60+
- Three old entries in the ready-queue are removed.
61+
- [enqueue_and_unlock_chain_wraps-5](./tiny/enqueue_and_unlock_chain_wraps-5.json)
62+
- Report with no dependencies resolves all previous enqueued reports.
63+
- [enqueue_self_referential-1](./tiny/enqueue_self_referential-1.json)
64+
- Report with direct dependency on itself.
65+
- This makes the report stale, but pushed to the ready-queue anyway.
66+
- [enqueue_self_referential-2](./tiny/enqueue_self_referential-2.json)
67+
- Two reports with indirect circular dependency.
68+
- This makes the reports stale, but pushed to the ready-queue anyway.
69+
- [enqueue_self_referential-3](./tiny/enqueue_self_referential-3.json)
70+
- Two reports. First depends on second, which depends on unseen report.
71+
- [enqueue_self_referential-4](./tiny/enqueue_self_referential-4.json)
72+
- New report creates a cycle with the previously queued reports.
73+
- This makes the reports stale, but pushed to the ready-queue anyway.
74+
- [accumulate_ready_queued_reports-1](./tiny/accumulate_ready_queued_reports-1.json)
75+
- There are some reports in the ready-queue ready to be accumulated.
76+
- Even though we don't supply any new available work report these are processed.
77+
- This condition may result because of gas exhausition during previous block execution.
78+
- [queues_are_shifted-1](./tiny/queues_are_shifted-1.json)
79+
- Check that ready-queue and accumulated-reports queues are shifted.
80+
- A new available report is supplied.
81+
- [queues_are_shifted-2](./tiny/queues_are_shifted-2.json)
82+
- Check that ready-queue and accumulated-reports queues are shifted.
83+
- No new report is supplied.
84+
- [ready_queue_editing-1](./tiny/ready_queue_editing-1.json)
85+
- Two reports with unsatisfied dependencies added to the ready-queue.
86+
- [ready_queue_editing-2](./tiny/ready_queue_editing-2.json)
87+
- Two reports, one with unsatisfied dependency added to the ready-queue.
88+
- One accumulated. Ready queue items dependencies are edited.
89+
- [ready_queue_editing-3](./tiny/ready_queue_editing-3.json)
90+
- One report unlocks reports in the ready-queue.
91+
92+
## Full Vectors
93+
94+
Currently, the same test cases as tiny vectors but at a larger scale.

‎accumulate/accumulate.asn‎

Lines changed: 80 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,80 @@
1+
-- Accumulate STF test vectors schema
2+
3+
AccumulateModule DEFINITIONS ::= BEGIN
4+
5+
IMPORTS
6+
TimeSlot, ServiceId, ServiceInfo, WorkReport, OpaqueHash, ByteSequence,
7+
Entropy, ReadyQueue, AccumulatedQueue, Privileges, AccumulateRoot, ServicesStatistics
8+
FROM JamTypes;
9+
10+
StorageMapEntry ::= SEQUENCE {
11+
-- Storage key (unhashed, as managed by the service code)
12+
key ByteSequence,
13+
-- Storage value
14+
value ByteSequence
15+
}
16+
17+
PreimagesMapEntry ::= SEQUENCE {
18+
-- Preimage blob full hash
19+
hash OpaqueHash,
20+
-- Preimage blob
21+
blob ByteSequence
22+
}
23+
24+
-- Service account information relevant for this STF.
25+
Account ::= SEQUENCE {
26+
-- [a_c, a_b, a_g, a_m, a_o, a_i] Service metadata.
27+
service ServiceInfo,
28+
-- [a_s] Service storage.
29+
storage SEQUENCE OF StorageMapEntry,
30+
-- [a_p] Preimages blobs.
31+
-- This is mostly provided to lookup code blob for accumulate procedure execution.
32+
-- It is not supposed to be altered by this STF (i.e. posterior matches prior).
33+
preimages SEQUENCE OF PreimagesMapEntry
34+
}
35+
36+
AccountsMapEntry ::= SEQUENCE {
37+
id ServiceId,
38+
data Account
39+
}
40+
41+
State ::= SEQUENCE {
42+
-- [τ] Most recent block's timeslot.
43+
slot TimeSlot,
44+
-- [n_0'] Posterior entropy accumulator.
45+
entropy Entropy,
46+
-- [ϑ] Work packages ready to be accumulated.
47+
ready-queue ReadyQueue,
48+
-- [ξ] Work packages recently accumulated.
49+
accumulated AccumulatedQueue,
50+
-- [χ] Privileged service indices.
51+
privileges Privileges,
52+
-- [π_S] Services statistics.
53+
-- Note: Only stats related to accumulate STF are updated, in particular:
54+
-- accumulate_count (a.0), accumulate_gas_used (a.1),
55+
-- on_transfers_count (t.0), on_transfers_gas_used (t.1)
56+
statistics ServicesStatistics,
57+
-- [δ] Relevant services account data. Refer to T(σ) in GP Appendix D.
58+
accounts SEQUENCE OF AccountsMapEntry
59+
}
60+
61+
Input ::= SEQUENCE {
62+
-- [H_t] Current time slot as found within the block header.
63+
slot TimeSlot,
64+
-- Newly available work reports (W).
65+
reports SEQUENCE OF WorkReport
66+
}
67+
68+
Output ::= CHOICE {
69+
ok AccumulateRoot,
70+
err NULL
71+
}
72+
73+
TestCase ::= SEQUENCE {
74+
input Input,
75+
pre-state State,
76+
output Output,
77+
post-state State
78+
}
79+
80+
END

‎accumulate/full/accumulate_ready_queued_reports-1.bin‎

77 KB
Binary file not shown.

0 commit comments

Comments
 (0)