Protobuf comments and minor changes

This change-set introduces comments to each of the protobuf for the next fabric
architecture (v1).

Change-Id: I36c556fc9feedf5819742eeb0556f786198b2ded
Signed-off-by: Alessandro Sorniotti <ale.linux@sopit.net>

protos/next/chaincode_proposal.proto

@@ -18,27 +18,116 @@ syntax = "proto3";
 
 package protos;
 
-message ChaincodeTransactionHeaderExtension {
+/*
+The flow to get a CHAINCODE transaction approved goes as follows:
+
+1. client sends proposal to endorser
+====================================
+
+The proposal is basically a request to do something on a chaincode, that will
+result on some action - some change in the state of a chaincode and/or some
+data to be committed to the ledger; a proposal in general contains a header
+(with some metadata describing it, such as the type, the identity of the
+invoker, the time, the ID of the chain, a cryptographic nonce..) and a payload
+(the chaincode ID, invocation arguments..). Optionally, it may contain actions
+that the endorser may be asked to endorse, to emulate a submitting peer. A
+chaincode proposal contains the following messages:
+
+SignedProposal
+|\_ Signature                                    (signature on the Proposal message by the creator specified in the header)
+ \_ Proposal
+    |\_ Header                                   (the header for this proposal)
+    |\_ ChaincodeProposalPayload                 (the payload for this proposal)
+     \_ ChaincodeAction                          (the actions for this proposal - optional for a proposal)
+
+2. endorser sends proposal response back to client
+==================================================
+
+The proposal response contains an endorser's response to a client's proposal. A
+proposal response contains a success/error code, a response payload and a
+signature (also referred to as endorsement) over the response payload. The
+response payload contains a hash of the proposal (to securely link this
+response to the corresponding proposal), a description of the action resulting
+from the proposal and the endorser's signature over its payload. Formally, a
+chaincode proposal response contains the following messages:
+
+ProposalResponse
+|\_ Endorsement                                  (the endorser's signature over the whole response payload)
+ \_ ProposalResponsePayload
+     \_ ChaincodeAction                          (the actions for this proposal)
+
+3. client assembles endorsements into a transaction
+===================================================
 
+A transaction message assembles one or more proposals and corresponding
+responses into a message to be sent to orderers. After ordering, (batches of)
+transactions are delivered to committing peers for validation and final
+delivery into the ledger. A transaction contains one or more actions. Each of
+them contains a header (same as that of the proposal that requested it), a
+proposal payload (same as that of the proposal that requested it), a
+description of the resulting action and signatures from each of the endorsers
+that endorsed the action.
+
+SignedTransaction
+|\_ Signature                                    (signature on the Transaction message by the creator specified in the header)
+ \_ Transaction
+     \_ TransactionAction (1...n)
+        |\_ Header (1)                           (the header of the proposal that requested this action)
+         \_ ChaincodeActionPayload (1)
+            |\_ ChaincodeProposalPayload (1)     (payload of the proposal that requested this action)
+             \_ ChaincodeEndorsedAction (1)
+                |\_ Endorsement (1...n)          (endorsers' signatures over the whole response payload)
+                 \_ ProposalResponsePayload
+                     \_ ChaincodeAction          (the actions for this proposal)
+*/
+
+// ChaincodeHeaderExtension is the Header's extentions message to be used when
+// the Header's type is CHAINCODE.  This extensions is used to specify which
+// chaincode to invoke and what should appear on the ledger.
+message ChaincodeHeaderExtension {
+
+	// The PayloadVisibility field controls to what extent the Proposal's payload
+	// (recall that for the type CHAINCODE, it is ChaincodeProposalPayload
+	// message) field will be visible in the final transaction and in the ledger.
+	// Ideally, it would be configurable, supporting at least 3 main “visibility
+	// modes”:
+	// 1. all bytes of the payload are visible;
+	// 2. only a hash of the payload is visible;
+	// 3. nothing is visible.
+	// Notice that the visibility function may be potentially part of the ESCC.
+	// In that case it overrides PayloadVisibility field.  Finally notice that
+	// this field impacts the content of ProposalResponsePayload.proposalHash.
 	bytes payloadVisibility = 1;
 
+	// The ID of the chaincode to target.
 	bytes chaincodeID = 2;
 }
 
+// ChaincodeProposalPayload is the Proposal's payload message to be used when
+// the Header's type is CHAINCODE.  It contains the arguments for this
+// invocation.
 message ChaincodeProposalPayload {
-	ChaincodeProposalInputs inputs  = 1;
-	ChaincodeProposalSimulation simulation = 2;
-}
 
-message ChaincodeProposalInputs {
+	// Input contains the arguments for this invocation. If this invocation
+	// deploys a new chaincode, ESCC/VSCC are part of this field.
 	bytes Input  = 1;
 
+	// Transient contains data (e.g. cryptographic material) that might be used
+	// to implement some form of application-level confidentiality. The contents
+	// of this field are supposed to always be omitted from the transaction and
+	// excluded from the ledger.
 	bytes Transient = 2;
 }
 
-message ChaincodeProposalSimulation {
-	bytes simulationResults = 1;
+// ChaincodeAction contains the actions the events generated by the execution
+// of the chaincode.
+message ChaincodeAction {
+
+	// This field contains the read set and the write set produced by the
+	// chaincode executing this invocation.
+	bytes results = 1;
 
+	// This field contains the events generated by the chaincode executing this
+	// invocation.
 	bytes events = 2;
 }
-

protos/next/chaincode_transaction.proto

@@ -20,23 +20,36 @@ package protos;
 
 import "fabric_proposal_response.proto";
 
-message ChaincodeActionsPayload {
-
-	// ChaincodeProposalPayload is present in the transaction
-	// depending on the payloadVisibility field in the
-	// ChaincodeTransactionHeaderExtension.
-	// (it could be there in its entirety, it could be hashed or it
-	// could be totally absent)
+// ChaincodeActionPayload is the message to be used for the TransactionAction's
+// payload when the Header's type is set to CHAINCODE.  It carries the
+// chaincodeProposalPayload and an endorsed action to apply to the ledger.
+message ChaincodeActionPayload {
+
+	// This field contains the bytes of the ChaincodeProposalPayload message from
+	// the original invocation (essentially the arguments) after the application
+	// of the visibility function. The main visibility modes are "full" (the
+	// entire ChaincodeProposalPayload message is included here), "hash" (only
+	// the hash of the ChaincodeProposalPayload message is included) or
+	// "nothing".  This field will be used to check the consistency of
+	// ProposalResponsePayload.proposalHash.  For the CHAINCODE type,
+	// ProposalResponsePayload.proposalHash is supposed to be H(ProposalHeader ||
+	// f(ChaincodeProposalPayload)) where f is the visibility function.
 	bytes chaincodeProposalPayload = 1;
 
-	repeated ChaincodeEndorsedAction actions = 2;
-
+	// The list of actions to apply to the ledger
+	ChaincodeEndorsedAction action = 2;
 }
 
+// ChaincodeEndorsedAction carries information about the endorsement of a
+// specific proposal
 message ChaincodeEndorsedAction {
 
-	ProposalResponsePayload responsePayload = 1;
+	// This is the bytes of the ProposalResponsePayload message signed by the
+	// endorsers.  Recall that for the CHAINCODE type, the
+	// ProposalResponsePayload's extenstion field carries a ChaincodeAction
+	bytes proposalResponsePayload = 1;
 
+	// The endorsement of the proposal, basically the endorser's signature over
+	// proposalResponsePayload
 	repeated Endorsement endorsements = 2;
-
 }

protos/next/fabric.proto

@@ -18,29 +18,29 @@ syntax = "proto3";
 
 package protos;
 
-
 // A Message encapsulates a payload of the indicated type in this message.
 message Message {
 
-    enum Type {
+	enum Type {
 
-        // Undefined exists to prevent invalid message construction.
-        UNDEFINED = 0;
+	    // Undefined exists to prevent invalid message construction.
+	    UNDEFINED = 0;
 
-        // Handshake messages.
-        DISCOVERY = 1;
+	    // Handshake messages.
+	    DISCOVERY = 1;
 
-        // Sent to catch up with existing peers.
-        SYNC = 2;
-    }
+	    // Sent to catch up with existing peers.
+	    SYNC = 2;
+	}
 
-    // Type of this message.
-    Type type = 1;
+	// Type of this message.
+	Type type = 1;
 
-    // Version indicates message protocol version.
-    int32 version = 2;
+	// Version indicates message protocol version.
+	int32 version = 2;
 
-    // The payload in this message.
-    bytes payload = 3;
+	// The payload in this message. The way it should be unmarshaled
+	// depends in the type field
+	bytes payload = 3;
 
 }

protos/next/fabric_proposal.proto

@@ -18,32 +18,123 @@ syntax = "proto3";
 
 package protos;
 
-import "fabric_transaction_header.proto";
+/*
+The flow to get a generic transaction approved goes as follows:
+
+1. client sends proposal to endorser
+====================================
+
+The proposal is basically a request to do something that will result on some
+action with impact on the ledger; a proposal contains a header (with some
+metadata describing it, such as the type, the identity of the invoker, the
+time, the ID of the chain, a cryptographic nonce..) and an opaque payload that
+depends on the type specified in the header. A proposal contains the following
+messages:
+
+SignedProposal
+|\_ Signature                                    (signature on the Proposal message by the creator specified in the header)
+ \_ Proposal
+    |\_ Header                                   (the header for this proposal)
+     \_ Payload                                  (the payload for this proposal)
+
+2. endorser sends proposal response back to client
+==================================================
+
+The proposal response contains an endorser's response to a client's proposal. A
+proposal response contains a success/error code, a response payload and a
+signature (also referred to as endorsement) over the response payload. The
+response payload contains a hash of the proposal (to securely link this
+response to the corresponding proposal) and an opaque extension field that
+depends on the type specified in the header of the corresponding proposal. A
+proposal response contains the following messages:
+
+ProposalResponse
+|\_ Endorsement                                  (the endorser's signature over the whole response payload)
+ \_ ProposalResponsePayload                      (the payload of the proposal response)
 
-// This structure is necessary to sign over the proposal which contains
-// the header and the payload. Without this structure, we would have to
-// concatenate the header and the payload to verify the signature, which
-// could be expensive with large payload
+3. client assembles endorsements into a transaction
+===================================================
+
+A transaction message assembles one or more proposals and corresponding
+responses into a message to be sent to orderers. After ordering, (batches of)
+transactions are delivered to committing peers for validation and final
+delivery into the ledger. A transaction contains one or more actions. Each of
+them contains a header (same as that of the proposal that requested it) and an
+opaque payload that depends on the type specified in the header.
+
+SignedTransaction
+|\_ Signature                                    (signature on the Transaction message by the creator specified in the header)
+ \_ Transaction
+     \_ TransactionAction (1...n)
+        |\_ Header (1)                           (the header of the proposal that requested this action)
+         \_ Payload (1)                          (the payload for this action)
+*/
+
+// This structure is necessary to sign the proposal which contains the header
+// and the payload. Without this structure, we would have to concatenate the
+// header and the payload to verify the signature, which could be expensive
+// with large payload
+//
+// When an endorser receives a SignedProposal message, it should verify the
+// signature over the proposal bytes. This verification requires the following
+// steps:
+// 1. Verification of the validity of the certificate that was used to produce
+//    the signature.  The certificate will be available once proposalBytes has
+//    been unmarshalled to a Proposal message, and Proposal.header has been
+//    unmarshalled to a Header message. While this unmarshalling-before-verifying
+//    might not be ideal, it is unavoidable because i) the signature needs to also
+//    protect the signing certificate; ii) it is desirable that Header is created
+//    once by the client and never changed (for the sake of accountability and
+//    non-repudiation). Note also that it is actually impossible to conclusively
+//    verify the validity of the certificate included in a Proposal, because the
+//    proposal needs to first be endorsed and ordered with respect to certificate
+//    expiration transactions. Still, it is useful to pre-filter expired
+//    certificates at this stage.
+// 2. Verification that the certificate is trusted (signed by a trusted CA) and
+//    that it is allowed to transact with us (with respect to some ACLs);
+// 3. Verification that the signature on proposalBytes is valid;
+// 4. Detect replay attacks;
 message SignedProposal {
+
 	// The bytes of Proposal
-	// Allow ProposalResponse to easily hash over the bytes
 	bytes proposalBytes = 1;
 
-	// Signaure over proposalBytes
+  // Signaure over proposalBytes; this signature is to be verified against
+  // the creator identity contained in the header of the Proposal message
+  // marshaled as proposalBytes
 	bytes signature = 2;
 }
 
-// A Proposal is sent to an endorser for endorsement.
-// The proposal contains:
-// 1. A header which has fields common to all proposals and specifies
-// a type field for customization
+// A Proposal is sent to an endorser for endorsement.  The proposal contains:
+// 1. A header which should be unmarshaled to a Header message.  Note that
+//    Header is both the header of a Proposal and of a Transaction, in that i)
+//    both headers should be unmarshaled to this message; and ii) it is used to
+//    compute cryptographic hashes and signatures.  The header has fields common
+//    to all proposals/transactions.  In addition it has a type field for
+//    additional customization. An example of this is the ChaincodeHeaderExtension
+//    message used to extend the Header for type CHAINCODE.
 // 2. A payload whose type depends on the header's type field.
+// 3. An extension whose type depends on the header's type field.
+//
+// Let us see an example. For type CHAINCODE (see the Header message),
+// we have the following:
+// 1. The header is a Header message whose extensions field is a
+//    ChaincodeHeaderExtension message.
+// 2. The payload is a ChaincodeProposalPayload message.
+// 3. The extension is a ChaincodeAction that might be used to ask the
+//    endorsers to endorse a specific ChaincodeAction, thus emulating the
+//    submitting peer model.
 message Proposal {
 
-	// The header of the proposal
-	TransactionHeader header = 1;
+	// The header of the proposal. It is the bytes of the Header
+	bytes header = 1;
 
 	// The payload of the proposal as defined by the type in the proposal
-	// header. For chaincode, it's bytes of ChaincodeProposalPayload
+	// header.
 	bytes payload = 2;
-}
+
+	// Optional extensions to the proposal. Its content depends on the Header's
+	// type field.  For the type CHAINCODE, it might be the bytes of a
+	// ChaincodeAction message.
+	bytes extension = 3;
+}