<commit_before>Architecture Explained
======================

The Hyperledger Fabric architecture delivers the following advantages:

-  **Chaincode trust flexibility.** The architecture separates *trust
   assumptions* for chaincodes (blockchain applications) from trust
   assumptions for ordering. In other words, the ordering service may be
   provided by one set of nodes (orderers) and tolerate some of them to
   fail or misbehave, and the endorsers may be different for each
   chaincode.

-  **Scalability.** As the endorser nodes responsible for particular
   chaincode are orthogonal to the orderers, the system may *scale*
   better than if these functions were done by the same nodes. In
   particular, this results when different chaincodes specify disjoint
   endorsers, which introduces a partitioning of chaincodes between
   endorsers and allows parallel chaincode execution (endorsement).
   Besides, chaincode execution, which can potentially be costly, is
   removed from the critical path of the ordering service.

-  **Confidentiality.** The architecture facilitates deployment of
   chaincodes that have *confidentiality* requirements with respect to
   the content and state updates of its transactions.

-  **Consensus modularity.** The architecture is *modular* and allows
   pluggable consensus (i.e., ordering service) implementations.

**Part I: Elements of the architecture relevant to Hyperledger Fabric
v1**

1. System architecture
2. Basic workflow of transaction endorsement
3. Endorsement policies

   **Part II: Post-v1 elements of the architecture**

4. Ledger checkpointing (pruning)

1. System architecture
----------------------

The blockchain is a distributed system consisting of many nodes that
communicate with each other. The blockchain runs programs called
chaincode, holds state and ledger data, and executes transactions. The
chaincode is the central element as transactions are operations invoked
on the chaincode. Transactions have to be "endorsed" and only endorsed
transactions may be committed and have an effect on the state. There may
exist one or more special chaincodes for management functions and
parameters, collectively called *system chaincodes*.

1.1. Transactions
~~~~~~~~~~~~~~~~~

Transactions may be of two types:

-  *Deploy transactions* create new chaincode and take a program as
   parameter. When a deploy transaction executes successfully, the
   chaincode has been installed "on" the blockchain.

-  *Invoke transactions* perform an operation in the context of
   previously deployed chaincode. An invoke transaction refers to a
   chaincode and to one of its provided functions. When successful, the
   chaincode executes the specified function - which may involve
   modifying the corresponding state, and returning an output.

As described later, deploy transactions are special cases of invoke
transactions, where a deploy transaction that creates new chaincode,
corresponds to an invoke transaction on a system chaincode.

**Remark:** *This document currently assumes that a transaction either
creates new chaincode or invokes an operation provided by *one* already
deployed chaincode. This document does not yet describe: a)
optimizations for query (read-only) transactions (included in v1), b)
support for cross-chaincode transactions (post-v1 feature).*

1.2. Blockchain datastructures
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

1.2.1. State
^^^^^^^^^^^^

The latest state of the blockchain (or, simply, *state*) is modeled as a
versioned key-value store (KVS), where keys are names and values are
arbitrary blobs. These entries are manipulated by the chaincodes
(applications) running on the blockchain through ``put`` and ``get``
KVS-operations. The state is stored persistently and updates to the
state are logged. Notice that versioned KVS is adopted as state model,
an implementation may use actual KVSs, but also RDBMSs or any other
solution.

More formally, state ``s`` is modeled as an element of a mapping
``K -> (V X N)``, where:

-  ``K`` is a set of keys
-  ``V`` is a set of values
-  ``N`` is an infinite ordered set of version numbers. Injective
   function ``next: N -> N`` takes an element of ``N`` and returns the
   next version number.

Both ``V`` and ``N`` contain a special element |falsum| (empty type), which is
in case of ``N`` the lowest element. Initially all keys are mapped to
(|falsum|, |falsum|). For ``s(k)=(v,ver)`` we denote ``v`` by ``s(k).value``,
and ``ver`` by ``s(k).version``.

.. |falsum| unicode:: U+22A5
.. |in| unicode:: U+2208

KVS operations are modeled as follows:

