package common

Get desktop application:
View/edit binary Protocol Buffers messages

This is finalized block structure to be shared among the consenter and node Note that the BlockHeader chains to the previous BlockHeader, and the BlockData hash is embedded in the BlockHeader. This makes it natural and obvious that the Data is included in the hash, but the Metadata is not.

Used in: consenter.DeliverResponse, protos.DeliverResponse, protos.Event

• optional BlockHeader header = 1

• optional BlockData data = 2

• optional BlockMetadata metadata = 3

Used in: Block

• repeated bytes data = 1

BlockDataHashingStructure is encoded into the configuration transaction as a configuration item of type Chain with a Key of "BlockDataHashingStructure" and a Value of HashingAlgorithm as marshaled protobuf bytes

• uint32 width = 1

  width specifies the width of the Merkle tree to use when computing the BlockDataHash in order to replicate flat hashing, set this width to MAX_UINT32

BlockHeader is the element of the block which forms the block chain The block header is hashed using the configured chain hashing algorithm over the ASN.1 encoding of the BlockHeader

Used in: Block

• uint64 number = 1

  The position in the blockchain

• bytes previous_hash = 2

  The hash of the previous block header

• bytes data_hash = 3

  The hash of the BlockData, by MerkleTree

Used in: Block

• repeated bytes metadata = 1

This enum enlists indexes of the block metadata array

• SIGNATURES = 0

  Block metadata array position for block signatures

• LAST_CONFIG = 1

  Block metadata array position to store last configuration block sequence number

• TRANSACTIONS_FILTER = 2

  Block metadata array position to store serialized bit array filter of invalid transactions

• CONSENTER = 3

  Block metadata array position to store operational metadata for consenters

Contains information about the blockchain ledger such as height, current block hash, and previous block hash.

• uint64 height = 1

• bytes currentBlockHash = 2

• bytes previousBlockHash = 3

Capabilities message defines the capabilities a particular binary must implement for that binary to be able to safely participate in the group. The capabilities message is defined at the /Group level, the /Group/Application level, and the /Group/Consenter level. The /Group level capabilties define capabilities which both the consenter and node binaries must satisfy. These capabilties might be things like a new MSP type, or a new policy type. The /Group/Consenter level capabilties define capabilities which must be supported by the consenter, but which have no bearing on the behavior of the node. For instance if the consenter changes the logic for how it constructs new groups, only all consenters must agree on the new logic. The nodes do not need to be aware of this change as they only interact with the group after it has been constructed. Finally, the /Group/Application level capabilities define capabilities which the node binary must satisfy, but which have no bearing on the consenter. For instance, if the node adds a new UTXO transaction type, or changes the chaincode lifecycle requirements, all nodes must agree on the new logic. However, consenters never inspect transactions this deeply, and therefore have no need to be aware of the change. The capabilities strings defined in these messages typically correspond to release binary versions (e.g. "V1.1"), and are used primarilly as a mechanism for a fully upgraded network to switch from one set of logic to a new one. Although for V1.1, the consenters must be upgraded to V1.1 prior to the rest of the network, going forward, because of the split between the /Group, /Group/Consenter and /Group/Application capabilities. It should be possible for the consenter and application networks to upgrade themselves independently (with the exception of any new capabilities defined at the /Group level).

• map<string, Capability> capabilities = 1

Capability is an empty message for the time being. It is defined as a protobuf message rather than a constant, so that we may extend capabilities with other fields if the need arises in the future. For the time being, a capability being in the capabilities map requires that that capability be supported.

Used in: Capabilities

(message has no fields)

CollectionConfig defines the configuration of a collection object; it currently contains a single, static type. Dynamic collections are deferred.

Used in: CollectionConfigPackage

• oneof payload

  • StaticCollectionConfig static_collection_config = 1

CollectionConfigPackage represents an array of CollectionConfig messages; the extra struct is required because repeated oneof is forbidden by the protobuf syntax

