package protos

Get desktop application:
View/edit binary Protocol Buffers messages

• rpc ProcessProposal (SignedProposal, ProposalResponse)

  peer.proto:36

  message SignedProposal

  proposal.proto:104

  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;

  • bytes proposal_bytes = 1

    The bytes of Proposal

  • bytes signature = 2

    Signaure over proposalBytes; this signature is to be verified against the creator identity contained in the header of the Proposal message marshaled as proposalBytes

  message ProposalResponse

  proposal_response.proto:35

  A ProposalResponse is returned from an endorser to the proposal submitter. The idea is that this message contains the endorser's response to the request of a client to perform an action over a chaincode (or more generically on the ledger); the response might be success/error (conveyed in the Response field) together with a description of the action and a signature over it by that endorser. If a sufficient number of distinct endorsers agree on the same action and produce signature to that effect, a transaction can be generated and sent for ordering.

  • int32 version = 1

    Version indicates message protocol version

  • optional google.protobuf.Timestamp timestamp = 2

    Timestamp is the time that the message was created as defined by the sender

  • optional Response response = 4

    A response message indicating whether the endorsement of the action was successful

  • bytes payload = 5

    The payload of response. It is the bytes of ProposalResponsePayload

  • optional Endorsement endorsement = 6

    The endorsement of the proposal, basically the endorser's signature over the payload

Interface exported by the events server

• rpc Chat (stream SignedEvent, stream Event)

  events.proto:110

  event chatting using Event

  message SignedEvent

  events.proto:78

  SignedEvent is used for any communication between consumer and producer

  • bytes signature = 1

    Signature over the event bytes

  • bytes eventBytes = 2

    Marshal of Event object

  message Event

  events.proto:88

  Event is used by - consumers (adapters) to send Register - producer to advertise supported types and events

  TODO need timestamp

  • oneof Event

    • Register register = 1

      Register consumer sent event

    • common.Block block = 2

      producer events

    • ChaincodeEvent chaincode_event = 3

    • Rejection rejection = 4

    • Unregister unregister = 5

      Unregister consumer sent events

  • bytes creator = 6

    Creator of the event, specified as a certificate chain

AnchorPeer message structure which provides information about anchor peer, it includes host name, port number and peer certificate.

Used in: AnchorPeers

• string host = 1

  DNS host name of the anchor peer

• int32 port = 2

  The port number

AnchorPeers simply represents list of anchor peers which is used in ConfigurationItem

• repeated AnchorPeer anchor_peers = 1

ChaincodeAction contains the actions the events generated by the execution of the chaincode.

• bytes results = 1

  This field contains the read set and the write set produced by the chaincode executing this invocation.

• bytes events = 2

  This field contains the events generated by the chaincode executing this invocation.

• optional Response response = 3

  This field contains the result of executing this invocation.

• optional ChaincodeID chaincode_id = 4

  This field contains the ChaincodeID of executing this invocation. Endorser will set it with the ChaincodeID called by endorser while simulating proposal. Committer will validate the version matching with latest chaincode version. Adding ChaincodeID to keep version opens up the possibility of multiple ChaincodeAction per transaction.

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.

• bytes chaincode_proposal_payload = 1

  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.

• optional ChaincodeEndorsedAction action = 2

  The list of actions to apply to the ledger

Specify the deployment of a chaincode. TODO: Define `codePackage`.

• optional ChaincodeSpec chaincode_spec = 1

• optional google.protobuf.Timestamp effective_date = 2

  Controls when the chaincode becomes executable.

• bytes code_package = 3

• ChaincodeDeploymentSpec.ExecutionEnvironment exec_env = 4

Used in: ChaincodeDeploymentSpec

• DOCKER = 0

• SYSTEM = 1

ChaincodeEndorsedAction carries information about the endorsement of a specific proposal

Used in: ChaincodeActionPayload

• bytes proposal_response_payload = 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

• repeated Endorsement endorsements = 2

  The endorsement of the proposal, basically the endorser's signature over proposalResponsePayload

ChaincodeEvent is used for events and registrations that are specific to chaincode string type - "chaincode"

Used in: Event

• string chaincode_id = 1

• string tx_id = 2

• string event_name = 3

• bytes payload = 4

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.

• bytes payload_visibility = 1

  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.

• optional ChaincodeID chaincode_id = 2

  The ID of the chaincode to target.

ChaincodeID contains the path as specified by the deploy transaction that created it as well as the hashCode that is generated by the system for the path. From the user level (ie, CLI, REST API and so on) deploy transaction is expected to provide the path and other requests are expected to provide the hashCode. The other value will be ignored. Internally, the structure could contain both values. For instance, the hashCode will be set when first generated using the path

Used in: ChaincodeAction, ChaincodeHeaderExtension, ChaincodeSpec

• string path = 1

  deploy transaction will use the path

