Merge "FAB-4384 update getting started and doc tidy"

hyperledger · Jun 8, 2017 · 9492d4d · 9492d4d
2 parents 85ccddc + 8fe748f
commit 9492d4d
Show file tree

Hide file tree

Showing 33 changed files with 182 additions and 208 deletions.
diff --git a/docs/source/CONTRIBUTING.rst b/docs/source/CONTRIBUTING.rst
@@ -268,7 +268,7 @@ Software License 2.0. See the template of the `license header
 We have tried to make it as easy as possible to make contributions. This
 applies to how we handle the legal aspects of contribution. We use the
 same approach—the `Developer's Certificate of Origin 1.1
-(DCO) <https://github.com/hyperledger/fabric/blob/master/docs/source/biz/DCO1.1.txt>`__—that the Linux® Kernel
+(DCO) <https://github.com/hyperledger/fabric/blob/master/docs/source/DCO1.1.txt>`__—that the Linux® Kernel
 `community <http://elinux.org/Developer_Certificate_Of_Origin>`__ uses
 to manage code contributions.
 

diff --git a/docs/source/biz/DCO1.1.txt → docs/source/DCO1.1.txt b/docs/source/biz/DCO1.1.txt → docs/source/DCO1.1.txt
diff --git a/docs/source/FAQ/architecture_FAQ.rst b/docs/source/FAQ/architecture_FAQ.rst
@@ -1,5 +1,5 @@
-V1 Architecture
-===========================
+Hyperledger Fabric FAQs
+=======================
 
 Endorsement
 -----------
@@ -90,6 +90,99 @@ queried may be recovering and catching up on block processing?
 A. The client can query multiple peers, compare their block heights, compare their query results,
 and favor the peers at the higher block heights.
 
+Chaincode (Smart Contracts and Digital Assets)
+----------------------------------------------
+
+* Does the fabric implementation support smart contract logic?
+
+Yes. Chaincode is the fabric’s interpretation of the smart contract
+method/algorithm, with additional features.
+
+A chaincode is programmatic code deployed on the network, where it is
+executed and validated by chain validators together during the consensus
+process. Developers can use chaincodes to develop business contracts,
+asset definitions, and collectively-managed decentralized applications.
+
+* How do I create a business contract using the fabric?
+
+There are generally two ways to develop business contracts: the first way is to
+code individual contracts into standalone instances of chaincode; the
+second way, and probably the more efficient way, is to use chaincode to
+create decentralized applications that manage the life cycle of one or
+multiple types of business contracts, and let end users instantiate
+instances of contracts within these applications.
+
+* How do I create assets using the fabric?
+
+Users can use chaincode (for business rules) and membership service (for digital tokens) to
+design assets, as well as the logic that manages them.
+
+There are two popular approaches to defining assets in most blockchain
+solutions: the stateless UTXO model, where account balances are encoded
+into past transaction records; and the account model, where account
+balances are kept in state storage space on the ledger.
+
+Each approach carries its own benefits and drawbacks. This blockchain
+fabric does not advocate either one over the other. Instead, one of our
+first requirements was to ensure that both approaches can be easily
+implemented with tools available in the fabric.
+
+* Which languages are supported for writing chaincode?
+
+Chaincode can be written in any programming language and executed in containers
+inside the fabric context layer. We are also looking into developing a
+templating language (such as Apache Velocity) that can either get
+compiled into chaincode or have its interpreter embedded into a
+chaincode container.
+
+The fabric's first fully supported chaincode language is Golang, and
+support for JavaScript and Java is planned for 2016. Support for
+additional languages and the development of a fabric-specific templating
+language have been discussed, and more details will be released in the
+near future.
+
+* Does the fabric have native currency?
+
+No. However, if you really need a native currency for your chain network, you can develop your own
+native currency with chaincode. One common attribute 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)
+----------------------------------------
+
+* What is unique about the fabric's Membership Service module?
+
+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 on Fabric, you can always replace the
+default module with another membership service option should the need
+arise.
+
+* Does its Membership Service make Fabric a centralized solution?
+
+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/arch-deep-dive.rst b/docs/source/arch-deep-dive.rst
@@ -1,7 +1,7 @@
 Architecture Explained
 ======================
 
