User Tools

Site Tools

*This is an on-going work from the Protocol Workgroup.*

### Blockchain Protocol

#### Abstract This document specifies the proposed blockchain protocol for the Hyperledger project.

The specification outlines the architecture of the protocol and its functionality, including transport, encode, message structures, message flows, message processing instructions, message formats, and semantics.

#### Copyright Notice

#### Table of Contents

#### 1. Introduction

#### 1.1. Terminology

#### 1.2. Example of Transaction Flow - Jeremy Sevareid

The following excerpt is taken from the Post-Trade use case being developed by the Requirements Working Group for a type of post-trade settlement in capital markets. The URL is

Delivery versus payment, or DvP, is a common form of settlement for securities trading. During the settlement process, obligations incurred during the trading process are met. Specifically, the physical delivery and/or book-keeping transfers of securities and of cash agreed to during trading occurs.

In this example, Alice and Bob have previously agreed to trade securities for cash. They have agreed to settle the trade via DvP on the ledger. They have put these items of value–the securities and the cash–onto the ledger through Trent, a mutually-trusted third-party custodian.

User |As a . . . |Wants to . . . |Because . . . | ——–|—————|———————–|———————–| Alice |Seller of Securities |Sell securities for cash in a contingent all-or-nothing exchange |She wants to minimize the risk that she delivers the agreed-upon securities into Bob's account but he fails to transfer the agreed-upon cash into her account Bob |Buyer of Securities |Buy securities with cash in a contingent all-or-nothing exchange |He wants to minimize the risk that he pays the agreed-upon cash into Alice's account but she fails to deliver the agreed-upon securities into his account Trent |Custodian of Cash and Securities |Provide all-or-nothing exchange of securities and cash if and only if matching delivery and payment instructions are received |Alice and Bob need a trusted third party to act as a settlement intermediary to minimize Alice's cash payment risk and Bob's securities delivery risk

~~~ Steps 1,2 Alice and Bob fund their on-ledger locations through DvPs that Trent attests to. Step 3 The all-or-nothing exchange of Alice's on-ledger securities for Bob's on-ledger cash occurs. Steps 4,5 Alice and Bob withdraw their on-ledger locations through DvPs that Trent attests to. ~~~

Each DvP has two legs. Each leg is a transfer of a quantity of cash or securities from one location to another. The two legs of a single DvP are processed as one - a single, indivisible atomic step. If and only if both legs are valid, do they go through. If either is invalid, then neither is applied.

Step |Leg1_Source_Location |Leg1_Type |Leg1_Quantity |Leg1_Destination_Location |Leg2_Source_Location |Leg2_Type |Leg2_Quantity |Leg2_Destination_Location |Signatories_to_Transfer –|–|–|–|–|–|–|–|–|– 1 |Foreign Key of Bob's Off-Ledger Cash Account with Trent |Foreign Key of Bob's Off-Ledger Funding Transaction with Trent |Foreign Key of Bob's Off-Ledger Quantity |OFF_LEDGER_LOCATION_FLAG |OFF_LEDGER_LOCATION_FLAG |USD |10,000,000.00 |Bob's_On-Ledger_Location |Bob, Trent 2 |Foreign Key of Alice's Off-Ledger Securities Account with Trent |Foreign Key of Alice's Off-Ledger Funding Transaction with Trent |Foreign Key of Alice's Off-Ledger Quantity |OFF_LEDGER_LOCATION_FLAG |OFF_LEDGER_LOCATION_FLAG |T-BILL |10 |Alice's_On-Ledger_Location |Alice, Trent 3 |Alice's_On-Ledger_Location |T-BILL |10 |Bob's_On-Ledger_Location |Bob's_On-Ledger_Location |USD |10,000,000.00 |Alice's_on-ledger_location |Alice, Bob, Trent 4 |Alice's_On-Ledger_location |USD |10,000,000.00 |OFF_LEDGER_LOCATION_FLAG |OFF_LEDGER_LOCATION_FLAG |OFF_LEDGER_TYPE_FLAG |10,000,000.00 |Foreign Key of Alice's Cash Account with Trent |Alice, Trent 5 |Bob's_On-Ledger_Location |T-BILL |10 |OFF_LEDGER_LOCATION_FLAG |OFF_LEDGER_LOCATION_FLAG |OFF_LEDGER_TYPE_FLAG |10 |Foreign Key of Bob's |Off-Ledger Securities Account with Trent |Bob, Trent