• string name = 2

  all other requests will use the name (really a hashcode) generated by the deploy transaction

• string version = 3

  user friendly version name for the chaincode

ChaincodeInfo contains general information about an installed/instantiated chaincode

Used in: ChaincodeQueryResponse

• string name = 1

• string version = 2

• string path = 3

  the path as specified by the install/instantiate transaction

• string input = 4

  the chaincode function upon instantiation and its arguments. This will be blank if the query is returning information about installed chaincodes.

• string escc = 5

  the name of the ESCC for this chaincode. This will be blank if the query is returning information about installed chaincodes.

• string vscc = 6

  the name of the VSCC for this chaincode. This will be blank if the query is returning information about installed chaincodes.

Carries the chaincode function and its arguments. UnmarshalJSON in transaction.go converts the string-based REST/JSON input to the []byte-based current ChaincodeInput structure.

Used in: ChaincodeSpec

• repeated bytes args = 1

• map<string, bytes> decorations = 2

Carries the chaincode function and its arguments.

• optional ChaincodeSpec chaincode_spec = 1

• string id_generation_alg = 2

  This field can contain a user-specified ID generation algorithm If supplied, this will be used to generate a ID If not supplied (left empty), sha256base64 will be used The algorithm consists of two parts: 1, a hash function 2, a decoding used to decode user (string) input to bytes Currently, SHA256 with BASE64 is supported (e.g. idGenerationAlg='sha256base64')

ChaincodeProposalPayload is the Proposal's payload message to be used when the Header's type is CHAINCODE. It contains the arguments for this invocation.

• bytes input = 1

  Input contains the arguments for this invocation. If this invocation deploys a new chaincode, ESCC/VSCC are part of this field. This is usually a marshaled ChaincodeInvocationSpec

• map<string, bytes> TransientMap = 2

  TransientMap 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.

ChaincodeQueryResponse returns information about each chaincode that pertains to a query in lscc.go, such as GetChaincodes (returns all chaincodes instantiated on a channel), and GetInstalledChaincodes (returns all chaincodes installed on a peer)

• repeated ChaincodeInfo chaincodes = 1

ChaincodeReg is used for registering chaincode Interests when EventType is CHAINCODE

Used in: Interest

• string chaincode_id = 1

• string event_name = 2

Carries the chaincode specification. This is the actual metadata required for defining a chaincode.

Used in: ChaincodeDeploymentSpec, ChaincodeInvocationSpec

• ChaincodeSpec.Type type = 1

• optional ChaincodeID chaincode_id = 2

• optional ChaincodeInput input = 3

• int32 timeout = 4

Used in: ChaincodeSpec

• UNDEFINED = 0

• GOLANG = 1

• NODE = 2

• CAR = 3

• JAVA = 4

ChannelInfo contains general information about channels

Used in: ChannelQueryResponse

• string channel_id = 1

ChannelQueryResponse returns information about each channel that pertains to a query in lscc.go, such as GetChannels (returns all channels for a given peer)

• repeated ChannelInfo channels = 1

Confidentiality Levels

• PUBLIC = 0

• CONFIDENTIAL = 1

An endorsement is a signature of an endorser over a proposal response. By producing an endorsement message, an endorser implicitly "approves" that proposal response and the actions contained therein. When enough endorsements have been collected, a transaction can be generated out of a set of proposal responses. Note that this message only contains an identity and a signature but no signed payload. This is intentional because endorsements are supposed to be collected in a transaction, and they are all expected to endorse a single proposal response/action (many endorsements over a single proposal response)

Used in: ChaincodeEndorsedAction, ProposalResponse

• bytes endorser = 1

  Identity of the endorser (e.g. its certificate)

• bytes signature = 2

  Signature of the payload included in ProposalResponse concatenated with the endorser's certificate; ie, sign(ProposalResponse.payload + endorser)

Used in: Interest

• REGISTER = 0

• BLOCK = 1

• CHAINCODE = 2

• REJECTION = 3

Used in: Register, Unregister

• EventType event_type = 1

• oneof RegInfo

  Ideally we should just have the following oneof for different Reg types and get rid of EventType. But this is an API change Additional Reg types may add messages specific to their type to the oneof.

  • ChaincodeReg chaincode_reg_info = 2

• string chainID = 3

• optional PeerID id = 1

• string address = 2

Used in: PeerEndpoint

• string name = 1

ProcessedTransaction wraps an Envelope that includes a transaction along with an indication of whether the transaction was validated or invalidated by committing peer. The use case is that GetTransactionByID API needs to retrieve the transaction Envelope from block storage, and return it to a client, and indicate whether the transaction was validated or invalidated by committing peer. So that the originally submitted transaction Envelope is not modified, the ProcessedTransaction wrapper is returned.

• optional common.Envelope transactionEnvelope = 1

  An Envelope which includes a processed transaction

• int32 validationCode = 2

  An indication of whether the transaction was validated or invalidated by committing peer

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.

