From dd44c2e44617c1a67d33106d7c60c750bb7bceed Mon Sep 17 00:00:00 2001 From: Will Lahti Date: Tue, 6 Feb 2018 15:45:23 -0500 Subject: [PATCH] [FAB-6979] Improve chaincode shim API documentation This CR improves the documentation for a number of chaincode shim API calls. Change-Id: I3f7463e974538775a4e362fd221ea6a38c12f42a Signed-off-by: Will Lahti --- core/chaincode/shim/interfaces_experimental.go | 17 +++++++++++------ core/chaincode/shim/interfaces_stable.go | 17 +++++++++++------ 2 files changed, 22 insertions(+), 12 deletions(-) diff --git a/core/chaincode/shim/interfaces_experimental.go b/core/chaincode/shim/interfaces_experimental.go index b20c6e62fb8..70e847947aa 100644 --- a/core/chaincode/shim/interfaces_experimental.go +++ b/core/chaincode/shim/interfaces_experimental.go @@ -51,8 +51,9 @@ type ChaincodeStubInterface interface { // Invoke as a byte array GetArgsSlice() ([]byte, error) - // GetTxID returns the tx_id of the transaction proposal (see ChannelHeader - // in protos/common/common.proto) + // GetTxID returns the tx_id of the transaction proposal, which is unique per + // transaction and per client. See ChannelHeader in protos/common/common.proto + // for further details. GetTxID() string // GetChannelID returns the channel the proposal is sent to for chaincode to process. @@ -236,11 +237,15 @@ type ChaincodeStubInterface interface { // be omitted from the transaction and excluded from the ledger. GetTransient() (map[string][]byte, error) - // GetBinding returns the transaction binding + // GetBinding returns the transaction binding, which is used to enofrce a + // link between application data (like those stored in the transient field + // above) to the proposal itself. This is useful to avoid possible replay + // attacks. GetBinding() ([]byte, error) - // GetDecorations returns additional data (if applicable) - // about the proposal that originated from the peer + // GetDecorations returns additional data (if applicable) about the proposal + // that originated from the peer. This data is set by the decorators of the + // peer, which append or mutate the chaincode input passed to the chaincode. GetDecorations() map[string][]byte // GetSignedProposal returns the SignedProposal object, which contains all @@ -249,7 +254,7 @@ type ChaincodeStubInterface interface { // GetTxTimestamp returns the timestamp when the transaction was created. This // is taken from the transaction ChannelHeader, therefore it will indicate the - // client's timestamp, and will have the same value across all endorsers. + // client's timestamp and will have the same value across all endorsers. GetTxTimestamp() (*timestamp.Timestamp, error) // SetEvent allows the chaincode to set an event on the response to the diff --git a/core/chaincode/shim/interfaces_stable.go b/core/chaincode/shim/interfaces_stable.go index 4c959db8dae..c16c4492b8c 100644 --- a/core/chaincode/shim/interfaces_stable.go +++ b/core/chaincode/shim/interfaces_stable.go @@ -51,8 +51,9 @@ type ChaincodeStubInterface interface { // Invoke as a byte array GetArgsSlice() ([]byte, error) - // GetTxID returns the tx_id of the transaction proposal (see ChannelHeader - // in protos/common/common.proto) + // GetTxID returns the tx_id of the transaction proposal, which is unique per + // transaction and per client. See ChannelHeader in protos/common/common.proto + // for further details. GetTxID() string // GetChannelID returns the channel the proposal is sent to for chaincode to process. @@ -174,11 +175,15 @@ type ChaincodeStubInterface interface { // be omitted from the transaction and excluded from the ledger. GetTransient() (map[string][]byte, error) - // GetBinding returns the transaction binding + // GetBinding returns the transaction binding, which is used to enofrce a + // link between application data (like those stored in the transient field + // above) to the proposal itself. This is useful to avoid possible replay + // attacks. GetBinding() ([]byte, error) - // GetDecorations returns additional data (if applicable) - // about the proposal that originated from the peer + // GetDecorations returns additional data (if applicable) about the proposal + // that originated from the peer. This data is set by the decorators of the + // peer, which append or mutate the chaincode input passed to the chaincode. GetDecorations() map[string][]byte // GetSignedProposal returns the SignedProposal object, which contains all @@ -187,7 +192,7 @@ type ChaincodeStubInterface interface { // GetTxTimestamp returns the timestamp when the transaction was created. This // is taken from the transaction ChannelHeader, therefore it will indicate the - // client's timestamp, and will have the same value across all endorsers. + // client's timestamp and will have the same value across all endorsers. GetTxTimestamp() (*timestamp.Timestamp, error) // SetEvent allows the chaincode to set an event on the response to the