Safrole (γ)

Bases: StateComponent

Source code in pyjamaz/state/components.py

class Safrole(StateComponent):
    component_id = 4

    def __init__(
        self,
        block_context: BlockContext,
        app_context: AppContext,
        ring_data: bytes
    ):
        super().__init__(block_context, app_context)
        self.ring_data = ring_data
        self.post_state_safrole = None

    @log_execution_time
    def create_ticket_body(self, ticket_data: TicketEnvelope, ring_context: RingContext, entropy: bytes) -> TicketBody:
        if ticket_data.attempt >= gp_const.TICKET_ENTRIES:
            raise StateTransitionError(SafroleErrorCode.bad_ticket_attempt)

        vrf_input_data = ticket_data.generate_vrf_input(entropy)

        aux_data = b''

        try:
            DEBUG and logging.debug(f'Validating ticket in STF with entropy {entropy.hex()}')
            ring_vrf_output = ring_context.ring_vrf_verify(vrf_input_data, aux_data, bytes(ticket_data.signature))

        except ValueError as e:
            raise StateTransitionError(SafroleErrorCode.bad_ticket_proof)

        return TicketBody(id=ring_vrf_output, attempt=ticket_data.attempt)

    @log_execution_time
    def state_transition(
            self,
            header: Header,
            extrinsic_tickets: List[TicketEnvelope],
            pre_state_timeslot: TimeslotState,
            pre_state_safrole: SafroleState,
            pre_state_validator_queue: ValidatorQueueState,
            post_state_entropy: EntropyState,
            post_state_validator_pool: ValidatorPoolState,
            post_state_disputes: DisputesState
    ) -> SafroleOutput:
        """
        GP-0.7.2-eq:6.13,6.15,6.16,6.24,6.34 (γ') | State transition function for the state's Safrole data.

        Parameters
        ----------
        header: Header
            GP-0.7.2-eq:4.7 (bold_H)
        pre_state_timeslot: TimeslotState
            GP-0.7.2-eq:4.7 (τ)
        extrinsic_tickets: List[TicketEnvelope]
            GP-0.7.2-eq:4.7 (bold_E_T)
        pre_state_safrole: SafroleState
            GP-0.7.2-eq:4.7 (γ)
        pre_state_validator_queue: ValidatorQueueState
            GP-0.7.2-eq:4.7 (ι)
        post_state_entropy: EntropyState
            GP-0.7.2-eq:4.7 (η')
        post_state_validator_pool: ValidatorPoolState
            GP-0.7.2-eq:4.7 (κ')
        post_state_disputes: DisputesState
            GP-0.7.2-eq:4.7 (ψ')
        Returns
        -------
        SafroleOutput
            Output containing: Posterior state of SafroleState (γ') and optional Outputmarks
        """

        if header.timeslot <= pre_state_timeslot.number:
            raise StateTransitionError(SafroleErrorCode.bad_slot)

        self.post_state_safrole = deepcopy(pre_state_safrole)

        # GP-0.7.2-eq:6.30
        if self.slot_phase_index(header.timeslot) < gp_const.TICKET_SUBMISSION_END_SLOT:
            # Min 0, max 16 tickets
            if len(extrinsic_tickets) > gp_const.MAXIMUM_EXTRINSIC_TICKETS:  # constant_K=16
                raise StateTransitionError(SafroleErrorCode.too_many_tickets)
        else:
            if len(extrinsic_tickets) > 0:
                # Don't accept tickets after TICKET_SUBMISSION_END_SLOT:
                raise StateTransitionError(SafroleErrorCode.unexpected_ticket)

        input_tickets = [None] * len(extrinsic_tickets)

        if len(extrinsic_tickets) > 0:

            # Check for duplicate ticket_data; GP-0.7.2-eq:6.32
            if list_has_duplicates(extrinsic_tickets):
                raise StateTransitionError(SafroleErrorCode.duplicate_ticket)

            ring_public_keys = [v.bandersnatch for v in self.post_state_safrole.validators]

            ring_context = RingContext(self.ring_data, ring_public_keys)

            if USE_THREAD_POOL_SAFROLE:

                DEBUG and logging.debug(f'Using ThreadPool max_workers={THREAD_POOL_MAX_WORKERS}')

                with ThreadPoolExecutor(max_workers=THREAD_POOL_MAX_WORKERS) as tp:
                    futs = {
                        tp.submit(
                            self.create_ticket_body,
                            ticket_data,
                            ring_context,
                            post_state_entropy.entropy[2]
                        ): idx
                        for idx, ticket_data in enumerate(extrinsic_tickets)
                    }

                    for fut in as_completed(futs):
                        ticket = fut.result()
                        idx = futs[fut]

                        # Check if ticket already exists
                        if ticket in self.post_state_safrole.ticket_accumulator:
                            # GP-0.7.2-eq:6.33
                            raise StateTransitionError(SafroleErrorCode.duplicate_ticket)
                        else:
                            input_tickets[idx] = ticket
            else:
                # Validate extrinsic
                for idx, ticket_data in enumerate(extrinsic_tickets):

                    ticket = self.create_ticket_body(ticket_data, ring_context, post_state_entropy.entropy[2])

                    # Check if ticket already exists
                    if ticket in self.post_state_safrole.ticket_accumulator:
                        # GP-0.7.2-eq:6.33
                        raise StateTransitionError(SafroleErrorCode.duplicate_ticket)
                    else:
                        input_tickets[idx] = ticket

            # Check if tickets are in order: GP-0.7.2-eq:6.32
            if not self.tickets_in_order(input_tickets):
                raise StateTransitionError(SafroleErrorCode.bad_ticket_order)


        # Create output markers if conditions are met
        epoch_mark = None
        tickets_mark = None

        if (not self.is_epoch_change(pre_state_timeslot.number, header.timeslot) and
                self.slot_phase_index(pre_state_timeslot.number) < gp_const.TICKET_SUBMISSION_END_SLOT <=
                self.slot_phase_index(header.timeslot)):
            # Ticket mark only when accumulator is saturated # GP-0.7.2-eq:6.28
            if len(self.post_state_safrole.ticket_accumulator) == gp_const.EPOCH_TIMESLOTS:
                # GP-0.7.2-eq:6.25
                tickets_mark = reorder_list_outside_in(deepcopy(self.post_state_safrole.ticket_accumulator))
                DEBUG and logging.debug(f"Tickets Mark generated")

        # TODO check conditions when epoch should be mark as changed
        if self.is_epoch_change(pre_state_timeslot.number, header.timeslot):
            # Epoch change

            # Update Validator keys for the following epoch. # GP-0.7.2-eq:6.13
            # Apply key_nullifier-function (Φ). This function substitutes offenders with null keys. GP-0.7.2-eq:6.14
            self.post_state_safrole.validators = self.check_offenders(
                validators=deepcopy(pre_state_validator_queue.validators),
                offenders=post_state_disputes.offenders
            )

            # Clear tickets mark
            tickets_mark = None

            # Create epoch mark
            epoch_mark = EpochMark(
                entropy=post_state_entropy.entropy[1],
                tickets_entropy=post_state_entropy.entropy[2],
                validators=[
                    EpochMarkValidatorKeys(
                        bandersnatch=validator.bandersnatch,
                        ed25519=validator.ed25519
                    ) for validator in self.post_state_safrole.validators
                ]
            )
            DEBUG and logging.debug(f"Epoch Mark generated")

            # Update Sealing-key series of the current epoch.
            if self.enact_fallback_method(pre_state_timeslot.number, header.timeslot):
                # Determine fallback keys according to # GP-0.7.2-eq:6.26
                # TODO refactor to separate function F(r, k)
                validators = []
                for n in range(gp_const.EPOCH_TIMESLOTS):
                    blake_hash = blake2b_256_hash(
                        post_state_entropy.entropy[2] + int.to_bytes(
                            n, length=4, byteorder='little'
                        )
                    )
                    validator_idx = int.from_bytes(
                        blake_hash[:4], byteorder='little'
                    ) % len(post_state_validator_pool.validators)
                    if SOLO_MODE:
                        validator_idx = 0
                    validators.append(post_state_validator_pool.validators[validator_idx].bandersnatch)

                self.post_state_safrole.slot_sealer_series = SlotSealerSeries(keys=validators)
                logging.info(f"🤷‍ New Slot Sealer Series with fallback keys")
                # TODO temp
                DEBUG and logging.debug(f"Used entropy: {post_state_entropy.entropy[2].hex()}")
                DEBUG and logging.debug(f"New Series: {self.post_state_safrole.slot_sealer_series.to_json()}")
            else:
                # When ticket accumulator is saturated and ticket mark is generated # GP-0.7.2-eq:6.24
                self.post_state_safrole.slot_sealer_series = SlotSealerSeries(
                    tickets=reorder_list_outside_in(deepcopy(self.post_state_safrole.ticket_accumulator))
                )
                DEBUG and logging.debug(f"New Slot Sealer Series with tickets")

            # Update ring commitment using O(); GP-0.7.2-eq:6.13
            ring_context = RingContext(self.ring_data, [v.bandersnatch for v in self.post_state_safrole.validators])
            self.post_state_safrole.ring_commitment = ring_context.commitment

        # Add tickets to ticket accumulator, sort and limit: GP-0.7.2-eq:6.34,6.35
        if self.is_epoch_change(pre_state_timeslot.number, header.timeslot):
            # Not checked by W3F test vectors
            self.post_state_safrole.ticket_accumulator = input_tickets
        else:
            self.post_state_safrole.ticket_accumulator = input_tickets + pre_state_safrole.ticket_accumulator

        self.post_state_safrole.ticket_accumulator = sorted(
            self.post_state_safrole.ticket_accumulator, key=lambda t: t.id
        )[:gp_const.EPOCH_TIMESLOTS]

        return SafroleOutput(
            post_state=self.post_state_safrole,
            epoch_mark=epoch_mark,
            tickets_mark=tickets_mark
        )

    def enact_fallback_method(self, pre_time_slot: int, post_time_slot: int) -> bool:
        return (
            # Not a full tickets accumulator
            len(self.post_state_safrole.ticket_accumulator) != gp_const.EPOCH_TIMESLOTS
            # No Ticket marker generated
            or self.slot_phase_index(pre_time_slot) < gp_const.TICKET_SUBMISSION_END_SLOT
            # Whole epoch is skipped
            or self.epoch_number(post_time_slot) - self.epoch_number(pre_time_slot) > 1
        )

    @staticmethod
    def tickets_in_order(tickets: List[TicketBody]) -> bool:
        ticket_ids = [t.id for t in tickets]
        return all(x <= y for x, y in zip(ticket_ids, ticket_ids[1:]))

    def retrieve_state(self) -> SafroleState:
        value = self.retrieve()
        return SafroleState.from_jam_bytes(JamBytes(value))

    def check_offenders(self, validators: List[ValidatorData], offenders: List[bytes]):
        """
        GP-0.7.2-eq:6.14
        """
        checked_validators = []
        for v in validators:
            if v.ed25519 in offenders:
                v.bandersnatch = bytes(32)
                v.ed25519 = bytes(32)
            checked_validators.append(v)

        return checked_validators