• bytes header = 1

  The header of the proposal. It is the bytes of the Header

• bytes payload = 2

  The payload of the proposal as defined by the type in the proposal header.

• bytes extension = 3

  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.

ProposalResponsePayload is the payload of a proposal response. This message is the "bridge" between the client's request and the endorser's action in response to that request. Concretely, for chaincodes, it contains a hashed representation of the proposal (proposalHash) and a representation of the chaincode state changes and events inside the extension field.

• bytes proposal_hash = 1

  Hash of the proposal that triggered this response. The hash is used to link a response with its proposal, both for bookeeping purposes on an asynchronous system and for security reasons (accountability, non-repudiation). The hash usually covers the entire Proposal message (byte-by-byte). However this implies that the hash can only be verified if the entire proposal message is available when ProposalResponsePayload is included in a transaction or stored in the ledger. For confidentiality reasons, with chaincodes it might be undesirable to store the proposal payload in the ledger. If the type is CHAINCODE, this is handled by separating the proposal's header and the payload: the header is always hashed in its entirety whereas the payload can either be hashed fully, or only its hash may be hashed, or nothing from the payload can be hashed. The PayloadVisibility field in the Header's extension controls to which extent the proposal payload is "visible" in the sense that was just explained.

• bytes extension = 2

  Extension should be unmarshaled to a type-specific message. The type of the extension in any proposal response depends on the type of the proposal that the client selected when the proposal was initially sent out. In particular, this information is stored in the type field of a Header. For chaincode, it's a ChaincodeAction message

---------- consumer events --------- Register is sent by consumers for registering events string type - "register"

Used in: Event

• repeated Interest events = 1

Rejection is sent by consumers for erroneous transaction rejection events string type - "rejection"

Used in: Event

• optional Transaction tx = 1

• string error_msg = 2

A response with a representation similar to an HTTP response that can be used within another message.

Used in: ChaincodeAction, ProposalResponse

• int32 status = 1

  A status code that should follow the HTTP status codes.

• string message = 2

  A message associated with the response code.

• bytes payload = 3

  A payload that can be used to include metadata with this response.

This message is necessary to facilitate the verification of the signature (in the signature field) over the bytes of the transaction (in the transactionBytes field).

• bytes transaction_bytes = 1

  The bytes of the Transaction. NDD

• bytes signature = 2

  Signature of the transactionBytes The public key of the signature is in the header field of TransactionAction There might be multiple TransactionAction, so multiple headers, but there should be same transactor identity (cert) in all headers

The transaction to be sent to the ordering service. A transaction contains one or more TransactionAction. Each TransactionAction binds a proposal to potentially multiple actions. The transaction is atomic meaning that either all actions in the transaction will be committed or none will. Note that while a Transaction might include more than one Header, the Header.creator field must be the same in each. A single client is free to issue a number of independent Proposal, each with their header (Header) and request payload (ChaincodeProposalPayload). Each proposal is independently endorsed generating an action (ProposalResponsePayload) with one signature per Endorser. Any number of independent proposals (and their action) might be included in a transaction to ensure that they are treated atomically.

Used in: Rejection

• repeated TransactionAction actions = 1

  The payload is an array of TransactionAction. An array is necessary to accommodate multiple actions per transaction

TransactionAction binds a proposal to its action. The type field in the header dictates the type of action to be applied to the ledger.

Used in: Transaction

• bytes header = 1

  The header of the proposal action, which is the proposal header

• bytes payload = 2

  The payload of the action as defined by the type in the header For chaincode, it's the bytes of ChaincodeActionPayload

• VALID = 0

• NIL_ENVELOPE = 1

• BAD_PAYLOAD = 2

• BAD_COMMON_HEADER = 3

• BAD_CREATOR_SIGNATURE = 4

• INVALID_ENDORSER_TRANSACTION = 5

• INVALID_CONFIG_TRANSACTION = 6

• UNSUPPORTED_TX_PAYLOAD = 7

• BAD_PROPOSAL_TXID = 8

• DUPLICATE_TXID = 9

• ENDORSEMENT_POLICY_FAILURE = 10

• MVCC_READ_CONFLICT = 11

• PHANTOM_READ_CONFLICT = 12

• UNKNOWN_TX_TYPE = 13

• TARGET_CHAIN_NOT_FOUND = 14

• MARSHAL_TX_ERROR = 15

• NIL_TXACTION = 16

• EXPIRED_CHAINCODE = 17

• CHAINCODE_VERSION_CONFLICT = 18

• BAD_HEADER_EXTENSION = 19

• BAD_CHANNEL_HEADER = 20

• BAD_RESPONSE_PAYLOAD = 21

• BAD_RWSET = 22

• ILLEGAL_WRITESET = 23

• INVALID_OTHER_REASON = 255

---------- producer events ---------

Used in: Event

• repeated Interest events = 1