Interacting With Your Firefly System

Your FireFly environment now contains at least one Ethereum or Fabric blockchain node (running the configured node client and consensus algorithm defined during environment creation), a FireFly Supernode for interaction with the FireFly API surface (the FireFly Supernode also exposes an explorer and prebuilt Sandbox) and at least one IPFS node for storage of public data and a system monitor for the indexing of blockchain transactions.

You have the option to use the environment just like any other Ethereum orchestration on Kaleido:

Your blockchain nodes are available for web3-based calls against their JSON/RPC endpoints and you also have the same access to REST APIs for any smart contracts uploaded to the system.

Additionally, your environment contains the same access to the rich array of pluggable services and components available on Kaleido (storage utilities, key management, token templates, cloud integrations, etc.)

If you're unfamiliar with the basic usage of an Ethereum-based Kaleido environment, it's highly recommended to go through the Ethereum Quick Start Guide to familiarize yourself with the core tenets of the platform (e.g. smart contract management, REST APIs, etc.).

That said, you're probably here because you want to try out FireFly. For interaction with the FireFly system at large, you are provided with a comprehensive set of REST APIs (accessible through an interactive Swagger interface or via external REST API calls), a prebuilt interactive Sandbox for immediate testing and exploration, and a FireFly explorer for enhanced visualization of transactions and messages flowing through the system.

Anatomy of your FireFly environment

• Blockchain Node(s) - available for direct JSON/RPC or REST API calls, which also execute and pin transactions flowing through the FireFly APIs.
• IPFS Node(s) - available for direct upload of arbitrary data, and also responsible for storing various hash representations of "broadcasted" data flowing through the FireFly APIs.
• FireFly Node(s) - the core FireFly runtimes, and the wrapper for the embedded Swagger, FireFly explorer and FireFly Sandbox components of each.
  • FireFly APIs - served in an interactive Swagger interface and also accessible programmatically via a unique request URL for each FireFly node.
  • FireFly Explorer - unique visualization interface for each FireFly node. Displays high level and granular details about data and messages flowing through the FireFly system.
  • FireFly Sandbox - a prebuilt interactive application to explore the core functionality of FireFly. The Sandbox includes public/private messaging, token interactions and smart contract interactions. It also contains a preconfigured websocket event stream for realtime notification of system state changes both on and off-chain. The Sandbox is built using a React frontend and a typescript SDK backend.
• One System Monitor Node - responsible for the indexing of blockchain transactions that are visible in the "Data Explorer" interface within your environment.
• Pluggable Components - access to Kaleido's rich library of pluggable services (e.g. key management, storage, wallets, cloud integrations, etc.)

Elements of a FireFly Node

• Dashboard - The landing page for your FireFly node. Provides an overview of metadata and API/UI endpoints, along with the associated runtimes of the FireFly stack - blockchain node, IPFS node, FireFly Explorer and Swagger Interface.
• Logs - The logs for you FireFly runtime. Toggle between firefly-os ( tracking state changes of the blockchain environment) and firefly-dx (tracking data exchange in the environment).
• Settings - Management panel for your FireFly node. Available actions are:
  • Change runtime name
  • Restart runtime
  • Reset runtime
  • Delete runtime

FireFly APIs

Your FireFly node encapsulates a large set of APIs for calls such as /broadcast, /send, /request, /subscribe, and more. These are exercisable directly within the built-in Swagger interface or programmatically via the FireFly node's request URL. To learn more about the core APIs and their associated JSON schemas, please refer to the open source FireFly developer documentation. These APIs are the interfaces for sending, requesting and querying data within your multi-party FireFly system.

The Getting Started section of the open source documentation contains various samples for broadcasting, sending private messages, listening for events and other layers of functionality in the FireFly system.

Accessing the Swagger Interface

• Navigate to your FireFly environment within the Kaleido console by clicking the top-level "Dashboard" tab in the left hand navigation.
• From your environmental dashboard, click on one of your FireFly nodes to access the available utilities.

• Click the Open Web UI button beneath the Swagger image. This will open a new tab for your node's interactive Swagger interface.

• Exercise the FireFly APIs by expanding the REST method next to your desired call.
• Click the Try it out button to make the route callable.
• Use the server request URL at the top of the screen to call these APIs programmatically.
• Download the full specification by clicking the .yaml hyperlink above the server request URL