-  ``put(k,v)`` for ``k`` |in| ``K`` and ``v`` |in| ``V``, takes the blockchain
   state ``s`` and changes it to ``s'`` such that
   ``s'(k)=(v,next(s(k).version))`` with ``s'(k')=s(k')`` for all
   ``k'!=k``.
-  ``get(k)`` returns ``s(k)``.

State is maintained by peers, but not by orderers and clients.

**State partitioning.** Keys in the KVS can be recognized from their
name to belong to a particular chaincode, in the sense that only
transaction of a certain chaincode may modify the keys belonging to this
chaincode. In principle, any chaincode can read the keys belonging to
other chaincodes. *Support for cross-chaincode transactions, that modify
the state belonging to two or more chaincodes is a post-v1 feature.*

1.2.2 Ledger
^^^^^^^^^^^^

Ledger provides a verifiable history of all successful state changes (we
talk about *valid* transactions) and unsuccessful attempts to change
state (we talk about *invalid* transactions), occurring during the
operation of the system.

Ledger is constructed by the ordering service (see Sec 1.3.3) as a
totally ordered hashchain of *blocks* of (valid or invalid)
transactions. The hashchain imposes the total order of blocks in a
ledger and each block contains an array of totally ordered transactions.
This imposes total order across all transactions.

Ledger is kept at all peers and, optionally, at a subset of orderers. In
the context of an orderer we refer to the Ledger as to
``OrdererLedger``, whereas in the context of a peer we refer to the
ledger as to ``PeerLedger``. ``PeerLedger`` differs from the
``OrdererLedger`` in that peers locally maintain a bitmask that tells
apart valid transactions from invalid ones (see Section XX for more
details).

Peers may prune ``PeerLedger`` as described in Section XX (post-v1
feature). Orderers maintain ``OrdererLedger`` for fault-tolerance and
availability (of the ``PeerLedger``) and may decide to prune it at
anytime, provided that properties of the ordering service (see Sec.
1.3.3) are maintained.

The ledger allows peers to replay the history of all transactions and to
reconstruct the state. Therefore, state as described in Sec 1.2.1 is an
optional datastructure.

1.3. Nodes
~~~~~~~~~~

Nodes are the communication entities of the blockchain. A "node" is only
a logical function in the sense that multiple nodes of different types
can run on the same physical server. What counts is how nodes are
grouped in "trust domains" and associated to logical entities that
control them.

There are three types of nodes:

1. **Client** or **submitting-client**: a client that submits an actual
   transaction-invocation to the endorsers, and broadcasts
   transaction-proposals to the ordering service.

2. **Peer**: a node that commits transactions and maintains the state
   and a copy of the ledger (see Sec, 1.2). Besides, peers can have a
   special **endorser** role.

3. **Ordering-service-node** or **orderer**: a node running the
   communication service that implements a delivery guarantee, such as
   atomic or total order broadcast.

The types of nodes are explained next in more detail.

1.3.1. Client
^^^^^^^^^^^^^

The client represents the entity that acts on behalf of an end-user. It
must connect to a peer for communicating with the blockchain. The client
may connect to any peer of its choice. Clients create and thereby invoke
transactions.

As detailed in Section 2, clients communicate with both peers and the
ordering service.

1.3.2. Peer
^^^^^^^^^^^

A peer receives ordered state updates in the form of *blocks* from the
ordering service and maintain the state and the ledger.

