add comments

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;