-The v1 architecture delivers the following advantages:
+The Hyperledger Fabric architecture delivers the following advantages:
 
 -  **Chaincode trust flexibility.** The architecture separates *trust
    assumptions* for chaincodes (blockchain applications) from trust
@@ -832,4 +832,3 @@ also be combined:
 
 .. Licensed under Creative Commons Attribution 4.0 International License
    https://creativecommons.org/licenses/by/4.0/
-
diff --git a/docs/source/biz/images/Canonical-Use-Cases_Asset-Depository.png b/docs/source/biz/images/Canonical-Use-Cases_Asset-Depository.png
diff --git a/docs/source/biz/images/Canonical-Use-Cases_B2BContract.png b/docs/source/biz/images/Canonical-Use-Cases_B2BContract.png
diff --git a/docs/source/biz/images/Canonical-Use-Cases_Direct-Communication.png b/docs/source/biz/images/Canonical-Use-Cases_Direct-Communication.png
diff --git a/docs/source/biz/images/Canonical-Use-Cases_Interoperability-of-Assets.png b/docs/source/biz/images/Canonical-Use-Cases_Interoperability-of-Assets.png
diff --git a/docs/source/biz/images/Canonical-Use-Cases_Manufacturing-Supply-Chain.png b/docs/source/biz/images/Canonical-Use-Cases_Manufacturing-Supply-Chain.png
diff --git a/docs/source/biz/images/Canonical-Use-Cases_One-Trade-One-Contract.png b/docs/source/biz/images/Canonical-Use-Cases_One-Trade-One-Contract.png
diff --git a/...ges/Canonical-Use-Cases_Separation-of-Asset-Ownership-and-Custodians-Duties.png b/...ges/Canonical-Use-Cases_Separation-of-Asset-Ownership-and-Custodians-Duties.png
diff --git a/docs/source/biz/images/assetrepository.png b/docs/source/biz/images/assetrepository.png
diff --git a/docs/source/biz/images/b2bcontract.png b/docs/source/biz/images/b2bcontract.png
diff --git a/docs/source/biz/images/corporate_action.png b/docs/source/biz/images/corporate_action.png
diff --git a/docs/source/biz/images/exchange.png b/docs/source/biz/images/exchange.png
diff --git a/docs/source/biz/images/interoperability_of_assets.png b/docs/source/biz/images/interoperability_of_assets.png
diff --git a/docs/source/biz/images/one_contract_per_trade.png b/docs/source/biz/images/one_contract_per_trade.png
diff --git a/docs/source/biz/images/separation_of_ownship_and_custodyservice.png b/docs/source/biz/images/separation_of_ownship_and_custodyservice.png
diff --git a/docs/source/biz/images/supplychain.png b/docs/source/biz/images/supplychain.png
diff --git a/docs/source/capabilities.rst b/docs/source/capabilities.rst
@@ -1,5 +1,5 @@
-Fabric Capabilities
-===================
+Hyperledger Fabric Capabilities
+===============================
 
 Hyperledger Fabric is a unique implementation of distributed ledger technology
 (DLT) that delivers enterprise-ready network security, scalability,
@@ -73,4 +73,3 @@ 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
@@ -1,11 +1,6 @@
 What is chaincode?
 ==================
 
-[WIP]
-
-coming soon ... end-to-end examples of chaincode demonstrating the
-available APIs.
-
 Chaincode is a piece of code that is written in one of the supported
 languages such as Go or Java. It is installed and instantiated through
 an SDK or CLI onto a network of Hyperledger Fabric peer nodes, enabling