Peers can additionally take up a special role of an **endorsing peer**,
or an **endorser**. The special function of an *endorsing peer* occurs
with respect to a particular chaincode and consists in *endorsing* a
transaction before it is committed. Every chaincode may specify an
*endorsement policy* that may refer to a set of endorsing peers. The
policy defines the necessary and sufficient conditions for a valid
transaction endorsement (typically a set of endorsers' signatures), as
described later in Sections 2 and 3. In the special case of deploy
transactions that install new chaincode the (deployment) endorsement
policy is specified as an endorsement policy of the system chaincode.

1.3.3. Ordering service nodes (Orderers)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

The *orderers* form the *ordering service*, i.e., a communication fabric
that provides delivery guarantees. The ordering service can be
implemented in different ways: ranging from a centralized service (used
e.g., in development and testing) to distributed protocols that target
different network and node fault models.

Ordering service provides a shared *communication channel* to clients
and peers, offering a broadcast service for messages containing
transactions. Clients connect to the channel and may broadcast messages
on the channel which are then delivered to all peers. The channel
supports *atomic* delivery of all messages, that is, message
communication with total-order delivery and (implementation specific)
reliability. In other words, the channel outputs the same messages to
all connected peers and outputs them to all peers in the same logical
order. This atomic communication guarantee is also called *total-order
broadcast*, *atomic broadcast*, or *consensus* in the context of
distributed systems. The communicated messages are the candidate
transactions for inclusion in the blockchain state.

**Partitioning (ordering service channels).** Ordering service may
support multiple *channels* similar to the *topics* of a
publish/subscribe (pub/sub) messaging system. Clients can connect to a
given channel and can then send messages and obtain the messages that
arrive. Channels can be thought of as partitions - clients connecting to
one channel are unaware of the existence of other channels, but clients
may connect to multiple channels. Even though some ordering service
implementations included with Hyperledger Fabric support multiple
channels, for simplicity of presentation, in the rest of this
document, we assume ordering service consists of a single channel/topic.

**Ordering service API.** Peers connect to the channel provided by the
ordering service, via the interface provided by the ordering service.
The ordering service API consists of two basic operations (more
generally *asynchronous events*):

**TODO** add the part of the API for fetching particular blocks under
client/peer specified sequence numbers.

-  ``broadcast(blob)``: a client calls this to broadcast an arbitrary
   message ``blob`` for dissemination over the channel. This is also
   called ``request(blob)`` in the BFT context, when sending a request
   to a service.

-  ``deliver(seqno, prevhash, blob)``: the ordering service calls this
   on the peer to deliver the message ``blob`` with the specified
   non-negative integer sequence number (``seqno``) and hash of the most
   recently delivered blob (``prevhash``). In other words, it is an
   output event from the ordering service. ``deliver()`` is also
   sometimes called ``notify()`` in pub-sub systems or ``commit()`` in
   BFT systems.

**Ledger and block formation.** The ledger (see also Sec. 1.2.2)
contains all data output by the ordering service. In a nutshell, it is a
sequence of ``deliver(seqno, prevhash, blob)`` events, which form a hash
chain according to the computation of ``prevhash`` described before.

Most of the time, for efficiency reasons, instead of outputting
individual transactions (blobs), the ordering service will group (batch)
the blobs and output *blocks* within a single ``deliver`` event. In this
case, the ordering service must impose and convey a deterministic
ordering of the blobs within each block. The number of blobs in a block
may be chosen dynamically by an ordering service implementation.

In the following, for ease of presentation, we define ordering service
properties (rest of this subsection) and explain the workflow of
transaction endorsement (Section 2) assuming one blob per ``deliver``
event. These are easily extended to blocks, assuming that a ``deliver``
event for a block corresponds to a sequence of individual ``deliver``
events for each blob within a block, according to the above mentioned
deterministic ordering of blobs within a blocs.

**Ordering service properties**

The guarantees of the ordering service (or atomic-broadcast channel)
stipulate what happens to a broadcasted message and what relations exist
among delivered messages. These guarantees are as follows:

1. **Safety (consistency guarantees)**: As long as peers are connected
   for sufficiently long periods of time to the channel (they can
   disconnect or crash, but will restart and reconnect), they will see
   an *identical* series of delivered ``(seqno, prevhash, blob)``
   messages. This means the outputs (``deliver()`` events) occur in the
   *same order* on all peers and according to sequence number and carry
   *identical content* (``blob`` and ``prevhash``) for the same sequence
   number. Note this is only a *logical order*, and a
   ``deliver(seqno, prevhash, blob)`` on one peer is not required to
   occur in any real-time relation to ``deliver(seqno, prevhash, blob)``
   that outputs the same message at another peer. Put differently, given<commit_msg>docs: fix a typo in arch-deep-drive<commit_after>Architecture Explained
======================

The Hyperledger Fabric architecture delivers the following advantages:

-  **Chaincode trust flexibility.** The architecture separates *trust
   assumptions* for chaincodes (blockchain applications) from trust
   assumptions for ordering. In other words, the ordering service may be
   provided by one set of nodes (orderers) and tolerate some of them to
   fail or misbehave, and the endorsers may be different for each
   chaincode.

-  **Scalability.** As the endorser nodes responsible for particular
   chaincode are orthogonal to the orderers, the system may *scale*
   better than if these functions were done by the same nodes. In
   particular, this results when different chaincodes specify disjoint
   endorsers, which introduces a partitioning of chaincodes between
   endorsers and allows parallel chaincode execution (endorsement).
   Besides, chaincode execution, which can potentially be costly, is
   removed from the critical path of the ordering service.

-  **Confidentiality.** The architecture facilitates deployment of
   chaincodes that have *confidentiality* requirements with respect to
   the content and state updates of its transactions.

-  **Consensus modularity.** The architecture is *modular* and allows
   pluggable consensus (i.e., ordering service) implementations.

**Part I: Elements of the architecture relevant to Hyperledger Fabric
v1**

1. System architecture
2. Basic workflow of transaction endorsement
3. Endorsement policies

   **Part II: Post-v1 elements of the architecture**

4. Ledger checkpointing (pruning)

1. System architecture
----------------------

The blockchain is a distributed system consisting of many nodes that
communicate with each other. The blockchain runs programs called
chaincode, holds state and ledger data, and executes transactions. The
chaincode is the central element as transactions are operations invoked
on the chaincode. Transactions have to be "endorsed" and only endorsed
transactions may be committed and have an effect on the state. There may
exist one or more special chaincodes for management functions and
parameters, collectively called *system chaincodes*.

1.1. Transactions
~~~~~~~~~~~~~~~~~

Transactions may be of two types:

-  *Deploy transactions* create new chaincode and take a program as
   parameter. When a deploy transaction executes successfully, the
   chaincode has been installed "on" the blockchain.

-  *Invoke transactions* perform an operation in the context of
   previously deployed chaincode. An invoke transaction refers to a
   chaincode and to one of its provided functions. When successful, the
   chaincode executes the specified function - which may involve
   modifying the corresponding state, and returning an output.

As described later, deploy transactions are special cases of invoke
transactions, where a deploy transaction that creates new chaincode,
corresponds to an invoke transaction on a system chaincode.

**Remark:** *This document currently assumes that a transaction either
creates new chaincode or invokes an operation provided by *one* already
deployed chaincode. This document does not yet describe: a)
optimizations for query (read-only) transactions (included in v1), b)
support for cross-chaincode transactions (post-v1 feature).*

