From 34d92effd7f35cc07752308e42af6eb6efc52388 Mon Sep 17 00:00:00 2001 From: David Date: Thu, 28 Sep 2017 16:54:34 -0400 Subject: [PATCH] added faq --- README.md | 22 +++++++++++--- docs/faq.md | 85 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 103 insertions(+), 4 deletions(-) create mode 100644 docs/faq.md diff --git a/README.md b/README.md index 3f6c47e58..f12a0e21e 100644 --- a/README.md +++ b/README.md @@ -550,10 +550,24 @@ The admin moved the marble, JS detected the drag/drop, client sends a websocket That’s it! Hope you had fun transferring marbles. -## Marbles Tips -There are few comments about marbles that don't fit neatly into the instructions above. -Here is an assortment of marbles tips and instructions. -- coming soon +# Marbles FAQs +Do you have questions about _why_ something in marbles is the way it is? Or _how_ to do something? Check out the [FAQ](./docs/faq.md) . + +# Feedback +I'm very interested in your feedback. +This is a demo built for people like you, and it will continue to be shaped for people like you. +On a scale of no-anesthetic-root-canal to basket of puppies, how was it? +If you have any ideas on how to improve the demo/tutorial, please reach out! +Specifically: + +- Did the format of the readme work well for you? +- At which points did you get lost? +- Is something broken!? +- Did your knowledge grow by the end of the tutorial? +- Was something particularly painful? +- Did it make you have an existential crisis and you are suddenly unsure of what it means to be, you? + +Use the [GitHub Issues](https://github.com/IBM-Blockchain/marbles/issues) section to communicate any improvements/bugs and pain points! # License [Apache 2.0](LICENSE) diff --git a/docs/faq.md b/docs/faq.md new file mode 100644 index 000000000..a187fed0d --- /dev/null +++ b/docs/faq.md @@ -0,0 +1,85 @@ +# Marbles FAQ + +1. [Does deleting a marble re-write history? How is this not breaking the blockchain ledger?](./#deleteHistory) + +1. [What is with the required input arguments for the marbles chaincode?](./#inputArgs) + +1. [How can I create a HA(high-availability) setup?](./#ha) + +1. [I want to run a local Hyperledger Fabric network... how?](./#localFabric) + +1. [What is this "fcw" aka "fc wrangler" thing?](./#fcw) + +1. [I'm stuck, can you help me?](./#stuck) + +*** + + + +### Q. Does deleting a marble re-write history? How is this not breaking the blockchain ledger? +It does not re-write history. +"History" would refer to the ledger, which can not be re-written under normal circumstances. +The "delete" transaction is a regular transaction that gets recorded into a block in the ledger. +Therefore the marble's creation and activity remains in the ledger unchanged, forever, even after a "delete". +However the _state_ of the asset did change. +The ledger and the world state are different things. +The ledger contains the historic actions to the chaincode and channel (transactions). +While the world state is all the asset data at a specific _moment_ of time. +Think of it as the combined result of playing back all transactions. +When we created a marble, we appended the create transaction to the ledger, and added the marble to the world state. +Like-wise when we delete, the delete transaction is appended to the ledger, and the world state is altered to remove the marble. + + + + +### Q. What is with the required input arguments for the marbles chaincode? +The marbles chaincode requires a single integer as an input. +This is purely for demonstration reasons to show how its possible to pass inputs to a chaincode during its instantiate. +The actual number you provide to marbles is meaningless, go nuts. + + + + +### Q. How can I create a HA(high-availability) setup +The latest and greatest marbles already does this! Checkout the `fc wrangler` files: [high_availability.js](../utils/fc_wrangler/high_availability.js) and [index.js](../utils/fc_wrangler/index.js). The code snippet below shows that when an invoke fails, we call `ha.switch_peer()` to send the same call to the next peer. Remember that the SDK is configured to send requests to specific peers, so all we have to do is change this peer. + +__./utils/fc_wrangler/index.js__ +```js + fcw.invoke_chaincode = function (obj, options, cb_done) { + invoke_cc.invoke_chaincode(obj, options, function (err, resp) { + if (err != null) { //looks like an error with the request + if (ha.switch_peer(obj, options) == null) { //try another peer + logger.info('Retrying invoke on different peer'); + fcw.invoke_chaincode(obj, options, cb_done); + } else { + if (cb_done) cb_done(err, resp); //out of peers, give up + } + } else { //all good, pass resp back to callback + ha.success_peer_position = ha.using_peer_position; //remember the last good one + if (cb_done) cb_done(err, resp); + } + }); + }; +``` + + + + +### Q. I want to run a local Hyperledger Fabric network... how? +Great, I recommend that everyone starts with a local network. [Lets get going](../docs/use_local_hyperledger.md) . + + + + +### Q. What is this "fcw" aka "fc wrangler" thing? +It's called the Fabric Client Wrangler. +It is simply a wrapper around the [fabric-client](https://www.npmjs.com/package/fabric-client) SDK module. +ie it gives me a slightly friendlier interface to the SDK. +It is generic and reuseable for your own adaptations. +It is **not** a required component of a node.js -> Fabric application, but I feel it helps. + + + + +### Q. I'm stuck, can you help me? +Yes. Open an issue on our [GitHub Issues](https://github.com/IBM-Blockchain/marbles/issues). Please include as much info as you can, such as the logs you are seeing, what you were expecting to happen, etc.