From 9a86c1a236bedf3f35a5d153538e0aa3dbc47470 Mon Sep 17 00:00:00 2001 From: Gari Singh Date: Tue, 4 Jul 2017 10:46:23 -0400 Subject: [PATCH] FAB-5166 Docs should use Hyperledger Fabric There are still several places in the docs which do not properly use Hyperledger Fabric when referring to Hyperledger Fabric. While this change covers a lot of files, it simply changes all reference to Hyperledger Fabric or provides a minor rewrite to avoid using the terms at all. As part of this, also addressed - FAB-5014 - FAB-5139 - Changed docker to Docker as appropriate - Other minor cleanups since this included most of the docs Change-Id: I7818a44b1411abb536a595c537202615bf901199 Signed-off-by: Gari Singh --- docs/source/CONTRIBUTING.rst | 4 +- docs/source/Fabric-FAQ.rst | 35 ---------------- docs/source/Gerrit/lf-account.rst | 2 +- docs/source/Style-guides/go-style.rst | 6 +-- docs/source/arch-deep-dive.rst | 4 +- docs/source/architecture.rst | 4 +- docs/source/blockchain.rst | 10 ++--- docs/source/build_network.rst | 58 ++++++++++++++------------- docs/source/capabilities.rst | 14 +++---- docs/source/chaincode.rst | 6 +-- docs/source/chaincode4ade.rst | 6 +-- docs/source/chaincode4noah.rst | 11 ++--- docs/source/configtxgen.rst | 2 +- docs/source/dev-setup/build.rst | 8 ++-- docs/source/dev-setup/devenv.rst | 19 ++++----- docs/source/error-handling.rst | 14 +++---- docs/source/fabric_model.rst | 37 ++++++++--------- docs/source/getting_started.rst | 4 +- docs/source/glossary.rst | 39 +++++++----------- docs/source/gossip.rst | 6 +-- docs/source/install_instantiate.rst | 2 +- docs/source/kafka.rst | 10 ++--- docs/source/ledger.rst | 8 ++-- docs/source/msp.rst | 31 ++++++-------- docs/source/policies.rst | 5 +-- docs/source/prereqs.rst | 4 +- docs/source/questions.rst | 5 +-- docs/source/releases.rst | 4 +- docs/source/samples.rst | 10 ++--- docs/source/testing.rst | 2 +- docs/source/write_first_app.rst | 26 ++++++------ 31 files changed, 175 insertions(+), 221 deletions(-) diff --git a/docs/source/CONTRIBUTING.rst b/docs/source/CONTRIBUTING.rst index f51364ec598..a2c745f46dd 100644 --- a/docs/source/CONTRIBUTING.rst +++ b/docs/source/CONTRIBUTING.rst @@ -111,7 +111,7 @@ Discussion of the proposed feature should be conducted in the JIRA issue itself, so that we have a consistent pattern within our community as to where to find design discussion. -Getting the support of three or more of the Fabric maintainers for the new +Getting the support of three or more of the Hyperledger Fabric maintainers for the new feature will greatly enhance the probability that the feature's related CRs will be merged. @@ -133,7 +133,7 @@ Next, try :doc:`building the project ` in your local development environment to ensure that everything is set up correctly. The :doc:`logging-control` document describes how to tweak -the logging levels of various components within the Fabric. Finally, +the logging levels of various components within Hyperledger Fabric. Finally, every source file needs to include a `license header `__: modified to include a copyright statement for the principle author(s). diff --git a/docs/source/Fabric-FAQ.rst b/docs/source/Fabric-FAQ.rst index b03fa15bbad..e80f3e1aed3 100644 --- a/docs/source/Fabric-FAQ.rst +++ b/docs/source/Fabric-FAQ.rst @@ -154,40 +154,5 @@ of native currency is that some amount will get transacted (the chaincode defining that currency will get called) every time a transaction is processed on its chain. -Identity Management (Membership Service) ----------------------------------------- - -Q. What is unique about the Hyperledger Fabric's membership service module? - -A. One of the things that makes the membership service module stand out from -the pack is our implementation of the latest advances in cryptography. - -In addition to ensuring private, auditable transactions, our membership -service module introduces the concept of enrollment and transaction -certificates. This innovation ensures that only verified owners can -create asset tokens, allowing an infinite number of transaction -certificates to be issued through parent enrollment certificates while -guaranteeing the private keys of asset tokens can be regenerated if -lost. - -Issuers also have the ability revoke transaction certificates or -designate them to expire within a certain timeframe, allowing greater -control over the asset tokens they have issued. - -Like most other modules, you can always replace the -default module with another membership service option should the need -arise. - -Q. Does its Membership Service make Fabric a centralized solution? - -A. No. The only role of the Membership Service module is to issue digital -certificates to validated entities that want to participate in the -network. It does not execute transactions nor is it aware of how or when -these certificates are used in any particular network. - -However, because certificates are the way networks regulate and manage -their users, the module serves a central regulatory and organizational -role. - .. Licensed under Creative Commons Attribution 4.0 International License https://creativecommons.org/licenses/by/4.0/ diff --git a/docs/source/Gerrit/lf-account.rst b/docs/source/Gerrit/lf-account.rst index a9983075d5b..05d8cf8dd66 100644 --- a/docs/source/Gerrit/lf-account.rst +++ b/docs/source/Gerrit/lf-account.rst @@ -1,7 +1,7 @@ Requesting a Linux Foundation Account ===================================== -Contributions to the Fabric code base require a Linux Foundation +Contributions to the Hyperledger Fabric code base require a Linux Foundation account. Follow the steps below to create a Linux Foundation account. Creating a Linux Foundation ID diff --git a/docs/source/Style-guides/go-style.rst b/docs/source/Style-guides/go-style.rst index 28f5966a244..1d8854b887b 100644 --- a/docs/source/Style-guides/go-style.rst +++ b/docs/source/Style-guides/go-style.rst @@ -26,10 +26,10 @@ generate/update the respective ``.pb.go`` files. Adding or updating Go packages ------------------------------ -The Hyperledger Fabric Project uses Go 1.6 vendoring for package +The Hyperledger Fabric Project uses Govendor for package management. This means that all required packages reside in the -``vendor`` folder within the fabric project. Go will use packages in -this folder instead of the GOPATH when the ``go install`` or +``$GOPATH/src/github.com/hyperledger/fabric/vendor`` folder. Go will use +packages in this folder instead of the GOPATH when the ``go install`` or ``go build`` commands are executed. To manage the packages in the ``vendor`` folder, we use `Govendor `__, which is installed diff --git a/docs/source/arch-deep-dive.rst b/docs/source/arch-deep-dive.rst index 9da18bd3f2e..9792516f476 100644 --- a/docs/source/arch-deep-dive.rst +++ b/docs/source/arch-deep-dive.rst @@ -234,8 +234,8 @@ 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 v1 will support -multiple channels, for simplicity of presentation, in the rest of this +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 diff --git a/docs/source/architecture.rst b/docs/source/architecture.rst index f79d3299c08..38d27bb5cbd 100644 --- a/docs/source/architecture.rst +++ b/docs/source/architecture.rst @@ -22,8 +22,8 @@ only to the set of nodes participating in that channel. The Hyperledger Fabric architecture is comprised of the following components: peer nodes, ordering nodes and the clients applications that -are likely leveraging one of the language-specific Fabric SDKs. These -components have identities derived from certificate authorities. +are likely leveraging one of the language-specific Hyperledger Fabric SDKs. +These components have identities derived from certificate authorities. Hyperledger Fabric also offers a certificate authority service, *fabric-ca* but, you may substitute that with your own. diff --git a/docs/source/blockchain.rst b/docs/source/blockchain.rst index c1bbb39f5f5..efecce4c88f 100644 --- a/docs/source/blockchain.rst +++ b/docs/source/blockchain.rst @@ -147,12 +147,12 @@ and is a system by which participants manage their transactions. Where Hyperledger Fabric breaks from some other blockchain systems is that it is **private** and **permissioned**. Rather than the “proof of work” some blockchain networks use to verify identity (allowing anyone who meets those -criteria to join the network), the members of a Fabric network enroll through -a **membership services provider**. +criteria to join the network), the members of a Hyperledger Fabric network +enroll through a **membership services provider**. -Fabric also offers several pluggable options. Ledger data can be stored in -multiple formats, consensus mechanisms can be switched in and out, -and different membership service providers are supported. +Hyperledger Fabric also offers several pluggable options. Ledger data can be +stored in multiple formats, consensus mechanisms can be switched in and out, +and different MSPs are supported. Hyperledger Fabric also offers the ability to create **channels**, allowing a group of participants to create a separate ledger of transactions. This is an especially diff --git a/docs/source/build_network.rst b/docs/source/build_network.rst index 831fb79b925..1eca2fec75a 100644 --- a/docs/source/build_network.rst +++ b/docs/source/build_network.rst @@ -2,15 +2,15 @@ Building Your First Network =========================== .. note:: These instructions have been verified to work against the - version "1.0.0-rc1" tagged docker images and the pre-compiled + version "1.0.0-rc1" tagged Docker images and the pre-compiled setup utilities within the supplied tar file. If you run these commands with images or tools from the current master branch, it is possible that you will see configuration and panic errors. -The build your first network (BYFN) scenario provisions a sample Fabric network -consisting of two organizations, each maintaining two peer nodes, and a "solo" -ordering service. +The build your first network (BYFN) scenario provisions a sample Hyperledger +Fabric network consisting of two organizations, each maintaining two peer +nodes, and a "solo" ordering service. Install prerequisites --------------------- @@ -38,12 +38,12 @@ sub-directory now. Want to run it now? ------------------- -We provide a fully annotated script ``byfn.sh`` that leverages these docker -images to quickly bootstrap a Fabric network comprised of 4 peers representing -two different organizations, and an orderer node. It will also launch a -container to run a scripted execution that will join peers to a channel, deploy -and instantiate chaincode and drive execution of transactions against the -deployed chaincode. +We provide a fully annotated script ``byfn.sh`` that leverages these Docker +images to quickly bootstrap a Hyperledger Fabric network comprised of 4 peers +representing two different organizations, and an orderer node. It will also +launch a container to run a scripted execution that will join peers to a +channel, deploy and instantiate chaincode and drive execution of transactions +against the deployed chaincode. Here's the help text for the ``byfn.sh`` script: @@ -213,7 +213,7 @@ Once again, you will be prompted to continue, respond with a ``y``: If you'd like to learn more about the underlying tooling and bootstrap mechanics, continue reading. In these next sections we'll walk through the various steps -and requirements to build a fully-functional Fabric network. +and requirements to build a fully-functional Hyperledger Fabric network. Crypto Generator ---------------- @@ -229,15 +229,17 @@ How does it work? Cryptogen consumes a file - ``crypto-config.yaml`` - that contains the network topology and allows us to generate a set of certificates and keys for both the Organizations and the components that belong to those Organizations. Each -Organization is provisioned a unique root certificate (``ca-cert``), that binds +Organization is provisioned a unique root certificate (``ca-cert``) that binds specific components (peers and orderers) to that Org. By assigning each Organization a unique CA certificate, we are mimicking a typical network where a participating :ref:`Member` would use its own Certificate Authority. -Transactions and communications within Fabric are signed by an entity's private -key (``keystore``), and then verified by means of a public key (``signcerts``). -You will notice a "count" variable within this file. We use this to specify -the number of peers per Organization; in our case it's two peers per Org. We -won't delve into the minutiae of `x.509 certificates and public key +Transactions and communications within Hyperledger Fabric are signed by an +entity's private key (``keystore``), and then verified by means of a public +key (``signcerts``). + +You will notice a ``count`` variable within this file. We use this to specify +the number of peers per Organization; in our case there are two peers per Org. +We won't delve into the minutiae of `x.509 certificates and public key infrastructure `__ right now. If you're interested, you can peruse these topics on your own time. @@ -284,7 +286,7 @@ Configuration Transaction Generator The ``configtxgen tool`` is used to create four configuration artifacts: * orderer ``genesis block``, - * fabric ``channel configuration transaction``, + * channel ``channel configuration transaction``, * and two ``anchor peer transactions`` - one for each Peer Org. Please see :doc:`configtxgen` for a complete description of the use of this @@ -677,7 +679,7 @@ traditional transaction - read/write - is performed against that chaincode (e.g. the value of "a"). The transaction causes the container to start. Also, all peers in a channel maintain an exact copy of the ledger which comprises the blockchain to store the immutable, sequenced record in -blocks, as well as a state database to maintain current fabric state. +blocks, as well as a state database to maintain a snapshot of the current state. This includes those peers that do not have chaincode installed on them (like ``peer1.org1.example.com`` in the above example) . Finally, the chaincode is accessible after it is installed (like ``peer1.org2.example.com`` in the above example) because it @@ -686,7 +688,7 @@ has already been instantiated. How do I see these transactions? ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Check the logs for the CLI docker container. +Check the logs for the CLI Docker container. .. code:: bash @@ -741,17 +743,17 @@ output from each container: ex02 Invoke Query Response:{"Name":"a","Amount":"90"} -Understanding the docker-compose topology +Understanding the Docker Compose topology ----------------------------------------- -The BYFN sample offers us two flavors of docker-compose files, both of which +The BYFN sample offers us two flavors of Docker Compose files, both of which are extended from the ``docker-compose-base.yaml`` (located in the ``base`` folder). Our first flavor, ``docker-compose-cli.yaml``, provides us with a -CLI container, along with an orderer, four peers. We use this docker-compose +CLI container, along with an orderer, four peers. We use this file for the entirety of the instructions on this page. .. note:: the remainder of this section covers a docker-compose file designed for the - SDK. Refer to the `Node.js SDK `__ + SDK. Refer to the `Node SDK `__ repo for details on running these tests. The second flavor, ``docker-compose-e2e.yaml``, is constructed to run end-to-end tests @@ -782,7 +784,7 @@ data content contingent upon the chaincode data being modeled as JSON. To use CouchDB instead of the default database (goleveldb), follow the same procedures outlined earlier for generating the artifacts, except when starting -the network pass the couchdb docker-compose as well: +the network pass ``docker-compose-couch.yaml`` as well: .. code:: bash @@ -910,8 +912,8 @@ Troubleshooting - **YOU WILL SEE ERRORS IF YOU DO NOT REMOVE CONTAINERS AND IMAGES** -- If you see docker errors, first check your version (should be 1.12 or above), - and then try restarting your docker process. Problems with Docker are +- If you see Docker errors, first check your version (should be 1.12 or above), + and then try restarting your Docker process. Problems with Docker are oftentimes not immediately recognizable. For example, you may see errors resulting from an inability to access crypto material mounted within a container. @@ -970,7 +972,7 @@ channel artifacts. ./byfn.sh -m down - If you see an error stating that you still have "active endpoints", then prune - your docker networks. This will wipe your previous networks and start you with a + your Docker networks. This will wipe your previous networks and start you with a fresh environment: .. code:: bash diff --git a/docs/source/capabilities.rst b/docs/source/capabilities.rst index 78db9ae7ad2..d697946e5d2 100644 --- a/docs/source/capabilities.rst +++ b/docs/source/capabilities.rst @@ -3,8 +3,8 @@ Hyperledger Fabric Capabilities Hyperledger Fabric is a unique implementation of distributed ledger technology (DLT) that delivers enterprise-ready network security, scalability, -confidentiality and performance, in a modular blockchain architecture. The -fabric delivers the following blockchain network capabilities: +confidentiality and performance, in a modular blockchain architecture. +Hyperledger Fabric delivers the following blockchain network capabilities: Identity management ------------------- @@ -65,11 +65,11 @@ Modular design Hyperledger Fabric implements a modular architecture to provide functional choice to network designers. Specific algorithms for identity, ordering (consensus) and encryption, for example, can be plugged in -to any fabric network. The result is a universal blockchain architecture that -any industry or public domain can adopt, with the assurance that its networks -will be interoperable across market, regulatory and geographic boundaries. By -contrast, current alternatives to Hyperledger Fabric are largely partisan, -constrained and industry-specific. +to any Hyperledger Fabric network. The result is a universal blockchain +architecture that any industry or public domain can adopt, with the assurance +that its networks will be interoperable across market, regulatory and +geographic boundaries. By contrast, current alternatives to Hyperledger Fabric +are largely partisan, constrained and industry-specific. .. Licensed under Creative Commons Attribution 4.0 International License https://creativecommons.org/licenses/by/4.0/ diff --git a/docs/source/chaincode.rst b/docs/source/chaincode.rst index ec6f5152f3e..b72b13fb55d 100644 --- a/docs/source/chaincode.rst +++ b/docs/source/chaincode.rst @@ -24,9 +24,9 @@ We offer two different perspectives on chaincode. One, from the perspective of an application developer developing a blockchain application/solution entitled :doc:`chaincode4ade`, and the other, :doc:`chaincode4noah` oriented to the blockchain network operator who is responsible for managing a blockchain -network, and who would leverage the Fabric API to install, instantiate, and -upgrade chaincode, but would likely not be involved in the development of a -chaincode application. +network, and who would leverage the Hyperledger Fabric API to install, +instantiate, and upgrade chaincode, but would likely not be involved in the +development of a chaincode application. .. Licensed under Creative Commons Attribution 4.0 International License https://creativecommons.org/licenses/by/4.0/ diff --git a/docs/source/chaincode4ade.rst b/docs/source/chaincode4ade.rst index 897f5fde86a..25bfd354c7d 100644 --- a/docs/source/chaincode4ade.rst +++ b/docs/source/chaincode4ade.rst @@ -382,7 +382,7 @@ We start "dev mode" by leveraging pre-generated orderer and channel artifacts fo a sample dev network. As such, the user can immediately jump into the process of compiling chaincode and driving calls. -Install Fabric Samples +Install Hyperledger Fabric Samples ---------------------- If you haven't already done so, please install the :doc:`samples`. @@ -394,10 +394,10 @@ clone: cd chaincode-docker-devmode -Download docker images +Download Docker images ---------------------- -We need four docker images in order for "dev mode" to run against the supplied +We need four Docker images in order for "dev mode" to run against the supplied docker compose script. If you installed the ``fabric-samples`` repo clone and followed the instructions to :ref:`download-platform-specific-binaries`, then you should have the necessary Docker images installed locally. diff --git a/docs/source/chaincode4noah.rst b/docs/source/chaincode4noah.rst index 6d17c38f8fa..58ac89e4bbe 100644 --- a/docs/source/chaincode4noah.rst +++ b/docs/source/chaincode4noah.rst @@ -30,9 +30,9 @@ The Hyperledger Fabric API enables interaction with the various nodes in a blockchain network - the peers, orderers and MSPs - and it also allows one to package, install, instantiate and upgrade chaincode on the endorsing peer nodes. The Hyperledger Fabric language-specific SDKs -abstract the specifics of the Hyperledger Fabric's API to facilitate +abstract the specifics of the Hyperledger Fabric API to facilitate application development, though it can be used to manage a chaincode's -lifecycle. Additionally, the Hyperledger Fabric's API can be accessed +lifecycle. Additionally, the Hyperledger Fabric API can be accessed directly via the CLI, which we will use in this document. We provide four commands to manage a chaincode's lifecycle: ``package``, @@ -307,7 +307,7 @@ CLI can simply invoke the commands from within a running docker container. To view the currently available CLI commands, execute the following command from -within a running ``fabric-peer`` docker container: +within a running ``fabric-peer`` Docker container: .. code:: bash @@ -384,8 +384,9 @@ register with a `fixed set of parameters compiled in and doesn't have endorsement policies or endorsement policy functionality. -System chaincode is used in Fabric to implement a number of system behaviors -so that they can be replaced or modified as appropriate by a system integrator. +System chaincode is used in Hyperledger Fabric to implement a number of +system behaviors so that they can be replaced or modified as appropriate +by a system integrator. The current list of system chaincodes: diff --git a/docs/source/configtxgen.rst b/docs/source/configtxgen.rst index 19257b430a4..633083692c7 100644 --- a/docs/source/configtxgen.rst +++ b/docs/source/configtxgen.rst @@ -2,7 +2,7 @@ Channel Configuration (configtxgen) =================================== This document describe the usage for the ``configtxgen`` utility for -manipulating fabric channel configuration. +manipulating Hyperledger Fabric channel configuration. For now, the tool is primarily focused on generating the genesis block for bootstrapping the orderer, but it is intended to be enhanced in the diff --git a/docs/source/dev-setup/build.rst b/docs/source/dev-setup/build.rst index 2c2475e66fe..e76f83b2e03 100644 --- a/docs/source/dev-setup/build.rst +++ b/docs/source/dev-setup/build.rst @@ -1,10 +1,10 @@ -Building the fabric -------------------- +Building Hyperledger Fabric +--------------------------- The following instructions assume that you have already set up your :doc:`development environment `. -To build the Fabric: +To build Hyperledger Fabric: :: @@ -165,7 +165,7 @@ The available log levels in order of increasing verbosity are: *CRITICAL See the :doc:`logging-control` document for instructions on tweaking the level of log messages to output when running -the various Fabric components. +the various Hyperledger Fabric components. .. Licensed under Creative Commons Attribution 4.0 International License https://creativecommons.org/licenses/by/4.0/ diff --git a/docs/source/dev-setup/devenv.rst b/docs/source/dev-setup/devenv.rst index f2af26e8a64..9efccbcb813 100644 --- a/docs/source/dev-setup/devenv.rst +++ b/docs/source/dev-setup/devenv.rst @@ -97,13 +97,13 @@ If you continue with ``core.autocrlf`` set to ``true``, the ``./setup.sh: /bin/bash^M: bad interpreter: No such file or directory`` -Cloning the Fabric project -^^^^^^^^^^^^^^^^^^^^^^^^^^ +Cloning the Hyperledger Fabric project +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Since the Fabric project is a ``Go`` project, you'll need to clone the -Fabric repo to your $GOPATH/src directory. If your $GOPATH has multiple -path components, then you will want to use the first one. There's a -little bit of setup needed: +Since the Hyperledger Fabric project is a ``Go`` project, you'll need to +clone the source repository to your $GOPATH/src directory. If your $GOPATH +has multiple path components, then you will want to use the first one. +There's a little bit of setup needed: :: @@ -147,11 +147,12 @@ Once inside the VM, you can find the peer project under ``$GOPATH/src/github.com/hyperledger/fabric``. It is also mounted as ``/hyperledger``. -Building the fabric -~~~~~~~~~~~~~~~~~~~ +Building Hyperledger Fabric +~~~~~~~~~~~~~~~~~~~~~~~~~~~ Once you have all the dependencies installed, and have cloned the -repository, you can proceed to :doc:`build and test ` the fabric. +repository, you can proceed to :doc:`build and test ` Hyperledger +Fabric. Notes ~~~~~ diff --git a/docs/source/error-handling.rst b/docs/source/error-handling.rst index 389d497eaba..338ecc7f16c 100644 --- a/docs/source/error-handling.rst +++ b/docs/source/error-handling.rst @@ -3,9 +3,9 @@ Error handling General Overview ---------------- -The Fabric error handling framework can be found in the Fabric repository under -**common/errors**. It defines a new type of error, CallStackError, to use in -place of the standard error type provided by Go. +The Hyperledger Fabric error handling framework can be found in the source +repository under **common/errors**. It defines a new type of error, +CallStackError, to use in place of the standard error type provided by Go. A CallStackError consists of the following: @@ -130,14 +130,14 @@ would display the error message: .. note:: The callstacks have not been displayed for this example for the sake of brevity. -General guidelines for error handling in Fabric ------------------------------------------------ +General guidelines for error handling in Hyperledger Fabric +----------------------------------------------------------- - If it is some sort of best effort thing you are doing, you should log the error and ignore it. - If you are servicing a user request, you should log the error and return it. -- If the error comes from elsewhere in the Fabric, you have the choice to wrap - the error or not. Typically, it's best to not wrap the error and simply return +- If the error comes from elsewhere, you have the choice to wrap the error + or not. Typically, it's best to not wrap the error and simply return it as is. However, for certain cases where a utility function is called, wrapping the error with a new component and reason code can help an end user understand where the error is really occurring without inspecting the callstack. diff --git a/docs/source/fabric_model.rst b/docs/source/fabric_model.rst index 3e25470ea8e..b376d7babdd 100644 --- a/docs/source/fabric_model.rst +++ b/docs/source/fabric_model.rst @@ -19,7 +19,7 @@ fulfill its promise of a comprehensive, yet customizable, enterprise blockchain * :ref:`Security-Membership-Services` - Permissioned membership provides a trusted blockchain network, where participants know that all transactions can be detected and traced by authorized regulators and auditors. -* :ref:`Consensus` - Fabric's unique approach to consensus enables the +* :ref:`Consensus` - a unique approach to consensus enables the flexibility and scalability needed for the enterprise. .. _Assets: @@ -28,15 +28,15 @@ Assets ------ Assets can range from the tangible (real estate and hardware) to the intangible -(contracts and intellectual property). You can easily define Assets in client-side -javascript and use them in your Fabric application using the included -`Fabric Composer `__ tool. +(contracts and intellectual property). Hyperledger Fabric provides the +ability to modify assets using chaincode transactions. -Fabric supports the ability to exchange assets using unspent transaction outputs -as the inputs for subsequent transactions. Assets (and asset registries) live -in Fabric as a collection of key-value pairs, with state changes recorded as transactions -on a :ref:`Channel` ledger. Fabric allows for any asset -to be represented in binary or JSON format. +Assets are represented in Hyperledger Fabric as a collection of +key-value pairs, with state changes recorded as transactions on a :ref:`Channel` +ledger. Assets can be represented in binary and/or JSON form. + +You can easily define and use assets in your Hyperledger Fabric applications +using the `Hyperledger Composer `__ tool. .. _Chaincode: @@ -83,20 +83,20 @@ See the :doc:`ledger` topic for a deeper dive on the databases, storage structur Privacy through Channels ------------------------ -Fabric employs an immutable ledger on a per-channel basis, as well as +Hyperledger Fabric employs an immutable ledger on a per-channel basis, as well as chaincodes that can manipulate and modify the current state of assets (i.e. update key value pairs). A ledger exists in the scope of a channel - it can be shared across the entire network (assuming every participant is operating on one common channel) - or it can be privatized to only include a specific set of participants. In the latter scenario, these participants would create a separate channel and -thereby isolate/segregate their transactions and ledger. Fabric even solves -scenarios that want to bridge the gap between total transparency and privacy. -Chaincode gets installed only on peers that need to access the asset states +thereby isolate/segregate their transactions and ledger. In order to solve +scenarios that want to bridge the gap between total transparency and privacy, +chaincode can be installed only on peers that need to access the asset states to perform reads and writes (in other words, if a chaincode is not installed on a peer, it will not be able to properly interface with the ledger). To further obfuscate the data, values within chaincode can be encrypted (in part or in total) using common -cryptographic algorithms such as SHA-256 before appending to the ledger. +cryptographic algorithms such as AES before appending to the ledger. .. _Security-Membership-Services: @@ -108,11 +108,12 @@ known identities. Public Key Infrastructure is used to generate cryptographic certificates which are tied to organizations, network components, and end users or client applications. As a result, data access control can be manipulated and governed on the broader network and on channel levels. This "permissioned" notion -of Fabric, coupled with the existence and capabilities of channels, helps address -scenarios where privacy and confidentiality are paramount concerns. +of Hyperledger Fabric, coupled with the existence and capabilities of channels, +helps address scenarios where privacy and confidentiality are paramount concerns. -See the :doc:`Fabric CA ` section to better understand cryptographic -implementations, and the sign, verify, authenticate approach used in Fabric. +See the :doc:`msp` topic to better understand cryptographic +implementations, and the sign, verify, authenticate approach used in +Hyperledger Fabric. .. _Consensus: diff --git a/docs/source/getting_started.rst b/docs/source/getting_started.rst index d5908035737..ded68f638f4 100644 --- a/docs/source/getting_started.rst +++ b/docs/source/getting_started.rst @@ -28,8 +28,8 @@ Tutorials We offer four initial tutorials to get you started with Hyperledger Fabric. The first is oriented to the Hyperledger Fabric **application developer**, :doc:`write_first_app`. It takes you through the process of writing your first -blockchain application for Hyperledger Fabric using the Hyperledger Fabric's -`Node.js SDK `__. +blockchain application for Hyperledger Fabric using the Hyperledger Fabric +`Node SDK `__. The second tutorial is oriented towards the Hyperledger Fabric network operators, :doc:`build_network`. This one walks you through the process of diff --git a/docs/source/glossary.rst b/docs/source/glossary.rst index 22749a14130..e76267e6acc 100644 --- a/docs/source/glossary.rst +++ b/docs/source/glossary.rst @@ -3,10 +3,10 @@ Glossary =========================== -Terminology is important, so that all Fabric users and developers agree on what -we mean by each specific term. What is chaincode, for example. So we'll point you -there, whenever you want to reassure yourself. Of course, feel free to read the -entire thing in one sitting if you like, it's pretty enlightening! +Terminology is important, so that all Hyperledger Fabric users and developers +agree on what we mean by each specific term. What is chaincode, for example. +The documentation will reference the glossary as needed, but feel free to +read the entire thing in one sitting if you like; it's pretty enlightening! .. _Anchor-Peer: @@ -51,7 +51,7 @@ instructions (business logic) for modifying the assets. Channel ------- -A channel is a private blockchain overlay on a Fabric network, allowing for data +A channel is a private blockchain overlay which allows for data isolation and confidentiality. A channel-specific ledger is shared across the peers in the channel, and transacting parties must be properly authenticated to a channel in order to interact with it. Channels are defined by a @@ -117,7 +117,7 @@ against current state data. Dynamic Membership ------------------ -Fabric supports the addition/removal of members, peers, and ordering service +Hyperledger Fabric supports the addition/removal of members, peers, and ordering service nodes, without compromising the operationality of the overall network. Dynamic membership is critical when business relationships adjust and entities need to be added/removed for various reasons. @@ -148,14 +148,13 @@ policy for install and instantiate transactions is also required. .. _Fabric-ca: -Fabric-ca -------------- +Hyperledger Fabric CA +--------------------- -Fabric-ca is the default Certificate Authority component, which issues PKI-based -certificates to network member organizations and their users. The CA issues one -root certificate (rootCert) to each member, one enrollment certificate (eCert) -to each authorized user, and a number of transaction certificates (tCerts) for -each eCert. +Hyperledger Fabric CA is the default Certificate Authority component, which +issues PKI-based certificates to network member organizations and their users. +The CA issues one root certificate (rootCert) to each member and one enrollment +certificate (ECert) to each authorized user. .. _Genesis-Block: @@ -255,13 +254,6 @@ permissioned blockchain network. The membership services code that runs in peers and orderers both authenticates and authorizes blockchain operations. It is a PKI-based implementation of the Membership Services Provider (MSP) abstraction. -The ``fabric-ca`` component is an implementation of membership services to manage -identities. In particular, it handles the issuance and revocation of enrollment -certificates and transaction certificates. - -An enrollment certificate is a long-term identity credential; a transaction -certificate is a short-term identity credential which is both anonymous and un-linkable. - .. _Ordering-Service: Ordering Service @@ -314,10 +306,9 @@ The Hyperledger Fabric client SDK provides a structured environment of libraries for developers to write and test chaincode applications. The SDK is fully configurable and extensible through a standard interface. Components, including cryptographic algorithms for signatures, logging frameworks and state stores, -are easily swapped in and out of the SDK. The SDK API uses protocol buffers over -gRPC for transaction processing, membership services, node traversal and event -handling applications to communicate across the fabric. The SDK comes in -multiple flavors - Node.js, Java. and Python. +are easily swapped in and out of the SDK. The SDK provides APIs for transaction +processing, membership services, node traversal and event handling. The SDK +comes in multiple flavors: Node.js, Java. and Python. .. _State-DB: diff --git a/docs/source/gossip.rst b/docs/source/gossip.rst index 9430040c15e..0907f3d9616 100644 --- a/docs/source/gossip.rst +++ b/docs/source/gossip.rst @@ -6,7 +6,7 @@ and scalability by dividing workload across transaction execution (endorsing and committing) peers and transaction ordering nodes. This decoupling of network operations requires a secure, reliable and scalable data dissemination protocol to ensure data integrity and -consistency. To meet these requirements, the fabric implements a +consistency. To meet these requirements, Hyperledger Fabric implements a **gossip data dissemination protocol**. Gossip protocol @@ -23,7 +23,7 @@ synced up to the current ledger state by contacting peers in possession of these missing blocks. The gossip-based data dissemination protocol performs three primary functions on -a Fabric network: +a Hyperledger Fabric network: 1. Manages peer discovery and channel membership, by continually identifying available member peers, and eventually detecting peers that have @@ -77,7 +77,7 @@ on peers' channel subscriptions. are signed by the ordering service, and then delivered to the leader peers on a channel. 2. Authentication is governed by the membership service provider for the peer. When the peer connects to the channel for the first time, the - TLS session binds with fabric membership identity. This essentially + TLS session binds with the membership identity. This essentially authenticates each peer to the connecting peer, with respect to membership in the network and channel. diff --git a/docs/source/install_instantiate.rst b/docs/source/install_instantiate.rst index 91849eb43a5..1b188995f0e 100644 --- a/docs/source/install_instantiate.rst +++ b/docs/source/install_instantiate.rst @@ -3,7 +3,7 @@ Install and Instantiate This tutorial requires the latest builds for ``hyperledger/fabric-baseimage``, ``hyperledger/fabric-peer`` and -``hyperledger/fabric-orderer``. Rather than pull from docker hub, you +``hyperledger/fabric-orderer``. Rather than pull from Docker Hub, you can compile these images locally to ensure they are up to date. It is up to the user how to build the images, although a typical approach is through vagrant. If you do choose to build through vagrant, make sure diff --git a/docs/source/kafka.rst b/docs/source/kafka.rst index e0b51a6f17b..951266cc56e 100644 --- a/docs/source/kafka.rst +++ b/docs/source/kafka.rst @@ -13,7 +13,7 @@ your blockchain network. Big picture ----------- -Each channel in Fabric maps to a separate single-partition topic in Kafka. When +Each channel maps to a separate single-partition topic in Kafka. When an OSN receives transactions via the ``Broadcast`` RPC, it checks to make sure that the broadcasting client has permissions to write on the channel, then relays (i.e. produces) those transactions to the appropriate partition in Kafka. @@ -108,7 +108,7 @@ every Kafka broker has these keys configured: ``fabric/orderer/kafka/config.go`` and rebuild the binary from source. This is not advisable.) - e. ``log.retention.ms = -1``. Until the ordering service in Fabric adds + e. ``log.retention.ms = -1``. Until the ordering service adds support for pruning of the Kafka logs, you should disable time-based retention and prevent segments from expiring. (Size-based retention -- see ``log.retention.bytes`` -- is disabled by default in Kafka at the time of @@ -180,9 +180,9 @@ default value for ``Orderer.Kafka.Retry.ShortInterval``. Supported Kafka versions and upgrading -------------------------------------- -Supported Kafka versions for v1 are ``0.9`` and ``0.10``. (Fabric uses the -`sarama client library `_ and vendors a -version of it that supports Kafka 0.9 and 0.10.) +Supported Kafka versions for v1 are ``0.9`` and ``0.10``. (Hyperledger Fabric +uses the `sarama client library `_ +and vendors a version of it that supports Kafka 0.9 and 0.10.) Out of the box the Kafka version defaults to ``0.9.0.1``. If you wish to use a different supported version, specify a supported version using the diff --git a/docs/source/ledger.rst b/docs/source/ledger.rst index 98750e0c049..a8277d04b7c 100644 --- a/docs/source/ledger.rst +++ b/docs/source/ledger.rst @@ -1,13 +1,13 @@ Ledger ====== -The ledger is the sequenced, tamper-resistant record of all state transitions in the fabric. State +The ledger is the sequenced, tamper-resistant record of all state transitions. State transitions are a result of chaincode invocations ('transactions') submitted by participating parties. Each transaction results in a set of asset key-value pairs that are committed to the ledger as creates, updates, or deletes. The ledger is comprised of a blockchain ('chain') to store the immutable, sequenced record in -blocks, as well as a state database to maintain current fabric state. There is one ledger per +blocks, as well as a state database to maintain current state. There is one ledger per channel. Each peer maintains a copy of the ledger for each channel of which they are a member. Chain @@ -56,7 +56,7 @@ will authenticate the signatures against the transaction payload. Secondly, peers will perform a versioning check against the transaction read set, to ensure data integrity and protect against threats such as double-spending. -The fabric has concurrency control whereby transactions execute in parallel (by endorsers) +Hyperledger Fabric has concurrency control whereby transactions execute in parallel (by endorsers) to increase throughput, and upon commit (by all peers) each transaction is verified to ensure that no other transaction has modified data it has read. In other words, it ensures that the data that was read during chaincode execution has not changed since execution (endorsement) time, @@ -89,7 +89,7 @@ If you model assets as JSON and use CouchDB, you can also perform complex rich q chaincode data values, using the CouchDB JSON query language within chaincode. These types of queries are excellent for understanding what is on the ledger. Proposal responses for these types of queries are typically useful to the client application, but are not typically submitted as -transactions to the ordering service. In fact the fabric does not guarantee the result set is stable +transactions to the ordering service. In fact, there is no guarantee the result set is stable between chaincode execution and commit time for rich queries, and therefore rich queries are not appropriate for use in update transactions, unless your application can guarantee the result set is stable between chaincode execution time and commit time, or can handle potential diff --git a/docs/source/msp.rst b/docs/source/msp.rst index 6932a8245d4..37b317b8798 100644 --- a/docs/source/msp.rst +++ b/docs/source/msp.rst @@ -12,14 +12,13 @@ MSP may define their own notion of identity, and the rules by which those identities are governed (identity validation) and authenticated (signature generation and verification). -A Fabric blockchain network can be governed by one or more MSPs. In this -way Fabric offers modularity of membership operations, and interoperability -across different membership standards and architectures. Fabric currently -supports PKCS #11 libraries. +A Hyperledger Fabric blockchain network can be governed by one or more MSPs. +This provides modularity of membership operations, and interoperability +across different membership standards and architectures. In the rest of this document we elaborate on the setup of the MSP -implementation supported by Fabric, and discuss best practices concerning -its use. +implementation supported by Hyperledger Fabric, and discuss best practices +concerning its use. MSP Configuration ----------------- @@ -88,9 +87,9 @@ specify: - The node's X.509 certificate, that is a valid identity under the verification parameters of this MSP -It is important to note that MSP identities never expire, they can only be revoked -by adding them the appropriate CRLs. In addition, for TLS certificates, -fabric does not offer support for revocation. +It is important to note that MSP identities never expire; they can only be revoked +by adding them to the appropriate CRLs. Additionally, there is currently no +support for enforcing revocation of TLS certificates. How to generate MSP certificates and their signing keys? -------------------------------------------------------- @@ -102,9 +101,8 @@ Fabric there is no support for certificates including RSA keys. Alternatively one can use ``cryptogen`` tool, whose operation is explained in :doc:`getting_started`. -For fabric-ca related certificate generation, we refer the reader to the -fabric-ca related documentation - -`Setup/ca-setup `_. +`Hyperledger Fabric CA `_ +can also be used to generate the keys and certificates needed to configure an MSP. MSP setup on the peer & orderer side ------------------------------------ @@ -213,12 +211,7 @@ considered: organization-scoped messages to the peers that have an identity under the same MSP regardless of whether they belong to the same actual organization. This is a limitation of the granularity of MSP definition, and/or of the peer’s - configuration. In future versions of Fabric, this can change as we move - towards (i) an identity channel that contains all membership related - information of the network, (ii) peer notion of “trust-zone” being - configurable, where a peer’s administrator specifying at peer setup time whose - MSP members should be treated by peers as authorized to receive - organization-scoped messages. + configuration. **2) One organization has different divisions (say organizational units), to** **which it wants to grant access to different channels.** @@ -307,7 +300,7 @@ and does not require blacklisting the no longer considered intermediate CA. MSP identities' root CAs and MSP TLS certificates' root CAs (and relative intermediate CAs) need to be declared in different folders. This is to avoid confusion between -different classes of certificates. Fabric does not forbid to reuse the same +different classes of certificates. It is not forbidden to reuse the same CAs for both MSP identities and TLS certificates but best practices suggest to avoid this in production. diff --git a/docs/source/policies.rst b/docs/source/policies.rst index 54a3e69f991..1aa5b1df1af 100644 --- a/docs/source/policies.rst +++ b/docs/source/policies.rst @@ -32,8 +32,7 @@ constructed. Policy Types ------------ -There are presently two different types of policies implemented in the -hyperledger fabric. +There are presently two different types of policies implemented: 1. **SignaturePolicy**: This policy type is the most powerful, and specifies the policy as a combination of evaluation rules for MSP @@ -264,7 +263,7 @@ The MSP Principal is a generalized notion of cryptographic identity. Although the MSP framework is designed to work with types of cryptography other than X.509, for the purposes of this document, the discussion will assume that the underlying MSP implementation is the -fabric MSP type, based on X.509 cryptography. +default MSP type, based on X.509 cryptography. An MSP Principal is defined in ``fabric/protos/msp_principal.proto`` as follows: diff --git a/docs/source/prereqs.rst b/docs/source/prereqs.rst index 7e279ad01cf..8b9803de524 100644 --- a/docs/source/prereqs.rst +++ b/docs/source/prereqs.rst @@ -77,7 +77,7 @@ Node.js Runtime and NPM ----------------------- If you will be developing applications for Hyperledger Fabric leveraging the -Fabric SDK for Node.js, you will need to have version 6.9.x of Node.js +Hyperledger Fabric SDK for Node.js, you will need to have version 6.9.x of Node.js installed. .. note:: Node.js version 7.x is not supported at this time. @@ -104,7 +104,7 @@ provides a better alternative to the built-in Windows tools: typically get this as part of installing Docker Toolbox. However experience has shown this to be a poor development environment with limited functionality. It is - suitable to run docker based scenarios, such as + suitable to run Docker based scenarios, such as :doc:`getting_started`, but you may not be able to find a suitable ``make`` command. diff --git a/docs/source/questions.rst b/docs/source/questions.rst index ef758d2c4fb..ad6371c471a 100644 --- a/docs/source/questions.rst +++ b/docs/source/questions.rst @@ -3,9 +3,8 @@ Still Have Questions? We try to maintain a comprehensive set of documentation for various audiences. However, we realize that often there are questions that -remain unanswered. For any technical questions relating to the -Hyperledger Fabric project not answered in this documentation, please -use +remain unanswered. For any technical questions relating to Hyperledger +Fabric not answered here, please use `StackOverflow `__. If you need help finding things, please don't hesitate to send a note to the `mailing diff --git a/docs/source/releases.rst b/docs/source/releases.rst index 9de6701ddaa..ad2cb5a1ea7 100644 --- a/docs/source/releases.rst +++ b/docs/source/releases.rst @@ -57,7 +57,7 @@ Java Chaincode support has been disabled until post 1.0.0 as it is not yet fully `v1.0.0-alpha2 `__ -The second alpha release of the v1.0.0 Hyperledger Fabric project. The code is +The second alpha release of the v1.0.0 Hyperledger Fabric. The code is now feature complete. From now until the v1.0.0 release, the community is focused on documentation improvements, testing, hardening, bug fixing and tooling. We will be releasing successive release candidates periodically as @@ -68,7 +68,7 @@ the release firms up. `v1.0.0-alpha `__ March 16, 2017 -The first alpha release of the v1.0.0 Hyperledger Fabric project. The code is +The first alpha release of the v1.0.0 Hyperledger Fabric. The code is being made available to developers to begin exploring the v1.0 architecture. `Change Log `__ diff --git a/docs/source/samples.rst b/docs/source/samples.rst index 3e13ce9f5b7..532fdbdb661 100644 --- a/docs/source/samples.rst +++ b/docs/source/samples.rst @@ -66,15 +66,15 @@ can be picked up without fully qualifying the path to each binary. e.g.: export PATH=/bin:$PATH Finally, the script will download the Hyperledger Fabric docker images from -`DockerHub `__ into +`Docker Hub `__ into your local Docker registry and tag them as 'latest'. -The script lists out the docker images installed upon conclusion. +The script lists out the Docker images installed upon conclusion. Look at the names for each image; these are the components that will ultimately -comprise our Fabric network. You will also notice that you have two instances -of the same image ID - one tagged as "x86_64-1.0.0-rc1" and one tagged as -"latest". +comprise our Hyperledger Fabric network. You will also notice that you have +two instances of the same image ID - one tagged as "x86_64-1.0.0-rc1" and +one tagged as "latest". .. note:: Note that on different architectures, the x86_64 would be replaced with the string identifying your architecture. diff --git a/docs/source/testing.rst b/docs/source/testing.rst index a734f3d3328..62bfd7b968b 100644 --- a/docs/source/testing.rst +++ b/docs/source/testing.rst @@ -3,7 +3,7 @@ Testing Unit test ~~~~~~~~~ -See :doc:`building the fabric ` for unit testing instructions. +See :doc:`building Hyperledger Fabric ` for unit testing instructions. See `Unit test coverage reports `__ diff --git a/docs/source/write_first_app.rst b/docs/source/write_first_app.rst index 004464f2016..c645901bd95 100644 --- a/docs/source/write_first_app.rst +++ b/docs/source/write_first_app.rst @@ -2,7 +2,7 @@ Writing Your First Application ============================== The goal of this document is to show the tasks and provide a baseline for writing -your first application against a Hyperledger Fabric network (a.k.a. Fabric). +your first application against a Hyperledger Fabric network. At the most basic level, applications on a blockchain network are what enable users to **query** a ledger (asking for specific records it contains), or to @@ -12,8 +12,8 @@ Our application, composed in Javascript, leverages the Node.js SDK to interact with the network (where our ledger exists). This tutorial will guide you through the three steps involved in writing your first application. - **1. Starting a test Fabric blockchain network.** We need some basic components - in our Fabric in order to query and update the ledger. These components -- + **1. Starting a test Hyperledger Fabric blockchain network.** We need some basic components + in our network in order to query and update the ledger. These components -- a peer node, ordering node and Certificate Authority -- serve as the backbone of our network; we'll also have a CLI container used for a few administrative commands. A single script will download and launch this test network. @@ -23,14 +23,15 @@ the three steps involved in writing your first application. in different ways. For example, we can read data holistically or on a more granular level. - **3. Developing the application to be able to query and update Fabric records.** + **3. Developing the application to be able to query and update records.** We provide two sample applications -- one for querying the ledger and another for updating it. Our apps will use the SDK APIs to interact with the network and ultimately call these functions. After completing this tutorial, you should have a basic understanding of how -an application, using the Fabric SDK for Node.js, is programmed in conjunction with a smart contract -to interact with the ledger on a Fabric network. +an application, using the Hyperledger Fabric SDK for Node.js, is programmed +in conjunction with a smart contract to interact with the ledger on a +Hyperledger Fabric network. First, let's launch our test network... @@ -58,8 +59,8 @@ this directory. You should see the following: Now use the ``startFabric.sh`` script to launch the network. -.. note:: The following command downloads and extracts the Fabric docker images, so it - will take a few minutes to complete. +.. note:: The following command downloads and extracts the Hyperledger Fabric + Docker images, so it will take a few minutes to complete. .. code:: bash @@ -81,7 +82,8 @@ this command. Here's a quick synopsis: Issue a ``docker ps`` command to reveal the processes started by the ``startFabric.sh`` script. You can learn more about the details and mechanics of these operations in the :doc:`build_network` section. Here we'll just focus on the application. The following picture -provides a simplistic representation of how the application interacts with the Fabric network. +provides a simplistic representation of how the application interacts with the +Hyperledger Fabric network. .. image:: images/AppConceptsOverview.png @@ -91,7 +93,7 @@ look at how the different pieces fit together. How Applications Interact with the Network ------------------------------------------ -Applications use **APIs** to invoke smart contracts (referred to in Fabric as "chaincode"). +Applications use **APIs** to invoke smart contracts (referred to as "chaincode"). These smart contracts are hosted in the network and identified by name and version. For example, our chaincode container is titled - ``dev-peer0.org1.example.com-fabcar-1.0`` - where the name is ``fabcar``, the version is ``1.0`` and the peer it is running against is ``dev-peer0.org1.example.com``. @@ -203,7 +205,7 @@ ledger. resultsIterator, err := APIstub.GetStateByRange(startKey, endKey) -The function uses the Fabric's shim interface ``GetStateByRange`` to return +The function uses the shim interface function ``GetStateByRange`` to return ledger data between the args of ``startKey`` and ``endKey``. Those keys are defined as ``CAR0`` and ``CAR999`` respectively. Therefore, we could theoretically create 1,000 cars (assuming the keys are tagged properly) and a ``queryAllCars`` would @@ -359,7 +361,7 @@ Additional Resources The `Hyperledger Fabric Node SDK repo `__ is an excellent resource for deeper documentation and sample code. You can also consult -the Fabric community and component experts on `Hyperledger Rocket Chat `__. +the Hyperledger Fabric community and component experts on `Hyperledger Rocket Chat `__. .. Licensed under Creative Commons Attribution 4.0 International License https://creativecommons.org/licenses/by/4.0/