1.2. Blockchain datastructures
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

1.2.1. State
^^^^^^^^^^^^

The latest state of the blockchain (or, simply, *state*) is modeled as a
versioned key-value store (KVS), where keys are names and values are
arbitrary blobs. These entries are manipulated by the chaincodes
(applications) running on the blockchain through ``put`` and ``get``
KVS-operations. The state is stored persistently and updates to the
state are logged. Notice that versioned KVS is adopted as state model,
an implementation may use actual KVSs, but also RDBMSs or any other
solution.

More formally, state ``s`` is modeled as an element of a mapping
``K -> (V X N)``, where:

-  ``K`` is a set of keys
-  ``V`` is a set of values
-  ``N`` is an infinite ordered set of version numbers. Injective
   function ``next: N -> N`` takes an element of ``N`` and returns the
   next version number.

Both ``V`` and ``N`` contain a special element |falsum| (empty type), which is
in case of ``N`` the lowest element. Initially all keys are mapped to
(|falsum|, |falsum|). For ``s(k)=(v,ver)`` we denote ``v`` by ``s(k).value``,
and ``ver`` by ``s(k).version``.

.. |falsum| unicode:: U+22A5
.. |in| unicode:: U+2208

KVS operations are modeled as follows:

-  ``put(k,v)`` for ``k`` |in| ``K`` and ``v`` |in| ``V``, takes the blockchain
   state ``s`` and changes it to ``s'`` such that
   ``s'(k)=(v,next(s(k).version))`` with ``s'(k')=s(k')`` for all
   ``k'!=k``.
