diff --git a/README.md b/README.md index dd8bbf7..f934e48 100644 --- a/README.md +++ b/README.md @@ -927,7 +927,31 @@ recovery data to this participant. def participant_blame(blame_state: ParticipantBlameState, cblame: CoordinatorBlameMsg) -> NoReturn ``` -Perform a participant's blame step of a ChillDKG session. TODO +Perform a blame investigation (TODO) for a participant in a ChillDKG session. + +This function can optionally be called when `participant_step2` raises +`UnknownFaultyParticipantOrCoordinatorError`. It narrows down the suspected +faulty parties by analyzing the blame message provided by the coordinator. + +This function does not return normally. Instead, it raises one of two +exceptions. + +*Arguments*: + +- `blame_state` - The participant's blame state as contained in + `UnknownFaultyParticipantOrCoordinatorError` raised by + `participant_step2`. +- `cblame` - The coordinator blame message for this participant as output by + `coordinator_blame`. + + +*Raises*: + +- `FaultyParticipantOrCoordinatorError` - If another known participant or the + coordinator is faulty. See the documentation of the exception for + further details. +- `FaultyCoordinatorError` - If the coordinator is faulty. See the + documentation of the exception for further details. #### coordinator\_step1 @@ -1010,7 +1034,17 @@ other participants via a communication channel beside the coordinator. def coordinator_blame(pmsgs: List[ParticipantMsg1]) -> List[CoordinatorBlameMsg] ``` -Perform the coordinator's blame step of a ChillDKG session. TODO +Generate blame messages for participants to allow blame investigation. + +*Arguments*: + +- `pmsgs` - List of first messages received from the participants. + + +*Returns*: + +- `List[CoordinatorBlameMsg]` - A list of blame messages, each intended for a + single participant. #### recover diff --git a/python/chilldkg_ref/chilldkg.py b/python/chilldkg_ref/chilldkg.py index 1eaf834..d891946 100644 --- a/python/chilldkg_ref/chilldkg.py +++ b/python/chilldkg_ref/chilldkg.py @@ -604,7 +604,29 @@ def participant_blame( blame_state: ParticipantBlameState, cblame: CoordinatorBlameMsg, ) -> NoReturn: - """Perform a participant's blame step of a ChillDKG session. TODO""" + """Perform a blame investigation (TODO) for a participant in a ChillDKG session. + + This function can optionally be called when `participant_step2` raises + `UnknownFaultyParticipantOrCoordinatorError`. It narrows down the suspected + faulty parties by analyzing the blame message provided by the coordinator. + + This function does not return normally. Instead, it raises one of two + exceptions. + + Arguments: + blame_state: The participant's blame state as contained in + `UnknownFaultyParticipantOrCoordinatorError` raised by + `participant_step2`. + cblame: The coordinator blame message for this participant as output by + `coordinator_blame`. + + Raises: + FaultyParticipantOrCoordinatorError: If another known participant or the + coordinator is faulty. See the documentation of the exception for + further details. + FaultyCoordinatorError: If the coordinator is faulty. See the + documentation of the exception for further details. + """ encpedpop.participant_blame( blame_state=blame_state.enc_blame_state, cblame=cblame.enc_cblame, @@ -709,7 +731,15 @@ def coordinator_finalize( def coordinator_blame(pmsgs: List[ParticipantMsg1]) -> List[CoordinatorBlameMsg]: - """Perform the coordinator's blame step of a ChillDKG session. TODO""" + """Generate blame messages for participants to allow blame investigation. + + Arguments: + pmsgs: List of first messages received from the participants. + + Returns: + List[CoordinatorBlameMsg]: A list of blame messages, each intended for a + single participant. + """ enc_cblames = encpedpop.coordinator_blame([pmsg.enc_pmsg for pmsg in pmsgs]) return [CoordinatorBlameMsg(enc_cblame) for enc_cblame in enc_cblames]