• Any programmatic calls to the FireFly request URL need to be accompanied with application credentials (passed over basic auth) bound to the same membership that owns the FireFly node.
• To generate app credentials for programmatic access, you will need to navigate to Security then App Creds where you can opt to create a New App Cred.

  Once created, you will be shown your App ID and Password in addition to a couple of other descriptive fields. Kaleido doesn't store the credential password, so it is important to make sure it is copied and stored external to the platform.

FireFly Explorer

The FireFly Explorer will allow you to visualize and inspect messages, data and blockchain transactions amongst the various nodes and members of your network. Each FireFly node has its own unique explorer instance that contains the public information flowing through the system, along with any private data/messages the node has received.

Accessing the FireFly Explorer

• Navigate to your FireFly environment within the Kaleido console by clicking the top-level Dashboard tab in the left hand navigation.
• From your dashboard, click the View FireFly Node button on one of your FireFly nodes to access the available utilities.

• Click the Open Web UI button beneath the Explorer image. This will open a new tab for your node's interactive FireFly Explorer interface.

Using the FireFly Explorer

• Use the dropdown in the top right of the explorer console to toggle views between the FireFly node-specific view and the FF system view. Available on all panels.
• Use the timeline dropdown to toggle between 24 hours, 7 days and 30 days. Available on all panels.
• Explorer may be toggled between light and dark mode through the button in the upper right of the screen.
• The eight tabs in the left navigation allow you to switch contexts across:
  • Dashboard - macro counters for members, messages, data and transactions. Also displays state of recent transactions and latest messages within the system.
  • Activity - View the timeline, events, transactions, and operations that have been submitted in the blockchain.
  • Blockchain - Dashboard to track operations, transactions, events, contracts, blockchain events, APIs, and contract listeners. Click the individual tabs of events, APIs, interfaces, and listeners for further details.
  • Off-Chain - View messages, data, blobs, and datatypes that are sent off-chain. Broadcast messages along with private messages may be viewed here.
  • Tokens - View information on token activity, pools, approvals, connectors, transfer types, and account balances. Minting, transferring, and burning tokens may all be tracked here.
  • Network - Visualization of organizations and nodes. Organization and node names and IDs may be seen here for all who are participating in the network. Information specific for the organization that is operating is denoted as "Your Org"
  • My Node - Track services that are running with the FireFly node as well as any subscriptions or WebSockets that are connected.
  • Docs - Additional information is available in the open source Hyperledger FireFly Documentation

FireFly SandBox

The FireFly Sandbox sits logically outside the Supernode, and it acts like an “end-user” application written to use FireFly’s API (specifically the Typescript SDK). In your setup, you have one Sandbox per member, each talking to their own FireFly API surface. 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.

Accessing the FireFly SandBox

• Navigate to your FireFly environment within the Kaleido console by clicking the top-level "Dashboard" tab in the left hand navigation.
• From your dashboard, click the View FireFly Node button to access the available utilities.

• Click the Open Web UI button beneath the Sandbox image. This will open a new tab for your node's interactive FireFly Sandbox interface.

• Sandbox should show "Connected" in the top right corner in order to listen to events in the backend.
• Sandbox may be toggled between light and dark mode through the button in the upper right of the screen.
• The Snadbox has three differet sections: Messages, Tokens, and Contracts.
  • Messages - Users have the option to send a broadcast message, send a private message, or define a datatype. Messages may include text, files, or datatype, and can be constructed as strings, JSON or form-data. Broadcast messages may be seen by all members in the environment, while private messages may only be seen by the sender and designated recipients.
  • Tokens - Tokens created from the Kaleido console via Smart Contract upload may be connected to the FireFly Sandbox. To create a token pool, enter the name, symbol, type, and contract address which may be found in the Kaleido console. The ability to mint, transfer, and burn tokens will be available once the token pool is successfully created. For more information please visit the Hyperledger FireFly Token Docs.
  • Contracts - There are four options which are to deploy a contract, define a contract interface, register a contract API, or register a contract listener. For more information please visit the Hyperledger FireFly Custom Smart Contract Docs

Troubleshooting

• FireFly nodes in an uninitialized state.
  • Make sure you have gone through the Initialize Firefly step.
  • If nodes do not transition to a Started state after initializing or resuming your environment, use the "Settings" tab on your node to perform a node reset.
• API unable to execute with supplied inputs.
  • Refer to the open source FireFly Developer Documentation for example payloads and additional details on the APIs, required parameters and JSON schemas.
• External API calls from REST client or application are returning 401.
  • Make sure you are supplying valid application credentials bound to the same Kaleido membership that owns the FireFly node. Note that application credentials are passed as username:password over basic auth.