state_transition(header: Header, extrinsic_tickets: List[TicketEnvelope], pre_state_timeslot: TimeslotState, pre_state_safrole: SafroleState, pre_state_validator_queue: ValidatorQueueState, post_state_entropy: EntropyState, post_state_validator_pool: ValidatorPoolState, post_state_disputes: DisputesState) -> SafroleOutput

GP-0.7.2-eq:6.13,6.15,6.16,6.24,6.34 (γ') | State transition function for the state's Safrole data.

Parameters:

Name	Type	Description	Default
header	Header	GP-0.7.2-eq:4.7 (bold_H)	required
pre_state_timeslot	TimeslotState	GP-0.7.2-eq:4.7 (τ)	required
extrinsic_tickets	List[TicketEnvelope]	GP-0.7.2-eq:4.7 (bold_E_T)	required
pre_state_safrole	SafroleState	GP-0.7.2-eq:4.7 (γ)	required
pre_state_validator_queue	ValidatorQueueState	GP-0.7.2-eq:4.7 (ι)	required
post_state_entropy	EntropyState	GP-0.7.2-eq:4.7 (η')	required
post_state_validator_pool	ValidatorPoolState	GP-0.7.2-eq:4.7 (κ')	required
post_state_disputes	DisputesState	GP-0.7.2-eq:4.7 (ψ')	required

Returns:

Type	Description
SafroleOutput	Output containing: Posterior state of SafroleState (γ') and optional Outputmarks

Source code in pyjamaz/state/components.py

@log_execution_time
def state_transition(
        self,
        header: Header,
        extrinsic_tickets: List[TicketEnvelope],
        pre_state_timeslot: TimeslotState,
        pre_state_safrole: SafroleState,
        pre_state_validator_queue: ValidatorQueueState,
        post_state_entropy: EntropyState,
        post_state_validator_pool: ValidatorPoolState,
        post_state_disputes: DisputesState
) -> SafroleOutput:
    """
    GP-0.7.2-eq:6.13,6.15,6.16,6.24,6.34 (γ') | State transition function for the state's Safrole data.

    Parameters
    ----------
    header: Header
        GP-0.7.2-eq:4.7 (bold_H)
    pre_state_timeslot: TimeslotState
        GP-0.7.2-eq:4.7 (τ)
    extrinsic_tickets: List[TicketEnvelope]
        GP-0.7.2-eq:4.7 (bold_E_T)
    pre_state_safrole: SafroleState
        GP-0.7.2-eq:4.7 (γ)
    pre_state_validator_queue: ValidatorQueueState
        GP-0.7.2-eq:4.7 (ι)
    post_state_entropy: EntropyState
        GP-0.7.2-eq:4.7 (η')
    post_state_validator_pool: ValidatorPoolState
        GP-0.7.2-eq:4.7 (κ')
    post_state_disputes: DisputesState
        GP-0.7.2-eq:4.7 (ψ')
    Returns
    -------
    SafroleOutput
        Output containing: Posterior state of SafroleState (γ') and optional Outputmarks
    """

    if header.timeslot <= pre_state_timeslot.number:
        raise StateTransitionError(SafroleErrorCode.bad_slot)

    self.post_state_safrole = deepcopy(pre_state_safrole)

    # GP-0.7.2-eq:6.30
    if self.slot_phase_index(header.timeslot) < gp_const.TICKET_SUBMISSION_END_SLOT:
        # Min 0, max 16 tickets
        if len(extrinsic_tickets) > gp_const.MAXIMUM_EXTRINSIC_TICKETS:  # constant_K=16
            raise StateTransitionError(SafroleErrorCode.too_many_tickets)
    else:
        if len(extrinsic_tickets) > 0:
            # Don't accept tickets after TICKET_SUBMISSION_END_SLOT:
            raise StateTransitionError(SafroleErrorCode.unexpected_ticket)

    input_tickets = [None] * len(extrinsic_tickets)

    if len(extrinsic_tickets) > 0:

        # Check for duplicate ticket_data; GP-0.7.2-eq:6.32
        if list_has_duplicates(extrinsic_tickets):
            raise StateTransitionError(SafroleErrorCode.duplicate_ticket)

        ring_public_keys = [v.bandersnatch for v in self.post_state_safrole.validators]

        ring_context = RingContext(self.ring_data, ring_public_keys)

        if USE_THREAD_POOL_SAFROLE:

            DEBUG and logging.debug(f'Using ThreadPool max_workers={THREAD_POOL_MAX_WORKERS}')

            with ThreadPoolExecutor(max_workers=THREAD_POOL_MAX_WORKERS) as tp:
                futs = {
                    tp.submit(
                        self.create_ticket_body,
                        ticket_data,
                        ring_context,
                        post_state_entropy.entropy[2]
                    ): idx
                    for idx, ticket_data in enumerate(extrinsic_tickets)
                }

                for fut in as_completed(futs):
                    ticket = fut.result()
                    idx = futs[fut]

                    # Check if ticket already exists
                    if ticket in self.post_state_safrole.ticket_accumulator:
                        # GP-0.7.2-eq:6.33
                        raise StateTransitionError(SafroleErrorCode.duplicate_ticket)
                    else:
                        input_tickets[idx] = ticket
        else:
            # Validate extrinsic
            for idx, ticket_data in enumerate(extrinsic_tickets):

                ticket = self.create_ticket_body(ticket_data, ring_context, post_state_entropy.entropy[2])

                # Check if ticket already exists
                if ticket in self.post_state_safrole.ticket_accumulator:
                    # GP-0.7.2-eq:6.33
                    raise StateTransitionError(SafroleErrorCode.duplicate_ticket)
                else:
                    input_tickets[idx] = ticket

        # Check if tickets are in order: GP-0.7.2-eq:6.32
        if not self.tickets_in_order(input_tickets):
            raise StateTransitionError(SafroleErrorCode.bad_ticket_order)


    # Create output markers if conditions are met
    epoch_mark = None
    tickets_mark = None

    if (not self.is_epoch_change(pre_state_timeslot.number, header.timeslot) and
            self.slot_phase_index(pre_state_timeslot.number) < gp_const.TICKET_SUBMISSION_END_SLOT <=
            self.slot_phase_index(header.timeslot)):
        # Ticket mark only when accumulator is saturated # GP-0.7.2-eq:6.28
        if len(self.post_state_safrole.ticket_accumulator) == gp_const.EPOCH_TIMESLOTS:
            # GP-0.7.2-eq:6.25
            tickets_mark = reorder_list_outside_in(deepcopy(self.post_state_safrole.ticket_accumulator))
            DEBUG and logging.debug(f"Tickets Mark generated")

    # TODO check conditions when epoch should be mark as changed
    if self.is_epoch_change(pre_state_timeslot.number, header.timeslot):
        # Epoch change

        # Update Validator keys for the following epoch. # GP-0.7.2-eq:6.13
        # Apply key_nullifier-function (Φ). This function substitutes offenders with null keys. GP-0.7.2-eq:6.14
        self.post_state_safrole.validators = self.check_offenders(
            validators=deepcopy(pre_state_validator_queue.validators),
            offenders=post_state_disputes.offenders
        )

        # Clear tickets mark
        tickets_mark = None

        # Create epoch mark
        epoch_mark = EpochMark(
            entropy=post_state_entropy.entropy[1],
            tickets_entropy=post_state_entropy.entropy[2],
            validators=[
                EpochMarkValidatorKeys(
                    bandersnatch=validator.bandersnatch,
                    ed25519=validator.ed25519
                ) for validator in self.post_state_safrole.validators
            ]
        )
        DEBUG and logging.debug(f"Epoch Mark generated")

        # Update Sealing-key series of the current epoch.
        if self.enact_fallback_method(pre_state_timeslot.number, header.timeslot):
            # Determine fallback keys according to # GP-0.7.2-eq:6.26
            # TODO refactor to separate function F(r, k)
            validators = []
            for n in range(gp_const.EPOCH_TIMESLOTS):
                blake_hash = blake2b_256_hash(
                    post_state_entropy.entropy[2] + int.to_bytes(
                        n, length=4, byteorder='little'
                    )
                )
                validator_idx = int.from_bytes(
                    blake_hash[:4], byteorder='little'
                ) % len(post_state_validator_pool.validators)
                if SOLO_MODE:
                    validator_idx = 0
                validators.append(post_state_validator_pool.validators[validator_idx].bandersnatch)

            self.post_state_safrole.slot_sealer_series = SlotSealerSeries(keys=validators)
            logging.info(f"🤷‍ New Slot Sealer Series with fallback keys")
            # TODO temp
            DEBUG and logging.debug(f"Used entropy: {post_state_entropy.entropy[2].hex()}")
            DEBUG and logging.debug(f"New Series: {self.post_state_safrole.slot_sealer_series.to_json()}")
        else:
            # When ticket accumulator is saturated and ticket mark is generated # GP-0.7.2-eq:6.24
            self.post_state_safrole.slot_sealer_series = SlotSealerSeries(
                tickets=reorder_list_outside_in(deepcopy(self.post_state_safrole.ticket_accumulator))
            )
            DEBUG and logging.debug(f"New Slot Sealer Series with tickets")

        # Update ring commitment using O(); GP-0.7.2-eq:6.13
        ring_context = RingContext(self.ring_data, [v.bandersnatch for v in self.post_state_safrole.validators])
        self.post_state_safrole.ring_commitment = ring_context.commitment

    # Add tickets to ticket accumulator, sort and limit: GP-0.7.2-eq:6.34,6.35
    if self.is_epoch_change(pre_state_timeslot.number, header.timeslot):
        # Not checked by W3F test vectors
        self.post_state_safrole.ticket_accumulator = input_tickets
    else:
        self.post_state_safrole.ticket_accumulator = input_tickets + pre_state_safrole.ticket_accumulator

    self.post_state_safrole.ticket_accumulator = sorted(
        self.post_state_safrole.ticket_accumulator, key=lambda t: t.id
    )[:gp_const.EPOCH_TIMESLOTS]

    return SafroleOutput(
        post_state=self.post_state_safrole,
        epoch_mark=epoch_mark,
        tickets_mark=tickets_mark
    )

check_offenders(validators: List[ValidatorData], offenders: List[bytes])

GP-0.7.2-eq:6.14

Source code in pyjamaz/state/components.py

def check_offenders(self, validators: List[ValidatorData], offenders: List[bytes]):
    """
    GP-0.7.2-eq:6.14
    """
    checked_validators = []
    for v in validators:
        if v.ed25519 in offenders:
            v.bandersnatch = bytes(32)
            v.ed25519 = bytes(32)
        checked_validators.append(v)

    return checked_validators