From 5d4dc0f83d8ea4b746746ddd267e4549a4fd648c Mon Sep 17 00:00:00 2001 From: Jonas Nick Date: Tue, 17 Dec 2024 21:10:29 +0000 Subject: [PATCH] chilldkg: add API docs for blaming functions --- README.md | 46 ++++++++++++++++++++++++++++++--- python/chilldkg_ref/chilldkg.py | 39 ++++++++++++++++++++++++++-- python/chilldkg_ref/util.py | 2 +- 3 files changed, 81 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index 4f1319e..67c0558 100644 --- a/README.md +++ b/README.md @@ -990,7 +990,30 @@ recovery data to this participant. def participant_investigate(error: UnknownFaultyParticipantOrCoordinatorError, cinv: CoordinatorInvestigationMsg) -> NoReturn ``` -Perform a participant's blame step of a ChillDKG session. TODO +Investigate who is to blame for a failed 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*: + +- `error` - `UnknownFaultyParticipantOrCoordinatorError` raised by + `participant_step2`. +- `cinv` - Coordinator investigation 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 @@ -1074,7 +1097,24 @@ other participants via a communication channel beside the coordinator. def coordinator_investigate(pmsgs: List[ParticipantMsg1]) -> List[CoordinatorInvestigationMsg] ``` -Perform the coordinator's blame step of a ChillDKG session. TODO +Generate investigation messages for a ChillDKG session. + +The investigation messages will allow the participants to investigate who is +to blame for a failed ChillDKG session (see `participant_investigate`). + +Each message is intended for a single participant but can be safely +broadcast to all participants because the messages contain no confidential +information. + +*Arguments*: + +- `pmsgs` - List of first messages received from the participants. + + +*Returns*: + +- `List[CoordinatorInvestigationMsg]` - A list of blame messages, each + intended for a single participant. #### recover @@ -1209,7 +1249,7 @@ information to determine which participant should be suspected. To determine a suspected participant, the raising participant may choose to run the optional investigation procedure of the protocol, which requires -obtaining an investigation message by the coordinator. See the +obtaining an investigation message from the coordinator. See the `participant_investigate` function for details. This is only raised for specific faulty behavior by another participant diff --git a/python/chilldkg_ref/chilldkg.py b/python/chilldkg_ref/chilldkg.py index ac8520d..714e50d 100644 --- a/python/chilldkg_ref/chilldkg.py +++ b/python/chilldkg_ref/chilldkg.py @@ -593,8 +593,28 @@ def participant_investigate( error: UnknownFaultyParticipantOrCoordinatorError, cinv: CoordinatorInvestigationMsg, ) -> NoReturn: - """Perform a participant's blame step of a ChillDKG session. TODO""" + """Investigate who is to blame for a failed 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: + error: `UnknownFaultyParticipantOrCoordinatorError` raised by + `participant_step2`. + cinv: Coordinator investigation 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. + """ assert isinstance(error.inv_data, encpedpop.ParticipantInvestigationData) encpedpop.participant_investigate( error=error, @@ -703,7 +723,22 @@ def coordinator_finalize( def coordinator_investigate( pmsgs: List[ParticipantMsg1], ) -> List[CoordinatorInvestigationMsg]: - """Perform the coordinator's blame step of a ChillDKG session. TODO""" + """Generate investigation messages for a ChillDKG session. + + The investigation messages will allow the participants to investigate who is + to blame for a failed ChillDKG session (see `participant_investigate`). + + Each message is intended for a single participant but can be safely + broadcast to all participants because the messages contain no confidential + information. + + Arguments: + pmsgs: List of first messages received from the participants. + + Returns: + List[CoordinatorInvestigationMsg]: A list of blame messages, each + intended for a single participant. + """ enc_cinvs = encpedpop.coordinator_investigate([pmsg.enc_pmsg for pmsg in pmsgs]) return [CoordinatorInvestigationMsg(enc_cinv) for enc_cinv in enc_cinvs] diff --git a/python/chilldkg_ref/util.py b/python/chilldkg_ref/util.py index 02e9404..fe313f6 100644 --- a/python/chilldkg_ref/util.py +++ b/python/chilldkg_ref/util.py @@ -87,7 +87,7 @@ class UnknownFaultyParticipantOrCoordinatorError(ProtocolError): To determine a suspected participant, the raising participant may choose to run the optional investigation procedure of the protocol, which requires - obtaining an investigation message by the coordinator. See the + obtaining an investigation message from the coordinator. See the `participant_investigate` function for details. This is only raised for specific faulty behavior by another participant