#### 1.3 Proposed Transaction Flow - Andrew Bransford Brown

This conforms to contract law and will describe any transaction in any form of value, with any number of equilateral participants.

Selling stock:

CommerceID |EventType |Description —————|————–|———— MyID |Offer |1000 shares of IBM stock MyID |Terms |2000 Great Britain Pounds

Buying stock:

CommerceID |EventType |Description —————|————–|———— MyID |Offer |2000 Great Britain Pounds MyID |Terms |1000 shares of IBM stock

NOTE: the structure of both the Selling and Buying is identical.

The Offer & Terms are separate events in what I term a “transaction stack”. A legal offer does not exist until the Terms event. Alternative “Terms” are allowed, to accept other forms of value.

A matching Offer:

CommerceID |EventType |Description —————|————–|———— YourID |Offer |2000 Great Britain Pounds Your |Terms |1000 shares of IBM stock OR| YourID | Accept

That creates a legal binding contract.

CommerceID |EventType |Description —————|————–|———— MyID |Deliver |1000 shares of IBM stock YourID |Deliver |2000 Great Britain Pounds

This completes the contract, including negotiation and settlement. It's an audit trail and a complete description of the transaction. The events can easily be rolled up into any accounting structure or displayed as a real-time exchange with Bid/Ask.

One UI for this transaction flow could be called a Contract Scripting Language (CSL).

An example of a 3-party equilateral contract:

Scenario: ~~~ Andrew has Dollars and wants Yen. Matthew has British Pounds and wants Dollars. Since we have non-matching value, we advertise on Bank of England's settlement book and also market it on Forex. Bank of Japan sees the opportunity and translates the value. ~~~

Contract script:

CommerceID |EventType |Description —————|————–|———— Andrew |Offer |2,000 USD Andrew |Terms |200,000 JPY Computer |Notice |“This is a legal binding offer from Andrew.”

Matthew |Offer |1,500 GBP Matthew |Terms |2,000 USD Computer |Notice |“This is a legal binding offer from Matthew.”

Andrew |Terms |210,000 JPY Andrew |Counter Computer |Notice |“Terms-value change from Andrew.”

Matthew |Terms-Advertise Bank of England Matthew |Counter

Andrew |Terms-Advertise Forex Andrew |Terms-Advertise Bank of England Andrew |Counter

Bank of Japan |Offer |210,000 JPY Bank of Japan |Terms |1,500 GBP Computer |Notice |“This is a 3-party equilateral contract between Andrew, Matthew, and Bank of Japan.”

Andrew |Deliver |2,000 USD Matthew |Deliver |1,500 GBP Bank of Japan |Deliver |210,000 JPY Computer |Notice |“Contract complete”

Andrew |Complete Matthew |Complete Bank of Japan |Complete

NOTE: Computer is performing as the lawyer above. This introduces the idea of Computer as a legal entity. If one creates a contract creating a currency as above, the Computer enters into a contract with a Human with specific Terms, such as the Human must keep the computer running and the Computer must keep the ledger.

#### 2. Protocol Architecture

##### Layers

It is critical to identify separation of duties among layers. This will assist with, for example, evaluating whether or not an alternative transport might be possible such as message queues (MQ), publish-subscribe (pub-sub) or multi-cast over UDP.

###### Application

Application layer is responsible for defining business level interactions required to implement a particular use case. It would, generally, describe protocols for multiple parties to leverage the blockchain without explicitly talking about the communication and storage needs. Term `transaction` is this context refers to business transactions between the specified participants.

These protocols will vary depending on a use case and are out of scope for this document.

###### Messaging

Messaging portion of the specification should include both message flows and message definitions (fields and types). These are the messages required to enable application level transactions within the blockchain. Term `transaction` is traditionally used in this context to describe an entry on a ledger or a state machine transition.

Depending on the definition language we choose, it may also specify encoding (e.g. if protobuf format is used). Eventually, we may consider using a more formal definition language for this, such as ABNF (RFC5234).

###### Encoding

Message encoding specification should describe unambiguously the types of data used in all messages. It may also define the format of the data on the wire, assuming this format is not dictated by the choice of transport.

###### Transport

Transport is responsible for communicating encoded messages among the participants. Communication may be over: network, inter-process, inter-thread. Some transports require specific encoding to be used, e.g. gRPC uses protobuf.

##### Types of Errors

- gRPC-style

#### 2.1. Messaging Model - Request/Response - Streaming - Broadcast

