Protocol Documentation

Protocol Documentation

Table of Contents

• common_messages.proto
  • TransactionContext
• contract_messages.proto
  • InvokeTransactionRequest
  • InvokeTransactionRequest.TransientArgsEntry
  • InvokeTransactionResponse
• contract_services.proto
  • ContractService
• ledger_messages.proto
  • Collection
  • CreateStateRequest
  • CreateStateResponse
  • EndorsementPolicy
  • EndorsementPrincipal
  • EndorsementRule
  • ExistsStateRequest
  • ExistsStateResponse
  • GetEndorsementPolicyRequest
  • GetEndorsementPolicyResponse
  • GetHashRequest
  • GetHashResponse
  • GetStatesRequest
  • GetStatesResponse
  • KeyRangeQuery
  • ReadStateRequest
  • ReadStateResponse
  • RichQuery
  • SetEndorsementPolicyRequest
  • SetEndorsementPolicyResponse
  • State
  • UpdateStateRequest

  • UpdateStateResponse

  • EndorsementPrincipal.Role
• ledger_services.proto
  • LedgerService
• Scalar Value Types

Top

common_messages.proto

Common messages.

TransactionContext

Provides the context necessary for interacting with the ledger.

Field	Type	Label	Description
channel_id	string		The channel which the transaction is on
transaction_id	string		Identifier for the transaction.

Top

contract_messages.proto

Contract related messages.

InvokeTransactionRequest

Request message for an InvokeTransaction call.

Field	Type	Label	Description
context	TransactionContext		Context the transaction will be invoked with.
transaction_name	string		The name of the transaction to invoke.
args	bytes	repeated	Input parameters for the transaction.
transient_args	InvokeTransactionRequest.TransientArgsEntry	repeated	Transient data for the transaction.

InvokeTransactionRequest.TransientArgsEntry

Field	Type	Label	Description
key	string
value	bytes

InvokeTransactionResponse

Response message from an InvokeTransaction request.

Field	Type	Label	Description
payload	bytes		Result data from the transaction.

Top

contract_services.proto

Contract related services.

Services are not currently generated however they document what operations are exposed via waPC in the Wasm tech preview.

ContractService

Service for handling calls from peer to contract.

Method Name	Request Type	Response Type	Description
InvokeTransaction	InvokeTransactionRequest	InvokeTransactionResponse	Used to invoke the transaction specified in InvokeTransactionRequest. Returns an InvokeTransactionResponse with the results.

Top

ledger_messages.proto

Ledger related messages.

Collection

A collection is a set of states, with each state holding a business object or data.

Field	Type	Label	Description
name	string		Private collections are identified by name. The default, world state collection, has no name.

CreateStateRequest

Request message for a CreateState call.

Field	Type	Label	Description
context	TransactionContext		Context of the current transaction.
collection	Collection		The collection the state should be created in.
state	State		The new state.

CreateStateResponse

Response message from a CreateState call.

EndorsementPolicy

Field	Type	Label	Description
rule	EndorsementRule

EndorsementPrincipal

Field	Type	Label	Description
msp_id	string
role	EndorsementPrincipal.Role

EndorsementRule

Field	Type	Label	Description
min_endorsements	int32
principals	EndorsementPrincipal	repeated
rules	EndorsementRule	repeated

ExistsStateRequest

Request message for an ExistsState call.

Field	Type	Label	Description
context	TransactionContext		Context of the current transaction.
collection	Collection		The collection to check for the specified state key.
state_key	string		Key of the state to check.

ExistsStateResponse

Response message from a ExistsState call.

Field	Type	Label	Description
exists	bool		True if the specified state exists, and false otherwise.

GetEndorsementPolicyRequest

Request message for a GetEndorsementPolicy call.

Field	Type	Label	Description
context	TransactionContext		Context of the current transaction.
collection	Collection
state_key	string

GetEndorsementPolicyResponse

Response message from a GetEndorsementPolicy call.

Field	Type	Label	Description
policy	EndorsementPolicy

GetHashRequest

Request message for a GetHash call.

Field	Type	Label	Description
context	TransactionContext		Context of the current transaction.
collection	Collection		The collection the state hash should be read from.
state_key	string		Key of the state to hash.

GetHashResponse

Response message from a GetHash call.

Field	Type	Label	Description
hash	bytes		Hash of the requested state.

GetStatesRequest

Request message for a GetStates call.

Field	Type	Label	Description
context	TransactionContext		Context of the current transaction.
collection	Collection		The collection the states should be queried in.
by_key_range	KeyRangeQuery
by_rich_query	RichQuery