diff --git a/docs/source/demos.rst b/docs/source/demos.rst
diff --git a/docs/source/fabric-sdks.rst b/docs/source/fabric-sdks.rst
@@ -0,0 +1,12 @@
+Hyperledger Fabric SDKs
+=======================
+
+Hyperledger Fabric intends to offer a number of SDKs for a wide variety of
+programming languages. The first two delivered are the Node.js and Java
+SDKs. We hope to provide Python and Go SDKs soon after the 1.0.0 release.
+
+  * `Hyperledger Fabric Node SDK documentation <https://fabric-sdk-node.github.io/>`__.
+  * `Hyperledger Fabric Java SDK documentation <https://github.com/hyperledger/fabric-sdk-java>`__.
+
+.. Licensed under Creative Commons Attribution 4.0 International License
+   https://creativecommons.org/licenses/by/4.0/
diff --git a/docs/source/fabric_model.rst b/docs/source/fabric_model.rst
@@ -1,5 +1,26 @@
-The Fabric Model
-=================
+Hyperledger Fabric Model
+========================
+
+This section outlines the key design features woven into Hyperledger Fabric that
+fulfill its promise of a comprehensive, yet customizable, enterprise blockchain solution:
+
+* :ref:`Assets` - Asset definitions enable the exchange of almost anything with
+  monetary value over the network, from whole foods to antique cars to currency
+  futures.
+* :ref:`Chaincode` - Chaincode execution is partitioned from transaction ordering,
+  limiting the required levels of trust and verification across node types, and
+  optimizing network scalability and performance.
+* :ref:`Ledger-Features` - The immutable, shared ledger encodes the entire
+  transaction history for each channel, and includes SQL-like query capability
+  for efficient auditing and dispute resolution.
+* :ref:`Privacy-through-Channels` - Channels enable multi-lateral transactions
+  with the high degrees of privacy and confidentiality required by competing
+  businesses and regulated industries that exchange assets on a common network.
+* :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
+  flexibility and scalability needed for the enterprise.
 
 .. _Assets:
 
@@ -136,4 +157,3 @@ of consensus.
 
 .. Licensed under Creative Commons Attribution 4.0 International License
    https://creativecommons.org/licenses/by/4.0/
-
diff --git a/docs/source/getting_started.rst b/docs/source/getting_started.rst
@@ -2,8 +2,8 @@ Getting Started
 ===============
 
 .. note:: These instructions have been verified to work against the
-          version "1.0.0-alpha2" tagged docker images and the pre-compiled
-          setup utilities within the supplied tarball file. If you run
+          version "1.0.0-beta" 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.
@@ -40,44 +40,23 @@ Next, execute the following command:
 
 .. code:: bash
 
-  curl -sSL https://goo.gl/NIKLiU | bash
+  curl -sSL https://goo.gl/LQkuoh | bash
 
 This command downloads and executes a bash script (``bootstrap.sh``) that will
 extract all of the necessary artifacts to set up your network and place them
 into a folder named ``release``.
 
-It also retrieves the two platform-specific binaries - ``cryptogen`` and
-``configtxgen`` - which we'll use later. Finally, the script will
-download the Hyperledger Fabric docker images into your local Docker registry.
-
-The script lists out the docker images upon conclusion.  You should see the
-following:
-
-.. code:: bash
-
-  jdoe-mbp:<your_platform> johndoe$ docker images
-  REPOSITORY                     TAG                  IMAGE ID            CREATED             SIZE
-  hyperledger/fabric-couchdb     latest                3d89ac4895f9        3 days ago          1.51 GB
-  hyperledger/fabric-couchdb     x86_64-1.0.0-alpha2   3d89ac4895f9        3 days ago          1.51 GB
-  hyperledger/fabric-ca          latest                86f4e4280690        3 days ago          241 MB
-  hyperledger/fabric-ca          x86_64-1.0.0-alpha2   86f4e4280690        3 days ago          241 MB
-  hyperledger/fabric-kafka       latest                b77440c116b3        3 days ago          1.3 GB
-  hyperledger/fabric-kafka       x86_64-1.0.0-alpha2   b77440c116b3        3 days ago          1.3 GB
-  hyperledger/fabric-zookeeper   latest                fb8ae6cea9bf        3 days ago          1.31 GB
-  hyperledger/fabric-zookeeper   x86_64-1.0.0-alpha2   fb8ae6cea9bf        3 days ago          1.31 GB
-  hyperledger/fabric-orderer     latest                9a63e8bac1f5        3 days ago          182 MB
-  hyperledger/fabric-orderer     x86_64-1.0.0-alpha2   9a63e8bac1f5        3 days ago          182 MB
-  hyperledger/fabric-peer        latest                23b4aedef57f        3 days ago          185 MB
-  hyperledger/fabric-peer        x86_64-1.0.0-alpha2   23b4aedef57f        3 days ago          185 MB
-  hyperledger/fabric-javaenv     latest                a9ca2c90a6bf        3 days ago          1.43 GB
-  hyperledger/fabric-javaenv     x86_64-1.0.0-alpha2   a9ca2c90a6bf        3 days ago          1.43 GB
-  hyperledger/fabric-ccenv       latest                c984ae2a1936        3 days ago          1.29 GB
-  hyperledger/fabric-ccenv       x86_64-1.0.0-alpha2   c984ae2a1936        3 days ago          1.29 GB
+It also retrieves the two platform-specific binaries - ``cryptogen``,
+``configtxgen`` and ``configtxlator`` - which we'll use later. Finally, the
+script will download the Hyperledger Fabric docker images from
+`DockerHub <https://hub.docker.com/u/hyperledger/>`__ into
+your local Docker registry.
 
