diff --git a/docs/_i18n/en.yml b/docs/_i18n/en.yml index e499e08a53..eb9fc5353e 100644 --- a/docs/_i18n/en.yml +++ b/docs/_i18n/en.yml @@ -10,8 +10,8 @@ pages: architecture: Architecture api_post_syntax: API Post Syntax api_query_syntax: API Query Syntax - blockchain_protocols: Blockchain protocols - broadcast_shared_data: Broadcast / shared data + blockchain_protocols: Blockchain Protocols + broadcast_shared_data: Broadcast / Shared Data broadcast_data: Broadcast data code_hierarchy: FireFly Code Hierarchy code_overview: FireFly Code Overview @@ -21,7 +21,19 @@ pages: custom_smart_contracts: Work with custom smart contracts faqs: FAQs getting_started: Getting Started - private_data_exchange: Private data exchange + data_exchange: Data Exchange reference: Reference tutorials: Tutorials - understanding_firefly: Understanding FireFly \ No newline at end of file + understanding_firefly: Understanding FireFly + chains: Connecting to other chains + remote_fabric_network: Remote Fabric Network + polygon_testnet: Polygon Testnet + arbitrum: Arbitrum Testnet + avalanche: Avalanche Testnet + binance_smart_chain: Binance Smartchain Testnet + near: NEAR Testnet + optimism: Optimism Testnet + multiparty_mode: Multiparty Mode + deterministic: Deterministic Compute + multiparty_flow: Multiparty Process Flow + firefly_core: Firefly Core diff --git a/docs/_i18n/en/index.md b/docs/_i18n/en/index.md index 908c9ce9fa..b8680691ce 100644 --- a/docs/_i18n/en/index.md +++ b/docs/_i18n/en/index.md @@ -2,12 +2,17 @@ ![Hyperledger FireFly](./images/hyperledger_firefly_social.png) -Hyperledger FireFly is the first open source Supernode: a complete stack for enterprises to build and scale secure Web3 applications. +Hyperledger FireFly is an open source Supernode, a complete stack for enterprises to build and scale secure Web3 applications. It is a project contributed by Kaleido and currently in the incubation phase for Hyperledger projects. -The FireFly API for digital assets, data flows, and blockchain transactions makes it radically faster to build production-ready apps on popular chains and protocols. +The easiest way to understand a FireFly Supernode is to think of it like a toolbox. Connect your existing apps and/or back office systems to the toolbox and within it there are two different sets of tools. One set of tools helps you connect to the Web3 world and the other set allows you to interact with multi-party systems. In FireFly language, these are referred to as [Web3 Gateway Mode](./overview/firefly_modes/gateway_mode.html) and [Multiparty Mode](./overview/firefly_modes/multiparty_mode.html). + +A FireFly Supernode simplifies the development process. Instead of building and maintaining the “plumbing’ or “middleware” yourself, a Supernode comes with pre-built solutions. These solutions include APIs, connector plugins, an orchestration layer, and user tools. Head to the Understanding FireFly section for more details. - [Understanding FireFly](./overview/) +- [Getting Started](./gettingstarted/) +- [Tutorials](./tutorials/) - [Reference](./reference/) - [Architecture](./architecture/) - [Contributors](./contributors/) - [API Spec](./swagger/swagger.html) +- [FAQs](./faqs/) \ No newline at end of file diff --git a/docs/faqs/faqs.md b/docs/faqs/index.md similarity index 100% rename from docs/faqs/faqs.md rename to docs/faqs/index.md diff --git a/docs/gettingstarted/firefly_cli.md b/docs/gettingstarted/firefly_cli.md index b73adb869e..521a231ea4 100644 --- a/docs/gettingstarted/firefly_cli.md +++ b/docs/gettingstarted/firefly_cli.md @@ -6,9 +6,11 @@ nav_order: 1 --- # ① Install the FireFly CLI + {: .no_toc } ## Table of contents + {: .no_toc .text-delta } 1. TOC @@ -16,12 +18,6 @@ nav_order: 1 --- -![FireFly CLI](../images/firefly_cli.png) - -## FireFly CLI - -The FireFly CLI can be used to create local FireFly stacks for offline development of blockchain apps. This allows developers to rapidly iterate on their idea without needing to set up a bunch of infrastructure before they can write the first line of code. - ## Prerequisites In order to run the FireFly CLI, you will need a few things installed on your dev machine: @@ -31,9 +27,11 @@ In order to run the FireFly CLI, you will need a few things installed on your de - openssl ### Linux Users + > **NOTE**: For Linux users, it is recommended that you add your user to the `docker` group so that you do not have to run `ff` or `docker` as `root` or with `sudo`. For more information about Docker permissions on Linux, please see [Docker's documentation on the topic](https://docs.docker.com/engine/install/linux-postinstall/). ### Windows Users + > **NOTE**: For Windows users, we recommend that you use [Windows Subsystem for Linux 2 (WSL2)](https://docs.microsoft.com/en-us/windows/wsl/). Binaries provided for Linux will work in this environment. ## Install the CLI @@ -41,6 +39,7 @@ In order to run the FireFly CLI, you will need a few things installed on your de There are several ways to install the FireFly CLI. The easiest way to get up and running with the FireFly CLI is to download a pre-compiled binary of the latest release. ### Download the package for your OS + Go to the [latest release page](https://github.com/hyperledger/firefly-cli/releases/latest) and download the package for your OS and CPU architecture. ### Extract the binary and move it to `/usr/bin/local` @@ -51,11 +50,11 @@ Assuming you downloaded the package from GitHub into your `Downloads` directory, sudo tar -zxf ~/Downloads/firefly-cli_*.tar.gz -C /usr/local/bin ff && rm ~/Downloads/firefly-cli_*.tar.gz ``` -If you downloaded the package from GitHub into a different directory, you will need to change the `tar` command above to wherever the `firefly-cli_*.tar.gz ` file is located. +If you downloaded the package from GitHub into a different directory, you will need to change the `tar` command above to wherever the `firefly-cli_*.tar.gz` file is located. ### macOSUsers - > **NOTE**: On recent versions of macOS, default security settings will prevent the FireFly CLI binary from running, because it was downloaded from the internet. You will need to [allow the FireFly CLI in System Preferences](https://github.com/hyperledger/firefly-cli/blob/main/docs/mac_help.md), before it will run. + > **NOTE**: On recent versions of macOS, default security settings will prevent the FireFly CLI binary from running, because it was downloaded from the internet. You will need to [allow the FireFly CLI in System Preferences](https://github.com/hyperledger/firefly-cli/blob/main/docs/mac_help.md), before it will run. ### Alternative installation method: Install via Go @@ -68,6 +67,7 @@ go install github.com/hyperledger/firefly-cli/ff@latest ## Verify the installation After using either installation method above, you can verify that the CLI is successfully installed by running `ff version`. This should print the current version like this: + ``` { "Version": "v0.0.47", @@ -76,6 +76,7 @@ After using either installation method above, you can verify that the CLI is suc ``` ## Next steps: Start your environment + Now that you've got the FireFly CLI set up on your machine, the next step is to create and start a FireFly stack. -[② Start your environment →](setup_env.md){: .btn .btn-purple .float-right .mb-5} \ No newline at end of file +[② Start your environment →](setup_env.md){: .btn .btn-purple .float-right .mb-5} diff --git a/docs/gettingstarted/sandbox.md b/docs/gettingstarted/sandbox.md index 8b50e2a35c..fe7f83a514 100644 --- a/docs/gettingstarted/sandbox.md +++ b/docs/gettingstarted/sandbox.md @@ -26,9 +26,9 @@ Now that you have a full network of three Supernodes running on your machine, le ## Video walkthrough -This video is a walkthrough of the FireFly Sandbox and FireFly Explorer from the FireFly 1.0 launch webinar. At this point you should be able to follow along and try all these same things on your own machine. +This video is a walkthrough of the FireFly Sandbox and FireFly Explorer from the FireFly 1.0 launch webinar. At this point you should be able to follow along and try all these same things on your own machine. -## What is the FireFly Sandbox? + ## Open the FireFly Sandbox for the first member diff --git a/docs/images/firefly_core.png b/docs/images/firefly_core.png new file mode 100644 index 0000000000..e39c114f6c Binary files /dev/null and b/docs/images/firefly_core.png differ diff --git a/docs/images/firefly_functionality_overview.png b/docs/images/firefly_functionality_overview.png index c54a4e3aa3..b29c883197 100644 Binary files a/docs/images/firefly_functionality_overview.png and b/docs/images/firefly_functionality_overview.png differ diff --git a/docs/images/gateway_mode.png b/docs/images/gateway_mode.png new file mode 100644 index 0000000000..56359c3923 Binary files /dev/null and b/docs/images/gateway_mode.png differ diff --git a/docs/images/gateway_multiparty_mode.png b/docs/images/gateway_multiparty_mode.png new file mode 100644 index 0000000000..b4eb2bbddf Binary files /dev/null and b/docs/images/gateway_multiparty_mode.png differ diff --git a/docs/images/multiparty_mode.png b/docs/images/multiparty_mode.png new file mode 100644 index 0000000000..003fede0a9 Binary files /dev/null and b/docs/images/multiparty_mode.png differ diff --git a/docs/images/multiparty_system.png b/docs/images/multiparty_system.png deleted file mode 100644 index 5e5d061d6e..0000000000 Binary files a/docs/images/multiparty_system.png and /dev/null differ diff --git a/docs/images/multiparty_system1.png b/docs/images/multiparty_system1.png new file mode 100644 index 0000000000..abdcbf7fd7 Binary files /dev/null and b/docs/images/multiparty_system1.png differ diff --git a/docs/images/understanding_firefly1.png b/docs/images/understanding_firefly1.png new file mode 100644 index 0000000000..24ab639084 Binary files /dev/null and b/docs/images/understanding_firefly1.png differ diff --git a/docs/images/without_firefly_with_firefly.png b/docs/images/without_firefly_with_firefly.png deleted file mode 100644 index 4abddc46f5..0000000000 Binary files a/docs/images/without_firefly_with_firefly.png and /dev/null differ diff --git a/docs/images/without_firefly_with_firefly1.png b/docs/images/without_firefly_with_firefly1.png new file mode 100644 index 0000000000..c36c172045 Binary files /dev/null and b/docs/images/without_firefly_with_firefly1.png differ diff --git a/docs/index.md b/docs/index.md index c515207352..68527df5a4 100644 --- a/docs/index.md +++ b/docs/index.md @@ -4,4 +4,5 @@ title: pages.home nav_order: 1 --- -{% tf index.md %} \ No newline at end of file +{% tf index.md %} + diff --git a/docs/overview/firefly_modes/gateway/public_connector.md b/docs/overview/firefly_modes/gateway/public_connector.md new file mode 100644 index 0000000000..66a8e6e97f --- /dev/null +++ b/docs/overview/firefly_modes/gateway/public_connector.md @@ -0,0 +1,56 @@ +--- +layout: default +title: Public Blockchain Connector Toolkit +parent: Web3 Gateway Mode +grand_parent: pages.understanding_firefly +nav_order: 1 +--- + +# Blockchain Connector Toolkit +{: .no_toc } + +--- + +## FireFly architecture for public chains + +One of the fastest evolving aspects of the Hyperledger FireFly ecosystem, is how it facilitates +enterprises to participate in public blockchains. + +[![FireFly Public Transaction Architecture](../../../images/firefly_transaction_manager.jpg)](https://github.com/hyperledger/firefly-transaction-manager) + +The architecture is summarized as follows: + +- New **FireFly Transaction Manager** runtime + - Operates as a microservice extension of the FireFly Core + - Uses the `operation` resource within FireFly Core to store and update state + - Runs as a singleton and is responsible for `nonce` assignment + - Takes as much heavy lifting away from blockchain specific connectors as possible +- Lightweight FireFly Connector API (`ffcapi`) + - Simple synchronous RPC operations that map to the most common operations supported across public blockchain technologies + - Examples: + - Find the next nonce for a given signing key + - Serialize a transaction from a set of JSON inputs and an interface definition + - Submit an un-signed transaction with a given gas price to the blockchain, via a signing wallet + - Establish a new block listener + - Poll for new blocks + - Establish a new event log listener + - Poll for new events +- Pluggable **Policy Engine** + - Invoked to make decisions on transaction submission + - Responsible for gas price calculation + - Able to intervene and adjust the characteristics of signing/submission + - OSS reference implementation provided with Gas Station REST API integration +- **Confirmation Manager** + - Extracted from the Ethconnect codebase + - Coupled to both transaction submission and event confirmation + - Embeds an efficient block cache +- **Event Streams** + - Extracted from the Ethconnect codebase + - Checkpoint restart based reliable at-least-once delivery of events + - WebSockets interface upstream to FireFly Core + +This evolution involves a significant refactoring of components used for production solutions in the FireFly Ethconnect +microservice since mid 2018. This was summarized in [firefly-ethconnect#149](https://github.com/hyperledger/firefly-ethconnect/issues/149), +and cumulated in the creation of a new repository in 2022. + +You can follow the progress and contribute in this repo: https://github.com/hyperledger/firefly-transaction-manager \ No newline at end of file diff --git a/docs/overview/firefly_modes/gateway/public_private_chains.md b/docs/overview/firefly_modes/gateway/public_private_chains.md new file mode 100644 index 0000000000..df1074d2d8 --- /dev/null +++ b/docs/overview/firefly_modes/gateway/public_private_chains.md @@ -0,0 +1,66 @@ +--- +layout: default +title: Public vs. Private chains +parent: Web3 Gateway Mode +grand_parent: pages.understanding_firefly +nav_order: 1 +--- + +# Public vs. Private Chains +{: .no_toc } + +--- + +## Public and Permissioned Blockchain + +A separate choice to the technology for your blockchain, is what combination +of blockchain ecosystems you will integrate with. + +There are a huge variety of options, and increasingly you might find yourself +integrating with multiple ecosystems in your solutions. + +A rough (and incomplete) high level classification of the blockchains available is as follows: + +- Layer 1 public blockchains + - This is where most token ecosystems are rooted and some of the popular ones include Ethereum, Avalanche, BNB Chain, etc.) +- Layer 2 public scaling solutions backed by a Layer 1 blockchain + - These are increasing where transaction execution takes place that + needs to be reflected eventually back to a Layer 1 blockchain (due + to cost/congestion in the Layer 1 chains). An example of a Layer 2 solution would be Arbitrum which uses rollups to connect back to Ethereum. +- Permissioned side-chains + - Historically this has been where the majority of production adoption of + enterprise blockchain has focussed, due to the predictable cost, performance, + and ability to manage the validator set and boundary API security + alongside a business network governance policy + - These might have their state check-pointed/rolled-up to a Layer 2 or Layer 1 chain + +The lines are blurring between these categorizations as the technologies and ecosystems evolve. + +## Public blockchain variations + +For the public Layer 1 and 2 solutions, there are too many subclassifications to go into in detail here: + +- Whether ecosystems supports custom smart contract execution (EVM based is most common, where contracts are supported) +- What types of token standards are supported, or other chain specific embedded smart contracts +- Whether the chain follows an unspent transaction output (UTXO) or Account model +- How value is bridged in-to / out-of the ecosystem +- How the validator set of the chain is established - most common is Proof of Stake (PoS) +- How data availability is maintained - to check the working of the validators ensure the historical state is not lost +- The consensus algorithm, and how it interacts with the consensus of other blockchains +- How state in a Layer 2 is provable in a parent Layer 1 chain (rollup technologies etc.) + +## Common public considerations + +The thing most consistent across public blockchain technologies, is that the technical decisions are +backed by token economics. + +Put simply, creating a system where it's more financially rewarding to behave honestly, than it +is to subvert and cheat the system. + +This means that participation costs, and that the mechanisms needed to reliably get your transactions +into these systems are complex. Also that the time it might take to get a transaction onto the chain +can be much longer than for a permissioned blockchain, with the potential to have to make a number +of adjustments/resubmissions. + +The choice of whether to run your own node, or use a managed API, to access these blockchain ecosystems +is also a factor in the behavior of the transaction submission and event streaming. diff --git a/docs/overview/firefly_modes/gateway_mode.md b/docs/overview/firefly_modes/gateway_mode.md new file mode 100644 index 0000000000..cde3225e2e --- /dev/null +++ b/docs/overview/firefly_modes/gateway_mode.md @@ -0,0 +1,32 @@ +--- +layout: default +title: Web3 Gateway Mode +parent: pages.understanding_firefly +nav_order: 3 +has_children: true +--- + +# Gateway Mode + +{: .no_toc } + +## Table of contents + +{: .no_toc .text-delta } + +1. TOC +{:toc} + +--- + +## Introduction + +Web3 Gateway Mode allows your FireFly Supernode to connect to any blockchain ecosystem, public or private. When a chain is connected, the FireFly Supernode may invoke custom smart contracts, interact with tokens, and monitor transactions. A single FireFly Supernode is able to have multiple namespaces, or isolated environments, where each namespace is a connection to a different chain. + +![Gateway Mode](../../images/gateway_mode.png "Gateway Mode") + +## Use Case Example + +There are many ways to use Gateway Mode. An example could be an interaction with a public chain such as Polygon. + +Imagine as a developer that there are multiple smart contracts that you have written for use on Polygon. You can start with FireFly's API generation to have a easy to use REST API interface to interact with the smart contracts. Next, imagine that one or more of your smart contracts conforms to the ERC-20 standard. Your Supernode is able to index the token operations (mint/burn/transfer/approvals) to see transaction history and balances associated with that contract. Finally, using FireFly’s tokens api, you may further interact with that ERC20. \ No newline at end of file diff --git a/docs/overview/blockchain_protocols.md b/docs/overview/firefly_modes/multiparty/blockchain_protocols.md similarity index 95% rename from docs/overview/blockchain_protocols.md rename to docs/overview/firefly_modes/multiparty/blockchain_protocols.md index 375cdcfd36..8f3995ff86 100644 --- a/docs/overview/blockchain_protocols.md +++ b/docs/overview/firefly_modes/multiparty/blockchain_protocols.md @@ -1,19 +1,14 @@ --- layout: i18n_page title: pages.blockchain_protocols -parent: pages.understanding_firefly -nav_order: 4 +parent: Multiparty Mode +grand_parent: pages.understanding_firefly +nav_order: 1 --- # Blockchain protocols {: .no_toc } -## Table of contents -{: .no_toc .text-delta } - -1. TOC -{:toc} - --- ## Supporting multiple blockchain protocols @@ -27,7 +22,7 @@ So you can choose the blockchain ecosystem that best meets the functional and non-functional requirements of your business network, and still benefit from the developer friendly APIs, event-driven programming model, and on-chain/off-chain coordination provided by FireFly. -![FireFly Multiple Blockchain Protocols](../images/multi_protocol.png "FireFly Multiple Blockchain Protocols") +![FireFly Multiple Blockchain Protocols](../../../images/multi_protocol.png "FireFly Multiple Blockchain Protocols") ## Core constructs and custom on-chain logic diff --git a/docs/overview/broadcast.md b/docs/overview/firefly_modes/multiparty/broadcast.md similarity index 93% rename from docs/overview/broadcast.md rename to docs/overview/firefly_modes/multiparty/broadcast.md index b3b0ac32c8..bdd6c4374c 100644 --- a/docs/overview/broadcast.md +++ b/docs/overview/firefly_modes/multiparty/broadcast.md @@ -1,19 +1,14 @@ --- -layout: i18n_page -title: pages.broadcast_shared_data -parent: pages.understanding_firefly -nav_order: 8 +layout: default +title: Broadcast shared data +parent: Multiparty Mode +grand_parent: pages.understanding_firefly +nav_order: 2 --- # Broadcast / shared data {: .no_toc } -## Table of contents -{: .no_toc .text-delta } - -1. TOC -{:toc} - --- ## Introduction @@ -23,7 +18,7 @@ often that needs to include certain reference data that is available to all parties in the network. The data needs to be "broadcast" to all members, and also need to be available to new members that join the network -![Multi-party Systems](../images/multiparty_system.png "Multi-Party System") +![Multi-party Systems](../../../images/multiparty_system1.png "Multi-Party System") ## Blockchain backed broadcast diff --git a/docs/overview/data_exchange.md b/docs/overview/firefly_modes/multiparty/data_exchange.md similarity index 94% rename from docs/overview/data_exchange.md rename to docs/overview/firefly_modes/multiparty/data_exchange.md index f08572b8ee..b457bc3e89 100644 --- a/docs/overview/data_exchange.md +++ b/docs/overview/firefly_modes/multiparty/data_exchange.md @@ -1,19 +1,14 @@ --- layout: i18n_page -title: pages.private_data_exchange -parent: pages.understanding_firefly -nav_order: 7 +title: pages.data_exchange +parent: Multiparty Mode +grand_parent: pages.understanding_firefly +nav_order: 3 --- # Private data exchange {: .no_toc } -## Table of contents -{: .no_toc .text-delta } - -1. TOC -{:toc} - --- ## Introduction @@ -23,7 +18,7 @@ happens today. One party private sends data to another, over a pipe that has bee agreed as sufficiently secure between the two parties. That might be a REST API, SOAP Web Service, FTP / EDI, Message Queue (MQ), or other B2B Gateway technology. -![Multi-party Systems](../images/multiparty_system.png "Multi-Party System") +![Multi-party Systems](../../../images/multiparty_system1.png "Multi-Party System") The ability to perform these same private data exchanges within a multi-party system is critical. In fact it's common for the majority of business diff --git a/docs/overview/deterministic_compute.md b/docs/overview/firefly_modes/multiparty/deterministic.md similarity index 96% rename from docs/overview/deterministic_compute.md rename to docs/overview/firefly_modes/multiparty/deterministic.md index 80634a4cd9..4419a83616 100644 --- a/docs/overview/deterministic_compute.md +++ b/docs/overview/firefly_modes/multiparty/deterministic.md @@ -1,19 +1,14 @@ --- -layout: default -title: Deterministic compute -parent: pages.understanding_firefly -nav_order: 6 +layout: i18n_page +title: pages.deterministic +parent: Multiparty Mode +grand_parent: pages.understanding_firefly +nav_order: 3 --- -# Deterministic compute +# Deterministic Compute {: .no_toc } -## Table of contents -{: .no_toc .text-delta } - -1. TOC -{:toc} - --- ## Introduction @@ -121,4 +116,4 @@ Not to be overlooked is the sometimes astonishing efficiency increase that can b business relationships, by being able to agree the order and sequence of a set of events. Having the tools to digitize processes that previously took physical documents flying round the world, into near-immediate digital agreement where the arbitration of a dispute can be resolved at a tiny fraction -of what would have been possible without a shared and immutable audit trail of who said what when. +of what would have been possible without a shared and immutable audit trail of who said what when. --> diff --git a/docs/overview/multiparty_process_flow.md b/docs/overview/firefly_modes/multiparty/multiparty_flow.md similarity index 58% rename from docs/overview/multiparty_process_flow.md rename to docs/overview/firefly_modes/multiparty/multiparty_flow.md index ec8e988d2a..6106d578eb 100644 --- a/docs/overview/multiparty_process_flow.md +++ b/docs/overview/firefly_modes/multiparty/multiparty_flow.md @@ -1,20 +1,65 @@ --- -layout: default -title: Multi-party process flow -parent: pages.understanding_firefly -nav_order: 9 +layout: i18n_page +title: pages.multiparty_flow +parent: Multiparty Mode +grand_parent: pages.understanding_firefly +nav_order: 5 --- -# Multi-party process flow +# Multiparty Process Flows {: .no_toc } -## Table of contents -{: .no_toc .text-delta } +--- -1. TOC -{:toc} +## Flow features ---- +Data, value, and process flow are how decentralized systems function. In an enterprise context +not all of this data can be shared with all parties, and some is very sensitive. + +### Private data flow + +Managing the flows of data so that the right information is shared with the right parties, +at the right time, means thinking carefully about what data flows over what channel. + +The number of enterprise solutions where all data can flow directly through the blockchain, +is vanishingly small. + +Coordinating these different data flows is often one of the biggest pieces of heavy lifting solved +on behalf of the application by a robust framework like FireFly: + +- Establishing the identity of participants so data can be shared +- Securing the transfer of data off-chain +- Coordinating off-chain data flow with on-chain data flow +- Managing sequence for deterministic outcomes for all parties +- Integrating off-chain private execution with multi-step stateful business logic + +### Multi-party business process flow + +Web3 has the potential to transform how ecosystems interact. Digitally transforming +legacy process flows, by giving deterministic outcomes that are trusted by all parties, +backed by new forms of digital trust between parties. + +Some of the most interesting use cases require complex multi-step business process across +participants. The Web3 version of business process management, comes with a some new challenges. + +So you need the platform to: + +- Provide a robust event-driven programming model fitting a "state machine" approach +- Integrate with the decentralized application stack of each participant +- Allow integration with the core-systems and human decision making of each participant +- Provide deterministic ordering between all parties +- Provide identity assurance and proofs for data flow / transition logic + +### Data exchange + +Business processes need data, and that data comes in many shapes and sizes. + +The platform needs to handle all of them: + +- Large files and documents, as well as application data +- Uniqueness / Enterprise NFTs - agreement on a single "foreign key" for a record +- Non-repudiation, and acknowledgement of receipt +- Coordination of flows of data, with flows of value - delivery vs. payment scenarios ## Building multi-party flows @@ -22,7 +67,7 @@ The ability to globally sequence events _across parties_ is a game changing capa systems. FireFly is designed to allow developers to harnesses that power in the application layer, to build sophisticated multi-party APIs and user experiences. -[![Multi-party business process flow](../images/multiparty_business_process_flow.svg "Multi-party business process flow")](../images/multiparty_business_process_flow.svg) +[![Multi-party business process flow](../../../images/multiparty_business_process_flow.svg "Multi-party business process flow")](../../../images/multiparty_business_process_flow.svg) - Build multi-party business processes where there is one agreed outcome: - Agree the trigger, inputs, outputs of each step in the process @@ -73,10 +118,10 @@ In the _deterministic compute_ section we talked about the value that determinis of multi-party logic can have. Either through on-chain execution, or advanced privacy preserving techniques. -It's important to state that almost every process can be enhanced with more sophisticated +It's important to state that almost every process can be enhanced with more sophisticated on-chain constructs like tokens. Maybe it's to build a token economy that enhances the value parties get from the system, or encourages healthy participation (and discourages leaching value). -Or maybe it's to track exactly which party owns a document, asset, or action within a process using NFTs. +Or maybe it's to track exactly which party owns a document, asset, or action within a process using NFTs. There are also cases where the foundation constructs are insufficient to implement the level of automation or efficiency you need in your multi-party process. Here making the investment in building diff --git a/docs/overview/multiparty.md b/docs/overview/firefly_modes/multiparty_mode.md similarity index 51% rename from docs/overview/multiparty.md rename to docs/overview/firefly_modes/multiparty_mode.md index 22efd359b1..282c353255 100644 --- a/docs/overview/multiparty.md +++ b/docs/overview/firefly_modes/multiparty_mode.md @@ -1,14 +1,17 @@ --- layout: default -title: Multi-party Systems +title: Multiparty Mode parent: pages.understanding_firefly -nav_order: 2 +nav_order: 4 +has_children: true --- # Enterprise multi-party systems + {: .no_toc } ## Table of contents + {: .no_toc .text-delta } 1. TOC @@ -18,7 +21,9 @@ nav_order: 2 ## Introduction -Multi-party systems are a class of application empowered by the technology revolution +Multiparty mode has all the features in Gateway mode with the added benefit of multi-party process flows. + +A multi-party system is a class of application empowered by the technology revolution of blockchain digital ledger technology (DLT), and emerging cryptographic proof technologies like zero-knowledge proofs (ZKPs) and trusted execution environments (TEEs). @@ -26,11 +31,11 @@ By combining these technologies with existing best practice technologies for data security in regulated industries, multi-party systems allow businesses to collaborate in ways previously impossible. -![Multi-party Systems](../images/multiparty_system.png "Multi-Party System") +![Multiparty Mode](../../images/multiparty_mode.png "Multiparty Mode") Through agreement on a common source of truth, such as the completion of a step in a business process to proceed, or the existence and ownership of a unique asset, businesses -can cut out huge inefficiencies in existing multi-party processes. +can cut out huge inefficiencies in existing multi-party processes. New business and transaction models can be achieved, unlocking value in assets and data that were previously siloed within a single organization. Governance and incentive @@ -50,8 +55,21 @@ each party, rather than seeking to unify or replace them. Multi-party systems are different from centralized third-party systems, because each party retains sovereignty over: - - Their application instance - - Their private data - - Their business processes - - Their proprietary business logic - - Their internal business processes and IT controls + +- Their application instance +- Their private data +- Their business processes +- Their proprietary business logic +- Their internal business processes and IT controls + +## Use Case Example + +There are many multiparty use cases. An example for healthcare is detailed below. + +Patient care requires multiple entities to work together including healthcare providers, insurance companies, and medical systems. Sharing data between these parties is inefficient and prone to errors and patient information must be kept secure and up to date. Blockchain's shared ledger makes it possible to automate data sharing while ensuring accuracy and privacy. + +In a Multi-party FireFly system, entities are able to share data privately as detailed in the "Data Exchange" section. For example, imagine a scenario where there is 1 healthcare provide and 2 insurance companies operating in a multi-party system. Insurance company A may send private data to the healthcare provider that insurance company B is not privy to. While insurance company B may not know the contents of data transferred, it may verify that a transfer of data did occur. This validation is all thats needed to maintain an up to date state of the blockchain. + +In a larger healthcare ecosystem with many members, a similar concept may emerge with multiple variations of members. + + \ No newline at end of file diff --git a/docs/overview/firefly_node.md b/docs/overview/firefly_node.md deleted file mode 100644 index 0c623f4985..0000000000 --- a/docs/overview/firefly_node.md +++ /dev/null @@ -1,57 +0,0 @@ ---- -layout: default -title: The FireFly node -parent: pages.understanding_firefly -nav_order: 3 ---- - -# The FireFly node -{: .no_toc } - -## Table of contents -{: .no_toc .text-delta } - -1. TOC -{:toc} - ---- - -## FireFly node runtimes - -A FireFly node is a collection of multiple microservice runtimes with a single unified HTTPS/Websocket API (exposed by the Core). - -![The FireFly node](../images/firefly_node.png "The FireFly node") - -The minimum set of runtimes is as follows: - -- FireFly Core - the API and event server for your multi-party applications -- Blockchain node - the decentralized ledger technology establishing a shared source of truth -- Blockchain interface - transaction submission and event streams for your chosen protocol -- Shared storage node - a network-wide peer-to-peer store of shared data -- Data exchange - for private member to member communications of messages and files - -> _Check out the [FireFly CLI](https://github.com/hyperledger/firefly-cli) to get a -> a multi-party system running on your laptop in minutes._ - -## Pluggable microservices architecture - -The runtimes are pluggable, allowing technology choice, and extensibility. - -- FireFly Core - - Orchestration engine - manages lifecycle of assets and data - - Hosts the API and UI - applications connect here - - Maintains private storage - - Written in Go -- Connectors - - Runtimes that bridge the core to multi-party infrastructure - - Can be written in any language Go, Java, Node.js etc. - - Can be stateful or stateless, depending on requirements - - Can contain significant function, such as managed file transfer, or e2e encryption -- Infrastructure runtimes - - Can be local runtimes, or cloud services - - Blockchain nodes - Fabric, Ethereum, Corda etc. - - Database servers - PostgreSQL, SQLite, CouchDB etc. - - Private messaging - Kafka, RabbitMQ, ActiveMQ, Mosquitto etc. - - Private blob storage - Kubernetes PVCs, AWS S3, Azure File etc. - - Public blob storage - IPFS, etc. - - ... and more - token bridges, trusted compute engines, etc. diff --git a/docs/overview/index.md b/docs/overview/index.md index 2d11133f39..cb5bbd1869 100644 --- a/docs/overview/index.md +++ b/docs/overview/index.md @@ -15,6 +15,6 @@ has_children: true --- -![Hyperledger FireFly features](../images/firefly_functionality_overview.png) - +![Hyperledger FireFly features](../images/understanding_firefly1.png) +In this section we'll go over what FireFly is, the different modes, and why you should use FireFly. For a more technical discussion check out our [Reference](../reference/) and [Architecture](../architecture/) sections. diff --git a/docs/overview/key_components/apps.md b/docs/overview/key_components/apps.md new file mode 100644 index 0000000000..3887b90999 --- /dev/null +++ b/docs/overview/key_components/apps.md @@ -0,0 +1,74 @@ +--- +layout: default +title: Apps +parent: The Key Components +grand_parent: pages.understanding_firefly +nav_order: 2 +--- + +# Apps +{: .no_toc } + +--- + +## Application features + +Rapidly accelerating development is a key requirement of any Supernode. + +The business logic APIs, web and mobile user experiences for Web3 applications need to be just as rich +and feature-full as the Web 2.0 / centralized applications. + +That means developers skilled in these application layers, must have the tools they need. + +Capabilities fitting their application development toolchain, and optimized to their skillset. + +### API Gateway + +Modern APIs that: + +- Are fast and efficient +- Have rich query support +- Give deterministic outcomes and clear instruction for safe use +- Integrate with your security frameworks like OAuth 2.0 / OpenID Connect single sign-on +- Provide Open API 3 / Swagger definitions +- Come with code SDKs, with rich type information +- Conform as closely as possible to the principles of REST +- Do not pretend to be RESTful in cases when it is impossible to be + +### Event Streams + +The reality is that the only programming paradigm that works for a decentralized solutions, +is an event-driven one. + +All blockchain technologies are for this reason event-driven programming interfaces at their core. + +In an overall solution, those on-chain events must be coordinated with off-chain private +data transfers, and existing core-systems / human workflows. + +This means great event support is a must: + +- Convenient WebSocket APIs that work for your microservices development stack +- Support for Webhooks to integrated serverless functions +- Integration with your core enterprise message queue (MQ) or enterprise service bus (ESB) +- At-least-once delivery assurance, with simple instructions at the application layer + +### API Generation + +The blockchain is going to be at the heart of your Web3 project. While usually small in overall surface +area compared to the lines of code in the traditional application tiers, this kernel of +mission-critical code is what makes your solution transformational compared to a centralized / Web 2.0 solution. + +Whether the smart contract is hand crafted for your project, an existing contract on a public blockchain, +or a built-in pattern of a framework like FireFly - it must be interacted with correctly. + +So there can be no room for misinterpretation in the hand-off between the blockchain +Smart Contract specialist, familiar with EVM contracts in Solidity/Vyper, Fabric chaincode +(or maybe even raw block transition logic in Rust or Go), and the backend/full-stack +application developer / core-system integrator. + +Well documented APIs are the modern norm for this, and it is no different for blockchain. This means: + +- Generating the interface for methods and events on your smart contract +- Providing robust transaction submission, and event streaming +- Publishing the API, version, and location, of your smart contracts to the network + diff --git a/docs/overview/key_components/digital_assets.md b/docs/overview/key_components/digital_assets.md new file mode 100644 index 0000000000..607be85672 --- /dev/null +++ b/docs/overview/key_components/digital_assets.md @@ -0,0 +1,67 @@ +--- +layout: default +title: Digital Assets +parent: The Key Components +grand_parent: pages.understanding_firefly +nav_order: 3 +--- + +# Digital Assets +{: .no_toc } + +--- + +## Digital asset features + +The modelling, transfer and management of digital assets is the core programming +foundation of blockchain. + +Yet out of the box, raw blockchains designed to efficiently manage these assets +in large ecosystems, do not come with all the building blocks needed by applications. + +### Token API + +Tokens are such a fundamental construct, that they justify a standard API. +This has been evolving in the industry through standards like ERC-20/ERC-721, +and Web3 signing wallets and that support these. + +Supernodes bring this same standardization to applications. Providing APIs +that work across token standards, and blockchain implementations, providing +consistent and interoperable support. + +This means one application or set of back-end systems, can integrate with multiple +blockchains, and different token implementations. + +Pluggability here is key, so that the rules of governance of each digital +asset ecosystem can be exposed and enforced. Whether tokens are fungible, +non-fungible, or some hybrid in between. + +### Transfer history / audit trail + +For efficiency blockchains seldom provide in their core the ability to +query historical transaction information. Sometimes even the ability +to query balances is unavailable, for blockchains based on a UTXO model. + +So off-chain indexing of transaction history is an absolute must-have +for any digital asset solution, or even a simple wallet application. + +A platform like Hyperledger FireFly provides: + +- Automatic indexing of tokens, whether existing or newly deployed +- Off-chain indexing of fungible and non-fungible asset transfers & balances +- Off-chain indexing of approvals +- Integration with digital identity +- Full extensibility across both token standards and blockchain technologies + +### Wallets + +Wallet and signing-key management is a critical requirement for any +blockchain solution, particularly those involving the transfer +of digital assets between wallets. + +A platform like Hyperledger FireFly provides you the ability to: + +- Integrate multiple different signing/custody solutions in a proven way +- Manage the mapping of off-chain identities to on-chain signing identities +- Provide a plug-point for policy-based decision making on high value transactions +- Manage connections to multiple different blockchain solutions diff --git a/docs/overview/key_components/firefly_core.md b/docs/overview/key_components/firefly_core.md new file mode 100644 index 0000000000..ff3d47ffee --- /dev/null +++ b/docs/overview/key_components/firefly_core.md @@ -0,0 +1,21 @@ +--- +layout: default +title: FireFly Core +parent: The Key Components +grand_parent: pages.understanding_firefly +nav_order: 5 +--- + +# FireFly Core + +{: .no_toc } + +--- + +## FireFly Core Overview + +FireFly Core acts as the brain for the Supernode. It is written in Go and hosts the API and UI. The two main components include the Event Bus and the orchestration layer. The Event Bus receives inputs from connected data sources, including on chain data, shared storage, and private data, as well as security and API layers. + +The second portion is the Orchestration Engine which takes inputs from the Event Bus as well as user commands from the FireFly CLI (command line interface) and manages the lifecycle of assets and data. The Orchestration Engine then translates these inputs into data and state that is viewable in the FireFly Explorer. + +![FireFly Core](../../images/firefly_core.png "FireFly Core") diff --git a/docs/overview/firefly_supernode.md b/docs/overview/key_components/firefly_supernode.md similarity index 97% rename from docs/overview/firefly_supernode.md rename to docs/overview/key_components/firefly_supernode.md index 1e9776efdc..54e1b1698d 100644 --- a/docs/overview/firefly_supernode.md +++ b/docs/overview/key_components/firefly_supernode.md @@ -1,11 +1,12 @@ ---- + diff --git a/docs/overview/key_components/security.md b/docs/overview/key_components/security.md new file mode 100644 index 0000000000..cc309e9187 --- /dev/null +++ b/docs/overview/key_components/security.md @@ -0,0 +1,64 @@ +--- +layout: default +title: Security +parent: The Key Components +grand_parent: pages.understanding_firefly +nav_order: 1 +--- + +# Security +{: .no_toc } + +--- + +## Security + + + +Data, value, and process flow are how decentralized systems function. In an enterprise context +not all of this data can be shared with all parties, and some is very sensitive. + +### Private data flow + +Managing the flows of data so that the right information is shared with the right parties, +at the right time, means thinking carefully about what data flows over what channel. + +The number of enterprise solutions where all data can flow directly through the blockchain, +is vanishingly small. + +Coordinating these different data flows is often one of the biggest pieces of heavy lifting solved +on behalf of the application by a robust framework like FireFly: + +- Establishing the identity of participants so data can be shared +- Securing the transfer of data off-chain +- Coordinating off-chain data flow with on-chain data flow +- Managing sequence for deterministic outcomes for all parties +- Integrating off-chain private execution with multi-step stateful business logic + +### Multi-party business process flow + +Web3 has the potential to transform how ecosystems interact. Digitally transforming +legacy process flows, by giving deterministic outcomes that are trusted by all parties, +backed by new forms of digital trust between parties. + +Some of the most interesting use cases require complex multi-step business process across +participants. The Web3 version of business process management, comes with a some new challenges. + +So you need the platform to: + +- Provide a robust event-driven programming model fitting a "state machine" approach +- Integrate with the decentralized application stack of each participant +- Allow integration with the core-systems and human decision making of each participant +- Provide deterministic ordering between all parties +- Provide identity assurance and proofs for data flow / transition logic + +### Data exchange + +Business processes need data, and that data comes in many shapes and sizes. + +The platform needs to handle all of them: + +- Large files and documents, as well as application data +- Uniqueness / Enterprise NFTs - agreement on a single "foreign key" for a record +- Non-repudiation, and acknowledgement of receipt +- Coordination of flows of data, with flows of value - delivery vs. payment scenarios \ No newline at end of file diff --git a/docs/overview/key_components/tools.md b/docs/overview/key_components/tools.md new file mode 100644 index 0000000000..6c646f471f --- /dev/null +++ b/docs/overview/key_components/tools.md @@ -0,0 +1,37 @@ +--- +layout: default +title: Tools +parent: The Key Components +grand_parent: pages.understanding_firefly +nav_order: 4 +--- + +# Tools + +{: .no_toc } + +--- + +## Tools Overview + +There are three main tools within FireFly which are the command line interface (CLI), FireFly Explorer, and FireFly Sandbox. + +## FireFly CLI + +![FireFly CLI](../../images/firefly_cli.png) + +The FireFly CLI can be used to create local FireFly stacks for offline development of blockchain apps. This allows developers to rapidly iterate on their idea without needing to set up a bunch of infrastructure before they can write the first line of code. + +## FireFly Sandbox + +![FireFly Sandbox](../../images/sandbox/sandbox_broadcast.png) + +The FireFly Sandbox sits logically outside the Supernode, and it acts like an "end-user" application written to use FireFly's API. In your setup, you have one Sandbox per member, each talking to their own FireFly API. The purpose of the Sandbox is to provide a quick and easy way to try out all of the fundamental building blocks that FireFly provides. It also shows developers, through example code snippets, how they would implement the same functionality in their own app's backend. + +> 🗒 Technical details: The FireFly Sandbox is an example "full-stack" web app. It has a backend written in TypeScript / Node.js, and a frontend in TypeScript / React. When you click a button in your browser, the frontend makes a request to the backend, which then uses the [FireFly Node.js SDK](https://www.npmjs.com/package/@hyperledger/firefly-sdk) to make requests to FireFly's API. + +## FireFly Explorer + +The FireFly explorer is a part of FireFly Core itself. It is a view into the system that allows operators to monitor the current state of the system and investigate specific transactions, messages, and events. It is also a great way for developers to see the results of running their code against FireFly's API. + +![FireFly Explorer](../../images/firefly_explorer.png) diff --git a/docs/overview/public_vs_permissioned.md b/docs/overview/public_vs_permissioned.md index 499ef617e3..2e1aee2a63 100644 --- a/docs/overview/public_vs_permissioned.md +++ b/docs/overview/public_vs_permissioned.md @@ -1,4 +1,4 @@ ---- + diff --git a/docs/overview/supernode_concept.md b/docs/overview/supernode_concept.md new file mode 100644 index 0000000000..d8cd78ed4d --- /dev/null +++ b/docs/overview/supernode_concept.md @@ -0,0 +1,59 @@ +--- +layout: default +title: Introduction to Supernodes +parent: pages.understanding_firefly +nav_order: 1 +--- + +# Introduction to SuperNodes +{: .no_toc } + +## Table of contents +{: .no_toc .text-delta } + +1. TOC +{:toc} + +--- + +## What is a Supernode + +A FireFly Supernode is designed to be an organization's connection to Web 3 and to all the blockchain ecosystems that they participate in - multiple blockchains, multiple token economis, or multiple business networks. What makes a SuperNode "super" compared to a regular node is that it includes a blockchain developers toolkit under the hood. This includes a security layer, orchestration engine, token connectors, API identity management, and much more. + +Over the last decade of enterprise blockchain projects, architects, and developers have realized +that they need much more than a blockchain node for their projects to be successful. + +The development stack needed for an enterprise grade Web3 application is just as sophisticated as the stack required for the Web 2.0 applications that came before. + +A raw blockchain node is simply not enough. + +## Your project with or without a Supernode + +![Without FireFly / with FireFly](../images/without_firefly_with_firefly1.png) + +So your choice as a development team for a blockchain project becomes whether you build +and update all of the "plumbing" / "middleware" components needed underneath your business +logic yourself, or whether you look for pre-built solutions. + +The Hyperledger FireFly approach is to allow the community to collaborate on the development and hardening of +these components, across industries and projects. Then fit them into an open source, enterprise grade, +pluggable development and runtime stack... the _Supernode_. + +The application developers then code against these APIs, and can be confident that the business logic that works +on their local laptop against a sandbox, is being written in a way that scales to an enterprise +decentralized application and can be deployed against one or more public/private blockchains in production. + +Thus allowing development teams to focus on differentiation where it matters - at the solution layer. + +## Web3 Gateway and Multiparty Mode + +There are two main modes that a Supernode can operate in which are Web3 Gateway and Multiparty mode. + +Web3 Gateway mode may be used to simplify the processes of invoking smart contracts, interacting with digital assets, and exchanging value in existing blockchain ecosystems. Existing ecosystems may be public chains (i.e. Ethereum, Polygon, etc.) or private chains that have been created. + +Multiparty mode is used with multi-party systems. The key difference compared to Gateway mode is that not only can your Supernode interact with a blockchain, but it can also share data, send messages, and transact with other members in the multi-party system. A multi-party system is a blockchain where a decentralized application is running across a set of participants. Every member in the ecosystem runs their own FireFly Supernode with a copy of the same application stack on top. + +![Gateway & Multiparty Mode](../images/gateway_multiparty_mode.png "Gateway & Multiparty Mode") + +To learn more about each mode, check out the [Web3 Gateway Mode](./firefly_modes/gateway_mode.html) and [Multiparty Mode](./firefly_modes/multiparty_mode.html) sections. + diff --git a/docs/overview/the_key_components.md b/docs/overview/the_key_components.md new file mode 100644 index 0000000000..6404c0d18e --- /dev/null +++ b/docs/overview/the_key_components.md @@ -0,0 +1,19 @@ +--- +layout: default +title: The Key Components +parent: pages.understanding_firefly +nav_order: 2 +has_children: true +--- + +# The Key Components +{: .no_toc } + + + +--- +![Hyperledger FireFly features](../images/firefly_functionality_overview.png) + +This section will introduce in detail the 5 key layers to a FireFly Supernode. + + diff --git a/docs/overview/why_firefly.md b/docs/overview/why_firefly.md new file mode 100644 index 0000000000..81a1d89feb --- /dev/null +++ b/docs/overview/why_firefly.md @@ -0,0 +1,43 @@ +--- +layout: default +title: Why FireFly +parent: pages.understanding_firefly +nav_order: 5 +--- + +# Why FireFly +{: .no_toc } + + +--- +## Types of blockchain project that benefit + +There are two main reasons your project might be exploring Supernodes, and considering the open source +approach of Hyperledger FireFly. + +### Solution builders + +Teams building new decentralized Web3 solutions need a full technology stack for +the application, to manage both private and blockchain data. Particularly in the enterprise space +due to data security, regulatory and privacy concerns. + +For theses solutions to be successful, they need decentralized deployment to multiple parties. +Each party needs to customize the deployment to their SecDevOps environment, as well as +onboard it to their key management solution etc. + +So the complexity of requiring a bespoke technology stack for a solution can be a barrier to its adoption. + +Whereas, building on top of a standardized and open technology stack can ease adoption, as well +as radically reducing the amount of engineering needed by the solution developer. + +### Organizations needing a gateway to Web3 + +Organizations are increasingly participating in multiple blockchain projects, and integrating with +digital assets in multiple blockchain ecosystems. + +This means core IT security policy needs to scale to the challenge of adding these connections, +and managing the wallets / signing identities, data flow, and SecDevOps requirements across multiple +projects. + +A gateway tier at the edge between the core systems of the enterprise, and the Web3 transactions, +helps reduce the overhead, and reduce risk. \ No newline at end of file diff --git a/docs/reference/events.md b/docs/reference/events.md index 2629df8dd0..d182c530a3 100644 --- a/docs/reference/events.md +++ b/docs/reference/events.md @@ -30,7 +30,7 @@ like NATS, Kafka, and JMS Servers can be connected through plugins. Each application creates one or more [Subscriptions](./types/subscription.md) to identify itself. In this subscription the application can choose to receive all events that -are emitted within a `namespace`, or can use server-side filtering to +are emitted within a `namespace`, or can use server-side filtering to only receive a sub-set of events. The event bus reliably keeps track of which events have been delivered to which @@ -136,7 +136,7 @@ cheat, and must follow the rules. How much of that rule enforcement needs to be executed on-chain vs. off-chain (backed by a deterministic order through the blockchain) is different for each use case. -> Remember that tokens provide a great set of building blocks for on-chain steps in +> Remember that tokens provide a great set of building blocks for on-chain steps in > your decentralized applications. Enterprise NFTs allow generation of a globally > unique ID, and track ownership. Fungible tokens allow value transfer, and can be > extended with smart contracts that to lock/unlock funds in "digital escrow" @@ -246,7 +246,7 @@ API and Events directly. Event aggregation between data arriving off-chain, and the associated ordered proof/transaction events being confirmed on-chain, is a complex orchestration task. -The universal order and additional transaction logic **on-chain must be the +The universal order and additional transaction logic **on-chain must be the source of truth** for when and how an event is processed. However, that event cannot be processed until the off-chain private/broadcast data diff --git a/docs/tutorials/broadcast_data.md b/docs/tutorials/broadcast_data.md index 2e90b5a266..743c54f07c 100644 --- a/docs/tutorials/broadcast_data.md +++ b/docs/tutorials/broadcast_data.md @@ -2,7 +2,7 @@ layout: i18n_page title: pages.broadcast_data parent: pages.tutorials -nav_order: 4 +nav_order: 1 --- # Broadcast data @@ -33,7 +33,7 @@ nav_order: 4 ## Additional info -- Key Concepts: [Broadcast / shared data](../overview/broadcast.md) +- Key Concepts: [Broadcast / shared data](../overview/firefly_modes/multiparty/broadcast.md) - Swagger Reference: POST /api/v1/namespaces/{ns}/messages/broadcast ## Example 1: Inline string data @@ -221,7 +221,7 @@ In the sandbox, enter your message into the message field as seen in the screens 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. +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) diff --git a/docs/tutorials/chains/Arbitrum.md b/docs/tutorials/chains/Arbitrum.md new file mode 100644 index 0000000000..ab23a54e16 --- /dev/null +++ b/docs/tutorials/chains/Arbitrum.md @@ -0,0 +1,111 @@ +--- +layout: i18n_page +title: pages.arbitrum +parent: pages.chains +grand_parent: pages.tutorials +nav_order: 4 +--- + + +# {%t pages.arbitrum %} +{: .no_toc } + +## Table of contents +{: .no_toc .text-delta } + +1. TOC +{:toc} + +--- + +Starting with FireFly v1.1, it's easy to connect to public Ethereum chains. This guide will walk you through the steps to create a local FireFly development environment and connect it to the Arbitrum Nitro Goerli Rollup Testnet. + +## Previous steps: Install the FireFly CLI +If you haven't set up the FireFly CLI already, please go back to the Getting Started guide and read the section on how to [Install the FireFly CLI](../../gettingstarted/firefly_cli.md). + +[← ① Install the FireFly CLI](../../gettingstarted/firefly_cli.md){: .btn .btn-purple .mb-5} + +## Create an `evmconnect.yml` config file +In order to connect to the Binance Smart Chain testnet, you will need to set a few configuration options for the evmconnect blockchain connector. Create a text file called `evmconnect.yml` with the following contents: + +```yml +confirmations: + required: 4 +policyengine.simple: + fixedGasPrice: null + gasOracle: + mode: connector +``` + +For this tutorial, we will assume this file is saved at `~/Desktop/evmconnect.yml`. If your path is different, you will need to adjust the path in the next command below. + +## Creating a new stack +To create a local FireFly development stack and connect it to the Arbitrum testnet, we will use command line flags to customize the following settings: + + - Create a new stack named `arbitrum` with `1` member + - Disable `multiparty` mode. We are going to be using this FireFly node as a Web3 gateway, and we don't need to communicate with a consortium here + - Connect to an ethereum network + - Use the `evmconnect` blockchain connector + - Use an remote RPC node. This will create a signer locally, so that our signing key never leaves the development machine. + - Set the remote RPC node URL to `https://goerli-rollup.arbitrum.io/rpc` (for a full list of testnet RPC node urls visit https://developer.offchainlabs.com/docs/Public_Chains) + - Set the chain ID to `421613` (the correct ID for the Binance Smart Chain testnet) + - Merge the custom config created above with the generated `evmconnect` config file + +To do this, run the following command: +``` +ff init arbitrum 1 \ + --multiparty=false \ + -b ethereum \ + -c evmconnect \ + -n remote-rpc \ + --remote-node-url https://goerli-rollup.arbitrum.io/rpc \ + --chain-id 421613 \ + --connector-config ~/Desktop/evmconnect.yml +``` + +## Start the stack +Now you should be able to start your stack by running: + +``` +ff start arbitrum +``` + +After some time it should print out the following: + +``` +Web UI for member '0': http://127.0.0.1:5000/ui +Sandbox UI for member '0': http://127.0.0.1:5109 + + +To see logs for your stack run: + +ff logs arbitrum +``` + +## Get some Aribitrum +At this point you should have a working FireFly stack, talking to a public chain. However, you won't be able to run any transactions just yet, because you don't have any way to pay for gas. + +First, you will need to know what signing address your FireFly node is using. To check that, you can run: + +``` +ff accounts list arbitrum +[ + { + "address": "0x225764d1be1f137be23ddfc426b819512b5d0f3e", + "privateKey": "..." + } +] +``` + +Copy the address listed in the output from this command. Next, check out this article [https://medium.com/offchainlabs/new-g%C3%B6rli-testnet-and-getting-rinkeby-ready-for-nitro-3ff590448053](https://medium.com/offchainlabs/new-g%C3%B6rli-testnet-and-getting-rinkeby-ready-for-nitro-3ff590448053) and follow the instructions to send a tweet to the developers. Make sure to change the address to the one in the CLI. + +![Arbitrum Faucet](images/arbitrum_faucet.png) + +### Confirm the transaction on Bscscan +You should be able to go lookup your account on [https://goerli-rollup-explorer.arbitrum.io/](https://goerli-rollup-explorer.arbitrum.io/) and see that you now have a balance of 0.001 ether. Simply paste in your account address to search for it. + + +![Blockscout Scan](images/arbitrum_scan.png) + +## Use the public testnet +Now that you have everything set up, you can follow one of the other FireFly guides such as [Using Tokens](../tokens/index.md) or [Custom Smart Contracts](../custom_contracts/ethereum.md). For detailed instructions on deploying a custom smart contract to Binance Smart Chain, please see the [Arbitrum docs](https://developer.offchainlabs.com/docs/Contract_Deployment) for instructions using various tools. \ No newline at end of file diff --git a/docs/tutorials/chains/NEAR.md b/docs/tutorials/chains/NEAR.md new file mode 100644 index 0000000000..21b3e3b243 --- /dev/null +++ b/docs/tutorials/chains/NEAR.md @@ -0,0 +1,117 @@ +--- +layout: i18n_page +title: pages.near +parent: pages.chains +grand_parent: pages.tutorials +nav_order: 6 +--- + + +# {%t pages.near %} +{: .no_toc } + +## Table of contents +{: .no_toc .text-delta } + +1. TOC +{:toc} + +--- + +Starting with FireFly v1.1, it's easy to connect to public Ethereum chains. This guide will walk you through the steps to create a local FireFly development environment and connect it to the NEAR testnet. + +## Previous steps: Install the FireFly CLI +If you haven't set up the FireFly CLI already, please go back to the Getting Started guide and read the section on how to [Install the FireFly CLI](../../gettingstarted/firefly_cli.md). + +[← ① Install the FireFly CLI](../../gettingstarted/firefly_cli.md){: .btn .btn-purple .mb-5} + +## Create an `evmconnect.yml` config file +In order to connect to the NEAR testnet, you will need to set a few configuration options for the evmconnect blockchain connector. Create a text file called `evmconnect.yml` with the following contents: + +```yml +confirmations: + required: 4 +policyengine.simple: + fixedGasPrice: null + gasOracle: + mode: connector +``` + +For this tutorial, we will assume this file is saved at `~/Desktop/evmconnect.yml`. If your path is different, you will need to adjust the path in the next command below. + +## Creating a new stack +To create a local FireFly development stack and connect it to the NEAR testnet, we will use command line flags to customize the following settings: + + - Create a new stack named `near` with `1` member + - Disable `multiparty` mode. We are going to be using this FireFly node as a Web3 gateway, and we don't need to communicate with a consortium here + - Connect to an ethereum network + - Use the `evmconnect` blockchain connector + - Use an remote RPC node. This will create a signer locally, so that our signing key never leaves the development machine. + - Set the remote RPC node URL to `https://rpc.testnet.near.org` (RPC nodes for other NEAR networks may be found here https://docs.near.org/api/rpc/setup) + - Set the chain ID to any number (NEAR works with any chain ID) + - Merge the custom config created above with the generated `evmconnect` config file + +To do this, run the following command: +``` +ff init near 1 \ + --multiparty=false \ + -b ethereum \ + -c evmconnect \ + -n remote-rpc \ + --remote-node-url https://rpc.testnet.near.org \ + --chain-id 1 \ + --connector-config ~/Desktop/evmconnect.yml +``` + +## Start the stack +Now you should be able to start your stack by running: + +``` +ff start near +``` + +After some time it should print out the following: + +``` +Web UI for member '0': http://127.0.0.1:5000/ui +Sandbox UI for member '0': http://127.0.0.1:5109 + + +To see logs for your stack run: + +ff logs near +``` + +## Get some NEAR +At this point you should have a working FireFly stack, talking to a public chain. However, you won't be able to run any transactions just yet, because you don't have any way to pay for gas. A testnet faucet can give us some NEAR, the native token for the NEAR protocol. + +First, you will need to know what signing address your FireFly node is using. To check that, you can run: + +``` +ff accounts list near +[ + { + "address": "0xa4ed2a9a99dfdf46f1812c38a1656ff2ad1f61da", + "privateKey": "..." + } +] +``` +Note, for the NEAR protocol, the line labeled privateKey is the address you will use. + +Go to [https://near-faucet.io/](https://near-faucet.io/) and click **Connect with Near Testnet**. Next click **Create Accounte**, make an account ID, and choose a security method. Follow the steps for either the Seedphrase or Ledger Hardware Wallet until your NEAR account is created. Once complete you will be redirected to the original https://near-faucet.io/ page and are now able to request 20 NEAR tokens. + +![NEAR Faucet](images/near_faucet.png) +![NEAR Account](images/near_account.png) +![NEAR Account Name](images/near_account_name.png) +![Fund Account](images/near_fund_account.png) + +### Confirm the transaction on NEAR Testnet Explorer +Once the request for 20 NEAR tokens is completed, go to [https://explorer.testnet.near.org/](https://explorer.testnet.near.org/) and search via your account name. Once it is found click on the link under **Balance Profile** to access your NEAR wallet. From here, click the **Wallet** button in the top left and then **Send**. Choose a denomination of NEAR to send, enter your 64 character string denominated as privateKey from the FireFly CLI, and you will now have funded tokens in your account. + + +![NEAR Scan](images/near_scan.png) +![Account Lookup](images/near_account_lookup.png) +![NEAR Wallet Send Funds](images/near_wallet_send_funds.png) + +## Use the public testnet +Now that you have everything set up, you can follow one of the other FireFly guides such as [Using Tokens](../tokens/index.md) or [Custom Smart Contracts](../custom_contracts/ethereum.md). For detailed instructions on deploying a custom smart contract to NEAR, please see the [NEAR docs](https://docs.near.org/develop/contracts/introduction) for instructions using various tools. \ No newline at end of file diff --git a/docs/tutorials/chains/Optimism.md b/docs/tutorials/chains/Optimism.md new file mode 100644 index 0000000000..f1d742b279 --- /dev/null +++ b/docs/tutorials/chains/Optimism.md @@ -0,0 +1,111 @@ +--- +layout: i18n_page +title: pages.optimism +parent: pages.chains +grand_parent: pages.tutorials +nav_order: 5 +--- + + +# {%t pages.optimism %} +{: .no_toc } + +## Table of contents +{: .no_toc .text-delta } + +1. TOC +{:toc} + +--- + +Starting with FireFly v1.1, it's easy to connect to public Ethereum chains. This guide will walk you through the steps to create a local FireFly development environment and connect it to the Optimism Goerli testnet. + +## Previous steps: Install the FireFly CLI +If you haven't set up the FireFly CLI already, please go back to the Getting Started guide and read the section on how to [Install the FireFly CLI](../../gettingstarted/firefly_cli.md). + +[← ① Install the FireFly CLI](../../gettingstarted/firefly_cli.md){: .btn .btn-purple .mb-5} + +## Create an `evmconnect.yml` config file +In order to connect to the Optimism testnet, you will need to set a few configuration options for the evmconnect blockchain connector. Create a text file called `evmconnect.yml` with the following contents: + +```yml +confirmations: + required: 4 +policyengine.simple: + fixedGasPrice: null + gasOracle: + mode: connector +``` + +For this tutorial, we will assume this file is saved at `~/Desktop/evmconnect.yml`. If your path is different, you will need to adjust the path in the next command below. + +## Creating a new stack +To create a local FireFly development stack and connect it to the Optimism testnet, we will use command line flags to customize the following settings: + + - Create a new stack named `optimism` with `1` member + - Disable `multiparty` mode. We are going to be using this FireFly node as a Web3 gateway, and we don't need to communicate with a consortium here + - Connect to an ethereum network + - Use the `evmconnect` blockchain connector + - Use an remote RPC node. This will create a signer locally, so that our signing key never leaves the development machine. + - Set the remote RPC node URL to `https://goerli.optimism.io` + - Set the chain ID to `420` (the correct ID for the Optimism testnet) + - Merge the custom config created above with the generated `evmconnect` config file + +To do this, run the following command: +``` +ff init optimism 1 \ + --multiparty=false \ + -b ethereum \ + -c evmconnect \ + -n remote-rpc \ + --remote-node-url https://goerli.optimism.io \ + --chain-id 420 \ + --connector-config ~/Desktop/evmconnect.yml +``` + +## Start the stack +Now you should be able to start your stack by running: + +``` +ff start optimism +``` + +After some time it should print out the following: + +``` +Web UI for member '0': http://127.0.0.1:5000/ui +Sandbox UI for member '0': http://127.0.0.1:5109 + + +To see logs for your stack run: + +ff logs optimism +``` + +## Get some Optimism +At this point you should have a working FireFly stack, talking to a public chain. However, you won't be able to run any transactions just yet, because you don't have any way to pay for gas. A testnet faucet can give us some OP, the native token for Optimism. + +First, you will need to know what signing address your FireFly node is using. To check that, you can run: + +``` +ff accounts list optimism +[ + { + "address": "0x235461d246ab95d367925b4e91bd2755a921fdd8", + "privateKey": "..." + } +] +``` + +Copy the address listed in the output from this command. Go to [https://optimismfaucet.xyz/](https://optimismfaucet.xyz/). You will need to login to your Github account and paste the address in the form. + +![Optimism Faucet](images/optimism_faucet.png) + +### Confirm the transaction on Blockcscout +You should be able to go lookup your account on [Blockscout for Optimism testnet https://blockscout.com/optimism/goerli](https://blockscout.com/optimism/goerli) and see that you now have a balance of 100 OP. Simply paste in your account address to search for it. + + +![Blockscout Scan](images/optimism_scan.png) + +## Use the public testnet +Now that you have everything set up, you can follow one of the other FireFly guides such as [Using Tokens](../tokens/index.md) or [Custom Smart Contracts](../custom_contracts/ethereum.md). For detailed instructions on deploying a custom smart contract to Optimism, please see the [Optimism docs](https://community.optimism.io/docs/developers/build/system-contracts/#getting-contract-artifacts-interfaces-and-abis) for instructions using various tools. \ No newline at end of file diff --git a/docs/tutorials/chains/avalanche.md b/docs/tutorials/chains/avalanche.md new file mode 100644 index 0000000000..6c7f7daa42 --- /dev/null +++ b/docs/tutorials/chains/avalanche.md @@ -0,0 +1,111 @@ +--- +layout: i18n_page +title: pages.avalanche +parent: pages.chains +grand_parent: pages.tutorials +nav_order: 3 +--- + + +# {%t pages.avalanche %} +{: .no_toc } + +## Table of contents +{: .no_toc .text-delta } + +1. TOC +{:toc} + +--- + +Starting with FireFly v1.1, it's easy to connect to public Ethereum chains. This guide will walk you through the steps to create a local FireFly development environment and connect it to the Avalanche C-Chain Fuji testnet. + +## Previous steps: Install the FireFly CLI +If you haven't set up the FireFly CLI already, please go back to the Getting Started guide and read the section on how to [Install the FireFly CLI](../../gettingstarted/firefly_cli.md). + +[← ① Install the FireFly CLI](../../gettingstarted/firefly_cli.md){: .btn .btn-purple .mb-5} + +## Create an `evmconnect.yml` config file +In order to connect to the Avalanche testnet, you will need to set a few configuration options for the evmconnect blockchain connector. Create a text file called `evmconnect.yml` with the following contents: + +```yml +confirmations: + required: 4 +policyengine.simple: + fixedGasPrice: null + gasOracle: + mode: connector +``` + +For this tutorial, we will assume this file is saved at `~/Desktop/evmconnect.yml`. If your path is different, you will need to adjust the path in the next command below. + +## Creating a new stack +To create a local FireFly development stack and connect it to the Avalanche Fuji testnet, we will use command line flags to customize the following settings: + + - Create a new stack named `avalanche` with `1` member + - Disable `multiparty` mode. We are going to be using this FireFly node as a Web3 gateway, and we don't need to communicate with a consortium here + - Connect to an ethereum network + - Use the `evmconnect` blockchain connector + - Use an remote RPC node. This will create a signer locally, so that our signing key never leaves the development machine. + - Set the remote RPC node URL to `https://api.avax-test.network/ext/bc/C/rpc` (for a full list of testnet RPC node urls visit https://docs.bscscan.com/misc-tools-and-utilities/public-rpc-nodes) + - Set the chain ID to `43113` (the correct ID for the Avalanche Fuji testnet) + - Merge the custom config created above with the generated `evmconnect` config file + +To do this, run the following command: +``` +ff init avalanche 1 \ + --multiparty=false \ + -b ethereum \ + -c evmconnect \ + -n remote-rpc \ + --remote-node-url https://api.avax-test.network/ext/bc/C/rpc \ + --chain-id 43113 \ + --connector-config ~/Desktop/evmconnect.yml +``` + +## Start the stack +Now you should be able to start your stack by running: + +``` +ff start avalanche +``` + +After some time it should print out the following: + +``` +Web UI for member '0': http://127.0.0.1:5000/ui +Sandbox UI for member '0': http://127.0.0.1:5109 + + +To see logs for your stack run: + +ff logs avalanche +``` + +## Get some AVAX +At this point you should have a working FireFly stack, talking to a public chain. However, you won't be able to run any transactions just yet, because you don't have any way to pay for gas. A testnet faucet can give us some AVAX, the native token for Avalanche. + +First, you will need to know what signing address your FireFly node is using. To check that, you can run: + +``` +ff accounts list avalanche +[ + { + "address": "0x6688e14f719766cc2a5856ccef63b069703d86f7", + "privateKey": "..." + } +] +``` + +Copy the address listed in the output from this command. Go to [https://faucet.avax.network/](https://faucet.avax.network/) and paste the address in the form. Make sure that the network you select is Fuji (C-Chain). Click the **Request 2 AVAX** button. + +Avalanche Faucet + +### Confirm the transaction on Snowtrace +You should be able to go lookup your account on [Snowtrace for the Fuji testnet](https://testnet.snowtrace.io/) and see that you now have a balance of 2 AVAX. Simply paste in your account address or transaction ID to search for it. + + +![Snowtrace Scan](images/avalanche_snowtrace_scan.png) + +## Use the public testnet +Now that you have everything set up, you can follow one of the other FireFly guides such as [Using Tokens](../tokens/index.md) or [Custom Smart Contracts](../custom_contracts/ethereum.md). For detailed instructions on deploying a custom smart contract to Avalanche, please see the [Avalanche docs](https://docs.avax.network/dapps/smart-contracts/deploy-a-smart-contract-on-avalanche-using-remix-and-metamask) for instructions using various tools. \ No newline at end of file diff --git a/docs/tutorials/chains/binance_smart_chain.md b/docs/tutorials/chains/binance_smart_chain.md new file mode 100644 index 0000000000..22a25192cb --- /dev/null +++ b/docs/tutorials/chains/binance_smart_chain.md @@ -0,0 +1,111 @@ +--- +layout: i18n_page +title: pages.binance_smart_chain +parent: pages.chains +grand_parent: pages.tutorials +nav_order: 2 +--- + + +# {%t pages.binance_smart_chain %} +{: .no_toc } + +## Table of contents +{: .no_toc .text-delta } + +1. TOC +{:toc} + +--- + +Starting with FireFly v1.1, it's easy to connect to public Ethereum chains. This guide will walk you through the steps to create a local FireFly development environment and connect it to the public Binance Smart Chain testnet. + +## Previous steps: Install the FireFly CLI +If you haven't set up the FireFly CLI already, please go back to the Getting Started guide and read the section on how to [Install the FireFly CLI](../../gettingstarted/firefly_cli.md). + +[← ① Install the FireFly CLI](../../gettingstarted/firefly_cli.md){: .btn .btn-purple .mb-5} + +## Create an `evmconnect.yml` config file +In order to connect to the Binance Smart Chain testnet, you will need to set a few configuration options for the evmconnect blockchain connector. Create a text file called `evmconnect.yml` with the following contents: + +```yml +confirmations: + required: 4 +policyengine.simple: + fixedGasPrice: null + gasOracle: + mode: connector +``` + +For this tutorial, we will assume this file is saved at `~/Desktop/evmconnect.yml`. If your path is different, you will need to adjust the path in the next command below. + +## Creating a new stack +To create a local FireFly development stack and connect it to the Binance Smart Chain testnet, we will use command line flags to customize the following settings: + + - Create a new stack named `bsc` with `1` member + - Disable `multiparty` mode. We are going to be using this FireFly node as a Web3 gateway, and we don't need to communicate with a consortium here + - Connect to an ethereum network + - Use the `evmconnect` blockchain connector + - Use an remote RPC node. This will create a signer locally, so that our signing key never leaves the development machine. + - Set the remote RPC node URL to `https://data-seed-prebsc-1-s1.binance.org:8545` (for a full list of testnet RPC node urls visit [https://docs.bscscan.com/misc-tools-and-utilities/public-rpc-nodes](https://docs.bscscan.com/misc-tools-and-utilities/public-rpc-nodes)) + - Set the chain ID to `97` (the correct ID for the Binance Smart Chain testnet) + - Merge the custom config created above with the generated `evmconnect` config file + +To do this, run the following command: +``` +ff init bsc 1 \ + --multiparty=false \ + -b ethereum \ + -c evmconnect \ + -n remote-rpc \ + --remote-node-url https://data-seed-prebsc-1-s1.binance.org:8545 \ + --chain-id 97 \ + --connector-config ~/Desktop/evmconnect.yml +``` + +## Start the stack +Now you should be able to start your stack by running: + +``` +ff start bsc +``` + +After some time it should print out the following: + +``` +Web UI for member '0': http://127.0.0.1:5000/ui +Sandbox UI for member '0': http://127.0.0.1:5109 + + +To see logs for your stack run: + +ff logs bsc +``` + +## Get some BNB +At this point you should have a working FireFly stack, talking to a public chain. However, you won't be able to run any transactions just yet, because you don't have any way to pay for gas. A testnet faucet can give us some BNB, the native token for Binance Smart Chain. + +First, you will need to know what signing address your FireFly node is using. To check that, you can run: + +``` +ff accounts list bsc +[ + { + "address": "0x235461d246ab95d367925b4e91bd2755a921fdd8", + "privateKey": "..." + } +] +``` + +Copy the address listed in the output from this command. Go to [https://testnet.binance.org/faucet-smart](https://testnet.binance.org/faucet-smart) and paste the address in the form. Go through the CAPTCH form and click the **Give me BNB** button. + +![BSC Faucet](images/bsc_faucet.png) + +### Confirm the transaction on Bscscan +You should be able to go lookup your account on [Bscscan for the testnet https://testnet.bscscan.com/](https://testnet.bscscan.com/) and see that you now have a balance of 0.5 BNB. Simply paste in your account address to search for it. + + +![BSC Scan](images/bsc_scan.png) + +## Use the public testnet +Now that you have everything set up, you can follow one of the other FireFly guides such as [Using Tokens](../tokens/index.md) or [Custom Smart Contracts](../custom_contracts/ethereum.md). For detailed instructions on deploying a custom smart contract to Binance Smart Chain, please see the [Binance docs](https://docs.bnbchain.org/docs/chainide) for instructions using various tools. \ No newline at end of file diff --git a/docs/tutorials/fabric_remote.md b/docs/tutorials/chains/fabric_remote.md similarity index 96% rename from docs/tutorials/fabric_remote.md rename to docs/tutorials/chains/fabric_remote.md index 5cc89b9c0a..f54fe08439 100644 --- a/docs/tutorials/fabric_remote.md +++ b/docs/tutorials/chains/fabric_remote.md @@ -1,8 +1,9 @@ --- -layout: default -title: Work with remote fabric network -parent: pages.tutorials -nav_order: +layout: i18n_page +title: pages.remote_fabric_network +parent: pages.chains +grand_parent: pages.tutorials +nav_order: 7 --- # Work with remote Hyperledger Fabric Network @@ -248,8 +249,8 @@ ff logs my-remote-fabric ## Integrate your FireFly stack with your Fabric chaincode -Once your stack is up and running, you can define and broadcast FireFly Interface Document for your remote fabric chaincode. You can refer to [Broadcast the Contract Interface(Fabric)](./custom_contracts/fabric.html#broadcast-the-contract-interface) guide for this. +Once your stack is up and running, you can define and broadcast FireFly Interface Document for your remote fabric chaincode. You can refer to [Broadcast the Contract Interface(Fabric)](../custom_contracts/fabric.html#broadcast-the-contract-interface) guide for this. -You can also now create an HTTP API for your fabric chaincode which will help you easily query/invoke all your chaincode methods with your organizational context that you set up in fabconnect. You can refer to [Create an HTTP API for the contract(Fabric)](./custom_contracts/fabric.html#create-an-http-api-for-the-contract) guide for this. +You can also now create an HTTP API for your fabric chaincode which will help you easily query/invoke all your chaincode methods with your organizational context that you set up in fabconnect. You can refer to [Create an HTTP API for the contract(Fabric)](../custom_contracts/fabric.html#create-an-http-api-for-the-contract) guide for this. -To view the OpenAPI spec for your contract, or to submit transactions, query for states and listen for events, you can further refer to [Work with Hyperledger Fabric chaincodes](./custom_contracts/fabric.html#work-with-hyperledger-fabric-chaincodes) guide. +To view the OpenAPI spec for your contract, or to submit transactions, query for states and listen for events, you can further refer to [Work with Hyperledger Fabric chaincodes](../custom_contracts/fabric.html#work-with-hyperledger-fabric-chaincodes) guide. diff --git a/docs/tutorials/chains/images/arbitrum_faucet.png b/docs/tutorials/chains/images/arbitrum_faucet.png new file mode 100644 index 0000000000..a36580943e Binary files /dev/null and b/docs/tutorials/chains/images/arbitrum_faucet.png differ diff --git a/docs/tutorials/chains/images/arbitrum_scan.png b/docs/tutorials/chains/images/arbitrum_scan.png new file mode 100644 index 0000000000..0d574db0f0 Binary files /dev/null and b/docs/tutorials/chains/images/arbitrum_scan.png differ diff --git a/docs/tutorials/chains/images/avalanche_faucet.png b/docs/tutorials/chains/images/avalanche_faucet.png new file mode 100644 index 0000000000..39ec60062e Binary files /dev/null and b/docs/tutorials/chains/images/avalanche_faucet.png differ diff --git a/docs/tutorials/chains/images/avalanche_snowtrace_scan.png b/docs/tutorials/chains/images/avalanche_snowtrace_scan.png new file mode 100644 index 0000000000..1839a86a51 Binary files /dev/null and b/docs/tutorials/chains/images/avalanche_snowtrace_scan.png differ diff --git a/docs/tutorials/chains/images/bsc_faucet.png b/docs/tutorials/chains/images/bsc_faucet.png new file mode 100644 index 0000000000..57b577483a Binary files /dev/null and b/docs/tutorials/chains/images/bsc_faucet.png differ diff --git a/docs/tutorials/chains/images/bsc_scan.png b/docs/tutorials/chains/images/bsc_scan.png new file mode 100644 index 0000000000..608fa83e4d Binary files /dev/null and b/docs/tutorials/chains/images/bsc_scan.png differ diff --git a/docs/tutorials/chains/images/near_account.png b/docs/tutorials/chains/images/near_account.png new file mode 100644 index 0000000000..fa3ee55f77 Binary files /dev/null and b/docs/tutorials/chains/images/near_account.png differ diff --git a/docs/tutorials/chains/images/near_account_lookup.png b/docs/tutorials/chains/images/near_account_lookup.png new file mode 100644 index 0000000000..eb2a41cd0d Binary files /dev/null and b/docs/tutorials/chains/images/near_account_lookup.png differ diff --git a/docs/tutorials/chains/images/near_account_name.png b/docs/tutorials/chains/images/near_account_name.png new file mode 100644 index 0000000000..f31dfc7193 Binary files /dev/null and b/docs/tutorials/chains/images/near_account_name.png differ diff --git a/docs/tutorials/chains/images/near_faucet.png b/docs/tutorials/chains/images/near_faucet.png new file mode 100644 index 0000000000..44bb9136bb Binary files /dev/null and b/docs/tutorials/chains/images/near_faucet.png differ diff --git a/docs/tutorials/chains/images/near_fund_account.png b/docs/tutorials/chains/images/near_fund_account.png new file mode 100644 index 0000000000..cfc1b1e424 Binary files /dev/null and b/docs/tutorials/chains/images/near_fund_account.png differ diff --git a/docs/tutorials/chains/images/near_navigate_to_wallet.png b/docs/tutorials/chains/images/near_navigate_to_wallet.png new file mode 100644 index 0000000000..1d5b9ff4d6 Binary files /dev/null and b/docs/tutorials/chains/images/near_navigate_to_wallet.png differ diff --git a/docs/tutorials/chains/images/near_scan.png b/docs/tutorials/chains/images/near_scan.png new file mode 100644 index 0000000000..a93b05598c Binary files /dev/null and b/docs/tutorials/chains/images/near_scan.png differ diff --git a/docs/tutorials/chains/images/near_wallet_send_funds.png b/docs/tutorials/chains/images/near_wallet_send_funds.png new file mode 100644 index 0000000000..b705e1dd94 Binary files /dev/null and b/docs/tutorials/chains/images/near_wallet_send_funds.png differ diff --git a/docs/tutorials/chains/images/optimism_faucet.png b/docs/tutorials/chains/images/optimism_faucet.png new file mode 100644 index 0000000000..1339d01be7 Binary files /dev/null and b/docs/tutorials/chains/images/optimism_faucet.png differ diff --git a/docs/tutorials/chains/images/optimism_scan.png b/docs/tutorials/chains/images/optimism_scan.png new file mode 100644 index 0000000000..aeedfdb355 Binary files /dev/null and b/docs/tutorials/chains/images/optimism_scan.png differ diff --git a/docs/tutorials/chains/images/polygon_faucet.png b/docs/tutorials/chains/images/polygon_faucet.png new file mode 100644 index 0000000000..793557ea25 Binary files /dev/null and b/docs/tutorials/chains/images/polygon_faucet.png differ diff --git a/docs/tutorials/chains/images/polygonscan_matic.png b/docs/tutorials/chains/images/polygonscan_matic.png new file mode 100644 index 0000000000..9f2515e466 Binary files /dev/null and b/docs/tutorials/chains/images/polygonscan_matic.png differ diff --git a/docs/tutorials/chains/index.md b/docs/tutorials/chains/index.md new file mode 100644 index 0000000000..c7c86c16ef --- /dev/null +++ b/docs/tutorials/chains/index.md @@ -0,0 +1,11 @@ +--- +layout: i18n_page +title: pages.chains +parent: pages.tutorials +nav_order: 8 +has_children: true +--- + +# {% t pages.chains %} + +If you want to connect a local development environment, created with the FireFly CLI to another chain, there are several tutorials below to help you do that. These other chains could also be on the same machine as FireFly, or they could be somewhere on the public internet, depending on the tutorial. \ No newline at end of file diff --git a/docs/tutorials/chains/polygon_testnet.md b/docs/tutorials/chains/polygon_testnet.md new file mode 100644 index 0000000000..821f5f178e --- /dev/null +++ b/docs/tutorials/chains/polygon_testnet.md @@ -0,0 +1,112 @@ +--- +layout: i18n_page +title: pages.polygon_testnet +parent: pages.chains +grand_parent: pages.tutorials +nav_order: 1 +--- + + +# {%t pages.polygon_testnet %} +{: .no_toc } + +## Table of contents +{: .no_toc .text-delta } + +1. TOC +{:toc} + +--- + +Starting with FireFly v1.1, it's easy to connect to public Ethereum chains. This guide will walk you through the steps to create a local FireFly development environment and connect it to the public Polygon Mumbai testnet. + +## Previous steps: Install the FireFly CLI +If you haven't set up the FireFly CLI already, please go back to the Getting Started guide and read the section on how to [Install the FireFly CLI](../../gettingstarted/firefly_cli.md). + +[← ① Install the FireFly CLI](../../gettingstarted/firefly_cli.md){: .btn .btn-purple .mb-5} + +## Create an `evmconnect.yml` config file +In order to connect to the Polygon testnet, you will need to set a few configuration options for the evmconnect blockchain connector. Create a text file called `evmconnect.yml` with the following contents: + +```yml +confirmations: + required: 4 +policyengine.simple: + fixedGasPrice: null + gasOracle: + mode: connector +``` + +For this tutorial, we will assume this file is saved at `~/Desktop/evmconnect.yml`. If your path is different, you will need to adjust the path in the next command below. + +## Creating a new stack +To create a local FireFly development stack and connect it to the Polygon Mumbai testnet, we will use command line flags to customize the following settings: + + - Create a new stack named `polygon` with `1` member + - Disable `multiparty` mode. We are going to be using this FireFly node as a Web3 gateway, and we don't need to communicate with a consortium here + - Connect to an ethereum network + - Use the `evmconnect` blockchain connector + - Use an remote RPC node. This will create a signer locally, so that our signing key never leaves the development machine. + - Set the remote RPC node URL to `https://rpc-mumbai.maticvigil.com` + - Set the chain ID to `80001` (the correct ID for the Polygon Mumbai testnet) + - Merge the custom config created above with the generated `evmconnect` config file + +To do this, run the following command: +``` +ff init polygon 1 \ + --multiparty=false \ + -b ethereum \ + -c evmconnect \ + -n remote-rpc \ + --remote-node-url https://rpc-mumbai.maticvigil.com \ + --chain-id 80001 \ + --connector-config ~/Desktop/evmconnect.yml +``` + +## Start the stack +Now you should be able to start your stack by running: + +``` +ff start polygon +``` + +After some time it should print out the following: + +``` +Web UI for member '0': http://127.0.0.1:5000/ui +Sandbox UI for member '0': http://127.0.0.1:5109 + + +To see logs for your stack run: + +ff logs polygon +``` + +## Get some MATIC +At this point you should have a working FireFly stack, talking to a public chain. However, you won't be able to run any transactions just yet, because you don't have any way to pay for gas. A testnet faucet can give us some MATIC, the native token for Polygon. + +First, you will need to know what signing address your FireFly node is using. To check that, you can run: + +``` +ff accounts list polygon +[ + { + "address": "0x02d42c32a97c894486afbc7b717edff50c70b292", + "privateKey": "..." + } +] +``` + +Copy the address listed in the output from this command. Go to [https://faucet.polygon.technology/](https://faucet.polygon.technology/) and paste the address in the form. Click the **Submit** button, and then **Confirm**. + +![Polygon Faucet](images/polygon_faucet.png) + +### Confirm the transaction on Polygonscan +You should be able to go lookup your account on [Polygonscan for the Mumbai testnet https://mumbai.polygonscan.com/](https://mumbai.polygonscan.com/) and see that you now have a balance of 0.2 MATIC. Simply paste in your account address to search for it. + +You can also click on the **Internal Txns** tab from you account page to see the actual transfer of the MATIC from the faucet. + +![Polygonscan](images/polygonscan_matic.png) + +## Use the public testnet +Now that you have everything set up, you can follow one of the other FireFly guides such as [Using Tokens](../tokens/index.md) or [Custom Smart Contracts](../custom_contracts/ethereum.md). For detailed instructions on deploying a custom smart contract to Polygon, please see the [Polygon docs](https://wiki.polygon.technology/docs/category/deploying-contracts) for instructions using various tools. \ No newline at end of file diff --git a/docs/tutorials/custom_contracts/index.md b/docs/tutorials/custom_contracts/index.md index db57a5f9e4..d96fe98f29 100644 --- a/docs/tutorials/custom_contracts/index.md +++ b/docs/tutorials/custom_contracts/index.md @@ -2,7 +2,7 @@ layout: i18n_page title: pages.custom_smart_contracts parent: pages.tutorials -nav_order: 10 +nav_order: 7 has_children: true --- diff --git a/docs/tutorials/define_datatype.md b/docs/tutorials/define_datatype.md index 4f429f7016..4ea53d1031 100644 --- a/docs/tutorials/define_datatype.md +++ b/docs/tutorials/define_datatype.md @@ -2,7 +2,7 @@ layout: default title: Define a datatype parent: pages.tutorials -nav_order: 7 +nav_order: 3 --- # Define a datatype @@ -31,7 +31,7 @@ of datatypes, as is used to broadcast the data itself. ## Additional info -- Key Concepts: [Broadcast / shared data](../overview//broadcast.md) +- Key Concepts: [Broadcast / shared data](../overview/firefly_modes/multiparty/broadcast.md) - Swagger: POST /api/v1/namespaces/{ns}/datatypes ### Example 1: Broadcast new datatype @@ -199,7 +199,7 @@ In the sandbox, enter the datatype's name, version, and JSON Schema as seen in t 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. +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. ![Message Broadcast](../images/message_broadcast_sample_result.png) diff --git a/docs/tutorials/deploying_contracts.md b/docs/tutorials/deploying_contracts.md deleted file mode 100644 index e69de29bb2..0000000000 diff --git a/docs/tutorials/events.md b/docs/tutorials/events.md index c87293eb90..7018281448 100644 --- a/docs/tutorials/events.md +++ b/docs/tutorials/events.md @@ -2,7 +2,7 @@ layout: default title: Listen for events parent: pages.tutorials -nav_order: 6 +nav_order: 5 --- # Listen for events @@ -36,7 +36,7 @@ We focus on WebSockets in this getting started guide. ## Additional info -- Key Concepts: [Multi-party process flow](../overview//multiparty_process_flow.md) +- Key Concepts: [Multi-party process flow](../overview/firefly_modes/multiparty/multiparty_flow.md) - Reference: _coming soon_ ## WebSockets Example 1: Ephemeral subscription with auto-commit diff --git a/docs/tutorials/private_send.md b/docs/tutorials/private_send.md index 2e69fc2497..d4d9f34a29 100644 --- a/docs/tutorials/private_send.md +++ b/docs/tutorials/private_send.md @@ -2,7 +2,7 @@ layout: default title: Privately send data parent: pages.tutorials -nav_order: 4 +nav_order: 2 --- # Privately send data @@ -48,7 +48,7 @@ nav_order: 4 ## Additional info -- Key Concepts: [Private data exchange](../overview/data_exchange.md) +- Key Concepts: [Private data exchange](../overview/firefly_modes/multiparty/data_exchange.md) - Swagger: POST /api/v1/namespaces/{ns}/messages/private ## Example 1: Pinned private send of in-line string data @@ -283,10 +283,10 @@ Make sure to expand the "Send a Private Message" section. Enter your message int Notice how the `data` field in the center panel updates in real time as you update the message you wish to send. -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. +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. ![Private Message 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. Compare the "Recent Network Changes" widget With private messages, your +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. Compare the "Recent Network Changes" widget With private messages, your ![Successful Transaction](../images/firefly_first_successful_transaction.png) \ No newline at end of file diff --git a/docs/tutorials/tokens/index.md b/docs/tutorials/tokens/index.md index 9fa10bd5e4..6133b62be1 100644 --- a/docs/tutorials/tokens/index.md +++ b/docs/tutorials/tokens/index.md @@ -2,7 +2,7 @@ layout: default title: Use tokens parent: pages.tutorials -nav_order: 7 +nav_order: 6 has_children: true ---