GetStatesResponse

Response message from a GetStates call.

Field	Type	Label	Description
states	State	repeated	The requested states.

KeyRangeQuery

Defines a key based query for a GetStatesRequest request. Open ended range queries are supported if the start key and/or end key are not provided.

Field	Type	Label	Description
start_key	string		Start key
end_key	string		End key
page_size	int32		Page size

ReadStateRequest

Request message for a ReadState call.

Field	Type	Label	Description
context	TransactionContext		Context of the current transaction.
collection	Collection		The collection the state should be read from.
state_key	string		Key of the state to read.

ReadStateResponse

Response message from a ReadState call.

Field	Type	Label	Description
state	State		The requested state.

RichQuery

Defines a rich query for a GetStatesRequest request.

SetEndorsementPolicyRequest

Request message for a SetEndorsementPolicy call.

Field	Type	Label	Description
context	TransactionContext		Context of the current transaction.
collection	Collection
state_key	string
policy	EndorsementPolicy

SetEndorsementPolicyResponse

Response message from a SetEndorsementPolicy call.

State

A state holds the value of a business object or data, addressed by a key.

Field	Type	Label	Description
key	string		Key
value	bytes		Value

UpdateStateRequest

Request message for an UpdateState call.

Field	Type	Label	Description
context	TransactionContext		Context of the current transaction.
collection	Collection		The collection the state should be updated in.
state	State		The updated state.

UpdateStateResponse

Response message from an UpdateState call.

EndorsementPrincipal.Role

Name	Number	Description
MEMBER	0
ADMIN	1
CLIENT	2
PEER	3

Top

ledger_services.proto

Ledger related services.

Services are not currently generated however they document what operations are exposed via waPC in the Wasm tech preview.

LedgerService

Service for handling ledger calls from a smart contract.

Method Name	Request Type	Response Type	Description
CreateState	CreateStateRequest	CreateStateResponse	Create a new state in the ledger if it does not exist already.
ReadState	ReadStateRequest	ReadStateResponse	Read a state from the ledger.
UpdateState	UpdateStateRequest	UpdateStateResponse	Update an existing state in the ledger.
ExistsState	ExistsStateRequest	ExistsStateResponse	Check whether a state exists in the ledger.
GetStates	GetStatesRequest	GetStatesResponse stream	Read multiple states from the ledger.
GetHash	GetHashRequest	GetHashResponse	Get the hash of a state in the ledger.
GetEndorsementPolicy	GetEndorsementPolicyRequest	GetEndorsementPolicyResponse stream	Get the endorsement policy for a state in the ledger.
SetEndorsementPolicy	SetEndorsementPolicyRequest	SetEndorsementPolicyResponse stream	Set the endorsement policy for a state in the ledger.

Scalar Value Types

.proto Type	Notes	C++	Java	Python	Go	C#	PHP	Ruby
double		double	double	float	float64	double	float	Float
float		float	float	float	float32	float	float	Float
int32	Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead.	int32	int	int	int32	int	integer	Bignum or Fixnum (as required)
int64	Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead.	int64	long	int/long	int64	long	integer/string	Bignum
uint32	Uses variable-length encoding.	uint32	int	int/long	uint32	uint	integer	Bignum or Fixnum (as required)
uint64	Uses variable-length encoding.	uint64	long	int/long	uint64	ulong	integer/string	Bignum or Fixnum (as required)
sint32	Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s.	int32	int	int	int32	int	integer	Bignum or Fixnum (as required)
sint64	Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s.	int64	long	int/long	int64	long	integer/string	Bignum
fixed32	Always four bytes. More efficient than uint32 if values are often greater than 2^28.	uint32	int	int	uint32	uint	integer	Bignum or Fixnum (as required)
fixed64	Always eight bytes. More efficient than uint64 if values are often greater than 2^56.	uint64	long	int/long	uint64	ulong	integer/string	Bignum
sfixed32	Always four bytes.	int32	int	int	int32	int	integer	Bignum or Fixnum (as required)
sfixed64	Always eight bytes.	int64	long	int/long	int64	long	integer/string	Bignum
bool		bool	boolean	boolean	bool	bool	boolean	TrueClass/FalseClass
string	A string must always contain UTF-8 encoded or 7-bit ASCII text.	string	String	str/unicode	string	string	string	String (UTF-8)
bytes	May contain any arbitrary sequence of bytes.	string	ByteString	str	[]byte	ByteString	string	String (ASCII-8BIT)