-  ``get(k)`` returns ``s(k)``.

State is maintained by peers, but not by orderers and clients.

**State partitioning.** Keys in the KVS can be recognized from their
name to belong to a particular chaincode, in the sense that only
transaction of a certain chaincode may modify the keys belonging to this
chaincode. In principle, any chaincode can read the keys belonging to
other chaincodes. *Support for cross-chaincode transactions, that modify
the state belonging to two or more chaincodes is a post-v1 feature.*

1.2.2 Ledger
^^^^^^^^^^^^

Ledger provides a verifiable history of all successful state changes (we
talk about *valid* transactions) and unsuccessful attempts to change
state (we talk about *invalid* transactions), occurring during the
operation of the system.

Ledger is constructed by the ordering service (see Sec 1.3.3) as a
totally ordered hashchain of *blocks* of (valid or invalid)
transactions. The hashchain imposes the total order of blocks in a
ledger and each block contains an array of totally ordered transactions.
This imposes total order across all transactions.

Ledger is kept at all peers and, optionally, at a subset of orderers. In
the context of an orderer we refer to the Ledger as to
``OrdererLedger``, whereas in the context of a peer we refer to the
ledger as to ``PeerLedger``. ``PeerLedger`` differs from the
``OrdererLedger`` in that peers locally maintain a bitmask that tells
apart valid transactions from invalid ones (see Section XX for more
details).

Peers may prune ``PeerLedger`` as described in Section XX (post-v1
feature). Orderers maintain ``OrdererLedger`` for fault-tolerance and
availability (of the ``PeerLedger``) and may decide to prune it at
anytime, provided that properties of the ordering service (see Sec.
1.3.3) are maintained.

The ledger allows peers to replay the history of all transactions and to
reconstruct the state. Therefore, state as described in Sec 1.2.1 is an
optional datastructure.

1.3. Nodes
~~~~~~~~~~

Nodes are the communication entities of the blockchain. A "node" is only
a logical function in the sense that multiple nodes of different types
can run on the same physical server. What counts is how nodes are
grouped in "trust domains" and associated to logical entities that
control them.

There are three types of nodes:

1. **Client** or **submitting-client**: a client that submits an actual
   transaction-invocation to the endorsers, and broadcasts
   transaction-proposals to the ordering service.

2. **Peer**: a node that commits transactions and maintains the state
   and a copy of the ledger (see Sec, 1.2). Besides, peers can have a
   special **endorser** role.

3. **Ordering-service-node** or **orderer**: a node running the
   communication service that implements a delivery guarantee, such as
   atomic or total order broadcast.

The types of nodes are explained next in more detail.

1.3.1. Client
^^^^^^^^^^^^^

The client represents the entity that acts on behalf of an end-user. It
must connect to a peer for communicating with the blockchain. The client
may connect to any peer of its choice. Clients create and thereby invoke
transactions.

As detailed in Section 2, clients communicate with both peers and the
ordering service.

1.3.2. Peer
^^^^^^^^^^^

A peer receives ordered state updates in the form of *blocks* from the
ordering service and maintain the state and the ledger.

