From 13785324ddb56eb747b59b4ddb7ebfe602c76bf5 Mon Sep 17 00:00:00 2001
From: GitHub Actions <noreply@github.com>
Date: Tue, 17 Sep 2024 15:16:34 +0000
Subject: [PATCH] Deployed 35db03292 to head with MkDocs 1.6.1 and mike 2.1.3

---
 head/gettingstarted/firefly_cli/index.html | 60 +++++++++-------------
 head/search/search_index.json              |  2 +-
 2 files changed, 24 insertions(+), 38 deletions(-)

diff --git a/head/gettingstarted/firefly_cli/index.html b/head/gettingstarted/firefly_cli/index.html
index 7feb093a4..3fec4378f 100644
--- a/head/gettingstarted/firefly_cli/index.html
+++ b/head/gettingstarted/firefly_cli/index.html
@@ -928,27 +928,18 @@
       <ul class="md-nav__list">
         
           <li class="md-nav__item">
-  <a href="#download-the-package-for-your-os" class="md-nav__link">
+  <a href="#install-via-binary-package-download" class="md-nav__link">
     <span class="md-ellipsis">
-      Download the package for your OS
+      Install via Binary Package Download
     </span>
   </a>
   
 </li>
         
           <li class="md-nav__item">
-  <a href="#extract-the-binary-and-move-it-to-usrbinlocal" class="md-nav__link">
+  <a href="#install-via-homebrew-macos" class="md-nav__link">
     <span class="md-ellipsis">
-      Extract the binary and move it to /usr/bin/local
-    </span>
-  </a>
-  
-</li>
-        
-          <li class="md-nav__item">
-  <a href="#macosusers" class="md-nav__link">
-    <span class="md-ellipsis">
-      macOSUsers
+      Install via Homebrew (macOS)
     </span>
   </a>
   
@@ -3459,27 +3450,18 @@
       <ul class="md-nav__list">
         
           <li class="md-nav__item">
-  <a href="#download-the-package-for-your-os" class="md-nav__link">
+  <a href="#install-via-binary-package-download" class="md-nav__link">
     <span class="md-ellipsis">
-      Download the package for your OS
+      Install via Binary Package Download
     </span>
   </a>
   
 </li>
         
           <li class="md-nav__item">
-  <a href="#extract-the-binary-and-move-it-to-usrbinlocal" class="md-nav__link">
+  <a href="#install-via-homebrew-macos" class="md-nav__link">
     <span class="md-ellipsis">
-      Extract the binary and move it to /usr/bin/local
-    </span>
-  </a>
-  
-</li>
-        
-          <li class="md-nav__item">
-  <a href="#macosusers" class="md-nav__link">
-    <span class="md-ellipsis">
-      macOSUsers
+      Install via Homebrew (macOS)
     </span>
   </a>
   
@@ -3553,27 +3535,31 @@ <h3 id="windows-users">Windows Users<a class="headerlink" href="#windows-users"
 </blockquote>
 <h2 id="install-the-cli">Install the CLI<a class="headerlink" href="#install-the-cli" title="Permanent link">&para;</a></h2>
 <p>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.</p>
-<h3 id="download-the-package-for-your-os">Download the package for your OS<a class="headerlink" href="#download-the-package-for-your-os" title="Permanent link">&para;</a></h3>
-<p>Go to the <a href="https://github.com/hyperledger/firefly-cli/releases/latest">latest release page</a> and download the package for your OS and CPU architecture.</p>
-<h3 id="extract-the-binary-and-move-it-to-usrbinlocal">Extract the binary and move it to <code>/usr/bin/local</code><a class="headerlink" href="#extract-the-binary-and-move-it-to-usrbinlocal" title="Permanent link">&para;</a></h3>
-<p>Assuming you downloaded the package from GitHub into your <code>Downloads</code> directory, run the following command:</p>
+<h3 id="install-via-binary-package-download">Install via Binary Package Download<a class="headerlink" href="#install-via-binary-package-download" title="Permanent link">&para;</a></h3>
+<p>Download the package for your OS by navigating to the <a href="https://github.com/hyperledger/firefly-cli/releases/latest">latest release page</a> and downloading the appropriate package for your OS and architecture.</p>
+<h4 id="unpack-and-install-the-binary">Unpack and Install the Binary<a class="headerlink" href="#unpack-and-install-the-binary" title="Permanent link">&para;</a></h4>
+<p>Assuming you downloaded the package from GitHub into your <code>Downloads</code> directory, run the following command to extract the binary and move it to your system path:</p>
 <div class="highlight"><pre><span></span><code><a id="__codelineno-0-1" name="__codelineno-0-1" href="#__codelineno-0-1"></a>sudo tar -zxf ~/Downloads/firefly-cli_*.tar.gz -C /usr/local/bin ff &amp;&amp; rm ~/Downloads/firefly-cli_*.tar.gz
 </code></pre></div>
-<p>If you downloaded the package from GitHub into a different directory, you will need to change the <code>tar</code> command above to wherever the <code>firefly-cli_*.tar.gz</code> file is located.</p>
-<h3 id="macosusers">macOSUsers<a class="headerlink" href="#macosusers" title="Permanent link">&para;</a></h3>
+<p>If you downloaded the package into a different directory, adjust the command to point to the correct location of the <code>firefly-cli_*.tar.gz</code> file.</p>
+<h4 id="macosusers">macOSUsers<a class="headerlink" href="#macosusers" title="Permanent link">&para;</a></h4>
 <blockquote>
 <p><strong>NOTE</strong>: 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 <a href="https://github.com/hyperledger/firefly-cli/blob/main/docs/mac_help.md">allow the FireFly CLI in System Preferences</a>, before it will run.</p>
 </blockquote>
+<h3 id="install-via-homebrew-macos">Install via Homebrew (macOS)<a class="headerlink" href="#install-via-homebrew-macos" title="Permanent link">&para;</a></h3>
+<p>You can also install the FireFly CLI using Homebrew:</p>
+<div class="highlight"><pre><span></span><code><a id="__codelineno-1-1" name="__codelineno-1-1" href="#__codelineno-1-1"></a>brew install firefly
+</code></pre></div>
 <h3 id="alternative-installation-method-install-via-go">Alternative installation method: Install via Go<a class="headerlink" href="#alternative-installation-method-install-via-go" title="Permanent link">&para;</a></h3>
 <p>If you have a local Go development environment, and you have included <code>${GOPATH}/bin</code> in your path, you could also use Go to install the FireFly CLI by running:</p>
-<div class="highlight"><pre><span></span><code><a id="__codelineno-1-1" name="__codelineno-1-1" href="#__codelineno-1-1"></a>go<span class="w"> </span>install<span class="w"> </span>github.com/hyperledger/firefly-cli/ff@latest
+<div class="highlight"><pre><span></span><code><a id="__codelineno-2-1" name="__codelineno-2-1" href="#__codelineno-2-1"></a>go<span class="w"> </span>install<span class="w"> </span>github.com/hyperledger/firefly-cli/ff@latest
 </code></pre></div>
 <h2 id="verify-the-installation">Verify the installation<a class="headerlink" href="#verify-the-installation" title="Permanent link">&para;</a></h2>
 <p>After using either installation method above, you can verify that the CLI is successfully installed by running <code>ff version</code>. This should print the current version like this:</p>
-<div class="highlight"><pre><span></span><code><a id="__codelineno-2-1" name="__codelineno-2-1" href="#__codelineno-2-1"></a>{
-<a id="__codelineno-2-2" name="__codelineno-2-2" href="#__codelineno-2-2"></a>  &quot;Version&quot;: &quot;v0.0.47&quot;,
-<a id="__codelineno-2-3" name="__codelineno-2-3" href="#__codelineno-2-3"></a>  &quot;License&quot;: &quot;Apache-2.0&quot;
-<a id="__codelineno-2-4" name="__codelineno-2-4" href="#__codelineno-2-4"></a>}
+<div class="highlight"><pre><span></span><code><a id="__codelineno-3-1" name="__codelineno-3-1" href="#__codelineno-3-1"></a>{
+<a id="__codelineno-3-2" name="__codelineno-3-2" href="#__codelineno-3-2"></a>  &quot;Version&quot;: &quot;v0.0.47&quot;,
+<a id="__codelineno-3-3" name="__codelineno-3-3" href="#__codelineno-3-3"></a>  &quot;License&quot;: &quot;Apache-2.0&quot;
+<a id="__codelineno-3-4" name="__codelineno-3-4" href="#__codelineno-3-4"></a>}
 </code></pre></div>
 <h2 id="next-steps-start-your-environment">Next steps: Start your environment<a class="headerlink" href="#next-steps-start-your-environment" title="Permanent link">&para;</a></h2>
 <p>Now that you've got the FireFly CLI set up on your machine, the next step is to create and start a FireFly stack.</p>
diff --git a/head/search/search_index.json b/head/search/search_index.json
index d02b15b05..0dd4cbc05 100644
--- a/head/search/search_index.json
+++ b/head/search/search_index.json
@@ -1 +1 @@
-{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"]},"docs":[{"location":"","title":"Hyperledger FireFly","text":"<p>Hyperledger FireFly is an open source Supernode, a complete stack for enterprises to build and scale secure Web3 applications.</p> <p>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 that already exists, and the other set allows you to build new decentralized applications quickly with security and scalability.</p> <p>Head to the Understanding FireFly section for more details.</p>"},{"location":"SUMMARY/","title":"SUMMARY","text":"<ul> <li>Home</li> <li>Understanding FireFly<ul> <li>Introduction</li> <li>Usage Patterns</li> <li>Key Features<ul> <li>overview/key_components/*</li> </ul> </li> <li>Web3 Gateway Features</li> <li>Multiparty Features<ul> <li>overview/multiparty/*</li> </ul> </li> <li>Public and Permissioned</li> </ul> </li> <li>Getting Started<ul> <li>\u2460 Install the FireFly CLI</li> <li>\u2461 Start your environment</li> <li>\u2462 Use the Sandbox</li> </ul> </li> <li>Tutorials<ul> <li>tutorials/*</li> </ul> </li> <li>Reference<ul> <li>reference/*.md</li> <li>Microservices<ul> <li>reference/microservices/*.md</li> </ul> </li> <li>Types<ul> <li>reference/types/*.md</li> </ul> </li> </ul> </li> <li>Architecture<ul> <li>architecture/*</li> </ul> </li> <li>Contributors<ul> <li>contributors/*</li> </ul> </li> <li>API Spec</li> <li>FAQs</li> <li>Release Notes<ul> <li>releasenotes/*</li> </ul> </li> </ul>"},{"location":"architecture/blockchain_connector_framework/","title":"Blockchain Connector Toolkit","text":""},{"location":"architecture/blockchain_connector_framework/#blockchain-connector-framework","title":"Blockchain Connector Framework","text":"<p>Hyperledger FireFly has a multi-tier pluggable architecture for supporting blockchains of all shapes and sizes. This includes a remote API that allows a microservice connector to be built from scratch in any programming language.</p> <p>It also includes the Connector Toolkit, which is a pluggable SDK in Golang that provides a set of re-usable modules that can be used across blockchain implementations.</p> <p>This is the preferred way to build a new blockchain connector, if you are comfortable with coding in Golang and there are language bindings available for the raw RPC interface of your blockchain.</p>"},{"location":"architecture/blockchain_connector_framework/#connector-toolkit-architecture","title":"Connector Toolkit Architecture","text":"<p>The core component of the FireFly Connector Framework for Blockchains is a Go module called FireFly Transaction Manager (FFTM).</p> <p>FFTM is responsible for:</p> <ul> <li> <p>Submission of transactions to blockchains of all types</p> </li> <li> <p>Protocol connectivity decoupled with additional lightweight API connector</p> </li> <li> <p>Easy to add additional protocols that conform to normal patterns of TX submission / events</p> </li> <li> <p>Monitoring and updating blockchain operations</p> </li> <li> <p>Receipts</p> </li> <li> <p>Confirmations</p> </li> <li> <p>Extensible transaction handler with capabilities such as:</p> </li> <li> <p>Nonce management: idempotent submission of transactions, and assignment of nonces</p> </li> <li>Transaction management: pre-signing transactions, resubmission, customizable policy engine</li> <li>Gas management: Gas Gas station API integration</li> <li> <p>Transaction process history</p> </li> <li> <p>Event streaming</p> </li> <li>Protocol agnostic event polling/streaming support</li> <li>Reliable checkpoint restart</li> <li>At least once delivery API</li> </ul>"},{"location":"architecture/blockchain_connector_framework/#assumptions-requirements","title":"Assumptions / Requirements","text":"<p>The framework is currently constrained to blockchains that adhere to certain basic principals:</p> <ol> <li> <p>Has transactions</p> </li> <li> <p>That are signed</p> </li> <li> <p>That can optionally have gas semantics (limits and prices, expressed in a blockchain specific way)</p> </li> <li> <p>Has events (or \"logs\")</p> </li> <li> <p>That are emitted as a deterministic outcome of transactions</p> </li> <li> <p>Has blocks</p> </li> <li> <p>Containing zero or more transactions, with their associated events</p> </li> <li>With a sequential numeric order</li> <li>With a hash</li> <li> <p>With a parent hash</p> </li> <li> <p>Has finality for transactions &amp; events that can be expressed as a level of confidence over time</p> </li> <li> <p>Confirmations: A number of sequential blocks in the canonical chain that contain the transaction</p> </li> </ol>"},{"location":"architecture/blockchain_connector_framework/#nonce-management-in-the-simple-transaction-handler","title":"Nonce management in the simple transaction handler","text":"<p>The nonces for transactions is assigned as early as possible in the flow:</p> <ul> <li>Before the REST API for submission of the transaction occurs</li> <li>After the FFCAPI blockchain connector verifies the transaction can be encoded successfully to the chain</li> <li>With protection against multiple parallel API requests for the same signing address</li> <li>With stateful persistence meaning the connector knows about all nonces it previously allocated, to avoids duplicates</li> </ul> <p>This \"at source\" allocation of nonces provides the strictest assurance of order of transactions possible, because the order is locked in with the coordination of the business logic of the application submitting the transaction.</p> <p>As well as protecting against loss of transactions, this protects against duplication of transactions - even in crash recovery scenarios with a sufficiently reliable persistence layer.</p>"},{"location":"architecture/blockchain_connector_framework/#avoid-multiple-nonce-management-systems-against-the-same-signing-key","title":"Avoid multiple nonce management systems against the same signing key","text":"<p>FFTM is optimized for cases where all transactions for a given signing address flow through the same FireFly connector. If you have signing and nonce allocation happening elsewhere, not going through the FireFly blockchain connector, then it is possible that the same nonce will be allocated in two places.</p> <p>Be careful that the signing keys for transactions you stream through the Nonce Management of the FireFly blockchain connector are not used elsewhere.</p> <p>If you must have multiple systems performing nonce management against the same keys you use with FireFly nonce management, you can set the <code>transactions.nonceStateTimeout</code> to <code>0</code> (or a low threshold like <code>100ms</code>) to cause the nonce management to query the pending transaction pool of the node every time a nonce is allocated.</p> <p>This reduces the window for concurrent nonce allocation to be small (basically the same as if you had multiple simple web/mobile wallets used against the same key), but it does not eliminate it completely it.</p>"},{"location":"architecture/blockchain_connector_framework/#why-at-source-nonce-management-was-chosen-vs-at-target","title":"Why \"at source\" nonce management was chosen vs. \"at target\"","text":"<p>The \"at source\" approach to ordering used in FFTM could be compared with the \"at target\" allocation of nonces used in EthConnect).</p> <p>The \"at target\" approach optimizes for throughput and ability to send new transactions to the chain, with an at-least-once delivery assurance to the applications.</p> <p>An \"at target\" algorithm as used in EthConnect could resume transaction delivery automatically without operator intervention from almost all scenarios, including where nonces have been double allocated.</p> <p>However, \"at target\" comes with two compromises that mean FFTM chose the \"at source\" approach was chosen for FFTM:</p> <ul> <li> <p>Individual transactions might fail in certain scenarios, and subsequent transactions will still be streamed to the chain.   While desirable for automation and throughput, this reduces the ordering guarantee for high value transactions.</p> </li> <li> <p>In crash recovery scenarios the assurance is at-least-once delivery for \"at target\" ordering (rather than \"exactly once\"),   although the window can be made very small through various optimizations included in the EthConnect codebase.</p> </li> </ul>"},{"location":"architecture/blockchain_connector_framework/#transaction-handler","title":"Transaction Handler","text":"<p>The transaction Handler is a pluggable component that allows customized logic to be applied to the gas pricing, signing, submission and re-submission of transactions to the blockchain.</p> <p>The transaction Handler can store custom state in the state store of the FFTM code, which is also reported in status within the FireFly API/Explorer on the operation.</p> <p>A reference implementation is provided that:</p> <ul> <li>Submits transactions via the underlying FFCAPI</li> <li>Estimates gas price in one of three modes:</li> <li>Fixed: It is specified via configuration</li> <li>Connector: The FFCAPI is used to estimate the gas price (e.g. <code>eth_gasPrice</code> for EVM JSON/RPC)</li> <li>Gas Oracle: A REST API is called the the result mapped via a Go template</li> <li>Re-submits transactions after a configurable stale time</li> <li>Record detailed information about transaction sub-status and actions</li> <li>Emit customized metrics for transaction processing</li> </ul> <p>The reference implementation is available here</p>"},{"location":"architecture/blockchain_connector_framework/#event-streams","title":"Event Streams","text":"<p>One of the largest pieces of heavy lifting code in the FFTM codebase, is the event stream support. This provides a WebSocket (and Webhook) interface that FireFly Core and the Tokens Connectors connect to in order to receive ordered streams of events from the blockchain.</p> <p>The interface down to the blockchain layer is via go channels, and there are lifecycle interactions over the FFCAPI to the blockchain specific code to add and remove listeners for different types of blockchain events.</p> <p>Some high architectural principals that informed the code:</p> <ul> <li>Event Stream</li> <li>A delivery stream of events that have been confirmed</li> <li>Only events that have reached finality are delivered to an event stream</li> <li>FireFly creates a single event stream per namespace from core</li> <li>Each token connector creates a single event stream</li> <li>If one event stream is blocked, it must not block other streams in the FFTM based runtime</li> <li>Listener (/Subscription)</li> <li>A blockchain specific specification for a set of events to listen to</li> <li>Specifies an initial block to listen from, and will replay all events from that block</li> <li>Can have multiple blockchain specific filters, to match multiple events</li> <li>The order of delivery within a listener matches the blockchain across all filters     &gt; - Note that the EVMConnect implementation of FFCAPI attempts to make this true across all listeners     &gt;   on an event stream. However, this is impossible when a new listener has been added,     &gt;   and that listener is catching up from an old block.</li> <li>Compatibility</li> <li>Has breaking changes from the API of EthConnect</li> <li>A component that has been upgraded to support EVMConnect,     can maintain backwards compatibility with EthConnect</li> <li>Batching &amp; Checkpoints</li> <li>Delivery on event streams is via batches, with a single confirmation for each batch</li> <li>At-least-once delivery of batches</li> <li>Checkpoints are written after each batch</li> <li>Chain head stability</li> <li>A configurable section of the head of the chain is considered unstable</li> <li>If no events have been delivered for a listener, checkpoints are still moved forwards</li> <li>These empty checkpoints will never be written in the unstable head of the chain</li> <li>Confirmation manager</li> <li>Plugged in between detection of the events, and assembling into batches</li> <li>Determines the final order based on order of confirmation on the blockchain</li> </ul> <p></p>"},{"location":"architecture/internal_event_sequencing/","title":"Internal Event Sequencing","text":""},{"location":"architecture/internal_event_sequencing/#overview","title":"Overview","text":"<p>One of the most important roles FireFly has, is to take actions being performed by the local apps, process them, get them confirmed, and then deliver back as \"stream of consciousness\" to the application alongside all the other events that are coming into the application from other FireFly Nodes in the network.</p> <p>You might observe the problems solved in this architecture are similar to those in a message queuing system (like Apache Kafka, or a JMS/AMQP provider like ActiveMQ etc.).</p> <p>However, we cannot directly replace the internal logic with such a runtime - because FireFly's job is to aggregate data from multiple runtimes that behave similarly to these:</p> <ul> <li>Private messaging in the Data Exchange</li> <li>The blockchain ledger(s) themselves, which are a stream of sequenced events</li> <li>The event dispatcher delivering messages to applications that have been sequenced by FireFly</li> </ul> <p>So FireFly provides the convenient REST based management interface to simplify the world for application developers, by aggregating the data from multiple locations, and delivering it to apps in a deterministic sequence.</p> <p>The sequence is made deterministic:</p> <ul> <li>Globally to all apps within the scope of the ledger, when a Blockchain ledger is used to pin events (see #10)</li> <li>Locally for messages delivered through a single FireFly node into the network</li> <li>Locally for all messages delivered to applications connected to a FireFly node, across blockchain</li> </ul>"},{"location":"architecture/internal_event_sequencing/#app-instances","title":"App Instances","text":"<ul> <li>Broadcast messages to the network</li> <li>Ingest ack when message persisted in local messages table</li> <li>Consume events via Websocket connection into FireFly</li> </ul>"},{"location":"architecture/internal_event_sequencing/#outbound-sequencers","title":"Outbound Sequencers","text":"<ul> <li>Broadcast or Private through IPFS or Private Data Storage</li> <li>Long-running leader-elected jobs listening to the database (via event tables in SQL, etc.)</li> </ul>"},{"location":"architecture/internal_event_sequencing/#inbound-aggregator","title":"Inbound Aggregator","text":"<ul> <li>Triggered each time an event is detected by the associated plugin.</li> <li>It is the responsibility of the plugin to fire events sequentially. Can be workload managed but must be sequential.</li> </ul>"},{"location":"architecture/internal_event_sequencing/#events-table","title":"Events Table","text":"<ul> <li>Deliberately lightweight persisted object, that is generated as a byproduct of other persistent actions.</li> <li>Records the local sequence of a specific event within the local node.</li> <li>The highest level event type is the confirmation of a message, however the table can be extended for more granularity on event types.</li> </ul>"},{"location":"architecture/internal_event_sequencing/#subscription-manager","title":"Subscription Manager","text":"<ul> <li>Responsible for filtering and delivering batches of events to the active event dispatchers.</li> <li>Records the latest offset confirmed by each dispatcher.</li> </ul>"},{"location":"architecture/internal_event_sequencing/#event-dispatcher","title":"Event Dispatcher","text":"<ul> <li>Created with leadership election when WebSocket connection is made from an app into FireFly.</li> <li>Extensible to other dispatchers (AMQP, etc.).</li> </ul>"},{"location":"architecture/multiparty_event_sequencing/","title":"Multiparty Event Sequencing","text":""},{"location":"architecture/multiparty_event_sequencing/#transaction-submission","title":"Transaction Submission","text":"<ul> <li>An individual FireFly instance preserves the order that it received messages from application instances.</li> <li>Where possible, batching is used to roll-up hundreds of transactions into a single blockchain transaction.</li> <li>Blockchain allows these messages to be globally sequenced with messages submitted by other members of the network.</li> </ul>"},{"location":"architecture/multiparty_event_sequencing/#blockchain-ordering","title":"Blockchain Ordering","text":"<ul> <li>All member FireFly runtimes see every transaction in the same sequence.</li> <li>This includes when transactions are being submitted by both sides concurrently.</li> </ul>"},{"location":"architecture/multiparty_event_sequencing/#message-assembly","title":"Message Assembly","text":"<ul> <li>A queue of events is maintained for each matching app subscription.</li> <li>The public/private payloads travel separately to the blockchain, and arrive at different times. FireFly assembles these together prior to delivery.</li> <li>If data associated with a blockchain transaction is late, or does not arrive, all messages on the same \"context\" will be blocked.</li> <li>It is good practice to send messages that don't need to be processed in order, with different \"context\" fields. For example use the ID of your business transaction, or other long-running process / customer identifier.</li> </ul>"},{"location":"architecture/multiparty_event_sequencing/#event-processing","title":"Event Processing","text":"<ul> <li>Events are processed consistently by all parties.</li> <li>All FireFly runtimes see every event that they are subscribed to, in the same sequence.</li> <li>The submitter must also apply the logic only in the sequence ordered by the blockhain. It cannot assume the order even if it is the member that submitted it.</li> </ul>"},{"location":"architecture/node_component_architecture/","title":"Node Component Architecture","text":""},{"location":"architecture/node_component_architecture/#what-is-a-firefly-node","title":"What is a FireFly Node?","text":"<p>The core architecture of a FireFly node can be broken down into the following three areas:</p> <ul> <li>The various runtimes encapsulating the node.</li> <li>The core runtime responsibilities and pluggable elements.</li> <li>The actual code running inside the node.</li> </ul> <p></p>"},{"location":"architecture/node_component_architecture/#runtimes","title":"Runtimes","text":"<p>What fundamentally is a node - left side of the above diagram.</p> <ul> <li>It is a collection of multiple runtimes with a single unified HTTPS/Websocket API (exposed by the Core).</li> <li>It has a private database, containing your private data, and data received from others in the network.</li> <li>It has connectivity out to other parties in the network, through runtimes (Blockchain, Shared Filesystems, Messaging etc.).</li> </ul>"},{"location":"architecture/node_component_architecture/#responsibilities-pluggable-elements","title":"Responsibilities &amp; Pluggable Elements","text":"<p>What are the core runtime responsibilities, and pluggable elements - right side of the above diagram.</p> <ul> <li>The core elements of function that FireFly performs, and which runtime is responsible.</li> <li>This means some insight into core itself, and the jobs it performs, but not full code structure.</li> <li>More importantly, what the split of responsibilities is between <code>Connectors</code> and <code>Infrastructure Runtimes</code>.<ul> <li><code>Connectors</code> are the bridging runtimes, that know how to talk to a particular runtime.</li> <li>They run separately to the core (like a microservice architecture of an app).</li> <li>They can be written in any language (not just Go) - Java, TypeScript, Rust, Python, .NET etc.</li> <li>They can use any network transport (not just HTTPS/Websockets) - GRPC, AMQP, UDP etc.</li> <li>They connect to the core with a Golang shim - see separate Plugin Architecture discussion.     &gt; - In some special cases (like the Database) the Golang shim does not need a connector runtime.</li> <li><code>Infrastructure Runtimes</code> are the core runtimes for multi-party system activities.</li> <li>Blockchain nodes - Ethereum (Hyperledger Besu, Quorum, Geth), Hyperledger Fabric, Corda etc.</li> <li>Shared strorage - IPFS etc.</li> <li>Database - PostreSQL, CouchDB etc.</li> </ul> </li> </ul>"},{"location":"architecture/node_component_architecture/#code-structure","title":"Code Structure","text":"<p>What is the code structure inside the core.</p> <ul> <li>The README.md is the reference for this.</li> <li>Developers contributing to FireFly, on the core, or building new plugins, need this level of detail. <ul> <li>A reconciliation is underway to ensure the medium-level view correlates well with this code structure.</li> </ul> </li> </ul>"},{"location":"architecture/ping_pong_txflow/","title":"Example Transaction Flow (Ping Pong)","text":""},{"location":"architecture/ping_pong_txflow/#overview","title":"Overview","text":"<p>This demonstrates the problem that at its core FireFly is there to solve. The internal plumbing complexity of just a very simple set of Enterprise blockchain / multi-party system interactions.</p> <ul> <li>Party A: Establish existence of a digital asset.</li> <li>Nothing more than some binary data (an image, a document, a specification etc.).</li> <li>Party A: Broadcast some information about that asset to everyone, using blockchain to record, sequence and propagate.</li> <li>So people can find it, or part of a more sophisticated workflow.</li> <li>Party B: Request the actual data - with evidence of that request tied to the blockchain.</li> <li>Including some private data that's sent to the Party A, reliably off-chain.</li> <li>Party A: Authorize the request, and send the data privately to Party B.</li> <li>In this example there's no blockchain involved in this step.</li> </ul> <p>This is the kind of thing that enterprise projects have been solving ground-up since the dawn of enterprise blockchain, and the level of engineering required that is completely detached from business value, is very high.</p> <p>The \"tramlines\" view shows how FireFly's pluggable model makes the job of the developer really simple:</p> <ul> <li>A few simple API calls from a modern web app.</li> <li>Event triggered execution of application logic.</li> </ul> <p>This is deliberately a simple flow, and all kinds of additional layers might well layer on (and fit within the FireFly model):</p> <ul> <li>NFTs to track ownership etc. related to the digital asset.</li> <li>Tokenized rewards/payments integrated with the authorization of the transfer of data.</li> <li>Proof of deterministic execution of the logic to perform the authorization (on-chain, TEEs, ZKPs).</li> <li>Human workflow, that is of course completely non-deterministic.</li> <li>Multiple additional process steps, deterministic or not.</li> <li>Inclusion of multiple additional parties (maybe it's a request-for-tender, submit-tender flow for example).</li> <li>etc.</li> </ul>"},{"location":"architecture/ping_pong_txflow/#broadcast-public-description-of-binary-data-asset-member-1","title":"Broadcast Public Description of Binary Data Asset (Member 1)","text":"<ul> <li>Upload Blob of the actual data</li> <li>Returns a hash of the payload</li> <li>Upload JSON containing the public index data</li> <li>Includes the hash of the full payload</li> <li>Send a broadcast message with the public index data</li> <li>Agree upon a primary key of the data as the \"context\"</li> </ul>"},{"location":"architecture/ping_pong_txflow/#receive-public-description-request-asset-data-member-2","title":"Receive Public Description &amp; Request Asset Data (Member 2)","text":"<ul> <li>Store data in your own off-chain database for rich, efficient query</li> <li>Run automated logic to decide if you want to request the full data</li> <li>Upload JSON for data request</li> <li>Send a private message</li> <li>Backed by blockchain in this flow</li> </ul>"},{"location":"architecture/ping_pong_txflow/#authorize-transfer-data-member-1","title":"Authorize &amp; Transfer Data (Member 1)","text":"<ul> <li>Inspect the request data</li> <li>Retrieve data asset by hash</li> <li>Send the private data in a private message</li> <li>No blockchain in this flow</li> </ul>"},{"location":"architecture/ping_pong_txflow/#receive-data-asset-member-2","title":"Receive Data Asset (Member 2)","text":"<ul> <li>Receive a link to your local copy of the asset data</li> </ul>"},{"location":"architecture/plugin_architecture/","title":"Plugin Architecture","text":"<p> This diagram shows the various plugins that are currently in the codebase and the layers in each plugin</p> <p> This diagram shows the details of what goes into each layer of a FireFly plugin</p>"},{"location":"architecture/plugin_architecture/#overview","title":"Overview","text":"<p>The FireFly node is built for extensibility, with separate pluggable runtimes orchestrated into a common API for developers. The mechanics of that pluggability for developers of new connectors is explained below:</p> <p>This architecture is designed to provide separations of concerns to account for:</p> <ul> <li>Differences in code language for the low-level connection to a backend (Java for Corda for example)</li> <li>Differences in transports, particularly for delivery of events:</li> <li>Between FireFly Core and the Connector<ul> <li>Different transports other than HTTPS/WebSockets (GRPC etc.), and different wire protocols (socket.io, etc.)</li> </ul> </li> <li>Between the Connector and the underlying Infrastructure Runtime<ul> <li>Often this is heavy lifting engineering within the connector</li> </ul> </li> <li>Differences in High Availability (HA) / Scale architectures</li> <li>Between FireFly Core, and the Connector<ul> <li>Often for event management, and active/passive connector runtime is sufficient</li> </ul> </li> <li>Between the Connector and the Infrastructure Runtime<ul> <li>The infrastructure runtimes have all kinds of variation here... think of the potential landscape here from PostreSQL through Besu/Fabric/Corda, to Hyperledger Avalon and even Main-net ethereum</li> </ul> </li> </ul>"},{"location":"architecture/plugin_architecture/#firefly-core","title":"FireFly Core","text":"<ul> <li>Golang</li> <li>N-way scalable cluster</li> <li>Database is also pluggable via this architecture</li> <li>No long lived in-memory processing</li> <li>All micro-batching must be recoverable</li> <li>Driven by single configuration set</li> <li>Viper semantics - file, env var, cmdline flags</li> </ul>"},{"location":"architecture/plugin_architecture/#plugin-for-connector","title":"Plugin for Connector","text":"<ul> <li>Golang</li> <li>Statically compiled in support at runtime</li> <li>Go dynamic plugin support too immature</li> <li>Must be 100% FLOSS code (no GPL/LGPL etc.)</li> <li>Contributed via PR to FF Core</li> <li>Intended to be lightweight binding/mapping</li> <li>Must adhere to FF Core Coding Standards</li> <li>Scrutiny on addition of new frameworks/transports</li> </ul>"},{"location":"architecture/plugin_architecture/#connector","title":"Connector","text":"<ul> <li>Node.js / Java / Golang, etc.</li> <li>Runs/scales independently from FF core</li> <li>Coded in any language, OSS or proprietary</li> <li>One runtime or multiple</li> <li>HA model can be active/passive or active/active</li> <li>Expectation is all plugins need a connector</li> <li>Some exceptions exist (e.g. database plugin)</li> </ul>"},{"location":"architecture/plugin_architecture/#infrastructure-runtime","title":"Infrastructure Runtime","text":"<ul> <li>Besu, Quorum, Corda, Fabric, IPFS, Kafka, etc.</li> <li>Runs/scales independently from FF Core</li> <li>Coded in any language, OSS or proprietary</li> <li>Not specific to FireFly</li> <li>HA model can be active/passive or active/active</li> </ul>"},{"location":"contributors/","title":"Contributors' Guide","text":"<p>We welcome anyone to contribute to the FireFly project! If you're interested, this is a guide on how to get started. You don't have to be a blockchain expert to make valuable contributions! There are lots of places for developers of all experience levels to get involved.</p> <p>\ud83e\uddd1\ud83c\udffd\u200d\ud83d\udcbb \ud83d\udc69\ud83c\udffb\u200d\ud83d\udcbb \ud83d\udc69\ud83c\udffe\u200d\ud83d\udcbb \ud83e\uddd1\ud83c\udffb\u200d\ud83d\udcbb \ud83e\uddd1\ud83c\udfff\u200d\ud83d\udcbb \ud83d\udc68\ud83c\udffd\u200d\ud83d\udcbb \ud83d\udc69\ud83c\udffd\u200d\ud83d\udcbb \ud83e\uddd1\ud83c\udffe\u200d\ud83d\udcbb \ud83d\udc68\ud83c\udfff\u200d\ud83d\udcbb \ud83d\udc68\ud83c\udffe\u200d\ud83d\udcbb \ud83d\udc69\ud83c\udfff\u200d\ud83d\udcbb \ud83d\udc68\ud83c\udffb\u200d\ud83d\udcbb</p>"},{"location":"contributors/#connect-with-us-on-discord","title":"\ud83d\ude80 Connect with us on Discord","text":"<p>You can chat with maintainers and other contributors on Discord in the <code>firefly</code> channel: https://discord.gg/hyperledger</p> <p>Join Discord Server</p>"},{"location":"contributors/#join-our-community-calls","title":"\ud83d\udcc5 Join our Community Calls","text":"<p>Community calls are a place to talk to other contributors, maintainers, and other people interested in FireFly. Maintainers often discuss upcoming changes and proposed new features on these calls. These calls are a great way for the community to give feedback on new ideas, ask questions about FireFly, and hear how others are using FireFly to solve real world problems.</p> <p>Please see the FireFly Calendar for the current meeting schedule, and the link to join. Everyone is welcome to join, regardless of background or experience level.</p>"},{"location":"contributors/#find-your-first-issue","title":"\ud83d\udd0d Find your first issue","text":"<p>If you're looking for somewhere to get started in the FireFly project and want something small and relatively easy, take a look at issues tagged with \"Good first issue\". You can definitely work on other things if you want to. These are only suggestions for easy places to get started.</p> <p>See \"Good First Issues\"</p> <p>NOTE Hyperledger FireFly has a microservice architecture so it has many different GitHub repos. Use the link or the button above to look for \"Good First Issues\" across all the repos at once.</p> <p>Here are some other suggestions of places to get started, based on experience you may already have:</p>"},{"location":"contributors/#any-level-of-experience","title":"Any level of experience","text":"<p>If you looking to make your first open source contribution the FireFly documentation is a great place to make small, easy improvements. These improvements are also very valuable, because they help the next person that may want to know the same thing.</p> <p>Here are some detailed instructions on Contributing to Documentation</p>"},{"location":"contributors/#go-experience","title":"Go experience","text":"<p>If you have some experience in Go and really want to jump into FireFly, the FireFly Core is the heart of the project.</p> <p>Here are some detailed instructions on Setting up a FireFly Core Development Environment.</p>"},{"location":"contributors/#little-or-no-go-experience-but-want-to-learn","title":"Little or no Go experience, but want to learn","text":"<p>If you don't have a lot of experience with Go, but are interested in learning, the FireFly CLI might be a good place to start. The FireFly CLI is a tool to set up local instances of FireFly for building apps that use FireFly, and for doing development on FireFly itself.</p>"},{"location":"contributors/#typescript-experience","title":"TypeScript experience","text":"<p>If you have some experience in TypeScript, there are several FireFly microservices that are written in TypeScript. The Data Exchange is used for private messaging between FireFly nodes. The ERC-20/ERC-271 Tokens Connector and ERC-1155 Tokens Connector are used to abstract token contract specifics from the FireFly Core.</p>"},{"location":"contributors/#reacttypescript-experience","title":"React/TypeScript experience","text":"<p>If you want to do some frontend development, the FireFly UI is written in TypeScript and React.</p>"},{"location":"contributors/#go-and-blockchain-experience","title":"Go and blockchain experience","text":"<p>If you already have some experience with blockchain and want to work on some backend components, the blockchain connectors, firefly-ethconnect (for Ethereum) and firefly-fabconnect (for Fabric) are great places to get involved.</p>"},{"location":"contributors/#make-changes","title":"\ud83d\udcdd Make changes","text":"<p>To contribute to the repository, please fork the repository that you want to change. Then clone your fork locally on your machine and make your changes. As you commit your changes, push them to your fork. More information on making commits below.</p>"},{"location":"contributors/#commit-with-developer-certificate-of-origin","title":"\ud83d\udcd1 Commit with Developer Certificate of Origin","text":"<p>As with all Hyperledger repositories, FireFly requires proper sign-off on every commit that is merged into the <code>main</code> branch. The sign-off indicates that you certify the changes you are submitting are in accordance with the Developer Certificate of Origin. To sign-off on your commit, you can use the <code>-s</code> flag when you commit changes.</p> <pre><code>git commit -s -m \"Your commit message\"\n</code></pre> <p>This will add a string like this to the end of your commit message:</p> <pre><code>\"Signed-off-by: Your Name &lt;your-email@address&gt;\"\n</code></pre> <p>NOTE: Sign-off is not the same thing as signing your commits with a private key. Both operations use a similar flag, which can be confusing. The one you want is the lowercase <code>-s</code> \ud83d\ude42</p>"},{"location":"contributors/#open-a-pull-request","title":"\ud83d\udce5 Open a Pull Request","text":"<p>When you're ready to submit your changes for review, open a Pull Request back to the upstream repository. When you open your pull request, the maintainers will automatically be notified. Additionally, a series of automated checks will be performed on your code to make sure it passes certain repository specific requirements.</p> <p>Maintainers may have suggestions on things to improve in your pull request. It is our goal to get code that is beneficial to the project merged as quickly as possible, so we don't like to leave pull requests hanging around for a long time. If the project maintainers are satisfied with the changes, they will approve and merge the pull request.</p> <p>Thanks for your interest in collaborating on this project!</p>"},{"location":"contributors/#inclusivity","title":"Inclusivity","text":"<p>The Hyperledger Foundation and the FireFly project are committed to fostering a community that is welcoming to all people. When participating in community discussions, contributing code, or documentaiton, please abide by the following guidelines:</p> <ul> <li>Consider that users who will read the docs are from different background and cultures and that they have different preferences.</li> <li>Avoid potential offensive terms and, for instance, prefer \"allow list and deny list\" to \"white list and black list\".</li> <li>We believe that we all have a role to play to improve our world, and even if writing inclusive doc might not look like a huge improvement, it's a first step in the right direction.</li> <li>We suggest to refer to Microsoft bias free writing guidelines and Google inclusive doc writing guide as starting points.</li> </ul>"},{"location":"contributors/advanced_cli_usage/","title":"Advanced CLI Usage","text":"<p>This page details some of the more advanced options of the FireFly CLI</p>"},{"location":"contributors/advanced_cli_usage/#understanding-how-the-cli-uses-firefly-releases","title":"Understanding how the CLI uses FireFly releases","text":""},{"location":"contributors/advanced_cli_usage/#the-manifestjson-file","title":"The <code>manifest.json</code> file","text":"<p>FireFly has a <code>manifest.json</code> file in the root of the repo. This file contains a list of versions (both tag and sha) for each of the microservices that should be used with this specific commit.</p> <p>Here is an example of what the <code>manifest.json</code> looks like:</p> <pre><code>{\n  \"ethconnect\": {\n    \"image\": \"ghcr.io/hyperledger/firefly-ethconnect\",\n    \"tag\": \"v3.0.4\",\n    \"sha\": \"0b7ce0fb175b5910f401ff576ced809fe6f0b83894277c1cc86a73a2d61c6f41\"\n  },\n  \"fabconnect\": {\n    \"image\": \"ghcr.io/hyperledger/firefly-fabconnect\",\n    \"tag\": \"v0.9.0\",\n    \"sha\": \"a79a4c66b0a2551d5122d019c15c6426e8cdadd6566ce3cbcb36e008fb7861ca\"\n  },\n  \"dataexchange-https\": {\n    \"image\": \"ghcr.io/hyperledger/firefly-dataexchange-https\",\n    \"tag\": \"v0.9.0\",\n    \"sha\": \"0de5b1db891a02871505ba5e0507821416d9fa93c96ccb4b1ba2fac45eb37214\"\n  },\n  \"tokens-erc1155\": {\n    \"image\": \"ghcr.io/hyperledger/firefly-tokens-erc1155\",\n    \"tag\": \"v0.9.0-20211019-01\",\n    \"sha\": \"aabc6c483db408896838329dab5f4b9e3c16d1e9fa9fffdb7e1ff05b7b2bbdd4\"\n  }\n}\n</code></pre>"},{"location":"contributors/advanced_cli_usage/#default-cli-behavior-for-releases","title":"Default CLI behavior for releases","text":"<p>When creating a new stack, the CLI will by default, check the latest non-pre-release version of FireFly and look at its <code>manifest.json</code> file that was part of that commit. It will then use the Docker images referenced in that file to determine which images it should pull for the new stack. The specific image tag and sha is written to the <code>docker-compose.yml</code> file for that stack, so restarting or resetting a stack will never pull a newer image.</p>"},{"location":"contributors/advanced_cli_usage/#running-a-specific-release-of-firefly","title":"Running a specific release of FireFly","text":"<p>If you need to run some other version that is not the latest release of FireFly, you can tell the FireFly CLI which release to use by using the <code>--release</code> or <code>-r</code> flag. For example, to explicitly use <code>v0.9.0</code> run this command to initialize the stack:</p> <pre><code>ff init -r v0.9.0\n</code></pre>"},{"location":"contributors/advanced_cli_usage/#running-an-unreleased-version-of-one-or-more-services","title":"Running an unreleased version of one or more services","text":"<p>If you need to run an unreleased version of FireFly or one of its microservices, you can point the CLI to a specific <code>manifest.json</code> on your local disk. To do this, use the <code>--manifest</code> or <code>-m</code> flag. For example, if you have a file at <code>~/firefly/manifest.json</code>:</p> <pre><code>ff init -m ~/firefly/manifest.json\n</code></pre> <p>If you need to test a locally built docker image of a specific service, you'll want to edit the <code>manifest.json</code> before running <code>ff init</code>. Let's look at an example where we want to run a locally built version of fabconnect. The same steps apply to any of FireFly's microservices.</p>"},{"location":"contributors/advanced_cli_usage/#build-a-new-image-of-fabconnect-locally","title":"Build a new image of fabconnect locally","text":"<p>From the fabconnect project directory, build and tag a new Docker image:</p> <pre><code>docker build -t ghcr.io/hyperledger/firefly-fabconnect .\n</code></pre>"},{"location":"contributors/advanced_cli_usage/#edit-your-manifestjson-file","title":"Edit your <code>manifest.json</code> file","text":"<p>Next, edit the <code>fabconnect</code> section of the <code>manifest.json</code> file. You'll want to remove the <code>tag</code> and <code>sha</code> and a <code>\"local\": true</code> field, so it looks like this:</p> <pre><code>...\n  \"fabconnect\": {\n    \"image\": \"ghcr.io/hyperledger/firefly-fabconnect\",\n    \"local\": true\n  },\n...\n</code></pre>"},{"location":"contributors/advanced_cli_usage/#initialize-the-stack-with-the-custom-manifestjson-file","title":"Initialize the stack with the custom <code>manifest.json</code> file","text":"<pre><code> ff init local-test -b fabric -m ~/Code/hyperledger/firefly/manifest.json\n ff start local-test\n</code></pre> <p>If you are iterating on changes locally, you can get the CLI to use an updated image by doing the following:</p> <ul> <li>Whenever the CLI does its first time setup, it will use your newly built local docker image</li> <li>If you've already run the stack, you can run <code>ff reset &lt;stack_name&gt;</code> and <code>ff start &lt;stack_name&gt;</code> to reset the data, and use the newer image</li> </ul>"},{"location":"contributors/advanced_cli_usage/#running-a-locally-built-firefly-core-image","title":"Running a locally built FireFly Core image","text":"<p>You may have noticed that FireFly core is actually not listed in the <code>manifest.json file</code>. If you want to run a locally built image of FireFly Core, you can follow the same steps above, but instead of editing an existing section in the file, we'll add a new one for FireFly.</p>"},{"location":"contributors/advanced_cli_usage/#build-a-new-image-of-firefly-locally","title":"Build a new image of FireFly locally","text":"<p>From the firefly project directory, build and tag a new Docker image:</p> <pre><code>make docker\n</code></pre>"},{"location":"contributors/advanced_cli_usage/#initialize-the-stack-with-the-custom-manifestjson-file_1","title":"Initialize the stack with the custom <code>manifest.json</code> file","text":"<pre><code> ff init local-test -m ~/Code/hyperledger/firefly/manifest.json\n ff start local-test\n</code></pre>"},{"location":"contributors/code_hierarchy/","title":"FireFly Code Hierarchy","text":"<p>Use the following diagram to better understand the hierarchy amongst the core FireFly components, plugins and utility frameworks:</p> <pre><code>\u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510  \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510\n\u2502 cmd      \u251c\u2500\u2500\u2524 firefly   [Ff]\u2502  - CLI entry point\n\u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518  \u2502               \u2502  - Creates parent context\n              \u2502               \u2502  - Signal handling\n              \u2514\u2500\u2500\u2500\u2500\u2500\u252c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n                    \u2502\n\u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510  \u250c\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510  - HTTP listener (Gorilla mux)\n\u2502 internal \u251c\u2500\u2500\u2524 api       [As]\u2502    * TLS (SSL), CORS configuration etc.\n\u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518  \u2502 server        \u2502    * WS upgrade on same port\n              \u2502               \u2502  - REST route definitions\n              \u2514\u2500\u2500\u2500\u2500\u2500\u252c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518    * Simple routing logic only, all processing deferred to orchestrator\n                    \u2502\n              \u250c\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510  - REST route definition framework\n              \u2502 openapi   [Oa]\u2502    * Standardizes Body, Path, Query, Filter semantics\n              \u2502 spec          |      - OpenAPI 3.0 (Swagger) generation\n              \u2514\u2500\u2500\u2500\u2500\u2500\u252c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518    * Including Swagger. UI\n                    \u2502\n              \u250c\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510  - WebSocket server\n              \u2502           [Ws]\u2502    * Developer friendly JSON based protocol business app development\n              \u2502 websockets    \u2502    * Reliable sequenced delivery\n              \u2514\u2500\u2500\u2500\u2500\u2500\u252c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518    * _Event interface [Ei] supports lower level integration with other compute frameworks/transports_\n                    \u2502\n              \u250c\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510  - Extension point interface to listen for database change events\n              \u2502 admin     [Ae]\u2502    * For building microservice extensions to the core that run externally\n              \u2502 events        |    * Used by the Transaction Manager component\n              \u2514\u2500\u2500\u2500\u2500\u2500\u252c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518    * Filtering to specific object types\n                    \u2502\n              \u250c\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510  - Core data types\n              \u2502 fftypes   [Ft]\u2502    * Used for API and Serialization\n              \u2502               \u2502    * APIs can mask fields on input via router definition\n              \u2514\u2500\u2500\u2500\u2500\u2500\u252c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n                    \u2502\n              \u250c\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510  - Core runtime server. Initializes and owns instances of:\n              \u2502           [Or]\u2502    * Components: Implement features\n  \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u252c\u2500\u2500\u2500\u2524 orchestrator  \u2502    * Plugins:    Pluggable infrastructure services\n  \u2502       \u2502   \u2502               \u2502  - Exposes actions to router\n  \u2502       \u2502   \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518    * Processing starts here for all API calls\n  \u2502       \u2502\n  \u2502  Components: Components do the heavy lifting within the engine\n  \u2502       \u2502\n  \u2502       \u2502   \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510  - Integrates with Blockchain Smart Contract logic across blockchain technologies\n  \u2502       \u251c\u2500\u2500\u2500\u2524 contract  [Cm]\u2502    * Generates OpenAPI 3 / Swagger definitions for smart contracts, and propagates to network\n  \u2502       \u2502   \u2502 manager       \u2502    * Manages listeners for native Blockchain events, and routes those to application events\n  \u2502       \u2502   \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518    * Convert to/from native Blockchain interfaces (ABI etc.) and FireFly Interface [FFI] format\n  \u2502       \u2502\n  \u2502       \u2502   \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510  - Maintains a view of the entire network\n  \u2502       \u251c\u2500\u2500\u2500\u2524 network   [Nm]\u2502    * Integrates with network permissioning [NP] plugin\n  \u2502       \u2502   \u2502 map           \u2502    * Integrates with broadcast plugin\n  \u2502       \u2502   \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518    * Handles hierarchy of member identity, node identity and signing identity\n  \u2502       \u2502\n  \u2502       \u2502   \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510  - Broadcast of data to all parties in the network\n  \u2502       \u251c\u2500\u2500\u2500\u2524 broadcast [Bm]\u2502    * Implements dispatcher for batch component\n  \u2502       \u2502   \u2502 manager       |    * Integrates with shared storage interface [Ss] plugin\n  \u2502       \u2502   \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518    * Integrates with blockchain interface [Bi] plugin\n  \u2502       \u2502\n  \u2502       \u2502   \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510  - Send private data to individual parties in the network\n  \u2502       \u251c\u2500\u2500\u2500\u2524 private   [Pm]\u2502    * Implements dispatcher for batch component\n  \u2502       \u2502   \u2502 messaging     |    * Integrates with the data exchange [Dx] plugin\n  \u2502       \u2502   \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u252c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518    * Messages can be pinned and sequenced via the blockchain, or just sent\n  \u2502       \u2502          \u2502\n  \u2502       \u2502   \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510  - Groups of parties, with isolated data and/or blockchains\n  \u2502       \u2502   \u2502 group     [Gm]\u2502    * Integrates with data exchange [Dx] plugin\n  \u2502       \u2502   \u2502 manager       \u2502    * Integrates with blockchain interface [Bi] plugin\n  \u2502       \u2502   \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n  \u2502       \u2502\n  \u2502       \u2502   \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510  - Private data management and validation\n  \u2502       \u251c\u2500\u2500\u2500\u2524 data      [Dm]\u2502    * Implements dispatcher for batch component\n  \u2502       \u2502   \u2502 manager       \u2502    * Integrates with data exchange [Dx] plugin\n  \u2502       \u2502   \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u252c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518    * Integrates with blockchain interface [Bi] plugin\n  \u2502       \u2502          \u2502\n  \u2502       \u2502   \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510  - JSON data schema management and validation (architecture extensible to XML and more)\n  \u2502       \u2502   \u2502 json      [Jv]\u2502    * JSON Schema validation logic for outbound and inbound messages\n  \u2502       \u2502   \u2502 validator     \u2502    * Schema propagation\n  \u2502       \u2502   \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u252c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518    * Integrates with broadcast plugin\n  \u2502       \u2502          \u2502\n  \u2502       \u2502   \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510  - Binary data addressable via ID or Hash\n  \u2502       \u2502   \u2502 blobstore [Bs]\u2502    * Integrates with data exchange [Dx] plugin\n  \u2502       \u2502   \u2502               \u2502    * Hashes data, and maintains mapping to payload references in blob storage\n  \u2502       \u2502   \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518    * Integrates with blockchain interface [Bi] plugin\n  \u2502       \u2502\n  \u2502       \u2502   \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510  - Download from shared storage\n  \u2502       \u251c\u2500\u2500\u2500\u2524 shared    [Sd]\u2502    * Parallel asynchronous download\n  \u2502       \u2502   \u2502 download      \u2502    * Resilient retry and crash recovery\n  \u2502       \u2502   \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518    * Notification to event aggregator on completion\n  \u2502       \u2502\n  \u2502       \u2502   \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510\n  \u2502       \u251c\u2500\u2500\u2500\u2524 identity [Im] \u2502  - Central identity management service across components\n  \u2502       \u2502   \u2502 manager       \u2502    * Resolves API input identity + key combos (short names, formatting etc.)\n  \u2502       \u2502   \u2502               \u2502    * Resolves registered on-chain signing keys back to identities\n  \u2502       \u2502   \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518    * Integrates with Blockchain Interface and pluggable Identity Interface (TBD)\n  \u2502       \u2502\n  \u2502       \u2502   \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510  - Keeps track of all operations performed against external components via plugins\n  \u2502       \u251c\u2500\u2500\u2500\u2524 operation [Om]\u2502    * Updates database with inputs/outputs\n  \u2502       \u2502   \u2502 manager       \u2502    * Provides consistent retry semantics across plugins\n  \u2502       \u2502   \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n  \u2502       \u2502\n  \u2502       \u2502   \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510  - Private data management and validation\n  \u2502       \u251c\u2500\u2500\u2500\u2524 event     [Em]\u2502    * Implements dispatcher for batch component\n  \u2502       \u2502   \u2502 manager       \u2502    * Integrates with data exchange [Dx] plugin\n  \u2502       \u2502   \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u252c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518    * Integrates with blockchain interface [Bi] plugin\n  \u2502       \u2502          \u2502\n  \u2502       \u2502   \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510  - Handles incoming external data\n  \u2502       \u2502   \u2502           [Ag]\u2502    * Integrates with data exchange [Dx] plugin\n  \u2502       \u2502   \u2502 aggregator    \u2502    * Integrates with shared storage interface [Ss] plugin\n  \u2502       \u2502   \u2502               \u2502    * Integrates with blockchain interface [Bi] plugin\n  \u2502       \u2502   \u2502               \u2502  - Ensures valid events are dispatched only once all data is available\n  \u2502       \u2502   \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u252c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518    * Context aware, to prevent block-the-world scenarios\n  \u2502       \u2502          \u2502\n  \u2502       \u2502   \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510  - Subscription manager\n  \u2502       \u2502   \u2502           [Sm]\u2502    * Creation and management of subscriptions\n  \u2502       \u2502   \u2502 subscription  \u2502    * Creation and management of subscriptions\n  \u2502       \u2502   \u2502 manager       \u2502    * Message to Event matching logic\n  \u2502       \u2502   \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u252c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n  \u2502       \u2502          \u2502\n  \u2502       \u2502   \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510  - Manages delivery of events to connected applications\n  \u2502       \u2502   \u2502 event     [Ed]\u2502    * Integrates with data exchange [Dx] plugin\n  \u2502       \u2502   \u2502 dispatcher    \u2502    * Integrates with blockchain interface [Bi] plugin\n  \u2502       \u2502   \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n  \u2502       \u2502\n  \u2502       \u2502   \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510  - Token creation/transfer initiation, indexing and coordination\n  \u2502       \u251c\u2500\u2500\u2500\u2524 asset     [Am]\u2502    * Fungible tokens: Digitized value/settlement (coins)\n  \u2502       \u2502   \u2502 manager       \u2502    * Non-fungible tokens: NFTs / globally uniqueness / digital twins\n  \u2502       \u2502   \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518    * Full indexing of transaction history\n  \u2502       \u2502   [REST/WebSockets]\n  \u2502       \u2502   \u250c\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510   \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510   \u250c\u2500\n  \u2502       \u2502   \u2502 ERC-20 / ERC-721  \u251c\u2500\u2500\u2500\u2524 ERC-1155 \u251c\u2500\u2500\u2500\u2524  Simple framework for building token connectors\n  \u2502       \u2502   \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518   \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518   \u2514\u2500\n  \u2502       \u2502\n  \u2502       \u2502   \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510\n  \u2502       \u251c\u2500\u2500\u2500\u2524 sync /   [Sa] \u2502  - Sync/Async Bridge\n  \u2502       \u2502   \u2502 async bridge  \u2502    * Provides synchronous request/reply APIs\n  \u2502       \u2502   \u2502               \u2502    * Translates to underlying event-driven API\n  \u2502       \u2502   \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n  \u2502       \u2502\n  \u2502       \u2502   \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510  - Aggregates messages and data, with rolled up hashes for pinning\n  \u2502       \u251c\u2500\u2500\u2500\u2524 batch     [Ba]\u2502    * Pluggable dispatchers\n  \u2502       \u2502   \u2502 manager       \u2502  - Database decoupled from main-line API processing\n  \u2502       \u2502   \u2502               \u2502    * See architecture diagrams for more info on active/active sequencing\n  \u2502       \u2502   \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u252c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518  - Manages creation of batch processor instances\n  \u2502       \u2502          \u2502\n  \u2502       \u2502   \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510  - Short lived agent spun up to assemble batches on demand\n  \u2502       \u2502   \u2502 batch     [Bp]\u2502    * Coupled to an author+type of messages\n  \u2502       \u2502   \u2502 processor     \u2502  - Builds batches of 100s messages for efficient pinning\n  \u2502       \u2502   \u2502               \u2502    * Aggregates messages and data, with rolled up hashes for pinning\n  \u2502       \u2502   \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518  - Shuts down automatically after a configurable inactivity period\n  \u2502       ... more TBD\n  \u2502\nPlugins: Each plugin comprises a Go shim, plus a remote agent microservice runtime (if required)\n  \u2502\n  \u2502           \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510  - Blockchain Interface\n  \u251c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2524           [Bi]\u2502    * Transaction submission - including signing key management\n  \u2502           \u2502 blockchain    \u2502    * Event listening\n  \u2502           \u2502 interface     \u2502    * Standardized operations, and custom on-chain coupling\n  \u2502           \u2514\u2500\u2500\u2500\u2500\u2500\u252c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n  \u2502                 \u2502\n  \u2502                 \u251c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u252c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510\n  \u2502           \u250c\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510   \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510   \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510\n  \u2502           \u2502 ethereum      \u2502   \u2502 fabric        \u2502   \u2502 corda/cordapps \u2502\n  \u2502           \u2514\u2500\u2500\u2500\u2500\u2500\u252c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518   \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518   \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n  \u2502           [REST/WebSockets]\n  \u2502           \u250c\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510   \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510   \u250c\u2500\n  \u2502           \u2502 transaction manager [Tm] \u251c\u2500\u2500\u2500\u2524 Connector API [ffcapi] \u251c\u2500\u2500\u2500\u2524  Simple framework for building blockchain connectors\n  \u2502           \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518   \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518   \u2514\u2500\n  \u2502\n  \u2502           \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510  - Token interface\n  \u251c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2524 tokens    [Ti]\u2502    * Standardizes core concepts: token pools, transfers, approvals\n  \u2502           \u2502 interface     \u2502    * Pluggable across token standards\n  \u2502           \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518    * Supports simple implementation of custom token standards via microservice connector\n  \u2502           [REST/WebSockets]\n  \u2502           \u250c\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510   \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510   \u250c\u2500\n  \u2502           \u2502 ERC-20 / ERC-721  \u251c\u2500\u2500\u2500\u2524 ERC-1155 \u251c\u2500\u2500\u2500\u2524  Simple framework for building token connectors\n  \u2502           \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518   \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518   \u2514\u2500\n  \u2502\n  \u2502           \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510  - P2P Content Addresssed Filesystem\n  \u251c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2524 shared    [Si]\u2502    * Payload upload / download\n  \u2502           \u2502 storage       \u2502    * Payload reference management\n  \u2502           \u2502 interface     \u2502\n  \u2502           \u2514\u2500\u2500\u2500\u2500\u2500\u252c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n  \u2502                 \u2502\n  \u2502                 \u251c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500 ... extensible to any shared storage sytem, accessible to all members\n  \u2502           \u250c\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510\n  \u2502           \u2502 ipfs          \u2502\n  \u2502           \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n  \u2502\n  \u2502           \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510  - Private Data Exchange\n  \u251c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2524 data      [Dx]\u2502    * Blob storage\n  \u2502           \u2502 exchange      \u2502    * Private secure messaging\n  \u2502           \u2514\u2500\u2500\u2500\u2500\u2500\u252c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518    * Secure file transfer\n  \u2502                 \u2502\n  \u2502                 \u251c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u252c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500 ... extensible to any private data exchange tech\n  \u2502           \u250c\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510   \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510\n  \u2502           \u2502 https / MTLS  \u2502   \u2502 Kaleido       \u2502\n  \u2502           \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518   \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n  \u2502\n  \u2502           \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510  - API Authentication and Authorization Interface\n  \u251c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2524 api auth  [Aa]\u2502    * Authenticates security credentials (OpenID Connect id token JWTs etc.)\n  \u2502           \u2502               \u2502    * Extracts API/user identity (for identity interface to map)\n  \u2502           \u2514\u2500\u2500\u2500\u2500\u2500\u252c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518    * Enforcement point for fine grained API access control\n  \u2502                 \u2502\n  \u2502                 \u251c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u252c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500 ... extensible other single sign-on technologies\n  \u2502           \u250c\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510   \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510\n  \u2502           \u2502 apikey        \u2502   \u2502 jwt           \u2502\n  \u2502           \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518   \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n  \u2502\n  \u2502           \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510  - Database Interactions\n  \u251c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2524 database  [Di]\u2502    * Create, Read, Update, Delete (CRUD) actions\n  \u2502           \u2502 interace      \u2502    * Filtering and update definition interace\n  \u2502           \u2514\u2500\u2500\u2500\u2500\u2500\u252c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518    * Migrations and Indexes\n  \u2502                 \u2502\n  \u2502                 \u251c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500 ... extensible to NoSQL (CouchDB / MongoDB etc.)\n  \u2502           \u250c\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510\n  \u2502           \u2502 sqlcommon     \u2502\n  \u2502           \u2514\u2500\u2500\u2500\u2500\u2500\u252c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n  \u2502                 \u251c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u252c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500 ... extensible other SQL databases\n  \u2502           \u250c\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510     \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510\n  \u2502           \u2502 postgres      \u2502     \u2502 sqlite3        \u2502\n  \u2502           \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518     \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n  \u2502\n  \u2502           \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510  - Connects the core event engine to external frameworks and applications\n  \u251c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2524 event     [Ei]\u2502    * Supports long-lived (durable) and ephemeral event subscriptions\n  \u2502           \u2502 interface     \u2502    * Batching, filtering, all handled in core prior to transport\n  \u2502           \u2514\u2500\u2500\u2500\u2500\u2500\u252c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518    * Interface supports connect-in (websocket) and connect-out (broker runtime style) plugins\n  \u2502                 \u2502\n  \u2502                 \u251c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u252c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500   ... extensible to additional event buses (Kafka, NATS, AMQP etc.)\n  \u2502           \u250c\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510     \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510\n  \u2502           \u2502 websockets    \u2502     \u2502 webhooks       \u2502\n  \u2502           \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518     \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n  \u2502  ... more TBD\n\n  Additional utility framworks\n              \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510  - REST API client\n              \u2502 rest      [Re]\u2502    * Provides convenience and logging\n              \u2502 client        \u2502    * Standardizes auth, config and retry logic\n              \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518    * Built on Resty\n\n              \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510  - WebSocket client\n              \u2502 wsclient  [Wc]\u2502    * Provides convenience and logging\n              \u2502               \u2502    * Standardizes auth, config and reconnect logic\n              \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518    * Built on Gorilla WebSockets\n\n              \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510  - Translation framework\n              \u2502 i18n      [In]\u2502    * Every translations must be added to `en_translations.json` - with an `FF10101` key\n              \u2502               \u2502    * Errors are wrapped, providing extra features from the `errors` package (stack etc.)\n              \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518    * Description translations also supported, such as OpenAPI description\n\n              \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510  - Logging framework\n              \u2502 log       [Lo]\u2502    * Logging framework (logrus) integrated with context based tagging\n              \u2502               \u2502    * Context is used throughout the code to pass API invocation context, and logging context\n              \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518    * Example: Every API call has an ID that can be traced, as well as a timeout\n\n              \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510  - Configuration\n              \u2502 config    [Co]\u2502    * File and Environment Variable based logging framework (viper)\n              \u2502               \u2502    * Primary config keys all defined centrally\n              \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518    * Plugins integrate by returning their config structure for unmarshaling (JSON tags)\n</code></pre>"},{"location":"contributors/code_overview/","title":"FireFly Code Overview","text":""},{"location":"contributors/code_overview/#developer-intro","title":"Developer Intro","text":"<p>FireFly is a second generation implementation re-engineered from the ground up to improve developer experience, runtime performance, and extensibility.</p> <p>This means a simplified REST/WebSocket programming model for app development, and a wider range of infrastructure options for deployment.</p> <p>It also means a focus on an architecture and code structure for a vibrant open source community.</p> <p>A few highlights:</p> <ul> <li>Golang codebase</li> <li>Strong coding standards, including unit test coverage, translation support, logging and more</li> <li>Fast starting, low memory footprint, multi-threaded runtime</li> <li>OpenAPI 3.0 API specification (Swagger)</li> <li>Generated from the API router code, to avoid divergence with the implementation</li> <li>Active/active HA architecture for the core runtime</li> <li>Deferring to the core database for state high availability</li> <li>Exploiting leader election where required</li> <li>Fully pluggable architecture</li> <li>Everything from Database through to Blockchain, and Compute</li> <li>Golang plugin infrastructure to decouple the core code from the implementation</li> <li>Remote Agent model to decouple code languages, and HA designs</li> <li>Updated API resource model</li> <li><code>Asset</code>, <code>Data</code>, <code>Message</code>, <code>Event</code>, <code>Topic</code>, <code>Transaction</code></li> <li> <p>Added flexibility, with simplified the developer experience:</p> </li> <li> <p>Versioning of data definitions</p> </li> <li>Introducing a first class <code>Context</code> construct link related events into a single sequence</li> <li>Allow many pieces of data to be attached to a single message, and be automatically re-assembled on arrival</li> <li>Clearer separation of concerns between the FireFly DB and the Application DB</li> <li>Better search, filter and query support</li> </ul> <p>## Directories</p> <ul> <li>internal: The core Golang implementation code</li> <li>pkg: Interfaces intended for external project use</li> <li>cmd: The command line entry point</li> <li>smart_contracts: smart contract code for FireFly's onchain logic</li> </ul>"},{"location":"contributors/code_repositories/","title":"Code Repositories","text":"<p>FireFly has a plugin based architecture design, with a microservice runtime footprint. As such there are a number of repos, and the list will grow as the community evolves.</p> <p>But not to worry, one of those repos is a CLI designed to get you running with all the components you need in minutes!</p> <ul> <li>CLI / Developer experience</li> <li>FireFly Samples</li> <li>UI Explorer</li> <li>Core</li> <li>HTTP Data Exchange</li> <li>Ethereum (Hyperledger Besu / Quorum) connector</li> <li>Corda connector</li> <li>Hyperledger Fabric connector</li> <li>Token connector reference implementation (ERC1155)</li> </ul> <p>Note only the projects that are primarily built to support FireFly are listed here, not all of the ecosystem of projects that integrate underneath the plugins.</p>"},{"location":"contributors/dev_environment_setup/","title":"Setting up a FireFly Core Development Environment","text":"<p>This guide will walk you through setting up your machine for contributing to FireFly, specifically the FireFly core.</p>"},{"location":"contributors/dev_environment_setup/#dependencies","title":"Dependencies","text":"<p>You will need a few prerequisites set up on your machine before you can build FireFly from source. We recommend doing development on macOS, Linux, or WSL 2.0.</p> <ul> <li>Go 1.22</li> <li>make</li> <li>GCC</li> <li>openssl</li> </ul>"},{"location":"contributors/dev_environment_setup/#install-the-firefly-cli","title":"Install the FireFly CLI","text":"<p>The first step to setting up a local development environment is to install the FireFly CLI. Please section of the Getting Started Guide to install The FireFly CLI.</p>"},{"location":"contributors/dev_environment_setup/#installing-go-and-setting-up-your-gopath","title":"Installing Go and setting up your <code>GOPATH</code>","text":"<p>We recommend following the instructions on golang.org to install Go, rather than installing Go from another package magager such as <code>brew</code>. Although it is possible to install Go any way you'd like, setting up your <code>GOPATH</code> may differ from the following instructions.</p> <p>After installing Go, you will need to add a few environment variables to your shell run commands file. This is usually a hidden file in your home directory called <code>.bashrc</code> or <code>.zshrc</code>, depending on which shell you're using.</p> <p>Add the following lines to your <code>.bashrc</code> or <code>.zshrc</code> file:</p> <pre><code>export GOPATH=$HOME/go\nexport GOROOT=\"/usr/local/go\"\nexport PATH=\"$PATH:${GOPATH}/bin:${GOROOT}/bin\"\n</code></pre>"},{"location":"contributors/dev_environment_setup/#building-firefly","title":"Building FireFly","text":"<p>After installing dependencies, building FireFly from source is very easy. Just clone the repo:</p> <pre><code>git clone git@github.com:hyperledger/firefly.git &amp;&amp; cd firefly\n</code></pre> <p>And run the <code>Makefile</code> to run tests, and compile the app</p> <pre><code>make\n</code></pre> <p>If you want to install the binary on your path (assuming your Go Home is already on your path), from inside the project directory you can simply run:</p> <pre><code>go install\n</code></pre>"},{"location":"contributors/dev_environment_setup/#install-the-cli","title":"Install the CLI","text":"<p>Please check the CLI Installation instructions for the best way to install the CLI on your machine: https://github.com/hyperledger/firefly-cli#install-the-cli</p>"},{"location":"contributors/dev_environment_setup/#set-up-a-development-stack","title":"Set up a development stack","text":"<p>Now that you have both FireFly and the FireFly CLI installed, it's time to create a development stack. The CLI can be used to create a docker-compose environment that runs the entirety of a FireFly network. This will include several different processes for each member of the network. This is very useful for people that want to build apps that use FireFly's API. It can also be useful if you want to make changes to FireFly itself, however we need to set up the stack slightly differently in that case.</p> <p>Essentially what we are going to do is have docker-compose run everything in the FireFly network except one FireFly core process. We'll run this FireFly core process on our host machine, and configure it to connect to the rest of the microservices running in docker-compose. This means we could launch FireFly from Visual Studio Code or some other IDE and use a debugger to see what's going on inside FireFly as it's running.</p> <p>We'll call this stack <code>dev</code>. We're also going to add <code>--external 1</code> to the end of our command to create the new stack:</p> <pre><code>ff init dev --external 1\n</code></pre> <p>This tells the CLI that we want to manage one of the FireFly core processes outside the docker-compose stack. For convenience, the CLI will still generate a config file for this process though.</p>"},{"location":"contributors/dev_environment_setup/#start-the-stack","title":"Start the stack","text":"<p>To start your new stack simply run:</p> <pre><code>ff start dev\n</code></pre> <p>At a certain point in the startup process, the CLI will pause and wait for up to two minutes for you to start the other FireFly node. There are two different ways you can run the external FireFly core process.</p>"},{"location":"contributors/dev_environment_setup/#1-from-another-terminal","title":"1) From another terminal","text":"<p>The CLI will print out the command line which can be copied and pasted into another terminal window to run FireFly. This command should be run from the <code>firefly</code> core project directory. Here is an example of the command that the CLI will tell you to run:</p> <pre><code>firefly -f ~/.firefly/stacks/dev/runtime/config/firefly_core_0.yml\n</code></pre> <p>NOTE: The first time you run FireFly with a fresh database, it will need a directory of database migrations to apply to the empty database. If you run FireFly from the <code>firefly</code> project directory you cloned from GitHub, it will automatically find these and apply them. If you run it from some other directory, you will have to point FireFly to the migrations on your own.</p>"},{"location":"contributors/dev_environment_setup/#2-using-an-ide","title":"2) Using an IDE","text":"<p>If you named your stack <code>dev</code> there is a <code>launch.json</code> file for Visual Studio code already in the project directory. If you have the project open in Visual Studio Code, you can either press the F5 key to run it, or go to the \"Run and Debug\" view in Visual Studio code, and click \"Run FireFly Core\".</p> <p></p> <p>Now you should have a full FireFly stack up and running, and be able to debug FireFly using your IDE. Happy hacking!</p> <p>NOTE: Because <code>firefly-ui</code> is a separate repo, unless you also start a UI dev server for the external FireFly core, the default UI path will not load. This is expected, and if you're just working on FireFly core itself, you don't need to worry about it.`</p>"},{"location":"contributors/dev_environment_setup/#set-up-dev-environment-for-other-components","title":"Set up dev environment for other components","text":"<p>Refer to Advanced CLI Usage.</p>"},{"location":"contributors/docs_setup/","title":"Contributing to Documentation","text":"<p>This guide will walk you through setting up your machine for contributing to FireFly documentation. Documentation contributions are extremely valuable. If you discover something is missing in the docs, we would love to include your additions or clarifications to help the next person who has the same question.</p> <p>This doc site is generated by a set of Markdown files in the main FireFly repository, under the <code>./doc-site</code> directory. You can browse the source for the current live site in GitHub here: https://github.com/hyperledger/firefly/tree/main/doc-site</p>"},{"location":"contributors/docs_setup/#process-for-updating-documentation","title":"Process for updating documentation","text":"<p>The process for updating the documentation is really easy! You'll follow the same basic steps outlined in the same steps outlined in the Contributor's guide. Here are the detailed steps for contributing to the docs:</p> <ol> <li>Fork https://github.com/hyperledger/firefly</li> <li>Clone your fork locally to your computer</li> <li>Follow the steps below to view your local copy of the docs in a browser</li> <li>Make some improvements to the Markdown files</li> <li>Verify that your changes look they way you want them to in your browser</li> <li>Create a new git commit with your changes. Be sure to sign-off on your commit by using <code>git commit -s</code>!</li> <li>Push your changes</li> <li>Open a Pull Request to incorporate your changes back into the hyperledger/firefly repo</li> </ol> <p>This FireFly documentation site is based on the Hyperledger documentation template. The template utilizes MkDocs (documentation at mkdocs.org) and the theme Material for MkDocs (documentation at Material for MkDocs). Material adds a number of extra features to MkDocs, and Hyperledger repositories can take advantage of the theme's Insiders capabilities.</p>"},{"location":"contributors/docs_setup/#prerequisites","title":"Prerequisites","text":"<p>To test the documents and update the published site, the following tools are needed:</p> <ul> <li>A Bash shell</li> <li>git</li> <li>Python 3</li> <li>The Material for Mkdocs theme.</li> <li>The Mike MkDocs plugin for publishing versions to gh-pages.</li> <li>Not used locally, but referenced in the <code>mkdocs.yml</code> file and needed for     deploying the site to gh-pages.</li> </ul>"},{"location":"contributors/docs_setup/#git","title":"git","text":"<p><code>git</code> can be installed locally, as described in the Install Git Guide from GitHub.</p>"},{"location":"contributors/docs_setup/#python-3","title":"Python 3","text":"<p><code>Python 3</code> can be installed locally, as described in the Python Getting Started guide.</p>"},{"location":"contributors/docs_setup/#virtual-environment","title":"Virtual environment","text":"<p>It is recommended to install your Python dependencies in a virtual environment in case you have other conflicting Python installations on your machine. This also removes the need to install these packages globally on your computer.</p> <pre><code>cd doc-site\npython3 -m venv venv\nsource venv/bin/activate\n</code></pre>"},{"location":"contributors/docs_setup/#mkdocs","title":"Mkdocs","text":"<p>The Mkdocs-related items can be installed locally, as described in the Material for Mkdocs installation instructions. The short, case-specific version of those instructions follow:</p> <pre><code>pip install -r requirements.txt\n</code></pre>"},{"location":"contributors/docs_setup/#verify-setup","title":"Verify Setup","text":"<p>To verify your setup, check that you can run <code>mkdocs</code> by running the command <code>mkdocs --help</code> to see the help text.</p>"},{"location":"contributors/docs_setup/#useful-mkdocs-commands","title":"Useful MkDocs Commands","text":"<p>The commands you will usually use with <code>mkdocs</code> are:</p> <ul> <li><code>mkdocs serve</code> - Start the live-reloading docs server.</li> <li><code>mkdocs build</code> - Build the documentation site.</li> <li><code>mkdocs -h</code> - Print help message and exit.</li> </ul>"},{"location":"contributors/docs_setup/#directory-layout","title":"Directory layout","text":"<pre><code>mkdocs.yml     # The configuration file.\ndocs/\n    index.md   # The documentation homepage.\n    SUMMARY.md # The main left nav\n    ...        # Other markdown pages, images and other files.\n</code></pre>"},{"location":"contributors/release_guide/","title":"Release Guide","text":"<p>This guide will walk you through creating a release.</p>"},{"location":"contributors/release_guide/#versioning-scheme","title":"Versioning scheme","text":"<p>FireFly follows semantic versioning. For more details on how we determine which version to use please see the Versioning Scheme guide.</p>"},{"location":"contributors/release_guide/#the-manifestjson-file","title":"The <code>manifest.json</code> file","text":"<p>FireFly has a <code>manifest.json</code> file in the root of the repo. This file contains a list of versions (both tag and sha) for each of the microservices that should be used with this specific commit. If you need FireFly to use a newer version of a microservice listed in this file, you should update the <code>manifest.json</code> file, commit it, and include it in your PR. This will trigger an end-to-end test run, using the specified versions.</p> <p>Here is an example of what the <code>manifest.json</code> looks like:</p> <pre><code>{\n  \"ethconnect\": {\n    \"image\": \"ghcr.io/hyperledger/firefly-ethconnect\",\n    \"tag\": \"v3.0.4\",\n    \"sha\": \"0b7ce0fb175b5910f401ff576ced809fe6f0b83894277c1cc86a73a2d61c6f41\"\n  },\n  \"fabconnect\": {\n    \"image\": \"ghcr.io/hyperledger/firefly-fabconnect\",\n    \"tag\": \"v0.9.0\",\n    \"sha\": \"a79a4c66b0a2551d5122d019c15c6426e8cdadd6566ce3cbcb36e008fb7861ca\"\n  },\n  \"dataexchange-https\": {\n    \"image\": \"ghcr.io/hyperledger/firefly-dataexchange-https\",\n    \"tag\": \"v0.9.0\",\n    \"sha\": \"0de5b1db891a02871505ba5e0507821416d9fa93c96ccb4b1ba2fac45eb37214\"\n  },\n  \"tokens-erc1155\": {\n    \"image\": \"ghcr.io/hyperledger/firefly-tokens-erc1155\",\n    \"tag\": \"v0.9.0-20211019-01\",\n    \"sha\": \"aabc6c483db408896838329dab5f4b9e3c16d1e9fa9fffdb7e1ff05b7b2bbdd4\"\n  }\n}\n</code></pre> <p>NOTE: You can run <code>make manifest</code> in the FireFly core source directory, and a script will run to automatically get the latests non-pre-release version of each of FireFly's microservices. If you need to use a snapshot or pre-release version you should edit <code>manifest.json</code> file manually, as this script will not fetch those versions.</p>"},{"location":"contributors/release_guide/#creating-a-new-release","title":"Creating a new release","text":"<p>Releases and builds are managed by GitHub. New binaries and/or Docker images will automatically be created when a new release is published. The easiest way to create a release is through the web UI for the repo that you wish to release.</p>"},{"location":"contributors/release_guide/#1-navigate-to-the-release-page-for-the-repo","title":"1) Navigate to the release page for the repo","text":""},{"location":"contributors/release_guide/#2-click-the-draft-a-new-release-button","title":"2) Click the <code>Draft a new release</code> button","text":""},{"location":"contributors/release_guide/#3-fill-out-the-form-for-your-release","title":"3) Fill out the form for your release","text":"<p>It is recommended to start with the auto-generated release notes. Additional notes can be added as-needed.</p>"},{"location":"contributors/release_guide/#automatic-docker-builds","title":"Automatic Docker builds","text":"<p>After cutting a new release, a GitHub Action will automatically start a new Docker build, if the repo has a Docker image associated with it. You can check the status of the build by clicking the \"Actions\" tab along the top of the page, for that repo.</p> <p></p>"},{"location":"contributors/version_scheme/","title":"Versioning Scheme","text":"<p>This page describes FireFly's versioning scheme</p>"},{"location":"contributors/version_scheme/#semantic-versioning","title":"Semantic versioning","text":"<p>FireFly follows semantic versioning. In summary, this means:</p> <p>Given a version number MAJOR.MINOR.PATCH, increment the:</p> <ul> <li>MAJOR version when you make incompatible API changes,</li> <li>MINOR version when you add functionality in a backwards compatible manner, and</li> <li>PATCH version when you make backwards compatible bug fixes.</li> <li>Additional labels for pre-release and build metadata are available as extensions to the MAJOR.MINOR.PATCH format.</li> </ul> <p>When creating a new release, the release name and tag should be the semantic version should be prefixed with a <code>v</code> . For example, a certain release name/tag could be <code>v0.9.0</code>.</p>"},{"location":"contributors/version_scheme/#pre-release-test-versions","title":"Pre-release test versions","text":"<p>For pre-release versions for testing, we append a date and index to the end of the most recently released version. For example, if we needed to create a pre-release based on <code>v0.9.0</code> and today's date is October 22, 2021, the version name/tag would be: <code>v0.9.0-20211022-01</code>. If for some reason you needed to create another pre-release version in the same day (hey, stuff happens), the name/tag for that one would be <code>v0.9.0-20211022-02</code>.</p>"},{"location":"contributors/version_scheme/#candidate-releases","title":"Candidate releases","text":"<p>For pre-releases that are candidates to become a new major or minor release, the release name/tag will be based on the release that the candidate will become (as opposed to the test releases above, which are based on the previous release). For example, if the current latest release is <code>v0.9.0</code> but we want to create an alpha release for 1.0, the release name/tag would be <code>v1.0.0-alpha.1</code>.</p>"},{"location":"faqs/","title":"FAQs","text":"<p>Find answers to the most commonly asked FireFly questions.</p>"},{"location":"faqs/#how-does-firefly-enable-multi-chain-applications","title":"How does FireFly enable multi-chain applications?","text":"<p>It's best to think about FireFly as a rich orchestration layer that sits one layer above the blockchain. FireFly helps to abstract away much of the complex blockchain functionality (such as data exchange, private messaging, common token functionality, etc) in a loosely coupled microservice architecture with highly pluggable components. This enables application developers to focus on building innovative Web3 applications.</p> <p>There aren't any out of the box bridges to connect two separate chains together, but with a collection of FireFly instances across a consortium, FireFly could help listen for events on Blockchain A and take an action on Blockchain B when certain conditions are met.</p>"},{"location":"faqs/#how-do-i-deploy-smart-contracts","title":"\ud83d\udcdc How do I deploy smart contracts?","text":"<p>The recommended way to deploy smart contracts on Ethereum chains is by using FireFly's built in API. For a step by step example of how to do this you can refer to the Smart Contract Tutorial for Ethereum based chains.</p> <p>For Fabric networks, please refer to the Fabric chaincode lifecycle docs for detailed instructions on how to deploy and manage Fabric chaincode.</p>"},{"location":"faqs/#can-i-connect-firefly-to-metamask","title":"\ud83e\udd8a Can I connect FireFly to MetaMask?","text":"<p>Yes! Before you set up MetaMask you'll likely want to create some tokens that you can use to send between wallets on your FF network. Go to the tokens tab in your FireFly node's UI, create a token pool, and then mint some tokens. Once you've done this, follow the steps listed here to set up MetaMask on your network.</p>"},{"location":"faqs/#connect-with-us-on-discord","title":"\ud83d\ude80 Connect with us on Discord","text":"<p>If your question isn't answered here or if you have immediate questions please don't hesitate to reach out to us on Discord in the <code>firefly</code> channel:</p>"},{"location":"gettingstarted/","title":"Getting Started","text":"<p>If you're new to FireFly, this is the perfect place to start! With the FireFly CLI and the FireFly Sandbox it's really easy to get started building powerful blockchain apps. Just follow along with the steps below and you'll be up and running in no time!</p> <p> </p>"},{"location":"gettingstarted/#what-you-will-accomplish-with-this-guide","title":"What you will accomplish with this guide","text":"<p>With this easy-to-follow guide, you'll go from \"zero\" to blockchain-hero in the time it takes to drink a single cup of coffee. It will walk you through setting up your machine, all the way through sending your first blockchain transactions using the FireFly Sandbox.</p> <p></p>"},{"location":"gettingstarted/#were-here-to-help","title":"We're here to help!","text":"<p>We want to make it as easy as possible for anyone to get started with FireFly, and we don't want anyone to feel like they're stuck. If you're having trouble, or are just curious about what else you can do with FireFly we encourage you to join the Hyperledger Discord server and come chat with us in the #firefly channel.</p>"},{"location":"gettingstarted/#get-started-install-the-firefly-cli","title":"Get started: Install the FireFly CLI","text":"<p>Now that you've got the FireFly CLI set up on your machine, the next step is to create and start a FireFly stack.</p> <p>\u2460 Install the FireFly CLI \u2192</p>"},{"location":"gettingstarted/firefly_cli/","title":"Install the FireFly CLI","text":""},{"location":"gettingstarted/firefly_cli/#prerequisites","title":"Prerequisites","text":"<p>In order to run the FireFly CLI, you will need a few things installed on your dev machine:</p> <ul> <li>Docker</li> <li>Docker Compose</li> <li>openssl</li> </ul>"},{"location":"gettingstarted/firefly_cli/#linux-users","title":"Linux Users","text":"<p>NOTE: For Linux users, it is recommended that you add your user to the <code>docker</code> group so that you do not have to run <code>ff</code> or <code>docker</code> as <code>root</code> or with <code>sudo</code>. For more information about Docker permissions on Linux, please see Docker's documentation on the topic.</p>"},{"location":"gettingstarted/firefly_cli/#windows-users","title":"Windows Users","text":"<p>NOTE: For Windows users, we recommend that you use Windows Subsystem for Linux 2 (WSL2). Binaries provided for Linux will work in this environment.</p>"},{"location":"gettingstarted/firefly_cli/#install-the-cli","title":"Install the CLI","text":"<p>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.</p>"},{"location":"gettingstarted/firefly_cli/#download-the-package-for-your-os","title":"Download the package for your OS","text":"<p>Go to the latest release page and download the package for your OS and CPU architecture.</p>"},{"location":"gettingstarted/firefly_cli/#extract-the-binary-and-move-it-to-usrbinlocal","title":"Extract the binary and move it to <code>/usr/bin/local</code>","text":"<p>Assuming you downloaded the package from GitHub into your <code>Downloads</code> directory, run the following command:</p> <pre><code>sudo tar -zxf ~/Downloads/firefly-cli_*.tar.gz -C /usr/local/bin ff &amp;&amp; rm ~/Downloads/firefly-cli_*.tar.gz\n</code></pre> <p>If you downloaded the package from GitHub into a different directory, you will need to change the <code>tar</code> command above to wherever the <code>firefly-cli_*.tar.gz</code> file is located.</p>"},{"location":"gettingstarted/firefly_cli/#macosusers","title":"macOSUsers","text":"<p>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, before it will run.</p>"},{"location":"gettingstarted/firefly_cli/#alternative-installation-method-install-via-go","title":"Alternative installation method: Install via Go","text":"<p>If you have a local Go development environment, and you have included <code>${GOPATH}/bin</code> in your path, you could also use Go to install the FireFly CLI by running:</p> <pre><code>go install github.com/hyperledger/firefly-cli/ff@latest\n</code></pre>"},{"location":"gettingstarted/firefly_cli/#verify-the-installation","title":"Verify the installation","text":"<p>After using either installation method above, you can verify that the CLI is successfully installed by running <code>ff version</code>. This should print the current version like this:</p> <pre><code>{\n  \"Version\": \"v0.0.47\",\n  \"License\": \"Apache-2.0\"\n}\n</code></pre>"},{"location":"gettingstarted/firefly_cli/#next-steps-start-your-environment","title":"Next steps: Start your environment","text":"<p>Now that you've got the FireFly CLI set up on your machine, the next step is to create and start a FireFly stack.</p> <p>\u2461 Start your environment \u2192</p>"},{"location":"gettingstarted/sandbox/","title":"Use the Sandbox","text":""},{"location":"gettingstarted/sandbox/#previous-steps-start-your-environment","title":"Previous steps: Start your environment","text":"<p>If you haven't started a FireFly stack already, please go back to the previous step and read the guide on how to Start your environment.</p> <p>\u2190 \u2461 Start your environment</p> <p>Now that you have a full network of three Supernodes running on your machine, let's look at the first two components that you will interact with: the FireFly Sandbox and the FireFly Explorer.</p>"},{"location":"gettingstarted/sandbox/#video-walkthrough","title":"Video walkthrough","text":"<p>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.</p>"},{"location":"gettingstarted/sandbox/#open-the-firefly-sandbox-for-the-first-member","title":"Open the FireFly Sandbox for the first member","text":"<p>When you set up your FireFly stack in the previous section, it should have printed some URLs like the following. Open the link in a browser for the `Sandbox UI for member '0'. It should be: http://127.0.0.1:5109</p> <pre><code>ff start dev\nthis will take a few seconds longer since this is the first time you're running this stack...\ndone\n\nWeb UI for member '0': http://127.0.0.1:5000/ui\nSandbox UI for member '0': http://127.0.0.1:5109\n\nWeb UI for member '1': http://127.0.0.1:5001/ui\nSandbox UI for member '1': http://127.0.0.1:5209\n\nWeb UI for member '2': http://127.0.0.1:5002/ui\nSandbox UI for member '2': http://127.0.0.1:5309\n\n\nTo see logs for your stack run:\n\nff logs dev\n</code></pre>"},{"location":"gettingstarted/sandbox/#sandbox-layout","title":"Sandbox Layout","text":"<p>The Sandbox is split up into three columns:</p>"},{"location":"gettingstarted/sandbox/#left-column-prepare-your-request","title":"Left column: Prepare your request","text":"<p>On the left-hand side of the page, you can fill out simple form fields to construct messages and more. Some tabs have more types of requests on them in sections that can be expanded or collapsed. Across the top of this column there are three tabs that switch between the three main sets of functionality in the Sandbox. The next three sections of this guide will walk you through each one of these.</p> <p>The first tab we will explore is the MESSAGING tab. This is where we can send broadcasts and private messages.</p>"},{"location":"gettingstarted/sandbox/#middle-column-preview-server-code-and-see-response","title":"Middle column: Preview server code and see response","text":"<p>As you type in the form on the left side of the page, you may notice that the source code in the top middle of the page updates automatically. If you were building a backend app, this is an example of code that your app could use to call the FireFly SDK. The middle column also contains a <code>RUN</code> button to actually send the request.</p>"},{"location":"gettingstarted/sandbox/#right-column-events-received-on-the-websocket","title":"Right column: Events received on the WebSocket","text":"<p>On the right-hand side of the page you can see a stream of events being received on a WebSocket connection that the backend has open to FireFly. For example, as you make requests to send messages, you can see when the messages are asynchronously confirmed.</p>"},{"location":"gettingstarted/sandbox/#messages","title":"Messages","text":"<p>The Messages tab is where we can send broadcast and private messages to other members and nodes in the FireFly network. Messages can be a string, any arbitrary JSON object, or a binary file. For more details, please see the tutorial on Broadcasting data and Privately sending data.</p>"},{"location":"gettingstarted/sandbox/#things-to-try-out","title":"Things to try out","text":"<ul> <li>Send a broadcast message and view the data payload in every member's FireFly Explorer</li> <li>Send a private message to one member, and verify that the data payload is not visible in the third member's FireFly Explorer</li> <li>Send an image file and download it from another member's FireFly Explorer</li> </ul>"},{"location":"gettingstarted/sandbox/#tokens","title":"Tokens","text":"<p>The Tokens tab is where you can create token pools, and mint, burn, or transfer tokens. This works with both fungible and non-fungible tokens (NFTs). For more details, please see the Tokens tutorials.</p>"},{"location":"gettingstarted/sandbox/#things-to-try-out_1","title":"Things to try out","text":"<ul> <li>Create a fungible token pool and mint some tokens and view your balance in the FireFly Explorer</li> <li>Transfer some amount of those tokens to another member and view the transfer transaction in the FireFly Explorer</li> <li>Burn some amount of tokens and view the transaction and updated balances in the FireFly Explorer</li> <li>Create a non-fungible token pool and mint some NFTs</li> <li>Transfer an NFT to another member and verify the account balances in the FireFly Explorer</li> </ul>"},{"location":"gettingstarted/sandbox/#contracts","title":"Contracts","text":"<p>The Contracts section of the Sandbox lets you interact with custom smart contracts, right from your web browser! The Sandbox also provides some helpful tips on deploying your smart contract to the blockchain. For more details, please see the tutorial on Working with custom smart contracts.</p> <p></p> <p></p>"},{"location":"gettingstarted/sandbox/#things-to-try-out_2","title":"Things to try out","text":"<ul> <li>Create a contract interface and API, then view the Swagger UI for your new API</li> <li>Create an event listener</li> <li>Use the Swagger UI to call a smart contract function that emits an event. Verify that the event is received in the Sandbox and shows up in the FireFly Explorer.</li> </ul>"},{"location":"gettingstarted/sandbox/#go-forth-and-build","title":"Go forth and build!","text":"<p>At this point you should have a pretty good understanding of some of the major features of Hyperledger FireFly. Now, using what you've learned, you can go and build your own Web3 app! Don't forget to join the Hyperledger Discord server and come chat with us in the #firefly channel.</p>"},{"location":"gettingstarted/setup_env/","title":"Start your environment","text":""},{"location":"gettingstarted/setup_env/#previous-steps-install-the-firefly-cli","title":"Previous steps: Install the FireFly CLI","text":"<p>If you haven't set up the FireFly CLI already, please go back to the previous step and read the guide on how to Install the FireFly CLI.</p> <p>\u2190 \u2460 Install the FireFly CLI</p> <p>Now that you have the FireFly CLI installed, you are ready to run some Supernodes on your machine!</p>"},{"location":"gettingstarted/setup_env/#a-firefly-stack","title":"A FireFly Stack","text":"<p>A FireFly stack is a collection of Supernodes with networking and configuration that are designed to work together on a single development machine. A stack has multiple members (also referred to organizations). Each member has their own Supernode within the stack. This allows developers to build and test data flows with a mix of public and private data between various parties, all within a single development environment.</p> <p></p> <p>The stack also contains an instance of the FireFly Sandbox for each member. This is an example of an end-user application that uses FireFly's API. It has a backend and a frontend which are designed to walk developers through the features of FireFly, and provides code snippets as examples of how to build those features into their own application. The next section in this guide will walk you through using the Sandbox.</p>"},{"location":"gettingstarted/setup_env/#system-resources","title":"System Resources","text":"<p>The FireFly stack will run in a <code>docker-compose</code> project. For systems that run Docker containers inside a virtual machine, like macOS, you need to make sure that you've allocated enough memory to the Docker virtual machine. We recommend allocating 1GB per member. In this case, we're going to set up a stack with 3 members, so please make sure you have at least 3 GB of RAM allocated in your Docker Desktop settings.</p> <p></p>"},{"location":"gettingstarted/setup_env/#creating-a-new-stack","title":"Creating a new stack","text":"<p>It's really easy to create a new FireFly stack. The <code>ff init</code> command can create a new stack for you, and will prompt you for a few details such as the name, and how many members you want in your stack.</p> <p>To create an Ethereum based stack, run:</p> <pre><code>ff init ethereum\n</code></pre> <p>To create an Fabric based stack, run:</p> <pre><code>ff init fabric\n</code></pre> <p>Choose a stack name. For this guide, I will choose the name <code>dev</code>, but you can pick whatever you want:</p> <pre><code>stack name: dev\n</code></pre> <p>Chose the number of members for your stack. For this guide, we should pick <code>3</code> members, so we can try out both public and private messaging use cases:</p> <pre><code>number of members: 3\n</code></pre> <p></p>"},{"location":"gettingstarted/setup_env/#stack-initialization-options","title":"Stack initialization options","text":"<p>There are quite a few options that you can choose from when creating a new stack. For now, we'll just stick with the defaults. To see the full list of Ethereum options, just run <code>ff init ethereum --help</code> or to see the full list of Fabric options run <code>ff init fabric --help</code></p> <pre><code>ff init ethereum --help\nCreate a new FireFly local dev stack using an Ethereum blockchain\n\nUsage:\n  ff init ethereum [stack_name] [member_count] [flags]\n\nFlags:\n      --block-period int              Block period in seconds. Default is variable based on selected blockchain provider. (default -1)\n  -c, --blockchain-connector string   Blockchain connector to use. Options are: [evmconnect ethconnect] (default \"evmconnect\")\n  -n, --blockchain-node string        Blockchain node type to use. Options are: [geth besu remote-rpc] (default \"geth\")\n      --chain-id int                  The chain ID - also used as the network ID (default 2021)\n      --contract-address string       Do not automatically deploy a contract, instead use a pre-configured address\n  -h, --help                          help for ethereum\n      --remote-node-url string        For cases where the node is pre-existing and running remotely\n\nGlobal Flags:\n      --ansi string                   control when to print ANSI control characters (\"never\"|\"always\"|\"auto\") (default \"auto\")\n      --channel string                Select the FireFly release channel to use. Options are: [stable head alpha beta rc] (default \"stable\")\n      --connector-config string       The path to a yaml file containing extra config for the blockchain connector\n      --core-config string            The path to a yaml file containing extra config for FireFly Core\n  -d, --database string               Database type to use. Options are: [sqlite3 postgres] (default \"sqlite3\")\n  -e, --external int                  Manage a number of FireFly core processes outside of the docker-compose stack - useful for development and debugging\n  -p, --firefly-base-port int         Mapped port base of FireFly core API (1 added for each member) (default 5000)\n      --ipfs-mode string              Set the mode in which IFPS operates. Options are: [private public] (default \"private\")\n  -m, --manifest string               Path to a manifest.json file containing the versions of each FireFly microservice to use. Overrides the --release flag.\n      --multiparty                    Enable or disable multiparty mode (default true)\n      --node-name stringArray         Node name\n      --org-name stringArray          Organization name\n      --prometheus-enabled            Enables Prometheus metrics exposition and aggregation to a shared Prometheus server\n      --prometheus-port int           Port for the shared Prometheus server (default 9090)\n      --prompt-names                  Prompt for org and node names instead of using the defaults\n  -r, --release string                Select the FireFly release version to use. Options are: [stable head alpha beta rc] (default \"latest\")\n      --request-timeout int           Custom request timeout (in seconds) - useful for registration to public chains\n      --sandbox-enabled               Enables the FireFly Sandbox to be started with your FireFly stack (default true)\n  -s, --services-base-port int        Mapped port base of services (100 added for each member) (default 5100)\n  -t, --token-providers stringArray   Token providers to use. Options are: [none erc1155 erc20_erc721] (default [erc20_erc721])\n  -v, --verbose                       verbose log output\n</code></pre>"},{"location":"gettingstarted/setup_env/#start-your-stack","title":"Start your stack","text":"<p>To start your stack simply run:</p> <pre><code>ff start dev\n</code></pre> <p>This may take a minute or two and in the background the FireFly CLI will do the following for you:</p> <ul> <li>Download Docker images for all of the components of the Supernode</li> <li>Initialize a new blockchain and blockchain node running inside a container</li> <li>Set up configuration between all the components</li> <li>Deploy FireFly's <code>BatchPin</code> smart contract</li> <li>Deploy an <code>ERC-1155</code> token smart contract</li> <li>Register an identity for each member and node</li> </ul> <p>NOTE: For macOS users, the default port (5000) is already in-use by <code>ControlCe</code> service (AirPlay Receiver). You can either disable this service in your environment, or use a different port when creating your stack (e.g. <code>ff init dev -p 8000</code>)</p> <p>After your stack finishes starting it will print out the links to each member's UI and the Sandbox for that node:</p> <pre><code>ff start dev\nthis will take a few seconds longer since this is the first time you're running this stack...\ndone\n\nWeb UI for member '0': http://127.0.0.1:5000/ui\nSandbox UI for member '0': http://127.0.0.1:5109\n\nWeb UI for member '1': http://127.0.0.1:5001/ui\nSandbox UI for member '1': http://127.0.0.1:5209\n\nWeb UI for member '2': http://127.0.0.1:5002/ui\nSandbox UI for member '2': http://127.0.0.1:5309\n\n\nTo see logs for your stack run:\n\nff logs dev\n</code></pre>"},{"location":"gettingstarted/setup_env/#next-steps-use-in-the-sandbox","title":"Next steps: Use in the Sandbox","text":"<p>Now that you have some Supernodes running, it's time to start playing: in the Sandbox!</p> <p>\u2462 Use the Sandbox \u2192</p>"},{"location":"overview/gateway_features/","title":"Web3 Gateway Features","text":"<p>Web3 Gateway features allow 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.</p> <p></p>"},{"location":"overview/gateway_features/#transfer-tokenized-value","title":"Transfer tokenized value","text":"<p>The Digital Asset Features allow you to connect to token economies, in multiple blockchains, using the same infrastructure and signing keys.</p> <p>The complexities of how each token works, and how each blockchain works, are abstracted away from you by the Hyperledger FireFly Connector Framework.</p> <p>All of the layers of plumbing required to execute a transaction exactly once on a blockchain, and tracking it through to completion, are part of the stack. Deploy and configure them once in your Web3 gateway, and use them for multiple use cases in your enterprise.</p>"},{"location":"overview/gateway_features/#invoke-any-other-type-of-smart-contract","title":"Invoke any other type of smart contract","text":"<p>The API Generation features of Hyperledger FireFly, allow you to generate a convenient and reliable REST API for any smart contract logic.</p> <p>Then you just invoke that contract like you would any other API, with all the features you would expect like an OpenAPI 3.0 specification for the API, and UI explorer.</p> <p>The same reliable transaction submission framework is used as for token transfers, and you can use Hyperledger FireFly as a high volume staging post for those transactions.</p> <ul> <li>Handles peaks in workload, drip-feeding transactions onto the chain</li> <li>Handles large batch submissions, tracking</li> <li>Manages nonce assignment at high volume</li> <li>Idempotent APIs assuring that business transactions are submitted exactly once</li> </ul> <p>For EVM based chains, these features were significantly enhanced in the new EVMConnect connector introduced in v1.1 of FireFly (superseding EthConnect).</p>"},{"location":"overview/gateway_features/#index-data-from-the-blockchain","title":"Index data from the blockchain","text":"<p>Blockchain nodes are not designed for efficient querying of historical information. Instead their core function is to provide an ordered ledger of actions+events, along with a consistent world state at any point in time.</p> <p>This means that almost all user experiences and business APIs need a separate data store, that provides an fast indexed view of the history and current state of the chain.</p> <p>As an example, you've probably looked at a Block Explorer for a public blockchain on the web. Well, you weren't looking directly at the blockchain node. You were querying an off-chain indexed database, of all the blocks and transactions on that chain. An indexer behind the scenes was listening to the blockchain and synchronizing the off-chain state.</p> <p>Hyperledger FireFly has a built-in indexer for tokens, that maps every token mint/burn/transfer/approve operation that happens on the the blockchain into the database for fast query. You just specify which tokens you're interested in, and FireFly takes care of the rest.</p> <p>Additionally, FireFly does the heavy lifting part of indexing for all other types of smart contract event that might occur. It scrapes the blockchain for the events, formats them into easy to consume JSON, and reliably delivers them to your application.</p> <p>So your application just needs a small bit of code to take those payloads, and insert them into the database with the right database indexes you need to query your data by.</p>"},{"location":"overview/gateway_features/#reliably-trigger-events-in-your-applications","title":"Reliably trigger events in your applications","text":"<p>One of the most important universal rules about Web3 applications, is that they are event-driven.</p> <p>No one party in the system can chose to change the state, instead they must submit transactions that get ordered against everyone else's transactions, and only once confirmed through the consensus algorithm are they actioned.</p> <p>This means the integration into your application and core systems needs to be event-driven too.</p> <p>The same features that support reliable indexing of the blockchain data, allow reliable triggering of application code, business workflows, and core system integrations.</p> <p>Learn more about the FireFly Event Bus</p>"},{"location":"overview/gateway_features/#manage-decentralized-data-nfts-etc","title":"Manage decentralized data (NFTs etc.)","text":"<p>Your blockchain transactions are likely to refer to data that is stored off-chain.</p> <p>One common example is non-fungible-token (NFT) metadata, images and documents. These are not a good fit for storing directly in any blockchain ledger, so complimentary decentralized technologies like the InterPlanetary File System (IPFS) are used to make the data widely available and resilient outside of the blockchain itself.</p> <p>As a publisher or consumer of such metadata from decentralized storage, you need to be confident you have your own copy safe. So just like with the blockchain data, Hyperledger FireFly can act as a staging post for this data.</p> <p>Structured JSON data can be stored, uploaded and downloaded from the FireFly database.</p> <p>Large image/document/video payloads are handled by the pluggable Data Exchange microservice, which allows you to attach local or cloud storage to manage your copy of the data.</p> <p>FireFly then provides a standardized API to allow publishing of this data. So configuring a reliable gateway to the decentralized storage tier can be done once, and then accessed from your applications via a single Web3 Gateway.</p>"},{"location":"overview/gateway_features/#maintain-a-private-address-book","title":"Maintain a private address book","text":"<p>You need to manage your signing keys, and know the signing keys of others you are transacting with. A blockchain address like <code>0x0742e81393ee79C768e84cF57F1bF314F0f31ECe</code> is not very helpful for this.</p> <p>So Hyperledger FireFly provides a pluggable identity system, built on the foundation of the Decentralized IDentifier (DID). When in Web3 Gateway Mode these identities are not shared or published, and simply provide you a local address book.</p> <p>You can associate profile information with the identities, for example correlating them to the identifiers in your own core systems - such as an Identity and Access Management (IAM) system, or Know Your Customer (KYC) database.</p> <p>Learn more about Hyperledger FireFly Identities</p>"},{"location":"overview/public_vs_permissioned/","title":"Public and Permissioned Blockchain","text":""},{"location":"overview/public_vs_permissioned/#public-and-permissioned-blockchains","title":"Public and Permissioned Blockchains","text":"<p>A separate choice to the technology for your blockchain, is what combination of blockchain ecosystems you will integrate with.</p> <p>There are a huge variety of options, and increasingly you might find yourself integrating with multiple ecosystems in your solutions.</p> <p>A rough (and incomplete) high level classification of the blockchains available is as follows:</p> <ul> <li>Layer 1 public blockchains</li> <li>This is where most token ecosystems are rooted</li> <li>Layer 2 public scaling solutions backed by a Layer 1 blockchain</li> <li>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)</li> <li>Permissioned side-chains</li> <li>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</li> <li>These might have their state check-pointed/rolled-up to a Layer 2 or Layer 1 chain</li> </ul> <p>The lines are blurring between these categorizations as the technologies and ecosystems evolve.</p>"},{"location":"overview/public_vs_permissioned/#public-blockchain-variations","title":"Public blockchain variations","text":"<p>For the public Layer 1 and 2 solutions, there are too many subclassifications to go into in detail here:</p> <ul> <li>Whether ecosystems supports custom smart contract execution (EVM based is most common, where contracts are supported)</li> <li>What types of token standards are supported, or other chain specific embedded smart contracts</li> <li>Whether the chain follows an unspent transaction output (UTXO) or Account model</li> <li>How value is bridged in-to / out-of the ecosystem</li> <li>How the validator set of the chain is established - most common is Proof of Stake (PoS)</li> <li>How data availability is maintained - to check the working of the validators ensure the historical state is not lost</li> <li>The consensus algorithm, and how it interacts with the consensus of other blockchains</li> <li>How state in a Layer 2 is provable in a parent Layer 1 chain (rollup technologies etc.)</li> </ul>"},{"location":"overview/public_vs_permissioned/#common-public-considerations","title":"Common public considerations","text":"<p>The thing most consistent across public blockchain technologies, is that the technical decisions are backed by token economics.</p> <p>Put simply, creating a system where it's more financially rewarding to behave honestly, than it is to subvert and cheat the system.</p> <p>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.</p> <p>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.</p>"},{"location":"overview/public_vs_permissioned/#firefly-architecture-for-public-chains","title":"FireFly architecture for public chains","text":"<p>One of the fastest evolving aspects of the Hyperledger FireFly ecosystem, is how it facilitates enterprises to participate in these.</p> <p></p> <p>The architecture is summarized as follows:</p> <ul> <li>New FireFly Transaction Manager runtime</li> <li>Operates as a microservice extension of the FireFly Core</li> <li>Uses the <code>operation</code> resource within FireFly Core to store and update state</li> <li>Runs as a singleton and is responsible for <code>nonce</code> assignment</li> <li>Takes as much heavy lifting away from blockchain specific connectors as possible</li> <li>Lightweight FireFly Connector API (<code>ffcapi</code>)</li> <li>Simple synchronous RPC operations that map to the most common operations supported across public blockchain technologies</li> <li>Examples:<ul> <li>Find the next nonce for a given signing key</li> <li>Serialize a transaction from a set of JSON inputs and an interface definition</li> <li>Submit an un-signed transaction with a given gas price to the blockchain, via a signing wallet</li> <li>Establish a new block listener</li> <li>Poll for new blocks</li> <li>Establish a new event log listener</li> <li>Poll for new events</li> </ul> </li> <li>Pluggable Policy Engine</li> <li>Invoked to make decisions on transaction submission</li> <li>Responsible for gas price calculation</li> <li>Able to intervene and adjust the characteristics of signing/submission</li> <li>OSS reference implementation provided with Gas Station REST API integration</li> <li>Confirmation Manager</li> <li>Extracted from the Ethconnect codebase</li> <li>Coupled to both transaction submission and event confirmation</li> <li>Embeds an efficient block cache</li> <li>Event Streams</li> <li>Extracted from the Ethconnect codebase</li> <li>Checkpoint restart based reliable at-least-once delivery of events</li> <li>WebSockets interface upstream to FireFly Core</li> </ul> <p>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, and cumulated in the creation of a new repository in 2022.</p> <p>You can follow the progress and contribute in this repo: https://github.com/hyperledger/firefly-transaction-manager</p>"},{"location":"overview/supernode_concept/","title":"Introduction to Hyperledger FireFly","text":""},{"location":"overview/supernode_concept/#your-gateway-to-web3-technologies","title":"Your Gateway to Web3 Technologies","text":"<p>Hyperledger FireFly is an organization's gateway to Web3, including all the blockchain ecosystems that they participate in.</p> <p>Multiple blockchains, multiple token economies, and multiple business networks.</p> <p>FireFly is not another blockchain implementation, rather it is a pluggable API Orchestration and Data layer, integrating into all of the different types of decentralized technologies that exist in Web3:</p> <ul> <li>Public Blockchains, Layer 2 scaling solutions, Side chains, and App chains</li> <li>Permissioned Blockchains and Distributed Ledger Technologies (DLTs)</li> <li>Decentralized storage solutions</li> <li>Token ecosystems and standards</li> <li>Smart Contracts, DeFi solutions and DAOs</li> <li>Private off-chain encrypted communication rails</li> <li>Advanced cryptography solutions</li> <li>Identity frameworks</li> </ul>"},{"location":"overview/supernode_concept/#an-open-source-supernode-for-web3-apps","title":"An Open Source Supernode for Web3 Apps","text":"<p>Hyperledger FireFly is a toolkit for building and connecting new full-stack decentralized applications (dapps), as well as integrating your existing core systems to the world of Web3.</p> <p>It has a runtime engine, and it provides a data layer that synchronizes state from the blockchain and other Web3 technologies. It exposes an API and Event Bus to your business logic, that is reliable, developer friendly and ready for enterprise use.</p> <p>We call this a Supernode - it sits between the application and the underlying infrastructure nodes, providing layers of additional function.</p> <p></p> <p>The concept of a Supernode has evolved over the last decade of enterprise blockchain projects, as developers realized that they need much more than a blockchain node for their projects to be successful.</p> <p>Without a technology like Hyperledger FireFly, the application layer becomes extremely complex and fragile. Tens of thousands of lines of complex low-level \"plumbing\" / \"middleware\" code is required to integrate the web3 infrastructure into the application. This code provides zero unique business value to the solution, but can consume a huge proportion of the engineering budget and maintenance cost if built bespoke within a solution.</p>"},{"location":"overview/usage_patterns/","title":"Usage Patterns","text":"<p>There are two modes of usage for Hyperledger Firefly: Web3 Gateway and Multiparty</p> <p>A single runtime can operate in both of these modes, using different namespaces.</p>"},{"location":"overview/usage_patterns/#web3-gateway-mode","title":"Web3 Gateway Mode","text":"<p>Web3 Gateway mode lets you interact with any Web3 application, regardless of whether Hyperledger FireFly is being used by other members of your business network.</p> <p>In this mode you can:</p> <ul> <li>Transfer tokenized value</li> <li>Invoke any other type of smart contract</li> <li>Index data from the blockchain</li> <li>Reliably trigger events in your applications and back-office core systems</li> <li>Manage decentralized data (NFTs etc.)</li> <li>Use a private address book to manage signing identities and relationships</li> <li>... and much more</li> </ul> <p>Learn more about Web3 Gateway Mode.</p>"},{"location":"overview/usage_patterns/#multiparty-mode","title":"Multiparty Mode","text":"<p>Multiparty mode is used to build multi-party systems, with a common application runtime deployed by each enterprise participant.</p> <p></p> <p>This allows sophisticated applications to be built, that all use the pluggable APIs of Hyperledger FireFly to achieve end-to-end business value in an enterprise context.</p> <p>In this mode you can do everything you could do in Web3 Gateway mode, plus:</p> <ul> <li>Share and enforce common data formats</li> <li>Exchange data privately, via an encrypted data bus</li> <li>Structured JSON data payloads</li> <li>Large documents</li> <li>Coordinate on-chain and off-chain data exchange</li> <li>Private data</li> <li>Broadcast data</li> <li>Mask on-chain activities using hashes</li> <li>Use a shared address book to manage signing identities and relationships</li> <li>... and much more</li> </ul> <p>Learn more about Multiparty Mode.</p>"},{"location":"overview/key_components/","title":"Key Features","text":"<p>Hyperledger FireFly provides a rich suite of features for building new applications, and connecting existing Web3 ecosystems to your business. In this section we introduce each core pillar of functionality.</p>"},{"location":"overview/key_components/apps/","title":"Apps","text":""},{"location":"overview/key_components/apps/#apps","title":"Apps","text":"<p>Rapidly accelerating development of applications is a key feature of Hyperledger FireFly.</p> <p>The toolkit is designed to support the full-stack of applications in the enterprise Web3 ecosystem, not just the Smart Contract layer.</p> <p>Business logic APIs, back-office system integrations, and web/mobile user experiences are just as important to the overall Web3 use case.</p> <p>These layers require a different developer skill-set to the on-chain Smart Contracts, and those developers must have the tools they need to work efficiently.</p>"},{"location":"overview/key_components/apps/#api-gateway","title":"API Gateway","text":"<p>FireFly provides APIs that:</p> <ul> <li>Are fast and efficient</li> <li>Have rich query support</li> <li>Give deterministic outcomes and clear instructions for safe use</li> <li>Integrate with your security frameworks like OAuth 2.0 / OpenID Connect single sign-on</li> <li>Provide Open API 3 / Swagger definitions</li> <li>Come with code SDKs, with rich type information</li> <li>Conform as closely as possible to the principles of REST</li> <li>Do not pretend to be RESTful in cases when it is impossible to be</li> </ul> <p>Learn more about deploying APIs for custom smart contracts in this tutorial</p>"},{"location":"overview/key_components/apps/#event-streams","title":"Event Streams","text":"<p>The reality is that the only programming paradigm that works for a decentralized solutions, is an event-driven one.</p> <p>All blockchain technologies are for this reason event-driven programming interfaces at their core.</p> <p>In an overall solution, those on-chain events must be coordinated with off-chain private data transfers, and existing core-systems / human workflows.</p> <p>This means great event support is a must:</p> <ul> <li>Convenient WebSocket APIs that work for your microservices development stack</li> <li>Support for Webhooks to integrated serverless functions</li> <li>Integration with your core enterprise message queue (MQ) or enterprise service bus (ESB)</li> <li>At-least-once delivery assurance, with simple instructions at the application layer</li> </ul> <p>Learn all about the Hyperledger FireFly Event Bus, and event-driven application architecture, in this reference section</p>"},{"location":"overview/key_components/apps/#api-generation","title":"API Generation","text":"<p>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.</p> <p>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.</p> <p>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.</p> <p>Well documented APIs are the modern norm for this, and it is no different for blockchain.</p> <p>This means Hyperledger FireFly provides:</p> <ul> <li>Generating the interface for methods and events on your smart contract</li> <li>Providing robust transaction submission, and event streaming</li> <li>Publishing the API, version, and location, of your smart contracts to the network</li> </ul>"},{"location":"overview/key_components/connectors/","title":"Connector Framework","text":""},{"location":"overview/key_components/connectors/#pluggable-microservices-architecture","title":"Pluggable Microservices Architecture","text":"<p>The ability for every component to be pluggable is at the core of Hyperledger FireFly.</p> <p>A microservices approach is used, combining code plug-points in the core runtime, with API extensibility to remote runtimes implemented in a variety of programming languages.</p> <p></p>"},{"location":"overview/key_components/connectors/#extension-points","title":"Extension points","text":"<ul> <li>Blockchain - a rich framework for extensibility to any blockchain / digital ledger technology (DLT)</li> <li>Tokens - mapping token standards and governance models to a common data model</li> <li>Shared storage - supporting permissioned and public distributed storage technologies</li> <li>Data exchange - private local/storage and encrypted transfer of data</li> <li>Identity - flexibility for resolving identities via Decentralized IDentifier (DID)</li> <li>Persistence - the local private database</li> </ul> <p>Learn more about the plugin architecture here</p>"},{"location":"overview/key_components/connectors/#blockchain-connector-framework","title":"Blockchain Connector Framework","text":"<p>The most advanced extension point is for the blockchain layer, where multiple layers of extensibility are provided to support the programming models, and behaviors of different blockchain technologies.</p> <p>This framework has been proven with technologies as different as EVM based Layer 2 Ethereum Scaling solutions like Polygon, all the way to permissioned Hyperledger Fabric networks.</p> <p>Check out instructions to connect to a list of remote blockchain networks here.</p> <p></p> <p>Find out more about the Blockchain Connector Framework here.</p>"},{"location":"overview/key_components/digital_assets/","title":"Digital Assets","text":""},{"location":"overview/key_components/digital_assets/#digital-asset-features","title":"Digital asset features","text":"<p>The modelling, transfer and management of digital assets is the core programming foundation of blockchain.</p> <p>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.</p>"},{"location":"overview/key_components/digital_assets/#token-api","title":"Token API","text":"<p>Token standards have been evolving in the industry through standards like ERC-20/ERC-721, and the Web3 signing wallets that support these.</p> <p>Hyperledger FireFly bring this same standardization to the application tier. Providing APIs that work across token standards, and blockchain implementations, providing consistent and interoperable support.</p> <p>This means one application or set of back-end systems, can integrate with multiple blockchains, and different token implementations.</p> <p>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.</p> <p>Learn more about token standards for fungible tokens, and non-fungible tokens (NFTs) in this set of tutorials</p>"},{"location":"overview/key_components/digital_assets/#transfer-history-audit-trail","title":"Transfer history / audit trail","text":"<p>For efficiency blockchains do not provide a direct ability to query historical transaction information.</p> <p>Depending on the blockchain technology, even the current balance of your wallet can be complex to calculate - particularly for blockchain technologies based on an Unspent Transaction Output (UTXO) model.</p> <p>So off-chain indexing of transaction history is an absolute must-have for any digital asset solution.</p> <p>Hyperledger FireFly provides:</p> <ul> <li>Automatic indexing of tokens, whether existing or newly deployed</li> <li>Off-chain indexing of fungible and non-fungible asset transfers &amp; balances</li> <li>Off-chain indexing of approvals</li> <li>Integration with digital identity</li> <li>Full extensibility across both token standards and blockchain technologies</li> </ul>"},{"location":"overview/key_components/digital_assets/#wallets","title":"Wallets","text":"<p>Wallet and signing-key management is a critical requirement for any blockchain solution, particularly those involving the transfer of digital assets between wallets.</p> <p>Hyperledger FireFly provides you the ability to:</p> <ul> <li>Integrate multiple different signing/custody solutions in a proven way</li> <li>Manage the mapping of off-chain identities to on-chain signing identities</li> <li>Provide a plug-point for policy-based decision making on high value transactions</li> <li>Manage connections to multiple different blockchain solutions</li> </ul>"},{"location":"overview/key_components/flows/","title":"Flows","text":""},{"location":"overview/key_components/flows/#data-flow","title":"Data flow","text":"<p>The reality of most Web3 scenarios is that only a small part of the overall use-case can be represented inside the blockchain or distributed ledger technology.</p> <p>Some additional data flow is always required. This does not diminish the value of executing the kernel of the logic within the blockchain itself.</p> <p>Hyperledger FireFly embraces this reality, and allows an organization to keep track of the relationship between the off-chain data flow, and the on-chain transactions.</p> <p>Let's look at a few common examples:</p>"},{"location":"overview/key_components/flows/#digital-asset-transfers","title":"Digital Asset Transfers","text":"<p>Examples of common data flows performed off-chain, include Know Your Customer (KYC) and Anti Money Laundering (AML) checks that need to be performed and validated before participating in transactions.</p> <p>There might also be document management and business transaction flows required to verify the conditions are correct to digitally settle a transaction. Have the goods been delivered? Are the contracts in place?</p> <p>In regulated enterprise scenarios it is common to see a 10-to-1 difference in the number of steps performed off-chain to complete a business transaction, vs. the number of steps performed on-chain.</p> <p>These off-chain data flows might be coordinated with on-chain smart contracts that lock assets in digital escrow until the off-chain steps are completed by each party, and protect each party while the steps are being completed.</p> <p>A common form of digital escrow is a Hashed Timelock Contract (HTLC).</p>"},{"location":"overview/key_components/flows/#non-fungible-tokens-nfts-and-hash-pinning","title":"Non-fungible Tokens (NFTs) and hash-pinning","text":"<p>The data associated with an NFT might be as simple as a JSON document pointing at an interesting piece of artwork, or as complex a set of high resolution scans / authenticity documents representing a digital twin of a real world object.</p> <p>Here the concept of a hash pinning is used - allowing anyone who has a copy of the original data to recreate the hash that is stored in the on-chain record.</p> <p>With even the simplest NFT the business data is not stored on-chain, so simple data flow is always required to publish/download the off-chain data.</p> <p>The data might be published publicly for anyone to download, or it might be sensitive and require a detailed permissioning flow to obtain it from a current holder of that data.</p>"},{"location":"overview/key_components/flows/#dynamic-nfts-and-business-transaction-flow","title":"Dynamic NFTs and Business Transaction Flow","text":"<p>In an enterprise context, an NFT might have a dynamic ever-evolving trail of business transaction data associated with it. Different parties might have different views of that business data, based on their participation in the business transactions associated with it.</p> <p>Here the NFT becomes a like a foreign key integrated across the core systems of a set of enterprises working together in a set of business transactions.</p> <p>The data itself needs to be downloaded, retained, processed and rendered. Probably integrated to systems, acted upon, and used in multiple exchanges between companies on different blockchains, or off-chain.</p> <p>The business process is accelerated through this Enterprise NFT on the blockchain - as all parties have matched or bound their own private data store to that NFT. This means they are confident to be executing a business transaction against the same person or thing in the world.</p>"},{"location":"overview/key_components/flows/#data-and-transaction-flow-patterns","title":"Data and Transaction Flow patterns","text":"<p>Hyperledger FireFly provides the raw tools for building data and transaction flow patterns, such as storing, hashing and transferring data. It provides the event bus to trigger off-chain applications and integration to participate in the flows.</p> <p>It also provides the higher level flow capabilities that are needed for multiple parties to build sophisticated transaction flows together, massively simplifying the application logic required:</p> <ul> <li>Coordinating the transfer of data off-chain with a blockchain sequencing transaction</li> <li>Batching for high throughput transfer via the blockchain and distributed storage technologies</li> <li>Managing privacy groups between parties involved in a business transaction</li> <li>Masking the relationship between blockchain transactions, for sensitive data</li> </ul> <p></p> <p>Learn more in Multiparty Process Flows</p>"},{"location":"overview/key_components/orchestration_engine/","title":"Orchestration Engine","text":""},{"location":"overview/key_components/orchestration_engine/#firefly-core","title":"FireFly Core","text":"<p>At the core of Hyperledger FireFly is an event-driven engine that routes, indexed, aggregates, and sequences data to and from the blockchain, and other connectors.</p> <p></p>"},{"location":"overview/key_components/orchestration_engine/#data-layer","title":"Data Layer","text":"<p>Your own private view of the each network you connect:</p> <ul> <li>Indexes of all tokens and NFTs that you transact with</li> <li>A consistent view across multiple blockchains</li> <li>High performance rich query of transaction and data audit trail</li> <li>Private data you have received from other parties</li> <li>Local copies of data you have download from IPFS or other shared storage tech</li> </ul>"},{"location":"overview/key_components/orchestration_engine/#event-bus","title":"Event Bus","text":"<p>Whether a few dozen companies in a private blockchain consortium, or millions of users connected to a public blockchain network - one thing is always true:</p> <p>Decentralized applications are event-driven.</p> <p>In an enterprise context, you need to think not only about how those events are being handled and made consistent within the blockchain layer, but also how those events are being processed and integrated to your core systems.</p> <p>FireFly provides you with the reliable streams of events you need, as well as the interfaces to subscribe to those events and integrate them into your core systems.</p> <ul> <li>Token transfer events, across multiple blockchains, and varied asset types</li> <li>Custom smart contract events</li> <li>Correlated on-chain and off-chain data events</li> </ul> <p></p> <p>Learn more about the event bus and event-driven programming in this reference document</p>"},{"location":"overview/key_components/security/","title":"Security","text":""},{"location":"overview/key_components/security/#api-security","title":"API Security","text":"<p>Hyperledger FireFly provides a pluggable infrastructure for authenticating API requests.</p> <p>Each namespace can be configured with a different authentication plugin, such that different teams can have different access to resources on the same FireFly server.</p> <p>A reference plugin implementation is provided for HTTP Basic Auth, combined with a <code>htpasswd</code> verification of passwords with a <code>bcrypt</code> encoding.</p> <p>See this config section for details, and the reference implementation in Github</p> <p>Pre-packaged vendor extensions to Hyperledger FireFly are known to be available, addressing more comprehensive role-based access control (RBAC) and JWT/OAuth based security models.</p>"},{"location":"overview/key_components/security/#data-partitioning-and-tenancy","title":"Data Partitioning and Tenancy","text":"<p>Namespaces also provide a data isolation system for different applications / teams / tenants sharing a Hyperledger FireFly node.</p> <p></p> <p>Data is partitioned within the FireFly database by namespace. It is also possible to increase the separation between namespaces, by using separate database configurations. For example to different databases or table spaces within a single database server, or even to different database servers.</p>"},{"location":"overview/key_components/security/#private-data-exchange","title":"Private Data Exchange","text":"<p>FireFly has a pluggable implementation of a private data transfer bus. This transport supports both structured data (conforming to agreed data formats), and large unstructured data &amp; documents.</p> <p></p> <p>A reference microservice implementation is provided for HTTPS point-to-point connectivity with mutual TLS encryption.</p> <p>See the reference implementation in Github</p> <p>Pre-packaged vendor extensions to Hyperledger FireFly are known to be available, addressing message queue based reliable delivery of messages, hub-and-spoke connectivity models, chunking of very large file payloads, and end-to-end encryption.</p> <p>Learn more about these private data flows in Multiparty Process Flows.</p>"},{"location":"overview/key_components/tools/","title":"Tools","text":""},{"location":"overview/key_components/tools/#firefly-cli","title":"FireFly CLI","text":"<p>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.</p>"},{"location":"overview/key_components/tools/#firefly-sandbox","title":"FireFly Sandbox","text":"<p>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.</p> <p>\ud83d\uddd2 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 to make requests to FireFly's API.</p>"},{"location":"overview/key_components/tools/#firefly-explorer","title":"FireFly Explorer","text":"<p>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.</p> <p></p>"},{"location":"overview/multiparty/","title":"Enterprise multi-party systems","text":""},{"location":"overview/multiparty/#introduction","title":"Introduction","text":"<p>Multiparty mode has all the features in Gateway mode with the added benefit of multi-party process flows.</p> <p>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).</p> <p>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.</p> <p></p> <p>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.</p> <p>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 models can be created to enable secure collaboration in new ways, without compromising the integrity of an individual organization.</p> <p>The technology is most powerful in ecosystems of \"coopetition\", where privacy and security requirements are high. Multi-party systems establish new models of trust, with easy to prove outcomes that minimize the need for third party arbitration, and costly investigation into disputes.</p>"},{"location":"overview/multiparty/#points-of-difference","title":"Points of difference","text":"<p>Integration with existing systems of record is critical to unlock the potential of these new ecosystems. So multi-party systems embrace the existing investments of each party, rather than seeking to unify or replace them.</p> <p>Multi-party systems are different from centralized third-party systems, because each party retains sovereignty over:</p> <ul> <li>Their application instance</li> <li>Their private data</li> <li>Their business processes</li> <li>Their proprietary business logic</li> <li>Their internal business processes and IT controls</li> </ul>"},{"location":"overview/multiparty/#use-case-example","title":"Use Case Example","text":"<p>There are many multiparty use cases. An example for healthcare is detailed below.</p> <p>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.</p> <p>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 one healthcare provider and two 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.</p> <p>In a larger healthcare ecosystem with many members, a similar concept may emerge with multiple variations of members.</p>"},{"location":"overview/multiparty/broadcast/","title":"Broadcast / shared data","text":""},{"location":"overview/multiparty/broadcast/#introduction","title":"Introduction","text":"<p>Multi-party systems are about establishing a shared source of truth, and 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</p> <p></p>"},{"location":"overview/multiparty/broadcast/#blockchain-backed-broadcast","title":"Blockchain backed broadcast","text":"<p>In order to maintain a complete history of all broadcast data for new members joining the network, FireFly uses the blockchain to sequence the broadcasts with pinning transactions referring to the data itself.</p> <p>Using the blockchain also gives a global order of events for these broadcasts, which allows them to be processed by each member in a way that allows them to derive the same result - even though the processing logic on the events themselves is being performed independently by each member.</p> <p>For more information see Multiparty Event Sequencing.</p>"},{"location":"overview/multiparty/broadcast/#shared-data","title":"Shared data","text":"<p>The data included in broadcasts is not recorded on the blockchain. Instead a pluggable shared storage mechanism is used to contain the data itself. The on-chain transaction just contains a hash of the data that is stored off-chain.</p> <p>This is because the data itself might be too large to be efficiently stored and transferred via the blockchain itself, or subject to deletion at some point in the future through agreement by the members in the network.</p> <p>While the data should be reliably stored with visibility to all members of the network, the data can still be secured from leakage outside of the network.</p> <p>The InterPlanetary File System (IPFS) is an example of a distributed technology for peer-to-peer storage and distribution of such data in a decentralized multi-party system. It provides secure connectivity between a number of nodes, combined with a decentralized index of data that is available, and native use of hashes within the technology as the way to reference data by content.</p>"},{"location":"overview/multiparty/broadcast/#firefly-built-in-broadcasts","title":"FireFly built-in broadcasts","text":"<p>FireFly uses the broadcast mechanism internally to distribute key information to all parties in the network:</p> <ul> <li>Network map</li> <li>Organizational identities</li> <li>Nodes</li> <li>See Identities in the reference section for more information</li> <li>Datatype definitions</li> <li>See Datatype in the reference section for more information</li> <li>Namespaces</li> <li>See Namespaces for more information</li> </ul> <p>These definitions rely on the same assurances provided by blockchain backed broadcast that FireFly applications do.</p> <ul> <li>Verification of the identity of the party in the network that performed the broadcast</li> <li>Deterministic assignment of a namespace+name to an unique item of data</li> <li>If two parties in the network broadcast the same data at similar times, the     same one \"wins\" for all parties in the network (including the broadcaster)</li> </ul>"},{"location":"overview/multiparty/data_exchange/","title":"Private data exchange","text":""},{"location":"overview/multiparty/data_exchange/#introduction","title":"Introduction","text":"<p>Private data exchange is the way most enterprise business-to-business communication happens today. One party privately sends data to another, over a pipe that has been 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.</p> <p></p> <p>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 data continue to transfer over such interfaces.</p> <p>So real-time application to application private messaging, and private transfer of large blobs/documents, are first class constructs in the FireFly API.</p>"},{"location":"overview/multiparty/data_exchange/#qualities-of-service","title":"Qualities of service","text":"<p>FireFly recognizes that a multi-party system will need to establish a secure messaging backbone, with the right qualities of service for their requirements. So the implementation is pluggable, and the plugin interface embraces the following quality of service characteristics that differ between different implementations.</p> <ul> <li>Transport Encryption</li> <li>Technologies like TLS encrypt data while it is in flight, so that it cannot be     sniffed by a third party that has access to the underlying network.</li> <li>Authentication</li> <li>There are many technologies including Mutual TLS, and Java Web Tokens (JWT),     that can be used to ensure a private data exchange is happening with the     correct party in the system.</li> <li>Most modern approaches use public/private key encryption to establish the identity     during the setup phase of a connection. This means a distribution mechanism is required     for public keys, which might be enhanced with a trust hierarchy (like PKI).</li> <li>Request/Response (Sync) vs. Message Queuing (Async)</li> <li>Synchronous transports like HTTPS require both parties to be available at the     time data is sent, and the transmission must be retried at the application (plugin)     layer if it fails or times out.</li> <li>Asynchronous transports like AMQP, MQTT or Kafka introduce one or more broker runtimes     between the parties, that reliably buffer the communications if the target application     falls behind or is temporarily unavailable.</li> <li>Hub &amp; spoke vs. Peer to peer</li> <li>Connectivity might be direct from one party to another within the network, tackling     the IT security complexity of firewalls between sensitive networks. Or network shared     infrastructure / as-a-service provider might be used to provide a reliable backbone     for data exchange between the members.</li> <li>End-to-end Payload Encryption</li> <li>Particularly in cases where the networking hops are complex, or involve shared     shared/third-party infrastructure, end-to-end encryption can be used to additionally     protect the data while in flight. This technology means data remains encrypted     from the source to the target, regardless of the number of transport hops taken in-between.</li> <li>Large blob / Managed file transfer</li> <li>The optimal approach to transferring real-time small messages (KBs in size) is different     to the approach to transferring large blobs (MBs/GBs in size). For large blobs chunking,     compression, and checkpoint restart are common for efficient and reliable transfer.</li> </ul>"},{"location":"overview/multiparty/data_exchange/#firefly-oss-implementation","title":"FireFly OSS implementation","text":"<p>A reference implementation of a private data exchange is provided as part of the FireFly project. This implementation uses peer-to-peer transfer over a synchronous HTTPS transport, backed by Mutual TLS authentication. X509 certificate exchange is orchestrated by FireFly, such that self-signed certificates can be used (or multiple PKI trust roots) and bound to the blockchain-backed identities of the organizations in FireFly.</p> <p>See hyperledger/firefly-dataexchange-https</p>"},{"location":"overview/multiparty/deterministic/","title":"Deterministic Compute","text":""},{"location":"overview/multiparty/deterministic/#introduction","title":"Introduction","text":"<p>A critical aspect of designing a multi-party systems, is choosing where you exploit the blockchain and other advanced cryptography technology to automate agreement between parties.</p> <p>Specifically where you rely on the computation itself to come up with a result that all parties can independently trust. For example because all parties performed the same computation independently and came up with the same result, against the same data, and agreed to that result using a consensus algorithm.</p> <p>The more sophisticated the agreement is you want to prove, the more consideration needs to be taken into factors such as:</p> <ul> <li>Data privacy</li> <li>Data deletion</li> <li>Ease of understanding by business users</li> <li>Ease of audit</li> <li>Autonomy of parties with proprietary business logic</li> <li>Human workflows (obviously non-deterministic)</li> <li>Technology complexity/maturity (particularly for privacy preserving technologies)</li> <li>Cost and skills for implementation</li> </ul> <p>FireFly embraces the fact that different use cases, will make different decisions on how much of the agreement should be enforced through deterministic compute.</p> <p>Also that multi-party systems include a mixture of approaches in addition to deterministic compute, including traditional off-chain secure HTTP/Messaging, documents, private non-deterministic logic, and human workflows.</p>"},{"location":"overview/multiparty/deterministic/#the-fundamental-building-blocks","title":"The fundamental building blocks","text":"<p>There are some fundamental types of deterministic computation, that can be proved with mature blockchain technology, and all multi-party systems should consider exploiting:</p> <ul> <li>Total conservation of value</li> <li>Allows you to assign value to something, because you know it is a fraction of a total pool</li> <li>This is the magic behind fungible tokens, or \"coins\"</li> <li>The proven technology for this is a shared ledger of all previous transactions</li> <li>Learn more in the Tokens section</li> <li>Existence and ownership of a unique identifiable thing</li> <li>Gives you an anchor to attach to something in the real world</li> <li>This is the magic behind non-fungible tokens (NTFs)</li> <li>The proven technology for this is a shared ledger of its creation, and ownership changes</li> <li>Learn more in the Tokens section</li> <li>An agreed sequence of events</li> <li>The foundation tool that allows the building of higher level constructs (including tokens)</li> <li>Not previously available when business ecosystems used HTTP/Messaging transports alone</li> <li>Can be bi-lateral, multi-lateral or global</li> <li>Each blockchain technology has different features to establish these \"chains\" of information</li> <li>Different approaches provide privacy different levels of privacy on the parties and sequence</li> <li>Identification of data by a \"hash\" of its contents</li> <li>The glue that binds a piece of private data, to a proof that you have a copy of that data</li> <li>This is the basis of \"pinning\" data to the blockchain, without sharing its contents</li> <li>Care needs to be taken to make sure the data is unique enough to make the hash secure</li> <li>Learn more in the Gateway Features section</li> </ul>"},{"location":"overview/multiparty/deterministic/#advanced-cryptography-and-privacy-preserving-trusted-compute","title":"Advanced Cryptography and Privacy Preserving Trusted Compute","text":"<p>There are use cases where a deterministic agreement on computation is desired, but the data upon which the execution is performed cannot be shared between all the parties.</p> <p>For example proving total conservation of value in a token trading scenario, without knowing who is involved in the individual transactions. Or providing you have access to a piece of data, without disclosing what that data is.</p> <p>Technologies exist that can solve these requirements, with two major categories:</p> <ul> <li>Zero Knowledge Proofs (ZKPs)</li> <li>Advanced cryptography techniques that allow one party to generate a proof that can be     be verified by another party, without access to the data used to generate the proof.</li> <li>Trusted Compute Environments (TEEs)</li> <li>Secure compute environments that provide proofs of what code was executed, such that     other parties can be confident of the logic that was executed without having access to the data.</li> </ul> <p>FireFly today provides an orchestration engine that's helpful in coordinating the inputs, outputs, and execution of such advanced cryptography technologies.</p> <p>Active collaboration between the FireFly and other projects like Hyperledger Avalon, and Hyperledger Cactus, is evolving how these technologies can plug-in with higher level patterns.</p>"},{"location":"overview/multiparty/deterministic/#complementary-approaches-to-deterministic-computation","title":"Complementary approaches to deterministic computation","text":"<p>Enterprise multi-party systems usually operate differently to end-user decentralized applications. In particular, strong identity is established for the organizations that are involved, and those organizations usually sign legally binding commitments around their participation in the network. Those businesses then bring on-board an ecosystem of employees and or customers that are end-users to the system.</p> <p>So the shared source of truth empowered by the blockchain and other cryptography are not the only tools that can be used in the toolbox to ensure correct behavior. Recognizing that there are real legal entities involved, that are mature and regulated, does not undermine the value of the blockchain components. In fact it enhances it.</p> <p>A multi-party system can use just enough of this secret sauce in the right places, to change the dynamics of trust such that competitors in a market are willing to create value together that could never be created before.</p> <p>Or create a system where parties can share data with each other while still conforming to their own regulatory and audit commitments, that previously would have been impossible to share.</p> <p>Not to be overlooked is the sometimes astonishing efficiency increase that can be added to existing 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.</p>"},{"location":"overview/multiparty/multiparty_flow/","title":"Multiparty Process Flows","text":""},{"location":"overview/multiparty/multiparty_flow/#flow-features","title":"Flow features","text":"<p>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.</p>"},{"location":"overview/multiparty/multiparty_flow/#private-data-flow","title":"Private data flow","text":"<p>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.</p> <p>The number of enterprise solutions where all data can flow directly through the blockchain, is vanishingly small.</p> <p>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:</p> <ul> <li>Establishing the identity of participants so data can be shared</li> <li>Securing the transfer of data off-chain</li> <li>Coordinating off-chain data flow with on-chain data flow</li> <li>Managing sequence for deterministic outcomes for all parties</li> <li>Integrating off-chain private execution with multi-step stateful business logic</li> </ul>"},{"location":"overview/multiparty/multiparty_flow/#multi-party-business-process-flow","title":"Multi-party business process flow","text":"<p>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.</p> <p>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.</p> <p>So you need the platform to:</p> <ul> <li>Provide a robust event-driven programming model fitting a \"state machine\" approach</li> <li>Integrate with the decentralized application stack of each participant</li> <li>Allow integration with the core-systems and human decision making of each participant</li> <li>Provide deterministic ordering between all parties</li> <li>Provide identity assurance and proofs for data flow / transition logic</li> </ul>"},{"location":"overview/multiparty/multiparty_flow/#data-exchange","title":"Data exchange","text":"<p>Business processes need data, and that data comes in many shapes and sizes.</p> <p>The platform needs to handle all of them:</p> <ul> <li>Large files and documents, as well as application data</li> <li>Uniqueness / Enterprise NFTs - agreement on a single \"foreign key\" for a record</li> <li>Non-repudiation, and acknowledgement of receipt</li> <li>Coordination of flows of data, with flows of value - delivery vs. payment scenarios</li> </ul>"},{"location":"overview/multiparty/multiparty_flow/#building-multi-party-flows","title":"Building multi-party flows","text":"<p>The ability to globally sequence events across parties is a game changing capability of a multiparty system. FireFly is designed to allow developers to harnesses that power in the application layer, to build sophisticated multi-party APIs and user experiences.</p> <p></p> <ul> <li>Build multi-party business processes where there is one agreed outcome:</li> <li>Agree the trigger, inputs, outputs of each step in the process</li> <li>Agree any common \"rules of the road\" must be adhered to</li> <li>Look back at your shared history, when deciding to commit to the next step:</li> <li>Fast rich-query cache, backed by a private database</li> <li>Initiate the next step through automated or manual decision making</li> <li>Only consider a step final once it's multi-party sequence has been confirmed</li> <li>Gain big efficiencies in how multi-party business processes work:</li> <li>Once locked in, a step is consider final - attested to by the party</li> <li>If two parties submit conflicting actions, one wins, and one loses</li> <li>Avoids complex compensation logic in the business orchestration layer</li> <li>Provides one clear source of truth to quickly resolve multi-party disputes</li> <li>Program multi-party apps using the tools you know:</li> <li>REST APIs for triggering the next step in a process, and querying history</li> <li>WebSockets and Webhooks for events (pluggable to other event transports)</li> <li>Remember - each party runs their own copy of the app, with their own private data</li> <li>Allow each party to integrate into their existing core systems:</li> <li>Realtime or batch</li> <li>Human workflows</li> <li>Proprietary business logic that is unique to one party</li> <li>Avoid sensitive data written to the blockchain:</li> <li>Works in bi-lateral and multi-lateral scenarios</li> <li>Designed to limit leaking other \"metadata\" about the transaction as well</li> <li>Share partial history with different participants in a</li> <li>No requirement to write custom on-chain smart contract logic:</li> <li>Can be combined with rich custom on-chain logic as well</li> </ul>"},{"location":"overview/multiparty/multiparty_flow/#innovate-fast","title":"Innovate fast","text":"<p>Building a successful multi-party system is often about business experimentation, and business results. Proving the efficiency gains, and new business models, made possible by working together in a new way under a new system of trust.</p> <p>Things that can get in the way of that innovation, can include concerns over data privacy, technology maturity, and constraints on autonomy of an individual party in the system. An easy to explain position on how new technology components are used, where data lives, and how business process independence is maintained can really help parties make the leap of faith necessary to take the step towards a new model.</p> <p>Keys to success often include building great user experiences that help digitize clunky decades old manual processes. Also easy to integrate with APIs, what embrace the existing core systems of record that are establish within each party.</p>"},{"location":"overview/multiparty/multiparty_flow/#consider-the-on-chain-toolbox-too","title":"Consider the on-chain toolbox too","text":"<p>There is a huge amount of value that deterministic execution of multi-party logic within the blockchain can add. However, the more compute is made fully deterministic via a blockchain consensus algorithm validated by multiple parties beyond those with a business need for access to the data, the more sensitivity needs to be taken to data privacy. Also bear in mind any data that is used in this processing becomes immutable - it can never be deleted.</p> <p>The core constructs of blockchain are a great place to start. Almost every process can be enhanced with pre-built fungible and non-fungible tokens, for example. Maybe it's to build a token economy that enhances the value parties get from the system, or to encourage healthy participation (and discourage bad behavior). Or maybe it's to track exactly which party owns a document, asset, or action within a process using NFTs.</p> <p>On top of this you can add advanced tools like digital escrow, signature / threshold based voting on outcomes, and atomic swaps of value/ownership.</p> <p>The investment in building this bespoke on-chain logic is higher than building the off-chain pieces (and there are always some off-chain pieces as we've discussed), so it's about finding the kernel of value the blockchain can provide to differentiate your solution from a centralized database solution.</p> <p>The power provided by deterministic sequencing of events, attested by signatures, and pinned to private data might be sufficient for some cases. In others the token constructs are the key value that differentiates the decentralized ecosystem. Whatever it is, it's important it is identified and crafted carefully.</p> <p>Note that advanced privacy preserving techniques such as zero-knowledge proofs (ZKP) are gaining traction and hardening in their production readiness and efficiency. Expect these to play an increasing role in the technology stack of multiparty systems (and Hyperledger FireFly) in the future.</p> <p>Learn more in the Deterministic Compute section.</p>"},{"location":"reference/api_post_syntax/","title":"API POST Syntax","text":""},{"location":"reference/api_post_syntax/#syntax-overview","title":"Syntax Overview","text":"<p>Endpoints that allow submitting a transaction allow an optional query parameter called <code>confirm</code>. When <code>confirm=true</code> is set in the query string, FireFly will wait to send an HTTP response until the message has been confirmed. This means, where a blockchain transaction is involved, the HTTP request will not return until the blockchain transaction is complete.</p> <p>This is useful for endpoints such as registration, where the client app cannot proceed until the transaction is complete and the member/node is registered. Rather than making a request to register a member/node and then repeatedly polling the API to check to see if it succeeded, an HTTP client can use this query parameter and block until registration is complete.</p> <p>NOTE: This does not mean that any other member of the network has received, processed, or responded to the message. It just means that the transaction is complete from the perspective of the FireFly node to which the transaction was submitted.</p>"},{"location":"reference/api_post_syntax/#example-api-call","title":"Example API Call","text":"<p><code>POST</code> <code>/api/v1/messages/broadcast?confirm=true</code></p> <p>This will broadcast a message and wait for the message to be confirmed before returning.</p>"},{"location":"reference/api_query_syntax/","title":"API Query Syntax","text":""},{"location":"reference/api_query_syntax/#syntax-overview","title":"Syntax Overview","text":"<p>REST collections provide filter, <code>skip</code>, <code>limit</code> and <code>sort</code> support.</p> <ul> <li>The field in the message is used as the query parameter</li> <li>Syntax: <code>field=[modifiers][operator]match-string</code></li> <li>When multiple query parameters are supplied these are combined with AND</li> <li>When the same query parameter is supplied multiple times, these are combined with OR</li> </ul>"},{"location":"reference/api_query_syntax/#example-api-call","title":"Example API Call","text":"<p><code>GET</code> <code>/api/v1/messages?confirmed=&gt;0&amp;type=broadcast&amp;topic=t1&amp;topic=t2&amp;context=@someprefix&amp;sort=sequence&amp;descending&amp;skip=100&amp;limit=50</code></p> <p>This states:</p> <ul> <li>Filter on <code>confirmed</code> greater than 0</li> <li>Filter on <code>type</code> exactly equal to <code>broadcast</code></li> <li>Filter on <code>topic</code> exactly equal to <code>t1</code> or <code>t2</code></li> <li>Filter on <code>context</code> containing the case-sensitive string <code>someprefix</code></li> <li>Sort on <code>sequence</code> in <code>descending</code> order</li> <li>Paginate with <code>limit</code> of <code>50</code> and <code>skip</code> of <code>100</code> (e.g. get page 3, with 50/page)</li> </ul> <p>Table of filter operations, which must be the first character of the query string (after the <code>=</code> in the above URL path example)</p>"},{"location":"reference/api_query_syntax/#operators","title":"Operators","text":"<p>Operators are a type of comparison operation to perform against the match string.</p> Operator Description <code>=</code> Equal (none) Equal (shortcut) <code>@</code> Containing <code>^</code> Starts with <code>$</code> Ends with <code>&lt;&lt;</code> Less than <code>&lt;</code> Less than (shortcut) <code>&lt;=</code> Less than or equal <code>&gt;&gt;</code> Greater than <code>&gt;</code> Greater than (shortcut) <code>&gt;=</code> Greater than or equal <p>Shortcuts are only safe to use when your match string starts with <code>a-z</code>, <code>A-Z</code>, <code>0-9</code>, <code>-</code> or <code>_</code>.</p>"},{"location":"reference/api_query_syntax/#modifiers","title":"Modifiers","text":"<p>Modifiers can appear before the operator, to change its behavior.</p> Modifier Description <code>!</code> Not - negates the match <code>:</code> Case insensitive <code>?</code> Treat empty match string as null <code>[</code> Combine using <code>AND</code> on the same field <code>]</code> Combine using <code>OR</code> on the same field (default)"},{"location":"reference/api_query_syntax/#detailed-examples","title":"Detailed examples","text":"Example Description <code>cat</code> Equals \"cat\" <code>=cat</code> Equals \"cat\" (same) <code>!=cat</code> Not equal to \"cat\" <code>:=cat</code> Equal to \"CAT\", \"cat\", \"CaT etc. <code>!:cat</code> Not equal to \"CAT\", \"cat\", \"CaT etc. <code>=!cat</code> Equal to \"!cat\" (! is after operator) <code>^cats/</code> Starts with \"cats/\" <code>$_cat</code> Ends with with \"_cat\" <code>!:^cats/</code> Does not start with \"cats/\", \"CATs/\" etc. <code>!$-cat</code> Does not end with \"-cat\" <code>?=</code> Is null <code>!?=</code> Is not null"},{"location":"reference/api_query_syntax/#time-range-example","title":"Time range example","text":"<p>For this case we need to combine multiple queries on the same <code>created</code> field using AND semantics (with the <code>[</code>) modifier:</p> <pre><code>?created=[&gt;&gt;2021-01-01T00:00:00Z&amp;created=[&lt;=2021-01-02T00:00:00Z\n</code></pre> <p>So this means:</p> <ul> <li><code>created</code> greater than <code>2021-01-01T00:00:00Z</code></li> <li><code>AND</code></li> <li><code>created</code> less than or equal to <code>2021-01-02T00:00:00Z</code></li> </ul>"},{"location":"reference/blockchain_operation_errors/","title":"Blockchain Operation Errors","text":""},{"location":"reference/blockchain_operation_errors/#blockchain-error-messages","title":"Blockchain Error Messages","text":"<p>The receipt for a FireFly blockchain operation contains an <code>extraInfo</code> section that records additional information about the transaction. For example:</p> <pre><code>\"receipt\": {\n  ...\n  \"extraInfo\": [\n    {\n      {\n        \"contractAddress\":\"0x87ae94ab290932c4e6269648bb47c86978af4436\",\n        \"cumulativeGasUsed\":\"33812\",\n        \"from\":\"0x2b1c769ef5ad304a4889f2a07a6617cd935849ae\",\n        \"to\":\"0x302259069aaa5b10dc6f29a9a3f72a8e52837cc3\",\n        \"gasUsed\":\"33812\",\n        \"status\":\"0\",\n        \"errorMessage\":\"Not enough tokens\", \n      }\n    }\n  ],\n  ...\n},\n</code></pre> <p>The <code>errorMessage</code> field can be be set by a blockchain connector to provide FireFly and the end-user with more information about the reason why a tranasction failed. The blockchain connector can choose what information to include in <code>errorMessage</code> field. It may be set to an error message relating to the blockchain connector itself or an error message passed back from the blockchain or smart contract that was invoked.</p>"},{"location":"reference/blockchain_operation_errors/#default-error-format-with-hyperledger-firefly-13-and-hyperledger-besu-2430","title":"Default Error Format With Hyperledger FireFly 1.3 and Hyperledger Besu 24.3.0","text":"<p>If FireFly is configured to connect to a Besu EVM client, and Besu has been configured with the <code>revert-reason-enabled=true</code> setting (note - the default value for Besu is <code>false</code>) error messages passed to FireFly from the blockchain client itself will be set correctly in the FireFly blockchain operation. For example:</p> <ul> <li><code>\"errorMessage\":\"Not enough tokens\"</code> for a revert error string from a smart contract</li> </ul> <p>If the smart contract uses a custom error type, Besu will return the revert reason to FireFly as a hexadecimal string but FireFly will be unable to decode it into. In this case the blockchain operation error message and return values will be set to:</p> <ul> <li><code>\"errorMessage\":\"FF23053: Error return value for custom error: &lt;revert hex string&gt;</code></li> <li><code>\"returnValue\":\"&lt;revert hex string&gt;\"</code></li> </ul> <p>A future update to FireFly could be made to automatically decode custom error revert reasons if FireFly knows the ABI for the custom error. See FireFly issue 1466 which describes the current limitation.</p> <p>If FireFly is configured to connect to Besu without <code>revert-reason-enabled=true</code> the error message will be set to:</p> <ul> <li><code>\"errorMessage\":\"FF23054: Error return value unavailable\"</code></li> </ul>"},{"location":"reference/blockchain_operation_errors/#error-retrieval-details","title":"Error Retrieval Details","text":"<p>The precise format of the error message in a blockchain operation can vary based on different factors. The sections below describe in detail how the error message is populted, with specific references to the <code>firefly-evmconnect</code> blockchain connector.</p>"},{"location":"reference/blockchain_operation_errors/#format-of-a-firefly-evmconnect-error-message","title":"Format of a <code>firefly-evmconnect</code> Error Message","text":"<p>The following section describes the way that the <code>firefly-evmconnect</code> plugin uses the <code>errorMessage</code> field. This serves both as an explanation of how EVM-based transaction errors will be formatted, and as a guide that other blockchain connectors may decide to follow.</p> <p>The <code>errorMessage</code> field for a <code>firefly-evmconnect</code> transaction may contain one of the following:</p> <ol> <li>An error message from the FireFly blockchain connector</li> <li>For example <code>\"FF23054: Error return value unavailable\"</code></li> <li>A decoded error string from the blockchain transaction</li> <li>For example <code>Not enough tokens</code></li> <li>This could be an error string from a smart contract e.g. <code>require(requestedTokens &lt;= allowance, \"Not enough tokens\");</code></li> <li>An un-decoded byte string from the blockchain transaction</li> <li>For example  <pre><code>FF23053: Error return value for custom error: 0x1320fa6a00000000000000000000000000000000000000000000000000000000000000640000000000000000000000000000000000000000000000000000000000000010\n</code></pre></li> <li>This could be a custom error from a smart contract e.g. <pre><code>error AllowanceTooSmall(uint256 requested, uint256 allowance);\n...\nrevert AllowanceTooSmall({ requested: 100, allowance: 20 });\n</code></pre></li> <li>If an error reason cannot be decoded the <code>returnValue</code> of the <code>extraInfo</code> will be set to the raw byte string. For example: <pre><code>\"receipt\": {\n  ...\n  \"extraInfo\": [\n     {\n       {\n         \"contractAddress\":\"0x87ae94ab290932c4e6269648bb47c86978af4436\",\n         \"cumulativeGasUsed\":\"33812\",\n         \"from\":\"0x2b1c769ef5ad304a4889f2a07a6617cd935849ae\",\n         \"to\":\"0x302259069aaa5b10dc6f29a9a3f72a8e52837cc3\",\n         \"gasUsed\":\"33812\",\n         \"status\":\"0\",\n         \"errorMessage\":\"FF23053: Error return value for custom error: 0x1320fa6a00000000000000000000000000000000000000000000000000000000000000640000000000000000000000000000000000000000000000000000000000000010\", \n         \"returnValue\":\"0x1320fa6a00000000000000000000000000000000000000000000000000000000000000640000000000000000000000000000000000000000000000000000000000000010\"\n       }\n     }\n  ],\n  ...\n},\n</code></pre></li> </ol>"},{"location":"reference/blockchain_operation_errors/#retrieving-evm-blockchain-transaction-errors","title":"Retrieving EVM Blockchain Transaction Errors","text":"<p>The ability of a blockchain connector such as <code>firefly-evmconnect</code> to retrieve the reason for a transaction failure, is dependent on by the configuration of the blockchain it is connected to. For an EVM blockchain the reason why a transaction failed is recorded with the <code>REVERT</code> op code, with a <code>REASON</code> set to the reason for the failure. By default, most EVM clients do not store this reason in the transaction receipt. This is typically to reduce resource consumption such as memory usage in the client. It is usually possible to configure an EVM client to store the revert reason in the transaction receipt. For example Hyperledger Besu\u2122 provides the <code>--revert-reason-enabled</code> configuration option. If the transaction receipt does not contain the revert reason it is possible to request that an EVM client re-run the transaction and return a trace of all of the op-codes, including the final <code>REVERT</code> <code>REASON</code>. This can be a resource intensive request to submit to an EVM client, and is only available on archive nodes or for very recent blocks.</p> <p>The <code>firefly-evmconnect</code> blockchain connector attempts to obtain the reason for a transaction revert and include it in the <code>extraInfo</code> field. It uses the following mechanisms, in this order:</p> <ol> <li>Checks if the blockchain transaction receipt contains the revert reason.</li> <li>If the revert reason is not in the receipt, and the <code>connector.traceTXForRevertReason</code> configuration option is set to <code>true</code>, calls <code>debug_traceTransaction</code> to obtain a full trace of the transaction and extract the revert reason. By default, <code>connector.traceTXForRevertReason</code> is set to <code>false</code> to avoid submitting high-resource requests to the EVM client.</li> </ol> <p>If the revert reason can be obtained using either mechanism above, the revert reason bytes are decoded in the following way:   - Attempts to decode the bytes as the standard <code>Error(string)</code> signature format and includes the decoded string in the <code>errorMessage</code>   - If the reason is not a standard <code>Error(String)</code> error, sets the <code>errorMessage</code> to <code>FF23053: Error return value for custom error: &lt;raw hex string&gt;</code> and includes the raw byte string in the <code>returnValue</code> field.</p>"},{"location":"reference/blockchain_operation_status/","title":"Blockchain Operation Status","text":""},{"location":"reference/blockchain_operation_status/#blockchain-operations","title":"Blockchain Operations","text":"<p>Every FireFly Transaction can involve zero or more Operations. Blockchain operations are handled by the blockchain connector configured for the namespace and represent a blockchain transaction being handled by that connector.</p>"},{"location":"reference/blockchain_operation_status/#blockchain-operation-status_1","title":"Blockchain Operation Status","text":"<p>A blockchain operation can require the connector to go through various stages of processing in order to successfully confirm the transaction on the blockchain. The orchestrator in FireFly receives updates from the connector to indicate when the operation has been completed and determine when the FireFly transaction as a whole has finished. These updates must contain enough information to correlate the operation to the FireFly transaction but it can be useful to see more detailed information about how the transaction was processed.</p> <p>FireFly 1.2 introduced the concept of sub-status types that allow a blockchain connector to distinguish between the intermediate steps involved in progressing a transaction. It also introduced the concept of an action which a connector might carry out in order to progress between types of sub-status. This can be described as a state machine as shown in the following diagram:</p> <p></p> <p>To access detailed information about a blockchain operation FireFly 1.2 introduced a new query parameter, <code>fetchStatus</code>, to the <code>/transaction/{txid}/operation/{opid}</code> API. When FireFly receives an API request that includes the fetchStatus query parameter it makes a synchronous call directly to the blockchain connector, requesting all of blockchain transaction detail it has. This payload is then included in the FireFly operation response under a new <code>detail</code> field.</p>"},{"location":"reference/blockchain_operation_status/#blockchain-operation-example","title":"Blockchain Operation Example","text":"<pre><code>{\n  \"id\": \"04a8b0c4-03c2-4935-85a1-87d17cddc20a\",\n  \"created\": \"2022-05-16T01:23:15Z\",\n  \"namespace\": \"ns1\",\n  \"tx\": \"99543134-769b-42a8-8be4-a5f8873f969d\",\n  \"type\": \"blockchain_invoke\",\n  \"status\": \"Succeeded\",\n  \"plugin\": \"ethereum\",\n  \"input\": {\n    // Input used to initiate the blockchain operation\n  },\n  \"output\": {\n    // Minimal blockchain operation data necessary\n    // to resolve the FF transaction\n  },\n  \"detail\": {\n    // Full blockchain operation information, including sub-status\n    // transitions that took place for the operation to succeed.\n  }\n}\n</code></pre>"},{"location":"reference/blockchain_operation_status/#detail-status-structure","title":"Detail Status Structure","text":"<p>The structure of a blockchain operation follows the structure described in Operations. In FireFly 1.2, 2 new attributes were added to that structure to allow more detailed status information to be recorded:</p> <ul> <li>history an ordered list of status changes that have taken place during processing of the transaction</li> <li>historySummary an un-ordered list any sub-status type that the blockchain connector uses, and any action type that the blockchain connector carries out as part of processing the transaction.</li> </ul> <p>The <code>history</code> field is designed to record an ordered list of sub-status changes that the transaction has gone through. Within each sub-status change are the actions that have been carried out to try and move the transaction on to a new sub-status. Some transactions might spend a long time going looping between different sub-status types so this field records the N most recent sub-status changes (where the size of N is determined by blockchain connector and its configuration). The follow example shows a transaction going starting at <code>Received</code>, moving to <code>Tracking</code>, and finally ending up as <code>Confirmed</code>. In order to move from <code>Received</code> to <code>Tracking</code> several actions were performed: <code>AssignNonce</code>, <code>RetrieveGasPrice</code>, and <code>SubmitTransaction</code>.</p>"},{"location":"reference/blockchain_operation_status/#history-example","title":"History Example","text":"<pre><code>{\n    ...\n    \"lastSubmit\": \"2023-01-27T17:11:41.222375469Z\",\n    \"nonce\": \"14\",\n    \"history\": [\n        {\n            \"subStatus\": \"Received\",\n            \"time\": \"2023-01-27T17:11:41.122965803Z\",\n            \"actions\": [\n                {\n                    \"action\": \"AssignNonce\",\n                    \"count\": 1,\n                    \"lastInfo\": {\n   \u2003                    \"nonce\": \"14\"\n                    },\n                    \"lastOccurrence\": \"2023-01-27T17:11:41.122967219Z\",\n                    \"time\": \"2023-01-27T17:11:41.122967136Z\"\n                },\n   \u2003            {\n                    \"action\": \"RetrieveGasPrice\",\n                    \"count\": 1,\n                    \"lastInfo\": {\n                        \"gasPrice\": \"0\"\n                    },\n                    \"lastOccurrence\": \"2023-01-27T17:11:41.161213303Z\",\n                    \"time\": \"2023-01-27T17:11:41.161213094Z\"\n                },\n                {\n                    \"action\": \"SubmitTransaction\",\n                    \"count\": 1,\n   \u2003                \"lastInfo\": {\n                        \"txHash\": \"0x4c37de1cf320a1d5c949082bbec8ad5fe918e6621cec3948d609ec3f7deac243\"\n                    },\n   \u2003                \"lastOccurrence\": \"2023-01-27T17:11:41.222374636Z\",\n   \u2003                \"time\": \"2023-01-27T17:11:41.222374553Z\"\n   \u2003            }\n   \u2003        ],\n  \u2003     },\n \u2003      {\n \u2003\u2003         \"subStatus\": \"Tracking\",\n            \"time\": \"2023-01-27T17:11:41.222400219Z\",\n    \u2003       \"actions\": [\n   \u2003\u2003\u2003          {\n    \u2003\u2003\u2003\u2003            \"action\": \"ReceiveReceipt\",\n     \u2003\u2003\u2003\u2003           \"count\": 2,\n    \u2003\u2003\u2003\u2003            \"lastInfo\": {\n     \u2003\u2003\u2003\u2003\u2003              \"protocolId\": \"000001265122/000000\"\n    \u2003\u2003\u2003\u2003            },\n    \u2003\u2003\u2003\u2003            \"lastOccurrence\": \"2023-01-27T17:11:57.93120838Z\",\n    \u2003\u2003\u2003\u2003            \"time\": \"2023-01-27T17:11:47.930332625Z\"\n   \u2003\u2003\u2003          },\n   \u2003\u2003\u2003          {\n   \u2003\u2003\u2003\u2003             \"action\": \"Confirm\",\n    \u2003\u2003\u2003\u2003            \"count\": 1,\n    \u2003\u2003\u2003\u2003            \"lastOccurrence\": \"2023-01-27T17:12:02.660275549Z\",\n    \u2003\u2003\u2003\u2003            \"time\": \"2023-01-27T17:12:02.660275382Z\"\n    \u2003\u2003\u2003         }\n   \u2003\u2003       ],\n  \u2003     },\n  \u2003     {\n \u2003\u2003         \"subStatus\": \"Confirmed\",\n  \u2003\u2003        \"time\": \"2023-01-27T17:12:02.660309382Z\",\n  \u2003\u2003        \"actions\": [],\n  \u2003     }\n    ]\n    ...\n}\n</code></pre> <p>Because the <code>history</code> field is a FIFO structure describing the N most recent sub-status changes, some early sub-status changes or actions may be lost over time. For example an action of <code>assignNonce</code> might only happen once when the transaction is first processed by the connector. The <code>historySummary</code> field ensures that a minimal set of information is kept about every single subStatus type and action that has been recorded.</p>"},{"location":"reference/blockchain_operation_status/#history-summary-example","title":"History Summary Example","text":"<pre><code>{\n    ...\n    \"historySummary\": [\n        {\n            \"count\": 1,\n   \u2003        \"firstOccurrence\": \"2023-01-27T17:11:41.122966136Z\",\n            \"lastOccurrence\": \"2023-01-27T17:11:41.122966136Z\",\n   \u2003        \"subStatus\": \"Received\"\n        },\n        {\n            \"count\": 1,\n            \"firstOccurrence\": \"2023-01-27T17:11:41.122967219Z\",\n            \"lastOccurrence\": \"2023-01-27T17:11:41.122967219Z\",\n            \"action\": \"AssignNonce\"\n        },\n        {\n            \"count\": 1,\n            \"firstOccurrence\": \"2023-01-27T17:11:41.161213303Z\",\n            \"lastOccurrence\": \"2023-01-27T17:11:41.161213303Z\",\n            \"action\": \"RetrieveGasPrice\"\n        },\n        {\n            \"count\": 1,\n            \"firstOccurrence\": \"2023-01-27T17:11:41.222374636Z\",\n            \"lastOccurrence\": \"2023-01-27T17:11:41.222374636Z\",\n            \"action\": \"SubmitTransaction\"\n        },\n        {\n  \u2003         \"count\": 1,\n  \u2003         \"firstOccurrence\": \"2023-01-27T17:11:41.222400678Z\",\n            \"lastOccurrence\": \"\",\n  \u2003         \"subStatus\": \"Tracking\"\n        },\n        {\n            \"count\": 1,\n            \"firstOccurrence\": \"2023-01-27T17:11:57.93120838Z\",\n            \"lastOccurrence\": \"2023-01-27T17:11:57.93120838Z\",\n            \"action\": \"ReceiveReceipt\"\n        },\n        {\n            \"count\": 1,\n            \"firstOccurrence\": \"2023-01-27T17:12:02.660309382Z\",\n            \"lastOccurrence\": \"2023-01-27T17:12:02.660309382Z\",\n            \"action\": \"Confirm\"\n        },\n        {\n \u2003          \"count\": 1,\n   \u2003        \"firstOccurrence\": \"2023-01-27T17:12:02.660309757Z\",\n            \"lastOccurrence\": \"2023-01-27T17:12:02.660309757Z\",\n   \u2003        \"subStatus\": \"Confirmed\"\n        }\n    ]\n}\n</code></pre>"},{"location":"reference/blockchain_operation_status/#public-chain-operations","title":"Public Chain Operations","text":"<p>Blockchain transactions submitted to a public chain, for example to Polygon PoS, might take longer and involve more sub-status transitions before being confirmed. One reason for this could be because of gas price fluctuations of the chain. In this case the <code>history</code> for a public blockchain operation might include a large number of <code>subStatus</code> entries. Using the example sub-status values above, a blockchain operation might move from <code>Tracking</code> to <code>Stale</code>, back to <code>Tracking</code>, back to <code>Stale</code> and so on.</p> <p>Below is an example of the <code>history</code> for a public blockchain operation.</p>"},{"location":"reference/blockchain_operation_status/#polygon-example","title":"Polygon Example","text":"<pre><code>{\n    ...\n    \"lastSubmit\": \"2023-01-27T17:11:41.222375469Z\",\n    \"nonce\": \"14\",\n    \"history\": [\n        {\n            \"subStatus\": \"Received\",\n            \"time\": \"2023-01-27T17:11:41.122965803Z\",\n            \"actions\": [\n                {\n                    \"action\": \"AssignNonce\",\n                    \"count\": 1,\n                    \"lastInfo\": {\n   \u2003                    \"nonce\": \"1\"\n                    },\n                    \"lastOccurrence\": \"2023-01-27T17:11:41.122967219Z\",\n                    \"time\": \"2023-01-27T17:11:41.122967136Z\"\n                },\n   \u2003            {\n                    \"action\": \"RetrieveGasPrice\",\n                    \"count\": 1,\n                    \"lastInfo\": {\n                        \"gasPrice\": \"34422243\"\n                    },\n                    \"lastOccurrence\": \"2023-01-27T17:11:41.161213303Z\",\n                    \"time\": \"2023-01-27T17:11:41.161213094Z\"\n                },\n                {\n                    \"action\": \"SubmitTransaction\",\n                    \"count\": 1,\n   \u2003                \"lastInfo\": {\n                        \"txHash\": \"0x83ba5e1cf320a1d5c949082bbec8ae7fe918e6621cec39478609ec3f7deacbdb\"\n                    },\n   \u2003                \"lastOccurrence\": \"2023-01-27T17:11:41.222374636Z\",\n   \u2003                \"time\": \"2023-01-27T17:11:41.222374553Z\"\n   \u2003            }\n   \u2003        ],\n  \u2003     },\n \u2003      {\n \u2003\u2003         \"subStatus\": \"Tracking\",\n            \"time\": \"2023-01-27T17:11:41.222400219Z\",\n    \u2003       \"actions\": [],\n  \u2003     },\n \u2003      {\n \u2003\u2003         \"subStatus\": \"Stale\",\n            \"time\": \"2023-01-27T17:13:21.222100434Z\",\n    \u2003       \"actions\": [\n   \u2003\u2003\u2003          {\n    \u2003\u2003\u2003\u2003            \"action\": \"RetrieveGasPrice\",\n     \u2003\u2003\u2003\u2003           \"count\": 1,\n                    \"lastInfo\": {\n                        \"gasPrice\": \"44436243\"\n                    },\n    \u2003\u2003\u2003\u2003            \"lastOccurrence\": \"2023-01-27T17:13:22.93120838Z\",\n    \u2003\u2003\u2003\u2003            \"time\": \"2023-01-27T17:13:22.93120838Z\"\n   \u2003\u2003\u2003          },\n                {\n                    \"action\": \"SubmitTransaction\",\n                    \"count\": 1,\n   \u2003                \"lastInfo\": {\n                        \"txHash\": \"0x7b3a5e1ccbc0a1d5c949082bbec8ae7fe918e6621cec39478609ec7aea6103d5\"\n                    },\n   \u2003                \"lastOccurrence\": \"2023-01-27T17:13:32.656374637Z\",\n   \u2003                \"time\": \"2023-01-27T17:13:32.656374637Z\"\n   \u2003            }\n   \u2003\u2003       ],\n  \u2003     },\n \u2003      {\n \u2003\u2003         \"subStatus\": \"Tracking\",\n            \"time\": \"2023-01-27T17:13:33.434400219Z\",\n    \u2003       \"actions\": [],\n  \u2003     },\n \u2003      {\n \u2003\u2003         \"subStatus\": \"Stale\",\n            \"time\": \"2023-01-27T17:15:21.222100434Z\",\n    \u2003       \"actions\": [\n   \u2003\u2003\u2003          {\n    \u2003\u2003\u2003\u2003            \"action\": \"RetrieveGasPrice\",\n     \u2003\u2003\u2003\u2003           \"count\": 1,\n                    \"lastInfo\": {\n                        \"gasPrice\": \"52129243\"\n                    },\n    \u2003\u2003\u2003\u2003            \"lastOccurrence\": \"2023-01-27T17:15:22.93120838Z\",\n    \u2003\u2003\u2003\u2003            \"time\": \"2023-01-27T17:15:22.93120838Z\"\n   \u2003\u2003\u2003          },\n                {\n                    \"action\": \"SubmitTransaction\",\n                    \"count\": 1,\n   \u2003                \"lastInfo\": {\n                        \"txHash\": \"0x89995e1ccbc0a1d5c949082bbec8ae7fe918e6621cec39478609ec7a8c64abc\"\n                    },\n   \u2003                \"lastOccurrence\": \"2023-01-27T17:15:32.656374637Z\",\n   \u2003                \"time\": \"2023-01-27T17:15:32.656374637Z\"\n   \u2003            }\n   \u2003\u2003       ],\n  \u2003     },\n \u2003      {\n \u2003\u2003         \"subStatus\": \"Tracking\",\n            \"time\": \"2023-01-27T17:15:33.434400219Z\",\n    \u2003       \"actions\": [\n   \u2003\u2003\u2003          {\n    \u2003\u2003\u2003\u2003            \"action\": \"ReceiveReceipt\",\n     \u2003\u2003\u2003\u2003           \"count\": 1,\n    \u2003\u2003\u2003\u2003            \"lastInfo\": {\n     \u2003\u2003\u2003\u2003\u2003              \"protocolId\": \"000004897621/000000\"\n    \u2003\u2003\u2003\u2003            },\n    \u2003\u2003\u2003\u2003            \"lastOccurrence\": \"2023-01-27T17:15:33.94120833Z\",\n    \u2003\u2003\u2003\u2003            \"time\": \"2023-01-27T17:15:33.94120833Z\"\n   \u2003\u2003\u2003          },\n   \u2003\u2003\u2003          {\n   \u2003\u2003\u2003\u2003             \"action\": \"Confirm\",\n    \u2003\u2003\u2003\u2003            \"count\": 1,\n    \u2003\u2003\u2003\u2003            \"lastOccurrence\": \"2023-01-27T17:16:02.780275549Z\",\n    \u2003\u2003\u2003\u2003            \"time\": \"2023-01-27T17:16:02.780275382Z\"\n    \u2003\u2003\u2003         }\n   \u2003\u2003       ],\n  \u2003     },\n  \u2003     {\n \u2003\u2003         \"subStatus\": \"Confirmed\",\n  \u2003\u2003        \"time\": \"2023-01-27T17:16:03.990309381Z\",\n  \u2003\u2003        \"actions\": [],\n  \u2003     }\n    ]\n    ...\n}\n</code></pre>"},{"location":"reference/config/","title":"Configuration Reference","text":""},{"location":"reference/config/#admin","title":"admin","text":"Key Description Type Default Value enabled Deprecated - use spi.enabled instead <code>boolean</code> <code>&lt;nil&gt;</code>"},{"location":"reference/config/#api","title":"api","text":"Key Description Type Default Value defaultFilterLimit The maximum number of rows to return if no limit is specified on an API request <code>int</code> <code>25</code> dynamicPublicURLHeader Dynamic header that informs the backend the base public URL for the request, in order to build URL links in OpenAPI/SwaggerUI <code>string</code> <code>&lt;nil&gt;</code> maxFilterLimit The largest value of <code>limit</code> that an HTTP client can specify in a request <code>int</code> <code>1000</code> passthroughHeaders A list of HTTP request headers to pass through to dependency microservices <code>[]string</code> <code>[]</code> requestMaxTimeout The maximum amount of time that an HTTP client can specify in a <code>Request-Timeout</code> header to keep a specific request open <code>time.Duration</code> <code>10m</code> requestTimeout The maximum amount of time that a request is allowed to remain open <code>time.Duration</code> <code>120s</code>"},{"location":"reference/config/#assetmanager","title":"asset.manager","text":"Key Description Type Default Value keyNormalization Mechanism to normalize keys before using them. Valid options are <code>blockchain_plugin</code> - use blockchain plugin (default) or <code>none</code> - do not attempt normalization (deprecated - use namespaces.predefined[].asset.manager.keyNormalization) <code>string</code> <code>blockchain_plugin</code>"},{"location":"reference/config/#batchmanager","title":"batch.manager","text":"Key Description Type Default Value minimumPollDelay The minimum time the batch manager waits between polls on the DB - to prevent thrashing <code>time.Duration</code> <code>100ms</code> pollTimeout How long to wait without any notifications of new messages before doing a page query <code>time.Duration</code> <code>30s</code> readPageSize The size of each page of messages read from the database into memory when assembling batches <code>int</code> <code>100</code>"},{"location":"reference/config/#batchretry","title":"batch.retry","text":"Key Description Type Default Value factor The retry backoff factor <code>float32</code> <code>2</code> initDelay The initial retry delay <code>time.Duration</code> <code>250ms</code> maxDelay The maximum retry delay <code>time.Duration</code> <code>30s</code>"},{"location":"reference/config/#blobreceiverretry","title":"blobreceiver.retry","text":"Key Description Type Default Value factor The retry backoff factor <code>float32</code> <code>2</code> initialDelay The initial retry delay <code>time.Duration</code> <code>250ms</code> maxDelay The maximum retry delay <code>time.Duration</code> <code>1m</code>"},{"location":"reference/config/#blobreceiverworker","title":"blobreceiver.worker","text":"Key Description Type Default Value batchMaxInserts The maximum number of items the blob receiver worker will insert in a batch <code>int</code> <code>200</code> batchTimeout The maximum amount of the the blob receiver worker will wait <code>time.Duration</code> <code>50ms</code> count The number of blob receiver workers <code>int</code> <code>5</code>"},{"location":"reference/config/#broadcastbatch","title":"broadcast.batch","text":"Key Description Type Default Value agentTimeout How long to keep around a batching agent for a sending identity before disposal <code>string</code> <code>2m</code> payloadLimit The maximum payload size of a batch for broadcast messages <code>BytesSize</code> <code>800Kb</code> size The maximum number of messages that can be packed into a batch <code>int</code> <code>200</code> timeout The timeout to wait for a batch to fill, before sending <code>time.Duration</code> <code>1s</code>"},{"location":"reference/config/#cache","title":"cache","text":"Key Description Type Default Value enabled Enables caching, defaults to true <code>boolean</code> <code>true</code>"},{"location":"reference/config/#cacheaddressresolver","title":"cache.addressresolver","text":"Key Description Type Default Value limit Max number of cached items for address resolver <code>int</code> <code>1000</code> ttl Time to live of cached items for address resolver <code>string</code> <code>24h</code>"},{"location":"reference/config/#cachebatch","title":"cache.batch","text":"Key Description Type Default Value limit Max number of cached items for batches <code>int</code> <code>100</code> ttl Time to live of cache items for batches <code>string</code> <code>5m</code>"},{"location":"reference/config/#cacheblockchain","title":"cache.blockchain","text":"Key Description Type Default Value limit Max number of cached items for blockchain <code>int</code> <code>100</code> ttl Time to live of cached items for blockchain <code>string</code> <code>5m</code>"},{"location":"reference/config/#cacheblockchainevent","title":"cache.blockchainevent","text":"Key Description Type Default Value limit Max number of cached blockchain events for transactions <code>int</code> <code>1000</code> ttl Time to live of cached blockchain events for transactions <code>string</code> <code>5m</code>"},{"location":"reference/config/#cacheeventlistenertopic","title":"cache.eventlistenertopic","text":"Key Description Type Default Value limit Max number of cached items for blockchain listener topics <code>int</code> <code>100</code> ttl Time to live of cached items for blockchain listener topics <code>string</code> <code>5m</code>"},{"location":"reference/config/#cachegroup","title":"cache.group","text":"Key Description Type Default Value limit Max number of cached items for groups <code>int</code> <code>50</code> ttl Time to live of cached items for groups <code>string</code> <code>1h</code>"},{"location":"reference/config/#cacheidentity","title":"cache.identity","text":"Key Description Type Default Value limit Max number of cached identities for identity manager <code>int</code> <code>100</code> ttl Time to live of cached identities for identity manager <code>string</code> <code>1h</code>"},{"location":"reference/config/#cachemessage","title":"cache.message","text":"Key Description Type Default Value size Max size of cached messages for data manager <code>BytesSize</code> <code>50Mb</code> ttl Time to live of cached messages for data manager <code>string</code> <code>5m</code>"},{"location":"reference/config/#cachemethods","title":"cache.methods","text":"Key Description Type Default Value limit Max number of cached items for schema validations on blockchain methods <code>int</code> <code>200</code> ttl Time to live of cached items for schema validations on blockchain methods <code>string</code> <code>5m</code>"},{"location":"reference/config/#cacheoperations","title":"cache.operations","text":"Key Description Type Default Value limit Max number of cached items for operations <code>int</code> <code>1000</code> ttl Time to live of cached items for operations <code>string</code> <code>5m</code>"},{"location":"reference/config/#cachetokenpool","title":"cache.tokenpool","text":"Key Description Type Default Value limit Max number of cached items for token pools <code>int</code> <code>100</code> ttl Time to live of cached items for token pool <code>string</code> <code>1h</code>"},{"location":"reference/config/#cachetransaction","title":"cache.transaction","text":"Key Description Type Default Value size Max size of cached transactions <code>BytesSize</code> <code>1Mb</code> ttl Time to live of cached transactions <code>string</code> <code>5m</code>"},{"location":"reference/config/#cachevalidator","title":"cache.validator","text":"Key Description Type Default Value size Max size of cached validators for data manager <code>BytesSize</code> <code>1Mb</code> ttl Time to live of cached validators for data manager <code>string</code> <code>1h</code>"},{"location":"reference/config/#config","title":"config","text":"Key Description Type Default Value autoReload Monitor the configuration file for changes, and automatically add/remove/reload namespaces and plugins <code>boolean</code> <code>&lt;nil&gt;</code>"},{"location":"reference/config/#cors","title":"cors","text":"Key Description Type Default Value credentials CORS setting to control whether a browser allows credentials to be sent to this API <code>boolean</code> <code>true</code> debug Whether debug is enabled for the CORS implementation <code>boolean</code> <code>false</code> enabled Whether CORS is enabled <code>boolean</code> <code>true</code> headers CORS setting to control the allowed headers <code>[]string</code> <code>[*]</code> maxAge The maximum age a browser should rely on CORS checks <code>time.Duration</code> <code>600</code> methods CORS setting to control the allowed methods <code>[]string</code> <code>[GET POST PUT PATCH DELETE]</code> origins CORS setting to control the allowed origins <code>[]string</code> <code>[*]</code>"},{"location":"reference/config/#debug","title":"debug","text":"Key Description Type Default Value address The HTTP interface the go debugger binds to <code>string</code> <code>localhost</code> port An HTTP port on which to enable the go debugger <code>int</code> <code>-1</code>"},{"location":"reference/config/#downloadretry","title":"download.retry","text":"Key Description Type Default Value factor The retry backoff factor <code>float32</code> <code>2</code> initialDelay The initial retry delay <code>time.Duration</code> <code>100ms</code> maxAttempts The maximum number attempts <code>int</code> <code>100</code> maxDelay The maximum retry delay <code>time.Duration</code> <code>1m</code>"},{"location":"reference/config/#downloadworker","title":"download.worker","text":"Key Description Type Default Value count The number of download workers <code>int</code> <code>10</code> queueLength The length of the work queue in the channel to the workers - defaults to 2x the worker count <code>int</code> <code>&lt;nil&gt;</code>"},{"location":"reference/config/#eventaggregator","title":"event.aggregator","text":"Key Description Type Default Value batchSize The maximum number of records to read from the DB before performing an aggregation run <code>BytesSize</code> <code>200</code> batchTimeout How long to wait for new events to arrive before performing aggregation on a page of events <code>time.Duration</code> <code>0ms</code> firstEvent The first event the aggregator should process, if no previous offest is stored in the DB. Valid options are <code>oldest</code> or <code>newest</code> <code>string</code> <code>oldest</code> pollTimeout The time to wait without a notification of new events, before trying a select on the table <code>time.Duration</code> <code>30s</code> rewindQueryLimit Safety limit on the maximum number of records to search when performing queries to search for rewinds <code>int</code> <code>1000</code> rewindQueueLength The size of the queue into the rewind dispatcher <code>int</code> <code>10</code> rewindTimeout The minimum time to wait for rewinds to accumulate before resolving them <code>time.Duration</code> <code>50ms</code>"},{"location":"reference/config/#eventaggregatorretry","title":"event.aggregator.retry","text":"Key Description Type Default Value factor The retry backoff factor <code>float32</code> <code>2</code> initDelay The initial retry delay <code>time.Duration</code> <code>100ms</code> maxDelay The maximum retry delay <code>time.Duration</code> <code>30s</code>"},{"location":"reference/config/#eventdbevents","title":"event.dbevents","text":"Key Description Type Default Value bufferSize The size of the buffer of change events <code>BytesSize</code> <code>100</code>"},{"location":"reference/config/#eventdispatcher","title":"event.dispatcher","text":"Key Description Type Default Value batchTimeout A short time to wait for new events to arrive before re-polling for new events <code>time.Duration</code> <code>0ms</code> bufferLength The number of events + attachments an individual dispatcher should hold in memory ready for delivery to the subscription <code>int</code> <code>5</code> pollTimeout The time to wait without a notification of new events, before trying a select on the table <code>time.Duration</code> <code>30s</code>"},{"location":"reference/config/#eventdispatcherretry","title":"event.dispatcher.retry","text":"Key Description Type Default Value factor The retry backoff factor <code>float32</code> <code>&lt;nil&gt;</code> initDelay The initial retry delay <code>time.Duration</code> <code>&lt;nil&gt;</code> maxDelay The maximum retry delay <code>time.Duration</code> <code>&lt;nil&gt;</code>"},{"location":"reference/config/#eventtransports","title":"event.transports","text":"Key Description Type Default Value default The default event transport for new subscriptions <code>string</code> <code>websockets</code> enabled Which event interface plugins are enabled <code>boolean</code> <code>[websockets webhooks]</code>"},{"location":"reference/config/#eventswebhooks","title":"events.webhooks","text":"Key Description Type Default Value connectionTimeout The maximum amount of time that a connection is allowed to remain with no data transmitted <code>time.Duration</code> <code>30s</code> expectContinueTimeout See ExpectContinueTimeout in the Go docs <code>time.Duration</code> <code>1s</code> headers Adds custom headers to HTTP requests <code>map[string]string</code> <code>&lt;nil&gt;</code> idleTimeout The max duration to hold a HTTP keepalive connection between calls <code>time.Duration</code> <code>475ms</code> maxConnsPerHost The max number of connections, per unique hostname. Zero means no limit <code>int</code> <code>0</code> maxIdleConns The max number of idle connections to hold pooled <code>int</code> <code>100</code> passthroughHeadersEnabled Enable passing through the set of allowed HTTP request headers <code>boolean</code> <code>false</code> requestTimeout The maximum amount of time that a request is allowed to remain open <code>time.Duration</code> <code>30s</code> tlsHandshakeTimeout The maximum amount of time to wait for a successful TLS handshake <code>time.Duration</code> <code>10s</code>"},{"location":"reference/config/#eventswebhooksauth","title":"events.webhooks.auth","text":"Key Description Type Default Value password Password <code>string</code> <code>&lt;nil&gt;</code> username Username <code>string</code> <code>&lt;nil&gt;</code>"},{"location":"reference/config/#eventswebhooksproxy","title":"events.webhooks.proxy","text":"Key Description Type Default Value url Optional HTTP proxy server to connect through <code>string</code> <code>&lt;nil&gt;</code>"},{"location":"reference/config/#eventswebhooksretry","title":"events.webhooks.retry","text":"Key Description Type Default Value count The maximum number of times to retry <code>int</code> <code>5</code> enabled Enables retries <code>boolean</code> <code>false</code> errorStatusCodeRegex The regex that the error response status code must match to trigger retry <code>string</code> <code>&lt;nil&gt;</code> initWaitTime The initial retry delay <code>time.Duration</code> <code>250ms</code> maxWaitTime The maximum retry delay <code>time.Duration</code> <code>30s</code>"},{"location":"reference/config/#eventswebhooksthrottle","title":"events.webhooks.throttle","text":"Key Description Type Default Value burst The maximum number of requests that can be made in a short period of time before the throttling kicks in. <code>int</code> <code>&lt;nil&gt;</code> requestsPerSecond The average rate at which requests are allowed to pass through over time. <code>int</code> <code>&lt;nil&gt;</code>"},{"location":"reference/config/#eventswebhookstls","title":"events.webhooks.tls","text":"Key Description Type Default Value ca The TLS certificate authority in PEM format (this option is ignored if caFile is also set) <code>string</code> <code>&lt;nil&gt;</code> caFile The path to the CA file for TLS on this API <code>string</code> <code>&lt;nil&gt;</code> cert The TLS certificate in PEM format (this option is ignored if certFile is also set) <code>string</code> <code>&lt;nil&gt;</code> certFile The path to the certificate file for TLS on this API <code>string</code> <code>&lt;nil&gt;</code> clientAuth Enables or disables client auth for TLS on this API <code>string</code> <code>&lt;nil&gt;</code> enabled Enables or disables TLS on this API <code>boolean</code> <code>false</code> insecureSkipHostVerify When to true in unit test development environments to disable TLS verification. Use with extreme caution <code>boolean</code> <code>&lt;nil&gt;</code> key The TLS certificate key in PEM format (this option is ignored if keyFile is also set) <code>string</code> <code>&lt;nil&gt;</code> keyFile The path to the private key file for TLS on this API <code>string</code> <code>&lt;nil&gt;</code> requiredDNAttributes A set of required subject DN attributes. Each entry is a regular expression, and the subject certificate must have a matching attribute of the specified type (CN, C, O, OU, ST, L, STREET, POSTALCODE, SERIALNUMBER are valid attributes) <code>map[string]string</code> <code>&lt;nil&gt;</code>"},{"location":"reference/config/#eventswebsockets","title":"events.websockets","text":"Key Description Type Default Value readBufferSize WebSocket read buffer size <code>BytesSize</code> <code>16Kb</code> writeBufferSize WebSocket write buffer size <code>BytesSize</code> <code>16Kb</code>"},{"location":"reference/config/#histograms","title":"histograms","text":"Key Description Type Default Value maxChartRows The maximum rows to fetch for each histogram bucket <code>int</code> <code>100</code>"},{"location":"reference/config/#http","title":"http","text":"Key Description Type Default Value address The IP address on which the HTTP API should listen IP Address <code>string</code> <code>127.0.0.1</code> port The port on which the HTTP API should listen <code>int</code> <code>5000</code> publicURL The fully qualified public URL for the API. This is used for building URLs in HTTP responses and in OpenAPI Spec generation URL <code>string</code> <code>&lt;nil&gt;</code> readTimeout The maximum time to wait when reading from an HTTP connection <code>time.Duration</code> <code>15s</code> shutdownTimeout The maximum amount of time to wait for any open HTTP requests to finish before shutting down the HTTP server <code>time.Duration</code> <code>10s</code> writeTimeout The maximum time to wait when writing to an HTTP connection <code>time.Duration</code> <code>15s</code>"},{"location":"reference/config/#httpauth","title":"http.auth","text":"Key Description Type Default Value type The auth plugin to use for server side authentication of requests <code>string</code> <code>&lt;nil&gt;</code>"},{"location":"reference/config/#httpauthbasic","title":"http.auth.basic","text":"Key Description Type Default Value passwordfile The path to a .htpasswd file to use for authenticating requests. Passwords should be hashed with bcrypt. <code>string</code> <code>&lt;nil&gt;</code>"},{"location":"reference/config/#httptls","title":"http.tls","text":"Key Description Type Default Value ca The TLS certificate authority in PEM format (this option is ignored if caFile is also set) <code>string</code> <code>&lt;nil&gt;</code> caFile The path to the CA file for TLS on this API <code>string</code> <code>&lt;nil&gt;</code> cert The TLS certificate in PEM format (this option is ignored if certFile is also set) <code>string</code> <code>&lt;nil&gt;</code> certFile The path to the certificate file for TLS on this API <code>string</code> <code>&lt;nil&gt;</code> clientAuth Enables or disables client auth for TLS on this API <code>string</code> <code>&lt;nil&gt;</code> enabled Enables or disables TLS on this API <code>boolean</code> <code>false</code> insecureSkipHostVerify When to true in unit test development environments to disable TLS verification. Use with extreme caution <code>boolean</code> <code>&lt;nil&gt;</code> key The TLS certificate key in PEM format (this option is ignored if keyFile is also set) <code>string</code> <code>&lt;nil&gt;</code> keyFile The path to the private key file for TLS on this API <code>string</code> <code>&lt;nil&gt;</code> requiredDNAttributes A set of required subject DN attributes. Each entry is a regular expression, and the subject certificate must have a matching attribute of the specified type (CN, C, O, OU, ST, L, STREET, POSTALCODE, SERIALNUMBER are valid attributes) <code>map[string]string</code> <code>&lt;nil&gt;</code>"},{"location":"reference/config/#log","title":"log","text":"Key Description Type Default Value compress Determines if the rotated log files should be compressed using gzip <code>boolean</code> <code>&lt;nil&gt;</code> filename Filename is the file to write logs to.  Backup log files will be retained in the same directory <code>string</code> <code>&lt;nil&gt;</code> filesize MaxSize is the maximum size the log file before it gets rotated <code>BytesSize</code> <code>100m</code> forceColor Force color to be enabled, even when a non-TTY output is detected <code>boolean</code> <code>&lt;nil&gt;</code> includeCodeInfo Enables the report caller for including the calling file and line number, and the calling function. If using text logs, it uses the logrus text format rather than the default prefix format. <code>boolean</code> <code>false</code> level The log level - error, warn, info, debug, trace <code>string</code> <code>info</code> maxAge The maximum time to retain old log files based on the timestamp encoded in their filename <code>time.Duration</code> <code>24h</code> maxBackups Maximum number of old log files to retain <code>int</code> <code>2</code> noColor Force color to be disabled, event when TTY output is detected <code>boolean</code> <code>&lt;nil&gt;</code> timeFormat Custom time format for logs Time format <code>string</code> <code>2006-01-02T15:04:05.000Z07:00</code> utc Use UTC timestamps for logs <code>boolean</code> <code>false</code>"},{"location":"reference/config/#logjson","title":"log.json","text":"Key Description Type Default Value enabled Enables JSON formatted logs rather than text. All log color settings are ignored when enabled. <code>boolean</code> <code>false</code>"},{"location":"reference/config/#logjsonfields","title":"log.json.fields","text":"Key Description Type Default Value file configures the JSON key containing the calling file <code>string</code> <code>file</code> func Configures the JSON key containing the calling function <code>string</code> <code>func</code> level Configures the JSON key containing the log level <code>string</code> <code>level</code> message Configures the JSON key containing the log message <code>string</code> <code>message</code> timestamp Configures the JSON key containing the timestamp of the log <code>string</code> <code>@timestamp</code>"},{"location":"reference/config/#messagewriter","title":"message.writer","text":"Key Description Type Default Value batchMaxInserts The maximum number of database inserts to include when writing a single batch of messages + data <code>int</code> <code>200</code> batchTimeout How long to wait for more messages to arrive before flushing the batch <code>time.Duration</code> <code>10ms</code> count The number of message writer workers <code>int</code> <code>5</code>"},{"location":"reference/config/#metrics","title":"metrics","text":"Key Description Type Default Value address The IP address on which the metrics HTTP API should listen <code>int</code> <code>127.0.0.1</code> enabled Enables the metrics API <code>boolean</code> <code>true</code> path The path from which to serve the Prometheus metrics <code>string</code> <code>/metrics</code> port The port on which the metrics HTTP API should listen <code>int</code> <code>6000</code> publicURL The fully qualified public URL for the metrics API. This is used for building URLs in HTTP responses and in OpenAPI Spec generation URL <code>string</code> <code>&lt;nil&gt;</code> readTimeout The maximum time to wait when reading from an HTTP connection <code>time.Duration</code> <code>15s</code> shutdownTimeout The maximum amount of time to wait for any open HTTP requests to finish before shutting down the HTTP server <code>time.Duration</code> <code>10s</code> writeTimeout The maximum time to wait when writing to an HTTP connection <code>time.Duration</code> <code>15s</code>"},{"location":"reference/config/#metricsauth","title":"metrics.auth","text":"Key Description Type Default Value type The auth plugin to use for server side authentication of requests <code>string</code> <code>&lt;nil&gt;</code>"},{"location":"reference/config/#metricsauthbasic","title":"metrics.auth.basic","text":"Key Description Type Default Value passwordfile The path to a .htpasswd file to use for authenticating requests. Passwords should be hashed with bcrypt. <code>string</code> <code>&lt;nil&gt;</code>"},{"location":"reference/config/#metricstls","title":"metrics.tls","text":"Key Description Type Default Value ca The TLS certificate authority in PEM format (this option is ignored if caFile is also set) <code>string</code> <code>&lt;nil&gt;</code> caFile The path to the CA file for TLS on this API <code>string</code> <code>&lt;nil&gt;</code> cert The TLS certificate in PEM format (this option is ignored if certFile is also set) <code>string</code> <code>&lt;nil&gt;</code> certFile The path to the certificate file for TLS on this API <code>string</code> <code>&lt;nil&gt;</code> clientAuth Enables or disables client auth for TLS on this API <code>string</code> <code>&lt;nil&gt;</code> enabled Enables or disables TLS on this API <code>boolean</code> <code>false</code> insecureSkipHostVerify When to true in unit test development environments to disable TLS verification. Use with extreme caution <code>boolean</code> <code>&lt;nil&gt;</code> key The TLS certificate key in PEM format (this option is ignored if keyFile is also set) <code>string</code> <code>&lt;nil&gt;</code> keyFile The path to the private key file for TLS on this API <code>string</code> <code>&lt;nil&gt;</code> requiredDNAttributes A set of required subject DN attributes. Each entry is a regular expression, and the subject certificate must have a matching attribute of the specified type (CN, C, O, OU, ST, L, STREET, POSTALCODE, SERIALNUMBER are valid attributes) <code>map[string]string</code> <code>&lt;nil&gt;</code>"},{"location":"reference/config/#namespaces","title":"namespaces","text":"Key Description Type Default Value default The default namespace - must be in the predefined list <code>string</code> <code>default</code> predefined A list of namespaces to ensure exists, without requiring a broadcast from the network List <code>string</code> <code>&lt;nil&gt;</code>"},{"location":"reference/config/#namespacespredefined","title":"namespaces.predefined[]","text":"Key Description Type Default Value defaultKey A default signing key for blockchain transactions within this namespace <code>string</code> <code>&lt;nil&gt;</code> description A description for the namespace <code>string</code> <code>&lt;nil&gt;</code> name The name of the namespace (must be unique) <code>string</code> <code>&lt;nil&gt;</code> plugins The list of plugins for this namespace <code>string</code> <code>&lt;nil&gt;</code>"},{"location":"reference/config/#namespacespredefinedassetmanager","title":"namespaces.predefined[].asset.manager","text":"Key Description Type Default Value keyNormalization Mechanism to normalize keys before using them. Valid options are <code>blockchain_plugin</code> - use blockchain plugin (default) or <code>none</code> - do not attempt normalization <code>string</code> <code>&lt;nil&gt;</code>"},{"location":"reference/config/#namespacespredefinedmultiparty","title":"namespaces.predefined[].multiparty","text":"Key Description Type Default Value enabled Enables multi-party mode for this namespace (defaults to true if an org name or key is configured, either here or at the root level) <code>boolean</code> <code>&lt;nil&gt;</code> networknamespace The shared namespace name to be sent in multiparty messages, if it differs from the local namespace name <code>string</code> <code>&lt;nil&gt;</code>"},{"location":"reference/config/#namespacespredefinedmultipartycontract","title":"namespaces.predefined[].multiparty.contract[]","text":"Key Description Type Default Value firstEvent The first event the contract should process. Valid options are <code>oldest</code> or <code>newest</code> <code>string</code> <code>&lt;nil&gt;</code> location A blockchain-specific contract location. For example, an Ethereum contract address, or a Fabric chaincode name and channel <code>string</code> <code>&lt;nil&gt;</code> options Blockchain-specific contract options <code>string</code> <code>&lt;nil&gt;</code>"},{"location":"reference/config/#namespacespredefinedmultipartynode","title":"namespaces.predefined[].multiparty.node","text":"Key Description Type Default Value description A description for the node in this namespace <code>string</code> <code>&lt;nil&gt;</code> name The node name for this namespace <code>string</code> <code>&lt;nil&gt;</code>"},{"location":"reference/config/#namespacespredefinedmultipartyorg","title":"namespaces.predefined[].multiparty.org","text":"Key Description Type Default Value description A description for the local root organization within this namespace <code>string</code> <code>&lt;nil&gt;</code> key The signing key allocated to the root organization within this namespace <code>string</code> <code>&lt;nil&gt;</code> name A short name for the local root organization within this namespace <code>string</code> <code>&lt;nil&gt;</code>"},{"location":"reference/config/#namespacespredefinedtlsconfigs","title":"namespaces.predefined[].tlsConfigs[]","text":"Key Description Type Default Value name Name of the TLS Config <code>string</code> <code>&lt;nil&gt;</code>"},{"location":"reference/config/#namespacespredefinedtlsconfigstls","title":"namespaces.predefined[].tlsConfigs[].tls","text":"Key Description Type Default Value ca The TLS certificate authority in PEM format (this option is ignored if caFile is also set) <code>string</code> <code>&lt;nil&gt;</code> caFile The path to the CA file for TLS on this API <code>string</code> <code>&lt;nil&gt;</code> cert The TLS certificate in PEM format (this option is ignored if certFile is also set) <code>string</code> <code>&lt;nil&gt;</code> certFile The path to the certificate file for TLS on this API <code>string</code> <code>&lt;nil&gt;</code> clientAuth Enables or disables client auth for TLS on this API <code>string</code> <code>&lt;nil&gt;</code> enabled Enables or disables TLS on this API <code>boolean</code> <code>false</code> insecureSkipHostVerify When to true in unit test development environments to disable TLS verification. Use with extreme caution <code>boolean</code> <code>&lt;nil&gt;</code> key The TLS certificate key in PEM format (this option is ignored if keyFile is also set) <code>string</code> <code>&lt;nil&gt;</code> keyFile The path to the private key file for TLS on this API <code>string</code> <code>&lt;nil&gt;</code> requiredDNAttributes A set of required subject DN attributes. Each entry is a regular expression, and the subject certificate must have a matching attribute of the specified type (CN, C, O, OU, ST, L, STREET, POSTALCODE, SERIALNUMBER are valid attributes) <code>map[string]string</code> <code>&lt;nil&gt;</code>"},{"location":"reference/config/#namespacesretry","title":"namespaces.retry","text":"Key Description Type Default Value factor The retry backoff factor <code>float32</code> <code>2</code> initDelay The initial retry delay <code>time.Duration</code> <code>5s</code> maxDelay The maximum retry delay <code>time.Duration</code> <code>1m</code>"},{"location":"reference/config/#node","title":"node","text":"Key Description Type Default Value description The description of this FireFly node <code>string</code> <code>&lt;nil&gt;</code> name The name of this FireFly node <code>string</code> <code>&lt;nil&gt;</code>"},{"location":"reference/config/#opupdateretry","title":"opupdate.retry","text":"Key Description Type Default Value factor The retry backoff factor <code>float32</code> <code>2</code> initialDelay The initial retry delay <code>time.Duration</code> <code>250ms</code> maxDelay The maximum retry delay <code>time.Duration</code> <code>1m</code>"},{"location":"reference/config/#opupdateworker","title":"opupdate.worker","text":"Key Description Type Default Value batchMaxInserts The maximum number of database inserts to include when writing a single batch of messages + data <code>int</code> <code>200</code> batchTimeout How long to wait for more messages to arrive before flushing the batch <code>time.Duration</code> <code>50ms</code> count The number of operation update works <code>int</code> <code>5</code> queueLength The size of the queue for the Operation Update worker <code>int</code> <code>50</code>"},{"location":"reference/config/#orchestrator","title":"orchestrator","text":"Key Description Type Default Value startupAttempts The number of times to attempt to connect to core infrastructure on startup <code>string</code> <code>5</code>"},{"location":"reference/config/#org","title":"org","text":"Key Description Type Default Value description A description of the organization to which this FireFly node belongs (deprecated - should be set on each multi-party namespace instead) <code>string</code> <code>&lt;nil&gt;</code> key The signing key allocated to the organization (deprecated - should be set on each multi-party namespace instead) <code>string</code> <code>&lt;nil&gt;</code> name The name of the organization to which this FireFly node belongs (deprecated - should be set on each multi-party namespace instead) <code>string</code> <code>&lt;nil&gt;</code>"},{"location":"reference/config/#plugins","title":"plugins","text":"Key Description Type Default Value auth Authorization plugin configuration <code>map[string]string</code> <code>&lt;nil&gt;</code> blockchain The list of configured Blockchain plugins <code>string</code> <code>&lt;nil&gt;</code> database The list of configured Database plugins <code>string</code> <code>&lt;nil&gt;</code> dataexchange The array of configured Data Exchange plugins <code>string</code> <code>&lt;nil&gt;</code> identity The list of available Identity plugins <code>string</code> <code>&lt;nil&gt;</code> sharedstorage The list of configured Shared Storage plugins <code>string</code> <code>&lt;nil&gt;</code> tokens The token plugin configurations <code>string</code> <code>&lt;nil&gt;</code>"},{"location":"reference/config/#pluginsauth","title":"plugins.auth[]","text":"Key Description Type Default Value name The name of the auth plugin to use <code>string</code> <code>&lt;nil&gt;</code> type The type of the auth plugin to use <code>string</code> <code>&lt;nil&gt;</code>"},{"location":"reference/config/#pluginsauthbasic","title":"plugins.auth[].basic","text":"Key Description Type Default Value passwordfile The path to a .htpasswd file to use for authenticating requests. Passwords should be hashed with bcrypt. <code>string</code> <code>&lt;nil&gt;</code>"},{"location":"reference/config/#pluginsblockchain","title":"plugins.blockchain[]","text":"Key Description Type Default Value name The name of the configured Blockchain plugin <code>string</code> <code>&lt;nil&gt;</code> type The type of the configured Blockchain Connector plugin <code>string</code> <code>&lt;nil&gt;</code>"},{"location":"reference/config/#pluginsblockchainethereumaddressresolver","title":"plugins.blockchain[].ethereum.addressResolver","text":"Key Description Type Default Value alwaysResolve Causes the address resolver to be invoked on every API call that submits a signing key, regardless of whether the input string conforms to an 0x address. Also disables any result caching <code>boolean</code> <code>&lt;nil&gt;</code> bodyTemplate The body go template string to use when making HTTP requests. The template input contains '.Key' and '.Intent' string variables. Go Template <code>string</code> <code>&lt;nil&gt;</code> connectionTimeout The maximum amount of time that a connection is allowed to remain with no data transmitted <code>time.Duration</code> <code>30s</code> expectContinueTimeout See ExpectContinueTimeout in the Go docs <code>time.Duration</code> <code>1s</code> headers Adds custom headers to HTTP requests <code>string</code> <code>&lt;nil&gt;</code> idleTimeout The max duration to hold a HTTP keepalive connection between calls <code>time.Duration</code> <code>475ms</code> maxConnsPerHost The max number of connections, per unique hostname. Zero means no limit <code>int</code> <code>0</code> maxIdleConns The max number of idle connections to hold pooled <code>int</code> <code>100</code> method The HTTP method to use when making requests to the Address Resolver <code>string</code> <code>GET</code> passthroughHeadersEnabled Enable passing through the set of allowed HTTP request headers <code>boolean</code> <code>false</code> requestTimeout The maximum amount of time that a request is allowed to remain open <code>time.Duration</code> <code>30s</code> responseField The name of a JSON field that is provided in the response, that contains the ethereum address (default <code>address</code>) <code>string</code> <code>address</code> retainOriginal When true the original pre-resolved string is retained after the lookup, and passed down to Ethconnect as the from address <code>boolean</code> <code>&lt;nil&gt;</code> tlsHandshakeTimeout The maximum amount of time to wait for a successful TLS handshake <code>time.Duration</code> <code>10s</code> url The URL of the Address Resolver <code>string</code> <code>&lt;nil&gt;</code> urlTemplate The URL Go template string to use when calling the Address Resolver. The template input contains '.Key' and '.Intent' string variables. Go Template <code>string</code> <code>&lt;nil&gt;</code>"},{"location":"reference/config/#pluginsblockchainethereumaddressresolverauth","title":"plugins.blockchain[].ethereum.addressResolver.auth","text":"Key Description Type Default Value password Password <code>string</code> <code>&lt;nil&gt;</code> username Username <code>string</code> <code>&lt;nil&gt;</code>"},{"location":"reference/config/#pluginsblockchainethereumaddressresolverproxy","title":"plugins.blockchain[].ethereum.addressResolver.proxy","text":"Key Description Type Default Value url Optional HTTP proxy server to use when connecting to the Address Resolver URL <code>string</code> <code>&lt;nil&gt;</code>"},{"location":"reference/config/#pluginsblockchainethereumaddressresolverretry","title":"plugins.blockchain[].ethereum.addressResolver.retry","text":"Key Description Type Default Value count The maximum number of times to retry <code>int</code> <code>5</code> enabled Enables retries <code>boolean</code> <code>false</code> errorStatusCodeRegex The regex that the error response status code must match to trigger retry <code>string</code> <code>&lt;nil&gt;</code> initWaitTime The initial retry delay <code>time.Duration</code> <code>250ms</code> maxWaitTime The maximum retry delay <code>time.Duration</code> <code>30s</code>"},{"location":"reference/config/#pluginsblockchainethereumaddressresolverthrottle","title":"plugins.blockchain[].ethereum.addressResolver.throttle","text":"Key Description Type Default Value burst The maximum number of requests that can be made in a short period of time before the throttling kicks in. <code>int</code> <code>&lt;nil&gt;</code> requestsPerSecond The average rate at which requests are allowed to pass through over time. <code>int</code> <code>&lt;nil&gt;</code>"},{"location":"reference/config/#pluginsblockchainethereumaddressresolvertls","title":"plugins.blockchain[].ethereum.addressResolver.tls","text":"Key Description Type Default Value ca The TLS certificate authority in PEM format (this option is ignored if caFile is also set) <code>string</code> <code>&lt;nil&gt;</code> caFile The path to the CA file for TLS on this API <code>string</code> <code>&lt;nil&gt;</code> cert The TLS certificate in PEM format (this option is ignored if certFile is also set) <code>string</code> <code>&lt;nil&gt;</code> certFile The path to the certificate file for TLS on this API <code>string</code> <code>&lt;nil&gt;</code> clientAuth Enables or disables client auth for TLS on this API <code>string</code> <code>&lt;nil&gt;</code> enabled Enables or disables TLS on this API <code>boolean</code> <code>false</code> insecureSkipHostVerify When to true in unit test development environments to disable TLS verification. Use with extreme caution <code>boolean</code> <code>&lt;nil&gt;</code> key The TLS certificate key in PEM format (this option is ignored if keyFile is also set) <code>string</code> <code>&lt;nil&gt;</code> keyFile The path to the private key file for TLS on this API <code>string</code> <code>&lt;nil&gt;</code> requiredDNAttributes A set of required subject DN attributes. Each entry is a regular expression, and the subject certificate must have a matching attribute of the specified type (CN, C, O, OU, ST, L, STREET, POSTALCODE, SERIALNUMBER are valid attributes) <code>map[string]string</code> <code>&lt;nil&gt;</code>"},{"location":"reference/config/#pluginsblockchainethereumethconnect","title":"plugins.blockchain[].ethereum.ethconnect","text":"Key Description Type Default Value batchSize The number of events Ethconnect should batch together for delivery to FireFly core. Only applies when automatically creating a new event stream <code>int</code> <code>50</code> batchTimeout How long Ethconnect should wait for new events to arrive and fill a batch, before sending the batch to FireFly core. Only applies when automatically creating a new event stream <code>time.Duration</code> <code>500</code> connectionTimeout The maximum amount of time that a connection is allowed to remain with no data transmitted <code>time.Duration</code> <code>30s</code> expectContinueTimeout See ExpectContinueTimeout in the Go docs <code>time.Duration</code> <code>1s</code> fromBlock The first event this FireFly instance should listen to from the BatchPin smart contract. Default=0. Only affects initial creation of the event stream Address <code>string</code> <code>0</code> headers Adds custom headers to HTTP requests <code>map[string]string</code> <code>&lt;nil&gt;</code> idleTimeout The max duration to hold a HTTP keepalive connection between calls <code>time.Duration</code> <code>475ms</code> instance The Ethereum address of the FireFly BatchPin smart contract that has been deployed to the blockchain Address <code>string</code> <code>&lt;nil&gt;</code> maxConnsPerHost The max number of connections, per unique hostname. Zero means no limit <code>int</code> <code>0</code> maxIdleConns The max number of idle connections to hold pooled <code>int</code> <code>100</code> passthroughHeadersEnabled Enable passing through the set of allowed HTTP request headers <code>boolean</code> <code>false</code> prefixLong The prefix that will be used for Ethconnect specific HTTP headers when FireFly makes requests to Ethconnect <code>string</code> <code>firefly</code> prefixShort The prefix that will be used for Ethconnect specific query parameters when FireFly makes requests to Ethconnect <code>string</code> <code>fly</code> requestTimeout The maximum amount of time that a request is allowed to remain open <code>time.Duration</code> <code>30s</code> tlsHandshakeTimeout The maximum amount of time to wait for a successful TLS handshake <code>time.Duration</code> <code>10s</code> topic The websocket listen topic that the node should register on, which is important if there are multiple nodes using a single ethconnect <code>string</code> <code>&lt;nil&gt;</code> url The URL of the Ethconnect instance URL <code>string</code> <code>&lt;nil&gt;</code>"},{"location":"reference/config/#pluginsblockchainethereumethconnectauth","title":"plugins.blockchain[].ethereum.ethconnect.auth","text":"Key Description Type Default Value password Password <code>string</code> <code>&lt;nil&gt;</code> username Username <code>string</code> <code>&lt;nil&gt;</code>"},{"location":"reference/config/#pluginsblockchainethereumethconnectbackgroundstart","title":"plugins.blockchain[].ethereum.ethconnect.backgroundStart","text":"Key Description Type Default Value enabled Start the Ethconnect plugin in the background and enter retry loop if failed to start <code>boolean</code> <code>&lt;nil&gt;</code> factor Set the factor by which the delay increases when retrying <code>float32</code> <code>2</code> initialDelay Delay between restarts in the case where we retry to restart the ethereum plugin <code>time.Duration</code> <code>5s</code> maxDelay Max delay between restarts in the case where we retry to restart the ethereum plugin <code>time.Duration</code> <code>1m</code>"},{"location":"reference/config/#pluginsblockchainethereumethconnectproxy","title":"plugins.blockchain[].ethereum.ethconnect.proxy","text":"Key Description Type Default Value url Optional HTTP proxy server to use when connecting to Ethconnect URL <code>string</code> <code>&lt;nil&gt;</code>"},{"location":"reference/config/#pluginsblockchainethereumethconnectretry","title":"plugins.blockchain[].ethereum.ethconnect.retry","text":"Key Description Type Default Value count The maximum number of times to retry <code>int</code> <code>5</code> enabled Enables retries <code>boolean</code> <code>false</code> errorStatusCodeRegex The regex that the error response status code must match to trigger retry <code>string</code> <code>&lt;nil&gt;</code> initWaitTime The initial retry delay <code>time.Duration</code> <code>250ms</code> maxWaitTime The maximum retry delay <code>time.Duration</code> <code>30s</code>"},{"location":"reference/config/#pluginsblockchainethereumethconnectthrottle","title":"plugins.blockchain[].ethereum.ethconnect.throttle","text":"Key Description Type Default Value burst The maximum number of requests that can be made in a short period of time before the throttling kicks in. <code>int</code> <code>&lt;nil&gt;</code> requestsPerSecond The average rate at which requests are allowed to pass through over time. <code>int</code> <code>&lt;nil&gt;</code>"},{"location":"reference/config/#pluginsblockchainethereumethconnecttls","title":"plugins.blockchain[].ethereum.ethconnect.tls","text":"Key Description Type Default Value ca The TLS certificate authority in PEM format (this option is ignored if caFile is also set) <code>string</code> <code>&lt;nil&gt;</code> caFile The path to the CA file for TLS on this API <code>string</code> <code>&lt;nil&gt;</code> cert The TLS certificate in PEM format (this option is ignored if certFile is also set) <code>string</code> <code>&lt;nil&gt;</code> certFile The path to the certificate file for TLS on this API <code>string</code> <code>&lt;nil&gt;</code> clientAuth Enables or disables client auth for TLS on this API <code>string</code> <code>&lt;nil&gt;</code> enabled Enables or disables TLS on this API <code>boolean</code> <code>false</code> insecureSkipHostVerify When to true in unit test development environments to disable TLS verification. Use with extreme caution <code>boolean</code> <code>&lt;nil&gt;</code> key The TLS certificate key in PEM format (this option is ignored if keyFile is also set) <code>string</code> <code>&lt;nil&gt;</code> keyFile The path to the private key file for TLS on this API <code>string</code> <code>&lt;nil&gt;</code> requiredDNAttributes A set of required subject DN attributes. Each entry is a regular expression, and the subject certificate must have a matching attribute of the specified type (CN, C, O, OU, ST, L, STREET, POSTALCODE, SERIALNUMBER are valid attributes) <code>map[string]string</code> <code>&lt;nil&gt;</code>"},{"location":"reference/config/#pluginsblockchainethereumethconnectws","title":"plugins.blockchain[].ethereum.ethconnect.ws","text":"Key Description Type Default Value connectionTimeout The amount of time to wait while establishing a connection (or auto-reconnection) <code>time.Duration</code> <code>45s</code> heartbeatInterval The amount of time to wait between heartbeat signals on the WebSocket connection <code>time.Duration</code> <code>30s</code> initialConnectAttempts The number of attempts FireFly will make to connect to the WebSocket when starting up, before failing <code>int</code> <code>5</code> path The WebSocket sever URL to which FireFly should connect WebSocket URL <code>string</code> <code>&lt;nil&gt;</code> readBufferSize The size in bytes of the read buffer for the WebSocket connection <code>BytesSize</code> <code>16Kb</code> url URL to use for WebSocket - overrides url one level up (in the HTTP config) <code>string</code> <code>&lt;nil&gt;</code> writeBufferSize The size in bytes of the write buffer for the WebSocket connection <code>BytesSize</code> <code>16Kb</code>"},{"location":"reference/config/#pluginsblockchainethereumfftm","title":"plugins.blockchain[].ethereum.fftm","text":"Key Description Type Default Value connectionTimeout The maximum amount of time that a connection is allowed to remain with no data transmitted <code>time.Duration</code> <code>30s</code> expectContinueTimeout See ExpectContinueTimeout in the Go docs <code>time.Duration</code> <code>1s</code> headers Adds custom headers to HTTP requests <code>map[string]string</code> <code>&lt;nil&gt;</code> idleTimeout The max duration to hold a HTTP keepalive connection between calls <code>time.Duration</code> <code>475ms</code> maxConnsPerHost The max number of connections, per unique hostname. Zero means no limit <code>int</code> <code>0</code> maxIdleConns The max number of idle connections to hold pooled <code>int</code> <code>100</code> passthroughHeadersEnabled Enable passing through the set of allowed HTTP request headers <code>boolean</code> <code>false</code> requestTimeout The maximum amount of time that a request is allowed to remain open <code>time.Duration</code> <code>30s</code> tlsHandshakeTimeout The maximum amount of time to wait for a successful TLS handshake <code>time.Duration</code> <code>10s</code> url The URL of the FireFly Transaction Manager runtime, if enabled <code>string</code> <code>&lt;nil&gt;</code>"},{"location":"reference/config/#pluginsblockchainethereumfftmauth","title":"plugins.blockchain[].ethereum.fftm.auth","text":"Key Description Type Default Value password Password <code>string</code> <code>&lt;nil&gt;</code> username Username <code>string</code> <code>&lt;nil&gt;</code>"},{"location":"reference/config/#pluginsblockchainethereumfftmproxy","title":"plugins.blockchain[].ethereum.fftm.proxy","text":"Key Description Type Default Value url Optional HTTP proxy server to use when connecting to the Transaction Manager <code>string</code> <code>&lt;nil&gt;</code>"},{"location":"reference/config/#pluginsblockchainethereumfftmretry","title":"plugins.blockchain[].ethereum.fftm.retry","text":"Key Description Type Default Value count The maximum number of times to retry <code>int</code> <code>5</code> enabled Enables retries <code>boolean</code> <code>false</code> errorStatusCodeRegex The regex that the error response status code must match to trigger retry <code>string</code> <code>&lt;nil&gt;</code> initWaitTime The initial retry delay <code>time.Duration</code> <code>250ms</code> maxWaitTime The maximum retry delay <code>time.Duration</code> <code>30s</code>"},{"location":"reference/config/#pluginsblockchainethereumfftmthrottle","title":"plugins.blockchain[].ethereum.fftm.throttle","text":"Key Description Type Default Value burst The maximum number of requests that can be made in a short period of time before the throttling kicks in. <code>int</code> <code>&lt;nil&gt;</code> requestsPerSecond The average rate at which requests are allowed to pass through over time. <code>int</code> <code>&lt;nil&gt;</code>"},{"location":"reference/config/#pluginsblockchainethereumfftmtls","title":"plugins.blockchain[].ethereum.fftm.tls","text":"Key Description Type Default Value ca The TLS certificate authority in PEM format (this option is ignored if caFile is also set) <code>string</code> <code>&lt;nil&gt;</code> caFile The path to the CA file for TLS on this API <code>string</code> <code>&lt;nil&gt;</code> cert The TLS certificate in PEM format (this option is ignored if certFile is also set) <code>string</code> <code>&lt;nil&gt;</code> certFile The path to the certificate file for TLS on this API <code>string</code> <code>&lt;nil&gt;</code> clientAuth Enables or disables client auth for TLS on this API <code>string</code> <code>&lt;nil&gt;</code> enabled Enables or disables TLS on this API <code>boolean</code> <code>false</code> insecureSkipHostVerify When to true in unit test development environments to disable TLS verification. Use with extreme caution <code>boolean</code> <code>&lt;nil&gt;</code> key The TLS certificate key in PEM format (this option is ignored if keyFile is also set) <code>string</code> <code>&lt;nil&gt;</code> keyFile The path to the private key file for TLS on this API <code>string</code> <code>&lt;nil&gt;</code> requiredDNAttributes A set of required subject DN attributes. Each entry is a regular expression, and the subject certificate must have a matching attribute of the specified type (CN, C, O, OU, ST, L, STREET, POSTALCODE, SERIALNUMBER are valid attributes) <code>map[string]string</code> <code>&lt;nil&gt;</code>"},{"location":"reference/config/#pluginsblockchainfabricfabconnect","title":"plugins.blockchain[].fabric.fabconnect","text":"Key Description Type Default Value batchSize The number of events Fabconnect should batch together for delivery to FireFly core. Only applies when automatically creating a new event stream <code>int</code> <code>50</code> batchTimeout The maximum amount of time to wait for a batch to complete <code>time.Duration</code> <code>500</code> chaincode The name of the Fabric chaincode that FireFly will use for BatchPin transactions (deprecated - use fireflyContract[].chaincode) <code>string</code> <code>&lt;nil&gt;</code> channel The Fabric channel that FireFly will use for BatchPin transactions <code>string</code> <code>&lt;nil&gt;</code> connectionTimeout The maximum amount of time that a connection is allowed to remain with no data transmitted <code>time.Duration</code> <code>30s</code> expectContinueTimeout See ExpectContinueTimeout in the Go docs <code>time.Duration</code> <code>1s</code> headers Adds custom headers to HTTP requests <code>map[string]string</code> <code>&lt;nil&gt;</code> idleTimeout The max duration to hold a HTTP keepalive connection between calls <code>time.Duration</code> <code>475ms</code> maxConnsPerHost The max number of connections, per unique hostname. Zero means no limit <code>int</code> <code>0</code> maxIdleConns The max number of idle connections to hold pooled <code>int</code> <code>100</code> passthroughHeadersEnabled Enable passing through the set of allowed HTTP request headers <code>boolean</code> <code>false</code> prefixLong The prefix that will be used for Fabconnect specific HTTP headers when FireFly makes requests to Fabconnect <code>string</code> <code>firefly</code> prefixShort The prefix that will be used for Fabconnect specific query parameters when FireFly makes requests to Fabconnect <code>string</code> <code>fly</code> requestTimeout The maximum amount of time that a request is allowed to remain open <code>time.Duration</code> <code>30s</code> signer The Fabric signing key to use when submitting transactions to Fabconnect <code>string</code> <code>&lt;nil&gt;</code> tlsHandshakeTimeout The maximum amount of time to wait for a successful TLS handshake <code>time.Duration</code> <code>10s</code> topic The websocket listen topic that the node should register on, which is important if there are multiple nodes using a single Fabconnect <code>string</code> <code>&lt;nil&gt;</code> url The URL of the Fabconnect instance URL <code>string</code> <code>&lt;nil&gt;</code>"},{"location":"reference/config/#pluginsblockchainfabricfabconnectauth","title":"plugins.blockchain[].fabric.fabconnect.auth","text":"Key Description Type Default Value password Password <code>string</code> <code>&lt;nil&gt;</code> username Username <code>string</code> <code>&lt;nil&gt;</code>"},{"location":"reference/config/#pluginsblockchainfabricfabconnectbackgroundstart","title":"plugins.blockchain[].fabric.fabconnect.backgroundStart","text":"Key Description Type Default Value enabled Start the fabric plugin in the background and enter retry loop if failed to start <code>boolean</code> <code>&lt;nil&gt;</code> factor Set the factor by which the delay increases when retrying <code>float32</code> <code>2</code> initialDelay Delay between restarts in the case where we retry to restart the fabric plugin <code>time.Duration</code> <code>5s</code> maxDelay Max delay between restarts in the case where we retry to restart the fabric plugin <code>time.Duration</code> <code>1m</code>"},{"location":"reference/config/#pluginsblockchainfabricfabconnectproxy","title":"plugins.blockchain[].fabric.fabconnect.proxy","text":"Key Description Type Default Value url Optional HTTP proxy server to use when connecting to Fabconnect URL <code>string</code> <code>&lt;nil&gt;</code>"},{"location":"reference/config/#pluginsblockchainfabricfabconnectretry","title":"plugins.blockchain[].fabric.fabconnect.retry","text":"Key Description Type Default Value count The maximum number of times to retry <code>int</code> <code>5</code> enabled Enables retries <code>boolean</code> <code>false</code> errorStatusCodeRegex The regex that the error response status code must match to trigger retry <code>string</code> <code>&lt;nil&gt;</code> initWaitTime The initial retry delay <code>time.Duration</code> <code>250ms</code> maxWaitTime The maximum retry delay <code>time.Duration</code> <code>30s</code>"},{"location":"reference/config/#pluginsblockchainfabricfabconnectthrottle","title":"plugins.blockchain[].fabric.fabconnect.throttle","text":"Key Description Type Default Value burst The maximum number of requests that can be made in a short period of time before the throttling kicks in. <code>int</code> <code>&lt;nil&gt;</code> requestsPerSecond The average rate at which requests are allowed to pass through over time. <code>int</code> <code>&lt;nil&gt;</code>"},{"location":"reference/config/#pluginsblockchainfabricfabconnecttls","title":"plugins.blockchain[].fabric.fabconnect.tls","text":"Key Description Type Default Value ca The TLS certificate authority in PEM format (this option is ignored if caFile is also set) <code>string</code> <code>&lt;nil&gt;</code> caFile The path to the CA file for TLS on this API <code>string</code> <code>&lt;nil&gt;</code> cert The TLS certificate in PEM format (this option is ignored if certFile is also set) <code>string</code> <code>&lt;nil&gt;</code> certFile The path to the certificate file for TLS on this API <code>string</code> <code>&lt;nil&gt;</code> clientAuth Enables or disables client auth for TLS on this API <code>string</code> <code>&lt;nil&gt;</code> enabled Enables or disables TLS on this API <code>boolean</code> <code>false</code> insecureSkipHostVerify When to true in unit test development environments to disable TLS verification. Use with extreme caution <code>boolean</code> <code>&lt;nil&gt;</code> key The TLS certificate key in PEM format (this option is ignored if keyFile is also set) <code>string</code> <code>&lt;nil&gt;</code> keyFile The path to the private key file for TLS on this API <code>string</code> <code>&lt;nil&gt;</code> requiredDNAttributes A set of required subject DN attributes. Each entry is a regular expression, and the subject certificate must have a matching attribute of the specified type (CN, C, O, OU, ST, L, STREET, POSTALCODE, SERIALNUMBER are valid attributes) <code>map[string]string</code> <code>&lt;nil&gt;</code>"},{"location":"reference/config/#pluginsblockchainfabricfabconnectws","title":"plugins.blockchain[].fabric.fabconnect.ws","text":"Key Description Type Default Value connectionTimeout The amount of time to wait while establishing a connection (or auto-reconnection) <code>time.Duration</code> <code>45s</code> heartbeatInterval The amount of time to wait between heartbeat signals on the WebSocket connection <code>time.Duration</code> <code>30s</code> initialConnectAttempts The number of attempts FireFly will make to connect to the WebSocket when starting up, before failing <code>int</code> <code>5</code> path The WebSocket sever URL to which FireFly should connect WebSocket URL <code>string</code> <code>&lt;nil&gt;</code> readBufferSize The size in bytes of the read buffer for the WebSocket connection <code>BytesSize</code> <code>16Kb</code> url URL to use for WebSocket - overrides url one level up (in the HTTP config) <code>string</code> <code>&lt;nil&gt;</code> writeBufferSize The size in bytes of the write buffer for the WebSocket connection <code>BytesSize</code> <code>16Kb</code>"},{"location":"reference/config/#pluginsblockchaintezosaddressresolver","title":"plugins.blockchain[].tezos.addressResolver","text":"Key Description Type Default Value alwaysResolve Causes the address resolver to be invoked on every API call that submits a signing key. Also disables any result caching <code>boolean</code> <code>&lt;nil&gt;</code> bodyTemplate The body go template string to use when making HTTP requests Go Template <code>string</code> <code>&lt;nil&gt;</code> connectionTimeout The maximum amount of time that a connection is allowed to remain with no data transmitted <code>time.Duration</code> <code>30s</code> expectContinueTimeout See ExpectContinueTimeout in the Go docs <code>time.Duration</code> <code>1s</code> headers Adds custom headers to HTTP requests <code>map[string]string</code> <code>&lt;nil&gt;</code> idleTimeout The max duration to hold a HTTP keepalive connection between calls <code>time.Duration</code> <code>475ms</code> maxConnsPerHost The max number of connections, per unique hostname. Zero means no limit <code>int</code> <code>0</code> maxIdleConns The max number of idle connections to hold pooled <code>int</code> <code>100</code> method The HTTP method to use when making requests to the Address Resolver <code>string</code> <code>GET</code> passthroughHeadersEnabled Enable passing through the set of allowed HTTP request headers <code>boolean</code> <code>false</code> requestTimeout The maximum amount of time that a request is allowed to remain open <code>time.Duration</code> <code>30s</code> responseField The name of a JSON field that is provided in the response, that contains the tezos address (default <code>address</code>) <code>string</code> <code>address</code> retainOriginal When true the original pre-resolved string is retained after the lookup, and passed down to Tezosconnect as the from address <code>boolean</code> <code>&lt;nil&gt;</code> tlsHandshakeTimeout The maximum amount of time to wait for a successful TLS handshake <code>time.Duration</code> <code>10s</code> url The URL of the Address Resolver <code>string</code> <code>&lt;nil&gt;</code> urlTemplate The URL Go template string to use when calling the Address Resolver. The template input contains '.Key' and '.Intent' string variables. Go Template <code>string</code> <code>&lt;nil&gt;</code>"},{"location":"reference/config/#pluginsblockchaintezosaddressresolverauth","title":"plugins.blockchain[].tezos.addressResolver.auth","text":"Key Description Type Default Value password Password <code>string</code> <code>&lt;nil&gt;</code> username Username <code>string</code> <code>&lt;nil&gt;</code>"},{"location":"reference/config/#pluginsblockchaintezosaddressresolverproxy","title":"plugins.blockchain[].tezos.addressResolver.proxy","text":"Key Description Type Default Value url Optional HTTP proxy server to connect through <code>string</code> <code>&lt;nil&gt;</code>"},{"location":"reference/config/#pluginsblockchaintezosaddressresolverretry","title":"plugins.blockchain[].tezos.addressResolver.retry","text":"Key Description Type Default Value count The maximum number of times to retry <code>int</code> <code>5</code> enabled Enables retries <code>boolean</code> <code>false</code> errorStatusCodeRegex The regex that the error response status code must match to trigger retry <code>string</code> <code>&lt;nil&gt;</code> initWaitTime The initial retry delay <code>time.Duration</code> <code>250ms</code> maxWaitTime The maximum retry delay <code>time.Duration</code> <code>30s</code>"},{"location":"reference/config/#pluginsblockchaintezosaddressresolverthrottle","title":"plugins.blockchain[].tezos.addressResolver.throttle","text":"Key Description Type Default Value burst The maximum number of requests that can be made in a short period of time before the throttling kicks in. <code>int</code> <code>&lt;nil&gt;</code> requestsPerSecond The average rate at which requests are allowed to pass through over time. <code>int</code> <code>&lt;nil&gt;</code>"},{"location":"reference/config/#pluginsblockchaintezosaddressresolvertls","title":"plugins.blockchain[].tezos.addressResolver.tls","text":"Key Description Type Default Value ca The TLS certificate authority in PEM format (this option is ignored if caFile is also set) <code>string</code> <code>&lt;nil&gt;</code> caFile The path to the CA file for TLS on this API <code>string</code> <code>&lt;nil&gt;</code> cert The TLS certificate in PEM format (this option is ignored if certFile is also set) <code>string</code> <code>&lt;nil&gt;</code> certFile The path to the certificate file for TLS on this API <code>string</code> <code>&lt;nil&gt;</code> clientAuth Enables or disables client auth for TLS on this API <code>string</code> <code>&lt;nil&gt;</code> enabled Enables or disables TLS on this API <code>boolean</code> <code>false</code> insecureSkipHostVerify When to true in unit test development environments to disable TLS verification. Use with extreme caution <code>boolean</code> <code>&lt;nil&gt;</code> key The TLS certificate key in PEM format (this option is ignored if keyFile is also set) <code>string</code> <code>&lt;nil&gt;</code> keyFile The path to the private key file for TLS on this API <code>string</code> <code>&lt;nil&gt;</code> requiredDNAttributes A set of required subject DN attributes. Each entry is a regular expression, and the subject certificate must have a matching attribute of the specified type (CN, C, O, OU, ST, L, STREET, POSTALCODE, SERIALNUMBER are valid attributes) <code>map[string]string</code> <code>&lt;nil&gt;</code>"},{"location":"reference/config/#pluginsblockchaintezostezosconnect","title":"plugins.blockchain[].tezos.tezosconnect","text":"Key Description Type Default Value batchSize The number of events Tezosconnect should batch together for delivery to FireFly core. Only applies when automatically creating a new event stream <code>int</code> <code>50</code> batchTimeout How long Tezosconnect should wait for new events to arrive and fill a batch, before sending the batch to FireFly core. Only applies when automatically creating a new event stream <code>time.Duration</code> <code>500</code> connectionTimeout The maximum amount of time that a connection is allowed to remain with no data transmitted <code>time.Duration</code> <code>30s</code> expectContinueTimeout See ExpectContinueTimeout in the Go docs <code>time.Duration</code> <code>1s</code> headers Adds custom headers to HTTP requests <code>map[string]string</code> <code>&lt;nil&gt;</code> idleTimeout The max duration to hold a HTTP keepalive connection between calls <code>time.Duration</code> <code>475ms</code> maxConnsPerHost The max number of connections, per unique hostname. Zero means no limit <code>int</code> <code>0</code> maxIdleConns The max number of idle connections to hold pooled <code>int</code> <code>100</code> passthroughHeadersEnabled Enable passing through the set of allowed HTTP request headers <code>boolean</code> <code>false</code> prefixLong The prefix that will be used for Tezosconnect specific HTTP headers when FireFly makes requests to Tezosconnect <code>string</code> <code>firefly</code> prefixShort The prefix that will be used for Tezosconnect specific query parameters when FireFly makes requests to Tezosconnect <code>string</code> <code>fly</code> requestTimeout The maximum amount of time that a request is allowed to remain open <code>time.Duration</code> <code>30s</code> tlsHandshakeTimeout The maximum amount of time to wait for a successful TLS handshake <code>time.Duration</code> <code>10s</code> topic The websocket listen topic that the node should register on, which is important if there are multiple nodes using a single tezosconnect <code>string</code> <code>&lt;nil&gt;</code> url The URL of the Tezosconnect instance URL <code>string</code> <code>&lt;nil&gt;</code>"},{"location":"reference/config/#pluginsblockchaintezostezosconnectauth","title":"plugins.blockchain[].tezos.tezosconnect.auth","text":"Key Description Type Default Value password Password <code>string</code> <code>&lt;nil&gt;</code> username Username <code>string</code> <code>&lt;nil&gt;</code>"},{"location":"reference/config/#pluginsblockchaintezostezosconnectbackgroundstart","title":"plugins.blockchain[].tezos.tezosconnect.backgroundStart","text":"Key Description Type Default Value enabled Start the Tezosconnect plugin in the background and enter retry loop if failed to start <code>boolean</code> <code>&lt;nil&gt;</code> factor Set the factor by which the delay increases when retrying <code>float32</code> <code>2</code> initialDelay Delay between restarts in the case where we retry to restart the tezos plugin <code>time.Duration</code> <code>5s</code> maxDelay Max delay between restarts in the case where we retry to restart the tezos plugin <code>time.Duration</code> <code>1m</code>"},{"location":"reference/config/#pluginsblockchaintezostezosconnectproxy","title":"plugins.blockchain[].tezos.tezosconnect.proxy","text":"Key Description Type Default Value url Optional HTTP proxy server to use when connecting to Tezosconnect URL <code>string</code> <code>&lt;nil&gt;</code>"},{"location":"reference/config/#pluginsblockchaintezostezosconnectretry","title":"plugins.blockchain[].tezos.tezosconnect.retry","text":"Key Description Type Default Value count The maximum number of times to retry <code>int</code> <code>5</code> enabled Enables retries <code>boolean</code> <code>false</code> errorStatusCodeRegex The regex that the error response status code must match to trigger retry <code>string</code> <code>&lt;nil&gt;</code> initWaitTime The initial retry delay <code>time.Duration</code> <code>250ms</code> maxWaitTime The maximum retry delay <code>time.Duration</code> <code>30s</code>"},{"location":"reference/config/#pluginsblockchaintezostezosconnectthrottle","title":"plugins.blockchain[].tezos.tezosconnect.throttle","text":"Key Description Type Default Value burst The maximum number of requests that can be made in a short period of time before the throttling kicks in. <code>int</code> <code>&lt;nil&gt;</code> requestsPerSecond The average rate at which requests are allowed to pass through over time. <code>int</code> <code>&lt;nil&gt;</code>"},{"location":"reference/config/#pluginsblockchaintezostezosconnecttls","title":"plugins.blockchain[].tezos.tezosconnect.tls","text":"Key Description Type Default Value ca The TLS certificate authority in PEM format (this option is ignored if caFile is also set) <code>string</code> <code>&lt;nil&gt;</code> caFile The path to the CA file for TLS on this API <code>string</code> <code>&lt;nil&gt;</code> cert The TLS certificate in PEM format (this option is ignored if certFile is also set) <code>string</code> <code>&lt;nil&gt;</code> certFile The path to the certificate file for TLS on this API <code>string</code> <code>&lt;nil&gt;</code> clientAuth Enables or disables client auth for TLS on this API <code>string</code> <code>&lt;nil&gt;</code> enabled Enables or disables TLS on this API <code>boolean</code> <code>false</code> insecureSkipHostVerify When to true in unit test development environments to disable TLS verification. Use with extreme caution <code>boolean</code> <code>&lt;nil&gt;</code> key The TLS certificate key in PEM format (this option is ignored if keyFile is also set) <code>string</code> <code>&lt;nil&gt;</code> keyFile The path to the private key file for TLS on this API <code>string</code> <code>&lt;nil&gt;</code> requiredDNAttributes A set of required subject DN attributes. Each entry is a regular expression, and the subject certificate must have a matching attribute of the specified type (CN, C, O, OU, ST, L, STREET, POSTALCODE, SERIALNUMBER are valid attributes) <code>map[string]string</code> <code>&lt;nil&gt;</code>"},{"location":"reference/config/#pluginsblockchaintezostezosconnectws","title":"plugins.blockchain[].tezos.tezosconnect.ws","text":"Key Description Type Default Value connectionTimeout The amount of time to wait while establishing a connection (or auto-reconnection) <code>time.Duration</code> <code>45s</code> heartbeatInterval The amount of time to wait between heartbeat signals on the WebSocket connection <code>time.Duration</code> <code>30s</code> initialConnectAttempts The number of attempts FireFly will make to connect to the WebSocket when starting up, before failing <code>int</code> <code>5</code> path The WebSocket sever URL to which FireFly should connect WebSocket URL <code>string</code> <code>&lt;nil&gt;</code> readBufferSize The size in bytes of the read buffer for the WebSocket connection <code>BytesSize</code> <code>16Kb</code> url URL to use for WebSocket - overrides url one level up (in the HTTP config) <code>string</code> <code>&lt;nil&gt;</code> writeBufferSize The size in bytes of the write buffer for the WebSocket connection <code>BytesSize</code> <code>16Kb</code>"},{"location":"reference/config/#pluginsdatabase","title":"plugins.database[]","text":"Key Description Type Default Value name The name of the Database plugin <code>string</code> <code>&lt;nil&gt;</code> type The type of the configured Database plugin <code>string</code> <code>&lt;nil&gt;</code>"},{"location":"reference/config/#pluginsdatabasepostgres","title":"plugins.database[].postgres","text":"Key Description Type Default Value maxConnIdleTime The maximum amount of time a database connection can be idle <code>time.Duration</code> <code>1m</code> maxConnLifetime The maximum amount of time to keep a database connection open <code>time.Duration</code> <code>&lt;nil&gt;</code> maxConns Maximum connections to the database <code>int</code> <code>50</code> maxIdleConns The maximum number of idle connections to the database <code>int</code> <code>&lt;nil&gt;</code> url The PostgreSQL connection string for the database <code>string</code> <code>&lt;nil&gt;</code>"},{"location":"reference/config/#pluginsdatabasepostgresmigrations","title":"plugins.database[].postgres.migrations","text":"Key Description Type Default Value auto Enables automatic database migrations <code>boolean</code> <code>false</code> directory The directory containing the numerically ordered migration DDL files to apply to the database <code>string</code> <code>./db/migrations/postgres</code>"},{"location":"reference/config/#pluginsdatabasesqlite3","title":"plugins.database[].sqlite3","text":"Key Description Type Default Value maxConnIdleTime The maximum amount of time a database connection can be idle <code>time.Duration</code> <code>1m</code> maxConnLifetime The maximum amount of time to keep a database connection open <code>time.Duration</code> <code>&lt;nil&gt;</code> maxConns Maximum connections to the database <code>int</code> <code>1</code> maxIdleConns The maximum number of idle connections to the database <code>int</code> <code>&lt;nil&gt;</code> url The SQLite connection string for the database <code>string</code> <code>&lt;nil&gt;</code>"},{"location":"reference/config/#pluginsdatabasesqlite3migrations","title":"plugins.database[].sqlite3.migrations","text":"Key Description Type Default Value auto Enables automatic database migrations <code>boolean</code> <code>false</code> directory The directory containing the numerically ordered migration DDL files to apply to the database <code>string</code> <code>./db/migrations/sqlite</code>"},{"location":"reference/config/#pluginsdataexchange","title":"plugins.dataexchange[]","text":"Key Description Type Default Value name The name of the configured Data Exchange plugin <code>string</code> <code>&lt;nil&gt;</code> type The Data Exchange plugin to use <code>string</code> <code>&lt;nil&gt;</code>"},{"location":"reference/config/#pluginsdataexchangeffdx","title":"plugins.dataexchange[].ffdx","text":"Key Description Type Default Value connectionTimeout The maximum amount of time that a connection is allowed to remain with no data transmitted <code>time.Duration</code> <code>30s</code> expectContinueTimeout See ExpectContinueTimeout in the Go docs <code>time.Duration</code> <code>1s</code> headers Adds custom headers to HTTP requests <code>map[string]string</code> <code>&lt;nil&gt;</code> idleTimeout The max duration to hold a HTTP keepalive connection between calls <code>time.Duration</code> <code>475ms</code> initEnabled Instructs FireFly to always post all current nodes to the <code>/init</code> API before connecting or reconnecting to the connector <code>boolean</code> <code>false</code> manifestEnabled Determines whether to require+validate a manifest from other DX instances in the network. Must be supported by the connector <code>string</code> <code>false</code> maxConnsPerHost The max number of connections, per unique hostname. Zero means no limit <code>int</code> <code>0</code> maxIdleConns The max number of idle connections to hold pooled <code>int</code> <code>100</code> passthroughHeadersEnabled Enable passing through the set of allowed HTTP request headers <code>boolean</code> <code>false</code> requestTimeout The maximum amount of time that a request is allowed to remain open <code>time.Duration</code> <code>30s</code> tlsHandshakeTimeout The maximum amount of time to wait for a successful TLS handshake <code>time.Duration</code> <code>10s</code> url The URL of the Data Exchange instance URL <code>string</code> <code>&lt;nil&gt;</code>"},{"location":"reference/config/#pluginsdataexchangeffdxauth","title":"plugins.dataexchange[].ffdx.auth","text":"Key Description Type Default Value password Password <code>string</code> <code>&lt;nil&gt;</code> username Username <code>string</code> <code>&lt;nil&gt;</code>"},{"location":"reference/config/#pluginsdataexchangeffdxbackgroundstart","title":"plugins.dataexchange[].ffdx.backgroundStart","text":"Key Description Type Default Value enabled Start the data exchange plugin in the background and enter retry loop if failed to start <code>boolean</code> <code>false</code> factor Set the factor by which the delay increases when retrying <code>float32</code> <code>2</code> initialDelay Delay between restarts in the case where we retry to restart the data exchange plugin <code>time.Duration</code> <code>5s</code> maxDelay Max delay between restarts in the case where we retry to restart the data exchange plugin <code>time.Duration</code> <code>1m</code>"},{"location":"reference/config/#pluginsdataexchangeffdxeventretry","title":"plugins.dataexchange[].ffdx.eventRetry","text":"Key Description Type Default Value factor The retry backoff factor, for event processing <code>float32</code> <code>2</code> initialDelay The initial retry delay, for event processing <code>time.Duration</code> <code>50ms</code> maxDelay The maximum retry delay, for event processing <code>time.Duration</code> <code>30s</code>"},{"location":"reference/config/#pluginsdataexchangeffdxproxy","title":"plugins.dataexchange[].ffdx.proxy","text":"Key Description Type Default Value url Optional HTTP proxy server to use when connecting to the Data Exchange URL <code>string</code> <code>&lt;nil&gt;</code>"},{"location":"reference/config/#pluginsdataexchangeffdxretry","title":"plugins.dataexchange[].ffdx.retry","text":"Key Description Type Default Value count The maximum number of times to retry <code>int</code> <code>5</code> enabled Enables retries <code>boolean</code> <code>false</code> errorStatusCodeRegex The regex that the error response status code must match to trigger retry <code>string</code> <code>&lt;nil&gt;</code> initWaitTime The initial retry delay <code>time.Duration</code> <code>250ms</code> maxWaitTime The maximum retry delay <code>time.Duration</code> <code>30s</code>"},{"location":"reference/config/#pluginsdataexchangeffdxthrottle","title":"plugins.dataexchange[].ffdx.throttle","text":"Key Description Type Default Value burst The maximum number of requests that can be made in a short period of time before the throttling kicks in. <code>int</code> <code>&lt;nil&gt;</code> requestsPerSecond The average rate at which requests are allowed to pass through over time. <code>int</code> <code>&lt;nil&gt;</code>"},{"location":"reference/config/#pluginsdataexchangeffdxtls","title":"plugins.dataexchange[].ffdx.tls","text":"Key Description Type Default Value ca The TLS certificate authority in PEM format (this option is ignored if caFile is also set) <code>string</code> <code>&lt;nil&gt;</code> caFile The path to the CA file for TLS on this API <code>string</code> <code>&lt;nil&gt;</code> cert The TLS certificate in PEM format (this option is ignored if certFile is also set) <code>string</code> <code>&lt;nil&gt;</code> certFile The path to the certificate file for TLS on this API <code>string</code> <code>&lt;nil&gt;</code> clientAuth Enables or disables client auth for TLS on this API <code>string</code> <code>&lt;nil&gt;</code> enabled Enables or disables TLS on this API <code>boolean</code> <code>false</code> insecureSkipHostVerify When to true in unit test development environments to disable TLS verification. Use with extreme caution <code>boolean</code> <code>&lt;nil&gt;</code> key The TLS certificate key in PEM format (this option is ignored if keyFile is also set) <code>string</code> <code>&lt;nil&gt;</code> keyFile The path to the private key file for TLS on this API <code>string</code> <code>&lt;nil&gt;</code> requiredDNAttributes A set of required subject DN attributes. Each entry is a regular expression, and the subject certificate must have a matching attribute of the specified type (CN, C, O, OU, ST, L, STREET, POSTALCODE, SERIALNUMBER are valid attributes) <code>map[string]string</code> <code>&lt;nil&gt;</code>"},{"location":"reference/config/#pluginsdataexchangeffdxws","title":"plugins.dataexchange[].ffdx.ws","text":"Key Description Type Default Value connectionTimeout The amount of time to wait while establishing a connection (or auto-reconnection) <code>time.Duration</code> <code>45s</code> heartbeatInterval The amount of time to wait between heartbeat signals on the WebSocket connection <code>time.Duration</code> <code>30s</code> initialConnectAttempts The number of attempts FireFly will make to connect to the WebSocket when starting up, before failing <code>int</code> <code>5</code> path The WebSocket sever URL to which FireFly should connect WebSocket URL <code>string</code> <code>&lt;nil&gt;</code> readBufferSize The size in bytes of the read buffer for the WebSocket connection <code>BytesSize</code> <code>16Kb</code> url URL to use for WebSocket - overrides url one level up (in the HTTP config) <code>string</code> <code>&lt;nil&gt;</code> writeBufferSize The size in bytes of the write buffer for the WebSocket connection <code>BytesSize</code> <code>16Kb</code>"},{"location":"reference/config/#pluginsidentity","title":"plugins.identity[]","text":"Key Description Type Default Value name The name of a configured Identity plugin <code>string</code> <code>&lt;nil&gt;</code> type The type of a configured Identity plugin <code>string</code> <code>&lt;nil&gt;</code>"},{"location":"reference/config/#pluginssharedstorage","title":"plugins.sharedstorage[]","text":"Key Description Type Default Value name The name of the Shared Storage plugin to use <code>string</code> <code>&lt;nil&gt;</code> type The Shared Storage plugin to use <code>string</code> <code>&lt;nil&gt;</code>"},{"location":"reference/config/#pluginssharedstorageipfsapi","title":"plugins.sharedstorage[].ipfs.api","text":"Key Description Type Default Value connectionTimeout The maximum amount of time that a connection is allowed to remain with no data transmitted <code>time.Duration</code> <code>30s</code> expectContinueTimeout See ExpectContinueTimeout in the Go docs <code>time.Duration</code> <code>1s</code> headers Adds custom headers to HTTP requests <code>map[string]string</code> <code>&lt;nil&gt;</code> idleTimeout The max duration to hold a HTTP keepalive connection between calls <code>time.Duration</code> <code>475ms</code> maxConnsPerHost The max number of connections, per unique hostname. Zero means no limit <code>int</code> <code>0</code> maxIdleConns The max number of idle connections to hold pooled <code>int</code> <code>100</code> passthroughHeadersEnabled Enable passing through the set of allowed HTTP request headers <code>boolean</code> <code>false</code> requestTimeout The maximum amount of time that a request is allowed to remain open <code>time.Duration</code> <code>30s</code> tlsHandshakeTimeout The maximum amount of time to wait for a successful TLS handshake <code>time.Duration</code> <code>10s</code> url The URL for the IPFS API URL <code>string</code> <code>&lt;nil&gt;</code>"},{"location":"reference/config/#pluginssharedstorageipfsapiauth","title":"plugins.sharedstorage[].ipfs.api.auth","text":"Key Description Type Default Value password Password <code>string</code> <code>&lt;nil&gt;</code> username Username <code>string</code> <code>&lt;nil&gt;</code>"},{"location":"reference/config/#pluginssharedstorageipfsapiproxy","title":"plugins.sharedstorage[].ipfs.api.proxy","text":"Key Description Type Default Value url Optional HTTP proxy server to use when connecting to the IPFS API URL <code>string</code> <code>&lt;nil&gt;</code>"},{"location":"reference/config/#pluginssharedstorageipfsapiretry","title":"plugins.sharedstorage[].ipfs.api.retry","text":"Key Description Type Default Value count The maximum number of times to retry <code>int</code> <code>5</code> enabled Enables retries <code>boolean</code> <code>false</code> errorStatusCodeRegex The regex that the error response status code must match to trigger retry <code>string</code> <code>&lt;nil&gt;</code> initWaitTime The initial retry delay <code>time.Duration</code> <code>250ms</code> maxWaitTime The maximum retry delay <code>time.Duration</code> <code>30s</code>"},{"location":"reference/config/#pluginssharedstorageipfsapithrottle","title":"plugins.sharedstorage[].ipfs.api.throttle","text":"Key Description Type Default Value burst The maximum number of requests that can be made in a short period of time before the throttling kicks in. <code>int</code> <code>&lt;nil&gt;</code> requestsPerSecond The average rate at which requests are allowed to pass through over time. <code>int</code> <code>&lt;nil&gt;</code>"},{"location":"reference/config/#pluginssharedstorageipfsapitls","title":"plugins.sharedstorage[].ipfs.api.tls","text":"Key Description Type Default Value ca The TLS certificate authority in PEM format (this option is ignored if caFile is also set) <code>string</code> <code>&lt;nil&gt;</code> caFile The path to the CA file for TLS on this API <code>string</code> <code>&lt;nil&gt;</code> cert The TLS certificate in PEM format (this option is ignored if certFile is also set) <code>string</code> <code>&lt;nil&gt;</code> certFile The path to the certificate file for TLS on this API <code>string</code> <code>&lt;nil&gt;</code> clientAuth Enables or disables client auth for TLS on this API <code>string</code> <code>&lt;nil&gt;</code> enabled Enables or disables TLS on this API <code>boolean</code> <code>false</code> insecureSkipHostVerify When to true in unit test development environments to disable TLS verification. Use with extreme caution <code>boolean</code> <code>&lt;nil&gt;</code> key The TLS certificate key in PEM format (this option is ignored if keyFile is also set) <code>string</code> <code>&lt;nil&gt;</code> keyFile The path to the private key file for TLS on this API <code>string</code> <code>&lt;nil&gt;</code> requiredDNAttributes A set of required subject DN attributes. Each entry is a regular expression, and the subject certificate must have a matching attribute of the specified type (CN, C, O, OU, ST, L, STREET, POSTALCODE, SERIALNUMBER are valid attributes) <code>map[string]string</code> <code>&lt;nil&gt;</code>"},{"location":"reference/config/#pluginssharedstorageipfsgateway","title":"plugins.sharedstorage[].ipfs.gateway","text":"Key Description Type Default Value connectionTimeout The maximum amount of time that a connection is allowed to remain with no data transmitted <code>time.Duration</code> <code>30s</code> expectContinueTimeout See ExpectContinueTimeout in the Go docs <code>time.Duration</code> <code>1s</code> headers Adds custom headers to HTTP requests <code>map[string]string</code> <code>&lt;nil&gt;</code> idleTimeout The max duration to hold a HTTP keepalive connection between calls <code>time.Duration</code> <code>475ms</code> maxConnsPerHost The max number of connections, per unique hostname. Zero means no limit <code>int</code> <code>0</code> maxIdleConns The max number of idle connections to hold pooled <code>int</code> <code>100</code> passthroughHeadersEnabled Enable passing through the set of allowed HTTP request headers <code>boolean</code> <code>false</code> requestTimeout The maximum amount of time that a request is allowed to remain open <code>time.Duration</code> <code>30s</code> tlsHandshakeTimeout The maximum amount of time to wait for a successful TLS handshake <code>time.Duration</code> <code>10s</code> url The URL for the IPFS Gateway URL <code>string</code> <code>&lt;nil&gt;</code>"},{"location":"reference/config/#pluginssharedstorageipfsgatewayauth","title":"plugins.sharedstorage[].ipfs.gateway.auth","text":"Key Description Type Default Value password Password <code>string</code> <code>&lt;nil&gt;</code> username Username <code>string</code> <code>&lt;nil&gt;</code>"},{"location":"reference/config/#pluginssharedstorageipfsgatewayproxy","title":"plugins.sharedstorage[].ipfs.gateway.proxy","text":"Key Description Type Default Value url Optional HTTP proxy server to use when connecting to the IPFS Gateway URL <code>string</code> <code>&lt;nil&gt;</code>"},{"location":"reference/config/#pluginssharedstorageipfsgatewayretry","title":"plugins.sharedstorage[].ipfs.gateway.retry","text":"Key Description Type Default Value count The maximum number of times to retry <code>int</code> <code>5</code> enabled Enables retries <code>boolean</code> <code>false</code> errorStatusCodeRegex The regex that the error response status code must match to trigger retry <code>string</code> <code>&lt;nil&gt;</code> initWaitTime The initial retry delay <code>time.Duration</code> <code>250ms</code> maxWaitTime The maximum retry delay <code>time.Duration</code> <code>30s</code>"},{"location":"reference/config/#pluginssharedstorageipfsgatewaythrottle","title":"plugins.sharedstorage[].ipfs.gateway.throttle","text":"Key Description Type Default Value burst The maximum number of requests that can be made in a short period of time before the throttling kicks in. <code>int</code> <code>&lt;nil&gt;</code> requestsPerSecond The average rate at which requests are allowed to pass through over time. <code>int</code> <code>&lt;nil&gt;</code>"},{"location":"reference/config/#pluginssharedstorageipfsgatewaytls","title":"plugins.sharedstorage[].ipfs.gateway.tls","text":"Key Description Type Default Value ca The TLS certificate authority in PEM format (this option is ignored if caFile is also set) <code>string</code> <code>&lt;nil&gt;</code> caFile The path to the CA file for TLS on this API <code>string</code> <code>&lt;nil&gt;</code> cert The TLS certificate in PEM format (this option is ignored if certFile is also set) <code>string</code> <code>&lt;nil&gt;</code> certFile The path to the certificate file for TLS on this API <code>string</code> <code>&lt;nil&gt;</code> clientAuth Enables or disables client auth for TLS on this API <code>string</code> <code>&lt;nil&gt;</code> enabled Enables or disables TLS on this API <code>boolean</code> <code>false</code> insecureSkipHostVerify When to true in unit test development environments to disable TLS verification. Use with extreme caution <code>boolean</code> <code>&lt;nil&gt;</code> key The TLS certificate key in PEM format (this option is ignored if keyFile is also set) <code>string</code> <code>&lt;nil&gt;</code> keyFile The path to the private key file for TLS on this API <code>string</code> <code>&lt;nil&gt;</code> requiredDNAttributes A set of required subject DN attributes. Each entry is a regular expression, and the subject certificate must have a matching attribute of the specified type (CN, C, O, OU, ST, L, STREET, POSTALCODE, SERIALNUMBER are valid attributes) <code>map[string]string</code> <code>&lt;nil&gt;</code>"},{"location":"reference/config/#pluginstokens","title":"plugins.tokens[]","text":"Key Description Type Default Value broadcastName The name to be used in broadcast messages related to this token plugin, if it differs from the local plugin name <code>string</code> <code>&lt;nil&gt;</code> name A name to identify this token plugin <code>string</code> <code>&lt;nil&gt;</code> type The type of the token plugin to use <code>string</code> <code>&lt;nil&gt;</code>"},{"location":"reference/config/#pluginstokensfftokens","title":"plugins.tokens[].fftokens","text":"Key Description Type Default Value connectionTimeout The maximum amount of time that a connection is allowed to remain with no data transmitted <code>time.Duration</code> <code>30s</code> expectContinueTimeout See ExpectContinueTimeout in the Go docs <code>time.Duration</code> <code>1s</code> headers Adds custom headers to HTTP requests <code>map[string]string</code> <code>&lt;nil&gt;</code> idleTimeout The max duration to hold a HTTP keepalive connection between calls <code>time.Duration</code> <code>475ms</code> maxConnsPerHost The max number of connections, per unique hostname. Zero means no limit <code>int</code> <code>0</code> maxIdleConns The max number of idle connections to hold pooled <code>int</code> <code>100</code> passthroughHeadersEnabled Enable passing through the set of allowed HTTP request headers <code>boolean</code> <code>false</code> requestTimeout The maximum amount of time that a request is allowed to remain open <code>time.Duration</code> <code>30s</code> tlsHandshakeTimeout The maximum amount of time to wait for a successful TLS handshake <code>time.Duration</code> <code>10s</code> url The URL of the token connector URL <code>string</code> <code>&lt;nil&gt;</code>"},{"location":"reference/config/#pluginstokensfftokensauth","title":"plugins.tokens[].fftokens.auth","text":"Key Description Type Default Value password Password <code>string</code> <code>&lt;nil&gt;</code> username Username <code>string</code> <code>&lt;nil&gt;</code>"},{"location":"reference/config/#pluginstokensfftokensbackgroundstart","title":"plugins.tokens[].fftokens.backgroundStart","text":"Key Description Type Default Value enabled Start the tokens plugin in the background and enter retry loop if failed to start <code>boolean</code> <code>false</code> factor Set the factor by which the delay increases when retrying <code>float32</code> <code>2</code> initialDelay Delay between restarts in the case where we retry to restart the token plugin <code>time.Duration</code> <code>5s</code> maxDelay Max delay between restarts in the case where we retry to restart the token plugin <code>time.Duration</code> <code>1m</code>"},{"location":"reference/config/#pluginstokensfftokenseventretry","title":"plugins.tokens[].fftokens.eventRetry","text":"Key Description Type Default Value factor The retry backoff factor, for event processing <code>float32</code> <code>2</code> initialDelay The initial retry delay, for event processing <code>time.Duration</code> <code>50ms</code> maxDelay The maximum retry delay, for event processing <code>time.Duration</code> <code>30s</code>"},{"location":"reference/config/#pluginstokensfftokensproxy","title":"plugins.tokens[].fftokens.proxy","text":"Key Description Type Default Value url Optional HTTP proxy server to use when connecting to the token connector URL <code>string</code> <code>&lt;nil&gt;</code>"},{"location":"reference/config/#pluginstokensfftokensretry","title":"plugins.tokens[].fftokens.retry","text":"Key Description Type Default Value count The maximum number of times to retry <code>int</code> <code>5</code> enabled Enables retries <code>boolean</code> <code>false</code> errorStatusCodeRegex The regex that the error response status code must match to trigger retry <code>string</code> <code>&lt;nil&gt;</code> initWaitTime The initial retry delay <code>time.Duration</code> <code>250ms</code> maxWaitTime The maximum retry delay <code>time.Duration</code> <code>30s</code>"},{"location":"reference/config/#pluginstokensfftokensthrottle","title":"plugins.tokens[].fftokens.throttle","text":"Key Description Type Default Value burst The maximum number of requests that can be made in a short period of time before the throttling kicks in. <code>int</code> <code>&lt;nil&gt;</code> requestsPerSecond The average rate at which requests are allowed to pass through over time. <code>int</code> <code>&lt;nil&gt;</code>"},{"location":"reference/config/#pluginstokensfftokenstls","title":"plugins.tokens[].fftokens.tls","text":"Key Description Type Default Value ca The TLS certificate authority in PEM format (this option is ignored if caFile is also set) <code>string</code> <code>&lt;nil&gt;</code> caFile The path to the CA file for TLS on this API <code>string</code> <code>&lt;nil&gt;</code> cert The TLS certificate in PEM format (this option is ignored if certFile is also set) <code>string</code> <code>&lt;nil&gt;</code> certFile The path to the certificate file for TLS on this API <code>string</code> <code>&lt;nil&gt;</code> clientAuth Enables or disables client auth for TLS on this API <code>string</code> <code>&lt;nil&gt;</code> enabled Enables or disables TLS on this API <code>boolean</code> <code>false</code> insecureSkipHostVerify When to true in unit test development environments to disable TLS verification. Use with extreme caution <code>boolean</code> <code>&lt;nil&gt;</code> key The TLS certificate key in PEM format (this option is ignored if keyFile is also set) <code>string</code> <code>&lt;nil&gt;</code> keyFile The path to the private key file for TLS on this API <code>string</code> <code>&lt;nil&gt;</code> requiredDNAttributes A set of required subject DN attributes. Each entry is a regular expression, and the subject certificate must have a matching attribute of the specified type (CN, C, O, OU, ST, L, STREET, POSTALCODE, SERIALNUMBER are valid attributes) <code>map[string]string</code> <code>&lt;nil&gt;</code>"},{"location":"reference/config/#pluginstokensfftokensws","title":"plugins.tokens[].fftokens.ws","text":"Key Description Type Default Value connectionTimeout The amount of time to wait while establishing a connection (or auto-reconnection) <code>time.Duration</code> <code>45s</code> heartbeatInterval The amount of time to wait between heartbeat signals on the WebSocket connection <code>time.Duration</code> <code>30s</code> initialConnectAttempts The number of attempts FireFly will make to connect to the WebSocket when starting up, before failing <code>int</code> <code>5</code> path The WebSocket sever URL to which FireFly should connect WebSocket URL <code>string</code> <code>&lt;nil&gt;</code> readBufferSize The size in bytes of the read buffer for the WebSocket connection <code>BytesSize</code> <code>16Kb</code> url URL to use for WebSocket - overrides url one level up (in the HTTP config) <code>string</code> <code>&lt;nil&gt;</code> writeBufferSize The size in bytes of the write buffer for the WebSocket connection <code>BytesSize</code> <code>16Kb</code>"},{"location":"reference/config/#privatemessagingbatch","title":"privatemessaging.batch","text":"Key Description Type Default Value agentTimeout How long to keep around a batching agent for a sending identity before disposal <code>time.Duration</code> <code>2m</code> payloadLimit The maximum payload size of a private message Data Exchange payload <code>BytesSize</code> <code>800Kb</code> size The maximum number of messages in a batch for private messages <code>int</code> <code>200</code> timeout The timeout to wait for a batch to fill, before sending <code>time.Duration</code> <code>1s</code>"},{"location":"reference/config/#privatemessagingretry","title":"privatemessaging.retry","text":"Key Description Type Default Value factor The retry backoff factor <code>float32</code> <code>2</code> initDelay The initial retry delay <code>time.Duration</code> <code>100ms</code> maxDelay The maximum retry delay <code>time.Duration</code> <code>30s</code>"},{"location":"reference/config/#spi","title":"spi","text":"Key Description Type Default Value address The IP address on which the admin HTTP API should listen IP Address <code>string</code> <code>127.0.0.1</code> enabled Enables the admin HTTP API <code>boolean</code> <code>false</code> port The port on which the admin HTTP API should listen <code>int</code> <code>5001</code> publicURL The fully qualified public URL for the admin API. This is used for building URLs in HTTP responses and in OpenAPI Spec generation URL <code>string</code> <code>&lt;nil&gt;</code> readTimeout The maximum time to wait when reading from an HTTP connection <code>time.Duration</code> <code>15s</code> shutdownTimeout The maximum amount of time to wait for any open HTTP requests to finish before shutting down the HTTP server <code>time.Duration</code> <code>10s</code> writeTimeout The maximum time to wait when writing to an HTTP connection <code>time.Duration</code> <code>15s</code>"},{"location":"reference/config/#spiauth","title":"spi.auth","text":"Key Description Type Default Value type The auth plugin to use for server side authentication of requests <code>string</code> <code>&lt;nil&gt;</code>"},{"location":"reference/config/#spiauthbasic","title":"spi.auth.basic","text":"Key Description Type Default Value passwordfile The path to a .htpasswd file to use for authenticating requests. Passwords should be hashed with bcrypt. <code>string</code> <code>&lt;nil&gt;</code>"},{"location":"reference/config/#spitls","title":"spi.tls","text":"Key Description Type Default Value ca The TLS certificate authority in PEM format (this option is ignored if caFile is also set) <code>string</code> <code>&lt;nil&gt;</code> caFile The path to the CA file for TLS on this API <code>string</code> <code>&lt;nil&gt;</code> cert The TLS certificate in PEM format (this option is ignored if certFile is also set) <code>string</code> <code>&lt;nil&gt;</code> certFile The path to the certificate file for TLS on this API <code>string</code> <code>&lt;nil&gt;</code> clientAuth Enables or disables client auth for TLS on this API <code>string</code> <code>&lt;nil&gt;</code> enabled Enables or disables TLS on this API <code>boolean</code> <code>false</code> insecureSkipHostVerify When to true in unit test development environments to disable TLS verification. Use with extreme caution <code>boolean</code> <code>&lt;nil&gt;</code> key The TLS certificate key in PEM format (this option is ignored if keyFile is also set) <code>string</code> <code>&lt;nil&gt;</code> keyFile The path to the private key file for TLS on this API <code>string</code> <code>&lt;nil&gt;</code> requiredDNAttributes A set of required subject DN attributes. Each entry is a regular expression, and the subject certificate must have a matching attribute of the specified type (CN, C, O, OU, ST, L, STREET, POSTALCODE, SERIALNUMBER are valid attributes) <code>map[string]string</code> <code>&lt;nil&gt;</code>"},{"location":"reference/config/#spiws","title":"spi.ws","text":"Key Description Type Default Value blockedWarnInterval How often to log warnings in core, when an admin change event listener falls behind the stream they requested and misses events <code>time.Duration</code> <code>1m</code> eventQueueLength Server-side queue length for events waiting for delivery over an admin change event listener websocket <code>int</code> <code>250</code> readBufferSize The size in bytes of the read buffer for the WebSocket connection <code>BytesSize</code> <code>16Kb</code> writeBufferSize The size in bytes of the write buffer for the WebSocket connection <code>BytesSize</code> <code>16Kb</code>"},{"location":"reference/config/#subscription","title":"subscription","text":"Key Description Type Default Value max The maximum number of pre-defined subscriptions that can exist (note for high fan-out consider connecting a dedicated pub/sub broker to the dispatcher) <code>int</code> <code>500</code>"},{"location":"reference/config/#subscriptiondefaults","title":"subscription.defaults","text":"Key Description Type Default Value batchSize Default read ahead to enable for subscriptions that do not explicitly configure readahead <code>int</code> <code>50</code> batchTimeout Default batch timeout <code>int</code> <code>50ms</code>"},{"location":"reference/config/#subscriptionevents","title":"subscription.events","text":"Key Description Type Default Value maxScanLength The maximum number of events a search for historical events matching a subscription will index from the database <code>int</code> <code>1000</code>"},{"location":"reference/config/#subscriptionretry","title":"subscription.retry","text":"Key Description Type Default Value factor The retry backoff factor <code>float32</code> <code>2</code> initDelay The initial retry delay <code>time.Duration</code> <code>250ms</code> maxDelay The maximum retry delay <code>time.Duration</code> <code>30s</code>"},{"location":"reference/config/#transactionwriter","title":"transaction.writer","text":"Key Description Type Default Value batchMaxTransactions The maximum number of transaction inserts to include in a batch <code>int</code> <code>100</code> batchTimeout How long to wait for more transactions to arrive before flushing the batch <code>time.Duration</code> <code>10ms</code> count The number of message writer workers <code>int</code> <code>5</code>"},{"location":"reference/config/#ui","title":"ui","text":"Key Description Type Default Value enabled Enables the web user interface <code>boolean</code> <code>true</code> path The file system path which contains the static HTML, CSS, and JavaScript files for the user interface <code>string</code> <code>&lt;nil&gt;</code>"},{"location":"reference/events/","title":"Event Bus","text":""},{"location":"reference/events/#hyperledger-firefly-event-bus","title":"Hyperledger FireFly Event Bus","text":"<p>The FireFly event bus provides your application with a single stream of events from all of the back-end services that plug into FireFly.</p> <p>Applications subscribe to these events using developer friendly protocols like WebSockets, and Webhooks. Additional transports and messaging systems like NATS, Kafka, and JMS Servers can be connected through plugins.</p> <p>Each application creates one or more Subscriptions to identify itself. In this subscription the application can choose to receive all events that are emitted within a <code>namespace</code>, or can use server-side filtering to only receive a sub-set of events.</p> <p>The event bus reliably keeps track of which events have been delivered to which applications, via an <code>offset</code> into the main event stream that is updated each time an application acknowledges receipt of events over its subscription.</p>"},{"location":"reference/events/#event-driven-application-architecture","title":"Event-Driven Application Architecture","text":"<p>Decentralized applications are built around a source of truth that is shared between multiple parties. No one party can change the state unilaterally, as their changes need to be processed in order with the other changes in the system. Each party processes requests to change shared state in the same order, against a common set of rules for what is allowed at that exact point in the processing. As a result everybody deterministically ends up with the same state at the end of the processing.</p> <p>This requires an event-driven programming model.</p> <p>You will find an event-driven model at the core of every blockchain Smart Contract technology.</p> <p>This event-driven approach is unavoidable regardless of how much of your business data &amp; logic can be directly stored/processed on-chain, vs. off-chain.</p> <p>So Hyperledger FireFly aims to provide you with the tools to easily manage this model throughout your decentralized application stack.</p> <p></p> <p>Your back-end application should be structured for this event-driven paradigm, with an Event Handler constantly listening for events, applying a consistent State Machine to those events and applying the changes to your Application Database.</p> <p>FireFly comes with a built in event processor for Token transfers &amp; approvals, that implements this pattern to maintain balances, and transaction history in a rich query off-chain data cache.</p>"},{"location":"reference/events/#decentralized-event-processing","title":"Decentralized Event Processing","text":"<p>In a decentralized system, you need to consider that each organization runs its own applications, and has its own private database.</p> <p>At any given point in time different organizations will have slightly different views of what the most up to date information is - even for the blockchain state.</p> <p>As well as the agreed business logic, there will be private data and core system integration that are needed to process events as they happen. Some of this data might be received privately from other parties, over a secure communications channel (not the blockchain).</p> <p></p> <p>The system must be eventually consistent across all parties for any business data/decision that those parties need to agree on. This happens by all parties processing the same events in the same order, and by applying the same business logic (for the parts of the business logic that are agreed).</p> <p>This means that when processing an event, a participant must have access to enough historical data/state to reach the same conclusion as everyone else.</p> <p>Let's look at a couple of examples.</p>"},{"location":"reference/events/#example-1-a-fungible-token-balance-transfer","title":"Example 1: A fungible token balance transfer","text":"<p>You need to be able to verify the complete lineage of the tokens being spent, in order to know that they cannot be double spent anywhere in the network.</p> <p>This means the transaction must be backed by a blockchain verifiable by all participants on the network that could hold balances of that token.</p> <p>You might be able to use advanced cryptography (such as zero-knowledge proofs) to mask the participants in the trade, but the transaction themselves must be verifiable to everyone in a global sequence that prevents double spending.</p>"},{"location":"reference/events/#example-2-a-step-in-a-multi-party-business-process","title":"Example 2: A step in a multi-party business process","text":"<p>Here it is likely you want to restrict visibility of the data to just the parties directly involved in the business process.</p> <p>To come to a common agreement on outcome, the parties must know they are processing the same data in the same order. So at minimum a proof (a hash of the data) needs to \"pinned\" to a blockchain ledger visible to all participants involved in the process.</p> <p>You can then choose to put more processing on the blockchain, to enforce some critical rules in the business state machine that must be executed fairly to prevent one party from cheating the system. Such as that the highest bid is chosen in a competitive bidding process, or a minimum set of parties have voted agreement before a transaction is finalized.</p> <p>Other steps in the process might include human decision making, private data from the core systems of one member, or proprietary business logic that one member is not willing to share. These steps are \"non-deterministic\" - you cannot predict the outcome, nor be guaranteed to reproduce the same outcome with the same inputs in the future.</p> <p>The FireFly event bus is designed to make triggering these non-deterministic steps easy, while still allowing them to be part of the overall state machine of the business process. You need to take care that the system is designed so parties cannot 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.</p> <p>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\" while complex off-chain agreement happens.</p>"},{"location":"reference/events/#privacy-groups-and-late-join","title":"Privacy groups and late join","text":"<p>If a new participant needs to join into a business transaction that has already started, they must first \"catch up\" with the current state before they can play their part. In a real-world scenario they might not be allowed to see all the data that's visible to the other parties, so it is common to create a new stream of communications that includes all of the existing parties, plus the new party, to continue the process.</p> <p>If you use the same blockchain to back both groups, then you can safely order business process steps that involve different parties across these overlapping groups of participants.</p> <p>Using a single Ethereum permissioned side-chain for example.</p> <p>Alternatively, you can create dedicated distributed ledgers (DLTs) for communication between these groups of participants. This can allow more logic and data to go on-chain directly, although you still must consider the fact that this data is immutable and can never be deleted.</p> <p>Using Hyperledger Fabric channels for example.</p> <p>On top of either type of ledger, FireFly provides a private Group construct to facilitate secure off-chain data exchanges, and to efficiently pin these communications to the blockchain in batches.</p> <p>These private data exchanges can also be coordinated with most sophisticated on-chain transactions, such as token transfers.</p>"},{"location":"reference/events/#event-types","title":"Event Types","text":"<p>FireFly provides a number of different types of events to your application, designed to allow you to build your application state machine quickly and reliably.</p> <p>All events in FireFly share a common base structure, regardless of their type. They are then linked (via a <code>reference</code>) to an object that contains detailed information.</p> <p>The categories of event your application can receive are as follows:</p> <p>See the Core Resources/Event page for a full list of event types, and more details on the data you can expect for each type.</p>"},{"location":"reference/events/#blockchain-events","title":"Blockchain events","text":"<p>FireFly allows your application to subscribe to any event from a blockchain smart contract.</p> <p>In order for applications connected to the FireFly API to receive blockchain events from a smart contracts, a ContractListener fist must be created to instruct FireFly to listen to those events from the blockchain (via the blockchain plugin).</p> <p>Once you have configured the blockchain event listener, every event detected from the blockchain will result in a FireFly event delivered to your application of type <code>blockchain_event_received</code>.</p> <p>As of 1.3.1 a group of event filters can be established under a single topic when supported by the connector, which has benefits for ordering.  See Contract Listeners for more detail</p> <p>Check out the Custom Contracts Tutorial for a walk-through of how to set up listeners for the events from your smart contracts.</p> <p>FireFly automatically establishes listeners for some blockchain events:</p> <ul> <li> <p>Events from the FireFly <code>BatchPin</code> contract that is used to pin identities,   off-chain data broadcast and private messaging to the blockchain.</p> </li> <li> <p>Events from Token contracts, for which a Token Pool   has been configured. These events are detected indirectly via the token connector.</p> </li> </ul>"},{"location":"reference/events/#token-events","title":"Token events","text":"<p>FireFly provides a Wallet API, that is pluggable to multiple token implementations without needing to change your app.</p> <p>The pluggable API/Event interface allows all kinds of technical implementations of tokens to be fitted into a common framework.</p> <p>The following wallet operations are supported. These are universal to all token implementations - NFTs and fungible tokens alike:</p> <ul> <li>Mint</li> <li>Burn</li> <li>Transfer</li> <li>Approve</li> </ul> <p>FireFly processes, indexes and stores the events associated with these actions, for any Token Pool that has been configured on the FireFly node.</p> <p>See Token Transfer and Token Approval for more information on the individual operations.</p> <p>The token connector is responsible for mapping from the raw Blockchain Events, to the FireFly model for tokens. Reference token connector implementations are provided for common interface standards implemented by tokens - like ERC-20, ERC-721 and ERC-115.</p> <p>A particular token contract might have many additional features that are unique to that contract, particularly around governance. For these you would use the Smart Contract features of FireFly to interact with the blockchain API and Events directly.</p>"},{"location":"reference/events/#message-events-on-chain-off-chain-coordinated","title":"Message events: on-chain / off-chain coordinated","text":"<p>Event aggregation between data arriving off-chain, and the associated ordered proof/transaction events being confirmed on-chain, is a complex orchestration task.</p> <p>The universal order and additional transaction logic on-chain must be the source of truth for when and how an event is processed.</p> <p>However, that event cannot be processed until the off-chain private/broadcast data associated with that event is also available and verified against the on-chain hash of that additional data.</p> <p>They might arrive in any order, and no further events can be processed on that business transaction until the data is available.</p> <p>Multiple parties might be emitting events as part of the business transaction, and the outcome will only be assured to be the same by all parties if they process these events in the same order.</p> <p>Hyperledger FireFly handles this for you. Events related to a message are not emitted until both the on-chain and off-chain parts (including large binary attachments) are available+verified in your local FireFly node, and all previous messages on the same <code>topic</code> have been processed successfully by your application.</p> <p>Your application just needs to:</p> <ol> <li>Choose a suitable <code>topic</code> for your messages that determines the ordered stream    it is part of. Such as a business transaction identifier.</li> <li>Make sure the application does not acknowledge a message, until it has finished    processing it.</li> </ol> <p>See Message for more information</p>"},{"location":"reference/events/#transaction-submission-events","title":"Transaction submission events","text":"<p>These events are emitted each time a new transaction is initiated via the Firefly API.</p> <p>These events are only emitted on the local FireFly node that initiates an activity.</p> <p>For more information about FireFly Transactions, and how they relate to blockchain transactions, see Transaction.</p>"},{"location":"reference/firefly_interface_format/","title":"FireFly Interface Format","text":"<p>FireFly defines a common, blockchain agnostic way to describe smart contracts. This is referred to as a Contract Interface, and it is written in the FireFly Interface (FFI) format. It is a simple JSON document that has a name, a namespace, a version, a list of methods, and a list of events.</p>"},{"location":"reference/firefly_interface_format/#overview","title":"Overview","text":"<p>There are four required fields when broadcasting a contract interface in FireFly: a <code>name</code>, a <code>version</code>, a list of <code>methods</code>, and a list of <code>events</code>. A <code>namespace</code> field will also be filled in automatically based on the URL path parameter. Here is an example of the structure of the required fields:</p> <pre><code>{\n  \"name\": \"example\",\n  \"version\": \"v1.0.0\",\n  \"methods\": [],\n  \"events\": []\n}\n</code></pre> <p>NOTE: Contract interfaces are scoped to a namespace. Within a namespace each contract interface must have a unique name and version combination. The same name and version combination can exist in different namespaces simultaneously.</p>"},{"location":"reference/firefly_interface_format/#method","title":"Method","text":"<p>Let's look at a what goes inside the <code>methods</code> array now. It is also a JSON object that has a <code>name</code>, a list of <code>params</code> which are the arguments the function will take and a list of <code>returns</code> which are the return values of the function. It also has an optional <code>description</code> which can be helpful in OpenAPI Spec generation. Finally, it has an optional <code>details</code> object which wraps blockchain specific information about this method. This can be used by the blockchain plugin when invoking this function, and it is also used in documentation generation.</p> <pre><code>{\n  \"name\": \"add\",\n  \"description\": \"Add two numbers together\",\n  \"params\": [],\n  \"returns\": [],\n  \"details\": {}\n}\n</code></pre>"},{"location":"reference/firefly_interface_format/#event","title":"Event","text":"<p>What goes into the <code>events</code> array is very similar. It is also a JSON object that has a <code>name</code> and a list of <code>params</code>. The difference is that <code>events</code> don't have <code>returns</code>. Arguments that are passed to the event when it is emitted are in <code>params</code>. It also has an optional <code>description</code> which can be helpful in OpenAPI Spec generation. Finally, it has an optional <code>details</code> object which wraps blockchain specific information about this event. This can be used by the blockchain plugin when invoking this function, and it is also used in documentation generation.</p> <pre><code>{\n  \"name\": \"added\",\n  \"description\": \"An event that occurs when numbers have been added\",\n  \"params\": [],\n  \"details\": {}\n}\n</code></pre>"},{"location":"reference/firefly_interface_format/#param","title":"Param","text":"<p>Both <code>methods</code>, and <code>events</code> have lists of <code>params</code> or <code>returns</code>, and the type of JSON object that goes in each of these arrays is the same. It is simply a JSON object with a <code>name</code> and a <code>schema</code>. There is also an optional <code>details</code> field that is passed to the blockchain plugin for blockchain specific requirements.</p> <pre><code>{\n  \"name\": \"x\",\n  \"schema\": {\n    \"type\": \"integer\",\n    \"details\": {}\n  }\n}\n</code></pre>"},{"location":"reference/firefly_interface_format/#schema","title":"Schema","text":"<p>The param <code>schema</code> is an important field which tells FireFly the type information about this particular field. This is used in several different places, such as OpenAPI Spec generation, API request validation, and blockchain request preparation.</p> <p>The <code>schema</code> field accepts JSON Schema (version 2020-12) with several additional requirements:</p> <ul> <li>A <code>type</code> field is always mandatory</li> <li>The list of valid types is:</li> <li><code>boolean</code></li> <li><code>integer</code></li> <li><code>string</code></li> <li><code>object</code></li> <li><code>array</code></li> <li>Blockchain plugins can add their own specific requirements to this list of validation rules</li> </ul> <p>NOTE: Floats or decimals are not currently accepted because certain underlying blockchains (e.g. Ethereum) only allow integers</p> <p>The type field here is the JSON input type when making a request to FireFly to invoke or query a smart contract. This type can be different from the actual blockchain type, usually specified in the <code>details</code> field, if there is a compatible type mapping between the two.</p>"},{"location":"reference/firefly_interface_format/#schema-details","title":"Schema details","text":"<p> The details field is quite important in some cases. Because the <code>details</code> field is passed to the blockchain plugin, it is used to encapsulate blockchain specific type information about a particular field. Additionally, because each blockchain plugin can add rules to the list of schema requirements above, a blockchain plugin can enforce that certain fields are always present within the <code>details</code> field.</p> <p>For example, the Ethereum plugin always needs to know what Solidity type the field is. It also defines several optional fields. A full Ethereum details field may look like:</p> <pre><code>{\n  \"type\": \"uint256\",\n  \"internalType\": \"uint256\",\n  \"indexed\": false\n}\n</code></pre>"},{"location":"reference/firefly_interface_format/#automated-generation-of-firefly-interfaces","title":"Automated generation of FireFly Interfaces","text":"<p>A convenience endpoint exists on the API to facilitate converting from native blockchain interface formats such as an Ethereum ABI to the FireFly Interface format. For details, please see the API documentation for the contract interface generation endpoint.</p> <p>For an example of using this endpoint with a specific Ethereum contract, please see the Tutorial to Work with custom smart contracts.</p>"},{"location":"reference/firefly_interface_format/#full-example","title":"Full Example","text":"<p>Putting it all together, here is a full example of the FireFly Interface format with all the fields filled in:</p> <pre><code>{\n  \"namespace\": \"default\",\n  \"name\": \"SimpleStorage\",\n  \"description\": \"A simple smart contract that stores and retrieves an integer on-chain\",\n  \"version\": \"v1.0.0\",\n  \"methods\": [\n    {\n      \"name\": \"get\",\n      \"description\": \"Retrieve the value of the stored integer\",\n      \"params\": [],\n      \"returns\": [\n        {\n          \"name\": \"output\",\n          \"schema\": {\n            \"type\": \"integer\",\n            \"details\": {\n              \"type\": \"uint256\",\n              \"internalType\": \"uint256\"\n            }\n          }\n        }\n      ],\n      \"details\": {\n        \"stateMutability\": \"viewable\"\n      }\n    },\n    {\n      \"name\": \"set\",\n      \"description\": \"Set the stored value on-chain\",\n      \"params\": [\n        {\n          \"name\": \"newValue\",\n          \"schema\": {\n            \"type\": \"integer\",\n            \"details\": {\n              \"type\": \"uint256\",\n              \"internalType\": \"uint256\"\n            }\n          }\n        }\n      ],\n      \"returns\": [],\n      \"details\": {\n        \"stateMutability\": \"payable\"\n      }\n    }\n  ],\n  \"events\": [\n    {\n      \"name\": \"Changed\",\n      \"description\": \"An event that is fired when the stored integer value changes\",\n      \"params\": [\n        {\n          \"name\": \"from\",\n          \"schema\": {\n            \"type\": \"string\",\n            \"details\": {\n              \"type\": \"address\",\n              \"internalType\": \"address\",\n              \"indexed\": true\n            }\n          }\n        },\n        {\n          \"name\": \"value\",\n          \"schema\": {\n            \"type\": \"integer\",\n            \"details\": {\n              \"type\": \"uint256\",\n              \"internalType\": \"uint256\"\n            }\n          }\n        }\n      ],\n      \"details\": {}\n    }\n  ]\n}\n</code></pre>"},{"location":"reference/idempotency/","title":"Idempotency Keys","text":""},{"location":"reference/idempotency/#idempotency","title":"Idempotency","text":"<p>The transaction submission REST APIs of Hyperledger FireFly are idempotent.</p> <p>Idempotent APIs allow an application to safely submit a request multiple times, and for the transaction to only be accepted and executed once.</p> <p>This is the well accepted approach for REST APIs over HTTP/HTTPS to achieve resilience, as HTTP requests can fail in indeterminate ways. For example in a request or gateway timeout situation, the requester is unable to know whether the request will or will not eventually be processed.</p> <p>There are various types of FireFly transaction that can be submitted. These include direct submission of blockchain transactions to a smart contract, as well as more complex transactions including coordination of multiple operations across on-chain and off-chain connectors.</p> <p>In order for Hyperledger FireFly to deduplicate transactions, and make them idempotent, the application must supply an <code>idempotencyKey</code> on each API request.</p>"},{"location":"reference/idempotency/#firefly-idempotency-keys","title":"FireFly Idempotency Keys","text":"<p>The caller of the API specifies its own unique identifier (an arbitrary string up to 256 characters) that uniquely identifies the request, in the <code>idempotencyKey</code> field of the API.</p> <p>So if there is a network connectivity failure, or an abrupt termination of either runtime, the application can safely attempt to resubmit the REST API call and be returned a <code>409 Conflict</code> HTTP code.</p> <p>Examples of how an app might construct such an idempotencyKey include:</p> <ul> <li>Unique business identifiers from the request that comes into its API up-stream - passing idempotency along the chain</li> <li>A hash of the business unique data that relates to the request - maybe all the input data of a blockchain transaction for example, if that payload is guaranteed to be unique. <p>Be careful of cases where the business data might not be unique - like a transfer of 10 coins from A to B.</p> <p>Such a transfer could happen multiple times, and each would be a separate business transaction.</p> <p>Where as transfer with invoice number <code>abcd1234</code> of 10 coins from A to B would be assured to be unique.</p> </li> <li>A unique identifier of a business transaction generated within the application and stored in its database before submission <p>This moves the challenge up one layer into your application. How does that unique ID get generated? Is that itself idempotent?</p> </li> </ul>"},{"location":"reference/idempotency/#operation-idempotency","title":"Operation Idempotency","text":"<p>FireFly provides an idempotent interface downstream to connectors.</p> <p>Each operation within a FireFly transaction receives a unique ID within the overall transaction that is used as an idempotency key when invoking that connector.</p> <p>Well formed connectors honor this idempotency key internally, ensuring that the end-to-end transaction submission is idempotent.</p> <p>Key examples of such connectors are EVMConnect and others built on the Blockchain Connector Toolkit.</p> <p>When an operation is retried automatically, the same idempotency key is re-used to avoid resubmission.</p>"},{"location":"reference/idempotency/#short-term-retry","title":"Short term retry","text":"<p>The FireFly core uses standard HTTP request code to communicate with all connector APIs.</p> <p>This code include exponential backoff retry, that can be enabled with a simple boolean in the plugin of FireFly core. The minimum retry, maximum retry, and backoff factor can be tuned individually as well on each connector.</p> <p>See Configuration Reference for more information.</p>"},{"location":"reference/idempotency/#administrative-operation-retry","title":"Administrative operation retry","text":"<p>The <code>operations/{operationId}/retry</code> API can be called administratively to resubmit a transaction that has reached <code>Failed</code> status, or otherwise been determined by an operator/monitor to be unrecoverable within the connector.</p> <p>In this case, the previous operation is marked <code>Retried</code>, a new operation ID is allocated, and the operation is re-submitted to the connector with this new ID.</p>"},{"location":"reference/identities/","title":"Identities","text":""},{"location":"reference/identities/#overview","title":"Overview","text":"<p>Identities are a critical part of using FireFly in a multi-party system. Every party that joins a multi-party system must begin by claiming an on- and off-chain identity, which is described with a unique DID. Each type of identity is also associated with an on- or off-chain verifier, which can be used in some way to check the authorship of a piece of data. Together, these concepts form the backbone of the trust model for exchanging multi-party data.</p>"},{"location":"reference/identities/#types-of-identities","title":"Types of Identities","text":"<p>There are three types of identities:</p>"},{"location":"reference/identities/#org","title":"org","text":"<p>Organizations are the primary identity type in FireFly. They represent a logical on-chain signing identity, and the attached verifier is therefore a blockchain key (with the exact format depending on the blockchain being used). Every party in a multi-party system must claim a root organization identity as the first step to joining the network.</p> <p>The root organization <code>name</code> and <code>key</code> must be defined in the FireFly config (once for every multi-party system). It can be claimed with a POST to <code>/network/organizations/self</code>.</p> <p>Organizations may have child identities of any type.</p>"},{"location":"reference/identities/#node","title":"node","text":"<p>Nodes represent a logical off-chain identity - and specifically, they are tied to an instance of a data exchange connector. The format of the attached verifier depends on the data exchange plugin being used, but it will be mapped to some validation provided by that plugin (ie the name of an X.509 certificate or similar). Every party in a multi-party system must claim a node identity when joining the network, which must be a child of one of its organization identities (but it is possible for many nodes to share a parent organization).</p> <p>The node <code>name</code> must be defined in the FireFly config (once for every multi-party system). It can be claimed with a POST to <code>/network/nodes/self</code>.</p> <p>Nodes must be a child of an organization, and cannot have any child identities of their own.</p> <p>Note that \"nodes\" as an identity concept are distinct from FireFly supernodes, from underlying blockchain nodes, and from anywhere else the term \"node\" happens to be used.</p>"},{"location":"reference/identities/#custom","title":"custom","text":"<p>Custom identities are similar to organizations, but are provided for applications to define their own more granular notions of identity. They are associated with an on-chain verifier in the same way as organizations.</p> <p>They can only have child identities which are also of type \"custom\".</p>"},{"location":"reference/identities/#identity-claims","title":"Identity Claims","text":"<p>Before an identity can be used within a multi-party system, it must be claimed. The identity claim is a special type of broadcast message sent by FireFly to establish an identity uniquely among the parties in the multi-party system. As with other broadcasts, this entails an on-chain transaction which contains a public reference to an off-chain piece of data (such as an IPFS reference) describing the details of the identity claim.</p> <p>The claim data consists of information on the identity being claimed - such as the type, the DID, and the parent (if applicable). The DID must be unique and unclaimed. The verifier will be inferred from the message - for on-chain identities (org and custom), it is the blockchain key that was used to sign the on-chain portion of the message, while for off-chain identities (nodes), is is an identifier queried from data exchange.</p> <p>For on-chain identities with a parent, two messages are actually required - the claim message signed with the new identity's blockchain key, as well as a separate verification message signed with the parent identity's blockchain key. Both messages must be received before the identity is confirmed.</p>"},{"location":"reference/identities/#messaging","title":"Messaging","text":"<p>In the context of a multi-party system, FireFly provides capabilities for sending off-chain messages that are pinned to an on-chain proof. The sender of every message must therefore have an on-chain and off-chain identity. For private messages, every recipient must also have an on-chain and off-chain identity.</p>"},{"location":"reference/identities/#sender","title":"Sender","text":"<p>When sending a message, the on-chain identity of the sender is controlled by the <code>author</code> and <code>key</code> fields.</p> <ul> <li>If both are blank, the root organization is assumed.</li> <li>If <code>author</code> alone is specified, it should be the DID of an org or custom identity. The associated   verifier will be looked up to use as the <code>key</code>.</li> <li>If <code>key</code> alone is specified, it must match the registered blockchain verifier for an org or custom identity that was previously claimed.   A reverse lookup will be used to populate the DID for the <code>author</code>.</li> <li>If <code>author</code> and <code>key</code> are both specified, they will be used as-is (can be used to send private messages with an unregistered blockchain key).</li> </ul> <p>The resolved <code>key</code> will be used to sign the blockchain transaction, which establishes the sender's on-chain identity.</p> <p>The sender's off-chain identity is always controlled by the <code>node.name</code> from the config along with the data exchange plugin.</p>"},{"location":"reference/identities/#recipients","title":"Recipients","text":"<p>When specifying private message recipients, each one has an <code>identity</code> and a <code>node</code>.</p> <ul> <li>If <code>identity</code> alone is specified, it should be the DID of an org or custom identity. The first <code>node</code> owned by that identity or one of its   ancestors will be automatically selected.</li> <li>If both <code>identity</code> and <code>node</code> are specified, they will be used as-is. The <code>node</code> should be a child of the given <code>identity</code> or one of its   ancestors.</li> </ul> <p>The <code>node</code> in this case will control how the off-chain portion of the message is routed via data exchange.</p>"},{"location":"reference/identities/#verification","title":"Verification","text":"<p>When a message is received, FireFly verifies the following:</p> <ul> <li>The sender's <code>author</code> and <code>key</code> are specified in the message. The <code>author</code> must be a known org or custom identity. The <code>key</code> must match the   blockchain key that was used to sign the on-chain portion of the message. For broadcast messages, the <code>key</code> must match the registered   verifier for the <code>author</code>.</li> <li>For private messages, the sending <code>node</code> (as reported by data exchange) must be a known node identity which is a child of the message's   <code>author</code> identity or one of its ancestors. The combination of the <code>author</code> identity and the <code>node</code> must also be found in the message <code>group</code>.</li> </ul> <p>In addition, the data exchange plugin is responsible for verifying the sending and receiving identities for the off-chain data (such as validating the relevant certificates).</p>"},{"location":"reference/namespaces/","title":"Namespaces","text":""},{"location":"reference/namespaces/#introduction-to-namespaces","title":"Introduction to Namespaces","text":"<p>Namespaces are a construct for segregating data and operations within a FireFly supernode. Each namespace is an isolated environment within a FireFly runtime, that allows independent configuration of:</p> <ul> <li>Plugin and infrastructure components</li> <li>API security</li> <li>Identity broadcasting</li> <li>On-chain data indexing</li> <li>How datatypes, locations of on-chain contrats, etc. should be shared</li> </ul> <p>They can be thought of in two basic modes:</p>"},{"location":"reference/namespaces/#multi-party-namespaces","title":"Multi-party Namespaces","text":"<p>This namespace is shared with one or more other FireFly nodes. It requires three types of communication plugins - blockchain, data exchange, and shared storage. Organization and node identities must be claimed with an identity broadcast when joining the namespace, which establishes credentials for blockchain and off-chain communication. Shared objects can be defined in the namespace (such as datatypes and token pools), and details of them will be implicitly broadcast to other members.</p> <p>This type of namespace is used when multiple parties need to share on- and off-chain data and agree upon the ordering and authenticity of that data. For more information, see the multi-party system overview.</p>"},{"location":"reference/namespaces/#gateway-namespaces","title":"Gateway Namespaces","text":"<p>Nothing in this namespace will be shared automatically, and no assumptions are made about whether other parties connected through this namespace are also using Hyperledger FireFly. Plugins for data exchange and shared storage are not supported. If any identities or definitions are created in this namespace, they will be stored in the local database, but will not be shared implicitly outside the node.</p> <p>This type of namespace is mainly used when interacting directly with a blockchain, without assuming that the interaction needs to conform to FireFly's multi-party system model.</p>"},{"location":"reference/namespaces/#configuration","title":"Configuration","text":"<p>FireFly nodes can be configured with one or many namespaces of different modes. This means that a single FireFly node can be used to interact with multiple distinct blockchains, multiple distinct token economies, and multiple business networks.</p> <p>Below is an example plugin and namespace configuration containing both a multi-party and gateway namespace:</p> <pre><code>plugins:\n  database:\n  - name: database0\n    type: sqlite3\n    sqlite3:\n      migrations:\n        auto: true\n      url: /etc/firefly/db?_busy_timeout=5000\n  blockchain:\n  - name: blockchain0\n    type: ethereum\n    ethereum:\n      ethconnect:\n        url: http://ethconnect_0:8080\n        topic: \"0\"\n  - name: blockchain1\n    type: ethereum\n    ethereum:\n      ethconnect:\n        url: http://ethconnect_01:8080\n        topic: \"0\"\n  dataexchange:\n  - name: dataexchange0\n    type: ffdx\n    ffdx:\n      url: http://dataexchange_0:3000\n  sharedstorage:\n  - name: sharedstorage0\n    type: ipfs\n    ipfs:\n      api:\n        url: http://ipfs_0:5001\n      gateway:\n        url: http://ipfs_0:8080\n  tokens:\n  - name: erc20_erc721\n    broadcastName: erc20_erc721\n    type: fftokens\n    fftokens:\n      url: http://tokens_0_0:3000\nnamespaces:\n  default: alpha\n  predefined:\n  - name: alpha\n    description: Default predefined namespace\n    defaultKey: 0x123456\n    plugins: [database0, blockchain0, dataexchange0, sharedstorage0, erc20_erc721]\n    multiparty:\n      networkNamespace: alpha\n      enabled: true\n      org:\n        name: org0\n        description: org0\n        key: 0x123456\n      node:\n        name: node0\n        description: node0\n      contract:\n        - location:\n            address: 0x4ae50189462b0e5d52285f59929d037f790771a6\n          firstEvent: 0\n        - location:\n            address: 0x3c1bef20a7858f5c2f78bda60796758d7cafff27\n          firstEvent: 5000\n  - name: omega\n    defaultkey: 0x48a54f9964d7ceede2d6a8b451bf7ad300c7b09f\n    description: Gateway namespace\n    plugins: [database0, blockchain1, erc20_erc721]\n</code></pre> <p>The <code>namespaces.predefined</code> object contains the follow sub-keys:</p> <ul> <li><code>defaultKey</code> is a blockchain key used to sign transactions when none is specified (in multi-party mode,   defaults to the org key)</li> <li><code>plugins</code> is an array of plugin names to be activated for this namespace (defaults to   all available plugins if omitted)</li> <li><code>multiparty.networkNamespace</code> is the namespace name to be sent in plugin calls, if it differs from the   locally used name (useful for interacting with multiple shared namespaces of the same name -   defaults to the value of <code>name</code>)</li> <li><code>multiparty.enabled</code> controls if multi-party mode is enabled (defaults to true if an org key or   org name is defined on this namespace or in the deprecated <code>org</code> section at the root)</li> <li><code>multiparty.org</code> is the root org identity for this multi-party namespace (containing <code>name</code>,   <code>description</code>, and <code>key</code>)</li> <li><code>multiparty.node</code> is the local node identity for this multi-party namespace (containing <code>name</code> and   <code>description</code>)</li> <li><code>multiparty.contract</code> is an array of objects describing the location(s) of a FireFly multi-party   smart contract. Its children are blockchain-agnostic <code>location</code> and <code>firstEvent</code> fields, with formats   identical to the same fields on custom contract interfaces and contract listeners. The blockchain plugin   will interact with the first contract in the list until instructions are received to terminate it and   migrate to the next.</li> </ul>"},{"location":"reference/namespaces/#config-restrictions","title":"Config Restrictions","text":"<ul> <li><code>name</code> must be unique on this node</li> <li>for historical reasons, \"ff_system\" is a reserved string and cannot be used as a <code>name</code> or <code>multiparty.networkNamespace</code></li> <li>a <code>database</code> plugin is required for every namespace</li> <li>if <code>multiparty.enabled</code> is true, plugins must include one each of <code>blockchain</code>, <code>dataexchange</code>, and   <code>sharedstorage</code></li> <li>if <code>multiparty.enabled</code> is false, plugins must not include <code>dataexchange</code> or <code>sharedstorage</code></li> <li>at most one of each type of plugin is allowed per namespace, except for tokens (which   may have many per namespace)</li> </ul> <p>All namespaces must be called out in the FireFly config file in order to be valid. Namespaces found in the database but not represented in the config file will be ignored.</p>"},{"location":"reference/namespaces/#definitions","title":"Definitions","text":"<p>In FireFly, definitions are immutable payloads that are used to define identities, datatypes, smart contract interfaces, token pools, and other constructs. Each type of definition in FireFly has a schema that it must adhere to. Some definitions also have a name and a version which must be unique within a namespace. In a multiparty namespace, definitions are broadcasted to other organizations.</p>"},{"location":"reference/namespaces/#local-definitions","title":"Local Definitions","text":"<p>The following are all \"definition\" types in FireFly:</p> <ul> <li>datatype</li> <li>group</li> <li>token pool</li> <li>contract interface</li> <li>contract API</li> <li>organization (deprecated)</li> <li>node (deprecated)</li> <li>identity claim</li> <li>identity verification</li> <li>identity update</li> </ul> <p>For gateway namespaces, the APIs which create these definitions will become an immediate local database insert, instead of performing a broadcast. Additional caveats:</p> <ul> <li>identities in this mode will not undergo any claim/verification process,   but will be created and stored locally</li> <li>datatypes and groups will not be supported, as they are only useful in the context   of messaging (which is disabled in gateway namespaces)</li> </ul>"},{"location":"reference/tls/","title":"TLS","text":""},{"location":"reference/tls/#tls-overview","title":"TLS Overview","text":"<p>To enable TLS in Firefly, there is a configuration available to provide certificates and keys.</p> <p>The common configuration is as such:</p> <pre><code>tls:\n  enabled: true/false # Toggle on or off TLS\n  caFile: &lt;path to the CA file you want the client or server to trust&gt;\n  certFile: &lt;path to the cert file you want the client or server to use when performing authentication in mTLS&gt;\n  keyFile: &lt;path to the priavte key file you want the client or server to use when performing  authentication in mTLS&gt;\n  clientAuth: true/false # Only applicable to the server side, to toggle on or off client authentication\n  requiredDNAttributes: A set of required subject DN attributes. Each entry is a regular expression, and the subject certificate must have a matching attribute of the specified type (CN, C, O, OU, ST, L, STREET, POSTALCODE, SERIALNUMBER are valid attributes)\n</code></pre> <p>NOTE The CAs, certificates and keys have to be in PEM format.</p>"},{"location":"reference/tls/#configuring-tls-for-the-api-server","title":"Configuring TLS for the API server","text":"<p>Using the above configuration, we can place it under the <code>http</code> config and enable TLS or mTLS for any API call.</p> <p>See this config section for details</p>"},{"location":"reference/tls/#configuring-tls-for-the-webhooks","title":"Configuring TLS for the webhooks","text":"<p>Using the above configuration, we can place it under the <code>events.webhooks</code> config and enable TLS or mTLS for any webhook call.</p> <p>See this config section for details</p>"},{"location":"reference/tls/#configuring-clients-and-websockets","title":"Configuring clients and websockets","text":"<p>Firefly has a set of HTTP clients and websockets that communicate the external endpoints and services that could be secured using TLS. In order to configure these clients, we can use the same configuration as above in the respective places in the config which relate to those clients.</p> <p>For example, if you wish to configure the ethereum blockchain connector with TLS you would look at this config section</p> <p>For more clients, search in the configuration reference for a TLS section.</p>"},{"location":"reference/tls/#enhancing-validation-of-certificates","title":"Enhancing validation of certificates","text":"<p>In the case where we want to verify that a specific client certificate has certain attributes we can use the <code>requiredDNAtributes</code> configuration as described above. This will allow you by the means of a regex expresssion matching against well known distinguished names (DN). To learn more about a DNs look at this document</p>"},{"location":"reference/microservices/fftokens/","title":"fftokens","text":""},{"location":"reference/microservices/fftokens/#overview","title":"Overview","text":"<p>fftokens is a protocol that can be implemented by token connector runtimes in order to be usable by the fftokens plugin in FireFly.</p> <p>The connector runtime must expose an HTTP and websocket server, along with a minimum set of HTTP APIs and websocket events. Each connector will be strongly coupled to a specific ledger technology and token standard(s), but no assumptions are made in the fftokens spec about what these technologies must be, as long as they can satisfy the basic requirements laid out here.</p> <p>Note that this is an internal protocol in the FireFly ecosystem - application developers working against FireFly should never need to care about or directly interact with a token connector runtime. The audience for this document is only developers interested in creating new token connectors (or editing/forking existing ones).</p> <p>Two implementations of this specification have been created to date (both based on common Ethereum token standards) - firefly-tokens-erc1155 and firefly-tokens-erc20-erc721.</p>"},{"location":"reference/microservices/fftokens/#http-apis","title":"HTTP APIs","text":"<p>This is the minimum set of APIs that must be implemented by a conforming token connector. A connector may choose to expose other APIs for its own purposes. All requests and responses to the APIs below are encoded as JSON. The APIs are currently understood to live under a <code>/api/v1</code> prefix.</p>"},{"location":"reference/microservices/fftokens/#post-createpool","title":"<code>POST /createpool</code>","text":"<p>Create a new token pool. The exact meaning of this is flexible - it may mean invoking a contract or contract factory to actually define a new set of tokens via a blockchain transaction, or it may mean indexing a set of tokens that already exists (depending on the options a connector accepts in <code>config</code>).</p> <p>In a multiparty network, this operation will only be performed by one of the parties, and FireFly will broadcast the result to the others.</p> <p>FireFly will store a \"pending\" token pool after a successful creation, but will replace it with a \"confirmed\" token pool after a successful activation (see below).</p> <p>Request</p> <pre><code>{\n  \"type\": \"fungible\",\n  \"signer\": \"0x0Ef1D0Dd56a8FB1226C0EaC374000B81D6c8304A\",\n  \"namespace\": \"default\",\n  \"name\": \"FFCoin\",\n  \"symbol\": \"FFC\",\n  \"data\": \"pool-metadata\",\n  \"requestId\": \"1\",\n  \"config\": {}\n}\n</code></pre> Parameter Type Description type string enum The type of pool to create. Currently supported types are \"fungible\" and \"nonfungible\". It is recommended (but not required) that token connectors support both. Unrecognized/unsupported types should be rejected with HTTP 400. signer string The signing identity to be used for the blockchain transaction, in a format understood by this connector. namespace string The namespace of the token pool name string (OPTIONAL) If supported by this token contract, this is a requested name for the token pool. May be ignored at the connector's discretion. symbol string (OPTIONAL) If supported by this token contract, this is a requested symbol for the token pool. May be ignored at the connector's discretion. requestId string (OPTIONAL) A unique identifier for this request. Will be included in the \"receipt\" websocket event to match receipts to requests. data string (OPTIONAL) A data string that should be returned in the connector's response to this creation request. config object (OPTIONAL) An arbitrary JSON object where the connector may accept additional parameters if desired. Each connector may define its own valid options to influence how the token pool is created. <p>Response</p> <p>HTTP 200: pool creation was successful, and the pool details are returned in the response.</p> <p>See Response Types: Token Pool</p> <p>HTTP 202: request was accepted, but pool will be created asynchronously, with \"receipt\" and \"token-pool\" events sent later on the websocket.</p> <p>See Response Types: Async Request</p>"},{"location":"reference/microservices/fftokens/#post-activatepool","title":"<code>POST /activatepool</code>","text":"<p>Activate a token pool to begin receiving events. Generally this means the connector will create blockchain event listeners for transfer and approval events related to the set of tokens encompassed by this token pool.</p> <p>In a multiparty network, this step will be performed by every member after a successful token pool broadcast. It therefore also serves the purpose of validating the broadcast info - if the connector does not find a valid pool given the <code>poolLocator</code> and <code>config</code> information passed in to this call, the pool should not get confirmed.</p> <p>Request</p> <pre><code>{\n  \"namespace\": \"default\",\n  \"poolLocator\": \"id=F1\",\n  \"poolData\": \"extra-pool-info\",\n  \"config\": {}\n}\n</code></pre> Parameter Type Description namespace string The namespace of the token pool poolLocator string The locator of the pool, as supplied by the output of the pool creation. poolData string (OPTIONAL) A data string that should be permanently attached to this pool and returned in all events. config object (OPTIONAL) An arbitrary JSON object where the connector may accept additional parameters if desired. This should be the same <code>config</code> object that was passed when the pool was created. <p>Response</p> <p>HTTP 200: pool activation was successful, and the pool details are returned in the response.</p> <p>See Response Types: Token Pool</p> <p>HTTP 202: request was accepted, but pool will be activated asynchronously, with \"receipt\" and \"token-pool\" events sent later on the websocket.</p> <p>See Response Types: Async Request</p> <p>HTTP 204: activation was successful - no separate receipt will be delivered, but \"token-pool\" event will be sent later on the websocket.</p> <p>No body</p>"},{"location":"reference/microservices/fftokens/#post-deactivatepool","title":"<code>POST /deactivatepool</code>","text":"<p>Deactivate a token pool to stop receiving events and delete all blockchain listeners related to that pool.</p> <p>Request</p> <pre><code>{\n  \"namespace\": \"default\",\n  \"poolLocator\": \"id=F1\",\n  \"poolData\": \"extra-pool-info\",\n  \"config\": {}\n}\n</code></pre> Parameter Type Description namespace string The namespace of the token pool poolLocator string The locator of the pool, as supplied by the output of the pool creation. poolData string (OPTIONAL) The data string that was attached to this pool at activation. config object (OPTIONAL) An arbitrary JSON object where the connector may accept additional parameters if desired. <p>Response</p> <p>HTTP 204: deactivation was successful, and one or more listeners were deleted.</p> <p>No body</p> <p>HTTP 404: no blockchain listeners were found for the given pool information.</p> <p>No body</p>"},{"location":"reference/microservices/fftokens/#post-checkinterface","title":"<code>POST /checkinterface</code>","text":"<p>This is an optional (but recommended) API for token connectors. If implemented, support will be indicated by the presence of the <code>interfaceFormat</code> field in all Token Pool responses.</p> <p>In the case that a connector supports multiple variants of a given token standard (such as many different ways to structure \"mint\" or \"burn\" calls on an underlying smart contract), this API allows the connector to be provided with a full description of the interface methods in use for a given token pool, so the connector can determine which methods it knows how to invoke.</p> <p>Request</p> <pre><code>{\n  \"poolLocator\": \"id=F1\",\n  \"format\": \"abi\",\n  \"methods\": [\n    {\n      \"name\": \"burn\",\n      \"type\": \"function\",\n      \"inputs\": [\n        {\n          \"internalType\": \"uint256\",\n          \"name\": \"tokenId\",\n          \"type\": \"uint256\"\n        }\n      ],\n      \"outputs\": [],\n      \"stateMutability\": \"nonpayable\"\n    },\n    ...\n  ]\n}\n</code></pre> Parameter Type Description poolLocator string The locator of the pool, as supplied by the output of the pool creation. format string enum The format of the data in this payload. Should match the <code>interfaceFormat</code> as supplied by the output of the pool creation. methods object array A list of all the methods available on the interface underpinning this token pool, encoded in the format specified by <code>format</code>. <p>Response</p> <p>HTTP 200: interface was successfully parsed, and methods of interest are returned in the body.</p> <p>The response body includes a section for each type of token operation (burn/mint/transfer/approval), which specifies a subset of the input body useful to that operation. The caller (FireFly) can then store and provide the proper subset of the interface for every future token operation (via the <code>interface</code> parameter).</p> <pre><code>{\n  \"burn\": {\n    \"format\": \"abi\",\n    \"methods\": [\n      {\n        \"name\": \"burn\",\n        \"type\": \"function\",\n        \"inputs\": [\n          {\n            \"internalType\": \"uint256\",\n            \"name\": \"tokenId\",\n            \"type\": \"uint256\"\n          }\n        ],\n        \"outputs\": [],\n        \"stateMutability\": \"nonpayable\"\n      }\n    ]\n  },\n  \"mint\": { ... },\n  \"transfer\": { ... },\n  \"approval\": { ... }\n}\n</code></pre>"},{"location":"reference/microservices/fftokens/#post-mint","title":"<code>POST /mint</code>","text":"<p>Mint new tokens.</p> <p>Request</p> <pre><code>{\n  \"namespace\": \"default\",\n  \"poolLocator\": \"id=F1\",\n  \"signer\": \"0x0Ef1D0Dd56a8FB1226C0EaC374000B81D6c8304A\",\n  \"to\": \"0x0Ef1D0Dd56a8FB1226C0EaC374000B81D6c8304A\",\n  \"amount\": \"10\",\n  \"tokenIndex\": \"1\",\n  \"uri\": \"ipfs://000000\",\n  \"requestId\": \"1\",\n  \"data\": \"transfer-metadata\",\n  \"config\": {},\n  \"interface\": {}\n}\n</code></pre> Parameter Type Description namespace string The namespace of the token pool poolLocator string The locator of the pool, as supplied by the output of the pool creation. signer string The signing identity to be used for the blockchain transaction, in a format understood by this connector. to string The identity to receive the minted tokens, in a format understood by this connector. amount number string The amount of tokens to mint. tokenIndex string (OPTIONAL) For non-fungible tokens that require choosing an index at mint time, the index of the specific token to mint. uri string (OPTIONAL) For non-fungible tokens that support choosing a URI at mint time, the URI to be attached to the token. requestId string (OPTIONAL) A unique identifier for this request. Will be included in the \"receipt\" websocket event to match receipts to requests. data string (OPTIONAL) A data string that should be returned in the connector's response to this mint request. config object (OPTIONAL) An arbitrary JSON object where the connector may accept additional parameters if desired. Each connector may define its own valid options to influence how the mint is carried out. interface object (OPTIONAL) Details on interface methods that are useful to this operation, as negotiated previously by a <code>/checkinterface</code> call. <p>Response</p> <p>HTTP 202: request was accepted, but mint will occur asynchronously, with \"receipt\" and \"token-mint\" events sent later on the websocket.</p> <p>See Response Types: Async Request</p>"},{"location":"reference/microservices/fftokens/#post-burn","title":"<code>POST /burn</code>","text":"<p>Burn tokens.</p> <p>Request</p> <pre><code>{\n  \"namespace\": \"default\",\n  \"poolLocator\": \"id=F1\",\n  \"signer\": \"0x0Ef1D0Dd56a8FB1226C0EaC374000B81D6c8304A\",\n  \"from\": \"0x0Ef1D0Dd56a8FB1226C0EaC374000B81D6c8304A\",\n  \"amount\": \"10\",\n  \"tokenIndex\": \"1\",\n  \"requestId\": \"1\",\n  \"data\": \"transfer-metadata\",\n  \"config\": {},\n  \"interface\": {}\n}\n</code></pre> Parameter Type Description namespace string The namespace of the token pool poolLocator string The locator of the pool, as supplied by the output of the pool creation. signer string The signing identity to be used for the blockchain transaction, in a format understood by this connector. from string The identity that currently owns the tokens to be burned, in a format understood by this connector. amount number string The amount of tokens to burn. tokenIndex string (OPTIONAL) For non-fungible tokens, the index of the specific token to burn. requestId string (OPTIONAL) A unique identifier for this request. Will be included in the \"receipt\" websocket event to match receipts to requests. data string (OPTIONAL) A data string that should be returned in the connector's response to this burn request. config object (OPTIONAL) An arbitrary JSON object where the connector may accept additional parameters if desired. Each connector may define its own valid options to influence how the burn is carried out. interface object (OPTIONAL) Details on interface methods that are useful to this operation, as negotiated previously by a <code>/checkinterface</code> call. <p>Response</p> <p>HTTP 202: request was accepted, but burn will occur asynchronously, with \"receipt\" and \"token-burn\" events sent later on the websocket.</p> <p>See Response Types: Async Request</p>"},{"location":"reference/microservices/fftokens/#post-transfer","title":"<code>POST /transfer</code>","text":"<p>Transfer tokens from one address to another.</p> <p>Request</p> <pre><code>{\n  \"namespace\": \"default\",\n  \"poolLocator\": \"id=F1\",\n  \"signer\": \"0x0Ef1D0Dd56a8FB1226C0EaC374000B81D6c8304A\",\n  \"from\": \"0x0Ef1D0Dd56a8FB1226C0EaC374000B81D6c8304A\",\n  \"to\": \"0xb107ed9caa1323b7bc36e81995a4658ec2251951\",\n  \"amount\": \"1\",\n  \"tokenIndex\": \"1\",\n  \"requestId\": \"1\",\n  \"data\": \"transfer-metadata\",\n  \"config\": {},\n  \"interface\": {}\n}\n</code></pre> Parameter Type Description namespace string The namespace of the token pool poolLocator string The locator of the pool, as supplied by the output of the pool creation. signer string The signing identity to be used for the blockchain transaction, in a format understood by this connector. from string The identity to be used for the source of the transfer, in a format understood by this connector. to string The identity to be used for the destination of the transfer, in a format understood by this connector. amount number string The amount of tokens to transfer. tokenIndex string (OPTIONAL) For non-fungible tokens, the index of the specific token to transfer. requestId string (OPTIONAL) A unique identifier for this request. Will be included in the \"receipt\" websocket event to match receipts to requests. data string (OPTIONAL) A data string that should be returned in the connector's response to this transfer request. config object (OPTIONAL) An arbitrary JSON object where the connector may accept additional parameters if desired. Each connector may define its own valid options to influence how the transfer is carried out. interface object (OPTIONAL) Details on interface methods that are useful to this operation, as negotiated previously by a <code>/checkinterface</code> call. <p>Response</p> <p>HTTP 202: request was accepted, but transfer will occur asynchronously, with \"receipt\" and \"token-transfer\" events sent later on the websocket.</p> <p>See Response Types: Async Request</p>"},{"location":"reference/microservices/fftokens/#post-approval","title":"<code>POST /approval</code>","text":"<p>Approve another identity to manage tokens.</p> <p>Request</p> <pre><code>{\n  \"namespace\": \"default\",\n  \"poolLocator\": \"id=F1\",\n  \"signer\": \"0x0Ef1D0Dd56a8FB1226C0EaC374000B81D6c8304A\",\n  \"operator\": \"0xb107ed9caa1323b7bc36e81995a4658ec2251951\",\n  \"approved\": true,\n  \"requestId\": \"1\",\n  \"data\": \"approval-metadata\",\n  \"config\": {},\n  \"interface\": {}\n}\n</code></pre> Parameter Type Description namespace string The namespace of the token pool poolLocator string The locator of the pool, as supplied by the output of the pool creation. signer string The signing identity to be used for the blockchain transaction, in a format understood by this connector. operator string The identity to be approved (or unapproved) for managing the signer's tokens. approved boolean Whether to approve (the default) or unapprove. requestId string (OPTIONAL) A unique identifier for this request. Will be included in the \"receipt\" websocket event to match receipts to requests. data string (OPTIONAL) A data string that should be returned in the connector's response to this approval request. config object (OPTIONAL) An arbitrary JSON object where the connector may accept additional parameters if desired. Each connector may define its own valid options to influence how the approval is carried out. interface object (OPTIONAL) Details on interface methods that are useful to this operation, as negotiated previously by a <code>/checkinterface</code> call. <p>Response</p> <p>HTTP 202: request was accepted, but approval will occur asynchronously, with \"receipt\" and \"token-approval\" events sent later on the websocket.</p> <p>See Response Types: Async Request</p>"},{"location":"reference/microservices/fftokens/#websocket-commands","title":"Websocket Commands","text":"<p>In order to start listening for events on a certain namespace, the client needs to send the <code>start</code> command. Clients should send this command every time they connect, or after an automatic reconnect.</p> <pre><code>{\n  \"type\": \"start\",\n  \"namespace\": \"default\"\n}\n</code></pre>"},{"location":"reference/microservices/fftokens/#websocket-events","title":"Websocket Events","text":"<p>A connector should expose a websocket at <code>/api/ws</code>. All emitted websocket events are a JSON string of the form:</p> <pre><code>{\n  \"id\": \"event-id\",\n  \"event\": \"event-name\",\n  \"data\": {}\n}\n</code></pre> <p>The <code>event</code> name will match one of the names listed below, and the <code>data</code> payload will correspond to the linked response object.</p> <p>All events except the receipt event must be acknowledged by sending an ack of the form:</p> <pre><code>{\n  \"event\": \"ack\",\n  \"data\": {\n    \"id\": \"event-id\"\n  }\n}\n</code></pre> <p>Many messages may also be batched into a single websocket event of the form:</p> <pre><code>{\n  \"id\": \"event-id\",\n  \"event\": \"batch\",\n  \"data\": {\n    \"events\": [\n      {\n        \"event\": \"event-name\",\n        \"data\": {}\n      },\n      ...\n    ]\n  }\n}\n</code></pre> <p>Batched messages must be acked all at once using the ID of the batch.</p>"},{"location":"reference/microservices/fftokens/#receipt","title":"<code>receipt</code>","text":"<p>An asynchronous operation has completed.</p> <p>See Response Types: Receipt</p>"},{"location":"reference/microservices/fftokens/#token-pool","title":"<code>token-pool</code>","text":"<p>A new token pool has been created or activated.</p> <p>See Response Types: Token Pool</p>"},{"location":"reference/microservices/fftokens/#token-mint","title":"<code>token-mint</code>","text":"<p>Tokens have been minted.</p> <p>See Response Types: Token Transfer</p>"},{"location":"reference/microservices/fftokens/#token-burn","title":"<code>token-burn</code>","text":"<p>Tokens have been burned.</p> <p>See Response Types: Token Transfer</p>"},{"location":"reference/microservices/fftokens/#token-transfer","title":"<code>token-transfer</code>","text":"<p>Tokens have been transferred.</p> <p>See Response Types: Token Transfer</p>"},{"location":"reference/microservices/fftokens/#token-approval","title":"<code>token-approval</code>","text":"<p>Token approvals have changed.</p> <p>See Response Types: Token Approval</p>"},{"location":"reference/microservices/fftokens/#response-types","title":"Response Types","text":""},{"location":"reference/microservices/fftokens/#async-request","title":"Async Request","text":"<p>Many operations may happen asynchronously in the background, and will return only a request ID. This may be a request ID that was passed in, or if none was passed, will be randomly assigned. This ID can be used to correlate with a receipt event later received on the websocket.</p> <pre><code>{\n  \"id\": \"b84ab27d-0d50-42a6-9c26-2fda5eb901ba\"\n}\n</code></pre>"},{"location":"reference/microservices/fftokens/#receipt_1","title":"Receipt","text":"<pre><code>  \"headers\": {\n    \"type\": \"\",\n    \"requestId\": \"\"\n  }\n  \"transactionHash\": \"\",\n  \"errorMessage\": \"\"\n}\n</code></pre> Parameter Type Description headers.type string enum The type of this response. Should be \"TransactionSuccess\", \"TransactionUpdate\", or \"TransactionFailed\". headers.requestId string The ID of the request to which this receipt should correlate. transactionHash string The unique identifier for the blockchain transaction which generated this receipt. errorMessage string (OPTIONAL) If this is a failure, contains details on the reason for the failure."},{"location":"reference/microservices/fftokens/#token-pool_1","title":"Token Pool","text":"<pre><code>{\n  \"namespace\": \"default\",\n  \"type\": \"fungible\",\n  \"data\": \"pool-metadata\",\n  \"poolLocator\": \"id=F1\",\n  \"standard\": \"ERC20\",\n  \"interfaceFormat\": \"abi\",\n  \"symbol\": \"FFC\",\n  \"decimals\": 18,\n  \"info\": {},\n  \"signer\": \"0x0Ef1D0Dd56a8FB1226C0EaC374000B81D6c8304A\",\n  \"blockchain\": {}\n}\n</code></pre> Parameter Type Description namespace string The namespace of the token pool type string enum The type of pool that was created. data string A copy of the data that was passed in on the creation request. poolLocator string A string to identify this pool, generated by the connector. Must be unique for each pool created by this connector. Will be passed back on all operations within this pool, and may be packed with relevant data about the pool for later usage (such as the address and type of the pool). standard string (OPTIONAL) The name of a well-defined token standard to which this pool conforms. interfaceFormat string enum (OPTIONAL) If this connector supports the <code>/checkinterface</code> API, this is the interface format to be used for describing the interface underpinning this pool. Must be \"abi\" or \"ffi\". symbol string (OPTIONAL) The symbol for this token pool, if applicable. decimals number (OPTIONAL) The number of decimals used for balances in this token pool, if applicable. info object (OPTIONAL) Additional information about the pool. Each connector may define the format for this object. signer string (OPTIONAL) If this operation triggered a blockchain transaction, the signing identity used for the transaction. blockchain object (OPTIONAL) If this operation triggered a blockchain transaction, contains details on the blockchain event in FireFly's standard blockchain event format."},{"location":"reference/microservices/fftokens/#token-transfer_1","title":"Token Transfer","text":"<p>Note that mint and burn operations are just specialized versions of transfer. A mint will omit the \"from\" field, while a burn will omit the \"to\" field.</p> <pre><code>{\n  \"namespace\": \"default\",\n  \"id\": \"1\",\n  \"data\": \"transfer-metadata\",\n  \"poolLocator\": \"id=F1\",\n  \"poolData\": \"extra-pool-info\",\n  \"from\": \"0x0Ef1D0Dd56a8FB1226C0EaC374000B81D6c8304A\",\n  \"to\": \"0xb107ed9caa1323b7bc36e81995a4658ec2251951\",\n  \"amount\": \"1\",\n  \"tokenIndex\": \"1\",\n  \"uri\": \"ipfs://000000\",\n  \"signer\": \"0x0Ef1D0Dd56a8FB1226C0EaC374000B81D6c8304A\",\n  \"blockchain\": {}\n}\n</code></pre> Parameter Type Description namespace string The namespace of the token pool id string An identifier for this transfer. Must be unique for every transfer within this pool. data string A copy of the data that was passed in on the mint/burn/transfer request. May be omitted if the token contract does not support a method of attaching extra data (will result in reduced ability for FireFly to correlate the inputs and outputs of the transaction). poolLocator string The locator of the pool, as supplied by the output of the pool creation. poolData string The extra data associated with the pool at pool activation. from string The identity used for the source of the transfer. to string The identity used for the destination of the transfer. amount number string The amount of tokens transferred. tokenIndex string (OPTIONAL) For non-fungible tokens, the index of the specific token transferred. uri string (OPTIONAL) For non-fungible tokens, the URI attached to the token. signer string (OPTIONAL) If this operation triggered a blockchain transaction, the signing identity used for the transaction. blockchain object (OPTIONAL) If this operation triggered a blockchain transaction, contains details on the blockchain event in FireFly's standard blockchain event format."},{"location":"reference/microservices/fftokens/#token-approval_1","title":"Token Approval","text":"<pre><code>{\n  \"namespace\": \"default\",\n  \"id\": \"1\",\n  \"data\": \"transfer-metadata\",\n  \"poolLocator\": \"id=F1\",\n  \"poolData\": \"extra-pool-info\",\n  \"operator\": \"0xb107ed9caa1323b7bc36e81995a4658ec2251951\",\n  \"approved\": true,\n  \"subject\": \"0x0Ef1D0Dd56a8FB1226C0EaC374000B81D6c8304A:0xb107ed9caa1323b7bc36e81995a4658ec2251951\",\n  \"info\": {},\n  \"signer\": \"0x0Ef1D0Dd56a8FB1226C0EaC374000B81D6c8304A\",\n  \"blockchain\": {}\n}\n</code></pre> Parameter Type Description namespace string The namespace of the token pool id string An identifier for this approval. Must be unique for every approval within this pool. data string A copy of the data that was passed in on the approval request. May be omitted if the token contract does not support a method of attaching extra data (will result in reduced ability for FireFly to correlate the inputs and outputs of the transaction). poolLocator string The locator of the pool, as supplied by the output of the pool creation. poolData string The extra data associated with the pool at pool activation. operator string The identity that was approved (or unapproved) for managing tokens. approved boolean Whether this was an approval or unapproval. subject string A string identifying the scope of the approval, generated by the connector. Approvals with the same subject are understood replace one another, so that a previously-recorded approval becomes inactive. This string may be a combination of the identities involved, the token index, etc. info object (OPTIONAL) Additional information about the approval. Each connector may define the format for this object. signer string (OPTIONAL) If this operation triggered a blockchain transaction, the signing identity used for the transaction. blockchain object (OPTIONAL) If this operation triggered a blockchain transaction, contains details on the blockchain event in FireFly's standard blockchain event format."},{"location":"reference/types/batch/","title":"Batch","text":"<p>A batch bundles a number of off-chain messages, with associated data, into a single payload for broadcast or private transfer.</p> <p>This allows the transfer of many messages (hundreds) to be backed by a single blockchain transaction. Thus making very efficient use of the blockchain.</p> <p>The same benefit also applies to the off-chain transport mechanism.</p> <p>Shared storage operations benefit from the same optimization. In IPFS for example chunks are 256Kb in size, so there is a great throughput benefit in packaging many small messages into a single large payload.</p> <p>For a data exchange transport, there is often cryptography and transport overhead for each individual transport level send between participants. This is particularly true if using a data exchange transport with end-to-end payload encryption, using public/private key cryptography for the envelope.</p>"},{"location":"reference/types/batch/#example","title":"Example","text":"<pre><code>{\n    \"id\": \"894bc0ea-0c2e-4ca4-bbca-b4c39a816bbb\",\n    \"type\": \"private\",\n    \"namespace\": \"ns1\",\n    \"node\": \"5802ab80-fa71-4f52-9189-fb534de93756\",\n    \"group\": \"cd1fedb69fb83ad5c0c62f2f5d0b04c59d2e41740916e6815a8e063b337bd32e\",\n    \"created\": \"2022-05-16T01:23:16Z\",\n    \"author\": \"did:firefly:org/example\",\n    \"key\": \"0x0a989907dcd17272257f3ebcf72f4351df65a846\",\n    \"hash\": \"78d6861f860c8724468c9254b99dc09e7d9fd2d43f26f7bd40ecc9ee47be384d\",\n    \"payload\": {\n        \"tx\": {\n            \"type\": \"private\",\n            \"id\": \"04930d84-0227-4044-9d6d-82c2952a0108\"\n        },\n        \"messages\": [],\n        \"data\": []\n    }\n}\n</code></pre>"},{"location":"reference/types/batch/#field-descriptions","title":"Field Descriptions","text":"Field Name Description Type <code>id</code> The UUID of the batch <code>UUID</code> <code>type</code> The type of the batch <code>FFEnum</code>:<code>\"broadcast\"</code><code>\"private\"</code> <code>namespace</code> The namespace of the batch <code>string</code> <code>node</code> The UUID of the node that generated the batch <code>UUID</code> <code>group</code> The privacy group the batch is sent to, for private batches <code>Bytes32</code> <code>created</code> The time the batch was sealed <code>FFTime</code> <code>author</code> The DID of identity of the submitter <code>string</code> <code>key</code> The on-chain signing key used to sign the transaction <code>string</code> <code>hash</code> The hash of the manifest of the batch <code>Bytes32</code> <code>payload</code> Batch.payload <code>BatchPayload</code>"},{"location":"reference/types/batch/#batchpayload","title":"BatchPayload","text":"Field Name Description Type <code>tx</code> BatchPayload.tx <code>TransactionRef</code> <code>messages</code> BatchPayload.messages <code>Message[]</code> <code>data</code> BatchPayload.data <code>Data[]</code>"},{"location":"reference/types/batch/#transactionref","title":"TransactionRef","text":"Field Name Description Type <code>type</code> The type of the FireFly transaction <code>FFEnum</code>: <code>id</code> The UUID of the FireFly transaction <code>UUID</code>"},{"location":"reference/types/blockchainevent/","title":"BlockchainEvent","text":"<p>Blockchain Events are detected by the blockchain plugin:</p> <ol> <li>When a ContractListener has been    configured against any custom smart contract through the FireFly API</li> <li>Indirectly via a Token Connector, which understands the correct events    to listen to for a Token Pool configured against a    standard such as ERC-20/ERC-721/ERC-1155</li> <li>Automatically by FireFly core, for the BatchPin contract that can    be used for high throughput batched pinning of off-chain data transfers    to the blockchain (complementary to using your own smart contracts).</li> </ol>"},{"location":"reference/types/blockchainevent/#protocol-id","title":"Protocol ID","text":"<p>Each Blockchain Event (once final) exists in an absolute location somewhere in the transaction history of the blockchain. A particular slot, in a particular block.</p> <p>How to describe that position contains blockchain specifics - depending on how a particular blockchain represents transactions, blocks and events (or \"logs\").</p> <p>So FireFly is flexible with a string <code>protocolId</code> in the core object to represent this location, and then there is a convention that is adopted by the blockchain plugins to try and create some consistency.</p> <p>An example <code>protocolId</code> string is: <code>000000000041/000020/000003</code></p> <ul> <li><code>000000000041</code> - this is the block number</li> <li><code>000020</code> - this is the transaction index within that block</li> <li><code>000003</code> - this is the event (/log) index within that block</li> </ul> <p>The string is alphanumerically sortable as a plain string;</p> <p>Sufficient zero padding is included at each layer to support future expansion without creating a string that would no longer sort correctly.</p>"},{"location":"reference/types/blockchainevent/#example","title":"Example","text":"<pre><code>{\n    \"id\": \"e9bc4735-a332-4071-9975-b1066e51ab8b\",\n    \"source\": \"ethereum\",\n    \"namespace\": \"ns1\",\n    \"name\": \"MyEvent\",\n    \"listener\": \"c29b4595-03c2-411a-89e3-8b7f27ef17bb\",\n    \"protocolId\": \"000000000048/000000/000000\",\n    \"output\": {\n        \"addr1\": \"0x55860105d6a675dbe6e4d83f67b834377ba677ad\",\n        \"value2\": \"42\"\n    },\n    \"info\": {\n        \"address\": \"0x57A9bE18CCB50D06B7567012AaF6031D669BBcAA\",\n        \"blockHash\": \"0xae7382ef2573553f517913b927d8b9691ada8d617266b8b16f74bb37aa78cae8\",\n        \"blockNumber\": \"48\",\n        \"logIndex\": \"0\",\n        \"signature\": \"Changed(address,uint256)\",\n        \"subId\": \"sb-e4d5efcd-2eba-4ed1-43e8-24831353fffc\",\n        \"timestamp\": \"1653048837\",\n        \"transactionHash\": \"0x34b0327567fefed09ac7b4429549bc609302b08a9cbd8f019a078ec44447593d\",\n        \"transactionIndex\": \"0x0\"\n    },\n    \"timestamp\": \"2022-05-16T01:23:15Z\",\n    \"tx\": {\n        \"blockchainId\": \"0x34b0327567fefed09ac7b4429549bc609302b08a9cbd8f019a078ec44447593d\"\n    }\n}\n</code></pre>"},{"location":"reference/types/blockchainevent/#field-descriptions","title":"Field Descriptions","text":"Field Name Description Type <code>id</code> The UUID assigned to the event by FireFly <code>UUID</code> <code>source</code> The blockchain plugin or token service that detected the event <code>string</code> <code>namespace</code> The namespace of the listener that detected this blockchain event <code>string</code> <code>name</code> The name of the event in the blockchain smart contract <code>string</code> <code>listener</code> The UUID of the listener that detected this event, or nil for built-in events in the system namespace <code>UUID</code> <code>protocolId</code> An alphanumerically sortable string that represents this event uniquely on the blockchain (convention for plugins is zero-padded values BLOCKNUMBER/TXN_INDEX/EVENT_INDEX) <code>string</code> <code>output</code> The data output by the event, parsed to JSON according to the interface of the smart contract <code>JSONObject</code> <code>info</code> Detailed blockchain specific information about the event, as generated by the blockchain connector <code>JSONObject</code> <code>timestamp</code> The time allocated to this event by the blockchain. This is the block timestamp for most blockchain connectors <code>FFTime</code> <code>tx</code> If this blockchain event is coorelated to FireFly transaction such as a FireFly submitted token transfer, this field is set to the UUID of the FireFly transaction <code>BlockchainTransactionRef</code>"},{"location":"reference/types/blockchainevent/#blockchaintransactionref","title":"BlockchainTransactionRef","text":"Field Name Description Type <code>type</code> The type of the FireFly transaction <code>FFEnum</code>: <code>id</code> The UUID of the FireFly transaction <code>UUID</code> <code>blockchainId</code> The blockchain transaction ID, in the format specific to the blockchain involved in the transaction. Not all FireFly transactions include a blockchain <code>string</code>"},{"location":"reference/types/contractapi/","title":"ContractAPI","text":"<p>Contract APIs provide generated REST APIs for on-chain smart contracts.</p> <p>API endpoints are generated to invoke or perform query operations against each of the functions/methods implemented by the smart contract.</p> <p>API endpoints are also provided to add listeners to the events of that smart contract.</p> <p>Note that once you have established listeners for your blockchain events into FireFly, you need to also subscribe in your application to receive the FireFly events (of type <code>blockchain_event_received</code>) that are emitted for each detected blockchain event.</p> <p>For more information see the Events reference section.</p>"},{"location":"reference/types/contractapi/#url","title":"URL","text":"<p>The base path for your Contract API is:</p> <ul> <li><code>/api/v1/namespaces/{ns}/apis/{apiName}</code></li> </ul> <p>For the default namespace, this can be shortened to:</p> <ul> <li><code>/api/v1/apis/{apiName}</code></li> </ul>"},{"location":"reference/types/contractapi/#firefly-interface-ffi-and-on-chain-location","title":"FireFly Interface (FFI) and On-chain Location","text":"<p>Contract APIs are registered against:</p> <ol> <li> <p>A FireFly Interface (FFI) definition, which defines in a blockchain agnostic    format the list of functions/events supported by the smart contract. Also    detailed type information about the inputs/outputs to those functions/events.</p> </li> <li> <p>An optional <code>location</code> configured on the Contract API describes where the    instance of the smart contract the API should interact with exists in the blockchain layer.    For example the <code>address</code> of the Smart Contract for an Ethereum based blockchain,    or the <code>name</code> and <code>channel</code> for a Hyperledger Fabric based blockchain.</p> </li> </ol> <p>If the <code>location</code> is not specified on creation of the Contract API, then it must be specified on each API call made to the Contract API endpoints.</p>"},{"location":"reference/types/contractapi/#openapi-v3-swagger-definitions","title":"OpenAPI V3 / Swagger Definitions","text":"<p>Each Contract API comes with an OpenAPI V3 / Swagger generated definition, which can be downloaded from:</p> <ul> <li><code>/api/v1/namespaces/{namespaces}/apis/{apiName}/api/swagger.json</code></li> </ul>"},{"location":"reference/types/contractapi/#swagger-ui","title":"Swagger UI","text":"<p>A browser / exerciser UI for your API is also available on:</p> <ul> <li><code>/api/v1/namespaces/{namespaces}/apis/{apiName}/api</code></li> </ul>"},{"location":"reference/types/contractapi/#example","title":"Example","text":"<pre><code>{\n    \"id\": \"0f12317b-85a0-4a77-a722-857ea2b0a5fa\",\n    \"namespace\": \"ns1\",\n    \"interface\": {\n        \"id\": \"c35d3449-4f24-4676-8e64-91c9e46f06c4\"\n    },\n    \"location\": {\n        \"address\": \"0x95a6c4895c7806499ba35f75069198f45e88fc69\"\n    },\n    \"name\": \"my_contract_api\",\n    \"message\": \"b09d9f77-7b16-4760-a8d7-0e3c319b2a16\",\n    \"urls\": {\n        \"api\": \"http://127.0.0.1:5000/api/v1/namespaces/default/apis/my_contract_api\",\n        \"openapi\": \"http://127.0.0.1:5000/api/v1/namespaces/default/apis/my_contract_api/api/swagger.json\",\n        \"ui\": \"http://127.0.0.1:5000/api/v1/namespaces/default/apis/my_contract_api/api\"\n    },\n    \"published\": false\n}\n</code></pre>"},{"location":"reference/types/contractapi/#field-descriptions","title":"Field Descriptions","text":"Field Name Description Type <code>id</code> The UUID of the contract API <code>UUID</code> <code>namespace</code> The namespace of the contract API <code>string</code> <code>interface</code> Reference to the FireFly Interface definition associated with the contract API <code>FFIReference</code> <code>location</code> If this API is tied to an individual instance of a smart contract, this field can include a blockchain specific contract identifier. For example an Ethereum contract address, or a Fabric chaincode name and channel <code>JSONAny</code> <code>name</code> The name that is used in the URL to access the API <code>string</code> <code>networkName</code> The published name of the API within the multiparty network <code>string</code> <code>message</code> The UUID of the broadcast message that was used to publish this API to the network <code>UUID</code> <code>urls</code> The URLs to use to access the API <code>ContractURLs</code> <code>published</code> Indicates if the API is published to other members of the multiparty network <code>bool</code>"},{"location":"reference/types/contractapi/#ffireference","title":"FFIReference","text":"Field Name Description Type <code>id</code> The UUID of the FireFly interface <code>UUID</code> <code>name</code> The name of the FireFly interface <code>string</code> <code>version</code> The version of the FireFly interface <code>string</code>"},{"location":"reference/types/contractapi/#contracturls","title":"ContractURLs","text":"Field Name Description Type <code>api</code> The URL to use to invoke the API <code>string</code> <code>openapi</code> The URL to download the OpenAPI v3 (Swagger) description for the API generated in JSON or YAML format <code>string</code> <code>ui</code> The URL to use in a web browser to access the SwaggerUI explorer/exerciser for the API <code>string</code>"},{"location":"reference/types/contractlistener/","title":"ContractListener","text":"<p>A contract listener configures FireFly to stream events from the blockchain, from a specific location on the blockchain, according to a given definition of the interface for that event.</p> <p>Check out the Custom Contracts Tutorial for a walk-through of how to set up listeners for the events from your smart contracts.</p> <p>See below for a deep dive into the format of contract listeners and important concepts to understand when managing them.</p>"},{"location":"reference/types/contractlistener/#event-filters","title":"Event filters","text":""},{"location":"reference/types/contractlistener/#multiple-filters","title":"Multiple filters","text":"<p>From v1.3.1 onwards, a contract listener can be created with multiple filters under a single topic, when supported by the connector. Each filter contains:</p> <ul> <li>a reference to a specific blockchain event to listen for</li> <li>(optional) a specific location/address to listen from</li> <li>a connector-specific signature (generated from the event and the location)</li> </ul> <p>In addition to this list of multiple filters, the listener specifies a single <code>topic</code> to identify the stream of events.</p> <p>Creating a single listener that listens for multiple events will allow for the easiest management of listeners, and for strong ordering of the events that they process.</p>"},{"location":"reference/types/contractlistener/#single-filter","title":"Single filter","text":"<p>Before v1.3.1, each contract listener would only support listening to one specific event from a contract interface. Each listener would be comprised of:</p> <ul> <li>a reference to a specific blockchain event to listen for</li> <li>(optional) a specific location/address to listen from</li> <li>a connector-specific signature (generated from the event), which allows you to easily identify and search for the contact listener for an event</li> <li>a <code>topic</code> which determines the ordered stream that these events are part of</li> </ul> <p>For backwards compatibility, this format is still supported by the API.</p>"},{"location":"reference/types/contractlistener/#signature-strings","title":"Signature strings","text":""},{"location":"reference/types/contractlistener/#string-format","title":"String format","text":"<p>Each filter is identified by a generated <code>signature</code> that matches a single event, and each contract listener is identified by a <code>signature</code> computed from its filters.</p> <p>Ethereum provides a string standard for event signatures, of the form <code>EventName(uint256,bytes)</code>. Prior to v1.3.1, the signature of each Ethereum contract listener would exactly follow this Ethereum format.</p> <p>As of v1.3.1, Ethereum signature strings have been changed, because this format does not fully describe the event - particularly because each top-level parameter can in the ABI definition be marked as <code>indexed</code>. For example, while the following two Solidity events have the same signature, they are serialized differently due to the different placement of <code>indexed</code> parameters, and thus a listener must define both individually to be able to process them:</p> <ul> <li>ERC-20 <code>Transfer</code></li> </ul> <pre><code>event Transfer(address indexed _from, address indexed _to, uint256 _value)\n</code></pre> <ul> <li>ERC-721 <code>Transfer</code></li> </ul> <pre><code>event Transfer(address indexed _from, address indexed _to, uint256 indexed _tokenId);\n</code></pre> <p>The two above are now expressed in the following manner by the Ethereum blockchain connector:</p> <pre><code>Transfer(address,address,uint256) [i=0,1]\nTransfer(address,address,uint256) [i=0,1,2]\n</code></pre> <p>The <code>[i=]</code> listing at the end of the signature indicates the position of all parameters that are marked as <code>indexed</code>.</p> <p>Building on the blockchain-specific signature format for each event, FireFly will then compute the final signature for each filter and each contract listener as follows:</p> <ul> <li>Each filter signature is a combination of the location and the specific connector event signature, such as <code>0xa5ea5d0a6b2eaf194716f0cc73981939dca26da1:Changed(address,uint256) [i=0]</code></li> <li>Each contract listener signature is a concatenation of all the filter signatures, separated by <code>;</code></li> </ul>"},{"location":"reference/types/contractlistener/#duplicate-filters","title":"Duplicate filters","text":"<p>FireFly restricts the creation of a contract listener containing duplicate filters.</p> <p>This includes the special case where one filter is a superset of another filter, due to a wildcard location.</p> <p>For example, if two filters are listening to the same event, but one has specified a location and the other hasn't, then the latter will be a superset, and already be listening to all the events matching the first filter. Creation of duplicate or superset filters within a single listener will be blocked.</p>"},{"location":"reference/types/contractlistener/#duplicate-listeners","title":"Duplicate listeners","text":"<p>As noted above, each listener has a generated signature. This signature - containing all the locations and event signatures combined with the listener topic - will guarantee uniqueness of the contract listener. If you tried to create the same listener again, you would receive HTTP 409. This combination can allow a developer to assert that their listener exists, without the risk of creating duplicates.</p> <p>Note: Prior to v1.3.1, FireFly would detect duplicates simply by requiring a unique combination of signature + topic + location for each listener. The updated behavior for the listener signature is intended to preserve similar functionality, even when dealing with listeners that contain many event filters.</p>"},{"location":"reference/types/contractlistener/#backwards-compatibility","title":"Backwards compatibility","text":"<p>As noted throughout this document, the behavior of listeners is changed in v1.3.1. However, the following behaviors are retained for backwards-compatibility, to ensure that code written prior to v1.3.1 should continue to function.</p> <ul> <li>The response from all query APIs of <code>listeners</code> will continue to populate top-level <code>event</code> and <code>location</code> fields</li> <li>The first entry from the <code>filters</code> array is duplicated to these fields</li> <li>On input to create a new <code>listener</code>, the <code>event</code> and <code>location</code> fields are still supported</li> <li>They function identically to supplying a <code>filters</code> array with a single entry</li> <li>The <code>signature</code> field is preserved at the listener level</li> <li>The format has been changed as described above</li> </ul>"},{"location":"reference/types/contractlistener/#input-formats","title":"Input formats","text":"<p>The two input formats supported when creating a contract listener are shown below.</p> <p>Muliple Filters</p> <pre><code>{\n  \"filters\": [\n    {\n      \"interface\": {\n        \"id\": \"8bdd27a5-67c1-4960-8d1e-7aa31b9084d3\"\n      },\n      \"location\": {\n        \"address\": \"0xa5ea5d0a6b2eaf194716f0cc73981939dca26da1\"\n      },\n      \"eventPath\": \"Changed\"\n    },\n    {\n      \"interface\": {\n        \"id\": \"8bdd27a5-67c1-4960-8d1e-7aa31b9084d3\"\n      },\n      \"location\": {\n        \"address\": \"0xa4ea5d0b6b2eaf194716f0cc73981939dca27da1\"\n      },\n      \"eventPath\": \"AnotherEvent\"\n    }\n  ],\n  \"options\": {\n    \"firstEvent\": \"newest\"\n  },\n  \"topic\": \"simple-storage\"\n}\n</code></pre> <p>One filter (old format)</p> <pre><code>{\n  \"interface\": {\n    \"id\": \"8bdd27a5-67c1-4960-8d1e-7aa31b9084d3\"\n  },\n  \"location\": {\n    \"address\": \"0xa5ea5d0a6b2eaf194716f0cc73981939dca26da1\"\n  },\n  \"eventPath\": \"Changed\",\n  \"options\": {\n    \"firstEvent\": \"newest\"\n  },\n  \"topic\": \"simple-storage\"\n}\n</code></pre>"},{"location":"reference/types/contractlistener/#example","title":"Example","text":"<pre><code>{\n    \"id\": \"d61980a9-748c-4c72-baf5-8b485b514d59\",\n    \"interface\": {\n        \"id\": \"ff1da3c1-f9e7-40c2-8d93-abb8855e8a1d\"\n    },\n    \"namespace\": \"ns1\",\n    \"name\": \"contract1_events\",\n    \"backendId\": \"sb-dd8795fc-a004-4554-669d-c0cf1ee2c279\",\n    \"location\": {\n        \"address\": \"0x596003a91a97757ef1916c8d6c0d42592630d2cf\"\n    },\n    \"created\": \"2022-05-16T01:23:15Z\",\n    \"event\": {\n        \"name\": \"Changed\",\n        \"description\": \"\",\n        \"params\": [\n            {\n                \"name\": \"x\",\n                \"schema\": {\n                    \"type\": \"integer\",\n                    \"details\": {\n                        \"type\": \"uint256\",\n                        \"internalType\": \"uint256\"\n                    }\n                }\n            }\n        ]\n    },\n    \"signature\": \"0x596003a91a97757ef1916c8d6c0d42592630d2cf:Changed(uint256)\",\n    \"topic\": \"app1_topic\",\n    \"options\": {\n        \"firstEvent\": \"newest\"\n    },\n    \"filters\": [\n        {\n            \"event\": {\n                \"name\": \"Changed\",\n                \"description\": \"\",\n                \"params\": [\n                    {\n                        \"name\": \"x\",\n                        \"schema\": {\n                            \"type\": \"integer\",\n                            \"details\": {\n                                \"type\": \"uint256\",\n                                \"internalType\": \"uint256\"\n                            }\n                        }\n                    }\n                ]\n            },\n            \"location\": {\n                \"address\": \"0x596003a91a97757ef1916c8d6c0d42592630d2cf\"\n            },\n            \"signature\": \"0x596003a91a97757ef1916c8d6c0d42592630d2cf:Changed(uint256)\"\n        }\n    ]\n}\n</code></pre>"},{"location":"reference/types/contractlistener/#field-descriptions","title":"Field Descriptions","text":"Field Name Description Type <code>id</code> The UUID of the smart contract listener <code>UUID</code> <code>interface</code> Deprecated: Please use 'interface' in the array of 'filters' instead <code>FFIReference</code> <code>namespace</code> The namespace of the listener, which defines the namespace of all blockchain events detected by this listener <code>string</code> <code>name</code> A descriptive name for the listener <code>string</code> <code>backendId</code> An ID assigned by the blockchain connector to this listener <code>string</code> <code>location</code> Deprecated: Please use 'location' in the array of 'filters' instead <code>JSONAny</code> <code>created</code> The creation time of the listener <code>FFTime</code> <code>event</code> Deprecated: Please use 'event' in the array of 'filters' instead <code>FFISerializedEvent</code> <code>signature</code> A concatenation of all the stringified signature of the event and location, as computed by the blockchain plugin <code>string</code> <code>topic</code> A topic to set on the FireFly event that is emitted each time a blockchain event is detected from the blockchain. Setting this topic on a number of listeners allows applications to easily subscribe to all events they need <code>string</code> <code>options</code> Options that control how the listener subscribes to events from the underlying blockchain <code>ContractListenerOptions</code> <code>filters</code> A list of filters for the contract listener. Each filter is made up of an Event and an optional Location. Events matching these filters will always be emitted in the order determined by the blockchain. <code>ListenerFilter[]</code>"},{"location":"reference/types/contractlistener/#ffireference","title":"FFIReference","text":"Field Name Description Type <code>id</code> The UUID of the FireFly interface <code>UUID</code> <code>name</code> The name of the FireFly interface <code>string</code> <code>version</code> The version of the FireFly interface <code>string</code>"},{"location":"reference/types/contractlistener/#ffiserializedevent","title":"FFISerializedEvent","text":"Field Name Description Type <code>name</code> The name of the event <code>string</code> <code>description</code> A description of the smart contract event <code>string</code> <code>params</code> An array of event parameter/argument definitions <code>FFIParam[]</code> <code>details</code> Additional blockchain specific fields about this event from the original smart contract. Used by the blockchain plugin and for documentation generation. <code>JSONObject</code>"},{"location":"reference/types/contractlistener/#ffiparam","title":"FFIParam","text":"Field Name Description Type <code>name</code> The name of the parameter. Note that parameters must be ordered correctly on the FFI, according to the order in the blockchain smart contract <code>string</code> <code>schema</code> FireFly uses an extended subset of JSON Schema to describe parameters, similar to OpenAPI/Swagger. Converters are available for native blockchain interface definitions / type systems - such as an Ethereum ABI. See the documentation for more detail <code>JSONAny</code>"},{"location":"reference/types/contractlistener/#contractlisteneroptions","title":"ContractListenerOptions","text":"Field Name Description Type <code>firstEvent</code> A blockchain specific string, such as a block number, to start listening from. The special strings 'oldest' and 'newest' are supported by all blockchain connectors. Default is 'newest' <code>string</code>"},{"location":"reference/types/contractlistener/#listenerfilter","title":"ListenerFilter","text":"Field Name Description Type <code>event</code> The definition of the event, either provided in-line when creating the listener, or extracted from the referenced FFI <code>FFISerializedEvent</code> <code>location</code> A blockchain specific contract identifier. For example an Ethereum contract address, or a Fabric chaincode name and channel <code>JSONAny</code> <code>interface</code> A reference to an existing FFI, containing pre-registered type information for the event <code>FFIReference</code> <code>signature</code> The stringified signature of the event and location, as computed by the blockchain plugin <code>string</code>"},{"location":"reference/types/data/","title":"Data","text":"<p>Data is a uniquely identified piece of data available for retrieval or transfer.</p> <p>Multiple data items can be attached to a message when sending data off-chain to another party in a multi-party system. Note that if you pass data in-line when sending a message, those data elements will be stored separately to the message and available to retrieve separately later.</p> <p>An UUID is allocated to each data resource.</p> <p>A hash is also calculated as follows:</p> <ul> <li>If there is only data, the hash is of the <code>value</code> serialized as JSON with   no additional whitespace (order of the keys is retained from the original   upload order).</li> <li>If there is only a <code>blob</code> attachment, the hash is of the blob data.</li> <li>There is is both a <code>blob</code> and a <code>value</code>, then the hash is a hash of the   concatenation of a hash of the value and a hash of the blob.</li> </ul>"},{"location":"reference/types/data/#value-json-data-stored-in-the-core-database","title":"Value - JSON data stored in the core database","text":"<p>Each data resource can contain a <code>value</code>, which is any JSON type. String, number, boolean, array or object. This value is stored directly in the FireFly database.</p> <p>If the value you are storing is not JSON data, but is small enough you want it to be stored in the core database, then use a JSON string to store an encoded form of your data (such as XML, CSV etc.).</p>"},{"location":"reference/types/data/#datatype-validation-of-agreed-data-types","title":"Datatype - validation of agreed data types","text":"<p>A datatype can be associated with your data, causing FireFly to verify the <code>value</code> against a schema before accepting it (on upload, or receipt from another party in the network).</p> <p>These datatypes are pre-established via broadcast messages, and support versioning. Use this system to enforce a set of common data types for exchange of data across your business network, and reduce the overhead of data verification\\ required in the application/integration tier.</p> <p>More information in the Datatype section</p>"},{"location":"reference/types/data/#blob-binary-data-stored-via-the-data-exchange","title":"Blob - binary data stored via the Data Exchange","text":"<p>Data resources can also contain a <code>blob</code> attachment, which is stored via the Data Exchange plugin outside of the FireFly core database. This is intended for large data payloads, which might be structured or unstructured. PDF documents, multi-MB XML payloads, CSV data exports, JPEG images video files etc.</p> <p>A Data resource can contain both a <code>value</code> JSON payload, and a <code>blob</code> attachment, meaning that you bind a set of metadata to a binary payload. For example a set of extracted metadata from OCR processing of a PDF document.</p> <p>One special case is a filename for a document. This pattern is so common for file/document management scenarios, that special handling is provided for it. If a JSON object is stored in <code>value</code>, and it has a property called <code>name</code>, then this value forms part of the data hash (as does every field in the <code>value</code>) and is stored in a separately indexed <code>blob.name</code> field.</p> <p>The upload REST API provides an <code>autometa</code> form field, which can be set to ask FireFly core to automatically set the <code>value</code> to contain the filename, size, and MIME type from the file upload.</p>"},{"location":"reference/types/data/#example","title":"Example","text":"<pre><code>{\n    \"id\": \"4f11e022-01f4-4c3f-909f-5226947d9ef0\",\n    \"validator\": \"json\",\n    \"namespace\": \"ns1\",\n    \"hash\": \"5e2758423c99b799f53d3f04f587f5716c1ff19f1d1a050f40e02ea66860b491\",\n    \"created\": \"2022-05-16T01:23:15Z\",\n    \"datatype\": {\n        \"name\": \"widget\",\n        \"version\": \"v1.2.3\"\n    },\n    \"value\": {\n        \"name\": \"filename.pdf\",\n        \"a\": \"example\",\n        \"b\": {\n            \"c\": 12345\n        }\n    },\n    \"blob\": {\n        \"hash\": \"cef238f7b02803a799f040cdabe285ad5cd6db4a15cb9e2a1000f2860884c7ad\",\n        \"size\": 12345,\n        \"name\": \"filename.pdf\"\n    }\n}\n</code></pre>"},{"location":"reference/types/data/#field-descriptions","title":"Field Descriptions","text":"Field Name Description Type <code>id</code> The UUID of the data resource <code>UUID</code> <code>validator</code> The data validator type <code>FFEnum</code>: <code>namespace</code> The namespace of the data resource <code>string</code> <code>hash</code> The hash of the data resource. Derived from the value and the hash of any binary blob attachment <code>Bytes32</code> <code>created</code> The creation time of the data resource <code>FFTime</code> <code>datatype</code> The optional datatype to use of validation of this data <code>DatatypeRef</code> <code>value</code> The value for the data, stored in the FireFly core database. Can be any JSON type - object, array, string, number or boolean. Can be combined with a binary blob attachment <code>JSONAny</code> <code>public</code> If the JSON value has been published to shared storage, this field is the id of the data in the shared storage plugin (IPFS hash etc.) <code>string</code> <code>blob</code> An optional hash reference to a binary blob attachment <code>BlobRef</code>"},{"location":"reference/types/data/#datatyperef","title":"DatatypeRef","text":"Field Name Description Type <code>name</code> The name of the datatype <code>string</code> <code>version</code> The version of the datatype. Semantic versioning is encouraged, such as v1.0.1 <code>string</code>"},{"location":"reference/types/data/#blobref","title":"BlobRef","text":"Field Name Description Type <code>hash</code> The hash of the binary blob data <code>Bytes32</code> <code>size</code> The size of the binary data <code>int64</code> <code>name</code> The name field from the metadata attached to the blob, commonly used as a path/filename, and indexed for search <code>string</code> <code>path</code> If a name is specified, this field stores the '/' prefixed and separated path extracted from the full name <code>string</code> <code>public</code> If the blob data has been published to shared storage, this field is the id of the data in the shared storage plugin (IPFS hash etc.) <code>string</code>"},{"location":"reference/types/datatype/","title":"Datatype","text":"<p>A datatype defines the format of some data that can be shared between parties, in a way that FireFly can enforce consistency of that data against the schema.</p> <p>Data that does not match the schema associated with it will not be accepted on upload to FireFly, and if this were bypassed by a participant in some way it would be rejected by all parties and result in a <code>message_rejected</code> event (rather than <code>message_confirmed</code> event).</p> <p>Currently JSON Schema validation of data is supported.</p> <p>The system for defining datatypes is pluggable, to support other schemes in the future, such as XML Schema, or CSV, EDI etc.</p>"},{"location":"reference/types/datatype/#example","title":"Example","text":"<pre><code>{\n    \"id\": \"3a479f7e-ddda-4bda-aa24-56d06c0bf08e\",\n    \"message\": \"bfcf904c-bdf7-40aa-bbd7-567f625c26c0\",\n    \"validator\": \"json\",\n    \"namespace\": \"ns1\",\n    \"name\": \"widget\",\n    \"version\": \"1.0.0\",\n    \"hash\": \"639cd98c893fa45a9df6fd87bd0393a9b39e31e26fbb1eeefe90cb40c3fa02d2\",\n    \"created\": \"2022-05-16T01:23:16Z\",\n    \"value\": {\n        \"$id\": \"https://example.com/widget.schema.json\",\n        \"$schema\": \"https://json-schema.org/draft/2020-12/schema\",\n        \"title\": \"Widget\",\n        \"type\": \"object\",\n        \"properties\": {\n            \"id\": {\n                \"type\": \"string\",\n                \"description\": \"The unique identifier for the widget.\"\n            },\n            \"name\": {\n                \"type\": \"string\",\n                \"description\": \"The person's last name.\"\n            }\n        },\n        \"additionalProperties\": false\n    }\n}\n</code></pre>"},{"location":"reference/types/datatype/#field-descriptions","title":"Field Descriptions","text":"Field Name Description Type <code>id</code> The UUID of the datatype <code>UUID</code> <code>message</code> The UUID of the broadcast message that was used to publish this datatype to the network <code>UUID</code> <code>validator</code> The validator that should be used to verify this datatype <code>FFEnum</code>:<code>\"json\"</code><code>\"none\"</code><code>\"definition\"</code> <code>namespace</code> The namespace of the datatype. Data resources can only be created referencing datatypes in the same namespace <code>string</code> <code>name</code> The name of the datatype <code>string</code> <code>version</code> The version of the datatype. Multiple versions can exist with the same name. Use of semantic versioning is encourages, such as v1.0.1 <code>string</code> <code>hash</code> The hash of the value, such as the JSON schema. Allows all parties to be confident they have the exact same rules for verifying data created against a datatype <code>Bytes32</code> <code>created</code> The time the datatype was created <code>FFTime</code> <code>value</code> The definition of the datatype, in the syntax supported by the validator (such as a JSON Schema definition) <code>JSONAny</code>"},{"location":"reference/types/event/","title":"Event","text":"<p>Every Event emitted by FireFly shares a common structure.</p> <p>See Events for a reference for how the overall event bus in Hyperledger FireFly operates, and descriptions of all the sub-categories of events.</p>"},{"location":"reference/types/event/#sequence","title":"Sequence","text":"<p>A local <code>sequence</code> number is assigned to each event, and you can use an API to query events using this sequence number in exactly the same order that they are delivered to your application.</p>"},{"location":"reference/types/event/#reference","title":"Reference","text":"<p>Events have a <code>reference</code> to the UUID of an object that is the subject of the event, such as a detailed Blockchain Event, or an off-chain Message.</p> <p>When events are delivered to your application, the <code>reference</code> field is automatically retrieved and included in the JSON payload that is delivered to your application.</p> <p>You can use the <code>?fetchreferences</code> query parameter on API calls to request the same in-line JSON payload be included in query results.</p> <p>The type of the reference also determines what subscription filters apply when performing server-side filters.</p> <p>Here is the mapping between event types, and the object that you find in the <code>reference</code> field.</p>"},{"location":"reference/types/event/#correlator","title":"Correlator","text":"<p>For some event types, there is a secondary reference to an object that is associated with the event. This is set in a <code>correlator</code> field on the Event, but is not automatically fetched. This field is primarily used for the <code>confirm</code> option on API calls to allow FireFly to determine when a request has succeeded/failed.</p>"},{"location":"reference/types/event/#topic","title":"Topic","text":"<p>Events have a <code>topic</code>, and how that topic is determined is specific to the type of event. This is intended to be a property you would use to filter events to your application, or query all historical events associated with a given business data stream.</p> <p>For example when you send a Message, you set the <code>topics</code> you want that message to apply to, and FireFly ensures a consistent global order between all parties that receive that message.</p>"},{"location":"reference/types/event/#transaction","title":"Transaction","text":"<p>When actions are submitted by a FireFly node, they are performed within a FireFly Transaction. The events that occur as a direct result of that transaction, are tagged with the transaction ID so that they can be grouped together.</p> <p>This construct is a distinct higher level construct than a Blockchain transaction, that groups together a number of operations/events that might be on-chain or off-chain. In some cases, such as unpinned off-chain data transfer, a FireFly transaction can exist when there is no blockchain transaction at all. Wherever possible you will find that FireFly tags the FireFly transaction with any associated Blockchain transaction(s).</p> <p>Note that some events cannot be tagged with a Transaction ID:</p> <ul> <li>Blockchain events, unless they were part of a batch-pin transaction   for transfer of a message</li> <li>Token transfers/approvals, unless they had a message transfer associated   with them (and included a <code>data</code> payload in the event they emitted)</li> </ul>"},{"location":"reference/types/event/#reference-topic-and-correlator-by-event-type","title":"Reference, Topic and Correlator by Event Type","text":"Types Reference Topic Correlator <code>transaction_submitted</code> Transaction <code>transaction.type</code> <code>message_confirmed</code><code>message_rejected</code> Message <code>message.header.topics[i]</code>* <code>message.header.cid</code> <code>token_pool_confirmed</code> TokenPool <code>tokenPool.id</code> <code>token_pool_op_failed</code> Operation <code>tokenPool.id</code> <code>tokenPool.id</code> <code>token_transfer_confirmed</code> TokenTransfer <code>tokenPool.id</code> <code>token_transfer_op_failed</code> Operation <code>tokenPool.id</code> <code>tokenTransfer.localId</code> <code>token_approval_confirmed</code> TokenApproval <code>tokenPool.id</code> <code>token_approval_op_failed</code> Operation <code>tokenPool.id</code> <code>tokenApproval.localId</code> <code>namespace_confirmed</code> Namespace <code>\"ff_definition\"</code> <code>datatype_confirmed</code> Datatype <code>\"ff_definition\"</code> <code>identity_confirmed</code><code>identity_updated</code> Identity <code>\"ff_definition\"</code> <code>contract_interface_confirmed</code> FFI <code>\"ff_definition\"</code> <code>contract_api_confirmed</code> ContractAPI <code>\"ff_definition\"</code> <code>blockchain_event_received</code> BlockchainEvent From listener ** <code>blockchain_invoke_op_succeeded</code> Operation <code>blockchain_invoke_op_failed</code> Operation <code>blockchain_contract_deploy_op_succeeded</code> Operation <code>blockchain_contract_deploy_op_failed</code> Operation <ul> <li>A separate event is emitted for each topic associated with a Message.</li> </ul> <p>** The topic for a blockchain event is inherited from the blockchain listener, allowing you to create multiple blockchain listeners that all deliver messages to your application on a single FireFly topic.</p>"},{"location":"reference/types/event/#example","title":"Example","text":"<pre><code>{\n    \"id\": \"5f875824-b36b-4559-9791-a57a2e2b30dd\",\n    \"sequence\": 168,\n    \"type\": \"transaction_submitted\",\n    \"namespace\": \"ns1\",\n    \"reference\": \"0d12aa75-5ed8-48a7-8b54-45274c6edcb1\",\n    \"tx\": \"0d12aa75-5ed8-48a7-8b54-45274c6edcb1\",\n    \"topic\": \"batch_pin\",\n    \"created\": \"2022-05-16T01:23:15Z\"\n}\n</code></pre>"},{"location":"reference/types/event/#field-descriptions","title":"Field Descriptions","text":"Field Name Description Type <code>id</code> The UUID assigned to this event by your local FireFly node <code>UUID</code> <code>sequence</code> A sequence indicating the order in which events are delivered to your application. Assure to be unique per event in your local FireFly database (unlike the created timestamp) <code>int64</code> <code>type</code> All interesting activity in FireFly is emitted as a FireFly event, of a given type. The 'type' combined with the 'reference' can be used to determine how to process the event within your application <code>FFEnum</code>:<code>\"transaction_submitted\"</code><code>\"message_confirmed\"</code><code>\"message_rejected\"</code><code>\"datatype_confirmed\"</code><code>\"identity_confirmed\"</code><code>\"identity_updated\"</code><code>\"token_pool_confirmed\"</code><code>\"token_pool_op_failed\"</code><code>\"token_transfer_confirmed\"</code><code>\"token_transfer_op_failed\"</code><code>\"token_approval_confirmed\"</code><code>\"token_approval_op_failed\"</code><code>\"contract_interface_confirmed\"</code><code>\"contract_api_confirmed\"</code><code>\"blockchain_event_received\"</code><code>\"blockchain_invoke_op_succeeded\"</code><code>\"blockchain_invoke_op_failed\"</code><code>\"blockchain_contract_deploy_op_succeeded\"</code><code>\"blockchain_contract_deploy_op_failed\"</code> <code>namespace</code> The namespace of the event. Your application must subscribe to events within a namespace <code>string</code> <code>reference</code> The UUID of an resource that is the subject of this event. The event type determines what type of resource is referenced, and whether this field might be unset <code>UUID</code> <code>correlator</code> For message events, this is the 'header.cid' field from the referenced message. For certain other event types, a secondary object is referenced such as a token pool <code>UUID</code> <code>tx</code> The UUID of a transaction that is event is part of. Not all events are part of a transaction <code>UUID</code> <code>topic</code> A stream of information this event relates to. For message confirmation events, a separate event is emitted for each topic in the message. For blockchain events, the listener specifies the topic. Rules exist for how the topic is set for other event types <code>string</code> <code>created</code> The time the event was emitted. Not guaranteed to be unique, or to increase between events in the same order as the final sequence events are delivered to your application. As such, the 'sequence' field should be used instead of the 'created' field for querying events in the exact order they are delivered to applications <code>FFTime</code>"},{"location":"reference/types/ffi/","title":"FFI","text":"<p>See FireFly Interface Format</p>"},{"location":"reference/types/ffi/#example","title":"Example","text":"<pre><code>{\n    \"id\": \"c35d3449-4f24-4676-8e64-91c9e46f06c4\",\n    \"message\": \"e4ad2077-5714-416e-81f9-7964a6223b6f\",\n    \"namespace\": \"ns1\",\n    \"name\": \"SimpleStorage\",\n    \"description\": \"A simple example contract in Solidity\",\n    \"version\": \"v0.0.1\",\n    \"methods\": [\n        {\n            \"id\": \"8f3289dd-3a19-4a9f-aab3-cb05289b013c\",\n            \"interface\": \"c35d3449-4f24-4676-8e64-91c9e46f06c4\",\n            \"name\": \"get\",\n            \"namespace\": \"ns1\",\n            \"pathname\": \"get\",\n            \"description\": \"Get the current value\",\n            \"params\": [],\n            \"returns\": [\n                {\n                    \"name\": \"output\",\n                    \"schema\": {\n                        \"type\": \"integer\",\n                        \"details\": {\n                            \"type\": \"uint256\"\n                        }\n                    }\n                }\n            ],\n            \"details\": {\n                \"stateMutability\": \"viewable\"\n            }\n        },\n        {\n            \"id\": \"fc6f54ee-2e3c-4e56-b17c-4a1a0ae7394b\",\n            \"interface\": \"c35d3449-4f24-4676-8e64-91c9e46f06c4\",\n            \"name\": \"set\",\n            \"namespace\": \"ns1\",\n            \"pathname\": \"set\",\n            \"description\": \"Set the value\",\n            \"params\": [\n                {\n                    \"name\": \"newValue\",\n                    \"schema\": {\n                        \"type\": \"integer\",\n                        \"details\": {\n                            \"type\": \"uint256\"\n                        }\n                    }\n                }\n            ],\n            \"returns\": [],\n            \"details\": {\n                \"stateMutability\": \"payable\"\n            }\n        }\n    ],\n    \"events\": [\n        {\n            \"id\": \"9f653f93-86f4-45bc-be75-d7f5888fbbc0\",\n            \"interface\": \"c35d3449-4f24-4676-8e64-91c9e46f06c4\",\n            \"namespace\": \"ns1\",\n            \"pathname\": \"Changed\",\n            \"signature\": \"Changed(address,uint256)\",\n            \"name\": \"Changed\",\n            \"description\": \"Emitted when the value changes\",\n            \"params\": [\n                {\n                    \"name\": \"_from\",\n                    \"schema\": {\n                        \"type\": \"string\",\n                        \"details\": {\n                            \"type\": \"address\",\n                            \"indexed\": true\n                        }\n                    }\n                },\n                {\n                    \"name\": \"_value\",\n                    \"schema\": {\n                        \"type\": \"integer\",\n                        \"details\": {\n                            \"type\": \"uint256\"\n                        }\n                    }\n                }\n            ]\n        }\n    ],\n    \"published\": false\n}\n</code></pre>"},{"location":"reference/types/ffi/#field-descriptions","title":"Field Descriptions","text":"Field Name Description Type <code>id</code> The UUID of the FireFly interface (FFI) smart contract definition <code>UUID</code> <code>message</code> The UUID of the broadcast message that was used to publish this FFI to the network <code>UUID</code> <code>namespace</code> The namespace of the FFI <code>string</code> <code>name</code> The name of the FFI - usually matching the smart contract name <code>string</code> <code>networkName</code> The published name of the FFI within the multiparty network <code>string</code> <code>description</code> A description of the smart contract this FFI represents <code>string</code> <code>version</code> A version for the FFI - use of semantic versioning such as 'v1.0.1' is encouraged <code>string</code> <code>methods</code> An array of smart contract method definitions <code>FFIMethod[]</code> <code>events</code> An array of smart contract event definitions <code>FFIEvent[]</code> <code>errors</code> An array of smart contract error definitions <code>FFIError[]</code> <code>published</code> Indicates if the FFI is published to other members of the multiparty network <code>bool</code>"},{"location":"reference/types/ffi/#ffimethod","title":"FFIMethod","text":"Field Name Description Type <code>id</code> The UUID of the FFI method definition <code>UUID</code> <code>interface</code> The UUID of the FFI smart contract definition that this method is part of <code>UUID</code> <code>name</code> The name of the method <code>string</code> <code>namespace</code> The namespace of the FFI <code>string</code> <code>pathname</code> The unique name allocated to this method within the FFI for use on URL paths. Supports contracts that have multiple method overrides with the same name <code>string</code> <code>description</code> A description of the smart contract method <code>string</code> <code>params</code> An array of method parameter/argument definitions <code>FFIParam[]</code> <code>returns</code> An array of method return definitions <code>FFIParam[]</code> <code>details</code> Additional blockchain specific fields about this method from the original smart contract. Used by the blockchain plugin and for documentation generation. <code>JSONObject</code>"},{"location":"reference/types/ffi/#ffiparam","title":"FFIParam","text":"Field Name Description Type <code>name</code> The name of the parameter. Note that parameters must be ordered correctly on the FFI, according to the order in the blockchain smart contract <code>string</code> <code>schema</code> FireFly uses an extended subset of JSON Schema to describe parameters, similar to OpenAPI/Swagger. Converters are available for native blockchain interface definitions / type systems - such as an Ethereum ABI. See the documentation for more detail <code>JSONAny</code>"},{"location":"reference/types/ffi/#ffievent","title":"FFIEvent","text":"Field Name Description Type <code>id</code> The UUID of the FFI event definition <code>UUID</code> <code>interface</code> The UUID of the FFI smart contract definition that this event is part of <code>UUID</code> <code>namespace</code> The namespace of the FFI <code>string</code> <code>pathname</code> The unique name allocated to this event within the FFI for use on URL paths. Supports contracts that have multiple event overrides with the same name <code>string</code> <code>signature</code> The stringified signature of the event, as computed by the blockchain plugin <code>string</code> <code>name</code> The name of the event <code>string</code> <code>description</code> A description of the smart contract event <code>string</code> <code>params</code> An array of event parameter/argument definitions <code>FFIParam[]</code> <code>details</code> Additional blockchain specific fields about this event from the original smart contract. Used by the blockchain plugin and for documentation generation. <code>JSONObject</code>"},{"location":"reference/types/ffi/#ffiparam_1","title":"FFIParam","text":"Field Name Description Type <code>name</code> The name of the parameter. Note that parameters must be ordered correctly on the FFI, according to the order in the blockchain smart contract <code>string</code> <code>schema</code> FireFly uses an extended subset of JSON Schema to describe parameters, similar to OpenAPI/Swagger. Converters are available for native blockchain interface definitions / type systems - such as an Ethereum ABI. See the documentation for more detail <code>JSONAny</code>"},{"location":"reference/types/ffi/#ffierror","title":"FFIError","text":"Field Name Description Type <code>id</code> The UUID of the FFI error definition <code>UUID</code> <code>interface</code> The UUID of the FFI smart contract definition that this error is part of <code>UUID</code> <code>namespace</code> The namespace of the FFI <code>string</code> <code>pathname</code> The unique name allocated to this error within the FFI for use on URL paths <code>string</code> <code>signature</code> The stringified signature of the error, as computed by the blockchain plugin <code>string</code> <code>name</code> The name of the error <code>string</code> <code>description</code> A description of the smart contract error <code>string</code> <code>params</code> An array of error parameter/argument definitions <code>FFIParam[]</code>"},{"location":"reference/types/ffi/#ffiparam_2","title":"FFIParam","text":"Field Name Description Type <code>name</code> The name of the parameter. Note that parameters must be ordered correctly on the FFI, according to the order in the blockchain smart contract <code>string</code> <code>schema</code> FireFly uses an extended subset of JSON Schema to describe parameters, similar to OpenAPI/Swagger. Converters are available for native blockchain interface definitions / type systems - such as an Ethereum ABI. See the documentation for more detail <code>JSONAny</code>"},{"location":"reference/types/group/","title":"Group","text":"<p>A privacy group is a list of identities that should receive a private communication.</p> <p>When you send a private message, you can specify the list of participants in-line and it will be resolved to a group. Or you can reference the group using its identifying hash.</p> <p>The sender of a message must be included in the group along with the other participants. The sender receives an event confirming the message, just as any other participant would do.</p> <p>The sender is included automatically in the group when members are specified in-line, if it is omitted.</p>"},{"location":"reference/types/group/#group-identity-hash","title":"Group identity hash","text":"<p>The identifying hash for a group is determined as follows:</p> <ul> <li>All identities are resolved to their DID.</li> <li>An organization name or identity UUID can be used on input</li> <li>The UUID of the node that should receive the data for each participant is   determined (if not specified).</li> <li>The first node found that is in the same identity hierarchy as the     participant identity, will be chosen.</li> <li>The list of participants is ordered by DID, with de-duplication of   any identities.</li> <li>The <code>namespace</code>, <code>name</code>, and <code>members</code> array are then serialized into   a JSON object, without whitespace.</li> <li>A SHA256 hash of the JSON object is calculated</li> </ul>"},{"location":"reference/types/group/#private-messaging-architecture","title":"Private messaging architecture","text":"<p>The mechanism that keeps data private and ordered, without leaking data to the blockchain, is summarized in the below diagram.</p> <p>The key points are:</p> <ul> <li>Data is sent off-chain to all participants via the Data Exchange plugin</li> <li>The Data Exchange is responsible for encryption and off-chain identity verification</li> <li>Only parties that are involved in the privacy group receive the data</li> <li>Other parties are only able to view the blockchain transaction</li> <li>The hash and member list of the group are not shared outside of the privacy group</li> <li>The <code>name</code> of the group can be used as an additional salt in generation of the group hash</li> <li>The member list must be known by all members of the group to verify the blockchain transactions,     so the full group JSON structure is communicated privately with the first message     sent on a group</li> <li>The blockchain transaction is the source of truth for ordering</li> <li>All members are able to detect a blockchain transaction is part of a group     they are a member of, from only the blockchain transaction - so they can block     processing of subsequent messages until the off-chain data arrives (asynchronously)</li> <li>The ordering context for messages is masked on the blockchain, so that two messages   that are for same group do not contain the same context</li> <li>The ordering context (<code>topic</code>+<code>group</code>) is combined with a <code>nonce</code> that is incremented     for each individual sender, to form a message-specific hash.</li> <li>For each blockchain transaction, this hash can be compared against the expected next     hash for each member to determine if it is a message on a known group - even without     the private data (which might arrive later)</li> </ul> <p>See NextPin for more information on the structure used for storing the next expected masked context pin, for each member of the privacy group.</p> <p></p>"},{"location":"reference/types/group/#example","title":"Example","text":"<pre><code>{\n    \"namespace\": \"ns1\",\n    \"name\": \"\",\n    \"members\": [\n        {\n            \"identity\": \"did:firefly:org/1111\",\n            \"node\": \"4f563179-b4bd-4161-86e0-c2c1c0869c4f\"\n        },\n        {\n            \"identity\": \"did:firefly:org/2222\",\n            \"node\": \"61a99af8-c1f7-48ea-8fcc-489e4822a0ed\"\n        }\n    ],\n    \"localNamespace\": \"ns1\",\n    \"message\": \"0b9dfb76-103d-443d-92fd-b114fe07c54d\",\n    \"hash\": \"c52ad6c034cf5c7382d9a294f49297096a52eb55cc2da696c564b2a276633b95\",\n    \"created\": \"2022-05-16T01:23:16Z\"\n}\n</code></pre>"},{"location":"reference/types/group/#field-descriptions","title":"Field Descriptions","text":"Field Name Description Type <code>namespace</code> The namespace of the group within the multiparty network <code>string</code> <code>name</code> The optional name of the group, allowing multiple unique groups to exist with the same list of recipients <code>string</code> <code>members</code> The list of members in this privacy group <code>Member[]</code> <code>localNamespace</code> The local namespace of the group <code>string</code> <code>message</code> The message used to broadcast this group privately to the members <code>UUID</code> <code>hash</code> The identifier hash of this group. Derived from the name and group members <code>Bytes32</code> <code>created</code> The time when the group was first used to send a message in the network <code>FFTime</code>"},{"location":"reference/types/group/#member","title":"Member","text":"Field Name Description Type <code>identity</code> The DID of the group member <code>string</code> <code>node</code> The UUID of the node that receives a copy of the off-chain message for the identity <code>UUID</code>"},{"location":"reference/types/identity/","title":"Identity","text":"<p>FireFly contains an address book of identities, which is managed in a decentralized way across a multi-party system through <code>claim</code> and <code>verification</code> system.</p> <p>See FIR-12 for evolution that is happening to Hyperledger FireFly to allow:</p> <ul> <li>Private address books that are not shared with other participants</li> <li>Multiple address books backed by different chains, in the same node</li> </ul> <p>Root identities are registered with only a <code>claim</code> - which is a signed transaction from a particular blockchain account, to bind a DID with a <code>name</code> that is unique within the network, to that signing key.</p> <p>The signing key then becomes a Verifier for that identity. Using that key the root identity can be used to register a new FireFly node in the network, send and receive messages, and register child identities.</p> <p>When child identities are registered, a <code>claim</code> using a key that is going to be the Verifier for that child identity is required. However, this is insufficient to establish that identity as a child identity of the parent. There must be an additional <code>verification</code> that references the <code>claim</code> (by UUID) using the key verifier of the parent identity.</p>"},{"location":"reference/types/identity/#dids","title":"DIDs","text":"<p>FireFly has adopted the DID standard for representing identities. A \"DID Method\" name of <code>firefly</code> is used to represent that the built-in identity system of Hyperledger FireFly is being used to resolve these DIDs.</p> <p>So an example FireFly DID for organization <code>abcd1234</code> is:</p> <ul> <li><code>did:firefly:org/abcd1234</code></li> </ul> <p>The adoption of DIDs in Hyperledger FireFly v1.0 is also a stepping stone to allowing pluggable DID based identity resolvers into FireFly in the future.</p> <p>You can also download a DID Document for a FireFly identity, which represents the verifiers and other information about that identity according to the JSON format in the DID standard.</p>"},{"location":"reference/types/identity/#example","title":"Example","text":"<pre><code>{\n    \"id\": \"114f5857-9983-46fb-b1fc-8c8f0a20846c\",\n    \"did\": \"did:firefly:org/org_1\",\n    \"type\": \"org\",\n    \"parent\": \"688072c3-4fa0-436c-a86b-5d89673b8938\",\n    \"namespace\": \"ff_system\",\n    \"name\": \"org_1\",\n    \"messages\": {\n        \"claim\": \"911b364b-5863-4e49-a3f8-766dbbae7c4c\",\n        \"verification\": \"24636f11-c1f9-4bbb-9874-04dd24c7502f\",\n        \"update\": null\n    },\n    \"created\": \"2022-05-16T01:23:15Z\"\n}\n</code></pre>"},{"location":"reference/types/identity/#field-descriptions","title":"Field Descriptions","text":"Field Name Description Type <code>id</code> The UUID of the identity <code>UUID</code> <code>did</code> The DID of the identity. Unique across namespaces within a FireFly network <code>string</code> <code>type</code> The type of the identity <code>FFEnum</code>:<code>\"org\"</code><code>\"node\"</code><code>\"custom\"</code> <code>parent</code> The UUID of the parent identity. Unset for root organization identities <code>UUID</code> <code>namespace</code> The namespace of the identity. Organization and node identities are always defined in the ff_system namespace <code>string</code> <code>name</code> The name of the identity. The name must be unique within the type and namespace <code>string</code> <code>description</code> A description of the identity. Part of the updatable profile information of an identity <code>string</code> <code>profile</code> A set of metadata for the identity. Part of the updatable profile information of an identity <code>JSONObject</code> <code>messages</code> References to the broadcast messages that established this identity and proved ownership of the associated verifiers (keys) <code>IdentityMessages</code> <code>created</code> The creation time of the identity <code>FFTime</code> <code>updated</code> The last update time of the identity profile <code>FFTime</code>"},{"location":"reference/types/identity/#identitymessages","title":"IdentityMessages","text":"Field Name Description Type <code>claim</code> The UUID of claim message <code>UUID</code> <code>verification</code> The UUID of claim message. Unset for root organization identities <code>UUID</code> <code>update</code> The UUID of the most recently applied update message. Unset if no updates have been confirmed <code>UUID</code>"},{"location":"reference/types/message/","title":"Message","text":"<p>Message is the envelope by which coordinated data exchange can happen between parties in the network. Data is passed by reference in these messages, and a chain of hashes covering the data and the details of the message, provides a verification against tampering.</p> <p>A message is made up of three sections:</p> <ol> <li>The header - a set of metadata that determines how the message is ordered, who should receive it, and how they should process it</li> <li>The data - an array of data attachments</li> <li>Status information - fields that are calculated independently by each node, and hence update as the message makes it way through the system</li> </ol>"},{"location":"reference/types/message/#hash","title":"Hash","text":"<p>Sections (1) and (2) are fixed once the message is sent, and a <code>hash</code> is generated that provides tamper protection.</p> <p>The hash is a function of the header, and all of the data payloads. Calculated as follows:</p> <ul> <li>The hash of each Data element is calculated individually</li> <li>A JSON array of <code>[{\"id\":\"{{DATA_UUID}}\",\"hash\":\"{{DATA_HASH}}\"}]</code> is hashed, and that hash is stored in <code>header.datahash</code></li> <li>The <code>header</code> is serialized as JSON with the deterministic order (listed below) and hashed</li> <li>JSON data is serialized without whitespace to hash it.</li> <li>The hashing algorithm is SHA-256</li> </ul> <p>Each node independently calculates the hash, and the hash is included in the manifest of the Batch by the node that sends the message. Because the hash of that batch manifest is included in the blockchain transaction, a message transferred to a node that does not match the original message hash is rejected.</p>"},{"location":"reference/types/message/#tag","title":"Tag","text":"<p>The <code>header.tag</code> tells the processors of the message how it should be processed, and what data they should expect it to contain.</p> <p>If you think of your decentralized application like a state machine, then you need to have a set of well defined transitions that can be performed between states. Each of these transitions that requires off-chain transfer of private data (optionally coordinated with an on-chain transaction) should be expressed as a type of message, with a particular <code>tag</code>.</p> <p>Every copy of the application that runs in the participants of the network should look at this <code>tag</code> to determine what logic to execute against it.</p> <p>Note: For consistency in ordering, the sender should also wait to process the state machine transitions associated with the message they send until it is ordered by the blockchain. They should not consider themselves special because they sent the message, and process it immediately - otherwise they could end up processing it in a different order to other parties in the network that are also processing the message.</p>"},{"location":"reference/types/message/#topics","title":"Topics","text":"<p>The <code>header.topics</code> strings allow you to set the the ordering context for each message you send, and you are strongly encouraged to set it explicitly on every message you send (falling back to the <code>default</code> topic is not recommended).</p> <p>A key difference between blockchain backed decentralized applications and other event-driven applications, is that there is a single source of truth for the order in which things happen.</p> <p>In a multi-party system with off-chain transfer of data as well as on-chain transfer of data, the two sets of data need to be coordinated together. The off-chain transfer might happen at different times, and is subject to the reliability of the parties &amp; network links involved in that off-chain communication.</p> <p>A \"stop the world\" approach to handling a single piece of missing data is not practical for a high volume production business network.</p> <p>The ordering context is a function of:</p> <ol> <li>Whether the message is broadcast or private</li> <li>If it is private, the privacy group associated with the message</li> <li>The <code>topic</code> of the message</li> </ol> <p>When an on-chain transaction is detected by FireFly, it can determine the above ordering - noting that privacy is preserved for private messages by masking this ordering context message-by-message with a nonce and the group ID, so that only the participants in that group can decode the ordering context.</p> <p>If a piece of off-chain data is unavailable, then the FireFly node will block only streams of data that are associated with that ordering context.</p> <p>For your application, you should choose the most granular identifier you can for your <code>topic</code> to minimize the scope of any blockage if one item of off-chain data fails to be delivered or is delayed. Some good examples are:</p> <ul> <li>A business transaction identifier - to ensure all data related to particular business transaction are processed in order</li> <li>A globally agreed customer identifier - to ensure all data related to a particular business entity are processed in order</li> </ul>"},{"location":"reference/types/message/#using-multiple-topics","title":"Using multiple topics","text":"<p>There are some advanced scenarios where you need to merge streams of ordered data, so that two previously separately ordered streams of communication (different state machines) are joined together to process a critical decision/transition in a deterministic order.</p> <p>A synchronization point between two otherwise independent streams of communication.</p> <p>To do this, simply specify two <code>topics</code> in the message you sent, and the message will be independently ordered against both of those topics.</p> <p>You will also receive two events for the confirmation of that message, one for each topic.</p> <p>Some examples:</p> <ul> <li>Agreeing to join two previously separate business transactions with ids <code>000001</code> and <code>000002</code>, by discarding business transaction <code>000001</code> as a duplicate</li> <li>Specify <code>topics: [\"000001\",\"000002\"]</code> on the special merge message, and then from that point onwards you would only need to specify <code>topics: [\"000002\"]</code>.</li> <li>Agreeing to join two previously separate entities with <code>id1</code> and <code>id2</code>, into a merged entity with <code>id3</code>.</li> <li>Specify <code>topics: [\"id1\",\"id2\",\"id3\"]</code> on the special merge message, and then from that point onwards you would only need to specify <code>topics: [\"id3\"]</code>.</li> </ul>"},{"location":"reference/types/message/#transaction-type","title":"Transaction type","text":"<p>By default messages are pinned to the blockchain, within a Batch.</p> <p>For private messages, you can choose to disable this pinning by setting <code>header.txtype: \"unpinned\"</code>.</p> <p>Broadcast messages must be pinned to the blockchain.</p>"},{"location":"reference/types/message/#in-line-data","title":"In-line data","text":"<p>When sending a message you can specify the array of Data attachments in-line, as part of the same JSON payload.</p> <p>For example, a minimal broadcast message could be:</p> <pre><code>{\n    \"data\": [\n        {\"value\": \"hello world\"}\n    ]\n}\n</code></pre> <p>When you send this message with <code>/api/v1/namespaces/{ns}/messages/broadcast</code>:</p> <ul> <li>The <code>header</code> will be initialized with the default values, including <code>txtype: \"batch_pin\"</code></li> <li>The <code>data[0]</code> entry will be stored as a Data resource</li> <li>The message will be assembled into a batch and broadcast</li> </ul>"},{"location":"reference/types/message/#example","title":"Example","text":"<pre><code>{\n    \"header\": {\n        \"id\": \"4ea27cce-a103-4187-b318-f7b20fd87bf3\",\n        \"cid\": \"00d20cba-76ed-431d-b9ff-f04b4cbee55c\",\n        \"type\": \"private\",\n        \"txtype\": \"batch_pin\",\n        \"author\": \"did:firefly:org/acme\",\n        \"key\": \"0xD53B0294B6a596D404809b1d51D1b4B3d1aD4945\",\n        \"created\": \"2022-05-16T01:23:10Z\",\n        \"namespace\": \"ns1\",\n        \"group\": \"781caa6738a604344ae86ee336ada1b48a404a85e7041cf75b864e50e3b14a22\",\n        \"topics\": [\n            \"topic1\"\n        ],\n        \"tag\": \"blue_message\",\n        \"datahash\": \"c07be180b147049baced0b6219d9ce7a84ab48f2ca7ca7ae949abb3fe6491b54\"\n    },\n    \"localNamespace\": \"ns1\",\n    \"state\": \"confirmed\",\n    \"confirmed\": \"2022-05-16T01:23:16Z\",\n    \"data\": [\n        {\n            \"id\": \"fdf9f118-eb81-4086-a63d-b06715b3bb4e\",\n            \"hash\": \"34cf848d896c83cdf433ea7bd9490c71800b316a96aac3c3a78a42a4c455d67d\"\n        }\n    ]\n}\n</code></pre>"},{"location":"reference/types/message/#field-descriptions","title":"Field Descriptions","text":"Field Name Description Type <code>header</code> The message header contains all fields that are used to build the message hash <code>MessageHeader</code> <code>localNamespace</code> The local namespace of the message <code>string</code> <code>hash</code> The hash of the message. Derived from the header, which includes the data hash <code>Bytes32</code> <code>batch</code> The UUID of the batch in which the message was pinned/transferred <code>UUID</code> <code>txid</code> The ID of the transaction used to order/deliver this message <code>UUID</code> <code>state</code> The current state of the message <code>FFEnum</code>:<code>\"staged\"</code><code>\"ready\"</code><code>\"sent\"</code><code>\"pending\"</code><code>\"confirmed\"</code><code>\"rejected\"</code><code>\"cancelled\"</code> <code>confirmed</code> The timestamp of when the message was confirmed/rejected <code>FFTime</code> <code>rejectReason</code> If a message was rejected, provides details on the rejection reason <code>string</code> <code>data</code> The list of data elements attached to the message <code>DataRef[]</code> <code>pins</code> For private messages, a unique pin hash:nonce is assigned for each topic <code>string[]</code> <code>idempotencyKey</code> An optional unique identifier for a message. Cannot be duplicated within a namespace, thus allowing idempotent submission of messages to the API. Local only - not transferred when the message is sent to other members of the network <code>IdempotencyKey</code>"},{"location":"reference/types/message/#messageheader","title":"MessageHeader","text":"Field Name Description Type <code>id</code> The UUID of the message. Unique to each message <code>UUID</code> <code>cid</code> The correlation ID of the message. Set this when a message is a response to another message <code>UUID</code> <code>type</code> The type of the message <code>FFEnum</code>:<code>\"definition\"</code><code>\"broadcast\"</code><code>\"private\"</code><code>\"groupinit\"</code><code>\"transfer_broadcast\"</code><code>\"transfer_private\"</code><code>\"approval_broadcast\"</code><code>\"approval_private\"</code> <code>txtype</code> The type of transaction used to order/deliver this message <code>FFEnum</code>:<code>\"none\"</code><code>\"unpinned\"</code><code>\"batch_pin\"</code><code>\"network_action\"</code><code>\"token_pool\"</code><code>\"token_transfer\"</code><code>\"contract_deploy\"</code><code>\"contract_invoke\"</code><code>\"contract_invoke_pin\"</code><code>\"token_approval\"</code><code>\"data_publish\"</code> <code>author</code> The DID of identity of the submitter <code>string</code> <code>key</code> The on-chain signing key used to sign the transaction <code>string</code> <code>created</code> The creation time of the message <code>FFTime</code> <code>namespace</code> The namespace of the message within the multiparty network <code>string</code> <code>topics</code> A message topic associates this message with an ordered stream of data. A custom topic should be assigned - using the default topic is discouraged <code>string[]</code> <code>tag</code> The message tag indicates the purpose of the message to the applications that process it <code>string</code> <code>datahash</code> A single hash representing all data in the message. Derived from the array of data ids+hashes attached to this message <code>Bytes32</code> <code>txparent</code> The parent transaction that originally triggered this message <code>TransactionRef</code>"},{"location":"reference/types/message/#transactionref","title":"TransactionRef","text":"Field Name Description Type <code>type</code> The type of the FireFly transaction <code>FFEnum</code>: <code>id</code> The UUID of the FireFly transaction <code>UUID</code>"},{"location":"reference/types/message/#dataref","title":"DataRef","text":"Field Name Description Type <code>id</code> The UUID of the referenced data resource <code>UUID</code> <code>hash</code> The hash of the referenced data <code>Bytes32</code>"},{"location":"reference/types/namespace/","title":"Namespace","text":"<p>A namespace is a logical isolation domain for different applications, or tenants, that share the FireFly node.</p> <p>Significant evolution of the Hyperledger FireFly namespace construct, is proposed under FIR-12</p>"},{"location":"reference/types/namespace/#example","title":"Example","text":"<pre><code>{\n    \"name\": \"default\",\n    \"networkName\": \"default\",\n    \"description\": \"Default predefined namespace\",\n    \"created\": \"2022-05-16T01:23:16Z\"\n}\n</code></pre>"},{"location":"reference/types/namespace/#field-descriptions","title":"Field Descriptions","text":"Field Name Description Type <code>name</code> The local namespace name <code>string</code> <code>networkName</code> The shared namespace name within the multiparty network <code>string</code> <code>description</code> A description of the namespace <code>string</code> <code>created</code> The time the namespace was created <code>FFTime</code>"},{"location":"reference/types/nextpin/","title":"NextPin","text":"<p>Next-pins are maintained by each member of a privacy group, in order to detect if a on-chain transaction with a given \"pin\" for a message represents the next message for any member of the privacy group.</p> <p>This allows every member to maintain a global order of transactions within a <code>topic</code> in a privacy group, without leaking the same hash between the messages that are communicated in that group.</p> <p>See Group for more information on privacy groups.</p>"},{"location":"reference/types/nextpin/#example","title":"Example","text":"<pre><code>{\n    \"namespace\": \"ns1\",\n    \"context\": \"a25b65cfe49e5ed78c256e85cf07c96da938144f12fcb02fe4b5243a4631bd5e\",\n    \"identity\": \"did:firefly:org/example\",\n    \"hash\": \"00e55c63905a59782d5bc466093ead980afc4a2825eb68445bcf1312cc3d6de2\",\n    \"nonce\": 12345\n}\n</code></pre>"},{"location":"reference/types/nextpin/#field-descriptions","title":"Field Descriptions","text":"Field Name Description Type <code>namespace</code> The namespace of the next-pin <code>string</code> <code>context</code> The context the next-pin applies to - the hash of the privacy group-hash + topic. The group-hash is only known to the participants (can itself contain a salt in the group-name). This context is combined with the member and nonce to determine the final hash that is written on-chain <code>Bytes32</code> <code>identity</code> The member of the privacy group the next-pin applies to <code>string</code> <code>hash</code> The unique masked pin string <code>Bytes32</code> <code>nonce</code> The numeric index - which is monotonically increasing for each member of the privacy group <code>int64</code>"},{"location":"reference/types/operation/","title":"Operation","text":"<p>Operations are stateful external actions that FireFly triggers via plugins. They can succeed or fail. They are grouped into Transactions in order to accomplish a single logical task.</p> <p>The diagram below shows the different types of operation that are performed by each FireFly plugin type. The color coding (and numbers) map those different types of operation to the Transaction types that include those operations.</p> <p></p>"},{"location":"reference/types/operation/#operation-status","title":"Operation status","text":"<p>When initially created an operation is in <code>Initialized</code> state. Once the operation has been successfully sent to its respective plugin to be processed its status moves to <code>Pending</code> state. This indicates that the plugin is processing the operation. The operation will then move to <code>Succeeded</code> or <code>Failed</code> state depending on the outcome.</p> <p>In the event that an operation could not be submitted to the plugin for processing, for example because the plugin's microservice was temporarily unavailable, the operation will remain in <code>Initialized</code> state. Re-submitting the same FireFly API call using the same idempotency key will cause FireFly to re-submit the operation to its plugin.</p>"},{"location":"reference/types/operation/#example","title":"Example","text":"<pre><code>{\n    \"id\": \"04a8b0c4-03c2-4935-85a1-87d17cddc20a\",\n    \"namespace\": \"ns1\",\n    \"tx\": \"99543134-769b-42a8-8be4-a5f8873f969d\",\n    \"type\": \"sharedstorage_upload_batch\",\n    \"status\": \"Succeeded\",\n    \"plugin\": \"ipfs\",\n    \"input\": {\n        \"id\": \"80d89712-57f3-48fe-b085-a8cba6e0667d\"\n    },\n    \"output\": {\n        \"payloadRef\": \"QmWj3tr2aTHqnRYovhS2mQAjYneRtMWJSU4M4RdAJpJwEC\"\n    },\n    \"created\": \"2022-05-16T01:23:15Z\"\n}\n</code></pre>"},{"location":"reference/types/operation/#field-descriptions","title":"Field Descriptions","text":"Field Name Description Type <code>id</code> The UUID of the operation <code>UUID</code> <code>namespace</code> The namespace of the operation <code>string</code> <code>tx</code> The UUID of the FireFly transaction the operation is part of <code>UUID</code> <code>type</code> The type of the operation <code>FFEnum</code>:<code>\"blockchain_pin_batch\"</code><code>\"blockchain_network_action\"</code><code>\"blockchain_deploy\"</code><code>\"blockchain_invoke\"</code><code>\"sharedstorage_upload_batch\"</code><code>\"sharedstorage_upload_blob\"</code><code>\"sharedstorage_upload_value\"</code><code>\"sharedstorage_download_batch\"</code><code>\"sharedstorage_download_blob\"</code><code>\"dataexchange_send_batch\"</code><code>\"dataexchange_send_blob\"</code><code>\"token_create_pool\"</code><code>\"token_activate_pool\"</code><code>\"token_transfer\"</code><code>\"token_approval\"</code> <code>status</code> The current status of the operation <code>OpStatus</code> <code>plugin</code> The plugin responsible for performing the operation <code>string</code> <code>input</code> The input to this operation <code>JSONObject</code> <code>output</code> Any output reported back from the plugin for this operation <code>JSONObject</code> <code>error</code> Any error reported back from the plugin for this operation <code>string</code> <code>created</code> The time the operation was created <code>FFTime</code> <code>updated</code> The last update time of the operation <code>FFTime</code> <code>retry</code> If this operation was initiated as a retry to a previous operation, this field points to the UUID of the operation being retried <code>UUID</code>"},{"location":"reference/types/operationwithdetail/","title":"OperationWithDetail","text":"<p>Operation with detail is an extension to operations that allow additional information to be encapsulated with an operation. An operation can be supplemented by a connector and that information will be returned in the <code>detail</code> field.</p>"},{"location":"reference/types/operationwithdetail/#example","title":"Example","text":"<pre><code>{\n    \"id\": \"04a8b0c4-03c2-4935-85a1-87d17cddc20a\",\n    \"namespace\": \"ns1\",\n    \"tx\": \"99543134-769b-42a8-8be4-a5f8873f969d\",\n    \"type\": \"sharedstorage_upload_batch\",\n    \"status\": \"Succeeded\",\n    \"plugin\": \"ipfs\",\n    \"input\": {\n        \"id\": \"80d89712-57f3-48fe-b085-a8cba6e0667d\"\n    },\n    \"output\": {\n        \"payloadRef\": \"QmWj3tr2aTHqnRYovhS2mQAjYneRtMWJSU4M4RdAJpJwEC\"\n    },\n    \"created\": \"2022-05-16T01:23:15Z\",\n    \"detail\": {\n        \"created\": \"2023-01-27T17:04:24.26406392Z\",\n        \"firstSubmit\": \"2023-01-27T17:04:24.419913295Z\",\n        \"gas\": \"4161076\",\n        \"gasPrice\": \"0\",\n        \"history\": [\n            {\n                \"actions\": [\n                    {\n                        \"action\": \"AssignNonce\",\n                        \"count\": 1,\n                        \"lastOccurrence\": \"\",\n                        \"time\": \"\"\n                    },\n                    {\n                        \"action\": \"RetrieveGasPrice\",\n                        \"count\": 1,\n                        \"lastOccurrence\": \"2023-01-27T17:11:41.161213303Z\",\n                        \"time\": \"2023-01-27T17:11:41.161213303Z\"\n                    },\n                    {\n                        \"action\": \"Submit\",\n                        \"count\": 1,\n                        \"lastOccurrence\": \"2023-01-27T17:11:41.222374636Z\",\n                        \"time\": \"2023-01-27T17:11:41.222374636Z\"\n                    }\n                ],\n                \"subStatus\": \"Received\",\n                \"time\": \"2023-01-27T17:11:41.122965803Z\"\n            },\n            {\n                \"actions\": [\n                    {\n                        \"action\": \"ReceiveReceipt\",\n                        \"count\": 1,\n                        \"lastOccurrence\": \"2023-01-27T17:11:47.930332625Z\",\n                        \"time\": \"2023-01-27T17:11:47.930332625Z\"\n                    },\n                    {\n                        \"action\": \"Confirm\",\n                        \"count\": 1,\n                        \"lastOccurrence\": \"2023-01-27T17:12:02.660275549Z\",\n                        \"time\": \"2023-01-27T17:12:02.660275549Z\"\n                    }\n                ],\n                \"subStatus\": \"Tracking\",\n                \"time\": \"2023-01-27T17:11:41.222400219Z\"\n            },\n            {\n                \"actions\": [],\n                \"subStatus\": \"Confirmed\",\n                \"time\": \"2023-01-27T17:12:02.660309382Z\"\n            }\n        ],\n        \"historySummary\": [\n            {\n                \"count\": 1,\n                \"subStatus\": \"Received\"\n            },\n            {\n                \"action\": \"AssignNonce\",\n                \"count\": 1\n            },\n            {\n                \"action\": \"RetrieveGasPrice\",\n                \"count\": 1\n            },\n            {\n                \"action\": \"Submit\",\n                \"count\": 1\n            },\n            {\n                \"count\": 1,\n                \"subStatus\": \"Tracking\"\n            },\n            {\n                \"action\": \"ReceiveReceipt\",\n                \"count\": 1\n            },\n            {\n                \"action\": \"Confirm\",\n                \"count\": 1\n            },\n            {\n                \"count\": 1,\n                \"subStatus\": \"Confirmed\"\n            }\n        ],\n        \"sequenceId\": \"0185f42f-fec8-93df-aeba-387417d477e0\",\n        \"status\": \"Succeeded\",\n        \"transactionHash\": \"0xfb39178fee8e725c03647b8286e6f5cb13f982abf685479a9ee59e8e9d9e51d8\"\n    }\n}\n</code></pre>"},{"location":"reference/types/operationwithdetail/#field-descriptions","title":"Field Descriptions","text":"Field Name Description Type <code>id</code> The UUID of the operation <code>UUID</code> <code>namespace</code> The namespace of the operation <code>string</code> <code>tx</code> The UUID of the FireFly transaction the operation is part of <code>UUID</code> <code>type</code> The type of the operation <code>FFEnum</code>:<code>\"blockchain_pin_batch\"</code><code>\"blockchain_network_action\"</code><code>\"blockchain_deploy\"</code><code>\"blockchain_invoke\"</code><code>\"sharedstorage_upload_batch\"</code><code>\"sharedstorage_upload_blob\"</code><code>\"sharedstorage_upload_value\"</code><code>\"sharedstorage_download_batch\"</code><code>\"sharedstorage_download_blob\"</code><code>\"dataexchange_send_batch\"</code><code>\"dataexchange_send_blob\"</code><code>\"token_create_pool\"</code><code>\"token_activate_pool\"</code><code>\"token_transfer\"</code><code>\"token_approval\"</code> <code>status</code> The current status of the operation <code>OpStatus</code> <code>plugin</code> The plugin responsible for performing the operation <code>string</code> <code>input</code> The input to this operation <code>JSONObject</code> <code>output</code> Any output reported back from the plugin for this operation <code>JSONObject</code> <code>error</code> Any error reported back from the plugin for this operation <code>string</code> <code>created</code> The time the operation was created <code>FFTime</code> <code>updated</code> The last update time of the operation <code>FFTime</code> <code>retry</code> If this operation was initiated as a retry to a previous operation, this field points to the UUID of the operation being retried <code>UUID</code> <code>detail</code> Additional detailed information about an operation provided by the connector ``"},{"location":"reference/types/simpletypes/","title":"Simple Types","text":""},{"location":"reference/types/simpletypes/#uuid","title":"UUID","text":"<p>IDs are generated as UUID V4 globally unique identifiers</p>"},{"location":"reference/types/simpletypes/#fftime","title":"FFTime","text":"<p>Times are serialized to JSON on the API in RFC 3339 / ISO 8601 nanosecond UTC time for example <code>2022-05-05T21:19:27.454767543Z</code>.</p> <p>Note that JavaScript can parse this format happily into millisecond time with <code>Date.parse()</code>.</p> <p>Times are persisted as a nanosecond resolution timestamps in the database.</p> <p>On input, and in queries, times can be parsed from RFC3339, or unix timestamps (second, millisecond or nanosecond resolution).</p>"},{"location":"reference/types/simpletypes/#ffbigint","title":"FFBigInt","text":"<p>Large integers of up to 256bits in size are common in blockchain, and handled in FireFly.</p> <p>In JSON output payloads in FireFly, including events, they are serialized as strings (with base 10).</p> <p>On input you can provide JSON string (string with an <code>0x</code> prefix are parsed at base 16), or a JSON number.</p>"},{"location":"reference/types/simpletypes/#maximum-size-of-numbers-in-versions-of-firefly-up-to-v131","title":"Maximum size of numbers in versions of FireFly up to <code>v1.3.1</code>","text":"<p>In versions of FireFly up to and including <code>v1.3.1</code>, be careful when using large JSON numbers. The largest number that is safe to transfer using a JSON number is 2^53 - 1 and it is possible to receive errors from the transaction manager, or for precision to be silently lost when passing numeric parameters larger than that. It is recommended to pass large numbers as strings to avoid loss of precision.</p>"},{"location":"reference/types/simpletypes/#maximum-size-of-numbers-in-versions-of-firefly-v132-and-higher","title":"Maximum size of numbers in versions of FireFly <code>v1.3.2</code> and higher","text":"<p>In FireFly <code>v1.3.2</code> support was added for 256-bit precision JSON numbers. Some application frameworks automatically serialize large JSON numbers to a string which FireFly already supports, but there is no upper limit to the size of a number that can be represented in JSON. FireFly now supports much larger JSON numbers, up to 256-bit precision. For example the following input parameter to a contract constructor is now supported:</p> <pre><code>    ...\n    \"definition\": [{\n        \"inputs\": [\n            {\n                \"internalType\":\" uint256\",\n                \"name\": \"x\",\n                \"type\": \"uint256\"\n            }\n        ],\n        \"outputs\":[],\n        \"type\":\"constructor\"\n    }],\n    \"params\": [ 10000000000000000000000000 ]\n    ...\n</code></pre> <p>Some application frameworks seralize large numbers in scientific notation e.g. <code>1e+25</code>. FireFly <code>v1.3.2</code> added supported for handling scientific numbers in parameters. This removes the need to change an application that uses this number format. For example the following input parameter to a contract constructor is now supported:</p> <pre><code>    ...\n    \"definition\": [{\n        \"inputs\": [\n            {\n                \"internalType\":\" uint256\",\n                \"name\": \"x\",\n                \"type\": \"uint256\"\n            }\n        ],\n        \"outputs\":[],\n        \"type\":\"constructor\"\n    }],\n    \"params\": [ 1e+25 ]\n    ...\n</code></pre>"},{"location":"reference/types/simpletypes/#jsonany","title":"JSONAny","text":"<p>Any JSON type. An <code>object</code>, <code>array</code>, <code>string</code>, <code>number</code>, <code>boolean</code> or <code>null</code>.</p> <p>FireFly stores object data with the same field order as was provided on the input, but with any whitespace removed.</p>"},{"location":"reference/types/simpletypes/#jsonobject","title":"JSONObject","text":"<p>Any JSON Object. Must be an object, rather than an array or a simple type.</p>"},{"location":"reference/types/subscription/","title":"Subscription","text":"<p>Each Subscription tracks delivery of events to a particular application, and allows FireFly to ensure that messages are delivered reliably to that application.</p> <p></p>"},{"location":"reference/types/subscription/#creating-a-subscription","title":"Creating a subscription","text":"<p>Before you can connect to a subscription, you must create it via the REST API.</p> <p>One special case where you do not need to do this, is Ephemeral WebSocket connections (described below). For these you can just connect and immediately start receiving events.</p> <p>When creating a new subscription, you give it a <code>name</code> which is how you will refer to it when you connect.</p> <p>You are also able to specify server-side filtering that should be performed against the event stream, to limit the set of events that are sent to your application.</p> <p>All subscriptions are created within a <code>namespace</code>, and automatically filter events to only those emitted within that namespace.</p> <p>You can create multiple subscriptions for your application, to request different sets of server-side filtering for events. You can then request FireFly to deliver events for both subscriptions over the same WebSocket (if you are using the WebSocket transport). However, delivery order is not assured between two subscriptions.</p>"},{"location":"reference/types/subscription/#subscriptions-and-workload-balancing","title":"Subscriptions and workload balancing","text":"<p>You can have multiple scaled runtime instances of a single application, all running in parallel. These instances of the application all share a single subscription.</p> <p>Each event is only delivered once to the subscription, regardless of how many instances of your application connect to FireFly.</p> <p>With multiple WebSocket connections active on a single subscription, each event might be delivered to different instance of your application. This means workload is balanced across your instances. However, each event still needs to be acknowledged, so delivery processing order can still be maintained within your application database state.</p> <p>If you have multiple different applications all needing their own copy of the same event, then you need to configure a separate subscription for each application.</p>"},{"location":"reference/types/subscription/#pluggable-transports","title":"Pluggable Transports","text":"<p>Hyperledger FireFly has two built-in transports for delivery of events to applications - WebSockets and Webhooks.</p> <p>The event interface is fully pluggable, so you can extend connectivity over an external event bus - such as NATS, Apache Kafka, Rabbit MQ, Redis etc.</p>"},{"location":"reference/types/subscription/#websockets","title":"WebSockets","text":"<p>If your application has a back-end server runtime, then WebSockets are the most popular option for listening to events. WebSockets are well supported by all popular application development frameworks, and are very firewall friendly for connecting applications into your FireFly server.</p> <p>Check out the @hyperledger/firefly-sdk SDK for Node.js applications, and the hyperledger/firefly-common module for Golang applications. These both contain reliable WebSocket clients for your event listeners.</p> <p>A Java SDK is a roadmap item for the community.</p>"},{"location":"reference/types/subscription/#websocket-protocol","title":"WebSocket protocol","text":"<p>FireFly has a simple protocol on top of WebSockets:</p> <ol> <li>Each time you connect/reconnect you need to tell FireFly to start    sending you events on a particular subscription. You can do this in two    ways (described in detail below):</li> <li>Send a WSStart JSON payload</li> <li>Include a <code>namespace</code> and <code>name</code> query parameter in the URL when you       connect, along with query params for other fields of WSStart</li> <li>One you have started your subscription, each event flows from    the server, to your application as a JSON Event payload</li> <li>For each event you receive, you need to send a WSAck payload.</li> <li>Unless you specified <code>autoack</code> in step (1)</li> </ol> <p>The SDK libraries for FireFly help you ensure you send the <code>start</code> payload each time your WebSocket reconnects.</p>"},{"location":"reference/types/subscription/#using-start-and-ack-explicitly","title":"Using <code>start</code> and <code>ack</code> explicitly","text":"<p>Here's an example websocat command showing an explicit <code>start</code> and <code>ack</code>.</p> <pre><code>$ websocat ws://localhost:5000/ws\n{\"type\":\"start\",\"namespace\":\"default\",\"name\":\"docexample\"}\n# ... for each event that arrives here, you send an ack ...\n{\"type\":\"ack\",\"id\":\"70ed4411-57cf-4ba1-bedb-fe3b4b5fd6b6\"}\n</code></pre> <p>When creating your subscription, you can set <code>readahead</code> in order to ask FireFly to stream a number of messages to your application, ahead of receiving the acknowledgements.</p> <p><code>readahead</code> can be a powerful tool to increase performance, but does require your application to ensure it processes events in the correct order and sends exactly one <code>ack</code> for each event.</p>"},{"location":"reference/types/subscription/#auto-starting-via-url-query-and-autoack","title":"Auto-starting via URL query and <code>autoack</code>","text":"<p>Here's an example websocat where we use URL query parameters to avoid the need to send a <code>start</code> JSON payload.</p> <p>We also use <code>autoack</code> so that events just keep flowing from the server.</p> <pre><code>$ websocat \"ws://localhost:5000/ws?namespace=default&amp;name=docexample&amp;autoack\"\n# ... events just keep arriving here, as the server-side auto-acknowledges\n#     the events as it delivers them to you.\n</code></pre> <p>Note using <code>autoack</code> means you can miss events in the case of a disconnection, so should not be used for production applications that require at-least-once delivery.</p>"},{"location":"reference/types/subscription/#ephemeral-websocket-subscriptions","title":"Ephemeral WebSocket subscriptions","text":"<p>FireFly WebSockets provide a special option to create a subscription dynamically, that only lasts for as long as you are connected to the server.</p> <p>We call these <code>ephemeral</code> subscriptions.</p> <p>Here's an example websocat command showing an an ephemeral subscription - notice we don't specify a <code>name</code> for the subscription, and there is no need to have already created the subscription beforehand.</p> <p>Here we also include an extra query parameter to set a server-side filter, to only include message events.</p> <pre><code>$ websocat \"ws://localhost:5000/ws?namespace=default&amp;ephemeral&amp;autoack&amp;filter.events=message_.*\"\n{\"type\":\"start\",\"namespace\":\"default\",\"name\":\"docexample\"}\n# ... for each event that arrives here, you send an ack ...\n{\"type\":\"ack\",\"id\":\"70ed4411-57cf-4ba1-bedb-fe3b4b5fd6b6\"}\n</code></pre> <p>Ephemeral subscriptions are very convenient for experimentation, debugging and monitoring. However, they do not give reliable delivery because you only receive events that occur while you are connected. If you disconnect and reconnect, you will miss all events that happened while your application was not listening.</p>"},{"location":"reference/types/subscription/#webhooks","title":"Webhooks","text":"<p>The Webhook transport allows FireFly to make HTTP calls against your application's API when events matching your subscription are emitted.</p> <p>This means the direction of network connection is from the FireFly server, to the application (the reverse of WebSockets). Conversely it means you don't need to add any connection management code to your application - just expose and API that FireFly can call to process the events.</p> <p>Webhooks are great for serverless functions (AWS Lambda etc.), integrations with SaaS applications, and calling existing APIs.</p> <p>The FireFly configuration options for a Webhook subscription are very flexible, allowing you to customize your HTTP requests as follows:</p> <ul> <li>Set the HTTP request details:</li> <li>Method, URL, query, headers and input body</li> <li>Wait for a invocation of the back-end service, before acknowledging</li> <li>To retry requests to your Webhook on a non-<code>2xx</code> HTTP status code     or other error, you should enable and configure     options.retry</li> <li>The event is acknowledged once the request (with any retries), is     completed - regardless of whether the outcome was a success or failure.</li> <li>Use <code>fastack</code> to acknowledge against FireFly immediately and make multiple   parallel calls to the HTTP API in a fire-and-forget fashion.</li> <li>Set the HTTP request details dynamically from <code>message_confirmed</code> events:</li> <li>Map data out of the first <code>data</code> element in message events</li> <li>Requires <code>withData</code> to be set on the subscription, in addition to the     <code>input.*</code> configuration options</li> <li>Can automatically generate a \"reply\" message for <code>message_confirmed</code> events:</li> <li>Maps the response body of the HTTP call to data in the reply message</li> <li>Sets the <code>cid</code> and <code>topic</code> in the reply message to match the request</li> <li>Sets a <code>tag</code> in the reply message, per the configuration, or dynamically     based on a field in the input request data.</li> </ul>"},{"location":"reference/types/subscription/#batching-events","title":"Batching events","text":"<p>Webhooks have the ability to batch events into a single HTTP request instead of sending an event per HTTP request. The interface will be a JSON array of events instead of a top level JSON object with a single event. The size of the batch will be set by the <code>readAhead</code> limit and an optional timeout can be specified to send the events when the batch hasn't filled.</p> <p>To enable this set the following configuration under SubscriptionOptions</p> <p><code>batch</code> | Events are delivered in batches in an ordered array. The batch size is capped to the readAhead limit. The event payload is always an array even if there is a single event in the batch. Commonly used with Webhooks to allow events to be delivered and acknowledged in batches. | <code>bool</code> |</p> <p><code>batchTimeout</code> | When batching is enabled, the optional timeout to send events even when the batch hasn't filled. Defaults to 2 seconds | <code>string</code></p> <p>NOTE: When batch is enabled, <code>withData</code> cannot be used as these may alter the HTTP request based on a single event and in batching it does not make sense for now.</p>"},{"location":"reference/types/subscription/#example","title":"Example","text":"<pre><code>{\n    \"id\": \"c38d69fd-442e-4d6f-b5a4-bab1411c7fe8\",\n    \"namespace\": \"ns1\",\n    \"name\": \"app1\",\n    \"transport\": \"websockets\",\n    \"filter\": {\n        \"events\": \"^(message_.*|token_.*)$\",\n        \"message\": {\n            \"tag\": \"^(red|blue)$\"\n        },\n        \"transaction\": {},\n        \"blockchainevent\": {}\n    },\n    \"options\": {\n        \"firstEvent\": \"newest\",\n        \"readAhead\": 50\n    },\n    \"created\": \"2022-05-16T01:23:15Z\",\n    \"updated\": null\n}\n</code></pre>"},{"location":"reference/types/subscription/#field-descriptions","title":"Field Descriptions","text":"Field Name Description Type <code>id</code> The UUID of the subscription <code>UUID</code> <code>namespace</code> The namespace of the subscription. A subscription will only receive events generated in the namespace of the subscription <code>string</code> <code>name</code> The name of the subscription. The application specifies this name when it connects, in order to attach to the subscription and receive events that arrived while it was disconnected. If multiple apps connect to the same subscription, events are workload balanced across the connected application instances <code>string</code> <code>transport</code> The transport plugin responsible for event delivery (WebSockets, Webhooks, JMS, NATS etc.) <code>string</code> <code>filter</code> Server-side filter to apply to events <code>SubscriptionFilter</code> <code>options</code> Subscription options <code>SubscriptionOptions</code> <code>ephemeral</code> Ephemeral subscriptions only exist as long as the application is connected, and as such will miss events that occur while the application is disconnected, and cannot be created administratively. You can create one over over a connected WebSocket connection <code>bool</code> <code>created</code> Creation time of the subscription <code>FFTime</code> <code>updated</code> Last time the subscription was updated <code>FFTime</code>"},{"location":"reference/types/subscription/#subscriptionfilter","title":"SubscriptionFilter","text":"Field Name Description Type <code>events</code> Regular expression to apply to the event type, to subscribe to a subset of event types <code>string</code> <code>message</code> Filters specific to message events. If an event is not a message event, these filters are ignored <code>MessageFilter</code> <code>transaction</code> Filters specific to events with a transaction. If an event is not associated with a transaction, this filter is ignored <code>TransactionFilter</code> <code>blockchainevent</code> Filters specific to blockchain events. If an event is not a blockchain event, these filters are ignored <code>BlockchainEventFilter</code> <code>topic</code> Regular expression to apply to the topic of the event, to subscribe to a subset of topics. Note for messages sent with multiple topics, a separate event is emitted for each topic <code>string</code> <code>topics</code> Deprecated: Please use 'topic' instead <code>string</code> <code>tag</code> Deprecated: Please use 'message.tag' instead <code>string</code> <code>group</code> Deprecated: Please use 'message.group' instead <code>string</code> <code>author</code> Deprecated: Please use 'message.author' instead <code>string</code>"},{"location":"reference/types/subscription/#messagefilter","title":"MessageFilter","text":"Field Name Description Type <code>tag</code> Regular expression to apply to the message 'header.tag' field <code>string</code> <code>group</code> Regular expression to apply to the message 'header.group' field <code>string</code> <code>author</code> Regular expression to apply to the message 'header.author' field <code>string</code>"},{"location":"reference/types/subscription/#transactionfilter","title":"TransactionFilter","text":"Field Name Description Type <code>type</code> Regular expression to apply to the transaction 'type' field <code>string</code>"},{"location":"reference/types/subscription/#blockchaineventfilter","title":"BlockchainEventFilter","text":"Field Name Description Type <code>name</code> Regular expression to apply to the blockchain event 'name' field, which is the name of the event in the underlying blockchain smart contract <code>string</code> <code>listener</code> Regular expression to apply to the blockchain event 'listener' field, which is the UUID of the event listener. So you can restrict your subscription to certain blockchain listeners. Alternatively to avoid your application need to know listener UUIDs you can set the 'topic' field of blockchain event listeners, and use a topic filter on your subscriptions <code>string</code>"},{"location":"reference/types/subscription/#subscriptionoptions","title":"SubscriptionOptions","text":"Field Name Description Type <code>firstEvent</code> Whether your application would like to receive events from the 'oldest' event emitted by your FireFly node (from the beginning of time), or the 'newest' event (from now), or a specific event sequence. Default is 'newest' <code>SubOptsFirstEvent</code> <code>readAhead</code> The number of events to stream ahead to your application, while waiting for confirmation of consumption of those events. At least once delivery semantics are used in FireFly, so if your application crashes/reconnects this is the maximum number of events you would expect to be redelivered after it restarts <code>uint16</code> <code>withData</code> Whether message events delivered over the subscription, should be packaged with the full data of those messages in-line as part of the event JSON payload. Or if the application should make separate REST calls to download that data. May not be supported on some transports. <code>bool</code> <code>batch</code> Events are delivered in batches in an ordered array. The batch size is capped to the readAhead limit. The event payload is always an array even if there is a single event in the batch, allowing client-side optimizations when processing the events in a group. Available for both Webhooks and WebSockets. <code>bool</code> <code>batchTimeout</code> When batching is enabled, the optional timeout to send events even when the batch hasn't filled. <code>string</code> <code>fastack</code> Webhooks only: When true the event will be acknowledged before the webhook is invoked, allowing parallel invocations <code>bool</code> <code>url</code> Webhooks only: HTTP url to invoke. Can be relative if a base URL is set in the webhook plugin config <code>string</code> <code>method</code> Webhooks only: HTTP method to invoke. Default=POST <code>string</code> <code>json</code> Webhooks only: Whether to assume the response body is JSON, regardless of the returned Content-Type <code>bool</code> <code>reply</code> Webhooks only: Whether to automatically send a reply event, using the body returned by the webhook <code>bool</code> <code>replytag</code> Webhooks only: The tag to set on the reply message <code>string</code> <code>replytx</code> Webhooks only: The transaction type to set on the reply message <code>string</code> <code>headers</code> Webhooks only: Static headers to set on the webhook request `` <code>query</code> Webhooks only: Static query params to set on the webhook request `` <code>tlsConfigName</code> The name of an existing TLS configuration associated to the namespace to use <code>string</code> <code>input</code> Webhooks only: A set of options to extract data from the first JSON input data in the incoming message. Only applies if withData=true <code>WebhookInputOptions</code> <code>retry</code> Webhooks only: a set of options for retrying the webhook call <code>WebhookRetryOptions</code> <code>httpOptions</code> Webhooks only: a set of options for HTTP <code>WebhookHTTPOptions</code>"},{"location":"reference/types/subscription/#webhookinputoptions","title":"WebhookInputOptions","text":"Field Name Description Type <code>query</code> A top-level property of the first data input, to use for query parameters <code>string</code> <code>headers</code> A top-level property of the first data input, to use for headers <code>string</code> <code>body</code> A top-level property of the first data input, to use for the request body. Default is the whole first body <code>string</code> <code>path</code> A top-level property of the first data input, to use for a path to append with escaping to the webhook path <code>string</code> <code>replytx</code> A top-level property of the first data input, to use to dynamically set whether to pin the response (so the requester can choose) <code>string</code>"},{"location":"reference/types/subscription/#webhookretryoptions","title":"WebhookRetryOptions","text":"Field Name Description Type <code>enabled</code> Enables retry on HTTP calls, defaults to false <code>bool</code> <code>count</code> Number of times to retry the webhook call in case of failure <code>int</code> <code>initialDelay</code> Initial delay between retries when we retry the webhook call <code>string</code> <code>maxDelay</code> Max delay between retries when we retry the webhookcall <code>string</code>"},{"location":"reference/types/subscription/#webhookhttpoptions","title":"WebhookHTTPOptions","text":"Field Name Description Type <code>proxyURL</code> HTTP proxy URL to use for outbound requests to the webhook <code>string</code> <code>tlsHandshakeTimeout</code> The max duration to hold a TLS handshake alive <code>string</code> <code>requestTimeout</code> The max duration to hold a TLS handshake alive <code>string</code> <code>maxIdleConns</code> The max number of idle connections to hold pooled <code>int</code> <code>idleTimeout</code> The max duration to hold a HTTP keepalive connection between calls <code>string</code> <code>connectionTimeout</code> The maximum amount of time that a connection is allowed to remain with no data transmitted. <code>string</code> <code>expectContinueTimeout</code> See ExpectContinueTimeout in the Go docs <code>string</code>"},{"location":"reference/types/tokenapproval/","title":"TokenApproval","text":"<p>A token approval is a record that an address other than the owner of a token balance, has been granted authority to transfer tokens on the owners behalf.</p> <p>The approved \"operator\" (or \"spender\") account might be a smart contract, or another individual.</p> <p>FireFly provides APIs for initiating and tracking approvals, which token connectors integrate with the implementation of the underlying token.</p> <p>The off-chain index maintained in FireFly for allowance allows you to quickly find the most recent allowance event associated with a pair of keys, using the <code>subject</code> field, combined with the <code>active</code> field. When a new Token Approval event is delivered to FireFly Core by the Token Connector, any previous approval for the same subject is marked <code>\"active\": false</code>, and the new approval is marked with <code>\"active\": true</code></p> <p>The token connector is responsible for the format of the <code>subject</code> field to reflect the owner / operator (spender) relationship.</p>"},{"location":"reference/types/tokenapproval/#example","title":"Example","text":"<pre><code>{\n    \"localId\": \"1cd3e2e2-dd6a-441d-94c5-02439de9897b\",\n    \"pool\": \"1244ecbe-5862-41c3-99ec-4666a18b9dd5\",\n    \"connector\": \"erc20_erc721\",\n    \"key\": \"0x55860105d6a675dbe6e4d83f67b834377ba677ad\",\n    \"operator\": \"0x30017fd084715e41aa6536ab777a8f3a2b11a5a1\",\n    \"approved\": true,\n    \"info\": {\n        \"owner\": \"0x55860105d6a675dbe6e4d83f67b834377ba677ad\",\n        \"spender\": \"0x30017fd084715e41aa6536ab777a8f3a2b11a5a1\",\n        \"value\": \"115792089237316195423570985008687907853269984665640564039457584007913129639935\"\n    },\n    \"namespace\": \"ns1\",\n    \"protocolId\": \"000000000032/000000/000000\",\n    \"subject\": \"0x55860105d6a675dbe6e4d83f67b834377ba677ad:0x30017fd084715e41aa6536ab777a8f3a2b11a5a1\",\n    \"active\": true,\n    \"created\": \"2022-05-16T01:23:15Z\",\n    \"tx\": {\n        \"type\": \"token_approval\",\n        \"id\": \"4b6e086d-0e31-482d-9683-cd18b2045031\"\n    }\n}\n</code></pre>"},{"location":"reference/types/tokenapproval/#field-descriptions","title":"Field Descriptions","text":"Field Name Description Type <code>localId</code> The UUID of this token approval, in the local FireFly node <code>UUID</code> <code>pool</code> The UUID the token pool this approval applies to <code>UUID</code> <code>connector</code> The name of the token connector, as specified in the FireFly core configuration file. Required on input when there are more than one token connectors configured <code>string</code> <code>key</code> The blockchain signing key for the approval request. On input defaults to the first signing key of the organization that operates the node <code>string</code> <code>operator</code> The blockchain identity that is granted the approval <code>string</code> <code>approved</code> Whether this record grants permission for an operator to perform actions on the token balance (true), or revokes permission (false) <code>bool</code> <code>info</code> Token connector specific information about the approval operation, such as whether it applied to a limited balance of a fungible token. See your chosen token connector documentation for details <code>JSONObject</code> <code>namespace</code> The namespace for the approval, which must match the namespace of the token pool <code>string</code> <code>protocolId</code> An alphanumerically sortable string that represents this event uniquely with respect to the blockchain <code>string</code> <code>subject</code> A string identifying the parties and entities in the scope of this approval, as provided by the token connector <code>string</code> <code>active</code> Indicates if this approval is currently active (only one approval can be active per subject) <code>bool</code> <code>message</code> The UUID of a message that has been correlated with this approval using the data field of the approval in a compatible token connector <code>UUID</code> <code>messageHash</code> The hash of a message that has been correlated with this approval using the data field of the approval in a compatible token connector <code>Bytes32</code> <code>created</code> The creation time of the token approval <code>FFTime</code> <code>tx</code> If submitted via FireFly, this will reference the UUID of the FireFly transaction (if the token connector in use supports attaching data) <code>TransactionRef</code> <code>blockchainEvent</code> The UUID of the blockchain event <code>UUID</code> <code>config</code> Input only field, with token connector specific configuration of the approval.  See your chosen token connector documentation for details <code>JSONObject</code>"},{"location":"reference/types/tokenapproval/#transactionref","title":"TransactionRef","text":"Field Name Description Type <code>type</code> The type of the FireFly transaction <code>FFEnum</code>: <code>id</code> The UUID of the FireFly transaction <code>UUID</code>"},{"location":"reference/types/tokenpool/","title":"TokenPool","text":"<p>Token pools are a FireFly construct for describing a set of tokens.</p> <p>The total supply of a particular fungible token, or a group of related non-fungible tokens.</p> <p>The exact definition of a token pool is dependent on the token connector implementation.</p> <p>Check the documentation for your chosen connector implementation to see the detailed options for configuring a new Token Pool.</p> <p>Note that it is very common to use a Token Pool to teach Hyperledger FireFly about an existing token, so that you can start interacting with a token that already exists.</p>"},{"location":"reference/types/tokenpool/#example-token-pool-types","title":"Example token pool types","text":"<p>Some examples of how the generic concept of a Token Pool maps to various well-defined Ethereum standards:</p> <ul> <li>ERC-1155: a single contract instance can efficiently allocate   many isolated pools of fungible or non-fungible tokens</li> <li>ERC-20 / ERC-777:   each contract instance represents a single fungible pool of value, e.g. \"a coin\"</li> <li>ERC-721: each contract instance represents a single pool of NFTs,   each with unique identities within the pool</li> <li>ERC-1400 / ERC-1410:   partially supported in the same manner as ERC-20/ERC-777, but would require new features for working with partitions</li> </ul> <p>These are provided as examples only - a custom token connector could be backed by any token technology (Ethereum or otherwise) as long as it can support the basic operations described here (create pool, mint, burn, transfer). Other FireFly repos include a sample implementation of a token connector for ERC-20 and ERC-721 as well as ERC-1155.</p>"},{"location":"reference/types/tokenpool/#example","title":"Example","text":"<pre><code>{\n    \"id\": \"90ebefdf-4230-48a5-9d07-c59751545859\",\n    \"type\": \"fungible\",\n    \"namespace\": \"ns1\",\n    \"name\": \"my_token\",\n    \"standard\": \"ERC-20\",\n    \"locator\": \"address=0x056df1c53c3c00b0e13d37543f46930b42f71db0\\u0026schema=ERC20WithData\\u0026type=fungible\",\n    \"decimals\": 18,\n    \"connector\": \"erc20_erc721\",\n    \"message\": \"43923040-b1e5-4164-aa20-47636c7177ee\",\n    \"active\": true,\n    \"created\": \"2022-05-16T01:23:15Z\",\n    \"info\": {\n        \"address\": \"0x056df1c53c3c00b0e13d37543f46930b42f71db0\",\n        \"name\": \"pool8197\",\n        \"schema\": \"ERC20WithData\"\n    },\n    \"tx\": {\n        \"type\": \"token_pool\",\n        \"id\": \"a23ffc87-81a2-4cbc-97d6-f53d320c36cd\"\n    },\n    \"published\": false\n}\n</code></pre>"},{"location":"reference/types/tokenpool/#field-descriptions","title":"Field Descriptions","text":"Field Name Description Type <code>id</code> The UUID of the token pool <code>UUID</code> <code>type</code> The type of token the pool contains, such as fungible/non-fungible <code>FFEnum</code>:<code>\"fungible\"</code><code>\"nonfungible\"</code> <code>namespace</code> The namespace for the token pool <code>string</code> <code>name</code> The name of the token pool. Note the name is not validated against the description of the token on the blockchain <code>string</code> <code>networkName</code> The published name of the token pool within the multiparty network <code>string</code> <code>standard</code> The ERC standard the token pool conforms to, as reported by the token connector <code>string</code> <code>locator</code> A unique identifier for the pool, as provided by the token connector <code>string</code> <code>key</code> The signing key used to create the token pool. On input for token connectors that support on-chain deployment of new tokens (vs. only index existing ones) this determines the signing key used to create the token on-chain <code>string</code> <code>symbol</code> The token symbol. If supplied on input for an existing on-chain token, this must match the on-chain information <code>string</code> <code>decimals</code> Number of decimal places that this token has <code>int</code> <code>connector</code> The name of the token connector, as specified in the FireFly core configuration file that is responsible for the token pool. Required on input when multiple token connectors are configured <code>string</code> <code>message</code> The UUID of the broadcast message used to inform the network about this pool <code>UUID</code> <code>active</code> Indicates whether the pool has been successfully activated with the token connector <code>bool</code> <code>created</code> The creation time of the pool <code>FFTime</code> <code>config</code> Input only field, with token connector specific configuration of the pool, such as an existing Ethereum address and block number to used to index the pool. See your chosen token connector documentation for details <code>JSONObject</code> <code>info</code> Token connector specific information about the pool. See your chosen token connector documentation for details <code>JSONObject</code> <code>tx</code> Reference to the FireFly transaction used to create and broadcast this pool to the network <code>TransactionRef</code> <code>interface</code> A reference to an existing FFI, containing pre-registered type information for the token contract <code>FFIReference</code> <code>interfaceFormat</code> The interface encoding format supported by the connector for this token pool <code>FFEnum</code>:<code>\"abi\"</code><code>\"ffi\"</code> <code>methods</code> The method definitions resolved by the token connector to be used by each token operation <code>JSONAny</code> <code>published</code> Indicates if the token pool is published to other members of the multiparty network <code>bool</code>"},{"location":"reference/types/tokenpool/#transactionref","title":"TransactionRef","text":"Field Name Description Type <code>type</code> The type of the FireFly transaction <code>FFEnum</code>: <code>id</code> The UUID of the FireFly transaction <code>UUID</code>"},{"location":"reference/types/tokenpool/#ffireference","title":"FFIReference","text":"Field Name Description Type <code>id</code> The UUID of the FireFly interface <code>UUID</code> <code>name</code> The name of the FireFly interface <code>string</code> <code>version</code> The version of the FireFly interface <code>string</code>"},{"location":"reference/types/tokentransfer/","title":"TokenTransfer","text":"<p>A Token Transfer is created for each transfer of value that happens under a token pool.</p> <p>The transfers form an off-chain audit history (an \"index\") of the transactions that have been performed on the blockchain.</p> <p>This historical information cannot be queried directly from the blockchain for most token implementations, because it is inefficient to use the blockchain to store complex data structures like this. So the blockchain simply emits events when state changes, and if you want to be able to query this historical information you need to track it in your own off-chain database.</p> <p>Hyperledger FireFly maintains this index automatically for all Token Pools that are configured.</p>"},{"location":"reference/types/tokentransfer/#firefly-initiated-vs-non-firefly-initiated-transfers","title":"FireFly initiated vs. non-FireFly initiated transfers","text":"<p>There is no requirement at all to use FireFly to initiate transfers in Token Pools that Hyperledger FireFly is aware of. FireFly will listen to and update its audit history and balances for all transfers, regardless of whether they were initiated using a FireFly Supernode or not.</p> <p>So you could for example use Metamask to initiate a transfer directly against an ERC-20/ERC-721 contract directly on your blockchain, and you will see it appear as a transfer. Or initiate a transfer on-chain via another Smart Contract, such as a Hashed Timelock Contract (HTLC) releasing funds held in digital escrow.</p>"},{"location":"reference/types/tokentransfer/#message-coordinated-transfers","title":"Message coordinated transfers","text":"<p>One special feature enabled when using FireFly to initiate transfers, is to coordinate an off-chain data transfer (private or broadcast) with the on-chain transfer of value.  This is a powerful tool to allow transfers to have rich metadata associated that is too sensitive (or too large) to include on the blockchain itself.</p> <p>These transfers have a <code>message</code> associated with them, and require a compatible Token Connector and on-chain Smart Contract that allows a <code>data</code> payload to be included as part of the transfer, and to be emitted as part of the transfer event.</p> <p>Examples of how to do this are included in the ERC-20, ERC-721 and ERC-1155 Token Connector sample smart contracts.</p>"},{"location":"reference/types/tokentransfer/#transfer-types","title":"Transfer types","text":"<p>There are three primary types of transfer:</p> <ol> <li>Mint - new tokens come into existence, increasing the total supply of tokens    within the pool. The <code>from</code> address will be unset for these transfer types.</li> <li>Burn - existing tokens are taken out of circulation. The <code>to</code> address will be    unset for these transfer types.</li> <li>Transfer - tokens move from ownership by one account, to another account.    The <code>from</code> and <code>to</code> addresses are both set for these type of transfers.</li> </ol> <p>Note that the <code>key</code> that signed the Transfer transaction might be different to the <code>from</code> account that is the owner of the tokens before the transfer.</p> <p>The Approval resource is used to track which signing accounts (other than the owner) have approval to transfer tokens on the owner's behalf.</p>"},{"location":"reference/types/tokentransfer/#example","title":"Example","text":"<pre><code>{\n    \"type\": \"transfer\",\n    \"pool\": \"1244ecbe-5862-41c3-99ec-4666a18b9dd5\",\n    \"uri\": \"firefly://token/1\",\n    \"connector\": \"erc20_erc721\",\n    \"namespace\": \"ns1\",\n    \"key\": \"0x55860105D6A675dBE6e4d83F67b834377Ba677AD\",\n    \"from\": \"0x55860105D6A675dBE6e4d83F67b834377Ba677AD\",\n    \"to\": \"0x55860105D6A675dBE6e4d83F67b834377Ba677AD\",\n    \"amount\": \"1000000000000000000\",\n    \"protocolId\": \"000000000041/000000/000000\",\n    \"message\": \"780b9b90-e3b0-4510-afac-b4b1f2940b36\",\n    \"messageHash\": \"780204e634364c42779920eddc8d9fecccb33e3607eeac9f53abd1b31184ae4e\",\n    \"created\": \"2022-05-16T01:23:15Z\",\n    \"tx\": {\n        \"type\": \"token_transfer\",\n        \"id\": \"62767ca8-99f9-439c-9deb-d80c6672c158\"\n    },\n    \"blockchainEvent\": \"b57fcaa2-156e-4c3f-9b0b-ddec9ee25933\"\n}\n</code></pre>"},{"location":"reference/types/tokentransfer/#field-descriptions","title":"Field Descriptions","text":"Field Name Description Type <code>type</code> The type of transfer such as mint/burn/transfer <code>FFEnum</code>:<code>\"mint\"</code><code>\"burn\"</code><code>\"transfer\"</code> <code>localId</code> The UUID of this token transfer, in the local FireFly node <code>UUID</code> <code>pool</code> The UUID the token pool this transfer applies to <code>UUID</code> <code>tokenIndex</code> The index of the token within the pool that this transfer applies to <code>string</code> <code>uri</code> The URI of the token this transfer applies to <code>string</code> <code>connector</code> The name of the token connector, as specified in the FireFly core configuration file. Required on input when there are more than one token connectors configured <code>string</code> <code>namespace</code> The namespace for the transfer, which must match the namespace of the token pool <code>string</code> <code>key</code> The blockchain signing key for the transfer. On input defaults to the first signing key of the organization that operates the node <code>string</code> <code>from</code> The source account for the transfer. On input defaults to the value of 'key' <code>string</code> <code>to</code> The target account for the transfer. On input defaults to the value of 'key' <code>string</code> <code>amount</code> The amount for the transfer. For non-fungible tokens will always be 1. For fungible tokens, the number of decimals for the token pool should be considered when inputting the amount. For example, with 18 decimals a fractional balance of 10.234 will be specified as 10,234,000,000,000,000,000 <code>FFBigInt</code> <code>protocolId</code> An alphanumerically sortable string that represents this event uniquely with respect to the blockchain <code>string</code> <code>message</code> The UUID of a message that has been correlated with this transfer using the data field of the transfer in a compatible token connector <code>UUID</code> <code>messageHash</code> The hash of a message that has been correlated with this transfer using the data field of the transfer in a compatible token connector <code>Bytes32</code> <code>created</code> The creation time of the transfer <code>FFTime</code> <code>tx</code> If submitted via FireFly, this will reference the UUID of the FireFly transaction (if the token connector in use supports attaching data) <code>TransactionRef</code> <code>blockchainEvent</code> The UUID of the blockchain event <code>UUID</code> <code>config</code> Input only field, with token connector specific configuration of the transfer. See your chosen token connector documentation for details <code>JSONObject</code>"},{"location":"reference/types/tokentransfer/#transactionref","title":"TransactionRef","text":"Field Name Description Type <code>type</code> The type of the FireFly transaction <code>FFEnum</code>: <code>id</code> The UUID of the FireFly transaction <code>UUID</code>"},{"location":"reference/types/transaction/","title":"Transaction","text":"<p>FireFly Transactions are a grouping construct for a number of Operations and Events that need to complete or fail as unit.</p> <p>FireFly Transactions are not themselves Blockchain transactions, but in many cases there is exactly one Blockchain transaction associated with each FireFly transaction. Exceptions include <code>unpinned</code> transactions, where there is no blockchain transaction at all.</p> <p>The Blockchain native transaction ID is stored in the FireFly transaction object when it is known. However, the FireFly transaction starts before a Blockchain transaction exists - because reliably submitting the blockchain transaction is one of the operations that is performed inside of the FireFly transaction.</p> <p>The below screenshot from the FireFly Explorer nicely illustrates how multiple operations and events are associated with a FireFly transaction. In this example, the transaction tracking is pinning of a batch of messages stored in IPFS to the blockchain.</p> <p>So there is a <code>Blockchain ID</code> for the transaction - as there is just one Blockchain transaction regardless of how many messages in the batch. There are operations for the submission of that transaction, and the upload of the data to IPFS. Then a corresponding <code>Blockchain Event Received</code> event for the detection of the event from the blockchain smart contract when the transaction was mined, and a <code>Message Confirmed</code> event for each message in the batch (in this case 1). Then here the message was a special <code>Definition</code> message that advertised a new Contract API to all members of the network - so there is a <code>Contract API Confirmed</code> event as well.</p> <p></p> <p>Each FireFly transaction has a UUID. This UUID is propagated through to all participants in a FireFly transaction. For example in a Token Transfer that is coordinated with an off-chain private Message, the transaction ID is propagated to all parties who are part of that transaction. So the same UUID can be used to find the transaction in the FireFly Explorer of any member who has access to the message. This is possible because hash-pinned off-chain data is associated with that on-chain transfer.</p> <p>However, in the case of a raw ERC-20/ERC-721 transfer (without data), or any other raw Blockchain transaction, the FireFly transaction UUID cannot be propagated - so it will be local on the node that initiated the transaction.</p>"},{"location":"reference/types/transaction/#example","title":"Example","text":"<pre><code>{\n    \"id\": \"4e7e0943-4230-4f67-89b6-181adf471edc\",\n    \"namespace\": \"ns1\",\n    \"type\": \"contract_invoke\",\n    \"created\": \"2022-05-16T01:23:15Z\",\n    \"blockchainIds\": [\n        \"0x34b0327567fefed09ac7b4429549bc609302b08a9cbd8f019a078ec44447593d\"\n    ]\n}\n</code></pre>"},{"location":"reference/types/transaction/#field-descriptions","title":"Field Descriptions","text":"Field Name Description Type <code>id</code> The UUID of the FireFly transaction <code>UUID</code> <code>namespace</code> The namespace of the FireFly transaction <code>string</code> <code>type</code> The type of the FireFly transaction <code>FFEnum</code>:<code>\"none\"</code><code>\"unpinned\"</code><code>\"batch_pin\"</code><code>\"network_action\"</code><code>\"token_pool\"</code><code>\"token_transfer\"</code><code>\"contract_deploy\"</code><code>\"contract_invoke\"</code><code>\"contract_invoke_pin\"</code><code>\"token_approval\"</code><code>\"data_publish\"</code> <code>created</code> The time the transaction was created on this node. Note the transaction is individually created with the same UUID on each participant in the FireFly transaction <code>FFTime</code> <code>idempotencyKey</code> An optional unique identifier for a transaction. Cannot be duplicated within a namespace, thus allowing idempotent submission of transactions to the API <code>IdempotencyKey</code> <code>blockchainIds</code> The blockchain transaction ID, in the format specific to the blockchain involved in the transaction. Not all FireFly transactions include a blockchain. FireFly transactions are extensible to support multiple blockchain transactions <code>string[]</code>"},{"location":"reference/types/verifier/","title":"Verifier","text":"<p>A verifier is a cryptographic verification mechanism for an identity in FireFly.</p> <p>FireFly generally defers verification of these keys to the lower layers of technologies in the stack - the blockchain (Fabric, Ethereum etc.) or Data Exchange technology.</p> <p>As such the details of the public key cryptography scheme are not represented in the FireFly verifiers. Only the string identifier of the verifier that is appropriate to the technology.</p> <ul> <li>Ethereum blockchains: The Ethereum address hex string</li> <li>Hyperledger Fabric: The fully qualified MSP Identifier string</li> <li>Data exchange: The data exchange \"Peer ID\", as determined by the DX plugin</li> </ul>"},{"location":"reference/types/verifier/#example","title":"Example","text":"<pre><code>{\n    \"hash\": \"6818c41093590b862b781082d4df5d4abda6d2a4b71d737779edf6d2375d810b\",\n    \"identity\": \"114f5857-9983-46fb-b1fc-8c8f0a20846c\",\n    \"type\": \"ethereum_address\",\n    \"value\": \"0x30017fd084715e41aa6536ab777a8f3a2b11a5a1\",\n    \"created\": \"2022-05-16T01:23:15Z\"\n}\n</code></pre>"},{"location":"reference/types/verifier/#field-descriptions","title":"Field Descriptions","text":"Field Name Description Type <code>hash</code> Hash used as a globally consistent identifier for this namespace + type + value combination on every node in the network <code>Bytes32</code> <code>identity</code> The UUID of the parent identity that has claimed this verifier <code>UUID</code> <code>namespace</code> The namespace of the verifier <code>string</code> <code>type</code> The type of the verifier <code>FFEnum</code>:<code>\"ethereum_address\"</code><code>\"tezos_address\"</code><code>\"fabric_msp_id\"</code><code>\"dx_peer_id\"</code> <code>value</code> The verifier string, such as an Ethereum address, or Fabric MSP identifier <code>string</code> <code>created</code> The time this verifier was created on this node <code>FFTime</code>"},{"location":"reference/types/wsack/","title":"WSAck","text":"<p>An <code>ack</code> must be sent on a WebSocket for each event delivered to an application.</p> <p>Unless <code>autoack</code> is set in the WSStart payload/URL parameters to cause automatic acknowledgement.</p> <p>Your application should specify the <code>id</code> of each event that it acknowledges.</p> <p>If the <code>id</code> is omitted, then FireFly will assume the oldest message delivered to the application that has not been acknowledged is the one the <code>ack</code> is associated with.</p> <p>If multiple subscriptions are started on a WebSocket, then you need to specify the subscription <code>namespace</code>+<code>name</code> as part of each <code>ack</code>.</p> <p>If you send an acknowledgement that cannot be correlated, then a WSError payload will be sent to the application.</p>"},{"location":"reference/types/wsack/#example","title":"Example","text":"<pre><code>{\n    \"type\": \"ack\",\n    \"id\": \"f78bf82b-1292-4c86-8a08-e53d855f1a64\",\n    \"subscription\": {\n        \"namespace\": \"ns1\",\n        \"name\": \"app1_subscription\"\n    }\n}\n</code></pre>"},{"location":"reference/types/wsack/#field-descriptions","title":"Field Descriptions","text":"Field Name Description Type <code>type</code> WSActionBase.type <code>FFEnum</code>:<code>\"start\"</code><code>\"ack\"</code><code>\"protocol_error\"</code><code>\"event_batch\"</code> <code>id</code> WSAck.id <code>UUID</code> <code>subscription</code> WSAck.subscription <code>SubscriptionRef</code>"},{"location":"reference/types/wsack/#subscriptionref","title":"SubscriptionRef","text":"Field Name Description Type <code>id</code> The UUID of the subscription <code>UUID</code> <code>namespace</code> The namespace of the subscription. A subscription will only receive events generated in the namespace of the subscription <code>string</code> <code>name</code> The name of the subscription. The application specifies this name when it connects, in order to attach to the subscription and receive events that arrived while it was disconnected. If multiple apps connect to the same subscription, events are workload balanced across the connected application instances <code>string</code>"},{"location":"reference/types/wserror/","title":"WSError","text":""},{"location":"reference/types/wserror/#example","title":"Example","text":"<pre><code>{\n    \"type\": \"protocol_error\",\n    \"error\": \"FF10175: Acknowledgment does not match an inflight event + subscription\"\n}\n</code></pre>"},{"location":"reference/types/wserror/#field-descriptions","title":"Field Descriptions","text":"Field Name Description Type <code>type</code> WSAck.type <code>FFEnum</code>:<code>\"start\"</code><code>\"ack\"</code><code>\"protocol_error\"</code><code>\"event_batch\"</code> <code>error</code> WSAck.error <code>string</code>"},{"location":"reference/types/wsstart/","title":"WSStart","text":"<p>The <code>start</code> payload is sent after an application connects to a WebSocket, to start delivery of events over that connection.</p> <p>The start command can refer to a subscription by name in order to reliably receive all matching events for that subscription, including those that were emitted when the application was disconnected.</p> <p>Alternatively the start command can request <code>\"ephemeral\": true</code> in order to dynamically create a new subscription that lasts only for the duration that the connection is active.</p>"},{"location":"reference/types/wsstart/#example","title":"Example","text":"<pre><code>{\n    \"type\": \"start\",\n    \"autoack\": false,\n    \"namespace\": \"ns1\",\n    \"name\": \"app1_subscription\",\n    \"ephemeral\": false,\n    \"filter\": {\n        \"message\": {},\n        \"transaction\": {},\n        \"blockchainevent\": {}\n    },\n    \"options\": {}\n}\n</code></pre>"},{"location":"reference/types/wsstart/#field-descriptions","title":"Field Descriptions","text":"Field Name Description Type <code>type</code> WSActionBase.type <code>FFEnum</code>:<code>\"start\"</code><code>\"ack\"</code><code>\"protocol_error\"</code><code>\"event_batch\"</code> <code>autoack</code> WSStart.autoack <code>bool</code> <code>namespace</code> WSStart.namespace <code>string</code> <code>name</code> WSStart.name <code>string</code> <code>ephemeral</code> WSStart.ephemeral <code>bool</code> <code>filter</code> WSStart.filter <code>SubscriptionFilter</code> <code>options</code> WSStart.options <code>SubscriptionOptions</code>"},{"location":"reference/types/wsstart/#subscriptionfilter","title":"SubscriptionFilter","text":"Field Name Description Type <code>events</code> Regular expression to apply to the event type, to subscribe to a subset of event types <code>string</code> <code>message</code> Filters specific to message events. If an event is not a message event, these filters are ignored <code>MessageFilter</code> <code>transaction</code> Filters specific to events with a transaction. If an event is not associated with a transaction, this filter is ignored <code>TransactionFilter</code> <code>blockchainevent</code> Filters specific to blockchain events. If an event is not a blockchain event, these filters are ignored <code>BlockchainEventFilter</code> <code>topic</code> Regular expression to apply to the topic of the event, to subscribe to a subset of topics. Note for messages sent with multiple topics, a separate event is emitted for each topic <code>string</code> <code>topics</code> Deprecated: Please use 'topic' instead <code>string</code> <code>tag</code> Deprecated: Please use 'message.tag' instead <code>string</code> <code>group</code> Deprecated: Please use 'message.group' instead <code>string</code> <code>author</code> Deprecated: Please use 'message.author' instead <code>string</code>"},{"location":"reference/types/wsstart/#messagefilter","title":"MessageFilter","text":"Field Name Description Type <code>tag</code> Regular expression to apply to the message 'header.tag' field <code>string</code> <code>group</code> Regular expression to apply to the message 'header.group' field <code>string</code> <code>author</code> Regular expression to apply to the message 'header.author' field <code>string</code>"},{"location":"reference/types/wsstart/#transactionfilter","title":"TransactionFilter","text":"Field Name Description Type <code>type</code> Regular expression to apply to the transaction 'type' field <code>string</code>"},{"location":"reference/types/wsstart/#blockchaineventfilter","title":"BlockchainEventFilter","text":"Field Name Description Type <code>name</code> Regular expression to apply to the blockchain event 'name' field, which is the name of the event in the underlying blockchain smart contract <code>string</code> <code>listener</code> Regular expression to apply to the blockchain event 'listener' field, which is the UUID of the event listener. So you can restrict your subscription to certain blockchain listeners. Alternatively to avoid your application need to know listener UUIDs you can set the 'topic' field of blockchain event listeners, and use a topic filter on your subscriptions <code>string</code>"},{"location":"reference/types/wsstart/#subscriptionoptions","title":"SubscriptionOptions","text":"Field Name Description Type <code>firstEvent</code> Whether your application would like to receive events from the 'oldest' event emitted by your FireFly node (from the beginning of time), or the 'newest' event (from now), or a specific event sequence. Default is 'newest' <code>SubOptsFirstEvent</code> <code>readAhead</code> The number of events to stream ahead to your application, while waiting for confirmation of consumption of those events. At least once delivery semantics are used in FireFly, so if your application crashes/reconnects this is the maximum number of events you would expect to be redelivered after it restarts <code>uint16</code> <code>withData</code> Whether message events delivered over the subscription, should be packaged with the full data of those messages in-line as part of the event JSON payload. Or if the application should make separate REST calls to download that data. May not be supported on some transports. <code>bool</code> <code>batch</code> Events are delivered in batches in an ordered array. The batch size is capped to the readAhead limit. The event payload is always an array even if there is a single event in the batch, allowing client-side optimizations when processing the events in a group. Available for both Webhooks and WebSockets. <code>bool</code> <code>batchTimeout</code> When batching is enabled, the optional timeout to send events even when the batch hasn't filled. <code>string</code> <code>fastack</code> Webhooks only: When true the event will be acknowledged before the webhook is invoked, allowing parallel invocations <code>bool</code> <code>url</code> Webhooks only: HTTP url to invoke. Can be relative if a base URL is set in the webhook plugin config <code>string</code> <code>method</code> Webhooks only: HTTP method to invoke. Default=POST <code>string</code> <code>json</code> Webhooks only: Whether to assume the response body is JSON, regardless of the returned Content-Type <code>bool</code> <code>reply</code> Webhooks only: Whether to automatically send a reply event, using the body returned by the webhook <code>bool</code> <code>replytag</code> Webhooks only: The tag to set on the reply message <code>string</code> <code>replytx</code> Webhooks only: The transaction type to set on the reply message <code>string</code> <code>headers</code> Webhooks only: Static headers to set on the webhook request `` <code>query</code> Webhooks only: Static query params to set on the webhook request `` <code>tlsConfigName</code> The name of an existing TLS configuration associated to the namespace to use <code>string</code> <code>input</code> Webhooks only: A set of options to extract data from the first JSON input data in the incoming message. Only applies if withData=true <code>WebhookInputOptions</code> <code>retry</code> Webhooks only: a set of options for retrying the webhook call <code>WebhookRetryOptions</code> <code>httpOptions</code> Webhooks only: a set of options for HTTP <code>WebhookHTTPOptions</code>"},{"location":"reference/types/wsstart/#webhookinputoptions","title":"WebhookInputOptions","text":"Field Name Description Type <code>query</code> A top-level property of the first data input, to use for query parameters <code>string</code> <code>headers</code> A top-level property of the first data input, to use for headers <code>string</code> <code>body</code> A top-level property of the first data input, to use for the request body. Default is the whole first body <code>string</code> <code>path</code> A top-level property of the first data input, to use for a path to append with escaping to the webhook path <code>string</code> <code>replytx</code> A top-level property of the first data input, to use to dynamically set whether to pin the response (so the requester can choose) <code>string</code>"},{"location":"reference/types/wsstart/#webhookretryoptions","title":"WebhookRetryOptions","text":"Field Name Description Type <code>enabled</code> Enables retry on HTTP calls, defaults to false <code>bool</code> <code>count</code> Number of times to retry the webhook call in case of failure <code>int</code> <code>initialDelay</code> Initial delay between retries when we retry the webhook call <code>string</code> <code>maxDelay</code> Max delay between retries when we retry the webhookcall <code>string</code>"},{"location":"reference/types/wsstart/#webhookhttpoptions","title":"WebhookHTTPOptions","text":"Field Name Description Type <code>proxyURL</code> HTTP proxy URL to use for outbound requests to the webhook <code>string</code> <code>tlsHandshakeTimeout</code> The max duration to hold a TLS handshake alive <code>string</code> <code>requestTimeout</code> The max duration to hold a TLS handshake alive <code>string</code> <code>maxIdleConns</code> The max number of idle connections to hold pooled <code>int</code> <code>idleTimeout</code> The max duration to hold a HTTP keepalive connection between calls <code>string</code> <code>connectionTimeout</code> The maximum amount of time that a connection is allowed to remain with no data transmitted. <code>string</code> <code>expectContinueTimeout</code> See ExpectContinueTimeout in the Go docs <code>string</code>"},{"location":"releasenotes/","title":"Release Notes","text":"<p>Full release notes</p>"},{"location":"releasenotes/#v132-sept-13-2024","title":"v1.3.2 - Sept 13, 2024","text":"<p>What's New:</p> <ul> <li>Support for JSON numbers larger than <code>2^53-1</code>     See FFBigInt </li> <li>Ability to install FireFly CLI with Brew for MacOS users     See Brew </li> <li>Miscellaneous bug fixes and minor improvements</li> <li>FireFly has been upgraded to use Go 1.22</li> </ul>"},{"location":"releasenotes/#v131-aug-5-2024","title":"v1.3.1 - Aug 5, 2024","text":"<p>What's New:</p> <ul> <li>Enable contract listeners with multiple filters     See Contract Listeners for details</li> <li>New multiparty status API at <code>/status/multiparty</code></li> </ul>"},{"location":"releasenotes/#v130-april-25-2024","title":"v1.3.0 - April 25, 2024","text":"<p>Migration guide</p> <p>What's New:</p> <ul> <li>Enhancements to FireFly Messaging capabilities, allowing off-chain data to be linked to on-chain transactions from custom smart contracts</li> <li>Sample contract implementation for custom pin contracts</li> <li>Contract interfaces, contract APIs, and token pools can now be separately defined and published</li> <li>Support for batching events when delivering over websockets</li> <li>Lots of bug fixes and miscellaneous enhancements</li> </ul>"},{"location":"releasenotes/#v120-february-6-2023","title":"v1.2.0 - February 6, 2023","text":"<p>Migration guide</p> <p>What's New:</p> <ul> <li>Enhanced support for token contracts generated by the OpenZeppelin Wizard</li> <li>Custom smart contract error types are now returned on the API</li> <li>Data objects and associated blobs can now be deleted</li> <li>Optional dynamic reload of core configuration file</li> <li>The <code>X-FireFly-Request-ID</code> HTTP header is now passed through to FireFly dependency microservices</li> <li>Custom HTTP headers can be passed through to FireFly dependency microservices</li> <li>Evmconnect is now the default blockchain connector for Ethereum based FireFly stacks</li> </ul>"},{"location":"releasenotes/#release-notes","title":"Release Notes","text":"<p>Full release notes</p>"},{"location":"releasenotes/#v110-september-12-2022","title":"v1.1.0 - September 12, 2022","text":"<p>Migration guide</p> <p>What's New:</p> <ul> <li>Gateway Mode: Connect to many chains with auto-indexing of activities</li> <li>Public EVM Chain Support: Manage public chain connections including Ethereum, Polygon, Arbitrum, Binance Smart Chain, Moonbeam, and more.</li> <li>Namespaces: Isolated environments within a FireFly runtime allowing independent configuration of plugin and infrastructure components and more</li> <li>Connector Toolkit: Quickly build custom connectors</li> <li>Pluggable API Security: Plug in your own API security</li> <li>Mass Scale Tokens: Support many parallel copies of token plugins for mass scale</li> </ul>"},{"location":"releasenotes/#v103-july-07-2022","title":"v1.0.3 - July 07, 2022","text":"<p>What's New:</p> <ul> <li>Adds support for custom URIs for non-fungible tokens and documentation updates</li> <li>Deprecate default value for \"ffdx\"</li> <li>Back port of custom URI support for non-fungible tokens</li> <li>Update token connector versions</li> <li>Back port of \"FAQ and FireFly Tutorial updates\"</li> </ul>"},{"location":"releasenotes/#v102-may-12-2022","title":"v1.0.2 - May 12, 2022","text":"<p>What's New:</p> <ul> <li>Fix invocations on custom Fabric chaincode, which were not properly reporting success/failure status back to FireFly (along with other minor bugfixes).</li> <li>De-duplicate existing token approvals in database migration</li> <li>Backport docs generation and versioning code for 1.0 stream</li> <li>Default fabconnect calls to async</li> <li>Set message header type of broadcast/private</li> </ul>"},{"location":"releasenotes/#v101-may-09-2022","title":"v1.0.1 - May 09, 2022","text":"<p>What's New:</p> <ul> <li>Fixes for token approvals - previously approvals would intermittently be missed by FireFly or recorded with incorrect details.</li> <li>New versions of ERC20/ERC721 connector will assume \"no data\" support if you create a token pool against an older version of the sample smart contracts.</li> </ul>"},{"location":"releasenotes/#v100-april-28-2022","title":"v1.0.0 - April 28, 2022","text":"<p>This release includes lots of major hardening, performance improvements, and bug fixes, as well as more complete documentation and OpenAPI specifications.</p> <p>What's New:</p> <ul> <li>Massive performance improvements across the board</li> <li>Up-to-date documentation and fully annotated OpenAPI specification</li> <li>Overhaul of UI</li> <li>Cleaner logs and error messages</li> <li>Lots of bug fixes and miscellaneous enhancements</li> </ul>"},{"location":"releasenotes/#v0140-march-22-2022","title":"v0.14.0 - March 22, 2022","text":"<p>What's New:</p> <ul> <li>Major UI updates including Activity, Blockchain, Off-Chain, Tokens, Network Map, and My Node sections</li> <li>Custom contract APIs</li> <li>Enhanced subscription filters</li> <li>Event API enrichment</li> <li>Performance updates</li> <li>Bug fixes</li> </ul>"},{"location":"releasenotes/#v0130-february-14-2022","title":"v0.13.0 - February 14, 2022","text":"<p>What's New:</p> <ul> <li>Hardening release with significant rework to core of FireFly, mostly to fix issues exposed by the performance testing.</li> <li>Support for running on ARM-based M1 processors</li> <li>Rewrite of the message batching and event aggregation logic inside FireFly, to fix numerous edge cases with lost or hung messages</li> <li>Hardening of operations and transactions to behave more consistently across all types</li> <li>Metrics reporting to Prometheus</li> <li>Continued development to support custom on-chain logic (still in preview)</li> </ul>"},{"location":"releasenotes/#v0120-february-02-2022","title":"v0.12.0 - February 02, 2022","text":"<p>What's New:</p> <ul> <li>All APIs deprecated in v0.11.0 or earlier are removed</li> <li>Preview of custom on-chain logic</li> <li>Support for new ERC20 / ERC721 connector</li> <li>Overhaul of Transaction type and new BlockchainEvent type</li> <li>Support for delivery confirmations via DX plugin</li> </ul>"},{"location":"releasenotes/#v0110-november-22-2021","title":"v0.11.0 - November 22, 2021","text":"<p>What's New:</p> <ul> <li>Significant hardening and enhanced token functionality</li> <li>Major web UI overhaul</li> <li>Optimized database operations for increased transactional throughput</li> <li>Fixed PostgreSQL database migrations</li> </ul>"},{"location":"releasenotes/1.1_migration_guide/","title":"v1.1.0 Migration Guide","text":""},{"location":"releasenotes/1.1_migration_guide/#overview","title":"Overview","text":"<p>Hyperledger FireFly v1.1.0 is a feature release that includes significant new functionality around namespaces and plugins, as detailed in FIR-12. As a result, upgrading an existing FireFly environment from any prior release may require special steps (depending on the functionality used).</p> <p>If seamless data preservation is not required, you can simply create a new network from scratch using FireFly v1.1.0.</p> <p>If you want to preserve data from an existing 1.0.x network, significant care has been taken to ensure that it is possible. Most existing environments can be upgraded with minimal extra steps. This document attempts to call out all potentially breaking changes (both common and uncommon), so that you can easily assess the impact of the upgrade and any needed preparation before proceeding.</p>"},{"location":"releasenotes/1.1_migration_guide/#before-upgrading","title":"Before Upgrading","text":"<p>These steps are all safe to do while running FireFly v1.0.x. While they do not have to be done prior to upgrading, performing them ahead of time may allow you to preemptively fix some problems and ease the migration to v1.1.0.</p>"},{"location":"releasenotes/1.1_migration_guide/#common-steps","title":"Common Steps","text":"<p>Upgrade to latest v1.0.x patch release</p> <p>Before upgrading to v1.1.0, it is strongly recommended to upgrade to the latest v1.0.x patch release (v1.0.4 as of the writing this document). Do not proceed any further in this guide until all nodes are successfully running the latest patch release version.</p> <p>Fix any deprecated config usage</p> <p>All items in FireFly's YAML config that were deprecated at any time in the v1.0.x line will be unsupported in v1.1.0. After upgrading to the latest v1.0.x patch release, you should therefore look for any deprecation warnings when starting FireFly, and ensure they are fixed before upgrading to v1.1.0. Failure to do so will cause your config file to be rejected in v1.1.0, and FireFly will fail to start.</p> <p>You can utilize the ffconfig tool to automatically check and fix deprecated config with a command such as:</p> <pre><code>ffconfig migrate -f &lt;input-file&gt; -o &lt;output-file&gt; --to 1.0.4\n</code></pre> <p>This should ensure your config file is acceptable to 1.0.x or 1.1.x.</p> <p>Note that if you are attempting to migrate a Dockerized development environment (such as one stood up by the firefly-cli), you may need to edit the config file inside the Docker. Environments created by a v1.0.x CLI do not expose the config file outside the Docker container.</p>"},{"location":"releasenotes/1.1_migration_guide/#less-common-situations","title":"Less Common Situations","text":"<p>Record all broadcast namespaces in the config file</p> Expand for migration details only if your application uses non-default namespaces.  FireFly v1.0 allowed for the dynamic creation of new namespaces by broadcasting a namespace definition to all nodes. This functionality is _removed_ in v1.1.0. If your network relies on any namespaces that were created via a broadcast, you must add those namespaces to the `namespaces.predefined` list in your YAML config prior to upgrade. If you do not, they will cease to function after upgrading to v1.1.0 (all events on those namespaces will be ignored by your node).   <p>Identify queries for organization/node identities</p> Expand for migration details only if your application queries <code>/network/organizations</code> or <code>/network/nodes</code>.  Applications that query `/network/organizations` or `/network/nodes` will temporarily receive _empty result lists_ after upgrading to v1.1.0, just until all identities have been re-registered (see steps in \"After Upgrading\"). This is because organization and node identities were broadcast on a global \"ff_system\" namespace in v1.0, but are no longer global in v1.1.0.  The simplest solution is to shut down applications until the FireFly upgrade is complete on all nodes and all identities have been re-broadcast.  If this poses a problem and you require zero downtime from these APIs, you can proactively mitigate with the following steps in your application code:  - Applications that query the `/network/organizations` may be altered to _also_ query `/namespaces/ff_system/network/organizations` and combine the results (but should disregard the second query if it fails). - Applications that query the `/network/nodes` may be altered to _also_ query `/namespaces/ff_system/network/nodes` and combine the results (but should disregard the second query if it fails).  Further details on the changes to `/network` APIs are provided in the next section.   <p>Identify usage of changed APIs</p> Expand for migration details on all changes to <code>/namespaces</code>, <code>/status</code>, and <code>/network</code> APIs.  The primary API change in this version is that the \"global\" paths beginning with `/network` and `/status` have been relocated under the `/namespaces/{ns}` prefix, as this data is now specific to a namespace instead of being global. At the same time, the API server has been enhanced so that omitting a namespace from an API path will _query the default namespace_ instead. That is, querying `/messages` is now the same as querying `/namespaces/default/messages` (assuming your default namespace is named \"default\"). This has the effect that most of the moved APIs will continue to function without requiring changes. See below for details on the affected paths.  These global routes have been moved under `/namespaces/{ns}`. Continuing to use them without the namespace prefix **will still work**, and will simply query the default namespace.  <pre><code>/network/diddocs/{did}\n/network/nodes\n/network/nodes/{nameOrId}\n/network/nodes/self\n/network/organizations\n/network/organizations/{nameOrId}\n/network/organizations/self\n/status\n/status/batchmanager\n</code></pre>  These global routes have been moved under `/namespaces/{ns}` and have also been deprecated in favor of a new route name. Continuing to use them without the namespace prefix **will still work**, and will simply query the default namespace. However, it is recommended to switch to the new API spelling when possible.  <pre><code>/network/identities - replaced by existing /namespaces/{ns}/identities\n/network/identities/{did} - replaced by new /namespaces/{ns}/identities/{did}\n</code></pre>  These global routes have been have been permanently renamed. They are deemed less likely to be used by client applications, but any usage **will be broken** by this release and must be changed after upgrading.  <pre><code>/status/pins - moved to /namespaces/{ns}/pins (or /pins to query the default namespace)\n/status/websockets - moved to /websockets\n</code></pre>  The response bodies of the following APIs have also had fields removed. Any usage of the removed fields **will be broken** by this release and must be changed after upgrading.  <pre><code>/namespaces - removed all fields except \"name\", \"description\", \"created\"\n/namespaces/{ns} - same as above\n/namespaces/{ns}/status - removed \"defaults\"\n</code></pre> <p>Adjust or remove usage of admin APIs</p> Expand for migration details on all changes to <code>/admin</code> and <code>/spi</code>.  FireFly provides an administrative API in addition to the normal API. In v1.1.0, this has been renamed to SPI (Service Provider Interface). Consequently, all of the routes have moved from `/admin` to `/spi`, and the config section has been renamed from `admin` to `spi`. There is no automatic migration provided, so any usage of the old routes will need to be changed, and your config file will need to be adjusted if you wish to keep the SPI enabled (although it is perfectly fine to have both `admin` and `spi` sections if needed for migration).  The ability to set FireFly config via these routes has also been removed. Any usage of the `/admin/config` routes must be discontinued, and config should be set exclusively by editing the FireFly config file. The only route retained from this functionality was `/admin/config/reset`, which has been renamed to `/spi/reset` - this will continue to be available for performing a soft reset that reloads FireFly's config."},{"location":"releasenotes/1.1_migration_guide/#performing-the-upgrade","title":"Performing the Upgrade","text":"<p>Backup current data</p> <p>Before beginning the upgrade, it is recommended to take a full backup of your FireFly database(s). If you encounter any serious issues after the upgrade, you should revert to the old binary and restore your database snapshot. While down-migrations are provided to revert a database in place, they are not guaranteed to work in all scenarios.</p> <p>Upgrade FireFly and all dependencies</p> <p>Bring FireFly down and replace it with the new v1.1.0 binary. You should also replace other runtimes (such as blockchain, data exchange, and token connectors) with the supported versions noted in the v1.1.0 release. Once all binaries have been replaced, start them up again.</p>"},{"location":"releasenotes/1.1_migration_guide/#after-upgrading","title":"After Upgrading","text":"<p>Ensure nodes start without errors</p> <p>Ensure that FireFly starts without errors. There will likely be new deprecation warnings for config that was deprecated in v1.1.0, but these are safe to ignore for the moment. If you face any errors or crashes, please report the logs to the FireFly channel on Discord, and return your nodes to running the previous version of FireFly if necessary.</p> <p>Re-broadcast organization and node identities</p> <p>Once all nodes in the multiparty network have been upgraded and are running without errors, each node should re-broadcast its org and node identity by invoking <code>/network/organizations/self</code> and <code>/network/nodes/self</code> (or, if your application uses a non-default namespace, by invoking the <code>/namespace/{ns}</code>-prefixed versions of these APIs).</p> <p>This will ensure that queries to <code>/network/organizations</code> and <code>/network/nodes</code> return the expected results, and will register the identities in a way that can be supported by both V1 and V2 multiparty contracts (see \"Upgrading the Multi-Party Contract\").</p> <p>Update config file to latest format</p> <p>Once the network is stable, you should update your config file(s) again to remove deprecated configuration and set yourself up to take advantage of all the new configuration options available in v1.1.0.</p> <p>You can utilize the ffconfig tool to automatically check and fix deprecated config with a command such as:</p> <pre><code>ffconfig migrate -f &lt;input-file&gt; -o &lt;output-file&gt;\n</code></pre>"},{"location":"releasenotes/1.1_migration_guide/#upgrading-the-multi-party-contract","title":"Upgrading the Multi-Party Contract","text":"<p>FireFly v1.1.0 includes a new recommended version of the contract used for multi-party systems (for both Ethereum and Fabric). It also introduces a versioning method for this contract, and a path for migrating networks from one contract address to a new one.</p> <p>After upgrading FireFly itself, it is recommended to upgrade your multi-party system to the latest contract version by following these steps.</p> <ol> <li>Compile and deploy an instance of the new FireFly contract (linked above) to your blockchain, using <code>ff deploy</code> or a similar method.</li> <li>Edit the config file on each node in your network, to add the new contract to the multi-party contract list like so:</li> </ol> <pre><code>namespaces:\n  predefined:\n  - name: default\n    multiparty:\n      enabled: true\n      contract:\n      - location:\n          address: 0x09f107d670b2e69a700a4d9ef1687490ae1568db\n      - location:\n          address: 0x1bee32b37dc48e99c6b6bf037982eb3bee0e816b\n</code></pre> <p>This example assumes <code>0x09f1...</code> represents the address of the original contract, and <code>0x1bee...</code> represents the new one. Note that if you have multiple namespaces, you must repeat this step for each namespace in the config - and you must deploy a unique contract instance per namespace (in the new network rules, multiple namespaces cannot share a single contract).</p> <ol> <li>After updating each node's configuration, restart the node and ensure it starts without issues.</li> <li>Have any member of the multi-party network invoke the <code>/namespaces/{ns}/network/action</code> FireFly API with a body of <code>{\"type\": \"terminate\"}</code>. This will terminate the old contract and instruct all members to move simultaneously to the newly configured one.</li> <li>Verify success by querying <code>/namespaces/{ns}/status</code> on each node and checking that the active multi-party contract matches the new address.</li> </ol>"},{"location":"releasenotes/1.2_migration_guide/","title":"v1.2.0 Migration Guide","text":""},{"location":"releasenotes/1.2_migration_guide/#overview","title":"Overview","text":"<p>Hyperledger FireFly v1.2.0 is a feature release that includes new features for tokens and data management as well as enhancements for debugging FireFly apps and operating FireFly nodes.</p> <p>For the most part, upgrading from v1.1.x to v.1.2.0 should be a seamless experience, but there are several important things to note about changes between the two versions, which are described in detail on this page.</p>"},{"location":"releasenotes/1.2_migration_guide/#tokens-considerations","title":"Tokens considerations","text":"<p>There are quite a few new features around tokens in FireFly v1.2.0. Most notably, FireFly's token APIs now work with a much wider variety of ERC-20, ERC-721, and ERC-1155 contracts, supporting variations of these contracts generated by the OpenZepplin Contract Wizard.</p>"},{"location":"releasenotes/1.2_migration_guide/#sample-token-contract-deprecations","title":"Sample token contract deprecations","text":"<p>In FireFly v1.2.0 two of the old, lesser used sample token contracts have been deprecated. The <code>ERC20NoData</code> and <code>ERC721NoData</code> contracts have been updated and the previous versions are no longer supported, unless you set the <code>USE_LEGACY_ERC20_SAMPLE=true</code> or <code>USE_LEGACY_ERC721_SAMPLE=true</code> environment variables for your token connector.</p> <p>For more details you can read the description of the pull requests (#104 and #109) where these changes were made.</p>"},{"location":"releasenotes/1.2_migration_guide/#differences-from-v110","title":"Differences from v1.1.0","text":""},{"location":"releasenotes/1.2_migration_guide/#optional-fields","title":"Optional fields","text":"<p>Some token connectors support some optional fields when using them with certain contracts. For example, the ERC-721 token connector supports a URI field. If these optional fields are specified in an API call to a token connector and contract that does not support that field, an error will be returned, rather than the field being silently ignored.</p>"},{"location":"releasenotes/1.2_migration_guide/#auto-incrementing-token-index","title":"Auto incrementing token index","text":"<p>In FireFly v1.2.0 the default ERC-721 and ERC-1155 contracts have changed to automatically increment the token index when a token is minted. This is useful when many tokens may be minted around the same time, or by different minters. This lets the blockchain handle the ordering, and keeping track of the state of which token index should be minted next, rather than making that an application concern.</p> <p>NOTE: These new contracts will only be used for brand new FireFly stacks with v1.2.0. If you have an existing stack, the new token contracts will not be used, unless you specifically deploy them and start using them.</p>"},{"location":"releasenotes/1.2_migration_guide/#data-management-considerations","title":"Data management considerations","text":"<p>FireFly v1.2.0 introduces the ability to delete data records and their associated blobs, if present. This will remove the data and blob rows from the FireFly database, as well as removing the blob from the Data Exchange microservice. This can be very useful if your organization has data retention requirements for sensitive, private data and needs to purge data after a certain period of time.</p> <p>Please note that this API only removes data from the FireFly node on which it is called. If data has been shared with other participants of a multi-party network, it is each participants' responsibility to satisfy their own data retention policies.</p>"},{"location":"releasenotes/1.2_migration_guide/#differences-from-v110_1","title":"Differences from v1.1.0","text":"<p>It is important to note that FireFly now stores a separate copy of a blob for a given payload, even if the same data object is sent in different messages, by different network participants. Previously, in FireFly v1.1.0 the blob was de-duplicated in some cases. In FireFly v1.2.0, deleting the data object will result in each copy of the associated payload being removed.</p> <p>NOTE: If data has been published to IPFS, it cannot be deleted completely. You can still call the <code>DELETE</code> method on it, and it will be removed from FireFly's database and Data Exchange, but the payload will still persist in IPFS.</p>"},{"location":"releasenotes/1.2_migration_guide/#application-considerations","title":"Application considerations","text":""},{"location":"releasenotes/1.2_migration_guide/#optional-tokens-fields","title":"Optional tokens fields","text":"<p>Please see the optional token fields section above for details. If your application code is calling any token API endpoints with optional fields that are not supported by your token connector or contract, you will need to remove those fields from your API request or it will fail.</p>"},{"location":"releasenotes/1.2_migration_guide/#transaction-output-details","title":"Transaction output details","text":"<p>In previous versions of FireFly, transaction output details used to appear under the <code>output</code> object in the response body. Behind the scenes, some of this data is now fetched from the blockchain connector asynchronously. If your application needs the detailed output, it should now add a <code>fetchStatus=true</code> query parameter when querying for an Operation. Additionally the details have moved from the <code>output</code> field to a new <code>detail</code> field on the response body. For more details, please refer to the PRs where this change was made (#1111 and #1151). For a detailed example comparing what an Operation response body looks like in FireFly v1.2.0 compared with v1.1.x, you can expand the sections below.</p> v1.2.0 Operation response body with `fetchStatus=true` <pre>\n{\n  \"id\": \"2b0ec132-2abd-40f0-aa56-79871a7a23b9\",\n  \"namespace\": \"default\",\n  \"tx\": \"cb0e6de1-50a9-44f2-a2ff-411f6dcc19c9\",\n  \"type\": \"blockchain_invoke\",\n  \"status\": \"Succeeded\",\n  \"plugin\": \"ethereum\",\n  \"input\": {\n    \"idempotencyKey\": \"5a634941-29cb-4a4b-b5a7-196331723d6d\",\n    \"input\": {\n      \"newValue\": 42\n    },\n    \"interface\": \"46189886-cae5-42ff-bf09-25d4f58d649e\",\n    \"key\": \"0x2ecd8d5d97fb4bb7af0fbc27d7b89fd6f0366350\",\n    \"location\": {\n      \"address\": \"0x9d7ea8561d4b21cba495d1bd29a6d3421c31cf8f\"\n    },\n    \"method\": {\n      \"description\": \"\",\n      \"id\": \"d1d2a0cf-19ea-42c3-89b8-cb65850fb9c5\",\n      \"interface\": \"46189886-cae5-42ff-bf09-25d4f58d649e\",\n      \"name\": \"set\",\n      \"namespace\": \"default\",\n      \"params\": [\n        {\n          \"name\": \"newValue\",\n          \"schema\": {\n            \"details\": {\n              \"type\": \"uint256\"\n            },\n            \"type\": \"integer\"\n          }\n        }\n      ],\n      \"pathname\": \"set\",\n      \"returns\": []\n    },\n    \"methodPath\": \"set\",\n    \"options\": null,\n    \"type\": \"invoke\"\n  },\n  \"output\": {\n    \"Headers\": {\n      \"requestId\": \"default:2b0ec132-2abd-40f0-aa56-79871a7a23b9\",\n      \"type\": \"TransactionSuccess\"\n    },\n    \"protocolId\": \"000000000052/000000\",\n    \"transactionHash\": \"0x9adae77a46bf869ee97aab38bb5d789fa2496209500801e87bf9e2cce945dc71\"\n  },\n  \"created\": \"2023-01-24T14:08:17.371587084Z\",\n  \"updated\": \"2023-01-24T14:08:17.385558417Z\",\n  \"detail\": {\n    \"created\": \"2023-01-24T14:08:17.378147625Z\",\n    \"firstSubmit\": \"2023-01-24T14:08:17.381787042Z\",\n    \"gas\": \"42264\",\n    \"gasPrice\": 0,\n    \"history\": [\n      {\n        \"count\": 1,\n        \"info\": \"Success=true,Receipt=000000000052/000000,Confirmations=0,Hash=0x9adae77a46bf869ee97aab38bb5d789fa2496209500801e87bf9e2cce945dc71\",\n        \"lastOccurrence\": null,\n        \"time\": \"2023-01-24T14:08:17.384371042Z\"\n      },\n      {\n        \"count\": 1,\n        \"info\": \"Submitted=true,Receipt=,Hash=0x9adae77a46bf869ee97aab38bb5d789fa2496209500801e87bf9e2cce945dc71\",\n        \"lastOccurrence\": null,\n        \"time\": \"2023-01-24T14:08:17.381908959Z\"\n      }\n    ],\n    \"id\": \"default:2b0ec132-2abd-40f0-aa56-79871a7a23b9\",\n    \"lastSubmit\": \"2023-01-24T14:08:17.381787042Z\",\n    \"nonce\": \"34\",\n    \"policyInfo\": null,\n    \"receipt\": {\n      \"blockHash\": \"0x7a2ca7cc57fe1eb4ead3e60d3030b123667d18eb67f4b390fb0f51f970f1fba0\",\n      \"blockNumber\": \"52\",\n      \"extraInfo\": {\n        \"contractAddress\": null,\n        \"cumulativeGasUsed\": \"28176\",\n        \"from\": \"0x2ecd8d5d97fb4bb7af0fbc27d7b89fd6f0366350\",\n        \"gasUsed\": \"28176\",\n        \"status\": \"1\",\n        \"to\": \"0x9d7ea8561d4b21cba495d1bd29a6d3421c31cf8f\"\n      },\n      \"protocolId\": \"000000000052/000000\",\n      \"success\": true,\n      \"transactionIndex\": \"0\"\n    },\n    \"sequenceId\": \"0185e41b-ade2-67e4-c104-5ff553135320\",\n    \"status\": \"Succeeded\",\n    \"transactionData\": \"0x60fe47b1000000000000000000000000000000000000000000000000000000000000002a\",\n    \"transactionHash\": \"0x9adae77a46bf869ee97aab38bb5d789fa2496209500801e87bf9e2cce945dc71\",\n    \"transactionHeaders\": {\n      \"from\": \"0x2ecd8d5d97fb4bb7af0fbc27d7b89fd6f0366350\",\n      \"to\": \"0x9d7ea8561d4b21cba495d1bd29a6d3421c31cf8f\"\n    },\n    \"updated\": \"2023-01-24T14:08:17.384371042Z\"\n  }\n}\n</pre> v1.1.x Operation response body <pre>\n{\n  \"id\": \"4a1a19cf-7fd2-43f1-8fae-1e3d5774cf0d\",\n  \"namespace\": \"default\",\n  \"tx\": \"2978a248-f5df-4c78-bf04-711ab9c79f3d\",\n  \"type\": \"blockchain_invoke\",\n  \"status\": \"Succeeded\",\n  \"plugin\": \"ethereum\",\n  \"input\": {\n    \"idempotencyKey\": \"5dc2ee8a-be5c-4e60-995f-9e21818a441d\",\n    \"input\": {\n      \"newValue\": 42\n    },\n    \"interface\": \"752af5a3-d383-4952-88a9-b32b837ed1cb\",\n    \"key\": \"0xd8a27cb390fd4f446acce01eb282c7808ec52572\",\n    \"location\": {\n      \"address\": \"0x7c0a598252183999754c53d97659af9436293b82\"\n    },\n    \"method\": {\n      \"description\": \"\",\n      \"id\": \"1739f25d-ab48-4534-b278-58c4cf151bf9\",\n      \"interface\": \"752af5a3-d383-4952-88a9-b32b837ed1cb\",\n      \"name\": \"set\",\n      \"namespace\": \"default\",\n      \"params\": [\n        {\n          \"name\": \"newValue\",\n          \"schema\": {\n            \"details\": {\n              \"type\": \"uint256\"\n            },\n            \"type\": \"integer\"\n          }\n        }\n      ],\n      \"pathname\": \"set\",\n      \"returns\": []\n    },\n    \"methodPath\": \"set\",\n    \"options\": null,\n    \"type\": \"invoke\"\n  },\n  \"output\": {\n    \"_id\": \"default:4a1a19cf-7fd2-43f1-8fae-1e3d5774cf0d\",\n    \"blockHash\": \"0x13660667b69f48646025a87db603abdeeaa88036e9a1252b1af4ec1fc3e1d850\",\n    \"blockNumber\": \"52\",\n    \"cumulativeGasUsed\": \"28176\",\n    \"from\": \"0xd8a27cb390fd4f446acce01eb282c7808ec52572\",\n    \"gasUsed\": \"28176\",\n    \"headers\": {\n      \"id\": \"8dfaabd1-4493-4a64-52dd-762497022ba2\",\n      \"requestId\": \"default:4a1a19cf-7fd2-43f1-8fae-1e3d5774cf0d\",\n      \"requestOffset\": \"\",\n      \"timeElapsed\": 0.109499833,\n      \"timeReceived\": \"2023-01-24T17:16:52.372449013Z\",\n      \"type\": \"TransactionSuccess\"\n    },\n    \"nonce\": \"0\",\n    \"receivedAt\": 1674580612482,\n    \"status\": \"1\",\n    \"to\": \"0x7c0a598252183999754c53d97659af9436293b82\",\n    \"transactionHash\": \"0x522e5aac000f5befba61ddfd707aaf5c61314f47e00cd0c5b779f69dd14bd899\",\n    \"transactionIndex\": \"0\"\n  },\n  \"created\": \"2023-01-24T17:16:52.368498346Z\",\n  \"updated\": \"2023-01-24T17:16:52.48408293Z\"\n}\n</pre>"},{"location":"releasenotes/1.2_migration_guide/#local-development-considerations","title":"Local development considerations","text":"<p>It is also worth noting that the default Ethereum blockchain connector in the FireFly CLI is now Evmconnect. Ethconnect is still fully supported, but FireFly v1.2.0 marks a point of maturity in the project where it is now the recommended choice for any Ethereum based FireFly stack.</p>"},{"location":"releasenotes/1.3_migration_guide/","title":"v1.3.0 Migration Guide","text":""},{"location":"releasenotes/1.3_migration_guide/#overview","title":"Overview","text":"<p>Hyperledger FireFly v1.3.0 is a feature release that includes changes around event streaming, contract listeners, define/publish APIs as well as a range of general fixes.</p> <p>For the most part, upgrading from v1.2.x to v1.3.0 should be a seamless experience, but there are several important things to note about changes between the two versions, which are described in detail on this page.</p>"},{"location":"releasenotes/1.3_migration_guide/#docker-image-file-permission-considerations","title":"Docker image file permission considerations","text":"<p>Following security best practices, the official published Docker images for FireFly Core and all of its microservices now run as a non-root user by default. If you are running a FireFly release prior to v1.3.0, depending on how you were running your containers, you may need to adjust file permissions inside volumes that these containers write to. If you have overridden the default user for your containers (for example though a Kubernetes deployment) you may safely ignore this section.</p> <p>\u26a0\ufe0f Warning: If you have been using the default root user and upgrade to FireFly v1.3.0 without changing these file permissions your services may fail to start.</p> <p>The new default user is <code>1001</code>. If you are not overriding the user for your container, this user or group needs to have write permissions in several places. The list of services and directories you should specifically check are:</p> <ul> <li>firefly-evmconnect</li> <li><code>persistence.leveldb.path</code> directory set in the config file</li> <li>firefly-ethconnect</li> <li><code>rest.rest-gateway.openapi.storagePath</code> directory in the config file</li> <li><code>rest.rest-gateway.openapi.eventsDB</code> directory in the config file</li> <li>firefly-fabconnect</li> <li><code>receipts.leveldb.path</code> directory in the config file</li> <li><code>events.leveldb.path</code> directory in the config file</li> <li>firefly-dataexchange-https</li> <li>Data directory set by the <code>DATA_DIRECTORY</code> environment variable (default <code>/data</code>)</li> </ul>"},{"location":"releasenotes/1.3_migration_guide/#api-definitionpublication-considerations","title":"API definition/publication considerations","text":"<p>As of FireFly v1.3.0 in multi-party namespaces, by default, contract interfaces, contracts APIs, and token pools have distinct steps in their creation flow and by default they are unpublished.</p> <p>These following described changes impact contract interfaces, contract APIs, and token pools.</p> <p>Previously, when creating one of the affected resources in a multi-party network, if successful, the resource would be automatically broadcasted to other namespaces. In FireFly v1.3.0, this behaviour has changed, now when one of the resources is created there are 2 distinct states for the resource, published and unpublished. The default state for a resource (provided FireFly is not told otherwise) after creation is unpublished.</p> <p>When a resource is unpublished it is not broadcasted to other namespaces in the multi-party network, and it is not pinned to the blockchain. In this state, it is possible to call the <code>DELETE</code> APIs to remove the resource (such as in the case where configuration needs to be changed) and reclaim the name that has been provided to it, so that it can be recreated.</p> <p>When a resource is published it is broadcasted to other namespaces in the multi-party network, and it is pinned to the blockchain. In this state, it is no longer possible to call the <code>DELETE</code> APIs to remove the resource.</p> <p>In FireFly v1.2.0 to create one of the affected resources and publish it to other parties, a <code>POST</code> call would be made to its respective API route and the broadcast would happen immediately. To achieve the same behaviour in FireFly v1.3.0, there are 2 options for all impacted resources, either providing a query parameter at creation to signal immediate publish, or a subsequent API call to publish the resources.</p>"},{"location":"releasenotes/1.3_migration_guide/#contract-interfaces","title":"Contract interfaces","text":"<p>Previously, to create a contract interface a <code>POST</code> call would be made to <code>/contracts/interfaces</code> and the interface would be broadcasted to all other namepsaces. In FireFly v1.3.0, this same call can be made with the <code>publish=true</code> query parameter, or a subsequent API call can be made on an unpublished interface on <code>POST /contracts/interfaces/{name}/{version}/publish</code> specifying the name and version of the interface.</p> <p>For an exact view of the changes to contract interfaces, see PR #1279.</p>"},{"location":"releasenotes/1.3_migration_guide/#contract-apis","title":"Contract APIs","text":"<p>Previously, to create a contract API a <code>POST</code> call would be made to <code>/apis</code> and the API would be broadcasted to all other namepsaces. In FireFly v1.3.0, this same call can be made with the <code>publish=true</code> query parameter, or a subsequent API call can be made on an unpublished API on <code>/apis/{apiName}/publish</code> specifying the name of the API.</p> <p>For an exact view of the changes to contract APIs, see PR #1322.</p>"},{"location":"releasenotes/1.3_migration_guide/#token-pools","title":"Token pools","text":"<p>Previously, to create a token pool a <code>POST</code> call would be made to <code>/tokens/pools</code> and the token pool would be broadcasted to all other namepsaces. In FireFly v1.3.0, this same call can be made with the <code>publish=true</code> query parameter, or a subsequent API call can be made on an unpublished token pool on <code>/tokens/pools/{nameOrId}/publish</code> specifying the name or ID of the token pool.</p> <p>For an exact view of the changes to token pools, see PR #1261.</p>"},{"location":"releasenotes/1.3_migration_guide/#event-stream-considerations","title":"Event stream considerations","text":""},{"location":"releasenotes/1.3_migration_guide/#single-event-stream-per-namespace","title":"Single event stream per namespace","text":"<p>In this release, the model for event streams in a multi-party network has fundamentally changed. Previously, there was a single event stream for each blockchain plugin, even if this plugin served multiple namespaces. In FireFly v1.3.0 there is now a single event stream per namespace in the network.</p> <p>When migrating from FireFly v1.2.X to v1.3.0, due to these changes, existing event streams will be rebuilt. This means that connectors will replay past events to FireFly, but FireFly will automatically de-duplicate them by design so this is a safe operation.</p> <p>The migration to individual event streams promotes high-availability capability but is not itself a breaking change, however the ID format for event streams has changed. Event streams now follow the format <code>&lt;plugin_topic_name&gt;/&lt;namespace_name&gt;</code>. For example, an event stream for the default namespace with a plugin topic of 0 would now be: <code>0/default</code>.</p> <p>Summarily, these changes should not impact end-users of FireFly, but they're noted here as they are significant architectural changes to the relationships between namespaces, plugins, and connectors.</p> <p>For an exact view of the changes, see PR #1388.</p>"},{"location":"releasenotes/1.3_migration_guide/#configuration-considerations","title":"Configuration considerations","text":""},{"location":"releasenotes/1.3_migration_guide/#deprecated-configuration","title":"Deprecated configuration","text":"<p>In FireFly v1.3.0 deprecated configuration options for the <code>blockchain</code>, <code>database</code>, <code>dataexchange</code>, <code>sharedstorage</code> and <code>tokens</code> plugins have been removed, and can no longer be provided.</p> <p>For an exact view of the changes, see PR #1289.</p>"},{"location":"releasenotes/1.3_migration_guide/#token-pool-considerations","title":"Token pool considerations","text":""},{"location":"releasenotes/1.3_migration_guide/#activity-indicator-changes","title":"Activity indicator changes","text":"<p>Token pools have a status, when creating a token pool previously, it would go into a pending state immediately following creation, and then into a confirmed state when it has been confirmed on the chain. This behaviour is still consistent in FireFly v1.3.0, but the representation of the data has changed.</p> <p>Previously, token pools had a <code>state</code> field with an enumerated value which was either <code>pending</code>, or <code>confirmed</code>, this has been replaced with an <code>active</code> boolean field, where <code>true</code> indicates the token pool has been committed onto chain, and <code>false</code> indicated the transaction has not yet been confirmed.</p> <p>For an exact view of the changes, see PR #1305.</p>"},{"location":"releasenotes/1.3_migration_guide/#fabconnect-event-considerations","title":"FabConnect event considerations","text":""},{"location":"releasenotes/1.3_migration_guide/#fabconnect-protocol-id-format-changes","title":"FabConnect Protocol ID format changes","text":"<p>Prior to FireFly v1.3.0, when the FabConnect client indexed events submitted by the Fabric SDK, FireFly would deduplicate events into a single event because the protocol ID of the events compiled into a single block would evaluate to be the same. In this release, we have changed the format of the calculated protocol ID so that is unique across events even if they are located within the same block. Crucially, the new format includes the transaction hash, so events are no longer alphanumerically sortable.</p> <p>For an exact view of the changes, see PR #1345.</p>"},{"location":"releasenotes/1.3_migration_guide/#local-development-considerations","title":"Local development considerations","text":""},{"location":"releasenotes/1.3_migration_guide/#go-version-upgrade","title":"Go version upgrade","text":"<p>FireFly v1.3.0 now uses Go 1.21 across all modules.</p>"},{"location":"swagger/","title":"API Spec","text":"<p>This is the FireFly OpenAPI Specification document generated by FireFly</p> <p>Note: The 'Try it out' buttons will not work on this page because it's not running against a live version of FireFly. To actually try it out, we recommend using the FireFly CLI to start an instance on your local machine (which will start the FireFly core on port 5000 by default) and then open the Swagger UI associated with your local node by opening a new tab and visiting http://localhost:5000/api</p> <p></p>"},{"location":"tutorials/basic_auth/","title":"Basic Auth","text":""},{"location":"tutorials/basic_auth/#quick-reference","title":"Quick reference","text":"<p>FireFly has a pluggable auth system which can be enabled at two different layers of the stack. At the top, auth can be enabled at the HTTP listener level. This will protect all requests to the given listener. FireFly has three different HTTP listeners, which could each use a different auth scheme:</p> <ol> <li>The main API</li> <li>The SPI (for internal or admin use)</li> <li>The metrics API.</li> </ol> <p>Auth can also be enabled at the namespace level within FireFly as well. This enables several different use cases. For example, you might have two different teams that want to use the same FireFly node, each with different sets of authorized users. You could configure them to use separate namespaces and create separate auth schemes on each.</p> <p>FireFly has a basic auth plugin built in, which we will be configuring in this tutorial.</p> <p>NOTE: This guide assumes that you have already gone through the Getting Started Guide and have set up and run a stack at least once.</p>"},{"location":"tutorials/basic_auth/#additional-info","title":"Additional info","text":"<ul> <li>Config Reference: HTTP Auth</li> <li>Auth plugin interface</li> <li>Basic auth plugin implementation</li> </ul>"},{"location":"tutorials/basic_auth/#create-a-password-file","title":"Create a password file","text":"<p>FireFly's built in basic auth plugin uses a password hash file to store the list of authorized users. FireFly uses the bcrypt algorithm to compare passwords against the stored hash. You can use <code>htpasswd</code> on a command line to generate a hash file.</p>"},{"location":"tutorials/basic_auth/#create-the-test_users-password-hash-file","title":"Create the <code>test_users</code> password hash file","text":"<pre><code>touch test_users\n</code></pre>"},{"location":"tutorials/basic_auth/#create-a-user-named-firefly","title":"Create a user named <code>firefly</code>","text":"<pre><code>htpasswd -B test_users firefly\n</code></pre> <p>You will be prompted to type the password for the new user twice. Optional: You can continue to add new users by running this command with a different username.</p> <pre><code>htpasswd -B test_users &lt;username&gt;\n</code></pre>"},{"location":"tutorials/basic_auth/#enable-basic-auth-at-the-namespace-level","title":"Enable basic auth at the Namespace level","text":"<p>To enable auth at the HTTP listener level we will need to edit the FireFly core config file. You can find the config file for the first node in your stack at the following path:</p> <pre><code>~/.firefly/stacks/&lt;stack_name&gt;/runtime/config/firefly_core_0.yml\n</code></pre> <p>Open the config file in your favorite editor and add the <code>auth</code> section to the <code>plugins</code> list:</p> <pre><code>plugins:\n  auth:\n  - name: test_user_auth\n    type: basic\n    basic:\n      passwordfile: /etc/firefly/test_users\n</code></pre> <p>You will also need to add <code>test_user_auth</code> to the list of plugins used by the <code>default</code> namespace:</p> <pre><code>namespaces:\n  predefined:\n  - plugins:\n    - database0\n    - blockchain0\n    - dataexchange0\n    - sharedstorage0\n    - erc20_erc721\n    - test_user_auth\n</code></pre>"},{"location":"tutorials/basic_auth/#mount-the-password-hash-file-in-the-docker-container","title":"Mount the password hash file in the Docker container","text":"<p>If you set up your FireFly stack using the FireFly CLI we will need to mount the password hash file in the Docker container, so that FireFly can actually read the file. This can be done by editing the <code>docker-compose.override.yml</code> file at:</p> <pre><code>~/.firefly/stacks/&lt;stack_name&gt;/docker-compose.override.yml\n</code></pre> <p>Edit the file to look like this, replacing the path to your <code>test_users</code> file:</p> <pre><code># Add custom config overrides here\n# See https://docs.docker.com/compose/extends\nversion: \"2.1\"\nservices:\n  firefly_core_0:\n    volumes:\n      - PATH_TO_YOUR_TEST_USERS_FILE:/etc/firefly/test_users\n</code></pre>"},{"location":"tutorials/basic_auth/#restart-your-firefly-core-container","title":"Restart your FireFly Core container","text":"<p>To restart your FireFly stack and have Docker pick up the new volume, run:</p> <pre><code>ff stop &lt;stack_name&gt;\nff start &lt;stack_name&gt;\n</code></pre> <p>NOTE: The FireFly basic auth plugin reads this file at startup and will not read it again during runtime. If you add any users or change passwords, restarting the node will be necessary to use an updated file.</p>"},{"location":"tutorials/basic_auth/#test-basic-auth","title":"Test basic auth","text":"<p>After FireFly starts back up, you should be able to test that auth is working correctly by making an unauthenticated request to the API:</p> <pre><code>curl http://localhost:5000/api/v1/status\n{\"error\":\"FF00169: Unauthorized\"}\n</code></pre> <p>However, if we add the username and password that we created above, the request should still work:</p> <pre><code>curl -u \"firefly:firefly\" http://localhost:5000/api/v1/status\n{\"namespace\":{\"name\":\"default\",\"networkName\":\"default\",\"description\":\"Default predefined namespace\",\"created\":\"2022-10-18T16:35:57.603205507Z\"},\"node\":{\"name\":\"node_0\",\"registered\":false},\"org\":{\"name\":\"org_0\",\"registered\":false},\"plugins\":{\"blockchain\":[{\"name\":\"blockchain0\",\"pluginType\":\"ethereum\"}],\"database\":[{\"name\":\"database0\",\"pluginType\":\"sqlite3\"}],\"dataExchange\":[{\"name\":\"dataexchange0\",\"pluginType\":\"ffdx\"}],\"events\":[{\"pluginType\":\"websockets\"},{\"pluginType\":\"webhooks\"},{\"pluginType\":\"system\"}],\"identity\":[],\"sharedStorage\":[{\"name\":\"sharedstorage0\",\"pluginType\":\"ipfs\"}],\"tokens\":[{\"name\":\"erc20_erc721\",\"pluginType\":\"fftokens\"}]},\"multiparty\":{\"enabled\":true,\"contract\":{\"active\":{\"index\":0,\"location\":{\"address\":\"0xa750e2647e24828f4fec2e6e6d61fc08ccca5efa\"},\"info\":{\"subscription\":\"sb-d0642f14-f89a-41bb-6fd4-ae74b9501b6c\",\"version\":2}}}}}\n</code></pre>"},{"location":"tutorials/basic_auth/#enable-auth-at-the-http-listener-level","title":"Enable auth at the HTTP listener level","text":"<p>You may also want to enable auth at the HTTP listener level, for instance on the SPI (Service Provider Interface) to limit administrative actions. To enable auth at the HTTP listener level we will need to edit the FireFly core config file. You can find the config file for the first node in your stack at the following path:</p> <pre><code>~/.firefly/stacks/&lt;stack_name&gt;/runtime/config/firefly_core_0.yml\n</code></pre> <p>Open the config file in your favorite editor and change the <code>spi</code> section to look like the following:</p> <pre><code>spi:\n  address: 0.0.0.0\n  enabled: true\n  port: 5101\n  publicURL: http://127.0.0.1:5101\n  auth:\n    type: basic\n    basic:\n      passwordfile: /etc/firefly/test_users\n</code></pre>"},{"location":"tutorials/basic_auth/#restart-firefly-to-apply-the-changes","title":"Restart FireFly to apply the changes","text":"<p>NOTE You will need to mount the password hash file following the instructions above if you have not already.</p> <p>You can run the following to restart your stack:</p> <pre><code>ff stop &lt;stack_name&gt;\nff start &lt;stack_name&gt;\n</code></pre>"},{"location":"tutorials/basic_auth/#test-basic-auth_1","title":"Test basic auth","text":"<p>After FireFly starts back up, you should be able to query the SPI and the request should be unauthorized.</p> <pre><code>curl http://127.0.0.1:5101/spi/v1/namespaces\n{\"error\":\"FF00169: Unauthorized\"}\n</code></pre> <p>Adding the username and password that we set earlier, should make the request succeed.</p> <pre><code>curl -u \"firefly:firefly\" http://127.0.0.1:5101/spi/v1/namespaces\n[{\"name\":\"default\",\"networkName\":\"default\",\"description\":\"Default predefined namespace\",\"created\":\"2022-10-18T16:35:57.603205507Z\"}]\n</code></pre>"},{"location":"tutorials/broadcast_data/","title":"Broadcast data","text":""},{"location":"tutorials/broadcast_data/#quick-reference","title":"Quick reference","text":"<ul> <li>Sends a <code>message</code> visible to all parties in the network</li> <li>The message describes who sent it, and exactly what data was sent</li> <li>A <code>message</code> has one or more attached pieces of business <code>data</code></li> <li>Can be sent in-line, uploaded in advanced, or received from other parties</li> <li>Can include smaller JSON payloads suitable for database storage<ul> <li>These can be verified against a <code>datatype</code></li> </ul> </li> <li>Can include references to large (multi megabyte/gigabyte) Blob data</li> <li>Sequenced via the blockchain</li> <li>The blockchain does not contain any data, just a hash pin</li> <li>Batched for efficiency</li> <li>One <code>batch</code> can pin hundreds of <code>message</code> broadcasts</li> <li>The whole batch is written to the shared storage</li> </ul>"},{"location":"tutorials/broadcast_data/#additional-info","title":"Additional info","text":"<ul> <li>Key Concepts: Broadcast / shared data</li> <li>Swagger Reference: POST /api/v1/namespaces/{ns}/messages/broadcast</li> </ul>"},{"location":"tutorials/broadcast_data/#example-1-inline-string-data","title":"Example 1: Inline string data","text":"<p><code>POST</code> <code>/api/v1/namespaces/default/messages/broadcast</code></p> <pre><code>{\n  \"data\": [\n    {\n      \"value\": \"a string\"\n    }\n  ]\n}\n</code></pre>"},{"location":"tutorials/broadcast_data/#example-message-response","title":"Example message response","text":"<pre><code>{\n  \"header\": {\n    \"id\": \"607e22ad-04fa-434a-a073-54f528ca14fb\", // uniquely identifies this broadcast message\n    \"type\": \"broadcast\", // set automatically\n    \"txtype\": \"batch_pin\", // message will be batched, and sequenced via the blockchain\n    \"author\": \"0x0a65365587a65ce44938eab5a765fe8bc6532bdf\", // set automatically in this example to the node org\n    \"created\": \"2021-07-01T18:06:24.5817016Z\", // set automatically\n    \"namespace\": \"default\", // the 'default' namespace was set in the URL\n    \"topics\": [\n      \"default\" // the default topic that the message is published on, if no topic is set\n    ],\n    // datahash is calculated from the data array below\n    \"datahash\": \"5a7bbc074441fa3231d9c8fc942d68ef9b9b646dd234bb48c57826dc723b26fd\"\n  },\n  \"hash\": \"81acf8c8f7982dbc49258535561461601cbe769752fecec0f8ce0358664979e6\", // hash of the header\n  \"state\": \"ready\", // this message is stored locally but not yet confirmed\n  \"data\": [\n    // one item of data was stored\n    {\n      \"id\": \"8d8635e2-7c90-4963-99cc-794c98a68b1d\", // can be used to query the data in the future\n      \"hash\": \"c95d6352f524a770a787c16509237baf7eb59967699fb9a6d825270e7ec0eacf\" // sha256 hash of `\"a string\"`\n    }\n  ]\n}\n</code></pre>"},{"location":"tutorials/broadcast_data/#example-2-inline-object-data-to-a-topic-no-datatype-verification","title":"Example 2: Inline object data to a topic (no datatype verification)","text":"<p>It is very good practice to set a <code>tag</code> and <code>topic</code> in each of your messages:</p> <ul> <li><code>tag</code> should tell the apps receiving the broadcast (including the local app), what   to do when it receives the message. Its the reason for the broadcast - an   application specific type for the message.</li> <li><code>topic</code> should be something like a well known identifier that relates to the   information you are publishing. It is used as an ordering context, so all   broadcasts on a given topic are assured to be processed in order.</li> </ul> <p><code>POST</code> <code>/api/v1/namespaces/default/messages/broadcast</code></p> <pre><code>{\n  \"header\": {\n    \"tag\": \"new_widget_created\",\n    \"topics\": [\"widget_id_12345\"]\n  },\n  \"data\": [\n    {\n      \"value\": {\n        \"id\": \"widget_id_12345\",\n        \"name\": \"superwidget\"\n      }\n    }\n  ]\n}\n</code></pre>"},{"location":"tutorials/broadcast_data/#notes-on-why-setting-a-topic-is-important","title":"Notes on why setting a topic is important","text":"<p>The FireFly aggregator uses the <code>topic</code> (obfuscated on chain) to determine if a message is the next message in an in-flight sequence for any groups the node is involved in. If it is, then that message must receive all off-chain private data and be confirmed before any subsequent messages can be confirmed on the same sequence.</p> <p>So if you use the same topic in every message, then a single failed send on one topic blocks delivery of all messages between those parties, until the missing data arrives.</p> <p>Instead it is best practice to set the topic on your messages to a value that identifies an ordered stream of business processing. Some examples:</p> <ul> <li>A long-running business process instance identifier assigned at initiation</li> <li>A real-world business transaction identifier used off-chain</li> <li>The agreed identifier of an asset you are attaching a stream of evidence to</li> <li>An NFT identifier that is assigned to an asset (digital twin scenarios)</li> <li>An agreed primary key for a data resource being reconciled between multiple parties</li> </ul> <p>The <code>topic</code> field is an array, because there are cases (such as merging two identifiers) where you need a message to be deterministically ordered across multiple sequences. However, this is an advanced use case and you are likely to set a single topic on the vast majority of your messages.</p>"},{"location":"tutorials/broadcast_data/#example-3-upload-a-blob-with-metadata-and-broadcast","title":"Example 3: Upload a blob with metadata and broadcast","text":"<p>Here we make two API calls.</p> <ol> <li> <p>Create the <code>data</code> object explicitly, using a multi-part form upload</p> </li> <li> <p>You can also just post JSON to this endpoint</p> </li> <li> <p>Broadcast a message referring to that data</p> </li> <li> <p>The Blob attachment gets published to shared storage</p> </li> <li>This happens the first time a broadcast happens on a data attachment</li> <li>A pin goes to the blockchain</li> <li>The metadata goes into a batch with the message</li> </ol>"},{"location":"tutorials/broadcast_data/#multipart-form-post-of-a-file","title":"Multipart form post of a file","text":"<p>Example curl command (Linux/Mac) to grab an image from the internet, and pipe it into a multi-part form post to FireFly.</p> <p>Note we use <code>autometa</code> to cause FireFly to automatically add the <code>filename</code>, and <code>size</code>, to the JSON part of the <code>data</code> object for us.</p> <pre><code>curl -sLo - https://github.com/hyperledger/firefly/raw/main/docs/firefly_logo.png \\\n | curl --form autometa=true --form file=@- \\\n   http://localhost:5000/api/v1/namespaces/default/data\n</code></pre>"},{"location":"tutorials/broadcast_data/#example-data-response-from-blob-upload","title":"Example data response from Blob upload","text":"<p>Status: <code>200 OK</code> - your data is uploaded to your local FireFly node</p> <p>At this point the data has not be shared with anyone else in the network</p> <pre><code>{\n  // A uniquely generated ID, we can refer to when sending this data to other parties\n  \"id\": \"97eb750f-0d0b-4c1d-9e37-1e92d1a22bb8\",\n  \"validator\": \"json\", // the \"value\" part is JSON\n  \"namespace\": \"default\", // from the URL\n  // The hash is a combination of the hash of the \"value\" metadata, and the\n  // hash of the blob\n  \"hash\": \"997af6a9a19f06cc8a46872617b8bf974b106f744b2e407e94cc6959aa8cf0b8\",\n  \"created\": \"2021-07-01T20:20:35.5462306Z\",\n  \"value\": {\n    \"filename\": \"-\", // dash is how curl represents the filename for stdin\n    \"size\": 31185 // the size of the blob data\n  },\n  \"blob\": {\n    // A hash reference to the blob\n    \"hash\": \"86e6b39b04b605dd1b03f70932976775962509d29ae1ad2628e684faabe48136\"\n    // Note at this point there is no public reference. The only place\n    // this data has been uploaded to is our own private data exchange.\n    // It's ready to be published to everyone (broadcast), or privately\n    // transferred (send) to other parties in the network. But that hasn't\n    // happened yet.\n  }\n}\n</code></pre>"},{"location":"tutorials/broadcast_data/#broadcast-the-uploaded-data","title":"Broadcast the uploaded data","text":"<p>Just include a reference to the <code>id</code> returned from the upload.</p> <p><code>POST</code> <code>/api/v1/namespaces/default/messages/broadcast</code></p> <pre><code>{\n  \"data\": [\n    {\n      \"id\": \"97eb750f-0d0b-4c1d-9e37-1e92d1a22bb8\"\n    }\n  ]\n}\n</code></pre>"},{"location":"tutorials/broadcast_data/#broadcasting-messages-using-the-sandbox","title":"Broadcasting Messages using the Sandbox","text":"<p>All of the functionality discussed above can be done through the FireFly Sandbox.</p> <p>To get started, open up the Web UI and Sanbox UI for at least one of your members. The URLs for these were printed in your terminal when you started your FireFly stack.</p> <p>In the sandbox, enter your message into the message field as seen in the screenshot below.</p> <p></p> <p>Notice how the <code>data</code> field in the center panel updates in real time.</p> <p>Click the blue <code>Run</code> button. This should return a <code>202</code> response immediately in the Server Response section and will populate the right hand panel with transaction information after a few seconds.</p> <p></p> <p>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</p> <p></p>"},{"location":"tutorials/create_custom_identity/","title":"Create a Custom Identity","text":""},{"location":"tutorials/create_custom_identity/#quick-reference","title":"Quick reference","text":"<p>Out of the box, a FireFly Supernode contains both an <code>org</code> and a <code>node</code> identity. Your use case might demand more granular notions of identity (ex. customers, clients, etc.). Instead of creating a Supernode for each identity, you can create multiple custom identities within a FireFly Supernode.</p>"},{"location":"tutorials/create_custom_identity/#additional-info","title":"Additional info","text":"<ul> <li>Reference: Identities</li> <li>Swagger: POST /api/v1/identities</li> </ul>"},{"location":"tutorials/create_custom_identity/#previous-steps-start-your-environment","title":"Previous steps: Start your environment","text":"<p>If you haven't started a FireFly stack already, please go to the Getting Started guide on how to Start your environment</p> <p>\u2190 \u2461 Start your environment</p>"},{"location":"tutorials/create_custom_identity/#step-1-create-a-new-account","title":"Step 1: Create a new account","text":"<p>The FireFly CLI has a helpful command to create an account in a local development environment for you.</p> <p>NOTE: In a production environment, key management actions such as creation, encryption, unlocking, etc. may be very different, depending on what type of blockchain node and signer your specific deployment is using.</p> <p>To create a new account on your local stack, run:</p> <pre><code>ff accounts create &lt;stack_name&gt;\n</code></pre> <pre><code>{\n  \"address\": \"0xc00109e112e21165c7065da776c75cfbc9cdc5e7\",\n  \"privateKey\": \"...\"\n}\n</code></pre> <p>The FireFly CLI has created a new private key and address for us to be able to use, and it has loaded the encrypted private key into the signing container. However, we haven't told FireFly itself about the new key, or who it belongs to. That's what we'll do in the next steps.</p>"},{"location":"tutorials/create_custom_identity/#step-2-query-the-parent-org-for-its-uuid","title":"Step 2: Query the parent org for its UUID","text":"<p>If we want to create a new custom identity under the organizational identity that we're using in a multiparty network, first we will need to look up the UUID for our org identity. We can look that up by making a <code>GET</code> request to the status endpoint on the default namespace.</p>"},{"location":"tutorials/create_custom_identity/#request","title":"Request","text":"<p><code>GET</code> <code>http://localhost:5000/api/v1/status</code></p>"},{"location":"tutorials/create_custom_identity/#response","title":"Response","text":"<pre><code>{\n    \"namespace\": {...},\n    \"node\": {...},\n    \"org\": {\n        \"name\": \"org_0\",\n        \"registered\": true,\n        \"did\": \"did:firefly:org/org_0\",\n        \"id\": \"1c0abf75-0f3a-40e4-a8cd-5ff926f80aa8\", // We need this in Step 3\n        \"verifiers\": [\n            {\n                \"type\": \"ethereum_address\",\n                \"value\": \"0xd7320c76a2efc1909196dea876c4c7dabe49c0f4\"\n            }\n        ]\n    },\n    \"plugins\": {...},\n    \"multiparty\": {...}\n}\n</code></pre>"},{"location":"tutorials/create_custom_identity/#step-3-register-the-new-custom-identity-with-firefly","title":"Step 3: Register the new custom identity with FireFly","text":"<p>Now we can <code>POST</code> to the identities endpoint to create a new custom identity. We will include the UUID of the organizational identity from the previous step in the <code>\"parent\"</code> field in the request.</p>"},{"location":"tutorials/create_custom_identity/#request_1","title":"Request","text":"<p><code>POST</code> <code>http://localhost:5000/api/v1/identities</code></p> <pre><code>{\n    \"name\": \"myCustomIdentity\",\n    \"key\": \"0xc00109e112e21165c7065da776c75cfbc9cdc5e7\", // Signing Key from Step 1\n    \"parent\": \"1c0abf75-0f3a-40e4-a8cd-5ff926f80aa8\" // Org UUID from Step 2\n}\n</code></pre>"},{"location":"tutorials/create_custom_identity/#response_1","title":"Response","text":"<pre><code>{\n    \"id\": \"5ea8f770-e004-48b5-af60-01994230ed05\",\n    \"did\": \"did:firefly:myCustomIdentity\",\n    \"type\": \"custom\",\n    \"parent\": \"1c0abf75-0f3a-40e4-a8cd-5ff926f80aa8\",\n    \"namespace\": \"\",\n    \"name\": \"myCustomIdentity\",\n    \"messages\": {\n        \"claim\": \"817b7c79-a934-4936-bbb1-7dcc7c76c1f4\",\n        \"verification\": \"ae55f998-49b1-4391-bed2-fa5e86dc85a2\",\n        \"update\": null\n    }\n}\n</code></pre>"},{"location":"tutorials/create_custom_identity/#step-4-query-the-new-custom-identity","title":"Step 4: Query the New Custom Identity","text":"<p>Lastly, if we want to confirm that the new identity has been created, we can query the identities endpoint to see our new custom identity.</p>"},{"location":"tutorials/create_custom_identity/#request_2","title":"Request","text":"<p><code>GET</code> <code>http://localhost:5000/api/v1/identities?fetchverifiers=true</code></p> <p>NOTE: Using <code>fetchverifiers=true</code> will return the cryptographic verification mechanism for the FireFly identity.</p>"},{"location":"tutorials/create_custom_identity/#response_2","title":"Response","text":"<pre><code>[\n    {\n        \"id\": \"5ea8f770-e004-48b5-af60-01994230ed05\",\n        \"did\": \"did:firefly:myCustomIdentity\",\n        \"type\": \"custom\",\n        \"parent\": \"1c0abf75-0f3a-40e4-a8cd-5ff926f80aa8\",\n        \"namespace\": \"default\",\n        \"name\": \"myCustomIdentity\",\n        \"messages\": {\n            \"claim\": \"817b7c79-a934-4936-bbb1-7dcc7c76c1f4\",\n            \"verification\": \"ae55f998-49b1-4391-bed2-fa5e86dc85a2\",\n            \"update\": null\n        },\n        \"created\": \"2022-09-19T18:10:47.365068013Z\",\n        \"updated\": \"2022-09-19T18:10:47.365068013Z\",\n        \"verifiers\": [\n            {\n                \"type\": \"ethereum_address\",\n                \"value\": \"0xfe1ea8c8a065a0cda424e2351707c7e8eb4d2b6f\"\n            }\n        ]\n    },\n    { ... },\n    { ... }\n]\n</code></pre>"},{"location":"tutorials/define_datatype/","title":"Define a datatype","text":""},{"location":"tutorials/define_datatype/#quick-reference","title":"Quick reference","text":"<p>As your use case matures, it is important to agree formal datatypes between the parties. These canonical datatypes need to be defined and versioned, so that each member can extract and transform data from their internal systems into this datatype.</p> <p>Datatypes are broadcast to the network so everybody refers to the same JSON schema when validating their data. The broadcast must complete before a datatype can be used by an application to upload/broadcast/send data. The same system of broadcast within FireFly is used to broadcast definitions of datatypes, as is used to broadcast the data itself.</p>"},{"location":"tutorials/define_datatype/#additional-info","title":"Additional info","text":"<ul> <li>Key Concepts: Broadcast / shared data</li> <li>Swagger: POST /api/v1/namespaces/{ns}/datatypes</li> </ul>"},{"location":"tutorials/define_datatype/#example-1-broadcast-new-datatype","title":"Example 1: Broadcast new datatype","text":"<p><code>POST</code> <code>/api/v1/namespaces/{ns}/datatypes</code></p> <pre><code>{\n  \"name\": \"widget\",\n  \"version\": \"0.0.2\",\n  \"value\": {\n    \"$id\": \"https://example.com/widget.schema.json\",\n    \"$schema\": \"https://json-schema.org/draft/2020-12/schema\",\n    \"title\": \"Widget\",\n    \"type\": \"object\",\n    \"properties\": {\n      \"id\": {\n        \"type\": \"string\",\n        \"description\": \"The unique identifier for the widget.\"\n      },\n      \"name\": {\n        \"type\": \"string\",\n        \"description\": \"The person's last name.\"\n      }\n    }\n  }\n}\n</code></pre>"},{"location":"tutorials/define_datatype/#example-message-response","title":"Example message response","text":"<p>Status: <code>202 Accepted</code> - a broadcast message has been sent, and on confirmation the new datatype will be created (unless it conflicts with another definition with the same <code>name</code> and <code>version</code> that was ordered onto the blockchain before this definition).</p> <pre><code>{\n  \"header\": {\n    \"id\": \"727f7d3a-d07e-4e80-95af-59f8d2ac7531\", // this is the ID of the message, not the data type\n    \"type\": \"definition\", // a special type for system broadcasts\n    \"txtype\": \"batch_pin\", // the broadcast is pinned to the chain\n    \"author\": \"0x0a65365587a65ce44938eab5a765fe8bc6532bdf\", // the local identity\n    \"created\": \"2021-07-01T21:06:26.9997478Z\", // the time the broadcast was sent\n    \"namespace\": \"ff_system\", // the data/message broadcast happens on the system namespace\n    \"topic\": [\n      \"ff_ns_default\" // the namespace itself is used in the topic\n    ],\n    \"tag\": \"ff_define_datatype\", // a tag instructing FireFly to process this as a datatype definition\n    \"datahash\": \"56bd677e3e070ba62f547237edd7a90df5deaaf1a42e7d6435ec66a587c14370\"\n  },\n  \"hash\": \"5b6593720243831ba9e4ad002c550e95c63704b2c9dbdf31135d7d9207f8cae8\",\n  \"state\": \"ready\", // this message is stored locally but not yet confirmed\n  \"data\": [\n    {\n      \"id\": \"7539a0ab-78d8-4d42-b283-7e316b3afed3\", // this data object in the ff_system namespace, contains the schema\n      \"hash\": \"22ba1cdf84f2a4aaffac665c83ff27c5431c0004dc72a9bf031ae35a75ac5aef\"\n    }\n  ]\n}\n</code></pre>"},{"location":"tutorials/define_datatype/#lookup-the-confirmed-data-type","title":"Lookup the confirmed data type","text":"<p><code>GET</code> <code>/api/v1/namespaces/default/datatypes?name=widget&amp;version=0.0.2</code></p> <pre><code>[\n  {\n    \"id\": \"421c94b1-66ce-4ba0-9794-7e03c63df29d\", // an ID allocated to the datatype\n    \"message\": \"727f7d3a-d07e-4e80-95af-59f8d2ac7531\", // the message that broadcast this data type\n    \"validator\": \"json\", // the type of validator that this datatype can be used for (this one is JSON Schema)\n    \"namespace\": \"default\", // the namespace of the datatype\n    \"name\": \"widget\", // the name of the datatype\n    \"version\": \"0.0.2\", // the version of the data type\n    \"hash\": \"a4dceb79a21937ca5ea9fa22419011ca937b4b8bc563d690cea3114af9abce2c\", // hash of the schema itself\n    \"created\": \"2021-07-01T21:06:26.983986Z\", // time it was confirmed\n    \"value\": {\n      // the JSON schema itself\n      \"$id\": \"https://example.com/widget.schema.json\",\n      \"$schema\": \"https://json-schema.org/draft/2020-12/schema\",\n      \"title\": \"Widget\",\n      \"type\": \"object\",\n      \"properties\": {\n        \"id\": {\n          \"type\": \"string\",\n          \"description\": \"The unique identifier for the widget.\"\n        },\n        \"name\": {\n          \"type\": \"string\",\n          \"description\": \"The person's last name.\"\n        }\n      }\n    }\n  }\n]\n</code></pre>"},{"location":"tutorials/define_datatype/#example-private-send-referring-to-the-datatype","title":"Example private send referring to the datatype","text":"<p>Once confirmed, a piece of data can be assigned that datatype and all FireFly nodes will verify it against the schema. On a sending node, the data will be rejected at upload/send time if it does not conform. On other nodes, bad data results in a <code>message_rejected</code> event (rather than <code>message_confirmed</code>) for any message that arrives referring to that data.</p> <p><code>POST</code> <code>/api/v1/namespaces/default/send/message</code></p> <pre><code>{\n  \"header\": {\n    \"tag\": \"new_widget_created\",\n    \"topic\": [\"widget_id_12345\"]\n  },\n  \"group\": {\n    \"members\": [\n      {\n        \"identity\": \"org_1\"\n      }\n    ]\n  },\n  \"data\": [\n    {\n      \"datatype\": {\n        \"name\": \"widget\",\n        \"version\": \"0.0.2\"\n      },\n      \"value\": {\n        \"id\": \"widget_id_12345\",\n        \"name\": \"superwidget\"\n      }\n    }\n  ]\n}\n</code></pre>"},{"location":"tutorials/define_datatype/#defining-datatypes-using-the-sandbox","title":"Defining Datatypes using the Sandbox","text":"<p>You can also define a datatype through the FireFly Sandbox.</p> <p>To get started, open up the Web UI and Sanbox UI for at least one of your members. The URLs for these were printed in your terminal when you started your FireFly stack.</p> <p>In the sandbox, enter the datatype's name, version, and JSON Schema as seen in the screenshot below.</p> <pre><code>{\n  \"name\": \"widget\",\n  \"version\": \"0.0.2\",\n  \"value\": {\n    \"$id\": \"https://example.com/widget.schema.json\",\n    \"$schema\": \"https://json-schema.org/draft/2020-12/schema\",\n    \"title\": \"Widget\",\n    \"type\": \"object\",\n    \"properties\": {\n      \"id\": {\n        \"type\": \"string\",\n        \"description\": \"The unique identifier for the widget.\"\n      },\n      \"name\": {\n        \"type\": \"string\",\n        \"description\": \"The person's last name.\"\n      }\n    }\n  }\n}\n</code></pre> <p></p> <p>Notice how the <code>data</code> field in the center panel updates in real time.</p> <p>Click the blue <code>Run</code> button. This should return a <code>202</code> response immediately in the Server Response section and will populate the right hand panel with transaction information after a few seconds.</p> <p></p> <p>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 that you've successfully defined your datatype</p> <p></p>"},{"location":"tutorials/events/","title":"Listen for events","text":""},{"location":"tutorials/events/#quick-reference","title":"Quick reference","text":"<p>Probably the most important aspect of FireFly is that it is an event-driven programming model.</p> <p>Parties interact by sending messages and transactions to each other, on and off chain. Once aggregated and confirmed those events drive processing in the other party.</p> <p>This allows orchestration of complex multi-party system applications and business processes.</p> <p>FireFly provides each party with their own private history, that includes all exchanges outbound and inbound performed through the node into the multi-party system. That includes blockchain backed transactions, as well as completely off-chain message exchanges.</p> <p>The event transports are pluggable. The core transports are WebSockets and Webhooks. We focus on WebSockets in this getting started guide.</p> <p>Check out the Request/Reply section for more information on Webhooks</p>"},{"location":"tutorials/events/#additional-info","title":"Additional info","text":"<ul> <li>Key Concepts: Multi-party process flow</li> <li>Reference: coming soon</li> </ul>"},{"location":"tutorials/events/#websockets-example-1-ephemeral-subscription-with-auto-commit","title":"WebSockets Example 1: Ephemeral subscription with auto-commit","text":"<p>The simplest way to get started consuming events, is with an ephemeral WebSocket listener.</p> <p>Example connection URL:</p> <p><code>ws://localhost:5000/ws?namespace=default&amp;ephemeral&amp;autoack&amp;filter.events=message_confirmed</code></p> <ul> <li><code>namespace=default</code> - event listeners are scoped to a namespace</li> <li><code>ephemeral</code> - listen for events that occur while this connection is active, but do not remember the app instance (great for UIs)</li> <li><code>autoack</code>- automatically acknowledge each event, so the next event is sent (great for UIs)</li> <li><code>filter.events=message_confirmed</code> - only listen for events resulting from a message confirmation</li> </ul> <p>There are a number of browser extensions that let you experiment with WebSockets:</p> <p></p>"},{"location":"tutorials/events/#example-event-payload","title":"Example event payload","text":"<p>The events (by default) do not contain the payload data, just the <code>event</code> and referred <code>message</code>. This means the WebSocket payloads are a predictably small size, and the application can use the information in the <code>message</code> to post-filter the event to decide if it needs to download the full data.</p> <p>There are server-side filters provided on events as well</p> <pre><code>{\n  \"id\": \"8f0da4d7-8af7-48da-912d-187979bf60ed\",\n  \"sequence\": 61,\n  \"type\": \"message_confirmed\",\n  \"namespace\": \"default\",\n  \"reference\": \"9710a350-0ba1-43c6-90fc-352131ce818a\",\n  \"created\": \"2021-07-02T04:37:47.6556589Z\",\n  \"subscription\": {\n    \"id\": \"2426c5b1-ffa9-4f7d-affb-e4e541945808\",\n    \"namespace\": \"default\",\n    \"name\": \"2426c5b1-ffa9-4f7d-affb-e4e541945808\"\n  },\n  \"message\": {\n    \"header\": {\n      \"id\": \"9710a350-0ba1-43c6-90fc-352131ce818a\",\n      \"type\": \"broadcast\",\n      \"txtype\": \"batch_pin\",\n      \"author\": \"0x1d14b65d2dd5c13f6cb6d3dc4aa13c795a8f3b28\",\n      \"created\": \"2021-07-02T04:37:40.1257944Z\",\n      \"namespace\": \"default\",\n      \"topic\": [\"default\"],\n      \"datahash\": \"cd6a09a15ccd3e6ed1d67d69fa4773b563f27f17f3eaad611a2792ba945ca34f\"\n    },\n    \"hash\": \"1b6808d2b95b418e54e7bd34593bfa36a002b841ac42f89d00586dac61e8df43\",\n    \"batchID\": \"16ffc02c-8cb0-4e2f-8b58-a707ad1d1eae\",\n    \"state\": \"confirmed\",\n    \"confirmed\": \"2021-07-02T04:37:47.6548399Z\",\n    \"data\": [\n      {\n        \"id\": \"b3a814cc-17d1-45d5-975e-90279ed2c3fc\",\n        \"hash\": \"9ddefe4435b21d901439e546d54a14a175a3493b9fd8fbf38d9ea6d3cbf70826\"\n      }\n    ]\n  }\n}\n</code></pre>"},{"location":"tutorials/events/#download-the-message-and-data","title":"Download the message and data","text":"<p>A simple REST API is provided to allow you to download the data associated with the message:</p> <p><code>GET</code> <code>/api/v1/namespaces/default/messages/{id}?data=true</code></p>"},{"location":"tutorials/events/#download-just-the-data-array-associated-with-a-message","title":"Download just the data array associated with a message","text":"<p>As you already have the message object in the event delivery, you can query just the array of data objects as follows:</p> <p><code>GET</code> <code>/api/v1/namespaces/default/messages/{id}/data</code></p>"},{"location":"tutorials/events/#websockets-example-2-durable-subscription-for-your-application-with-manual-commit","title":"WebSockets Example 2: Durable subscription for your application, with manual-commit","text":"<p>To reliably process messages within your application, you should first set up a subscription.</p> <p>A subscription requests that:</p> <ul> <li>FireFly keeps a record of the latest event consumed by that application</li> <li>FireFly only delivers one copy of the event to the application, even when there are multiple active connections</li> </ul> <p>This should be combined with manual acknowledgment of the events, where the application sends a payload such as the following in response to each event it receives (where the <code>id</code> comes from the event it received):</p> <pre><code>{ \"type\": \"ack\", \"id\": \"617db63-2cf5-4fa3-8320-46150cbb5372\" }\n</code></pre> <p>You must send an acknowledgement for every message, or you will stop receiving messages.</p>"},{"location":"tutorials/events/#set-up-the-websocket-subscription","title":"Set up the WebSocket subscription","text":"<p>Each subscription is scoped to a namespace, and must have a <code>name</code>. You can then choose to perform server-side filtering on the events using regular expressions matched against the information in the event.</p> <p><code>POST</code> <code>/namespaces/default/subscriptions</code></p> <pre><code>{\n  \"transport\": \"websockets\",\n  \"name\": \"app1\",\n  \"filter\": {\n    \"blockchainevent\": {\n      \"listener\": \".*\",\n      \"name\": \".*\"\n    },\n    \"events\": \".*\",\n    \"message\": {\n      \"author\": \".*\",\n      \"group\": \".*\",\n      \"tag\": \".*\",\n      \"topics\": \".*\"\n    },\n    \"transaction\": {\n      \"type\": \".*\"\n    }\n  },\n  \"options\": {\n    \"firstEvent\": \"newest\",\n    \"readAhead\": 50\n  }\n}\n</code></pre>"},{"location":"tutorials/events/#connect-to-consume-messages","title":"Connect to consume messages","text":"<p>Example connection URL:</p> <p><code>ws://localhost:5000/ws?namespace=default&amp;name=app1</code></p> <ul> <li><code>namespace=default</code> - event listeners are scoped to a namespace</li> <li><code>name=app1</code> - the subscription name</li> </ul>"},{"location":"tutorials/events/#custom-contract-events","title":"Custom Contract Events","text":"<p>If you are interested in learning more about events for custom smart contracts, please see the Working with custom smart contracts section.</p>"},{"location":"tutorials/private_send/","title":"Privately send data","text":""},{"location":"tutorials/private_send/#quick-reference","title":"Quick reference","text":"<ul> <li>Sends a <code>message</code> to a restricted set of parties</li> <li>The message describes who sent it, to whom, and exactly what data was sent</li> <li>A <code>message</code> has one or more attached pieces of business <code>data</code></li> <li>Can be sent in-line, uploaded in advanced, or received from other parties</li> <li>Can include smaller JSON payloads suitable for database storage<ul> <li>These can be verified against a <code>datatype</code></li> </ul> </li> <li>Can include references to large (multi megabyte/gigabyte) Blob data</li> <li>A <code>group</code> specifies who has visibility to the data</li> <li>The author must be included in the group - auto-added if omitted</li> <li>Can be specified in-line in the message by listing recipients directly</li> <li>Can be referred to by hash</li> <li>Private sends are optionally sequenced via pinning to the blockchain</li> <li>If the send is pinned:<ul> <li>The blockchain does not contain any data, just a hash pin</li> <li>Even the ordering context (topic) is obscured in the on-chain data</li> <li>This is true regardless of whether a restricted set of participants     are maintaining the ledger, such as in the case of a Fabric Channel.</li> <li>The message should not be considered confirmed (even by the sender) until it   has been sequenced via the blockchain and a <code>message_confirmed</code> event occurs</li> <li>Batched for efficiency</li> <li>One <code>batch</code> can pin hundreds of private <code>message</code> sends</li> <li>The batch flows privately off-chain from the sender to each recipient</li> </ul> </li> <li>If the send is unpinned:<ul> <li>No data is written to the blockchain at all</li> <li>The message is marked confirmed immediately</li> <li>The sender receives a <code>message_confirmed</code> event immediately</li> <li>The other parties in the group get <code>message_confirmed</code> events as soon as the data arrives</li> </ul> </li> </ul>"},{"location":"tutorials/private_send/#additional-info","title":"Additional info","text":"<ul> <li>Key Concepts: Private data exchange</li> <li>Swagger: POST /api/v1/namespaces/{ns}/messages/private</li> </ul>"},{"location":"tutorials/private_send/#example-1-pinned-private-send-of-in-line-string-data","title":"Example 1: Pinned private send of in-line string data","text":"<p><code>POST</code> <code>/api/v1/namespaces/default/messages/private</code></p> <pre><code>{\n  \"data\": [\n    {\n      \"value\": \"a string\"\n    }\n  ],\n  \"group\": {\n    \"members\": [\n      {\n        \"identity\": \"org_1\"\n      }\n    ]\n  }\n}\n</code></pre>"},{"location":"tutorials/private_send/#example-message-response","title":"Example message response","text":"<p>Status: <code>202 Accepted</code> - the message is on it's way, but has not yet been confirmed.</p> <pre><code>{\n  \"header\": {\n    \"id\": \"c387e9d2-bdac-44cc-9dd5-5e7f0b6b0e58\", // uniquely identifies this private message\n    \"type\": \"private\", // set automatically\n    \"txtype\": \"batch_pin\", // message will be batched, and sequenced via the blockchain\n    \"author\": \"0x0a65365587a65ce44938eab5a765fe8bc6532bdf\", // set automatically in this example to the node org\n    \"created\": \"2021-07-02T02:37:13.4642085Z\", // set automatically\n    \"namespace\": \"default\", // the 'default' namespace was set in the URL\n    // The group hash is calculated from the resolved list of group participants.\n    // The first time a group is used, the participant list is sent privately along with the\n    // batch of messages in a `groupinit` message.\n    \"group\": \"2aa5297b5eed0c3a612a667c727ca38b54fb3b5cc245ebac4c2c7abe490bdf6c\",\n    \"topics\": [\n      \"default\" // the default topic that the message is published on, if no topic is set\n    ],\n    // datahash is calculated from the data array below\n    \"datahash\": \"24b2d583b87eda952fa00e02c6de4f78110df63218eddf568f0240be3d02c866\"\n  },\n  \"hash\": \"423ad7d99fd30ff679270ad2b6b35cdd85d48db30bafb71464ca1527ce114a60\", // hash of the header\n  \"state\": \"ready\", // this message is stored locally but not yet confirmed\n  \"data\": [\n    // one item of data was stored\n    {\n      \"id\": \"8d8635e2-7c90-4963-99cc-794c98a68b1d\", // can be used to query the data in the future\n      \"hash\": \"c95d6352f524a770a787c16509237baf7eb59967699fb9a6d825270e7ec0eacf\" // sha256 hash of `\"a string\"`\n    }\n  ]\n}\n</code></pre>"},{"location":"tutorials/private_send/#example-2-unpinned-private-send-of-in-line-string-data","title":"Example 2: Unpinned private send of in-line string data","text":"<p>Set <code>header.txtype: \"none\"</code> to disable pinning of the private message send to the blockchain. The message is sent immediately (no batching) over the private data exchange.</p> <p><code>POST</code> <code>/api/v1/namespaces/default/messages/private</code></p> <pre><code>{\n  \"header\": {\n    \"txtype\": \"none\"\n  },\n  \"data\": [\n    {\n      \"value\": \"a string\"\n    }\n  ],\n  \"group\": {\n    \"members\": [\n      {\n        \"identity\": \"org_1\"\n      }\n    ]\n  }\n}\n</code></pre>"},{"location":"tutorials/private_send/#example-3-inline-object-data-to-a-topic-no-datatype-verification","title":"Example 3: Inline object data to a topic (no datatype verification)","text":"<p>It is very good practice to set a <code>tag</code> and <code>topic</code> in each of your messages:</p> <ul> <li><code>tag</code> should tell the apps receiving the private send (including the local app), what   to do when it receives the message. Its the reason for the send - an   application specific type for the message.</li> <li><code>topic</code> should be something like a well known identifier that relates to the   information you are publishing. It is used as an ordering context, so all   sends on a given topic are assured to be processed in order.</li> </ul> <p><code>POST</code> <code>/api/v1/namespaces/default/messages/private</code></p> <pre><code>{\n  \"header\": {\n    \"tag\": \"new_widget_created\",\n    \"topics\": [\"widget_id_12345\"]\n  },\n  \"group\": {\n    \"members\": [\n      {\n        \"identity\": \"org_1\"\n      }\n    ]\n  },\n  \"data\": [\n    {\n      \"value\": {\n        \"id\": \"widget_id_12345\",\n        \"name\": \"superwidget\"\n      }\n    }\n  ]\n}\n</code></pre>"},{"location":"tutorials/private_send/#notes-on-why-setting-a-topic-is-important","title":"Notes on why setting a topic is important","text":"<p>The FireFly aggregator uses the <code>topic</code> (obfuscated on chain) to determine if a message is the next message in an in-flight sequence for any groups the node is involved in. If it is, then that message must receive all off-chain private data and be confirmed before any subsequent messages can be confirmed on the same sequence.</p> <p>So if you use the same topic in every message, then a single failed send on one topic blocks delivery of all messages between those parties, until the missing data arrives.</p> <p>Instead it is best practice to set the topic on your messages to value that identifies an ordered stream of business processing. Some examples:</p> <ul> <li>A long-running business process instance identifier assigned at initiation</li> <li>A real-world business transaction identifier used off-chain</li> <li>The agreed identifier of an asset you are attaching a stream of evidence to</li> <li>An NFT identifier that is assigned to an asset (digital twin scenarios)</li> <li>An agreed primary key for a data resource being reconciled between multiple parties</li> </ul> <p>The <code>topic</code> field is an array, because there are cases (such as merging two identifiers) where you need a message to be deterministically ordered across multiple sequences. However, this is an advanced use case and you are likely to set a single topic on the vast majority of your messages.</p>"},{"location":"tutorials/private_send/#example-3-upload-a-blob-with-metadata-and-send-privately","title":"Example 3: Upload a blob with metadata and send privately","text":"<p>Here we make two API calls.</p> <ol> <li> <p>Create the <code>data</code> object explicitly, using a multi-part form upload</p> </li> <li> <p>You can also just post JSON to this endpoint</p> </li> <li> <p>Privately send a message referring to that data</p> </li> <li> <p>The Blob is sent privately to each party</p> </li> <li>A pin goes to the blockchain</li> <li>The metadata goes into a batch with the message</li> </ol>"},{"location":"tutorials/private_send/#multipart-form-post-of-a-file","title":"Multipart form post of a file","text":"<p>Example curl command (Linux/Mac) to grab an image from the internet, and pipe it into a multi-part form post to FireFly.</p> <p>Note we use <code>autometa</code> to cause FireFly to automatically add the <code>filename</code>, and <code>size</code>, to the JSON part of the <code>data</code> object for us.</p> <pre><code>curl -sLo - https://github.com/hyperledger/firefly/raw/main/docs/firefly_logo.png \\\n | curl --form autometa=true --form file=@- \\\n   http://localhost:5000/api/v1/namespaces/default/data\n</code></pre>"},{"location":"tutorials/private_send/#example-data-response-from-blob-upload","title":"Example data response from Blob upload","text":"<p>Status: <code>200 OK</code> - your data is uploaded to your local FireFly node</p> <p>At this point the data has not be shared with anyone else in the network</p> <pre><code>{\n  // A uniquely generated ID, we can refer to when sending this data to other parties\n  \"id\": \"97eb750f-0d0b-4c1d-9e37-1e92d1a22bb8\",\n  \"validator\": \"json\", // the \"value\" part is JSON\n  \"namespace\": \"default\", // from the URL\n  // The hash is a combination of the hash of the \"value\" metadata, and the\n  // hash of the blob\n  \"hash\": \"997af6a9a19f06cc8a46872617b8bf974b106f744b2e407e94cc6959aa8cf0b8\",\n  \"created\": \"2021-07-01T20:20:35.5462306Z\",\n  \"value\": {\n    \"filename\": \"-\", // dash is how curl represents the filename for stdin\n    \"size\": 31185 // the size of the blob data\n  },\n  \"blob\": {\n    // A hash reference to the blob\n    \"hash\": \"86e6b39b04b605dd1b03f70932976775962509d29ae1ad2628e684faabe48136\"\n  }\n}\n</code></pre>"},{"location":"tutorials/private_send/#send-the-uploaded-data-privately","title":"Send the uploaded data privately","text":"<p>Just include a reference to the <code>id</code> returned from the upload.</p> <p><code>POST</code> <code>/api/v1/namespaces/default/messages/private</code></p> <pre><code>{\n  \"data\": [\n    {\n      \"id\": \"97eb750f-0d0b-4c1d-9e37-1e92d1a22bb8\"\n    }\n  ],\n  \"group\": {\n    \"members\": [\n      {\n        \"identity\": \"org_1\"\n      }\n    ]\n  }\n}\n</code></pre>"},{"location":"tutorials/private_send/#sending-private-messages-using-the-sandbox","title":"Sending Private Messages using the Sandbox","text":"<p>All of the functionality discussed above can be done through the FireFly Sandbox.</p> <p>To get started, open up the Web UI and Sanbox UI for at least one of your members. The URLs for these were printed in your terminal when you started your FireFly stack.</p> <p>Make sure to expand the \"Send a Private Message\" section. Enter your message into the message field as seen in the screenshot below. Because we are sending a private message, make sure you're in the \"Send a Private Message\" section and that you choose a message recipient</p> <p></p> <p>Notice how the <code>data</code> field in the center panel updates in real time as you update the message you wish to send.</p> <p>Click the blue <code>Run</code> button. This should return a <code>202</code> response immediately in the Server Response section and will populate the right hand panel with transaction information after a few seconds.</p> <p></p> <p>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</p> <p></p>"},{"location":"tutorials/query_messages/","title":"Explore messages","text":""},{"location":"tutorials/query_messages/#quick-reference","title":"Quick reference","text":"<p>The FireFly Explorer is a great way to view the messages sent and received by your node.</p> <p>Just open <code>/ui</code> on your FireFly node to access it.</p> <p></p> <p>This builds on the APIs to query and filter messages, described below</p>"},{"location":"tutorials/query_messages/#additional-info","title":"Additional info","text":"<ul> <li>Reference: API Query Syntax</li> <li>Swagger: GET /api/v1/namespaces/{ns}/messages</li> </ul>"},{"location":"tutorials/query_messages/#example-1-query-confirmed-messages","title":"Example 1: Query confirmed messages","text":"<p>These are the messages ready to be processed in your application. All data associated with the message (including Blob attachments) is available, and if they are sequenced by the blockchain, then those blockchain transactions are complete.</p> <p>The order in which you process messages should be determined by absolute order of <code>message_confirmed</code> events - queryable via the <code>events</code> collection, or through event listeners (discussed next in the getting started guide).</p> <p>That is because <code>messages</code> are ordered by timestamp, which is potentially subject to adjustments of the clock. Whereas <code>events</code> are ordered by the insertion order into the database, and as such changes in the clock do not affect the order.</p> <p><code>GET</code> <code>/api/v1/namespaces/{ns}/messages?pending=false&amp;limit=100</code></p>"},{"location":"tutorials/query_messages/#example-response","title":"Example response","text":"<pre><code>[\n  {\n    \"header\": {\n      \"id\": \"423302bb-abfc-4d64-892d-38b2fdfe1549\",\n      \"type\": \"private\", // this was a private send\n      \"txtype\": \"batch_pin\", // pinned in a batch to the blockchain\n      \"author\": \"0x1d14b65d2dd5c13f6cb6d3dc4aa13c795a8f3b28\",\n      \"created\": \"2021-07-02T03:09:40.2606238Z\",\n      \"namespace\": \"default\",\n      \"group\": \"2aa5297b5eed0c3a612a667c727ca38b54fb3b5cc245ebac4c2c7abe490bdf6c\", // sent to this group\n      \"topic\": [\"widget_id_12345\"],\n      \"tag\": \"new_widget_created\",\n      \"datahash\": \"551dd261e80ce76b1908c031cff8a707bd76376d6eddfdc1040c2ed6481ec8dd\"\n    },\n    \"hash\": \"bf2ca94db8c31bae3cae974bb626fa822c6eee5f572d274d72281e72537b30b3\",\n    \"batch\": \"f7ac773d-885a-4d73-ac6b-c09f5346a051\", // the batch ID that pinned this message to the chain\n    \"state\": \"confirmed\", // message is now confirmed\n    \"confirmed\": \"2021-07-02T03:09:49.9207211Z\", // timestamp when this node confirmed the message\n    \"data\": [\n      {\n        \"id\": \"914eed77-8789-451c-b55f-ba9570a71eba\",\n        \"hash\": \"9541cabc750c692e553a421a6c5c07ebcae820774d2d8d0b88fac2a231c10bf2\"\n      }\n    ],\n    \"pins\": [\n      // A \"pin\" is an identifier that is used by FireFly for sequencing messages.\n      //\n      // For private messages, it is an obfuscated representation of the sequence of this message,\n      // on a topic, within this group, from this sender. There will be one pin per topic. You will find these\n      // pins in the blockchain transaction, as well as the off-chain data.\n      // Each one is unqiue, and without the group hash, very difficult to correlate - meaning\n      // the data on-chain provides a high level of privacy.\n      //\n      // Note for broadcast (which does not require obfuscation), it is simply a hash of the topic.\n      // So you will see the same pin for all messages on the same topic.\n      \"ee56de6241522ab0ad8266faebf2c0f1dc11be7bd0c41d847998135b45685b77\"\n    ]\n  }\n]\n</code></pre>"},{"location":"tutorials/query_messages/#example-2-query-all-messages","title":"Example 2: Query all messages","text":"<p>The natural sort order the API will return for messages is:</p> <ul> <li>Pending messages first</li> <li>In descending <code>created</code> timestamp order</li> <li>Confirmed messages</li> <li>In descending <code>confirmed</code> timestamp order</li> </ul> <p><code>GET</code> <code>/api/v1/namespaces/{ns}/messages</code></p>"},{"location":"tutorials/rotate_dx_certs/","title":"Rotate DX Certs","text":""},{"location":"tutorials/rotate_dx_certs/#quick-reference","title":"Quick reference","text":"<p>At some point you may need to rotate certificates on your Data Exchange nodes. FireFly provides an API to update a node identity, but there are a few prerequisite steps to load a new certificate on the Data Exchange node itself. This guide will walk you through that process. For more information on different types of identities in FireFly, please see the Reference page on Identities.</p> <p>NOTE: This guide assumes that you are working in a local development environment that was set up with the Getting Started Guide. For a production deployment, the exact process to accomplish each step may be different. For example, you may generate your certs with a CA, or in some other manner. But the high level steps remain the same.</p> <p>The high level steps to the process (described in detail below) are:</p> <ul> <li>Generate new certs and keys</li> <li>Install new certs and keys on each Data Exchange filesystem</li> <li>Remove old certs from the <code>peer-certs</code> directory</li> <li>Restart each Data Exchange process</li> <li><code>PATCH</code> the node identity using the FireFly API</li> </ul>"},{"location":"tutorials/rotate_dx_certs/#generate-new-certs-and-keys","title":"Generate new certs and keys","text":"<p>To generate a new cert, we're going to use a self signed certificate generated by <code>openssl</code>. This is how the FireFly CLI generated the original cert that was used when it created your stack.</p> <p>For the first member of a FireFly stack you run:</p> <pre><code>openssl req -new -x509 -nodes -days 365 -subj /CN=dataexchange_0/O=member_0 -keyout key.pem -out cert.pem\n</code></pre> <p>For the second member:</p> <pre><code>openssl req -new -x509 -nodes -days 365 -subj /CN=dataexchange_1/O=member_1 -keyout key.pem -out cert.pem\n</code></pre> <p>NOTE: If you perform these two commands in the same directory, the second one will overwrite the output of the first. It is advisable to run them in separate directories, or copy the cert and key to the Data Exchange file system (the next step below) before generating the next cert / key pair.</p>"},{"location":"tutorials/rotate_dx_certs/#install-the-new-certs-on-each-data-exchange-file-system","title":"Install the new certs on each Data Exchange File System","text":"<p>For a dev environment created with the FireFly CLI, the certificate and key will be located in the <code>/data</code> directory on the Data Exchange node's file system. You can use the <code>docker cp</code> command to copy the file to the correct location, then set the file ownership correctly.</p> <pre><code>docker cp cert.pem dev_dataexchange_0:/data/cert.pem\ndocker exec dev_dataexchange_0 chown root:root /data/cert.pem\n</code></pre> <p>NOTE: If your environment is not called <code>dev</code> you may need to change the beginning of the container name in the Docker commands listed in this guide.</p>"},{"location":"tutorials/rotate_dx_certs/#remove-old-certs-from-the-peer-certs-directory","title":"Remove old certs from the <code>peer-certs</code> directory","text":"<p>To clear out the old certs from the first Data Exchange node run:</p> <pre><code>docker exec dev_dataexchange_0 sh -c \"rm /data/peer-certs/*.pem\"\n</code></pre> <p>To clear out the old certs from the second Data Exchange node run:</p> <pre><code>docker exec dev_dataexchange_1 sh -c \"rm /data/peer-certs/*.pem\"\n</code></pre>"},{"location":"tutorials/rotate_dx_certs/#restart-each-data-exchange-process","title":"Restart each Data Exchange process","text":"<p>To restart your Data Exchange processes, run:</p> <pre><code>docker restart dev_dataexchange_0\n</code></pre> <pre><code>docker restart dev_dataexchange_1\n</code></pre>"},{"location":"tutorials/rotate_dx_certs/#patch-the-node-identity-using-the-firefly-api","title":"<code>PATCH</code> the node identity using the FireFly API","text":"<p>The final step is to broadcast the new cert for each node, from the FireFly node that will be using that cert. You will need to lookup the UUID for the node identity in order to update it.</p>"},{"location":"tutorials/rotate_dx_certs/#request","title":"Request","text":"<p><code>GET</code> <code>http://localhost:5000/api/v1/namespaces/default/identities</code></p>"},{"location":"tutorials/rotate_dx_certs/#response","title":"Response","text":"<p>In the JSON response body, look for the node identity that belongs on this FireFly instance. Here is the node identity from an example stack:</p> <pre><code>...\n    {\n        \"id\": \"20da74a2-d4e6-4eaf-8506-e7cd205d8254\",\n        \"did\": \"did:firefly:node/node_2b9630\",\n        \"type\": \"node\",\n        \"parent\": \"41e93d92-d0da-4e5a-9cee-adf33f017a60\",\n        \"namespace\": \"default\",\n        \"name\": \"node_2b9630\",\n        \"profile\": {\n            \"cert\": \"-----BEGIN CERTIFICATE-----\\nMIIC1DCCAbwCCQDa9x3wC7wepDANBgkqhkiG9w0BAQsFADAsMRcwFQYDVQQDDA5k\\nYXRhZXhjaGFuZ2VfMDERMA8GA1UECgwIbWVtYmVyXzAwHhcNMjMwMjA2MTQwMTEy\\nWhcNMjQwMjA2MTQwMTEyWjAsMRcwFQYDVQQDDA5kYXRhZXhjaGFuZ2VfMDERMA8G\\nA1UECgwIbWVtYmVyXzAwggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQDJ\\nSgtJw99V7EynvqxWdJkeiUlOg3y+JtJlhxGC//JLp+4sYCtOMriULNf5ouImxniR\\nO2vEd+LNdMuREN4oZdUHtJD4MM7lOFw/0ICNEPJ+oEoUTzOC0OK68sA+OCybeS2L\\nmLBu4yvWDkpufR8bxBJfBGarTAFl36ao1Eoogn4m9gmVrX+V5SOKUhyhlHZFkZNb\\ne0flwQmDMKg6qAbHf3j8cnrrZp26n68IGjwqySPFIRLFSz28zzMYtyzo4b9cF9NW\\nGxusMHsExX5gzlTjNacGx8Tlzwjfolt23D+WHhZX/gekOsFiV78mVjgJanE2ls6D\\n5ZlXi5iQSwm8dlmo9RxFAgMBAAEwDQYJKoZIhvcNAQELBQADggEBAAwr4aAvQnXG\\nkO3xNO+7NGzbb/Nyck5udiQ3RmlZBEJSUsPCsWd4SBhH7LvgbT9ECuAEjgH+2Ip7\\nusd8CROr3sTb9t+7Krk+ljgZirkjq4j/mIRlqHcBJeBtylOz2p0oPsitlI8Yea2D\\nQ4/Xru6txUKNK+Yut3G9qvg/vm9TAwkNHSthzb26bI7s6lx9ZSuFbbG6mR+RQ+8A\\nU4AX1DVo5QyTwSi1lp0+pKFEgtutmWGYn8oT/ya+OLzj+l7Ul4HE/mEAnvECtA7r\\nOC8AEjC5T4gUsLt2IXW9a7lCgovjHjHIySQyqsdYBjkKSn5iw2LRovUWxT1GBvwH\\nFkTvCpHhgko=\\n-----END CERTIFICATE-----\\n\",\n            \"endpoint\": \"https://dataexchange_0:3001\",\n            \"id\": \"member_0/node_2b9630\"\n        },\n        \"messages\": {\n            \"claim\": \"95da690b-bb05-4873-9478-942f607f363a\",\n            \"verification\": null,\n            \"update\": null\n        },\n        \"created\": \"2023-02-06T14:02:50.874319382Z\",\n        \"updated\": \"2023-02-06T14:02:50.874319382Z\"\n    },\n...\n</code></pre> <p>Copy the UUID from the <code>id</code> field, and add that to the <code>PATCH</code> request. In this case it is <code>20da74a2-d4e6-4eaf-8506-e7cd205d8254</code>.</p>"},{"location":"tutorials/rotate_dx_certs/#request_1","title":"Request","text":"<p>Now we will send the new certificate to FireFly. Put the contents of your <code>cert.pem</code> file in the <code>cert</code> field.</p> <p>NOTE: Usually the <code>cert.pem</code> file will contain line breaks which will not be handled correctly by JSON parsers. Be sure to replace those line breaks with <code>\\n</code> so that the <code>cert</code> field is all on one line as shown below.</p> <p><code>PATCH</code> <code>http://localhost:5000/api/v1/namespaces/default/identities/20da74a2-d4e6-4eaf-8506-e7cd205d8254</code></p> <pre><code>{\n  \"profile\": {\n    \"cert\": \"-----BEGIN CERTIFICATE-----\\nMIIC1DCCAbwCCQDeKjPt3siRHzANBgkqhkiG9w0BAQsFADAsMRcwFQYDVQQDDA5k\\nYXRhZXhjaGFuZ2VfMDERMA8GA1UECgwIbWVtYmVyXzAwHhcNMjMwMjA2MTYxNTU3\\nWhcNMjQwMjA2MTYxNTU3WjAsMRcwFQYDVQQDDA5kYXRhZXhjaGFuZ2VfMDERMA8G\\nA1UECgwIbWVtYmVyXzAwggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQCy\\nEJaqDskxhkPHmCqj5Mxq+9QX1ec19fulh9Zvp8dLA6bfeg4fdQ9Ha7APG6w/0K8S\\nEaXOflSpXb0oKMe42amIqwvQaqTOA97HIe5R2HZxA1RWqXf+AueowWgI4crxr2M0\\nZCiXHyiZKpB8nzO+bdO9AKeYnzbhCsO0gq4LPOgpPjYkHPKhabeMVZilZypDVOGk\\nLU+ReQoVEZ+P+t0B/9v+5IQ2yyH41n5dh6lKv4mIaC1OBtLc+Pd6DtbRb7pijkgo\\n+LyqSdl24RHhSgZcTtMQfoRIVzvMkhF5SiJczOC4R8hmt62jtWadO4D5ZtJ7N37/\\noAG/7KJO4HbByVf4xOcDAgMBAAEwDQYJKoZIhvcNAQELBQADggEBAKWbQftV05Fc\\niwVtZpyvP2l4BvKXvMOyg4GKcnBSZol7UwCNrjwYSjqgqyuedTSZXHNhGFxQbfAC\\n94H25bDhWOfd7JH2D7E6RRe3eD9ouDnrt+de7JulsNsFK23IM4Nz5mRhRMVy/5p5\\n9yrsdW+5MXKWgz9569TIjiciCf0JqB7iVPwRrQyz5gqOiPf81PlyaMDeaH9wXtra\\n/1ZRipXiGiNroSPFrQjIVLKWdmnhWKWjFXsiijdSV/5E+8dBb3t//kEZ8UWfBrc4\\nfYVuZ8SJtm2ZzBmit3HFatDlFTE8PanRf/UDALUp4p6YKJ8NE2T8g/uDE0ee1pnF\\nIDsrC1GX7rs=\\n-----END CERTIFICATE-----\\n\",\n    \"endpoint\": \"https://dataexchange_0:3001\",\n    \"id\": \"member_0\"\n  }\n}\n</code></pre>"},{"location":"tutorials/rotate_dx_certs/#response_1","title":"Response","text":"<pre><code>{\n  \"id\": \"20da74a2-d4e6-4eaf-8506-e7cd205d8254\",\n  \"did\": \"did:firefly:node/node_2b9630\",\n  \"type\": \"node\",\n  \"parent\": \"41e93d92-d0da-4e5a-9cee-adf33f017a60\",\n  \"namespace\": \"default\",\n  \"name\": \"node_2b9630\",\n  \"profile\": {\n    \"cert\": \"-----BEGIN CERTIFICATE-----\\nMIIC1DCCAbwCCQDeKjPt3siRHzANBgkqhkiG9w0BAQsFADAsMRcwFQYDVQQDDA5k\\nYXRhZXhjaGFuZ2VfMDERMA8GA1UECgwIbWVtYmVyXzAwHhcNMjMwMjA2MTYxNTU3\\nWhcNMjQwMjA2MTYxNTU3WjAsMRcwFQYDVQQDDA5kYXRhZXhjaGFuZ2VfMDERMA8G\\nA1UECgwIbWVtYmVyXzAwggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQCy\\nEJaqDskxhkPHmCqj5Mxq+9QX1ec19fulh9Zvp8dLA6bfeg4fdQ9Ha7APG6w/0K8S\\nEaXOflSpXb0oKMe42amIqwvQaqTOA97HIe5R2HZxA1RWqXf+AueowWgI4crxr2M0\\nZCiXHyiZKpB8nzO+bdO9AKeYnzbhCsO0gq4LPOgpPjYkHPKhabeMVZilZypDVOGk\\nLU+ReQoVEZ+P+t0B/9v+5IQ2yyH41n5dh6lKv4mIaC1OBtLc+Pd6DtbRb7pijkgo\\n+LyqSdl24RHhSgZcTtMQfoRIVzvMkhF5SiJczOC4R8hmt62jtWadO4D5ZtJ7N37/\\noAG/7KJO4HbByVf4xOcDAgMBAAEwDQYJKoZIhvcNAQELBQADggEBAKWbQftV05Fc\\niwVtZpyvP2l4BvKXvMOyg4GKcnBSZol7UwCNrjwYSjqgqyuedTSZXHNhGFxQbfAC\\n94H25bDhWOfd7JH2D7E6RRe3eD9ouDnrt+de7JulsNsFK23IM4Nz5mRhRMVy/5p5\\n9yrsdW+5MXKWgz9569TIjiciCf0JqB7iVPwRrQyz5gqOiPf81PlyaMDeaH9wXtra\\n/1ZRipXiGiNroSPFrQjIVLKWdmnhWKWjFXsiijdSV/5E+8dBb3t//kEZ8UWfBrc4\\nfYVuZ8SJtm2ZzBmit3HFatDlFTE8PanRf/UDALUp4p6YKJ8NE2T8g/uDE0ee1pnF\\nIDsrC1GX7rs=\\n-----END CERTIFICATE-----\\n\",\n    \"endpoint\": \"https://dataexchange_0:3001\",\n    \"id\": \"member_0\"\n  },\n  \"messages\": {\n    \"claim\": \"95da690b-bb05-4873-9478-942f607f363a\",\n    \"verification\": null,\n    \"update\": \"5782cd7c-7643-4d7f-811b-02765a7aaec5\"\n  },\n  \"created\": \"2023-02-06T14:02:50.874319382Z\",\n  \"updated\": \"2023-02-06T14:02:50.874319382Z\"\n}\n</code></pre> <p>Repeat these requests for the second member/node running on port <code>5001</code>. After that you should be back up and running with your new certs, and you should be able to send private messages again.</p>"},{"location":"tutorials/chains/arbitrum/","title":"Arbitrum","text":"<p>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.</p>"},{"location":"tutorials/chains/arbitrum/#previous-steps-install-the-firefly-cli","title":"Previous steps: Install the FireFly CLI","text":"<p>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.</p> <p>\u2190 \u2460 Install the FireFly CLI</p>"},{"location":"tutorials/chains/arbitrum/#create-an-evmconnectyml-config-file","title":"Create an <code>evmconnect.yml</code> config file","text":"<p>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 <code>evmconnect.yml</code> with the following contents:</p> <pre><code>confirmations:\n  required: 4 # choose the number of confirmations you require\npolicyengine.simple:\n  fixedGasPrice: null\n  gasOracle:\n    mode: connector\n</code></pre> <p>For more info about <code>confirmations</code>, see Public vs. Permissioned</p> <p>For this tutorial, we will assume this file is saved at <code>~/Desktop/evmconnect.yml</code>. If your path is different, you will need to adjust the path in the next command below.</p>"},{"location":"tutorials/chains/arbitrum/#creating-a-new-stack","title":"Creating a new stack","text":"<p>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:</p> <ul> <li>Create a new Ethereum based stack named <code>arbitrum</code> with <code>1</code> member</li> <li>Disable <code>multiparty</code> 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</li> <li>Use an remote RPC node. This will create a signer locally, so that our signing key never leaves the development machine.</li> <li>See the Arbitrum docs and select an HTTPS RPC endpoint.</li> <li>Set the chain ID to <code>421613</code> (the correct ID for the Binance Smart Chain testnet)</li> <li>Merge the custom config created above with the generated <code>evmconnect</code> config file</li> </ul> <p>To do this, run the following command:</p> <pre><code>ff init ethereum arbitrum 1 \\\n    --multiparty=false \\\n    -n remote-rpc \\\n    --remote-node-url &lt;selected RPC endpoint&gt; \\\n    --chain-id 421613 \\\n    --connector-config ~/Desktop/evmconnect.yml\n</code></pre>"},{"location":"tutorials/chains/arbitrum/#start-the-stack","title":"Start the stack","text":"<p>Now you should be able to start your stack by running:</p> <pre><code>ff start arbitrum\n</code></pre> <p>After some time it should print out the following:</p> <pre><code>Web UI for member '0': http://127.0.0.1:5000/ui\nSandbox UI for member '0': http://127.0.0.1:5109\n\n\nTo see logs for your stack run:\n\nff logs arbitrum\n</code></pre>"},{"location":"tutorials/chains/arbitrum/#get-some-aribitrum","title":"Get some Aribitrum","text":"<p>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.</p> <p>First, you will need to know what signing address your FireFly node is using. To check that, you can run:</p> <pre><code>ff accounts list arbitrum\n[\n  {\n    \"address\": \"0x225764d1be1f137be23ddfc426b819512b5d0f3e\",\n    \"privateKey\": \"...\"\n  }\n]\n</code></pre> <p>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 and follow the instructions to send a tweet to the developers. Make sure to change the address to the one in the CLI.</p> <p></p>"},{"location":"tutorials/chains/arbitrum/#confirm-the-transaction-on-bscscan","title":"Confirm the transaction on Bscscan","text":"<p>You should be able to go lookup your account on 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.</p> <p></p>"},{"location":"tutorials/chains/arbitrum/#use-the-public-testnet","title":"Use the public testnet","text":"<p>Now that you have everything set up, you can follow one of the other FireFly guides such as Using Tokens or Custom Smart Contracts. For detailed instructions on deploying a custom smart contract to Binance Smart Chain, please see the Arbitrum docs for instructions using various tools.</p>"},{"location":"tutorials/chains/avalanche/","title":"Aavalanche","text":"<p>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.</p>"},{"location":"tutorials/chains/avalanche/#previous-steps-install-the-firefly-cli","title":"Previous steps: Install the FireFly CLI","text":"<p>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.</p> <p>\u2190 \u2460 Install the FireFly CLI</p>"},{"location":"tutorials/chains/avalanche/#create-an-evmconnectyml-config-file","title":"Create an <code>evmconnect.yml</code> config file","text":"<p>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 <code>evmconnect.yml</code> with the following contents:</p> <pre><code>confirmations:\n  required: 4 # choose the number of confirmations you require\npolicyengine.simple:\n  fixedGasPrice: null\n  gasOracle:\n    mode: connector\n</code></pre> <p>For more info about <code>confirmations</code>, see Public vs. Permissioned</p> <p>For this tutorial, we will assume this file is saved at <code>~/Desktop/evmconnect.yml</code>. If your path is different, you will need to adjust the path in the next command below.</p>"},{"location":"tutorials/chains/avalanche/#creating-a-new-stack","title":"Creating a new stack","text":"<p>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:</p> <ul> <li>Create a new Ethereum based stack named <code>avalanche</code> with <code>1</code> member</li> <li>Disable <code>multiparty</code> 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</li> <li>Use an remote RPC node. This will create a signer locally, so that our signing key never leaves the development machine.</li> <li>See the Avalanche docs and select and HTTPS RPC endpoint.</li> <li>Set the chain ID to <code>43113</code> (the correct ID for the Avalanche Fuji testnet)</li> <li>Merge the custom config created above with the generated <code>evmconnect</code> config file</li> </ul> <p>To do this, run the following command:</p> <pre><code>ff init ethereum avalanche 1 \\\n    --multiparty=false \\\n    -n remote-rpc \\\n    --remote-node-url &lt;selected RPC endpoint&gt; \\\n    --chain-id 43113 \\\n    --connector-config ~/Desktop/evmconnect.yml\n</code></pre>"},{"location":"tutorials/chains/avalanche/#start-the-stack","title":"Start the stack","text":"<p>Now you should be able to start your stack by running:</p> <pre><code>ff start avalanche\n</code></pre> <p>After some time it should print out the following:</p> <pre><code>Web UI for member '0': http://127.0.0.1:5000/ui\nSandbox UI for member '0': http://127.0.0.1:5109\n\n\nTo see logs for your stack run:\n\nff logs avalanche\n</code></pre>"},{"location":"tutorials/chains/avalanche/#get-some-avax","title":"Get some AVAX","text":"<p>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.</p> <p>First, you will need to know what signing address your FireFly node is using. To check that, you can run:</p> <pre><code>ff accounts list avalanche\n[\n  {\n    \"address\": \"0x6688e14f719766cc2a5856ccef63b069703d86f7\",\n    \"privateKey\": \"...\"\n  }\n]\n</code></pre> <p>Copy the address listed in the output from this command. Go to 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.</p> <p></p>"},{"location":"tutorials/chains/avalanche/#confirm-the-transaction-on-snowtrace","title":"Confirm the transaction on Snowtrace","text":"<p>You should be able to go lookup your account on Snowtrace for the Fuji testnet and see that you now have a balance of 2 AVAX. Simply paste in your account address or transaction ID to search for it.</p> <p></p>"},{"location":"tutorials/chains/avalanche/#use-the-public-testnet","title":"Use the public testnet","text":"<p>Now that you have everything set up, you can follow one of the other FireFly guides such as Using Tokens or Custom Smart Contracts. For detailed instructions on deploying a custom smart contract to Avalanche, please see the Avalanche docs for instructions using various tools.</p>"},{"location":"tutorials/chains/binance_smart_chain/","title":"Binance Smart Chain","text":"<p>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.</p>"},{"location":"tutorials/chains/binance_smart_chain/#previous-steps-install-the-firefly-cli","title":"Previous steps: Install the FireFly CLI","text":"<p>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.</p> <p>\u2190 \u2460 Install the FireFly CLI</p>"},{"location":"tutorials/chains/binance_smart_chain/#create-an-evmconnectyml-config-file","title":"Create an <code>evmconnect.yml</code> config file","text":"<p>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 <code>evmconnect.yml</code> with the following contents:</p> <pre><code>confirmations:\n  required: 4 # choose the number of confirmations you require\npolicyengine.simple:\n  fixedGasPrice: null\n  gasOracle:\n    mode: connector\n</code></pre> <p>For more info about <code>confirmations</code>, see Public vs. Permissioned</p> <p>For this tutorial, we will assume this file is saved at <code>~/Desktop/evmconnect.yml</code>. If your path is different, you will need to adjust the path in the next command below.</p>"},{"location":"tutorials/chains/binance_smart_chain/#creating-a-new-stack","title":"Creating a new stack","text":"<p>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:</p> <ul> <li>Create a new Ethereum based stack named <code>bsc</code> with <code>1</code> member</li> <li>Disable <code>multiparty</code> 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</li> <li>Use an remote RPC node. This will create a signer locally, so that our signing key never leaves the development machine.</li> <li>See the Binance BscScan docs and select an HTTPS RPC endpoint.</li> <li>Set the chain ID to <code>97</code> (the correct ID for the Binance Smart Chain testnet)</li> <li>Merge the custom config created above with the generated <code>evmconnect</code> config file</li> </ul> <p>To do this, run the following command:</p> <pre><code>ff init ethereum bsc 1 \\\n    --multiparty=false \\\n    -n remote-rpc \\\n    --remote-node-url &lt;selected RPC endpoint&gt; \\\n    --chain-id 97 \\\n    --connector-config ~/Desktop/evmconnect.yml\n</code></pre>"},{"location":"tutorials/chains/binance_smart_chain/#start-the-stack","title":"Start the stack","text":"<p>Now you should be able to start your stack by running:</p> <pre><code>ff start bsc\n</code></pre> <p>After some time it should print out the following:</p> <pre><code>Web UI for member '0': http://127.0.0.1:5000/ui\nSandbox UI for member '0': http://127.0.0.1:5109\n\n\nTo see logs for your stack run:\n\nff logs bsc\n</code></pre>"},{"location":"tutorials/chains/binance_smart_chain/#get-some-bnb","title":"Get some BNB","text":"<p>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.</p> <p>First, you will need to know what signing address your FireFly node is using. To check that, you can run:</p> <pre><code>ff accounts list bsc\n[\n  {\n    \"address\": \"0x235461d246ab95d367925b4e91bd2755a921fdd8\",\n    \"privateKey\": \"...\"\n  }\n]\n</code></pre> <p>Copy the address listed in the output from this command. Go to 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.</p> <p></p>"},{"location":"tutorials/chains/binance_smart_chain/#confirm-the-transaction-on-bscscan","title":"Confirm the transaction on Bscscan","text":"<p>You should be able to go lookup your account on Bscscan for the testnet 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.</p> <p></p>"},{"location":"tutorials/chains/binance_smart_chain/#use-the-public-testnet","title":"Use the public testnet","text":"<p>Now that you have everything set up, you can follow one of the other FireFly guides such as Using Tokens or Custom Smart Contracts. For detailed instructions on deploying a custom smart contract to Binance Smart Chain, please see the Binance docs for instructions using various tools.</p>"},{"location":"tutorials/chains/fabric_test_network/","title":"Work with Fabric-Samples Test Network","text":"<p>This guide will walk you through the steps to create a local FireFly development environment and connect it to the Fabric Test Network from the Fabric Samples repo</p>"},{"location":"tutorials/chains/fabric_test_network/#previous-steps-install-the-firefly-cli","title":"Previous steps: Install the FireFly CLI","text":"<p>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.</p> <p>\u2190 \u2460 Install the FireFly CLI</p>"},{"location":"tutorials/chains/fabric_test_network/#start-fabric-test-network-with-fabric-ca","title":"Start Fabric Test Network with Fabric CA","text":"<p>For details about the Fabric Test Network and how to set it up, please see the Fabric Samples repo. The one important detail is that you need to start up the Test Network with a Fabric CA. This is because Fabconnect will use the Fabric CA to create an identity for its FireFly node to use. To start up the network with the CA, and create a new channel called <code>mychannel</code> run:</p> <pre><code>./network.sh up createChannel -ca\n</code></pre> <p>NOTE: If you already have the Test Network running, you will need to bring it down first, by running: <code>./network.sh down</code></p>"},{"location":"tutorials/chains/fabric_test_network/#deploy-firefly-chaincode","title":"Deploy FireFly Chaincode","text":"<p>Next we will need to package and deploy the FireFly chaincode to <code>mychannel</code> in our new network. For more details on packaging and deploying chaincode, please see the Fabric chaincode lifecycle documentation. If you already have the FireFly repo cloned in the same directory as your <code>fabric-samples</code> repo, you can run the following script from your <code>test-network</code> directory:</p> <p>NOTE: This script is provided as a convenience only, and you are not required to use it. You are welcome to package and deploy the chaincode to your test-network any way you would like.</p> <pre><code>#!/bin/bash\n\n# This file should be run from the test-network directory in the fabric-samples repo\n# It also assumes that you have the firefly repo checked out at the same level as the fabric-samples directory\n# It also assumes that the test-network is up and running and a channel named 'mychannel' has already been created\n\ncd ../../firefly/smart_contracts/fabric/firefly-go\nGO111MODULE=on go mod vendor\ncd ../../../../fabric-samples/test-network\n\nexport PATH=${PWD}/../bin:$PATH\nexport FABRIC_CFG_PATH=$PWD/../config/\n\npeer lifecycle chaincode package firefly.tar.gz --path ../../firefly/smart_contracts/fabric/firefly-go --lang golang --label firefly_1.0\n\nexport CORE_PEER_TLS_ENABLED=true\nexport CORE_PEER_LOCALMSPID=\"Org1MSP\"\nexport CORE_PEER_TLS_ROOTCERT_FILE=${PWD}/organizations/peerOrganizations/org1.example.com/peers/peer0.org1.example.com/tls/ca.crt\nexport CORE_PEER_MSPCONFIGPATH=${PWD}/organizations/peerOrganizations/org1.example.com/users/Admin@org1.example.com/msp\nexport CORE_PEER_ADDRESS=localhost:7051\n\npeer lifecycle chaincode install firefly.tar.gz\n\nexport CORE_PEER_LOCALMSPID=\"Org2MSP\"\nexport CORE_PEER_TLS_ROOTCERT_FILE=${PWD}/organizations/peerOrganizations/org2.example.com/peers/peer0.org2.example.com/tls/ca.crt\nexport CORE_PEER_MSPCONFIGPATH=${PWD}/organizations/peerOrganizations/org2.example.com/users/Admin@org2.example.com/msp\nexport CORE_PEER_ADDRESS=localhost:9051\n\npeer lifecycle chaincode install firefly.tar.gz\n\nexport CC_PACKAGE_ID=$(peer lifecycle chaincode queryinstalled --output json | jq --raw-output \".installed_chaincodes[0].package_id\")\n\npeer lifecycle chaincode approveformyorg -o localhost:7050 --ordererTLSHostnameOverride orderer.example.com --channelID mychannel --name firefly --version 1.0 --package-id $CC_PACKAGE_ID --sequence 1 --tls --cafile \"${PWD}/organizations/ordererOrganizations/example.com/orderers/orderer.example.com/msp/tlscacerts/tlsca.example.com-cert.pem\"\n\nexport CORE_PEER_LOCALMSPID=\"Org1MSP\"\nexport CORE_PEER_MSPCONFIGPATH=${PWD}/organizations/peerOrganizations/org1.example.com/users/Admin@org1.example.com/msp\nexport CORE_PEER_TLS_ROOTCERT_FILE=${PWD}/organizations/peerOrganizations/org1.example.com/peers/peer0.org1.example.com/tls/ca.crt\nexport CORE_PEER_ADDRESS=localhost:7051\n\npeer lifecycle chaincode approveformyorg -o localhost:7050 --ordererTLSHostnameOverride orderer.example.com --channelID mychannel --name firefly --version 1.0 --package-id $CC_PACKAGE_ID --sequence 1 --tls --cafile \"${PWD}/organizations/ordererOrganizations/example.com/orderers/orderer.example.com/msp/tlscacerts/tlsca.example.com-cert.pem\"\n\npeer lifecycle chaincode commit -o localhost:7050 --ordererTLSHostnameOverride orderer.example.com --channelID mychannel --name firefly --version 1.0 --sequence 1 --tls --cafile \"${PWD}/organizations/ordererOrganizations/example.com/orderers/orderer.example.com/msp/tlscacerts/tlsca.example.com-cert.pem\" --peerAddresses localhost:7051 --tlsRootCertFiles \"${PWD}/organizations/peerOrganizations/org1.example.com/peers/peer0.org1.example.com/tls/ca.crt\" --peerAddresses localhost:9051 --tlsRootCertFiles \"${PWD}/organizations/peerOrganizations/org2.example.com/peers/peer0.org2.example.com/tls/ca.crt\"\n</code></pre>"},{"location":"tutorials/chains/fabric_test_network/#create-ccpyml-documents","title":"Create <code>ccp.yml</code> documents","text":"<p>Each FireFly Supernode (specifically the Fabconnect instance in each) will need to know how to connect to the Fabric network. Fabconnect will use a Fabric Connection Profile which describes the network and tells it where the certs and keys are that it needs. Below is a <code>ccp.yml</code> for each organization. You will need to fill in one line by replacing the string <code>FILL_IN_KEY_NAME_HERE</code>, because the file name of the private key for each user is randomly generated.</p>"},{"location":"tutorials/chains/fabric_test_network/#organization-1-connection-profile","title":"Organization 1 connection profile","text":"<p>Create a new file at <code>~/org1_ccp.yml</code> with the contents below. Replace the string <code>FILL_IN_KEY_NAME_HERE</code> with the filename in your <code>fabric-samples/test-network/organizations/peerOrganizations/org1.example.com/users/Admin@org1.example.com/msp/keystore</code> directory.</p> <pre><code>certificateAuthorities:\n  org1.example.com:\n    tlsCACerts:\n      path: /etc/firefly/organizations/peerOrganizations/org1.example.com/msp/tlscacerts/ca.crt\n    url: https://ca_org1:7054\n    grpcOptions:\n      ssl-target-name-override: org1.example.com\n    registrar:\n      enrollId: admin\n      enrollSecret: adminpw\nchannels:\n  mychannel:\n    orderers:\n      - fabric_orderer\n    peers:\n      fabric_peer:\n        chaincodeQuery: true\n        endorsingPeer: true\n        eventSource: true\n        ledgerQuery: true\nclient:\n  BCCSP:\n    security:\n      default:\n        provider: SW\n      enabled: true\n      hashAlgorithm: SHA2\n      level: 256\n      softVerify: true\n  credentialStore:\n    cryptoStore:\n      path: /etc/firefly/organizations/peerOrganizations/org1.example.com/msp\n    path: /etc/firefly/organizations/peerOrganizations/org1.example.com/msp\n  cryptoconfig:\n    path: /etc/firefly/organizations/peerOrganizations/org1.example.com/msp\n  logging:\n    level: info\n  organization: org1.example.com\n  tlsCerts:\n    client:\n      cert:\n        path: /etc/firefly/organizations/peerOrganizations/org1.example.com/users/Admin@org1.example.com/msp/signcerts/cert.pem\n      key:\n        path: /etc/firefly/organizations/peerOrganizations/org1.example.com/users/Admin@org1.example.com/msp/keystore/FILL_IN_KEY_NAME_HERE\norderers:\n  fabric_orderer:\n    tlsCACerts:\n      path: /etc/firefly/organizations/ordererOrganizations/example.com/orderers/orderer.example.com/tls/tlscacerts/tls-localhost-9054-ca-orderer.pem\n    url: grpcs://orderer.example.com:7050\norganizations:\n  org1.example.com:\n    certificateAuthorities:\n      - org1.example.com\n    cryptoPath: /tmp/msp\n    mspid: Org1MSP\n    peers:\n      - fabric_peer\npeers:\n  fabric_peer:\n    tlsCACerts:\n      path: /etc/firefly/organizations/peerOrganizations/org1.example.com/peers/peer0.org1.example.com/tls/tlscacerts/tls-localhost-7054-ca-org1.pem\n    url: grpcs://peer0.org1.example.com:7051\nversion: 1.1.0%\n</code></pre>"},{"location":"tutorials/chains/fabric_test_network/#organization-2-connection-profile","title":"Organization 2 connection profile","text":"<p>Create a new file at <code>~/org2_ccp.yml</code> with the contents below. Replace the string <code>FILL_IN_KEY_NAME_HERE</code> with the filename in your <code>fabric-samples/test-network/organizations/peerOrganizations/org2.example.com/users/Admin@org2.example.com/msp/keystore</code> directory.</p> <pre><code>certificateAuthorities:\n  org2.example.com:\n    tlsCACerts:\n      path: /etc/firefly/organizations/peerOrganizations/org2.example.com/msp/tlscacerts/ca.crt\n    url: https://ca_org2:8054\n    grpcOptions:\n      ssl-target-name-override: org2.example.com\n    registrar:\n      enrollId: admin\n      enrollSecret: adminpw\nchannels:\n  mychannel:\n    orderers:\n      - fabric_orderer\n    peers:\n      fabric_peer:\n        chaincodeQuery: true\n        endorsingPeer: true\n        eventSource: true\n        ledgerQuery: true\nclient:\n  BCCSP:\n    security:\n      default:\n        provider: SW\n      enabled: true\n      hashAlgorithm: SHA2\n      level: 256\n      softVerify: true\n  credentialStore:\n    cryptoStore:\n      path: /etc/firefly/organizations/peerOrganizations/org2.example.com/msp\n    path: /etc/firefly/organizations/peerOrganizations/org2.example.com/msp\n  cryptoconfig:\n    path: /etc/firefly/organizations/peerOrganizations/org2.example.com/msp\n  logging:\n    level: info\n  organization: org2.example.com\n  tlsCerts:\n    client:\n      cert:\n        path: /etc/firefly/organizations/peerOrganizations/org2.example.com/users/Admin@org2.example.com/msp/signcerts/cert.pem\n      key:\n        path: /etc/firefly/organizations/peerOrganizations/org2.example.com/users/Admin@org2.example.com/msp/keystore/FILL_IN_KEY_NAME_HERE\norderers:\n  fabric_orderer:\n    tlsCACerts:\n      path: /etc/firefly/organizations/ordererOrganizations/example.com/orderers/orderer.example.com/tls/tlscacerts/tls-localhost-9054-ca-orderer.pem\n    url: grpcs://orderer.example.com:7050\norganizations:\n  org2.example.com:\n    certificateAuthorities:\n      - org2.example.com\n    cryptoPath: /tmp/msp\n    mspid: Org2MSP\n    peers:\n      - fabric_peer\npeers:\n  fabric_peer:\n    tlsCACerts:\n      path: /etc/firefly/organizations/peerOrganizations/org2.example.com/peers/peer0.org2.example.com/tls/tlscacerts/tls-localhost-8054-ca-org2.pem\n    url: grpcs://peer0.org2.example.com:9051\nversion: 1.1.0%\n</code></pre>"},{"location":"tutorials/chains/fabric_test_network/#create-the-firefly-stack","title":"Create the FireFly stack","text":"<p>Now we can create a FireFly stack and pass in these files as command line flags.</p> <p>NOTE: The following command should be run in the <code>test-network</code> directory as it includes a relative path to the <code>organizations</code> directory containing each org's MSP.</p> <pre><code>ff init fabric dev \\\n  --ccp \"${HOME}/org1_ccp.yml\" \\\n  --msp \"organizations\" \\\n  --ccp \"${HOME}/org2_ccp.yml\" \\\n  --msp \"organizations\" \\\n  --channel mychannel \\\n  --chaincode firefly\n</code></pre>"},{"location":"tutorials/chains/fabric_test_network/#edit-docker-composeoverrideyml","title":"Edit <code>docker-compose.override.yml</code>","text":"<p>The last step before starting up FireFly is to make sure that our FireFly containers have networking access to the Fabric containers. Because these are in two different Docker Compose networks by default, normally the containers would not be able to connect directly. We can fix this by instructing Docker to also attach our FireFly containers to the Fabric test network Docker Compose network. The easiest way to do that is to edit <code>~/.firefly/stacks/dev/docker-compose.override.yml</code> and set its contents to the following:</p> <pre><code># Add custom config overrides here\n# See https://docs.docker.com/compose/extends\nversion: \"2.1\"\nnetworks:\n  default:\n    name: fabric_test\n    external: true\n</code></pre>"},{"location":"tutorials/chains/fabric_test_network/#start-firefly-stack","title":"Start FireFly stack","text":"<p>Now we can start up FireFly!</p> <pre><code>ff start dev\n</code></pre> <p>After everything starts up, you should have two FireFly nodes that are each mapped to an Organization in your Fabric network. You can that they each use separate signing keys for their Org on messages that each FireFly node sends.</p>"},{"location":"tutorials/chains/fabric_test_network/#connecting-to-a-remote-fabric-network","title":"Connecting to a remote Fabric Network","text":"<p>This same guide can be adapted to connect to a remote Fabric network running somewhere else. They key takeaways are:</p> <ul> <li>You need the FireFly chaincode deployed on channel in your Fabric network</li> <li>You need to pass the channel and chaincode name when you run <code>ff init</code></li> <li>You need to provide a connection profile and the correct certs, keys, etc. for each node when you run <code>ff init</code></li> <li>Your FireFly containers will need to have network access to your Fabric network</li> </ul>"},{"location":"tutorials/chains/fabric_test_network/#troubleshooting","title":"Troubleshooting","text":"<p>There are quite a few moving parts in this guide and if steps are missed or done out of order it can cause problems. Below are some of the common situations that you might run into while following this guide, and solutions for each.</p> <p>You may see a message something along the lines of:</p> <pre><code>ERROR: for firefly_core_0  Container \"bc04521372aa\" is unhealthy.\nEncountered errors while bringing up the project.\n</code></pre> <p>In this case, we need to look at the container logs to get more detail about what happened. To do this, we can run <code>ff start</code> and tell it not to clean up the stack after the failure, to let you inspect what went wrong. To do that, you can run:</p> <pre><code>ff start dev --verbose --no-rollback\n</code></pre> <p>Then we could run <code>docker logs &lt;container_name&gt;</code> to see the logs for that container.</p>"},{"location":"tutorials/chains/fabric_test_network/#no-such-host","title":"No such host","text":"<pre><code>Error: http://127.0.0.1:5102/identities [500] {\"error\":\"enroll failed: enroll failed: POST failure of request: POST https://ca_org1:7054/enroll\\n{\\\"hosts\\\":null,\\\"certificate_request\\\":\\\"-----BEGIN CERTIFICATE REQUEST-----\\\\nMIH0MIGcAgEAMBAxDjAMBgNVBAMTBWFkbWluMFkwEwYHKoZIzj0CAQYIKoZIzj0D\\\\nAQcDQgAE7qJZ5nGt/kxU9IvrEb7EmgNIgn9xXoQUJLl1+U9nXdWB9cnxcmoitnvy\\\\nYN63kbBuUh0z21vOmO8GLD3QxaRaD6AqMCgGCSqGSIb3DQEJDjEbMBkwFwYDVR0R\\\\nBBAwDoIMMGQ4NGJhZWIwZGY0MAoGCCqGSM49BAMCA0cAMEQCIBcWb127dVxm/80K\\\\nB2LtenAY/Jtb2FbZczolrXNCKq+LAiAcGEJ6Mx8LVaPzuSP4uGpEoty6+bEErc5r\\\\nHVER+0aXiQ==\\\\n-----END CERTIFICATE REQUEST-----\\\\n\\\",\\\"profile\\\":\\\"\\\",\\\"crl_override\\\":\\\"\\\",\\\"label\\\":\\\"\\\",\\\"NotBefore\\\":\\\"0001-01-01T00:00:00Z\\\",\\\"NotAfter\\\":\\\"0001-01-01T00:00:00Z\\\",\\\"ReturnPrecert\\\":false,\\\"CAName\\\":\\\"\\\"}: Post \\\"https://ca_org1:7054/enroll\\\": dial tcp: lookup ca_org1 on 127.0.0.11:53: no such host\"}\n</code></pre> <p>If you see something in your logs that looks like the above, there could be a couple issues:</p> <ol> <li>The hostname for one of your Fabric containers could be wrong in the <code>ccp.yml</code>. Check the <code>ccp.yml</code> for that member and make sure the hostnames are correct.</li> <li>The FireFly container doesn't have networking connectivity to the Fabric containers. Check the <code>docker-compose.override.yml</code> file to make sure you added the <code>fabric_test</code> network as instructed above.</li> </ol>"},{"location":"tutorials/chains/fabric_test_network/#no-such-file-or-directory","title":"No such file or directory","text":"<pre><code>User credentials store creation failed. Failed to load identity configurations: failed to create identity config from backends: failed to load client TLSConfig : failed to load client key: failed to load pem bytes from path /etc/firefly/organizations/peerOrganizations/org1.example.com/users/User1@org1.example.com/msp/keystore/cfc50311e2204f232cfdfaf4eba7731279f2366ec291ca1c1781e2bf7bc75529_sk: open /etc/firefly/organizations/peerOrganizations/org1.example.com/users/User1@org1.example.com/msp/keystore/cfc50311e2204f232cfdfaf4eba7731279f2366ec291ca1c1781e2bf7bc75529_sk: no such file or directory\n</code></pre> <p>If you see something in your logs that looks like the above, it's likely that your private key file name is not correct in your <code>ccp.yml</code> file for that particular member. Check your <code>ccp.yml</code> and make sure all the files listed there exist in your <code>organizations</code> directory.</p>"},{"location":"tutorials/chains/moonbeam/","title":"Moonbeam Testnet","text":"<p>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 Moonbeam Alpha testnet.</p>"},{"location":"tutorials/chains/moonbeam/#previous-steps-install-the-firefly-cli","title":"Previous steps: Install the FireFly CLI","text":"<p>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.</p> <p>\u2190 \u2460 Install the FireFly CLI</p>"},{"location":"tutorials/chains/moonbeam/#create-an-evmconnectyml-config-file","title":"Create an <code>evmconnect.yml</code> config file","text":"<p>In order to connect to the Moonbeam testnet, you will need to set a few configuration options for the evmconnect blockchain connector. Create a text file called <code>evmconnect.yml</code> with the following contents:</p> <pre><code>confirmations:\n  required: 4 # choose the number of confirmations you require\npolicyengine.simple:\n  fixedGasPrice: null\n  gasOracle:\n    mode: connector\n</code></pre> <p>For more info about <code>confirmations</code>, see Public vs. Permissioned</p> <p>For this tutorial, we will assume this file is saved at <code>~/Desktop/evmconnect.yml</code>. If your path is different, you will need to adjust the path in the next command below.</p>"},{"location":"tutorials/chains/moonbeam/#creating-a-new-stack","title":"Creating a new stack","text":"<p>To create a local FireFly development stack and connect it to the Moonbeam Alpha testnet, we will use command line flags to customize the following settings:</p> <ul> <li>Create a new Ethereum based stack named <code>moonbeam</code> with <code>1</code> member</li> <li>Disable <code>multiparty</code> 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</li> <li>Use an remote RPC node. This will create a signer locally, so that our signing key never leaves the development machine.</li> <li>See the moonbeam docs and select an HTTPS RPC endpoint</li> <li>Set the chain ID to <code>1287</code> (the correct ID for the Moonbeam Alpha testnet)</li> <li>Merge the custom config created above with the generated <code>evmconnect</code> config file</li> </ul> <p>To do this, run the following command:</p> <pre><code>ff init ethereum moonbeam 1 \\\n    --multiparty=false \\\n    -n remote-rpc \\\n    --remote-node-url &lt;selected RPC endpoint&gt; \\\n    --chain-id 1287 \\\n    --connector-config ~/Desktop/evmconnect.yml\n</code></pre>"},{"location":"tutorials/chains/moonbeam/#start-the-stack","title":"Start the stack","text":"<p>Now you should be able to start your stack by running:</p> <pre><code>ff start moonbeam\n</code></pre> <p>After some time it should print out the following:</p> <pre><code>Web UI for member '0': http://127.0.0.1:5000/ui\nSandbox UI for member '0': http://127.0.0.1:5109\n\n\nTo see logs for your stack run:\n\nff logs moonbeam\n</code></pre>"},{"location":"tutorials/chains/moonbeam/#get-some-dev","title":"Get some DEV","text":"<p>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 DEV, the native token for Moonbeam.</p> <p>First, you will need to know what signing address your FireFly node is using. To check that, you can run:</p> <pre><code>ff accounts list moonbeam\n[\n  {\n    \"address\": \"0x02d42c32a97c894486afbc7b717edff50c70b292\",\n    \"privateKey\": \"...\"\n  }\n]\n</code></pre> <p>Copy the address listed in the output from this command. Go to https://apps.moonbeam.network/moonbase-alpha/faucet/ and paste the address in the form. Click the Submit button.</p> <p></p>"},{"location":"tutorials/chains/moonbeam/#confirm-the-transaction-on-moonscan","title":"Confirm the transaction on Moonscan","text":"<p>You should be able to go lookup your account on Moonscan for the Moonbase Alpha testnet and see that you now have a sufficient balance of DEV. Simply paste in your account address to search for it.</p> <p></p>"},{"location":"tutorials/chains/moonbeam/#use-the-public-testnet","title":"Use the public testnet","text":"<p>Now that you have everything set up, you can follow one of the other FireFly guides such as Using Tokens or Custom Smart Contracts. For detailed instructions on interacting with the Moonbeam Alpha testnet, please see the Moonbeam docs.</p>"},{"location":"tutorials/chains/optimism/","title":"Optimism","text":"<p>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.</p>"},{"location":"tutorials/chains/optimism/#previous-steps-install-the-firefly-cli","title":"Previous steps: Install the FireFly CLI","text":"<p>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.</p> <p>\u2190 \u2460 Install the FireFly CLI</p>"},{"location":"tutorials/chains/optimism/#create-an-evmconnectyml-config-file","title":"Create an <code>evmconnect.yml</code> config file","text":"<p>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 <code>evmconnect.yml</code> with the following contents:</p> <pre><code>confirmations:\n  required: 4 # choose the number of confirmations you require\npolicyengine.simple:\n  fixedGasPrice: null\n  gasOracle:\n    mode: connector\n</code></pre> <p>For this tutorial, we will assume this file is saved at <code>~/Desktop/evmconnect.yml</code>. If your path is different, you will need to adjust the path in the next command below.</p>"},{"location":"tutorials/chains/optimism/#creating-a-new-stack","title":"Creating a new stack","text":"<p>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:</p> <ul> <li>Create a new Ethereum based stack named <code>optimism</code> with <code>1</code> member</li> <li>Disable <code>multiparty</code> 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</li> <li>Use an remote RPC node. This will create a signer locally, so that our signing key never leaves the development machine.</li> <li>See the optimism docs and select an HTTPS RPC endpoint.</li> <li>Set the chain ID to <code>420</code> (the correct ID for the Optimism testnet)</li> <li>Merge the custom config created above with the generated <code>evmconnect</code> config file</li> </ul> <p>To do this, run the following command:</p> <pre><code>ff init ethereum optimism 1 \\\n    --multiparty=false \\\n    -n remote-rpc \\\n    --remote-node-url &lt;selected RPC endpoint&gt; \\\n    --chain-id 420 \\\n    --connector-config ~/Desktop/evmconnect.yml\n</code></pre>"},{"location":"tutorials/chains/optimism/#start-the-stack","title":"Start the stack","text":"<p>Now you should be able to start your stack by running:</p> <pre><code>ff start optimism\n</code></pre> <p>After some time it should print out the following:</p> <pre><code>Web UI for member '0': http://127.0.0.1:5000/ui\nSandbox UI for member '0': http://127.0.0.1:5109\n\n\nTo see logs for your stack run:\n\nff logs optimism\n</code></pre>"},{"location":"tutorials/chains/optimism/#get-some-optimism","title":"Get some Optimism","text":"<p>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.</p> <p>First, you will need to know what signing address your FireFly node is using. To check that, you can run:</p> <pre><code>ff accounts list optimism\n[\n  {\n    \"address\": \"0x235461d246ab95d367925b4e91bd2755a921fdd8\",\n    \"privateKey\": \"...\"\n  }\n]\n</code></pre> <p>Copy the address listed in the output from this command. Go to https://optimismfaucet.xyz/. You will need to login to your Github account and paste the address in the form.</p> <p></p>"},{"location":"tutorials/chains/optimism/#confirm-the-transaction-on-blockcscout","title":"Confirm the transaction on Blockcscout","text":"<p>You should be able to go lookup your account on Blockscout for Optimism testnet 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.</p> <p></p>"},{"location":"tutorials/chains/optimism/#use-the-public-testnet","title":"Use the public testnet","text":"<p>Now that you have everything set up, you can follow one of the other FireFly guides such as Using Tokens or Custom Smart Contracts. For detailed instructions on deploying a custom smart contract to Optimism, please see the Optimism docs for instructions using various tools.</p>"},{"location":"tutorials/chains/polygon_testnet/","title":"Polygon Testnet","text":"<p>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.</p>"},{"location":"tutorials/chains/polygon_testnet/#previous-steps-install-the-firefly-cli","title":"Previous steps: Install the FireFly CLI","text":"<p>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.</p> <p>\u2190 \u2460 Install the FireFly CLI</p>"},{"location":"tutorials/chains/polygon_testnet/#create-an-evmconnectyml-config-file","title":"Create an <code>evmconnect.yml</code> config file","text":"<p>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 <code>evmconnect.yml</code> with the following contents:</p> <pre><code>confirmations:\n  required: 4 # choose the number of confirmations you require\npolicyengine.simple:\n  fixedGasPrice: null\n  gasOracle:\n    mode: connector\n</code></pre> <p>For more info about <code>confirmations</code>, see Public vs. Permissioned</p> <p>For this tutorial, we will assume this file is saved at <code>~/Desktop/evmconnect.yml</code>. If your path is different, you will need to adjust the path in the next command below.</p>"},{"location":"tutorials/chains/polygon_testnet/#creating-a-new-stack","title":"Creating a new stack","text":"<p>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:</p> <ul> <li>Create a new Ethereum based stack named <code>polygon</code> with <code>1</code> member</li> <li>Disable <code>multiparty</code> 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</li> <li>Use an remote RPC node. This will create a signer locally, so that our signing key never leaves the development machine.</li> <li>See the list of Polygon RPC endpoints and select an HTTPS RPC endpoint.</li> <li>Set the chain ID to <code>80001</code> (the correct ID for the Polygon Mumbai testnet)</li> <li>Merge the custom config created above with the generated <code>evmconnect</code> config file</li> </ul> <p>To do this, run the following command:</p> <pre><code>ff init ethereum polygon 1 \\\n    --multiparty=false \\\n    -n remote-rpc \\\n    --remote-node-url &lt;selected RPC endpoint&gt; \\\n    --chain-id 80001 \\\n    --connector-config ~/Desktop/evmconnect.yml\n</code></pre>"},{"location":"tutorials/chains/polygon_testnet/#start-the-stack","title":"Start the stack","text":"<p>Now you should be able to start your stack by running:</p> <pre><code>ff start polygon\n</code></pre> <p>After some time it should print out the following:</p> <pre><code>Web UI for member '0': http://127.0.0.1:5000/ui\nSandbox UI for member '0': http://127.0.0.1:5109\n\n\nTo see logs for your stack run:\n\nff logs polygon\n</code></pre>"},{"location":"tutorials/chains/polygon_testnet/#get-some-matic","title":"Get some MATIC","text":"<p>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.</p> <p>First, you will need to know what signing address your FireFly node is using. To check that, you can run:</p> <pre><code>ff accounts list polygon\n[\n  {\n    \"address\": \"0x02d42c32a97c894486afbc7b717edff50c70b292\",\n    \"privateKey\": \"...\"\n  }\n]\n</code></pre> <p>Copy the address listed in the output from this command. Go to https://faucet.polygon.technology/ and paste the address in the form. Click the Submit button, and then Confirm.</p> <p></p>"},{"location":"tutorials/chains/polygon_testnet/#confirm-the-transaction-on-polygonscan","title":"Confirm the transaction on Polygonscan","text":"<p>You should be able to go lookup your account on Polygonscan for the Mumbai testnet and see that you now have a balance of 0.2 MATIC. Simply paste in your account address to search for it.</p> <p>You can also click on the Internal Txns tab from you account page to see the actual transfer of the MATIC from the faucet.</p> <p></p>"},{"location":"tutorials/chains/polygon_testnet/#use-the-public-testnet","title":"Use the public testnet","text":"<p>Now that you have everything set up, you can follow one of the other FireFly guides such as Using Tokens or Custom Smart Contracts. For detailed instructions on deploying a custom smart contract to Polygon, please see the Polygon docs for instructions using various tools.</p>"},{"location":"tutorials/chains/tezos_testnet/","title":"Tezos Testnet","text":"<p>This guide will walk you through the steps to create a local FireFly development environment and connect it to the public Tezos Ghostnet testnet.</p>"},{"location":"tutorials/chains/tezos_testnet/#previous-steps-install-the-firefly-cli","title":"Previous steps: Install the FireFly CLI","text":"<p>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.</p> <p>\u2190 \u2460 Install the FireFly CLI</p>"},{"location":"tutorials/chains/tezos_testnet/#set-up-the-transaction-signing-service","title":"Set up the transaction signing service","text":"<p>Signatory service allows to work with many different key-management systems.\\ By default, FF uses local signing option.\\ However, it is also possible to configure the transaction signing service using key management systems such as: AWS/Google/Azure KMS, HCP Vault, etc.</p> <p>NOTE: The default option is not secure and is mainly used for development and demo purposes. Therefore, for the production, use the selected KMS.\\ The full list can be found here.</p>"},{"location":"tutorials/chains/tezos_testnet/#creating-a-new-stack","title":"Creating a new stack","text":"<p>To create a local FireFly development stack and connect it to the Tezos Ghostnet testnet, we will use command line flags to customize the following settings:</p> <ul> <li>Create a new Tezos based stack named <code>tezos</code> with <code>1</code> member</li> <li>Disable <code>multiparty</code> 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</li> <li>See the list of Tezos public RPC nodes and select an HTTPS RPC node.</li> </ul> <p>To do this, run the following command:</p> <pre><code>ff init tezos dev 1 \\\n    --multiparty=false \\\n    --remote-node-url &lt;selected RPC endpoint&gt;\n</code></pre> <p>NOTE: The public RPC nodes may have limitations or may not support all FF required RPC endpoints. Therefore it's not recommended to use ones for production and you may need to run own node or use third-party vendors.</p>"},{"location":"tutorials/chains/tezos_testnet/#start-the-stack","title":"Start the stack","text":"<p>Now you should be able to start your stack by running:</p> <pre><code>ff start dev\n</code></pre> <p>After some time it should print out the following:</p> <pre><code>Web UI for member '0': http://127.0.0.1:5000/ui\nSandbox UI for member '0': http://127.0.0.1:5109\n\n\nTo see logs for your stack run:\n\nff logs dev\n</code></pre>"},{"location":"tutorials/chains/tezos_testnet/#get-some-xtz","title":"Get some XTZ","text":"<p>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 transaction fee. A testnet faucet can give us some XTZ, the native token for Tezos.</p> <p>First, you need to get an account address, which was created during signer set up step.\\ To check that, you can run:</p> <pre><code>ff accounts list dev\n[\n  {\n    \"address\": \"tz1cuFw1E2Mn2bVS8q8d7QoCb6FXC18JivSp\",\n    \"privateKey\": \"...\"\n  }\n]\n</code></pre> <p>After that, go to Tezos Ghostnet Faucet and paste the address in the form and click the Request button.</p> <p></p>"},{"location":"tutorials/chains/tezos_testnet/#confirm-the-transaction-on-tzstats","title":"Confirm the transaction on TzStats","text":"<p>You should be able to go lookup your account on TzStats for the Ghostnet testnet and see that you now have a balance of 100 XTZ (or 2001 XTZ accordingly). Simply paste in your account address to search for it.</p> <p>On the Transfers tab from you account page you will see the actual transfer of the XTZ from the faucet.</p> <p></p>"},{"location":"tutorials/chains/tezos_testnet/#use-the-public-testnet","title":"Use the public testnet","text":"<p>Now that you have everything set up, you can follow one of the other FireFly guides such as Custom Smart Contracts. For detailed instructions on deploying a custom smart contract to Tezos, please see the Tezos docs for instructions using various tools.</p>"},{"location":"tutorials/chains/zksync_testnet/","title":"zkSync Testnet","text":"<p>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 zkSync testnet.</p>"},{"location":"tutorials/chains/zksync_testnet/#previous-steps-install-the-firefly-cli","title":"Previous steps: Install the FireFly CLI","text":"<p>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.</p> <p>\u2190 \u2460 Install the FireFly CLI</p>"},{"location":"tutorials/chains/zksync_testnet/#create-an-evmconnectyml-config-file","title":"Create an <code>evmconnect.yml</code> config file","text":"<p>In order to connect to the zkSync testnet, you will need to set a few configuration options for the evmconnect blockchain connector. Create a text file called <code>evmconnect.yml</code> with the following contents:</p> <pre><code>confirmations:\n  required: 4 # choose the number of confirmations you require\npolicyengine.simple:\n  fixedGasPrice: null\n  gasOracle:\n    mode: connector\n</code></pre> <p>For this tutorial, we will assume this file is saved at <code>~/Desktop/evmconnect.yml</code>. If your path is different, you will need to adjust the path in the next command below.</p>"},{"location":"tutorials/chains/zksync_testnet/#creating-a-new-stack","title":"Creating a new stack","text":"<p>To create a local FireFly development stack and connect it to the zkSync testnet, we will use command line flags to customize the following settings:</p> <ul> <li>Create a new stack named <code>zkSync</code> with <code>1</code> member</li> <li>Disable <code>multiparty</code> 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</li> <li>Connect to an ethereum network</li> <li>Use the <code>evmconnect</code> blockchain connector</li> <li>Use an remote RPC node. This will create a signer locally, so that our signing key never leaves the development machine.</li> <li>See the list of providers for zkSync docs. For this tutorial we will use <code>https://zksync2-testnet.zksync.dev</code></li> <li>Set the chain ID to <code>280</code> (the correct ID for the zkSync testnet)</li> <li>Merge the custom config created above with the generated <code>evmconnect</code> config file</li> </ul> <p>To do this, run the following command:</p> <pre><code>ff init zksync 1\\\n    --multiparty=false \\\n    -b ethereum \\\n    -c evmconnect \\\n    -n remote-rpc \\\n    --remote-node-url https://zksync2-testnet.zksync.dev\\\n    --chain-id 280 \\\n    --connector-config ~/Desktop/evmconnect.yml\n</code></pre>"},{"location":"tutorials/chains/zksync_testnet/#start-the-stack","title":"Start the stack","text":"<p>Now you should be able to start your stack by running:</p> <pre><code>ff start zksync\n</code></pre> <p>After some time it should print out the following:</p> <pre><code>Web UI for member '0': http://127.0.0.1:5000/ui\nSandbox UI for member '0': http://127.0.0.1:5109\n\n\nTo see logs for your stack run:\n\nff logs zksync\n</code></pre>"},{"location":"tutorials/chains/zksync_testnet/#get-some-eth","title":"Get some ETH","text":"<p>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. zkSync does not currently have its own native token and instead uses Ethereum for transaction. A testnet faucet can give us some ETH.</p> <p>First, you will need to know what signing address your FireFly node is using. To check that, you can run:</p> <pre><code>ff accounts list zkSync\n[\n  {\n    \"address\": \"0x8cf4fd38b2d56a905113d23b5a7131f0269d8611\",\n    \"privateKey\": \"...\"\n  }\n]\n</code></pre> <p>Copy your zkSync address and go to the Goerli Ethereum faucet and paste the address in the form. Click the Request Tokens button. Note that any Goerli Ethereum faucet will work.</p> <p></p>"},{"location":"tutorials/chains/zksync_testnet/#confirm-the-transaction-on-the-etherscan-explorer","title":"Confirm the transaction on the Etherscan Explorer","text":"<p>You should be able to go lookup your account at https://etherscan.io/ and see that you now have a balance of 0.025 ETH. Simply paste in your account address to search for it.</p> <p></p>"},{"location":"tutorials/chains/zksync_testnet/#use-the-public-testnet","title":"Use the public testnet","text":"<p>Now that you have everything set up, you can follow one of the other FireFly guides such as Using Tokens or Custom Smart Contracts. For detailed instructions on deploying a custom smart contract to zkSync, please see the zkSync docs for instructions using various tools.</p>"},{"location":"tutorials/custom_contracts/","title":"Work with custom smart contracts","text":""},{"location":"tutorials/custom_contracts/#quick-reference","title":"Quick reference","text":"<p>Almost all blockchain platforms offer the ability to execute smart contracts on-chain in order to manage states on the shared ledger. FireFly provides support to use RESTful APIs to interact with the smart contracts deployed in the target blockchains, and listening to events via websocket.</p> <p>FireFly's unified API creates a consistent application experience regardless of the specific underlying blockchain implementation. It also provides developer-friendly features like automatic OpenAPI Specification generation for smart contracts, plus a built-in Swagger UI.</p>"},{"location":"tutorials/custom_contracts/#key-concepts","title":"Key concepts","text":"<p>FireFly defines the following constructs to support custom smart contracts:</p>"},{"location":"tutorials/custom_contracts/#contract-interface","title":"Contract Interface","text":"<p>FireFly defines a common, blockchain agnostic way to describe smart contracts. This is referred to as a Contract Interface. A contract interface is written in the FireFly Interface (FFI) format. It is a simple JSON document that has a name, a namespace, a version, a list of methods, and a list of events.</p> <p>For more details, you can also have a look at the Reference page for the FireFly Interface Format.</p> <p>For blockchains that offer a DSL describing the smart contract interface, such as Ethereum's ABI (Application Binary Interface), FireFly offers an API to convert the DSL into the FFI format.</p> <p>NOTE: Contract interfaces are scoped to a namespace. Within a namespace each contract interface must have a unique name and version combination. The same name and version combination can exist in different namespaces simultaneously.</p>"},{"location":"tutorials/custom_contracts/#http-api","title":"HTTP API","text":"<p>Based on a Contract Interface, FireFly further defines an HTTP API for the smart contract, which is complete with an OpenAPI Specification and the Swagger UI. An HTTP API defines an <code>/invoke</code> root path to submit transactions, and a <code>/query</code> root path to send query requests to read the state back out.</p> <p>How the invoke vs. query requests get interpreted into the native blockchain requests are specific to the blockchain's connector. For instance, the Ethereum connector translates <code>/invoke</code> calls to <code>eth_sendTransaction</code> JSON-RPC requests, while <code>/query</code> calls are translated into <code>eth_call</code> JSON-RPC requests. On the other hand, the Fabric connector translates <code>/invoke</code> calls to the multiple requests required to submit a transaction to a Fabric channel (which first collects endorsements from peer nodes, and then sends the assembled transaction payload to an orderer, for details please refer to the Fabric documentation).</p>"},{"location":"tutorials/custom_contracts/#blockchain-event-listener","title":"Blockchain Event Listener","text":"<p>Regardless of a blockchain's specific design, transaction processing are always asynchronous. This means a transaction is submitted to the network, at which point the submitting client gets an acknowledgement that it has been accepted for further processing. The client then listens for notifications by the blockchain when the transaction gets committed to the blockchain's ledger.</p> <p>FireFly defines event listeners to allow the client application to specify the relevant blockchain events to keep track of. A client application can then receive the notifications from FireFly via an event subscription.</p>"},{"location":"tutorials/custom_contracts/#event-subscription","title":"Event Subscription","text":"<p>An event listener in FireFly tracks specific blockchain events, while an event subscription directs FireFly to send those events to the client application. Each subscription creates a stream of events that can be delivered to the client with various delivery options, ensuring an at-least-once delivery guarantee.</p> <p>This is exactly the same as listening for any other events from FireFly. For more details on how Subscriptions work in FireFly you can read the Getting Started guide to Listen for events.</p>"},{"location":"tutorials/custom_contracts/#custom-onchain-logic-async-programming-in-firefly","title":"Custom onchain logic async programming in FireFly","text":"<p>Like the rest of FireFly, custom onchain logic support are implemented with an asynchronous programming model. The key concepts here are:</p> <ul> <li>Transactions are submitted to FireFly and an ID is returned. This is the Operation ID.</li> <li>The transaction itself happens asynchronously from the HTTP request that initiated it</li> <li>Blockchain events emitted by the custom onchain logic (Ethereum smart contracts, Fabric chaincodes, Corda flows, etc.) will be stored in FireFly's database if FireFly has a Event Listener set up for that specific type of event. FireFly will also emit an event of type <code>blockchain_event_received</code> when this happens.</li> </ul> <p></p>"},{"location":"tutorials/custom_contracts/ethereum/","title":"Work with Ethereum smart contracts","text":"<p>This guide describes the steps to deploy a smart contract to an Ethereum blockchain and use FireFly to interact with it in order to submit transactions, query for states and listening for events.</p> <p>NOTE: This guide assumes that you are running a local FireFly stack with at least 2 members and an Ethereum blockchain created by the FireFly CLI. If you need help getting that set up, please see the Getting Started guide to Start your environment.</p>"},{"location":"tutorials/custom_contracts/ethereum/#example-smart-contract","title":"Example smart contract","text":"<p>For this tutorial, we will be using a well known, but slightly modified smart contract called <code>SimpleStorage</code>, and will be using this contract on an Ethereum blockchain. As the name implies, it's a very simple contract which stores an unsigned 256 bit integer, emits and event when the value is updated, and allows you to retrieve the current value.</p> <p>Here is the source for this contract:</p> <pre><code>// SPDX-License-Identifier: Apache-2.0\npragma solidity ^0.8.10;\n\n// Declares a new contract\ncontract SimpleStorage {\n    // Storage. Persists in between transactions\n    uint256 x;\n\n    // Allows the unsigned integer stored to be changed\n    function set(uint256 newValue) public {\n        x = newValue;\n        emit Changed(msg.sender, newValue);\n    }\n\n    // Returns the currently stored unsigned integer\n    function get() public view returns (uint256) {\n        return x;\n    }\n\n    event Changed(address indexed from, uint256 value);\n}\n</code></pre>"},{"location":"tutorials/custom_contracts/ethereum/#contract-deployment","title":"Contract deployment","text":"<p>If you need to deploy an Ethereum smart contract with a signing key that FireFly will use for submitting future transactions it is recommended to use FireFly's built in contract deployment API. This is useful in many cases. For example, you may want to deploy a token contract and have FireFly mint some tokens. Many token contracts only allow the contract deployer to mint, so the contract would need to be deployed with a FireFly signing key.</p> <p>You will need compile the contract yourself using solc or some other tool. After you have compiled the contract, look in the JSON output file for the fields to build the request below.</p>"},{"location":"tutorials/custom_contracts/ethereum/#request","title":"Request","text":"Field Description <code>key</code> The signing key to use to dpeloy the contract. If omitted, the namespaces's default signing key will be used. <code>contract</code> The compiled bytecode for your smart contract. It should be either a hex encded string or Base64. <code>definition</code> The full ABI JSON array from your compiled JSON file. Copy the entire value of the <code>abi</code> field from the <code>[</code> to the <code>]</code>. <code>input</code> An ordered list of constructor arguments. Some contracts may not require any (such as this example). <p><code>POST</code> <code>http://localhost:5000/api/v1/namespaces/default/contracts/deploy</code></p> <pre><code>{\n  \"contract\": \"608060405234801561001057600080fd5b5061019e806100206000396000f3fe608060405234801561001057600080fd5b50600436106100365760003560e01c806360fe47b11461003b5780636d4ce63c14610057575b600080fd5b61005560048036038101906100509190610111565b610075565b005b61005f6100cd565b60405161006c919061014d565b60405180910390f35b806000819055503373ffffffffffffffffffffffffffffffffffffffff167fb52dda022b6c1a1f40905a85f257f689aa5d69d850e49cf939d688fbe5af5946826040516100c2919061014d565b60405180910390a250565b60008054905090565b600080fd5b6000819050919050565b6100ee816100db565b81146100f957600080fd5b50565b60008135905061010b816100e5565b92915050565b600060208284031215610127576101266100d6565b5b6000610135848285016100fc565b91505092915050565b610147816100db565b82525050565b6000602082019050610162600083018461013e565b9291505056fea2646970667358221220e6cbd7725b98b234d07bc1823b60ac065b567c6645d15c8f8f6986e5fa5317c664736f6c634300080b0033\",\n  \"definition\": [\n    {\n      \"anonymous\": false,\n      \"inputs\": [\n        {\n          \"indexed\": true,\n          \"internalType\": \"address\",\n          \"name\": \"from\",\n          \"type\": \"address\"\n        },\n        {\n          \"indexed\": false,\n          \"internalType\": \"uint256\",\n          \"name\": \"value\",\n          \"type\": \"uint256\"\n        }\n      ],\n      \"name\": \"Changed\",\n      \"type\": \"event\"\n    },\n    {\n      \"inputs\": [],\n      \"name\": \"get\",\n      \"outputs\": [\n        {\n          \"internalType\": \"uint256\",\n          \"name\": \"\",\n          \"type\": \"uint256\"\n        }\n      ],\n      \"stateMutability\": \"view\",\n      \"type\": \"function\"\n    },\n    {\n      \"inputs\": [\n        {\n          \"internalType\": \"uint256\",\n          \"name\": \"newValue\",\n          \"type\": \"uint256\"\n        }\n      ],\n      \"name\": \"set\",\n      \"outputs\": [],\n      \"stateMutability\": \"nonpayable\",\n      \"type\": \"function\"\n    }\n  ],\n  \"input\": []\n}\n</code></pre>"},{"location":"tutorials/custom_contracts/ethereum/#response","title":"Response","text":"<pre><code>{\n  \"id\": \"aa155a3c-2591-410e-bc9d-68ae7de34689\",\n  \"namespace\": \"default\",\n  \"tx\": \"4712ffb3-cc1a-4a91-aef2-206ac068ba6f\",\n  \"type\": \"blockchain_deploy\",\n  \"status\": \"Succeeded\",\n  \"plugin\": \"ethereum\",\n  \"input\": {\n    \"contract\": \"608060405234801561001057600080fd5b5061019e806100206000396000f3fe608060405234801561001057600080fd5b50600436106100365760003560e01c806360fe47b11461003b5780636d4ce63c14610057575b600080fd5b61005560048036038101906100509190610111565b610075565b005b61005f6100cd565b60405161006c919061014d565b60405180910390f35b806000819055503373ffffffffffffffffffffffffffffffffffffffff167fb52dda022b6c1a1f40905a85f257f689aa5d69d850e49cf939d688fbe5af5946826040516100c2919061014d565b60405180910390a250565b60008054905090565b600080fd5b6000819050919050565b6100ee816100db565b81146100f957600080fd5b50565b60008135905061010b816100e5565b92915050565b600060208284031215610127576101266100d6565b5b6000610135848285016100fc565b91505092915050565b610147816100db565b82525050565b6000602082019050610162600083018461013e565b9291505056fea2646970667358221220e6cbd7725b98b234d07bc1823b60ac065b567c6645d15c8f8f6986e5fa5317c664736f6c634300080b0033\",\n    \"definition\": [\n      {\n        \"anonymous\": false,\n        \"inputs\": [\n          {\n            \"indexed\": true,\n            \"internalType\": \"address\",\n            \"name\": \"from\",\n            \"type\": \"address\"\n          },\n          {\n            \"indexed\": false,\n            \"internalType\": \"uint256\",\n            \"name\": \"value\",\n            \"type\": \"uint256\"\n          }\n        ],\n        \"name\": \"Changed\",\n        \"type\": \"event\"\n      },\n      {\n        \"inputs\": [],\n        \"name\": \"get\",\n        \"outputs\": [\n          {\n            \"internalType\": \"uint256\",\n            \"name\": \"\",\n            \"type\": \"uint256\"\n          }\n        ],\n        \"stateMutability\": \"view\",\n        \"type\": \"function\"\n      },\n      {\n        \"inputs\": [\n          {\n            \"internalType\": \"uint256\",\n            \"name\": \"newValue\",\n            \"type\": \"uint256\"\n          }\n        ],\n        \"name\": \"set\",\n        \"outputs\": [],\n        \"stateMutability\": \"nonpayable\",\n        \"type\": \"function\"\n      }\n    ],\n    \"input\": [],\n    \"key\": \"0xddd93a452bfc8d3e62bbc60c243046e4d0cb971b\",\n    \"options\": null\n  },\n  \"output\": {\n    \"headers\": {\n      \"requestId\": \"default:aa155a3c-2591-410e-bc9d-68ae7de34689\",\n      \"type\": \"TransactionSuccess\"\n    },\n    \"contractLocation\": {\n      \"address\": \"0xa5ea5d0a6b2eaf194716f0cc73981939dca26da1\"\n    },\n    \"protocolId\": \"000000000024/000000\",\n    \"transactionHash\": \"0x32d1144091877266d7f0426e48db157e7d1a857c62e6f488319bb09243f0f851\"\n  },\n  \"created\": \"2023-02-03T15:42:52.750277Z\",\n  \"updated\": \"2023-02-03T15:42:52.750277Z\"\n}\n</code></pre> <p>Here we can see in the response above under the <code>output</code> section that our new contract address is <code>0xa5ea5d0a6b2eaf194716f0cc73981939dca26da1</code>. This is the address that we will reference in the rest of this guide.</p>"},{"location":"tutorials/custom_contracts/ethereum/#the-firefly-interface-format","title":"The FireFly Interface Format","text":"<p>If you have an Ethereum ABI for an existing smart contract, there is an HTTP endpoint on the FireFly API that will take the ABI as input and automatically generate the FireFly Interface for you. Rather than handcrafting our FFI, we'll let FireFly generate it for us using that endpoint now.</p>"},{"location":"tutorials/custom_contracts/ethereum/#request_1","title":"Request","text":"<p>Here we will take the JSON ABI generated by <code>truffle</code> or <code>solc</code> and <code>POST</code> that to FireFly to have it automatically generate the FireFly Interface for us. Copy the <code>abi</code> from the compiled JSON file, and put that inside an <code>input</code> object like the example below:</p> <p><code>POST</code> <code>http://localhost:5000/api/v1/namespaces/default/contracts/interfaces/generate</code></p> <pre><code>{\n  \"input\": {\n    \"abi\": [\n      {\n        \"anonymous\": false,\n        \"inputs\": [\n          {\n            \"indexed\": true,\n            \"internalType\": \"address\",\n            \"name\": \"from\",\n            \"type\": \"address\"\n          },\n          {\n            \"indexed\": false,\n            \"internalType\": \"uint256\",\n            \"name\": \"value\",\n            \"type\": \"uint256\"\n          }\n        ],\n        \"name\": \"Changed\",\n        \"type\": \"event\"\n      },\n      {\n        \"inputs\": [],\n        \"name\": \"get\",\n        \"outputs\": [\n          {\n            \"internalType\": \"uint256\",\n            \"name\": \"\",\n            \"type\": \"uint256\"\n          }\n        ],\n        \"stateMutability\": \"view\",\n        \"type\": \"function\"\n      },\n      {\n        \"inputs\": [\n          {\n            \"internalType\": \"uint256\",\n            \"name\": \"newValue\",\n            \"type\": \"uint256\"\n          }\n        ],\n        \"name\": \"set\",\n        \"outputs\": [],\n        \"stateMutability\": \"nonpayable\",\n        \"type\": \"function\"\n      }\n    ]\n  }\n}\n</code></pre>"},{"location":"tutorials/custom_contracts/ethereum/#response_1","title":"Response","text":"<p>FireFly generates and returns the the full FireFly Interface for the SimpleStorage contract in the response body:</p> <pre><code>{\n  \"namespace\": \"default\",\n  \"name\": \"\",\n  \"description\": \"\",\n  \"version\": \"\",\n  \"methods\": [\n    {\n      \"name\": \"get\",\n      \"pathname\": \"\",\n      \"description\": \"\",\n      \"params\": [],\n      \"returns\": [\n        {\n          \"name\": \"\",\n          \"schema\": {\n            \"type\": \"integer\",\n            \"details\": {\n              \"type\": \"uint256\",\n              \"internalType\": \"uint256\"\n            }\n          }\n        }\n      ]\n    },\n    {\n      \"name\": \"set\",\n      \"pathname\": \"\",\n      \"description\": \"\",\n      \"params\": [\n        {\n          \"name\": \"newValue\",\n          \"schema\": {\n            \"type\": \"integer\",\n            \"details\": {\n              \"type\": \"uint256\",\n              \"internalType\": \"uint256\"\n            }\n          }\n        }\n      ],\n      \"returns\": []\n    }\n  ],\n  \"events\": [\n    {\n      \"name\": \"Changed\",\n      \"description\": \"\",\n      \"params\": [\n        {\n          \"name\": \"from\",\n          \"schema\": {\n            \"type\": \"string\",\n            \"details\": {\n              \"type\": \"address\",\n              \"internalType\": \"address\",\n              \"indexed\": true\n            }\n          }\n        },\n        {\n          \"name\": \"value\",\n          \"schema\": {\n            \"type\": \"integer\",\n            \"details\": {\n              \"type\": \"uint256\",\n              \"internalType\": \"uint256\"\n            }\n          }\n        }\n      ]\n    }\n  ]\n}\n</code></pre>"},{"location":"tutorials/custom_contracts/ethereum/#broadcast-the-contract-interface","title":"Broadcast the contract interface","text":"<p>Now that we have a FireFly Interface representation of our smart contract, we want to broadcast that to the entire network. This broadcast will be pinned to the blockchain, so we can always refer to this specific name and version, and everyone in the network will know exactly which contract interface we are talking about.</p> <p>We will take the output from the previous HTTP response above, fill in the name and version and then <code>POST</code> that to the <code>/contracts/interfaces</code> API endpoint.</p>"},{"location":"tutorials/custom_contracts/ethereum/#request_2","title":"Request","text":"<p><code>POST</code> <code>http://localhost:5000/api/v1/namespaces/default/contracts/interfaces?publish=true</code></p> <p>NOTE: Without passing the query parameter <code>publish=true</code> when the interface is created, it will initially be unpublished and not broadcasted to other members of the network (if configured in multi-party). To publish the interface, a subsequent API call would need to be made to <code>/contracts/interfaces/{name}/{version}/publish</code></p> <pre><code>{\n  \"namespace\": \"default\",\n  \"name\": \"SimpleStorage\",\n  \"version\": \"v1.0.0\",\n  \"description\": \"\",\n  \"methods\": [\n    {\n      \"name\": \"get\",\n      \"pathname\": \"\",\n      \"description\": \"\",\n      \"params\": [],\n      \"returns\": [\n        {\n          \"name\": \"\",\n          \"schema\": {\n            \"type\": \"integer\",\n            \"details\": {\n              \"type\": \"uint256\",\n              \"internalType\": \"uint256\"\n            }\n          }\n        }\n      ]\n    },\n    {\n      \"name\": \"set\",\n      \"pathname\": \"\",\n      \"description\": \"\",\n      \"params\": [\n        {\n          \"name\": \"newValue\",\n          \"schema\": {\n            \"type\": \"integer\",\n            \"details\": {\n              \"type\": \"uint256\",\n              \"internalType\": \"uint256\"\n            }\n          }\n        }\n      ],\n      \"returns\": []\n    }\n  ],\n  \"events\": [\n    {\n      \"name\": \"Changed\",\n      \"description\": \"\",\n      \"params\": [\n        {\n          \"name\": \"from\",\n          \"schema\": {\n            \"type\": \"string\",\n            \"details\": {\n              \"type\": \"address\",\n              \"internalType\": \"address\",\n              \"indexed\": true\n            }\n          }\n        },\n        {\n          \"name\": \"value\",\n          \"schema\": {\n            \"type\": \"integer\",\n            \"details\": {\n              \"type\": \"uint256\",\n              \"internalType\": \"uint256\"\n            }\n          }\n        }\n      ]\n    }\n  ]\n}\n</code></pre>"},{"location":"tutorials/custom_contracts/ethereum/#response_2","title":"Response","text":"<pre><code>{\n  \"id\": \"8bdd27a5-67c1-4960-8d1e-7aa31b9084d3\",\n  \"message\": \"3cd0dde2-1e39-4c9e-a4a1-569e87cca93a\",\n  \"namespace\": \"default\",\n  \"name\": \"SimpleStorage\",\n  \"description\": \"\",\n  \"version\": \"v1.0.0\",\n  \"methods\": [\n    {\n      \"id\": \"56467890-5713-4463-84b8-4537fcb63d8b\",\n      \"contract\": \"8bdd27a5-67c1-4960-8d1e-7aa31b9084d3\",\n      \"name\": \"get\",\n      \"namespace\": \"default\",\n      \"pathname\": \"get\",\n      \"description\": \"\",\n      \"params\": [],\n      \"returns\": [\n        {\n          \"name\": \"\",\n          \"schema\": {\n            \"type\": \"integer\",\n            \"details\": {\n              \"type\": \"uint256\",\n              \"internalType\": \"uint256\"\n            }\n          }\n        }\n      ]\n    },\n    {\n      \"id\": \"6b254d1d-5f5f-491e-bbd2-201e96892e1a\",\n      \"contract\": \"8bdd27a5-67c1-4960-8d1e-7aa31b9084d3\",\n      \"name\": \"set\",\n      \"namespace\": \"default\",\n      \"pathname\": \"set\",\n      \"description\": \"\",\n      \"params\": [\n        {\n          \"name\": \"newValue\",\n          \"schema\": {\n            \"type\": \"integer\",\n            \"details\": {\n              \"type\": \"uint256\",\n              \"internalType\": \"uint256\"\n            }\n          }\n        }\n      ],\n      \"returns\": []\n    }\n  ],\n  \"events\": [\n    {\n      \"id\": \"aa1fe67b-b2ac-41af-a7e7-7ad54a30a78d\",\n      \"contract\": \"8bdd27a5-67c1-4960-8d1e-7aa31b9084d3\",\n      \"namespace\": \"default\",\n      \"pathname\": \"Changed\",\n      \"name\": \"Changed\",\n      \"description\": \"\",\n      \"params\": [\n        {\n          \"name\": \"from\",\n          \"schema\": {\n            \"type\": \"string\",\n            \"details\": {\n              \"type\": \"address\",\n              \"internalType\": \"address\",\n              \"indexed\": true\n            }\n          }\n        },\n        {\n          \"name\": \"value\",\n          \"schema\": {\n            \"type\": \"integer\",\n            \"details\": {\n              \"type\": \"uint256\",\n              \"internalType\": \"uint256\"\n            }\n          }\n        }\n      ]\n    }\n  ],\n  \"published\": true\n}\n</code></pre>"},{"location":"tutorials/custom_contracts/ethereum/#create-an-http-api-for-the-contract","title":"Create an HTTP API for the contract","text":"<p>Now comes the fun part where we see some of the powerful, developer-friendly features of FireFly. The next thing we're going to do is tell FireFly to build an HTTP API for this smart contract, complete with an OpenAPI Specification and Swagger UI. As part of this, we'll also tell FireFly where the contract is on the blockchain. Like the interface broadcast above, this will also generate a broadcast which will be pinned to the blockchain so all the members of the network will be aware of and able to interact with this API.</p> <p>We need to copy the <code>id</code> field we got in the response from the previous step to the <code>interface.id</code> field in the request body below. We will also pick a name that will be part of the URL for our HTTP API, so be sure to pick a name that is URL friendly. In this case we'll call it <code>simple-storage</code>. Lastly, in the <code>location.address</code> field, we're telling FireFly where an instance of the contract is deployed on-chain.</p> <p>NOTE: The <code>location</code> field is optional here, but if it is omitted, it will be required in every request to invoke or query the contract. This can be useful if you have multiple instances of the same contract deployed to different addresses.</p>"},{"location":"tutorials/custom_contracts/ethereum/#request_3","title":"Request","text":"<p><code>POST</code> <code>http://localhost:5000/api/v1/namespaces/default/apis?publish=true</code></p> <p>NOTE: Without passing the query parameter <code>publish=true</code> when the API is created, it will initially be unpublished and not broadcasted to other members of the network (if configured in multi-party). To publish the API, a subsequent API call would need to be made to <code>/apis/{apiName}/publish</code></p> <pre><code>{\n  \"name\": \"simple-storage\",\n  \"interface\": {\n    \"id\": \"8bdd27a5-67c1-4960-8d1e-7aa31b9084d3\"\n  },\n  \"location\": {\n    \"address\": \"0xa5ea5d0a6b2eaf194716f0cc73981939dca26da1\"\n  }\n}\n</code></pre>"},{"location":"tutorials/custom_contracts/ethereum/#response_3","title":"Response","text":"<pre><code>{\n  \"id\": \"9a681ec6-1dee-42a0-b91b-61d23a814b0f\",\n  \"namespace\": \"default\",\n  \"interface\": {\n    \"id\": \"8bdd27a5-67c1-4960-8d1e-7aa31b9084d3\"\n  },\n  \"location\": {\n    \"address\": \"0xa5ea5d0a6b2eaf194716f0cc73981939dca26da1\"\n  },\n  \"name\": \"simple-storage\",\n  \"message\": \"d90d0386-8874-43fb-b7d3-485c22f35f47\",\n  \"urls\": {\n    \"openapi\": \"http://127.0.0.1:5000/api/v1/namespaces/default/apis/simple-storage/api/swagger.json\",\n    \"ui\": \"http://127.0.0.1:5000/api/v1/namespaces/default/apis/simple-storage/api\"\n  },\n  \"published\": true\n}\n</code></pre>"},{"location":"tutorials/custom_contracts/ethereum/#view-openapi-spec-for-the-contract","title":"View OpenAPI spec for the contract","text":"<p>You'll notice in the response body that there are a couple of URLs near the bottom. If you navigate to the one labeled <code>ui</code> in your browser, you should see the Swagger UI for your smart contract.</p> <p></p>"},{"location":"tutorials/custom_contracts/ethereum/#invoke-the-smart-contract","title":"Invoke the smart contract","text":"<p>Now that we've got everything set up, it's time to use our smart contract! We're going to make a <code>POST</code> request to the <code>invoke/set</code> endpoint to set the integer value on-chain. Let's set it to the value of <code>3</code> right now.</p>"},{"location":"tutorials/custom_contracts/ethereum/#request_4","title":"Request","text":"<p><code>POST</code> <code>http://localhost:5000/api/v1/namespaces/default/apis/simple-storage/invoke/set</code></p> <pre><code>{\n  \"input\": {\n    \"newValue\": 3\n  }\n}\n</code></pre>"},{"location":"tutorials/custom_contracts/ethereum/#response_4","title":"Response","text":"<pre><code>{\n  \"id\": \"41c67c63-52cf-47ce-8a59-895fe2ffdc86\"\n}\n</code></pre> <p>You'll notice that we just get an ID back here, and that's expected due to the asynchronous programming model of working with smart contracts in FireFly. To see what the value is now, we can query the smart contract. In a little bit, we'll also subscribe to the events emitted by this contract so we can know when the value is updated in realtime.</p>"},{"location":"tutorials/custom_contracts/ethereum/#query-the-current-value","title":"Query the current value","text":"<p>To make a read-only request to the blockchain to check the current value of the stored integer, we can make a <code>POST</code> to the <code>query/get</code> endpoint.</p>"},{"location":"tutorials/custom_contracts/ethereum/#request_5","title":"Request","text":"<p><code>POST</code> <code>http://localhost:5000/api/v1/namespaces/default/apis/simple-storage/query/get</code></p> <pre><code>{}\n</code></pre>"},{"location":"tutorials/custom_contracts/ethereum/#response_5","title":"Response","text":"<pre><code>{\n  \"output\": \"3\"\n}\n</code></pre> <p>NOTE: Some contracts may have queries that require input parameters. That's why the query endpoint is a <code>POST</code>, rather than a <code>GET</code> so that parameters can be passed as JSON in the request body. This particular function does not have any parameters, so we just pass an empty JSON object.</p>"},{"location":"tutorials/custom_contracts/ethereum/#passing-additional-options-with-a-request","title":"Passing additional options with a request","text":"<p>Some smart contract functions may accept or require additional options to be passed with the request. For example, a Solidity function might be <code>payable</code>, meaning that a <code>value</code> field must be specified, indicating an amount of ETH to be transferred with the request. Each of your smart contract API's <code>/invoke</code> or <code>/query</code> endpoints support an <code>options</code> object in addition to the <code>input</code> arguments for the function itself.</p> <p>Here is an example of sending 100 wei with a transaction:</p>"},{"location":"tutorials/custom_contracts/ethereum/#request_6","title":"Request","text":"<p><code>POST</code> <code>http://localhost:5000/api/v1/namespaces/default/apis/simple-storage/invoke/set</code></p> <pre><code>{\n  \"input\": {\n    \"newValue\": 3\n  },\n  \"options\": {\n    \"value\": 100\n  }\n}\n</code></pre>"},{"location":"tutorials/custom_contracts/ethereum/#response_6","title":"Response","text":"<pre><code>{\n  \"id\": \"41c67c63-52cf-47ce-8a59-895fe2ffdc86\"\n}\n</code></pre>"},{"location":"tutorials/custom_contracts/ethereum/#create-a-blockchain-event-listener","title":"Create a blockchain event listener","text":"<p>Now that we've seen how to submit transactions and preform read-only queries to the blockchain, let's look at how to receive blockchain events so we know when things are happening in realtime.</p> <p>If you look at the source code for the smart contract we're working with above, you'll notice that it emits an event when the stored value of the integer is set. In order to receive these events, we first need to instruct FireFly to listen for this specific type of blockchain event. To do this, we create an Event Listener. The <code>/contracts/listeners</code> endpoint is RESTful so there are <code>POST</code>, <code>GET</code>, and <code>DELETE</code> methods available on it. To create a new listener, we will make a <code>POST</code> request. We are going to tell FireFly to listen to events with name <code>\"Changed\"</code> from the FireFly Interface we defined earlier, referenced by its ID. We will also tell FireFly which contract address we expect to emit these events, and the topic to assign these events to. You can specify multiple filters for a listener, in this case we only specify one for our event. Topics are a way for applications to subscribe to events they are interested in.</p>"},{"location":"tutorials/custom_contracts/ethereum/#request_7","title":"Request","text":"<p><code>POST</code> <code>http://localhost:5000/api/v1/namespaces/default/contracts/listeners</code></p> <pre><code>{\n  \"filters\": [\n    {\n      \"interface\": {\n        \"id\": \"8bdd27a5-67c1-4960-8d1e-7aa31b9084d3\"\n      },\n      \"location\": {\n        \"address\": \"0xa5ea5d0a6b2eaf194716f0cc73981939dca26da1\"\n      },\n      \"eventPath\": \"Changed\"\n    }\n  ],\n  \"options\": {\n    \"firstEvent\": \"newest\"\n  },\n  \"topic\": \"simple-storage\"\n}\n</code></pre>"},{"location":"tutorials/custom_contracts/ethereum/#response_7","title":"Response","text":"<pre><code>{\n  \"id\": \"e7c8457f-4ffd-42eb-ac11-4ad8aed30de1\",\n  \"interface\": {\n    \"id\": \"55fdb62a-fefc-4313-99e4-e3f95fcca5f0\"\n  },\n  \"namespace\": \"default\",\n  \"name\": \"019104d7-bb0a-c008-76a9-8cb923d91b37\",\n  \"backendId\": \"019104d7-bb0a-c008-76a9-8cb923d91b37\",\n  \"location\": {\n    \"address\": \"0xa5ea5d0a6b2eaf194716f0cc73981939dca26da1\"\n  },\n  \"created\": \"2024-07-30T18:12:12.704964Z\",\n  \"event\": {\n    \"name\": \"Changed\",\n    \"description\": \"\",\n    \"params\": [\n      {\n        \"name\": \"from\",\n        \"schema\": {\n          \"type\": \"string\",\n          \"details\": {\n            \"type\": \"address\",\n            \"internalType\": \"address\",\n            \"indexed\": true\n          }\n        }\n      },\n      {\n        \"name\": \"value\",\n        \"schema\": {\n          \"type\": \"integer\",\n          \"details\": {\n            \"type\": \"uint256\",\n            \"internalType\": \"uint256\"\n          }\n        }\n      }\n    ]\n  },\n  \"signature\": \"0xa5ea5d0a6b2eaf194716f0cc73981939dca26da1:Changed(address,uint256) [i=0]\",\n  \"topic\": \"simple-storage\",\n  \"options\": {\n    \"firstEvent\": \"newest\"\n  },\n  \"filters\": [\n    {\n      \"event\": {\n        \"name\": \"Changed\",\n        \"description\": \"\",\n        \"params\": [\n          {\n            \"name\": \"from\",\n            \"schema\": {\n              \"type\": \"string\",\n              \"details\": {\n                \"type\": \"address\",\n                \"internalType\": \"address\",\n                \"indexed\": true\n              }\n            }\n          },\n          {\n            \"name\": \"value\",\n            \"schema\": {\n              \"type\": \"integer\",\n              \"details\": {\n                \"type\": \"uint256\",\n                \"internalType\": \"uint256\"\n              }\n            }\n          }\n        ]\n      },\n      \"location\": {\n        \"address\": \"0xa5ea5d0a6b2eaf194716f0cc73981939dca26da1\"\n      },\n      \"interface\": {\n        \"id\": \"55fdb62a-fefc-4313-99e4-e3f95fcca5f0\"\n      },\n      \"signature\": \"0xa5ea5d0a6b2eaf194716f0cc73981939dca26da1:Changed(address,uint256) [i=0]\"\n    }\n  ]\n}\n</code></pre> <p>We can see in the response, that FireFly pulls all the schema information from the FireFly Interface that we broadcasted earlier and creates the listener with that schema. This is useful so that we don't have to enter all of that data again.</p>"},{"location":"tutorials/custom_contracts/ethereum/#querying-listener-status","title":"Querying listener status","text":"<p>If you are interested in learning about the current state of a listener you have created, you can query with the <code>fetchstatus</code> parameter. For FireFly stacks with an EVM compatible blockchain connector, the response will include checkpoint information and if the listener is currently in catchup mode.</p>"},{"location":"tutorials/custom_contracts/ethereum/#request-response","title":"Request / Response","text":"<p><code>GET</code> <code>http://localhost:5000/api/v1/namespaces/default/contracts/listeners/1bfa3b0f-3d90-403e-94a4-af978d8c5b14?fetchstatus</code></p> <pre><code>{\n  \"id\": \"1bfa3b0f-3d90-403e-94a4-af978d8c5b14\",\n  \"interface\": {\n    \"id\": \"8bdd27a5-67c1-4960-8d1e-7aa31b9084d3\"\n  },\n  \"namespace\": \"default\",\n  \"name\": \"sb-66209ffc-d355-4ac0-7151-bc82490ca9df\",\n  \"protocolId\": \"sb-66209ffc-d355-4ac0-7151-bc82490ca9df\",\n  \"location\": {\n    \"address\": \"0xa5ea5d0a6b2eaf194716f0cc73981939dca26da1\"\n  },\n  \"created\": \"2022-02-17T22:02:36.34549538Z\",\n  \"event\": {\n    \"name\": \"Changed\",\n    \"description\": \"\",\n    \"params\": [\n      {\n        \"name\": \"from\",\n        \"schema\": {\n          \"type\": \"string\",\n          \"details\": {\n            \"type\": \"address\",\n            \"internalType\": \"address\",\n            \"indexed\": true\n          }\n        }\n      },\n      {\n        \"name\": \"value\",\n        \"schema\": {\n          \"type\": \"integer\",\n          \"details\": {\n            \"type\": \"uint256\",\n            \"internalType\": \"uint256\"\n          }\n        }\n      }\n    ]\n  },\n  \"status\": {\n    \"checkpoint\": {\n      \"block\": 0,\n      \"transactionIndex\": -1,\n      \"logIndex\": -1\n    },\n    \"catchup\": true\n  },\n  \"options\": {\n    \"firstEvent\": \"oldest\"\n  }\n}\n</code></pre>"},{"location":"tutorials/custom_contracts/ethereum/#subscribe-to-events-from-our-contract","title":"Subscribe to events from our contract","text":"<p>Now that we've told FireFly that it should listen for specific events on the blockchain, we can set up a Subscription for FireFly to send events to our app. To set up our subscription, we will make a <code>POST</code> to the <code>/subscriptions</code> endpoint.</p> <p>We will set a friendly name <code>simple-storage</code> to identify the Subscription when we are connecting to it in the next step.</p> <p>We're also going to set up a filter to only send events blockchain events from our listener that we created in the previous step. To do that, we'll copy the listener ID from the step above (<code>1bfa3b0f-3d90-403e-94a4-af978d8c5b14</code>) and set that as the value of the <code>listener</code> field in the example below:</p>"},{"location":"tutorials/custom_contracts/ethereum/#request_8","title":"Request","text":"<p><code>POST</code> <code>http://localhost:5000/api/v1/namespaces/default/subscriptions</code></p> <pre><code>{\n  \"namespace\": \"default\",\n  \"name\": \"simple-storage\",\n  \"transport\": \"websockets\",\n  \"filter\": {\n    \"events\": \"blockchain_event_received\",\n    \"blockchainevent\": {\n      \"listener\": \"1bfa3b0f-3d90-403e-94a4-af978d8c5b14\"\n    }\n  },\n  \"options\": {\n    \"firstEvent\": \"oldest\"\n  }\n}\n</code></pre>"},{"location":"tutorials/custom_contracts/ethereum/#response_8","title":"Response","text":"<pre><code>{\n  \"id\": \"f826269c-65ed-4634-b24c-4f399ec53a32\",\n  \"namespace\": \"default\",\n  \"name\": \"simple-storage\",\n  \"transport\": \"websockets\",\n  \"filter\": {\n    \"events\": \"blockchain_event_received\",\n    \"message\": {},\n    \"transaction\": {},\n    \"blockchainevent\": {\n      \"listener\": \"1bfa3b0f-3d90-403e-94a4-af978d8c5b14\"\n    }\n  },\n  \"options\": {\n    \"firstEvent\": \"-1\",\n    \"withData\": false\n  },\n  \"created\": \"2022-03-15T17:35:30.131698921Z\",\n  \"updated\": null\n}\n</code></pre>"},{"location":"tutorials/custom_contracts/ethereum/#receive-custom-smart-contract-events","title":"Receive custom smart contract events","text":"<p>The last step is to connect a WebSocket client to FireFly to receive the event. You can use any WebSocket client you like, such as Postman or a command line app like <code>websocat</code>.</p> <p>Connect your WebSocket client to <code>ws://localhost:5000/ws</code>.</p> <p>After connecting the WebSocket client, send a message to tell FireFly to:</p> <ul> <li>Start sending events</li> <li>For the Subscription named <code>simple-storage</code></li> <li>On the <code>default</code> namespace</li> <li>Automatically \"ack\" each event which will let FireFly immediately send the next event when available</li> </ul> <pre><code>{\n  \"type\": \"start\",\n  \"name\": \"simple-storage\",\n  \"namespace\": \"default\",\n  \"autoack\": true\n}\n</code></pre>"},{"location":"tutorials/custom_contracts/ethereum/#websocket-event","title":"WebSocket event","text":"<p>After creating the subscription, you should see an event arrive on the connected WebSocket client that looks something like this:</p> <pre><code>{\n  \"id\": \"0f4a31d6-9743-4537-82df-5a9c76ccbd1e\",\n  \"sequence\": 24,\n  \"type\": \"blockchain_event_received\",\n  \"namespace\": \"default\",\n  \"reference\": \"dd3e1554-c832-47a8-898e-f1ee406bea41\",\n  \"created\": \"2022-03-15T17:32:27.824417878Z\",\n  \"blockchainevent\": {\n    \"id\": \"dd3e1554-c832-47a8-898e-f1ee406bea41\",\n    \"sequence\": 7,\n    \"source\": \"ethereum\",\n    \"namespace\": \"default\",\n    \"name\": \"Changed\",\n    \"listener\": \"1bfa3b0f-3d90-403e-94a4-af978d8c5b14\",\n    \"protocolId\": \"000000000010/000000/000000\",\n    \"output\": {\n      \"from\": \"0xb7e6a5eb07a75a2c81801a157192a82bcbce0f21\",\n      \"value\": \"3\"\n    },\n    \"info\": {\n      \"address\": \"0xa5ea5d0a6b2eaf194716f0cc73981939dca26da1\",\n      \"blockNumber\": \"10\",\n      \"logIndex\": \"0\",\n      \"signature\": \"Changed(address,uint256)\",\n      \"subId\": \"sb-724b8416-786d-4e67-4cd3-5bae4a26eb0e\",\n      \"timestamp\": \"1647365460\",\n      \"transactionHash\": \"0xd5b5c716554097b2868d8705241bb2189bb76d16300f702ad05b0b02fccc4afb\",\n      \"transactionIndex\": \"0x0\"\n    },\n    \"timestamp\": \"2022-03-15T17:31:00Z\",\n    \"tx\": {\n      \"type\": \"\"\n    }\n  },\n  \"subscription\": {\n    \"id\": \"f826269c-65ed-4634-b24c-4f399ec53a32\",\n    \"namespace\": \"default\",\n    \"name\": \"simple-storage\"\n  }\n}\n</code></pre> <p>You can see in the event received over the WebSocket connection, the blockchain event that was emitted from our first transaction, which happened in the past. We received this event, because when we set up both the Listener, and the Subscription, we specified the <code>\"firstEvent\"</code> as <code>\"oldest\"</code>. This tells FireFly to look for this event from the beginning of the blockchain, and that your app is interested in FireFly events since the beginning of FireFly's event history.</p> <p>In the event, we can also see the <code>blockchainevent</code> itself, which has an <code>output</code> object. These are the <code>params</code> in our FireFly Interface, and the actual output of the event. Here we can see the <code>value</code> is <code>3</code> which is what we set the integer to in our original transaction.</p>"},{"location":"tutorials/custom_contracts/ethereum/#subscription-offset","title":"Subscription offset","text":"<p>If you query by the ID of your subscription with the <code>fetchstatus</code> parameter, you can see its current <code>offset</code>.</p> <p><code>GET</code> <code>http://localhost:5000/api/v1/namespaces/default/subscriptions/f826269c-65ed-4634-b24c-4f399ec53a32</code></p> <pre><code>{\n  \"id\": \"f826269c-65ed-4634-b24c-4f399ec53a32\",\n  \"namespace\": \"default\",\n  \"name\": \"simple-storage\",\n  \"transport\": \"websockets\",\n  \"filter\": {\n    \"events\": \"blockchain_event_received\",\n    \"message\": {},\n    \"transaction\": {},\n    \"blockchainevent\": {\n      \"listener\": \"1bfa3b0f-3d90-403e-94a4-af978d8c5b14\"\n    }\n  },\n  \"options\": {\n    \"firstEvent\": \"-1\",\n    \"withData\": false\n  },\n  \"status\": {\n    \"offset\": 20\n  }\n  \"created\": \"2022-03-15T17:35:30.131698921Z\",\n  \"updated\": null\n}\n</code></pre> <p>You've reached the end of the main guide to working with custom smart contracts in FireFly. Hopefully this was helpful and gives you what you need to get up and running with your own contracts. There are several additional ways to invoke or query smart contracts detailed below, so feel free to keep reading if you're curious.</p>"},{"location":"tutorials/custom_contracts/ethereum/#appendix-i-work-with-a-custom-contract-without-creating-a-named-api","title":"Appendix I: Work with a custom contract without creating a named API","text":"<p>FireFly aims to offer a developer-friendly and flexible approach to using custom smart contracts. The guide above has detailed the most robust and feature-rich way to use custom contracts with FireFly, but there are several alternative API usage patterns available as well.</p> <p>It is possible to broadcast a contract interface and use a smart contract that implements that interface without also broadcasting a named API as above. There are several key differences (which may or may not be desirable) compared to the method outlined in the full guide above:</p> <ul> <li>OpenAPI Spec and Swagger UI are not available</li> <li>Each HTTP request to invoke/query the contract will need to include the contract location</li> <li>The contract location will not have been broadcasted to all other members of the network</li> <li>The URL to invoke/query the contract will be different (described below)</li> </ul>"},{"location":"tutorials/custom_contracts/ethereum/#request_9","title":"Request","text":"<p><code>POST</code> <code>http://localhost:5000/api/v1/namespaces/default/contracts/interfaces/8bdd27a5-67c1-4960-8d1e-7aa31b9084d3/invoke/set</code></p> <pre><code>{\n  \"location\": {\n    \"address\": \"0xa5ea5d0a6b2eaf194716f0cc73981939dca26da1\"\n  },\n  \"input\": {\n    \"newValue\": 7\n  }\n}\n</code></pre>"},{"location":"tutorials/custom_contracts/ethereum/#response_9","title":"Response","text":"<pre><code>{\n  \"id\": \"f310fa4a-73d8-4777-9f9d-dfa5012a052f\"\n}\n</code></pre> <p>All of the same invoke, query, and subscribe endpoints are available on the contract interface itself.</p>"},{"location":"tutorials/custom_contracts/ethereum/#appendix-ii-work-directly-with-contracts-with-inline-requests","title":"Appendix II: Work directly with contracts with inline requests","text":"<p>The final way of working with custom smart contracts with FireFly is to just put everything FireFly needs all in one request, each time a contract is invoked or queried. This is the most lightweight, but least feature-rich way of using a custom contract.</p> <p>To do this, we will need to put both the contract location, and a subset of the FireFly Interface that describes the method we want to invoke in the request body, in addition to the function input.</p>"},{"location":"tutorials/custom_contracts/ethereum/#request_10","title":"Request","text":"<p><code>POST</code> <code>http://localhost:5000/api/v1/namespaces/default/contracts/invoke</code></p> <pre><code>{\n  \"location\": {\n    \"address\": \"0xa5ea5d0a6b2eaf194716f0cc73981939dca26da1\"\n  },\n  \"method\": {\n    \"name\": \"set\",\n    \"params\": [\n      {\n        \"name\": \"x\",\n        \"schema\": {\n          \"type\": \"integer\",\n          \"details\": {\n            \"type\": \"uint256\"\n          }\n        }\n      }\n    ],\n    \"returns\": []\n  },\n  \"input\": {\n    \"x\": 42\n  }\n}\n</code></pre>"},{"location":"tutorials/custom_contracts/ethereum/#response_10","title":"Response","text":"<pre><code>{\n  \"id\": \"386d3e23-e4bc-4a9b-bc1f-452f0a8c9ae5\"\n}\n</code></pre>"},{"location":"tutorials/custom_contracts/fabric/","title":"Work with Hyperledger Fabric chaincodes","text":"<p>This guide describes the steps to deploy a chaincode to a Hyperledger Fabric blockchain and use FireFly to interact with it in order to submit transactions, query for states and listening for events.</p> <p>NOTE: This guide assumes that you are running a local FireFly stack with at least 2 members and a Fabric blockchain created by the FireFly CLI. If you need help getting that set up, please see the Getting Started guide to Start your environment.</p>"},{"location":"tutorials/custom_contracts/fabric/#example-smart-contract","title":"Example smart contract","text":"<p>For this tutorial, we will be using a well known, but slightly modified smart contract called <code>asset_transfer</code>. It's based on the <code>asset-transfer-basic</code> chaincode in the fabric-samples project. Check out the code repository and use the source code provided below to replace part of the content of the file <code>fabric-samples/asset-transfer-basic/chaincode-go/chaincode/smartcontract.go</code>.</p> <p>Find the following return statement in the function <code>CreateAsset</code>:</p> <pre><code>    return ctx.GetStub().PutState(id, assetJSON)\n</code></pre> <p>and replace it with the following, so that an event will be emitted when the transaction is committed to the channel ledger:</p> <pre><code>  err = ctx.GetStub().PutState(id, assetJSON)\n  if err != nil {\n    return err\n  }\n  return ctx.GetStub().SetEvent(\"AssetCreated\", assetJSON)\n</code></pre>"},{"location":"tutorials/custom_contracts/fabric/#create-the-chaincode-package","title":"Create the chaincode package","text":"<p>Use the <code>peer</code> command to create the chaincode package for deployment. You can download the peer binary from the releases page of the Fabric project or build it from source.</p> <pre><code>  ~ johndoe$ cd fabric-samples/asset-transfer-basic/chaincode-go\n  chaincode-go johndoe$ touch core.yaml\n  chaincode-go johndoe$ peer lifecycle chaincode package -p . --label asset_transfer ./asset_transfer.zip\n</code></pre> <p>The <code>peer</code> command requires an empty core.yaml file to be present in the working directory to perform the packaging. That's what <code>touch core.yaml</code> did above</p> <p>The resulting <code>asset_transfer.zip</code> archive file will be used in the next step to deploy to the Fabric network used in FireFly.</p>"},{"location":"tutorials/custom_contracts/fabric/#contract-deployment","title":"Contract deployment","text":"<p>Deployment of smart contracts is not currently within the scope of responsibility for FireFly. You can use your standard blockchain specific tools to deploy your contract to the blockchain you are using.</p> <p>The FireFly CLI provides a convenient function to deploy a chaincode package to a local FireFly stack.</p> <p>NOTE: The contract deployment function of the FireFly CLI is a convenience function to speed up local development, and not intended for production applications</p> <pre><code>~ johndoe$ ff help deploy fabric\nDeploy a packaged chaincode to the Fabric network used by a FireFly stack\n\nUsage:\n  ff deploy fabric &lt;stack_name&gt; &lt;chaincode_package&gt; &lt;channel&gt; &lt;chaincodeName&gt; &lt;version&gt; [flags]\n</code></pre> <p>Notice the various parameters used by the command <code>ff deploy fabric</code>. We'll tell the FireFly to deploy using the following parameter values, if your stack setup is different, update the command accordingly:</p> <ul> <li>stack name: <code>dev</code></li> <li>channel: <code>firefly</code> (this is the channel that is created by the FireFly CLI when bootstrapping the stack, replace if you use a different channel in your setup)</li> <li>chaincode name: <code>asset_transfer</code> (must match the value of the <code>--label</code> parameter when creating the chaincode package)</li> <li>version: <code>1.0</code></li> </ul> <pre><code>$ ff deploy fabric dev asset_transfer.zip firefly asset_transfer 1.0\ninstalling chaincode\nquerying installed chaincode\napproving chaincode\ncommitting chaincode\n{\n  \"chaincode\": \"asset_transfer\",\n  \"channel\": \"firefly\"\n}\n</code></pre>"},{"location":"tutorials/custom_contracts/fabric/#the-firefly-interface-format","title":"The FireFly Interface Format","text":"<p>In order to teach FireFly how to interact with the chaincode, a FireFly Interface (FFI) document is needed. While Ethereum (or other EVM based blockchains) requires an Application Binary Interface (ABI) to govern the interaction between the client and the smart contract, which is specific to each smart contract interface design, Fabric defines a generic chaincode interface and leaves the encoding and decoding of the parameter values to the discretion of the chaincode developer.</p> <p>As a result, the FFI document for a Fabric chaincode must be hand-crafted. The following FFI sample demonstrates the specification for the following common cases:</p> <ul> <li>structured JSON, used here for the list of chaincode function <code>CreateAsset</code> input parameters</li> <li>array of JSON, used here for the chaincode function <code>GetAllAssets</code> output</li> <li>structured JSON, used here for the list of chaincode event <code>AssetCreated</code> properties</li> </ul> <pre><code>{\n  \"namespace\": \"default\",\n  \"name\": \"asset_transfer\",\n  \"description\": \"Spec interface for the asset-transfer-basic golang chaincode\",\n  \"version\": \"1.0\",\n  \"methods\": [\n    {\n      \"name\": \"GetAllAssets\",\n      \"pathname\": \"\",\n      \"description\": \"\",\n      \"params\": [],\n      \"returns\": [\n        {\n          \"name\": \"\",\n          \"schema\": {\n            \"type\": \"array\",\n            \"details\": {\n              \"type\": \"object\",\n              \"properties\": {\n                \"type\": \"string\"\n              }\n            }\n          }\n        }\n      ]\n    },\n    {\n      \"name\": \"CreateAsset\",\n      \"pathname\": \"\",\n      \"description\": \"\",\n      \"params\": [\n        {\n          \"name\": \"id\",\n          \"schema\": {\n            \"type\": \"string\"\n          }\n        },\n        {\n          \"name\": \"color\",\n          \"schema\": {\n            \"type\": \"string\"\n          }\n        },\n        {\n          \"name\": \"size\",\n          \"schema\": {\n            \"type\": \"string\"\n          }\n        },\n        {\n          \"name\": \"owner\",\n          \"schema\": {\n            \"type\": \"string\"\n          }\n        },\n        {\n          \"name\": \"value\",\n          \"schema\": {\n            \"type\": \"string\"\n          }\n        }\n      ],\n      \"returns\": []\n    }\n  ],\n  \"events\": [\n    {\n      \"name\": \"AssetCreated\"\n    }\n  ]\n}\n</code></pre>"},{"location":"tutorials/custom_contracts/fabric/#input-parameters","title":"Input parameters","text":"<p>For the <code>params</code> section of the <code>CreateAsset</code> function, it is critical that the sequence of the properties (<code>id</code>, <code>color</code>, <code>size</code>, <code>owner</code>, <code>value</code>) matches the order of the input parameters in the chaincode's function signature:</p> <pre><code>func CreateAsset(ctx contractapi.TransactionContextInterface, id string, color string, size int, owner string, appraisedValue int) error\n</code></pre>"},{"location":"tutorials/custom_contracts/fabric/#return-values","title":"Return values","text":"<p>FireFly can automatically decode JSON payloads in the return values. That's why the <code>returns</code> section of the <code>GetAllAssets</code> function only needs to specify the type as <code>array of objects</code>, without having to specify the detailed structure of the JSON payload.</p> <p>On the other hand, if certain properties of the returned value are to be hidden, then you can provide a detailed structure of the JSON object with the desired properties. This is demonstrated in the JSON structure for the event payload, see below, where the property <code>AppraisedValue</code> is omitted from the output.</p>"},{"location":"tutorials/custom_contracts/fabric/#event-payloads","title":"Event payloads","text":"<p>For events, FireFly automatically decodes JSON payloads. If the event payload is not JSON, base64 encoded bytes will be returned instead. For the <code>events</code> section of the FFI, only the <code>name</code> property needs to be specified.</p>"},{"location":"tutorials/custom_contracts/fabric/#broadcast-the-contract-interface","title":"Broadcast the contract interface","text":"<p>Now that we have a FireFly Interface representation of our chaincode, we want to broadcast that to the entire network. This broadcast will be pinned to the blockchain, so we can always refer to this specific name and version, and everyone in the network will know exactly which contract interface we are talking about.</p> <p>We will use the FFI JSON constructed above and <code>POST</code> that to the <code>/contracts/interfaces</code> API endpoint.</p>"},{"location":"tutorials/custom_contracts/fabric/#request","title":"Request","text":"<p><code>POST</code> <code>http://localhost:5000/api/v1/namespaces/default/contracts/interfaces?publish=true</code></p> <p>NOTE: Without passing the query parameter <code>publish=true</code> when the interface is created, it will initially be unpublished and not broadcasted to other members of the network (if configured in multi-party). To publish the interface, a subsequent API call would need to be made to <code>/contracts/interfaces/{name}/{version}/publish</code></p> <pre><code>{\n  \"namespace\": \"default\",\n  \"name\": \"asset_transfer\",\n  \"description\": \"Spec interface for the asset-transfer-basic golang chaincode\",\n  \"version\": \"1.0\",\n  \"methods\": [\n    {\n      \"name\": \"GetAllAssets\",\n      \"pathname\": \"\",\n      \"description\": \"\",\n      \"params\": [],\n      \"returns\": [\n        {\n          \"name\": \"\",\n          \"schema\": {\n            \"type\": \"array\",\n            \"details\": {\n              \"type\": \"object\",\n              \"properties\": {\n                \"type\": \"string\"\n              }\n            }\n          }\n        }\n      ]\n    },\n    {\n      \"name\": \"CreateAsset\",\n      \"pathname\": \"\",\n      \"description\": \"\",\n      \"params\": [\n        {\n          \"name\": \"id\",\n          \"schema\": {\n            \"type\": \"string\"\n          }\n        },\n        {\n          \"name\": \"color\",\n          \"schema\": {\n            \"type\": \"string\"\n          }\n        },\n        {\n          \"name\": \"size\",\n          \"schema\": {\n            \"type\": \"string\"\n          }\n        },\n        {\n          \"name\": \"owner\",\n          \"schema\": {\n            \"type\": \"string\"\n          }\n        },\n        {\n          \"name\": \"value\",\n          \"schema\": {\n            \"type\": \"string\"\n          }\n        }\n      ],\n      \"returns\": []\n    }\n  ],\n  \"events\": [\n    {\n      \"name\": \"AssetCreated\"\n    }\n  ]\n}\n</code></pre>"},{"location":"tutorials/custom_contracts/fabric/#response","title":"Response","text":"<pre><code>{\n  \"id\": \"f1e5522c-59a5-4787-bbfd-89975e5b0954\",\n  \"message\": \"8a01fc83-5729-418b-9706-6fc17c8d2aac\",\n  \"namespace\": \"default\",\n  \"name\": \"asset_transfer\",\n  \"description\": \"Spec interface for the asset-transfer-basic golang chaincode\",\n  \"version\": \"1.1\",\n  \"methods\": [\n    {\n      \"id\": \"b31e3623-35e8-4918-bf8c-1b0d6c01de25\",\n      \"interface\": \"f1e5522c-59a5-4787-bbfd-89975e5b0954\",\n      \"name\": \"GetAllAssets\",\n      \"namespace\": \"default\",\n      \"pathname\": \"GetAllAssets\",\n      \"description\": \"\",\n      \"params\": [],\n      \"returns\": [\n        {\n          \"name\": \"\",\n          \"schema\": {\n            \"type\": \"array\",\n            \"details\": {\n              \"type\": \"object\",\n              \"properties\": {\n                \"type\": \"string\"\n              }\n            }\n          }\n        }\n      ]\n    },\n    {\n      \"id\": \"e5a170d1-0be1-4697-800b-f4bcfaf71cf6\",\n      \"interface\": \"f1e5522c-59a5-4787-bbfd-89975e5b0954\",\n      \"name\": \"CreateAsset\",\n      \"namespace\": \"default\",\n      \"pathname\": \"CreateAsset\",\n      \"description\": \"\",\n      \"params\": [\n        {\n          \"name\": \"id\",\n          \"schema\": {\n            \"type\": \"string\"\n          }\n        },\n        {\n          \"name\": \"color\",\n          \"schema\": {\n            \"type\": \"string\"\n          }\n        },\n        {\n          \"name\": \"size\",\n          \"schema\": {\n            \"type\": \"string\"\n          }\n        },\n        {\n          \"name\": \"owner\",\n          \"schema\": {\n            \"type\": \"string\"\n          }\n        },\n        {\n          \"name\": \"value\",\n          \"schema\": {\n            \"type\": \"string\"\n          }\n        }\n      ],\n      \"returns\": []\n    }\n  ],\n  \"events\": [\n    {\n      \"id\": \"27564533-30bd-4536-884e-02e5d79ec238\",\n      \"interface\": \"f1e5522c-59a5-4787-bbfd-89975e5b0954\",\n      \"namespace\": \"default\",\n      \"pathname\": \"AssetCreated\",\n      \"signature\": \"\",\n      \"name\": \"AssetCreated\",\n      \"description\": \"\",\n      \"params\": null\n    }\n  ]\n}\n</code></pre> <p>NOTE: We can broadcast this contract interface conveniently with the help of FireFly Sandbox running at <code>http://127.0.0.1:5108</code></p> <ul> <li>Go to the <code>Contracts Section</code></li> <li>Click on <code>Define a Contract Interface</code></li> <li>Select <code>FFI - FireFly Interface</code> in the <code>Interface Fromat</code> dropdown</li> <li>Copy the <code>FFI JSON</code> crafted by you into the <code>Schema</code> Field</li> <li>Click on <code>Run</code></li> </ul>"},{"location":"tutorials/custom_contracts/fabric/#create-an-http-api-for-the-contract","title":"Create an HTTP API for the contract","text":"<p>Now comes the fun part where we see some of the powerful, developer-friendly features of FireFly. The next thing we're going to do is tell FireFly to build an HTTP API for this chaincode, complete with an OpenAPI Specification and Swagger UI. As part of this, we'll also tell FireFly where the chaincode is on the blockchain.</p> <p>Like the interface broadcast above, this will also generate a broadcast which will be pinned to the blockchain so all the members of the network will be aware of and able to interact with this API.</p> <p>We need to copy the <code>id</code> field we got in the response from the previous step to the <code>interface.id</code> field in the request body below. We will also pick a name that will be part of the URL for our HTTP API, so be sure to pick a name that is URL friendly. In this case we'll call it <code>asset_transfer</code>. Lastly, in the <code>location</code> field, we're telling FireFly where an instance of the chaincode is deployed on-chain, which is a chaincode named <code>asset_transfer</code> in the channel <code>firefly</code>.</p> <p>NOTE: The <code>location</code> field is optional here, but if it is omitted, it will be required in every request to invoke or query the chaincode. This can be useful if you have multiple instances of the same chaincode deployed to different channels.</p>"},{"location":"tutorials/custom_contracts/fabric/#request_1","title":"Request","text":"<p><code>POST</code> <code>http://localhost:5000/api/v1/namespaces/default/apis?publish=true</code></p> <p>NOTE: Without passing the query parameter <code>publish=true</code> when the API is created, it will initially be unpublished and not broadcasted to other members of the network (if configured in multi-party). To publish the API, a subsequent API call would need to be made to <code>/apis/{apiName}/publish</code></p> <pre><code>{\n  \"name\": \"asset_transfer\",\n  \"interface\": {\n    \"id\": \"f1e5522c-59a5-4787-bbfd-89975e5b0954\"\n  },\n  \"location\": {\n    \"channel\": \"firefly\",\n    \"chaincode\": \"asset_transfer\"\n  }\n}\n</code></pre>"},{"location":"tutorials/custom_contracts/fabric/#response_1","title":"Response","text":"<pre><code>{\n  \"id\": \"a9a9ab4e-2544-45d5-8824-3c05074fbf75\",\n  \"namespace\": \"default\",\n  \"interface\": {\n    \"id\": \"f1e5522c-59a5-4787-bbfd-89975e5b0954\"\n  },\n  \"location\": {\n    \"channel\": \"firefly\",\n    \"chaincode\": \"asset_transfer\"\n  },\n  \"name\": \"asset_transfer\",\n  \"message\": \"5f1556a1-5cb1-4bc6-8611-d8f88ccf9c30\",\n  \"urls\": {\n    \"openapi\": \"http://127.0.0.1:5000/api/v1/namespaces/default/apis/asset_transfer/api/swagger.json\",\n    \"ui\": \"http://127.0.0.1:5000/api/v1/namespaces/default/apis/asset_transfer/api\"\n  }\n}\n</code></pre> <p>NOTE: We can create this Http API conveniently with the help of FireFly Sandbox running at <code>http://127.0.0.1:5108</code></p> <ul> <li>Go to the <code>Contracts Section</code></li> <li>Click on <code>Register a Contract API</code></li> <li>Select the name of your broadcasted FFI in the <code>Contract Interface</code> dropdown</li> <li>In the <code>Name</code> Field, give a name that will be part of the URL for your Http API</li> <li>In the <code>Chaincode</code> Field, give your chaincode name for which you wrote the FFI</li> <li>In the <code>Channel</code> Field, give the channel name where your chaincode is deployed</li> <li>Click on <code>Run</code></li> </ul>"},{"location":"tutorials/custom_contracts/fabric/#view-openapi-spec-for-the-contract","title":"View OpenAPI spec for the contract","text":"<p>You'll notice in the response body that there are a couple of URLs near the bottom. If you navigate to the one labeled <code>ui</code> in your browser, you should see the Swagger UI for your chaincode.</p> <p></p>"},{"location":"tutorials/custom_contracts/fabric/#invoke-endpoints","title":"/invoke/* endpoints","text":"<p>The <code>/invoke</code> endpoints in the generated API are for submitting transactions. These endpoints will be mapped to the <code>POST /transactions</code> endpoint of the FabConnect API.</p>"},{"location":"tutorials/custom_contracts/fabric/#query-endpoints","title":"/query/* endpoints","text":"<p>The <code>/query</code> endpoints in the generated API, on the other hand, are for sending query requests. These endpoints will be mapped to the <code>POST /query</code> endpoint of the Fabconnect API, which under the cover only sends chaincode endorsement requests to the target peer node without sending a trasaction payload to the orderer node.</p>"},{"location":"tutorials/custom_contracts/fabric/#invoke-the-chaincode","title":"Invoke the chaincode","text":"<p>Now that we've got everything set up, it's time to use our chaincode! We're going to make a <code>POST</code> request to the <code>invoke/CreateAsset</code> endpoint to create a new asset.</p>"},{"location":"tutorials/custom_contracts/fabric/#request_2","title":"Request","text":"<p><code>POST</code> <code>http://localhost:5000/api/v1/namespaces/default/apis/asset_transfer/invoke/CreateAsset</code></p> <pre><code>{\n  \"input\": {\n    \"color\": \"blue\",\n    \"id\": \"asset-01\",\n    \"owner\": \"Harry\",\n    \"size\": \"30\",\n    \"value\": \"23400\"\n  }\n}\n</code></pre>"},{"location":"tutorials/custom_contracts/fabric/#response_2","title":"Response","text":"<pre><code>{\n  \"id\": \"b8e905cc-bc23-434a-af7d-13c6d85ae545\",\n  \"namespace\": \"default\",\n  \"tx\": \"79d2668e-4626-4634-9448-1b40fa0d9dfd\",\n  \"type\": \"blockchain_invoke\",\n  \"status\": \"Pending\",\n  \"plugin\": \"fabric\",\n  \"input\": {\n    \"input\": {\n      \"color\": \"blue\",\n      \"id\": \"asset-02\",\n      \"owner\": \"Harry\",\n      \"size\": \"30\",\n      \"value\": \"23400\"\n    },\n    \"interface\": \"f1e5522c-59a5-4787-bbfd-89975e5b0954\",\n    \"key\": \"Org1MSP::x509::CN=org_0,OU=client::CN=fabric_ca.org1.example.com,OU=Hyperledger FireFly,O=org1.example.com,L=Raleigh,ST=North Carolina,C=US\",\n    \"location\": {\n      \"chaincode\": \"asset_transfer\",\n      \"channel\": \"firefly\"\n    },\n    \"method\": {\n      \"description\": \"\",\n      \"id\": \"e5a170d1-0be1-4697-800b-f4bcfaf71cf6\",\n      \"interface\": \"f1e5522c-59a5-4787-bbfd-89975e5b0954\",\n      \"name\": \"CreateAsset\",\n      \"namespace\": \"default\",\n      \"params\": [\n        {\n          \"name\": \"id\",\n          \"schema\": {\n            \"type\": \"string\"\n          }\n        },\n        {\n          \"name\": \"color\",\n          \"schema\": {\n            \"type\": \"string\"\n          }\n        },\n        {\n          \"name\": \"size\",\n          \"schema\": {\n            \"type\": \"string\"\n          }\n        },\n        {\n          \"name\": \"owner\",\n          \"schema\": {\n            \"type\": \"string\"\n          }\n        },\n        {\n          \"name\": \"value\",\n          \"schema\": {\n            \"type\": \"string\"\n          }\n        }\n      ],\n      \"pathname\": \"CreateAsset\",\n      \"returns\": []\n    },\n    \"methodPath\": \"CreateAsset\",\n    \"type\": \"invoke\"\n  },\n  \"created\": \"2022-05-02T17:08:40.811630044Z\",\n  \"updated\": \"2022-05-02T17:08:40.811630044Z\"\n}\n</code></pre> <p>You'll notice that we got an ID back with status <code>Pending</code>, and that's expected due to the asynchronous programming model of working with custom onchain logic in FireFly. To see what the latest state is now, we can query the chaincode. In a little bit, we'll also subscribe to the events emitted by this chaincode so we can know when the state is updated in realtime.</p>"},{"location":"tutorials/custom_contracts/fabric/#query-the-current-state","title":"Query the current state","text":"<p>To make a read-only request to the blockchain to check the current list of assets, we can make a <code>POST</code> to the <code>query/GetAllAssets</code> endpoint.</p>"},{"location":"tutorials/custom_contracts/fabric/#request_3","title":"Request","text":"<p><code>POST</code> <code>http://localhost:5000/api/v1/namespaces/default/apis/asset_transfer/query/GetAllAssets</code></p> <pre><code>{}\n</code></pre>"},{"location":"tutorials/custom_contracts/fabric/#response_3","title":"Response","text":"<pre><code>[\n  {\n    \"AppraisedValue\": 23400,\n    \"Color\": \"blue\",\n    \"ID\": \"asset-01\",\n    \"Owner\": \"Harry\",\n    \"Size\": 30\n  }\n]\n</code></pre> <p>NOTE: Some chaincodes may have queries that require input parameters. That's why the query endpoint is a <code>POST</code>, rather than a <code>GET</code> so that parameters can be passed as JSON in the request body. This particular function does not have any parameters, so we just pass an empty JSON object.</p>"},{"location":"tutorials/custom_contracts/fabric/#create-a-blockchain-event-listener","title":"Create a blockchain event listener","text":"<p>Now that we've seen how to submit transactions and preform read-only queries to the blockchain, let's look at how to receive blockchain events so we know when things are happening in realtime.</p> <p>If you look at the source code for the smart contract we're working with above, you'll notice that it emits an event when a new asset is created. In order to receive these events, we first need to instruct FireFly to listen for this specific type of blockchain event. To do this, we create an Event Listener.</p> <p>The <code>/contracts/listeners</code> endpoint is RESTful so there are <code>POST</code>, <code>GET</code>, and <code>DELETE</code> methods available on it. To create a new listener, we will make a <code>POST</code> request. We are going to tell FireFly to listen to events with name <code>\"AssetCreated\"</code> from the FireFly Interface we defined earlier, referenced by its ID. We will also tell FireFly which channel and chaincode we expect to emit these events.</p>"},{"location":"tutorials/custom_contracts/fabric/#request_4","title":"Request","text":"<p><code>POST</code> <code>http://localhost:5000/api/v1/namespaces/default/contracts/listeners</code></p> <pre><code>{\n  \"filters\": [\n    {\n      \"interface\": {\n        \"id\": \"f1e5522c-59a5-4787-bbfd-89975e5b0954\"\n      },\n      \"location\": {\n        \"channel\": \"firefly\",\n        \"chaincode\": \"asset_transfer\"\n      },\n      \"event\": {\n        \"name\": \"AssetCreated\"\n      }\n    }\n  ],\n  \"options\": {\n    \"firstEvent\": \"oldest\"\n  },\n  \"topic\": \"assets\"\n}\n</code></pre>"},{"location":"tutorials/custom_contracts/fabric/#response_4","title":"Response","text":"<pre><code>{\n  \"id\": \"d6b5e774-c9e5-474c-9495-ec07fa47a907\",\n  \"namespace\": \"default\",\n  \"name\": \"sb-44aa348a-bafb-4243-594e-dcad689f1032\",\n  \"backendId\": \"sb-44aa348a-bafb-4243-594e-dcad689f1032\",\n  \"location\": {\n    \"channel\": \"firefly\",\n    \"chaincode\": \"asset_transfer\"\n  },\n  \"created\": \"2024-07-22T15:36:58.514085959Z\",\n  \"event\": {\n    \"name\": \"AssetCreated\",\n    \"description\": \"\",\n    \"params\": null\n  },\n  \"signature\": \"firefly-asset_transfer:AssetCreated\",\n  \"topic\": \"assets\",\n  \"options\": {\n    \"firstEvent\": \"oldest\"\n  },\n  \"filters\": [\n    {\n      \"event\": {\n        \"name\": \"AssetCreated\",\n        \"description\": \"\",\n        \"params\": null\n      },\n      \"location\": {\n        \"channel\": \"firefly\",\n        \"chaincode\": \"asset_transfer\"\n      },\n      \"signature\": \"firefly-asset_transfer:AssetCreated\"\n    }\n  ]\n}\n</code></pre>"},{"location":"tutorials/custom_contracts/fabric/#subscribe-to-events-from-our-contract","title":"Subscribe to events from our contract","text":"<p>Now that we've told FireFly that it should listen for specific events on the blockchain, we can set up a Subscription for FireFly to send events to our client app. To set up our subscription, we will make a <code>POST</code> to the <code>/subscriptions</code> endpoint.</p> <p>We will set a friendly name <code>asset_transfer</code> to identify the Subscription when we are connecting to it in the next step.</p> <p>We're also going to set up a filter to only send events blockchain events from our listener that we created in the previous step. To do that, we'll copy the listener ID from the step above (<code>6e7f5dd8-5a57-4163-a1d2-5654e784dc31</code>) and set that as the value of the <code>listener</code> field in the example below:</p>"},{"location":"tutorials/custom_contracts/fabric/#request_5","title":"Request","text":"<p><code>POST</code> <code>http://localhost:5000/api/v1/namespaces/default/subscriptions</code></p> <pre><code>{\n  \"namespace\": \"default\",\n  \"name\": \"asset_transfer\",\n  \"transport\": \"websockets\",\n  \"filter\": {\n    \"events\": \"blockchain_event_received\",\n    \"blockchainevent\": {\n      \"listener\": \"6e7f5dd8-5a57-4163-a1d2-5654e784dc31\"\n    }\n  },\n  \"options\": {\n    \"firstEvent\": \"oldest\"\n  }\n}\n</code></pre>"},{"location":"tutorials/custom_contracts/fabric/#response_5","title":"Response","text":"<pre><code>{\n  \"id\": \"06d18b49-e763-4f5c-9e97-c25024fe57c8\",\n  \"namespace\": \"default\",\n  \"name\": \"asset_transfer\",\n  \"transport\": \"websockets\",\n  \"filter\": {\n    \"events\": \"blockchain_event_received\",\n    \"message\": {},\n    \"transaction\": {},\n    \"blockchainevent\": {\n      \"listener\": \"6e7f5dd8-5a57-4163-a1d2-5654e784dc31\"\n    }\n  },\n  \"options\": {\n    \"firstEvent\": \"-1\",\n    \"withData\": false\n  },\n  \"created\": \"2022-05-02T17:22:06.480181291Z\",\n  \"updated\": null\n}\n</code></pre>"},{"location":"tutorials/custom_contracts/fabric/#receive-custom-smart-contract-events","title":"Receive custom smart contract events","text":"<p>The last step is to connect a WebSocket client to FireFly to receive the event. You can use any WebSocket client you like, such as Postman or a command line app like <code>websocat</code>.</p> <p>Connect your WebSocket client to <code>ws://localhost:5000/ws</code>.</p> <p>After connecting the WebSocket client, send a message to tell FireFly to:</p> <ul> <li>Start sending events</li> <li>For the Subscription named <code>asset_transfer</code></li> <li>On the <code>default</code> namespace</li> <li>Automatically \"ack\" each event which will let FireFly immediately send the next event when available</li> </ul> <pre><code>{\n  \"type\": \"start\",\n  \"name\": \"asset_transfer\",\n  \"namespace\": \"default\",\n  \"autoack\": true\n}\n</code></pre>"},{"location":"tutorials/custom_contracts/fabric/#websocket-event","title":"WebSocket event","text":"<p>After creating the subscription, you should see an event arrive on the connected WebSocket client that looks something like this:</p> <pre><code>{\n  \"id\": \"d9fb86b2-b25b-43b8-80d3-936c5daa5a66\",\n  \"sequence\": 29,\n  \"type\": \"blockchain_event_received\",\n  \"namespace\": \"default\",\n  \"reference\": \"e0d670b4-a1b6-4efd-a985-06dfaaa58fe3\",\n  \"topic\": \"assets\",\n  \"created\": \"2022-05-02T17:26:57.57612001Z\",\n  \"blockchainEvent\": {\n    \"id\": \"e0d670b4-a1b6-4efd-a985-06dfaaa58fe3\",\n    \"source\": \"fabric\",\n    \"namespace\": \"default\",\n    \"name\": \"AssetCreated\",\n    \"listener\": \"6e7f5dd8-5a57-4163-a1d2-5654e784dc31\",\n    \"protocolId\": \"000000000015/000000/000000\",\n    \"output\": {\n      \"AppraisedValue\": 12300,\n      \"Color\": \"red\",\n      \"ID\": \"asset-01\",\n      \"Owner\": \"Jerry\",\n      \"Size\": 10\n    },\n    \"info\": {\n      \"blockNumber\": 15,\n      \"chaincodeId\": \"asset_transfer\",\n      \"eventIndex\": 0,\n      \"eventName\": \"AssetCreated\",\n      \"subId\": \"sb-2cac2bfa-38af-4408-4ff3-973421410e5d\",\n      \"timestamp\": 1651512414920972300,\n      \"transactionId\": \"172637bf59a3520ca6dd02f716e1043ba080e10e1cd2f98b4e6b85abcc6a6d69\",\n      \"transactionIndex\": 0\n    },\n    \"timestamp\": \"2022-05-02T17:26:54.9209723Z\",\n    \"tx\": {\n      \"type\": \"\",\n      \"blockchainId\": \"172637bf59a3520ca6dd02f716e1043ba080e10e1cd2f98b4e6b85abcc6a6d69\"\n    }\n  },\n  \"subscription\": {\n    \"id\": \"06d18b49-e763-4f5c-9e97-c25024fe57c8\",\n    \"namespace\": \"default\",\n    \"name\": \"asset_transfer\"\n  }\n}\n</code></pre> <p>You can see in the event received over the WebSocket connection, the blockchain event that was emitted from our first transaction, which happened in the past. We received this event, because when we set up both the Listener, and the Subscription, we specified the <code>\"firstEvent\"</code> as <code>\"oldest\"</code>. This tells FireFly to look for this event from the beginning of the blockchain, and that your app is interested in FireFly events since the beginning of FireFly's event history.</p> <p>In the event, we can also see the <code>blockchainEvent</code> itself, which has an <code>output</code> object. This contains the event payload that was set by the chaincode.</p>"},{"location":"tutorials/custom_contracts/pinning/","title":"Pin off-chain data to a custom blockchain transaction","text":"<p>This guide describes how to associate an arbitrary off-chain payload with a blockchain transaction on a contract of your own design. A hash of the payload will be recorded as part of the blockchain transaction, and on the receiving side, FireFly will ensure that both the on-chain and off-chain pieces are received and aggregated together.</p> <p>NOTE: This is an advanced FireFly feature. Before following any of the steps in this guide, you should be very familiar and comfortable with the basic features of how broadcast messages and private messages work, be proficient at custom contract development on your blockchain of choice, and understand the fundamentals of how FireFly interacts with custom contracts.</p>"},{"location":"tutorials/custom_contracts/pinning/#designing-a-compatible-contract","title":"Designing a compatible contract","text":"<p>In order to allow pinning a FireFly message batch with a custom contract transaction, your contract must meet certain criteria.</p> <p>First, any external method of the contract that will be used for associating with off-chain payloads must provide an extra parameter for passing the encoded batch data. This must be the last parameter in the method signature. This convention is chosen partly to align with the Ethereum ERC5750 standard, but should serve as a straightforward guideline for nearly any blockchain.</p> <p>Second, this method must emit a <code>BatchPin</code> event that can be received and parsed by FireFly. Exactly how the data is unpacked and used to emit this event will differ for each blockchain.</p>"},{"location":"tutorials/custom_contracts/pinning/#ethereum","title":"Ethereum","text":"<pre><code>import \"@hyperledger/firefly-contracts/contracts/IBatchPin.sol\";\n\ncontract CustomPin {\n    IBatchPin firefly;\n\n    function setFireFlyAddress(address addr) external {\n        firefly = IBatchPin(addr);\n    }\n\n    function sayHello(bytes calldata data) external {\n        require(\n            address(firefly) != address(0),\n            \"CustomPin: FireFly address has not been set\"\n        );\n\n        /* do custom things */\n\n        firefly.pinBatchData(data);\n    }\n}\n</code></pre> <ul> <li>The method in question will receive packed \"batch pin\" data in its last method parameter (in the   form of ABI-encoded <code>bytes</code>). The method must invoke the <code>pinBatchData</code> method of the   FireFly Multiparty Contract and pass along this data payload. It is generally good practice to   trigger this as a final step before returning, after the method has performed its own logic.</li> <li>This also implies that the contract must know the on-chain location of the   FireFly Multiparty Contract. How this is achieved is up to your individual implementation -   the example above shows exposing a method to set the address. An application may leverage the fact that   this location is available by querying the FireFly   <code>/status</code> API (under <code>multiparty.contract.location</code> as of FireFly v1.1.0). However, the application must   also consider how appropriately secure this functionality, and how to update this location if a multiparty   \"network action\" is used to migrate the network onto a new FireFly multiparty contract.</li> </ul>"},{"location":"tutorials/custom_contracts/pinning/#fabric","title":"Fabric","text":"<pre><code>package chaincode\n\nimport (\n    \"encoding/json\"\n    \"fmt\"\n\n    \"github.com/hyperledger/fabric-contract-api-go/contractapi\"\n    \"github.com/hyperledger/firefly/custompin_sample/batchpin\"\n)\n\ntype SmartContract struct {\n    contractapi.Contract\n}\n\nfunc (s *SmartContract) MyCustomPin(ctx contractapi.TransactionContextInterface, data string) error {\n    event, err := batchpin.BuildEventFromString(ctx, data)\n    if err != nil {\n        return err\n    }\n    bytes, err := json.Marshal(event)\n    if err != nil {\n        return fmt.Errorf(\"failed to marshal event: %s\", err)\n    }\n    return ctx.GetStub().SetEvent(\"BatchPin\", bytes)\n}\n</code></pre> <ul> <li>The method in question will received packed \"batch pin\" data in its last method parameter (in the   form of a JSON-encoded <code>string</code>). The method must unpack this argument into a JSON object.</li> <li>The contract must directly set a <code>BatchPin</code> event in the same format that is used by the   FireFly Multiparty Contract.</li> </ul>"},{"location":"tutorials/custom_contracts/pinning/#initializing-firefly","title":"Initializing FireFly","text":"<p>Once you have a contract designed, you can initialize your environment using the blockchain of your choice.</p> <p>No special initialization arguments are needed for Ethereum.</p> <p>If you are using Fabric, you must pass the <code>--custom-pin-support</code> argument when initializing your FireFly stack. This will ensure that the <code>BatchPin</code> event listener listens to events from all chaincode deployed on the default channel, instead of only listening to events from the pre-deployed FireFly chaincode.</p>"},{"location":"tutorials/custom_contracts/pinning/#invoking-the-contract","title":"Invoking the contract","text":"<p>You can follow the normal steps for Ethereum or Fabric to define your contract interface and API in FireFly. When invoking the contract, you can include a message payload alongside the other parameters.</p> <p><code>POST</code> <code>http://localhost:5000/api/v1/namespaces/default/apis/custom-pin/invoke/sayHello</code></p> <pre><code>{\n  \"input\": {},\n  \"message\": {\n    \"data\": [\n      {\n        \"value\": \"payload here\"\n      }\n    ]\n  }\n}\n</code></pre>"},{"location":"tutorials/custom_contracts/pinning/#listening-for-events","title":"Listening for events","text":"<p>All parties that receive the message will receive a <code>message_confirmed</code> on their event listeners. This event confirms that the off-chain payload has been received (via data exchange or shared storage) and that the blockchain transaction has been received and sequenced. It is guaranteed that these <code>message_confirmed</code> events will be ordered based on the sequence of the on-chain transactions, regardless of when the off-chain payload becomes available. This means that all parties will order messages on a given topic in exactly the same order, allowing for deterministic but decentralized event-driven architecture.</p>"},{"location":"tutorials/custom_contracts/tezos/","title":"Work with Tezos smart contracts","text":"<p>This guide describes the steps to deploy a smart contract to a Tezos blockchain and use FireFly to interact with it in order to submit transactions, query for states and listening for events.</p>"},{"location":"tutorials/custom_contracts/tezos/#smart-contract-languages","title":"Smart Contract Languages","text":"<p>Smart contracts on Tezos can be programmed using familiar, developer-friendly languages. All features available on Tezos can be written in any of the high-level languages used to write smart contracts, such as Archetype, LIGO, and SmartPy. These languages all compile down to Michelson and you can switch between languages based on your preferences and projects.</p> <p>NOTE: For this tutorial we are going to use SmartPy for building Tezos smart contracts utilizing the broadly adopted Python language.</p>"},{"location":"tutorials/custom_contracts/tezos/#example-smart-contract","title":"Example smart contract","text":"<p>First let's look at a simple contract smart contract called <code>SimpleStorage</code>, which we will be using on a Tezos blockchain. Here we have one state variable called 'storedValue' and initialized with the value 12. During initialization the type of the variable was defined as 'int'. You can see more at SmartPy types. And then we added a simple test, which set the storage value to 15 and checks that the value was changed as expected.</p> <p>NOTE: Smart contract's tests (marked with <code>@sp.add_test</code> annotation) are used to verify the validity of contract entrypoints and do not affect the state of the contract during deployment.</p> <p>Here is the source for this contract:</p> <pre><code>import smartpy as sp\n\n@sp.module\ndef main():\n    # Declares a new contract\n    class SimpleStorage(sp.Contract):\n        # Storage. Persists in between transactions\n        def __init__(self, value):\n            self.data.x = value\n\n        # Allows the stored integer to be changed\n        @sp.entrypoint\n        def set(self, params):\n            self.data.x = params.value\n\n        # Returns the currently stored integer\n        @sp.onchain_view()\n        def get(self):\n            return self.data.x\n\n@sp.add_test()\ndef test():\n    # Create a test scenario\n    scenario = sp.test_scenario(\"Test simple storage\", main)\n    scenario.h1(\"SimpleStorage\")\n\n    # Initialize the contract\n    c = main.SimpleStorage(12)\n\n    # Run some test cases\n    scenario += c\n    c.set(value=15)\n    scenario.verify(c.data.x == 15)\n    scenario.verify(scenario.compute(c.get()) == 15)\n</code></pre>"},{"location":"tutorials/custom_contracts/tezos/#contract-deployment-via-smartpy-ide","title":"Contract deployment via SmartPy IDE","text":"<p>To deploy the contract, we will use SmartPy IDE.</p> <ol> <li>Open an IDE;</li> <li>Paste the contract code;</li> <li>Click \"Run code\" button;</li> <li>Then you will see \"Show Michelson\" button, click on that;</li> <li>On the opened pop-up click button \"Deploy Contract\";</li> <li>Choose the Ghostnet network;</li> <li>Select an account, which you're going to use to deploy the contract;</li> <li>Click \"Estimate Cost From RPC\" button;</li> <li>Click \"Deploy Contract\" button;</li> </ol> <p> </p> <p>Here we can see that our new contract address is <code>KT1ED4gj2xZnp8318yxa5NpvyvW15pqe4yFg</code>. This is the address that we will reference in the rest of this guide.</p>"},{"location":"tutorials/custom_contracts/tezos/#contract-deployment-via-http-api","title":"Contract deployment via HTTP API","text":"<p>To deploy the contract we can use HTTP API: <code>POST</code> <code>http://localhost:5000/api/v1/namespaces/default/contracts/deploy</code></p> <pre><code>{\n  \"contract\": {\n    \"code\": [\n      {\n        \"prim\": \"storage\",\n        \"args\": [\n          {\n            \"prim\": \"int\"\n          }\n        ]\n      },\n      {\n        \"prim\": \"parameter\",\n        \"args\": [\n          {\n            \"prim\": \"int\",\n            \"annots\": [\"%set\"]\n          }\n        ]\n      },\n      {\n        \"prim\": \"code\",\n        \"args\": [\n          [\n            {\n              \"prim\": \"CAR\"\n            },\n            {\n              \"prim\": \"NIL\",\n              \"args\": [\n                {\n                  \"prim\": \"operation\"\n                }\n              ]\n            },\n            {\n              \"prim\": \"PAIR\"\n            }\n          ]\n        ]\n      },\n      {\n        \"prim\": \"view\",\n        \"args\": [\n          {\n            \"string\": \"get\"\n          },\n          {\n            \"prim\": \"unit\"\n          },\n          {\n            \"prim\": \"int\"\n          },\n          [\n            {\n              \"prim\": \"CDR\"\n            }\n          ]\n        ]\n      }\n    ],\n    \"storage\": {\n      \"int\": \"12\"\n    }\n  }\n}\n</code></pre> <p>The <code>contract</code> field has two fields - <code>code</code> with Michelson code of contract and <code>storage</code> with initial Storage values.</p> <p>The response of request above:</p> <pre><code>{\n  \"id\": \"0c3810c7-baed-4077-9d2c-af316a4a567f\",\n  \"namespace\": \"default\",\n  \"tx\": \"21d03e6d-d106-48f4-aacd-688bf17b71fd\",\n  \"type\": \"blockchain_deploy\",\n  \"status\": \"Pending\",\n  \"plugin\": \"tezos\",\n  \"input\": {\n    \"contract\": {\n      \"code\": [\n        {\n          \"args\": [\n            {\n              \"prim\": \"int\"\n            }\n          ],\n          \"prim\": \"storage\"\n        },\n        {\n          \"args\": [\n            {\n              \"annots\": [\"%set\"],\n              \"prim\": \"int\"\n            }\n          ],\n          \"prim\": \"parameter\"\n        },\n        {\n          \"args\": [\n            [\n              {\n                \"prim\": \"CAR\"\n              },\n              {\n                \"args\": [\n                  {\n                    \"prim\": \"operation\"\n                  }\n                ],\n                \"prim\": \"NIL\"\n              },\n              {\n                \"prim\": \"PAIR\"\n              }\n            ]\n          ],\n          \"prim\": \"code\"\n        },\n        {\n          \"args\": [\n            {\n              \"string\": \"get\"\n            },\n            {\n              \"prim\": \"unit\"\n            },\n            {\n              \"prim\": \"int\"\n            },\n            [\n              {\n                \"prim\": \"CDR\"\n              }\n            ]\n          ],\n          \"prim\": \"view\"\n        }\n      ],\n      \"storage\": {\n        \"int\": \"12\"\n      }\n    },\n    \"definition\": null,\n    \"input\": null,\n    \"key\": \"tz1V3spuktTP2wuEZP7D2hJruLZ5uJTuJk31\",\n    \"options\": null\n  },\n  \"created\": \"2024-04-01T14:20:20.665039Z\",\n  \"updated\": \"2024-04-01T14:20:20.665039Z\"\n}\n</code></pre> <p>The success result of deploy can be checked by <code>GET</code> <code>http://localhost:5000/api/v1/namespaces/default/operations/0c3810c7-baed-4077-9d2c-af316a4a567f</code> where <code>0c3810c7-baed-4077-9d2c-af316a4a567f</code> is operation id from response above.</p> <p>The success response:</p> <pre><code>{\n  \"id\": \"0c3810c7-baed-4077-9d2c-af316a4a567f\",\n  \"namespace\": \"default\",\n  \"tx\": \"21d03e6d-d106-48f4-aacd-688bf17b71fd\",\n  \"type\": \"blockchain_deploy\",\n  \"status\": \"Succeeded\",\n  \"plugin\": \"tezos\",\n  \"input\": {\n    \"contract\": {\n      \"code\": [\n        {\n          \"args\": [\n            {\n              \"prim\": \"int\"\n            }\n          ],\n          \"prim\": \"storage\"\n        },\n        {\n          \"args\": [\n            {\n              \"annots\": [\"%set\"],\n              \"prim\": \"int\"\n            }\n          ],\n          \"prim\": \"parameter\"\n        },\n        {\n          \"args\": [\n            [\n              {\n                \"prim\": \"CAR\"\n              },\n              {\n                \"args\": [\n                  {\n                    \"prim\": \"operation\"\n                  }\n                ],\n                \"prim\": \"NIL\"\n              },\n              {\n                \"prim\": \"PAIR\"\n              }\n            ]\n          ],\n          \"prim\": \"code\"\n        },\n        {\n          \"args\": [\n            {\n              \"string\": \"get\"\n            },\n            {\n              \"prim\": \"unit\"\n            },\n            {\n              \"prim\": \"int\"\n            },\n            [\n              {\n                \"prim\": \"CDR\"\n              }\n            ]\n          ],\n          \"prim\": \"view\"\n        }\n      ],\n      \"storage\": {\n        \"int\": \"12\"\n      }\n    },\n    \"definition\": null,\n    \"input\": null,\n    \"key\": \"tz1V3spuktTP2wuEZP7D2hJruLZ5uJTuJk31\",\n    \"options\": null\n  },\n  \"output\": {\n    \"headers\": {\n      \"requestId\": \"default:0c3810c7-baed-4077-9d2c-af316a4a567f\",\n      \"type\": \"TransactionSuccess\"\n    },\n    \"protocolId\": \"ProxfordYmVfjWnRcgjWH36fW6PArwqykTFzotUxRs6gmTcZDuH\",\n    \"transactionHash\": \"ootDut4xxR2yeYz6JuySuyTVZnXgda2t8SYrk3iuJpm531TZuCj\"\n  },\n  \"created\": \"2024-04-01T14:20:20.665039Z\",\n  \"updated\": \"2024-04-01T14:20:20.665039Z\",\n  \"detail\": {\n    \"created\": \"2024-04-01T14:20:21.928976Z\",\n    \"firstSubmit\": \"2024-04-01T14:20:22.714493Z\",\n    \"from\": \"tz1V3spuktTP2wuEZP7D2hJruLZ5uJTuJk31\",\n    \"gasPrice\": \"0\",\n    \"historySummary\": [\n      {\n        \"count\": 1,\n        \"firstOccurrence\": \"2024-04-01T14:20:21.930764Z\",\n        \"lastOccurrence\": \"2024-04-01T14:20:21.930765Z\",\n        \"subStatus\": \"Received\"\n      },\n      {\n        \"action\": \"AssignNonce\",\n        \"count\": 2,\n        \"firstOccurrence\": \"2024-04-01T14:20:21.930767Z\",\n        \"lastOccurrence\": \"2024-04-01T14:20:22.714772Z\"\n      },\n      {\n        \"action\": \"RetrieveGasPrice\",\n        \"count\": 1,\n        \"firstOccurrence\": \"2024-04-01T14:20:22.714774Z\",\n        \"lastOccurrence\": \"2024-04-01T14:20:22.714774Z\"\n      },\n      {\n        \"action\": \"SubmitTransaction\",\n        \"count\": 1,\n        \"firstOccurrence\": \"2024-04-01T14:20:22.715269Z\",\n        \"lastOccurrence\": \"2024-04-01T14:20:22.715269Z\"\n      },\n      {\n        \"action\": \"ReceiveReceipt\",\n        \"count\": 1,\n        \"firstOccurrence\": \"2024-04-01T14:20:29.244396Z\",\n        \"lastOccurrence\": \"2024-04-01T14:20:29.244396Z\"\n      },\n      {\n        \"action\": \"Confirm\",\n        \"count\": 1,\n        \"firstOccurrence\": \"2024-04-01T14:20:29.244762Z\",\n        \"lastOccurrence\": \"2024-04-01T14:20:29.244762Z\"\n      }\n    ],\n    \"id\": \"default:0c3810c7-baed-4077-9d2c-af316a4a567f\",\n    \"lastSubmit\": \"2024-04-01T14:20:22.714493Z\",\n    \"nonce\": \"23094946\",\n    \"policyInfo\": {},\n    \"receipt\": {\n      \"blockHash\": \"BLvWL4t8GbaufGcQwiv3hHCsvgD6qwXfAXofyvojSMoFeGMXMR1\",\n      \"blockNumber\": \"5868268\",\n      \"contractLocation\": {\n        \"address\": \"KT1CkTPsgTUQxR3CCpvtrcuQFV5Jf7cJgHFg\"\n      },\n      \"extraInfo\": [\n        {\n          \"consumedGas\": \"584\",\n          \"contractAddress\": \"KT1CkTPsgTUQxR3CCpvtrcuQFV5Jf7cJgHFg\",\n          \"counter\": null,\n          \"errorMessage\": null,\n          \"fee\": null,\n          \"from\": null,\n          \"gasLimit\": null,\n          \"paidStorageSizeDiff\": \"75\",\n          \"status\": \"applied\",\n          \"storage\": null,\n          \"storageLimit\": null,\n          \"storageSize\": \"75\",\n          \"to\": null\n        }\n      ],\n      \"protocolId\": \"ProxfordYmVfjWnRcgjWH36fW6PArwqykTFzotUxRs6gmTcZDuH\",\n      \"success\": true,\n      \"transactionIndex\": \"0\"\n    },\n    \"sequenceId\": \"018e9a08-582a-01ec-9209-9d79ef742c9b\",\n    \"status\": \"Succeeded\",\n    \"transactionData\": \"c37274b662d68da8fdae2a02ad6c460a79933c70c6fa7500dc98a9ade6822f026d00673bb6e6298063f97940953de23d441ab20bf757f602a3cd810bad05b003000000000041020000003c0500045b00000004257365740501035b050202000000080316053d036d03420991000000130100000003676574036c035b020000000203170000000000000002000c\",\n    \"transactionHash\": \"ootDut4xxR2yeYz6JuySuyTVZnXgda2t8SYrk3iuJpm531TZuCj\",\n    \"transactionHeaders\": {\n      \"from\": \"tz1V3spuktTP2wuEZP7D2hJruLZ5uJTuJk31\",\n      \"nonce\": \"23094946\"\n    },\n    \"updated\": \"2024-04-01T14:20:29.245172Z\"\n  }\n}\n</code></pre>"},{"location":"tutorials/custom_contracts/tezos/#the-firefly-interface-format","title":"The FireFly Interface Format","text":"<p>As we know from the previous section - smart contracts on the Tezos blockchain are using the domain-specific, stack-based programming language called Michelson. It is a key component of the Tezos platform and plays a fundamental role in defining the behavior of smart contracts and facilitating their execution. This language is very efficient but also a bit tricky and challenging for learning, so in order to teach FireFly how to interact with the smart contract, we will be using FireFly Interface (FFI) to define the contract inteface which later will be encoded to Michelson.</p>"},{"location":"tutorials/custom_contracts/tezos/#schema-details","title":"Schema details","text":"<p>The <code>details</code> field is used to encapsulate blockchain specific type information about a specific field. (More details at schema details)</p>"},{"location":"tutorials/custom_contracts/tezos/#supported-tezos-types","title":"Supported Tezos types","text":"<ul> <li>nat</li> <li>integer</li> <li>string</li> <li>address</li> <li>bytes</li> <li>boolean</li> <li>variant</li> <li>list</li> <li>struct</li> <li>map</li> </ul>"},{"location":"tutorials/custom_contracts/tezos/#internal-type-vs-internal-schema","title":"Internal type vs Internal schema","text":"<p>internalType is a field which is used to describe tezos primitive types</p> <pre><code>{\n  \"details\": {\n    \"type\": \"address\",\n    \"internalType\": \"address\"\n  }\n}\n</code></pre> <p>internalSchema in turn is used to describe more complex tezos types as list, struct or variant</p> <p>Struct example:</p> <pre><code>{\n  \"details\": {\n    \"type\": \"schema\",\n    \"internalSchema\": {\n      \"type\": \"struct\",\n      \"args\": [\n        {\n          \"name\": \"metadata\",\n          \"type\": \"bytes\"\n        },\n        {\n          \"name\": \"token_id\",\n          \"type\": \"nat\"\n        }\n      ]\n    }\n  }\n}\n</code></pre> <p>List example:</p> <pre><code>{\n  \"details\": {\n    \"type\": \"schema\",\n    \"internalSchema\": {\n      \"type\": \"struct\",\n      \"args\": [\n        {\n          \"name\": \"metadata\",\n          \"type\": \"bytes\"\n        },\n        {\n          \"name\": \"token_id\",\n          \"type\": \"nat\"\n        }\n      ]\n    }\n  }\n}\n</code></pre> <p>Variant example:</p> <pre><code>{\n  \"details\": {\n    \"type\": \"schema\",\n    \"internalSchema\": {\n      \"type\": \"variant\",\n      \"variants\": [\"add_operator\", \"remove_operator\"],\n      \"args\": [\n        {\n          \"type\": \"struct\",\n          \"args\": [\n            {\n              \"name\": \"owner\",\n              \"type\": \"address\"\n            },\n            {\n              \"name\": \"operator\",\n              \"type\": \"address\"\n            },\n            {\n              \"name\": \"token_id\",\n              \"type\": \"nat\"\n            }\n          ]\n        }\n      ]\n    }\n  }\n}\n</code></pre> <p>Map example:</p> <pre><code>{\n  \"details\": {\n    \"type\": \"schema\",\n    \"internalSchema\": {\n      \"type\": \"map\",\n      \"args\": [\n        {\n          \"name\": \"key\",\n          \"type\": \"integer\"\n        },\n        {\n          \"name\": \"value\",\n          \"type\": \"string\"\n        }\n      ]\n    }\n  }\n}\n</code></pre>"},{"location":"tutorials/custom_contracts/tezos/#options","title":"Options","text":"<p>Option type is used to indicate a value as optional (see more at smartpy options)</p> <pre><code>{\n  \"details\": {\n    \"type\": \"string\",\n    \"internalType\": \"string\",\n    \"kind\": \"option\"\n  }\n}\n</code></pre>"},{"location":"tutorials/custom_contracts/tezos/#fa2-example","title":"FA2 example","text":"<p>The following FFI sample demonstrates the specification for the widely used FA2 (analogue of ERC721 for EVM) smart contract:</p> <pre><code>{\n  \"namespace\": \"default\",\n  \"name\": \"fa2\",\n  \"version\": \"v1.0.0\",\n  \"description\": \"\",\n  \"methods\": [\n    {\n      \"name\": \"burn\",\n      \"pathname\": \"\",\n      \"description\": \"\",\n      \"params\": [\n        {\n          \"name\": \"token_ids\",\n          \"schema\": {\n            \"type\": \"array\",\n            \"details\": {\n              \"type\": \"nat\",\n              \"internalType\": \"nat\"\n            }\n          }\n        }\n      ],\n      \"returns\": []\n    },\n    {\n      \"name\": \"destroy\",\n      \"pathname\": \"\",\n      \"description\": \"\",\n      \"params\": [],\n      \"returns\": []\n    },\n    {\n      \"name\": \"mint\",\n      \"pathname\": \"\",\n      \"description\": \"\",\n      \"params\": [\n        {\n          \"name\": \"owner\",\n          \"schema\": {\n            \"type\": \"string\",\n            \"details\": {\n              \"type\": \"address\",\n              \"internalType\": \"address\"\n            }\n          }\n        },\n        {\n          \"name\": \"requests\",\n          \"schema\": {\n            \"type\": \"array\",\n            \"details\": {\n              \"type\": \"schema\",\n              \"internalSchema\": {\n                \"type\": \"struct\",\n                \"args\": [\n                  {\n                    \"name\": \"metadata\",\n                    \"type\": \"bytes\"\n                  },\n                  {\n                    \"name\": \"token_id\",\n                    \"type\": \"nat\"\n                  }\n                ]\n              }\n            }\n          }\n        }\n      ],\n      \"returns\": []\n    },\n    {\n      \"name\": \"pause\",\n      \"pathname\": \"\",\n      \"description\": \"\",\n      \"params\": [\n        {\n          \"name\": \"pause\",\n          \"schema\": {\n            \"type\": \"boolean\",\n            \"details\": {\n              \"type\": \"boolean\",\n              \"internalType\": \"boolean\"\n            }\n          }\n        }\n      ],\n      \"returns\": []\n    },\n    {\n      \"name\": \"select\",\n      \"pathname\": \"\",\n      \"description\": \"\",\n      \"params\": [\n        {\n          \"name\": \"batch\",\n          \"schema\": {\n            \"type\": \"array\",\n            \"details\": {\n              \"type\": \"schema\",\n              \"internalSchema\": {\n                \"type\": \"struct\",\n                \"args\": [\n                  {\n                    \"name\": \"token_id\",\n                    \"type\": \"nat\"\n                  },\n                  {\n                    \"name\": \"recipient\",\n                    \"type\": \"address\"\n                  },\n                  {\n                    \"name\": \"token_id_start\",\n                    \"type\": \"nat\"\n                  },\n                  {\n                    \"name\": \"token_id_end\",\n                    \"type\": \"nat\"\n                  }\n                ]\n              }\n            }\n          }\n        }\n      ],\n      \"returns\": []\n    },\n    {\n      \"name\": \"transfer\",\n      \"pathname\": \"\",\n      \"description\": \"\",\n      \"params\": [\n        {\n          \"name\": \"batch\",\n          \"schema\": {\n            \"type\": \"array\",\n            \"details\": {\n              \"type\": \"schema\",\n              \"internalSchema\": {\n                \"type\": \"struct\",\n                \"args\": [\n                  {\n                    \"name\": \"from_\",\n                    \"type\": \"address\"\n                  },\n                  {\n                    \"name\": \"txs\",\n                    \"type\": \"list\",\n                    \"args\": [\n                      {\n                        \"type\": \"struct\",\n                        \"args\": [\n                          {\n                            \"name\": \"to_\",\n                            \"type\": \"address\"\n                          },\n                          {\n                            \"name\": \"token_id\",\n                            \"type\": \"nat\"\n                          },\n                          {\n                            \"name\": \"amount\",\n                            \"type\": \"nat\"\n                          }\n                        ]\n                      }\n                    ]\n                  }\n                ]\n              }\n            }\n          }\n        }\n      ],\n      \"returns\": []\n    },\n    {\n      \"name\": \"update_admin\",\n      \"pathname\": \"\",\n      \"description\": \"\",\n      \"params\": [\n        {\n          \"name\": \"admin\",\n          \"schema\": {\n            \"type\": \"string\",\n            \"details\": {\n              \"type\": \"address\",\n              \"internalType\": \"address\"\n            }\n          }\n        }\n      ],\n      \"returns\": []\n    },\n    {\n      \"name\": \"update_operators\",\n      \"pathname\": \"\",\n      \"description\": \"\",\n      \"params\": [\n        {\n          \"name\": \"requests\",\n          \"schema\": {\n            \"type\": \"array\",\n            \"details\": {\n              \"type\": \"schema\",\n              \"internalSchema\": {\n                \"type\": \"variant\",\n                \"variants\": [\"add_operator\", \"remove_operator\"],\n                \"args\": [\n                  {\n                    \"type\": \"struct\",\n                    \"args\": [\n                      {\n                        \"name\": \"owner\",\n                        \"type\": \"address\"\n                      },\n                      {\n                        \"name\": \"operator\",\n                        \"type\": \"address\"\n                      },\n                      {\n                        \"name\": \"token_id\",\n                        \"type\": \"nat\"\n                      }\n                    ]\n                  }\n                ]\n              }\n            }\n          }\n        }\n      ],\n      \"returns\": []\n    }\n  ],\n  \"events\": []\n}\n</code></pre>"},{"location":"tutorials/custom_contracts/tezos/#broadcast-the-contract-interface","title":"Broadcast the contract interface","text":"<p>Now that we have a FireFly Interface representation of our smart contract, we want to broadcast that to the entire network. This broadcast will be pinned to the blockchain, so we can always refer to this specific name and version, and everyone in the network will know exactly which contract interface we are talking about.</p> <p>We will use the FFI JSON constructed above and <code>POST</code> that to the <code>/contracts/interfaces</code> API endpoint.</p>"},{"location":"tutorials/custom_contracts/tezos/#request","title":"Request","text":"<p><code>POST</code> <code>http://localhost:5000/api/v1/namespaces/default/contracts/interfaces</code></p> <pre><code>{\n  \"namespace\": \"default\",\n  \"name\": \"simplestorage\",\n  \"version\": \"v1.0.0\",\n  \"description\": \"\",\n  \"methods\": [\n    {\n      \"name\": \"set\",\n      \"pathname\": \"\",\n      \"description\": \"\",\n      \"params\": [\n        {\n          \"name\": \"newValue\",\n          \"schema\": {\n            \"type\": \"integer\",\n            \"details\": {\n              \"type\": \"integer\",\n              \"internalType\": \"integer\"\n            }\n          }\n        }\n      ],\n      \"returns\": []\n    },\n    {\n      \"name\": \"get\",\n      \"pathname\": \"\",\n      \"description\": \"\",\n      \"params\": [],\n      \"returns\": []\n    }\n  ],\n  \"events\": []\n}\n</code></pre>"},{"location":"tutorials/custom_contracts/tezos/#response","title":"Response","text":"<pre><code>{\n  \"id\": \"f9e34787-e634-46cd-af47-b52c537404ff\",\n  \"namespace\": \"default\",\n  \"name\": \"simplestorage\",\n  \"description\": \"\",\n  \"version\": \"v1.0.0\",\n  \"methods\": [\n    {\n      \"id\": \"78f13a7f-7b85-47c3-bf51-346a9858c027\",\n      \"interface\": \"f9e34787-e634-46cd-af47-b52c537404ff\",\n      \"name\": \"set\",\n      \"namespace\": \"default\",\n      \"pathname\": \"set\",\n      \"description\": \"\",\n      \"params\": [\n        {\n          \"name\": \"newValue\",\n          \"schema\": {\n            \"type\": \"integer\",\n            \"details\": {\n              \"type\": \"integer\",\n              \"internalType\": \"integer\"\n            }\n          }\n        }\n      ],\n      \"returns\": []\n    },\n    {\n      \"id\": \"ee864e25-c3f7-42d3-aefd-a82f753e9002\",\n      \"interface\": \"f9e34787-e634-46cd-af47-b52c537404ff\",\n      \"name\": \"get\",\n      \"namespace\": \"tezos\",\n      \"pathname\": \"get\",\n      \"description\": \"\",\n      \"params\": [],\n      \"returns\": []\n    }\n  ]\n}\n</code></pre> <p>NOTE: We can broadcast this contract interface conveniently with the help of FireFly Sandbox running at <code>http://127.0.0.1:5108</code></p> <ul> <li>Go to the <code>Contracts Section</code></li> <li>Click on <code>Define a Contract Interface</code></li> <li>Select <code>FFI - FireFly Interface</code> in the <code>Interface Fromat</code> dropdown</li> <li>Copy the <code>FFI JSON</code> crafted by you into the <code>Schema</code> Field</li> <li>Click on <code>Run</code></li> </ul>"},{"location":"tutorials/custom_contracts/tezos/#create-an-http-api-for-the-contract","title":"Create an HTTP API for the contract","text":"<p>Now comes the fun part where we see some of the powerful, developer-friendly features of FireFly. The next thing we're going to do is tell FireFly to build an HTTP API for this smart contract, complete with an OpenAPI Specification and Swagger UI. As part of this, we'll also tell FireFly where the contract is on the blockchain.</p> <p>Like the interface broadcast above, this will also generate a broadcast which will be pinned to the blockchain so all the members of the network will be aware of and able to interact with this API.</p> <p>We need to copy the <code>id</code> field we got in the response from the previous step to the <code>interface.id</code> field in the request body below. We will also pick a name that will be part of the URL for our HTTP API, so be sure to pick a name that is URL friendly. In this case we'll call it <code>simple-storage</code>. Lastly, in the <code>location.address</code> field, we're telling FireFly where an instance of the contract is deployed on-chain.</p> <p>NOTE: The <code>location</code> field is optional here, but if it is omitted, it will be required in every request to invoke or query the contract. This can be useful if you have multiple instances of the same contract deployed to different addresses.</p>"},{"location":"tutorials/custom_contracts/tezos/#request_1","title":"Request","text":"<p><code>POST</code> <code>http://localhost:5000/api/v1/namespaces/default/apis</code></p> <pre><code>{\n  \"name\": \"simple-storage\",\n  \"interface\": {\n    \"id\": \"f9e34787-e634-46cd-af47-b52c537404ff\"\n  },\n  \"location\": {\n    \"address\": \"KT1ED4gj2xZnp8318yxa5NpvyvW15pqe4yFg\"\n  }\n}\n</code></pre>"},{"location":"tutorials/custom_contracts/tezos/#response_1","title":"Response","text":"<pre><code>{\n  \"id\": \"af09de97-741d-4f61-8d30-4db5e7460f76\",\n  \"namespace\": \"default\",\n  \"interface\": {\n    \"id\": \"f9e34787-e634-46cd-af47-b52c537404ff\"\n  },\n  \"location\": {\n    \"address\": \"KT1ED4gj2xZnp8318yxa5NpvyvW15pqe4yFg\"\n  },\n  \"name\": \"simple-storage\",\n  \"urls\": {\n    \"openapi\": \"http://127.0.0.1:5000/api/v1/namespaces/default/apis/simple-storage/api/swagger.json\",\n    \"ui\": \"http://127.0.0.1:5000/api/v1/namespaces/default/apis/simple-storage/api\"\n  }\n}\n</code></pre>"},{"location":"tutorials/custom_contracts/tezos/#view-openapi-spec-for-the-contract","title":"View OpenAPI spec for the contract","text":"<p>You'll notice in the response body that there are a couple of URLs near the bottom. If you navigate to the one labeled <code>ui</code> in your browser, you should see the Swagger UI for your smart contract.</p> <p></p>"},{"location":"tutorials/custom_contracts/tezos/#invoke-the-smart-contract","title":"Invoke the smart contract","text":"<p>Now that we've got everything set up, it's time to use our smart contract! We're going to make a <code>POST</code> request to the <code>invoke/set</code> endpoint to set the integer value on-chain. Let's set it to the value of <code>3</code> right now.</p>"},{"location":"tutorials/custom_contracts/tezos/#request_2","title":"Request","text":"<p><code>POST</code> <code>http://localhost:5000/api/v1/namespaces/default/apis/simple-storage/invoke/set</code></p> <pre><code>{\n  \"input\": {\n    \"newValue\": 3\n  }\n}\n</code></pre>"},{"location":"tutorials/custom_contracts/tezos/#response_2","title":"Response","text":"<pre><code>{\n  \"id\": \"87c7ee1b-33d1-46e2-b3f5-8566c14367cf\",\n  \"type\": \"blockchain_invoke\",\n  \"status\": \"Pending\",\n  \"...\"\n}\n</code></pre> <p>You'll notice that we got an ID back with status <code>Pending</code>, and that's expected due to the asynchronous programming model of working with smart contracts in FireFly. To see what the value is now, we can query the smart contract.</p>"},{"location":"tutorials/custom_contracts/tezos/#query-the-current-value","title":"Query the current value","text":"<p>To make a read-only request to the blockchain to check the current value of the stored integer, we can make a <code>POST</code> to the <code>query/get</code> endpoint.</p>"},{"location":"tutorials/custom_contracts/tezos/#request_3","title":"Request","text":"<p><code>POST</code> <code>http://localhost:5000/api/v1/namespaces/default/apis/simple-storage/query/get</code></p> <pre><code>{}\n</code></pre>"},{"location":"tutorials/custom_contracts/tezos/#response_3","title":"Response","text":"<pre><code>{\n  \"3\"\n}\n</code></pre> <p>NOTE: Some contracts may have queries that require input parameters. That's why the query endpoint is a <code>POST</code>, rather than a <code>GET</code> so that parameters can be passed as JSON in the request body. This particular function does not have any parameters, so we just pass an empty JSON object.</p>"},{"location":"tutorials/tokens/","title":"Use tokens","text":""},{"location":"tutorials/tokens/#quick-reference","title":"Quick reference","text":"<p>Tokens are a critical building block in many blockchain-backed applications. Fungible tokens can represent a store of value or a means of rewarding participation in a multi-party system, while non-fungible tokens provide a clear way to identify and track unique entities across the network. FireFly provides flexible mechanisms to operate on any type of token and to tie those operations to on- and off-chain data.</p> <ul> <li>FireFly provides an abstraction layer for multiple types of tokens</li> <li>Tokens are grouped into pools, which each represent a particular type or class of token</li> <li>Each pool is classified as fungible or non-fungible</li> <li>In the case of non-fungible tokens, the pool is subdivided into individual tokens with a unique token index</li> <li>Within a pool, you may mint (issue), transfer, and burn (redeem) tokens</li> <li>Each operation can be optionally accompanied by a broadcast or private message, which will be recorded alongside the transfer on-chain</li> <li>FireFly tracks a history of all token operations along with all current token balances</li> <li>The blockchain backing each token connector may be the same or different from the one backing FireFly message pinning</li> </ul>"},{"location":"tutorials/tokens/#what-is-a-pool","title":"What is a pool?","text":"<p>Token pools are a FireFly construct for describing a set of tokens. The exact definition of a token pool is dependent on the token connector implementation. Some examples of how pools might map to various well-defined Ethereum standards:</p> <ul> <li>ERC-1155: a single contract instance can efficiently allocate   many isolated pools of fungible or non-fungible tokens</li> <li>ERC-20 / ERC-777:   each contract instance represents a single fungible pool of value, e.g. \"a coin\"</li> <li>ERC-721: each contract instance represents a single pool of NFTs,   each with unique identities within the pool</li> <li>ERC-1400 / ERC-1410:   partially supported in the same manner as ERC-20/ERC-777, but would require new features for working with partitions</li> </ul> <p>These are provided as examples only - a custom token connector could be backed by any token technology (Ethereum or otherwise) as long as it can support the basic operations described here (create pool, mint, burn, transfer). Other FireFly repos include a sample implementation of a token connector for ERC-20 and ERC-721 as well as ERC-1155.</p>"},{"location":"tutorials/tokens/erc1155/","title":"Use ERC-1155 tokens","text":""},{"location":"tutorials/tokens/erc1155/#previous-steps-install-the-firefly-cli","title":"Previous steps: Install the FireFly CLI","text":"<p>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.</p> <p>\u2190 \u2460 Install the FireFly CLI</p>"},{"location":"tutorials/tokens/erc1155/#create-a-stack-with-an-erc-1155-connector","title":"Create a stack with an ERC-1155 connector","text":"<p>The default token connector that the FireFly CLI sets up is for ERC-20 and ERC-721. If you would like to work with ERC-1155 tokens, you need to create a stack that is configured to use that token connector. To do that, run:</p> <pre><code>ff init ethereum -t erc-1155\n</code></pre> <p>Then run:</p> <pre><code>ff start &lt;your_stack_name&gt;\n</code></pre>"},{"location":"tutorials/tokens/erc1155/#about-the-sample-token-contract","title":"About the sample token contract","text":"<p>When the FireFly CLI set up your FireFly stack, it also deployed a sample ERC-1155 contract that conforms to the expectations of the token connector. When you create a token pool through FireFly's token APIs, that contract will be used by default.</p> \u26a0\ufe0f WARNING: The default token contract that was deployed by the FireFly CLI is only provided for the purpose of learning about FireFly. It is not a production grade contract. If you intend to deploy a production application using tokens on FireFly, you should research token contract best practices. For details, please see the source code for the contract that was deployed."},{"location":"tutorials/tokens/erc1155/#use-the-sandbox-optional","title":"Use the Sandbox (optional)","text":"<p>At this point you could open the Sandbox at http://127.0.0.1:5109/home?action=tokens.pools and perform the functions outlined in the rest of this guide. Or you can keep reading to learn how to build HTTP requests to work with tokens in FireFly. </p>"},{"location":"tutorials/tokens/erc1155/#create-a-pool-using-default-token-contract","title":"Create a pool (using default token contract)","text":"<p>After your stack is up and running, the first thing you need to do is create a token pool. Every application will need at least one token pool. At a minimum, you must always specify a <code>name</code> and <code>type</code> (<code>fungible</code> or <code>nonfungible</code>) for the pool.</p> <p><code>POST</code> <code>http://127.0.0.1:5000/api/v1/namespaces/default/tokens/pools?publish=true</code></p> <p>NOTE: Without passing the query parameter <code>publish=true</code> when the token pool is created, it will initially be unpublished and not broadcasted to other members of the network (if configured in multi-party). To publish the token pool, a subsequent API call would need to be made to <code>/tokens/pools/{nameOrId}/publish</code></p> <pre><code>{\n  \"name\": \"testpool\",\n  \"type\": \"fungible\"\n}\n</code></pre> <p>Other parameters:</p> <ul> <li>You must specify a <code>connector</code> if you have configured multiple token connectors</li> <li>You may pass through a <code>config</code> object of additional parameters, if supported by your token connector</li> <li>You may specify a <code>key</code> understood by the connector (i.e. an Ethereum address) if you'd like to use a non-default signing identity</li> </ul>"},{"location":"tutorials/tokens/erc1155/#create-a-pool-from-a-deployed-token-contract","title":"Create a pool (from a deployed token contract)","text":"<p>If you wish to use a contract that is already on the chain, it is recommended that you first upload the ABI for your specific contract by creating a FireFly contract interface. This step is optional if you're certain that your ERC-1155 ABI conforms to the default expectations of the token connector, but is generally recommended.</p> <p>See the README of the token connector for details on what contract variants can currently be understood.</p> <p>You can pass a <code>config</code> object with an <code>address</code> when you make the request to create the token pool, and if you created a contract interface, you can include the <code>interface</code> ID as well.</p> <p><code>POST</code> <code>http://127.0.0.1:5000/api/v1/namespaces/default/tokens/pools?publish=true</code></p> <p>NOTE: Without passing the query parameter <code>publish=true</code> when the token pool is created, it will initially be unpublished and not broadcasted to other members of the network (if configured in multi-party). To publish the token pool, a subsequent API call would need to be made to <code>/tokens/pools/{nameOrId}/publish</code></p> <pre><code>{\n  \"name\": \"testpool\",\n  \"type\": \"fungible\",\n  \"interface\": {\n    \"id\": \"b9e5e1ce-97bb-4a35-a25c-52c7c3f523d8\"\n  },\n  \"config\": {\n    \"address\": \"0xb1C845D32966c79E23f733742Ed7fCe4B41901FC\"\n  }\n}\n</code></pre>"},{"location":"tutorials/tokens/erc1155/#mint-tokens","title":"Mint tokens","text":"<p>Once you have a token pool, you can mint tokens within it. With the default sample contract, only the creator of a pool is allowed to mint - but each contract may define its own permission model.</p> <p><code>POST</code> <code>http://127.0.0.1:5000/api/v1/namespaces/default/tokens/mint</code></p> <pre><code>{\n  \"amount\": 10\n}\n</code></pre> <p>Other parameters:</p> <ul> <li>You must specify a <code>pool</code> name if you've created more than one pool</li> <li>You may specify a <code>key</code> understood by the connector (i.e. an Ethereum address) if you'd like to use a non-default signing identity</li> <li>You may specify <code>to</code> if you'd like to send the minted tokens to a specific identity (default is the same as <code>key</code>)</li> </ul>"},{"location":"tutorials/tokens/erc1155/#transfer-tokens","title":"Transfer tokens","text":"<p>You may transfer tokens within a pool by specifying an amount and a destination understood by the connector (i.e. an Ethereum address). With the default sample contract, only the owner of a token or another approved account may transfer it away - but each contract may define its own permission model.</p> <p><code>POST</code> <code>http://127.0.0.1:5000/api/v1/namespaces/default/tokens/transfers</code></p> <pre><code>{\n  \"amount\": 1,\n  \"to\": \"0x07eab7731db665caf02bc92c286f51dea81f923f\"\n}\n</code></pre> <p>NOTE: When transferring a non-fungible token, the amount must always be <code>1</code>. The <code>tokenIndex</code> field is also required when transferring a non-fungible token.</p> <p>Other parameters:</p> <ul> <li>You must specify a <code>pool</code> name if you've created more than one pool</li> <li>You may specify a <code>key</code> understood by the connector (i.e. an Ethereum address) if you'd like to use a non-default signing identity</li> <li>You may specify <code>from</code> if you'd like to send tokens from a specific identity (default is the same as <code>key</code>)</li> </ul>"},{"location":"tutorials/tokens/erc1155/#sending-data-with-a-transfer","title":"Sending data with a transfer","text":"<p>All transfers (as well as mint/burn operations) support an optional <code>message</code> parameter that contains a broadcast or private message to be sent along with the transfer. This message follows the same convention as other FireFly messages, and may be comprised of text or blob data, and can provide context, metadata, or other supporting information about the transfer. The message will be batched, hashed, and pinned to the primary blockchain.</p> <p>The message ID and hash will also be sent to the token connector as part of the transfer operation, to be written to the token blockchain when the transaction is submitted. All recipients of the message will then be able to correlate the message with the token transfer.</p> <p><code>POST</code> <code>http://127.0.0.1:5000/api/v1/namespaces/default/tokens/transfers</code></p>"},{"location":"tutorials/tokens/erc1155/#broadcast-message","title":"Broadcast message","text":"<pre><code>{\n  \"amount\": 1,\n  \"to\": \"0x07eab7731db665caf02bc92c286f51dea81f923f\",\n  \"message\": {\n    \"data\": [\n      {\n        \"value\": \"payment for goods\"\n      }\n    ]\n  }\n}\n</code></pre>"},{"location":"tutorials/tokens/erc1155/#private-message","title":"Private message","text":"<pre><code>{\n  \"amount\": 1,\n  \"to\": \"0x07eab7731db665caf02bc92c286f51dea81f923f\",\n  \"message\": {\n    \"header\": {\n      \"type\": \"transfer_private\"\n    },\n    \"group\": {\n      \"members\": [\n        {\n          \"identity\": \"org_1\"\n        }\n      ]\n    },\n    \"data\": [\n      {\n        \"value\": \"payment for goods\"\n      }\n    ]\n  }\n}\n</code></pre> <p>Note that all parties in the network will be able to see the transfer (including the message ID and hash), but only the recipients of the message will be able to view the actual message data.</p>"},{"location":"tutorials/tokens/erc1155/#burn-tokens","title":"Burn tokens","text":"<p>You may burn tokens by simply specifying an amount. With the default sample contract, only the owner of a token or another approved account may burn it - but each connector may define its own permission model.</p> <p><code>POST</code> <code>http://127.0.0.1:5000/api/v1/namespaces/default/tokens/burn</code></p> <pre><code>{\n  \"amount\": 1\n}\n</code></pre> <p>NOTE: When burning a non-fungible token, the amount must always be <code>1</code>. The <code>tokenIndex</code> field is also required when burning a non-fungible token.</p> <p>Other parameters:</p> <ul> <li>You must specify a <code>pool</code> name if you've created more than one pool</li> <li>You may specify a <code>key</code> understood by the connector (i.e. an Ethereum address) if you'd like to use a non-default signing identity</li> <li>You may specify <code>from</code> if you'd like to burn tokens from a specific identity (default is the same as <code>key</code>)</li> </ul>"},{"location":"tutorials/tokens/erc1155/#token-approvals","title":"Token approvals","text":"<p>You can also approve other wallets to transfer tokens on your behalf with the <code>/approvals</code> API. The important fields in a token approval API request are as follows:</p> <ul> <li><code>approved</code>: Sets whether another account is allowed to transfer tokens out of this wallet or not. If not specified, will default to <code>true</code>. Setting to <code>false</code> can revoke an existing approval.</li> <li><code>operator</code>: The other account that is allowed to transfer tokens out of the wallet specified in the <code>key</code> field</li> <li><code>key</code>: The wallet address for the approval. If not set, it defaults to the address of the FireFly node submitting the transaction</li> </ul> <p>Here is an example request that would let the signing account <code>0x634ee8c7d0894d086c7af1fc8514736aed251528</code> transfer any amount of tokens from my wallet</p>"},{"location":"tutorials/tokens/erc1155/#request","title":"Request","text":"<p><code>POST</code> <code>http://127.0.0.1:5000/api/v1/namespaces/default/tokens/approvals</code></p> <pre><code>{\n  \"operator\": \"0x634ee8c7d0894d086c7af1fc8514736aed251528\"\n}\n</code></pre>"},{"location":"tutorials/tokens/erc1155/#response","title":"Response","text":"<pre><code>{\n  \"localId\": \"46fef50a-cf93-4f92-acf8-fae161b37362\",\n  \"pool\": \"e1477ed5-7282-48e5-ad9d-1612296bb29d\",\n  \"connector\": \"erc1155\",\n  \"key\": \"0x14ddd36a0c2f747130915bf5214061b1e4bec74c\",\n  \"operator\": \"0x634ee8c7d0894d086c7af1fc8514736aed251528\",\n  \"approved\": true,\n  \"tx\": {\n    \"type\": \"token_approval\",\n    \"id\": \"00faa011-f42c-403d-a047-2df7318967cd\"\n  }\n}\n</code></pre>"},{"location":"tutorials/tokens/erc20/","title":"Use ERC-20 tokens","text":""},{"location":"tutorials/tokens/erc20/#previous-steps-start-your-environment","title":"Previous steps: Start your environment","text":"<p>If you haven't started a FireFly stack already, please go to the Getting Started guide on how to Start your environment. This will set up a token connector that works with both ERC-20 and ERC-721 by default.</p> <p>\u2190 \u2461 Start your environment</p>"},{"location":"tutorials/tokens/erc20/#about-the-sample-token-contracts","title":"About the sample token contracts","text":"<p>If you are using the default ERC-20 / ERC-721 token connector, when the FireFly CLI set up your FireFly stack, it also deployed a token factory contract. When you create a token pool through FireFly's token APIs, the token factory contract will automatically deploy an ERC-20 or ERC-721 contract, based on the pool <code>type</code> in the API request.</p> \u26a0\ufe0f WARNING: The default token contract that was deployed by the FireFly CLI is only provided for the purpose of learning about FireFly. It is not a production grade contract. If you intend to deploy a production application using tokens on FireFly, you should research token contract best practices. For details, please see the source code for the contract that was deployed."},{"location":"tutorials/tokens/erc20/#use-the-sandbox-optional","title":"Use the Sandbox (optional)","text":"<p>At this point you could open the Sandbox at http://127.0.0.1:5109/home?action=tokens.pools and perform the functions outlined in the rest of this guide. Or you can keep reading to learn how to build HTTP requests to work with tokens in FireFly. </p>"},{"location":"tutorials/tokens/erc20/#create-a-pool-using-default-token-factory","title":"Create a pool (using default token factory)","text":"<p>After your stack is up and running, the first thing you need to do is create a token pool. Every application will need at least one token pool. At a minimum, you must always specify a <code>name</code> and <code>type</code> for the pool.</p> <p>If you're using the default ERC-20 / ERC-721 token connector and its sample token factory, it will automatically deploy a new ERC-20 contract instance.</p>"},{"location":"tutorials/tokens/erc20/#request","title":"Request","text":"<p><code>POST</code> <code>http://127.0.0.1:5000/api/v1/namespaces/default/tokens/pools?publish=true</code></p> <p>NOTE: Without passing the query parameter <code>publish=true</code> when the token pool is created, it will initially be unpublished and not broadcasted to other members of the network (if configured in multi-party). To publish the token pool, a subsequent API call would need to be made to <code>/tokens/pools/{nameOrId}/publish</code></p> <pre><code>{\n  \"name\": \"testpool\",\n  \"type\": \"fungible\"\n}\n</code></pre>"},{"location":"tutorials/tokens/erc20/#response","title":"Response","text":"<pre><code>{\n  \"id\": \"e1477ed5-7282-48e5-ad9d-1612296bb29d\",\n  \"type\": \"fungible\",\n  \"namespace\": \"default\",\n  \"name\": \"testpool\",\n  \"key\": \"0x14ddd36a0c2f747130915bf5214061b1e4bec74c\",\n  \"connector\": \"erc20_erc721\",\n  \"tx\": {\n    \"type\": \"token_pool\",\n    \"id\": \"e901921e-ffc4-4776-b20a-9e9face70a47\"\n  },\n  \"published\": true\n}\n</code></pre> <p>Other parameters:</p> <ul> <li>You must specify a <code>connector</code> if you have configured multiple token connectors</li> <li>You may pass through a <code>config</code> object of additional parameters, if supported by your token connector</li> <li>You may specify a <code>key</code> understood by the connector (i.e. an Ethereum address) if you'd like to use a non-default signing identity</li> </ul>"},{"location":"tutorials/tokens/erc20/#get-the-address-of-the-deployed-contract","title":"Get the address of the deployed contract","text":"<p>To lookup the address of the new contract, you can lookup the token pool by its ID on the API. Creating the token pool will also emit an event which will contain the address. To query the token pool you can make a <code>GET</code> request to the pool's ID:</p>"},{"location":"tutorials/tokens/erc20/#request_1","title":"Request","text":"<p><code>GET</code> <code>http://127.0.0.1:5000/api/v1/namespaces/default/tokens/pools/5811e8d5-52d0-44b1-8b75-73f5ff88f598</code></p>"},{"location":"tutorials/tokens/erc20/#response_1","title":"Response","text":"<pre><code>{\n  \"id\": \"e1477ed5-7282-48e5-ad9d-1612296bb29d\",\n  \"type\": \"fungible\",\n  \"namespace\": \"default\",\n  \"name\": \"testpool\",\n  \"standard\": \"ERC20\",\n  \"locator\": \"address=0xc4d02efcfab06f18ec0a68e00b98ffecf6bf7e3c&amp;schema=ERC20WithData&amp;type=fungible\",\n  \"decimals\": 18,\n  \"connector\": \"erc20_erc721\",\n  \"message\": \"7e2f6004-31fd-4ba8-9845-15c5fe5fbcd7\",\n  \"state\": \"confirmed\",\n  \"created\": \"2022-04-28T14:03:16.732222381Z\",\n  \"info\": {\n    \"address\": \"0xc4d02efcfab06f18ec0a68e00b98ffecf6bf7e3c\",\n    \"name\": \"testpool\",\n    \"schema\": \"ERC20WithData\"\n  },\n  \"tx\": {\n    \"type\": \"token_pool\",\n    \"id\": \"e901921e-ffc4-4776-b20a-9e9face70a47\"\n  }\n}\n</code></pre>"},{"location":"tutorials/tokens/erc20/#create-a-pool-from-a-deployed-token-contract","title":"Create a pool (from a deployed token contract)","text":"<p>If you wish to index and use a contract that is already on the chain, it is recommended that you first upload the ABI for your specific contract by creating a FireFly contract interface. This step is optional if you're certain that your ERC-20 ABI conforms to the default expectations of the token connector, but is generally recommended.</p> <p>See the README of the token connector for details on what contract variants can currently be understood.</p> <p>You can pass a <code>config</code> object with an <code>address</code> and <code>blockNumber</code> when you make the request to create the token pool, and if you created a contract interface, you can include the <code>interface</code> ID as well.</p>"},{"location":"tutorials/tokens/erc20/#request_2","title":"Request","text":"<p><code>POST</code> <code>http://127.0.0.1:5000/api/v1/namespaces/default/tokens/pools?publish=true</code></p> <p>NOTE: Without passing the query parameter <code>publish=true</code> when the token pool is created, it will initially be unpublished and not broadcasted to other members of the network (if configured in multi-party). To publish the token pool, a subsequent API call would need to be made to <code>/tokens/pools/{nameOrId}/publish</code></p> <pre><code>{\n  \"name\": \"testpool\",\n  \"type\": \"fungible\",\n  \"interface\": {\n    \"id\": \"b9e5e1ce-97bb-4a35-a25c-52c7c3f523d8\"\n  },\n  \"config\": {\n    \"address\": \"0xb1C845D32966c79E23f733742Ed7fCe4B41901FC\",\n    \"blockNumber\": \"0\"\n  }\n}\n</code></pre>"},{"location":"tutorials/tokens/erc20/#mint-tokens","title":"Mint tokens","text":"<p>Once you have a token pool, you can mint tokens within it. When using the sample contract deployed by the CLI, only the creator of a pool is allowed to mint, but a different contract may define its own permission model.</p> <p>NOTE: The default sample contract uses 18 decimal places. This means that if you want to create 100 tokens, the number submitted to the API / blockchain should actually be 100\u00d710<sup>18</sup> = <code>100000000000000000000</code>. This allows users to work with \"fractional\" tokens even though Ethereum virtual machines only support integer arithmetic.</p>"},{"location":"tutorials/tokens/erc20/#request_3","title":"Request","text":"<p><code>POST</code> <code>http://127.0.0.1:5000/api/v1/namespaces/default/tokens/mint</code></p> <pre><code>{\n  \"amount\": \"100000000000000000000\"\n}\n</code></pre>"},{"location":"tutorials/tokens/erc20/#response_2","title":"Response","text":"<pre><code>{\n  \"type\": \"mint\",\n  \"localId\": \"835fe2a1-594b-4336-bc1d-b2f59d51064b\",\n  \"pool\": \"e1477ed5-7282-48e5-ad9d-1612296bb29d\",\n  \"connector\": \"erc20_erc721\",\n  \"key\": \"0x14ddd36a0c2f747130915bf5214061b1e4bec74c\",\n  \"from\": \"0x14ddd36a0c2f747130915bf5214061b1e4bec74c\",\n  \"to\": \"0x14ddd36a0c2f747130915bf5214061b1e4bec74c\",\n  \"amount\": \"100000000000000000000\",\n  \"tx\": {\n    \"type\": \"token_transfer\",\n    \"id\": \"3fc97e24-fde1-4e80-bd82-660e479c0c43\"\n  }\n}\n</code></pre> <p>Other parameters:</p> <ul> <li>You must specify a <code>pool</code> name if you've created more than one pool</li> <li>You may specify a <code>key</code> understood by the connector (i.e. an Ethereum address) if you'd like to use a non-default signing identity</li> <li>You may specify <code>to</code> if you'd like to send the minted tokens to a specific identity (default is the same as <code>key</code>)</li> </ul>"},{"location":"tutorials/tokens/erc20/#transfer-tokens","title":"Transfer tokens","text":"<p>You may transfer tokens within a pool by specifying an amount and a destination understood by the connector (i.e. an Ethereum address). With the default sample contract, only the owner of the tokens or another approved account may transfer their tokens, but a different contract may define its own permission model.</p>"},{"location":"tutorials/tokens/erc20/#request_4","title":"Request","text":"<p><code>POST</code> <code>http://127.0.0.1:5000/api/v1/namespaces/default/tokens/transfers</code></p> <pre><code>{\n  \"amount\": \"10000000000000000000\",\n  \"to\": \"0xa4222a4ae19448d43a338e6586edd5fb2ac398e1\"\n}\n</code></pre>"},{"location":"tutorials/tokens/erc20/#response_3","title":"Response","text":"<pre><code>{\n  \"type\": \"transfer\",\n  \"localId\": \"61f0a71f-712b-4778-8b37-784fbee52657\",\n  \"pool\": \"e1477ed5-7282-48e5-ad9d-1612296bb29d\",\n  \"connector\": \"erc20_erc721\",\n  \"key\": \"0x14ddd36a0c2f747130915bf5214061b1e4bec74c\",\n  \"from\": \"0x14ddd36a0c2f747130915bf5214061b1e4bec74c\",\n  \"to\": \"0xa4222a4ae19448d43a338e6586edd5fb2ac398e1\",\n  \"amount\": \"10000000000000000000\",\n  \"tx\": {\n    \"type\": \"token_transfer\",\n    \"id\": \"c0c316a3-23a9-42f3-89b3-1cfdba6c948d\"\n  }\n}\n</code></pre> <p>Other parameters:</p> <ul> <li>You must specify a <code>pool</code> name if you've created more than one pool</li> <li>You may specify a <code>key</code> understood by the connector (i.e. an Ethereum address) if you'd like to use a non-default signing identity</li> <li>You may specify <code>from</code> if you'd like to send tokens from a specific identity (default is the same as <code>key</code>)</li> </ul>"},{"location":"tutorials/tokens/erc20/#sending-data-with-a-transfer","title":"Sending data with a transfer","text":"<p>All transfers (as well as mint/burn operations) support an optional <code>message</code> parameter that contains a broadcast or private message to be sent along with the transfer. This message follows the same convention as other FireFly messages, and may be comprised of text or blob data, and can provide context, metadata, or other supporting information about the transfer. The message will be batched, hashed, and pinned to the primary blockchain.</p> <p>The message ID and hash will also be sent to the token connector as part of the transfer operation, to be written to the token blockchain when the transaction is submitted. All recipients of the message will then be able to correlate the message with the token transfer.</p> <p><code>POST</code> <code>http://127.0.0.1:5000/api/v1/namespaces/default/tokens/transfers</code></p>"},{"location":"tutorials/tokens/erc20/#broadcast-message","title":"Broadcast message","text":"<pre><code>{\n  \"amount\": 1,\n  \"to\": \"0x07eab7731db665caf02bc92c286f51dea81f923f\",\n  \"message\": {\n    \"data\": [\n      {\n        \"value\": \"payment for goods\"\n      }\n    ]\n  }\n}\n</code></pre>"},{"location":"tutorials/tokens/erc20/#private-message","title":"Private message","text":"<pre><code>{\n  \"amount\": 1,\n  \"to\": \"0x07eab7731db665caf02bc92c286f51dea81f923f\",\n  \"message\": {\n    \"header\": {\n      \"type\": \"transfer_private\"\n    },\n    \"group\": {\n      \"members\": [\n        {\n          \"identity\": \"org_1\"\n        }\n      ]\n    },\n    \"data\": [\n      {\n        \"value\": \"payment for goods\"\n      }\n    ]\n  }\n}\n</code></pre> <p>Note that all parties in the network will be able to see the transfer (including the message ID and hash), but only the recipients of the message will be able to view the actual message data.</p>"},{"location":"tutorials/tokens/erc20/#burn-tokens","title":"Burn tokens","text":"<p>You may burn tokens by simply specifying an amount. With the default sample contract, only the owner of a token or another approved account may burn it, but a different contract may define its own permission model.</p> <p><code>POST</code> <code>http://127.0.0.1:5000/api/v1/namespaces/default/tokens/burn</code></p> <pre><code>{\n  \"amount\": 1\n}\n</code></pre> <p>Other parameters:</p> <ul> <li>You must specify a <code>pool</code> name if you've created more than one pool</li> <li>You may specify a <code>key</code> understood by the connector (i.e. an Ethereum address) if you'd like to use a non-default signing identity</li> <li>You may specify <code>from</code> if you'd like to burn tokens from a specific identity (default is the same as <code>key</code>)</li> </ul>"},{"location":"tutorials/tokens/erc20/#token-approvals","title":"Token approvals","text":"<p>You can also approve other wallets to transfer tokens on your behalf with the <code>/approvals</code> API. The important fields in a token approval API request are as follows:</p> <ul> <li><code>approved</code>: Sets whether another account is allowed to transfer tokens out of this wallet or not. If not specified, will default to <code>true</code>. Setting to <code>false</code> can revoke an existing approval.</li> <li><code>operator</code>: The other account that is allowed to transfer tokens out of the wallet specified in the <code>key</code> field.</li> <li><code>config.allowance</code>: The number of tokens the other account is allowed to transfer. If <code>0</code> or not set, the approval is valid for any number.</li> <li><code>key</code>: The wallet address for the approval. If not set, it defaults to the address of the FireFly node submitting the transaction.</li> </ul> <p>Here is an example request that would let the signing account <code>0x634ee8c7d0894d086c7af1fc8514736aed251528</code> transfer up to 10\u00d710<sup>18</sup> (<code>10000000000000000000</code>) tokens from my wallet</p>"},{"location":"tutorials/tokens/erc20/#request_5","title":"Request","text":"<p><code>POST</code> <code>http://127.0.0.1:5000/api/v1/namespaces/default/tokens/approvals</code></p> <pre><code>{\n  \"operator\": \"0x634ee8c7d0894d086c7af1fc8514736aed251528\",\n  \"config\": {\n    \"allowance\": \"10000000000000000000\"\n  }\n}\n</code></pre>"},{"location":"tutorials/tokens/erc20/#response_4","title":"Response","text":"<pre><code>{\n  \"localId\": \"46fef50a-cf93-4f92-acf8-fae161b37362\",\n  \"pool\": \"e1477ed5-7282-48e5-ad9d-1612296bb29d\",\n  \"connector\": \"erc20_erc721\",\n  \"key\": \"0x14ddd36a0c2f747130915bf5214061b1e4bec74c\",\n  \"operator\": \"0x634ee8c7d0894d086c7af1fc8514736aed251528\",\n  \"approved\": true,\n  \"tx\": {\n    \"type\": \"token_approval\",\n    \"id\": \"00faa011-f42c-403d-a047-2df7318967cd\"\n  },\n  \"config\": {\n    \"allowance\": \"10000000000000000000\"\n  }\n}\n</code></pre>"},{"location":"tutorials/tokens/erc20/#use-metamask","title":"Use Metamask","text":"<p>Now that you have an ERC-20 contract up and running, you may be wondering how to use Metamask (or some other wallet) with this contract. This section will walk you through how to connect Metamask to the blockchain and token contract that FireFly is using.</p>"},{"location":"tutorials/tokens/erc20/#configure-a-new-network","title":"Configure a new network","text":"<p>The first thing we need to do is tell Metamask how to connect to our local blockchain node. To do that:</p> <ul> <li>Click your account icon</li> <li> <p>In the drop down menu, click Settings </p> </li> <li> <p>On the left hand side of the page, click Networks</p> </li> <li> <p>Click the Add a network button   </p> </li> <li> <p>Fill in the network details:</p> </li> <li>Network Name: <code>FireFly</code> (could be any name)</li> <li>New RPC URL: <code>http://127.0.0.1:5100</code></li> <li>Chain ID: <code>2021</code></li> <li>Currency Symbol: ETH</li> <li>Click Save </li> </ul>"},{"location":"tutorials/tokens/erc20/#import-tokens","title":"Import tokens","text":"<p>Metamask won't know about our custom ERC-20 contract until we give it the Ethereum address for the contract, so that's what we'll do next.</p> <ul> <li> <p>Click on Import tokens </p> </li> <li> <p>Enter the Ethereum address of the contract</p> </li> <li>Enter a Token Symbol (can be anything you want)</li> <li>Click Add Custom Token</li> </ul> <p>NOTE: You can find the address of your contract from the response to the request to create the token pool above. You can also do a <code>GET</code> to <code>http://127.0.0.1:5000/api/v1/namespaces/default/tokens/pools</code> to lookup your configured token pools.</p> <p></p>"},{"location":"tutorials/tokens/erc20/#transfer-tokens_1","title":"Transfer tokens","text":"<p>Now you can copy your account address from your Metamask wallet, and perform a transfer from FireFly's API (as described above) to your Metamask address.</p> <p></p> <p>After a couple seconds, you should see your tokens show up in your Metamask wallet.</p> <p></p> <p>You can also send tokens to a FireFly address or any other Ethereum address from your Metamask wallet.</p> <p>NOTE: You can find the Ethereum addresses for organizations in your FireFly network in the Network \u2192 Organizations page in the FireFly explorer. Click on an organization and look under the Verifiers header for the organization's Ethereum address.</p> <p></p>"},{"location":"tutorials/tokens/erc721/","title":"Use ERC-721 tokens","text":""},{"location":"tutorials/tokens/erc721/#previous-steps-start-your-environment","title":"Previous steps: Start your environment","text":"<p>If you haven't started a FireFly stack already, please go to the Getting Started guide on how to Start your environment. This will set up a token connector that works with both ERC-20 and ERC-721 by default.</p> <p>\u2190 \u2461 Start your environment</p>"},{"location":"tutorials/tokens/erc721/#about-the-sample-token-contracts","title":"About the sample token contracts","text":"<p>If you are using the default ERC-20 / ERC-721 token connector, when the FireFly CLI set up your FireFly stack, it also deployed a token factory contract. When you create a token pool through FireFly's token APIs, the token factory contract will automatically deploy an ERC-20 or ERC-721 contract, based on the pool <code>type</code> in the API request.</p> \u26a0\ufe0f WARNING: The default token contract that was deployed by the FireFly CLI is only provided for the purpose of learning about FireFly. It is not a production grade contract. If you intend to deploy a production application using tokens on FireFly, you should research token contract best practices. For details, please see the source code for the contract that was deployed."},{"location":"tutorials/tokens/erc721/#use-the-sandbox-optional","title":"Use the Sandbox (optional)","text":"<p>At this point you could open the Sandbox at http://127.0.0.1:5109/home?action=tokens.pools and perform the functions outlined in the rest of this guide. Or you can keep reading to learn how to build HTTP requests to work with tokens in FireFly. </p>"},{"location":"tutorials/tokens/erc721/#create-a-pool-using-default-token-factory","title":"Create a pool (using default token factory)","text":"<p>After your stack is up and running, the first thing you need to do is create a token pool. Every application will need at least one token pool. At a minimum, you must always specify a <code>name</code> and <code>type</code> for the pool.</p> <p>If you're using the default ERC-20 / ERC-721 token connector and its sample token factory, it will automatically deploy a new ERC-721 contract instance.</p>"},{"location":"tutorials/tokens/erc721/#request","title":"Request","text":"<p><code>POST</code> <code>http://127.0.0.1:5000/api/v1/namespaces/default/tokens/pools?publish=true</code></p> <p>NOTE: Without passing the query parameter <code>publish=true</code> when the token pool is created, it will initially be unpublished and not broadcasted to other members of the network (if configured in multi-party). To publish the token pool, a subsequent API call would need to be made to <code>/tokens/pools/{nameOrId}/publish</code></p> <pre><code>{\n  \"type\": \"nonfungible\",\n  \"name\": \"nfts\"\n}\n</code></pre>"},{"location":"tutorials/tokens/erc721/#response","title":"Response","text":"<pre><code>{\n  \"id\": \"a92a0a25-b886-4b43-931f-4add2840258a\",\n  \"type\": \"nonfungible\",\n  \"namespace\": \"default\",\n  \"name\": \"nfts\",\n  \"key\": \"0x14ddd36a0c2f747130915bf5214061b1e4bec74c\",\n  \"connector\": \"erc20_erc721\",\n  \"tx\": {\n    \"type\": \"token_pool\",\n    \"id\": \"00678116-89d2-4295-990c-bd5ffa6e2434\"\n  },\n  \"published\": true\n}\n</code></pre> <p>Other parameters:</p> <ul> <li>You must specify a <code>connector</code> if you have configured multiple token connectors</li> <li>You may pass through a <code>config</code> object of additional parameters, if supported by your token connector</li> <li>You may specify a <code>key</code> understood by the connector (i.e. an Ethereum address) if you'd like to use a non-default signing identity</li> </ul>"},{"location":"tutorials/tokens/erc721/#get-the-address-of-the-deployed-contract","title":"Get the address of the deployed contract","text":"<p>To lookup the address of the new contract, you can lookup the token pool by its ID on the API. Creating the token pool will also emit an event which will contain the address. To query the token pool you can make a <code>GET</code> request to the pool's ID:</p>"},{"location":"tutorials/tokens/erc721/#request_1","title":"Request","text":"<p><code>GET</code> <code>http://127.0.0.1:5000/api/v1/namespaces/default/tokens/pools/5811e8d5-52d0-44b1-8b75-73f5ff88f598</code></p>"},{"location":"tutorials/tokens/erc721/#response_1","title":"Response","text":"<pre><code>{\n  \"id\": \"a92a0a25-b886-4b43-931f-4add2840258a\",\n  \"type\": \"nonfungible\",\n  \"namespace\": \"default\",\n  \"name\": \"nfts\",\n  \"standard\": \"ERC721\",\n  \"locator\": \"address=0xc4d02efcfab06f18ec0a68e00b98ffecf6bf7e3c&amp;schema=ERC721WithData&amp;type=nonfungible\",\n  \"connector\": \"erc20_erc721\",\n  \"message\": \"53d95dda-e8ca-4546-9226-a0fdc6ec03ec\",\n  \"state\": \"confirmed\",\n  \"created\": \"2022-04-29T12:03:51.971349509Z\",\n  \"info\": {\n    \"address\": \"0xc4d02efcfab06f18ec0a68e00b98ffecf6bf7e3c\",\n    \"name\": \"nfts\",\n    \"schema\": \"ERC721WithData\"\n  },\n  \"tx\": {\n    \"type\": \"token_pool\",\n    \"id\": \"00678116-89d2-4295-990c-bd5ffa6e2434\"\n  }\n}\n</code></pre>"},{"location":"tutorials/tokens/erc721/#create-a-pool-from-a-deployed-token-contract","title":"Create a pool (from a deployed token contract)","text":"<p>If you wish to index and use a contract that is already on the chain, it is recommended that you first upload the ABI for your specific contract by creating a FireFly contract interface. This step is optional if you're certain that your ERC-721 ABI conforms to the default expectations of the token connector, but is generally recommended.</p> <p>See the README of the token connector for details on what contract variants can currently be understood.</p> <p>You can pass a <code>config</code> object with an <code>address</code> and <code>blockNumber</code> when you make the request to create the token pool, and if you created a contract interface, you can include the <code>interface</code> ID as well.</p>"},{"location":"tutorials/tokens/erc721/#request_2","title":"Request","text":"<p><code>POST</code> <code>http://127.0.0.1:5000/api/v1/namespaces/default/tokens/pools?publish=true</code></p> <p>NOTE: Without passing the query parameter <code>publish=true</code> when the token pool is created, it will initially be unpublished and not broadcasted to other members of the network (if configured in multi-party). To publish the token pool, a subsequent API call would need to be made to <code>/tokens/pools/{nameOrId}/publish</code></p> <pre><code>{\n  \"name\": \"testpool\",\n  \"type\": \"nonfungible\",\n  \"interface\": {\n    \"id\": \"b9e5e1ce-97bb-4a35-a25c-52c7c3f523d8\"\n  },\n  \"config\": {\n    \"address\": \"0xb1C845D32966c79E23f733742Ed7fCe4B41901FC\",\n    \"blockNumber\": \"0\"\n  }\n}\n</code></pre>"},{"location":"tutorials/tokens/erc721/#mint-a-token","title":"Mint a token","text":"<p>Once you have a token pool, you can mint tokens within it. When using the sample contract deployed by the CLI, the following are true:</p> <ul> <li>only the creator of a pool is allowed to mint within that pool</li> <li>the <code>tokenIndex</code> must be set to a unique value</li> <li>the <code>amount</code> must be <code>1</code></li> </ul> <p>A different ERC-721 contract may define its own requirements.</p>"},{"location":"tutorials/tokens/erc721/#request_3","title":"Request","text":"<p><code>POST</code> <code>http://127.0.0.1:5000/api/v1/namespaces/default/tokens/mint</code></p> <pre><code>{\n  \"amount\": \"1\",\n  \"tokenIndex\": \"1\"\n}\n</code></pre>"},{"location":"tutorials/tokens/erc721/#response_2","title":"Response","text":"<pre><code>{\n  \"type\": \"mint\",\n  \"localId\": \"2de2e05e-9474-4a08-a64f-2cceb076bdaa\",\n  \"pool\": \"a92a0a25-b886-4b43-931f-4add2840258a\",\n  \"connector\": \"erc20_erc721\",\n  \"key\": \"0x14ddd36a0c2f747130915bf5214061b1e4bec74c\",\n  \"from\": \"0x14ddd36a0c2f747130915bf5214061b1e4bec74c\",\n  \"to\": \"0x14ddd36a0c2f747130915bf5214061b1e4bec74c\",\n  \"amount\": \"1\",\n  \"tx\": {\n    \"type\": \"token_transfer\",\n    \"id\": \"0fad4581-7cb2-42c7-8f78-62d32205c2c2\"\n  }\n}\n</code></pre> <p>Other parameters:</p> <ul> <li>You must specify a <code>pool</code> name if you've created more than one pool</li> <li>You may specify a <code>key</code> understood by the connector (i.e. an Ethereum address) if you'd like to use a non-default signing identity</li> <li>You may specify <code>to</code> if you'd like to send the minted tokens to a specific identity (default is the same as <code>key</code>)</li> </ul>"},{"location":"tutorials/tokens/erc721/#transfer-a-token","title":"Transfer a token","text":"<p>You may transfer tokens within a pool by specifying an amount and a destination understood by the connector (i.e. an Ethereum address). With the default sample contract, only the owner of the tokens or another approved account may transfer their tokens, but a different contract may define its own permission model.</p> <p>When transferring an NFT, you must also specify the <code>tokenIndex</code> that you wish to transfer. The <code>tokenIndex</code> is simply the ID of the specific NFT within the pool that you wish to transfer.</p> <p>NOTE: When transferring NFTs the <code>amount</code> must be <code>1</code>. If you wish to transfer more NFTs, simply call the endpoint multiple times, specifying the token index of each token to transfer.</p>"},{"location":"tutorials/tokens/erc721/#request_4","title":"Request","text":"<p><code>POST</code> <code>http://127.0.0.1:5000/api/v1/namespaces/default/tokens/transfers</code></p> <pre><code>{\n  \"amount\": \"1\",\n  \"tokenIndex\": \"1\",\n  \"to\": \"0xa4222a4ae19448d43a338e6586edd5fb2ac398e1\"\n}\n</code></pre>"},{"location":"tutorials/tokens/erc721/#response_3","title":"Response","text":"<pre><code>{\n  \"type\": \"transfer\",\n  \"localId\": \"f5fd0d13-db13-4d70-9a99-6bcd747f1e42\",\n  \"pool\": \"a92a0a25-b886-4b43-931f-4add2840258a\",\n  \"tokenIndex\": \"1\",\n  \"connector\": \"erc20_erc721\",\n  \"key\": \"0x14ddd36a0c2f747130915bf5214061b1e4bec74c\",\n  \"from\": \"0x14ddd36a0c2f747130915bf5214061b1e4bec74c\",\n  \"to\": \"0xa4222a4ae19448d43a338e6586edd5fb2ac398e1\",\n  \"amount\": \"1\",\n  \"tx\": {\n    \"type\": \"token_transfer\",\n    \"id\": \"63c1a89b-240c-41eb-84bb-323d56f4ba5a\"\n  }\n}\n</code></pre> <p>Other parameters:</p> <ul> <li>You must specify a <code>pool</code> name if you've created more than one pool</li> <li>You may specify a <code>key</code> understood by the connector (i.e. an Ethereum address) if you'd like to use a non-default signing identity</li> <li>You may specify <code>from</code> if you'd like to send tokens from a specific identity (default is the same as <code>key</code>)</li> </ul>"},{"location":"tutorials/tokens/erc721/#sending-data-with-a-transfer","title":"Sending data with a transfer","text":"<p>All transfers (as well as mint/burn operations) support an optional <code>message</code> parameter that contains a broadcast or private message to be sent along with the transfer. This message follows the same convention as other FireFly messages, and may be comprised of text or blob data, and can provide context, metadata, or other supporting information about the transfer. The message will be batched, hashed, and pinned to the primary blockchain.</p> <p>The message ID and hash will also be sent to the token connector as part of the transfer operation, to be written to the token blockchain when the transaction is submitted. All recipients of the message will then be able to correlate the message with the token transfer.</p> <p><code>POST</code> <code>http://127.0.0.1:5000/api/v1/namespaces/default/tokens/transfers</code></p>"},{"location":"tutorials/tokens/erc721/#broadcast-message","title":"Broadcast message","text":"<pre><code>{\n  \"amount\": 1,\n  \"tokenIndex\": \"1\",\n  \"to\": \"0x07eab7731db665caf02bc92c286f51dea81f923f\",\n  \"message\": {\n    \"data\": [\n      {\n        \"value\": \"payment for goods\"\n      }\n    ]\n  }\n}\n</code></pre>"},{"location":"tutorials/tokens/erc721/#private-message","title":"Private message","text":"<pre><code>{\n  \"amount\": 1,\n  \"tokenIndex\": \"1\",\n  \"to\": \"0x07eab7731db665caf02bc92c286f51dea81f923f\",\n  \"message\": {\n    \"header\": {\n      \"type\": \"transfer_private\"\n    },\n    \"group\": {\n      \"members\": [\n        {\n          \"identity\": \"org_1\"\n        }\n      ]\n    },\n    \"data\": [\n      {\n        \"value\": \"payment for goods\"\n      }\n    ]\n  }\n}\n</code></pre> <p>Note that all parties in the network will be able to see the transfer (including the message ID and hash), but only the recipients of the message will be able to view the actual message data.</p>"},{"location":"tutorials/tokens/erc721/#burn-tokens","title":"Burn tokens","text":"<p>You may burn a token by specifying the token's <code>tokenIndex</code>. With the default sample contract, only the owner of a token or another approved account may burn it, but a different contract may define its own permission model.</p> <p><code>POST</code> <code>http://127.0.0.1:5000/api/v1/namespaces/default/tokens/burn</code></p> <pre><code>{\n  \"amount\": 1,\n  \"tokenIndex\": \"1\"\n}\n</code></pre> <p>Other parameters:</p> <ul> <li>You must specify a <code>pool</code> name if you've created more than one pool</li> <li>You may specify a <code>key</code> understood by the connector (i.e. an Ethereum address) if you'd like to use a non-default signing identity</li> <li>You may specify <code>from</code> if you'd like to burn tokens from a specific identity (default is the same as <code>key</code>)</li> </ul>"},{"location":"tutorials/tokens/erc721/#token-approvals","title":"Token approvals","text":"<p>You can also approve other wallets to transfer tokens on your behalf with the <code>/approvals</code> API. The important fields in a token approval API request are as follows:</p> <ul> <li><code>approved</code>: Sets whether another account is allowed to transfer tokens out of this wallet or not. If not specified, will default to <code>true</code>. Setting to <code>false</code> can revoke an existing approval.</li> <li><code>operator</code>: The other account that is allowed to transfer tokens out of the wallet specified in the <code>key</code> field</li> <li><code>config.tokenIndex</code>: The specific token index within the pool that the operator is allowed to transfer. If <code>0</code> or not set, the approval is valid for all tokens.</li> <li><code>key</code>: The wallet address for the approval. If not set, it defaults to the address of the FireFly node submitting the transaction</li> </ul> <p>Here is an example request that would let the signing account <code>0x634ee8c7d0894d086c7af1fc8514736aed251528</code> transfer <code>tokenIndex</code> <code>2</code> from my wallet.</p>"},{"location":"tutorials/tokens/erc721/#request_5","title":"Request","text":"<p><code>POST</code> <code>http://127.0.0.1:5000/api/v1/namespaces/default/tokens/approvals</code></p> <pre><code>{\n  \"operator\": \"0x634ee8c7d0894d086c7af1fc8514736aed251528\",\n  \"config\": {\n    \"tokenIndex\": \"2\"\n  }\n}\n</code></pre>"},{"location":"tutorials/tokens/erc721/#response_4","title":"Response","text":"<pre><code>{\n  \"localId\": \"46fef50a-cf93-4f92-acf8-fae161b37362\",\n  \"pool\": \"e1477ed5-7282-48e5-ad9d-1612296bb29d\",\n  \"connector\": \"erc20_erc721\",\n  \"key\": \"0x14ddd36a0c2f747130915bf5214061b1e4bec74c\",\n  \"operator\": \"0x634ee8c7d0894d086c7af1fc8514736aed251528\",\n  \"approved\": true,\n  \"tx\": {\n    \"type\": \"token_approval\",\n    \"id\": \"00faa011-f42c-403d-a047-2df7318967cd\"\n  },\n  \"config\": {\n    \"tokenIndex\": \"2\"\n  }\n}\n</code></pre>"},{"location":"tutorials/tokens/erc721/#use-metamask","title":"Use Metamask","text":"<p>Now that you have an ERC-721 contract up and running, you may be wondering how to use Metamask (or some other wallet) with this contract. This section will walk you through how to connect Metamask to the blockchain and token contract that FireFly is using.</p>"},{"location":"tutorials/tokens/erc721/#configure-a-new-network","title":"Configure a new network","text":"<p>The first thing we need to do is tell Metamask how to connect to our local blockchain node. To do that:</p> <ul> <li>Click your account icon</li> <li> <p>In the drop down menu, click Settings </p> </li> <li> <p>On the left hand side of the page, click Networks</p> </li> <li> <p>Click the Add a network button   </p> </li> <li> <p>Fill in the network details:</p> </li> <li>Network Name: <code>FireFly</code> (could be any name)</li> <li>New RPC URL: <code>http://127.0.0.1:5100</code></li> <li>Chain ID: <code>2021</code></li> <li>Currency Symbol: ETH</li> <li>Click Save </li> </ul>"},{"location":"tutorials/tokens/erc721/#import-tokens","title":"Import tokens","text":"<p>Metamask won't know about our custom ERC-721 contract until we give it the Ethereum address for the contract, so that's what we'll do next.</p> <ul> <li> <p>Click on Import tokens </p> </li> <li> <p>Enter the Ethereum address of the contract</p> </li> <li>Enter a Token Symbol (can be anything you want)</li> <li>Click Add Custom Token</li> </ul> <p>NOTE: You can find the address of your contract from the response to the request to create the token pool above. You can also do a <code>GET</code> to <code>http://127.0.0.1:5000/api/v1/namespaces/default/tokens/pools</code> to lookup your configured token pools.</p> <p></p>"},{"location":"tutorials/tokens/erc721/#transfer-tokens","title":"Transfer tokens","text":"<p>Now you can copy your account address from your Metamask wallet, and perform a transfer from FireFly's API (as described above) to your Metamask address.</p> <p></p> <p>After a couple seconds, you should see your token show up in your Metamask wallet.</p> <p></p> <p>NOTE: While the NFT token balance can be viewed in Metamask, it does not appear that Metamask supports sending these tokens to another address at this time.</p>"}]}
\ No newline at end of file
+{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"]},"docs":[{"location":"","title":"Hyperledger FireFly","text":"<p>Hyperledger FireFly is an open source Supernode, a complete stack for enterprises to build and scale secure Web3 applications.</p> <p>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 that already exists, and the other set allows you to build new decentralized applications quickly with security and scalability.</p> <p>Head to the Understanding FireFly section for more details.</p>"},{"location":"SUMMARY/","title":"SUMMARY","text":"<ul> <li>Home</li> <li>Understanding FireFly<ul> <li>Introduction</li> <li>Usage Patterns</li> <li>Key Features<ul> <li>overview/key_components/*</li> </ul> </li> <li>Web3 Gateway Features</li> <li>Multiparty Features<ul> <li>overview/multiparty/*</li> </ul> </li> <li>Public and Permissioned</li> </ul> </li> <li>Getting Started<ul> <li>\u2460 Install the FireFly CLI</li> <li>\u2461 Start your environment</li> <li>\u2462 Use the Sandbox</li> </ul> </li> <li>Tutorials<ul> <li>tutorials/*</li> </ul> </li> <li>Reference<ul> <li>reference/*.md</li> <li>Microservices<ul> <li>reference/microservices/*.md</li> </ul> </li> <li>Types<ul> <li>reference/types/*.md</li> </ul> </li> </ul> </li> <li>Architecture<ul> <li>architecture/*</li> </ul> </li> <li>Contributors<ul> <li>contributors/*</li> </ul> </li> <li>API Spec</li> <li>FAQs</li> <li>Release Notes<ul> <li>releasenotes/*</li> </ul> </li> </ul>"},{"location":"architecture/blockchain_connector_framework/","title":"Blockchain Connector Toolkit","text":""},{"location":"architecture/blockchain_connector_framework/#blockchain-connector-framework","title":"Blockchain Connector Framework","text":"<p>Hyperledger FireFly has a multi-tier pluggable architecture for supporting blockchains of all shapes and sizes. This includes a remote API that allows a microservice connector to be built from scratch in any programming language.</p> <p>It also includes the Connector Toolkit, which is a pluggable SDK in Golang that provides a set of re-usable modules that can be used across blockchain implementations.</p> <p>This is the preferred way to build a new blockchain connector, if you are comfortable with coding in Golang and there are language bindings available for the raw RPC interface of your blockchain.</p>"},{"location":"architecture/blockchain_connector_framework/#connector-toolkit-architecture","title":"Connector Toolkit Architecture","text":"<p>The core component of the FireFly Connector Framework for Blockchains is a Go module called FireFly Transaction Manager (FFTM).</p> <p>FFTM is responsible for:</p> <ul> <li> <p>Submission of transactions to blockchains of all types</p> </li> <li> <p>Protocol connectivity decoupled with additional lightweight API connector</p> </li> <li> <p>Easy to add additional protocols that conform to normal patterns of TX submission / events</p> </li> <li> <p>Monitoring and updating blockchain operations</p> </li> <li> <p>Receipts</p> </li> <li> <p>Confirmations</p> </li> <li> <p>Extensible transaction handler with capabilities such as:</p> </li> <li> <p>Nonce management: idempotent submission of transactions, and assignment of nonces</p> </li> <li>Transaction management: pre-signing transactions, resubmission, customizable policy engine</li> <li>Gas management: Gas Gas station API integration</li> <li> <p>Transaction process history</p> </li> <li> <p>Event streaming</p> </li> <li>Protocol agnostic event polling/streaming support</li> <li>Reliable checkpoint restart</li> <li>At least once delivery API</li> </ul>"},{"location":"architecture/blockchain_connector_framework/#assumptions-requirements","title":"Assumptions / Requirements","text":"<p>The framework is currently constrained to blockchains that adhere to certain basic principals:</p> <ol> <li> <p>Has transactions</p> </li> <li> <p>That are signed</p> </li> <li> <p>That can optionally have gas semantics (limits and prices, expressed in a blockchain specific way)</p> </li> <li> <p>Has events (or \"logs\")</p> </li> <li> <p>That are emitted as a deterministic outcome of transactions</p> </li> <li> <p>Has blocks</p> </li> <li> <p>Containing zero or more transactions, with their associated events</p> </li> <li>With a sequential numeric order</li> <li>With a hash</li> <li> <p>With a parent hash</p> </li> <li> <p>Has finality for transactions &amp; events that can be expressed as a level of confidence over time</p> </li> <li> <p>Confirmations: A number of sequential blocks in the canonical chain that contain the transaction</p> </li> </ol>"},{"location":"architecture/blockchain_connector_framework/#nonce-management-in-the-simple-transaction-handler","title":"Nonce management in the simple transaction handler","text":"<p>The nonces for transactions is assigned as early as possible in the flow:</p> <ul> <li>Before the REST API for submission of the transaction occurs</li> <li>After the FFCAPI blockchain connector verifies the transaction can be encoded successfully to the chain</li> <li>With protection against multiple parallel API requests for the same signing address</li> <li>With stateful persistence meaning the connector knows about all nonces it previously allocated, to avoids duplicates</li> </ul> <p>This \"at source\" allocation of nonces provides the strictest assurance of order of transactions possible, because the order is locked in with the coordination of the business logic of the application submitting the transaction.</p> <p>As well as protecting against loss of transactions, this protects against duplication of transactions - even in crash recovery scenarios with a sufficiently reliable persistence layer.</p>"},{"location":"architecture/blockchain_connector_framework/#avoid-multiple-nonce-management-systems-against-the-same-signing-key","title":"Avoid multiple nonce management systems against the same signing key","text":"<p>FFTM is optimized for cases where all transactions for a given signing address flow through the same FireFly connector. If you have signing and nonce allocation happening elsewhere, not going through the FireFly blockchain connector, then it is possible that the same nonce will be allocated in two places.</p> <p>Be careful that the signing keys for transactions you stream through the Nonce Management of the FireFly blockchain connector are not used elsewhere.</p> <p>If you must have multiple systems performing nonce management against the same keys you use with FireFly nonce management, you can set the <code>transactions.nonceStateTimeout</code> to <code>0</code> (or a low threshold like <code>100ms</code>) to cause the nonce management to query the pending transaction pool of the node every time a nonce is allocated.</p> <p>This reduces the window for concurrent nonce allocation to be small (basically the same as if you had multiple simple web/mobile wallets used against the same key), but it does not eliminate it completely it.</p>"},{"location":"architecture/blockchain_connector_framework/#why-at-source-nonce-management-was-chosen-vs-at-target","title":"Why \"at source\" nonce management was chosen vs. \"at target\"","text":"<p>The \"at source\" approach to ordering used in FFTM could be compared with the \"at target\" allocation of nonces used in EthConnect).</p> <p>The \"at target\" approach optimizes for throughput and ability to send new transactions to the chain, with an at-least-once delivery assurance to the applications.</p> <p>An \"at target\" algorithm as used in EthConnect could resume transaction delivery automatically without operator intervention from almost all scenarios, including where nonces have been double allocated.</p> <p>However, \"at target\" comes with two compromises that mean FFTM chose the \"at source\" approach was chosen for FFTM:</p> <ul> <li> <p>Individual transactions might fail in certain scenarios, and subsequent transactions will still be streamed to the chain.   While desirable for automation and throughput, this reduces the ordering guarantee for high value transactions.</p> </li> <li> <p>In crash recovery scenarios the assurance is at-least-once delivery for \"at target\" ordering (rather than \"exactly once\"),   although the window can be made very small through various optimizations included in the EthConnect codebase.</p> </li> </ul>"},{"location":"architecture/blockchain_connector_framework/#transaction-handler","title":"Transaction Handler","text":"<p>The transaction Handler is a pluggable component that allows customized logic to be applied to the gas pricing, signing, submission and re-submission of transactions to the blockchain.</p> <p>The transaction Handler can store custom state in the state store of the FFTM code, which is also reported in status within the FireFly API/Explorer on the operation.</p> <p>A reference implementation is provided that:</p> <ul> <li>Submits transactions via the underlying FFCAPI</li> <li>Estimates gas price in one of three modes:</li> <li>Fixed: It is specified via configuration</li> <li>Connector: The FFCAPI is used to estimate the gas price (e.g. <code>eth_gasPrice</code> for EVM JSON/RPC)</li> <li>Gas Oracle: A REST API is called the the result mapped via a Go template</li> <li>Re-submits transactions after a configurable stale time</li> <li>Record detailed information about transaction sub-status and actions</li> <li>Emit customized metrics for transaction processing</li> </ul> <p>The reference implementation is available here</p>"},{"location":"architecture/blockchain_connector_framework/#event-streams","title":"Event Streams","text":"<p>One of the largest pieces of heavy lifting code in the FFTM codebase, is the event stream support. This provides a WebSocket (and Webhook) interface that FireFly Core and the Tokens Connectors connect to in order to receive ordered streams of events from the blockchain.</p> <p>The interface down to the blockchain layer is via go channels, and there are lifecycle interactions over the FFCAPI to the blockchain specific code to add and remove listeners for different types of blockchain events.</p> <p>Some high architectural principals that informed the code:</p> <ul> <li>Event Stream</li> <li>A delivery stream of events that have been confirmed</li> <li>Only events that have reached finality are delivered to an event stream</li> <li>FireFly creates a single event stream per namespace from core</li> <li>Each token connector creates a single event stream</li> <li>If one event stream is blocked, it must not block other streams in the FFTM based runtime</li> <li>Listener (/Subscription)</li> <li>A blockchain specific specification for a set of events to listen to</li> <li>Specifies an initial block to listen from, and will replay all events from that block</li> <li>Can have multiple blockchain specific filters, to match multiple events</li> <li>The order of delivery within a listener matches the blockchain across all filters     &gt; - Note that the EVMConnect implementation of FFCAPI attempts to make this true across all listeners     &gt;   on an event stream. However, this is impossible when a new listener has been added,     &gt;   and that listener is catching up from an old block.</li> <li>Compatibility</li> <li>Has breaking changes from the API of EthConnect</li> <li>A component that has been upgraded to support EVMConnect,     can maintain backwards compatibility with EthConnect</li> <li>Batching &amp; Checkpoints</li> <li>Delivery on event streams is via batches, with a single confirmation for each batch</li> <li>At-least-once delivery of batches</li> <li>Checkpoints are written after each batch</li> <li>Chain head stability</li> <li>A configurable section of the head of the chain is considered unstable</li> <li>If no events have been delivered for a listener, checkpoints are still moved forwards</li> <li>These empty checkpoints will never be written in the unstable head of the chain</li> <li>Confirmation manager</li> <li>Plugged in between detection of the events, and assembling into batches</li> <li>Determines the final order based on order of confirmation on the blockchain</li> </ul> <p></p>"},{"location":"architecture/internal_event_sequencing/","title":"Internal Event Sequencing","text":""},{"location":"architecture/internal_event_sequencing/#overview","title":"Overview","text":"<p>One of the most important roles FireFly has, is to take actions being performed by the local apps, process them, get them confirmed, and then deliver back as \"stream of consciousness\" to the application alongside all the other events that are coming into the application from other FireFly Nodes in the network.</p> <p>You might observe the problems solved in this architecture are similar to those in a message queuing system (like Apache Kafka, or a JMS/AMQP provider like ActiveMQ etc.).</p> <p>However, we cannot directly replace the internal logic with such a runtime - because FireFly's job is to aggregate data from multiple runtimes that behave similarly to these:</p> <ul> <li>Private messaging in the Data Exchange</li> <li>The blockchain ledger(s) themselves, which are a stream of sequenced events</li> <li>The event dispatcher delivering messages to applications that have been sequenced by FireFly</li> </ul> <p>So FireFly provides the convenient REST based management interface to simplify the world for application developers, by aggregating the data from multiple locations, and delivering it to apps in a deterministic sequence.</p> <p>The sequence is made deterministic:</p> <ul> <li>Globally to all apps within the scope of the ledger, when a Blockchain ledger is used to pin events (see #10)</li> <li>Locally for messages delivered through a single FireFly node into the network</li> <li>Locally for all messages delivered to applications connected to a FireFly node, across blockchain</li> </ul>"},{"location":"architecture/internal_event_sequencing/#app-instances","title":"App Instances","text":"<ul> <li>Broadcast messages to the network</li> <li>Ingest ack when message persisted in local messages table</li> <li>Consume events via Websocket connection into FireFly</li> </ul>"},{"location":"architecture/internal_event_sequencing/#outbound-sequencers","title":"Outbound Sequencers","text":"<ul> <li>Broadcast or Private through IPFS or Private Data Storage</li> <li>Long-running leader-elected jobs listening to the database (via event tables in SQL, etc.)</li> </ul>"},{"location":"architecture/internal_event_sequencing/#inbound-aggregator","title":"Inbound Aggregator","text":"<ul> <li>Triggered each time an event is detected by the associated plugin.</li> <li>It is the responsibility of the plugin to fire events sequentially. Can be workload managed but must be sequential.</li> </ul>"},{"location":"architecture/internal_event_sequencing/#events-table","title":"Events Table","text":"<ul> <li>Deliberately lightweight persisted object, that is generated as a byproduct of other persistent actions.</li> <li>Records the local sequence of a specific event within the local node.</li> <li>The highest level event type is the confirmation of a message, however the table can be extended for more granularity on event types.</li> </ul>"},{"location":"architecture/internal_event_sequencing/#subscription-manager","title":"Subscription Manager","text":"<ul> <li>Responsible for filtering and delivering batches of events to the active event dispatchers.</li> <li>Records the latest offset confirmed by each dispatcher.</li> </ul>"},{"location":"architecture/internal_event_sequencing/#event-dispatcher","title":"Event Dispatcher","text":"<ul> <li>Created with leadership election when WebSocket connection is made from an app into FireFly.</li> <li>Extensible to other dispatchers (AMQP, etc.).</li> </ul>"},{"location":"architecture/multiparty_event_sequencing/","title":"Multiparty Event Sequencing","text":""},{"location":"architecture/multiparty_event_sequencing/#transaction-submission","title":"Transaction Submission","text":"<ul> <li>An individual FireFly instance preserves the order that it received messages from application instances.</li> <li>Where possible, batching is used to roll-up hundreds of transactions into a single blockchain transaction.</li> <li>Blockchain allows these messages to be globally sequenced with messages submitted by other members of the network.</li> </ul>"},{"location":"architecture/multiparty_event_sequencing/#blockchain-ordering","title":"Blockchain Ordering","text":"<ul> <li>All member FireFly runtimes see every transaction in the same sequence.</li> <li>This includes when transactions are being submitted by both sides concurrently.</li> </ul>"},{"location":"architecture/multiparty_event_sequencing/#message-assembly","title":"Message Assembly","text":"<ul> <li>A queue of events is maintained for each matching app subscription.</li> <li>The public/private payloads travel separately to the blockchain, and arrive at different times. FireFly assembles these together prior to delivery.</li> <li>If data associated with a blockchain transaction is late, or does not arrive, all messages on the same \"context\" will be blocked.</li> <li>It is good practice to send messages that don't need to be processed in order, with different \"context\" fields. For example use the ID of your business transaction, or other long-running process / customer identifier.</li> </ul>"},{"location":"architecture/multiparty_event_sequencing/#event-processing","title":"Event Processing","text":"<ul> <li>Events are processed consistently by all parties.</li> <li>All FireFly runtimes see every event that they are subscribed to, in the same sequence.</li> <li>The submitter must also apply the logic only in the sequence ordered by the blockhain. It cannot assume the order even if it is the member that submitted it.</li> </ul>"},{"location":"architecture/node_component_architecture/","title":"Node Component Architecture","text":""},{"location":"architecture/node_component_architecture/#what-is-a-firefly-node","title":"What is a FireFly Node?","text":"<p>The core architecture of a FireFly node can be broken down into the following three areas:</p> <ul> <li>The various runtimes encapsulating the node.</li> <li>The core runtime responsibilities and pluggable elements.</li> <li>The actual code running inside the node.</li> </ul> <p></p>"},{"location":"architecture/node_component_architecture/#runtimes","title":"Runtimes","text":"<p>What fundamentally is a node - left side of the above diagram.</p> <ul> <li>It is a collection of multiple runtimes with a single unified HTTPS/Websocket API (exposed by the Core).</li> <li>It has a private database, containing your private data, and data received from others in the network.</li> <li>It has connectivity out to other parties in the network, through runtimes (Blockchain, Shared Filesystems, Messaging etc.).</li> </ul>"},{"location":"architecture/node_component_architecture/#responsibilities-pluggable-elements","title":"Responsibilities &amp; Pluggable Elements","text":"<p>What are the core runtime responsibilities, and pluggable elements - right side of the above diagram.</p> <ul> <li>The core elements of function that FireFly performs, and which runtime is responsible.</li> <li>This means some insight into core itself, and the jobs it performs, but not full code structure.</li> <li>More importantly, what the split of responsibilities is between <code>Connectors</code> and <code>Infrastructure Runtimes</code>.<ul> <li><code>Connectors</code> are the bridging runtimes, that know how to talk to a particular runtime.</li> <li>They run separately to the core (like a microservice architecture of an app).</li> <li>They can be written in any language (not just Go) - Java, TypeScript, Rust, Python, .NET etc.</li> <li>They can use any network transport (not just HTTPS/Websockets) - GRPC, AMQP, UDP etc.</li> <li>They connect to the core with a Golang shim - see separate Plugin Architecture discussion.     &gt; - In some special cases (like the Database) the Golang shim does not need a connector runtime.</li> <li><code>Infrastructure Runtimes</code> are the core runtimes for multi-party system activities.</li> <li>Blockchain nodes - Ethereum (Hyperledger Besu, Quorum, Geth), Hyperledger Fabric, Corda etc.</li> <li>Shared strorage - IPFS etc.</li> <li>Database - PostreSQL, CouchDB etc.</li> </ul> </li> </ul>"},{"location":"architecture/node_component_architecture/#code-structure","title":"Code Structure","text":"<p>What is the code structure inside the core.</p> <ul> <li>The README.md is the reference for this.</li> <li>Developers contributing to FireFly, on the core, or building new plugins, need this level of detail. <ul> <li>A reconciliation is underway to ensure the medium-level view correlates well with this code structure.</li> </ul> </li> </ul>"},{"location":"architecture/ping_pong_txflow/","title":"Example Transaction Flow (Ping Pong)","text":""},{"location":"architecture/ping_pong_txflow/#overview","title":"Overview","text":"<p>This demonstrates the problem that at its core FireFly is there to solve. The internal plumbing complexity of just a very simple set of Enterprise blockchain / multi-party system interactions.</p> <ul> <li>Party A: Establish existence of a digital asset.</li> <li>Nothing more than some binary data (an image, a document, a specification etc.).</li> <li>Party A: Broadcast some information about that asset to everyone, using blockchain to record, sequence and propagate.</li> <li>So people can find it, or part of a more sophisticated workflow.</li> <li>Party B: Request the actual data - with evidence of that request tied to the blockchain.</li> <li>Including some private data that's sent to the Party A, reliably off-chain.</li> <li>Party A: Authorize the request, and send the data privately to Party B.</li> <li>In this example there's no blockchain involved in this step.</li> </ul> <p>This is the kind of thing that enterprise projects have been solving ground-up since the dawn of enterprise blockchain, and the level of engineering required that is completely detached from business value, is very high.</p> <p>The \"tramlines\" view shows how FireFly's pluggable model makes the job of the developer really simple:</p> <ul> <li>A few simple API calls from a modern web app.</li> <li>Event triggered execution of application logic.</li> </ul> <p>This is deliberately a simple flow, and all kinds of additional layers might well layer on (and fit within the FireFly model):</p> <ul> <li>NFTs to track ownership etc. related to the digital asset.</li> <li>Tokenized rewards/payments integrated with the authorization of the transfer of data.</li> <li>Proof of deterministic execution of the logic to perform the authorization (on-chain, TEEs, ZKPs).</li> <li>Human workflow, that is of course completely non-deterministic.</li> <li>Multiple additional process steps, deterministic or not.</li> <li>Inclusion of multiple additional parties (maybe it's a request-for-tender, submit-tender flow for example).</li> <li>etc.</li> </ul>"},{"location":"architecture/ping_pong_txflow/#broadcast-public-description-of-binary-data-asset-member-1","title":"Broadcast Public Description of Binary Data Asset (Member 1)","text":"<ul> <li>Upload Blob of the actual data</li> <li>Returns a hash of the payload</li> <li>Upload JSON containing the public index data</li> <li>Includes the hash of the full payload</li> <li>Send a broadcast message with the public index data</li> <li>Agree upon a primary key of the data as the \"context\"</li> </ul>"},{"location":"architecture/ping_pong_txflow/#receive-public-description-request-asset-data-member-2","title":"Receive Public Description &amp; Request Asset Data (Member 2)","text":"<ul> <li>Store data in your own off-chain database for rich, efficient query</li> <li>Run automated logic to decide if you want to request the full data</li> <li>Upload JSON for data request</li> <li>Send a private message</li> <li>Backed by blockchain in this flow</li> </ul>"},{"location":"architecture/ping_pong_txflow/#authorize-transfer-data-member-1","title":"Authorize &amp; Transfer Data (Member 1)","text":"<ul> <li>Inspect the request data</li> <li>Retrieve data asset by hash</li> <li>Send the private data in a private message</li> <li>No blockchain in this flow</li> </ul>"},{"location":"architecture/ping_pong_txflow/#receive-data-asset-member-2","title":"Receive Data Asset (Member 2)","text":"<ul> <li>Receive a link to your local copy of the asset data</li> </ul>"},{"location":"architecture/plugin_architecture/","title":"Plugin Architecture","text":"<p> This diagram shows the various plugins that are currently in the codebase and the layers in each plugin</p> <p> This diagram shows the details of what goes into each layer of a FireFly plugin</p>"},{"location":"architecture/plugin_architecture/#overview","title":"Overview","text":"<p>The FireFly node is built for extensibility, with separate pluggable runtimes orchestrated into a common API for developers. The mechanics of that pluggability for developers of new connectors is explained below:</p> <p>This architecture is designed to provide separations of concerns to account for:</p> <ul> <li>Differences in code language for the low-level connection to a backend (Java for Corda for example)</li> <li>Differences in transports, particularly for delivery of events:</li> <li>Between FireFly Core and the Connector<ul> <li>Different transports other than HTTPS/WebSockets (GRPC etc.), and different wire protocols (socket.io, etc.)</li> </ul> </li> <li>Between the Connector and the underlying Infrastructure Runtime<ul> <li>Often this is heavy lifting engineering within the connector</li> </ul> </li> <li>Differences in High Availability (HA) / Scale architectures</li> <li>Between FireFly Core, and the Connector<ul> <li>Often for event management, and active/passive connector runtime is sufficient</li> </ul> </li> <li>Between the Connector and the Infrastructure Runtime<ul> <li>The infrastructure runtimes have all kinds of variation here... think of the potential landscape here from PostreSQL through Besu/Fabric/Corda, to Hyperledger Avalon and even Main-net ethereum</li> </ul> </li> </ul>"},{"location":"architecture/plugin_architecture/#firefly-core","title":"FireFly Core","text":"<ul> <li>Golang</li> <li>N-way scalable cluster</li> <li>Database is also pluggable via this architecture</li> <li>No long lived in-memory processing</li> <li>All micro-batching must be recoverable</li> <li>Driven by single configuration set</li> <li>Viper semantics - file, env var, cmdline flags</li> </ul>"},{"location":"architecture/plugin_architecture/#plugin-for-connector","title":"Plugin for Connector","text":"<ul> <li>Golang</li> <li>Statically compiled in support at runtime</li> <li>Go dynamic plugin support too immature</li> <li>Must be 100% FLOSS code (no GPL/LGPL etc.)</li> <li>Contributed via PR to FF Core</li> <li>Intended to be lightweight binding/mapping</li> <li>Must adhere to FF Core Coding Standards</li> <li>Scrutiny on addition of new frameworks/transports</li> </ul>"},{"location":"architecture/plugin_architecture/#connector","title":"Connector","text":"<ul> <li>Node.js / Java / Golang, etc.</li> <li>Runs/scales independently from FF core</li> <li>Coded in any language, OSS or proprietary</li> <li>One runtime or multiple</li> <li>HA model can be active/passive or active/active</li> <li>Expectation is all plugins need a connector</li> <li>Some exceptions exist (e.g. database plugin)</li> </ul>"},{"location":"architecture/plugin_architecture/#infrastructure-runtime","title":"Infrastructure Runtime","text":"<ul> <li>Besu, Quorum, Corda, Fabric, IPFS, Kafka, etc.</li> <li>Runs/scales independently from FF Core</li> <li>Coded in any language, OSS or proprietary</li> <li>Not specific to FireFly</li> <li>HA model can be active/passive or active/active</li> </ul>"},{"location":"contributors/","title":"Contributors' Guide","text":"<p>We welcome anyone to contribute to the FireFly project! If you're interested, this is a guide on how to get started. You don't have to be a blockchain expert to make valuable contributions! There are lots of places for developers of all experience levels to get involved.</p> <p>\ud83e\uddd1\ud83c\udffd\u200d\ud83d\udcbb \ud83d\udc69\ud83c\udffb\u200d\ud83d\udcbb \ud83d\udc69\ud83c\udffe\u200d\ud83d\udcbb \ud83e\uddd1\ud83c\udffb\u200d\ud83d\udcbb \ud83e\uddd1\ud83c\udfff\u200d\ud83d\udcbb \ud83d\udc68\ud83c\udffd\u200d\ud83d\udcbb \ud83d\udc69\ud83c\udffd\u200d\ud83d\udcbb \ud83e\uddd1\ud83c\udffe\u200d\ud83d\udcbb \ud83d\udc68\ud83c\udfff\u200d\ud83d\udcbb \ud83d\udc68\ud83c\udffe\u200d\ud83d\udcbb \ud83d\udc69\ud83c\udfff\u200d\ud83d\udcbb \ud83d\udc68\ud83c\udffb\u200d\ud83d\udcbb</p>"},{"location":"contributors/#connect-with-us-on-discord","title":"\ud83d\ude80 Connect with us on Discord","text":"<p>You can chat with maintainers and other contributors on Discord in the <code>firefly</code> channel: https://discord.gg/hyperledger</p> <p>Join Discord Server</p>"},{"location":"contributors/#join-our-community-calls","title":"\ud83d\udcc5 Join our Community Calls","text":"<p>Community calls are a place to talk to other contributors, maintainers, and other people interested in FireFly. Maintainers often discuss upcoming changes and proposed new features on these calls. These calls are a great way for the community to give feedback on new ideas, ask questions about FireFly, and hear how others are using FireFly to solve real world problems.</p> <p>Please see the FireFly Calendar for the current meeting schedule, and the link to join. Everyone is welcome to join, regardless of background or experience level.</p>"},{"location":"contributors/#find-your-first-issue","title":"\ud83d\udd0d Find your first issue","text":"<p>If you're looking for somewhere to get started in the FireFly project and want something small and relatively easy, take a look at issues tagged with \"Good first issue\". You can definitely work on other things if you want to. These are only suggestions for easy places to get started.</p> <p>See \"Good First Issues\"</p> <p>NOTE Hyperledger FireFly has a microservice architecture so it has many different GitHub repos. Use the link or the button above to look for \"Good First Issues\" across all the repos at once.</p> <p>Here are some other suggestions of places to get started, based on experience you may already have:</p>"},{"location":"contributors/#any-level-of-experience","title":"Any level of experience","text":"<p>If you looking to make your first open source contribution the FireFly documentation is a great place to make small, easy improvements. These improvements are also very valuable, because they help the next person that may want to know the same thing.</p> <p>Here are some detailed instructions on Contributing to Documentation</p>"},{"location":"contributors/#go-experience","title":"Go experience","text":"<p>If you have some experience in Go and really want to jump into FireFly, the FireFly Core is the heart of the project.</p> <p>Here are some detailed instructions on Setting up a FireFly Core Development Environment.</p>"},{"location":"contributors/#little-or-no-go-experience-but-want-to-learn","title":"Little or no Go experience, but want to learn","text":"<p>If you don't have a lot of experience with Go, but are interested in learning, the FireFly CLI might be a good place to start. The FireFly CLI is a tool to set up local instances of FireFly for building apps that use FireFly, and for doing development on FireFly itself.</p>"},{"location":"contributors/#typescript-experience","title":"TypeScript experience","text":"<p>If you have some experience in TypeScript, there are several FireFly microservices that are written in TypeScript. The Data Exchange is used for private messaging between FireFly nodes. The ERC-20/ERC-271 Tokens Connector and ERC-1155 Tokens Connector are used to abstract token contract specifics from the FireFly Core.</p>"},{"location":"contributors/#reacttypescript-experience","title":"React/TypeScript experience","text":"<p>If you want to do some frontend development, the FireFly UI is written in TypeScript and React.</p>"},{"location":"contributors/#go-and-blockchain-experience","title":"Go and blockchain experience","text":"<p>If you already have some experience with blockchain and want to work on some backend components, the blockchain connectors, firefly-ethconnect (for Ethereum) and firefly-fabconnect (for Fabric) are great places to get involved.</p>"},{"location":"contributors/#make-changes","title":"\ud83d\udcdd Make changes","text":"<p>To contribute to the repository, please fork the repository that you want to change. Then clone your fork locally on your machine and make your changes. As you commit your changes, push them to your fork. More information on making commits below.</p>"},{"location":"contributors/#commit-with-developer-certificate-of-origin","title":"\ud83d\udcd1 Commit with Developer Certificate of Origin","text":"<p>As with all Hyperledger repositories, FireFly requires proper sign-off on every commit that is merged into the <code>main</code> branch. The sign-off indicates that you certify the changes you are submitting are in accordance with the Developer Certificate of Origin. To sign-off on your commit, you can use the <code>-s</code> flag when you commit changes.</p> <pre><code>git commit -s -m \"Your commit message\"\n</code></pre> <p>This will add a string like this to the end of your commit message:</p> <pre><code>\"Signed-off-by: Your Name &lt;your-email@address&gt;\"\n</code></pre> <p>NOTE: Sign-off is not the same thing as signing your commits with a private key. Both operations use a similar flag, which can be confusing. The one you want is the lowercase <code>-s</code> \ud83d\ude42</p>"},{"location":"contributors/#open-a-pull-request","title":"\ud83d\udce5 Open a Pull Request","text":"<p>When you're ready to submit your changes for review, open a Pull Request back to the upstream repository. When you open your pull request, the maintainers will automatically be notified. Additionally, a series of automated checks will be performed on your code to make sure it passes certain repository specific requirements.</p> <p>Maintainers may have suggestions on things to improve in your pull request. It is our goal to get code that is beneficial to the project merged as quickly as possible, so we don't like to leave pull requests hanging around for a long time. If the project maintainers are satisfied with the changes, they will approve and merge the pull request.</p> <p>Thanks for your interest in collaborating on this project!</p>"},{"location":"contributors/#inclusivity","title":"Inclusivity","text":"<p>The Hyperledger Foundation and the FireFly project are committed to fostering a community that is welcoming to all people. When participating in community discussions, contributing code, or documentaiton, please abide by the following guidelines:</p> <ul> <li>Consider that users who will read the docs are from different background and cultures and that they have different preferences.</li> <li>Avoid potential offensive terms and, for instance, prefer \"allow list and deny list\" to \"white list and black list\".</li> <li>We believe that we all have a role to play to improve our world, and even if writing inclusive doc might not look like a huge improvement, it's a first step in the right direction.</li> <li>We suggest to refer to Microsoft bias free writing guidelines and Google inclusive doc writing guide as starting points.</li> </ul>"},{"location":"contributors/advanced_cli_usage/","title":"Advanced CLI Usage","text":"<p>This page details some of the more advanced options of the FireFly CLI</p>"},{"location":"contributors/advanced_cli_usage/#understanding-how-the-cli-uses-firefly-releases","title":"Understanding how the CLI uses FireFly releases","text":""},{"location":"contributors/advanced_cli_usage/#the-manifestjson-file","title":"The <code>manifest.json</code> file","text":"<p>FireFly has a <code>manifest.json</code> file in the root of the repo. This file contains a list of versions (both tag and sha) for each of the microservices that should be used with this specific commit.</p> <p>Here is an example of what the <code>manifest.json</code> looks like:</p> <pre><code>{\n  \"ethconnect\": {\n    \"image\": \"ghcr.io/hyperledger/firefly-ethconnect\",\n    \"tag\": \"v3.0.4\",\n    \"sha\": \"0b7ce0fb175b5910f401ff576ced809fe6f0b83894277c1cc86a73a2d61c6f41\"\n  },\n  \"fabconnect\": {\n    \"image\": \"ghcr.io/hyperledger/firefly-fabconnect\",\n    \"tag\": \"v0.9.0\",\n    \"sha\": \"a79a4c66b0a2551d5122d019c15c6426e8cdadd6566ce3cbcb36e008fb7861ca\"\n  },\n  \"dataexchange-https\": {\n    \"image\": \"ghcr.io/hyperledger/firefly-dataexchange-https\",\n    \"tag\": \"v0.9.0\",\n    \"sha\": \"0de5b1db891a02871505ba5e0507821416d9fa93c96ccb4b1ba2fac45eb37214\"\n  },\n  \"tokens-erc1155\": {\n    \"image\": \"ghcr.io/hyperledger/firefly-tokens-erc1155\",\n    \"tag\": \"v0.9.0-20211019-01\",\n    \"sha\": \"aabc6c483db408896838329dab5f4b9e3c16d1e9fa9fffdb7e1ff05b7b2bbdd4\"\n  }\n}\n</code></pre>"},{"location":"contributors/advanced_cli_usage/#default-cli-behavior-for-releases","title":"Default CLI behavior for releases","text":"<p>When creating a new stack, the CLI will by default, check the latest non-pre-release version of FireFly and look at its <code>manifest.json</code> file that was part of that commit. It will then use the Docker images referenced in that file to determine which images it should pull for the new stack. The specific image tag and sha is written to the <code>docker-compose.yml</code> file for that stack, so restarting or resetting a stack will never pull a newer image.</p>"},{"location":"contributors/advanced_cli_usage/#running-a-specific-release-of-firefly","title":"Running a specific release of FireFly","text":"<p>If you need to run some other version that is not the latest release of FireFly, you can tell the FireFly CLI which release to use by using the <code>--release</code> or <code>-r</code> flag. For example, to explicitly use <code>v0.9.0</code> run this command to initialize the stack:</p> <pre><code>ff init -r v0.9.0\n</code></pre>"},{"location":"contributors/advanced_cli_usage/#running-an-unreleased-version-of-one-or-more-services","title":"Running an unreleased version of one or more services","text":"<p>If you need to run an unreleased version of FireFly or one of its microservices, you can point the CLI to a specific <code>manifest.json</code> on your local disk. To do this, use the <code>--manifest</code> or <code>-m</code> flag. For example, if you have a file at <code>~/firefly/manifest.json</code>:</p> <pre><code>ff init -m ~/firefly/manifest.json\n</code></pre> <p>If you need to test a locally built docker image of a specific service, you'll want to edit the <code>manifest.json</code> before running <code>ff init</code>. Let's look at an example where we want to run a locally built version of fabconnect. The same steps apply to any of FireFly's microservices.</p>"},{"location":"contributors/advanced_cli_usage/#build-a-new-image-of-fabconnect-locally","title":"Build a new image of fabconnect locally","text":"<p>From the fabconnect project directory, build and tag a new Docker image:</p> <pre><code>docker build -t ghcr.io/hyperledger/firefly-fabconnect .\n</code></pre>"},{"location":"contributors/advanced_cli_usage/#edit-your-manifestjson-file","title":"Edit your <code>manifest.json</code> file","text":"<p>Next, edit the <code>fabconnect</code> section of the <code>manifest.json</code> file. You'll want to remove the <code>tag</code> and <code>sha</code> and a <code>\"local\": true</code> field, so it looks like this:</p> <pre><code>...\n  \"fabconnect\": {\n    \"image\": \"ghcr.io/hyperledger/firefly-fabconnect\",\n    \"local\": true\n  },\n...\n</code></pre>"},{"location":"contributors/advanced_cli_usage/#initialize-the-stack-with-the-custom-manifestjson-file","title":"Initialize the stack with the custom <code>manifest.json</code> file","text":"<pre><code> ff init local-test -b fabric -m ~/Code/hyperledger/firefly/manifest.json\n ff start local-test\n</code></pre> <p>If you are iterating on changes locally, you can get the CLI to use an updated image by doing the following:</p> <ul> <li>Whenever the CLI does its first time setup, it will use your newly built local docker image</li> <li>If you've already run the stack, you can run <code>ff reset &lt;stack_name&gt;</code> and <code>ff start &lt;stack_name&gt;</code> to reset the data, and use the newer image</li> </ul>"},{"location":"contributors/advanced_cli_usage/#running-a-locally-built-firefly-core-image","title":"Running a locally built FireFly Core image","text":"<p>You may have noticed that FireFly core is actually not listed in the <code>manifest.json file</code>. If you want to run a locally built image of FireFly Core, you can follow the same steps above, but instead of editing an existing section in the file, we'll add a new one for FireFly.</p>"},{"location":"contributors/advanced_cli_usage/#build-a-new-image-of-firefly-locally","title":"Build a new image of FireFly locally","text":"<p>From the firefly project directory, build and tag a new Docker image:</p> <pre><code>make docker\n</code></pre>"},{"location":"contributors/advanced_cli_usage/#initialize-the-stack-with-the-custom-manifestjson-file_1","title":"Initialize the stack with the custom <code>manifest.json</code> file","text":"<pre><code> ff init local-test -m ~/Code/hyperledger/firefly/manifest.json\n ff start local-test\n</code></pre>"},{"location":"contributors/code_hierarchy/","title":"FireFly Code Hierarchy","text":"<p>Use the following diagram to better understand the hierarchy amongst the core FireFly components, plugins and utility frameworks:</p> <pre><code>\u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510  \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510\n\u2502 cmd      \u251c\u2500\u2500\u2524 firefly   [Ff]\u2502  - CLI entry point\n\u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518  \u2502               \u2502  - Creates parent context\n              \u2502               \u2502  - Signal handling\n              \u2514\u2500\u2500\u2500\u2500\u2500\u252c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n                    \u2502\n\u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510  \u250c\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510  - HTTP listener (Gorilla mux)\n\u2502 internal \u251c\u2500\u2500\u2524 api       [As]\u2502    * TLS (SSL), CORS configuration etc.\n\u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518  \u2502 server        \u2502    * WS upgrade on same port\n              \u2502               \u2502  - REST route definitions\n              \u2514\u2500\u2500\u2500\u2500\u2500\u252c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518    * Simple routing logic only, all processing deferred to orchestrator\n                    \u2502\n              \u250c\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510  - REST route definition framework\n              \u2502 openapi   [Oa]\u2502    * Standardizes Body, Path, Query, Filter semantics\n              \u2502 spec          |      - OpenAPI 3.0 (Swagger) generation\n              \u2514\u2500\u2500\u2500\u2500\u2500\u252c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518    * Including Swagger. UI\n                    \u2502\n              \u250c\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510  - WebSocket server\n              \u2502           [Ws]\u2502    * Developer friendly JSON based protocol business app development\n              \u2502 websockets    \u2502    * Reliable sequenced delivery\n              \u2514\u2500\u2500\u2500\u2500\u2500\u252c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518    * _Event interface [Ei] supports lower level integration with other compute frameworks/transports_\n                    \u2502\n              \u250c\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510  - Extension point interface to listen for database change events\n              \u2502 admin     [Ae]\u2502    * For building microservice extensions to the core that run externally\n              \u2502 events        |    * Used by the Transaction Manager component\n              \u2514\u2500\u2500\u2500\u2500\u2500\u252c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518    * Filtering to specific object types\n                    \u2502\n              \u250c\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510  - Core data types\n              \u2502 fftypes   [Ft]\u2502    * Used for API and Serialization\n              \u2502               \u2502    * APIs can mask fields on input via router definition\n              \u2514\u2500\u2500\u2500\u2500\u2500\u252c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n                    \u2502\n              \u250c\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510  - Core runtime server. Initializes and owns instances of:\n              \u2502           [Or]\u2502    * Components: Implement features\n  \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u252c\u2500\u2500\u2500\u2524 orchestrator  \u2502    * Plugins:    Pluggable infrastructure services\n  \u2502       \u2502   \u2502               \u2502  - Exposes actions to router\n  \u2502       \u2502   \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518    * Processing starts here for all API calls\n  \u2502       \u2502\n  \u2502  Components: Components do the heavy lifting within the engine\n  \u2502       \u2502\n  \u2502       \u2502   \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510  - Integrates with Blockchain Smart Contract logic across blockchain technologies\n  \u2502       \u251c\u2500\u2500\u2500\u2524 contract  [Cm]\u2502    * Generates OpenAPI 3 / Swagger definitions for smart contracts, and propagates to network\n  \u2502       \u2502   \u2502 manager       \u2502    * Manages listeners for native Blockchain events, and routes those to application events\n  \u2502       \u2502   \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518    * Convert to/from native Blockchain interfaces (ABI etc.) and FireFly Interface [FFI] format\n  \u2502       \u2502\n  \u2502       \u2502   \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510  - Maintains a view of the entire network\n  \u2502       \u251c\u2500\u2500\u2500\u2524 network   [Nm]\u2502    * Integrates with network permissioning [NP] plugin\n  \u2502       \u2502   \u2502 map           \u2502    * Integrates with broadcast plugin\n  \u2502       \u2502   \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518    * Handles hierarchy of member identity, node identity and signing identity\n  \u2502       \u2502\n  \u2502       \u2502   \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510  - Broadcast of data to all parties in the network\n  \u2502       \u251c\u2500\u2500\u2500\u2524 broadcast [Bm]\u2502    * Implements dispatcher for batch component\n  \u2502       \u2502   \u2502 manager       |    * Integrates with shared storage interface [Ss] plugin\n  \u2502       \u2502   \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518    * Integrates with blockchain interface [Bi] plugin\n  \u2502       \u2502\n  \u2502       \u2502   \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510  - Send private data to individual parties in the network\n  \u2502       \u251c\u2500\u2500\u2500\u2524 private   [Pm]\u2502    * Implements dispatcher for batch component\n  \u2502       \u2502   \u2502 messaging     |    * Integrates with the data exchange [Dx] plugin\n  \u2502       \u2502   \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u252c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518    * Messages can be pinned and sequenced via the blockchain, or just sent\n  \u2502       \u2502          \u2502\n  \u2502       \u2502   \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510  - Groups of parties, with isolated data and/or blockchains\n  \u2502       \u2502   \u2502 group     [Gm]\u2502    * Integrates with data exchange [Dx] plugin\n  \u2502       \u2502   \u2502 manager       \u2502    * Integrates with blockchain interface [Bi] plugin\n  \u2502       \u2502   \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n  \u2502       \u2502\n  \u2502       \u2502   \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510  - Private data management and validation\n  \u2502       \u251c\u2500\u2500\u2500\u2524 data      [Dm]\u2502    * Implements dispatcher for batch component\n  \u2502       \u2502   \u2502 manager       \u2502    * Integrates with data exchange [Dx] plugin\n  \u2502       \u2502   \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u252c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518    * Integrates with blockchain interface [Bi] plugin\n  \u2502       \u2502          \u2502\n  \u2502       \u2502   \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510  - JSON data schema management and validation (architecture extensible to XML and more)\n  \u2502       \u2502   \u2502 json      [Jv]\u2502    * JSON Schema validation logic for outbound and inbound messages\n  \u2502       \u2502   \u2502 validator     \u2502    * Schema propagation\n  \u2502       \u2502   \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u252c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518    * Integrates with broadcast plugin\n  \u2502       \u2502          \u2502\n  \u2502       \u2502   \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510  - Binary data addressable via ID or Hash\n  \u2502       \u2502   \u2502 blobstore [Bs]\u2502    * Integrates with data exchange [Dx] plugin\n  \u2502       \u2502   \u2502               \u2502    * Hashes data, and maintains mapping to payload references in blob storage\n  \u2502       \u2502   \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518    * Integrates with blockchain interface [Bi] plugin\n  \u2502       \u2502\n  \u2502       \u2502   \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510  - Download from shared storage\n  \u2502       \u251c\u2500\u2500\u2500\u2524 shared    [Sd]\u2502    * Parallel asynchronous download\n  \u2502       \u2502   \u2502 download      \u2502    * Resilient retry and crash recovery\n  \u2502       \u2502   \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518    * Notification to event aggregator on completion\n  \u2502       \u2502\n  \u2502       \u2502   \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510\n  \u2502       \u251c\u2500\u2500\u2500\u2524 identity [Im] \u2502  - Central identity management service across components\n  \u2502       \u2502   \u2502 manager       \u2502    * Resolves API input identity + key combos (short names, formatting etc.)\n  \u2502       \u2502   \u2502               \u2502    * Resolves registered on-chain signing keys back to identities\n  \u2502       \u2502   \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518    * Integrates with Blockchain Interface and pluggable Identity Interface (TBD)\n  \u2502       \u2502\n  \u2502       \u2502   \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510  - Keeps track of all operations performed against external components via plugins\n  \u2502       \u251c\u2500\u2500\u2500\u2524 operation [Om]\u2502    * Updates database with inputs/outputs\n  \u2502       \u2502   \u2502 manager       \u2502    * Provides consistent retry semantics across plugins\n  \u2502       \u2502   \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n  \u2502       \u2502\n  \u2502       \u2502   \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510  - Private data management and validation\n  \u2502       \u251c\u2500\u2500\u2500\u2524 event     [Em]\u2502    * Implements dispatcher for batch component\n  \u2502       \u2502   \u2502 manager       \u2502    * Integrates with data exchange [Dx] plugin\n  \u2502       \u2502   \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u252c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518    * Integrates with blockchain interface [Bi] plugin\n  \u2502       \u2502          \u2502\n  \u2502       \u2502   \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510  - Handles incoming external data\n  \u2502       \u2502   \u2502           [Ag]\u2502    * Integrates with data exchange [Dx] plugin\n  \u2502       \u2502   \u2502 aggregator    \u2502    * Integrates with shared storage interface [Ss] plugin\n  \u2502       \u2502   \u2502               \u2502    * Integrates with blockchain interface [Bi] plugin\n  \u2502       \u2502   \u2502               \u2502  - Ensures valid events are dispatched only once all data is available\n  \u2502       \u2502   \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u252c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518    * Context aware, to prevent block-the-world scenarios\n  \u2502       \u2502          \u2502\n  \u2502       \u2502   \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510  - Subscription manager\n  \u2502       \u2502   \u2502           [Sm]\u2502    * Creation and management of subscriptions\n  \u2502       \u2502   \u2502 subscription  \u2502    * Creation and management of subscriptions\n  \u2502       \u2502   \u2502 manager       \u2502    * Message to Event matching logic\n  \u2502       \u2502   \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u252c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n  \u2502       \u2502          \u2502\n  \u2502       \u2502   \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510  - Manages delivery of events to connected applications\n  \u2502       \u2502   \u2502 event     [Ed]\u2502    * Integrates with data exchange [Dx] plugin\n  \u2502       \u2502   \u2502 dispatcher    \u2502    * Integrates with blockchain interface [Bi] plugin\n  \u2502       \u2502   \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n  \u2502       \u2502\n  \u2502       \u2502   \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510  - Token creation/transfer initiation, indexing and coordination\n  \u2502       \u251c\u2500\u2500\u2500\u2524 asset     [Am]\u2502    * Fungible tokens: Digitized value/settlement (coins)\n  \u2502       \u2502   \u2502 manager       \u2502    * Non-fungible tokens: NFTs / globally uniqueness / digital twins\n  \u2502       \u2502   \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518    * Full indexing of transaction history\n  \u2502       \u2502   [REST/WebSockets]\n  \u2502       \u2502   \u250c\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510   \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510   \u250c\u2500\n  \u2502       \u2502   \u2502 ERC-20 / ERC-721  \u251c\u2500\u2500\u2500\u2524 ERC-1155 \u251c\u2500\u2500\u2500\u2524  Simple framework for building token connectors\n  \u2502       \u2502   \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518   \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518   \u2514\u2500\n  \u2502       \u2502\n  \u2502       \u2502   \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510\n  \u2502       \u251c\u2500\u2500\u2500\u2524 sync /   [Sa] \u2502  - Sync/Async Bridge\n  \u2502       \u2502   \u2502 async bridge  \u2502    * Provides synchronous request/reply APIs\n  \u2502       \u2502   \u2502               \u2502    * Translates to underlying event-driven API\n  \u2502       \u2502   \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n  \u2502       \u2502\n  \u2502       \u2502   \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510  - Aggregates messages and data, with rolled up hashes for pinning\n  \u2502       \u251c\u2500\u2500\u2500\u2524 batch     [Ba]\u2502    * Pluggable dispatchers\n  \u2502       \u2502   \u2502 manager       \u2502  - Database decoupled from main-line API processing\n  \u2502       \u2502   \u2502               \u2502    * See architecture diagrams for more info on active/active sequencing\n  \u2502       \u2502   \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u252c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518  - Manages creation of batch processor instances\n  \u2502       \u2502          \u2502\n  \u2502       \u2502   \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510  - Short lived agent spun up to assemble batches on demand\n  \u2502       \u2502   \u2502 batch     [Bp]\u2502    * Coupled to an author+type of messages\n  \u2502       \u2502   \u2502 processor     \u2502  - Builds batches of 100s messages for efficient pinning\n  \u2502       \u2502   \u2502               \u2502    * Aggregates messages and data, with rolled up hashes for pinning\n  \u2502       \u2502   \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518  - Shuts down automatically after a configurable inactivity period\n  \u2502       ... more TBD\n  \u2502\nPlugins: Each plugin comprises a Go shim, plus a remote agent microservice runtime (if required)\n  \u2502\n  \u2502           \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510  - Blockchain Interface\n  \u251c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2524           [Bi]\u2502    * Transaction submission - including signing key management\n  \u2502           \u2502 blockchain    \u2502    * Event listening\n  \u2502           \u2502 interface     \u2502    * Standardized operations, and custom on-chain coupling\n  \u2502           \u2514\u2500\u2500\u2500\u2500\u2500\u252c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n  \u2502                 \u2502\n  \u2502                 \u251c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u252c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510\n  \u2502           \u250c\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510   \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510   \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510\n  \u2502           \u2502 ethereum      \u2502   \u2502 fabric        \u2502   \u2502 corda/cordapps \u2502\n  \u2502           \u2514\u2500\u2500\u2500\u2500\u2500\u252c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518   \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518   \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n  \u2502           [REST/WebSockets]\n  \u2502           \u250c\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510   \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510   \u250c\u2500\n  \u2502           \u2502 transaction manager [Tm] \u251c\u2500\u2500\u2500\u2524 Connector API [ffcapi] \u251c\u2500\u2500\u2500\u2524  Simple framework for building blockchain connectors\n  \u2502           \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518   \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518   \u2514\u2500\n  \u2502\n  \u2502           \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510  - Token interface\n  \u251c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2524 tokens    [Ti]\u2502    * Standardizes core concepts: token pools, transfers, approvals\n  \u2502           \u2502 interface     \u2502    * Pluggable across token standards\n  \u2502           \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518    * Supports simple implementation of custom token standards via microservice connector\n  \u2502           [REST/WebSockets]\n  \u2502           \u250c\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510   \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510   \u250c\u2500\n  \u2502           \u2502 ERC-20 / ERC-721  \u251c\u2500\u2500\u2500\u2524 ERC-1155 \u251c\u2500\u2500\u2500\u2524  Simple framework for building token connectors\n  \u2502           \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518   \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518   \u2514\u2500\n  \u2502\n  \u2502           \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510  - P2P Content Addresssed Filesystem\n  \u251c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2524 shared    [Si]\u2502    * Payload upload / download\n  \u2502           \u2502 storage       \u2502    * Payload reference management\n  \u2502           \u2502 interface     \u2502\n  \u2502           \u2514\u2500\u2500\u2500\u2500\u2500\u252c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n  \u2502                 \u2502\n  \u2502                 \u251c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500 ... extensible to any shared storage sytem, accessible to all members\n  \u2502           \u250c\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510\n  \u2502           \u2502 ipfs          \u2502\n  \u2502           \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n  \u2502\n  \u2502           \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510  - Private Data Exchange\n  \u251c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2524 data      [Dx]\u2502    * Blob storage\n  \u2502           \u2502 exchange      \u2502    * Private secure messaging\n  \u2502           \u2514\u2500\u2500\u2500\u2500\u2500\u252c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518    * Secure file transfer\n  \u2502                 \u2502\n  \u2502                 \u251c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u252c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500 ... extensible to any private data exchange tech\n  \u2502           \u250c\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510   \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510\n  \u2502           \u2502 https / MTLS  \u2502   \u2502 Kaleido       \u2502\n  \u2502           \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518   \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n  \u2502\n  \u2502           \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510  - API Authentication and Authorization Interface\n  \u251c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2524 api auth  [Aa]\u2502    * Authenticates security credentials (OpenID Connect id token JWTs etc.)\n  \u2502           \u2502               \u2502    * Extracts API/user identity (for identity interface to map)\n  \u2502           \u2514\u2500\u2500\u2500\u2500\u2500\u252c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518    * Enforcement point for fine grained API access control\n  \u2502                 \u2502\n  \u2502                 \u251c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u252c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500 ... extensible other single sign-on technologies\n  \u2502           \u250c\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510   \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510\n  \u2502           \u2502 apikey        \u2502   \u2502 jwt           \u2502\n  \u2502           \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518   \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n  \u2502\n  \u2502           \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510  - Database Interactions\n  \u251c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2524 database  [Di]\u2502    * Create, Read, Update, Delete (CRUD) actions\n  \u2502           \u2502 interace      \u2502    * Filtering and update definition interace\n  \u2502           \u2514\u2500\u2500\u2500\u2500\u2500\u252c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518    * Migrations and Indexes\n  \u2502                 \u2502\n  \u2502                 \u251c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500 ... extensible to NoSQL (CouchDB / MongoDB etc.)\n  \u2502           \u250c\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510\n  \u2502           \u2502 sqlcommon     \u2502\n  \u2502           \u2514\u2500\u2500\u2500\u2500\u2500\u252c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n  \u2502                 \u251c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u252c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500 ... extensible other SQL databases\n  \u2502           \u250c\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510     \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510\n  \u2502           \u2502 postgres      \u2502     \u2502 sqlite3        \u2502\n  \u2502           \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518     \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n  \u2502\n  \u2502           \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510  - Connects the core event engine to external frameworks and applications\n  \u251c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2524 event     [Ei]\u2502    * Supports long-lived (durable) and ephemeral event subscriptions\n  \u2502           \u2502 interface     \u2502    * Batching, filtering, all handled in core prior to transport\n  \u2502           \u2514\u2500\u2500\u2500\u2500\u2500\u252c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518    * Interface supports connect-in (websocket) and connect-out (broker runtime style) plugins\n  \u2502                 \u2502\n  \u2502                 \u251c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u252c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500   ... extensible to additional event buses (Kafka, NATS, AMQP etc.)\n  \u2502           \u250c\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510     \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510\n  \u2502           \u2502 websockets    \u2502     \u2502 webhooks       \u2502\n  \u2502           \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518     \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n  \u2502  ... more TBD\n\n  Additional utility framworks\n              \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510  - REST API client\n              \u2502 rest      [Re]\u2502    * Provides convenience and logging\n              \u2502 client        \u2502    * Standardizes auth, config and retry logic\n              \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518    * Built on Resty\n\n              \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510  - WebSocket client\n              \u2502 wsclient  [Wc]\u2502    * Provides convenience and logging\n              \u2502               \u2502    * Standardizes auth, config and reconnect logic\n              \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518    * Built on Gorilla WebSockets\n\n              \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510  - Translation framework\n              \u2502 i18n      [In]\u2502    * Every translations must be added to `en_translations.json` - with an `FF10101` key\n              \u2502               \u2502    * Errors are wrapped, providing extra features from the `errors` package (stack etc.)\n              \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518    * Description translations also supported, such as OpenAPI description\n\n              \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510  - Logging framework\n              \u2502 log       [Lo]\u2502    * Logging framework (logrus) integrated with context based tagging\n              \u2502               \u2502    * Context is used throughout the code to pass API invocation context, and logging context\n              \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518    * Example: Every API call has an ID that can be traced, as well as a timeout\n\n              \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510  - Configuration\n              \u2502 config    [Co]\u2502    * File and Environment Variable based logging framework (viper)\n              \u2502               \u2502    * Primary config keys all defined centrally\n              \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518    * Plugins integrate by returning their config structure for unmarshaling (JSON tags)\n</code></pre>"},{"location":"contributors/code_overview/","title":"FireFly Code Overview","text":""},{"location":"contributors/code_overview/#developer-intro","title":"Developer Intro","text":"<p>FireFly is a second generation implementation re-engineered from the ground up to improve developer experience, runtime performance, and extensibility.</p> <p>This means a simplified REST/WebSocket programming model for app development, and a wider range of infrastructure options for deployment.</p> <p>It also means a focus on an architecture and code structure for a vibrant open source community.</p> <p>A few highlights:</p> <ul> <li>Golang codebase</li> <li>Strong coding standards, including unit test coverage, translation support, logging and more</li> <li>Fast starting, low memory footprint, multi-threaded runtime</li> <li>OpenAPI 3.0 API specification (Swagger)</li> <li>Generated from the API router code, to avoid divergence with the implementation</li> <li>Active/active HA architecture for the core runtime</li> <li>Deferring to the core database for state high availability</li> <li>Exploiting leader election where required</li> <li>Fully pluggable architecture</li> <li>Everything from Database through to Blockchain, and Compute</li> <li>Golang plugin infrastructure to decouple the core code from the implementation</li> <li>Remote Agent model to decouple code languages, and HA designs</li> <li>Updated API resource model</li> <li><code>Asset</code>, <code>Data</code>, <code>Message</code>, <code>Event</code>, <code>Topic</code>, <code>Transaction</code></li> <li> <p>Added flexibility, with simplified the developer experience:</p> </li> <li> <p>Versioning of data definitions</p> </li> <li>Introducing a first class <code>Context</code> construct link related events into a single sequence</li> <li>Allow many pieces of data to be attached to a single message, and be automatically re-assembled on arrival</li> <li>Clearer separation of concerns between the FireFly DB and the Application DB</li> <li>Better search, filter and query support</li> </ul> <p>## Directories</p> <ul> <li>internal: The core Golang implementation code</li> <li>pkg: Interfaces intended for external project use</li> <li>cmd: The command line entry point</li> <li>smart_contracts: smart contract code for FireFly's onchain logic</li> </ul>"},{"location":"contributors/code_repositories/","title":"Code Repositories","text":"<p>FireFly has a plugin based architecture design, with a microservice runtime footprint. As such there are a number of repos, and the list will grow as the community evolves.</p> <p>But not to worry, one of those repos is a CLI designed to get you running with all the components you need in minutes!</p> <ul> <li>CLI / Developer experience</li> <li>FireFly Samples</li> <li>UI Explorer</li> <li>Core</li> <li>HTTP Data Exchange</li> <li>Ethereum (Hyperledger Besu / Quorum) connector</li> <li>Corda connector</li> <li>Hyperledger Fabric connector</li> <li>Token connector reference implementation (ERC1155)</li> </ul> <p>Note only the projects that are primarily built to support FireFly are listed here, not all of the ecosystem of projects that integrate underneath the plugins.</p>"},{"location":"contributors/dev_environment_setup/","title":"Setting up a FireFly Core Development Environment","text":"<p>This guide will walk you through setting up your machine for contributing to FireFly, specifically the FireFly core.</p>"},{"location":"contributors/dev_environment_setup/#dependencies","title":"Dependencies","text":"<p>You will need a few prerequisites set up on your machine before you can build FireFly from source. We recommend doing development on macOS, Linux, or WSL 2.0.</p> <ul> <li>Go 1.22</li> <li>make</li> <li>GCC</li> <li>openssl</li> </ul>"},{"location":"contributors/dev_environment_setup/#install-the-firefly-cli","title":"Install the FireFly CLI","text":"<p>The first step to setting up a local development environment is to install the FireFly CLI. Please section of the Getting Started Guide to install The FireFly CLI.</p>"},{"location":"contributors/dev_environment_setup/#installing-go-and-setting-up-your-gopath","title":"Installing Go and setting up your <code>GOPATH</code>","text":"<p>We recommend following the instructions on golang.org to install Go, rather than installing Go from another package magager such as <code>brew</code>. Although it is possible to install Go any way you'd like, setting up your <code>GOPATH</code> may differ from the following instructions.</p> <p>After installing Go, you will need to add a few environment variables to your shell run commands file. This is usually a hidden file in your home directory called <code>.bashrc</code> or <code>.zshrc</code>, depending on which shell you're using.</p> <p>Add the following lines to your <code>.bashrc</code> or <code>.zshrc</code> file:</p> <pre><code>export GOPATH=$HOME/go\nexport GOROOT=\"/usr/local/go\"\nexport PATH=\"$PATH:${GOPATH}/bin:${GOROOT}/bin\"\n</code></pre>"},{"location":"contributors/dev_environment_setup/#building-firefly","title":"Building FireFly","text":"<p>After installing dependencies, building FireFly from source is very easy. Just clone the repo:</p> <pre><code>git clone git@github.com:hyperledger/firefly.git &amp;&amp; cd firefly\n</code></pre> <p>And run the <code>Makefile</code> to run tests, and compile the app</p> <pre><code>make\n</code></pre> <p>If you want to install the binary on your path (assuming your Go Home is already on your path), from inside the project directory you can simply run:</p> <pre><code>go install\n</code></pre>"},{"location":"contributors/dev_environment_setup/#install-the-cli","title":"Install the CLI","text":"<p>Please check the CLI Installation instructions for the best way to install the CLI on your machine: https://github.com/hyperledger/firefly-cli#install-the-cli</p>"},{"location":"contributors/dev_environment_setup/#set-up-a-development-stack","title":"Set up a development stack","text":"<p>Now that you have both FireFly and the FireFly CLI installed, it's time to create a development stack. The CLI can be used to create a docker-compose environment that runs the entirety of a FireFly network. This will include several different processes for each member of the network. This is very useful for people that want to build apps that use FireFly's API. It can also be useful if you want to make changes to FireFly itself, however we need to set up the stack slightly differently in that case.</p> <p>Essentially what we are going to do is have docker-compose run everything in the FireFly network except one FireFly core process. We'll run this FireFly core process on our host machine, and configure it to connect to the rest of the microservices running in docker-compose. This means we could launch FireFly from Visual Studio Code or some other IDE and use a debugger to see what's going on inside FireFly as it's running.</p> <p>We'll call this stack <code>dev</code>. We're also going to add <code>--external 1</code> to the end of our command to create the new stack:</p> <pre><code>ff init dev --external 1\n</code></pre> <p>This tells the CLI that we want to manage one of the FireFly core processes outside the docker-compose stack. For convenience, the CLI will still generate a config file for this process though.</p>"},{"location":"contributors/dev_environment_setup/#start-the-stack","title":"Start the stack","text":"<p>To start your new stack simply run:</p> <pre><code>ff start dev\n</code></pre> <p>At a certain point in the startup process, the CLI will pause and wait for up to two minutes for you to start the other FireFly node. There are two different ways you can run the external FireFly core process.</p>"},{"location":"contributors/dev_environment_setup/#1-from-another-terminal","title":"1) From another terminal","text":"<p>The CLI will print out the command line which can be copied and pasted into another terminal window to run FireFly. This command should be run from the <code>firefly</code> core project directory. Here is an example of the command that the CLI will tell you to run:</p> <pre><code>firefly -f ~/.firefly/stacks/dev/runtime/config/firefly_core_0.yml\n</code></pre> <p>NOTE: The first time you run FireFly with a fresh database, it will need a directory of database migrations to apply to the empty database. If you run FireFly from the <code>firefly</code> project directory you cloned from GitHub, it will automatically find these and apply them. If you run it from some other directory, you will have to point FireFly to the migrations on your own.</p>"},{"location":"contributors/dev_environment_setup/#2-using-an-ide","title":"2) Using an IDE","text":"<p>If you named your stack <code>dev</code> there is a <code>launch.json</code> file for Visual Studio code already in the project directory. If you have the project open in Visual Studio Code, you can either press the F5 key to run it, or go to the \"Run and Debug\" view in Visual Studio code, and click \"Run FireFly Core\".</p> <p></p> <p>Now you should have a full FireFly stack up and running, and be able to debug FireFly using your IDE. Happy hacking!</p> <p>NOTE: Because <code>firefly-ui</code> is a separate repo, unless you also start a UI dev server for the external FireFly core, the default UI path will not load. This is expected, and if you're just working on FireFly core itself, you don't need to worry about it.`</p>"},{"location":"contributors/dev_environment_setup/#set-up-dev-environment-for-other-components","title":"Set up dev environment for other components","text":"<p>Refer to Advanced CLI Usage.</p>"},{"location":"contributors/docs_setup/","title":"Contributing to Documentation","text":"<p>This guide will walk you through setting up your machine for contributing to FireFly documentation. Documentation contributions are extremely valuable. If you discover something is missing in the docs, we would love to include your additions or clarifications to help the next person who has the same question.</p> <p>This doc site is generated by a set of Markdown files in the main FireFly repository, under the <code>./doc-site</code> directory. You can browse the source for the current live site in GitHub here: https://github.com/hyperledger/firefly/tree/main/doc-site</p>"},{"location":"contributors/docs_setup/#process-for-updating-documentation","title":"Process for updating documentation","text":"<p>The process for updating the documentation is really easy! You'll follow the same basic steps outlined in the same steps outlined in the Contributor's guide. Here are the detailed steps for contributing to the docs:</p> <ol> <li>Fork https://github.com/hyperledger/firefly</li> <li>Clone your fork locally to your computer</li> <li>Follow the steps below to view your local copy of the docs in a browser</li> <li>Make some improvements to the Markdown files</li> <li>Verify that your changes look they way you want them to in your browser</li> <li>Create a new git commit with your changes. Be sure to sign-off on your commit by using <code>git commit -s</code>!</li> <li>Push your changes</li> <li>Open a Pull Request to incorporate your changes back into the hyperledger/firefly repo</li> </ol> <p>This FireFly documentation site is based on the Hyperledger documentation template. The template utilizes MkDocs (documentation at mkdocs.org) and the theme Material for MkDocs (documentation at Material for MkDocs). Material adds a number of extra features to MkDocs, and Hyperledger repositories can take advantage of the theme's Insiders capabilities.</p>"},{"location":"contributors/docs_setup/#prerequisites","title":"Prerequisites","text":"<p>To test the documents and update the published site, the following tools are needed:</p> <ul> <li>A Bash shell</li> <li>git</li> <li>Python 3</li> <li>The Material for Mkdocs theme.</li> <li>The Mike MkDocs plugin for publishing versions to gh-pages.</li> <li>Not used locally, but referenced in the <code>mkdocs.yml</code> file and needed for     deploying the site to gh-pages.</li> </ul>"},{"location":"contributors/docs_setup/#git","title":"git","text":"<p><code>git</code> can be installed locally, as described in the Install Git Guide from GitHub.</p>"},{"location":"contributors/docs_setup/#python-3","title":"Python 3","text":"<p><code>Python 3</code> can be installed locally, as described in the Python Getting Started guide.</p>"},{"location":"contributors/docs_setup/#virtual-environment","title":"Virtual environment","text":"<p>It is recommended to install your Python dependencies in a virtual environment in case you have other conflicting Python installations on your machine. This also removes the need to install these packages globally on your computer.</p> <pre><code>cd doc-site\npython3 -m venv venv\nsource venv/bin/activate\n</code></pre>"},{"location":"contributors/docs_setup/#mkdocs","title":"Mkdocs","text":"<p>The Mkdocs-related items can be installed locally, as described in the Material for Mkdocs installation instructions. The short, case-specific version of those instructions follow:</p> <pre><code>pip install -r requirements.txt\n</code></pre>"},{"location":"contributors/docs_setup/#verify-setup","title":"Verify Setup","text":"<p>To verify your setup, check that you can run <code>mkdocs</code> by running the command <code>mkdocs --help</code> to see the help text.</p>"},{"location":"contributors/docs_setup/#useful-mkdocs-commands","title":"Useful MkDocs Commands","text":"<p>The commands you will usually use with <code>mkdocs</code> are:</p> <ul> <li><code>mkdocs serve</code> - Start the live-reloading docs server.</li> <li><code>mkdocs build</code> - Build the documentation site.</li> <li><code>mkdocs -h</code> - Print help message and exit.</li> </ul>"},{"location":"contributors/docs_setup/#directory-layout","title":"Directory layout","text":"<pre><code>mkdocs.yml     # The configuration file.\ndocs/\n    index.md   # The documentation homepage.\n    SUMMARY.md # The main left nav\n    ...        # Other markdown pages, images and other files.\n</code></pre>"},{"location":"contributors/release_guide/","title":"Release Guide","text":"<p>This guide will walk you through creating a release.</p>"},{"location":"contributors/release_guide/#versioning-scheme","title":"Versioning scheme","text":"<p>FireFly follows semantic versioning. For more details on how we determine which version to use please see the Versioning Scheme guide.</p>"},{"location":"contributors/release_guide/#the-manifestjson-file","title":"The <code>manifest.json</code> file","text":"<p>FireFly has a <code>manifest.json</code> file in the root of the repo. This file contains a list of versions (both tag and sha) for each of the microservices that should be used with this specific commit. If you need FireFly to use a newer version of a microservice listed in this file, you should update the <code>manifest.json</code> file, commit it, and include it in your PR. This will trigger an end-to-end test run, using the specified versions.</p> <p>Here is an example of what the <code>manifest.json</code> looks like:</p> <pre><code>{\n  \"ethconnect\": {\n    \"image\": \"ghcr.io/hyperledger/firefly-ethconnect\",\n    \"tag\": \"v3.0.4\",\n    \"sha\": \"0b7ce0fb175b5910f401ff576ced809fe6f0b83894277c1cc86a73a2d61c6f41\"\n  },\n  \"fabconnect\": {\n    \"image\": \"ghcr.io/hyperledger/firefly-fabconnect\",\n    \"tag\": \"v0.9.0\",\n    \"sha\": \"a79a4c66b0a2551d5122d019c15c6426e8cdadd6566ce3cbcb36e008fb7861ca\"\n  },\n  \"dataexchange-https\": {\n    \"image\": \"ghcr.io/hyperledger/firefly-dataexchange-https\",\n    \"tag\": \"v0.9.0\",\n    \"sha\": \"0de5b1db891a02871505ba5e0507821416d9fa93c96ccb4b1ba2fac45eb37214\"\n  },\n  \"tokens-erc1155\": {\n    \"image\": \"ghcr.io/hyperledger/firefly-tokens-erc1155\",\n    \"tag\": \"v0.9.0-20211019-01\",\n    \"sha\": \"aabc6c483db408896838329dab5f4b9e3c16d1e9fa9fffdb7e1ff05b7b2bbdd4\"\n  }\n}\n</code></pre> <p>NOTE: You can run <code>make manifest</code> in the FireFly core source directory, and a script will run to automatically get the latests non-pre-release version of each of FireFly's microservices. If you need to use a snapshot or pre-release version you should edit <code>manifest.json</code> file manually, as this script will not fetch those versions.</p>"},{"location":"contributors/release_guide/#creating-a-new-release","title":"Creating a new release","text":"<p>Releases and builds are managed by GitHub. New binaries and/or Docker images will automatically be created when a new release is published. The easiest way to create a release is through the web UI for the repo that you wish to release.</p>"},{"location":"contributors/release_guide/#1-navigate-to-the-release-page-for-the-repo","title":"1) Navigate to the release page for the repo","text":""},{"location":"contributors/release_guide/#2-click-the-draft-a-new-release-button","title":"2) Click the <code>Draft a new release</code> button","text":""},{"location":"contributors/release_guide/#3-fill-out-the-form-for-your-release","title":"3) Fill out the form for your release","text":"<p>It is recommended to start with the auto-generated release notes. Additional notes can be added as-needed.</p>"},{"location":"contributors/release_guide/#automatic-docker-builds","title":"Automatic Docker builds","text":"<p>After cutting a new release, a GitHub Action will automatically start a new Docker build, if the repo has a Docker image associated with it. You can check the status of the build by clicking the \"Actions\" tab along the top of the page, for that repo.</p> <p></p>"},{"location":"contributors/version_scheme/","title":"Versioning Scheme","text":"<p>This page describes FireFly's versioning scheme</p>"},{"location":"contributors/version_scheme/#semantic-versioning","title":"Semantic versioning","text":"<p>FireFly follows semantic versioning. In summary, this means:</p> <p>Given a version number MAJOR.MINOR.PATCH, increment the:</p> <ul> <li>MAJOR version when you make incompatible API changes,</li> <li>MINOR version when you add functionality in a backwards compatible manner, and</li> <li>PATCH version when you make backwards compatible bug fixes.</li> <li>Additional labels for pre-release and build metadata are available as extensions to the MAJOR.MINOR.PATCH format.</li> </ul> <p>When creating a new release, the release name and tag should be the semantic version should be prefixed with a <code>v</code> . For example, a certain release name/tag could be <code>v0.9.0</code>.</p>"},{"location":"contributors/version_scheme/#pre-release-test-versions","title":"Pre-release test versions","text":"<p>For pre-release versions for testing, we append a date and index to the end of the most recently released version. For example, if we needed to create a pre-release based on <code>v0.9.0</code> and today's date is October 22, 2021, the version name/tag would be: <code>v0.9.0-20211022-01</code>. If for some reason you needed to create another pre-release version in the same day (hey, stuff happens), the name/tag for that one would be <code>v0.9.0-20211022-02</code>.</p>"},{"location":"contributors/version_scheme/#candidate-releases","title":"Candidate releases","text":"<p>For pre-releases that are candidates to become a new major or minor release, the release name/tag will be based on the release that the candidate will become (as opposed to the test releases above, which are based on the previous release). For example, if the current latest release is <code>v0.9.0</code> but we want to create an alpha release for 1.0, the release name/tag would be <code>v1.0.0-alpha.1</code>.</p>"},{"location":"faqs/","title":"FAQs","text":"<p>Find answers to the most commonly asked FireFly questions.</p>"},{"location":"faqs/#how-does-firefly-enable-multi-chain-applications","title":"How does FireFly enable multi-chain applications?","text":"<p>It's best to think about FireFly as a rich orchestration layer that sits one layer above the blockchain. FireFly helps to abstract away much of the complex blockchain functionality (such as data exchange, private messaging, common token functionality, etc) in a loosely coupled microservice architecture with highly pluggable components. This enables application developers to focus on building innovative Web3 applications.</p> <p>There aren't any out of the box bridges to connect two separate chains together, but with a collection of FireFly instances across a consortium, FireFly could help listen for events on Blockchain A and take an action on Blockchain B when certain conditions are met.</p>"},{"location":"faqs/#how-do-i-deploy-smart-contracts","title":"\ud83d\udcdc How do I deploy smart contracts?","text":"<p>The recommended way to deploy smart contracts on Ethereum chains is by using FireFly's built in API. For a step by step example of how to do this you can refer to the Smart Contract Tutorial for Ethereum based chains.</p> <p>For Fabric networks, please refer to the Fabric chaincode lifecycle docs for detailed instructions on how to deploy and manage Fabric chaincode.</p>"},{"location":"faqs/#can-i-connect-firefly-to-metamask","title":"\ud83e\udd8a Can I connect FireFly to MetaMask?","text":"<p>Yes! Before you set up MetaMask you'll likely want to create some tokens that you can use to send between wallets on your FF network. Go to the tokens tab in your FireFly node's UI, create a token pool, and then mint some tokens. Once you've done this, follow the steps listed here to set up MetaMask on your network.</p>"},{"location":"faqs/#connect-with-us-on-discord","title":"\ud83d\ude80 Connect with us on Discord","text":"<p>If your question isn't answered here or if you have immediate questions please don't hesitate to reach out to us on Discord in the <code>firefly</code> channel:</p>"},{"location":"gettingstarted/","title":"Getting Started","text":"<p>If you're new to FireFly, this is the perfect place to start! With the FireFly CLI and the FireFly Sandbox it's really easy to get started building powerful blockchain apps. Just follow along with the steps below and you'll be up and running in no time!</p> <p> </p>"},{"location":"gettingstarted/#what-you-will-accomplish-with-this-guide","title":"What you will accomplish with this guide","text":"<p>With this easy-to-follow guide, you'll go from \"zero\" to blockchain-hero in the time it takes to drink a single cup of coffee. It will walk you through setting up your machine, all the way through sending your first blockchain transactions using the FireFly Sandbox.</p> <p></p>"},{"location":"gettingstarted/#were-here-to-help","title":"We're here to help!","text":"<p>We want to make it as easy as possible for anyone to get started with FireFly, and we don't want anyone to feel like they're stuck. If you're having trouble, or are just curious about what else you can do with FireFly we encourage you to join the Hyperledger Discord server and come chat with us in the #firefly channel.</p>"},{"location":"gettingstarted/#get-started-install-the-firefly-cli","title":"Get started: Install the FireFly CLI","text":"<p>Now that you've got the FireFly CLI set up on your machine, the next step is to create and start a FireFly stack.</p> <p>\u2460 Install the FireFly CLI \u2192</p>"},{"location":"gettingstarted/firefly_cli/","title":"Install the FireFly CLI","text":""},{"location":"gettingstarted/firefly_cli/#prerequisites","title":"Prerequisites","text":"<p>In order to run the FireFly CLI, you will need a few things installed on your dev machine:</p> <ul> <li>Docker</li> <li>Docker Compose</li> <li>openssl</li> </ul>"},{"location":"gettingstarted/firefly_cli/#linux-users","title":"Linux Users","text":"<p>NOTE: For Linux users, it is recommended that you add your user to the <code>docker</code> group so that you do not have to run <code>ff</code> or <code>docker</code> as <code>root</code> or with <code>sudo</code>. For more information about Docker permissions on Linux, please see Docker's documentation on the topic.</p>"},{"location":"gettingstarted/firefly_cli/#windows-users","title":"Windows Users","text":"<p>NOTE: For Windows users, we recommend that you use Windows Subsystem for Linux 2 (WSL2). Binaries provided for Linux will work in this environment.</p>"},{"location":"gettingstarted/firefly_cli/#install-the-cli","title":"Install the CLI","text":"<p>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.</p>"},{"location":"gettingstarted/firefly_cli/#install-via-binary-package-download","title":"Install via Binary Package Download","text":"<p>Download the package for your OS by navigating to the latest release page and downloading the appropriate package for your OS and architecture.</p>"},{"location":"gettingstarted/firefly_cli/#unpack-and-install-the-binary","title":"Unpack and Install the Binary","text":"<p>Assuming you downloaded the package from GitHub into your <code>Downloads</code> directory, run the following command to extract the binary and move it to your system path:</p> <pre><code>sudo tar -zxf ~/Downloads/firefly-cli_*.tar.gz -C /usr/local/bin ff &amp;&amp; rm ~/Downloads/firefly-cli_*.tar.gz\n</code></pre> <p>If you downloaded the package into a different directory, adjust the command to point to the correct location of the <code>firefly-cli_*.tar.gz</code> file.</p>"},{"location":"gettingstarted/firefly_cli/#macosusers","title":"macOSUsers","text":"<p>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, before it will run.</p>"},{"location":"gettingstarted/firefly_cli/#install-via-homebrew-macos","title":"Install via Homebrew (macOS)","text":"<p>You can also install the FireFly CLI using Homebrew:</p> <pre><code>brew install firefly\n</code></pre>"},{"location":"gettingstarted/firefly_cli/#alternative-installation-method-install-via-go","title":"Alternative installation method: Install via Go","text":"<p>If you have a local Go development environment, and you have included <code>${GOPATH}/bin</code> in your path, you could also use Go to install the FireFly CLI by running:</p> <pre><code>go install github.com/hyperledger/firefly-cli/ff@latest\n</code></pre>"},{"location":"gettingstarted/firefly_cli/#verify-the-installation","title":"Verify the installation","text":"<p>After using either installation method above, you can verify that the CLI is successfully installed by running <code>ff version</code>. This should print the current version like this:</p> <pre><code>{\n  \"Version\": \"v0.0.47\",\n  \"License\": \"Apache-2.0\"\n}\n</code></pre>"},{"location":"gettingstarted/firefly_cli/#next-steps-start-your-environment","title":"Next steps: Start your environment","text":"<p>Now that you've got the FireFly CLI set up on your machine, the next step is to create and start a FireFly stack.</p> <p>\u2461 Start your environment \u2192</p>"},{"location":"gettingstarted/sandbox/","title":"Use the Sandbox","text":""},{"location":"gettingstarted/sandbox/#previous-steps-start-your-environment","title":"Previous steps: Start your environment","text":"<p>If you haven't started a FireFly stack already, please go back to the previous step and read the guide on how to Start your environment.</p> <p>\u2190 \u2461 Start your environment</p> <p>Now that you have a full network of three Supernodes running on your machine, let's look at the first two components that you will interact with: the FireFly Sandbox and the FireFly Explorer.</p>"},{"location":"gettingstarted/sandbox/#video-walkthrough","title":"Video walkthrough","text":"<p>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.</p>"},{"location":"gettingstarted/sandbox/#open-the-firefly-sandbox-for-the-first-member","title":"Open the FireFly Sandbox for the first member","text":"<p>When you set up your FireFly stack in the previous section, it should have printed some URLs like the following. Open the link in a browser for the `Sandbox UI for member '0'. It should be: http://127.0.0.1:5109</p> <pre><code>ff start dev\nthis will take a few seconds longer since this is the first time you're running this stack...\ndone\n\nWeb UI for member '0': http://127.0.0.1:5000/ui\nSandbox UI for member '0': http://127.0.0.1:5109\n\nWeb UI for member '1': http://127.0.0.1:5001/ui\nSandbox UI for member '1': http://127.0.0.1:5209\n\nWeb UI for member '2': http://127.0.0.1:5002/ui\nSandbox UI for member '2': http://127.0.0.1:5309\n\n\nTo see logs for your stack run:\n\nff logs dev\n</code></pre>"},{"location":"gettingstarted/sandbox/#sandbox-layout","title":"Sandbox Layout","text":"<p>The Sandbox is split up into three columns:</p>"},{"location":"gettingstarted/sandbox/#left-column-prepare-your-request","title":"Left column: Prepare your request","text":"<p>On the left-hand side of the page, you can fill out simple form fields to construct messages and more. Some tabs have more types of requests on them in sections that can be expanded or collapsed. Across the top of this column there are three tabs that switch between the three main sets of functionality in the Sandbox. The next three sections of this guide will walk you through each one of these.</p> <p>The first tab we will explore is the MESSAGING tab. This is where we can send broadcasts and private messages.</p>"},{"location":"gettingstarted/sandbox/#middle-column-preview-server-code-and-see-response","title":"Middle column: Preview server code and see response","text":"<p>As you type in the form on the left side of the page, you may notice that the source code in the top middle of the page updates automatically. If you were building a backend app, this is an example of code that your app could use to call the FireFly SDK. The middle column also contains a <code>RUN</code> button to actually send the request.</p>"},{"location":"gettingstarted/sandbox/#right-column-events-received-on-the-websocket","title":"Right column: Events received on the WebSocket","text":"<p>On the right-hand side of the page you can see a stream of events being received on a WebSocket connection that the backend has open to FireFly. For example, as you make requests to send messages, you can see when the messages are asynchronously confirmed.</p>"},{"location":"gettingstarted/sandbox/#messages","title":"Messages","text":"<p>The Messages tab is where we can send broadcast and private messages to other members and nodes in the FireFly network. Messages can be a string, any arbitrary JSON object, or a binary file. For more details, please see the tutorial on Broadcasting data and Privately sending data.</p>"},{"location":"gettingstarted/sandbox/#things-to-try-out","title":"Things to try out","text":"<ul> <li>Send a broadcast message and view the data payload in every member's FireFly Explorer</li> <li>Send a private message to one member, and verify that the data payload is not visible in the third member's FireFly Explorer</li> <li>Send an image file and download it from another member's FireFly Explorer</li> </ul>"},{"location":"gettingstarted/sandbox/#tokens","title":"Tokens","text":"<p>The Tokens tab is where you can create token pools, and mint, burn, or transfer tokens. This works with both fungible and non-fungible tokens (NFTs). For more details, please see the Tokens tutorials.</p>"},{"location":"gettingstarted/sandbox/#things-to-try-out_1","title":"Things to try out","text":"<ul> <li>Create a fungible token pool and mint some tokens and view your balance in the FireFly Explorer</li> <li>Transfer some amount of those tokens to another member and view the transfer transaction in the FireFly Explorer</li> <li>Burn some amount of tokens and view the transaction and updated balances in the FireFly Explorer</li> <li>Create a non-fungible token pool and mint some NFTs</li> <li>Transfer an NFT to another member and verify the account balances in the FireFly Explorer</li> </ul>"},{"location":"gettingstarted/sandbox/#contracts","title":"Contracts","text":"<p>The Contracts section of the Sandbox lets you interact with custom smart contracts, right from your web browser! The Sandbox also provides some helpful tips on deploying your smart contract to the blockchain. For more details, please see the tutorial on Working with custom smart contracts.</p> <p></p> <p></p>"},{"location":"gettingstarted/sandbox/#things-to-try-out_2","title":"Things to try out","text":"<ul> <li>Create a contract interface and API, then view the Swagger UI for your new API</li> <li>Create an event listener</li> <li>Use the Swagger UI to call a smart contract function that emits an event. Verify that the event is received in the Sandbox and shows up in the FireFly Explorer.</li> </ul>"},{"location":"gettingstarted/sandbox/#go-forth-and-build","title":"Go forth and build!","text":"<p>At this point you should have a pretty good understanding of some of the major features of Hyperledger FireFly. Now, using what you've learned, you can go and build your own Web3 app! Don't forget to join the Hyperledger Discord server and come chat with us in the #firefly channel.</p>"},{"location":"gettingstarted/setup_env/","title":"Start your environment","text":""},{"location":"gettingstarted/setup_env/#previous-steps-install-the-firefly-cli","title":"Previous steps: Install the FireFly CLI","text":"<p>If you haven't set up the FireFly CLI already, please go back to the previous step and read the guide on how to Install the FireFly CLI.</p> <p>\u2190 \u2460 Install the FireFly CLI</p> <p>Now that you have the FireFly CLI installed, you are ready to run some Supernodes on your machine!</p>"},{"location":"gettingstarted/setup_env/#a-firefly-stack","title":"A FireFly Stack","text":"<p>A FireFly stack is a collection of Supernodes with networking and configuration that are designed to work together on a single development machine. A stack has multiple members (also referred to organizations). Each member has their own Supernode within the stack. This allows developers to build and test data flows with a mix of public and private data between various parties, all within a single development environment.</p> <p></p> <p>The stack also contains an instance of the FireFly Sandbox for each member. This is an example of an end-user application that uses FireFly's API. It has a backend and a frontend which are designed to walk developers through the features of FireFly, and provides code snippets as examples of how to build those features into their own application. The next section in this guide will walk you through using the Sandbox.</p>"},{"location":"gettingstarted/setup_env/#system-resources","title":"System Resources","text":"<p>The FireFly stack will run in a <code>docker-compose</code> project. For systems that run Docker containers inside a virtual machine, like macOS, you need to make sure that you've allocated enough memory to the Docker virtual machine. We recommend allocating 1GB per member. In this case, we're going to set up a stack with 3 members, so please make sure you have at least 3 GB of RAM allocated in your Docker Desktop settings.</p> <p></p>"},{"location":"gettingstarted/setup_env/#creating-a-new-stack","title":"Creating a new stack","text":"<p>It's really easy to create a new FireFly stack. The <code>ff init</code> command can create a new stack for you, and will prompt you for a few details such as the name, and how many members you want in your stack.</p> <p>To create an Ethereum based stack, run:</p> <pre><code>ff init ethereum\n</code></pre> <p>To create an Fabric based stack, run:</p> <pre><code>ff init fabric\n</code></pre> <p>Choose a stack name. For this guide, I will choose the name <code>dev</code>, but you can pick whatever you want:</p> <pre><code>stack name: dev\n</code></pre> <p>Chose the number of members for your stack. For this guide, we should pick <code>3</code> members, so we can try out both public and private messaging use cases:</p> <pre><code>number of members: 3\n</code></pre> <p></p>"},{"location":"gettingstarted/setup_env/#stack-initialization-options","title":"Stack initialization options","text":"<p>There are quite a few options that you can choose from when creating a new stack. For now, we'll just stick with the defaults. To see the full list of Ethereum options, just run <code>ff init ethereum --help</code> or to see the full list of Fabric options run <code>ff init fabric --help</code></p> <pre><code>ff init ethereum --help\nCreate a new FireFly local dev stack using an Ethereum blockchain\n\nUsage:\n  ff init ethereum [stack_name] [member_count] [flags]\n\nFlags:\n      --block-period int              Block period in seconds. Default is variable based on selected blockchain provider. (default -1)\n  -c, --blockchain-connector string   Blockchain connector to use. Options are: [evmconnect ethconnect] (default \"evmconnect\")\n  -n, --blockchain-node string        Blockchain node type to use. Options are: [geth besu remote-rpc] (default \"geth\")\n      --chain-id int                  The chain ID - also used as the network ID (default 2021)\n      --contract-address string       Do not automatically deploy a contract, instead use a pre-configured address\n  -h, --help                          help for ethereum\n      --remote-node-url string        For cases where the node is pre-existing and running remotely\n\nGlobal Flags:\n      --ansi string                   control when to print ANSI control characters (\"never\"|\"always\"|\"auto\") (default \"auto\")\n      --channel string                Select the FireFly release channel to use. Options are: [stable head alpha beta rc] (default \"stable\")\n      --connector-config string       The path to a yaml file containing extra config for the blockchain connector\n      --core-config string            The path to a yaml file containing extra config for FireFly Core\n  -d, --database string               Database type to use. Options are: [sqlite3 postgres] (default \"sqlite3\")\n  -e, --external int                  Manage a number of FireFly core processes outside of the docker-compose stack - useful for development and debugging\n  -p, --firefly-base-port int         Mapped port base of FireFly core API (1 added for each member) (default 5000)\n      --ipfs-mode string              Set the mode in which IFPS operates. Options are: [private public] (default \"private\")\n  -m, --manifest string               Path to a manifest.json file containing the versions of each FireFly microservice to use. Overrides the --release flag.\n      --multiparty                    Enable or disable multiparty mode (default true)\n      --node-name stringArray         Node name\n      --org-name stringArray          Organization name\n      --prometheus-enabled            Enables Prometheus metrics exposition and aggregation to a shared Prometheus server\n      --prometheus-port int           Port for the shared Prometheus server (default 9090)\n      --prompt-names                  Prompt for org and node names instead of using the defaults\n  -r, --release string                Select the FireFly release version to use. Options are: [stable head alpha beta rc] (default \"latest\")\n      --request-timeout int           Custom request timeout (in seconds) - useful for registration to public chains\n      --sandbox-enabled               Enables the FireFly Sandbox to be started with your FireFly stack (default true)\n  -s, --services-base-port int        Mapped port base of services (100 added for each member) (default 5100)\n  -t, --token-providers stringArray   Token providers to use. Options are: [none erc1155 erc20_erc721] (default [erc20_erc721])\n  -v, --verbose                       verbose log output\n</code></pre>"},{"location":"gettingstarted/setup_env/#start-your-stack","title":"Start your stack","text":"<p>To start your stack simply run:</p> <pre><code>ff start dev\n</code></pre> <p>This may take a minute or two and in the background the FireFly CLI will do the following for you:</p> <ul> <li>Download Docker images for all of the components of the Supernode</li> <li>Initialize a new blockchain and blockchain node running inside a container</li> <li>Set up configuration between all the components</li> <li>Deploy FireFly's <code>BatchPin</code> smart contract</li> <li>Deploy an <code>ERC-1155</code> token smart contract</li> <li>Register an identity for each member and node</li> </ul> <p>NOTE: For macOS users, the default port (5000) is already in-use by <code>ControlCe</code> service (AirPlay Receiver). You can either disable this service in your environment, or use a different port when creating your stack (e.g. <code>ff init dev -p 8000</code>)</p> <p>After your stack finishes starting it will print out the links to each member's UI and the Sandbox for that node:</p> <pre><code>ff start dev\nthis will take a few seconds longer since this is the first time you're running this stack...\ndone\n\nWeb UI for member '0': http://127.0.0.1:5000/ui\nSandbox UI for member '0': http://127.0.0.1:5109\n\nWeb UI for member '1': http://127.0.0.1:5001/ui\nSandbox UI for member '1': http://127.0.0.1:5209\n\nWeb UI for member '2': http://127.0.0.1:5002/ui\nSandbox UI for member '2': http://127.0.0.1:5309\n\n\nTo see logs for your stack run:\n\nff logs dev\n</code></pre>"},{"location":"gettingstarted/setup_env/#next-steps-use-in-the-sandbox","title":"Next steps: Use in the Sandbox","text":"<p>Now that you have some Supernodes running, it's time to start playing: in the Sandbox!</p> <p>\u2462 Use the Sandbox \u2192</p>"},{"location":"overview/gateway_features/","title":"Web3 Gateway Features","text":"<p>Web3 Gateway features allow 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.</p> <p></p>"},{"location":"overview/gateway_features/#transfer-tokenized-value","title":"Transfer tokenized value","text":"<p>The Digital Asset Features allow you to connect to token economies, in multiple blockchains, using the same infrastructure and signing keys.</p> <p>The complexities of how each token works, and how each blockchain works, are abstracted away from you by the Hyperledger FireFly Connector Framework.</p> <p>All of the layers of plumbing required to execute a transaction exactly once on a blockchain, and tracking it through to completion, are part of the stack. Deploy and configure them once in your Web3 gateway, and use them for multiple use cases in your enterprise.</p>"},{"location":"overview/gateway_features/#invoke-any-other-type-of-smart-contract","title":"Invoke any other type of smart contract","text":"<p>The API Generation features of Hyperledger FireFly, allow you to generate a convenient and reliable REST API for any smart contract logic.</p> <p>Then you just invoke that contract like you would any other API, with all the features you would expect like an OpenAPI 3.0 specification for the API, and UI explorer.</p> <p>The same reliable transaction submission framework is used as for token transfers, and you can use Hyperledger FireFly as a high volume staging post for those transactions.</p> <ul> <li>Handles peaks in workload, drip-feeding transactions onto the chain</li> <li>Handles large batch submissions, tracking</li> <li>Manages nonce assignment at high volume</li> <li>Idempotent APIs assuring that business transactions are submitted exactly once</li> </ul> <p>For EVM based chains, these features were significantly enhanced in the new EVMConnect connector introduced in v1.1 of FireFly (superseding EthConnect).</p>"},{"location":"overview/gateway_features/#index-data-from-the-blockchain","title":"Index data from the blockchain","text":"<p>Blockchain nodes are not designed for efficient querying of historical information. Instead their core function is to provide an ordered ledger of actions+events, along with a consistent world state at any point in time.</p> <p>This means that almost all user experiences and business APIs need a separate data store, that provides an fast indexed view of the history and current state of the chain.</p> <p>As an example, you've probably looked at a Block Explorer for a public blockchain on the web. Well, you weren't looking directly at the blockchain node. You were querying an off-chain indexed database, of all the blocks and transactions on that chain. An indexer behind the scenes was listening to the blockchain and synchronizing the off-chain state.</p> <p>Hyperledger FireFly has a built-in indexer for tokens, that maps every token mint/burn/transfer/approve operation that happens on the the blockchain into the database for fast query. You just specify which tokens you're interested in, and FireFly takes care of the rest.</p> <p>Additionally, FireFly does the heavy lifting part of indexing for all other types of smart contract event that might occur. It scrapes the blockchain for the events, formats them into easy to consume JSON, and reliably delivers them to your application.</p> <p>So your application just needs a small bit of code to take those payloads, and insert them into the database with the right database indexes you need to query your data by.</p>"},{"location":"overview/gateway_features/#reliably-trigger-events-in-your-applications","title":"Reliably trigger events in your applications","text":"<p>One of the most important universal rules about Web3 applications, is that they are event-driven.</p> <p>No one party in the system can chose to change the state, instead they must submit transactions that get ordered against everyone else's transactions, and only once confirmed through the consensus algorithm are they actioned.</p> <p>This means the integration into your application and core systems needs to be event-driven too.</p> <p>The same features that support reliable indexing of the blockchain data, allow reliable triggering of application code, business workflows, and core system integrations.</p> <p>Learn more about the FireFly Event Bus</p>"},{"location":"overview/gateway_features/#manage-decentralized-data-nfts-etc","title":"Manage decentralized data (NFTs etc.)","text":"<p>Your blockchain transactions are likely to refer to data that is stored off-chain.</p> <p>One common example is non-fungible-token (NFT) metadata, images and documents. These are not a good fit for storing directly in any blockchain ledger, so complimentary decentralized technologies like the InterPlanetary File System (IPFS) are used to make the data widely available and resilient outside of the blockchain itself.</p> <p>As a publisher or consumer of such metadata from decentralized storage, you need to be confident you have your own copy safe. So just like with the blockchain data, Hyperledger FireFly can act as a staging post for this data.</p> <p>Structured JSON data can be stored, uploaded and downloaded from the FireFly database.</p> <p>Large image/document/video payloads are handled by the pluggable Data Exchange microservice, which allows you to attach local or cloud storage to manage your copy of the data.</p> <p>FireFly then provides a standardized API to allow publishing of this data. So configuring a reliable gateway to the decentralized storage tier can be done once, and then accessed from your applications via a single Web3 Gateway.</p>"},{"location":"overview/gateway_features/#maintain-a-private-address-book","title":"Maintain a private address book","text":"<p>You need to manage your signing keys, and know the signing keys of others you are transacting with. A blockchain address like <code>0x0742e81393ee79C768e84cF57F1bF314F0f31ECe</code> is not very helpful for this.</p> <p>So Hyperledger FireFly provides a pluggable identity system, built on the foundation of the Decentralized IDentifier (DID). When in Web3 Gateway Mode these identities are not shared or published, and simply provide you a local address book.</p> <p>You can associate profile information with the identities, for example correlating them to the identifiers in your own core systems - such as an Identity and Access Management (IAM) system, or Know Your Customer (KYC) database.</p> <p>Learn more about Hyperledger FireFly Identities</p>"},{"location":"overview/public_vs_permissioned/","title":"Public and Permissioned Blockchain","text":""},{"location":"overview/public_vs_permissioned/#public-and-permissioned-blockchains","title":"Public and Permissioned Blockchains","text":"<p>A separate choice to the technology for your blockchain, is what combination of blockchain ecosystems you will integrate with.</p> <p>There are a huge variety of options, and increasingly you might find yourself integrating with multiple ecosystems in your solutions.</p> <p>A rough (and incomplete) high level classification of the blockchains available is as follows:</p> <ul> <li>Layer 1 public blockchains</li> <li>This is where most token ecosystems are rooted</li> <li>Layer 2 public scaling solutions backed by a Layer 1 blockchain</li> <li>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)</li> <li>Permissioned side-chains</li> <li>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</li> <li>These might have their state check-pointed/rolled-up to a Layer 2 or Layer 1 chain</li> </ul> <p>The lines are blurring between these categorizations as the technologies and ecosystems evolve.</p>"},{"location":"overview/public_vs_permissioned/#public-blockchain-variations","title":"Public blockchain variations","text":"<p>For the public Layer 1 and 2 solutions, there are too many subclassifications to go into in detail here:</p> <ul> <li>Whether ecosystems supports custom smart contract execution (EVM based is most common, where contracts are supported)</li> <li>What types of token standards are supported, or other chain specific embedded smart contracts</li> <li>Whether the chain follows an unspent transaction output (UTXO) or Account model</li> <li>How value is bridged in-to / out-of the ecosystem</li> <li>How the validator set of the chain is established - most common is Proof of Stake (PoS)</li> <li>How data availability is maintained - to check the working of the validators ensure the historical state is not lost</li> <li>The consensus algorithm, and how it interacts with the consensus of other blockchains</li> <li>How state in a Layer 2 is provable in a parent Layer 1 chain (rollup technologies etc.)</li> </ul>"},{"location":"overview/public_vs_permissioned/#common-public-considerations","title":"Common public considerations","text":"<p>The thing most consistent across public blockchain technologies, is that the technical decisions are backed by token economics.</p> <p>Put simply, creating a system where it's more financially rewarding to behave honestly, than it is to subvert and cheat the system.</p> <p>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.</p> <p>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.</p>"},{"location":"overview/public_vs_permissioned/#firefly-architecture-for-public-chains","title":"FireFly architecture for public chains","text":"<p>One of the fastest evolving aspects of the Hyperledger FireFly ecosystem, is how it facilitates enterprises to participate in these.</p> <p></p> <p>The architecture is summarized as follows:</p> <ul> <li>New FireFly Transaction Manager runtime</li> <li>Operates as a microservice extension of the FireFly Core</li> <li>Uses the <code>operation</code> resource within FireFly Core to store and update state</li> <li>Runs as a singleton and is responsible for <code>nonce</code> assignment</li> <li>Takes as much heavy lifting away from blockchain specific connectors as possible</li> <li>Lightweight FireFly Connector API (<code>ffcapi</code>)</li> <li>Simple synchronous RPC operations that map to the most common operations supported across public blockchain technologies</li> <li>Examples:<ul> <li>Find the next nonce for a given signing key</li> <li>Serialize a transaction from a set of JSON inputs and an interface definition</li> <li>Submit an un-signed transaction with a given gas price to the blockchain, via a signing wallet</li> <li>Establish a new block listener</li> <li>Poll for new blocks</li> <li>Establish a new event log listener</li> <li>Poll for new events</li> </ul> </li> <li>Pluggable Policy Engine</li> <li>Invoked to make decisions on transaction submission</li> <li>Responsible for gas price calculation</li> <li>Able to intervene and adjust the characteristics of signing/submission</li> <li>OSS reference implementation provided with Gas Station REST API integration</li> <li>Confirmation Manager</li> <li>Extracted from the Ethconnect codebase</li> <li>Coupled to both transaction submission and event confirmation</li> <li>Embeds an efficient block cache</li> <li>Event Streams</li> <li>Extracted from the Ethconnect codebase</li> <li>Checkpoint restart based reliable at-least-once delivery of events</li> <li>WebSockets interface upstream to FireFly Core</li> </ul> <p>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, and cumulated in the creation of a new repository in 2022.</p> <p>You can follow the progress and contribute in this repo: https://github.com/hyperledger/firefly-transaction-manager</p>"},{"location":"overview/supernode_concept/","title":"Introduction to Hyperledger FireFly","text":""},{"location":"overview/supernode_concept/#your-gateway-to-web3-technologies","title":"Your Gateway to Web3 Technologies","text":"<p>Hyperledger FireFly is an organization's gateway to Web3, including all the blockchain ecosystems that they participate in.</p> <p>Multiple blockchains, multiple token economies, and multiple business networks.</p> <p>FireFly is not another blockchain implementation, rather it is a pluggable API Orchestration and Data layer, integrating into all of the different types of decentralized technologies that exist in Web3:</p> <ul> <li>Public Blockchains, Layer 2 scaling solutions, Side chains, and App chains</li> <li>Permissioned Blockchains and Distributed Ledger Technologies (DLTs)</li> <li>Decentralized storage solutions</li> <li>Token ecosystems and standards</li> <li>Smart Contracts, DeFi solutions and DAOs</li> <li>Private off-chain encrypted communication rails</li> <li>Advanced cryptography solutions</li> <li>Identity frameworks</li> </ul>"},{"location":"overview/supernode_concept/#an-open-source-supernode-for-web3-apps","title":"An Open Source Supernode for Web3 Apps","text":"<p>Hyperledger FireFly is a toolkit for building and connecting new full-stack decentralized applications (dapps), as well as integrating your existing core systems to the world of Web3.</p> <p>It has a runtime engine, and it provides a data layer that synchronizes state from the blockchain and other Web3 technologies. It exposes an API and Event Bus to your business logic, that is reliable, developer friendly and ready for enterprise use.</p> <p>We call this a Supernode - it sits between the application and the underlying infrastructure nodes, providing layers of additional function.</p> <p></p> <p>The concept of a Supernode has evolved over the last decade of enterprise blockchain projects, as developers realized that they need much more than a blockchain node for their projects to be successful.</p> <p>Without a technology like Hyperledger FireFly, the application layer becomes extremely complex and fragile. Tens of thousands of lines of complex low-level \"plumbing\" / \"middleware\" code is required to integrate the web3 infrastructure into the application. This code provides zero unique business value to the solution, but can consume a huge proportion of the engineering budget and maintenance cost if built bespoke within a solution.</p>"},{"location":"overview/usage_patterns/","title":"Usage Patterns","text":"<p>There are two modes of usage for Hyperledger Firefly: Web3 Gateway and Multiparty</p> <p>A single runtime can operate in both of these modes, using different namespaces.</p>"},{"location":"overview/usage_patterns/#web3-gateway-mode","title":"Web3 Gateway Mode","text":"<p>Web3 Gateway mode lets you interact with any Web3 application, regardless of whether Hyperledger FireFly is being used by other members of your business network.</p> <p>In this mode you can:</p> <ul> <li>Transfer tokenized value</li> <li>Invoke any other type of smart contract</li> <li>Index data from the blockchain</li> <li>Reliably trigger events in your applications and back-office core systems</li> <li>Manage decentralized data (NFTs etc.)</li> <li>Use a private address book to manage signing identities and relationships</li> <li>... and much more</li> </ul> <p>Learn more about Web3 Gateway Mode.</p>"},{"location":"overview/usage_patterns/#multiparty-mode","title":"Multiparty Mode","text":"<p>Multiparty mode is used to build multi-party systems, with a common application runtime deployed by each enterprise participant.</p> <p></p> <p>This allows sophisticated applications to be built, that all use the pluggable APIs of Hyperledger FireFly to achieve end-to-end business value in an enterprise context.</p> <p>In this mode you can do everything you could do in Web3 Gateway mode, plus:</p> <ul> <li>Share and enforce common data formats</li> <li>Exchange data privately, via an encrypted data bus</li> <li>Structured JSON data payloads</li> <li>Large documents</li> <li>Coordinate on-chain and off-chain data exchange</li> <li>Private data</li> <li>Broadcast data</li> <li>Mask on-chain activities using hashes</li> <li>Use a shared address book to manage signing identities and relationships</li> <li>... and much more</li> </ul> <p>Learn more about Multiparty Mode.</p>"},{"location":"overview/key_components/","title":"Key Features","text":"<p>Hyperledger FireFly provides a rich suite of features for building new applications, and connecting existing Web3 ecosystems to your business. In this section we introduce each core pillar of functionality.</p>"},{"location":"overview/key_components/apps/","title":"Apps","text":""},{"location":"overview/key_components/apps/#apps","title":"Apps","text":"<p>Rapidly accelerating development of applications is a key feature of Hyperledger FireFly.</p> <p>The toolkit is designed to support the full-stack of applications in the enterprise Web3 ecosystem, not just the Smart Contract layer.</p> <p>Business logic APIs, back-office system integrations, and web/mobile user experiences are just as important to the overall Web3 use case.</p> <p>These layers require a different developer skill-set to the on-chain Smart Contracts, and those developers must have the tools they need to work efficiently.</p>"},{"location":"overview/key_components/apps/#api-gateway","title":"API Gateway","text":"<p>FireFly provides APIs that:</p> <ul> <li>Are fast and efficient</li> <li>Have rich query support</li> <li>Give deterministic outcomes and clear instructions for safe use</li> <li>Integrate with your security frameworks like OAuth 2.0 / OpenID Connect single sign-on</li> <li>Provide Open API 3 / Swagger definitions</li> <li>Come with code SDKs, with rich type information</li> <li>Conform as closely as possible to the principles of REST</li> <li>Do not pretend to be RESTful in cases when it is impossible to be</li> </ul> <p>Learn more about deploying APIs for custom smart contracts in this tutorial</p>"},{"location":"overview/key_components/apps/#event-streams","title":"Event Streams","text":"<p>The reality is that the only programming paradigm that works for a decentralized solutions, is an event-driven one.</p> <p>All blockchain technologies are for this reason event-driven programming interfaces at their core.</p> <p>In an overall solution, those on-chain events must be coordinated with off-chain private data transfers, and existing core-systems / human workflows.</p> <p>This means great event support is a must:</p> <ul> <li>Convenient WebSocket APIs that work for your microservices development stack</li> <li>Support for Webhooks to integrated serverless functions</li> <li>Integration with your core enterprise message queue (MQ) or enterprise service bus (ESB)</li> <li>At-least-once delivery assurance, with simple instructions at the application layer</li> </ul> <p>Learn all about the Hyperledger FireFly Event Bus, and event-driven application architecture, in this reference section</p>"},{"location":"overview/key_components/apps/#api-generation","title":"API Generation","text":"<p>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.</p> <p>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.</p> <p>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.</p> <p>Well documented APIs are the modern norm for this, and it is no different for blockchain.</p> <p>This means Hyperledger FireFly provides:</p> <ul> <li>Generating the interface for methods and events on your smart contract</li> <li>Providing robust transaction submission, and event streaming</li> <li>Publishing the API, version, and location, of your smart contracts to the network</li> </ul>"},{"location":"overview/key_components/connectors/","title":"Connector Framework","text":""},{"location":"overview/key_components/connectors/#pluggable-microservices-architecture","title":"Pluggable Microservices Architecture","text":"<p>The ability for every component to be pluggable is at the core of Hyperledger FireFly.</p> <p>A microservices approach is used, combining code plug-points in the core runtime, with API extensibility to remote runtimes implemented in a variety of programming languages.</p> <p></p>"},{"location":"overview/key_components/connectors/#extension-points","title":"Extension points","text":"<ul> <li>Blockchain - a rich framework for extensibility to any blockchain / digital ledger technology (DLT)</li> <li>Tokens - mapping token standards and governance models to a common data model</li> <li>Shared storage - supporting permissioned and public distributed storage technologies</li> <li>Data exchange - private local/storage and encrypted transfer of data</li> <li>Identity - flexibility for resolving identities via Decentralized IDentifier (DID)</li> <li>Persistence - the local private database</li> </ul> <p>Learn more about the plugin architecture here</p>"},{"location":"overview/key_components/connectors/#blockchain-connector-framework","title":"Blockchain Connector Framework","text":"<p>The most advanced extension point is for the blockchain layer, where multiple layers of extensibility are provided to support the programming models, and behaviors of different blockchain technologies.</p> <p>This framework has been proven with technologies as different as EVM based Layer 2 Ethereum Scaling solutions like Polygon, all the way to permissioned Hyperledger Fabric networks.</p> <p>Check out instructions to connect to a list of remote blockchain networks here.</p> <p></p> <p>Find out more about the Blockchain Connector Framework here.</p>"},{"location":"overview/key_components/digital_assets/","title":"Digital Assets","text":""},{"location":"overview/key_components/digital_assets/#digital-asset-features","title":"Digital asset features","text":"<p>The modelling, transfer and management of digital assets is the core programming foundation of blockchain.</p> <p>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.</p>"},{"location":"overview/key_components/digital_assets/#token-api","title":"Token API","text":"<p>Token standards have been evolving in the industry through standards like ERC-20/ERC-721, and the Web3 signing wallets that support these.</p> <p>Hyperledger FireFly bring this same standardization to the application tier. Providing APIs that work across token standards, and blockchain implementations, providing consistent and interoperable support.</p> <p>This means one application or set of back-end systems, can integrate with multiple blockchains, and different token implementations.</p> <p>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.</p> <p>Learn more about token standards for fungible tokens, and non-fungible tokens (NFTs) in this set of tutorials</p>"},{"location":"overview/key_components/digital_assets/#transfer-history-audit-trail","title":"Transfer history / audit trail","text":"<p>For efficiency blockchains do not provide a direct ability to query historical transaction information.</p> <p>Depending on the blockchain technology, even the current balance of your wallet can be complex to calculate - particularly for blockchain technologies based on an Unspent Transaction Output (UTXO) model.</p> <p>So off-chain indexing of transaction history is an absolute must-have for any digital asset solution.</p> <p>Hyperledger FireFly provides:</p> <ul> <li>Automatic indexing of tokens, whether existing or newly deployed</li> <li>Off-chain indexing of fungible and non-fungible asset transfers &amp; balances</li> <li>Off-chain indexing of approvals</li> <li>Integration with digital identity</li> <li>Full extensibility across both token standards and blockchain technologies</li> </ul>"},{"location":"overview/key_components/digital_assets/#wallets","title":"Wallets","text":"<p>Wallet and signing-key management is a critical requirement for any blockchain solution, particularly those involving the transfer of digital assets between wallets.</p> <p>Hyperledger FireFly provides you the ability to:</p> <ul> <li>Integrate multiple different signing/custody solutions in a proven way</li> <li>Manage the mapping of off-chain identities to on-chain signing identities</li> <li>Provide a plug-point for policy-based decision making on high value transactions</li> <li>Manage connections to multiple different blockchain solutions</li> </ul>"},{"location":"overview/key_components/flows/","title":"Flows","text":""},{"location":"overview/key_components/flows/#data-flow","title":"Data flow","text":"<p>The reality of most Web3 scenarios is that only a small part of the overall use-case can be represented inside the blockchain or distributed ledger technology.</p> <p>Some additional data flow is always required. This does not diminish the value of executing the kernel of the logic within the blockchain itself.</p> <p>Hyperledger FireFly embraces this reality, and allows an organization to keep track of the relationship between the off-chain data flow, and the on-chain transactions.</p> <p>Let's look at a few common examples:</p>"},{"location":"overview/key_components/flows/#digital-asset-transfers","title":"Digital Asset Transfers","text":"<p>Examples of common data flows performed off-chain, include Know Your Customer (KYC) and Anti Money Laundering (AML) checks that need to be performed and validated before participating in transactions.</p> <p>There might also be document management and business transaction flows required to verify the conditions are correct to digitally settle a transaction. Have the goods been delivered? Are the contracts in place?</p> <p>In regulated enterprise scenarios it is common to see a 10-to-1 difference in the number of steps performed off-chain to complete a business transaction, vs. the number of steps performed on-chain.</p> <p>These off-chain data flows might be coordinated with on-chain smart contracts that lock assets in digital escrow until the off-chain steps are completed by each party, and protect each party while the steps are being completed.</p> <p>A common form of digital escrow is a Hashed Timelock Contract (HTLC).</p>"},{"location":"overview/key_components/flows/#non-fungible-tokens-nfts-and-hash-pinning","title":"Non-fungible Tokens (NFTs) and hash-pinning","text":"<p>The data associated with an NFT might be as simple as a JSON document pointing at an interesting piece of artwork, or as complex a set of high resolution scans / authenticity documents representing a digital twin of a real world object.</p> <p>Here the concept of a hash pinning is used - allowing anyone who has a copy of the original data to recreate the hash that is stored in the on-chain record.</p> <p>With even the simplest NFT the business data is not stored on-chain, so simple data flow is always required to publish/download the off-chain data.</p> <p>The data might be published publicly for anyone to download, or it might be sensitive and require a detailed permissioning flow to obtain it from a current holder of that data.</p>"},{"location":"overview/key_components/flows/#dynamic-nfts-and-business-transaction-flow","title":"Dynamic NFTs and Business Transaction Flow","text":"<p>In an enterprise context, an NFT might have a dynamic ever-evolving trail of business transaction data associated with it. Different parties might have different views of that business data, based on their participation in the business transactions associated with it.</p> <p>Here the NFT becomes a like a foreign key integrated across the core systems of a set of enterprises working together in a set of business transactions.</p> <p>The data itself needs to be downloaded, retained, processed and rendered. Probably integrated to systems, acted upon, and used in multiple exchanges between companies on different blockchains, or off-chain.</p> <p>The business process is accelerated through this Enterprise NFT on the blockchain - as all parties have matched or bound their own private data store to that NFT. This means they are confident to be executing a business transaction against the same person or thing in the world.</p>"},{"location":"overview/key_components/flows/#data-and-transaction-flow-patterns","title":"Data and Transaction Flow patterns","text":"<p>Hyperledger FireFly provides the raw tools for building data and transaction flow patterns, such as storing, hashing and transferring data. It provides the event bus to trigger off-chain applications and integration to participate in the flows.</p> <p>It also provides the higher level flow capabilities that are needed for multiple parties to build sophisticated transaction flows together, massively simplifying the application logic required:</p> <ul> <li>Coordinating the transfer of data off-chain with a blockchain sequencing transaction</li> <li>Batching for high throughput transfer via the blockchain and distributed storage technologies</li> <li>Managing privacy groups between parties involved in a business transaction</li> <li>Masking the relationship between blockchain transactions, for sensitive data</li> </ul> <p></p> <p>Learn more in Multiparty Process Flows</p>"},{"location":"overview/key_components/orchestration_engine/","title":"Orchestration Engine","text":""},{"location":"overview/key_components/orchestration_engine/#firefly-core","title":"FireFly Core","text":"<p>At the core of Hyperledger FireFly is an event-driven engine that routes, indexed, aggregates, and sequences data to and from the blockchain, and other connectors.</p> <p></p>"},{"location":"overview/key_components/orchestration_engine/#data-layer","title":"Data Layer","text":"<p>Your own private view of the each network you connect:</p> <ul> <li>Indexes of all tokens and NFTs that you transact with</li> <li>A consistent view across multiple blockchains</li> <li>High performance rich query of transaction and data audit trail</li> <li>Private data you have received from other parties</li> <li>Local copies of data you have download from IPFS or other shared storage tech</li> </ul>"},{"location":"overview/key_components/orchestration_engine/#event-bus","title":"Event Bus","text":"<p>Whether a few dozen companies in a private blockchain consortium, or millions of users connected to a public blockchain network - one thing is always true:</p> <p>Decentralized applications are event-driven.</p> <p>In an enterprise context, you need to think not only about how those events are being handled and made consistent within the blockchain layer, but also how those events are being processed and integrated to your core systems.</p> <p>FireFly provides you with the reliable streams of events you need, as well as the interfaces to subscribe to those events and integrate them into your core systems.</p> <ul> <li>Token transfer events, across multiple blockchains, and varied asset types</li> <li>Custom smart contract events</li> <li>Correlated on-chain and off-chain data events</li> </ul> <p></p> <p>Learn more about the event bus and event-driven programming in this reference document</p>"},{"location":"overview/key_components/security/","title":"Security","text":""},{"location":"overview/key_components/security/#api-security","title":"API Security","text":"<p>Hyperledger FireFly provides a pluggable infrastructure for authenticating API requests.</p> <p>Each namespace can be configured with a different authentication plugin, such that different teams can have different access to resources on the same FireFly server.</p> <p>A reference plugin implementation is provided for HTTP Basic Auth, combined with a <code>htpasswd</code> verification of passwords with a <code>bcrypt</code> encoding.</p> <p>See this config section for details, and the reference implementation in Github</p> <p>Pre-packaged vendor extensions to Hyperledger FireFly are known to be available, addressing more comprehensive role-based access control (RBAC) and JWT/OAuth based security models.</p>"},{"location":"overview/key_components/security/#data-partitioning-and-tenancy","title":"Data Partitioning and Tenancy","text":"<p>Namespaces also provide a data isolation system for different applications / teams / tenants sharing a Hyperledger FireFly node.</p> <p></p> <p>Data is partitioned within the FireFly database by namespace. It is also possible to increase the separation between namespaces, by using separate database configurations. For example to different databases or table spaces within a single database server, or even to different database servers.</p>"},{"location":"overview/key_components/security/#private-data-exchange","title":"Private Data Exchange","text":"<p>FireFly has a pluggable implementation of a private data transfer bus. This transport supports both structured data (conforming to agreed data formats), and large unstructured data &amp; documents.</p> <p></p> <p>A reference microservice implementation is provided for HTTPS point-to-point connectivity with mutual TLS encryption.</p> <p>See the reference implementation in Github</p> <p>Pre-packaged vendor extensions to Hyperledger FireFly are known to be available, addressing message queue based reliable delivery of messages, hub-and-spoke connectivity models, chunking of very large file payloads, and end-to-end encryption.</p> <p>Learn more about these private data flows in Multiparty Process Flows.</p>"},{"location":"overview/key_components/tools/","title":"Tools","text":""},{"location":"overview/key_components/tools/#firefly-cli","title":"FireFly CLI","text":"<p>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.</p>"},{"location":"overview/key_components/tools/#firefly-sandbox","title":"FireFly Sandbox","text":"<p>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.</p> <p>\ud83d\uddd2 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 to make requests to FireFly's API.</p>"},{"location":"overview/key_components/tools/#firefly-explorer","title":"FireFly Explorer","text":"<p>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.</p> <p></p>"},{"location":"overview/multiparty/","title":"Enterprise multi-party systems","text":""},{"location":"overview/multiparty/#introduction","title":"Introduction","text":"<p>Multiparty mode has all the features in Gateway mode with the added benefit of multi-party process flows.</p> <p>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).</p> <p>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.</p> <p></p> <p>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.</p> <p>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 models can be created to enable secure collaboration in new ways, without compromising the integrity of an individual organization.</p> <p>The technology is most powerful in ecosystems of \"coopetition\", where privacy and security requirements are high. Multi-party systems establish new models of trust, with easy to prove outcomes that minimize the need for third party arbitration, and costly investigation into disputes.</p>"},{"location":"overview/multiparty/#points-of-difference","title":"Points of difference","text":"<p>Integration with existing systems of record is critical to unlock the potential of these new ecosystems. So multi-party systems embrace the existing investments of each party, rather than seeking to unify or replace them.</p> <p>Multi-party systems are different from centralized third-party systems, because each party retains sovereignty over:</p> <ul> <li>Their application instance</li> <li>Their private data</li> <li>Their business processes</li> <li>Their proprietary business logic</li> <li>Their internal business processes and IT controls</li> </ul>"},{"location":"overview/multiparty/#use-case-example","title":"Use Case Example","text":"<p>There are many multiparty use cases. An example for healthcare is detailed below.</p> <p>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.</p> <p>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 one healthcare provider and two 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.</p> <p>In a larger healthcare ecosystem with many members, a similar concept may emerge with multiple variations of members.</p>"},{"location":"overview/multiparty/broadcast/","title":"Broadcast / shared data","text":""},{"location":"overview/multiparty/broadcast/#introduction","title":"Introduction","text":"<p>Multi-party systems are about establishing a shared source of truth, and 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</p> <p></p>"},{"location":"overview/multiparty/broadcast/#blockchain-backed-broadcast","title":"Blockchain backed broadcast","text":"<p>In order to maintain a complete history of all broadcast data for new members joining the network, FireFly uses the blockchain to sequence the broadcasts with pinning transactions referring to the data itself.</p> <p>Using the blockchain also gives a global order of events for these broadcasts, which allows them to be processed by each member in a way that allows them to derive the same result - even though the processing logic on the events themselves is being performed independently by each member.</p> <p>For more information see Multiparty Event Sequencing.</p>"},{"location":"overview/multiparty/broadcast/#shared-data","title":"Shared data","text":"<p>The data included in broadcasts is not recorded on the blockchain. Instead a pluggable shared storage mechanism is used to contain the data itself. The on-chain transaction just contains a hash of the data that is stored off-chain.</p> <p>This is because the data itself might be too large to be efficiently stored and transferred via the blockchain itself, or subject to deletion at some point in the future through agreement by the members in the network.</p> <p>While the data should be reliably stored with visibility to all members of the network, the data can still be secured from leakage outside of the network.</p> <p>The InterPlanetary File System (IPFS) is an example of a distributed technology for peer-to-peer storage and distribution of such data in a decentralized multi-party system. It provides secure connectivity between a number of nodes, combined with a decentralized index of data that is available, and native use of hashes within the technology as the way to reference data by content.</p>"},{"location":"overview/multiparty/broadcast/#firefly-built-in-broadcasts","title":"FireFly built-in broadcasts","text":"<p>FireFly uses the broadcast mechanism internally to distribute key information to all parties in the network:</p> <ul> <li>Network map</li> <li>Organizational identities</li> <li>Nodes</li> <li>See Identities in the reference section for more information</li> <li>Datatype definitions</li> <li>See Datatype in the reference section for more information</li> <li>Namespaces</li> <li>See Namespaces for more information</li> </ul> <p>These definitions rely on the same assurances provided by blockchain backed broadcast that FireFly applications do.</p> <ul> <li>Verification of the identity of the party in the network that performed the broadcast</li> <li>Deterministic assignment of a namespace+name to an unique item of data</li> <li>If two parties in the network broadcast the same data at similar times, the     same one \"wins\" for all parties in the network (including the broadcaster)</li> </ul>"},{"location":"overview/multiparty/data_exchange/","title":"Private data exchange","text":""},{"location":"overview/multiparty/data_exchange/#introduction","title":"Introduction","text":"<p>Private data exchange is the way most enterprise business-to-business communication happens today. One party privately sends data to another, over a pipe that has been 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.</p> <p></p> <p>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 data continue to transfer over such interfaces.</p> <p>So real-time application to application private messaging, and private transfer of large blobs/documents, are first class constructs in the FireFly API.</p>"},{"location":"overview/multiparty/data_exchange/#qualities-of-service","title":"Qualities of service","text":"<p>FireFly recognizes that a multi-party system will need to establish a secure messaging backbone, with the right qualities of service for their requirements. So the implementation is pluggable, and the plugin interface embraces the following quality of service characteristics that differ between different implementations.</p> <ul> <li>Transport Encryption</li> <li>Technologies like TLS encrypt data while it is in flight, so that it cannot be     sniffed by a third party that has access to the underlying network.</li> <li>Authentication</li> <li>There are many technologies including Mutual TLS, and Java Web Tokens (JWT),     that can be used to ensure a private data exchange is happening with the     correct party in the system.</li> <li>Most modern approaches use public/private key encryption to establish the identity     during the setup phase of a connection. This means a distribution mechanism is required     for public keys, which might be enhanced with a trust hierarchy (like PKI).</li> <li>Request/Response (Sync) vs. Message Queuing (Async)</li> <li>Synchronous transports like HTTPS require both parties to be available at the     time data is sent, and the transmission must be retried at the application (plugin)     layer if it fails or times out.</li> <li>Asynchronous transports like AMQP, MQTT or Kafka introduce one or more broker runtimes     between the parties, that reliably buffer the communications if the target application     falls behind or is temporarily unavailable.</li> <li>Hub &amp; spoke vs. Peer to peer</li> <li>Connectivity might be direct from one party to another within the network, tackling     the IT security complexity of firewalls between sensitive networks. Or network shared     infrastructure / as-a-service provider might be used to provide a reliable backbone     for data exchange between the members.</li> <li>End-to-end Payload Encryption</li> <li>Particularly in cases where the networking hops are complex, or involve shared     shared/third-party infrastructure, end-to-end encryption can be used to additionally     protect the data while in flight. This technology means data remains encrypted     from the source to the target, regardless of the number of transport hops taken in-between.</li> <li>Large blob / Managed file transfer</li> <li>The optimal approach to transferring real-time small messages (KBs in size) is different     to the approach to transferring large blobs (MBs/GBs in size). For large blobs chunking,     compression, and checkpoint restart are common for efficient and reliable transfer.</li> </ul>"},{"location":"overview/multiparty/data_exchange/#firefly-oss-implementation","title":"FireFly OSS implementation","text":"<p>A reference implementation of a private data exchange is provided as part of the FireFly project. This implementation uses peer-to-peer transfer over a synchronous HTTPS transport, backed by Mutual TLS authentication. X509 certificate exchange is orchestrated by FireFly, such that self-signed certificates can be used (or multiple PKI trust roots) and bound to the blockchain-backed identities of the organizations in FireFly.</p> <p>See hyperledger/firefly-dataexchange-https</p>"},{"location":"overview/multiparty/deterministic/","title":"Deterministic Compute","text":""},{"location":"overview/multiparty/deterministic/#introduction","title":"Introduction","text":"<p>A critical aspect of designing a multi-party systems, is choosing where you exploit the blockchain and other advanced cryptography technology to automate agreement between parties.</p> <p>Specifically where you rely on the computation itself to come up with a result that all parties can independently trust. For example because all parties performed the same computation independently and came up with the same result, against the same data, and agreed to that result using a consensus algorithm.</p> <p>The more sophisticated the agreement is you want to prove, the more consideration needs to be taken into factors such as:</p> <ul> <li>Data privacy</li> <li>Data deletion</li> <li>Ease of understanding by business users</li> <li>Ease of audit</li> <li>Autonomy of parties with proprietary business logic</li> <li>Human workflows (obviously non-deterministic)</li> <li>Technology complexity/maturity (particularly for privacy preserving technologies)</li> <li>Cost and skills for implementation</li> </ul> <p>FireFly embraces the fact that different use cases, will make different decisions on how much of the agreement should be enforced through deterministic compute.</p> <p>Also that multi-party systems include a mixture of approaches in addition to deterministic compute, including traditional off-chain secure HTTP/Messaging, documents, private non-deterministic logic, and human workflows.</p>"},{"location":"overview/multiparty/deterministic/#the-fundamental-building-blocks","title":"The fundamental building blocks","text":"<p>There are some fundamental types of deterministic computation, that can be proved with mature blockchain technology, and all multi-party systems should consider exploiting:</p> <ul> <li>Total conservation of value</li> <li>Allows you to assign value to something, because you know it is a fraction of a total pool</li> <li>This is the magic behind fungible tokens, or \"coins\"</li> <li>The proven technology for this is a shared ledger of all previous transactions</li> <li>Learn more in the Tokens section</li> <li>Existence and ownership of a unique identifiable thing</li> <li>Gives you an anchor to attach to something in the real world</li> <li>This is the magic behind non-fungible tokens (NTFs)</li> <li>The proven technology for this is a shared ledger of its creation, and ownership changes</li> <li>Learn more in the Tokens section</li> <li>An agreed sequence of events</li> <li>The foundation tool that allows the building of higher level constructs (including tokens)</li> <li>Not previously available when business ecosystems used HTTP/Messaging transports alone</li> <li>Can be bi-lateral, multi-lateral or global</li> <li>Each blockchain technology has different features to establish these \"chains\" of information</li> <li>Different approaches provide privacy different levels of privacy on the parties and sequence</li> <li>Identification of data by a \"hash\" of its contents</li> <li>The glue that binds a piece of private data, to a proof that you have a copy of that data</li> <li>This is the basis of \"pinning\" data to the blockchain, without sharing its contents</li> <li>Care needs to be taken to make sure the data is unique enough to make the hash secure</li> <li>Learn more in the Gateway Features section</li> </ul>"},{"location":"overview/multiparty/deterministic/#advanced-cryptography-and-privacy-preserving-trusted-compute","title":"Advanced Cryptography and Privacy Preserving Trusted Compute","text":"<p>There are use cases where a deterministic agreement on computation is desired, but the data upon which the execution is performed cannot be shared between all the parties.</p> <p>For example proving total conservation of value in a token trading scenario, without knowing who is involved in the individual transactions. Or providing you have access to a piece of data, without disclosing what that data is.</p> <p>Technologies exist that can solve these requirements, with two major categories:</p> <ul> <li>Zero Knowledge Proofs (ZKPs)</li> <li>Advanced cryptography techniques that allow one party to generate a proof that can be     be verified by another party, without access to the data used to generate the proof.</li> <li>Trusted Compute Environments (TEEs)</li> <li>Secure compute environments that provide proofs of what code was executed, such that     other parties can be confident of the logic that was executed without having access to the data.</li> </ul> <p>FireFly today provides an orchestration engine that's helpful in coordinating the inputs, outputs, and execution of such advanced cryptography technologies.</p> <p>Active collaboration between the FireFly and other projects like Hyperledger Avalon, and Hyperledger Cactus, is evolving how these technologies can plug-in with higher level patterns.</p>"},{"location":"overview/multiparty/deterministic/#complementary-approaches-to-deterministic-computation","title":"Complementary approaches to deterministic computation","text":"<p>Enterprise multi-party systems usually operate differently to end-user decentralized applications. In particular, strong identity is established for the organizations that are involved, and those organizations usually sign legally binding commitments around their participation in the network. Those businesses then bring on-board an ecosystem of employees and or customers that are end-users to the system.</p> <p>So the shared source of truth empowered by the blockchain and other cryptography are not the only tools that can be used in the toolbox to ensure correct behavior. Recognizing that there are real legal entities involved, that are mature and regulated, does not undermine the value of the blockchain components. In fact it enhances it.</p> <p>A multi-party system can use just enough of this secret sauce in the right places, to change the dynamics of trust such that competitors in a market are willing to create value together that could never be created before.</p> <p>Or create a system where parties can share data with each other while still conforming to their own regulatory and audit commitments, that previously would have been impossible to share.</p> <p>Not to be overlooked is the sometimes astonishing efficiency increase that can be added to existing 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.</p>"},{"location":"overview/multiparty/multiparty_flow/","title":"Multiparty Process Flows","text":""},{"location":"overview/multiparty/multiparty_flow/#flow-features","title":"Flow features","text":"<p>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.</p>"},{"location":"overview/multiparty/multiparty_flow/#private-data-flow","title":"Private data flow","text":"<p>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.</p> <p>The number of enterprise solutions where all data can flow directly through the blockchain, is vanishingly small.</p> <p>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:</p> <ul> <li>Establishing the identity of participants so data can be shared</li> <li>Securing the transfer of data off-chain</li> <li>Coordinating off-chain data flow with on-chain data flow</li> <li>Managing sequence for deterministic outcomes for all parties</li> <li>Integrating off-chain private execution with multi-step stateful business logic</li> </ul>"},{"location":"overview/multiparty/multiparty_flow/#multi-party-business-process-flow","title":"Multi-party business process flow","text":"<p>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.</p> <p>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.</p> <p>So you need the platform to:</p> <ul> <li>Provide a robust event-driven programming model fitting a \"state machine\" approach</li> <li>Integrate with the decentralized application stack of each participant</li> <li>Allow integration with the core-systems and human decision making of each participant</li> <li>Provide deterministic ordering between all parties</li> <li>Provide identity assurance and proofs for data flow / transition logic</li> </ul>"},{"location":"overview/multiparty/multiparty_flow/#data-exchange","title":"Data exchange","text":"<p>Business processes need data, and that data comes in many shapes and sizes.</p> <p>The platform needs to handle all of them:</p> <ul> <li>Large files and documents, as well as application data</li> <li>Uniqueness / Enterprise NFTs - agreement on a single \"foreign key\" for a record</li> <li>Non-repudiation, and acknowledgement of receipt</li> <li>Coordination of flows of data, with flows of value - delivery vs. payment scenarios</li> </ul>"},{"location":"overview/multiparty/multiparty_flow/#building-multi-party-flows","title":"Building multi-party flows","text":"<p>The ability to globally sequence events across parties is a game changing capability of a multiparty system. FireFly is designed to allow developers to harnesses that power in the application layer, to build sophisticated multi-party APIs and user experiences.</p> <p></p> <ul> <li>Build multi-party business processes where there is one agreed outcome:</li> <li>Agree the trigger, inputs, outputs of each step in the process</li> <li>Agree any common \"rules of the road\" must be adhered to</li> <li>Look back at your shared history, when deciding to commit to the next step:</li> <li>Fast rich-query cache, backed by a private database</li> <li>Initiate the next step through automated or manual decision making</li> <li>Only consider a step final once it's multi-party sequence has been confirmed</li> <li>Gain big efficiencies in how multi-party business processes work:</li> <li>Once locked in, a step is consider final - attested to by the party</li> <li>If two parties submit conflicting actions, one wins, and one loses</li> <li>Avoids complex compensation logic in the business orchestration layer</li> <li>Provides one clear source of truth to quickly resolve multi-party disputes</li> <li>Program multi-party apps using the tools you know:</li> <li>REST APIs for triggering the next step in a process, and querying history</li> <li>WebSockets and Webhooks for events (pluggable to other event transports)</li> <li>Remember - each party runs their own copy of the app, with their own private data</li> <li>Allow each party to integrate into their existing core systems:</li> <li>Realtime or batch</li> <li>Human workflows</li> <li>Proprietary business logic that is unique to one party</li> <li>Avoid sensitive data written to the blockchain:</li> <li>Works in bi-lateral and multi-lateral scenarios</li> <li>Designed to limit leaking other \"metadata\" about the transaction as well</li> <li>Share partial history with different participants in a</li> <li>No requirement to write custom on-chain smart contract logic:</li> <li>Can be combined with rich custom on-chain logic as well</li> </ul>"},{"location":"overview/multiparty/multiparty_flow/#innovate-fast","title":"Innovate fast","text":"<p>Building a successful multi-party system is often about business experimentation, and business results. Proving the efficiency gains, and new business models, made possible by working together in a new way under a new system of trust.</p> <p>Things that can get in the way of that innovation, can include concerns over data privacy, technology maturity, and constraints on autonomy of an individual party in the system. An easy to explain position on how new technology components are used, where data lives, and how business process independence is maintained can really help parties make the leap of faith necessary to take the step towards a new model.</p> <p>Keys to success often include building great user experiences that help digitize clunky decades old manual processes. Also easy to integrate with APIs, what embrace the existing core systems of record that are establish within each party.</p>"},{"location":"overview/multiparty/multiparty_flow/#consider-the-on-chain-toolbox-too","title":"Consider the on-chain toolbox too","text":"<p>There is a huge amount of value that deterministic execution of multi-party logic within the blockchain can add. However, the more compute is made fully deterministic via a blockchain consensus algorithm validated by multiple parties beyond those with a business need for access to the data, the more sensitivity needs to be taken to data privacy. Also bear in mind any data that is used in this processing becomes immutable - it can never be deleted.</p> <p>The core constructs of blockchain are a great place to start. Almost every process can be enhanced with pre-built fungible and non-fungible tokens, for example. Maybe it's to build a token economy that enhances the value parties get from the system, or to encourage healthy participation (and discourage bad behavior). Or maybe it's to track exactly which party owns a document, asset, or action within a process using NFTs.</p> <p>On top of this you can add advanced tools like digital escrow, signature / threshold based voting on outcomes, and atomic swaps of value/ownership.</p> <p>The investment in building this bespoke on-chain logic is higher than building the off-chain pieces (and there are always some off-chain pieces as we've discussed), so it's about finding the kernel of value the blockchain can provide to differentiate your solution from a centralized database solution.</p> <p>The power provided by deterministic sequencing of events, attested by signatures, and pinned to private data might be sufficient for some cases. In others the token constructs are the key value that differentiates the decentralized ecosystem. Whatever it is, it's important it is identified and crafted carefully.</p> <p>Note that advanced privacy preserving techniques such as zero-knowledge proofs (ZKP) are gaining traction and hardening in their production readiness and efficiency. Expect these to play an increasing role in the technology stack of multiparty systems (and Hyperledger FireFly) in the future.</p> <p>Learn more in the Deterministic Compute section.</p>"},{"location":"reference/api_post_syntax/","title":"API POST Syntax","text":""},{"location":"reference/api_post_syntax/#syntax-overview","title":"Syntax Overview","text":"<p>Endpoints that allow submitting a transaction allow an optional query parameter called <code>confirm</code>. When <code>confirm=true</code> is set in the query string, FireFly will wait to send an HTTP response until the message has been confirmed. This means, where a blockchain transaction is involved, the HTTP request will not return until the blockchain transaction is complete.</p> <p>This is useful for endpoints such as registration, where the client app cannot proceed until the transaction is complete and the member/node is registered. Rather than making a request to register a member/node and then repeatedly polling the API to check to see if it succeeded, an HTTP client can use this query parameter and block until registration is complete.</p> <p>NOTE: This does not mean that any other member of the network has received, processed, or responded to the message. It just means that the transaction is complete from the perspective of the FireFly node to which the transaction was submitted.</p>"},{"location":"reference/api_post_syntax/#example-api-call","title":"Example API Call","text":"<p><code>POST</code> <code>/api/v1/messages/broadcast?confirm=true</code></p> <p>This will broadcast a message and wait for the message to be confirmed before returning.</p>"},{"location":"reference/api_query_syntax/","title":"API Query Syntax","text":""},{"location":"reference/api_query_syntax/#syntax-overview","title":"Syntax Overview","text":"<p>REST collections provide filter, <code>skip</code>, <code>limit</code> and <code>sort</code> support.</p> <ul> <li>The field in the message is used as the query parameter</li> <li>Syntax: <code>field=[modifiers][operator]match-string</code></li> <li>When multiple query parameters are supplied these are combined with AND</li> <li>When the same query parameter is supplied multiple times, these are combined with OR</li> </ul>"},{"location":"reference/api_query_syntax/#example-api-call","title":"Example API Call","text":"<p><code>GET</code> <code>/api/v1/messages?confirmed=&gt;0&amp;type=broadcast&amp;topic=t1&amp;topic=t2&amp;context=@someprefix&amp;sort=sequence&amp;descending&amp;skip=100&amp;limit=50</code></p> <p>This states:</p> <ul> <li>Filter on <code>confirmed</code> greater than 0</li> <li>Filter on <code>type</code> exactly equal to <code>broadcast</code></li> <li>Filter on <code>topic</code> exactly equal to <code>t1</code> or <code>t2</code></li> <li>Filter on <code>context</code> containing the case-sensitive string <code>someprefix</code></li> <li>Sort on <code>sequence</code> in <code>descending</code> order</li> <li>Paginate with <code>limit</code> of <code>50</code> and <code>skip</code> of <code>100</code> (e.g. get page 3, with 50/page)</li> </ul> <p>Table of filter operations, which must be the first character of the query string (after the <code>=</code> in the above URL path example)</p>"},{"location":"reference/api_query_syntax/#operators","title":"Operators","text":"<p>Operators are a type of comparison operation to perform against the match string.</p> Operator Description <code>=</code> Equal (none) Equal (shortcut) <code>@</code> Containing <code>^</code> Starts with <code>$</code> Ends with <code>&lt;&lt;</code> Less than <code>&lt;</code> Less than (shortcut) <code>&lt;=</code> Less than or equal <code>&gt;&gt;</code> Greater than <code>&gt;</code> Greater than (shortcut) <code>&gt;=</code> Greater than or equal <p>Shortcuts are only safe to use when your match string starts with <code>a-z</code>, <code>A-Z</code>, <code>0-9</code>, <code>-</code> or <code>_</code>.</p>"},{"location":"reference/api_query_syntax/#modifiers","title":"Modifiers","text":"<p>Modifiers can appear before the operator, to change its behavior.</p> Modifier Description <code>!</code> Not - negates the match <code>:</code> Case insensitive <code>?</code> Treat empty match string as null <code>[</code> Combine using <code>AND</code> on the same field <code>]</code> Combine using <code>OR</code> on the same field (default)"},{"location":"reference/api_query_syntax/#detailed-examples","title":"Detailed examples","text":"Example Description <code>cat</code> Equals \"cat\" <code>=cat</code> Equals \"cat\" (same) <code>!=cat</code> Not equal to \"cat\" <code>:=cat</code> Equal to \"CAT\", \"cat\", \"CaT etc. <code>!:cat</code> Not equal to \"CAT\", \"cat\", \"CaT etc. <code>=!cat</code> Equal to \"!cat\" (! is after operator) <code>^cats/</code> Starts with \"cats/\" <code>$_cat</code> Ends with with \"_cat\" <code>!:^cats/</code> Does not start with \"cats/\", \"CATs/\" etc. <code>!$-cat</code> Does not end with \"-cat\" <code>?=</code> Is null <code>!?=</code> Is not null"},{"location":"reference/api_query_syntax/#time-range-example","title":"Time range example","text":"<p>For this case we need to combine multiple queries on the same <code>created</code> field using AND semantics (with the <code>[</code>) modifier:</p> <pre><code>?created=[&gt;&gt;2021-01-01T00:00:00Z&amp;created=[&lt;=2021-01-02T00:00:00Z\n</code></pre> <p>So this means:</p> <ul> <li><code>created</code> greater than <code>2021-01-01T00:00:00Z</code></li> <li><code>AND</code></li> <li><code>created</code> less than or equal to <code>2021-01-02T00:00:00Z</code></li> </ul>"},{"location":"reference/blockchain_operation_errors/","title":"Blockchain Operation Errors","text":""},{"location":"reference/blockchain_operation_errors/#blockchain-error-messages","title":"Blockchain Error Messages","text":"<p>The receipt for a FireFly blockchain operation contains an <code>extraInfo</code> section that records additional information about the transaction. For example:</p> <pre><code>\"receipt\": {\n  ...\n  \"extraInfo\": [\n    {\n      {\n        \"contractAddress\":\"0x87ae94ab290932c4e6269648bb47c86978af4436\",\n        \"cumulativeGasUsed\":\"33812\",\n        \"from\":\"0x2b1c769ef5ad304a4889f2a07a6617cd935849ae\",\n        \"to\":\"0x302259069aaa5b10dc6f29a9a3f72a8e52837cc3\",\n        \"gasUsed\":\"33812\",\n        \"status\":\"0\",\n        \"errorMessage\":\"Not enough tokens\", \n      }\n    }\n  ],\n  ...\n},\n</code></pre> <p>The <code>errorMessage</code> field can be be set by a blockchain connector to provide FireFly and the end-user with more information about the reason why a tranasction failed. The blockchain connector can choose what information to include in <code>errorMessage</code> field. It may be set to an error message relating to the blockchain connector itself or an error message passed back from the blockchain or smart contract that was invoked.</p>"},{"location":"reference/blockchain_operation_errors/#default-error-format-with-hyperledger-firefly-13-and-hyperledger-besu-2430","title":"Default Error Format With Hyperledger FireFly 1.3 and Hyperledger Besu 24.3.0","text":"<p>If FireFly is configured to connect to a Besu EVM client, and Besu has been configured with the <code>revert-reason-enabled=true</code> setting (note - the default value for Besu is <code>false</code>) error messages passed to FireFly from the blockchain client itself will be set correctly in the FireFly blockchain operation. For example:</p> <ul> <li><code>\"errorMessage\":\"Not enough tokens\"</code> for a revert error string from a smart contract</li> </ul> <p>If the smart contract uses a custom error type, Besu will return the revert reason to FireFly as a hexadecimal string but FireFly will be unable to decode it into. In this case the blockchain operation error message and return values will be set to:</p> <ul> <li><code>\"errorMessage\":\"FF23053: Error return value for custom error: &lt;revert hex string&gt;</code></li> <li><code>\"returnValue\":\"&lt;revert hex string&gt;\"</code></li> </ul> <p>A future update to FireFly could be made to automatically decode custom error revert reasons if FireFly knows the ABI for the custom error. See FireFly issue 1466 which describes the current limitation.</p> <p>If FireFly is configured to connect to Besu without <code>revert-reason-enabled=true</code> the error message will be set to:</p> <ul> <li><code>\"errorMessage\":\"FF23054: Error return value unavailable\"</code></li> </ul>"},{"location":"reference/blockchain_operation_errors/#error-retrieval-details","title":"Error Retrieval Details","text":"<p>The precise format of the error message in a blockchain operation can vary based on different factors. The sections below describe in detail how the error message is populted, with specific references to the <code>firefly-evmconnect</code> blockchain connector.</p>"},{"location":"reference/blockchain_operation_errors/#format-of-a-firefly-evmconnect-error-message","title":"Format of a <code>firefly-evmconnect</code> Error Message","text":"<p>The following section describes the way that the <code>firefly-evmconnect</code> plugin uses the <code>errorMessage</code> field. This serves both as an explanation of how EVM-based transaction errors will be formatted, and as a guide that other blockchain connectors may decide to follow.</p> <p>The <code>errorMessage</code> field for a <code>firefly-evmconnect</code> transaction may contain one of the following:</p> <ol> <li>An error message from the FireFly blockchain connector</li> <li>For example <code>\"FF23054: Error return value unavailable\"</code></li> <li>A decoded error string from the blockchain transaction</li> <li>For example <code>Not enough tokens</code></li> <li>This could be an error string from a smart contract e.g. <code>require(requestedTokens &lt;= allowance, \"Not enough tokens\");</code></li> <li>An un-decoded byte string from the blockchain transaction</li> <li>For example  <pre><code>FF23053: Error return value for custom error: 0x1320fa6a00000000000000000000000000000000000000000000000000000000000000640000000000000000000000000000000000000000000000000000000000000010\n</code></pre></li> <li>This could be a custom error from a smart contract e.g. <pre><code>error AllowanceTooSmall(uint256 requested, uint256 allowance);\n...\nrevert AllowanceTooSmall({ requested: 100, allowance: 20 });\n</code></pre></li> <li>If an error reason cannot be decoded the <code>returnValue</code> of the <code>extraInfo</code> will be set to the raw byte string. For example: <pre><code>\"receipt\": {\n  ...\n  \"extraInfo\": [\n     {\n       {\n         \"contractAddress\":\"0x87ae94ab290932c4e6269648bb47c86978af4436\",\n         \"cumulativeGasUsed\":\"33812\",\n         \"from\":\"0x2b1c769ef5ad304a4889f2a07a6617cd935849ae\",\n         \"to\":\"0x302259069aaa5b10dc6f29a9a3f72a8e52837cc3\",\n         \"gasUsed\":\"33812\",\n         \"status\":\"0\",\n         \"errorMessage\":\"FF23053: Error return value for custom error: 0x1320fa6a00000000000000000000000000000000000000000000000000000000000000640000000000000000000000000000000000000000000000000000000000000010\", \n         \"returnValue\":\"0x1320fa6a00000000000000000000000000000000000000000000000000000000000000640000000000000000000000000000000000000000000000000000000000000010\"\n       }\n     }\n  ],\n  ...\n},\n</code></pre></li> </ol>"},{"location":"reference/blockchain_operation_errors/#retrieving-evm-blockchain-transaction-errors","title":"Retrieving EVM Blockchain Transaction Errors","text":"<p>The ability of a blockchain connector such as <code>firefly-evmconnect</code> to retrieve the reason for a transaction failure, is dependent on by the configuration of the blockchain it is connected to. For an EVM blockchain the reason why a transaction failed is recorded with the <code>REVERT</code> op code, with a <code>REASON</code> set to the reason for the failure. By default, most EVM clients do not store this reason in the transaction receipt. This is typically to reduce resource consumption such as memory usage in the client. It is usually possible to configure an EVM client to store the revert reason in the transaction receipt. For example Hyperledger Besu\u2122 provides the <code>--revert-reason-enabled</code> configuration option. If the transaction receipt does not contain the revert reason it is possible to request that an EVM client re-run the transaction and return a trace of all of the op-codes, including the final <code>REVERT</code> <code>REASON</code>. This can be a resource intensive request to submit to an EVM client, and is only available on archive nodes or for very recent blocks.</p> <p>The <code>firefly-evmconnect</code> blockchain connector attempts to obtain the reason for a transaction revert and include it in the <code>extraInfo</code> field. It uses the following mechanisms, in this order:</p> <ol> <li>Checks if the blockchain transaction receipt contains the revert reason.</li> <li>If the revert reason is not in the receipt, and the <code>connector.traceTXForRevertReason</code> configuration option is set to <code>true</code>, calls <code>debug_traceTransaction</code> to obtain a full trace of the transaction and extract the revert reason. By default, <code>connector.traceTXForRevertReason</code> is set to <code>false</code> to avoid submitting high-resource requests to the EVM client.</li> </ol> <p>If the revert reason can be obtained using either mechanism above, the revert reason bytes are decoded in the following way:   - Attempts to decode the bytes as the standard <code>Error(string)</code> signature format and includes the decoded string in the <code>errorMessage</code>   - If the reason is not a standard <code>Error(String)</code> error, sets the <code>errorMessage</code> to <code>FF23053: Error return value for custom error: &lt;raw hex string&gt;</code> and includes the raw byte string in the <code>returnValue</code> field.</p>"},{"location":"reference/blockchain_operation_status/","title":"Blockchain Operation Status","text":""},{"location":"reference/blockchain_operation_status/#blockchain-operations","title":"Blockchain Operations","text":"<p>Every FireFly Transaction can involve zero or more Operations. Blockchain operations are handled by the blockchain connector configured for the namespace and represent a blockchain transaction being handled by that connector.</p>"},{"location":"reference/blockchain_operation_status/#blockchain-operation-status_1","title":"Blockchain Operation Status","text":"<p>A blockchain operation can require the connector to go through various stages of processing in order to successfully confirm the transaction on the blockchain. The orchestrator in FireFly receives updates from the connector to indicate when the operation has been completed and determine when the FireFly transaction as a whole has finished. These updates must contain enough information to correlate the operation to the FireFly transaction but it can be useful to see more detailed information about how the transaction was processed.</p> <p>FireFly 1.2 introduced the concept of sub-status types that allow a blockchain connector to distinguish between the intermediate steps involved in progressing a transaction. It also introduced the concept of an action which a connector might carry out in order to progress between types of sub-status. This can be described as a state machine as shown in the following diagram:</p> <p></p> <p>To access detailed information about a blockchain operation FireFly 1.2 introduced a new query parameter, <code>fetchStatus</code>, to the <code>/transaction/{txid}/operation/{opid}</code> API. When FireFly receives an API request that includes the fetchStatus query parameter it makes a synchronous call directly to the blockchain connector, requesting all of blockchain transaction detail it has. This payload is then included in the FireFly operation response under a new <code>detail</code> field.</p>"},{"location":"reference/blockchain_operation_status/#blockchain-operation-example","title":"Blockchain Operation Example","text":"<pre><code>{\n  \"id\": \"04a8b0c4-03c2-4935-85a1-87d17cddc20a\",\n  \"created\": \"2022-05-16T01:23:15Z\",\n  \"namespace\": \"ns1\",\n  \"tx\": \"99543134-769b-42a8-8be4-a5f8873f969d\",\n  \"type\": \"blockchain_invoke\",\n  \"status\": \"Succeeded\",\n  \"plugin\": \"ethereum\",\n  \"input\": {\n    // Input used to initiate the blockchain operation\n  },\n  \"output\": {\n    // Minimal blockchain operation data necessary\n    // to resolve the FF transaction\n  },\n  \"detail\": {\n    // Full blockchain operation information, including sub-status\n    // transitions that took place for the operation to succeed.\n  }\n}\n</code></pre>"},{"location":"reference/blockchain_operation_status/#detail-status-structure","title":"Detail Status Structure","text":"<p>The structure of a blockchain operation follows the structure described in Operations. In FireFly 1.2, 2 new attributes were added to that structure to allow more detailed status information to be recorded:</p> <ul> <li>history an ordered list of status changes that have taken place during processing of the transaction</li> <li>historySummary an un-ordered list any sub-status type that the blockchain connector uses, and any action type that the blockchain connector carries out as part of processing the transaction.</li> </ul> <p>The <code>history</code> field is designed to record an ordered list of sub-status changes that the transaction has gone through. Within each sub-status change are the actions that have been carried out to try and move the transaction on to a new sub-status. Some transactions might spend a long time going looping between different sub-status types so this field records the N most recent sub-status changes (where the size of N is determined by blockchain connector and its configuration). The follow example shows a transaction going starting at <code>Received</code>, moving to <code>Tracking</code>, and finally ending up as <code>Confirmed</code>. In order to move from <code>Received</code> to <code>Tracking</code> several actions were performed: <code>AssignNonce</code>, <code>RetrieveGasPrice</code>, and <code>SubmitTransaction</code>.</p>"},{"location":"reference/blockchain_operation_status/#history-example","title":"History Example","text":"<pre><code>{\n    ...\n    \"lastSubmit\": \"2023-01-27T17:11:41.222375469Z\",\n    \"nonce\": \"14\",\n    \"history\": [\n        {\n            \"subStatus\": \"Received\",\n            \"time\": \"2023-01-27T17:11:41.122965803Z\",\n            \"actions\": [\n                {\n                    \"action\": \"AssignNonce\",\n                    \"count\": 1,\n                    \"lastInfo\": {\n   \u2003                    \"nonce\": \"14\"\n                    },\n                    \"lastOccurrence\": \"2023-01-27T17:11:41.122967219Z\",\n                    \"time\": \"2023-01-27T17:11:41.122967136Z\"\n                },\n   \u2003            {\n                    \"action\": \"RetrieveGasPrice\",\n                    \"count\": 1,\n                    \"lastInfo\": {\n                        \"gasPrice\": \"0\"\n                    },\n                    \"lastOccurrence\": \"2023-01-27T17:11:41.161213303Z\",\n                    \"time\": \"2023-01-27T17:11:41.161213094Z\"\n                },\n                {\n                    \"action\": \"SubmitTransaction\",\n                    \"count\": 1,\n   \u2003                \"lastInfo\": {\n                        \"txHash\": \"0x4c37de1cf320a1d5c949082bbec8ad5fe918e6621cec3948d609ec3f7deac243\"\n                    },\n   \u2003                \"lastOccurrence\": \"2023-01-27T17:11:41.222374636Z\",\n   \u2003                \"time\": \"2023-01-27T17:11:41.222374553Z\"\n   \u2003            }\n   \u2003        ],\n  \u2003     },\n \u2003      {\n \u2003\u2003         \"subStatus\": \"Tracking\",\n            \"time\": \"2023-01-27T17:11:41.222400219Z\",\n    \u2003       \"actions\": [\n   \u2003\u2003\u2003          {\n    \u2003\u2003\u2003\u2003            \"action\": \"ReceiveReceipt\",\n     \u2003\u2003\u2003\u2003           \"count\": 2,\n    \u2003\u2003\u2003\u2003            \"lastInfo\": {\n     \u2003\u2003\u2003\u2003\u2003              \"protocolId\": \"000001265122/000000\"\n    \u2003\u2003\u2003\u2003            },\n    \u2003\u2003\u2003\u2003            \"lastOccurrence\": \"2023-01-27T17:11:57.93120838Z\",\n    \u2003\u2003\u2003\u2003            \"time\": \"2023-01-27T17:11:47.930332625Z\"\n   \u2003\u2003\u2003          },\n   \u2003\u2003\u2003          {\n   \u2003\u2003\u2003\u2003             \"action\": \"Confirm\",\n    \u2003\u2003\u2003\u2003            \"count\": 1,\n    \u2003\u2003\u2003\u2003            \"lastOccurrence\": \"2023-01-27T17:12:02.660275549Z\",\n    \u2003\u2003\u2003\u2003            \"time\": \"2023-01-27T17:12:02.660275382Z\"\n    \u2003\u2003\u2003         }\n   \u2003\u2003       ],\n  \u2003     },\n  \u2003     {\n \u2003\u2003         \"subStatus\": \"Confirmed\",\n  \u2003\u2003        \"time\": \"2023-01-27T17:12:02.660309382Z\",\n  \u2003\u2003        \"actions\": [],\n  \u2003     }\n    ]\n    ...\n}\n</code></pre> <p>Because the <code>history</code> field is a FIFO structure describing the N most recent sub-status changes, some early sub-status changes or actions may be lost over time. For example an action of <code>assignNonce</code> might only happen once when the transaction is first processed by the connector. The <code>historySummary</code> field ensures that a minimal set of information is kept about every single subStatus type and action that has been recorded.</p>"},{"location":"reference/blockchain_operation_status/#history-summary-example","title":"History Summary Example","text":"<pre><code>{\n    ...\n    \"historySummary\": [\n        {\n            \"count\": 1,\n   \u2003        \"firstOccurrence\": \"2023-01-27T17:11:41.122966136Z\",\n            \"lastOccurrence\": \"2023-01-27T17:11:41.122966136Z\",\n   \u2003        \"subStatus\": \"Received\"\n        },\n        {\n            \"count\": 1,\n            \"firstOccurrence\": \"2023-01-27T17:11:41.122967219Z\",\n            \"lastOccurrence\": \"2023-01-27T17:11:41.122967219Z\",\n            \"action\": \"AssignNonce\"\n        },\n        {\n            \"count\": 1,\n            \"firstOccurrence\": \"2023-01-27T17:11:41.161213303Z\",\n            \"lastOccurrence\": \"2023-01-27T17:11:41.161213303Z\",\n            \"action\": \"RetrieveGasPrice\"\n        },\n        {\n            \"count\": 1,\n            \"firstOccurrence\": \"2023-01-27T17:11:41.222374636Z\",\n            \"lastOccurrence\": \"2023-01-27T17:11:41.222374636Z\",\n            \"action\": \"SubmitTransaction\"\n        },\n        {\n  \u2003         \"count\": 1,\n  \u2003         \"firstOccurrence\": \"2023-01-27T17:11:41.222400678Z\",\n            \"lastOccurrence\": \"\",\n  \u2003         \"subStatus\": \"Tracking\"\n        },\n        {\n            \"count\": 1,\n            \"firstOccurrence\": \"2023-01-27T17:11:57.93120838Z\",\n            \"lastOccurrence\": \"2023-01-27T17:11:57.93120838Z\",\n            \"action\": \"ReceiveReceipt\"\n        },\n        {\n            \"count\": 1,\n            \"firstOccurrence\": \"2023-01-27T17:12:02.660309382Z\",\n            \"lastOccurrence\": \"2023-01-27T17:12:02.660309382Z\",\n            \"action\": \"Confirm\"\n        },\n        {\n \u2003          \"count\": 1,\n   \u2003        \"firstOccurrence\": \"2023-01-27T17:12:02.660309757Z\",\n            \"lastOccurrence\": \"2023-01-27T17:12:02.660309757Z\",\n   \u2003        \"subStatus\": \"Confirmed\"\n        }\n    ]\n}\n</code></pre>"},{"location":"reference/blockchain_operation_status/#public-chain-operations","title":"Public Chain Operations","text":"<p>Blockchain transactions submitted to a public chain, for example to Polygon PoS, might take longer and involve more sub-status transitions before being confirmed. One reason for this could be because of gas price fluctuations of the chain. In this case the <code>history</code> for a public blockchain operation might include a large number of <code>subStatus</code> entries. Using the example sub-status values above, a blockchain operation might move from <code>Tracking</code> to <code>Stale</code>, back to <code>Tracking</code>, back to <code>Stale</code> and so on.</p> <p>Below is an example of the <code>history</code> for a public blockchain operation.</p>"},{"location":"reference/blockchain_operation_status/#polygon-example","title":"Polygon Example","text":"<pre><code>{\n    ...\n    \"lastSubmit\": \"2023-01-27T17:11:41.222375469Z\",\n    \"nonce\": \"14\",\n    \"history\": [\n        {\n            \"subStatus\": \"Received\",\n            \"time\": \"2023-01-27T17:11:41.122965803Z\",\n            \"actions\": [\n                {\n                    \"action\": \"AssignNonce\",\n                    \"count\": 1,\n                    \"lastInfo\": {\n   \u2003                    \"nonce\": \"1\"\n                    },\n                    \"lastOccurrence\": \"2023-01-27T17:11:41.122967219Z\",\n                    \"time\": \"2023-01-27T17:11:41.122967136Z\"\n                },\n   \u2003            {\n                    \"action\": \"RetrieveGasPrice\",\n                    \"count\": 1,\n                    \"lastInfo\": {\n                        \"gasPrice\": \"34422243\"\n                    },\n                    \"lastOccurrence\": \"2023-01-27T17:11:41.161213303Z\",\n                    \"time\": \"2023-01-27T17:11:41.161213094Z\"\n                },\n                {\n                    \"action\": \"SubmitTransaction\",\n                    \"count\": 1,\n   \u2003                \"lastInfo\": {\n                        \"txHash\": \"0x83ba5e1cf320a1d5c949082bbec8ae7fe918e6621cec39478609ec3f7deacbdb\"\n                    },\n   \u2003                \"lastOccurrence\": \"2023-01-27T17:11:41.222374636Z\",\n   \u2003                \"time\": \"2023-01-27T17:11:41.222374553Z\"\n   \u2003            }\n   \u2003        ],\n  \u2003     },\n \u2003      {\n \u2003\u2003         \"subStatus\": \"Tracking\",\n            \"time\": \"2023-01-27T17:11:41.222400219Z\",\n    \u2003       \"actions\": [],\n  \u2003     },\n \u2003      {\n \u2003\u2003         \"subStatus\": \"Stale\",\n            \"time\": \"2023-01-27T17:13:21.222100434Z\",\n    \u2003       \"actions\": [\n   \u2003\u2003\u2003          {\n    \u2003\u2003\u2003\u2003            \"action\": \"RetrieveGasPrice\",\n     \u2003\u2003\u2003\u2003           \"count\": 1,\n                    \"lastInfo\": {\n                        \"gasPrice\": \"44436243\"\n                    },\n    \u2003\u2003\u2003\u2003            \"lastOccurrence\": \"2023-01-27T17:13:22.93120838Z\",\n    \u2003\u2003\u2003\u2003            \"time\": \"2023-01-27T17:13:22.93120838Z\"\n   \u2003\u2003\u2003          },\n                {\n                    \"action\": \"SubmitTransaction\",\n                    \"count\": 1,\n   \u2003                \"lastInfo\": {\n                        \"txHash\": \"0x7b3a5e1ccbc0a1d5c949082bbec8ae7fe918e6621cec39478609ec7aea6103d5\"\n                    },\n   \u2003                \"lastOccurrence\": \"2023-01-27T17:13:32.656374637Z\",\n   \u2003                \"time\": \"2023-01-27T17:13:32.656374637Z\"\n   \u2003            }\n   \u2003\u2003       ],\n  \u2003     },\n \u2003      {\n \u2003\u2003         \"subStatus\": \"Tracking\",\n            \"time\": \"2023-01-27T17:13:33.434400219Z\",\n    \u2003       \"actions\": [],\n  \u2003     },\n \u2003      {\n \u2003\u2003         \"subStatus\": \"Stale\",\n            \"time\": \"2023-01-27T17:15:21.222100434Z\",\n    \u2003       \"actions\": [\n   \u2003\u2003\u2003          {\n    \u2003\u2003\u2003\u2003            \"action\": \"RetrieveGasPrice\",\n     \u2003\u2003\u2003\u2003           \"count\": 1,\n                    \"lastInfo\": {\n                        \"gasPrice\": \"52129243\"\n                    },\n    \u2003\u2003\u2003\u2003            \"lastOccurrence\": \"2023-01-27T17:15:22.93120838Z\",\n    \u2003\u2003\u2003\u2003            \"time\": \"2023-01-27T17:15:22.93120838Z\"\n   \u2003\u2003\u2003          },\n                {\n                    \"action\": \"SubmitTransaction\",\n                    \"count\": 1,\n   \u2003                \"lastInfo\": {\n                        \"txHash\": \"0x89995e1ccbc0a1d5c949082bbec8ae7fe918e6621cec39478609ec7a8c64abc\"\n                    },\n   \u2003                \"lastOccurrence\": \"2023-01-27T17:15:32.656374637Z\",\n   \u2003                \"time\": \"2023-01-27T17:15:32.656374637Z\"\n   \u2003            }\n   \u2003\u2003       ],\n  \u2003     },\n \u2003      {\n \u2003\u2003         \"subStatus\": \"Tracking\",\n            \"time\": \"2023-01-27T17:15:33.434400219Z\",\n    \u2003       \"actions\": [\n   \u2003\u2003\u2003          {\n    \u2003\u2003\u2003\u2003            \"action\": \"ReceiveReceipt\",\n     \u2003\u2003\u2003\u2003           \"count\": 1,\n    \u2003\u2003\u2003\u2003            \"lastInfo\": {\n     \u2003\u2003\u2003\u2003\u2003              \"protocolId\": \"000004897621/000000\"\n    \u2003\u2003\u2003\u2003            },\n    \u2003\u2003\u2003\u2003            \"lastOccurrence\": \"2023-01-27T17:15:33.94120833Z\",\n    \u2003\u2003\u2003\u2003            \"time\": \"2023-01-27T17:15:33.94120833Z\"\n   \u2003\u2003\u2003          },\n   \u2003\u2003\u2003          {\n   \u2003\u2003\u2003\u2003             \"action\": \"Confirm\",\n    \u2003\u2003\u2003\u2003            \"count\": 1,\n    \u2003\u2003\u2003\u2003            \"lastOccurrence\": \"2023-01-27T17:16:02.780275549Z\",\n    \u2003\u2003\u2003\u2003            \"time\": \"2023-01-27T17:16:02.780275382Z\"\n    \u2003\u2003\u2003         }\n   \u2003\u2003       ],\n  \u2003     },\n  \u2003     {\n \u2003\u2003         \"subStatus\": \"Confirmed\",\n  \u2003\u2003        \"time\": \"2023-01-27T17:16:03.990309381Z\",\n  \u2003\u2003        \"actions\": [],\n  \u2003     }\n    ]\n    ...\n}\n</code></pre>"},{"location":"reference/config/","title":"Configuration Reference","text":""},{"location":"reference/config/#admin","title":"admin","text":"Key Description Type Default Value enabled Deprecated - use spi.enabled instead <code>boolean</code> <code>&lt;nil&gt;</code>"},{"location":"reference/config/#api","title":"api","text":"Key Description Type Default Value defaultFilterLimit The maximum number of rows to return if no limit is specified on an API request <code>int</code> <code>25</code> dynamicPublicURLHeader Dynamic header that informs the backend the base public URL for the request, in order to build URL links in OpenAPI/SwaggerUI <code>string</code> <code>&lt;nil&gt;</code> maxFilterLimit The largest value of <code>limit</code> that an HTTP client can specify in a request <code>int</code> <code>1000</code> passthroughHeaders A list of HTTP request headers to pass through to dependency microservices <code>[]string</code> <code>[]</code> requestMaxTimeout The maximum amount of time that an HTTP client can specify in a <code>Request-Timeout</code> header to keep a specific request open <code>time.Duration</code> <code>10m</code> requestTimeout The maximum amount of time that a request is allowed to remain open <code>time.Duration</code> <code>120s</code>"},{"location":"reference/config/#assetmanager","title":"asset.manager","text":"Key Description Type Default Value keyNormalization Mechanism to normalize keys before using them. Valid options are <code>blockchain_plugin</code> - use blockchain plugin (default) or <code>none</code> - do not attempt normalization (deprecated - use namespaces.predefined[].asset.manager.keyNormalization) <code>string</code> <code>blockchain_plugin</code>"},{"location":"reference/config/#batchmanager","title":"batch.manager","text":"Key Description Type Default Value minimumPollDelay The minimum time the batch manager waits between polls on the DB - to prevent thrashing <code>time.Duration</code> <code>100ms</code> pollTimeout How long to wait without any notifications of new messages before doing a page query <code>time.Duration</code> <code>30s</code> readPageSize The size of each page of messages read from the database into memory when assembling batches <code>int</code> <code>100</code>"},{"location":"reference/config/#batchretry","title":"batch.retry","text":"Key Description Type Default Value factor The retry backoff factor <code>float32</code> <code>2</code> initDelay The initial retry delay <code>time.Duration</code> <code>250ms</code> maxDelay The maximum retry delay <code>time.Duration</code> <code>30s</code>"},{"location":"reference/config/#blobreceiverretry","title":"blobreceiver.retry","text":"Key Description Type Default Value factor The retry backoff factor <code>float32</code> <code>2</code> initialDelay The initial retry delay <code>time.Duration</code> <code>250ms</code> maxDelay The maximum retry delay <code>time.Duration</code> <code>1m</code>"},{"location":"reference/config/#blobreceiverworker","title":"blobreceiver.worker","text":"Key Description Type Default Value batchMaxInserts The maximum number of items the blob receiver worker will insert in a batch <code>int</code> <code>200</code> batchTimeout The maximum amount of the the blob receiver worker will wait <code>time.Duration</code> <code>50ms</code> count The number of blob receiver workers <code>int</code> <code>5</code>"},{"location":"reference/config/#broadcastbatch","title":"broadcast.batch","text":"Key Description Type Default Value agentTimeout How long to keep around a batching agent for a sending identity before disposal <code>string</code> <code>2m</code> payloadLimit The maximum payload size of a batch for broadcast messages <code>BytesSize</code> <code>800Kb</code> size The maximum number of messages that can be packed into a batch <code>int</code> <code>200</code> timeout The timeout to wait for a batch to fill, before sending <code>time.Duration</code> <code>1s</code>"},{"location":"reference/config/#cache","title":"cache","text":"Key Description Type Default Value enabled Enables caching, defaults to true <code>boolean</code> <code>true</code>"},{"location":"reference/config/#cacheaddressresolver","title":"cache.addressresolver","text":"Key Description Type Default Value limit Max number of cached items for address resolver <code>int</code> <code>1000</code> ttl Time to live of cached items for address resolver <code>string</code> <code>24h</code>"},{"location":"reference/config/#cachebatch","title":"cache.batch","text":"Key Description Type Default Value limit Max number of cached items for batches <code>int</code> <code>100</code> ttl Time to live of cache items for batches <code>string</code> <code>5m</code>"},{"location":"reference/config/#cacheblockchain","title":"cache.blockchain","text":"Key Description Type Default Value limit Max number of cached items for blockchain <code>int</code> <code>100</code> ttl Time to live of cached items for blockchain <code>string</code> <code>5m</code>"},{"location":"reference/config/#cacheblockchainevent","title":"cache.blockchainevent","text":"Key Description Type Default Value limit Max number of cached blockchain events for transactions <code>int</code> <code>1000</code> ttl Time to live of cached blockchain events for transactions <code>string</code> <code>5m</code>"},{"location":"reference/config/#cacheeventlistenertopic","title":"cache.eventlistenertopic","text":"Key Description Type Default Value limit Max number of cached items for blockchain listener topics <code>int</code> <code>100</code> ttl Time to live of cached items for blockchain listener topics <code>string</code> <code>5m</code>"},{"location":"reference/config/#cachegroup","title":"cache.group","text":"Key Description Type Default Value limit Max number of cached items for groups <code>int</code> <code>50</code> ttl Time to live of cached items for groups <code>string</code> <code>1h</code>"},{"location":"reference/config/#cacheidentity","title":"cache.identity","text":"Key Description Type Default Value limit Max number of cached identities for identity manager <code>int</code> <code>100</code> ttl Time to live of cached identities for identity manager <code>string</code> <code>1h</code>"},{"location":"reference/config/#cachemessage","title":"cache.message","text":"Key Description Type Default Value size Max size of cached messages for data manager <code>BytesSize</code> <code>50Mb</code> ttl Time to live of cached messages for data manager <code>string</code> <code>5m</code>"},{"location":"reference/config/#cachemethods","title":"cache.methods","text":"Key Description Type Default Value limit Max number of cached items for schema validations on blockchain methods <code>int</code> <code>200</code> ttl Time to live of cached items for schema validations on blockchain methods <code>string</code> <code>5m</code>"},{"location":"reference/config/#cacheoperations","title":"cache.operations","text":"Key Description Type Default Value limit Max number of cached items for operations <code>int</code> <code>1000</code> ttl Time to live of cached items for operations <code>string</code> <code>5m</code>"},{"location":"reference/config/#cachetokenpool","title":"cache.tokenpool","text":"Key Description Type Default Value limit Max number of cached items for token pools <code>int</code> <code>100</code> ttl Time to live of cached items for token pool <code>string</code> <code>1h</code>"},{"location":"reference/config/#cachetransaction","title":"cache.transaction","text":"Key Description Type Default Value size Max size of cached transactions <code>BytesSize</code> <code>1Mb</code> ttl Time to live of cached transactions <code>string</code> <code>5m</code>"},{"location":"reference/config/#cachevalidator","title":"cache.validator","text":"Key Description Type Default Value size Max size of cached validators for data manager <code>BytesSize</code> <code>1Mb</code> ttl Time to live of cached validators for data manager <code>string</code> <code>1h</code>"},{"location":"reference/config/#config","title":"config","text":"Key Description Type Default Value autoReload Monitor the configuration file for changes, and automatically add/remove/reload namespaces and plugins <code>boolean</code> <code>&lt;nil&gt;</code>"},{"location":"reference/config/#cors","title":"cors","text":"Key Description Type Default Value credentials CORS setting to control whether a browser allows credentials to be sent to this API <code>boolean</code> <code>true</code> debug Whether debug is enabled for the CORS implementation <code>boolean</code> <code>false</code> enabled Whether CORS is enabled <code>boolean</code> <code>true</code> headers CORS setting to control the allowed headers <code>[]string</code> <code>[*]</code> maxAge The maximum age a browser should rely on CORS checks <code>time.Duration</code> <code>600</code> methods CORS setting to control the allowed methods <code>[]string</code> <code>[GET POST PUT PATCH DELETE]</code> origins CORS setting to control the allowed origins <code>[]string</code> <code>[*]</code>"},{"location":"reference/config/#debug","title":"debug","text":"Key Description Type Default Value address The HTTP interface the go debugger binds to <code>string</code> <code>localhost</code> port An HTTP port on which to enable the go debugger <code>int</code> <code>-1</code>"},{"location":"reference/config/#downloadretry","title":"download.retry","text":"Key Description Type Default Value factor The retry backoff factor <code>float32</code> <code>2</code> initialDelay The initial retry delay <code>time.Duration</code> <code>100ms</code> maxAttempts The maximum number attempts <code>int</code> <code>100</code> maxDelay The maximum retry delay <code>time.Duration</code> <code>1m</code>"},{"location":"reference/config/#downloadworker","title":"download.worker","text":"Key Description Type Default Value count The number of download workers <code>int</code> <code>10</code> queueLength The length of the work queue in the channel to the workers - defaults to 2x the worker count <code>int</code> <code>&lt;nil&gt;</code>"},{"location":"reference/config/#eventaggregator","title":"event.aggregator","text":"Key Description Type Default Value batchSize The maximum number of records to read from the DB before performing an aggregation run <code>BytesSize</code> <code>200</code> batchTimeout How long to wait for new events to arrive before performing aggregation on a page of events <code>time.Duration</code> <code>0ms</code> firstEvent The first event the aggregator should process, if no previous offest is stored in the DB. Valid options are <code>oldest</code> or <code>newest</code> <code>string</code> <code>oldest</code> pollTimeout The time to wait without a notification of new events, before trying a select on the table <code>time.Duration</code> <code>30s</code> rewindQueryLimit Safety limit on the maximum number of records to search when performing queries to search for rewinds <code>int</code> <code>1000</code> rewindQueueLength The size of the queue into the rewind dispatcher <code>int</code> <code>10</code> rewindTimeout The minimum time to wait for rewinds to accumulate before resolving them <code>time.Duration</code> <code>50ms</code>"},{"location":"reference/config/#eventaggregatorretry","title":"event.aggregator.retry","text":"Key Description Type Default Value factor The retry backoff factor <code>float32</code> <code>2</code> initDelay The initial retry delay <code>time.Duration</code> <code>100ms</code> maxDelay The maximum retry delay <code>time.Duration</code> <code>30s</code>"},{"location":"reference/config/#eventdbevents","title":"event.dbevents","text":"Key Description Type Default Value bufferSize The size of the buffer of change events <code>BytesSize</code> <code>100</code>"},{"location":"reference/config/#eventdispatcher","title":"event.dispatcher","text":"Key Description Type Default Value batchTimeout A short time to wait for new events to arrive before re-polling for new events <code>time.Duration</code> <code>0ms</code> bufferLength The number of events + attachments an individual dispatcher should hold in memory ready for delivery to the subscription <code>int</code> <code>5</code> pollTimeout The time to wait without a notification of new events, before trying a select on the table <code>time.Duration</code> <code>30s</code>"},{"location":"reference/config/#eventdispatcherretry","title":"event.dispatcher.retry","text":"Key Description Type Default Value factor The retry backoff factor <code>float32</code> <code>&lt;nil&gt;</code> initDelay The initial retry delay <code>time.Duration</code> <code>&lt;nil&gt;</code> maxDelay The maximum retry delay <code>time.Duration</code> <code>&lt;nil&gt;</code>"},{"location":"reference/config/#eventtransports","title":"event.transports","text":"Key Description Type Default Value default The default event transport for new subscriptions <code>string</code> <code>websockets</code> enabled Which event interface plugins are enabled <code>boolean</code> <code>[websockets webhooks]</code>"},{"location":"reference/config/#eventswebhooks","title":"events.webhooks","text":"Key Description Type Default Value connectionTimeout The maximum amount of time that a connection is allowed to remain with no data transmitted <code>time.Duration</code> <code>30s</code> expectContinueTimeout See ExpectContinueTimeout in the Go docs <code>time.Duration</code> <code>1s</code> headers Adds custom headers to HTTP requests <code>map[string]string</code> <code>&lt;nil&gt;</code> idleTimeout The max duration to hold a HTTP keepalive connection between calls <code>time.Duration</code> <code>475ms</code> maxConnsPerHost The max number of connections, per unique hostname. Zero means no limit <code>int</code> <code>0</code> maxIdleConns The max number of idle connections to hold pooled <code>int</code> <code>100</code> passthroughHeadersEnabled Enable passing through the set of allowed HTTP request headers <code>boolean</code> <code>false</code> requestTimeout The maximum amount of time that a request is allowed to remain open <code>time.Duration</code> <code>30s</code> tlsHandshakeTimeout The maximum amount of time to wait for a successful TLS handshake <code>time.Duration</code> <code>10s</code>"},{"location":"reference/config/#eventswebhooksauth","title":"events.webhooks.auth","text":"Key Description Type Default Value password Password <code>string</code> <code>&lt;nil&gt;</code> username Username <code>string</code> <code>&lt;nil&gt;</code>"},{"location":"reference/config/#eventswebhooksproxy","title":"events.webhooks.proxy","text":"Key Description Type Default Value url Optional HTTP proxy server to connect through <code>string</code> <code>&lt;nil&gt;</code>"},{"location":"reference/config/#eventswebhooksretry","title":"events.webhooks.retry","text":"Key Description Type Default Value count The maximum number of times to retry <code>int</code> <code>5</code> enabled Enables retries <code>boolean</code> <code>false</code> errorStatusCodeRegex The regex that the error response status code must match to trigger retry <code>string</code> <code>&lt;nil&gt;</code> initWaitTime The initial retry delay <code>time.Duration</code> <code>250ms</code> maxWaitTime The maximum retry delay <code>time.Duration</code> <code>30s</code>"},{"location":"reference/config/#eventswebhooksthrottle","title":"events.webhooks.throttle","text":"Key Description Type Default Value burst The maximum number of requests that can be made in a short period of time before the throttling kicks in. <code>int</code> <code>&lt;nil&gt;</code> requestsPerSecond The average rate at which requests are allowed to pass through over time. <code>int</code> <code>&lt;nil&gt;</code>"},{"location":"reference/config/#eventswebhookstls","title":"events.webhooks.tls","text":"Key Description Type Default Value ca The TLS certificate authority in PEM format (this option is ignored if caFile is also set) <code>string</code> <code>&lt;nil&gt;</code> caFile The path to the CA file for TLS on this API <code>string</code> <code>&lt;nil&gt;</code> cert The TLS certificate in PEM format (this option is ignored if certFile is also set) <code>string</code> <code>&lt;nil&gt;</code> certFile The path to the certificate file for TLS on this API <code>string</code> <code>&lt;nil&gt;</code> clientAuth Enables or disables client auth for TLS on this API <code>string</code> <code>&lt;nil&gt;</code> enabled Enables or disables TLS on this API <code>boolean</code> <code>false</code> insecureSkipHostVerify When to true in unit test development environments to disable TLS verification. Use with extreme caution <code>boolean</code> <code>&lt;nil&gt;</code> key The TLS certificate key in PEM format (this option is ignored if keyFile is also set) <code>string</code> <code>&lt;nil&gt;</code> keyFile The path to the private key file for TLS on this API <code>string</code> <code>&lt;nil&gt;</code> requiredDNAttributes A set of required subject DN attributes. Each entry is a regular expression, and the subject certificate must have a matching attribute of the specified type (CN, C, O, OU, ST, L, STREET, POSTALCODE, SERIALNUMBER are valid attributes) <code>map[string]string</code> <code>&lt;nil&gt;</code>"},{"location":"reference/config/#eventswebsockets","title":"events.websockets","text":"Key Description Type Default Value readBufferSize WebSocket read buffer size <code>BytesSize</code> <code>16Kb</code> writeBufferSize WebSocket write buffer size <code>BytesSize</code> <code>16Kb</code>"},{"location":"reference/config/#histograms","title":"histograms","text":"Key Description Type Default Value maxChartRows The maximum rows to fetch for each histogram bucket <code>int</code> <code>100</code>"},{"location":"reference/config/#http","title":"http","text":"Key Description Type Default Value address The IP address on which the HTTP API should listen IP Address <code>string</code> <code>127.0.0.1</code> port The port on which the HTTP API should listen <code>int</code> <code>5000</code> publicURL The fully qualified public URL for the API. This is used for building URLs in HTTP responses and in OpenAPI Spec generation URL <code>string</code> <code>&lt;nil&gt;</code> readTimeout The maximum time to wait when reading from an HTTP connection <code>time.Duration</code> <code>15s</code> shutdownTimeout The maximum amount of time to wait for any open HTTP requests to finish before shutting down the HTTP server <code>time.Duration</code> <code>10s</code> writeTimeout The maximum time to wait when writing to an HTTP connection <code>time.Duration</code> <code>15s</code>"},{"location":"reference/config/#httpauth","title":"http.auth","text":"Key Description Type Default Value type The auth plugin to use for server side authentication of requests <code>string</code> <code>&lt;nil&gt;</code>"},{"location":"reference/config/#httpauthbasic","title":"http.auth.basic","text":"Key Description Type Default Value passwordfile The path to a .htpasswd file to use for authenticating requests. Passwords should be hashed with bcrypt. <code>string</code> <code>&lt;nil&gt;</code>"},{"location":"reference/config/#httptls","title":"http.tls","text":"Key Description Type Default Value ca The TLS certificate authority in PEM format (this option is ignored if caFile is also set) <code>string</code> <code>&lt;nil&gt;</code> caFile The path to the CA file for TLS on this API <code>string</code> <code>&lt;nil&gt;</code> cert The TLS certificate in PEM format (this option is ignored if certFile is also set) <code>string</code> <code>&lt;nil&gt;</code> certFile The path to the certificate file for TLS on this API <code>string</code> <code>&lt;nil&gt;</code> clientAuth Enables or disables client auth for TLS on this API <code>string</code> <code>&lt;nil&gt;</code> enabled Enables or disables TLS on this API <code>boolean</code> <code>false</code> insecureSkipHostVerify When to true in unit test development environments to disable TLS verification. Use with extreme caution <code>boolean</code> <code>&lt;nil&gt;</code> key The TLS certificate key in PEM format (this option is ignored if keyFile is also set) <code>string</code> <code>&lt;nil&gt;</code> keyFile The path to the private key file for TLS on this API <code>string</code> <code>&lt;nil&gt;</code> requiredDNAttributes A set of required subject DN attributes. Each entry is a regular expression, and the subject certificate must have a matching attribute of the specified type (CN, C, O, OU, ST, L, STREET, POSTALCODE, SERIALNUMBER are valid attributes) <code>map[string]string</code> <code>&lt;nil&gt;</code>"},{"location":"reference/config/#log","title":"log","text":"Key Description Type Default Value compress Determines if the rotated log files should be compressed using gzip <code>boolean</code> <code>&lt;nil&gt;</code> filename Filename is the file to write logs to.  Backup log files will be retained in the same directory <code>string</code> <code>&lt;nil&gt;</code> filesize MaxSize is the maximum size the log file before it gets rotated <code>BytesSize</code> <code>100m</code> forceColor Force color to be enabled, even when a non-TTY output is detected <code>boolean</code> <code>&lt;nil&gt;</code> includeCodeInfo Enables the report caller for including the calling file and line number, and the calling function. If using text logs, it uses the logrus text format rather than the default prefix format. <code>boolean</code> <code>false</code> level The log level - error, warn, info, debug, trace <code>string</code> <code>info</code> maxAge The maximum time to retain old log files based on the timestamp encoded in their filename <code>time.Duration</code> <code>24h</code> maxBackups Maximum number of old log files to retain <code>int</code> <code>2</code> noColor Force color to be disabled, event when TTY output is detected <code>boolean</code> <code>&lt;nil&gt;</code> timeFormat Custom time format for logs Time format <code>string</code> <code>2006-01-02T15:04:05.000Z07:00</code> utc Use UTC timestamps for logs <code>boolean</code> <code>false</code>"},{"location":"reference/config/#logjson","title":"log.json","text":"Key Description Type Default Value enabled Enables JSON formatted logs rather than text. All log color settings are ignored when enabled. <code>boolean</code> <code>false</code>"},{"location":"reference/config/#logjsonfields","title":"log.json.fields","text":"Key Description Type Default Value file configures the JSON key containing the calling file <code>string</code> <code>file</code> func Configures the JSON key containing the calling function <code>string</code> <code>func</code> level Configures the JSON key containing the log level <code>string</code> <code>level</code> message Configures the JSON key containing the log message <code>string</code> <code>message</code> timestamp Configures the JSON key containing the timestamp of the log <code>string</code> <code>@timestamp</code>"},{"location":"reference/config/#messagewriter","title":"message.writer","text":"Key Description Type Default Value batchMaxInserts The maximum number of database inserts to include when writing a single batch of messages + data <code>int</code> <code>200</code> batchTimeout How long to wait for more messages to arrive before flushing the batch <code>time.Duration</code> <code>10ms</code> count The number of message writer workers <code>int</code> <code>5</code>"},{"location":"reference/config/#metrics","title":"metrics","text":"Key Description Type Default Value address The IP address on which the metrics HTTP API should listen <code>int</code> <code>127.0.0.1</code> enabled Enables the metrics API <code>boolean</code> <code>true</code> path The path from which to serve the Prometheus metrics <code>string</code> <code>/metrics</code> port The port on which the metrics HTTP API should listen <code>int</code> <code>6000</code> publicURL The fully qualified public URL for the metrics API. This is used for building URLs in HTTP responses and in OpenAPI Spec generation URL <code>string</code> <code>&lt;nil&gt;</code> readTimeout The maximum time to wait when reading from an HTTP connection <code>time.Duration</code> <code>15s</code> shutdownTimeout The maximum amount of time to wait for any open HTTP requests to finish before shutting down the HTTP server <code>time.Duration</code> <code>10s</code> writeTimeout The maximum time to wait when writing to an HTTP connection <code>time.Duration</code> <code>15s</code>"},{"location":"reference/config/#metricsauth","title":"metrics.auth","text":"Key Description Type Default Value type The auth plugin to use for server side authentication of requests <code>string</code> <code>&lt;nil&gt;</code>"},{"location":"reference/config/#metricsauthbasic","title":"metrics.auth.basic","text":"Key Description Type Default Value passwordfile The path to a .htpasswd file to use for authenticating requests. Passwords should be hashed with bcrypt. <code>string</code> <code>&lt;nil&gt;</code>"},{"location":"reference/config/#metricstls","title":"metrics.tls","text":"Key Description Type Default Value ca The TLS certificate authority in PEM format (this option is ignored if caFile is also set) <code>string</code> <code>&lt;nil&gt;</code> caFile The path to the CA file for TLS on this API <code>string</code> <code>&lt;nil&gt;</code> cert The TLS certificate in PEM format (this option is ignored if certFile is also set) <code>string</code> <code>&lt;nil&gt;</code> certFile The path to the certificate file for TLS on this API <code>string</code> <code>&lt;nil&gt;</code> clientAuth Enables or disables client auth for TLS on this API <code>string</code> <code>&lt;nil&gt;</code> enabled Enables or disables TLS on this API <code>boolean</code> <code>false</code> insecureSkipHostVerify When to true in unit test development environments to disable TLS verification. Use with extreme caution <code>boolean</code> <code>&lt;nil&gt;</code> key The TLS certificate key in PEM format (this option is ignored if keyFile is also set) <code>string</code> <code>&lt;nil&gt;</code> keyFile The path to the private key file for TLS on this API <code>string</code> <code>&lt;nil&gt;</code> requiredDNAttributes A set of required subject DN attributes. Each entry is a regular expression, and the subject certificate must have a matching attribute of the specified type (CN, C, O, OU, ST, L, STREET, POSTALCODE, SERIALNUMBER are valid attributes) <code>map[string]string</code> <code>&lt;nil&gt;</code>"},{"location":"reference/config/#namespaces","title":"namespaces","text":"Key Description Type Default Value default The default namespace - must be in the predefined list <code>string</code> <code>default</code> predefined A list of namespaces to ensure exists, without requiring a broadcast from the network List <code>string</code> <code>&lt;nil&gt;</code>"},{"location":"reference/config/#namespacespredefined","title":"namespaces.predefined[]","text":"Key Description Type Default Value defaultKey A default signing key for blockchain transactions within this namespace <code>string</code> <code>&lt;nil&gt;</code> description A description for the namespace <code>string</code> <code>&lt;nil&gt;</code> name The name of the namespace (must be unique) <code>string</code> <code>&lt;nil&gt;</code> plugins The list of plugins for this namespace <code>string</code> <code>&lt;nil&gt;</code>"},{"location":"reference/config/#namespacespredefinedassetmanager","title":"namespaces.predefined[].asset.manager","text":"Key Description Type Default Value keyNormalization Mechanism to normalize keys before using them. Valid options are <code>blockchain_plugin</code> - use blockchain plugin (default) or <code>none</code> - do not attempt normalization <code>string</code> <code>&lt;nil&gt;</code>"},{"location":"reference/config/#namespacespredefinedmultiparty","title":"namespaces.predefined[].multiparty","text":"Key Description Type Default Value enabled Enables multi-party mode for this namespace (defaults to true if an org name or key is configured, either here or at the root level) <code>boolean</code> <code>&lt;nil&gt;</code> networknamespace The shared namespace name to be sent in multiparty messages, if it differs from the local namespace name <code>string</code> <code>&lt;nil&gt;</code>"},{"location":"reference/config/#namespacespredefinedmultipartycontract","title":"namespaces.predefined[].multiparty.contract[]","text":"Key Description Type Default Value firstEvent The first event the contract should process. Valid options are <code>oldest</code> or <code>newest</code> <code>string</code> <code>&lt;nil&gt;</code> location A blockchain-specific contract location. For example, an Ethereum contract address, or a Fabric chaincode name and channel <code>string</code> <code>&lt;nil&gt;</code> options Blockchain-specific contract options <code>string</code> <code>&lt;nil&gt;</code>"},{"location":"reference/config/#namespacespredefinedmultipartynode","title":"namespaces.predefined[].multiparty.node","text":"Key Description Type Default Value description A description for the node in this namespace <code>string</code> <code>&lt;nil&gt;</code> name The node name for this namespace <code>string</code> <code>&lt;nil&gt;</code>"},{"location":"reference/config/#namespacespredefinedmultipartyorg","title":"namespaces.predefined[].multiparty.org","text":"Key Description Type Default Value description A description for the local root organization within this namespace <code>string</code> <code>&lt;nil&gt;</code> key The signing key allocated to the root organization within this namespace <code>string</code> <code>&lt;nil&gt;</code> name A short name for the local root organization within this namespace <code>string</code> <code>&lt;nil&gt;</code>"},{"location":"reference/config/#namespacespredefinedtlsconfigs","title":"namespaces.predefined[].tlsConfigs[]","text":"Key Description Type Default Value name Name of the TLS Config <code>string</code> <code>&lt;nil&gt;</code>"},{"location":"reference/config/#namespacespredefinedtlsconfigstls","title":"namespaces.predefined[].tlsConfigs[].tls","text":"Key Description Type Default Value ca The TLS certificate authority in PEM format (this option is ignored if caFile is also set) <code>string</code> <code>&lt;nil&gt;</code> caFile The path to the CA file for TLS on this API <code>string</code> <code>&lt;nil&gt;</code> cert The TLS certificate in PEM format (this option is ignored if certFile is also set) <code>string</code> <code>&lt;nil&gt;</code> certFile The path to the certificate file for TLS on this API <code>string</code> <code>&lt;nil&gt;</code> clientAuth Enables or disables client auth for TLS on this API <code>string</code> <code>&lt;nil&gt;</code> enabled Enables or disables TLS on this API <code>boolean</code> <code>false</code> insecureSkipHostVerify When to true in unit test development environments to disable TLS verification. Use with extreme caution <code>boolean</code> <code>&lt;nil&gt;</code> key The TLS certificate key in PEM format (this option is ignored if keyFile is also set) <code>string</code> <code>&lt;nil&gt;</code> keyFile The path to the private key file for TLS on this API <code>string</code> <code>&lt;nil&gt;</code> requiredDNAttributes A set of required subject DN attributes. Each entry is a regular expression, and the subject certificate must have a matching attribute of the specified type (CN, C, O, OU, ST, L, STREET, POSTALCODE, SERIALNUMBER are valid attributes) <code>map[string]string</code> <code>&lt;nil&gt;</code>"},{"location":"reference/config/#namespacesretry","title":"namespaces.retry","text":"Key Description Type Default Value factor The retry backoff factor <code>float32</code> <code>2</code> initDelay The initial retry delay <code>time.Duration</code> <code>5s</code> maxDelay The maximum retry delay <code>time.Duration</code> <code>1m</code>"},{"location":"reference/config/#node","title":"node","text":"Key Description Type Default Value description The description of this FireFly node <code>string</code> <code>&lt;nil&gt;</code> name The name of this FireFly node <code>string</code> <code>&lt;nil&gt;</code>"},{"location":"reference/config/#opupdateretry","title":"opupdate.retry","text":"Key Description Type Default Value factor The retry backoff factor <code>float32</code> <code>2</code> initialDelay The initial retry delay <code>time.Duration</code> <code>250ms</code> maxDelay The maximum retry delay <code>time.Duration</code> <code>1m</code>"},{"location":"reference/config/#opupdateworker","title":"opupdate.worker","text":"Key Description Type Default Value batchMaxInserts The maximum number of database inserts to include when writing a single batch of messages + data <code>int</code> <code>200</code> batchTimeout How long to wait for more messages to arrive before flushing the batch <code>time.Duration</code> <code>50ms</code> count The number of operation update works <code>int</code> <code>5</code> queueLength The size of the queue for the Operation Update worker <code>int</code> <code>50</code>"},{"location":"reference/config/#orchestrator","title":"orchestrator","text":"Key Description Type Default Value startupAttempts The number of times to attempt to connect to core infrastructure on startup <code>string</code> <code>5</code>"},{"location":"reference/config/#org","title":"org","text":"Key Description Type Default Value description A description of the organization to which this FireFly node belongs (deprecated - should be set on each multi-party namespace instead) <code>string</code> <code>&lt;nil&gt;</code> key The signing key allocated to the organization (deprecated - should be set on each multi-party namespace instead) <code>string</code> <code>&lt;nil&gt;</code> name The name of the organization to which this FireFly node belongs (deprecated - should be set on each multi-party namespace instead) <code>string</code> <code>&lt;nil&gt;</code>"},{"location":"reference/config/#plugins","title":"plugins","text":"Key Description Type Default Value auth Authorization plugin configuration <code>map[string]string</code> <code>&lt;nil&gt;</code> blockchain The list of configured Blockchain plugins <code>string</code> <code>&lt;nil&gt;</code> database The list of configured Database plugins <code>string</code> <code>&lt;nil&gt;</code> dataexchange The array of configured Data Exchange plugins <code>string</code> <code>&lt;nil&gt;</code> identity The list of available Identity plugins <code>string</code> <code>&lt;nil&gt;</code> sharedstorage The list of configured Shared Storage plugins <code>string</code> <code>&lt;nil&gt;</code> tokens The token plugin configurations <code>string</code> <code>&lt;nil&gt;</code>"},{"location":"reference/config/#pluginsauth","title":"plugins.auth[]","text":"Key Description Type Default Value name The name of the auth plugin to use <code>string</code> <code>&lt;nil&gt;</code> type The type of the auth plugin to use <code>string</code> <code>&lt;nil&gt;</code>"},{"location":"reference/config/#pluginsauthbasic","title":"plugins.auth[].basic","text":"Key Description Type Default Value passwordfile The path to a .htpasswd file to use for authenticating requests. Passwords should be hashed with bcrypt. <code>string</code> <code>&lt;nil&gt;</code>"},{"location":"reference/config/#pluginsblockchain","title":"plugins.blockchain[]","text":"Key Description Type Default Value name The name of the configured Blockchain plugin <code>string</code> <code>&lt;nil&gt;</code> type The type of the configured Blockchain Connector plugin <code>string</code> <code>&lt;nil&gt;</code>"},{"location":"reference/config/#pluginsblockchainethereumaddressresolver","title":"plugins.blockchain[].ethereum.addressResolver","text":"Key Description Type Default Value alwaysResolve Causes the address resolver to be invoked on every API call that submits a signing key, regardless of whether the input string conforms to an 0x address. Also disables any result caching <code>boolean</code> <code>&lt;nil&gt;</code> bodyTemplate The body go template string to use when making HTTP requests. The template input contains '.Key' and '.Intent' string variables. Go Template <code>string</code> <code>&lt;nil&gt;</code> connectionTimeout The maximum amount of time that a connection is allowed to remain with no data transmitted <code>time.Duration</code> <code>30s</code> expectContinueTimeout See ExpectContinueTimeout in the Go docs <code>time.Duration</code> <code>1s</code> headers Adds custom headers to HTTP requests <code>string</code> <code>&lt;nil&gt;</code> idleTimeout The max duration to hold a HTTP keepalive connection between calls <code>time.Duration</code> <code>475ms</code> maxConnsPerHost The max number of connections, per unique hostname. Zero means no limit <code>int</code> <code>0</code> maxIdleConns The max number of idle connections to hold pooled <code>int</code> <code>100</code> method The HTTP method to use when making requests to the Address Resolver <code>string</code> <code>GET</code> passthroughHeadersEnabled Enable passing through the set of allowed HTTP request headers <code>boolean</code> <code>false</code> requestTimeout The maximum amount of time that a request is allowed to remain open <code>time.Duration</code> <code>30s</code> responseField The name of a JSON field that is provided in the response, that contains the ethereum address (default <code>address</code>) <code>string</code> <code>address</code> retainOriginal When true the original pre-resolved string is retained after the lookup, and passed down to Ethconnect as the from address <code>boolean</code> <code>&lt;nil&gt;</code> tlsHandshakeTimeout The maximum amount of time to wait for a successful TLS handshake <code>time.Duration</code> <code>10s</code> url The URL of the Address Resolver <code>string</code> <code>&lt;nil&gt;</code> urlTemplate The URL Go template string to use when calling the Address Resolver. The template input contains '.Key' and '.Intent' string variables. Go Template <code>string</code> <code>&lt;nil&gt;</code>"},{"location":"reference/config/#pluginsblockchainethereumaddressresolverauth","title":"plugins.blockchain[].ethereum.addressResolver.auth","text":"Key Description Type Default Value password Password <code>string</code> <code>&lt;nil&gt;</code> username Username <code>string</code> <code>&lt;nil&gt;</code>"},{"location":"reference/config/#pluginsblockchainethereumaddressresolverproxy","title":"plugins.blockchain[].ethereum.addressResolver.proxy","text":"Key Description Type Default Value url Optional HTTP proxy server to use when connecting to the Address Resolver URL <code>string</code> <code>&lt;nil&gt;</code>"},{"location":"reference/config/#pluginsblockchainethereumaddressresolverretry","title":"plugins.blockchain[].ethereum.addressResolver.retry","text":"Key Description Type Default Value count The maximum number of times to retry <code>int</code> <code>5</code> enabled Enables retries <code>boolean</code> <code>false</code> errorStatusCodeRegex The regex that the error response status code must match to trigger retry <code>string</code> <code>&lt;nil&gt;</code> initWaitTime The initial retry delay <code>time.Duration</code> <code>250ms</code> maxWaitTime The maximum retry delay <code>time.Duration</code> <code>30s</code>"},{"location":"reference/config/#pluginsblockchainethereumaddressresolverthrottle","title":"plugins.blockchain[].ethereum.addressResolver.throttle","text":"Key Description Type Default Value burst The maximum number of requests that can be made in a short period of time before the throttling kicks in. <code>int</code> <code>&lt;nil&gt;</code> requestsPerSecond The average rate at which requests are allowed to pass through over time. <code>int</code> <code>&lt;nil&gt;</code>"},{"location":"reference/config/#pluginsblockchainethereumaddressresolvertls","title":"plugins.blockchain[].ethereum.addressResolver.tls","text":"Key Description Type Default Value ca The TLS certificate authority in PEM format (this option is ignored if caFile is also set) <code>string</code> <code>&lt;nil&gt;</code> caFile The path to the CA file for TLS on this API <code>string</code> <code>&lt;nil&gt;</code> cert The TLS certificate in PEM format (this option is ignored if certFile is also set) <code>string</code> <code>&lt;nil&gt;</code> certFile The path to the certificate file for TLS on this API <code>string</code> <code>&lt;nil&gt;</code> clientAuth Enables or disables client auth for TLS on this API <code>string</code> <code>&lt;nil&gt;</code> enabled Enables or disables TLS on this API <code>boolean</code> <code>false</code> insecureSkipHostVerify When to true in unit test development environments to disable TLS verification. Use with extreme caution <code>boolean</code> <code>&lt;nil&gt;</code> key The TLS certificate key in PEM format (this option is ignored if keyFile is also set) <code>string</code> <code>&lt;nil&gt;</code> keyFile The path to the private key file for TLS on this API <code>string</code> <code>&lt;nil&gt;</code> requiredDNAttributes A set of required subject DN attributes. Each entry is a regular expression, and the subject certificate must have a matching attribute of the specified type (CN, C, O, OU, ST, L, STREET, POSTALCODE, SERIALNUMBER are valid attributes) <code>map[string]string</code> <code>&lt;nil&gt;</code>"},{"location":"reference/config/#pluginsblockchainethereumethconnect","title":"plugins.blockchain[].ethereum.ethconnect","text":"Key Description Type Default Value batchSize The number of events Ethconnect should batch together for delivery to FireFly core. Only applies when automatically creating a new event stream <code>int</code> <code>50</code> batchTimeout How long Ethconnect should wait for new events to arrive and fill a batch, before sending the batch to FireFly core. Only applies when automatically creating a new event stream <code>time.Duration</code> <code>500</code> connectionTimeout The maximum amount of time that a connection is allowed to remain with no data transmitted <code>time.Duration</code> <code>30s</code> expectContinueTimeout See ExpectContinueTimeout in the Go docs <code>time.Duration</code> <code>1s</code> fromBlock The first event this FireFly instance should listen to from the BatchPin smart contract. Default=0. Only affects initial creation of the event stream Address <code>string</code> <code>0</code> headers Adds custom headers to HTTP requests <code>map[string]string</code> <code>&lt;nil&gt;</code> idleTimeout The max duration to hold a HTTP keepalive connection between calls <code>time.Duration</code> <code>475ms</code> instance The Ethereum address of the FireFly BatchPin smart contract that has been deployed to the blockchain Address <code>string</code> <code>&lt;nil&gt;</code> maxConnsPerHost The max number of connections, per unique hostname. Zero means no limit <code>int</code> <code>0</code> maxIdleConns The max number of idle connections to hold pooled <code>int</code> <code>100</code> passthroughHeadersEnabled Enable passing through the set of allowed HTTP request headers <code>boolean</code> <code>false</code> prefixLong The prefix that will be used for Ethconnect specific HTTP headers when FireFly makes requests to Ethconnect <code>string</code> <code>firefly</code> prefixShort The prefix that will be used for Ethconnect specific query parameters when FireFly makes requests to Ethconnect <code>string</code> <code>fly</code> requestTimeout The maximum amount of time that a request is allowed to remain open <code>time.Duration</code> <code>30s</code> tlsHandshakeTimeout The maximum amount of time to wait for a successful TLS handshake <code>time.Duration</code> <code>10s</code> topic The websocket listen topic that the node should register on, which is important if there are multiple nodes using a single ethconnect <code>string</code> <code>&lt;nil&gt;</code> url The URL of the Ethconnect instance URL <code>string</code> <code>&lt;nil&gt;</code>"},{"location":"reference/config/#pluginsblockchainethereumethconnectauth","title":"plugins.blockchain[].ethereum.ethconnect.auth","text":"Key Description Type Default Value password Password <code>string</code> <code>&lt;nil&gt;</code> username Username <code>string</code> <code>&lt;nil&gt;</code>"},{"location":"reference/config/#pluginsblockchainethereumethconnectbackgroundstart","title":"plugins.blockchain[].ethereum.ethconnect.backgroundStart","text":"Key Description Type Default Value enabled Start the Ethconnect plugin in the background and enter retry loop if failed to start <code>boolean</code> <code>&lt;nil&gt;</code> factor Set the factor by which the delay increases when retrying <code>float32</code> <code>2</code> initialDelay Delay between restarts in the case where we retry to restart the ethereum plugin <code>time.Duration</code> <code>5s</code> maxDelay Max delay between restarts in the case where we retry to restart the ethereum plugin <code>time.Duration</code> <code>1m</code>"},{"location":"reference/config/#pluginsblockchainethereumethconnectproxy","title":"plugins.blockchain[].ethereum.ethconnect.proxy","text":"Key Description Type Default Value url Optional HTTP proxy server to use when connecting to Ethconnect URL <code>string</code> <code>&lt;nil&gt;</code>"},{"location":"reference/config/#pluginsblockchainethereumethconnectretry","title":"plugins.blockchain[].ethereum.ethconnect.retry","text":"Key Description Type Default Value count The maximum number of times to retry <code>int</code> <code>5</code> enabled Enables retries <code>boolean</code> <code>false</code> errorStatusCodeRegex The regex that the error response status code must match to trigger retry <code>string</code> <code>&lt;nil&gt;</code> initWaitTime The initial retry delay <code>time.Duration</code> <code>250ms</code> maxWaitTime The maximum retry delay <code>time.Duration</code> <code>30s</code>"},{"location":"reference/config/#pluginsblockchainethereumethconnectthrottle","title":"plugins.blockchain[].ethereum.ethconnect.throttle","text":"Key Description Type Default Value burst The maximum number of requests that can be made in a short period of time before the throttling kicks in. <code>int</code> <code>&lt;nil&gt;</code> requestsPerSecond The average rate at which requests are allowed to pass through over time. <code>int</code> <code>&lt;nil&gt;</code>"},{"location":"reference/config/#pluginsblockchainethereumethconnecttls","title":"plugins.blockchain[].ethereum.ethconnect.tls","text":"Key Description Type Default Value ca The TLS certificate authority in PEM format (this option is ignored if caFile is also set) <code>string</code> <code>&lt;nil&gt;</code> caFile The path to the CA file for TLS on this API <code>string</code> <code>&lt;nil&gt;</code> cert The TLS certificate in PEM format (this option is ignored if certFile is also set) <code>string</code> <code>&lt;nil&gt;</code> certFile The path to the certificate file for TLS on this API <code>string</code> <code>&lt;nil&gt;</code> clientAuth Enables or disables client auth for TLS on this API <code>string</code> <code>&lt;nil&gt;</code> enabled Enables or disables TLS on this API <code>boolean</code> <code>false</code> insecureSkipHostVerify When to true in unit test development environments to disable TLS verification. Use with extreme caution <code>boolean</code> <code>&lt;nil&gt;</code> key The TLS certificate key in PEM format (this option is ignored if keyFile is also set) <code>string</code> <code>&lt;nil&gt;</code> keyFile The path to the private key file for TLS on this API <code>string</code> <code>&lt;nil&gt;</code> requiredDNAttributes A set of required subject DN attributes. Each entry is a regular expression, and the subject certificate must have a matching attribute of the specified type (CN, C, O, OU, ST, L, STREET, POSTALCODE, SERIALNUMBER are valid attributes) <code>map[string]string</code> <code>&lt;nil&gt;</code>"},{"location":"reference/config/#pluginsblockchainethereumethconnectws","title":"plugins.blockchain[].ethereum.ethconnect.ws","text":"Key Description Type Default Value connectionTimeout The amount of time to wait while establishing a connection (or auto-reconnection) <code>time.Duration</code> <code>45s</code> heartbeatInterval The amount of time to wait between heartbeat signals on the WebSocket connection <code>time.Duration</code> <code>30s</code> initialConnectAttempts The number of attempts FireFly will make to connect to the WebSocket when starting up, before failing <code>int</code> <code>5</code> path The WebSocket sever URL to which FireFly should connect WebSocket URL <code>string</code> <code>&lt;nil&gt;</code> readBufferSize The size in bytes of the read buffer for the WebSocket connection <code>BytesSize</code> <code>16Kb</code> url URL to use for WebSocket - overrides url one level up (in the HTTP config) <code>string</code> <code>&lt;nil&gt;</code> writeBufferSize The size in bytes of the write buffer for the WebSocket connection <code>BytesSize</code> <code>16Kb</code>"},{"location":"reference/config/#pluginsblockchainethereumfftm","title":"plugins.blockchain[].ethereum.fftm","text":"Key Description Type Default Value connectionTimeout The maximum amount of time that a connection is allowed to remain with no data transmitted <code>time.Duration</code> <code>30s</code> expectContinueTimeout See ExpectContinueTimeout in the Go docs <code>time.Duration</code> <code>1s</code> headers Adds custom headers to HTTP requests <code>map[string]string</code> <code>&lt;nil&gt;</code> idleTimeout The max duration to hold a HTTP keepalive connection between calls <code>time.Duration</code> <code>475ms</code> maxConnsPerHost The max number of connections, per unique hostname. Zero means no limit <code>int</code> <code>0</code> maxIdleConns The max number of idle connections to hold pooled <code>int</code> <code>100</code> passthroughHeadersEnabled Enable passing through the set of allowed HTTP request headers <code>boolean</code> <code>false</code> requestTimeout The maximum amount of time that a request is allowed to remain open <code>time.Duration</code> <code>30s</code> tlsHandshakeTimeout The maximum amount of time to wait for a successful TLS handshake <code>time.Duration</code> <code>10s</code> url The URL of the FireFly Transaction Manager runtime, if enabled <code>string</code> <code>&lt;nil&gt;</code>"},{"location":"reference/config/#pluginsblockchainethereumfftmauth","title":"plugins.blockchain[].ethereum.fftm.auth","text":"Key Description Type Default Value password Password <code>string</code> <code>&lt;nil&gt;</code> username Username <code>string</code> <code>&lt;nil&gt;</code>"},{"location":"reference/config/#pluginsblockchainethereumfftmproxy","title":"plugins.blockchain[].ethereum.fftm.proxy","text":"Key Description Type Default Value url Optional HTTP proxy server to use when connecting to the Transaction Manager <code>string</code> <code>&lt;nil&gt;</code>"},{"location":"reference/config/#pluginsblockchainethereumfftmretry","title":"plugins.blockchain[].ethereum.fftm.retry","text":"Key Description Type Default Value count The maximum number of times to retry <code>int</code> <code>5</code> enabled Enables retries <code>boolean</code> <code>false</code> errorStatusCodeRegex The regex that the error response status code must match to trigger retry <code>string</code> <code>&lt;nil&gt;</code> initWaitTime The initial retry delay <code>time.Duration</code> <code>250ms</code> maxWaitTime The maximum retry delay <code>time.Duration</code> <code>30s</code>"},{"location":"reference/config/#pluginsblockchainethereumfftmthrottle","title":"plugins.blockchain[].ethereum.fftm.throttle","text":"Key Description Type Default Value burst The maximum number of requests that can be made in a short period of time before the throttling kicks in. <code>int</code> <code>&lt;nil&gt;</code> requestsPerSecond The average rate at which requests are allowed to pass through over time. <code>int</code> <code>&lt;nil&gt;</code>"},{"location":"reference/config/#pluginsblockchainethereumfftmtls","title":"plugins.blockchain[].ethereum.fftm.tls","text":"Key Description Type Default Value ca The TLS certificate authority in PEM format (this option is ignored if caFile is also set) <code>string</code> <code>&lt;nil&gt;</code> caFile The path to the CA file for TLS on this API <code>string</code> <code>&lt;nil&gt;</code> cert The TLS certificate in PEM format (this option is ignored if certFile is also set) <code>string</code> <code>&lt;nil&gt;</code> certFile The path to the certificate file for TLS on this API <code>string</code> <code>&lt;nil&gt;</code> clientAuth Enables or disables client auth for TLS on this API <code>string</code> <code>&lt;nil&gt;</code> enabled Enables or disables TLS on this API <code>boolean</code> <code>false</code> insecureSkipHostVerify When to true in unit test development environments to disable TLS verification. Use with extreme caution <code>boolean</code> <code>&lt;nil&gt;</code> key The TLS certificate key in PEM format (this option is ignored if keyFile is also set) <code>string</code> <code>&lt;nil&gt;</code> keyFile The path to the private key file for TLS on this API <code>string</code> <code>&lt;nil&gt;</code> requiredDNAttributes A set of required subject DN attributes. Each entry is a regular expression, and the subject certificate must have a matching attribute of the specified type (CN, C, O, OU, ST, L, STREET, POSTALCODE, SERIALNUMBER are valid attributes) <code>map[string]string</code> <code>&lt;nil&gt;</code>"},{"location":"reference/config/#pluginsblockchainfabricfabconnect","title":"plugins.blockchain[].fabric.fabconnect","text":"Key Description Type Default Value batchSize The number of events Fabconnect should batch together for delivery to FireFly core. Only applies when automatically creating a new event stream <code>int</code> <code>50</code> batchTimeout The maximum amount of time to wait for a batch to complete <code>time.Duration</code> <code>500</code> chaincode The name of the Fabric chaincode that FireFly will use for BatchPin transactions (deprecated - use fireflyContract[].chaincode) <code>string</code> <code>&lt;nil&gt;</code> channel The Fabric channel that FireFly will use for BatchPin transactions <code>string</code> <code>&lt;nil&gt;</code> connectionTimeout The maximum amount of time that a connection is allowed to remain with no data transmitted <code>time.Duration</code> <code>30s</code> expectContinueTimeout See ExpectContinueTimeout in the Go docs <code>time.Duration</code> <code>1s</code> headers Adds custom headers to HTTP requests <code>map[string]string</code> <code>&lt;nil&gt;</code> idleTimeout The max duration to hold a HTTP keepalive connection between calls <code>time.Duration</code> <code>475ms</code> maxConnsPerHost The max number of connections, per unique hostname. Zero means no limit <code>int</code> <code>0</code> maxIdleConns The max number of idle connections to hold pooled <code>int</code> <code>100</code> passthroughHeadersEnabled Enable passing through the set of allowed HTTP request headers <code>boolean</code> <code>false</code> prefixLong The prefix that will be used for Fabconnect specific HTTP headers when FireFly makes requests to Fabconnect <code>string</code> <code>firefly</code> prefixShort The prefix that will be used for Fabconnect specific query parameters when FireFly makes requests to Fabconnect <code>string</code> <code>fly</code> requestTimeout The maximum amount of time that a request is allowed to remain open <code>time.Duration</code> <code>30s</code> signer The Fabric signing key to use when submitting transactions to Fabconnect <code>string</code> <code>&lt;nil&gt;</code> tlsHandshakeTimeout The maximum amount of time to wait for a successful TLS handshake <code>time.Duration</code> <code>10s</code> topic The websocket listen topic that the node should register on, which is important if there are multiple nodes using a single Fabconnect <code>string</code> <code>&lt;nil&gt;</code> url The URL of the Fabconnect instance URL <code>string</code> <code>&lt;nil&gt;</code>"},{"location":"reference/config/#pluginsblockchainfabricfabconnectauth","title":"plugins.blockchain[].fabric.fabconnect.auth","text":"Key Description Type Default Value password Password <code>string</code> <code>&lt;nil&gt;</code> username Username <code>string</code> <code>&lt;nil&gt;</code>"},{"location":"reference/config/#pluginsblockchainfabricfabconnectbackgroundstart","title":"plugins.blockchain[].fabric.fabconnect.backgroundStart","text":"Key Description Type Default Value enabled Start the fabric plugin in the background and enter retry loop if failed to start <code>boolean</code> <code>&lt;nil&gt;</code> factor Set the factor by which the delay increases when retrying <code>float32</code> <code>2</code> initialDelay Delay between restarts in the case where we retry to restart the fabric plugin <code>time.Duration</code> <code>5s</code> maxDelay Max delay between restarts in the case where we retry to restart the fabric plugin <code>time.Duration</code> <code>1m</code>"},{"location":"reference/config/#pluginsblockchainfabricfabconnectproxy","title":"plugins.blockchain[].fabric.fabconnect.proxy","text":"Key Description Type Default Value url Optional HTTP proxy server to use when connecting to Fabconnect URL <code>string</code> <code>&lt;nil&gt;</code>"},{"location":"reference/config/#pluginsblockchainfabricfabconnectretry","title":"plugins.blockchain[].fabric.fabconnect.retry","text":"Key Description Type Default Value count The maximum number of times to retry <code>int</code> <code>5</code> enabled Enables retries <code>boolean</code> <code>false</code> errorStatusCodeRegex The regex that the error response status code must match to trigger retry <code>string</code> <code>&lt;nil&gt;</code> initWaitTime The initial retry delay <code>time.Duration</code> <code>250ms</code> maxWaitTime The maximum retry delay <code>time.Duration</code> <code>30s</code>"},{"location":"reference/config/#pluginsblockchainfabricfabconnectthrottle","title":"plugins.blockchain[].fabric.fabconnect.throttle","text":"Key Description Type Default Value burst The maximum number of requests that can be made in a short period of time before the throttling kicks in. <code>int</code> <code>&lt;nil&gt;</code> requestsPerSecond The average rate at which requests are allowed to pass through over time. <code>int</code> <code>&lt;nil&gt;</code>"},{"location":"reference/config/#pluginsblockchainfabricfabconnecttls","title":"plugins.blockchain[].fabric.fabconnect.tls","text":"Key Description Type Default Value ca The TLS certificate authority in PEM format (this option is ignored if caFile is also set) <code>string</code> <code>&lt;nil&gt;</code> caFile The path to the CA file for TLS on this API <code>string</code> <code>&lt;nil&gt;</code> cert The TLS certificate in PEM format (this option is ignored if certFile is also set) <code>string</code> <code>&lt;nil&gt;</code> certFile The path to the certificate file for TLS on this API <code>string</code> <code>&lt;nil&gt;</code> clientAuth Enables or disables client auth for TLS on this API <code>string</code> <code>&lt;nil&gt;</code> enabled Enables or disables TLS on this API <code>boolean</code> <code>false</code> insecureSkipHostVerify When to true in unit test development environments to disable TLS verification. Use with extreme caution <code>boolean</code> <code>&lt;nil&gt;</code> key The TLS certificate key in PEM format (this option is ignored if keyFile is also set) <code>string</code> <code>&lt;nil&gt;</code> keyFile The path to the private key file for TLS on this API <code>string</code> <code>&lt;nil&gt;</code> requiredDNAttributes A set of required subject DN attributes. Each entry is a regular expression, and the subject certificate must have a matching attribute of the specified type (CN, C, O, OU, ST, L, STREET, POSTALCODE, SERIALNUMBER are valid attributes) <code>map[string]string</code> <code>&lt;nil&gt;</code>"},{"location":"reference/config/#pluginsblockchainfabricfabconnectws","title":"plugins.blockchain[].fabric.fabconnect.ws","text":"Key Description Type Default Value connectionTimeout The amount of time to wait while establishing a connection (or auto-reconnection) <code>time.Duration</code> <code>45s</code> heartbeatInterval The amount of time to wait between heartbeat signals on the WebSocket connection <code>time.Duration</code> <code>30s</code> initialConnectAttempts The number of attempts FireFly will make to connect to the WebSocket when starting up, before failing <code>int</code> <code>5</code> path The WebSocket sever URL to which FireFly should connect WebSocket URL <code>string</code> <code>&lt;nil&gt;</code> readBufferSize The size in bytes of the read buffer for the WebSocket connection <code>BytesSize</code> <code>16Kb</code> url URL to use for WebSocket - overrides url one level up (in the HTTP config) <code>string</code> <code>&lt;nil&gt;</code> writeBufferSize The size in bytes of the write buffer for the WebSocket connection <code>BytesSize</code> <code>16Kb</code>"},{"location":"reference/config/#pluginsblockchaintezosaddressresolver","title":"plugins.blockchain[].tezos.addressResolver","text":"Key Description Type Default Value alwaysResolve Causes the address resolver to be invoked on every API call that submits a signing key. Also disables any result caching <code>boolean</code> <code>&lt;nil&gt;</code> bodyTemplate The body go template string to use when making HTTP requests Go Template <code>string</code> <code>&lt;nil&gt;</code> connectionTimeout The maximum amount of time that a connection is allowed to remain with no data transmitted <code>time.Duration</code> <code>30s</code> expectContinueTimeout See ExpectContinueTimeout in the Go docs <code>time.Duration</code> <code>1s</code> headers Adds custom headers to HTTP requests <code>map[string]string</code> <code>&lt;nil&gt;</code> idleTimeout The max duration to hold a HTTP keepalive connection between calls <code>time.Duration</code> <code>475ms</code> maxConnsPerHost The max number of connections, per unique hostname. Zero means no limit <code>int</code> <code>0</code> maxIdleConns The max number of idle connections to hold pooled <code>int</code> <code>100</code> method The HTTP method to use when making requests to the Address Resolver <code>string</code> <code>GET</code> passthroughHeadersEnabled Enable passing through the set of allowed HTTP request headers <code>boolean</code> <code>false</code> requestTimeout The maximum amount of time that a request is allowed to remain open <code>time.Duration</code> <code>30s</code> responseField The name of a JSON field that is provided in the response, that contains the tezos address (default <code>address</code>) <code>string</code> <code>address</code> retainOriginal When true the original pre-resolved string is retained after the lookup, and passed down to Tezosconnect as the from address <code>boolean</code> <code>&lt;nil&gt;</code> tlsHandshakeTimeout The maximum amount of time to wait for a successful TLS handshake <code>time.Duration</code> <code>10s</code> url The URL of the Address Resolver <code>string</code> <code>&lt;nil&gt;</code> urlTemplate The URL Go template string to use when calling the Address Resolver. The template input contains '.Key' and '.Intent' string variables. Go Template <code>string</code> <code>&lt;nil&gt;</code>"},{"location":"reference/config/#pluginsblockchaintezosaddressresolverauth","title":"plugins.blockchain[].tezos.addressResolver.auth","text":"Key Description Type Default Value password Password <code>string</code> <code>&lt;nil&gt;</code> username Username <code>string</code> <code>&lt;nil&gt;</code>"},{"location":"reference/config/#pluginsblockchaintezosaddressresolverproxy","title":"plugins.blockchain[].tezos.addressResolver.proxy","text":"Key Description Type Default Value url Optional HTTP proxy server to connect through <code>string</code> <code>&lt;nil&gt;</code>"},{"location":"reference/config/#pluginsblockchaintezosaddressresolverretry","title":"plugins.blockchain[].tezos.addressResolver.retry","text":"Key Description Type Default Value count The maximum number of times to retry <code>int</code> <code>5</code> enabled Enables retries <code>boolean</code> <code>false</code> errorStatusCodeRegex The regex that the error response status code must match to trigger retry <code>string</code> <code>&lt;nil&gt;</code> initWaitTime The initial retry delay <code>time.Duration</code> <code>250ms</code> maxWaitTime The maximum retry delay <code>time.Duration</code> <code>30s</code>"},{"location":"reference/config/#pluginsblockchaintezosaddressresolverthrottle","title":"plugins.blockchain[].tezos.addressResolver.throttle","text":"Key Description Type Default Value burst The maximum number of requests that can be made in a short period of time before the throttling kicks in. <code>int</code> <code>&lt;nil&gt;</code> requestsPerSecond The average rate at which requests are allowed to pass through over time. <code>int</code> <code>&lt;nil&gt;</code>"},{"location":"reference/config/#pluginsblockchaintezosaddressresolvertls","title":"plugins.blockchain[].tezos.addressResolver.tls","text":"Key Description Type Default Value ca The TLS certificate authority in PEM format (this option is ignored if caFile is also set) <code>string</code> <code>&lt;nil&gt;</code> caFile The path to the CA file for TLS on this API <code>string</code> <code>&lt;nil&gt;</code> cert The TLS certificate in PEM format (this option is ignored if certFile is also set) <code>string</code> <code>&lt;nil&gt;</code> certFile The path to the certificate file for TLS on this API <code>string</code> <code>&lt;nil&gt;</code> clientAuth Enables or disables client auth for TLS on this API <code>string</code> <code>&lt;nil&gt;</code> enabled Enables or disables TLS on this API <code>boolean</code> <code>false</code> insecureSkipHostVerify When to true in unit test development environments to disable TLS verification. Use with extreme caution <code>boolean</code> <code>&lt;nil&gt;</code> key The TLS certificate key in PEM format (this option is ignored if keyFile is also set) <code>string</code> <code>&lt;nil&gt;</code> keyFile The path to the private key file for TLS on this API <code>string</code> <code>&lt;nil&gt;</code> requiredDNAttributes A set of required subject DN attributes. Each entry is a regular expression, and the subject certificate must have a matching attribute of the specified type (CN, C, O, OU, ST, L, STREET, POSTALCODE, SERIALNUMBER are valid attributes) <code>map[string]string</code> <code>&lt;nil&gt;</code>"},{"location":"reference/config/#pluginsblockchaintezostezosconnect","title":"plugins.blockchain[].tezos.tezosconnect","text":"Key Description Type Default Value batchSize The number of events Tezosconnect should batch together for delivery to FireFly core. Only applies when automatically creating a new event stream <code>int</code> <code>50</code> batchTimeout How long Tezosconnect should wait for new events to arrive and fill a batch, before sending the batch to FireFly core. Only applies when automatically creating a new event stream <code>time.Duration</code> <code>500</code> connectionTimeout The maximum amount of time that a connection is allowed to remain with no data transmitted <code>time.Duration</code> <code>30s</code> expectContinueTimeout See ExpectContinueTimeout in the Go docs <code>time.Duration</code> <code>1s</code> headers Adds custom headers to HTTP requests <code>map[string]string</code> <code>&lt;nil&gt;</code> idleTimeout The max duration to hold a HTTP keepalive connection between calls <code>time.Duration</code> <code>475ms</code> maxConnsPerHost The max number of connections, per unique hostname. Zero means no limit <code>int</code> <code>0</code> maxIdleConns The max number of idle connections to hold pooled <code>int</code> <code>100</code> passthroughHeadersEnabled Enable passing through the set of allowed HTTP request headers <code>boolean</code> <code>false</code> prefixLong The prefix that will be used for Tezosconnect specific HTTP headers when FireFly makes requests to Tezosconnect <code>string</code> <code>firefly</code> prefixShort The prefix that will be used for Tezosconnect specific query parameters when FireFly makes requests to Tezosconnect <code>string</code> <code>fly</code> requestTimeout The maximum amount of time that a request is allowed to remain open <code>time.Duration</code> <code>30s</code> tlsHandshakeTimeout The maximum amount of time to wait for a successful TLS handshake <code>time.Duration</code> <code>10s</code> topic The websocket listen topic that the node should register on, which is important if there are multiple nodes using a single tezosconnect <code>string</code> <code>&lt;nil&gt;</code> url The URL of the Tezosconnect instance URL <code>string</code> <code>&lt;nil&gt;</code>"},{"location":"reference/config/#pluginsblockchaintezostezosconnectauth","title":"plugins.blockchain[].tezos.tezosconnect.auth","text":"Key Description Type Default Value password Password <code>string</code> <code>&lt;nil&gt;</code> username Username <code>string</code> <code>&lt;nil&gt;</code>"},{"location":"reference/config/#pluginsblockchaintezostezosconnectbackgroundstart","title":"plugins.blockchain[].tezos.tezosconnect.backgroundStart","text":"Key Description Type Default Value enabled Start the Tezosconnect plugin in the background and enter retry loop if failed to start <code>boolean</code> <code>&lt;nil&gt;</code> factor Set the factor by which the delay increases when retrying <code>float32</code> <code>2</code> initialDelay Delay between restarts in the case where we retry to restart the tezos plugin <code>time.Duration</code> <code>5s</code> maxDelay Max delay between restarts in the case where we retry to restart the tezos plugin <code>time.Duration</code> <code>1m</code>"},{"location":"reference/config/#pluginsblockchaintezostezosconnectproxy","title":"plugins.blockchain[].tezos.tezosconnect.proxy","text":"Key Description Type Default Value url Optional HTTP proxy server to use when connecting to Tezosconnect URL <code>string</code> <code>&lt;nil&gt;</code>"},{"location":"reference/config/#pluginsblockchaintezostezosconnectretry","title":"plugins.blockchain[].tezos.tezosconnect.retry","text":"Key Description Type Default Value count The maximum number of times to retry <code>int</code> <code>5</code> enabled Enables retries <code>boolean</code> <code>false</code> errorStatusCodeRegex The regex that the error response status code must match to trigger retry <code>string</code> <code>&lt;nil&gt;</code> initWaitTime The initial retry delay <code>time.Duration</code> <code>250ms</code> maxWaitTime The maximum retry delay <code>time.Duration</code> <code>30s</code>"},{"location":"reference/config/#pluginsblockchaintezostezosconnectthrottle","title":"plugins.blockchain[].tezos.tezosconnect.throttle","text":"Key Description Type Default Value burst The maximum number of requests that can be made in a short period of time before the throttling kicks in. <code>int</code> <code>&lt;nil&gt;</code> requestsPerSecond The average rate at which requests are allowed to pass through over time. <code>int</code> <code>&lt;nil&gt;</code>"},{"location":"reference/config/#pluginsblockchaintezostezosconnecttls","title":"plugins.blockchain[].tezos.tezosconnect.tls","text":"Key Description Type Default Value ca The TLS certificate authority in PEM format (this option is ignored if caFile is also set) <code>string</code> <code>&lt;nil&gt;</code> caFile The path to the CA file for TLS on this API <code>string</code> <code>&lt;nil&gt;</code> cert The TLS certificate in PEM format (this option is ignored if certFile is also set) <code>string</code> <code>&lt;nil&gt;</code> certFile The path to the certificate file for TLS on this API <code>string</code> <code>&lt;nil&gt;</code> clientAuth Enables or disables client auth for TLS on this API <code>string</code> <code>&lt;nil&gt;</code> enabled Enables or disables TLS on this API <code>boolean</code> <code>false</code> insecureSkipHostVerify When to true in unit test development environments to disable TLS verification. Use with extreme caution <code>boolean</code> <code>&lt;nil&gt;</code> key The TLS certificate key in PEM format (this option is ignored if keyFile is also set) <code>string</code> <code>&lt;nil&gt;</code> keyFile The path to the private key file for TLS on this API <code>string</code> <code>&lt;nil&gt;</code> requiredDNAttributes A set of required subject DN attributes. Each entry is a regular expression, and the subject certificate must have a matching attribute of the specified type (CN, C, O, OU, ST, L, STREET, POSTALCODE, SERIALNUMBER are valid attributes) <code>map[string]string</code> <code>&lt;nil&gt;</code>"},{"location":"reference/config/#pluginsblockchaintezostezosconnectws","title":"plugins.blockchain[].tezos.tezosconnect.ws","text":"Key Description Type Default Value connectionTimeout The amount of time to wait while establishing a connection (or auto-reconnection) <code>time.Duration</code> <code>45s</code> heartbeatInterval The amount of time to wait between heartbeat signals on the WebSocket connection <code>time.Duration</code> <code>30s</code> initialConnectAttempts The number of attempts FireFly will make to connect to the WebSocket when starting up, before failing <code>int</code> <code>5</code> path The WebSocket sever URL to which FireFly should connect WebSocket URL <code>string</code> <code>&lt;nil&gt;</code> readBufferSize The size in bytes of the read buffer for the WebSocket connection <code>BytesSize</code> <code>16Kb</code> url URL to use for WebSocket - overrides url one level up (in the HTTP config) <code>string</code> <code>&lt;nil&gt;</code> writeBufferSize The size in bytes of the write buffer for the WebSocket connection <code>BytesSize</code> <code>16Kb</code>"},{"location":"reference/config/#pluginsdatabase","title":"plugins.database[]","text":"Key Description Type Default Value name The name of the Database plugin <code>string</code> <code>&lt;nil&gt;</code> type The type of the configured Database plugin <code>string</code> <code>&lt;nil&gt;</code>"},{"location":"reference/config/#pluginsdatabasepostgres","title":"plugins.database[].postgres","text":"Key Description Type Default Value maxConnIdleTime The maximum amount of time a database connection can be idle <code>time.Duration</code> <code>1m</code> maxConnLifetime The maximum amount of time to keep a database connection open <code>time.Duration</code> <code>&lt;nil&gt;</code> maxConns Maximum connections to the database <code>int</code> <code>50</code> maxIdleConns The maximum number of idle connections to the database <code>int</code> <code>&lt;nil&gt;</code> url The PostgreSQL connection string for the database <code>string</code> <code>&lt;nil&gt;</code>"},{"location":"reference/config/#pluginsdatabasepostgresmigrations","title":"plugins.database[].postgres.migrations","text":"Key Description Type Default Value auto Enables automatic database migrations <code>boolean</code> <code>false</code> directory The directory containing the numerically ordered migration DDL files to apply to the database <code>string</code> <code>./db/migrations/postgres</code>"},{"location":"reference/config/#pluginsdatabasesqlite3","title":"plugins.database[].sqlite3","text":"Key Description Type Default Value maxConnIdleTime The maximum amount of time a database connection can be idle <code>time.Duration</code> <code>1m</code> maxConnLifetime The maximum amount of time to keep a database connection open <code>time.Duration</code> <code>&lt;nil&gt;</code> maxConns Maximum connections to the database <code>int</code> <code>1</code> maxIdleConns The maximum number of idle connections to the database <code>int</code> <code>&lt;nil&gt;</code> url The SQLite connection string for the database <code>string</code> <code>&lt;nil&gt;</code>"},{"location":"reference/config/#pluginsdatabasesqlite3migrations","title":"plugins.database[].sqlite3.migrations","text":"Key Description Type Default Value auto Enables automatic database migrations <code>boolean</code> <code>false</code> directory The directory containing the numerically ordered migration DDL files to apply to the database <code>string</code> <code>./db/migrations/sqlite</code>"},{"location":"reference/config/#pluginsdataexchange","title":"plugins.dataexchange[]","text":"Key Description Type Default Value name The name of the configured Data Exchange plugin <code>string</code> <code>&lt;nil&gt;</code> type The Data Exchange plugin to use <code>string</code> <code>&lt;nil&gt;</code>"},{"location":"reference/config/#pluginsdataexchangeffdx","title":"plugins.dataexchange[].ffdx","text":"Key Description Type Default Value connectionTimeout The maximum amount of time that a connection is allowed to remain with no data transmitted <code>time.Duration</code> <code>30s</code> expectContinueTimeout See ExpectContinueTimeout in the Go docs <code>time.Duration</code> <code>1s</code> headers Adds custom headers to HTTP requests <code>map[string]string</code> <code>&lt;nil&gt;</code> idleTimeout The max duration to hold a HTTP keepalive connection between calls <code>time.Duration</code> <code>475ms</code> initEnabled Instructs FireFly to always post all current nodes to the <code>/init</code> API before connecting or reconnecting to the connector <code>boolean</code> <code>false</code> manifestEnabled Determines whether to require+validate a manifest from other DX instances in the network. Must be supported by the connector <code>string</code> <code>false</code> maxConnsPerHost The max number of connections, per unique hostname. Zero means no limit <code>int</code> <code>0</code> maxIdleConns The max number of idle connections to hold pooled <code>int</code> <code>100</code> passthroughHeadersEnabled Enable passing through the set of allowed HTTP request headers <code>boolean</code> <code>false</code> requestTimeout The maximum amount of time that a request is allowed to remain open <code>time.Duration</code> <code>30s</code> tlsHandshakeTimeout The maximum amount of time to wait for a successful TLS handshake <code>time.Duration</code> <code>10s</code> url The URL of the Data Exchange instance URL <code>string</code> <code>&lt;nil&gt;</code>"},{"location":"reference/config/#pluginsdataexchangeffdxauth","title":"plugins.dataexchange[].ffdx.auth","text":"Key Description Type Default Value password Password <code>string</code> <code>&lt;nil&gt;</code> username Username <code>string</code> <code>&lt;nil&gt;</code>"},{"location":"reference/config/#pluginsdataexchangeffdxbackgroundstart","title":"plugins.dataexchange[].ffdx.backgroundStart","text":"Key Description Type Default Value enabled Start the data exchange plugin in the background and enter retry loop if failed to start <code>boolean</code> <code>false</code> factor Set the factor by which the delay increases when retrying <code>float32</code> <code>2</code> initialDelay Delay between restarts in the case where we retry to restart the data exchange plugin <code>time.Duration</code> <code>5s</code> maxDelay Max delay between restarts in the case where we retry to restart the data exchange plugin <code>time.Duration</code> <code>1m</code>"},{"location":"reference/config/#pluginsdataexchangeffdxeventretry","title":"plugins.dataexchange[].ffdx.eventRetry","text":"Key Description Type Default Value factor The retry backoff factor, for event processing <code>float32</code> <code>2</code> initialDelay The initial retry delay, for event processing <code>time.Duration</code> <code>50ms</code> maxDelay The maximum retry delay, for event processing <code>time.Duration</code> <code>30s</code>"},{"location":"reference/config/#pluginsdataexchangeffdxproxy","title":"plugins.dataexchange[].ffdx.proxy","text":"Key Description Type Default Value url Optional HTTP proxy server to use when connecting to the Data Exchange URL <code>string</code> <code>&lt;nil&gt;</code>"},{"location":"reference/config/#pluginsdataexchangeffdxretry","title":"plugins.dataexchange[].ffdx.retry","text":"Key Description Type Default Value count The maximum number of times to retry <code>int</code> <code>5</code> enabled Enables retries <code>boolean</code> <code>false</code> errorStatusCodeRegex The regex that the error response status code must match to trigger retry <code>string</code> <code>&lt;nil&gt;</code> initWaitTime The initial retry delay <code>time.Duration</code> <code>250ms</code> maxWaitTime The maximum retry delay <code>time.Duration</code> <code>30s</code>"},{"location":"reference/config/#pluginsdataexchangeffdxthrottle","title":"plugins.dataexchange[].ffdx.throttle","text":"Key Description Type Default Value burst The maximum number of requests that can be made in a short period of time before the throttling kicks in. <code>int</code> <code>&lt;nil&gt;</code> requestsPerSecond The average rate at which requests are allowed to pass through over time. <code>int</code> <code>&lt;nil&gt;</code>"},{"location":"reference/config/#pluginsdataexchangeffdxtls","title":"plugins.dataexchange[].ffdx.tls","text":"Key Description Type Default Value ca The TLS certificate authority in PEM format (this option is ignored if caFile is also set) <code>string</code> <code>&lt;nil&gt;</code> caFile The path to the CA file for TLS on this API <code>string</code> <code>&lt;nil&gt;</code> cert The TLS certificate in PEM format (this option is ignored if certFile is also set) <code>string</code> <code>&lt;nil&gt;</code> certFile The path to the certificate file for TLS on this API <code>string</code> <code>&lt;nil&gt;</code> clientAuth Enables or disables client auth for TLS on this API <code>string</code> <code>&lt;nil&gt;</code> enabled Enables or disables TLS on this API <code>boolean</code> <code>false</code> insecureSkipHostVerify When to true in unit test development environments to disable TLS verification. Use with extreme caution <code>boolean</code> <code>&lt;nil&gt;</code> key The TLS certificate key in PEM format (this option is ignored if keyFile is also set) <code>string</code> <code>&lt;nil&gt;</code> keyFile The path to the private key file for TLS on this API <code>string</code> <code>&lt;nil&gt;</code> requiredDNAttributes A set of required subject DN attributes. Each entry is a regular expression, and the subject certificate must have a matching attribute of the specified type (CN, C, O, OU, ST, L, STREET, POSTALCODE, SERIALNUMBER are valid attributes) <code>map[string]string</code> <code>&lt;nil&gt;</code>"},{"location":"reference/config/#pluginsdataexchangeffdxws","title":"plugins.dataexchange[].ffdx.ws","text":"Key Description Type Default Value connectionTimeout The amount of time to wait while establishing a connection (or auto-reconnection) <code>time.Duration</code> <code>45s</code> heartbeatInterval The amount of time to wait between heartbeat signals on the WebSocket connection <code>time.Duration</code> <code>30s</code> initialConnectAttempts The number of attempts FireFly will make to connect to the WebSocket when starting up, before failing <code>int</code> <code>5</code> path The WebSocket sever URL to which FireFly should connect WebSocket URL <code>string</code> <code>&lt;nil&gt;</code> readBufferSize The size in bytes of the read buffer for the WebSocket connection <code>BytesSize</code> <code>16Kb</code> url URL to use for WebSocket - overrides url one level up (in the HTTP config) <code>string</code> <code>&lt;nil&gt;</code> writeBufferSize The size in bytes of the write buffer for the WebSocket connection <code>BytesSize</code> <code>16Kb</code>"},{"location":"reference/config/#pluginsidentity","title":"plugins.identity[]","text":"Key Description Type Default Value name The name of a configured Identity plugin <code>string</code> <code>&lt;nil&gt;</code> type The type of a configured Identity plugin <code>string</code> <code>&lt;nil&gt;</code>"},{"location":"reference/config/#pluginssharedstorage","title":"plugins.sharedstorage[]","text":"Key Description Type Default Value name The name of the Shared Storage plugin to use <code>string</code> <code>&lt;nil&gt;</code> type The Shared Storage plugin to use <code>string</code> <code>&lt;nil&gt;</code>"},{"location":"reference/config/#pluginssharedstorageipfsapi","title":"plugins.sharedstorage[].ipfs.api","text":"Key Description Type Default Value connectionTimeout The maximum amount of time that a connection is allowed to remain with no data transmitted <code>time.Duration</code> <code>30s</code> expectContinueTimeout See ExpectContinueTimeout in the Go docs <code>time.Duration</code> <code>1s</code> headers Adds custom headers to HTTP requests <code>map[string]string</code> <code>&lt;nil&gt;</code> idleTimeout The max duration to hold a HTTP keepalive connection between calls <code>time.Duration</code> <code>475ms</code> maxConnsPerHost The max number of connections, per unique hostname. Zero means no limit <code>int</code> <code>0</code> maxIdleConns The max number of idle connections to hold pooled <code>int</code> <code>100</code> passthroughHeadersEnabled Enable passing through the set of allowed HTTP request headers <code>boolean</code> <code>false</code> requestTimeout The maximum amount of time that a request is allowed to remain open <code>time.Duration</code> <code>30s</code> tlsHandshakeTimeout The maximum amount of time to wait for a successful TLS handshake <code>time.Duration</code> <code>10s</code> url The URL for the IPFS API URL <code>string</code> <code>&lt;nil&gt;</code>"},{"location":"reference/config/#pluginssharedstorageipfsapiauth","title":"plugins.sharedstorage[].ipfs.api.auth","text":"Key Description Type Default Value password Password <code>string</code> <code>&lt;nil&gt;</code> username Username <code>string</code> <code>&lt;nil&gt;</code>"},{"location":"reference/config/#pluginssharedstorageipfsapiproxy","title":"plugins.sharedstorage[].ipfs.api.proxy","text":"Key Description Type Default Value url Optional HTTP proxy server to use when connecting to the IPFS API URL <code>string</code> <code>&lt;nil&gt;</code>"},{"location":"reference/config/#pluginssharedstorageipfsapiretry","title":"plugins.sharedstorage[].ipfs.api.retry","text":"Key Description Type Default Value count The maximum number of times to retry <code>int</code> <code>5</code> enabled Enables retries <code>boolean</code> <code>false</code> errorStatusCodeRegex The regex that the error response status code must match to trigger retry <code>string</code> <code>&lt;nil&gt;</code> initWaitTime The initial retry delay <code>time.Duration</code> <code>250ms</code> maxWaitTime The maximum retry delay <code>time.Duration</code> <code>30s</code>"},{"location":"reference/config/#pluginssharedstorageipfsapithrottle","title":"plugins.sharedstorage[].ipfs.api.throttle","text":"Key Description Type Default Value burst The maximum number of requests that can be made in a short period of time before the throttling kicks in. <code>int</code> <code>&lt;nil&gt;</code> requestsPerSecond The average rate at which requests are allowed to pass through over time. <code>int</code> <code>&lt;nil&gt;</code>"},{"location":"reference/config/#pluginssharedstorageipfsapitls","title":"plugins.sharedstorage[].ipfs.api.tls","text":"Key Description Type Default Value ca The TLS certificate authority in PEM format (this option is ignored if caFile is also set) <code>string</code> <code>&lt;nil&gt;</code> caFile The path to the CA file for TLS on this API <code>string</code> <code>&lt;nil&gt;</code> cert The TLS certificate in PEM format (this option is ignored if certFile is also set) <code>string</code> <code>&lt;nil&gt;</code> certFile The path to the certificate file for TLS on this API <code>string</code> <code>&lt;nil&gt;</code> clientAuth Enables or disables client auth for TLS on this API <code>string</code> <code>&lt;nil&gt;</code> enabled Enables or disables TLS on this API <code>boolean</code> <code>false</code> insecureSkipHostVerify When to true in unit test development environments to disable TLS verification. Use with extreme caution <code>boolean</code> <code>&lt;nil&gt;</code> key The TLS certificate key in PEM format (this option is ignored if keyFile is also set) <code>string</code> <code>&lt;nil&gt;</code> keyFile The path to the private key file for TLS on this API <code>string</code> <code>&lt;nil&gt;</code> requiredDNAttributes A set of required subject DN attributes. Each entry is a regular expression, and the subject certificate must have a matching attribute of the specified type (CN, C, O, OU, ST, L, STREET, POSTALCODE, SERIALNUMBER are valid attributes) <code>map[string]string</code> <code>&lt;nil&gt;</code>"},{"location":"reference/config/#pluginssharedstorageipfsgateway","title":"plugins.sharedstorage[].ipfs.gateway","text":"Key Description Type Default Value connectionTimeout The maximum amount of time that a connection is allowed to remain with no data transmitted <code>time.Duration</code> <code>30s</code> expectContinueTimeout See ExpectContinueTimeout in the Go docs <code>time.Duration</code> <code>1s</code> headers Adds custom headers to HTTP requests <code>map[string]string</code> <code>&lt;nil&gt;</code> idleTimeout The max duration to hold a HTTP keepalive connection between calls <code>time.Duration</code> <code>475ms</code> maxConnsPerHost The max number of connections, per unique hostname. Zero means no limit <code>int</code> <code>0</code> maxIdleConns The max number of idle connections to hold pooled <code>int</code> <code>100</code> passthroughHeadersEnabled Enable passing through the set of allowed HTTP request headers <code>boolean</code> <code>false</code> requestTimeout The maximum amount of time that a request is allowed to remain open <code>time.Duration</code> <code>30s</code> tlsHandshakeTimeout The maximum amount of time to wait for a successful TLS handshake <code>time.Duration</code> <code>10s</code> url The URL for the IPFS Gateway URL <code>string</code> <code>&lt;nil&gt;</code>"},{"location":"reference/config/#pluginssharedstorageipfsgatewayauth","title":"plugins.sharedstorage[].ipfs.gateway.auth","text":"Key Description Type Default Value password Password <code>string</code> <code>&lt;nil&gt;</code> username Username <code>string</code> <code>&lt;nil&gt;</code>"},{"location":"reference/config/#pluginssharedstorageipfsgatewayproxy","title":"plugins.sharedstorage[].ipfs.gateway.proxy","text":"Key Description Type Default Value url Optional HTTP proxy server to use when connecting to the IPFS Gateway URL <code>string</code> <code>&lt;nil&gt;</code>"},{"location":"reference/config/#pluginssharedstorageipfsgatewayretry","title":"plugins.sharedstorage[].ipfs.gateway.retry","text":"Key Description Type Default Value count The maximum number of times to retry <code>int</code> <code>5</code> enabled Enables retries <code>boolean</code> <code>false</code> errorStatusCodeRegex The regex that the error response status code must match to trigger retry <code>string</code> <code>&lt;nil&gt;</code> initWaitTime The initial retry delay <code>time.Duration</code> <code>250ms</code> maxWaitTime The maximum retry delay <code>time.Duration</code> <code>30s</code>"},{"location":"reference/config/#pluginssharedstorageipfsgatewaythrottle","title":"plugins.sharedstorage[].ipfs.gateway.throttle","text":"Key Description Type Default Value burst The maximum number of requests that can be made in a short period of time before the throttling kicks in. <code>int</code> <code>&lt;nil&gt;</code> requestsPerSecond The average rate at which requests are allowed to pass through over time. <code>int</code> <code>&lt;nil&gt;</code>"},{"location":"reference/config/#pluginssharedstorageipfsgatewaytls","title":"plugins.sharedstorage[].ipfs.gateway.tls","text":"Key Description Type Default Value ca The TLS certificate authority in PEM format (this option is ignored if caFile is also set) <code>string</code> <code>&lt;nil&gt;</code> caFile The path to the CA file for TLS on this API <code>string</code> <code>&lt;nil&gt;</code> cert The TLS certificate in PEM format (this option is ignored if certFile is also set) <code>string</code> <code>&lt;nil&gt;</code> certFile The path to the certificate file for TLS on this API <code>string</code> <code>&lt;nil&gt;</code> clientAuth Enables or disables client auth for TLS on this API <code>string</code> <code>&lt;nil&gt;</code> enabled Enables or disables TLS on this API <code>boolean</code> <code>false</code> insecureSkipHostVerify When to true in unit test development environments to disable TLS verification. Use with extreme caution <code>boolean</code> <code>&lt;nil&gt;</code> key The TLS certificate key in PEM format (this option is ignored if keyFile is also set) <code>string</code> <code>&lt;nil&gt;</code> keyFile The path to the private key file for TLS on this API <code>string</code> <code>&lt;nil&gt;</code> requiredDNAttributes A set of required subject DN attributes. Each entry is a regular expression, and the subject certificate must have a matching attribute of the specified type (CN, C, O, OU, ST, L, STREET, POSTALCODE, SERIALNUMBER are valid attributes) <code>map[string]string</code> <code>&lt;nil&gt;</code>"},{"location":"reference/config/#pluginstokens","title":"plugins.tokens[]","text":"Key Description Type Default Value broadcastName The name to be used in broadcast messages related to this token plugin, if it differs from the local plugin name <code>string</code> <code>&lt;nil&gt;</code> name A name to identify this token plugin <code>string</code> <code>&lt;nil&gt;</code> type The type of the token plugin to use <code>string</code> <code>&lt;nil&gt;</code>"},{"location":"reference/config/#pluginstokensfftokens","title":"plugins.tokens[].fftokens","text":"Key Description Type Default Value connectionTimeout The maximum amount of time that a connection is allowed to remain with no data transmitted <code>time.Duration</code> <code>30s</code> expectContinueTimeout See ExpectContinueTimeout in the Go docs <code>time.Duration</code> <code>1s</code> headers Adds custom headers to HTTP requests <code>map[string]string</code> <code>&lt;nil&gt;</code> idleTimeout The max duration to hold a HTTP keepalive connection between calls <code>time.Duration</code> <code>475ms</code> maxConnsPerHost The max number of connections, per unique hostname. Zero means no limit <code>int</code> <code>0</code> maxIdleConns The max number of idle connections to hold pooled <code>int</code> <code>100</code> passthroughHeadersEnabled Enable passing through the set of allowed HTTP request headers <code>boolean</code> <code>false</code> requestTimeout The maximum amount of time that a request is allowed to remain open <code>time.Duration</code> <code>30s</code> tlsHandshakeTimeout The maximum amount of time to wait for a successful TLS handshake <code>time.Duration</code> <code>10s</code> url The URL of the token connector URL <code>string</code> <code>&lt;nil&gt;</code>"},{"location":"reference/config/#pluginstokensfftokensauth","title":"plugins.tokens[].fftokens.auth","text":"Key Description Type Default Value password Password <code>string</code> <code>&lt;nil&gt;</code> username Username <code>string</code> <code>&lt;nil&gt;</code>"},{"location":"reference/config/#pluginstokensfftokensbackgroundstart","title":"plugins.tokens[].fftokens.backgroundStart","text":"Key Description Type Default Value enabled Start the tokens plugin in the background and enter retry loop if failed to start <code>boolean</code> <code>false</code> factor Set the factor by which the delay increases when retrying <code>float32</code> <code>2</code> initialDelay Delay between restarts in the case where we retry to restart the token plugin <code>time.Duration</code> <code>5s</code> maxDelay Max delay between restarts in the case where we retry to restart the token plugin <code>time.Duration</code> <code>1m</code>"},{"location":"reference/config/#pluginstokensfftokenseventretry","title":"plugins.tokens[].fftokens.eventRetry","text":"Key Description Type Default Value factor The retry backoff factor, for event processing <code>float32</code> <code>2</code> initialDelay The initial retry delay, for event processing <code>time.Duration</code> <code>50ms</code> maxDelay The maximum retry delay, for event processing <code>time.Duration</code> <code>30s</code>"},{"location":"reference/config/#pluginstokensfftokensproxy","title":"plugins.tokens[].fftokens.proxy","text":"Key Description Type Default Value url Optional HTTP proxy server to use when connecting to the token connector URL <code>string</code> <code>&lt;nil&gt;</code>"},{"location":"reference/config/#pluginstokensfftokensretry","title":"plugins.tokens[].fftokens.retry","text":"Key Description Type Default Value count The maximum number of times to retry <code>int</code> <code>5</code> enabled Enables retries <code>boolean</code> <code>false</code> errorStatusCodeRegex The regex that the error response status code must match to trigger retry <code>string</code> <code>&lt;nil&gt;</code> initWaitTime The initial retry delay <code>time.Duration</code> <code>250ms</code> maxWaitTime The maximum retry delay <code>time.Duration</code> <code>30s</code>"},{"location":"reference/config/#pluginstokensfftokensthrottle","title":"plugins.tokens[].fftokens.throttle","text":"Key Description Type Default Value burst The maximum number of requests that can be made in a short period of time before the throttling kicks in. <code>int</code> <code>&lt;nil&gt;</code> requestsPerSecond The average rate at which requests are allowed to pass through over time. <code>int</code> <code>&lt;nil&gt;</code>"},{"location":"reference/config/#pluginstokensfftokenstls","title":"plugins.tokens[].fftokens.tls","text":"Key Description Type Default Value ca The TLS certificate authority in PEM format (this option is ignored if caFile is also set) <code>string</code> <code>&lt;nil&gt;</code> caFile The path to the CA file for TLS on this API <code>string</code> <code>&lt;nil&gt;</code> cert The TLS certificate in PEM format (this option is ignored if certFile is also set) <code>string</code> <code>&lt;nil&gt;</code> certFile The path to the certificate file for TLS on this API <code>string</code> <code>&lt;nil&gt;</code> clientAuth Enables or disables client auth for TLS on this API <code>string</code> <code>&lt;nil&gt;</code> enabled Enables or disables TLS on this API <code>boolean</code> <code>false</code> insecureSkipHostVerify When to true in unit test development environments to disable TLS verification. Use with extreme caution <code>boolean</code> <code>&lt;nil&gt;</code> key The TLS certificate key in PEM format (this option is ignored if keyFile is also set) <code>string</code> <code>&lt;nil&gt;</code> keyFile The path to the private key file for TLS on this API <code>string</code> <code>&lt;nil&gt;</code> requiredDNAttributes A set of required subject DN attributes. Each entry is a regular expression, and the subject certificate must have a matching attribute of the specified type (CN, C, O, OU, ST, L, STREET, POSTALCODE, SERIALNUMBER are valid attributes) <code>map[string]string</code> <code>&lt;nil&gt;</code>"},{"location":"reference/config/#pluginstokensfftokensws","title":"plugins.tokens[].fftokens.ws","text":"Key Description Type Default Value connectionTimeout The amount of time to wait while establishing a connection (or auto-reconnection) <code>time.Duration</code> <code>45s</code> heartbeatInterval The amount of time to wait between heartbeat signals on the WebSocket connection <code>time.Duration</code> <code>30s</code> initialConnectAttempts The number of attempts FireFly will make to connect to the WebSocket when starting up, before failing <code>int</code> <code>5</code> path The WebSocket sever URL to which FireFly should connect WebSocket URL <code>string</code> <code>&lt;nil&gt;</code> readBufferSize The size in bytes of the read buffer for the WebSocket connection <code>BytesSize</code> <code>16Kb</code> url URL to use for WebSocket - overrides url one level up (in the HTTP config) <code>string</code> <code>&lt;nil&gt;</code> writeBufferSize The size in bytes of the write buffer for the WebSocket connection <code>BytesSize</code> <code>16Kb</code>"},{"location":"reference/config/#privatemessagingbatch","title":"privatemessaging.batch","text":"Key Description Type Default Value agentTimeout How long to keep around a batching agent for a sending identity before disposal <code>time.Duration</code> <code>2m</code> payloadLimit The maximum payload size of a private message Data Exchange payload <code>BytesSize</code> <code>800Kb</code> size The maximum number of messages in a batch for private messages <code>int</code> <code>200</code> timeout The timeout to wait for a batch to fill, before sending <code>time.Duration</code> <code>1s</code>"},{"location":"reference/config/#privatemessagingretry","title":"privatemessaging.retry","text":"Key Description Type Default Value factor The retry backoff factor <code>float32</code> <code>2</code> initDelay The initial retry delay <code>time.Duration</code> <code>100ms</code> maxDelay The maximum retry delay <code>time.Duration</code> <code>30s</code>"},{"location":"reference/config/#spi","title":"spi","text":"Key Description Type Default Value address The IP address on which the admin HTTP API should listen IP Address <code>string</code> <code>127.0.0.1</code> enabled Enables the admin HTTP API <code>boolean</code> <code>false</code> port The port on which the admin HTTP API should listen <code>int</code> <code>5001</code> publicURL The fully qualified public URL for the admin API. This is used for building URLs in HTTP responses and in OpenAPI Spec generation URL <code>string</code> <code>&lt;nil&gt;</code> readTimeout The maximum time to wait when reading from an HTTP connection <code>time.Duration</code> <code>15s</code> shutdownTimeout The maximum amount of time to wait for any open HTTP requests to finish before shutting down the HTTP server <code>time.Duration</code> <code>10s</code> writeTimeout The maximum time to wait when writing to an HTTP connection <code>time.Duration</code> <code>15s</code>"},{"location":"reference/config/#spiauth","title":"spi.auth","text":"Key Description Type Default Value type The auth plugin to use for server side authentication of requests <code>string</code> <code>&lt;nil&gt;</code>"},{"location":"reference/config/#spiauthbasic","title":"spi.auth.basic","text":"Key Description Type Default Value passwordfile The path to a .htpasswd file to use for authenticating requests. Passwords should be hashed with bcrypt. <code>string</code> <code>&lt;nil&gt;</code>"},{"location":"reference/config/#spitls","title":"spi.tls","text":"Key Description Type Default Value ca The TLS certificate authority in PEM format (this option is ignored if caFile is also set) <code>string</code> <code>&lt;nil&gt;</code> caFile The path to the CA file for TLS on this API <code>string</code> <code>&lt;nil&gt;</code> cert The TLS certificate in PEM format (this option is ignored if certFile is also set) <code>string</code> <code>&lt;nil&gt;</code> certFile The path to the certificate file for TLS on this API <code>string</code> <code>&lt;nil&gt;</code> clientAuth Enables or disables client auth for TLS on this API <code>string</code> <code>&lt;nil&gt;</code> enabled Enables or disables TLS on this API <code>boolean</code> <code>false</code> insecureSkipHostVerify When to true in unit test development environments to disable TLS verification. Use with extreme caution <code>boolean</code> <code>&lt;nil&gt;</code> key The TLS certificate key in PEM format (this option is ignored if keyFile is also set) <code>string</code> <code>&lt;nil&gt;</code> keyFile The path to the private key file for TLS on this API <code>string</code> <code>&lt;nil&gt;</code> requiredDNAttributes A set of required subject DN attributes. Each entry is a regular expression, and the subject certificate must have a matching attribute of the specified type (CN, C, O, OU, ST, L, STREET, POSTALCODE, SERIALNUMBER are valid attributes) <code>map[string]string</code> <code>&lt;nil&gt;</code>"},{"location":"reference/config/#spiws","title":"spi.ws","text":"Key Description Type Default Value blockedWarnInterval How often to log warnings in core, when an admin change event listener falls behind the stream they requested and misses events <code>time.Duration</code> <code>1m</code> eventQueueLength Server-side queue length for events waiting for delivery over an admin change event listener websocket <code>int</code> <code>250</code> readBufferSize The size in bytes of the read buffer for the WebSocket connection <code>BytesSize</code> <code>16Kb</code> writeBufferSize The size in bytes of the write buffer for the WebSocket connection <code>BytesSize</code> <code>16Kb</code>"},{"location":"reference/config/#subscription","title":"subscription","text":"Key Description Type Default Value max The maximum number of pre-defined subscriptions that can exist (note for high fan-out consider connecting a dedicated pub/sub broker to the dispatcher) <code>int</code> <code>500</code>"},{"location":"reference/config/#subscriptiondefaults","title":"subscription.defaults","text":"Key Description Type Default Value batchSize Default read ahead to enable for subscriptions that do not explicitly configure readahead <code>int</code> <code>50</code> batchTimeout Default batch timeout <code>int</code> <code>50ms</code>"},{"location":"reference/config/#subscriptionevents","title":"subscription.events","text":"Key Description Type Default Value maxScanLength The maximum number of events a search for historical events matching a subscription will index from the database <code>int</code> <code>1000</code>"},{"location":"reference/config/#subscriptionretry","title":"subscription.retry","text":"Key Description Type Default Value factor The retry backoff factor <code>float32</code> <code>2</code> initDelay The initial retry delay <code>time.Duration</code> <code>250ms</code> maxDelay The maximum retry delay <code>time.Duration</code> <code>30s</code>"},{"location":"reference/config/#transactionwriter","title":"transaction.writer","text":"Key Description Type Default Value batchMaxTransactions The maximum number of transaction inserts to include in a batch <code>int</code> <code>100</code> batchTimeout How long to wait for more transactions to arrive before flushing the batch <code>time.Duration</code> <code>10ms</code> count The number of message writer workers <code>int</code> <code>5</code>"},{"location":"reference/config/#ui","title":"ui","text":"Key Description Type Default Value enabled Enables the web user interface <code>boolean</code> <code>true</code> path The file system path which contains the static HTML, CSS, and JavaScript files for the user interface <code>string</code> <code>&lt;nil&gt;</code>"},{"location":"reference/events/","title":"Event Bus","text":""},{"location":"reference/events/#hyperledger-firefly-event-bus","title":"Hyperledger FireFly Event Bus","text":"<p>The FireFly event bus provides your application with a single stream of events from all of the back-end services that plug into FireFly.</p> <p>Applications subscribe to these events using developer friendly protocols like WebSockets, and Webhooks. Additional transports and messaging systems like NATS, Kafka, and JMS Servers can be connected through plugins.</p> <p>Each application creates one or more Subscriptions to identify itself. In this subscription the application can choose to receive all events that are emitted within a <code>namespace</code>, or can use server-side filtering to only receive a sub-set of events.</p> <p>The event bus reliably keeps track of which events have been delivered to which applications, via an <code>offset</code> into the main event stream that is updated each time an application acknowledges receipt of events over its subscription.</p>"},{"location":"reference/events/#event-driven-application-architecture","title":"Event-Driven Application Architecture","text":"<p>Decentralized applications are built around a source of truth that is shared between multiple parties. No one party can change the state unilaterally, as their changes need to be processed in order with the other changes in the system. Each party processes requests to change shared state in the same order, against a common set of rules for what is allowed at that exact point in the processing. As a result everybody deterministically ends up with the same state at the end of the processing.</p> <p>This requires an event-driven programming model.</p> <p>You will find an event-driven model at the core of every blockchain Smart Contract technology.</p> <p>This event-driven approach is unavoidable regardless of how much of your business data &amp; logic can be directly stored/processed on-chain, vs. off-chain.</p> <p>So Hyperledger FireFly aims to provide you with the tools to easily manage this model throughout your decentralized application stack.</p> <p></p> <p>Your back-end application should be structured for this event-driven paradigm, with an Event Handler constantly listening for events, applying a consistent State Machine to those events and applying the changes to your Application Database.</p> <p>FireFly comes with a built in event processor for Token transfers &amp; approvals, that implements this pattern to maintain balances, and transaction history in a rich query off-chain data cache.</p>"},{"location":"reference/events/#decentralized-event-processing","title":"Decentralized Event Processing","text":"<p>In a decentralized system, you need to consider that each organization runs its own applications, and has its own private database.</p> <p>At any given point in time different organizations will have slightly different views of what the most up to date information is - even for the blockchain state.</p> <p>As well as the agreed business logic, there will be private data and core system integration that are needed to process events as they happen. Some of this data might be received privately from other parties, over a secure communications channel (not the blockchain).</p> <p></p> <p>The system must be eventually consistent across all parties for any business data/decision that those parties need to agree on. This happens by all parties processing the same events in the same order, and by applying the same business logic (for the parts of the business logic that are agreed).</p> <p>This means that when processing an event, a participant must have access to enough historical data/state to reach the same conclusion as everyone else.</p> <p>Let's look at a couple of examples.</p>"},{"location":"reference/events/#example-1-a-fungible-token-balance-transfer","title":"Example 1: A fungible token balance transfer","text":"<p>You need to be able to verify the complete lineage of the tokens being spent, in order to know that they cannot be double spent anywhere in the network.</p> <p>This means the transaction must be backed by a blockchain verifiable by all participants on the network that could hold balances of that token.</p> <p>You might be able to use advanced cryptography (such as zero-knowledge proofs) to mask the participants in the trade, but the transaction themselves must be verifiable to everyone in a global sequence that prevents double spending.</p>"},{"location":"reference/events/#example-2-a-step-in-a-multi-party-business-process","title":"Example 2: A step in a multi-party business process","text":"<p>Here it is likely you want to restrict visibility of the data to just the parties directly involved in the business process.</p> <p>To come to a common agreement on outcome, the parties must know they are processing the same data in the same order. So at minimum a proof (a hash of the data) needs to \"pinned\" to a blockchain ledger visible to all participants involved in the process.</p> <p>You can then choose to put more processing on the blockchain, to enforce some critical rules in the business state machine that must be executed fairly to prevent one party from cheating the system. Such as that the highest bid is chosen in a competitive bidding process, or a minimum set of parties have voted agreement before a transaction is finalized.</p> <p>Other steps in the process might include human decision making, private data from the core systems of one member, or proprietary business logic that one member is not willing to share. These steps are \"non-deterministic\" - you cannot predict the outcome, nor be guaranteed to reproduce the same outcome with the same inputs in the future.</p> <p>The FireFly event bus is designed to make triggering these non-deterministic steps easy, while still allowing them to be part of the overall state machine of the business process. You need to take care that the system is designed so parties cannot 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.</p> <p>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\" while complex off-chain agreement happens.</p>"},{"location":"reference/events/#privacy-groups-and-late-join","title":"Privacy groups and late join","text":"<p>If a new participant needs to join into a business transaction that has already started, they must first \"catch up\" with the current state before they can play their part. In a real-world scenario they might not be allowed to see all the data that's visible to the other parties, so it is common to create a new stream of communications that includes all of the existing parties, plus the new party, to continue the process.</p> <p>If you use the same blockchain to back both groups, then you can safely order business process steps that involve different parties across these overlapping groups of participants.</p> <p>Using a single Ethereum permissioned side-chain for example.</p> <p>Alternatively, you can create dedicated distributed ledgers (DLTs) for communication between these groups of participants. This can allow more logic and data to go on-chain directly, although you still must consider the fact that this data is immutable and can never be deleted.</p> <p>Using Hyperledger Fabric channels for example.</p> <p>On top of either type of ledger, FireFly provides a private Group construct to facilitate secure off-chain data exchanges, and to efficiently pin these communications to the blockchain in batches.</p> <p>These private data exchanges can also be coordinated with most sophisticated on-chain transactions, such as token transfers.</p>"},{"location":"reference/events/#event-types","title":"Event Types","text":"<p>FireFly provides a number of different types of events to your application, designed to allow you to build your application state machine quickly and reliably.</p> <p>All events in FireFly share a common base structure, regardless of their type. They are then linked (via a <code>reference</code>) to an object that contains detailed information.</p> <p>The categories of event your application can receive are as follows:</p> <p>See the Core Resources/Event page for a full list of event types, and more details on the data you can expect for each type.</p>"},{"location":"reference/events/#blockchain-events","title":"Blockchain events","text":"<p>FireFly allows your application to subscribe to any event from a blockchain smart contract.</p> <p>In order for applications connected to the FireFly API to receive blockchain events from a smart contracts, a ContractListener fist must be created to instruct FireFly to listen to those events from the blockchain (via the blockchain plugin).</p> <p>Once you have configured the blockchain event listener, every event detected from the blockchain will result in a FireFly event delivered to your application of type <code>blockchain_event_received</code>.</p> <p>As of 1.3.1 a group of event filters can be established under a single topic when supported by the connector, which has benefits for ordering.  See Contract Listeners for more detail</p> <p>Check out the Custom Contracts Tutorial for a walk-through of how to set up listeners for the events from your smart contracts.</p> <p>FireFly automatically establishes listeners for some blockchain events:</p> <ul> <li> <p>Events from the FireFly <code>BatchPin</code> contract that is used to pin identities,   off-chain data broadcast and private messaging to the blockchain.</p> </li> <li> <p>Events from Token contracts, for which a Token Pool   has been configured. These events are detected indirectly via the token connector.</p> </li> </ul>"},{"location":"reference/events/#token-events","title":"Token events","text":"<p>FireFly provides a Wallet API, that is pluggable to multiple token implementations without needing to change your app.</p> <p>The pluggable API/Event interface allows all kinds of technical implementations of tokens to be fitted into a common framework.</p> <p>The following wallet operations are supported. These are universal to all token implementations - NFTs and fungible tokens alike:</p> <ul> <li>Mint</li> <li>Burn</li> <li>Transfer</li> <li>Approve</li> </ul> <p>FireFly processes, indexes and stores the events associated with these actions, for any Token Pool that has been configured on the FireFly node.</p> <p>See Token Transfer and Token Approval for more information on the individual operations.</p> <p>The token connector is responsible for mapping from the raw Blockchain Events, to the FireFly model for tokens. Reference token connector implementations are provided for common interface standards implemented by tokens - like ERC-20, ERC-721 and ERC-115.</p> <p>A particular token contract might have many additional features that are unique to that contract, particularly around governance. For these you would use the Smart Contract features of FireFly to interact with the blockchain API and Events directly.</p>"},{"location":"reference/events/#message-events-on-chain-off-chain-coordinated","title":"Message events: on-chain / off-chain coordinated","text":"<p>Event aggregation between data arriving off-chain, and the associated ordered proof/transaction events being confirmed on-chain, is a complex orchestration task.</p> <p>The universal order and additional transaction logic on-chain must be the source of truth for when and how an event is processed.</p> <p>However, that event cannot be processed until the off-chain private/broadcast data associated with that event is also available and verified against the on-chain hash of that additional data.</p> <p>They might arrive in any order, and no further events can be processed on that business transaction until the data is available.</p> <p>Multiple parties might be emitting events as part of the business transaction, and the outcome will only be assured to be the same by all parties if they process these events in the same order.</p> <p>Hyperledger FireFly handles this for you. Events related to a message are not emitted until both the on-chain and off-chain parts (including large binary attachments) are available+verified in your local FireFly node, and all previous messages on the same <code>topic</code> have been processed successfully by your application.</p> <p>Your application just needs to:</p> <ol> <li>Choose a suitable <code>topic</code> for your messages that determines the ordered stream    it is part of. Such as a business transaction identifier.</li> <li>Make sure the application does not acknowledge a message, until it has finished    processing it.</li> </ol> <p>See Message for more information</p>"},{"location":"reference/events/#transaction-submission-events","title":"Transaction submission events","text":"<p>These events are emitted each time a new transaction is initiated via the Firefly API.</p> <p>These events are only emitted on the local FireFly node that initiates an activity.</p> <p>For more information about FireFly Transactions, and how they relate to blockchain transactions, see Transaction.</p>"},{"location":"reference/firefly_interface_format/","title":"FireFly Interface Format","text":"<p>FireFly defines a common, blockchain agnostic way to describe smart contracts. This is referred to as a Contract Interface, and it is written in the FireFly Interface (FFI) format. It is a simple JSON document that has a name, a namespace, a version, a list of methods, and a list of events.</p>"},{"location":"reference/firefly_interface_format/#overview","title":"Overview","text":"<p>There are four required fields when broadcasting a contract interface in FireFly: a <code>name</code>, a <code>version</code>, a list of <code>methods</code>, and a list of <code>events</code>. A <code>namespace</code> field will also be filled in automatically based on the URL path parameter. Here is an example of the structure of the required fields:</p> <pre><code>{\n  \"name\": \"example\",\n  \"version\": \"v1.0.0\",\n  \"methods\": [],\n  \"events\": []\n}\n</code></pre> <p>NOTE: Contract interfaces are scoped to a namespace. Within a namespace each contract interface must have a unique name and version combination. The same name and version combination can exist in different namespaces simultaneously.</p>"},{"location":"reference/firefly_interface_format/#method","title":"Method","text":"<p>Let's look at a what goes inside the <code>methods</code> array now. It is also a JSON object that has a <code>name</code>, a list of <code>params</code> which are the arguments the function will take and a list of <code>returns</code> which are the return values of the function. It also has an optional <code>description</code> which can be helpful in OpenAPI Spec generation. Finally, it has an optional <code>details</code> object which wraps blockchain specific information about this method. This can be used by the blockchain plugin when invoking this function, and it is also used in documentation generation.</p> <pre><code>{\n  \"name\": \"add\",\n  \"description\": \"Add two numbers together\",\n  \"params\": [],\n  \"returns\": [],\n  \"details\": {}\n}\n</code></pre>"},{"location":"reference/firefly_interface_format/#event","title":"Event","text":"<p>What goes into the <code>events</code> array is very similar. It is also a JSON object that has a <code>name</code> and a list of <code>params</code>. The difference is that <code>events</code> don't have <code>returns</code>. Arguments that are passed to the event when it is emitted are in <code>params</code>. It also has an optional <code>description</code> which can be helpful in OpenAPI Spec generation. Finally, it has an optional <code>details</code> object which wraps blockchain specific information about this event. This can be used by the blockchain plugin when invoking this function, and it is also used in documentation generation.</p> <pre><code>{\n  \"name\": \"added\",\n  \"description\": \"An event that occurs when numbers have been added\",\n  \"params\": [],\n  \"details\": {}\n}\n</code></pre>"},{"location":"reference/firefly_interface_format/#param","title":"Param","text":"<p>Both <code>methods</code>, and <code>events</code> have lists of <code>params</code> or <code>returns</code>, and the type of JSON object that goes in each of these arrays is the same. It is simply a JSON object with a <code>name</code> and a <code>schema</code>. There is also an optional <code>details</code> field that is passed to the blockchain plugin for blockchain specific requirements.</p> <pre><code>{\n  \"name\": \"x\",\n  \"schema\": {\n    \"type\": \"integer\",\n    \"details\": {}\n  }\n}\n</code></pre>"},{"location":"reference/firefly_interface_format/#schema","title":"Schema","text":"<p>The param <code>schema</code> is an important field which tells FireFly the type information about this particular field. This is used in several different places, such as OpenAPI Spec generation, API request validation, and blockchain request preparation.</p> <p>The <code>schema</code> field accepts JSON Schema (version 2020-12) with several additional requirements:</p> <ul> <li>A <code>type</code> field is always mandatory</li> <li>The list of valid types is:</li> <li><code>boolean</code></li> <li><code>integer</code></li> <li><code>string</code></li> <li><code>object</code></li> <li><code>array</code></li> <li>Blockchain plugins can add their own specific requirements to this list of validation rules</li> </ul> <p>NOTE: Floats or decimals are not currently accepted because certain underlying blockchains (e.g. Ethereum) only allow integers</p> <p>The type field here is the JSON input type when making a request to FireFly to invoke or query a smart contract. This type can be different from the actual blockchain type, usually specified in the <code>details</code> field, if there is a compatible type mapping between the two.</p>"},{"location":"reference/firefly_interface_format/#schema-details","title":"Schema details","text":"<p> The details field is quite important in some cases. Because the <code>details</code> field is passed to the blockchain plugin, it is used to encapsulate blockchain specific type information about a particular field. Additionally, because each blockchain plugin can add rules to the list of schema requirements above, a blockchain plugin can enforce that certain fields are always present within the <code>details</code> field.</p> <p>For example, the Ethereum plugin always needs to know what Solidity type the field is. It also defines several optional fields. A full Ethereum details field may look like:</p> <pre><code>{\n  \"type\": \"uint256\",\n  \"internalType\": \"uint256\",\n  \"indexed\": false\n}\n</code></pre>"},{"location":"reference/firefly_interface_format/#automated-generation-of-firefly-interfaces","title":"Automated generation of FireFly Interfaces","text":"<p>A convenience endpoint exists on the API to facilitate converting from native blockchain interface formats such as an Ethereum ABI to the FireFly Interface format. For details, please see the API documentation for the contract interface generation endpoint.</p> <p>For an example of using this endpoint with a specific Ethereum contract, please see the Tutorial to Work with custom smart contracts.</p>"},{"location":"reference/firefly_interface_format/#full-example","title":"Full Example","text":"<p>Putting it all together, here is a full example of the FireFly Interface format with all the fields filled in:</p> <pre><code>{\n  \"namespace\": \"default\",\n  \"name\": \"SimpleStorage\",\n  \"description\": \"A simple smart contract that stores and retrieves an integer on-chain\",\n  \"version\": \"v1.0.0\",\n  \"methods\": [\n    {\n      \"name\": \"get\",\n      \"description\": \"Retrieve the value of the stored integer\",\n      \"params\": [],\n      \"returns\": [\n        {\n          \"name\": \"output\",\n          \"schema\": {\n            \"type\": \"integer\",\n            \"details\": {\n              \"type\": \"uint256\",\n              \"internalType\": \"uint256\"\n            }\n          }\n        }\n      ],\n      \"details\": {\n        \"stateMutability\": \"viewable\"\n      }\n    },\n    {\n      \"name\": \"set\",\n      \"description\": \"Set the stored value on-chain\",\n      \"params\": [\n        {\n          \"name\": \"newValue\",\n          \"schema\": {\n            \"type\": \"integer\",\n            \"details\": {\n              \"type\": \"uint256\",\n              \"internalType\": \"uint256\"\n            }\n          }\n        }\n      ],\n      \"returns\": [],\n      \"details\": {\n        \"stateMutability\": \"payable\"\n      }\n    }\n  ],\n  \"events\": [\n    {\n      \"name\": \"Changed\",\n      \"description\": \"An event that is fired when the stored integer value changes\",\n      \"params\": [\n        {\n          \"name\": \"from\",\n          \"schema\": {\n            \"type\": \"string\",\n            \"details\": {\n              \"type\": \"address\",\n              \"internalType\": \"address\",\n              \"indexed\": true\n            }\n          }\n        },\n        {\n          \"name\": \"value\",\n          \"schema\": {\n            \"type\": \"integer\",\n            \"details\": {\n              \"type\": \"uint256\",\n              \"internalType\": \"uint256\"\n            }\n          }\n        }\n      ],\n      \"details\": {}\n    }\n  ]\n}\n</code></pre>"},{"location":"reference/idempotency/","title":"Idempotency Keys","text":""},{"location":"reference/idempotency/#idempotency","title":"Idempotency","text":"<p>The transaction submission REST APIs of Hyperledger FireFly are idempotent.</p> <p>Idempotent APIs allow an application to safely submit a request multiple times, and for the transaction to only be accepted and executed once.</p> <p>This is the well accepted approach for REST APIs over HTTP/HTTPS to achieve resilience, as HTTP requests can fail in indeterminate ways. For example in a request or gateway timeout situation, the requester is unable to know whether the request will or will not eventually be processed.</p> <p>There are various types of FireFly transaction that can be submitted. These include direct submission of blockchain transactions to a smart contract, as well as more complex transactions including coordination of multiple operations across on-chain and off-chain connectors.</p> <p>In order for Hyperledger FireFly to deduplicate transactions, and make them idempotent, the application must supply an <code>idempotencyKey</code> on each API request.</p>"},{"location":"reference/idempotency/#firefly-idempotency-keys","title":"FireFly Idempotency Keys","text":"<p>The caller of the API specifies its own unique identifier (an arbitrary string up to 256 characters) that uniquely identifies the request, in the <code>idempotencyKey</code> field of the API.</p> <p>So if there is a network connectivity failure, or an abrupt termination of either runtime, the application can safely attempt to resubmit the REST API call and be returned a <code>409 Conflict</code> HTTP code.</p> <p>Examples of how an app might construct such an idempotencyKey include:</p> <ul> <li>Unique business identifiers from the request that comes into its API up-stream - passing idempotency along the chain</li> <li>A hash of the business unique data that relates to the request - maybe all the input data of a blockchain transaction for example, if that payload is guaranteed to be unique. <p>Be careful of cases where the business data might not be unique - like a transfer of 10 coins from A to B.</p> <p>Such a transfer could happen multiple times, and each would be a separate business transaction.</p> <p>Where as transfer with invoice number <code>abcd1234</code> of 10 coins from A to B would be assured to be unique.</p> </li> <li>A unique identifier of a business transaction generated within the application and stored in its database before submission <p>This moves the challenge up one layer into your application. How does that unique ID get generated? Is that itself idempotent?</p> </li> </ul>"},{"location":"reference/idempotency/#operation-idempotency","title":"Operation Idempotency","text":"<p>FireFly provides an idempotent interface downstream to connectors.</p> <p>Each operation within a FireFly transaction receives a unique ID within the overall transaction that is used as an idempotency key when invoking that connector.</p> <p>Well formed connectors honor this idempotency key internally, ensuring that the end-to-end transaction submission is idempotent.</p> <p>Key examples of such connectors are EVMConnect and others built on the Blockchain Connector Toolkit.</p> <p>When an operation is retried automatically, the same idempotency key is re-used to avoid resubmission.</p>"},{"location":"reference/idempotency/#short-term-retry","title":"Short term retry","text":"<p>The FireFly core uses standard HTTP request code to communicate with all connector APIs.</p> <p>This code include exponential backoff retry, that can be enabled with a simple boolean in the plugin of FireFly core. The minimum retry, maximum retry, and backoff factor can be tuned individually as well on each connector.</p> <p>See Configuration Reference for more information.</p>"},{"location":"reference/idempotency/#administrative-operation-retry","title":"Administrative operation retry","text":"<p>The <code>operations/{operationId}/retry</code> API can be called administratively to resubmit a transaction that has reached <code>Failed</code> status, or otherwise been determined by an operator/monitor to be unrecoverable within the connector.</p> <p>In this case, the previous operation is marked <code>Retried</code>, a new operation ID is allocated, and the operation is re-submitted to the connector with this new ID.</p>"},{"location":"reference/identities/","title":"Identities","text":""},{"location":"reference/identities/#overview","title":"Overview","text":"<p>Identities are a critical part of using FireFly in a multi-party system. Every party that joins a multi-party system must begin by claiming an on- and off-chain identity, which is described with a unique DID. Each type of identity is also associated with an on- or off-chain verifier, which can be used in some way to check the authorship of a piece of data. Together, these concepts form the backbone of the trust model for exchanging multi-party data.</p>"},{"location":"reference/identities/#types-of-identities","title":"Types of Identities","text":"<p>There are three types of identities:</p>"},{"location":"reference/identities/#org","title":"org","text":"<p>Organizations are the primary identity type in FireFly. They represent a logical on-chain signing identity, and the attached verifier is therefore a blockchain key (with the exact format depending on the blockchain being used). Every party in a multi-party system must claim a root organization identity as the first step to joining the network.</p> <p>The root organization <code>name</code> and <code>key</code> must be defined in the FireFly config (once for every multi-party system). It can be claimed with a POST to <code>/network/organizations/self</code>.</p> <p>Organizations may have child identities of any type.</p>"},{"location":"reference/identities/#node","title":"node","text":"<p>Nodes represent a logical off-chain identity - and specifically, they are tied to an instance of a data exchange connector. The format of the attached verifier depends on the data exchange plugin being used, but it will be mapped to some validation provided by that plugin (ie the name of an X.509 certificate or similar). Every party in a multi-party system must claim a node identity when joining the network, which must be a child of one of its organization identities (but it is possible for many nodes to share a parent organization).</p> <p>The node <code>name</code> must be defined in the FireFly config (once for every multi-party system). It can be claimed with a POST to <code>/network/nodes/self</code>.</p> <p>Nodes must be a child of an organization, and cannot have any child identities of their own.</p> <p>Note that \"nodes\" as an identity concept are distinct from FireFly supernodes, from underlying blockchain nodes, and from anywhere else the term \"node\" happens to be used.</p>"},{"location":"reference/identities/#custom","title":"custom","text":"<p>Custom identities are similar to organizations, but are provided for applications to define their own more granular notions of identity. They are associated with an on-chain verifier in the same way as organizations.</p> <p>They can only have child identities which are also of type \"custom\".</p>"},{"location":"reference/identities/#identity-claims","title":"Identity Claims","text":"<p>Before an identity can be used within a multi-party system, it must be claimed. The identity claim is a special type of broadcast message sent by FireFly to establish an identity uniquely among the parties in the multi-party system. As with other broadcasts, this entails an on-chain transaction which contains a public reference to an off-chain piece of data (such as an IPFS reference) describing the details of the identity claim.</p> <p>The claim data consists of information on the identity being claimed - such as the type, the DID, and the parent (if applicable). The DID must be unique and unclaimed. The verifier will be inferred from the message - for on-chain identities (org and custom), it is the blockchain key that was used to sign the on-chain portion of the message, while for off-chain identities (nodes), is is an identifier queried from data exchange.</p> <p>For on-chain identities with a parent, two messages are actually required - the claim message signed with the new identity's blockchain key, as well as a separate verification message signed with the parent identity's blockchain key. Both messages must be received before the identity is confirmed.</p>"},{"location":"reference/identities/#messaging","title":"Messaging","text":"<p>In the context of a multi-party system, FireFly provides capabilities for sending off-chain messages that are pinned to an on-chain proof. The sender of every message must therefore have an on-chain and off-chain identity. For private messages, every recipient must also have an on-chain and off-chain identity.</p>"},{"location":"reference/identities/#sender","title":"Sender","text":"<p>When sending a message, the on-chain identity of the sender is controlled by the <code>author</code> and <code>key</code> fields.</p> <ul> <li>If both are blank, the root organization is assumed.</li> <li>If <code>author</code> alone is specified, it should be the DID of an org or custom identity. The associated   verifier will be looked up to use as the <code>key</code>.</li> <li>If <code>key</code> alone is specified, it must match the registered blockchain verifier for an org or custom identity that was previously claimed.   A reverse lookup will be used to populate the DID for the <code>author</code>.</li> <li>If <code>author</code> and <code>key</code> are both specified, they will be used as-is (can be used to send private messages with an unregistered blockchain key).</li> </ul> <p>The resolved <code>key</code> will be used to sign the blockchain transaction, which establishes the sender's on-chain identity.</p> <p>The sender's off-chain identity is always controlled by the <code>node.name</code> from the config along with the data exchange plugin.</p>"},{"location":"reference/identities/#recipients","title":"Recipients","text":"<p>When specifying private message recipients, each one has an <code>identity</code> and a <code>node</code>.</p> <ul> <li>If <code>identity</code> alone is specified, it should be the DID of an org or custom identity. The first <code>node</code> owned by that identity or one of its   ancestors will be automatically selected.</li> <li>If both <code>identity</code> and <code>node</code> are specified, they will be used as-is. The <code>node</code> should be a child of the given <code>identity</code> or one of its   ancestors.</li> </ul> <p>The <code>node</code> in this case will control how the off-chain portion of the message is routed via data exchange.</p>"},{"location":"reference/identities/#verification","title":"Verification","text":"<p>When a message is received, FireFly verifies the following:</p> <ul> <li>The sender's <code>author</code> and <code>key</code> are specified in the message. The <code>author</code> must be a known org or custom identity. The <code>key</code> must match the   blockchain key that was used to sign the on-chain portion of the message. For broadcast messages, the <code>key</code> must match the registered   verifier for the <code>author</code>.</li> <li>For private messages, the sending <code>node</code> (as reported by data exchange) must be a known node identity which is a child of the message's   <code>author</code> identity or one of its ancestors. The combination of the <code>author</code> identity and the <code>node</code> must also be found in the message <code>group</code>.</li> </ul> <p>In addition, the data exchange plugin is responsible for verifying the sending and receiving identities for the off-chain data (such as validating the relevant certificates).</p>"},{"location":"reference/namespaces/","title":"Namespaces","text":""},{"location":"reference/namespaces/#introduction-to-namespaces","title":"Introduction to Namespaces","text":"<p>Namespaces are a construct for segregating data and operations within a FireFly supernode. Each namespace is an isolated environment within a FireFly runtime, that allows independent configuration of:</p> <ul> <li>Plugin and infrastructure components</li> <li>API security</li> <li>Identity broadcasting</li> <li>On-chain data indexing</li> <li>How datatypes, locations of on-chain contrats, etc. should be shared</li> </ul> <p>They can be thought of in two basic modes:</p>"},{"location":"reference/namespaces/#multi-party-namespaces","title":"Multi-party Namespaces","text":"<p>This namespace is shared with one or more other FireFly nodes. It requires three types of communication plugins - blockchain, data exchange, and shared storage. Organization and node identities must be claimed with an identity broadcast when joining the namespace, which establishes credentials for blockchain and off-chain communication. Shared objects can be defined in the namespace (such as datatypes and token pools), and details of them will be implicitly broadcast to other members.</p> <p>This type of namespace is used when multiple parties need to share on- and off-chain data and agree upon the ordering and authenticity of that data. For more information, see the multi-party system overview.</p>"},{"location":"reference/namespaces/#gateway-namespaces","title":"Gateway Namespaces","text":"<p>Nothing in this namespace will be shared automatically, and no assumptions are made about whether other parties connected through this namespace are also using Hyperledger FireFly. Plugins for data exchange and shared storage are not supported. If any identities or definitions are created in this namespace, they will be stored in the local database, but will not be shared implicitly outside the node.</p> <p>This type of namespace is mainly used when interacting directly with a blockchain, without assuming that the interaction needs to conform to FireFly's multi-party system model.</p>"},{"location":"reference/namespaces/#configuration","title":"Configuration","text":"<p>FireFly nodes can be configured with one or many namespaces of different modes. This means that a single FireFly node can be used to interact with multiple distinct blockchains, multiple distinct token economies, and multiple business networks.</p> <p>Below is an example plugin and namespace configuration containing both a multi-party and gateway namespace:</p> <pre><code>plugins:\n  database:\n  - name: database0\n    type: sqlite3\n    sqlite3:\n      migrations:\n        auto: true\n      url: /etc/firefly/db?_busy_timeout=5000\n  blockchain:\n  - name: blockchain0\n    type: ethereum\n    ethereum:\n      ethconnect:\n        url: http://ethconnect_0:8080\n        topic: \"0\"\n  - name: blockchain1\n    type: ethereum\n    ethereum:\n      ethconnect:\n        url: http://ethconnect_01:8080\n        topic: \"0\"\n  dataexchange:\n  - name: dataexchange0\n    type: ffdx\n    ffdx:\n      url: http://dataexchange_0:3000\n  sharedstorage:\n  - name: sharedstorage0\n    type: ipfs\n    ipfs:\n      api:\n        url: http://ipfs_0:5001\n      gateway:\n        url: http://ipfs_0:8080\n  tokens:\n  - name: erc20_erc721\n    broadcastName: erc20_erc721\n    type: fftokens\n    fftokens:\n      url: http://tokens_0_0:3000\nnamespaces:\n  default: alpha\n  predefined:\n  - name: alpha\n    description: Default predefined namespace\n    defaultKey: 0x123456\n    plugins: [database0, blockchain0, dataexchange0, sharedstorage0, erc20_erc721]\n    multiparty:\n      networkNamespace: alpha\n      enabled: true\n      org:\n        name: org0\n        description: org0\n        key: 0x123456\n      node:\n        name: node0\n        description: node0\n      contract:\n        - location:\n            address: 0x4ae50189462b0e5d52285f59929d037f790771a6\n          firstEvent: 0\n        - location:\n            address: 0x3c1bef20a7858f5c2f78bda60796758d7cafff27\n          firstEvent: 5000\n  - name: omega\n    defaultkey: 0x48a54f9964d7ceede2d6a8b451bf7ad300c7b09f\n    description: Gateway namespace\n    plugins: [database0, blockchain1, erc20_erc721]\n</code></pre> <p>The <code>namespaces.predefined</code> object contains the follow sub-keys:</p> <ul> <li><code>defaultKey</code> is a blockchain key used to sign transactions when none is specified (in multi-party mode,   defaults to the org key)</li> <li><code>plugins</code> is an array of plugin names to be activated for this namespace (defaults to   all available plugins if omitted)</li> <li><code>multiparty.networkNamespace</code> is the namespace name to be sent in plugin calls, if it differs from the   locally used name (useful for interacting with multiple shared namespaces of the same name -   defaults to the value of <code>name</code>)</li> <li><code>multiparty.enabled</code> controls if multi-party mode is enabled (defaults to true if an org key or   org name is defined on this namespace or in the deprecated <code>org</code> section at the root)</li> <li><code>multiparty.org</code> is the root org identity for this multi-party namespace (containing <code>name</code>,   <code>description</code>, and <code>key</code>)</li> <li><code>multiparty.node</code> is the local node identity for this multi-party namespace (containing <code>name</code> and   <code>description</code>)</li> <li><code>multiparty.contract</code> is an array of objects describing the location(s) of a FireFly multi-party   smart contract. Its children are blockchain-agnostic <code>location</code> and <code>firstEvent</code> fields, with formats   identical to the same fields on custom contract interfaces and contract listeners. The blockchain plugin   will interact with the first contract in the list until instructions are received to terminate it and   migrate to the next.</li> </ul>"},{"location":"reference/namespaces/#config-restrictions","title":"Config Restrictions","text":"<ul> <li><code>name</code> must be unique on this node</li> <li>for historical reasons, \"ff_system\" is a reserved string and cannot be used as a <code>name</code> or <code>multiparty.networkNamespace</code></li> <li>a <code>database</code> plugin is required for every namespace</li> <li>if <code>multiparty.enabled</code> is true, plugins must include one each of <code>blockchain</code>, <code>dataexchange</code>, and   <code>sharedstorage</code></li> <li>if <code>multiparty.enabled</code> is false, plugins must not include <code>dataexchange</code> or <code>sharedstorage</code></li> <li>at most one of each type of plugin is allowed per namespace, except for tokens (which   may have many per namespace)</li> </ul> <p>All namespaces must be called out in the FireFly config file in order to be valid. Namespaces found in the database but not represented in the config file will be ignored.</p>"},{"location":"reference/namespaces/#definitions","title":"Definitions","text":"<p>In FireFly, definitions are immutable payloads that are used to define identities, datatypes, smart contract interfaces, token pools, and other constructs. Each type of definition in FireFly has a schema that it must adhere to. Some definitions also have a name and a version which must be unique within a namespace. In a multiparty namespace, definitions are broadcasted to other organizations.</p>"},{"location":"reference/namespaces/#local-definitions","title":"Local Definitions","text":"<p>The following are all \"definition\" types in FireFly:</p> <ul> <li>datatype</li> <li>group</li> <li>token pool</li> <li>contract interface</li> <li>contract API</li> <li>organization (deprecated)</li> <li>node (deprecated)</li> <li>identity claim</li> <li>identity verification</li> <li>identity update</li> </ul> <p>For gateway namespaces, the APIs which create these definitions will become an immediate local database insert, instead of performing a broadcast. Additional caveats:</p> <ul> <li>identities in this mode will not undergo any claim/verification process,   but will be created and stored locally</li> <li>datatypes and groups will not be supported, as they are only useful in the context   of messaging (which is disabled in gateway namespaces)</li> </ul>"},{"location":"reference/tls/","title":"TLS","text":""},{"location":"reference/tls/#tls-overview","title":"TLS Overview","text":"<p>To enable TLS in Firefly, there is a configuration available to provide certificates and keys.</p> <p>The common configuration is as such:</p> <pre><code>tls:\n  enabled: true/false # Toggle on or off TLS\n  caFile: &lt;path to the CA file you want the client or server to trust&gt;\n  certFile: &lt;path to the cert file you want the client or server to use when performing authentication in mTLS&gt;\n  keyFile: &lt;path to the priavte key file you want the client or server to use when performing  authentication in mTLS&gt;\n  clientAuth: true/false # Only applicable to the server side, to toggle on or off client authentication\n  requiredDNAttributes: A set of required subject DN attributes. Each entry is a regular expression, and the subject certificate must have a matching attribute of the specified type (CN, C, O, OU, ST, L, STREET, POSTALCODE, SERIALNUMBER are valid attributes)\n</code></pre> <p>NOTE The CAs, certificates and keys have to be in PEM format.</p>"},{"location":"reference/tls/#configuring-tls-for-the-api-server","title":"Configuring TLS for the API server","text":"<p>Using the above configuration, we can place it under the <code>http</code> config and enable TLS or mTLS for any API call.</p> <p>See this config section for details</p>"},{"location":"reference/tls/#configuring-tls-for-the-webhooks","title":"Configuring TLS for the webhooks","text":"<p>Using the above configuration, we can place it under the <code>events.webhooks</code> config and enable TLS or mTLS for any webhook call.</p> <p>See this config section for details</p>"},{"location":"reference/tls/#configuring-clients-and-websockets","title":"Configuring clients and websockets","text":"<p>Firefly has a set of HTTP clients and websockets that communicate the external endpoints and services that could be secured using TLS. In order to configure these clients, we can use the same configuration as above in the respective places in the config which relate to those clients.</p> <p>For example, if you wish to configure the ethereum blockchain connector with TLS you would look at this config section</p> <p>For more clients, search in the configuration reference for a TLS section.</p>"},{"location":"reference/tls/#enhancing-validation-of-certificates","title":"Enhancing validation of certificates","text":"<p>In the case where we want to verify that a specific client certificate has certain attributes we can use the <code>requiredDNAtributes</code> configuration as described above. This will allow you by the means of a regex expresssion matching against well known distinguished names (DN). To learn more about a DNs look at this document</p>"},{"location":"reference/microservices/fftokens/","title":"fftokens","text":""},{"location":"reference/microservices/fftokens/#overview","title":"Overview","text":"<p>fftokens is a protocol that can be implemented by token connector runtimes in order to be usable by the fftokens plugin in FireFly.</p> <p>The connector runtime must expose an HTTP and websocket server, along with a minimum set of HTTP APIs and websocket events. Each connector will be strongly coupled to a specific ledger technology and token standard(s), but no assumptions are made in the fftokens spec about what these technologies must be, as long as they can satisfy the basic requirements laid out here.</p> <p>Note that this is an internal protocol in the FireFly ecosystem - application developers working against FireFly should never need to care about or directly interact with a token connector runtime. The audience for this document is only developers interested in creating new token connectors (or editing/forking existing ones).</p> <p>Two implementations of this specification have been created to date (both based on common Ethereum token standards) - firefly-tokens-erc1155 and firefly-tokens-erc20-erc721.</p>"},{"location":"reference/microservices/fftokens/#http-apis","title":"HTTP APIs","text":"<p>This is the minimum set of APIs that must be implemented by a conforming token connector. A connector may choose to expose other APIs for its own purposes. All requests and responses to the APIs below are encoded as JSON. The APIs are currently understood to live under a <code>/api/v1</code> prefix.</p>"},{"location":"reference/microservices/fftokens/#post-createpool","title":"<code>POST /createpool</code>","text":"<p>Create a new token pool. The exact meaning of this is flexible - it may mean invoking a contract or contract factory to actually define a new set of tokens via a blockchain transaction, or it may mean indexing a set of tokens that already exists (depending on the options a connector accepts in <code>config</code>).</p> <p>In a multiparty network, this operation will only be performed by one of the parties, and FireFly will broadcast the result to the others.</p> <p>FireFly will store a \"pending\" token pool after a successful creation, but will replace it with a \"confirmed\" token pool after a successful activation (see below).</p> <p>Request</p> <pre><code>{\n  \"type\": \"fungible\",\n  \"signer\": \"0x0Ef1D0Dd56a8FB1226C0EaC374000B81D6c8304A\",\n  \"namespace\": \"default\",\n  \"name\": \"FFCoin\",\n  \"symbol\": \"FFC\",\n  \"data\": \"pool-metadata\",\n  \"requestId\": \"1\",\n  \"config\": {}\n}\n</code></pre> Parameter Type Description type string enum The type of pool to create. Currently supported types are \"fungible\" and \"nonfungible\". It is recommended (but not required) that token connectors support both. Unrecognized/unsupported types should be rejected with HTTP 400. signer string The signing identity to be used for the blockchain transaction, in a format understood by this connector. namespace string The namespace of the token pool name string (OPTIONAL) If supported by this token contract, this is a requested name for the token pool. May be ignored at the connector's discretion. symbol string (OPTIONAL) If supported by this token contract, this is a requested symbol for the token pool. May be ignored at the connector's discretion. requestId string (OPTIONAL) A unique identifier for this request. Will be included in the \"receipt\" websocket event to match receipts to requests. data string (OPTIONAL) A data string that should be returned in the connector's response to this creation request. config object (OPTIONAL) An arbitrary JSON object where the connector may accept additional parameters if desired. Each connector may define its own valid options to influence how the token pool is created. <p>Response</p> <p>HTTP 200: pool creation was successful, and the pool details are returned in the response.</p> <p>See Response Types: Token Pool</p> <p>HTTP 202: request was accepted, but pool will be created asynchronously, with \"receipt\" and \"token-pool\" events sent later on the websocket.</p> <p>See Response Types: Async Request</p>"},{"location":"reference/microservices/fftokens/#post-activatepool","title":"<code>POST /activatepool</code>","text":"<p>Activate a token pool to begin receiving events. Generally this means the connector will create blockchain event listeners for transfer and approval events related to the set of tokens encompassed by this token pool.</p> <p>In a multiparty network, this step will be performed by every member after a successful token pool broadcast. It therefore also serves the purpose of validating the broadcast info - if the connector does not find a valid pool given the <code>poolLocator</code> and <code>config</code> information passed in to this call, the pool should not get confirmed.</p> <p>Request</p> <pre><code>{\n  \"namespace\": \"default\",\n  \"poolLocator\": \"id=F1\",\n  \"poolData\": \"extra-pool-info\",\n  \"config\": {}\n}\n</code></pre> Parameter Type Description namespace string The namespace of the token pool poolLocator string The locator of the pool, as supplied by the output of the pool creation. poolData string (OPTIONAL) A data string that should be permanently attached to this pool and returned in all events. config object (OPTIONAL) An arbitrary JSON object where the connector may accept additional parameters if desired. This should be the same <code>config</code> object that was passed when the pool was created. <p>Response</p> <p>HTTP 200: pool activation was successful, and the pool details are returned in the response.</p> <p>See Response Types: Token Pool</p> <p>HTTP 202: request was accepted, but pool will be activated asynchronously, with \"receipt\" and \"token-pool\" events sent later on the websocket.</p> <p>See Response Types: Async Request</p> <p>HTTP 204: activation was successful - no separate receipt will be delivered, but \"token-pool\" event will be sent later on the websocket.</p> <p>No body</p>"},{"location":"reference/microservices/fftokens/#post-deactivatepool","title":"<code>POST /deactivatepool</code>","text":"<p>Deactivate a token pool to stop receiving events and delete all blockchain listeners related to that pool.</p> <p>Request</p> <pre><code>{\n  \"namespace\": \"default\",\n  \"poolLocator\": \"id=F1\",\n  \"poolData\": \"extra-pool-info\",\n  \"config\": {}\n}\n</code></pre> Parameter Type Description namespace string The namespace of the token pool poolLocator string The locator of the pool, as supplied by the output of the pool creation. poolData string (OPTIONAL) The data string that was attached to this pool at activation. config object (OPTIONAL) An arbitrary JSON object where the connector may accept additional parameters if desired. <p>Response</p> <p>HTTP 204: deactivation was successful, and one or more listeners were deleted.</p> <p>No body</p> <p>HTTP 404: no blockchain listeners were found for the given pool information.</p> <p>No body</p>"},{"location":"reference/microservices/fftokens/#post-checkinterface","title":"<code>POST /checkinterface</code>","text":"<p>This is an optional (but recommended) API for token connectors. If implemented, support will be indicated by the presence of the <code>interfaceFormat</code> field in all Token Pool responses.</p> <p>In the case that a connector supports multiple variants of a given token standard (such as many different ways to structure \"mint\" or \"burn\" calls on an underlying smart contract), this API allows the connector to be provided with a full description of the interface methods in use for a given token pool, so the connector can determine which methods it knows how to invoke.</p> <p>Request</p> <pre><code>{\n  \"poolLocator\": \"id=F1\",\n  \"format\": \"abi\",\n  \"methods\": [\n    {\n      \"name\": \"burn\",\n      \"type\": \"function\",\n      \"inputs\": [\n        {\n          \"internalType\": \"uint256\",\n          \"name\": \"tokenId\",\n          \"type\": \"uint256\"\n        }\n      ],\n      \"outputs\": [],\n      \"stateMutability\": \"nonpayable\"\n    },\n    ...\n  ]\n}\n</code></pre> Parameter Type Description poolLocator string The locator of the pool, as supplied by the output of the pool creation. format string enum The format of the data in this payload. Should match the <code>interfaceFormat</code> as supplied by the output of the pool creation. methods object array A list of all the methods available on the interface underpinning this token pool, encoded in the format specified by <code>format</code>. <p>Response</p> <p>HTTP 200: interface was successfully parsed, and methods of interest are returned in the body.</p> <p>The response body includes a section for each type of token operation (burn/mint/transfer/approval), which specifies a subset of the input body useful to that operation. The caller (FireFly) can then store and provide the proper subset of the interface for every future token operation (via the <code>interface</code> parameter).</p> <pre><code>{\n  \"burn\": {\n    \"format\": \"abi\",\n    \"methods\": [\n      {\n        \"name\": \"burn\",\n        \"type\": \"function\",\n        \"inputs\": [\n          {\n            \"internalType\": \"uint256\",\n            \"name\": \"tokenId\",\n            \"type\": \"uint256\"\n          }\n        ],\n        \"outputs\": [],\n        \"stateMutability\": \"nonpayable\"\n      }\n    ]\n  },\n  \"mint\": { ... },\n  \"transfer\": { ... },\n  \"approval\": { ... }\n}\n</code></pre>"},{"location":"reference/microservices/fftokens/#post-mint","title":"<code>POST /mint</code>","text":"<p>Mint new tokens.</p> <p>Request</p> <pre><code>{\n  \"namespace\": \"default\",\n  \"poolLocator\": \"id=F1\",\n  \"signer\": \"0x0Ef1D0Dd56a8FB1226C0EaC374000B81D6c8304A\",\n  \"to\": \"0x0Ef1D0Dd56a8FB1226C0EaC374000B81D6c8304A\",\n  \"amount\": \"10\",\n  \"tokenIndex\": \"1\",\n  \"uri\": \"ipfs://000000\",\n  \"requestId\": \"1\",\n  \"data\": \"transfer-metadata\",\n  \"config\": {},\n  \"interface\": {}\n}\n</code></pre> Parameter Type Description namespace string The namespace of the token pool poolLocator string The locator of the pool, as supplied by the output of the pool creation. signer string The signing identity to be used for the blockchain transaction, in a format understood by this connector. to string The identity to receive the minted tokens, in a format understood by this connector. amount number string The amount of tokens to mint. tokenIndex string (OPTIONAL) For non-fungible tokens that require choosing an index at mint time, the index of the specific token to mint. uri string (OPTIONAL) For non-fungible tokens that support choosing a URI at mint time, the URI to be attached to the token. requestId string (OPTIONAL) A unique identifier for this request. Will be included in the \"receipt\" websocket event to match receipts to requests. data string (OPTIONAL) A data string that should be returned in the connector's response to this mint request. config object (OPTIONAL) An arbitrary JSON object where the connector may accept additional parameters if desired. Each connector may define its own valid options to influence how the mint is carried out. interface object (OPTIONAL) Details on interface methods that are useful to this operation, as negotiated previously by a <code>/checkinterface</code> call. <p>Response</p> <p>HTTP 202: request was accepted, but mint will occur asynchronously, with \"receipt\" and \"token-mint\" events sent later on the websocket.</p> <p>See Response Types: Async Request</p>"},{"location":"reference/microservices/fftokens/#post-burn","title":"<code>POST /burn</code>","text":"<p>Burn tokens.</p> <p>Request</p> <pre><code>{\n  \"namespace\": \"default\",\n  \"poolLocator\": \"id=F1\",\n  \"signer\": \"0x0Ef1D0Dd56a8FB1226C0EaC374000B81D6c8304A\",\n  \"from\": \"0x0Ef1D0Dd56a8FB1226C0EaC374000B81D6c8304A\",\n  \"amount\": \"10\",\n  \"tokenIndex\": \"1\",\n  \"requestId\": \"1\",\n  \"data\": \"transfer-metadata\",\n  \"config\": {},\n  \"interface\": {}\n}\n</code></pre> Parameter Type Description namespace string The namespace of the token pool poolLocator string The locator of the pool, as supplied by the output of the pool creation. signer string The signing identity to be used for the blockchain transaction, in a format understood by this connector. from string The identity that currently owns the tokens to be burned, in a format understood by this connector. amount number string The amount of tokens to burn. tokenIndex string (OPTIONAL) For non-fungible tokens, the index of the specific token to burn. requestId string (OPTIONAL) A unique identifier for this request. Will be included in the \"receipt\" websocket event to match receipts to requests. data string (OPTIONAL) A data string that should be returned in the connector's response to this burn request. config object (OPTIONAL) An arbitrary JSON object where the connector may accept additional parameters if desired. Each connector may define its own valid options to influence how the burn is carried out. interface object (OPTIONAL) Details on interface methods that are useful to this operation, as negotiated previously by a <code>/checkinterface</code> call. <p>Response</p> <p>HTTP 202: request was accepted, but burn will occur asynchronously, with \"receipt\" and \"token-burn\" events sent later on the websocket.</p> <p>See Response Types: Async Request</p>"},{"location":"reference/microservices/fftokens/#post-transfer","title":"<code>POST /transfer</code>","text":"<p>Transfer tokens from one address to another.</p> <p>Request</p> <pre><code>{\n  \"namespace\": \"default\",\n  \"poolLocator\": \"id=F1\",\n  \"signer\": \"0x0Ef1D0Dd56a8FB1226C0EaC374000B81D6c8304A\",\n  \"from\": \"0x0Ef1D0Dd56a8FB1226C0EaC374000B81D6c8304A\",\n  \"to\": \"0xb107ed9caa1323b7bc36e81995a4658ec2251951\",\n  \"amount\": \"1\",\n  \"tokenIndex\": \"1\",\n  \"requestId\": \"1\",\n  \"data\": \"transfer-metadata\",\n  \"config\": {},\n  \"interface\": {}\n}\n</code></pre> Parameter Type Description namespace string The namespace of the token pool poolLocator string The locator of the pool, as supplied by the output of the pool creation. signer string The signing identity to be used for the blockchain transaction, in a format understood by this connector. from string The identity to be used for the source of the transfer, in a format understood by this connector. to string The identity to be used for the destination of the transfer, in a format understood by this connector. amount number string The amount of tokens to transfer. tokenIndex string (OPTIONAL) For non-fungible tokens, the index of the specific token to transfer. requestId string (OPTIONAL) A unique identifier for this request. Will be included in the \"receipt\" websocket event to match receipts to requests. data string (OPTIONAL) A data string that should be returned in the connector's response to this transfer request. config object (OPTIONAL) An arbitrary JSON object where the connector may accept additional parameters if desired. Each connector may define its own valid options to influence how the transfer is carried out. interface object (OPTIONAL) Details on interface methods that are useful to this operation, as negotiated previously by a <code>/checkinterface</code> call. <p>Response</p> <p>HTTP 202: request was accepted, but transfer will occur asynchronously, with \"receipt\" and \"token-transfer\" events sent later on the websocket.</p> <p>See Response Types: Async Request</p>"},{"location":"reference/microservices/fftokens/#post-approval","title":"<code>POST /approval</code>","text":"<p>Approve another identity to manage tokens.</p> <p>Request</p> <pre><code>{\n  \"namespace\": \"default\",\n  \"poolLocator\": \"id=F1\",\n  \"signer\": \"0x0Ef1D0Dd56a8FB1226C0EaC374000B81D6c8304A\",\n  \"operator\": \"0xb107ed9caa1323b7bc36e81995a4658ec2251951\",\n  \"approved\": true,\n  \"requestId\": \"1\",\n  \"data\": \"approval-metadata\",\n  \"config\": {},\n  \"interface\": {}\n}\n</code></pre> Parameter Type Description namespace string The namespace of the token pool poolLocator string The locator of the pool, as supplied by the output of the pool creation. signer string The signing identity to be used for the blockchain transaction, in a format understood by this connector. operator string The identity to be approved (or unapproved) for managing the signer's tokens. approved boolean Whether to approve (the default) or unapprove. requestId string (OPTIONAL) A unique identifier for this request. Will be included in the \"receipt\" websocket event to match receipts to requests. data string (OPTIONAL) A data string that should be returned in the connector's response to this approval request. config object (OPTIONAL) An arbitrary JSON object where the connector may accept additional parameters if desired. Each connector may define its own valid options to influence how the approval is carried out. interface object (OPTIONAL) Details on interface methods that are useful to this operation, as negotiated previously by a <code>/checkinterface</code> call. <p>Response</p> <p>HTTP 202: request was accepted, but approval will occur asynchronously, with \"receipt\" and \"token-approval\" events sent later on the websocket.</p> <p>See Response Types: Async Request</p>"},{"location":"reference/microservices/fftokens/#websocket-commands","title":"Websocket Commands","text":"<p>In order to start listening for events on a certain namespace, the client needs to send the <code>start</code> command. Clients should send this command every time they connect, or after an automatic reconnect.</p> <pre><code>{\n  \"type\": \"start\",\n  \"namespace\": \"default\"\n}\n</code></pre>"},{"location":"reference/microservices/fftokens/#websocket-events","title":"Websocket Events","text":"<p>A connector should expose a websocket at <code>/api/ws</code>. All emitted websocket events are a JSON string of the form:</p> <pre><code>{\n  \"id\": \"event-id\",\n  \"event\": \"event-name\",\n  \"data\": {}\n}\n</code></pre> <p>The <code>event</code> name will match one of the names listed below, and the <code>data</code> payload will correspond to the linked response object.</p> <p>All events except the receipt event must be acknowledged by sending an ack of the form:</p> <pre><code>{\n  \"event\": \"ack\",\n  \"data\": {\n    \"id\": \"event-id\"\n  }\n}\n</code></pre> <p>Many messages may also be batched into a single websocket event of the form:</p> <pre><code>{\n  \"id\": \"event-id\",\n  \"event\": \"batch\",\n  \"data\": {\n    \"events\": [\n      {\n        \"event\": \"event-name\",\n        \"data\": {}\n      },\n      ...\n    ]\n  }\n}\n</code></pre> <p>Batched messages must be acked all at once using the ID of the batch.</p>"},{"location":"reference/microservices/fftokens/#receipt","title":"<code>receipt</code>","text":"<p>An asynchronous operation has completed.</p> <p>See Response Types: Receipt</p>"},{"location":"reference/microservices/fftokens/#token-pool","title":"<code>token-pool</code>","text":"<p>A new token pool has been created or activated.</p> <p>See Response Types: Token Pool</p>"},{"location":"reference/microservices/fftokens/#token-mint","title":"<code>token-mint</code>","text":"<p>Tokens have been minted.</p> <p>See Response Types: Token Transfer</p>"},{"location":"reference/microservices/fftokens/#token-burn","title":"<code>token-burn</code>","text":"<p>Tokens have been burned.</p> <p>See Response Types: Token Transfer</p>"},{"location":"reference/microservices/fftokens/#token-transfer","title":"<code>token-transfer</code>","text":"<p>Tokens have been transferred.</p> <p>See Response Types: Token Transfer</p>"},{"location":"reference/microservices/fftokens/#token-approval","title":"<code>token-approval</code>","text":"<p>Token approvals have changed.</p> <p>See Response Types: Token Approval</p>"},{"location":"reference/microservices/fftokens/#response-types","title":"Response Types","text":""},{"location":"reference/microservices/fftokens/#async-request","title":"Async Request","text":"<p>Many operations may happen asynchronously in the background, and will return only a request ID. This may be a request ID that was passed in, or if none was passed, will be randomly assigned. This ID can be used to correlate with a receipt event later received on the websocket.</p> <pre><code>{\n  \"id\": \"b84ab27d-0d50-42a6-9c26-2fda5eb901ba\"\n}\n</code></pre>"},{"location":"reference/microservices/fftokens/#receipt_1","title":"Receipt","text":"<pre><code>  \"headers\": {\n    \"type\": \"\",\n    \"requestId\": \"\"\n  }\n  \"transactionHash\": \"\",\n  \"errorMessage\": \"\"\n}\n</code></pre> Parameter Type Description headers.type string enum The type of this response. Should be \"TransactionSuccess\", \"TransactionUpdate\", or \"TransactionFailed\". headers.requestId string The ID of the request to which this receipt should correlate. transactionHash string The unique identifier for the blockchain transaction which generated this receipt. errorMessage string (OPTIONAL) If this is a failure, contains details on the reason for the failure."},{"location":"reference/microservices/fftokens/#token-pool_1","title":"Token Pool","text":"<pre><code>{\n  \"namespace\": \"default\",\n  \"type\": \"fungible\",\n  \"data\": \"pool-metadata\",\n  \"poolLocator\": \"id=F1\",\n  \"standard\": \"ERC20\",\n  \"interfaceFormat\": \"abi\",\n  \"symbol\": \"FFC\",\n  \"decimals\": 18,\n  \"info\": {},\n  \"signer\": \"0x0Ef1D0Dd56a8FB1226C0EaC374000B81D6c8304A\",\n  \"blockchain\": {}\n}\n</code></pre> Parameter Type Description namespace string The namespace of the token pool type string enum The type of pool that was created. data string A copy of the data that was passed in on the creation request. poolLocator string A string to identify this pool, generated by the connector. Must be unique for each pool created by this connector. Will be passed back on all operations within this pool, and may be packed with relevant data about the pool for later usage (such as the address and type of the pool). standard string (OPTIONAL) The name of a well-defined token standard to which this pool conforms. interfaceFormat string enum (OPTIONAL) If this connector supports the <code>/checkinterface</code> API, this is the interface format to be used for describing the interface underpinning this pool. Must be \"abi\" or \"ffi\". symbol string (OPTIONAL) The symbol for this token pool, if applicable. decimals number (OPTIONAL) The number of decimals used for balances in this token pool, if applicable. info object (OPTIONAL) Additional information about the pool. Each connector may define the format for this object. signer string (OPTIONAL) If this operation triggered a blockchain transaction, the signing identity used for the transaction. blockchain object (OPTIONAL) If this operation triggered a blockchain transaction, contains details on the blockchain event in FireFly's standard blockchain event format."},{"location":"reference/microservices/fftokens/#token-transfer_1","title":"Token Transfer","text":"<p>Note that mint and burn operations are just specialized versions of transfer. A mint will omit the \"from\" field, while a burn will omit the \"to\" field.</p> <pre><code>{\n  \"namespace\": \"default\",\n  \"id\": \"1\",\n  \"data\": \"transfer-metadata\",\n  \"poolLocator\": \"id=F1\",\n  \"poolData\": \"extra-pool-info\",\n  \"from\": \"0x0Ef1D0Dd56a8FB1226C0EaC374000B81D6c8304A\",\n  \"to\": \"0xb107ed9caa1323b7bc36e81995a4658ec2251951\",\n  \"amount\": \"1\",\n  \"tokenIndex\": \"1\",\n  \"uri\": \"ipfs://000000\",\n  \"signer\": \"0x0Ef1D0Dd56a8FB1226C0EaC374000B81D6c8304A\",\n  \"blockchain\": {}\n}\n</code></pre> Parameter Type Description namespace string The namespace of the token pool id string An identifier for this transfer. Must be unique for every transfer within this pool. data string A copy of the data that was passed in on the mint/burn/transfer request. May be omitted if the token contract does not support a method of attaching extra data (will result in reduced ability for FireFly to correlate the inputs and outputs of the transaction). poolLocator string The locator of the pool, as supplied by the output of the pool creation. poolData string The extra data associated with the pool at pool activation. from string The identity used for the source of the transfer. to string The identity used for the destination of the transfer. amount number string The amount of tokens transferred. tokenIndex string (OPTIONAL) For non-fungible tokens, the index of the specific token transferred. uri string (OPTIONAL) For non-fungible tokens, the URI attached to the token. signer string (OPTIONAL) If this operation triggered a blockchain transaction, the signing identity used for the transaction. blockchain object (OPTIONAL) If this operation triggered a blockchain transaction, contains details on the blockchain event in FireFly's standard blockchain event format."},{"location":"reference/microservices/fftokens/#token-approval_1","title":"Token Approval","text":"<pre><code>{\n  \"namespace\": \"default\",\n  \"id\": \"1\",\n  \"data\": \"transfer-metadata\",\n  \"poolLocator\": \"id=F1\",\n  \"poolData\": \"extra-pool-info\",\n  \"operator\": \"0xb107ed9caa1323b7bc36e81995a4658ec2251951\",\n  \"approved\": true,\n  \"subject\": \"0x0Ef1D0Dd56a8FB1226C0EaC374000B81D6c8304A:0xb107ed9caa1323b7bc36e81995a4658ec2251951\",\n  \"info\": {},\n  \"signer\": \"0x0Ef1D0Dd56a8FB1226C0EaC374000B81D6c8304A\",\n  \"blockchain\": {}\n}\n</code></pre> Parameter Type Description namespace string The namespace of the token pool id string An identifier for this approval. Must be unique for every approval within this pool. data string A copy of the data that was passed in on the approval request. May be omitted if the token contract does not support a method of attaching extra data (will result in reduced ability for FireFly to correlate the inputs and outputs of the transaction). poolLocator string The locator of the pool, as supplied by the output of the pool creation. poolData string The extra data associated with the pool at pool activation. operator string The identity that was approved (or unapproved) for managing tokens. approved boolean Whether this was an approval or unapproval. subject string A string identifying the scope of the approval, generated by the connector. Approvals with the same subject are understood replace one another, so that a previously-recorded approval becomes inactive. This string may be a combination of the identities involved, the token index, etc. info object (OPTIONAL) Additional information about the approval. Each connector may define the format for this object. signer string (OPTIONAL) If this operation triggered a blockchain transaction, the signing identity used for the transaction. blockchain object (OPTIONAL) If this operation triggered a blockchain transaction, contains details on the blockchain event in FireFly's standard blockchain event format."},{"location":"reference/types/batch/","title":"Batch","text":"<p>A batch bundles a number of off-chain messages, with associated data, into a single payload for broadcast or private transfer.</p> <p>This allows the transfer of many messages (hundreds) to be backed by a single blockchain transaction. Thus making very efficient use of the blockchain.</p> <p>The same benefit also applies to the off-chain transport mechanism.</p> <p>Shared storage operations benefit from the same optimization. In IPFS for example chunks are 256Kb in size, so there is a great throughput benefit in packaging many small messages into a single large payload.</p> <p>For a data exchange transport, there is often cryptography and transport overhead for each individual transport level send between participants. This is particularly true if using a data exchange transport with end-to-end payload encryption, using public/private key cryptography for the envelope.</p>"},{"location":"reference/types/batch/#example","title":"Example","text":"<pre><code>{\n    \"id\": \"894bc0ea-0c2e-4ca4-bbca-b4c39a816bbb\",\n    \"type\": \"private\",\n    \"namespace\": \"ns1\",\n    \"node\": \"5802ab80-fa71-4f52-9189-fb534de93756\",\n    \"group\": \"cd1fedb69fb83ad5c0c62f2f5d0b04c59d2e41740916e6815a8e063b337bd32e\",\n    \"created\": \"2022-05-16T01:23:16Z\",\n    \"author\": \"did:firefly:org/example\",\n    \"key\": \"0x0a989907dcd17272257f3ebcf72f4351df65a846\",\n    \"hash\": \"78d6861f860c8724468c9254b99dc09e7d9fd2d43f26f7bd40ecc9ee47be384d\",\n    \"payload\": {\n        \"tx\": {\n            \"type\": \"private\",\n            \"id\": \"04930d84-0227-4044-9d6d-82c2952a0108\"\n        },\n        \"messages\": [],\n        \"data\": []\n    }\n}\n</code></pre>"},{"location":"reference/types/batch/#field-descriptions","title":"Field Descriptions","text":"Field Name Description Type <code>id</code> The UUID of the batch <code>UUID</code> <code>type</code> The type of the batch <code>FFEnum</code>:<code>\"broadcast\"</code><code>\"private\"</code> <code>namespace</code> The namespace of the batch <code>string</code> <code>node</code> The UUID of the node that generated the batch <code>UUID</code> <code>group</code> The privacy group the batch is sent to, for private batches <code>Bytes32</code> <code>created</code> The time the batch was sealed <code>FFTime</code> <code>author</code> The DID of identity of the submitter <code>string</code> <code>key</code> The on-chain signing key used to sign the transaction <code>string</code> <code>hash</code> The hash of the manifest of the batch <code>Bytes32</code> <code>payload</code> Batch.payload <code>BatchPayload</code>"},{"location":"reference/types/batch/#batchpayload","title":"BatchPayload","text":"Field Name Description Type <code>tx</code> BatchPayload.tx <code>TransactionRef</code> <code>messages</code> BatchPayload.messages <code>Message[]</code> <code>data</code> BatchPayload.data <code>Data[]</code>"},{"location":"reference/types/batch/#transactionref","title":"TransactionRef","text":"Field Name Description Type <code>type</code> The type of the FireFly transaction <code>FFEnum</code>: <code>id</code> The UUID of the FireFly transaction <code>UUID</code>"},{"location":"reference/types/blockchainevent/","title":"BlockchainEvent","text":"<p>Blockchain Events are detected by the blockchain plugin:</p> <ol> <li>When a ContractListener has been    configured against any custom smart contract through the FireFly API</li> <li>Indirectly via a Token Connector, which understands the correct events    to listen to for a Token Pool configured against a    standard such as ERC-20/ERC-721/ERC-1155</li> <li>Automatically by FireFly core, for the BatchPin contract that can    be used for high throughput batched pinning of off-chain data transfers    to the blockchain (complementary to using your own smart contracts).</li> </ol>"},{"location":"reference/types/blockchainevent/#protocol-id","title":"Protocol ID","text":"<p>Each Blockchain Event (once final) exists in an absolute location somewhere in the transaction history of the blockchain. A particular slot, in a particular block.</p> <p>How to describe that position contains blockchain specifics - depending on how a particular blockchain represents transactions, blocks and events (or \"logs\").</p> <p>So FireFly is flexible with a string <code>protocolId</code> in the core object to represent this location, and then there is a convention that is adopted by the blockchain plugins to try and create some consistency.</p> <p>An example <code>protocolId</code> string is: <code>000000000041/000020/000003</code></p> <ul> <li><code>000000000041</code> - this is the block number</li> <li><code>000020</code> - this is the transaction index within that block</li> <li><code>000003</code> - this is the event (/log) index within that block</li> </ul> <p>The string is alphanumerically sortable as a plain string;</p> <p>Sufficient zero padding is included at each layer to support future expansion without creating a string that would no longer sort correctly.</p>"},{"location":"reference/types/blockchainevent/#example","title":"Example","text":"<pre><code>{\n    \"id\": \"e9bc4735-a332-4071-9975-b1066e51ab8b\",\n    \"source\": \"ethereum\",\n    \"namespace\": \"ns1\",\n    \"name\": \"MyEvent\",\n    \"listener\": \"c29b4595-03c2-411a-89e3-8b7f27ef17bb\",\n    \"protocolId\": \"000000000048/000000/000000\",\n    \"output\": {\n        \"addr1\": \"0x55860105d6a675dbe6e4d83f67b834377ba677ad\",\n        \"value2\": \"42\"\n    },\n    \"info\": {\n        \"address\": \"0x57A9bE18CCB50D06B7567012AaF6031D669BBcAA\",\n        \"blockHash\": \"0xae7382ef2573553f517913b927d8b9691ada8d617266b8b16f74bb37aa78cae8\",\n        \"blockNumber\": \"48\",\n        \"logIndex\": \"0\",\n        \"signature\": \"Changed(address,uint256)\",\n        \"subId\": \"sb-e4d5efcd-2eba-4ed1-43e8-24831353fffc\",\n        \"timestamp\": \"1653048837\",\n        \"transactionHash\": \"0x34b0327567fefed09ac7b4429549bc609302b08a9cbd8f019a078ec44447593d\",\n        \"transactionIndex\": \"0x0\"\n    },\n    \"timestamp\": \"2022-05-16T01:23:15Z\",\n    \"tx\": {\n        \"blockchainId\": \"0x34b0327567fefed09ac7b4429549bc609302b08a9cbd8f019a078ec44447593d\"\n    }\n}\n</code></pre>"},{"location":"reference/types/blockchainevent/#field-descriptions","title":"Field Descriptions","text":"Field Name Description Type <code>id</code> The UUID assigned to the event by FireFly <code>UUID</code> <code>source</code> The blockchain plugin or token service that detected the event <code>string</code> <code>namespace</code> The namespace of the listener that detected this blockchain event <code>string</code> <code>name</code> The name of the event in the blockchain smart contract <code>string</code> <code>listener</code> The UUID of the listener that detected this event, or nil for built-in events in the system namespace <code>UUID</code> <code>protocolId</code> An alphanumerically sortable string that represents this event uniquely on the blockchain (convention for plugins is zero-padded values BLOCKNUMBER/TXN_INDEX/EVENT_INDEX) <code>string</code> <code>output</code> The data output by the event, parsed to JSON according to the interface of the smart contract <code>JSONObject</code> <code>info</code> Detailed blockchain specific information about the event, as generated by the blockchain connector <code>JSONObject</code> <code>timestamp</code> The time allocated to this event by the blockchain. This is the block timestamp for most blockchain connectors <code>FFTime</code> <code>tx</code> If this blockchain event is coorelated to FireFly transaction such as a FireFly submitted token transfer, this field is set to the UUID of the FireFly transaction <code>BlockchainTransactionRef</code>"},{"location":"reference/types/blockchainevent/#blockchaintransactionref","title":"BlockchainTransactionRef","text":"Field Name Description Type <code>type</code> The type of the FireFly transaction <code>FFEnum</code>: <code>id</code> The UUID of the FireFly transaction <code>UUID</code> <code>blockchainId</code> The blockchain transaction ID, in the format specific to the blockchain involved in the transaction. Not all FireFly transactions include a blockchain <code>string</code>"},{"location":"reference/types/contractapi/","title":"ContractAPI","text":"<p>Contract APIs provide generated REST APIs for on-chain smart contracts.</p> <p>API endpoints are generated to invoke or perform query operations against each of the functions/methods implemented by the smart contract.</p> <p>API endpoints are also provided to add listeners to the events of that smart contract.</p> <p>Note that once you have established listeners for your blockchain events into FireFly, you need to also subscribe in your application to receive the FireFly events (of type <code>blockchain_event_received</code>) that are emitted for each detected blockchain event.</p> <p>For more information see the Events reference section.</p>"},{"location":"reference/types/contractapi/#url","title":"URL","text":"<p>The base path for your Contract API is:</p> <ul> <li><code>/api/v1/namespaces/{ns}/apis/{apiName}</code></li> </ul> <p>For the default namespace, this can be shortened to:</p> <ul> <li><code>/api/v1/apis/{apiName}</code></li> </ul>"},{"location":"reference/types/contractapi/#firefly-interface-ffi-and-on-chain-location","title":"FireFly Interface (FFI) and On-chain Location","text":"<p>Contract APIs are registered against:</p> <ol> <li> <p>A FireFly Interface (FFI) definition, which defines in a blockchain agnostic    format the list of functions/events supported by the smart contract. Also    detailed type information about the inputs/outputs to those functions/events.</p> </li> <li> <p>An optional <code>location</code> configured on the Contract API describes where the    instance of the smart contract the API should interact with exists in the blockchain layer.    For example the <code>address</code> of the Smart Contract for an Ethereum based blockchain,    or the <code>name</code> and <code>channel</code> for a Hyperledger Fabric based blockchain.</p> </li> </ol> <p>If the <code>location</code> is not specified on creation of the Contract API, then it must be specified on each API call made to the Contract API endpoints.</p>"},{"location":"reference/types/contractapi/#openapi-v3-swagger-definitions","title":"OpenAPI V3 / Swagger Definitions","text":"<p>Each Contract API comes with an OpenAPI V3 / Swagger generated definition, which can be downloaded from:</p> <ul> <li><code>/api/v1/namespaces/{namespaces}/apis/{apiName}/api/swagger.json</code></li> </ul>"},{"location":"reference/types/contractapi/#swagger-ui","title":"Swagger UI","text":"<p>A browser / exerciser UI for your API is also available on:</p> <ul> <li><code>/api/v1/namespaces/{namespaces}/apis/{apiName}/api</code></li> </ul>"},{"location":"reference/types/contractapi/#example","title":"Example","text":"<pre><code>{\n    \"id\": \"0f12317b-85a0-4a77-a722-857ea2b0a5fa\",\n    \"namespace\": \"ns1\",\n    \"interface\": {\n        \"id\": \"c35d3449-4f24-4676-8e64-91c9e46f06c4\"\n    },\n    \"location\": {\n        \"address\": \"0x95a6c4895c7806499ba35f75069198f45e88fc69\"\n    },\n    \"name\": \"my_contract_api\",\n    \"message\": \"b09d9f77-7b16-4760-a8d7-0e3c319b2a16\",\n    \"urls\": {\n        \"api\": \"http://127.0.0.1:5000/api/v1/namespaces/default/apis/my_contract_api\",\n        \"openapi\": \"http://127.0.0.1:5000/api/v1/namespaces/default/apis/my_contract_api/api/swagger.json\",\n        \"ui\": \"http://127.0.0.1:5000/api/v1/namespaces/default/apis/my_contract_api/api\"\n    },\n    \"published\": false\n}\n</code></pre>"},{"location":"reference/types/contractapi/#field-descriptions","title":"Field Descriptions","text":"Field Name Description Type <code>id</code> The UUID of the contract API <code>UUID</code> <code>namespace</code> The namespace of the contract API <code>string</code> <code>interface</code> Reference to the FireFly Interface definition associated with the contract API <code>FFIReference</code> <code>location</code> If this API is tied to an individual instance of a smart contract, this field can include a blockchain specific contract identifier. For example an Ethereum contract address, or a Fabric chaincode name and channel <code>JSONAny</code> <code>name</code> The name that is used in the URL to access the API <code>string</code> <code>networkName</code> The published name of the API within the multiparty network <code>string</code> <code>message</code> The UUID of the broadcast message that was used to publish this API to the network <code>UUID</code> <code>urls</code> The URLs to use to access the API <code>ContractURLs</code> <code>published</code> Indicates if the API is published to other members of the multiparty network <code>bool</code>"},{"location":"reference/types/contractapi/#ffireference","title":"FFIReference","text":"Field Name Description Type <code>id</code> The UUID of the FireFly interface <code>UUID</code> <code>name</code> The name of the FireFly interface <code>string</code> <code>version</code> The version of the FireFly interface <code>string</code>"},{"location":"reference/types/contractapi/#contracturls","title":"ContractURLs","text":"Field Name Description Type <code>api</code> The URL to use to invoke the API <code>string</code> <code>openapi</code> The URL to download the OpenAPI v3 (Swagger) description for the API generated in JSON or YAML format <code>string</code> <code>ui</code> The URL to use in a web browser to access the SwaggerUI explorer/exerciser for the API <code>string</code>"},{"location":"reference/types/contractlistener/","title":"ContractListener","text":"<p>A contract listener configures FireFly to stream events from the blockchain, from a specific location on the blockchain, according to a given definition of the interface for that event.</p> <p>Check out the Custom Contracts Tutorial for a walk-through of how to set up listeners for the events from your smart contracts.</p> <p>See below for a deep dive into the format of contract listeners and important concepts to understand when managing them.</p>"},{"location":"reference/types/contractlistener/#event-filters","title":"Event filters","text":""},{"location":"reference/types/contractlistener/#multiple-filters","title":"Multiple filters","text":"<p>From v1.3.1 onwards, a contract listener can be created with multiple filters under a single topic, when supported by the connector. Each filter contains:</p> <ul> <li>a reference to a specific blockchain event to listen for</li> <li>(optional) a specific location/address to listen from</li> <li>a connector-specific signature (generated from the event and the location)</li> </ul> <p>In addition to this list of multiple filters, the listener specifies a single <code>topic</code> to identify the stream of events.</p> <p>Creating a single listener that listens for multiple events will allow for the easiest management of listeners, and for strong ordering of the events that they process.</p>"},{"location":"reference/types/contractlistener/#single-filter","title":"Single filter","text":"<p>Before v1.3.1, each contract listener would only support listening to one specific event from a contract interface. Each listener would be comprised of:</p> <ul> <li>a reference to a specific blockchain event to listen for</li> <li>(optional) a specific location/address to listen from</li> <li>a connector-specific signature (generated from the event), which allows you to easily identify and search for the contact listener for an event</li> <li>a <code>topic</code> which determines the ordered stream that these events are part of</li> </ul> <p>For backwards compatibility, this format is still supported by the API.</p>"},{"location":"reference/types/contractlistener/#signature-strings","title":"Signature strings","text":""},{"location":"reference/types/contractlistener/#string-format","title":"String format","text":"<p>Each filter is identified by a generated <code>signature</code> that matches a single event, and each contract listener is identified by a <code>signature</code> computed from its filters.</p> <p>Ethereum provides a string standard for event signatures, of the form <code>EventName(uint256,bytes)</code>. Prior to v1.3.1, the signature of each Ethereum contract listener would exactly follow this Ethereum format.</p> <p>As of v1.3.1, Ethereum signature strings have been changed, because this format does not fully describe the event - particularly because each top-level parameter can in the ABI definition be marked as <code>indexed</code>. For example, while the following two Solidity events have the same signature, they are serialized differently due to the different placement of <code>indexed</code> parameters, and thus a listener must define both individually to be able to process them:</p> <ul> <li>ERC-20 <code>Transfer</code></li> </ul> <pre><code>event Transfer(address indexed _from, address indexed _to, uint256 _value)\n</code></pre> <ul> <li>ERC-721 <code>Transfer</code></li> </ul> <pre><code>event Transfer(address indexed _from, address indexed _to, uint256 indexed _tokenId);\n</code></pre> <p>The two above are now expressed in the following manner by the Ethereum blockchain connector:</p> <pre><code>Transfer(address,address,uint256) [i=0,1]\nTransfer(address,address,uint256) [i=0,1,2]\n</code></pre> <p>The <code>[i=]</code> listing at the end of the signature indicates the position of all parameters that are marked as <code>indexed</code>.</p> <p>Building on the blockchain-specific signature format for each event, FireFly will then compute the final signature for each filter and each contract listener as follows:</p> <ul> <li>Each filter signature is a combination of the location and the specific connector event signature, such as <code>0xa5ea5d0a6b2eaf194716f0cc73981939dca26da1:Changed(address,uint256) [i=0]</code></li> <li>Each contract listener signature is a concatenation of all the filter signatures, separated by <code>;</code></li> </ul>"},{"location":"reference/types/contractlistener/#duplicate-filters","title":"Duplicate filters","text":"<p>FireFly restricts the creation of a contract listener containing duplicate filters.</p> <p>This includes the special case where one filter is a superset of another filter, due to a wildcard location.</p> <p>For example, if two filters are listening to the same event, but one has specified a location and the other hasn't, then the latter will be a superset, and already be listening to all the events matching the first filter. Creation of duplicate or superset filters within a single listener will be blocked.</p>"},{"location":"reference/types/contractlistener/#duplicate-listeners","title":"Duplicate listeners","text":"<p>As noted above, each listener has a generated signature. This signature - containing all the locations and event signatures combined with the listener topic - will guarantee uniqueness of the contract listener. If you tried to create the same listener again, you would receive HTTP 409. This combination can allow a developer to assert that their listener exists, without the risk of creating duplicates.</p> <p>Note: Prior to v1.3.1, FireFly would detect duplicates simply by requiring a unique combination of signature + topic + location for each listener. The updated behavior for the listener signature is intended to preserve similar functionality, even when dealing with listeners that contain many event filters.</p>"},{"location":"reference/types/contractlistener/#backwards-compatibility","title":"Backwards compatibility","text":"<p>As noted throughout this document, the behavior of listeners is changed in v1.3.1. However, the following behaviors are retained for backwards-compatibility, to ensure that code written prior to v1.3.1 should continue to function.</p> <ul> <li>The response from all query APIs of <code>listeners</code> will continue to populate top-level <code>event</code> and <code>location</code> fields</li> <li>The first entry from the <code>filters</code> array is duplicated to these fields</li> <li>On input to create a new <code>listener</code>, the <code>event</code> and <code>location</code> fields are still supported</li> <li>They function identically to supplying a <code>filters</code> array with a single entry</li> <li>The <code>signature</code> field is preserved at the listener level</li> <li>The format has been changed as described above</li> </ul>"},{"location":"reference/types/contractlistener/#input-formats","title":"Input formats","text":"<p>The two input formats supported when creating a contract listener are shown below.</p> <p>Muliple Filters</p> <pre><code>{\n  \"filters\": [\n    {\n      \"interface\": {\n        \"id\": \"8bdd27a5-67c1-4960-8d1e-7aa31b9084d3\"\n      },\n      \"location\": {\n        \"address\": \"0xa5ea5d0a6b2eaf194716f0cc73981939dca26da1\"\n      },\n      \"eventPath\": \"Changed\"\n    },\n    {\n      \"interface\": {\n        \"id\": \"8bdd27a5-67c1-4960-8d1e-7aa31b9084d3\"\n      },\n      \"location\": {\n        \"address\": \"0xa4ea5d0b6b2eaf194716f0cc73981939dca27da1\"\n      },\n      \"eventPath\": \"AnotherEvent\"\n    }\n  ],\n  \"options\": {\n    \"firstEvent\": \"newest\"\n  },\n  \"topic\": \"simple-storage\"\n}\n</code></pre> <p>One filter (old format)</p> <pre><code>{\n  \"interface\": {\n    \"id\": \"8bdd27a5-67c1-4960-8d1e-7aa31b9084d3\"\n  },\n  \"location\": {\n    \"address\": \"0xa5ea5d0a6b2eaf194716f0cc73981939dca26da1\"\n  },\n  \"eventPath\": \"Changed\",\n  \"options\": {\n    \"firstEvent\": \"newest\"\n  },\n  \"topic\": \"simple-storage\"\n}\n</code></pre>"},{"location":"reference/types/contractlistener/#example","title":"Example","text":"<pre><code>{\n    \"id\": \"d61980a9-748c-4c72-baf5-8b485b514d59\",\n    \"interface\": {\n        \"id\": \"ff1da3c1-f9e7-40c2-8d93-abb8855e8a1d\"\n    },\n    \"namespace\": \"ns1\",\n    \"name\": \"contract1_events\",\n    \"backendId\": \"sb-dd8795fc-a004-4554-669d-c0cf1ee2c279\",\n    \"location\": {\n        \"address\": \"0x596003a91a97757ef1916c8d6c0d42592630d2cf\"\n    },\n    \"created\": \"2022-05-16T01:23:15Z\",\n    \"event\": {\n        \"name\": \"Changed\",\n        \"description\": \"\",\n        \"params\": [\n            {\n                \"name\": \"x\",\n                \"schema\": {\n                    \"type\": \"integer\",\n                    \"details\": {\n                        \"type\": \"uint256\",\n                        \"internalType\": \"uint256\"\n                    }\n                }\n            }\n        ]\n    },\n    \"signature\": \"0x596003a91a97757ef1916c8d6c0d42592630d2cf:Changed(uint256)\",\n    \"topic\": \"app1_topic\",\n    \"options\": {\n        \"firstEvent\": \"newest\"\n    },\n    \"filters\": [\n        {\n            \"event\": {\n                \"name\": \"Changed\",\n                \"description\": \"\",\n                \"params\": [\n                    {\n                        \"name\": \"x\",\n                        \"schema\": {\n                            \"type\": \"integer\",\n                            \"details\": {\n                                \"type\": \"uint256\",\n                                \"internalType\": \"uint256\"\n                            }\n                        }\n                    }\n                ]\n            },\n            \"location\": {\n                \"address\": \"0x596003a91a97757ef1916c8d6c0d42592630d2cf\"\n            },\n            \"signature\": \"0x596003a91a97757ef1916c8d6c0d42592630d2cf:Changed(uint256)\"\n        }\n    ]\n}\n</code></pre>"},{"location":"reference/types/contractlistener/#field-descriptions","title":"Field Descriptions","text":"Field Name Description Type <code>id</code> The UUID of the smart contract listener <code>UUID</code> <code>interface</code> Deprecated: Please use 'interface' in the array of 'filters' instead <code>FFIReference</code> <code>namespace</code> The namespace of the listener, which defines the namespace of all blockchain events detected by this listener <code>string</code> <code>name</code> A descriptive name for the listener <code>string</code> <code>backendId</code> An ID assigned by the blockchain connector to this listener <code>string</code> <code>location</code> Deprecated: Please use 'location' in the array of 'filters' instead <code>JSONAny</code> <code>created</code> The creation time of the listener <code>FFTime</code> <code>event</code> Deprecated: Please use 'event' in the array of 'filters' instead <code>FFISerializedEvent</code> <code>signature</code> A concatenation of all the stringified signature of the event and location, as computed by the blockchain plugin <code>string</code> <code>topic</code> A topic to set on the FireFly event that is emitted each time a blockchain event is detected from the blockchain. Setting this topic on a number of listeners allows applications to easily subscribe to all events they need <code>string</code> <code>options</code> Options that control how the listener subscribes to events from the underlying blockchain <code>ContractListenerOptions</code> <code>filters</code> A list of filters for the contract listener. Each filter is made up of an Event and an optional Location. Events matching these filters will always be emitted in the order determined by the blockchain. <code>ListenerFilter[]</code>"},{"location":"reference/types/contractlistener/#ffireference","title":"FFIReference","text":"Field Name Description Type <code>id</code> The UUID of the FireFly interface <code>UUID</code> <code>name</code> The name of the FireFly interface <code>string</code> <code>version</code> The version of the FireFly interface <code>string</code>"},{"location":"reference/types/contractlistener/#ffiserializedevent","title":"FFISerializedEvent","text":"Field Name Description Type <code>name</code> The name of the event <code>string</code> <code>description</code> A description of the smart contract event <code>string</code> <code>params</code> An array of event parameter/argument definitions <code>FFIParam[]</code> <code>details</code> Additional blockchain specific fields about this event from the original smart contract. Used by the blockchain plugin and for documentation generation. <code>JSONObject</code>"},{"location":"reference/types/contractlistener/#ffiparam","title":"FFIParam","text":"Field Name Description Type <code>name</code> The name of the parameter. Note that parameters must be ordered correctly on the FFI, according to the order in the blockchain smart contract <code>string</code> <code>schema</code> FireFly uses an extended subset of JSON Schema to describe parameters, similar to OpenAPI/Swagger. Converters are available for native blockchain interface definitions / type systems - such as an Ethereum ABI. See the documentation for more detail <code>JSONAny</code>"},{"location":"reference/types/contractlistener/#contractlisteneroptions","title":"ContractListenerOptions","text":"Field Name Description Type <code>firstEvent</code> A blockchain specific string, such as a block number, to start listening from. The special strings 'oldest' and 'newest' are supported by all blockchain connectors. Default is 'newest' <code>string</code>"},{"location":"reference/types/contractlistener/#listenerfilter","title":"ListenerFilter","text":"Field Name Description Type <code>event</code> The definition of the event, either provided in-line when creating the listener, or extracted from the referenced FFI <code>FFISerializedEvent</code> <code>location</code> A blockchain specific contract identifier. For example an Ethereum contract address, or a Fabric chaincode name and channel <code>JSONAny</code> <code>interface</code> A reference to an existing FFI, containing pre-registered type information for the event <code>FFIReference</code> <code>signature</code> The stringified signature of the event and location, as computed by the blockchain plugin <code>string</code>"},{"location":"reference/types/data/","title":"Data","text":"<p>Data is a uniquely identified piece of data available for retrieval or transfer.</p> <p>Multiple data items can be attached to a message when sending data off-chain to another party in a multi-party system. Note that if you pass data in-line when sending a message, those data elements will be stored separately to the message and available to retrieve separately later.</p> <p>An UUID is allocated to each data resource.</p> <p>A hash is also calculated as follows:</p> <ul> <li>If there is only data, the hash is of the <code>value</code> serialized as JSON with   no additional whitespace (order of the keys is retained from the original   upload order).</li> <li>If there is only a <code>blob</code> attachment, the hash is of the blob data.</li> <li>There is is both a <code>blob</code> and a <code>value</code>, then the hash is a hash of the   concatenation of a hash of the value and a hash of the blob.</li> </ul>"},{"location":"reference/types/data/#value-json-data-stored-in-the-core-database","title":"Value - JSON data stored in the core database","text":"<p>Each data resource can contain a <code>value</code>, which is any JSON type. String, number, boolean, array or object. This value is stored directly in the FireFly database.</p> <p>If the value you are storing is not JSON data, but is small enough you want it to be stored in the core database, then use a JSON string to store an encoded form of your data (such as XML, CSV etc.).</p>"},{"location":"reference/types/data/#datatype-validation-of-agreed-data-types","title":"Datatype - validation of agreed data types","text":"<p>A datatype can be associated with your data, causing FireFly to verify the <code>value</code> against a schema before accepting it (on upload, or receipt from another party in the network).</p> <p>These datatypes are pre-established via broadcast messages, and support versioning. Use this system to enforce a set of common data types for exchange of data across your business network, and reduce the overhead of data verification\\ required in the application/integration tier.</p> <p>More information in the Datatype section</p>"},{"location":"reference/types/data/#blob-binary-data-stored-via-the-data-exchange","title":"Blob - binary data stored via the Data Exchange","text":"<p>Data resources can also contain a <code>blob</code> attachment, which is stored via the Data Exchange plugin outside of the FireFly core database. This is intended for large data payloads, which might be structured or unstructured. PDF documents, multi-MB XML payloads, CSV data exports, JPEG images video files etc.</p> <p>A Data resource can contain both a <code>value</code> JSON payload, and a <code>blob</code> attachment, meaning that you bind a set of metadata to a binary payload. For example a set of extracted metadata from OCR processing of a PDF document.</p> <p>One special case is a filename for a document. This pattern is so common for file/document management scenarios, that special handling is provided for it. If a JSON object is stored in <code>value</code>, and it has a property called <code>name</code>, then this value forms part of the data hash (as does every field in the <code>value</code>) and is stored in a separately indexed <code>blob.name</code> field.</p> <p>The upload REST API provides an <code>autometa</code> form field, which can be set to ask FireFly core to automatically set the <code>value</code> to contain the filename, size, and MIME type from the file upload.</p>"},{"location":"reference/types/data/#example","title":"Example","text":"<pre><code>{\n    \"id\": \"4f11e022-01f4-4c3f-909f-5226947d9ef0\",\n    \"validator\": \"json\",\n    \"namespace\": \"ns1\",\n    \"hash\": \"5e2758423c99b799f53d3f04f587f5716c1ff19f1d1a050f40e02ea66860b491\",\n    \"created\": \"2022-05-16T01:23:15Z\",\n    \"datatype\": {\n        \"name\": \"widget\",\n        \"version\": \"v1.2.3\"\n    },\n    \"value\": {\n        \"name\": \"filename.pdf\",\n        \"a\": \"example\",\n        \"b\": {\n            \"c\": 12345\n        }\n    },\n    \"blob\": {\n        \"hash\": \"cef238f7b02803a799f040cdabe285ad5cd6db4a15cb9e2a1000f2860884c7ad\",\n        \"size\": 12345,\n        \"name\": \"filename.pdf\"\n    }\n}\n</code></pre>"},{"location":"reference/types/data/#field-descriptions","title":"Field Descriptions","text":"Field Name Description Type <code>id</code> The UUID of the data resource <code>UUID</code> <code>validator</code> The data validator type <code>FFEnum</code>: <code>namespace</code> The namespace of the data resource <code>string</code> <code>hash</code> The hash of the data resource. Derived from the value and the hash of any binary blob attachment <code>Bytes32</code> <code>created</code> The creation time of the data resource <code>FFTime</code> <code>datatype</code> The optional datatype to use of validation of this data <code>DatatypeRef</code> <code>value</code> The value for the data, stored in the FireFly core database. Can be any JSON type - object, array, string, number or boolean. Can be combined with a binary blob attachment <code>JSONAny</code> <code>public</code> If the JSON value has been published to shared storage, this field is the id of the data in the shared storage plugin (IPFS hash etc.) <code>string</code> <code>blob</code> An optional hash reference to a binary blob attachment <code>BlobRef</code>"},{"location":"reference/types/data/#datatyperef","title":"DatatypeRef","text":"Field Name Description Type <code>name</code> The name of the datatype <code>string</code> <code>version</code> The version of the datatype. Semantic versioning is encouraged, such as v1.0.1 <code>string</code>"},{"location":"reference/types/data/#blobref","title":"BlobRef","text":"Field Name Description Type <code>hash</code> The hash of the binary blob data <code>Bytes32</code> <code>size</code> The size of the binary data <code>int64</code> <code>name</code> The name field from the metadata attached to the blob, commonly used as a path/filename, and indexed for search <code>string</code> <code>path</code> If a name is specified, this field stores the '/' prefixed and separated path extracted from the full name <code>string</code> <code>public</code> If the blob data has been published to shared storage, this field is the id of the data in the shared storage plugin (IPFS hash etc.) <code>string</code>"},{"location":"reference/types/datatype/","title":"Datatype","text":"<p>A datatype defines the format of some data that can be shared between parties, in a way that FireFly can enforce consistency of that data against the schema.</p> <p>Data that does not match the schema associated with it will not be accepted on upload to FireFly, and if this were bypassed by a participant in some way it would be rejected by all parties and result in a <code>message_rejected</code> event (rather than <code>message_confirmed</code> event).</p> <p>Currently JSON Schema validation of data is supported.</p> <p>The system for defining datatypes is pluggable, to support other schemes in the future, such as XML Schema, or CSV, EDI etc.</p>"},{"location":"reference/types/datatype/#example","title":"Example","text":"<pre><code>{\n    \"id\": \"3a479f7e-ddda-4bda-aa24-56d06c0bf08e\",\n    \"message\": \"bfcf904c-bdf7-40aa-bbd7-567f625c26c0\",\n    \"validator\": \"json\",\n    \"namespace\": \"ns1\",\n    \"name\": \"widget\",\n    \"version\": \"1.0.0\",\n    \"hash\": \"639cd98c893fa45a9df6fd87bd0393a9b39e31e26fbb1eeefe90cb40c3fa02d2\",\n    \"created\": \"2022-05-16T01:23:16Z\",\n    \"value\": {\n        \"$id\": \"https://example.com/widget.schema.json\",\n        \"$schema\": \"https://json-schema.org/draft/2020-12/schema\",\n        \"title\": \"Widget\",\n        \"type\": \"object\",\n        \"properties\": {\n            \"id\": {\n                \"type\": \"string\",\n                \"description\": \"The unique identifier for the widget.\"\n            },\n            \"name\": {\n                \"type\": \"string\",\n                \"description\": \"The person's last name.\"\n            }\n        },\n        \"additionalProperties\": false\n    }\n}\n</code></pre>"},{"location":"reference/types/datatype/#field-descriptions","title":"Field Descriptions","text":"Field Name Description Type <code>id</code> The UUID of the datatype <code>UUID</code> <code>message</code> The UUID of the broadcast message that was used to publish this datatype to the network <code>UUID</code> <code>validator</code> The validator that should be used to verify this datatype <code>FFEnum</code>:<code>\"json\"</code><code>\"none\"</code><code>\"definition\"</code> <code>namespace</code> The namespace of the datatype. Data resources can only be created referencing datatypes in the same namespace <code>string</code> <code>name</code> The name of the datatype <code>string</code> <code>version</code> The version of the datatype. Multiple versions can exist with the same name. Use of semantic versioning is encourages, such as v1.0.1 <code>string</code> <code>hash</code> The hash of the value, such as the JSON schema. Allows all parties to be confident they have the exact same rules for verifying data created against a datatype <code>Bytes32</code> <code>created</code> The time the datatype was created <code>FFTime</code> <code>value</code> The definition of the datatype, in the syntax supported by the validator (such as a JSON Schema definition) <code>JSONAny</code>"},{"location":"reference/types/event/","title":"Event","text":"<p>Every Event emitted by FireFly shares a common structure.</p> <p>See Events for a reference for how the overall event bus in Hyperledger FireFly operates, and descriptions of all the sub-categories of events.</p>"},{"location":"reference/types/event/#sequence","title":"Sequence","text":"<p>A local <code>sequence</code> number is assigned to each event, and you can use an API to query events using this sequence number in exactly the same order that they are delivered to your application.</p>"},{"location":"reference/types/event/#reference","title":"Reference","text":"<p>Events have a <code>reference</code> to the UUID of an object that is the subject of the event, such as a detailed Blockchain Event, or an off-chain Message.</p> <p>When events are delivered to your application, the <code>reference</code> field is automatically retrieved and included in the JSON payload that is delivered to your application.</p> <p>You can use the <code>?fetchreferences</code> query parameter on API calls to request the same in-line JSON payload be included in query results.</p> <p>The type of the reference also determines what subscription filters apply when performing server-side filters.</p> <p>Here is the mapping between event types, and the object that you find in the <code>reference</code> field.</p>"},{"location":"reference/types/event/#correlator","title":"Correlator","text":"<p>For some event types, there is a secondary reference to an object that is associated with the event. This is set in a <code>correlator</code> field on the Event, but is not automatically fetched. This field is primarily used for the <code>confirm</code> option on API calls to allow FireFly to determine when a request has succeeded/failed.</p>"},{"location":"reference/types/event/#topic","title":"Topic","text":"<p>Events have a <code>topic</code>, and how that topic is determined is specific to the type of event. This is intended to be a property you would use to filter events to your application, or query all historical events associated with a given business data stream.</p> <p>For example when you send a Message, you set the <code>topics</code> you want that message to apply to, and FireFly ensures a consistent global order between all parties that receive that message.</p>"},{"location":"reference/types/event/#transaction","title":"Transaction","text":"<p>When actions are submitted by a FireFly node, they are performed within a FireFly Transaction. The events that occur as a direct result of that transaction, are tagged with the transaction ID so that they can be grouped together.</p> <p>This construct is a distinct higher level construct than a Blockchain transaction, that groups together a number of operations/events that might be on-chain or off-chain. In some cases, such as unpinned off-chain data transfer, a FireFly transaction can exist when there is no blockchain transaction at all. Wherever possible you will find that FireFly tags the FireFly transaction with any associated Blockchain transaction(s).</p> <p>Note that some events cannot be tagged with a Transaction ID:</p> <ul> <li>Blockchain events, unless they were part of a batch-pin transaction   for transfer of a message</li> <li>Token transfers/approvals, unless they had a message transfer associated   with them (and included a <code>data</code> payload in the event they emitted)</li> </ul>"},{"location":"reference/types/event/#reference-topic-and-correlator-by-event-type","title":"Reference, Topic and Correlator by Event Type","text":"Types Reference Topic Correlator <code>transaction_submitted</code> Transaction <code>transaction.type</code> <code>message_confirmed</code><code>message_rejected</code> Message <code>message.header.topics[i]</code>* <code>message.header.cid</code> <code>token_pool_confirmed</code> TokenPool <code>tokenPool.id</code> <code>token_pool_op_failed</code> Operation <code>tokenPool.id</code> <code>tokenPool.id</code> <code>token_transfer_confirmed</code> TokenTransfer <code>tokenPool.id</code> <code>token_transfer_op_failed</code> Operation <code>tokenPool.id</code> <code>tokenTransfer.localId</code> <code>token_approval_confirmed</code> TokenApproval <code>tokenPool.id</code> <code>token_approval_op_failed</code> Operation <code>tokenPool.id</code> <code>tokenApproval.localId</code> <code>namespace_confirmed</code> Namespace <code>\"ff_definition\"</code> <code>datatype_confirmed</code> Datatype <code>\"ff_definition\"</code> <code>identity_confirmed</code><code>identity_updated</code> Identity <code>\"ff_definition\"</code> <code>contract_interface_confirmed</code> FFI <code>\"ff_definition\"</code> <code>contract_api_confirmed</code> ContractAPI <code>\"ff_definition\"</code> <code>blockchain_event_received</code> BlockchainEvent From listener ** <code>blockchain_invoke_op_succeeded</code> Operation <code>blockchain_invoke_op_failed</code> Operation <code>blockchain_contract_deploy_op_succeeded</code> Operation <code>blockchain_contract_deploy_op_failed</code> Operation <ul> <li>A separate event is emitted for each topic associated with a Message.</li> </ul> <p>** The topic for a blockchain event is inherited from the blockchain listener, allowing you to create multiple blockchain listeners that all deliver messages to your application on a single FireFly topic.</p>"},{"location":"reference/types/event/#example","title":"Example","text":"<pre><code>{\n    \"id\": \"5f875824-b36b-4559-9791-a57a2e2b30dd\",\n    \"sequence\": 168,\n    \"type\": \"transaction_submitted\",\n    \"namespace\": \"ns1\",\n    \"reference\": \"0d12aa75-5ed8-48a7-8b54-45274c6edcb1\",\n    \"tx\": \"0d12aa75-5ed8-48a7-8b54-45274c6edcb1\",\n    \"topic\": \"batch_pin\",\n    \"created\": \"2022-05-16T01:23:15Z\"\n}\n</code></pre>"},{"location":"reference/types/event/#field-descriptions","title":"Field Descriptions","text":"Field Name Description Type <code>id</code> The UUID assigned to this event by your local FireFly node <code>UUID</code> <code>sequence</code> A sequence indicating the order in which events are delivered to your application. Assure to be unique per event in your local FireFly database (unlike the created timestamp) <code>int64</code> <code>type</code> All interesting activity in FireFly is emitted as a FireFly event, of a given type. The 'type' combined with the 'reference' can be used to determine how to process the event within your application <code>FFEnum</code>:<code>\"transaction_submitted\"</code><code>\"message_confirmed\"</code><code>\"message_rejected\"</code><code>\"datatype_confirmed\"</code><code>\"identity_confirmed\"</code><code>\"identity_updated\"</code><code>\"token_pool_confirmed\"</code><code>\"token_pool_op_failed\"</code><code>\"token_transfer_confirmed\"</code><code>\"token_transfer_op_failed\"</code><code>\"token_approval_confirmed\"</code><code>\"token_approval_op_failed\"</code><code>\"contract_interface_confirmed\"</code><code>\"contract_api_confirmed\"</code><code>\"blockchain_event_received\"</code><code>\"blockchain_invoke_op_succeeded\"</code><code>\"blockchain_invoke_op_failed\"</code><code>\"blockchain_contract_deploy_op_succeeded\"</code><code>\"blockchain_contract_deploy_op_failed\"</code> <code>namespace</code> The namespace of the event. Your application must subscribe to events within a namespace <code>string</code> <code>reference</code> The UUID of an resource that is the subject of this event. The event type determines what type of resource is referenced, and whether this field might be unset <code>UUID</code> <code>correlator</code> For message events, this is the 'header.cid' field from the referenced message. For certain other event types, a secondary object is referenced such as a token pool <code>UUID</code> <code>tx</code> The UUID of a transaction that is event is part of. Not all events are part of a transaction <code>UUID</code> <code>topic</code> A stream of information this event relates to. For message confirmation events, a separate event is emitted for each topic in the message. For blockchain events, the listener specifies the topic. Rules exist for how the topic is set for other event types <code>string</code> <code>created</code> The time the event was emitted. Not guaranteed to be unique, or to increase between events in the same order as the final sequence events are delivered to your application. As such, the 'sequence' field should be used instead of the 'created' field for querying events in the exact order they are delivered to applications <code>FFTime</code>"},{"location":"reference/types/ffi/","title":"FFI","text":"<p>See FireFly Interface Format</p>"},{"location":"reference/types/ffi/#example","title":"Example","text":"<pre><code>{\n    \"id\": \"c35d3449-4f24-4676-8e64-91c9e46f06c4\",\n    \"message\": \"e4ad2077-5714-416e-81f9-7964a6223b6f\",\n    \"namespace\": \"ns1\",\n    \"name\": \"SimpleStorage\",\n    \"description\": \"A simple example contract in Solidity\",\n    \"version\": \"v0.0.1\",\n    \"methods\": [\n        {\n            \"id\": \"8f3289dd-3a19-4a9f-aab3-cb05289b013c\",\n            \"interface\": \"c35d3449-4f24-4676-8e64-91c9e46f06c4\",\n            \"name\": \"get\",\n            \"namespace\": \"ns1\",\n            \"pathname\": \"get\",\n            \"description\": \"Get the current value\",\n            \"params\": [],\n            \"returns\": [\n                {\n                    \"name\": \"output\",\n                    \"schema\": {\n                        \"type\": \"integer\",\n                        \"details\": {\n                            \"type\": \"uint256\"\n                        }\n                    }\n                }\n            ],\n            \"details\": {\n                \"stateMutability\": \"viewable\"\n            }\n        },\n        {\n            \"id\": \"fc6f54ee-2e3c-4e56-b17c-4a1a0ae7394b\",\n            \"interface\": \"c35d3449-4f24-4676-8e64-91c9e46f06c4\",\n            \"name\": \"set\",\n            \"namespace\": \"ns1\",\n            \"pathname\": \"set\",\n            \"description\": \"Set the value\",\n            \"params\": [\n                {\n                    \"name\": \"newValue\",\n                    \"schema\": {\n                        \"type\": \"integer\",\n                        \"details\": {\n                            \"type\": \"uint256\"\n                        }\n                    }\n                }\n            ],\n            \"returns\": [],\n            \"details\": {\n                \"stateMutability\": \"payable\"\n            }\n        }\n    ],\n    \"events\": [\n        {\n            \"id\": \"9f653f93-86f4-45bc-be75-d7f5888fbbc0\",\n            \"interface\": \"c35d3449-4f24-4676-8e64-91c9e46f06c4\",\n            \"namespace\": \"ns1\",\n            \"pathname\": \"Changed\",\n            \"signature\": \"Changed(address,uint256)\",\n            \"name\": \"Changed\",\n            \"description\": \"Emitted when the value changes\",\n            \"params\": [\n                {\n                    \"name\": \"_from\",\n                    \"schema\": {\n                        \"type\": \"string\",\n                        \"details\": {\n                            \"type\": \"address\",\n                            \"indexed\": true\n                        }\n                    }\n                },\n                {\n                    \"name\": \"_value\",\n                    \"schema\": {\n                        \"type\": \"integer\",\n                        \"details\": {\n                            \"type\": \"uint256\"\n                        }\n                    }\n                }\n            ]\n        }\n    ],\n    \"published\": false\n}\n</code></pre>"},{"location":"reference/types/ffi/#field-descriptions","title":"Field Descriptions","text":"Field Name Description Type <code>id</code> The UUID of the FireFly interface (FFI) smart contract definition <code>UUID</code> <code>message</code> The UUID of the broadcast message that was used to publish this FFI to the network <code>UUID</code> <code>namespace</code> The namespace of the FFI <code>string</code> <code>name</code> The name of the FFI - usually matching the smart contract name <code>string</code> <code>networkName</code> The published name of the FFI within the multiparty network <code>string</code> <code>description</code> A description of the smart contract this FFI represents <code>string</code> <code>version</code> A version for the FFI - use of semantic versioning such as 'v1.0.1' is encouraged <code>string</code> <code>methods</code> An array of smart contract method definitions <code>FFIMethod[]</code> <code>events</code> An array of smart contract event definitions <code>FFIEvent[]</code> <code>errors</code> An array of smart contract error definitions <code>FFIError[]</code> <code>published</code> Indicates if the FFI is published to other members of the multiparty network <code>bool</code>"},{"location":"reference/types/ffi/#ffimethod","title":"FFIMethod","text":"Field Name Description Type <code>id</code> The UUID of the FFI method definition <code>UUID</code> <code>interface</code> The UUID of the FFI smart contract definition that this method is part of <code>UUID</code> <code>name</code> The name of the method <code>string</code> <code>namespace</code> The namespace of the FFI <code>string</code> <code>pathname</code> The unique name allocated to this method within the FFI for use on URL paths. Supports contracts that have multiple method overrides with the same name <code>string</code> <code>description</code> A description of the smart contract method <code>string</code> <code>params</code> An array of method parameter/argument definitions <code>FFIParam[]</code> <code>returns</code> An array of method return definitions <code>FFIParam[]</code> <code>details</code> Additional blockchain specific fields about this method from the original smart contract. Used by the blockchain plugin and for documentation generation. <code>JSONObject</code>"},{"location":"reference/types/ffi/#ffiparam","title":"FFIParam","text":"Field Name Description Type <code>name</code> The name of the parameter. Note that parameters must be ordered correctly on the FFI, according to the order in the blockchain smart contract <code>string</code> <code>schema</code> FireFly uses an extended subset of JSON Schema to describe parameters, similar to OpenAPI/Swagger. Converters are available for native blockchain interface definitions / type systems - such as an Ethereum ABI. See the documentation for more detail <code>JSONAny</code>"},{"location":"reference/types/ffi/#ffievent","title":"FFIEvent","text":"Field Name Description Type <code>id</code> The UUID of the FFI event definition <code>UUID</code> <code>interface</code> The UUID of the FFI smart contract definition that this event is part of <code>UUID</code> <code>namespace</code> The namespace of the FFI <code>string</code> <code>pathname</code> The unique name allocated to this event within the FFI for use on URL paths. Supports contracts that have multiple event overrides with the same name <code>string</code> <code>signature</code> The stringified signature of the event, as computed by the blockchain plugin <code>string</code> <code>name</code> The name of the event <code>string</code> <code>description</code> A description of the smart contract event <code>string</code> <code>params</code> An array of event parameter/argument definitions <code>FFIParam[]</code> <code>details</code> Additional blockchain specific fields about this event from the original smart contract. Used by the blockchain plugin and for documentation generation. <code>JSONObject</code>"},{"location":"reference/types/ffi/#ffiparam_1","title":"FFIParam","text":"Field Name Description Type <code>name</code> The name of the parameter. Note that parameters must be ordered correctly on the FFI, according to the order in the blockchain smart contract <code>string</code> <code>schema</code> FireFly uses an extended subset of JSON Schema to describe parameters, similar to OpenAPI/Swagger. Converters are available for native blockchain interface definitions / type systems - such as an Ethereum ABI. See the documentation for more detail <code>JSONAny</code>"},{"location":"reference/types/ffi/#ffierror","title":"FFIError","text":"Field Name Description Type <code>id</code> The UUID of the FFI error definition <code>UUID</code> <code>interface</code> The UUID of the FFI smart contract definition that this error is part of <code>UUID</code> <code>namespace</code> The namespace of the FFI <code>string</code> <code>pathname</code> The unique name allocated to this error within the FFI for use on URL paths <code>string</code> <code>signature</code> The stringified signature of the error, as computed by the blockchain plugin <code>string</code> <code>name</code> The name of the error <code>string</code> <code>description</code> A description of the smart contract error <code>string</code> <code>params</code> An array of error parameter/argument definitions <code>FFIParam[]</code>"},{"location":"reference/types/ffi/#ffiparam_2","title":"FFIParam","text":"Field Name Description Type <code>name</code> The name of the parameter. Note that parameters must be ordered correctly on the FFI, according to the order in the blockchain smart contract <code>string</code> <code>schema</code> FireFly uses an extended subset of JSON Schema to describe parameters, similar to OpenAPI/Swagger. Converters are available for native blockchain interface definitions / type systems - such as an Ethereum ABI. See the documentation for more detail <code>JSONAny</code>"},{"location":"reference/types/group/","title":"Group","text":"<p>A privacy group is a list of identities that should receive a private communication.</p> <p>When you send a private message, you can specify the list of participants in-line and it will be resolved to a group. Or you can reference the group using its identifying hash.</p> <p>The sender of a message must be included in the group along with the other participants. The sender receives an event confirming the message, just as any other participant would do.</p> <p>The sender is included automatically in the group when members are specified in-line, if it is omitted.</p>"},{"location":"reference/types/group/#group-identity-hash","title":"Group identity hash","text":"<p>The identifying hash for a group is determined as follows:</p> <ul> <li>All identities are resolved to their DID.</li> <li>An organization name or identity UUID can be used on input</li> <li>The UUID of the node that should receive the data for each participant is   determined (if not specified).</li> <li>The first node found that is in the same identity hierarchy as the     participant identity, will be chosen.</li> <li>The list of participants is ordered by DID, with de-duplication of   any identities.</li> <li>The <code>namespace</code>, <code>name</code>, and <code>members</code> array are then serialized into   a JSON object, without whitespace.</li> <li>A SHA256 hash of the JSON object is calculated</li> </ul>"},{"location":"reference/types/group/#private-messaging-architecture","title":"Private messaging architecture","text":"<p>The mechanism that keeps data private and ordered, without leaking data to the blockchain, is summarized in the below diagram.</p> <p>The key points are:</p> <ul> <li>Data is sent off-chain to all participants via the Data Exchange plugin</li> <li>The Data Exchange is responsible for encryption and off-chain identity verification</li> <li>Only parties that are involved in the privacy group receive the data</li> <li>Other parties are only able to view the blockchain transaction</li> <li>The hash and member list of the group are not shared outside of the privacy group</li> <li>The <code>name</code> of the group can be used as an additional salt in generation of the group hash</li> <li>The member list must be known by all members of the group to verify the blockchain transactions,     so the full group JSON structure is communicated privately with the first message     sent on a group</li> <li>The blockchain transaction is the source of truth for ordering</li> <li>All members are able to detect a blockchain transaction is part of a group     they are a member of, from only the blockchain transaction - so they can block     processing of subsequent messages until the off-chain data arrives (asynchronously)</li> <li>The ordering context for messages is masked on the blockchain, so that two messages   that are for same group do not contain the same context</li> <li>The ordering context (<code>topic</code>+<code>group</code>) is combined with a <code>nonce</code> that is incremented     for each individual sender, to form a message-specific hash.</li> <li>For each blockchain transaction, this hash can be compared against the expected next     hash for each member to determine if it is a message on a known group - even without     the private data (which might arrive later)</li> </ul> <p>See NextPin for more information on the structure used for storing the next expected masked context pin, for each member of the privacy group.</p> <p></p>"},{"location":"reference/types/group/#example","title":"Example","text":"<pre><code>{\n    \"namespace\": \"ns1\",\n    \"name\": \"\",\n    \"members\": [\n        {\n            \"identity\": \"did:firefly:org/1111\",\n            \"node\": \"4f563179-b4bd-4161-86e0-c2c1c0869c4f\"\n        },\n        {\n            \"identity\": \"did:firefly:org/2222\",\n            \"node\": \"61a99af8-c1f7-48ea-8fcc-489e4822a0ed\"\n        }\n    ],\n    \"localNamespace\": \"ns1\",\n    \"message\": \"0b9dfb76-103d-443d-92fd-b114fe07c54d\",\n    \"hash\": \"c52ad6c034cf5c7382d9a294f49297096a52eb55cc2da696c564b2a276633b95\",\n    \"created\": \"2022-05-16T01:23:16Z\"\n}\n</code></pre>"},{"location":"reference/types/group/#field-descriptions","title":"Field Descriptions","text":"Field Name Description Type <code>namespace</code> The namespace of the group within the multiparty network <code>string</code> <code>name</code> The optional name of the group, allowing multiple unique groups to exist with the same list of recipients <code>string</code> <code>members</code> The list of members in this privacy group <code>Member[]</code> <code>localNamespace</code> The local namespace of the group <code>string</code> <code>message</code> The message used to broadcast this group privately to the members <code>UUID</code> <code>hash</code> The identifier hash of this group. Derived from the name and group members <code>Bytes32</code> <code>created</code> The time when the group was first used to send a message in the network <code>FFTime</code>"},{"location":"reference/types/group/#member","title":"Member","text":"Field Name Description Type <code>identity</code> The DID of the group member <code>string</code> <code>node</code> The UUID of the node that receives a copy of the off-chain message for the identity <code>UUID</code>"},{"location":"reference/types/identity/","title":"Identity","text":"<p>FireFly contains an address book of identities, which is managed in a decentralized way across a multi-party system through <code>claim</code> and <code>verification</code> system.</p> <p>See FIR-12 for evolution that is happening to Hyperledger FireFly to allow:</p> <ul> <li>Private address books that are not shared with other participants</li> <li>Multiple address books backed by different chains, in the same node</li> </ul> <p>Root identities are registered with only a <code>claim</code> - which is a signed transaction from a particular blockchain account, to bind a DID with a <code>name</code> that is unique within the network, to that signing key.</p> <p>The signing key then becomes a Verifier for that identity. Using that key the root identity can be used to register a new FireFly node in the network, send and receive messages, and register child identities.</p> <p>When child identities are registered, a <code>claim</code> using a key that is going to be the Verifier for that child identity is required. However, this is insufficient to establish that identity as a child identity of the parent. There must be an additional <code>verification</code> that references the <code>claim</code> (by UUID) using the key verifier of the parent identity.</p>"},{"location":"reference/types/identity/#dids","title":"DIDs","text":"<p>FireFly has adopted the DID standard for representing identities. A \"DID Method\" name of <code>firefly</code> is used to represent that the built-in identity system of Hyperledger FireFly is being used to resolve these DIDs.</p> <p>So an example FireFly DID for organization <code>abcd1234</code> is:</p> <ul> <li><code>did:firefly:org/abcd1234</code></li> </ul> <p>The adoption of DIDs in Hyperledger FireFly v1.0 is also a stepping stone to allowing pluggable DID based identity resolvers into FireFly in the future.</p> <p>You can also download a DID Document for a FireFly identity, which represents the verifiers and other information about that identity according to the JSON format in the DID standard.</p>"},{"location":"reference/types/identity/#example","title":"Example","text":"<pre><code>{\n    \"id\": \"114f5857-9983-46fb-b1fc-8c8f0a20846c\",\n    \"did\": \"did:firefly:org/org_1\",\n    \"type\": \"org\",\n    \"parent\": \"688072c3-4fa0-436c-a86b-5d89673b8938\",\n    \"namespace\": \"ff_system\",\n    \"name\": \"org_1\",\n    \"messages\": {\n        \"claim\": \"911b364b-5863-4e49-a3f8-766dbbae7c4c\",\n        \"verification\": \"24636f11-c1f9-4bbb-9874-04dd24c7502f\",\n        \"update\": null\n    },\n    \"created\": \"2022-05-16T01:23:15Z\"\n}\n</code></pre>"},{"location":"reference/types/identity/#field-descriptions","title":"Field Descriptions","text":"Field Name Description Type <code>id</code> The UUID of the identity <code>UUID</code> <code>did</code> The DID of the identity. Unique across namespaces within a FireFly network <code>string</code> <code>type</code> The type of the identity <code>FFEnum</code>:<code>\"org\"</code><code>\"node\"</code><code>\"custom\"</code> <code>parent</code> The UUID of the parent identity. Unset for root organization identities <code>UUID</code> <code>namespace</code> The namespace of the identity. Organization and node identities are always defined in the ff_system namespace <code>string</code> <code>name</code> The name of the identity. The name must be unique within the type and namespace <code>string</code> <code>description</code> A description of the identity. Part of the updatable profile information of an identity <code>string</code> <code>profile</code> A set of metadata for the identity. Part of the updatable profile information of an identity <code>JSONObject</code> <code>messages</code> References to the broadcast messages that established this identity and proved ownership of the associated verifiers (keys) <code>IdentityMessages</code> <code>created</code> The creation time of the identity <code>FFTime</code> <code>updated</code> The last update time of the identity profile <code>FFTime</code>"},{"location":"reference/types/identity/#identitymessages","title":"IdentityMessages","text":"Field Name Description Type <code>claim</code> The UUID of claim message <code>UUID</code> <code>verification</code> The UUID of claim message. Unset for root organization identities <code>UUID</code> <code>update</code> The UUID of the most recently applied update message. Unset if no updates have been confirmed <code>UUID</code>"},{"location":"reference/types/message/","title":"Message","text":"<p>Message is the envelope by which coordinated data exchange can happen between parties in the network. Data is passed by reference in these messages, and a chain of hashes covering the data and the details of the message, provides a verification against tampering.</p> <p>A message is made up of three sections:</p> <ol> <li>The header - a set of metadata that determines how the message is ordered, who should receive it, and how they should process it</li> <li>The data - an array of data attachments</li> <li>Status information - fields that are calculated independently by each node, and hence update as the message makes it way through the system</li> </ol>"},{"location":"reference/types/message/#hash","title":"Hash","text":"<p>Sections (1) and (2) are fixed once the message is sent, and a <code>hash</code> is generated that provides tamper protection.</p> <p>The hash is a function of the header, and all of the data payloads. Calculated as follows:</p> <ul> <li>The hash of each Data element is calculated individually</li> <li>A JSON array of <code>[{\"id\":\"{{DATA_UUID}}\",\"hash\":\"{{DATA_HASH}}\"}]</code> is hashed, and that hash is stored in <code>header.datahash</code></li> <li>The <code>header</code> is serialized as JSON with the deterministic order (listed below) and hashed</li> <li>JSON data is serialized without whitespace to hash it.</li> <li>The hashing algorithm is SHA-256</li> </ul> <p>Each node independently calculates the hash, and the hash is included in the manifest of the Batch by the node that sends the message. Because the hash of that batch manifest is included in the blockchain transaction, a message transferred to a node that does not match the original message hash is rejected.</p>"},{"location":"reference/types/message/#tag","title":"Tag","text":"<p>The <code>header.tag</code> tells the processors of the message how it should be processed, and what data they should expect it to contain.</p> <p>If you think of your decentralized application like a state machine, then you need to have a set of well defined transitions that can be performed between states. Each of these transitions that requires off-chain transfer of private data (optionally coordinated with an on-chain transaction) should be expressed as a type of message, with a particular <code>tag</code>.</p> <p>Every copy of the application that runs in the participants of the network should look at this <code>tag</code> to determine what logic to execute against it.</p> <p>Note: For consistency in ordering, the sender should also wait to process the state machine transitions associated with the message they send until it is ordered by the blockchain. They should not consider themselves special because they sent the message, and process it immediately - otherwise they could end up processing it in a different order to other parties in the network that are also processing the message.</p>"},{"location":"reference/types/message/#topics","title":"Topics","text":"<p>The <code>header.topics</code> strings allow you to set the the ordering context for each message you send, and you are strongly encouraged to set it explicitly on every message you send (falling back to the <code>default</code> topic is not recommended).</p> <p>A key difference between blockchain backed decentralized applications and other event-driven applications, is that there is a single source of truth for the order in which things happen.</p> <p>In a multi-party system with off-chain transfer of data as well as on-chain transfer of data, the two sets of data need to be coordinated together. The off-chain transfer might happen at different times, and is subject to the reliability of the parties &amp; network links involved in that off-chain communication.</p> <p>A \"stop the world\" approach to handling a single piece of missing data is not practical for a high volume production business network.</p> <p>The ordering context is a function of:</p> <ol> <li>Whether the message is broadcast or private</li> <li>If it is private, the privacy group associated with the message</li> <li>The <code>topic</code> of the message</li> </ol> <p>When an on-chain transaction is detected by FireFly, it can determine the above ordering - noting that privacy is preserved for private messages by masking this ordering context message-by-message with a nonce and the group ID, so that only the participants in that group can decode the ordering context.</p> <p>If a piece of off-chain data is unavailable, then the FireFly node will block only streams of data that are associated with that ordering context.</p> <p>For your application, you should choose the most granular identifier you can for your <code>topic</code> to minimize the scope of any blockage if one item of off-chain data fails to be delivered or is delayed. Some good examples are:</p> <ul> <li>A business transaction identifier - to ensure all data related to particular business transaction are processed in order</li> <li>A globally agreed customer identifier - to ensure all data related to a particular business entity are processed in order</li> </ul>"},{"location":"reference/types/message/#using-multiple-topics","title":"Using multiple topics","text":"<p>There are some advanced scenarios where you need to merge streams of ordered data, so that two previously separately ordered streams of communication (different state machines) are joined together to process a critical decision/transition in a deterministic order.</p> <p>A synchronization point between two otherwise independent streams of communication.</p> <p>To do this, simply specify two <code>topics</code> in the message you sent, and the message will be independently ordered against both of those topics.</p> <p>You will also receive two events for the confirmation of that message, one for each topic.</p> <p>Some examples:</p> <ul> <li>Agreeing to join two previously separate business transactions with ids <code>000001</code> and <code>000002</code>, by discarding business transaction <code>000001</code> as a duplicate</li> <li>Specify <code>topics: [\"000001\",\"000002\"]</code> on the special merge message, and then from that point onwards you would only need to specify <code>topics: [\"000002\"]</code>.</li> <li>Agreeing to join two previously separate entities with <code>id1</code> and <code>id2</code>, into a merged entity with <code>id3</code>.</li> <li>Specify <code>topics: [\"id1\",\"id2\",\"id3\"]</code> on the special merge message, and then from that point onwards you would only need to specify <code>topics: [\"id3\"]</code>.</li> </ul>"},{"location":"reference/types/message/#transaction-type","title":"Transaction type","text":"<p>By default messages are pinned to the blockchain, within a Batch.</p> <p>For private messages, you can choose to disable this pinning by setting <code>header.txtype: \"unpinned\"</code>.</p> <p>Broadcast messages must be pinned to the blockchain.</p>"},{"location":"reference/types/message/#in-line-data","title":"In-line data","text":"<p>When sending a message you can specify the array of Data attachments in-line, as part of the same JSON payload.</p> <p>For example, a minimal broadcast message could be:</p> <pre><code>{\n    \"data\": [\n        {\"value\": \"hello world\"}\n    ]\n}\n</code></pre> <p>When you send this message with <code>/api/v1/namespaces/{ns}/messages/broadcast</code>:</p> <ul> <li>The <code>header</code> will be initialized with the default values, including <code>txtype: \"batch_pin\"</code></li> <li>The <code>data[0]</code> entry will be stored as a Data resource</li> <li>The message will be assembled into a batch and broadcast</li> </ul>"},{"location":"reference/types/message/#example","title":"Example","text":"<pre><code>{\n    \"header\": {\n        \"id\": \"4ea27cce-a103-4187-b318-f7b20fd87bf3\",\n        \"cid\": \"00d20cba-76ed-431d-b9ff-f04b4cbee55c\",\n        \"type\": \"private\",\n        \"txtype\": \"batch_pin\",\n        \"author\": \"did:firefly:org/acme\",\n        \"key\": \"0xD53B0294B6a596D404809b1d51D1b4B3d1aD4945\",\n        \"created\": \"2022-05-16T01:23:10Z\",\n        \"namespace\": \"ns1\",\n        \"group\": \"781caa6738a604344ae86ee336ada1b48a404a85e7041cf75b864e50e3b14a22\",\n        \"topics\": [\n            \"topic1\"\n        ],\n        \"tag\": \"blue_message\",\n        \"datahash\": \"c07be180b147049baced0b6219d9ce7a84ab48f2ca7ca7ae949abb3fe6491b54\"\n    },\n    \"localNamespace\": \"ns1\",\n    \"state\": \"confirmed\",\n    \"confirmed\": \"2022-05-16T01:23:16Z\",\n    \"data\": [\n        {\n            \"id\": \"fdf9f118-eb81-4086-a63d-b06715b3bb4e\",\n            \"hash\": \"34cf848d896c83cdf433ea7bd9490c71800b316a96aac3c3a78a42a4c455d67d\"\n        }\n    ]\n}\n</code></pre>"},{"location":"reference/types/message/#field-descriptions","title":"Field Descriptions","text":"Field Name Description Type <code>header</code> The message header contains all fields that are used to build the message hash <code>MessageHeader</code> <code>localNamespace</code> The local namespace of the message <code>string</code> <code>hash</code> The hash of the message. Derived from the header, which includes the data hash <code>Bytes32</code> <code>batch</code> The UUID of the batch in which the message was pinned/transferred <code>UUID</code> <code>txid</code> The ID of the transaction used to order/deliver this message <code>UUID</code> <code>state</code> The current state of the message <code>FFEnum</code>:<code>\"staged\"</code><code>\"ready\"</code><code>\"sent\"</code><code>\"pending\"</code><code>\"confirmed\"</code><code>\"rejected\"</code><code>\"cancelled\"</code> <code>confirmed</code> The timestamp of when the message was confirmed/rejected <code>FFTime</code> <code>rejectReason</code> If a message was rejected, provides details on the rejection reason <code>string</code> <code>data</code> The list of data elements attached to the message <code>DataRef[]</code> <code>pins</code> For private messages, a unique pin hash:nonce is assigned for each topic <code>string[]</code> <code>idempotencyKey</code> An optional unique identifier for a message. Cannot be duplicated within a namespace, thus allowing idempotent submission of messages to the API. Local only - not transferred when the message is sent to other members of the network <code>IdempotencyKey</code>"},{"location":"reference/types/message/#messageheader","title":"MessageHeader","text":"Field Name Description Type <code>id</code> The UUID of the message. Unique to each message <code>UUID</code> <code>cid</code> The correlation ID of the message. Set this when a message is a response to another message <code>UUID</code> <code>type</code> The type of the message <code>FFEnum</code>:<code>\"definition\"</code><code>\"broadcast\"</code><code>\"private\"</code><code>\"groupinit\"</code><code>\"transfer_broadcast\"</code><code>\"transfer_private\"</code><code>\"approval_broadcast\"</code><code>\"approval_private\"</code> <code>txtype</code> The type of transaction used to order/deliver this message <code>FFEnum</code>:<code>\"none\"</code><code>\"unpinned\"</code><code>\"batch_pin\"</code><code>\"network_action\"</code><code>\"token_pool\"</code><code>\"token_transfer\"</code><code>\"contract_deploy\"</code><code>\"contract_invoke\"</code><code>\"contract_invoke_pin\"</code><code>\"token_approval\"</code><code>\"data_publish\"</code> <code>author</code> The DID of identity of the submitter <code>string</code> <code>key</code> The on-chain signing key used to sign the transaction <code>string</code> <code>created</code> The creation time of the message <code>FFTime</code> <code>namespace</code> The namespace of the message within the multiparty network <code>string</code> <code>topics</code> A message topic associates this message with an ordered stream of data. A custom topic should be assigned - using the default topic is discouraged <code>string[]</code> <code>tag</code> The message tag indicates the purpose of the message to the applications that process it <code>string</code> <code>datahash</code> A single hash representing all data in the message. Derived from the array of data ids+hashes attached to this message <code>Bytes32</code> <code>txparent</code> The parent transaction that originally triggered this message <code>TransactionRef</code>"},{"location":"reference/types/message/#transactionref","title":"TransactionRef","text":"Field Name Description Type <code>type</code> The type of the FireFly transaction <code>FFEnum</code>: <code>id</code> The UUID of the FireFly transaction <code>UUID</code>"},{"location":"reference/types/message/#dataref","title":"DataRef","text":"Field Name Description Type <code>id</code> The UUID of the referenced data resource <code>UUID</code> <code>hash</code> The hash of the referenced data <code>Bytes32</code>"},{"location":"reference/types/namespace/","title":"Namespace","text":"<p>A namespace is a logical isolation domain for different applications, or tenants, that share the FireFly node.</p> <p>Significant evolution of the Hyperledger FireFly namespace construct, is proposed under FIR-12</p>"},{"location":"reference/types/namespace/#example","title":"Example","text":"<pre><code>{\n    \"name\": \"default\",\n    \"networkName\": \"default\",\n    \"description\": \"Default predefined namespace\",\n    \"created\": \"2022-05-16T01:23:16Z\"\n}\n</code></pre>"},{"location":"reference/types/namespace/#field-descriptions","title":"Field Descriptions","text":"Field Name Description Type <code>name</code> The local namespace name <code>string</code> <code>networkName</code> The shared namespace name within the multiparty network <code>string</code> <code>description</code> A description of the namespace <code>string</code> <code>created</code> The time the namespace was created <code>FFTime</code>"},{"location":"reference/types/nextpin/","title":"NextPin","text":"<p>Next-pins are maintained by each member of a privacy group, in order to detect if a on-chain transaction with a given \"pin\" for a message represents the next message for any member of the privacy group.</p> <p>This allows every member to maintain a global order of transactions within a <code>topic</code> in a privacy group, without leaking the same hash between the messages that are communicated in that group.</p> <p>See Group for more information on privacy groups.</p>"},{"location":"reference/types/nextpin/#example","title":"Example","text":"<pre><code>{\n    \"namespace\": \"ns1\",\n    \"context\": \"a25b65cfe49e5ed78c256e85cf07c96da938144f12fcb02fe4b5243a4631bd5e\",\n    \"identity\": \"did:firefly:org/example\",\n    \"hash\": \"00e55c63905a59782d5bc466093ead980afc4a2825eb68445bcf1312cc3d6de2\",\n    \"nonce\": 12345\n}\n</code></pre>"},{"location":"reference/types/nextpin/#field-descriptions","title":"Field Descriptions","text":"Field Name Description Type <code>namespace</code> The namespace of the next-pin <code>string</code> <code>context</code> The context the next-pin applies to - the hash of the privacy group-hash + topic. The group-hash is only known to the participants (can itself contain a salt in the group-name). This context is combined with the member and nonce to determine the final hash that is written on-chain <code>Bytes32</code> <code>identity</code> The member of the privacy group the next-pin applies to <code>string</code> <code>hash</code> The unique masked pin string <code>Bytes32</code> <code>nonce</code> The numeric index - which is monotonically increasing for each member of the privacy group <code>int64</code>"},{"location":"reference/types/operation/","title":"Operation","text":"<p>Operations are stateful external actions that FireFly triggers via plugins. They can succeed or fail. They are grouped into Transactions in order to accomplish a single logical task.</p> <p>The diagram below shows the different types of operation that are performed by each FireFly plugin type. The color coding (and numbers) map those different types of operation to the Transaction types that include those operations.</p> <p></p>"},{"location":"reference/types/operation/#operation-status","title":"Operation status","text":"<p>When initially created an operation is in <code>Initialized</code> state. Once the operation has been successfully sent to its respective plugin to be processed its status moves to <code>Pending</code> state. This indicates that the plugin is processing the operation. The operation will then move to <code>Succeeded</code> or <code>Failed</code> state depending on the outcome.</p> <p>In the event that an operation could not be submitted to the plugin for processing, for example because the plugin's microservice was temporarily unavailable, the operation will remain in <code>Initialized</code> state. Re-submitting the same FireFly API call using the same idempotency key will cause FireFly to re-submit the operation to its plugin.</p>"},{"location":"reference/types/operation/#example","title":"Example","text":"<pre><code>{\n    \"id\": \"04a8b0c4-03c2-4935-85a1-87d17cddc20a\",\n    \"namespace\": \"ns1\",\n    \"tx\": \"99543134-769b-42a8-8be4-a5f8873f969d\",\n    \"type\": \"sharedstorage_upload_batch\",\n    \"status\": \"Succeeded\",\n    \"plugin\": \"ipfs\",\n    \"input\": {\n        \"id\": \"80d89712-57f3-48fe-b085-a8cba6e0667d\"\n    },\n    \"output\": {\n        \"payloadRef\": \"QmWj3tr2aTHqnRYovhS2mQAjYneRtMWJSU4M4RdAJpJwEC\"\n    },\n    \"created\": \"2022-05-16T01:23:15Z\"\n}\n</code></pre>"},{"location":"reference/types/operation/#field-descriptions","title":"Field Descriptions","text":"Field Name Description Type <code>id</code> The UUID of the operation <code>UUID</code> <code>namespace</code> The namespace of the operation <code>string</code> <code>tx</code> The UUID of the FireFly transaction the operation is part of <code>UUID</code> <code>type</code> The type of the operation <code>FFEnum</code>:<code>\"blockchain_pin_batch\"</code><code>\"blockchain_network_action\"</code><code>\"blockchain_deploy\"</code><code>\"blockchain_invoke\"</code><code>\"sharedstorage_upload_batch\"</code><code>\"sharedstorage_upload_blob\"</code><code>\"sharedstorage_upload_value\"</code><code>\"sharedstorage_download_batch\"</code><code>\"sharedstorage_download_blob\"</code><code>\"dataexchange_send_batch\"</code><code>\"dataexchange_send_blob\"</code><code>\"token_create_pool\"</code><code>\"token_activate_pool\"</code><code>\"token_transfer\"</code><code>\"token_approval\"</code> <code>status</code> The current status of the operation <code>OpStatus</code> <code>plugin</code> The plugin responsible for performing the operation <code>string</code> <code>input</code> The input to this operation <code>JSONObject</code> <code>output</code> Any output reported back from the plugin for this operation <code>JSONObject</code> <code>error</code> Any error reported back from the plugin for this operation <code>string</code> <code>created</code> The time the operation was created <code>FFTime</code> <code>updated</code> The last update time of the operation <code>FFTime</code> <code>retry</code> If this operation was initiated as a retry to a previous operation, this field points to the UUID of the operation being retried <code>UUID</code>"},{"location":"reference/types/operationwithdetail/","title":"OperationWithDetail","text":"<p>Operation with detail is an extension to operations that allow additional information to be encapsulated with an operation. An operation can be supplemented by a connector and that information will be returned in the <code>detail</code> field.</p>"},{"location":"reference/types/operationwithdetail/#example","title":"Example","text":"<pre><code>{\n    \"id\": \"04a8b0c4-03c2-4935-85a1-87d17cddc20a\",\n    \"namespace\": \"ns1\",\n    \"tx\": \"99543134-769b-42a8-8be4-a5f8873f969d\",\n    \"type\": \"sharedstorage_upload_batch\",\n    \"status\": \"Succeeded\",\n    \"plugin\": \"ipfs\",\n    \"input\": {\n        \"id\": \"80d89712-57f3-48fe-b085-a8cba6e0667d\"\n    },\n    \"output\": {\n        \"payloadRef\": \"QmWj3tr2aTHqnRYovhS2mQAjYneRtMWJSU4M4RdAJpJwEC\"\n    },\n    \"created\": \"2022-05-16T01:23:15Z\",\n    \"detail\": {\n        \"created\": \"2023-01-27T17:04:24.26406392Z\",\n        \"firstSubmit\": \"2023-01-27T17:04:24.419913295Z\",\n        \"gas\": \"4161076\",\n        \"gasPrice\": \"0\",\n        \"history\": [\n            {\n                \"actions\": [\n                    {\n                        \"action\": \"AssignNonce\",\n                        \"count\": 1,\n                        \"lastOccurrence\": \"\",\n                        \"time\": \"\"\n                    },\n                    {\n                        \"action\": \"RetrieveGasPrice\",\n                        \"count\": 1,\n                        \"lastOccurrence\": \"2023-01-27T17:11:41.161213303Z\",\n                        \"time\": \"2023-01-27T17:11:41.161213303Z\"\n                    },\n                    {\n                        \"action\": \"Submit\",\n                        \"count\": 1,\n                        \"lastOccurrence\": \"2023-01-27T17:11:41.222374636Z\",\n                        \"time\": \"2023-01-27T17:11:41.222374636Z\"\n                    }\n                ],\n                \"subStatus\": \"Received\",\n                \"time\": \"2023-01-27T17:11:41.122965803Z\"\n            },\n            {\n                \"actions\": [\n                    {\n                        \"action\": \"ReceiveReceipt\",\n                        \"count\": 1,\n                        \"lastOccurrence\": \"2023-01-27T17:11:47.930332625Z\",\n                        \"time\": \"2023-01-27T17:11:47.930332625Z\"\n                    },\n                    {\n                        \"action\": \"Confirm\",\n                        \"count\": 1,\n                        \"lastOccurrence\": \"2023-01-27T17:12:02.660275549Z\",\n                        \"time\": \"2023-01-27T17:12:02.660275549Z\"\n                    }\n                ],\n                \"subStatus\": \"Tracking\",\n                \"time\": \"2023-01-27T17:11:41.222400219Z\"\n            },\n            {\n                \"actions\": [],\n                \"subStatus\": \"Confirmed\",\n                \"time\": \"2023-01-27T17:12:02.660309382Z\"\n            }\n        ],\n        \"historySummary\": [\n            {\n                \"count\": 1,\n                \"subStatus\": \"Received\"\n            },\n            {\n                \"action\": \"AssignNonce\",\n                \"count\": 1\n            },\n            {\n                \"action\": \"RetrieveGasPrice\",\n                \"count\": 1\n            },\n            {\n                \"action\": \"Submit\",\n                \"count\": 1\n            },\n            {\n                \"count\": 1,\n                \"subStatus\": \"Tracking\"\n            },\n            {\n                \"action\": \"ReceiveReceipt\",\n                \"count\": 1\n            },\n            {\n                \"action\": \"Confirm\",\n                \"count\": 1\n            },\n            {\n                \"count\": 1,\n                \"subStatus\": \"Confirmed\"\n            }\n        ],\n        \"sequenceId\": \"0185f42f-fec8-93df-aeba-387417d477e0\",\n        \"status\": \"Succeeded\",\n        \"transactionHash\": \"0xfb39178fee8e725c03647b8286e6f5cb13f982abf685479a9ee59e8e9d9e51d8\"\n    }\n}\n</code></pre>"},{"location":"reference/types/operationwithdetail/#field-descriptions","title":"Field Descriptions","text":"Field Name Description Type <code>id</code> The UUID of the operation <code>UUID</code> <code>namespace</code> The namespace of the operation <code>string</code> <code>tx</code> The UUID of the FireFly transaction the operation is part of <code>UUID</code> <code>type</code> The type of the operation <code>FFEnum</code>:<code>\"blockchain_pin_batch\"</code><code>\"blockchain_network_action\"</code><code>\"blockchain_deploy\"</code><code>\"blockchain_invoke\"</code><code>\"sharedstorage_upload_batch\"</code><code>\"sharedstorage_upload_blob\"</code><code>\"sharedstorage_upload_value\"</code><code>\"sharedstorage_download_batch\"</code><code>\"sharedstorage_download_blob\"</code><code>\"dataexchange_send_batch\"</code><code>\"dataexchange_send_blob\"</code><code>\"token_create_pool\"</code><code>\"token_activate_pool\"</code><code>\"token_transfer\"</code><code>\"token_approval\"</code> <code>status</code> The current status of the operation <code>OpStatus</code> <code>plugin</code> The plugin responsible for performing the operation <code>string</code> <code>input</code> The input to this operation <code>JSONObject</code> <code>output</code> Any output reported back from the plugin for this operation <code>JSONObject</code> <code>error</code> Any error reported back from the plugin for this operation <code>string</code> <code>created</code> The time the operation was created <code>FFTime</code> <code>updated</code> The last update time of the operation <code>FFTime</code> <code>retry</code> If this operation was initiated as a retry to a previous operation, this field points to the UUID of the operation being retried <code>UUID</code> <code>detail</code> Additional detailed information about an operation provided by the connector ``"},{"location":"reference/types/simpletypes/","title":"Simple Types","text":""},{"location":"reference/types/simpletypes/#uuid","title":"UUID","text":"<p>IDs are generated as UUID V4 globally unique identifiers</p>"},{"location":"reference/types/simpletypes/#fftime","title":"FFTime","text":"<p>Times are serialized to JSON on the API in RFC 3339 / ISO 8601 nanosecond UTC time for example <code>2022-05-05T21:19:27.454767543Z</code>.</p> <p>Note that JavaScript can parse this format happily into millisecond time with <code>Date.parse()</code>.</p> <p>Times are persisted as a nanosecond resolution timestamps in the database.</p> <p>On input, and in queries, times can be parsed from RFC3339, or unix timestamps (second, millisecond or nanosecond resolution).</p>"},{"location":"reference/types/simpletypes/#ffbigint","title":"FFBigInt","text":"<p>Large integers of up to 256bits in size are common in blockchain, and handled in FireFly.</p> <p>In JSON output payloads in FireFly, including events, they are serialized as strings (with base 10).</p> <p>On input you can provide JSON string (string with an <code>0x</code> prefix are parsed at base 16), or a JSON number.</p>"},{"location":"reference/types/simpletypes/#maximum-size-of-numbers-in-versions-of-firefly-up-to-v131","title":"Maximum size of numbers in versions of FireFly up to <code>v1.3.1</code>","text":"<p>In versions of FireFly up to and including <code>v1.3.1</code>, be careful when using large JSON numbers. The largest number that is safe to transfer using a JSON number is 2^53 - 1 and it is possible to receive errors from the transaction manager, or for precision to be silently lost when passing numeric parameters larger than that. It is recommended to pass large numbers as strings to avoid loss of precision.</p>"},{"location":"reference/types/simpletypes/#maximum-size-of-numbers-in-versions-of-firefly-v132-and-higher","title":"Maximum size of numbers in versions of FireFly <code>v1.3.2</code> and higher","text":"<p>In FireFly <code>v1.3.2</code> support was added for 256-bit precision JSON numbers. Some application frameworks automatically serialize large JSON numbers to a string which FireFly already supports, but there is no upper limit to the size of a number that can be represented in JSON. FireFly now supports much larger JSON numbers, up to 256-bit precision. For example the following input parameter to a contract constructor is now supported:</p> <pre><code>    ...\n    \"definition\": [{\n        \"inputs\": [\n            {\n                \"internalType\":\" uint256\",\n                \"name\": \"x\",\n                \"type\": \"uint256\"\n            }\n        ],\n        \"outputs\":[],\n        \"type\":\"constructor\"\n    }],\n    \"params\": [ 10000000000000000000000000 ]\n    ...\n</code></pre> <p>Some application frameworks seralize large numbers in scientific notation e.g. <code>1e+25</code>. FireFly <code>v1.3.2</code> added supported for handling scientific numbers in parameters. This removes the need to change an application that uses this number format. For example the following input parameter to a contract constructor is now supported:</p> <pre><code>    ...\n    \"definition\": [{\n        \"inputs\": [\n            {\n                \"internalType\":\" uint256\",\n                \"name\": \"x\",\n                \"type\": \"uint256\"\n            }\n        ],\n        \"outputs\":[],\n        \"type\":\"constructor\"\n    }],\n    \"params\": [ 1e+25 ]\n    ...\n</code></pre>"},{"location":"reference/types/simpletypes/#jsonany","title":"JSONAny","text":"<p>Any JSON type. An <code>object</code>, <code>array</code>, <code>string</code>, <code>number</code>, <code>boolean</code> or <code>null</code>.</p> <p>FireFly stores object data with the same field order as was provided on the input, but with any whitespace removed.</p>"},{"location":"reference/types/simpletypes/#jsonobject","title":"JSONObject","text":"<p>Any JSON Object. Must be an object, rather than an array or a simple type.</p>"},{"location":"reference/types/subscription/","title":"Subscription","text":"<p>Each Subscription tracks delivery of events to a particular application, and allows FireFly to ensure that messages are delivered reliably to that application.</p> <p></p>"},{"location":"reference/types/subscription/#creating-a-subscription","title":"Creating a subscription","text":"<p>Before you can connect to a subscription, you must create it via the REST API.</p> <p>One special case where you do not need to do this, is Ephemeral WebSocket connections (described below). For these you can just connect and immediately start receiving events.</p> <p>When creating a new subscription, you give it a <code>name</code> which is how you will refer to it when you connect.</p> <p>You are also able to specify server-side filtering that should be performed against the event stream, to limit the set of events that are sent to your application.</p> <p>All subscriptions are created within a <code>namespace</code>, and automatically filter events to only those emitted within that namespace.</p> <p>You can create multiple subscriptions for your application, to request different sets of server-side filtering for events. You can then request FireFly to deliver events for both subscriptions over the same WebSocket (if you are using the WebSocket transport). However, delivery order is not assured between two subscriptions.</p>"},{"location":"reference/types/subscription/#subscriptions-and-workload-balancing","title":"Subscriptions and workload balancing","text":"<p>You can have multiple scaled runtime instances of a single application, all running in parallel. These instances of the application all share a single subscription.</p> <p>Each event is only delivered once to the subscription, regardless of how many instances of your application connect to FireFly.</p> <p>With multiple WebSocket connections active on a single subscription, each event might be delivered to different instance of your application. This means workload is balanced across your instances. However, each event still needs to be acknowledged, so delivery processing order can still be maintained within your application database state.</p> <p>If you have multiple different applications all needing their own copy of the same event, then you need to configure a separate subscription for each application.</p>"},{"location":"reference/types/subscription/#pluggable-transports","title":"Pluggable Transports","text":"<p>Hyperledger FireFly has two built-in transports for delivery of events to applications - WebSockets and Webhooks.</p> <p>The event interface is fully pluggable, so you can extend connectivity over an external event bus - such as NATS, Apache Kafka, Rabbit MQ, Redis etc.</p>"},{"location":"reference/types/subscription/#websockets","title":"WebSockets","text":"<p>If your application has a back-end server runtime, then WebSockets are the most popular option for listening to events. WebSockets are well supported by all popular application development frameworks, and are very firewall friendly for connecting applications into your FireFly server.</p> <p>Check out the @hyperledger/firefly-sdk SDK for Node.js applications, and the hyperledger/firefly-common module for Golang applications. These both contain reliable WebSocket clients for your event listeners.</p> <p>A Java SDK is a roadmap item for the community.</p>"},{"location":"reference/types/subscription/#websocket-protocol","title":"WebSocket protocol","text":"<p>FireFly has a simple protocol on top of WebSockets:</p> <ol> <li>Each time you connect/reconnect you need to tell FireFly to start    sending you events on a particular subscription. You can do this in two    ways (described in detail below):</li> <li>Send a WSStart JSON payload</li> <li>Include a <code>namespace</code> and <code>name</code> query parameter in the URL when you       connect, along with query params for other fields of WSStart</li> <li>One you have started your subscription, each event flows from    the server, to your application as a JSON Event payload</li> <li>For each event you receive, you need to send a WSAck payload.</li> <li>Unless you specified <code>autoack</code> in step (1)</li> </ol> <p>The SDK libraries for FireFly help you ensure you send the <code>start</code> payload each time your WebSocket reconnects.</p>"},{"location":"reference/types/subscription/#using-start-and-ack-explicitly","title":"Using <code>start</code> and <code>ack</code> explicitly","text":"<p>Here's an example websocat command showing an explicit <code>start</code> and <code>ack</code>.</p> <pre><code>$ websocat ws://localhost:5000/ws\n{\"type\":\"start\",\"namespace\":\"default\",\"name\":\"docexample\"}\n# ... for each event that arrives here, you send an ack ...\n{\"type\":\"ack\",\"id\":\"70ed4411-57cf-4ba1-bedb-fe3b4b5fd6b6\"}\n</code></pre> <p>When creating your subscription, you can set <code>readahead</code> in order to ask FireFly to stream a number of messages to your application, ahead of receiving the acknowledgements.</p> <p><code>readahead</code> can be a powerful tool to increase performance, but does require your application to ensure it processes events in the correct order and sends exactly one <code>ack</code> for each event.</p>"},{"location":"reference/types/subscription/#auto-starting-via-url-query-and-autoack","title":"Auto-starting via URL query and <code>autoack</code>","text":"<p>Here's an example websocat where we use URL query parameters to avoid the need to send a <code>start</code> JSON payload.</p> <p>We also use <code>autoack</code> so that events just keep flowing from the server.</p> <pre><code>$ websocat \"ws://localhost:5000/ws?namespace=default&amp;name=docexample&amp;autoack\"\n# ... events just keep arriving here, as the server-side auto-acknowledges\n#     the events as it delivers them to you.\n</code></pre> <p>Note using <code>autoack</code> means you can miss events in the case of a disconnection, so should not be used for production applications that require at-least-once delivery.</p>"},{"location":"reference/types/subscription/#ephemeral-websocket-subscriptions","title":"Ephemeral WebSocket subscriptions","text":"<p>FireFly WebSockets provide a special option to create a subscription dynamically, that only lasts for as long as you are connected to the server.</p> <p>We call these <code>ephemeral</code> subscriptions.</p> <p>Here's an example websocat command showing an an ephemeral subscription - notice we don't specify a <code>name</code> for the subscription, and there is no need to have already created the subscription beforehand.</p> <p>Here we also include an extra query parameter to set a server-side filter, to only include message events.</p> <pre><code>$ websocat \"ws://localhost:5000/ws?namespace=default&amp;ephemeral&amp;autoack&amp;filter.events=message_.*\"\n{\"type\":\"start\",\"namespace\":\"default\",\"name\":\"docexample\"}\n# ... for each event that arrives here, you send an ack ...\n{\"type\":\"ack\",\"id\":\"70ed4411-57cf-4ba1-bedb-fe3b4b5fd6b6\"}\n</code></pre> <p>Ephemeral subscriptions are very convenient for experimentation, debugging and monitoring. However, they do not give reliable delivery because you only receive events that occur while you are connected. If you disconnect and reconnect, you will miss all events that happened while your application was not listening.</p>"},{"location":"reference/types/subscription/#webhooks","title":"Webhooks","text":"<p>The Webhook transport allows FireFly to make HTTP calls against your application's API when events matching your subscription are emitted.</p> <p>This means the direction of network connection is from the FireFly server, to the application (the reverse of WebSockets). Conversely it means you don't need to add any connection management code to your application - just expose and API that FireFly can call to process the events.</p> <p>Webhooks are great for serverless functions (AWS Lambda etc.), integrations with SaaS applications, and calling existing APIs.</p> <p>The FireFly configuration options for a Webhook subscription are very flexible, allowing you to customize your HTTP requests as follows:</p> <ul> <li>Set the HTTP request details:</li> <li>Method, URL, query, headers and input body</li> <li>Wait for a invocation of the back-end service, before acknowledging</li> <li>To retry requests to your Webhook on a non-<code>2xx</code> HTTP status code     or other error, you should enable and configure     options.retry</li> <li>The event is acknowledged once the request (with any retries), is     completed - regardless of whether the outcome was a success or failure.</li> <li>Use <code>fastack</code> to acknowledge against FireFly immediately and make multiple   parallel calls to the HTTP API in a fire-and-forget fashion.</li> <li>Set the HTTP request details dynamically from <code>message_confirmed</code> events:</li> <li>Map data out of the first <code>data</code> element in message events</li> <li>Requires <code>withData</code> to be set on the subscription, in addition to the     <code>input.*</code> configuration options</li> <li>Can automatically generate a \"reply\" message for <code>message_confirmed</code> events:</li> <li>Maps the response body of the HTTP call to data in the reply message</li> <li>Sets the <code>cid</code> and <code>topic</code> in the reply message to match the request</li> <li>Sets a <code>tag</code> in the reply message, per the configuration, or dynamically     based on a field in the input request data.</li> </ul>"},{"location":"reference/types/subscription/#batching-events","title":"Batching events","text":"<p>Webhooks have the ability to batch events into a single HTTP request instead of sending an event per HTTP request. The interface will be a JSON array of events instead of a top level JSON object with a single event. The size of the batch will be set by the <code>readAhead</code> limit and an optional timeout can be specified to send the events when the batch hasn't filled.</p> <p>To enable this set the following configuration under SubscriptionOptions</p> <p><code>batch</code> | Events are delivered in batches in an ordered array. The batch size is capped to the readAhead limit. The event payload is always an array even if there is a single event in the batch. Commonly used with Webhooks to allow events to be delivered and acknowledged in batches. | <code>bool</code> |</p> <p><code>batchTimeout</code> | When batching is enabled, the optional timeout to send events even when the batch hasn't filled. Defaults to 2 seconds | <code>string</code></p> <p>NOTE: When batch is enabled, <code>withData</code> cannot be used as these may alter the HTTP request based on a single event and in batching it does not make sense for now.</p>"},{"location":"reference/types/subscription/#example","title":"Example","text":"<pre><code>{\n    \"id\": \"c38d69fd-442e-4d6f-b5a4-bab1411c7fe8\",\n    \"namespace\": \"ns1\",\n    \"name\": \"app1\",\n    \"transport\": \"websockets\",\n    \"filter\": {\n        \"events\": \"^(message_.*|token_.*)$\",\n        \"message\": {\n            \"tag\": \"^(red|blue)$\"\n        },\n        \"transaction\": {},\n        \"blockchainevent\": {}\n    },\n    \"options\": {\n        \"firstEvent\": \"newest\",\n        \"readAhead\": 50\n    },\n    \"created\": \"2022-05-16T01:23:15Z\",\n    \"updated\": null\n}\n</code></pre>"},{"location":"reference/types/subscription/#field-descriptions","title":"Field Descriptions","text":"Field Name Description Type <code>id</code> The UUID of the subscription <code>UUID</code> <code>namespace</code> The namespace of the subscription. A subscription will only receive events generated in the namespace of the subscription <code>string</code> <code>name</code> The name of the subscription. The application specifies this name when it connects, in order to attach to the subscription and receive events that arrived while it was disconnected. If multiple apps connect to the same subscription, events are workload balanced across the connected application instances <code>string</code> <code>transport</code> The transport plugin responsible for event delivery (WebSockets, Webhooks, JMS, NATS etc.) <code>string</code> <code>filter</code> Server-side filter to apply to events <code>SubscriptionFilter</code> <code>options</code> Subscription options <code>SubscriptionOptions</code> <code>ephemeral</code> Ephemeral subscriptions only exist as long as the application is connected, and as such will miss events that occur while the application is disconnected, and cannot be created administratively. You can create one over over a connected WebSocket connection <code>bool</code> <code>created</code> Creation time of the subscription <code>FFTime</code> <code>updated</code> Last time the subscription was updated <code>FFTime</code>"},{"location":"reference/types/subscription/#subscriptionfilter","title":"SubscriptionFilter","text":"Field Name Description Type <code>events</code> Regular expression to apply to the event type, to subscribe to a subset of event types <code>string</code> <code>message</code> Filters specific to message events. If an event is not a message event, these filters are ignored <code>MessageFilter</code> <code>transaction</code> Filters specific to events with a transaction. If an event is not associated with a transaction, this filter is ignored <code>TransactionFilter</code> <code>blockchainevent</code> Filters specific to blockchain events. If an event is not a blockchain event, these filters are ignored <code>BlockchainEventFilter</code> <code>topic</code> Regular expression to apply to the topic of the event, to subscribe to a subset of topics. Note for messages sent with multiple topics, a separate event is emitted for each topic <code>string</code> <code>topics</code> Deprecated: Please use 'topic' instead <code>string</code> <code>tag</code> Deprecated: Please use 'message.tag' instead <code>string</code> <code>group</code> Deprecated: Please use 'message.group' instead <code>string</code> <code>author</code> Deprecated: Please use 'message.author' instead <code>string</code>"},{"location":"reference/types/subscription/#messagefilter","title":"MessageFilter","text":"Field Name Description Type <code>tag</code> Regular expression to apply to the message 'header.tag' field <code>string</code> <code>group</code> Regular expression to apply to the message 'header.group' field <code>string</code> <code>author</code> Regular expression to apply to the message 'header.author' field <code>string</code>"},{"location":"reference/types/subscription/#transactionfilter","title":"TransactionFilter","text":"Field Name Description Type <code>type</code> Regular expression to apply to the transaction 'type' field <code>string</code>"},{"location":"reference/types/subscription/#blockchaineventfilter","title":"BlockchainEventFilter","text":"Field Name Description Type <code>name</code> Regular expression to apply to the blockchain event 'name' field, which is the name of the event in the underlying blockchain smart contract <code>string</code> <code>listener</code> Regular expression to apply to the blockchain event 'listener' field, which is the UUID of the event listener. So you can restrict your subscription to certain blockchain listeners. Alternatively to avoid your application need to know listener UUIDs you can set the 'topic' field of blockchain event listeners, and use a topic filter on your subscriptions <code>string</code>"},{"location":"reference/types/subscription/#subscriptionoptions","title":"SubscriptionOptions","text":"Field Name Description Type <code>firstEvent</code> Whether your application would like to receive events from the 'oldest' event emitted by your FireFly node (from the beginning of time), or the 'newest' event (from now), or a specific event sequence. Default is 'newest' <code>SubOptsFirstEvent</code> <code>readAhead</code> The number of events to stream ahead to your application, while waiting for confirmation of consumption of those events. At least once delivery semantics are used in FireFly, so if your application crashes/reconnects this is the maximum number of events you would expect to be redelivered after it restarts <code>uint16</code> <code>withData</code> Whether message events delivered over the subscription, should be packaged with the full data of those messages in-line as part of the event JSON payload. Or if the application should make separate REST calls to download that data. May not be supported on some transports. <code>bool</code> <code>batch</code> Events are delivered in batches in an ordered array. The batch size is capped to the readAhead limit. The event payload is always an array even if there is a single event in the batch, allowing client-side optimizations when processing the events in a group. Available for both Webhooks and WebSockets. <code>bool</code> <code>batchTimeout</code> When batching is enabled, the optional timeout to send events even when the batch hasn't filled. <code>string</code> <code>fastack</code> Webhooks only: When true the event will be acknowledged before the webhook is invoked, allowing parallel invocations <code>bool</code> <code>url</code> Webhooks only: HTTP url to invoke. Can be relative if a base URL is set in the webhook plugin config <code>string</code> <code>method</code> Webhooks only: HTTP method to invoke. Default=POST <code>string</code> <code>json</code> Webhooks only: Whether to assume the response body is JSON, regardless of the returned Content-Type <code>bool</code> <code>reply</code> Webhooks only: Whether to automatically send a reply event, using the body returned by the webhook <code>bool</code> <code>replytag</code> Webhooks only: The tag to set on the reply message <code>string</code> <code>replytx</code> Webhooks only: The transaction type to set on the reply message <code>string</code> <code>headers</code> Webhooks only: Static headers to set on the webhook request `` <code>query</code> Webhooks only: Static query params to set on the webhook request `` <code>tlsConfigName</code> The name of an existing TLS configuration associated to the namespace to use <code>string</code> <code>input</code> Webhooks only: A set of options to extract data from the first JSON input data in the incoming message. Only applies if withData=true <code>WebhookInputOptions</code> <code>retry</code> Webhooks only: a set of options for retrying the webhook call <code>WebhookRetryOptions</code> <code>httpOptions</code> Webhooks only: a set of options for HTTP <code>WebhookHTTPOptions</code>"},{"location":"reference/types/subscription/#webhookinputoptions","title":"WebhookInputOptions","text":"Field Name Description Type <code>query</code> A top-level property of the first data input, to use for query parameters <code>string</code> <code>headers</code> A top-level property of the first data input, to use for headers <code>string</code> <code>body</code> A top-level property of the first data input, to use for the request body. Default is the whole first body <code>string</code> <code>path</code> A top-level property of the first data input, to use for a path to append with escaping to the webhook path <code>string</code> <code>replytx</code> A top-level property of the first data input, to use to dynamically set whether to pin the response (so the requester can choose) <code>string</code>"},{"location":"reference/types/subscription/#webhookretryoptions","title":"WebhookRetryOptions","text":"Field Name Description Type <code>enabled</code> Enables retry on HTTP calls, defaults to false <code>bool</code> <code>count</code> Number of times to retry the webhook call in case of failure <code>int</code> <code>initialDelay</code> Initial delay between retries when we retry the webhook call <code>string</code> <code>maxDelay</code> Max delay between retries when we retry the webhookcall <code>string</code>"},{"location":"reference/types/subscription/#webhookhttpoptions","title":"WebhookHTTPOptions","text":"Field Name Description Type <code>proxyURL</code> HTTP proxy URL to use for outbound requests to the webhook <code>string</code> <code>tlsHandshakeTimeout</code> The max duration to hold a TLS handshake alive <code>string</code> <code>requestTimeout</code> The max duration to hold a TLS handshake alive <code>string</code> <code>maxIdleConns</code> The max number of idle connections to hold pooled <code>int</code> <code>idleTimeout</code> The max duration to hold a HTTP keepalive connection between calls <code>string</code> <code>connectionTimeout</code> The maximum amount of time that a connection is allowed to remain with no data transmitted. <code>string</code> <code>expectContinueTimeout</code> See ExpectContinueTimeout in the Go docs <code>string</code>"},{"location":"reference/types/tokenapproval/","title":"TokenApproval","text":"<p>A token approval is a record that an address other than the owner of a token balance, has been granted authority to transfer tokens on the owners behalf.</p> <p>The approved \"operator\" (or \"spender\") account might be a smart contract, or another individual.</p> <p>FireFly provides APIs for initiating and tracking approvals, which token connectors integrate with the implementation of the underlying token.</p> <p>The off-chain index maintained in FireFly for allowance allows you to quickly find the most recent allowance event associated with a pair of keys, using the <code>subject</code> field, combined with the <code>active</code> field. When a new Token Approval event is delivered to FireFly Core by the Token Connector, any previous approval for the same subject is marked <code>\"active\": false</code>, and the new approval is marked with <code>\"active\": true</code></p> <p>The token connector is responsible for the format of the <code>subject</code> field to reflect the owner / operator (spender) relationship.</p>"},{"location":"reference/types/tokenapproval/#example","title":"Example","text":"<pre><code>{\n    \"localId\": \"1cd3e2e2-dd6a-441d-94c5-02439de9897b\",\n    \"pool\": \"1244ecbe-5862-41c3-99ec-4666a18b9dd5\",\n    \"connector\": \"erc20_erc721\",\n    \"key\": \"0x55860105d6a675dbe6e4d83f67b834377ba677ad\",\n    \"operator\": \"0x30017fd084715e41aa6536ab777a8f3a2b11a5a1\",\n    \"approved\": true,\n    \"info\": {\n        \"owner\": \"0x55860105d6a675dbe6e4d83f67b834377ba677ad\",\n        \"spender\": \"0x30017fd084715e41aa6536ab777a8f3a2b11a5a1\",\n        \"value\": \"115792089237316195423570985008687907853269984665640564039457584007913129639935\"\n    },\n    \"namespace\": \"ns1\",\n    \"protocolId\": \"000000000032/000000/000000\",\n    \"subject\": \"0x55860105d6a675dbe6e4d83f67b834377ba677ad:0x30017fd084715e41aa6536ab777a8f3a2b11a5a1\",\n    \"active\": true,\n    \"created\": \"2022-05-16T01:23:15Z\",\n    \"tx\": {\n        \"type\": \"token_approval\",\n        \"id\": \"4b6e086d-0e31-482d-9683-cd18b2045031\"\n    }\n}\n</code></pre>"},{"location":"reference/types/tokenapproval/#field-descriptions","title":"Field Descriptions","text":"Field Name Description Type <code>localId</code> The UUID of this token approval, in the local FireFly node <code>UUID</code> <code>pool</code> The UUID the token pool this approval applies to <code>UUID</code> <code>connector</code> The name of the token connector, as specified in the FireFly core configuration file. Required on input when there are more than one token connectors configured <code>string</code> <code>key</code> The blockchain signing key for the approval request. On input defaults to the first signing key of the organization that operates the node <code>string</code> <code>operator</code> The blockchain identity that is granted the approval <code>string</code> <code>approved</code> Whether this record grants permission for an operator to perform actions on the token balance (true), or revokes permission (false) <code>bool</code> <code>info</code> Token connector specific information about the approval operation, such as whether it applied to a limited balance of a fungible token. See your chosen token connector documentation for details <code>JSONObject</code> <code>namespace</code> The namespace for the approval, which must match the namespace of the token pool <code>string</code> <code>protocolId</code> An alphanumerically sortable string that represents this event uniquely with respect to the blockchain <code>string</code> <code>subject</code> A string identifying the parties and entities in the scope of this approval, as provided by the token connector <code>string</code> <code>active</code> Indicates if this approval is currently active (only one approval can be active per subject) <code>bool</code> <code>message</code> The UUID of a message that has been correlated with this approval using the data field of the approval in a compatible token connector <code>UUID</code> <code>messageHash</code> The hash of a message that has been correlated with this approval using the data field of the approval in a compatible token connector <code>Bytes32</code> <code>created</code> The creation time of the token approval <code>FFTime</code> <code>tx</code> If submitted via FireFly, this will reference the UUID of the FireFly transaction (if the token connector in use supports attaching data) <code>TransactionRef</code> <code>blockchainEvent</code> The UUID of the blockchain event <code>UUID</code> <code>config</code> Input only field, with token connector specific configuration of the approval.  See your chosen token connector documentation for details <code>JSONObject</code>"},{"location":"reference/types/tokenapproval/#transactionref","title":"TransactionRef","text":"Field Name Description Type <code>type</code> The type of the FireFly transaction <code>FFEnum</code>: <code>id</code> The UUID of the FireFly transaction <code>UUID</code>"},{"location":"reference/types/tokenpool/","title":"TokenPool","text":"<p>Token pools are a FireFly construct for describing a set of tokens.</p> <p>The total supply of a particular fungible token, or a group of related non-fungible tokens.</p> <p>The exact definition of a token pool is dependent on the token connector implementation.</p> <p>Check the documentation for your chosen connector implementation to see the detailed options for configuring a new Token Pool.</p> <p>Note that it is very common to use a Token Pool to teach Hyperledger FireFly about an existing token, so that you can start interacting with a token that already exists.</p>"},{"location":"reference/types/tokenpool/#example-token-pool-types","title":"Example token pool types","text":"<p>Some examples of how the generic concept of a Token Pool maps to various well-defined Ethereum standards:</p> <ul> <li>ERC-1155: a single contract instance can efficiently allocate   many isolated pools of fungible or non-fungible tokens</li> <li>ERC-20 / ERC-777:   each contract instance represents a single fungible pool of value, e.g. \"a coin\"</li> <li>ERC-721: each contract instance represents a single pool of NFTs,   each with unique identities within the pool</li> <li>ERC-1400 / ERC-1410:   partially supported in the same manner as ERC-20/ERC-777, but would require new features for working with partitions</li> </ul> <p>These are provided as examples only - a custom token connector could be backed by any token technology (Ethereum or otherwise) as long as it can support the basic operations described here (create pool, mint, burn, transfer). Other FireFly repos include a sample implementation of a token connector for ERC-20 and ERC-721 as well as ERC-1155.</p>"},{"location":"reference/types/tokenpool/#example","title":"Example","text":"<pre><code>{\n    \"id\": \"90ebefdf-4230-48a5-9d07-c59751545859\",\n    \"type\": \"fungible\",\n    \"namespace\": \"ns1\",\n    \"name\": \"my_token\",\n    \"standard\": \"ERC-20\",\n    \"locator\": \"address=0x056df1c53c3c00b0e13d37543f46930b42f71db0\\u0026schema=ERC20WithData\\u0026type=fungible\",\n    \"decimals\": 18,\n    \"connector\": \"erc20_erc721\",\n    \"message\": \"43923040-b1e5-4164-aa20-47636c7177ee\",\n    \"active\": true,\n    \"created\": \"2022-05-16T01:23:15Z\",\n    \"info\": {\n        \"address\": \"0x056df1c53c3c00b0e13d37543f46930b42f71db0\",\n        \"name\": \"pool8197\",\n        \"schema\": \"ERC20WithData\"\n    },\n    \"tx\": {\n        \"type\": \"token_pool\",\n        \"id\": \"a23ffc87-81a2-4cbc-97d6-f53d320c36cd\"\n    },\n    \"published\": false\n}\n</code></pre>"},{"location":"reference/types/tokenpool/#field-descriptions","title":"Field Descriptions","text":"Field Name Description Type <code>id</code> The UUID of the token pool <code>UUID</code> <code>type</code> The type of token the pool contains, such as fungible/non-fungible <code>FFEnum</code>:<code>\"fungible\"</code><code>\"nonfungible\"</code> <code>namespace</code> The namespace for the token pool <code>string</code> <code>name</code> The name of the token pool. Note the name is not validated against the description of the token on the blockchain <code>string</code> <code>networkName</code> The published name of the token pool within the multiparty network <code>string</code> <code>standard</code> The ERC standard the token pool conforms to, as reported by the token connector <code>string</code> <code>locator</code> A unique identifier for the pool, as provided by the token connector <code>string</code> <code>key</code> The signing key used to create the token pool. On input for token connectors that support on-chain deployment of new tokens (vs. only index existing ones) this determines the signing key used to create the token on-chain <code>string</code> <code>symbol</code> The token symbol. If supplied on input for an existing on-chain token, this must match the on-chain information <code>string</code> <code>decimals</code> Number of decimal places that this token has <code>int</code> <code>connector</code> The name of the token connector, as specified in the FireFly core configuration file that is responsible for the token pool. Required on input when multiple token connectors are configured <code>string</code> <code>message</code> The UUID of the broadcast message used to inform the network about this pool <code>UUID</code> <code>active</code> Indicates whether the pool has been successfully activated with the token connector <code>bool</code> <code>created</code> The creation time of the pool <code>FFTime</code> <code>config</code> Input only field, with token connector specific configuration of the pool, such as an existing Ethereum address and block number to used to index the pool. See your chosen token connector documentation for details <code>JSONObject</code> <code>info</code> Token connector specific information about the pool. See your chosen token connector documentation for details <code>JSONObject</code> <code>tx</code> Reference to the FireFly transaction used to create and broadcast this pool to the network <code>TransactionRef</code> <code>interface</code> A reference to an existing FFI, containing pre-registered type information for the token contract <code>FFIReference</code> <code>interfaceFormat</code> The interface encoding format supported by the connector for this token pool <code>FFEnum</code>:<code>\"abi\"</code><code>\"ffi\"</code> <code>methods</code> The method definitions resolved by the token connector to be used by each token operation <code>JSONAny</code> <code>published</code> Indicates if the token pool is published to other members of the multiparty network <code>bool</code>"},{"location":"reference/types/tokenpool/#transactionref","title":"TransactionRef","text":"Field Name Description Type <code>type</code> The type of the FireFly transaction <code>FFEnum</code>: <code>id</code> The UUID of the FireFly transaction <code>UUID</code>"},{"location":"reference/types/tokenpool/#ffireference","title":"FFIReference","text":"Field Name Description Type <code>id</code> The UUID of the FireFly interface <code>UUID</code> <code>name</code> The name of the FireFly interface <code>string</code> <code>version</code> The version of the FireFly interface <code>string</code>"},{"location":"reference/types/tokentransfer/","title":"TokenTransfer","text":"<p>A Token Transfer is created for each transfer of value that happens under a token pool.</p> <p>The transfers form an off-chain audit history (an \"index\") of the transactions that have been performed on the blockchain.</p> <p>This historical information cannot be queried directly from the blockchain for most token implementations, because it is inefficient to use the blockchain to store complex data structures like this. So the blockchain simply emits events when state changes, and if you want to be able to query this historical information you need to track it in your own off-chain database.</p> <p>Hyperledger FireFly maintains this index automatically for all Token Pools that are configured.</p>"},{"location":"reference/types/tokentransfer/#firefly-initiated-vs-non-firefly-initiated-transfers","title":"FireFly initiated vs. non-FireFly initiated transfers","text":"<p>There is no requirement at all to use FireFly to initiate transfers in Token Pools that Hyperledger FireFly is aware of. FireFly will listen to and update its audit history and balances for all transfers, regardless of whether they were initiated using a FireFly Supernode or not.</p> <p>So you could for example use Metamask to initiate a transfer directly against an ERC-20/ERC-721 contract directly on your blockchain, and you will see it appear as a transfer. Or initiate a transfer on-chain via another Smart Contract, such as a Hashed Timelock Contract (HTLC) releasing funds held in digital escrow.</p>"},{"location":"reference/types/tokentransfer/#message-coordinated-transfers","title":"Message coordinated transfers","text":"<p>One special feature enabled when using FireFly to initiate transfers, is to coordinate an off-chain data transfer (private or broadcast) with the on-chain transfer of value.  This is a powerful tool to allow transfers to have rich metadata associated that is too sensitive (or too large) to include on the blockchain itself.</p> <p>These transfers have a <code>message</code> associated with them, and require a compatible Token Connector and on-chain Smart Contract that allows a <code>data</code> payload to be included as part of the transfer, and to be emitted as part of the transfer event.</p> <p>Examples of how to do this are included in the ERC-20, ERC-721 and ERC-1155 Token Connector sample smart contracts.</p>"},{"location":"reference/types/tokentransfer/#transfer-types","title":"Transfer types","text":"<p>There are three primary types of transfer:</p> <ol> <li>Mint - new tokens come into existence, increasing the total supply of tokens    within the pool. The <code>from</code> address will be unset for these transfer types.</li> <li>Burn - existing tokens are taken out of circulation. The <code>to</code> address will be    unset for these transfer types.</li> <li>Transfer - tokens move from ownership by one account, to another account.    The <code>from</code> and <code>to</code> addresses are both set for these type of transfers.</li> </ol> <p>Note that the <code>key</code> that signed the Transfer transaction might be different to the <code>from</code> account that is the owner of the tokens before the transfer.</p> <p>The Approval resource is used to track which signing accounts (other than the owner) have approval to transfer tokens on the owner's behalf.</p>"},{"location":"reference/types/tokentransfer/#example","title":"Example","text":"<pre><code>{\n    \"type\": \"transfer\",\n    \"pool\": \"1244ecbe-5862-41c3-99ec-4666a18b9dd5\",\n    \"uri\": \"firefly://token/1\",\n    \"connector\": \"erc20_erc721\",\n    \"namespace\": \"ns1\",\n    \"key\": \"0x55860105D6A675dBE6e4d83F67b834377Ba677AD\",\n    \"from\": \"0x55860105D6A675dBE6e4d83F67b834377Ba677AD\",\n    \"to\": \"0x55860105D6A675dBE6e4d83F67b834377Ba677AD\",\n    \"amount\": \"1000000000000000000\",\n    \"protocolId\": \"000000000041/000000/000000\",\n    \"message\": \"780b9b90-e3b0-4510-afac-b4b1f2940b36\",\n    \"messageHash\": \"780204e634364c42779920eddc8d9fecccb33e3607eeac9f53abd1b31184ae4e\",\n    \"created\": \"2022-05-16T01:23:15Z\",\n    \"tx\": {\n        \"type\": \"token_transfer\",\n        \"id\": \"62767ca8-99f9-439c-9deb-d80c6672c158\"\n    },\n    \"blockchainEvent\": \"b57fcaa2-156e-4c3f-9b0b-ddec9ee25933\"\n}\n</code></pre>"},{"location":"reference/types/tokentransfer/#field-descriptions","title":"Field Descriptions","text":"Field Name Description Type <code>type</code> The type of transfer such as mint/burn/transfer <code>FFEnum</code>:<code>\"mint\"</code><code>\"burn\"</code><code>\"transfer\"</code> <code>localId</code> The UUID of this token transfer, in the local FireFly node <code>UUID</code> <code>pool</code> The UUID the token pool this transfer applies to <code>UUID</code> <code>tokenIndex</code> The index of the token within the pool that this transfer applies to <code>string</code> <code>uri</code> The URI of the token this transfer applies to <code>string</code> <code>connector</code> The name of the token connector, as specified in the FireFly core configuration file. Required on input when there are more than one token connectors configured <code>string</code> <code>namespace</code> The namespace for the transfer, which must match the namespace of the token pool <code>string</code> <code>key</code> The blockchain signing key for the transfer. On input defaults to the first signing key of the organization that operates the node <code>string</code> <code>from</code> The source account for the transfer. On input defaults to the value of 'key' <code>string</code> <code>to</code> The target account for the transfer. On input defaults to the value of 'key' <code>string</code> <code>amount</code> The amount for the transfer. For non-fungible tokens will always be 1. For fungible tokens, the number of decimals for the token pool should be considered when inputting the amount. For example, with 18 decimals a fractional balance of 10.234 will be specified as 10,234,000,000,000,000,000 <code>FFBigInt</code> <code>protocolId</code> An alphanumerically sortable string that represents this event uniquely with respect to the blockchain <code>string</code> <code>message</code> The UUID of a message that has been correlated with this transfer using the data field of the transfer in a compatible token connector <code>UUID</code> <code>messageHash</code> The hash of a message that has been correlated with this transfer using the data field of the transfer in a compatible token connector <code>Bytes32</code> <code>created</code> The creation time of the transfer <code>FFTime</code> <code>tx</code> If submitted via FireFly, this will reference the UUID of the FireFly transaction (if the token connector in use supports attaching data) <code>TransactionRef</code> <code>blockchainEvent</code> The UUID of the blockchain event <code>UUID</code> <code>config</code> Input only field, with token connector specific configuration of the transfer. See your chosen token connector documentation for details <code>JSONObject</code>"},{"location":"reference/types/tokentransfer/#transactionref","title":"TransactionRef","text":"Field Name Description Type <code>type</code> The type of the FireFly transaction <code>FFEnum</code>: <code>id</code> The UUID of the FireFly transaction <code>UUID</code>"},{"location":"reference/types/transaction/","title":"Transaction","text":"<p>FireFly Transactions are a grouping construct for a number of Operations and Events that need to complete or fail as unit.</p> <p>FireFly Transactions are not themselves Blockchain transactions, but in many cases there is exactly one Blockchain transaction associated with each FireFly transaction. Exceptions include <code>unpinned</code> transactions, where there is no blockchain transaction at all.</p> <p>The Blockchain native transaction ID is stored in the FireFly transaction object when it is known. However, the FireFly transaction starts before a Blockchain transaction exists - because reliably submitting the blockchain transaction is one of the operations that is performed inside of the FireFly transaction.</p> <p>The below screenshot from the FireFly Explorer nicely illustrates how multiple operations and events are associated with a FireFly transaction. In this example, the transaction tracking is pinning of a batch of messages stored in IPFS to the blockchain.</p> <p>So there is a <code>Blockchain ID</code> for the transaction - as there is just one Blockchain transaction regardless of how many messages in the batch. There are operations for the submission of that transaction, and the upload of the data to IPFS. Then a corresponding <code>Blockchain Event Received</code> event for the detection of the event from the blockchain smart contract when the transaction was mined, and a <code>Message Confirmed</code> event for each message in the batch (in this case 1). Then here the message was a special <code>Definition</code> message that advertised a new Contract API to all members of the network - so there is a <code>Contract API Confirmed</code> event as well.</p> <p></p> <p>Each FireFly transaction has a UUID. This UUID is propagated through to all participants in a FireFly transaction. For example in a Token Transfer that is coordinated with an off-chain private Message, the transaction ID is propagated to all parties who are part of that transaction. So the same UUID can be used to find the transaction in the FireFly Explorer of any member who has access to the message. This is possible because hash-pinned off-chain data is associated with that on-chain transfer.</p> <p>However, in the case of a raw ERC-20/ERC-721 transfer (without data), or any other raw Blockchain transaction, the FireFly transaction UUID cannot be propagated - so it will be local on the node that initiated the transaction.</p>"},{"location":"reference/types/transaction/#example","title":"Example","text":"<pre><code>{\n    \"id\": \"4e7e0943-4230-4f67-89b6-181adf471edc\",\n    \"namespace\": \"ns1\",\n    \"type\": \"contract_invoke\",\n    \"created\": \"2022-05-16T01:23:15Z\",\n    \"blockchainIds\": [\n        \"0x34b0327567fefed09ac7b4429549bc609302b08a9cbd8f019a078ec44447593d\"\n    ]\n}\n</code></pre>"},{"location":"reference/types/transaction/#field-descriptions","title":"Field Descriptions","text":"Field Name Description Type <code>id</code> The UUID of the FireFly transaction <code>UUID</code> <code>namespace</code> The namespace of the FireFly transaction <code>string</code> <code>type</code> The type of the FireFly transaction <code>FFEnum</code>:<code>\"none\"</code><code>\"unpinned\"</code><code>\"batch_pin\"</code><code>\"network_action\"</code><code>\"token_pool\"</code><code>\"token_transfer\"</code><code>\"contract_deploy\"</code><code>\"contract_invoke\"</code><code>\"contract_invoke_pin\"</code><code>\"token_approval\"</code><code>\"data_publish\"</code> <code>created</code> The time the transaction was created on this node. Note the transaction is individually created with the same UUID on each participant in the FireFly transaction <code>FFTime</code> <code>idempotencyKey</code> An optional unique identifier for a transaction. Cannot be duplicated within a namespace, thus allowing idempotent submission of transactions to the API <code>IdempotencyKey</code> <code>blockchainIds</code> The blockchain transaction ID, in the format specific to the blockchain involved in the transaction. Not all FireFly transactions include a blockchain. FireFly transactions are extensible to support multiple blockchain transactions <code>string[]</code>"},{"location":"reference/types/verifier/","title":"Verifier","text":"<p>A verifier is a cryptographic verification mechanism for an identity in FireFly.</p> <p>FireFly generally defers verification of these keys to the lower layers of technologies in the stack - the blockchain (Fabric, Ethereum etc.) or Data Exchange technology.</p> <p>As such the details of the public key cryptography scheme are not represented in the FireFly verifiers. Only the string identifier of the verifier that is appropriate to the technology.</p> <ul> <li>Ethereum blockchains: The Ethereum address hex string</li> <li>Hyperledger Fabric: The fully qualified MSP Identifier string</li> <li>Data exchange: The data exchange \"Peer ID\", as determined by the DX plugin</li> </ul>"},{"location":"reference/types/verifier/#example","title":"Example","text":"<pre><code>{\n    \"hash\": \"6818c41093590b862b781082d4df5d4abda6d2a4b71d737779edf6d2375d810b\",\n    \"identity\": \"114f5857-9983-46fb-b1fc-8c8f0a20846c\",\n    \"type\": \"ethereum_address\",\n    \"value\": \"0x30017fd084715e41aa6536ab777a8f3a2b11a5a1\",\n    \"created\": \"2022-05-16T01:23:15Z\"\n}\n</code></pre>"},{"location":"reference/types/verifier/#field-descriptions","title":"Field Descriptions","text":"Field Name Description Type <code>hash</code> Hash used as a globally consistent identifier for this namespace + type + value combination on every node in the network <code>Bytes32</code> <code>identity</code> The UUID of the parent identity that has claimed this verifier <code>UUID</code> <code>namespace</code> The namespace of the verifier <code>string</code> <code>type</code> The type of the verifier <code>FFEnum</code>:<code>\"ethereum_address\"</code><code>\"tezos_address\"</code><code>\"fabric_msp_id\"</code><code>\"dx_peer_id\"</code> <code>value</code> The verifier string, such as an Ethereum address, or Fabric MSP identifier <code>string</code> <code>created</code> The time this verifier was created on this node <code>FFTime</code>"},{"location":"reference/types/wsack/","title":"WSAck","text":"<p>An <code>ack</code> must be sent on a WebSocket for each event delivered to an application.</p> <p>Unless <code>autoack</code> is set in the WSStart payload/URL parameters to cause automatic acknowledgement.</p> <p>Your application should specify the <code>id</code> of each event that it acknowledges.</p> <p>If the <code>id</code> is omitted, then FireFly will assume the oldest message delivered to the application that has not been acknowledged is the one the <code>ack</code> is associated with.</p> <p>If multiple subscriptions are started on a WebSocket, then you need to specify the subscription <code>namespace</code>+<code>name</code> as part of each <code>ack</code>.</p> <p>If you send an acknowledgement that cannot be correlated, then a WSError payload will be sent to the application.</p>"},{"location":"reference/types/wsack/#example","title":"Example","text":"<pre><code>{\n    \"type\": \"ack\",\n    \"id\": \"f78bf82b-1292-4c86-8a08-e53d855f1a64\",\n    \"subscription\": {\n        \"namespace\": \"ns1\",\n        \"name\": \"app1_subscription\"\n    }\n}\n</code></pre>"},{"location":"reference/types/wsack/#field-descriptions","title":"Field Descriptions","text":"Field Name Description Type <code>type</code> WSActionBase.type <code>FFEnum</code>:<code>\"start\"</code><code>\"ack\"</code><code>\"protocol_error\"</code><code>\"event_batch\"</code> <code>id</code> WSAck.id <code>UUID</code> <code>subscription</code> WSAck.subscription <code>SubscriptionRef</code>"},{"location":"reference/types/wsack/#subscriptionref","title":"SubscriptionRef","text":"Field Name Description Type <code>id</code> The UUID of the subscription <code>UUID</code> <code>namespace</code> The namespace of the subscription. A subscription will only receive events generated in the namespace of the subscription <code>string</code> <code>name</code> The name of the subscription. The application specifies this name when it connects, in order to attach to the subscription and receive events that arrived while it was disconnected. If multiple apps connect to the same subscription, events are workload balanced across the connected application instances <code>string</code>"},{"location":"reference/types/wserror/","title":"WSError","text":""},{"location":"reference/types/wserror/#example","title":"Example","text":"<pre><code>{\n    \"type\": \"protocol_error\",\n    \"error\": \"FF10175: Acknowledgment does not match an inflight event + subscription\"\n}\n</code></pre>"},{"location":"reference/types/wserror/#field-descriptions","title":"Field Descriptions","text":"Field Name Description Type <code>type</code> WSAck.type <code>FFEnum</code>:<code>\"start\"</code><code>\"ack\"</code><code>\"protocol_error\"</code><code>\"event_batch\"</code> <code>error</code> WSAck.error <code>string</code>"},{"location":"reference/types/wsstart/","title":"WSStart","text":"<p>The <code>start</code> payload is sent after an application connects to a WebSocket, to start delivery of events over that connection.</p> <p>The start command can refer to a subscription by name in order to reliably receive all matching events for that subscription, including those that were emitted when the application was disconnected.</p> <p>Alternatively the start command can request <code>\"ephemeral\": true</code> in order to dynamically create a new subscription that lasts only for the duration that the connection is active.</p>"},{"location":"reference/types/wsstart/#example","title":"Example","text":"<pre><code>{\n    \"type\": \"start\",\n    \"autoack\": false,\n    \"namespace\": \"ns1\",\n    \"name\": \"app1_subscription\",\n    \"ephemeral\": false,\n    \"filter\": {\n        \"message\": {},\n        \"transaction\": {},\n        \"blockchainevent\": {}\n    },\n    \"options\": {}\n}\n</code></pre>"},{"location":"reference/types/wsstart/#field-descriptions","title":"Field Descriptions","text":"Field Name Description Type <code>type</code> WSActionBase.type <code>FFEnum</code>:<code>\"start\"</code><code>\"ack\"</code><code>\"protocol_error\"</code><code>\"event_batch\"</code> <code>autoack</code> WSStart.autoack <code>bool</code> <code>namespace</code> WSStart.namespace <code>string</code> <code>name</code> WSStart.name <code>string</code> <code>ephemeral</code> WSStart.ephemeral <code>bool</code> <code>filter</code> WSStart.filter <code>SubscriptionFilter</code> <code>options</code> WSStart.options <code>SubscriptionOptions</code>"},{"location":"reference/types/wsstart/#subscriptionfilter","title":"SubscriptionFilter","text":"Field Name Description Type <code>events</code> Regular expression to apply to the event type, to subscribe to a subset of event types <code>string</code> <code>message</code> Filters specific to message events. If an event is not a message event, these filters are ignored <code>MessageFilter</code> <code>transaction</code> Filters specific to events with a transaction. If an event is not associated with a transaction, this filter is ignored <code>TransactionFilter</code> <code>blockchainevent</code> Filters specific to blockchain events. If an event is not a blockchain event, these filters are ignored <code>BlockchainEventFilter</code> <code>topic</code> Regular expression to apply to the topic of the event, to subscribe to a subset of topics. Note for messages sent with multiple topics, a separate event is emitted for each topic <code>string</code> <code>topics</code> Deprecated: Please use 'topic' instead <code>string</code> <code>tag</code> Deprecated: Please use 'message.tag' instead <code>string</code> <code>group</code> Deprecated: Please use 'message.group' instead <code>string</code> <code>author</code> Deprecated: Please use 'message.author' instead <code>string</code>"},{"location":"reference/types/wsstart/#messagefilter","title":"MessageFilter","text":"Field Name Description Type <code>tag</code> Regular expression to apply to the message 'header.tag' field <code>string</code> <code>group</code> Regular expression to apply to the message 'header.group' field <code>string</code> <code>author</code> Regular expression to apply to the message 'header.author' field <code>string</code>"},{"location":"reference/types/wsstart/#transactionfilter","title":"TransactionFilter","text":"Field Name Description Type <code>type</code> Regular expression to apply to the transaction 'type' field <code>string</code>"},{"location":"reference/types/wsstart/#blockchaineventfilter","title":"BlockchainEventFilter","text":"Field Name Description Type <code>name</code> Regular expression to apply to the blockchain event 'name' field, which is the name of the event in the underlying blockchain smart contract <code>string</code> <code>listener</code> Regular expression to apply to the blockchain event 'listener' field, which is the UUID of the event listener. So you can restrict your subscription to certain blockchain listeners. Alternatively to avoid your application need to know listener UUIDs you can set the 'topic' field of blockchain event listeners, and use a topic filter on your subscriptions <code>string</code>"},{"location":"reference/types/wsstart/#subscriptionoptions","title":"SubscriptionOptions","text":"Field Name Description Type <code>firstEvent</code> Whether your application would like to receive events from the 'oldest' event emitted by your FireFly node (from the beginning of time), or the 'newest' event (from now), or a specific event sequence. Default is 'newest' <code>SubOptsFirstEvent</code> <code>readAhead</code> The number of events to stream ahead to your application, while waiting for confirmation of consumption of those events. At least once delivery semantics are used in FireFly, so if your application crashes/reconnects this is the maximum number of events you would expect to be redelivered after it restarts <code>uint16</code> <code>withData</code> Whether message events delivered over the subscription, should be packaged with the full data of those messages in-line as part of the event JSON payload. Or if the application should make separate REST calls to download that data. May not be supported on some transports. <code>bool</code> <code>batch</code> Events are delivered in batches in an ordered array. The batch size is capped to the readAhead limit. The event payload is always an array even if there is a single event in the batch, allowing client-side optimizations when processing the events in a group. Available for both Webhooks and WebSockets. <code>bool</code> <code>batchTimeout</code> When batching is enabled, the optional timeout to send events even when the batch hasn't filled. <code>string</code> <code>fastack</code> Webhooks only: When true the event will be acknowledged before the webhook is invoked, allowing parallel invocations <code>bool</code> <code>url</code> Webhooks only: HTTP url to invoke. Can be relative if a base URL is set in the webhook plugin config <code>string</code> <code>method</code> Webhooks only: HTTP method to invoke. Default=POST <code>string</code> <code>json</code> Webhooks only: Whether to assume the response body is JSON, regardless of the returned Content-Type <code>bool</code> <code>reply</code> Webhooks only: Whether to automatically send a reply event, using the body returned by the webhook <code>bool</code> <code>replytag</code> Webhooks only: The tag to set on the reply message <code>string</code> <code>replytx</code> Webhooks only: The transaction type to set on the reply message <code>string</code> <code>headers</code> Webhooks only: Static headers to set on the webhook request `` <code>query</code> Webhooks only: Static query params to set on the webhook request `` <code>tlsConfigName</code> The name of an existing TLS configuration associated to the namespace to use <code>string</code> <code>input</code> Webhooks only: A set of options to extract data from the first JSON input data in the incoming message. Only applies if withData=true <code>WebhookInputOptions</code> <code>retry</code> Webhooks only: a set of options for retrying the webhook call <code>WebhookRetryOptions</code> <code>httpOptions</code> Webhooks only: a set of options for HTTP <code>WebhookHTTPOptions</code>"},{"location":"reference/types/wsstart/#webhookinputoptions","title":"WebhookInputOptions","text":"Field Name Description Type <code>query</code> A top-level property of the first data input, to use for query parameters <code>string</code> <code>headers</code> A top-level property of the first data input, to use for headers <code>string</code> <code>body</code> A top-level property of the first data input, to use for the request body. Default is the whole first body <code>string</code> <code>path</code> A top-level property of the first data input, to use for a path to append with escaping to the webhook path <code>string</code> <code>replytx</code> A top-level property of the first data input, to use to dynamically set whether to pin the response (so the requester can choose) <code>string</code>"},{"location":"reference/types/wsstart/#webhookretryoptions","title":"WebhookRetryOptions","text":"Field Name Description Type <code>enabled</code> Enables retry on HTTP calls, defaults to false <code>bool</code> <code>count</code> Number of times to retry the webhook call in case of failure <code>int</code> <code>initialDelay</code> Initial delay between retries when we retry the webhook call <code>string</code> <code>maxDelay</code> Max delay between retries when we retry the webhookcall <code>string</code>"},{"location":"reference/types/wsstart/#webhookhttpoptions","title":"WebhookHTTPOptions","text":"Field Name Description Type <code>proxyURL</code> HTTP proxy URL to use for outbound requests to the webhook <code>string</code> <code>tlsHandshakeTimeout</code> The max duration to hold a TLS handshake alive <code>string</code> <code>requestTimeout</code> The max duration to hold a TLS handshake alive <code>string</code> <code>maxIdleConns</code> The max number of idle connections to hold pooled <code>int</code> <code>idleTimeout</code> The max duration to hold a HTTP keepalive connection between calls <code>string</code> <code>connectionTimeout</code> The maximum amount of time that a connection is allowed to remain with no data transmitted. <code>string</code> <code>expectContinueTimeout</code> See ExpectContinueTimeout in the Go docs <code>string</code>"},{"location":"releasenotes/","title":"Release Notes","text":"<p>Full release notes</p>"},{"location":"releasenotes/#v132-sept-13-2024","title":"v1.3.2 - Sept 13, 2024","text":"<p>What's New:</p> <ul> <li>Support for JSON numbers larger than <code>2^53-1</code>     See FFBigInt </li> <li>Ability to install FireFly CLI with Brew for MacOS users     See Brew </li> <li>Miscellaneous bug fixes and minor improvements</li> <li>FireFly has been upgraded to use Go 1.22</li> </ul>"},{"location":"releasenotes/#v131-aug-5-2024","title":"v1.3.1 - Aug 5, 2024","text":"<p>What's New:</p> <ul> <li>Enable contract listeners with multiple filters     See Contract Listeners for details</li> <li>New multiparty status API at <code>/status/multiparty</code></li> </ul>"},{"location":"releasenotes/#v130-april-25-2024","title":"v1.3.0 - April 25, 2024","text":"<p>Migration guide</p> <p>What's New:</p> <ul> <li>Enhancements to FireFly Messaging capabilities, allowing off-chain data to be linked to on-chain transactions from custom smart contracts</li> <li>Sample contract implementation for custom pin contracts</li> <li>Contract interfaces, contract APIs, and token pools can now be separately defined and published</li> <li>Support for batching events when delivering over websockets</li> <li>Lots of bug fixes and miscellaneous enhancements</li> </ul>"},{"location":"releasenotes/#v120-february-6-2023","title":"v1.2.0 - February 6, 2023","text":"<p>Migration guide</p> <p>What's New:</p> <ul> <li>Enhanced support for token contracts generated by the OpenZeppelin Wizard</li> <li>Custom smart contract error types are now returned on the API</li> <li>Data objects and associated blobs can now be deleted</li> <li>Optional dynamic reload of core configuration file</li> <li>The <code>X-FireFly-Request-ID</code> HTTP header is now passed through to FireFly dependency microservices</li> <li>Custom HTTP headers can be passed through to FireFly dependency microservices</li> <li>Evmconnect is now the default blockchain connector for Ethereum based FireFly stacks</li> </ul>"},{"location":"releasenotes/#release-notes","title":"Release Notes","text":"<p>Full release notes</p>"},{"location":"releasenotes/#v110-september-12-2022","title":"v1.1.0 - September 12, 2022","text":"<p>Migration guide</p> <p>What's New:</p> <ul> <li>Gateway Mode: Connect to many chains with auto-indexing of activities</li> <li>Public EVM Chain Support: Manage public chain connections including Ethereum, Polygon, Arbitrum, Binance Smart Chain, Moonbeam, and more.</li> <li>Namespaces: Isolated environments within a FireFly runtime allowing independent configuration of plugin and infrastructure components and more</li> <li>Connector Toolkit: Quickly build custom connectors</li> <li>Pluggable API Security: Plug in your own API security</li> <li>Mass Scale Tokens: Support many parallel copies of token plugins for mass scale</li> </ul>"},{"location":"releasenotes/#v103-july-07-2022","title":"v1.0.3 - July 07, 2022","text":"<p>What's New:</p> <ul> <li>Adds support for custom URIs for non-fungible tokens and documentation updates</li> <li>Deprecate default value for \"ffdx\"</li> <li>Back port of custom URI support for non-fungible tokens</li> <li>Update token connector versions</li> <li>Back port of \"FAQ and FireFly Tutorial updates\"</li> </ul>"},{"location":"releasenotes/#v102-may-12-2022","title":"v1.0.2 - May 12, 2022","text":"<p>What's New:</p> <ul> <li>Fix invocations on custom Fabric chaincode, which were not properly reporting success/failure status back to FireFly (along with other minor bugfixes).</li> <li>De-duplicate existing token approvals in database migration</li> <li>Backport docs generation and versioning code for 1.0 stream</li> <li>Default fabconnect calls to async</li> <li>Set message header type of broadcast/private</li> </ul>"},{"location":"releasenotes/#v101-may-09-2022","title":"v1.0.1 - May 09, 2022","text":"<p>What's New:</p> <ul> <li>Fixes for token approvals - previously approvals would intermittently be missed by FireFly or recorded with incorrect details.</li> <li>New versions of ERC20/ERC721 connector will assume \"no data\" support if you create a token pool against an older version of the sample smart contracts.</li> </ul>"},{"location":"releasenotes/#v100-april-28-2022","title":"v1.0.0 - April 28, 2022","text":"<p>This release includes lots of major hardening, performance improvements, and bug fixes, as well as more complete documentation and OpenAPI specifications.</p> <p>What's New:</p> <ul> <li>Massive performance improvements across the board</li> <li>Up-to-date documentation and fully annotated OpenAPI specification</li> <li>Overhaul of UI</li> <li>Cleaner logs and error messages</li> <li>Lots of bug fixes and miscellaneous enhancements</li> </ul>"},{"location":"releasenotes/#v0140-march-22-2022","title":"v0.14.0 - March 22, 2022","text":"<p>What's New:</p> <ul> <li>Major UI updates including Activity, Blockchain, Off-Chain, Tokens, Network Map, and My Node sections</li> <li>Custom contract APIs</li> <li>Enhanced subscription filters</li> <li>Event API enrichment</li> <li>Performance updates</li> <li>Bug fixes</li> </ul>"},{"location":"releasenotes/#v0130-february-14-2022","title":"v0.13.0 - February 14, 2022","text":"<p>What's New:</p> <ul> <li>Hardening release with significant rework to core of FireFly, mostly to fix issues exposed by the performance testing.</li> <li>Support for running on ARM-based M1 processors</li> <li>Rewrite of the message batching and event aggregation logic inside FireFly, to fix numerous edge cases with lost or hung messages</li> <li>Hardening of operations and transactions to behave more consistently across all types</li> <li>Metrics reporting to Prometheus</li> <li>Continued development to support custom on-chain logic (still in preview)</li> </ul>"},{"location":"releasenotes/#v0120-february-02-2022","title":"v0.12.0 - February 02, 2022","text":"<p>What's New:</p> <ul> <li>All APIs deprecated in v0.11.0 or earlier are removed</li> <li>Preview of custom on-chain logic</li> <li>Support for new ERC20 / ERC721 connector</li> <li>Overhaul of Transaction type and new BlockchainEvent type</li> <li>Support for delivery confirmations via DX plugin</li> </ul>"},{"location":"releasenotes/#v0110-november-22-2021","title":"v0.11.0 - November 22, 2021","text":"<p>What's New:</p> <ul> <li>Significant hardening and enhanced token functionality</li> <li>Major web UI overhaul</li> <li>Optimized database operations for increased transactional throughput</li> <li>Fixed PostgreSQL database migrations</li> </ul>"},{"location":"releasenotes/1.1_migration_guide/","title":"v1.1.0 Migration Guide","text":""},{"location":"releasenotes/1.1_migration_guide/#overview","title":"Overview","text":"<p>Hyperledger FireFly v1.1.0 is a feature release that includes significant new functionality around namespaces and plugins, as detailed in FIR-12. As a result, upgrading an existing FireFly environment from any prior release may require special steps (depending on the functionality used).</p> <p>If seamless data preservation is not required, you can simply create a new network from scratch using FireFly v1.1.0.</p> <p>If you want to preserve data from an existing 1.0.x network, significant care has been taken to ensure that it is possible. Most existing environments can be upgraded with minimal extra steps. This document attempts to call out all potentially breaking changes (both common and uncommon), so that you can easily assess the impact of the upgrade and any needed preparation before proceeding.</p>"},{"location":"releasenotes/1.1_migration_guide/#before-upgrading","title":"Before Upgrading","text":"<p>These steps are all safe to do while running FireFly v1.0.x. While they do not have to be done prior to upgrading, performing them ahead of time may allow you to preemptively fix some problems and ease the migration to v1.1.0.</p>"},{"location":"releasenotes/1.1_migration_guide/#common-steps","title":"Common Steps","text":"<p>Upgrade to latest v1.0.x patch release</p> <p>Before upgrading to v1.1.0, it is strongly recommended to upgrade to the latest v1.0.x patch release (v1.0.4 as of the writing this document). Do not proceed any further in this guide until all nodes are successfully running the latest patch release version.</p> <p>Fix any deprecated config usage</p> <p>All items in FireFly's YAML config that were deprecated at any time in the v1.0.x line will be unsupported in v1.1.0. After upgrading to the latest v1.0.x patch release, you should therefore look for any deprecation warnings when starting FireFly, and ensure they are fixed before upgrading to v1.1.0. Failure to do so will cause your config file to be rejected in v1.1.0, and FireFly will fail to start.</p> <p>You can utilize the ffconfig tool to automatically check and fix deprecated config with a command such as:</p> <pre><code>ffconfig migrate -f &lt;input-file&gt; -o &lt;output-file&gt; --to 1.0.4\n</code></pre> <p>This should ensure your config file is acceptable to 1.0.x or 1.1.x.</p> <p>Note that if you are attempting to migrate a Dockerized development environment (such as one stood up by the firefly-cli), you may need to edit the config file inside the Docker. Environments created by a v1.0.x CLI do not expose the config file outside the Docker container.</p>"},{"location":"releasenotes/1.1_migration_guide/#less-common-situations","title":"Less Common Situations","text":"<p>Record all broadcast namespaces in the config file</p> Expand for migration details only if your application uses non-default namespaces.  FireFly v1.0 allowed for the dynamic creation of new namespaces by broadcasting a namespace definition to all nodes. This functionality is _removed_ in v1.1.0. If your network relies on any namespaces that were created via a broadcast, you must add those namespaces to the `namespaces.predefined` list in your YAML config prior to upgrade. If you do not, they will cease to function after upgrading to v1.1.0 (all events on those namespaces will be ignored by your node).   <p>Identify queries for organization/node identities</p> Expand for migration details only if your application queries <code>/network/organizations</code> or <code>/network/nodes</code>.  Applications that query `/network/organizations` or `/network/nodes` will temporarily receive _empty result lists_ after upgrading to v1.1.0, just until all identities have been re-registered (see steps in \"After Upgrading\"). This is because organization and node identities were broadcast on a global \"ff_system\" namespace in v1.0, but are no longer global in v1.1.0.  The simplest solution is to shut down applications until the FireFly upgrade is complete on all nodes and all identities have been re-broadcast.  If this poses a problem and you require zero downtime from these APIs, you can proactively mitigate with the following steps in your application code:  - Applications that query the `/network/organizations` may be altered to _also_ query `/namespaces/ff_system/network/organizations` and combine the results (but should disregard the second query if it fails). - Applications that query the `/network/nodes` may be altered to _also_ query `/namespaces/ff_system/network/nodes` and combine the results (but should disregard the second query if it fails).  Further details on the changes to `/network` APIs are provided in the next section.   <p>Identify usage of changed APIs</p> Expand for migration details on all changes to <code>/namespaces</code>, <code>/status</code>, and <code>/network</code> APIs.  The primary API change in this version is that the \"global\" paths beginning with `/network` and `/status` have been relocated under the `/namespaces/{ns}` prefix, as this data is now specific to a namespace instead of being global. At the same time, the API server has been enhanced so that omitting a namespace from an API path will _query the default namespace_ instead. That is, querying `/messages` is now the same as querying `/namespaces/default/messages` (assuming your default namespace is named \"default\"). This has the effect that most of the moved APIs will continue to function without requiring changes. See below for details on the affected paths.  These global routes have been moved under `/namespaces/{ns}`. Continuing to use them without the namespace prefix **will still work**, and will simply query the default namespace.  <pre><code>/network/diddocs/{did}\n/network/nodes\n/network/nodes/{nameOrId}\n/network/nodes/self\n/network/organizations\n/network/organizations/{nameOrId}\n/network/organizations/self\n/status\n/status/batchmanager\n</code></pre>  These global routes have been moved under `/namespaces/{ns}` and have also been deprecated in favor of a new route name. Continuing to use them without the namespace prefix **will still work**, and will simply query the default namespace. However, it is recommended to switch to the new API spelling when possible.  <pre><code>/network/identities - replaced by existing /namespaces/{ns}/identities\n/network/identities/{did} - replaced by new /namespaces/{ns}/identities/{did}\n</code></pre>  These global routes have been have been permanently renamed. They are deemed less likely to be used by client applications, but any usage **will be broken** by this release and must be changed after upgrading.  <pre><code>/status/pins - moved to /namespaces/{ns}/pins (or /pins to query the default namespace)\n/status/websockets - moved to /websockets\n</code></pre>  The response bodies of the following APIs have also had fields removed. Any usage of the removed fields **will be broken** by this release and must be changed after upgrading.  <pre><code>/namespaces - removed all fields except \"name\", \"description\", \"created\"\n/namespaces/{ns} - same as above\n/namespaces/{ns}/status - removed \"defaults\"\n</code></pre> <p>Adjust or remove usage of admin APIs</p> Expand for migration details on all changes to <code>/admin</code> and <code>/spi</code>.  FireFly provides an administrative API in addition to the normal API. In v1.1.0, this has been renamed to SPI (Service Provider Interface). Consequently, all of the routes have moved from `/admin` to `/spi`, and the config section has been renamed from `admin` to `spi`. There is no automatic migration provided, so any usage of the old routes will need to be changed, and your config file will need to be adjusted if you wish to keep the SPI enabled (although it is perfectly fine to have both `admin` and `spi` sections if needed for migration).  The ability to set FireFly config via these routes has also been removed. Any usage of the `/admin/config` routes must be discontinued, and config should be set exclusively by editing the FireFly config file. The only route retained from this functionality was `/admin/config/reset`, which has been renamed to `/spi/reset` - this will continue to be available for performing a soft reset that reloads FireFly's config."},{"location":"releasenotes/1.1_migration_guide/#performing-the-upgrade","title":"Performing the Upgrade","text":"<p>Backup current data</p> <p>Before beginning the upgrade, it is recommended to take a full backup of your FireFly database(s). If you encounter any serious issues after the upgrade, you should revert to the old binary and restore your database snapshot. While down-migrations are provided to revert a database in place, they are not guaranteed to work in all scenarios.</p> <p>Upgrade FireFly and all dependencies</p> <p>Bring FireFly down and replace it with the new v1.1.0 binary. You should also replace other runtimes (such as blockchain, data exchange, and token connectors) with the supported versions noted in the v1.1.0 release. Once all binaries have been replaced, start them up again.</p>"},{"location":"releasenotes/1.1_migration_guide/#after-upgrading","title":"After Upgrading","text":"<p>Ensure nodes start without errors</p> <p>Ensure that FireFly starts without errors. There will likely be new deprecation warnings for config that was deprecated in v1.1.0, but these are safe to ignore for the moment. If you face any errors or crashes, please report the logs to the FireFly channel on Discord, and return your nodes to running the previous version of FireFly if necessary.</p> <p>Re-broadcast organization and node identities</p> <p>Once all nodes in the multiparty network have been upgraded and are running without errors, each node should re-broadcast its org and node identity by invoking <code>/network/organizations/self</code> and <code>/network/nodes/self</code> (or, if your application uses a non-default namespace, by invoking the <code>/namespace/{ns}</code>-prefixed versions of these APIs).</p> <p>This will ensure that queries to <code>/network/organizations</code> and <code>/network/nodes</code> return the expected results, and will register the identities in a way that can be supported by both V1 and V2 multiparty contracts (see \"Upgrading the Multi-Party Contract\").</p> <p>Update config file to latest format</p> <p>Once the network is stable, you should update your config file(s) again to remove deprecated configuration and set yourself up to take advantage of all the new configuration options available in v1.1.0.</p> <p>You can utilize the ffconfig tool to automatically check and fix deprecated config with a command such as:</p> <pre><code>ffconfig migrate -f &lt;input-file&gt; -o &lt;output-file&gt;\n</code></pre>"},{"location":"releasenotes/1.1_migration_guide/#upgrading-the-multi-party-contract","title":"Upgrading the Multi-Party Contract","text":"<p>FireFly v1.1.0 includes a new recommended version of the contract used for multi-party systems (for both Ethereum and Fabric). It also introduces a versioning method for this contract, and a path for migrating networks from one contract address to a new one.</p> <p>After upgrading FireFly itself, it is recommended to upgrade your multi-party system to the latest contract version by following these steps.</p> <ol> <li>Compile and deploy an instance of the new FireFly contract (linked above) to your blockchain, using <code>ff deploy</code> or a similar method.</li> <li>Edit the config file on each node in your network, to add the new contract to the multi-party contract list like so:</li> </ol> <pre><code>namespaces:\n  predefined:\n  - name: default\n    multiparty:\n      enabled: true\n      contract:\n      - location:\n          address: 0x09f107d670b2e69a700a4d9ef1687490ae1568db\n      - location:\n          address: 0x1bee32b37dc48e99c6b6bf037982eb3bee0e816b\n</code></pre> <p>This example assumes <code>0x09f1...</code> represents the address of the original contract, and <code>0x1bee...</code> represents the new one. Note that if you have multiple namespaces, you must repeat this step for each namespace in the config - and you must deploy a unique contract instance per namespace (in the new network rules, multiple namespaces cannot share a single contract).</p> <ol> <li>After updating each node's configuration, restart the node and ensure it starts without issues.</li> <li>Have any member of the multi-party network invoke the <code>/namespaces/{ns}/network/action</code> FireFly API with a body of <code>{\"type\": \"terminate\"}</code>. This will terminate the old contract and instruct all members to move simultaneously to the newly configured one.</li> <li>Verify success by querying <code>/namespaces/{ns}/status</code> on each node and checking that the active multi-party contract matches the new address.</li> </ol>"},{"location":"releasenotes/1.2_migration_guide/","title":"v1.2.0 Migration Guide","text":""},{"location":"releasenotes/1.2_migration_guide/#overview","title":"Overview","text":"<p>Hyperledger FireFly v1.2.0 is a feature release that includes new features for tokens and data management as well as enhancements for debugging FireFly apps and operating FireFly nodes.</p> <p>For the most part, upgrading from v1.1.x to v.1.2.0 should be a seamless experience, but there are several important things to note about changes between the two versions, which are described in detail on this page.</p>"},{"location":"releasenotes/1.2_migration_guide/#tokens-considerations","title":"Tokens considerations","text":"<p>There are quite a few new features around tokens in FireFly v1.2.0. Most notably, FireFly's token APIs now work with a much wider variety of ERC-20, ERC-721, and ERC-1155 contracts, supporting variations of these contracts generated by the OpenZepplin Contract Wizard.</p>"},{"location":"releasenotes/1.2_migration_guide/#sample-token-contract-deprecations","title":"Sample token contract deprecations","text":"<p>In FireFly v1.2.0 two of the old, lesser used sample token contracts have been deprecated. The <code>ERC20NoData</code> and <code>ERC721NoData</code> contracts have been updated and the previous versions are no longer supported, unless you set the <code>USE_LEGACY_ERC20_SAMPLE=true</code> or <code>USE_LEGACY_ERC721_SAMPLE=true</code> environment variables for your token connector.</p> <p>For more details you can read the description of the pull requests (#104 and #109) where these changes were made.</p>"},{"location":"releasenotes/1.2_migration_guide/#differences-from-v110","title":"Differences from v1.1.0","text":""},{"location":"releasenotes/1.2_migration_guide/#optional-fields","title":"Optional fields","text":"<p>Some token connectors support some optional fields when using them with certain contracts. For example, the ERC-721 token connector supports a URI field. If these optional fields are specified in an API call to a token connector and contract that does not support that field, an error will be returned, rather than the field being silently ignored.</p>"},{"location":"releasenotes/1.2_migration_guide/#auto-incrementing-token-index","title":"Auto incrementing token index","text":"<p>In FireFly v1.2.0 the default ERC-721 and ERC-1155 contracts have changed to automatically increment the token index when a token is minted. This is useful when many tokens may be minted around the same time, or by different minters. This lets the blockchain handle the ordering, and keeping track of the state of which token index should be minted next, rather than making that an application concern.</p> <p>NOTE: These new contracts will only be used for brand new FireFly stacks with v1.2.0. If you have an existing stack, the new token contracts will not be used, unless you specifically deploy them and start using them.</p>"},{"location":"releasenotes/1.2_migration_guide/#data-management-considerations","title":"Data management considerations","text":"<p>FireFly v1.2.0 introduces the ability to delete data records and their associated blobs, if present. This will remove the data and blob rows from the FireFly database, as well as removing the blob from the Data Exchange microservice. This can be very useful if your organization has data retention requirements for sensitive, private data and needs to purge data after a certain period of time.</p> <p>Please note that this API only removes data from the FireFly node on which it is called. If data has been shared with other participants of a multi-party network, it is each participants' responsibility to satisfy their own data retention policies.</p>"},{"location":"releasenotes/1.2_migration_guide/#differences-from-v110_1","title":"Differences from v1.1.0","text":"<p>It is important to note that FireFly now stores a separate copy of a blob for a given payload, even if the same data object is sent in different messages, by different network participants. Previously, in FireFly v1.1.0 the blob was de-duplicated in some cases. In FireFly v1.2.0, deleting the data object will result in each copy of the associated payload being removed.</p> <p>NOTE: If data has been published to IPFS, it cannot be deleted completely. You can still call the <code>DELETE</code> method on it, and it will be removed from FireFly's database and Data Exchange, but the payload will still persist in IPFS.</p>"},{"location":"releasenotes/1.2_migration_guide/#application-considerations","title":"Application considerations","text":""},{"location":"releasenotes/1.2_migration_guide/#optional-tokens-fields","title":"Optional tokens fields","text":"<p>Please see the optional token fields section above for details. If your application code is calling any token API endpoints with optional fields that are not supported by your token connector or contract, you will need to remove those fields from your API request or it will fail.</p>"},{"location":"releasenotes/1.2_migration_guide/#transaction-output-details","title":"Transaction output details","text":"<p>In previous versions of FireFly, transaction output details used to appear under the <code>output</code> object in the response body. Behind the scenes, some of this data is now fetched from the blockchain connector asynchronously. If your application needs the detailed output, it should now add a <code>fetchStatus=true</code> query parameter when querying for an Operation. Additionally the details have moved from the <code>output</code> field to a new <code>detail</code> field on the response body. For more details, please refer to the PRs where this change was made (#1111 and #1151). For a detailed example comparing what an Operation response body looks like in FireFly v1.2.0 compared with v1.1.x, you can expand the sections below.</p> v1.2.0 Operation response body with `fetchStatus=true` <pre>\n{\n  \"id\": \"2b0ec132-2abd-40f0-aa56-79871a7a23b9\",\n  \"namespace\": \"default\",\n  \"tx\": \"cb0e6de1-50a9-44f2-a2ff-411f6dcc19c9\",\n  \"type\": \"blockchain_invoke\",\n  \"status\": \"Succeeded\",\n  \"plugin\": \"ethereum\",\n  \"input\": {\n    \"idempotencyKey\": \"5a634941-29cb-4a4b-b5a7-196331723d6d\",\n    \"input\": {\n      \"newValue\": 42\n    },\n    \"interface\": \"46189886-cae5-42ff-bf09-25d4f58d649e\",\n    \"key\": \"0x2ecd8d5d97fb4bb7af0fbc27d7b89fd6f0366350\",\n    \"location\": {\n      \"address\": \"0x9d7ea8561d4b21cba495d1bd29a6d3421c31cf8f\"\n    },\n    \"method\": {\n      \"description\": \"\",\n      \"id\": \"d1d2a0cf-19ea-42c3-89b8-cb65850fb9c5\",\n      \"interface\": \"46189886-cae5-42ff-bf09-25d4f58d649e\",\n      \"name\": \"set\",\n      \"namespace\": \"default\",\n      \"params\": [\n        {\n          \"name\": \"newValue\",\n          \"schema\": {\n            \"details\": {\n              \"type\": \"uint256\"\n            },\n            \"type\": \"integer\"\n          }\n        }\n      ],\n      \"pathname\": \"set\",\n      \"returns\": []\n    },\n    \"methodPath\": \"set\",\n    \"options\": null,\n    \"type\": \"invoke\"\n  },\n  \"output\": {\n    \"Headers\": {\n      \"requestId\": \"default:2b0ec132-2abd-40f0-aa56-79871a7a23b9\",\n      \"type\": \"TransactionSuccess\"\n    },\n    \"protocolId\": \"000000000052/000000\",\n    \"transactionHash\": \"0x9adae77a46bf869ee97aab38bb5d789fa2496209500801e87bf9e2cce945dc71\"\n  },\n  \"created\": \"2023-01-24T14:08:17.371587084Z\",\n  \"updated\": \"2023-01-24T14:08:17.385558417Z\",\n  \"detail\": {\n    \"created\": \"2023-01-24T14:08:17.378147625Z\",\n    \"firstSubmit\": \"2023-01-24T14:08:17.381787042Z\",\n    \"gas\": \"42264\",\n    \"gasPrice\": 0,\n    \"history\": [\n      {\n        \"count\": 1,\n        \"info\": \"Success=true,Receipt=000000000052/000000,Confirmations=0,Hash=0x9adae77a46bf869ee97aab38bb5d789fa2496209500801e87bf9e2cce945dc71\",\n        \"lastOccurrence\": null,\n        \"time\": \"2023-01-24T14:08:17.384371042Z\"\n      },\n      {\n        \"count\": 1,\n        \"info\": \"Submitted=true,Receipt=,Hash=0x9adae77a46bf869ee97aab38bb5d789fa2496209500801e87bf9e2cce945dc71\",\n        \"lastOccurrence\": null,\n        \"time\": \"2023-01-24T14:08:17.381908959Z\"\n      }\n    ],\n    \"id\": \"default:2b0ec132-2abd-40f0-aa56-79871a7a23b9\",\n    \"lastSubmit\": \"2023-01-24T14:08:17.381787042Z\",\n    \"nonce\": \"34\",\n    \"policyInfo\": null,\n    \"receipt\": {\n      \"blockHash\": \"0x7a2ca7cc57fe1eb4ead3e60d3030b123667d18eb67f4b390fb0f51f970f1fba0\",\n      \"blockNumber\": \"52\",\n      \"extraInfo\": {\n        \"contractAddress\": null,\n        \"cumulativeGasUsed\": \"28176\",\n        \"from\": \"0x2ecd8d5d97fb4bb7af0fbc27d7b89fd6f0366350\",\n        \"gasUsed\": \"28176\",\n        \"status\": \"1\",\n        \"to\": \"0x9d7ea8561d4b21cba495d1bd29a6d3421c31cf8f\"\n      },\n      \"protocolId\": \"000000000052/000000\",\n      \"success\": true,\n      \"transactionIndex\": \"0\"\n    },\n    \"sequenceId\": \"0185e41b-ade2-67e4-c104-5ff553135320\",\n    \"status\": \"Succeeded\",\n    \"transactionData\": \"0x60fe47b1000000000000000000000000000000000000000000000000000000000000002a\",\n    \"transactionHash\": \"0x9adae77a46bf869ee97aab38bb5d789fa2496209500801e87bf9e2cce945dc71\",\n    \"transactionHeaders\": {\n      \"from\": \"0x2ecd8d5d97fb4bb7af0fbc27d7b89fd6f0366350\",\n      \"to\": \"0x9d7ea8561d4b21cba495d1bd29a6d3421c31cf8f\"\n    },\n    \"updated\": \"2023-01-24T14:08:17.384371042Z\"\n  }\n}\n</pre> v1.1.x Operation response body <pre>\n{\n  \"id\": \"4a1a19cf-7fd2-43f1-8fae-1e3d5774cf0d\",\n  \"namespace\": \"default\",\n  \"tx\": \"2978a248-f5df-4c78-bf04-711ab9c79f3d\",\n  \"type\": \"blockchain_invoke\",\n  \"status\": \"Succeeded\",\n  \"plugin\": \"ethereum\",\n  \"input\": {\n    \"idempotencyKey\": \"5dc2ee8a-be5c-4e60-995f-9e21818a441d\",\n    \"input\": {\n      \"newValue\": 42\n    },\n    \"interface\": \"752af5a3-d383-4952-88a9-b32b837ed1cb\",\n    \"key\": \"0xd8a27cb390fd4f446acce01eb282c7808ec52572\",\n    \"location\": {\n      \"address\": \"0x7c0a598252183999754c53d97659af9436293b82\"\n    },\n    \"method\": {\n      \"description\": \"\",\n      \"id\": \"1739f25d-ab48-4534-b278-58c4cf151bf9\",\n      \"interface\": \"752af5a3-d383-4952-88a9-b32b837ed1cb\",\n      \"name\": \"set\",\n      \"namespace\": \"default\",\n      \"params\": [\n        {\n          \"name\": \"newValue\",\n          \"schema\": {\n            \"details\": {\n              \"type\": \"uint256\"\n            },\n            \"type\": \"integer\"\n          }\n        }\n      ],\n      \"pathname\": \"set\",\n      \"returns\": []\n    },\n    \"methodPath\": \"set\",\n    \"options\": null,\n    \"type\": \"invoke\"\n  },\n  \"output\": {\n    \"_id\": \"default:4a1a19cf-7fd2-43f1-8fae-1e3d5774cf0d\",\n    \"blockHash\": \"0x13660667b69f48646025a87db603abdeeaa88036e9a1252b1af4ec1fc3e1d850\",\n    \"blockNumber\": \"52\",\n    \"cumulativeGasUsed\": \"28176\",\n    \"from\": \"0xd8a27cb390fd4f446acce01eb282c7808ec52572\",\n    \"gasUsed\": \"28176\",\n    \"headers\": {\n      \"id\": \"8dfaabd1-4493-4a64-52dd-762497022ba2\",\n      \"requestId\": \"default:4a1a19cf-7fd2-43f1-8fae-1e3d5774cf0d\",\n      \"requestOffset\": \"\",\n      \"timeElapsed\": 0.109499833,\n      \"timeReceived\": \"2023-01-24T17:16:52.372449013Z\",\n      \"type\": \"TransactionSuccess\"\n    },\n    \"nonce\": \"0\",\n    \"receivedAt\": 1674580612482,\n    \"status\": \"1\",\n    \"to\": \"0x7c0a598252183999754c53d97659af9436293b82\",\n    \"transactionHash\": \"0x522e5aac000f5befba61ddfd707aaf5c61314f47e00cd0c5b779f69dd14bd899\",\n    \"transactionIndex\": \"0\"\n  },\n  \"created\": \"2023-01-24T17:16:52.368498346Z\",\n  \"updated\": \"2023-01-24T17:16:52.48408293Z\"\n}\n</pre>"},{"location":"releasenotes/1.2_migration_guide/#local-development-considerations","title":"Local development considerations","text":"<p>It is also worth noting that the default Ethereum blockchain connector in the FireFly CLI is now Evmconnect. Ethconnect is still fully supported, but FireFly v1.2.0 marks a point of maturity in the project where it is now the recommended choice for any Ethereum based FireFly stack.</p>"},{"location":"releasenotes/1.3_migration_guide/","title":"v1.3.0 Migration Guide","text":""},{"location":"releasenotes/1.3_migration_guide/#overview","title":"Overview","text":"<p>Hyperledger FireFly v1.3.0 is a feature release that includes changes around event streaming, contract listeners, define/publish APIs as well as a range of general fixes.</p> <p>For the most part, upgrading from v1.2.x to v1.3.0 should be a seamless experience, but there are several important things to note about changes between the two versions, which are described in detail on this page.</p>"},{"location":"releasenotes/1.3_migration_guide/#docker-image-file-permission-considerations","title":"Docker image file permission considerations","text":"<p>Following security best practices, the official published Docker images for FireFly Core and all of its microservices now run as a non-root user by default. If you are running a FireFly release prior to v1.3.0, depending on how you were running your containers, you may need to adjust file permissions inside volumes that these containers write to. If you have overridden the default user for your containers (for example though a Kubernetes deployment) you may safely ignore this section.</p> <p>\u26a0\ufe0f Warning: If you have been using the default root user and upgrade to FireFly v1.3.0 without changing these file permissions your services may fail to start.</p> <p>The new default user is <code>1001</code>. If you are not overriding the user for your container, this user or group needs to have write permissions in several places. The list of services and directories you should specifically check are:</p> <ul> <li>firefly-evmconnect</li> <li><code>persistence.leveldb.path</code> directory set in the config file</li> <li>firefly-ethconnect</li> <li><code>rest.rest-gateway.openapi.storagePath</code> directory in the config file</li> <li><code>rest.rest-gateway.openapi.eventsDB</code> directory in the config file</li> <li>firefly-fabconnect</li> <li><code>receipts.leveldb.path</code> directory in the config file</li> <li><code>events.leveldb.path</code> directory in the config file</li> <li>firefly-dataexchange-https</li> <li>Data directory set by the <code>DATA_DIRECTORY</code> environment variable (default <code>/data</code>)</li> </ul>"},{"location":"releasenotes/1.3_migration_guide/#api-definitionpublication-considerations","title":"API definition/publication considerations","text":"<p>As of FireFly v1.3.0 in multi-party namespaces, by default, contract interfaces, contracts APIs, and token pools have distinct steps in their creation flow and by default they are unpublished.</p> <p>These following described changes impact contract interfaces, contract APIs, and token pools.</p> <p>Previously, when creating one of the affected resources in a multi-party network, if successful, the resource would be automatically broadcasted to other namespaces. In FireFly v1.3.0, this behaviour has changed, now when one of the resources is created there are 2 distinct states for the resource, published and unpublished. The default state for a resource (provided FireFly is not told otherwise) after creation is unpublished.</p> <p>When a resource is unpublished it is not broadcasted to other namespaces in the multi-party network, and it is not pinned to the blockchain. In this state, it is possible to call the <code>DELETE</code> APIs to remove the resource (such as in the case where configuration needs to be changed) and reclaim the name that has been provided to it, so that it can be recreated.</p> <p>When a resource is published it is broadcasted to other namespaces in the multi-party network, and it is pinned to the blockchain. In this state, it is no longer possible to call the <code>DELETE</code> APIs to remove the resource.</p> <p>In FireFly v1.2.0 to create one of the affected resources and publish it to other parties, a <code>POST</code> call would be made to its respective API route and the broadcast would happen immediately. To achieve the same behaviour in FireFly v1.3.0, there are 2 options for all impacted resources, either providing a query parameter at creation to signal immediate publish, or a subsequent API call to publish the resources.</p>"},{"location":"releasenotes/1.3_migration_guide/#contract-interfaces","title":"Contract interfaces","text":"<p>Previously, to create a contract interface a <code>POST</code> call would be made to <code>/contracts/interfaces</code> and the interface would be broadcasted to all other namepsaces. In FireFly v1.3.0, this same call can be made with the <code>publish=true</code> query parameter, or a subsequent API call can be made on an unpublished interface on <code>POST /contracts/interfaces/{name}/{version}/publish</code> specifying the name and version of the interface.</p> <p>For an exact view of the changes to contract interfaces, see PR #1279.</p>"},{"location":"releasenotes/1.3_migration_guide/#contract-apis","title":"Contract APIs","text":"<p>Previously, to create a contract API a <code>POST</code> call would be made to <code>/apis</code> and the API would be broadcasted to all other namepsaces. In FireFly v1.3.0, this same call can be made with the <code>publish=true</code> query parameter, or a subsequent API call can be made on an unpublished API on <code>/apis/{apiName}/publish</code> specifying the name of the API.</p> <p>For an exact view of the changes to contract APIs, see PR #1322.</p>"},{"location":"releasenotes/1.3_migration_guide/#token-pools","title":"Token pools","text":"<p>Previously, to create a token pool a <code>POST</code> call would be made to <code>/tokens/pools</code> and the token pool would be broadcasted to all other namepsaces. In FireFly v1.3.0, this same call can be made with the <code>publish=true</code> query parameter, or a subsequent API call can be made on an unpublished token pool on <code>/tokens/pools/{nameOrId}/publish</code> specifying the name or ID of the token pool.</p> <p>For an exact view of the changes to token pools, see PR #1261.</p>"},{"location":"releasenotes/1.3_migration_guide/#event-stream-considerations","title":"Event stream considerations","text":""},{"location":"releasenotes/1.3_migration_guide/#single-event-stream-per-namespace","title":"Single event stream per namespace","text":"<p>In this release, the model for event streams in a multi-party network has fundamentally changed. Previously, there was a single event stream for each blockchain plugin, even if this plugin served multiple namespaces. In FireFly v1.3.0 there is now a single event stream per namespace in the network.</p> <p>When migrating from FireFly v1.2.X to v1.3.0, due to these changes, existing event streams will be rebuilt. This means that connectors will replay past events to FireFly, but FireFly will automatically de-duplicate them by design so this is a safe operation.</p> <p>The migration to individual event streams promotes high-availability capability but is not itself a breaking change, however the ID format for event streams has changed. Event streams now follow the format <code>&lt;plugin_topic_name&gt;/&lt;namespace_name&gt;</code>. For example, an event stream for the default namespace with a plugin topic of 0 would now be: <code>0/default</code>.</p> <p>Summarily, these changes should not impact end-users of FireFly, but they're noted here as they are significant architectural changes to the relationships between namespaces, plugins, and connectors.</p> <p>For an exact view of the changes, see PR #1388.</p>"},{"location":"releasenotes/1.3_migration_guide/#configuration-considerations","title":"Configuration considerations","text":""},{"location":"releasenotes/1.3_migration_guide/#deprecated-configuration","title":"Deprecated configuration","text":"<p>In FireFly v1.3.0 deprecated configuration options for the <code>blockchain</code>, <code>database</code>, <code>dataexchange</code>, <code>sharedstorage</code> and <code>tokens</code> plugins have been removed, and can no longer be provided.</p> <p>For an exact view of the changes, see PR #1289.</p>"},{"location":"releasenotes/1.3_migration_guide/#token-pool-considerations","title":"Token pool considerations","text":""},{"location":"releasenotes/1.3_migration_guide/#activity-indicator-changes","title":"Activity indicator changes","text":"<p>Token pools have a status, when creating a token pool previously, it would go into a pending state immediately following creation, and then into a confirmed state when it has been confirmed on the chain. This behaviour is still consistent in FireFly v1.3.0, but the representation of the data has changed.</p> <p>Previously, token pools had a <code>state</code> field with an enumerated value which was either <code>pending</code>, or <code>confirmed</code>, this has been replaced with an <code>active</code> boolean field, where <code>true</code> indicates the token pool has been committed onto chain, and <code>false</code> indicated the transaction has not yet been confirmed.</p> <p>For an exact view of the changes, see PR #1305.</p>"},{"location":"releasenotes/1.3_migration_guide/#fabconnect-event-considerations","title":"FabConnect event considerations","text":""},{"location":"releasenotes/1.3_migration_guide/#fabconnect-protocol-id-format-changes","title":"FabConnect Protocol ID format changes","text":"<p>Prior to FireFly v1.3.0, when the FabConnect client indexed events submitted by the Fabric SDK, FireFly would deduplicate events into a single event because the protocol ID of the events compiled into a single block would evaluate to be the same. In this release, we have changed the format of the calculated protocol ID so that is unique across events even if they are located within the same block. Crucially, the new format includes the transaction hash, so events are no longer alphanumerically sortable.</p> <p>For an exact view of the changes, see PR #1345.</p>"},{"location":"releasenotes/1.3_migration_guide/#local-development-considerations","title":"Local development considerations","text":""},{"location":"releasenotes/1.3_migration_guide/#go-version-upgrade","title":"Go version upgrade","text":"<p>FireFly v1.3.0 now uses Go 1.21 across all modules.</p>"},{"location":"swagger/","title":"API Spec","text":"<p>This is the FireFly OpenAPI Specification document generated by FireFly</p> <p>Note: The 'Try it out' buttons will not work on this page because it's not running against a live version of FireFly. To actually try it out, we recommend using the FireFly CLI to start an instance on your local machine (which will start the FireFly core on port 5000 by default) and then open the Swagger UI associated with your local node by opening a new tab and visiting http://localhost:5000/api</p> <p></p>"},{"location":"tutorials/basic_auth/","title":"Basic Auth","text":""},{"location":"tutorials/basic_auth/#quick-reference","title":"Quick reference","text":"<p>FireFly has a pluggable auth system which can be enabled at two different layers of the stack. At the top, auth can be enabled at the HTTP listener level. This will protect all requests to the given listener. FireFly has three different HTTP listeners, which could each use a different auth scheme:</p> <ol> <li>The main API</li> <li>The SPI (for internal or admin use)</li> <li>The metrics API.</li> </ol> <p>Auth can also be enabled at the namespace level within FireFly as well. This enables several different use cases. For example, you might have two different teams that want to use the same FireFly node, each with different sets of authorized users. You could configure them to use separate namespaces and create separate auth schemes on each.</p> <p>FireFly has a basic auth plugin built in, which we will be configuring in this tutorial.</p> <p>NOTE: This guide assumes that you have already gone through the Getting Started Guide and have set up and run a stack at least once.</p>"},{"location":"tutorials/basic_auth/#additional-info","title":"Additional info","text":"<ul> <li>Config Reference: HTTP Auth</li> <li>Auth plugin interface</li> <li>Basic auth plugin implementation</li> </ul>"},{"location":"tutorials/basic_auth/#create-a-password-file","title":"Create a password file","text":"<p>FireFly's built in basic auth plugin uses a password hash file to store the list of authorized users. FireFly uses the bcrypt algorithm to compare passwords against the stored hash. You can use <code>htpasswd</code> on a command line to generate a hash file.</p>"},{"location":"tutorials/basic_auth/#create-the-test_users-password-hash-file","title":"Create the <code>test_users</code> password hash file","text":"<pre><code>touch test_users\n</code></pre>"},{"location":"tutorials/basic_auth/#create-a-user-named-firefly","title":"Create a user named <code>firefly</code>","text":"<pre><code>htpasswd -B test_users firefly\n</code></pre> <p>You will be prompted to type the password for the new user twice. Optional: You can continue to add new users by running this command with a different username.</p> <pre><code>htpasswd -B test_users &lt;username&gt;\n</code></pre>"},{"location":"tutorials/basic_auth/#enable-basic-auth-at-the-namespace-level","title":"Enable basic auth at the Namespace level","text":"<p>To enable auth at the HTTP listener level we will need to edit the FireFly core config file. You can find the config file for the first node in your stack at the following path:</p> <pre><code>~/.firefly/stacks/&lt;stack_name&gt;/runtime/config/firefly_core_0.yml\n</code></pre> <p>Open the config file in your favorite editor and add the <code>auth</code> section to the <code>plugins</code> list:</p> <pre><code>plugins:\n  auth:\n  - name: test_user_auth\n    type: basic\n    basic:\n      passwordfile: /etc/firefly/test_users\n</code></pre> <p>You will also need to add <code>test_user_auth</code> to the list of plugins used by the <code>default</code> namespace:</p> <pre><code>namespaces:\n  predefined:\n  - plugins:\n    - database0\n    - blockchain0\n    - dataexchange0\n    - sharedstorage0\n    - erc20_erc721\n    - test_user_auth\n</code></pre>"},{"location":"tutorials/basic_auth/#mount-the-password-hash-file-in-the-docker-container","title":"Mount the password hash file in the Docker container","text":"<p>If you set up your FireFly stack using the FireFly CLI we will need to mount the password hash file in the Docker container, so that FireFly can actually read the file. This can be done by editing the <code>docker-compose.override.yml</code> file at:</p> <pre><code>~/.firefly/stacks/&lt;stack_name&gt;/docker-compose.override.yml\n</code></pre> <p>Edit the file to look like this, replacing the path to your <code>test_users</code> file:</p> <pre><code># Add custom config overrides here\n# See https://docs.docker.com/compose/extends\nversion: \"2.1\"\nservices:\n  firefly_core_0:\n    volumes:\n      - PATH_TO_YOUR_TEST_USERS_FILE:/etc/firefly/test_users\n</code></pre>"},{"location":"tutorials/basic_auth/#restart-your-firefly-core-container","title":"Restart your FireFly Core container","text":"<p>To restart your FireFly stack and have Docker pick up the new volume, run:</p> <pre><code>ff stop &lt;stack_name&gt;\nff start &lt;stack_name&gt;\n</code></pre> <p>NOTE: The FireFly basic auth plugin reads this file at startup and will not read it again during runtime. If you add any users or change passwords, restarting the node will be necessary to use an updated file.</p>"},{"location":"tutorials/basic_auth/#test-basic-auth","title":"Test basic auth","text":"<p>After FireFly starts back up, you should be able to test that auth is working correctly by making an unauthenticated request to the API:</p> <pre><code>curl http://localhost:5000/api/v1/status\n{\"error\":\"FF00169: Unauthorized\"}\n</code></pre> <p>However, if we add the username and password that we created above, the request should still work:</p> <pre><code>curl -u \"firefly:firefly\" http://localhost:5000/api/v1/status\n{\"namespace\":{\"name\":\"default\",\"networkName\":\"default\",\"description\":\"Default predefined namespace\",\"created\":\"2022-10-18T16:35:57.603205507Z\"},\"node\":{\"name\":\"node_0\",\"registered\":false},\"org\":{\"name\":\"org_0\",\"registered\":false},\"plugins\":{\"blockchain\":[{\"name\":\"blockchain0\",\"pluginType\":\"ethereum\"}],\"database\":[{\"name\":\"database0\",\"pluginType\":\"sqlite3\"}],\"dataExchange\":[{\"name\":\"dataexchange0\",\"pluginType\":\"ffdx\"}],\"events\":[{\"pluginType\":\"websockets\"},{\"pluginType\":\"webhooks\"},{\"pluginType\":\"system\"}],\"identity\":[],\"sharedStorage\":[{\"name\":\"sharedstorage0\",\"pluginType\":\"ipfs\"}],\"tokens\":[{\"name\":\"erc20_erc721\",\"pluginType\":\"fftokens\"}]},\"multiparty\":{\"enabled\":true,\"contract\":{\"active\":{\"index\":0,\"location\":{\"address\":\"0xa750e2647e24828f4fec2e6e6d61fc08ccca5efa\"},\"info\":{\"subscription\":\"sb-d0642f14-f89a-41bb-6fd4-ae74b9501b6c\",\"version\":2}}}}}\n</code></pre>"},{"location":"tutorials/basic_auth/#enable-auth-at-the-http-listener-level","title":"Enable auth at the HTTP listener level","text":"<p>You may also want to enable auth at the HTTP listener level, for instance on the SPI (Service Provider Interface) to limit administrative actions. To enable auth at the HTTP listener level we will need to edit the FireFly core config file. You can find the config file for the first node in your stack at the following path:</p> <pre><code>~/.firefly/stacks/&lt;stack_name&gt;/runtime/config/firefly_core_0.yml\n</code></pre> <p>Open the config file in your favorite editor and change the <code>spi</code> section to look like the following:</p> <pre><code>spi:\n  address: 0.0.0.0\n  enabled: true\n  port: 5101\n  publicURL: http://127.0.0.1:5101\n  auth:\n    type: basic\n    basic:\n      passwordfile: /etc/firefly/test_users\n</code></pre>"},{"location":"tutorials/basic_auth/#restart-firefly-to-apply-the-changes","title":"Restart FireFly to apply the changes","text":"<p>NOTE You will need to mount the password hash file following the instructions above if you have not already.</p> <p>You can run the following to restart your stack:</p> <pre><code>ff stop &lt;stack_name&gt;\nff start &lt;stack_name&gt;\n</code></pre>"},{"location":"tutorials/basic_auth/#test-basic-auth_1","title":"Test basic auth","text":"<p>After FireFly starts back up, you should be able to query the SPI and the request should be unauthorized.</p> <pre><code>curl http://127.0.0.1:5101/spi/v1/namespaces\n{\"error\":\"FF00169: Unauthorized\"}\n</code></pre> <p>Adding the username and password that we set earlier, should make the request succeed.</p> <pre><code>curl -u \"firefly:firefly\" http://127.0.0.1:5101/spi/v1/namespaces\n[{\"name\":\"default\",\"networkName\":\"default\",\"description\":\"Default predefined namespace\",\"created\":\"2022-10-18T16:35:57.603205507Z\"}]\n</code></pre>"},{"location":"tutorials/broadcast_data/","title":"Broadcast data","text":""},{"location":"tutorials/broadcast_data/#quick-reference","title":"Quick reference","text":"<ul> <li>Sends a <code>message</code> visible to all parties in the network</li> <li>The message describes who sent it, and exactly what data was sent</li> <li>A <code>message</code> has one or more attached pieces of business <code>data</code></li> <li>Can be sent in-line, uploaded in advanced, or received from other parties</li> <li>Can include smaller JSON payloads suitable for database storage<ul> <li>These can be verified against a <code>datatype</code></li> </ul> </li> <li>Can include references to large (multi megabyte/gigabyte) Blob data</li> <li>Sequenced via the blockchain</li> <li>The blockchain does not contain any data, just a hash pin</li> <li>Batched for efficiency</li> <li>One <code>batch</code> can pin hundreds of <code>message</code> broadcasts</li> <li>The whole batch is written to the shared storage</li> </ul>"},{"location":"tutorials/broadcast_data/#additional-info","title":"Additional info","text":"<ul> <li>Key Concepts: Broadcast / shared data</li> <li>Swagger Reference: POST /api/v1/namespaces/{ns}/messages/broadcast</li> </ul>"},{"location":"tutorials/broadcast_data/#example-1-inline-string-data","title":"Example 1: Inline string data","text":"<p><code>POST</code> <code>/api/v1/namespaces/default/messages/broadcast</code></p> <pre><code>{\n  \"data\": [\n    {\n      \"value\": \"a string\"\n    }\n  ]\n}\n</code></pre>"},{"location":"tutorials/broadcast_data/#example-message-response","title":"Example message response","text":"<pre><code>{\n  \"header\": {\n    \"id\": \"607e22ad-04fa-434a-a073-54f528ca14fb\", // uniquely identifies this broadcast message\n    \"type\": \"broadcast\", // set automatically\n    \"txtype\": \"batch_pin\", // message will be batched, and sequenced via the blockchain\n    \"author\": \"0x0a65365587a65ce44938eab5a765fe8bc6532bdf\", // set automatically in this example to the node org\n    \"created\": \"2021-07-01T18:06:24.5817016Z\", // set automatically\n    \"namespace\": \"default\", // the 'default' namespace was set in the URL\n    \"topics\": [\n      \"default\" // the default topic that the message is published on, if no topic is set\n    ],\n    // datahash is calculated from the data array below\n    \"datahash\": \"5a7bbc074441fa3231d9c8fc942d68ef9b9b646dd234bb48c57826dc723b26fd\"\n  },\n  \"hash\": \"81acf8c8f7982dbc49258535561461601cbe769752fecec0f8ce0358664979e6\", // hash of the header\n  \"state\": \"ready\", // this message is stored locally but not yet confirmed\n  \"data\": [\n    // one item of data was stored\n    {\n      \"id\": \"8d8635e2-7c90-4963-99cc-794c98a68b1d\", // can be used to query the data in the future\n      \"hash\": \"c95d6352f524a770a787c16509237baf7eb59967699fb9a6d825270e7ec0eacf\" // sha256 hash of `\"a string\"`\n    }\n  ]\n}\n</code></pre>"},{"location":"tutorials/broadcast_data/#example-2-inline-object-data-to-a-topic-no-datatype-verification","title":"Example 2: Inline object data to a topic (no datatype verification)","text":"<p>It is very good practice to set a <code>tag</code> and <code>topic</code> in each of your messages:</p> <ul> <li><code>tag</code> should tell the apps receiving the broadcast (including the local app), what   to do when it receives the message. Its the reason for the broadcast - an   application specific type for the message.</li> <li><code>topic</code> should be something like a well known identifier that relates to the   information you are publishing. It is used as an ordering context, so all   broadcasts on a given topic are assured to be processed in order.</li> </ul> <p><code>POST</code> <code>/api/v1/namespaces/default/messages/broadcast</code></p> <pre><code>{\n  \"header\": {\n    \"tag\": \"new_widget_created\",\n    \"topics\": [\"widget_id_12345\"]\n  },\n  \"data\": [\n    {\n      \"value\": {\n        \"id\": \"widget_id_12345\",\n        \"name\": \"superwidget\"\n      }\n    }\n  ]\n}\n</code></pre>"},{"location":"tutorials/broadcast_data/#notes-on-why-setting-a-topic-is-important","title":"Notes on why setting a topic is important","text":"<p>The FireFly aggregator uses the <code>topic</code> (obfuscated on chain) to determine if a message is the next message in an in-flight sequence for any groups the node is involved in. If it is, then that message must receive all off-chain private data and be confirmed before any subsequent messages can be confirmed on the same sequence.</p> <p>So if you use the same topic in every message, then a single failed send on one topic blocks delivery of all messages between those parties, until the missing data arrives.</p> <p>Instead it is best practice to set the topic on your messages to a value that identifies an ordered stream of business processing. Some examples:</p> <ul> <li>A long-running business process instance identifier assigned at initiation</li> <li>A real-world business transaction identifier used off-chain</li> <li>The agreed identifier of an asset you are attaching a stream of evidence to</li> <li>An NFT identifier that is assigned to an asset (digital twin scenarios)</li> <li>An agreed primary key for a data resource being reconciled between multiple parties</li> </ul> <p>The <code>topic</code> field is an array, because there are cases (such as merging two identifiers) where you need a message to be deterministically ordered across multiple sequences. However, this is an advanced use case and you are likely to set a single topic on the vast majority of your messages.</p>"},{"location":"tutorials/broadcast_data/#example-3-upload-a-blob-with-metadata-and-broadcast","title":"Example 3: Upload a blob with metadata and broadcast","text":"<p>Here we make two API calls.</p> <ol> <li> <p>Create the <code>data</code> object explicitly, using a multi-part form upload</p> </li> <li> <p>You can also just post JSON to this endpoint</p> </li> <li> <p>Broadcast a message referring to that data</p> </li> <li> <p>The Blob attachment gets published to shared storage</p> </li> <li>This happens the first time a broadcast happens on a data attachment</li> <li>A pin goes to the blockchain</li> <li>The metadata goes into a batch with the message</li> </ol>"},{"location":"tutorials/broadcast_data/#multipart-form-post-of-a-file","title":"Multipart form post of a file","text":"<p>Example curl command (Linux/Mac) to grab an image from the internet, and pipe it into a multi-part form post to FireFly.</p> <p>Note we use <code>autometa</code> to cause FireFly to automatically add the <code>filename</code>, and <code>size</code>, to the JSON part of the <code>data</code> object for us.</p> <pre><code>curl -sLo - https://github.com/hyperledger/firefly/raw/main/docs/firefly_logo.png \\\n | curl --form autometa=true --form file=@- \\\n   http://localhost:5000/api/v1/namespaces/default/data\n</code></pre>"},{"location":"tutorials/broadcast_data/#example-data-response-from-blob-upload","title":"Example data response from Blob upload","text":"<p>Status: <code>200 OK</code> - your data is uploaded to your local FireFly node</p> <p>At this point the data has not be shared with anyone else in the network</p> <pre><code>{\n  // A uniquely generated ID, we can refer to when sending this data to other parties\n  \"id\": \"97eb750f-0d0b-4c1d-9e37-1e92d1a22bb8\",\n  \"validator\": \"json\", // the \"value\" part is JSON\n  \"namespace\": \"default\", // from the URL\n  // The hash is a combination of the hash of the \"value\" metadata, and the\n  // hash of the blob\n  \"hash\": \"997af6a9a19f06cc8a46872617b8bf974b106f744b2e407e94cc6959aa8cf0b8\",\n  \"created\": \"2021-07-01T20:20:35.5462306Z\",\n  \"value\": {\n    \"filename\": \"-\", // dash is how curl represents the filename for stdin\n    \"size\": 31185 // the size of the blob data\n  },\n  \"blob\": {\n    // A hash reference to the blob\n    \"hash\": \"86e6b39b04b605dd1b03f70932976775962509d29ae1ad2628e684faabe48136\"\n    // Note at this point there is no public reference. The only place\n    // this data has been uploaded to is our own private data exchange.\n    // It's ready to be published to everyone (broadcast), or privately\n    // transferred (send) to other parties in the network. But that hasn't\n    // happened yet.\n  }\n}\n</code></pre>"},{"location":"tutorials/broadcast_data/#broadcast-the-uploaded-data","title":"Broadcast the uploaded data","text":"<p>Just include a reference to the <code>id</code> returned from the upload.</p> <p><code>POST</code> <code>/api/v1/namespaces/default/messages/broadcast</code></p> <pre><code>{\n  \"data\": [\n    {\n      \"id\": \"97eb750f-0d0b-4c1d-9e37-1e92d1a22bb8\"\n    }\n  ]\n}\n</code></pre>"},{"location":"tutorials/broadcast_data/#broadcasting-messages-using-the-sandbox","title":"Broadcasting Messages using the Sandbox","text":"<p>All of the functionality discussed above can be done through the FireFly Sandbox.</p> <p>To get started, open up the Web UI and Sanbox UI for at least one of your members. The URLs for these were printed in your terminal when you started your FireFly stack.</p> <p>In the sandbox, enter your message into the message field as seen in the screenshot below.</p> <p></p> <p>Notice how the <code>data</code> field in the center panel updates in real time.</p> <p>Click the blue <code>Run</code> button. This should return a <code>202</code> response immediately in the Server Response section and will populate the right hand panel with transaction information after a few seconds.</p> <p></p> <p>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</p> <p></p>"},{"location":"tutorials/create_custom_identity/","title":"Create a Custom Identity","text":""},{"location":"tutorials/create_custom_identity/#quick-reference","title":"Quick reference","text":"<p>Out of the box, a FireFly Supernode contains both an <code>org</code> and a <code>node</code> identity. Your use case might demand more granular notions of identity (ex. customers, clients, etc.). Instead of creating a Supernode for each identity, you can create multiple custom identities within a FireFly Supernode.</p>"},{"location":"tutorials/create_custom_identity/#additional-info","title":"Additional info","text":"<ul> <li>Reference: Identities</li> <li>Swagger: POST /api/v1/identities</li> </ul>"},{"location":"tutorials/create_custom_identity/#previous-steps-start-your-environment","title":"Previous steps: Start your environment","text":"<p>If you haven't started a FireFly stack already, please go to the Getting Started guide on how to Start your environment</p> <p>\u2190 \u2461 Start your environment</p>"},{"location":"tutorials/create_custom_identity/#step-1-create-a-new-account","title":"Step 1: Create a new account","text":"<p>The FireFly CLI has a helpful command to create an account in a local development environment for you.</p> <p>NOTE: In a production environment, key management actions such as creation, encryption, unlocking, etc. may be very different, depending on what type of blockchain node and signer your specific deployment is using.</p> <p>To create a new account on your local stack, run:</p> <pre><code>ff accounts create &lt;stack_name&gt;\n</code></pre> <pre><code>{\n  \"address\": \"0xc00109e112e21165c7065da776c75cfbc9cdc5e7\",\n  \"privateKey\": \"...\"\n}\n</code></pre> <p>The FireFly CLI has created a new private key and address for us to be able to use, and it has loaded the encrypted private key into the signing container. However, we haven't told FireFly itself about the new key, or who it belongs to. That's what we'll do in the next steps.</p>"},{"location":"tutorials/create_custom_identity/#step-2-query-the-parent-org-for-its-uuid","title":"Step 2: Query the parent org for its UUID","text":"<p>If we want to create a new custom identity under the organizational identity that we're using in a multiparty network, first we will need to look up the UUID for our org identity. We can look that up by making a <code>GET</code> request to the status endpoint on the default namespace.</p>"},{"location":"tutorials/create_custom_identity/#request","title":"Request","text":"<p><code>GET</code> <code>http://localhost:5000/api/v1/status</code></p>"},{"location":"tutorials/create_custom_identity/#response","title":"Response","text":"<pre><code>{\n    \"namespace\": {...},\n    \"node\": {...},\n    \"org\": {\n        \"name\": \"org_0\",\n        \"registered\": true,\n        \"did\": \"did:firefly:org/org_0\",\n        \"id\": \"1c0abf75-0f3a-40e4-a8cd-5ff926f80aa8\", // We need this in Step 3\n        \"verifiers\": [\n            {\n                \"type\": \"ethereum_address\",\n                \"value\": \"0xd7320c76a2efc1909196dea876c4c7dabe49c0f4\"\n            }\n        ]\n    },\n    \"plugins\": {...},\n    \"multiparty\": {...}\n}\n</code></pre>"},{"location":"tutorials/create_custom_identity/#step-3-register-the-new-custom-identity-with-firefly","title":"Step 3: Register the new custom identity with FireFly","text":"<p>Now we can <code>POST</code> to the identities endpoint to create a new custom identity. We will include the UUID of the organizational identity from the previous step in the <code>\"parent\"</code> field in the request.</p>"},{"location":"tutorials/create_custom_identity/#request_1","title":"Request","text":"<p><code>POST</code> <code>http://localhost:5000/api/v1/identities</code></p> <pre><code>{\n    \"name\": \"myCustomIdentity\",\n    \"key\": \"0xc00109e112e21165c7065da776c75cfbc9cdc5e7\", // Signing Key from Step 1\n    \"parent\": \"1c0abf75-0f3a-40e4-a8cd-5ff926f80aa8\" // Org UUID from Step 2\n}\n</code></pre>"},{"location":"tutorials/create_custom_identity/#response_1","title":"Response","text":"<pre><code>{\n    \"id\": \"5ea8f770-e004-48b5-af60-01994230ed05\",\n    \"did\": \"did:firefly:myCustomIdentity\",\n    \"type\": \"custom\",\n    \"parent\": \"1c0abf75-0f3a-40e4-a8cd-5ff926f80aa8\",\n    \"namespace\": \"\",\n    \"name\": \"myCustomIdentity\",\n    \"messages\": {\n        \"claim\": \"817b7c79-a934-4936-bbb1-7dcc7c76c1f4\",\n        \"verification\": \"ae55f998-49b1-4391-bed2-fa5e86dc85a2\",\n        \"update\": null\n    }\n}\n</code></pre>"},{"location":"tutorials/create_custom_identity/#step-4-query-the-new-custom-identity","title":"Step 4: Query the New Custom Identity","text":"<p>Lastly, if we want to confirm that the new identity has been created, we can query the identities endpoint to see our new custom identity.</p>"},{"location":"tutorials/create_custom_identity/#request_2","title":"Request","text":"<p><code>GET</code> <code>http://localhost:5000/api/v1/identities?fetchverifiers=true</code></p> <p>NOTE: Using <code>fetchverifiers=true</code> will return the cryptographic verification mechanism for the FireFly identity.</p>"},{"location":"tutorials/create_custom_identity/#response_2","title":"Response","text":"<pre><code>[\n    {\n        \"id\": \"5ea8f770-e004-48b5-af60-01994230ed05\",\n        \"did\": \"did:firefly:myCustomIdentity\",\n        \"type\": \"custom\",\n        \"parent\": \"1c0abf75-0f3a-40e4-a8cd-5ff926f80aa8\",\n        \"namespace\": \"default\",\n        \"name\": \"myCustomIdentity\",\n        \"messages\": {\n            \"claim\": \"817b7c79-a934-4936-bbb1-7dcc7c76c1f4\",\n            \"verification\": \"ae55f998-49b1-4391-bed2-fa5e86dc85a2\",\n            \"update\": null\n        },\n        \"created\": \"2022-09-19T18:10:47.365068013Z\",\n        \"updated\": \"2022-09-19T18:10:47.365068013Z\",\n        \"verifiers\": [\n            {\n                \"type\": \"ethereum_address\",\n                \"value\": \"0xfe1ea8c8a065a0cda424e2351707c7e8eb4d2b6f\"\n            }\n        ]\n    },\n    { ... },\n    { ... }\n]\n</code></pre>"},{"location":"tutorials/define_datatype/","title":"Define a datatype","text":""},{"location":"tutorials/define_datatype/#quick-reference","title":"Quick reference","text":"<p>As your use case matures, it is important to agree formal datatypes between the parties. These canonical datatypes need to be defined and versioned, so that each member can extract and transform data from their internal systems into this datatype.</p> <p>Datatypes are broadcast to the network so everybody refers to the same JSON schema when validating their data. The broadcast must complete before a datatype can be used by an application to upload/broadcast/send data. The same system of broadcast within FireFly is used to broadcast definitions of datatypes, as is used to broadcast the data itself.</p>"},{"location":"tutorials/define_datatype/#additional-info","title":"Additional info","text":"<ul> <li>Key Concepts: Broadcast / shared data</li> <li>Swagger: POST /api/v1/namespaces/{ns}/datatypes</li> </ul>"},{"location":"tutorials/define_datatype/#example-1-broadcast-new-datatype","title":"Example 1: Broadcast new datatype","text":"<p><code>POST</code> <code>/api/v1/namespaces/{ns}/datatypes</code></p> <pre><code>{\n  \"name\": \"widget\",\n  \"version\": \"0.0.2\",\n  \"value\": {\n    \"$id\": \"https://example.com/widget.schema.json\",\n    \"$schema\": \"https://json-schema.org/draft/2020-12/schema\",\n    \"title\": \"Widget\",\n    \"type\": \"object\",\n    \"properties\": {\n      \"id\": {\n        \"type\": \"string\",\n        \"description\": \"The unique identifier for the widget.\"\n      },\n      \"name\": {\n        \"type\": \"string\",\n        \"description\": \"The person's last name.\"\n      }\n    }\n  }\n}\n</code></pre>"},{"location":"tutorials/define_datatype/#example-message-response","title":"Example message response","text":"<p>Status: <code>202 Accepted</code> - a broadcast message has been sent, and on confirmation the new datatype will be created (unless it conflicts with another definition with the same <code>name</code> and <code>version</code> that was ordered onto the blockchain before this definition).</p> <pre><code>{\n  \"header\": {\n    \"id\": \"727f7d3a-d07e-4e80-95af-59f8d2ac7531\", // this is the ID of the message, not the data type\n    \"type\": \"definition\", // a special type for system broadcasts\n    \"txtype\": \"batch_pin\", // the broadcast is pinned to the chain\n    \"author\": \"0x0a65365587a65ce44938eab5a765fe8bc6532bdf\", // the local identity\n    \"created\": \"2021-07-01T21:06:26.9997478Z\", // the time the broadcast was sent\n    \"namespace\": \"ff_system\", // the data/message broadcast happens on the system namespace\n    \"topic\": [\n      \"ff_ns_default\" // the namespace itself is used in the topic\n    ],\n    \"tag\": \"ff_define_datatype\", // a tag instructing FireFly to process this as a datatype definition\n    \"datahash\": \"56bd677e3e070ba62f547237edd7a90df5deaaf1a42e7d6435ec66a587c14370\"\n  },\n  \"hash\": \"5b6593720243831ba9e4ad002c550e95c63704b2c9dbdf31135d7d9207f8cae8\",\n  \"state\": \"ready\", // this message is stored locally but not yet confirmed\n  \"data\": [\n    {\n      \"id\": \"7539a0ab-78d8-4d42-b283-7e316b3afed3\", // this data object in the ff_system namespace, contains the schema\n      \"hash\": \"22ba1cdf84f2a4aaffac665c83ff27c5431c0004dc72a9bf031ae35a75ac5aef\"\n    }\n  ]\n}\n</code></pre>"},{"location":"tutorials/define_datatype/#lookup-the-confirmed-data-type","title":"Lookup the confirmed data type","text":"<p><code>GET</code> <code>/api/v1/namespaces/default/datatypes?name=widget&amp;version=0.0.2</code></p> <pre><code>[\n  {\n    \"id\": \"421c94b1-66ce-4ba0-9794-7e03c63df29d\", // an ID allocated to the datatype\n    \"message\": \"727f7d3a-d07e-4e80-95af-59f8d2ac7531\", // the message that broadcast this data type\n    \"validator\": \"json\", // the type of validator that this datatype can be used for (this one is JSON Schema)\n    \"namespace\": \"default\", // the namespace of the datatype\n    \"name\": \"widget\", // the name of the datatype\n    \"version\": \"0.0.2\", // the version of the data type\n    \"hash\": \"a4dceb79a21937ca5ea9fa22419011ca937b4b8bc563d690cea3114af9abce2c\", // hash of the schema itself\n    \"created\": \"2021-07-01T21:06:26.983986Z\", // time it was confirmed\n    \"value\": {\n      // the JSON schema itself\n      \"$id\": \"https://example.com/widget.schema.json\",\n      \"$schema\": \"https://json-schema.org/draft/2020-12/schema\",\n      \"title\": \"Widget\",\n      \"type\": \"object\",\n      \"properties\": {\n        \"id\": {\n          \"type\": \"string\",\n          \"description\": \"The unique identifier for the widget.\"\n        },\n        \"name\": {\n          \"type\": \"string\",\n          \"description\": \"The person's last name.\"\n        }\n      }\n    }\n  }\n]\n</code></pre>"},{"location":"tutorials/define_datatype/#example-private-send-referring-to-the-datatype","title":"Example private send referring to the datatype","text":"<p>Once confirmed, a piece of data can be assigned that datatype and all FireFly nodes will verify it against the schema. On a sending node, the data will be rejected at upload/send time if it does not conform. On other nodes, bad data results in a <code>message_rejected</code> event (rather than <code>message_confirmed</code>) for any message that arrives referring to that data.</p> <p><code>POST</code> <code>/api/v1/namespaces/default/send/message</code></p> <pre><code>{\n  \"header\": {\n    \"tag\": \"new_widget_created\",\n    \"topic\": [\"widget_id_12345\"]\n  },\n  \"group\": {\n    \"members\": [\n      {\n        \"identity\": \"org_1\"\n      }\n    ]\n  },\n  \"data\": [\n    {\n      \"datatype\": {\n        \"name\": \"widget\",\n        \"version\": \"0.0.2\"\n      },\n      \"value\": {\n        \"id\": \"widget_id_12345\",\n        \"name\": \"superwidget\"\n      }\n    }\n  ]\n}\n</code></pre>"},{"location":"tutorials/define_datatype/#defining-datatypes-using-the-sandbox","title":"Defining Datatypes using the Sandbox","text":"<p>You can also define a datatype through the FireFly Sandbox.</p> <p>To get started, open up the Web UI and Sanbox UI for at least one of your members. The URLs for these were printed in your terminal when you started your FireFly stack.</p> <p>In the sandbox, enter the datatype's name, version, and JSON Schema as seen in the screenshot below.</p> <pre><code>{\n  \"name\": \"widget\",\n  \"version\": \"0.0.2\",\n  \"value\": {\n    \"$id\": \"https://example.com/widget.schema.json\",\n    \"$schema\": \"https://json-schema.org/draft/2020-12/schema\",\n    \"title\": \"Widget\",\n    \"type\": \"object\",\n    \"properties\": {\n      \"id\": {\n        \"type\": \"string\",\n        \"description\": \"The unique identifier for the widget.\"\n      },\n      \"name\": {\n        \"type\": \"string\",\n        \"description\": \"The person's last name.\"\n      }\n    }\n  }\n}\n</code></pre> <p></p> <p>Notice how the <code>data</code> field in the center panel updates in real time.</p> <p>Click the blue <code>Run</code> button. This should return a <code>202</code> response immediately in the Server Response section and will populate the right hand panel with transaction information after a few seconds.</p> <p></p> <p>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 that you've successfully defined your datatype</p> <p></p>"},{"location":"tutorials/events/","title":"Listen for events","text":""},{"location":"tutorials/events/#quick-reference","title":"Quick reference","text":"<p>Probably the most important aspect of FireFly is that it is an event-driven programming model.</p> <p>Parties interact by sending messages and transactions to each other, on and off chain. Once aggregated and confirmed those events drive processing in the other party.</p> <p>This allows orchestration of complex multi-party system applications and business processes.</p> <p>FireFly provides each party with their own private history, that includes all exchanges outbound and inbound performed through the node into the multi-party system. That includes blockchain backed transactions, as well as completely off-chain message exchanges.</p> <p>The event transports are pluggable. The core transports are WebSockets and Webhooks. We focus on WebSockets in this getting started guide.</p> <p>Check out the Request/Reply section for more information on Webhooks</p>"},{"location":"tutorials/events/#additional-info","title":"Additional info","text":"<ul> <li>Key Concepts: Multi-party process flow</li> <li>Reference: coming soon</li> </ul>"},{"location":"tutorials/events/#websockets-example-1-ephemeral-subscription-with-auto-commit","title":"WebSockets Example 1: Ephemeral subscription with auto-commit","text":"<p>The simplest way to get started consuming events, is with an ephemeral WebSocket listener.</p> <p>Example connection URL:</p> <p><code>ws://localhost:5000/ws?namespace=default&amp;ephemeral&amp;autoack&amp;filter.events=message_confirmed</code></p> <ul> <li><code>namespace=default</code> - event listeners are scoped to a namespace</li> <li><code>ephemeral</code> - listen for events that occur while this connection is active, but do not remember the app instance (great for UIs)</li> <li><code>autoack</code>- automatically acknowledge each event, so the next event is sent (great for UIs)</li> <li><code>filter.events=message_confirmed</code> - only listen for events resulting from a message confirmation</li> </ul> <p>There are a number of browser extensions that let you experiment with WebSockets:</p> <p></p>"},{"location":"tutorials/events/#example-event-payload","title":"Example event payload","text":"<p>The events (by default) do not contain the payload data, just the <code>event</code> and referred <code>message</code>. This means the WebSocket payloads are a predictably small size, and the application can use the information in the <code>message</code> to post-filter the event to decide if it needs to download the full data.</p> <p>There are server-side filters provided on events as well</p> <pre><code>{\n  \"id\": \"8f0da4d7-8af7-48da-912d-187979bf60ed\",\n  \"sequence\": 61,\n  \"type\": \"message_confirmed\",\n  \"namespace\": \"default\",\n  \"reference\": \"9710a350-0ba1-43c6-90fc-352131ce818a\",\n  \"created\": \"2021-07-02T04:37:47.6556589Z\",\n  \"subscription\": {\n    \"id\": \"2426c5b1-ffa9-4f7d-affb-e4e541945808\",\n    \"namespace\": \"default\",\n    \"name\": \"2426c5b1-ffa9-4f7d-affb-e4e541945808\"\n  },\n  \"message\": {\n    \"header\": {\n      \"id\": \"9710a350-0ba1-43c6-90fc-352131ce818a\",\n      \"type\": \"broadcast\",\n      \"txtype\": \"batch_pin\",\n      \"author\": \"0x1d14b65d2dd5c13f6cb6d3dc4aa13c795a8f3b28\",\n      \"created\": \"2021-07-02T04:37:40.1257944Z\",\n      \"namespace\": \"default\",\n      \"topic\": [\"default\"],\n      \"datahash\": \"cd6a09a15ccd3e6ed1d67d69fa4773b563f27f17f3eaad611a2792ba945ca34f\"\n    },\n    \"hash\": \"1b6808d2b95b418e54e7bd34593bfa36a002b841ac42f89d00586dac61e8df43\",\n    \"batchID\": \"16ffc02c-8cb0-4e2f-8b58-a707ad1d1eae\",\n    \"state\": \"confirmed\",\n    \"confirmed\": \"2021-07-02T04:37:47.6548399Z\",\n    \"data\": [\n      {\n        \"id\": \"b3a814cc-17d1-45d5-975e-90279ed2c3fc\",\n        \"hash\": \"9ddefe4435b21d901439e546d54a14a175a3493b9fd8fbf38d9ea6d3cbf70826\"\n      }\n    ]\n  }\n}\n</code></pre>"},{"location":"tutorials/events/#download-the-message-and-data","title":"Download the message and data","text":"<p>A simple REST API is provided to allow you to download the data associated with the message:</p> <p><code>GET</code> <code>/api/v1/namespaces/default/messages/{id}?data=true</code></p>"},{"location":"tutorials/events/#download-just-the-data-array-associated-with-a-message","title":"Download just the data array associated with a message","text":"<p>As you already have the message object in the event delivery, you can query just the array of data objects as follows:</p> <p><code>GET</code> <code>/api/v1/namespaces/default/messages/{id}/data</code></p>"},{"location":"tutorials/events/#websockets-example-2-durable-subscription-for-your-application-with-manual-commit","title":"WebSockets Example 2: Durable subscription for your application, with manual-commit","text":"<p>To reliably process messages within your application, you should first set up a subscription.</p> <p>A subscription requests that:</p> <ul> <li>FireFly keeps a record of the latest event consumed by that application</li> <li>FireFly only delivers one copy of the event to the application, even when there are multiple active connections</li> </ul> <p>This should be combined with manual acknowledgment of the events, where the application sends a payload such as the following in response to each event it receives (where the <code>id</code> comes from the event it received):</p> <pre><code>{ \"type\": \"ack\", \"id\": \"617db63-2cf5-4fa3-8320-46150cbb5372\" }\n</code></pre> <p>You must send an acknowledgement for every message, or you will stop receiving messages.</p>"},{"location":"tutorials/events/#set-up-the-websocket-subscription","title":"Set up the WebSocket subscription","text":"<p>Each subscription is scoped to a namespace, and must have a <code>name</code>. You can then choose to perform server-side filtering on the events using regular expressions matched against the information in the event.</p> <p><code>POST</code> <code>/namespaces/default/subscriptions</code></p> <pre><code>{\n  \"transport\": \"websockets\",\n  \"name\": \"app1\",\n  \"filter\": {\n    \"blockchainevent\": {\n      \"listener\": \".*\",\n      \"name\": \".*\"\n    },\n    \"events\": \".*\",\n    \"message\": {\n      \"author\": \".*\",\n      \"group\": \".*\",\n      \"tag\": \".*\",\n      \"topics\": \".*\"\n    },\n    \"transaction\": {\n      \"type\": \".*\"\n    }\n  },\n  \"options\": {\n    \"firstEvent\": \"newest\",\n    \"readAhead\": 50\n  }\n}\n</code></pre>"},{"location":"tutorials/events/#connect-to-consume-messages","title":"Connect to consume messages","text":"<p>Example connection URL:</p> <p><code>ws://localhost:5000/ws?namespace=default&amp;name=app1</code></p> <ul> <li><code>namespace=default</code> - event listeners are scoped to a namespace</li> <li><code>name=app1</code> - the subscription name</li> </ul>"},{"location":"tutorials/events/#custom-contract-events","title":"Custom Contract Events","text":"<p>If you are interested in learning more about events for custom smart contracts, please see the Working with custom smart contracts section.</p>"},{"location":"tutorials/private_send/","title":"Privately send data","text":""},{"location":"tutorials/private_send/#quick-reference","title":"Quick reference","text":"<ul> <li>Sends a <code>message</code> to a restricted set of parties</li> <li>The message describes who sent it, to whom, and exactly what data was sent</li> <li>A <code>message</code> has one or more attached pieces of business <code>data</code></li> <li>Can be sent in-line, uploaded in advanced, or received from other parties</li> <li>Can include smaller JSON payloads suitable for database storage<ul> <li>These can be verified against a <code>datatype</code></li> </ul> </li> <li>Can include references to large (multi megabyte/gigabyte) Blob data</li> <li>A <code>group</code> specifies who has visibility to the data</li> <li>The author must be included in the group - auto-added if omitted</li> <li>Can be specified in-line in the message by listing recipients directly</li> <li>Can be referred to by hash</li> <li>Private sends are optionally sequenced via pinning to the blockchain</li> <li>If the send is pinned:<ul> <li>The blockchain does not contain any data, just a hash pin</li> <li>Even the ordering context (topic) is obscured in the on-chain data</li> <li>This is true regardless of whether a restricted set of participants     are maintaining the ledger, such as in the case of a Fabric Channel.</li> <li>The message should not be considered confirmed (even by the sender) until it   has been sequenced via the blockchain and a <code>message_confirmed</code> event occurs</li> <li>Batched for efficiency</li> <li>One <code>batch</code> can pin hundreds of private <code>message</code> sends</li> <li>The batch flows privately off-chain from the sender to each recipient</li> </ul> </li> <li>If the send is unpinned:<ul> <li>No data is written to the blockchain at all</li> <li>The message is marked confirmed immediately</li> <li>The sender receives a <code>message_confirmed</code> event immediately</li> <li>The other parties in the group get <code>message_confirmed</code> events as soon as the data arrives</li> </ul> </li> </ul>"},{"location":"tutorials/private_send/#additional-info","title":"Additional info","text":"<ul> <li>Key Concepts: Private data exchange</li> <li>Swagger: POST /api/v1/namespaces/{ns}/messages/private</li> </ul>"},{"location":"tutorials/private_send/#example-1-pinned-private-send-of-in-line-string-data","title":"Example 1: Pinned private send of in-line string data","text":"<p><code>POST</code> <code>/api/v1/namespaces/default/messages/private</code></p> <pre><code>{\n  \"data\": [\n    {\n      \"value\": \"a string\"\n    }\n  ],\n  \"group\": {\n    \"members\": [\n      {\n        \"identity\": \"org_1\"\n      }\n    ]\n  }\n}\n</code></pre>"},{"location":"tutorials/private_send/#example-message-response","title":"Example message response","text":"<p>Status: <code>202 Accepted</code> - the message is on it's way, but has not yet been confirmed.</p> <pre><code>{\n  \"header\": {\n    \"id\": \"c387e9d2-bdac-44cc-9dd5-5e7f0b6b0e58\", // uniquely identifies this private message\n    \"type\": \"private\", // set automatically\n    \"txtype\": \"batch_pin\", // message will be batched, and sequenced via the blockchain\n    \"author\": \"0x0a65365587a65ce44938eab5a765fe8bc6532bdf\", // set automatically in this example to the node org\n    \"created\": \"2021-07-02T02:37:13.4642085Z\", // set automatically\n    \"namespace\": \"default\", // the 'default' namespace was set in the URL\n    // The group hash is calculated from the resolved list of group participants.\n    // The first time a group is used, the participant list is sent privately along with the\n    // batch of messages in a `groupinit` message.\n    \"group\": \"2aa5297b5eed0c3a612a667c727ca38b54fb3b5cc245ebac4c2c7abe490bdf6c\",\n    \"topics\": [\n      \"default\" // the default topic that the message is published on, if no topic is set\n    ],\n    // datahash is calculated from the data array below\n    \"datahash\": \"24b2d583b87eda952fa00e02c6de4f78110df63218eddf568f0240be3d02c866\"\n  },\n  \"hash\": \"423ad7d99fd30ff679270ad2b6b35cdd85d48db30bafb71464ca1527ce114a60\", // hash of the header\n  \"state\": \"ready\", // this message is stored locally but not yet confirmed\n  \"data\": [\n    // one item of data was stored\n    {\n      \"id\": \"8d8635e2-7c90-4963-99cc-794c98a68b1d\", // can be used to query the data in the future\n      \"hash\": \"c95d6352f524a770a787c16509237baf7eb59967699fb9a6d825270e7ec0eacf\" // sha256 hash of `\"a string\"`\n    }\n  ]\n}\n</code></pre>"},{"location":"tutorials/private_send/#example-2-unpinned-private-send-of-in-line-string-data","title":"Example 2: Unpinned private send of in-line string data","text":"<p>Set <code>header.txtype: \"none\"</code> to disable pinning of the private message send to the blockchain. The message is sent immediately (no batching) over the private data exchange.</p> <p><code>POST</code> <code>/api/v1/namespaces/default/messages/private</code></p> <pre><code>{\n  \"header\": {\n    \"txtype\": \"none\"\n  },\n  \"data\": [\n    {\n      \"value\": \"a string\"\n    }\n  ],\n  \"group\": {\n    \"members\": [\n      {\n        \"identity\": \"org_1\"\n      }\n    ]\n  }\n}\n</code></pre>"},{"location":"tutorials/private_send/#example-3-inline-object-data-to-a-topic-no-datatype-verification","title":"Example 3: Inline object data to a topic (no datatype verification)","text":"<p>It is very good practice to set a <code>tag</code> and <code>topic</code> in each of your messages:</p> <ul> <li><code>tag</code> should tell the apps receiving the private send (including the local app), what   to do when it receives the message. Its the reason for the send - an   application specific type for the message.</li> <li><code>topic</code> should be something like a well known identifier that relates to the   information you are publishing. It is used as an ordering context, so all   sends on a given topic are assured to be processed in order.</li> </ul> <p><code>POST</code> <code>/api/v1/namespaces/default/messages/private</code></p> <pre><code>{\n  \"header\": {\n    \"tag\": \"new_widget_created\",\n    \"topics\": [\"widget_id_12345\"]\n  },\n  \"group\": {\n    \"members\": [\n      {\n        \"identity\": \"org_1\"\n      }\n    ]\n  },\n  \"data\": [\n    {\n      \"value\": {\n        \"id\": \"widget_id_12345\",\n        \"name\": \"superwidget\"\n      }\n    }\n  ]\n}\n</code></pre>"},{"location":"tutorials/private_send/#notes-on-why-setting-a-topic-is-important","title":"Notes on why setting a topic is important","text":"<p>The FireFly aggregator uses the <code>topic</code> (obfuscated on chain) to determine if a message is the next message in an in-flight sequence for any groups the node is involved in. If it is, then that message must receive all off-chain private data and be confirmed before any subsequent messages can be confirmed on the same sequence.</p> <p>So if you use the same topic in every message, then a single failed send on one topic blocks delivery of all messages between those parties, until the missing data arrives.</p> <p>Instead it is best practice to set the topic on your messages to value that identifies an ordered stream of business processing. Some examples:</p> <ul> <li>A long-running business process instance identifier assigned at initiation</li> <li>A real-world business transaction identifier used off-chain</li> <li>The agreed identifier of an asset you are attaching a stream of evidence to</li> <li>An NFT identifier that is assigned to an asset (digital twin scenarios)</li> <li>An agreed primary key for a data resource being reconciled between multiple parties</li> </ul> <p>The <code>topic</code> field is an array, because there are cases (such as merging two identifiers) where you need a message to be deterministically ordered across multiple sequences. However, this is an advanced use case and you are likely to set a single topic on the vast majority of your messages.</p>"},{"location":"tutorials/private_send/#example-3-upload-a-blob-with-metadata-and-send-privately","title":"Example 3: Upload a blob with metadata and send privately","text":"<p>Here we make two API calls.</p> <ol> <li> <p>Create the <code>data</code> object explicitly, using a multi-part form upload</p> </li> <li> <p>You can also just post JSON to this endpoint</p> </li> <li> <p>Privately send a message referring to that data</p> </li> <li> <p>The Blob is sent privately to each party</p> </li> <li>A pin goes to the blockchain</li> <li>The metadata goes into a batch with the message</li> </ol>"},{"location":"tutorials/private_send/#multipart-form-post-of-a-file","title":"Multipart form post of a file","text":"<p>Example curl command (Linux/Mac) to grab an image from the internet, and pipe it into a multi-part form post to FireFly.</p> <p>Note we use <code>autometa</code> to cause FireFly to automatically add the <code>filename</code>, and <code>size</code>, to the JSON part of the <code>data</code> object for us.</p> <pre><code>curl -sLo - https://github.com/hyperledger/firefly/raw/main/docs/firefly_logo.png \\\n | curl --form autometa=true --form file=@- \\\n   http://localhost:5000/api/v1/namespaces/default/data\n</code></pre>"},{"location":"tutorials/private_send/#example-data-response-from-blob-upload","title":"Example data response from Blob upload","text":"<p>Status: <code>200 OK</code> - your data is uploaded to your local FireFly node</p> <p>At this point the data has not be shared with anyone else in the network</p> <pre><code>{\n  // A uniquely generated ID, we can refer to when sending this data to other parties\n  \"id\": \"97eb750f-0d0b-4c1d-9e37-1e92d1a22bb8\",\n  \"validator\": \"json\", // the \"value\" part is JSON\n  \"namespace\": \"default\", // from the URL\n  // The hash is a combination of the hash of the \"value\" metadata, and the\n  // hash of the blob\n  \"hash\": \"997af6a9a19f06cc8a46872617b8bf974b106f744b2e407e94cc6959aa8cf0b8\",\n  \"created\": \"2021-07-01T20:20:35.5462306Z\",\n  \"value\": {\n    \"filename\": \"-\", // dash is how curl represents the filename for stdin\n    \"size\": 31185 // the size of the blob data\n  },\n  \"blob\": {\n    // A hash reference to the blob\n    \"hash\": \"86e6b39b04b605dd1b03f70932976775962509d29ae1ad2628e684faabe48136\"\n  }\n}\n</code></pre>"},{"location":"tutorials/private_send/#send-the-uploaded-data-privately","title":"Send the uploaded data privately","text":"<p>Just include a reference to the <code>id</code> returned from the upload.</p> <p><code>POST</code> <code>/api/v1/namespaces/default/messages/private</code></p> <pre><code>{\n  \"data\": [\n    {\n      \"id\": \"97eb750f-0d0b-4c1d-9e37-1e92d1a22bb8\"\n    }\n  ],\n  \"group\": {\n    \"members\": [\n      {\n        \"identity\": \"org_1\"\n      }\n    ]\n  }\n}\n</code></pre>"},{"location":"tutorials/private_send/#sending-private-messages-using-the-sandbox","title":"Sending Private Messages using the Sandbox","text":"<p>All of the functionality discussed above can be done through the FireFly Sandbox.</p> <p>To get started, open up the Web UI and Sanbox UI for at least one of your members. The URLs for these were printed in your terminal when you started your FireFly stack.</p> <p>Make sure to expand the \"Send a Private Message\" section. Enter your message into the message field as seen in the screenshot below. Because we are sending a private message, make sure you're in the \"Send a Private Message\" section and that you choose a message recipient</p> <p></p> <p>Notice how the <code>data</code> field in the center panel updates in real time as you update the message you wish to send.</p> <p>Click the blue <code>Run</code> button. This should return a <code>202</code> response immediately in the Server Response section and will populate the right hand panel with transaction information after a few seconds.</p> <p></p> <p>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</p> <p></p>"},{"location":"tutorials/query_messages/","title":"Explore messages","text":""},{"location":"tutorials/query_messages/#quick-reference","title":"Quick reference","text":"<p>The FireFly Explorer is a great way to view the messages sent and received by your node.</p> <p>Just open <code>/ui</code> on your FireFly node to access it.</p> <p></p> <p>This builds on the APIs to query and filter messages, described below</p>"},{"location":"tutorials/query_messages/#additional-info","title":"Additional info","text":"<ul> <li>Reference: API Query Syntax</li> <li>Swagger: GET /api/v1/namespaces/{ns}/messages</li> </ul>"},{"location":"tutorials/query_messages/#example-1-query-confirmed-messages","title":"Example 1: Query confirmed messages","text":"<p>These are the messages ready to be processed in your application. All data associated with the message (including Blob attachments) is available, and if they are sequenced by the blockchain, then those blockchain transactions are complete.</p> <p>The order in which you process messages should be determined by absolute order of <code>message_confirmed</code> events - queryable via the <code>events</code> collection, or through event listeners (discussed next in the getting started guide).</p> <p>That is because <code>messages</code> are ordered by timestamp, which is potentially subject to adjustments of the clock. Whereas <code>events</code> are ordered by the insertion order into the database, and as such changes in the clock do not affect the order.</p> <p><code>GET</code> <code>/api/v1/namespaces/{ns}/messages?pending=false&amp;limit=100</code></p>"},{"location":"tutorials/query_messages/#example-response","title":"Example response","text":"<pre><code>[\n  {\n    \"header\": {\n      \"id\": \"423302bb-abfc-4d64-892d-38b2fdfe1549\",\n      \"type\": \"private\", // this was a private send\n      \"txtype\": \"batch_pin\", // pinned in a batch to the blockchain\n      \"author\": \"0x1d14b65d2dd5c13f6cb6d3dc4aa13c795a8f3b28\",\n      \"created\": \"2021-07-02T03:09:40.2606238Z\",\n      \"namespace\": \"default\",\n      \"group\": \"2aa5297b5eed0c3a612a667c727ca38b54fb3b5cc245ebac4c2c7abe490bdf6c\", // sent to this group\n      \"topic\": [\"widget_id_12345\"],\n      \"tag\": \"new_widget_created\",\n      \"datahash\": \"551dd261e80ce76b1908c031cff8a707bd76376d6eddfdc1040c2ed6481ec8dd\"\n    },\n    \"hash\": \"bf2ca94db8c31bae3cae974bb626fa822c6eee5f572d274d72281e72537b30b3\",\n    \"batch\": \"f7ac773d-885a-4d73-ac6b-c09f5346a051\", // the batch ID that pinned this message to the chain\n    \"state\": \"confirmed\", // message is now confirmed\n    \"confirmed\": \"2021-07-02T03:09:49.9207211Z\", // timestamp when this node confirmed the message\n    \"data\": [\n      {\n        \"id\": \"914eed77-8789-451c-b55f-ba9570a71eba\",\n        \"hash\": \"9541cabc750c692e553a421a6c5c07ebcae820774d2d8d0b88fac2a231c10bf2\"\n      }\n    ],\n    \"pins\": [\n      // A \"pin\" is an identifier that is used by FireFly for sequencing messages.\n      //\n      // For private messages, it is an obfuscated representation of the sequence of this message,\n      // on a topic, within this group, from this sender. There will be one pin per topic. You will find these\n      // pins in the blockchain transaction, as well as the off-chain data.\n      // Each one is unqiue, and without the group hash, very difficult to correlate - meaning\n      // the data on-chain provides a high level of privacy.\n      //\n      // Note for broadcast (which does not require obfuscation), it is simply a hash of the topic.\n      // So you will see the same pin for all messages on the same topic.\n      \"ee56de6241522ab0ad8266faebf2c0f1dc11be7bd0c41d847998135b45685b77\"\n    ]\n  }\n]\n</code></pre>"},{"location":"tutorials/query_messages/#example-2-query-all-messages","title":"Example 2: Query all messages","text":"<p>The natural sort order the API will return for messages is:</p> <ul> <li>Pending messages first</li> <li>In descending <code>created</code> timestamp order</li> <li>Confirmed messages</li> <li>In descending <code>confirmed</code> timestamp order</li> </ul> <p><code>GET</code> <code>/api/v1/namespaces/{ns}/messages</code></p>"},{"location":"tutorials/rotate_dx_certs/","title":"Rotate DX Certs","text":""},{"location":"tutorials/rotate_dx_certs/#quick-reference","title":"Quick reference","text":"<p>At some point you may need to rotate certificates on your Data Exchange nodes. FireFly provides an API to update a node identity, but there are a few prerequisite steps to load a new certificate on the Data Exchange node itself. This guide will walk you through that process. For more information on different types of identities in FireFly, please see the Reference page on Identities.</p> <p>NOTE: This guide assumes that you are working in a local development environment that was set up with the Getting Started Guide. For a production deployment, the exact process to accomplish each step may be different. For example, you may generate your certs with a CA, or in some other manner. But the high level steps remain the same.</p> <p>The high level steps to the process (described in detail below) are:</p> <ul> <li>Generate new certs and keys</li> <li>Install new certs and keys on each Data Exchange filesystem</li> <li>Remove old certs from the <code>peer-certs</code> directory</li> <li>Restart each Data Exchange process</li> <li><code>PATCH</code> the node identity using the FireFly API</li> </ul>"},{"location":"tutorials/rotate_dx_certs/#generate-new-certs-and-keys","title":"Generate new certs and keys","text":"<p>To generate a new cert, we're going to use a self signed certificate generated by <code>openssl</code>. This is how the FireFly CLI generated the original cert that was used when it created your stack.</p> <p>For the first member of a FireFly stack you run:</p> <pre><code>openssl req -new -x509 -nodes -days 365 -subj /CN=dataexchange_0/O=member_0 -keyout key.pem -out cert.pem\n</code></pre> <p>For the second member:</p> <pre><code>openssl req -new -x509 -nodes -days 365 -subj /CN=dataexchange_1/O=member_1 -keyout key.pem -out cert.pem\n</code></pre> <p>NOTE: If you perform these two commands in the same directory, the second one will overwrite the output of the first. It is advisable to run them in separate directories, or copy the cert and key to the Data Exchange file system (the next step below) before generating the next cert / key pair.</p>"},{"location":"tutorials/rotate_dx_certs/#install-the-new-certs-on-each-data-exchange-file-system","title":"Install the new certs on each Data Exchange File System","text":"<p>For a dev environment created with the FireFly CLI, the certificate and key will be located in the <code>/data</code> directory on the Data Exchange node's file system. You can use the <code>docker cp</code> command to copy the file to the correct location, then set the file ownership correctly.</p> <pre><code>docker cp cert.pem dev_dataexchange_0:/data/cert.pem\ndocker exec dev_dataexchange_0 chown root:root /data/cert.pem\n</code></pre> <p>NOTE: If your environment is not called <code>dev</code> you may need to change the beginning of the container name in the Docker commands listed in this guide.</p>"},{"location":"tutorials/rotate_dx_certs/#remove-old-certs-from-the-peer-certs-directory","title":"Remove old certs from the <code>peer-certs</code> directory","text":"<p>To clear out the old certs from the first Data Exchange node run:</p> <pre><code>docker exec dev_dataexchange_0 sh -c \"rm /data/peer-certs/*.pem\"\n</code></pre> <p>To clear out the old certs from the second Data Exchange node run:</p> <pre><code>docker exec dev_dataexchange_1 sh -c \"rm /data/peer-certs/*.pem\"\n</code></pre>"},{"location":"tutorials/rotate_dx_certs/#restart-each-data-exchange-process","title":"Restart each Data Exchange process","text":"<p>To restart your Data Exchange processes, run:</p> <pre><code>docker restart dev_dataexchange_0\n</code></pre> <pre><code>docker restart dev_dataexchange_1\n</code></pre>"},{"location":"tutorials/rotate_dx_certs/#patch-the-node-identity-using-the-firefly-api","title":"<code>PATCH</code> the node identity using the FireFly API","text":"<p>The final step is to broadcast the new cert for each node, from the FireFly node that will be using that cert. You will need to lookup the UUID for the node identity in order to update it.</p>"},{"location":"tutorials/rotate_dx_certs/#request","title":"Request","text":"<p><code>GET</code> <code>http://localhost:5000/api/v1/namespaces/default/identities</code></p>"},{"location":"tutorials/rotate_dx_certs/#response","title":"Response","text":"<p>In the JSON response body, look for the node identity that belongs on this FireFly instance. Here is the node identity from an example stack:</p> <pre><code>...\n    {\n        \"id\": \"20da74a2-d4e6-4eaf-8506-e7cd205d8254\",\n        \"did\": \"did:firefly:node/node_2b9630\",\n        \"type\": \"node\",\n        \"parent\": \"41e93d92-d0da-4e5a-9cee-adf33f017a60\",\n        \"namespace\": \"default\",\n        \"name\": \"node_2b9630\",\n        \"profile\": {\n            \"cert\": \"-----BEGIN CERTIFICATE-----\\nMIIC1DCCAbwCCQDa9x3wC7wepDANBgkqhkiG9w0BAQsFADAsMRcwFQYDVQQDDA5k\\nYXRhZXhjaGFuZ2VfMDERMA8GA1UECgwIbWVtYmVyXzAwHhcNMjMwMjA2MTQwMTEy\\nWhcNMjQwMjA2MTQwMTEyWjAsMRcwFQYDVQQDDA5kYXRhZXhjaGFuZ2VfMDERMA8G\\nA1UECgwIbWVtYmVyXzAwggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQDJ\\nSgtJw99V7EynvqxWdJkeiUlOg3y+JtJlhxGC//JLp+4sYCtOMriULNf5ouImxniR\\nO2vEd+LNdMuREN4oZdUHtJD4MM7lOFw/0ICNEPJ+oEoUTzOC0OK68sA+OCybeS2L\\nmLBu4yvWDkpufR8bxBJfBGarTAFl36ao1Eoogn4m9gmVrX+V5SOKUhyhlHZFkZNb\\ne0flwQmDMKg6qAbHf3j8cnrrZp26n68IGjwqySPFIRLFSz28zzMYtyzo4b9cF9NW\\nGxusMHsExX5gzlTjNacGx8Tlzwjfolt23D+WHhZX/gekOsFiV78mVjgJanE2ls6D\\n5ZlXi5iQSwm8dlmo9RxFAgMBAAEwDQYJKoZIhvcNAQELBQADggEBAAwr4aAvQnXG\\nkO3xNO+7NGzbb/Nyck5udiQ3RmlZBEJSUsPCsWd4SBhH7LvgbT9ECuAEjgH+2Ip7\\nusd8CROr3sTb9t+7Krk+ljgZirkjq4j/mIRlqHcBJeBtylOz2p0oPsitlI8Yea2D\\nQ4/Xru6txUKNK+Yut3G9qvg/vm9TAwkNHSthzb26bI7s6lx9ZSuFbbG6mR+RQ+8A\\nU4AX1DVo5QyTwSi1lp0+pKFEgtutmWGYn8oT/ya+OLzj+l7Ul4HE/mEAnvECtA7r\\nOC8AEjC5T4gUsLt2IXW9a7lCgovjHjHIySQyqsdYBjkKSn5iw2LRovUWxT1GBvwH\\nFkTvCpHhgko=\\n-----END CERTIFICATE-----\\n\",\n            \"endpoint\": \"https://dataexchange_0:3001\",\n            \"id\": \"member_0/node_2b9630\"\n        },\n        \"messages\": {\n            \"claim\": \"95da690b-bb05-4873-9478-942f607f363a\",\n            \"verification\": null,\n            \"update\": null\n        },\n        \"created\": \"2023-02-06T14:02:50.874319382Z\",\n        \"updated\": \"2023-02-06T14:02:50.874319382Z\"\n    },\n...\n</code></pre> <p>Copy the UUID from the <code>id</code> field, and add that to the <code>PATCH</code> request. In this case it is <code>20da74a2-d4e6-4eaf-8506-e7cd205d8254</code>.</p>"},{"location":"tutorials/rotate_dx_certs/#request_1","title":"Request","text":"<p>Now we will send the new certificate to FireFly. Put the contents of your <code>cert.pem</code> file in the <code>cert</code> field.</p> <p>NOTE: Usually the <code>cert.pem</code> file will contain line breaks which will not be handled correctly by JSON parsers. Be sure to replace those line breaks with <code>\\n</code> so that the <code>cert</code> field is all on one line as shown below.</p> <p><code>PATCH</code> <code>http://localhost:5000/api/v1/namespaces/default/identities/20da74a2-d4e6-4eaf-8506-e7cd205d8254</code></p> <pre><code>{\n  \"profile\": {\n    \"cert\": \"-----BEGIN CERTIFICATE-----\\nMIIC1DCCAbwCCQDeKjPt3siRHzANBgkqhkiG9w0BAQsFADAsMRcwFQYDVQQDDA5k\\nYXRhZXhjaGFuZ2VfMDERMA8GA1UECgwIbWVtYmVyXzAwHhcNMjMwMjA2MTYxNTU3\\nWhcNMjQwMjA2MTYxNTU3WjAsMRcwFQYDVQQDDA5kYXRhZXhjaGFuZ2VfMDERMA8G\\nA1UECgwIbWVtYmVyXzAwggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQCy\\nEJaqDskxhkPHmCqj5Mxq+9QX1ec19fulh9Zvp8dLA6bfeg4fdQ9Ha7APG6w/0K8S\\nEaXOflSpXb0oKMe42amIqwvQaqTOA97HIe5R2HZxA1RWqXf+AueowWgI4crxr2M0\\nZCiXHyiZKpB8nzO+bdO9AKeYnzbhCsO0gq4LPOgpPjYkHPKhabeMVZilZypDVOGk\\nLU+ReQoVEZ+P+t0B/9v+5IQ2yyH41n5dh6lKv4mIaC1OBtLc+Pd6DtbRb7pijkgo\\n+LyqSdl24RHhSgZcTtMQfoRIVzvMkhF5SiJczOC4R8hmt62jtWadO4D5ZtJ7N37/\\noAG/7KJO4HbByVf4xOcDAgMBAAEwDQYJKoZIhvcNAQELBQADggEBAKWbQftV05Fc\\niwVtZpyvP2l4BvKXvMOyg4GKcnBSZol7UwCNrjwYSjqgqyuedTSZXHNhGFxQbfAC\\n94H25bDhWOfd7JH2D7E6RRe3eD9ouDnrt+de7JulsNsFK23IM4Nz5mRhRMVy/5p5\\n9yrsdW+5MXKWgz9569TIjiciCf0JqB7iVPwRrQyz5gqOiPf81PlyaMDeaH9wXtra\\n/1ZRipXiGiNroSPFrQjIVLKWdmnhWKWjFXsiijdSV/5E+8dBb3t//kEZ8UWfBrc4\\nfYVuZ8SJtm2ZzBmit3HFatDlFTE8PanRf/UDALUp4p6YKJ8NE2T8g/uDE0ee1pnF\\nIDsrC1GX7rs=\\n-----END CERTIFICATE-----\\n\",\n    \"endpoint\": \"https://dataexchange_0:3001\",\n    \"id\": \"member_0\"\n  }\n}\n</code></pre>"},{"location":"tutorials/rotate_dx_certs/#response_1","title":"Response","text":"<pre><code>{\n  \"id\": \"20da74a2-d4e6-4eaf-8506-e7cd205d8254\",\n  \"did\": \"did:firefly:node/node_2b9630\",\n  \"type\": \"node\",\n  \"parent\": \"41e93d92-d0da-4e5a-9cee-adf33f017a60\",\n  \"namespace\": \"default\",\n  \"name\": \"node_2b9630\",\n  \"profile\": {\n    \"cert\": \"-----BEGIN CERTIFICATE-----\\nMIIC1DCCAbwCCQDeKjPt3siRHzANBgkqhkiG9w0BAQsFADAsMRcwFQYDVQQDDA5k\\nYXRhZXhjaGFuZ2VfMDERMA8GA1UECgwIbWVtYmVyXzAwHhcNMjMwMjA2MTYxNTU3\\nWhcNMjQwMjA2MTYxNTU3WjAsMRcwFQYDVQQDDA5kYXRhZXhjaGFuZ2VfMDERMA8G\\nA1UECgwIbWVtYmVyXzAwggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQCy\\nEJaqDskxhkPHmCqj5Mxq+9QX1ec19fulh9Zvp8dLA6bfeg4fdQ9Ha7APG6w/0K8S\\nEaXOflSpXb0oKMe42amIqwvQaqTOA97HIe5R2HZxA1RWqXf+AueowWgI4crxr2M0\\nZCiXHyiZKpB8nzO+bdO9AKeYnzbhCsO0gq4LPOgpPjYkHPKhabeMVZilZypDVOGk\\nLU+ReQoVEZ+P+t0B/9v+5IQ2yyH41n5dh6lKv4mIaC1OBtLc+Pd6DtbRb7pijkgo\\n+LyqSdl24RHhSgZcTtMQfoRIVzvMkhF5SiJczOC4R8hmt62jtWadO4D5ZtJ7N37/\\noAG/7KJO4HbByVf4xOcDAgMBAAEwDQYJKoZIhvcNAQELBQADggEBAKWbQftV05Fc\\niwVtZpyvP2l4BvKXvMOyg4GKcnBSZol7UwCNrjwYSjqgqyuedTSZXHNhGFxQbfAC\\n94H25bDhWOfd7JH2D7E6RRe3eD9ouDnrt+de7JulsNsFK23IM4Nz5mRhRMVy/5p5\\n9yrsdW+5MXKWgz9569TIjiciCf0JqB7iVPwRrQyz5gqOiPf81PlyaMDeaH9wXtra\\n/1ZRipXiGiNroSPFrQjIVLKWdmnhWKWjFXsiijdSV/5E+8dBb3t//kEZ8UWfBrc4\\nfYVuZ8SJtm2ZzBmit3HFatDlFTE8PanRf/UDALUp4p6YKJ8NE2T8g/uDE0ee1pnF\\nIDsrC1GX7rs=\\n-----END CERTIFICATE-----\\n\",\n    \"endpoint\": \"https://dataexchange_0:3001\",\n    \"id\": \"member_0\"\n  },\n  \"messages\": {\n    \"claim\": \"95da690b-bb05-4873-9478-942f607f363a\",\n    \"verification\": null,\n    \"update\": \"5782cd7c-7643-4d7f-811b-02765a7aaec5\"\n  },\n  \"created\": \"2023-02-06T14:02:50.874319382Z\",\n  \"updated\": \"2023-02-06T14:02:50.874319382Z\"\n}\n</code></pre> <p>Repeat these requests for the second member/node running on port <code>5001</code>. After that you should be back up and running with your new certs, and you should be able to send private messages again.</p>"},{"location":"tutorials/chains/arbitrum/","title":"Arbitrum","text":"<p>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.</p>"},{"location":"tutorials/chains/arbitrum/#previous-steps-install-the-firefly-cli","title":"Previous steps: Install the FireFly CLI","text":"<p>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.</p> <p>\u2190 \u2460 Install the FireFly CLI</p>"},{"location":"tutorials/chains/arbitrum/#create-an-evmconnectyml-config-file","title":"Create an <code>evmconnect.yml</code> config file","text":"<p>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 <code>evmconnect.yml</code> with the following contents:</p> <pre><code>confirmations:\n  required: 4 # choose the number of confirmations you require\npolicyengine.simple:\n  fixedGasPrice: null\n  gasOracle:\n    mode: connector\n</code></pre> <p>For more info about <code>confirmations</code>, see Public vs. Permissioned</p> <p>For this tutorial, we will assume this file is saved at <code>~/Desktop/evmconnect.yml</code>. If your path is different, you will need to adjust the path in the next command below.</p>"},{"location":"tutorials/chains/arbitrum/#creating-a-new-stack","title":"Creating a new stack","text":"<p>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:</p> <ul> <li>Create a new Ethereum based stack named <code>arbitrum</code> with <code>1</code> member</li> <li>Disable <code>multiparty</code> 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</li> <li>Use an remote RPC node. This will create a signer locally, so that our signing key never leaves the development machine.</li> <li>See the Arbitrum docs and select an HTTPS RPC endpoint.</li> <li>Set the chain ID to <code>421613</code> (the correct ID for the Binance Smart Chain testnet)</li> <li>Merge the custom config created above with the generated <code>evmconnect</code> config file</li> </ul> <p>To do this, run the following command:</p> <pre><code>ff init ethereum arbitrum 1 \\\n    --multiparty=false \\\n    -n remote-rpc \\\n    --remote-node-url &lt;selected RPC endpoint&gt; \\\n    --chain-id 421613 \\\n    --connector-config ~/Desktop/evmconnect.yml\n</code></pre>"},{"location":"tutorials/chains/arbitrum/#start-the-stack","title":"Start the stack","text":"<p>Now you should be able to start your stack by running:</p> <pre><code>ff start arbitrum\n</code></pre> <p>After some time it should print out the following:</p> <pre><code>Web UI for member '0': http://127.0.0.1:5000/ui\nSandbox UI for member '0': http://127.0.0.1:5109\n\n\nTo see logs for your stack run:\n\nff logs arbitrum\n</code></pre>"},{"location":"tutorials/chains/arbitrum/#get-some-aribitrum","title":"Get some Aribitrum","text":"<p>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.</p> <p>First, you will need to know what signing address your FireFly node is using. To check that, you can run:</p> <pre><code>ff accounts list arbitrum\n[\n  {\n    \"address\": \"0x225764d1be1f137be23ddfc426b819512b5d0f3e\",\n    \"privateKey\": \"...\"\n  }\n]\n</code></pre> <p>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 and follow the instructions to send a tweet to the developers. Make sure to change the address to the one in the CLI.</p> <p></p>"},{"location":"tutorials/chains/arbitrum/#confirm-the-transaction-on-bscscan","title":"Confirm the transaction on Bscscan","text":"<p>You should be able to go lookup your account on 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.</p> <p></p>"},{"location":"tutorials/chains/arbitrum/#use-the-public-testnet","title":"Use the public testnet","text":"<p>Now that you have everything set up, you can follow one of the other FireFly guides such as Using Tokens or Custom Smart Contracts. For detailed instructions on deploying a custom smart contract to Binance Smart Chain, please see the Arbitrum docs for instructions using various tools.</p>"},{"location":"tutorials/chains/avalanche/","title":"Aavalanche","text":"<p>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.</p>"},{"location":"tutorials/chains/avalanche/#previous-steps-install-the-firefly-cli","title":"Previous steps: Install the FireFly CLI","text":"<p>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.</p> <p>\u2190 \u2460 Install the FireFly CLI</p>"},{"location":"tutorials/chains/avalanche/#create-an-evmconnectyml-config-file","title":"Create an <code>evmconnect.yml</code> config file","text":"<p>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 <code>evmconnect.yml</code> with the following contents:</p> <pre><code>confirmations:\n  required: 4 # choose the number of confirmations you require\npolicyengine.simple:\n  fixedGasPrice: null\n  gasOracle:\n    mode: connector\n</code></pre> <p>For more info about <code>confirmations</code>, see Public vs. Permissioned</p> <p>For this tutorial, we will assume this file is saved at <code>~/Desktop/evmconnect.yml</code>. If your path is different, you will need to adjust the path in the next command below.</p>"},{"location":"tutorials/chains/avalanche/#creating-a-new-stack","title":"Creating a new stack","text":"<p>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:</p> <ul> <li>Create a new Ethereum based stack named <code>avalanche</code> with <code>1</code> member</li> <li>Disable <code>multiparty</code> 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</li> <li>Use an remote RPC node. This will create a signer locally, so that our signing key never leaves the development machine.</li> <li>See the Avalanche docs and select and HTTPS RPC endpoint.</li> <li>Set the chain ID to <code>43113</code> (the correct ID for the Avalanche Fuji testnet)</li> <li>Merge the custom config created above with the generated <code>evmconnect</code> config file</li> </ul> <p>To do this, run the following command:</p> <pre><code>ff init ethereum avalanche 1 \\\n    --multiparty=false \\\n    -n remote-rpc \\\n    --remote-node-url &lt;selected RPC endpoint&gt; \\\n    --chain-id 43113 \\\n    --connector-config ~/Desktop/evmconnect.yml\n</code></pre>"},{"location":"tutorials/chains/avalanche/#start-the-stack","title":"Start the stack","text":"<p>Now you should be able to start your stack by running:</p> <pre><code>ff start avalanche\n</code></pre> <p>After some time it should print out the following:</p> <pre><code>Web UI for member '0': http://127.0.0.1:5000/ui\nSandbox UI for member '0': http://127.0.0.1:5109\n\n\nTo see logs for your stack run:\n\nff logs avalanche\n</code></pre>"},{"location":"tutorials/chains/avalanche/#get-some-avax","title":"Get some AVAX","text":"<p>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.</p> <p>First, you will need to know what signing address your FireFly node is using. To check that, you can run:</p> <pre><code>ff accounts list avalanche\n[\n  {\n    \"address\": \"0x6688e14f719766cc2a5856ccef63b069703d86f7\",\n    \"privateKey\": \"...\"\n  }\n]\n</code></pre> <p>Copy the address listed in the output from this command. Go to 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.</p> <p></p>"},{"location":"tutorials/chains/avalanche/#confirm-the-transaction-on-snowtrace","title":"Confirm the transaction on Snowtrace","text":"<p>You should be able to go lookup your account on Snowtrace for the Fuji testnet and see that you now have a balance of 2 AVAX. Simply paste in your account address or transaction ID to search for it.</p> <p></p>"},{"location":"tutorials/chains/avalanche/#use-the-public-testnet","title":"Use the public testnet","text":"<p>Now that you have everything set up, you can follow one of the other FireFly guides such as Using Tokens or Custom Smart Contracts. For detailed instructions on deploying a custom smart contract to Avalanche, please see the Avalanche docs for instructions using various tools.</p>"},{"location":"tutorials/chains/binance_smart_chain/","title":"Binance Smart Chain","text":"<p>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.</p>"},{"location":"tutorials/chains/binance_smart_chain/#previous-steps-install-the-firefly-cli","title":"Previous steps: Install the FireFly CLI","text":"<p>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.</p> <p>\u2190 \u2460 Install the FireFly CLI</p>"},{"location":"tutorials/chains/binance_smart_chain/#create-an-evmconnectyml-config-file","title":"Create an <code>evmconnect.yml</code> config file","text":"<p>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 <code>evmconnect.yml</code> with the following contents:</p> <pre><code>confirmations:\n  required: 4 # choose the number of confirmations you require\npolicyengine.simple:\n  fixedGasPrice: null\n  gasOracle:\n    mode: connector\n</code></pre> <p>For more info about <code>confirmations</code>, see Public vs. Permissioned</p> <p>For this tutorial, we will assume this file is saved at <code>~/Desktop/evmconnect.yml</code>. If your path is different, you will need to adjust the path in the next command below.</p>"},{"location":"tutorials/chains/binance_smart_chain/#creating-a-new-stack","title":"Creating a new stack","text":"<p>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:</p> <ul> <li>Create a new Ethereum based stack named <code>bsc</code> with <code>1</code> member</li> <li>Disable <code>multiparty</code> 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</li> <li>Use an remote RPC node. This will create a signer locally, so that our signing key never leaves the development machine.</li> <li>See the Binance BscScan docs and select an HTTPS RPC endpoint.</li> <li>Set the chain ID to <code>97</code> (the correct ID for the Binance Smart Chain testnet)</li> <li>Merge the custom config created above with the generated <code>evmconnect</code> config file</li> </ul> <p>To do this, run the following command:</p> <pre><code>ff init ethereum bsc 1 \\\n    --multiparty=false \\\n    -n remote-rpc \\\n    --remote-node-url &lt;selected RPC endpoint&gt; \\\n    --chain-id 97 \\\n    --connector-config ~/Desktop/evmconnect.yml\n</code></pre>"},{"location":"tutorials/chains/binance_smart_chain/#start-the-stack","title":"Start the stack","text":"<p>Now you should be able to start your stack by running:</p> <pre><code>ff start bsc\n</code></pre> <p>After some time it should print out the following:</p> <pre><code>Web UI for member '0': http://127.0.0.1:5000/ui\nSandbox UI for member '0': http://127.0.0.1:5109\n\n\nTo see logs for your stack run:\n\nff logs bsc\n</code></pre>"},{"location":"tutorials/chains/binance_smart_chain/#get-some-bnb","title":"Get some BNB","text":"<p>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.</p> <p>First, you will need to know what signing address your FireFly node is using. To check that, you can run:</p> <pre><code>ff accounts list bsc\n[\n  {\n    \"address\": \"0x235461d246ab95d367925b4e91bd2755a921fdd8\",\n    \"privateKey\": \"...\"\n  }\n]\n</code></pre> <p>Copy the address listed in the output from this command. Go to 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.</p> <p></p>"},{"location":"tutorials/chains/binance_smart_chain/#confirm-the-transaction-on-bscscan","title":"Confirm the transaction on Bscscan","text":"<p>You should be able to go lookup your account on Bscscan for the testnet 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.</p> <p></p>"},{"location":"tutorials/chains/binance_smart_chain/#use-the-public-testnet","title":"Use the public testnet","text":"<p>Now that you have everything set up, you can follow one of the other FireFly guides such as Using Tokens or Custom Smart Contracts. For detailed instructions on deploying a custom smart contract to Binance Smart Chain, please see the Binance docs for instructions using various tools.</p>"},{"location":"tutorials/chains/fabric_test_network/","title":"Work with Fabric-Samples Test Network","text":"<p>This guide will walk you through the steps to create a local FireFly development environment and connect it to the Fabric Test Network from the Fabric Samples repo</p>"},{"location":"tutorials/chains/fabric_test_network/#previous-steps-install-the-firefly-cli","title":"Previous steps: Install the FireFly CLI","text":"<p>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.</p> <p>\u2190 \u2460 Install the FireFly CLI</p>"},{"location":"tutorials/chains/fabric_test_network/#start-fabric-test-network-with-fabric-ca","title":"Start Fabric Test Network with Fabric CA","text":"<p>For details about the Fabric Test Network and how to set it up, please see the Fabric Samples repo. The one important detail is that you need to start up the Test Network with a Fabric CA. This is because Fabconnect will use the Fabric CA to create an identity for its FireFly node to use. To start up the network with the CA, and create a new channel called <code>mychannel</code> run:</p> <pre><code>./network.sh up createChannel -ca\n</code></pre> <p>NOTE: If you already have the Test Network running, you will need to bring it down first, by running: <code>./network.sh down</code></p>"},{"location":"tutorials/chains/fabric_test_network/#deploy-firefly-chaincode","title":"Deploy FireFly Chaincode","text":"<p>Next we will need to package and deploy the FireFly chaincode to <code>mychannel</code> in our new network. For more details on packaging and deploying chaincode, please see the Fabric chaincode lifecycle documentation. If you already have the FireFly repo cloned in the same directory as your <code>fabric-samples</code> repo, you can run the following script from your <code>test-network</code> directory:</p> <p>NOTE: This script is provided as a convenience only, and you are not required to use it. You are welcome to package and deploy the chaincode to your test-network any way you would like.</p> <pre><code>#!/bin/bash\n\n# This file should be run from the test-network directory in the fabric-samples repo\n# It also assumes that you have the firefly repo checked out at the same level as the fabric-samples directory\n# It also assumes that the test-network is up and running and a channel named 'mychannel' has already been created\n\ncd ../../firefly/smart_contracts/fabric/firefly-go\nGO111MODULE=on go mod vendor\ncd ../../../../fabric-samples/test-network\n\nexport PATH=${PWD}/../bin:$PATH\nexport FABRIC_CFG_PATH=$PWD/../config/\n\npeer lifecycle chaincode package firefly.tar.gz --path ../../firefly/smart_contracts/fabric/firefly-go --lang golang --label firefly_1.0\n\nexport CORE_PEER_TLS_ENABLED=true\nexport CORE_PEER_LOCALMSPID=\"Org1MSP\"\nexport CORE_PEER_TLS_ROOTCERT_FILE=${PWD}/organizations/peerOrganizations/org1.example.com/peers/peer0.org1.example.com/tls/ca.crt\nexport CORE_PEER_MSPCONFIGPATH=${PWD}/organizations/peerOrganizations/org1.example.com/users/Admin@org1.example.com/msp\nexport CORE_PEER_ADDRESS=localhost:7051\n\npeer lifecycle chaincode install firefly.tar.gz\n\nexport CORE_PEER_LOCALMSPID=\"Org2MSP\"\nexport CORE_PEER_TLS_ROOTCERT_FILE=${PWD}/organizations/peerOrganizations/org2.example.com/peers/peer0.org2.example.com/tls/ca.crt\nexport CORE_PEER_MSPCONFIGPATH=${PWD}/organizations/peerOrganizations/org2.example.com/users/Admin@org2.example.com/msp\nexport CORE_PEER_ADDRESS=localhost:9051\n\npeer lifecycle chaincode install firefly.tar.gz\n\nexport CC_PACKAGE_ID=$(peer lifecycle chaincode queryinstalled --output json | jq --raw-output \".installed_chaincodes[0].package_id\")\n\npeer lifecycle chaincode approveformyorg -o localhost:7050 --ordererTLSHostnameOverride orderer.example.com --channelID mychannel --name firefly --version 1.0 --package-id $CC_PACKAGE_ID --sequence 1 --tls --cafile \"${PWD}/organizations/ordererOrganizations/example.com/orderers/orderer.example.com/msp/tlscacerts/tlsca.example.com-cert.pem\"\n\nexport CORE_PEER_LOCALMSPID=\"Org1MSP\"\nexport CORE_PEER_MSPCONFIGPATH=${PWD}/organizations/peerOrganizations/org1.example.com/users/Admin@org1.example.com/msp\nexport CORE_PEER_TLS_ROOTCERT_FILE=${PWD}/organizations/peerOrganizations/org1.example.com/peers/peer0.org1.example.com/tls/ca.crt\nexport CORE_PEER_ADDRESS=localhost:7051\n\npeer lifecycle chaincode approveformyorg -o localhost:7050 --ordererTLSHostnameOverride orderer.example.com --channelID mychannel --name firefly --version 1.0 --package-id $CC_PACKAGE_ID --sequence 1 --tls --cafile \"${PWD}/organizations/ordererOrganizations/example.com/orderers/orderer.example.com/msp/tlscacerts/tlsca.example.com-cert.pem\"\n\npeer lifecycle chaincode commit -o localhost:7050 --ordererTLSHostnameOverride orderer.example.com --channelID mychannel --name firefly --version 1.0 --sequence 1 --tls --cafile \"${PWD}/organizations/ordererOrganizations/example.com/orderers/orderer.example.com/msp/tlscacerts/tlsca.example.com-cert.pem\" --peerAddresses localhost:7051 --tlsRootCertFiles \"${PWD}/organizations/peerOrganizations/org1.example.com/peers/peer0.org1.example.com/tls/ca.crt\" --peerAddresses localhost:9051 --tlsRootCertFiles \"${PWD}/organizations/peerOrganizations/org2.example.com/peers/peer0.org2.example.com/tls/ca.crt\"\n</code></pre>"},{"location":"tutorials/chains/fabric_test_network/#create-ccpyml-documents","title":"Create <code>ccp.yml</code> documents","text":"<p>Each FireFly Supernode (specifically the Fabconnect instance in each) will need to know how to connect to the Fabric network. Fabconnect will use a Fabric Connection Profile which describes the network and tells it where the certs and keys are that it needs. Below is a <code>ccp.yml</code> for each organization. You will need to fill in one line by replacing the string <code>FILL_IN_KEY_NAME_HERE</code>, because the file name of the private key for each user is randomly generated.</p>"},{"location":"tutorials/chains/fabric_test_network/#organization-1-connection-profile","title":"Organization 1 connection profile","text":"<p>Create a new file at <code>~/org1_ccp.yml</code> with the contents below. Replace the string <code>FILL_IN_KEY_NAME_HERE</code> with the filename in your <code>fabric-samples/test-network/organizations/peerOrganizations/org1.example.com/users/Admin@org1.example.com/msp/keystore</code> directory.</p> <pre><code>certificateAuthorities:\n  org1.example.com:\n    tlsCACerts:\n      path: /etc/firefly/organizations/peerOrganizations/org1.example.com/msp/tlscacerts/ca.crt\n    url: https://ca_org1:7054\n    grpcOptions:\n      ssl-target-name-override: org1.example.com\n    registrar:\n      enrollId: admin\n      enrollSecret: adminpw\nchannels:\n  mychannel:\n    orderers:\n      - fabric_orderer\n    peers:\n      fabric_peer:\n        chaincodeQuery: true\n        endorsingPeer: true\n        eventSource: true\n        ledgerQuery: true\nclient:\n  BCCSP:\n    security:\n      default:\n        provider: SW\n      enabled: true\n      hashAlgorithm: SHA2\n      level: 256\n      softVerify: true\n  credentialStore:\n    cryptoStore:\n      path: /etc/firefly/organizations/peerOrganizations/org1.example.com/msp\n    path: /etc/firefly/organizations/peerOrganizations/org1.example.com/msp\n  cryptoconfig:\n    path: /etc/firefly/organizations/peerOrganizations/org1.example.com/msp\n  logging:\n    level: info\n  organization: org1.example.com\n  tlsCerts:\n    client:\n      cert:\n        path: /etc/firefly/organizations/peerOrganizations/org1.example.com/users/Admin@org1.example.com/msp/signcerts/cert.pem\n      key:\n        path: /etc/firefly/organizations/peerOrganizations/org1.example.com/users/Admin@org1.example.com/msp/keystore/FILL_IN_KEY_NAME_HERE\norderers:\n  fabric_orderer:\n    tlsCACerts:\n      path: /etc/firefly/organizations/ordererOrganizations/example.com/orderers/orderer.example.com/tls/tlscacerts/tls-localhost-9054-ca-orderer.pem\n    url: grpcs://orderer.example.com:7050\norganizations:\n  org1.example.com:\n    certificateAuthorities:\n      - org1.example.com\n    cryptoPath: /tmp/msp\n    mspid: Org1MSP\n    peers:\n      - fabric_peer\npeers:\n  fabric_peer:\n    tlsCACerts:\n      path: /etc/firefly/organizations/peerOrganizations/org1.example.com/peers/peer0.org1.example.com/tls/tlscacerts/tls-localhost-7054-ca-org1.pem\n    url: grpcs://peer0.org1.example.com:7051\nversion: 1.1.0%\n</code></pre>"},{"location":"tutorials/chains/fabric_test_network/#organization-2-connection-profile","title":"Organization 2 connection profile","text":"<p>Create a new file at <code>~/org2_ccp.yml</code> with the contents below. Replace the string <code>FILL_IN_KEY_NAME_HERE</code> with the filename in your <code>fabric-samples/test-network/organizations/peerOrganizations/org2.example.com/users/Admin@org2.example.com/msp/keystore</code> directory.</p> <pre><code>certificateAuthorities:\n  org2.example.com:\n    tlsCACerts:\n      path: /etc/firefly/organizations/peerOrganizations/org2.example.com/msp/tlscacerts/ca.crt\n    url: https://ca_org2:8054\n    grpcOptions:\n      ssl-target-name-override: org2.example.com\n    registrar:\n      enrollId: admin\n      enrollSecret: adminpw\nchannels:\n  mychannel:\n    orderers:\n      - fabric_orderer\n    peers:\n      fabric_peer:\n        chaincodeQuery: true\n        endorsingPeer: true\n        eventSource: true\n        ledgerQuery: true\nclient:\n  BCCSP:\n    security:\n      default:\n        provider: SW\n      enabled: true\n      hashAlgorithm: SHA2\n      level: 256\n      softVerify: true\n  credentialStore:\n    cryptoStore:\n      path: /etc/firefly/organizations/peerOrganizations/org2.example.com/msp\n    path: /etc/firefly/organizations/peerOrganizations/org2.example.com/msp\n  cryptoconfig:\n    path: /etc/firefly/organizations/peerOrganizations/org2.example.com/msp\n  logging:\n    level: info\n  organization: org2.example.com\n  tlsCerts:\n    client:\n      cert:\n        path: /etc/firefly/organizations/peerOrganizations/org2.example.com/users/Admin@org2.example.com/msp/signcerts/cert.pem\n      key:\n        path: /etc/firefly/organizations/peerOrganizations/org2.example.com/users/Admin@org2.example.com/msp/keystore/FILL_IN_KEY_NAME_HERE\norderers:\n  fabric_orderer:\n    tlsCACerts:\n      path: /etc/firefly/organizations/ordererOrganizations/example.com/orderers/orderer.example.com/tls/tlscacerts/tls-localhost-9054-ca-orderer.pem\n    url: grpcs://orderer.example.com:7050\norganizations:\n  org2.example.com:\n    certificateAuthorities:\n      - org2.example.com\n    cryptoPath: /tmp/msp\n    mspid: Org2MSP\n    peers:\n      - fabric_peer\npeers:\n  fabric_peer:\n    tlsCACerts:\n      path: /etc/firefly/organizations/peerOrganizations/org2.example.com/peers/peer0.org2.example.com/tls/tlscacerts/tls-localhost-8054-ca-org2.pem\n    url: grpcs://peer0.org2.example.com:9051\nversion: 1.1.0%\n</code></pre>"},{"location":"tutorials/chains/fabric_test_network/#create-the-firefly-stack","title":"Create the FireFly stack","text":"<p>Now we can create a FireFly stack and pass in these files as command line flags.</p> <p>NOTE: The following command should be run in the <code>test-network</code> directory as it includes a relative path to the <code>organizations</code> directory containing each org's MSP.</p> <pre><code>ff init fabric dev \\\n  --ccp \"${HOME}/org1_ccp.yml\" \\\n  --msp \"organizations\" \\\n  --ccp \"${HOME}/org2_ccp.yml\" \\\n  --msp \"organizations\" \\\n  --channel mychannel \\\n  --chaincode firefly\n</code></pre>"},{"location":"tutorials/chains/fabric_test_network/#edit-docker-composeoverrideyml","title":"Edit <code>docker-compose.override.yml</code>","text":"<p>The last step before starting up FireFly is to make sure that our FireFly containers have networking access to the Fabric containers. Because these are in two different Docker Compose networks by default, normally the containers would not be able to connect directly. We can fix this by instructing Docker to also attach our FireFly containers to the Fabric test network Docker Compose network. The easiest way to do that is to edit <code>~/.firefly/stacks/dev/docker-compose.override.yml</code> and set its contents to the following:</p> <pre><code># Add custom config overrides here\n# See https://docs.docker.com/compose/extends\nversion: \"2.1\"\nnetworks:\n  default:\n    name: fabric_test\n    external: true\n</code></pre>"},{"location":"tutorials/chains/fabric_test_network/#start-firefly-stack","title":"Start FireFly stack","text":"<p>Now we can start up FireFly!</p> <pre><code>ff start dev\n</code></pre> <p>After everything starts up, you should have two FireFly nodes that are each mapped to an Organization in your Fabric network. You can that they each use separate signing keys for their Org on messages that each FireFly node sends.</p>"},{"location":"tutorials/chains/fabric_test_network/#connecting-to-a-remote-fabric-network","title":"Connecting to a remote Fabric Network","text":"<p>This same guide can be adapted to connect to a remote Fabric network running somewhere else. They key takeaways are:</p> <ul> <li>You need the FireFly chaincode deployed on channel in your Fabric network</li> <li>You need to pass the channel and chaincode name when you run <code>ff init</code></li> <li>You need to provide a connection profile and the correct certs, keys, etc. for each node when you run <code>ff init</code></li> <li>Your FireFly containers will need to have network access to your Fabric network</li> </ul>"},{"location":"tutorials/chains/fabric_test_network/#troubleshooting","title":"Troubleshooting","text":"<p>There are quite a few moving parts in this guide and if steps are missed or done out of order it can cause problems. Below are some of the common situations that you might run into while following this guide, and solutions for each.</p> <p>You may see a message something along the lines of:</p> <pre><code>ERROR: for firefly_core_0  Container \"bc04521372aa\" is unhealthy.\nEncountered errors while bringing up the project.\n</code></pre> <p>In this case, we need to look at the container logs to get more detail about what happened. To do this, we can run <code>ff start</code> and tell it not to clean up the stack after the failure, to let you inspect what went wrong. To do that, you can run:</p> <pre><code>ff start dev --verbose --no-rollback\n</code></pre> <p>Then we could run <code>docker logs &lt;container_name&gt;</code> to see the logs for that container.</p>"},{"location":"tutorials/chains/fabric_test_network/#no-such-host","title":"No such host","text":"<pre><code>Error: http://127.0.0.1:5102/identities [500] {\"error\":\"enroll failed: enroll failed: POST failure of request: POST https://ca_org1:7054/enroll\\n{\\\"hosts\\\":null,\\\"certificate_request\\\":\\\"-----BEGIN CERTIFICATE REQUEST-----\\\\nMIH0MIGcAgEAMBAxDjAMBgNVBAMTBWFkbWluMFkwEwYHKoZIzj0CAQYIKoZIzj0D\\\\nAQcDQgAE7qJZ5nGt/kxU9IvrEb7EmgNIgn9xXoQUJLl1+U9nXdWB9cnxcmoitnvy\\\\nYN63kbBuUh0z21vOmO8GLD3QxaRaD6AqMCgGCSqGSIb3DQEJDjEbMBkwFwYDVR0R\\\\nBBAwDoIMMGQ4NGJhZWIwZGY0MAoGCCqGSM49BAMCA0cAMEQCIBcWb127dVxm/80K\\\\nB2LtenAY/Jtb2FbZczolrXNCKq+LAiAcGEJ6Mx8LVaPzuSP4uGpEoty6+bEErc5r\\\\nHVER+0aXiQ==\\\\n-----END CERTIFICATE REQUEST-----\\\\n\\\",\\\"profile\\\":\\\"\\\",\\\"crl_override\\\":\\\"\\\",\\\"label\\\":\\\"\\\",\\\"NotBefore\\\":\\\"0001-01-01T00:00:00Z\\\",\\\"NotAfter\\\":\\\"0001-01-01T00:00:00Z\\\",\\\"ReturnPrecert\\\":false,\\\"CAName\\\":\\\"\\\"}: Post \\\"https://ca_org1:7054/enroll\\\": dial tcp: lookup ca_org1 on 127.0.0.11:53: no such host\"}\n</code></pre> <p>If you see something in your logs that looks like the above, there could be a couple issues:</p> <ol> <li>The hostname for one of your Fabric containers could be wrong in the <code>ccp.yml</code>. Check the <code>ccp.yml</code> for that member and make sure the hostnames are correct.</li> <li>The FireFly container doesn't have networking connectivity to the Fabric containers. Check the <code>docker-compose.override.yml</code> file to make sure you added the <code>fabric_test</code> network as instructed above.</li> </ol>"},{"location":"tutorials/chains/fabric_test_network/#no-such-file-or-directory","title":"No such file or directory","text":"<pre><code>User credentials store creation failed. Failed to load identity configurations: failed to create identity config from backends: failed to load client TLSConfig : failed to load client key: failed to load pem bytes from path /etc/firefly/organizations/peerOrganizations/org1.example.com/users/User1@org1.example.com/msp/keystore/cfc50311e2204f232cfdfaf4eba7731279f2366ec291ca1c1781e2bf7bc75529_sk: open /etc/firefly/organizations/peerOrganizations/org1.example.com/users/User1@org1.example.com/msp/keystore/cfc50311e2204f232cfdfaf4eba7731279f2366ec291ca1c1781e2bf7bc75529_sk: no such file or directory\n</code></pre> <p>If you see something in your logs that looks like the above, it's likely that your private key file name is not correct in your <code>ccp.yml</code> file for that particular member. Check your <code>ccp.yml</code> and make sure all the files listed there exist in your <code>organizations</code> directory.</p>"},{"location":"tutorials/chains/moonbeam/","title":"Moonbeam Testnet","text":"<p>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 Moonbeam Alpha testnet.</p>"},{"location":"tutorials/chains/moonbeam/#previous-steps-install-the-firefly-cli","title":"Previous steps: Install the FireFly CLI","text":"<p>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.</p> <p>\u2190 \u2460 Install the FireFly CLI</p>"},{"location":"tutorials/chains/moonbeam/#create-an-evmconnectyml-config-file","title":"Create an <code>evmconnect.yml</code> config file","text":"<p>In order to connect to the Moonbeam testnet, you will need to set a few configuration options for the evmconnect blockchain connector. Create a text file called <code>evmconnect.yml</code> with the following contents:</p> <pre><code>confirmations:\n  required: 4 # choose the number of confirmations you require\npolicyengine.simple:\n  fixedGasPrice: null\n  gasOracle:\n    mode: connector\n</code></pre> <p>For more info about <code>confirmations</code>, see Public vs. Permissioned</p> <p>For this tutorial, we will assume this file is saved at <code>~/Desktop/evmconnect.yml</code>. If your path is different, you will need to adjust the path in the next command below.</p>"},{"location":"tutorials/chains/moonbeam/#creating-a-new-stack","title":"Creating a new stack","text":"<p>To create a local FireFly development stack and connect it to the Moonbeam Alpha testnet, we will use command line flags to customize the following settings:</p> <ul> <li>Create a new Ethereum based stack named <code>moonbeam</code> with <code>1</code> member</li> <li>Disable <code>multiparty</code> 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</li> <li>Use an remote RPC node. This will create a signer locally, so that our signing key never leaves the development machine.</li> <li>See the moonbeam docs and select an HTTPS RPC endpoint</li> <li>Set the chain ID to <code>1287</code> (the correct ID for the Moonbeam Alpha testnet)</li> <li>Merge the custom config created above with the generated <code>evmconnect</code> config file</li> </ul> <p>To do this, run the following command:</p> <pre><code>ff init ethereum moonbeam 1 \\\n    --multiparty=false \\\n    -n remote-rpc \\\n    --remote-node-url &lt;selected RPC endpoint&gt; \\\n    --chain-id 1287 \\\n    --connector-config ~/Desktop/evmconnect.yml\n</code></pre>"},{"location":"tutorials/chains/moonbeam/#start-the-stack","title":"Start the stack","text":"<p>Now you should be able to start your stack by running:</p> <pre><code>ff start moonbeam\n</code></pre> <p>After some time it should print out the following:</p> <pre><code>Web UI for member '0': http://127.0.0.1:5000/ui\nSandbox UI for member '0': http://127.0.0.1:5109\n\n\nTo see logs for your stack run:\n\nff logs moonbeam\n</code></pre>"},{"location":"tutorials/chains/moonbeam/#get-some-dev","title":"Get some DEV","text":"<p>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 DEV, the native token for Moonbeam.</p> <p>First, you will need to know what signing address your FireFly node is using. To check that, you can run:</p> <pre><code>ff accounts list moonbeam\n[\n  {\n    \"address\": \"0x02d42c32a97c894486afbc7b717edff50c70b292\",\n    \"privateKey\": \"...\"\n  }\n]\n</code></pre> <p>Copy the address listed in the output from this command. Go to https://apps.moonbeam.network/moonbase-alpha/faucet/ and paste the address in the form. Click the Submit button.</p> <p></p>"},{"location":"tutorials/chains/moonbeam/#confirm-the-transaction-on-moonscan","title":"Confirm the transaction on Moonscan","text":"<p>You should be able to go lookup your account on Moonscan for the Moonbase Alpha testnet and see that you now have a sufficient balance of DEV. Simply paste in your account address to search for it.</p> <p></p>"},{"location":"tutorials/chains/moonbeam/#use-the-public-testnet","title":"Use the public testnet","text":"<p>Now that you have everything set up, you can follow one of the other FireFly guides such as Using Tokens or Custom Smart Contracts. For detailed instructions on interacting with the Moonbeam Alpha testnet, please see the Moonbeam docs.</p>"},{"location":"tutorials/chains/optimism/","title":"Optimism","text":"<p>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.</p>"},{"location":"tutorials/chains/optimism/#previous-steps-install-the-firefly-cli","title":"Previous steps: Install the FireFly CLI","text":"<p>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.</p> <p>\u2190 \u2460 Install the FireFly CLI</p>"},{"location":"tutorials/chains/optimism/#create-an-evmconnectyml-config-file","title":"Create an <code>evmconnect.yml</code> config file","text":"<p>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 <code>evmconnect.yml</code> with the following contents:</p> <pre><code>confirmations:\n  required: 4 # choose the number of confirmations you require\npolicyengine.simple:\n  fixedGasPrice: null\n  gasOracle:\n    mode: connector\n</code></pre> <p>For this tutorial, we will assume this file is saved at <code>~/Desktop/evmconnect.yml</code>. If your path is different, you will need to adjust the path in the next command below.</p>"},{"location":"tutorials/chains/optimism/#creating-a-new-stack","title":"Creating a new stack","text":"<p>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:</p> <ul> <li>Create a new Ethereum based stack named <code>optimism</code> with <code>1</code> member</li> <li>Disable <code>multiparty</code> 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</li> <li>Use an remote RPC node. This will create a signer locally, so that our signing key never leaves the development machine.</li> <li>See the optimism docs and select an HTTPS RPC endpoint.</li> <li>Set the chain ID to <code>420</code> (the correct ID for the Optimism testnet)</li> <li>Merge the custom config created above with the generated <code>evmconnect</code> config file</li> </ul> <p>To do this, run the following command:</p> <pre><code>ff init ethereum optimism 1 \\\n    --multiparty=false \\\n    -n remote-rpc \\\n    --remote-node-url &lt;selected RPC endpoint&gt; \\\n    --chain-id 420 \\\n    --connector-config ~/Desktop/evmconnect.yml\n</code></pre>"},{"location":"tutorials/chains/optimism/#start-the-stack","title":"Start the stack","text":"<p>Now you should be able to start your stack by running:</p> <pre><code>ff start optimism\n</code></pre> <p>After some time it should print out the following:</p> <pre><code>Web UI for member '0': http://127.0.0.1:5000/ui\nSandbox UI for member '0': http://127.0.0.1:5109\n\n\nTo see logs for your stack run:\n\nff logs optimism\n</code></pre>"},{"location":"tutorials/chains/optimism/#get-some-optimism","title":"Get some Optimism","text":"<p>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.</p> <p>First, you will need to know what signing address your FireFly node is using. To check that, you can run:</p> <pre><code>ff accounts list optimism\n[\n  {\n    \"address\": \"0x235461d246ab95d367925b4e91bd2755a921fdd8\",\n    \"privateKey\": \"...\"\n  }\n]\n</code></pre> <p>Copy the address listed in the output from this command. Go to https://optimismfaucet.xyz/. You will need to login to your Github account and paste the address in the form.</p> <p></p>"},{"location":"tutorials/chains/optimism/#confirm-the-transaction-on-blockcscout","title":"Confirm the transaction on Blockcscout","text":"<p>You should be able to go lookup your account on Blockscout for Optimism testnet 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.</p> <p></p>"},{"location":"tutorials/chains/optimism/#use-the-public-testnet","title":"Use the public testnet","text":"<p>Now that you have everything set up, you can follow one of the other FireFly guides such as Using Tokens or Custom Smart Contracts. For detailed instructions on deploying a custom smart contract to Optimism, please see the Optimism docs for instructions using various tools.</p>"},{"location":"tutorials/chains/polygon_testnet/","title":"Polygon Testnet","text":"<p>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.</p>"},{"location":"tutorials/chains/polygon_testnet/#previous-steps-install-the-firefly-cli","title":"Previous steps: Install the FireFly CLI","text":"<p>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.</p> <p>\u2190 \u2460 Install the FireFly CLI</p>"},{"location":"tutorials/chains/polygon_testnet/#create-an-evmconnectyml-config-file","title":"Create an <code>evmconnect.yml</code> config file","text":"<p>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 <code>evmconnect.yml</code> with the following contents:</p> <pre><code>confirmations:\n  required: 4 # choose the number of confirmations you require\npolicyengine.simple:\n  fixedGasPrice: null\n  gasOracle:\n    mode: connector\n</code></pre> <p>For more info about <code>confirmations</code>, see Public vs. Permissioned</p> <p>For this tutorial, we will assume this file is saved at <code>~/Desktop/evmconnect.yml</code>. If your path is different, you will need to adjust the path in the next command below.</p>"},{"location":"tutorials/chains/polygon_testnet/#creating-a-new-stack","title":"Creating a new stack","text":"<p>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:</p> <ul> <li>Create a new Ethereum based stack named <code>polygon</code> with <code>1</code> member</li> <li>Disable <code>multiparty</code> 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</li> <li>Use an remote RPC node. This will create a signer locally, so that our signing key never leaves the development machine.</li> <li>See the list of Polygon RPC endpoints and select an HTTPS RPC endpoint.</li> <li>Set the chain ID to <code>80001</code> (the correct ID for the Polygon Mumbai testnet)</li> <li>Merge the custom config created above with the generated <code>evmconnect</code> config file</li> </ul> <p>To do this, run the following command:</p> <pre><code>ff init ethereum polygon 1 \\\n    --multiparty=false \\\n    -n remote-rpc \\\n    --remote-node-url &lt;selected RPC endpoint&gt; \\\n    --chain-id 80001 \\\n    --connector-config ~/Desktop/evmconnect.yml\n</code></pre>"},{"location":"tutorials/chains/polygon_testnet/#start-the-stack","title":"Start the stack","text":"<p>Now you should be able to start your stack by running:</p> <pre><code>ff start polygon\n</code></pre> <p>After some time it should print out the following:</p> <pre><code>Web UI for member '0': http://127.0.0.1:5000/ui\nSandbox UI for member '0': http://127.0.0.1:5109\n\n\nTo see logs for your stack run:\n\nff logs polygon\n</code></pre>"},{"location":"tutorials/chains/polygon_testnet/#get-some-matic","title":"Get some MATIC","text":"<p>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.</p> <p>First, you will need to know what signing address your FireFly node is using. To check that, you can run:</p> <pre><code>ff accounts list polygon\n[\n  {\n    \"address\": \"0x02d42c32a97c894486afbc7b717edff50c70b292\",\n    \"privateKey\": \"...\"\n  }\n]\n</code></pre> <p>Copy the address listed in the output from this command. Go to https://faucet.polygon.technology/ and paste the address in the form. Click the Submit button, and then Confirm.</p> <p></p>"},{"location":"tutorials/chains/polygon_testnet/#confirm-the-transaction-on-polygonscan","title":"Confirm the transaction on Polygonscan","text":"<p>You should be able to go lookup your account on Polygonscan for the Mumbai testnet and see that you now have a balance of 0.2 MATIC. Simply paste in your account address to search for it.</p> <p>You can also click on the Internal Txns tab from you account page to see the actual transfer of the MATIC from the faucet.</p> <p></p>"},{"location":"tutorials/chains/polygon_testnet/#use-the-public-testnet","title":"Use the public testnet","text":"<p>Now that you have everything set up, you can follow one of the other FireFly guides such as Using Tokens or Custom Smart Contracts. For detailed instructions on deploying a custom smart contract to Polygon, please see the Polygon docs for instructions using various tools.</p>"},{"location":"tutorials/chains/tezos_testnet/","title":"Tezos Testnet","text":"<p>This guide will walk you through the steps to create a local FireFly development environment and connect it to the public Tezos Ghostnet testnet.</p>"},{"location":"tutorials/chains/tezos_testnet/#previous-steps-install-the-firefly-cli","title":"Previous steps: Install the FireFly CLI","text":"<p>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.</p> <p>\u2190 \u2460 Install the FireFly CLI</p>"},{"location":"tutorials/chains/tezos_testnet/#set-up-the-transaction-signing-service","title":"Set up the transaction signing service","text":"<p>Signatory service allows to work with many different key-management systems.\\ By default, FF uses local signing option.\\ However, it is also possible to configure the transaction signing service using key management systems such as: AWS/Google/Azure KMS, HCP Vault, etc.</p> <p>NOTE: The default option is not secure and is mainly used for development and demo purposes. Therefore, for the production, use the selected KMS.\\ The full list can be found here.</p>"},{"location":"tutorials/chains/tezos_testnet/#creating-a-new-stack","title":"Creating a new stack","text":"<p>To create a local FireFly development stack and connect it to the Tezos Ghostnet testnet, we will use command line flags to customize the following settings:</p> <ul> <li>Create a new Tezos based stack named <code>tezos</code> with <code>1</code> member</li> <li>Disable <code>multiparty</code> 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</li> <li>See the list of Tezos public RPC nodes and select an HTTPS RPC node.</li> </ul> <p>To do this, run the following command:</p> <pre><code>ff init tezos dev 1 \\\n    --multiparty=false \\\n    --remote-node-url &lt;selected RPC endpoint&gt;\n</code></pre> <p>NOTE: The public RPC nodes may have limitations or may not support all FF required RPC endpoints. Therefore it's not recommended to use ones for production and you may need to run own node or use third-party vendors.</p>"},{"location":"tutorials/chains/tezos_testnet/#start-the-stack","title":"Start the stack","text":"<p>Now you should be able to start your stack by running:</p> <pre><code>ff start dev\n</code></pre> <p>After some time it should print out the following:</p> <pre><code>Web UI for member '0': http://127.0.0.1:5000/ui\nSandbox UI for member '0': http://127.0.0.1:5109\n\n\nTo see logs for your stack run:\n\nff logs dev\n</code></pre>"},{"location":"tutorials/chains/tezos_testnet/#get-some-xtz","title":"Get some XTZ","text":"<p>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 transaction fee. A testnet faucet can give us some XTZ, the native token for Tezos.</p> <p>First, you need to get an account address, which was created during signer set up step.\\ To check that, you can run:</p> <pre><code>ff accounts list dev\n[\n  {\n    \"address\": \"tz1cuFw1E2Mn2bVS8q8d7QoCb6FXC18JivSp\",\n    \"privateKey\": \"...\"\n  }\n]\n</code></pre> <p>After that, go to Tezos Ghostnet Faucet and paste the address in the form and click the Request button.</p> <p></p>"},{"location":"tutorials/chains/tezos_testnet/#confirm-the-transaction-on-tzstats","title":"Confirm the transaction on TzStats","text":"<p>You should be able to go lookup your account on TzStats for the Ghostnet testnet and see that you now have a balance of 100 XTZ (or 2001 XTZ accordingly). Simply paste in your account address to search for it.</p> <p>On the Transfers tab from you account page you will see the actual transfer of the XTZ from the faucet.</p> <p></p>"},{"location":"tutorials/chains/tezos_testnet/#use-the-public-testnet","title":"Use the public testnet","text":"<p>Now that you have everything set up, you can follow one of the other FireFly guides such as Custom Smart Contracts. For detailed instructions on deploying a custom smart contract to Tezos, please see the Tezos docs for instructions using various tools.</p>"},{"location":"tutorials/chains/zksync_testnet/","title":"zkSync Testnet","text":"<p>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 zkSync testnet.</p>"},{"location":"tutorials/chains/zksync_testnet/#previous-steps-install-the-firefly-cli","title":"Previous steps: Install the FireFly CLI","text":"<p>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.</p> <p>\u2190 \u2460 Install the FireFly CLI</p>"},{"location":"tutorials/chains/zksync_testnet/#create-an-evmconnectyml-config-file","title":"Create an <code>evmconnect.yml</code> config file","text":"<p>In order to connect to the zkSync testnet, you will need to set a few configuration options for the evmconnect blockchain connector. Create a text file called <code>evmconnect.yml</code> with the following contents:</p> <pre><code>confirmations:\n  required: 4 # choose the number of confirmations you require\npolicyengine.simple:\n  fixedGasPrice: null\n  gasOracle:\n    mode: connector\n</code></pre> <p>For this tutorial, we will assume this file is saved at <code>~/Desktop/evmconnect.yml</code>. If your path is different, you will need to adjust the path in the next command below.</p>"},{"location":"tutorials/chains/zksync_testnet/#creating-a-new-stack","title":"Creating a new stack","text":"<p>To create a local FireFly development stack and connect it to the zkSync testnet, we will use command line flags to customize the following settings:</p> <ul> <li>Create a new stack named <code>zkSync</code> with <code>1</code> member</li> <li>Disable <code>multiparty</code> 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</li> <li>Connect to an ethereum network</li> <li>Use the <code>evmconnect</code> blockchain connector</li> <li>Use an remote RPC node. This will create a signer locally, so that our signing key never leaves the development machine.</li> <li>See the list of providers for zkSync docs. For this tutorial we will use <code>https://zksync2-testnet.zksync.dev</code></li> <li>Set the chain ID to <code>280</code> (the correct ID for the zkSync testnet)</li> <li>Merge the custom config created above with the generated <code>evmconnect</code> config file</li> </ul> <p>To do this, run the following command:</p> <pre><code>ff init zksync 1\\\n    --multiparty=false \\\n    -b ethereum \\\n    -c evmconnect \\\n    -n remote-rpc \\\n    --remote-node-url https://zksync2-testnet.zksync.dev\\\n    --chain-id 280 \\\n    --connector-config ~/Desktop/evmconnect.yml\n</code></pre>"},{"location":"tutorials/chains/zksync_testnet/#start-the-stack","title":"Start the stack","text":"<p>Now you should be able to start your stack by running:</p> <pre><code>ff start zksync\n</code></pre> <p>After some time it should print out the following:</p> <pre><code>Web UI for member '0': http://127.0.0.1:5000/ui\nSandbox UI for member '0': http://127.0.0.1:5109\n\n\nTo see logs for your stack run:\n\nff logs zksync\n</code></pre>"},{"location":"tutorials/chains/zksync_testnet/#get-some-eth","title":"Get some ETH","text":"<p>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. zkSync does not currently have its own native token and instead uses Ethereum for transaction. A testnet faucet can give us some ETH.</p> <p>First, you will need to know what signing address your FireFly node is using. To check that, you can run:</p> <pre><code>ff accounts list zkSync\n[\n  {\n    \"address\": \"0x8cf4fd38b2d56a905113d23b5a7131f0269d8611\",\n    \"privateKey\": \"...\"\n  }\n]\n</code></pre> <p>Copy your zkSync address and go to the Goerli Ethereum faucet and paste the address in the form. Click the Request Tokens button. Note that any Goerli Ethereum faucet will work.</p> <p></p>"},{"location":"tutorials/chains/zksync_testnet/#confirm-the-transaction-on-the-etherscan-explorer","title":"Confirm the transaction on the Etherscan Explorer","text":"<p>You should be able to go lookup your account at https://etherscan.io/ and see that you now have a balance of 0.025 ETH. Simply paste in your account address to search for it.</p> <p></p>"},{"location":"tutorials/chains/zksync_testnet/#use-the-public-testnet","title":"Use the public testnet","text":"<p>Now that you have everything set up, you can follow one of the other FireFly guides such as Using Tokens or Custom Smart Contracts. For detailed instructions on deploying a custom smart contract to zkSync, please see the zkSync docs for instructions using various tools.</p>"},{"location":"tutorials/custom_contracts/","title":"Work with custom smart contracts","text":""},{"location":"tutorials/custom_contracts/#quick-reference","title":"Quick reference","text":"<p>Almost all blockchain platforms offer the ability to execute smart contracts on-chain in order to manage states on the shared ledger. FireFly provides support to use RESTful APIs to interact with the smart contracts deployed in the target blockchains, and listening to events via websocket.</p> <p>FireFly's unified API creates a consistent application experience regardless of the specific underlying blockchain implementation. It also provides developer-friendly features like automatic OpenAPI Specification generation for smart contracts, plus a built-in Swagger UI.</p>"},{"location":"tutorials/custom_contracts/#key-concepts","title":"Key concepts","text":"<p>FireFly defines the following constructs to support custom smart contracts:</p>"},{"location":"tutorials/custom_contracts/#contract-interface","title":"Contract Interface","text":"<p>FireFly defines a common, blockchain agnostic way to describe smart contracts. This is referred to as a Contract Interface. A contract interface is written in the FireFly Interface (FFI) format. It is a simple JSON document that has a name, a namespace, a version, a list of methods, and a list of events.</p> <p>For more details, you can also have a look at the Reference page for the FireFly Interface Format.</p> <p>For blockchains that offer a DSL describing the smart contract interface, such as Ethereum's ABI (Application Binary Interface), FireFly offers an API to convert the DSL into the FFI format.</p> <p>NOTE: Contract interfaces are scoped to a namespace. Within a namespace each contract interface must have a unique name and version combination. The same name and version combination can exist in different namespaces simultaneously.</p>"},{"location":"tutorials/custom_contracts/#http-api","title":"HTTP API","text":"<p>Based on a Contract Interface, FireFly further defines an HTTP API for the smart contract, which is complete with an OpenAPI Specification and the Swagger UI. An HTTP API defines an <code>/invoke</code> root path to submit transactions, and a <code>/query</code> root path to send query requests to read the state back out.</p> <p>How the invoke vs. query requests get interpreted into the native blockchain requests are specific to the blockchain's connector. For instance, the Ethereum connector translates <code>/invoke</code> calls to <code>eth_sendTransaction</code> JSON-RPC requests, while <code>/query</code> calls are translated into <code>eth_call</code> JSON-RPC requests. On the other hand, the Fabric connector translates <code>/invoke</code> calls to the multiple requests required to submit a transaction to a Fabric channel (which first collects endorsements from peer nodes, and then sends the assembled transaction payload to an orderer, for details please refer to the Fabric documentation).</p>"},{"location":"tutorials/custom_contracts/#blockchain-event-listener","title":"Blockchain Event Listener","text":"<p>Regardless of a blockchain's specific design, transaction processing are always asynchronous. This means a transaction is submitted to the network, at which point the submitting client gets an acknowledgement that it has been accepted for further processing. The client then listens for notifications by the blockchain when the transaction gets committed to the blockchain's ledger.</p> <p>FireFly defines event listeners to allow the client application to specify the relevant blockchain events to keep track of. A client application can then receive the notifications from FireFly via an event subscription.</p>"},{"location":"tutorials/custom_contracts/#event-subscription","title":"Event Subscription","text":"<p>An event listener in FireFly tracks specific blockchain events, while an event subscription directs FireFly to send those events to the client application. Each subscription creates a stream of events that can be delivered to the client with various delivery options, ensuring an at-least-once delivery guarantee.</p> <p>This is exactly the same as listening for any other events from FireFly. For more details on how Subscriptions work in FireFly you can read the Getting Started guide to Listen for events.</p>"},{"location":"tutorials/custom_contracts/#custom-onchain-logic-async-programming-in-firefly","title":"Custom onchain logic async programming in FireFly","text":"<p>Like the rest of FireFly, custom onchain logic support are implemented with an asynchronous programming model. The key concepts here are:</p> <ul> <li>Transactions are submitted to FireFly and an ID is returned. This is the Operation ID.</li> <li>The transaction itself happens asynchronously from the HTTP request that initiated it</li> <li>Blockchain events emitted by the custom onchain logic (Ethereum smart contracts, Fabric chaincodes, Corda flows, etc.) will be stored in FireFly's database if FireFly has a Event Listener set up for that specific type of event. FireFly will also emit an event of type <code>blockchain_event_received</code> when this happens.</li> </ul> <p></p>"},{"location":"tutorials/custom_contracts/ethereum/","title":"Work with Ethereum smart contracts","text":"<p>This guide describes the steps to deploy a smart contract to an Ethereum blockchain and use FireFly to interact with it in order to submit transactions, query for states and listening for events.</p> <p>NOTE: This guide assumes that you are running a local FireFly stack with at least 2 members and an Ethereum blockchain created by the FireFly CLI. If you need help getting that set up, please see the Getting Started guide to Start your environment.</p>"},{"location":"tutorials/custom_contracts/ethereum/#example-smart-contract","title":"Example smart contract","text":"<p>For this tutorial, we will be using a well known, but slightly modified smart contract called <code>SimpleStorage</code>, and will be using this contract on an Ethereum blockchain. As the name implies, it's a very simple contract which stores an unsigned 256 bit integer, emits and event when the value is updated, and allows you to retrieve the current value.</p> <p>Here is the source for this contract:</p> <pre><code>// SPDX-License-Identifier: Apache-2.0\npragma solidity ^0.8.10;\n\n// Declares a new contract\ncontract SimpleStorage {\n    // Storage. Persists in between transactions\n    uint256 x;\n\n    // Allows the unsigned integer stored to be changed\n    function set(uint256 newValue) public {\n        x = newValue;\n        emit Changed(msg.sender, newValue);\n    }\n\n    // Returns the currently stored unsigned integer\n    function get() public view returns (uint256) {\n        return x;\n    }\n\n    event Changed(address indexed from, uint256 value);\n}\n</code></pre>"},{"location":"tutorials/custom_contracts/ethereum/#contract-deployment","title":"Contract deployment","text":"<p>If you need to deploy an Ethereum smart contract with a signing key that FireFly will use for submitting future transactions it is recommended to use FireFly's built in contract deployment API. This is useful in many cases. For example, you may want to deploy a token contract and have FireFly mint some tokens. Many token contracts only allow the contract deployer to mint, so the contract would need to be deployed with a FireFly signing key.</p> <p>You will need compile the contract yourself using solc or some other tool. After you have compiled the contract, look in the JSON output file for the fields to build the request below.</p>"},{"location":"tutorials/custom_contracts/ethereum/#request","title":"Request","text":"Field Description <code>key</code> The signing key to use to dpeloy the contract. If omitted, the namespaces's default signing key will be used. <code>contract</code> The compiled bytecode for your smart contract. It should be either a hex encded string or Base64. <code>definition</code> The full ABI JSON array from your compiled JSON file. Copy the entire value of the <code>abi</code> field from the <code>[</code> to the <code>]</code>. <code>input</code> An ordered list of constructor arguments. Some contracts may not require any (such as this example). <p><code>POST</code> <code>http://localhost:5000/api/v1/namespaces/default/contracts/deploy</code></p> <pre><code>{\n  \"contract\": \"608060405234801561001057600080fd5b5061019e806100206000396000f3fe608060405234801561001057600080fd5b50600436106100365760003560e01c806360fe47b11461003b5780636d4ce63c14610057575b600080fd5b61005560048036038101906100509190610111565b610075565b005b61005f6100cd565b60405161006c919061014d565b60405180910390f35b806000819055503373ffffffffffffffffffffffffffffffffffffffff167fb52dda022b6c1a1f40905a85f257f689aa5d69d850e49cf939d688fbe5af5946826040516100c2919061014d565b60405180910390a250565b60008054905090565b600080fd5b6000819050919050565b6100ee816100db565b81146100f957600080fd5b50565b60008135905061010b816100e5565b92915050565b600060208284031215610127576101266100d6565b5b6000610135848285016100fc565b91505092915050565b610147816100db565b82525050565b6000602082019050610162600083018461013e565b9291505056fea2646970667358221220e6cbd7725b98b234d07bc1823b60ac065b567c6645d15c8f8f6986e5fa5317c664736f6c634300080b0033\",\n  \"definition\": [\n    {\n      \"anonymous\": false,\n      \"inputs\": [\n        {\n          \"indexed\": true,\n          \"internalType\": \"address\",\n          \"name\": \"from\",\n          \"type\": \"address\"\n        },\n        {\n          \"indexed\": false,\n          \"internalType\": \"uint256\",\n          \"name\": \"value\",\n          \"type\": \"uint256\"\n        }\n      ],\n      \"name\": \"Changed\",\n      \"type\": \"event\"\n    },\n    {\n      \"inputs\": [],\n      \"name\": \"get\",\n      \"outputs\": [\n        {\n          \"internalType\": \"uint256\",\n          \"name\": \"\",\n          \"type\": \"uint256\"\n        }\n      ],\n      \"stateMutability\": \"view\",\n      \"type\": \"function\"\n    },\n    {\n      \"inputs\": [\n        {\n          \"internalType\": \"uint256\",\n          \"name\": \"newValue\",\n          \"type\": \"uint256\"\n        }\n      ],\n      \"name\": \"set\",\n      \"outputs\": [],\n      \"stateMutability\": \"nonpayable\",\n      \"type\": \"function\"\n    }\n  ],\n  \"input\": []\n}\n</code></pre>"},{"location":"tutorials/custom_contracts/ethereum/#response","title":"Response","text":"<pre><code>{\n  \"id\": \"aa155a3c-2591-410e-bc9d-68ae7de34689\",\n  \"namespace\": \"default\",\n  \"tx\": \"4712ffb3-cc1a-4a91-aef2-206ac068ba6f\",\n  \"type\": \"blockchain_deploy\",\n  \"status\": \"Succeeded\",\n  \"plugin\": \"ethereum\",\n  \"input\": {\n    \"contract\": \"608060405234801561001057600080fd5b5061019e806100206000396000f3fe608060405234801561001057600080fd5b50600436106100365760003560e01c806360fe47b11461003b5780636d4ce63c14610057575b600080fd5b61005560048036038101906100509190610111565b610075565b005b61005f6100cd565b60405161006c919061014d565b60405180910390f35b806000819055503373ffffffffffffffffffffffffffffffffffffffff167fb52dda022b6c1a1f40905a85f257f689aa5d69d850e49cf939d688fbe5af5946826040516100c2919061014d565b60405180910390a250565b60008054905090565b600080fd5b6000819050919050565b6100ee816100db565b81146100f957600080fd5b50565b60008135905061010b816100e5565b92915050565b600060208284031215610127576101266100d6565b5b6000610135848285016100fc565b91505092915050565b610147816100db565b82525050565b6000602082019050610162600083018461013e565b9291505056fea2646970667358221220e6cbd7725b98b234d07bc1823b60ac065b567c6645d15c8f8f6986e5fa5317c664736f6c634300080b0033\",\n    \"definition\": [\n      {\n        \"anonymous\": false,\n        \"inputs\": [\n          {\n            \"indexed\": true,\n            \"internalType\": \"address\",\n            \"name\": \"from\",\n            \"type\": \"address\"\n          },\n          {\n            \"indexed\": false,\n            \"internalType\": \"uint256\",\n            \"name\": \"value\",\n            \"type\": \"uint256\"\n          }\n        ],\n        \"name\": \"Changed\",\n        \"type\": \"event\"\n      },\n      {\n        \"inputs\": [],\n        \"name\": \"get\",\n        \"outputs\": [\n          {\n            \"internalType\": \"uint256\",\n            \"name\": \"\",\n            \"type\": \"uint256\"\n          }\n        ],\n        \"stateMutability\": \"view\",\n        \"type\": \"function\"\n      },\n      {\n        \"inputs\": [\n          {\n            \"internalType\": \"uint256\",\n            \"name\": \"newValue\",\n            \"type\": \"uint256\"\n          }\n        ],\n        \"name\": \"set\",\n        \"outputs\": [],\n        \"stateMutability\": \"nonpayable\",\n        \"type\": \"function\"\n      }\n    ],\n    \"input\": [],\n    \"key\": \"0xddd93a452bfc8d3e62bbc60c243046e4d0cb971b\",\n    \"options\": null\n  },\n  \"output\": {\n    \"headers\": {\n      \"requestId\": \"default:aa155a3c-2591-410e-bc9d-68ae7de34689\",\n      \"type\": \"TransactionSuccess\"\n    },\n    \"contractLocation\": {\n      \"address\": \"0xa5ea5d0a6b2eaf194716f0cc73981939dca26da1\"\n    },\n    \"protocolId\": \"000000000024/000000\",\n    \"transactionHash\": \"0x32d1144091877266d7f0426e48db157e7d1a857c62e6f488319bb09243f0f851\"\n  },\n  \"created\": \"2023-02-03T15:42:52.750277Z\",\n  \"updated\": \"2023-02-03T15:42:52.750277Z\"\n}\n</code></pre> <p>Here we can see in the response above under the <code>output</code> section that our new contract address is <code>0xa5ea5d0a6b2eaf194716f0cc73981939dca26da1</code>. This is the address that we will reference in the rest of this guide.</p>"},{"location":"tutorials/custom_contracts/ethereum/#the-firefly-interface-format","title":"The FireFly Interface Format","text":"<p>If you have an Ethereum ABI for an existing smart contract, there is an HTTP endpoint on the FireFly API that will take the ABI as input and automatically generate the FireFly Interface for you. Rather than handcrafting our FFI, we'll let FireFly generate it for us using that endpoint now.</p>"},{"location":"tutorials/custom_contracts/ethereum/#request_1","title":"Request","text":"<p>Here we will take the JSON ABI generated by <code>truffle</code> or <code>solc</code> and <code>POST</code> that to FireFly to have it automatically generate the FireFly Interface for us. Copy the <code>abi</code> from the compiled JSON file, and put that inside an <code>input</code> object like the example below:</p> <p><code>POST</code> <code>http://localhost:5000/api/v1/namespaces/default/contracts/interfaces/generate</code></p> <pre><code>{\n  \"input\": {\n    \"abi\": [\n      {\n        \"anonymous\": false,\n        \"inputs\": [\n          {\n            \"indexed\": true,\n            \"internalType\": \"address\",\n            \"name\": \"from\",\n            \"type\": \"address\"\n          },\n          {\n            \"indexed\": false,\n            \"internalType\": \"uint256\",\n            \"name\": \"value\",\n            \"type\": \"uint256\"\n          }\n        ],\n        \"name\": \"Changed\",\n        \"type\": \"event\"\n      },\n      {\n        \"inputs\": [],\n        \"name\": \"get\",\n        \"outputs\": [\n          {\n            \"internalType\": \"uint256\",\n            \"name\": \"\",\n            \"type\": \"uint256\"\n          }\n        ],\n        \"stateMutability\": \"view\",\n        \"type\": \"function\"\n      },\n      {\n        \"inputs\": [\n          {\n            \"internalType\": \"uint256\",\n            \"name\": \"newValue\",\n            \"type\": \"uint256\"\n          }\n        ],\n        \"name\": \"set\",\n        \"outputs\": [],\n        \"stateMutability\": \"nonpayable\",\n        \"type\": \"function\"\n      }\n    ]\n  }\n}\n</code></pre>"},{"location":"tutorials/custom_contracts/ethereum/#response_1","title":"Response","text":"<p>FireFly generates and returns the the full FireFly Interface for the SimpleStorage contract in the response body:</p> <pre><code>{\n  \"namespace\": \"default\",\n  \"name\": \"\",\n  \"description\": \"\",\n  \"version\": \"\",\n  \"methods\": [\n    {\n      \"name\": \"get\",\n      \"pathname\": \"\",\n      \"description\": \"\",\n      \"params\": [],\n      \"returns\": [\n        {\n          \"name\": \"\",\n          \"schema\": {\n            \"type\": \"integer\",\n            \"details\": {\n              \"type\": \"uint256\",\n              \"internalType\": \"uint256\"\n            }\n          }\n        }\n      ]\n    },\n    {\n      \"name\": \"set\",\n      \"pathname\": \"\",\n      \"description\": \"\",\n      \"params\": [\n        {\n          \"name\": \"newValue\",\n          \"schema\": {\n            \"type\": \"integer\",\n            \"details\": {\n              \"type\": \"uint256\",\n              \"internalType\": \"uint256\"\n            }\n          }\n        }\n      ],\n      \"returns\": []\n    }\n  ],\n  \"events\": [\n    {\n      \"name\": \"Changed\",\n      \"description\": \"\",\n      \"params\": [\n        {\n          \"name\": \"from\",\n          \"schema\": {\n            \"type\": \"string\",\n            \"details\": {\n              \"type\": \"address\",\n              \"internalType\": \"address\",\n              \"indexed\": true\n            }\n          }\n        },\n        {\n          \"name\": \"value\",\n          \"schema\": {\n            \"type\": \"integer\",\n            \"details\": {\n              \"type\": \"uint256\",\n              \"internalType\": \"uint256\"\n            }\n          }\n        }\n      ]\n    }\n  ]\n}\n</code></pre>"},{"location":"tutorials/custom_contracts/ethereum/#broadcast-the-contract-interface","title":"Broadcast the contract interface","text":"<p>Now that we have a FireFly Interface representation of our smart contract, we want to broadcast that to the entire network. This broadcast will be pinned to the blockchain, so we can always refer to this specific name and version, and everyone in the network will know exactly which contract interface we are talking about.</p> <p>We will take the output from the previous HTTP response above, fill in the name and version and then <code>POST</code> that to the <code>/contracts/interfaces</code> API endpoint.</p>"},{"location":"tutorials/custom_contracts/ethereum/#request_2","title":"Request","text":"<p><code>POST</code> <code>http://localhost:5000/api/v1/namespaces/default/contracts/interfaces?publish=true</code></p> <p>NOTE: Without passing the query parameter <code>publish=true</code> when the interface is created, it will initially be unpublished and not broadcasted to other members of the network (if configured in multi-party). To publish the interface, a subsequent API call would need to be made to <code>/contracts/interfaces/{name}/{version}/publish</code></p> <pre><code>{\n  \"namespace\": \"default\",\n  \"name\": \"SimpleStorage\",\n  \"version\": \"v1.0.0\",\n  \"description\": \"\",\n  \"methods\": [\n    {\n      \"name\": \"get\",\n      \"pathname\": \"\",\n      \"description\": \"\",\n      \"params\": [],\n      \"returns\": [\n        {\n          \"name\": \"\",\n          \"schema\": {\n            \"type\": \"integer\",\n            \"details\": {\n              \"type\": \"uint256\",\n              \"internalType\": \"uint256\"\n            }\n          }\n        }\n      ]\n    },\n    {\n      \"name\": \"set\",\n      \"pathname\": \"\",\n      \"description\": \"\",\n      \"params\": [\n        {\n          \"name\": \"newValue\",\n          \"schema\": {\n            \"type\": \"integer\",\n            \"details\": {\n              \"type\": \"uint256\",\n              \"internalType\": \"uint256\"\n            }\n          }\n        }\n      ],\n      \"returns\": []\n    }\n  ],\n  \"events\": [\n    {\n      \"name\": \"Changed\",\n      \"description\": \"\",\n      \"params\": [\n        {\n          \"name\": \"from\",\n          \"schema\": {\n            \"type\": \"string\",\n            \"details\": {\n              \"type\": \"address\",\n              \"internalType\": \"address\",\n              \"indexed\": true\n            }\n          }\n        },\n        {\n          \"name\": \"value\",\n          \"schema\": {\n            \"type\": \"integer\",\n            \"details\": {\n              \"type\": \"uint256\",\n              \"internalType\": \"uint256\"\n            }\n          }\n        }\n      ]\n    }\n  ]\n}\n</code></pre>"},{"location":"tutorials/custom_contracts/ethereum/#response_2","title":"Response","text":"<pre><code>{\n  \"id\": \"8bdd27a5-67c1-4960-8d1e-7aa31b9084d3\",\n  \"message\": \"3cd0dde2-1e39-4c9e-a4a1-569e87cca93a\",\n  \"namespace\": \"default\",\n  \"name\": \"SimpleStorage\",\n  \"description\": \"\",\n  \"version\": \"v1.0.0\",\n  \"methods\": [\n    {\n      \"id\": \"56467890-5713-4463-84b8-4537fcb63d8b\",\n      \"contract\": \"8bdd27a5-67c1-4960-8d1e-7aa31b9084d3\",\n      \"name\": \"get\",\n      \"namespace\": \"default\",\n      \"pathname\": \"get\",\n      \"description\": \"\",\n      \"params\": [],\n      \"returns\": [\n        {\n          \"name\": \"\",\n          \"schema\": {\n            \"type\": \"integer\",\n            \"details\": {\n              \"type\": \"uint256\",\n              \"internalType\": \"uint256\"\n            }\n          }\n        }\n      ]\n    },\n    {\n      \"id\": \"6b254d1d-5f5f-491e-bbd2-201e96892e1a\",\n      \"contract\": \"8bdd27a5-67c1-4960-8d1e-7aa31b9084d3\",\n      \"name\": \"set\",\n      \"namespace\": \"default\",\n      \"pathname\": \"set\",\n      \"description\": \"\",\n      \"params\": [\n        {\n          \"name\": \"newValue\",\n          \"schema\": {\n            \"type\": \"integer\",\n            \"details\": {\n              \"type\": \"uint256\",\n              \"internalType\": \"uint256\"\n            }\n          }\n        }\n      ],\n      \"returns\": []\n    }\n  ],\n  \"events\": [\n    {\n      \"id\": \"aa1fe67b-b2ac-41af-a7e7-7ad54a30a78d\",\n      \"contract\": \"8bdd27a5-67c1-4960-8d1e-7aa31b9084d3\",\n      \"namespace\": \"default\",\n      \"pathname\": \"Changed\",\n      \"name\": \"Changed\",\n      \"description\": \"\",\n      \"params\": [\n        {\n          \"name\": \"from\",\n          \"schema\": {\n            \"type\": \"string\",\n            \"details\": {\n              \"type\": \"address\",\n              \"internalType\": \"address\",\n              \"indexed\": true\n            }\n          }\n        },\n        {\n          \"name\": \"value\",\n          \"schema\": {\n            \"type\": \"integer\",\n            \"details\": {\n              \"type\": \"uint256\",\n              \"internalType\": \"uint256\"\n            }\n          }\n        }\n      ]\n    }\n  ],\n  \"published\": true\n}\n</code></pre>"},{"location":"tutorials/custom_contracts/ethereum/#create-an-http-api-for-the-contract","title":"Create an HTTP API for the contract","text":"<p>Now comes the fun part where we see some of the powerful, developer-friendly features of FireFly. The next thing we're going to do is tell FireFly to build an HTTP API for this smart contract, complete with an OpenAPI Specification and Swagger UI. As part of this, we'll also tell FireFly where the contract is on the blockchain. Like the interface broadcast above, this will also generate a broadcast which will be pinned to the blockchain so all the members of the network will be aware of and able to interact with this API.</p> <p>We need to copy the <code>id</code> field we got in the response from the previous step to the <code>interface.id</code> field in the request body below. We will also pick a name that will be part of the URL for our HTTP API, so be sure to pick a name that is URL friendly. In this case we'll call it <code>simple-storage</code>. Lastly, in the <code>location.address</code> field, we're telling FireFly where an instance of the contract is deployed on-chain.</p> <p>NOTE: The <code>location</code> field is optional here, but if it is omitted, it will be required in every request to invoke or query the contract. This can be useful if you have multiple instances of the same contract deployed to different addresses.</p>"},{"location":"tutorials/custom_contracts/ethereum/#request_3","title":"Request","text":"<p><code>POST</code> <code>http://localhost:5000/api/v1/namespaces/default/apis?publish=true</code></p> <p>NOTE: Without passing the query parameter <code>publish=true</code> when the API is created, it will initially be unpublished and not broadcasted to other members of the network (if configured in multi-party). To publish the API, a subsequent API call would need to be made to <code>/apis/{apiName}/publish</code></p> <pre><code>{\n  \"name\": \"simple-storage\",\n  \"interface\": {\n    \"id\": \"8bdd27a5-67c1-4960-8d1e-7aa31b9084d3\"\n  },\n  \"location\": {\n    \"address\": \"0xa5ea5d0a6b2eaf194716f0cc73981939dca26da1\"\n  }\n}\n</code></pre>"},{"location":"tutorials/custom_contracts/ethereum/#response_3","title":"Response","text":"<pre><code>{\n  \"id\": \"9a681ec6-1dee-42a0-b91b-61d23a814b0f\",\n  \"namespace\": \"default\",\n  \"interface\": {\n    \"id\": \"8bdd27a5-67c1-4960-8d1e-7aa31b9084d3\"\n  },\n  \"location\": {\n    \"address\": \"0xa5ea5d0a6b2eaf194716f0cc73981939dca26da1\"\n  },\n  \"name\": \"simple-storage\",\n  \"message\": \"d90d0386-8874-43fb-b7d3-485c22f35f47\",\n  \"urls\": {\n    \"openapi\": \"http://127.0.0.1:5000/api/v1/namespaces/default/apis/simple-storage/api/swagger.json\",\n    \"ui\": \"http://127.0.0.1:5000/api/v1/namespaces/default/apis/simple-storage/api\"\n  },\n  \"published\": true\n}\n</code></pre>"},{"location":"tutorials/custom_contracts/ethereum/#view-openapi-spec-for-the-contract","title":"View OpenAPI spec for the contract","text":"<p>You'll notice in the response body that there are a couple of URLs near the bottom. If you navigate to the one labeled <code>ui</code> in your browser, you should see the Swagger UI for your smart contract.</p> <p></p>"},{"location":"tutorials/custom_contracts/ethereum/#invoke-the-smart-contract","title":"Invoke the smart contract","text":"<p>Now that we've got everything set up, it's time to use our smart contract! We're going to make a <code>POST</code> request to the <code>invoke/set</code> endpoint to set the integer value on-chain. Let's set it to the value of <code>3</code> right now.</p>"},{"location":"tutorials/custom_contracts/ethereum/#request_4","title":"Request","text":"<p><code>POST</code> <code>http://localhost:5000/api/v1/namespaces/default/apis/simple-storage/invoke/set</code></p> <pre><code>{\n  \"input\": {\n    \"newValue\": 3\n  }\n}\n</code></pre>"},{"location":"tutorials/custom_contracts/ethereum/#response_4","title":"Response","text":"<pre><code>{\n  \"id\": \"41c67c63-52cf-47ce-8a59-895fe2ffdc86\"\n}\n</code></pre> <p>You'll notice that we just get an ID back here, and that's expected due to the asynchronous programming model of working with smart contracts in FireFly. To see what the value is now, we can query the smart contract. In a little bit, we'll also subscribe to the events emitted by this contract so we can know when the value is updated in realtime.</p>"},{"location":"tutorials/custom_contracts/ethereum/#query-the-current-value","title":"Query the current value","text":"<p>To make a read-only request to the blockchain to check the current value of the stored integer, we can make a <code>POST</code> to the <code>query/get</code> endpoint.</p>"},{"location":"tutorials/custom_contracts/ethereum/#request_5","title":"Request","text":"<p><code>POST</code> <code>http://localhost:5000/api/v1/namespaces/default/apis/simple-storage/query/get</code></p> <pre><code>{}\n</code></pre>"},{"location":"tutorials/custom_contracts/ethereum/#response_5","title":"Response","text":"<pre><code>{\n  \"output\": \"3\"\n}\n</code></pre> <p>NOTE: Some contracts may have queries that require input parameters. That's why the query endpoint is a <code>POST</code>, rather than a <code>GET</code> so that parameters can be passed as JSON in the request body. This particular function does not have any parameters, so we just pass an empty JSON object.</p>"},{"location":"tutorials/custom_contracts/ethereum/#passing-additional-options-with-a-request","title":"Passing additional options with a request","text":"<p>Some smart contract functions may accept or require additional options to be passed with the request. For example, a Solidity function might be <code>payable</code>, meaning that a <code>value</code> field must be specified, indicating an amount of ETH to be transferred with the request. Each of your smart contract API's <code>/invoke</code> or <code>/query</code> endpoints support an <code>options</code> object in addition to the <code>input</code> arguments for the function itself.</p> <p>Here is an example of sending 100 wei with a transaction:</p>"},{"location":"tutorials/custom_contracts/ethereum/#request_6","title":"Request","text":"<p><code>POST</code> <code>http://localhost:5000/api/v1/namespaces/default/apis/simple-storage/invoke/set</code></p> <pre><code>{\n  \"input\": {\n    \"newValue\": 3\n  },\n  \"options\": {\n    \"value\": 100\n  }\n}\n</code></pre>"},{"location":"tutorials/custom_contracts/ethereum/#response_6","title":"Response","text":"<pre><code>{\n  \"id\": \"41c67c63-52cf-47ce-8a59-895fe2ffdc86\"\n}\n</code></pre>"},{"location":"tutorials/custom_contracts/ethereum/#create-a-blockchain-event-listener","title":"Create a blockchain event listener","text":"<p>Now that we've seen how to submit transactions and preform read-only queries to the blockchain, let's look at how to receive blockchain events so we know when things are happening in realtime.</p> <p>If you look at the source code for the smart contract we're working with above, you'll notice that it emits an event when the stored value of the integer is set. In order to receive these events, we first need to instruct FireFly to listen for this specific type of blockchain event. To do this, we create an Event Listener. The <code>/contracts/listeners</code> endpoint is RESTful so there are <code>POST</code>, <code>GET</code>, and <code>DELETE</code> methods available on it. To create a new listener, we will make a <code>POST</code> request. We are going to tell FireFly to listen to events with name <code>\"Changed\"</code> from the FireFly Interface we defined earlier, referenced by its ID. We will also tell FireFly which contract address we expect to emit these events, and the topic to assign these events to. You can specify multiple filters for a listener, in this case we only specify one for our event. Topics are a way for applications to subscribe to events they are interested in.</p>"},{"location":"tutorials/custom_contracts/ethereum/#request_7","title":"Request","text":"<p><code>POST</code> <code>http://localhost:5000/api/v1/namespaces/default/contracts/listeners</code></p> <pre><code>{\n  \"filters\": [\n    {\n      \"interface\": {\n        \"id\": \"8bdd27a5-67c1-4960-8d1e-7aa31b9084d3\"\n      },\n      \"location\": {\n        \"address\": \"0xa5ea5d0a6b2eaf194716f0cc73981939dca26da1\"\n      },\n      \"eventPath\": \"Changed\"\n    }\n  ],\n  \"options\": {\n    \"firstEvent\": \"newest\"\n  },\n  \"topic\": \"simple-storage\"\n}\n</code></pre>"},{"location":"tutorials/custom_contracts/ethereum/#response_7","title":"Response","text":"<pre><code>{\n  \"id\": \"e7c8457f-4ffd-42eb-ac11-4ad8aed30de1\",\n  \"interface\": {\n    \"id\": \"55fdb62a-fefc-4313-99e4-e3f95fcca5f0\"\n  },\n  \"namespace\": \"default\",\n  \"name\": \"019104d7-bb0a-c008-76a9-8cb923d91b37\",\n  \"backendId\": \"019104d7-bb0a-c008-76a9-8cb923d91b37\",\n  \"location\": {\n    \"address\": \"0xa5ea5d0a6b2eaf194716f0cc73981939dca26da1\"\n  },\n  \"created\": \"2024-07-30T18:12:12.704964Z\",\n  \"event\": {\n    \"name\": \"Changed\",\n    \"description\": \"\",\n    \"params\": [\n      {\n        \"name\": \"from\",\n        \"schema\": {\n          \"type\": \"string\",\n          \"details\": {\n            \"type\": \"address\",\n            \"internalType\": \"address\",\n            \"indexed\": true\n          }\n        }\n      },\n      {\n        \"name\": \"value\",\n        \"schema\": {\n          \"type\": \"integer\",\n          \"details\": {\n            \"type\": \"uint256\",\n            \"internalType\": \"uint256\"\n          }\n        }\n      }\n    ]\n  },\n  \"signature\": \"0xa5ea5d0a6b2eaf194716f0cc73981939dca26da1:Changed(address,uint256) [i=0]\",\n  \"topic\": \"simple-storage\",\n  \"options\": {\n    \"firstEvent\": \"newest\"\n  },\n  \"filters\": [\n    {\n      \"event\": {\n        \"name\": \"Changed\",\n        \"description\": \"\",\n        \"params\": [\n          {\n            \"name\": \"from\",\n            \"schema\": {\n              \"type\": \"string\",\n              \"details\": {\n                \"type\": \"address\",\n                \"internalType\": \"address\",\n                \"indexed\": true\n              }\n            }\n          },\n          {\n            \"name\": \"value\",\n            \"schema\": {\n              \"type\": \"integer\",\n              \"details\": {\n                \"type\": \"uint256\",\n                \"internalType\": \"uint256\"\n              }\n            }\n          }\n        ]\n      },\n      \"location\": {\n        \"address\": \"0xa5ea5d0a6b2eaf194716f0cc73981939dca26da1\"\n      },\n      \"interface\": {\n        \"id\": \"55fdb62a-fefc-4313-99e4-e3f95fcca5f0\"\n      },\n      \"signature\": \"0xa5ea5d0a6b2eaf194716f0cc73981939dca26da1:Changed(address,uint256) [i=0]\"\n    }\n  ]\n}\n</code></pre> <p>We can see in the response, that FireFly pulls all the schema information from the FireFly Interface that we broadcasted earlier and creates the listener with that schema. This is useful so that we don't have to enter all of that data again.</p>"},{"location":"tutorials/custom_contracts/ethereum/#querying-listener-status","title":"Querying listener status","text":"<p>If you are interested in learning about the current state of a listener you have created, you can query with the <code>fetchstatus</code> parameter. For FireFly stacks with an EVM compatible blockchain connector, the response will include checkpoint information and if the listener is currently in catchup mode.</p>"},{"location":"tutorials/custom_contracts/ethereum/#request-response","title":"Request / Response","text":"<p><code>GET</code> <code>http://localhost:5000/api/v1/namespaces/default/contracts/listeners/1bfa3b0f-3d90-403e-94a4-af978d8c5b14?fetchstatus</code></p> <pre><code>{\n  \"id\": \"1bfa3b0f-3d90-403e-94a4-af978d8c5b14\",\n  \"interface\": {\n    \"id\": \"8bdd27a5-67c1-4960-8d1e-7aa31b9084d3\"\n  },\n  \"namespace\": \"default\",\n  \"name\": \"sb-66209ffc-d355-4ac0-7151-bc82490ca9df\",\n  \"protocolId\": \"sb-66209ffc-d355-4ac0-7151-bc82490ca9df\",\n  \"location\": {\n    \"address\": \"0xa5ea5d0a6b2eaf194716f0cc73981939dca26da1\"\n  },\n  \"created\": \"2022-02-17T22:02:36.34549538Z\",\n  \"event\": {\n    \"name\": \"Changed\",\n    \"description\": \"\",\n    \"params\": [\n      {\n        \"name\": \"from\",\n        \"schema\": {\n          \"type\": \"string\",\n          \"details\": {\n            \"type\": \"address\",\n            \"internalType\": \"address\",\n            \"indexed\": true\n          }\n        }\n      },\n      {\n        \"name\": \"value\",\n        \"schema\": {\n          \"type\": \"integer\",\n          \"details\": {\n            \"type\": \"uint256\",\n            \"internalType\": \"uint256\"\n          }\n        }\n      }\n    ]\n  },\n  \"status\": {\n    \"checkpoint\": {\n      \"block\": 0,\n      \"transactionIndex\": -1,\n      \"logIndex\": -1\n    },\n    \"catchup\": true\n  },\n  \"options\": {\n    \"firstEvent\": \"oldest\"\n  }\n}\n</code></pre>"},{"location":"tutorials/custom_contracts/ethereum/#subscribe-to-events-from-our-contract","title":"Subscribe to events from our contract","text":"<p>Now that we've told FireFly that it should listen for specific events on the blockchain, we can set up a Subscription for FireFly to send events to our app. To set up our subscription, we will make a <code>POST</code> to the <code>/subscriptions</code> endpoint.</p> <p>We will set a friendly name <code>simple-storage</code> to identify the Subscription when we are connecting to it in the next step.</p> <p>We're also going to set up a filter to only send events blockchain events from our listener that we created in the previous step. To do that, we'll copy the listener ID from the step above (<code>1bfa3b0f-3d90-403e-94a4-af978d8c5b14</code>) and set that as the value of the <code>listener</code> field in the example below:</p>"},{"location":"tutorials/custom_contracts/ethereum/#request_8","title":"Request","text":"<p><code>POST</code> <code>http://localhost:5000/api/v1/namespaces/default/subscriptions</code></p> <pre><code>{\n  \"namespace\": \"default\",\n  \"name\": \"simple-storage\",\n  \"transport\": \"websockets\",\n  \"filter\": {\n    \"events\": \"blockchain_event_received\",\n    \"blockchainevent\": {\n      \"listener\": \"1bfa3b0f-3d90-403e-94a4-af978d8c5b14\"\n    }\n  },\n  \"options\": {\n    \"firstEvent\": \"oldest\"\n  }\n}\n</code></pre>"},{"location":"tutorials/custom_contracts/ethereum/#response_8","title":"Response","text":"<pre><code>{\n  \"id\": \"f826269c-65ed-4634-b24c-4f399ec53a32\",\n  \"namespace\": \"default\",\n  \"name\": \"simple-storage\",\n  \"transport\": \"websockets\",\n  \"filter\": {\n    \"events\": \"blockchain_event_received\",\n    \"message\": {},\n    \"transaction\": {},\n    \"blockchainevent\": {\n      \"listener\": \"1bfa3b0f-3d90-403e-94a4-af978d8c5b14\"\n    }\n  },\n  \"options\": {\n    \"firstEvent\": \"-1\",\n    \"withData\": false\n  },\n  \"created\": \"2022-03-15T17:35:30.131698921Z\",\n  \"updated\": null\n}\n</code></pre>"},{"location":"tutorials/custom_contracts/ethereum/#receive-custom-smart-contract-events","title":"Receive custom smart contract events","text":"<p>The last step is to connect a WebSocket client to FireFly to receive the event. You can use any WebSocket client you like, such as Postman or a command line app like <code>websocat</code>.</p> <p>Connect your WebSocket client to <code>ws://localhost:5000/ws</code>.</p> <p>After connecting the WebSocket client, send a message to tell FireFly to:</p> <ul> <li>Start sending events</li> <li>For the Subscription named <code>simple-storage</code></li> <li>On the <code>default</code> namespace</li> <li>Automatically \"ack\" each event which will let FireFly immediately send the next event when available</li> </ul> <pre><code>{\n  \"type\": \"start\",\n  \"name\": \"simple-storage\",\n  \"namespace\": \"default\",\n  \"autoack\": true\n}\n</code></pre>"},{"location":"tutorials/custom_contracts/ethereum/#websocket-event","title":"WebSocket event","text":"<p>After creating the subscription, you should see an event arrive on the connected WebSocket client that looks something like this:</p> <pre><code>{\n  \"id\": \"0f4a31d6-9743-4537-82df-5a9c76ccbd1e\",\n  \"sequence\": 24,\n  \"type\": \"blockchain_event_received\",\n  \"namespace\": \"default\",\n  \"reference\": \"dd3e1554-c832-47a8-898e-f1ee406bea41\",\n  \"created\": \"2022-03-15T17:32:27.824417878Z\",\n  \"blockchainevent\": {\n    \"id\": \"dd3e1554-c832-47a8-898e-f1ee406bea41\",\n    \"sequence\": 7,\n    \"source\": \"ethereum\",\n    \"namespace\": \"default\",\n    \"name\": \"Changed\",\n    \"listener\": \"1bfa3b0f-3d90-403e-94a4-af978d8c5b14\",\n    \"protocolId\": \"000000000010/000000/000000\",\n    \"output\": {\n      \"from\": \"0xb7e6a5eb07a75a2c81801a157192a82bcbce0f21\",\n      \"value\": \"3\"\n    },\n    \"info\": {\n      \"address\": \"0xa5ea5d0a6b2eaf194716f0cc73981939dca26da1\",\n      \"blockNumber\": \"10\",\n      \"logIndex\": \"0\",\n      \"signature\": \"Changed(address,uint256)\",\n      \"subId\": \"sb-724b8416-786d-4e67-4cd3-5bae4a26eb0e\",\n      \"timestamp\": \"1647365460\",\n      \"transactionHash\": \"0xd5b5c716554097b2868d8705241bb2189bb76d16300f702ad05b0b02fccc4afb\",\n      \"transactionIndex\": \"0x0\"\n    },\n    \"timestamp\": \"2022-03-15T17:31:00Z\",\n    \"tx\": {\n      \"type\": \"\"\n    }\n  },\n  \"subscription\": {\n    \"id\": \"f826269c-65ed-4634-b24c-4f399ec53a32\",\n    \"namespace\": \"default\",\n    \"name\": \"simple-storage\"\n  }\n}\n</code></pre> <p>You can see in the event received over the WebSocket connection, the blockchain event that was emitted from our first transaction, which happened in the past. We received this event, because when we set up both the Listener, and the Subscription, we specified the <code>\"firstEvent\"</code> as <code>\"oldest\"</code>. This tells FireFly to look for this event from the beginning of the blockchain, and that your app is interested in FireFly events since the beginning of FireFly's event history.</p> <p>In the event, we can also see the <code>blockchainevent</code> itself, which has an <code>output</code> object. These are the <code>params</code> in our FireFly Interface, and the actual output of the event. Here we can see the <code>value</code> is <code>3</code> which is what we set the integer to in our original transaction.</p>"},{"location":"tutorials/custom_contracts/ethereum/#subscription-offset","title":"Subscription offset","text":"<p>If you query by the ID of your subscription with the <code>fetchstatus</code> parameter, you can see its current <code>offset</code>.</p> <p><code>GET</code> <code>http://localhost:5000/api/v1/namespaces/default/subscriptions/f826269c-65ed-4634-b24c-4f399ec53a32</code></p> <pre><code>{\n  \"id\": \"f826269c-65ed-4634-b24c-4f399ec53a32\",\n  \"namespace\": \"default\",\n  \"name\": \"simple-storage\",\n  \"transport\": \"websockets\",\n  \"filter\": {\n    \"events\": \"blockchain_event_received\",\n    \"message\": {},\n    \"transaction\": {},\n    \"blockchainevent\": {\n      \"listener\": \"1bfa3b0f-3d90-403e-94a4-af978d8c5b14\"\n    }\n  },\n  \"options\": {\n    \"firstEvent\": \"-1\",\n    \"withData\": false\n  },\n  \"status\": {\n    \"offset\": 20\n  }\n  \"created\": \"2022-03-15T17:35:30.131698921Z\",\n  \"updated\": null\n}\n</code></pre> <p>You've reached the end of the main guide to working with custom smart contracts in FireFly. Hopefully this was helpful and gives you what you need to get up and running with your own contracts. There are several additional ways to invoke or query smart contracts detailed below, so feel free to keep reading if you're curious.</p>"},{"location":"tutorials/custom_contracts/ethereum/#appendix-i-work-with-a-custom-contract-without-creating-a-named-api","title":"Appendix I: Work with a custom contract without creating a named API","text":"<p>FireFly aims to offer a developer-friendly and flexible approach to using custom smart contracts. The guide above has detailed the most robust and feature-rich way to use custom contracts with FireFly, but there are several alternative API usage patterns available as well.</p> <p>It is possible to broadcast a contract interface and use a smart contract that implements that interface without also broadcasting a named API as above. There are several key differences (which may or may not be desirable) compared to the method outlined in the full guide above:</p> <ul> <li>OpenAPI Spec and Swagger UI are not available</li> <li>Each HTTP request to invoke/query the contract will need to include the contract location</li> <li>The contract location will not have been broadcasted to all other members of the network</li> <li>The URL to invoke/query the contract will be different (described below)</li> </ul>"},{"location":"tutorials/custom_contracts/ethereum/#request_9","title":"Request","text":"<p><code>POST</code> <code>http://localhost:5000/api/v1/namespaces/default/contracts/interfaces/8bdd27a5-67c1-4960-8d1e-7aa31b9084d3/invoke/set</code></p> <pre><code>{\n  \"location\": {\n    \"address\": \"0xa5ea5d0a6b2eaf194716f0cc73981939dca26da1\"\n  },\n  \"input\": {\n    \"newValue\": 7\n  }\n}\n</code></pre>"},{"location":"tutorials/custom_contracts/ethereum/#response_9","title":"Response","text":"<pre><code>{\n  \"id\": \"f310fa4a-73d8-4777-9f9d-dfa5012a052f\"\n}\n</code></pre> <p>All of the same invoke, query, and subscribe endpoints are available on the contract interface itself.</p>"},{"location":"tutorials/custom_contracts/ethereum/#appendix-ii-work-directly-with-contracts-with-inline-requests","title":"Appendix II: Work directly with contracts with inline requests","text":"<p>The final way of working with custom smart contracts with FireFly is to just put everything FireFly needs all in one request, each time a contract is invoked or queried. This is the most lightweight, but least feature-rich way of using a custom contract.</p> <p>To do this, we will need to put both the contract location, and a subset of the FireFly Interface that describes the method we want to invoke in the request body, in addition to the function input.</p>"},{"location":"tutorials/custom_contracts/ethereum/#request_10","title":"Request","text":"<p><code>POST</code> <code>http://localhost:5000/api/v1/namespaces/default/contracts/invoke</code></p> <pre><code>{\n  \"location\": {\n    \"address\": \"0xa5ea5d0a6b2eaf194716f0cc73981939dca26da1\"\n  },\n  \"method\": {\n    \"name\": \"set\",\n    \"params\": [\n      {\n        \"name\": \"x\",\n        \"schema\": {\n          \"type\": \"integer\",\n          \"details\": {\n            \"type\": \"uint256\"\n          }\n        }\n      }\n    ],\n    \"returns\": []\n  },\n  \"input\": {\n    \"x\": 42\n  }\n}\n</code></pre>"},{"location":"tutorials/custom_contracts/ethereum/#response_10","title":"Response","text":"<pre><code>{\n  \"id\": \"386d3e23-e4bc-4a9b-bc1f-452f0a8c9ae5\"\n}\n</code></pre>"},{"location":"tutorials/custom_contracts/fabric/","title":"Work with Hyperledger Fabric chaincodes","text":"<p>This guide describes the steps to deploy a chaincode to a Hyperledger Fabric blockchain and use FireFly to interact with it in order to submit transactions, query for states and listening for events.</p> <p>NOTE: This guide assumes that you are running a local FireFly stack with at least 2 members and a Fabric blockchain created by the FireFly CLI. If you need help getting that set up, please see the Getting Started guide to Start your environment.</p>"},{"location":"tutorials/custom_contracts/fabric/#example-smart-contract","title":"Example smart contract","text":"<p>For this tutorial, we will be using a well known, but slightly modified smart contract called <code>asset_transfer</code>. It's based on the <code>asset-transfer-basic</code> chaincode in the fabric-samples project. Check out the code repository and use the source code provided below to replace part of the content of the file <code>fabric-samples/asset-transfer-basic/chaincode-go/chaincode/smartcontract.go</code>.</p> <p>Find the following return statement in the function <code>CreateAsset</code>:</p> <pre><code>    return ctx.GetStub().PutState(id, assetJSON)\n</code></pre> <p>and replace it with the following, so that an event will be emitted when the transaction is committed to the channel ledger:</p> <pre><code>  err = ctx.GetStub().PutState(id, assetJSON)\n  if err != nil {\n    return err\n  }\n  return ctx.GetStub().SetEvent(\"AssetCreated\", assetJSON)\n</code></pre>"},{"location":"tutorials/custom_contracts/fabric/#create-the-chaincode-package","title":"Create the chaincode package","text":"<p>Use the <code>peer</code> command to create the chaincode package for deployment. You can download the peer binary from the releases page of the Fabric project or build it from source.</p> <pre><code>  ~ johndoe$ cd fabric-samples/asset-transfer-basic/chaincode-go\n  chaincode-go johndoe$ touch core.yaml\n  chaincode-go johndoe$ peer lifecycle chaincode package -p . --label asset_transfer ./asset_transfer.zip\n</code></pre> <p>The <code>peer</code> command requires an empty core.yaml file to be present in the working directory to perform the packaging. That's what <code>touch core.yaml</code> did above</p> <p>The resulting <code>asset_transfer.zip</code> archive file will be used in the next step to deploy to the Fabric network used in FireFly.</p>"},{"location":"tutorials/custom_contracts/fabric/#contract-deployment","title":"Contract deployment","text":"<p>Deployment of smart contracts is not currently within the scope of responsibility for FireFly. You can use your standard blockchain specific tools to deploy your contract to the blockchain you are using.</p> <p>The FireFly CLI provides a convenient function to deploy a chaincode package to a local FireFly stack.</p> <p>NOTE: The contract deployment function of the FireFly CLI is a convenience function to speed up local development, and not intended for production applications</p> <pre><code>~ johndoe$ ff help deploy fabric\nDeploy a packaged chaincode to the Fabric network used by a FireFly stack\n\nUsage:\n  ff deploy fabric &lt;stack_name&gt; &lt;chaincode_package&gt; &lt;channel&gt; &lt;chaincodeName&gt; &lt;version&gt; [flags]\n</code></pre> <p>Notice the various parameters used by the command <code>ff deploy fabric</code>. We'll tell the FireFly to deploy using the following parameter values, if your stack setup is different, update the command accordingly:</p> <ul> <li>stack name: <code>dev</code></li> <li>channel: <code>firefly</code> (this is the channel that is created by the FireFly CLI when bootstrapping the stack, replace if you use a different channel in your setup)</li> <li>chaincode name: <code>asset_transfer</code> (must match the value of the <code>--label</code> parameter when creating the chaincode package)</li> <li>version: <code>1.0</code></li> </ul> <pre><code>$ ff deploy fabric dev asset_transfer.zip firefly asset_transfer 1.0\ninstalling chaincode\nquerying installed chaincode\napproving chaincode\ncommitting chaincode\n{\n  \"chaincode\": \"asset_transfer\",\n  \"channel\": \"firefly\"\n}\n</code></pre>"},{"location":"tutorials/custom_contracts/fabric/#the-firefly-interface-format","title":"The FireFly Interface Format","text":"<p>In order to teach FireFly how to interact with the chaincode, a FireFly Interface (FFI) document is needed. While Ethereum (or other EVM based blockchains) requires an Application Binary Interface (ABI) to govern the interaction between the client and the smart contract, which is specific to each smart contract interface design, Fabric defines a generic chaincode interface and leaves the encoding and decoding of the parameter values to the discretion of the chaincode developer.</p> <p>As a result, the FFI document for a Fabric chaincode must be hand-crafted. The following FFI sample demonstrates the specification for the following common cases:</p> <ul> <li>structured JSON, used here for the list of chaincode function <code>CreateAsset</code> input parameters</li> <li>array of JSON, used here for the chaincode function <code>GetAllAssets</code> output</li> <li>structured JSON, used here for the list of chaincode event <code>AssetCreated</code> properties</li> </ul> <pre><code>{\n  \"namespace\": \"default\",\n  \"name\": \"asset_transfer\",\n  \"description\": \"Spec interface for the asset-transfer-basic golang chaincode\",\n  \"version\": \"1.0\",\n  \"methods\": [\n    {\n      \"name\": \"GetAllAssets\",\n      \"pathname\": \"\",\n      \"description\": \"\",\n      \"params\": [],\n      \"returns\": [\n        {\n          \"name\": \"\",\n          \"schema\": {\n            \"type\": \"array\",\n            \"details\": {\n              \"type\": \"object\",\n              \"properties\": {\n                \"type\": \"string\"\n              }\n            }\n          }\n        }\n      ]\n    },\n    {\n      \"name\": \"CreateAsset\",\n      \"pathname\": \"\",\n      \"description\": \"\",\n      \"params\": [\n        {\n          \"name\": \"id\",\n          \"schema\": {\n            \"type\": \"string\"\n          }\n        },\n        {\n          \"name\": \"color\",\n          \"schema\": {\n            \"type\": \"string\"\n          }\n        },\n        {\n          \"name\": \"size\",\n          \"schema\": {\n            \"type\": \"string\"\n          }\n        },\n        {\n          \"name\": \"owner\",\n          \"schema\": {\n            \"type\": \"string\"\n          }\n        },\n        {\n          \"name\": \"value\",\n          \"schema\": {\n            \"type\": \"string\"\n          }\n        }\n      ],\n      \"returns\": []\n    }\n  ],\n  \"events\": [\n    {\n      \"name\": \"AssetCreated\"\n    }\n  ]\n}\n</code></pre>"},{"location":"tutorials/custom_contracts/fabric/#input-parameters","title":"Input parameters","text":"<p>For the <code>params</code> section of the <code>CreateAsset</code> function, it is critical that the sequence of the properties (<code>id</code>, <code>color</code>, <code>size</code>, <code>owner</code>, <code>value</code>) matches the order of the input parameters in the chaincode's function signature:</p> <pre><code>func CreateAsset(ctx contractapi.TransactionContextInterface, id string, color string, size int, owner string, appraisedValue int) error\n</code></pre>"},{"location":"tutorials/custom_contracts/fabric/#return-values","title":"Return values","text":"<p>FireFly can automatically decode JSON payloads in the return values. That's why the <code>returns</code> section of the <code>GetAllAssets</code> function only needs to specify the type as <code>array of objects</code>, without having to specify the detailed structure of the JSON payload.</p> <p>On the other hand, if certain properties of the returned value are to be hidden, then you can provide a detailed structure of the JSON object with the desired properties. This is demonstrated in the JSON structure for the event payload, see below, where the property <code>AppraisedValue</code> is omitted from the output.</p>"},{"location":"tutorials/custom_contracts/fabric/#event-payloads","title":"Event payloads","text":"<p>For events, FireFly automatically decodes JSON payloads. If the event payload is not JSON, base64 encoded bytes will be returned instead. For the <code>events</code> section of the FFI, only the <code>name</code> property needs to be specified.</p>"},{"location":"tutorials/custom_contracts/fabric/#broadcast-the-contract-interface","title":"Broadcast the contract interface","text":"<p>Now that we have a FireFly Interface representation of our chaincode, we want to broadcast that to the entire network. This broadcast will be pinned to the blockchain, so we can always refer to this specific name and version, and everyone in the network will know exactly which contract interface we are talking about.</p> <p>We will use the FFI JSON constructed above and <code>POST</code> that to the <code>/contracts/interfaces</code> API endpoint.</p>"},{"location":"tutorials/custom_contracts/fabric/#request","title":"Request","text":"<p><code>POST</code> <code>http://localhost:5000/api/v1/namespaces/default/contracts/interfaces?publish=true</code></p> <p>NOTE: Without passing the query parameter <code>publish=true</code> when the interface is created, it will initially be unpublished and not broadcasted to other members of the network (if configured in multi-party). To publish the interface, a subsequent API call would need to be made to <code>/contracts/interfaces/{name}/{version}/publish</code></p> <pre><code>{\n  \"namespace\": \"default\",\n  \"name\": \"asset_transfer\",\n  \"description\": \"Spec interface for the asset-transfer-basic golang chaincode\",\n  \"version\": \"1.0\",\n  \"methods\": [\n    {\n      \"name\": \"GetAllAssets\",\n      \"pathname\": \"\",\n      \"description\": \"\",\n      \"params\": [],\n      \"returns\": [\n        {\n          \"name\": \"\",\n          \"schema\": {\n            \"type\": \"array\",\n            \"details\": {\n              \"type\": \"object\",\n              \"properties\": {\n                \"type\": \"string\"\n              }\n            }\n          }\n        }\n      ]\n    },\n    {\n      \"name\": \"CreateAsset\",\n      \"pathname\": \"\",\n      \"description\": \"\",\n      \"params\": [\n        {\n          \"name\": \"id\",\n          \"schema\": {\n            \"type\": \"string\"\n          }\n        },\n        {\n          \"name\": \"color\",\n          \"schema\": {\n            \"type\": \"string\"\n          }\n        },\n        {\n          \"name\": \"size\",\n          \"schema\": {\n            \"type\": \"string\"\n          }\n        },\n        {\n          \"name\": \"owner\",\n          \"schema\": {\n            \"type\": \"string\"\n          }\n        },\n        {\n          \"name\": \"value\",\n          \"schema\": {\n            \"type\": \"string\"\n          }\n        }\n      ],\n      \"returns\": []\n    }\n  ],\n  \"events\": [\n    {\n      \"name\": \"AssetCreated\"\n    }\n  ]\n}\n</code></pre>"},{"location":"tutorials/custom_contracts/fabric/#response","title":"Response","text":"<pre><code>{\n  \"id\": \"f1e5522c-59a5-4787-bbfd-89975e5b0954\",\n  \"message\": \"8a01fc83-5729-418b-9706-6fc17c8d2aac\",\n  \"namespace\": \"default\",\n  \"name\": \"asset_transfer\",\n  \"description\": \"Spec interface for the asset-transfer-basic golang chaincode\",\n  \"version\": \"1.1\",\n  \"methods\": [\n    {\n      \"id\": \"b31e3623-35e8-4918-bf8c-1b0d6c01de25\",\n      \"interface\": \"f1e5522c-59a5-4787-bbfd-89975e5b0954\",\n      \"name\": \"GetAllAssets\",\n      \"namespace\": \"default\",\n      \"pathname\": \"GetAllAssets\",\n      \"description\": \"\",\n      \"params\": [],\n      \"returns\": [\n        {\n          \"name\": \"\",\n          \"schema\": {\n            \"type\": \"array\",\n            \"details\": {\n              \"type\": \"object\",\n              \"properties\": {\n                \"type\": \"string\"\n              }\n            }\n          }\n        }\n      ]\n    },\n    {\n      \"id\": \"e5a170d1-0be1-4697-800b-f4bcfaf71cf6\",\n      \"interface\": \"f1e5522c-59a5-4787-bbfd-89975e5b0954\",\n      \"name\": \"CreateAsset\",\n      \"namespace\": \"default\",\n      \"pathname\": \"CreateAsset\",\n      \"description\": \"\",\n      \"params\": [\n        {\n          \"name\": \"id\",\n          \"schema\": {\n            \"type\": \"string\"\n          }\n        },\n        {\n          \"name\": \"color\",\n          \"schema\": {\n            \"type\": \"string\"\n          }\n        },\n        {\n          \"name\": \"size\",\n          \"schema\": {\n            \"type\": \"string\"\n          }\n        },\n        {\n          \"name\": \"owner\",\n          \"schema\": {\n            \"type\": \"string\"\n          }\n        },\n        {\n          \"name\": \"value\",\n          \"schema\": {\n            \"type\": \"string\"\n          }\n        }\n      ],\n      \"returns\": []\n    }\n  ],\n  \"events\": [\n    {\n      \"id\": \"27564533-30bd-4536-884e-02e5d79ec238\",\n      \"interface\": \"f1e5522c-59a5-4787-bbfd-89975e5b0954\",\n      \"namespace\": \"default\",\n      \"pathname\": \"AssetCreated\",\n      \"signature\": \"\",\n      \"name\": \"AssetCreated\",\n      \"description\": \"\",\n      \"params\": null\n    }\n  ]\n}\n</code></pre> <p>NOTE: We can broadcast this contract interface conveniently with the help of FireFly Sandbox running at <code>http://127.0.0.1:5108</code></p> <ul> <li>Go to the <code>Contracts Section</code></li> <li>Click on <code>Define a Contract Interface</code></li> <li>Select <code>FFI - FireFly Interface</code> in the <code>Interface Fromat</code> dropdown</li> <li>Copy the <code>FFI JSON</code> crafted by you into the <code>Schema</code> Field</li> <li>Click on <code>Run</code></li> </ul>"},{"location":"tutorials/custom_contracts/fabric/#create-an-http-api-for-the-contract","title":"Create an HTTP API for the contract","text":"<p>Now comes the fun part where we see some of the powerful, developer-friendly features of FireFly. The next thing we're going to do is tell FireFly to build an HTTP API for this chaincode, complete with an OpenAPI Specification and Swagger UI. As part of this, we'll also tell FireFly where the chaincode is on the blockchain.</p> <p>Like the interface broadcast above, this will also generate a broadcast which will be pinned to the blockchain so all the members of the network will be aware of and able to interact with this API.</p> <p>We need to copy the <code>id</code> field we got in the response from the previous step to the <code>interface.id</code> field in the request body below. We will also pick a name that will be part of the URL for our HTTP API, so be sure to pick a name that is URL friendly. In this case we'll call it <code>asset_transfer</code>. Lastly, in the <code>location</code> field, we're telling FireFly where an instance of the chaincode is deployed on-chain, which is a chaincode named <code>asset_transfer</code> in the channel <code>firefly</code>.</p> <p>NOTE: The <code>location</code> field is optional here, but if it is omitted, it will be required in every request to invoke or query the chaincode. This can be useful if you have multiple instances of the same chaincode deployed to different channels.</p>"},{"location":"tutorials/custom_contracts/fabric/#request_1","title":"Request","text":"<p><code>POST</code> <code>http://localhost:5000/api/v1/namespaces/default/apis?publish=true</code></p> <p>NOTE: Without passing the query parameter <code>publish=true</code> when the API is created, it will initially be unpublished and not broadcasted to other members of the network (if configured in multi-party). To publish the API, a subsequent API call would need to be made to <code>/apis/{apiName}/publish</code></p> <pre><code>{\n  \"name\": \"asset_transfer\",\n  \"interface\": {\n    \"id\": \"f1e5522c-59a5-4787-bbfd-89975e5b0954\"\n  },\n  \"location\": {\n    \"channel\": \"firefly\",\n    \"chaincode\": \"asset_transfer\"\n  }\n}\n</code></pre>"},{"location":"tutorials/custom_contracts/fabric/#response_1","title":"Response","text":"<pre><code>{\n  \"id\": \"a9a9ab4e-2544-45d5-8824-3c05074fbf75\",\n  \"namespace\": \"default\",\n  \"interface\": {\n    \"id\": \"f1e5522c-59a5-4787-bbfd-89975e5b0954\"\n  },\n  \"location\": {\n    \"channel\": \"firefly\",\n    \"chaincode\": \"asset_transfer\"\n  },\n  \"name\": \"asset_transfer\",\n  \"message\": \"5f1556a1-5cb1-4bc6-8611-d8f88ccf9c30\",\n  \"urls\": {\n    \"openapi\": \"http://127.0.0.1:5000/api/v1/namespaces/default/apis/asset_transfer/api/swagger.json\",\n    \"ui\": \"http://127.0.0.1:5000/api/v1/namespaces/default/apis/asset_transfer/api\"\n  }\n}\n</code></pre> <p>NOTE: We can create this Http API conveniently with the help of FireFly Sandbox running at <code>http://127.0.0.1:5108</code></p> <ul> <li>Go to the <code>Contracts Section</code></li> <li>Click on <code>Register a Contract API</code></li> <li>Select the name of your broadcasted FFI in the <code>Contract Interface</code> dropdown</li> <li>In the <code>Name</code> Field, give a name that will be part of the URL for your Http API</li> <li>In the <code>Chaincode</code> Field, give your chaincode name for which you wrote the FFI</li> <li>In the <code>Channel</code> Field, give the channel name where your chaincode is deployed</li> <li>Click on <code>Run</code></li> </ul>"},{"location":"tutorials/custom_contracts/fabric/#view-openapi-spec-for-the-contract","title":"View OpenAPI spec for the contract","text":"<p>You'll notice in the response body that there are a couple of URLs near the bottom. If you navigate to the one labeled <code>ui</code> in your browser, you should see the Swagger UI for your chaincode.</p> <p></p>"},{"location":"tutorials/custom_contracts/fabric/#invoke-endpoints","title":"/invoke/* endpoints","text":"<p>The <code>/invoke</code> endpoints in the generated API are for submitting transactions. These endpoints will be mapped to the <code>POST /transactions</code> endpoint of the FabConnect API.</p>"},{"location":"tutorials/custom_contracts/fabric/#query-endpoints","title":"/query/* endpoints","text":"<p>The <code>/query</code> endpoints in the generated API, on the other hand, are for sending query requests. These endpoints will be mapped to the <code>POST /query</code> endpoint of the Fabconnect API, which under the cover only sends chaincode endorsement requests to the target peer node without sending a trasaction payload to the orderer node.</p>"},{"location":"tutorials/custom_contracts/fabric/#invoke-the-chaincode","title":"Invoke the chaincode","text":"<p>Now that we've got everything set up, it's time to use our chaincode! We're going to make a <code>POST</code> request to the <code>invoke/CreateAsset</code> endpoint to create a new asset.</p>"},{"location":"tutorials/custom_contracts/fabric/#request_2","title":"Request","text":"<p><code>POST</code> <code>http://localhost:5000/api/v1/namespaces/default/apis/asset_transfer/invoke/CreateAsset</code></p> <pre><code>{\n  \"input\": {\n    \"color\": \"blue\",\n    \"id\": \"asset-01\",\n    \"owner\": \"Harry\",\n    \"size\": \"30\",\n    \"value\": \"23400\"\n  }\n}\n</code></pre>"},{"location":"tutorials/custom_contracts/fabric/#response_2","title":"Response","text":"<pre><code>{\n  \"id\": \"b8e905cc-bc23-434a-af7d-13c6d85ae545\",\n  \"namespace\": \"default\",\n  \"tx\": \"79d2668e-4626-4634-9448-1b40fa0d9dfd\",\n  \"type\": \"blockchain_invoke\",\n  \"status\": \"Pending\",\n  \"plugin\": \"fabric\",\n  \"input\": {\n    \"input\": {\n      \"color\": \"blue\",\n      \"id\": \"asset-02\",\n      \"owner\": \"Harry\",\n      \"size\": \"30\",\n      \"value\": \"23400\"\n    },\n    \"interface\": \"f1e5522c-59a5-4787-bbfd-89975e5b0954\",\n    \"key\": \"Org1MSP::x509::CN=org_0,OU=client::CN=fabric_ca.org1.example.com,OU=Hyperledger FireFly,O=org1.example.com,L=Raleigh,ST=North Carolina,C=US\",\n    \"location\": {\n      \"chaincode\": \"asset_transfer\",\n      \"channel\": \"firefly\"\n    },\n    \"method\": {\n      \"description\": \"\",\n      \"id\": \"e5a170d1-0be1-4697-800b-f4bcfaf71cf6\",\n      \"interface\": \"f1e5522c-59a5-4787-bbfd-89975e5b0954\",\n      \"name\": \"CreateAsset\",\n      \"namespace\": \"default\",\n      \"params\": [\n        {\n          \"name\": \"id\",\n          \"schema\": {\n            \"type\": \"string\"\n          }\n        },\n        {\n          \"name\": \"color\",\n          \"schema\": {\n            \"type\": \"string\"\n          }\n        },\n        {\n          \"name\": \"size\",\n          \"schema\": {\n            \"type\": \"string\"\n          }\n        },\n        {\n          \"name\": \"owner\",\n          \"schema\": {\n            \"type\": \"string\"\n          }\n        },\n        {\n          \"name\": \"value\",\n          \"schema\": {\n            \"type\": \"string\"\n          }\n        }\n      ],\n      \"pathname\": \"CreateAsset\",\n      \"returns\": []\n    },\n    \"methodPath\": \"CreateAsset\",\n    \"type\": \"invoke\"\n  },\n  \"created\": \"2022-05-02T17:08:40.811630044Z\",\n  \"updated\": \"2022-05-02T17:08:40.811630044Z\"\n}\n</code></pre> <p>You'll notice that we got an ID back with status <code>Pending</code>, and that's expected due to the asynchronous programming model of working with custom onchain logic in FireFly. To see what the latest state is now, we can query the chaincode. In a little bit, we'll also subscribe to the events emitted by this chaincode so we can know when the state is updated in realtime.</p>"},{"location":"tutorials/custom_contracts/fabric/#query-the-current-state","title":"Query the current state","text":"<p>To make a read-only request to the blockchain to check the current list of assets, we can make a <code>POST</code> to the <code>query/GetAllAssets</code> endpoint.</p>"},{"location":"tutorials/custom_contracts/fabric/#request_3","title":"Request","text":"<p><code>POST</code> <code>http://localhost:5000/api/v1/namespaces/default/apis/asset_transfer/query/GetAllAssets</code></p> <pre><code>{}\n</code></pre>"},{"location":"tutorials/custom_contracts/fabric/#response_3","title":"Response","text":"<pre><code>[\n  {\n    \"AppraisedValue\": 23400,\n    \"Color\": \"blue\",\n    \"ID\": \"asset-01\",\n    \"Owner\": \"Harry\",\n    \"Size\": 30\n  }\n]\n</code></pre> <p>NOTE: Some chaincodes may have queries that require input parameters. That's why the query endpoint is a <code>POST</code>, rather than a <code>GET</code> so that parameters can be passed as JSON in the request body. This particular function does not have any parameters, so we just pass an empty JSON object.</p>"},{"location":"tutorials/custom_contracts/fabric/#create-a-blockchain-event-listener","title":"Create a blockchain event listener","text":"<p>Now that we've seen how to submit transactions and preform read-only queries to the blockchain, let's look at how to receive blockchain events so we know when things are happening in realtime.</p> <p>If you look at the source code for the smart contract we're working with above, you'll notice that it emits an event when a new asset is created. In order to receive these events, we first need to instruct FireFly to listen for this specific type of blockchain event. To do this, we create an Event Listener.</p> <p>The <code>/contracts/listeners</code> endpoint is RESTful so there are <code>POST</code>, <code>GET</code>, and <code>DELETE</code> methods available on it. To create a new listener, we will make a <code>POST</code> request. We are going to tell FireFly to listen to events with name <code>\"AssetCreated\"</code> from the FireFly Interface we defined earlier, referenced by its ID. We will also tell FireFly which channel and chaincode we expect to emit these events.</p>"},{"location":"tutorials/custom_contracts/fabric/#request_4","title":"Request","text":"<p><code>POST</code> <code>http://localhost:5000/api/v1/namespaces/default/contracts/listeners</code></p> <pre><code>{\n  \"filters\": [\n    {\n      \"interface\": {\n        \"id\": \"f1e5522c-59a5-4787-bbfd-89975e5b0954\"\n      },\n      \"location\": {\n        \"channel\": \"firefly\",\n        \"chaincode\": \"asset_transfer\"\n      },\n      \"event\": {\n        \"name\": \"AssetCreated\"\n      }\n    }\n  ],\n  \"options\": {\n    \"firstEvent\": \"oldest\"\n  },\n  \"topic\": \"assets\"\n}\n</code></pre>"},{"location":"tutorials/custom_contracts/fabric/#response_4","title":"Response","text":"<pre><code>{\n  \"id\": \"d6b5e774-c9e5-474c-9495-ec07fa47a907\",\n  \"namespace\": \"default\",\n  \"name\": \"sb-44aa348a-bafb-4243-594e-dcad689f1032\",\n  \"backendId\": \"sb-44aa348a-bafb-4243-594e-dcad689f1032\",\n  \"location\": {\n    \"channel\": \"firefly\",\n    \"chaincode\": \"asset_transfer\"\n  },\n  \"created\": \"2024-07-22T15:36:58.514085959Z\",\n  \"event\": {\n    \"name\": \"AssetCreated\",\n    \"description\": \"\",\n    \"params\": null\n  },\n  \"signature\": \"firefly-asset_transfer:AssetCreated\",\n  \"topic\": \"assets\",\n  \"options\": {\n    \"firstEvent\": \"oldest\"\n  },\n  \"filters\": [\n    {\n      \"event\": {\n        \"name\": \"AssetCreated\",\n        \"description\": \"\",\n        \"params\": null\n      },\n      \"location\": {\n        \"channel\": \"firefly\",\n        \"chaincode\": \"asset_transfer\"\n      },\n      \"signature\": \"firefly-asset_transfer:AssetCreated\"\n    }\n  ]\n}\n</code></pre>"},{"location":"tutorials/custom_contracts/fabric/#subscribe-to-events-from-our-contract","title":"Subscribe to events from our contract","text":"<p>Now that we've told FireFly that it should listen for specific events on the blockchain, we can set up a Subscription for FireFly to send events to our client app. To set up our subscription, we will make a <code>POST</code> to the <code>/subscriptions</code> endpoint.</p> <p>We will set a friendly name <code>asset_transfer</code> to identify the Subscription when we are connecting to it in the next step.</p> <p>We're also going to set up a filter to only send events blockchain events from our listener that we created in the previous step. To do that, we'll copy the listener ID from the step above (<code>6e7f5dd8-5a57-4163-a1d2-5654e784dc31</code>) and set that as the value of the <code>listener</code> field in the example below:</p>"},{"location":"tutorials/custom_contracts/fabric/#request_5","title":"Request","text":"<p><code>POST</code> <code>http://localhost:5000/api/v1/namespaces/default/subscriptions</code></p> <pre><code>{\n  \"namespace\": \"default\",\n  \"name\": \"asset_transfer\",\n  \"transport\": \"websockets\",\n  \"filter\": {\n    \"events\": \"blockchain_event_received\",\n    \"blockchainevent\": {\n      \"listener\": \"6e7f5dd8-5a57-4163-a1d2-5654e784dc31\"\n    }\n  },\n  \"options\": {\n    \"firstEvent\": \"oldest\"\n  }\n}\n</code></pre>"},{"location":"tutorials/custom_contracts/fabric/#response_5","title":"Response","text":"<pre><code>{\n  \"id\": \"06d18b49-e763-4f5c-9e97-c25024fe57c8\",\n  \"namespace\": \"default\",\n  \"name\": \"asset_transfer\",\n  \"transport\": \"websockets\",\n  \"filter\": {\n    \"events\": \"blockchain_event_received\",\n    \"message\": {},\n    \"transaction\": {},\n    \"blockchainevent\": {\n      \"listener\": \"6e7f5dd8-5a57-4163-a1d2-5654e784dc31\"\n    }\n  },\n  \"options\": {\n    \"firstEvent\": \"-1\",\n    \"withData\": false\n  },\n  \"created\": \"2022-05-02T17:22:06.480181291Z\",\n  \"updated\": null\n}\n</code></pre>"},{"location":"tutorials/custom_contracts/fabric/#receive-custom-smart-contract-events","title":"Receive custom smart contract events","text":"<p>The last step is to connect a WebSocket client to FireFly to receive the event. You can use any WebSocket client you like, such as Postman or a command line app like <code>websocat</code>.</p> <p>Connect your WebSocket client to <code>ws://localhost:5000/ws</code>.</p> <p>After connecting the WebSocket client, send a message to tell FireFly to:</p> <ul> <li>Start sending events</li> <li>For the Subscription named <code>asset_transfer</code></li> <li>On the <code>default</code> namespace</li> <li>Automatically \"ack\" each event which will let FireFly immediately send the next event when available</li> </ul> <pre><code>{\n  \"type\": \"start\",\n  \"name\": \"asset_transfer\",\n  \"namespace\": \"default\",\n  \"autoack\": true\n}\n</code></pre>"},{"location":"tutorials/custom_contracts/fabric/#websocket-event","title":"WebSocket event","text":"<p>After creating the subscription, you should see an event arrive on the connected WebSocket client that looks something like this:</p> <pre><code>{\n  \"id\": \"d9fb86b2-b25b-43b8-80d3-936c5daa5a66\",\n  \"sequence\": 29,\n  \"type\": \"blockchain_event_received\",\n  \"namespace\": \"default\",\n  \"reference\": \"e0d670b4-a1b6-4efd-a985-06dfaaa58fe3\",\n  \"topic\": \"assets\",\n  \"created\": \"2022-05-02T17:26:57.57612001Z\",\n  \"blockchainEvent\": {\n    \"id\": \"e0d670b4-a1b6-4efd-a985-06dfaaa58fe3\",\n    \"source\": \"fabric\",\n    \"namespace\": \"default\",\n    \"name\": \"AssetCreated\",\n    \"listener\": \"6e7f5dd8-5a57-4163-a1d2-5654e784dc31\",\n    \"protocolId\": \"000000000015/000000/000000\",\n    \"output\": {\n      \"AppraisedValue\": 12300,\n      \"Color\": \"red\",\n      \"ID\": \"asset-01\",\n      \"Owner\": \"Jerry\",\n      \"Size\": 10\n    },\n    \"info\": {\n      \"blockNumber\": 15,\n      \"chaincodeId\": \"asset_transfer\",\n      \"eventIndex\": 0,\n      \"eventName\": \"AssetCreated\",\n      \"subId\": \"sb-2cac2bfa-38af-4408-4ff3-973421410e5d\",\n      \"timestamp\": 1651512414920972300,\n      \"transactionId\": \"172637bf59a3520ca6dd02f716e1043ba080e10e1cd2f98b4e6b85abcc6a6d69\",\n      \"transactionIndex\": 0\n    },\n    \"timestamp\": \"2022-05-02T17:26:54.9209723Z\",\n    \"tx\": {\n      \"type\": \"\",\n      \"blockchainId\": \"172637bf59a3520ca6dd02f716e1043ba080e10e1cd2f98b4e6b85abcc6a6d69\"\n    }\n  },\n  \"subscription\": {\n    \"id\": \"06d18b49-e763-4f5c-9e97-c25024fe57c8\",\n    \"namespace\": \"default\",\n    \"name\": \"asset_transfer\"\n  }\n}\n</code></pre> <p>You can see in the event received over the WebSocket connection, the blockchain event that was emitted from our first transaction, which happened in the past. We received this event, because when we set up both the Listener, and the Subscription, we specified the <code>\"firstEvent\"</code> as <code>\"oldest\"</code>. This tells FireFly to look for this event from the beginning of the blockchain, and that your app is interested in FireFly events since the beginning of FireFly's event history.</p> <p>In the event, we can also see the <code>blockchainEvent</code> itself, which has an <code>output</code> object. This contains the event payload that was set by the chaincode.</p>"},{"location":"tutorials/custom_contracts/pinning/","title":"Pin off-chain data to a custom blockchain transaction","text":"<p>This guide describes how to associate an arbitrary off-chain payload with a blockchain transaction on a contract of your own design. A hash of the payload will be recorded as part of the blockchain transaction, and on the receiving side, FireFly will ensure that both the on-chain and off-chain pieces are received and aggregated together.</p> <p>NOTE: This is an advanced FireFly feature. Before following any of the steps in this guide, you should be very familiar and comfortable with the basic features of how broadcast messages and private messages work, be proficient at custom contract development on your blockchain of choice, and understand the fundamentals of how FireFly interacts with custom contracts.</p>"},{"location":"tutorials/custom_contracts/pinning/#designing-a-compatible-contract","title":"Designing a compatible contract","text":"<p>In order to allow pinning a FireFly message batch with a custom contract transaction, your contract must meet certain criteria.</p> <p>First, any external method of the contract that will be used for associating with off-chain payloads must provide an extra parameter for passing the encoded batch data. This must be the last parameter in the method signature. This convention is chosen partly to align with the Ethereum ERC5750 standard, but should serve as a straightforward guideline for nearly any blockchain.</p> <p>Second, this method must emit a <code>BatchPin</code> event that can be received and parsed by FireFly. Exactly how the data is unpacked and used to emit this event will differ for each blockchain.</p>"},{"location":"tutorials/custom_contracts/pinning/#ethereum","title":"Ethereum","text":"<pre><code>import \"@hyperledger/firefly-contracts/contracts/IBatchPin.sol\";\n\ncontract CustomPin {\n    IBatchPin firefly;\n\n    function setFireFlyAddress(address addr) external {\n        firefly = IBatchPin(addr);\n    }\n\n    function sayHello(bytes calldata data) external {\n        require(\n            address(firefly) != address(0),\n            \"CustomPin: FireFly address has not been set\"\n        );\n\n        /* do custom things */\n\n        firefly.pinBatchData(data);\n    }\n}\n</code></pre> <ul> <li>The method in question will receive packed \"batch pin\" data in its last method parameter (in the   form of ABI-encoded <code>bytes</code>). The method must invoke the <code>pinBatchData</code> method of the   FireFly Multiparty Contract and pass along this data payload. It is generally good practice to   trigger this as a final step before returning, after the method has performed its own logic.</li> <li>This also implies that the contract must know the on-chain location of the   FireFly Multiparty Contract. How this is achieved is up to your individual implementation -   the example above shows exposing a method to set the address. An application may leverage the fact that   this location is available by querying the FireFly   <code>/status</code> API (under <code>multiparty.contract.location</code> as of FireFly v1.1.0). However, the application must   also consider how appropriately secure this functionality, and how to update this location if a multiparty   \"network action\" is used to migrate the network onto a new FireFly multiparty contract.</li> </ul>"},{"location":"tutorials/custom_contracts/pinning/#fabric","title":"Fabric","text":"<pre><code>package chaincode\n\nimport (\n    \"encoding/json\"\n    \"fmt\"\n\n    \"github.com/hyperledger/fabric-contract-api-go/contractapi\"\n    \"github.com/hyperledger/firefly/custompin_sample/batchpin\"\n)\n\ntype SmartContract struct {\n    contractapi.Contract\n}\n\nfunc (s *SmartContract) MyCustomPin(ctx contractapi.TransactionContextInterface, data string) error {\n    event, err := batchpin.BuildEventFromString(ctx, data)\n    if err != nil {\n        return err\n    }\n    bytes, err := json.Marshal(event)\n    if err != nil {\n        return fmt.Errorf(\"failed to marshal event: %s\", err)\n    }\n    return ctx.GetStub().SetEvent(\"BatchPin\", bytes)\n}\n</code></pre> <ul> <li>The method in question will received packed \"batch pin\" data in its last method parameter (in the   form of a JSON-encoded <code>string</code>). The method must unpack this argument into a JSON object.</li> <li>The contract must directly set a <code>BatchPin</code> event in the same format that is used by the   FireFly Multiparty Contract.</li> </ul>"},{"location":"tutorials/custom_contracts/pinning/#initializing-firefly","title":"Initializing FireFly","text":"<p>Once you have a contract designed, you can initialize your environment using the blockchain of your choice.</p> <p>No special initialization arguments are needed for Ethereum.</p> <p>If you are using Fabric, you must pass the <code>--custom-pin-support</code> argument when initializing your FireFly stack. This will ensure that the <code>BatchPin</code> event listener listens to events from all chaincode deployed on the default channel, instead of only listening to events from the pre-deployed FireFly chaincode.</p>"},{"location":"tutorials/custom_contracts/pinning/#invoking-the-contract","title":"Invoking the contract","text":"<p>You can follow the normal steps for Ethereum or Fabric to define your contract interface and API in FireFly. When invoking the contract, you can include a message payload alongside the other parameters.</p> <p><code>POST</code> <code>http://localhost:5000/api/v1/namespaces/default/apis/custom-pin/invoke/sayHello</code></p> <pre><code>{\n  \"input\": {},\n  \"message\": {\n    \"data\": [\n      {\n        \"value\": \"payload here\"\n      }\n    ]\n  }\n}\n</code></pre>"},{"location":"tutorials/custom_contracts/pinning/#listening-for-events","title":"Listening for events","text":"<p>All parties that receive the message will receive a <code>message_confirmed</code> on their event listeners. This event confirms that the off-chain payload has been received (via data exchange or shared storage) and that the blockchain transaction has been received and sequenced. It is guaranteed that these <code>message_confirmed</code> events will be ordered based on the sequence of the on-chain transactions, regardless of when the off-chain payload becomes available. This means that all parties will order messages on a given topic in exactly the same order, allowing for deterministic but decentralized event-driven architecture.</p>"},{"location":"tutorials/custom_contracts/tezos/","title":"Work with Tezos smart contracts","text":"<p>This guide describes the steps to deploy a smart contract to a Tezos blockchain and use FireFly to interact with it in order to submit transactions, query for states and listening for events.</p>"},{"location":"tutorials/custom_contracts/tezos/#smart-contract-languages","title":"Smart Contract Languages","text":"<p>Smart contracts on Tezos can be programmed using familiar, developer-friendly languages. All features available on Tezos can be written in any of the high-level languages used to write smart contracts, such as Archetype, LIGO, and SmartPy. These languages all compile down to Michelson and you can switch between languages based on your preferences and projects.</p> <p>NOTE: For this tutorial we are going to use SmartPy for building Tezos smart contracts utilizing the broadly adopted Python language.</p>"},{"location":"tutorials/custom_contracts/tezos/#example-smart-contract","title":"Example smart contract","text":"<p>First let's look at a simple contract smart contract called <code>SimpleStorage</code>, which we will be using on a Tezos blockchain. Here we have one state variable called 'storedValue' and initialized with the value 12. During initialization the type of the variable was defined as 'int'. You can see more at SmartPy types. And then we added a simple test, which set the storage value to 15 and checks that the value was changed as expected.</p> <p>NOTE: Smart contract's tests (marked with <code>@sp.add_test</code> annotation) are used to verify the validity of contract entrypoints and do not affect the state of the contract during deployment.</p> <p>Here is the source for this contract:</p> <pre><code>import smartpy as sp\n\n@sp.module\ndef main():\n    # Declares a new contract\n    class SimpleStorage(sp.Contract):\n        # Storage. Persists in between transactions\n        def __init__(self, value):\n            self.data.x = value\n\n        # Allows the stored integer to be changed\n        @sp.entrypoint\n        def set(self, params):\n            self.data.x = params.value\n\n        # Returns the currently stored integer\n        @sp.onchain_view()\n        def get(self):\n            return self.data.x\n\n@sp.add_test()\ndef test():\n    # Create a test scenario\n    scenario = sp.test_scenario(\"Test simple storage\", main)\n    scenario.h1(\"SimpleStorage\")\n\n    # Initialize the contract\n    c = main.SimpleStorage(12)\n\n    # Run some test cases\n    scenario += c\n    c.set(value=15)\n    scenario.verify(c.data.x == 15)\n    scenario.verify(scenario.compute(c.get()) == 15)\n</code></pre>"},{"location":"tutorials/custom_contracts/tezos/#contract-deployment-via-smartpy-ide","title":"Contract deployment via SmartPy IDE","text":"<p>To deploy the contract, we will use SmartPy IDE.</p> <ol> <li>Open an IDE;</li> <li>Paste the contract code;</li> <li>Click \"Run code\" button;</li> <li>Then you will see \"Show Michelson\" button, click on that;</li> <li>On the opened pop-up click button \"Deploy Contract\";</li> <li>Choose the Ghostnet network;</li> <li>Select an account, which you're going to use to deploy the contract;</li> <li>Click \"Estimate Cost From RPC\" button;</li> <li>Click \"Deploy Contract\" button;</li> </ol> <p> </p> <p>Here we can see that our new contract address is <code>KT1ED4gj2xZnp8318yxa5NpvyvW15pqe4yFg</code>. This is the address that we will reference in the rest of this guide.</p>"},{"location":"tutorials/custom_contracts/tezos/#contract-deployment-via-http-api","title":"Contract deployment via HTTP API","text":"<p>To deploy the contract we can use HTTP API: <code>POST</code> <code>http://localhost:5000/api/v1/namespaces/default/contracts/deploy</code></p> <pre><code>{\n  \"contract\": {\n    \"code\": [\n      {\n        \"prim\": \"storage\",\n        \"args\": [\n          {\n            \"prim\": \"int\"\n          }\n        ]\n      },\n      {\n        \"prim\": \"parameter\",\n        \"args\": [\n          {\n            \"prim\": \"int\",\n            \"annots\": [\"%set\"]\n          }\n        ]\n      },\n      {\n        \"prim\": \"code\",\n        \"args\": [\n          [\n            {\n              \"prim\": \"CAR\"\n            },\n            {\n              \"prim\": \"NIL\",\n              \"args\": [\n                {\n                  \"prim\": \"operation\"\n                }\n              ]\n            },\n            {\n              \"prim\": \"PAIR\"\n            }\n          ]\n        ]\n      },\n      {\n        \"prim\": \"view\",\n        \"args\": [\n          {\n            \"string\": \"get\"\n          },\n          {\n            \"prim\": \"unit\"\n          },\n          {\n            \"prim\": \"int\"\n          },\n          [\n            {\n              \"prim\": \"CDR\"\n            }\n          ]\n        ]\n      }\n    ],\n    \"storage\": {\n      \"int\": \"12\"\n    }\n  }\n}\n</code></pre> <p>The <code>contract</code> field has two fields - <code>code</code> with Michelson code of contract and <code>storage</code> with initial Storage values.</p> <p>The response of request above:</p> <pre><code>{\n  \"id\": \"0c3810c7-baed-4077-9d2c-af316a4a567f\",\n  \"namespace\": \"default\",\n  \"tx\": \"21d03e6d-d106-48f4-aacd-688bf17b71fd\",\n  \"type\": \"blockchain_deploy\",\n  \"status\": \"Pending\",\n  \"plugin\": \"tezos\",\n  \"input\": {\n    \"contract\": {\n      \"code\": [\n        {\n          \"args\": [\n            {\n              \"prim\": \"int\"\n            }\n          ],\n          \"prim\": \"storage\"\n        },\n        {\n          \"args\": [\n            {\n              \"annots\": [\"%set\"],\n              \"prim\": \"int\"\n            }\n          ],\n          \"prim\": \"parameter\"\n        },\n        {\n          \"args\": [\n            [\n              {\n                \"prim\": \"CAR\"\n              },\n              {\n                \"args\": [\n                  {\n                    \"prim\": \"operation\"\n                  }\n                ],\n                \"prim\": \"NIL\"\n              },\n              {\n                \"prim\": \"PAIR\"\n              }\n            ]\n          ],\n          \"prim\": \"code\"\n        },\n        {\n          \"args\": [\n            {\n              \"string\": \"get\"\n            },\n            {\n              \"prim\": \"unit\"\n            },\n            {\n              \"prim\": \"int\"\n            },\n            [\n              {\n                \"prim\": \"CDR\"\n              }\n            ]\n          ],\n          \"prim\": \"view\"\n        }\n      ],\n      \"storage\": {\n        \"int\": \"12\"\n      }\n    },\n    \"definition\": null,\n    \"input\": null,\n    \"key\": \"tz1V3spuktTP2wuEZP7D2hJruLZ5uJTuJk31\",\n    \"options\": null\n  },\n  \"created\": \"2024-04-01T14:20:20.665039Z\",\n  \"updated\": \"2024-04-01T14:20:20.665039Z\"\n}\n</code></pre> <p>The success result of deploy can be checked by <code>GET</code> <code>http://localhost:5000/api/v1/namespaces/default/operations/0c3810c7-baed-4077-9d2c-af316a4a567f</code> where <code>0c3810c7-baed-4077-9d2c-af316a4a567f</code> is operation id from response above.</p> <p>The success response:</p> <pre><code>{\n  \"id\": \"0c3810c7-baed-4077-9d2c-af316a4a567f\",\n  \"namespace\": \"default\",\n  \"tx\": \"21d03e6d-d106-48f4-aacd-688bf17b71fd\",\n  \"type\": \"blockchain_deploy\",\n  \"status\": \"Succeeded\",\n  \"plugin\": \"tezos\",\n  \"input\": {\n    \"contract\": {\n      \"code\": [\n        {\n          \"args\": [\n            {\n              \"prim\": \"int\"\n            }\n          ],\n          \"prim\": \"storage\"\n        },\n        {\n          \"args\": [\n            {\n              \"annots\": [\"%set\"],\n              \"prim\": \"int\"\n            }\n          ],\n          \"prim\": \"parameter\"\n        },\n        {\n          \"args\": [\n            [\n              {\n                \"prim\": \"CAR\"\n              },\n              {\n                \"args\": [\n                  {\n                    \"prim\": \"operation\"\n                  }\n                ],\n                \"prim\": \"NIL\"\n              },\n              {\n                \"prim\": \"PAIR\"\n              }\n            ]\n          ],\n          \"prim\": \"code\"\n        },\n        {\n          \"args\": [\n            {\n              \"string\": \"get\"\n            },\n            {\n              \"prim\": \"unit\"\n            },\n            {\n              \"prim\": \"int\"\n            },\n            [\n              {\n                \"prim\": \"CDR\"\n              }\n            ]\n          ],\n          \"prim\": \"view\"\n        }\n      ],\n      \"storage\": {\n        \"int\": \"12\"\n      }\n    },\n    \"definition\": null,\n    \"input\": null,\n    \"key\": \"tz1V3spuktTP2wuEZP7D2hJruLZ5uJTuJk31\",\n    \"options\": null\n  },\n  \"output\": {\n    \"headers\": {\n      \"requestId\": \"default:0c3810c7-baed-4077-9d2c-af316a4a567f\",\n      \"type\": \"TransactionSuccess\"\n    },\n    \"protocolId\": \"ProxfordYmVfjWnRcgjWH36fW6PArwqykTFzotUxRs6gmTcZDuH\",\n    \"transactionHash\": \"ootDut4xxR2yeYz6JuySuyTVZnXgda2t8SYrk3iuJpm531TZuCj\"\n  },\n  \"created\": \"2024-04-01T14:20:20.665039Z\",\n  \"updated\": \"2024-04-01T14:20:20.665039Z\",\n  \"detail\": {\n    \"created\": \"2024-04-01T14:20:21.928976Z\",\n    \"firstSubmit\": \"2024-04-01T14:20:22.714493Z\",\n    \"from\": \"tz1V3spuktTP2wuEZP7D2hJruLZ5uJTuJk31\",\n    \"gasPrice\": \"0\",\n    \"historySummary\": [\n      {\n        \"count\": 1,\n        \"firstOccurrence\": \"2024-04-01T14:20:21.930764Z\",\n        \"lastOccurrence\": \"2024-04-01T14:20:21.930765Z\",\n        \"subStatus\": \"Received\"\n      },\n      {\n        \"action\": \"AssignNonce\",\n        \"count\": 2,\n        \"firstOccurrence\": \"2024-04-01T14:20:21.930767Z\",\n        \"lastOccurrence\": \"2024-04-01T14:20:22.714772Z\"\n      },\n      {\n        \"action\": \"RetrieveGasPrice\",\n        \"count\": 1,\n        \"firstOccurrence\": \"2024-04-01T14:20:22.714774Z\",\n        \"lastOccurrence\": \"2024-04-01T14:20:22.714774Z\"\n      },\n      {\n        \"action\": \"SubmitTransaction\",\n        \"count\": 1,\n        \"firstOccurrence\": \"2024-04-01T14:20:22.715269Z\",\n        \"lastOccurrence\": \"2024-04-01T14:20:22.715269Z\"\n      },\n      {\n        \"action\": \"ReceiveReceipt\",\n        \"count\": 1,\n        \"firstOccurrence\": \"2024-04-01T14:20:29.244396Z\",\n        \"lastOccurrence\": \"2024-04-01T14:20:29.244396Z\"\n      },\n      {\n        \"action\": \"Confirm\",\n        \"count\": 1,\n        \"firstOccurrence\": \"2024-04-01T14:20:29.244762Z\",\n        \"lastOccurrence\": \"2024-04-01T14:20:29.244762Z\"\n      }\n    ],\n    \"id\": \"default:0c3810c7-baed-4077-9d2c-af316a4a567f\",\n    \"lastSubmit\": \"2024-04-01T14:20:22.714493Z\",\n    \"nonce\": \"23094946\",\n    \"policyInfo\": {},\n    \"receipt\": {\n      \"blockHash\": \"BLvWL4t8GbaufGcQwiv3hHCsvgD6qwXfAXofyvojSMoFeGMXMR1\",\n      \"blockNumber\": \"5868268\",\n      \"contractLocation\": {\n        \"address\": \"KT1CkTPsgTUQxR3CCpvtrcuQFV5Jf7cJgHFg\"\n      },\n      \"extraInfo\": [\n        {\n          \"consumedGas\": \"584\",\n          \"contractAddress\": \"KT1CkTPsgTUQxR3CCpvtrcuQFV5Jf7cJgHFg\",\n          \"counter\": null,\n          \"errorMessage\": null,\n          \"fee\": null,\n          \"from\": null,\n          \"gasLimit\": null,\n          \"paidStorageSizeDiff\": \"75\",\n          \"status\": \"applied\",\n          \"storage\": null,\n          \"storageLimit\": null,\n          \"storageSize\": \"75\",\n          \"to\": null\n        }\n      ],\n      \"protocolId\": \"ProxfordYmVfjWnRcgjWH36fW6PArwqykTFzotUxRs6gmTcZDuH\",\n      \"success\": true,\n      \"transactionIndex\": \"0\"\n    },\n    \"sequenceId\": \"018e9a08-582a-01ec-9209-9d79ef742c9b\",\n    \"status\": \"Succeeded\",\n    \"transactionData\": \"c37274b662d68da8fdae2a02ad6c460a79933c70c6fa7500dc98a9ade6822f026d00673bb6e6298063f97940953de23d441ab20bf757f602a3cd810bad05b003000000000041020000003c0500045b00000004257365740501035b050202000000080316053d036d03420991000000130100000003676574036c035b020000000203170000000000000002000c\",\n    \"transactionHash\": \"ootDut4xxR2yeYz6JuySuyTVZnXgda2t8SYrk3iuJpm531TZuCj\",\n    \"transactionHeaders\": {\n      \"from\": \"tz1V3spuktTP2wuEZP7D2hJruLZ5uJTuJk31\",\n      \"nonce\": \"23094946\"\n    },\n    \"updated\": \"2024-04-01T14:20:29.245172Z\"\n  }\n}\n</code></pre>"},{"location":"tutorials/custom_contracts/tezos/#the-firefly-interface-format","title":"The FireFly Interface Format","text":"<p>As we know from the previous section - smart contracts on the Tezos blockchain are using the domain-specific, stack-based programming language called Michelson. It is a key component of the Tezos platform and plays a fundamental role in defining the behavior of smart contracts and facilitating their execution. This language is very efficient but also a bit tricky and challenging for learning, so in order to teach FireFly how to interact with the smart contract, we will be using FireFly Interface (FFI) to define the contract inteface which later will be encoded to Michelson.</p>"},{"location":"tutorials/custom_contracts/tezos/#schema-details","title":"Schema details","text":"<p>The <code>details</code> field is used to encapsulate blockchain specific type information about a specific field. (More details at schema details)</p>"},{"location":"tutorials/custom_contracts/tezos/#supported-tezos-types","title":"Supported Tezos types","text":"<ul> <li>nat</li> <li>integer</li> <li>string</li> <li>address</li> <li>bytes</li> <li>boolean</li> <li>variant</li> <li>list</li> <li>struct</li> <li>map</li> </ul>"},{"location":"tutorials/custom_contracts/tezos/#internal-type-vs-internal-schema","title":"Internal type vs Internal schema","text":"<p>internalType is a field which is used to describe tezos primitive types</p> <pre><code>{\n  \"details\": {\n    \"type\": \"address\",\n    \"internalType\": \"address\"\n  }\n}\n</code></pre> <p>internalSchema in turn is used to describe more complex tezos types as list, struct or variant</p> <p>Struct example:</p> <pre><code>{\n  \"details\": {\n    \"type\": \"schema\",\n    \"internalSchema\": {\n      \"type\": \"struct\",\n      \"args\": [\n        {\n          \"name\": \"metadata\",\n          \"type\": \"bytes\"\n        },\n        {\n          \"name\": \"token_id\",\n          \"type\": \"nat\"\n        }\n      ]\n    }\n  }\n}\n</code></pre> <p>List example:</p> <pre><code>{\n  \"details\": {\n    \"type\": \"schema\",\n    \"internalSchema\": {\n      \"type\": \"struct\",\n      \"args\": [\n        {\n          \"name\": \"metadata\",\n          \"type\": \"bytes\"\n        },\n        {\n          \"name\": \"token_id\",\n          \"type\": \"nat\"\n        }\n      ]\n    }\n  }\n}\n</code></pre> <p>Variant example:</p> <pre><code>{\n  \"details\": {\n    \"type\": \"schema\",\n    \"internalSchema\": {\n      \"type\": \"variant\",\n      \"variants\": [\"add_operator\", \"remove_operator\"],\n      \"args\": [\n        {\n          \"type\": \"struct\",\n          \"args\": [\n            {\n              \"name\": \"owner\",\n              \"type\": \"address\"\n            },\n            {\n              \"name\": \"operator\",\n              \"type\": \"address\"\n            },\n            {\n              \"name\": \"token_id\",\n              \"type\": \"nat\"\n            }\n          ]\n        }\n      ]\n    }\n  }\n}\n</code></pre> <p>Map example:</p> <pre><code>{\n  \"details\": {\n    \"type\": \"schema\",\n    \"internalSchema\": {\n      \"type\": \"map\",\n      \"args\": [\n        {\n          \"name\": \"key\",\n          \"type\": \"integer\"\n        },\n        {\n          \"name\": \"value\",\n          \"type\": \"string\"\n        }\n      ]\n    }\n  }\n}\n</code></pre>"},{"location":"tutorials/custom_contracts/tezos/#options","title":"Options","text":"<p>Option type is used to indicate a value as optional (see more at smartpy options)</p> <pre><code>{\n  \"details\": {\n    \"type\": \"string\",\n    \"internalType\": \"string\",\n    \"kind\": \"option\"\n  }\n}\n</code></pre>"},{"location":"tutorials/custom_contracts/tezos/#fa2-example","title":"FA2 example","text":"<p>The following FFI sample demonstrates the specification for the widely used FA2 (analogue of ERC721 for EVM) smart contract:</p> <pre><code>{\n  \"namespace\": \"default\",\n  \"name\": \"fa2\",\n  \"version\": \"v1.0.0\",\n  \"description\": \"\",\n  \"methods\": [\n    {\n      \"name\": \"burn\",\n      \"pathname\": \"\",\n      \"description\": \"\",\n      \"params\": [\n        {\n          \"name\": \"token_ids\",\n          \"schema\": {\n            \"type\": \"array\",\n            \"details\": {\n              \"type\": \"nat\",\n              \"internalType\": \"nat\"\n            }\n          }\n        }\n      ],\n      \"returns\": []\n    },\n    {\n      \"name\": \"destroy\",\n      \"pathname\": \"\",\n      \"description\": \"\",\n      \"params\": [],\n      \"returns\": []\n    },\n    {\n      \"name\": \"mint\",\n      \"pathname\": \"\",\n      \"description\": \"\",\n      \"params\": [\n        {\n          \"name\": \"owner\",\n          \"schema\": {\n            \"type\": \"string\",\n            \"details\": {\n              \"type\": \"address\",\n              \"internalType\": \"address\"\n            }\n          }\n        },\n        {\n          \"name\": \"requests\",\n          \"schema\": {\n            \"type\": \"array\",\n            \"details\": {\n              \"type\": \"schema\",\n              \"internalSchema\": {\n                \"type\": \"struct\",\n                \"args\": [\n                  {\n                    \"name\": \"metadata\",\n                    \"type\": \"bytes\"\n                  },\n                  {\n                    \"name\": \"token_id\",\n                    \"type\": \"nat\"\n                  }\n                ]\n              }\n            }\n          }\n        }\n      ],\n      \"returns\": []\n    },\n    {\n      \"name\": \"pause\",\n      \"pathname\": \"\",\n      \"description\": \"\",\n      \"params\": [\n        {\n          \"name\": \"pause\",\n          \"schema\": {\n            \"type\": \"boolean\",\n            \"details\": {\n              \"type\": \"boolean\",\n              \"internalType\": \"boolean\"\n            }\n          }\n        }\n      ],\n      \"returns\": []\n    },\n    {\n      \"name\": \"select\",\n      \"pathname\": \"\",\n      \"description\": \"\",\n      \"params\": [\n        {\n          \"name\": \"batch\",\n          \"schema\": {\n            \"type\": \"array\",\n            \"details\": {\n              \"type\": \"schema\",\n              \"internalSchema\": {\n                \"type\": \"struct\",\n                \"args\": [\n                  {\n                    \"name\": \"token_id\",\n                    \"type\": \"nat\"\n                  },\n                  {\n                    \"name\": \"recipient\",\n                    \"type\": \"address\"\n                  },\n                  {\n                    \"name\": \"token_id_start\",\n                    \"type\": \"nat\"\n                  },\n                  {\n                    \"name\": \"token_id_end\",\n                    \"type\": \"nat\"\n                  }\n                ]\n              }\n            }\n          }\n        }\n      ],\n      \"returns\": []\n    },\n    {\n      \"name\": \"transfer\",\n      \"pathname\": \"\",\n      \"description\": \"\",\n      \"params\": [\n        {\n          \"name\": \"batch\",\n          \"schema\": {\n            \"type\": \"array\",\n            \"details\": {\n              \"type\": \"schema\",\n              \"internalSchema\": {\n                \"type\": \"struct\",\n                \"args\": [\n                  {\n                    \"name\": \"from_\",\n                    \"type\": \"address\"\n                  },\n                  {\n                    \"name\": \"txs\",\n                    \"type\": \"list\",\n                    \"args\": [\n                      {\n                        \"type\": \"struct\",\n                        \"args\": [\n                          {\n                            \"name\": \"to_\",\n                            \"type\": \"address\"\n                          },\n                          {\n                            \"name\": \"token_id\",\n                            \"type\": \"nat\"\n                          },\n                          {\n                            \"name\": \"amount\",\n                            \"type\": \"nat\"\n                          }\n                        ]\n                      }\n                    ]\n                  }\n                ]\n              }\n            }\n          }\n        }\n      ],\n      \"returns\": []\n    },\n    {\n      \"name\": \"update_admin\",\n      \"pathname\": \"\",\n      \"description\": \"\",\n      \"params\": [\n        {\n          \"name\": \"admin\",\n          \"schema\": {\n            \"type\": \"string\",\n            \"details\": {\n              \"type\": \"address\",\n              \"internalType\": \"address\"\n            }\n          }\n        }\n      ],\n      \"returns\": []\n    },\n    {\n      \"name\": \"update_operators\",\n      \"pathname\": \"\",\n      \"description\": \"\",\n      \"params\": [\n        {\n          \"name\": \"requests\",\n          \"schema\": {\n            \"type\": \"array\",\n            \"details\": {\n              \"type\": \"schema\",\n              \"internalSchema\": {\n                \"type\": \"variant\",\n                \"variants\": [\"add_operator\", \"remove_operator\"],\n                \"args\": [\n                  {\n                    \"type\": \"struct\",\n                    \"args\": [\n                      {\n                        \"name\": \"owner\",\n                        \"type\": \"address\"\n                      },\n                      {\n                        \"name\": \"operator\",\n                        \"type\": \"address\"\n                      },\n                      {\n                        \"name\": \"token_id\",\n                        \"type\": \"nat\"\n                      }\n                    ]\n                  }\n                ]\n              }\n            }\n          }\n        }\n      ],\n      \"returns\": []\n    }\n  ],\n  \"events\": []\n}\n</code></pre>"},{"location":"tutorials/custom_contracts/tezos/#broadcast-the-contract-interface","title":"Broadcast the contract interface","text":"<p>Now that we have a FireFly Interface representation of our smart contract, we want to broadcast that to the entire network. This broadcast will be pinned to the blockchain, so we can always refer to this specific name and version, and everyone in the network will know exactly which contract interface we are talking about.</p> <p>We will use the FFI JSON constructed above and <code>POST</code> that to the <code>/contracts/interfaces</code> API endpoint.</p>"},{"location":"tutorials/custom_contracts/tezos/#request","title":"Request","text":"<p><code>POST</code> <code>http://localhost:5000/api/v1/namespaces/default/contracts/interfaces</code></p> <pre><code>{\n  \"namespace\": \"default\",\n  \"name\": \"simplestorage\",\n  \"version\": \"v1.0.0\",\n  \"description\": \"\",\n  \"methods\": [\n    {\n      \"name\": \"set\",\n      \"pathname\": \"\",\n      \"description\": \"\",\n      \"params\": [\n        {\n          \"name\": \"newValue\",\n          \"schema\": {\n            \"type\": \"integer\",\n            \"details\": {\n              \"type\": \"integer\",\n              \"internalType\": \"integer\"\n            }\n          }\n        }\n      ],\n      \"returns\": []\n    },\n    {\n      \"name\": \"get\",\n      \"pathname\": \"\",\n      \"description\": \"\",\n      \"params\": [],\n      \"returns\": []\n    }\n  ],\n  \"events\": []\n}\n</code></pre>"},{"location":"tutorials/custom_contracts/tezos/#response","title":"Response","text":"<pre><code>{\n  \"id\": \"f9e34787-e634-46cd-af47-b52c537404ff\",\n  \"namespace\": \"default\",\n  \"name\": \"simplestorage\",\n  \"description\": \"\",\n  \"version\": \"v1.0.0\",\n  \"methods\": [\n    {\n      \"id\": \"78f13a7f-7b85-47c3-bf51-346a9858c027\",\n      \"interface\": \"f9e34787-e634-46cd-af47-b52c537404ff\",\n      \"name\": \"set\",\n      \"namespace\": \"default\",\n      \"pathname\": \"set\",\n      \"description\": \"\",\n      \"params\": [\n        {\n          \"name\": \"newValue\",\n          \"schema\": {\n            \"type\": \"integer\",\n            \"details\": {\n              \"type\": \"integer\",\n              \"internalType\": \"integer\"\n            }\n          }\n        }\n      ],\n      \"returns\": []\n    },\n    {\n      \"id\": \"ee864e25-c3f7-42d3-aefd-a82f753e9002\",\n      \"interface\": \"f9e34787-e634-46cd-af47-b52c537404ff\",\n      \"name\": \"get\",\n      \"namespace\": \"tezos\",\n      \"pathname\": \"get\",\n      \"description\": \"\",\n      \"params\": [],\n      \"returns\": []\n    }\n  ]\n}\n</code></pre> <p>NOTE: We can broadcast this contract interface conveniently with the help of FireFly Sandbox running at <code>http://127.0.0.1:5108</code></p> <ul> <li>Go to the <code>Contracts Section</code></li> <li>Click on <code>Define a Contract Interface</code></li> <li>Select <code>FFI - FireFly Interface</code> in the <code>Interface Fromat</code> dropdown</li> <li>Copy the <code>FFI JSON</code> crafted by you into the <code>Schema</code> Field</li> <li>Click on <code>Run</code></li> </ul>"},{"location":"tutorials/custom_contracts/tezos/#create-an-http-api-for-the-contract","title":"Create an HTTP API for the contract","text":"<p>Now comes the fun part where we see some of the powerful, developer-friendly features of FireFly. The next thing we're going to do is tell FireFly to build an HTTP API for this smart contract, complete with an OpenAPI Specification and Swagger UI. As part of this, we'll also tell FireFly where the contract is on the blockchain.</p> <p>Like the interface broadcast above, this will also generate a broadcast which will be pinned to the blockchain so all the members of the network will be aware of and able to interact with this API.</p> <p>We need to copy the <code>id</code> field we got in the response from the previous step to the <code>interface.id</code> field in the request body below. We will also pick a name that will be part of the URL for our HTTP API, so be sure to pick a name that is URL friendly. In this case we'll call it <code>simple-storage</code>. Lastly, in the <code>location.address</code> field, we're telling FireFly where an instance of the contract is deployed on-chain.</p> <p>NOTE: The <code>location</code> field is optional here, but if it is omitted, it will be required in every request to invoke or query the contract. This can be useful if you have multiple instances of the same contract deployed to different addresses.</p>"},{"location":"tutorials/custom_contracts/tezos/#request_1","title":"Request","text":"<p><code>POST</code> <code>http://localhost:5000/api/v1/namespaces/default/apis</code></p> <pre><code>{\n  \"name\": \"simple-storage\",\n  \"interface\": {\n    \"id\": \"f9e34787-e634-46cd-af47-b52c537404ff\"\n  },\n  \"location\": {\n    \"address\": \"KT1ED4gj2xZnp8318yxa5NpvyvW15pqe4yFg\"\n  }\n}\n</code></pre>"},{"location":"tutorials/custom_contracts/tezos/#response_1","title":"Response","text":"<pre><code>{\n  \"id\": \"af09de97-741d-4f61-8d30-4db5e7460f76\",\n  \"namespace\": \"default\",\n  \"interface\": {\n    \"id\": \"f9e34787-e634-46cd-af47-b52c537404ff\"\n  },\n  \"location\": {\n    \"address\": \"KT1ED4gj2xZnp8318yxa5NpvyvW15pqe4yFg\"\n  },\n  \"name\": \"simple-storage\",\n  \"urls\": {\n    \"openapi\": \"http://127.0.0.1:5000/api/v1/namespaces/default/apis/simple-storage/api/swagger.json\",\n    \"ui\": \"http://127.0.0.1:5000/api/v1/namespaces/default/apis/simple-storage/api\"\n  }\n}\n</code></pre>"},{"location":"tutorials/custom_contracts/tezos/#view-openapi-spec-for-the-contract","title":"View OpenAPI spec for the contract","text":"<p>You'll notice in the response body that there are a couple of URLs near the bottom. If you navigate to the one labeled <code>ui</code> in your browser, you should see the Swagger UI for your smart contract.</p> <p></p>"},{"location":"tutorials/custom_contracts/tezos/#invoke-the-smart-contract","title":"Invoke the smart contract","text":"<p>Now that we've got everything set up, it's time to use our smart contract! We're going to make a <code>POST</code> request to the <code>invoke/set</code> endpoint to set the integer value on-chain. Let's set it to the value of <code>3</code> right now.</p>"},{"location":"tutorials/custom_contracts/tezos/#request_2","title":"Request","text":"<p><code>POST</code> <code>http://localhost:5000/api/v1/namespaces/default/apis/simple-storage/invoke/set</code></p> <pre><code>{\n  \"input\": {\n    \"newValue\": 3\n  }\n}\n</code></pre>"},{"location":"tutorials/custom_contracts/tezos/#response_2","title":"Response","text":"<pre><code>{\n  \"id\": \"87c7ee1b-33d1-46e2-b3f5-8566c14367cf\",\n  \"type\": \"blockchain_invoke\",\n  \"status\": \"Pending\",\n  \"...\"\n}\n</code></pre> <p>You'll notice that we got an ID back with status <code>Pending</code>, and that's expected due to the asynchronous programming model of working with smart contracts in FireFly. To see what the value is now, we can query the smart contract.</p>"},{"location":"tutorials/custom_contracts/tezos/#query-the-current-value","title":"Query the current value","text":"<p>To make a read-only request to the blockchain to check the current value of the stored integer, we can make a <code>POST</code> to the <code>query/get</code> endpoint.</p>"},{"location":"tutorials/custom_contracts/tezos/#request_3","title":"Request","text":"<p><code>POST</code> <code>http://localhost:5000/api/v1/namespaces/default/apis/simple-storage/query/get</code></p> <pre><code>{}\n</code></pre>"},{"location":"tutorials/custom_contracts/tezos/#response_3","title":"Response","text":"<pre><code>{\n  \"3\"\n}\n</code></pre> <p>NOTE: Some contracts may have queries that require input parameters. That's why the query endpoint is a <code>POST</code>, rather than a <code>GET</code> so that parameters can be passed as JSON in the request body. This particular function does not have any parameters, so we just pass an empty JSON object.</p>"},{"location":"tutorials/tokens/","title":"Use tokens","text":""},{"location":"tutorials/tokens/#quick-reference","title":"Quick reference","text":"<p>Tokens are a critical building block in many blockchain-backed applications. Fungible tokens can represent a store of value or a means of rewarding participation in a multi-party system, while non-fungible tokens provide a clear way to identify and track unique entities across the network. FireFly provides flexible mechanisms to operate on any type of token and to tie those operations to on- and off-chain data.</p> <ul> <li>FireFly provides an abstraction layer for multiple types of tokens</li> <li>Tokens are grouped into pools, which each represent a particular type or class of token</li> <li>Each pool is classified as fungible or non-fungible</li> <li>In the case of non-fungible tokens, the pool is subdivided into individual tokens with a unique token index</li> <li>Within a pool, you may mint (issue), transfer, and burn (redeem) tokens</li> <li>Each operation can be optionally accompanied by a broadcast or private message, which will be recorded alongside the transfer on-chain</li> <li>FireFly tracks a history of all token operations along with all current token balances</li> <li>The blockchain backing each token connector may be the same or different from the one backing FireFly message pinning</li> </ul>"},{"location":"tutorials/tokens/#what-is-a-pool","title":"What is a pool?","text":"<p>Token pools are a FireFly construct for describing a set of tokens. The exact definition of a token pool is dependent on the token connector implementation. Some examples of how pools might map to various well-defined Ethereum standards:</p> <ul> <li>ERC-1155: a single contract instance can efficiently allocate   many isolated pools of fungible or non-fungible tokens</li> <li>ERC-20 / ERC-777:   each contract instance represents a single fungible pool of value, e.g. \"a coin\"</li> <li>ERC-721: each contract instance represents a single pool of NFTs,   each with unique identities within the pool</li> <li>ERC-1400 / ERC-1410:   partially supported in the same manner as ERC-20/ERC-777, but would require new features for working with partitions</li> </ul> <p>These are provided as examples only - a custom token connector could be backed by any token technology (Ethereum or otherwise) as long as it can support the basic operations described here (create pool, mint, burn, transfer). Other FireFly repos include a sample implementation of a token connector for ERC-20 and ERC-721 as well as ERC-1155.</p>"},{"location":"tutorials/tokens/erc1155/","title":"Use ERC-1155 tokens","text":""},{"location":"tutorials/tokens/erc1155/#previous-steps-install-the-firefly-cli","title":"Previous steps: Install the FireFly CLI","text":"<p>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.</p> <p>\u2190 \u2460 Install the FireFly CLI</p>"},{"location":"tutorials/tokens/erc1155/#create-a-stack-with-an-erc-1155-connector","title":"Create a stack with an ERC-1155 connector","text":"<p>The default token connector that the FireFly CLI sets up is for ERC-20 and ERC-721. If you would like to work with ERC-1155 tokens, you need to create a stack that is configured to use that token connector. To do that, run:</p> <pre><code>ff init ethereum -t erc-1155\n</code></pre> <p>Then run:</p> <pre><code>ff start &lt;your_stack_name&gt;\n</code></pre>"},{"location":"tutorials/tokens/erc1155/#about-the-sample-token-contract","title":"About the sample token contract","text":"<p>When the FireFly CLI set up your FireFly stack, it also deployed a sample ERC-1155 contract that conforms to the expectations of the token connector. When you create a token pool through FireFly's token APIs, that contract will be used by default.</p> \u26a0\ufe0f WARNING: The default token contract that was deployed by the FireFly CLI is only provided for the purpose of learning about FireFly. It is not a production grade contract. If you intend to deploy a production application using tokens on FireFly, you should research token contract best practices. For details, please see the source code for the contract that was deployed."},{"location":"tutorials/tokens/erc1155/#use-the-sandbox-optional","title":"Use the Sandbox (optional)","text":"<p>At this point you could open the Sandbox at http://127.0.0.1:5109/home?action=tokens.pools and perform the functions outlined in the rest of this guide. Or you can keep reading to learn how to build HTTP requests to work with tokens in FireFly. </p>"},{"location":"tutorials/tokens/erc1155/#create-a-pool-using-default-token-contract","title":"Create a pool (using default token contract)","text":"<p>After your stack is up and running, the first thing you need to do is create a token pool. Every application will need at least one token pool. At a minimum, you must always specify a <code>name</code> and <code>type</code> (<code>fungible</code> or <code>nonfungible</code>) for the pool.</p> <p><code>POST</code> <code>http://127.0.0.1:5000/api/v1/namespaces/default/tokens/pools?publish=true</code></p> <p>NOTE: Without passing the query parameter <code>publish=true</code> when the token pool is created, it will initially be unpublished and not broadcasted to other members of the network (if configured in multi-party). To publish the token pool, a subsequent API call would need to be made to <code>/tokens/pools/{nameOrId}/publish</code></p> <pre><code>{\n  \"name\": \"testpool\",\n  \"type\": \"fungible\"\n}\n</code></pre> <p>Other parameters:</p> <ul> <li>You must specify a <code>connector</code> if you have configured multiple token connectors</li> <li>You may pass through a <code>config</code> object of additional parameters, if supported by your token connector</li> <li>You may specify a <code>key</code> understood by the connector (i.e. an Ethereum address) if you'd like to use a non-default signing identity</li> </ul>"},{"location":"tutorials/tokens/erc1155/#create-a-pool-from-a-deployed-token-contract","title":"Create a pool (from a deployed token contract)","text":"<p>If you wish to use a contract that is already on the chain, it is recommended that you first upload the ABI for your specific contract by creating a FireFly contract interface. This step is optional if you're certain that your ERC-1155 ABI conforms to the default expectations of the token connector, but is generally recommended.</p> <p>See the README of the token connector for details on what contract variants can currently be understood.</p> <p>You can pass a <code>config</code> object with an <code>address</code> when you make the request to create the token pool, and if you created a contract interface, you can include the <code>interface</code> ID as well.</p> <p><code>POST</code> <code>http://127.0.0.1:5000/api/v1/namespaces/default/tokens/pools?publish=true</code></p> <p>NOTE: Without passing the query parameter <code>publish=true</code> when the token pool is created, it will initially be unpublished and not broadcasted to other members of the network (if configured in multi-party). To publish the token pool, a subsequent API call would need to be made to <code>/tokens/pools/{nameOrId}/publish</code></p> <pre><code>{\n  \"name\": \"testpool\",\n  \"type\": \"fungible\",\n  \"interface\": {\n    \"id\": \"b9e5e1ce-97bb-4a35-a25c-52c7c3f523d8\"\n  },\n  \"config\": {\n    \"address\": \"0xb1C845D32966c79E23f733742Ed7fCe4B41901FC\"\n  }\n}\n</code></pre>"},{"location":"tutorials/tokens/erc1155/#mint-tokens","title":"Mint tokens","text":"<p>Once you have a token pool, you can mint tokens within it. With the default sample contract, only the creator of a pool is allowed to mint - but each contract may define its own permission model.</p> <p><code>POST</code> <code>http://127.0.0.1:5000/api/v1/namespaces/default/tokens/mint</code></p> <pre><code>{\n  \"amount\": 10\n}\n</code></pre> <p>Other parameters:</p> <ul> <li>You must specify a <code>pool</code> name if you've created more than one pool</li> <li>You may specify a <code>key</code> understood by the connector (i.e. an Ethereum address) if you'd like to use a non-default signing identity</li> <li>You may specify <code>to</code> if you'd like to send the minted tokens to a specific identity (default is the same as <code>key</code>)</li> </ul>"},{"location":"tutorials/tokens/erc1155/#transfer-tokens","title":"Transfer tokens","text":"<p>You may transfer tokens within a pool by specifying an amount and a destination understood by the connector (i.e. an Ethereum address). With the default sample contract, only the owner of a token or another approved account may transfer it away - but each contract may define its own permission model.</p> <p><code>POST</code> <code>http://127.0.0.1:5000/api/v1/namespaces/default/tokens/transfers</code></p> <pre><code>{\n  \"amount\": 1,\n  \"to\": \"0x07eab7731db665caf02bc92c286f51dea81f923f\"\n}\n</code></pre> <p>NOTE: When transferring a non-fungible token, the amount must always be <code>1</code>. The <code>tokenIndex</code> field is also required when transferring a non-fungible token.</p> <p>Other parameters:</p> <ul> <li>You must specify a <code>pool</code> name if you've created more than one pool</li> <li>You may specify a <code>key</code> understood by the connector (i.e. an Ethereum address) if you'd like to use a non-default signing identity</li> <li>You may specify <code>from</code> if you'd like to send tokens from a specific identity (default is the same as <code>key</code>)</li> </ul>"},{"location":"tutorials/tokens/erc1155/#sending-data-with-a-transfer","title":"Sending data with a transfer","text":"<p>All transfers (as well as mint/burn operations) support an optional <code>message</code> parameter that contains a broadcast or private message to be sent along with the transfer. This message follows the same convention as other FireFly messages, and may be comprised of text or blob data, and can provide context, metadata, or other supporting information about the transfer. The message will be batched, hashed, and pinned to the primary blockchain.</p> <p>The message ID and hash will also be sent to the token connector as part of the transfer operation, to be written to the token blockchain when the transaction is submitted. All recipients of the message will then be able to correlate the message with the token transfer.</p> <p><code>POST</code> <code>http://127.0.0.1:5000/api/v1/namespaces/default/tokens/transfers</code></p>"},{"location":"tutorials/tokens/erc1155/#broadcast-message","title":"Broadcast message","text":"<pre><code>{\n  \"amount\": 1,\n  \"to\": \"0x07eab7731db665caf02bc92c286f51dea81f923f\",\n  \"message\": {\n    \"data\": [\n      {\n        \"value\": \"payment for goods\"\n      }\n    ]\n  }\n}\n</code></pre>"},{"location":"tutorials/tokens/erc1155/#private-message","title":"Private message","text":"<pre><code>{\n  \"amount\": 1,\n  \"to\": \"0x07eab7731db665caf02bc92c286f51dea81f923f\",\n  \"message\": {\n    \"header\": {\n      \"type\": \"transfer_private\"\n    },\n    \"group\": {\n      \"members\": [\n        {\n          \"identity\": \"org_1\"\n        }\n      ]\n    },\n    \"data\": [\n      {\n        \"value\": \"payment for goods\"\n      }\n    ]\n  }\n}\n</code></pre> <p>Note that all parties in the network will be able to see the transfer (including the message ID and hash), but only the recipients of the message will be able to view the actual message data.</p>"},{"location":"tutorials/tokens/erc1155/#burn-tokens","title":"Burn tokens","text":"<p>You may burn tokens by simply specifying an amount. With the default sample contract, only the owner of a token or another approved account may burn it - but each connector may define its own permission model.</p> <p><code>POST</code> <code>http://127.0.0.1:5000/api/v1/namespaces/default/tokens/burn</code></p> <pre><code>{\n  \"amount\": 1\n}\n</code></pre> <p>NOTE: When burning a non-fungible token, the amount must always be <code>1</code>. The <code>tokenIndex</code> field is also required when burning a non-fungible token.</p> <p>Other parameters:</p> <ul> <li>You must specify a <code>pool</code> name if you've created more than one pool</li> <li>You may specify a <code>key</code> understood by the connector (i.e. an Ethereum address) if you'd like to use a non-default signing identity</li> <li>You may specify <code>from</code> if you'd like to burn tokens from a specific identity (default is the same as <code>key</code>)</li> </ul>"},{"location":"tutorials/tokens/erc1155/#token-approvals","title":"Token approvals","text":"<p>You can also approve other wallets to transfer tokens on your behalf with the <code>/approvals</code> API. The important fields in a token approval API request are as follows:</p> <ul> <li><code>approved</code>: Sets whether another account is allowed to transfer tokens out of this wallet or not. If not specified, will default to <code>true</code>. Setting to <code>false</code> can revoke an existing approval.</li> <li><code>operator</code>: The other account that is allowed to transfer tokens out of the wallet specified in the <code>key</code> field</li> <li><code>key</code>: The wallet address for the approval. If not set, it defaults to the address of the FireFly node submitting the transaction</li> </ul> <p>Here is an example request that would let the signing account <code>0x634ee8c7d0894d086c7af1fc8514736aed251528</code> transfer any amount of tokens from my wallet</p>"},{"location":"tutorials/tokens/erc1155/#request","title":"Request","text":"<p><code>POST</code> <code>http://127.0.0.1:5000/api/v1/namespaces/default/tokens/approvals</code></p> <pre><code>{\n  \"operator\": \"0x634ee8c7d0894d086c7af1fc8514736aed251528\"\n}\n</code></pre>"},{"location":"tutorials/tokens/erc1155/#response","title":"Response","text":"<pre><code>{\n  \"localId\": \"46fef50a-cf93-4f92-acf8-fae161b37362\",\n  \"pool\": \"e1477ed5-7282-48e5-ad9d-1612296bb29d\",\n  \"connector\": \"erc1155\",\n  \"key\": \"0x14ddd36a0c2f747130915bf5214061b1e4bec74c\",\n  \"operator\": \"0x634ee8c7d0894d086c7af1fc8514736aed251528\",\n  \"approved\": true,\n  \"tx\": {\n    \"type\": \"token_approval\",\n    \"id\": \"00faa011-f42c-403d-a047-2df7318967cd\"\n  }\n}\n</code></pre>"},{"location":"tutorials/tokens/erc20/","title":"Use ERC-20 tokens","text":""},{"location":"tutorials/tokens/erc20/#previous-steps-start-your-environment","title":"Previous steps: Start your environment","text":"<p>If you haven't started a FireFly stack already, please go to the Getting Started guide on how to Start your environment. This will set up a token connector that works with both ERC-20 and ERC-721 by default.</p> <p>\u2190 \u2461 Start your environment</p>"},{"location":"tutorials/tokens/erc20/#about-the-sample-token-contracts","title":"About the sample token contracts","text":"<p>If you are using the default ERC-20 / ERC-721 token connector, when the FireFly CLI set up your FireFly stack, it also deployed a token factory contract. When you create a token pool through FireFly's token APIs, the token factory contract will automatically deploy an ERC-20 or ERC-721 contract, based on the pool <code>type</code> in the API request.</p> \u26a0\ufe0f WARNING: The default token contract that was deployed by the FireFly CLI is only provided for the purpose of learning about FireFly. It is not a production grade contract. If you intend to deploy a production application using tokens on FireFly, you should research token contract best practices. For details, please see the source code for the contract that was deployed."},{"location":"tutorials/tokens/erc20/#use-the-sandbox-optional","title":"Use the Sandbox (optional)","text":"<p>At this point you could open the Sandbox at http://127.0.0.1:5109/home?action=tokens.pools and perform the functions outlined in the rest of this guide. Or you can keep reading to learn how to build HTTP requests to work with tokens in FireFly. </p>"},{"location":"tutorials/tokens/erc20/#create-a-pool-using-default-token-factory","title":"Create a pool (using default token factory)","text":"<p>After your stack is up and running, the first thing you need to do is create a token pool. Every application will need at least one token pool. At a minimum, you must always specify a <code>name</code> and <code>type</code> for the pool.</p> <p>If you're using the default ERC-20 / ERC-721 token connector and its sample token factory, it will automatically deploy a new ERC-20 contract instance.</p>"},{"location":"tutorials/tokens/erc20/#request","title":"Request","text":"<p><code>POST</code> <code>http://127.0.0.1:5000/api/v1/namespaces/default/tokens/pools?publish=true</code></p> <p>NOTE: Without passing the query parameter <code>publish=true</code> when the token pool is created, it will initially be unpublished and not broadcasted to other members of the network (if configured in multi-party). To publish the token pool, a subsequent API call would need to be made to <code>/tokens/pools/{nameOrId}/publish</code></p> <pre><code>{\n  \"name\": \"testpool\",\n  \"type\": \"fungible\"\n}\n</code></pre>"},{"location":"tutorials/tokens/erc20/#response","title":"Response","text":"<pre><code>{\n  \"id\": \"e1477ed5-7282-48e5-ad9d-1612296bb29d\",\n  \"type\": \"fungible\",\n  \"namespace\": \"default\",\n  \"name\": \"testpool\",\n  \"key\": \"0x14ddd36a0c2f747130915bf5214061b1e4bec74c\",\n  \"connector\": \"erc20_erc721\",\n  \"tx\": {\n    \"type\": \"token_pool\",\n    \"id\": \"e901921e-ffc4-4776-b20a-9e9face70a47\"\n  },\n  \"published\": true\n}\n</code></pre> <p>Other parameters:</p> <ul> <li>You must specify a <code>connector</code> if you have configured multiple token connectors</li> <li>You may pass through a <code>config</code> object of additional parameters, if supported by your token connector</li> <li>You may specify a <code>key</code> understood by the connector (i.e. an Ethereum address) if you'd like to use a non-default signing identity</li> </ul>"},{"location":"tutorials/tokens/erc20/#get-the-address-of-the-deployed-contract","title":"Get the address of the deployed contract","text":"<p>To lookup the address of the new contract, you can lookup the token pool by its ID on the API. Creating the token pool will also emit an event which will contain the address. To query the token pool you can make a <code>GET</code> request to the pool's ID:</p>"},{"location":"tutorials/tokens/erc20/#request_1","title":"Request","text":"<p><code>GET</code> <code>http://127.0.0.1:5000/api/v1/namespaces/default/tokens/pools/5811e8d5-52d0-44b1-8b75-73f5ff88f598</code></p>"},{"location":"tutorials/tokens/erc20/#response_1","title":"Response","text":"<pre><code>{\n  \"id\": \"e1477ed5-7282-48e5-ad9d-1612296bb29d\",\n  \"type\": \"fungible\",\n  \"namespace\": \"default\",\n  \"name\": \"testpool\",\n  \"standard\": \"ERC20\",\n  \"locator\": \"address=0xc4d02efcfab06f18ec0a68e00b98ffecf6bf7e3c&amp;schema=ERC20WithData&amp;type=fungible\",\n  \"decimals\": 18,\n  \"connector\": \"erc20_erc721\",\n  \"message\": \"7e2f6004-31fd-4ba8-9845-15c5fe5fbcd7\",\n  \"state\": \"confirmed\",\n  \"created\": \"2022-04-28T14:03:16.732222381Z\",\n  \"info\": {\n    \"address\": \"0xc4d02efcfab06f18ec0a68e00b98ffecf6bf7e3c\",\n    \"name\": \"testpool\",\n    \"schema\": \"ERC20WithData\"\n  },\n  \"tx\": {\n    \"type\": \"token_pool\",\n    \"id\": \"e901921e-ffc4-4776-b20a-9e9face70a47\"\n  }\n}\n</code></pre>"},{"location":"tutorials/tokens/erc20/#create-a-pool-from-a-deployed-token-contract","title":"Create a pool (from a deployed token contract)","text":"<p>If you wish to index and use a contract that is already on the chain, it is recommended that you first upload the ABI for your specific contract by creating a FireFly contract interface. This step is optional if you're certain that your ERC-20 ABI conforms to the default expectations of the token connector, but is generally recommended.</p> <p>See the README of the token connector for details on what contract variants can currently be understood.</p> <p>You can pass a <code>config</code> object with an <code>address</code> and <code>blockNumber</code> when you make the request to create the token pool, and if you created a contract interface, you can include the <code>interface</code> ID as well.</p>"},{"location":"tutorials/tokens/erc20/#request_2","title":"Request","text":"<p><code>POST</code> <code>http://127.0.0.1:5000/api/v1/namespaces/default/tokens/pools?publish=true</code></p> <p>NOTE: Without passing the query parameter <code>publish=true</code> when the token pool is created, it will initially be unpublished and not broadcasted to other members of the network (if configured in multi-party). To publish the token pool, a subsequent API call would need to be made to <code>/tokens/pools/{nameOrId}/publish</code></p> <pre><code>{\n  \"name\": \"testpool\",\n  \"type\": \"fungible\",\n  \"interface\": {\n    \"id\": \"b9e5e1ce-97bb-4a35-a25c-52c7c3f523d8\"\n  },\n  \"config\": {\n    \"address\": \"0xb1C845D32966c79E23f733742Ed7fCe4B41901FC\",\n    \"blockNumber\": \"0\"\n  }\n}\n</code></pre>"},{"location":"tutorials/tokens/erc20/#mint-tokens","title":"Mint tokens","text":"<p>Once you have a token pool, you can mint tokens within it. When using the sample contract deployed by the CLI, only the creator of a pool is allowed to mint, but a different contract may define its own permission model.</p> <p>NOTE: The default sample contract uses 18 decimal places. This means that if you want to create 100 tokens, the number submitted to the API / blockchain should actually be 100\u00d710<sup>18</sup> = <code>100000000000000000000</code>. This allows users to work with \"fractional\" tokens even though Ethereum virtual machines only support integer arithmetic.</p>"},{"location":"tutorials/tokens/erc20/#request_3","title":"Request","text":"<p><code>POST</code> <code>http://127.0.0.1:5000/api/v1/namespaces/default/tokens/mint</code></p> <pre><code>{\n  \"amount\": \"100000000000000000000\"\n}\n</code></pre>"},{"location":"tutorials/tokens/erc20/#response_2","title":"Response","text":"<pre><code>{\n  \"type\": \"mint\",\n  \"localId\": \"835fe2a1-594b-4336-bc1d-b2f59d51064b\",\n  \"pool\": \"e1477ed5-7282-48e5-ad9d-1612296bb29d\",\n  \"connector\": \"erc20_erc721\",\n  \"key\": \"0x14ddd36a0c2f747130915bf5214061b1e4bec74c\",\n  \"from\": \"0x14ddd36a0c2f747130915bf5214061b1e4bec74c\",\n  \"to\": \"0x14ddd36a0c2f747130915bf5214061b1e4bec74c\",\n  \"amount\": \"100000000000000000000\",\n  \"tx\": {\n    \"type\": \"token_transfer\",\n    \"id\": \"3fc97e24-fde1-4e80-bd82-660e479c0c43\"\n  }\n}\n</code></pre> <p>Other parameters:</p> <ul> <li>You must specify a <code>pool</code> name if you've created more than one pool</li> <li>You may specify a <code>key</code> understood by the connector (i.e. an Ethereum address) if you'd like to use a non-default signing identity</li> <li>You may specify <code>to</code> if you'd like to send the minted tokens to a specific identity (default is the same as <code>key</code>)</li> </ul>"},{"location":"tutorials/tokens/erc20/#transfer-tokens","title":"Transfer tokens","text":"<p>You may transfer tokens within a pool by specifying an amount and a destination understood by the connector (i.e. an Ethereum address). With the default sample contract, only the owner of the tokens or another approved account may transfer their tokens, but a different contract may define its own permission model.</p>"},{"location":"tutorials/tokens/erc20/#request_4","title":"Request","text":"<p><code>POST</code> <code>http://127.0.0.1:5000/api/v1/namespaces/default/tokens/transfers</code></p> <pre><code>{\n  \"amount\": \"10000000000000000000\",\n  \"to\": \"0xa4222a4ae19448d43a338e6586edd5fb2ac398e1\"\n}\n</code></pre>"},{"location":"tutorials/tokens/erc20/#response_3","title":"Response","text":"<pre><code>{\n  \"type\": \"transfer\",\n  \"localId\": \"61f0a71f-712b-4778-8b37-784fbee52657\",\n  \"pool\": \"e1477ed5-7282-48e5-ad9d-1612296bb29d\",\n  \"connector\": \"erc20_erc721\",\n  \"key\": \"0x14ddd36a0c2f747130915bf5214061b1e4bec74c\",\n  \"from\": \"0x14ddd36a0c2f747130915bf5214061b1e4bec74c\",\n  \"to\": \"0xa4222a4ae19448d43a338e6586edd5fb2ac398e1\",\n  \"amount\": \"10000000000000000000\",\n  \"tx\": {\n    \"type\": \"token_transfer\",\n    \"id\": \"c0c316a3-23a9-42f3-89b3-1cfdba6c948d\"\n  }\n}\n</code></pre> <p>Other parameters:</p> <ul> <li>You must specify a <code>pool</code> name if you've created more than one pool</li> <li>You may specify a <code>key</code> understood by the connector (i.e. an Ethereum address) if you'd like to use a non-default signing identity</li> <li>You may specify <code>from</code> if you'd like to send tokens from a specific identity (default is the same as <code>key</code>)</li> </ul>"},{"location":"tutorials/tokens/erc20/#sending-data-with-a-transfer","title":"Sending data with a transfer","text":"<p>All transfers (as well as mint/burn operations) support an optional <code>message</code> parameter that contains a broadcast or private message to be sent along with the transfer. This message follows the same convention as other FireFly messages, and may be comprised of text or blob data, and can provide context, metadata, or other supporting information about the transfer. The message will be batched, hashed, and pinned to the primary blockchain.</p> <p>The message ID and hash will also be sent to the token connector as part of the transfer operation, to be written to the token blockchain when the transaction is submitted. All recipients of the message will then be able to correlate the message with the token transfer.</p> <p><code>POST</code> <code>http://127.0.0.1:5000/api/v1/namespaces/default/tokens/transfers</code></p>"},{"location":"tutorials/tokens/erc20/#broadcast-message","title":"Broadcast message","text":"<pre><code>{\n  \"amount\": 1,\n  \"to\": \"0x07eab7731db665caf02bc92c286f51dea81f923f\",\n  \"message\": {\n    \"data\": [\n      {\n        \"value\": \"payment for goods\"\n      }\n    ]\n  }\n}\n</code></pre>"},{"location":"tutorials/tokens/erc20/#private-message","title":"Private message","text":"<pre><code>{\n  \"amount\": 1,\n  \"to\": \"0x07eab7731db665caf02bc92c286f51dea81f923f\",\n  \"message\": {\n    \"header\": {\n      \"type\": \"transfer_private\"\n    },\n    \"group\": {\n      \"members\": [\n        {\n          \"identity\": \"org_1\"\n        }\n      ]\n    },\n    \"data\": [\n      {\n        \"value\": \"payment for goods\"\n      }\n    ]\n  }\n}\n</code></pre> <p>Note that all parties in the network will be able to see the transfer (including the message ID and hash), but only the recipients of the message will be able to view the actual message data.</p>"},{"location":"tutorials/tokens/erc20/#burn-tokens","title":"Burn tokens","text":"<p>You may burn tokens by simply specifying an amount. With the default sample contract, only the owner of a token or another approved account may burn it, but a different contract may define its own permission model.</p> <p><code>POST</code> <code>http://127.0.0.1:5000/api/v1/namespaces/default/tokens/burn</code></p> <pre><code>{\n  \"amount\": 1\n}\n</code></pre> <p>Other parameters:</p> <ul> <li>You must specify a <code>pool</code> name if you've created more than one pool</li> <li>You may specify a <code>key</code> understood by the connector (i.e. an Ethereum address) if you'd like to use a non-default signing identity</li> <li>You may specify <code>from</code> if you'd like to burn tokens from a specific identity (default is the same as <code>key</code>)</li> </ul>"},{"location":"tutorials/tokens/erc20/#token-approvals","title":"Token approvals","text":"<p>You can also approve other wallets to transfer tokens on your behalf with the <code>/approvals</code> API. The important fields in a token approval API request are as follows:</p> <ul> <li><code>approved</code>: Sets whether another account is allowed to transfer tokens out of this wallet or not. If not specified, will default to <code>true</code>. Setting to <code>false</code> can revoke an existing approval.</li> <li><code>operator</code>: The other account that is allowed to transfer tokens out of the wallet specified in the <code>key</code> field.</li> <li><code>config.allowance</code>: The number of tokens the other account is allowed to transfer. If <code>0</code> or not set, the approval is valid for any number.</li> <li><code>key</code>: The wallet address for the approval. If not set, it defaults to the address of the FireFly node submitting the transaction.</li> </ul> <p>Here is an example request that would let the signing account <code>0x634ee8c7d0894d086c7af1fc8514736aed251528</code> transfer up to 10\u00d710<sup>18</sup> (<code>10000000000000000000</code>) tokens from my wallet</p>"},{"location":"tutorials/tokens/erc20/#request_5","title":"Request","text":"<p><code>POST</code> <code>http://127.0.0.1:5000/api/v1/namespaces/default/tokens/approvals</code></p> <pre><code>{\n  \"operator\": \"0x634ee8c7d0894d086c7af1fc8514736aed251528\",\n  \"config\": {\n    \"allowance\": \"10000000000000000000\"\n  }\n}\n</code></pre>"},{"location":"tutorials/tokens/erc20/#response_4","title":"Response","text":"<pre><code>{\n  \"localId\": \"46fef50a-cf93-4f92-acf8-fae161b37362\",\n  \"pool\": \"e1477ed5-7282-48e5-ad9d-1612296bb29d\",\n  \"connector\": \"erc20_erc721\",\n  \"key\": \"0x14ddd36a0c2f747130915bf5214061b1e4bec74c\",\n  \"operator\": \"0x634ee8c7d0894d086c7af1fc8514736aed251528\",\n  \"approved\": true,\n  \"tx\": {\n    \"type\": \"token_approval\",\n    \"id\": \"00faa011-f42c-403d-a047-2df7318967cd\"\n  },\n  \"config\": {\n    \"allowance\": \"10000000000000000000\"\n  }\n}\n</code></pre>"},{"location":"tutorials/tokens/erc20/#use-metamask","title":"Use Metamask","text":"<p>Now that you have an ERC-20 contract up and running, you may be wondering how to use Metamask (or some other wallet) with this contract. This section will walk you through how to connect Metamask to the blockchain and token contract that FireFly is using.</p>"},{"location":"tutorials/tokens/erc20/#configure-a-new-network","title":"Configure a new network","text":"<p>The first thing we need to do is tell Metamask how to connect to our local blockchain node. To do that:</p> <ul> <li>Click your account icon</li> <li> <p>In the drop down menu, click Settings </p> </li> <li> <p>On the left hand side of the page, click Networks</p> </li> <li> <p>Click the Add a network button   </p> </li> <li> <p>Fill in the network details:</p> </li> <li>Network Name: <code>FireFly</code> (could be any name)</li> <li>New RPC URL: <code>http://127.0.0.1:5100</code></li> <li>Chain ID: <code>2021</code></li> <li>Currency Symbol: ETH</li> <li>Click Save </li> </ul>"},{"location":"tutorials/tokens/erc20/#import-tokens","title":"Import tokens","text":"<p>Metamask won't know about our custom ERC-20 contract until we give it the Ethereum address for the contract, so that's what we'll do next.</p> <ul> <li> <p>Click on Import tokens </p> </li> <li> <p>Enter the Ethereum address of the contract</p> </li> <li>Enter a Token Symbol (can be anything you want)</li> <li>Click Add Custom Token</li> </ul> <p>NOTE: You can find the address of your contract from the response to the request to create the token pool above. You can also do a <code>GET</code> to <code>http://127.0.0.1:5000/api/v1/namespaces/default/tokens/pools</code> to lookup your configured token pools.</p> <p></p>"},{"location":"tutorials/tokens/erc20/#transfer-tokens_1","title":"Transfer tokens","text":"<p>Now you can copy your account address from your Metamask wallet, and perform a transfer from FireFly's API (as described above) to your Metamask address.</p> <p></p> <p>After a couple seconds, you should see your tokens show up in your Metamask wallet.</p> <p></p> <p>You can also send tokens to a FireFly address or any other Ethereum address from your Metamask wallet.</p> <p>NOTE: You can find the Ethereum addresses for organizations in your FireFly network in the Network \u2192 Organizations page in the FireFly explorer. Click on an organization and look under the Verifiers header for the organization's Ethereum address.</p> <p></p>"},{"location":"tutorials/tokens/erc721/","title":"Use ERC-721 tokens","text":""},{"location":"tutorials/tokens/erc721/#previous-steps-start-your-environment","title":"Previous steps: Start your environment","text":"<p>If you haven't started a FireFly stack already, please go to the Getting Started guide on how to Start your environment. This will set up a token connector that works with both ERC-20 and ERC-721 by default.</p> <p>\u2190 \u2461 Start your environment</p>"},{"location":"tutorials/tokens/erc721/#about-the-sample-token-contracts","title":"About the sample token contracts","text":"<p>If you are using the default ERC-20 / ERC-721 token connector, when the FireFly CLI set up your FireFly stack, it also deployed a token factory contract. When you create a token pool through FireFly's token APIs, the token factory contract will automatically deploy an ERC-20 or ERC-721 contract, based on the pool <code>type</code> in the API request.</p> \u26a0\ufe0f WARNING: The default token contract that was deployed by the FireFly CLI is only provided for the purpose of learning about FireFly. It is not a production grade contract. If you intend to deploy a production application using tokens on FireFly, you should research token contract best practices. For details, please see the source code for the contract that was deployed."},{"location":"tutorials/tokens/erc721/#use-the-sandbox-optional","title":"Use the Sandbox (optional)","text":"<p>At this point you could open the Sandbox at http://127.0.0.1:5109/home?action=tokens.pools and perform the functions outlined in the rest of this guide. Or you can keep reading to learn how to build HTTP requests to work with tokens in FireFly. </p>"},{"location":"tutorials/tokens/erc721/#create-a-pool-using-default-token-factory","title":"Create a pool (using default token factory)","text":"<p>After your stack is up and running, the first thing you need to do is create a token pool. Every application will need at least one token pool. At a minimum, you must always specify a <code>name</code> and <code>type</code> for the pool.</p> <p>If you're using the default ERC-20 / ERC-721 token connector and its sample token factory, it will automatically deploy a new ERC-721 contract instance.</p>"},{"location":"tutorials/tokens/erc721/#request","title":"Request","text":"<p><code>POST</code> <code>http://127.0.0.1:5000/api/v1/namespaces/default/tokens/pools?publish=true</code></p> <p>NOTE: Without passing the query parameter <code>publish=true</code> when the token pool is created, it will initially be unpublished and not broadcasted to other members of the network (if configured in multi-party). To publish the token pool, a subsequent API call would need to be made to <code>/tokens/pools/{nameOrId}/publish</code></p> <pre><code>{\n  \"type\": \"nonfungible\",\n  \"name\": \"nfts\"\n}\n</code></pre>"},{"location":"tutorials/tokens/erc721/#response","title":"Response","text":"<pre><code>{\n  \"id\": \"a92a0a25-b886-4b43-931f-4add2840258a\",\n  \"type\": \"nonfungible\",\n  \"namespace\": \"default\",\n  \"name\": \"nfts\",\n  \"key\": \"0x14ddd36a0c2f747130915bf5214061b1e4bec74c\",\n  \"connector\": \"erc20_erc721\",\n  \"tx\": {\n    \"type\": \"token_pool\",\n    \"id\": \"00678116-89d2-4295-990c-bd5ffa6e2434\"\n  },\n  \"published\": true\n}\n</code></pre> <p>Other parameters:</p> <ul> <li>You must specify a <code>connector</code> if you have configured multiple token connectors</li> <li>You may pass through a <code>config</code> object of additional parameters, if supported by your token connector</li> <li>You may specify a <code>key</code> understood by the connector (i.e. an Ethereum address) if you'd like to use a non-default signing identity</li> </ul>"},{"location":"tutorials/tokens/erc721/#get-the-address-of-the-deployed-contract","title":"Get the address of the deployed contract","text":"<p>To lookup the address of the new contract, you can lookup the token pool by its ID on the API. Creating the token pool will also emit an event which will contain the address. To query the token pool you can make a <code>GET</code> request to the pool's ID:</p>"},{"location":"tutorials/tokens/erc721/#request_1","title":"Request","text":"<p><code>GET</code> <code>http://127.0.0.1:5000/api/v1/namespaces/default/tokens/pools/5811e8d5-52d0-44b1-8b75-73f5ff88f598</code></p>"},{"location":"tutorials/tokens/erc721/#response_1","title":"Response","text":"<pre><code>{\n  \"id\": \"a92a0a25-b886-4b43-931f-4add2840258a\",\n  \"type\": \"nonfungible\",\n  \"namespace\": \"default\",\n  \"name\": \"nfts\",\n  \"standard\": \"ERC721\",\n  \"locator\": \"address=0xc4d02efcfab06f18ec0a68e00b98ffecf6bf7e3c&amp;schema=ERC721WithData&amp;type=nonfungible\",\n  \"connector\": \"erc20_erc721\",\n  \"message\": \"53d95dda-e8ca-4546-9226-a0fdc6ec03ec\",\n  \"state\": \"confirmed\",\n  \"created\": \"2022-04-29T12:03:51.971349509Z\",\n  \"info\": {\n    \"address\": \"0xc4d02efcfab06f18ec0a68e00b98ffecf6bf7e3c\",\n    \"name\": \"nfts\",\n    \"schema\": \"ERC721WithData\"\n  },\n  \"tx\": {\n    \"type\": \"token_pool\",\n    \"id\": \"00678116-89d2-4295-990c-bd5ffa6e2434\"\n  }\n}\n</code></pre>"},{"location":"tutorials/tokens/erc721/#create-a-pool-from-a-deployed-token-contract","title":"Create a pool (from a deployed token contract)","text":"<p>If you wish to index and use a contract that is already on the chain, it is recommended that you first upload the ABI for your specific contract by creating a FireFly contract interface. This step is optional if you're certain that your ERC-721 ABI conforms to the default expectations of the token connector, but is generally recommended.</p> <p>See the README of the token connector for details on what contract variants can currently be understood.</p> <p>You can pass a <code>config</code> object with an <code>address</code> and <code>blockNumber</code> when you make the request to create the token pool, and if you created a contract interface, you can include the <code>interface</code> ID as well.</p>"},{"location":"tutorials/tokens/erc721/#request_2","title":"Request","text":"<p><code>POST</code> <code>http://127.0.0.1:5000/api/v1/namespaces/default/tokens/pools?publish=true</code></p> <p>NOTE: Without passing the query parameter <code>publish=true</code> when the token pool is created, it will initially be unpublished and not broadcasted to other members of the network (if configured in multi-party). To publish the token pool, a subsequent API call would need to be made to <code>/tokens/pools/{nameOrId}/publish</code></p> <pre><code>{\n  \"name\": \"testpool\",\n  \"type\": \"nonfungible\",\n  \"interface\": {\n    \"id\": \"b9e5e1ce-97bb-4a35-a25c-52c7c3f523d8\"\n  },\n  \"config\": {\n    \"address\": \"0xb1C845D32966c79E23f733742Ed7fCe4B41901FC\",\n    \"blockNumber\": \"0\"\n  }\n}\n</code></pre>"},{"location":"tutorials/tokens/erc721/#mint-a-token","title":"Mint a token","text":"<p>Once you have a token pool, you can mint tokens within it. When using the sample contract deployed by the CLI, the following are true:</p> <ul> <li>only the creator of a pool is allowed to mint within that pool</li> <li>the <code>tokenIndex</code> must be set to a unique value</li> <li>the <code>amount</code> must be <code>1</code></li> </ul> <p>A different ERC-721 contract may define its own requirements.</p>"},{"location":"tutorials/tokens/erc721/#request_3","title":"Request","text":"<p><code>POST</code> <code>http://127.0.0.1:5000/api/v1/namespaces/default/tokens/mint</code></p> <pre><code>{\n  \"amount\": \"1\",\n  \"tokenIndex\": \"1\"\n}\n</code></pre>"},{"location":"tutorials/tokens/erc721/#response_2","title":"Response","text":"<pre><code>{\n  \"type\": \"mint\",\n  \"localId\": \"2de2e05e-9474-4a08-a64f-2cceb076bdaa\",\n  \"pool\": \"a92a0a25-b886-4b43-931f-4add2840258a\",\n  \"connector\": \"erc20_erc721\",\n  \"key\": \"0x14ddd36a0c2f747130915bf5214061b1e4bec74c\",\n  \"from\": \"0x14ddd36a0c2f747130915bf5214061b1e4bec74c\",\n  \"to\": \"0x14ddd36a0c2f747130915bf5214061b1e4bec74c\",\n  \"amount\": \"1\",\n  \"tx\": {\n    \"type\": \"token_transfer\",\n    \"id\": \"0fad4581-7cb2-42c7-8f78-62d32205c2c2\"\n  }\n}\n</code></pre> <p>Other parameters:</p> <ul> <li>You must specify a <code>pool</code> name if you've created more than one pool</li> <li>You may specify a <code>key</code> understood by the connector (i.e. an Ethereum address) if you'd like to use a non-default signing identity</li> <li>You may specify <code>to</code> if you'd like to send the minted tokens to a specific identity (default is the same as <code>key</code>)</li> </ul>"},{"location":"tutorials/tokens/erc721/#transfer-a-token","title":"Transfer a token","text":"<p>You may transfer tokens within a pool by specifying an amount and a destination understood by the connector (i.e. an Ethereum address). With the default sample contract, only the owner of the tokens or another approved account may transfer their tokens, but a different contract may define its own permission model.</p> <p>When transferring an NFT, you must also specify the <code>tokenIndex</code> that you wish to transfer. The <code>tokenIndex</code> is simply the ID of the specific NFT within the pool that you wish to transfer.</p> <p>NOTE: When transferring NFTs the <code>amount</code> must be <code>1</code>. If you wish to transfer more NFTs, simply call the endpoint multiple times, specifying the token index of each token to transfer.</p>"},{"location":"tutorials/tokens/erc721/#request_4","title":"Request","text":"<p><code>POST</code> <code>http://127.0.0.1:5000/api/v1/namespaces/default/tokens/transfers</code></p> <pre><code>{\n  \"amount\": \"1\",\n  \"tokenIndex\": \"1\",\n  \"to\": \"0xa4222a4ae19448d43a338e6586edd5fb2ac398e1\"\n}\n</code></pre>"},{"location":"tutorials/tokens/erc721/#response_3","title":"Response","text":"<pre><code>{\n  \"type\": \"transfer\",\n  \"localId\": \"f5fd0d13-db13-4d70-9a99-6bcd747f1e42\",\n  \"pool\": \"a92a0a25-b886-4b43-931f-4add2840258a\",\n  \"tokenIndex\": \"1\",\n  \"connector\": \"erc20_erc721\",\n  \"key\": \"0x14ddd36a0c2f747130915bf5214061b1e4bec74c\",\n  \"from\": \"0x14ddd36a0c2f747130915bf5214061b1e4bec74c\",\n  \"to\": \"0xa4222a4ae19448d43a338e6586edd5fb2ac398e1\",\n  \"amount\": \"1\",\n  \"tx\": {\n    \"type\": \"token_transfer\",\n    \"id\": \"63c1a89b-240c-41eb-84bb-323d56f4ba5a\"\n  }\n}\n</code></pre> <p>Other parameters:</p> <ul> <li>You must specify a <code>pool</code> name if you've created more than one pool</li> <li>You may specify a <code>key</code> understood by the connector (i.e. an Ethereum address) if you'd like to use a non-default signing identity</li> <li>You may specify <code>from</code> if you'd like to send tokens from a specific identity (default is the same as <code>key</code>)</li> </ul>"},{"location":"tutorials/tokens/erc721/#sending-data-with-a-transfer","title":"Sending data with a transfer","text":"<p>All transfers (as well as mint/burn operations) support an optional <code>message</code> parameter that contains a broadcast or private message to be sent along with the transfer. This message follows the same convention as other FireFly messages, and may be comprised of text or blob data, and can provide context, metadata, or other supporting information about the transfer. The message will be batched, hashed, and pinned to the primary blockchain.</p> <p>The message ID and hash will also be sent to the token connector as part of the transfer operation, to be written to the token blockchain when the transaction is submitted. All recipients of the message will then be able to correlate the message with the token transfer.</p> <p><code>POST</code> <code>http://127.0.0.1:5000/api/v1/namespaces/default/tokens/transfers</code></p>"},{"location":"tutorials/tokens/erc721/#broadcast-message","title":"Broadcast message","text":"<pre><code>{\n  \"amount\": 1,\n  \"tokenIndex\": \"1\",\n  \"to\": \"0x07eab7731db665caf02bc92c286f51dea81f923f\",\n  \"message\": {\n    \"data\": [\n      {\n        \"value\": \"payment for goods\"\n      }\n    ]\n  }\n}\n</code></pre>"},{"location":"tutorials/tokens/erc721/#private-message","title":"Private message","text":"<pre><code>{\n  \"amount\": 1,\n  \"tokenIndex\": \"1\",\n  \"to\": \"0x07eab7731db665caf02bc92c286f51dea81f923f\",\n  \"message\": {\n    \"header\": {\n      \"type\": \"transfer_private\"\n    },\n    \"group\": {\n      \"members\": [\n        {\n          \"identity\": \"org_1\"\n        }\n      ]\n    },\n    \"data\": [\n      {\n        \"value\": \"payment for goods\"\n      }\n    ]\n  }\n}\n</code></pre> <p>Note that all parties in the network will be able to see the transfer (including the message ID and hash), but only the recipients of the message will be able to view the actual message data.</p>"},{"location":"tutorials/tokens/erc721/#burn-tokens","title":"Burn tokens","text":"<p>You may burn a token by specifying the token's <code>tokenIndex</code>. With the default sample contract, only the owner of a token or another approved account may burn it, but a different contract may define its own permission model.</p> <p><code>POST</code> <code>http://127.0.0.1:5000/api/v1/namespaces/default/tokens/burn</code></p> <pre><code>{\n  \"amount\": 1,\n  \"tokenIndex\": \"1\"\n}\n</code></pre> <p>Other parameters:</p> <ul> <li>You must specify a <code>pool</code> name if you've created more than one pool</li> <li>You may specify a <code>key</code> understood by the connector (i.e. an Ethereum address) if you'd like to use a non-default signing identity</li> <li>You may specify <code>from</code> if you'd like to burn tokens from a specific identity (default is the same as <code>key</code>)</li> </ul>"},{"location":"tutorials/tokens/erc721/#token-approvals","title":"Token approvals","text":"<p>You can also approve other wallets to transfer tokens on your behalf with the <code>/approvals</code> API. The important fields in a token approval API request are as follows:</p> <ul> <li><code>approved</code>: Sets whether another account is allowed to transfer tokens out of this wallet or not. If not specified, will default to <code>true</code>. Setting to <code>false</code> can revoke an existing approval.</li> <li><code>operator</code>: The other account that is allowed to transfer tokens out of the wallet specified in the <code>key</code> field</li> <li><code>config.tokenIndex</code>: The specific token index within the pool that the operator is allowed to transfer. If <code>0</code> or not set, the approval is valid for all tokens.</li> <li><code>key</code>: The wallet address for the approval. If not set, it defaults to the address of the FireFly node submitting the transaction</li> </ul> <p>Here is an example request that would let the signing account <code>0x634ee8c7d0894d086c7af1fc8514736aed251528</code> transfer <code>tokenIndex</code> <code>2</code> from my wallet.</p>"},{"location":"tutorials/tokens/erc721/#request_5","title":"Request","text":"<p><code>POST</code> <code>http://127.0.0.1:5000/api/v1/namespaces/default/tokens/approvals</code></p> <pre><code>{\n  \"operator\": \"0x634ee8c7d0894d086c7af1fc8514736aed251528\",\n  \"config\": {\n    \"tokenIndex\": \"2\"\n  }\n}\n</code></pre>"},{"location":"tutorials/tokens/erc721/#response_4","title":"Response","text":"<pre><code>{\n  \"localId\": \"46fef50a-cf93-4f92-acf8-fae161b37362\",\n  \"pool\": \"e1477ed5-7282-48e5-ad9d-1612296bb29d\",\n  \"connector\": \"erc20_erc721\",\n  \"key\": \"0x14ddd36a0c2f747130915bf5214061b1e4bec74c\",\n  \"operator\": \"0x634ee8c7d0894d086c7af1fc8514736aed251528\",\n  \"approved\": true,\n  \"tx\": {\n    \"type\": \"token_approval\",\n    \"id\": \"00faa011-f42c-403d-a047-2df7318967cd\"\n  },\n  \"config\": {\n    \"tokenIndex\": \"2\"\n  }\n}\n</code></pre>"},{"location":"tutorials/tokens/erc721/#use-metamask","title":"Use Metamask","text":"<p>Now that you have an ERC-721 contract up and running, you may be wondering how to use Metamask (or some other wallet) with this contract. This section will walk you through how to connect Metamask to the blockchain and token contract that FireFly is using.</p>"},{"location":"tutorials/tokens/erc721/#configure-a-new-network","title":"Configure a new network","text":"<p>The first thing we need to do is tell Metamask how to connect to our local blockchain node. To do that:</p> <ul> <li>Click your account icon</li> <li> <p>In the drop down menu, click Settings </p> </li> <li> <p>On the left hand side of the page, click Networks</p> </li> <li> <p>Click the Add a network button   </p> </li> <li> <p>Fill in the network details:</p> </li> <li>Network Name: <code>FireFly</code> (could be any name)</li> <li>New RPC URL: <code>http://127.0.0.1:5100</code></li> <li>Chain ID: <code>2021</code></li> <li>Currency Symbol: ETH</li> <li>Click Save </li> </ul>"},{"location":"tutorials/tokens/erc721/#import-tokens","title":"Import tokens","text":"<p>Metamask won't know about our custom ERC-721 contract until we give it the Ethereum address for the contract, so that's what we'll do next.</p> <ul> <li> <p>Click on Import tokens </p> </li> <li> <p>Enter the Ethereum address of the contract</p> </li> <li>Enter a Token Symbol (can be anything you want)</li> <li>Click Add Custom Token</li> </ul> <p>NOTE: You can find the address of your contract from the response to the request to create the token pool above. You can also do a <code>GET</code> to <code>http://127.0.0.1:5000/api/v1/namespaces/default/tokens/pools</code> to lookup your configured token pools.</p> <p></p>"},{"location":"tutorials/tokens/erc721/#transfer-tokens","title":"Transfer tokens","text":"<p>Now you can copy your account address from your Metamask wallet, and perform a transfer from FireFly's API (as described above) to your Metamask address.</p> <p></p> <p>After a couple seconds, you should see your token show up in your Metamask wallet.</p> <p></p> <p>NOTE: While the NFT token balance can be viewed in Metamask, it does not appear that Metamask supports sending these tokens to another address at this time.</p>"}]}
\ No newline at end of file