FAQ and FireFly Tutorial Updates (#857) (#889)

Signed-off-by: Alex Shorsher <[email protected]>

Co-authored-by: trevorsc19 <[email protected]>

Author: shorsher

docs/faqs/faqs.md

@@ -9,6 +9,18 @@ has_children: true
 
 Find answers to the most commonly asked FireFly questions.
 
-This content is coming soon and will be guided by community interactions via Discord, meetups, webinars and other technical forums.
+## How does FireFly enable multi-chain applications?
+It's best to think about FireFly as a rich orchestration layer that sits one layer above the blockchain.  FireFly helps to abstract away much of the complex blockchain functionality (such as data exchange, private messaging, common token functionality, etc) in a loosely coupled microservice architecture with highly pluggable components. This enables application developers to focus on building innovative Web3 applications.
 
-If you have immediate questions please don't hesitate to reach out to us on the [Hyperledger Discord](https://discord.gg/hyperledger) in the `#firefly` channel.
+There aren't any out of the box bridges to connect two separate chains together, but with a collection of FireFly instances across a consortium, FireFly could help listen for events on Blockchain A and take an action on Blockchain B when certain conditions are met.
+
+## 📜 How do I deploy smart contracts?
+In order to interact with a smart contract on a public or private Ethereum chain you need to first deploy it to the chain. Deployment means that you've sent a transaction with the compiled source code to the chain without a specified recipient and received a contract address that you and others on the network can use to interact with your contract.
+
+Refer to the [Smart Contract Tutorial](../tutorials/custom_contracts/) for instructions to deploy a smart contract to your private networking using FireFly.
+
+## 🦊 Can I connect FireFly to MetaMask?
+Yes! Before you set up MetaMask you'll likely want to create some tokens that you can use to send between wallets on your FF network. Go to the tokens tab in your FireFly node's UI, create a token pool, and then mint some tokens. Once you've done this, follow the steps listed [here](https://hyperledger.github.io/firefly/tutorials/tokens/erc721.html#use-metamask) to set up MetaMask on your network.
+
+## 🚀 Connect with us on Discord
+If your question isn't answered here or if you have immediate questions please don't hesitate to reach out to us on [Discord](https://discord.gg/hyperledger_) in the `firefly` channel:

docs/images/define_a_datatype.png

@@ -9,7 +9,7 @@ has_children: false
 
 This is the FireFly OpenAPI Specification document generated by FireFly
 
-Note: The 'Try it out' buttons will not work on this page, because it's not running against a live version of FireFly. To actually try it out, we recommend using the [FireFly CLI](https://github.com/hyperledger/firefly-cli) to start an instance on your local machine, then have a look at the API spec there.
+**Note**: The 'Try it out' buttons will not work on this page because it's not running against a live version of FireFly. To actually try it out, we recommend using the [FireFly CLI](https://github.com/hyperledger/firefly-cli) to start an instance on your local machine (which will start the FireFly core on port 5000 by default) and then open the Swagger UI associated with your local node by opening a new tab and visiting [http://localhost:5000/api](http://localhost:5000/api)
 
 <link rel="stylesheet" type="text/css" href="https://unpkg.com/swagger-ui-dist@3/swagger-ui.css">
 

docs/images/firefly_first_successful_transaction.png

@@ -34,11 +34,11 @@ nav_order: 4
 ## Additional info
 
 - Key Concepts: [Broadcast / shared data](../overview/broadcast.md)
-- Swagger: <a href="../swagger/swagger.html#/Default%20Namespace/postNewMessageBroadcast" data-proofer-ignore>POST /api/v1/namespaces/{ns}/messages/broadcast]</a>
+- Swagger Reference: <a href="../swagger/swagger.html#/Default%20Namespace/postNewMessageBroadcast" data-proofer-ignore>POST /api/v1/namespaces/{ns}/messages/broadcast</a>
 
 ## Example 1: Inline string data
 
-`POST` `/api/v1/namespaces/default/broadcast/message`
+`POST` `/api/v1/namespaces/default/messages/broadcast`
 
 ```json
 {
@@ -52,12 +52,6 @@ nav_order: 4
 
 ## Example message response
 
-Status: `202 Accepted` - the message is on it's way, but has not yet been confirmed.
-
-> _Issue [#112](https://github.com/hyperledger/firefly/issues/112) proposes adding
-> an option to wait for the message to be confirmed by the blockchain before returning,
-> with `200 OK`._
-
 ```json
 {
   "header": {
@@ -96,7 +90,7 @@ It is very good practice to set a `tag` and `topic` in each of your messages:
   information you are publishing. It is used as an ordering context, so all
   broadcasts on a given topic are assured to be processed in order.
 
-`POST` `/api/v1/namespaces/default/broadcast/message`
+`POST` `/api/v1/namespaces/default/messages/broadcast`
 
 ```json
 {
@@ -114,21 +108,45 @@ It is very good practice to set a `tag` and `topic` in each of your messages:
   ]
 }
 ```
+## Notes on why setting a topic is important
+
+The FireFly aggregator uses the `topic` (obfuscated on chain) to determine if a
+message is the next message in an in-flight sequence for any groups the node is
+involved in. If it is, then that message must receive all off-chain private data
+and be confirmed before any subsequent messages can be confirmed on the same sequence.
+
+So if you use the same topic in every message, then a single failed send on one
+topic blocks delivery of all messages between those parties, until the missing
+data arrives.
+
+Instead it is best practice to set the topic on your messages to a value
+that identifies an ordered stream of business processing. Some examples:
+
+- A long-running business process instance identifier assigned at initiation
+- A real-world business transaction identifier used off-chain
+- The agreed identifier of an asset you are attaching a stream of evidence to
+- An NFT identifier that is assigned to an asset (digital twin scenarios)
+- An agreed primary key for a data resource being reconciled between multiple parties
+
+The `topic` field is an array, because there are cases (such as merging two identifiers)
+where you need a message to be deterministically ordered across multiple sequences.
+However, this is an advanced use case and you are likely to set a single topic
+on the vast majority of your messages.
 
 ## Example 3: Upload a blob with metadata and broadcast
 
 Here we make two API calls.
 
-1. Create the `data` object explicitly, using a multi-party form upload
+1) Create the `data` object explicitly, using a multi-party form upload
 
-- You can also just post JSON to this endpoint
+  - You can also just post JSON to this endpoint
 
-2. Broadcast a message referring to that data
+2) Broadcast a message referring to that data
 
-- The Blob attachment gets published to shared storage
-  - This happens the first time a broadcast happens on a data attachment
-- A pin goes to the blockchain
-- The metadata goes into a batch with the message
+  - The Blob attachment gets published to shared storage
+    - This happens the first time a broadcast happens on a data attachment
+  - A pin goes to the blockchain
+  - The metadata goes into a batch with the message
 
 ### Multipart form post of a file
 
@@ -191,3 +209,22 @@ Just include a reference to the `id` returned from the upload.
   ]
 }
 ```
+
+## Broadcasting Messages using the Sandbox
+All of the functionality discussed above can be done through the [FireFly Sandbox](../gettingstarted/sandbox.md).
+
+To get started, open up the Web UI and Sanbox UI for at least one of your members. The URLs for these were printed in your terminal when you started your FireFly stack.
+
+In the sandbox, enter your message into the message field as seen in the screenshot below.
+
+![Initial Broadcast Message](../images/message_broadcast_initial.png)
+
+Notice how the `data` field in the center panel updates in real time.
+
+Click the blue `Run` button. This should return a `202` response immediately in the Server Response section and will populate the right hand panel with transaction information after a few seconds. 
+
+![Broadcast Result](../images/message_broadcast_sample_result.png)
+
+Go back to the FireFly UI (the URL for this would have been shown in the terminal when you started the stack) and you'll see your successful blockchain transaction
+
+![Successful Broadcast Transaction](../images/firefly_first_successful_transaction.png)