• repeated CollectionConfig config = 1

CollectionCriteria defines an element of a private data that corresponds to a certain transaction and collection

• string group = 1

• string tx_id = 2

• string collection = 3

• string namespace = 4

Collection policy configuration. Initially, the configuration can only contain a SignaturePolicy. In the future, the SignaturePolicy may be a more general Policy. Instead of containing the actual policy, the configuration may in the future contain a string reference to a policy.

Used in: StaticCollectionConfig

• oneof payload

  • SignaturePolicyEnvelope signature_policy = 1

    Initially, only a signature policy is supported.

    Later, the SignaturePolicy will be replaced by a Policy. Policy policy = 1; A reference to a Policy is planned to be added later. string reference = 2;

Config represents the config for a particular group

Used in: ConfigEnvelope, protos.RootConfigTree

• uint64 sequence = 1

• optional ConfigTree group_tree = 2

  group_tree is a bad name for this, it should be changed to root when API breakage is

• int32 type = 3

  allowed

ConfigEnvelope is designed to contain _all_ configuration for a chain with no dependency on previous configuration transactions. It is generated with the following scheme: 1. Retrieve the existing configuration 2. Note the config properties (ConfigValue, IConfigPolicy, ConfigTree) to be modified 3. Add any intermediate ConfigTrees to the ConfigUpdate.read_set (sparsely) 4. Add any additional desired dependencies to ConfigUpdate.read_set (sparsely) 5. Modify the config properties, incrementing each version by 1, set them in the ConfigUpdate.write_set Note: any element not modified but specified should already be in the read_set, so may be specified sparsely 6. Create ConfigUpdate message and marshal it into ConfigUpdateEnvelope.update and encode the required signatures a) Each signature is of type ConfigSignature b) The ConfigSignature signature is over the concatenation of signature_header and the ConfigUpdate bytes (which includes a ChainHeader) 5. Submit new Config for ordering in Envelope signed by submitter a) The Envelope Payload has data set to the marshaled ConfigEnvelope b) The Envelope Payload has a header of type Header.Type.CONFIG_UPDATE The configuration getPolicyManager will verify: 1. All items in the read_set exist at the read versions 2. All items in the write_set at a different version than, or not in, the read_set have been appropriately signed according to their mod_policy 3. The new configuration satisfies the ConfigSchema

• optional Config config = 1

  A marshaled Config structure

• optional Envelope last_update = 2

  The last CONFIG_UPDATE message which generated this current configuration

Used in: ConfigTree

• uint64 version = 1

• optional Policy policy = 2

• string mod_policy = 3

Used in: ConfigTreeSchema

(message has no fields)

Used in: ConfigUpdateEnvelope

• bytes signature_header = 1

  A marshaled SignatureHeader

• bytes signature = 2

  Signature over the concatenation signatureHeader bytes and config bytes

ConfigTree is the hierarchical data structure for holding config

Used in: Config, ConfigUpdate

• uint64 version = 1

• map<string, ConfigTree> childs = 2

• map<string, ConfigValue> values = 3

• map<string, ConfigPolicy> policies = 4

• string mod_policy = 5

• map<string, ConfigTreeSchema> childs = 1

• map<string, ConfigValueSchema> values = 2

• map<string, ConfigPolicySchema> policies = 3

ConfigType is an enumeration of possible types for the config. The type field in the config is an int32 for extensibility, but this enum type should generally be used to populate it

• GROUP = 0

  The original and default configuration type, defines parameters for the operation of a group

• RESOURCE = 1

  Defines a set of resource names, and their mapping to policies which restrict access to those resources

ConfigUpdate is used to submit a subset of config and to have the consenter apply to Config it is always submitted inside a ConfigUpdateEnvelope which allows the addition of signatures resulting in a new total configuration. The update is applied as follows: 1. The versions from all of the elements in the read_set is verified against the versions in the existing config. If there is a mismatch in the read versions, then the config update fails and is rejected. 2. Any elements in the write_set with the same version as the read_set are ignored. 3. The corresponding mod_policy for every remaining element in the write_set is collected. 4. Each policy is checked against the signatures from the ConfigUpdateEnvelope, any failing to verify are rejected 5. The write_set is applied to the Config and the ConfigTreeSchema verifies that the updates were legal

