Skip to content

Commit 41e8113

Browse files
ale-linuxale-linux
committed
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 <[email protected]>
1 parent 5274bb1 commit 41e8113

8 files changed

+357
-118
lines changed

‎protos/next/chaincode_proposal.proto

+97-8
Original file line numberDiff line numberDiff line change
@@ -18,27 +18,116 @@ syntax = "proto3";
1818

1919
package protos;
2020

21-
message ChaincodeTransactionHeaderExtension {
21+
/*
22+
The flow to get a CHAINCODE transaction approved goes as follows:
23+
24+
1. client sends proposal to endorser
25+
====================================
26+
27+
The proposal is basically a request to do something on a chaincode, that will
28+
result on some action - some change in the state of a chaincode and/or some
29+
data to be committed to the ledger; a proposal in general contains a header
30+
(with some metadata describing it, such as the type, the identity of the
31+
invoker, the time, the ID of the chain, a cryptographic nonce..) and a payload
32+
(the chaincode ID, invocation arguments..). Optionally, it may contain actions
33+
that the endorser may be asked to endorse, to emulate a submitting peer. A
34+
chaincode proposal contains the following messages:
35+
36+
SignedProposal
37+
|\_ Signature (signature on the Proposal message by the creator specified in the header)
38+
\_ Proposal
39+
|\_ Header (the header for this proposal)
40+
|\_ ChaincodeProposalPayload (the payload for this proposal)
41+
\_ ChaincodeAction (the actions for this proposal - optional for a proposal)
42+
43+
2. endorser sends proposal response back to client
44+
==================================================
45+
46+
The proposal response contains an endorser's response to a client's proposal. A
47+
proposal response contains a success/error code, a response payload and a
48+
signature (also referred to as endorsement) over the response payload. The
49+
response payload contains a hash of the proposal (to securely link this
50+
response to the corresponding proposal), a description of the action resulting
51+
from the proposal and the endorser's signature over its payload. Formally, a
52+
chaincode proposal response contains the following messages:
53+
54+
ProposalResponse
55+
|\_ Endorsement (the endorser's signature over the whole response payload)
56+
\_ ProposalResponsePayload
57+
\_ ChaincodeAction (the actions for this proposal)
58+
59+
3. client assembles endorsements into a transaction
60+
===================================================
2261
62+
A transaction message assembles one or more proposals and corresponding
63+
responses into a message to be sent to orderers. After ordering, (batches of)
64+
transactions are delivered to committing peers for validation and final
65+
delivery into the ledger. A transaction contains one or more actions. Each of
66+
them contains a header (same as that of the proposal that requested it), a
67+
proposal payload (same as that of the proposal that requested it), a
68+
description of the resulting action and signatures from each of the endorsers
69+
that endorsed the action.
70+
71+
SignedTransaction
72+
|\_ Signature (signature on the Transaction message by the creator specified in the header)
73+
\_ Transaction
74+
\_ TransactionAction (1...n)
75+
|\_ Header (1) (the header of the proposal that requested this action)
76+
\_ ChaincodeActionPayload (1)
77+
|\_ ChaincodeProposalPayload (1) (payload of the proposal that requested this action)
78+
\_ ChaincodeEndorsedAction (1)
79+
|\_ Endorsement (1...n) (endorsers' signatures over the whole response payload)
80+
\_ ProposalResponsePayload
81+
\_ ChaincodeAction (the actions for this proposal)
82+
*/
83+
84+
// ChaincodeHeaderExtension is the Header's extentions message to be used when
85+
// the Header's type is CHAINCODE. This extensions is used to specify which
86+
// chaincode to invoke and what should appear on the ledger.
87+
message ChaincodeHeaderExtension {
88+
89+
// The PayloadVisibility field controls to what extent the Proposal's payload
90+
// (recall that for the type CHAINCODE, it is ChaincodeProposalPayload
91+
// message) field will be visible in the final transaction and in the ledger.
92+
// Ideally, it would be configurable, supporting at least 3 main “visibility
93+
// modes”:
94+
// 1. all bytes of the payload are visible;
95+
// 2. only a hash of the payload is visible;
96+
// 3. nothing is visible.
97+
// Notice that the visibility function may be potentially part of the ESCC.
98+
// In that case it overrides PayloadVisibility field. Finally notice that
99+
// this field impacts the content of ProposalResponsePayload.proposalHash.
23100
bytes payloadVisibility = 1;
24101

102+
// The ID of the chaincode to target.
25103
bytes chaincodeID = 2;
26104
}
27105

106+
// ChaincodeProposalPayload is the Proposal's payload message to be used when
107+
// the Header's type is CHAINCODE. It contains the arguments for this
108+
// invocation.
28109
message ChaincodeProposalPayload {
29-
ChaincodeProposalInputs inputs = 1;
30-
ChaincodeProposalSimulation simulation = 2;
31-
}
32110

33-
message ChaincodeProposalInputs {
111+
// Input contains the arguments for this invocation. If this invocation
112+
// deploys a new chaincode, ESCC/VSCC are part of this field.
34113
bytes Input = 1;
35114

115+
// Transient contains data (e.g. cryptographic material) that might be used
116+
// to implement some form of application-level confidentiality. The contents
117+
// of this field are supposed to always be omitted from the transaction and
118+
// excluded from the ledger.
36119
bytes Transient = 2;
37120
}
38121

39-
message ChaincodeProposalSimulation {
40-
bytes simulationResults = 1;
122+
// ChaincodeAction contains the actions the events generated by the execution
123+
// of the chaincode.
124+
message ChaincodeAction {
125+
126+
// This field contains the read set and the write set produced by the
127+
// chaincode executing this invocation.
128+
bytes results = 1;
41129

130+
// This field contains the events generated by the chaincode executing this
131+
// invocation.
42132
bytes events = 2;
43133
}
44-

‎protos/next/chaincode_proposal_response.proto

-26
This file was deleted.

‎protos/next/chaincode_transaction.proto

+24-11
Original file line numberDiff line numberDiff line change
@@ -20,23 +20,36 @@ package protos;
2020

2121
import "fabric_proposal_response.proto";
2222

23-
message ChaincodeActionsPayload {
24-
25-
// ChaincodeProposalPayload is present in the transaction
26-
// depending on the payloadVisibility field in the
27-
// ChaincodeTransactionHeaderExtension.
28-
// (it could be there in its entirety, it could be hashed or it
29-
// could be totally absent)
23+
// ChaincodeActionPayload is the message to be used for the TransactionAction's
24+
// payload when the Header's type is set to CHAINCODE. It carries the
25+
// chaincodeProposalPayload and an endorsed action to apply to the ledger.
26+
message ChaincodeActionPayload {
27+
28+
// This field contains the bytes of the ChaincodeProposalPayload message from
29+
// the original invocation (essentially the arguments) after the application
30+
// of the visibility function. The main visibility modes are "full" (the
31+
// entire ChaincodeProposalPayload message is included here), "hash" (only
32+
// the hash of the ChaincodeProposalPayload message is included) or
33+
// "nothing". This field will be used to check the consistency of
34+
// ProposalResponsePayload.proposalHash. For the CHAINCODE type,
35+
// ProposalResponsePayload.proposalHash is supposed to be H(ProposalHeader ||
36+
// f(ChaincodeProposalPayload)) where f is the visibility function.
3037
bytes chaincodeProposalPayload = 1;
3138

32-
repeated ChaincodeEndorsedAction actions = 2;
33-
39+
// The list of actions to apply to the ledger
40+
ChaincodeEndorsedAction action = 2;
3441
}
3542

43+
// ChaincodeEndorsedAction carries information about the endorsement of a
44+
// specific proposal
3645
message ChaincodeEndorsedAction {
3746

38-
ProposalResponsePayload responsePayload = 1;
47+
// This is the bytes of the ProposalResponsePayload message signed by the
48+
// endorsers. Recall that for the CHAINCODE type, the
49+
// ProposalResponsePayload's extenstion field carries a ChaincodeAction
50+
bytes proposalResponsePayload = 1;
3951

52+
// The endorsement of the proposal, basically the endorser's signature over
53+
// proposalResponsePayload
4054
repeated Endorsement endorsements = 2;
41-
4255
}

‎protos/next/fabric.proto

+15-15
Original file line numberDiff line numberDiff line change
@@ -18,29 +18,29 @@ syntax = "proto3";
1818

1919
package protos;
2020

21-
2221
// A Message encapsulates a payload of the indicated type in this message.
2322
message Message {
2423

25-
enum Type {
24+
enum Type {
2625

27-
// Undefined exists to prevent invalid message construction.
28-
UNDEFINED = 0;
26+
// Undefined exists to prevent invalid message construction.
27+
UNDEFINED = 0;
2928

30-
// Handshake messages.
31-
DISCOVERY = 1;
29+
// Handshake messages.
30+
DISCOVERY = 1;
3231

33-
// Sent to catch up with existing peers.
34-
SYNC = 2;
35-
}
32+
// Sent to catch up with existing peers.
33+
SYNC = 2;
34+
}
3635

37-
// Type of this message.
38-
Type type = 1;
36+
// Type of this message.
37+
Type type = 1;
3938

40-
// Version indicates message protocol version.
41-
int32 version = 2;
39+
// Version indicates message protocol version.
40+
int32 version = 2;
4241

43-
// The payload in this message.
44-
bytes payload = 3;
42+
// The payload in this message. The way it should be unmarshaled
43+
// depends in the type field
44+
bytes payload = 3;
4545

4646
}

‎protos/next/fabric_proposal.proto

+106-15
Original file line numberDiff line numberDiff line change
@@ -18,32 +18,123 @@ syntax = "proto3";
1818

1919
package protos;
2020

21-
import "fabric_transaction_header.proto";
21+
/*
22+
The flow to get a generic transaction approved goes as follows:
23+
24+
1. client sends proposal to endorser
25+
====================================
26+
27+
The proposal is basically a request to do something that will result on some
28+
action with impact on the ledger; a proposal contains a header (with some
29+
metadata describing it, such as the type, the identity of the invoker, the
30+
time, the ID of the chain, a cryptographic nonce..) and an opaque payload that
31+
depends on the type specified in the header. A proposal contains the following
32+
messages:
33+
34+
SignedProposal
35+
|\_ Signature (signature on the Proposal message by the creator specified in the header)
36+
\_ Proposal
37+
|\_ Header (the header for this proposal)
38+
\_ Payload (the payload for this proposal)
39+
40+
2. endorser sends proposal response back to client
41+
==================================================
42+
43+
The proposal response contains an endorser's response to a client's proposal. A
44+
proposal response contains a success/error code, a response payload and a
45+
signature (also referred to as endorsement) over the response payload. The
46+
response payload contains a hash of the proposal (to securely link this
47+
response to the corresponding proposal) and an opaque extension field that
48+
depends on the type specified in the header of the corresponding proposal. A
49+
proposal response contains the following messages:
50+
51+
ProposalResponse
52+
|\_ Endorsement (the endorser's signature over the whole response payload)
53+
\_ ProposalResponsePayload (the payload of the proposal response)
2254
23-
// This structure is necessary to sign over the proposal which contains
24-
// the header and the payload. Without this structure, we would have to
25-
// concatenate the header and the payload to verify the signature, which
26-
// could be expensive with large payload
55+
3. client assembles endorsements into a transaction
56+
===================================================
57+
58+
A transaction message assembles one or more proposals and corresponding
59+
responses into a message to be sent to orderers. After ordering, (batches of)
60+
transactions are delivered to committing peers for validation and final
61+
delivery into the ledger. A transaction contains one or more actions. Each of
62+
them contains a header (same as that of the proposal that requested it) and an
63+
opaque payload that depends on the type specified in the header.
64+
65+
SignedTransaction
66+
|\_ Signature (signature on the Transaction message by the creator specified in the header)
67+
\_ Transaction
68+
\_ TransactionAction (1...n)
69+
|\_ Header (1) (the header of the proposal that requested this action)
70+
\_ Payload (1) (the payload for this action)
71+
*/
72+
73+
// This structure is necessary to sign the proposal which contains the header
74+
// and the payload. Without this structure, we would have to concatenate the
75+
// header and the payload to verify the signature, which could be expensive
76+
// with large payload
77+
//
78+
// When an endorser receives a SignedProposal message, it should verify the
79+
// signature over the proposal bytes. This verification requires the following
80+
// steps:
81+
// 1. Verification of the validity of the certificate that was used to produce
82+
// the signature. The certificate will be available once proposalBytes has
83+
// been unmarshalled to a Proposal message, and Proposal.header has been
84+
// unmarshalled to a Header message. While this unmarshalling-before-verifying
85+
// might not be ideal, it is unavoidable because i) the signature needs to also
86+
// protect the signing certificate; ii) it is desirable that Header is created
87+
// once by the client and never changed (for the sake of accountability and
88+
// non-repudiation). Note also that it is actually impossible to conclusively
89+
// verify the validity of the certificate included in a Proposal, because the
90+
// proposal needs to first be endorsed and ordered with respect to certificate
91+
// expiration transactions. Still, it is useful to pre-filter expired
92+
// certificates at this stage.
93+
// 2. Verification that the certificate is trusted (signed by a trusted CA) and
94+
// that it is allowed to transact with us (with respect to some ACLs);
95+
// 3. Verification that the signature on proposalBytes is valid;
96+
// 4. Detect replay attacks;
2797
message SignedProposal {
98+
2899
// The bytes of Proposal
29-
// Allow ProposalResponse to easily hash over the bytes
30100
bytes proposalBytes = 1;
31101

32-
// Signaure over proposalBytes
102+
// Signaure over proposalBytes; this signature is to be verified against
103+
// the creator identity contained in the header of the Proposal message
104+
// marshaled as proposalBytes
33105
bytes signature = 2;
34106
}
35107

36-
// A Proposal is sent to an endorser for endorsement.
37-
// The proposal contains:
38-
// 1. A header which has fields common to all proposals and specifies
39-
// a type field for customization
108+
// A Proposal is sent to an endorser for endorsement. The proposal contains:
109+
// 1. A header which should be unmarshaled to a Header message. Note that
110+
// Header is both the header of a Proposal and of a Transaction, in that i)
111+
// both headers should be unmarshaled to this message; and ii) it is used to
112+
// compute cryptographic hashes and signatures. The header has fields common
113+
// to all proposals/transactions. In addition it has a type field for
114+
// additional customization. An example of this is the ChaincodeHeaderExtension
115+
// message used to extend the Header for type CHAINCODE.
40116
// 2. A payload whose type depends on the header's type field.
117+
// 3. An extension whose type depends on the header's type field.
118+
//
119+
// Let us see an example. For type CHAINCODE (see the Header message),
120+
// we have the following:
121+
// 1. The header is a Header message whose extensions field is a
122+
// ChaincodeHeaderExtension message.
123+
// 2. The payload is a ChaincodeProposalPayload message.
124+
// 3. The extension is a ChaincodeAction that might be used to ask the
125+
// endorsers to endorse a specific ChaincodeAction, thus emulating the
126+
// submitting peer model.
41127
message Proposal {
42128

43-
// The header of the proposal
44-
TransactionHeader header = 1;
129+
// The header of the proposal. It is the bytes of the Header
130+
bytes header = 1;
45131

46132
// The payload of the proposal as defined by the type in the proposal
47-
// header. For chaincode, it's bytes of ChaincodeProposalPayload
133+
// header.
48134
bytes payload = 2;
49-
}
135+
136+
// Optional extensions to the proposal. Its content depends on the Header's
137+
// type field. For the type CHAINCODE, it might be the bytes of a
138+
// ChaincodeAction message.
139+
bytes extension = 3;
140+
}

0 commit comments

Comments
 (0)