README.md

Safrole Test Vectors

We offer two types of test vectors:

• Tiny: These are designed for quick adjustments and prototyping, with reduced validators count (6) and epoch duration (12). Tickets per validator max attempts is 3 in order to be able to fill the full epoch when only the supermajority of validators is honest (5).
• Full: These vectors use production validators count (1023) and epoch duration (600). Tickets per validator max attempts is aligned to the GP (2).

Both JSON and SCALE formats conform to the JAM ASN.1 schema and this subsystem STF specific schema.

⚠️ WARNING ⚠️

The ring-proof backend used by ark-ec-vrfs remains subject to modifications.

If you encounter any issues when processing these vectors, particularly regarding the verification of Bandersnatch tickets, please ensure that you are using the same ark-ec-vrfs revision employed for the production of these vectors.

Used ark-ec-vrfs revision: d90e180

zk-SNARK SRS

Ring proofs were constructed using a SNARK built using the the Zcash SRS paramaters. (powers of tau ceremony details).

For construction and usage refer to Bandersnatch vrfs spec example.

NOTE: for "tiny" initialize the RingContext with ring_size = 6; while for full ring size = 1023.

Safrole is not Sassafras

You can use the Sassafras RFC as a guideline provided it does not conflict with the protocol described by the Graypaper If case of any discrepancy, the Graypaper must be considered the authoritative source for the JAM protocol.

Here are some key differences:

• Safrole does not use a threshold to determine if a ticket score should be considered. A ticket is persisted in the state if the ticket accumulator is not full or if the score is lower than the highest score currently in the accumulator (which is removed after the new ticket is inserted).
• Safrole requires the entire ticket accumulator to be filled before it can be used. If not enough tickets are received, a fallback mechanism is enacted. In contrast, Sassafras can operate with an epoch that is only partially filled with tickets.
• In Safrole, the ticket envelope contains no additional application-specific data, it includes only the "attempt" and the "ring proof".

Most of these differences aim to provide a clear and concise protocol specification.

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

• enact_epoch_change_with_no_tickets-1 🟢

  • Progress by one slot.
  • Randomness accumulator is updated.

• enact_epoch_change_with_no_tickets-2 🔴

  • Progress from slot X to slot X.
  • Timeslot must be strictly monotonic.

• enact_epoch_change_with_no_tickets-3 🟢

  • Progress from a slot at the begining of the epoch to a slot in the epoch's tail.
  • Tickets mark is not generated (no enough tickets).

• enact_epoch_change_with_no_tickets-4 🟢

  • Progress from epoch's tail to next epoch.
  • Authorities and entropies are rotated. Epoch mark is generated.

• skip_epochs-1 🟢

  • Progress skipping epochs with a full tickets accumulator.
  • Tickets mark is not generated. Accumulated tickets discarded. Fallback method enacted.

• skip_epoch_tail-1 🟢

  • Progress to next epoch by skipping epochs tail with a full tickets accumulator.
  • Tickets mark has no chance to be generated. Accumulated tickets discarded. Fallback method enacted.

• publish_tickets_no_mark-1 🔴

  • Submit an extrinsic with a bad ticket attempt number.

• publish_tickets_no_mark-2 🟢

  • Submit good tickets extrinsic from some authorities.

• publish_tickets_no_mark-3 🔴

  • Submit one ticket already recorded in the state.

• publish_tickets_no_mark-4 🔴

  • Submit tickets in bad order.

• publish_tickets_no_mark-5 🔴

  • Submit tickets with bad ring proof.

• publish_tickets_no_mark-6 🟢

  • Submit some tickets.

• publish_tickets_no_mark-7 🔴

  • Submit tickets when epoch's lottery is over.

• publish_tickets_no_mark-8 🟢

  • Progress into epoch tail, closing the epoch's lottery.
  • No enough tickets, thus no tickets mark is generated.

• publish_tickets_no_mark-9 🟢

  • Progress into next epoch with no enough tickets.
  • Accumulated tickets are discarded. Epoch mark generated. Fallback method enacted.

• publish_tickets_with_mark-1 🟢

  • Publish some tickets with an almost full tickets accumulator.
  • Tickets accumulator is not full yet. No ticket is dropped from accumulator.

• publish_tickets_with_mark-2 🟢

  • Publish some tickets filling the accumulator.
  • Two old tickets are removed from the accumulator.

• publish_tickets_with_mark-3 🟢

  • Publish some tickets with a full accumulator.
  • Some old ticket are removed to make space for new ones.

• publish_tickets_with_mark-4 🟢

  • With a full accumulator, conclude the lottery.
  • Tickets mark is generated.

• publish_tickets_with_mark-5 🟢

  • With a published tickets mark, progress into next epoch.
  • Epoch mark is generated. Tickets are enacted.

• enact-epoch-change-with-padding-1 🟢

  • On epoch change we recompute the ring commitment.
  • One of the keys to be used is invalidated (zeroed out) because it belongs to the (posterior) offenders list.
  • One of the keys is just invalid (i.e. it can't be decoded into a valid Bandersnatch point).
  • Both the invalid keys are replaced with the padding point during ring commitment computation.

Full Vectors

Currently, the same test cases as tiny vectors but at a larger scale.