• string group_id = 1

  Which group this config update is for

• optional ConfigTree read_set = 2

  ReadSet explicitly lists the portion of the config which was read, this should be sparse with only Version set

• optional ConfigTree write_set = 3

  WriteSet lists the portion of the config which was written, this should included updated Versions

• int32 type = 4

  The type of config this update is intended for (usually a value from ConfigType enum) , must match the type in the Config message

• map<string, bytes> isolated_data = 5

  Data which is not to be reflected in the resulting Config, but is still needed for some other purpose. For instance, rscc_seed_data

• bytes config_update = 1

  A marshaled ConfigUpdate structure

• repeated ConfigSignature signatures = 2

  Signatures over the config_update

ConfigValue represents an individual piece of config data

Used in: ConfigTree

• uint64 version = 1

• bytes value = 2

• string mod_policy = 3

Used in: ConfigTreeSchema

(message has no fields)

ConsenterAddresses is encoded into the configuration transaction as a configuration item of type Chain with a Key of "ConsenterAddresses" and a Value of ConsenterAddresses as marshaled protobuf bytes

• repeated string addresses = 1

Consortium represents the consortium context in which the group was created

• string name = 1

Envelope wraps a Payload with a signature so that the message may be authenticated

Used as request type in: consenter.AtomicBroadcast.Broadcast, consenter.AtomicBroadcast.Deliver, protos.Deliver.Deliver, protos.Deliver.DeliverFiltered

Used as field type in: ConfigEnvelope, protos.ProcessedTransaction

• bytes payload = 1

  A marshaled Payload

• bytes signature = 2

  A signature by the creator specified in the Payload header

Header is a generic replay prevention and identity message to include in a signed payload

• int32 type = 1

  Header types 0-10000 are reserved and defined by HeaderType

• int32 version = 2

  Version indicates message protocol version

• optional google.protobuf.Timestamp timestamp = 3

  Timestamp is the local time when the message was created by the sender

• string group_id = 4

  Identifier of the group this message is bound for

• string tx_id = 5

  An unique identifier that is used end-to-end. - set by higher layers such as end user or SDK - passed to the endorser (which will check for uniqueness) - as the header is passed along unchanged, it will be be retrieved by the committer (uniqueness check here as well) - to be stored in the ledger