+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-alpha2" and one tagged as "latest".
+of the same image ID - one tagged as "x86_64-1.0.0-beta" and one tagged as "latest".
 (Note that on different architectures, the x86_64 would be replaced with the string
 identifying your architecture).
 
@@ -86,8 +65,35 @@ Want to run it now?
 
 We provide a script that leverages these docker images to quickly bootstrap
 a Fabric network, join peers to a channel, and drive transactions.  If you're
-already familiar with Fabric or just want to see it in action, feel free to jump
-down to the :ref:`Network-Setup` section and run the script.
+already familiar with Fabric or just want to see it in action, we have provided
+a script that runs an end-to-end sample application.
+
+This script literally does it all.  It calls ``generateArtifacts.sh`` to exercise
+the ``cryptogen`` and ``configtxgen`` tools, followed by ``script.sh`` which
+launches the network, joins peers to a generated channel and then drives
+transactions.  If you choose not to supply a channel ID, then the
+script will use a default name of ``mychannel``.  The cli timeout parameter
+is an optional value; if you choose not to set it, then your cli container
+will exit upon conclusion of the script.
+
+.. code:: bash
+
+              ./network_setup.sh up
+
+OR
+
+.. code:: bash
+
+              ./network_setup.sh up <channel-ID> <timeout-value>
+
+Once the demo has completed execution, run it again to clean up...
+
+The following will kill your containers, remove the crypto material and
+four artifacts, and remove our the created chaincode images:
+
+.. code:: bash
+
+              ./network_setup.sh down
 
 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
@@ -481,18 +487,6 @@ the underlying flow and the appropriate syntax. Entering the commands manually
 through the CLI is quite onerous, therefore we provide a few scripts to do the
 entirety of the heavy lifting.
 
-Clean up
-^^^^^^^^
-
-Let's clean up first...
-
-The following script will kill our containers, remove the crypto material and
-four artifacts, and remove our three chaincode images:
-
-.. code:: bash
-
-  ./network_setup.sh down
-
 .. _Network-Setup:
 
 All in one
@@ -518,10 +512,14 @@ OR
 
 Now clean up...
 
+The following script will kill our containers, remove the crypto material and
+four artifacts, and remove our three chaincode images:
+
 .. code:: bash
 
               ./network_setup.sh down
 
+
 Config only
 ^^^^^^^^^^^
 
@@ -921,7 +919,7 @@ again.
       Error connecting: rpc error: code = 14 desc = grpc: RPC failed fast due to transport failure
       Error: rpc error: code = 14 desc = grpc: RPC failed fast due to transport failure
 
-Make sure you are running your network against "alpha2" images that have been
+Make sure you are running your network against the "beta" images that have been
 retagged as "latest".
 
 If you see the below error:
@@ -942,7 +940,7 @@ back and recreate your channel artifacts.
        ./network_setup.sh 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