diff --git a/api/grpc/churner/churner.pb.go b/api/grpc/churner/churner.pb.go index 94129cccfa..d5b3517038 100644 --- a/api/grpc/churner/churner.pb.go +++ b/api/grpc/churner/churner.pb.go @@ -42,8 +42,8 @@ type ChurnRequest struct { // - If any of the quorum fails to register, this entire request will fail. // - Regardless of whether the specified quorums are full or not, the Churner // will return parameters for all quorums specified here. The smart contract will - // determine whether to churn out existing operators based on whether the quorums - // have available space. + // determine whether it needs to churn out existing operators based on whether + // the quorums have available space. // // The IDs must be in range [0, 254]. QuorumIds []uint32 `protobuf:"varint,6,rep,packed,name=quorum_ids,json=quorumIds,proto3" json:"quorum_ids,omitempty"` @@ -131,6 +131,16 @@ type ChurnReply struct { // The signature signed by the Churner. SignatureWithSaltAndExpiry *SignatureWithSaltAndExpiry `protobuf:"bytes,1,opt,name=signature_with_salt_and_expiry,json=signatureWithSaltAndExpiry,proto3" json:"signature_with_salt_and_expiry,omitempty"` // A list of existing operators that get churned out. + // This list will contain the target operators to be churned out for all quorums specified + // in the ChurnRequest even if some quorums may not have any churned out operators. + // It is smart contract's responsibility to determine whether it needs to churn out + // these target operators based on whether the quorums have available space. + // + // For example, if the ChurnRequest specifies quorums 0 and 1 where quorum 0 is full + // and quorum 1 has available space, the ChurnReply will contain the operators to be + // churned out for both quorums 0 and 1 (operators with lowest stake). However, + // smart contract should only churn out the operators for quorum 0 because quorum 1 + // has available space without having any operators churned. // Note: it's possible an operator gets churned out just for one or more quorums // (rather than entirely churned out for all quorums). OperatorsToChurn []*OperatorToChurn `protobuf:"bytes,2,rep,name=operators_to_churn,json=operatorsToChurn,proto3" json:"operators_to_churn,omitempty"` diff --git a/api/proto/churner/churner.proto b/api/proto/churner/churner.proto index 6b69ab509c..27e7b95917 100644 --- a/api/proto/churner/churner.proto +++ b/api/proto/churner/churner.proto @@ -35,8 +35,8 @@ message ChurnRequest { // - If any of the quorum fails to register, this entire request will fail. // - Regardless of whether the specified quorums are full or not, the Churner // will return parameters for all quorums specified here. The smart contract will - // determine whether to churn out existing operators based on whether the quorums - // have available space. + // determine whether it needs to churn out existing operators based on whether + // the quorums have available space. // The IDs must be in range [0, 254]. repeated uint32 quorum_ids = 6; } @@ -45,6 +45,16 @@ message ChurnReply { // The signature signed by the Churner. SignatureWithSaltAndExpiry signature_with_salt_and_expiry = 1; // A list of existing operators that get churned out. + // This list will contain the target operators to be churned out for all quorums specified + // in the ChurnRequest even if some quorums may not have any churned out operators. + // It is smart contract's responsibility to determine whether it needs to churn out + // these target operators based on whether the quorums have available space. + // + // For example, if the ChurnRequest specifies quorums 0 and 1 where quorum 0 is full + // and quorum 1 has available space, the ChurnReply will contain the operators to be + // churned out for both quorums 0 and 1 (operators with lowest stake). However, + // smart contract should only churn out the operators for quorum 0 because quorum 1 + // has available space without having any operators churned. // Note: it's possible an operator gets churned out just for one or more quorums // (rather than entirely churned out for all quorums). repeated OperatorToChurn operators_to_churn = 2;