• uint64 epoch = 6

  The epoch in which this header was generated, where epoch is defined based on block height Epoch in which the response has been generated. This field identifies a logical window of time. A proposal response is accepted by a node only if two conditions hold: 1. the epoch specified in the message is the current epoch 2. this message has been only seen once during this epoch (i.e. it hasn't been replayed)

• bytes extension = 7

  Extension that may be attached based on the header type

• bytes tls_cert_hash = 8

  If mutual TLS is employed, this represents the hash of the client's TLS certificate

HashingAlgorithm is encoded into the configuration transaction as a configuration item of type Chain with a Key of "HashingAlgorithm" and a Value of HashingAlgorithm as marshaled protobuf bytes

• string name = 1

  Currently supported algorithms are: SHAKE256

Used in: Payload

• bytes group_header = 1

• bytes signature_header = 2

Used in: protos.FilteredTransaction

• MESSAGE = 0

  Used for messages which are signed but opaque

• CONFIG = 1

  Used for messages which express the group config

• CONFIG_UPDATE = 2

  Used for transactions which update the group config

• ENDORSER_TRANSACTION = 3

  Used by the SDK to submit endorser based transactions

• CONSENTER_TRANSACTION = 4

  Used internally by the consenter for management

• DELIVER_SEEK_INFO = 5

  Used as the type for Envelope messages submitted to instruct the Deliver API to seek

• SMART_CONTRACT_PACKAGE = 6

  Used for packaging smart contract artifacts for install

• NODE_RESOURCE_UPDATE = 7

  Used for encoding updates to the node resource configuration

ImplicitMetaPolicy is a policy type which depends on the hierarchical nature of the configuration It is implicit because the rule is generate implicitly based on the number of sub policies It is meta because it depends only on the result of other policies When evaluated, this policy iterates over all immediate child sub-groups, retrieves the policy of name sub_policy, evaluates the collection and applies the rule. For example, with 4 sub-groups, and a policy name of "foo", ImplicitMetaPolicy retrieves each sub-group, retrieves policy "foo" for each subgroup, evaluates it, and, in the case of ANY 1 satisfied is sufficient, ALL would require 4 signatures, and MAJORITY would require 3 signatures.

• string sub_policy = 1

• ImplicitMetaPolicy.Rule rule = 2

Used in: ImplicitMetaPolicy

• ANY = 0

  Requires any of the sub-policies be satisfied, if no sub-policies exist, always returns true

• ALL = 1

  Requires all of the sub-policies be satisfied

• MAJORITY = 2

  Requires a strict majority (greater than half) of the sub-policies be satisfied

LastConfig is the encoded value for the Metadata message which is encoded in the LAST_CONFIGURATION block metadata index

• uint64 index = 1

MSPPrincipal aims to represent an MSP-centric set of identities. In particular, this structure allows for definition of - a group of identities that are member of the same MSP - a group of identities that are member of the same organization unit in the same MSP - a group of identities that are administering a specific MSP - a specific identity Expressing these groups is done given two fields of the fields below - Classification, that defines the type of classification of identities in an MSP this principal would be defined on; Classification can take three values: (i) ByMSPRole: that represents a classification of identities within MSP based on one of the two pre-defined MSP rules, "member" and "admin" (ii) ByOrganizationUnit: that represents a classification of identities within MSP based on the organization unit an identity belongs to (iii)ByIdentity that denotes that MSPPrincipal is mapped to a single identity/certificate; this would mean that the MSPPrincipalGetter bytes message

Used in: SignaturePolicyEnvelope

• MSPPrincipal.Classification principal_classification = 1

  Classification describes the way that one should process MSPPrincipalGetter. An Classification value of "ByOrganizationUnit" reflects that "MSPPrincipalGetter" contains the name of an organization this MSP handles. A Classification value "ByIdentity" means that "MSPPrincipalGetter" contains a specific identity. Default value denotes that MSPPrincipalGetter contains one of the groups by default supported by all MSPs ("admin" or "member").

• bytes principal = 2

  MSPPrincipalGetter completes the policy principal definition. For the default principal types, MSPPrincipalGetter can be either "Admin" or "Member". For the ByOrganizationUnit/ByIdentity values of Classification, PolicyPrincipal acquires its value from an organization unit or identity, respectively.

Used in: MSPPrincipal

• ROLE = 0

  Represents the one of the dedicated MSP roles, the

• ORGANIZATION_UNIT = 1

  one of a member of MSP network, and the one of an administrator of an MSP network

  Denotes a finer grained (affiliation-based)

• IDENTITY = 2

  groupping of entities, per MSP affiliation E.g., this can well be represented by an MSP's Organization unit

  Denotes a principal that consists of a single

MSPRole governs the organization of the MSPPrincipalGetter field of an MSPPrincipal when it aims to define one of the two dedicated roles within an MSP: Admin and Members.

• string msp_identifier = 1

  MSPIdentifier represents the identifier of the MSP this principal refers to

• MSPRole.MSPRoleType role = 2

  MSPRoleType defines which of the available, pre-defined MSP-roles an identiy should posess inside the MSP with identifier MSPidentifier

Used in: MSPRole

• MEMBER = 0

  Represents an MSP Member

• ADMIN = 1

  Represents an MSP Admin

• CLIENT = 2

  Represents an MSP Client

• NODE = 3

  Represents an MSP Node

Metadata is a common structure to be used to encode block metadata

• bytes value = 1

• repeated MetadataSignature signatures = 2

Used in: Metadata

• bytes signature_header = 1

  An encoded SignatureHeader

• bytes signature = 2

  The signature over the concatenation of the Metadata value bytes, signatureHeader, and block header

OrganizationUnit governs the organization of the MSPPrincipalGetter field of a policy principal when a specific organization unity members are to be defined within a policy principal.

• string msp_identifier = 1

  MSPIdentifier represents the identifier of the MSP this organization unit refers to

• string organizational_unit_identifier = 2

  OrganizationUnitIdentifier defines the organizational unit under the MSP identified with MSPIdentifier

• bytes certifiers_identifier = 3

  CertifiersIdentifier is the hash of certificates chain of trust related to this organizational unit

Payload is the message contents (and header to allow for signing)

• optional Header header = 1

  Header is included to provide identity and prevent replay

• bytes data = 2

  Data, the encoding of which is defined by the type in the header

Policy expresses a policy which the consenter can evaluate, because there has been some desire expressed to support multiple policy engines, this is typed as a oneof for now

Used in: ConfigPolicy

• int32 type = 1

  For outside implementors, consider the first 1000 types reserved, otherwise one of PolicyType

• bytes value = 2

• UNKNOWN = 0

  Reserved to check for proper initialization

• SIGNATURE = 1

• MSP = 2

• IMPLICIT_META = 3

• bytes creator = 1

  Creator of the message, a marshaled msp.SerializedIdentity

• bytes nonce = 2

  Arbitrary number that may only be used once. Can be used to detect replay attacks.

• string nodeid = 3

SignaturePolicy is a recursive message structure which defines a featherweight DSL for describing policies which are more complicated than 'exactly this signature'. The NOutOf operator is sufficent to express AND as well as OR, as well as of course N out of the following M policies SignedBy implies that the signature is from a valid certificate which is signed by the trusted authority specified in the bytes. This will be the certificate itself for a self-signed certificate and will be the CA for more traditional certificates

Used in: SignaturePolicy.NOutOf, SignaturePolicyEnvelope

• oneof Type

  • int32 signed_by = 1

  • SignaturePolicy.NOutOf n_out_of = 2

Used in: SignaturePolicy

• int32 n = 1

• repeated SignaturePolicy rules = 2

SignaturePolicyEnvelope wraps a SignaturePolicy and includes a version for future enhancements

Used in: CollectionPolicyConfig

• int32 version = 1

• optional SignaturePolicy rule = 2

• repeated MSPPrincipal identities = 3

StaticCollectionConfig constitutes the configuration parameters of a static collection object. Static collections are collections that are known at chaincode instantiation time, and that cannot be changed. Dynamic collections are deferred.

Used in: CollectionConfig

• string name = 1

  the name of the collection inside the denoted chaincode

• optional CollectionPolicyConfig member_orgs_policy = 2

  a reference to a policy residing / managed in the config block to define which orgs have access to this collection’s private data

• int32 required_peer_count = 3

  The minimum number of peers private data will be sent to upon endorsement. The endorsement would fail if dissemination to at least this number of peers is not achieved.

• int32 maximum_peer_count = 4

  The maximum number of peers that private data will be sent to upon endorsement. This number has to be bigger than required_peer_count.

These status codes are intended to resemble selected HTTP status codes

Used in: consenter.BroadcastResponse, consenter.DeliverResponse, protos.DeliverResponse

• UNKNOWN = 0

• SUCCESS = 200

• BAD_REQUEST = 400

• FORBIDDEN = 403

• NOT_FOUND = 404

• REQUEST_ENTITY_TOO_LARGE = 413

• INTERNAL_SERVER_ERROR = 500

• NOT_IMPLEMENTED = 501

• SERVICE_UNAVAILABLE = 503