Peers can additionally take up a special role of an **endorsing peer**,
or an **endorser**. The special function of an *endorsing peer* occurs
with respect to a particular chaincode and consists in *endorsing* a
transaction before it is committed. Every chaincode may specify an
*endorsement policy* that may refer to a set of endorsing peers. The
policy defines the necessary and sufficient conditions for a valid
transaction endorsement (typically a set of endorsers' signatures), as
described later in Sections 2 and 3. In the special case of deploy
transactions that install new chaincode the (deployment) endorsement
policy is specified as an endorsement policy of the system chaincode.

1.3.3. Ordering service nodes (Orderers)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

The *orderers* form the *ordering service*, i.e., a communication fabric
that provides delivery guarantees. The ordering service can be
implemented in different ways: ranging from a centralized service (used
e.g., in development and testing) to distributed protocols that target
different network and node fault models.

Ordering service provides a shared *communication channel* to clients
and peers, offering a broadcast service for messages containing
transactions. Clients connect to the channel and may broadcast messages
on the channel which are then delivered to all peers. The channel
supports *atomic* delivery of all messages, that is, message
communication with total-order delivery and (implementation specific)
reliability. In other words, the channel outputs the same messages to
all connected peers and outputs them to all peers in the same logical
order. This atomic communication guarantee is also called *total-order
broadcast*, *atomic broadcast*, or *consensus* in the context of
distributed systems. The communicated messages are the candidate
transactions for inclusion in the blockchain state.

**Partitioning (ordering service channels).** Ordering service may
support multiple *channels* similar to the *topics* of a
publish/subscribe (pub/sub) messaging system. Clients can connect to a
given channel and can then send messages and obtain the messages that
arrive. Channels can be thought of as partitions - clients connecting to
one channel are unaware of the existence of other channels, but clients
may connect to multiple channels. Even though some ordering service
implementations included with Hyperledger Fabric support multiple
channels, for simplicity of presentation, in the rest of this
document, we assume ordering service consists of a single channel/topic.

**Ordering service API.** Peers connect to the channel provided by the
ordering service, via the interface provided by the ordering service.
The ordering service API consists of two basic operations (more
generally *asynchronous events*):

**TODO** add the part of the API for fetching particular blocks under
client/peer specified sequence numbers.

-  ``broadcast(blob)``: a client calls this to broadcast an arbitrary
   message ``blob`` for dissemination over the channel. This is also
   called ``request(blob)`` in the BFT context, when sending a request
   to a service.

-  ``deliver(seqno, prevhash, blob)``: the ordering service calls this
   on the peer to deliver the message ``blob`` with the specified
   non-negative integer sequence number (``seqno``) and hash of the most
   recently delivered blob (``prevhash``). In other words, it is an
   output event from the ordering service. ``deliver()`` is also
   sometimes called ``notify()`` in pub-sub systems or ``commit()`` in
   BFT systems.

**Ledger and block formation.** The ledger (see also Sec. 1.2.2)
contains all data output by the ordering service. In a nutshell, it is a
sequence of ``deliver(seqno, prevhash, blob)`` events, which form a hash
chain according to the computation of ``prevhash`` described before.

Most of the time, for efficiency reasons, instead of outputting
individual transactions (blobs), the ordering service will group (batch)
the blobs and output *blocks* within a single ``deliver`` event. In this
case, the ordering service must impose and convey a deterministic
ordering of the blobs within each block. The number of blobs in a block
may be chosen dynamically by an ordering service implementation.

In the following, for ease of presentation, we define ordering service
properties (rest of this subsection) and explain the workflow of
transaction endorsement (Section 2) assuming one blob per ``deliver``
event. These are easily extended to blocks, assuming that a ``deliver``
event for a block corresponds to a sequence of individual ``deliver``
events for each blob within a block, according to the above mentioned
deterministic ordering of blobs within a block.

**Ordering service properties**

The guarantees of the ordering service (or atomic-broadcast channel)
stipulate what happens to a broadcasted message and what relations exist
among delivered messages. These guarantees are as follows:

1. **Safety (consistency guarantees)**: As long as peers are connected
   for sufficiently long periods of time to the channel (they can
   disconnect or crash, but will restart and reconnect), they will see
   an *identical* series of delivered ``(seqno, prevhash, blob)``
   messages. This means the outputs (``deliver()`` events) occur in the
   *same order* on all peers and according to sequence number and carry
   *identical content* (``blob`` and ``prevhash``) for the same sequence
   number. Note this is only a *logical order*, and a
   ``deliver(seqno, prevhash, blob)`` on one peer is not required to
   occur in any real-time relation to ``deliver(seqno, prevhash, blob)``
   that outputs the same message at another peer. Put differently, given
{'fraction_non_alphanumeric': 0.07632521489971347, 'fraction_numerical': 0.0043696275071633236, 'mean_word_length': 4.638327948303716, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 7, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '1530373', 'n_tokens_mistral': 7118, 'n_tokens_neox': 6880, 'n_words': 3990}