diff --git a/docs/FAQ/architecture_FAQ.md b/docs/FAQ/architecture_FAQ.md new file mode 100644 index 00000000000..95e27520865 --- /dev/null +++ b/docs/FAQ/architecture_FAQ.md @@ -0,0 +1,153 @@ +# V1 Network and Architecture + +## Network + +__Network architecture__: + +Q. In the design document, clients are supposed to be able to connect to all peers (endorsers and consenters). But in reality, the blockchain peers may be hosted in private, restricted and secure network, for example, the participants are likely to host their peer in each internal network. In this case, how can clients connect to all peers? + +A. Clients only need to connect to as many peers as are required for endorsement. We expect 'clients' will more likely be application servers running close to a peer, which has connection to the peer network, rather than end user clients. There has been discussion of a 'submitting peer' pattern where your peer could act on behalf of your client to connect to other peers to gather endorsements and submit to ordering. This is not in plan for v1 but may get re-visited in future releases. + +## Security & Access Control + +__Reliance on External Application Server__: + +Q. Security (data integrity) — Reliance on an external application server is a single-point of control over data that could be compromised easily. Write operations flow through through the application server and/or directly to the primary data store. These systems have no concept of consensus and thus represent a single-point of control and therefore vulnerability. + +A. More question context is needed - which external application server is in question? + +Q. I hear that within a channel "everyone sees all the data." Does this mean "every endorser sees all the data" or do all users of the chaincode (non-endorsers) also see all the data? My understanding was that every endorser will see all the data, but ACLs in chaincode can ensure that users get selective visibility. Has there been a change to this? If so, where can I find documentation? I can't find any documentation on access control. + +A. A channel is comprised of a subset of the committing peers in a network that are authorized to maintain the ledger (and see the data) for a certain set of chaincodes. Endorsers are a subset of Committer peers that simulate and endorse a given transaction on the channel, but the transaction results will ultimately get sent to all committing peers on the channel. Access control can still be enforced within chaincode running on the channel, using similar ACL control mechanisms that were in v0.5/0.6 chaincode. The ACL control options within chaincode do need to be better documented. + + +__Application-level Data access control__: + +Q. In the business process, fine grained access control is required, not only by use or role, but also the state, or content of the data (e.g., only the owner of the document can update it). Currently it is all responsibility of the chaincode to implement such ALC. Is there any design abstract for this? + +A. This aspect will remain the same as 0.5/0.6, see above question. + +Q. How is access control enforced at the direct query to CouchDB? What is the granularity? + +A. Docker configuration enforces that only the peer container can connect to CouchDB. All queries should go through peer chaincode, where chaincode enforces the access control. + +Q. Even if there are multiple private chains, the Orderers can see all the transactions, which means they are the single point of trust. This is not acceptable in some use cases. Are there any plans to make orderers decentralized? + +A. This is generally true. The orderers do receive a higher degree of trust, and they must necessarily see all channels and their membership. I would point out, however, that the orderers only see the information which passes through them. Certain pieces of the transaction, such as the proposal, can be configured not to go through ordering. Similarly, any data which is referenced by hash or encrypted would be opaque to the orderers. Clients can hash/encrypt the data that they submit to ledger. + +Q. This is not acceptable in some use cases. Is there any plans to make orderers decentralized? + +A. I'm not sure I understand this portion of the question. There are other ordering protocols in the works, like SBFT, which allow further decentralization by allowing for more parties to take part because of the Byzantine fault tolerance. But, this does not really solve the confidentiality problem, in fact, distributing it makes it worse as there are more potential information leakage points. + +A. I would point out that ordering does not necessarily need to be centralized. A single peer could participate with many different ordering networks. (This is not necessarily targeted for v1, but the architecture does explicitly intend this). + +Q. Is encryption of transaction and ledger removed from V1? + +A. V1 does not have encryption at fabric level. The data at rest can be encrypted via file system encryption, and the data in transit is encrypted via TLS. In v1 it is possible to set up private channels so that you can share a ledger (and corresponding transactions) with the subset of network participants that are allowed to see the data. The submitting party now has full control - they can encrypt the complete set of data before submitting to ledger, encrypt sensitive portions only, or not encrypt if complete transparency/queryability is the goal. + +## Application-side Programming Model + +__Processing capacity of client__: + +Q. In the current design, client needs to send tx, collect endorsement result, check endorsement policy and broadcast endowment. These tasks are acceptable for the powerful clients such as server, but may be beyond the processing capacity of weaker ones, such as mobile app, IOT edge device. Is there any consideration for this scenario? + +A. We expect 'clients' will more likely be application servers that are serving the actual end user base. That being said, there has been discussion of a 'submitting peer' pattern where your peer could act on behalf of your client to connect to other peers to gather endorsements and submit to ordering. This is not in plan for v1 but may get re-visited in future releases. + + +__Transaction execution result__: + +Q. Transaction execution is asynchronous in blockchain. We cannot get the tx result for now, which is a big problem in the solution development. Any plan to fetch the output result? + +A. The output of the transaction execution is provided to the client by the endorser. Ultimately the transaction output will get validated or invalidated by the committing peers, and the client becomes aware of the outcome via an event. + +## Monitoring + +__More Monitoring Metrics are expected from the Docker Image__: + +Q. (phrased as a requirement) Provide basic information about deployed chaincode on the chain, such as chaincode ID, its deployed time, etc. For each chain code, with proper permission, provide invoke/query metrics data such as TPS, consensus latency (average, 50%, 85%), broken down into different chaincode API (function). Provide storage usage information on peer node. + +A. Agreed, much work remains around serviceability in general, monitoring is one piece of that. The specific feedback here has been added to: +https://jira.hyperledger.org/browse/FAB-2174 - As an administrator, I need better runtime monitoring capabilities for the fabric + +## Backward Compatibility + +__Chaincode Stub Interface__: + +Q. (phrased as a requirement) It's preferred to minimize changes to chaincode stub API +1. Removal of Table API causes backward compatibility issues to existing chaincode +2. Need RangeQuery for the world state to maintain backward compatibility of chaincode + +A. There is general agreement that chaincode API should be as stable as possible. That being said, 0.5/0.6 was a developer preview to gather feedback, and community feedback around API experiences must be taken into consideration for v1 release. There were many complaints and frustrations around the table API limitations, since it added overhead but didn't enable typical table queries. v1 provides a broader and richer set of APIs that solutions have called for, including `GetStateByRange()`, `GetStateByPartialCompositeKey()`, `GetHistoryForKey()` against the default/embedded Key/Value data store. Also there is a beta option to use CouchDB JSON document store that enables rich query via a new `GetQueryResult()` API. The new rich query is intended to be used for read-only queries, but it can also be used in chaincode read-write transactions if the application layer can guarantee the stability of the query result set between transaction simulation and validation/commit phases (no phantoms). + +__REST API__: + +Q. (phrased as a requirement) It's preferred to maintain REST API and hopefully make it more secure, in order to use existing tools via REST API (e.g., JMeter, Postman, etc.) + +A. SDK resolves security concerns of 0.5/0.6 REST API. SDK itself will likely provide the REST API interface going forward (rather than the peer). This is not yet available but planned for v1 or shortly thereafter. + + +__Database / Data Store__ + +Q. How ACL is enforced at block data? + +A. In v1 a member of the channel has access to the data on that channel's ledger. Access can be controlled within chaincode, and data can be encrypted before submitting to ledger. See questions in Security section above. + + +__ACID-Compliant Transactions__: + +Q. (phrased as a requirement) ACID-compliant transactions. While the overall Hyperledger system is eventually consistent, having a local datastore that is ACID compliant will simplify integration/implementation. + +A. v1 architecture separates execution (transaction simulation) and validation/commit phases. Upon commit, the transaction is indeed atomic, consistent, isolated (serializable), and durable. But clients working with endorsers and the chaincode needs to be designed with the understanding that the transaction is a proposal only, until such time that it is sent to peers for commitment. See NCAP document for more details: https://github.com/hyperledger/fabric/blob/master/proposals/r1/Next-Consensus-Architecture-Proposal.md + + +Q. (phrased as a requirement) Query the historical data + +A. New chaincode API in v1 `GetHistoryForKey()` will return history of values for a key. + +Q. (phrased as a requirement) Too much burden on chaincode to implement data access layer (such as DAO) to wrap KVS. + +A. v1 provides a broader and richer set of APIs that solutions have called for, including `GetStateByRange()`, `GetStateByPartialCompositeKey()`, `GetHistoryForKey()` against the default/embedded Key/Value data store. Also there is a beta option to use CouchDB JSON document store that enables rich query via a new GetQueryResult() API. The new rich query is intended to be used for read-only queries, but it can also be used in chaincode read-write transactions if the application layer can guarantee the stability of the query result set between transaction simulation and validation/commit phases (no phantoms). Research is investigating even richer data experience for future releases. Additionally, the new Composer offering is intended to make it simpler for developers to work with the fabric. + +__Data integrity constraint__: + +Q. Data integrity constraint is an important requirement from customer. For example, the balance of user bank account should always be non-negative. Is there any plan for data integrity constraint? + +A. Chaincode is the appropriate place to enforce data constraints. + +Q. How to guarantee the query result is correct, when the peer being queried is just recovering from failure and in the middle of the state transfer? + +A. New blocks are always being added to the blockchain, whether the peer is catching up or doing normal processing. The client can query multiple peers, compare their block heights, compare their query results, and favor the peers at the higher block heights. + +__The Missing/Altered Data Problem__: + +Q. (phrased as a requirement) Describe the minimal query results vs full set, how we can only do error detection. If we search for Shanghai, and get five results, and can verify the hashcode, that means that at a minimum there are five assets from Shanghai. However, there may in fact be more, but they may have been edited to say the location is Beijing. For those we can only detect that they are wrong, but we cannot correct them back to Shanghai. + +A. Is this a question about past state, or malicious tampering of data? If the former, there has been talk of solutions to sync data to a data warehouse for historical queries and analysis. If the latter, there is future work planned to audit the validity of the blockchain data, for example recalculate and compare hashes to prove/audit the data integrity of the blockchain. + +Q. (phrased as a requirement) No support for tables and range queries. Only simple GetState and PutState. + +A. There were many complaints and frustrations around the table API limitations in 0.5/0.6, since it added overhead but didn't enable typical table queries. v1 provides a broader and richer set of APIs that solutions have called for, including `GetStateByRange()`, `GetStateByPartialCompositeKey()`, `GetHistoryForKey()` against the default/embedded Key/Value data store. Also there is a beta option to use CouchDB JSON document store that enables rich query via a new GetQueryResult() API. The new rich query is intended to be used for read-only queries, but it can also be used in chaincode read-write transactions if the application layer can guarantee the stability of the query result set between transaction simulation and validation/commit phases (no phantoms). + +Q. (phrased as a requirement) Request for a Trusted Storage Service to store large files that are not appropriate to store in the world state and to replicate across all the peers. + +A. In traditional systems, it is very common to have a separate object storage to manage large object files aside from the DBMS. A common approach today is to only store the hash values of the files in the ledger and have the files managed somewhere else. There are three main problems for this approach. 1. the developer has to handle the interaction between the ledger and the object storage. 2. there is no good way to guarantee the consistency of the content between the ledger and the object storage. 3. the object storage has to be well secured, and protected by the access control in the same manner as the data on blockchain. Therefore, trusted storage service, that is integrated with blockchain is desired. + +Additional issues when most of the data is stored in an external data store, and the hash-codes used for verification and the linked-list data structures are stored in in the blockchain. This leads to the following problems: + + 2.1. Primary Data Store Schema/Behavior Changes — In order to track an asset and recall historical values, the whole point of provenance, the primary data store, which is external to blockchain, will need to store all historical versions of the documents. Without this, historical hash values stored on the blockchain are meaningless for navigating provenance. + + 2.2. Query-ability —The blockchain serves two purposes in the provenance solution as it stands today: data integrity and storing the graph of historical hash values of an asset. This means that for many types of queries, such as tell me all locations an asset has been at, the application server must perform data fusion between the lineage data, which is a sequence of document hashes, and the primary data store, which has been supplemented to store the document hashes necessary for quickly retrieving the documents referenced by the provenance graph’s hashes stored in the blockchain. + + 2.3. Data duplication — In part to overcome the query-ability challenges, some additional data should be duplicated in the primary data store. For example, to be able to easily traverse the history of an asset, it is helpful to store the hash of the previous document in the primary data store so that the application server is not required to perform data fusion between the data stored in the blockchain and the primary data store to show the provenance of an asset, such as all locations it has been at. + +It sounds like new v1 rich query and history APIs will help, but will not entirely address the requirement here. Please net out the specific remaining requirements for consideration post-v1. + + + +__Data Integration with Graph DB__: + +Q. Blockchain Integration Challenges for Provenance MVP. + +1. Manipulating/querying the opaque linked-list data structure stored in the values of the Hyperledger key-value store is not possible in a generic way. Custom chaincode that is able to interpret the opaque data structure is required. + 1.1. Thoughts: In graph databases, such as Neo4J, there are typically three data stores used to represent the various parts of a graph: 1) Nodes: a key-value store with the node id as the key, 2) Properties, and 3) Relationships. The most basic solution would be to allow us to use multiple key-value stores as part of the chaincode, but of course if we do that we might as well just focus on integrating an existing graph database. One good example of a graph database that in fact already uses rocksdb and is written in go is Dgraph. However, this data structure is not well-optimized for forward edge-chaining traversals, such as we want to use for traversing history. +2. Related to the thoughts mentioned in point 1, we really need a good way to do efficient graph edge/version traversal. Typical graph systems are optimized for answering questions such as "tell me the set of all friends of my friends" This only chains two edge traversals. We are mostly interested in much longer edge traversals. diff --git a/docs/Setup/NodeSDK-setup.md b/docs/Setup/NodeSDK-setup.md old mode 100644 new mode 100755 diff --git a/docs/adminops.md b/docs/adminops.md new file mode 100644 index 00000000000..985afb1c8c9 --- /dev/null +++ b/docs/adminops.md @@ -0,0 +1,4 @@ +# Administration and operations + +[WIP] +...coming soon diff --git a/docs/asset_cli.md b/docs/asset_cli.md new file mode 100644 index 00000000000..03c136b3220 --- /dev/null +++ b/docs/asset_cli.md @@ -0,0 +1,68 @@ +## Manually create and join peers to a new channel + +Use the cli container to manually exercise the create channel and join channel APIs. + +Channel - `myc1` already exists, so let's create a new channel named `myc2`. + +Exec into the cli container: +```bash +docker exec -it cli bash +``` +If successful, you should see the following in your terminal: +```bash +/opt/gopath/src/github.com/hyperledger/fabric/peer # +``` +Send createChannel API to Ordering Service: +``` +CORE_PEER_COMMITTER_LEDGER_ORDERER=orderer:7050 peer channel create -c myc2 +``` +This will return a genesis block - `myc2.block` - that you can issue join commands with. +Next, send a joinChannel API to `peer0` and pass in the genesis block as an argument. +The channel is defined within the genesis block: +``` +CORE_PEER_COMMITTER_LEDGER_ORDERER=orderer:7050 CORE_PEER_ADDRESS=peer0:7051 peer channel join -b myc2.block +``` +To join the other peers to the channel, simply reissue the above command with `peer1` +or `peer2` specified. For example: +``` +CORE_PEER_COMMITTER_LEDGER_ORDERER=orderer:7050 CORE_PEER_ADDRESS=peer1:7051 peer channel join -b myc2.block +``` +Once the peers have all joined the channel, you are able to issues queries against +any peer without having to deploy chaincode to each of them. + +## Use cli to deploy, invoke and query + +Run the deploy command. This command is deploying a chaincode named `mycc` to +`peer0` on the Channel ID `myc2`. The constructor message is initializing `a` and +`b` with values of 100 and 200 respectively. +``` +CORE_PEER_ADDRESS=peer0:7051 CORE_PEER_COMMITTER_LEDGER_ORDERER=orderer:7050 peer chaincode deploy -C myc2 -n mycc -p github.com/hyperledger/fabric/examples -c '{"Args":["init","a","100","b","200"]}' +``` +Run the invoke command. This invocation is moving 10 units from `a` to `b`. +``` +CORE_PEER_ADDRESS=peer0:7051 CORE_PEER_COMMITTER_LEDGER_ORDERER=orderer:7050 peer chaincode invoke -C myc2 -n mycc -c '{"function":"invoke","Args":["move","a","b","10"]}' +``` +Run the query command. The invocation transferred 10 units from `a` to `b`, therefore +a query against `a` should return the value 90. +``` +CORE_PEER_ADDRESS=peer0:7051 CORE_PEER_COMMITTER_LEDGER_ORDERER=orderer:7050 peer chaincode query -C myc2 -n mycc -c '{"function":"invoke","Args":["query","a"]}' +``` +You can issue an `exit` command at any time to exit the cli container. + +## Creating your initial channel through the cli + +If you want to manually create the initial channel through the cli container, you will +need to edit the Docker Compose file. Use an editor to open `docker-compose-gettingstarted.yml` and +comment out the `channel_test.sh` command in your cli image. Simply place a `#` to the left +of the command. (Recall that this script is executing the create and join channel +APIs when you run `docker-compose up`) For example: +```bash +cli: + container_name: cli + + working_dir: /opt/gopath/src/github.com/hyperledger/fabric/peer +# command: sh -c './channel_test.sh; sleep 1000' +# command: /bin/sh +``` + +Then use the cli commands from above. diff --git a/docs/asset_sdk.md b/docs/asset_sdk.md new file mode 100644 index 00000000000..d966a026744 --- /dev/null +++ b/docs/asset_sdk.md @@ -0,0 +1,31 @@ +## Use node SDK to register/enroll user, followed by deploy/invoke + +The individual javascript programs will exercise the SDK APIs to register and enroll the client with +the provisioned Certificate Authority. Once the client is properly authenticated, +the programs will demonstrate basic chaincode functionalities - deploy, invoke, and query. Make +sure you are in the working directory where you pulled the source code before proceeding. + +Upon success of each node program, you will receive a "200" response in the terminal. + +Register/enroll & deploy chaincode (Linux or OSX): +```bash +# Deploy initializes key value pairs of "a","100" & "b","200". +GOPATH=$PWD node deploy.js +``` +Register/enroll & deploy chaincode (Windows): +```bash +# Deploy initializes key value pairs of "a","100" & "b","200". +SET GOPATH=%cd% +node deploy.js +``` +Issue an invoke. Move units 100 from "a" to "b": +```bash +node invoke.js +``` +Query against key value "b": +```bash +# this should return a value of 300 +node query.js +``` +Explore the various node.js programs, along with `example_cc.go` to better understand +the SDK and APIs. diff --git a/docs/asset_setup.md b/docs/asset_setup.md new file mode 100644 index 00000000000..3a6c3bddf81 --- /dev/null +++ b/docs/asset_setup.md @@ -0,0 +1,134 @@ +## Prerequisites and setup + +* [Go](https://golang.org/) - most recent version +* [Docker](https://www.docker.com/products/overview) - v1.13 or higher +* [Docker Compose](https://docs.docker.com/compose/overview/) - v1.8 or higher +* [Node.js & npm](https://nodejs.org/en/download/) - node v6.9.5 and npm v3.10.10 +* [xcode](https://developer.apple.com/xcode/) - only required for OS X users +* [nvm](https://github.com/creationix/nvm/blob/master/README.markdown) - if you want to use `nvm install` command +If you already have node on your machine, use the node website to install v6.9.5 or +issue the following command in your terminal: +```bash +nvm install v6.9.5 +``` +then execute the following to see your versions: +```bash +# should be 6.9.5 +node -v +``` +AND +```bash +# should be 3.10.10 +npm -v +``` + +## Curl the source code to create network entities + +* Download the [cURL](https://curl.haxx.se/download.html) tool if not already installed. +* Determine a location on your local machine where you want to place the Fabric artifacts and application code. +```bash +mkdir -p /hackfest +cd /hackfest +``` +Next, execute the following command: +```bash +curl -L https://raw.githubusercontent.com/hyperledger/fabric/master/examples/sfhackfest/sfhackfest.tar.gz -o sfhackfest.tar.gz 2> /dev/null; tar -xvf sfhackfest.tar.gz +``` +This command pulls and extracts all of the necessary artifacts to set up your +network - Docker Compose script, channel generate/join script, crypto material +for identity attestation, etc. In the `/src/github.com/example_cc` directory you +will find the chaincode that will be deployed. + +Your directory should contain the following: +```bash +JDoe-mbp: JohnDoe$ pwd +/Users/JohnDoe +JDoe-mbp: JohnDoe$ ls +sfhackfest.tar.gz channel_test.sh src +ccenv docker-compose-gettingstarted.yml tmp +``` + +## Using Docker + +You do not need to manually pull any images. The images for - `fabric-peer`, +`fabric-orderer`, `fabric-ca`, and `cli` are specified in the .yml file and will +automatically download, extract, and run when you execute the `docker-compose` command. + +## Commands + +The channel commands are: + +* `create` - create and name a channel in the `orderer` and get back a genesis +block for the channel. The genesis block is named in accordance with the channel name. +* `join` - use the genesis block from the `create` command to issue a join +request to a peer. + +## Use Docker to spawn network entities & create/join a channel + +Ensure the hyperledger/fabric-ccenv image is tagged as latest: +```bash +docker-compose -f docker-compose-gettingstarted.yml build +``` +Create network entities, create channel, join peers to channel: +```bash +docker-compose -f docker-compose-gettingstarted.yml up -d +``` +Behind the scenes this started six containers (3 peers, a "solo" orderer, cli and CA) +in detached mode. A script - `channel_test.sh` - embedded within the +`docker-compose-gettingstarted.yml` issued the create channel and join channel +commands within the CLI container. In the end, you are left with a network and +a channel containing three peers - peer0, peer1, peer2. + +View your containers: +```bash +# if you have no other containers running, you will see six +docker ps +``` +Ensure the channel has been created and peers have successfully joined: +```bash +docker exec -it cli bash +``` +You should see the following in your terminal: +```bash +/opt/gopath/src/github.com/hyperledger/fabric/peer # +``` +To view results for channel creation/join: +```bash +more results.txt +``` +You're looking for: +```bash +SUCCESSFUL CHANNEL CREATION +SUCCESSFUL JOIN CHANNEL on PEER0 +SUCCESSFUL JOIN CHANNEL on PEER1 +SUCCESSFUL JOIN CHANNEL on PEER2 +``` + +To view genesis block: +```bash +more myc1.block +``` + +Exit the cli container: +```bash +exit +``` + +## Curl the application source code and SDK modules + +* Prior to issuing the command, make sure you are in the same working directory +where you curled the network code. AND make sure you have exited the cli container. +* Execute the following command: +```bash +curl -OOOOOO https://raw.githubusercontent.com/hyperledger/fabric-sdk-node/v1.0-alpha/examples/balance-transfer/{config.json,deploy.js,helper.js,invoke.js,query.js,package.json} +``` + +This command pulls the javascript code for issuing your deploy, invoke and query calls. +It also retrieves dependencies for the node SDK modules. + +* Install the node modules: +```bash +# You may be prompted for your root password at one or more times during this process. +npm install +``` +You now have all of the necessary prerequisites and Fabric artifacts. diff --git a/docs/asset_trouble.md b/docs/asset_trouble.md new file mode 100644 index 00000000000..adc921ad9d8 --- /dev/null +++ b/docs/asset_trouble.md @@ -0,0 +1,124 @@ +## Troubleshooting + +If you have existing containers running, you may receive an error indicating that a port is +already occupied. If this occurs, you will need to kill the container that is using said port. + +If a file cannot be located, make sure your curl commands executed successfully and make +sure you are in the directory where you pulled the source code. + +If you are receiving timeout or GRPC communication errors, make sure you have the +correct version of Docker installed - v1.13.0. Then try restarting your failing +docker process. For example: +```bash +docker stop peer0 +``` +Then: +```bash +docker start peer0 +``` + +Another approach to GRPC and DNS errors (peer failing to resolve with orderer and vice +versa) is to hardcode the IP addresses for each. You will know if there is a DNS +issue, because a `more results.txt` command within the cli container will display +something similar to: +```bash +ERROR CREATING CHANNEL +PEER0 ERROR JOINING CHANNEL +``` + +Issue a `docker inspect ` to ascertain the IP address. For example: +```bash +docker inspect peer0 | grep IPAddress +``` +AND +```bash +docker inspect orderer | grep IPAddress +``` +Take these values and hard code them into your cli commands. For example: +```bash +CORE_PEER_COMMITTER_LEDGER_ORDERER=172.21.0.2:7050 peer channel create -c myc1 +``` +AND THEN +```bash +CORE_PEER_COMMITTER_LEDGER_ORDERER= CORE_PEER_ADDRESS= peer channel join -b myc1.block +``` + +If you are seeing errors while using the node SDK, make sure you have the correct versions +of node.js and npm installed on your machine. You want node v6.9.5 and npm v3.10.10. + +If you ran through the automated channel create/join process (i.e. did not comment out +`channel_test.sh` in the `docker-compose-gettingstarted.yml`), then channel - `myc1` - and +genesis block - `myc1.block` - have already been created and exist on your machine. +As a result, if you proceed to execute the manual steps in your cli container: +``` +CORE_PEER_COMMITTER_LEDGER_ORDERER=orderer:7050 peer channel create -c myc1 +``` +Then you will run into an error similar to: +``` + UTC [msp] Sign -> DEBU 064 Sign: digest: 5ABA6805B3CDBAF16C6D0DCD6DC439F92793D55C82DB130206E35791BCF18E5F +Error: Got unexpected status: BAD_REQUEST +Usage: + peer channel create [flags] +``` +This occurs because you are attempting to create a channel named `myc1`, and this channel +already exists! There are two options. Try issuing the peer channel create command +with a different channel name - `myc2`. For example: +``` +CORE_PEER_COMMITTER_LEDGER_ORDERER=orderer:7050 peer channel create -c myc2 +``` +Then join: +``` +CORE_PEER_COMMITTER_LEDGER_ORDERER=orderer:7050 CORE_PEER_ADDRESS=peer0:7051 peer channel join -b myc2.block +``` + +If you do choose to create a new channel, and want to run deploy/invoke/query with +the node.js programs, you also need to edit the "channelID" parameter in the +`config.json` file to match the new channel's name. For example: +``` +{ + "chainName":"fabric-client1", + "chaincodeID":"mycc", + "channelID":"myc2", + "goPath":"../../test/fixtures", + "chaincodePath":"github.com/example_cc", +``` + +OR, if you want your channel called - `myc1` -, remove your docker containers and +then follow the same commands in the __Manually create and join peers to a new channel__ +topic. + +## Clean up + +Shut down your containers: +```bash +docker-compose -f docker-compose-gettingstarted.yml down +``` + +## Helpful Docker tips + +Remove a specific docker container: +```bash +docker rm +``` +Force removal: +```bash +docker rm -f +``` +Remove all docker containers: +```bash +docker rm -f $(docker ps -aq) +``` +This will merely kill docker containers (i.e. stop the process). You will not lose any images. + +Remove an image: +```bash +docker rmi +``` +Forcibly remove: +```bash +docker rmi -f +``` +Remove all images: +```bash +docker rmi -f $(docker images -q) +``` diff --git a/docs/auction.md b/docs/auction.md new file mode 100644 index 00000000000..1c743ab2f20 --- /dev/null +++ b/docs/auction.md @@ -0,0 +1,11 @@ +# Art Auction + +[WIP] +...coming soon + +Shows the provenance, attestation, and ownership of a piece of artwork and the +ensuing interaction of the various stakeholders. Not yet stable with v1 codebase. + +Learn more about the components [here](https://github.com/ITPeople-Blockchain/auction) + +Learn more about the client-side application [here](https://github.com/ITPeople-Blockchain/auction-app) diff --git a/docs/blockchain.md b/docs/blockchain.md new file mode 100644 index 00000000000..2f1515d5a79 --- /dev/null +++ b/docs/blockchain.md @@ -0,0 +1,3 @@ +# Why blockchain? + +...coming soon diff --git a/docs/bootstrap.md b/docs/bootstrap.md new file mode 100644 index 00000000000..9c62d74fe2a --- /dev/null +++ b/docs/bootstrap.md @@ -0,0 +1,9 @@ +# Starting a network + +[WIP] +...coming soon + +Intended to contain the recommended steps for generating prerequisite cryptographic +material and then bootstrapping an ordering service (i.e. overall network) with +participating organizations, ordering node certificates, load balancing, configuration, +policies, etc... diff --git a/docs/capabilities.md b/docs/capabilities.md new file mode 100644 index 00000000000..935abcc8fd0 --- /dev/null +++ b/docs/capabilities.md @@ -0,0 +1,5 @@ +## Capabilities + +...coming soon + +Identity Management, Privacy, Confidentiality, Throughput, Chaincode, Modularity diff --git a/docs/carlease.md b/docs/carlease.md new file mode 100644 index 00000000000..4146668448b --- /dev/null +++ b/docs/carlease.md @@ -0,0 +1,9 @@ +# Car Lease + +[WIP] +...coming soon + +Uses the blockchain to record the lifecycle of a vehicle from materials provenance, +manufacture, buyer, all the way to scrap yard. Not yet stable with v1 codebase. + +Learn more about the application and underlying chaincode [here](https://github.com/IBM-Blockchain/car-lease-demo) diff --git a/docs/chaincode.md b/docs/chaincode.md new file mode 100644 index 00000000000..5b1b69cee6b --- /dev/null +++ b/docs/chaincode.md @@ -0,0 +1,343 @@ +# 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 interaction with that +network's shared ledger. + +There are three aspects to chaincode development: +* The interfaces that the chaincode should implement +* APIs the chaincode can use to interact with the Fabric +* A chaincode response + +## Chaincode interfaces + +A chaincode implements the Chaincode Interface that supports two methods: +* `Init` +* `Invoke` + +#### Init() + +Init is called when you first deploy your chaincode. As the name implies, this +function is used to do any initialization your chaincode needs. + +#### Invoke() + +Invoke is called when you want to call chaincode functions to do real work (i.e. read +and write to the ledger). Invocations are captured as transactions, which get +grouped into blocks on the chain. When you need to update or query the ledger, +you do so by invoking your chaincode. + +## Dependencies + +The import statement lists a few dependencies for the chaincode to compile successfully. +* fmt – contains Println for debugging/logging. +* errors – standard go error format. +* [shim](https://github.com/hyperledger/fabric/tree/master/core/chaincode/shim) – +contains the definitions for the chaincode interface and the chaincode stub, +which you are required to interact with the ledger. + +## Chaincode APIs + +When the Init or Invoke function of a chaincode is called, the fabric passes the +`stub shim.ChaincodeStubInterface` parameter and the chaincode returns a `pb.Response`. +This stub can be used to call APIs to access to the ledger services, transaction +context, or to invoke other chaincodes. + +The current APIs are defined in the shim package, and can be generated with the +following command: +```bash +godoc github.com/hyperledger/fabric/core/chaincode/shim +``` +However, it also includes functions from chaincode.pb.go (protobuffer functions) +that are not intended as public APIs. The best practice is to look at the function +definitions in chaincode.go and and the +[examples](https://github.com/hyperledger/fabric/tree/master/examples/chaincode/go) +directory. + +## Response + +The chaincode response comes in the form of a protobuffer. + +```go +message Response { + + // A status code that should follow the HTTP status codes. + int32 status = 1; + + // A message associated with the response code. + string message = 2; + + // A payload that can be used to include metadata with this response. + bytes payload = 3; + +} +``` +The chaincode will also return events. Message events and chaincode events. +```go +messageEvent { + + oneof Event { + + //Register consumer sent event + Register register = 1; + + //producer events common. + Block block = 2; + ChaincodeEvent chaincodeEvent = 3; + Rejection rejection = 4; + + //Unregister consumer sent events + Unregister unregister = 5; + + } + +} +``` + +```go +messageChaincodeEvent { + + string chaincodeID = 1; + string txID = 2; + string eventName = 3; + bytes payload = 4; + +} +``` + +Once developed and deployed, there are two ways to interact with the chaincode - +through an SDK or the CLI. The steps for CLI are described below. For SDK interaction, +refer to the [balance transfer](https://github.com/hyperledger/fabric-sdk-node/tree/master/examples/balance-transfer) +samples. __Note__: This SDK interaction is covered in the __Getting Started__ section. + +## Command Line Interfaces + +To view the currently available CLI commands, execute the following: +```bash +# this assumes that you have correctly set the GOPATH variable and cloned the Fabric codebase into that path +cd /opt/gopath/src/github.com/hyperledger/fabric +build /bin/peer +``` +You will see output similar to the example below. (__NOTE__: rootcommand below is +hardcoded in main.go. Currently, the build will create a _peer_ executable file). +```bash +Usage: + peer [flags] + peer [command] + + Available Commands: + version Print fabric peer version. + node node specific commands. + channel channel specific commands. + chaincode chaincode specific commands. + logging logging specific commands + + + Flags: + --logging-level string: Default logging level and overrides, see core.yaml for full syntax + --test.coverprofile string: Done (default “coverage.cov) + -v, --version: Display current version of fabric peer server + Use "peer [command] --help" for more information about a command. +``` +The `peer` command supports several subcommands and flags, as shown above. To +facilitate its use in scripted applications, the `peer` command always produces a +non-zero return code in the event of command failure. Upon success, many of the +subcommands produce a result on stdout as shown in the table below: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +Command + + + +stdout result in the event of success + +
+ +version + + + +String form of peer.version defined in core.yaml + +
+ +node start + + + +N/A + +
+ +node status + + + +String form of StatusCode + +
+ +node stop + + + +String form of StatusCode + +
+ +chaincode deploy + + + +The chaincode container name (hash) required for subsequent chaincode invoke and chaincode query commands + +
+ +chaincode invoke + + + +The transaction ID (UUID) + +
+ +chaincode query + + + +By default, the query result is formatted as a printable + +
+ +channel create + + + +Create a chain + +
+ +channel join + + + +Adds a peer to the chain + +
+ +
--peer-defaultchain=true
+ +		 + + Allows users to continue to work with the default TEST_CHAINID string. Command line options support writing this value as raw bytes (-r, –raw) or formatted as the hexadecimal representation of the raw bytes (-x, –hex). If the query response is empty then nothing is output. + +
+ +## Deploy a chaincode + +[WIP] - the CLI commands need to be refactored based on the new deployment model. +Channel Create and Channel Join will remain the same. diff --git a/docs/channels.md b/docs/channels.md new file mode 100644 index 00000000000..b61e3e8847a --- /dev/null +++ b/docs/channels.md @@ -0,0 +1,3 @@ +## Channels + +...coming soon diff --git a/docs/committer.md b/docs/committer.md new file mode 100644 index 00000000000..acd713a9fc9 --- /dev/null +++ b/docs/committer.md @@ -0,0 +1,7 @@ +# Committing Peer + +[WIP] +...coming soon + +This topic will explain the peer's runtime and role as a committer for transactions +on a channel. In the meantime, refer to the [high-level data flow](https://jira.hyperledger.org/browse/FAB-37). diff --git a/docs/components.md b/docs/components.md new file mode 100644 index 00000000000..e8b6c0ac4f3 --- /dev/null +++ b/docs/components.md @@ -0,0 +1,7 @@ +# Components + +[WIP] +...coming soon + +This topic will contain a diagram explaining the various components of a blockchain +network and their corresponding roles. diff --git a/docs/consensus.md b/docs/consensus.md new file mode 100644 index 00000000000..8aee49ecece --- /dev/null +++ b/docs/consensus.md @@ -0,0 +1,12 @@ +# Consensus + +[WIP] + +Not to be conflated with the ordering process. Consensus in v1 architecture is a +broader term overarching the entire transactional flow, which +serves to generate an agreement on the order and to confirm the correctness of +the set of transactions constituting a block. + +It is achieved as a byproduct of the various steps and verifications that occur during +a transaction's lifecycle from proposal to commitment. More information on the +high-level data flows is available [here](https://jira.hyperledger.org/browse/FAB-37). diff --git a/docs/data_model.md b/docs/data_model.md new file mode 100644 index 00000000000..c0e8555fcb3 --- /dev/null +++ b/docs/data_model.md @@ -0,0 +1,36 @@ +# Transaction Model + +[WIP] + +The Fabric transaction model is a complete, self-encapsulated immutable record +of the state transition on the ledger of the participating parties. It contains +a chaincode function call, versioned inputs (referred to as the read set), and +outputs (referred to as the write set). The read-write-sets are the actual states +making up the multi-version concurrency control, which serves to grant an +appropriate version to each read request. Transactions issuing write requests +which might destroy database integrity are aborted at the "validation" phase to +counter against malicious threats such as double-spending. + +Transactions are appended in order of processing to an append-only log with +cryptographic links to prevent any modification to the records. There is no +limit on the log size except available physical storage space. + +States are data variables of any type represented by binary or text (JSON) format; +they are scoped and manipulated by chaincodes running on a ledger. A chaincode +function reads and writes states (read-write set) in the context of a transaction +proposal, which is endorsed by the counter-parties specified for the chaincode. +The endorsed proposal is submitted to the network as a transaction for ordering, +validation, and then committal to the ledger within a block. + +Before committal, peers will make sure that the transaction has been both adequately, +and properly endorsed (i.e. the correct allotment of the specified peers have +signed the proposal, and these signatures have been authenticated) - this is +referred to as validation. Secondly, a versioning check will occur to ensure +that the key value pairs affected by this transaction have not been altered +since simulation of the proposal. Or put another way, the world state for this +chaincode still mirrors the world state used for the inputs. If these conditions +are met, then this transaction is written to the ledger and the versions of the +keys, along with their new values, are updated in the world state. + +See the [Read Write Set](readwrite.md) topic for a deeper dive on transaction +structure, MVCC and the state DB. diff --git a/docs/debug.md b/docs/debug.md new file mode 100644 index 00000000000..0ee777b477d --- /dev/null +++ b/docs/debug.md @@ -0,0 +1,4 @@ +# Debugging & Logging + +[WIP] +...coming soon diff --git a/docs/dockercompose.md b/docs/dockercompose.md new file mode 100644 index 00000000000..8a92ed31ae7 --- /dev/null +++ b/docs/dockercompose.md @@ -0,0 +1,9 @@ +# Docker Compose + +[WIP] +...coming soon + +This section will explain how to use Docker Compose to stand up the necessary +components for a blockchain network. The various environment variables +correlated to each image will be explained, and different configurations will +be outlined. diff --git a/docs/endorser.md b/docs/endorser.md new file mode 100644 index 00000000000..a03ab3e9445 --- /dev/null +++ b/docs/endorser.md @@ -0,0 +1,7 @@ +# Endorsing Peer + +[WIP] +...coming soon + +This topic will explain the peer's runtime and role as an endorser for a certain +piece of chaincode. In the meantime, refer to the [high-level data flow](https://jira.hyperledger.org/browse/FAB-37). diff --git a/docs/gettingstarted.md b/docs/gettingstarted.md deleted file mode 100644 index 29f9d767567..00000000000 --- a/docs/gettingstarted.md +++ /dev/null @@ -1,371 +0,0 @@ -# Getting Started with v1.0 Hyperledger Fabric - App Developers -This document demonstrates an example using the Hyperledger Fabric V1.0 architecture. -The scenario will include the creation and joining of channels, client side authentication, -and the deployment and invocation of chaincode. CLI will be used for the creation and -joining of the channel and the node SDK will be used for the client authentication, -and chaincode functions utilizing the channel. - -Docker Compose will be used to create a consortium of three organizations, each -running an endorsing/committing peer, as well as a "solo" orderer and a Certificate Authority (CA). -The cryptographic material, based on standard PKI implementation, has been pre-generated -and is included in the `sfhackfest.tar.gz` in order to expedite the flow. The CA, responsible for -issuing, revoking and maintaining the crypto material represents one of the organizations and -is needed by the client (node SDK) for authentication. In an enterprise scenario, each -organization might have their own CA, with more complex security measures implemented - e.g. -cross-signing certificates, etc. - -The network will be generated automatically upon execution of `docker-compose up`, -and the APIs for create channel and join channel will be explained and demonstrated; -as such, a user can go through the steps to manually generate their own network -and channel, or quickly jump to the application development phase. - -## Prerequisites and setup - -* [Docker](https://www.docker.com/products/overview) - v1.12 or higher -* [Docker Compose](https://docs.docker.com/compose/overview/) - v1.8 or higher -* [Node.js](https://nodejs.org/en/download/) - comes with the node package manager (npm). -If you already have npm on your machine, issue the following command to retrieve the latest package: -```bash -npm install npm@latest -``` -then execute the following to see your version: -```bash -npm -v -``` -You're looking for a version higher than 2.1.8. - -## Curl the source code to create network entities - -* Download the [cURL](https://curl.haxx.se/download.html) tool if not already installed. -* Determine a location on your local machine where you want to place the Fabric artifacts and application code. -```bash -mkdir -p /hackfest -cd /hackfest -``` -Next, execute the following command: -```bash -curl -L https://raw.githubusercontent.com/hyperledger/fabric/master/examples/sfhackfest/sfhackfest.tar.gz -o sfhackfest.tar.gz 2> /dev/null; tar -xvf sfhackfest.tar.gz -``` -This command pulls and extracts all of the necessary artifacts to set up your -network - Docker Compose script, channel generate/join script, crypto material -for identity attestation, etc. In the `/src/github.com/example_cc` directory you -will find the chaincode that will be deployed. - -Your directory should contain the following: -```bash -JDoe-mbp: JohnDoe$ pwd -/Users/JohnDoe -JDoe-mbp: JohnDoe$ ls -sfhackfest.tar.gz channel_test.sh src -ccenv docker-compose-gettingstarted.yml tmp -``` - -## Using Docker - -You do not need to manually pull any images. The images for - `fabric-peer`, -`fabric-orderer`, `fabric-ca`, and `cli` are specified in the .yml file and will -automatically download, extract, and run when you execute the `docker-compose` command. - -## Commands - -The channel commands are: - -* `create` - create and name a channel in the `orderer` and get back a genesis -block for the channel. The genesis block is named in accordance with the channel name. -* `join` - use the genesis block from the `create` command to issue a join -request to a peer. - -## Use Docker to spawn network entities & create/join a channel - -Ensure the hyperledger/fabric-ccenv image is tagged as latest: -```bash -docker-compose -f docker-compose-gettingstarted.yml build -``` -Create network entities, create channel, join peers to channel: -```bash -docker-compose -f docker-compose-gettingstarted.yml up -d -``` -Behind the scenes this started six containers (3 peers, a "solo" orderer, cli and CA) -in detached mode. A script - `channel_test.sh` - embedded within the -`docker-compose-gettingstarted.yml` issued the create channel and join channel -commands within the CLI container. In the end, you are left with a network and -a channel containing three peers - peer0, peer1, peer2. - -View your containers: -```bash -# if you have no other containers running, you will see six -docker ps -``` -Ensure the channel has been created and peers have successfully joined: -```bash -docker exec -it cli bash -``` -You should see the following in your terminal: -```bash -/opt/gopath/src/github.com/hyperledger/fabric/peer # -``` -To view results for channel creation/join: -```bash -more results.txt -``` -You're looking for: -```bash -SUCCESSFUL CHANNEL CREATION -SUCCESSFUL JOIN CHANNEL on PEER0 -SUCCESSFUL JOIN CHANNEL on PEER1 -SUCCESSFUL JOIN CHANNEL on PEER2 -``` - -To view genesis block: -```bash -more myc1.block -``` - -Exit the cli container: -```bash -exit -``` - -## Curl the application source code and SDK modules - -* Prior to issuing the command, make sure you are in the same working directory -where you curled the network code. AND make sure you have exited the cli container. -* Execute the following command: -```bash -curl -OOOOOO https://raw.githubusercontent.com/hyperledger/fabric-sdk-node/master/examples/balance-transfer/{config.json,deploy.js,helper.js,invoke.js,query.js,package.json} -``` - -This command pulls the javascript code for issuing your deploy, invoke and query calls. -It also retrieves dependencies for the node SDK modules. - -* Install the node modules: -```bash -# You may be prompted for your root password at one or more times during this process. -npm install -``` -You now have all of the necessary prerequisites and Fabric artifacts. - -## Use node SDK to register/enroll user and deploy/invoke/query - -The individual javascript programs will exercise the SDK APIs to register and enroll the client with -the provisioned Certificate Authority. Once the client is properly authenticated, -the programs will demonstrate basic chaincode functionalities - deploy, invoke, and query. Make -sure you are in the working directory where you pulled the source code before proceeding. - -Upon success of each node program, you will receive a "200" response in the terminal. - -Register/enroll & deploy chaincode (Linux or OSX): -```bash -# Deploy initializes key value pairs of "a","100" & "b","200". -GOPATH=$PWD node deploy.js -``` -Register/enroll & deploy chaincode (Windows): -```bash -# Deploy initializes key value pairs of "a","100" & "b","200". -SET GOPATH=%cd% -node deploy.js -``` -Issue an invoke. Move units 100 from "a" to "b": -```bash -node invoke.js -``` -Query against key value "b": -```bash -# this should return a value of 300 -node query.js -``` -Explore the various node.js programs, along with `example_cc.go` to better understand -the SDK and APIs. - -## Manually create and join peers to a new channel - -Use the cli container to manually exercise the create channel and join channel APIs. - -Channel - `myc1` already exists, so let's create a new channel named `myc2`. - -Exec into the cli container: -```bash -docker exec -it cli bash -``` -If successful, you should see the following in your terminal: -```bash -/opt/gopath/src/github.com/hyperledger/fabric/peer # -``` -Send createChannel API to Ordering Service: -``` -CORE_PEER_COMMITTER_LEDGER_ORDERER=orderer:7050 peer channel create -c myc2 -``` -This will return a genesis block - `myc2.block` - that you can issue join commands with. -Next, send a joinChannel API to `peer0` and pass in the genesis block as an argument. -The channel is defined within the genesis block: -``` -CORE_PEER_COMMITTER_LEDGER_ORDERER=orderer:7050 CORE_PEER_ADDRESS=peer0:7051 peer channel join -b myc2.block -``` -To join the other peers to the channel, simply reissue the above command with `peer1` -or `peer2` specified. For example: -``` -CORE_PEER_COMMITTER_LEDGER_ORDERER=orderer:7050 CORE_PEER_ADDRESS=peer1:7051 peer channel join -b myc2.block -``` -Once the peers have all joined the channel, you are able to issues queries against -any peer without having to deploy chaincode to each of them. - -## Use cli to deploy, invoke and query - -Run the deploy command. This command is deploying a chaincode named `mycc` to -`peer0` on the Channel ID `myc2`. The constructor message is initializing `a` and -`b` with values of 100 and 200 respectively. -``` -CORE_PEER_ADDRESS=peer0:7051 CORE_PEER_COMMITTER_LEDGER_ORDERER=orderer:7050 peer chaincode deploy -C myc2 -n mycc -p github.com/hyperledger/fabric/examples -c '{"Args":["init","a","100","b","200"]}' -``` -Run the invoke command. This invocation is moving 10 units from `a` to `b`. -``` -CORE_PEER_ADDRESS=peer0:7051 CORE_PEER_COMMITTER_LEDGER_ORDERER=orderer:7050 peer chaincode invoke -C myc2 -n mycc -c '{"function":"invoke","Args":["move","a","b","10"]}' -``` -Run the query command. The invocation transferred 10 units from `a` to `b`, therefore -a query against `a` should return the value 90. -``` -CORE_PEER_ADDRESS=peer0:7051 CORE_PEER_COMMITTER_LEDGER_ORDERER=orderer:7050 peer chaincode query -C myc2 -n mycc -c '{"function":"invoke","Args":["query","a"]}' -``` -You can issue an `exit` command at any time to exit the cli container. - -## Creating your initial channel through the cli - -If you want to manually create the initial channel through the cli container, you will -need to edit the Docker Compose file. Use an editor to open `docker-compose-gettingstarted.yml` and -comment out the `channel_test.sh` command in your cli image. Simply place a `#` to the left -of the command. (Recall that this script is executing the create and join channel -APIs when you run `docker-compose up`) For example: -```bash -cli: - container_name: cli - - working_dir: /opt/gopath/src/github.com/hyperledger/fabric/peer -# command: sh -c './channel_test.sh; sleep 1000' -# command: /bin/sh -``` - -Then use the cli commands from the prior two sections. - -## Troubleshooting (optional) - -If you have existing containers running, you may receive an error indicating that a port is -already occupied. If this occurs, you will need to kill the container that is using said port. - -If a file cannot be located, make sure your curl commands executed successfully and make -sure you are in the directory where you pulled the source code. - -If you are receiving timeout or GRPC communication errors, try restarting your -failing docker process. For example: -```bash -docker stop peer0 -``` -Then: -```bash -docker start peer0 -``` - -Another approach to GRPC and DNS errors (peer failing to resolve with orderer and vice -versa) is to hardcode the IP addresses for each. You will know if there is a DNS -issue, because a `more results.txt` command within the cli container will display -something similar to: -```bash -ERROR CREATING CHANNEL -PEER0 ERROR JOINING CHANNEL -``` - -Issue a `docker inspect ` to ascertain the IP address. For example: -```bash -docker inspect peer0 | grep IPAddress -``` -AND -```bash -docker inspect orderer | grep IPAddress -``` -Take these values and hard code them into your cli commands. For example: -```bash -CORE_PEER_COMMITTER_LEDGER_ORDERER=172.21.0.2:7050 peer channel create -c myc1 -``` -AND THEN -```bash -CORE_PEER_COMMITTER_LEDGER_ORDERER= CORE_PEER_ADDRESS= peer channel join -b myc1.block -``` - -If you are seeing errors while using the node SDK, make sure you have a current version -of node.js and npm installed on your machine. - -If you ran through the automated channel create/join process (i.e. did not comment out -`channel_test.sh` in the `docker-compose-gettingstarted.yml`), then channel - `myc1` - and -genesis block - `myc1.block` - have already been created and exist on your machine. -As a result, if you proceed to execute the manual steps in your cli container: -``` -CORE_PEER_COMMITTER_LEDGER_ORDERER=orderer:7050 peer channel create -c myc1 -``` -Then you will run into an error similar to: -``` - UTC [msp] Sign -> DEBU 064 Sign: digest: 5ABA6805B3CDBAF16C6D0DCD6DC439F92793D55C82DB130206E35791BCF18E5F -Error: Got unexpected status: BAD_REQUEST -Usage: - peer channel create [flags] -``` -This occurs because you are attempting to create a channel named `myc1`, and this channel -already exists! There are two options. Try issuing the peer channel create command -with a different channel name - `myc2`. For example: -``` -CORE_PEER_COMMITTER_LEDGER_ORDERER=orderer:7050 peer channel create -c myc2 -``` -Then join: -``` -CORE_PEER_COMMITTER_LEDGER_ORDERER=orderer:7050 CORE_PEER_ADDRESS=peer0:7051 peer channel join -b myc2.block -``` - -If you do choose to create a new channel, and want to run deploy/invoke/query with -the node.js programs, you also need to edit the "channelID" parameter in the -`config.json` file to match the new channel's name. For example: -``` -{ - "chainName":"fabric-client1", - "chaincodeID":"mycc", - "channelID":"myc2", - "goPath":"../../test/fixtures", - "chaincodePath":"github.com/example_cc", -``` - -OR, if you want your channel called - `myc1` -, remove your docker containers and -then follow the same commands in the __Manually create and join peers to a new channel__ -section. - -## Clean up - -Shut down your containers: -```bash -docker-compose -f docker-compose-gettingstarted.yml down -``` - -## Helpful Docker tips - -Remove a specific docker container: -```bash -docker rm -``` -Force removal: -```bash -docker rm -f -``` -Remove all docker containers: -```bash -docker rm -f $(docker ps -aq) -``` -This will merely kill docker containers (i.e. stop the process). You will not lose any images. - -Remove an image: -```bash -docker rmi -``` -Forcibly remove: -```bash -docker rmi -f -``` -Remove all images: -```bash -docker rmi -f $(docker images -q) -``` diff --git a/docs/gossip.md b/docs/gossip.md new file mode 100644 index 00000000000..8726654bbef --- /dev/null +++ b/docs/gossip.md @@ -0,0 +1,3 @@ +## Gossip data dissemination protocol + +...coming soon diff --git a/docs/included.md b/docs/included.md new file mode 100644 index 00000000000..a7db3f94c68 --- /dev/null +++ b/docs/included.md @@ -0,0 +1,24 @@ +# What's Included? + +This section demonstrates an example using the Hyperledger Fabric V1.0 architecture. +The scenario will include the creation and joining of channels, client side authentication, +and the deployment and invocation of chaincode. CLI will be used for the creation and +joining of the channel and the node SDK will be used for the client authentication, +and chaincode functions utilizing the channel. + +Docker Compose will be used to create a consortium of three organizations, each +running an endorsing/committing peer, as well as a "solo" orderer and a Certificate Authority (CA). +The cryptographic material, based on standard PKI implementation, has been pre-generated +and is included in the `sfhackfest.tar.gz` in order to expedite the flow. The CA, responsible for +issuing, revoking and maintaining the crypto material, represents one of the organizations and +is needed by the client (node SDK) for authentication. In an enterprise scenario, each +organization might have their own CA, with more complex security measures implemented - e.g. +cross-signing certificates, etc. + +The network will be generated automatically upon execution of `docker-compose up`, +and the APIs for create channel and join channel will be explained and demonstrated; +as such, a user can go through the steps to manually generate their own network +and channel, or quickly jump to the application development phase. + +It is recommended to run through this section in the order it is laid out - node +program first, followed by the CLI approach. diff --git a/docs/incubation.md b/docs/incubation.md new file mode 100644 index 00000000000..cf9f0b2969a --- /dev/null +++ b/docs/incubation.md @@ -0,0 +1,6 @@ +# Incubation Notice + +This project is a Hyperledger project in _Incubation_. It was proposed to the +community and documented [here](https://goo.gl/RYQZ5N). Information on what +_Incubation_ entails can be found in the [Hyperledger Project Lifecycle +document](https://goo.gl/4edNRc). diff --git a/docs/index.md b/docs/index.md index 75a4fc6fba7..419ada2c418 100644 --- a/docs/index.md +++ b/docs/index.md @@ -5,93 +5,17 @@ # Hyperledger Fabric -The Hyperledger Fabric is an implementation of blockchain technology, -leveraging familiar and proven technologies. It offers a modular -[architecture](architecture.md) allowing pluggable implementations of -various capabilities, such as smart contracts (chaincode), cryptography, -consensus, ledger datastore and more. It leverages powerful container technology -for its deployment and for providing the execution environment for the smart -contracts (chaincode) such that the network is protected from malicious code. - -## Get Hyperledger Fabric - -The Fabric releases are documented [here](releases.md). We -published our second release under the governance of the Hyperledger Project - -[v0.6-preview](http://hyperledger-fabric.readthedocs.io/en/v0.6/) in October, -2016. - -If you are seeking a **stable** version of the Hyperledger Fabric on which to -develop applications or explore the technology, we **strongly recommend** that -you use the -[v0.6 Starter Kit](http://hyperledger-fabric.readthedocs.io/en/v0.6/starter/fabric-starter-kit/) -while the architectural refactoring for our upcoming v1.0 release is still in -development. - -However, if you'd like a taste of what the Hyperledger Fabric architecture has -in store, we invite you to read the preview [here](abstract_v1.md). - -If you are *adventurous*, we invite you to explore the current state of -development using the [v1.0 Starter Kit](gettingstarted.md), with the caveat -that it is not yet completely stable. We hope to have a stable v1.0-alpha -release in the very near term. - -# Hyperledger Fabric Documentation - -If you are new to the project, you might want to familiarize yourself with some -of the basics before diving into either developing applications using the -Hyperledger Fabric, or collaborating with us on our journey to continuously -extend and improve its capabilities. - -- [Use cases](biz/usecases.md) -- [Glossary](glossary.md): to understand the terminology that we use throughout -the Hyperledger Fabric project's documentation. -- [Hyperledger Fabric FAQ](https://github.com/hyperledger/fabric/tree/master/docs/FAQ) - -## Application developer guide - -- [CLI](API/CLI.md): working with the command-line interface. -- [Node.js SDK](http://fabric-sdk-node.readthedocs.io/en/latest/node-sdk-guide): -working with the Node.js SDK. -- Java SDK (coming soon). -- [Python SDK](https://wiki.hyperledger.org/projects/fabric-sdk-py.md): working with the Python SDK. -- [Writing, Building, and Running Chaincode](Setup/Chaincode-setup.md): -a step-by-step guide to developing and testing Chaincode. -- [Chaincode FAQ](FAQ/chaincode_FAQ.md): a FAQ for all of your burning questions -relating to Chaincode. - -# Operations guide - -(coming soon) - -**Note:** if you are looking for instructions to operate the fabric for a POC, -we recommend that you use the more stable [v0.6 Starter Kit](http://hyperledger-fabric.readthedocs.io/en/v0.6/starter/fabric-starter-kit/). -However, the [v1.0 Starter Kit](gettingstarted.md) is also available, though -subject to change as we stabilize the code for the upcoming v1.0-alpha release. - -## Contributing to the project - -We welcome contributions to the Hyperledger Project in many forms. There's -always plenty to do! Full details of how to contribute to this project are -documented in the [Contribution Guidelines](CONTRIBUTING.md). - -## Still Have Questions? -We try to maintain a comprehensive set of documentation (see below) 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 -[StackOverflow](http://stackoverflow.com/questions/tagged/hyperledger). If you -need help finding things, please don't hesitate to send a note to the -[mailing list](http://lists.hyperledger.org/mailman/listinfo/hyperledger-fabric), -or ask on [RocketChat]((https://chat.hyperledger.org/)) (an alternative to -Slack). - -# Incubation Notice - -This project is a Hyperledger project in _Incubation_. It was proposed to the -community and documented [here](https://goo.gl/RYQZ5N). Information on what -_Incubation_ entails can be found in the [Hyperledger Project Lifecycle -document](https://goo.gl/4edNRc). - -# License -The Hyperledger Project uses the [Apache License Version 2.0](LICENSE) software -license. +Hyperledger Fabric is an open source blockchain technology that leverages +proven technologies in providing a base [architecture](architecture.md) for +custom enterprise networks. Hyperledger Fabric is modular, allowing for +pluggable implementation of blockchain components, such as smart contracts +(chaincode), cryptographic algorithms, consensus protocols and data store +solutions. The fabric leverages powerful container technology for deployment, +and to provide a secure chaincode execution environment that protects the +network against malicious code. + +**Attention**: The Hyperledger Fabric project team is continually working to +improve the security, performance and robustness of the released software, and +frequently publishes updates. To stay current as the project progresses, please +see the **Communication** and **Still Have Questions?** topics. Your +participation in Linux Foundation projects is welcomed and encouraged! diff --git a/docs/javasdk.md b/docs/javasdk.md new file mode 100644 index 00000000000..d72032c72a4 --- /dev/null +++ b/docs/javasdk.md @@ -0,0 +1,12 @@ +# Java SDK + +[WIP] +...coming soon + +In the meantime, refer to the [Hyperledger Fabric SDK design doc](https://docs.google.com/document/d/1R5RtIBMW9fZpli37E5Li5_Q9ve3BnQ4q3gWmGZj6Sv4/edit#heading=h.z6ne0og04bp5) +for more details on the APIs and specifications. + +OR + +Refer to the [fabric-sdk-java](https://github.com/hyperledger/fabric-sdk-java) +repository in the Hyperledger community. diff --git a/docs/learn_chaincode.md b/docs/learn_chaincode.md new file mode 100644 index 00000000000..61e84dadbdd --- /dev/null +++ b/docs/learn_chaincode.md @@ -0,0 +1,10 @@ +# Learn to write chaincode + +[WIP] +...coming soon + +Teaches a developer how to write chaincode functions and implement the necessary +interfaces to create generic assets. + +In the meantime, visit the learn chaincode repo [here](https://github.com/IBM-Blockchain/learn-chaincode) +to familiarize yourself with high level concepts and go code. diff --git a/docs/ledger.md b/docs/ledger.md new file mode 100644 index 00000000000..9cf5aef8d45 --- /dev/null +++ b/docs/ledger.md @@ -0,0 +1,15 @@ +# Ledger + +[WIP] +...coming soon + +The ledger exists as a peer process utilizing levelDB. It supports the high level +transaction flow - read-write-set simulation, endorsement, MVCC check, file-based +blockchain transaction log, and state database. + +v1 architecture has been designed to support various ledger implementations such +as couchDB, where more complexity with rich queries, pruning, archiving, etc... +becomes possible. + +For more information on the current state of ledger development, explore the corresponding +JIRA issue - https://jira.hyperledger.org/browse/FAB-758 diff --git a/docs/license.md b/docs/license.md new file mode 100644 index 00000000000..aa433338eba --- /dev/null +++ b/docs/license.md @@ -0,0 +1,3 @@ +# License +The Hyperledger Project uses the [Apache License Version 2.0](LICENSE) software +license. diff --git a/docs/marbles.md b/docs/marbles.md new file mode 100644 index 00000000000..7a673456c8b --- /dev/null +++ b/docs/marbles.md @@ -0,0 +1,10 @@ +# Marbles + +[WIP] +...coming soon + +The marbles chaincode application demonstrates the ability to create assets (marbles) +with unique attributes - size, color, owner, etc... and trade these assets with fellow +participants in a blockchain network. It is not yet stable with v1 codebase. + +Learn more about the marbles chaincode and client-side application [here](https://github.com/IBM-Blockchain/marbles) diff --git a/docs/multichannel.md b/docs/multichannel.md new file mode 100644 index 00000000000..833b68b56ab --- /dev/null +++ b/docs/multichannel.md @@ -0,0 +1,12 @@ +# Multichannel + +[WIP] + +The fabric will allow for multiple channels with a designated ledger per channel (data segregation). +This capability allows for multilateral contracts where only the restricted +participants on the channel will submit, endorse, order, or commit transactions +on that channel.  As such, a single peer can maintain multiple ledgers without +compromising privacy and confidentiality. + +Refer to the [multichannel design document](https://docs.google.com/document/d/1eRNxxQ0P8yp4Wh__Vi6ddaN_vhN2RQHP-IruHNUwyhc/edit#heading=h.hml58k6zw29h) +for more detailed explanation on the mechanics and architecture. diff --git a/docs/nodesdk.md b/docs/nodesdk.md new file mode 100644 index 00000000000..eb72b328bbb --- /dev/null +++ b/docs/nodesdk.md @@ -0,0 +1,12 @@ +# Node SDK + +[WIP] +...coming soon + +In the meantime, refer to the [Hyperledger Fabric SDK design doc](https://docs.google.com/document/d/1R5RtIBMW9fZpli37E5Li5_Q9ve3BnQ4q3gWmGZj6Sv4/edit#heading=h.z6ne0og04bp5) +for more details on the APIs and specifications. + +OR + +Refer to the [fabric-sdk-node](https://github.com/hyperledger/fabric-sdk-node) +repository in the Hyperledger community. diff --git a/docs/orderingservice.md b/docs/orderingservice.md new file mode 100644 index 00000000000..e6f16fb1ee7 --- /dev/null +++ b/docs/orderingservice.md @@ -0,0 +1,13 @@ +# Ordering Service + +[WIP] +...coming soon + +This topic will outline the role and functionalities of the ordering service, and +explain its place in the broader network and in the lifecycle of a transaction. +The v1 architecture has been designed such that the ordering service is the centralized +point of trust in a decentralized network, but also such that the specific +implementation of "ordering" (solo, kafka, BFT) becomes a pluggable component. + +Refer to the design document on a [Kafka-based Ordering Service](https://docs.google.com/document/d/1vNMaM7XhOlu9tB_10dKnlrhy5d7b1u8lSY8a-kVjCO4/edit) +for more information on the default v1 implementation. diff --git a/docs/overview.md b/docs/overview.md index 381ca13db26..cff2e68521e 100644 --- a/docs/overview.md +++ b/docs/overview.md @@ -1,29 +1,31 @@ # Overview -Hyperledger Fabric is a robust and flexible blockchain network architecture +**Hyperledger Fabric** is an implementation of a robust and flexible blockchain network architecture that provides enterprise-ready security, scalability, confidentiality and -performance. Its unique implementation of distributed ledger technology ensures -data integrity and consistency, while delivering accountability, transparency -and efficiency. As a permissioned network, the fabric delivers a trusted -blockchain network, where members are assured that all transactions can be -detected and traced by authorized regulators and auditors. +performance. Its unique implementation of distributed ledger technology (DLT) +ensures data integrity and consistency, while delivering accountability, +transparency and efficiency to the network. -Hyperledger Fabric separates chaincode execution from transaction ordering, -which limits the required levels of trust and verification across nodes, -optimizing network scalability and performance. Private channels provide multi- -lateral transactions with the high degree of privacy and confidentiality -required for competing businesses and regulated industries to coexist on a -common network. The fabric incorporates a modular approach to blockchain, -enabling network designers to plug in their preferred implementations for -components such as ordering, identity management and encryption. +The key design features woven into the fabric fulfill its promise of a +comprehensive, yet customizable, enterprise blockchain solution: -In total, Hyperledger Fabric delivers a uniquely comprehensive, elastic and -extensible architecture, distinguishing it from the alternative blockchain -solutions. Planning for the future of enterprise blockchain requires building -on a fully-vetted, open architecture; Hyperledger Fabric is your starting point. +- Permissioned membership provides a trusted blockchain network, where +participants know that all transactions can be detected and traced by authorized +regulators and auditors. +- 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. +- The immutable, shared ledger encodes the entire transaction history for each +channel, and includes SQL-like query capability for efficient auditing and +dispute resolution. +- Chaincode execution is partitioned from transaction ordering, limiting +the required levels of trust and verification across node types, and optimizing +network scalability and performance. +- Modularity enables network designers to plug in their preferred +implementations for components such as transaction ordering (consensus), +identity management and encryption. -**Attention**: The Hyperledger Fabric project team is continually working to -improve the security, performance and robustness of the released software, and -frequently publishes updates. To stay current as the project progresses, please -see the **Communication** and **Still Have Questions?** topics. Your -participation in Linux Foundation projects is welcomed and encouraged! +Hyperledger Fabric delivers a uniquely elastic and extensible architecture, +distinguishing it from alternative blockchain solutions. Planning for the +future of enterprise blockchain requires building on top of a fully-vetted, +open architecture; Hyperledger Fabric is your starting point. diff --git a/docs/paper.md b/docs/paper.md new file mode 100644 index 00000000000..f381690ae3e --- /dev/null +++ b/docs/paper.md @@ -0,0 +1,9 @@ +# Commercial Paper + +[WIP] +...coming soon + +Web application demonstrating a commercial trading network and the issuance and +maturation of trades. Not yet stable with v1 codebase. + +Learn more about the application and underlying chaincode [here](https://github.com/IBM-Blockchain/cp-web) diff --git a/docs/pluggableos.md b/docs/pluggableos.md new file mode 100644 index 00000000000..ad45af734f2 --- /dev/null +++ b/docs/pluggableos.md @@ -0,0 +1,10 @@ +# Pluggable Ordering implementations + +[WIP] +...coming soon + +This topic is intended to explain how to configure an ordering service such that +it implements a alternate protocol from the default kafka-based method. + +This JIRA issue outlines the proposal for a Simplified Byzantine Fault Tolerant +consensus protocol - https://jira.hyperledger.org/browse/FAB-378 diff --git a/docs/protocol-spec_zh.md b/docs/protocol-spec_zh.md old mode 100644 new mode 100755 diff --git a/docs/pythonsdk.md b/docs/pythonsdk.md new file mode 100644 index 00000000000..dda1cfda740 --- /dev/null +++ b/docs/pythonsdk.md @@ -0,0 +1,12 @@ +# Python SDK + +[WIP] +...coming soon + +In the meantime, refer to the [Hyperledger Fabric SDK design doc](https://docs.google.com/document/d/1R5RtIBMW9fZpli37E5Li5_Q9ve3BnQ4q3gWmGZj6Sv4/edit#heading=h.z6ne0og04bp5) +for more details on the APIs and specifications. + +OR + +Refer to the [fabric-sdk-py](https://github.com/hyperledger/fabric-sdk-py) +repository in the Hyperledger community. diff --git a/docs/quality.md b/docs/quality.md new file mode 100644 index 00000000000..c5eab2498d4 --- /dev/null +++ b/docs/quality.md @@ -0,0 +1,4 @@ +# Quality + +[WIP] +...coming soon diff --git a/docs/questions.md b/docs/questions.md new file mode 100644 index 00000000000..ef84cda1cfe --- /dev/null +++ b/docs/questions.md @@ -0,0 +1,10 @@ +# 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 +[StackOverflow](http://stackoverflow.com/questions/tagged/hyperledger). If you +need help finding things, please don't hesitate to send a note to the +[mailing list](http://lists.hyperledger.org/mailman/listinfo/hyperledger-fabric), +or ask on [RocketChat]((https://chat.hyperledger.org/)) (an alternative to +Slack). diff --git a/docs/readwrite.md b/docs/readwrite.md new file mode 100644 index 00000000000..c634bbd05e5 --- /dev/null +++ b/docs/readwrite.md @@ -0,0 +1,127 @@ +### Read-Write set semantics + +This documents discusses the details of the current implementation about the +semantics of read-write sets. + +##### Transaction simulation and read-write set +During simulation of a transaction at an `endorser`, a read-write set is prepared +for the transaction. The `read set` contains a list of unique keys and their +committed versions that the transaction reads during simulation. The `write set` +contains a list of unique keys (though there can be overlap with the keys present +in the read set) and their new values that the transaction writes. A delete +marker is set (in the place of new value) for the key if the update performed +by the transaction is to delete the key. + +Further, if the transaction writes a value multiple times for a key, only the +last written value is retained. Also, if a transaction reads a value for a key, +the value in the committed state is returned even if the transaction has updated +the value for the key before issuing the read. In another words, Read-your-writes +semantics are not supported. + +As noted earlier, the versions of the keys are recorded only in the read set; +the write set just contains the list of unique keys and their latest values set +by the transaction. + +There could be various schemes for implementing versions. The minimal requirement +for a versioning scheme is to produce non-repeating identifiers for a given key. +For instance, using monotonically increasing numbers for versions can be one such scheme. +In the current implementation, we use a blockchain height based versioning scheme +in which the height of the committing transaction is used as the latest version for +all the keys modified by the transaction. In this scheme, the height of a transaction +is represented by a tuple (txNumber is the height of the +transaction within the block). This scheme has many advantages over the incremental +number scheme - primarily, it enables other components such as statedb, transaction +simulation and validation for making efficient design choices. + +Following is an illustration of an example read-write set prepared by simulation +of a hypothetical transaction. For the sake of simplicity, in the illustrations, +we use the incremental numbers for representing the versions. + +``` + + + + + + + + + + +``` + +Additionally, if the transaction performs a range query during simulation, the +range query as well as its results will be added to the read-write set as `query-info`. + +##### Transaction validation and updating world state using read-write set +A `committer` uses the read set portion of the read-write set for checking the +validity of a transaction and the write set portion of the read-write set for +updating the versions and the values of the affected keys. + +In the validation phase, a transaction is considered `valid` if the version of +each key present in the read set of the transaction matches the version for the +same key in the world state - assuming all the preceding `valid` transactions +(including the preceding transactions in the same block) are committed +(*committed-state*). An additional validation is performed if the read-write set +also contains one or more query-info. + +This additional validation should ensure that no key has been +inserted/deleted/updated in the super range (i.e., union of the ranges) of the +results captured in the query-info(s). In other words, if we re-execute any of +the range queries (that the transaction performed during simulation) during +validation on the committed-state, it should yield the same results that were +observed by the transaction at the time of simulation. This check ensures that +if a transaction observes phantom items during commit, the transaction should be +marked as invalid. Note that the this phantom protection is limited to range +queries (i.e., `GetStateByRange` function in the chaincode) and not yet +implemented for other queries (i.e., `GetQueryResult` function in the chaincode). +Other queries are at risk of phantoms, and should therefore only be used in +read-only transactions that are not submitted to ordering, unless the application +can guarantee the stability of the result set between simulation and validation/commit time. + +If a transaction passes the validity check, the committer uses the write set for +updating the world state. In the update phase, for each key present in the write +set, the value in the world state for the same key is set to the value as specified +in the write set. Further, the version of the key in the world state is changed +to reflect the latest version. + +##### Example simulation and validation +This section helps with understanding the semantics through an example scenario. +For the purpose of this example, the presence of a key, `k`, in the world state is +represented by a tuple `(k,ver,val)` where `ver` is the latest version of the +key `k` having `val` as its value. + +Now, consider a set of five transactions `T1, T2, T3, T4, and T5`, all simulated +on the same snapshot of the world state. The following snippet shows the snapshot of +the world state against which the transactions are simulated and the sequence of +read and write activities performed by each of these transactions. + +``` +World state: (k1,1,v1), (k2,1,v2), (k3,1,v3), (k4,1,v4), (k5,1,v5) +T1 -> Write(k1, v1'), Write(k2, v2') +T2 -> Read(k1), Write(k3, v3') +T3 -> Write(k2, v2'') +T4 -> Write(k2, v2'''), read(k2) +T5 -> Write(k6, v6'), read(k5) +``` +Now, assume that these transactions are ordered in the sequence of T1,..,T5 +(could be contained in a single block or different blocks) + +1. `T1` passes validation because it does not perform any read. Further, the +tuple of keys `k1` and `k2` in the world state are updated to `(k1,2,v1'), (k2,2,v2')` + +2. `T2` fails validation because it reads a key, `k1`, which was modified by a preceding transaction - `T1` + +3. `T3` passes the validation because it does not perform a read. Further the +tuple of the key, `k2`, in the world state is updated to `(k2,3,v2'')` + +4. `T4` fails the validation because it reads a key, `k2`, which was modified by a preceding transaction `T1` + +5. `T5` passes validation because it reads a key, `k5,` which was not modified +by any of the preceding transactions + +#### Transactions with multiple read-write sets +Not yet supported (https://jira.hyperledger.org/browse/FAB-445) diff --git a/docs/recipes.md b/docs/recipes.md new file mode 100644 index 00000000000..3be28ab6fc8 --- /dev/null +++ b/docs/recipes.md @@ -0,0 +1,7 @@ +# Recipe Book + +[WIP] +...coming soon + +Intended to contain best practices and configurations for MSP, networks, ordering +service, channels, ACL, stress, policies, chaincode development, functions, etc... diff --git a/docs/sampleapp.md b/docs/sampleapp.md new file mode 100644 index 00000000000..57a4ae49184 --- /dev/null +++ b/docs/sampleapp.md @@ -0,0 +1,6 @@ +# Sample Application + +[WIP] +...coming soon + +In the meantime, refer to the [Asset transfer through SDK](asset_sdk.md) topic. diff --git a/docs/security_model.md b/docs/security_model.md new file mode 100644 index 00000000000..bbe21ce9688 --- /dev/null +++ b/docs/security_model.md @@ -0,0 +1,13 @@ +# Security Model + +[WIP] + +Hyperledger Fabric allows for different organizations and participants in a common network +to utilize their own certificate authority, and as a byproduct, implement varying +cryptographic algorithms for signing/verifying/identity attestation. This is done through an MSP +process running on both the ordering service and channel levels. + +Membership service provider (MSP): A set of cryptographic mechanisms and protocols +for issuing and validating certificates and identities throughout the blockchain network. +Identities issued in the scope of a membership service provider can be evaluated +within that membership service provider’s rules validation policies. diff --git a/docs/smartcontract.md b/docs/smartcontract.md new file mode 100644 index 00000000000..0b20938007a --- /dev/null +++ b/docs/smartcontract.md @@ -0,0 +1,12 @@ +# Chaincode + +[WIP] + +The widely-used term, smart contract, is referred to as "chaincode" in Hyperledger Fabric. + +Self-executing logic that encodes the rules for specific types of +network transactions. Chaincode (currently written in Go or Java) is installed and +instantiated onto a channel's peers by an appropriately authorized member. End users then +invoke chaincode through a client-side application that interfaces with a +network peer. Chaincode runs network transactions, which if validated, are +appended to the shared ledger and modify world state. diff --git a/docs/starter/fabric-starter-kit.md b/docs/starter/fabric-starter-kit.md old mode 100644 new mode 100755 diff --git a/docs/testing.md b/docs/testing.md new file mode 100644 index 00000000000..875d4d57b61 --- /dev/null +++ b/docs/testing.md @@ -0,0 +1,7 @@ +# Testing + +[WIP] +...coming soon + +This topic is intended to contain recommended test scenarios, as well as current +performance numbers against a variety of configurations. diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md new file mode 100644 index 00000000000..1814cc0e63b --- /dev/null +++ b/docs/troubleshooting.md @@ -0,0 +1,7 @@ +# Troubleshooting + +[WIP] +...coming soon + +This topic is intended to solve high level bugs and then direct users to more +granular FAQ topics based on their errors. diff --git a/docs/txflow.md b/docs/txflow.md new file mode 100644 index 00000000000..0802a1a5482 --- /dev/null +++ b/docs/txflow.md @@ -0,0 +1,12 @@ +# Transaction Flow + +[WIP] +...coming soon + +This topic will contain a diagram (currently in progress) outlining at a high level the +basic flow of a transaction(s) from Application/SDK -> Endorsing Peers -> Back to SDK +with proposal responses -> "Broadcast" to ordering service -> "Delivered" as a block +to a channel's peers for validation and commitment (i.e. written to the shared ledger). + +In the meantime, view the [high level data flows](https://jira.hyperledger.org/browse/FAB-37) +and familiarize yourself with the concepts, components, and roles of system chaincodes. diff --git a/docs/videos.md b/docs/videos.md new file mode 100644 index 00000000000..e97baeb7d04 --- /dev/null +++ b/docs/videos.md @@ -0,0 +1,5 @@ +# Videos + +Refer to the Hyperledger Fabric libary on [youtube](https://www.youtube.com/channel/UCCFdgCWH_1vCndMPVqQlwZw). +The collection contains developers demonstrating various v1 features and components such as: +ledger, channels, gossip, SDK, chaincode, MSP, and more... diff --git a/docs/whyfabric.md b/docs/whyfabric.md index 22eb0b4488c..ee9be1c9be1 100644 --- a/docs/whyfabric.md +++ b/docs/whyfabric.md @@ -2,10 +2,10 @@ The Hyperledger Fabric project is delivering a blockchain platform designed to allow the exchange of an asset or the state of an asset to be -consented upon, maintained, and viewed by all parties in a permissioned group. -A key characteristic of Hyperledger Fabric is that the asset is defined +consented upon, maintained, and viewed by all parties in a permissioned group. A +key characteristic of Hyperledger Fabric is that the asset is defined digitally, with all participants simply agreeing on its -representation/characterization. As such, Hypewrledger Fabric can support a +representation/characterization. As such, Hyperledger Fabric can support a broad range of asset types; ranging from the tangible (real estate and hardware) to the intangible (contracts and intellectual property). diff --git a/mkdocs.yml b/mkdocs.yml index 09f493a0140..cf6ff912740 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -8,41 +8,96 @@ theme_dir: 'docs/custom_theme' pages: - Home: index.md -- Why Hyperledger Fabric?: whyfabric.md -- Fabric Overview: overview.md -- Architecture Overview: architecture.md -- Architecture Deep Dive: arch-deep-dive.md -#- Fabric capabilities: capabilities.md -- Getting started: gettingstarted.md -#- Chaincode and sample program: chaincode.md -- Glossary: glossary.md -- Releases: releases.md - -- Fabric Developer: - - v1.0 Preview: abstract_v1.md - - Contributing: CONTRIBUTING.md - - Maintainers: MAINTAINERS.md - - Getting an Account: Gerrit/lf-account.md - - Navigating Jira: jira_navigation.md - - Fabric Developer Setup: dev-setup/devenv.md - - Building Fabric: dev-setup/build.md - - Gerrit: Gerrit/gerrit.md - - Changes: Gerrit/changes.md - - Reviewing: Gerrit/reviewing.md - - Best Practices: Gerrit/best-practices.md - - Canonical Use Cases: biz/usecases.md - - Style Guides: - - Golang: Style-guides/go-style.md +- Key Concepts: + - Overview: overview.md + - Why Fabric: whyfabric.md + - Use Cases: biz/usecases.md + - Glossary: glossary.md + - Transaction Data Model: data_model.md + - Security Model: security_model.md + - Multi Channel: multichannel.md + - Chaincode: smartcontract.md + - Consensus: consensus.md -- Application Developer: - - CLI: API/CLI.md - - Writing, Building, and Running Chaincode: Setup/Chaincode-setup.md - - Chaincode FAQ: FAQ/chaincode_FAQ.md +- Getting Started: + - Network Components: included.md + - Setting up: asset_setup.md + - Asset Transfer through SDK: asset_sdk.md + - Using the CLI: asset_cli.md + - Troubleshooting: asset_trouble.md -- Setup: - - Fabric CA: Setup/ca-setup.md +- Application Interfaces: + - Node.js SDK: nodesdk.md + - Java SDK: javasdk.md + - Python SDK: pythonsdk.md + +- Running Demos: + - Marbles: marbles.md + - Art Auction: auction.md + - CP Paper: paper.md + - Car Lease: carlease.md + +- Tutorials: + - Understanding chaincode basics: chaincode.md + - Learn chaincode: learn_chaincode.md + - Understanding docker compose: dockercompose.md + - Sample application: sampleapp.md + - Developer videos: videos.md + - Administration and operations: adminops.md + - Debugging: debug.md - Logging Control: Setup/logging-control.md +- Configuration Considerations: + - Best Practices: recipes.md + - Starting a network: bootstrap.md + +- Architecture: + - Overview: architecture.md + - Deep Dive: arch-deep-dive.md + - Peer Nodes: + - Endorsers: endorser.md + - Committers: committer.md + - Policies & System Chaincode: endorsement-policies.md + - Ordering Service: orderingservice.md + - Pluggable Implementations: pluggableos.md + - Ledger: ledger.md + - Gossip: gossip.md + - Security & Cryptography: Setup/ca-setup.md + - Components: components.md + - Read/Write Set Semantics: readwrite.md + - Transaction Flow: txflow.md + +- Getting Help: + - Troubleshooting: troubleshooting.md + - FAQs: + - Architecture: FAQ/architecture_FAQ.md + - Chaincode: FAQ/chaincode_FAQ.md + - Confidentiality: FAQ/confidentiality_FAQ.md + - Consensus: FAQ/consensus_FAQ.md + - Identity: FAQ/identity_management_FAQ.md + - Usage: FAQ/usage_FAQ.md + +- Appendix: + - Release notes: releases.md + - Contributing: CONTRIBUTING.md + - Development Process and Code: + - Getting an account: Gerrit/lf-account.md + - Maintainers: MAINTAINERS.md + - Navigating JIRA: jira_navigation.md + - Fabric developer setup: dev-setup/devenv.md + - Building fabric: dev-setup/build.md + - Gerrit: Gerrit/gerrit.md + - Committing code: Gerrit/changes.md + - Reviewing code: Gerrit/reviewing.md + - Best practices: Gerrit/best-practices.md + - Testing process: testing.md + - Style Guides: + - Golang: Style-guides/go-style.md + - Still Have Questions?: questions.md + - Criteria on quality: quality.md + - Incubation notice: incubation.md + - License: license.md + markdown_extensions: - toc: permalink: true @@ -56,4 +111,4 @@ markdown_extensions: enable_dollar_delimiter: True #for use of inline $..$ - footnotes -copyright: Copyright © 2017 IBM Corp.

Contributed to the Hyperledger Project under the Apache Software License 2.0 +copyright:

Contributed to the Hyperledger Project under the Apache Software License 2.0