Skip to content

Interacting with your FireFly System

Your FireFly environment contains two Ethereum blockchain nodes (running the configured node client and consensus algorithm defined during environment creation), two FireFly nodes for interaction with the FireFly APIs and user interface, two IPFS nodes for storage 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.).

You're probably here though 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), along with a FireFly explorer for enhanced visualization of transactions and messages flowing through the system.

Anatomy of your FireFly environment

  • Two blockchain nodes - available for direct JSON/RPC or REST API calls, which also execute and pin transactions flowing through the FireFly APIs.
  • Two IPFS nodes - available for direct upload of arbitrary data, and also responsible for storing various hash representations of "broadcasted" data flowing through the FireFly APIs.
  • Two FireFly nodes - the core FireFly runtimes, and the wrapper for the embedded Swagger and FireFly explorer 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.
  • 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.)

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 and firefly-dx.
  • 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.

FireFly API Access

  • On the left side of your FireFly node overview screen there is a modal for the FireFly Swagger API.
  • Click the Open Web UI button. This will open a new tab for your node's interactive Swagger interface.

FireFly Open Swagger

  • Exercise the FireFly APIs by expanding the root 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

FireFly Use Swagger

  • 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.

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 environmental dashboard, click on one of your FireFly nodes to access the available utilities.

FireFly API Access

  • On the left side of your FireFly node overview screen there is a modal for the FireFly Explorer.
  • Click the Open Web UI button. This will open a new tab for your node's interactive FireFly Explorer interface.

FireFly Open 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.
  • The four tabs in the left navigation allow you to switch contexts across:
  • Overview - macro counters for members, messages, data and transactions. Also displays state of recent transactions and latest messages within the system.
  • Messages - messages sent through the system; displays author identity, type, tag, transaction type, data hash and timestamp. Use the view switcher to alternate between list and timeline mode.
  • Data - data objects defined in the system; displays UUID for the data construct, validator type, data hash and timestamp.
  • Transactions - blockchain transactions; displays block number, tx hash, signing account, status and timestamp of block it was mined into. Use the view switcher to alternate between list and timeline mode.

FireFly Open Explorer

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.