#### 2.2. State Machine - Hello → Transfer → Operation → Terminate

#### 2.3. Message Flows - Normal - Error

#### 3. Protocol Specification

#### 3.1. Overall Structure - header, payload, extension (application or implementation specific area)

#### 3.2. Message Types - Handshake

~~~ message Hello {

  // ID of the peer
  bytes id = 1;
  // Address of the peer
  bytes address = 2;
  // Type of peer
  bytes type = 3;
  // PKI ID of peer
  bytes pkiID = 4;
  // Current block hash
  bytes currentBlockHash = 5;
  // Current chain height
  bytes chainHeight = 6;

} ~~~

- Synchronization - Transaction ~~~ A proposal for a Transaction message Proposal { Signing of hash of all other properties in the message

  bytes signature = 1;
  // A version for identifying the format of this transaction
  int32 version = 2;
  // The ID of the peer that submitted this proposal
  bytes peerID = 3;
  // An ID indicating the originator of this proposal
  bytes onBehalfOf = 4;
  // Indicate delivery address of this transaction, such as a contract, account, endorser, etc.
  bytes deliverTo = 5;
  // The payload of the proposal
  bytes payload = 6;
  // Script that is associated with the proposal
  bytes script = 7;
  // Simulation results of this proposal
  bytes simulationResults = 8;
  // Certificate associated with this proposal
  bytes certificate = 9;
  // Nonce for this proposal
  bytes nonce = 10;


An endorsement of a Proposal message Endorsement { Signing of the Proposal hash

  bytes signature = 1;


The transaction to be sent to consensus message Transaction { Signing of hash of all other properties in the message

  bytes signature = 1;
  // Proposal
  Proposal proposal = 2;
  // The endorsed proposals
  repeated Endorsement endorsements = 3;

} ~~~ - Consensus - Status codes

#### 3.3. Requests and Responses - For each message types, describe structure of request and response

#### 3.4. Encoding and Operation - Establish connection - Encode/decode message structures - Example for each interaction

#### 4. Data and Identity Protection for Entities

#### 5. Guidelines for Extending

#### 6. REST API

A basic common REST API between Hyperledger projects will help to facilitate the ability to build common tools and user interfaces.

TODO - define responses

- /chain - /block/<number> - /transaction/<id> - /statistics - /network

#### 7. References

- Protocol implementation. Binh Q Nguyen, Elli Androulaki, Angelo De Caro, Sheehan Anderson, Manish Sethi, Thorsten Kramp, Alessandro Sorniotti, Marko Vukolic, Florian Simon Schubert, Jason K Yellick, Konstantinos Christidis, Srinivasan Muralidharan, Anna D Derbakova, Dulce Ponceleon, David Kravitz, Diego Masini. (Accessed 2016-07-12). “This document is the protocol specification for a permissioned blockchain implementation for industry use-cases. It is not intended to be a complete explanation of the implementation, but rather a description of the interfaces and relationships between components in the system and the application.”

- “Protocol buffers are a language-neutral, platform-neutral extensible mechanism for serializing structured data.” (Accessed 2016-06-28).

- “Protocol Buffers Version 3 Language Specification.” (Accessed 2016-06-28).

- Suggested reference model for semantics and definitions of types of errors - “Error Handling.” (Accessed 2016-06-28).

- “IP multicast.” From Wikipedia, the free encyclopedia. (Accessed 2016-06-28).

- “Augmented BNF for Syntax Specifications: ABNF”. Crocker & Overell. RFC 5234. (Accessed 2016-07-05). Potentially useful for formal grammar syntax definitions meant to minimize potential for ambiguity.

- “ISO 15022 Data Field Dictionary” International Organization for Standardization. (Accessed 2016-07-05). Potentially useful example for semantic meaning of business layer message fields.

- “Technical Resources / Specifications” FIX Trading Community. Accessed 2016-07-05. Potentially useful example for splitting out of protocol layers (e.g., application, presentation, session) and for concerns (e.g., possible duplicates/resends) and for semantic meanings for business layer messages.

- “Digital Currency/Blockchain Working Group”. Fix Trading Community. (Accessed 2016-07-05). “The mission of FIX Trading Digital Currency Working Group is to identify, analyze and define use cases and integration points for digital currency and distributed ledger technologies across the spectrum of capital markets requirements, and recommend best practices for FIX implementation and usage of this emerging technology in financial markets.”

groups/protocol/ · Last modified: 2017/05/02 20:16 by Tracy Kuhrt